[objectstack-fleet]

Requested by Leehom · project thread

Fixes #32657

Refs #33524 (console half pinned, no console change; the card stays open for its server half)

Clause-②: yes (widening)
Metadata-protocol: none

维护者速读

• 改了什么：保存元数据后弹出的「提醒」以及保存被拒时的问题列表，现在显示服务端按用户语言写好的那句话（userMessage），不再显示给开发者看的英文 message/hint；Studio 被拒保存的提示句也直接用这句话，不再由控制台自己翻译服务端英文。服务端没写这句话的条目保持原样。另外给新建/编辑记录弹窗加了钉子测试：带 userMessage 的 403（中英文）显示该原因，不带的仍显示通用的「你没有权限保存此记录」。
• 为什么改：执行维护者裁决「32440 选C，32043 一起按C处理」的第 3 层：服务端（feat(metadata-protocol): a metadata write's advisories and refusals come back in the caller's language (#32656, 1/2) #33276、fix(plugin-security): permission refusals speak the caller's language, falling back to the workspace default (#32656, 2/2) #33290）已按请求语言写好用户文案，控制台要直接渲染。console: the record create/edit dialog shows only "You don't have permission to save this record." on a controlled_by_parent master-edit refusal, dropping the API's reason ("requires edit access to its master record"); #7366 regression on this path #33524 实测：弹窗本来就先读 userMessage，HotCRM 看到通用句是因为 plugin-security 的「需要主记录编辑权限」拒绝根本没带 userMessage，那是服务端的缺口，本 PR 不改服务端。
• 风险与回滚：只改控制台读哪个字段来显示；没有 userMessage 的条目逐字不变。@object-ui/data-objectstack 的 MetadataValidationIssue 多一个可选字段（只加不减）。回滚即 revert。
• 先看：ui/packages/app-shell/src/providers/saveAdvisoryToast.ts 的 formatFinding；ui/packages/data-objectstack/src/metadata-error.ts 的 formatMetadataIssue；ui/packages/app-shell/src/views/studio-design/metadataError.ts 的 issueRefusal。
• 两分钟验证：pnpm --dir ui exec vitest run packages/app-shell/src/providers/AdapterProvider.advisoryUserMessage-32657.test.tsx，预期 3 个用例全绿，其中中文用例在真实 sonner 弹出的提醒里读到「权限集“sales_rep”的持有者只能看到……」，读不到英文 message。
• 需要你做的：无，席位落地（契约复审记录由席位补）。

What changes

Layer 3 of tracking #32654 (ruling C on #32440, 「32440 选C，32043 一起按C处理」): the console renders the user-facing text the producer composed in the request's language, with no per-code key table of its own.

• Advisory toast (saveAdvisoryToast.ts, formatFinding, @object-ui/app-shell). An advisory finding that carries userMessage (RuntimeAuthoringIssueSchema.userMessage, which the save and publish doors compose since feat(metadata-protocol): a metadata write's advisories and refusals come back in the caller's language (#32656, 1/2) #33276) renders as [rule] where — USER_MESSAGE, in place of the developer-facing English message and hint. The rule id and where are locators and frame both faces. A finding without one keeps [rule] where — message hint. The module header now says which prose is shown.
• The one issue reader (metadata-error.ts, formatMetadataIssue, @object-ui/data-objectstack). A 422 issue with userMessage renders • path — USER_MESSAGE; one without keeps • path — message. formatMetadataError and app-shell's formatPublishFailures both write issues through it, so the banners, the field designer's refusal and the publish-failure list follow.
• Studio's refusal sentence (metadataError.ts, issueRefusal). When the issue carries userMessage, the sentence's problem part is that text verbatim; only an issue without one has its English message read through translateValidationMessage, the console's own table. This is the console-side translation of server prose the ruling retires where the producer speaks.
• Type (metadata-client.ts). MetadataValidationIssue gains optional userMessage, typed RuntimeAuthoringIssue['userMessage'] from @objectstack/spec/api, so a rename in the spec stops it compiling. Published interface, optional member: Clause-②: yes (widening).
• Changeset .changeset/32657-console-localized-user-text.md: @object-ui/app-shell, @object-ui/console, @object-ui/data-objectstack patch, with both declaration lines.

The presence test is the same predicate in all three readers (a non-empty string after trimming, the rule @objectstack/client applies when it lifts userMessage). declaredUserMessage (@object-ui/react) is the one reader of an API ERROR's marking; it was not reused here because a finding element is not an error, @object-ui/data-objectstack sits below @object-ui/react (no import that way), and saveAdvisoryToast.ts imports nothing that renders by design.

Why

• console: render the localized userMessage and advisory text instead of substituting raw server prose (ruling C on #32440, layer 3) #32657 reproduced on origin/main e3f0cfd4: the toast never read advisories[].userMessage, formatMetadataIssue never read issues[].userMessage, and issueRefusal translated the English message console-side.
• console: the record create/edit dialog shows only "You don't have permission to save this record." on a controlled_by_parent master-edit refusal, dropping the API's reason ("requires edit access to its master record"); #7366 regression on this path #33524 did not reproduce in the console. The console's New and Edit buttons open ModalForm (app-shell console/AppContent.tsx), which rethrows a refused write into the components form renderer; its refusal reader takes declaredUserMessage(error) before the fixed form.noPermissionToSave line, as do FormPage.tsx's refusalText and the edit OCC path (occSave.tsx). The master-edit refusal reaches the console with no userMessage: plugin-security's masterEditDenied (security-plugin-cbp-write-gate.ts) throws a bare PermissionDeniedError whose message is the developer sentence "requires edit access to its master record", and fix(plugin-security): permission refusals speak the caller's language, falling back to the workspace default (#32656, 2/2) #33290 localized other refusals, not this one. So the generic line is the correct reading of what the server sends, and acceptance 1 and 2 of console: the record create/edit dialog shows only "You don't have permission to save this record." on a controlled_by_parent master-edit refusal, dropping the API's reason ("requires edit access to its master record"); #7366 regression on this path #33524 need the producer to compose a localized userMessage naming the master. That is a server change this PR does not make; the card stays open for it (seat ruling in the card thread).

Tests

• New AdapterProvider.advisoryUserMessage-32657.test.tsx (rendered end to end): the real AdapterProvider builds the real adapter, the real SDK client parses a save response from a fetch double, and the real sonner Toaster draws the toast; the assertions read the toast's text on screen.
  • a zh-CN userMessage (the security-private-no-readscope catalog sentence for these params) shows, with the rule id, and neither the English message nor hint shows;
  • an en userMessage shows the same way;
  • CONTROL: a finding without one keeps message + hint + rule.
• saveAdvisoryToast.test.ts: two cases added (the exact line with a userMessage; CONTROL: a blank one is no sentence).
• New metadataError.issueUserMessage-32657.test.ts: formatMetadataIssue with and without userMessage; formatMetadataError and formatPublishFailures carry it; flowSaveRefusal (through issueRefusal) carries a zh userMessage verbatim and not the console's translation, and CONTROL: an issue without one keeps the console's reading.
• New ModalForm.markedRefusal-33524.test.tsx (rendered; the dialog the console's New and Edit buttons open): the user types and presses the dialog's own Create or Update button, the data source refuses with a 403 shaped as the ObjectStack adapter throws it.
  • create and edit, each with an en and a zh-CN userMessage: the sentence shows, the generic line does not, the developer message does not;
  • CONTROL, create and edit: a 403 with no userMessage shows the generic line and withholds the developer message.

Red-first on base, and ablations

• Base. The four production files checked out at e3f0cfd4 (tree only), the new and edited tests kept: Test Files 3 failed, 1 passed (4); Tests 6 failed, 26 passed (32). The six reds are exactly the userMessage cases of the three console: render the localized userMessage and advisory text instead of substituting raw server prose (ruling C on #32440, layer 3) #32657 files; the controls passed. ModalForm.markedRefusal-33524.test.tsx passed on base, 6 of 6: the console: the record create/edit dialog shows only "You don't have permission to save this record." on a controlled_by_parent master-edit refusal, dropping the API's reason ("requires edit access to its master record"); #7366 regression on this path #33524 console half does not reproduce. Restored with git checkout HEAD --, git diff HEAD empty.
• Ablations through scripts/ablation-replace.mjs, each restored to the HEAD blob with git diff HEAD empty. ui vitest reads @object-ui/* from source, so no build sits between mutation and run.
  • A1 formatFinding's userMessage branch made unreachable: Tests 3 failed, 18 passed; the reds are the two rendered userMessage cases and the unit case; both controls green.
  • A2 formatMetadataIssue made to read message always: Tests 2 failed, 3 passed.
  • A3 issueRefusal's userMessage branch made unreachable: Tests 1 failed, 4 passed.
  • A4 (the console: the record create/edit dialog shows only "You don't have permission to save this record." on a controlled_by_parent master-edit refusal, dropping the API's reason ("requires edit access to its master record"); #7366 regression on this path #33524 pin's bite) the form renderer's refusal reader made to answer the generic line for any permission error before declaredUserMessage: Tests 4 failed, 2 passed; the four marked cases red, the two CONTROLs green. The first A4 attempt passed a two-line anchor and was refused before running anything; it was rerun with a one-line anchor.

Acceptance notes

• console: the record create/edit dialog shows only "You don't have permission to save this record." on a controlled_by_parent master-edit refusal, dropping the API's reason ("requires edit access to its master record"); #7366 regression on this path #33524 is referenced, not closed. Its console half is pinned with no console change (above). Its producer half, plugin-security's master-edit refusal composing a localized userMessage that names the master, is reported to the seat as a server finding; the seat re-lanes the card.
• Studio: an unconfigured nav item vanishes from the navigation editor after reload while still counted as a pending draft; publish dialog shows raw type names in zh #32440's post-save advisory half is met by this PR: the advisory toast now renders the producer's localized sentence wherever the save door sends one. Rules the producer has written no sentence for still show their English message and hint, as the contract declares (the remaining catalogue is tracked on lint: every save-door advisory rule carries a localized user sentence (67 rule ids in 36 rule files remain after the security posture), per ruling C on #32440 #32835).
• console: the invite dialog names the Developer Edition member limit when cloud refuses DEVELOPER_ORGANIZATION_MEMBER_LIMIT_REACHED #32043's member-limit sentence is not met by this PR: that refusal (DEVELOPER_ORGANIZATION_MEMBER_LIMIT_REACHED) is produced by cloud. If cloud sends it with a userMessage, the invite dialog's reader decides what shows; this PR did not measure that dialog.
• Other write-error readers. Several console surfaces read a write error through extractWriteErrorMessage alone (for example the sharing-rule clone dialog and the position and assigned-user sections), which reads the server's error / message and not userMessage. Noted, not changed here: outside this card's declared surface.
• File surface: as declared to the seat (the four production files above, their tests, one new plugin-form test, the changeset). No i18n key, no FormPage.tsx or flowResponse.ts edit, no server, spec or cloud change.

Verification

Run on head e0302529 (base origin/main e3f0cfd4).

Build, tests, type-check and lint

• Builds under the verify lock: pnpm --workspace-concurrency=2 --filter '@objectstack/spec...' --filter '@objectstack/formula...' --filter '@objectstack/client...' --filter '@objectstack/lint...' --filter '@objectstack/sdui-parser...' build (VERDICT command-exit 0), then pnpm --workspace-concurrency=2 --filter '@object-ui/app-shell^...' build (VERDICT command-exit 0).
• The four new or edited test files: Test Files 4 passed (4), Tests 32 passed (32).
• Neighbouring suites, pnpm --dir ui exec vitest run --maxWorkers=2 packages/data-objectstack/ packages/app-shell/src/providers/ packages/app-shell/src/views/studio-design/ packages/plugin-designer/src/MetadataFieldsPage.refusalIssues-11302.test.tsx packages/plugin-form/src/ModalForm packages/components/src/__tests__/form-write-error-message.test.tsx: Test Files 499 passed (499), Tests 4343 passed (4343).
• Type-check, each VERDICT command-exit 0: pnpm --filter @object-ui/data-objectstack run type-check (tsc --noEmit), pnpm --filter @object-ui/app-shell run type-check and pnpm --filter @object-ui/plugin-form run type-check (both tsc --noEmit && tsc -p tsconfig.test.json, so the new test files are compiled).
• eslint on the eight changed files: 0 errors (8 warnings, all pre-existing no-explicit-any lines in metadata-client.ts). pnpm --dir ui run check:new-line-citations: 0 new citations.

Derived gates (37)

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 37 families on e0302529. All 37 exited 0. pnpm --dir ui exec vitest run scripts/ was SIGKILLed in the loop while a 23-minute suite run held the box; rerun alone under the lock with --maxWorkers=2: Test Files 171 passed, 2 skipped (173), exit 0. --ran reconciliation: 37 derived, 37 run, 0 NOT-MEASURED. Changed lines: 446, under the 3,000 threshold. No dogfood battery: no ! in the title and no (narrowing) arm.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic.
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes.
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: its generated artifacts are regenerated and committed.
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English.
• The Before Submitting list in CONTRIBUTING.md is done.

Development by the card thread session_01FEkQ5m1xDT63aCaQJNjwXD for the seat domain:ui#2.

---

Generated by Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_01FEkQ5m1xDT63aCaQJNjwXD

[objectstack-fleet]

domain:ui#2 · os-project-manager · session_01FEkQ5oF8GgTHN2jBZoDwz8

Contract review

Served-tier: TIER_DEFAULT
Head-sha: e030252941226b20d688116cb55785eb34621455
Local-runs: none

Inputs: card #32657 (body, all 4 comments, including claim amendment 6886423383 that sets Clause-②: yes (widening) on MetadataValidationIssue.userMessage), card #33524 (body, both comments, including the premise correction), the PR #33576 body, its 9-file list and net diff against main, and the head's check-runs. Files read at the head and at main with git show only.

① Derived judgments

The diff makes five accept-set or public-surface changes. Each is judged below.

1. MetadataValidationIssue gains optional userMessage?: RuntimeAuthoringIssue['userMessage'] (ui/packages/data-objectstack/src/metadata-client.ts, barrel-exported from src/index.ts). Right: a pure widening. On main, RuntimeAuthoringIssueSchema.userMessage is z.string().optional() (packages/spec/src/api/protocol.zod.ts), and RuntimeAuthoringIssue is its z.input. The indexed type therefore resolves to string | undefined, and the member is optional. Objects built without it still type-check, and existing readers see one more optional key. The runtime parser stores issues unmapped (metadata-client.ts, the err.issues = issues lift), so the field the server sends reaches MetadataError.issues with no further change. The only type that newly fails to compile is a caller value carrying a non-string userMessage. That is theoretical, and the spec forbids it. Nothing is removed or renamed.
2. Type import from @objectstack/spec/api. Right: a legitimate edge, and not a new one. @objectstack/spec is already a dependencies entry (workspace:^) of @object-ui/data-objectstack. The import type { …, RuntimeAuthoringIssue } from '@objectstack/spec/api' line is byte-identical on main (it already types advisories/readSaveAdvisories). The diff adds only a use of it. The import is type-only and erased, and ./api is a declared subpath export of the spec. No package.json change is needed, and the diff makes none.
3. Rendering prefers userMessage over message (and over hint in the toast) in formatFinding (app-shell saveAdvisoryToast.ts), formatMetadataIssue (data-objectstack metadata-error.ts, and through it formatMetadataError and formatPublishFailures) and issueRefusal (app-shell studio-design/metadataError.ts). Right; no relied-on content is lost. This is the behaviour the spec contract prescribes: "absent, a consumer renders message as before. Consumers render it as received; rule stays the stable id and message / hint stay the developer-facing text". It is also ruling C on Studio: an unconfigured nav item vanishes from the navigation editor after reload while still counted as a pending draft; publish dialog shows raw type names in zh #32440. Details:
   • The locators stay on both faces: [rule] where in the toast, and path in the issue line.
   • Machine readers are unaffected, because issues[] and advisories[] are not mutated.
   • CLI, MCP and os validate are untouched.
   • What a person no longer sees is the English developer message (and the toast's hint), for findings that carry a userMessage. That includes the Studio Details disclosure, which is also built by formatMetadataError. This is the ruling's intent: the producer's sentence is the user channel. Should-know, not a defect: an admin who wants the English prose now has to read the network response.
   • The issueRefusal change retires the console-side translateValidationMessage reading only where the producer spoke. Issues without a sentence (every spec-validation issue) keep the old reading.
4. Empty/whitespace guard (typeof x === 'string' && x.trim() !== '', the same in all three readers). Right.
   • It is the same predicate @objectstack/client applies when it lifts an API error's userMessage (asUserMessage, packages/client/src/index.ts), and the one @object-ui/react's error-message.ts reader uses.
   • A blank sentence falls back to message (plus hint). This is pinned by the saveAdvisoryToast.test.ts CONTROL.
   • A non-blank sentence is rendered untrimmed, which matches the spec's "render it as received".
   • The typeof check also guards a non-string value that reaches a cast issues array at runtime.
5. ModalForm.markedRefusal-33524.test.tsx (plugin-form). Right: tests only, no product change. It pins the existing declaredUserMessage-before-generic-line reading on create and edit, in en and zh-CN, plus CONTROLs. The PR's red-first record states that it passes on base, which matches the corrected premise of console: the record create/edit dialog shows only "You don't have permission to save this record." on a controlled_by_parent master-edit refusal, dropping the API's reason ("requires edit access to its master record"); #7366 regression on this path #33524.

No must-fix and no should-fix finding in the diff.

② Semver level

The changeset .changeset/32657-console-localized-user-text.md bumps @object-ui/app-shell, @object-ui/console and @object-ui/data-objectstack at patch, with Clause-②: yes (widening) and Metadata-protocol: none as line-initial declarations in both the changeset and the PR body. Matches.

• Packages. The diff changes production code in app-shell (2 files) and data-objectstack (2 files). @object-ui/console is listed correctly: it is a published package that ships a pre-built SPA bundling @object-ui/app-shell (workspace:*), so its shipped bytes change. @object-ui/plugin-form gains only a test file and publishes nothing new, so it is correctly absent.
• Level. Under AGENTS.md Post-Task Checklist step 3 the level follows the Metadata-protocol kind alone: none takes patch, and "a non-protocol change, widening or breaking, ships patch". The earlier "Clause-② yes ⇒ ≥ minor" rule (gate census, 2026-09) is superseded by that text on main.
• Metadata-protocol: none. Correct. Nothing a metadata author writes changes; only which server field the console renders changes.
• Clause-②: yes (widening). Correct. A new optional member on an exported interface widens the public surface and narrows nothing. It agrees with the claim amendment on console: render the localized userMessage and advisory text instead of substituting raw server prose (ruling C on #32440, layer 3) #32657.
• No breaking banner or ADR-0087 marker. Correctly, none is needed.

③ Boundary flags

• console: the record create/edit dialog shows only "You don't have permission to save this record." on a controlled_by_parent master-edit refusal, dropping the API's reason ("requires edit access to its master record"); #7366 regression on this path #33524 / plugin-security masterEditDenied. Answered.

  • Confirmed on main: packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts (~L463) builds the master-edit denial with no userMessage. That is a producer gap, outside the ui lane.
  • The PR correctly says Refs #33524, not Fixes. It ships pins only.
  • The dev reported the server half as an out-of-scope finding, with carrier console: the record create/edit dialog shows only "You don't have permission to save this record." on a controlled_by_parent master-edit refusal, dropping the API's reason ("requires edit access to its master record"); #7366 regression on this path #33524. The claim amendment commits the seat to release console: the record create/edit dialog shows only "You don't have permission to save this record." on a controlled_by_parent master-edit refusal, dropping the API's reason ("requires edit access to its master record"); #7366 regression on this path #33524 to triage with pm:retriage after merge, so it can be re-laned to domain:server. Escalated to the seat: that release is owed after merge.

• Studio: an unconfigured nav item vanishes from the navigation editor after reload while still counted as a pending draft; publish dialog shows raw type names in zh #32440 (open). Answered. Its post-save advisory half is met wherever the save door sends a userMessage. The PR does not close Studio: an unconfigured nav item vanishes from the navigation editor after reload while still counted as a pending draft; publish dialog shows raw type names in zh #32440, which is correct. The remaining rule catalogue without user sentences is tracked on lint: every save-door advisory rule carries a localized user sentence (67 rule ids in 36 rule files remain after the security posture), per ruling C on #32440 #32835 (open).

• console: the invite dialog names the Developer Edition member limit when cloud refuses DEVELOPER_ORGANIZATION_MEMBER_LIMIT_REACHED #32043 (open). Escalated. The member-limit sentence is produced by cloud (DEVELOPER_ORGANIZATION_MEMBER_LIMIT_REACHED), so this PR does not meet it. The PR states that it did not measure whether the invite dialog reads a userMessage. console: render the localized userMessage and advisory text instead of substituting raw server prose (ruling C on #32440, layer 3) #32657's own text routes this to a repo:cloud card once layer 1 has landed. The seat should file or confirm that card, and record the open question about the invite dialog's reader on tracking Platform: user-facing refusal and advisory text comes back in the request's language, composed by its producer (ruling C on #32440, #32043) #32654. This does not block this PR.

• Other extractWriteErrorMessage-only readers (sharing-rule clone dialog, position and assigned-user sections, inline edit saves, …). These are noted in the PR and fall outside the declared file surface; no carrier was filed. Escalated to the seat as a candidate domain:ui card under Platform: user-facing refusal and advisory text comes back in the request's language, composed by its producer (ruling C on #32440, #32043) #32654. This does not block this PR.

• File surface. The diff matches the claim amendment: four production files, their tests, one plugin-form test and the changeset. There is no FormPage.tsx, flowResponse.ts, i18n, spec, server or cloud edit.

• Gates as at render. 60 check-runs on the head:

  • 10 completed success, including Check Changeset, PR-body guards, Governed Surface Queue Guard, Check PR Size, Test Core, Build UI Deps and Dogfood Regression Gate.
  • 17 completed skipped (opt-in, matrix placeholders or not applicable).
  • 33 in progress: Type Check ×5 (including UI), Test UI 1–16/16, Live E2E UI, Build & E2E UI, Lint ×9 and the second Check Changeset.
  • 0 failed.

  These are the gate verdicts. The ones still running decide landing; they do not decide this contract verdict.

• The PR is still a draft (draft: true, mergeable_state: blocked) at render. The seat undrafts it once the gates are green.

Implemented-by: claude/project-thread-bhbxol
Reviewed-by: session_01FEkQ5oF8GgTHN2jBZoDwz8

VERDICT: PASS