fix(spec): require a non-empty reference on lookup/master_detail fields

[os-warren]

Fixes#13632

Contract review: this PR carries needs:contract-review (Clause-② — it changes contract accept/reject behaviour in packages/spec), stated here as the second carrier alongside the label.

What

FieldSchema now refuses type: 'lookup' / type: 'master_detail' whose reference is missing or the empty string, via a new check in the existing superRefine chain of packages/spec/src/data/field.zod.ts — the ruling on the card (ADR-0049 enforce-or-remove, option 1). The refusal is prescriptive on the reference path: it names the type, the key, the expected shape (a snake_case target object name) and the fix, and carries no issue number (doc-authoring discipline). The key's TSDoc — which has always called reference required on these two types — now also states the enforcement. No key is removed, renamed or re-shaped: this is an accept-set narrowing only. Empty string and absence are refused alike (the card measured both as accepted before).

Premise measurement (ruling ②, taken BEFORE the tightening)

Census over the whole tree at 8c6a7fc, three channels:

• Structured metadata (all tracked yaml/json parsed and walked): 0 field objects with type lookup/master_detail at all, hence 0 targetless.
• Literal object fixtures in ts/js/md/mdx (balanced-brace block extraction around every type: 'lookup' / type: 'master_detail' occurrence): 515 with a non-empty reference (positive), 179 without — every one triaged below; 0 are authored objects that FieldSchema parses.
• Helper calls Field.lookup(...) / Field.masterDetail(...) (both take the target as a required first positional argument): 209 with a non-empty string-literal target; 22 flagged for review, all resolved as comments, docstrings, markdown API tables, or old-signature blog snippets — 0 real targetless calls.

Positive controls proving the pipeline reads real hits: the showcase field-zoo's f_lookup (target showcase_account) and f_master_detail (target showcase_project) surface through the same scan; the card's own reference_to control still refuses with unrecognized_keys after the change.

Verdict: zero existing authored objects depend on a targetless lookup/master_detail. The premise holds; the narrowing was executed (no fork). Corroborating: lint's relationship/missing-reference (error severity, non-empty check over exactly lookup + master_detail) has long graded the same hole an error, and the troubleshooting docs page already documents missing reference as a validation failure — the publish seam was the one door left open.

The 179 literal negatives, triaged (three-way, per the wizard-tightening precedent)

• Different surface, untouched (the bulk): analytics dataset dimension descriptors, dashboard filter descriptors, UI view column descriptors, object-designer edge styles, inline-grid columns, action/bulk-action param shapes — each parses under its own schema, not FieldSchema. Also untouched: REST route runtime-defense fixtures (public-form-lookup-picker pins what the route does with stored rows that deliberately never passed FieldSchema, including its own LOOKUP_TARGET_MISSING guard), driver fixtures fed straight to the driver (below), lint fixtures fed to pure stack-to-findings validators, and docs that deliberately show the wrong shape as wrong (the field-types skill guide and the troubleshooting page).
• Moved to legal shape (3 sites — the only parse-gated targetless fixtures in the tree, found red by the spec suite): the key-absence sample loops that push a bare type set through FieldSchema.parse — the maxLength/minLength absence pins in field.test.ts and the materialization pin in field-autonumber-default-format.test.ts. Their subject is key-absence propagation, not the lookup accept surface; the lookup sample now carries reference: 'company', other types unchanged.
• Refusal pins, unaffected: reference_to / referenceTo / target alias fixtures across drivers, lint and spec already refuse via unrecognized_keys and still do.

Blast radius noted, deliberately untouched

driver-mongodb (#13222): syncCollectionSchema declining to build the lookup index for a targetless def stays in place as runtime defense for stored/legacy artifacts, and its tests still pass — but the comment inside its "does not index a lookup that declares no target" case, which records that both targetless shapes "parse successfully" on FieldSchema, is now stale as a statement about the current schema. Recorded here for triage rather than edited: driver code and driver tests are out of this card's scope per the dispatch.

Verification

• Reverse verification of the card's measurement table on the rebuilt dist: the three former accepts now refuse on the reference path; the two legal shapes and the reference_to positive control are unchanged.
• New pins (8): missing refused and empty refused for both types, legal accepted for both types (the positive-control leg), non-relationship types untouched, helper builders pass. Name-filtered run: 8 passed.
• Ablation, from the committed fix: mutation proven on disk (anchor grep 1 to 0), name-filtered pins then 4 failed / 4 passed — exactly the four refusal pins red, accepts green — and restoration proven by an empty git diff HEAD plus git hash-object equal to the HEAD blob (d4e3c6b6). The spec suite imports field.zod.ts by relative source path, so no dist rebuild sits in this ablation's resolution path.
• Union at final head e740733 (git rev-parse --short HEAD from the same tree the run measured): full @objectstack/spec suite — verdict line "Test Files 445 passed (445) / Tests 11938 passed (11938)" — chained with pnpm --filter @objectstack/spec typecheck (tsc + scripts + tests programs), lock entry-point verdict "VERDICT command-exit 0" covering both.
• Derived gates (dispatch-gates from this tree at fe5b03c; the script itself flags this tree as 3 commits behind origin/main with 1 derives-from file changed across the range — CI on the merge ref is the authority): 43 families derived; measured green locally, including check:authorable-surface, check:strictness-ledger, check:docs, check:doc-authoring, check:dispatcher-error-vocabulary, check:engine-double-contract, check:where-matcher and the changeset family, after three repairs — the adr-0087 marker below, a system-context census re-anchor (--fix; the superRefine insertion shifted field.zod.ts line numbers by two), and building @objectstack/formula + @objectstack/lint so check:doc-formula-expressions could measure (then green).
• NOT MEASURED locally, preconditions named (CI-owned): check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-coverage, check:type-check-debt (all need the full workspace closure built), check-test-completeness (needs a saved turbo test log), check:pm-half-states (route refused from this container; its exit 3 self-describes as an unread instrument). Repo-wide pnpm lint is CI's run.

Changeset / ADR-0087

@objectstack/specminor with the BREAKING narrative, per the #11519 / #11842 / #13733 narrowing precedents. ADR-0087 disposition: not-required (no-migration-prescription) — no tombstone exists, the parse refusal is the channel that reaches an affected author, and which target a targetless relationship was meant to point at is authoring intent no migration entry can decide; marker in the changeset body.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 2 documentable anchor(s).

27 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 128 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 55519d50363147da03df0af068fb82fcc6d1d8c1 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e80b881f55da1c500d8d261d222ec98dc6c9156c — the merge of head e7407339c968d096bf4e6f945117036dae250fbb into base 55519d50363147da03df0af068fb82fcc6d1d8c1, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e80b881f55da1c500d8d261d222ec98dc6c9156c && git checkout e80b881f55da1c500d8d261d222ec98dc6c9156c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 55519d50363147da03df0af068fb82fcc6d1d8c1 e7407339c968d096bf4e6f945117036dae250fbb && git checkout -B drift-repro 55519d50363147da03df0af068fb82fcc6d1d8c1 && git merge --no-ff e7407339c968d096bf4e6f945117036dae250fbb
node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 55519d50363147da03df0af068fb82fcc6d1d8c1 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-warren]

