Skip to content

docs(driver-memory): re-anchor the dead tracker citations to the commits that decided them (stage 5 of #20595) - #21375

Merged
objectstack-fleet[bot] merged 3 commits into
mainfrom
claude/issue-20595-driver-memory-citations
Oct 2, 2026
Merged

objectstack-fleet[bot] merged 3 commits into
mainfrom
claude/issue-20595-driver-memory-citations

Conversation

@objectstack-fleet

Copy link
Copy Markdown
Contributor

Part of #20595
Clause-②: no

What changed

Stage 5 of the domain:engine lane of the dead-citation sweep: packages/drivers/driver-memory/**, comment and docblock prose only, per the claim (5947712781). Stages 1 to 4 landed as a7d9768ec, d150c3039, 4bf4e7e70 and 13a24ece2; #20595 stays open for the next stage.

Every comment or docblock site in the package that cited a tracker number answering 404 is rewritten in ruling C+D's form C (record 5749154545 on #19123): the ADR when one records the decision, otherwise the commit in this repository's history that made it. That is 104 sites on 103 lines in 27 files, covering 13 numbers:

No comment-id citation in the package is dead (see Census).

Anchors: 13 numbers by commit, 0 by ADR, 0 by words alone. 11 numbers reuse the anchor another lane or stage already measured for them; 2 were measured here (#14435, #16838). 13 distinct shas. No ADR or ruling record names any of the 13 for this subject: git grep over docs/adr and scripts/adr-anchors finds only ADR-0088's correction row for #10724, which is about contributes.functions, not the contributes.drivers retirement cited here.

Only comments changed. Every file keeps its line count (103 lines out, 103 in, plus the changeset), so no line citation into any of them moves. No code token moves (the guard below). No citation number is added: on every changed line, the numbers on the new text are a subset of those on the old, and the diff-scoped gate judged the 7 citations left on changed lines: all 7 resolve.

A patch changeset: 20 of the 62 rewritten non-test lines are in the published dist (the .d.ts keeps JSDoc on exported members, and esbuild keeps some comments in the JS), and dist is not byte-identical with the base text (see Changeset).

H0: the largest remaining domain:engine package

The gate's own node scripts/check-issue-citations.mjs --census --json at base 5fd4855a9 (the before run below), allocated-but-absent per package over every domain:engine family in .claude/skills/pm-dispatch/SKILL.md's lane table:

package sites
drivers/driver-memory 59
metadata 41
core 40
platform-objects 27
metadata-core 19
drivers/driver-turso 14
drivers/driver-mongodb 9
formula 4
metadata-fs 2
drivers/driver-sqlite-wasm, plugins/plugin-pinyin-search, objectql, metadata-protocol, drivers/driver-sql 0 each

driver-memory is still the largest (lane total 215), so this stage went ahead.

Census: driver-memory, before and after

Instrument (A1). The gate's own node scripts/check-issue-citations.mjs --census --json, read-only and unchanged. The count is its allocated-but-absent findings under packages/drivers/driver-memory/.

reading tree board whole-repo allocated-but-absent sites lines files numbers
before base 5fd4855a9, run 07:54:54Z to 07:58:32Z enumerated, 192 pages, frontier #21366, 19,187 records (newest number read before and after the run: #21366) 330 59 59 5 6
after 17f667f86, run 08:13:08Z to 08:17:18Z enumerated, 192 pages, frontier #21370, 19,191 records (newest before and after: #21370) 271 0 0 0 0

The whole-repo drop is 59, and the two finding sets differ by exactly the 59 rows of this package, removed; none was added. resolves (34,880), resolves-as-pull-request (2,378) and cross-repo-unjudged (1,165) did not move. The card's 62 was taken at f11b5f20a2 with the older extractor; the base here reads 59. The head's later commits are the changeset (outside the census surface) and one merge of main that touches no file under packages/drivers/driver-memory.

Supplementary instrument, the whole package. The census reads neither test files nor strings nor files outside src. A second reading runs the gate's own exported extractCitations (whole-file and comment-prose projections) over every tracked file in the package (89: 82 .ts, package.json, tsconfig.json, tsconfig.typecheck.json, README.md, CHANGELOG.md, LICENSE, objectstack.config.ts among the .ts), and classifies each citation with the gate's classifyCitation against one board enumerated by the gate's enumerateBoard (192 pages, frontier #21369, 19,190 records, 07:59:39Z to 08:03:13Z). Every one of the 13 numbers in the population was then read on its own over the issues endpoint (08:04Z): all 13 answer 404, and the lit controls #5286 and #12624 answer 200.

reading citations dead src comment test comment other (tsconfig.typecheck.json) test string changelog
before, 5fd4855a9 1,720 143 61 41 2 21 18
after, 17f667f86 1,616 39 0 0 0 21 18

src comment here is the 59 census sites plus the 2 in objectstack.config.ts. The drop of 104 citations is exactly the rewritten sites, and the live counts did not move (src comment: 494 resolve, 13 as pull requests, 1 cross-repo; test comment: 504, 20 and 4). A third, raw reading (every # followed by 2 to 6 digits, whatever surrounds it) counts 1,736 before and 1,632 after: a drop of 104.

Comment ids. Three distinct comment-id citations stand on 6 sites in this package: 5234868334 (1 site), 5861435168 (2) and 5865693155 (3). Each was read over the issue-comments endpoint and answers 200 (control 5947712781, 200). So no comment id is in the population.

Per-number table

src counts the census sites plus the four outside the census glob; test counts test-comment sites. Every sha below matches exactly one commit (git rev-parse --disambiguate, count 1) and is an ancestor of the base 5fd4855a9 (git merge-base --is-ancestor, exit 0 for all 13 shas; the clone is not shallow). The + lines introduce exactly these 13 nine-hex spans and no other. The message or the diff of each one names the number it replaces: 6 in the message and the diff (56c093c4d, 0f38ab084, 9dac1ae01, be21955ba, e04a0aff2, d367f03d6), 6 in the diff alone (555a89cbd 28 added lines, 20950404c 7, dce5cd4f0 26, 51efbf116 4, 20032594f 8, b90aff81f 9), and 1 only in the subject's squash suffix (93940d492, where #14434 was that pull request's own number). Each anchor touches packages/drivers/driver-memory itself, except e04a0aff2, whose two sites name the driver-sql fixture it created. git blame at the base puts 67 of the 104 sites on their anchor. The other 37 were written by a different commit that cites the number as another change: for #13197, the declared-index commit b7f645a8a and the atomicity commits 34e80993f and 4642f4c64; for #13195, the clobber generalisation df1812050, the reference-matcher retirement 8fec76a2b, and two commits from while that card was open (178325bcb, 9268aec56, see Wordings to check). In each case the anchor is the commit that made the change the sentence credits to the number. source says whether another lane or stage already used this anchor for this number (reused) or it was measured here (measured).

number src test anchor kind source what it decided
#6075 0 1 d367f03d6 commit reused (stage 4) five drivers' query parameters follow DriverQuery
#10724 2 0 be21955ba commit reused (cli lane, the eleven-package sweep aaad682dbc, spec) retire the nine dead contributes members, drivers among them, with driver-memory's manifest corrected in the same change
#11065 2 3 20950404c commit reused (stage 4) count a boolean aggregand as 1/0 in avg and sum, on driver-memory's data face and analytics face
#11332 2 0 dce5cd4f0 commit reused (cli lane, the eleven-package sweep, spec) retire the plugin manifest's dead top-level containers (capabilities, configuration, extensions), driver-memory's manifest included
#13195 8 11 9dac1ae01 commit reused (spec stage 4) $exists means HAS A VALUE on the live mingo path, the analytics face and translateFilter, with the lowered $exists promoted to its own $and branch when its key is taken; its changeset records the maintainer's 2026-08-30 ruling
#13197 16 11 56c093c4d commit reused (stage 3, the types, rest and spec lanes) driver-memory enforces field-level unique, refusing a colliding write with the ADR-0112 envelope; updateMany checks every row before mutating any
#14434 0 1 93940d492 commit reused (stage 4) un-mask driver-memory's published update / upsert types (that pull request's squash)
#14435 3 3 20032594f commit measured publish the declared return types on find(), findOne() and create()
#16589 23 3 555a89cbd commit reused (the services lane's pointer 5904005321 on this card) refuse a tenant-scoped call instead of returning cross-organization rows: seam 3, assertCallNotTenantScoped
#16729 7 1 0f38ab084 commit reused (stage 4) an explicit tenancy opt-out survives a partial syncSchema re-registration, on driver-memory and driver-sql
#16838 0 4 b90aff81f commit measured read a stored ARRAY as its elements in the equality arm, so both filter faces answer one filter one way
#17348 0 1 51efbf116 commit reused (spec stage 3) type-gate a text operator over a declared temporal column; it pinned driver-memory's divergence by name and recorded the follow-up as filed
#17590 0 2 e04a0aff2 commit reused (stage 4) compile $contains on a JSON column as a per-dialect MEMBERSHIP test; it created the driver-sql fixture these two sites copy

Wordings to check

Most rewrites swap a tag in place ([#N] to [commit SHA], (#N) to (commit SHA), #N's X to commit SHA's X, since #N to since commit SHA), the form the landed stages use. These say more than the tag:

Sites left

  • In comments (src, test, the two config files): none.
  • String literals: 21 test-string sites, 7 numbers, 11 files (describe and it titles, assertion arguments): #13195 7, #13197 7, #11065 2, #16838 2, #14435 1, #16589 1, #16729 1. Every one of the 7 is in this stage's population, so the table above holds an anchor for each. Non-test strings carry none. Strings are outside this stage's surface.
  • Outside src: the release-owned CHANGELOG.md names dead numbers on 18 sites (11 numbers); left. package.json, tsconfig.json, README.md and LICENSE cite no dead number.

Mechanical guard: no code token moves

The guard (stages 2 to 4's) compares base 5fd4855a9 against the working tree over all 27 touched files, with TypeScript 6.0.3 (tsconfig.typecheck.json through ts.parseJsonText, the same two walks):

  • Reading 1: the parser's leaf nodes, from a forEachChild walk. Comments are trivia there, and JSDoc is never visited. A leaf that is not itself a token is re-scanned with trivia skipped.
  • Reading 2: the full token stream in parser context, from a getChildren walk, JSDoc nodes skipped. String, template and numeric literals are compared in full on both readings.

Results:

  • Real run at the head: 61,808 base tokens, 0 files with a token change (exit 0).
  • Comment control (「The declaration dies with the table.」 to 「DIES」, memory-driver.ts): 0 files changed (exit 0).
  • Positive control, an identifier (tenantFieldOf to tenantFieldOfX, memory-unique-constraint.ts): DIFFER on both readings (exit 1).
  • Positive control, a string literal ('MEMORY_MULTI_TENANT_UNSUPPORTED' to …X, memory-tenancy-guard.ts): DIFFER on both readings (exit 1).
  • Positive control, a numeric literal (UNIQUE_VIOLATION_STATUS = 409 to 410, memory-unique-constraint.ts): DIFFER on both readings (exit 1).
  • Positive control, a JSON value ("rootDir": "." to "./", tsconfig.typecheck.json): DIFFER on both readings (exit 1).

Each mutation went through scripts/ablation-replace.mjs (wrap mode, anchor hit 1 to 0) under a shell trap that restores by absolute path from HEAD. Each restore was proven equal to its HEAD blob (ac823bf8fa9b, eb0eb11358ea, 7b008c1f12b7, eb0eb11358ea, 88035b359542), with git diff HEAD empty and a clean tree afterwards.

Changeset: patch (dist measured)

files[] is dist, README.md and CHANGELOG.md, and the package is not private. The dependency closure and the package were built first (turbo run build --filter='@objectstack/driver-memory^...' --filter=@objectstack/driver-memory, 5 of 5 tasks, VERDICT command-exit 0). Then the package's own build (tsup plus check-dts-emitted) ran three times in one script under the shared verify lock (VERDICT command-exit 0), at 17f667f86:

So the rewrite ships, and .changeset/20595-driver-memory-provenance-anchors.md declares a patch for @objectstack/driver-memory, comment text only, with the claim's Clause-②: no line. The later changeset commit and the merge of main touch no file under packages/drivers/driver-memory.

Gates (head 381dddc9c)

  • Derived gates: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands at 381dddc9c (28 paths against merge base fbe2debb7, 220 changed lines) derived 62 commands. All 62 ran, each exit code captured before any pipe: 62 exit 0. --ran reports 「62 derived, 62 run, 0 NOT-MEASURED, 0 UNRUN」 (a derived zero) and exits 0.
  • Roster families the derivation flags under a touched directory, also run, each exit 0: node scripts/check-changeset-fixed.mjs, pnpm check:authz-resolver, pnpm check:error-code-casing, pnpm check:filter-alias-parity, pnpm check:object-def-param-keys, pnpm check:tenant-chokepoint.
  • Named readings: node scripts/check-issue-citations.mjs exits 0 (「every citation this change adds resolves」, 7 judged across 5 files); pnpm check:issue-citations exits 0 (self-test, 173 cases, 9 batteries); pnpm check:doc-authoring exits 0 (the sibling-package prose-id baseline holds, no growth); pnpm check:nul-bytes exits 0 (9,669 files, no raw control bytes), and a control-byte grep over the 28 changed files finds none (exit 1).
  • Build before the gates: turbo run build --filter='./packages/*' --filter='./packages/*/*' --concurrency=2 at 381dddc9c, 71 of 71 tasks, VERDICT command-exit 0.
  • Tests and typecheck, under the verify lock, at 381dddc9c: pnpm --filter @objectstack/driver-memory test: 70 test files pass (70), 1,718 tests pass (1,718), exit 0; pnpm --filter @objectstack/driver-memory typecheck (both programs, tsconfig.json and tsconfig.typecheck.json) exits 0. tsc --listFiles puts all 70 tracked test files and the 25 changed src files in the tsconfig.json program, and objectstack.config.ts in the tsconfig.typecheck.json one.
  • Lint, as a proven narrowing: eslint with inline config disabled, over the 26 touched .ts files plus dist/index.js as the control: 27 results, 0 errors and 1 warning, the control's ignore notice; none of the 26 is reported ignored. eslint.config.mjs never enables type-aware linting (its lines 327-328 say so), so a comment edit cannot move the verdict on an untouched file. tsconfig.typecheck.json is not an eslint target (run alone, eslint answers 「File ignored because no matching configuration was supplied」); the token guard covers it. The repo-wide pnpm lint is CI's run.

Acceptance notes

  • Base. The branch was cut at 5fd4855a9 and merged with main once, at fbe2debb7, before the gates (merge 381dddc9c, no conflict, no file under packages/drivers/driver-memory, and neither check-issue-citations.mjs nor dispatch-gates.mjs). 45ce12a48 (the last driver-memory change before this stage) is in the base (merge-base --is-ancestor exit 0; control 13a24ece2, exit 0). The net diff against main is the 27 rewritten files (+103/−103) and the changeset.
  • One sentence keeps a deictic whose antecedent was the number. memory-exists-has-value-faces.test.ts:264 says 「not in the card」 two lines under the tag that named that card, now [commit 9dac1ae01]. It has no number of its own, so it was not touched.
  • Wording only: no line without a number was changed.

Generated by Claude Code

claude added 3 commits October 2, 2026 08:12
…its that decided them (stage 5 of #20595)

Every comment or docblock site in packages/drivers/driver-memory that cited a
tracker number answering 404 now cites the commit in this repository that
decided it (ruling C+D, form C): 104 sites on 103 lines in 27 files, 13
numbers. Comment prose only; every file keeps its line count.

Claude-Session: https://claude.ai/code/session_017xfMoEjKUuSh2xYB8sCozp
Co-authored-by: Claude <noreply@anthropic.com>
The rewritten docblocks reach the published dist (index.d.ts / index.d.mts and
the JS output), so the package owes a patch changeset.

Claude-Session: https://claude.ai/code/session_017xfMoEjKUuSh2xYB8sCozp
Co-authored-by: Claude <noreply@anthropic.com>
@github-actions github-actions Bot added the size/m label Oct 2, 2026
@github-actions github-actions Bot added documentation Improvements or additions to documentation tests tooling labels Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-memory, touching 22 documentable anchor(s). ⚠️ 4 changed file(s) yielded no anchor (packages/drivers/driver-memory/src/index.ts, packages/drivers/driver-memory/src/memory-tenancy-guard.ts, packages/drivers/driver-memory/src/memory-unique-constraint.ts, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

25 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 3937ad2f327450c0ce4d4ded30acae815ef98810.

⛔ 10 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see
  • 4 changed file(s) yielded no anchor (packages/drivers/driver-memory/src/index.ts, packages/drivers/driver-memory/src/memory-tenancy-guard.ts, packages/drivers/driver-memory/src/memory-unique-constraint.ts, …) — pages documenting those are invisible to this run
  • 5 name(s) were too generic to anchor anything (single lowercase words)
  • the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
  • a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
  • a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 10 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 3937ad2f327450c0ce4d4ded30acae815ef98810 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 86f6f7bde684c227c2dabf87d73c3b554f3f5a79 — the merge of head 381dddc9c67d3d551107674bc471bda703b00719 into base 3937ad2f327450c0ce4d4ded30acae815ef98810, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 86f6f7bde684c227c2dabf87d73c3b554f3f5a79 && git checkout 86f6f7bde684c227c2dabf87d73c3b554f3f5a79
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 3937ad2f327450c0ce4d4ded30acae815ef98810 381dddc9c67d3d551107674bc471bda703b00719 && git checkout -B drift-repro 3937ad2f327450c0ce4d4ded30acae815ef98810 && git merge --no-ff 381dddc9c67d3d551107674bc471bda703b00719

node scripts/docs-audit/affected-docs.mjs --json 3937ad2f327450c0ce4d4ded30acae815ef98810

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 3937ad2f327450c0ce4d4ded30acae815ef98810 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/m tests tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants