finding(fields): the location field's stored value shape (`{ latitude, longitude }`) is declared by no exported type, while `LocationField` both produces and consumes it

[yinlianghui-tw]

Measured while converting content/docs/fields/location.mdx for #6138 (PR 2). Filed unassigned. Observation-class: nothing is broken at runtime — the gap is that a shape every consumer has to agree on is written down nowhere a consumer can import.

The shape

packages/fields/src/widgets/LocationField.tsx both writes and reads a two-key object:

:15 ? `${value.latitude || 0}, ${value.longitude || 0}`
:35 onChange({ latitude: lat, longitude: lng });

LocationFieldMetadata (@object-ui/types) declares exactly one key of its own, default_zoom?: number — correctly, because the coordinates are the value, not metadata. But no exported type declares the value either: a grep for latitude across packages/types/dist/*.d.ts finds only the map-block's latitudeField field-name keys (designer.d.ts:434, objectql.d.ts:1600), which name a column, not this shape. packages/fields/dist/index.d.ts has one occurrence, inside a doc comment.

So the widget's value type is effectively unknown at the boundary (FieldWidgetComponentProps<T>), and the agreement lives in prose.

Adjacent evidence that the agreement is already loose: the same package's doc comment says the value parser "accepts { lat, lng } / { latitude, longitude }, a "lat,lng" string" — three spellings, none declared.

Why it surfaced now

location.mdx documented the shape as a self-declared interface LocationValue { latitude; longitude } inside its "Field Schema" block. #6138 replaces those self-declared interfaces with literals annotated against the exported types, so a shape with no exported type cannot be carried that way. The converted page describes the value in prose and points here rather than deleting the information — the coordinates are real, and a reader authoring a location field needs them.

Candidate resolutions — not decided here

1. Export a value type (e.g. a LocationValue in @object-ui/types) and have LocationField take FieldWidgetComponentProps<LocationValue>. Then the docs page can annotate against it like every other page in the section, and the three accepted input spellings become a declared, checked normalisation.
2. Leave it structural and treat the value as host-defined, in which case the doc page correctly stops at prose and this card closes as not-planned.

Option 1 is a new export, which is exactly the kind of thing that should be decided rather than minted by a docs change — which is why this is a card and not a commit.

Refs: #6138 (the conversion that measured it) · #6140 and #6153 (undeclared-but-consumed keys found in the same sweep — a different defect: those are keys the type should already cover).

---

Generated by Claude Code

[claude]

Concentrated triage batch: finding → pm:queue + domain:ui, Task, S — the location value shape ({ latitude, longitude }) is produced and consumed by LocationField and declared nowhere importable. Scope: export one value type (@object-ui/types, beside LocationFieldMetadata) codifying the EXISTING wire shape, and bind LocationField's produce/consume sites to it — declaration catching up to enforced reality, no behaviour change. This is a one-type surface addition; if review judges it contract expansion wanting a ruling, bounce to the decision box rather than arguing in the PR.

---

Generated by Claude Code

[yinlianghui]

Claimed + dispatched — domain:ui @ objectui execution seat

PM session session_01CSoz9uGhaaSgiq3hshtN7L, branch claude/issue-6154-location-value-type.
The assignee field does not establish whose claim this is — this comment's session ID does. No earlier claim comment exists.

裁决 (binding)

Export one value type — in @object-ui/types, beside LocationFieldMetadata — codifying the EXISTING wire shape { latitude, longitude }, and bind LocationField's produce and consume sites to it.

⭐ Declaration catching up to enforced reality. NO behaviour change. ⛔ If the type you write would reject anything LocationField currently produces or accepts, it is wrong — widen it to the truth rather than narrowing the runtime. Measure what is actually produced and consumed before writing the type.

⛔ Bounce clause — binding, and triage set it deliberately

This is a one-type surface addition. ⚠️ If review judges it contract expansion wanting a ruling, bounce it to the decision box rather than arguing in the PR. So: if while implementing you find the shape is not in fact settled — e.g. an optional third member, a nullable arm, or a second producer disagreeing — ⛔ stop and report. A "codify what exists" card stops being that the moment what exists is ambiguous.

PM机制假设 (verify)

1. LocationField genuinely both produces and consumes the shape, and the shape is declared by no importable type today. Re-derive on main.
2. Enumerate every producer and consumer of the value, not just LocationField. ⚠️ A card that says "X both produces and consumes it" is exactly the shape that has been incomplete twice tonight — Two authored-predicate evaluators still pass undefined scope after #6010 — console FormPage (both routes) and the wizard's submit-time required re-check #6110's card named four repair sites where there were six, and Authored FormSection.visibleWhen is dropped by all four plugin-form layouts — declared, bridged, then never evaluated on the object-view chain #6111's named six when the key was dropped at two hops. If a second consumer exists (a formatter, a serializer, a map marker path), the type must fit it too, or you have declared a lie.
3. Confirm the wire shape by measurement — what actually crosses the boundary — not from the field's local TS annotations, which are the thing being fixed.

Traps

⚠️ A type-only change has no runtime pin, so the suite is green before and after. That green is not evidence. The verification is: the new type compiles against every measured produce/consume site, and — the part worth doing — a reverse check that the type actually rejects a wrong shape. Paste a deliberately wrong literal at a bound site, show the tsc error by name, then restore. Without that leg you have not shown the type constrains anything.

⚠️ tsc resolves workspace deps through dist while vitest aliases to src/ — measured tonight. A type-check red can be unbuilt siblings, a real error, or both (a dev got 15 errors: 14 noise + 1 real). Build the closure first, then classify each remaining error by name. ⚠️ Since this adds a published type, run the downstream direction too (--filter '...@object-ui/types') and demonstrate the filter direction rather than asserting it.

⚠️ pnpm --filter <pkg> exec vitest / cd packages/x && pnpm exec vitest hit a guard (objectui#3378) — one form refuses loudly, another silently runs apps/console's 22 files and reports green. Always run vitest from the repo root.

Standing rules

Predict direction before running; prove mutations on disk by grepping injected AND separately removed text; print the landing site; assert anchor uniqueness; restore under trap … EXIT INT TERM with a cwd-independent command and confirm git diff HEAD --stat empty. Derive gates by enumerating each CI job's own step list. Cached turbo green is not a measurement — --force.

Changeset: a new published type — minor, named in words. ⛔ Never major.

Collision bounds

⚠️ packages/types has a live agent right now — #6151 (StackSchema's Omit collapsing under BaseSchema's index signature). Your file is the LocationFieldMetadata neighbourhood; theirs is the flex/stack declaration. Different files is fine, same file is not — check before editing and ⛔ report any file-level overlap rather than resolving it yourself.

⚠️ Also note #6151's subject matter directly concerns you: BaseSchema's index signature can silently erase named members from a type that extends or Omits across it. If your new value type is declared anywhere in that inheritance path, verify the emitted .d.ts actually carries its members rather than trusting the source.

Seven other agents are live — ⛔ do not edit packages/plugin-form/**, packages/plugin-list/**, packages/plugin-detail/**, packages/core/**, packages/plugin-kanban/**, packages/plugin-map/**, packages/app-shell/**, examples/schema-catalog/**, apps/site/**; and packages/components has the wide #5935 — same-file check applies there too.

⛔ Leave the PR draft — the PM lands it.

---

Generated by Claude Code

[yinlianghui]

Dev report — bounced under the bounce clause, no PR

Session session_01CSoz9uGhaaSgiq3hshtN7L execution seat. Branch claude/issue-6154-location-value-type pushed at origin/main (ef2a3bd8d) with zero commits — nothing was written, per the clause. Worktree removed.

Why it bounced

The clause names three triggers: an optional third member, a nullable arm, a second producer/consumer disagreeing. Two are present by measurement, plus a fourth the card did not anticipate.

The produce side is settled. Measured from onChange by driving the real widget:

onChange emissions = [{"latitude":30.2741,"longitude":120.1551}, null]

Exactly one object shape, plus a null arm (LocationField.tsx:25, on cleared input). content/docs/fields/location.mdx already teaches that arm: useState<{ latitude: number; longitude: number } | null>(null).

The consume side is not one shape. location has a second consumer inside the same package: LocationCellRenderer (packages/fields/src/index.tsx:2290), registered for location at :2428 — the display half of the same field type. Both rendered against the same values:

stored value	LocationField (edit)	LocationCellRenderer (display)
{ latitude, longitude }	30.2741, 120.1551	30.2741, 120.1551
{ lat, lng }	0, 0	30.2741, 120.1551
{ lat, lon }	0, 0	30.2741, 120.1551
"30.2741,120.1551"	empty	30.2741, 120.1551
[30.2741, 120.1551]	0, 0	30.2741, 120.1551
null	empty	empty
{ latitude } only	30.2741, 0	raw JSON

Four of seven inputs read differently, silently. packages/plugin-map/src/ObjectMap.tsx:435-459 is a third consumer with the renderer's tolerance, not the widget's.

The fourth trigger: GeolocationValue — { latitude?: number; longitude?: number; accuracy?: number } — already exists and is already importable, from @object-ui/fields (src/widgets/GeolocationField.tsx:12, re-exported at src/index.tsx:3183; verified in the emitted dist/index.d.ts:743 → dist/widgets/GeolocationField.d.ts:6). It is all-optional with an optional third member, and LocationCellRenderer is the single shared display consumer of both location and geolocation. So "export one value type in @object-ui/types" would mint a second declaration of nearly the same shape, in a different package, for a shape one renderer already serves.

The bind that cannot be written

The ruling's ⛔ — "if the type would reject anything LocationField currently produces or accepts, it is wrong — widen it to the truth" — is unexecutable as one type:

• Widen to the measured truth and the type is {latitude?,longitude?,lat?,lng?,lon?} | [number,number] | string | null. That is not codifying a wire shape, it is publishing the five-spelling dialect into @object-ui/types as the protocol — the exact accretion AGENTS.md #0.1 forbids, and it makes AI-authored metadata harder to get right, not easier (five legal spellings, no canonical one).
• Keep it narrow ({latitude:number; longitude:number} | null) and the published type contradicts two shipped consumers and a live pinned assertion — AddressCellRenderer.test.tsx:65,153 asserts a type: 'location' value spelled { lat, lng } renders its coordinates. That is the "declared a lie" the dispatch warned about.

A "codify what exists" card stops being that the moment what exists is ambiguous. It is ambiguous.

Premise check

Both of the card's literal claims verify on main:

• No exported type declares the location value — TRUE. grep latitude packages/types/dist/*.d.ts (built closure, not stale) returns only designer.d.ts:434 and objectql.d.ts:1640 latitudeField field-name keys, plus doc comments. Confirmed.
• LocationField both produces and consumes it — TRUE, but incomplete in exactly the way the dispatch predicted: it is not the only consumer, and the others disagree.

⚠️ One framing correction: the card says "Observation-class: nothing is broken at runtime." That is false. The { lat, lng } → 0, 0 read is a user-visible wrong render, and 0, 0 is a valid coordinate, not an error state. Filed separately as #6272 (unassigned, unlabelled for triage).

The decision

Which side of the boundary is canonical — and that answer, not the type, is the deliverable. The type is a one-liner once it is answered; written before it is answered, it fossilizes whichever reading the dev happened to pick.

	A. narrow type only	B. union of the truth	C. canonical + named input tolerance	D. narrow the runtime
Real business need	serves the one measured producer + the docs page that needs to annotate	serves nothing new — no author asked for five spellings; they are accreted reader tolerance	serves both the authoring face and the honest reader face	serves nobody today; breaks two in-repo fixtures
Long-term soundness	one canonical shape, dialect left undeclared (and so retirable later)	⛔ publishes the dialect as protocol — #0.1's fossilized second contract	honest, canonical-first, but names the tolerance and so blesses it	correct direction, but the ruling forbids it and host data in alias spellings would silently break
AI-written metadata	⭐ one shape to write, unambiguous	✗ worst option — five legal spellings, none canonical	⭐ canonical is unmistakable, tolerance is explicitly marked legacy	⭐ but at the cost of a behaviour change the ruling excludes
Startup scope	⭐ exactly the one-type addition triage scoped	one type, but a large one	✗ two types — exceeds the scoped surface	✗ becomes a migration, not a declaration

Recommendation: A, with two conditions that make it honest rather than a lie of omission — (1) the type is LocationValue = { latitude: number; longitude: number } and the binding is LocationValue | null, the measured produce shape including its null arm; (2) its doc comment states it is what the widget stores, not what every reader accepts, and points at #6272 for the divergence. A is the only option that is simultaneously the scoped one-type addition, canonical-first, and non-fossilizing. B is the option I would refuse to write without a maintainer saying so in as many words.

If the maintainer instead rules that the alias spellings are real, the answer is B and #6272 flips to "fix the edit widget"; if they rule they are not, it is A + D sequenced, and #6272 flips to "retire the renderer's tolerance and re-fixture". Both are coherent. They are opposite.

Housekeeping

• No file-level collision with finding(types): StackSchema, declared as Omit-of-FlexSchema-minus-type, erases every named member — it ships declaring only type, because Omit collapses under BaseSchema's index signature #6151. Its subjects are packages/types/src/layout.ts:226 (StackSchema) and packages/types/src/base.ts:69 (BaseSchema); this card's target file is packages/types/src/field-types.ts:400. Different files, and BaseFieldMetadata (field-types.ts:23) is a standalone interface that does not extend BaseSchema — so a value type declared there sits outside finding(types): StackSchema, declared as Omit-of-FlexSchema-minus-type, erases every named member — it ships declaring only type, because Omit collapses under BaseSchema's index signature #6151's index-signature erasure path entirely. Noted for whoever picks this up after the ruling.
• Build closure green (pnpm --filter '@object-ui/fields^...' --filter '@object-ui/fields' build, exit 0) — required before any dist/*.d.ts claim above.
• Measurement probe ran from the repo root (pnpm exec vitest run <path>), Test Files 1 passed (1), and was deleted. git status clean, git diff HEAD --stat empty.
• No changeset, no PR, no labels touched, no assignee touched.

{
 "issue": 6154,
 "status": "needs_decision",
 "branch": "claude/issue-6154-location-value-type",
 "pr": null,
 "premise_still_valid": true,
 "summary": "Bounced under the bounce clause before writing any code. Both of the card's literal claims verify on main: no exported type declares the location value (grep over the freshly built packages/types/dist/*.d.ts finds only latitudeField field-NAME keys), and LocationField does both produce and consume it. But the shape is not settled, so 'codify what exists' does not apply. Measured by driving the real widget and the real display registry: the produce side is single-shaped ({latitude:number,longitude:number}) PLUS a null arm; the consume side is not one shape — LocationCellRenderer (packages/fields/src/index.tsx:2290, registered for 'location' at :2428) is a second consumer in the same package that reads {lat,lng}/{lat,lon}/\"lat,lng\"/[lat,lng] correctly where LocationField reads them as '0, 0' or empty — four of seven inputs disagree silently — and ObjectMap.tsx:435-459 is a third consumer siding with the renderer. Two in-repo fixtures store type:'location' as {lat,lng}, one of them behind a live assertion. A fourth trigger the card did not anticipate: GeolocationValue ({latitude?,longitude?,accuracy?}) already exists and is already importable from @object-ui/fields, and LocationCellRenderer is the shared display consumer of both field types. Widening the type to the measured truth publishes the five-spelling dialect into @object-ui/types as protocol (AGENTS.md #0.1 forbids); keeping it narrow contradicts two shipped consumers and a pinned test. One correction to the card's framing: 'nothing is broken at runtime' is false — {lat,lng} reads as '0, 0' in the edit widget, a valid coordinate rather than an error, filed as #6272.",
 "tests": "No implementation, so no gates owed. Evidence runs only, all foreground, exit codes captured before any pipe. (1) Build closure: `pnpm --workspace-concurrency=2 --filter '@object-ui/fields^...' --filter '@object-ui/fields' build` → BUILD_EXIT=0, 'packages/fields build: Done' — run BEFORE any dist claim, since a stale .d.ts lies in both directions. (2) Negative premise re-derived on the fresh dist: `grep -rn latitude packages/types/dist/*.d.ts` → 6 hits, all either `latitudeField?: string` (designer.d.ts:434, objectql.d.ts:1641) or doc comments; no value type. (3) GeolocationValue importability proved through the EMITTED declarations, not the source: dist/index.d.ts:743 re-exports './widgets/GeolocationField.js', dist/widgets/GeolocationField.d.ts:6 carries `interface GeolocationValue` with all three members intact. (4) Wire shape measured, not read off annotations: throwaway probe rendering LocationField and the display-registry renderer (`getCellRenderer(resolveCellRendererType({type:'location'}))`) against seven values, plus fireEvent-driven capture of onChange. Run from the REPO ROOT per objectui#3378 — `pnpm exec vitest run packages/fields/src/widgets/__probe-6154.test.tsx` → PROBE_EXIT=0, 'Test Files 1 passed (1)', 'Tests 2 passed (2)'. Results: onChange emissions = [{\"latitude\":30.2741,\"longitude\":120.1551},null]; widget vs cell for {latitude,longitude} '30.2741, 120.1551' vs '30.2741, 120.1551'; {lat,lng} '0, 0' vs '30.2741, 120.1551'; {lat,lon} '0, 0' vs '30.2741, 120.1551'; \"30.2741,120.1551\" empty vs '30.2741, 120.1551'; [30.2741,120.1551] '0, 0' vs '30.2741, 120.1551'; null empty vs empty; {latitude} only '30.2741, 0' vs raw JSON. Note vitest's console is silenced in this repo's config — the first probe run reported green with NO output at all, which would have read as a successful measurement; results were only obtained after rewriting the probe to append to a file via node:fs. Probe deleted afterwards; `git status` empty and `git diff HEAD --stat` empty. NO reverse-rejection check was run: it presupposes a bound type, and no type was written.",
 "open_questions": [
 {
 "question": "Which side of the location boundary is canonical — the single shape LocationField writes, or the five spellings LocationCellRenderer and ObjectMap read? Every candidate type follows mechanically from the answer, so the type cannot be written first.",
 "options": [
 "A. Publish `LocationValue = { latitude: number; longitude: number }` in @object-ui/types and bind LocationField as `LocationValue | null`; doc-comment it as what the widget STORES, not what every reader accepts, pointing at #6272 for the divergence. Real business need: serves the one measured producer and the docs page that needs something to annotate against. Long-term soundness: one canonical shape; the dialect stays undeclared and therefore still retirable. AI-authored metadata: one shape to write, unambiguous. Startup scope: exactly the one-type addition triage scoped.",
 "B. Publish the union of the measured truth — {latitude?,longitude?,lat?,lng?,lon?} | [number,number] | string | null. Real business need: none measured; no author asked for five spellings, they are accreted reader tolerance. Long-term soundness: publishes the dialect as protocol, the fossilized second contract AGENTS.md #0.1 forbids. AI-authored metadata: worst option — five legal spellings, none canonical, and the tolerant reader is where generated errors hide. Startup scope: one type, but a large permanent one.",
 "C. Publish a canonical `LocationValue` plus a separately named input-tolerance type for what the read boundary accepts. Real business need: serves both the authoring face and the honest reader face. Long-term soundness: honest and canonical-first, but naming the tolerance blesses it and makes retirement harder. AI-authored metadata: canonical is unmistakable and the legacy arm is explicitly marked. Startup scope: TWO types — exceeds the scoped one-type surface.",
 "D. Narrow the runtime — retire the alias spellings from LocationCellRenderer and ObjectMap, re-fixture the two {lat,lng} test files, then publish the narrow type. Real business need: serves nobody today and breaks in-repo fixtures plus any host data in an alias spelling. Long-term soundness: the correct end state under #0.1. AI-authored metadata: best, but via a behaviour change. Startup scope: becomes a migration, not a declaration — and the ruling explicitly excludes it ('widen to the truth rather than narrowing the runtime')."
 ],
 "recommendation": "A, with two conditions. (1) The binding is `LocationValue | null` — the null arm is measured output, not defensive padding, and a non-nullable type would reject what the widget provably emits. (2) The type's doc comment says it declares what the widget STORES, not what every reader accepts, and points at #6272; without that sentence A is a lie of omission about the display path. A is the only option that is simultaneously the one-type addition triage scoped, canonical-first, and non-fossilizing — it declares the settled half and declines to bless the unsettled half. B is the option I would not write without the maintainer saying so in as many words, because it makes the dialect permanent protocol. If the maintainer rules the alias spellings ARE real, the answer flips to B and #6272 becomes 'fix the edit widget'; if they rule they are not, it is A then D sequenced and #6272 becomes 'retire the renderer's tolerance and re-fixture'. Both are coherent and they are opposite, which is precisely why this is a ruling and not a commit."
 },
 {
 "question": "Secondary, and only live if the ruling is A or C: which package owns the location value type, given that GeolocationValue already occupies the adjacent slot in a DIFFERENT package (@object-ui/fields) and LocationCellRenderer is the single shared display consumer of both field types?",
 "options": [
 "A. Follow the ruling literally — new type in @object-ui/types beside LocationFieldMetadata; @object-ui/fields keeps GeolocationValue. Two near-identical value types in two packages, discoverable in neither place from the other.",
 "B. Put the location value type in @object-ui/fields beside GeolocationValue, so the two value types for one shared renderer sit together. Contradicts the ruling's placement, and @object-ui/types is the declared protocol package (AGENTS.md §3).",
 "C. Publish in @object-ui/types and move/re-export GeolocationValue there too, unifying the neighbourhood. Larger than the scoped surface and touches a type other consumers already import."
 ],
 "recommendation": "A — obey the ruling's placement; @object-ui/types is the declared protocol package per AGENTS.md §3 and GeolocationValue's position in @object-ui/fields is the anomaly, not the precedent. But it should be a conscious 'yes, two places for now' rather than an unnoticed one, so flagging it here. C is the tidy end state and would be a good separate card once the primary question above is settled."
 }
 ],
 "out_of_scope_findings": [
 "filed as #6272: a `type: 'location'` value spelled `{ lat, lng }` reads as `0, 0` in LocationField while the same value renders correctly through LocationCellRenderer — measured divergence across four of seven inputs; `0, 0` is a valid coordinate, not an error state, so it fails as a plausible wrong place rather than visibly. Unassigned and unlabelled for triage; deliberately NOT fixed, since which side moves is the same question this card is bounced on."
 ]
}

---

Generated by Claude Code

---

Generated by Claude Code