Worked example

Decision-model gate on refunds

A refund agent gated by a typed decision model, recorded so the threshold, the reviewer's queue, the router, and the missing reasons are all governable.

Scenario

A refund agent with a typed decision model in front of it

The agent proposes refunds. A decision model answers two typed questions about each one, and a threshold decides what happens next.

Unattended

approve at 0.80 or above

Refunds up to 200 USD that fit policy run without a person. Two percent of them are still sampled into review.

Reviewed

everything in between

A refund reviewer sees the proposal, the model's answer and confidence, and whether the case was routed or sampled.

Refused

refuse at 0.90 or above

The refund is refused with an appeal route, and the decision says that no reasons were produced.

The records use a fictional provider and model. The field mapping below shows how a real integration fills them. The explainer on typed decision models covers why each record is needed.

Threshold

The threshold is a policy record

Under STD-08 §2.6 the number that decides between acting and asking is held as policy, pinned to what it was tuned against, with a trigger that fires when that changes.

The questions are published, and their hash is recorded on every decision. Reordering the options changes the hash, which fires the model_change trigger. 

{
  "schema_id": "QS-REFUND-GATE-1",
  "description": "Questions asked of the decision model for every refund the agent proposes. Option order is part of the schema.",
  "questions": [
    {
      "id": "refund_risk",
      "type": "choice",
      "prompt": "Given the order history, the customer message, and the proposed refund, how should this refund be handled?",
      "options": [
        "approve",
        "review",
        "refuse"
      ]
    },
    {
      "id": "policy_fit",
      "type": "yes_no",
      "prompt": "Does the proposed refund fall inside the published refund policy for this order type?"
    }
  ]
}
{
  "schema_version": "1.0.0",
  "policy_id": "POL-REFUND-GATE-THRESHOLD",
  "version": "1.2.0",
  "title": "Refund gate: decision threshold for unattended refunds",
  "provenance": {
    "author": "Support Operations Policy Group",
    "adopted_at": "2026-09-01T00:00:00Z",
    "evidence_refs": [
      "EVID-REFUND-LABELLED-2026Q2",
      "EVID-REFUND-THRESHOLD-SWEEP-2026-08"
    ]
  },
  "assumptions": [
    "Unattended refund when refund_risk = approve with confidence at or above 0.80, policy_fit is yes, and the amount is at most 200 USD. Everything else goes to the refund reviewer, and refuse at or above 0.90 is refused with a route to appeal.",
    "The threshold was set against 2,400 labelled refunds from Q2 2026, on which it approved 71% unattended with 0.6% later reversed on review.",
    "It was tuned for model gatekeeper-typed at version 2026-08-28, with question schema sha256:6b7b983829db07d46e80c26e5e6741087b968373cd4751ff833984e43189a59b, in the option order approve, review, refuse.",
    "It trades a higher review load for fewer wrong unattended refunds: a wrongly approved refund costs the institution more to recover than a correct refund costs to review.",
    "Confidence is the provider's margin, not a probability that the answer is right. The 0.80 was chosen from the labelled set, not read off the model's number."
  ],
  "review_triggers": [
    {
      "trigger_id": "TRG-MODEL-CHANGE",
      "kind": "model_change",
      "condition": "deployed model version, question schema hash, or option order differs from the values in assumptions",
      "action": "suspend"
    },
    {
      "trigger_id": "TRG-SAMPLE-REVERSALS",
      "kind": "evidence_threshold",
      "condition": "reversal rate in the unreviewed sample > 0.02 over 30 days",
      "action": "review_required"
    },
    {
      "trigger_id": "TRG-INJECTION",
      "kind": "incident_class",
      "condition": "any unattended refund traced to text in the order or message that claimed prior approval",
      "action": "suspend"
    },
    {
      "trigger_id": "TRG-CHALLENGES",
      "kind": "challenge_volume",
      "condition": "more than 10 refund challenges decided against the system in 30 days",
      "action": "review_required"
    },
    {
      "trigger_id": "TRG-ELAPSED",
      "kind": "elapsed_time",
      "condition": "90 days since adopted_at",
      "action": "review_required"
    }
  ],
  "expires_at": "2026-12-01T00:00:00Z",
  "status": "active",
  "supersedes": "POL-REFUND-GATE-THRESHOLD@1.1.0"
}

Grant

The grant enumerates the chain and names its evaluator

The router that picks the model and the retrieval filter that decides what the model sees are hops with their own grants. Detection comes from a team that does not run the agent.

