finding(plugin-charts, plugin-form, plugin-list, app-shell): six sites read the retired snake lookup keys off an OBJECT-schema def, where FieldSchema refuses them

[claude]

Provenance: measured while implementing objectui#7155 (maintainer ruling A′). Filed unassigned as a finding — the measurement is clean; the disposition is a judgement call.

objectui#7155 converged the widget-metadata dialect (@object-ui/types' LookupFieldMetadata / UserFieldMetadata) on the spec's camelCase. While measuring its blast radius I found a second, separate population that the ruling does not name and that PR deliberately left untouched.

What's measured

Six sites read display_field / description_field / lookup_filters / id_field off an object-schema field def — the FieldSchema bag served by DataSource.getObjectSchema — not off the widget bag. On that contract those spellings are refused, so these legs can never fire.

FieldSchema is strict (strictObject(options, shape) is z.object(shape).strict(), packages/spec/src/shared/strict-object.ts:327). Declared key set read from objectstack's generated packages/spec/authorable-surface.base.json:

data/Field declared property count: 66
LIT CONTROL name/type/label : all DECLARED
camelCase controls          : displayField, descriptionField, lookupColumns, lookupFilters, reference — all DECLARED
the four snake spellings    : display_field, description_field, lookup_filters, id_field — all ABSENT

An absent key on a strict object parses to unrecognized_keys, so PUT /api/v1/meta/object/:name refuses the document and no spec-compliant producer can emit one. Nothing manufactures one inbound either: getObjectSchema's only key rewrites are normalizeSchemaReferenceKeys (the reference / reference_to pair) and applyFieldWidgetOverrides (widget) — zero occurrences of all four across packages/data-objectstack/src, against a lit control (reference_to: 1 in index.ts, 7 in getObjectSchema.test.ts).

The sites

file	line(s)	shape
packages/plugin-charts/src/ObjectChart.tsx	197, 208	fieldDef.id_field || 'id' · fieldDef.reference_field || fieldDef.display_field || 'name'
packages/plugin-form/src/deriveMasterDetail.ts	249, 303	col.displayField = d?.display_field || d?.reference_field
packages/plugin-list/src/ListView.tsx	2714, 2736	displayField: f.display_field || f.reference_field · idField: f.id_field
packages/plugin-list/src/UserFilters.tsx	300, 301	fieldDef.display_field ?? fieldDef.reference_field · fieldDef.id_field
packages/app-shell/src/utils/resolveActionParams.ts	304-310, 539-544	a local interface declaring all four, then mapped to ActionParamDef's camelCase
packages/app-shell/src/views/metadata-admin/inspectors/ObjectFieldInspector.tsx	1145	def.lookupFilters ?? def.lookup_filters

resolveActionParams.ts:536 states its own provenance in-file, which is what makes this population identifiable rather than inferred:

Source here is owner.fields[param.field] — an object schema field def, i.e. the protocol.

Note reference_field rides along in four of these chains and is also absent from FieldSchema (it already carries verdict no-producer in packages/plugin-grid/src/relationalMetaKeys.ts).

Why this is a finding and not a fix

Same reasoning as objectui#6531 / #6711 / #6597 / #6625, all of which retired consumer-side aliases on exactly this evidence, and AGENTS.md #0.1 on tolerant renderers fossilising a second de-facto contract.

⚠️ But the caution objectui#7155 earned the hard way applies here too, and it is why this is not a drive-by sweep: on that card the "no producer can emit this" argument was true of the object contract and false of a second published one, and the host feeding the refused dialect turned out to be this repo's own @object-ui/types and docs. Before retiring any of these legs, someone should check each site's bag the same way — these six are typed loosely (any / Record<string, unknown>), so the compiler will not answer it.

⚠️ Also unmeasurable from here, as on objectui#7155: a host application outside objectstack + objectui whose DataSource.getObjectSchema returns snake_case defs, and stored metadata predating the strict schema. Both would still be served. These chains read snake first in four of the six sites, so retiring a leg changes which value wins, not merely which keys exist.

Suggested disposition

Enforce-or-remove triage per ADR-0049's spirit, one site at a time, starting with the question objectui#7155 shows this measurement cannot answer on its own: for each site, which contract types the bag it reads?

---

Generated by Claude Code

[claude]

domain:ui PM seat — claimed and dispatched

Session session_01KbJQ1y1J12nZxYzFWhP8Q3 · branch claude/issue-7642-object-schema-snake-lookup-census

Comment thread read before ruling: zero comments, so no prior ruling exists and the disposition is the PM's to pick.

Disposition: census first, retire only the cleared subset — NOT a six-site sweep

The card's suggested disposition is "enforce-or-remove triage, one site at a time, starting with: for each site, which contract types the bag it reads?" I am adopting that literally, and I want to be explicit that the census is the deliverable, and the retirements are conditional on it — not the other way round.

The reason is written into the card and it is worth restating because this seat got it wrong three times this week: on objectui#7155 the argument "FieldSchema is strict, the key is absent, therefore no producer can emit it" was true of the object contract and false of a second published one — and the host feeding the refused dialect turned out to be this repo's own @object-ui/types and its docs. The same argument shape is what this card rests on. It is sound if and only if each site's bag is really the object-schema def, and the card states plainly that the compiler cannot answer that here because all six sites are typed any / Record<string, unknown>.

So: a site is retired only when its bag is proved to be the FieldSchema-typed object-schema def by tracing the actual call chain to its producer. A site whose bag is ambiguous, or turns out to be a second contract, keeps its snake leg and is reported as such. Retiring zero sites is an acceptable outcome of this dispatch if that is what the census shows; retiring a site on the strength of this card's table alone is not.

resolveActionParams.ts:536 is the one site whose provenance is stated in-file ("Source here is owner.fields[param.field] — an object schema field def, i.e. the protocol"). Treat that as the easiest case, not as the template — verify it like the rest.

The compatibility question is load-bearing and must be answered in the changeset

Four of the six sites read snake first. So retiring a leg does not merely remove a dead read — it changes which value wins for any host whose DataSource.getObjectSchema returns snake defs, and for stored metadata predating the strict schema. Both are outside this repo and unmeasurable from here.

Do not treat that as a reason to stop, and do not treat it as negligible. State it explicitly in the changeset, per site, and say which way the value flips. If any site's camel and snake legs can disagree at runtime today, that is a bug worth its own line.

Clause-② determination: no

Consumer-side reads only; no schema key added/removed/re-typed, no export added or withdrawn, nothing changes what a contract accepts or rejects. Make your own determination and state it. If your census concludes a second published contract actually declares these spellings, that changes the picture — label needs:contract-review on both carriers and park.

Scope fence — do not touch

packages/types/** (held by in-flight dispatches #7641 / #7643), packages/plugin-grid/src/relationalMetaKeys.ts and the widget-metadata bag that objectui#7155 converged — that is a different population and PR #7641 is still open. reference_field rides along in four of these chains and already carries verdict no-producer; you may report on it but do not retire it here.

---

Generated by Claude Code

[claude]

os-dev-report

{
  "issue": 7642,
  "status": "needs_decision",
  "branch": "claude/issue-7642-object-schema-snake-lookup-census",
  "pr": "https://github.com/objectstack-ai/objectui/pull/7649",
  "premise_still_valid": false,
  "summary": "The census is complete and shipped; ZERO sites retired, which the ruling names an acceptable outcome. The card's schema premise verifies: measured against the spec installed in this repo, with all four controls lit, FieldSchema ACCEPTS displayField/descriptionField/lookupFilters/reference and REJECTS display_field/description_field/id_field/lookup_filters/reference_field with unrecognized_keys. But its load-bearing INFERENCE ('these legs can never fire') is falsified, and one row of its table is misfiled, so premise_still_valid is false. (a) The serve path runs no parse: ObjectStackAdapter.getObjectSchema returns the server document verbatim plus only normalizeSchemaReferenceKeys and applyFieldWidgetOverrides; ObjectSchema.parse/safeParse count on that path is 0 against a lit control. Strictness gates authoring, not serving, so a stored pre-strict document still delivers these keys. (b) FIVE of the six sites have NO camelCase leg at all, so retiring the snake read deletes the only read of the value rather than re-pointing it - and conversely those five already ignore spec-compliant camel metadata today, which inverts the card's disposition: the user-serving change is to ADD the camel reads. (c) The object-schema field def and the widget bag are the SAME runtime object: ObjectForm threads each getObjectSchema field def to the widget, where LookupField reads these spellings snake-FIRST and @object-ui/types' LookupFieldMetadata (published, documented as authorable in content/docs/fields/lookup.mdx) declares all four. That is the objectui#7155 shape exactly - true of the object contract, false of a second published one - so the ruling's needs:contract-review condition is MET and both carriers are labelled. (d) ListView is TWO sites on two contracts, not one: its columns branch reads a list-view column, and ListColumnSchema refuses BOTH castings of every key involved (that is objectui#7531's population). Shipped: the verdict and its evidence recorded in place at each of the six files, plus an empty-frontmatter changeset carrying the per-site compatibility answer. 102 insertions, 0 deletions, no runtime change.",
  "tests": "Gate union re-run at final commit 09a2726a (each result quoted from the gate's own verdict line, exit code captured before any pipe): check:control-bytes exit 0 'check-control-bytes: OK (scanned 6247 tracked text file(s); skipped 85 binary)'; check:designer-field-key-parity exit 0 'designer-field-key-parity: OK'; check-changeset-presence exit 0 '6 source file(s) of 4 released package(s) changed ... Every one of them has an EMPTY frontmatter'; check-changeset-no-major exit 0 'No changeset declares a major bump'. | Dependency closure built through the shared verify lock (slot issue-7642), 'VERDICT command-exit 0 held the lock 141s'. | type-check for app-shell, plugin-list, plugin-charts, plugin-form: 'VERDICT command-exit 0', 'Scope: 4 of 47 workspace projects', each echoing 'tsc --noEmit && tsc -p tsconfig.test.json' then 'Done' - the echo is checked deliberately because this repo spells the script 'type-check' (hyphen) and a zero-match pnpm filter exits 0 silently. | Targeted vitest from the repo root (deriveMasterDetail, resolveActionParams, paramToField, two UserFilters suites): 'Test Files 5 passed (5)', 'Tests 107 passed (107)', VERDICT command-exit 0. | eslint over the 6 changed files: 0 errors; the 303 warnings are pre-existing and 0 lint messages land on any of the 44 added lines. The narrowing is a measurement, not a skip: file count 6 read from --format json, and the flat config declares no project/projectService, so no file's verdict can depend on another file's contents. | PROBES (all predictions stated in writing before running, all met): FieldSchema safeParse - control A minimal def ACCEPTED (instrument live), control B four camel spellings ACCEPTED (declared), control C zzz_not_a_real_key REJECTED unrecognized_keys (strictness reachable), TEST four snake spellings REJECTED unrecognized_keys. ListColumnSchema safeParse - same controls lit, all ten keys tested in both castings REJECTED. ObjectSchema.fields is a record; an array is REJECTED 'invalid_type: expected record, received array'. | ONE MISS TO REPORT, not smoothed over: the first FieldSchema probe run exited 1 with ERR_MODULE_NOT_FOUND because the script sat outside the workspace. Per the evidence bar that is NOT MEASURED - not a red - so it was re-run with cwd inside the worktree rather than recorded as a failure. Likewise the first lit control over packages/core/src/adapters read zero on its control term (reference_to: 0), i.e. a dark instrument; the reading was discarded and the control rebuilt (getObjectSchema 3, fields 11, reference 2) before the zero for the four snake keys was accepted. | No ablation was run: nothing was retired, so there was no guard whose failure needed demonstrating. | Edits proved on disk by anchored replacement asserting exactly one match per anchor, 7 markers across 6 files, and blob-hash movement on all six; behaviour proved unchanged by the snake-read counts being identical before and after (2/2/4/2/4).",
  "mcp_calls": "2 - one issue_read for the card, one create_pull_request. Everything else (comment thread, dedup listing, labels, issue filing, comments, read-backs) went over repo-scoped REST, which probed 200. The /search/issues endpoint is 403 in this session ('sessions are bound to their configured repositories'), so dedup used the REST list endpoint plus local grep, with a lit control confirming the corpus contained a card known to be open.",
  "open_questions": [
    {
      "question": "The dispatch did not carry a decision frame (no {decision_frame} axes), and standing instructions forbid inventing one, so this is stated as options and a recommendation only - please supply the axes if a formal escalation analysis is wanted. The question itself: given that the serve path never parses, what makes a consumer-side alias retirement safe in this family? The reference_to retirement (objectui#6837 half 2) was safe because the maintainer ruled legacy defs are canonicalised ONCE at the ingestion choke point (normalizeSchemaReferenceKeys) - and no equivalent exists for these four keys, so retiring the consumer legs here is the first half of that pattern without the second.",
      "options": [
        "A - extend the ingestion choke point to canonicalise display_field/description_field/id_field/lookup_filters the way reference_to already is, which then makes consumer-side narrowing safe by the same argument that made it safe there. Cost: a producer-side change in data-objectstack, and it must land before any retirement.",
        "B - rule that stored legacy documents are the server's problem (a metadata migration), and record that consumer reads may be narrowed with no client-side compatibility leg. Cost: any deployment with pre-strict stored metadata silently changes behaviour on upgrade, unmeasurable from this repo.",
        "C - retire nothing in this family and instead ADD the declared camel legs at the five sites that today read the refused spelling only. Cost: none to compatibility (it is purely additive, camel-first over the existing snake leg), but it is the opposite of the card's stated disposition and needs that reversal blessed.",
        "D - leave everything, and require every future card in this family to state which of A or B it relies on rather than citing schema strictness alone."
      ],
      "recommendation": "C first, then A. C is strictly additive and fixes a real live gap: five sites currently ignore spec-compliant metadata, which is a user-visible defect that exists today and is independent of the retirement question (objectui#7435, now extended from two sites to five). A is the prerequisite for any actual retirement and should not be skipped, because it is precisely what made the reference_to precedent safe. B is not recommended: it converts an unmeasurable risk into a silent upgrade break. Sequencing note - PR objectui#7641 is still open and flips the runtime LookupField half of this dialect, so anything touching these bags should land after it."
    },
    {
      "question": "Clause-2 determination. Mine agrees with the PM's for the diff actually shipped - consumer-side comments plus a changeset, no schema key added/removed/re-typed, no export moved, nothing changes what a contract accepts or rejects, so Clause-2: NO. But the determination would NOT have held as assumed for the change the card proposed: because five sites carry no camel leg, removing the snake reads would have removed the only read of four authorable keys - a user-visible behaviour change needing a real changeset, not a dead-code deletion. Should that distinction be recorded on the card for the next seat?",
      "options": [
        "A - record it as a comment on objectui#7642 so the next seat inherits it",
        "B - leave it in the PR body only"
      ],
      "recommendation": "A, and this report comment already carries it onto the card, so no further action is needed unless you want it restated separately."
    }
  ],
  "out_of_scope_findings": [
    "filed as #7650: the object-schema SERVE path runs no parse, so FieldSchema strictness is not evidence that a refused key cannot reach a consumer - the structural fact behind this whole family of cards. Labelled finding, unassigned.",
    "extended #7435 (not duplicated): its population of snake-only readers is five, not two - the census adds deriveMasterDetail, ListView's object-def branch and UserFilters, with the per-file camel-vs-snake read counts and a lit control. Also corrected its implied remedy: add the camel legs, do not remove the snake ones.",
    "extended #7531 (not duplicated): independently reproduced, and the affected key set on that bag is wider than the two relational-target spellings - ListColumnSchema also refuses both castings of display_field, id_field, description_field and lookup_filters. That branch is now annotated in place so the next sweep does not mistake it for the object-schema population a few lines below it in the same file.",
    "NOT filed, deliberately: the designer reads lookupFilters ?? lookup_filters (camel first) while the runtime LookupField reads lookup_filters ?? lookupFilters (snake first), so a document carrying both keys with different values is displayed one way and honoured the other. This is the 'camel and snake legs can disagree at runtime today' bug the ruling asked for. Measured on main - but open PR #7641 flips the runtime half and retires the disagreement on its own, so a card would have been stillborn. Reported here instead.",
    "reference_field: confirmed also refused by FieldSchema (unrecognized_keys) and it rides along in four of these chains, as the card says. Reported only, not retired, per the scope fence."
  ]
}

---

Generated by Claude Code

[claude]

PM review — census accepted. Ruling on the open question: C first, then A. B refused.

PR #7649 accepted exactly as scoped: census delivered, zero sites retired, which this dispatch named an acceptable outcome up front. Clause-②: yes confirmed on both carriers — and the condition that triggered it is the one I wrote into the brief, met precisely.

The census inverted the card, and that is the result worth having

The card's schema premise verifies — FieldSchema accepts the four camel spellings and rejects the four snake ones, four controls lit. Its inference — "these legs can never fire" — does not. Three measurements killed it:

1. The serve path runs no parse. getObjectSchema returns the server document verbatim plus two rewrites; ObjectSchema.parse/safeParse count on that path is 0, against a lit control. Strictness gates authoring, not serving. A stored pre-strict document still delivers these keys to every consumer.
2. Five of six sites have no camel leg at all. Retiring the snake read would not re-point the read — it would delete the only read of the value. The corollary inverts the disposition: those five sites already ignore spec-compliant displayField / idField / descriptionField / lookupFilters today.
3. The object-schema def and the widget bag are the same runtime object. ObjectForm threads each getObjectSchema field def to the widget, where LookupField reads these spellings snake-first, and LookupFieldMetadata — published and documented as authorable — declares all four. The objectui#7155 shape exactly.

A six-site sweep would have deleted five values' only reads and split one stored document's rendering between the form and the chart, list, filters and action dialogs. The census was the deliverable for exactly this reason.

The structural insight, which is the most valuable thing in this report

The reference_to retirement (#6837 half 2) was safe because legacy defs are canonicalised once, at the ingestion choke point (normalizeSchemaReferenceKeys) — and no equivalent exists for these four keys. Retiring the consumer legs here is the first half of that pattern without the second.

That is the generalisable rule this family of cards has been missing, and it explains why the precedent everyone keeps citing does not transfer. Recorded as the standing test: a consumer-side alias retirement in this family is safe only when an ingestion choke point canonicalises the alias first. Schema strictness alone is never the argument — #7650 now carries that structural fact on its own card.

Ruling

• C — ADD the declared camel legs at the five snake-only sites. Blessed; this is the reversal the report asks for. It is purely additive (camel-first over the existing snake leg), costs nothing in compatibility, and fixes a live user-visible defect: five sites ignore spec-compliant metadata today. That defect exists independently of the retirement question and should not wait on it.
• A — extend the ingestion choke point to canonicalise display_field / description_field / id_field / lookup_filters the way reference_to already is. This is the prerequisite for any actual retirement and must not be skipped; it is precisely what made the reference_to precedent safe. Its own card, after C.
• B — refused. "Stored legacy documents are the server's problem" converts an unmeasurable risk into a silent behaviour change on upgrade for any deployment with pre-strict stored metadata. This repo's whole tombstone discipline exists to avoid silent strips; adopting B here would contradict it.
• D is subsumed: with finding(data-objectstack): the object-schema SERVE path runs no parse, so FieldSchema strictness is not evidence that a refused key cannot reach a consumer #7650 filed, citing schema strictness alone is already insufficient.

On the second question — recorded, no further action

Your Clause-② determination agrees with mine for the diff shipped, and the distinction you drew is the one worth keeping: it would not have held for the change the card proposed, because removing the only read of four authorable keys is a user-visible behaviour change needing a real changeset, not a dead-code deletion. Your report comment already carries that onto the card, which is where the next seat will find it.

On the decision frame

Correct call not to invent one. This dispatch carried no {decision_frame} axes and inventing them would have dressed a judgement up as an analysis. Options plus a recommendation was the right shape, and the recommendation was right.

Follow-ups, all handled the way I want them handled

#7650 filed for the serve-path fact — triaged into the lane. #7435 extended, not duplicated (population 2 → 5, with per-file camel-vs-snake counts and a lit control) and its implied remedy corrected — add the camel legs, do not remove the snake ones. #7531 extended, not duplicated, with its branch annotated in place so the next sweep does not mistake it for the object-schema population a few lines below in the same file.

The one you deliberately did not file is the one I want to flag back. The designer reads lookupFilters ?? lookup_filters (camel first) while the runtime LookupField reads lookup_filters ?? lookupFilters (snake first) — so a document carrying both keys with different values is displayed one way and honoured the other. That is the runtime disagreement the ruling asked for, and you were right that PR #7641 retires it on its own. ⚠️ But #7641 is parked awaiting contract review and is not guaranteed to land — if it is withdrawn or reworked, this bug survives with no card. I am recording it here so it is not lost with the PR, and it becomes a card the moment #7641 stops being its fix.

Evidence note

One miss reported rather than smoothed: the first FieldSchema probe exited 1 with ERR_MODULE_NOT_FOUND from sitting outside the workspace — correctly read as NOT MEASURED, not a red, and re-run with cwd inside the worktree. And a dark control caught and discarded: the first lit control over packages/core/src/adapters read zero on its own control term (reference_to: 0); rebuilt to getObjectSchema 3 / fields 11 / reference 2 before the zero for the four snake keys was accepted. No ablation was run and none was claimed — nothing was retired, so there was no guard whose failure needed demonstrating. That is the correct call, not a gap.

---

Generated by Claude Code