feat(spec): page:header placedActions draws every placed header action, refused beside an actions list (#30018) - #30028

📓 Docs Drift Check

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

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

• content/docs/protocol/objectui/layout-dsl.mdx (via placedActions (symbol, a field of const object PageHeaderProps, an authorable key of ui/PageHeaderProps), placedActions (literal, a string literal in PAGE_HEADER_PLACED_ACTIONS_BESIDE_LIST))
• content/docs/ui/pages.mdx (via placedActions (symbol, a field of const object PageHeaderProps, an authorable key of ui/PageHeaderProps), placedActions (literal, a string literal in PAGE_HEADER_PLACED_ACTIONS_BESIDE_LIST))

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

• content/docs/releases/v17/17-6.mdx (via PageHeaderProps (symbol, a top-level const object))

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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 7f3e4eadbbd9f1cfa03a29d5de1868f2847e8144 && git checkout 7f3e4eadbbd9f1cfa03a29d5de1868f2847e8144
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 140d8ce805dc55245d9841a6ece6dfb956d9e071 371cb0fd9d323a0cc3c3b536831c10fab7ec78b4 && git checkout -B drift-repro 140d8ce805dc55245d9841a6ece6dfb956d9e071 && git merge --no-ff 371cb0fd9d323a0cc3c3b536831c10fab7ec78b4

node scripts/docs-audit/affected-docs.mjs --json 140d8ce805dc55245d9841a6ece6dfb956d9e071

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 140d8ce805dc55245d9841a6ece6dfb956d9e071 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:spec#2 · os-support-ai · session_01WGufzhJG3tKnksHVa1krBz

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 371cb0fd9d323a0cc3c3b536831c10fab7ec78b4
Local-runs: none
Scope: packages/spec/src/ui/component.zod.ts, skills/objectstack-ui/rules/pages.md + packages/spec/src/shared/strict-object.ts, packages/spec/src/shared/refinement-projection.ts, packages/lint/src/validate-component-props.ts, packages/spec/scripts/liveness/check-liveness.mts, packages/spec/src/ui/page.zod.ts, ui/packages/components/src/renderers/layout/containers.tsx, skills/objectstack-ui/evals/views-apps-actions-pages.json, scripts/check-changeset-no-major.mjs

Inputs read: card #30018 (body, the claim 6624302286, triage 6624681862, os-dev-report 6626669313), the ruling 6624172200 on #29951, PR #30028 (body, 12-file list, net diff origin/main...371cb0fd, merge-base 63b86b38), and the check-runs on the head. The rest of the diff (changeset, docs, generated reference, authorable-surface/ui.json, dropped-refinements.baseline.json, liveness/page.json, the two test files, the one ui/ line) is the lane seat's ACCEPT at TIER_DEFAULT; it was read where the hits hunks make a claim about it, not reviewed.

① Derived judgments

• Accept-set, ui/PageHeaderProps: widened by one key. placedActions: z.boolean().optional(), no default. Right: on main the closed shape (strictObject → closedObject(z.object(...).strict())) refuses the key as unknown, so nothing that parsed before is refused now. The pair placedActions: true + actions moves from an unrecognized_keys refusal (rule component-props-unknown-key) to a custom refusal at placedActions (rule component-props-invalid); still refused, a different door, not a narrowing. Clause-②: yes (widening) is the right reading.
• placedActions: false beside a list is accepted. Right against the ruling: false asserts nothing the list does not, and refusing it would make the key a presence switch rather than a value switch.
• No schema default. Right, and load-bearing: maxVisible in the same shape records the rule (an unset key must stay unset so a parsed header does not become an authored one); the renderer on main (PageHeaderRenderer, containers.tsx) reads no placedActions, so a materialised false would be noise in every stored page.
• Public surface: authorable-surface/ui.json +1 row ui/PageHeaderProps:placedActions. Right; the generator enumerates .shape, which a zod 4 .refine() keeps (same-file precedent: ElementButtonPropsSchema is a strictObject(...).refine(...) chain, and the new describe-marker test reads .shape.placedActions).
• Published JSON Schema ui/PageHeaderProps is wider than the runtime on the pair; ledger row ui/PageHeaderProps site "" added, totals 250→251 / 1018→1019. Right: the rule is value-conditional (true arms it). The closed list in shared/refinement-projection.ts has five arms (required-one-of, non-blank-string, dependent-required, banned-keys, banned-key-pattern); dependent-required is presence-only by its own docblock, and a presence-based "not both" would refuse false + list, which the runtime accepts, so no arm is exact. Dropped and annotated is the correct outcome, not a shortcut.
• First consumer, @objectstack/lint validateComponentProps. It safe-parses ComponentPropsMap['page:header'] (the refined instance, pinned by the toBe(PageHeaderProps) test) and maps a non-unrecognized_keys, non-retired issue to component-props-invalid at ${base}.${issue.path}, so the finding lands at properties.placedActions with the schema message. The lint test pins exactly that. Right.
• Liveness. No ledger row is possible (component-level keys sit under the undrilled page/regions container; _note on main says so for three earlier keys). The describe opens [PLANNED — not yet rendered], which check-liveness.mts MARKER_RE.planned (/\[planned|.../i) reads as planned; the _note PLANNED RECORD names the carrier (console(record header): a url action placed at record_header on sys_user no longer renders in the 18.3 Console header menu, drawer or full page (18.2 rendered it) #29951 ui half). The Spec property liveness check-run on the head is green. Right.
• One ui/ line. UNPUBLISHED_EXEMPTIONS['page:header.placedActions'] in the console parity test books a spec key no registration input publishes; the key format matches the map's existing type.key entries. Within the ruling (spec half first; the ui half strikes it). Lane ACCEPT, noted here only because the liveness note cites it.

② Semver level

• Changeset .changeset/30018-page-header-placed-actions.md: @objectstack/spec minor, @objectstack/skills minor, with Clause-②: yes (widening) and Metadata-protocol: added in both the PR body and the changeset. Matches what the diff publishes: a new authorable key on a published schema and a new authorable-surface row (added is required; the dev's none control exits 1 for that reason).
• @objectstack/skills minor rather than the patch that skills-only changesets on main carry: right here. check-changeset-no-major leg 3 counts skills/** as a file @objectstack/skills's build copies into what it packs, and under a declared Clause-②: yes it refuses a moved package graded patch; the patch precedents are Clause-②: no PRs. Check Changeset is green on the head.
• No 18.3.x note, per the maintainer amendment 「18.3.x 不发」; the card says the release note rides with the release that carries A. Right.
• Clause-②: line: yes (widening) — the PR body, the changeset and the diff agree.

③ Boundary flags

• open_questions: none. Nothing to escalate from the dev.
• Dev flag: the one ui/ line. Answered above: it is a test-ledger booking, not a renderer read, and the ruling's sequencing ("spec half first, then the ui reader") is exactly what makes it necessary. Accepted.
• Dev flag: skills/objectui/guides/page-builder.md line 101 lists breadcrumb on page:header. Verified in the tree at main: the guide names breadcrumb in the title row, and PageHeaderProps.breadcrumb is a retiredKey tombstone the closed shape refuses (spec 17, ADR-0087 D2). Real, out of this card's scope, not blocking; it belongs on its own card. Escalated to the seat to file; the dev left it untouched, which is the right call.
• Dev flag: Skills-docs: follow-up #29951. Accepted: no renderer reads the key, so an eval that asks for placedActions would teach a key that draws nothing today. The existing eval views-apps-actions-pages.json still expects the declared action id in properties.actions, which the new catalogue row keeps as its first alternative.
• Deviation: PR attribution links the card thread rather than the seat thread. Bookkeeping; no effect on the tree.
• Qualifier ledger for console(record header): a url action placed at record_header on sys_user no longer renders in the 18.3 Console header menu, drawer or full page (18.2 rendered it) #29951. The PR names six "not drawn yet" sites (describe marker, _note sentence, parity exemption, pages.mdx, layout-dsl.mdx, pages.md). Verified each is in the diff; the ui half must drop all six. Recorded here so the next card's reviewer can count them.

④ Design judgment

packages/spec/src/ui/component.zod.ts — judged against ruling 6624172200 letter A and the first consumer (validateComponentProps).

• Ruling A asks for one explicit opt-in on page:header that draws every action placed at record_header / record_more, read live, in place of an authored id list, with actions keeping its PageHeaderProps.actions declares z.array(z.string()) but objectui's canonical page:header renderer consumes ActionDef objects — satisfying the schema deletes every header button #11592 meaning, and spelling plus exclusivity as the seat's call, named in the PR. The tree delivers that: one boolean key placedActions; the describe states the live read and the two locations; the actions docblock and describe still say an authored list is the whole set and an omitted key draws none, now with the one addition "unless it sets placedActions: true"; the .refine refuses true beside a list (an empty list included: [] is "draw none" under PageHeaderProps.actions declares z.array(z.string()) but objectui's canonical page:header renderer consumes ActionDef objects — satisfying the schema deletes every header button #11592, which contradicts "draw every placed one"); the message names both keys and says keep one. The PR body's 维护者速读 names the spelling and the refusal, so the ruling's "named in the PR for the maintainer" condition is met.
• Tried to break it: (a) placedActions: 'true' + list: the type issue lands at placedActions, the predicate reads === true so it adds nothing and cannot throw on a non-object payload (the refine runs on the parsed object). (b) placedActions: true + a retired key: the terminal unknown-key refusal of closedObject fires; the pair rule is moot. (c) A consumer calling .extend / .pick on PageHeaderProps would lose the check in zod 4; no consumer on main does (every use is parse / safeParse, plus .shape reads by the generators). (d) The refusal prose carries no tracker number (the docblock's ruling-record citation is a comment, not runtime text). (e) defineStack never parses properties, so the only doors are the lint rule and the page save door, both of which read ComponentPropsMap; the test that pins ComponentPropsMap['page:header'] === PageHeaderProps is what keeps the refine from being bypassed by a stale map entry.
• Design holds. No must-fix. No should-fix.

skills/objectstack-ui/rules/pages.md — judged against the card's eval (the skill's views-apps-actions-pages.json on main; the card itself names no eval) and the spec it teaches on main.

• The page:header catalogue row now reads actions (ids of the bound object's actions, never action nodes) or placedActions: true (all placed; not drawn yet). Against the spec on the head that is accurate on every clause: the two are exclusive ("or"), true is the spelling, and the qualifier matches the describe marker. The eval's expected output (the declared id in properties.actions, no sibling action node) is still what the row teaches first.
• The clause paid for the row, "and a full page with no regions" in the print paragraph, names a refusal the spec does make (page.zod.ts checkPagePrintComposition, "print needs the document's blocks in regions"). After the edit the paragraph still states the condition ("Only a kind: 'full' page ... with its blocks in regions may declare it"), and no eval pins the deleted clause; the ratchet has zero headroom on this file, so the trade is a fair one and leaves nothing untrue. Observation only, not a finding.
• Design holds. No must-fix. No should-fix.

Check-runs on the head at the time of this record: 24 success, 7 skipped, 0 failure, 31 in progress (Build Core, Build & E2E UI, Live E2E UI, Test Core 1-8, Test UI 1-16, Lint & Repo Gates, Lint UI, Type Check UI, Type Check · workspace). Completed and green include Check Changeset, Governed Surface Queue Guard, PR-body guards, Spec property liveness, Dogfood Regression Gate, Check PR Size, Check Documentation Links, Flag docs affected by code changes, Build Docs, Build UI Deps and the scoped Lint / Type Check source-gate jobs. Nothing has concluded red. The verdict below is the contract verdict on the tree; the derived gates still running are the lane seat's merge condition.

Implemented-by: claude/project-thread-i7bk4t
Reviewed-by: session_01WGufzhJG3tKnksHVa1krBz

VERDICT: PASS

domain:spec#2 · os-support-ai · session_01WGufzhJG3tKnksHVa1krBz

席位核对 — ACCEPT · domain:spec#2 · head 371cb0fd9d323a0cc3c3b536831c10fab7ec78b4

• Shape: page:header gains placedActions: z.boolean().optional() (no default). true draws every action of the bound object placed at record_header / record_more, read live; omitted or false leaves the authored actions list in charge with its PageHeaderProps.actions declares z.array(z.string()) but objectui's canonical page:header renderer consumes ActionDef objects — satisfying the schema deletes every header button #11592 meaning. placedActions: true beside an authored actions list (including []) is refused at properties.placedActions, naming both keys; false beside a list is accepted. The key carries [PLANNED — not yet rendered] until the ui reader lands (console(record header): a url action placed at record_header on sys_user no longer renders in the 18.3 Console header menu, drawer or full page (18.2 rendered it) #29951). One dropped-refinements row (value-conditional rule), one UNPUBLISHED_EXEMPTIONS line in the ui registry-inputs parity test, docs and the objectstack-ui pages rule. 12 files, +230 −15.
• Ruling: A on console(record header): a url action placed at record_header on sys_user no longer renders in the 18.3 Console header menu, drawer or full page (18.2 rendered it) #29951 (6624172200, maintainer 「以上同意」): one explicit opt-in, the list keeps its whole-set meaning, spelling and exclusivity are the spec seat's call. The seat's calls (placedActions: true; refused beside a list) are in the order and the PR body's 维护者速读; the one ui/ test line is the seat's fork ruling A.
• Contract review: record 6626813985 (CONTRACT_REVIEW_TIER, head 371cb0fd, PASS, no must-fix, no should-fix).
• Declarations: Clause-②: yes (widening), Metadata-protocol: added, @objectstack/spec minor + @objectstack/skills minor; Skills-docs: follow-up #29951. Nothing ships in 18.3.x for this (maintainer, 2026-11-04T06:24Z).
• Gates: every check-run on the head is complete: 58 success, 7 skipped, none red.
• Handoff: console(record header): a url action placed at record_header on sys_user no longer renders in the 18.3 Console header menu, drawer or full page (18.2 rendered it) #29951's ui half strikes the exemption line and the six "not drawn yet" qualifiers the PR lists. Out-of-scope finding, to be filed separately: skills/objectui/guides/page-builder.md still teaches the retired page:header key breadcrumb.
• Landing: ⛔ GOVERNED, Tier H. skills/objectstack-ui/rules/pages.md is on the register. The seat does not flip it ready or arm auto-merge. It waits for the maintainer's merge or an authorized APPROVED review (GOVERNED_APPROVERS); the seat then lands it.