docs(spec): section 26 prover loop spawn, four controls, kill switch (#3265)

[MichaelTaylor3d]

What

Adds SPEC.md §26 — Reward prover loop: the spawn, the four controls, and the kill switch (DIG-Network/dig_ecosystem#3265), plus a one-sentence cross-reference in §5. Docs only: no source, no dependency, no version change.

Written against tip 69c793a7 and the published dig-rewards-coin 0.8.0 / dig-rpc-protocol 0.12.0 sources. Every clause either cites the code that already satisfies it or is marked (target) and listed in §26.14 with the ticket that lands it.

The locked shape, in one paragraph

Spawn from serve_with_shutdown right after the claim spawn, through a decide → spawn_if → from_config seam mirrored from rewards_claim/driver.rs (shape only — the claim config's default_enabled() == true is explicitly the trap, §26.3 cl. 6). Config is <state_dir>/rewards-prover.json with exactly three keys: enabled (default false, under a const _: () = assert! so the default cannot flip silently), mode (dryRun default | live), standard_fee_mojos (default 0 = refuse; above 0.1 XCH = refuse, never clamp). The node never writes the file. Spawn prints ONE warn line with the §6.3-derived figures (24 bundles/day, 192 actions/day, FeeBudget::daily_limit_for(fee), 0.24 XCH/day = 87.6 XCH/year at 0.01 XCH, 192 removals/day → ~1.3 days, 96 churns/day → ~2.6 days) per funded distributor. Dry-run is a DryRunChainPort decorator that logs and never calls the inner writes, runs the scheduler against a scratch bound store, and is log-only (0.12.0 cannot carry a mode). The kill switch is two tokio tasks on one watch channel: a switch task that ticks heartbeat_tick, re-reads enabled + <state_dir>/rewards-prover.STOP every 60 s and flips the sender; a cycle task that select!s the receiver against the cycle so a wedged cycle is dropped immediately — no RPC method. Stopped is durable until process restart. A cycle whose seam is absent faults (CycleOutcome, never advances last_cycle_completed_at); while the inventory is undetermined dig.getRewardProverStatus answers Half::NotConsulted; money counters are chain-derived, never local. Live mode is refused until PROVER_LIVE_MODE_RELEASED is flipped by a one-line PR citing the composed-system gate, which follows #3292, #3421, #3422, #3423.

Hard truth the section states

At this tip a spawned loop faults ChainSourceUnavailable on every cycle (chain_port.rs:77-97). The controls are verifiable now; distribution is not. The section orders the port work AFTER the controls and makes "spawns, reports Idle, distributes nothing" unrepresentable (§26.9 cl. 9).

Decider questions (for the orchestrator, not settled here)

1. Undetermined inventory on the wire — Half::NotConsulted (locked, node-side only) vs a whole-call error vs a new wire field (protocol lane).
2. Dry-run write bounds — scratch in-memory store seeded from the live store (locked) vs advancing the live bounds.
3. PROVER_LIVE_MODE_RELEASED tripwire — a code constant flipped only by the gate verdict (locked).
4. First cycle immediately at spawn (locked; the claim loop waits one cadence) — changes the periodicity test from 0→1→2 to 1→2→3.

Verification

• git ls-files --eol SPEC.md → LF in/out; 15 new headings; 21 (target) markers; cross-reference at §5 line 1095.
• No cargo invoked (docs only).

Refs: DIG-Network/dig_ecosystem#3265, #3274, #3261, #3292, #3421, #3422, #3423.

🤖 Generated with Claude Code