Summary

Implement the typed reasoning and provenance foundation for #335. Current progress: typed reasoning, fail-closed stored history, server-owned policy/provenance, upstream-reported model evidence, pinned candidate-profile compatibility preflight, the stateless opaque request/isolated transport adapter, stream-owned producer cancellation, pinned provider-reference replay coverage, assistant phase preservation, offline full-executor acceptance, canonical durable tool-round ordering, modeled request-surface preflight, and closed nested HTTP/WebSocket wire guards and matching core preflight are implemented. Opaque replay remains disabled; this draft does not close #335.

Review follow-up (2026-09-24): default plaintext provenance no longer fingerprints credentials; bounded legacy reasoning rows remain continuable without gaining opaque trust; lenient JSON/SSE treat malformed upstream model metadata as unknown evidence; the closed opaque profile rejects prompt_cache_key. The request guard shares the typed field list with core preflight. Full workspace tests, Clippy with -D warnings, formatting, and staged pre-commit hooks pass. Opaque qualification remains gated.

• Model reasoning text, summaries, status, and opaque state with typed Rust contracts. Preserve exact opaque bytes, redact debug output, and enforce decoded-byte and retained-response bounds. Preserve canonical reasoning while keeping the current vLLM plaintext projection and early rejection of opaque-only continuation.
• Reject invalid/missing history rows, malformed response metadata/references, and missing or foreign captured conversation responses. Preserve legacy SQL NULL behavior and keep stored values out of error diagnostics.
• Add typed server configuration responses.reasoning_replay_policy, defaulting to vllm_plaintext. Reserved opaque_responses fails before storage initialization, rehydration, tool discovery, inference, compaction, or external commit.
• Persist versioned, non-wire provenance per reasoning item. Durable history, transient sessions, forks, and ephemeral-to-durable promotion preserve origin; manual submissions and externally committed outputs cannot claim gateway-observed origin. Fixed-size fingerprints bind policy, configured endpoint, requested model, and optional reported model without retaining original strings. Only the closed opaque profile also binds the effective credential.
• Carry bounded, typed model metadata through the existing JSON/SSE ingestion path, separately from request-derived public ResponsePayload.model. Only explicit, consistent terminal metadata supplies evidence. Missing/null metadata, nonterminal JSON, lenient EOF completion, and ambiguous lenient streams remain unknown. Malformed model metadata becomes unknown evidence in lenient ingestion and a redacted upstream error in strict ingestion; strict ingestion also rejects changing model names. Model retention is charged once per round.
• Preserve recorded gateway compatibility: the existing reasoning stream reports gpt-5.6-sol early and echoes requested gpt-5.6 at completion. Lenient execution succeeds with unknown model evidence; strict decoding rejects the conflict. No alias or model-family equivalence is inferred.
• Add the closed candidate profile openai_gpt_5_4_2026_03_05_v1, pinning the exact OpenAI Responses endpoint and gpt-5.4-2026-03-05 requested/reported snapshot. Validate policy/profile consistency, exact routing, canonical provenance, credential compatibility, nonempty opaque state, and unsupported compaction before inference. Profile fingerprints bind a separate contract domain and cannot match legacy observational identities. Post-ingestion profile provenance requires exact terminal model evidence. Errors use static redacted messages and typed HTTP/SSE mappings. Even a compatible candidate remains unavailable: configuration and request execution still fail the qualification gate.
• Add a borrowed, typed upstream-only reasoning projection with explicit upstream store: false, preserving exact opaque state, summaries, IDs, optional status, and ordering while omitting plaintext content and internal provenance. Canonical item types and gateway storage policy stay unchanged; the initial plaintext sanitizer remains vLLM-only.
• Isolate candidate transport from caller-supplied HTTP-client defaults: direct HTTPS only, no redirects, environment proxies, automatic retries, or organization/project/cookie defaults; explicit per-request bearer auth, bounded connect/read timeouts, and bounded idle pooling. Discard non-2xx bodies/headers without reading them; redirects become 502 errors.
• Select the existing strict ingestion transitions for candidate JSON/SSE. The shared SSE framer rejects invalid UTF-8 and unfinished lines for this candidate, without changing default vLLM framing. Redact invalid-provider diagnostics while retaining typed causes and safe tool-search lifecycle errors. Every candidate round requires exact terminal model evidence, including rounds without reasoning. No availability gate was removed.
• Remove the nested spawned Responses producer and its abort-only drop guard. The consumer stream now owns and polls orchestration with the existing bounded event receiver; dropping it synchronously disposes local request/tool futures and continuation leases. Drain accepted events in order, emit a typed static panic error without forwarding panic payloads, and preserve persistence/checkpoint publication before completion. WebSocket request tasks still have explicit abort/join and session-idle fences. This closes the specific producer lifetime gap, not all of refactor: extract StreamRelay and bound client delivery #244 or remote side-effect cancellation.
• Add six recorder-generated pinned OpenAI reference cassettes covering 18 real requests: initial, continuation and independent branch for text and function outputs over JSON, SSE and WebSocket. All use exact gpt-5.4-2026-03-05, store: false, complete item replay, low reasoning effort and concise summaries. The provider accepts continuations using the exact output_item.done opaque bytes retained by gateway ingestion, which differ from the terminal envelope bytes. WebSocket references use a fresh connection per request, not gateway connection-local continuation.
• Preserve optional typed assistant MessagePhase::{Commentary, FinalAnswer} through completion, output-to-input conversion, storage and rehydration. Live captures exposed that this field was previously dropped. Reject phase on non-assistant input; absent/null legacy phase remains absent. OpenAI phase guidance informs the contract without introducing a second production ingestion path.
• Extend the existing recorder with explicit immutable stateless checkpoints, branch isolation, item/byte/turn limits, payload-log suppression, a selectable item-completion replay source, and bounded WebSocket capture. Preserve raw captures and honor WebSocket store: false.
• Replay the pinned JSON/SSE recordings through full ExecuteRequest execution, durable storage, transient forks/promotion, explicit conversations, and a deterministic local MCP tool loop. A bounded, per-context, core-unit-test-only loopback fixture skips availability without weakening profile, routing, credential, provenance, or terminal-model checks. An ordinary opaque transport cannot grant test availability. No runtime configuration or feature flag enables the candidate, and startup, external commit, and compaction gates remain closed. This is offline executor acceptance, not live gateway or actual HTTP/WebSocket handler qualification.
• Fix a durable opaque-history ordering defect exposed by the tool-loop tests: reasoning must precede its function call and output in later continuations, as it does during the live loop. Reuse canonical round recording and the existing output-to-input conversion, with typed, non-wire RecordedOutputPrefix bookkeeping owned by the turn rather than its session lease. Both persistence modes avoid duplicated public projections while retaining MCP discovery metadata. Default vLLM persistence behavior remains unchanged; no existing history is rewritten.
• Validate the pinned candidate's modeled request fields before history lookup or tool discovery, and again after effective settings are resolved before each round. The typed allowlist accepts the recorded low/concise reasoning flow, bounded output tokens, and function or local MCP normalization with explicit require_approval: never. It rejects unqualified reasoning/sampling/text settings, automatic truncation, vLLM-only fields, unsupported tool kinds and lossy function extensions with static parameter-specific 400 errors. Default vLLM behavior is unchanged; the availability gate remains closed. The HTTP/WebSocket profile guard rejects unknown and duplicate top-level keys and unknown reasoning keys. Closed nested schemas now cover the pinned user/assistant message, opaque reasoning, function call/output, function/MCP tool, and named-function-choice shapes. Bounded visitors reject duplicate keys inside open function JSON Schema and MCP header documents; empty replay metadata arrays and explicit list caps match the captures. Core preflight applies the same typed input surface to direct callers and rehydrated history. All 18 requests in the six recorder-generated pinned cassettes pass the guard. The availability gate remains closed.
• Keep normalization, synchronous ingestion, delivery, and orchestration responsibilities separate. No new production parser, queue, worker, or client-emission path is added. Cohesive extractions lower the existing production-file size allowances.

