All chapters
  1. Start hereParseable is not valid. Valid is not correct
  2. Foundations · 1From free text to fields and records: why contracts matter
  3. Foundations · 2Syntax, schema, semantics, business validity: four different kinds of right
  4. Foundations · 3JSON and JSON Schema: types, enums, nullable fields, unions and nested objects
  5. Building · 4Typed models: Pydantic in Python, records and Bean Validation in Java
  6. Building · 5Provider output modes: prompting, JSON mode, constrained decoding and tool arguments
  7. Building · 6Tool input, tool result, agent handoff, final response: four contracts on one path
  8. Building · 7Schema design: names, required or optional, and where each value came from
  9. Operating · 8Validation stages: parse, schema, cross-field, domain rules
  10. Operating · 9Errors and repair: retry, clarify, correct within bounds, fall back
  11. Operating · 10Schema evolution: versions, compatibility and migrations
  12. Operating · 11Security: a valid string can still be an attack
  13. Operating · 12Observing contracts: validation failures, schema drift and replay artifacts
  14. Operating · 13Testing contracts: golden examples, property-based tests, fuzzing and contract suites
  15. Reference · 14Frameworks and standards: what each one checks for you
  16. Reference · 15Advanced: partial objects in a stream, polymorphism, multilingual data and typed events
  17. Reference · 16The insurance lab: one submission, four contracts, end to end
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Reference · 16

The insurance lab: one submission, four contracts, end to end

The whole example in one place: the 63 fields, the tool results, the recommendation, every validation stage, the repair loop and the stored record, with the code that produced them.

What you will understand
The whole path
One submission, SUB-1004, from the broker's email to the underwriter's decision.
Every contract
Intake, tool input, tool result, handoff, final response: each checked where it lands.
Twenty cases
This site's own cases, UW-S01 to UW-S20, run together, with the code.
Run it yourself
Standard-library Python, no key, no network, four commands.

This page puts the example of the whole site in one place. Every chapter used a piece of it; here it runs end to end. If you arrived here first, the Start page explains the idea in five minutes and each section below links to the chapter that explains its part.

An honest boundary first. This is an illustrative reconstruction for teaching. The insurer, the broker, the cases, the rules, the 63 fields, the roof-data provider and every number are invented. The roof thresholds are synthetic, not insurance practice. Nothing here reports the quality of a real system or model: the model here is a scripted stand-in, so these results show how the mechanism works, not how good any model is. The model recommends; a person decides.

The situation#

An insurer sells commercial property insurance through brokers. A broker sends a quote request by email. In our main case the email is for SUB-1004, a masonry office:

From: broker@brokerage.example
To: submissions@insurer.example
Subject: Quote request SUB-1004

Please quote property cover for Example Holdings LLC (synthetic), a masonry office, built 2001, floor area 1,858 square metres, sprinklered. Building value about 2.4 million dollars. The owner says the roof was replaced 9 years ago. Wind zone C. No losses, 0 claims in five years.

That is the version of the email in case UW-S18; the series' shared case UW-004 has the same facts with the area already in square feet. Three agents and one person handle it:

ActorDoesContract it produces
the intake agent (a model)turns the email into a submissionsubmission.v1, 63 fields with provenance
the assessment agentgets the roof assessment from the roof-data provider and hands it onhandoff.v1 around roof_assessment.v1
the underwriting agent (a model)reads everything, runs the rules, writes a recommendationrecommendation.v1 (or v2 with evidence ids)
the workflow (code)validates at every boundary, repairs within bounds, stamps identifiers, stores the recordrecommendation_record.v1
the underwriter (a person)decides in the underwriter cockpithuman_decision

The policy fixture, UW-GUIDE version 2026.2 (illustrative), has five rules. The one that matters for SUB-1004 is R-ROOF-03: when the roof age on the application and from the provider differ by more than 5 years, escalate to a senior underwriter. Here they differ by 13 (9 against 22).

Diagram: SUB-1004 from email to decision · who produces, who checks

