Track B / Volume 1 / B1.05

Approval gates

Sample lesson · Fictional examples

Lab starter repo: Coming soon

The public starter will use fictional data only. Read this lesson alongside the lab specifications; executable starter files are not available yet.

Outcome: Design a hard stop bound to the complete execution envelope and prove the intent was durable before execution.

The idea

A gate stops an action before it happens. A prompt, an after-send notification or a person named in a function argument is insufficient. Academy policy requires separate named-person approval of every send, payment and delete. It has no low-value auto-send exception. This is academy policy, not a statutory claim.

Lane & Hoy, Mei Tan and the operations director are fictional. Use the local mock, not a live mailbox or bank. Complete the owner/access/privacy/stop preflight from B1.01 first. Python is the working default, using Python 3.12 with type hints and dataclasses; runtime support is pending verification. The lab repository will be public and contain fictional Lane & Hoy data only, with no real customer data or secrets. Assessment-specific responses and variation seeds remain outside candidate-controlled public state. After installing the released locked package with uv sync --frozen, run uv run --offline pytest -m lab_b1_05. Installation may download packages; execution is offline and needs no API keys, database, Docker or cloud.

Architecture, in one path

Authenticated agent -> runtime proposes validated envelope
                    -> policy checks scope and mandatory gate
Authenticated person -> reviews exact envelope -> approval
                    -> policy mints registered expiring token
Facade + adapter    -> check token, scope, hash, freeze, identity
                    -> atomic claim + DURABLE INTENT
                    -> connector executes with operation key
                    -> OUTCOME + receipt (or UNKNOWN)
Restart             -> reconcile receipt before any retry

The four runtime components are runtime, policy, connectors and log. The owner's four-part handoff is outcome, steps, gates and record. A session role description is not an authenticated principal. The private executor has provider capabilities; the proposer cannot call it directly. No standing grant authorises send/pay/delete by itself. A valid approval cannot supply a missing provider scope, and a provider scope cannot supply approval.

What the approver approves

Hash the entire validated, frozen execution envelope, not selected fields. It binds tenant/workflow, request and operation IDs, action/contract version, principal/executor/acting-for authority, evidence versions and every field that affects the action. Email includes sender/reply-to, to/cc/bcc, subject, exact body/content type and attachment metadata plus byte digests. Payment includes the complete batch, beneficiary accounts, integer minor-unit amounts/currency, fees/options, dates and evidence. Delete includes precise resources/versions, mode and cascade effects. Unsupported fields are rejected.

Use SHA-256 over recursively key-sorted UTF-8 canonical JSON, preserving array order and exact text. Reject duplicate/unknown keys, non-finite numbers and floating-point money. The adapter verifies frozen attachment bytes, not a mutable URL. Changing only an attachment, CC, beneficiary or authority invalidates approval. A reused operation ID with different content is an error.

The full field and state contract appears in the lab specifications and B1.05 handout. No lesson permits a partial hash as an alternative.

Who may approve, and what a token proves

The mock IdP issues opaque caller contexts. Policy reads the person from that trusted context and checks current active status and role; it does not trust approve(..., "mei"). Agents, strangers, shared mailboxes, departed people and forged contexts fail.

Only policy may mint an opaque token registered in protected durable state with request/action/digest/authority, tenant/workflow, approver, expiry and consumption state. The adapter checks that issuance before dispatch. A fabricated object is not a token. Tokens expire at the earlier of 15 minutes after approval or the active request deadline, and authorise one operation only. A duplicate call may return the recorded result; it must not dispatch twice or reuse that token on another request.

Mei can approve a pending send request for 8 hours. Without a decision, it escalates to the operations director alone for a further 8 hours, then expires. Payment/delete requests hold after 24 hours. A backup can handle those only through an explicitly reassigned new request. Rejection, cancellation, withdrawal before claim, expiry and changed envelopes never authorise execution. A race between withdrawal and execution is serialised; after dispatch begins, stop and reconcile rather than pretend to undo a send.

Worked case: a supplier query

The draft is from mailbox-omitted to mailbox-omitted, concerning INV-4200 for SGD 4,200. Mei sees the complete message, attachment and supporting records. The proposal identity has draft/read scopes only; a mock administrator explicitly configured the private executor's mailbox-scoped send capability.

After Mei approves, the facade rechecks scope, identity, token and exact envelope. It writes durable intent, then sends once and records the receipt. If the attachment changes, it voids the approval. If provider scope was revoked, it denies even though Mei approved. If no one answers before the deadline, it escalates or holds; a small amount changes none of these rules. A THB invoice stays THB on the review card; uncertain translation requires human review and fresh approval if corrected.

The log and uncertain outcomes

Intent failure before dispatch leaves zero additional connector receipts. Failure after the connector accepted a send may leave one receipt and an unknown local outcome. The system cannot undo that send. On restart, read the receipt under the same operation key and record reconciliation; never assume a missing outcome means nothing happened.

Logs contain minimal intent/outcome metadata. Restricted payload snapshots expire under the customer's retention plan. Append-only application behavior does not prevent authorised retention/correction or prove tamper resistance against a host administrator. The regional briefing cites Singapore PDPA 2012, Thailand PDPA B.E. 2562 and IMDA's Model AI Governance Framework for Agentic AI; editions/URLs/sections are pending verification. Action approval is not privacy consent. Counsel/customer privacy roles decide legal questions, and FusionWork's DPO handles its own; incident notification decisions belong to the responsible customer roles.

Try it

A support lead requests: “Draft replies from the knowledge base, send simple ones and escalate the rest.” Deliver a one-page design and recut the request so every send has a separate named-person approval. Include the complete envelope, authenticated primary/backup, timeouts, provider scopes, intent/outcome events, retention and stop route. Demonstrate one valid send, an attachment-only change, a forged token and a revoked scope. If another operation automatically sends a message and that side effect cannot be disabled or separately gated, refuse that operation or change the connector.

Check yourself

  1. Why does a valid human approval not fix missing connector scope?
  2. What catches an attachment added after approval?
  3. What is different about an intent-write failure and an outcome-write failure?

Answers

  1. Scope and action approval are independent requirements; the adapter checks both at dispatch.
  2. A digest of the full envelope, including checked attachment byte digests, compared at dispatch; the changed request needs new approval.
  3. Intent failure prevents dispatch. Outcome failure may occur after acceptance; inspect receipts and reconcile instead of blindly retrying.

After the lesson

Complete the B1.05 handout and cumulative acceptance cases. A successful local mock establishes foundations, not permission to connect customer systems.