rutster/AGENTS.md

# Agent Guide: rutster

Rutster is the open-source engine for building the **AI-era contact center** — self-hostable,
AI-native, memory-safe Rust. A framework/engine (not a turnkey product); a spiritual successor to
Asterisk's *place in the world*, not its protocols or architecture. See [`README.md`](README.md)
for the full vision and [`docs/superpowers/specs/2026-06-28-slice-1-webrtc-loopback-design.md`](docs/superpowers/specs/2026-06-28-slice-1-webrtc-loopback-design.md)
for the active build target.

This file orients any agent (human, AI, hybrid) working in the repo.

---

## Project structure (current + planned)

```
rutster/
├── README.md                                       # vision, persona, wedge, capability ladder
├── AGENTS.md                                       # this file
├── LEARNING.md                                     # (planned) index of "to learn concept X, read file Y"
├── Cargo.toml                                      # (planned) [workspace] manifest
├── deny.toml                                       # (planned) cargo-deny config
├── rust-toolchain.toml                             # (planned) pinned stable
├── crates/                                         # (planned) workspace members, ADR-0002-fused-vertical shape
│   ├── rutster/                                    # binary: axum signaling server + media driver + static page
│   ├── rutster-media/                             # str0m WebRTC + Opus<->PCM codec boundary
│   ├── rutster-call-model/                        # the Channel/Leg object embryo
│   ├── rutster-trunk/                     # stub until spearhead step 5
│   ├── rutster-tap/                               # stub until spearhead step 2
│   └── rutster-spend/                             # stub until spearhead step 6
├── fuzz/                                           # (planned) placeholder cargo-fuzz harness dir
├── docs/
│   ├── ARCHITECTURE.md                             # fused per-call vertical + composable platform
│   ├── PORT_PLAN.md                                # capability checklist + thin-slice phasing
│   ├── adr/                                        # Architecture Decision Records (read before design work)
│   └── superpowers/specs/                          # design specs (brainstorming → plan → implementation)
└── .github/workflows/ci.yml                        # (planned) fmt, clippy -D warnings, test --all, cargo deny check
```

Items marked **(planned)** are not yet on disk; they land with slice-1 implementation. Until then
the repo is docs-only.

---

## Build / lint / test commands

**Rust (when the workspace exists):**

```bash
cargo fmt --check                  # formatting check (CI gate)
cargo clippy -- -D warnings        # lints (CI gate; warnings = failures)
cargo test --all                   # all unit + integration tests across the workspace
cargo deny check                   # licenses, advisories, bans, sources (CI gate)
cargo doc --no-deps --open         # render the API docs (slice 1 heavily commented for learners)
```

**Per-crate iteration:**

```bash
cargo test -p rutster-media                  # one crate's tests
cargo test -p rutster-media -- --nocapture   # see println! output
cargo run -p rutster                         # run the binary (axum on 0.0.0.0:8080)
RUST_LOG=rutster=debug cargo run              # verbose tracing
```

**Docs-only iterations (current state):**

```bash
# validate markdown links + structure
ls docs/adr/ docs/superpowers/specs/
```

There is no Python, no Node, no Docker in the dev loop for slice 1. The batteries-included
`compose up` is a later-rung concern (lands with Valkey + trunk).

---

## Code style (Rust)

### Formatting & linting

- `cargo fmt` is the single source of truth for whitespace/indentation. Don't hand-format.
- `clippy -D warnings` is the lint bar. CI fails on any warning. Fix the code, don't suppress
  with `#[allow]` unless the rationale is documented inline.

### Naming

- `snake_case` for functions, methods, variables, modules, crates.
- `PascalCase` for types (struct, enum, trait).
- `UPPER_SNAKE_CASE` for constants.
- `newtype` wrappers over primitives for type-safety (e.g. `ChannelId(Uuid)`, not bare `Uuid`) —
  see `rutster-call-model`. The pattern prevents mixing up a `ChannelId` with a `SessionId` at
  the type system level.

### Error handling

- Cold path (signaling, setup, request handlers): `thiserror`-derived error enums, `?`
  propagation, converted to HTTP status codes at the axum boundary.
- Hot path (the 20 ms media loop): **never** `?`-propagate. Match-and-continue. A dropped packet
  must not terminate the peer. Policy: "drop + observe (log + counter), don't crash." This is
  the posture the eventual fuzz harness will test against.
- Never `unwrap()` / `expect()` outside tests or const-initialization contexts. Use `?` or
  explicit match.

### Async & concurrency

- tokio for the control plane and for slice-1 media polling (**acknowledged deviation** from
  ARCHITECTURE.md, which mandates dedicated timing threads — see slice-1 spec §3.4).
