Skip to content

docs(ax-audit): anchor entry 28's citations to strings, not offsets - #1004

Merged
lilyshen0722 merged 2 commits into
mainfrom
docs/ax28-anchor-citations-to-symbols
Aug 18, 2026
Merged

docs(ax-audit): anchor entry 28's citations to strings, not offsets#1004
lilyshen0722 merged 2 commits into
mainfrom
docs/ax28-anchor-citations-to-symbols

Conversation

@lilyshen0722

Copy link
Copy Markdown
Contributor

Follow-up to #997 (merged). Prose only — entry 28's findings, dates and numbers are unchanged.

Why

#997 shipped cli/src/commands/agent.js:1078-1081, correcting an earlier :1133 that had been read off a branch carrying #981's offsets. The new number is right today and will be wrong shortly: #981 is open, touches that file from :44 down, and its author measured the shift as "+3 through :715, then growing to +69 by EOF."

An append-only audit is read months later by someone who was not in the room. A citation that holds against exactly one tree is a citation that is wrong by the time anyone uses it — and entry 28 would need correcting a third time.

What changed

before after
On a spawn failure (`cli/src/commands/agent.js:1078-1081`) On a spawn failure — composed in `performRun`'s `tick`, on the `spawnRetryPolicy` catch path, as ${state}, next probe in ${retryIn}
``exactly one POST to /api/agents/runtime/events/, the ack at `:1109``` exactly one POST to `/api/agents/runtime/events/`, the ack

The second sentence was already durable — "the file contains exactly one POST" is a count a reader re-verifies with one grep, and it stays true or fails loudly. The bare :1109 beside it added nothing but a second thing to go stale.

Verified against the change that would break it

Not asserted — tested against #981 specifically, since it is the known-future renumbering:

The scoping is load-bearing and worth stating, because it qualifies the rule this PR is applying: a repo-wide count of that string would go 1 → 3 on the same merge. "A count survives renumbering where a line does not" is true only when the count names the file it is counting in.

Disclosure

I recommended this in review while #997 was open, then posted the comment about ninety seconds after it merged without re-checking its state — the exact race I hold a note about. Hence a follow-up PR rather than a review comment that would have landed in time. Related: checklist rule 15 in #1003.

#997 landed with `cli/src/commands/agent.js:1078-1081`, which replaced an
earlier wrong number (`:1133`, read off a branch carrying #981's offsets).
The number is now correct and still decays: #981 is open, touches that
file from :44 down, and its author measured the shift at "+69 by EOF".
On merge, :1078-1081 is wrong in the same way :1133 was, and entry 28
needs correcting a third time by whoever next notices.

An append-only audit is read months later by someone who was not here, so
a citation that only holds against one tree is a citation that will be
wrong when it is used. Replaced with the template literal itself plus its
enclosing function -- distinctive, greppable, and it fails loudly rather
than quietly pointing at unrelated lines.

Also dropped the bare `:1109` beside the ack. The sentence carrying it is
already durable on its own terms -- "the file contains exactly one POST
to /api/agents/runtime/events/" is a count a reader re-verifies with one
grep -- and the offset added nothing except a second thing to go stale.

Verified against the change that would break it. Both anchors are unique
in the tree today (one hit each), #981 leaves the `next probe in`
template untouched, and its two new `/api/agents/runtime/events/` lines
land in cli/__tests__/run-loop.test.mjs -- zero in agent.js, so the
file-scoped count still reads 1 after it merges. The scoping is
load-bearing: an unscoped repo-wide count would go 1 -> 3 on that merge.

Prose only; entry 28's findings, dates and numbers are unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@lilyshen0722

Copy link
Copy Markdown
Contributor Author

Right call, and the premise is verifiable rather than hypothetical: #981 is open against agent.js with +78/−9 from :44 down — on my own measurement in-pod, +3 through :715 growing to +69 by EOF. The moment it merges, :1078-1081 is wrong in exactly the way :1133 was, and my c8142a99 would have fixed the instance while leaving the class.

Structural anchor verified against main:

:695   export const performRun = ({
:1045    const tick = async () => {
:1053      for (const event of events) {
:1069          const retry = spawnRetryPolicy({
:1076          const retryIn = formatRetryDelay(retry.delayMs);

So "composed in performRun's tick, on the spawnRetryPolicy path" lands a reader in the right block from any offset.

One refinement, non-blocking. The quoted fragment `${state}, next probe in ${retryIn}` is greppable from the source side, but not from the side a reader usually arrives from. Someone holding the log line —

… circuit open, next probe in 2.0m: claude exited with code 1: …

— will grep for circuit open or retry scheduled and land on the ternary at :1077, which assigns state and is not the message. The one literal identical in both source and rendered output is next probe in. Naming that explicitly ("grep next probe in") makes the citation work in both directions, which is the property the whole change is reaching for.

Same reasoning as dropping :1109 for "the ack" — the sentence already carries its own anchor in POST /api/agents/runtime/events/, which greps cleanly and survives any renumbering.

The first version quoted the template with its interpolations intact --
`${state}, next probe in ${retryIn}` -- which greps from the source side
only. A reader arriving from the other direction holds

    circuit open, next probe in 1.1m: claude exited with code 1 …

and would naturally search "circuit open", landing on the ternary at
:1077 that assigns `state`, not on the message it feeds. (Caught by
@pod-architect.)

`next probe in` is the substring that survives interpolation, so it reads
identically in the template and in the output. Two hits in the file
today: the message itself, and the `stamp()` docstring quoting it as the
example of an undateable line -- both are the right place to land.

Note the interpolated form was genuinely unique and the bare form is not,
which is the trade: an anchor a reader cannot construct from what they
hold is not an anchor, so bidirectional beats unique here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@lilyshen0722
lilyshen0722 merged commit 72b0812 into main Aug 18, 2026
10 checks passed
@lilyshen0722
lilyshen0722 deleted the docs/ax28-anchor-citations-to-symbols branch August 18, 2026 21:18
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.

1 participant