instar 1.3.782 → 1.3.783

package/upgrades/side-effects/routing-spend-increment-b.md

@@ -0,0 +1,44 @@
+# Side-Effects Review — Routing Control Room Increment B (money layer)
+
+**Spec:** `docs/specs/routing-control-room-spend-alerts.md` (review-convergence r7, approved 2026-07-07)
+**Worktree:** `echo/money-increment-b` off `JKHeadley/main` @ `4811c74bb` (v1.3.782) — remotes verified (`JKHeadley` = canonical, push target), version recorded per Phase 2.
+**Scope of this PR:** Increment B money core — `MeteredSpendLedger` (booking-priced, append-only, fold-is-canon), the O(1) fail-closed money gate, the PIN-only caps/go-live store (`state/routing-spend-caps.json`, versioned), rendered-plan machinery (nonce + TTL + version-pin), durable PIN-attempt store, Bearer freeze (set-true-only), caps-view wiring to real committed totals, and the stale-price/observed-drift alert emission on the minimal topic-resolver foundation (lifeline-fallback rails). Layer 1c provider_cost_report/reconciliation and the full Increment C channel abstraction land as the NEXT PRs in this sequence (tracked: CMT-1929).
+
+## Phase 1 — Principle check (signal-vs-authority)
+
+**Does this change involve a decision point?** YES — the money gate blocks metered LLM calls at cap.
+
+**Compliance:** The gate holds blocking authority with DETERMINISTIC ARITHMETIC over booked dollars (`committed + estCost > cap`, strict `>`), never brittle pattern-matching over meaning — the same class as the fork-bomb spawn cap and the test-runner semaphore, where deterministic authority is the CORRECT shape (docs/signal-vs-authority.md draws the line at brittle/semantic checks holding authority; arithmetic over money is neither brittle nor semantic). Authority is additionally BOUNDED: a cap refusal is a swap-tail ADVANCE (the chain falls to a free door), never a chain kill; `RouterFailClosedError` remains reserved for whole-chain exhaustion. Everything reporting-side (provider reports, drift, subsidies, credits) is SIGNAL-ONLY by structural exclusion — the gate's read set cannot reach those stores (unit-tested).
+
+## Phase 2 — Plan
+
+- **Decision points touched:** metered-call admission (new gate, fail-closed on every uncertainty); PIN plan-commit (S2-3 rendered-plan, single-use nonce, version drift refusal); Bearer freeze (set-true-only — halting money is cheap, releasing is the operator's).
+- **Existing detectors/authorities interacted with:** `checkMandatePin` (gains a durable attempt write-through, semantics unchanged); `PATCHABLE_CONFIG_KEYS` (regression-tested to NEVER reach the caps store or any gate-consumed price value — S-F2); `RoutingPriceAuthority` (gate consumes canonical-validated points ONLY, with code-defined per-provider plausibility floors); serving-lease staleness window (self-fence read); `DARK_GATE_EXCLUSIONS` (money authority documented as the action-bearing exclusion — dark everywhere until an explicit operator enable, FD-16).
+- **Rollback path:** every surface is additive + dark. `routingSpend.money.enabled` absent ⇒ routes 503, gate never constructed, ledger never written. Disabling reverts to Increment A behavior byte-for-byte. The caps store and ledger files are inert data at rest; no migration touches existing state.
+
+## Phase 4 — Side-effects review
+
+1. **Over-block:** The gate fails closed on unknown price / stale lease / unbounded reservation — this can refuse legitimate metered calls when the manifest is stale or the pool is partitioned. Accepted BY DESIGN (money safety over availability); the refusal is a swap-tail advance to free doors, so the JOB still completes — only the paid door is withheld. Stale-price default is `book-conservative-max` (spend continues, over-booked), so manifest staleness alone does not halt paid routing.
+2. **Under-block:** A crash between fsync'd row-append and totals update leaves totals STALE-LOW by at most one booking; the next gate read runs the row-count/high-water check and re-folds — bounded, tested both torn directions. Reserve sizing uses `max_tokens` worst-case; a provider that bills MORE than `max_tokens` output would under-reserve — mitigated by settle-books-actual (absolute row) and the billed-token per-door mapping erring HIGH. **Build-time finding worth recording:** the first gate implementation compared committed-vs-cap OUTSIDE the ledger's booking mutex; the two-concurrent-reserves test caught two $8 admits passing against a $12 cap. Fixed by moving the comparison INSIDE the per-key critical section (`admitOnlyUnderCaps` on `reserve()`), which is now the pinned shape — the check-and-reserve is atomic by construction.
+3. **Level-of-abstraction fit:** The ledger/gate live in `src/core/` beside `DriftSpendLedger` (whose write-discipline they adopt); the caps store is a dedicated PIN-only store OUTSIDE config, exactly where the spec pins it (S-F2). The gate is a library consumed at the (future) metered dispatch seam — it does NOT modify `IntelligenceRouter` selection (the seam is declared, not wired; metered doors still skip — FD-11).
+4. **Signal vs authority:** See Phase 1 — compliant; deterministic authority at the right layer, reporting side structurally excluded from the gate.
+5. **Interactions:** Freeze vs go-live: freeze halts NEW admissions only (in-flight settles land — A-Min11). The reserve-expiry sweep takes the per-key lock; the (future) provider-reconciliation sweep never does — named distinctly to keep them un-conflated. Plan commits refuse on store-version drift, so a concurrent PIN action or background change re-renders instead of silently composing. The alert resolver is serving-lease-holder-only for creation; everyone else falls back to the lifeline — no duplicate-topic race with the attention queue (which is never used for spend alerts — Amendment 2).
+6. **External surfaces:** New Bearer routes (plan render, freeze, caps log) and PIN routes (adjust, go-live, price promotion) — all 503 while dark. One new Telegram surface: the "💰 Routing & Spend Alerts" topic, created at most once by the serving-lease holder as a bounded create-once system topic; stale-price/drift alerts are edge-triggered + deduped. No third-party egress beyond Telegram.
+7. **Multi-machine posture:** Money truth is SINGLE-WRITER by design in B (the whole cap on one PIN-designated metered-lease machine; FD-20); the gate self-fences (`lease-liveness-unconfirmed`) on a staleness window pinned shorter than the mesh-death threshold, so a partitioned old holder is $0-fenced before any reclaim can be offered — dual money authority structurally impossible. Caps view: committed figures are holder-known; non-holder reads proxy to the holder (wired when the pool read lands; in B-single-machine the local read IS the holder read, stated in the response). Topic-creation authority follows the SERVING lease (exists in every topology). The ledger/caps files are machine-local BY DESIGN on the designated holder; Increment D replicates slices, not files.
+8. **Rollback cost:** Config-flag revert (dark) with zero data migration; ledger/caps files remain as inert audit history. A wrong booking can never be silently edited (append-only) — corrective action is a new row + the audit trail, never a rewrite.
+
+## Phase 5 — Second-pass review
+
+Required (money gate = "gate" class). Independent audit performed via a CROSS-MODEL reviewer — the gemini CLI (this build ran as a fork that cannot spawn subagents, so the skill's reviewer-subagent step was satisfied with a cross-model independent audit instead, which is stronger independence than a same-model subagent; codex is not installed on this machine and pi's non-interactive mode wedged on file attachments). Review scope: this artifact + `MeteredSpendGate.ts` in full, with the ledger/caps-store/plan-store contracts summarized; questions posed: fail-closed completeness, reporting-side reachability into the gate, Bearer-level money authority, signal-vs-authority compliance.
+
+**Reviewer verdict:** `VERDICT: Concur with the review` (gemini, 2026-07-08)
+
+## Self-action convergence (unbounded-self-action — closure: guard)
+
+This change adds two self-triggered cadences, both registered as convergence models in `src/testing/selfActionRegistry.ts` and proven to settle by `tests/unit/self-action-convergence.test.ts` (the ratchet — enforcement: ratchet):
+- **Reserve-expiry sweep** (`metered-reserve-expiry-sweep`): the idempotent terminal state machine IS the brake — an expired reserve can never re-expire and the sweep creates no reserves, so the steady-state emission bound is the finite stale pool (per-target 1, ever).
+- **Stale-price alert** (`spend-stale-price-alert`): the 24h edge latch is the brake — a declared **Eternal Sentinel** with a 24h rate floor (stale pricing changes money ADMISSION behavior, so the alarm must re-arm daily while the condition persists; never a flood).
+
+## No-deferrals accounting
+
+Work sequenced to later PRs in this increment train (Layer 1c capture/reconciliation, Increment C channel abstraction + full emitter set, amortized-subscription display, scheduled web-research price checks) is tracked under the durable commitment CMT-1929 <!-- tracked: CMT-1929 --> and enumerated in `.instar/plans/money-increment-b-brief.md`; nothing in THIS PR's claimed scope is partial.