primarypath-server 1.0.0__py3-none-any.whl

app/ledger/store.py

@@ -0,0 +1,1042 @@
+"""The spine: append-only, hash-chained event log over Postgres.
+
+The chain scope is (tenant_id, chain_id) — F24. Activity events
+(`approval_*`, `run_event`) live on per-agent chains (chain_id = the
+agent), so each agent is its own independently verifiable log; control-
+plane events (`policy_set`, `admin_action`, ...) live on a per-tenant
+governance chain. Every append runs in one transaction that takes a
+per-chain advisory lock, reads that chain's tail, computes the chained
+hash, inserts, and updates the projection. That serializes writers per
+chain — agents append in parallel instead of contending on one tenant-
+wide lock — and each chain's sequence stays gap-free with every
+prev_hash matching the prior hash even under concurrency.
+
+agent_id and unit are stamped INTO the payload (so the hash chain proves
+them; a relabeled column would be detectable) and mirrored onto row
+columns for querying.
+
+Single-tenant, single-agent deployments use DEFAULT_TENANT/DEFAULT_AGENT
+everywhere and behave exactly as before the seam existed.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Any
+
+from psycopg import AsyncConnection
+from psycopg_pool import AsyncConnectionPool
+
+from ..faults import fault_point
+from ..jcs import jcs
+from .fold import fold_approvals
+from .hashing import GENESIS, canonical, chain_hash
+from .projection import apply_event
+
+APPEND_LOCK = 762718294  # first advisory-lock key; second is hashtext(tenant:chain)
+IDEM_LOCK = 762718295    # ... for an idempotency key; second is hashtext(tenant:key)
+RUN_LOCK = 762718296     # ... for a run's ownership; second is hashtext(tenant:run_id)
+DEFAULT_TENANT = "default"
+DEFAULT_AGENT = "default"
+GOVERNANCE_CHAIN = "__governance__"
+
+# Control-plane event types: who changed a control, and why. They live on
+# the per-tenant governance chain; no agent reasoning or run traces do.
+GOVERNANCE_TYPES = frozenset({
+    "policy_set", "budget_set", "gate_decision", "eval_recorded",
+    "admin_action", "evidence_set", "agent_registered", "audit_exported",
+})
+
+
+def chain_for(type: str, agent_id: str | None) -> str:
+    return GOVERNANCE_CHAIN if type in GOVERNANCE_TYPES \
+        else (agent_id or DEFAULT_AGENT)
+
+
+class UnknownApproval(Exception):
+    pass
+
+
+class UnsupportedPayload(ValueError):
+    """Postgres cannot represent NUL (\\u0000) in jsonb; refuse it honestly
+    at the boundary instead of failing mid-transaction."""
+
+
+def _contains_nul(v) -> bool:
+    if isinstance(v, str):
+        return "\x00" in v
+    if isinstance(v, dict):
+        return any(_contains_nul(k) or _contains_nul(x) for k, x in v.items())
+    if isinstance(v, (list, tuple)):
+        return any(_contains_nul(x) for x in v)
+    return False
+
+
+class AlreadyDecided(Exception):
+    def __init__(self, approval_id: str, status: str):
+        super().__init__(f"{approval_id} already {status}")
+        self.approval_id = approval_id
+        self.status = status
+
+
+class ActionMismatch(Exception):
+    """An idempotent retry of (run_id, call_id) described a DIFFERENT
+    action than the one the approval was created for. The old decision
+    must not attach to the new operation: the caller gets a conflict, not
+    a grant."""
+
+    def __init__(self, approval_id: str, fields: list[str]):
+        super().__init__(
+            f"{approval_id} already exists for a different action "
+            f"(differs in: {', '.join(fields)})")
+        self.approval_id = approval_id
+        self.fields = fields
+
+
+class RunOwnedByAnotherAgent(Exception):
+    """A pinned credential wrote to a run_id that another agent's events
+    already live under. A run belongs to the agent that started it: run
+    reads (audit, export, trace) are authorized per run, so a shared id
+    would hand one agent's stream to another."""
+
+    def __init__(self, run_id: str):
+        super().__init__(f"run {run_id} belongs to another agent")
+        self.run_id = run_id
+
+
+# the fields that define WHAT is being approved. Everything else on the
+# request (deadline, tenant/agent binding) is context, not the action.
+ACTION_FIELDS = ("tool", "arguments", "reasoning", "framework", "callback_url")
+
+
+# the digest algorithm stamped next to action_digest: "jcs" (RFC 8785,
+# reproducible from any language) for every new approval; absent means
+# the pre-0.3 Python-canonical digest ("py"), kept only to check retries
+# of approvals created before the change
+DIGEST_ALG = "jcs"
+
+
+def _action_record(tool, arguments, reasoning, framework, callback_url) -> dict:
+    return {"tool": tool, "arguments": arguments or {}, "reasoning": reasoning,
+            "framework": framework, "callback_url": callback_url}
+
+
+def action_digest(tool: str, arguments: dict | None, reasoning: str | None,
+                  framework: str | None, callback_url: str | None) -> str:
+    """sha256 over the RFC 8785 (JCS) form of the immutable action fields.
+    Stamped into approval_requested so the chain records exactly what was
+    reviewed, checked on idempotent retries, and bound into the execution
+    grant — where an executor in ANY language recomputes it from the
+    arguments it is about to dispatch (JCS is JSON.stringify over sorted
+    keys; app.jcs reproduces it)."""
+    return hashlib.sha256(jcs(_action_record(
+        tool, arguments, reasoning, framework, callback_url)).encode("utf-8")).hexdigest()
+
+
+def action_digest_legacy(tool: str, arguments: dict | None, reasoning: str | None,
+                         framework: str | None, callback_url: str | None) -> str:
+    """The pre-0.3 digest (Python canonical JSON), for retries of approvals
+    stamped without a digest_alg."""
+    return hashlib.sha256(canonical(_action_record(
+        tool, arguments, reasoning, framework, callback_url)).encode("utf-8")).hexdigest()
+
+
+class IdempotencyMismatch(Exception):
+    """An Idempotency-Key reused for a different request."""
+
+
+class GrantRefused(Exception):
+    """An execution grant that must not be redeemed: the approval is not
+    granted, no grant was minted, the nonce does not match, it expired,
+    or it was already redeemed (single use)."""
+
+
+class SecondReviewerRequired(Exception):
+    """Dual control: the endorser cannot also give the second approval."""
+
+    def __init__(self, approval_id: str, endorsed_by: str):
+        super().__init__(
+            f"{approval_id} was endorsed by {endorsed_by}; the second "
+            f"approval must come from a different reviewer")
+        self.approval_id = approval_id
+        self.endorsed_by = endorsed_by
+
+
+VIEW_COLUMNS = (
+    "approval_id, run_id, call_id, tool, arguments, reasoning, framework, "
+    "callback_url, status, reviewer, reason, requested_ts_ms, decided_ts_ms, "
+    "deadline_ms, annotations, tenant_id, agent_id, unit, endorsed_by, "
+    "endorsed_ts_ms, disposition, action_digest, policy, rule_result, "
+    "supersedes, grant_nonce, grant_issued_ms, grant_expires_ms, "
+    "grant_key_id, grant_signature, grant_redeemed_ts_ms, grant_redeemed_by, "
+    "digest_alg, grant_redeemed_instance"
+)
+
+GRANT_COLUMNS = ("grant_nonce", "grant_issued_ms", "grant_expires_ms",
+                 "grant_key_id", "grant_signature", "grant_redeemed_ts_ms",
+                 "grant_redeemed_by", "grant_redeemed_instance")
+
+# every status an approval can end in; only "pending" accepts a transition
+TERMINAL = ("granted", "denied", "cancelled", "expired", "superseded",
+            "changes_requested")
+
+EVENT_COLUMNS = "seq, ts_ms, type, payload, prev_hash, hash, agent_id, unit"
+_EVENT_KEYS = ("seq", "ts_ms", "type", "payload", "prev_hash", "hash",
+               "agent_id", "unit")
+
+
+def _view_row_to_approval(row: tuple) -> dict:
+    keys = [k.strip() for k in VIEW_COLUMNS.split(",")]
+    a = dict(zip(keys, row))
+    # drop nulls for optional passthrough fields, matching the fold's shape
+    if a.get("framework") is None:
+        a.pop("framework", None)
+    if a.get("callback_url") is None:
+        a.pop("callback_url", None)
+    if a.get("deadline_ms") is None:
+        a.pop("deadline_ms", None)
+    if a.get("unit") is None:
+        a.pop("unit", None)
+    # dual control: only present while an endorsement is standing
+    if a.get("endorsed_by") is None:
+        a.pop("endorsed_by", None)
+        a.pop("endorsed_ts_ms", None)
+    # request-time snapshot fields: absent for pre-0020 approvals
+    for k in ("disposition", "action_digest", "policy", "rule_result",
+              "supersedes", "digest_alg"):
+        if a.get(k) is None:
+            a.pop(k, None)
+    # the execution grant, in the exact shape stamped into the
+    # approval_granted payload (the fold returns the payload's dict; the
+    # view reassembles it from columns, so both read the same)
+    if a.get("grant_nonce") is not None:
+        grant = {
+            "v": 1, "approval_id": a["approval_id"], "tenant": a["tenant_id"],
+            "agent_id": a["agent_id"], "tool": a["tool"],
+            "action_digest": a.get("action_digest") or action_digest(
+                a["tool"], a.get("arguments"), a.get("reasoning"),
+                a.get("framework"), a.get("callback_url")),
+            "issued_ms": a["grant_issued_ms"],
+            "expires_ms": a["grant_expires_ms"], "nonce": a["grant_nonce"],
+            "key_id": a["grant_key_id"], "signature": a["grant_signature"],
+        }
+        if a.get("grant_redeemed_ts_ms") is not None:
+            grant["redeemed_ts_ms"] = a["grant_redeemed_ts_ms"]
+            grant["redeemed_by"] = a.get("grant_redeemed_by")
+            if a.get("grant_redeemed_instance") is not None:
+                grant["redeemed_instance"] = a["grant_redeemed_instance"]
+        a["grant"] = grant
+    for k in GRANT_COLUMNS:
+        a.pop(k, None)
+    return a
+
+
+def unit_predicate(units: set[str] | frozenset[str]) -> tuple[str, list]:
+    """SQL fragment for the need-to-know read gate: rows whose agent has a
+    unit are visible only when it intersects the viewer's groups; rows with
+    no unit assigned are visible to any authorized reader (an unassigned
+    agent is ungoverned by need-to-know, which keeps pre-F24 installs
+    working)."""
+    return " AND (unit IS NULL OR unit = ANY(%s))", [sorted(units)]
+
+
+class Ledger:
+    def __init__(self, pool: AsyncConnectionPool):
+        self.pool = pool
+        self.on_append_seconds = None  # optional metrics hook (F18)
+        # async (conn, approval, event) -> None, run INSIDE the decision's
+        # transaction for every granted/denied append: what a decision must
+        # atomically entail (the webhook outbox row) commits with it
+        self.decision_hooks: list = []
+        # (approval_view, tenant) -> grant dict, called INSIDE the granting
+        # transaction so the grant is stamped into approval_granted and the
+        # chain carries it; None = no signer, no grants (executors that
+        # require one refuse, fail closed)
+        self.grant_minter = None
+
+    # -- operation idempotency ----------------------------------------------
+
+    @staticmethod
+    async def _idem_begin(conn: AsyncConnection, tenant: str, idem) -> dict | None:
+        """Inside a write transaction: the recorded result for this key
+        (a replay: the caller returns it and writes nothing), or None to
+        proceed. A different fingerprint under the same key is refused.
+
+        Serialized on the key itself, not on its row: on FIRST use there
+        is no row to lock, so two simultaneous requests would both see
+        "no record", and the second to insert would die on the primary
+        key. The transaction-scoped advisory lock on (tenant, key) makes
+        the second wait for the first to commit, then find and replay
+        its result. Always taken before the chain lock (every caller
+        begins with this), so lock order is fixed and cannot deadlock."""
+        if idem is None:
+            return None
+        await conn.execute("SELECT pg_advisory_xact_lock(%s, hashtext(%s))",
+                           (IDEM_LOCK, f"{tenant}:{idem.key}"))
+        cur = await conn.execute(
+            "SELECT fingerprint, result FROM idempotency_keys "
+            "WHERE tenant_id = %s AND key = %s",
+            (tenant, idem.key))
+        row = await cur.fetchone()
+        if row is None:
+            return None
+        if row[0] != idem.fingerprint:
+            raise IdempotencyMismatch(idem.key)
+        return {"__replay__": True, "result": row[1]}
+
+    @staticmethod
+    async def _idem_commit(conn: AsyncConnection, tenant: str, idem,
+                           result) -> None:
+        """Record the result in the SAME transaction as the events."""
+        if idem is None:
+            return
+        await conn.execute(
+            "INSERT INTO idempotency_keys "
+            "(tenant_id, key, fingerprint, result, created_ts_ms) "
+            "VALUES (%s, %s, %s, %s::jsonb, %s)",
+            (tenant, idem.key, idem.fingerprint, canonical(result),
+             int(time.time() * 1000)))
+
+    async def purge_idempotency_keys(self, older_than_ms: int) -> int:
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "DELETE FROM idempotency_keys WHERE created_ts_ms < %s",
+                (int(time.time() * 1000) - older_than_ms,))
+            return cur.rowcount
+
+    # -- append core ---------------------------------------------------------
+
+    async def append(self, type: str, payload: dict,
+                     tenant: str = DEFAULT_TENANT,
+                     agent_id: str | None = None,
+                     unit: str | None = None) -> dict:
+        start = time.perf_counter()
+        async with self.pool.connection() as conn:
+            async with conn.transaction():
+                event = await self._append_in_tx(conn, type, payload, tenant,
+                                                 agent_id=agent_id, unit=unit)
+        if self.on_append_seconds is not None:
+            self.on_append_seconds(time.perf_counter() - start)
+        return event
+
+    async def _claim_run(self, conn: AsyncConnection, run_id: str,
+                         tenant: str, agent_id: str | None,
+                         pinned: bool, check: bool = True) -> None:
+        """Serialize writers of one run and refuse a pinned agent that is
+        not its owner. Taken BEFORE the chain append lock, always in that
+        order, so two agents racing to open the same run_id cannot both
+        win (their chain locks differ) and cannot deadlock. As with
+        approval ids, only a pinned credential is checked: an unpinned one
+        is the single-trust posture. Governance events carry no agent and
+        never own a run."""
+        await conn.execute(
+            "SELECT pg_advisory_xact_lock(%s, hashtext(%s))",
+            (RUN_LOCK, f"{tenant}:{run_id}"))
+        if not (pinned and check):
+            return
+        cur = await conn.execute(
+            "SELECT 1 FROM events WHERE tenant_id = %s AND run_id = %s "
+            "AND agent_id IS NOT NULL AND agent_id <> %s LIMIT 1",
+            (tenant, run_id, agent_id or DEFAULT_AGENT))
+        if await cur.fetchone() is not None:
+            raise RunOwnedByAnotherAgent(run_id)
+
+    async def append_batch(self, type: str, payloads: list[dict],
+                           tenant: str = DEFAULT_TENANT,
+                           agent_id: str | None = None,
+                           unit: str | None = None,
+                           idem=None, run_id: str | None = None,
+                           pinned: bool = False) -> list[dict]:
+        """Append several events of one type to one chain atomically: one
+        transaction holding the chain lock end to end, instead of one
+        transaction per event. A crash mid-batch rolls the whole batch
+        back, so a client retry can never leave a silently half-ingested
+        run."""
+        if not payloads and idem is None:
+            return []
+        start = time.perf_counter()
+        out: list[dict] = []
+        async with self.pool.connection() as conn:
+            async with conn.transaction():
+                replay = await self._idem_begin(conn, tenant, idem)
+                if replay is not None:
+                    return replay["result"]
+                if run_id is not None:
+                    await self._claim_run(conn, run_id, tenant, agent_id,
+                                          pinned)
+                for payload in payloads:
+                    out.append(await self._append_in_tx(
+                        conn, type, payload, tenant,
+                        agent_id=agent_id, unit=unit))
+                await self._idem_commit(conn, tenant, idem, out)
+        if self.on_append_seconds is not None:
+            self.on_append_seconds(time.perf_counter() - start)
+        return out
+
+    async def _append_in_tx(self, conn: AsyncConnection, type: str,
+                            payload: dict,
+                            tenant: str = DEFAULT_TENANT,
+                            agent_id: str | None = None,
+                            unit: str | None = None) -> dict:
+        """Assumes it runs inside a transaction; takes the per-chain lock."""
+        if _contains_nul(payload):
+            raise UnsupportedPayload(
+                "payload contains NUL (\\u0000), which Postgres cannot store")
+        chain = chain_for(type, agent_id)
+        if type in GOVERNANCE_TYPES:
+            # governance events are BY operators, never by agents; the
+            # subject agent (if any) lives in the payload (e.g. evidence_set)
+            agent_id, unit = None, None
+        else:
+            agent_id = agent_id or DEFAULT_AGENT
+            # the hash chain must prove the stamped identity, so it goes in
+            # the payload (columns are not hashed); DEFAULT_AGENT is left
+            # implicit so single-agent payloads stay byte-identical to F20
+            if agent_id != DEFAULT_AGENT:
+                payload = {**payload, "agent_id": agent_id}
+            if unit is not None:
+                payload = {**payload, "unit": unit}
+        await conn.execute("SELECT pg_advisory_xact_lock(%s, hashtext(%s))",
+                           (APPEND_LOCK, f"{tenant}:{chain}"))
+        cur = await conn.execute(
+            "SELECT seq, hash FROM events WHERE tenant_id = %s "
+            "AND chain_id = %s ORDER BY seq DESC LIMIT 1", (tenant, chain))
+        row = await cur.fetchone()
+        seq = (row[0] + 1) if row else 1
+        prev = row[1] if row else GENESIS
+        ts_ms = int(time.time() * 1000)
+        payload_json = canonical(payload)
+        h = chain_hash(seq, ts_ms, type, payload_json, prev)
+        # stored as the exact canonical TEXT that was hashed (byte-identical
+        # on export; payload_json is a derived column for querying)
+        await conn.execute(
+            "INSERT INTO events (tenant_id, chain_id, seq, ts_ms, type, "
+            "payload, prev_hash, hash, run_id, agent_id, unit) "
+            "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)",
+            (tenant, chain, seq, ts_ms, type, payload_json, prev, h,
+             payload.get("run_id"), agent_id, unit),
+        )
+        fault_point("after_event_insert_before_commit")
+        fault_point("before_projection_update")
+        await apply_event(conn, type, payload, ts_ms, tenant,
+                          agent_id=agent_id, unit=unit, event_hash=h)
+        return {"seq": seq, "ts_ms": ts_ms, "type": type,
+                "payload": payload, "prev_hash": prev, "hash": h,
+                "tenant_id": tenant, "chain_id": chain}
+
+    # -- queries -------------------------------------------------------------
+
+    async def events(self, tenant: str = DEFAULT_TENANT,
+                     chain: str | None = None) -> list[dict]:
+        """Events with payload as the exact stored canonical TEXT (the bytes
+        that were hashed). With `chain`, one chain in seq order (a verifiable
+        unit); without, the tenant's whole log in ingest order (a read for
+        listings and type filters, NOT a single verifiable chain)."""
+        async with self.pool.connection() as conn:
+            if chain is not None:
+                cur = await conn.execute(
+                    f"SELECT {EVENT_COLUMNS} FROM events WHERE tenant_id = %s "
+                    f"AND chain_id = %s ORDER BY seq", (tenant, chain))
+            else:
+                cur = await conn.execute(
+                    f"SELECT {EVENT_COLUMNS} FROM events WHERE tenant_id = %s "
+                    f"ORDER BY rowid", (tenant,))
+            rows = await cur.fetchall()
+        return [self._event_row(r) for r in rows]
+
+    @staticmethod
+    def _event_row(r: tuple) -> dict:
+        e = dict(zip(_EVENT_KEYS, r))
+        # the default agent stays implicit (single-agent installs keep the
+        # F20 event shape); governance events carry no agent at all
+        if e.get("agent_id") in (None, DEFAULT_AGENT):
+            e.pop("agent_id", None)
+        if e.get("unit") is None:
+            e.pop("unit", None)
+        return e
+
+    async def chains(self, tenant: str = DEFAULT_TENANT) -> list[dict]:
+        """Every chain in the tenant with its length and head."""
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "SELECT DISTINCT ON (chain_id) chain_id, seq, hash "
+                "FROM events WHERE tenant_id = %s "
+                "ORDER BY chain_id, seq DESC", (tenant,))
+            rows = await cur.fetchall()
+        return [{"chain_id": r[0], "length": r[1], "head": r[2]}
+                for r in rows]
+
+    async def chain_has_unit_outside(self, tenant: str, chain: str,
+                                     units: set[str]) -> bool:
+        """Whether any event on `chain` is stamped with a unit not in
+        `units`. An agent moved between units carries both on its chain;
+        only a reader of every one of them may take the whole chain (B23).
+        A range scan on the (tenant_id, chain_id, seq) key."""
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "SELECT EXISTS (SELECT 1 FROM events WHERE tenant_id = %s "
+                "AND chain_id = %s AND unit IS NOT NULL "
+                "AND NOT (unit = ANY(%s)))", (tenant, chain, sorted(units)))
+            row = await cur.fetchone()
+        return bool(row and row[0])
+
+    async def events_for_run(self, run_id: str,
+                             tenant: str = DEFAULT_TENANT) -> list[dict]:
+        """A run's events all live on its agent's chain, so seq order is
+        the chain order."""
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                f"SELECT {EVENT_COLUMNS} FROM events WHERE tenant_id = %s "
+                f"AND run_id = %s ORDER BY seq", (tenant, run_id))
+            rows = await cur.fetchall()
+        return [self._event_row(r) for r in rows]
+
+    async def head(self, tenant: str = DEFAULT_TENANT,
+                   chain: str = DEFAULT_AGENT) -> str:
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "SELECT hash FROM events WHERE tenant_id = %s "
+                "AND chain_id = %s ORDER BY seq DESC LIMIT 1",
+                (tenant, chain))
+            row = await cur.fetchone()
+        return row[0] if row else GENESIS
+
+    async def export_bundle(self, tenant: str = DEFAULT_TENANT,
+                            chain: str = DEFAULT_AGENT) -> dict:
+        """One chain as a self-contained, independently verifiable bundle.
+        No re-serialization: the payload text is byte-identical to what was
+        hashed at append time. The default-agent bundle of a single-agent
+        install is the same surface as the F20 tenant bundle."""
+        events = await self.events(tenant, chain=chain)
+        head = events[-1]["hash"] if events else GENESIS
+        bundle = {"events": events, "head": head}
+        if tenant != DEFAULT_TENANT:
+            bundle["tenant_id"] = tenant
+        if chain != DEFAULT_AGENT:
+            bundle["chain_id"] = chain
+        return bundle
+
+    async def export_full(self, tenant: str = DEFAULT_TENANT) -> dict:
+        """The whole log: every chain, each its own verifiable unit. There
+        is no single cross-chain hash — per-chain heads are the truth."""
+        chains = []
+        for c in sorted(ch["chain_id"] for ch in await self.chains(tenant)):
+            b = await self.export_bundle(tenant, chain=c)
+            chains.append({"chain_id": c, "events": b["events"],
+                           "head": b["head"]})
+        bundle = {"scope": "full", "chains": chains}
+        if tenant != DEFAULT_TENANT:
+            bundle["tenant_id"] = tenant
+        return bundle
+
+    # -- approvals -----------------------------------------------------------
+
+    async def create_approval(self, run_id: str, call_id: str, tool: str,
+                              arguments: dict | None = None,
+                              reasoning: str | None = None,
+                              framework: str | None = None,
+                              deadline_ms: int | None = None,
+                              callback_url: str | None = None,
+                              tenant: str = DEFAULT_TENANT,
+                              agent_id: str = DEFAULT_AGENT,
+                              unit: str | None = None,
+                              disposition: str | None = None,
+                              policy: dict | None = None,
+                              rule_result: list | None = None,
+                              supersedes: str | None = None,
+                              pinned: bool = False) -> tuple[dict, bool]:
+        """Idempotent on (tenant, run_id, call_id). Returns (approval, created).
+        agent_id/unit come from the service token (resolved server-side),
+        never from the request body — an agent cannot claim another unit.
+        `pinned` says the credential is bound to agent_id (an issued token
+        with an agent); it is credential metadata, never inferred from the
+        agent's name, so an agent literally called "default" is pinned too.
+        `disposition` is the create-time evaluation ("auto"/"deny"/"gated"),
+        stamped into the chain so an idempotent retry executes the original
+        intent instead of re-evaluating live policy."""
+        approval_id = f"{run_id}:{call_id}"
+        async with self.pool.connection() as conn:
+            async with conn.transaction():
+                # run lock first, chain lock second (see _claim_run); the
+                # ownership check itself waits until the id is known to be
+                # new, so a reused approval id keeps its ActionMismatch
+                await self._claim_run(conn, run_id, tenant, agent_id,
+                                      pinned, check=False)
+                await conn.execute(
+                    "SELECT pg_advisory_xact_lock(%s, hashtext(%s))",
+                    (APPEND_LOCK, f"{tenant}:{agent_id}"))
+                digest = action_digest(tool, arguments, reasoning,
+                                       framework, callback_url)
+                existing = await self._get_view(conn, approval_id, tenant)
+                if existing is not None:
+                    # idempotent only for the SAME agent: a pinned agent
+                    # that reuses another agent's run_id:call_id must not
+                    # be handed that agent's approval (ownership is part
+                    # of the identity; an unpinned credential stays
+                    # single-trust, as for cancel and evidence writes)
+                    if pinned and existing.get("agent_id") != agent_id:
+                        raise ActionMismatch(approval_id, ["agent"])
+                    # ...and only for the SAME action: an id reused for a
+                    # different tool/arguments/callback must never inherit
+                    # the earlier decision
+                    await self._check_same_action(
+                        conn, existing, run_id, tenant, digest,
+                        tool=tool, arguments=arguments or {},
+                        reasoning=reasoning, framework=framework,
+                        callback_url=callback_url)
+                    return existing, False
+                # approval ingestion is a run write like any other
+                await self._claim_run(conn, run_id, tenant, agent_id, pinned)
+                payload: dict[str, Any] = {
+                    "approval_id": approval_id, "run_id": run_id,
+                    "call_id": call_id, "tool": tool,
+                    "arguments": arguments or {}, "reasoning": reasoning,
+                    "action_digest": digest, "digest_alg": DIGEST_ALG,
+                }
+                if framework is not None:
+                    payload["framework"] = framework
+                if deadline_ms is not None:
+                    payload["deadline_ms"] = deadline_ms
+                if callback_url is not None:
+                    payload["callback_url"] = callback_url
+                if disposition is not None:
+                    payload["disposition"] = disposition
+                if policy is not None:
+                    # the rule as it stood, with its version: what this
+                    # request was evaluated against, in the chain
+                    payload["policy"] = policy
+                if rule_result is not None:
+                    payload["rule_result"] = rule_result
+                if supersedes is not None:
+                    # the older proposal this one replaces (arguments or
+                    # context changed): it closes in the SAME transaction,
+                    # so there is never a moment with two live proposals
+                    old = await self._get_view(conn, supersedes, tenant)
+                    if old is None:
+                        raise UnknownApproval(supersedes)
+                    if old["status"] not in ("pending", "changes_requested"):
+                        raise AlreadyDecided(supersedes, old["status"])
+                    if old.get("agent_id") != agent_id:
+                        raise ActionMismatch(supersedes, ["agent"])
+                    if old["status"] == "pending":
+                        await self._append_in_tx(conn, "approval_superseded", {
+                            "approval_id": supersedes,
+                            "run_id": old["run_id"],
+                            "superseded_by": approval_id,
+                            "reviewer": f"agent:{agent_id}",
+                            "reason": f"superseded by {approval_id}",
+                        }, tenant, agent_id=agent_id, unit=unit)
+                        closed = await self._get_view(conn, supersedes, tenant)
+                        assert closed is not None
+                        await self._run_hooks(
+                            conn, closed, {"hash": None, "tenant_id": tenant})
+                    else:
+                        # the REVISION a reviewer asked for. The predecessor
+                        # is already closed, and its outcome is evidence (who
+                        # sent it back, and why): nothing is appended to it.
+                        # The link lives on the new proposal, which is how
+                        # the case shows the reviewer what changed. One live
+                        # revision at a time, serialized by the chain lock
+                        # (same agent): a second one revises the first.
+                        cur = await conn.execute(
+                            "SELECT approval_id FROM approvals_view "
+                            "WHERE tenant_id = %s AND supersedes = %s "
+                            "AND status = 'pending' LIMIT 1",
+                            (tenant, supersedes))
+                        live = await cur.fetchone()
+                        if live is not None:
+                            raise AlreadyDecided(
+                                supersedes, f"being revised by {live[0]}")
+                    payload["supersedes"] = supersedes
+                await self._append_in_tx(conn, "approval_requested", payload,
+                                         tenant, agent_id=agent_id, unit=unit)
+                created = await self._get_view(conn, approval_id, tenant)
+                assert created is not None  # just appended in this transaction
+                return created, True
+
+    async def _check_same_action(self, conn: AsyncConnection, existing: dict,
+                                 run_id: str, tenant: str, digest: str,
+                                 **fields) -> None:
+        """Raise ActionMismatch unless the retry describes the action the
+        approval was created for. Compares against the digest stamped in
+        the chain, recomputed with the algorithm stamped next to it (a
+        pre-0.3 approval carries a Python-canonical digest and no
+        digest_alg); events from before any stamp existed fall back to a
+        field-by-field comparison against the folded view."""
+        stamped = await self._requested_payload(
+            conn, existing["approval_id"], run_id, tenant)
+        stamped_digest = (stamped or {}).get("action_digest")
+        if stamped_digest is not None:
+            if (stamped or {}).get("digest_alg") != DIGEST_ALG:
+                digest = action_digest_legacy(
+                    str(fields.get("tool")), fields.get("arguments"),
+                    fields.get("reasoning"), fields.get("framework"),
+                    fields.get("callback_url"))
+            if stamped_digest == digest:
+                return
+        differing = [f for f in ACTION_FIELDS
+                     if (existing.get(f) or ({} if f == "arguments" else None))
+                     != (fields.get(f) or ({} if f == "arguments" else None))]
+        if stamped_digest is None and not differing:
+            return  # pre-digest event, same action
+        raise ActionMismatch(existing["approval_id"],
+                             differing or ["action_digest"])
+
+    @staticmethod
+    async def _requested_payload(conn: AsyncConnection, approval_id: str,
+                                 run_id: str, tenant: str) -> dict | None:
+        cur = await conn.execute(
+            "SELECT payload_json FROM events "
+            "WHERE tenant_id = %s AND run_id = %s "
+            "AND type = 'approval_requested' "
+            "AND payload_json->>'approval_id' = %s LIMIT 1",
+            (tenant, run_id, approval_id))
+        row = await cur.fetchone()
+        return row[0] if row else None
+
+    async def requested_disposition(self, approval_id: str, run_id: str,
+                                    tenant: str = DEFAULT_TENANT) -> str | None:
+        """The create-time evaluation stamped in the approval_requested
+        event. None for events written before the stamp existed — callers
+        treat that as gated (fail safe: a human finishes what a crash left
+        pending)."""
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "SELECT payload_json->>'disposition' FROM events "
+                "WHERE tenant_id = %s AND run_id = %s "
+                "AND type = 'approval_requested' "
+                "AND payload_json->>'approval_id' = %s LIMIT 1",
+                (tenant, run_id, approval_id))
+            row = await cur.fetchone()
+        return row[0] if row else None
+
+    async def decide(self, approval_id: str, approved: bool,
+                     reviewer: str, reason: str = "",
+                     reviewer_role: str | None = None,
+                     require_second: bool = False,
+                     tenant: str = DEFAULT_TENANT, idem=None) -> dict:
+        """Write a decision. With `require_second` (dual control, from the
+        action's policy), the FIRST approval appends `approval_endorsed`
+        and the approval stays pending; only a DIFFERENT reviewer's
+        approval appends `approval_granted`. A denial always decides
+        immediately. All checks run inside the chain-locked transaction,
+        so two racing approvers cannot both count as the pair."""
+        async with self.pool.connection() as conn:
+            async with conn.transaction():
+                replay = await self._idem_begin(conn, tenant, idem)
+                if replay is not None:
+                    return replay["result"]
+                a = await self._lock_approval_chain(conn, approval_id, tenant)
+                if a is None:
+                    raise UnknownApproval(approval_id)
+                if a["status"] != "pending":
+                    raise AlreadyDecided(approval_id, a["status"])
+                if approved and require_second:
+                    endorsed_by = a.get("endorsed_by")
+                    if endorsed_by is None:
+                        payload = {"approval_id": approval_id,
+                                   "run_id": a["run_id"],
+                                   "reviewer": reviewer, "reason": reason}
+                        if reviewer_role is not None:
+                            payload["reviewer_role"] = reviewer_role
+                        await self._append_in_tx(
+                            conn, "approval_endorsed", payload, tenant,
+                            agent_id=a["agent_id"], unit=a.get("unit"))
+                        endorsed = await self._get_view(conn, approval_id, tenant)
+                        assert endorsed is not None
+                        await self._idem_commit(conn, tenant, idem, endorsed)
+                        return endorsed
+                    if endorsed_by == reviewer:
+                        raise SecondReviewerRequired(approval_id, endorsed_by)
+                etype = "approval_granted" if approved else "approval_denied"
+                payload = {"approval_id": approval_id, "run_id": a["run_id"],
+                           "reviewer": reviewer, "reason": reason}
+                if reviewer_role is not None:
+                    payload["reviewer_role"] = reviewer_role
+                if approved and self.grant_minter is not None:
+                    # the execution grant is born with the decision: same
+                    # transaction, same event, same chain
+                    payload["grant"] = self.grant_minter(a, tenant)
+                event = await self._append_in_tx(conn, etype, payload, tenant,
+                                                 agent_id=a["agent_id"],
+                                                 unit=a.get("unit"))
+                view = await self._get_view(conn, approval_id, tenant)
+                assert view is not None  # written in this transaction
+                await self._run_hooks(conn, view, event)
+                await self._idem_commit(conn, tenant, idem, view)
+                return view
+
+    async def redeem_grant(self, approval_id: str, nonce: str, *,
+                           executor: str, instance: str | None = None,
+                           tenant: str = DEFAULT_TENANT,
+                           only_agent: str | None = None,
+                           now_ms: int | None = None,
+                           idem=None) -> tuple[dict, dict]:
+        """Redeem an execution grant exactly once, under the chain lock:
+        the approval must be granted, carry a grant, the nonce must match
+        (constant-time), the grant must be unexpired and unredeemed. The
+        `grant_redeemed` event is the chain's record that the executor
+        ran the approved action — and that it could run it only once.
+        `executor` is the credential-derived identity (server-authored,
+        the attribution); `instance` is the executor's own name for
+        itself (self-asserted, informational), stored separately.
+        `only_agent` is the credential's pin (None = unpinned), never
+        inferred from an agent's name."""
+        async with self.pool.connection() as conn:
+            async with conn.transaction():
+                replay = await self._idem_begin(conn, tenant, idem)
+                if replay is not None:
+                    # the same executor asking again for the same grant: it
+                    # never got its answer; the grant was spent by ITS call,
+                    # so it may dispatch
+                    return replay["result"]["view"], replay["result"]["event"]
+                a = await self._lock_approval_chain(conn, approval_id, tenant)
+                if a is None:
+                    raise UnknownApproval(approval_id)
+                if only_agent is not None and a.get("agent_id") != only_agent:
+                    raise ActionMismatch(approval_id, ["agent"])
+                if a["status"] != "granted":
+                    raise GrantRefused(f"{approval_id} is {a['status']}, "
+                                       f"not granted")
+                grant = a.get("grant")
+                if grant is None:
+                    raise GrantRefused(
+                        f"{approval_id} carries no execution grant (no "
+                        f"signing key was configured when it was granted)")
+                if not hmac.compare_digest(str(nonce), grant["nonce"]):
+                    raise GrantRefused("nonce does not match the grant")
+                if grant.get("redeemed_ts_ms") is not None:
+                    raise GrantRefused(
+                        f"grant already redeemed by {grant.get('redeemed_by')}"
+                        f" at {grant['redeemed_ts_ms']} (single use)")
+                now = int(time.time() * 1000) if now_ms is None else now_ms
+                if now > int(grant["expires_ms"]):
+                    raise GrantRefused(f"grant expired at "
+                                       f"{grant['expires_ms']}")
+                payload = {
+                    "approval_id": approval_id, "run_id": a["run_id"],
+                    "nonce": grant["nonce"], "tool": a["tool"],
+                    "action_digest": grant["action_digest"],
+                    "executor": executor,
+                }
+                if instance:
+                    payload["executor_instance"] = instance
+                event = await self._append_in_tx(
+                    conn, "grant_redeemed", payload, tenant,
+                    agent_id=a["agent_id"], unit=a.get("unit"))
+                redeemed = await self._get_view(conn, approval_id, tenant)
+                assert redeemed is not None
+                await self._idem_commit(conn, tenant, idem,
+                                        {"view": redeemed, "event": event})
+                return redeemed, event
+
+    async def _run_hooks(self, conn, view: dict, event: dict) -> None:
+        """Every terminal transition tells the agent (webhook outbox row,
+        in this transaction) — a cancellation or expiry is as final for
+        the waiting agent as a denial."""
+        for hook in self.decision_hooks:
+            await hook(conn, view, event)
+
+    async def _transition(self, approval_id: str, etype: str, *,
+                          reviewer: str, reason: str,
+                          extra: dict | None = None,
+                          tenant: str = DEFAULT_TENANT,
+                          only_agent: str | None = None,
+                          idem=None) -> dict:
+        """A non-decision terminal transition (cancel / expire /
+        changes-requested): pending -> the lifecycle status, first one
+        wins, under the chain lock, hooks run in the transaction."""
+        async with self.pool.connection() as conn:
+            async with conn.transaction():
+                replay = await self._idem_begin(conn, tenant, idem)
+                if replay is not None:
+                    return replay["result"]
+                a = await self._lock_approval_chain(conn, approval_id, tenant)
+                if a is None:
+                    raise UnknownApproval(approval_id)
+                if a["status"] != "pending":
+                    raise AlreadyDecided(approval_id, a["status"])
+                if only_agent is not None and a.get("agent_id") != only_agent:
+                    raise ActionMismatch(approval_id, ["agent"])
+                payload = {"approval_id": approval_id, "run_id": a["run_id"],
+                           "reviewer": reviewer, "reason": reason,
+                           **(extra or {})}
+                event = await self._append_in_tx(
+                    conn, etype, payload, tenant, agent_id=a["agent_id"],
+                    unit=a.get("unit"))
+                view = await self._get_view(conn, approval_id, tenant)
+                assert view is not None  # written in this transaction
+                await self._run_hooks(conn, view, event)
+                await self._idem_commit(conn, tenant, idem, view)
+                return view
+
+    async def cancel(self, approval_id: str, agent_id: str, reason: str = "",
+                     tenant: str = DEFAULT_TENANT, pinned: bool = False,
+                     idem=None) -> dict:
+        """The proposing agent withdraws its own pending proposal (a pinned
+        credential can only cancel its agent's; an unpinned one any).
+        `pinned` is credential metadata, never the agent's name."""
+        return await self._transition(
+            approval_id, "approval_cancelled", reviewer=f"agent:{agent_id}",
+            reason=reason or "withdrawn by the agent", tenant=tenant,
+            only_agent=agent_id if pinned else None, idem=idem)
+
+    async def expire(self, approval_id: str, reason: str,
+                     tenant: str = DEFAULT_TENANT) -> dict:
+        """The deadline passed with no decision: the proposal expires. The
+        tool never runs; a fresh proposal is needed."""
+        return await self._transition(
+            approval_id, "approval_expired", reviewer="system:sla",
+            reason=reason, tenant=tenant)
+
+    async def request_changes(self, approval_id: str, reviewer: str,
+                              reason: str, reviewer_role: str | None = None,
+                              tenant: str = DEFAULT_TENANT, idem=None) -> dict:
+        """A human sends the proposal back: not approved, not refused —
+        change it and propose again (the new one `supersedes` this)."""
+        extra = {"reviewer_role": reviewer_role} if reviewer_role else None
+        return await self._transition(
+            approval_id, "approval_changes_requested", reviewer=reviewer,
+            reason=reason, extra=extra, tenant=tenant, idem=idem)
+
+    async def annotate(self, approval_id: str, reviewer: str, note: str,
+                       tenant: str = DEFAULT_TENANT, idem=None) -> dict:
+        async with self.pool.connection() as conn:
+            async with conn.transaction():
+                replay = await self._idem_begin(conn, tenant, idem)
+                if replay is not None:
+                    return replay["result"]
+                a = await self._lock_approval_chain(conn, approval_id, tenant)
+                if a is None:
+                    raise UnknownApproval(approval_id)
+                await self._append_in_tx(conn, "approval_annotated", {
+                    "approval_id": approval_id, "run_id": a["run_id"],
+                    "reviewer": reviewer, "note": note}, tenant,
+                    agent_id=a["agent_id"], unit=a.get("unit"))
+                annotated = await self._get_view(conn, approval_id, tenant)
+                assert annotated is not None
+                await self._idem_commit(conn, tenant, idem, annotated)
+                return annotated
+
+    async def report_incident(self, approval_id: str, reviewer: str,
+                              severity: str, summary: str,
+                              tenant: str = DEFAULT_TENANT, idem=None) -> dict:
+        """A structured outcome event on the approval's own chain: this
+        action, once executed, caused (or contributed to) an incident. The
+        rollout track record counts these — never a word in a note."""
+        async with self.pool.connection() as conn:
+            async with conn.transaction():
+                replay = await self._idem_begin(conn, tenant, idem)
+                if replay is not None:
+                    return replay["result"]
+                a = await self._lock_approval_chain(conn, approval_id, tenant)
+                if a is None:
+                    raise UnknownApproval(approval_id)
+                await self._append_in_tx(conn, "incident_reported", {
+                    "approval_id": approval_id, "run_id": a["run_id"],
+                    "tool": a["tool"], "reviewer": reviewer,
+                    "severity": severity, "summary": summary,
+                }, tenant, agent_id=a["agent_id"], unit=a.get("unit"))
+                reported = await self._get_view(conn, approval_id, tenant)
+                assert reported is not None
+                await self._idem_commit(conn, tenant, idem, reported)
+                return reported
+
+    async def _lock_approval_chain(self, conn: AsyncConnection,
+                                   approval_id: str,
+                                   tenant: str) -> dict | None:
+        """Look up the approval, then serialize on ITS agent's chain: a
+        decision event must land on the chain that carries the request."""
+        a = await self._get_view(conn, approval_id, tenant)
+        if a is None:
+            return None
+        await conn.execute(
+            "SELECT pg_advisory_xact_lock(%s, hashtext(%s))",
+            (APPEND_LOCK, f"{tenant}:{a['agent_id']}"))
+        # re-read under the lock: a racing decision may have landed
+        return await self._get_view(conn, approval_id, tenant)
+
+    async def approval(self, approval_id: str,
+                       tenant: str = DEFAULT_TENANT) -> dict | None:
+        async with self.pool.connection() as conn:
+            return await self._get_view(conn, approval_id, tenant)
+
+    async def approvals(self, status: str | None = None,
+                        limit: int = 100, offset: int = 0,
+                        tenant: str = DEFAULT_TENANT,
+                        units: set[str] | None = None,
+                        agent: str | None = None,
+                        newest_first: bool = False,
+                        after: tuple[int, str] | None = None) -> list[dict]:
+        """`units` is the need-to-know gate: None = unrestricted (dev/open,
+        or a viewer the gate does not apply to); a set = only agents whose
+        unit intersects it (plus unit-less agents). `agent` pins one agent
+        (a service token reading its own queue).
+
+        `after` is a keyset cursor, the (requested_ts_ms, approval_id) of
+        the last row already held: unlike an offset it does not skip or
+        repeat rows when the set changes between pages (a pending page
+        shrinks every time someone decides)."""
+        q = f"SELECT {VIEW_COLUMNS} FROM approvals_view WHERE tenant_id = %s"
+        params: list = [tenant]
+        if status:
+            q += " AND status = %s"
+            params.append(status)
+        if units is not None:
+            frag, p = unit_predicate(units)
+            q += frag
+            params += p
+        if agent is not None:
+            q += " AND agent_id = %s"
+            params.append(agent)
+        if after is not None:
+            q += (" AND (requested_ts_ms, approval_id) "
+                  + ("<" if newest_first else ">") + " (%s, %s)")
+            params += [after[0], after[1]]
+        # approval_id tiebreak: batch-created rows share a requested_ts_ms,
+        # and without a total order pages duplicate or skip rows
+        q += (" ORDER BY requested_ts_ms DESC, approval_id DESC"
+              if newest_first else " ORDER BY requested_ts_ms, approval_id")
+        q += " LIMIT %s OFFSET %s"
+        params += [limit, offset]
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(q, params)
+            rows = await cur.fetchall()
+        return [_view_row_to_approval(r) for r in rows]
+
+    async def pending_count(self, tenant: str = DEFAULT_TENANT,
+                            units: set[str] | None = None,
+                            agent: str | None = None) -> int:
+        """The nav badge — unit-scoped so it never leaks another unit's
+        volume."""
+        q = ("SELECT count(*) FROM approvals_view WHERE tenant_id = %s "
+             "AND status = 'pending'")
+        params: list = [tenant]
+        if units is not None:
+            frag, p = unit_predicate(units)
+            q += frag
+            params += p
+        if agent is not None:
+            q += " AND agent_id = %s"
+            params.append(agent)
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(q, params)
+            row = await cur.fetchone()
+        return row[0] if row else 0
+
+    async def approval_folded(self, approval_id: str,
+                              tenant: str = DEFAULT_TENANT) -> dict | None:
+        """The same state derived straight from the log (truth, not cache)."""
+        run_id = approval_id.rsplit(":", 1)[0]
+        events = await self.events_for_run(run_id, tenant)
+        return fold_approvals(events).get(approval_id)
+
+    async def _get_view(self, conn: AsyncConnection, approval_id: str,
+                        tenant: str = DEFAULT_TENANT) -> dict | None:
+        cur = await conn.execute(
+            f"SELECT {VIEW_COLUMNS} FROM approvals_view "
+            f"WHERE tenant_id = %s AND approval_id = %s",
+            (tenant, approval_id))
+        row = await cur.fetchone()
+        return _view_row_to_approval(row) if row else None