docs: ratify vision revision across README/ARCHITECTURE/PORT_PLAN + ADRs 0002-0006

Folds the 2026-06-26 vision-revision pressure-test into the canonical
docs. The spec moves from Proposed to Ratified; the decisions it produced
land in the docs it said it would amend, with ADRs recording each
load-bearing reversal.

- README.md: reframe north star (AI-era contact-center engine, not
  Asterisk successor); persona; revised pillars (add data-ownership,
  demote WASM, promote spend-control); update 'what it is/isn't'.
- ARCHITECTURE.md: replace three-plane framing with fused per-call
  vertical + composable horizontal platform; remove control<->media
  hot-path gRPC hop; make the agent tap the central interface; add
  DX spine + GUI-as-API-client + k8s declarative/operational model.
  Also: 'too slow to police' -> 'too slow to enforce' (terminology).
- PORT_PLAN.md: recharacterize as capability checklist (not template);
  graduate contact-center capabilities to first-class domain; Rust-native
  trunk SIP rows; WASM demoted; thin-slice + capability ladder phasing.
- ADR-0001: marked Superseded by ADR-0003.
- ADR-0002 (new): north star + fused per-call core.
- ADR-0003 (new): Rust-native trunk SIP, no SBC shield.
- ADR-0004 (new): GPL-3.0-or-later license.
- ADR-0005 (new): Valkey as event bus + state store.
- ADR-0006 (new): WebRTC-first ingress; SIP endpoint deferred.
- vision-revision spec: status -> Ratified 2026-06-26.
This commit is contained in:
adlee-was-taken
2026-06-28 09:33:29 -04:00
parent 23cec14977
commit 075e984fb5
10 changed files with 674 additions and 109 deletions

View File

@@ -0,0 +1,65 @@
# ADR-0006 — Ingress posture: WebRTC-first; SIP endpoint deferred
- **Status:** Accepted
- **Date:** 2026-06
- **Related:** [ADR-0003](0003-sip-rust-native-trunk.md) (trunk SIP), [ADR-0002](0002-north-star-and-fused-core.md) (fused vertical)
## Context
The fused per-call vertical ([ADR-0002](0002-north-star-and-fused-core.md)) needs an answer for
**human-participant ingress** — agents and supervisors joining/taking calls. The thin-slice first
proof starts at WebRTC loopback (vision-revision §10). The question: which protocols carry humans
into calls, and is inbound **endpoint** SIP (desk/soft phones) in scope?
## Decision
### 1. WebRTC is the first-party human-participant ingress
Agents and supervisors use the browser as the softphone: SSO in, one peer-connection,
DTLS-SRTP + ICE handled by the browser, **zero device-provisioning tail**. This is also the modern
hosted UX. Escalation (capability rung 2) is a UX gesture: an agent clicks *take this call* in the
dashboard → a WebRTC leg joins → audiohook/barge handoff. Writes itself onto the audiohook primitive
(PORT_PLAN) and shares step-1 infrastructure (WebRTC ships first regardless).
### 2. SIP trunk client = core (per ADR-0003)
Bounded: a few documented, IP-allowlisted, cooperative carriers.
### 3. Inbound SIP *endpoint* registrar = deferred / community edge, NOT core
`REGISTER` from Polycoms/Yealinks/Zoiper, BLF/MWI subscribe-notify, RFC2833-vs-SIP-INFO DTMF,
per-device NAT keepalives and provisioning quirks are **deferred out of the core**:
- **The real reason** is not "SIP is hard" — it's that an inbound endpoint server **re-imports the
unbounded device-interop tail** [ADR-0003](0003-sip-rust-native-trunk.md) deliberately closed.
ADR-0003's "tail collapses" argument survives only because rutster talks to *documented carriers*,
not *thousands of desk-phone UAs*. Opening an endpoint server reopens that seam.
- In an SSO/browser-agent contact center the desk-phone demographic has collapsed to niche ops
floors already served by dated OSS (FreePBX/Vicidial). Wrong place to spend a solo multi-year
build — a pointlessly-and-diverting distraction in a modern hosted-UX/SSO world.
- **Don't burn the bridge:** if an operator genuinely needs desk phones, the right home is an
**optional, out-of-tree SBC-style adapter** (the Kamailio-flavored thing ADR-0003 chose not to put
in the core) fronting the public API or B2B-SIP'ing into rutster — community-owned, **outside the
trust boundary** so its tail can't compromise the wedge.
### 4. Core interop perimeter is deliberately bounded
**SIP trunk client + WebRTC ingress.** Nothing else inbound.
## Security seam — tap ≠ ingress
Two distinct extension points with **opposite** security postures; never unified into one model:
- **Tap** (agent brain): **egress**, core-as-**client**, **no inbound tap port** on the core. The
boundary dials out to the brain. (See ARCHITECTURE.md, "Agent tap.")
- **Ingress** (humans): **inbound**, core-as-**server**, with SSO + RBAC + per-tenant scoping.
Legitimately a server surface — that's fine, it's auth'd; the "core-as-client" move was
specifically about the egress brain tap, where *egress* is the dangerous direction.
## Consequences
- **Positive:** first-call via WebRTC ships before any SIP; escalation is a UX click not a new
protocol; the core's interop surface stays bounded; no device-provisioning tail in the trust
boundary.
- **Negative:** desk-phone-only operators are not served by the core — accepted, the community
adapter path exists.