spec: the dashboard widget TranslationData node needs a third member for the metric sub-caption — the #5428 ruling's "own key" mandate is unimplementable against the strict `{title?, description?}` node

[yinlianghui]

Contract-first card filed by the objectui whole-repo PM seat (session session_017Qqyix2QcnpUC9XeYVDzx3), spun out of objectui#4032 / PR objectui#4358. Unassigned — for this lane's triage; the objectui seat does not land code here.

The conflict (measured in objectui#4358's implementation)

The #5428 maintainer ruling (2026-08-06), item 4, gives the metric widget's sub-caption (options.description — a DIFFERENT authored field from widget.description) its own translation convention segment, ⛔ explicitly not sharing widget.description's key ("两个作者字段两个 key").

The spec refuses every implementation of that: TranslationDataSchema.dashboards.<dash>.widgets.<id> is strict over exactly { title?, description? }. Measured:

+subCaption  → unrecognized_keys: "Unrecognized key(s) on this widget translation: `subCaption`. …"
+subtitle    → "… Did you mean `subtitle` → `description`? …"
+caption     → unrecognized_keys

— and the schema's own suggestion points the sub-caption AT description, i.e. at precisely the shared key the ruling forbids. objectui#4358 landed ruling items 1–3 and returned item 4 as a stop rather than a workaround; widget.description on a self-contained metric is deliberately still unrendered there, because the only available slot would conflate the two fields.

The ask

Either:

• A — add an optional third member to the widget translation node (subCaption?, or the spelling this lane prefers) so the metric sub-caption keys dashboards.<d>.widgets.<id>.subCaption; objectui's renderer half then lands as a small follow-up (the resolution seam is already in place from console 记录详情页附件面板:沉在整页最底部不可发现(无位置配置)+ 文案未 i18n 中文界面裸奔英文 #4358), or
• B — overturn ruling item 4's two-keys mandate (maintainer veto was reserved) and let the sub-caption share description. That conflates two authored fields under one key — the drift shape the ruling named — but it is the zero-vocabulary option and the schema's own hint currently points there.

A preserves the ruling; B preserves the vocabulary. Either unblocks objectui#4032's last item.

Refs objectui#4032, objectui PR #4358, objectstack#5428 (the ruling), ADR governing TranslationData strictness.

[hotlong]

Triage: lands in packages/spec (TranslationDataSchema's widget node) → domain:spec (accept-set gains an optional member — semantic face). Queued as option A rather than escalated, on ruling inheritance: the #5428 maintainer ruling (2026-08-06, item 4) already mandates the sub-caption gets its own key and explicitly forbids sharing widget.description's ("两个作者字段两个 key"). A strict schema that refuses every implementation of a standing ruling is the ruling being unimplementable, not a new open question — option A (add the optional third member) is the only ruling-consistent shape, and option B is by construction a maintainer-only veto (reserved in the ruling itself). This card appearing in the round report IS that veto window.

Notes for the spec seat:

• Spelling of the member (subCaption? vs alternatives) is lane discretion; whatever is picked, mind the existing error-guidance hint that currently points subtitle → description — after the change it should point at the new member, or it will keep steering authors to the forbidden shared key.
• Downstream: objectui's renderer half is a small follow-up once this lands (resolution seam already in place from objectui#4358); the consuming-package test rule applies — dispatch should name the objectui-facing fixture/test surface to re-check.

Size/model suggestion: S–M, model: sonnet–opus.

---

Generated by Claude Code

[huangyiirene]

Claim: PM loop round 1 (duty-division session, seat post #6017)
Session: session_0123k4cam2jEAkPmbJeoaY3r
Branch: claude/issue-7862-widget-subcaption
Worktree: objectstack-issue-7862
Domain: domain:spec
File surface: packages/spec/src/system/translation.zod.ts (dashboards.<name>.widgets.<id> node + its alias/guidance tables), translation-typegen.ts if it enumerates node members, their tests; regenerated references/** ride. (stop on breach; explain in the report)
Container & model: S–M, mode:subagent, model: fable (claude-fable-5 — mandatory clause: accept-set grows; triage's sonnet–opus suggestion not adopted for that reason)
Serial constraints cleared: no in-flight spec PR touches system/translation.zod.ts (#7892 ui/dashboard.zod.ts, #7972 ui/action.zod.ts, #7985 data/driver/memory.zod.ts); seat-post hot-file queue clear on this file.

Direction per triage's ruling-inheritance read (option A — the #5428 item-4 mandate 「两个作者字段两个 key」 is standing; adding the optional third member is the only ruling-consistent shape; option B remains a maintainer-only veto). Spelling ruled by this seat: subCaption.

---

Generated by Claude Code

[huangyiirene]

{
  "issue": 7862,
  "status": "done",
  "branch": "claude/issue-7862-widget-subcaption",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/8056",
  "premise_still_valid": true,
  "summary": "Option A per the inherited #5428 item-4 ruling, spelling `subCaption` per the seat ruling. The widget translation node (translation.zod.ts:485 region, premise verified on merged main) gains the optional third member; the `subtitle` alias is re-pointed description -> subCaption (the file's recorded rationale covered only the label/title trap, so no fork to report), with the #5428 rationale recorded in-file. Measured per the PM mechanism assumptions: translateDashboard (i18n-resolver.ts, the REST /meta path) DOES enumerate node members and was extended -- `subCaption` overlays the widget's `options.description`, carrying other options keys through, with the two authored fields pinned to their own keys; translation-typegen.ts is object-scoped and needs nothing; lint's validate-translation-references checks widget ids only, not members. Liveness ledger dashboards row note updated. Changeset: @objectstack/spec minor. The exact bundle key path the objectui follow-up consumes (angle brackets avoided for the sanitizer -- read {name}/{widgetId} as placeholders): dashboards.{name}.widgets.{widgetId}.subCaption -- resolution fallback should be the authored options.description. Merged origin/main (7dc1067->3373a29, spec moved on the incoming side) and re-verified on the merged tree. PR body's ready-state/labels: `size/m` was bot-applied; skip-changeset deliberately NOT applied (the PR carries a changeset and releases). CI farm status at report time: in_progress by design -- targeted local gates below were green; the convergence wait is the PM's.",
  "tests": "Local, all green on the merged tree (987333ee8): pnpm --filter @objectstack/spec build; check:generated -> 'All 13 generated artifacts are up to date' (docs/authorable-surface genuinely unchanged -- reference docs truncate the widget node inner shape at `object`); pnpm --filter @objectstack/spec test -> '382 passed (382) / Tests 10113 passed (10113)'; typecheck + test-typecheck ratchet OK (debt unchanged; my new fixtures compile clean). New coverage both directions: subCaption accepted; title/description round-trip pinned byte-identical; unknown key `footnote` still refused naming 'this widget translation'; hint asserted '`subtitle` -> `subCaption`' AND NOT '-> `description`'; near-miss subCaptoin suggested; resolver overlay + two-keys-two-fields separation + no-mutation + options carry-through. Reverse verification against the BUILT dist (directions predicted before running, all confirmed): subCaption parses green, subtitle rejects red pointing at subCaption not description, dist translateDashboard overlays options.description. Named gate families run locally, all PASS: check:adr-anchors, check:changeset-gate-self-tests, check:cross-package-test-inputs, check:doc-formula-expressions (after building @objectstack/formula -- first run was a stale-dist false red), check:docs-audit-scope, check:i18n (9 packages in sync, after building the CLI closure -- same false-red class, gate's own prerequisite message), check:merge-driver, check:release-body, check:spec-parsed-alias, check:nul-bytes (+ raw-control-byte self-scan of every edited file: clean).",
  "open_questions": [],
  "out_of_scope_findings": ["filed as #8052 (sub-issue of #7862): content/docs/ui/translations.mdx (hand-written guide, outside the declared file surface) does not list the widget node's subCaption key; Blocked-by #7862"]
}

---

Generated by Claude Code

---

Generated by Claude Code

[huangyiirene]

ACCEPT — PR #8056 (draft), reviewed per step 7 against GitHub, not the report's self-description.

• Diff is exactly the card plus the measured-in resolver half: optional subCaption on the widget translation node with the objectui: dashboard KPI cards drop the translated widget title/description — the self-contained metric path bypasses tWidgetTitle, and the plugin's private resolveLabel never calls t() #5428 item-4 rationale recorded in-file; the subtitle alias re-pointed at subCaption with both directions asserted (points at subCaption AND does not point at description — the steering trap triage flagged); strictness preserved and pinned (unknown key refused with substance, near-miss subCaptoin suggested); title/description round-trip pinned byte-identical; translateDashboard overlays options.description with the two-keys-two-fields separation pinned both ways, other options keys carried through, no input mutation, bundle-only key creating the bag mirroring title. 6 files; no content/docs/releases/ touches; the liveness/translation.json row note is mechanically entailed bookkeeping for the resolver extension — accepted as in-surface.
• Reverse verification ran against the built dist with directions predicted first; 10113 spec tests green on the merged tree; check:generated 13/13 with references/** genuinely unchanged (the reference docs truncate the widget node's inner shape — verified explanation, not an omission).
• Out-of-scope finding verified filed: docs: content/docs/ui/translations.mdx does not list the dashboard widget node's subCaption key (follow-up to #7862) #8052 (docs guide row; sub-issue, Blocked-by: #7862; unlabeled — left for the triage sweep to route).
• Landing path measured, not assumed: none of the six files carries merge=os-regen in .gitattributes ⇒ this PR needs no relay slot and lands independently; the promised feat(spec,lint): gate managed apiMethods ⊆ affordances where the author is (#7521) #7851 (engine-core) → fix(sharing): enforce the declared publicSharing.eligibility predicate at link creation #7974 (identity) slots are untouched. Flip to ready + queue entry are PM-driven once the gate jobs conclude (the farm was honestly in_progress at report time).
• Consuming-repo follow-up (multi-repo rule): an objectui renderer card will be filed by this seat consuming dashboards.<name>.widgets.<widgetId>.subCaption (resolution fallback = the authored options.description), Blocked-by: this card's PR.

---

Generated by Claude Code