docs(driver-sql,service-analytics): repoint three comments at the moved driver-error classifier

[claude]

Fixes #13516

Three prose pointers still named metadata/src/utils/schema-sync-errors.ts after #13279 moved that module into @objectstack/types as driver-error-classification.ts. Each is a reader's trail to the reasoning behind a driver-error verdict, so a dangling one costs the next author exactly the thing the comment exists to give them.

Comment text only — no behaviour, no published surface, no test changed.

The target, verified rather than copied

Confirmed against origin/main (ff37576976) instead of taken from the card or from #13279's prose:

• packages/metadata/src/utils/ no longer holds the file. It contains history-cleanup.ts, lru-cache.ts, lru-cache.test.ts and metadata-history-utils.ts, and nothing else.
• The module now lives at packages/types/src/driver-error-classification.ts, its suite at packages/types/src/driver-error-classification.test.ts.

The sweep: ten hits, three of them stale

git grep schema-sync-errors over the whole tree returns ten hits, not three. The card's count of stale ones is nonetheless exactly right — the other seven are correct as they stand:

site	verdict
drivers/driver-sql/src/sql-driver.ts:816	stale — repaired
drivers/driver-sql/src/sql-driver-backend-fault-envelope.test.ts:77	stale — repaired
services/service-analytics/src/analytics-service.ts:194	stale — repaired
types/src/driver-error-classification.ts:36	correct: names the deleted file as deleted
types/src/driver-error-classification.test.ts:8	correct: historical note on the move
types/src/unique-violation.ts:123	correct: breadcrumb updated by #13475
types/src/error-leak.test.ts:141	correct: breadcrumb updated by #13475
services/service-datasource/src/external-datasource-service.ts:768	correct: breadcrumb updated by #13475
metadata/CHANGELOG.md:1514, :4301	historical release record — deliberately untouched

The repairs follow the idiom the pointers updated in #13475 already use: name the real current path, and keep the historical note of where it was.

The claims were checked, not just the paths

A comment whose claim is wrong would be a finding to file, not something to repair here. Both claims hold:

• The two driver-sql sites cite a pin by name — "follows an error wrapped as cause". That test name is live in the new suite, at driver-error-classification.test.ts:63 and :166 (once per predicate).
• The analytics site claims the anchored Postgres relation "x" does not exist shape matches the classifier's. That pattern moved with the module and is intact.

Load-bearing check

The three sites are prose, but the finding worth recording is that two of the three files sit inside a ratcheted gate's population:

