Approvals and the Routing Policy
Some actions need a person to sign off before they happen: returns, refunds, cancelling or changing an order, a backorder. This page describes the routing policy that decides who signs off — nobody, support, or a manager — the foundation it sits on, and the approvals API staff use to decide.
On both stacks the engine is wired in: every gated tool call and every paused return opens an inbox approvals row routed by the policy, and every approval is decided through one function (see The approvals API). Both stacks serve the same routes with the same JSON over the same tables, so the web UI calls one API whichever orchestrator is behind it. Not built yet: the customer-confirm step, and acting on an auto route for tool calls (an auto route is recorded but still waits for a person). The SLA worker is Python’s only — see The .NET stack.
The pieces
| Piece | Where | What it does |
|---|---|---|
| Policy file | agents/python/config/policies/approvals.yaml | The rules, read by both stacks |
| Golden cases | agents/python/config/policies/testdata/*.yaml | Input facts → expected route and reasons; both stacks run every one |
| Python engine | agents/python/shared/policy/{loader,facts,engine}.py | Validate the file, gather facts, evaluate |
| .NET engine | agents/dotnet/src/ECommerceAgents.Shared/Policy/ApprovalPolicy.cs | Same file, same rules |
| Inbox schema | migration 0006_approvals_foundation.sql | approvals, approval_events (append-only), outbox, notifications — see Database Schema |
| Repository | agents/python/shared/approvals/repo.py, shared/outbox.py | Guarded state transitions, audit trail, outbox |
Roles
support is staff and reviews what the policy routes to support; admin acts as manager and handles manager. Nobody decides their own request: decided_by must differ from requester_email, enforced by a database constraint and again in the repository. See the roles table in the Security Guide.
The policy file
policy_version: "2026-11-16.3"
kinds:
return_approval:
editable_fields: [amount, resolution]
sla_hours: 24
on_timeout: expire
rules:
- id: outside-return-window
route: manager
reason: Delivered more than 30 days ago, outside the return window
when:
- { fact: days_since_delivery, op: gt, value: 30 }
# ... more rules ...
- id: default-support
route: support
reason: Needs a support review
when: []
- Ordered, first match wins. A rule matches when all its
whenconditions hold. The last rule of a kind has an emptywhen, so a route is always found. An unconditional rule anywhere but last is rejected, because it would make the rest unreachable. - No expressions. A condition is
{fact, op, value}. Operators arelt,lte,gt,gte,eqandin(intakes a list). Nothing is evaluated from a string. - Facts:
amount,days_since_delivery,loyalty_tier(bronze/silver/gold),returns_90d,refund_to_spend_ratio(amount÷ lifetime spend) andaccount_age_days. - Unknown facts never match. A fact that could not be determined (the order is not delivered yet, no spend is recorded) makes any condition on it false, including
lt. So anautorule can never fire on missing evidence — it falls through tosupport. - Per kind:
editable_fields(what a reviewer may change when approving with edits),sla_hours(how long a review may wait before it is reminded and escalated) andon_timeout(rejectorexpire). - Loading fails loudly. An unknown key, fact, operator, route, loyalty tier or timeout action, a value of the wrong type, a duplicate rule id or a kind with no catch-all rule is an error at load time, not at the first approval that hits it.
The default policy
Kinds: return_approval plus the gated tools in shared/hitl.py (initiate_return, process_refund, cancel_order, modify_order, place_backorder). The three money kinds share one rule list.
| Order | Rule | Route |
|---|---|---|
| 1 | Delivered more than 30 days ago | manager |
| 2 | 3 or more returns in 90 days | manager |
| 3 | Refund over half of lifetime spend | manager |
| 4 | Amount over 500 | manager |
| 5 | Account under 30 days old and amount over 100 | manager |
| 6 | Amount ≤ 50, in window, fewer than 2 returns, ratio ≤ 0.25, account ≥ 30 days | auto |
| 7 | Amount ≤ 150, in window, silver or gold, fewer than 2 returns, ratio ≤ 0.25, account ≥ 30 days | auto |
| 8 | Everything else | support |
cancel_order: over 1000 → manager; up to 100 with fewer than 3 returns → auto; else support. modify_order: over 1000 → manager, else support. place_backorder: always manager.
Changing the policy
- Edit
approvals.yamland bumppolicy_version(it is stored on every approval it routes). - Add or adjust golden cases in
testdata/. Every rule must be hit by at least one case; both test suites enforce it. - Run both:
cd agents/python && uv run pytest tests/test_policy_engine.pyandcd agents/dotnet && dotnet test tests/ECommerceAgents.Shared.Tests --filter ApprovalPolicyTests.
The two engines read the same file and run the same cases, so a change that behaves differently on one stack fails there. One known gap: Python rejects an unquoted policy_version that YAML would read as a number (2026.11); .NET reads it as text. Always quote it.
Using the engine (Python)
from shared.policy import evaluate
from shared.policy.facts import gather_facts
facts = await gather_facts(order_id, amount=refund_amount) # who is asking: the current_user_email ContextVar
decision = evaluate("return_approval", facts)
decision.route, decision.reasons, decision.evidence, decision.version
gather_facts reads who is asking from the request’s identity and scopes every query to that person; for a stored approval (a worker has no request context) pass subject_email= explicitly. evaluate is pure: same facts, same decision, and evidence records the rule, its conditions and the facts it saw.
The outbox worker, SLA and notifications
A review that nobody picks up must not sit forever. sla_hours and on_timeout in the policy file drive that, and a small worker process enforces it.
Scheduling. When an approval enters pending_review — created there, or moved there (from pending_confirm, or back from needs_info) — the repository (shared/approvals/repo.py) sets due_at = now + sla_hours and enqueues two outbox rows in the same transaction: approval.reminder_due at APPROVAL_REMINDER_FRACTION of the way to the deadline and approval.sla_breached at the deadline. A timer is just an outbox row whose available_at is in the future. Scheduling lives in the repository, not in a route, so every creator gets it for free and a rolled-back approval leaves no timer. A kind missing from the policy file gets no deadline (and a warning).
What the handlers do (worker/approval_handlers.py):
| Event | Effect |
|---|---|
approval.reminder_due | A notification to the assigned role, once (audit event sla_reminder_sent) |
approval.sla_breached, assigned to support | Escalate once to manager (the admin role): assigned_role, escalation_level + 1, a fresh deadline and timers, audit event escalated, a notification to managers |
approval.sla_breached, at the top level | Apply the kind’s on_timeout (reject or expire) through a guarded transition, audit event sla_timeout, and tell the requester |
Handlers lock the approval and ignore the event unless it is still a pending_review at the same escalation level and deadline the timer was set for. So a redelivered event, an approval that was decided meanwhile, one that went to needs_info, and a timer left from an earlier trip through review are all no-ops. State changes go through repo.transition() / repo.escalate(), never a bare UPDATE.
The worker (worker/): an asyncio loop over outbox using SELECT ... FOR UPDATE SKIP LOCKED, so several workers can run safely. Each row runs in its own transaction with its handler’s writes. Claiming leases the row (locked_until, locked_by) and counts the attempt; if the worker dies, the lease runs out and another worker takes the row (a worker that lost its lease cannot also finish it). A failing handler rolls back, the row records a fixed error class (handler_error, database_error, timeout, unknown_topic — never payload text), and is retried with capped exponential backoff. After OUTBOX_MAX_ATTEMPTS the row is parked (failed_at set, never retried); admins list them at GET /api/admin/outbox/parked. SIGTERM finishes the current row, hands the rest back and exits. One Python worker serves both stacks, which share the database.
Notifications. The worker writes notifications, addressed to a person or to a role (“all support staff”). GET /api/me/notifications returns the caller’s own plus those addressed to the caller’s role, newest first, with the unread count; POST /api/me/notifications/{id}/read marks one read for the caller only (404 for someone else’s). The web sidebar shows a bell with an unread badge and a short list, polling every 30 seconds.
Run it locally.
cd agents/python && uv run python -m worker.main # needs DATABASE_URL and a migrated database
docker compose --profile agents up outbox-worker # or as part of the stack
Merchant limits (groundwork — nothing uses them yet)
Status: groundwork for #93. The schema, the seed data, the limits file and the guard functions below exist; nothing proposes or changes a price yet — no merchant-ops agent, no route, no screen calls them. They are here so the later steps (merchant-ops agent, batch review, execution) share one definition of “what a change may not do”.
agents/python/config/policies/merchant_limits.yaml holds the hard limits, separate from the approval routing policy above. A limit is hard: a line that breaks one is marked blocked with a reason code, and no approver can wave it through.
| Key | Meaning |
|---|---|
margin_floor_pct | Lowest margin a price may leave, (price − unit_cost) / price × 100. Exactly at the floor is allowed; a product with no unit_cost is blocked. |
max_change_pct_per_day | Most a price may move in one UTC day. Every change already in price_history today counts, plus the proposed one, each as |new − old| / old × 100. Exactly at the cap is allowed. |
block_during_active_promotion | Refuse a price change to a product covered by a promotion active now (promotion_products, promotions.is_active, start and end dates). |
max_lines_per_batch | Most lines one proposal batch may hold. |
max_restock_quantity | Most units one restock line may order (1 to INT32). Placeholder default 5000. |
max_restock_order_value | Most one restock line may commit, quantity × unit_cost. Placeholder default 50000. |
policy_version | Recorded on every guard result. Bump it when a number changes. |
shared/merchant/guards.py is pure: check_price_change, check_restock_line and check_batch take the proposed change plus the facts and return a GuardResult (ok, the reasons, the numbers used and the policy_version). Every applicable reason is reported, not just the first. The reason codes are fixed: invalid_price, missing_cost, margin_below_floor, daily_change_cap_exceeded, active_promotion, invalid_quantity, batch_too_large, restock_quantity_exceeded, restock_value_exceeded, and three raised when a line is applied: edit_beyond_proposal (a reviewer’s value raises the line: a restock above the proposed quantity, a price deeper than proposed or above where it started), price_moved (the price is no longer the one the line was proposed against) and restock_already_scheduled (stock is already on order). shared/merchant/facts.py reads the facts from Postgres (current price, products.unit_cost, today’s price_history steps, the promotions linked in promotion_products), and shared/merchant/limits.py validates the YAML at load time, failing loudly on an unknown key or out-of-range value.
A merchant proposal is not the staff inbox’s to decide, on both stacks. Every staff route answers 404 Approval not found for source proposal, byte-for-byte what a missing id gets, so staff cannot tell a proposal id from an unused one: decide() and the answer-info route (for every decision, including request_info, which used to park the batch in needs_info where its system-actor requester can never answer) and GET /api/approvals/{id}, matching the staff list that leaves it out (.NET’s list excludes it too); the legacy resume and admin approve/deny routes cannot reach one. The seller decides on /api/seller/proposals/{id}/decide (Python only). An SLA breach never expires a proposal under a decide in flight: see merchant proposals.
The schema is migration 0009_merchant_proposals.sql: proposals, proposal_lines (per-line status including blocked, the guard result as JSONB), promotion_products and a nullable products.unit_cost. The seeder fills unit_cost from the price by a per-category ratio and links the bundle and flash-sale promotions to their products, in a step appended after every other one so no previously seeded value moves.
The approvals API
On Python all of it lives in orchestrator/routes/approvals.py, every rule in orchestrator/approvals_service.py. On .NET the routes are Routes/ApprovalRoutes.cs and the rules are Approvals/ApprovalsService.cs (see The .NET stack); the paths, JSON field names, status codes and {"detail": ...} error bodies are the same.
| Route | Who | What |
|---|---|---|
GET /api/approvals | staff | The queue for the caller’s role (open items by default; ?status=all or one status). support sees what is routed to support; admin sees everything |
GET /api/approvals/{id} | staff, at or above the assigned role | The approval, its audit events, the policy evidence, the fields a reviewer may edit, and what it would execute |
POST /api/approvals/{id}/decide | staff | {decision: approve \| reject \| request_info, edits?, note?} |
POST /api/approvals/{id}/info | the requester only | {message} — answers a request for more information |
GET /api/me/approvals | any signed-in user | Their own approvals, status only |
Who may decide. Only staff; never the requester (compared case-insensitively, even for an admin deciding their own request); never the subject (the party who receives the money or benefit: an autonomous action’s requester is the system actor, so a staff member whose own order a credit is for must not be able to approve it; 403, every source except proposal, whose seller is the subject and the intended reviewer and decides on the seller routes, never through this check: SELLER_DECIDED_SOURCES in Python, SellerDecidedSources in .NET, named rather than silently exempt; a database CHECK, approvals_no_beneficiary_decision in migration 0012, backs it with the same exemption); and the staff role must be at or above the approval’s assigned_role — support decides what the policy routed to support (and auto requests still waiting for a person), admin decides everything including manager routes. A refusal is a 403 and changes nothing; it is checked before anything is claimed, and again after the claim is taken, on every path (approve, reject and request-info; tool and workflow alike). The first check ran on an earlier read, and an SLA escalation (support to manager) can land between that read and the claim; the claim is what closes the window (escalate refuses while one is held), so the fresh row is reloaded and the same decider check re-run, the claim is handed back and the normal 403 returned if it now fails. Role rank is case-insensitive on both stacks, and a route the policy engine returns that is not auto / support / manager fails closed to a manager (logged) on both.
| Caller | support route | manager route |
|---|---|---|
| The requester (any role) | 403 | 403 |
| Another customer or a seller | 403 | 403 |
support | allowed | 403 |
admin | allowed | allowed |
Deciding executes the action exactly once.
- Tool approvals take a TTL’d claim on the approval (
repo.claim), runexecute_approved_actionkeyed by the approval id — a reviewer’s edits change the tool input, so an input hash would let an edited retry run twice — then record the outcome fenced by the same claim token. A second concurrent decide gets409. - Workflow approvals resume the paused workflow from its checkpoint (
resume_workflow): an atomicpending -> processingclaim on thehitl_requestsrow fenced byclaimed_at, a hard timeout inside the claim TTL, and the remaining steps executed as the requester with the reviewer recorded separately. - A decision that fails to execute is not recorded: the claim is handed back, the approval stays in
pending_review, and the reviewer can try again. - An action that ran but whose recording lost the claim is finished, not abandoned. If the executor ran and the request row is
executed(carrying this approval’s id and result) but the approval was left inpending_review(the claim was taken over before the outcome was recorded), a retry of approve records the replayed result and moves the approval toexecuted/failedinstead of answering409forever, and the timeout handler (expire, which also serves .NET) does the same instead of marking an executed thingexpired. Request information on such a row is refused (409): the action already happened. A request that is resolved any other way is still a409. - The same holds for an autonomous-action (
event) credit, and a reject never contradicts a paid credit. The credit commits on its own transaction before the approval is recorded. If it ran and the recording died, reject answers409(“approve to record it”) rather than recordingrejectedwhile the customer keeps the money; approve replays the stored ledger row (it does not go back throughrun_once, whose reservation a cancelled attempt leaves “in progress”) and records the amount that actually went out: a retry’s conflicting amount edit is409, and a retry without edits records{"amount": "<paid>"}. Arun_oncereservation held by another live attempt is409with the claim handed back, never afailedapproval. The SLA handler records such a credit instead of expiring it. Tool and workflow approvals were already safe: their reject is a409once the request row isexecuted/resolved. - An
amountedit that is not a finite number a database column could hold (1e30, a 400-digit string, NaN, an integer past float range) is a422, never a500. - A claim lost while recording a workflow decision is a
409(“taken over by another reviewer”), like every other lost claim, on both stacks (it used to surface as a500).
Edits (approve only) are merged only for fields on the policy’s editable_fields for that kind; any other field, or a bad value, is a 422 and nothing runs. For a tool approval they merge into the tool input; for a return they are amount (not above what is under review) and resolution (refund, store_credit or replacement), and are honoured when the return is created.
The return workflow
workflow:return-replace is check-eligibility → policy-gate → initiate-return → search-replacements → apply-discount → finalize. The gate asks the policy engine (kind return_approval): auto proceeds without pausing; anything else pauses via ctx.request_info and opens an approval. Nothing is created before the gate — the returns row, the label and the order’s returned status all come from initiate-return, which runs only after auto or a reviewer’s approval. So a rejected or expired request leaves no return and the order untouched.
The pause carries the whole WorkflowState and is answered with a ReturnDecision (decision, resolution, amount, note, decided_by, approval_id), so the resumed run restores everything and runs as the requester. RETURN_HITL_THRESHOLD is only the fallback when the engine cannot decide. Migration 0010 expired the returns that were paused under the previous graph: their checkpoints cannot be resumed under the new response type.
Request more information does not touch MAF. The approval moves to needs_info, the reviewer’s question is written into the requester’s conversation, and a paused workflow stays paused (its hitl_requests row is parked as needs_info, so it cannot be resumed meanwhile). The requester’s answer (/info) moves it back to pending_review. A reviewer may still reject while it waits.
Expiry. At the top escalation level the worker does not just flip the row: it queues approval.timeout_apply, which calls orchestrator.approvals_service.expire(id) — it resumes a paused workflow as a rejection (nothing is created) or denies a tool request, then marks the approval expired (or rejected for on_timeout: reject). It runs as its own outbox row because resuming a workflow cannot happen inside the breach row’s locked transaction. An auto route (recorded, waiting for a person, assigned to support) gets the same SLA timers: reminded, escalated to a manager, then timed out.
The legacy endpoints
POST /api/orchestration/{run_id}/resume and POST /api/admin/hitl/requests/{id}/approve|deny are thin shims: they find (or, for a request that predates the inbox, create) the linked approval and call the same decide. They are staff-only now (they were admin-only) and keep the status codes they always returned. There is one code path.
The .NET stack
The .NET orchestrator serves the same API over the same tables (approvals, approval_events, outbox — migrations 0006+; .NET adds no schema). It is a port, so the rules above hold unchanged and each has a test in agents/dotnet/tests/:
| Piece | Where |
|---|---|
| Routes | Orchestrator/Routes/ApprovalRoutes.cs — /api/approvals, /api/approvals/{id}, /decide, /info, /api/me/approvals |
| Decide path | Orchestrator/Approvals/ApprovalsService.cs — authorisation, claims, edits, executing the paused work. The legacy POST /api/orchestration/{run_id}/resume and POST /api/admin/hitl/requests/{id}/approve\|deny are shims over it, and are staff (not admin-only) bounded by the assigned role, as on Python |
| Repository | Shared/Approvals/ApprovalRepository.cs — create (idempotent per source), guarded TransitionAsync, ClaimAsync / ReleaseClaimAsync with a fencing token and TTL, EscalateAsync |
| Timers | ApprovalRepository writes approval.reminder_due and approval.sla_breached in the same transaction as the state change (Shared/Approvals/Outbox.cs) |
| Intake | Shared/Approvals/ApprovalIntake.cs — routes a gated tool call (HitlGate) or a paused return (ChatRoutes) through the policy and opens the row; the policy gate’s own decision routes a return, not a second evaluation |
| Executor | Orchestrator/Routes/HitlActionExecutor.cs, run once per approval id through IdempotencyGuard.RunOnceAsync |
One worker for both stacks. The Python worker drains timers .NET wrote. The timer’s dedupe key ({topic}:{approval id}:{level}:{epoch ms of due_at}), its payload (approval_id, level, due_at) and the way due_at is written (microsecond precision, +00:00) are what the worker’s handlers compare, so they match what Python writes. ApprovalCrossStackTests dumps what .NET writes from Postgres and compares it to agents/python/tests/data/dotnet_approval_rows.json; test_approval_dotnet_rows.py loads that same file and runs the real worker handlers over it (reminder, escalation, a stale timer). Change the .NET write path and the .NET test fails until the fixture is regenerated (set APPROVAL_DUMP_PATH to the fixture’s path and run dotnet test --filter ApprovalCrossStackTests); the Python test then proves the worker still reads it.
Known differences from Python:
- An expiry cannot resume a paused .NET return. When a review nobody picks up times out at the top level, the Python worker resumes the paused workflow from its checkpoint with Python’s
ReturnReplaceMode; a checkpoint written by .NET’s workflow is MAF .NET’s own JSON (PostgresJsonCheckpointStore), not the format Python’s storage decodes, so that resume cannot succeed and the row ends up retried and parked (GET /api/admin/outbox/parked; reasoned from the two storage implementations, not run end to end). Reminders and the support-to-manager escalation resume nothing and work for .NET approvals, and a .NET tool approval expires correctly (the worker only denies the request row). Until the worker can hand a .NET workflow to .NET, an unattended .NET return is closed by a manager’s decision, not by timeout. - Requests stored before that change (PascalCase tool name, camelCase input keys) are mapped when approved: the name as before, and the top-level input keys with the same snake_case rule (
orderIdbecomesorder_id; nested objects are left alone). If two different keys would collapse onto one name with different values the mapping is a guess, so the approve is refused with422before anything is claimed or executed, the approval stayspending_review(it can still be rejected), and alegacy_input_refusedevent is written to its audit trail once. - A gated .NET tool call is stored with the same name and input keys as Python (
cancel_order,order_id), not the .NET pipeline’sCancelOrder/orderId— that is what the policy kinds, the executor and the other stack key on. - Customer confirm (
pending_confirm) is not built on either stack. /api/me/notificationshas no .NET route (see the parity matrix).
Source: docs/approvals.md — this page is generated from the repository.