Storage and compatibility

Migration 0006_reasoning_provenance.sql adds nullable items.reasoning_provenance TEXT without backfilling legacy rows. Startup/readiness require the column, including supervisor-managed schemas. Invalid, oversized, unknown-version, or wrong-item-kind provenance fails closed. Fixed non-wire provenance charges participate in response/checkpoint budgets. Reported-model propagation requires no additional migration and does not rewrite old unknown-model fingerprints.

Public JSON/OpenAPI remain free of provenance fields; public completed-response model naming is unchanged. Rust struct-literal callers must supply the new policy/profile/provenance fields and the typed optional model in EventPayload::Response. Raw item insertion is crate-private; typed stores remain the persistence interface. UpstreamRequest import paths remain available; Rust struct literals now require store: None for the default contract and .into() to convert Cow<ResponsesInput> into the typed input view. No additional storage migration is needed for this adapter, stream-owned producer lifecycle, assistant phase, or canonical round-ordering fix. Public Rust RequestContext struct literals must now initialize recorded_output_prefix with RecordedOutputPrefix::default(); split contexts do so without serializing the marker. Item JSON preserves phase directly; public InputMessage and OutputMessage struct literals must now supply phase, while constructors default it to None and existing import paths remain available. Design and migration details are in docs/design/provider-aware-reasoning.md.