Fixes#13632

Contract review: this PR carries needs:contract-review (Clause-② — it changes contract accept/reject behaviour in packages/spec), stated here as the second carrier alongside the label.

What

FieldSchema now refuses type: 'lookup' / type: 'master_detail' whose reference is missing or the empty string, via a new check in the existing superRefine chain of packages/spec/src/data/field.zod.ts — the ruling on the card (ADR-0049 enforce-or-remove, option 1). The refusal is prescriptive on the reference path: it names the type, the key, the expected shape (a snake_case target object name) and the fix, and carries no issue number (doc-authoring discipline). The key's TSDoc — which has always called reference required on these two types — now also states the enforcement. No key is removed, renamed or re-shaped: this is an accept-set narrowing only. Empty string and absence are refused alike (the card measured both as accepted before).

Premise measurement (ruling ②, taken BEFORE the tightening)

Census over the whole tree at 8c6a7fc, three channels:

• Structured metadata (all tracked yaml/json parsed and walked): 0 field objects with type lookup/master_detail at all, hence 0 targetless.
• Literal object fixtures in ts/js/md/mdx (balanced-brace block extraction around every type: 'lookup' / type: 'master_detail' occurrence): 515 with a non-empty reference (positive), 179 without — every one triaged below; 0 are authored objects that FieldSchema parses.
• Helper calls Field.lookup(...) / Field.masterDetail(...) (both take the target as a required first positional argument): 209 with a non-empty string-literal target; 22 flagged for review, all resolved as comments, docstrings, markdown API tables, or old-signature blog snippets — 0 real targetless calls.

Positive controls proving the pipeline reads real hits: the showcase field-zoo's f_lookup (target showcase_account) and f_master_detail (target showcase_project) surface through the same scan; the card's own reference_to control still refuses with unrecognized_keys after the change.

Verdict: zero existing authored objects depend on a targetless lookup/master_detail. The premise holds; the narrowing was executed (no fork). Corroborating: lint's relationship/missing-reference (error severity, non-empty check over exactly lookup + master_detail) has long graded the same hole an error, and the troubleshooting docs page already documents missing reference as a validation failure — the publish seam was the one door left open.

The 179 literal negatives, triaged (three-way, per the wizard-tightening precedent)

• Different surface, untouched (the bulk): analytics dataset dimension descriptors, dashboard filter descriptors, UI view column descriptors, object-designer edge styles, inline-grid columns, action/bulk-action param shapes — each parses under its own schema, not FieldSchema. Also untouched: REST route runtime-defense fixtures (public-form-lookup-picker pins what the route does with stored rows that deliberately never passed FieldSchema, including its own LOOKUP_TARGET_MISSING guard), driver fixtures fed straight to the driver (below), lint fixtures fed to pure stack-to-findings validators, and docs that deliberately show the wrong shape as wrong (the field-types skill guide and the troubleshooting page).
• Moved to legal shape (3 sites — the only parse-gated targetless fixtures in the tree, found red by the spec suite): the key-absence sample loops that push a bare type set through FieldSchema.parse — the maxLength/minLength absence pins in field.test.ts and the materialization pin in field-autonumber-default-format.test.ts. Their subject is key-absence propagation, not the lookup accept surface; the lookup sample now carries reference: 'company', other types unchanged.
• Refusal pins, unaffected: reference_to / referenceTo / target alias fixtures across drivers, lint and spec already refuse via unrecognized_keys and still do.

Blast radius noted, deliberately untouched

driver-mongodb (#13222): syncCollectionSchema declining to build the lookup index for a targetless def stays in place as runtime defense for stored/legacy artifacts, and its tests still pass — but the comment inside its "does not index a lookup that declares no target" case, which records that both targetless shapes "parse successfully" on FieldSchema, is now stale as a statement about the current schema. Recorded here for triage rather than edited: driver code and driver tests are out of this card's scope per the dispatch.

Verification

• Reverse verification of the card's measurement table on the rebuilt dist: the three former accepts now refuse on the reference path; the two legal shapes and the reference_to positive control are unchanged.
• New pins (8): missing refused and empty refused for both types, legal accepted for both types (the positive-control leg), non-relationship types untouched, helper builders pass. Name-filtered run: 8 passed.
• Ablation, from the committed fix: mutation proven on disk (anchor grep 1 to 0), name-filtered pins then 4 failed / 4 passed — exactly the four refusal pins red, accepts green — and restoration proven by an empty git diff HEAD plus git hash-object equal to the HEAD blob (d4e3c6b6). The spec suite imports field.zod.ts by relative source path, so no dist rebuild sits in this ablation's resolution path.
• Union at final head e740733 (git rev-parse --short HEAD from the same tree the run measured): full @objectstack/spec suite — verdict line "Test Files 445 passed (445) / Tests 11938 passed (11938)" — chained with pnpm --filter @objectstack/spec typecheck (tsc + scripts + tests programs), lock entry-point verdict "VERDICT command-exit 0" covering both.
• Derived gates (dispatch-gates from this tree at fe5b03c; the script itself flags this tree as 3 commits behind origin/main with 1 derives-from file changed across the range — CI on the merge ref is the authority): 43 families derived; measured green locally, including check:authorable-surface, check:strictness-ledger, check:docs, check:doc-authoring, check:dispatcher-error-vocabulary, check:engine-double-contract, check:where-matcher and the changeset family, after three repairs — the adr-0087 marker below, a system-context census re-anchor (--fix; the superRefine insertion shifted field.zod.ts line numbers by two), and building @objectstack/formula + @objectstack/lint so check:doc-formula-expressions could measure (then green).
• NOT MEASURED locally, preconditions named (CI-owned): check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-coverage, check:type-check-debt (all need the full workspace closure built), check-test-completeness (needs a saved turbo test log), check:pm-half-states (route refused from this container; its exit 3 self-describes as an unread instrument). Repo-wide pnpm lint is CI's run.

Changeset / ADR-0087

@objectstack/specminor with the BREAKING narrative, per the #11519 / #11842 / #13733 narrowing precedents. ADR-0087 disposition: not-required (no-migration-prescription) — no tombstone exists, the parse refusal is the channel that reaches an affected author, and which target a targetless relationship was meant to point at is authoring intent no migration entry can decide; marker in the changeset body.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 2 documentable anchor(s).

27 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 128 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 55519d50363147da03df0af068fb82fcc6d1d8c1 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e80b881f55da1c500d8d261d222ec98dc6c9156c — the merge of head e7407339c968d096bf4e6f945117036dae250fbb into base 55519d50363147da03df0af068fb82fcc6d1d8c1, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e80b881f55da1c500d8d261d222ec98dc6c9156c && git checkout e80b881f55da1c500d8d261d222ec98dc6c9156c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 55519d50363147da03df0af068fb82fcc6d1d8c1 e7407339c968d096bf4e6f945117036dae250fbb && git checkout -B drift-repro 55519d50363147da03df0af068fb82fcc6d1d8c1 && git merge --no-ff e7407339c968d096bf4e6f945117036dae250fbb
node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 55519d50363147da03df0af068fb82fcc6d1d8c1 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-warren]

