fix(docker): copy scripts/ into appservice builder so the root prepare hook can run (#1446)

docker/appservice.Dockerfile

@@ -10,6 +10,8 @@ COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
 COPY apps/appservice/package.json ./apps/appservice/
 COPY packages/ ./packages/
 COPY plugins/ ./plugins/
+# the root prepare script runs scripts/install-hooks.mjs on install
+COPY scripts/ ./scripts/
 RUN pnpm install --frozen-lockfile
 COPY . .
 RUN pnpm turbo run build --filter @mosaicstack/mosaic-as...

docs/requirements/identity-lifecycle.md

@@ -0,0 +1,328 @@
+# Identity Account-Lifecycle Contract
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 4 of 9).
+Authority: PRD D10 (better-auth is the account system of record), Q1 ruled O1
+by Jason 2026-08-26 (webui-audit T10). This document turns that ruling into
+enforceable policy. It also carries the bootstrap/first-admin invariant from
+issue #1430, folded in here after PR #1431's independent review showed the
+quick-fix approach was insufficient.
+
+Revision 2: addresses the 9 findings of the independent review
+(`fleet/lanes/webui-audit/findings/pr1433-review.md`) — epoch enforcement
+tightened (§3), canonical email split from provider claims (§5), external
+principal keyed by issuer+subject with DB uniqueness and link step-up (§6),
+JIT default precedence and first-admin SSO path defined (§2, §4),
+deactivation made measurable (§7.1), deletion kept in scope and the existing
+hard-delete endpoint required to fail closed (§7.3), workspace identity
+reconciled with the native-kanban SOT (§1.4), verification matrix expanded
+(§8), factual labels corrected (§7.3, §8.1).
+
+Revision 3: addresses the residuals and new findings of the revision-2
+re-review (`fleet/lanes/webui-audit/findings/pr1433-review-r2.md`) —
+`users.emailVerified` added to the canonical set with a defined reset rule on
+email change (§5.1–5.2), external-principal uniqueness moved to
+(issuer, subject) (§6.1), "can actually use" defined (§6.5), the shipped
+delete affordances (web admin page, `mosaic auth users delete`) required to
+be removed or disabled with a defined user-visible state (§7.3), the
+admin-creation switch removed in favor of plain admin authorization (§2.3),
+and §8 extended with observables for IdP removal, forward-auth non-use,
+first-admin SSO, wizard-recorded JIT choice, the admin-guide statement, and
+positive/expiry-bound step-up cases.
+
+Scope: account creation, bootstrap, federated login, account linking, claim
+mapping, deactivation, and (minimally) deletion gating. Out of scope: RBAC
+grant semantics (contract 2), wizard UX flow (contract 3), hierarchy schema
+(contract 1), sensitive-data custody (contract 7 / D14).
+
+## 1. System of record
+
+1. better-auth's tables (`users`, `accounts`, `sessions`, `verifications`) are
+   the only account system of record. All foreign keys reference `users.id`.
+2. External IdPs (Authentik or any OIDC provider) are login methods, attached
+   through better-auth's generic-OAuth plugin (`packages/auth/src/sso.ts`).
+   They never own accounts. Removing an IdP removes a login method, not users.
+3. The forward-auth perimeter shim is a deployment measure. Once in-app OIDC
+   is configured for a deployment, the shim is demoted: it may stay as network
+   perimeter, but no application code may read identity from its headers.
+4. **Account ≠ workspace membership.** Creating an account (by any path:
+   bootstrap, sign-up, invite, JIT, admin creation) creates no workspace, no
+   hierarchy grant, and no workspace-scoped authority (native-kanban SOT
+   REQ-TEN-001 / REQ-ID-001). The better-auth `role` field is a platform/auth
+   role (`member` | `admin`), not workspace membership. Workspace grants are
+   defined by contract 2; until then a fresh account can authenticate and
+   holds no workspace authority.
+
+## 2. Registration gating
+
+Measured current state on `next`: `emailAndPassword.enabled: true` with no
+gating — anyone who can reach the Gateway can create an account via
+`POST /api/auth/sign-up/email` and receives role `member`.
+
+Contract:
+
+1. A single server-side setting `registration_mode` with values
+   `open | invite | closed`. It lives in the database (admin-mutable at
+   runtime), not in env config.
+2. Default after bootstrap: `closed`. The wizard (contract 3) may set a
+   different mode during setup, recorded as an explicit operator choice.
+   While the bootstrap epoch is open (§3), the effective mode is `closed`
+   regardless of any stored value: the setting takes effect only after the
+   epoch completes.
+3. `closed` blocks self-service email/password sign-up. It does not block
+   admin-created users or OIDC JIT (§4). Post-bootstrap admin creation is
+   gated by admin authorization alone — there is no separate switch for it.
+   JIT is gated by its per-provider flag (§4.1). All user-creating paths are
+   closed while the bootstrap epoch is open (§3).
+4. `invite` requires a single-use, expiring invite token bound to an email
+   address. Invite issuance is an admin operation and is audit-logged.
+5. Enforcement point: a better-auth hook (or equivalent middleware executed
+   inside the auth handler path), not a Gateway route guard in front of it —
+   the raw `/api/auth/*` handler must be incapable of bypassing the gate.
+
+## 3. Bootstrap / first-admin invariant (from #1430)
+
+Invariant: **the system transitions from zero users to one admin user exactly
+once per bootstrap epoch, atomically, regardless of concurrency or which code
+path writes users.**
+
+Constraints any implementation MUST satisfy (each traces to a verified defect
+in PR #1431's review, `fleet/lanes/webui-audit/findings/pr1431-review.md`):
+
+1. **Durable fail-closed epoch state, obeyed by every writer.** The epoch
+   lives in a constraint-backed one-row `bootstrap_state` table. While the
+   epoch is open, every non-bootstrap user-creating writer — better-auth
+   sign-up, OIDC JIT, admin creation — refuses, fail-closed, enforced inside
+   the writer's own path (better-auth hook for the raw handler; guard for
+   admin routes). A partial unique index or a winning epoch-transition row is
+   necessary but not sufficient on its own: neither stops an untagged insert
+   from a writer that never consulted the epoch. Both layers are required:
+   database-level transition safety (the epoch-completing write races safely
+   and at most one wins) and writer-level refusal (no path can create a user
+   without reading epoch state).
+2. **Atomic first-admin transition.** The admin user, its credential account,
+   the initial admin token, and the epoch-completed transition commit in one
+   database transaction or not at all. A better-auth call through
+   `drizzleAdapter(db)` runs on the root pool and is NOT part of any caller
+   transaction; it may be used inside the bootstrap transition only if the
+   adapter is explicitly bound to the transaction handle. Otherwise the
+   bootstrap writer must create the user rows itself within the transaction.
+3. **Pool safety.** No design may hold a pooled connection inside a
+   transaction while awaiting a write that acquires a second connection from
+   the same pool (`DB_POOL_MAX=1` is a supported configuration).
+4. **Re-runnability (D4).** Bootstrap is not a one-shot: after the first-admin
+   epoch completes, re-running the wizard reconfigures the system but never
+   re-opens the zero-user transition. "Setup already completed" is a stable,
+   testable state, and factory-reset (a future, explicitly destructive
+   operation) is the only way to open a new epoch.
+5. **No stranded partial outcome.** A failure at any point in the transition
+   leaves nothing observable (no admin user without its token, no completed
+   epoch without an admin) and setup remains retryable — this follows from
+   §3.2 and is stated separately because it is the pre-existing failure mode
+   the #1431 review verified.
+6. **First-admin via SSO (D4).** When the operator chooses SSO for the
+   initial user, the wizard executes the OIDC login as part of the bootstrap
+   transition itself: the bootstrap writer creates the account from the
+   asserted identity inside the §3.2 transaction. This path is the bootstrap
+   writer, not JIT — §4's JIT gate stays closed during the epoch and is not
+   an obstacle to D4.
+
+## 4. JIT provisioning (OIDC first login)
+
+1. A successful OIDC login with no matching account creates a user
+   just-in-time only when `jit_provisioning` is enabled for that provider.
+   The flag is per-provider and defaults off, always. There is no
+   mode-implied default: Enterprise setup enables JIT only when the wizard
+   records it as an explicit operator choice for a named provider (this
+   replaces revision 1's "Enterprise mode defaults to closed with OIDC JIT
+   enabled", which contradicted the per-provider default).
+2. JIT users receive platform role `member`, never an elevated role,
+   regardless of IdP claims (§5), and no workspace authority (§1.4).
+3. An optional per-provider email-domain allowlist constrains JIT. The
+   allowlist matches only when the IdP asserts the email with
+   `email_verified: true`; an unverified address never satisfies the
+   allowlist. Empty allowlist with JIT on means any authenticated subject at
+   that IdP gets an account — permitted, but the wizard must present it as an
+   explicit choice.
+4. JIT is disabled while the bootstrap epoch is open (§3.1). The first-admin
+   SSO path is §3.6, not JIT.
+
+## 5. Claim mapping
+
+1. **Two stores, not one.** Provider-observed claims (`email`,
+   `email_verified`, display name, avatar) are recorded per external
+   principal — keyed by issuer + subject (§6.1) — at first login and
+   refreshed at each login. The canonical account fields (`users.email`,
+   `users.emailVerified`, `users.name`, `users.image`) are set exactly once
+   at account creation and are never silently overwritten by a later login.
+   For SSO-created accounts (JIT or first-admin SSO), `users.emailVerified`
+   is set from the provider's `email_verified` claim at creation; for
+   password-created accounts it is false until the address completes
+   verification.
+2. **Canonical email changes only through an explicit workflow.** Either the
+   user-initiated email change (with verification of the new address) or an
+   admin edit. Any canonical email change — user- or admin-initiated — sets
+   `users.emailVerified` to false until the new address completes
+   verification; an admin may instead explicitly attest the address as
+   verified in the same operation, and that attestation is audit-logged. A
+   provider-claim refresh never rebinds `users.email` or
+   `users.emailVerified`; a divergence between canonical email and the latest
+   provider-observed email is surfaced per §6.4.
+3. Never mapped from IdP claims: `role` and any future authorization
+   attribute. Authorization lives in the system of record and in the RBAC
+   layer (contract 2). An IdP group/role claim may at most be recorded for
+   audit; it grants nothing.
+
+## 6. Account linking trust
+
+1. **External principal identity is issuer + subject.** A linked identity is
+   keyed by the OIDC issuer and subject claims, not by an unqualified
+   provider subject id and not by email. The linked-identity row stores the
+   issuer, and the database enforces at most one local account per
+   **(issuer, subject)** with a unique constraint on those stored columns —
+   uniqueness on (provider, subject) is insufficient because provider →
+   issuer is not one-to-one: two provider configurations can point at the
+   same issuer, and the identity must not alias across them. The current
+   non-unique `(provider_id, account_id)` index satisfies neither;
+   application-level checks without a uniqueness witness lose
+   concurrent-callback races. Each configured provider additionally binds to
+   exactly one issuer, immutable after creation (changing the issuer means
+   creating a new provider).
+2. Linking an OIDC identity to an existing account happens only in one of two
+   ways: (a) explicit link initiated by the logged-in user from settings,
+   which requires step-up: a fresh reauthentication (password or existing
+   linked method) no older than a short bound the implementation defines
+   (≤ 10 minutes) — a session cookie alone is insufficient, so a stolen
+   session cannot quietly attach a durable login method; or (b) automatic
+   link when the IdP asserts a verified email exactly matching an existing
+   account **and** the provider is marked `trusted_for_linking`
+   (per-provider flag, default off).
+3. Untrusted-provider email collision produces a login error naming the
+   conflict, not an auto-link and not a duplicate account.
+4. A linked identity whose IdP-observed email later diverges from the
+   canonical account email keeps working (the link is by issuer + subject,
+   §6.1) but the divergence is surfaced in the user's settings and audit log
+   (the per-principal claim store in §5.1 is what makes the divergence
+   representable).
+5. Unlinking a login method is refused when it would leave the account with
+   no **usable** login method. Usable means: a set password, or a linked
+   identity whose provider is currently configured and enabled on this
+   deployment. A linked identity whose provider has been removed or disabled
+   (§1.2) is not usable and does not count; setting a password first lifts
+   the refusal.
+
+## 7. Deactivation propagation
+
+1. **Deactivation (better-auth admin ban) is authoritative and bounded.**
+   Concretely:
+   - Ban and session revocation are one operation: the ban commit revokes all
+     better-auth sessions for the user. If revocation partially fails, the
+     ban itself must already be committed and every guard denies from that
+     point (fail closed); the operation is retryable.
+   - Every authenticated entry path checks banned state: HTTP session guards,
+     the admin bearer-token path (which today does not test `banned` — an
+     implementation defect this contract makes non-conformant), MCP, and
+     Socket.IO.
+   - Active socket connections are terminated or denied within 30 seconds of
+     the ban commit, or at the next inbound message on that socket, whichever
+     comes first (socket auth at connect-time only, as today, does not
+     satisfy this).
+   - The current admin ban route updates only the user row; it does not
+     conform to this section until revocation and guard coverage land.
+   - Admin tokens owned by the banned user are revoked in the same operation.
+2. Deactivation at an external IdP does not propagate automatically in this
+   contract's scope (no SCIM). Operational rule: removing a user from the IdP
+   without banning them in Mosaic leaves any password or other linked login
+   method usable — the admin guide must state this. SCIM/webhook-driven
+   propagation is future work and out of scope here.
+3. **Deletion is not deactivation, and deletion is gated here.** Account
+   deletion semantics (FK fan-out across the 21 foreign-key constraints to
+   `users.id`, spread over 19 referencing tables) require their own
+   deletion-and-retention contract, chartered as an addition to the S2 list —
+   contract 7 is the D14 sensitive-data custody contract and does not cover
+   account deletion. Until that deletion contract is ratified: the existing
+   hard-delete endpoint (`DELETE /api/admin/users/:id`) is disabled and fails
+   closed, and deactivation is the only supported removal operation. A
+   contract that merely declared deactivation "the only supported removal"
+   while the endpoint stayed live would be false on its face.
+   Disabling the endpoint alone is insufficient — its shipped callers must
+   not be left as advertised operations that now fail generically:
+   - The admin web UI delete action (`apps/web/src/app/(dashboard)/admin/page.tsx`
+     and any SPA port of it) is removed, or replaced by a disabled control
+     whose visible text states that deletion is unavailable pending the
+     deletion-and-retention contract and points at deactivation.
+   - The CLI command `mosaic auth users delete`
+     (`packages/mosaic/src/commands/auth.ts`) is removed, or exits non-zero
+     with a message stating the same and naming the deactivation command.
+   - Both surfaces expose deactivation as the supported operation.
+
+## 8. Verification requirements
+
+Every MUST above needs a bounded observable. The matrix:
+
+1. **Bootstrap invariant (§3).** Real-PostgreSQL concurrency tests using two
+   distinct physical connections (pattern:
+   `apps/gateway/src/agent/connector-lease.postgres.integration.test.ts`,
+   which runs in the `test` CI step against the `ci-postgres` PostgreSQL
+   service — note that pattern multiplexes one pooled handle, so the tests
+   here must explicitly open separate connections). Races to cover:
+   setup-vs-setup, setup-vs-raw-sign-up, setup-vs-JIT, setup-vs-admin-create.
+   Plus: liveness under `DB_POOL_MAX=1`; fault injection after each write in
+   the transition (user, credential, token, epoch) proving nothing observable
+   leaks and setup retries; wizard re-run after completion proving the
+   zero-user transition never re-opens. Mocked-transaction specs are
+   supplementary; they cannot prove serialization.
+2. **Registration gating (§2).** Spec coverage of all three modes against the
+   raw `/api/auth/` handler path, not only Gateway controllers; invite
+   lifecycle (single-use, expiry, email binding); effective-`closed` while
+   the epoch is open regardless of stored mode.
+3. **JIT (§4).** Provider flag off → no account on first OIDC login; on →
+   account with platform role `member` and no workspace grant; domain
+   allowlist rejects an unverified email claim even when the domain matches;
+   JIT refused while the epoch is open.
+4. **Claim mapping (§5).** Login refresh updates the per-principal claim
+   store and touches none of the canonical fields (`users.email`,
+   `users.emailVerified`, name, image); explicit email-change workflow is the
+   only path that rebinds canonical email; every canonical email change
+   resets `users.emailVerified` to false unless the admin attestation path
+   is taken, and that attestation appears in the audit log.
+5. **Linking (§6).** Unique-constraint witness: concurrent first-login
+   callbacks for the same (issuer, subject) yield exactly one account, and
+   two provider configurations sharing one issuer cannot create two accounts
+   for the same subject; trusted auto-link; untrusted collision error;
+   step-up both ways: an explicit link succeeds immediately after a fresh
+   reauthentication and is refused once the implementation's chosen bound
+   (≤ 10 minutes) has elapsed, and refused with no reauthentication at all;
+   unlink refusal when no remaining method is usable per §6.5, including the
+   removed-provider case, and acceptance after a password is set; divergence
+   surfaced after IdP email change.
+6. **Deactivation (§7).** Ban revokes sessions atomically or fails closed
+   (partial-failure injection); guard denial post-ban on each transport:
+   HTTP session, admin bearer token, MCP, Socket.IO; active socket terminated
+   within the 30-second/next-message bound; banned user's admin tokens
+   unusable; hard-delete endpoint returns a fail-closed error while the
+   deletion contract is unratified; the admin web UI renders no live delete
+   action (absent, or disabled with the §7.3 text) and `mosaic auth users
+delete` exits non-zero with the §7.3 message — both asserted by spec.
+7. **System of record and bootstrap edges (§1, §3.6, §4.3).** IdP removal:
+   deleting a provider configuration leaves every user row intact and every
+   other login method working (spec over the provider-config removal path).
+   Forward-auth non-use: with in-app OIDC configured, a request carrying
+   forward-auth identity headers and no session is treated as anonymous —
+   no code path derives identity from those headers (negative spec at the
+   Gateway entry). First-admin SSO: the §3.6 transition commits account,
+   token, and epoch atomically from the asserted identity, and fault
+   injection mid-transition leaves nothing observable (same harness as §8.1).
+   Wizard-recorded JIT choice: enabling JIT for a provider writes an
+   explicit per-provider operator-choice record, and no mode selection
+   enables it implicitly (assert the stored record, not UI behavior).
+8. **Documentation observable (§7.2).** The admin guide contains the
+   IdP-removal-does-not-deactivate statement; verified by a docs assertion
+   (content check in CI or an enumerated review-checklist item on the
+   implementing PR) — a MUST about documentation needs a checkable artifact,
+   not intent.
+
+## Ruling request
+
+Ratify sections 1–8 as written, with one decision embedded: registration
+defaults to `closed` after bootstrap (§2.2) — say "agreed" or name the mode
+you want as the default.

docs/requirements/rollup-projection.md

@@ -0,0 +1,351 @@
+# Roll-up Projection Contract (S2 contract 8)
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 8 of 9).
+Authority: `native-kanban-sot.md` §8 (A1 amendment) — "task and status
+visualization bubbles up the hierarchy as aggregation over workspaces
+the reader is authorized on" (§8.1.3); roll-up is never a write and
+bubble-up views are generated projections, non-authoritative and never
+import sources (§8.2.2); the express, narrow carve-out from the
+portfolio-analytics non-goal covers per-workspace task counts and
+statuses aggregated up the parent chain over readable workspaces, and
+nothing beyond that boundary (§8.2.4); acceptance requires that roll-up
+endpoints cannot mutate state and that a reader sees aggregates only
+over workspaces they are authorized on, with no cross-tenant existence
+oracles (§8.3). A5 rank 5 names the deliverable: an authorized
+read-only roll-up query over only readable workspaces, at every
+hierarchy level, as its own non-mutating query tool, dependent on ranks
+1–3.
+
+Revision 2 (terra review F1–F7): membership-only readability is now
+workspace-local — it contributes at the workspace node only and never
+promotes ancestor visibility; upward aggregation requires an effective
+chain role, and §1 defines direct vs effective grants in contract 2's
+terms (F1). The no-oracle rule gains a defined equivalence predicate
+(normalized byte equality with an enumerated volatile-field set) and a
+partial-scope hidden-sibling witness (F2). §2.5 enumerates the closed
+semantic result and denial schemas field-by-field, including the
+explicit-zero representation (F3). Cache invalidation, when a cache
+exists, is witnessed per invalidator class (F4). Non-authoritative and
+never-gate rules gain an import-graph/data-flow witness, and the
+mutation check is aligned to contract 1 §6.7's both-table zero-write
+assertion (F5). The fixture gains a second estate with distinct counts
+and explicit company-, estate-, project-grant, and membership cases
+(F6). The §5.3 legacy-row exclusion and pre-rank no-obligation rules
+are disclosed as drafting additions (F7).
+
+Revision 3 (terra re-review residuals): the partial-scope witnesses are
+reconstructed at levels where chain grants can actually differ —
+platform-project siblings under one estate and estate siblings under
+one company — because contract 1 §3.1/§3.4 defines no workspace-level
+grant target, so no reader can hold a chain grant on two of three
+sibling workspaces (F2). §2.5 now defines one field-exact recursive
+record — every node, including the queried node and every leaf, is the
+same five-field shape with a required, deterministically ordered
+`children` array that is empty at workspaces — and the whole-result
+rules (no optional fields, denial envelope, wire faithfulness) are
+their own §2.6 at section scope (F3). The fixture assigns workspaces
+to named platform-projects, and §6.1's grant-level cases are the three
+levels contract 1 defines, with workspace-level access covered by the
+membership case and stated as having no direct chain grant (F6).
+
+This contract binds the projection semantics (§2), reader authorization
+semantics (§3), read-only enforcement (§4), dependencies and phase
+timing (§5), witnesses (§6), and disclosed drafting additions (§7). It
+defines the roll-up only: hierarchy shape stays with contract 1
+(`hierarchy-schema.md`), grant vocabulary and evaluation with contract 2
+(`rbac-grant-model.md`), the task lifecycle and status taxonomy with
+`native-kanban-sot.md`'s typed surface, and the tool↔Gateway mapping
+row with contract 5 (`tool-gateway-mapping.md`).
+
+## 1. Definitions
+
+1. **Roll-up**: the read-only projection of per-workspace task counts
+   by status, aggregated up the contract 1 parent chain (workspace →
+   platform-project → estate → company).
+2. **Effective chain role** (at a node, for a reader): the role
+   contract 2 §3 evaluation yields at that node — from a grant on the
+   node itself (a **direct grant**) or from a grant on an ancestor
+   whose domain covers it (an **inherited grant**, contract 2 §3.2).
+   The role vocabulary is contract 2 §2's; this contract adds no role
+   and no new authority source.
+3. **Chain-readable workspace** (for a reader): a workspace where the
+   reader's effective chain role permits reading task state.
+4. **Member-readable workspace** (for a reader): a workspace readable
+   only through workspace membership under the SOT's own membership
+   rules (REQ-ID-001), with no effective chain role. Membership
+   confers workspace-local semantics only (contract 2 §3.1, §7.4): it
+   never contributes authority, visibility, or aggregation upward.
+5. **Aggregation scope** (of a hierarchy node, for a reader): the set
+   of chain-readable workspaces in that node's descendant subtree;
+   plus, when the node is itself a workspace, that workspace if it is
+   chain-readable or member-readable. A member-readable workspace
+   therefore contributes to exactly one node's aggregation scope: its
+   own.
+6. **Projection**: a generated, non-authoritative view in the sense of
+   `native-kanban-sot.md` §3 invariant 5 — derived from SOT rows,
+   never an import source, never authoritative.
+
+## 2. Projection semantics
+
+1. **Aggregate content.** The roll-up for a node reports, per
+   workspace in the reader's aggregation scope and as subtree totals:
+   task counts keyed by the typed lifecycle's status values (owned by
+   `native-kanban-sot.md`; this contract introduces no status), and
+   nothing else. Direct count/status aggregation is the entire
+   surface.
+2. **Every level.** The roll-up is queryable at workspace,
+   platform-project, estate, and company level. A node's totals equal
+   the sum over its aggregation scope; chain resolution is contract 1
+   §2.5's (every workspace resolves to exactly one chain), so no
+   workspace is counted twice and none is orphaned.
+3. **Carve-out boundary.** Everything beyond direct count/status
+   aggregation — metrics, trends, forecasting, scoring, velocity,
+   cross-workspace derived analytics, dashboards computed across
+   workspaces — remains a `native-kanban-sot.md` §6 non-goal
+   (§8.2.4). The response schema is closed (§2.5; §6.7 witness):
+   adding any field is an amendment to this contract.
+4. **Non-authoritative.** No consumer may treat roll-up output as a
+   source of record; it is recomputable at any time from SOT rows and
+   is never imported, persisted as authoritative state, or used to
+   gate or deny work (witness §6.8 — both the write-path and the
+   decision-path prohibitions are witnessed).
+5. **Closed semantic schema.** The successful result is exactly one
+   **roll-up node record**, a single recursive shape used at every
+   depth. A roll-up node record consists of exactly these five
+   fields, and no others:
+   - `id`: the node's identifier.
+   - `type`: one of the four contract 1 levels.
+   - `name`: the node's name.
+   - `totals`: one entry per status value of the typed lifecycle —
+     every status key present, a count of zero represented explicitly
+     as `0`, never by key absence. At a workspace node, `totals` is
+     that workspace's own counts; at any other node, `totals` is the
+     sum over the node's aggregation scope (§2.2). This is how §2.1's
+     "per workspace and as subtree totals" content is carried:
+     per-workspace counts are the leaf records' `totals`, subtree
+     totals are the interior records' `totals`.
+   - `children`: a required array, present on EVERY node record. Its
+     elements are the reader-visible (§3.2) child nodes of this node,
+     each itself a complete roll-up node record, recursing down to
+     the workspaces in the reader's aggregation scope. At a workspace
+     node the array is exactly `[]` — a workspace record never has
+     children. The array is ordered deterministically, ascending by
+     `id`; the implementing PR asserts that ordering. A node outside
+     §3.2 visibility never appears at any depth.
+
+   The queried node's record IS the whole result — there is no
+   wrapper field around it.
+
+6. **Whole-result rules.** There are no optional result fields at any
+   depth. The denial/nonexistent response is the contract 5 §4.2
+   not-found-class error envelope with no fields beyond that
+   envelope. The wire DTO is expressed under contract 5 §4.1, and
+   MUST be a faithful serialization of exactly the §2.5 recursive
+   record: a wire field with no corresponding semantic field is a
+   conformance defect.
+
+## 3. Reader authorization semantics
+
+1. **Scope rule.** A reader's roll-up over any node aggregates ONLY
+   the reader's aggregation scope (§1.5). An unreadable workspace
+   contributes nothing to any total — not a count, not a row, not a
+   presence marker. A member-readable workspace contributes only at
+   the workspace node itself (§1.4–§1.5): querying it directly
+   succeeds; it never appears in, and never adds to, any ancestor's
+   response for that reader.
+2. **Node visibility.** A node appears in a roll-up response iff the
+   reader's aggregation scope at that node is non-empty, or the
+   reader holds an effective chain role at the node (§1.2 — direct or
+   inherited; contract 2 §3.2 makes a grant's domain the node and its
+   subtree, so an ancestor grant makes empty descendants visible per
+   the ruling). Per the ruling below, a node with an effective chain
+   role but an empty aggregation scope appears with zero counts.
+   Workspace membership alone never makes any non-workspace node
+   visible. A node where the reader has neither an effective chain
+   role nor a non-empty aggregation scope does not appear at all.
+3. **No existence oracle.** The response MUST NOT disclose the
+   existence, count, name, or any property of unreadable workspaces
+   or of nodes outside §3.2 visibility — no "N workspaces hidden"
+   fields, no total-vs-visible discrepancy fields. A query naming a
+   node outside §3.2 visibility MUST satisfy the §3.4 response
+   equivalence with a query naming a nonexistent node (fail closed,
+   `rbac-grant-model.md` §3.5 pattern: a decision path that cannot
+   read grant state denies).
+4. **Response equivalence predicate.** Two responses are equivalent
+   when they carry the identical HTTP status, the identical contract
+   5 §4.2 error code, and byte-identical bodies after normalizing
+   exactly the declared volatile envelope fields — correlation id and
+   response timestamp, and nothing else. The implementing PR declares
+   that volatile-field list in the witness; any additional
+   normalization is a conformance defect. This is contract 5 §4.2's
+   same code/status/shape rule made executable.
+5. **Live evaluation.** Readability is evaluated per contract 2 §3.5
+   (live rows or transactionally-invalidated cache). Revocation
+   propagates per contract 2 §6: the next roll-up query decided after
+   the revoking transaction commits excludes the revoked scope.
+
+## 4. Read-only enforcement
+
+1. **Never a write.** No roll-up path may mutate, claim, order, or
+   gate work in any workspace (§8.2.2). The roll-up ships as a
+   non-mutating query tool (A5 rank 5) — a query surface with no
+   command counterpart.
+2. **Mechanical enforcement.** The implementing PR executes roll-up
+   database work inside read-only transactions (or an equivalently
+   privilege-restricted path), so a mutation attempt fails at the
+   database boundary, not only by convention.
+3. **Freshness.** v1 computes the roll-up live from SOT rows at query
+   time. A cache is an implementation option only if it is
+   invalidated in the same transaction as any task, hierarchy, grant,
+   or membership mutation that affects it (each invalidator class
+   witnessed, §6.5), and it is never authoritative (§1.6).
+
+## 5. Dependencies and phase timing
+
+1. The roll-up depends on A5 ranks 1–3: contract 1's hierarchy tables
+   (the parent chain), contract 2's evaluator (readability), and the
+   typed Kanban lifecycle (the task state being counted). It ships
+   after them and reads their surfaces; it defines none of them.
+2. The roll-up query is one tool with one Gateway mapping row under
+   contract 5's regime (request/result/error/audit contracts there);
+   this contract binds its semantics (§2.5 defines the semantic
+   fields the contract 5 §4.1 DTO serializes), not its wire encoding.
+3. Legacy task rows outside the typed lifecycle are not aggregated;
+   the roll-up begins counting a workspace's tasks when they exist in
+   the typed surface. No roll-up obligation attaches to v1 before
+   ranks 1–3 exist. Both rules are drafting additions disclosed in §7
+   (they trace to no §8 sentence).
+
+## 6. Verification requirements
+
+Binding on the implementing PRs. Every witness names, in its
+implementation, the exact endpoints/tools, tables, and fixtures it
+exercises. The base fixture seeds two companies; under company A **two
+estates with distinct, non-identical count profiles**: estate A1 with
+two platform-projects — P1 holding workspaces W1 and W2, P2 holding
+workspace W3 — and estate A2 with one platform-project P3 holding one
+workspace W4, all with known task counts across at least three
+statuses; under company B one workspace.
+
+1. **Correctness witnesses:** for a reader holding a direct company-A
+   grant, roll-up totals at every level equal the seeded sums — each
+   workspace, each platform-project, estate A1 and estate A2
+   separately (their distinct profiles asserted distinct), and the
+   company total equal to A1+A2 — keyed by the typed status values,
+   with no double count across the chain. For a reader holding a
+   direct estate-A1 grant, the estate-A1 result equals the A1 sum and
+   a company-A query returns company A with exactly A1's contribution
+   (estate A2 invisible). Each of the three chain grant levels
+   contract 1 §3.1 defines — company, estate, platform-project
+   (below, §6.2) — has an explicit direct-grant case, none simulated
+   by unioning lower access. Workspace-level access has NO direct
+   chain grant (contract 1 §3.1/§3.4 define no workspace grant
+   target) and is covered by the §6.2 membership case.
+2. **Scope witnesses:** a reader with a direct grant on
+   platform-project P1 only sees exactly P1's subtree counts
+   (W1+W2): a P1 query returns W1+W2; an estate-A1 query returns the
+   estate node with exactly P1's contribution, sibling project P2 and
+   its workspace W3 absent at every depth; a company-A query likewise
+   carries only P1's contribution. An estate-sibling case: a reader
+   with a direct grant on estate A1 only queries company A and
+   receives exactly A1's contribution, estate A2 absent. (Chain
+   grants exist only at company, estate, and platform-project —
+   contract 1 §3.1 — so partial scope among SIBLING WORKSPACES of
+   one project is not constructible by grants and is not witnessed;
+   the constructible partial-scope cases are the project- and
+   estate-sibling ones above.) **Membership locality (§1.4):** a member-only reader queries
+   the workspace directly and receives its counts; the same reader
+   querying the workspace's parent (or any ancestor) receives the
+   §3.4-equivalent nonexistent-node response, and no ancestor
+   response for any other reader changes because of that membership.
+3. **No-oracle witnesses:** the P1-only reader's estate-A1 response
+   above contains no field disclosing P2's or W3's existence
+   (closed-schema comparison against an estate-A1-granted reader's
+   response: identical field set, differing only in counts and
+   visible nodes). **Partial-scope hidden node:** the P1-only reader
+   — who sees estate A1 and the P1 subtree — queries hidden sibling
+   project P2 by its real id, and separately hidden workspace W3 by
+   its real id; each response satisfies the §3.4 equivalence
+   predicate against the same query naming a nonexistent id, under
+   one fixed request context with the declared volatile-field
+   normalization. **Cross-tenant:** an unauthorized reader naming company B receives
+   a response §3.4-equivalent to naming a nonexistent id. Each
+   equivalence check is executable byte comparison after the declared
+   normalization, not a shape judgment.
+4. **Empty-vs-hidden witness (ruling):** a reader granted (direct
+   chain grant) on an empty platform-project receives it with zero
+   counts — every status key present at `0` (§2.5); with the grant
+   deleted, the same query returns the §3.4-equivalent
+   nonexistent-node response. An inherited-grant case: a company
+   grant makes an empty descendant platform-project visible with zero
+   counts.
+5. **Cache-invalidation witnesses (conditional):** bound only if the
+   implementation caches — for EACH invalidator class, prime the
+   cache, commit one mutation of that class, and assert the next
+   query reflects it: a task status change, a task creation, a
+   membership removal (the member-readable workspace disappears from
+   its own node's next query), a workspace reparenting (both old and
+   new parent totals correct), and a grant revocation. A live
+   (cacheless) v1 implementation records that fact and the witnesses
+   bind at the PR that introduces a cache.
+6. **Mutation witnesses:** the roll-up surface rejects every mutating
+   verb/command; a crafted attempt to issue a write through the
+   roll-up's database path fails at the read-only boundary (§4.2);
+   after any roll-up query, the row diff is empty across BOTH the
+   workspace tables and the hierarchy tables (contract 1 §6.7's
+   both-table zero-write assertion).
+7. **Closed-schema witness:** the response is asserted field-exact
+   against the §2.5 recursive record at every depth — exactly
+   `id`/`type`/`name`/`totals`/`children` on every node, every typed
+   status present with explicit zeros, `children: []` at every
+   workspace record, the declared ascending-`id` ordering, no
+   wrapper field — and a response carrying any field outside the
+   record at any depth fails the assertion (carve-out boundary,
+   §2.3). The denial envelope is asserted field-exact against
+   contract 5 §4.2's envelope (§2.6).
+8. **Non-authoritative and never-gate witnesses:** (a) a static
+   production import-graph inventory (hierarchy contract §6.3 style,
+   production code over `apps/` and `packages/`, tests excluded)
+   shows no production module imports the roll-up query module or its
+   result DTO into any SOT write path, any authorization/gating
+   decision path, or any persistence beyond the response lifetime —
+   asserted in both directions (the roll-up module's consumers are
+   enumerated and each is a presentation surface); (b) a behavioral
+   probe: with roll-up output artificially perturbed (test double),
+   no authorization outcome and no work-gating decision anywhere in
+   the fixture suite changes — proving no gate consumes it.
+9. **Revocation witness:** after revoking the grant that made a
+   subtree readable, the next roll-up query excludes it (contract 2
+   §6.2 bound).
+
+## 7. Drafting additions (PRD §12.1 disclosure)
+
+Proposed drafting additions, visible here for ratification, each
+severable; the aggregation itself, its authorization scope, its
+read-only nature, and the no-oracle acceptance are traced to
+`native-kanban-sot.md` §8 and are not additions:
+
+1. The §3.2 node-visibility rule and the granted-but-empty behavior
+   (the ruling below).
+2. The §3.3–§3.4 nonexistent-node response equivalence, with its
+   normalized-byte-equality predicate, as the concrete no-oracle
+   mechanism.
+3. The §4.2 read-only-transaction mechanical enforcement.
+4. The §4.3 cache option with transactional invalidation and the
+   §6.5 per-invalidator witnesses.
+5. The §2.5 closed response schema as an amendment boundary.
+6. The §1.4 membership-locality rule — membership-only readability
+   contributes at the workspace node only (this contract's
+   reconciliation of `native-kanban-sot.md` §8.1.3 "authorized on"
+   with contract 2 §3.1/§7.4's workspace-local membership).
+7. The §5.3 legacy-row exclusion and the §5.3 pre-rank no-obligation
+   rule.
+
+## Ruling request
+
+Ruling requested (one decision): shall a node the reader holds an
+effective chain role on (direct or inherited, §1.2) but whose
+aggregation scope is empty appear in the roll-up with zero counts
+(recommended — it lets the UI show a granted-but-empty subtree
+honestly) — or, as the alternative, be indistinguishable from a
+nonexistent node until it contains a readable workspace?