finding(app-shell): the page designer writes page:tabs items[].key — a key PageTabsProps refuses by name and the tabs renderer never reads

Found by the census objectui#8216 asked for (branch claude/issue-8216-block-config-schema-parity). Filed unassigned, out of that card's scope — objectui#8216 ships the gate and ledgers this key; the resolution is this card's.

Measured on origin/main f20e57d62, installed @objectstack/spec 17.2.0.

What

BLOCK_CONFIG['page:tabs'] (packages/app-shell/src/views/metadata-admin/previews/block-config.ts) offers one array control, items, whose item editors are key and label. PageBlockInspector.renderField writes an item key VERBATIM — next[i] = { ...itemObj, [n]: v } — so an author who fills the first box gets properties.items[0].key.

Three faces disagree with that spelling:

The spec refuses it by name. ComponentPropsMap['page:tabs'] is strict, and its item shape declares label, icon, visibleWhen, value, count, children. Measured at runtime:
ComponentPropsMap['page:tabs'].safeParse({ items: [{ key: 'a', label: 'A' }] }) returns success: false with unrecognized_keys naming key at path items.0.
The renderer never reads it. PageTabsRenderer (packages/components/src/renderers/layout/containers.tsx:630) builds itemsWithValue from it.value, falling back to an index-derived tab-IDX when absent. There is no read of it.key in that file.
The repo's own prose already says value is the live key. previews/__tests__/block-config.test.ts states it inside the page:accordion describe: the accordion's panel id is unconditionally derived, "the tabs one is genuinely live", and PageTabsProps.items[].value "is a real, declared schema member". The designer control simply does not write that member.

Consequence

A tab strip built in Studio carries no stable per-tab value, so every tab falls back to tab-IDX. That is exactly the failure objectui#2257 dealt with for the URL-addressable active tab (?tab=): an index value silently points at a different tab once the item list changes. The author DID supply a stable identifier; it landed under a key nothing reads.

The key additionally reaches the platform's component-props lint as an unknown authoring key: PageComponent.properties is z.record(z.string(), z.unknown()) so the page parse itself stays green, and ComponentPropsMap[type] is reached only by the lint gate that dispatches on the sibling type (the spec's own note on lintUnknownKeysAgainstSchema, objectstack#5068).

The decision this needs

Contract-first (AGENTS.md #0.1) points at the producer, and the producer is this table — the fix is to rename the control to value, not to teach the renderer a second spelling. But the rename is not a one-line edit and that is why it is a card rather than a rider:

the field name is the i18n key's last segment, so engine.inspector.pageBlock.field.page:tabs.items.key becomes ...items.value in BOTH locale tables in metadata-admin/i18n.ts, and the retired key must leave both (the pattern objectui#3829 and objectui#5212 set);
documents saved by every released build carry items[].key, so the read-door question objectui#7772 answered with stripRetiredBlockProps applies here too — except this one is a NESTED key, which that helper does not reach;
objectui#3912 is open against the same box for a different reason (no pattern/validate affordance on BlockPropField), so whoever takes this should read that card first.

Triage: lands in domain:ui (packages/app-shell designer table, with a read-door question in packages/components); rationale: admitted under class (c) and class (b), and it is the cleanest example of (c) this seat has graded. The designer writes properties.items[].key; ComponentPropsMap['page:tabs'] is strict and returns success: false with unrecognized_keys naming key — measured at runtime, quoted in the card — and PageTabsRenderer never reads it.key. So the author supplies a stable identifier and the runtime both refuses it by name and drops it in practice. Bug: the spelling contradicts a declared, cited contract.

priority:p2 — 坏得安静. Every Studio-built tab strip falls back to the index-derived tab-IDX, which is exactly the ?tab= failure #2257 was written to prevent: the deep link points at a different tab as soon as the item list changes. No error is raised anywhere on the path (PageComponent.properties is z.record(z.string(), z.unknown()), so the page parse stays green), and the author's own evidence of doing it right — a filled-in key box — is the thing that disappears.

Sequencing for whoever takes it, as a conclusion rather than a suggestion: the rename to value is the producer-side fix (AGENTS.md #0.1) and is right, but it is not complete on its own. Documents saved by released builds carry items[].key, and this is a nested key, which stripRetiredBlockProps (#7772's read door) does not reach — so a rename without a nested read-door path silently discards identifiers already on disk, converting a wrong-key defect into a data-loss one. Both i18n tables move with the field name (…field.page:tabs.items.key → …items.value, retired key removed from both, per the #3829 / #5212 pattern). Read #3912 first — same box, different defect.

⛔ This seat grades and routes only: not claimed, not dispatched, no code.

Generated by Claude Code

Claim: session session_01YBWFb5YgMU5dw8p2VKj16S · branch claude/issue-8278-page-tabs-items-value

PM dispatch (domain:ui seat). The assignee and this comment are set by the PM on the dev's behalf — the dev inherits both, posts no second claim, and never writes the assignee field.

PM ruling — the rename ships now; the stored-document read door does not.

Take the card's contract-first direction: rename the page:tabs items[] control from key to value, and move the i18n key in both locale tables with the retired spelling leaving both (the objectui#3829 / objectui#5212 pattern). The spec refuses key by name at items.0 and PageTabsRenderer reads only it.value, so the producer is the one that is wrong.

⛔ Do NOT add a nested carry-over, alias, or migration for documents already saved with items[].key in this PR. Reasoning, so it is not mistaken for an oversight:

The harm those documents suffer already exists today — items[].key is unread right now, so every stored tab strip already falls back to tab-IDX. The rename does not make them worse; it makes newly-authored strips correct. It is a strict improvement with no regression, which is why it can ship on its own.
The migration is a genuinely separate decision, and a bigger one than this card: stripRetiredBlockProps (objectui#7772) does not reach nested keys, so honouring old documents means extending that machinery, not adding a line. An alias added here instead would be a permanent second spelling with no retirement path — the shape AGENTS.md #0.1 forbids and the one this card exists to remove.
⇒ If your measurement says the migration is worth having, file it as its own card and say so in your report. Do not fold it in.

Two things to read before you write anything:

objectui#3912 is open against this same box for a different reason (no pattern/validate affordance on BlockPropField). The card names it; read it first so this rename does not collide with or pre-empt it.
objectui#8216 ships the census gate that found this and ledgers this key. Check on your own base whether that ledger entry exists, and if it does, deleting it belongs in this change — the same in-the-same-change obligation objectui#8212 established for the input ledger. A rename that leaves its own ledger row behind is a stale pin by construction.

⚠️ Re-measure the spec on your own base: the card measured @objectstack/spec 17.2.0; the installed version is now 17.3.0. Re-run the safeParse probe with its control rather than quoting the card's.

Generated by Claude Code

os-dev-report

{
  "issue": 8278,
  "status": "done",
  "branch": "claude/issue-8278-page-tabs-items-value",
  "pr": "https://github.com/objectstack-ai/objectui/pull/8359",
  "premise_still_valid": true,
  "summary": "Renamed the page:tabs designer item control key -> value in BLOCK_CONFIG, moved the i18n key in BOTH locale tables with the retired spelling leaving both ('Value' / '值', matching the sibling record:path.stages.value box), deleted objectui#8216's LEDGER row for this key, repaired the ledger probe test that row fed, updated three prose sites naming the old spelling, and added a round-trip pin. No carry-over, alias, or migration for stored documents, per the PM ruling. Base 33b507365; PR is DRAFT awaiting PM contract review. The card's premise held on my own base in every particular: spec refuses `key` by name at items.0, PageTabsRenderer reads only it.value, RETIRED_BLOCK_PROP_KEYS cannot express a nested key.",
  "tests": "SPEC PROBE (my own, @objectstack/spec 17.3.0, not the card's 17.2.0), four legs one run, children supplied since the item shape requires it: DEFECT {key,label,children} success=false unrecognized_keys=['key'] at items.0 | CONTROL-A {zzzNotAKey,...} success=false unrecognized_keys=['zzzNotAKey'] (the parser CAN refuse) | CONTROL-B {value,label,children} success=TRUE (so the refusal is about the NAME, not the probe shape) | CONTROL-C {label,children} success=TRUE. ⭐ NEW vs the card: 17.3.0's own message now reads 'Did you mean `key` -> `value`?' — upstream already encodes this rename. || SUITES (repo root, explicit positional paths): packages/app-shell/ + the page:tabs renderer suite = 649 files, 6249 passed, 1 skipped, 0 failed. previews/ + inspectors/ = 118 files, 1348 passed. New pin alone 9/9; pin + 8216 gate 22/22. || type-check: pnpm --filter @object-ui/app-shell type-check exit 0 (tsc --noEmit && tsc -p tsconfig.test.json); tsc --listFiles confirms the new pin IS inside the program (not excluded). || eslint . in packages/app-shell: 0 errors, 2923 pre-existing warnings; the 4 in my file are the no-explicit-any idiom its siblings use. || GATES all exit 0: check:i18n-keys, check:i18n-drift, check:i18n-dead-keys, check:control-bytes, check:designer-field-key-parity, check-changeset-presence, check-changeset-no-major. check-governed-queue-guard --test on the exact file list: NOT GOVERNED, 6 paths vs 5 governed surfaces, none matched. || ABLATION #1 — the READ SITE, not the pin, from the committed implementation, EXIT INT TERM trap on an absolute path: control line put back to name:'key'. ON-DISK PROOF: HEAD blob b35c31bab80dbb2151eee447daacc6d98e2aabb0 vs mutated blob 8efe702b21967714b6107dedefb3d144205c63ff (differ); anchor counts inverted (new 1->0, old 0->1). No rebuild leg needed and this was verified not assumed: the tests import the mutated module by RELATIVE path (../block-config), so it resolves to SOURCE, no dist is involved. FOUR RED ROWS BY NAME: 'no control writes a name its oracle refuses or tombstones' (the 8216 gate: unledgered violation returns) | 'the item an author builds through the designer table is ACCEPTED by the spec' (a designer-authored tab item is refused by name: expected ['key'] to deeply equal []) | 'reports the AUTHORED value on tab change — not the index-derived one' | 'is URL-ADDRESSABLE by the authored value — the objectui#2257 consequence'. CONTROL ROWS STAYED GREEN, including 'CONTROL — the harness renders a tab strip at all' (18 passed / 4 failed of 22), so a red row is the key and not a dead fixture. RESTORED BY STATE, never by an exit code: on-disk blob equal to the HEAD blob again, git diff HEAD EMPTY, git status EMPTY, re-run 22/22 green. || ABLATION #2 — reverted ONLY the ZH row, leaving EN renamed (the half-done rename): on-disk proof HEAD b254cece8... vs mutated fb6956bac...; ONE RED ROW, naming my key: block-config-i18n.test.ts > 'every key resolves in zh-CN' (+ engine.inspector.pageBlock.field.page:tabs.items.value). Restored by state (hash equal, diff empty). || PRE-DELETION EVIDENCE that the ledger deletion was forced, not a courtesy: with the rename landed and the row still present the 8216 gate failed twice by name — 'every ledger row still applies' (stale LEDGER rows) and 'every ledger row names a control that still exists' (LEDGER names 'items[].key': expected ['value','label'] to include 'key').",
  "mcp_calls": "11 — 4 issue_read (8278 get, 8278 get_comments, 3912, 8216), 1 issue_read (8281), 3 search_issues (ALL FAILED, rate limit), 1 create_pull_request, 1 pull_request_read, 1 add_issue_comment (this one)",
  "open_questions": [
    {
      "question": "The nested read door for stored page:tabs items[].key needs a card, and I could not file it: MCP search_issues returned 'API rate limit already exceeded for user ID 323634890' on all three attempts, so I could not run the dedup search, and filing without dedup is a forbidden shape. Requesting the PM file it. NEW measurement that sharpens the card beyond what objectui#8278 knew: (a) RETIRED_BLOCK_PROP_KEYS is a Record keyed by block type holding TOP-LEVEL key arrays, so a nested key is structurally inexpressible — not an omission; (b) objectui#7772's read door admits a key only when the schema refuses it BY NAME, and page:tabs items[].key MEETS that criterion (unlike objectui#8279's definition-list keys, which had no schema at all), so this is the FIRST key that qualifies for the strip and cannot be written into the ledger's shape; (c) after this rename the orphan is unreachable from EVERY inspector control — advancedKeys is Object.keys(blockProps), so a nested key never reaches the Advanced section, and the value box does not read it. Net: an author who repairs a stored strip through the new box still ships an item the component-props lint refuses by name.",
      "options": [
        "A — PM files the nested read-door card from this report; it extends stripRetiredBlockProps to a nested path spec",
        "B — fold it into objectui#8281 / the existing read-door work instead of a new card",
        "C — do not file; accept that stored strips stay lint-refused until re-authored from scratch"
      ],
      "recommendation": "A. The measurement in (c) is a genuinely new failure mode — before this rename no stored strip could be repaired at all, so the 'repaired but still lint-refused' class did not exist; it does now. It does NOT overturn the PM ruling (the lint verdict on a stored item is identical before and after: refused; and the render outcome strictly improves), so the rename correctly ships alone — but the follow-up is now well-specified rather than speculative."
    },
    {
      "question": "Coverage gap found while measuring, worth a finding card: the 'retired i18n key LEFT both tables' half of a metadata-admin rename is enforced by NOTHING. Measured — block-config-i18n.test.ts's 'every key resolves in en-US / zh-CN' catches a MISSING new key (ablation #2 proved it goes red and names the key), but check-i18n-dead-keys.mjs reads only packages/i18n/src/locales/ and does not see metadata-admin/i18n.ts's ENGINE_STRINGS tables at all, so a leftover retired key is invisible. Same dedup blocker as above.",
      "options": [
        "A — PM files it as a finding; extend the dead-key report's corpus to the metadata-admin tables",
        "B — leave it; the four manual readings are the convention and this is the third rename to rely on them"
      ],
      "recommendation": "A, at finding severity, not bug. It is exactly the voluntary-pin shape objectui#8068 argued against for registry inputs, one table over."
    }
  ],
  "out_of_scope_findings": [
    "NOT FILED (search_issues rate-limited, dedup impossible, reported instead of hard-filed): the nested read door for stored page:tabs items[].key — see open_questions[0] for the three new measurements.",
    "NOT FILED (same reason): metadata-admin ENGINE_STRINGS retired keys have no dead-key coverage — see open_questions[1].",
    "NO CARD NEEDED, reported only: objectui#3912's body prose names `page:tabs` items[].key as one of its three identifier-valued examples; that spelling is now stale. Its issue body was left untouched — not my card to edit."
  ]
}

Corrections against the dispatch brief, since a correction is worth more than agreement:

The brief implied the four i18n readings are the only guard. Half wrong, measured by ablation Add automated testing infrastructure and CI/CD workflows #2: block-config-i18n.test.ts › every key resolves in zh-CN goes RED and names the key when only one table is moved. But the enforcement is one-directional — it proves the NEW key arrived, never that the RETIRED one left. So the four readings are still load-bearing, for the other half only.
The brief said to ablate "the READ SITE / the control table". Those are two different things here and only the control table is ablatable: the read site is itemsWithValue in @object-ui/components, which reads it.value and is correct on main — ablating it would test the renderer, not this change. Ablated the control table.
The ledger deletion is not merely "in-the-same-change obligation" by convention — objectui#8216's gate mechanically forces it in two places. Evidence quoted in tests. Worth knowing for the next rename in that table: the row cannot be forgotten.
The spec moved in the fix's favour between 17.2.0 and 17.3.0 — its unrecognized_keys message now names the remedy (Did you mean key -> value ?). Neither the card nor the brief knew this; it is upstream corroboration that value is the intended spelling, not merely the one the renderer happens to read.
PR is DRAFT and stays draft. The diff is NOT governed (guard verdict quoted above), so the ordinary route applies, but per this dispatch the PM contract-reviews, flips to ready and arms auto-merge. I did not flip it and did not arm anything.

Generated by Claude Code

test(metadata-admin): pin that a retired page-block i18n key leaves b…

test(metadata-admin): pin that a retired page-block i18n key leaves B…

Navigation Menu

Repository navigation

finding(app-shell): the page designer writes page:tabs items[].key — a key PageTabsProps refuses by name and the tabs renderer never reads #8278

What

Consequence

The decision this needs

Related

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

finding(app-shell): the page designer writes page:tabs items[].key — a key PageTabsProps refuses by name and the tabs renderer never reads #8278

Description

What

Consequence

The decision this needs

Related

Activity

os-zhuang commented on Sep 7, 2026

os-justin commented on Sep 7, 2026

os-justin commented on Sep 7, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions