The vendor changed the shape for 5% of responses

The problem

A vendor ships a response-shape change — but not all at once. A canary at 5% of traffic, then 25, then 50. Or not a rollout at all: the shape varies by data, like a geocoder that returns null for formatted_address only on ambiguous queries.

Intermittent breakage is harder than total breakage. A change that breaks every call is found in minutes and rolled back. A change that breaks 5% looks like flakiness, sits in the backlog for a week, and gets fixed once someone spots the pattern.

Four change classes, and treating them alike is the mistake — addition is non-breaking by every published policy, removal and type change are breaking, and a field becoming nullable is warning-level and the most intermittent of all.

The dangerous one is the type change, because a naive cast produces a plausible value: a payment provider moves transaction_id from 12345 to "12345", your code casts to int, gets 0, and processes a $0 transaction.

The common solutions

What StitchAPI does

The default is safe, and that is the headline. Against z.number(), a transaction_id that arrives as "12345" produces error | invalid | transaction_id | Invalid input: expected number, received string and the call fails with data: null. Even z.coerce.number() on "abc" fails — Zod rejects NaN. StitchAPI does not manufacture a $0 charge on its own.

The precision is excellent. Over 100 calls where a geocoder returned null on 5 of them, drift fired on exactly calls [20, 40, 60, 80, 100] — matching the vendor's own ledger, zero false positives on the other 95, each finding naming formatted_address with null -> string.

And aggregation is a real seam, which is what makes an intermittent change actionable. A TraceSink sees every event of every call, and ctx.spanId lets you hold per-call state honestly:

const charges = stitch({
    url: 'https://api.vendor.com/charges/{id}',
    output: drift(StrictCharge, { level: { undeclared: 'verbose' } }),
    trace: new DriftRate({ window: '15m' }),
});

Measured: 5.0% of calls: warn|coerced|transaction_id|null -> number (5/100, 5 landed 0), and on a rolling window the same field widening 5.0% → 25.0% as the canary expanded. Across six workloads at 100 calls each: silent on a 100% addition rollout, one alert line per breaking class at 5%, and zero $0 charges. The same six workloads against the soft schema teams write for availability kept 100% of calls and produced ten $0 charges.

What StitchAPI does not solve here

1. A coerced finding cannot say whether the coercion was destructive. "12345" → 12345 and "abc" → 0 emit byte-identical findings — warn | coerced | transaction_id | string -> number — because detail is kindOf(old) -> kindOf(new) and values never appear in a finding. Only joining drift to result on ctx.spanId in a sink separates them.
2. The nullable class is inexpressible. "Nullable is a warning, value intact" — the fourth industry class — has no spelling. .nullable() produces nothing at all, so the 5% rollout is invisible; the strict schema turns it into a 5% error rate that also discards the four fields that were fine. A hand-rolled classifier beats DriftOptions on exactly this row.
3. level is keyed by mechanism, not by change class. It takes undeclared/coerced/defaulted — of which only addition maps 1:1 to an industry class. Removal, type change and nullability each land on a kind decided by your schema, so their loudness is a schema decision rather than a severity one.
4. No per-path severity. ignore is the only path-aware lever and it is on/off. "Coercion on transaction_id pages, coercion on description doesn't" has no spelling.
5. A soft finding cannot be promoted to fatal through the type. error isn't in the soft half of DriftLevel — Exclude<DriftLevel, 'error'> (a cast past it does work at runtime).
6. Soft findings are invisible on the awaited path. await and .safe() carry nothing — StitchError has no findings, and a hard failure gives only a generic contract violation (drift). The trace sink for the same run named the field and both types. drift() with only .safe() does nothing for you.
7. A schema strips what it doesn't declare. The added field in the addition case is undefined on data; reading it needs .inspect().raw, which is a fresh request.

StitchAPI vs the common solution

A wash on size — 93 lines against 92. But the halves are not alike: detection is 9 declarative lines against ~35, while aggregation is ~84 lines of user code either way, because the library counts nothing.

What the hand-rolled 92 lack is the resilience stack, measured here as one retry line absorbing 8 × 503 across the canary while the rate still counted 100 logical calls out of 108 wire requests.

See also