2026-07-19 Phase 8 Three-Provider Contract and Streaming State-Machine Record

This phase turns the Provider-contract gap identified in Phase 7 into a fully offline, auditable course project. The primary Agent unified version boundaries, terminology, continuation semantics, documentation counts, and final verification for three APIs. Specialists performed document-consistency, code-red-team, and official-fact checks. Every high-risk finding was first reproduced, then fixed with a regression; no P0/P1 is currently known.

Evidence boundary

docs/LLM API integration/examples/provider_contracts/ reads no keys, imports no Provider SDK, and accesses no network. Under the official API Reference/SDK-type baseline on a fixed date, it proves contracts for local projection parser, identity association, terminal gate, resource limits, and continuation builder. OpenAI/Gemini fixture is typed-sse-projection, Anthropic is wire-sse-envelope-projection; neither is raw SSE bytes, an SDK instance, live conformance, server exactly-once, or model-quality evaluation.

1. Current baseline and version boundary

• OpenAI Responses with openai-python 2.46.0 (2026-07-17): ordinary HTTP previous_response_id continuation is recorded separately from WebSocket current-connection cache.
• Anthropic Messages with anthropic-python 0.117.0 (2026-07-16): top-level system remains broadly compatible default; mid-conversation system is allowed only for checked model/placement constraints. Invalid JSON in eager/fine-grained tool input enters recovery.
• Gemini Interactions stable v1 with google-genai 2.12.1 (2026-07-16): its Step discriminator is fixed to 15 types from official Reference. An MCP-server step in current v1beta OpenAPI is not part of the stable contract and fails closed in local parser.
• Gemini status_update is optional intermediate notification; terminal Interaction status is authoritative. last_event_id supports recovery only for still-retrievable stored-Interaction GET stream.
• Every fixture binds Provider, API family/version, contract revision, SDK baseline, checked date, and HTTPS source URL. Example IDs/model values are synthetic opaque values.

2. Implementation and teaching structure

The Three-Provider Contract Tests project adds three versioned fixtures, provider_contracts.py, and test_provider_contracts.py. It retains Provider differences rather than building an event-renaming table:

• OpenAI: correlates by sequence_number + output_index + item_id; preserves complete Item lifecycle, non-function terminal binding, direct caller retention, and HTTP storage proof. Stateless replay uses caller-validated input Items plus complete raw output Items.
• Anthropic: retains named SSE envelope; thinking/redacted thinking; signatures; citations; and mixed server/client tools. calls exposes only executable client calls; illegal input or a truncated sibling call enters a separate recovery_calls. Continuation requires is_error.
• Gemini: deduplicates by event_id and correlates stream by Step index; separates optional status_update from terminal; keeps current usage fields unchanged; separates create/GET complete-steps input-history source; fails closed when opaque model/hosted steps are not provable.

All three turns retain a local canonical snapshot digest. Builders recheck digest before copying history/call/block, detecting post-parse nested-object mutation; it is not a signature or cross-process truth proof. Five builders require explicit re-send of caller controls and verify every observed function name appears in that Provider’s tool declaration.

3. Red-team closure

Finding	Repair and regression
Nonfunction OpenAI Items such as reasoning/message could be replaced in terminal	Preserve output_item.done by output index; terminal validates complete Item consistency; add tamper fixture.
Nested dict in frozen dataclasses could mutate after parse, misbinding call/result	Add Provider-specific snapshot digest and fail-closed builder entry; mutation regression for each Provider.
An Anthropic truncated turn might let naive caller execute a complete sibling tool call	Put all max_tokens calls in recovery_calls; only explicit stop_reason=tool_use with parseable input enters calls.
Deep tool JSON leaked bare RecursionError before json.loads	Add string-scan nesting guard; map parser/load-fixture recursion errors to stable contract error.
Malformed HTTPS source URL leaked urlsplit ValueError	Catch and return structured validation error.
Gemini v1 included a v1beta MCP Step in stable union	Stable v1 keeps 15 types; forward MCP type receives unknown-Step negative test.
Continuation could declare a same-shaped tool with no observed call name	All three builders check observed function name against declaration set.
Gemini prior history accepted nonfirst user_input, orphan/duplicate function result	Require initial user_input, paired function call/result, matching names, and complete results.
Result iterable could grow forever	_bind_results fails immediately after expected count.

