mirror bond-states answers chain_unreadable on a synced node with 8 peers, while balances read fine

[MichaelTaylor3d]

Parent epic: https://github.com/DIG-Network/dig_ecosystem/issues/3166
Sibling: #412 (step 7 shipped the observation this reports on)
Found by: the dig-app#289 lane, on the installed node, 2026-08-30

Task

dign mirror bond-states --json returns {"state":"unknown","reason":"chain_unreadable"} on a node
that is synced, with 8 chia peers, and reading the chain fine for balances. Establish why the bond
observation cannot read a chain that the balance path reads successfully, and make it able to.

The measurement

On the installed dign 0.172.0, at the same moment, on the same machine:

call	result
control.wallet.balance	{"balance":1010000, "synced":true} — 1 010 $DIG, independently corroborated against api.coinset.org
dign mirror bond-states --json	{"state":"unknown","reason":"chain_unreadable"}

chia_peer_peak_height equals the replica peak, so this is not the silent-staleness shape NC-12
records. The node can read the chain. The bond observation says it cannot.

Why this matters rather than being cosmetic

#412 step 7 shipped the observation (merged 5df3e34) specifically so control.mirror.bondStates
would stop answering chain_unreadable on every call. It now constructs a real observation — and on a
real machine still answers chain_unreadable. So the capability exists and the surface does not
receive it, which is the gap between a code path existing and a person seeing it work (§2.6).

Downstream, this is a money surface going blank: dig-app's collateral heading derives its locked
figure from this method, so on this configuration a real user sees "How much is locked up is not
known — your node cannot read the chain right now." That sentence is honest, which is why this is a
capability gap and not a lie — but it is the wrong answer, and the honest-unknown is masking it.

Scope

Find which chain read the observation performs that the balance path does not, and why it fails.
Candidates worth checking before anything else, in order:

1. dig_mirror_coin::list needs a ChainSource plus the operator wallet's own puzzle hash. The
   balance path answers per-address through a different route; if the observation's ChainSource is
   absent or differently constructed, chain_unreadable is the honest report of a missing dependency
   rather than a failing read.
2. Whether the reason is accurate at all. chain_unreadable may be the catch-all arm for several
   distinct failures. If so, the reason itself is the first defect — an operator told the chain is
   unreadable will go looking at peers, which are fine.
3. Whether it differs by configuration (enable_live_broadcast defaults false; the operator wallet may
   hold nothing).

The trap to avoid

Do not "fix" this by making the observation return an empty page. A page of no rows is a definite
claim that this node holds no bonds, and control.rs's own comment says so: "A caller MUST NOT
substitute an empty observation for an Err — a page of no rows says 'this node holds no bonds',
which is a definite claim about money." If the read genuinely cannot be performed, the honest unknown
stays; the deliverable is then a more accurate reason, not a fabricated zero.

Acceptance

On a real machine with a synced node, dign mirror bond-states --json returns either a real
observation, or an unknown whose reason names the actual obstacle. Verified by running it — not by a
passing test, and not from the node's own logs alone.

[MichaelTaylor3d]

The premise is false: the measured binary predates the fix it is said to contradict

Measured 2026-08-31T00:2xZ against the repo, not against a comment.

$ git rev-list -n1 v0.172.0
6e8bfa74b3f8...
$ git merge-base --is-ancestor 5df3e34 v0.172.0 ; echo $?
1        # NO — step 7 is not an ancestor of v0.172.0

v0.172.0 is 6e8bfa7, and the step-7 observation merged as 5df3e34 after it. The commit order
on main is:

