Skip to content

docs(driver-turso): re-anchor the dead tracker citations to the commits that decided them (stage 10 of #20595) - #21546

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

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

Conversation

@objectstack-fleet

Copy link
Copy Markdown
Contributor

Part of #20595
Clause-②: no

What changed

Stage 10 of the domain:engine lane of the dead-citation sweep: packages/drivers/driver-turso/**, comment and docblock prose only, per the claim (5965451347). Stages 1 to 9 landed as a7d9768ec, d150c3039, 4bf4e7e70, 13a24ece2, db0cf2231, 85986144c, 48fa7a381, c205b6c35 and c98a72d69. #20595 stays open: the other half of this lane is the packages this stage does not touch (drivers/driver-mongodb 9, formula 4, metadata-fs 2 on the census after this stage, 15 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 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 50 sites on 49 lines in 12 files, covering 13 numbers:

No comment-id citation is dead here: the package's two comment ids, ruling records 5865693155 and 5861435168 (remote-transport.ts:38, :4152 to :4153, turso-20444-empty-operator.test.ts:8), both answer 200 (see Census).

Anchors: 13 numbers by commit, 0 by ADR, 0 by repository qualifier; 12 distinct shas (#17690 and #17876 share be5c60291: the squash of PR #17876, whose message opens 「Part of」 #17690). 12 numbers reuse the anchor stage 4 (driver-sql) measured for them; ca3fd4b1a (#14428) is measured here.

Only comments changed. Every file keeps its line count (49 lines out, 49 in, plus the changeset), so no line citation into any of them moves. No code token moves (the guard below). All 98 changed lines open with a comment marker. 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 #5181, #6210 twice, #6212, #13878 and #20987, each already on its line and each answering 200).

A patch changeset: all 13 rewritten non-test lines are in the published dist (the .d.ts keeps JSDoc on exported members, and esbuild keeps these comments in the JavaScript), 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 31d2255f5 (the before run below), allocated-but-absent per remaining domain:engine package:

package before after this stage
drivers/driver-turso 14 0
drivers/driver-mongodb 9 9
formula 4 4
metadata-fs 2 2
metadata-core, core, 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 29 to 15. driver-turso is the largest remaining package and reads 14, as at stage 9's head census (99f2cfdf0), so the stage went ahead.

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

reading tree board whole-repo allocated-but-absent sites lines files numbers
before base 31d2255f5, run 04:20:17Z to 04:23:32Z enumerated, 194 pages, frontier #21537, 19,358 records 144 14 13 2 8
after 841405134, run 04:32:36Z to 04:35:47Z enumerated, 194 pages, frontier #21539, 19,360 records (newest number read before and after the run: #21539) 130 0 0 0 0

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

The head's later commits are the changeset and one merge of main. The census was run a third time at the head e89bd10cd (04:53:10Z to 04:56:16Z, 194 pages, frontier #21544, 19,365 records, newest #21543 before and #21544 after): whole-repo 130, driver-turso 0. Against the after run, 5 rows moved line (all in packages/spec, shifted by the merged main commit 48eb9c193), and the finding multiset with line numbers set aside is identical. Its resolves reads 35,509, 14 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 (102) and classifies each citation with the gate's classifyCitation against one board enumerated by the gate's enumerateBoard (194 pages, frontier #21537, 19,358 records, read 04:24:21Z to 04:27:29Z), the same board for both readings. Every one of the 13 numbers was then read on its own over the issues endpoint (04:29:27Z): all 13 answer 404; the numbers that stay on changed lines (#5181, #6210, #6212, #13878, #20987) and the lit controls #15280, #12585 and #6402 answer 200.

reading citations dead src comment test comment other files test string changelog
before, 31d2255f5 1,921 83 14 36 0 6 27
after, 841405134 1,871 33 0 0 0 6 27

The citation count drops by 50, the 50 rewritten sites; no respelling stays a citation. The live counts did not move (src comment: 522 resolve, 80 as pull requests, 8 cross-repo; test comment: 609, 75 and 6). A third, raw reading (every # followed by 2 to 6 digits, whatever surrounds it, CHANGELOG.md aside) counts 1,558 before and 1,509 after, and the URL-spelled issue links go 7 to 6: also a drop of 50.

Comment ids. Every ten-digit run under packages/drivers/driver-turso (its CHANGELOG.md aside) was read: five lines. 5861435168 (the record of ruling B on #20311) and 5865693155 (the record of ruling A on #20399) answer 200 (the control 5965451347, the claim, answers 200 too). remote-canonical-backfill.ts:357 is an epoch-seconds example, not a citation.

Per-number table

src counts census sites, test the test-comment sites. Every sha matches exactly one commit (git rev-parse --disambiguate, count 1), is an ancestor of the base 31d2255f5 and of origin/main (git merge-base --is-ancestor, exit 0 for all 12 on both; the clone is not shallow), and resolves over the commits endpoint. The + lines carry exactly these 12 nine-hex spans as new ones. Each commit names the number it replaces, in its message, its diff or both: 7 in the message and the diff (#6075, #12380, #16570, #17590, #17690, #17879, #17970), 3 in the diff alone (#14428 for ca3fd4b1a, #14438 for 2200f8ec8, #16711 for 7862fb711), and 3 only in the subject's squash suffix (#6076 for 6513c1749, #14434 for 93940d492, #17876 for be5c60291), where the dead number was that pull request's own and the commit is its squash. git blame at the base puts 24 of the 49 changed lines on their anchor; the other 25 were written by a commit that cites the number as an earlier decision (242eb0ac1, 9f4a6d55f, 9bfbacbf8 and 6bd3231f6 citing #12380; 3cbcedb62 and e35c40a52 citing #14438; fa2d3b737 citing #6075 and #6076; 5ba2ec3ca citing #17690; 862f12c0b citing #17590; 2200f8ec8 citing #14428; ca3fd4b1a citing #14434; 7862fb711 citing #16570; eb9334915 citing #17876), and in each case the anchor is the commit that made the change the sentence credits to the number. source says whether stage 4 already used this anchor for this number (reused) or it was measured here (measured).

number src test anchor kind source what it decided
#6075 1 1 d367f03d6 commit reused (stage 4, stage 5) five drivers' query parameters follow DriverQuery; its turso diff narrows count's query and leaves options?: any, the half-narrowed state both sites describe. It is the squash of PR #6210, the live number kept beside it
#6076 1 0 6513c1749 commit reused (stage 4) IDataDriver's query parameter becomes DriverQuery (that pull request's squash)
#12380 2 6 4045b954d commit reused (stage 4) make the SQLite Field.json codec injective, one encoding across all three dialects: the local half's codec every site credits
#14428 2 3 ca3fd4b1a commit measured update() on a missing id answers null on Turso's remote face; it wrote the RemoteTransport.update() docblock and the turso-update-missing-id.test.ts header the sites carry, and declared that door's record-or-null return
#14434 0 1 93940d492 commit reused (stage 4, stage 5) declare the not-found arm on IDataDriver.update() (that pull request's squash)
#14438 2 5 2200f8ec8 commit reused (stage 4) update() publishes the contract's record-or-null, not any, on SqlDriver and on TursoDriver's override (the squash of PR #15280)
#16570 1 1 b72226f48 commit reused (stage 4) declare the indexes key initObjects / registerObjectMetadata already read
#16711 1 3 7862fb711 commit reused (stage 4, stage 3) object-definition parameters declare the keys they are read for, plus the gate that sees subclass overrides; it wrote TursoDriver.initObjects's docblock and turso-driver-16711-init-objects-param.test.ts
#17590 0 1 e04a0aff2 commit reused (stage 4, stage 5, stage 8) compile $contains on a JSON column as a per-dialect MEMBERSHIP test
#17690 4 4 be5c60291 commit reused (stage 4) eight more IDataDriver doors publish their declared return type, TursoDriver's overrides among them; its message records the transaction door left un-narrowed because each of the two repairs is 「neither of which is an annotation swap」, with the 「+14 further consumer sites」 measurement, the sentence turso-driver.ts:3549 cites
#17876 0 3 be5c60291 commit reused (stage 4) that pull request's squash, which installed the ContainsAny detector
#17879 0 6 eb9334915 commit reused (stage 4) measure the ContainsAny phantom-leg sweep across eight door pins; its message records that both repair candidates were measured
#17970 0 2 47e6601c5 commit reused (stage 4) collapse ContainsAny's distributivity so union-shaped doors assert

No ADR or ruling record names any of the 13 numbers as the place their decision is recorded; ADR-0104 names #12380 in passing, and 4045b954d is the change these sites describe.

Wordings to check

Most rewrites swap a tag in place ([#N] to [commit SHA], (#N) to (commit SHA), with #N to with commit SHA, stage 1's form). These say more than the tag:

Sites left

Mechanical guard: no code token moves

The guard (stages 2 to 9's, copied verbatim from stage 9) compares base 31d2255f5 against the tree over all 12 touched files, with TypeScript 6.0.3:

  • 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, at 841405134 (the later commits touch none of the 12 files):

  • Real run: 38,590 base tokens, 0 files with a token change (exit 0).
  • Comment control (「Keep it that way」 to 「KEEP it that way」, turso-driver.ts): 0 files changed (exit 0).
  • Positive control, an identifier (export class RemoteTransport to XRemoteTransport, remote-transport.ts): DIFFER on both readings (exit 1).
  • Positive control, a string literal (the assertion message 「… for an existing id」 to 「… for an existing iD」, turso-update-missing-id.test.ts): DIFFER on both readings (exit 1).
  • Positive control, a template literal (the index name 「uniq_ … v」 to 「uniq … _w」, turso-driver-16711-init-objects-param.test.ts): DIFFER on both readings (exit 1).
  • Positive control, a numeric literal (deepArray(1001) to 1002, turso-local-json-backfill-depth-limit.test.ts): 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 (cc15138aba39, 8deefdb0598b, e36d370cb3ed, f9142478172e, 7343e92b5c7d), 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 104s), at 841405134: the dependency closure was built first (pnpm --filter '@objectstack/driver-turso^...' build), then the package's own build (tsup and check-dts-emitted) ran three times:

  • Leg 1, the head text: 6 dist files hashed (index.js, index.mjs, their sourcemaps, index.d.ts, index.d.mts). All 13 rewritten non-test lines appear verbatim in dist. The 5 docblock lines on exported members (remote-transport.ts:1645, :2601, :2612; turso-driver.ts:3689, :3694) are in all four of index.js, index.mjs, index.d.ts and index.d.mts; the 8 // lines in turso-driver.ts are in index.js and index.mjs.
  • Leg 2, the base text put back in the 2 non-test touched files (2 of 2 proven equal to their base blob): 4 of the 6 files differ from leg 1 (index.d.ts, index.d.mts, index.js, index.mjs); the two sourcemaps do not. scripts/ablation-dist-preflight.mjs finds the base marker 「[[finding] MongoDBDriver.update() and RemoteTransport.update() fabricate a record for a missing id — a third posture that becomes a semantic violation once IDataDriver.update() declares null (#13878 ruling item 5) #14428] A miss answers」 in those 4 built files (exit 0).
  • Leg 3, after the proven restore (2 of 2 equal to their HEAD blob, git diff HEAD empty, porcelain empty): all 6 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-driver-turso-provenance-anchors.md declares a patch for @objectstack/driver-turso, comment text only, with the claim's Clause-②: no line. Every anchor is a commit, so it names no ADR, repository qualifier or bracketed substitution; it says which published files carry the reworded text, as measured above. The changeset commit touches no file under packages/drivers/driver-turso.

Gates (head e89bd10cd)

  • Derived gates: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands at e89bd10cd (13 paths against merge base 49161683f, 113 changed lines) derived 65 commands. All 65 ran (04:52:21Z to 05:03:07Z, after the workspace build), 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 550f4cc2f) is a subset: the extra 10 are the eight families the .changeset/ path adds (the ADR-0087 registration and empty-changeset pairs, check:objectui-changeset, check:pm-changeset-deadline-census and two release self-tests) and two gates whose source names packages/drivers/driver-turso/src/turso-driver.ts itself (check:object-def-param-keys, check:tenant-chokepoint).

  • Named readings: node scripts/check-issue-citations.mjs exits 0 (「every citation this change adds resolves (or is a declared cross-repo reference)」: 3 judged across 2 files, the three numbers kept on turso-driver.ts:2131, two of them issues and one a pull request); 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,888 files, no raw control bytes), and a control-byte grep over the 13 changed files finds none (exit 1). The changeset gates (check-changeset-no-major, check-adr-0087-registration, check-empty-changeset with --base origin/main, and check:changeset-gate-self-tests) exit 0; check:object-def-param-keys exits 0 (5 override parameter positions compared).

  • Build, tests and typecheck, under the verify lock: at e89bd10cd, the dependency closure and the package were rebuilt, then pnpm --filter @objectstack/driver-turso test: 88 test files pass (88), 2,365 tests pass and 33 are skipped (2,398); pnpm --filter @objectstack/driver-turso typecheck (tsc --noEmit) exits 0 (VERDICT command-exit 0, held 151s). tsc --listFilesOnly puts all 88 tracked test files and all 12 changed files in tsconfig.json's program. The workspace build after the merge (turbo run build --filter='./packages/*' --filter='./packages/*/*' --concurrency=2, 71 of 71 tasks, 1 cached; VERDICT command-exit 0, held 319s) ran before the gates. No importing package owes a run: the declaration files change only in comment text.

  • Lint, as a proven narrowing, at e89bd10cd: eslint with inline config disabled, over the 12 touched .ts files plus dist/index.js as the control: 13 results, 0 errors and 1 warning, the control's ignore notice; none of the 12 is reported ignored. 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 3 commits October 3, 2026 04:32
…ts that decided them

Comment and docblock prose only, 50 sites on 49 lines in 12 files under
packages/drivers/driver-turso/src: every site citing a tracker number that
answers 404 now cites the commit in this repository's history that made the
decision it describes (13 numbers, 12 distinct commits). 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 declaration files and the
JavaScript output (measured: three builds, head / base text / restored),
so the package ships a patch; comment text only.

Claude-Session: https://claude.ai/code/session_01DDZNkDVwPQnevTFcYE47H3
Co-authored-by: Claude <noreply@anthropic.com>
@github-actions github-actions Bot added size/m 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/driver-turso, touching 2 documentable anchor(s).

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

  • content/docs/data-modeling/drivers.mdx (via TursoDriver (symbol, a top-level class))
  • content/docs/plugins/packages.mdx (via TursoDriver (symbol, a top-level class))
  • content/docs/protocol/objectql/query-syntax.mdx (via TursoDriver (symbol, a top-level class))

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

  • content/docs/releases/v17/17-5.mdx (via TursoDriver (symbol, a top-level class))
  • content/docs/releases/v17/17-6.mdx (via TursoDriver (symbol, a top-level class))

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

Coarse fallback — 7 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 1ac7308d7aadf2c800154afb706d3a3cb0738ddf → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 1ac7308d7aadf2c800154afb706d3a3cb0738ddf

⚠️ 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 1ac7308d7aadf2c800154afb706d3a3cb0738ddf → 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