diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 5c27d75..e236fba 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -32,8 +32,9 @@ carrier SIP trunk ─► media termination (RTP/SRTP + local real-time reflexes) ``` **Horizontal platform** concerns are services *around* the core, independently scaled: number -inventory, billing rollup, analytics, multi-region orchestration, the management API, and the agent -brain itself. +inventory, billing rollup, analytics, multi-region orchestration, call placement (the +session→node directory — which node owns which live call, the routing layer above N cores), +the management API, and the agent brain itself. This **replaces the founding three-plane framing**: diff --git a/docs/adr/0005-event-bus.md b/docs/adr/0005-event-bus.md index 8f0d94a..460c586 100644 --- a/docs/adr/0005-event-bus.md +++ b/docs/adr/0005-event-bus.md @@ -53,6 +53,10 @@ Recommending "Redis" undercuts the data-ownership pillar ([ADR-0002](0002-north- persistence (RDB/AOF) is async-ish — fine for transport / replay / fleeting retention, **wrong** for "the CDR that proves what we billed." CDR and recordings emit **durably to object storage** in their own services; the bus only *flows* events into that pipeline and lets services *react*. +3. **Constraint 2 governs the durable CDR, not enforcement counters.** The spend gate's + live accounting state (spend/pacing/rate counters) is ephemeral control state and DOES + belong in Valkey KV at N>1 — see the + [ADR-0009 amendment 2026-07-04](0009-spend-gate-honest-rescope.md#amendment-2026-07-04--enforcement-locality--accounting-locality). ## Consequences diff --git a/docs/adr/0009-spend-gate-honest-rescope.md b/docs/adr/0009-spend-gate-honest-rescope.md index ff7e16a..8e37c8f 100644 --- a/docs/adr/0009-spend-gate-honest-rescope.md +++ b/docs/adr/0009-spend-gate-honest-rescope.md @@ -82,6 +82,32 @@ security-constitutive), but its guarantees are restated precisely: [market feature scan F5](../reviews/2026-07-03-market-feature-scan.md), since integrator unit economics run on cost-per-contained-call). +## Amendment 2026-07-04 — enforcement locality ≠ accounting locality + +- **Status:** Proposed (pending maintainer ratification) +- **Origin:** [2026-07-04 scalability & infra-fit review](../reviews/2026-07-04-scalability-infra-review.md), + finding M5. + +Guarantee 2 above prescribes where the **check** sits — in-process with the tap and the +provider call-control client. It is silent on where the **accounting state** lives, and at +N>1 core instances that silence becomes a correctness trap: per-instance counters make +every spend/pacing cap silently N× the fleet intent, and toll-fraud thresholds never trip +because attempts spread across instances. + +Clarification, binding on the step-6 implementation: + +1. **Enforcement is in-process** (unchanged — constitutive; guarantee 2 stands). +2. **Accounting is shared.** The gate is built against a ledger trait with atomic + check-and-reserve semantics from day one: an in-memory implementation for single-node, + a Valkey-backed one ([ADR-0005](0005-event-bus.md)) for fleets. The check path never + assumes counter locality. +3. **ADR-0005 constraint 2 is not a counter-argument.** "The bus is not the source of + truth for billing- or call-loss-critical state" governs the *durable CDR*. Live + enforcement counters (spend/pacing/rate state) are ephemeral control state — exactly + what Valkey KV is for. Losing them on a Valkey restart degrades fail-safe (re-count + from zero, provider-side caps as the backstop per this ADR's deployment guidance) — + not to billing corruption. + ## References - [ADR-0002](0002-north-star-and-fused-core.md) — the pillar this amends