Customer refunds - Pactmark

Compatibility: Pactmark 0.1.x. This scenario uses the runtime effect and decision surfaces. The public authoring facade currently exposes read tools — see Limits and the approval-purchase-boundary example, which demonstrates this boundary honestly rather than simulating success.

The situation

A support agent handles a refund request. The assistant should gather the order, check eligibility against policy, compute the amount, and — if a human agrees — issue the refund through the payment provider. Every hard problem in agent engineering shows up in this one flow:

The effect is irreversible

Money leaves. There is no undo, only a compensating transaction that is itself a business action.

The amount is model-influenced

A model computed it. A human must see the normalized value, not the model’s narration.

The API can time out

A lost response tells you nothing about whether the refund was issued.

Someone will ask about it

Three months later, in a dispute, with a specific transaction id.

The WorkOrder

const request = createWorkOrderRequest({
  agent: { id: "support-refund-agent", version: "2.1.0" },
  goal: "Assess and, if approved, issue a refund for order ORD-88213.",
  input: { orderId: "ORD-88213", reason: "damaged_on_arrival" },
  context: {
    roleFamily: "customer_support",
    workflowId: "refund-v2",
    riskClass: "high",
  },
  workMode: "augment",
  autonomyMode: "delegate_review",
  decisionOwner: { mode: "registered_role", role: "refund_approver" },
  purpose: { code: "customer_service", registryVersion: "support@3" },
  dataClass: "confidential",
  retention: { mode: "host_policy", policyId: "support-7y" },
  requestedCapabilities: [
    "orders:read",
    "payments:refund",
  ],
  budget: {
    maxTurns: 8,
    maxModelCalls: 8,
    maxToolCalls: 6,
    maxActiveExecutionMs: 60_000,
    monetaryCeiling: {
      amount: 500,
      currency: "EUR",
      maximumPriceBoundVersion: "eur-2026-q3",
      maximumPriceBoundExpiresAt: "2026-09-30T00:00:00Z",
    },
  },
  deadline: "2026-08-05T18:00:00Z",
});

Three details do most of the work:

refund_approver

The person who asked is not automatically the person who may approve. Support agents raise refunds; approvers approve them.

delegate_review

The run is allowed to do the work, and the output is reviewed before it counts as done.

500 EUR

A hard ceiling with an explicit price-bound version and expiry. Above it, the run cannot proceed regardless of what anyone approves.

The policy

definePolicy({
  id: "support.refund.policy",
  implementationVersion: "2.1.0",
  default: "deny",
  rules: [
    { riskClass: "R1", decision: "allow_with_grant" },   // read the order
    { riskClass: "R2", decision: "allow_with_grant" },   // annotate the ticket
    { riskClass: "R4", decision: "require_approval" },   // issue the refund
  ],
});

R3 and R5 have no rule, so they are denied. That is not an omission — it is the default working correctly.

The tools

security: {
  riskClass: "R1",
  dataClasses: ["confidential"],
  reversibility: "not_applicable",
  requiredScopes: ["orders:read"],
  egress: {
    mode: "allowlist",
    destinations: ["https://orders.internal.example.com"],
    methods: ["GET"],
    credentialSlots: ["orders.api"],
  },
  networkEnforcement: "required",
  maxCallsPerRun: 3,
  timeoutMs: 4_000,
}

security: {
  riskClass: "R4",
  dataClasses: ["confidential"],
  reversibility: "irreversible",
  requiredScopes: ["payments:refund"],
  egress: {
    mode: "allowlist",
    destinations: ["https://api.payments.example.com"],
    methods: ["POST"],
    credentialSlots: ["payments.api"],
  },
  networkEnforcement: "required",
  maxCallsPerRun: 1,
  timeoutMs: 15_000,
  costCeiling: 500,
}
// effect strategy: reconcilable
// the provider supports lookup by idempotency key

maxCallsPerRun: 1 on the refund tool. If the model somehow proposes a second refund in the same run, the ceiling refuses it before policy even has to think about it.

