docs(spec): fields stops prescribing a dotted path no driver resolves (#7601) - #7617
Merged
Merged
Conversation
…es (#7601) OS-DEV-REPORT ============= STATUS: complete — all six carded surfaces addressed, plus four extras the completeness sweep found beyond the card's enumeration. Every named gate green. BRANCH: claude/issue-7601-dotted-fields-prose (cut from origin/main @ 59768f7, fresh fetch; dedicated worktree; no `git stash` used anywhere) ISSUE: #7601 — claimed by the PM spec-surface seat (comment 5250873539). Not re-claimed by this session. PREMISE STILL VALID — ANCHOR RE-VERIFICATION @ 59768f7 ------------------------------------------------------ Triage verified the anchors at 2c1988c; #7534 and #7588 merged since. Re-measured at my fetched head. The premise holds in full: every surface still offered the dotted spelling, and the enforcement side (`assertProjectionFieldsExist`) is still live. Line-number drift and one structural change absorbed: 1 query.zod.ts:484 describe -> STILL AT :484, verbatim. No drift. 2 recursive-schema-input-assertions -> STILL AT :74, :99. No drift. 3 17.query-joins-retired.ts:10 -> STILL AT :10, verbatim. No drift. 4 17.query-field-node-object-form- -> STILL AT :8, verbatim. No drift. retired.ts:8 5 json-schema/** artifacts -> ** STRUCTURAL DRIFT — see below ** 6 query-syntax.mdx:140 -> STILL AT :140. No drift. query-syntax.mdx:972 -> DRIFTED to :1007-1011 (the "Joins — removed (#4286)" section). Same text, ~35 lines later. references/data/query.mdx:125,134 -> STILL AT :125, :134. GENERATED (confirmed: build-docs.ts owns all of content/docs/references/**). references/api/contract.mdx:407 -> STILL AT :407. Same, generated. SURFACE 5 IS STALE IN THE CARD — `packages/spec/json-schema/` IS GITIGNORED --------------------------------------------------------------------------- The card calls these "shipped JSON Schema artifacts ... commit the artifacts", and the dispatch brief says the same. That is no longer true at my head: `.gitignore:61` carries `packages/spec/json-schema/`, and `git ls-files` returns nothing under it. The tree is rebuilt by `pnpm gen:schema` as the first step of `pnpm build`; it is a build output, not a tracked artifact. (The ignore predates this card — earliest touch found on that .gitignore line is 2c28df9.) Handled correctly either way: I ran the generator (`gen:schema`), confirmed the regenerated tree carries the corrected text and zero occurrences of the old "optionally dotted" string, and `check:authorable-surface` — the gate that verifies this tree against source — is green. There is simply nothing to commit for surface 5. The regeneration reached WIDER than the card's three files: 8 schema files carry the `fields` description (FindDataRequest, ExportRequest, objectstack.json, Query, DataEngineFindRequest, DataEngineFindOneRequest, DataEngineRequest, EngineQueryOptions), all updated. DIRECTION HELD (not re-litigated) --------------------------------- #7532's ruling taken as settled: dotted projections are refused at the ingress gate; dotted-path RESOLUTION is not authorised and was not implemented here. `FieldNodeSchema` was NOT narrowed — it remains `z.string()`. Verified byte- identical input validity: `packages/spec/src/data/query.test.ts` still asserts `FieldNodeSchema.parse('owner.name')` returns `'owner.name'` and that `QuerySchema.parse({ object: 'task', fields: ['title','owner.name'] })` does not throw, and both pass unchanged. Shape vs semantics split preserved throughout. PER-SURFACE: BEFORE -> AFTER ---------------------------- [1] packages/spec/src/data/query.zod.ts:484 — the normative `fields` describe BEFORE: "Fields to retrieve — field names, optionally dotted to reach through a relationship (`owner.name`). Related *records* are selected with `expand`, not from inside this list." AFTER: "Fields to retrieve — names of the queried object's OWN columns. A dotted path (`owner.name`) is not a projection: no driver resolves one, and the ingress refuses it with `400 INVALID_FIELD` (#7532). Related data is read with `expand`, whose nested QueryAST both filters (`where`) and selects (`fields`) the related record's columns. The projection must RETAIN the foreign-key column: `fields: ['title']` with `expand: 'project_id'` resolves nothing, because the relation is carried by that key — add `'project_id'` and it works. Where the value is wanted on the queried object itself, denormalise it onto that object (a stored field, written when the source changes), the same remedy the sort axis prescribes (#6924)." All four required elements present: dotted path no longer offered; `expand` named as the sanctioned mechanism with its filter+select capability; the FK- retention sharp edge carried verbatim in substance with the card's exact `fields: ['title'] / project_id` example; denormalisation named in #6924's own words ("a stored field, written when the source changes", lifted from 17.engine-find-formula-order-by-refused.ts:11-12). Same file, three SIBLING prescriptions corrected — they sit inside the normative source and would have contradicted the describe line-for-line if left: :276-282 joins-removal source comment. "Related records are read through `expand`; a single related column is a dotted `fields` path (`fields: ['owner.name']`)." -> related records AND single related columns both via `expand`'s nested `fields`; dotted named as refused. :296-302 the `FieldNode` type docblock. "The whole vocabulary is a column (`'name'`) or a dotted path the engine resolves through a relationship field" — factually false, no engine resolves it. -> own columns only, with the shape-vs-semantics split stated explicitly (parses, resolves nothing). :323 FIELD_NODE_OBJECT_FORM_REMOVED — the runtime rejection message an author actually reads. "...or name a single related column with a dotted path (`fields: ['owner.name']`)." -> `expand` keyed on the FK with the retention rule; dotted named as NOT the replacement. :361 QUERY_JOINS_REMOVED — same, for `query.joins`. This one is the source of the generated `joins` rows in BOTH reference docs (query.mdx:134, contract.mdx:416), so correcting it fixed those too. [2] packages/spec/src/recursive-schema-input-assertions.ts:74,99 — the type pins DECISION: **rename + comment** (both were permitted; reasoning below). :74 `queryInput` — the file's one canonical query, labelled "The authoring shape". BEFORE: `fields: ['name', 'owner.email']`, `expand: { owner: ... }`. AFTER: `fields: ['name', 'owner_id']`, `expand: { owner_id: ... }`, with a docblock noting the projection keeps the FK that `expand` resolves through. Still pins exactly what it pinned (only `object` required; `expand` recurses) — the change is which query it uses as the exemplar. :99 `fieldNodeDotted` -> `fieldNodeDottedNotNarrowed`, value unchanged (`'owner.email'`), under a new docblock section headed "The dotted probe is a NON-NARROWING guard, not an endorsement (#7601)". REASONING. Keep-with-comment was the cheaper option and I rejected it. A pin's name is what a future reader sees at the call site and in a failure report; a comment is what they see only if they scroll to the declaration. `fieldNodeDotted` states "there is a dotted field-node concept" in the one place the comment cannot reach. Renaming to `fieldNodeDottedNotNarrowed` makes the pin state its actual job — it fails if someone "fixes" this defect by narrowing `FieldNodeSchema`, which is precisely the move #7601 forbids and which a reader arriving from the corrected prose is most likely to attempt. The assertion itself is untouched and still passes, so the guard is strictly strengthened in legibility, not weakened. The rename is safe: `grep` over packages/ and scripts/ finds zero other references, and the file is not on the public export surface (absent from api-surface/ and export-origins/ — `check:api-surface` and `check:export-origins` both green, confirming no published symbol moved). I also renamed the RUNTIME twin of this pin for the same reason — `packages/spec/src/data/query.test.ts:129`, "accepts a field name, and a dotted path through a relationship" -> "accepts a field name, and still parses a dotted string (shape, not semantics)", with a comment carrying the same non-narrowing argument. The test body is unchanged and passes; only the sentence a failure report prints changed. [3] .../semantic/17.query-joins-retired.ts:10 — the `query.joins` prescription BEFORE (replacement): "expand (`expand: { owner: {...} }`), or a dotted `fields` path for a single related column (`fields: ['owner.name']`)" AFTER: `expand` keyed on the FK, whose nested query selects the related record's own columns; the FK-retention rule spelled out; "A dotted `fields` path is NOT a replacement: no driver ever resolved one, and the ingress refuses it (`400 INVALID_FIELD`, #7532)"; denormalisation named in #6924's words. acceptanceCriteria also corrected — it independently prescribed "single related columns through dotted `fields` paths", which the card's anchor list did not catch. Now: related records AND single related columns through `expand`, FK retained. `reason` deliberately UNCHANGED: it narrates the PAST retirement (#4286 / why `joins` was inert) and its historical clauses are accurate. Only the forward- looking prescription moved, per the tombstone rule. [4] .../semantic/17.query-field-node-object-form-retired.ts:8 — same fix, same replacement text, same acceptanceCriteria correction ("single related columns through dotted paths" -> through `expand` with the FK retained). `reason` untouched for the same reason. [5] packages/spec/json-schema/** — regenerated via the package's own `gen:schema` (build-schemas.ts). Never hand-edited. See the STALE CARD note above: the tree is gitignored, so nothing is committed; `check:generated` verifies it against source and is green. [6] Docs prose content/docs/protocol/objectql/query-syntax.mdx — HAND-WRITTEN (measured: the generator owns only content/docs/references/**). :140-142 the `FieldNode` code-comment in the AST listing. Rewritten to own columns + the parses-but-resolves-nothing split. :1009-11 (card's ":972", drifted) the "Joins — removed" advice, which offered "a dotted `fields` path (`'owner.name'`) for a single related column". Rewritten: `expand` for related records and single related columns alike; a bolded paragraph naming the dotted path as not the alternative, with the refusal and the denormalisation remedy; and a `<Callout type="warn">` (the page's own idiom, used 4x above) that carries the FK-retention edge as the card's two-line before/after code block. This is the sharp edge's first appearance in prose anywhere — it was pinned by #7588's GUARD test and documented nowhere. content/docs/references/data/query.mdx:125,134 and content/docs/references/api/contract.mdx:407,416 — GENERATED (measured, not assumed: build-docs.ts:5 declares it regenerates ALL of content/docs/references/{category}/). Regenerated via `gen:docs`; both the `fields` row and the `joins` row follow from surface 1 and surface [1]:361 respectively. Not hand-edited. content/docs/releases/ — NOT TOUCHED. Confirmed zero paths under it in the diff. COMPLETENESS SWEEP — THE CARD'S SIX WERE NOT COMPLETE ------------------------------------------------------ Swept the whole tree for the dotted spelling (`owner.name` / `owner.email` / "optionally dotted" / "dotted ... path") across .ts/.tsx/.mdx/.md/.json. #7588's enumeration missed four live forward-looking prescriptions. Three were the identical one-line prose fix and are FIXED here; one is a different defect in another package and is reported below, unfixed. FIXED (identical one-line prose fix, in scope): a) content/docs/kernel/contracts/data-engine.mdx:108 — the `EngineQueryOptions` interface listing: `fields?: FieldNode[]; // SELECT — field names ('name', 'owner.name')`. Hand-written page, same prescription, now names own columns and points at `expand`. b) .changeset/query-field-node-object-form-removed.md:43 — a PENDING (unversioned) changeset whose FROM -> TO table gave `fields: ['owner.name']` (dotted path) as the "Now" for the one-related-column case. This is a release-notes INPUT, so left alone it would have compiled the refused spelling into the v17 notes at release time — the exact failure mode the release-notes rule exists to prevent, arriving through the sanctioned channel. Row corrected to `expand` + FK retention. (Editing the pending changeset, not content/docs/releases/ — the compiled page is untouched.) c) The four in-file siblings in query.zod.ts (:276, :296, :323, :361) already itemised under surface [1], and the runtime pin in query.test.ts under surface [2]. Listed here so the count is honest: 6 carded surfaces + 4 extras found by sweep + 5 in-file/in-test siblings = 15 edited locations. VERIFIED-CLEAN, no change needed: d) content/docs/data-modeling/queries.mdx:308-316 — reads as a hit but is already CORRECT and unusually good: it narrates the dotted path as broken, names the `SELECT *` widening (#7589) as the observed result, and prescribes `expand`. Left exactly as is. e) All CHANGELOG.md hits and content/docs/releases/v17.mdx:977 — historical narration of the #4196/#4286 retirements as they shipped. Out of bounds by the tombstone rule and by the releases rule. Untouched. f) `{record.account.name}` / `{owner.name}` template hits (service-automation, formula, lint, trigger-record-change), `collectConditionFields({'owner.name'})` in plugin-security, and the analytics dataset dimension `{ field: 'owner.name' }` — different axes (flow templates, filter keys, dataset compiler), not `fields[]` projection. Not in scope, not touched. FINAL SWEEP RESULT: zero forward-looking dotted-`fields` prescriptions remain outside deliberate historical narration. Every surviving `owner.name` in a projection context is either (i) my corrected prose naming the spelling in order to refuse it, (ii) a tombstone/CHANGELOG narrating the past, or (iii) the non-narrowing pins, which now say so in their names. VERIFICATION ------------ pnpm --filter @objectstack/spec check:generated -> "All 13 generated artifacts are up to date." (13/13 green, including check:docs, check:authorable-surface, check:migration-registry, check:spec-changes, check:upgrade-guide, check:api-surface, check:export-origins) NOTE: check:api-surface reads the BUILT dist and reported red on a fresh checkout before any of my edits (dist absent — "the package is not built"). I ran `pnpm --filter @objectstack/spec build` and re-ran the aggregate; green. The earlier red was the unbuilt-dist precondition, not this diff. pnpm --filter @objectstack/spec check:docs -> "231 generated files in sync with packages/spec" pnpm --filter @objectstack/spec typecheck -> tsc --noEmit clean; check:scripts-typecheck clean; check:test-typecheck OK (debt ledger unchanged at 57 files / 265 errors — not grown) pnpm --filter @objectstack/spec test -> 376 files / 9867 tests passed, 0 failed. Includes the surface-2 pins: the renamed runtime pin passes, and the two retirement-message tests still match the rewritten prescriptions. node scripts/check-nul-bytes.mjs (+ --self-test) -> OK, 7056 text files, no raw ASCII control bytes node scripts/check-doc-authoring.mjs (+ --self-test) -> 375 files clean node scripts/check-empty-changeset.mjs -> green node scripts/check-adr-0087-registration.mjs -> green (no declared- breaking changeset) node scripts/check-changeset-no-major.mjs -> green (no major bump) npx eslint on all five edited .ts files -> clean CHANGESET --------- .changeset/dotted-fields-prose-corrected.md — `patch` for "@objectstack/spec", matching triage's call. Patch is right: the published `.describe()` text and the shipped JSON Schema descriptions move, which is a real change to what the package publishes, but no type, no runtime validation and no wire behaviour changes, and every previously-valid input remains byte-identically valid. The changeset states the no-narrowing decision explicitly so the release notes carry it. OUT-OF-SCOPE FINDINGS (not fixed here — for the PM to route) ------------------------------------------------------------- * packages/objectql/src/engine.ts:6760-6763 — a FALSE implementation comment, and the live code it explains: // Keep relationship paths like `owner.name` — the engine will // resolve those via populate; only validate top-level segment. const head = f.split('.')[0]; return known.has(head); There is no populate step in the engine — content/docs/data-modeling/queries.mdx says so in as many words, and #7601's own measurement confirms it. This is the head-only validation that lets a dotted entry survive into the driver, where it becomes the #7589 `SELECT *` widening. It is `domain:drivers`/objectql, it is code not prose, and it sits inside the #7589 mechanism, so I did not touch it — but the comment is the last place in the repo still asserting that resolution exists, and it will mislead whoever picks up #7589. Suggest folding the comment correction into #7589 rather than a new card. * The card's surface-5 description is stale (json-schema/ is gitignored, not shipped from the repo). Worth correcting in whatever template produced it, since the same "commit the artifacts" instruction will misroute the next card in this family. OPEN QUESTIONS -------------- None blocking. Two judgment calls made and argued rather than escalated, both reversible in review: 1. The type-pin disposition (rename vs keep-with-comment) — the card explicitly left this to the executor; reasoning is under surface [2]. 2. content/docs/protocol/objectql/index.mdx:132-176 was NOT on the card's list and is more than a one-line fix, so flagging it explicitly. It is the docs' single most prominent query example — the "Query Language: Database-Agnostic AST" showcase — and it both used `fields: [..., 'owner.name']` AND claimed the runtime compiles it to a `LEFT JOIN u ON c.owner_id = u.id` (Postgres) and a `$lookup` (MongoDB). Neither happens: `expand` is a second batched `$in` read, driver-agnostic by design. Leaving the headline example teaching the refused spelling while correcting five quieter surfaces would have left the repo self-contradicting, so I fixed it: the query now selects own columns + the FK and expands through it, and the two translations show the single-table SELECT followed by the batched related read that actually runs. If the PM would rather this were its own card, it reverts cleanly as one hunk in one file. Fixes #7601 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GZuvmrzekxHCf2bgVb3Swn
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 106 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
⛔ 7 release-owned page(s) also reference the affected code. These are read-only:
|
github-actions
Bot
added
size/m
documentation
os-help
marked this pull request as ready for review
August 11, 2026 09:25
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #7601
What this does
Six in-repo surfaces offered
fields: ['owner.name']as the supported way to read one related column. No driver implements it, and since #7532 the ingress additionally refuses it with400 INVALID_FIELD. This aligns the declaration to the enforcement — prose and the artifacts generated from it, per #7532's settled ruling.⛔
FieldNodeSchemais NOT narrowed — it staysz.string(). Every input valid before this change parses byte-identically after it; the runtime pin asserting exactly that is kept and passes unchanged. The refusal is a semantic verdict at the ingress gate, not a shape check.Index into the commit report
59768f7. One line drift (query-syntax.mdx:972→:1007); one structural finding below.packages/spec/json-schema/is gitignored at head (.gitignore:61) — a build output, not a tracked artifact. Regenerated and gate-verified; nothing to commit. Regeneration reached 8 schema files, wider than the card's three.query.zod.ts(:276,:296,:323,:361) that would otherwise contradict the corrected describe line-for-line.fieldNodeDotted→fieldNodeDottedNotNarrowed; not on the public export surface (check:api-surfacegreen).Sweep extras beyond the card's six
content/docs/kernel/contracts/data-engine.mdx:108— fixed..changeset/query-field-node-object-form-removed.md:43— a pending changeset whose FROM → TO table gave the dotted path as the "Now". Left alone it would compile the refused spelling into the v17 release notes through the sanctioned channel. Row corrected. (content/docs/releases/itself is untouched — confirmed zero paths under it in the diff.)content/docs/protocol/objectql/index.mdx:132-176— flagged in the report as the one judgment call worth a second look: the docs' headline query example both used'owner.name'and claimed the runtime compiles it to aLEFT JOIN/$lookup. Neither happens. Fixed; reverts cleanly as one hunk if the PM would rather it be its own card.packages/objectql/src/engine.ts:6760— not fixed, reported for routing: a false comment claiming "the engine will resolve those via populate". No populate step exists. Suggest folding into finding: SqlDriver's #3821 recovery ladder widens an unresolvable projection to every field #7589 rather than a new card.Verification
check:generated— 13/13 green (check:docs,check:authorable-surface,check:migration-registry,check:spec-changes,check:upgrade-guide,check:api-surface,check:export-origins, …)pnpm --filter @objectstack/spec test— 376 files / 9867 tests passed, 0 failedtypecheck— clean; test-typecheck debt ledger unchanged (not grown)check-nul-bytes,check-doc-authoring, the three changeset gates,eslinton all edited.ts— greenChangeset:
patchfor@objectstack/spec(published describe text + shipped JSON Schema descriptions move; no wire, type or validation change).Generated by Claude Code