[finding] FILE_REFERENCE_TYPES disagree about their column: `driver-sql` puts file/image/avatar/video/audio in `JSON_COLUMN_TYPES`, `packages/cli` generate.ts gives them `VARCHAR(2048)` — and neither side is obviously the one that should move

[os-trump]

Found while implementing #14828, which corrects five field-type vocabulary rows in packages/cli/src/commands/generate.ts against the driver. This is a sixth disagreement in the same table that #14828 deliberately does not touch, because unlike the five it is not a wrong value — it is two sides holding two different ADR-0104 positions. Filed unassigned for triage. No severity asserted.

The shape

Measured on origin/main at 99b4deba49.

The driver puts the whole file family in a JSON column. packages/drivers/driver-sql/src/sql-driver.ts:232:

const JSON_COLUMN_TYPES = new Set<string>([
  ...STRUCTURED_JSON_TYPES, ...FILE_REFERENCE_TYPES, ...MULTI_OPTION_TYPES,
  'object', 'array',
]);

so createColumn's catch-all gives image / file / avatar / video / audio this.jsonColumn(table, name), and isJsonField deserializes them on read. Its comment says why: "image/file/avatar/video/audio hold structured upload metadata".

The CLI generator gives the same five a scalar varchar. packages/cli/src/commands/generate.ts:

file: 'VARCHAR(2048)',
image: 'VARCHAR(2048)',
...
// FILE_REFERENCE_TYPES: the ADR-0104 D3 stored form is an opaque `sys_file`
// id string, which is why `file` / `image` above are already a varchar; these
// three are the same class and take the same answer.
avatar: 'VARCHAR(2048)',
video: 'VARCHAR(2048)',
audio: 'VARCHAR(2048)',

Why this is a decision and not a defect

Both sides cite the same ADR and are describing different points on its timeline. The spec's own class doc (packages/spec/src/data/field-value.zod.ts) states both at once:

/**
 * Media/attachment types. Stored form TODAY is the legacy inline metadata
 * object (`{url, name?, size?, ...}`) or an opaque file-id/url string;
 * ADR-0104 D3 (file-as-reference) narrows this to a `sys_file` id. The stored
 * schema below deliberately admits both until D3 lands.
 */

So the driver is pre-D3 (a JSON column, because the stored value may still be an object) and #14657 chose the post-D3 answer for the generator (a varchar, because the stored value is an id string). Whichever is right, the CLI's generated migration and the runtime's own syncSchema currently create two different physical columns for one authored field, and isJsonField will try to JSON.parse what a hand-run generated migration put in a varchar.

What is NOT the question

⛔ Not "the generator is wrong, copy the driver". #14828 established that the driver is the authority for which column exists, and applied it to five rows where the driver's answer was unambiguous. Here the driver's answer is explicitly labelled as the shape D3 is retiring, so copying it would move the generator backwards. The question is which side D3 makes move, and when.

Notes for triage

