Define model tags, timeouts, and fallback policy

Implement types or schemas around POST http://127.0.0.1:11434/api/generate so illegal states are unrepresentable at the boundary. For Ollama-backed local router with policy-controlled cloud fallback, trusted inputs come from sessions, signatures, pinned digests, or workload identity — not from free-form model text. legal analyst summarizing NDAs that must not leave the laptop by default should be able to read the contract and know which fields are optional, which are enumerated, and which abort the request. Constructors and boot paths must not perform provider side effects; injection points keep tests honest.

Document required env vars in .env.example with placeholders only. Rotation story belongs later, but the contract already forbids printing secrets and forbids defaulting to fail-open when a dependency is missing. Invariant to encode in types/tests: cloud fallback requires explicit policy flag + redaction pass; local p95 ≤ 6s for 512 tokens. If a config number lacks units, fix the name (timeout_ms, rpm_hard) before writing logic.

Create fixtures for the golden path and for LOCAL-FALLBACK-PII-03. Name files after the behavior (429-retry-after.json, cross-tenant.json, empty-citation.json) rather than test1. Each fixture carries expected status/code. This kit is the shared language for validation and failure pages.

Compatibility promise: additive fields may appear only if readers ignore unknowns safely; breaking changes bump a version visible on the wire. For AI payloads, size limits arrive before JSON parse when hostile blobs are a risk. Document how clock skew, idempotency keys, and tracing headers travel through Ollama-backed local router with policy-controlled cloud fallback. If you use feature flags later, the contract already states that flags are not authorization. Link each config knob to a unit and a failure mode (“0 means disabled” vs “0 means divide-by-zero”). A peer reviewing the PR should find LOCAL-FALLBACK-PII-03 named in a comment on the adversarial fixture.

Generate OpenAPI or a typed client only after the hand schema is stable for one fixture round-trip. Record how errors look on the wire — problem+json, envelope, or bare status — and stick to one. Clock sources must be injectable for skew tests. If webhooks appear later, document signature header names now even as TODOs. Keep sample payloads UTF-8 and free of real emails. Add a makefile or npm script that validates schemas without network. In this chapter the product is Ollama-backed local router with policy-controlled cloud fallback, the human stakeholder is legal analyst summarizing NDAs that must not leave the laptop by default, and the incident id you design against is LOCAL-FALLBACK-PII-03. Re-state the oracle in your notes — local llama3.2:3b answers fixture brief at ≥ 25 tok/s; fallback path logs reason=local_timeout — and keep the invariant visible: cloud fallback requires explicit policy flag + redaction pass; local p95 ≤ 6s for 512 tokens. Track local_share ≥ 0.8 and cloud_fallback_with_pii == 0 as the scoreboard. Surface under change control: POST http://127.0.0.1:11434/api/generate. If you only have forty minutes, finish the fixture for fallback silently ships full NDA text to cloud when Ollama is down before polishing UI. Promotion language stays ternary: promote, hold, or roll back based on evidence, not hope.