All chapters
  1. Start hereA software factory, from first principles
  2. Primitive · 1A factory, before AI: input, transformation, check, output
  3. Primitive · 2From repetition to a pattern: what stays, what varies, what to leave alone
  4. Primitive · 3The specification as an executable contract
  5. Primitive · 4Build the smallest factory: four stations, two specs, one manifest
  6. Primitive · 5Assembly stations: typed contracts, owners and failure handling
  7. Primitive · 6AI enters the factory: what a model adds, and what stays deterministic
  8. WatchAlgo · 7The WatchAlgo production story: what the repository shows
  9. WatchAlgo · 8A problem as a production unit: the files one unit must contain
  10. WatchAlgo · 9Station by station: description, solution, implementations, visualization
  11. WatchAlgo · 10The visualizer factory: from algorithm state to renderable steps
  12. WatchAlgo · 11Three flavors and three languages: two different contracts
  13. WatchAlgo · 12Looping over a large backlog: scheduling, limits and a failed-case queue
  14. WatchAlgo · 13Long-running agent execution: context, checkpoints and token limits
  15. WatchAlgo · 14Evidence of correctness: tests the producer cannot talk its way past
  16. WatchAlgo · 15The factory learning loop: defects change the pattern, not only the unit
  17. Enterprise · 16Classify the enterprise demand before choosing a pattern
  18. Enterprise · 17Reference enterprise patterns and their variation points
  19. Enterprise · 18Platform foundations: golden paths, templates, registries and catalogs
  20. Enterprise · 19Pattern versus configuration versus business logic
  21. Enterprise · 20Insurance factory, part 1: building the intake contract
  22. Enterprise · 21Insurance factory, part 2: building the underwriting workflow
  23. Enterprise · 22Insurance factory, part 3: trust and observability built in
  24. Enterprise · 23Data and integration engineering: contracts that survive change
  25. Enterprise · 24The CI/CD and deployment factory: from pull request to production
  26. Enterprise · 25Enterprise governance: owners, approved patterns and provenance
  27. Enterprise · 26Scaling safely: many teams, many agents, one set of boundaries
  28. Operations · 27Factory quality engineering: measuring accepted output, not activity
  29. Operations · 28Failure and recovery scenarios: what breaks a factory, and what restores it
  30. Operations · 29The landscape: which tool for which job, read from its own documentation
  31. Operations · 30Design an enterprise software factory: the blueprint and the rollout
  32. ReferenceSources and verification
  33. ReferenceGlossary
  34. AboutAbout this site
Enterprise · 20

Insurance factory, part 1: building the intake contract

The factory generates a broker submission endpoint and its validation from a synthetic product specification: schemas, errors, fixtures, audit fields, and the tests that prove each.

You will run
Factory run FR-0003 that assembles the broker intake endpoint, then real requests against it: 201, 401, 403, 409 and 422.
You will read
A 422 response that names six fields and what is wrong with each, and the audit record every refusal leaves.
You will find
One gap the gates miss: a broker's retry after a lost reply gets 409 and no run id, and the contract does not list it.

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 in jakarta.validation.constraints include @NotNull, @Min, @Max, @Pattern and @Email, and @Valid cascades 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.

FieldType and ruleExample (SUB-1004, case UW-004)
submission_idstring, pattern ^SUB-[0-9]{4}$SUB-1004
broker_emailstring, ends in .example, marked PIIbroker@brokerage.example
occupancymanufacturing, office, retail, warehouseoffice
constructionframe, masonry, steelmasonry
year_builtinteger 1850 to 20262001
area_sq_ft, building_value_usdinteger, at least 120000, 2400000
sprinkleredbooleantrue
roof_age_yearsinteger 0 to 150, may be null9
wind_zoneA, B, CC
prior_losses_5yinteger, at least 00
roof_material (v2 only)optional, default unknown, five valuesabsent 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.

  1. Skeleton steps (fixed order)
    1. parse the request: Method and path must be strings; the route is matched from the spec's routes.
    2. authenticate: A known demo bearer token or nothing; demo tokens prove nothing about identity.
    3. role check: The caller's role must be in the route's roles.
    4. schema validation: Every field checked; all errors collected and sorted.
    5. intake handler: Stores the submission once, emits two events, moves it to validated.
  2. Exits (each writes an audit record)
    1. 400 or 404: The request cannot be matched to a route.
    2. 401 + Bearer challenge: No token or an unknown token; no field list is revealed.
    3. 403 + required roles: Known caller, wrong role.
    4. 422 + field errors: Every broken field, by name and rule; nothing stored, no event.
    5. 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:

WhereFieldExample from SUB-1004Why it is there
audit recordseq, at1, 2026-11-20T09:00:03.000Z in run.py's audit (injected clock)order and time of the request
audit recordprincipal, rolesu-broker-n1, brokerwho acted, and in which role
audit recordroute, status, outcomecreate_submission, 201, okwhat was asked and what happened
audit record and eventtrace_id0c17c0046d4371b42858072814d7b4caone trace per runtime run
audit record and eventcorrelation_idcorr-broker-portal-01the caller's own id, echoed back
audit record and eventrun_id, submission_idrun-7f3a, SUB-1004which workflow execution, which submission
eventevent_type, event_schema_versionsubmission.received.v1, 1what 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 event submission.received.v1 carries the submission as received, email included, because its schema requires the submission field. 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 stationBuild view (what FR-0003 builds and tests)Run view (SUB-1004, run-7f3a)
RoutesPOST /submissions (broker); GET /submissions/{submission_id} (auditor, broker, underwriter)step 1: broker submits, 201, state validated
Accessno 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
Eventssubmission.received.v1, submission.validated.v1evt-0001 and evt-0002, same trace id
Transitionreceived to validatedreceived, validated
Tests11 named intake tests, all passing in the lab's recorded run50 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#

Checklist for Monday#

Exercises#

  1. Why does the other broker get 404 for SUB-1004 and 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).

  1. The spec adds a required field occupancy_code to 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.

  1. 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.