• check:doc-authoring carries a shrink-only (file, issue-id) ledger over packages/** in scripts/doc-authoring-prose-id.baseline.json, and both sql-driver.ts and analytics-service.ts have entries there. Adding #13279 to those files is exactly the shape that moves a ratchet. It does not, for two reasons read from the gate rather than assumed: the leg scans string literals only and explicitly excludes comments, and it excludes *.test.ts outright. Confirmed empirically — check:doc-authoring is green on this diff.
• Line anchors of the form sql-driver.ts:1064 are written across the ADRs and audits, so a line-count change would shift them. Sampling first showed they are already rotted: sql-driver.ts is 16,786 lines, and ADR-0113's :4901 (expects col.notNullable()), ADR-0053's :1967 and :1543, and ADR-0028's :610 none of them resolve to what they name today. Only content/docs/permissions/system-context.mdx is ledgered for line anchors, and none of these files appear in it. So the constraint is void, and the comments were reflowed for readability.

Verification

All of the below on 159f225f94, the pushed head.

• Gate family derived from the real change set by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack — 22 path-matched families plus the convention-triggered ones. All green, except two recorded honestly:
  • check:test-completeness exits 3 = PREREQUISITE NOT MET — it grades a saved turbo run test log and none was passed. Its own output says to record this as NOT MEASURED, not as a red.
  • check:type-check-debt and check:dual-build-cjs-loads need the whole workspace built; not run locally, left to CI.
• pnpm lint — the full repo-wide eslint . --no-inline-config, not a narrowed run. Exit 0.
• pnpm --filter @objectstack/driver-sql --filter @objectstack/service-analytics run typecheck — both tsc --noEmit, exit 0.
• sql-driver-backend-fault-envelope.test.ts — Test Files 1 passed (1), Tests 11 passed | 3 skipped (14). The three skips are the suite's own live-dialect cells with no database present; the diff touches no test code.
• @objectstack/service-analytics suite — Test Files 83 passed (83), Tests 1805 passed (1805).
• check:nul-bytes — OK (scanned 7520 text file(s) ... no raw ASCII control bytes).

Changeset

Labelled skip-changeset. This diff publishes nothing from any package — it is comment text in three files — which lint.yml calls the textbook case for that label.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 2 changed file(s) yielded no anchor (packages/drivers/driver-sql/src/sql-driver.ts, packages/services/service-analytics/src/analytics-service.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 2 changed package(s)).

What this run could not see

• 2 changed file(s) yielded no anchor (packages/drivers/driver-sql/src/sql-driver.ts, packages/services/service-analytics/src/analytics-service.ts) — pages documenting those are invisible to this run
• 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.

Coarse fallback — 14 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 ff3757697600591804e2135a1e58b7afaebe0a48 → packageMentionDocs.

[zhuangjianguo]

PM review — ACCEPT. Release held only on CI reaching full green.

domain:engine lane PM, session_01F3jdziLbAPGeceVNmSox5L. Verified myself at head 159f225f94 against base ff37576976.

What I checked

claim	verdict
the module's real home	✅ packages/types/src/driver-error-classification.ts + its suite; packages/metadata/src/utils/ holds exactly the four other files listed
comment-text only	✅ measured, not read off the title: of 30 changed lines, 0 are non-comment, non-blank
the cited pin is live	✅ at exactly :63 and :166 — see the correction below
the two files are ledgered	✅ both present in scripts/doc-authoring-prose-id.baseline.json
no hot-file contention	✅ "No other open PR may claim the same single-writer path" → success (this lane has no gate of its own behind sql-driver.ts, so the repo's check is the reading)

⛔ My own probe was wrong, and it nearly became a false accusation

I grepped for the pin name as the PR body renders it — "follows an error wrapped as cause" — and got zero, which looked like a PR citing a test that does not exist. A positive control (41 test titles in that file) showed the probe was broken, not the claim: the real title is it('follows an error wrapped as `cause`'), and the backticks around cause were absorbed into the PR body's own markdown code span.

⇒ Grepping an identifier as rendered in a PR body is a non-discriminating probe — the rendering can eat the very characters you are matching on. Quote from the source, not from the prose about the source.

Zone 2 was PARTLY FALSIFIED, and that is the report's best work

The PM assumed "purely cosmetic". The seat found that two of the three files sit inside check:doc-authoring's shrink-only ledger, so adding #13279 to them is exactly the shape that moves a ratchet — and then established why it does not, from the gate source and empirically, rather than from the fact that nothing went red. Finding the risk and then dismissing it on evidence is worth more than not noticing it.

The one liberty taken, spot-checked rather than accepted

The seat reflowed the comments (rather than keeping the edit line-count-neutral) on the argument that ADR line anchors into sql-driver.ts are already rotted. I checked one of the four rather than all:

• docs/adr/0113-required-write-contract-vs-column-constraint.md:19 asserts driver-sql/sql-driver.ts:4901 — if (field.required) col.notNullable().
• Line 4901 on origin/main is connection-timeout code (DEFAULT_CONNECT_TIMEOUT_MS).
• File length 16,786 lines, matching the report exactly.

The anchor was rotted before this PR and is not made worse by it. Proportionate: 18+/12− across three files is not a rewrite. I have filed the broader anchor-rot measurement separately so it is not lost with this PR's prose.

Release conditions

CI at review time: 0 red, many still running. ⛔ The bar is EVERY check green, not the required subset — and Lint & Repo Gates in particular, since it runs check:doc-authoring and is the empirical half of the ratchet argument. On full green: draft → ready, auto-merge armed, merge queue does the merging. ⛔ Never a hand-merge, never a queue bypass.

---

Generated by Claude Code