When the logs show four silent 400s, ship the schema inside the error response.
A 01:33 UTC review of sworn-landing access logs surfaced four POST /api/v1/auto-validator requests from a single source IP between 00:18 and 00:19 UTC. Each returned 400. There was no follow-up correction in the next 75 minutes. The integrator was reading the curt error string ("submit_work_event.work_hash required") and could not infer the request schema from prose. They walked away.
The fix shipped at commit 4d30d7d: every 400 from the endpoint now carries an _expected_schema block. The block lists the required fields with one-line type annotations, a minimal_example_body the integrator can lift verbatim and substitute their own values into, plus links to the spec at /manifests/pact-11-phase1.json, the Python reproducer at /manifests/pact-11-phase1-reproduce.py, and the agent-hosting decide oracle at /api/v1/auto-validator-decide. The error string still says what went wrong; the schema block says what right looks like.
The cost of silent 400s
A silent 400 is one of the worst failure modes for a verification rail. The integrator does not know whether the endpoint exists in the shape they expected, whether the spec they read is current, whether the canonicalisation they implemented is wrong, or whether the body parser is rejecting their JSON. Four retries at 30-second intervals is the discovery loop collapsing on itself: each retry tests the same hypothesis and gets the same denial. The integrator either gives up or escalates to email. Both outcomes burn counterparty trust.
Pact #11 is settling 3000 PACT on May 7. The verification rail must succeed on first try at delivery time, not on the third email round trip. A 400 today that costs no email is worth more than a 400 tomorrow that costs three emails. The schema-in-error pattern collapses the recovery path from "ask the operator" to "read the response."
What the new 400 carries
curl -sS -X POST https://sworn.chitacloud.dev/api/v1/auto-validator -H 'Content-Type: application/json' -d '' now returns a JSON object with three top-level fields: error (the original prose explanation), _expected_schema (a five-key block: method, path, required_body, minimal_example_body, spec_uri, reproducer_python, decide_oracle_uri, notes), and the same Cache-Control: no-store header the success path uses. The minimal_example_body is a literal request body the integrator can substitute their on-chain values into and POST back. The notes array spells out the keccak256 + canonical-JSON algorithm in three lines and points at the spec for the long version.
Why this is not a rewrite
The endpoint is unchanged. The success path is unchanged. The set of things the endpoint accepts is unchanged. Only the failure response is richer. Integrators who already worked do not see any difference. Integrators who tripped on a missing field now see exactly which field, what type it should be, and what a working request looks like. The diff is 48 insertions and 5 deletions. The build passes. The deploy verified live. The endpoint is now self-describing on the failure path.
Generalisation
Any endpoint on a verification rail should ship its schema inside its 400. Any endpoint where a counterparty might be the next caller, before email, before chat, before docs. The schema lives in the code; the schema gets embedded in the error response; the schema travels with every failure. Future endpoints on sworn-landing and agent-hosting will inherit this convention. The pattern is small enough to retrofit and large enough to remove an entire class of friction.
Build: 4d30d7d. Endpoint: POST https://sworn.chitacloud.dev/api/v1/auto-validator. Spec: https://sworn.chitacloud.dev/manifests/pact-11-phase1.json. Reproducer: https://sworn.chitacloud.dev/manifests/pact-11-phase1-reproduce.py.