Remaining #335 work

• Complete live gateway acceptance and actual HTTP/WebSocket transport coverage, including connection-local routing. Offline executor acceptance covers durable/transient continuations, forks, promotion, conversations and gateway-executed tool loops. The pinned provider reference captures cover JSON/SSE/WebSocket, but are not live gateway execution. Complete live gateway acceptance and qualify any further request settings, item/tool shapes, tool normalization, and provider terminal/error modes before opening the profile. The pinned nested wire shapes are now closed against silent field loss; store: false cannot bypass executor preflight through transparent HTTP proxying. Ambiguous WebSocket wire failures carry no stream or previous-response ID, so they cannot select a lane or cached checkpoint for eviction. Existing gpt-5.6 captures remain regression evidence, not pinned-model qualification.
• Keep local plaintext compaction distinct from provider opaque compaction. Candidate preflight rejects local compaction input/triggers and nonempty context_management; provider compaction remains unsupported.
• Keep qualification opt-in and credentials local. The expanded recorder and pinned reference fixtures are now available, and live access succeeded using the locally configured environment; credentials are not included in fixtures. Future captures must use the recorder and staged validation, never hand-authored YAML. The producer lifetime prerequisite is addressed; broader refactor: extract StreamRelay and bound client delivery #244 delivery/observability and perf: benchmark inline versus worker placement for streaming ingestion #245 placement measurements remain separate.

Test Plan