The approval

Figure 1. The approver sees a normalized preview, re-authenticates, and consumes a one-use proof. The proof never travels through the browser, a log line, or the model. What the approver actually sees:

Field	Value
`operationClass`	`payment.refund`
`normalizedTarget`	`payments:acct_9f21/order_ORD-88213`
`materialConsequence`	”€64.90 will be returned to the customer’s card ending 4417.”
`reversibility`	`irreversible`
`contentDigest`	`sha256:…` — the exact payload that will be sent
Risk class	R4
Policy	`support.refund.policy` digest
Grant	`grant_01J…`, expires in 14 minutes

Note that the amount appears in materialConsequence, derived from the normalized payload — not from a sentence the model wrote. If the model’s narration and the payload disagree, the human sees the payload.

The day the payment API times out

Figure 2. reconcilable was registered on the tool before any of this happened. That prior declaration is what makes the recovery path legitimate rather than improvised. The sequence:

EffectPrepared

With an effectKey derived from the order and idempotency key, and strategy: "reconcilable".

EffectDispatched

Attempt 1. The POST goes out.

The connection drops

No response. EffectUncertain, then EffectNeedsReconciliation with effectMayHaveOccurred: true.

The run parks

It does not retry. It does not fail with “refund failed” either, because that would be a false statement.

Reconciliation looks it up

npx pactmark effects reconcile <runId> <effectId> \
  --resolution '{"kind":"recovered_acknowledgement","providerRef":"re_1Nc…"}'

The provider is queried by idempotency key. If the refund exists, its real outcome is recorded.

Or it is abandoned, honestly

If the provider cannot answer, abandon_uncertain records that the effect may have occurred. Anything depending on it raises KAF_EFFECT_ABANDONED_UNCERTAIN. That friction is the point.

Compare with the common alternative: retry on timeout. On a payment provider without perfect idempotency, that is a double refund. Pactmark makes you decide before the outage which of those two failure modes you are willing to accept.

The evidence

{
  "claim": {
    "statement": "A €64.90 refund was authorised by an approver holding the refund_approver role and acknowledged by the payment provider.",
    "claimType": "authorised_financial_effect",
    "scope": "run_01J8… only"
  },
  "supports": [
    "The approver re-authenticated and consumed a one-use challenge bound to this exact effect preview",
    "The dispatched payload digest matches the digest shown in the preview",
    "The provider returned an acknowledgement recorded under effect_01J8…"
  ],
  "doesNotProve": [
    "That the refund was commercially correct or policy-compliant",
    "That the customer received the funds",
    "That the order data read from the orders service was accurate"
  ],
  "workSplit": {
    "ai": { "kind": "numeric", "value": 4, "unit": "tool_calls" },
    "human": { "kind": "numeric", "value": 1, "unit": "decisions" },
    "description": "Assistant assembled and proposed; a human approver authorised the effect."
  }
}

Read doesNotProve again. “That the customer received the funds” is a genuinely different claim from “the provider acknowledged the refund”, and conflating them is how disputes go badly.

What you still own

The desk limit

€500 is a number you chose. Pactmark enforces it faithfully whether or not it is right.

The approver's understanding

An accurate preview can still be misread. TM-05 records this residual risk explicitly.

Provider idempotency

reconcilable is your assertion about the provider. If it is wrong, the strategy is wrong.

Someone to resolve parked effects

Parked runs need a human on a rota, not a dashboard nobody opens.

Approval integration

Building the operator flow correctly.

Tools and effects

Why the strategy must be registered in advance.

​The situation

The effect is irreversible

The amount is model-influenced

The API can time out

Someone will ask about it

​The WorkOrder

​The policy

​The tools

​The approval

​The day the payment API times out

​The evidence

​What you still own

The desk limit

The approver's understanding

Provider idempotency

Someone to resolve parked effects

Approval integration

Tools and effects

The situation

The WorkOrder

The policy

The tools

The approval

The day the payment API times out

The evidence

What you still own