alee/rutster
0
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files

139
README.md
View File

@@ -1,50 +1,123 @@
# Rutster
A memory-safe, API-first, security-first telephony platform — a spiritual successor
to Asterisk for the WebRTC/microservices era, written in Rust.
The open-source engine for building the **AI-era contact center** — self-hostable, AI-native,
memory-safe Rust. A spiritual successor to Asterisk's *place in the world*, not its protocols
or its architecture.
> Not a port of Asterisk. A reimagining that keeps the *power* — era-bridging breadth,
> "wire anything to anything," a deep feature library — while dropping the legacy
> hardware/dead-protocol half and fixing Asterisk's two chronic wounds:
> memory-safety CVEs and toll fraud, at the design level.
> Not a port of Asterisk. rutster inherits the role Asterisk held — *the self-hostable engine a
> technical builder uses to stand up a contact center* — and re-aims it at a category AI is
> actively disrupting, instead of a PBX category UCaaS already ate.
## Why it exists
Asterisk won because contact centers were **built on it** (Vicidial, GOautodial, a thousand
integrator builds) — it never tried to *be* Five9. rutster inherits that position: it is a
**framework / engine, not a turnkey product**.
The white space no incumbent fills:
| Competitor | What they are | rutster's edge |
|---|---|---|
| **LiveKit** | Horizontal real-time media infra (Go) | rutster owns the **contact-center domain** (ACD, IVR, queues, recording, CDR, dialer, supervisor) LiveKit will never ship |
| **Cloud CCaaS** (Five9, Genesys, NICE, Amazon Connect, Twilio Flex) | Proprietary, AI bolted on | Self-hostable, AI-**native**, no per-seat/minute lock-in |
| **Cloud AI-voice** (Vapi, Retell, Bland) | Cheap managed voice bots | You own your **calls and training data**; it's a *contact center* (escalation, queues), not a single bot |
| **Dated OSS** (Vicidial, FreePBX) | Self-hostable, Asterisk-era | Modern, AI-native, memory-safe Rust |
The wedge is a **coherent combination, not a silver bullet**:
1. **No-GC real-time determinism** — tight turn-taking / barge-in / jitter in a no-GC loop.
2. **One secure auditable boundary** — trunk termination + media + spend/abuse control + audit in
a single memory-safe trust domain. One thing to certify (strongest for PCI / HIPAA / TCPA).
3. **Operational simplicity** — one binary, one bill, one deploy.
**Honest caveat:** the agent *brain* (STT/LLM/TTS) is necessarily external — audio leaves the box
to reach it, same as LiveKit. The real-time edge therefore lives in the **local reflexes that don't
need the brain** (VAD killing TTS the instant the caller speaks, barge-in, jitter, pacing, DTMF),
not the brain round-trip. The moat is the *whole*.
## Who it's for
The modern equivalent of the 2006 Linux-nerd-who-stood-up-Asterisk-for-an-SMB: the
**CLI/IDE/AI-comfortable self-hosting technical builder** — runs Claude Code in a terminal, lives
in an editor with an AI pair, versions everything in git, self-hosts on principle. *Not* the no-code
admin clicking a flow-designer canvas. The builder serves the non-technical operator downstream,
exactly as integrators did on top of Asterisk.
## What it is / isn't
- **Is:** SIP (TLS-only) + WebRTC signaling, a real-time media plane (transcode / mix /
DSP), a programmable call model exposed as a REST/gRPC API + event stream, a
WASM-sandboxed plugin runtime, and a library of telephony features delivered as
isolated services.
- **Isn't:** A TDM/PSTN-hardware PBX. No DAHDI, no Sangoma/Digium cards, no ISDN/SS7,
no IAX2/H.323/SCCP/MGCP/Unistim. PSTN reach is via SIP trunks / SBC only.
- **Is:** a Rust media core owning the **per-call vertical** (trunk SIP termination + RTP/SRTP media
+ local real-time reflexes + a clean audio tap to an external brain + in-boundary spend/abuse
control); a programmable call model exposed as a REST/gRPC API + event stream; WebRTC-first human
ingress; a library of contact-center capabilities (ACD, IVR, queues, recording, CDR, dialer,
supervisor) delivered as services around the core.
- **Isn't:** a TDM/PSTN-hardware PBX. No DAHDI, no Sangoma/Digium cards, no ISDN/SS7, no
IAX2/H.323/SCCP/MGCP/Unistim. PSTN reach is via SIP trunks only. Inbound SIP *endpoint*
registration (desk phones) is deferred to an out-of-tree edge adapter — not the browser/SSO UX
rutster targets.
## Core design pillars
1. **Memory-safe by construction** — Rust everywhere on the hot path; fuzzed, sans-IO
protocol parsers. Eliminates the buffer-overflow/RCE CVE class.
2. **Isolation over in-process modules** — extensions run in a **WASM sandbox**, not as
`.so` files in the daemon's address space. One bad plugin can't crash the box or
read another tenant's media. (The Asterisk `core show locks` era ends here.)
3. **Secure & deny-by-default** — mandatory TLS/SRTP, deny-by-default routing,
built-in toll-fraud controls, mTLS gRPC admin (no plaintext AMI), hard multi-tenancy.
4. **Three planes, scaled independently** — control / media / app. The media datapath
stays tight; business logic is microservices and plugins around it.
5. **Observable & declarative** — OpenTelemetry call traces across services;
config-as-data, not imperative `.conf` files edited on a box.
1. **Memory-safe by construction** — Rust everywhere on the hot path; fuzzed sans-IO protocol
parsers. Hostile bytes hit a fuzzed Rust parser first. Eliminates the buffer-overflow/RCE CVE
class — and, with the C SBC edge dropped, this is *literally true at the wire*.
2. **Security-as-product** — the single auditable boundary *is* the moat. TLS/SRTP mandatory,
deny-by-default routing, built-in toll-fraud controls, mTLS gRPC admin (no plaintext AMI), hard
multi-tenancy. Compliance is a buying criterion, not a row.
3. **In-boundary spend / abuse control** — spend caps and abuse/pacing control live **inside the
trust boundary**, co-located with trunk termination. A runaway brain can't exceed pacing or
spend because it doesn't hold the wire — structurally impossible for a 3-vendor stack.
4. **Data ownership** — calls and training data never leave the operator's infra. The self-host
wedge *and* the fuel for the ML self-improvement loop.
5. **Degradation, deterministic, observable** — no-GC real-time loop; OpenTelemetry traces that
follow a single call across the boundary; config-as-data, not `.conf` files edited on a box.
6. **Operational simplicity** — one binary, one bus, one deploy (`compose up`).
## Layout
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — the three-plane model and pillars.
- [`docs/PORT_PLAN.md`](docs/PORT_PLAN.md) — **the spine**: every Asterisk subsystem mapped
to a disposition (core / plugin / service / edge-FFI / dropped) with rationale.
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — the fused per-call vertical + composable
horizontal platform; the agent tap as the central interface.
- [`docs/PORT_PLAN.md`](docs/PORT_PLAN.md) — the capability *checklist* (what a telephony system
must handle), *not* an architecture template. Every Asterisk subsystem mapped to a disposition
with rationale.
- [`docs/adr/`](docs/adr/) — decisions. Highlights:
- [0002](docs/adr/0002-north-star-and-fused-core.md) — north star + fused vertical
- [0003](docs/adr/0003-sip-rust-native-trunk.md) — Rust-native trunk SIP (no SBC shield)
- [0004](docs/adr/0004-license.md) — GPL-3.0-or-later
- [0005](docs/adr/0005-event-bus.md) — Valkey (bus + state store)
- [0006](docs/adr/0006-ingress-posture.md) — WebRTC-first ingress; SIP endpoint deferred
## Status
Scoping. No code yet — the port plan defines the crate/service boundaries that the
workspace will be scaffolded from next.
Scoping. No code yet — the [vision revision](docs/superpowers/specs/2026-06-26-vision-revision-design.md)
and ADRs define the architecture; the workspace will be scaffolded from the capability ladder
and the thin-slice first proof.
## Open decisions
## First proof (the spearhead)
- **License** — undecided (Asterisk is GPLv2+commercial; rutster's model is TBD).
- **SIP stack** — FFI to pjproject vs. front with an SBC (Kamailio/drachtio) vs. a
long-term pure-Rust stack. See port plan §1.
- **WASM runtime** — `wasmtime` is the presumptive default (component model).
The full thin slice, sequenced so each step is its own proof — never a big bang:
1. **WebRTC media loopback** (terminate RTP/SRTP, echo audio to a browser) — proves the media core
2. **Add the tap** (route audio to an external echo process and back) — proves the tap interface
3. **Swap echo for the brain** (ideally a single speech-to-speech API, e.g. OpenAI Realtime, to
collapse STT+LLM+TTS into one integration) — proves agent integration
4. **Add barge-in** (VAD-driven playout kill) — proves the reflex
5. **Replace WebRTC ingress with a real PSTN trunk call** — proves the trunk client
6. **Add the spend cap** (hard-stop at threshold) — proves the boundary
Steps 1–4 *are* the reflex loop — the hard, most-differentiating part proves itself before trunk
integration piles on. "I called my Rust box and an AI answered the phone" is the momentum fuel a
solo multi-year build needs.
## Capability ladder (the grand vision, incrementally)
| Rung | Capability | Reuses |
|---|---|---|
| 1 | **Self-serve** — AI answers, contains the call | the thin-slice first proof |
| 2 | **Escalation** — human agent barges in / takes over when AI breaks down | the audiohook/barge primitive |
| 3 | **Measurement** — containment rate, where/why AI failed | CDR + analytics on calls *you own* |
| 4 | **Self-improvement** — every takeover → auto-labeled training data → loop | rungs 1–3 compounding |
## License
**GPL-3.0-or-later** ([ADR-0004](docs/adr/0004-license.md)). Strong copyleft in the Asterisk lineage,
modernized one notch. The license is the *floor*, not the moat — the wedge is.