[spec] 13 of 49 declared field types have no `Field.*` builder, so authors silently drop to the literal `{ type: … }` form

[qq9340100]

Restart-when: any PR edits the Field builder object in packages/spec/src/data/field.zod.ts (add Field.time as the minimal declared rider — three packages/spec comments already name it as existing)

Observation recorded while implementing #6533 (adding a time field to showcase_invoice_line). Filed unassigned, not fixed — out of that card's scope.

What was measured

packages/spec/src/data/field.zod.ts declares 49 members in FieldType, and the Field convenience object next to it exposes 36 builders. Cross-referencing the two (allowing masterDetail for master_detail), 13 declared field types have no Field.* builder:

audio  checkboxes  composite  multiselect  progress  radio  record
repeater  tags  time  toggle  tree  video

An author reaching for one of these has to write the literal object instead — which is exactly what the showcase already does:

// examples/app-showcase/src/data/objects/field-zoo.object.ts
f_date: Field.date({ label: 'Date' }),
f_datetime: Field.datetime({ label: 'Date / Time' }),
f_time: { type: 'time', label: 'Time' },     // no Field.time

Why it is worth recording rather than shrugging at

The literal form is fully valid — the contract is FieldType plus the field schema, not the Field helper — so nothing is broken and no runtime behaviour differs. The cost is authoring-surface asymmetry:

• the three temporal types split two-and-one (Field.date, Field.datetime, but a literal for time), which reads as an oversight at the call site rather than a decision;
• the builders give parameter typing and discoverability that the literal form does not, so the 13 types are the ones an AI author is most likely to get wrong — the direction AGENTS.md's "make AI-written metadata hard to get wrong" argues against.

Whether the right answer is "add the missing builders", "document the literal form as the intended shape for these types", or "leave it, the helper is deliberately partial" is a judgement call, which is why this is a finding and not a fix.

Not claimed

No claim that any of the 13 is unsupported: time in particular is fully live end-to-end — validated by field-value.zod.ts as HH:mm[:ss], stored, and rendered by the inline grid's time control, all exercised on a real machine in #6533.

Anchors (verified on origin/main @ 189a7322)

• packages/spec/src/data/field.zod.ts — FieldType enum, and the Field builder object below it
• examples/app-showcase/src/data/objects/field-zoo.object.ts — the literal-form precedent

---

Generated by Claude Code

---

Generated by Claude Code

[hotlong]

Triage — re-routed and first-touch graded.

Route corrected: domain:devx → domain:spec-surface. The landing file is packages/spec/src/data/field.zod.ts (the Field builder object), so the anchoring rule puts it in the spec seat, not devx. Sub-seat by the accept-face test: Field.time({ label }) produces exactly the { type: 'time', label } an author may already write literally today, so metadata legal before is byte-for-byte identically judged after ⇒ surface, not the semantic seat. (All three spec sub-seats are held by seat #6017 today, but the label should still be true.)

Grade: pm:on-hold — deferred, with named restart conditions. Reasoning against the prisms, since this is a judgement call and the card correctly says so:

• Measured business pull: none. Nothing is broken, no runtime behaviour differs, and the literal form is fully contract-valid. The one real author who hit it (the showcase's f_time) wrote the literal and shipped.
• Startup scope discipline: 13 new exported builders are a permanent public-API obligation, taken on with zero measured pull. defer beats declare-and-maintain here.
• AI-agent error-resistance — the axis that argues for it, and why it is weaker than it looks: an AI author reaching for Field.time(...) gets a typecheck failure, which is loud. The silent-drift shape the platform actually fears is absent here; the cost is discoverability, not correctness.

Restart conditions (any one re-opens this for grading):

1. an AI- or human-authored app is measured getting one of the 13 literal forms wrong in a way the type system does not catch — that converts this from ergonomics to error-resistance and it goes to the queue;
2. an authoring/docs page has to explain the two-and-one temporal split to readers — the asymmetry becoming user-facing prose is the signal it should be fixed instead of documented;
3. opportunistic: any PR already editing the Field builder object in packages/spec/src/data/field.zod.ts — closing the gap there is a cheap declared rider, not a separate card. Spec seat: worth a "check before dispatch" line in the seat post against that one file.

One measurement to add, found while re-verifying anchors on origin/main @ 1eb28a1 — it strengthens the card and was not in it: the spec's own prose already names the builder that does not exist —

packages/spec/src/contracts/data-driver.ts:234   // `Field.datetime` / `Field.time` value is physically stored on its
packages/spec/src/contracts/data-driver.ts:256   //  for a `Field.time` (#3994), a dialect-spelled datetime literal
packages/spec/src/data/calendar-day.ts:83        //  a `Field.time` is not an instant (#2004), so

Three comments in packages/spec refer to Field.time as an existing thing. That makes time the strongest single member of the 13 and the obvious minimal move if restart condition 3 fires: add Field.time alone, and the prose stops lying, with no judgement owed about the other 12.

---

Generated by Claude Code