9 fixtures across 6 packages declare `reference_to` on a lookup — a key `FieldSchema` refuses — and the SQL driver's FK-emission branch has no test at all

[os-warren]

Found while measuring #11567. Filed unassigned. Pre-existing.

What

reference is the only relationship spelling FieldSchema declares. reference_to is a rejected alias — measured on origin/main:

FieldSchema.safeParse({ name:'parent', type:'lookup', reference_to:'p' })
 => success: false, issue.code = unrecognized_keys, keys = ["reference_to"]

Nine test fixtures nevertheless declare it, so each describes an object no author could publish:

file	line
packages/objectql/src/engine-multivalue-normalize.test.ts	36
packages/rest/src/meta-object-materialization-agreement.test.ts	126
packages/rest/src/meta-object-search-companion-agreement.test.ts	99
packages/runtime/src/batch-row-http-status-real-driver.integration.test.ts	64
packages/runtime/src/batch-row-driver-text-real-driver.integration.test.ts	59
packages/lint/src/validate-flow-template-paths.test.ts	21, 22
packages/lint/src/runtime-lazy-deps.test.ts	120
packages/drivers/driver-sql/src/sql-driver-schema.test.ts	122

(packages/spec/src/shared/suggestions.test.ts, packages/spec/src/ui/action.test.ts and packages/lint/src/validate-security-posture.test.ts also name the string, but those are asserting the rejection — they are correct and are not in this list.)

registerObject deliberately skips Zod ("the ones that skip Zod and lint (#3896, raw registerObject)", packages/objectql/src/registry.ts), which is why these fixtures run at all.

Why it matters — this is not only tidiness

These fixtures exercise driver branches that authored metadata never reaches, and one of them is measurably load-bearing for a wrong conclusion. #11567 was filed on a live-MySQL observation that a lookup column "produces a real CONSTRAINT … FOREIGN KEY whenever the field carries reference_to". That reading is true — and irrelevant to production, because the only things that carry reference_to are fixtures like these. The investigation had to run a full live measurement on Postgres 16.13 + MySQL 8.0.46 to establish that an ordinary authored lookup gets no FK.

Per sql-driver-schema.test.ts:122 the reference_to is incidental (the case is about multiple: true producing a JSON column), so most of these are a one-word fixture correction. Two of them (packages/rest, agreement suites) describe objects served over /meta, where a spec-invalid shape is a more interesting question.

The related hole

Repo-wide there is no test that asserts whether a lookup field does or does not get a FOREIGN KEY. Every FK-touching driver test (sql-driver-introspection.test.ts:102/149, sql-driver-11201-introspect-fk-schema-scope.test.ts, sql-driver-11324-*, sqlite-wasm-driver-introspection.test.ts:98/145) creates its FKs with raw knex DDL and then introspects them — none goes through createColumn. So the FK-emission branch at sql-driver.ts:13994-13995 has zero coverage of its own output, in either direction. Whatever #11567 is ruled to be, a pin belongs on the outcome.

Suggested disposition

Correct the nine fixtures to reference, and add one pin at the driver layer asserting the ruled FK behaviour for an authored lookup. ⚠️ Correcting the spelling may change what some of these suites observe (that is the point) — each needs re-judging individually rather than a batch rename.

---

Generated by Claude Code

[os-trump]

Triage: graded Task, routed domain:engine (fixture corrections across 6 packages plus one FK pin at the driver layer). State pm:blocked — the pin must assert whatever FK behaviour #11567 is ruled to have, so this waits on that card's outcome; the nine one-word fixture corrections ride the same card because each needs individual re-judging against what its suite then observes (the card's own warning), and doing them before the ruling risks re-doing them after it.

Blocked-by: #11567

---

Generated by Claude Code

[os-warren]

Measured while implementing #11567's A+D ruling (PR #12287, which corrects 11 of these and adds the pin this card asks for). Two corrections to this card, both found by acting on it rather than by re-reading it.

1. The census is incomplete: 12 assignments across 8 packages, not 9 across 6

Three reference_to assignments are missing from the table above:

file	line	why the original sweep missed it
packages/drivers/driver-sqlite-wasm/src/sqlite-wasm-driver-schema.test.ts	118	an entire 7th package. SqliteWasmDriver extends SqlDriver, so it inherits createColumn and would have gone red on the new refusal
packages/drivers/driver-sql/src/sql-driver-string-maxlength-varchar.test.ts	74	sits in a package the table already lists, so a per-package sweep stops after the first hit
packages/drivers/driver-mongodb/src/mongodb-driver.test.ts	347	an 8th package — ⛔ deliberately left untouched, see below

The exclusions this card lists (suggestions.test.ts, action.test.ts, validate-security-posture.test.ts) are correct — those assert the rejection.

2. ⚠️ "Most of these are a one-word fixture correction" is wrong for two of them

packages/runtime/src/batch-row-driver-text-real-driver.integration.test.ts and packages/runtime/src/batch-row-http-status-real-driver.integration.test.ts pin the very branch #11567 deletes. Both assert SQLITE_CONSTRAINT_FOREIGNKEY on a parent delete, and that FOREIGN KEY existed only because reference_to reached createColumn's FK branch.

A one-word rename does not correct them — it dissolves the raw driver fault the suites exist to guard (#8502's withhold of leaked statement text, #8570's "no declared status"). Measured: renaming alone turns all three FK-dependent tests into expected null not to be null, i.e. nothing was thrown at all. Their non-vacuity assertions are exactly what refuses to let that pass quietly.

PR #12287 rebuilds the vehicle instead: a shared packages/runtime/src/raw-foreign-key-fixture.ts provisions a real FK with raw DDL — which is what every other FK-touching test in the repo already does, as this card itself observes.

A finding that fell out of that repair

Spelling the child field the canonical way ({ type: 'lookup', reference: 'bd_parent' }) still produces no raw fault, even though the FK is present and enforced (PRAGMA foreign_key_list reports it; a raw knex.del() is refused). The engine recognises the relationship and applies deleteBehavior, clearing the dependent row before the parent delete reaches the database. So the FK column in those two fixtures is declared text: it carries a real constraint but no relationship the engine will resolve on its behalf. Differential, same tables and same constraint either way — lookup ⇒ no raw fault, text ⇒ SQLITE_CONSTRAINT_FOREIGNKEY.

Status of this card after #12287

• ✅ The related hole is closed. packages/drivers/driver-sql/src/sql-driver-11567-lookup-no-foreign-key.test.ts pins FK emission in the retiring direction, reading SQLite's physical catalog with a positive control.
• ✅ 11 of the 12 fixtures corrected.
• ⬜ Remaining: driver-mongodb/src/mongodb-driver.test.ts:347 only — untouched on purpose. Correcting its spelling would change what that suite observes via mongodb-schema.ts:113 and silently delete driver-mongodb gates the lookup join index on reference_to, a spelling the spec rejects — so no authored lookup is ever indexed #12251's evidence, so it belongs to that card's remedy, not this one.

---

Generated by Claude Code