Architecture Decision Records (ADRs)¶
This directory records the significant architecture and design decisions for anvil-serving — the context, the options weighed, the decision, and its consequences — so the why survives the people and the chat logs.
Convention¶
- One file per decision:
NNNN-short-kebab-title.md(zero-padded, sequential —0001,0002, …). - Format: Context → Considered options → Decision → Consequences. Start from
template.md. - Status:
Proposed·Accepted·Deferred·Superseded by ADR-NNNN. - Never delete an ADR — supersede it. A reversed decision is itself history; write a new ADR that
supersedes the old one and mark the old one
Superseded. - When to write one: any non-trivial, hard-to-reverse, or cross-cutting decision — a product contract, a routing/auth model, a dependency, a protocol or wire-format choice, a security posture.
- New ADR: copy
template.md→ next number, fill it in, link related ADRs/issues, and add it to the index below.
Index¶
| # | Title | Status |
|---|---|---|
| 0001 | Cloud cost & subscription auth — why anvil should not relay cloud | Accepted |
| 0002 | Model serves are Docker-Compose-defined | Accepted |
| 0003 | Portable-by-default: out-of-box router correctness and a generated bring-up | Accepted |
| 0004 | Router as a service: containerized, network-facing, token-authed | Accepted |
| 0005 | anvil-503 native-failover loop (historical fallback architecture) | Superseded by ADR-0028 |
| 0006 | Multiplexer swaps drain in-flight requests before evicting the resident model | Accepted |
| 0007 | Subscription-auth cloud tier | Superseded by ADR-0028 |
| 0008 | Heavy tier enables NEXTN speculative decoding (self-speculation, no draft model) | Accepted |
| 0009 | Measured quality-profile write-back loop | Superseded by ADR-0028 |
| 0010 | Specialized-engine tier: run any model on any engine (config-first, RelayBackend-served) | Accepted |
| 0011 | Two modes of operation: agentic vs maximum-flexibility | Superseded by ADR-0028 |
| 0012 | Serve & router management flows through anvil-serving verbs; deployed router config is a mutable volume promoted via validate→atomic-write→reload→rollback | Accepted |
| 0013 | OpenClaw intent adapter and MCP control plane | Superseded by ADR-0028 |
| 0014 | Tailnet controller transport for split-host OpenClaw deployments | Accepted |
| 0015 | Operator skills and sub-agent workflows above the MCP/controller control plane | Accepted |
| 0016 | Runtime tier readiness excludes stopped serves without config rewrites | Accepted |
| 0017 | GPU residency reservations: declarative VRAM ledger enforced by serve lifecycle verbs | Accepted |
| 0018 | Router transition safety for slow single-workstation model swaps | Accepted |
| 0019 | anvil-serving owns the tailnet edge: a tailscale serve path-router (/v1 → router, /comfyui) in front of the unchanged router |
Accepted |
| 0020 | init defaults to the home scaffold, shipped as package data (installed-tool fix) |
Accepted |
| 0021 | CLI interaction contract: resource-first, previewable, recoverable, and cross-platform | Accepted |
| 0022 | Evaluation evidence protocol: model-aware, repeated, and comparison-safe | Accepted |
| 0023 | Lifecycle-aware WSL page-cache reclaim | Accepted |
| 0024 | Normalized authenticated one-shot audio gateway | Accepted |
| 0025 | TTS-authoritative Realtime assistant transcripts | Accepted |
| 0026 | Opt-in transparent response model reports the served tier | Superseded by ADR-0028 |
| 0027 | Public findings are durable evidence | Accepted |
| 0028 | Serving, benchmarks, and a thin capability gateway | Accepted |
| 0029 | Modular command registry with parser-owned leaf help | Accepted |
| 0030 | Containerized Dark controller and MCP 2026-only remote operation | Superseded by ADR-0031 |
| 0031 | Dual-era TypeScript MCP bridge on Companion Node | Accepted |
| 0032 | Public product, private operator state | Accepted |
| 0033 | Production durability model, plane contract, and controller-RPC fleet direction | Accepted |
| 0034 | Fleet control plane on the gateway host, and node runtime classes | Accepted |
| 0035 | Fleet configuration reconciliation: git as the state store, controller-mediated install and adopt | Accepted |
| 0036 | Voice relocates to the opportunistic macOS node; the freed discrete-GPU host becomes the qualification and ComfyUI host | Proposed |
| 0037 | Caller-side prompt-lane classification: an advisory encoder sidecar outside the gateway | Proposed |
| 0038 | Inference-owned model metadata behind stable capability aliases | Accepted |
| 0039 | Capability meta-router as the product model | Accepted |
| 0040 | One media gateway origin with separated operation authority | Accepted |
| 0041 | Initial media workflows and bounded operating policy | Accepted for implementation |
| 0042 | Anvil Serving is one umbrella with six explicit product families | Accepted |
| 0043 | Co-located connector tunnel fast-path over loopback | Proposed |