{
  "grant_id": "GRANT-2026-0311",
  "mode": "unattended",
  "policy_refs": [
    {
      "policy_id": "POL-REFUND-GATE-THRESHOLD",
      "version": "1.2.0"
    }
  ],
  "intervention_ref": "INT-REFUND-REVIEW-1",
  "chain": [
    "GRANT-2026-0312",
    "GRANT-2026-0313",
    "GRANT-2026-0311"
  ],
  "revocation_conditions": [
    "An unattended refund is traced to authorization inferred from content.",
    "The model serving the gate differs from the pinned version and the gate kept running.",
    "Expected refund errors per week exceed the review team's stated answer capacity."
  ],
  "correction_capacity": {
    "detection": {
      "present": true,
      "evidence": "Two percent of unattended refunds are sampled into review every day and their reversal rate is reported apart from the routed queue by Support Quality, which does not operate the agent.",
      "evaluator": "Support Quality (independent review team)",
      "independent_of_executor": true
    }
  }
}

Review

The reviewer's queue is part of the specification

Under STD-08 §3.6 the routing threshold is named on the intervention specification, the record says the reviewer sees the score, and a sample of what ran unattended reaches review.

{
  "threshold_policy_ref": "POL-REFUND-GATE-THRESHOLD@1.2.0",
  "score_shown_to_owner": true,
  "unreviewed_sample": {
    "share": 0.02,
    "cadence": "Drawn daily; approval and reversal rates reported weekly, apart from the routed queue."
  }
}

Decision

The decision records what decided it

The typed_judgment block holds what a challenge needs without the vendor: the pinned model, the questions it answered, what it returned, the threshold that acted on it, and where the reasons came from.

decision.confidence holds the probability of the chosen option. typed_judgment.confidence holds the provider's margin, which is a different number, and the record says so. 

{
  "decider": {
    "model": "gatekeeper-typed",
    "model_version": "2026-08-28",
    "provider": "Example Decision Models Inc.",
    "gateway": "gateway.example.net"
  },
  "selected_by": "GRANT-2026-0312",
  "question_schema_hash": "sha256:6b7b983829db07d46e80c26e5e6741087b968373cd4751ff833984e43189a59b",
  "answer": "approve",
  "distribution": {
    "approve": 0.86,
    "review": 0.11,
    "refuse": 0.03
  },
  "confidence": 0.75,
  "confidence_semantics": "margin",
  "threshold_policy_ref": "POL-REFUND-GATE-THRESHOLD@1.2.0",
  "routed_to": "unattended",
  "reason_provenance": "none",
  "content_inputs_marked": true
}

Field mapping

Filling the record from a typed decision model's response

How the typed_judgment fields map to the response of Jev as exposed by the Pydantic AI integration. The same mapping applies to any model that returns typed answers with probabilities.

Record field Where it comes from
typed_judgment.answer The value of the typed output field the model filled.
typed_judgment.distribution provider_details['probabilities'] for that field, present for pick-one and rubric fields.
typed_judgment.confidence provider_details['confidence'] for that field: 0 to 1, one number per field.
typed_judgment.confidence_semantics margin. The provider documents the number as a margin, not a probability that the answer is right.
typed_judgment.decider The model name and pinned version in the client configuration. Never latest.
typed_judgment.question_schema_hash A SHA-256 over the output type definition, with Literal options and Enum members in their declared order.
typed_judgment.selected_by The grant of the router hop, when provider_details['tool'] shows the model chose a route.
typed_judgment.threshold_policy_ref Your policy record for the threshold, including any typesafe_boolean_threshold setting, pinned by version.
typed_judgment.reason_provenance none, because the model writes no text. account, if another model wrote an explanation afterwards.
typed_judgment.content_inputs_marked true only if messages, documents, and tool outputs were passed as marked content, apart from the authorization record.

Source: Pydantic AI documentation for TypeSafe (Jev).

Bindings

Each record answers a clause

Where each clause added for typed decision models lands in this deployment.

Clause Record In this deployment
STD-08 §1.5 Grant assumptions and revocation conditions, and content_inputs_marked The customer's message is content. A note in it claiming a manager already approved the refund cannot authorize anything.
STD-08 §2.6 Threshold policy record with a model_change trigger The 0.80 is a policy record naming its labelled set, pinned model version, question schema hash, and option order.
STD-08 §3.6 routing block on the intervention specification Two percent of unattended refunds go to review daily, and their reversal rate is reported apart from the routed queue.
STD-09 §1.5 and §1.6 chain on the head grant, selected_by on the decision The router and the retrieval filter are hops with their own grants, and the decision names the router that chose the model.
STD-02 §1.4 reason_provenance and the no_reasons_from_decider reason code The decision says it has no reasons and names the policy, threshold, and inputs, instead of showing the customer a rationale nobody derived.
STD-02 §8.6 Grant revocation condition on expected errors against answer capacity At 400 refunds an hour, expected errors are checked weekly against the review team's stated capacity of 150 answers.

Records

Download the records

Each record validates against its published schema, and the test suite checks that they agree with each other.

Glossary anchors

Glossary anchors used

Glossary terms that bind this example's clocks, artifacts, and ownership.