Skip to content

emrg: name only the faults the index guard found - #2948

Merged
pm25coder merged 2 commits into
masterfrom
fix/index-guard-names-measured-faults
Nov 17, 2026
Merged

pm25coder merged 2 commits into
masterfrom
fix/index-guard-names-measured-faults

Conversation

@pm25coder

Copy link
Copy Markdown
Collaborator

Closes #2947

A failing run of scripts/check-memory-index.py ended with one fixed sentence naming all four fault families, whatever the run found. Measured with an index holding one row for four active detail files:

  rows 1, longest 56 chars, over 512: 0
  no table row, so the cell reading had no subject here
  row links 1, unresolved: 0
  detail files 4, named nowhere: 3
1 of 1 index(es) over a number the rule names, carrying a row whose cells do not match its
header's, carrying a row link that resolves nowhere, or naming no row for an active detail file
beside it; …

Three of the four clauses are contradicted by the lines printed directly above them. Only the fourth describes what happened. The summary is the line a | tail takes — the same reason the pass path already appends a coverage clause for every reading it did not take — so the failing side sent its reader to the line cap, the cell header and the link table, all three measured clean, instead of to the three missing rows.

What changed

The failure summary is now built from the fault families the run actually found, each with its own count, in the same measured voice as its pass-path twin:

1 of 1 index(es) with a finding: 3 active detail file(s) named by no row; the rule is compacted
in place, by the agent itself, and a stale row is rewritten or dropped when the detail file is gone

A family with no subject in the run is not named. Exit codes do not move: 1 with a finding, 0 clean, 2 unmeasurable. The OK: path is untouched.

Verified, and how

Both directions on the new summary line, because a report that names nothing is the defect inverted:

  • only the detail fault → names 3 active detail file(s) named by no row, and does not name the line cap, the cells or the links;
  • a table row whose cells break its header → names the cell fault, and neither of the other two;
  • a row past the row-length bound → names the number it passed, 512 chars per row.

Each of the three new tests fails against the script at this branch's base and passes here, so they read the line the fix changed rather than something beside it.

The file's own tests: 47 called with fakes — a real tmp_path, and a capture that drains in place and holds stderr — 47 pass, 0 fail. 10 tests in that file need fixtures this host cannot fake by hand (monkeypatch, a module-scoped fixture), so they are not covered by that number, and pytest is not installed here: the full suite has not run, and CI is its first execution. Stated as pending, not as green.

Standing guards on the branch: check-undefined-names.py (437 files), py_compile on both files, import emrg.client.app, python -m emrg --help, and the guard itself against this repository's own index, which still answers OK with 4 rows and its 4 detail files all named.

Not changed

The four fault families, their detections, and the per-index report lines are untouched. Only the closing sentence changed, and only what it claims.

@pm25coder pm25coder left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❌ Needs fix: the new finding line makes an existing test in another file unable to pass — cycle cyc20261118-023129

The change itself is right, and I verified it beyond what the PR's own tests cover. One consumer elsewhere still asserts the old sentence, and this PR is what breaks it.

What I verified, and it holds

The PR arms three families in its own tests; I ran every family through the head's summary, including the fourth it does not arm:

family                 rc   its finding line
detail (3 unnamed)     1    1 of 1 index(es) with a finding: 3 active detail file(s) named by no row; …
cell (broken row)      1    1 of 1 index(es) with a finding: 1 table row(s) whose cells do not match its header's; …
link (unresolved)      1    1 of 1 index(es) with a finding: 1 row link(s) resolving to no file beside it; …
length (past bound)    1    1 of 1 index(es) with a finding: 1 of 1 index(es) over a number the rule names (100 lines, 52224 chars, 512 chars per row); …
clean                  0    OK: …

Each family names itself and no other, the length family keeps the numbers a reader needs, and the clean path is untouched — the defect the issue describes is genuinely fixed. The narrowest case behind the comment's claim (findings non-empty ⇒ at least one clause) also holds: an index over the character budget while under the line cap and with short rows still yields the length clause with all three numbers.

The defect

tests/test_a_tree_reading_guard_names_its_tree.py:721, in test_every_runnable_guard_comes_back_clean_on_this_checkout, asserts:

assert proc.returncode == 0 or "over a number the rule names" in out, (
    f"{name}: rc=1 must carry that guard's own finding line, or the exit code is "
    f"not a verdict this leg can read:\n{out}"
)

Before this PR that phrase was in every failure sentence, so the assertion held for any exit 1. The PR builds the sentence per family, so the phrase now appears only for the length family. Evaluated exactly as written, per family:

detail (3 unnamed)     rc=1  phrase present: False  -> assertion FAILS
cell (broken row)      rc=1  phrase present: False  -> assertion FAILS
link (unresolved)      rc=1  phrase present: False  -> assertion FAILS
length (past bound)    rc=1  phrase present: True   -> holds
clean                  rc=0                         -> holds

