Skip to content

docs(core): re-anchor the dead tracker citations to the commits and ADRs that decided them (stage 8 of #20595) - #21506

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

objectstack-fleet[bot] merged 5 commits into
mainfrom
claude/issue-20595-core-citations

Conversation

@objectstack-fleet

Copy link
Copy Markdown
Contributor

Part of #20595
Clause-②: no

What changed

Stage 8 of the domain:engine lane of the dead-citation sweep: packages/core/**, comment and docblock prose only, per the claim (5963404083). Stages 1 to 7 landed as a7d9768ec, d150c3039, 4bf4e7e70, 13a24ece2, db0cf2231, 85986144c and 48fa7a381. #20595 stays open: the other half of this lane is the packages this stage does not touch (metadata-core 19, drivers/driver-turso 14, drivers/driver-mongodb 9, formula 4, metadata-fs 2 on the census after this stage, 48 in all), plus the test-string sites the card carries for a widened stage.

Every comment or docblock site in the package that cited a tracker number answering 404, and the one comment-id citation that answers 404, is rewritten in ruling C+D's form C (record 5749154545 on #19123), in the form #20234 applies it to the spec tree: the ADR when one records the decision, otherwise the commit in this repository's history that made it, otherwise the fact in words. That is 81 sites on 80 lines in 34 files, covering 24 numbers and 1 comment id:

Anchors: 22 numbers by commit, 1 by ADR, 1 by words, and the comment id by ADR; 24 distinct shas. Two numbers are split by subject: #14386 (7cbe705b0 for the plugin-auth program's widening, c49007a7c for the finding the sentence describes, see Wordings) and #17147 (aaacf1d5c for the pin and the seam, 65481183b for the pin's follow-up). #11333 and #17147 share one line. 19 numbers reuse the anchor another lane or stage already used for them; measured here are 5 commits (fd289be45 for #13179, cc00df2f7 for #14919, 7cbe705b0 and c49007a7c for #14386, 65481183b for #17147's follow-up half) and 2 ADR anchors (ADR-0131's 2026-09-17 amendment for #16682, ADR-0025 §3.7 for the comment id). The plugin-security lane's #16682 anchor (9b9581b11) was not taken: it is a different subject (see the table). #11331 takes words, as the spec lane gave it (see Wordings).

Only comments changed. Every file keeps its line count (81 lines out, 81 in, plus the changeset), so no line citation into any of them moves. One changed line carries no number (plugin-artifact-integrity.ts:12, see Wordings). 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 (the only numbers on + lines are #3984, #5286, #5881, #6551, #10869, #11974, #16404 twice and #17978, each already on its line and each answering 200).

A patch changeset: 21 of the 40 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 package and its size

The gate's own node scripts/check-issue-citations.mjs --census --json at base fd96a8473 (the before run below), allocated-but-absent per remaining domain:engine package:

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

The lane total goes 88 to 48. core is the largest remaining package and reads 40, as at stage 7's census (e5d9a5d85), so the stage went ahead.

Census: core, 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/core/.

reading tree board whole-repo allocated-but-absent sites lines files numbers
before base fd96a8473, run 00:07:44Z to 00:11:10Z enumerated, 194 pages, frontier #21494, 19,315 records (newest number read before and after the run: #21494) 203 40 39 17 17
after 195aa6bdb, run 00:27:00Z to 00:30:25Z enumerated, 194 pages, frontier #21498, 19,319 records (newest #21495 before, #21498 after) 163 0 0 0 0

The whole-repo drop is 40, and the two finding sets differ by exactly the 40 rows of this package, removed; none was added. resolves (35,428), resolves-as-pull-request (2,388) and cross-repo-unjudged (1,243) did not move.

The head's later commits are the changeset, one merge of main, and one comment line in resolve-authz-context.ts (the ADR re-anchor of :925, which adds and removes no number). The census was run a third time at the head a4c483901 (00:50:57Z to 00:54:06Z, 194 pages, frontier #21504, 19,325 records, newest #21504 before and after): whole-repo 163, core 0, and its allocated-but-absent finding set is identical to the after run's (0 removed, 0 added). Its resolves reads 35,441, 13 more than above, from the merged main commits outside this package.

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 (175) and classifies each citation with the gate's classifyCitation against one board enumerated by the gate's enumerateBoard (194 pages, frontier #21494, 19,315 records, 00:11:24Z to 00:14:37Z), the same board for both readings. Every one of the 24 numbers in the population was then read on its own over the issues endpoint (00:19:57Z): all 24 answer 404; the lit controls #5286 and #12624 answer 200, and so do the numbers that stay on changed lines (#3984, #5881, #6551, #10869, #11974, #16404, #17978).

reading citations dead src comment test comment vitest.config.ts comment other files (tsconfig*.json / rest) test string changelog
before, fd96a8473 2,048 125 40 34 1 5 / 2 22 21
after, 195aa6bdb 1,968 45 0 0 0 0 / 2 22 21

The citation count drops by exactly the 80 rewritten tracker-number sites (the 81st site is the comment id, which the citation grammar does not read). The live counts did not move (src comment: 755 resolve, 19 as pull requests, 3 cross-repo; test comment: 382, 12 and 4). A third, raw reading (every # followed by 2 to 6 digits, whatever surrounds it) counts 2,069 before and 1,989 after: also a drop of 80. The two other files rows left are a JSON string and a markdown line (see Sites left).

Comment ids. Every ten-digit run under packages/core (its CHANGELOG.md aside) was read. Three distinct comment ids are cited, on four lines: 5257880748 (auth-gate.test.ts:195, inside a verbatim quotation of a ruling) and 5394453215 (platform-admin.ts:5, resolve-authz-context.ts:1076) answer 200; 5486840233 (granted-permissions-not-enforced.pin.test.ts:9) answers 404 and is in this stage's population; the control 5963404083 (the claim) answers 200. The other runs are decimals, epochs and fixtures in tests, and two CI run ids in kernel.ts:33 and :34, which are not citations of this tracker. An issuecomment / discussion_r grep finds no line (exit 1). After the rewrite, 5486840233 stands in 0 files under packages/core.

Per-number table

census counts census sites, outside the six sites outside the census glob, test the test-comment sites. Every sha matches exactly one commit (git rev-parse --disambiguate, count 1) and is an ancestor of the base fd96a8473 (git merge-base --is-ancestor, exit 0 for all 24; the clone is not shallow). The + lines carry exactly these 24 nine-hex spans as new ones (the one other span on a + line, abc4b83ce, was already on its line). Each commit names the number it replaces, in its message, its diff or both, except c49007a7c, whose message names #10869 (see Wordings); each ADR anchor names its number or id in the cited section. git blame at the base puts 52 of the 76 commit-anchored lines on their anchor; the other 24 were written by a commit that cites the number as an earlier decision (for example 07150b33a citing #16721's convergence, baf974527 citing #16649's registration, 82da264e1 citing #6216's closed field set), and 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 census outside test anchor kind source what it decided
#6206 2 0 0 8e13ca876 commit reused (the rest, plugin-security and plugin-sharing lanes) share-link enforcement takes the whole authz envelope, so accessible_org_ids is no longer dropped
#6216 8 0 8 f586f1a89 commit reused (the rest, runtime, mcp, spec, plugin-hono-server and plugin-security lanes) one ExecutionContext assembler with two named anonymous entries; the frozen parity pins and the closed entry field set. Its message does not record the 2026-08-08 ruling, so the sites that name the ruling keep its date
#6241 1 0 0 83a3b1f2e commit reused (the rest lane) normalize the :type segment once per handler, closing the third plural-spelling bypass of the audience gate
#6725 1 0 0 1507ba356 commit reused (stage 3; the spec lane) MetadataFacade object writes reach the map its reads use
#8734 2 0 1 f8eb73601 commit reused (the plugin-auth lane) bind the last-admin standing-key lists to the authz resolver's measured read surface
#10978 0 0 5 4c9780c7a commit reused (stage 2; the runtime lane) authorization ObjectQL doubles enforce limit, by presence
#11330 0 0 2 a9ee98992 commit reused (the spec lane) the manifest.runtime trust-tier text states publish-gate-only enforcement truthfully: the tier half of the same sentence
#11331 2 0 0 none words the spec lane's form (21ab410417: 「The enforce leg is unbuilt.」) it tracked the unpack-time integrity re-verification leg, which was never built; no commit or ADR decides it
#11333 1 0 0 ea4d16420 commit reused (the runtime lane) option A phase 1 of that card, binding an artifact's granted permissions at load (its diff says so); the site names the phase after it
#13179 0 0 2 fd289be45 commit measured strip the tracker ids from HotReloadManager's author-facing refusal messages and re-pin the twins (the 2026-08-29 family adjudication's member half); it wrote both test lines
#13279 7 0 2 6a180e42d commit reused (stages 4 and 6; the service-settings, plugin-hono-server and cloud-connection lanes) fail loud when a permission-store read fails; its message records the 2026-08-30 ruling verbatim
#13324 1 0 0 4cda78c9b commit reused (stages 1, 4 and 6; the types lane) a missing-table error must name the table that was read (readObject)
#13644 1 0 0 34ce8e7db commit reused (stage 3) declare HookContext.referentialFieldClear and populate it on every set-null cleanup write
#14192 1 0 0 4d0d9445a commit reused (the cli and spec lanes, for the same 「strictObject since」 sentence) ManifestSchema goes strict
#14386 0 1 0 7cbe705b0 commit measured put three more package-root plugin manifests inside a tsc program; it widened plugin-auth's tsconfig.examples.json
#14386 0 1 0 c49007a7c commit measured declare plugin-hono-server and put plugin-auth's published example in a tsc program: the example that 「could not resolve, compile or run for anyone who copied it」
#14613 0 3 2 81208086a commit reused (the rest lane) @objectstack/core declares a typecheck script; the test and examples layers enter the ratchet. It wrote all three tsconfig lines
#14919 1 0 1 cc00df2f7 commit measured retire PluginSecurityScanner under ADR-0049; its message records the 2026-09-05 ruling
#16649 2 0 0 613bfbd3d commit reused (stage 4; the runtime and spec lanes) register the fourteen remaining door: 'none' codes in ERROR_CODE_LEDGER, PLUGIN_CONTRACT_VIOLATION and SERVICE_NOT_REGISTERED among them
#16682 1 0 0 ADR-0131's 2026-09-17 amendment ADR measured (the plugin-security lane's 9b9581b11 is the single-posture selection repair, a different subject) the amendment's 「What the ruling did NOT decide」 section quotes the 2026-09-08 ruling verbatim and untranslated, the sentence this site quotes (「retiring the walled write must not retire the single one」). 74832b68f, which wrote the line, quotes it too; the ADR comes first
#16721 7 0 8 51ae73123 commit reused (the cli and plugin-hono-server lanes) LiteKernel.use() enforces the declared plugin contract, converged with ObjectKernel (step 2). Its message does not record the 2026-09-08 ruling, so the sites that name it keep its date; step 1 was a measurement with no commit of its own
#17124 1 0 0 86c505286 commit reused (the service-analytics lane) a dateRange array that is not a two-bound window is refused once, instead of meaning three different things on four faces
#17147 1 0 1 aaacf1d5c commit reused (the spec and runtime lanes) the install-time granted permission set is registered at load and refuses nothing: say so, and pin the measurement. It created the pin file
#17147 0 0 1 65481183b commit measured the pin's follow-up: sweep the retracted phrasing repo-wide instead of reading one file. It wrote the line
#17590 0 0 1 e04a0aff2 commit reused (stages 4 and 5; this package's own json-membership-sql.ts) compile $contains on a JSON column as a per-dialect membership test, the construct that later moved here
#17853 0 1 0 08f5f0e5a commit reused (stage 3; the cli, rest, runtime, types and dogfood lanes, for the same line) a vitest filter that selects no test file says so
comment 5486840233 0 0 1 ADR-0025 §3.7 ADR measured the ruling that fences per-plugin context construction to ADR-0025's install-flow design work; §3.7 records that fence

No ADR or ruling record decides any of the 22 commit-anchored numbers: git grep over docs/adr and scripts/adr-anchors names only two of the 24 numbers, #16682 (ADR-0131, taken as that number's anchor) and #17147 (ADR-0025 §3.7, only as the tracker of the unbuilt seam).

Wordings to check

Most rewrites swap a tag in place ([#N] to [commit SHA], (#N) to (commit SHA), since #N to since commit SHA, pre-#N X to X before commit SHA). These say more than the tag:

Sites left

Mechanical guard: no code token moves

The guard (stages 2 to 7's) compares base fd96a8473 against the tree over all 34 touched files, with TypeScript 6.0.3; the three tsconfig*.json files are parsed with ts.parseJsonText. It ran at 195aa6bdb with the controls below, and again at the head a4c483901:

  • 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: 50,680 base tokens, 0 files with a token change (exit 0), at both trees.
  • Comment control (「distinguish the two」 to 「DISTINGUISH the two」, resolve-authz-context.ts): 0 files changed (exit 0).
  • Positive control, an identifier (PLUGIN_CONTRACT_VIOLATION_CODE to …CODEX, plugin-contract.ts): DIFFER on both readings (exit 1).
  • Positive control, a string literal ('SERVICE_NOT_REGISTERED' to 'SERVICE_NOT_REGISTEREDX', service-not-registered.ts): DIFFER on both readings (exit 1).
  • Positive control, a numeric literal ('b'.repeat(24) to 25, api-key.test.ts): DIFFER on both readings (exit 1).
  • Positive control, a JSON value ("noEmit": true to false, tsconfig.test.json): DIFFER on both readings (exit 1).

Each mutation went through scripts/ablation-replace.mjs (wrap mode, anchor hit 1 to 0, blob changed) under a shell trap that restores by absolute path from HEAD. Each restore was proven equal to its HEAD blob (ca0fbe39fd18, 362e8a56a1b9, d36529c990a5, 5ebcb9050807, d51f5f214b09), 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. In one script under the shared verify lock (VERDICT command-exit 0, held 355s), at 195aa6bdb: the workspace was built first (turbo run build --filter='./packages/*' --filter='./packages/*/*' --concurrency=2, 71 of 71 tasks, 1 cached), then the package's own build (tsup, check-dts-emitted and the dev-prereqs stamp) ran three times:

  • Leg 1, the head text: 14 dist files hashed. Of the 40 rewritten non-test lines, 21 appear verbatim in dist (docblocks on exported members in index.d.ts / index.d.cts; the lite-kernel.ts, plugin-loader.ts and plugin-permission-enforcer.ts ones also in index.js / index.cjs).
  • Leg 2, the base text put back in the 17 non-test touched files (17 of 17 proven equal to their base blob): 6 of the 14 files differ from leg 1 (index.js, index.cjs, index.d.ts, index.d.cts, and the two build-input hash stamps), and scripts/ablation-dist-preflight.mjs finds the base marker 「[[finding] a permission-store read failure resolves as an AUTHENTICATED caller holding ZERO capabilities — the package door answers 403 FORBIDDEN, byte-identical to a genuine capability denial #13279] This function used」 in 2 built files (index.d.ts, index.d.cts; exit 0).
  • Leg 3, after the proven restore (17 of 17 equal to their HEAD blob, git diff HEAD empty, porcelain empty): all 14 files are byte-identical to leg 1, and the preflight's --absent reading exits 0 with a clean tree, so the build is deterministic and the difference is the rewrite.

So the rewrite ships, and .changeset/20595-core-provenance-anchors.md declares a patch for @objectstack/core, comment text only, with the claim's Clause-②: no line. The changeset commit touches no file under packages/core. The one line a4c483901 changed after the legs is a // comment inside a function body: its text as built in leg 3 is in no dist file (grep exit 1), while a docblock line of the same build is in all four index files (since commit 51ae73123 it is ONE statement, the control), so that commit moves no shipped byte.

Gates (head a4c483901)

  • Derived gates: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands at a4c483901 (35 paths against merge base 6f17d1d36, 179 changed lines) derived 65 commands. All 65 ran, each exit code captured before any pipe: 65 exit 0. --ran reports 「65 derived, 65 run, 0 NOT-MEASURED, 0 UNRUN」 (a derived zero) and exits 0. The PM's lead derivation (55 commands, tree 6210f887) is a subset: the extra 10 are check:authz-resolver and check:dispatcher-error-vocabulary, which this package's paths add, and the 8 changeset families.
  • Roster families under touched directories, run as well: node scripts/check-changeset-fixed.mjs, pnpm check:error-code-casing, pnpm check:filter-alias-parity, pnpm check:tenant-chokepoint and pnpm check:object-def-param-keys: 5 exit 0.
  • Named readings: node scripts/check-issue-citations.mjs exits 0 (「every citation this change adds resolves (or is a declared cross-repo reference)」: 6 judged across 17 files, all 6 resolve; they are the live numbers kept on changed lines); pnpm check:issue-citations exits 0 (self-test); pnpm check:doc-authoring exits 0 (the sibling-package prose-id baseline holds, no growth); pnpm check:nul-bytes exits 0 (9,851 files, no raw control bytes), and a control-byte grep over the 35 changed files finds none (exit 1).
  • Tests and typecheck, under the verify lock, at a4c483901 (VERDICT command-exit 0, held 64s): pnpm --filter @objectstack/core test (vitest project local): 76 test files pass (76), 2,156 tests pass (2,156); pnpm --filter @objectstack/core exec vitest run --project repo --maxWorkers=2 (the three repo-reading tests vitest.repo-tests.json lists, two of them touched here): 3 files pass, 48 tests pass; pnpm --filter @objectstack/core typecheck (tsc --noEmit, tsc --noEmit -p tsconfig.examples.json, then check:test-typecheck: 「4 file(s) / 4 error(s) / 4 pinned signature(s) held」) exits 0. The same three were green at 67ef07870, before the last commit. tsc --listFilesOnly puts all 79 tracked test files in tsconfig.test.json's program and the 17 changed non-test src files in tsconfig.json's.
  • Lint, as a proven narrowing, at a4c483901: eslint with inline config disabled, over the 31 touched .ts files plus dist/index.js as the control: 32 results, 0 errors and 1 warning, the control's ignore notice; none of the 31 is reported ignored. The three tsconfig*.json files answer 「File ignored because no matching configuration was supplied」 (not eslint targets). eslint.config.mjs never enables type-aware linting (its lines 327 and 328 say so), so a comment edit cannot move the verdict on an untouched file. The repo-wide pnpm lint is CI's run.

Acceptance notes


Generated by Claude Code

claude added 4 commits October 3, 2026 00:26
…DR that decided them

Comment and docblock prose in packages/core only. 81 sites on 80 lines in
34 files, covering 24 tracker numbers that answer 404 and one dead comment
id, now cite the commit in this repository that decided them (ADR-0025 §3.7
for the comment id; two sites state in words that the unpack-time
re-verification leg is unbuilt). Every file keeps its line count; no code
token moves.

Claude-Session: https://claude.ai/code/session_01DDZNkDVwPQnevTFcYE47H3
Co-authored-by: Claude <noreply@anthropic.com>
The rewritten docblocks reach the published dist (index.d.ts / index.d.cts,
and index.js / index.cjs): measured with a base-text build leg against a
restored-head leg that is byte-identical to the first.

Claude-Session: https://claude.ai/code/session_01DDZNkDVwPQnevTFcYE47H3
Co-authored-by: Claude <noreply@anthropic.com>
… records it verbatim

ADR-0131's 2026-09-17 amendment quotes the same sentence verbatim and
untranslated, so the ADR comes before the commit as its anchor.

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

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/core, touching 7 documentable anchor(s). ⚠️ 15 changed file(s) yielded no anchor (packages/core/src/artifact-packages.ts, packages/core/src/metadata-service-contract.ts, packages/core/src/plugin-contract.ts, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

9 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

  • content/docs/ai/actions-as-tools.mdx (via LiteKernel (symbol, a top-level class))
  • content/docs/ai/natural-language-queries.mdx (via LiteKernel (symbol, a top-level class))
  • content/docs/ai/skills-reference.mdx (via LiteKernel (symbol, a top-level class))
  • content/docs/deployment/environment-variables.mdx (via resolveUserAuthzGrants (symbol, a top-level function))
  • content/docs/kernel/events.mdx (via LiteKernel (symbol, a top-level class))
  • content/docs/plugins/anatomy.mdx (via LiteKernel (symbol, a top-level class))
  • content/docs/plugins/development.mdx (via PluginPermissionEnforcer (symbol, a top-level class))
  • content/docs/plugins/packages.mdx (via LiteKernel (symbol, a top-level class))
  • content/docs/protocol/kernel/plugin-spec.mdx (via PluginPermissionEnforcer (symbol, a top-level class))

⛔ 6 release-owned page(s) also name something this change touched. These are read-only:

  • content/docs/releases/v15.mdx (via LiteKernel (symbol, a top-level class))
  • content/docs/releases/v16.mdx (via resolveUserAuthzGrants (symbol, a top-level function))
  • content/docs/releases/v17/17-1.mdx (via resolveUserAuthzGrants (symbol, a top-level function))
  • content/docs/releases/v17/17-3.mdx (via tryFind (symbol, a top-level function))
  • content/docs/releases/v17/17-4.mdx (via LiteKernel (symbol, a top-level class))
  • content/docs/releases/v17/17-5.mdx (via resolveUserAuthzGrants (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see
  • 15 changed file(s) yielded no anchor (packages/core/src/artifact-packages.ts, packages/core/src/metadata-service-contract.ts, packages/core/src/plugin-contract.ts, …) — pages documenting those are invisible to this run
  • 1 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 — 27 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 2ee8383f4e16248322a45a3e4fde5de75598eef4 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fd0cd0f8b4101bdbebd1ba5404b90881a9e0fb5e — the merge of head bb55f72ec067840cdc6343eba0dbf68c53e23af6 into base 2ee8383f4e16248322a45a3e4fde5de75598eef4, 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 fd0cd0f8b4101bdbebd1ba5404b90881a9e0fb5e && git checkout fd0cd0f8b4101bdbebd1ba5404b90881a9e0fb5e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 2ee8383f4e16248322a45a3e4fde5de75598eef4 bb55f72ec067840cdc6343eba0dbf68c53e23af6 && git checkout -B drift-repro 2ee8383f4e16248322a45a3e4fde5de75598eef4 && git merge --no-ff bb55f72ec067840cdc6343eba0dbf68c53e23af6

node scripts/docs-audit/affected-docs.mjs --json 2ee8383f4e16248322a45a3e4fde5de75598eef4

⚠️ 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 2ee8383f4e16248322a45a3e4fde5de75598eef4 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

…ore rewrite carries

The paragraph named only the two by-words comments. The diff also anchors one
source comment to ADR-0131's 2026-09-17 amendment and one test comment to
ADR-0025 §3.7; the paragraph now says so.

Claude-Session: https://claude.ai/code/session_01DDZNkDVwPQnevTFcYE47H3
Co-authored-by: Claude <noreply@anthropic.com>
@objectstack-fleet
objectstack-fleet Bot marked this pull request as ready for review October 3, 2026 01:45
@objectstack-fleet
objectstack-fleet Bot enabled auto-merge October 3, 2026 01:45
@objectstack-fleet
objectstack-fleet Bot added this pull request to the merge queue Oct 3, 2026
Merged via the queue into main with commit c205b6c Oct 3, 2026
36 checks passed
@objectstack-fleet
objectstack-fleet Bot deleted the claude/issue-20595-core-citations branch October 3, 2026 02:09
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