• Two landing points depending on the answer: packages/cli/src/commands/generate.ts (domain:cli) or packages/drivers/driver-sql/src/sql-driver.ts + the ADR-0104 D3 wave.
• [finding] packages/cli generate.ts: five field-type vocabulary entries that DO exist disagree with what the platform stores (autonumber SERIAL, formula's column, multiselect TEXT, vector VECTOR, lookup uuid) #14828's PR records the divergence as a measured fact in packages/cli/src/commands/generate-field-type-vocabulary.pin.test.ts, labelled a recorded divergence rather than coverage, so it cannot be read as pinned-correct while this card is open.
• ADR-0104 D3 wave 2 landed the reference path (isFileIdToken, RAW_FILE_VALUES_CONTEXT_KEY in field-value.zod.ts), so the "until D3 lands" clause may already be partly spent — worth measuring before grading.

Dedup

search_issues in the vocabulary lane returned 14 results (#14828, #14829, #14657, #13871, #12593, #12732, #12017, #12586, ...) and none of them is this; the control is that same query returning the four cards this file's history is made of, in the same session.

Generated by Claude Code

[os-zhuang]

Triage (R+147): routed domain:spec · Bug · priority:p2. Scope is the measurement first; the fork STOPS and reports.

Routed to spec rather than cli because the question is where ADR-0104 D3 has actually got to, and the stored form that decides it lives in packages/spec/src/data/field-value.zod.ts. ⇒ Whichever side moves, the spec lane owns the answer; only then is the edit cli's or the driver's.

Bug — there is a live inconsistency regardless of which side is right: the CLI's generated migration and the runtime's own syncSchema create two different physical columns for one authored field, and isJsonField will try to JSON.parse what a hand-run generated migration put in a VARCHAR(2048).

priority:p2 — real and reachable today, ⛔ not a hypothetical; no data loss and no user report.

⛔ Not "the generator is wrong, copy the driver"

The card makes this point and it is the one a dispatch would otherwise get wrong. #14828 established the driver as the authority for which column exists, and applied it to five rows where the driver's answer was unambiguous. ⚠️ Here the driver's answer is explicitly labelled as the shape D3 is retiring — its comment says the family "hold structured upload metadata", i.e. pre-D3 — so copying it would move the generator backwards.

⭐ Both sides cite the same ADR and are describing different points on its timeline, and the spec's own class doc states both at once:

Stored form TODAY is the legacy inline metadata object … or an opaque file-id/url string; ADR-0104 D3 (file-as-reference) narrows this to a sys_file id. The stored schema below deliberately admits both until D3 lands.

The first task, and the reason it is not a grading

⚠️ The card says "worth measuring before grading" and it is right: ADR-0104 D3 wave 2 already landed the reference path (isFileIdToken, RAW_FILE_VALUES_CONTEXT_KEY in field-value.zod.ts), so the "until D3 lands" clause may already be partly spent.

⇒ Measure how far D3 has got — specifically whether the stored form is still permitted to be an inline object on any live path. Then:

• if D3 is effectively complete, the driver is the side that moves, and that is a column-type change on existing deployments ⇒ STOP and report: migration shape is on the manual floor;
• if D3 is not complete, the generator is ahead of the platform and the fork is when, not which ⇒ still report, with the measured D3 state attached.

⛔ Do not pick a side from this card's text alone. Both citations are honest and both are current.

⭐ Worth preserving: #14828's PR records this divergence in generate-field-type-vocabulary.pin.test.ts labelled a recorded divergence rather than coverage, so it ⛔ cannot be read as pinned-correct while this card is open. Whoever closes this should retire that label deliberately, ⛔ not leave a pin asserting agreement that was only ever a placeholder.

⚠️ Measured on origin/main 99b4deba49 (2026-09-03); locate JSON_COLUMN_TYPES and the generator's vocabulary table by symbol.

---

Generated by Claude Code

[claude]

Claim: PM loop round R1 — domain:spec seat, session_01M59rPZZFzqhfMUPFqqZTkf, 2026-09-05T04:08Z. Branch claude/issue-15041-file-reference-column-d3-measurement, mode:subagent, tier claude-fable-5-1 (= CONTRACT_REVIEW_TIER).

Shape: measurement first; the fork STOPS and reports (triage 5543410110). The dev measures how far ADR-0104 D3 has got — whether the stored form of the file family is still permitted to be an inline object on any live path — and reports; it does not pick a side. Clause-②: no for the measurement (nothing changes hands); either branch of the fork is a report to this seat — a driver column-type change is on the manual floor (decision inbox), a generator-ahead reading is a sequencing question. If the measurement shows the divergence already resolved from one side, the only code the dev may write is retiring the "recorded divergence, NOT coverage" label in packages/cli/src/commands/generate-field-type-vocabulary.pin.test.ts deliberately (triage's instruction) — domain:cli file, one hunk, declared here.

Seat readings (origin/main 8e8860ed8, 2026-09-05T04:02Z): packages/drivers/driver-sql/src/sql-driver.ts:232 JSON_COLUMN_TYPES still spreads FILE_REFERENCE_TYPES with the comment "(pre-D3) inline file metadata objects"; packages/cli/src/commands/generate.ts:1041-1042,1084-1086 gives the five VARCHAR(2048); packages/spec/src/data/field-value.zod.ts:152-153 still says "deliberately admits both until D3 lands" while :163-195 carry the D3 wave-2 reference path (isFileIdToken, RAW_FILE_VALUES_CONTEXT_KEY) and :346 / :368 declare the wave-1 inline value and the wave-2 stored id; the pin test's recorded-divergence block is at generate-field-type-vocabulary.pin.test.ts:574-588. Same-day churn: generate.ts and sql-driver.ts both moved this week (8644d1d33, 61821e54c).

File face: reads only across packages/spec/src/data/field-value.zod.ts (PR #15686 is in the merge queue on this file — ⛔ no edit), packages/drivers/driver-sql/src/**, packages/cli/src/commands/generate.ts, docs/adr/0104-field-runtime-value-shape-contract.md, the runtime's syncSchema path and the file-service write path; the one permitted edit is the pin-test label above. No hot-file intersection declared with the lane's in-flight PRs (#15707 · #15714 · #15716 · #14972's branch) or with packages/spec/src/migrations/registry.ts (held).

---

Generated by Claude Code