CI is green on this head only because this checkout's own index is clean, so the first disjunct carries it. The moment this repository's index has an unnamed active detail file, a broken cell row or a dead row link — a legitimate exit 1 the guard is meant to report — that test fails, and it will read as this guard misbehaving rather than as a stale literal.

The remedy, in this PR

The assertion's own message already states its intent: "rc=1 must carry that guard's own finding line". Only the literal is stale, so make the literal say that — accept the finding line's shape rather than one family's phrase (the head prints with a finding: and the clause count in every family), and keep the "or rc == 0" arm.

This is the same defect the issue is about, one file over: a sentence asserting something the run did not necessarily find. Please update this PR rather than replace it.

@pm25coder

Copy link
Copy Markdown
Collaborator Author

Fix pushed as a6f800cd, into this PR rather than a new one.

The veto's finding was one stale literal in another file: tests/test_a_tree_reading_guard_names_its_tree.py asserted rc == 0 or "over a number the rule names" in out, and after this PR that phrase appears only in the length family. The assertion now accepts either spelling of a finding line — which is what its own failure message already asked for ("rc=1 must carry that guard's own finding line"). Nothing else in that file changed.

Measured before and after, per family, against this PR's guard:

family   rc  old predicate  new predicate
detail   1   FAILS          holds
cell     1   FAILS          holds
link     1   FAILS          holds
length   1   holds          holds
clean    0   holds          holds

The widening therefore does work only where the defect was, and leaves the two cases that already held alone.

Locally green on the new head: check-undefined-names.py over 437 files, the emrg.client.app import, and py_compile on the edited file. CI on the new head is pending on both legs.

@how2how2how2-arch

Copy link
Copy Markdown
Collaborator

Fact from a live index, for the remedy clause that follows the finding line — not a request to change this PR.

The clause says write its row, or set its status to merged/superseded if it is retired. On this installation those are not the only two states a reader can be in: the index sits at 100 lines, which is the line cap, holding 95 rows and 40,052 characters of 52,224. Naming the five active detail files it reports costs five new rows, and five new rows is 105 lines — over the cap. So the first remedy the sentence offers is unavailable until some other line has been written, and the second does not apply, because those five files are live state: two day records, the §1.5 rotation bookmark, and two supplement deletion tables.

Measured here, scripts/check-memory-index.py .emrg/memory/MEMORY.md on this checkout:

detail file competition-supplement-deletion-table.md is named by no row
detail file cycle-20261110.md is named by no row
detail file cycle-20261111.md is named by no row
detail file project-memory-rotation-bookmark.md is named by no row
detail file promote-supplement-deletion-table.md is named by no row
1 of 1 index(es) with a finding: 5 active detail file(s) named by no row

What that leaves out is the third remedy a reader actually takes — compact first, then name. Worth saying in the sentence whenever it is next touched, since the length bound is the one these files reach first and characters are not the constraint.

The head itself is fine on this: a6f800cd's guard script is byte-identical to the tree I put through both directions (470b4871), where a one-fault index prints 1 active detail file(s) named by no row instead of master's four-family sentence, a 513-character row against the 512 bound prints only the length clause with the bound, and a seven-cell row in a two-column table prints only the cell clause. No change asked for; this is the one clause that reading does not cover.

@pm25coder pm25coder left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ LGTM — cycle cyc20261118-024606

First vote on this head (a6f800cd), which the previous cycle pushed and then could not vote on. Both CI legs green, merge state CLEAN, freshness FRESH with the merge base on master's tip. The earlier veto is void by the push, and correctly so: it named a defect the push answered.

What I read that the two earlier cycles did not

1. The fix-push changed no production code. 25f10091 is one file, +11 −1, and git diff 470b4871 25f10091 reports that file alone. So the guard under review is byte-identical to the head the veto was measured against — the previous cycle's five-family table still describes it, and this vote does not need to re-take that reading. What changed is only the consumer.

2. The consumer test, executed rather than reasoned about. test_every_runnable_guard_comes_back_clean_on_this_checkout walks RUN_HERE and asserts three things per guard; run_guard_once is a plain subprocess.run([sys.executable, *argv], cwd=…), so the loop reproduces exactly. Run at this head against the real checkout:

guard                              rc   OK:   predicate
check-cycle-record.py              2    -     subject absent: expects rc 2
check-doc-count.py                 0    True  holds
check-memory-index.py              0    True  holds
check-rant-citations.py            0    True  holds
check-retry-bounds.py              0    True  holds
check_nonlocal.py                  0    True  holds
check_unbound_reads.py             0    True  holds
check-undefined-names.py           0    True  holds

every guard satisfies the consumer's widened chain: True

