Here is the email behind submission SUB-1004, in the version this site uses for intake (case UW-S18). The cases named UW-S.. are this site's own; each one is a scripted model output built on the facts of a case the whole series shares, here UW-004.
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.
The intake agent, a program that uses a language model, reads the email once and writes down its facts for every later step. Its first attempt contains these two lines:
{"area_sq_ft": 1858, "building_value_usd": "2.4M"}
A person who reads that sees nothing wrong. "2.4M" is clearly two point four million, and 1,858 is the number in the email. A program sees two problems. It cannot compare "2.4M" with a number, because "2.4M" is a piece of text. And it reads 1858 as square feet, because that is what the name says, so the building is now about ten times smaller than it is.
The second problem is the dangerous one. In the policy fixture (the illustrative rule set of the example), rule R-SPRK-01 sends any warehouse over 50,000 sq ft without sprinklers to a senior underwriter. Picture the same mistake on an unsprinklered warehouse of 5,000 square metres, about 53,800 sq ft. Written as 5000 under area_sq_ft, it sits far below the limit, and no senior underwriter ever sees it. Nothing crashes. The number is wrong and well formed.
The broker wrote for a person. Every program after intake needs something else. This page is about what that something is.
What a sentence gives a reader, and what it gives a program#
A sentence is easy to write and hard to depend on. "The building is about 1,858 square metres" carries a number, a unit and a hedge ("about"), and a person keeps all three in mind without effort. A program that needs the floor area has to find the number among the words, work out which unit it is in, and decide what "about" means. Each of those steps is a guess.
Text written for a person, with no agreed place for each fact, is called free text. The broker's email is free text. So is the first answer of the underwriting agent on Start, a correct paragraph that the underwriter cockpit could not route.
Free text has a real place in this example. The reasons of a recommendation are sentences, because a person reads them. What free text cannot do is carry a value that a program has to act on: a number to compare, a word to route on, a flag that blocks an automatic decision.
Production pitfall. The first fix teams reach for is a regular expression over the model's prose: find "escalat", find a number before "%". It works on the ten answers the team looked at and fails on the eleventh, which says "a senior underwriter should look" without the word. The model was never told about the pattern, so nothing makes it keep to it.
A field: one named value#
The repair starts small. Instead of a sentence that mentions the roof age, write one name and one value:
{"roof_age_years": 9}
That is a field: one named value. The name says what the value is and in which unit (years). The value is the fact, and nothing else. A program that needs the roof age reads the field roof_age_years; it never searches.
A good field name does part of the checking. roof_age_years says the unit; roof_age would leave a reader to guess between years and months, and roof would leave a reader to guess whether it holds an age, a material or a condition. How to name fields well has its own chapter, Schema design.
A type: what kind of value a field may hold#
The intake agent wrote "2.4M" where a number was needed. The problem is not the digits. It is the kind of value. A type is the kind of value a field may hold: a number, a piece of text, true or false, a list, or a group of fields.
Three values for the same field show the difference:
| Value written | Its type | What a program can do with it |
|---|---|---|
2400000 | integer (a whole number) | Compare it, add it, sort by it |
"2.4M" | string (a piece of text) | Show it. Every calculation needs a guess first |
"about 2.4 million dollars" | string | Show it, and nothing else without reading it like a person |
A type is the first thing a reader can check for certain. "Is this an integer?" has one answer. "Is this a sensible building value?" does not.
JSON, the text format the example uses, knows only six kinds of value: strings, numbers, booleans (true or false) and null as the four simple ones, and objects and arrays as the two that hold other values. RFC 8259, the standard that defines JSON, lists exactly these. There is no date and no unit among them, which is why units go into field names and dates into agreed string formats. JSON Schema is the home of those details.
A record: fields that belong to one thing#
One field is rarely enough. The underwriting agent needs the roof age, the wind zone, the floor area and the sprinklers of the same building, together. A record is a group of fields that describe one thing. In JSON a record is written as an object, between curly brackets.
The record intake writes is the submission. In the scenario it has 63 fields; these are the ten the examples carry, for SUB-1004, as the corrected intake writes them:
{
"submission_id": "SUB-1004",
"occupancy": "office",
"construction": "masonry",
"year_built": 2001,
"area_sq_ft": 20000,
"building_value_usd": 2400000,
"sprinklered": true,
"roof_age_years": 9,
"wind_zone": "C",
"prior_losses_5y": 0
}
Every later program reads this record and never the email. That is the point of a record, and its risk: a wrong value in it is now the truth for every step that follows.
Each field of the submission is described once, in the example's field catalog. This is the entry for the roof age, copied from examples/uw-contracts/field_catalog.json:
{"name": "roof_age_years", "group": "roof", "type": "integer", "unit": "years", "required": true, "nullable": true, "source": "email", "description": "Roof age stated on the application. Required but nullable: null means nobody said; 0 would mean a new roof.", "example": 9, "constraints": {"minimum": 0, "maximum": 150}}
Read it as a small contract for one field. The value is a whole number of years. The key must always be present (required), but its value may be null when nobody said (nullable). The value comes from the email (source), so it must point at the words it came from. And the description draws a line a person would never need drawn: null means unknown, and 0 means a brand-new roof. The difference between required, optional and nullable is taught on JSON Schema; the reason a source is recorded for every value, on Schema design.
Before AI. A record is a row in a relational table, a field is a column, and a type is the column type. A database also checks part of this for you: a column declared NOT NULL must not hold the null value. What changes with a model is who fills the row. A form in a web application can only send what its inputs allow. A model can write any text at all, so every one of these checks has to run on what it wrote.
Serialization: the record on the way between programs#
A record lives inside a program as a value: an object in Python, a class instance in Java. To pass it to another program, it has to become text (or bytes) and then become a value again on the other side. Turning a value into text for transport or storage is called serialization. Turning the text back into a value is called parsing.
RFC 8259 says it in five words: "A JSON text is a serialized value." The model in this example works the other way around from an ordinary service. A service holds a value and lets a library serialize it, so its JSON parses unless that library has a bug. A model writes the text directly, character by character, with no value behind it. Nothing guarantees that the text parses at all, which is why parsing is the first of the four layers.
Producer and consumer#
Every record has two sides. The producer is whoever writes it. The consumer is whoever reads it and acts on it. The intake agent produces the submission; the underwriting agent consumes it. The underwriting agent produces the recommendation; the workflow code and then the underwriter cockpit consume it.
The two words come from messaging systems. Kafka's documentation describes producers as the client applications that publish (write) events and consumers as those that subscribe to (read and process) them, and it calls the two "fully decoupled and agnostic of each other". That last phrase is the reason contracts exist. A producer does not know every consumer, and a consumer cannot ask the producer what it meant. The only thing they share is the agreement about the data.
On the path of SUB-1004 there are five such agreements. The first is intake; the other four are the main subject of this site, each with its own chapter later.
| # | Boundary | Producer | Consumer | Payload |
|---|---|---|---|---|
| 0 | Intake | intake agent (model) | the workflow | submission, 63 fields, plus where each value came from |
| 1 | Tool input | underwriting agent (model) | a tool | the arguments, for example {"submission_id": "SUB-1004"} |
| 2 | Tool result | a tool (code, outside provider) | underwriting agent | roof_assessment: status, roof age, source, evidence id |
| 3 | Agent handoff | one agent | the next agent | a handoff envelope around the payload |
| 4 | Final response | underwriting agent (model) | code, then the underwriter cockpit | the recommendation |
Notice the column of producers. Three of the five are models. In a system without models, every producer was code that someone reviewed. Here, most of the data that drives the next step was written by a component that can produce a different answer to the same input. Four contracts walks through each row.
What a contract promises, and to whom#
Now the main word. A contract is the agreement between a producer and its consumers: the shape of the data, plus the rules both sides rely on. The producer promises to keep it. The consumer may assume it, and builds on that assumption.
The recommendation contract of this site, version 1, promises seven things to the underwriter cockpit:
| The producer promises | So the consumer may |
|---|---|
recommendation is one of approve, decline, request_info, escalate | Route on it with a plain lookup, no text matching |
reasons holds one to six short sentences | Show them without truncating a page of prose |
citations holds rule ids such as R-ROOF-03 | Link each one to the policy fixture |
missing names fields such as roof_age_years | Ask the broker for exactly those fields |
stated_confidence is a number from 0 to 1 | Sort and filter (it is still only what the model says about itself) |
requires_human is true | Block every automatic decision |
policy_version names the rules that were read, such as 2026.2 | Check the answer against the same rules later |
Two more promises are rules rather than shapes: a decline or escalate cites at least one rule, and a request_info names at least one missing field. The machine-readable description of the shape is called a schema; the rules beyond the shape need checks of their own. Four layers separates the two.
The diagram puts the words of this page on one line, from the email to the contract.
Diagram: From a sentence to a contract · each step removes one kind of guess
Read left to right. Free text needs a reader to find each fact. A field gives the fact a name. A type says what kind of value it is. A record keeps the fields of one thing together. The contract turns all of it into a promise from the producer that the consumer may build on. No step makes a value true.
- 1 · Free text
- A sentence: Facts mixed with words. A program has to search and guess.
- 2 · Named and typed
- Field: One fact under a name that says what it is and in which unit.
- Type: Integer, string, boolean, list or object. The first thing a reader can check for certain.
- 3 · Grouped
- Record: The fields that describe one thing, read together.
- 4 · Agreed
- Producer: Writes the record and promises to keep the contract.
- Contract: What the producer promises and the consumer may assume. Not a promise that values are true.
- Consumer: Reads the record and acts on it, relying on the contract.
Read it left to right. Each step removes one kind of guess. A field removes the search. A type removes the conversion. A record keeps the facts of one thing together. The contract makes all of it a promise that a consumer may build on. Not one step makes a value true.
Common confusion. A contract does not promise that the content is right. It promises the shape and the rules that code can check. A recommendation can keep every promise in the table and still be false:UW-S10declines an 8-year roof citingR-ROOF-01, a rule for roofs older than 25 years. A schema checks shape, not truth.
Why a fluent sentence cannot be depended on#
The lab puts the same recommendation for UW-004 in three forms: the agent's paragraph, a loose JSON object with keys nobody agreed on, and the strict contract. For each form it shows which checks pass and what a consuming program can do.
The same result as a table. "Guess" means a program can do it only by interpreting words or keys that nobody agreed on.
| What a program must do | Free-form prose | Loose JSON | The strict contract |
|---|---|---|---|
| Route to the right queue (escalations go to a senior underwriter) | guess | guess | yes |
| Show which rule applies, as a link to the policy fixture | guess | no | yes |
| Check the cited rule against the facts in code | no | no | yes |
| Sort the cockpit queue by stated confidence | no | no | yes |
| Prove a person must decide | guess | guess | yes |
| Store it in a typed column and query it next month | no | guess | yes |
Look at the middle column. The loose JSON object is {"decision": "Escalate", "why": "roof ages differ: 9 vs 22", "rule": "roof gap rule", "confidence": "fairly high", "needs_person": "yes"}. It parses. Every value in it is a string, so every value needs a person to interpret it: "Escalate" with a capital letter under a key nobody agreed on, "roof gap rule" that cannot be looked up, "fairly high" that cannot be sorted, "yes" that is a word and not a boolean. JSON without a contract moves the guessing from the paragraph into the keys.
The example's validator says the same thing in its own terms. Against the recommendation schema the loose object fails with twelve errors: seven required fields are missing and five keys are not allowed. The paragraph does not get that far; it fails the parser at its first character.
One broker email becomes one record#
Back to the email from the start of the page. The example runs intake case UW-S18 with the real checks of examples/uw-contracts/. The model is a scripted stand-in, so these results show how the mechanism works, not how good any model is. The run shows three attempts at writing the submission. A successful run proves that the checks catch both mistakes from the opening, the string and the unit, and that the third attempt is accepted. It does not prove that a real model would make or fix them.
cd examples/uw-contracts
python3 run_contracts.py --case UW-S18
The model here is a scripted stand-in: these results show how the mechanism works, not how good any model is.
case boundary first failure outcome attempts
UW-S18 intake schema accepted_after_reask 3
attempt 1: first failure schema, action re_ask
[schema] /building_value_usd type: expected integer, got string
attempt 2: first failure domain, action re_ask
[domain] /area_sq_ft D-UNIT: the email gives square metres; the field holds square feet
attempt 3: first failure -, action accept
Read the two errors as two different kinds of check. The first is a type check: the contract says integer, the record holds a string. The check that catches it needs nothing but the record and the schema. The second error needs more. 1858 is a perfectly good integer, so the type check passes it. It is caught only because intake had to record where each value came from: the quoted words "1,858 square metres". A check that reads the quote finds a unit that the field name does not allow. The third attempt writes 20000 and declares the conversion from square metres.
Diagram: One broker email becomes one record · case UW-S18, three attempts
Read left to right. The intake agent turns the email into a record and points each value at the words it came from. A type check catches the string. Only the recorded source catches the unit, because 1858 is a good integer and a wrong number of square feet. The third attempt is accepted.
- 1 · The email
- Broker email: The quote request for SUB-1004, written for a person.
- 2 · Intake writes
- Attempt 1: building_value_usd holds the text "2.4M" where the contract says integer.
- Attempt 2: The value is now an integer, but area_sq_ft holds the square-metre number.
- Attempt 3: area_sq_ft is 20000 and the conversion from square metres is declared.
- 3 · Checks
- Type check: Needs nothing but the record and its schema. Catches the string.
- Source check: Reads where each value came from. Catches a unit the field name does not allow.
- 4 · The record
- Submission: The accepted record. From here on nobody reads the email.
That is the whole page in one run. A sentence became fields. The fields have types, so the wrong type was caught by a check that cannot be argued with. The record carries where each value came from, so a well-typed wrong number was caught too. The rest of the site makes each of those checks precise.
What this is not. This site owns the data contract, not the call that carries it. Where a tool's schema is published and how a tool call is executed belong to tools.sammuthu.com; how the instruction that asks for a record is written belongs to prompt.sammuthu.com.
For a coding agent. The same idea outside insurance: a coding agent finishes a change and reports{"files_changed": ["src/quote/roof_rules.py", "tests/test_roof_rules.py"], "tests_run": 42, "tests_passed": 42, "risk": "medium", "needs_review": true}. The CI pipeline is the consumer. "I ran the tests and they all look fine" cannot block a merge;tests_passedbelowtests_runcan. Review and CI lanes for coding agents live on diff-to-deploy.sammuthu.com.
How the standards describe these words#
Two standards sit under this page, and they are kept apart from any library or product. Both were read today; the log is in this site's facts file.
| Standard | What it says, in its own words | Where it matters here |
|---|---|---|
| JSON, RFC 8259 (Internet Standard, STD 90, December 2017) | "a lightweight, text-based, language-independent data interchange format"; four primitive types and two structured types; "A JSON text is a serialized value." | The text the model writes, and the six kinds of value a field can hold |
| JSON Schema (current version 2020-12) | "a declarative language for defining structure and constraints for JSON data"; checking needs a separate validator | The machine-readable shape of each contract, taught on JSON Schema |
Neither standard says anything about where a value came from, which unit it is in, or whether it is true. Those are parts of the contract that this site adds with checks of its own.
Who owns a contractProducer-owned, consumer-owned, or shared, and why it matters with a model
Three designs exist in ordinary systems. The producer owns the contract and publishes it; consumers adapt (typical for a public API). Consumers own it: each states what it needs, and the producer is tested against all of their expectations (consumer-driven contracts). Or a shared registry owns versioned schemas that both sides read.
With a model as producer, the first design has a gap: the model does not own anything. It cannot be told to keep a promise; it can only be asked, then checked. In this example the workflow code owns each contract that a model produces. It holds the schema, it validates every output, and it decides what happens on a failure. The consequence is a rule that holds on every page: a contract with a model on the producing side is enforced by the consumer side, every time, because nothing on the producing side can enforce it. Who validates at each boundary is the subject of Four contracts; how a contract changes while old producers and consumers live on, of Evolution.
Free text inside a recordWhy reasons stay sentences, and what that costs
The recommendation keeps one free-text field on purpose: reasons. A person needs sentences to check the agent's argument, and no enum could hold "the application says 9 years; the provider says 22". The cost is that the contract can say little about it: at least one sentence, at most six, each between 1 and 400 characters. Everything inside is unchecked text written by a model that read retrieved passages and a broker's email.
Two consequences follow. No program may act on the content of a free-text field; anything a program acts on gets its own typed field (citations holds the rule ids that the reasons talk about). And a free-text field is untrusted where it is shown: case UW-S15 passes every check while a reason carries markup and an instruction copied from a retrieved passage. Security is the home of that problem.
Units: name, field, or provenanceThree places a unit can live, and what each one lets a checker do
A unit can live in the field name (area_sq_ft), in a separate field ({"area": 1858, "area_unit": "sq_m"}), or in the provenance of the value (the quoted words plus a declared conversion). The name is the cheapest and the most readable, and it is the only option that keeps every consumer from doing arithmetic on two fields. A separate unit field moves conversion to every consumer, and an enum of units is one more thing that can drift. Provenance does not replace either: it is what lets a check catch a value that is well typed and in the wrong unit, as in UW-S18. The example uses the name for the unit and provenance for the check. Schema design is the home of units and provenance.
Checklist#
- List the free-text fields in your contracts. For each, confirm that no program acts on its content.
- Give every number a type and a unit, and put the unit in the field name.
- Write down the producer and every consumer of each record. Where the producer is a model, name the code that enforces the contract.
- For each field, decide three things separately: must the key be present, may the value be
null, and what doesnullmean. - Write the rules beyond the shape (
declinecites a rule) next to the schema, so that each one gets a check. - Never let "it parsed" stand for "it is right" in a log, a test name or a dashboard.
In one breath#
A sentence carries facts for a person; a program needs each fact as a named field with a type, grouped into a record. The producer writes the record and the consumer acts on it, and the contract between them is the shape plus the rules both rely on. When the producer is a model, nothing on its side can keep a promise, so the consumer side checks every promise every time. And even a record that keeps every promise can hold a wrong number, which is why one check is never enough.
This page caught a wrong type and a wrong unit, with two different kinds of check. The next page names all the kinds: an output can fail to parse, fail the shape, contradict itself, or be well formed and false. Four layers walks one recommendation through all four and shows what each check can and cannot see.