Contract drift audit 2026-09-21

[claude]

Summary

Audited the 4 snapshots selected by the deterministic stage
(drift-report/contract-drift-report.json, budget 4, all never_live_verified: true):
openai-compat, openai, openrouter, azure-foundry. Per contracts/DRIFT-CHECK.md.

Summary table

Provider	OK	DRIFT	DEPRECATION	NEW-CAPABILITY	UNVERIFIABLE
openai-compat	4	0	0	4	0
openai	5	1	0	6	2
openrouter	2	1	0	4	2
azure-foundry	6	1	0	3	0

Findings (most severe first)

openai: platform.openai.com/docs/changelog moved [DRIFT]

• Snapshot says: cites https://platform.openai.com/docs/changelog as a source.
• Live docs say: that URL now 301-redirects permanently to https://developers.openai.com/api/docs/changelog (fetched 2026-09-21, content unchanged in substance).
• Impact: none on the wire contract itself; the citation was stale.
• Proposed action: updated Upstream sources to record the redirect and the new URL. Applied.

azure-foundry: /reference upstream source no longer documents chat/embeddings [DRIFT]

• Snapshot says: cites learn.microsoft.com/en-us/azure/ai-foundry/openai/reference as the source for the chat-completions wire contract.
• Live docs say: that page (fetched 2026-09-21) now covers only image-generation and audio (transcription/translation) REST operations, and explicitly tells readers to go to https://learn.microsoft.com/en-us/rest/api/microsoft-foundry/azureopenai/chat for chat completions, embeddings, and "all other operations."
• Impact: the snapshot's chat-completions assertions (max_completion_tokens, reasoning_effort, etc.) were not actually checkable against the cited page anymore — they still happen to be correct, reconfirmed against the real page.
• Proposed action: added the actual chat reference URL as a source and re-verified against it directly. Applied.

openrouter: list-available-models source URL is dead [DRIFT]

• Snapshot says: cites https://openrouter.ai/docs/api-reference/list-available-models.
• Live docs say: 404 (confirmed both by the deterministic tripwire's source_checks and a live fetch 2026-09-21). Corrected URL: https://openrouter.ai/docs/api/api-reference/models/list-all-models-and-their-properties — the response shape (context_length, pricing.{prompt,completion}, supported_parameters) is unchanged at the new location.
• Impact: link rot only; no schema drift found.
• Proposed action: corrected the URL. Applied.

openai: prompt-caching "VERIFY on next drift run" item — resolved

• Snapshot said: cached tokens' inclusion in prompt_tokens/input_tokens and the caching threshold were both explicitly unverified.
• Live docs say (developers.openai.com/api/docs/guides/prompt-caching, fetched 2026-09-21): cached tokens are confirmed still included in usage.input_tokens, broken out at usage.input_tokens_details.cached_tokens. Threshold is 1,024 visible input tokens for GPT-5.6+; earlier models vary by request shape (documented as such, not a gap in our check).
• Impact: resolves a two-sprint-old open question; also surfaces a new cache_write_tokens field (Prompt Cache Diagnostics GA'd 2026-09-08) that isn't read by the adapter.
• Proposed action: contract updated with citation. cache_write_tokens / diagnostics-endpoint support is a proposed adapter work item, not applied.

NEW-CAPABILITY findings (not urgent; feed the capability catalog / roadmap)

• openai-compat / azure-foundry: stream_options.include_obfuscation, prompt_cache_key/prompt_cache_retention, and response usage.{prompt,completion}_tokens_details.* breakdowns exist on the wire and aren't read. Azure additionally exposes parallel_tool_calls, safety_identifier, store, modalities, prediction, and message-level annotations[].url_citation.
• openai-compat / openai: error bodies now carry typed code values (slow_down for 429, server_is_overloaded for 503) — both already fall inside the existing retryable-status set, so no break, just finer-grained typing available if wanted.
• openai: Responses API gained async tool calling, mid-turn steering, mid-conversation reasoning.effort changes, and expanded server-side tools (file_search, computer_use, image_generation, custom tools) beyond the web_search/code_interpreter pair already documented. GET /v1/models responses now include a shutdown_date field per model.
• openrouter: /models gained filter/sort query params (min/max_intelligence_index, agentic_index, coding_index, tool_success_rate, output_price, age_days); attribution headers gained X-OpenRouter-Categories (and X-OpenRouter-Title is now the canonical name, with X-Title as an accepted alias); OpenRouter also GA'd a Responses-API-shaped endpoint (out of scope — this adapter only implements Chat Completions).
• azure-foundry: confirmed the version-less /openai/v1 surface is now GA (resolves a standing Watchlist item), that both *.openai.azure.com and *.services.ai.azure.com base URL forms are valid, and that reasoning_effort now accepts xhigh.

Unverifiable

• openai: the Responses API's full typed streaming-event catalog — the fetch this run confirmed response.output_text.delta/response.completed still exist but didn't enumerate the rest. Needs a more targeted fetch next run.
• openai: platform.openai.com/docs/api-reference/{responses,models,chat} remain bot-walled (403) — verified instead via the developers.openai.com mirrors, the same substitution the embeddings section already used.
• openrouter: the : OPENROUTER PROCESSING SSE keep-alive comment framing and the 402 insufficient-credits error shape weren't re-fetched this run; not contradicted, just not re-confirmed.

Left unapplied (adapter/code follow-up, out of scope for this workflow)

• Reading usage.{prompt,completion}_tokens_details.* / cache_write_tokens for cache-aware pricing on the openai-compat, openai, and azure-foundry adapters.
• Wiring prompt_cache_key for cache-affinity hints.
• Declaring stream_options.include_obfuscation in ignored_parameters instead of silently dropping it.
• Any of the newly-listed server-side Responses tools (file_search, computer_use, image_generation, custom tools).
• GET /v1/models shutdown_date surfaced through model discovery.
• OpenRouter /models filter params and the X-OpenRouter-Categories header.

Proposed contract edits

All applied directly in this PR, each with an inline citation and date. See the diff.

🤖 Generated with Claude Code