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

.changeset/spec-functional-completeness-symbol-anchors.md

@@ -0,0 +1,29 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): `functional-completeness`'s three `objectql/engine.ts` citations name symbols instead of line numbers (#16960)
+
+The module doc block of `kernel/functional-completeness.ts` cited the runtime that
+justifies each rule by line number. All three had rotted: re-measured on `origin/main`
+`7ddf13dca` (`engine.ts` is 15,309 lines), the quoted texts live at 8630, 8978 and 921
+against cited 3001, 3191 and 346 — drifts of 5,629, 5,787 and 575. Each quoted text
+occurs exactly once in `engine.ts`, so those are readings rather than artefacts.
+
+The citations are the only limb tying a rule's justification to the runtime that
+implements it, and that limb is walked by a human reading it — nothing in the module can
+notice the runtime moved. `:3191` was the dangerous one: the line it names today is
+ordinary-looking `dispatch:` code, so a reader following it lands somewhere plausible and
+never learns they were sent to the wrong place.
+
+Each now names the enclosing symbol in the repo-root `path#symbol` form
+`packages/spec/liveness/field.json` already uses —
+`packages/objectql/src/engine.ts#buildSummaryIndex`, `#planFormulaProjection`,
+`#expandRelatedRecords` — beside the verbatim snippet. A corrected line number would rot
+again on the next refactor; a symbol plus a unique snippet is greppable and survives
+movement. The anchor form also moves these three from
+`check-spec-docblock-symbol-anchors`' not-judged bucket into resolution (that gate now
+reports `3 symbol (3 declaration)` where it reported `0`), so a rename reddens CI.
+
+Doc text only — no schema, export, type or runtime behaviour changes. It ships because
+this block is emitted into the published `dist/kernel/index.d.ts`.

packages/spec/src/kernel/functional-completeness.ts

@@ -19,7 +19,7 @@
  * duplicate rules onto it so the AI-build path cannot drift from the framework
  * (ADR-0078 §2 — the path-asymmetry the ADR exists to kill).
  *
- * ## Discipline: every rule here cites the runtime line that makes it true
+ * ## Discipline: every rule here cites the runtime site that makes it true
  *
  * The completeness audit's scariest candidate (a "fail-open sharing rule")
  * collapsed on a three-file read, and this campaign shipped four confidently
@@ -28,12 +28,16 @@
  * recorded with the evidence that exempts it. The codebase can be asked;
  * these were:
  *
- * - `summary` w/o `summaryOperations` → `objectql/engine.ts:3001`
+ * - `summary` w/o `summaryOperations` →
+ *   `packages/objectql/src/engine.ts#buildSummaryIndex`, verbatim
  *   `if (d?.type !== 'summary' || !d.summaryOperations) continue;`
- * - `formula` w/o `expression` → `objectql/engine.ts:346` builds the formula
- *   plan only from fields WITH an expression; a bare formula never computes.
- * - `lookup`/`master_detail` w/o `reference` → `objectql/engine.ts:3191`
- *   `$expand` `if (!referenceObject) continue;` — the relationship silently
+ * - `formula` w/o `expression` →
+ *   `packages/objectql/src/engine.ts#planFormulaProjection`, verbatim
+ *   `def?.type === 'formula' && def.expression`: it builds the formula plan
+ *   only from fields WITH an expression, so a bare formula never computes.
+ * - `lookup`/`master_detail` w/o `reference` →
+ *   `packages/objectql/src/engine.ts#expandRelatedRecords` (`$expand`),
+ *   verbatim `if (!referenceObject) continue;` — the relationship silently
  *   never resolves, and the record picker has no target to search.
  * - `select`/`radio` w/o `options` → `record-validator.ts`'s `validateOne`,
  *   verbatim `allowed.length > 0 && !allowed.includes(String(value))`: an