From 793b1aac13714a7b3e088c16038e17ba57bd95a1 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 10 Sep 2026 02:35:09 +0000 Subject: [PATCH 1/2] docs(spec): cite engine symbols, not line numbers, in functional-completeness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The three `objectql/engine.ts:NNNN` citations in this module's doc block pointed 575 to 5,787 lines away from the text they quote. Re-measured on origin/main 7ddf13dca (engine.ts is now 15,309 lines, not the 15,020 the card recorded): the summary snippet is at 8630 (cited 3001), the `referenceObject` snippet at 8978 (cited 3191), and the formula-plan snippet at 921 (cited 346). Each quoted text occurs exactly once in engine.ts (`grep -cF` = 1/1/1), so "the text is at line N" is a reading. A reader following the stale citations lands on a blank line, on prose inside an unrelated comment block, and — the dangerous one — on a line of plausible-looking `dispatch:` code, so the citation reads as answered when it is not. Repoint each to the enclosing symbol, written in the repo-root `path#symbol` anchor form `packages/spec/liveness/field.json` already uses, plus the verbatim snippet. A line number rots on the next refactor; a symbol plus a unique snippet is greppable and survives movement. The anchor form is load-bearing beyond readability: it moves these three out of `check-spec-docblock-symbol-anchors`' not-judged bucket (the relative `objectql/engine.ts` named no tracked file) and into resolution. That gate now reports `3 symbol (3 declaration)` where it reported 0, so a rename of any of the three methods reddens CI instead of rotting silently. The section heading is corrected in the same breath: it instructed the next author to cite "the runtime line", which is the instruction that produced this drift and now describes none of the block's citations. Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH Co-authored-by: Claude --- .../spec/src/kernel/functional-completeness.ts | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/packages/spec/src/kernel/functional-completeness.ts b/packages/spec/src/kernel/functional-completeness.ts index ea075484f7..3ace372763 100644 --- a/packages/spec/src/kernel/functional-completeness.ts +++ b/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 From 973daafe2db578d284636488a2848c0e20218e67 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 10 Sep 2026 02:56:05 +0000 Subject: [PATCH 2/2] chore(changeset): patch changeset for the functional-completeness citation repair Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH Co-authored-by: Claude --- ...-functional-completeness-symbol-anchors.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 .changeset/spec-functional-completeness-symbol-anchors.md diff --git a/.changeset/spec-functional-completeness-symbol-anchors.md b/.changeset/spec-functional-completeness-symbol-anchors.md new file mode 100644 index 0000000000..5cc858614d --- /dev/null +++ b/.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`.