primarypath-server 1.0.0__py3-none-any.whl

app/routes/approvals.py

@@ -0,0 +1,576 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import JSONResponse
+
+from ..auth import (
+    activity_scope,
+    agent_credential,
+    agent_pin,
+    is_agent_plane,
+    require_agent,
+    require_reader,
+    require_reviewer,
+    resolve_agent,
+    resolve_tenant,
+    reviewer_role,
+    reviewer_string,
+    scope_units,
+    visible_to,
+)
+from ..costgov import COST_REVIEWER
+from ..faults import fault_point
+from ..idempotency import idempotency_of
+from ..ledger import (
+    ActionMismatch,
+    AlreadyDecided,
+    GrantRefused,
+    IdempotencyMismatch,
+    Ledger,
+    RunOwnedByAnotherAgent,
+    SecondReviewerRequired,
+    UnknownApproval,
+)
+from ..policy import (
+    POLICY_REVIEWER,
+    NotAnApprover,
+    case_controls,
+    sampled_for_review,
+)
+from ..schemas import (
+    Annotation,
+    Cancel,
+    ChangesRequest,
+    CreateApproval,
+    Decision,
+    Incident,
+    Redeem,
+)
+
+router = APIRouter(prefix="/api/approvals")
+
+
+def _ledger(request: Request) -> Ledger:
+    return request.app.state.ledger
+
+
+async def _existing(ledger: Ledger, approval_id: str, tenant: str) -> dict:
+    """Re-read an approval this request already touched: it exists."""
+    a = await ledger.approval(approval_id, tenant)
+    assert a is not None
+    return a
+
+
+def redact_grant(a: dict) -> dict:
+    """The approval as the human plane sees it: the execution grant's
+    metadata (issued, expires, redeemed by whom) stays — it is the case's
+    provenance — but the signature, the bearer half of a capability to
+    run one consequential action, is handed only to the agent plane."""
+    if a and a.get("grant") and "signature" in a["grant"]:
+        return {**a, "grant": {k: v for k, v in a["grant"].items()
+                               if k != "signature"}}
+    return a
+
+
+async def _present(request: Request, a: dict) -> dict:
+    return a if await is_agent_plane(request) else redact_grant(a)
+
+
+def _reviewer_or_400(identity: dict | None, typed: str) -> str:
+    if identity is not None and identity.get("token_id"):
+        # issued-token operator: the typed name says WHO sat at the
+        # keyboard, the binding says WHICH revocable credential proved it
+        if not typed.strip():
+            raise HTTPException(400, "reviewer is required")
+        label = identity.get("token_label")
+        bind = f"token:{identity['token_id']}" + (f" {label}" if label else "")
+        return f"{typed.strip()} ({bind})"
+    if identity is not None:
+        return reviewer_string(identity)
+    if not typed.strip():
+        raise HTTPException(400, "reviewer is required")
+    return typed
+
+
+@router.post("", dependencies=[Depends(require_agent)])
+async def create(request: Request, body: CreateApproval):
+    from ..netguard import UnsafeCallbackURL, validate_callback_url
+    from ..sla import resolve_deadline_ms
+
+    # SSRF guard: refuse a callback_url pointing at internal/metadata targets
+    # before we ever POST a decision to it.
+    if body.callback_url:
+        try:
+            validate_callback_url(
+                body.callback_url,
+                request.app.state.settings.webhook_allow_private)
+        except UnsafeCallbackURL as e:
+            raise HTTPException(400, str(e)) from None
+
+    tenant = await resolve_tenant(request)
+    # non-spoofable: agent + unit come from the service token record,
+    # resolved server-side (F24) — never from the request body
+    agent_id, unit = await resolve_agent(request)
+    ledger = _ledger(request)
+
+    # live policy supersedes static config: an action whose current policy
+    # does not require approval is auto-granted by system:policy so the
+    # agent's loop resolves immediately; unknown actions fall back to the
+    # configured fail-safe (require approval).
+    effective = await request.app.state.policy.effective(body.tool, tenant)
+
+    # F23: cost governance can only TIGHTEN the safety decision, never weaken
+    # it. Over budget with on_exceed=gate forces a human even if policy said
+    # autonomous; on_exceed=deny refuses the action outright. Under budget (or
+    # the open no-budget posture) it adds nothing.
+    cost = await request.app.state.cost.check(body.tool, tenant,
+                                              run_id=body.run_id)
+    cost_denies = cost["exceeded"] and cost["on_exceed"] == "deny"
+    cost_gates = cost["exceeded"] and cost["on_exceed"] == "gate"
+    # sampled mode: a deterministic 1-in-N goes to a human. Computed on
+    # run_id:call_id BEFORE anything is created, so a retry of the same
+    # call gets the same answer — and keyed by a server-side salt the
+    # agent plane cannot read, so the agent cannot grind call ids that
+    # are never sampled.
+    sampled_in = (effective["mode"] == "sampled" and sampled_for_review(
+        f"{body.run_id}:{body.call_id}", effective.get("sample_n") or 0,
+        await request.app.state.policy.sampling_salt(tenant)))
+    # dual control is the strongest gate: never auto-grantable
+    requires_approval = (effective["requires_approval"] or cost_gates
+                         or sampled_in
+                         or effective.get("require_second_approval", False))
+    # the evaluation is made ONCE, at request time, and stamped into the
+    # requested event: "deny" (over budget), "auto" (no gate), or "gated"
+    # (a human must decide)
+    disposition = ("deny" if cost_denies
+                   else "gated" if requires_approval else "auto")
+    # the rule result, in words the reviewer reads: why this proposal is
+    # gated (or not), against which policy version
+    rule_result = []
+    if effective["source"] == "default":
+        rule_result.append("no policy rule: the configured default "
+                           + ("requires approval"
+                              if effective["requires_approval"]
+                              else "auto-grants"))
+    else:
+        rule_result.append(f"policy mode {effective['mode']}: "
+                           + ("requires approval"
+                              if effective["requires_approval"]
+                              else "no human gate"))
+    if effective.get("require_second_approval"):
+        rule_result.append("dual control: two different approvers")
+    if sampled_in:
+        rule_result.append(f"sampled: this 1-in-{effective.get('sample_n')} "
+                           f"pick goes to a human")
+    if cost_gates:
+        rule_result.append(f"cost: over budget ({cost['scope']}:{cost['key']}, "
+                           f"{cost['window']}) forces a human")
+    if cost_denies:
+        rule_result.append(f"cost: over budget ({cost['scope']}:{cost['key']}, "
+                           f"{cost['window']}) denies")
+    policy_snapshot = request.app.state.policy.snapshot(effective)
+
+    deadline_ms = resolve_deadline_ms(request.app.state.settings, body.tool,
+                                      body.deadline_ms)
+    try:
+        approval, created = await ledger.create_approval(
+            run_id=body.run_id, call_id=body.call_id, tool=body.tool,
+            arguments=body.arguments, reasoning=body.reasoning,
+            framework=body.framework, deadline_ms=deadline_ms,
+            callback_url=body.callback_url, tenant=tenant,
+            agent_id=agent_id, unit=unit, disposition=disposition,
+            policy=policy_snapshot, rule_result=rule_result,
+            supersedes=body.supersedes,
+            pinned=(await agent_pin(request)) is not None)
+    except ActionMismatch as e:
+        # the id is taken by a DIFFERENT action: refuse rather than hand
+        # the caller the earlier decision. An accidental (or deliberate)
+        # id reuse must never attach an old approval to a new operation.
+        # (also: superseding another agent's proposal)
+        raise HTTPException(409, str(e)) from None
+    except RunOwnedByAnotherAgent as e:
+        # a pinned agent proposing into another agent's run (the same rule
+        # as run-event ingest: a run has one owner)
+        raise HTTPException(409, str(e)) from None
+    except UnknownApproval:
+        raise HTTPException(404, f"unknown approval to supersede: "
+                                 f"{body.supersedes}") from None
+    except AlreadyDecided as e:
+        raise HTTPException(409, f"cannot supersede {e.approval_id}: "
+                                 f"already {e.status}") from None
+    fault_point("after_append_commit_before_http")
+
+    # These auto-decisions are idempotent on the approval, NOT conditional on
+    # `created`: the requested-append and the decision are separate
+    # transactions, so a crash (or lost response) between them leaves the
+    # approval pending and the agent's idempotent retry (created=False) must
+    # still finish it. AlreadyDecided means a human or earlier retry won.
+    #
+    # A retry executes the STAMPED disposition, never a fresh evaluation:
+    # otherwise a policy relaxed (or a budget window rolled over) after an
+    # action was gated would let the agent re-POST the same create and turn
+    # a pending, human-queued action into an auto-approval. Events from
+    # before the stamp existed read as gated — the fail-safe: a human
+    # finishes what a crash left pending.
+    if not created:
+        disposition = (await ledger.requested_disposition(
+            approval["approval_id"], body.run_id, tenant)) or "gated"
+    if disposition == "deny" and approval["status"] == "pending":
+        if cost.get("exceeded"):
+            limit = cost.get("limit") or {}
+            spent = cost.get("spent") or {}
+            detail = (f"over budget: {cost['scope']}:{cost['key']} spent "
+                      f"${(spent.get('usd') if spent else 0)} / "
+                      f"{(spent.get('tokens') if spent else 0)} tok vs "
+                      f"limit ${limit.get('usd')}/{limit.get('tokens')} tok "
+                      f"({cost['window']})")
+        else:
+            # a retry after the window rolled over: the stamped deny still
+            # stands (the evaluation happened once, at request time)
+            detail = "over budget at request time (stamped disposition)"
+        try:
+            approval = await ledger.decide(
+                approval["approval_id"], approved=False,
+                reviewer=COST_REVIEWER, reason=detail, reviewer_role="cost",
+                tenant=tenant)
+        except AlreadyDecided:
+            approval = await _existing(ledger, approval["approval_id"], tenant)
+    elif disposition == "auto" and approval["status"] == "pending":
+        reason = f"auto-approved: policy mode={effective['mode']}"
+        if effective["mode"] == "sampled":
+            reason += (f" (passed 1-in-{effective.get('sample_n')} "
+                       f"sampling; the pick is a salted HMAC over the "
+                       f"approval id — the export discloses the salt)")
+        try:
+            approval = await ledger.decide(
+                approval["approval_id"], approved=True,
+                reviewer=POLICY_REVIEWER, reason=reason,
+                reviewer_role="policy", tenant=tenant)
+        except AlreadyDecided:
+            approval = await _existing(ledger, approval["approval_id"], tenant)
+    elif created and disposition == "gated":
+        # gated for a human. When sampling or cost forced the gate, put
+        # the why in front of the reviewer as an annotation.
+        if sampled_in:
+            await ledger.annotate(
+                approval["approval_id"], POLICY_REVIEWER,
+                f"sampled for human review: 1 in "
+                f"{effective.get('sample_n')} {body.tool} proposals is "
+                f"checked (policy mode=sampled; the pick is a salted HMAC "
+                f"over the approval id — the export discloses the salt)",
+                tenant=tenant)
+            approval = await _existing(ledger, approval["approval_id"], tenant)
+        if cost_gates:
+            limit = cost.get("limit") or {}
+            spent = cost.get("spent") or {}
+            await ledger.annotate(
+                approval["approval_id"], COST_REVIEWER,
+                f"over budget ({cost['scope']}:{cost['key']}, {cost['window']}): "
+                f"spent ${spent.get('usd')} / {spent.get('tokens')} tok vs "
+                f"limit ${limit.get('usd')}/{limit.get('tokens')} tok",
+                tenant=tenant)
+            approval = await _existing(ledger, approval["approval_id"], tenant)
+        for chat in getattr(request.app.state, "chat_routers", []):
+            chat.notify(approval)
+    return JSONResponse(approval, status_code=201 if created else 200)
+
+
+# a client-supplied limit is clamped: an absurd value would fold the whole
+# table per request. The web inbox pages with cursor at this size.
+MAX_LIMIT = 500
+
+
+@router.get("", dependencies=[Depends(require_reader)])
+async def list_approvals(request: Request, status: str | None = None,
+                         limit: int = 100, cursor: int = 0,
+                         order: str = "asc", after: str | None = None):
+    """Unit-scoped, server-enforced (F24): the queue never shows — or
+    counts — another unit's work.
+
+    `order=desc` lists newest first. `after=<requested_ts_ms>:<approval_id>`
+    (the last row of the previous page) is a keyset cursor: stable while
+    rows are being decided, where the `cursor` offset skips or repeats."""
+    if order not in ("asc", "desc"):
+        raise HTTPException(400, "order must be asc or desc")
+    keyset = None
+    if after is not None:
+        ts, sep, last_id = after.partition(":")
+        if not sep or not last_id or not ts.lstrip("-").isdigit():
+            raise HTTPException(
+                400, "after must be <requested_ts_ms>:<approval_id>")
+        keyset = (int(ts), last_id)
+    scope = await activity_scope(request)
+    rows = await _ledger(request).approvals(
+        status=status, limit=max(1, min(limit, MAX_LIMIT)),
+        offset=max(0, cursor), newest_first=order == "desc", after=keyset,
+        tenant=await resolve_tenant(request),
+        units=scope_units(scope),
+        agent=scope.get("agent") if scope else None)
+    if await is_agent_plane(request):
+        return rows
+    return [redact_grant(a) for a in rows]
+
+
+@router.get("/pending-count", dependencies=[Depends(require_reader)])
+async def pending_count(request: Request):
+    """The nav badge, unit-scoped: volume is information too."""
+    scope = await activity_scope(request)
+    n = await _ledger(request).pending_count(
+        tenant=await resolve_tenant(request), units=scope_units(scope),
+        agent=scope.get("agent") if scope else None)
+    return {"pending": n}
+
+
+@router.get("/{approval_id}", dependencies=[Depends(require_reader)])
+async def get_one(request: Request, approval_id: str):
+    a = await _ledger(request).approval(approval_id,
+                                        tenant=await resolve_tenant(request))
+    scope = await activity_scope(request)
+    if a is None or not visible_to(scope, a.get("agent_id"), a.get("unit")):
+        # 404, not 403: outside your units, even existence is need-to-know
+        raise HTTPException(404, f"unknown approval {approval_id}")
+    return await _present(request, a)
+
+
+@router.post("/{approval_id}/decision")
+async def decide(request: Request, approval_id: str, body: Decision,
+                 identity: dict | None = Depends(require_reviewer)):
+    reviewer = _reviewer_or_400(identity, body.reviewer)
+    tenant = await resolve_tenant(request)
+
+    # unit scopes visibility BEFORE approver_groups scope the decision
+    # (F24): deciding outside your units is refused as unknown, because
+    # even existence is need-to-know.
+    existing = await _ledger(request).approval(approval_id, tenant=tenant)
+    if existing is not None and not visible_to(
+            await activity_scope(request), existing.get("agent_id"),
+            existing.get("unit")):
+        raise HTTPException(404, f"unknown approval {approval_id}")
+
+    # enforce "who may approve": if the action pins approver_groups, the
+    # reviewer's IdP groups must intersect (admins bypass). A control that is
+    # recorded in the chain but silently unenforced would be the sharp edge
+    # for a product whose pitch is provable governance. The case's own
+    # snapshot binds as well as the live rule (B6): relaxing a policy never
+    # weakens a case that was proposed under the stricter one.
+    require_second = False
+    if existing is not None:
+        rule = await request.app.state.policy.policy_for(existing["tool"], tenant)
+        try:
+            require_second = case_controls(existing.get("policy"), rule,
+                                           identity)
+        except NotAnApprover as e:
+            raise HTTPException(403, str(e)) from None
+        if body.bulk and body.approved:
+            # a bulk approval is a glance, not a review: irreversible,
+            # dual-control and high/critical-risk actions are decided one
+            # by one, on their own case — enforced here, not in the client
+            why = _individual_only(existing.get("policy") or {}, require_second)
+            if why:
+                raise HTTPException(
+                    403, f"{approval_id} must be decided individually: {why}")
+        # dual control distinctness binds to the CREDENTIAL for issued
+        # tokens: the same token with a different typed name is still the
+        # same approver (the in-transaction check covers exact strings)
+        if (require_second and body.approved and identity
+                and identity.get("token_id")):
+            standing = existing.get("endorsed_by") or ""
+            if f"(token:{identity['token_id']}" in standing:
+                raise HTTPException(
+                    403, "the second approval must come from a different "
+                         "credential, not a different name on the same token")
+
+    try:
+        a = await _ledger(request).decide(
+            approval_id, approved=body.approved, reviewer=reviewer,
+            reason=body.reason, reviewer_role=reviewer_role(identity),
+            require_second=require_second, tenant=tenant,
+            idem=await idempotency_of(request, body.model_dump()))
+    except UnknownApproval:
+        raise HTTPException(404, f"unknown approval {approval_id}") from None
+    except AlreadyDecided as e:
+        raise HTTPException(409, f"already {e.status}") from None
+    except IdempotencyMismatch:
+        raise HTTPException(422, "Idempotency-Key was already used for a "
+                                 "different request") from None
+    except SecondReviewerRequired as e:
+        # 403, not 409: the approval is NOT decided, this reviewer just
+        # cannot be both halves of the pair
+        raise HTTPException(403, str(e)) from None
+    fault_point("after_decision_commit_before_reflect")
+    if a["status"] in ("granted", "denied"):
+        # an endorsement is not a decision: no card flip (and no callback —
+        # the outbox row is written by the ledger's decision hook, inside
+        # the decision's own transaction, so it survives a crash here)
+        for chat in getattr(request.app.state, "chat_routers", []):
+            chat.reflect(a)
+    # the decider is the human plane: the grant goes to the executor
+    return redact_grant(a)
+
+
+def _individual_only(policy: dict, require_second: bool) -> str | None:
+    """Why a bulk approval is refused for this approval (None = allowed)."""
+    if policy.get("reversible") is False:
+        return "irreversible action"
+    if require_second or policy.get("require_second_approval"):
+        return "dual control"
+    if policy.get("risk") in ("high", "critical"):
+        return f"{policy['risk']} risk"
+    return None
+
+
+@router.post("/{approval_id}/request-changes")
+async def request_changes(request: Request, approval_id: str,
+                          body: ChangesRequest,
+                          identity: dict | None = Depends(require_reviewer)):
+    """Send the proposal back: neither approved nor refused. The agent
+    changes it and proposes again with `supersedes` set to this id."""
+    reviewer = _reviewer_or_400(identity, body.reviewer)
+    tenant = await resolve_tenant(request)
+    existing = await _ledger(request).approval(approval_id, tenant=tenant)
+    if existing is not None and not visible_to(
+            await activity_scope(request), existing.get("agent_id"),
+            existing.get("unit")):
+        raise HTTPException(404, f"unknown approval {approval_id}")
+    # sending a proposal back closes the case: it is a decision, bound by
+    # the same approver_groups as approve and deny (B11)
+    if existing is not None:
+        rule = await request.app.state.policy.policy_for(existing["tool"], tenant)
+        try:
+            case_controls(existing.get("policy"), rule, identity)
+        except NotAnApprover as e:
+            raise HTTPException(403, str(e)) from None
+    try:
+        a = await _ledger(request).request_changes(
+            approval_id, reviewer, body.reason,
+            reviewer_role=reviewer_role(identity), tenant=tenant,
+            idem=await idempotency_of(request, body.model_dump()))
+    except UnknownApproval:
+        raise HTTPException(404, f"unknown approval {approval_id}") from None
+    except AlreadyDecided as e:
+        raise HTTPException(409, f"already {e.status}") from None
+    except IdempotencyMismatch:
+        raise HTTPException(422, "Idempotency-Key was already used for a "
+                                 "different request") from None
+    for chat in getattr(request.app.state, "chat_routers", []):
+        chat.reflect(a)
+    return a
+
+
+@router.post("/{approval_id}/cancel", dependencies=[Depends(require_agent)])
+async def cancel(request: Request, approval_id: str, body: Cancel):
+    """The proposing agent withdraws its pending proposal (agent plane).
+    A pinned token cancels only its own agent's proposals."""
+    tenant = await resolve_tenant(request)
+    agent_id, _unit = await resolve_agent(request)
+    try:
+        a = await _ledger(request).cancel(
+            approval_id, agent_id, body.reason, tenant=tenant,
+            pinned=(await agent_pin(request)) is not None,
+            idem=await idempotency_of(request, body.model_dump()))
+    except UnknownApproval:
+        raise HTTPException(404, f"unknown approval {approval_id}") from None
+    except AlreadyDecided as e:
+        raise HTTPException(409, f"already {e.status}") from None
+    except ActionMismatch:
+        raise HTTPException(403, "a pinned token can only cancel its own "
+                                 "agent's proposals") from None
+    except IdempotencyMismatch:
+        raise HTTPException(422, "Idempotency-Key was already used for a "
+                                 "different request") from None
+    fault_point("after_write_commit_before_http")
+    for chat in getattr(request.app.state, "chat_routers", []):
+        chat.reflect(a)
+    return a
+
+
+@router.post("/{approval_id}/redeem", dependencies=[Depends(require_agent)])
+async def redeem(request: Request, approval_id: str, body: Redeem):
+    """The executor redeems the execution grant minted with the decision
+    — once. Agent plane: the gateway or tool proxy that holds the tool
+    credentials presents the grant's nonce right before dispatch. Under
+    the chain lock: 409 if the approval is not granted, carries no grant,
+    the nonce does not match, the grant expired, or it was already
+    redeemed. Success appends `grant_redeemed` to the approval's chain —
+    `executor` is the presenting credential's identity, written by the
+    server; `executor_instance` is whatever the caller called itself —
+    and returns that event's hash."""
+    tenant = await resolve_tenant(request)
+    agent_id, _unit = await resolve_agent(request)
+    # the attribution is the CREDENTIAL, resolved server-side (an issued
+    # token names its agent and its revocable id + label); the caller's
+    # name for itself is kept, but apart, as self-asserted context
+    executor = await agent_credential(request)
+    instance = (body.instance or body.executor).strip() or None
+    try:
+        a, event = await _ledger(request).redeem_grant(
+            approval_id, body.nonce, executor=executor, instance=instance,
+            tenant=tenant, only_agent=await agent_pin(request),
+            idem=await idempotency_of(request, body.model_dump()))
+    except UnknownApproval:
+        raise HTTPException(404, f"unknown approval {approval_id}") from None
+    except ActionMismatch:
+        # 404, not 403: another agent's approvals are need-to-know
+        raise HTTPException(404, f"unknown approval {approval_id}") from None
+    except GrantRefused as e:
+        raise HTTPException(409, str(e)) from None
+    except IdempotencyMismatch:
+        raise HTTPException(422, "Idempotency-Key was already used for a "
+                                 "different request") from None
+    fault_point("after_write_commit_before_http")
+    out = {"approval_id": approval_id, "status": a["status"],
+           "tool": a["tool"], "action_digest": a["grant"]["action_digest"],
+           "redeemed_ts_ms": event["ts_ms"], "redeemed_by": executor,
+           "event_hash": event["hash"]}
+    if instance:
+        out["redeemed_instance"] = instance
+    return out
+
+
+@router.post("/{approval_id}/incident")
+async def report_incident(request: Request, approval_id: str, body: Incident,
+                          identity: dict | None = Depends(require_reviewer)):
+    """Record that this action's execution caused an incident: a chained
+    `incident_reported` event the rollout track record counts (and
+    demotes on), and a typed annotation on the case."""
+    reviewer = _reviewer_or_400(identity, body.reviewer)
+    tenant = await resolve_tenant(request)
+    existing = await _ledger(request).approval(approval_id, tenant=tenant)
+    if existing is not None and not visible_to(
+            await activity_scope(request), existing.get("agent_id"),
+            existing.get("unit")):
+        raise HTTPException(404, f"unknown approval {approval_id}")
+    try:
+        a = await _ledger(request).report_incident(
+            approval_id, reviewer, body.severity, body.summary, tenant=tenant,
+            idem=await idempotency_of(request, body.model_dump()))
+    except UnknownApproval:
+        raise HTTPException(404, f"unknown approval {approval_id}") from None
+    except IdempotencyMismatch:
+        raise HTTPException(422, "Idempotency-Key was already used for a "
+                                 "different request") from None
+    fault_point("after_write_commit_before_http")
+    return a
+
+
+@router.post("/{approval_id}/annotate")
+async def annotate(request: Request, approval_id: str, body: Annotation,
+                   identity: dict | None = Depends(require_reviewer)):
+    reviewer = _reviewer_or_400(identity, body.reviewer)
+    tenant = await resolve_tenant(request)
+    existing = await _ledger(request).approval(approval_id, tenant=tenant)
+    if existing is not None and not visible_to(
+            await activity_scope(request), existing.get("agent_id"),
+            existing.get("unit")):
+        raise HTTPException(404, f"unknown approval {approval_id}")
+    try:
+        a = await _ledger(request).annotate(
+            approval_id, reviewer, body.note, tenant=tenant,
+            idem=await idempotency_of(request, body.model_dump()))
+    except UnknownApproval:
+        raise HTTPException(404, f"unknown approval {approval_id}") from None
+    except IdempotencyMismatch:
+        raise HTTPException(422, "Idempotency-Key was already used for a "
+                                 "different request") from None
+    fault_point("after_write_commit_before_http")
+    return a