docs(plan): anchor the byte budget to the delivered hooks and real boundaries

Three audit rounds against the post-035 tree rewrote the stale halves of
the observability plan: registrations become named adapters over the hook
shapes that actually shipped, the config field lands on /api/settings
because /api/config PUT is disabled, and the usage 'other' bucket must
bound the per-day model maps as well as the top-level one. The phase also
absorbs three verified external findings as pre-work — the unbounded
snapshot retry, stub-before-resident demotion, and the unwired GCP expiry
sweep — with the persistence follow-up contract locked to one bounded
same-path pass at shutdown.

Author: lidge-jun

devlog/_plan/260801_zero_leak_state_stores/040_app_bytes_observability.md

@@ -19,18 +19,32 @@ water counters but never evicted by this budget. Their hard admission is owned b
 
 ## Current code and anchors
 
-- `src/server/management/system-routes.ts:1-31` documents scalar/privacy constraints.
-- `src/server/management/system-routes.ts:33-95` assembles process memory,
+- `src/server/management/system-routes.ts:1-30` documents scalar/privacy constraints.
+- `src/server/management/system-routes.ts:35-97` assembles process memory,
   `responseState`, inspector counters, watchdog, and active-turn scalars.
-- `src/responses/state.ts:371-408` is an existing observe-only retained-store seam.
+- `src/responses/state.ts:640-695` is the observe-only retained-store seam
+  (`responseStateMetrics()` — resident/stub/tombstone counts, payload bytes, spill
+  counters from 010). It does NOT yet expose `evictableBytes`, `pinnedBytes`, or the
+  oldest-resident timestamp; this phase adds a resident-only snapshot/eviction API
+  (see the continuation pre-work section below).
 - `src/server/memory-watchdog.ts:53-60,102-155` owns a separate warn-only RSS/native
   watchdog with a 360-sample bounded ring; it does not manage app-owned state.
 - `src/types.ts:531-725` contains the top-level `OcxConfig` runtime fields.
-- `src/config.ts:703-733` begins the Zod config schema and reaches adjacent scalar
-  fields; write-time validation follows
-  the existing positive-integer helpers at `:530-550`.
-- `src/server/index.ts:300-316` starts process-wide memory/scheduler singletons.
-- `tests/memory-watchdog.test.ts:162-233` pins the current endpoint scalar shape.
+- `src/config.ts:739-748` begins the Zod config schema; positive-integer helpers are
+  at `:566-585`. Load-time degradation and write-time rejection are SEPARATE
+  boundaries: the schema rule degrades malformed persisted edits to the default, and
+  `validateConfigCandidate` (`src/config.ts:1438-1444`) rejects invalid candidates.
+  The actual MANAGEMENT boundary is `/api/settings` PUT
+  (`src/server/management/config-routes.ts:74-76,192-227`) — full `/api/config` PUT
+  is disabled — so this phase adds `appOwnedMemoryBudgetMb` to `/api/settings`
+  GET/PUT: the PUT validates the integer 64..4096 range, persists, then calls
+  `configureAppOwnedMemoryBudget` + `enforceAppOwnedMemoryBudget` synchronously.
+  Tests extend `tests/settings-stream-mode.test.ts`.
+- `src/server/index.ts:264-273,311-317` starts process-wide singletons: state
+  reconciliation at 266/273, watchdog at 316, state-store sweeper at 317. The
+  app-owned registrations + first enforcement run belong beside the sweeper start.
+- `tests/memory-watchdog.test.ts:162-236` pins the current endpoint scalar shape
+  (11 responseState scalars, no appOwnedBytes yet).
 
 ## Config decision
 
@@ -112,7 +126,20 @@ store as zeros; it never invokes `evictOldest()`.
 
 ## Retained-store registrations
 