9eb8fbd  feat(mirror): wire a production broadcaster (#424)      <- current main, 0.175.1
3d15118  feat(dht): attach the untrusted mirror-coin pointer (#431)
6d6bb7c  feat(mirror): advertised URLs (#426)
bd3d701  fix(wallet): honest refusal reasons (#410)
8b53156  feat(mirror): operator-scoped $DIG CAT selector (#421)
5df3e34  feat(mirror): construct the bond-state observation (#412 step 7)
6e8bfa7  chore(release): v0.172.0                                 <- the binary that was measured

So the installed dign 0.172.0 carried the stub — the one mirror/lifecycle.rs:6 describes in its
own words as answering unknown { chain_unreadable } on every call with no pass ever running. It
answered exactly as designed. This ticket's headline finding — step 7 shipped and a real machine still
says chain_unreadable — is not evidence about step 7, because step 7 was not in the binary.

This does not close the ticket. It relocates it: the real-machine behaviour of step 7 is still
unmeasured, and main is now five commits and three minors past what was tested. The acceptance
bar is unchanged and still unmet.

What IS a defect on current main, read directly and independently of the above

chain_unreadable is the catch-all for five structurally different states, only one of which is a
chain read failing. mirror_bond_observation (control.rs:3593-3599) returns it whenever the
ctx.mirror_bonds slot is None, and the slot is left None by every one of:

#	path	server.rs	what is actually wrong
1	enable_chain_sync == false	:2133	spawn_mirror_passes is never called; no task exists
2	no operator wallet	:2703-2711	early return — the task exits permanently, and a warn is the only trace
3	no epoch in force	:2758-2762	continue; nothing published yet
4	chain.chain_source() is Err	:2847	the only state chain_unreadable truthfully names
5	pass.run() is Err	:2838	deliberately not published (correctly — see below)

Rows 1 and 2 are the sharp ones: both are terminal, not transient. A node in either state answers
chain_unreadable forever while its chain reads work perfectly, which is what sends an operator to
inspect peers that are fine. Row 2 also silently ends the task, so no later pass can recover it.

The enum has no variant that can express any of rows 1-3
(MirrorBondStatesUnknownReason = ServedSetUnknown | ChainUnreadable | InFlightUnknown | ProvenanceUnknown, dig-node-control-interface 0.24.0 results.rs:2368), so making the reason
accurate is a release-first contract change (§4.1): publish the widened enum, then adopt it in
dig-node. It is not a dig-node-only edit.

What must NOT change

The Err arms are right and the ticket's own trap note covers them. Row 5 not publishing, and the
"keeps its previous answer" comment at server.rs:2838, are the correct behaviour: a failed
observation is not a smaller observation. The deliverable here is a truer reason, never a
fabricated empty page.

Revised acceptance

1. Build current main (>= 9eb8fbd), run it, and record what dign mirror bond-states --json
   actually prints. That reading is the thing this ticket was opened to obtain and does not exist yet.
2. If it is still unknown, the reason must name which of the five rows above is in force — which
   requires the contract widening, release-first.

[MichaelTaylor3d]

Lane opened for this ticket, batched with #412 and #411 (all three gated on the same missing
real-machine reading of the mirror lifecycle).

• branch: loop/433-mirror-bond-reason
• draft PR: feat(mirror): prove the mirror-coin lifecycle on a real machine #439
• worktree built from origin/main @ 9eb8fbd (0.179.0)

Step A is in flight: build dign from that commit, run the node, capture
dign mirror bond-states --json verbatim plus RUST_LOG=mirror=debug tracing. The reading
lands here as a comment before any code is written — it decides which of the five
chain_unreadable rows is actually in force.

[MichaelTaylor3d]

Closing as a STALE-MEASUREMENT artifact, not a defect — measured, not assumed

The node this was measured on predates the observation code entirely.

installed dign         0.172.0   (tag v0.172.0 = 6e8bfa74)
step 7 observation     5df3e34   (PR #419)
git merge-base --is-ancestor 5df3e34 v0.172.0  ->  FALSE

5df3e34 is not an ancestor of v0.172.0. All six of the mirror commits landed after that tag:

commit	what
5df3e34	construct the bond-state observation (#412 step 7)
8b53156	operator-scoped $DIG CAT selector (#421)
bd3d701	honest refusal reasons (#410)
6d6bb7c	advertised URLs (#426)
3d15118	untrusted mirror-coin pointer (#422)
9eb8fbd	production broadcaster (#424)

So dign mirror bond-states answering {"state":"unknown","reason":"chain_unreadable"} was the correct and honest answer from a node that genuinely has no observation to report. The verb existed at 0.172.0 because the method shipped in #417; the thing that fills it did not.

Why I filed it anyway, and the lesson

The report compared two readings taken at the same moment on the same host — control.wallet.balance returning a real 1 010 $DIG against bond-states returning chain_unreadable — and concluded the node could read chain for one and not the other. Both readings were accurate. The inference was wrong, because one capability existed in that binary and the other did not.

A measurement on an installed binary is a measurement of that binary's version, not of main. The check that was missing is one line: is the commit under test an ancestor of the installed tag? I have started doing that first.

Not closing blind

This will be re-verified on 0.179.0, which carries all six commits, as part of the epic's real acceptance — a bond created on chain and reclaimed, watched on a real machine (https://github.com/DIG-Network/dig_ecosystem/issues/3166). If bond-states still answers chain_unreadable on a node that does have the observation, that is a genuine defect and this ticket gets reopened with the new evidence.

[MichaelTaylor3d]

STEP A — the real-machine reading, and it is GOOD news

Measured 2026-08-31T00:35-00:36Z on Windows 11, from a dign built in this lane's own worktree at
origin/main = 9eb8fbd, version 0.179.0 — five commits and several minors past the
6e8bfa7 / 0.172.0 binary this ticket's headline was taken from.

Run: RUST_LOG=mirror=debug,dig_node_service=info DIG_NODE_PORT=9779 dign run
(port 9779 because the installed 0.172.0 service still holds 9778).

dign mirror bond-states --json, verbatim

{"ok":true,"action":"mirror","service":"dig-node","version":"0.179.0","state":"known","entries":[],"complete":true,"cursor":null,"locked_dig_base_units":0,"epoch":104}

The mirror-target tracing, verbatim

2026-08-31T00:35:49.576361Z  INFO mirror: the mirror lifecycle is live: this node may create and reclaim collateral
2026-08-31T00:35:49.576402Z  INFO mirror: no DIG_MIRROR_ADVERTISE_URLS entry is publishable, so this node advertises nothing and creates no mirror coin (SPEC.md 25.10)
2026-08-31T00:35:55.573832Z DEBUG mirror: mirror pass complete epoch=104 bonds=0 locked_dig_base_units=0 reclaimed=0 created=0

Which of the five rows is in force: NONE of them

state is known, not unknown. The pass ran ~6 seconds after bring-up, read the chain,
completed, and published. So on current main:

• row 1 (enable_chain_sync == false) — not in force; the flag defaults true and the task spawned.
• row 2 (no operator wallet) — not in force; the wallet opened and the bring-up log proves it.
• row 3 (no epoch in force) — not in force; epoch 104 is in force and is carried in the answer.
• row 4 (chain_source() is Err) — not in force; the pass read the chain successfully.
• row 5 (pass.run() is Err) — not in force; the pass completed and published.

entries: [] here is not a fabricated zero. It is a published observation with
complete: true and a named epoch, taken by a pass that genuinely read the chain, and it is
truthful: this node has never created a mirror coin, so it holds no bonds and locks no $DIG.
That is precisely the distinction the surface was built to make, and it makes it correctly.

What this settles

The step-7 lifecycle works end to end on a real machine. The chain_unreadable reading in this
ticket's title was an artifact of the measured binary predating the fix, exactly as the previous
comment predicted — and now that has been checked in the affirmative direction too, not merely
argued from commit ancestry.

This ticket's remaining content is therefore the reason-accuracy defect only: rows 1-3 still
cannot be named by MirrorBondStatesUnknownReason, so a node that IS in one of those states would
still say chain_unreadable while its chain reads work. That is real, it is latent rather than
active, and it is a release-first change in dig-node-control-interface.

Two things observed in passing, logged not ticketed

• DIG_WALLET_ENABLE_LIVE_BROADCAST=1 is set in this machine's user environment, so the node
  reports SpendCapability::Available and may broadcast real mainnet spends. Nothing was
  broadcast: with no publishable advertise URL, create refuses by name before any chain read,
  which is Mirror creates need an advertised URL this node can be fetched at #426's remaining gap doing its job.
• File logging is disabled on this host (C:\ProgramData\DigNetwork\logs\dig-node, os error 5
  from a non-elevated shell). Console logging carried the reading, so it cost nothing here.