Repository navigation
finding(console): the object preview sample spells a lookup target reference_to, a second off-spec key its KNOWN_STALE reason does not record #6647
Description
Found while censusing relationship-target spellings for objectui#6528. Filed rather than folded in — different file, different defect.
apps/console/src/preview-samples.ts, the object sample:
{ name: 'account', label: 'Account', type: 'lookup', reference_to: 'account' },reference_to is refused by name. Measured against the installed @objectstack/spec 17.2.0, on an otherwise-green field:
ObjectSchema.safeParse({ name:'census_obj', label:'Census',
fields: { acct: { type:'lookup', label:'Account', reference_to:'crm_account' } } })
=> success:false, code = unrecognized_keys, path = fields.acct
"Unrecognized key(s) on this field: `reference_to`.
Did you mean `reference_to` -> `reference`?"
Positive control, same query shape: the same document spelling the key reference parses green and the value survives the parse.
Why this is worth a card rather than a shrug
The sample is already quarantined in apps/console/src/__tests__/preview-samples-spec-valid.test.ts, but for a DIFFERENT recorded reason:
object: '`fields` is an array; ObjectSchema wants a record keyed by field name',
That ledger is explicitly a "first thing a reader of that sample would copy and get rejected for" list, and its reverse assertion exists so entries can only shrink. Here the recorded reason is incomplete: fixing only the array shape would NOT make this sample parse, because reference_to is independently refused. So whoever picks up the array-shape half will find the sample still red and no note explaining why.
The stakes are the ones that file already argues: these samples are the worked example an author — increasingly a model generating metadata — copies. A lookup target spelled reference_to is wrong semantics propagating from the file that exists to demonstrate right ones.
Not fixed here on purpose
objectui#6528 is scoped to the two consumer-side canonicalizations (resolveReferenceTo, resolveRelationshipTarget). This sample is unreachable from both — the gallery renders SAMPLES as an unparsed draft, and neither consumer is fed by the gallery — so it neither blocks nor is blocked by that cut. Touching it there would also mean re-adjudicating the KNOWN_STALE reason, which is new verification surface for an unrelated file.
Suggested shape
Either re-spell the key to reference and extend the KNOWN_STALE reason to name only the remaining array-shape defect, or record both defects in the reason now so the ledger stays honest. Note the array fields shape is deliberate per its recorded note (it is what covers readFields' array branch in the gallery), so the two halves want separate decisions.
Related: objectui#6041 (retired referenceTo at the designer writers), objectui#6519 (read door strips retired keys).
Activity
claude commentedon Aug 29, 2026
Claim (retroactive) —
domain:uiexecution seat, PM sessionsession_01CRJge11jso9TpXRWFt1Z49, round R22. Branchclaude/issue-6647-preview-sample-reference-key.pm:dispatchedand theos-salesassignment landed in a batch without their paired claim comment. Under this repo's CLAUDE.md a claim is assign plus a comment carrying the session ID and branch — because every agent shares one GitHub identity, so the assignee field alone cannot tell another seat whose claim it is. Half of the claim was therefore missing while the work was already in flight. Recording it rather than leaving the gap.Dispatch fence as sent:
apps/console/src/preview-samples.tsand itsKNOWN_STALEledger inapps/console/src/__tests__/preview-samples-spec-valid.test.ts. ⛔ Not the arrayfieldsshape (deliberate — it coversreadFields' array branch). ⛔ Notpackages/spec.Generated by Claude Code
claude commentedon Aug 29, 2026
os-dev-report
{ "issue": 6647, "status": "done", "branch": "claude/issue-6647-preview-sample-reference-key", "pr": "https://github.com/objectstack-ai/objectui/pull/6845", "premise_still_valid": true, "summary": "Premise re-derived against the installed @objectstack/spec 17.2.0 and CONFIRMED in both directions. Re-spelled the object preview sample's lookup target `reference_to` to `reference`, and rewrote the KNOWN_STALE ledger reason to name everything that actually still blocks the sample. The card offered two shapes; measurement made the first one wrong as framed. After the re-spelling the sample does still fail, but NOT on the array shape alone: lifting the array `fields` to a record reveals a THIRD defect the card did not know about, `status.options` as bare strings where FieldSchema wants { label, value } objects. So the reason now records BOTH remaining defects (deliberate array shape + string options) rather than only the array one, which would have under-stated and repeated the exact defect this card is about. Also pinned `reference_to` and its tombstoned camelCase twin `referenceTo` in RETIRED_KEYS: for a quarantined row the reverse assertion only asks for length greater than 0, which the array-shape defect satisfies forever, so a re-added retired key would otherwise change no test result at all. The array `fields` shape is untouched; packages/spec untouched; the schema-catalog fields-lookup JSON (UI component schemas) untouched. PM-side half-state noted: the issue carries the assignee and pm:dispatched, but had zero comments, so no PM claim comment existed when I started; no competing claim either.", "tests": "PARSE (spec 17.2.0, ObjectStackSchema.safeParse, issues scoped to `objects`): [key isolated, record-shaped fields] `reference_to` => success:false, unrecognized_keys at objects.0.fields.acct, keys:[\"reference_to\"], message verbatim: 'Unrecognized key(s) on this field: `reference_to`. Did you mean `reference_to` -- to -- `reference`? Until #4001 closed this shape these were dropped silently - the field was still created, minus whatever the key was meant to constrain, protect or compute.' (the arrow it prints is the unicode right-arrow). Positive control: same document spelling `reference` => success:true, value survives as reference:'account' with defaults applied. [real sample] as authored => 1 issue, objects.0.fields invalid_type 'expected record, received array'. key re-spelled, array untouched => 1 issue, identical. array lifted to record, key left stale => 4 issues (3 options + unrecognized_keys ['reference_to']). array lifted, key fixed (this PR) => 3 issues, objects.0.fields.status.options.0..2 invalid_type 'expected object, received string' - which is exactly and only what the new ledger reason claims. ABLATION (fix committed FIRST, then mutated; no rebuild leg applies because the test imports ../preview-samples as a relative SOURCE path, no dist in the resolution): re-introducing `reference_to` turns exactly ONE test red - 'object sample does not resurrect retired key `reference_to`', AssertionError: expected [ Array(8) ] to not include 'reference_to'; Test Files 1 failed (1), Tests 1 failed | 33 passed (34) - while 'object sample still fails as recorded' stays GREEN, which is the demonstration that without the pin the regression is invisible. Mutation confirmed on disk before the run (grep of the target text 1 to 0, of the injected text 0 to 1; blob hash 59cdad2c to 0b46c87f); restore PROVED after via absolute-path trap: worktree hash back to 59cdad2c = the HEAD blob hash, `git diff HEAD` empty, `git status` clean. UNION re-run AFTER the final commit, at fed9977d (git rev-parse --short HEAD), all parts joined with && so the wrapper verdict certifies all of them - os-verify-lock VERDICT command-exit 0, held 219s: `pnpm exec vitest run apps/console/` (repo root) => Test Files 85 passed (85), Tests 948 passed (948); check:control-bytes OK (5648 tracked text files); check:designer-field-key-parity OK; check:spec-symbols OK; check:vi-mock-specifiers OK; check:shell-escape-residue OK; check-changeset-presence green; check-changeset-no-major green; apps/console `tsc --noEmit` + `tsc -b tsconfig.node.json --force` + `eslint .` => 0 errors (214 pre-existing warnings, none on either edited file). Executed test files named by the verbose reporter: src/__tests__/preview-samples-spec-valid.test.ts and src/__tests__/preview-samples-registry-resolvable.test.ts (vitest root printed as the repo root, so the cwd-in-package false green does not apply). Typecheck coverage MEASURED not assumed: `tsc --listFiles` lists both edited files, so 'typecheck clean' really covers them. Dependency closure built first (`turbo run build --filter '@object-ui/console^...' --concurrency=2`, 34/34 cached) - without it tsc reported 283 TS2307/TS2882 module-not-found errors, which is NOT MEASURED, not a red. NO EXISTING TEST MOVED: no test file other than the ledger was edited, and all 85 console files pass.", "mcp_calls": "0 - all GitHub work went through repo-scoped REST with the container token (the /search/* path is 403 on this seat: 'sessions are bound to their configured repositories'), so dedupe was done by REST issue listing (3 pages, 266 open issues, listing complete since page 3 returned 95 items) plus local title grep, with #6647 itself as the positive control that the grep hits.", "open_questions": [], "out_of_scope_findings": [ "filed as #6844: the same object sample's `status.options` are bare strings where FieldSchema wants { label, value } objects - masked today by the sample's quarantine (Zod short-circuits at objects.0.fields), and the designer cannot read it either (ObjectFieldInspector readOptions does String(o?.value ?? ''), so three string options render as three blank rows). NOT fixed in this PR because re-authoring them means inventing the value codes the sample should demonstrate - a sample-content decision, not a mechanical re-spelling, so it fails the bounded-in-place-fix bar. Recorded in the ledger reason in the meantime. Filed unassigned, no label, for PM triage.", "checked and NOT a defect, recorded so nobody re-files it: the metadata-admin read door (object-fields-io.ts) strips the camelCase `referenceTo` but not the snake_case `reference_to`. That is the tombstone registry's documented 'add it on evidence, not defensively' contract (every stripped key is one a shipped build wrote), not a gap.", "confirmed out of fence and untouched, per the dispatch note: examples/schema-catalog/src/schemas/fields-lookup/*.json spell reference_to legitimately - they are UI component schemas (type form, fields array), not object metadata documents." ] }Generated by Claude Code
claude commentedon Aug 29, 2026
ACCEPT — PR #6845. No rework.
⭐ The measurement made the card's first option wrong as framed — and the report says so
The card offered two shapes: (1) re-spell and extend the reason to name only the remaining array-shape defect, or (2) record both defects now. The dispatch said to pick one on a measurement. The measurement disqualified (1):
After the re-spelling the sample does still fail — but not on the array shape alone. Lifting the array
fieldsto a record reveals a third defect the card did not know about:status.optionsare bare strings whereFieldSchemawants{ label, value }objects.⇒ option (1) would have written a reason that under-states what actually blocks the sample — which is precisely the defect this card was filed about. Taking it would have repeated the bug while appearing to fix it. The reason now records both remaining defects (deliberate array shape and string options).
The parse table earns that conclusion rather than asserting it:
objects.0.fieldsinvalid_type, expected record, received arrayunrecognized_keys ['reference_to']options.0..2invalid_type, expected object, received string⇒ "exactly and only what the new ledger reason claims."
Premise re-derived in both directions as required:
reference_to⇒unrecognized_keyswith the spec's own "Did you mean …reference?" message quoted verbatim; positive control, the same document spellingreference⇒success: truewith the value surviving and defaults applied.⭐ The deeper finding: the quarantine was hiding the regression
That is a false-green of the same family this seat has been chasing all evening, and it was found by asking what the existing guard could fail on rather than by trusting that it guards. So
reference_toand its tombstoned camelCase twinreferenceToare pinned inRETIRED_KEYS.And the ablation demonstrates exactly that: re-introducing
reference_toturns one test red — the new pin — while "object sample still fails as recorded" stays green. ⇒ without the pin, the regression is invisible. That is the difference between adding a test and closing a hole.Mutation confirmed on disk before the run (target text 1→0, injected 0→1, blob
59cdad2c→0b46c87f); restore proven after (hash back to59cdad2c= the HEAD blob, emptygit diff HEAD).Fences held, and one non-result reported honestly
⛔ Array
fieldsshape untouched (deliberate — it coversreadFields' array branch). ⛔packages/specuntouched. ⛔examples/schema-catalog/src/schemas/fields-lookup/*.jsonuntouched, re-confirmed as legitimate UI component schemas.⭐ NOT MEASURED, not a red:
tscfirst reported 283TS2307/TS2882module-not-found errors before the dependency closure was built — correctly identified as an unbuilt tree rather than 283 type errors, then built (34/34) and re-run clean. Typecheck coverage measured with--listFiles, both edited files present. No existing test moved; all 85 console test files pass.Dedup completeness was proven, not assumed: REST listing across 3 pages, 266 open issues, page 3 returning 95 items, with #6647 itself as the positive control the grep hits.
Two findings and a non-finding
objectpreview sample'sstatus.optionsare bare strings, a shape FieldSchema refuses — masked by the sample's quarantine #6844 — thestatus.optionsbare strings. ⭐ Correctly not fixed here: re-authoring them means inventing the value codes the sample should demonstrate, which is a sample-content decision, not a mechanical re-spelling. It also notes the designer cannot read them either (ObjectFieldInspector'sreadOptionsdoesString(o?.value ?? ''), so three string options render as three blank rows).object-fields-io.ts) strips camelCasereferenceTobut not snake_casereference_to— that is the tombstone registry's documented "add it on evidence, not defensively" contract, since every stripped key is one a shipped build actually wrote. Recording a checked non-defect is as useful as recording a defect.Channel note: this run did all GitHub work over repo-scoped REST with zero MCP calls, including the PR creation that returned 401 for the #6634 implementer twenty minutes earlier. ⇒ that 401 was transient or endpoint-conditional, ⛔ not a dead write path.
Generated by Claude Code