primarypath-server 1.0.0__py3-none-any.whl

app/jcs.py

@@ -0,0 +1,117 @@
+"""RFC 8785 JSON Canonicalization Scheme (JCS): the cross-language canonical
+form the action digest is computed over (digest_alg "jcs").
+
+Why not json.dumps(sort_keys=True, separators=(",", ":")): its number
+formatting is Python's (1.0 -> "1.0", 1e16 -> "1e+16"), which no other
+language reproduces without reimplementing Python. JCS pins numbers to
+ECMAScript's Number.prototype.toString (1.0 -> "1",
+1e16 -> "10000000000000000", 1e21 -> "1e+21"), sorts object keys by
+UTF-16 code units, and escapes strings exactly as JSON.stringify does,
+so `JSON.stringify` over a key-sorted object IS the reference
+implementation and this module reproduces it byte for byte.
+
+The chain hash (`ledger.hashing.canonical`) is NOT this: that format is
+frozen. JCS is only for values two independent parties must digest
+identically, which is the action an executor is about to run.
+"""
+from __future__ import annotations
+
+import math
+
+# ECMAScript Number::toString thresholds
+_EXP_UPPER = 21   # >= 1e21 switches to exponent form
+_EXP_LOWER = -6   # < 1e-6 switches to exponent form
+_MAX_SAFE = 2 ** 53
+_SHORT = {8: "\\b", 9: "\\t", 10: "\\n", 12: "\\f", 13: "\\r"}
+
+
+class NotCanonicalizable(ValueError):
+    """A value JSON (and therefore JCS) cannot represent."""
+
+
+def _es_number(x: float) -> str:
+    """Number::toString for a finite double: the shortest round-trip digit
+    string (Python's repr yields the same digits as ECMAScript's
+    "shortest" rule) laid out with ECMAScript's rules."""
+    if x == 0:
+        return "0"  # -0 prints as "0"
+    sign = "-" if x < 0 else ""
+    r = repr(abs(x))  # '1.5', '1e-07', '1.2345e+21', '123.0'
+    mantissa, _, exp = r.partition("e")
+    e = int(exp) if exp else 0
+    int_part, _, frac_part = mantissa.partition(".")
+    int_digits = int_part.lstrip("0")
+    if int_digits:
+        n = len(int_digits) + e
+    else:
+        n = e - (len(frac_part) - len(frac_part.lstrip("0")))
+    digits = (int_digits + frac_part if int_digits else frac_part.lstrip("0"))
+    digits = digits.rstrip("0")
+    k = len(digits)
+    if k == 0:
+        return "0"
+    if k <= n <= _EXP_UPPER:
+        return sign + digits + "0" * (n - k)
+    if 0 < n <= _EXP_UPPER:
+        return sign + digits[:n] + "." + digits[n:]
+    if _EXP_LOWER < n <= 0:
+        return sign + "0." + "0" * (-n) + digits
+    exp10 = n - 1
+    exp_s = ("+" if exp10 >= 0 else "-") + str(abs(exp10))
+    if k == 1:
+        return sign + digits + "e" + exp_s
+    return sign + digits[0] + "." + digits[1:] + "e" + exp_s
+
+
+def _string(s: str) -> str:
+    """JSON.stringify's string form: only `"`, backslash and control
+    characters are escaped (short forms for \\b \\f \\n \\r \\t, else
+    \\u00xx lowercase); everything else, non-ASCII included, is emitted
+    as is."""
+    out = ['"']
+    for ch in s:
+        o = ord(ch)
+        if ch == '"':
+            out.append('\\"')
+        elif ch == "\\":
+            out.append("\\\\")
+        elif o < 0x20:
+            out.append(_SHORT.get(o, f"\\u{o:04x}"))
+        elif 0xD800 <= o <= 0xDFFF:
+            raise NotCanonicalizable("lone surrogate in string")
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def jcs(value) -> str:
+    """Serialize `value` per RFC 8785."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, int):
+        # JCS numbers are IEEE doubles: an integer beyond 2^53 is what a
+        # JSON parser in any language rounds it to
+        if abs(value) > _MAX_SAFE:
+            return _es_number(float(value))
+        return str(value)
+    if isinstance(value, float):
+        if math.isnan(value) or math.isinf(value):
+            raise NotCanonicalizable("NaN and Infinity are not JSON")
+        return _es_number(value)
+    if isinstance(value, str):
+        return _string(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(jcs(v) for v in value) + "]"
+    if isinstance(value, dict):
+        items = []
+        for k in sorted(value, key=lambda k: str(k).encode("utf-16-be")):
+            if not isinstance(k, str):
+                raise NotCanonicalizable(f"object key is not a string: {k!r}")
+            items.append(_string(k) + ":" + jcs(value[k]))
+        return "{" + ",".join(items) + "}"
+    raise NotCanonicalizable(f"not a JSON value: {type(value).__name__}")

app/ledger/__init__.py

@@ -0,0 +1,41 @@
+from .fold import fold_approvals
+from .hashing import GENESIS, canonical, chain_hash
+from .store import (
+    DEFAULT_AGENT,
+    DEFAULT_TENANT,
+    GOVERNANCE_CHAIN,
+    GOVERNANCE_TYPES,
+    ActionMismatch,
+    AlreadyDecided,
+    GrantRefused,
+    IdempotencyMismatch,
+    Ledger,
+    RunOwnedByAnotherAgent,
+    SecondReviewerRequired,
+    UnknownApproval,
+    UnsupportedPayload,
+    chain_for,
+)
+from .verify import verify_chain
+
+__all__ = [
+    "DEFAULT_AGENT",
+    "DEFAULT_TENANT",
+    "GENESIS",
+    "GOVERNANCE_CHAIN",
+    "GOVERNANCE_TYPES",
+    "ActionMismatch",
+    "AlreadyDecided",
+    "GrantRefused",
+    "IdempotencyMismatch",
+    "Ledger",
+    "RunOwnedByAnotherAgent",
+    "SecondReviewerRequired",
+    "UnknownApproval",
+    "UnsupportedPayload",
+    "canonical",
+    "chain_for",
+    "chain_hash",
+    "fold_approvals",
+    "verify_chain",
+]

app/ledger/fold.py

@@ -0,0 +1,74 @@
+"""Approval state as a fold over the event log. No status column drifts
+because there is no status column in the truth — only in the projection cache.
+
+Events carry payload as the stored canonical TEXT (or an already-parsed
+dict when folding in-memory events).
+"""
+from __future__ import annotations
+
+import json
+
+from .projection import LIFECYCLE
+
+
+def fold_approvals(events: list[dict]) -> dict[str, dict]:
+    approvals: dict[str, dict] = {}
+    for e in events:
+        p = e["payload"]
+        if isinstance(p, str):
+            p = json.loads(p)
+        if e["type"] == "approval_requested":
+            approvals[p["approval_id"]] = {
+                **p,
+                "status": "pending",
+                "requested_ts_ms": e["ts_ms"],
+                "reviewer": None,
+                "reason": None,
+                "decided_ts_ms": None,
+                "annotations": [],
+            }
+        elif e["type"] == "approval_endorsed":
+            # dual control: the first approval; the approval stays pending
+            a = approvals.get(p["approval_id"])
+            if a and a["status"] == "pending":
+                a["endorsed_by"] = p.get("reviewer")
+                a["endorsed_ts_ms"] = e["ts_ms"]
+        elif e["type"] in ("approval_granted", "approval_denied") \
+                or e["type"] in LIFECYCLE:
+            a = approvals.get(p["approval_id"])
+            if a and a["status"] == "pending":  # first terminal event wins
+                a["status"] = ("granted" if e["type"] == "approval_granted"
+                               else "denied" if e["type"] == "approval_denied"
+                               else LIFECYCLE[e["type"]])
+                a["reviewer"] = p.get("reviewer")
+                a["reason"] = p.get("reason")
+                a["decided_ts_ms"] = e["ts_ms"]
+                if e["type"] == "approval_granted" and p.get("grant"):
+                    a["grant"] = dict(p["grant"])
+        elif e["type"] == "grant_redeemed":
+            a = approvals.get(p["approval_id"])
+            g = a.get("grant") if a else None
+            if (g and g.get("nonce") == p.get("nonce")
+                    and g.get("redeemed_ts_ms") is None):
+                g["redeemed_ts_ms"] = e["ts_ms"]
+                g["redeemed_by"] = p.get("executor")
+                if p.get("executor_instance"):
+                    g["redeemed_instance"] = p["executor_instance"]
+        elif e["type"] == "incident_reported":
+            a = approvals.get(p["approval_id"])
+            if a is not None:
+                a["annotations"].append({
+                    "reviewer": p.get("reviewer"),
+                    "note": f"incident ({p.get('severity')}): "
+                            f"{p.get('summary')}",
+                    "kind": "incident", "severity": p.get("severity"),
+                    "ts_ms": e["ts_ms"]})
+        elif e["type"] == "approval_annotated":
+            a = approvals.get(p["approval_id"])
+            if a:
+                a["annotations"].append({
+                    "reviewer": p.get("reviewer"),
+                    "note": p.get("note"),
+                    "ts_ms": e["ts_ms"],
+                })
+    return approvals

app/ledger/hashing.py

@@ -0,0 +1,19 @@
+"""Chain hashing, byte-identical to the walking skeleton (../../server.py).
+
+Exports built here must verify with the reference ../../verify.py.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+
+GENESIS = "genesis"
+
+
+def canonical(payload: dict) -> str:
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def chain_hash(seq: int, ts_ms: int, type: str, payload_json: str, prev_hash: str) -> str:
+    line = f"{seq}|{ts_ms}|{type}|{payload_json}|{prev_hash}"
+    return hashlib.sha256(line.encode("utf-8")).hexdigest()