-Register hooks delivered by 010/020/035 and existing owners:
+Register hooks delivered by 010/020/035 and existing owners. The delivered 035 hook
+shapes use `entries` (not `count`) and omit pinned/evictable fields, so each
+registration is a NAMED ADAPTER in `app-owned-memory` registration code mapping the
+owner hook onto `RetainedStoreSnapshot` (rings: `evictableBytes = bytes`,
+`pinnedBytes = 0`). Delivered hooks:
+
+- `debugBufferMetrics` / `evictOldestDebugEntryForBudget` (`src/lib/debug-log-buffer.ts:65-70`)
+- `injectionBufferMetrics` / `evictOldestInjectionEntryForBudget` (`src/lib/injection-debug-log.ts:43-48`)
+- `claudeInboundDebugMetrics` / `evictOldestClaudeInboundForBudget` (`src/claude/inbound-debug.ts:155-160`)
+- `crashRingMetrics` / `evictOldestCrashTraceForBudget` (`src/lib/crash-guard.ts:277-282`)
+- caches: `src/adapters/anthropic-image-normalize.ts:216-235`,
+  `src/vision/index.ts:119-133`, `src/adapters/google-antigravity-replay.ts:220-247`
+- blobs: `src/adapters/cursor/native-exec.ts:84-134,396-421` (provenance/pin classes
+  map directly onto pinned/evictable)
 
 | Category | Store ids | Demotion rule |
 |---|---|---|
@@ -123,11 +150,61 @@ Register hooks delivered by 010/020/035 and existing owners:
 
 The request-log owner (`src/server/request-log.ts:150-154,218-246`) must add per-entry
 UTF-8 byte accounting and a centralized oldest delete. Normalize individual retained
-diagnostic strings per 035, but preserve retry/failover attempt structure.
+diagnostic strings per 035, but preserve retry/failover attempt structure. The
+current mutation anchor is `src/server/request-log.ts:244-246` (push/shift only, no
+byte hook yet).
 
 Model cache and usage summary values receive owner-local byte accounting before they can
 register. Usage summary overflow aggregates excess model cardinality into an `other`
 bucket without dropping token/cost totals; it is not permissible to delete totals.
+Current owners: `src/codex/model-cache.ts:43-44,133-135` (unaccounted model arrays)
+and `src/server/management/logs-usage-routes.ts:82-86,207-211` +
+`src/usage/summary.ts:415-417` (unaccounted summaries, unbounded model breakdown —
+the `other` bucket does not exist yet and is created in this phase). The `other`
+contract covers BOTH the top-level `models` aggregation (`src/usage/summary.ts:415-417`)
+AND every per-day `days[].models` breakdown (`src/usage/summary.ts:290-337`), each of
+which independently builds an unbounded provider/model map; unique request counts,
+attempts, tokens, and cost are preserved in the bucket wherever applicable.
+
+## Continuation pre-work (fold-in of verified external findings)
+
+Three verified defects sit exactly on this phase's continuation/sweeper seam and are
+repaired here BEFORE the budget work builds on them:
+
+1. **Bounded snapshot retry (state.ts:448-487, VALID High).** `persistNow()` loops
+   until `revision === stateRevision`; sustained traffic keeps it spinning and
+   `flushResponseState()` (:511-518) never settles at shutdown. Fix: cap the rewrite
+   loop at 4 attempts. If the final write is still revision-unstable, schedule a
+   follow-up flush and DO NOT drain `pendingSpillUnlinks` — only a revision-stable
+   snapshot may authorize unlinking superseded spill generations (:488-493).
+   Follow-up contract: the follow-up retains the SAME captured `path` (the guard at
+   :501-508 against recomputing `snapshotPath()` stays intact). Background
+   persistence uses an unref'd timer. Explicit `flushResponseState()` (shutdown path,
+   `src/server/lifecycle.ts:164-166`) AWAITS one bounded same-path follow-up pass
+   after the cap; if that pass is still unstable it returns with a best-effort
+   snapshot and intact pending unlinks — shutdown is never blocked indefinitely.
+   Test: revision churn during atomic write settles within the bound and leaves
+   pending unlinks intact until a stable snapshot lands.
+
+2. **Resident-first demotion (state.ts:539-556, VALID High/data loss).** The RAM-cap
+   loop deletes the oldest spill stub/tombstone (including its durable spill file,
+   :131-143) whenever it precedes a resident. Fix: scan for the oldest RESIDENT and
+   demote it first; delete stubs/tombstones only when no resident remains and
+   bounded metadata alone exceeds the cap. This also makes the 040 continuation
+   `evictOldest()` callback resident-only by construction.
+   Test: mixed older-stub/newer-resident state demotes the resident and keeps the
+   stub's durable spill file on disk.
+
+3. **GCP ADC expiry sweep unwired (VALID Medium).** `sweepExpiredGcpAdcTokens()`
+   (`src/lib/gcp-adc.ts:71-80`) is exported but `STATE_STORE_REGISTRATIONS`
+   registers only `reconcileGcpAdcTokens` (`src/lib/state-store-registrations.ts:97`).
+   Wire the expiry sweep into the registration's TTL callback. Test: expired ADC
+   token is swept by the periodic pass.
+
+A fourth external claim (sweeper partial-pass fence dropping newly-added-owner
+writes) was audited INVALID against current source — every fenced writer also
+accepts keys in the owner's live-key set — but a partial-failure/live-key regression
+test is added to pin that property.
 
 ## Enforcement algorithm
 
