feat(schema-drift): envelope validation for openai/groq/cerebras (#39 slice 2)

[stackbilt-admin]

Summary

Follow-up to PR #40 (Anthropic slice 1 of #39). Wires response envelope schema validation into the three OpenAI-compatible providers so silent upstream contract drift routes through the existing SchemaDriftError → fallback → onSchemaDrift machinery instead of corrupting downstream parsers.

• openai — OPENAI_RESPONSE_SCHEMA validates id / model / choices[].message.{content,tool_calls} / usage.*
• groq — same envelope (OpenAI-compat)
• cerebras — same envelope (OpenAI-compat)
• Cloudflare is deferred — Workers AI returns heterogeneous shapes across model families (response / choices / output / result wrappers, all optional). Needs model-family-aware schema selection rather than a copy-paste template. Will file as its own PR.

Design decisions

Per-provider schema constants, not a shared import. Each provider's envelope is an independent API surface. If OpenAI ships a breaking change and Groq doesn't, we want both drift signals distinct, not hidden behind a single `OPENAI_COMPATIBLE_SCHEMA`.

Discriminated-union for `tool_calls`, even with one variant today. Matches the Anthropic template and gives forward-compat if/when OpenAI adds a new tool type (e.g. `code_interpreter`) — additive upstream change doesn't trip drift.

`No choices returned from X` → `SchemaDriftError('x', 'choices[0]', 'object', 'undefined')`. Empty choices was previously an uncaught generic `Error` that bypassed the fallback chain. Now it's drift-eligible like every other envelope failure, per PR #40 conventions.

Behavioral upgrade (called out explicitly)

One test from PR #23 was updated, not broken:

• Before: OpenAI returning `tool_calls[].function.arguments: 42` (a number) was silently dropped by `validateToolCalls`.
• After: It's routed as `SchemaDriftError` at path `choices[0].message.tool_calls[0].function.arguments`.

Rationale: OpenAI's contract is "stringified JSON". A non-string is an envelope violation, not a within-envelope semantic issue. Division of responsibility:

• Envelope shape violations → schema drift → fallback (observable)
• Within-envelope semantic issues (empty id/name, missing function object, etc.) → `validateToolCalls` → silent drop (unchanged)

Three existing PR #23 tests still assert silent drop (empty id, empty name, non-`function` type) because those are within-envelope semantic issues — schema validation accepts the shape, `validateToolCalls` filters the contents.

Test coverage

• Driven via `describe.each` over `[openai, groq, cerebras]` so schema-parity is enforced by construction — one provider's schema diverging breaks its tests loudly.
• 6 tests per provider × 3 providers = 18 new tests:
  • well-formed response passes through
  • `usage.prompt_tokens` rename → drift
  • `choices` removed → drift
  • `choices: []` → drift at `choices[0]` path
  • non-string `tool_calls[].function.arguments` → drift
  • unknown `tool_calls[].type` variant → forward-compat accept (no drift)
• 229 → 247 tests passing on Node 18/20/22 (expected via CI).

Test plan

• CI green on Node 18, 20, 22
• Existing Response envelope schema validation + schema drift canary #39 factory-fallback + onSchemaDrift-hook tests still pass (unchanged; slice 2 only adds new drift sites)
• Downstream consumers that touch OpenAI/Groq/Cerebras paths continue to work (no public API change; schema validation is transparent when envelopes are well-formed)

Follow-ups (tracked in #39)

• Cloudflare Workers AI — model-family-aware schema selection
• Schema drift canary module + golden fixtures
• Streaming-path drift (Validate streaming response path against schema drift #41) is separate concern

🤖 Generated with Claude Code

[stackbilt-admin]

Reviewer finding addressed in 5f084f0.

Root cause of the bug: schema discriminator says "unknown variant → skip (forward-compat)," but groq/cerebras `formatResponse` said "every tool_call has a `function` field." Two inconsistent forward-compat stances in the same code path.

Fix: filter `tool_calls` to `type === 'function'` before the map. Matches the schema's skip behavior explicitly at the map boundary. openai was already safe — passes `tc.function` through untouched, validateToolCalls drops null-function entries — so no change there.

Test upgrade: original test mocked a function-shaped payload and only asserted `res.content`, which hid both failure modes. New test:

• Omits `function` entirely (exercises the TypeError-through-`.map()` path)
• Asserts `res.toolCalls === undefined` (exercises the mis-surfaced-as-function-call path)

Two real bugs, one surfacing test. Thanks for the careful read.

All 247 tests still passing.