feat(spec): ActionParamSchema.carryOver — seeded from the row, rendered read-only, submitted verbatim (#11992)

[os-zhuang]

Fixes#11992

Spec half of the #11753 ruling (maintainer 2026-08-25, verbatim 「同意」 on recommendation A; full record = #11753 comment 5404887360). Parent #11753 remains open (tracking); the objectui renderer leg is its downstream card and is not addressed here.

Pre-measurements (both named by the card; both gate the design)

1. Can objectui's ActionParamDialog carry a read-only-summary render for a param it must still submit? — YES, no renderer surgery. Measured read-only in the local objectui checkout (586cfc2baa4e, zero objectui edits):

• Seeding is upstream of rendering: packages/app-shell/src/utils/resolveActionParams.ts resolves defaultFromRow into defaultValue (defaultValue: rowDefault ?? param.defaultValue), and ActionParamDialog seeds its values state from param.defaultValue on open.
• Submission reads the values STATE, never the DOM: handleSubmit resolves serializeParamValues(visibleParams, values). A param rendered as a read-only summary instead of an editable widget keeps its seeded value in values and is submitted verbatim.
• The renderer leg is therefore a bounded declaration-honouring change: a one-key passthrough in resolveActionParam (its output object is explicit-key, not a spread) plus a render branch in the dialog, plus the dialog-level render pin the ruling names. packages/types/src/ui-action.ts derives its authoring keys by reference from z.input of the spec's ActionParamSchema, so the new key flows into the authoring type automatically.

Fallback B (objectui-only collapsed summary) is NOT taken — the measurement does not point there.

2. Population sweep — every shipped defaultFromRow param bound to a JSON-serialized column (identities, not counts). Swept every shipped file declaring defaultFromRow params (repo-wide grep: 2 in plugin-security, 9 in platform-objects/identity; plugin-approvals declares none — config-borrow only):

• sys_permission_set.clone_permission_set: object_permissions, field_permissions, system_permissions, row_level_security, tab_permissions — all five are Field.textarea columns written with JSON.stringify by permissionSetRowFields(). This is the entire population.
• Every other shipped defaultFromRow param binds a scalar column: sys_permission_set.description + sys_position.description (text), sys_account.accountId (id), sys_invitation.email/role, sys_member.role, sys_oauth_application.client_id (4 actions), sys_organization.name/slug/logo (url), sys_sso_provider.providerId/domain, sys_team_member.teamId/userId, sys_team.name, sys_user.name/image (url). sys_approval_request declares no defaultFromRow param (config-borrow only).

So the exemplar set below is exactly the population the key serves today.

What this PR does

• ActionParamSchema.carryOver (packages/spec/src/ui/action.zod.ts): one CLOSED optional boolean expressing the ruled contract — seed from the row, render as a non-editable summary, submit verbatim — stated in full in the key's .describe(). Measured constraint restated from the parent: visible: false is NOT this contract (it omits the param from the submission entirely).
  • Parse-time co-requirement: carryOver: true refuses without defaultFromRow: true (path carryOver; the message carries the repair and the bodyExtra alternative). A carry-over with no row seed would render an empty locked control and submit nothing — the The clone_permission_set action copies only 2 of the 6 definition facets, so a clone silently drops system permissions, RLS and tab permissions #11703 silent-drop shape reintroduced through the key added to close it.
  • Aliases: readonly / disabled (the words option A itself used, borrowed from FieldSchema / widget vocabulary) are refused with guidance naming carryOver — a field's readonly means write-path strip, exactly the wrong half here.
• Exemplar (packages/plugins/plugin-security/src/objects/sys-permission-set.object.ts): the five clone_permission_set JSON facet params declare carryOver: true, riding this PR per the card. description deliberately stays editable — it is prose, not a permission facet; the objectui leg / The Clone dialog for a permission set now offers five raw JSON blobs as editable inputs — defaultFromRow has no non-editable carry-over #11753 can revisit if the ruling's "two ordinary inputs" is read to include it.
• Pins:
  • packages/spec/src/ui/action-param-carryover.test.ts (9 tests): accept set + parsed-output carry, the defaultFromRow co-requirement (both directions, message content), alias prescriptions, and the .describe() three-semantics contract.
  • packages/plugins/plugin-security/src/objects/clone-carryover.test.ts (7 tests): the five facets BY NAME declare the key, description does not, and every clone param parses under ActionParamSchema.
  • The clone_permission_set action copies only 2 of the 6 definition facets, so a clone silently drops system permissions, RLS and tab permissions #11703 pin 6 (send-side) stays green untouched — packaged-permission-set-lock.test.ts passes unmodified; carryOver changes what the dialog renders, never what it sends (its clonePayload reads only field/name/defaultFromRow).
• Generated baselines: packages/spec/authorable-surface/ui.json gains ui/ActionParam:carryOver (via gen:schema in the spec build); content/docs/references/ui/action.mdx regenerated (gen:docs). check:liveness green with no ledger edit — action/params is a RECORDED undrilled container (child keys inherit its blanket verdict); gen:liveness-counts produced no diff.
• Changeset: @objectstack/specminor (new authorable key — accept-set expansion, adr-0087 not-required, same class as the onSuccess precedent 07e630e58), @objectstack/plugin-securitypatch (metadata declaration on an existing action, same class as The clone_permission_set action copies only 2 of the 6 definition facets, so a clone silently drops system permissions, RLS and tab permissions #11703's changeset).

Verification

All at final head 3986bafea (branch includes a clean merge of current origin/main = d7b3963c2, i.e. after landing-watch #12612/#12611 — disjoint files; spec rebuilt at the merged head before every reading below):

• pnpm --filter @objectstack/spec build (gen:schema + gen:openapi + tsup + dts) — exit 0, check-dts-emitted: 34/34.
• Pins at 3986bafea: spec src/ui/action-param-carryover.test.ts + src/shared/alias-integrity.test.ts + src/ui/action-on-success.test.ts — Tests 48 passed (48); plugin-security src/objects/clone-carryover.test.ts + src/packaged-permission-set-lock.test.ts + src/objects/rbac-objects.test.ts — Tests 46 passed (46).
• Typechecks at 3986bafea: both packages exit 0 (spec's includes its check:test-typecheck half; tsc -p tsconfig.test.json --listFiles counts the new spec test file in that program — 1 hit).
• Reverse verification, expected-direction stated first then observed: expected RED from an unknown-key plant. Observed: tsc stayed GREEN (plugin-security's tsconfig excludes **/*.test.ts and its action literals do not surface excess-property checks for this key — the compile-time gate does not police this surface); the STRICT PARSE gate went RED exactly as required — planting carryOverX: true on one exemplar param (mutation proven on disk: anchored grep -c 0→1) failed clone-carryover.test.ts at module load with unrecognized_keys naming carryOverX and suggesting carryOver. So declared=enforced is carried by the schema at object-definition time, not by tsc. Restore via git checkout HEAD -- FILEPATH (absolute path), proven by empty git diff HEAD + grep 0.
• Derived gate union (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, derived at 3986bafea): 45 path-derived + convention-triggered families run locally — all exit 0 with their own verdict lines (check:authorable-surface, check:generated "All 14 generated artifacts are up to date", check:liveness, check:i18n "OK (9 packages)", check:skill-examples "260 prose examples type-check", check:nul-bytes "OK", alias/docs/changeset families, check:engine-double-contract, check:where-matcher, check:cross-package-test-inputs, check:type-check-coverage structural half, …), except two declared narrowings:
  • check:type-check-debt --re-measure refuses on this worktree (39 workspace deps of OTHER ledger entries unbuilt — its own designed refusal, NOT MEASURED ≠ red). Narrowed measurement taken instead: the only ledger entry this diff can move is TEST_DEBT @objectstack/plugin-security; with tests included in that package's own tsconfig program, error count is 13 with and 13 without the new test file (0 lines name it) — delta 0, no upward drift possible from this diff. The spec .d.ts change is an additive optional key (can only remove excess-property errors, never add).
  • node scripts/check-dev-prereqs.mjs — prerequisite not met (11 unrelated packages, studio/connectors, unbuilt in this worktree); it measures checkout build state, not the diff; CI's lint job builds the workspace before it.
• check:liveness needs no ledger edit: action/params is a RECORDED undrilled container (its baseline covers new child keys); gate green, counts unchanged.

Clause-② (contract-review tier): this PR widens the authorable public surface — staying DRAFT for maintainer review; no ready-flip, no auto-merge.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/plugin-security, @objectstack/spec, touching 8 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/spec/authorable-surface/ui.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/permissions/authorization.mdx(via system_permissions (literal), tab_permissions (literal))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx(via ActionParamSchema (symbol))
• content/docs/releases/v17.mdx(via ActionParamSchema (symbol), system_permissions (literal), tab_permissions (literal))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/authorable-surface/ui.json) — pages documenting those are invisible to this run
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 129 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json d7b3963c2d4f2b8f043f04fa708d54f642bd97e9 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from fde0e515b92cf59ec66f4c133a9fb9665e1c1c31 — the merge of head 3986bafead79b57041d6e33c7344005bd6608d1f into base d7b3963c2d4f2b8f043f04fa708d54f642bd97e9, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin fde0e515b92cf59ec66f4c133a9fb9665e1c1c31 && git checkout fde0e515b92cf59ec66f4c133a9fb9665e1c1c31
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d7b3963c2d4f2b8f043f04fa708d54f642bd97e9 3986bafead79b57041d6e33c7344005bd6608d1f && git checkout -B drift-repro d7b3963c2d4f2b8f043f04fa708d54f642bd97e9 && git merge --no-ff 3986bafead79b57041d6e33c7344005bd6608d1f
node scripts/docs-audit/affected-docs.mjs --json d7b3963c2d4f2b8f043f04fa708d54f642bd97e9

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs d7b3963c2d4f2b8f043f04fa708d54f642bd97e9 → pass the list as
args.docs, on the commit named under Which tree this was computed on.