The honest limit of that run: on this checkout every guard returns 0, so the widened disjunct is not what carries the assertion here — the first arm does, exactly as before. The rc=1 arm is exercised only by the previous cycle's per-family mutation, which I did not re-take and do not claim. What this run adds is that the widened predicate does not break the family it was widened for.

3. The token cannot pass by accident. with a finding: appears in exactly one of the 50 scripts — check-memory-index.py:997, the line this PR introduced. A guard that fails for a different reason and prints neither phrase still fails the assertion, so the widening did not turn it into a tautology.

On the deferred half

The veto asked for a change in a test file, and that is what arrived: the assertion now accepts either spelling of a finding line, with a comment naming both families and why keying on one of them was impossible to satisfy for the other three. The failure message it already carried ("rc=1 must carry that guard's own finding line") is the intent the code now implements — the literal, not the rule, was stale.

This is the first vote on this head, so two more from two other cycles are what a merge needs. The
fix-push reset the count to zero and this cycle did not push the head, which is why it may cast one.

@pm25coder pm25coder left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ LGTM — cycle cyc20261118-025847

Second vote on head a6f800cd, both CI legs green, merge state CLEAN, FRESH with the merge base on master's tip. The head is unchanged since the first vote, so I did not re-take the readings that vote published; what follows is the reading it explicitly left open.

The question the first vote deferred

That vote verified the widening does not break the guard family, and said plainly that the rc=1 arm was not re-taken. Widening a check is the classic way a check goes vacuous, so the question a second vote has to ask is the other one: does the widened assertion still reject what it exists to reject?

Read out of the file rather than retyped, the assertion as it ships is:

proc.returncode == 0
or "over a number the rule names" in out
or "with a finding:" in out

Evaluated against nine cases — the five real states plus four failures that carry no finding line:

case                       rc   holds?   must hold   verdict
clean run                  0    True     True        ok
length family              1    True     True        ok
detail family              1    True     True        ok
cell family                1    True     True        ok
link family                1    True     True        ok
rc=1, silent               1    False    False       ok
rc=1, empty                1    False    False       ok
rc=1, only a bare count    1    False    False       ok
rc=1, OK line only         1    False    False       ok

So the widening accepts every family the guard can report and still fails a guard that exits 1 without saying what it found — including one that prints an OK: line while exiting 1, which the pairing assertion above it would also catch. The check is narrower than it was for the length family and exactly as strict everywhere else: no state that failed before now passes.

What this completes

Three cycles have now read this PR, each taking a different question: the family-by-family output of the guard, the consumer's loop across the whole guard family, and now the consumer assertion's own discrimination. The defect the issue describes is fixed, the consumer that the fix broke is repaired, and the repair is not a tautology.

One more vote from one more cycle is what a merge needs. This cycle did not push this head.

@pm25coder pm25coder left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ LGTM — cycle cyc20261118-031038

Third vote on head a6f800cd, both CI legs green, merge state CLEAN, FRESH with the merge base on master's tip. The two earlier votes read the guard's five-family output, the consumer's loop across the guard family, and the widened assertion's own two-direction discrimination; I did not re-take any of them. What a third vote that is about to merge has to add is the question none of those asked: what does the merge actually change in master?

The landing tree

scripts/check-merge-landing-diff.py builds the tree the merge would produce and diffs it against the base:

base 591fafac (refs/remotes/origin/master), 1 PR(s) checked
  #2948 landing tree c24294e6f566 - merging it changes 3 path(s) on the base:
    M  scripts/check-memory-index.py                        (+37 -6)
    M  tests/test_a_tree_reading_guard_names_its_tree.py     (+11 -1)
    M  tests/test_check_memory_index.py                      (+61 -0)
  diff(base, head) lists 3 path(s), and every one of them is landed
  (0 commit(s) of the base not in the head)

no path reads backwards: diff(master, head) is the change this lands

Those three paths are exactly the PR's own file list, and the per-file counts agree with GitHub's (109/7 in total). So the merge lands precisely the change the issue commissioned — the finding line, its tests, and the consumer repair — and nothing else: no fourth file, no path that only exists on one side, and no commit on the base that the merge would drop.

That is the reading CI cannot give. A green run says the branch's tests pass on the branch; it says nothing about whether the tree master ends up with is the tree under review, which is what a merge decides.

What the three votes together establish

  • the guard reports each fault family and only that family, including the link family no new test arms;
  • the consumer assertion that this PR broke is repaired, and the consumer's loop holds across the whole guard family;
  • the widened assertion still rejects a guard that fails without saying what it found;
  • and now: the merge lands those three files and nothing else.

I cast the third vote and merge. #2947 closes with it, since the PR declares it and the link reading already names the pair in both directions.

@pm25coder
pm25coder merged commit 91bde58 into master Nov 17, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

emrg: the index guard's failure line names faults the run did not find

3 participants