Mirror-coin lifecycle: the pass runner, the state surface, the DHT pointer, and the real-machine proof

[MichaelTaylor3d]

Task

Land the impure half of dig-node#377 step 4 — the pass RUNNER — plus steps 6–8, which the parent PR names as children rather than deferrals.

The parent (#377, PR #379) landed everything that can be decided without I/O: the planner, the presence debounce, the spend builders, the scoped signer + OperatorWallet, the §25.7 switch, and mirror::pass::decide — a pure function over PassInputs. What is left is the part that touches a chain, a wallet, a clock and a socket.

Context

• crates/dig-node-service/src/mirror/pass.rs — decide(&PassInputs) -> PassDecision is the whole decision. The runner's job is to GATHER PassInputs and EXECUTE PassDecision, not to re-decide anything.
• crates/dig-node-service/src/mirror/signer.rs — MirrorSigner::sign(&MirrorSpends, &RecordedSpend). Do not relax that signature. A RecordedSpend is obtainable only from SpendJournal::begin, which is what makes "every unattended spend is recorded" structural rather than conventional. If the journal is awkward to construct at bring-up, make construction work.
• SPEC.md §25.4 (pass order, reclaims first, fee = 0 fallback, in-flight suppression), §25.6 (DHT pointer + epoch rollover), §25.8 (the per-(store, root) state surface, still marked PENDING).
• crates/dig-node-service/src/mirror/pass.rs's BondState doc records a vocabulary divergence step 6 must reconcile: §25.8 gives withheld a NARROWER meaning (Relayed provenance) and names a reclaiming state the enum has no variant for. Reconcile at the interface; do not quietly rename the enum to match.

Scope — four pieces, in this order

1. The runner. Start-up reconcile + round tick (dig_constants::MIRROR_ROUND_LENGTH_MS) + debounced presence deltas. Observe the Held set and dig_mirror_coin::list; call decide; execute reclaims first, then creates; audit begin → sign → broadcast → confirm; a process end with no outcome resolves to unresolved.
2. Step 6, release-first: declare the §25.8 state method in dig-node-control-interface and publish 0.25.0 before the node adopts it, then serve it and add the dign verb (the §8.6 CLI-parity drift test will demand it). Unblocks Drive the out-of-funds OS notification: the decision is built and tested but has no caller dig-app#300 and Activity tab auditing all automated spends, plus an hourly OS notification when out of DIG/XCH dig-app#289.
3. Step 7: dig-dht 0.12.1 → 0.15, attach unverified_mirror_coin_id at crates/dig-node-core/src/seams/dig_peer/dht.rs:423, re-announce on epoch rollover. §2.4b binds and the cascade is measured from the lock, never from the caret — dig-dht 0.13.0 took dig-nat 0.21 as a breaking bump, so check the dig-peer / dig-download / dig-peer-selector lines before assuming this is one line.
4. Step 8 — the §2.6 acceptance, which is what closes the parent. A person on a real machine: fund the wallet with $DIG, serve a .dig, watch the coin appear (dign spends, coin id resolvable on chain at the epoch's required amount — the schedule starts at 1.000 DIG per (store, root)), delete the .dig, watch the collateral return. Not a green suite.

Evidence

Simulator (chia-sdk-test) e2e for piece 1: a bond created for a Held capsule, the capsule removed, the coin reclaimed, the full amount back, and the audit ledger showing the whole lifecycle. Then the real-machine run for piece 4.

Parent

#377 · epic https://github.com/DIG-Network/dig_ecosystem/issues/3166

[MichaelTaylor3d]

Step 6 (release-first, contract half) is owned by a lane: dig-node-control-interface branch feat/412-mirror-bond-state, draft PR DIG-Network/dig-node-control-interface#38. Declaring the per-(store, root) bond state; 0.25.0 -> 0.26.0. Unblocks dig-app#300 and the locked-total half of dig-app#289.

[MichaelTaylor3d]

Step 6 (contract half) is READY for gating — draft PR DIG-Network/dig-node-control-interface#38, feat/412-mirror-bond-state @ 8101744, 0.25.0 -> 0.26.0.

control.mirror.bondStates is declared: seven states, paged ascending (store_id, root), {state:"known"|"unknown"} tagged union, and an authoritative whole-set locked_dig_base_units. 183 lib tests green, fmt/clippy clean, all repo CI checks pass.

The §25.8 vocabulary mismatch is reconciled at the interface, and BOTH sides must move:

• withheld in the contract carries §25.8's meaning — Relayed provenance, per capsule.
• disabled is new: the node-wide collateralisation switch, which §25.8 could not express at all and which BondState::Withheld currently occupies.
• reclaiming is new to the enum: §25.8 named it, BondState had no variant, and its money is still locked.

So dig-node must rename BondState::Withheld -> Disabled and add Withheld + Reclaiming, and SPEC.md §25.8 must gain disabled. Recorded normatively in the crate's own SPEC.md §4.2g.

Two things the serving half must know before it builds:

1. withheld is unreachable from a Held-keyed derivation. A Relayed capsule is by construction absent from the desired-bond set, so bond_states() as written can never emit it — it answers "no such row" where the contract promises "withheld on purpose". The surface must enumerate the SERVED set, or say plainly that it cannot.
2. "cannot tell" is a WHOLE-CALL answer, not a per-row one. {state:"unknown", reason: served_set_unknown | chain_unreadable | in_flight_unknown}. There is no per-row unknown and no empty-list fallback: entries: [] + complete: true asserts this node holds no bonds. Requirement-unknown is NOT one of these — it stays the definite per-row deferred.

Adopting 0.26.0 turns crates/dig-node-service/tests/control_contract_conformance.rs RED until the node serves the method and adds the dign verb. That is the intended forcing function, not a surprise.

Blast radius: additive only, no existing type or token changed shape, and ControlHandler has zero implementors outside the crate's own MockNode (dig-node dispatches manually in control.rs).

[MichaelTaylor3d]

Foundation merged — dig-node#379 landed as fba53ecb. Five things this ticket now carries.

SPEC.md §25, the planner, presence detection, the spend builders, the scoped signer and the §25.7
switch are all on main. Both gates PASSed; the security leg withdrew its own by-value
prescription and agreed the journal-taking signature is stronger, because making divergence
inexpressible beats checking it.

1. F6 (MEDIUM) — a status regression the fix commit introduced, deliberately carried here

crates/dig-node-service/src/mirror/signer.rs:174-181. On the ? after WalletSigner::sign,
recorded drops inside sign, and Drop writes Unresolved — which this crate defines
(spend_audit.rs:296-300) as "the node signed… money may well have moved".

The truthful status is Failed { stage: Signing }, whose money_may_have_moved() is false
(spend_audit.rs:211-216), and SPEC.md:8055-8058 implies the same.

Non-gating and it fails in the safe direction — it over-reports risk rather than under-reporting
it, and MirrorSigner has no production caller yet. But this ticket writes that first caller, so
fix it before the caller exists rather than after.

2. Two doc corrections, same file

• SPEC.md:8036-8038 — the banner says "two structural halves" then lists three, one being "the
  &RecordedSpend precondition", a parameter the same commit removed.
• SPEC.md:7924-7926 — the allowlist tail "…and §25.9's decision directions" reaches clauses that
  the §25.4/§25.5/§25.8 banners call pending. The closing default rule resolves it safely, but the
  auditor named it the loosest point of the construction.

3. BondState must be RENAMED, and the window to do it safely is now

The contract half (DIG-Network/dig-node-control-interface#38, 0.26.0)
established that withheld, disabled and reclaiming are three states, not two — they differ
in scope (one capsule's provenance vs one switch for the whole node) and decisively in remedy: an
operator told "withheld" about a disabled node goes looking at content, when they should be looking
for a switch.

dig-node must rename BondState::Withheld → Disabled and add Withheld + Reclaiming. That
enum is now on main via #379, so until this lands, dig-node holds an enum whose word means the
opposite of the published contract's.

4. §25.8's withheld is VACUOUS against the current derivation — do not paper over it

A Relayed capsule is by construction absent from a Held-keyed desired-bond set, so
bond_states() as written answers "no such row" exactly where the contract promises "withheld on
purpose". The surface must enumerate the served set, or say plainly that it cannot.

This is the vacuously-satisfied class: a conformance list ticks the clause while the producer
structurally cannot emit it. Conflating "out of funds" with "withheld on purpose" is
DIG-Network/dig-app#300 actual defect, so getting this wrong reproduces
the bug the surface exists to fix.

5. The Relayed filter belongs AT THE SOURCE

§25.1's exclusion is prose today — plan::Bond (plan.rs:27-32) carries only store_id and root,
with no provenance field. The banner now says so. Filter at the source rather than trusting a
pre-filtered set, and note this is the one place an attacker could influence what the node spends
its own money on.

Also still owed from the locked spec

The named fee constant (no MIRROR_SPEND_FEE_CEILING_MOJOS exists yet), and the fact that this
ticket writes the first real caller against sign(&MirrorSpends, &SpendJournal).

[MichaelTaylor3d]

Lane claimed. Worktree C:/tmp/worktrees/dn-412, branch loop/412-mirror-pass-runner off fba53ec,
draft PR #414.

Scope: step 4's impure half (the pass runner), plus F6, the BondState rename, the source-side
Relayed filter, and the two SPEC.md doc corrections. Steps 6/7/8 are not in this diff.

One correction to the brief already: MIRROR_SPEND_FEE_CEILING_MOJOS DOES exist — #379 shipped
it at crates/dig-node-service/src/mirror/signer.rs:70, with both-sided coverage in
the_fee_ceiling_is_exact_in_both_directions. So that item is already satisfied and is not owed.