• Current slice (0621bce): the complete core/server suites passed at the pushed head with cargo test -p agentic-server-core -p agentic-server --quiet; workspace all-target Clippy with -D warnings and all applicable staged-file pre-commit hooks passed. The server guard replays all 18 requests from six recorder-generated pinned cassettes; HTTP/WebSocket integration rejects nested unknown and duplicate fields, including duplicate keys in open JSON Schema, without leaking caller content. Core tests reject unqualified input shapes and excess list sizes before the closed gate. No live provider calls or cassette edits were made.
• Current slice (be77904): cargo test -p agentic-server-core -p agentic-server passed before the request-parser extraction, and the complete server suite passed again afterward. Workspace all-target Clippy with -D warnings, format, and all applicable staged-file pre-commit hooks passed. HTTP and WebSocket integration tests cover unknown/duplicate fields, redacted errors, the closed gate, store: false executor routing, and unchanged default proxying; core preflight rejects unknown input-item kinds. No live provider calls or cassette changes.
• Current slice (c825a66): the full core suite passed with cargo test -p agentic-server-core --offline --quiet --no-fail-fast; workspace all-target Clippy with -D warnings, formatting and applicable staged-file pre-commit hooks passed. A new JSON/SSE matrix rejects 20 unqualified modeled request cases before missing-history lookup or network access, with exact typed parameter errors. A positive unit case preserves the pinned settings without opening the gate; prior recorder-backed executor tests remain green. No provider calls or cassette edits were made.
• Prior slice (4a617d5): nine offline full-executor acceptance tests pass across pinned JSON/SSE recordings. Cover durable continuations/branches, transient fork isolation and promotion, origin and rotated-credential rejection before network access, ordinary-transport fail-closed behavior, unpolled/active drop, malformed or truncated upstream completion, failed-fork recovery, and two-round MCP tool execution with durable/conversation/session history ordering. A second-round model mismatch persists no response after a completed tool; remote tool side effects are explicitly not rolled back. The turn-prefix unit test checks monotonic deduplication and discovery retention.
• Reran the complete workspace suite and all-target Clippy after the final changes; all non-ignored tests and applicable staged-file pre-commit hooks pass. This slice made no live provider calls and changed no cassette YAML. All provider response bodies on positive paths are reused from the existing recorder-generated pinned captures; faults are in-memory mutations. User-owned local configuration and unrelated untracked files are excluded.
• Passed cargo test --workspace --offline --quiet --no-fail-fast, including storage, reasoning, stateful responses, sessions, HTTP/WebSocket, OpenAPI, and compaction/cassette suites.
• Passed cargo clippy --workspace --all-targets --offline -- -D warnings and all applicable staged-file pre-commit hooks, including formatting and Rust file-size checks.
• Added 16 adapter/profile regression tests: typed stateless projection and unchanged history, recorded JSON/SSE ingestion, malformed state, missing/out-of-order/duplicate completion, index mismatch, disconnect/backpressure/cancellation, model evidence on rounds without reasoning, and safe tool-search lifecycle preservation. Loopback transport fixtures cover HTTP rejection by the production constructor, redirect rejection, error-body redaction, explicit headers, byte limits, timeouts, and invalid/truncated SSE framing.
• Added 12 producer lifecycle regression tests (5 unit and 7 cassette-backed integration), replacing the older task-panic test. Cover unpolled/active drop, backpressure, pending I/O and tools, ordered completion, panic redaction/sequence numbers, storage-wait cancellation, persistence-before-completion, and cancelled-fork source provenance. The complete lifecycle integration suite and workspace Clippy were rerun after strengthening the active-fork case; all pre-commit hooks also passed. These tests reuse existing recorder-generated cassettes.
• Added candidate-profile unit/integration and server TOML tests for closed configuration, exact endpoint/model checks before history lookup/tool discovery/JSON or SSE inference, legacy/manual origin rejection, credential rotation, profile-domain separation, compaction boundaries, unchanged canonical bytes/call order, atomic provenance stamping, and safe error envelopes. Compatibility success never bypasses the availability gate. These are local checks, not provider qualification.
• New model-evidence tests cover JSON/SSE fingerprint equivalence under an unchanged request alias; reported-model changes; missing/null/conflicting metadata; exact UTF-8 bounds; round isolation; retained-budget exhaustion; upstream disconnect; client backpressure/drop; and rejection before response persistence. The cross-cassette strict audit asserts the exact known alias-rewriting capture/error while retaining its other compatibility checks.
• Provenance tests cover wire/OpenAPI exclusion, mixed-origin batched storage, SQLite migration/restart/readiness, corrupted history, split-execution resubmission, cancelled forks, and ephemeral-to-durable promotion.
• Captured and validated six pinned provider-reference cassettes (18 successful real requests), then replayed every body through strict AgentPipeline before promotion. Four reference tests verify exact terminal model evidence, opaque bytes, summaries, phase, item order, typed request projection, branch sources, and in-memory missing-terminal/duplicate-completion/wrong-index faults. The files match recorder staging byte-for-byte; no captured YAML was hand-authored or edited. These references do not qualify live gateway execution.
• Passed all 23 offline recorder tests, three assistant-phase serialization/storage/validation tests, and the phase OpenAPI schema test. Reran the complete workspace suite, workspace all-target Clippy with warnings denied, formatting and all applicable pre-commit hooks. Existing Qwen/OpenAI/gateway cassette regressions also pass; 11 existing opt-in/ignored tests, including the ignored doctest, remain unrun.
• Verified with Rust 1.98. Rust 1.85 verification remains blocked by existing locked dependencies requiring Rust 1.86–1.88. No dependency versions changed; the already-locked sha2 library is now also a direct core dependency.