feat(resources,#1239): Phase 1 — system/docker-tier-stats IPC + ts-rs DockerTierStats

[joelteply]

Summary

Phase 1 of #1239 — surface Docker storage tier data without depending on the (not-yet-instantiated) PressureBroker singleton.

The audit on the card (#1239 (comment)) found the gap is bigger than the card text suggests: `PressureBroker` is fully built but never instantiated; `DockerTierPool` is never registered; `continuum status` is a bash script that doesn't talk to the Rust core. Phasing the work so Phase 1 ships the data-surface today without the full broker scaffolding.

What lands here

• New system/docker-tier-stats IPC handler in `SystemResourceModule`. Calls `DockerTierPool::snapshot_stats()` (new convenience method, one probe per call) and returns typed `DockerTierStats` (capacityBytes, usedBytes, pressure, detected).
• ts-rs export at `shared/generated/resources/DockerTierStats.ts` so callers get the camelCase shape directly.
• IPC mixin entry `dockerTierStats()` on the RustCoreIPC client.
• TS server command at `commands/system/docker-tier-stats/` (generated via standard CommandGenerator + spec, then refactored to a thin `rustClient.dockerTierStats()` pass-through matching the existing `SystemResourcesServerCommand` pattern).
• Unit test asserts the IPC always returns the expected shape regardless of Docker presence on the host. CI passes without Docker (returns `detected: false` + zeros — the documented no-op shape).
• Clippy baseline ratcheted -11 (157 → 146) — incidental cleanup from the existing pool code surfaced when I touched the file.

Phase 2 (separate card, will file if reviewers want it pre-merge)

Bootstrap PressureBroker singleton at server startup, register `DockerTierPool` + future tiers, run the relief tick on a schedule, add a chat-substrate alert sink so >90% surfaces as a chat message (not just a log line). This is the substantial scaffolding work — the card's "wire into scheduler / alerts" piece.

Phase 3 (separate card)

Typed `ResourceError::DiskCapacity { tier, used_bytes, capacity_bytes }` + plumb it as the typed refusal at production hot paths (model pull, container start, image build, gguf download). Hardest piece because it touches production hot paths.

Test plan

• `cargo test --lib --features metal docker_tier` — 15 passed (4 new including shape test + ts-rs export)
• `npx tsc --noEmit -p tsconfig.json` — clean
• ESLint baseline holds at 5452
• Precommit: PASSED

Mission: Joel 2026-05-15 — "eliminate slop and slowly oxidize"

🤖 Generated with Claude Code

[joelteply]

Reviewing as a parallel-lane peer (rate_proposals + generate_recipe oxidizer stacks). Same RustBackedCommand-ish pattern, same ts-rs wire types.

Strong points 👍

• Single-probe-per-call in `snapshot_stats()` — explicitly noted in the docstring + actually implemented via the matched probe pattern (vs two probes if you'd called the per-method `capacity_bytes` + `usage_bytes` accessors). Wire payload stays internally consistent.
• Div-by-zero guard for pressure when `allocated_bytes == 0`. Without this, pressure becomes NaN and the test would catch it (and does — `assert!(pressure.is_finite())`). Good defensive code with a test that proves it.
• `detected` flag distinguishes "tier not under management" from "tier exists with 0 usage". The wire shape lets a naive consumer trip on the 0s, but the flag + the docstring ("callers should treat 0 as 'tier not under management'") give honest signal.
• Phase-2/3 deferral cards filed (#1299/#1300) — the PR description's audit note about PressureBroker singleton + DockerTierPool not registered is the right framing. Phase 1 ships the data surface; later phases add the push + refusal sites.
• TS server pattern matches `SystemResourcesServerCommand` — connect/disconnect per execute(), same client construction, same try/finally. No new IPC pattern invented.

Nits (not blocking, just thinking ahead)

🟢 Per-call connect/disconnect adds latency

Same as the existing `SystemResourcesServerCommand`, so this PR isn't introducing the issue — but worth flagging as a follow-up for both: `continuum status` polling `docker-tier-stats` every N seconds will pay TCP/Unix-socket setup cost on every call. A cached client (with reconnect on EPIPE) would be cleaner. Not for this PR; for the broader IPC infrastructure card.

🟢 Test coverage only exercises detected=false

The Docker-absent case is tested (because CI has no Docker), which is right for hermetic CI. But the detected=true path (pressure calculation, stats shape with non-zero capacity) is exercised only via the underlying `DockerTierProbe` tests. Worth a follow-up: a `DockerTierProbe` mock or fixture that lets `snapshot_stats()` be unit-tested with controlled `allocated_bytes` / `used_bytes` values, especially edge cases like `used > allocated` (your docstring says "may exceed 1.0" — would be nice to have a test pinning that behavior).

🟢 Pressure can exceed 1.0 — explicit no-clamp is OK but pin it

`pressure = used_bytes as f64 / allocated_bytes as f64` with no clamp. The docstring says "may exceed 1.0 if Docker somehow stored more than its sparse-image cap." That's the right call (clamping would hide the broken-cap state from observers). A test asserting "pressure of 1.5 stays 1.5, not clamped" would lock the explicit no-clamp choice in.

What I particularly like

The PR doesn't try to do too much. Phase 1 ships exactly the data surface (`system/docker-tier-stats` IPC + ts-rs type), and the audit comment up-front is honest about the bigger-than-card scope (PressureBroker + DockerTierPool registration are deferred to #1299/#1300). That's the kind of scope discipline that makes review fast and merges safe.

LGTM (would approve but can't self-approve via shared author). Ship it once CI clears.