docs(rfc): RFC-0036 positioning and layered architecture

[eric8810]

Summary

Draft RFC that sets aimux's direction before the 0.5.0 → 1.0 roadmap (#197) is finalized. #197 derives versions from the ideal code shape (#166); this RFC answers who aimux is for and which layer the long-term abstraction bets on, then re-orders the plan.

Positioning: aimux is a provider access and governance runtime — performance and size are hard constraints; it unifies behavior across a multi-language stack, follows each vendor's evolving and private protocols, ships provider testing/governance, and runs embedded (FFI bindings) or as a stdio CLI subprocess decoupled from harnesses. No agent loop, no multi-tenant gateway business.

What the RFC establishes

• §3 L0–L3 layering — truth moves down: L0 transport (auth / retry / recording + new native passthrough so private APIs are reachable day one), L1 lossless protocols (Tracking: code reduction roadmap (providers, FFI, bindings, docs) #166 track B), L2 = today's AI SDK shape as a versioned projection, not frozen with 1.0; L2 model choice gets its own evaluation RFC with stated metrics.
• §4 ops protocol — Tracking: code reduction roadmap (providers, FFI, bindings, docs) #166 track C (model_new + call(op, json) + stream(op, json)) lifted into a transport-agnostic protocol with two entries into one dispatch: FFI (all 8 bindings, one shape, no tiers) and a stdio CLI; adds binary frames (realtime audio, uploads) and version negotiation. UDS/HTTP transports deferred until needed.
• §5 aimux-proxy extension package (direction only, unscheduled) — foreign protocol facades; same-protocol via L0 passthrough, cross-protocol via L2 with explicit lossy-field reporting; outside default builds.
• §6 governance line — evidence-backed capability matrix, drift detection via Complete recording and replay (RFC-0023): protocol-generic replay, one record format, all bindings #167 transport replay, aimux probe / replay / diff.
• §7 size + perf gates — S1–S3 from docs: 0.5.0 → 1.0 roadmap (per RFC-0036) #197 kept as hard gates, plus a new perf regression gate and per-carrier budgets.
• §8 Tracking: code reduction roadmap (providers, FFI, bindings, docs) #166 mapping — code reduction is kept and re-classified, not dropped: A/B/C2/C3/E1 unchanged, C1 upgraded into the ops protocol, D track unchanged, C4 later, B9 and Registry triage: 27 base_url disagreements and 116 missing providers vs models.dev #171 bulk additions de-prioritized.
• §9 stages — 0.6 gates + protocol groundwork, 0.7 L1 + auth, 0.8 ops protocol (FFI + stdio), 0.9 governance, 1.0 freezes the ops protocol and L0/L1.

Open questions (§10)

Generator vs hand-written bindings; binary frame format; L2 model choice.

Follow-up

Once this settles, #197 is rewritten against it (including detail fixes found in its review).

🤖 Generated with Claude Code