Drive observe_disk and observe_chain from events, keeping the timer as the backstop

[MichaelTaylor3d]

Task

observe_disk and observe_chain must be event-driven, with the 10-minute timer kept as a backstop — not replaced by events.

Stated by the user 2026-08-31: "the observe_disk and observe_chain need to be event based, only using a timer as backup".

This does NOT contradict the existing rationale — read it before building

mirror/mod.rs:20-22 says:

"The start-up reconcile is the reliable path, not the file watcher. A watcher's event is exactly what a crash loses; a scan at start-up re-derives the whole answer from two observations that survive anything."

That rejects a watcher as the correctness mechanism. The user is asking for a watcher as an accelerant over a scan that stays. Those are the same position: events for latency, the scan for correctness.

So the invariant is: no behaviour may depend on an event arriving. Every event is a hint that lets the pass run sooner; the periodic scan and the start-up reconcile remain the guarantee, unchanged. If every event were dropped forever, the node must still converge — which is exactly what #464 requires, and this ticket must not weaken it.

Do not delete the timer. Do not lengthen it to "compensate" for having events — that trades the correctness floor for responsiveness, which is backwards.

What the events are

Disk: a capsule landing or being removed under the cache. Note the pass already consumes debounced presence deltas (runner.rs:243-245, server.rs:2742/2816/2821) with a settling window — check whether an event source already exists and is merely not wired to the mirror pass, before adding a watcher. Reuse before building (§2.0).

Chain: a new peak, or a coin-state update for the operator's puzzle hash. dig-node already runs a Chia light client with peer subscriptions and there is a chia-block-listener crate in the tree — measure what is already subscribed before adding anything. A mirror pass triggered on every new peak (~18.75s) would be far too often; see amplification below.

The two things that will go wrong if unattended

1. Amplification. A burst of capsule writes, or a peak every ~19 seconds, must not produce a pass per event. Each pass reads chain and may spend money. Coalesce: a settling window like the existing SETTLING_WINDOW_MS (30s) and a minimum interval between passes, so N events in a window cause ONE pass. State the chosen bound and what happens when events arrive during a pass.
2. A wedged pass. If a pass hangs, events must not queue unboundedly behind it, and the backstop timer must still fire afterwards. Passes must not overlap — confirm the current loop's guarantee and preserve it.

Also settle, because it is a real fork

Should a chain event trigger a pass at all, or only refresh the observation? A create is decided from disk presence; chain events mostly matter for reclaim (an epoch rolled over, a coin was spent by someone else) and for resolving landed spends. Triggering a full pass on chain activity may be more than is wanted. Decide, and say why (§1.10 — settle the shape before building).

Acceptance

• A capsule appearing on disk causes a pass well before the next timer tick, proven by a test that measures the delay rather than asserting a pass happened.
• Every event source can be silenced and the node still converges — the The mirror lifecycle must self-heal: every store gets a coin, every orphaned coin is spent, even after a failed attempt #464 convergence tests must pass with events disabled. This is the assertion that keeps events an accelerant rather than a dependency.
• A burst of N events in one settling window produces exactly one pass, asserted on the count.

Parent

Lifecycle #412 · self-healing sibling #464 · epic https://github.com/DIG-Network/dig_ecosystem/issues/3166

[MichaelTaylor3d]

Lane open: worktree C:/tmp/worktrees/dn-event, branch loop/mc-event, draft PR #470, base 95c9582.

Measurement of what already exists (§2.0, before building):

• Disk — no event source exists. The pass's disk observation is lifecycle::observe_disk → Node::cache_list_cached() (lifecycle.rs:755), a directory scan. There is no capsule-cached broadcast/watch channel anywhere in dig-node-core or dig-node-service, and no filesystem-watcher crate is in the workspace (notify is absent from Cargo.lock). The debounced presence deltas the ticket points at (runner.rs:243-245) are computed from consecutive scans by PresenceTracker; they are a settling filter over polled state, not an event source. So a watcher is genuinely new, and adding one is not a rival implementation.
• Chain — nothing subscribed, and chia-block-listener is not a dependency of this repo at all (zero hits for chia_block_listener in crates/). Peak is read from the wallet replica's sync_state, polled.

Chain-event decision: a chain event will NOT trigger a pass. Reasons: (1) creates are decided from disk presence, so chain activity cannot make a create newly correct; (2) at ~18.75s per peak this is the largest amplification source on a path that spends money, and each pass reads chain; (3) the reclaim triggers the ticket names — epoch rollover — are wall-clock, already derivable locally from current_epoch_now(), not chain events; and (4) reclaim latency is already bounded by one round (10 min), which is short relative to an epoch. Subscribing to peaks would therefore add a new integration to obtain the one trigger we most want to suppress. Chain stays observed inside the pass, on the timer.

Next: the coalescer + watcher in mirror/events.rs, then the select! wiring in spawn_mirror_passes.

[MichaelTaylor3d]

Design settled and implemented; verification in progress on #470.

The coalescing bound.

