A broker's portal sends a quote request for a commercial property to the synthetic insurer. The body says the building is sprinklered "yes", the roof is -3 years old, the wind zone is D, the submission id is SUB-12, the broker's email is missing its @, and the count of prior losses is not there at all. Six mistakes in one request, each of the kind a portal makes when its form and the insurer's contract drift apart.
What the portal needs back is not "400 Bad Request". It needs to know which six fields are wrong and why, so it can fix its mapping instead of opening a support ticket. The underwriter needs that nothing was stored, so a half-valid submission never reaches the review queue. And the auditor needs a record that the request came in, who sent it, and why it was refused.
The intake service that answers this way was not written by hand. The factory assembled it from the pattern PAT-INTAKE-API 2.1.0 and the product spec SPEC-INTAKE-001 in factory run FR-0003. This page runs that factory and then sends the requests.
The learner's question: how does a factory turn the intake part of a product spec into an endpoint whose every refusal is precise, tested and recorded, and what does that endpoint still leave undecided?
One boundary first, said once on this page. The insurance case is an illustrative reconstruction for teaching. It follows the shape of a real project by the author, but the insurer, the people, the rules and every number are invented, and nothing here reports the quality of a real system or model.
What "the factory builds the endpoint" means here#
Plain English. The intake endpoint is the front door: the one route a broker calls to hand in a submission. The factory does not invent that door each time. It takes a standard door (the pattern's skeleton), measures it to this product's spec, writes down the measurements as contracts, and fits it.
A broker is the outside party who sends a quote request for a client to the insurer; in Example C a broker is a person with the broker role. A submission is that request turned into structured data: in the series scenario 63 fields, of which Example C carries 11 in schema version 1 and 12 in version 2. The intake endpoint is the route that accepts a submission, here POST /submissions, allowed for the broker role only.
Be precise about what Example C's factory writes, because "the factory generates the service" can mean several things. The pattern's skeleton (service.py) is hand-written once and owned by the platform team: request parsing, authentication, role check, schema validation, idempotency key, audit record, event emission, trace and correlation id. The factory's four stations, all deterministic code in factory.py, check the spec and generate the product-specific artifacts: a data contract, an API contract, event schemas, a rollout manifest, and a service_config.json the skeleton runs from. run.py then loads that generated file from out/factory/ and starts the service from it, so every request on this page runs against what the factory wrote. No model takes part. Pattern versus configuration versus business logic explains why the skeleton is shared and the configuration is not.
Two kinds of run appear on this page and must never be confused. FR-0003 is a factory run: one execution of the factory that builds the service. run-7f3a is a runtime run: one execution of the underwriting workflow for submission SUB-1004, operating the service the factory built. The factory never processes a submission, never makes an underwriting decision and never touches production data. Insurance factory, part 2 is the home of building versus operating.
Before AI. A Java team would write the same front door as a controller with an annotated request class. Standard (Jakarta Validation 3.1, read 2026-11-20): its built-in constraints injakarta.validation.constraintsinclude@NotNull,@Min,@Max,@Patternand@Validcascades validation into nested objects. The factory's idea is the same, with one difference: the rules come from a spec the factory checks, and the tests that prove them are written once in the pattern, not by each team.
The intake part of the spec#
Station S1 reads these fields from product_spec.json; nothing below is invented on this page. Every field is required unless marked; roof_age_years may be null because an unknown roof age is a valid answer that the rule R-ROOF-02 handles later.
| Field | Type and rule | Example (SUB-1004, case UW-004) |
|---|---|---|
submission_id | string, pattern ^SUB-[0-9]{4}$ | SUB-1004 |
broker_email | string, ends in .example, marked PII | broker@brokerage.example |
occupancy | manufacturing, office, retail, warehouse | office |
construction | frame, masonry, steel | masonry |
year_built | integer 1850 to 2026 | 2001 |
area_sq_ft, building_value_usd | integer, at least 1 | 20000, 2400000 |
sprinklered | boolean | true |
roof_age_years | integer 0 to 150, may be null | 9 |
wind_zone | A, B, C | C |
prior_losses_5y | integer, at least 0 | 0 |
roof_material (v2 only) | optional, default unknown, five values | absent in v1 |
The route itself is configuration too: POST /submissions, roles ["broker"], body submission, idempotency: false, emits submission.received.v1 and submission.validated.v1. Keep the idempotency: false in mind; the failure test comes back to it.
Diagram: One intake request through the skeleton, and where each refusal leaves
The top lane is the skeleton of PAT-INTAKE-API, in its fixed order: parse, authenticate, check the role, validate the body against the schema, then the intake handler. The bottom lane is the exit each step can take: 400 malformed, 401 no valid token, 403 wrong role, 422 with a list of field errors, 409 for a duplicate submission id, or 201 with the run id and trace id. Every exit, refusals included, writes one audit record.
- Skeleton steps (fixed order)
- parse the request: Method and path must be strings; the route is matched from the spec's routes.
- authenticate: A known demo bearer token or nothing; demo tokens prove nothing about identity.
- role check: The caller's role must be in the route's roles.
- schema validation: Every field checked; all errors collected and sorted.
- intake handler: Stores the submission once, emits two events, moves it to validated.
- Exits (each writes an audit record)
- 400 or 404: The request cannot be matched to a route.
- 401 + Bearer challenge: No token or an unknown token; no field list is revealed.
- 403 + required roles: Known caller, wrong role.
- 422 + field errors: Every broken field, by name and rule; nothing stored, no event.
- 409 or 201: A second submission with the same id is refused; the first gets run id and trace id.
Follow a request from the left. It meets the skeleton's steps in a fixed order, and each step has its own exit: a malformed request leaves with 400, an unknown route with 404, no valid token with 401, the wrong role with 403, a body that breaks the schema with 422. Only a request that passed every step reaches the intake handler, which can still refuse a duplicate with 409 before it stores anything. Every exit, including the refusals, writes one audit record.
The factory run that builds it#
The script run.py in a scratch copy of examples/c-insurance-service/ first runs the factory. These are the first lines of its real output:
factory run FR-0003: PAT-INTAKE-API 2.1.0 + SPEC-INTAKE-001 (sha256:ecb151ab7f7f...)
S1-validate-spec passed
S2-generate-contracts passed
S3-assemble-service passed
S4-write-manifest passed
artifacts: data_contract.json, event_schemas.json, openapi.json, rollout_manifest.json, service_config.json
S1 confirmed the spec names the pattern and version and fills every extension point. S2 wrote the contracts. This is the generated contract for the intake route, from out/factory/openapi.json, as written:
{
"post": {
"operationId": "create_submission",
"requestBody": {"required": true, "x-schema-ref": "#/components/schemas/submission"},
"responses": {
"201": {"description": "ok"},
"401": {"description": "no valid demo bearer token"},
"403": {"description": "role not allowed: broker only"},
"422": {"description": "schema validation failed; body lists field errors"}
},
"security": [{"demoBearer": []}],
"x-emits": ["submission.received.v1", "submission.validated.v1"],
"x-roles": ["broker"]
}
}
(Reflowed onto fewer lines; keys and values as written.) The contract is OpenAPI-shaped, and the difference from OpenAPI matters. Standard (OpenAPI Specification 3.2.1, read 2026-11-20): the required top-level fields of an OpenAPI document are openapi, the specification version string, and info. Example C's generated file has info but no openapi field, its schemas use the example's own small format rather than the specification's Schema Object, and the example never runs it through an OpenAPI validator. The file says so itself, in a field named x-shape-note. It is a contract the example's own gate can check, not a document an OpenAPI tool should be expected to accept.
Sending the requests#
The first five lines of run.py's scripted day concern intake. Real output from the same scratch run:
# case actor status result
1 UW-004 broker 201 broker submits SUB-1004 (schema v1): state=validated run_id=run-7f3a
2 UW-F04 broker 422 broker submits an invalid body: field errors: broker_email does not match ^[^@\s]+@[^@\s]+\.example$; prior_losses_5y required; roof_age_years must be >= 0; sprinklered must be boolean; submission_id does not match ^SUB-[0-9]{4}$; wind_zone must be one of A, B, C
3 UW-F05 (no token) 401 no token, read SUB-1004: unauthenticated
4 UW-F05 broker 403 broker tries to record the decision: forbidden
5 UW-F05 other-broker 404 other broker reads SUB-1004: not_found
Row 2 is the opening story. Case UW-F04 is one of this site's own cases in cases.json, and its six mistakes come back as six field errors. Row 5 shows a choice worth noticing: a second broker asking for someone else's submission gets 404, not 403, so it cannot even learn that SUB-1004 exists.
To see full responses and the records left behind, a second script was written for this page (ch20_intake.py, scratch folder, not part of the example). It builds the service the same way the example's tests do and sends five intake requests in order: the invalid body, no token, an auditor trying to submit, the valid SUB-1004, and the same valid submission again. Real output:
--- 1 invalid body (UW-F04): 422
{"body": {"error": "validation_failed", "field_errors": [{"error": "does not match ^[^@\\s]+@[^@\\s]+\\.example$", "field": "broker_email"}, {"error": "required", "field": "prior_losses_5y"}, {"error": "must be >= 0", "field": "roof_age_years"}, {"error": "must be boolean", "field": "sprinklered"}, {"error": "does not match ^SUB-[0-9]{4}$", "field": "submission_id"}, {"error": "must be one of A, B, C", "field": "wind_zone"}]}, "headers": {"x-correlation-id": "corr-0001"}}
--- 2 no token: 401
{"body": {"detail": "missing bearer token", "error": "unauthenticated"}, "headers": {"www-authenticate": "Bearer", "x-correlation-id": "corr-0002"}}
--- 3 auditor submits: 403
{"body": {"error": "forbidden", "required_roles": ["broker"]}, "headers": {"x-correlation-id": "corr-0003"}}
--- 4 valid v1 (UW-004): 201
{"body": {"run_id": "run-7f3a", "state": "validated", "submission_id": "SUB-1004", "trace_id": "0c17c0046d4371b42858072814d7b4ca"}, "headers": {"x-correlation-id": "corr-broker-portal-01", "x-trace-id": "0c17c0046d4371b42858072814d7b4ca"}}
--- 5 same submission again: 409
{"body": {"error": "duplicate_submission"}, "headers": {"x-correlation-id": "corr-0005"}}
stored SUB-1004 roof_material: unknown | received_schema_version: 1
events: ['submission.received.v1', 'submission.validated.v1']
audit:
{"seq": 1, "principal": "u-broker-n1", "route": "create_submission", "status": 422, "outcome": "validation_failed", "trace_id": null, "correlation_id": "corr-0001"}
{"seq": 2, "principal": null, "route": "create_submission", "status": 401, "outcome": "unauthenticated", "trace_id": null, "correlation_id": "corr-0002"}
{"seq": 3, "principal": "u-auditor-1", "route": "create_submission", "status": 403, "outcome": "forbidden", "trace_id": null, "correlation_id": "corr-0003"}
{"seq": 4, "principal": "u-broker-n1", "route": "create_submission", "status": 201, "outcome": "ok", "trace_id": "0c17c0046d4371b42858072814d7b4ca", "correlation_id": "corr-broker-portal-01"}
{"seq": 5, "principal": "u-broker-n1", "route": "create_submission", "status": 409, "outcome": "duplicate_submission", "trace_id": null, "correlation_id": "corr-0005"}
Read it as four claims, each backed by a line. A validation error is a refusal that names the field and the rule it broke; the 422 body lists all six, sorted by field, so the portal can fix them in one pass. The 401 carries a www-authenticate: Bearer header, so a client knows which kind of credential is expected; the 403 names the role that would have been allowed. The 201 returns the runtime run_id and a 32-hex trace_id, and echoes the caller's own correlation id. And the submission was sent under schema version 1 but stored under version 2, with roof_material filled with its declared default unknown: old clients keep working while the contract grows.
The audit lines are the part an auditor reads. Every request left one record, including the three refusals, each with the principal (or none, for the 401), the route, the status and the outcome. Only the accepted request has a trace id; refused requests are tied together by the correlation id instead.
Where the 422 comes from#
Schema validation is checking a request body against a declared description of its fields before any product code sees it. In Example C it is skeleton step 4, and its mechanism is one function, quoted verbatim from schemas.py : validate:
def validate(obj, schema: dict) -> list[dict]:
"""Return a sorted list of field errors; an empty list means valid."""
if not isinstance(obj, dict):
return [{"field": "$", "error": "must be an object"}]
fields = schema["fields"]
errors = []
for name in obj:
if name not in fields:
errors.append({"field": name, "error": "unknown field"})
for name, f in fields.items():
if name not in obj:
if f.get("required") and "default" not in f:
errors.append({"field": name, "error": "required"})
continue
v = obj[name]
if v is None:
if not f.get("nullable"):
errors.append({"field": name, "error": "must not be null"})
continue
if not _type_ok(v, f["type"]):
errors.append({"field": name, "error": "must be " + f["type"]})
continue
if "enum" in f and v not in f["enum"]:
errors.append({"field": name, "error": "must be one of " + ", ".join(f["enum"])})
if "min" in f and v < f["min"]:
errors.append({"field": name, "error": "must be >= " + str(f["min"])})
if "max" in f and v > f["max"]:
errors.append({"field": name, "error": "must be <= " + str(f["max"])})
if "pattern" in f and not re.match(f["pattern"], v):
errors.append({"field": name, "error": "does not match " + f["pattern"]})
if "min_length" in f and len(v) < f["min_length"]:
errors.append({"field": name, "error": "must have at least " + str(f["min_length"]) + " characters"})
return sorted(errors, key=lambda e: (e["field"], e["error"]))
Three design choices in it are the ones to copy. It collects every error instead of stopping at the first, which is what makes one round trip enough. It rejects unknown fields, so a misspelled field name is an error, not silently dropped data. And _type_ok refuses a boolean where the contract says integer, because in Python True is an int; the test test_bool_is_not_an_integer holds that line. The module's docstring is honest about its scope: the format is "JSON-Schema-like, not JSON Schema".
Fixtures, tests and the fields every record carries#
A test fixture is a fixed, versioned input a test uses, so the same case runs the same way every time. Example C keeps its fixtures in cases.json: the series cases UW-003 and UW-004 and this site's own UW-F01 to UW-F05. The invalid body of the opening story is a fixture, quoted from the file:
{"schema_version": 1, "submission": {"submission_id": "SUB-12", "broker_email": "broker-at-brokerage.example", "occupancy": "office", "construction": "masonry", "year_built": 2001, "area_sq_ft": 20000, "building_value_usd": 2400000, "sprinklered": "yes", "roof_age_years": -3, "wind_zone": "D"}}
The test that uses it asserts the exact list of six errors and then checks that nothing happened: self.assertEqual(self.svc.store, {}) and self.assertEqual(self.svc.bus.events, []) close test_schema_violation_is_422_with_exact_field_errors in tests/test_auth_validation.py. A refusal that wrote nothing is a stronger claim than a refusal with the right status code, and the test checks both. The whole suite, run in the scratch copy:
Ran 50 tests in 0.039s
OK
Eleven of the fifty prove intake behavior directly (missing and unknown tokens, the auditor who cannot submit, the other broker's 404, the 422 cases, the schema version checks, the v1 to v2 upgrade); the uwmap lab below lists them by name. The time is from this one run and is not a benchmark.
An audit field is a field every record carries so a later reader can reconstruct who did what, when, under which version. Example C writes one audit record per request in Service.handle, refusals included, and stamps every event with an envelope. The two sets of fields, from the real output:
| Where | Field | Example from SUB-1004 | Why it is there |
|---|---|---|---|
| audit record | seq, at | 1, 2026-11-20T09:00:03.000Z in run.py's audit (injected clock) | order and time of the request |
| audit record | principal, roles | u-broker-n1, broker | who acted, and in which role |
| audit record | route, status, outcome | create_submission, 201, ok | what was asked and what happened |
| audit record and event | trace_id | 0c17c0046d4371b42858072814d7b4ca | one trace per runtime run |
| audit record and event | correlation_id | corr-broker-portal-01 | the caller's own id, echoed back |
| audit record and event | run_id, submission_id | run-7f3a, SUB-1004 | which workflow execution, which submission |
| event | event_type, event_schema_version | submission.received.v1, 1 | what happened, under which event contract |
The idempotency key sits in the same skeleton, step 5, and the spec decides where it applies. On SUB-1004's later routes (assessment and decision) it is required, and the tests prove that a repeated request with the same key replays the stored response without a second write. On the intake route the spec sets idempotency: false and relies on the submission id instead: a second submission with the same id is refused with 409. That choice has a consequence, which the failure test below shows.
Security note. Logs mask the broker's email (b***@brokerage.example,obs.py : mask), but the eventsubmission.received.v1carries the submission as received, email included, because its schema requires thesubmissionfield. Masking logs is not the same as controlling who reads events. Which consumers may read which event, and with what masking, belongs to Insurance factory, part 3: trust.
What this is not. This page owns the intake contract the factory builds. The underwriting workflow that runs after intake, and the full treatment of building versus operating, is Insurance factory, part 2. Real identity (signed tokens from an identity provider) is Auth Engineering; the demo tokens here prove nothing about identity. Schema evolution and contract tests in depth are Data and integration engineering and Schema Engineering.
In a coding agent. If a coding agent such as Claude Code or Codex were the station worker that wrote a new route handler for this service, the same 50 tests and the contract gate, not the agent's report, would decide whether its change advances. It would receive one work item and a scoped checkout of the product repository, never the pattern's skeleton. The controls around that run are Harness Engineering.
Try it#
The lab opens on the intake station of the insurance line in the build view: what the factory builds and tests for intake. Switch stations to follow SUB-1004 downstream, and switch to the run view to see what happened in run-7f3a. The decision is always the underwriter's.
docs/LABS.md has no plain table for this lab yet, so this one was written for this page from the lab's generated data (examples/labcore/b_insurance.py, which reads Example C's real files and runs). Same information for a reader without JavaScript:
| Intake station | Build view (what FR-0003 builds and tests) | Run view (SUB-1004, run-7f3a) |
|---|---|---|
| Routes | POST /submissions (broker); GET /submissions/{submission_id} (auditor, broker, underwriter) | step 1: broker submits, 201, state validated |
| Access | no token: 401 on every route; auditor on create: 403; broker on read: allowed (own submissions) | step 3: no token, 401; step 5: other broker, 404 |
| Events | submission.received.v1, submission.validated.v1 | evt-0001 and evt-0002, same trace id |
| Transition | received to validated | received, validated |
| Tests | 11 named intake tests, all passing in the lab's recorded run | 50 of 50 passing |
No model takes part. The underwriting agent in Example C is a scripted stand-in, so these results show how the factory mechanics work, not how good any model is.
WatchAlgo in practice#
WatchAlgo has no brokers and no intake route, but its repository shows the cost of the thing this page builds: a strict check at the point where data enters.
Observed in the repository (zenalgo-frontend, HEAD 1b183564; docs/EVIDENCE.md row 4, corrected 2026-11-20 by the chapter 7 to 9 writer): 2,772 of 2,773 solutions store their code as a map of three languages; wa-001609 stores code as one string instead. Observed (EVIDENCE.md metrics inventory): the solution validator validate_payload reads only data["solution"], so wa-002025 passes it even though its duplicated top-level sections differ from the nested ones.
Both are what this page's validate refuses by construction: a field with the wrong type (must be a map, not a string), and data the contract does not declare (unknown field). WatchAlgo's validators ran inside a solo author's pipeline, where a wrong shape costs a broken page that someone notices. At an insurer's front door the same gap costs a submission an underwriter cannot read. Reported by the author: 3,246 problems were produced by a repeatable process; The WatchAlgo story separates that report from what the files show.
Enterprise translation#
In a real insurer the intake contract is the most negotiated artifact in the project. The series scenario has 63 submission fields; Example C carries about ten. Agreeing the other fifty with the brokers' systems, deciding which are required, and versioning the contract so that a portal written last year keeps working is the critical path, not generating the endpoint. Next to it sit the security review of the identity integration (signed tokens instead of demo strings) and the data classification of every field that carries personal data.
What the factory changes is the cost of the second, fifth and tenth intake service. Each gets the same skeleton steps, the same refusal shapes, the same audit fields and the same 50-test baseline, so the reviewers of the tenth service read only its spec and its rule module. The factory does not shorten the negotiation over fields, and a plan that assumes it does will be late.
Failure test#
The failure: the broker's portal sends SUB-1004, the service stores it and answers 201 with run_id run-7f3a, and the reply is lost on the network. The portal does what it was built to do and retries. Request 5 in the output above is that retry: 409 duplicate_submission, no run_id, no trace id. The submission is safe, it was stored once, but the portal cannot learn which runtime run it belongs to, and the generated contract does not list 409 for this route, so the portal's developers had no warning it could happen.
How the factory catches it: in Example C as it stands, it does not. The spec sets idempotency: false on the intake route, so the skeleton's idempotency step is skipped there. The contract gate checks that every documented status is right; it does not check that every status the handler can return is documented. No test retries a create. This is a spec decision with a consequence, not a bug in the pattern. The fixes are equally spec-level: mark the route idempotent so a retry with the same key replays the original 201, or have the duplicate path return the existing run_id to the submission's own broker; either way, add 409 to the contract and a retry test to the suite.
The first fix was tried on a copy of the spec for this page (script ch20_idem.py, scratch folder): create_submission set to "idempotency": true, the contract regenerated, the contract gate run, and the same body sent twice with one key. Real output:
responses: ['201', '400', '401', '403', '409', '422'] parameters: [{"in": "header", "name": "Idempotency-Key", "required": true}]
contract gate problems: []
first: 201 run-7f3a | retry same key: 201 run-7f3a true
The contract now declares the header and the 400 and 409 responses, the gate still passes, and the retry gets the original 201 with run-7f3a and an idempotent-replay: true header. The cost is on the portal: it must send a key on every submission.
What to run or toggle: copy Example C to a scratch folder, run /opt/homebrew/bin/python3 run.py and read row 1; then send the same UW-004 body twice through Service.handle and compare the two responses. Then set "idempotency": true on create_submission in the copy's product_spec.json and repeat with an Idempotency-Key header.
Where to go deeper#
- Insurance factory, part 2: orchestration (next): the underwriting-review workflow after intake, and building versus operating.
- Insurance factory, part 3: trust: least privilege, audit, traces and masking installed as stations and gates.
- Data and integration engineering: the v1 to v2 migration test and contract tests in depth.
- Pattern versus configuration versus business logic: why the skeleton is shared and the spec is not.
- Schema Engineering: typed contracts, validation and repair.
- Auth Engineering: real identity instead of demo tokens.
Checklist for Monday#
- Make every intake refusal name its fields: collect all validation errors, sorted, in one response.
- Reject unknown fields and wrong types, including booleans where integers are expected.
- Write one audit record per request, refusals included, with principal, route, status, outcome and correlation id.
- Decide for every write route how a retry is recognized (idempotency key or natural key), and document every status the handler can return.
- Keep each invalid-input case as a fixture, and assert that a refusal stored nothing and emitted nothing.
- Call a contract by its real name: "OpenAPI-shaped" until it validates against the OpenAPI specification.
Exercises#
- Why does the other broker get 404 for
SUB-1004and not 403?
Answer 1Do not confirm existence
A 403 would tell the second broker that SUB-1004 exists and belongs to someone else. The skeleton treats another broker's submission as not existing for that caller (test_other_broker_sees_404_not_403).
- The spec adds a required field
occupancy_codeto version 3 with no default. What happens?
Answer 2The compatibility gate refuses it
Old v2 records could not be read under v3, so compat_problems reports "new required field without a default" and the schema-compat gate fails. Give the field a default or make it optional.
- A refused request has no trace id. How does an investigator connect it to the portal's logs?
Answer 3The correlation id
Every audit record and response carries x-correlation-id, the caller's own id when it sends one. A portal that sets it on every request can match any refusal to its own log line.
Advanced perspective#
OpenAPI-shaped, JSON-Schema-like, and what real validators addNaming the contract honestly, and what changes if you adopt the standards
Standard (OpenAPI Specification 3.2.1, read 2026-11-20): required top-level fields are openapi and info, and at least one of components, paths or webhooks; the Schema Object is by default "a superset of the JSON Schema Specification Draft 2020-12". Standard (JSON Schema 2020-12, read 2026-11-20): the specification is split into Core and Validation; validation keywords include type, enum, minimum, maximum, pattern and required, and format is an annotation by default unless the format-assertion vocabulary is used.
Example C's generated contract fails the first rule (no openapi field) and expresses fields in its own format ("min", "required": true per field) instead of JSON Schema keywords. Both are deliberate: the example uses the standard library only. Adopting the standards is a pattern change, not a product change. S2 would emit a real OpenAPI document with JSON Schema components, a new gate would validate it with an OpenAPI validator, and the skeleton could use a standard validator instead of schemas.py. One trap to plan for: translating the example's rules into another validator's keywords is itself a change, so the 422 fixtures must run against the new validator before the old one is removed; a field rule that loosens in translation shows up only as a fixture that stops failing.
Product (Pydantic, as documented on 2026-11-20): creating a model instance validates the input, one ValidationError reports all errors with their locations, and Pydantic generates JSON Schema compliant with Draft 2020-12 and OpenAPI 3.1.0. Its default lax mode converts input where it can, for example '123' to 123 for an integer field; strict mode does not coerce. For an intake contract that must refuse "sprinklered": "yes", strictness is a decision to make explicitly, per model or per field, not a default to inherit.
Upgrade on read, never rewriteHow v1 submissions live beside v2
SUB-1004 arrived under schema version 1 and was stored under version 2 with roof_material: "unknown" (schemas.py : upgrade). The event submission.received.v1 keeps the body exactly as received, with submission_schema_version: 1; when anything reads it later, events.py : read_submission upgrades it on read and never rewrites the stored event. test_old_v1_event_is_read_under_v2_with_the_default proves the default; test_v2_body_keeps_its_value_and_v1_rejects_the_new_field proves the other direction: a v1 client cannot send the new field.
The compatibility rule that makes this safe is enforced by a gate, not by care: compat_problems refuses a new version that removes a field, changes a type, takes away nullable, narrows an enum, or adds a required field without a default, and test_breaking_v3_is_rejected_by_the_gate names four such problems. The general lesson for intake contracts: the stored record and the event log are read for years, so every version must be readable by the newest code. Data and integration engineering is the home of schema evolution.
Why the skeleton checks in this orderAuthenticate before validating; validate before the idempotency key
The order of the skeleton steps is a security and correctness decision, fixed in the pattern so no product can change it. Authentication comes before schema validation so that an anonymous caller learns nothing about the contract: the 401 carries no field list. The role check comes before the resource lookup's ownership test, and the ownership test answers 404, so a caller without rights cannot probe which submission ids exist. Schema validation comes before the idempotency step, so an invalid body never occupies an idempotency slot that a corrected retry would then collide with. And a 5xx response is not stored under its idempotency key (Service._pipeline, right after step 6), so a retry after a provider outage is allowed to try again (test_503_is_not_cached_so_the_same_key_may_retry).
Each of those orderings has a counterexample in hand-written services: validators that run before authentication and leak field names, ownership checks that return 403 and confirm existence, idempotency stores that remember a failed request forever. Putting the order in the pattern means the fifth intake service cannot reintroduce a mistake the first one already paid for.
What operating the intake endpoint needs that this page does not buildRate limits, payload limits, real identity, retention
Example C runs in-process with no sockets, so several production concerns are absent by design, and a factory pattern for a real intake service must add them as skeleton steps or platform gates: a payload size limit before parsing; rate limits per broker identity; signed tokens validated against an identity provider; retention and deletion rules for stored submissions and for events that carry personal data; and an alert on the share of 422 responses per broker, which is often the first sign that a portal's mapping drifted after a contract release.
None of these changes the factory's shape. They are more invariant steps in the skeleton, more constraints in pattern.json, and more gates in CI. What they do change is the review: each one needs an owner who decides the threshold, and those thresholds belong in the product spec or the platform's configuration, never in a default nobody chose. Insurance factory, part 3: trust and CI/CD and deployment take them up.
In one breath#
The factory built the broker intake endpoint by checking SPEC-INTAKE-001 against PAT-INTAKE-API 2.1.0, generating its contracts and configuration in FR-0003, and starting the pattern's skeleton from them. Sent real requests, it refuses each kind of bad input with its own status and a precise body (six field errors for six mistakes), stores nothing on refusal, upgrades a v1 submission to v2 on the way in, and leaves one audit record per request; 50 tests prove those claims. Its contract is OpenAPI-shaped rather than OpenAPI, and a lost 201 followed by a retry exposes a gap the gates do not see: a 409 with no run id, missing from the contract.
SUB-1004 is now stored, validated and waiting in state validated, with run-7f3a and its trace id assigned. Nothing has assessed it, recommended anything, or decided anything yet. Insurance factory, part 2: orchestration builds the workflow that takes it from there, and keeps the line between what the factory builds and what the running service does.