app/ledger/projection.py

@@ -0,0 +1,389 @@
+"""approvals_view (+ the F24 governance folds): queryable caches over the log.
+
+Updated inside the append transaction; rebuild_projection() proves they are
+pure caches by truncating and re-folding the whole log (all tenants).
+"""
+from __future__ import annotations
+
+import json
+
+from psycopg import AsyncConnection
+
+DEFAULT_TENANT = "default"
+DEFAULT_AGENT = "default"
+
+
+# terminal transitions other than a decision: event type -> status
+LIFECYCLE = {
+    "approval_cancelled": "cancelled",
+    "approval_expired": "expired",
+    "approval_superseded": "superseded",
+    "approval_changes_requested": "changes_requested",
+}
+
+
+async def apply_event(conn: AsyncConnection, type: str, payload: dict,
+                      ts_ms: int, tenant: str = DEFAULT_TENANT,
+                      agent_id: str | None = None,
+                      unit: str | None = None,
+                      event_hash: str | None = None) -> None:
+    if type == "approval_requested":
+        await conn.execute(
+            """
+            INSERT INTO approvals_view
+                (tenant_id, approval_id, run_id, call_id, tool, arguments,
+                 reasoning, framework, callback_url, status, requested_ts_ms,
+                 deadline_ms, agent_id, unit, disposition, action_digest,
+                 policy, rule_result, supersedes, digest_alg)
+            VALUES (%s, %s, %s, %s, %s, %s::jsonb, %s, %s, %s, 'pending',
+                    %s, %s, %s, %s, %s, %s, %s::jsonb, %s::jsonb, %s, %s)
+            ON CONFLICT (tenant_id, approval_id) DO NOTHING
+            """,
+            (
+                tenant,
+                payload["approval_id"],
+                payload["run_id"],
+                payload["call_id"],
+                payload["tool"],
+                json.dumps(payload.get("arguments") or {}),
+                payload.get("reasoning"),
+                payload.get("framework"),
+                payload.get("callback_url"),
+                ts_ms,
+                payload.get("deadline_ms"),
+                agent_id or DEFAULT_AGENT,
+                unit,
+                payload.get("disposition"),
+                payload.get("action_digest"),
+                json.dumps(payload["policy"]) if payload.get("policy") else None,
+                (json.dumps(payload["rule_result"])
+                 if payload.get("rule_result") is not None else None),
+                payload.get("supersedes"),
+                payload.get("digest_alg"),
+            ),
+        )
+    elif type in LIFECYCLE:
+        await conn.execute(
+            """
+            UPDATE approvals_view
+            SET status = %s, reviewer = %s, reason = %s, decided_ts_ms = %s
+            WHERE tenant_id = %s AND approval_id = %s AND status = 'pending'
+            """,
+            (LIFECYCLE[type], payload.get("reviewer"), payload.get("reason"),
+             ts_ms, tenant, payload["approval_id"]),
+        )
+    elif type == "approval_endorsed":
+        # dual control: cache the first approval; status stays pending
+        await conn.execute(
+            """
+            UPDATE approvals_view
+            SET endorsed_by = %s, endorsed_ts_ms = %s
+            WHERE tenant_id = %s AND approval_id = %s AND status = 'pending'
+            """,
+            (payload.get("reviewer"), ts_ms, tenant, payload["approval_id"]),
+        )
+    elif type in ("approval_granted", "approval_denied"):
+        status = "granted" if type == "approval_granted" else "denied"
+        grant = payload.get("grant") if type == "approval_granted" else None
+        if isinstance(grant, dict) and grant.get("nonce"):
+            # the execution grant born with the decision: cached on the
+            # row so the agent's poll returns it and redeem checks it
+            await conn.execute(
+                """
+                UPDATE approvals_view
+                SET status = %s, reviewer = %s, reason = %s, decided_ts_ms = %s,
+                    grant_nonce = %s, grant_issued_ms = %s,
+                    grant_expires_ms = %s, grant_key_id = %s,
+                    grant_signature = %s
+                WHERE tenant_id = %s AND approval_id = %s AND status = 'pending'
+                """,
+                (status, payload.get("reviewer"), payload.get("reason"), ts_ms,
+                 grant["nonce"], grant.get("issued_ms"),
+                 grant.get("expires_ms"), grant.get("key_id"),
+                 grant.get("signature"), tenant, payload["approval_id"]),
+            )
+        else:
+            await conn.execute(
+                """
+                UPDATE approvals_view
+                SET status = %s, reviewer = %s, reason = %s, decided_ts_ms = %s
+                WHERE tenant_id = %s AND approval_id = %s AND status = 'pending'
+                """,
+                (status, payload.get("reviewer"), payload.get("reason"), ts_ms,
+                 tenant, payload["approval_id"]),
+            )
+    elif type == "grant_redeemed":
+        # single use: the first redemption of the grant's nonce wins
+        await conn.execute(
+            """
+            UPDATE approvals_view
+            SET grant_redeemed_ts_ms = %s, grant_redeemed_by = %s,
+                grant_redeemed_instance = %s
+            WHERE tenant_id = %s AND approval_id = %s AND grant_nonce = %s
+                  AND grant_redeemed_ts_ms IS NULL
+            """,
+            (ts_ms, payload.get("executor"), payload.get("executor_instance"),
+             tenant, payload["approval_id"], payload.get("nonce")),
+        )
+    elif type == "approval_annotated":
+        await conn.execute(
+            """
+            UPDATE approvals_view
+            SET annotations = annotations || %s::jsonb
+            WHERE tenant_id = %s AND approval_id = %s
+            """,
+            (
+                json.dumps([{
+                    "reviewer": payload.get("reviewer"),
+                    "note": payload.get("note"),
+                    "ts_ms": ts_ms,
+                }]),
+                tenant,
+                payload["approval_id"],
+            ),
+        )
+    elif type == "run_event":
+        # usage_view: one row per model decision, the SQL-aggregable form
+        # of what budgets and the spend report used to fold in Python
+        inner = payload.get("event") or {}
+        if isinstance(inner, dict) and inner.get("type") == "model_decision":
+            ip = inner.get("payload") or {}
+            usage = ip.get("usage") or {}
+            tools = sorted({str(c["name"]) for c in (ip.get("tool_calls") or [])
+                            if isinstance(c, dict) and c.get("name")})
+            await conn.execute(
+                """
+                INSERT INTO usage_view
+                    (tenant_id, run_id, ts_ms, model, input_tokens,
+                     output_tokens, tools)
+                VALUES (%s, %s, %s, %s, %s, %s, %s)
+                """,
+                (tenant, payload.get("run_id"), ts_ms,
+                 str(ip.get("model") or "unknown"),
+                 _int(usage.get("input_tokens")),
+                 _int(usage.get("output_tokens")), tools),
+            )
+    elif type == "incident_reported":
+        # surfaced on the case as a typed annotation; counted by the
+        # rollout track record straight from the event
+        await conn.execute(
+            """
+            UPDATE approvals_view
+            SET annotations = annotations || %s::jsonb
+            WHERE tenant_id = %s AND approval_id = %s
+            """,
+            (
+                json.dumps([{
+                    "reviewer": payload.get("reviewer"),
+                    "note": f"incident ({payload.get('severity')}): "
+                            f"{payload.get('summary')}",
+                    "kind": "incident",
+                    "severity": payload.get("severity"),
+                    "ts_ms": ts_ms,
+                }]),
+                tenant,
+                payload["approval_id"],
+            ),
+        )
+    elif type == "policy_set":
+        # last-write-wins per (tenant, action): the fold of policy_set events
+        await conn.execute(
+            """
+            INSERT INTO policy_view
+                (tenant_id, action, requires_approval, reversible, mode,
+                 allow, deny, approver_groups, require_second_approval,
+                 sample_n, updated_by, reason, updated_ts_ms,
+                 risk, blast_radius, version)
+            VALUES (%s, %s, %s, %s, %s, %s::jsonb, %s::jsonb, %s::jsonb,
+                    %s, %s, %s, %s, %s, %s, %s, %s)
+            ON CONFLICT (tenant_id, action) DO UPDATE SET
+                requires_approval = EXCLUDED.requires_approval,
+                reversible = EXCLUDED.reversible,
+                mode = EXCLUDED.mode,
+                allow = EXCLUDED.allow,
+                deny = EXCLUDED.deny,
+                approver_groups = EXCLUDED.approver_groups,
+                require_second_approval = EXCLUDED.require_second_approval,
+                sample_n = EXCLUDED.sample_n,
+                updated_by = EXCLUDED.updated_by,
+                reason = EXCLUDED.reason,
+                updated_ts_ms = EXCLUDED.updated_ts_ms,
+                risk = EXCLUDED.risk,
+                blast_radius = EXCLUDED.blast_radius,
+                version = EXCLUDED.version
+            """,
+            (
+                tenant,
+                payload["action"],
+                bool(payload["requires_approval"]),
+                bool(payload.get("reversible", False)),
+                payload["mode"],
+                json.dumps(payload.get("allow") or []),
+                json.dumps(payload.get("deny") or []),
+                json.dumps(payload.get("approver_groups") or []),
+                bool(payload.get("require_second_approval", False)),
+                int(payload.get("sample_n") or 0),
+                payload.get("by"),
+                payload.get("reason"),
+                ts_ms,
+                payload.get("risk") or ("medium" if payload.get("reversible")
+                                        else "high"),
+                payload.get("blast_radius"),
+                event_hash[:12] if event_hash else None,
+            ),
+        )
+    elif type == "budget_set":
+        # last-write-wins per (tenant, scope, key): the fold of budget_set (F23)
+        await conn.execute(
+            """
+            INSERT INTO budget_view
+                (tenant_id, scope, key, max_usd, max_tokens, window_kind,
+                 on_exceed, updated_by, reason, updated_ts_ms)
+            VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+            ON CONFLICT (tenant_id, scope, key) DO UPDATE SET
+                max_usd = EXCLUDED.max_usd,
+                max_tokens = EXCLUDED.max_tokens,
+                window_kind = EXCLUDED.window_kind,
+                on_exceed = EXCLUDED.on_exceed,
+                updated_by = EXCLUDED.updated_by,
+                reason = EXCLUDED.reason,
+                updated_ts_ms = EXCLUDED.updated_ts_ms
+            """,
+            (tenant, payload["scope"], payload["key"], payload.get("max_usd"),
+             payload.get("max_tokens"), payload["window"],
+             payload["on_exceed"], payload.get("by"), payload.get("reason"),
+             ts_ms),
+        )
+    elif type == "eval_recorded":
+        await conn.execute(
+            "INSERT INTO eval_history (tenant_id, kind, agent, version, "
+            "detail, ts_ms) VALUES (%s, 'eval', %s, %s, %s::jsonb, %s)",
+            (tenant, payload["agent"], payload["version"],
+             json.dumps({"profile": payload.get("profile"),
+                         "scenarios": payload.get("scenarios"),
+                         "by": payload.get("by")}), ts_ms),
+        )
+    elif type == "gate_decision":
+        await conn.execute(
+            "INSERT INTO eval_history (tenant_id, kind, agent, version, "
+            "detail, ts_ms) VALUES (%s, 'gate', %s, %s, %s::jsonb, %s)",
+            (tenant, payload["agent"], payload["version"],
+             json.dumps({k: payload.get(k) for k in
+                         ("passed", "baseline_version", "blocks", "override",
+                          "by", "reason")}), ts_ms),
+        )
+        # gate_view is the latest verdict; last-write-wins (an override is a
+        # newer gate_decision)
+        await conn.execute(
+            """
+            INSERT INTO gate_view
+                (tenant_id, agent, version, passed, baseline_version, blocks,
+                 override, decided_by, reason, decided_ts_ms)
+            VALUES (%s, %s, %s, %s, %s, %s::jsonb, %s, %s, %s, %s)
+            ON CONFLICT (tenant_id, agent, version) DO UPDATE SET
+                passed = EXCLUDED.passed,
+                baseline_version = EXCLUDED.baseline_version,
+                blocks = EXCLUDED.blocks,
+                override = EXCLUDED.override,
+                decided_by = EXCLUDED.decided_by,
+                reason = EXCLUDED.reason,
+                decided_ts_ms = EXCLUDED.decided_ts_ms
+            """,
+            (tenant, payload["agent"], payload["version"],
+             bool(payload.get("passed", False)),
+             payload.get("baseline_version"),
+             json.dumps(payload.get("blocks") or []),
+             bool(payload.get("override", False)),
+             payload.get("by"), payload.get("reason"), ts_ms),
+        )
+    elif type == "agent_registered":
+        # last-write-wins per (tenant, agent): the agent-to-unit map (F24)
+        await conn.execute(
+            """
+            INSERT INTO agents_view
+                (tenant_id, agent, unit, updated_by, reason, updated_ts_ms)
+            VALUES (%s, %s, %s, %s, %s, %s)
+            ON CONFLICT (tenant_id, agent) DO UPDATE SET
+                unit = EXCLUDED.unit,
+                updated_by = EXCLUDED.updated_by,
+                reason = EXCLUDED.reason,
+                updated_ts_ms = EXCLUDED.updated_ts_ms
+            """,
+            (tenant, payload["agent"], payload.get("unit"),
+             payload.get("by"), payload.get("reason"), ts_ms),
+        )
+    elif type == "evidence_set":
+        # last-write-wins per (tenant, agent): the evidence profile (F24)
+        await conn.execute(
+            """
+            INSERT INTO evidence_view
+                (tenant_id, agent, signing_backend, key_id, capture,
+                 retention_days, updated_by, reason, updated_ts_ms)
+            VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)
+            ON CONFLICT (tenant_id, agent) DO UPDATE SET
+                signing_backend = EXCLUDED.signing_backend,
+                key_id = EXCLUDED.key_id,
+                capture = EXCLUDED.capture,
+                retention_days = EXCLUDED.retention_days,
+                updated_by = EXCLUDED.updated_by,
+                reason = EXCLUDED.reason,
+                updated_ts_ms = EXCLUDED.updated_ts_ms
+            """,
+            (tenant, payload["agent"], payload["signing_backend"],
+             payload.get("key_id"), payload.get("capture", "full"),
+             payload.get("retention_days"), payload.get("by"),
+             payload.get("reason"), ts_ms),
+        )
+    elif type == "admin_action" and payload.get("action") == "set_config":
+        # runtime-tunable org config (e.g. admin_can_read_activity) is itself
+        # an event-sourced fold, so a rebuild reproduces the posture
+        await conn.execute(
+            """
+            INSERT INTO config_view (tenant_id, key, value, updated_ts_ms)
+            VALUES (%s, %s, %s::jsonb, %s)
+            ON CONFLICT (tenant_id, key) DO UPDATE SET
+                value = EXCLUDED.value,
+                updated_ts_ms = EXCLUDED.updated_ts_ms
+            """,
+            (tenant, payload["key"], json.dumps(payload.get("value")), ts_ms),
+        )
+
+
+_VIEW_TABLES = ("approvals_view", "policy_view", "budget_view", "gate_view",
+                "eval_history", "agents_view", "evidence_view", "config_view",
+                "usage_view")
+
+
+def _int(v) -> int:
+    try:
+        return int(v or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+async def rebuild_projection(conn: AsyncConnection,
+                             tenant: str | None = None) -> None:
+    """Re-fold the projections from the log. With `tenant`, only that
+    tenant's rows are cleared and re-folded: one tenant's admin never
+    rebuilds (or even touches) another tenant's cache. Without it, the
+    whole store (ops tooling and tests)."""
+    if tenant is None:
+        for table in _VIEW_TABLES:
+            await conn.execute(
+                f"TRUNCATE {table}"
+                + (" RESTART IDENTITY"
+                   if table in ("eval_history", "usage_view") else ""))
+        cur = await conn.execute(
+            "SELECT tenant_id, type, payload, ts_ms, agent_id, unit, hash "
+            "FROM events ORDER BY rowid")
+    else:
+        for table in _VIEW_TABLES:
+            await conn.execute(
+                f"DELETE FROM {table} WHERE tenant_id = %s", (tenant,))
+        cur = await conn.execute(
+            "SELECT tenant_id, type, payload, ts_ms, agent_id, unit, hash "
+            "FROM events WHERE tenant_id = %s ORDER BY rowid", (tenant,))
+    rows = await cur.fetchall()
+    for tenant_id, type_, payload, ts_ms, agent_id, unit, h in rows:
+        await apply_event(conn, type_, json.loads(payload), ts_ms, tenant_id,
+                          agent_id=agent_id, unit=unit, event_hash=h)