Vault Chunk Quality Gates
Scripts for maintaining correctness of the vault-index/semantic/ chunk corpus produced by the vault-indexing subagent pipeline.
Anchor Audit (scripts/check-anchors.mjs)
Verifies that every [path:LN] anchor in a semantic chunk points to a real line containing the quoted words verbatim. Four silent failure modes it prevents: vacuous zero-count (bracket imbalance swallows pattern), fabricated quotes (keyword overlap ≠ verbatim), synthetic harness padding (quotes sourced from session-event: synthetic blocks), and wrong anchor side (commentary before [path:LN] instead of after).
bun scripts/check-anchors.mjs rem-154 # one chunk, exit 1 on any failure
bun scripts/check-anchors.mjs --all # full corpus, report only
bun scripts/check-anchors.mjs --all --quiet # only chunks with failures
The anchor scan tracks [ ] depth, because a path's own trailing [ses_…]
group has to close before the anchor does. That tracking used to walk forward from
every [ to find its closer, which is correct and quadratic: an unbalanced
[ sends the walk to the end of the string and the next [ repeats the trip.
Measured on text [more words here and there\n repeated (ordinary prose with a
bracket and no closer, which is what a session note full of markdown links looks
like when the closing bracket is outside the quoted span):
| Input | Old | New |
|---|---|---|
| 63 KB | 123 ms | 2.3 ms |
| 125 KB | 759 ms | 8.1 ms |
| 250 KB | 3032 ms | 1.4 ms |
| 200 KB, fully unbalanced | 96 s | not recorded |
A bracket stack answers the same question in one pass, and is equivalent by
construction: the ] that brings depth to 0 from position i is exactly the
bracket matching i under standard matching. scripts/check-anchors-perf.test.mjs
asserts the equivalence over a 22-case corpus and re-measures the quadratic
control, so the claim stays falsifiable instead of becoming a comment.
Anchor Repair (scripts/repair-anchors.mjs)
Automatically repairs pre-§4a anchors that fail the verbatim test using a tiered strategy:
| Tier | Strategy |
|---|---|
| T1 | Quote IS verbatim somewhere in the file: rewrite anchor to the correct line number. |
| T2 | Quote wraps two consecutive lines: split into two anchors per §4a. |
| T3 | Quote absent, but source_location names a supporting line: replace with a verbatim slice. |
| T4 | Nothing verifiable: left alone and reported, never guessed. |
bun scripts/repair-anchors.mjs --survey # tier counts, no writes
bun scripts/repair-anchors.mjs --tier 1 --apply # rewrite correct line numbers
bun scripts/repair-anchors.mjs --chunk 037 --apply # one chunk, any tier
Chunk Validation & Acceptance (scripts/verify-chunk.sh, scripts/accept-chunks.sh)
Parent-side gather-and-synthesize helpers:
./scripts/verify-chunk.sh rem-090 # validate one chunk with cross-chunk link resolution
./scripts/accept-chunks.sh rem-127 075 # dry run: gate + structural diff
./scripts/accept-chunks.sh --commit -m 'msg' rem-127
./scripts/accept-chunks.sh --commit # all dirty chunks
accept-chunks.sh enforces that node ids, order, and links array match HEAD unless the chunk declared a case-3 deletion, the one change allowed to alter structure.