The sneaky part of a schema failure is where it lands. A parse failure fails at the parse call [4]. A wrong shape clears that gate, and a well-formed object travels on until something downstream reads a field that was never there, far from where the problem was born [6]. This pipeline caught it early only because Zod sat at the boundary and rejected the object JSON.parse had already accepted [3].
The commit that closed the incident did two things, and they are not redundant. Putting the literal schema in the prompt lowers the rate at which the model deviates [7]. Wrapping a bare top-level array in the expected envelope handles the deviation already observed, in code, every time [7]. Jula Markova, who writes at dev.to that she is an IT analyst rather than a software engineer by training [15], puts it as reducing the error rate with the prompt and making the residual error harmless with the fallback [8]. The prompt lowers how often the model deviates; the fallback routes any deviation that still happens into a branch someone wrote.
What turns that from a patch into a design rule is the runner interface. Every AI call goes through one interface, with three interchangeable backends behind it and a flag to swap them: the Claude CLI on a subscription, the Claude Agent SDK on an API key, and codex, GPT-5.5, through a ChatGPT subscription [10][11]. Only the SDK converts the Zod schema to JSON Schema and sends it as an output format, so the response cannot arrive in the wrong shape [12]. The CLI carries the schema in the prompt and returns free text, which the code then cuts the JSON out of and validates after the fact [13]. Two of the three can therefore only ask the model for the right shape rather than enforce it [1], and the shared prompt has to be correct on the weakest of them, so enforcement can sit on top of the extract-and-validate path but cannot delete it.
codex is the more interesting refusal. It has an output-schema mode, but according to Markova that mode rejects schemas containing references, and an ordinary Zod schema converted to JSON Schema produces exactly those; strict-mode constraints rule out the rest of her real schemas [14]. codex's output-schema mode exists in the product, but this pipeline cannot reach it.
Before borrowing the SDK's guarantee, test your schema graph, not a benchmark. For "cannot arrive in the wrong shape" to transfer, your schemas have to survive conversion into the subset the provider accepts [12], and you keep validating anyway, because the guarantee is about shape and the taxonomy that produced it stops at shape [4][12].
The house rule that came out of the incident is written twice, word for word, once in global rules and once in project rules [9]. Markova calls the duplication deliberate emphasis [9]. It is the version-controlled equivalent of writing it on the back of your hand.
The portable contract on this evidence is narrow: schema in the prompt, extract, validate at the boundary, one deterministic repair per known deviation. Treating API-layer enforcement as the design assumption is how the other two backends fail without saying so [13][14].