• QUIET_PERIOD_MS = 5_000 — an observing wake fires once disk writes have been quiet for 5s. A debounce, so copying a large .dig in causes one pass at the end rather than one per write event.
• MIN_EVENT_PASS_INTERVAL_MS = SETTLING_WINDOW_MS (30s) — a floor on how often events may cause a pass. Derived, not picked: a pass can only ACT on a change once PresenceTracker has seen it hold for a settling window, so two event-driven passes closer than one window cannot reach a decision the later one would not have reached alone. The quiet period alone does not bound this — writes arriving just slower than 5s quiesce every time and would otherwise wake a pass every ~6s indefinitely — so the floor is load-bearing, and there is a test that fails if it is removed.
• Two wakes per burst, and it terminates. PresenceTracker stamps since_ms at the first observation, not at file creation, so a single wake could only ever RECORD an appearance. One burst therefore yields an observing wake (quiet + 5s) and one settling wake a settling window later, which does not re-arm. N events in a window produce exactly one of each, never N.
• Events during a pass collapse into the single owed wake — the coalescer holds one instant, not a queue — so a wedged pass cannot be followed by a burst of drained passes. Asserted.
• Latency: a hand-copied capsule goes from up to two round timers (~20 min, because the first round only stamps it) to ~35s, with no figure in the settling contract changed.

Passes still cannot overlap. The pass loop is one sequential task; wait_for_next_pass computes the MIRROR_PASS_INTERVAL deadline once on entry and every return happens at or before it, so an event can only ever LOWER the next wake instant, never postpone it. That is what keeps the timer a backstop rather than a fallback, and it is why the timer is neither deleted nor lengthened.

Silencing. watch_capsule_cache returns Option; None (unsupported filesystem, platform limit) is a latency loss and nothing else, and wait_for_next_pass then waits on the deadline alone — the exact behaviour that shipped before this module. Asserted by silencing_every_event_source_leaves_the_timer_untouched, which also pins MIRROR_ROUND_LENGTH_MS at 10 minutes so a later edit cannot lengthen the backstop to compensate for having events.

No runner.rs change is needed. The event source sits entirely outside the pass: it changes only when spawn_mirror_passes waits, so PassRunner, MirrorEffects, observe_disk and observe_chain are untouched. Nothing in the #464 lane's surface is edited.

Note: this machine hit ENOSPC mid-build (C: at 0 bytes free). Reclaimed 2.4 GB from this lane's own target/debug/incremental only; no other repo touched.

[MichaelTaylor3d]

Implemented and verified. Draft PR #470, head ed2dfc4, one squashed commit on base 95c9582. Staying DRAFT for the gate round.

Acceptance, against the three criteria:

1. A capsule appearing causes a pass well before the next timer tick, proven by measuring the delay. — a_capsule_appearing_wakes_a_pass_far_inside_the_round_timer asserts the delay equals QUIET_PERIOD_MS and that delay * 20 < MIRROR_ROUND_LENGTH_MS. The watcher itself is proven against a real temp directory by a_file_appearing_signals_well_before_the_round_timer, which also measures elapsed time rather than asserting a signal eventually arrived. No tokio::time::pause() — a paused clock auto-advances past the wall-clock interval under test.
2. Every event source can be silenced and the node still converges. — watch_capsule_cache returns Option, and wait_for_next_pass then waits on the round deadline alone, which is the behaviour that shipped before this module. silencing_every_event_source_leaves_the_timer_untouched asserts an unfed coalescer owes nothing over three rounds AND pins MIRROR_ROUND_LENGTH_MS at 10 minutes, so a later edit cannot lengthen the backstop to compensate.
3. A burst of N events in one settling window produces exactly one pass, asserted on the count. — a_burst_of_events_in_one_window_produces_exactly_one_observing_pass records and drains 200 events in the same loop, as they arrive, and asserts passes == 1.

Evidence. cargo test -p dig-node-service --lib mirror:: → 113 passed, 0 failed (7 new in mirror::events; count checked, not just exit status). cargo clippy -p dig-node-service --lib --all-features -- -D warnings clean. Revert-proof on a committed tree, each guard disabled ALONE — floor → 0, quiet period → 0, settling wake re-arms forever — each failing exactly its own test and nothing else (6 passed / 1 failed, three times).

Diff scope, measured against the merge base: 7 files. mirror/events.rs (new), mirror/mod.rs, server.rs, SPEC.md §25.5, Cargo.toml (0.202.0), crates/dig-node-service/Cargo.toml (notify = "8"), Cargo.lock. runner.rs, resolve.rs and spend_audit.rs are untouched — #464 lane's surface is not entered, and no runner.rs change is required: the event source changes only when spawn_mirror_passes waits, so PassRunner, MirrorEffects, observe_disk and observe_chain keep their exact signatures and semantics.

SPEC.md §25.5 already specified "an optional watcher as an accelerator — never the reverse"; its pending note claiming there is no watcher was stale and is corrected, and the four bounds (deadline is a ceiling events may only lower, coalesce-never-queue, two wakes per burst with no re-arm, floor of one settling window) are now normative, along with the no-chain-trigger decision.

Note for the orchestrator: origin/main has moved since 95c9582; the branch needs a rebase before merge (§2.4 strict=true). Not done here, since sibling lanes are live in this repo.