Fixes#13632

Contract review: this PR carries needs:contract-review (Clause-② — it changes contract accept/reject behaviour in packages/spec), stated here as the second carrier alongside the label.

What

FieldSchema now refuses type: 'lookup' / type: 'master_detail' whose reference is missing or the empty string, via a new check in the existing superRefine chain of packages/spec/src/data/field.zod.ts — the ruling on the card (ADR-0049 enforce-or-remove, option 1). The refusal is prescriptive on the reference path: it names the type, the key, the expected shape (a snake_case target object name) and the fix, and carries no issue number (doc-authoring discipline). The key's TSDoc — which has always called reference required on these two types — now also states the enforcement. No key is removed, renamed or re-shaped: this is an accept-set narrowing only. Empty string and absence are refused alike (the card measured both as accepted before).

Premise measurement (ruling ②, taken BEFORE the tightening)

Census over the whole tree at 8c6a7fc, three channels:

• Structured metadata (all tracked yaml/json parsed and walked): 0 field objects with type lookup/master_detail at all, hence 0 targetless.
• Literal object fixtures in ts/js/md/mdx (balanced-brace block extraction around every type: 'lookup' / type: 'master_detail' occurrence): 515 with a non-empty reference (positive), 179 without — every one triaged below; 0 are authored objects that FieldSchema parses.
• Helper calls Field.lookup(...) / Field.masterDetail(...) (both take the target as a required first positional argument): 209 with a non-empty string-literal target; 22 flagged for review, all resolved as comments, docstrings, markdown API tables, or old-signature blog snippets — 0 real targetless calls.

Positive controls proving the pipeline reads real hits: the showcase field-zoo's f_lookup (target showcase_account) and f_master_detail (target showcase_project) surface through the same scan; the card's own reference_to control still refuses with unrecognized_keys after the change.

Verdict: zero existing authored objects depend on a targetless lookup/master_detail. The premise holds; the narrowing was executed (no fork). Corroborating: lint's relationship/missing-reference (error severity, non-empty check over exactly lookup + master_detail) has long graded the same hole an error, and the troubleshooting docs page already documents missing reference as a validation failure — the publish seam was the one door left open.

The 179 literal negatives, triaged (three-way, per the wizard-tightening precedent)

• Different surface, untouched (the bulk): analytics dataset dimension descriptors, dashboard filter descriptors, UI view column descriptors, object-designer edge styles, inline-grid columns, action/bulk-action param shapes — each parses under its own schema, not FieldSchema. Also untouched: REST route runtime-defense fixtures (public-form-lookup-picker pins what the route does with stored rows that deliberately never passed FieldSchema, including its own LOOKUP_TARGET_MISSING guard), driver fixtures fed straight to the driver (below), lint fixtures fed to pure stack-to-findings validators, and docs that deliberately show the wrong shape as wrong (the field-types skill guide and the troubleshooting page).
• Moved to legal shape (3 sites — the only parse-gated targetless fixtures in the tree, found red by the spec suite): the key-absence sample loops that push a bare type set through FieldSchema.parse — the maxLength/minLength absence pins in field.test.ts and the materialization pin in field-autonumber-default-format.test.ts. Their subject is key-absence propagation, not the lookup accept surface; the lookup sample now carries reference: 'company', other types unchanged.
• Refusal pins, unaffected: reference_to / referenceTo / target alias fixtures across drivers, lint and spec already refuse via unrecognized_keys and still do.

Blast radius noted, deliberately untouched

