docs: build log for round 1 of 3

This commit is contained in:
caelum0x 2026-10-23 20:07:43 +03:00
parent 3376017032
commit 2bbe01151f

60
BUILD-LOG-2026-10-23.md Normal file
View File

@ -0,0 +1,60 @@
# Build Log — 2026-10-23
## Round 1 of 3
Scope: highest-priority remaining backlog items from the deep-build/threat-model/strategy pass. Went item by item, building each fully (real handler logic, real data model wiring, real end-to-end flow), verifying each live against the actual demo stack (not just unit tests), before moving to the next.
All 12 backlog items from this round's brief are now done, plus 2 bugs found and fixed along the way. 12 commits on `main`, nothing pushed (no instruction to push this round; repo's established pattern is plain commits to `main`).
### 1. [fix] Bridge-grant holds now release on repayment (`700b6e8`)
`services/card-issuance/internal/bridge/service.go`'s HOLD reference changed from `bridge:<hold_id>` to `bridge:<deposit_id>:<hold_id>`, so `services/ledger-core/src/ledger.rs`'s `mark_deposit_received_with_entry` can find and atomically RELEASE every outstanding bridge HOLD tied to the deposit that just settled, in the same WAL frame as the credit. AGENT-DESIGN.md rule 3 ("unless the prior grant was fully repaid") is no longer dead code. Mirrored into audit-log too. Verified via the existing `TestRationBridgeFunding_VelocityCapAllowsAfterRepayment` test and live, later in the round, via the circuit-breaker fallback actually granting a second time after repayment.
### 2 & 3. Tenant-scoped authorization everywhere, including ledger-core itself (`eef5f6b`, `ed0dbe1`, `a515e13`)
- `proto/auth.proto`: added `is_operator` to API keys/JWTs.
- `services/cli`, `services/tui`, `services/agent` each mint an operator-scoped credential at startup and attach it to every gateway call. `RATION_GATEWAY_REQUIRE_TENANT_AUTH` now defaults to `true`.
- New `services/gateway/internal/cardtenant`: resolves `card_id` → `tenant_id` so `GetCard`/`AdjustCardLimit` are no longer unscoped.
- New `tenantauth.StreamServerInterceptor`: `StreamActivity` can no longer be subscribed to with an empty (all-tenants) `tenant_id` by an unauthenticated/non-operator caller.
- **The big one**: `services/ledger-core/src/tenantauth.rs` + `src/authclient.rs` — ledger-core now verifies every tenant-scoped (or operator-only) caller's own credential directly, closing THREAT-MODEL.md's "the biggest one" sub-gap (cli/tui/agent/gateway/card-issuance/webhook-ingestion/tenant-registry all dial ledger-core directly, bypassing gateway's tenantauth entirely). `RATION_LEDGER_REQUIRE_TENANT_AUTH` defaults to `true`; ledger-core refuses to start if that's true with no `AUTH_GRPC_ADDR` reachable. Every direct ledger-core caller (gateway, card-issuance, webhook-ingestion, tenant-registry) got a new `internal/authclient` to mint its own operator credential.
- Verified live: full seed → simulate-deposit → agent poll → bridge-funding cycle, zero `Unauthenticated`/`PermissionDenied` anywhere in any service's logs.
### 4. TUI "Agent Decisions" tab (`7bb72db`)
New 5th tab (`view/decisions.go`), fetches every tenant's `ListAgentDecisions` each refresh, merged newest-first. Extracted the CLI's `sanitizeControlChars` into `pkg/textsanitize`, applied to every LLM-authored field this tab renders (sanitize-then-truncate, not the other way, so a truncated string can't still carry an unterminated escape).
### 5. `ration audit-check` (`f61049d`)
New CLI subcommand cross-checking ledger-core's own `ListEntries`/`ListAgentDecisions` counts against audit-log's mirrored `ListRecords` count, per tenant, fully paginated both sides. Exits nonzero on divergence beyond `--tolerance`. Wired into `docs/RUNBOOK.md`. Verified live: 18/18 tenants OK, exact count matches.
### 6. Judge-facing live web dashboard (`cda90fc`)
New `gateway.proto` RPC `GetDashboardSnapshot` (aggregates tenant headroom + recent decisions server-side). Three new `httpapi` routes: `GET /v1/dashboard` (one self-contained HTML/CSS/JS page, zero external deps), `GET /v1/dashboard/snapshot` (polled JSON), `GET /v1/dashboard/activity/stream` (true SSE). Deliberately credential-free for the judge; the SSE route presents gateway's own operator credential specifically (not the caller's), so the existing `/v1/activity` route's security posture is unchanged. Verified live: real snapshot data, a real simulated-deposit event delivered over SSE end-to-end.
### [fix] `findRelevantLateDeposit` matches real data (`0f0de9b`)
Found while building the above: this function filtered on a deposit `status` field nothing on ledger-core's write path ever sets to `Late` — so bridge funding declined every genuinely-late deposit, always, against a real ledger-core. Every unit test happened to use fixtures that also satisfied the real time-based definition, masking it. Fixed to compute lateness the same way ledger-core's own `list_late` does. Documented in `docs/RUNBOOK.md`.
### 7. Webhook correlation by reference, not amount alone (`5a22085`)
`RecordDeposit`'s `external_ref` now carries through to the Airwallex payload's `reference` field; `handleTransactionCreated` prefers an exact reference match before falling back to the `(tenant, amount, oldest)` heuristic. Also recovered a dangling reference to `matchDepositByReference`/`matchDepositByAmountHeuristic` that had no implementation — added `matching.go`.
### 8 & 9. Covered by items 2/3 above (cardtenant resolver, StreamActivity scoping).
### 10. LLM circuit breaker (`9c859de`)
New `services/agent/internal/llm/breaker.go`: trips after N consecutive failures within a rolling window, short-circuits to `ErrCircuitOpen`, one half-open trial before fully closing. `internal/loop.Runner` treats a tripped breaker as "execute the deterministic hard-rule envelope directly" (same tool-handler code path, canned text) rather than skipping the tick. **Verified live**: with no `ANTHROPIC_API_KEY` configured, the breaker tripped after 3 failures and then executed real bridge-funding grants (HOLD entries landing on ledger-core, held balance increasing) via the fallback path.
### [fix] Velocity cap no longer blocked by a grant that never executed (`3376017`)
Found live while verifying the breaker fallback above: the unconditional "envelope pre-check" decision recording (before the LLM is even attempted) got counted by `hasOpenGrantWithinWindow` as "an open unrepaid grant" even when the real tool call never ran — permanently velocity-capping a deposit whose first attempt merely failed transiently. Fixed with a `wasActuallyGranted` check (only a decision snapshot containing `granted_minor_units`, which only a real executed grant's snapshot has, counts).
### 12. Automated dev-CA cert rotation (`9dca6d1`)
New `scripts/rotate-dev-ca.sh` + `services/auth/cmd/issue-service-cert` client for `IssueServiceCert`. Point `auth`'s `AUTH_CA_CERT_FILE`/`AUTH_CA_KEY_FILE` at the same static dev CA every service already trusts, and rotation issues fresh leaves against that identical root — no new CA to redistribute. **Verified live**: generated a CA, started `auth` against it, rotated all 10 service identities, confirmed new serials, matching keys, and `openssl verify -CAfile` passes.
### 11. Encryption at rest — WAL done, SQLite column-level NOT done (`cb87e97`)
New `services/ledger-core/src/wal_crypto.rs`: AES-256-GCM, wired into `append_and_commit`/`replay_wal_into_index` so every WAL frame is ciphertext before `wal_ffi::Wal::append` ever sees it — zero changes to the C WAL's frame format/CRC/recovery logic, since that layer already treats a payload as an opaque `&[u8]`. Opt-in via `RATION_LEDGER_ENCRYPTION_KEY`; disabled (unchanged plaintext behavior) by default. **Verified live**: the on-disk WAL file is genuine ciphertext (not valid JSON, no plaintext tenant names), a full seed/deposit/bridge-funding cycle runs correctly against an encrypted ledger, two new tests prove a real restart-and-recover round trip and loud failure on a wrong key.
**Remaining from item 11**: column-level encryption of SQLite's sensitive free-text fields (`deposit.external_ref`, `ledger_entries.reference`/`memo`, `agent_decisions.trigger`/`rationale`/`policy_snapshot_json`) was planned but not implemented this round — stopped short of it after a transient disk-full event on the build machine (unrelated to this change; recovered on its own) made me unwilling to start another multi-file refactor of the ledger's core read paths without full headroom to verify it thoroughly. The WAL is the system's actual source of truth and is now fully encrypted; the SQLite index is explicitly "a rebuildable, queryable index over it" (see `lib.rs`'s own doc comment) — a real but secondary exposure if the SQLite file leaks in isolation. Real, scoped next step for round 2: thread `Option<&wal_crypto::Key>` through `deposit.rs`/`agent_decision.rs`/the `ledger_entries` functions in `ledger.rs`, encrypting only those free-text columns (never `tenant_id`/amounts/timestamps/enums, which every query filters or sorts on).
## Owner-only steps hit this round
None. Every item was closeable without a payment, 2FA, or console-only step.
## Verification method
Every feature was verified by actually running `scripts/run-demo.sh` (or a targeted subset of the stack) and exercising the real flow via `./bin/ration`/`curl`/`openssl`, reading the resulting service logs and ledger state — not by adding automated tests alone (though unit/integration tests were added or updated where the existing codebase's own convention already does that, and all of them pass: `cargo test` 44/44 in ledger-core, full `go test ./...` green across every Go service touched).
## Totals
- 12 commits.
- ~20 files touched or added across ledger-core (Rust), gateway/cli/tui/agent/card-issuance/webhook-ingestion/tenant-registry/auth (Go), proto, infra scripts, and docs.
- 2 real bugs found and fixed beyond the assigned backlog (late-deposit status-vs-time mismatch; velocity-cap false-positive from an unexecuted grant).