Approval integration

Compatibility: Pactmark 0.1.x.

The sequence you are implementing

Figure 1. Your application owns the two middle lanes. Get the ordering right and the security properties come along for free; get it wrong and no amount of runtime enforcement saves you.

1. Detect that a decision is needed

Watch the event stream for ApprovalRequested, or read RunProjection.waitingDecisionId:

for await (const event of runtime.events(authority, runId)) {
  if (event.eventType === "ApprovalRequested") {
    const { decisionId, decisionGateDigest, proposedEffectDigest } = event.payload;
    await queueForReview({ runId, decisionId, proposedEffectDigest });
  }
}

The event carries digests, not content. Fetch the preview through the authenticated inspection API rather than trusting anything that arrived over a stream.

2. Render a preview a human can actually act on

<DecisionPreview>
  <Field label="Operation">{preview.operationClass}</Field>
  <Field label="Target">{preview.normalizedTarget}</Field>
  <Field label="Consequence">{preview.materialConsequence}</Field>
  <Field label="Reversible">{preview.reversibility}</Field>
  <Field label="Risk class">{gate.riskClass}</Field>
  <Field label="Cost bound">{gate.costBound}</Field>
  <Field label="Policy">{gate.policyRegistrationDigest}</Field>
  <Field label="Grant">{gate.capabilityGrantId}</Field>
</DecisionPreview>

Render normalizedTarget, never the raw model output. The normalized value is what will actually be used; showing anything else means the human approved a different thing from the one that happens.

3. Authenticate the actor now

Not “is there a session” — authenticate at decision time, with the strength your policy requires for this risk class. AuthenticationStrength and DecisionRole travel in the authority context, and a weak-authentication or wrong-role decision dispatches nothing.

4. Issue and submit the challenge

const { challengeProof, expiresAt } = await runtime.issueDecisionChallenge(
  authority,
  runId,
  decisionId,
  createCommandContext({
    commandId: createCommandId(),
    operation: "decision.challenge",
    payload: { decisionId },
  }),
);

// Submit it directly. Do not store it, log it, or pass it through a URL.
await runtime.approve(
  authority,
  runId,
  { decisionId, note: "Reviewed against ticket OPS-4821" },
  createCommandContext({
    commandId: createCommandId(),
    operation: "decision.approve",
    payload: { decisionId, challengeProof },
  }),
);

Never do this

Persist the proof, put it in a query string, include it in an email, log it at debug level, or let it enter model context.

Do this instead

Hold it in memory for the length of one request, submit it, and let it expire everywhere else.

The reference nextjs-vercel fixture keeps proofs in a short-lived server-side challenge vault rather than round-tripping them through the browser. That pattern is worth copying.

5. Handle rejection explicitly

await runtime.reject(
  authority,
  runId,
  { decisionId, reasonCode: "amount_above_desk_limit" },
  command,
);

ApprovalRejected carries a reasonCode and a nextStatus of planning, failed or cancelled. Rejection is a first-class outcome with its own path, not an error.

Idempotency and replay

Every command carries a CommandContext with a commandId. Replaying the same command returns the same semantic result. A command with the same id but different content conflicts with KAF_HTTP_IDEMPOTENCY_CONFLICT rather than silently overwriting. This matters most exactly here: a double-clicked approve button must not become two approvals.

KAF_COMMAND_IDEMPOTENCY_EXPIRED means the idempotency horizon has elapsed — the command is too old to be safely deduplicated. Treat it as “ask the human again”, not as “retry harder”.

What to test

// Approval replay returns the same result.
// A proof used twice is refused.
// An expired proof dispatches nothing.
// A cross-tenant approver is refused.
// A wrong-role approver is refused.
// A rejected decision produces a zero-dispatch counter.
// A decision bound to effect A cannot release effect B.

The zero-dispatch assertion is the important one. Asserting that an error was thrown is weaker than asserting that the external target was never called.

What you are still responsible for

Pactmark binds the decision. It cannot ensure the human understood the preview, that the preview was a fair summary, or that the desk limit in your policy is the right number. Threat model row TM-05 records that residual risk explicitly.

Human decisions concept

What an approval binds, and the eight things it can never waive.

Refund use case

The same flow in a complete, opinionated scenario.

Getting started

Core concepts

Guides

Deployment

Production

Security

Approval integration

The sequence you are implementing

1. Detect that a decision is needed

2. Render a preview a human can actually act on

3. Authenticate the actor now

4. Issue and submit the challenge

Never do this

Do this instead

5. Handle rejection explicitly

Idempotency and replay

What to test

What you are still responsible for

Human decisions concept

Refund use case

​The sequence you are implementing

​1. Detect that a decision is needed

​2. Render a preview a human can actually act on

​3. Authenticate the actor now

​4. Issue and submit the challenge

Never do this

Do this instead

​5. Handle rejection explicitly

​Idempotency and replay

​What to test

​What you are still responsible for

Human decisions concept

Refund use case

The sequence you are implementing

1. Detect that a decision is needed

2. Render a preview a human can actually act on

3. Authenticate the actor now

4. Issue and submit the challenge

5. Handle rejection explicitly

Idempotency and replay

What to test

What you are still responsible for