Each lane is one actor. Read left to right. Payloads cross from a producer lane to a consumer lane, and the workflow checks every crossing before the next actor uses it. Only the underwriter decides.

  1. Intake agent (model)
    1. Submission: Read from the broker's email, each value with a quote.
  2. Assessment agent
    1. Roof assessment: From the roof-data provider, checked before use.
  3. Underwriting agent (model)
    1. Recommendation: escalate, citing R-ROOF-03.
  4. Workflow (code)
    1. Intake check: Catches the phrase and the square metres.
    2. Handoff check: Ties the result to SUB-1004 and run-7f3a.
    3. Four stages, record: Validates, repairs within 3 attempts, writes the record.
  5. Underwriter (person)
    1. Decision: A person decides; the cockpit writes human_decision.

Step by step through the contracts#

The example walks the whole path with one command, run_contracts.py --path. Real output, from a scratch copy:

intake                   intake agent (model)           ok
tool input               underwriting agent (model)     ok
tool input (a bad call)  underwriting agent (model)     REJECTED
    /submission_id: "1004" does not match ^SUB-[0-9]{4}$
tool result              roof-data provider (stand-in)  ok
agent handoff            assessment agent               ok
final response           underwriting agent (model)     ok
stored record            the workflow (code)            ok

Each line is one contract checked by the side that receives it (boundaries explains why the receiver checks). The lab below lets you click each point and see the payload, the producer, the validator, and what would break if nobody checked it.

BoundaryWhat crosses it for SUB-1004Checked byChapter
Intakethe submission: area_sq_ft 20000 (converted, declared), roof_age_years 9, building_value_usd 2400000the workflow, with submission.v1 and provenanceschema design
Tool input{"submission_id": "SUB-1004"}the tool runner, before the callboundaries
Tool resultstatus ok, roof_age_years 22, evidence_id EV-ROOF-0412the workflow, before the model sees itboundaries
Handoffan envelope for SUB-1004, run-7f3a, payload type roof_assessment.v1the underwriting agent's codeboundaries
Final responseescalate, citing R-ROOF-03, requires_human truethe workflow: four stagesvalidation

1. Intake: 63 fields, and where each came from#

The intake agent fills the submission. Its contract is the largest: 63 fields from the catalog, 16 of them required, each with a source (44 from the email, 11 from providers, 5 stamped by code, 3 derived by code). Search them here:

What to look forFieldWhy
required and nullableroof_age_yearsthe producer must say whether it knows; null is "nobody said", never 0
unit in the namearea_sq_ft, building_value_usda number without a unit is half a fact
stamped by codesubmission_id, intake_run_id, source_email_idthe model must not write identifiers
from a providerprovider_roof_age_years, roof_evidence_idtool results, with evidence ids

On SUB-1004 the intake agent took three attempts (case UW-S18): a phrase where a number belongs, then square metres in a square-foot field, then the declared conversion. The second attempt was schema-valid and wrong by a factor of almost eleven; only provenance caught it.

2. Tool input and tool result#

The underwriting agent calls get_roof_assessment with {"submission_id": "SUB-1004"}. The tool runner checks the arguments before the call; the bad call in the output above ("1004") never reaches the provider. The provider answers with a roof age of 22 years and the evidence id EV-ROOF-0412. The workflow checks the result against roof_assessment.v1 before it enters the model's context. On another day (case UW-S20) the provider answers status: "partial"; the workflow rejects the unknown value, counts it as drift and degrades the run to request_info.

3. The final response, through four stages#

The underwriting agent writes its recommendation. In case UW-S01 the first attempt is a fluent paragraph instead of JSON; the parse stage stops it, the re-ask carries the error, and attempt 2 is:

{"recommendation": "escalate", "reasons": ["The application says the roof is 9 years old; the roof-data provider says 22 years.", "The two ages differ by 13 years, more than the 5 years rule R-ROOF-03 allows, so a senior underwriter should look."], "citations": ["R-ROOF-03"], "missing": [], "stated_confidence": 0.62, "requires_human": true, "policy_version": "2026.2"}