driver-mongodb (#13222): syncCollectionSchema declining to build the lookup index for a targetless def stays in place as runtime defense for stored/legacy artifacts, and its tests still pass — but the comment inside its "does not index a lookup that declares no target" case, which records that both targetless shapes "parse successfully" on FieldSchema, is now stale as a statement about the current schema. Recorded here for triage rather than edited: driver code and driver tests are out of this card's scope per the dispatch.

Verification

• Reverse verification of the card's measurement table on the rebuilt dist: the three former accepts now refuse on the reference path; the two legal shapes and the reference_to positive control are unchanged.
• New pins (8): missing refused and empty refused for both types, legal accepted for both types (the positive-control leg), non-relationship types untouched, helper builders pass. Name-filtered run: 8 passed.
• Ablation, from the committed fix: mutation proven on disk (anchor grep 1 to 0), name-filtered pins then 4 failed / 4 passed — exactly the four refusal pins red, accepts green — and restoration proven by an empty git diff HEAD plus git hash-object equal to the HEAD blob (d4e3c6b6). The spec suite imports field.zod.ts by relative source path, so no dist rebuild sits in this ablation's resolution path.
• Union at final head e740733 (git rev-parse --short HEAD from the same tree the run measured): full @objectstack/spec suite — verdict line "Test Files 445 passed (445) / Tests 11938 passed (11938)" — chained with pnpm --filter @objectstack/spec typecheck (tsc + scripts + tests programs), lock entry-point verdict "VERDICT command-exit 0" covering both.
• Derived gates (dispatch-gates from this tree at fe5b03c; the script itself flags this tree as 3 commits behind origin/main with 1 derives-from file changed across the range — CI on the merge ref is the authority): 43 families derived; measured green locally, including check:authorable-surface, check:strictness-ledger, check:docs, check:doc-authoring, check:dispatcher-error-vocabulary, check:engine-double-contract, check:where-matcher and the changeset family, after three repairs — the adr-0087 marker below, a system-context census re-anchor (--fix; the superRefine insertion shifted field.zod.ts line numbers by two), and building @objectstack/formula + @objectstack/lint so check:doc-formula-expressions could measure (then green).
• NOT MEASURED locally, preconditions named (CI-owned): check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-coverage, check:type-check-debt (all need the full workspace closure built), check-test-completeness (needs a saved turbo test log), check:pm-half-states (route refused from this container; its exit 3 self-describes as an unread instrument). Repo-wide pnpm lint is CI's run.

Changeset / ADR-0087

@objectstack/specminor with the BREAKING narrative, per the #11519 / #11842 / #13733 narrowing precedents. ADR-0087 disposition: not-required (no-migration-prescription) — no tombstone exists, the parse refusal is the channel that reaches an affected author, and which target a targetless relationship was meant to point at is authoring intent no migration entry can decide; marker in the changeset body.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 2 documentable anchor(s).

27 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 128 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 55519d50363147da03df0af068fb82fcc6d1d8c1 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e80b881f55da1c500d8d261d222ec98dc6c9156c — the merge of head e7407339c968d096bf4e6f945117036dae250fbb into base 55519d50363147da03df0af068fb82fcc6d1d8c1, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e80b881f55da1c500d8d261d222ec98dc6c9156c && git checkout e80b881f55da1c500d8d261d222ec98dc6c9156c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 55519d50363147da03df0af068fb82fcc6d1d8c1 e7407339c968d096bf4e6f945117036dae250fbb && git checkout -B drift-repro 55519d50363147da03df0af068fb82fcc6d1d8c1 && git merge --no-ff e7407339c968d096bf4e6f945117036dae250fbb
node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 55519d50363147da03df0af068fb82fcc6d1d8c1 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-warren]

Fixes#13632

Contract review: this PR carries needs:contract-review (Clause-② — it changes contract accept/reject behaviour in packages/spec), stated here as the second carrier alongside the label.

What

FieldSchema now refuses type: 'lookup' / type: 'master_detail' whose reference is missing or the empty string, via a new check in the existing superRefine chain of packages/spec/src/data/field.zod.ts — the ruling on the card (ADR-0049 enforce-or-remove, option 1). The refusal is prescriptive on the reference path: it names the type, the key, the expected shape (a snake_case target object name) and the fix, and carries no issue number (doc-authoring discipline). The key's TSDoc — which has always called reference required on these two types — now also states the enforcement. No key is removed, renamed or re-shaped: this is an accept-set narrowing only. Empty string and absence are refused alike (the card measured both as accepted before).

Premise measurement (ruling ②, taken BEFORE the tightening)

Census over the whole tree at 8c6a7fc, three channels:

• Structured metadata (all tracked yaml/json parsed and walked): 0 field objects with type lookup/master_detail at all, hence 0 targetless.
• Literal object fixtures in ts/js/md/mdx (balanced-brace block extraction around every type: 'lookup' / type: 'master_detail' occurrence): 515 with a non-empty reference (positive), 179 without — every one triaged below; 0 are authored objects that FieldSchema parses.
• Helper calls Field.lookup(...) / Field.masterDetail(...) (both take the target as a required first positional argument): 209 with a non-empty string-literal target; 22 flagged for review, all resolved as comments, docstrings, markdown API tables, or old-signature blog snippets — 0 real targetless calls.

Positive controls proving the pipeline reads real hits: the showcase field-zoo's f_lookup (target showcase_account) and f_master_detail (target showcase_project) surface through the same scan; the card's own reference_to control still refuses with unrecognized_keys after the change.

Verdict: zero existing authored objects depend on a targetless lookup/master_detail. The premise holds; the narrowing was executed (no fork). Corroborating: lint's relationship/missing-reference (error severity, non-empty check over exactly lookup + master_detail) has long graded the same hole an error, and the troubleshooting docs page already documents missing reference as a validation failure — the publish seam was the one door left open.

The 179 literal negatives, triaged (three-way, per the wizard-tightening precedent)

• Different surface, untouched (the bulk): analytics dataset dimension descriptors, dashboard filter descriptors, UI view column descriptors, object-designer edge styles, inline-grid columns, action/bulk-action param shapes — each parses under its own schema, not FieldSchema. Also untouched: REST route runtime-defense fixtures (public-form-lookup-picker pins what the route does with stored rows that deliberately never passed FieldSchema, including its own LOOKUP_TARGET_MISSING guard), driver fixtures fed straight to the driver (below), lint fixtures fed to pure stack-to-findings validators, and docs that deliberately show the wrong shape as wrong (the field-types skill guide and the troubleshooting page).
• Moved to legal shape (3 sites — the only parse-gated targetless fixtures in the tree, found red by the spec suite): the key-absence sample loops that push a bare type set through FieldSchema.parse — the maxLength/minLength absence pins in field.test.ts and the materialization pin in field-autonumber-default-format.test.ts. Their subject is key-absence propagation, not the lookup accept surface; the lookup sample now carries reference: 'company', other types unchanged.
• Refusal pins, unaffected: reference_to / referenceTo / target alias fixtures across drivers, lint and spec already refuse via unrecognized_keys and still do.

Blast radius noted, deliberately untouched

