docs(spec): cite engine symbols, not line numbers, in functional-completeness

[os-bill]

Fixes #16960

Clause-②: no

The module doc block of packages/spec/src/kernel/functional-completeness.ts cited the runtime that justifies each rule by line number. All three objectql/engine.ts:NNNN citations had rotted. Each now names the enclosing symbol plus the verbatim snippet.

Re-measured on current origin/main

⛔ Not transcribed from the card. Ref: origin/main 7ddf13dca (branch point). packages/objectql/src/engine.ts is 15,309 lines — it moved since the card's 97adce2fa reading of 15,020, and every drift figure moved with it.

citation	quoted text	grep -cF	actual line	drift	card said
engine.ts:3001	if (d?.type !== 'summary' || !d.summaryOperations) continue;	1	8630	5,629	8520 / 5,519
engine.ts:3191	if (!referenceObject) continue;	1	8978	5,787	8868 / 5,677
engine.ts:346	def?.type === 'formula' && def.expression	1	921	575	859 / 513

Uniqueness holds at 1 / 1 / 1, so "the text is at line N" is a reading and not an artefact. No snippet needed lengthening and none had vanished — the card's premise stands, only its arithmetic aged.

What a reader following each stale citation lands on today

:346   (blank line, between ENGINE_QUERY_SLOTS and the next doc block)
:3001    * undefined`. The runtime layer sets this once per engine (same boot point
:3191        dispatch: { ...(batchCtx.dispatch as object), index } as HookContext['dispatch'],

:3191 is still the dangerous one, and it has drifted onto different plausible code than the card recorded: a dispatch: property in a per-row hook-context build rather than the for loop the card saw. A reader lands on something that reads like a real answer and never learns they were sent to the wrong place.

Before / after

	before	after
summary	`objectql/engine.ts:3001`	`packages/objectql/src/engine.ts#buildSummaryIndex` + verbatim snippet
formula	`objectql/engine.ts:346` builds the formula plan…	`packages/objectql/src/engine.ts#planFormulaProjection` + verbatim snippet
lookup/master_detail	`objectql/engine.ts:3191`	`packages/objectql/src/engine.ts#expandRelatedRecords` + verbatim snippet

Both buildSummaryIndex and expandRelatedRecords are private methods of export class ObjectQL (declared at engine.ts line 2573, closing at 14757); planFormulaProjection is module-level.

The anchor form is load-bearing, not cosmetic

The repo-root path#symbol form is the one packages/spec/liveness/field.json already uses (packages/objectql/src/engine.ts#expandRelatedRecords), and it does more than read well:

scripts/check-spec-docblock-symbol-anchors.mjs (registered by #17065 on 2026-09-09, after this card was filed) judges packages/spec/src/** doc-block anchors. It declares judgeUntrackedLineAnchors: false, and the old citations spelled a relative objectql/engine.ts, which names no tracked file — so all three sat in its not-judged bucket. Measured both ways on this tree:

pre-fix  ✅ … 0 NEW line anchors …  (183 citations name no tracked file and are not judged)
post-fix ✅ … 0 symbol …            (180 citations name no tracked file and are not judged)
probe    ✅ … 3 symbol (3 declaration, 0 literal) …  (180 not judged)

The delta is exactly 3 — these citations were precisely the difference. In anchor form the gate resolves them (3 symbol (3 declaration) where it reported 0), so renaming any of the three methods now reddens CI instead of rotting silently. That is a stronger outcome than the card's criterion asked for, at no cost to it.

One extra word, declared

The section heading read "every rule here cites the runtime line that makes it true". That sentence is the instruction that produced this drift, and after this change it describes none of the block's citations. Corrected to "the runtime site" — one word, same doc block, same write surface. Called out here so it is reviewed rather than absorbed.

Scope

• Write surface: packages/spec/src/kernel/functional-completeness.ts + one changeset. packages/objectql/src/engine.ts was read-only — it is where the truth was measured, not where the fix lands.
• ⛔ Not widened into a repo-wide anchor gate. That is [finding] a pinned NON-rule in packages/spec justifies itself with a record-validator.ts line number that is 319 lines off, and nothing checks prose line anchors #16441's closing question; a view on it is in the report for the seat to file, and is ⛔ not filed here.
• ⛔ Not rework on [finding] a pinned NON-rule in packages/spec justifies itself with a record-validator.ts line number that is 319 lines off, and nothing checks prose line anchors #16441. That card's census was record-validator.ts-only by design; its dev measured these three, left them and reported them. The fence held.

Changeset — derived, not inherited

packages/spec's files[] carries dist, and src/kernel/index.ts:142 re-exports this module (export * from './functional-completeness'). Measured after pnpm --filter @objectstack/spec build: the edited prose reaches dist/kernel/index.d.ts (and .d.mts) at line 5186, verbatim anchors included, with two positive controls from the same file also landing. Published text moves ⇒ a patch changeset is owed and skip-changeset would have been wrong.

Verification

Derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, then re-derived once the changeset existed (it added 5 commands) and those run too. All exit 0:

• check-spec-docblock-symbol-anchors + --self-test; check:nul-bytes; control-byte scan of the touched file (no hits)
• pnpm --filter @objectstack/spec check:generated — all 15 generated artifacts up to date
• spec check:api-surface · check:docs · check:authorable-surface · check:liveness · check:exported-any · check:dual-source-exports · check:llms-txt · check:empty-state · check:skill-refs · check:variant-docs · check:objectui-pin-citations
• changeset family: check-changeset-no-major (+self-test) · check-adr-0087-registration · check-changeset-fixed · check:changeset-gate-self-tests · check-empty-changeset (+self-test) · check:objectui-changeset · check:pm-changeset-deadline-census · release-rehearsal-clone --self-test
• check:doc-authoring · check:published-files · check:cross-package-test-inputs · check:test-source-alias · check:dts-closure · check-closing-keyword-parity · check-comment-mask-adoption · check-system-context-census · check-keyed-text-bounds · check-undeclared-dep-imports · docs-audit/check-affected-docs
• pnpm --filter @objectstack/spec test — 470 files / 13,218 tests passed
• pnpm --filter @objectstack/spec typecheck — exit 0
• pnpm lint repo-wide (eslint . --no-inline-config) at 973daafe2 — 6,466 files, 0 errors, 0 warnings. Run in full, so no narrowing argument is claimed.

Heavy runs went through scripts/pm/os-verify-lock.sh; exit codes were landed to disk before reading, never through a pipe.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/spec/src/kernel/functional-completeness.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 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/src/kernel/functional-completeness.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 — 134 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 d64bcb63772b850b3ca8ae39779d492e46d3a0a6 → packageMentionDocs.