It parses, has the agreed shape, agrees with itself (an escalation cites a rule), and is true for this run (the rule check also gives escalate under R-ROOF-03). Switch stages off in the explorer to see what each case would do to the underwriter if a stage were missing:

StageQuestionCatches, among this site's cases
parseis it JSON?UW-S01 prose, UW-S02 fence, UW-S03 cut off
schemathe agreed shape?UW-S04 to UW-S07, UW-S16
cross_fieldagrees with itself?UW-S08, UW-S09
domaintrue for this run?UW-S10 to UW-S14
none(passes every stage)UW-S15: a valid string carrying markup and an instruction

4. Repair within bounds#

Every failure goes to whoever can fix it without changing its meaning: code unwraps a fence, the model gets a re-ask with the errors, and after 3 attempts the workflow falls back. Step through any case:

OutcomeCases
accepted after deterministic repairUW-S02
accepted after a re-askUW-S01, UW-S03 to UW-S12, UW-S14, UW-S17, UW-S18 (3 attempts)
fallback: no valid recommendationUW-S13 (requires_human false three times), UW-S16 (ambiguous three times)
accepted, flagged untrustedUW-S15
upcastUW-S19
degraded to request_infoUW-S20

5. The record code writes, and the person who decides#

Code wraps the accepted recommendation in a record and stamps every identifier. The record of UW-S01 (the recommendation itself left out here):

{
  "schema_version": 1,
  "submission_id": "SUB-1004",
  "run_id": "run-7f01",
  "attempt_number": 2,
  "trace_id": "41f93ea7fa4048728e1f5d184202311e",
  "policy_version": "2026.2",
  "evidence_ids": ["EV-EMAIL-1004", "EV-ROOF-0412", "EV-GUIDE-0031"],
  "status": "recommendation_ready",
  "validation": ["parse", "schema", "cross_field", "domain"],
  "requires_human": true,
  "human_decision": null
}

attempt_number 2 says a re-ask happened. human_decision is null: nobody has decided yet. The underwriter cockpit is the web app where the underwriter sees the submission, the evidence and this record, and decides. When they do, the cockpit, not the model, writes the decision. The series' shared case UW-009 shows one: the agent recommended approve, and the underwriter declined.

{"decided_by": "underwriter", "decision": "decline", "override": true, "reason": "The broker's loss run shows an open water damage claim that is not on the application."}

Plain English. An override is a human decision that differs from the agent's recommendation. For example: approve recommended, decline decided. override is computed by code from the two values, and the reason is required, so that every override can be counted and read later.

Diagram: Who writes which part of the stored record

Read left to right. The model writes only the recommendation inside the record. Code writes every identifier and the validation result. Only the cockpit, on a person's action, writes the decision.

  1. The model
    1. recommendation: The object that passed all four stages, nothing else.
  2. The workflow (code)
    1. Identifiers: submission_id, run_id, attempt_number, trace_id, policy_version, evidence_ids.
    2. status, validation: recommendation_ready with four stages, or no_valid_recommendation with the errors.
  3. The underwriter cockpit
    1. human_decision: decided_by, decision, override, reason; null until someone decides.

All twenty cases at once#

The example runs every case of this site with run_contracts.py. Real output:

