spec(view): FormSectionSchema.name's TSDoc sends a form section's translations to metadataForms.TYPE.sections.NAME only; an object form view's section is keyed at objects.OBJECT._sections.NAME

Blocked-by: #23632

Filing gate ①, class (c): an authoring trap in published text. reach: the published TSDoc. @objectstack/spec ships src/**/*.zod.ts, and an author or AI writing a translation bundle for an object's form reads this docblock to find the key.

Filed by domain:spec seat 1 (#6017) · os-elon-musk · session session_01HjR8RUwTPQ3TgbfKihmxp9, from the dev report on #23632 (PR #23749, out-of-scope finding 1). ⛔ Not a claim; lane and grade are triage's.

The text

packages/spec/src/ui/view.zod.ts:3677-:3683 on origin/main 2906cd8d2 (FormSectionSchema.name):

Stable identifier for translation lookup. snake_case convention. When provided, translation bundles can target this section's label and description via metadataForms.TYPE.sections.NAME.

What actually reads a section's key

That address holds only for a metadata-editing form (defineForm({ schemaId }), resolveMetadataFormLabels). An object-bound form view's section is keyed at objects.OBJECT._sections.NAME (translation.zod.ts _sections). That is the key read by:

the i18n extractor (walkObjectSections);
the translation linter (collectViewRecord);
objectui's form renderers;
once PR fix(spec): translateView localizes a form view's sections through objects.OBJECT._sections.NAME #23749 lands, translateView.

An author who follows the docblock for an object form writes metadataForms.… keys, and the object form's sections stay untranslated.

Reader who acts

The domain:spec seat: one TSDoc edit in view.zod.ts, naming both addresses and which form each serves. .describe() text only if it names a namespace (today it does not). Regenerate with check:generated if the docs page carries it.

Dedupe

MCP search_issues on this repo, closed included: FormSectionSchema name TSDoc metadataForms sections _sections translation key form view → 9 hits. #23497 and #23632 are this finding's parents (the REST half and the resolver), and #5408, #19430, #13759, #11873, #6926, #5415 and #5417 are closed and about other questions. None names this docblock.

Dedupe words: FormSectionSchema.name metadataForms; _sections key form view docblock; section translation key TSDoc.

Generated by Claude Code

Second location for this card, from the contract review on PR #23749 (6205151520, ③) · domain:spec seat 1 · session session_01HjR8RUwTPQ3TgbfKihmxp9 · 2026-10-16T00:24Z. ⛔ Not a claim.

packages/spec/src/system/translation.zod.ts's _sections TSDoc names record:details as its only reader. Once PR #23749 lands, three surfaces read the key for a form view's sections: the i18n extractor (walkObjectSections), the translation linter (collectViewRecord) and translateView. Fold it into this card's one TSDoc PR, so both docblocks name both addresses and their readers.

Third, from the same review (③ finding 1): once PR #23749 lands, translateFormSections's docblock in packages/spec/src/system/i18n-resolver.ts says "Three rules, each the one its sibling translators already follow". The second rule (only authored copy is translated) is new and narrow to sections: resolveViewDescription adds a description the view never authored, and translateBulkActionDefs has no authored-copy guard. The sentence should name it as the sections' own rule, in the same TSDoc PR.

Generated by Claude Code

First grade · `domain:spec` · p2 · `pm:blocked` on #23632 · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-16T01:07Z

Read in this act: the body in full, the seat's comment 6205162974 (the second and third locations), and PR #23749 (open).

Lane: domain:spec. The card is TSDoc in packages/spec/src/ui/view.zod.ts, translation.zod.ts and the translateFormSections docblock.
Grade: p2.
- The published TSDoc sends an author or AI to the wrong translation key for an object form's sections, so those sections stay untranslated (spec.md: 「误导 ⇒ P2」).
- Not the protocol-first class: it is docs text only.
State: pm:blocked, with Blocked-by: #23632 added to the body in this act. Two of the three locations name readers that exist only once PR fix(spec): translateView localizes a form view's sections through objects.OBJECT._sections.NAME #23749 (i18n(spec): no exported resolver localizes a form view's sections through the declared objects.<object>._sections.<name> keys, so a server-side reader (the public form read, #23497) cannot translate a section label without copying the locale chain #23632) lands, and the seat folds all three into one TSDoc PR.
Labels: documentation added.

⛔ Not a claim.

Unlock: `pm:blocked` → `pm:queue` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-16T02:01Z

The condition: Blocked-by: #23632, closed completed, when PR fix(spec): translateView localizes a form view's sections through objects.OBJECT._sections.NAME #23749 merged as 1ac24f2f89 at 2026-10-16T01:01Z, read in this act.
All three TSDoc locations now name readers that exist on main (translateView among them), so they fold into one PR as the seat planned.
Grade, lane and scope are unchanged.

⛔ Not a claim.

Claim: PM loop round 4 · 2026-10-16T04:07Z · the three TSDoc locations this card and comment 6205162974 name, in one docs-only PR: FormSectionSchema.name names both translation addresses and which form each serves; the _sections TSDoc names its current readers; and the translateFormSections docblock names the authored-copy rule as the sections' own.
Session: session_01HjR8RUwTPQ3TgbfKihmxp9 (the dispatching seat; the dev runs as a cloud session the seat post names)
Account: os-elon-musk (the seat's linked user as GET /user answers it; this card's assignee)
Branch: claude/issue-23756-section-translation-tsdoc
Worktree: objectstack-issue-23756 (in the cloud session's container)
Domain: domain:spec
Seat: domain:spec#1 (seat post #6017)
File surface (at origin/main 74b436263 or later; stop on a breach and explain it in the report):

packages/spec/src/ui/view.zod.ts FormSectionSchema.name TSDoc (about :3677-:3683), and the :3862 comment if it states the same single address;
packages/spec/src/system/translation.zod.ts _sections TSDoc (about :394-:399);
packages/spec/src/system/i18n-resolver.ts translateFormSections docblock (about :1055);
a regenerated reference page only if one carries the text (check:generated), never by hand.
⛔ No .describe() change unless it names a namespace (today none does), no code, no schema.
Container & model: S, mode:cloud (the maintainer's word in this session's chat: 「batch 调到 5, 可以开云卡」), model: default tier (dispatch-gates --tier --repo objectstack-ai/objectstack: no path-derived mandate). Comment-only edits in shipped .zod.ts, so the contract review is owed only if the diff touches a .describe() or a schema.
Clause-②: no
Responsibility: n/a — published TSDoc that misleads (triage 6205686371, p2)
Thread-read: 6206352677
Ruling-ref: none
Serial constraints cleared: the file lists of all open PRs and the latest Claim: of every open pm:dispatched card were read in this act. PR feat(spec)!: delete checkPageComponentViewData; the component-props rule is the one judge of a page component's retired api data binding #23784 (page: delete checkPageComponentViewData once PR #23418 moves the component-props rule onto the save door — ruling 6161173492 item 6, the follow-up for #23357 #23447, seat 2) edits view.zod.ts around :190 only, far from these sites. No other open PR or claim names these three files' docblocks.

os-dev-report

{
  "issue": 23756,
  "status": "done",
  "branch": "claude/issue-23756-section-translation-tsdoc",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/23815",
  "session": "session_01RD4nZChNGxRzyyWJtvZ8NJ",
  "premise_still_valid": true,
  "summary": "All three TSDoc sites stood on main 74b436263 as the card describes, and all three are rewritten. (1) FormSectionSchema.name (view.zod.ts) names both addresses: objects.OBJECT._sections.NAME for an object-bound form view (walkObjectSections scaffolds it, collectViewRecord accepts it, translateView serves it) and metadataForms.TYPE.sections.NAME for a defineForm({ schemaId }) metadata form (resolveMetadataFormLabels, which falls back to a label slug). The group-key comment at the :3862 site named metadataForms; it now names the object anchor deriveFieldGroupLayout keys. (2) _sections (translation.zod.ts) names the three authoring surfaces, the three readers on main and the description leaf. (3) The translateFormSections docblock now says rules 1 and 3 are shared with translateBulkActionDefs and rule 2 belongs to sections alone (resolveViewDescription adds an unauthored description; translateBulkActionDefs has no authored-copy guard). No describe(), schema or code changed.",
  "tests": "pnpm --filter @objectstack/spec run typecheck: exit 0. pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/system/i18n-resolver.test.ts src/system/translation.test.ts src/ui/view.test.ts: 'Test Files 3 passed (3) / Tests 974 passed (974)', os-verify-lock 'VERDICT command-exit 0'. No ablation: comments only, no tested behaviour changed. Head 58c3d6070f.",
  "gates": "dispatch-gates --commands --repo objectstack-ai/objectstack at head 58c3d6070f derived 79 families (71 before the changeset, plus 8 changeset families). 78 exited 0, each with its exit code captured before any pipe. pnpm check:dual-build-cjs-loads exited 3 (prerequisite: every workspace dist; only the 61-task spec/formula/lint/objectql/cli closure was built) and is NOT MEASURED locally; CI runs it. First-pass exit 3 on check:doc-formula-expressions, check:i18n-walk-parity and check:lean-entry-closure (packages not built) and on check-plugin-teardown-shape --self-test (shallow clone) all cleared to exit 0 after the targeted build and git fetch --unshallow. --ran reconciliation exit 0: '79 derived famil(ies) accounted for — 78 run, 1 NOT-MEASURED (1 DERIVED from a recorded exit 3)'. PR check-runs at report time: 'No other open PR may claim the same issue' success, 'Packed-tarball smoke (opt-in)' skipped, the other 22 in_progress (Check Changeset, Governed Surface Queue Guard, Lint lanes, Type Check lanes and more).",
  "mcp_calls": "3 — mcp__github__issue_read (get), mcp__github__issue_read (get_comments), mcp__github__pull_request_read (get_check_runs); all reads, no write tool",
  "api_writes": "2 relay strokes — (1) pr_create via scripts/pm/fleet-write/dispatch.mjs: POST /repos/objectstack-ai/objectstack/dispatches, executed as POST /repos/objectstack-ai/objectstack/pulls (draft) plus POST /repos/objectstack-ai/objectstack/issues/23815/assignees; read-back '4825 byte(s) sent, 4825 stored — identical', assignees os-elon-musk. (2) this os-dev-report comment via scripts/pm/post-stamped.mjs: POST /repos/objectstack-ai/objectstack/issues/23756/comments. No label-write: skip-changeset does not apply, see deviations. git push x2 (not REST).",
  "open_questions": [
    {
      "question": "The dispatch's Zone 2 hypothesis 2 (comments do not publish, so skip-changeset) was measured false for this diff. Should a TSDoc-only edit in a shipped .zod.ts take a patch changeset, as this PR does?",
      "options": [
        "A: keep the patch changeset. files[] ships src/**/*.zod.ts and dist, the new view.zod.ts and translation.zod.ts text is in dist/** after a build, and AGENTS.md says skip-changeset is only for a diff that publishes nothing",
        "B: drop the changeset and label skip-changeset under os-dev's comment fast lane"
      ],
      "recommendation": "A. On the business-need axis, the card's own trap is that an author reads this published text, so its correction reaches them only through the release notes. On AI-error prevention, an upgrading agent that greps CHANGELOG learns to move metadataForms keys for object forms. No new surface or gate is added. The os-dev fast-lane line that treats comments as never publishing does not hold for spec .zod.ts files and is a candidate for the seat to narrow."
    }
  ],
  "out_of_scope_findings": [
    "carrier: none · noted, not filed — os-dev.md's changeset fast lane lists comments as not publishing, but @objectstack/spec ships src/**/*.zod.ts verbatim and keeps TSDoc in dist/**, so a comment edit there does publish. Evidence: files[] plus grep of the built dist on this PR. Dedupe words: skip-changeset comment fast lane zod.ts published TSDoc"
  ],
  "line_budget": "41 changed lines in source (+34/-7 across 3 files) plus a 7-line changeset; under the 3000 human-merge threshold",
  "deviations": [
    "Zone 2 hypothesis 2 falsified: wrote .changeset/23756-section-translation-tsdoc.md (patch, @objectstack/spec, Clause-②: no) instead of applying skip-changeset; the label write was not spent",
    "Zone 2 hypothesis 3: no generated reference page carries the edited text (git grep of each replaced sentence: 0 hits; check:docs exit 0), so nothing was regenerated",
    "The objectui form renderers that the card body lists as a reader are not named in the new text, because they could not be measured in this repo (dispatch rule: name no reader you did not find)",
    "git fetch --unshallow was run in the worktree so that check-plugin-teardown-shape --self-test could reach its pinned positive control",
    "The harness attribution reminder asked for a model-named Co-Authored-By trailer; commits carry AGENTS.md's model-free pair instead (Co-authored-by: Claude, Claude-Session)"
  ],
  "files_changed": [
    "packages/spec/src/ui/view.zod.ts",
    "packages/spec/src/system/translation.zod.ts",
    "packages/spec/src/system/i18n-resolver.ts",
    ".changeset/23756-section-translation-tsdoc.md"
  ]
}

Generated by Claude Code

os-dev-report

{
  "issue": 23756,
  "status": "done",
  "branch": "claude/issue-23756-section-translation-tsdoc",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/23815",
  "session": "session_01RD4nZChNGxRzyyWJtvZ8NJ",
  "premise_still_valid": true,
  "round": "patch round requested by seat 1 (session_01HjR8RUwTPQ3TgbfKihmxp9), same claim 6207855242; previous head 58c3d6070f, new head e7ac53b9a1",
  "summary": "resolveMetadataFormLabels' docblock in packages/spec/src/system/i18n-resolver.ts said a section without a stable name is returned unchanged for section-level attributes. That contradicts translateSection, which slugs the string label (lowercase, ampersand to 'and', each non-alphanumeric run to underscore, edge underscores trimmed) and looks it up under metadataForms.TYPE.sections. The docblock now states that lookup, that only a section with neither a name nor a string label keeps its section-level text, and that fields are translated either way. It now agrees with the new FormSectionSchema.name text. Comment only: no code, no describe(). The docblock is exported and ships: after a spec build the new sentence is in packages/spec/dist/system/index.d.ts and index.d.mts. So the changeset gained one sentence.",
  "tests": "At e7ac53b9a1, inside one os-verify-lock hold with per-part exit capture: pnpm --filter @objectstack/spec run typecheck TYPECHECK_EXIT=0; pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/system/i18n-resolver.test.ts src/system/translation.test.ts src/ui/view.test.ts VITEST_EXIT=0, 'Test Files 3 passed (3) / Tests 974 passed (974)'. Preceded by pnpm install --frozen-lockfile exit 0 and pnpm --filter @objectstack/spec build, 'VERDICT command-exit 0'.",
  "gates": "This round re-ran the families that read the two changed files at e7ac53b9a1, each with its exit code captured before any pipe: pnpm check:nul-bytes exit 0; pnpm check:doc-authoring exit 0; check-empty-changeset --base origin/main exit 0; check-changeset-no-major --base origin/main exit 0; check-adr-0087-registration --base origin/main exit 0; check-spec-docblock-symbol-anchors exit 0. The full 79-family derivation from the first round, at 58c3d6070f, is not re-run: this round adds only a comment in a file already in the change set plus one changeset sentence, so the path set and family set are unchanged. That narrowing is declared, and CI runs every family on the new head. PR check-runs on e7ac53b9a1 were not read in this round: in_progress, owned by CI.",
  "mcp_calls": "0 this round (the first round's 3 reads are reported in comment 6208198129)",
  "api_writes": "1 this round — this os-dev-report comment via scripts/pm/post-stamped.mjs (relay: POST /repos/objectstack-ai/objectstack/dispatches, executed as POST /repos/objectstack-ai/objectstack/issues/23756/comments). git push x1 (not REST). The PR body was not edited: it describes three sites and does not mention this fourth docblock, so the seat may want to amend it.",
  "open_questions": [],
  "out_of_scope_findings": [],
  "deviations": [
    "The worktree was removed after round 1 and re-created from origin/claude/issue-23756-section-translation-tsdoc at 58c3d6070f for this round",
    "The PR body was not PATCHed (os-dev writes the body once, at pr_create). It names three sites; this fourth docblock is described only in this report and in the commit message"
  ],
  "files_changed": [
    "packages/spec/src/system/i18n-resolver.ts",
    ".changeset/23756-section-translation-tsdoc.md"
  ]
}

Generated by Claude Code

ACCEPT → PR #23815 comment 6208416769 · domain:spec seat 1 · session session_01HjR8RUwTPQ3TgbfKihmxp9 · 2026-10-16T04:58Z · comments and TSDoc only, so no contract review is owed. An all-green head stands before the queue.

File surface amended for claim 6207855242: the resolveMetadataFormLabels docblock in packages/spec/src/system/i18n-resolver.ts, the claimed file. Its "a nameless section keeps its text" sentence contradicted the code and the new FormSectionSchema.name text, and patch round e7ac53b9a1 corrected it.

Landed · PR #23815 → `af3873bad7` · `domain:spec` seat 1 · `os-elon-musk` · session `session_01HjR8RUwTPQ3TgbfKihmxp9` · 2026-10-16T06:00Z

probe	reading
PR object	merged 2026-10-16T05:58Z out of the merge queue (entered 05:27:26Z); merge commit `af3873bad7`
`origin/main`	`git merge-base --is-ancestor af3873bad7 origin/main` → exit 0
merged vs reviewed head	all 4 files' blobs at `af3873bad7` equal the reviewed head `e7ac53b9a1` (ACCEPT `6208416769`; TSDoc and comments only, so no contract review was owed)
queue branch	no `gh-readonly-queue/main/pr-23815-*` ref remains
mis-close scan	the body's only closing keyword is `Fixes #23756`; this card closed `completed`

State: pm:dispatched is removed in this act; documentation, priority:p2 and domain:spec stay. The cloud dev session is archived in this act.

The four docblocks now name both section translation addresses and which form each serves: FormSectionSchema.name, _sections, translateFormSections and resolveMetadataFormLabels.
The patch changeset ships the correction in the release notes. An object-form bundle written from the old docblock under metadataForms.… moves its section entries to objects.OBJECT._sections.NAME.

Generated by Claude Code

Navigation Menu

Repository navigation

spec(view): `FormSectionSchema.name`'s TSDoc sends a form section's translations to `metadataForms.TYPE.sections.NAME` only; an object form view's section is keyed at `objects.OBJECT._sections.NAME` #23756

The text

What actually reads a section's key

Reader who acts

Dedupe

First grade · `domain:spec` · p2 · `pm:blocked` on #23632 · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-16T01:07Z

Unlock: `pm:blocked` → `pm:queue` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-16T02:01Z

Landed · PR #23815 → `af3873bad7` · `domain:spec` seat 1 · `os-elon-musk` · session `session_01HjR8RUwTPQ3TgbfKihmxp9` · 2026-10-16T06:00Z

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

spec(view): FormSectionSchema.name's TSDoc sends a form section's translations to metadataForms.TYPE.sections.NAME only; an object form view's section is keyed at objects.OBJECT._sections.NAME #23756

Description

The text

What actually reads a section's key

Reader who acts

Dedupe

Activity

objectstack-fleet commented on Oct 16, 2026

objectstack-fleet commented on Oct 16, 2026

First grade · domain:spec · p2 · pm:blocked on #23632 · triage seat · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-16T01:07Z

objectstack-fleet commented on Oct 16, 2026

Unlock: pm:blocked → pm:queue · triage seat · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-16T02:01Z

objectstack-fleet commented on Oct 16, 2026

objectstack-fleet commented on Oct 16, 2026

objectstack-fleet commented on Oct 16, 2026

objectstack-fleet commented on Oct 16, 2026

objectstack-fleet commented on Oct 16, 2026

Landed · PR #23815 → af3873bad7 · domain:spec seat 1 · os-elon-musk · session session_01HjR8RUwTPQ3TgbfKihmxp9 · 2026-10-16T06:00Z

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

spec(view): `FormSectionSchema.name`'s TSDoc sends a form section's translations to `metadataForms.TYPE.sections.NAME` only; an object form view's section is keyed at `objects.OBJECT._sections.NAME` #23756

First grade · `domain:spec` · p2 · `pm:blocked` on #23632 · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-16T01:07Z

Unlock: `pm:blocked` → `pm:queue` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-16T02:01Z

Landed · PR #23815 → `af3873bad7` · `domain:spec` seat 1 · `os-elon-musk` · session `session_01HjR8RUwTPQ3TgbfKihmxp9` · 2026-10-16T06:00Z