driver-mongodb (#13222): syncCollectionSchema declining to build the lookup index for a targetless def stays in place as runtime defense for stored/legacy artifacts, and its tests still pass — but the comment inside its "does not index a lookup that declares no target" case, which records that both targetless shapes "parse successfully" on FieldSchema, is now stale as a statement about the current schema. Recorded here for triage rather than edited: driver code and driver tests are out of this card's scope per the dispatch.

Verification

• Reverse verification of the card's measurement table on the rebuilt dist: the three former accepts now refuse on the reference path; the two legal shapes and the reference_to positive control are unchanged.
• New pins (8): missing refused and empty refused for both types, legal accepted for both types (the positive-control leg), non-relationship types untouched, helper builders pass. Name-filtered run: 8 passed.
• Ablation, from the committed fix: mutation proven on disk (anchor grep 1 to 0), name-filtered pins then 4 failed / 4 passed — exactly the four refusal pins red, accepts green — and restoration proven by an empty git diff HEAD plus git hash-object equal to the HEAD blob (d4e3c6b6). The spec suite imports field.zod.ts by relative source path, so no dist rebuild sits in this ablation's resolution path.
• Union at final head e740733 (git rev-parse --short HEAD from the same tree the run measured): full @objectstack/spec suite — verdict line "Test Files 445 passed (445) / Tests 11938 passed (11938)" — chained with pnpm --filter @objectstack/spec typecheck (tsc + scripts + tests programs), lock entry-point verdict "VERDICT command-exit 0" covering both.
• Derived gates (dispatch-gates from this tree at fe5b03c; the script itself flags this tree as 3 commits behind origin/main with 1 derives-from file changed across the range — CI on the merge ref is the authority): 43 families derived; measured green locally, including check:authorable-surface, check:strictness-ledger, check:docs, check:doc-authoring, check:dispatcher-error-vocabulary, check:engine-double-contract, check:where-matcher and the changeset family, after three repairs — the adr-0087 marker below, a system-context census re-anchor (--fix; the superRefine insertion shifted field.zod.ts line numbers by two), and building @objectstack/formula + @objectstack/lint so check:doc-formula-expressions could measure (then green).
• NOT MEASURED locally, preconditions named (CI-owned): check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-coverage, check:type-check-debt (all need the full workspace closure built), check-test-completeness (needs a saved turbo test log), check:pm-half-states (route refused from this container; its exit 3 self-describes as an unread instrument). Repo-wide pnpm lint is CI's run.

Changeset / ADR-0087

@objectstack/specminor with the BREAKING narrative, per the #11519 / #11842 / #13733 narrowing precedents. ADR-0087 disposition: not-required (no-migration-prescription) — no tombstone exists, the parse refusal is the channel that reaches an affected author, and which target a targetless relationship was meant to point at is authoring intent no migration entry can decide; marker in the changeset body.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 2 documentable anchor(s).

27 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 128 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 55519d50363147da03df0af068fb82fcc6d1d8c1 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e80b881f55da1c500d8d261d222ec98dc6c9156c — the merge of head e7407339c968d096bf4e6f945117036dae250fbb into base 55519d50363147da03df0af068fb82fcc6d1d8c1, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e80b881f55da1c500d8d261d222ec98dc6c9156c && git checkout e80b881f55da1c500d8d261d222ec98dc6c9156c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 55519d50363147da03df0af068fb82fcc6d1d8c1 e7407339c968d096bf4e6f945117036dae250fbb && git checkout -B drift-repro 55519d50363147da03df0af068fb82fcc6d1d8c1 && git merge --no-ff e7407339c968d096bf4e6f945117036dae250fbb
node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 55519d50363147da03df0af068fb82fcc6d1d8c1 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-warren]

Fixes#13632

Contract review: this PR carries needs:contract-review (Clause-② — it changes contract accept/reject behaviour in packages/spec), stated here as the second carrier alongside the label.

What

FieldSchema now refuses type: 'lookup' / type: 'master_detail' whose reference is missing or the empty string, via a new check in the existing superRefine chain of packages/spec/src/data/field.zod.ts — the ruling on the card (ADR-0049 enforce-or-remove, option 1). The refusal is prescriptive on the reference path: it names the type, the key, the expected shape (a snake_case target object name) and the fix, and carries no issue number (doc-authoring discipline). The key's TSDoc — which has always called reference required on these two types — now also states the enforcement. No key is removed, renamed or re-shaped: this is an accept-set narrowing only. Empty string and absence are refused alike (the card measured both as accepted before).

Premise measurement (ruling ②, taken BEFORE the tightening)

Census over the whole tree at 8c6a7fc, three channels:

• Structured metadata (all tracked yaml/json parsed and walked): 0 field objects with type lookup/master_detail at all, hence 0 targetless.
• Literal object fixtures in ts/js/md/mdx (balanced-brace block extraction around every type: 'lookup' / type: 'master_detail' occurrence): 515 with a non-empty reference (positive), 179 without — every one triaged below; 0 are authored objects that FieldSchema parses.
• Helper calls Field.lookup(...) / Field.masterDetail(...) (both take the target as a required first positional argument): 209 with a non-empty string-literal target; 22 flagged for review, all resolved as comments, docstrings, markdown API tables, or old-signature blog snippets — 0 real targetless calls.

Positive controls proving the pipeline reads real hits: the showcase field-zoo's f_lookup (target showcase_account) and f_master_detail (target showcase_project) surface through the same scan; the card's own reference_to control still refuses with unrecognized_keys after the change.

Verdict: zero existing authored objects depend on a targetless lookup/master_detail. The premise holds; the narrowing was executed (no fork). Corroborating: lint's relationship/missing-reference (error severity, non-empty check over exactly lookup + master_detail) has long graded the same hole an error, and the troubleshooting docs page already documents missing reference as a validation failure — the publish seam was the one door left open.

The 179 literal negatives, triaged (three-way, per the wizard-tightening precedent)

• Different surface, untouched (the bulk): analytics dataset dimension descriptors, dashboard filter descriptors, UI view column descriptors, object-designer edge styles, inline-grid columns, action/bulk-action param shapes — each parses under its own schema, not FieldSchema. Also untouched: REST route runtime-defense fixtures (public-form-lookup-picker pins what the route does with stored rows that deliberately never passed FieldSchema, including its own LOOKUP_TARGET_MISSING guard), driver fixtures fed straight to the driver (below), lint fixtures fed to pure stack-to-findings validators, and docs that deliberately show the wrong shape as wrong (the field-types skill guide and the troubleshooting page).
• Moved to legal shape (3 sites — the only parse-gated targetless fixtures in the tree, found red by the spec suite): the key-absence sample loops that push a bare type set through FieldSchema.parse — the maxLength/minLength absence pins in field.test.ts and the materialization pin in field-autonumber-default-format.test.ts. Their subject is key-absence propagation, not the lookup accept surface; the lookup sample now carries reference: 'company', other types unchanged.
• Refusal pins, unaffected: reference_to / referenceTo / target alias fixtures across drivers, lint and spec already refuse via unrecognized_keys and still do.

Blast radius noted, deliberately untouched

driver-mongodb (#13222): syncCollectionSchema declining to build the lookup index for a targetless def stays in place as runtime defense for stored/legacy artifacts, and its tests still pass — but the comment inside its "does not index a lookup that declares no target" case, which records that both targetless shapes "parse successfully" on FieldSchema, is now stale as a statement about the current schema. Recorded here for triage rather than edited: driver code and driver tests are out of this card's scope per the dispatch.

Verification

• Reverse verification of the card's measurement table on the rebuilt dist: the three former accepts now refuse on the reference path; the two legal shapes and the reference_to positive control are unchanged.
• New pins (8): missing refused and empty refused for both types, legal accepted for both types (the positive-control leg), non-relationship types untouched, helper builders pass. Name-filtered run: 8 passed.
• Ablation, from the committed fix: mutation proven on disk (anchor grep 1 to 0), name-filtered pins then 4 failed / 4 passed — exactly the four refusal pins red, accepts green — and restoration proven by an empty git diff HEAD plus git hash-object equal to the HEAD blob (d4e3c6b6). The spec suite imports field.zod.ts by relative source path, so no dist rebuild sits in this ablation's resolution path.
• Union at final head e740733 (git rev-parse --short HEAD from the same tree the run measured): full @objectstack/spec suite — verdict line "Test Files 445 passed (445) / Tests 11938 passed (11938)" — chained with pnpm --filter @objectstack/spec typecheck (tsc + scripts + tests programs), lock entry-point verdict "VERDICT command-exit 0" covering both.
• Derived gates (dispatch-gates from this tree at fe5b03c; the script itself flags this tree as 3 commits behind origin/main with 1 derives-from file changed across the range — CI on the merge ref is the authority): 43 families derived; measured green locally, including check:authorable-surface, check:strictness-ledger, check:docs, check:doc-authoring, check:dispatcher-error-vocabulary, check:engine-double-contract, check:where-matcher and the changeset family, after three repairs — the adr-0087 marker below, a system-context census re-anchor (--fix; the superRefine insertion shifted field.zod.ts line numbers by two), and building @objectstack/formula + @objectstack/lint so check:doc-formula-expressions could measure (then green).
• NOT MEASURED locally, preconditions named (CI-owned): check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-coverage, check:type-check-debt (all need the full workspace closure built), check-test-completeness (needs a saved turbo test log), check:pm-half-states (route refused from this container; its exit 3 self-describes as an unread instrument). Repo-wide pnpm lint is CI's run.

Changeset / ADR-0087

@objectstack/specminor with the BREAKING narrative, per the #11519 / #11842 / #13733 narrowing precedents. ADR-0087 disposition: not-required (no-migration-prescription) — no tombstone exists, the parse refusal is the channel that reaches an affected author, and which target a targetless relationship was meant to point at is authoring intent no migration entry can decide; marker in the changeset body.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 2 documentable anchor(s).

27 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 128 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 55519d50363147da03df0af068fb82fcc6d1d8c1 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e80b881f55da1c500d8d261d222ec98dc6c9156c — the merge of head e7407339c968d096bf4e6f945117036dae250fbb into base 55519d50363147da03df0af068fb82fcc6d1d8c1, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e80b881f55da1c500d8d261d222ec98dc6c9156c && git checkout e80b881f55da1c500d8d261d222ec98dc6c9156c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 55519d50363147da03df0af068fb82fcc6d1d8c1 e7407339c968d096bf4e6f945117036dae250fbb && git checkout -B drift-repro 55519d50363147da03df0af068fb82fcc6d1d8c1 && git merge --no-ff e7407339c968d096bf4e6f945117036dae250fbb
node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 55519d50363147da03df0af068fb82fcc6d1d8c1 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-warren]

Fixes#13632

Contract review: this PR carries needs:contract-review (Clause-② — it changes contract accept/reject behaviour in packages/spec), stated here as the second carrier alongside the label.

What

FieldSchema now refuses type: 'lookup' / type: 'master_detail' whose reference is missing or the empty string, via a new check in the existing superRefine chain of packages/spec/src/data/field.zod.ts — the ruling on the card (ADR-0049 enforce-or-remove, option 1). The refusal is prescriptive on the reference path: it names the type, the key, the expected shape (a snake_case target object name) and the fix, and carries no issue number (doc-authoring discipline). The key's TSDoc — which has always called reference required on these two types — now also states the enforcement. No key is removed, renamed or re-shaped: this is an accept-set narrowing only. Empty string and absence are refused alike (the card measured both as accepted before).

Premise measurement (ruling ②, taken BEFORE the tightening)

Census over the whole tree at 8c6a7fc, three channels:

• Structured metadata (all tracked yaml/json parsed and walked): 0 field objects with type lookup/master_detail at all, hence 0 targetless.
• Literal object fixtures in ts/js/md/mdx (balanced-brace block extraction around every type: 'lookup' / type: 'master_detail' occurrence): 515 with a non-empty reference (positive), 179 without — every one triaged below; 0 are authored objects that FieldSchema parses.
• Helper calls Field.lookup(...) / Field.masterDetail(...) (both take the target as a required first positional argument): 209 with a non-empty string-literal target; 22 flagged for review, all resolved as comments, docstrings, markdown API tables, or old-signature blog snippets — 0 real targetless calls.

Positive controls proving the pipeline reads real hits: the showcase field-zoo's f_lookup (target showcase_account) and f_master_detail (target showcase_project) surface through the same scan; the card's own reference_to control still refuses with unrecognized_keys after the change.

Verdict: zero existing authored objects depend on a targetless lookup/master_detail. The premise holds; the narrowing was executed (no fork). Corroborating: lint's relationship/missing-reference (error severity, non-empty check over exactly lookup + master_detail) has long graded the same hole an error, and the troubleshooting docs page already documents missing reference as a validation failure — the publish seam was the one door left open.

The 179 literal negatives, triaged (three-way, per the wizard-tightening precedent)

• Different surface, untouched (the bulk): analytics dataset dimension descriptors, dashboard filter descriptors, UI view column descriptors, object-designer edge styles, inline-grid columns, action/bulk-action param shapes — each parses under its own schema, not FieldSchema. Also untouched: REST route runtime-defense fixtures (public-form-lookup-picker pins what the route does with stored rows that deliberately never passed FieldSchema, including its own LOOKUP_TARGET_MISSING guard), driver fixtures fed straight to the driver (below), lint fixtures fed to pure stack-to-findings validators, and docs that deliberately show the wrong shape as wrong (the field-types skill guide and the troubleshooting page).
• Moved to legal shape (3 sites — the only parse-gated targetless fixtures in the tree, found red by the spec suite): the key-absence sample loops that push a bare type set through FieldSchema.parse — the maxLength/minLength absence pins in field.test.ts and the materialization pin in field-autonumber-default-format.test.ts. Their subject is key-absence propagation, not the lookup accept surface; the lookup sample now carries reference: 'company', other types unchanged.
• Refusal pins, unaffected: reference_to / referenceTo / target alias fixtures across drivers, lint and spec already refuse via unrecognized_keys and still do.

Blast radius noted, deliberately untouched

driver-mongodb (#13222): syncCollectionSchema declining to build the lookup index for a targetless def stays in place as runtime defense for stored/legacy artifacts, and its tests still pass — but the comment inside its "does not index a lookup that declares no target" case, which records that both targetless shapes "parse successfully" on FieldSchema, is now stale as a statement about the current schema. Recorded here for triage rather than edited: driver code and driver tests are out of this card's scope per the dispatch.

Verification

• Reverse verification of the card's measurement table on the rebuilt dist: the three former accepts now refuse on the reference path; the two legal shapes and the reference_to positive control are unchanged.
• New pins (8): missing refused and empty refused for both types, legal accepted for both types (the positive-control leg), non-relationship types untouched, helper builders pass. Name-filtered run: 8 passed.
• Ablation, from the committed fix: mutation proven on disk (anchor grep 1 to 0), name-filtered pins then 4 failed / 4 passed — exactly the four refusal pins red, accepts green — and restoration proven by an empty git diff HEAD plus git hash-object equal to the HEAD blob (d4e3c6b6). The spec suite imports field.zod.ts by relative source path, so no dist rebuild sits in this ablation's resolution path.
• Union at final head e740733 (git rev-parse --short HEAD from the same tree the run measured): full @objectstack/spec suite — verdict line "Test Files 445 passed (445) / Tests 11938 passed (11938)" — chained with pnpm --filter @objectstack/spec typecheck (tsc + scripts + tests programs), lock entry-point verdict "VERDICT command-exit 0" covering both.
• Derived gates (dispatch-gates from this tree at fe5b03c; the script itself flags this tree as 3 commits behind origin/main with 1 derives-from file changed across the range — CI on the merge ref is the authority): 43 families derived; measured green locally, including check:authorable-surface, check:strictness-ledger, check:docs, check:doc-authoring, check:dispatcher-error-vocabulary, check:engine-double-contract, check:where-matcher and the changeset family, after three repairs — the adr-0087 marker below, a system-context census re-anchor (--fix; the superRefine insertion shifted field.zod.ts line numbers by two), and building @objectstack/formula + @objectstack/lint so check:doc-formula-expressions could measure (then green).
• NOT MEASURED locally, preconditions named (CI-owned): check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-coverage, check:type-check-debt (all need the full workspace closure built), check-test-completeness (needs a saved turbo test log), check:pm-half-states (route refused from this container; its exit 3 self-describes as an unread instrument). Repo-wide pnpm lint is CI's run.

Changeset / ADR-0087

@objectstack/specminor with the BREAKING narrative, per the #11519 / #11842 / #13733 narrowing precedents. ADR-0087 disposition: not-required (no-migration-prescription) — no tombstone exists, the parse refusal is the channel that reaches an affected author, and which target a targetless relationship was meant to point at is authoring intent no migration entry can decide; marker in the changeset body.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 2 documentable anchor(s).

27 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 128 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 55519d50363147da03df0af068fb82fcc6d1d8c1 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e80b881f55da1c500d8d261d222ec98dc6c9156c — the merge of head e7407339c968d096bf4e6f945117036dae250fbb into base 55519d50363147da03df0af068fb82fcc6d1d8c1, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e80b881f55da1c500d8d261d222ec98dc6c9156c && git checkout e80b881f55da1c500d8d261d222ec98dc6c9156c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 55519d50363147da03df0af068fb82fcc6d1d8c1 e7407339c968d096bf4e6f945117036dae250fbb && git checkout -B drift-repro 55519d50363147da03df0af068fb82fcc6d1d8c1 && git merge --no-ff e7407339c968d096bf4e6f945117036dae250fbb
node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 55519d50363147da03df0af068fb82fcc6d1d8c1 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-warren]

Fixes#13632

Contract review: this PR carries needs:contract-review (Clause-② — it changes contract accept/reject behaviour in packages/spec), stated here as the second carrier alongside the label.

What

FieldSchema now refuses type: 'lookup' / type: 'master_detail' whose reference is missing or the empty string, via a new check in the existing superRefine chain of packages/spec/src/data/field.zod.ts — the ruling on the card (ADR-0049 enforce-or-remove, option 1). The refusal is prescriptive on the reference path: it names the type, the key, the expected shape (a snake_case target object name) and the fix, and carries no issue number (doc-authoring discipline). The key's TSDoc — which has always called reference required on these two types — now also states the enforcement. No key is removed, renamed or re-shaped: this is an accept-set narrowing only. Empty string and absence are refused alike (the card measured both as accepted before).

Premise measurement (ruling ②, taken BEFORE the tightening)

Census over the whole tree at 8c6a7fc, three channels:

