The action-reference footer writes the catalogue total as total + 1, and nothing checks it against KNOWN_ACTION_NAMES

[vladimirrott]

crates/sysknife-daemon/tests/action_reference_doc.rs:139-144 writes the footer of docs/action-reference.md by adding one to the tabled count and naming ListJobHistory as a literal:

    out.push_str(&format!(
        "---\n\n_{total} actions have an `ActionSpec` and are tabled above. The \
         full catalogue (`KNOWN_ACTION_NAMES`) also includes `ListJobHistory`, \
         which the dispatcher handles before the executor, for **{}** total._\n",
        total + 1
    ));

The list that decides which actions bypass the executor is DISPATCHER_INTERNAL_ACTIONS, and the generator never reads it. At 736f9451:

$ grep -rn "DISPATCHER_INTERNAL_ACTIONS" crates/ --include=*.rs
crates/sysknife-daemon/tests/action_consistency.rs:27:const DISPATCHER_INTERNAL_ACTIONS: &[&str] = &["ListJobHistory"];
crates/sysknife-daemon/tests/action_consistency.rs:33:    for &name in DISPATCHER_INTERNAL_ACTIONS {
crates/sysknife-daemon/tests/action_consistency.rs:67:    let dispatcher_internal: BTreeSet<&str> = DISPATCHER_INTERNAL_ACTIONS.iter().copied().collect();

Add a second dispatcher-internal action and action_consistency.rs forces you to extend its list, while the generated document keeps counting one.

Why it matters

action_reference_doc_is_current compares the committed file against the generator, so both sides carry the same arithmetic and a wrong footer agrees with itself. Nothing compares that total against sysknife_types::KNOWN_ACTION_NAMES, which is the list the sentence names.

I put the arithmetic off by one at 736f9451 and regenerated:

python3 - <<'PY'
import pathlib
p=pathlib.Path('crates/sysknife-daemon/tests/action_reference_doc.rs')
s=p.read_text()
assert "        total + 1\n" in s, "anchor missing"
s2=s.replace("        total + 1\n","        total + 2\n",1)
assert s2!=s
p.write_text(s2)
print("mutation applied")
PY

$ UPDATE_ACTION_REFERENCE=1 cargo nextest run -p sysknife-daemon --test action_reference_doc --locked -E 'test(action_reference_doc_is_current)'
        PASS [   0.012s] (1/1) sysknife-daemon::action_reference_doc action_reference_doc_is_current
     Summary [   0.013s] 1 test run: 1 passed, 6 skipped
$ tail -2 docs/action-reference.md

_191 actions have an `ActionSpec` and are tabled above. The full catalogue (`KNOWN_ACTION_NAMES`) also includes `ListJobHistory`, which the dispatcher handles before the executor, for **193** total._

KNOWN_ACTION_NAMES holds 192 names. With the document claiming 193, the Rust suite and the public-claims gate both stay green:

$ out="$(cargo nextest run -p sysknife-daemon -p sysknife-types -p sysknife-brain --locked 2>&1)"; rc=$?; echo "rc=$rc"; printf '%s\n' "$out" | tail -4
rc=0
     Summary [   8.638s] 1451 tests run: 1451 passed, 5 skipped
$ out="$(bash tests/release/public-claims.test.sh 2>&1)"; rc=$?; echo "rc=$rc"; printf '%s\n' "$out" | tail -8
rc=0
Published figures match the evidence artifacts.
Public claims are internally consistent.
Public claims contract passed.

I reverted the mutation and regenerated; git diff --stat is empty at 736f9451.

#452 made scripts/check_evidence_claims.py derive the developer guide's ActionSpec figure from this table, which was the right move. It also means a published claim now rests on a document whose own total nothing checks.

Scope

• Move DISPATCHER_INTERNAL_ACTIONS somewhere both test binaries can read. Each file under crates/sysknife-daemon/tests/ compiles to its own binary, so a const in action_consistency.rs is invisible to action_reference_doc.rs. Putting it in sysknife-daemon's src/ next to the dispatcher that owns the behaviour is the option I would take; a #[path] include of a shared test module also works and keeps it out of the shipped crate. Either is fine, and the trap is assuming use across test binaries compiles.
• Derive both figures in the footer from that list: the tabled count, and the total. Name the bypassing actions from the list rather than spelling ListJobHistory into the format string, so a second entry appears in the sentence without anyone remembering to add it.
• Leave docs/action-reference.md byte-identical. The footer reads the same today; only its derivation changes.

Tests first

The assertion that is missing, in action_reference_doc.rs: the total in the generated footer equals sysknife_types::KNOWN_ACTION_NAMES.len(), and the tabled count equals that minus the number of dispatcher-internal actions. Write it and watch it fail before you touch the generator.

Prove it bites with the mutation above: change total + 1 to total + 2, run with UPDATE_ACTION_REFERENCE=1 so the committed file is regenerated to match, then run the test binary normally. Today that sequence passes. Your assertion has to fail on it, because that is the exact shape of the bug: the generator and the document agreeing with each other while both disagree with the catalogue.

A second worth having, cheaper to write: with DISPATCHER_INTERNAL_ACTIONS extended by one name, the footer sentence names both.

Difficulty

easy. The change is a constant moving and two numbers becoming derived. The one thing that will cost you an hour if nobody says it is the test-binary boundary in the first Scope bullet.

Getting started

CONTRIBUTING.md
has the build and test commands. No CLA and no copyright waiver. The project is MIT.

[vladimirrott]

@tayfuryldz this is the follow-up I promised in the #452 review, and it is yours on no deadline.

You made the developer guide's ActionSpec figure derive from docs/action-reference.md instead of a number somebody typed. One layer down, that document's own total is a number somebody typed: the generator writes total + 1 and spells ListJobHistory into the sentence, while the list of actions that bypass the executor lives in a different test file the generator never opens.

The body carries the reproduction, including the mutation I ran at 736f9451. I made the arithmetic off by one, regenerated, and 1451 Rust tests plus tests/release/public-claims.test.sh all stayed green over a document claiming 193 actions out of a catalogue of 192. That total is the figure your checker now reads as evidence.

One thing worth knowing before you start, because it costs an hour to discover: every file under crates/sysknife-daemon/tests/ compiles to its own binary, so the constant in action_consistency.rs cannot be reached with a use from action_reference_doc.rs. It has to move.

Reply here and I will mark it claimed and assign you. If you would rather take something else, say so and I will find it.

[vladimirrott]

Rechecked at ba1a7b8f. Nothing has touched action_reference_doc.rs since I filed this, and both figures are still correct today, which is the point: the document agrees with the catalogue by arithmetic rather than by derivation.

$ python3 -c "
import re
s=open('crates/sysknife-types/src/lib.rs').read()
m=re.search(r'pub const KNOWN_ACTION_NAMES: &\[&str\] = &\[(.*?)\n\];', s, re.S)
names=re.findall(r'\"([A-Za-z0-9_]+)\"', m.group(1))
print('KNOWN_ACTION_NAMES len =', len(names))
"
KNOWN_ACTION_NAMES len = 192
$ tail -2 docs/action-reference.md

_191 actions have an `ActionSpec` and are tabled above. The full catalogue (`KNOWN_ACTION_NAMES`) also includes `ListJobHistory`, which the dispatcher handles before the executor, for **192** total._

191 tabled, 192 total, 192 names. Correct, and nothing compares the three.

One anchor correction: the generator block is :139-144, not :138-143. I was off by one when I filed it, not since:

$ grep -n 'out.push_str(&format!(\|total + 1' crates/sysknife-daemon/tests/action_reference_doc.rs
115:        out.push_str(&format!("## {title}\n\n"));
121:            out.push_str(&format!(
139:    out.push_str(&format!(
143:        total + 1

DISPATCHER_INTERNAL_ACTIONS is still the one-element list in the other test binary:

$ grep -rn "DISPATCHER_INTERNAL_ACTIONS" crates/ --include=*.rs
crates/sysknife-daemon/tests/action_consistency.rs:27:const DISPATCHER_INTERNAL_ACTIONS: &[&str] = &["ListJobHistory"];
crates/sysknife-daemon/tests/action_consistency.rs:33:    for &name in DISPATCHER_INTERNAL_ACTIONS {
crates/sysknife-daemon/tests/action_consistency.rs:67:    let dispatcher_internal: BTreeSet<&str> = DISPATCHER_INTERNAL_ACTIONS.iter().copied().collect();

@tayfuryldz #456 is open against this, so you are already on it. The test-binary boundary I warned about is still the thing that costs an hour.

[vladimirrott]

@tayfuryldz, I offered you this on 19 September as the follow-up to #452 and haven't heard back, so it's back in the pool. Nothing is owed. It stays a good fit for you, and if you want it later, say so here and it's yours.

[tayfuryldz]

Sorry for leaving this hanging. I am taking the follow-up back now and will implement the derivation described here rather than the old total + 1 patch.