- `Arc<Mutex<T>>` for short-held shared state; prefer `Arc<RwLock<T>>` only when reads
  dominate writes. Comment the choice inline (it's a learner-facing item).
- Sans-IO design where the slice-1 spec calls for it (str0m `Live` polling). The code comments
  explain *why*: a sans-IO component is one that takes input via method calls and produces
  output via return values, never touching IO directly — making it fully testable without a
  network.

### Documentation comments (learner-facing — important)

**This project overrides the default "no comments" convention.** The user is learning Rust
from this codebase. Slice 1 carries thorough educational comments:

- `//!` module docs at the top of every `lib.rs` / `main.rs` / sub-module: what the module does,
  why it exists in the architecture (cross-ref the relevant ADR / PORT_PLAN row), key types.
- `///` item docs on every public struct / enum / fn / trait: purpose + short example where
  non-obvious. Must render correctly in `cargo doc`.
- `//` inline comments on the *mechanism*, not the what — why `Pin<Box<dyn Future>>` instead of
  `async fn`, why `Arc<Mutex<...>>` vs `Arc<RwLock<...>>`, what `PhantomData` is doing, why an
  `enum` was chosen over a `struct` with a `kind` field. Aim: a Rust learner reads the comment
  and learns a specific Rust concept they wouldn't have inferred from the code alone.
- str0m-specifics flagged: every str0m interaction gets a comment explaining what str0m is
  doing and why we drive it that way.
- Ownership / borrowing decisions called out the first time each non-obvious pattern appears.

This verbosity is a deliberate trade-off: more tokens to skim now, compound educational value
later. Once a pattern is established and the reader has learned it, later slices can be sparser
on the well-trodden patterns.

---

## Terminology policy (inclusive language)

**Avoid authoritarian / exclusionary terms** in our own code, prose, identifiers, and
endpoint names. Use equally-descriptive alternatives:

| Avoid | Use instead |
|---|---|
| police / policing (the verb) | enforce / gate / guard |
| master / slave | primary / replica, leader / follower, controller / worker |
| blacklist / whitelist | denylist / allowlist, blocklist / safelist |
| officer | operator / handler / controller |
| censor | suppress / filter |

**Exception: protocol-convention names are kept verbatim** when they come from upstream
specs or libraries we depend on — replacing them would hurt the educational mapping to
upstream documentation. Concretely, **ICE** (Interactive Connectivity Establishment,
RFC 8445) stays: it's the protocol name in `str0m::ice`, `RTCIceCandidate`, and the cargo
crate ecosystem. Our *prose* around it can say "NAT traversal" / "connectivity candidates"
where that reads better, but identifiers and protocol-level references keep `ICE`.

Same logic for any future RFC-defined acronym.

---

## Architecture pre-reading (required before design work)

Before proposing changes to the architecture, read in this order:

1. [`README.md`](README.md) — north star, persona, wedge, capability ladder (10 min).
2. [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — fused per-call vertical + composable platform,
   the agent tap as central interface (15 min).
3. [`docs/PORT_PLAN.md`](docs/PORT_PLAN.md) — capability checklist + disposition per subsystem +
   thin-slice phasing (20 min).
4. [`docs/adr/`](docs/adr/) — every ADR. Load-bearing decisions, not optional reading:
   - [ADR-0002](docs/adr/0002-north-star-and-fused-core.md) — north star + fused vertical
   - [ADR-0003](docs/adr/0003-sip-rust-native-trunk.md) — ~~Rust-native trunk SIP~~ **superseded by [ADR-0007](docs/adr/0007-trunk-rented-transport.md)**
   - [ADR-0004](docs/adr/0004-license.md) — GPL-3.0-or-later
   - [ADR-0005](docs/adr/0005-event-bus.md) — Valkey as bus + state store
   - [ADR-0006](docs/adr/0006-ingress-posture.md) — WebRTC-first ingress
   - [ADR-0007](docs/adr/0007-trunk-rented-transport.md) — rent the trunk transport; no first-party SIP stack
   - [ADR-0008](docs/adr/0008-fob-and-green-zone.md) — the FOB / green-zone build-vs-reuse doctrine
5. [`docs/superpowers/specs/`](docs/superpowers/specs/) — design specs in flight. Read the
   latest one to know what's currently being built and what's explicitly deferred.
   - [2026-06-26 vision-revision](docs/superpowers/specs/2026-06-26-vision-revision-design.md) —
     the pressure-test that produced the current architecture.
   - [2026-06-28 slice-1 WebRTC loopback](docs/superpowers/specs/2026-06-28-slice-1-webrtc-loopback-design.md) —
     the active build target.

The slice-1 spec's §1.2 out-of-scope table is the **single source of truth** for "is X done?"
and "why isn't X here?" questions. Consult it before adding anything.

---

## Key decisions to respect

- **The FOB / green-zone doctrine** (ADR-0008) — *the* build-vs-reuse rule. Build it in the
  memory-safe Rust **FOB** only if it's hot-path, security-constitutive, or differentiating; otherwise
  reuse trusted, **actively-maintained** OSS in the **green zone**, at arm's length (its own process /
  container / trust domain). 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.
- **License:** `GPL-3.0-or-later` on every crate manifest (ADR-0004). Strong copyleft in the
  Asterisk lineage. Don't introduce deps that conflict (`cargo deny check licenses` enforces).
- **WebRTC stack:** `str0m` (sans-IO). Not `webrtc-rs`. Chosen because the sans-IO design maps
  directly onto ARCHITECTURE.md's "dedicated timing threads, not the shared tokio pool."
- **Workspace shape:** full ADR-0002-fused-vertical layout. Stub crates are explicitly
  permissibly empty (`lib.rs` with doc comment + a `crate_compiles()` test). They lock
  boundaries, not anticipate code.
- **Agent tap posture:** core-as-client, brain-as-server. **No inbound tap port on the core.**
  Tap = egress; ingress = inbound (WebRTC) — opposite security postures, never unified
  (ADR-0006). Don't blur this line.
- **In-boundary spend/abuse control** is constitutive of the wedge (ADR-0002). Pulling it out
  into a service re-introduces the 3-vendor structural hole. Don't externalize it.
- **Fused per-call vertical** — the control↔media gRPC hop on the per-call hot path is
  *removed* by design (ADR-0002). Don't re-introduce it.
- **No WASM in the core story** (ADR-0002 demoted it). The agent tap is the extension point
  for in-call logic.

---

## Git workflow

- **Trunk-based development** (target, once branch protection is in place):
  1. Branch from `main` for any change.
  2. Open a PR targeting `main`.
  3. CI gates: `cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test --all`,
     `cargo deny check`. All must pass before merge.
  4. Squash-merge to keep `main` linear.
- **Never push directly to `main`.** Branch protection (planned) will enforce; until then,
  self-discipline.
- **Commit messages:** imperative mood, subject ≤ 72 chars, body wraps at 72, blank line
  between subject and body. Reference ADRs / specs by number when relevant. Match the style
  of recent commits (`git log --oneline -10`).
- **Atomic commits:** one logical change per commit. Doc ratifications, code, and tests
  each land as separate commits when practical. Don't bundle unrelated work.
- **Never commit secrets.** The `.gitignore` already covers `.env*`, `*.pem`, `*.key`. If
  a new secret pattern appears, extend `.gitignore` in the same commit.

---

## Slice-1 boundaries — what NOT to add (yet)

These are explicitly deferred per the slice-1 spec's out-of-scope table. Adding them NOW
would break the sequencing that the spearhead depends on:

- ❌ Dedicated timing thread for the media loop (deferred to step 4, barge-in)
- ❌ TLS on the HTTP signaling surface (deferred to step 5, rented-transport PSTN)
- ❌ Authn / authz / multi-tenancy on `/v1/sessions` (deferred to step 6, spend cap)
- ❌ Trickle ICE (deferred until NATs demand it)
- ❌ The tap itself (deferred to step 2 — slice 1 only *pre-paves* the seam)
- ❌ The brain / STT / LLM / TTS (deferred to step 3)
- ❌ Barge-in / VAD-driven playout kill (deferred to step 4)
- ❌ PSTN via rented transport / CPaaS media-leg ingress (deferred to step 5; no first-party SIP — ADR-0007)
- ❌ Spend cap / abuse gate (deferred to step 6)
- ❌ Browser-based automated e2e tests / Selenium / Playwright (deferred post-slice-1)
- ❌ Docker / compose (deferred to a later rung)
- ❌ Event bus / Valkey / CDR emission (deferred to step 5)
- ❌ Transfer / park / pickup / barge features (deferred to escalation rung 2)

If an agent proposes adding any of these in slice 1, the right answer is "no, see the
slice-1 spec §1.2."

---

## What's next

The active task is implementing slice 1 per
[`docs/superpowers/specs/2026-06-28-slice-1-webrtc-loopback-design.md`](docs/superpowers/specs/2026-06-28-slice-1-webrtc-loopback-design.md).
The brainstorming phase is complete; the next step is the implementation plan (via the
writing-plans skill), then TDD execution.