• Structured metadata (all tracked yaml/json parsed and walked): 0 field objects with type lookup/master_detail at all, hence 0 targetless.
• Literal object fixtures in ts/js/md/mdx (balanced-brace block extraction around every type: 'lookup' / type: 'master_detail' occurrence): 515 with a non-empty reference (positive), 179 without — every one triaged below; 0 are authored objects that FieldSchema parses.
• Helper calls Field.lookup(...) / Field.masterDetail(...) (both take the target as a required first positional argument): 209 with a non-empty string-literal target; 22 flagged for review, all resolved as comments, docstrings, markdown API tables, or old-signature blog snippets — 0 real targetless calls.

Positive controls proving the pipeline reads real hits: the showcase field-zoo's f_lookup (target showcase_account) and f_master_detail (target showcase_project) surface through the same scan; the card's own reference_to control still refuses with unrecognized_keys after the change.

Verdict: zero existing authored objects depend on a targetless lookup/master_detail. The premise holds; the narrowing was executed (no fork). Corroborating: lint's relationship/missing-reference (error severity, non-empty check over exactly lookup + master_detail) has long graded the same hole an error, and the troubleshooting docs page already documents missing reference as a validation failure — the publish seam was the one door left open.

The 179 literal negatives, triaged (three-way, per the wizard-tightening precedent)

• Different surface, untouched (the bulk): analytics dataset dimension descriptors, dashboard filter descriptors, UI view column descriptors, object-designer edge styles, inline-grid columns, action/bulk-action param shapes — each parses under its own schema, not FieldSchema. Also untouched: REST route runtime-defense fixtures (public-form-lookup-picker pins what the route does with stored rows that deliberately never passed FieldSchema, including its own LOOKUP_TARGET_MISSING guard), driver fixtures fed straight to the driver (below), lint fixtures fed to pure stack-to-findings validators, and docs that deliberately show the wrong shape as wrong (the field-types skill guide and the troubleshooting page).
• Moved to legal shape (3 sites — the only parse-gated targetless fixtures in the tree, found red by the spec suite): the key-absence sample loops that push a bare type set through FieldSchema.parse — the maxLength/minLength absence pins in field.test.ts and the materialization pin in field-autonumber-default-format.test.ts. Their subject is key-absence propagation, not the lookup accept surface; the lookup sample now carries reference: 'company', other types unchanged.
• Refusal pins, unaffected: reference_to / referenceTo / target alias fixtures across drivers, lint and spec already refuse via unrecognized_keys and still do.

Blast radius noted, deliberately untouched

driver-mongodb (#13222): syncCollectionSchema declining to build the lookup index for a targetless def stays in place as runtime defense for stored/legacy artifacts, and its tests still pass — but the comment inside its "does not index a lookup that declares no target" case, which records that both targetless shapes "parse successfully" on FieldSchema, is now stale as a statement about the current schema. Recorded here for triage rather than edited: driver code and driver tests are out of this card's scope per the dispatch.

Verification

• Reverse verification of the card's measurement table on the rebuilt dist: the three former accepts now refuse on the reference path; the two legal shapes and the reference_to positive control are unchanged.
• New pins (8): missing refused and empty refused for both types, legal accepted for both types (the positive-control leg), non-relationship types untouched, helper builders pass. Name-filtered run: 8 passed.
• Ablation, from the committed fix: mutation proven on disk (anchor grep 1 to 0), name-filtered pins then 4 failed / 4 passed — exactly the four refusal pins red, accepts green — and restoration proven by an empty git diff HEAD plus git hash-object equal to the HEAD blob (d4e3c6b6). The spec suite imports field.zod.ts by relative source path, so no dist rebuild sits in this ablation's resolution path.
• Union at final head e740733 (git rev-parse --short HEAD from the same tree the run measured): full @objectstack/spec suite — verdict line "Test Files 445 passed (445) / Tests 11938 passed (11938)" — chained with pnpm --filter @objectstack/spec typecheck (tsc + scripts + tests programs), lock entry-point verdict "VERDICT command-exit 0" covering both.
• Derived gates (dispatch-gates from this tree at fe5b03c; the script itself flags this tree as 3 commits behind origin/main with 1 derives-from file changed across the range — CI on the merge ref is the authority): 43 families derived; measured green locally, including check:authorable-surface, check:strictness-ledger, check:docs, check:doc-authoring, check:dispatcher-error-vocabulary, check:engine-double-contract, check:where-matcher and the changeset family, after three repairs — the adr-0087 marker below, a system-context census re-anchor (--fix; the superRefine insertion shifted field.zod.ts line numbers by two), and building @objectstack/formula + @objectstack/lint so check:doc-formula-expressions could measure (then green).
• NOT MEASURED locally, preconditions named (CI-owned): check-dev-prereqs, check:dual-build-cjs-loads, check:type-check-coverage, check:type-check-debt (all need the full workspace closure built), check-test-completeness (needs a saved turbo test log), check:pm-half-states (route refused from this container; its exit 3 self-describes as an unread instrument). Repo-wide pnpm lint is CI's run.

Changeset / ADR-0087

@objectstack/specminor with the BREAKING narrative, per the #11519 / #11842 / #13733 narrowing precedents. ADR-0087 disposition: not-required (no-migration-prescription) — no tombstone exists, the parse refusal is the channel that reaches an affected author, and which target a targetless relationship was meant to point at is authoring intent no migration entry can decide; marker in the changeset body.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 2 documentable anchor(s).

27 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 128 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 55519d50363147da03df0af068fb82fcc6d1d8c1 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e80b881f55da1c500d8d261d222ec98dc6c9156c — the merge of head e7407339c968d096bf4e6f945117036dae250fbb into base 55519d50363147da03df0af068fb82fcc6d1d8c1, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e80b881f55da1c500d8d261d222ec98dc6c9156c && git checkout e80b881f55da1c500d8d261d222ec98dc6c9156c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 55519d50363147da03df0af068fb82fcc6d1d8c1 e7407339c968d096bf4e6f945117036dae250fbb && git checkout -B drift-repro 55519d50363147da03df0af068fb82fcc6d1d8c1 && git merge --no-ff e7407339c968d096bf4e6f945117036dae250fbb
node scripts/docs-audit/affected-docs.mjs --json 55519d50363147da03df0af068fb82fcc6d1d8c1

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 55519d50363147da03df0af068fb82fcc6d1d8c1 → pass the list as
args.docs, on the commit named under Which tree this was computed on.