4. Documentation and route synchronization

• LLM API directory moves from 20 reliable-client and 82 legacy Provider tests to 20 + 96, 116 offline tests total, explicitly distinguishing projection, SDK integration, live evaluation, and production audit evidence.
• Lesson 08 adds three Mermaid state machines; OpenAI HTTP/WebSocket storage difference; Anthropic system capability gate/recovery calls; Gemini v1/v1beta boundary/15 Steps/retention/GET-create history/usage/native tool and response-format shape.
• Anthropic introduction narrows absolute claims about system role and adds tool-terminal gate, schema/semantic/permission validation, stable is_error error result, fine-grained-input risk, and one-turn loop limit.
• Dates, Gemini Interactions references, missing-usage semantics, and projection boundary in lessons 04/06/07 are synchronized; the overall route links this phase record.

5. Verification actually performed

• Provider contract: 96 tests all passed under normal, -O, warnings-as-errors, and -O + warnings-as-errors.
• Python repository: Python 3.11.9 discovered 68 test_*.py; five files with declared CrewAI/LangGraph/Matplotlib/scikit-learn optional dependencies were left out. The remaining 63 base-environment files passed 2,483/2,483 in each of normal, -W error, -O, and -O -W error—9,932 test executions total. Missing dependencies were not recorded as passed.
• Provider two-file script checks: py_compile plus normal/-O warnings-as-errors regression; no network/key access.
• Site: .website npm test 35/35. Build staged 893 Markdown, emitted 2,432 HTML and 2,676 public files; brokenLocalLinks, forbiddenFiles, progressMetadataLeaks, sensitiveLeaks, selfRedirects, tableWikilinkLeaks, checkboxProgressRuntimeLeaks, interactiveCheckboxes, and katexErrors all 0. It reports 56 course indexes, 225 assets, 8 stage navigation, 56 course navigation, 106 folder navigation.
• Worktree: git diff —check passed; generated cache/bytecode was cleaned in final check.

Key sources

• OpenAI Responses function calling, Conversation state, Programmatic tool calling, and Responses streaming events.
• Anthropic Streaming Messages, Handle tool calls, Fine-grained tool streaming, and Mid-conversation system messages.
• Gemini Interactions overview, Interactions API v1 reference, Interactions streaming, Gemini function calling, and v1beta OpenAPI as a forward-drift control only.
• SDK snapshots: openai-python 2.46.0, anthropic-python 0.117.0, and google-genai 2.12.1.

Follow-up queue

1. Outside the vault, build a credential-gated, low-cost, no-side-effect live-contract suite for real SSE framing, SDK typed-object decoding, HTTP/WebSocket, timeout, 429, recovery cursor, and default retry.
2. Capture de-identified real wire/SDK fixtures with API version, SDK, model, date, and schema hash, and compare local projections by golden diff.
3. Connect Provider turn with request/execution ledger, approval, business idempotency key, and SQLite persistent idempotency/outbox recovery. Offline parser does not prove exactly-once.
4. Build separate capability/evidence layers for OpenAI built-in/programmatic tools, Anthropic server tools, Gemini hosted/opaque Steps, GenerateContent, and multimodal tool result rather than forcing them into stable-v1 function projection.
5. Manually inspect Mermaid, wide tables, Callouts, and mobile layouts in Obsidian/Quartz, then continue reviewing dynamic SDK/protocol pages elsewhere.

See the preceding Phase 7 record. Source, license, and original/curated/third-party labels continue through the Content Quality and Source Labeling Standard.