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

docs: propagate ADR-0007/0008 to README, ARCHITECTURE, PORT_PLAN, AGENTS

Browse Source 
ADR-0007 (rent the trunk) + ADR-0008 (FOB/green-zone doctrine) propagation
into the narrative docs that orient contributors + readers. No code changes.

README:
- Wedge bullet 2: 'one secure auditable boundary' now lists media + local
  reflexes + spend + tap + audit (was: trunk termination + media + spend).
  Adds the honest caveat that PSTN media inside the boundary is the on-prem
  *graduation* (ADR-0007), not a day-one claim.
- 'Is / isn't': 'isn't a TDM/PSTN-hardware PBX — *and not a SIP stack.*'
  No first-party SIP (ADR-0007). PSTN reach is rented transport.
- Memory-safety pillar: 'rutster parses no SIP at all' — entire first-party
  wire surface is WebRTC/RTP/SRTP + WebSocket tap/ingress, all memory-safe
  Rust. The carrier-SIP interop tail lives outside the trust boundary.
- Spearhead step 5: 'Add a real phone number via rented transport' (was:
  'Replace WebRTC ingress with a real PSTN trunk call'). Re-aims at the
  AI-telephony frontier; no first-party SIP stack.
- References: 0007 supersedes 0003 in the highlighted ADR list.

ARCHITECTURE:
- New 'FOB and the green zone' section after the fused-vertical framing —
  names the build-vs-reuse doctrine with the FOB member list + green-zone
  member list, and restates memory-safety precisely ('FOB is 100%
  memory-safe Rust; the green zone is trusted OSS kept outside the
  boundary — not an over-claim that every byte is Rust').
- 'Inside the boundary': 'Carrier trunk — rented transport, not first-party'
  replaces 'Trunk SIP termination — Rust-native.' PSTN audio arrives as
  a media-leg ingress from a rented CPaaS raw-media fork or an out-of-tree
  SBC for on-prem sovereignty.
- Biggest technical risk: 'No longer the SIP stack — because rutster no
  longer builds one.' Retires ADR-0003's named schedule risk; redirects
  to 'the reflex loop itself' (turn-taking, VAD-driven barge-in, jitter,
  pacing) — which is also the differentiator.

PORT_PLAN:
- Design rule 4: 'rent it, don't own it' replaces ADR-0003's 'Rust-native
  trunk SIP, no SBC shield.' ADR-0007 restores the rule's original instinct.
- SIP signaling (trunk) row: disposition flipped to 🔌 Rented / out-of-tree.
- Outbound registration row: disposition flipped to 🔌 Rented / out-of-tree
  (handled by the rented transport or out-of-tree SBC; rutster parses no SIP).
- Spend/abuse engine row: 'co-located with call origination + the tap inside
  the boundary' (was: 'co-located with trunk termination'). rutster mediates
  both the provider call-control API and the brain tap — the brain never
  holds the wire.
- Spearhead step 5: 'Add a real phone number via rented transport.'
- Open decisions: SIP line updated to 'Re-decided — ADR-0007.'

AGENTS.md:
- ADR list: adds 0007 and 0008 with annotations; marks 0003 as superseded
  by 0007.
- Key decisions to respect: prepends the FOB/green-zone doctrine as the
  *the* build-vs-reuse rule. 'When in doubt, default to green zone — the
  FOB earns its members, it doesn't collect them. This is why the trunk is
  rented (ADR-0007) and Valkey reused (ADR-0005), not rebuilt. Don't pull
  green-zone plumbing into the core.'
This commit is contained in:
opencode controller
2026-06-29 20:26:51 -04:00
parent 3c3197e57a
commit 7616878bb1
4 changed files with 76 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
README.md
View File

@@ -56,8 +56,10 @@ The white space no incumbent fills:
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).
2. **One secure auditable boundary** — media + local reflexes + spend/abuse control + the tap +
audit in a single memory-safe trust domain. One thing to certify (strongest for PCI / HIPAA / TCPA).
The carrier trunk is rented (or out-of-tree); bringing PSTN media *inside* the boundary is the
on-prem **graduation** ([ADR-0007](docs/adr/0007-trunk-rented-transport.md)), not a day-one claim.
3. **Operational simplicity** — one binary, one bill, one deploy.
**Honest caveat:** the agent *brain* (STT/LLM/TTS) is necessarily external — audio leaves the box
@@ -75,21 +77,24 @@ exactly as integrators did on top of Asterisk.
## What it is / isn't
- **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
- **Is:** a Rust media core owning the **per-call vertical** (RTP/SRTP media termination + local real-time reflexes + a clean
audio tap to an external brain + in-boundary spend/abuse control; the carrier trunk is *rented
transport*, not first-party — [ADR-0007](docs/adr/0007-trunk-rented-transport.md)); 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.
- **Isn't:** a TDM/PSTN-hardware PBX — *and not a SIP stack.* No DAHDI, no Sangoma/Digium cards, no
ISDN/SS7, no IAX2/H.323/SCCP/MGCP/Unistim — and **no first-party SIP**
([ADR-0007](docs/adr/0007-trunk-rented-transport.md)). PSTN reach is **rented transport** (a CPaaS
raw-media fork, or an out-of-tree SBC for on-prem media). Inbound SIP *endpoint* registration (desk
phones) likewise stays out-of-tree — 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. 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*.
parsers. rutster **parses no SIP at all** ([ADR-0007](docs/adr/0007-trunk-rented-transport.md)): its
entire first-party wire surface is WebRTC/RTP/SRTP + the WebSocket tap/ingress protocol — all
memory-safe Rust. The carrier-SIP interop tail lives *outside* the trust boundary (rented transport
or an out-of-tree SBC), so the buffer-overflow/RCE CVE class is designed out of rutster's own surface.
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.
@@ -111,7 +116,7 @@ exactly as integrators did on top of Asterisk.
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)
- [0007](docs/adr/0007-trunk-rented-transport.md) — rent the trunk transport; no first-party SIP stack (supersedes [0003](docs/adr/0003-sip-rust-native-trunk.md))
- [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
@@ -133,7 +138,8 @@ The full thin slice, sequenced so each step is its own proof — never a big ban
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
5. **Add a real phone number via rented transport** (a CPaaS raw-media fork, e.g. Twilio Media
Streams) — proves a PSTN call reaches the reflex loop, no first-party SIP ([ADR-0007](docs/adr/0007-trunk-rented-transport.md))
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