@@ -0,0 +1,15 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the protocol upgrade guide has a public address, one docs-site page per protocol major
+
+Clause-②: no
+
+The guide is published on the docs site, one page per protocol major, at `https://objectstack.ai/docs/protocol-upgrade/N`; `https://objectstack.ai/docs/protocol-upgrade` lists them all. A link to one major keeps resolving after the next major opens. The site builds from `main`, so each page says whether its major is released, in prerelease, or not released yet.
+
+`docs/protocol-upgrade-guide.md` in the repository, which earlier READMEs and changelog entries point at, is now a short pointer naming that address.
+
+What a release shipped is unchanged: `protocol-upgrade-guide.md` inside the package and attached to its GitHub Release. Its only change is the header comment, which now names the command that writes the file.
+
+Nothing changes for an author, and nothing is renamed or removed.
@@ -0,0 +1,35 @@
+---
+'@objectstack/spec': minor
+'@objectstack/platform-objects': patch
+---
+
+feat(spec)!: `PageSchema` refuses a page that authors both `slots.details` and `slots.tabs`; the `sys_user` record page carries its details grid as its first tab
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered page-slots-details-beside-tabs-refused -->
+
+**BREAKING**: an accept-set narrowing on a published authoring surface, shipped as `minor` under the launch-window convention for accept-set narrowings.
+
+**Why.** The slot map read as seven independent slots, and two of them are not. On a slotted record page `details` replaces the body of the Details tab, that tab lives inside the synthesized `page:tabs` strip, and `tabs` replaces the whole strip. The console's default-page synthesizer therefore reads `tabs` and never reads `details` when both are authored. A page authoring both passed `PageSchema.parse`, `objectstack validate` and the metadata save door, and its details body (its `sections`, its `hideFields`) silently never applied. The platform's own `sys_user` record page was one: its Identity and Audit sections never showed, and the ban columns it hides were never hidden by it.
+
+**What is refused.** A page whose `slots` map carries both a `details` and a `tabs` key, at `slots.details`, with a `custom` issue that names both slots and the fix. Either slot may be one component or an array; an empty `details: []` is refused like a full one, and the page's `kind` does not matter. That covers `PageSchema`, `definePage`, `defineStack` (`STACK_SCHEMA_INVALID`, 422), `os validate` and the metadata save door (`422 INVALID_METADATA`). The check is exported as `checkPageSlotPair`, for a mirror built from `PageSchema.shape` to re-attach.
+
+**What is still accepted, byte for byte.** A page authoring only `details`, only `tabs`, or neither.
+
+## FROM → TO
+
+| you wrote | write instead |
+|:--|:--|
+| `slots: { details: { type: 'record:details', … }, tabs: { type: 'page:tabs', properties: { items: [ … ] } } }` | `slots: { tabs: { type: 'page:tabs', properties: { items: [ { label: 'Details', children: [ { type: 'record:details', … } ] }, … ] } } }` |
+| both slots, wanting the synthesized tabs with your details body | `slots: { details: { type: 'record:details', … } }`, with no `tabs` slot |
+
+**The one-line fix: move the `record:details` component into the `tabs` items (the first item's `children`, by convention) and delete `slots.details`.** Its `sections` and `hideFields` move unchanged. The page then shows the details body it always declared, which is a visible change on every page that authored the pair.
+
+**Who is affected, measured.** In this repository, only the `sys_user` record page (`sys_user_detail` in `@objectstack/platform-objects`) authored both slots; no example app page does. hotcrm's one slotted page authors `header` and `discussion` only. Deployed metadata was not measured. A page row already stored with the pair is replayed unchanged at load, so it renders as before (the authored tabs, without the details body); its read diagnostics name the pair, and saving it again is refused until the details body moves.
+
+### The kit
+
+- **The refusal.** `checkPageSlotPair`, attached to `PageSchema` by identifier beside its three other object-level checks. No new error code.
+- **The producer.** `sys_user_detail` moves its `record:details`, with its `sections` and `hideFields` unchanged, in as the first `tabs` item.
+- **The ledger.** The D3 semantic entry `page-slots-details-beside-tabs-refused` (protocol 18) and its step-18 rationale fragment. No key is removed, so there is no tombstone, and there is no D2 conversion: which tab item carries the details body, and under which label, is the author's decision.
@@ -0,0 +1,9 @@
+---
+'@objectstack/plugin-security': patch
+---
+
+`security/explain` answers a transfer of a row the caller cannot read the way the transfer door does: as a record that does not exist.
+
+- **What was wrong.** On the write doors, a row the caller cannot read answers what a nonexistent id answers: the by-id update or delete the caller addresses gets `404 RECORD_NOT_FOUND`. A transfer's door is the `PATCH` that writes `owner_id`, an update, so a transfer of an unreadable row gets that 404 too. explain's matching rewrite (the missing-record shape, `record: { visible: false }` with no `decidedBy`) keyed on the verb as asked, `update` or `delete`, so it never ran for `transfer`. Where the caller's update policy admitted the hidden row, explain answered `visible: true`, decided by `rls`. Where the caller declared no write policy, it answered `visible: false` decided by `rls`, which is the shape of a 403 refusal, not of the door's 404.
+- **What it does now.** The rewrite asks which operation the verb's door is through the same mapping the by-id write path reads (`transfer` and `restore` as update, `purge` as delete). So every write verb whose door is a by-id update or delete is asked the read question, and a transfer of a row the caller cannot read is `{ visible: false }` with no decider, beside the door's 404.
+- **What is unchanged.** `update` and `delete` are answered exactly as before. `restore` and `purge` are still refused at the object gate for every principal, which answers first. A readable row keeps its verdict for every verb. The object-level `allowed` answers the object question and is not touched. No door changes, and no export is added to the package.
@@ -0,0 +1,13 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): the approvals service contract declares an optional, transport-neutral action-page member (`IApprovalService.handleActionPage`)
+
+Clause-②: yes (widening)
+
+- **What is new.** `IApprovalService` in `@objectstack/spec/contracts` gains one optional member, `handleActionPage?(request: Request): Promise<Response>`. It serves the ADR-0043 action page, the session-less page an approver reaches from the approve or reject link in an e-mail or IM message. `GET` renders the confirm page from the `token` query parameter and never decides. `POST` redeems the `token` form field and answers the result page.
+- **The token is the only credential.** The member takes no `ExecutionContext` and reads no session, cookie or `Authorization` header. The decision is audited as the approver the token binds.
+- **Transport-neutral.** A web-standard `Request` in, a `Response` out: no Hono context, no raw app and no `http.server` type. A hosted tenant kernel has no raw app to mount pages on, and the runtime dispatcher's `/approvals/act` domain is the member's one caller.
+- **Absence.** The member is optional, so an approvals implementation without action pages still satisfies the contract. Its caller answers a typed 404 or 501 when the `approvals` service or this member is absent, never `ROUTE_NOT_FOUND`.
+- **Nothing changes for existing implementers.** No existing member moved. Nothing implements or calls the member yet: the plugin implementation and the dispatcher domain land separately, and the plugin's self-hosted pages stay as they are.
@@ -0,0 +1,11 @@
+---
+"@objectstack/core": minor
+---
+
+feat(core): the ADR-0069 auth-gate allow-list admits the ADR-0043 approval action route, `approvals/act`, as one exact route
+
+Clause-②: yes
+
+- **What the allow-list admits now.** `isAuthGateAllowlisted` answers `true` for the approval action route `approvals/act`, at the mount bases the gate already recognises (`/api/v1/approvals/act`, `/api/approvals/act`, and the dispatcher's prefix-stripped `/approvals/act`), unscoped or under one `/environments/<id>` (or legacy `/projects/<id>`) scope, with the query string and trailing slashes stripped as for every other entry. Nothing else moves: `/approvals/act/<anything>`, `/approvals/actx`, the approvals base and every `/approvals/requests/…` route stay gated.
+- **Why this is not a loosening.** ADR-0043 authenticates the action page by its single-use token alone, and `plugin-approvals`' self-hosted mount (`GET` renders, `POST` redeems on the host app) has never passed through this gate. The entry gives the dispatcher's spelling of the same route the same token-only authentication, so a session held by an authentication policy (expired password, required MFA) is no longer refused there with that policy's `403` before the token is read.
+- **Effect on a kernel whose dispatcher serves no `/approvals/act` domain.** A held session that reaches the route gets the dispatcher's `404 ROUTE_NOT_FOUND`, the answer every other caller already gets there, instead of the policy's `403`. Nothing on the REST surface is affected: no REST route serves `approvals/act`, and no shipped seam passes a path to `shouldDenyAnonymous`.
@@ -17,22 +17,37 @@
 # stay routed here as directories: the driver still owns a same-category
 # collision, which is the residue sharding cannot remove.
 #
-# Two entries below are still SINGLE files — spec-changes.json and
-# docs/protocol-upgrade-guide.md — and #8344 asked what the driver-less queue does
-# to them. MEASURED (2026-08-13, the real in-flight case plus four synthetic pairs,
-# each merged in a clone with no merge.os-regen.driver): it never leaves them
-# stale-but-clean. Both are sorted unions and an ADR-0087 registration is
-# insertion-only, so the queue's text merge either takes both sides — byte-identical
-# to the regeneration, gates green — or conflicts outright. It conflicts only when
-# the two in-flight entries are ADJACENT in registry sort order; one existing entry
-# between them is already enough to merge clean AND current.
-#
-# Sharding them would not buy back an ejection, which is why they are still single
-# files: every conflicting case also conflicts in
+# One entry below is still a SINGLE file — spec-changes.json — and #8344 asked
+# what the driver-less queue does to it. MEASURED (2026-08-13, the real in-flight
+# case plus four synthetic pairs, each merged in a clone with no
+# merge.os-regen.driver, over it and the protocol upgrade guide, then a second
+# committed single file): the queue leaves neither stale-but-clean. Both were sorted
+# unions and an ADR-0087 registration is insertion-only, so the queue's text merge
+# either takes both sides — byte-identical to the regeneration, gates green — or
+# conflicts outright. It conflicts only when the two in-flight entries are ADJACENT
+# in registry sort order; one existing entry between them is already enough to
+# merge clean AND current.
+#
+# Sharding it would not buy back an ejection, which is why it is still a single
+# file: every conflicting case also conflicts in
 # packages/spec/src/migrations/registry.ts — generated, committed, unsharded,
 # NOT_DRIVER_MANAGED — and every registration touches it by construction. The table
 # and the reproduction are in packages/spec/src/migrations/entries/README.md.
 #
+# docs/protocol-upgrade-guide.md LEFT this list at #22483 because nothing generates
+# it any more. It is a hand-written pointer stub naming the guide's public address,
+# and `gen:upgrade-guide` writes the gitignored docs pages under
+# content/docs/protocol-upgrade/ instead (NOT_DRIVER_MANAGED records that path). A
+# route there was harmful, not idle: the driver kept OURS whole, and the pre-commit
+# discharge then passed it, because `check:upgrade-guide` compares no committed
+# copy — so a branch carrying a generated guide merged the stub away in silence.
+# Unrouted, a merge made from a checkout that carries this file conflicts on the
+# stub. ⚠️ git reads the route from the checkout DOING the merge, so a branch
+# forked before #22483 still defers the guide on its first merge of main; the merged
+# tree has no row to discharge it against, so the next commit and the push are
+# refused instead of passed (measured on PR #22556 with the previous head as the
+# control, both merge directions).
+#
 # `merge=os-regen` hands those paths to `scripts/git-merge-regen.mjs`, which does
 # NOT text-merge them. See that file for why it also does not regenerate them
 # in place (git runs merge drivers BEFORE the sources are merged, so anything
@@ -173,7 +188,6 @@ packages/spec/src/meta-spelling/meta-url-data.generated.ts   merge=os-regen
 packages/spec/export-origins/**                              merge=os-regen
 packages/spec/declaration-map/**                             merge=os-regen
 packages/spec/api-surface-signatures.json                    merge=os-regen
-docs/protocol-upgrade-guide.md                               merge=os-regen
 docs/audits/2026-07-unknown-key-strictness-ledger.counts/**  merge=os-regen
 content/docs/references/**                                   merge=os-regen
 content/docs/permissions/system-context.mdx                  merge=os-regen
 
@@ -103,6 +103,9 @@ next-env.d.ts
 .source/
 apps/*/. source/
 apps/*/.next/docs/
+# The protocol upgrade guide's docs pages: generated at docs build by
+# `pnpm --filter @objectstack/spec gen:upgrade-guide`, never committed.
+content/docs/protocol-upgrade/
 .turbo
 
 # Local env overrides (may contain secrets)
 
@@ -6,7 +6,7 @@
   "license": "Apache-2.0",
   "scripts": {
     "dev": "next dev",
-    "build": "pnpm --filter @objectstack/spec gen:schema && pnpm --filter @objectstack/spec gen:docs && NODE_OPTIONS='--max-old-space-size=4096' next build",
+    "build": "pnpm --filter @objectstack/spec gen:schema && pnpm --filter @objectstack/spec gen:docs && pnpm --filter @objectstack/spec gen:upgrade-guide && NODE_OPTIONS='--max-old-space-size=4096' next build",
     "start": "next start",
     "site:lint": "next lint",
     "postinstall": "fumadocs-mdx",
 
@@ -14,6 +14,7 @@
     "ai",
     "api",
     "upgrading",
+    "protocol-upgrade",
     "---Platform---",
     "deployment",
     "plugins",