@@ -166,7 +243,7 @@ Edge contracts:
 
 ## `/api/system/memory` payload
 
-At `src/server/management/system-routes.ts:74-95`, add:
+At `src/server/management/system-routes.ts:76-97` (beside `responseState` at :90), add:
 
 ```ts
 appOwnedBytes: appOwnedBytesSnapshot(),
@@ -216,6 +293,16 @@ Add `tests/app-owned-memory.test.ts`:
 - `translator and serialized-tail observations never invoke budget eviction`
 - `budget decrease enforces synchronously in the documented order`.
 
+Continuation pre-work tests (extend `tests/responses-state.test.ts` and
+`tests/state-store-sweeper.test.ts` / `tests/gcp-adc.test.ts`):
+
+- `persistNow settles within the bounded rewrite attempts under revision churn`
+- `unstable final snapshot defers spill unlinks until a stable snapshot`
+- `RAM cap demotes the oldest resident before deleting any older spill stub`
+- `stub-only over-cap state still deletes bounded metadata oldest-first`
+- `expired GCP ADC token is removed by the periodic sweep registration`
+- `partial reconcile failure keeps live-key writes accepted for new owners`.
+
 Extend `tests/memory-watchdog.test.ts`:
 
 - `GET system memory includes privacy-safe appOwnedBytes scalars`
@@ -226,13 +313,16 @@ Config tests:
 
 - `appOwnedMemoryBudgetMb defaults to 256 MiB`
 - `accepts integer bounds 64 and 4096`
-- `rejects management writes below above fractional or nonnumeric values`
+- `settings PUT rejects below/above/fractional/nonnumeric budget values`
+- `settings PUT applies a valid budget change synchronously through enforcement`
 - `malformed persisted value degrades to default without dropping providers`.
 
 Run:
 
 ```bash
 bun test tests/app-owned-memory.test.ts tests/memory-watchdog.test.ts tests/config.test.ts
+bun test tests/responses-state.test.ts tests/state-store-sweeper.test.ts \
+  tests/gcp-adc.test.ts tests/settings-stream-mode.test.ts
 bun run typecheck
 bun run test
 bun run privacy:scan
@@ -251,4 +341,9 @@ bun run privacy:scan
 - No pin override for live remote Cursor blobs.
 - No path/id/account/provider/model/prompt/tool/error content in observability.
 - No 030 dependency or accounting hook; expiration sweeping stays independent.
+  (Exception: the GCP expiry-sweep wiring above touches the 030 registration table
+  because the defect lives there; it adds no accounting coupling.)
 - No GUI redesign beyond consuming the additive payload if desired in docs sync.
+
+Docs sync for the new config field covers English AND the translated configuration
+references (`ja`, `ko`, `ru`, `zh-cn`).