merge master into fix/issue-840-cross-role-queue-allocation

fix: authoritative cross-role generic queue allocation (Closes #840 )
Add controller-owned cross_role allocation mode that inspects the full queue and returns one selection with required role/profile/action and lease evidence. Document process_work_queue routing, normalize controller role metadata, and keep the dashboard explanatory only. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-07-23 00:06:09 -04:00 · 2026-07-23 00:05:35 -04:00 · 2026-07-22 23:00:24 -05:00 · 2026-07-22 22:16:38 -05:00
9 changed files with 2456 additions and 56 deletions
@@ -78,6 +78,33 @@ VALID_ROLES = frozenset(
    {ROLE_AUTHOR, ROLE_REVIEWER, ROLE_MERGER, ROLE_RECONCILER, ROLE_CONTROLLER}
 )

+# Allocation modes (#840).
+# role_scoped: only candidates whose expected role matches the caller role.
+# cross_role:  controller-owned generic queue selection — inspect full queue,
+# rank/eligibility canonically, return one selection naming the required
+# downstream role/profile. Controller routes; it does not perform mutations.
+ALLOCATION_MODE_ROLE_SCOPED = "role_scoped"
+ALLOCATION_MODE_CROSS_ROLE = "cross_role"
+VALID_ALLOCATION_MODES = frozenset(
+    {ALLOCATION_MODE_ROLE_SCOPED, ALLOCATION_MODE_CROSS_ROLE}
+)
+
+# Default execution-profile / MCP-namespace names for each role.
+DEFAULT_ROLE_PROFILES: dict[str, str] = {
+    ROLE_AUTHOR: "prgs-author",
+    ROLE_REVIEWER: "prgs-reviewer",
+    ROLE_MERGER: "prgs-merger",
+    ROLE_RECONCILER: "prgs-reconciler",
+    ROLE_CONTROLLER: "prgs-controller",
+}
+DEFAULT_ROLE_NAMESPACES: dict[str, str] = {
+    ROLE_AUTHOR: "gitea-author",
+    ROLE_REVIEWER: "gitea-reviewer",
+    ROLE_MERGER: "gitea-merger",
+    ROLE_RECONCILER: "gitea-reconciler",
+    ROLE_CONTROLLER: "gitea-controller",
+}
+
 # Default action matrices by role (mutation gate will re-check).
 ROLE_ACTIONS: dict[str, tuple[tuple[str, ...], tuple[str, ...]]] = {
    ROLE_AUTHOR: (
@@ -259,6 +286,126 @@ def normalize_role(role: str | None, *, profile_name: str | None = None) -> str:
    )


+def resolve_allocation_mode(
+    role: str,
+    allocation_mode: str | None = None,
+) -> str:
+    """Resolve allocation mode; controller defaults to cross_role (#840)."""
+    raw = (allocation_mode or "").strip().lower()
+    if raw:
+        if raw not in VALID_ALLOCATION_MODES:
+            raise ControlPlaneError(
+                f"unknown allocation_mode {allocation_mode!r}; expected one of "
+                f"{sorted(VALID_ALLOCATION_MODES)}"
+            )
+        return raw
+    if role == ROLE_CONTROLLER:
+        return ALLOCATION_MODE_CROSS_ROLE
+    return ALLOCATION_MODE_ROLE_SCOPED
+
+
+def required_profile_for_role(
+    role: str,
+    *,
+    profile_name: str | None = None,
+) -> str:
+    """Map a required role to the canonical execution profile name."""
+    role_norm = (role or "").strip().lower()
+    # Preserve remote/env prefix from the active profile when present
+    # (e.g. dadeschools-author → dadeschools-reviewer).
+    active = (profile_name or "").strip()
+    if active:
+        lower = active.lower()
+        for token in ("author", "reviewer", "merger", "reconciler", "controller"):
+            if lower.endswith(f"-{token}") or lower == token:
+                prefix = active[: -len(token)].rstrip("-")
+                if prefix:
+                    return f"{prefix}-{role_norm}"
+                return role_norm
+    return DEFAULT_ROLE_PROFILES.get(role_norm, f"prgs-{role_norm}")
+
+
+def required_namespace_for_role(
+    role: str,
+    *,
+    profile_name: str | None = None,
+) -> str:
+    """Map a required role to the canonical MCP namespace name."""
+    role_norm = (role or "").strip().lower()
+    profile = required_profile_for_role(role_norm, profile_name=profile_name)
+    # Namespace is typically gitea-<role>; keep stable mapping when profile is
+    # non-prgs (still gitea-<role> for isolation).
+    return DEFAULT_ROLE_NAMESPACES.get(role_norm, f"gitea-{role_norm}")
+
+
+def selected_action_for_candidate(c: WorkCandidate, required_role: str) -> str:
+    """Canonical next action for the selected work under *required_role*."""
+    role = (required_role or "").strip().lower()
+    if role == ROLE_AUTHOR:
+        if c.kind == "pr" and c.request_changes_current_head:
+            return "address_pr_change_requests"
+        if c.kind == "pr":
+            return "update_pr"
+        return "implement"
+    if role == ROLE_REVIEWER:
+        if c.approval_stale:
+            return "re_review"
+        return "review"
+    if role == ROLE_MERGER:
+        return "merge"
+    if role == ROLE_RECONCILER:
+        if c.approval_contaminated:
+            return "reconcile_contaminated_approval"
+        return "reconcile"
+    if role == ROLE_CONTROLLER:
+        return "diagnose"
+    return "process"
+
+
+def build_selection_dict(
+    selected: WorkCandidate,
+    *,
+    active_role: str,
+    required_role: str,
+    profile_name: str | None = None,
+    allocation_mode: str,
+) -> dict[str, Any]:
+    """Authoritative single selection payload for allocator results (#840)."""
+    action = selected_action_for_candidate(selected, required_role)
+    req_profile = required_profile_for_role(
+        required_role, profile_name=profile_name
+    )
+    req_ns = required_namespace_for_role(
+        required_role, profile_name=profile_name
+    )
+    return {
+        "kind": selected.kind,
+        "number": selected.number,
+        "title": selected.title,
+        "labels": list(selected.labels),
+        "head_sha": selected.head_sha,
+        "priority": selected.priority,
+        "expected_role_next": required_role,
+        "required_role": required_role,
+        "selected_action": action,
+        "action": action,
+        "required_profile": req_profile,
+        "required_namespace": req_ns,
+        "pinned": {
+            "kind": selected.kind,
+            "number": selected.number,
+            "head_sha": selected.head_sha,
+            "issue_number": selected.number if selected.kind == "issue" else None,
+            "pr_number": selected.number if selected.kind == "pr" else None,
+        },
+        "reason_selected": (
+            f"highest-priority eligible candidate under allocation_mode="
+            f"'{allocation_mode}' (active_role={active_role}, "
+            f"required_role={required_role}, action={action})"
+        ),
+    }
+
+
 def expected_role_for_candidate(c: WorkCandidate) -> str:
    """ADR §5.3 routing: which role should take this work next."""
    if c.kind == "pr":
@@ -289,6 +436,7 @@ def classify_skip(
    role: str,
    terminal_pr: int | None,
    claim_ownership: str | None = None,
+    allocation_mode: str | None = None,
 ) -> str | None:
    """Return skip reason, or None if candidate is selectable for *role*.

@@ -297,7 +445,12 @@ def classify_skip(
    and unknown claims are excluded so one session's in-progress task can never
    blockade the queue for a different controller; ``own`` stays selectable so
    a controller can resume its own work.
+
+    *allocation_mode* (#840): ``cross_role`` (controller default) ranks the full
+    queue and selects the highest-priority eligible item for any downstream
+    role. ``role_scoped`` retains prior role-match filtering.
    """
+    mode = resolve_allocation_mode(role, allocation_mode)
    if c.state in ("merged", "closed"):
        return f"{c.kind}#{c.number} is {c.state}; never assign"
    if c.blocked or "status:blocked" in c.labels:
@@ -322,34 +475,58 @@ def classify_skip(
    if c.kind == "pr" and not (c.head_sha or "").strip():
        return f"pr#{c.number} missing head_sha pin"

+    expected = expected_role_for_candidate(c)
+
    # Terminal path first: when an active terminal PR exists, only that PR
-    # (or controller diagnosis) is assignable for review-path roles.
+    # is assignable for review-path roles (or for work whose expected role is
+    # review/merge under cross_role selection).
    if terminal_pr is not None and c.kind == "pr" and c.number != terminal_pr:
-        if role in (ROLE_REVIEWER, ROLE_MERGER):
+        terminal_roles = (ROLE_REVIEWER, ROLE_MERGER)
+        if mode == ALLOCATION_MODE_CROSS_ROLE:
+            if expected in terminal_roles:
+                return (
+                    f"pr#{c.number} skipped: active terminal-review lock on "
+                    f"PR #{terminal_pr} must be resolved first"
+                )
+        elif role in terminal_roles:
            return (
                f"pr#{c.number} skipped: active terminal-review lock on "
                f"PR #{terminal_pr} must be resolved first"
            )

-    expected = expected_role_for_candidate(c)
-    if role == ROLE_CONTROLLER:
-        # Controller may inspect anything but only assigns diagnosis targets
-        # when contaminated / blocked.
+    if mode == ALLOCATION_MODE_CROSS_ROLE:
+        # Cross-role controller selection: eligibility only — no active-role
+        # match filter. The selection payload names required_role.
+        pass
+    elif role == ROLE_CONTROLLER:
+        # Legacy diagnosis-only controller path (role_scoped): only reconciler-
+        # needed targets. Prefer cross_role for generic queue allocation.
        if expected == ROLE_RECONCILER or c.blocked:
            return None
-        return f"{c.kind}#{c.number} does not require controller (expected {expected})"
-
-    if role != expected:
+        return (
+            f"{c.kind}#{c.number} does not require controller "
+            f"(expected {expected})"
+        )
+    elif role != expected:
        return (
            f"{c.kind}#{c.number} expects role '{expected}', active role is '{role}'"
        )

    # Ready-gate for issues: prefer status:ready when labels present.
+    # Applies for author-bound work in both modes (cross_role only gates
+    # author-expected issues so reconciler/reviewer PRs stay selectable).
    if c.kind == "issue" and c.labels:
-        if "status:ready" not in c.labels and "status:in-progress" not in c.labels:
-            # Allow unlabeled open issues; only skip explicit non-ready states.
+        gate_role = expected if mode == ALLOCATION_MODE_CROSS_ROLE else role
+        if gate_role in (ROLE_AUTHOR, ROLE_CONTROLLER):
+            if (
+                "status:ready" not in c.labels
+                and "status:in-progress" not in c.labels
+            ):
                if any(l.startswith("status:") for l in c.labels):
-                return f"issue#{c.number} not status:ready ({','.join(c.labels)})"
+                    return (
+                        f"issue#{c.number} not status:ready "
+                        f"({','.join(c.labels)})"
+                    )
    return None


@@ -501,12 +678,19 @@ def allocate_next_work(
    claims: Mapping[tuple[str, int], dict[str, Any]] | None = None,
    exclude_issue_numbers: Sequence[int] | None = None,
    expected_candidate_set_fingerprint: str | None = None,
+    allocation_mode: str | None = None,
 ) -> dict[str, Any]:
    """Select and optionally reserve the next work unit via control-plane DB.

    *apply=False* (default): dry-run selection only — no lease/assignment.
    *apply=True*: atomic ``assign_and_lease`` for the selected candidate.

+    *allocation_mode* (#840): ``cross_role`` (default for controller) inspects
+    the complete queue and returns one authoritative selection naming the
+    required downstream role/profile/action. ``role_scoped`` keeps prior
+    per-role filtering. Controller routes only — never grants author/reviewer/
+    merger/reconciler mutation rights to the controller session.
+
    *exclude_issue_numbers* (#776): numbers removed before ranking. Omitted /
    empty preserves prior behavior.

@@ -541,6 +725,19 @@ def allocate_next_work(
            "substrate": "control_plane_db",
        }

+    try:
+        mode = resolve_allocation_mode(role_norm, allocation_mode)
+    except ControlPlaneError as exc:
+        return {
+            "success": False,
+            "outcome": OUTCOME_ROLE_INELIGIBLE,
+            "reasons": [str(exc)],
+            "skipped": [],
+            "assignment": None,
+            "substrate": "control_plane_db",
+            "allocation_mode": (allocation_mode or "").strip() or None,
+        }
+
    session_id = (session_id or "").strip() or f"alloc-{uuid.uuid4().hex[:12]}"
    try:
        db.upsert_session(
@@ -748,6 +945,7 @@ def allocate_next_work(
            role=role_norm,
            terminal_pr=terminal_pr,
            claim_ownership=ownership,
+            allocation_mode=mode,
        )
        if reason:
            is_claim_skip = SKIP_CLAIMED_BY_OTHER_SESSION in reason
@@ -828,6 +1026,10 @@ def allocate_next_work(
            "outcome": outcome,
            "apply": bool(apply),
            "role": role_norm,
+            "allocation_mode": mode,
+            "routing_role": role_norm,
+            "required_role": None,
+            "selected_action": None,
            "profile_name": profile_name,
            "username": username,
            "session_id": session_id,
@@ -840,6 +1042,12 @@ def allocate_next_work(
            "skipped": [s.as_dict() for s in skipped],
            "terminal_pr": terminal_pr,
            "assignment": None,
+            "allocation_evidence": {
+                "mode": "empty",
+                "allocation_mode": mode,
+                "lease_created": False,
+                "selection_policy": SELECTION_POLICY,
+            },
            "substrate": "control_plane_db",
            "file_lock_only": False,
            "comment_lease_only": False,
@@ -852,25 +1060,37 @@ def allocate_next_work(
            "owner_session_id": owner_session_id,
            "downstream_note": (
                "#612 incident bridge remains downstream of #600; "
-                "allocator never assigns raw monitoring incidents"
+                "allocator never assigns raw monitoring incidents; "
+                "controller routes only under cross_role (#840)"
            ),
        }

    expected_role = expected_role_for_candidate(selected)
-    allowed, forbidden = role_actions(role_norm)
-    selection = {
-        "kind": selected.kind,
-        "number": selected.number,
-        "title": selected.title,
-        "labels": list(selected.labels),
-        "head_sha": selected.head_sha,
-        "priority": selected.priority,
-        "expected_role_next": expected_role,
-        "reason_selected": (
-            f"highest-priority candidate for role '{role_norm}' "
-            f"(expected_role={expected_role})"
-        ),
-    }
+    # Cross-role: lease/action matrix follows the required downstream role so
+    # evidence names the worker that must act. Controller session still owns
+    # the routing decision; mutation isolation is enforced by role gates on
+    # mutation tools (controller profile lacks author/review/merge ops).
+    lease_role = (
+        expected_role if mode == ALLOCATION_MODE_CROSS_ROLE else role_norm
+    )
+    allowed, forbidden = role_actions(lease_role)
+    # Controller must never receive mutation-class rights via cross-role apply.
+    if role_norm == ROLE_CONTROLLER:
+        ctrl_allowed, ctrl_forbidden = role_actions(ROLE_CONTROLLER)
+        # Keep controller session capability evidence separate from lease_role.
+        controller_allowed_actions = ctrl_allowed
+        controller_forbidden_actions = ctrl_forbidden
+    else:
+        controller_allowed_actions = allowed
+        controller_forbidden_actions = forbidden
+
+    selection = build_selection_dict(
+        selected,
+        active_role=role_norm,
+        required_role=expected_role,
+        profile_name=profile_name,
+        allocation_mode=mode,
+    )

    if not apply:
        return {
@@ -878,6 +1098,12 @@ def allocate_next_work(
            "outcome": OUTCOME_PREVIEW,
            "apply": False,
            "role": role_norm,
+            "allocation_mode": mode,
+            "routing_role": role_norm,
+            "required_role": expected_role,
+            "selected_action": selection["selected_action"],
+            "required_profile": selection["required_profile"],
+            "required_namespace": selection["required_namespace"],
            "profile_name": profile_name,
            "username": username,
            "session_id": session_id,
@@ -893,6 +1119,12 @@ def allocate_next_work(
            "skipped": [s.as_dict() for s in skipped],
            "terminal_pr": terminal_pr,
            "assignment": None,
+            "allocation_evidence": {
+                "mode": "preview",
+                "allocation_mode": mode,
+                "lease_created": False,
+                "selection_policy": SELECTION_POLICY,
+            },
            "substrate": "control_plane_db",
            "file_lock_only": False,
            "comment_lease_only": False,
@@ -902,9 +1134,12 @@ def allocate_next_work(
            "controller_excluded": list(controller_excluded),
            "exclude_issue_numbers": list(exclude_nums),
            "candidate_set_fingerprint": cas_fp,
+            "controller_allowed_actions": list(controller_allowed_actions),
+            "controller_forbidden_actions": list(controller_forbidden_actions),
            "downstream_note": (
                "#612 incident bridge remains downstream of #600; "
-                "allocator never assigns raw monitoring incidents"
+                "allocator never assigns raw monitoring incidents; "
+                "controller routes only under cross_role (#840)"
            ),
        }

@@ -913,7 +1148,7 @@ def allocate_next_work(
    try:
        kwargs: dict[str, Any] = {
            "session_id": session_id,
-            "role": role_norm,
+            "role": lease_role,
            "remote": remote,
            "org": org,
            "repo": repo,
@@ -992,11 +1227,27 @@ def allocate_next_work(
        }

    # assigned
+    lease_proof = {
+        "assignment_id": result.assignment_id,
+        "lease_id": result.lease_id,
+        "expires_at": result.expires_at,
+        "expected_head_sha": result.expected_head_sha,
+        "allowed_actions": list(result.allowed_actions),
+        "forbidden_actions": list(result.forbidden_actions),
+        "lease_role": lease_role,
+        "source": "control_plane_db.assign_and_lease",
+    }
    return {
        "success": True,
        "outcome": OUTCOME_ASSIGNED,
        "apply": True,
        "role": role_norm,
+        "allocation_mode": mode,
+        "routing_role": role_norm,
+        "required_role": expected_role,
+        "selected_action": selection["selected_action"],
+        "required_profile": selection["required_profile"],
+        "required_namespace": selection["required_namespace"],
        "profile_name": profile_name,
        "username": username,
        "session_id": session_id,
@@ -1012,16 +1263,16 @@ def allocate_next_work(
        "skipped": [s.as_dict() for s in skipped],
        "terminal_pr": terminal_pr,
        "assignment": result.as_dict(),
-        "lease_proof": {
-            "assignment_id": result.assignment_id,
-            "lease_id": result.lease_id,
-            "expires_at": result.expires_at,
-            "expected_head_sha": result.expected_head_sha,
-            "allowed_actions": list(result.allowed_actions),
-            "forbidden_actions": list(result.forbidden_actions),
-            "source": "control_plane_db.assign_and_lease",
+        "lease_proof": lease_proof,
+        "allocation_evidence": {
+            "mode": "assigned",
+            "allocation_mode": mode,
+            "lease_created": True,
+            "lease_role": lease_role,
+            "lease_proof": lease_proof,
+            "selection_policy": SELECTION_POLICY,
        },
-        "next_valid_command": _next_command(role_norm, selected),
+        "next_valid_command": _next_command(lease_role, selected),
        "substrate": "control_plane_db",
        "file_lock_only": False,
        "comment_lease_only": False,
@@ -1031,9 +1282,12 @@ def allocate_next_work(
        "controller_excluded": list(controller_excluded),
        "exclude_issue_numbers": list(exclude_nums),
        "candidate_set_fingerprint": cas_fp,
+        "controller_allowed_actions": list(controller_allowed_actions),
+        "controller_forbidden_actions": list(controller_forbidden_actions),
        "downstream_note": (
            "#612 incident bridge remains downstream of #600; "
-            "allocator never assigns raw monitoring incidents"
+            "allocator never assigns raw monitoring incidents; "
+            "controller routes only under cross_role (#840)"
        ),
    }

@@ -0,0 +1,892 @@
+"""ARCH-01 Foundation Slice A — atomic platform installation + authority kernel (#822).
+
+Parents: #820, #821. **First implementation leaf of the ARCH-01 program.**
+
+This module implements the smallest executable ARCH-01 foundation:
+
+* a connection-bound authenticated actor context (``cp_actor_*`` /
+  ``cp_operation_mode`` / ``cp_context_epoch`` SQLite scalar functions that SQL
+  may *read* but can never *set* — ``[TRUSTED-SERVICE]`` authenticity);
+* an immutable authority-dominance lattice with an exact seeded tuple set
+  (``[SCHEMA]``);
+* the principal-equivalence root (a class exists *before* its first principal;
+  ``principals.current_class_id`` is ``NOT NULL``; ``[SCHEMA]``);
+* a single-transaction platform installation that seeds the initial
+  ``platform.bootstrap`` grant and an immutable ``installed`` marker, validated
+  by a fail-closed ``install_state`` ``BEFORE INSERT`` trigger (``[SCHEMA]``).
+
+Everything else in the ARCH-01/02/04 program (evidence stores, repository
+bindings, workspaces, PostgreSQL parity, full grant succession, full principal
+merge) is out of scope here and tracked in its own issue — see #822 §5/§17.
+
+**Readiness / production posture.** This subsystem is *disabled by default*.
+Nothing in the running MCP server imports or enables it. It becomes a security
+boundary only once its readiness checks (the ACs in #822) pass in the target
+environment. Instantiating :class:`PlatformKernel` creates an isolated SQLite
+database and never touches the operational control-plane store.
+
+Enforcement classification (per #820 vocabulary):
+
+* ``[TRUSTED-SERVICE]`` — actor-context authenticity: the scalar functions are
+  registered by the trusted Python process; SQL cannot define or redefine them.
+* ``[SCHEMA]`` — fail-closed aborts, the dominance/immutability/NOT-NULL-class/
+  last-active-grant invariants, enforced by CHECK/FK/trigger.
+* ``[RUNTIME-ADAPTER]`` — *none* in this slice.
+
+SQLite-first. ``BEGIN IMMEDIATE`` serializes concurrent installs and concurrent
+grant/revoke on the singleton invariant row. PostgreSQL parity is a distinct
+issue (#827); this module does **not** claim it.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import threading
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Iterator, Optional
+
+# --------------------------------------------------------------------------- #
+# Closed enumerations (#822 §4).
+# --------------------------------------------------------------------------- #
+
+ACTOR_KINDS = ("operator", "supervisor", "service", "installer")
+OPERATION_MODES = ("normal", "install", "merge", "internal_service")
+
+# Exact seeded authority-dominance tuple set (#822 §4). This set is normative:
+# the install-state trigger rejects any missing, additional, or malformed tuple.
+DOMINANCE_TUPLES = (
+    ("platform.bootstrap", "platform.bootstrap"),
+    ("platform.bootstrap", "project.admin"),
+    ("platform.bootstrap", "supervisor.root.establish"),
+    ("supervisor.root", "supervisor.register"),
+    ("supervisor.root", "supervisor.verify"),
+    ("supervisor.root", "supervisor.recover"),
+)
+
+# The distinguished operator-key issuer seeded during install.
+DISTINGUISHED_ISSUER_KIND = "operator-key"
+DISTINGUISHED_ISSUER_ID = "platform.bootstrap.operator-key"
+
+# Structured result codes (#822 §10).
+INSTALLED = "INSTALLED"
+ALREADY_INSTALLED = "ALREADY_INSTALLED"
+INVALID_ACTOR_CONTEXT = "INVALID_ACTOR_CONTEXT"
+INVALID_BOOTSTRAP_STATE = "INVALID_BOOTSTRAP_STATE"
+DOMINANCE_SET_MISMATCH = "DOMINANCE_SET_MISMATCH"
+AUTHORIZATION_DENIED = "AUTHORIZATION_DENIED"
+CONCURRENT_INSTALLATION_LOST = "CONCURRENT_INSTALLATION_LOST"
+
+# Required audit events (#822 §14).
+EVT_PLATFORM_INSTALLED = "platform_installed"
+EVT_GRANT_CREATED = "platform_grant_created"
+EVT_GRANT_REVOKED = "platform_grant_revoked"
+EVT_PRINCIPAL_REGISTERED = "principal_registered"
+
+SCHEMA_VERSION = 1
+
+DB_PATH_ENV = "ARCH01_PLATFORM_DB"
+
+
+class PlatformKernelError(RuntimeError):
+    """Base class for structured, code-bearing kernel failures."""
+
+    def __init__(self, code: str, message: str = "") -> None:
+        super().__init__(message or code)
+        self.code = code
+
+
+class ActorContextError(PlatformKernelError):
+    """Raised when a mutation is attempted without a valid actor context."""
+
+
+# --------------------------------------------------------------------------- #
+# Schema (#822 §6). Tables + fail-closed triggers.
+#
+# Every *mutating* trigger opens with the actor protocol: read the context
+# epoch, read the actor fields, and abort unless the context is present,
+# non-null, mode/kind well-formed, and epoch-consistent with the active
+# transaction. The scalar functions ``cp_*`` are registered from Python only;
+# SQL has no statement that can set them, which is the trusted-service boundary.
+# --------------------------------------------------------------------------- #
+
+_ACTOR_KINDS_SQL = ", ".join("'%s'" % k for k in ACTOR_KINDS)
+_OP_MODES_SQL = ", ".join("'%s'" % m for m in OPERATION_MODES)
+
+# Actor-protocol predicate: TRUE when the context is INVALID and the trigger
+# must abort. ``cp_actor_context_valid()`` folds "present + non-expired +
+# live-epoch == bound-epoch" (the read/re-read epoch equality of #822 §4) into
+# one trusted-service answer; the remaining reads assert field well-formedness.
+_INVALID_ACTOR = (
+    "cp_actor_context_valid() IS NOT 1 "
+    "OR cp_context_epoch() IS NULL "
+    "OR cp_actor_principal() IS NULL "
+    "OR cp_actor_kind() NOT IN (%s) "
+    "OR cp_operation_mode() NOT IN (%s)" % (_ACTOR_KINDS_SQL, _OP_MODES_SQL)
+)
+
+_ACTOR_GUARD = (
+    "SELECT CASE WHEN (%s) "
+    "THEN RAISE(ABORT, 'INVALID_ACTOR_CONTEXT') END;" % _INVALID_ACTOR
+)
+
+# require_installed: abort a privileged mutation when there is no install
+# marker and we are not currently installing (#822 §4).
+_REQUIRE_INSTALLED = (
+    "SELECT CASE WHEN ((SELECT COUNT(*) FROM install_state) = 0 "
+    "AND cp_operation_mode() <> 'install') "
+    "THEN RAISE(ABORT, 'NOT_INSTALLED') END;"
+)
+
+_SCHEMA_SQL = f"""
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS arch01_meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+
+-- Equivalence classes are created BEFORE their first principal (#822 §4).
+CREATE TABLE IF NOT EXISTS principal_equivalence_classes (
+    class_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS authoritative_issuers (
+    issuer_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    issuer_kind TEXT NOT NULL,
+    issuer_ref TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    UNIQUE (issuer_kind, issuer_ref)
+);
+
+-- current_class_id is NOT NULL: a principal cannot exist without a class
+-- (#822 AC6). issuer_id is nullable ONLY for the installer during install
+-- (#822 AC7), enforced by trg_principals_null_issuer below.
+CREATE TABLE IF NOT EXISTS principals (
+    principal_id TEXT PRIMARY KEY,
+    actor_kind TEXT NOT NULL CHECK (actor_kind IN ({_ACTOR_KINDS_SQL})),
+    current_class_id INTEGER NOT NULL REFERENCES principal_equivalence_classes(class_id),
+    issuer_id INTEGER REFERENCES authoritative_issuers(issuer_id),
+    registered_by TEXT REFERENCES principals(principal_id),
+    created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS authority_dominance (
+    dominant TEXT NOT NULL,
+    subordinate TEXT NOT NULL,
+    PRIMARY KEY (dominant, subordinate)
+);
+
+CREATE TABLE IF NOT EXISTS platform_bootstrap_seed (
+    seed_id INTEGER PRIMARY KEY CHECK (seed_id = 1),
+    installer_principal_id TEXT NOT NULL REFERENCES principals(principal_id),
+    created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS platform_bootstrap_grants (
+    grant_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    grantee_principal_id TEXT NOT NULL REFERENCES principals(principal_id),
+    granted_by TEXT REFERENCES principals(principal_id),
+    active INTEGER NOT NULL DEFAULT 1 CHECK (active IN (0, 1)),
+    created_at TEXT NOT NULL,
+    revoked_at TEXT
+);
+
+-- Singleton row; active_count floored at 1 by CHECK so the last active grant
+-- can never be revoked (#822 AC11).
+CREATE TABLE IF NOT EXISTS platform_active_invariant (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    active_count INTEGER NOT NULL CHECK (active_count >= 1)
+);
+
+-- The immutable install marker; inserted LAST in the install transaction.
+CREATE TABLE IF NOT EXISTS install_state (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    marker TEXT NOT NULL CHECK (marker = 'installed'),
+    installed_at TEXT NOT NULL
+);
+
+-- Append-only (#822 AC14).
+CREATE TABLE IF NOT EXISTS audit_records (
+    audit_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    event TEXT NOT NULL,
+    principal_id TEXT,
+    detail TEXT,
+    created_at TEXT NOT NULL
+);
+
+-- ------------------------------------------------------------------------- --
+-- Actor protocol on every mutating trigger (#822 §4, [SCHEMA] fail-closed).
+-- ------------------------------------------------------------------------- --
+
+CREATE TRIGGER IF NOT EXISTS trg_classes_actor
+BEFORE INSERT ON principal_equivalence_classes
+BEGIN
+    {_ACTOR_GUARD}
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_issuers_actor
+BEFORE INSERT ON authoritative_issuers
+BEGIN
+    {_ACTOR_GUARD}
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_principals_actor
+BEFORE INSERT ON principals
+BEGIN
+    {_ACTOR_GUARD}
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_dominance_actor
+BEFORE INSERT ON authority_dominance
+BEGIN
+    {_ACTOR_GUARD}
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_seed_actor
+BEFORE INSERT ON platform_bootstrap_seed
+BEGIN
+    {_ACTOR_GUARD}
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_grants_actor_insert
+BEFORE INSERT ON platform_bootstrap_grants
+BEGIN
+    {_ACTOR_GUARD}
+    {_REQUIRE_INSTALLED}
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_grants_actor_update
+BEFORE UPDATE ON platform_bootstrap_grants
+BEGIN
+    {_ACTOR_GUARD}
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_invariant_actor_insert
+BEFORE INSERT ON platform_active_invariant
+BEGIN
+    {_ACTOR_GUARD}
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_invariant_actor_update
+BEFORE UPDATE ON platform_active_invariant
+BEGIN
+    {_ACTOR_GUARD}
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_audit_actor
+BEFORE INSERT ON audit_records
+BEGIN
+    {_ACTOR_GUARD}
+END;
+
+-- ------------------------------------------------------------------------- --
+-- NOT-NULL-issuer exception for the installer only (#822 AC7).
+-- A NULL issuer_id is accepted solely for an installer principal during
+-- install mode, before the marker exists; any other NULL-issuer principal is
+-- rejected. install-time issuer linkage (installer -> distinguished issuer)
+-- is applied by a later UPDATE, permitted while no marker exists.
+-- ------------------------------------------------------------------------- --
+
+CREATE TRIGGER IF NOT EXISTS trg_principals_null_issuer
+BEFORE INSERT ON principals
+WHEN NEW.issuer_id IS NULL
+BEGIN
+    SELECT CASE WHEN NOT (
+        NEW.actor_kind = 'installer'
+        AND cp_operation_mode() = 'install'
+        AND (SELECT COUNT(*) FROM install_state) = 0
+        AND (SELECT COUNT(*) FROM principals WHERE issuer_id IS NULL) = 0
+    ) THEN RAISE(ABORT, 'INVALID_BOOTSTRAP_STATE') END;
+END;
+
+-- ------------------------------------------------------------------------- --
+-- Post-install immutability of the authority root (#822 §4, AC9).
+-- Registration fields freeze only AFTER the marker exists, so the install
+-- transaction's own installer issuer-linkage UPDATE is permitted.
+-- ------------------------------------------------------------------------- --
+
+CREATE TRIGGER IF NOT EXISTS trg_principals_frozen_update
+BEFORE UPDATE ON principals
+WHEN (SELECT COUNT(*) FROM install_state) > 0
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_PRINCIPAL');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_principals_frozen_delete
+BEFORE DELETE ON principals
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_PRINCIPAL');
+END;
+
+-- Distinguished issuer identity is immutable once written.
+CREATE TRIGGER IF NOT EXISTS trg_issuers_immutable_update
+BEFORE UPDATE ON authoritative_issuers
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_ISSUER');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_issuers_immutable_delete
+BEFORE DELETE ON authoritative_issuers
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_ISSUER');
+END;
+
+-- The dominance lattice is immutable once seeded.
+CREATE TRIGGER IF NOT EXISTS trg_dominance_immutable_update
+BEFORE UPDATE ON authority_dominance
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_DOMINANCE');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_dominance_immutable_delete
+BEFORE DELETE ON authority_dominance
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_DOMINANCE');
+END;
+
+-- The bootstrap seed is immutable once written.
+CREATE TRIGGER IF NOT EXISTS trg_seed_immutable_update
+BEFORE UPDATE ON platform_bootstrap_seed
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_SEED');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_seed_immutable_delete
+BEFORE DELETE ON platform_bootstrap_seed
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_SEED');
+END;
+
+-- The install marker is immutable once written.
+CREATE TRIGGER IF NOT EXISTS trg_install_state_immutable_update
+BEFORE UPDATE ON install_state
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_INSTALL_STATE');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_install_state_immutable_delete
+BEFORE DELETE ON install_state
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_INSTALL_STATE');
+END;
+
+-- Grants: identity is immutable; the ONLY permitted mutation is a single
+-- active 1 -> 0 revocation (#822 §4 initial-grant identity immutability +
+-- grant/revoke). Reactivation and identity edits are rejected.
+CREATE TRIGGER IF NOT EXISTS trg_grants_identity_frozen
+BEFORE UPDATE ON platform_bootstrap_grants
+WHEN NOT (
+    NEW.grant_id = OLD.grant_id
+    AND NEW.grantee_principal_id = OLD.grantee_principal_id
+    AND NEW.granted_by IS OLD.granted_by
+    AND NEW.created_at = OLD.created_at
+    AND OLD.active = 1
+    AND NEW.active = 0
+)
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_GRANT');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_grants_no_delete
+BEFORE DELETE ON platform_bootstrap_grants
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_GRANT');
+END;
+
+-- audit_records is append-only.
+CREATE TRIGGER IF NOT EXISTS trg_audit_immutable_update
+BEFORE UPDATE ON audit_records
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_AUDIT');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_audit_immutable_delete
+BEFORE DELETE ON audit_records
+BEGIN
+    SELECT RAISE(ABORT, 'IMMUTABLE_AUDIT');
+END;
+
+-- ------------------------------------------------------------------------- --
+-- install_state BEFORE INSERT: validate the whole bootstrap atomically
+-- (#822 §4, AC4). Each dominance tuple is checked individually; a missing,
+-- additional, or malformed tuple -> DOMINANCE_SET_MISMATCH. The seed<->installer
+-- link, the single active NULL-grantor installer grant, the installer's
+-- non-NULL issuer, the active invariant, and "no extra principal created under
+-- the NULL-issuer exception" -> INVALID_BOOTSTRAP_STATE.
+-- ------------------------------------------------------------------------- --
+
+CREATE TRIGGER IF NOT EXISTS trg_install_state_validate
+BEFORE INSERT ON install_state
+BEGIN
+    SELECT CASE WHEN NOT (
+        (SELECT COUNT(*) FROM authority_dominance) = {len(DOMINANCE_TUPLES)}
+        AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='platform.bootstrap')
+        AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='project.admin')
+        AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='supervisor.root.establish')
+        AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.register')
+        AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.verify')
+        AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.recover')
+    ) THEN RAISE(ABORT, 'DOMINANCE_SET_MISMATCH') END;
+
+    SELECT CASE WHEN NOT (
+        (SELECT COUNT(*) FROM platform_bootstrap_seed) = 1
+        AND (SELECT COUNT(*) FROM principals) = 1
+        AND (SELECT actor_kind FROM principals
+             WHERE principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1)
+            ) = 'installer'
+        AND (SELECT issuer_id FROM principals
+             WHERE principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1)
+            ) IS NOT NULL
+        AND (SELECT COUNT(*) FROM platform_bootstrap_grants
+             WHERE granted_by IS NULL AND active = 1
+               AND grantee_principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1)
+            ) = 1
+        AND (SELECT COUNT(*) FROM platform_bootstrap_grants) = 1
+        AND (SELECT active_count FROM platform_active_invariant WHERE id = 1) = 1
+    ) THEN RAISE(ABORT, 'INVALID_BOOTSTRAP_STATE') END;
+END;
+"""
+
+
+def default_db_path() -> str:
+    return os.environ.get(
+        DB_PATH_ENV,
+        os.path.expanduser("~/.cache/gitea-tools/arch01/platform.sqlite3"),
+    )
+
+
+def _utc_now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+@dataclass(frozen=True)
+class OperationResult:
+    """Structured result of a kernel operation (#822 §10)."""
+
+    code: str
+    detail: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.code in (INSTALLED, ALREADY_INSTALLED)
+
+
+@dataclass
+class _ActorContext:
+    principal: str
+    kind: str
+    mode: str
+    session: Optional[str]
+    bound_epoch: int
+    live_epoch: int
+    expired: bool = False
+
+
+class PlatformKernel:
+    """ARCH-01 authority kernel over a single SQLite connection.
+
+    The connection carries the trusted-service actor context: the ``cp_*``
+    scalar functions read the context this object holds. Only Python code here
+    can bind or clear it, so no SQL statement can assert an actor identity — the
+    trusted-service authenticity boundary of #822 §4.
+    """
+
+    def __init__(self, db_path: Optional[str] = None, *, busy_timeout_ms: int = 5000) -> None:
+        self.db_path = db_path or default_db_path()
+        if self.db_path != ":memory:":
+            parent = os.path.dirname(self.db_path)
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+        self._ctx: Optional[_ActorContext] = None
+        self._epoch_seq = 0
+        self._lock = threading.Lock()
+        # check_same_thread=False is safe: every mutation path is serialized
+        # by self._lock, so the connection is never used concurrently even when
+        # callers drive the kernel from different threads (concurrency tests).
+        self._conn = sqlite3.connect(
+            self.db_path, isolation_level=None, check_same_thread=False
+        )
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._conn.execute(f"PRAGMA busy_timeout = {int(busy_timeout_ms)}")
+        self._register_actor_functions()
+        self._migrate()
+
+    # -- trusted-service actor functions ---------------------------------- #
+
+    def _register_actor_functions(self) -> None:
+        c = self._conn
+        c.create_function("cp_actor_principal", 0, lambda: self._ctx.principal if self._ctx else None)
+        c.create_function("cp_actor_kind", 0, lambda: self._ctx.kind if self._ctx else None)
+        c.create_function("cp_operation_mode", 0, lambda: self._ctx.mode if self._ctx else None)
+        c.create_function("cp_service_session", 0, lambda: self._ctx.session if self._ctx else None)
+        c.create_function("cp_context_epoch", 0, self._fn_context_epoch)
+        # Trusted-service helper: folds present + non-expired + epoch-consistent
+        # into the read/re-read epoch equality of #822 §4.
+        c.create_function("cp_actor_context_valid", 0, self._fn_context_valid)
+
+    def _fn_context_epoch(self) -> Optional[int]:
+        if self._ctx is None or self._ctx.expired:
+            return None
+        return self._ctx.live_epoch
+
+    def _fn_context_valid(self) -> int:
+        ctx = self._ctx
+        if ctx is None or ctx.expired:
+            return 0
+        # read/re-read epoch equality: a context whose live epoch has drifted
+        # from the epoch it was bound to (a stale/replaced connection context)
+        # is not bound to the active transaction and fails closed.
+        if ctx.live_epoch != ctx.bound_epoch:
+            return 0
+        if ctx.principal is None:
+            return 0
+        if ctx.kind not in ACTOR_KINDS or ctx.mode not in OPERATION_MODES:
+            return 0
+        return 1
+
+    # -- context lifecycle ------------------------------------------------ #
+
+    @contextmanager
+    def actor_context(
+        self, principal: str, kind: str, mode: str, session: Optional[str] = None
+    ) -> Iterator[None]:
+        """Bind a trusted actor context for the duration of the block."""
+        prev = self._ctx
+        self._epoch_seq += 1
+        epoch = self._epoch_seq
+        self._ctx = _ActorContext(
+            principal=principal, kind=kind, mode=mode, session=session,
+            bound_epoch=epoch, live_epoch=epoch,
+        )
+        try:
+            yield
+        finally:
+            self._ctx = prev
+
+    def _clear_context(self) -> None:
+        self._ctx = None
+
+    # -- migration -------------------------------------------------------- #
+
+    def _migrate(self) -> None:
+        self._conn.executescript(_SCHEMA_SQL)
+        self._conn.execute(
+            "INSERT OR IGNORE INTO arch01_meta(key, value) VALUES ('schema_version', ?)",
+            (str(SCHEMA_VERSION),),
+        )
+        self._conn.execute(
+            "INSERT OR IGNORE INTO arch01_meta(key, value) VALUES "
+            "('architecture', 'ARCH-01 Slice A: atomic install + authority kernel (#822); "
+            "disabled by default until readiness checks pass')"
+        )
+
+    # -- introspection ---------------------------------------------------- #
+
+    def is_installed(self) -> bool:
+        row = self._conn.execute("SELECT COUNT(*) FROM install_state").fetchone()
+        return bool(row[0])
+
+    def active_grant_count(self) -> int:
+        row = self._conn.execute(
+            "SELECT active_count FROM platform_active_invariant WHERE id = 1"
+        ).fetchone()
+        return int(row[0]) if row else 0
+
+    def audit_events(self) -> list[str]:
+        return [
+            r[0]
+            for r in self._conn.execute(
+                "SELECT event FROM audit_records ORDER BY audit_id"
+            ).fetchall()
+        ]
+
+    def close(self) -> None:
+        self._conn.close()
+
+    # -- operations ------------------------------------------------------- #
+
+    def install_platform(
+        self,
+        installer_principal_id: str = "platform.installer",
+        *,
+        session: Optional[str] = None,
+    ) -> OperationResult:
+        """Single atomic install transaction (#822 §4/§7).
+
+        ``BEGIN IMMEDIATE`` serializes concurrent installs; the loser rechecks
+        the marker and returns ``ALREADY_INSTALLED``, or — if it never acquires
+        the write lock — ``CONCURRENT_INSTALLATION_LOST``. On any stage failure
+        the whole transaction rolls back leaving no partial rows (AC3/AC5).
+        """
+        now = _utc_now_iso()
+        with self._lock:
+            try:
+                self._conn.execute("BEGIN IMMEDIATE")
+            except sqlite3.OperationalError as exc:
+                if "locked" in str(exc).lower() or "busy" in str(exc).lower():
+                    return OperationResult(CONCURRENT_INSTALLATION_LOST, str(exc))
+                raise
+            try:
+                if self.is_installed():
+                    self._conn.execute("ROLLBACK")
+                    return OperationResult(ALREADY_INSTALLED, "install marker already present")
+
+                with self.actor_context(installer_principal_id, "installer", "install", session):
+                    c = self._conn
+                    # class -> installer principal (temporary NULL issuer)
+                    cur = c.execute(
+                        "INSERT INTO principal_equivalence_classes(created_at) VALUES (?)",
+                        (now,),
+                    )
+                    class_id = cur.lastrowid
+                    c.execute(
+                        "INSERT INTO principals"
+                        "(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
+                        "VALUES (?, 'installer', ?, NULL, ?, ?)",
+                        (installer_principal_id, class_id, installer_principal_id, now),
+                    )
+                    # distinguished operator-key issuer
+                    cur = c.execute(
+                        "INSERT INTO authoritative_issuers(issuer_kind, issuer_ref, created_at) "
+                        "VALUES (?, ?, ?)",
+                        (DISTINGUISHED_ISSUER_KIND, DISTINGUISHED_ISSUER_ID, now),
+                    )
+                    issuer_id = cur.lastrowid
+                    # link installer -> issuer (permitted pre-marker)
+                    c.execute(
+                        "UPDATE principals SET issuer_id = ? WHERE principal_id = ?",
+                        (issuer_id, installer_principal_id),
+                    )
+                    # dominance tuples
+                    c.executemany(
+                        "INSERT INTO authority_dominance(dominant, subordinate) VALUES (?, ?)",
+                        DOMINANCE_TUPLES,
+                    )
+                    # seed
+                    c.execute(
+                        "INSERT INTO platform_bootstrap_seed(seed_id, installer_principal_id, created_at) "
+                        "VALUES (1, ?, ?)",
+                        (installer_principal_id, now),
+                    )
+                    # initial grant (granted_by NULL, active)
+                    c.execute(
+                        "INSERT INTO platform_bootstrap_grants"
+                        "(grantee_principal_id, granted_by, active, created_at) "
+                        "VALUES (?, NULL, 1, ?)",
+                        (installer_principal_id, now),
+                    )
+                    # active invariant
+                    c.execute(
+                        "INSERT INTO platform_active_invariant(id, active_count) VALUES (1, 1)"
+                    )
+                    # audit rows for the security-sensitive operation
+                    c.execute(
+                        "INSERT INTO audit_records(event, principal_id, detail, created_at) "
+                        "VALUES (?, ?, ?, ?)",
+                        (EVT_PRINCIPAL_REGISTERED, installer_principal_id, "installer", now),
+                    )
+                    c.execute(
+                        "INSERT INTO audit_records(event, principal_id, detail, created_at) "
+                        "VALUES (?, ?, ?, ?)",
+                        (EVT_GRANT_CREATED, installer_principal_id, "initial platform.bootstrap grant", now),
+                    )
+                    # install marker LAST -> fires the whole-bootstrap validator
+                    c.execute(
+                        "INSERT INTO install_state(id, marker, installed_at) VALUES (1, 'installed', ?)",
+                        (now,),
+                    )
+                    c.execute(
+                        "INSERT INTO audit_records(event, principal_id, detail, created_at) "
+                        "VALUES (?, ?, ?, ?)",
+                        (EVT_PLATFORM_INSTALLED, installer_principal_id, "platform installed", now),
+                    )
+                self._conn.execute("COMMIT")
+                return OperationResult(INSTALLED, "platform installed")
+            except sqlite3.Error as exc:
+                self._safe_rollback()
+                return OperationResult(self._classify(exc), str(exc))
+
+    def register_principal(
+        self,
+        principal_id: str,
+        actor_kind: str,
+        issuer_ref: str,
+        *,
+        actor_principal: str,
+        actor_kind_ctx: str = "operator",
+        session: Optional[str] = None,
+    ) -> OperationResult:
+        """Atomically create an equivalence class and its first principal.
+
+        The class is inserted *before* the principal, and ``current_class_id``
+        is ``NOT NULL`` (#822 AC6): a principal can never exist classless.
+        The principal references an existing issuer (non-NULL); the temporary
+        NULL-issuer exception is reserved for the installer during install
+        (AC7).
+        """
+        if actor_kind not in ACTOR_KINDS:
+            return OperationResult(INVALID_BOOTSTRAP_STATE, f"bad actor_kind {actor_kind!r}")
+        now = _utc_now_iso()
+        with self._lock:
+            try:
+                self._conn.execute("BEGIN IMMEDIATE")
+            except sqlite3.OperationalError as exc:
+                return OperationResult(AUTHORIZATION_DENIED, str(exc))
+            try:
+                if not self.is_installed():
+                    self._conn.execute("ROLLBACK")
+                    return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed")
+                row = self._conn.execute(
+                    "SELECT issuer_id FROM authoritative_issuers WHERE issuer_ref = ?",
+                    (issuer_ref,),
+                ).fetchone()
+                if row is None:
+                    self._conn.execute("ROLLBACK")
+                    return OperationResult(INVALID_BOOTSTRAP_STATE, f"unknown issuer {issuer_ref!r}")
+                issuer_id = row[0]
+                with self.actor_context(actor_principal, actor_kind_ctx, "normal", session):
+                    cur = self._conn.execute(
+                        "INSERT INTO principal_equivalence_classes(created_at) VALUES (?)",
+                        (now,),
+                    )
+                    class_id = cur.lastrowid
+                    self._conn.execute(
+                        "INSERT INTO principals"
+                        "(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
+                        "VALUES (?, ?, ?, ?, ?, ?)",
+                        (principal_id, actor_kind, class_id, issuer_id, actor_principal, now),
+                    )
+                    self._conn.execute(
+                        "INSERT INTO audit_records(event, principal_id, detail, created_at) "
+                        "VALUES (?, ?, ?, ?)",
+                        (EVT_PRINCIPAL_REGISTERED, principal_id, actor_kind, now),
+                    )
+                self._conn.execute("COMMIT")
+                return OperationResult(INSTALLED, f"registered {principal_id}")
+            except sqlite3.Error as exc:
+                self._safe_rollback()
+                return OperationResult(self._classify(exc), str(exc))
+
+    def grant_platform_bootstrap(
+        self,
+        grantee_principal_id: str,
+        granted_by: str,
+        *,
+        actor_kind_ctx: str = "operator",
+        session: Optional[str] = None,
+    ) -> OperationResult:
+        """Create an additional active platform.bootstrap grant.
+
+        Serialized on the singleton invariant row via ``BEGIN IMMEDIATE``.
+        """
+        now = _utc_now_iso()
+        with self._lock:
+            try:
+                self._conn.execute("BEGIN IMMEDIATE")
+            except sqlite3.OperationalError as exc:
+                return OperationResult(AUTHORIZATION_DENIED, str(exc))
+            try:
+                if not self.is_installed():
+                    self._conn.execute("ROLLBACK")
+                    return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed")
+                with self.actor_context(granted_by, actor_kind_ctx, "normal", session):
+                    self._conn.execute(
+                        "INSERT INTO platform_bootstrap_grants"
+                        "(grantee_principal_id, granted_by, active, created_at) "
+                        "VALUES (?, ?, 1, ?)",
+                        (grantee_principal_id, granted_by, now),
+                    )
+                    self._conn.execute(
+                        "UPDATE platform_active_invariant SET active_count = active_count + 1 WHERE id = 1"
+                    )
+                    self._conn.execute(
+                        "INSERT INTO audit_records(event, principal_id, detail, created_at) "
+                        "VALUES (?, ?, ?, ?)",
+                        (EVT_GRANT_CREATED, grantee_principal_id, f"granted_by={granted_by}", now),
+                    )
+                self._conn.execute("COMMIT")
+                return OperationResult(INSTALLED, f"granted to {grantee_principal_id}")
+            except sqlite3.Error as exc:
+                self._safe_rollback()
+                return OperationResult(self._classify(exc), str(exc))
+
+    def revoke_platform_bootstrap(
+        self,
+        grant_id: int,
+        *,
+        actor_principal: str,
+        actor_kind_ctx: str = "operator",
+        session: Optional[str] = None,
+    ) -> OperationResult:
+        """Revoke an active grant, floored so the last one can never drop.
+
+        The ``active_count >= 1`` CHECK plus ``BEGIN IMMEDIATE`` serialization
+        make two concurrent revocations unable to remove the final active grant
+        (#822 AC11): the decrement that would reach zero fails and rolls back.
+        """
+        now = _utc_now_iso()
+        with self._lock:
+            try:
+                self._conn.execute("BEGIN IMMEDIATE")
+            except sqlite3.OperationalError as exc:
+                return OperationResult(AUTHORIZATION_DENIED, str(exc))
+            try:
+                if not self.is_installed():
+                    self._conn.execute("ROLLBACK")
+                    return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed")
+                row = self._conn.execute(
+                    "SELECT active, grantee_principal_id FROM platform_bootstrap_grants WHERE grant_id = ?",
+                    (grant_id,),
+                ).fetchone()
+                if row is None or row[0] != 1:
+                    self._conn.execute("ROLLBACK")
+                    return OperationResult(AUTHORIZATION_DENIED, "grant absent or already inactive")
+                grantee = row[1]
+                with self.actor_context(actor_principal, actor_kind_ctx, "normal", session):
+                    # Decrement first: the CHECK floor rejects dropping below 1,
+                    # aborting the whole revoke before the grant flips inactive.
+                    self._conn.execute(
+                        "UPDATE platform_active_invariant SET active_count = active_count - 1 WHERE id = 1"
+                    )
+                    self._conn.execute(
+                        "UPDATE platform_bootstrap_grants SET active = 0, revoked_at = ? WHERE grant_id = ?",
+                        (now, grant_id),
+                    )
+                    self._conn.execute(
+                        "INSERT INTO audit_records(event, principal_id, detail, created_at) "
+                        "VALUES (?, ?, ?, ?)",
+                        (EVT_GRANT_REVOKED, grantee, f"grant_id={grant_id}", now),
+                    )
+                self._conn.execute("COMMIT")
+                return OperationResult(INSTALLED, f"revoked grant {grant_id}")
+            except sqlite3.Error as exc:
+                self._safe_rollback()
+                return OperationResult(self._classify(exc), str(exc))
+
+    # -- helpers ---------------------------------------------------------- #
+
+    def _safe_rollback(self) -> None:
+        try:
+            self._conn.execute("ROLLBACK")
+        except sqlite3.Error:
+            pass
+
+    @staticmethod
+    def _classify(exc: sqlite3.Error) -> str:
+        msg = str(exc)
+        if "INVALID_ACTOR_CONTEXT" in msg:
+            return INVALID_ACTOR_CONTEXT
+        if "DOMINANCE_SET_MISMATCH" in msg:
+            return DOMINANCE_SET_MISMATCH
+        if "active_count" in msg or "CHECK constraint failed: platform_active_invariant" in msg:
+            # last-active-grant floor tripped
+            return AUTHORIZATION_DENIED
+        if any(tag in msg for tag in (
+            "INVALID_BOOTSTRAP_STATE", "IMMUTABLE_", "NOT_INSTALLED",
+        )):
+            return INVALID_BOOTSTRAP_STATE
+        return INVALID_BOOTSTRAP_STATE
@@ -234,12 +234,25 @@ def _effective_workspace_role() -> str:


 def _profile_role_kind(profile: dict) -> str:
-    """Resolve a profile's declared role before inferring from permissions."""
-    role = (profile.get("role") or profile.get("role_kind") or "").strip()
+    """Resolve a profile's declared role before inferring from permissions.
+
+    Declared ``role`` / ``role_kind`` always wins so a controller profile is
+    never reclassified as reconciler from permission inference (#840).
+    """
+    role = (profile.get("role") or profile.get("role_kind") or "").strip().lower()
    if role:
+        # Normalize aliases / case.
+        if "control" in role:
+            return "controller"
        return role
    profile_name = (profile.get("profile_name") or "").strip().lower()
-    for candidate in ("reconciler", "merger", "reviewer", "author"):
+    for candidate in (
+        "controller",
+        "reconciler",
+        "merger",
+        "reviewer",
+        "author",
+    ):
        if candidate in profile_name:
            return candidate
    return _role_kind(
@@ -15538,7 +15551,8 @@ def mcp_get_control_plane_guide(
    profile = get_profile()
    allowed = profile["allowed_operations"]
    forbidden = profile["forbidden_operations"]
-    role = _role_kind(allowed, forbidden)
+    # Prefer declared profile role so controller is not mislabeled reconciler (#840).
+    role = _profile_role_kind(profile)
    username = _authenticated_username(h)

    identity = {
@@ -15597,6 +15611,16 @@ def mcp_get_control_plane_guide(
            "user, and merging requires explicit operator authorization plus the "
            "'MERGE PR <n>' confirmation. "
            "Review and merge are separate workflow roles. A reviewer approval is not merge authorization.")
+    elif role == "controller":
+        guidance.append(
+            "Controller profile: route work via "
+            "gitea_route_task_session(task_type='process_work_queue') then "
+            "gitea_allocate_next_work (allocation_mode=cross_role by default). "
+            "The allocator returns exactly one authoritative selection with "
+            "required_role / required_profile / selected_action. Do not "
+            "implement, review, approve, or merge in this session — schedule "
+            "the matching role namespace instead. Dashboard output is "
+            "explanatory only and never replaces allocator selection.")
    elif role == "mixed":
        guidance.append(
            "WARNING: this profile allows both authoring and "
@@ -15806,7 +15830,8 @@ def gitea_whoami(
            "environment": profile.get("environment"),
            "service": profile.get("service"),
            "identity": profile.get("identity"),
-            "role": profile.get("role"),
+            "role": profile.get("role") or _profile_role_kind(profile),
+            "role_kind": _profile_role_kind(profile),
            "profile_address": profile.get("profile_path"),
            "execution_profile": profile.get("execution_profile"),
            "audit_label": profile.get("audit_label"),
@@ -20590,9 +20615,10 @@ def gitea_allocate_next_work(
    candidates_json: Any = None,
    exclude_issue_numbers: list[int] | None = None,
    expected_candidate_set_fingerprint: str | None = None,
+    allocation_mode: str | None = None,
    limit: int = 50,
 ) -> dict:
-    """Controller-owned next-work allocator using the #613 control-plane DB (#600).
+    """Controller-owned next-work allocator using the #613 control-plane DB (#600/#840).

    Workers must not self-select exclusive work under the standard multi-LLM
    workflow. Call this tool instead.
@@ -20602,6 +20628,14 @@ def gitea_allocate_next_work(
    ``ControlPlaneDB.assign_and_lease`` (never file locks or comment-only
    leases as the coordination source).

+    *allocation_mode* (#840): when the active role is controller (or mode is
+    ``cross_role``), inspect the complete queue and return exactly one
+    authoritative selection with selected item, action, required_role,
+    required_profile/namespace, pins, and allocation/lease evidence.
+    Role-scoped workers pass ``role=author|reviewer|merger|reconciler`` (or
+    omit for profile role) for single-role filtering. Controller routes only
+    and does not perform downstream mutations.
+
    Outcomes include: ``assigned_work``, ``preview``, ``wait``,
    ``blocked_by_terminal_path``, ``no_safe_work``, ``role_ineligible``,
    ``blocked_by_excluded_own_lease``, ``candidate_set_drift``.
@@ -20736,6 +20770,7 @@ def gitea_allocate_next_work(
            controller_instance_id=allocator_service.resolve_controller_instance_id(),
            exclude_issue_numbers=exclude_issue_numbers,
            expected_candidate_set_fingerprint=expected_candidate_set_fingerprint,
+            allocation_mode=allocation_mode,
        )
    except ValueError as exc:
        return {
@@ -24,7 +24,12 @@ ROLE_WORKTREE_ENVS: dict[str, str] = {
    "reconciler": RECONCILER_WORKTREE_ENV,
 }

-NON_AUTHOR_ROLES = frozenset({"reviewer", "merger", "reconciler"})
+# Controller has no task worktree env — it routes only (#840).
+KNOWN_ROLE_KINDS = frozenset(
+    {"author", "reviewer", "merger", "reconciler", "controller"}
+)
+
+NON_AUTHOR_ROLES = frozenset({"reviewer", "merger", "reconciler", "controller"})


 def normalize_role_kind(
@@ -37,8 +42,12 @@ def normalize_role_kind(
    profile = (profile_name or "").strip().lower()
    if role == "reviewer" and "merger" in profile:
        return "merger"
+    if "controller" in profile or role == "controller":
+        return "controller"
    if role in ROLE_WORKTREE_ENVS:
        return role
+    if role in KNOWN_ROLE_KINDS:
+        return role
    return "author"


@@ -80,7 +89,7 @@ def resolve_namespace_workspace(
    """
    env_map = env if env is not None else os.environ
    role = normalize_role_kind(role_kind, profile_name=profile_name)
-    role_env_key = ROLE_WORKTREE_ENVS[role]
+    role_env_key = ROLE_WORKTREE_ENVS.get(role)

    # #618: durable author resolution — no silent control/master fallback.
    if role == "author" and verify_paths:
@@ -108,13 +117,17 @@ def resolve_namespace_workspace(
            )
        return workspace, source

+    role_env_candidate = (
+        (_env_value(env_map, role_env_key), f"{role_env_key} environment variable", True)
+        if role_env_key
+        else (None, "no role worktree env", True)
+    )
    for candidate, source, env_sourced in (
        (worktree_path, "worktree_path argument", False),
        (worktree, "worktree argument", False),
        (_env_value(env_map, ACTIVE_WORKTREE_ENV),
         f"{ACTIVE_WORKTREE_ENV} environment variable", True),
-        (_env_value(env_map, role_env_key),
-         f"{role_env_key} environment variable", True),
+        role_env_candidate,
        (session_lease_worktree if role in {"reviewer", "merger"} else None,
         "reviewer PR lease worktree", False),
        # Author lock derivation is handled by the durable path above when
@@ -433,7 +446,8 @@ def assess_namespace_mutation_workspace(
        reasons.append(
            f"{role} mutation blocked: workspace is the stable control checkout; "
            f"create or reconnect to a session-owned worktree under branches/ "
-            f"or set {ROLE_WORKTREE_ENVS[role]} / {ACTIVE_WORKTREE_ENV}"
+            f"or set {ROLE_WORKTREE_ENVS.get(role, ACTIVE_WORKTREE_ENV)} / "
+            f"{ACTIVE_WORKTREE_ENV}"
        )
    elif (
        role in {"reviewer", "merger"}
@@ -81,6 +81,12 @@ AUTHOR_TASKS = frozenset({
    "reconcile_landed_pr",
 })

+CONTROLLER_TASKS = frozenset({
+    "process_work_queue",
+    "process-work-queue",
+    "cross_role_allocate",
+})
+
 RECONCILER_TASKS = frozenset({
    "cleanup_merged_pr_branch",
    # #729: delete_branch is reconciler-owned (gitea.branch.delete is granted
@@ -132,6 +138,10 @@ TASK_REQUIRED_ROLE = {
    "reconcile_close_superseded_pr": "reconciler",
    "reconcile_close_satisfied_issue": "reconciler",
    "reconcile_create_followup_issue": "reconciler",
+    # #840: controller-owned generic queue allocation / routing.
+    "process_work_queue": "controller",
+    "process-work-queue": "controller",
+    "cross_role_allocate": "controller",
 }

 WRONG_ROLE_REVIEWER_MSG = (
@@ -147,6 +157,10 @@ WRONG_ROLE_MERGER_MSG = (
    "Wrong role/session for merger task. Launch merger MCP namespace."
 )

+WRONG_ROLE_CONTROLLER_MSG = (
+    "Wrong role/session for controller task. Launch controller MCP namespace."
+)
+
 _session_last_route: dict | None = None


@@ -281,6 +295,27 @@ def route_task_session(
        _record_route(result)
        return result

+    if required_role == "controller":
+        result = {
+            "task_type": task_type,
+            "required_role": required_role,
+            "active_role": active_role_kind,
+            "active_profile": active_profile,
+            "route_result": ROUTE_WRONG_ROLE,
+            "downstream_allowed": False,
+            "reasons": [
+                WRONG_ROLE_CONTROLLER_MSG,
+                "Controller tasks (process_work_queue / cross-role allocate) "
+                "cannot run in author, reviewer, merger, or reconciler "
+                "worker sessions.",
+            ],
+            "message": WRONG_ROLE_CONTROLLER_MSG,
+            "runtime_switching_supported": runtime_switching_supported,
+            "profile_switch_blocked": not runtime_switching_supported,
+        }
+        _record_route(result)
+        return result
+
    if required_role == "author":
        route = ROUTE_TO_AUTHOR
        message = (
@@ -309,8 +309,10 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = {
        "permission": "gitea.pr.create",
        "role": "author",
    },
-    # #600: controller-owned allocator — any authenticated profile may call;
-    # routing enforces role match to selected work. Uses control-plane DB (#613).
+    # #600: workers and controller may call with gitea.read; role-scoped workers
+    # pass role=author|reviewer|merger|reconciler. Cross-role routing is the
+    # controller default (#840). The canonical generic queue *task type* is
+    # process_work_queue (controller-only below).
    "allocate_next_work": {
        "permission": "gitea.read",
        "role": "author",
@@ -319,6 +321,19 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = {
        "permission": "gitea.read",
        "role": "author",
    },
+    # #840: documented generic queue task — controller routes only.
+    "process_work_queue": {
+        "permission": "gitea.read",
+        "role": "controller",
+    },
+    "process-work-queue": {
+        "permission": "gitea.read",
+        "role": "controller",
+    },
+    "cross_role_allocate": {
+        "permission": "gitea.read",
+        "role": "controller",
+    },

    # #601 first-class lease lifecycle — inspect/list need read; mutations gate on
    # ownership in the control-plane DB (not a separate Gitea write permission).
@@ -0,0 +1,572 @@
+"""Executable acceptance tests for ARCH-01 Slice A (#822).
+
+Each acceptance criterion (#822 §12) and named test (#822 §13) is exercised
+against a real SQLite database. The migration runs on a fresh DB in ``setUp``;
+the test-run output is the durable evidence the issue requires (§14).
+
+Enforcement being proven:
+
+* ``[TRUSTED-SERVICE]`` — the ``cp_*`` actor functions exist only on the
+  trusted kernel connection; a raw connection cannot satisfy the triggers.
+* ``[SCHEMA]`` — fail-closed aborts, exact dominance set, NOT-NULL class,
+  immutability, and the last-active-grant floor are enforced by
+  CHECK/FK/trigger, verified here including raw-write bypass and concurrency.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import tempfile
+import threading
+import unittest
+from concurrent.futures import ThreadPoolExecutor
+
+import arch01_platform as ap
+from arch01_platform import (
+    ALREADY_INSTALLED,
+    AUTHORIZATION_DENIED,
+    CONCURRENT_INSTALLATION_LOST,
+    DISTINGUISHED_ISSUER_ID,
+    DOMINANCE_SET_MISMATCH,
+    DOMINANCE_TUPLES,
+    INSTALLED,
+    INVALID_ACTOR_CONTEXT,
+    INVALID_BOOTSTRAP_STATE,
+    PlatformKernel,
+)
+
+INSTALLER = "platform.installer"
+
+_BOOTSTRAP_TABLES = (
+    "principal_equivalence_classes",
+    "principals",
+    "authoritative_issuers",
+    "authority_dominance",
+    "platform_bootstrap_seed",
+    "platform_bootstrap_grants",
+    "platform_active_invariant",
+    "install_state",
+)
+
+
+def _count(kernel: PlatformKernel, table: str) -> int:
+    return kernel._conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]
+
+
+def _count_where(kernel: PlatformKernel, table: str, where: str) -> int:
+    return kernel._conn.execute(f"SELECT COUNT(*) FROM {table} WHERE {where}").fetchone()[0]
+
+
+def _all_bootstrap_empty(kernel: PlatformKernel) -> bool:
+    return all(_count(kernel, t) == 0 for t in _BOOTSTRAP_TABLES)
+
+
+class Arch01MemoryTest(unittest.TestCase):
+    """Single-connection behavior on an in-memory database."""
+
+    def setUp(self) -> None:
+        self.kernel = PlatformKernel(":memory:")
+
+    def tearDown(self) -> None:
+        self.kernel.close()
+
+    # -- AC1 -------------------------------------------------------------- #
+    def test_install_clean(self) -> None:  # t_install_clean(+)
+        res = self.kernel.install_platform(INSTALLER)
+        self.assertEqual(res.code, INSTALLED)
+        self.assertTrue(self.kernel.is_installed())
+        self.assertEqual(_count(self.kernel, "install_state"), 1)
+        self.assertEqual(self.kernel.active_grant_count(), 1)
+        self.assertIn(ap.EVT_PLATFORM_INSTALLED, self.kernel.audit_events())
+        rows = set(
+            self.kernel._conn.execute(
+                "SELECT dominant, subordinate FROM authority_dominance"
+            ).fetchall()
+        )
+        self.assertEqual(rows, set(DOMINANCE_TUPLES))
+        issuer_ref = self.kernel._conn.execute(
+            "SELECT i.issuer_ref FROM principals p JOIN authoritative_issuers i "
+            "ON p.issuer_id = i.issuer_id WHERE p.principal_id = ?",
+            (INSTALLER,),
+        ).fetchone()
+        self.assertEqual(issuer_ref[0], DISTINGUISHED_ISSUER_ID)
+
+    # -- AC2 -------------------------------------------------------------- #
+    def test_install_twice(self) -> None:  # t_install_twice(-)
+        self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
+        res2 = self.kernel.install_platform(INSTALLER)
+        self.assertEqual(res2.code, ALREADY_INSTALLED)
+        self.assertEqual(_count(self.kernel, "principals"), 1)
+        self.assertEqual(_count(self.kernel, "platform_bootstrap_grants"), 1)
+        self.assertEqual(_count(self.kernel, "install_state"), 1)
+
+    # -- AC3 / AC5 -------------------------------------------------------- #
+    def test_install_stage_rollback(self) -> None:  # t_install_stage_rollback
+        for stop in range(1, 9):
+            with self.subTest(stages=stop):
+                k = PlatformKernel(":memory:")
+                try:
+                    self._partial_bootstrap_then_rollback(k, stop)
+                    self.assertTrue(
+                        _all_bootstrap_empty(k),
+                        f"partial rows survived rollback at stage {stop}",
+                    )
+                    self.assertFalse(k.is_installed())
+                finally:
+                    k.close()
+
+    def test_no_partial_after_rollback(self) -> None:  # t_no_partial_after_rollback
+        k = PlatformKernel(":memory:")
+        try:
+            code = self._seed_bootstrap_and_mark(k, dominance=DOMINANCE_TUPLES[:-1])
+            self.assertEqual(code, DOMINANCE_SET_MISMATCH)
+            self.assertTrue(_all_bootstrap_empty(k))
+            self.assertFalse(k.is_installed())
+        finally:
+            k.close()
+
+    # -- AC4 -------------------------------------------------------------- #
+    def test_dominance_missing(self) -> None:  # t_dominance_missing(-)
+        k = PlatformKernel(":memory:")
+        try:
+            self.assertEqual(
+                self._seed_bootstrap_and_mark(k, dominance=DOMINANCE_TUPLES[:-1]),
+                DOMINANCE_SET_MISMATCH,
+            )
+            self.assertFalse(k.is_installed())
+        finally:
+            k.close()
+
+    def test_dominance_extra(self) -> None:  # t_dominance_extra(-)
+        k = PlatformKernel(":memory:")
+        try:
+            extra = DOMINANCE_TUPLES + (("platform.bootstrap", "rogue.extra"),)
+            self.assertEqual(
+                self._seed_bootstrap_and_mark(k, dominance=extra),
+                DOMINANCE_SET_MISMATCH,
+            )
+            self.assertFalse(k.is_installed())
+        finally:
+            k.close()
+
+    def test_dominance_malformed(self) -> None:  # t_dominance_malformed(-)
+        k = PlatformKernel(":memory:")
+        try:
+            malformed = DOMINANCE_TUPLES[:-1] + (("supervisor.root", "WRONG.subordinate"),)
+            self.assertEqual(
+                self._seed_bootstrap_and_mark(k, dominance=malformed),
+                DOMINANCE_SET_MISMATCH,
+            )
+            self.assertFalse(k.is_installed())
+        finally:
+            k.close()
+
+    # -- AC6 -------------------------------------------------------------- #
+    def test_principal_no_class(self) -> None:  # t_principal_no_class(-)
+        with self.kernel.actor_context("op", "operator", "install"):
+            with self.assertRaises(sqlite3.IntegrityError):
+                self.kernel._conn.execute(
+                    "INSERT INTO principals"
+                    "(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
+                    "VALUES ('x', 'operator', NULL, NULL, NULL, '2026-01-01T00:00:00Z')"
+                )
+
+    # -- AC7 -------------------------------------------------------------- #
+    def test_noninstaller_null_issuer(self) -> None:  # t_nonobstaller_null_issuer(-)
+        self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
+        with self.kernel.actor_context("op", "operator", "normal"):
+            cur = self.kernel._conn.execute(
+                "INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')"
+            )
+            class_id = cur.lastrowid
+            with self.assertRaises(sqlite3.IntegrityError) as ctx:
+                self.kernel._conn.execute(
+                    "INSERT INTO principals"
+                    "(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
+                    "VALUES ('rogue', 'operator', ?, NULL, NULL, '2026-01-01T00:00:00Z')",
+                    (class_id,),
+                )
+            self.assertIn("INVALID_BOOTSTRAP_STATE", str(ctx.exception))
+
+    def test_installer_null_issuer_only_during_install(self) -> None:
+        self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
+        with self.kernel.actor_context("i2", "installer", "install"):
+            cur = self.kernel._conn.execute(
+                "INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')"
+            )
+            class_id = cur.lastrowid
+            with self.assertRaises(sqlite3.IntegrityError):
+                self.kernel._conn.execute(
+                    "INSERT INTO principals"
+                    "(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
+                    "VALUES ('i2', 'installer', ?, NULL, NULL, '2026-01-01T00:00:00Z')",
+                    (class_id,),
+                )
+
+    # -- AC8 -------------------------------------------------------------- #
+    def test_context_missing(self) -> None:  # t_context_missing(-)
+        self.assertIsNone(self.kernel._ctx)
+        with self.assertRaises(sqlite3.IntegrityError) as ctx:
+            self.kernel._conn.execute(
+                "INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')"
+            )
+        self.assertIn("INVALID_ACTOR_CONTEXT", str(ctx.exception))
+
+    def test_context_stale(self) -> None:  # t_context_stale(-)
+        with self.kernel.actor_context("op", "operator", "normal"):
+            self.kernel._ctx.expired = True
+            with self.assertRaises(sqlite3.IntegrityError) as ctx:
+                self.kernel._conn.execute(
+                    "INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')"
+                )
+            self.assertIn("INVALID_ACTOR_CONTEXT", str(ctx.exception))
+
+    def test_context_epoch_shift(self) -> None:  # t_context_epoch_shift(-)
+        with self.kernel.actor_context("op", "operator", "normal"):
+            self.kernel._ctx.live_epoch = self.kernel._ctx.bound_epoch + 99
+            with self.assertRaises(sqlite3.IntegrityError) as ctx:
+                self.kernel._conn.execute(
+                    "INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')"
+                )
+            self.assertIn("INVALID_ACTOR_CONTEXT", str(ctx.exception))
+
+    def test_bad_actor_kind_or_mode_rejected(self) -> None:
+        for kind, mode in (("intruder", "normal"), ("operator", "sabotage")):
+            with self.subTest(kind=kind, mode=mode):
+                with self.kernel.actor_context("op", kind, mode):
+                    with self.assertRaises(sqlite3.IntegrityError):
+                        self.kernel._conn.execute(
+                            "INSERT INTO principal_equivalence_classes(created_at) "
+                            "VALUES ('2026-01-01T00:00:00Z')"
+                        )
+
+    # -- AC9 -------------------------------------------------------------- #
+    def test_bootstrap_immutable_update(self) -> None:  # t_bootstrap_immutable_{update}
+        self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
+        cases = [
+            ("UPDATE install_state SET installed_at = 'x' WHERE id = 1", "IMMUTABLE_INSTALL_STATE"),
+            ("UPDATE platform_bootstrap_seed SET created_at = 'x' WHERE seed_id = 1", "IMMUTABLE_SEED"),
+            ("UPDATE authority_dominance SET subordinate = 'x' WHERE dominant = 'supervisor.root'", "IMMUTABLE_DOMINANCE"),
+            (f"UPDATE authoritative_issuers SET issuer_ref = 'x' WHERE issuer_ref = '{DISTINGUISHED_ISSUER_ID}'", "IMMUTABLE_ISSUER"),
+            (f"UPDATE principals SET actor_kind = 'operator' WHERE principal_id = '{INSTALLER}'", "IMMUTABLE_PRINCIPAL"),
+        ]
+        for sql, tag in cases:
+            with self.subTest(sql=sql):
+                with self.kernel.actor_context("op", "operator", "normal"):
+                    with self.assertRaises(sqlite3.IntegrityError) as ctx:
+                        self.kernel._conn.execute(sql)
+                    self.assertIn(tag, str(ctx.exception))
+
+    def test_bootstrap_immutable_delete(self) -> None:  # t_bootstrap_immutable_{delete}
+        self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
+        cases = [
+            ("DELETE FROM install_state WHERE id = 1", "IMMUTABLE_INSTALL_STATE"),
+            ("DELETE FROM platform_bootstrap_seed WHERE seed_id = 1", "IMMUTABLE_SEED"),
+            ("DELETE FROM authority_dominance", "IMMUTABLE_DOMINANCE"),
+            ("DELETE FROM authoritative_issuers", "IMMUTABLE_ISSUER"),
+            (f"DELETE FROM principals WHERE principal_id = '{INSTALLER}'", "IMMUTABLE_PRINCIPAL"),
+            ("DELETE FROM platform_bootstrap_grants", "IMMUTABLE_GRANT"),
+        ]
+        for sql, tag in cases:
+            with self.subTest(sql=sql):
+                with self.kernel.actor_context("op", "operator", "normal"):
+                    with self.assertRaises(sqlite3.IntegrityError) as ctx:
+                        self.kernel._conn.execute(sql)
+                    self.assertIn(tag, str(ctx.exception))
+
+    def test_grant_reactivation_rejected(self) -> None:
+        self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
+        self.kernel.register_principal(
+            "op1", "operator", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER
+        )
+        self.assertEqual(
+            self.kernel.grant_platform_bootstrap("op1", INSTALLER).code, INSTALLED
+        )
+        gid = self.kernel._conn.execute(
+            "SELECT grant_id FROM platform_bootstrap_grants WHERE grantee_principal_id = 'op1'"
+        ).fetchone()[0]
+        self.assertEqual(
+            self.kernel.revoke_platform_bootstrap(gid, actor_principal=INSTALLER).code,
+            INSTALLED,
+        )
+        with self.kernel.actor_context("op", "operator", "normal"):
+            with self.assertRaises(sqlite3.IntegrityError) as ctx:
+                self.kernel._conn.execute(
+                    "UPDATE platform_bootstrap_grants SET active = 1 WHERE grant_id = ?",
+                    (gid,),
+                )
+            self.assertIn("IMMUTABLE_GRANT", str(ctx.exception))
+
+    # -- AC12 ------------------------------------------------------------- #
+    def test_raw_write_bypass(self) -> None:  # t_raw_write_bypass(raw-bypass)
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "p.sqlite3")
+            k = PlatformKernel(path)
+            self.assertEqual(k.install_platform(INSTALLER).code, INSTALLED)
+            k.close()
+            raw = sqlite3.connect(path)
+            raw.execute("PRAGMA foreign_keys = ON")
+            try:
+                with self.assertRaises(sqlite3.Error):
+                    raw.execute(
+                        "INSERT INTO audit_records(event, created_at) "
+                        "VALUES ('forged', '2026-01-01T00:00:00Z')"
+                    )
+                    raw.commit()
+                with self.assertRaises(sqlite3.Error):
+                    raw.execute("UPDATE install_state SET installed_at = 'x' WHERE id = 1")
+                    raw.commit()
+                with self.assertRaises(sqlite3.Error):
+                    raw.execute("DELETE FROM platform_bootstrap_grants")
+                    raw.commit()
+            finally:
+                raw.close()
+
+    # -- AC13 ------------------------------------------------------------- #
+    def test_audit_created(self) -> None:  # t_audit_created(+)
+        self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
+        self.kernel.register_principal(
+            "op1", "operator", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER
+        )
+        self.assertEqual(
+            self.kernel.grant_platform_bootstrap("op1", INSTALLER).code, INSTALLED
+        )
+        gid = self.kernel._conn.execute(
+            "SELECT grant_id FROM platform_bootstrap_grants WHERE grantee_principal_id = 'op1'"
+        ).fetchone()[0]
+        self.assertEqual(
+            self.kernel.revoke_platform_bootstrap(gid, actor_principal=INSTALLER).code,
+            INSTALLED,
+        )
+        events = self.kernel.audit_events()
+        for evt in (
+            ap.EVT_PLATFORM_INSTALLED,
+            ap.EVT_GRANT_CREATED,
+            ap.EVT_GRANT_REVOKED,
+            ap.EVT_PRINCIPAL_REGISTERED,
+        ):
+            self.assertIn(evt, events)
+
+    # -- AC14 ------------------------------------------------------------- #
+    def test_audit_immutable(self) -> None:  # t_audit_immutable(raw-bypass)
+        self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
+        with self.kernel.actor_context("op", "operator", "normal"):
+            with self.assertRaises(sqlite3.IntegrityError) as up:
+                self.kernel._conn.execute("UPDATE audit_records SET event = 'x' WHERE audit_id = 1")
+            self.assertIn("IMMUTABLE_AUDIT", str(up.exception))
+            with self.assertRaises(sqlite3.IntegrityError) as dl:
+                self.kernel._conn.execute("DELETE FROM audit_records WHERE audit_id = 1")
+            self.assertIn("IMMUTABLE_AUDIT", str(dl.exception))
+
+    # -- meta ------------------------------------------------------------- #
+    def test_schema_meta(self) -> None:
+        rows = dict(self.kernel._conn.execute("SELECT key, value FROM arch01_meta").fetchall())
+        self.assertEqual(rows["schema_version"], str(ap.SCHEMA_VERSION))
+        self.assertIn("disabled by default", rows["architecture"])
+
+    def test_register_principal_creates_class_first(self) -> None:
+        self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED)
+        res = self.kernel.register_principal(
+            "svc1", "service", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER
+        )
+        self.assertEqual(res.code, INSTALLED)
+        row = self.kernel._conn.execute(
+            "SELECT current_class_id FROM principals WHERE principal_id = 'svc1'"
+        ).fetchone()
+        self.assertIsNotNone(row[0])
+
+    # -- helpers ---------------------------------------------------------- #
+    def _partial_bootstrap_then_rollback(self, k: PlatformKernel, stop: int) -> None:
+        """Execute the first ``stop`` bootstrap statements, then ROLLBACK."""
+        now = "2026-01-01T00:00:00Z"
+        k._conn.execute("BEGIN IMMEDIATE")
+        class_id = None
+        issuer_id = None
+        try:
+            with k.actor_context(INSTALLER, "installer", "install"):
+                c = k._conn
+                if stop >= 1:
+                    class_id = c.execute(
+                        "INSERT INTO principal_equivalence_classes(created_at) VALUES (?)", (now,)
+                    ).lastrowid
+                if stop >= 2:
+                    c.execute(
+                        "INSERT INTO principals(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
+                        "VALUES (?, 'installer', ?, NULL, ?, ?)",
+                        (INSTALLER, class_id, INSTALLER, now),
+                    )
+                if stop >= 3:
+                    issuer_id = c.execute(
+                        "INSERT INTO authoritative_issuers(issuer_kind, issuer_ref, created_at) VALUES ('operator-key', ?, ?)",
+                        (DISTINGUISHED_ISSUER_ID, now),
+                    ).lastrowid
+                if stop >= 4:
+                    c.execute(
+                        "UPDATE principals SET issuer_id = ? WHERE principal_id = ?",
+                        (issuer_id, INSTALLER),
+                    )
+                if stop >= 5:
+                    c.executemany(
+                        "INSERT INTO authority_dominance(dominant, subordinate) VALUES (?, ?)",
+                        DOMINANCE_TUPLES,
+                    )
+                if stop >= 6:
+                    c.execute(
+                        "INSERT INTO platform_bootstrap_seed(seed_id, installer_principal_id, created_at) VALUES (1, ?, ?)",
+                        (INSTALLER, now),
+                    )
+                if stop >= 7:
+                    c.execute(
+                        "INSERT INTO platform_bootstrap_grants(grantee_principal_id, granted_by, active, created_at) VALUES (?, NULL, 1, ?)",
+                        (INSTALLER, now),
+                    )
+                if stop >= 8:
+                    c.execute("INSERT INTO platform_active_invariant(id, active_count) VALUES (1, 1)")
+        finally:
+            k._conn.execute("ROLLBACK")
+
+    def _seed_bootstrap_and_mark(self, k: PlatformKernel, dominance) -> str:
+        """Seed a full bootstrap with a caller-supplied dominance set, then
+        attempt the marker insert. Returns the classified failure code (or
+        INSTALLED). Rolls back on failure so no partial rows remain."""
+        now = "2026-01-01T00:00:00Z"
+        k._conn.execute("BEGIN IMMEDIATE")
+        try:
+            with k.actor_context(INSTALLER, "installer", "install"):
+                c = k._conn
+                class_id = c.execute(
+                    "INSERT INTO principal_equivalence_classes(created_at) VALUES (?)", (now,)
+                ).lastrowid
+                c.execute(
+                    "INSERT INTO principals(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) "
+                    "VALUES (?, 'installer', ?, NULL, ?, ?)",
+                    (INSTALLER, class_id, INSTALLER, now),
+                )
+                issuer_id = c.execute(
+                    "INSERT INTO authoritative_issuers(issuer_kind, issuer_ref, created_at) VALUES ('operator-key', ?, ?)",
+                    (DISTINGUISHED_ISSUER_ID, now),
+                ).lastrowid
+                c.execute(
+                    "UPDATE principals SET issuer_id = ? WHERE principal_id = ?",
+                    (issuer_id, INSTALLER),
+                )
+                c.executemany(
+                    "INSERT INTO authority_dominance(dominant, subordinate) VALUES (?, ?)",
+                    dominance,
+                )
+                c.execute(
+                    "INSERT INTO platform_bootstrap_seed(seed_id, installer_principal_id, created_at) VALUES (1, ?, ?)",
+                    (INSTALLER, now),
+                )
+                c.execute(
+                    "INSERT INTO platform_bootstrap_grants(grantee_principal_id, granted_by, active, created_at) VALUES (?, NULL, 1, ?)",
+                    (INSTALLER, now),
+                )
+                c.execute("INSERT INTO platform_active_invariant(id, active_count) VALUES (1, 1)")
+                c.execute(
+                    "INSERT INTO install_state(id, marker, installed_at) VALUES (1, 'installed', ?)",
+                    (now,),
+                )
+            k._conn.execute("COMMIT")
+            return INSTALLED
+        except sqlite3.Error as exc:
+            k._safe_rollback()
+            return PlatformKernel._classify(exc)
+
+
+class Arch01ConcurrencyTest(unittest.TestCase):
+    """Concurrency invariants require file-backed DBs and independent connections."""
+
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.path = os.path.join(self._tmp.name, "p.sqlite3")
+
+    def tearDown(self) -> None:
+        self._tmp.cleanup()
+
+    # -- AC10 ------------------------------------------------------------- #
+    def test_concurrent_install(self) -> None:  # t_concurrent_install(concurrency)
+        k1 = PlatformKernel(self.path, busy_timeout_ms=0)
+        k2 = PlatformKernel(self.path, busy_timeout_ms=0)
+        barrier = threading.Barrier(2)
+        results = {}
+
+        def _install(name, kernel):
+            barrier.wait()
+            results[name] = kernel.install_platform(INSTALLER).code
+
+        try:
+            with ThreadPoolExecutor(max_workers=2) as ex:
+                f1 = ex.submit(_install, "a", k1)
+                f2 = ex.submit(_install, "b", k2)
+                f1.result()
+                f2.result()
+            codes = sorted(results.values())
+            self.assertEqual(codes.count(INSTALLED), 1, f"exactly one install expected: {results}")
+            other = [c for c in results.values() if c != INSTALLED][0]
+            self.assertIn(other, (ALREADY_INSTALLED, CONCURRENT_INSTALLATION_LOST))
+            self.assertTrue(k1.is_installed())
+            self.assertEqual(_count(k1, "install_state"), 1)
+            self.assertEqual(_count(k1, "principals"), 1)
+        finally:
+            k1.close()
+            k2.close()
+
+    # -- AC11 ------------------------------------------------------------- #
+    def test_concurrent_last_grant_revoke(self) -> None:  # t_concurrent_last_grant_revoke
+        setup = PlatformKernel(self.path)
+        self.assertEqual(setup.install_platform(INSTALLER).code, INSTALLED)
+        setup.register_principal("op1", "operator", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER)
+        self.assertEqual(setup.grant_platform_bootstrap("op1", INSTALLER).code, INSTALLED)
+        self.assertEqual(setup.active_grant_count(), 2)
+        gids = [
+            r[0]
+            for r in setup._conn.execute(
+                "SELECT grant_id FROM platform_bootstrap_grants WHERE active = 1 ORDER BY grant_id"
+            ).fetchall()
+        ]
+        setup.close()
+        self.assertEqual(len(gids), 2)
+
+        k1 = PlatformKernel(self.path, busy_timeout_ms=3000)
+        k2 = PlatformKernel(self.path, busy_timeout_ms=3000)
+        barrier = threading.Barrier(2)
+        results = {}
+
+        def _revoke(name, kernel, gid):
+            barrier.wait()
+            results[name] = kernel.revoke_platform_bootstrap(gid, actor_principal=INSTALLER).code
+
+        try:
+            with ThreadPoolExecutor(max_workers=2) as ex:
+                f1 = ex.submit(_revoke, "a", k1, gids[0])
+                f2 = ex.submit(_revoke, "b", k2, gids[1])
+                f1.result()
+                f2.result()
+            codes = list(results.values())
+            self.assertEqual(codes.count(INSTALLED), 1, f"exactly one revoke should win: {results}")
+            self.assertEqual(codes.count(AUTHORIZATION_DENIED), 1, f"one revoke must be denied: {results}")
+            self.assertEqual(k1.active_grant_count(), 1)
+            self.assertEqual(_count_where(k1, "platform_bootstrap_grants", "active = 1"), 1)
+        finally:
+            k1.close()
+            k2.close()
+
+    def test_revoke_final_grant_denied(self) -> None:
+        k = PlatformKernel(self.path)
+        try:
+            self.assertEqual(k.install_platform(INSTALLER).code, INSTALLED)
+            gid = k._conn.execute(
+                "SELECT grant_id FROM platform_bootstrap_grants WHERE active = 1"
+            ).fetchone()[0]
+            res = k.revoke_platform_bootstrap(gid, actor_principal=INSTALLER)
+            self.assertEqual(res.code, AUTHORIZATION_DENIED)
+            self.assertEqual(k.active_grant_count(), 1)
+            self.assertEqual(_count_where(k, "platform_bootstrap_grants", "active = 1"), 1)
+        finally:
+            k.close()
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,581 @@
+"""Authoritative controller cross-role generic queue allocation (#840)."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import unittest
+from unittest.mock import patch
+
+from allocator_service import (
+    ALLOCATION_MODE_CROSS_ROLE,
+    ALLOCATION_MODE_ROLE_SCOPED,
+    OUTCOME_NO_SAFE,
+    OUTCOME_PREVIEW,
+    OUTCOME_WAIT,
+    ROLE_AUTHOR,
+    ROLE_CONTROLLER,
+    ROLE_MERGER,
+    ROLE_RECONCILER,
+    ROLE_REVIEWER,
+    WorkCandidate,
+    allocate_next_work,
+    build_selection_dict,
+    classify_skip,
+    required_namespace_for_role,
+    required_profile_for_role,
+    resolve_allocation_mode,
+    selected_action_for_candidate,
+)
+from control_plane_db import ControlPlaneDB
+import role_session_router
+from role_session_router import (
+    ROUTE_ALLOWED,
+    ROUTE_AMBIGUOUS,
+    ROUTE_WRONG_ROLE,
+    route_task_session,
+)
+import namespace_workspace_binding as nwb
+import task_capability_map
+
+
+class CrossRoleAllocationModeTest(unittest.TestCase):
+    def test_controller_defaults_to_cross_role(self) -> None:
+        self.assertEqual(
+            resolve_allocation_mode(ROLE_CONTROLLER),
+            ALLOCATION_MODE_CROSS_ROLE,
+        )
+
+    def test_worker_defaults_to_role_scoped(self) -> None:
+        for role in (ROLE_AUTHOR, ROLE_REVIEWER, ROLE_MERGER, ROLE_RECONCILER):
+            self.assertEqual(
+                resolve_allocation_mode(role),
+                ALLOCATION_MODE_ROLE_SCOPED,
+            )
+
+    def test_explicit_modes(self) -> None:
+        self.assertEqual(
+            resolve_allocation_mode(ROLE_CONTROLLER, "role_scoped"),
+            ALLOCATION_MODE_ROLE_SCOPED,
+        )
+        self.assertEqual(
+            resolve_allocation_mode(ROLE_AUTHOR, "cross_role"),
+            ALLOCATION_MODE_CROSS_ROLE,
+        )
+
+
+class CrossRoleSelectionPayloadTest(unittest.TestCase):
+    def test_selection_contains_required_fields(self) -> None:
+        c = WorkCandidate(
+            kind="issue",
+            number=840,
+            labels=("status:ready",),
+            title="cross-role",
+            priority=20,
+        )
+        sel = build_selection_dict(
+            c,
+            active_role=ROLE_CONTROLLER,
+            required_role=ROLE_AUTHOR,
+            profile_name="prgs-controller",
+            allocation_mode=ALLOCATION_MODE_CROSS_ROLE,
+        )
+        self.assertEqual(sel["number"], 840)
+        self.assertEqual(sel["kind"], "issue")
+        self.assertEqual(sel["required_role"], ROLE_AUTHOR)
+        self.assertEqual(sel["selected_action"], "implement")
+        self.assertEqual(sel["action"], "implement")
+        self.assertEqual(sel["required_profile"], "prgs-author")
+        self.assertEqual(sel["required_namespace"], "gitea-author")
+        self.assertEqual(sel["pinned"]["number"], 840)
+        self.assertIsNone(sel["pinned"]["head_sha"])
+
+    def test_profile_prefix_preserved(self) -> None:
+        self.assertEqual(
+            required_profile_for_role(ROLE_REVIEWER, profile_name="dadeschools-controller"),
+            "dadeschools-reviewer",
+        )
+        self.assertEqual(
+            required_namespace_for_role(ROLE_MERGER),
+            "gitea-merger",
+        )
+
+    def test_selected_actions_per_role(self) -> None:
+        issue = WorkCandidate(kind="issue", number=1, labels=("status:ready",))
+        pr_review = WorkCandidate(kind="pr", number=2, head_sha="a" * 40)
+        pr_rc = WorkCandidate(
+            kind="pr",
+            number=3,
+            head_sha="b" * 40,
+            request_changes_current_head=True,
+        )
+        pr_merge = WorkCandidate(
+            kind="pr",
+            number=4,
+            head_sha="c" * 40,
+            approval_on_current_head=True,
+            mergeable=True,
+        )
+        pr_recon = WorkCandidate(
+            kind="pr",
+            number=5,
+            head_sha="d" * 40,
+            approval_contaminated=True,
+        )
+        self.assertEqual(selected_action_for_candidate(issue, ROLE_AUTHOR), "implement")
+        self.assertEqual(
+            selected_action_for_candidate(pr_rc, ROLE_AUTHOR),
+            "address_pr_change_requests",
+        )
+        self.assertEqual(
+            selected_action_for_candidate(pr_review, ROLE_REVIEWER), "review"
+        )
+        self.assertEqual(selected_action_for_candidate(pr_merge, ROLE_MERGER), "merge")
+        self.assertEqual(
+            selected_action_for_candidate(pr_recon, ROLE_RECONCILER),
+            "reconcile_contaminated_approval",
+        )
+
+
+class CrossRoleAllocateServiceTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.db = ControlPlaneDB(os.path.join(self._tmp.name, "cp.sqlite3"))
+
+    def tearDown(self) -> None:
+        self._tmp.cleanup()
+
+    def _alloc(self, **kwargs):
+        defaults = dict(
+            db=self.db,
+            session_id="ctrl-session",
+            role=ROLE_CONTROLLER,
+            remote="prgs",
+            org="org",
+            repo="repo",
+            candidates=[],
+            apply=False,
+            profile_name="prgs-controller",
+            username="controller-bot",
+            controller_instance_id="ctrl-1",
+        )
+        defaults.update(kwargs)
+        return allocate_next_work(**defaults)
+
+    def test_eligible_author_work(self) -> None:
+        cands = [
+            WorkCandidate(
+                kind="issue",
+                number=100,
+                labels=("status:ready",),
+                title="author work",
+                priority=20,
+            ),
+        ]
+        res = self._alloc(candidates=cands)
+        self.assertTrue(res["success"])
+        self.assertEqual(res["outcome"], OUTCOME_PREVIEW)
+        self.assertEqual(res["allocation_mode"], ALLOCATION_MODE_CROSS_ROLE)
+        self.assertIsNotNone(res["selected"])
+        self.assertEqual(res["selected"]["number"], 100)
+        self.assertEqual(res["required_role"], ROLE_AUTHOR)
+        self.assertEqual(res["selected_action"], "implement")
+        self.assertEqual(res["required_profile"], "prgs-author")
+        self.assertEqual(res["required_namespace"], "gitea-author")
+        self.assertIn("allocate", res["controller_allowed_actions"])
+        self.assertIn("merge", res["controller_forbidden_actions"])
+        self.assertFalse(res["allocation_evidence"]["lease_created"])
+
+    def test_eligible_reviewer_work(self) -> None:
+        cands = [
+            WorkCandidate(
+                kind="pr",
+                number=200,
+                head_sha="e" * 40,
+                title="needs review",
+                priority=30,
+            ),
+        ]
+        res = self._alloc(candidates=cands)
+        self.assertEqual(res["selected"]["number"], 200)
+        self.assertEqual(res["required_role"], ROLE_REVIEWER)
+        self.assertEqual(res["selected_action"], "review")
+        self.assertEqual(res["required_profile"], "prgs-reviewer")
+        self.assertEqual(res["selected"]["pinned"]["head_sha"], "e" * 40)
+
+    def test_eligible_merger_work(self) -> None:
+        cands = [
+            WorkCandidate(
+                kind="pr",
+                number=300,
+                head_sha="f" * 40,
+                approval_on_current_head=True,
+                mergeable=True,
+                priority=40,
+            ),
+        ]
+        res = self._alloc(candidates=cands)
+        self.assertEqual(res["selected"]["number"], 300)
+        self.assertEqual(res["required_role"], ROLE_MERGER)
+        self.assertEqual(res["selected_action"], "merge")
+
+    def test_eligible_reconciler_work(self) -> None:
+        cands = [
+            WorkCandidate(
+                kind="pr",
+                number=400,
+                head_sha="1" * 40,
+                approval_contaminated=True,
+                priority=50,
+            ),
+        ]
+        res = self._alloc(candidates=cands)
+        self.assertEqual(res["selected"]["number"], 400)
+        self.assertEqual(res["required_role"], ROLE_RECONCILER)
+        self.assertIn("reconcile", res["selected_action"])
+
+    def test_no_eligible_work(self) -> None:
+        cands = [
+            WorkCandidate(
+                kind="issue",
+                number=10,
+                labels=("status:blocked",),
+                blocked=True,
+                priority=99,
+            ),
+            WorkCandidate(
+                kind="issue",
+                number=11,
+                labels=("status:ready",),
+                dependency_unmet=True,
+                dependency_reason="blocked by #10",
+                priority=98,
+            ),
+        ]
+        res = self._alloc(candidates=cands)
+        self.assertTrue(res["success"])
+        self.assertEqual(res["outcome"], OUTCOME_NO_SAFE)
+        self.assertIsNone(res["selected"])
+        self.assertEqual(res["allocation_mode"], ALLOCATION_MODE_CROSS_ROLE)
+
+    def test_leased_work_skipped(self) -> None:
+        cands = [
+            WorkCandidate(
+                kind="issue",
+                number=50,
+                labels=("status:ready",),
+                priority=20,
+            ),
+            WorkCandidate(
+                kind="issue",
+                number=51,
+                labels=("status:ready",),
+                priority=10,
+            ),
+        ]
+        # Seed a foreign lease on issue 50 via assign_and_lease under another session.
+        other = allocate_next_work(
+            self.db,
+            session_id="other-worker",
+            role=ROLE_AUTHOR,
+            remote="prgs",
+            org="org",
+            repo="repo",
+            candidates=cands[:1],
+            apply=True,
+            profile_name="prgs-author",
+            controller_instance_id="other-ctrl",
+        )
+        self.assertEqual(other["outcome"], "assigned_work")
+        res = self._alloc(candidates=cands)
+        self.assertIsNotNone(res["selected"])
+        self.assertEqual(res["selected"]["number"], 51)
+        self.assertTrue(any(s["number"] == 50 for s in res["skipped"]))
+        self.assertTrue(res["claims_excluded"])
+
+    def test_dependencies_skipped(self) -> None:
+        cands = [
+            WorkCandidate(
+                kind="issue",
+                number=1,
+                labels=("status:ready",),
+                priority=99,
+                dependency_unmet=True,
+                dependency_reason="needs #2",
+            ),
+            WorkCandidate(
+                kind="issue",
+                number=2,
+                labels=("status:ready",),
+                priority=1,
+            ),
+        ]
+        res = self._alloc(candidates=cands)
+        self.assertEqual(res["selected"]["number"], 2)
+        skipped = {s["number"]: s["reason"] for s in res["skipped"]}
+        self.assertIn(1, skipped)
+        self.assertIn("needs #2", skipped[1])
+
+    def test_pagination_limit_only_truncates_skip_report(self) -> None:
+        """Ranking uses full inventory; reporting limit is MCP-layer only.
+
+        Service ranks all candidates; prove higher-priority eligible item
+        wins even when many skipped precede it.
+        """
+        cands = []
+        for n in range(1, 30):
+            cands.append(
+                WorkCandidate(
+                    kind="issue",
+                    number=n,
+                    labels=("status:ready",),
+                    priority=100 - n,
+                    dependency_unmet=True,
+                    dependency_reason=f"dep {n}",
+                )
+            )
+        cands.append(
+            WorkCandidate(
+                kind="issue",
+                number=999,
+                labels=("status:ready",),
+                priority=1,
+            )
+        )
+        res = self._alloc(candidates=cands)
+        self.assertEqual(res["selected"]["number"], 999)
+        self.assertGreaterEqual(len(res["skipped"]), 29)
+
+    def test_role_scoped_controller_legacy_still_restricts(self) -> None:
+        """role_scoped controller only takes reconciler-needed items."""
+        cands = [
+            WorkCandidate(
+                kind="issue",
+                number=1,
+                labels=("status:ready",),
+                priority=50,
+            ),
+            WorkCandidate(
+                kind="pr",
+                number=2,
+                head_sha="a" * 40,
+                approval_contaminated=True,
+                priority=1,
+            ),
+        ]
+        res = self._alloc(
+            candidates=cands,
+            allocation_mode=ALLOCATION_MODE_ROLE_SCOPED,
+        )
+        self.assertEqual(res["allocation_mode"], ALLOCATION_MODE_ROLE_SCOPED)
+        self.assertEqual(res["selected"]["number"], 2)
+        self.assertEqual(res["required_role"], ROLE_RECONCILER)
+
+    def test_cross_role_prefers_highest_priority_across_roles(self) -> None:
+        cands = [
+            WorkCandidate(
+                kind="issue",
+                number=10,
+                labels=("status:ready",),
+                priority=10,
+            ),
+            WorkCandidate(
+                kind="pr",
+                number=20,
+                head_sha="b" * 40,
+                priority=50,
+            ),
+            WorkCandidate(
+                kind="pr",
+                number=30,
+                head_sha="c" * 40,
+                approval_on_current_head=True,
+                mergeable=True,
+                priority=20,
+            ),
+        ]
+        res = self._alloc(candidates=cands)
+        # PR #20 highest priority → reviewer
+        self.assertEqual(res["selected"]["number"], 20)
+        self.assertEqual(res["required_role"], ROLE_REVIEWER)
+
+    def test_apply_creates_lease_evidence_for_required_role(self) -> None:
+        cands = [
+            WorkCandidate(
+                kind="issue",
+                number=777,
+                labels=("status:ready",),
+                priority=20,
+            ),
+        ]
+        res = self._alloc(candidates=cands, apply=True)
+        self.assertEqual(res["outcome"], "assigned_work")
+        self.assertTrue(res["allocation_evidence"]["lease_created"])
+        self.assertEqual(res["allocation_evidence"]["lease_role"], ROLE_AUTHOR)
+        proof = res["lease_proof"]
+        self.assertIsNotNone(proof["lease_id"])
+        self.assertEqual(proof["lease_role"], ROLE_AUTHOR)
+        self.assertIn("implement", proof["allowed_actions"])
+        # Controller isolation: controller still forbids merge/push/create_pr
+        self.assertIn("merge", res["controller_forbidden_actions"])
+        self.assertIn("push", res["controller_forbidden_actions"])
+
+    def test_metadata_consistency_role_is_controller(self) -> None:
+        cands = [
+            WorkCandidate(
+                kind="issue",
+                number=1,
+                labels=("status:ready",),
+            ),
+        ]
+        res = self._alloc(candidates=cands)
+        self.assertEqual(res["role"], ROLE_CONTROLLER)
+        self.assertEqual(res["routing_role"], ROLE_CONTROLLER)
+        self.assertEqual(res["required_role"], ROLE_AUTHOR)
+
+
+class ProcessWorkQueueRouterTest(unittest.TestCase):
+    def tearDown(self) -> None:
+        role_session_router.clear_route_state()
+
+    def test_process_work_queue_allowed_for_controller(self) -> None:
+        res = route_task_session(
+            "process_work_queue",
+            active_profile="prgs-controller",
+            active_role_kind="controller",
+            allowed_in_current_session=True,
+        )
+        self.assertEqual(res["route_result"], ROUTE_ALLOWED)
+        self.assertEqual(res["required_role"], "controller")
+        self.assertTrue(res["downstream_allowed"])
+
+    def test_process_work_queue_hyphen_alias(self) -> None:
+        res = route_task_session(
+            "process-work-queue",
+            active_profile="prgs-controller",
+            active_role_kind="controller",
+            allowed_in_current_session=True,
+        )
+        self.assertEqual(res["route_result"], ROUTE_ALLOWED)
+
+    def test_process_work_queue_wrong_role_for_author(self) -> None:
+        res = route_task_session(
+            "process_work_queue",
+            active_profile="prgs-author",
+            active_role_kind="author",
+            allowed_in_current_session=False,
+        )
+        self.assertEqual(res["route_result"], ROUTE_WRONG_ROLE)
+        self.assertEqual(res["required_role"], "controller")
+        self.assertFalse(res["downstream_allowed"])
+
+    def test_unknown_still_ambiguous(self) -> None:
+        res = route_task_session(
+            "not_a_real_task",
+            active_profile="prgs-controller",
+            active_role_kind="controller",
+            allowed_in_current_session=False,
+        )
+        self.assertEqual(res["route_result"], ROUTE_AMBIGUOUS)
+
+    def test_capability_map_process_work_queue_is_controller(self) -> None:
+        self.assertEqual(
+            task_capability_map.required_role("process_work_queue"),
+            "controller",
+        )
+        self.assertEqual(
+            task_capability_map.required_permission("process_work_queue"),
+            "gitea.read",
+        )
+
+
+class ControllerRoleMetadataTest(unittest.TestCase):
+    def test_normalize_role_kind_controller(self) -> None:
+        self.assertEqual(
+            nwb.normalize_role_kind("controller"),
+            "controller",
+        )
+        self.assertEqual(
+            nwb.normalize_role_kind("author", profile_name="prgs-controller"),
+            "controller",
+        )
+        self.assertEqual(
+            nwb.normalize_role_kind("reconciler", profile_name="prgs-controller"),
+            "controller",
+        )
+
+    def test_profile_role_kind_prefers_declared_controller(self) -> None:
+        # Import from worktree package path via sys.path already set by pytest.
+        import gitea_mcp_server as mcp
+
+        profile = {
+            "profile_name": "prgs-controller",
+            "role": "controller",
+            "allowed_operations": [
+                "gitea.read",
+                "gitea.issue.comment",
+                "gitea.pr.close",
+            ],
+            "forbidden_operations": [
+                "gitea.pr.approve",
+                "gitea.pr.merge",
+                "gitea.pr.create",
+                "gitea.branch.push",
+            ],
+        }
+        # Declared role wins even if permissions look reconciler-like.
+        self.assertEqual(mcp._profile_role_kind(profile), "controller")
+        # Name-based fallback.
+        profile_no_role = dict(profile)
+        profile_no_role["role"] = None
+        profile_no_role["role_kind"] = None
+        self.assertEqual(mcp._profile_role_kind(profile_no_role), "controller")
+
+    def test_permission_inference_without_controller_name_stays_reconciler(self) -> None:
+        import gitea_mcp_server as mcp
+
+        # Pure permission inference still may return reconciler when no controller
+        # declaration exists — that is intentional for reconciler profiles.
+        role = mcp._role_kind(
+            ["gitea.read", "gitea.pr.close", "gitea.issue.comment"],
+            ["gitea.pr.approve", "gitea.pr.merge", "gitea.pr.create", "gitea.branch.push"],
+        )
+        self.assertEqual(role, "reconciler")
+
+
+class DashboardRemainsExplanatoryTest(unittest.TestCase):
+    def test_dashboard_prompt_points_at_allocator_not_self_select(self) -> None:
+        import workflow_dashboard as wd
+
+        self.assertIn("gitea_allocate_next_work", wd.PROMPT_CONTROLLER)
+        self.assertIn("process_work_queue", wd.PROMPT_CONTROLLER)
+        self.assertIn("never replaces allocator", wd.PROMPT_CONTROLLER.lower())
+        self.assertNotIn("self-select", wd.PROMPT_CONTROLLER.lower())
+
+
+class ClassifySkipCrossRoleTest(unittest.TestCase):
+    def test_controller_cross_role_accepts_author_issue(self) -> None:
+        c = WorkCandidate(kind="issue", number=1, labels=("status:ready",))
+        self.assertIsNone(
+            classify_skip(
+                c,
+                role=ROLE_CONTROLLER,
+                terminal_pr=None,
+                allocation_mode=ALLOCATION_MODE_CROSS_ROLE,
+            )
+        )
+
+    def test_legacy_controller_skips_author_issue(self) -> None:
+        c = WorkCandidate(kind="issue", number=1, labels=("status:ready",))
+        reason = classify_skip(
+            c,
+            role=ROLE_CONTROLLER,
+            terminal_pr=None,
+            allocation_mode=ALLOCATION_MODE_ROLE_SCOPED,
+        )
+        self.assertIsNotNone(reason)
+        self.assertIn("does not require controller", reason or "")
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -65,9 +65,11 @@ PROMPT_RECONCILER = (
    "reconciliation (already-landed / post-merge cleanup). Do not approve or merge."
 )
 PROMPT_CONTROLLER = (
-    "CONTROLLER session: inspect gitea_workflow_dashboard + control-plane leases, "
-    "diagnose blocked/terminal-locked items for {remote}/{org}/{repo}, and schedule "
-    "exactly one fresh role-scoped cycle. Do not implement, review, or merge in-band."
+    "CONTROLLER session: call gitea_route_task_session(task_type='process_work_queue') "
+    "then gitea_allocate_next_work (cross_role default) for {remote}/{org}/{repo}; "
+    "use the returned required_role/profile/action to schedule exactly one downstream "
+    "role cycle. Dashboard is explanatory only and never replaces allocator selection. "
+    "Do not implement, review, approve, or merge in-band."
 )
 PROMPT_IDLE = (
    "IDLE: no safe assignable work for role '{role}' on {remote}/{org}/{repo}. "
Author	SHA1	Message	Date
sysadmin	9468dd624d	merge master into fix/issue-840-cross-role-queue-allocation	2026-07-23 00:06:09 -04:00
sysadminandClaude Opus 4.8	648d9464ba	fix: authoritative cross-role generic queue allocation (Closes #840 ) Add controller-owned cross_role allocation mode that inspects the full queue and returns one selection with required role/profile/action and lease evidence. Document process_work_queue routing, normalize controller role metadata, and keep the dashboard explanatory only. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>	2026-07-23 00:05:35 -04:00
jcwalker3andsysadmin	caaae9b6ee	feat(arch01): atomic platform install + authority kernel (Closes #822 ) (#839 ) Co-authored-by: jcwalker3 <[email protected]>	2026-07-22 23:00:24 -05:00
sysadmin	689c60fc7c	Merge pull request 'feat(webui): console authorization, RBAC, redaction, and audit model (Closes #633 )' (#811 ) from feat/issue-633-console-authz-audit-model into master	2026-07-22 22:16:38 -05:00