case     boundary     first failure  outcome                      attempts
UW-S01   final        parse          accepted_after_reask         2
UW-S02   final        parse          accepted_after_repair        1
UW-S03   final        parse          accepted_after_reask         2
UW-S04   final        schema         accepted_after_reask         2
UW-S05   final        schema         accepted_after_reask         2
UW-S06   final        schema         accepted_after_reask         2
UW-S07   final        schema         accepted_after_reask         2
UW-S08   final        cross_field    accepted_after_reask         2
UW-S09   final        cross_field    accepted_after_reask         2
UW-S10   final        domain         accepted_after_reask         2
UW-S11   final        domain         accepted_after_reask         2
UW-S12   final        domain         accepted_after_reask         2
UW-S13   final        domain         fallback                     3
UW-S14   final        domain         accepted_after_reask         2
UW-S15   final        -              accepted_flagged_untrusted   1
UW-S16   final        schema         fallback                     3
UW-S17   intake       domain         accepted_after_reask         2
UW-S18   intake       schema         accepted_after_reask         3
UW-S19   evolution    schema         upcast                       0
UW-S20   tool_result  schema         degraded                     0
CaseBuilt onThe raw outputChapter that explains it
UW-S01UW-004a fluent paragraph, no JSONfour layers, repair
UW-S02UW-004correct JSON in a code fencerepair
UW-S03UW-004JSON cut off by the output limitrepair, advanced
UW-S04UW-004"approved"JSON Schema
UW-S05UW-004policy_version absentrepair
UW-S06UW-004"stated_confidence": "high"typed models
UW-S07UW-004extra field premium_usdschema design
UW-S08UW-003request_info with nothing missingvalidation
UW-S09UW-001decline with no citationvalidation
UW-S10UW-002a rule that does not applyvalidation
UW-S11UW-004a rule the fixture does not containvalidation
UW-S12UW-007an old policy versionvalidation
UW-S13UW-004requires_human: falserepair
UW-S14UW-004evidence never gatheredschema design
UW-S15UW-005markup and an instruction in a valid stringsecurity
UW-S16UW-004an ambiguous word, three timesrepair
UW-S17UW-003a roof age of 0 with no sourceschema design
UW-S18UW-004a phrase for a number; square metresschema design
UW-S19UW-004version 1 read by a version 2 readerevolution
UW-S20UW-004an unknown status from the providerboundaries, observability

Run it yourself#

Everything above comes from examples/uw-contracts/ in this site's repository: standard-library Python 3, no key, no network, no model call. Copy the folder and run:

cd examples/uw-contracts
python3 run_contracts.py                  # the twenty cases, a summary, files in out/
python3 run_contracts.py --case UW-S18    # one case, every attempt and error
python3 run_contracts.py --path           # SUB-1004 across every boundary
python3 -m unittest                       # 43 tests

The folder's README lists every file and maps each concept to a function. The labs on this site run the same functions, ported to JavaScript and checked against the Python results row by row (1,290 rows on the day this was written). The Pydantic and Java comparison lives in examples/uw-contracts/twins/: a recorded run of real libraries, explained on typed models.

What this is not. Measuring how often the agent's recommendations are right, over many runs and with graders, is eval.sammuthu.com, which uses the same insurer and the shared cases UW-001 to UW-010. The runtime that would host these agents is harness.sammuthu.com.
For a coding agent. The same machinery fits a coding agent that reports its work as a change_report for CI: schemas/change_report.v1.json in the example, with one valid and one invalid sample checked by a test. Review and CI for coding agents are on diff-to-deploy.sammuthu.com.

Checklist#

What this example leaves outOn purpose, to stay readable

There is no real model, no real provider, no database and no web app: the underwriter cockpit is a role in the text and a lab on this page. The validator implements only the part of JSON Schema the site teaches. The repair loop is synchronous. Production systems add a queue for the human step, storage with access control for raw outputs, tracing through a real library, and the reliability concerns of retries and timeouts (see reliable.sammuthu.com). The contracts, the stage order, the bounds and the record shape carry over unchanged.

In one breath#

One quote request crosses five contracts on its way to a person: the intake agent's 63-field submission with provenance, the tool's arguments, the provider's result, the handoff envelope and the final recommendation, and each is checked by the side that depends on it. Failures go to whoever can fix them without changing their meaning, within three attempts, and code writes a record with stamped identifiers whether a valid recommendation exists or not. The underwriter decides, and the cockpit records it.

This is the end of the path. The glossary has every term in one place, and about lists the sources, the sister sites and what is original here.