SPEC.md

# dig-node — Normative Specification

This document is the authoritative contract for the **dig-node** repository: the **canonical DIG
node**. dig-node OWNS the node implementation directly — the JSON-RPC dispatch, local-first
content serve/fetch/redirect, chain-anchored-root resolution, chain-watch, subscription
management, generation gap-fill, the cache, and the peer-to-peer (P2P) stack. It ships two host
shells around that one node implementation: a self-contained cross-platform binary installable as
an OS service (Windows SCM, Linux systemd, macOS launchd), and an in-process cdylib the DIG
Browser links. This document specifies identity and naming, the environment/configuration
contract, the HTTP/JSON-RPC surface, the control plane, the CLI contract, the OS-service
lifecycle, and the release-asset contract.

The **DIG read protocol wire shapes** (the `dig.getContent` ciphertext + Merkle-proof shapes, the
URN grammar, anchored-root semantics, the §21 sync protocol) are the canonical DIG-node RPC
interface defined in the `dig-rpc-protocol` crate and specified on the docs.dig.net Protocol pages.
For the `.dig` STORE FORMAT itself (byte layout, read/verify/decrypt, chain anchoring) dig-node
depends on digstore's store-format LIBRARY crates. This document references those contracts; it
does not restate them (§2.2, §5).

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as in RFC 2119.

For usage instructions, see `README.md`. For non-normative narrative, see `USER_JOURNEY.md`.

---

## 1. Scope and architecture

1.1. dig-node is the **canonical node**, organized as a Cargo workspace of four crates:

- **`dig-node-core`** (library, `dig_node_core`) — the NODE engine itself. It owns `handle_rpc`
  dispatch, local-first content serve/fetch/redirect, chain-anchored-root resolution, chain-watch +
  subscriptions + generation gap-fill, the cache, and the P2P stack (peer serve/dial, DHT
  provider records, PEX, multi-source download). It depends on the P2P crates
  (`dig-nat`/`dig-gossip`/`dig-dht`/`dig-pex`/`dig-download`/`dig-peer-selector`) — consumed from
  crates.io per §3.6, with the single exception of `dig-gossip`, which stays a pinned git
  dependency until its crates.io publish is unblocked (guarded pending `dig-peer-protocol`, #681) —
  and on digstore's `.dig` store-format LIBRARY crates
  (`digstore-core`/`-crypto`/`-chain`/`-host`/`-remote`/`-stage`) as git dependencies. The
  dependency direction is dig-node-core → store-lib; digstore MUST NOT depend on dig-node-core
  (digstore is only ever an RPC client of a node). The engine library is named `dig-node-core` so
  it no longer shares a name with the `dig-node` binary the service shell produces (#216).
- **`dig-node-service`** (binary `dig-node`) — the OS-service host shell around the engine library.
- **`dig-runtime`** (cdylib `dig_runtime`) — the DIG Browser's in-process host shell (§15).
- **`dig-wallet`** (library + binary) — the DIG Browser's built-in Chia wallet host.

1.2. The **service shell** (`dig-node-service`) owns exactly:

- HTTP transport (axum): listeners, CORS, Host-header allowlist (§4);
- request **normalization** (param-name aliasing only, §5.3);
- the **opt-in passthrough relay** to a configured upstream DIG RPC for methods the node does not
  resolve — OFF by default, and never to itself (§5.4);
- the **discovery surface** (`/health`, `/version`, `/openrpc.json`,
  `/.well-known/dig-node.json`, `rpc.discover`) (§6);
- the **control plane** (`control.*`) with its local-token authorization (§7) — the operator
  surface (status/hostedStores/sync/config/cache); control methods it does not own are delegated
  to the node's own control surface (peerStatus/subscribe/unsubscribe/listSubscriptions);
- the **CLI** and OS-service registration (§8, §9);
- two small pieces of persisted state in the shared `config.json`: the pin registry and the
  upstream override (§7.6).

The service shell MUST NOT reimplement, transform, or "improve" the node's responses: what
`dig_node_core::handle_rpc` returns is what the client receives.

1.3. The wire contract is byte-identical across BOTH host shells because dispatch IS the same
`dig_node_core::handle_rpc` in both — the OS-service binary AND the `dig-runtime` cdylib's `dig_rpc`
export run ONE node implementation. (The DIG Browser itself starts the cdylib WALLET-ONLY (§15) and does
NOT run this in-process node — it is a pure RPC consumer of an EXTERNAL node over the §5.3 ladder; the
`dig_rpc` full-node path is for other consumers.) A client written against `rpc.dig.net` (e.g. the DIG
Chrome extension's `fetchContentViaRPC` pipeline) MUST work against this node unchanged. Verification and
decryption happen in the **client** — for the DIG Browser via the native read-crypto FFI (§15.1), for
webpages via the equivalent `dig-client-wasm`; the node serves blind ciphertext + proofs and MUST NOT
return plaintext for content reads. The ONE exception is the loopback-only local plaintext
content-serve surface (§4.6) — a DISTINCT HTTP surface from this JSON-RPC read plane — which decrypts
SERVER-SIDE for a same-machine browser over loopback; the JSON-RPC `POST /` read plane, `rpc.dig.net`,
and every peer surface stay blind ciphertext + proof.

1.4. **Canonical RPC interface — `dig-rpc-protocol` + `dig-rpc`.** The RPC surface this node exposes
(method names + request/response types, the error-code taxonomy, and the tier classification) is
the canonical DIG-node RPC interface defined ONCE in the **`dig-rpc-protocol`** crate (published on
crates.io; formerly `dig-rpc-types`) — the single source of truth this node (the one implementation
shared by both host shells) and the `rpc.dig.net` gateway share, so the two can never drift. The
JSON-RPC server framework (transport surfaces, tier allowlist enforcement, rate limiting, mTLS) is
the **`dig-rpc`** crate, which depends only on `dig-rpc-protocol`. This
SPEC's method catalogue (§5.5), envelope rules (§5.1), and error catalogue (§10) MUST match
`dig-rpc-protocol` exactly; where they differ, `dig-rpc-protocol` is authoritative and this SPEC is
the drift to fix. The OpenRPC document (§6.3) is generated from `dig-rpc-protocol`'s own
method/tier/error tables.

1.5. **dig-rpc-protocol adoption status.** `dig-rpc-protocol` is published on crates.io (0.3.0) and
this repo DEPENDS on it (#1075): `dig_node_core::handle_rpc` dispatches on `Method::from_name` + the
`Method` enum (not string literals), and the mTLS peer-reachability allowlist is
`Method::is_peer_reachable` — the single allowlist source both node implementations share (the #179
auth-bypass surface). The dig-node-service discovery catalogue (`meta.rs`) is a SUPERSET (it adds the
shell's HTTP control surface — pairing/control.status/hostedStores/updater — and the `served`/
`requires_auth` model that the node↔node `Method` crate deliberately does not model); a drift guard
ties its node-surface method names + the peer-reachable set to the crate. Not yet adopted: the crate's
`RpcError`/`ErrorCode` types (the shell keeps its own `ErrorCode`, whose two shell-specific machine
strings — `DISPATCH_FAILED` at `-32000`, `RESOURCE_NOT_AVAILABLE_AT_ROOT` at `-32004` — differ from
the crate's `SERVER_ERROR`/`RESOURCE_UNAVAILABLE`; reconciling those wire strings is a separate,
wire-visible decision) and the `dig-rpc` server framework. The numeric error codes remain guaranteed
identical by the conformance vectors.

---

## 2. Identity and naming

2.1. **Canonical name.** The produced binary, the service-shell Cargo package (`dig-node-service`),
the OS service, and every machine-readable service-identity surface are named `dig-node`. The node
ENGINE library crate is `dig-node-core` (lib `dig_node_core`) — a distinct name from the `dig-node`
binary so the two are never confused (#216). Every machine-readable surface (`/health.service`,
`/version.service`, the CLI `--json` envelopes' `service` field) MUST report the service identity
string `"dig-node"` (`meta::SERVICE_NAME`) — the alias below renames only the invoked binary, never
the service identity.

2.1a. **`dign` first-class alias (issue #548).** The service shell also produces a second binary,
`dign`, a FIRST-CLASS alias for `dig-node` (mirroring how `digs` aliases `digstore`, #434). It is a
real installed binary — not a shell alias — defined as a second `[[bin]]` target
(`crates/dig-node-service/src/bin/dign.rs`) that shares the SINGLE entrypoint
`dig_node_service::run()` with `dig-node`, so there is NO duplicated logic. `dign <args>` MUST behave
IDENTICALLY to `dig-node <args>`: the same subcommands, flags, `--json` envelopes, and exit codes.
The displayed program name is derived from arg0, so `dign --help`/`--version` report `dign` while
`dig-node --help`/`--version` report `dig-node`. A release publishes `dign` alongside the primary
under the stem `dign-<ver>-<os>-<arch>[.exe]` (byte-identical shape to `dig-node-<ver>-<os>-<arch>`).

2.2. **One canonical version field (HARD RULE).** The node reports exactly ONE version — the
`version` field (the shipped `dig-node` binary / workspace release version, `meta::VERSION`) —
across `/version`, `/.well-known/dig-node.json`, and `control.status`; `commit` (`meta::GIT_SHA`)
pins the exact source revision beside it. There is NO second version key: the former
`dig_node_version` (the internal engine-library crate version, `dig_node_core::NODE_VERSION`) was
removed in #585/#586 because it named a *different* value under a second key — ambiguous ("which
version?") — and `commit` already fingerprints the now-in-repo engine. The node engine
(`dig-node-core`) is a first-party sibling crate in this workspace; when its crate version changes,
or when the digstore store-format git dependencies (`digstore-*`) are bumped to a new rev, the
method catalogue MUST be re-verified against the node's real dispatch (the drift guard, §5.6,
enforces this).

2.3. **Protocol tag.** `meta::PROTOCOL` is the DIG read-protocol identifier (`"21"`, the
rpc.dig.net §21 JSON-RPC read contract). It MUST be bumped only when the wire contract changes.

2.4. **Service label.** The OS-service label is the reverse-DNS constant
`net.dignetwork.dig-node` (`service::SERVICE_LABEL`). On Windows it becomes the SCM service name
(qualified form `net-dignetwork-dig_node`); on launchd, the plist label; on systemd, the unit
name. It MUST remain stable: `install`, `uninstall`, `start`, `stop`, and the Windows service
dispatcher registration (§9.4) all address the service by this exact label.

2.5. **Build provenance.** `build.rs` embeds the short git SHA of HEAD at compile time as the
`DIG_NODE_GIT_SHA` compile-time env var (surfaced as `commit` in `/version`, `/health`,
`/.well-known/dig-node.json`, and `control.status`). Outside a git checkout the value MUST be the
literal string `"unknown"`; the build MUST NOT fail for lack of git.

2.6. **Legacy reference implementation.** The `node/` directory contains the retired v0.2
JavaScript server (`@dignetwork/dig-companion`), retained as documentation only. It is NOT a
shipped artifact and carries no conformance obligations.

---

## 3. Configuration — the environment contract

Configuration is resolved from the process environment by `Config::from_env()` at startup.

### 3.1. Stable `DIG_NODE_*` names (HARD RULE)

The bind variables are named **`DIG_NODE_PORT`** and **`DIG_NODE_HOST`**. These are the binary's
stable configuration contract: the dig-installer sets them and apt.dig.net documents them. They
MUST NOT be renamed again — DIG is pre-release with no legacy aliases (#201); the canonical names
ARE `DIG_NODE_*`, full stop.

### 3.2. Variables and defaults

| Variable | Meaning | Default | Rules |
|---|---|---|---|
| `DIG_NODE_PORT` | localhost-listener bind port | `9778` | Parsed as `u16`; `0`, unparsable, or unset → default. |
| `DIG_NODE_HOST` | EXPLICIT localhost-listener bind IP override | *(unset)* | Parsed as `IpAddr`; unparsable/blank/unset ⇒ unset (§4.1's dual-stack default — see below), NOT a hardcoded `127.0.0.1` default. Setting it REPLACES the dual-stack default with exactly that one address (#288). A NON-loopback value is REFUSED at startup unless `DIG_NODE_ALLOW_REMOTE` is truthy (§3.2.1, #1662). |
| `DIG_NODE_ALLOW_REMOTE` | permit a non-loopback `DIG_NODE_HOST` bind | `false` | Truthy = `1`/`true`/`yes`/`on`; anything else (unset/blank/falsy/unrecognized) ⇒ the security-safe default **false**. When false, a non-loopback `DIG_NODE_HOST` is a fatal configuration error at startup (§3.2.1). Loopback overrides and the no-override default never require it. |
| `DIG_RPC_UPSTREAM` | upstream DIG RPC base URL for passthrough + miss-proxy | *(unset — NO default upstream)* | Normalized (§3.3); highest precedence (§3.4). Unset ⇒ passthrough is OFF and an unimplemented method answers a local `-32601` (§5.4). A value naming THIS node is REFUSED (§3.4.1). |
| `DIG_NODE_CACHE` | explicit on-disk `.dig` cache dir | *(unset)* | Blank/whitespace ⇒ unset. Unset ⇒ shared canonical default (§3.5). |
| `DIG_NODE_DIGLOCAL` | toggle for the bare `dig.local` listeners (`http://dig.local` on `127.0.0.2:80` AND, when a dig-cert leaf is present, `https://dig.local` on `127.0.0.2:443` — §4.1a) | `true` | Falsy = `0`/`false`/`no`/`off`; truthy = `1`/`true`/`yes`/`on`; case/whitespace-insensitive; unset or unrecognized ⇒ **default true**. |

The default port is the UNCOMMON high port **`9778`** (not `80`/`8080`). Port 80 requires elevation
on most OSes, and both `80` and `8080` are the collision-prone common-dev ports most likely already
bound on a developer machine; `9778` is deliberately clear of the common-dev set
(80/443/3000/5000/8000/8080/8888/9000) and well-known service ports. It is the sibling of the
dig-wallet HTTP API's `9777` (wallet `9777`, node `9778`) and matches the local-node port the
digstore §5.3 resolver already expects (`DEFAULT_LOCAL_NODE_PORT`). Every consumer of the §5.3
`localhost` tier — the DIG Chrome extension's `server.host` default, the dig-installer, and the DIG
Browser — MUST target `localhost:9778` to match. `DIG_NODE_PORT` overrides it; the `http://dig.local`
listener (`127.0.0.2:80`) is unaffected — only this localhost port changed (#132).

### 3.2.1. Loopback-only enforcement (HARD RULE, #1662)

The local RPC/content API bind is loopback-only by default AND that property is ENFORCED, not
merely assumed. The node MUST refuse to start when `DIG_NODE_HOST` resolves to a NON-loopback
address unless `DIG_NODE_ALLOW_REMOTE` is truthy: an unauthorized non-loopback override is a fatal
startup configuration error with a clear message naming the escape hatch. This makes the service's
"loopback-only / never peer-reachable" invariants TRUE rather than asserted — the local API is
never silently exposed to the network from an unenforced config assumption.

- **Loopback** = an IPv4 loopback (`127.0.0.0/8`), the IPv6 loopback (`::1`), or an IPv4-mapped IPv6
  loopback (`::ffff:127.0.0.1`). All are accepted without the flag.
- **Escape hatch** — `DIG_NODE_ALLOW_REMOTE=1` (truthy per the table) permits a deliberate
  non-loopback bind (e.g. a remote-API test rig). This is opt-in only; it is never on by accident.
- **Scope** — this governs ONLY the local RPC/content bind ([`Config::bind_addr`]). The peer P2P
  wire (mTLS, dig-node-core) and the loopback wallet mTLS listener bind independently, so
  enforcement never affects peer connectivity.
- **Install-time fail-fast (#1667)** — the SAME refusal is applied at `dig-node install`: an
  unauthorized non-loopback `DIG_NODE_HOST` is rejected with the identical error BEFORE the service
  is registered, so an operator learns of the misconfiguration immediately instead of installing a
  service that fails closed on its first start.

The variables above are the shell's public bind/upstream/cache knobs. The node ENGINE library
(`dig-node-core`) additionally reads the following variables directly from the environment; the shell
does not own them (except `DIG_NODE_UPSTREAM`, which the shell SETS — see below):

| Variable | Meaning | Default | Rules |
|---|---|---|---|
| `DIG_NODE_CACHE_CAP` | LRU cache size cap, in bytes | `1073741824` (1 GiB) | Parsed as `u64`. Consulted ONLY when the persisted `cache_cap_bytes` key in `config.json` is absent or `0` (the persisted value wins). Unparsable/unset ⇒ default. |
| `DIG_NODE_COINSET` | override the coinset API base used for chain-anchored-root resolution | `https://api.coinset.org` (mainnet) | Blank/unset ⇒ mainnet default. Used for tests / alternate endpoints. |
| `DIG_NODE_PIN` | read-path anchored-root pin enforcement (§14.4) | `on` (ENFORCED, fail-closed) | ONLY `off`/`0`/`false` disable the node-side pin (a named offline/local-dev escape hatch); any other value or unset ENFORCES. Clients still verify proofs against their own trust root regardless. |
| `DIG_NODE_WATCH_INTERVAL` | chain-watch poll interval, in seconds (§14.2) | `30` | Parsed as `u64`; `0`/unparsable/unset ⇒ default `30`; floored at `1` s so a mis-set value cannot flood coinset. |
| `DIG_NODE_UPSTREAM` | **INTERNAL** — the effective upstream the node library reads | *(unset — NO default upstream)* | NOT a user knob. The shell resolves the upstream (§3.4) and writes this via `Config::apply_to_env()` (§3.5); the shell's public knob is `DIG_RPC_UPSTREAM`. Empty ⇒ the library makes no upstream request at all. |
| `DIG_WALLET_WC_PROJECT_ID` | initial/default WalletConnect projectId for the wallet host (§16) | *(unset ⇒ none)* | A persisted `wc_project_id` in `config.json` wins over this; a blank persisted value falls through to this env. Blank ⇒ treated as unset. |
| `DIG_NODE_MAX_OUTGOING_BYTES_PER_SEC` | outgoing-bandwidth throttle cap, in bytes/second (§17) | `0` (UNLIMITED — opt-in) | Parsed as `u64`; `0`, unparsable, or unset ⇒ unlimited (the throttle is a no-op until an operator configures a cap). Resolved ONCE at node construction. |

The peer-network layer additionally honors `DIG_PEER_NETWORK` (set to a falsy value to disable the L7
peer network) and `DIG_RELAY_URL` (override or disable the relay), which gate the P2P bring-up, and
**`DIG_PEER_PORT`** — the mTLS peer-RPC server listen port (dig-node-to-dig-node RPC traffic, §5.2).
Parsed as `u16`; unparsable/unset ⇒ the default **`9444`** (`peer::DEFAULT_P2P_PORT`).
Bound dual-stack IPv6-first with an IPv4 fallback, per §5.2.

**`DIG_GOSSIP_PORT`** — the gossip pool listen port (distinct from the mTLS peer-RPC port above, #871).
Parsed as `u16`; unparsable/unset ⇒ the default **`9445`** (`peer::DEFAULT_GOSSIP_PORT`).
The peer-RPC (9444) is the node's advertised peer-network identity and the route peers dial to fetch
content; the gossip pool (9445) is the internal connection manager for the node's own peer pool. Both
bind dual-stack IPv6-first with an IPv4 fallback, per §5.2. Both of these **chia-ssl** listeners MUST
present the node's persistent `NodeCert` identity, so the direct-gossip pool's inbound TLS listener
hashes to the SAME `peer_id = SHA-256(TLS SPKI DER)` the node registers/advertises/pins on :9444 — the
gossip pool loads its cert/key from the NodeCert files rather than minting its own, or a direct dial to
this node fails closed with a `peer_id mismatch` (#1532). This unification covers the chia-ssl path
(:9444 peer-RPC + :9445 direct-gossip listener) ONLY; the dig-nat / DigPeer NAT-traversal transport
(the relayed + hole-punch tiers) carries its OWN transport identity, which is unified with the
persistent NodeCert SEPARATELY under #1541 — until that lands, the NAT-traversal path presents an
ephemeral peer_id.

**Network identity — `DIG_NETWORK_GENESIS` + `DIG_NETWORK_ID`.** The node resolves TWO coupled
network identities:

- The **gossip `network_id`** — the L2 genesis challenge (`Bytes32`) the connected pool, DHT, and PEX
  key on. It is `DIG_NETWORK_GENESIS` (a valid non-zero 64-hex value) when set, else the canonical
  `DIG_MAINNET` genesis (a REAL non-zero Chia mainnet header hash pinned in `dig-constants`; a blank,
  non-hex, wrong-length, or all-zero value falls back to it). It MUST be non-zero or `dig-gossip`
  rejects the config at start.
- The **effective network label** — the STRING namespace advertised to the relay introducer + relay
  reservation and reported by `control.peerStatus` / `dig.getNetworkInfo` as `network_id`. Resolved in
  precedence order: an explicit **`DIG_NETWORK_ID`** wins; otherwise, when `DIG_NETWORK_GENESIS`
  selects a NON-default genesis, the label is DETERMINISTICALLY DERIVED from that genesis (`DIG_` + the
  first 16 hex chars of the genesis), DISTINCT from `DIG_MAINNET` and distinct per genesis; otherwise
  it is byte-identical **`DIG_MAINNET`**. Deriving the label from the genesis keeps a
  `DIG_NETWORK_GENESIS`-isolated dev/test network genuinely isolated at discovery (it neither joins nor
  is joined to the mainnet introducer namespace), while the default (no override) MUST remain
  byte-identical `DIG_MAINNET` so mainnet peer discovery never forks.

The EFFECTIVE genesis (64-hex) is surfaced alongside the label in the `control.peerStatus` and
`dig.getNetworkInfo` status snapshots (the `genesis` field) so an operator can see the real network a
node is running on.

### 3.3. Upstream normalization

`normalize_upstream` MUST: trim whitespace, strip all trailing `/`, and prefix `https://` when the
value has no `http://`/`https://` scheme. An empty result is treated as unset.

### 3.4. Upstream precedence

The effective upstream is resolved in this order (first non-empty wins):

1. `DIG_RPC_UPSTREAM` env var — a deploy/CI override MUST never be silently overridden by a saved
   setting;
2. the persisted `upstream_override` key in `config.json` (written by
   `control.config.setUpstream`, §7.5);
3. **no upstream.** There is NO default upstream (#1997). A node that has not been given one
   does not have one, and MUST NOT relay to any host it was not configured with.

### 3.4.1. A node MUST NOT be its own upstream

A resolved upstream that names THIS node MUST be refused and treated as no upstream. Two
independent checks are required, because neither covers the other's case:

1. **Static (offline, at config resolution).** An upstream naming a loopback address, `localhost`,
   or `dig.local` on ANY port this node listens on MUST be refused. The check is stated over the
   CLASS of the node's own listeners — the configurable localhost port, `dig.local` plaintext `:80`,
   and the `https://dig.local` TLS pair on `:443` — not one member of it. A guard naming only `:80`
   lets `DIG_RPC_UPSTREAM=dig.local` through, because that normalises to `https://dig.local`.
2. **Runtime loop detection.** A public name may resolve back to this node through DNS, a CDN, or a
   gateway — invisible to any address comparison. At bring-up a node with a configured upstream MUST
   send it one ordinary `dig.health` request carrying a single-use random JSON-RPC `id`. If a request
   bearing THAT id subsequently arrives at this node's own dispatcher, the upstream demonstrably
   leads here and passthrough MUST be disabled for the life of the process.

The marker MUST travel in the JSON-RPC `id`, not an HTTP header: an intermediary that forwards
JSON-RPC bodies while dropping unknown headers (the rpc.dig.net gateway does exactly this) would
otherwise defeat the detection. A node MUST match only its OWN full probe id — matching the prefix
would let any caller disable a node's passthrough, and would misfire whenever this node is
legitimately somebody else's upstream.

### 3.5. Shared `.dig` cache

- Before constructing the node, the shell MUST call `Config::apply_to_env()`, which sets
  `DIG_NODE_UPSTREAM` to the resolved upstream (the node library reads that name internally;
  the shell's public knob is `DIG_RPC_UPSTREAM`), and sets `DIG_NODE_CACHE` **only when an
  explicit non-blank dir was configured**.
- When `DIG_NODE_CACHE` is unset, the shell MUST NOT invent a path: the read path resolves its
  shared canonical default (`%LOCALAPPDATA%\DigNode\cache` on Windows, `$HOME/DigNode/cache` on
  Unix/macOS) — byte-identical to the dir the DIG Browser's in-process node uses, so both
  installations share ONE cache. Writing an empty/derived value would break that sharing and is
  forbidden.
- The read path makes the shared dir safe for two processes (atomic content-addressed writes + a
  cross-process advisory lock); the shell relies on that and MUST NOT add its own cache-file
  locking.
- The **authoritative** effective cache dir + `shared` flag are those returned by the
  `cache.getConfig` RPC. The shell's `meta::cache_dir()` mirrors the canonical-path logic for
  discovery surfaces only; `meta::cache_shared()` MUST delegate to the read path's resolver
  (`dig_node_core::cache_dir_is_shared`), never reimplement the writability probe.

### 3.6. `config.json` co-tenancy

The shell persists its own keys (`pinned_stores`, `upstream_override`) in the read path's
`config.json` (path from `dig_node_core::config_path()`). Writes MUST be read-modify-write with an
atomic temp-file + rename in the same directory, and MUST preserve all keys the shell does not own
(e.g. `cache_cap_bytes`, `wc_project_id`).

---

## 4. HTTP transport

### 4.1. Loopback listeners (dual-stack default, #91, #288)

The server opens UP TO THREE listeners for the SAME router:

1. **`<DIG_NODE_HOST>:<DIG_NODE_PORT>`** (default `127.0.0.1:9778`, §3.2) — always on. A bind
   failure here is FATAL (`serve` returns the error; CLI exit `BIND_FAILED`, §8.4).
2. **`[::1]:<DIG_NODE_PORT>`** (§5.2 dual-stack loopback) — the SAME `localhost:<port>` on the
   IPv6 loopback. Present ONLY when `DIG_NODE_HOST` is unset (the default): some resolvers return
   `::1` before `127.0.0.1` for `localhost` (Windows by default), so without this listener such a
   client cannot reach the node and observes it as offline even though the IPv4 listener answers.
   An explicit `DIG_NODE_HOST` override REPLACES the default dual bind with exactly that one
   address — this listener is then skipped, not added to. This bind is **best-effort**: on
   failure (IPv6 loopback unavailable/disabled) the node MUST log a structured warning to stderr
   and continue IPv4-only — it MUST NOT abort.
**Authority construction (§5.2, #1682).** Every socket authority the node binds, reports, or embeds
in a URL MUST be built from a typed address and port — never by concatenating the two as text. A
literal IPv6 address therefore always appears BRACKETED (`[::1]:9778`, `[2001:db8::1]:9778`), which
is what the socket-address and URL grammars require. `DIG_NODE_HOST` set to any IPv6 literal MUST
bind successfully; because a failure on listener 1 is FATAL, rendering that authority as unbracketed
text would make configuring the address family this ecosystem PREFERS a self-inflicted outage. This
governs the `/health` `addr` field, the `status` output, the control-client's JSON-RPC URL, and the
`open` command's browser-navigable candidate URLs equally.

3. **`127.0.0.2:80`** — the bare-`http://dig.local` listener (constants `DIG_LOCAL_IP` =
   `127.0.0.2`, `DIG_LOCAL_PORT` = `80`, `DIG_LOCAL_HOST` = `dig.local`). This bind is
   **best-effort**: on failure (no privilege, port in use, missing macOS `127.0.0.2` loopback
   alias) the node MUST log a structured warning to stderr and continue serving localhost-only —
   it MUST NOT abort. Skipped entirely when `DIG_NODE_DIGLOCAL` is falsy.

The distinct loopback IP `.2` exists so the port-80 bind can never collide with an unrelated
`localhost:80` service. The dig-installer writes the hosts entry `127.0.0.2  dig.local`; this
listener is what makes the portless `http://dig.local` URL reach the node. No listener may
bind `0.0.0.0` or the IPv6 wildcard `[::]` — the node is a localhost endpoint and MUST never be
LAN-exposed. A service install (§9) forwards `DIG_NODE_HOST` into the installed service's
environment ONLY when the operator gave an explicit override, so a plain `dig-node install` with
no override yields a service that also dual-binds by default, rather than freezing an IPv4-only
default into every future install.

### 4.1a. Local HTTPS listeners — `https://dig.local` (#624, the #620 local-HTTPS epic)

Beside the plaintext loopback listeners (§4.1) the node serves the SAME router over TLS so
`https://dig.local` is a trusted origin in the browser. The certificate material is owned by the
`dig-cert` crate (per-machine, name-constrained local CA; see `dig-cert` SPEC) and PROVISIONED by
the dig-installer (#623); the node only READS the leaf to serve and OWNS leaf renewal.

The node opens UP TO TWO HTTPS listeners for the SAME router, both **gated on `DIG_NODE_DIGLOCAL`
being truthy AND a dig-cert leaf being present**:

1. **`127.0.0.2:443`** — the bare-`https://dig.local` listener (the IPv4 alias the installer's
   `127.0.0.2 dig.local` hosts entry resolves to). Best-effort: `:443` is privileged, so a bind
   failure (no privilege, port in use, missing macOS loopback alias) MUST log a structured warning
   and be non-fatal — the plaintext surface keeps serving.
2. **`[::1]:443`** — the IPv6-loopback sibling (§5.2). The leaf's SAN covers `::1`, so an
   IPv6-loopback client reaches the identical surface. Best-effort, non-fatal on bind failure.

**Fail-soft when no CA/leaf (HARD RULE).** When `dig-cert`'s TLS root has no `leaf.crt`/`leaf.key`
(the installer has not provisioned the CA yet), or the leaf cannot be loaded, the node MUST log an
informational line and serve **plaintext only** — HTTPS is NEVER a hard requirement to start. No
listener may bind `0.0.0.0` or `[::]`.

**Leaf rotation (the node is the runtime OWNER; SPEC §6.4 of dig-cert).** When HTTPS is up the node
drives `dig-cert`'s `RenewalManager::maintain` at service start and once daily. A pass re-issues the
leaf from `ca.key` once it is within 30 days of its 90-day lifetime, atomically swaps
`leaf.{key,crt}` (temp + rename, so no reader observes a torn or mismatched pair), and fires the
reloadable rustls resolver's `reload()` so the running listener presents the new leaf **without a
restart and without dropping connections**. Transient failures retry on a bounded backoff so a leaf
never lapses; the listener keeps serving the previous leaf until a pass succeeds. The daily interval
uses a **delay** missed-tick policy (#660): after a host sleep/suspend across several intervals the
node runs ONE catch-up pass (which fully reconciles the leaf) rather than bursting one redundant pass
per missed tick.

**TLS-root owner gate (#661, defence-in-depth).** Before reading ANY TLS material — the leaf to
serve, and `ca.key` on the renewal path — the node verifies the TLS root directory is privileged-owned
(§ the shared whole-path owner check) and **fails CLOSED to plaintext** otherwise. A user-writable TLS
root could hold an attacker-swapped `ca.key` that this privileged service would otherwise read and sign
with; refusing it removes that vector. The owner SID is read directly through the Win32 security API
(launching no process — the same spawn-free check the self-heal LPE gate uses), so the guard never
itself executes an attacker-planted binary.

**Shared whole-path owner check (#565/#661/#46, #712).** The three gates above defer to ONE shared
helper that classifies a directory as privileged-owned. It verifies the ENTIRE path, not just the leaf:
EVERY existing ancestor component (the directory, its parent, … up to the filesystem root) MUST be
privileged-owned AND MUST NOT be a symlink/junction/reparse point. A privileged-owned leaf under a
user-writable or symlinked ANCESTOR is still tamperable — an intermediate rename/replace is governed by
the parent's permissions, and a reparse point anywhere redirects the whole path — so a single weak
component fails the check. Per component: **unix** — owned by `root`/uid 0, no group/other write bit,
judged via `symlink_metadata` (lstat) so a symlink is rejected on its own identity; **Windows** — owner
SID equal (exact equality) to the well-known LocalSystem `S-1-5-18`, BUILTIN\Administrators
`S-1-5-32-544`, or `NT SERVICE\TrustedInstaller` (the fixed service SID that owns `C:\Program Files`
and its protected subtree — required so the canonical `%ProgramFiles%` install root is not
false-rejected), and the component carries no `FILE_ATTRIBUTE_REPARSE_POINT`. Fails CLOSED on any
indeterminate or missing component.

**The CA trust anchor is NEVER auto-rotated by the node.** An approaching CA expiry is only REPORTED
(`ca_renewal_due`); anchor rotation is an explicit, installer-coordinated `dig-cert rotate_ca` (it
re-installs trust into every store), never an automatic maintenance side effect. Only two operations
read `ca.key`: install (dig-installer) and leaf renewal (the node via `dig-cert`).

**Transition posture.** The plaintext `127.0.0.2:80` listener (§4.1) is KEPT — no redirect to HTTPS
yet — so existing plaintext consumers (extension/dig-dns/clients) do not break before the §5.3
https-first ladder migration ships. The TLS stack is pinned byte-identical to `dig-cert`/`dig-dns`
(`rustls` 0.23, `ring`, no aws-lc) so exactly one `CryptoProvider` is installed.

### 4.2. Host-header allowlist (anti-rebinding)

Every non-`OPTIONS` request MUST pass the Host allowlist before any handler runs. Allowed host
names (with or without a `:port` suffix): `dig.local`, `localhost`, `127.0.0.1`, `127.0.0.2`, and
the IPv6 loopback `::1` (bracketed `[::1]`/`[::1]:<port>` per RFC 7230's mandatory bracketing for
an IPv6-literal Host, or bare `::1` for a non-browser client that omits them, #288). A missing or
empty `Host` header MUST be allowed (HTTP/1.0, health probes). Any other Host — the DNS-rebinding
vector — MUST be rejected with HTTP **`421 Misdirected Request`** and a JSON-RPC error body
carrying the catalogued `INVALID_REQUEST` code (§10). `OPTIONS` (CORS preflight) is exempt so
preflights to allowed origins always succeed.

### 4.3. CORS

The CORS layer reflects two families of **loopback-trust origins** (the node binds loopback only;
CORS is not an auth boundary):

- **Local web/extension origins:** `chrome-extension://*` and `http://<host>[:port]` where `<host>`
  passes the §4.2 allowlist. `https://` for an arbitrary host and other schemes MUST NOT be reflected.
- **Desktop-app origins (#669):** the two canonical Tauri origins `tauri://localhost` and
  `https://tauri.localhost` (built-in, no configuration), plus any exact origin listed in the
  operator opt-in `DIG_NODE_CORS_APP_ORIGINS` (a comma/semicolon-separated allowlist). This lets a
  native app consuming `dig-urn-resolver` reach the node-first content tier. A desktop app runs on
  the same machine as the node, so this stays loopback-trust only and broadens no trust surface.

  **Wallet-read exposure (#693).** Reflecting the desktop-app origins on the shared CORS layer grants
  any local Tauri app cross-origin READ access to the OPEN wallet-read methods (§7.2 / §18 `get_*`,
  which carry no token) reachable over the same CORS-covered HTTP surface (`POST /` JSON-RPC and
  `POST /{method}`). This is deliberately within the same-machine trust model — a program already
  running as the local user could read that data directly — and does NOT extend to custody or
  signing: every wallet MUTATION and every `control.*` call stays token-gated (§7.12), and the
  bidirectional wallet transport (`/ws`, §4.5/§4.8) validates `Origin` against only the local
  web/extension subset above, NEVER the desktop-app origins. Narrowing the wallet-read reflection to
  the app-origin allowlist WITHOUT also narrowing content reads is not currently cheap: both share
  one router-wide `CorsLayer` and the `POST /` endpoint multiplexes content and wallet reads by
  method, so a clean split would require per-method CORS evaluation the layer does not offer. It is
  therefore documented here rather than enforced; a future route/method-scoped CORS split can gate it
  without broadening any origin.

Allowed methods: `GET`, `POST`, `OPTIONS`. Allowed request headers: `Content-Type` and
`X-Dig-Control-Token`.

**Exposed response headers (#669).** The CORS layer MUST set `Access-Control-Expose-Headers` for the
`X-Dig-*` verification/provenance headers so a CROSS-ORIGIN browser client (dig-urn-resolver's
node-first path) can READ them — a cross-origin `fetch` can otherwise read only a short safelist, and
a resolver that cannot see `X-Dig-Verified` fails CLOSED and drops to the verified rpc tier. The
exposed set is: `X-Dig-Verified`, `X-Dig-Root`, `X-Dig-Inclusion-Proof`, `X-Dig-Chunk-Lens`,
`X-Dig-Source`, `X-Dig-Peer-Tier`, `X-Dig-Store-Id`, `X-Dig-Capsule`, `X-Dig-Resource-Key`,
`X-Dig-Owner-Puzzle-Hash`, `X-Dig-Generation`. These are read-only provenance metadata, so exposing them broadens only
readability. (Cross-repo contract with dig-urn-resolver — mirrored in `SYSTEM.md`.)

**Private Network Access (PNA, #285).** The server MUST advertise `allow_private_network` on the
CORS layer, so a preflight that carries `Access-Control-Request-Private-Network: true` gets
`Access-Control-Allow-Private-Network: true` back. Modern Chrome enforces PNA: any request from a
page or extension context to a private-network address (loopback included) is blocked unless the
preflight response carries this header — WITHOUT it, Chrome silently blocks every
extension→dig-node request and the extension (correctly, from its perspective) reports the node
OFFLINE even though the node is up and `/health` answers a direct, non-PNA-checked request. The
header is emitted ONLY on a preflight that itself requests it (tower_http's `CorsLayer` gates this
automatically); it never appears on an ordinary response and never changes the origin-reflection or
method/header-allow behavior above.

### 4.4. Routes

| Route | Method | Behavior |
|---|---|---|
| `/` | GET | Same body as `/health`. |
| `/` | POST | JSON-RPC endpoint (§5). |
| `/health` | GET | Liveness + identity + cache + methods (§6.1). |
| `/version` | GET | Build fingerprint (§6.2). |
| `/openrpc.json` | GET | The OpenRPC document (§6.3). |
| `/.well-known/dig-node.json` | GET | The discovery document (§6.4). |
| `/ws/status` | GET (WS upgrade) | WebSocket status/liveness channel (§4.5). |
| `/ws` | GET (WS upgrade) | Bidirectional wallet+control transport — correlated request/response + proactive push (§4.8). |
| `/{method}` | POST | Served Sage-parity wallet RPC (`POST {base}/{method}`, §18.1/§18.19). |
| `/{seg}` | GET | Root-absolute subresource rerooted via `Referer` into its store (§4.6). |
| `/s/<storeId>[:<root>]/<path>` | GET | Local plaintext content-serve — server-side decrypt (§4.6). |
| `/verify/<storeId>[:<root>]` | GET | Verification-ledger snapshot for a page session (§4.7). |
| *(fallback)* | GET | Root-absolute subresource rerooted via `Referer` into its store (§4.6). |

### 4.5. `GET /ws/status` — WebSocket status/liveness channel (#239)

A browser client (the DIG Chrome extension's service worker) that needs to react to the node
going offline/online AT ANY MOMENT — not just at the moment of its own next request — upgrades
this route to a WebSocket instead of polling `/health`. The **open socket is itself the liveness
signal**: a clean close, an abrupt reset, or a failed upgrade all mean "the node is not reachable
right now" to the client; there is no separate "are you alive" request/response on this channel.

**Origin validation (CSWSH defense).** Unlike `fetch`, a WebSocket handshake is not blocked by the
browser based on `Access-Control-*` response headers — a page from ANY origin can attempt
`new WebSocket(...)` against a listener the user's browser can reach. The server therefore
validates the `Origin` header itself, against the **local web/extension** subset of §4.3
(`chrome-extension://*` and an allowed local `http://` origin) — NOT the §4.3 desktop-app origins,
which are for the content-read surface only. A disallowed `Origin` MUST be
rejected `403 Forbidden` before the upgrade completes. A request with NO `Origin` header (a
non-browser client — a CLI, an integration test) MUST be allowed; the loopback-only bind is that
caller's defense.

**Message contract.** Every pushed frame is a JSON text frame carrying a discriminated `type`:

- **`status`** — sent EXACTLY ONCE, immediately on a successful upgrade. Fields: `type:"status"`,
  `service`, `version`, `commit`, `mode` (`"local-node"`), `addr`, `upstream`, `cache` (`dir` /
  `cap_bytes` / `used_bytes` / `shared`, identical shape to `/health`'s `cache` field), and `sync`
  (`{ "available": bool }`, whether a §21.9 identity is loaded — see §7.2). This is the SAME
  unauthenticated field set `/health` returns (`status_fields`, shared by both handlers so they can
  never drift) minus `/health`'s own `status:"ok"` and `methods` fields.
- **`heartbeat`** — pushed every ~5 seconds (`WS_HEARTBEAT_INTERVAL`) for the life of the
  connection: `type:"heartbeat"`, `ts` (unix milliseconds), plus a FRESH copy of the same
  service/version/commit/mode/addr/upstream/cache/sync fields as `status`. A heartbeat doubles as
  the "status changed" push — because it always carries a freshly-recomputed snapshot, any change
  (cache usage, sync availability) is visible to the client within one heartbeat interval; there is
  no separate change-detection mechanism in this version (the simplest thing that works).

Alongside each `heartbeat` text frame the server also sends a transport-level WS **Ping**. A
compliant WebSocket implementation (every browser; `tokio-tungstenite` on the Rust side) answers a
Ping with a Pong automatically at the protocol layer — this is invisible to page/service-worker
JavaScript (the browser `WebSocket` API never surfaces raw ping/pong frames to script), so it is a
belt-and-suspenders mechanism for the SERVER's own half-open detection, not something a browser
client can observe directly. If the server does not observe ANY frame from the client (a Pong or
otherwise) within `WS_PONG_TIMEOUT` (~20 seconds, 4x the heartbeat interval), it treats the
connection as half-open and closes it server-side (a clean WS Close), so the client's own
reconnect logic takes over. On receiving a client-initiated Close, the server MUST echo a Close
frame back (completing the WS closing handshake) before dropping the connection.

**Client responsibility (not specified here — see the consuming client's own SPEC.md).** Because a
browser's WebSocket API does not expose ping/pong to script, a client MUST judge liveness from the
`status`/`heartbeat` frames it actually receives: track the time since the last frame, and treat a
connection that has gone quiet for materially longer than the heartbeat interval as stale (close +
reconnect) even if the socket's `readyState` still reports open. A client SHOULD reconnect with
exponential backoff + jitter on any close/error and reset that backoff the moment a connection
succeeds again.

### 4.6. Local plaintext content-serve — `GET /s/<storeId>[:<root>]/<path>` (#289/#290)

A same-machine browser cannot present a client cert to obtain plaintext from the public gateway
(§5.3), so the LOCAL node — the trusted, key-holding, loopback-only endpoint — exposes a DISTINCT
HTTP surface that decrypts SERVER-SIDE and returns the real website. This is separate from the blind
JSON-RPC `POST /` read plane (§1.3, §5): plaintext crosses ONLY loopback; `rpc.dig.net` and peers
stay ciphertext-only.

**Route.** `GET /s/<storeId>[:<root>]/<path>` on every loopback listener (§4.1: `localhost:<port>`,
`[::1]:<port>`, and bare `http://dig.local`). `<storeId>` and the optional `<root>` are 64-hex; a
bare `/s/<storeId>[:<root>]/` (empty `<path>`) serves the store's default view `index.html`
(`DEFAULT_RESOURCE_KEY`). The Host allowlist (§4.2) + CORS (§4.3) answer only loopback names, so this
surface is never reachable off-machine.

**Resolution + verify + decrypt (fail-closed).** For `(storeId, path)` the node:
1. resolves `path` → `retrieval_key = SHA-256(canonical rootless URN)` (`urn:dig:chia:<storeId>[/<path>]`,
   empty → `index.html`) — byte-identical to `dig-client-wasm`/`dig-runtime`;
2. resolves the store's chain-anchored tip root and PINS the serve to it (§14.4, #127) — a requested
   root that is not the tip, an unconfirmable store, or an unreachable chain fails closed. A ROOTED
   request (`:<root>` present) anchors its pinned root by the singleton-lineage walk when that
   succeeds (which also yields the owner puzzle hash, §4.6 serve-metadata), but a walk aborted by a
   single unparseable intermediate generation (#747) falls back to a BOUNDED verify — one
   launcher-hint query reading only the current unspent generation (`verify_pinned_root`) — so a
   valid pinned root stays readable; both paths are fail-closed and enforce that the pinned root is
   the current on-chain generation. A ROOTLESS request resolves the tip via the walk and serves
   against it (surfaced as `X-Dig-Root` + `X-Dig-Verified: true`);
3. fetches the resource's ciphertext + inclusion proof + chunk lengths LOCAL-FIRST, then peer, then a
   CONFIGURED upstream if the operator set one (§4.6 cache order below; there is no upstream by
   default — §3.4 — so the ladder normally ends at peer and an unheld resource is a clean miss);
4. verifies `resource_leaf(ciphertext) == proof.leaf`, `proof.verify()`, and `proof.root ==
   chain_anchored_root`, THEN AES-256-GCM-SIV-decrypts each chunk under the per-URN key — the SAME
   `digstore-core` read-crypto every DIG client uses. A tampered chunk, decoy, or non-anchored root
   never decrypts.

**Store-root scoping (shared-origin best-effort).** Served HTML is rewritten with an injected
`<base href="/s/<storeId>[:<root>]/">` (RELATIVE links resolve within the store) and
`<meta name="referrer" content="same-origin">`. A ROOT-ABSOLUTE `/foo` request (the browser drops the
`/s/...` prefix) lands in the router fallback and is REROOTED via the same-origin `Referer` back into
its store; an unattributable root-absolute request is a `404` (asset) or the SPA fallback (route).
Absolute `https://…` URLs bypass the node entirely.

**SPA history-fallback + MIME rule (#144).** A route-like miss (`path` whose final segment has NO known
static-asset extension) serves the store's `index.html` (`200 text/html`) so a client-side deep link
boots. The node uses the store's `PublicManifest` (§5.5.1) to distinguish a KNOWN file genuinely missing
at this root (an honest `404`) from a route (the SPA fallback); a null manifest (old/private store)
degrades to the extension-less-path heuristic. An ASSET miss (a known non-HTML extension —
`js`/`mjs`/`css`/`json`/`wasm`/`svg`/images/fonts/media/…) is ALWAYS an honest `404`, never `text/html`
(a `text/html` body for a service-worker/module fetch is rejected by the browser for a wrong MIME type).

**Content-type + CSP.** The `Content-Type` is the ecosystem extension→MIME map (byte-identical to the
DIG loader's `contentType()`), with `X-Content-Type-Options: nosniff`. Served HTML additionally carries
a synthesized hardened store CSP (`object-src 'none'`, same-origin `base-uri`, un-framed, with the
sanctioned content network legs) attached as a response header, never trusted from the store body.

**Provenance headers (every serve, #292).** `X-Dig-Verified: true|false` (inclusion + chain-anchored-root
verified server-side — `false` only when the node-side pin is disabled via `DIG_NODE_PIN=off`),
`X-Dig-Root: <root>` (the resolved root served against), and `X-Dig-Source: local|peer|rpc` (the tier
that served the MAIN resource). A consumer's DIG Shields / toolbar reads these.

**Peer-tier attachment (every serve, #1763).** Every served response MUST additionally carry
`X-Dig-Peer-Tier: attached|unattached`, reporting whether the P2P content engine was attached at the
moment the read was ROUTED — i.e. whether Tier 2 was consultable at all. The node MUST capture this
once, before any tier runs, and report the same value regardless of which tier ultimately served the
bytes; it MUST NOT be derived from `X-Dig-Source`.

The two are independent and both are required, because `X-Dig-Source` alone cannot express the
difference between a gateway serve that MISSED on the peer tier and a gateway serve that never had
one. The node serves content from the moment its HTTP surface opens, which is BEFORE the peer network
attaches (§7.8) — availability is deliberately not traded away for readiness — so reads inside that
window skip Tier 2 entirely and fall to a configured upstream, or — with none, the default — MISS.
`unattached` is the node stating that;
a caller MUST NOT treat such a read as evidence about peer replication. `unattached` is also the
permanent value on the in-process/FFI path, which brings up no peer network.

`X-Dig-Peer-Tier` reports engine attachment ONLY: not peer count, not reachability, not whether a
fetch was attempted, and never verification (that is `X-Dig-Verified`).

**Serve-metadata headers (every serve, #486).** Alongside the provenance set, every served resource
carries: `X-Dig-Store-Id: <64-hex>` (the storeId serving this resource); `X-Dig-Owner-Puzzle-Hash:
<64-hex>` — the store's on-chain OWNER puzzle hash, resolved from the SAME chain read as the
anchored-root pin (§14.4) with no extra coinset call; **THE gate for tippability** — a consumer treats
a response carrying this header as tippable, one carrying no header as not; `X-Dig-Generation: <n>` —
the 0-based commit ordinal that last wrote the resource, per the store's embedded `PublicManifest`
(§5.5.1), a local-only lookup (never a chain call); `X-Dig-Capsule: <storeId:root>` — the capsule id
(the canonical `storeId:rootHash` pairing); `X-Dig-Resource-Key: <key>` — the resource/retrieval key of
the served resource (a bare/empty request normalizes to `index.html`, the resolved default view, never
an empty header value). All five describe the MAIN resource served; a value that is unknowable —
`X-Dig-Owner-Puzzle-Hash` when the chain-anchored pin did not run (`DIG_NODE_PIN=off`) or the resolver
could not supply it, `X-Dig-Generation` when the module carries no `PublicManifest` (an older `.dig` or
a private store) or lists no entry for the exact key — is OMITTED, never an empty placeholder. These
headers are attached ONLY on a genuine served resource (never on an error/`404`/non-DIG response), and
are present identically on a `HEAD` request to the same route (axum dispatches `HEAD` to the
registered `GET` handler and strips the body, so the full header set arrives with no body — no
separate HEAD code path).

**Local-first store cache (#290).** Resolution order per `(store, root)`:
1. a synced+verified `.dig` module on disk → serve LOCAL, no network (the DEFAULT once cached);
2. not held → serve the immediate resource from a peer (or a CONFIGURED upstream, if any) AND trigger a single-flight
   background whole-`.dig` sync-down (the deduped `maybe_backfill_capsule` → chain-anchored-root-pinned
   whole-store pull) into the reserved LRU cache dir, so the NEXT read is local. LRU eviction (§7.10)
   applies; an evicted-then-re-requested capsule re-syncs. Freshness is inherent to the anchored-root
   pin (§14.4): a stale locally-cached generation whose root is not the on-chain tip is NEVER served as
   current — the read resolves the tip and fetches/backfills that generation, so local-default is never
   local-FROZEN. A synced `.dig` is trusted only after it verifies against the on-chain root at serve.

**Salt.** A private store's secret salt is not yet provisioned to this surface; a private store therefore
fails closed at decrypt. Public stores (salt = none) serve fully. (Private-store salt provisioning is a
tracked follow-up.)

### 4.7. Verification ledger — `GET /verify/<storeId>[:<root>]` (#307)

The `/s/` serve path (§4.6) verifies every resource server-side against the store's chain-anchored root
and fails closed. The node RETAINS each per-resource verdict + the Merkle inclusion-proof data that verify
step computed, in a bounded, short-TTL, in-memory **verification ledger** keyed by `storeId:root`, and
exposes it read-only on the SAME loopback browser surface (same host-guard §4.2 + CORS §4.3 as `/s/`;
loopback-only, no secrets). A consumer (the DIG Chrome extension) reads it to render a page-level
"Verified by Chia" badge and a proof-inspection modal.

**Recording.** An entry is written on the EXISTING verify step (the ledger does NOT re-verify — it reuses
the proof the serve already computed), at each DEFINITIVE per-resource outcome:
- a resource served (`local`/`peer`/`rpc`) that verified → recorded with `verified` = the `X-Dig-Verified`
  result for that serve (`true` under the default chain-anchored pin; `false` only when `DIG_NODE_PIN=off`);
- an `rpc` response whose bytes were fetched but FAILED verification (a decoy / tamper / a root that is not
  the anchored tip) → recorded `verified: false` with a `failReason`, and — per fail-closed — NEVER served.

A tier fall-through (a `local` decoy that falls through to `peer`/`rpc`) and a genuine upstream content miss
(the `-32004` "resource not available") are NOT verification failures and are NOT recorded. Entries are
deduped by resource key (a re-served resource updates its entry in place, preserving load order).

**Bounds.** In-memory only, never persisted. Retained per `(store, root)` page session for a short TTL
(15 minutes since last update), capped at 64 sessions (least-recently-updated evicted) and 1024 resources
per session.

**Request.** `GET /verify/<storeId>[:<root>]`. `<storeId>` and the optional `<root>` are 64-hex (lowercased).
With `<root>` present the exact session is returned; with `<root>` omitted the store's most-recently-updated
session is returned (a page has one active root). A malformed path is `404`; any well-formed request is
`200` with a valid (possibly empty) JSON body.

**Response.** `application/json`, camelCase, stable field names:

```json
{
  "storeId": "<64-hex>",
  "root": "<64-hex>",
  "aggregate": {
    "verified": true,
    "anyRpcFailed": false,
    "counts": { "total": 3, "verified": 3, "failed": 0,
                "bySource": { "local": 2, "peer": 0, "rpc": 1 } }
  },
  "resources": [
    {
      "resourceKey": "index.html",
      "source": "local",
      "verified": true,
      "root": "<64-hex anchored root this entry served against>",
      "proof": {
        "leafHash": "<64-hex — SHA-256(resource ciphertext), the D5 leaf>",
        "siblings": [ { "hash": "<64-hex>", "dir": "left" }, { "hash": "<64-hex>", "dir": "right" } ],
        "leafIndex": 0,
        "proofRoot": "<64-hex — the root the proof folds to>"
      },
      "failReason": null
    }
  ]
}
```

**Aggregate rules (normative).**
- `aggregate.verified` = `resources` is non-empty AND every entry has `verified: true`. The badge is green
  "Verified by Chia" only when this is `true`; otherwise "Unverified".
- `aggregate.anyRpcFailed` = any entry with `source == "rpc" && verified == false`.
- `counts.total`/`verified`/`failed` count the entries; `counts.bySource` counts entries per tier.

**Proof-data semantics (for display + optional client re-verification).**
- `leafHash` = `SHA-256(resource_ciphertext)` — the per-resource Merkle leaf.
- `siblings` = the bottom-up inclusion path in fold order. `dir == "left"` means the sibling is the LEFT
  node (fold `hash(sibling, acc)`); `dir == "right"` means the sibling is the RIGHT node (fold
  `hash(acc, sibling)`). Internal-node hashing is domain-separated (`SHA-256("digstore:node:v1" || left || right)`).
- `proofRoot` = the root the proof folds to. A client re-verifies by folding `leafHash` up through `siblings`
  and checking it equals `proofRoot`, then checking `proofRoot == root` (the chain-anchored root). For a
  verified entry `proofRoot == root`; for a fail-closed entry they differ (and `failReason` explains why).
- `leafIndex` = the leaf's index reconstructed from the sibling directions (a left-sibling step sets the bit
  at that level). It is a DISPLAY value only — re-verification never consults it — and is exact for a leaf
  whose path has no odd-carry level.

### 4.8. `GET /ws` — bidirectional wallet+control transport (#369)

A thin client (the DIG Chrome extension) drives ALL wallet reads + `control.*`/wallet mutations over
ONE upgraded WebSocket instead of per-call HTTP, and the node PROACTIVELY PUSHES sync-status
transitions + sync events on the same socket — subsuming the SSE `SyncEvent` stream (§18.14) and
`get_sync_status` polling. This is the wallet+control channel ONLY; the resolver/content transport
(§4.6, JSON-RPC §5) is UNCHANGED.

**Origin validation (CSWSH).** Identical to §4.5: the `Origin` header is checked against the local-origin
allowlist (`chrome-extension://*` + allowed local `http://`); a disallowed browser `Origin` is rejected
`403` before the upgrade. No `Origin` (a non-browser client) is allowed (loopback bind is the defense).

**Frames are JSON text frames.** Client→node frames carry a discriminated `type`:

- **`request`** — `{ "type":"request", "id": <string|number>, "method": <string>, "params": <object>,
  "token": <string?> }`. `id` correlates the response. `method` is any served wallet method (Sage
  snake_case + the `wallet.*` custody lifecycle, §18.20) or a `control.*`/`pairing.*` method. `params` is
  the method's request object (the Sage body for a wallet method). `token` is the paired/control token
  (§7.11/§7.12), required for gated ops (below).

Node→client frames:

- **`response`** — `{ "type":"response", "id": <echoed>, "ok": <bool>, "result": <json>?, "error": {
  "code": <int>, "message": <string> }? }`. `ok:true` carries `result`; `ok:false` carries `error`.
- **`sync_status`** (PUSH) — `{ "type":"sync_status", "state": "syncing"|"synced"|"disconnected",
  "peak_height": <u32>?, "target_height": <u32>? }`. Pushed ONCE immediately on connect (the initial
  snapshot) and again on every TRANSITION. `state` is derived from the wallet DB's synced peak +
  initial-catch-up flag; a `stop` sync event pushes `disconnected`. The client renders "Syncing…
  (peak/target)" and gates trust in balances/spends on `synced`.
- **`event`** (PUSH) — `{ "type":"event", "event": <SyncEvent> }`, where `<SyncEvent>` is the tagged-union
  wire shape of §18.14 (`{"type":"coin_state"}`, `{"type":"stop"}`, …). Every published sync event is
  forwarded to each connected socket (best-effort; a lagging subscriber skips the gap).
- **`tip`** (PUSH) — `{ "type":"tip", "tip": <tip-ledger-entry> }` (§18.23). Pushed when the tipping
  subsystem records a tip. Carried on a DEDICATED bus (NOT the Sage `SyncEvent` union), so it never
  appears on the `GET /events` Sage-parity SSE stream — only on `/ws`.

**Subscription model.** A connected socket is IMPLICITLY subscribed to `sync_status` + `event` pushes for
its lifetime — the client gets one socket, no explicit subscribe call. A transport ping every ~5s with a
pong-timeout closes a half-open socket (as §4.5).

**Authorization (§7.12).** Over `/ws`, wallet READS are open to the local client; every wallet MUTATION,
every `wallet.*` custody method, and every `control.*` method REQUIRES the frame's `token` to be the
master control token OR a valid paired token (pairing-admin `control.*` needs the master token). An
unauthorized request gets an `ok:false` response with an `unauthorized` error — the op never runs and is
never relayed upstream. `pairing.request`/`pairing.poll` are open (the bootstrap, §7.11).

---

## 5. JSON-RPC surface (read plane)

The method catalogue (§5.5), request/response types, tier classification, and error taxonomy (§10)
below are the canonical set defined in the **`dig-rpc-protocol`** crate (§1.4) — the single source of
truth shared with `rpc.dig.net`. This node MUST NOT diverge from it.

### 5.1. Envelope rules

- `POST /` accepts a **single JSON-RPC 2.0 request object**. A non-object body (including a batch
  array) MUST be answered in-band with HTTP 200 and an `INVALID_REQUEST` (`-32600`) error envelope
  — never a transport-level failure.
- All JSON-RPC responses (success and error) are returned with HTTP **200**. The error taxonomy
  lives in the JSON-RPC `error` object (§10), not in HTTP status codes (the sole exception is the
  421 Host rejection, §4.2).
- Error envelopes minted by the shell MUST carry the numeric JSON-RPC `code` plus
  `data.code` (stable UPPER_SNAKE symbolic name) and `data.origin` (§10). Agents branch on the
  symbolic name, never on message prose.
- The response `id` echoes the request `id`, defaulting to `null` when absent.

### 5.2. Dispatch order

For each request, in order:

1. `rpc.discover` → answered by the shell with the OpenRPC document (§6.3) as `result`.
2. `control.*` → the control plane (§7): authorization gate, then `dispatch_control`.
3. Everything else → normalized (§5.3), then dispatched to `dig_node_core::handle_rpc` on a
   spawned task. A panicked/failed dispatch task yields `DISPATCH_FAILED` (`-32000`); the server
   MUST survive it.
4. If the read path returns `-32601` (method not found), the shell relays the **original,
   un-normalized** request to the upstream (§5.4).

### 5.3. Request normalization

Applied ONLY to content/proof methods (`dig.getContent`, `dig.getCapsule`, `dig.getModule`,
`dig.getProof`) and only when the canonical field is absent — an explicit value MUST never be
overwritten:

`dig.getModule` is in that list because it is advertised as an ALIAS of `dig.getCapsule`: an alias
that normalizes differently is not an alias, and would reject `storeId` input its twin accepts.
The capsule-scoped reads added in §5.5.0's family (`dig.getMetadata`, `dig.getPublicManifest`) take
the same `{store_id, root}` shape but are NOT yet normalized — tracked in
DIG-Network/dig_ecosystem#2107, along with the `root`/`"latest"` resolution this section predates.

- `storeId` → `store_id`;
- `resource_key` / `resourceKey` → `retrieval_key`.

A `"latest"` or non-64-hex `root` is passed through untouched: the read path treats it as rootless
and proxies, which is correct for this shell (it performs no chain resolution of "latest").
Requests for all other methods MUST pass through byte-unchanged.

### 5.4. Passthrough relay — opt-in, and never to itself

**There is no default upstream (§3.4).** When the read path answers `-32601` and NO upstream is
configured, the shell MUST return that `-32601` to the caller. That is the truthful answer for a
method the node does not implement, and it is what keeps an unrecognised method — and its params,
which can name stores and carry retrieval keys — from being forwarded to a host the operator never
chose. The shell MUST NOT substitute a well-known host for an absent one.

When an upstream IS configured and has not been proven to loop (§3.4.1), the shell MUST POST the
client's ORIGINAL request verbatim (JSON body) to it and return the upstream's parsed JSON envelope
unmodified. The shell is a transparent proxy for these methods: it MUST NOT rewrite params, results,
or upstream error codes. If the upstream is unreachable or returns non-JSON, the shell mints
`UPSTREAM_ERROR` (`-32010`). The relay client identifies itself with the User-Agent
`dig-node/<version>`.

Passthrough is NOT the node's content-miss path. A read for content this node does not hold is
resolved over the peer network — DHT provider lookup, then redirect or fetch-through per
`DIG_NODE_ON_MISS`. With no upstream configured, a resource no peer serves is reported as `-32004`
(resource not available at this root), NEVER as an upstream/configuration error: the resource's
availability is the caller's concern, this node's upstream configuration is not.

### 5.5. Method catalogue

`meta::methods()` is the single source of truth for the method catalogue; `rpc.discover`,
`/health.methods`, `/openrpc.json`, and `/.well-known/dig-node.json` are all generated from it and
MUST NOT re-declare method names. Each entry carries a `served` class and `requires_auth` flag:

| `served` | Meaning |
|---|---|
| `local` | Resolved by the node library (`handle_rpc`). |
| `passthrough` | Read path returns `-32601`; relayed verbatim to the upstream WHEN one is configured (§5.4), else returned to the caller as `-32601`. |
| `shell` | Answered by this service itself (`rpc.discover`). |
| `control` | The gated control plane (§7); always `requires_auth: true`. |

For the current node library (§2.2) the catalogue is:

- **local**: `dig.getContent`, `dig.getAnchoredRoot`, `dig.getManifest`, `dig.getPublicManifest`,
  `dig.getMetadata`, `dig.getProof`, `dig.getCapsule` / `dig.getModule`, `dig.stage`,
  `dig.getCollection`, `dig.listCollectionItems`, the L7 peer surface (`dig.getNetworkInfo`,
  `dig.getPeers`, `dig.announce`, `dig.getAvailability`, `dig.listInventory`, `dig.fetchRange`),
  all `cache.*` (`cache.getConfig`, `cache.setCapBytes`, `cache.clear`, `cache.listCached`,
  `cache.removeCached`, `cache.fetchAndCache`, `cache.pushCapsule` — §5.5.3), and the chat subsystem
  `chat.send` / `chat.poll` (§5.5.2).
- **passthrough**: `dig.listCapsules` (needs a chain generation walk this node does not perform)
  and `dig.getProofStatus` (polls an execution-proof JOB this node does not run — inventing a
  status would be the fabrication the anti-fabrication rule forbids: an absent attestation is
  reported as absent, never as a passed check). Both are honestly unserved rather than merely
  unwritten; a node with no upstream answers `-32601` for them, which is correct.
- **shell**: `rpc.discover`, `dig.health`, `dig.methods`. A node MUST answer its own liveness and
  its own method list on its own authority — neither may depend on an upstream being configured
  (#1997). `dig.health`'s PUBLIC result is liveness only (`status`, `version`, `methods`); the
  operational body (cache dir, bound addr, upstream, commit) stays on the loopback-only
  `GET /health`, because `dig.health` is anonymously reachable through the rpc.dig.net public read
  tier.
- **control**: the operator `control.*` methods of §7.4, plus the node-owned control methods the
  shell delegates to the node (`control.peerStatus`, `control.peers.connect`, `control.subscribe`,
  `control.unsubscribe`, `control.listSubscriptions`).

Param/result schemas for the `dig.*`/`cache.*` methods are owned by the digstore dig RPC and
published on docs.dig.net (Protocol → the L7 read/RPC pages); this repo's OpenRPC document is a
method + error **discovery** catalogue with intentionally permissive schemas.

Every non-`control.*` method MUST have `requires_auth: false`; every `control.*` method MUST have
`served: "control"` and `requires_auth: true`.

#### 5.5.0. `dig.getContent` — the window envelope (#2071)

A `dig.getContent` result is ONE window of a resource's ciphertext, and a client reassembles the
windows itself. The envelope MUST therefore describe both the WHOLE resource and THIS window:

| field | on | meaning |
|---|---|---|
| `ciphertext` | every window | base64 of this window's ciphertext bytes |
| `total_length` | every window | the FULL resource's ciphertext length in bytes |
| `offset` | every window | this window's start offset within the resource |
| `length` | every window | this window's byte length |
| `complete` | every window | whether this window ends the resource |
| `next_offset` | every window | the next window's offset, or **`null`** on the last one |
| `root` | every window | the generation root the window was served against |
| `inclusion_proof` | every window | base64 whole-resource Merkle inclusion proof |
| `chunk_lens` | prologue (once per stream, PAGED) | per-chunk ciphertext lengths of the WHOLE resource |
| `source` | node profile | `"local"` or `"remote"` — where this node served it from |

This table is normative and MUST agree field-for-field with `ChunkObject` in docs.dig.net's
`static/openrpc.json`, which is the ecosystem-wide publication of the same contract. All of
`ciphertext`, `total_length`, `offset`, `length`, `complete`, `next_offset`, `inclusion_proof` and
`root` are REQUIRED there; a node that omits any of them is non-conforming even when the bytes it
serves are correct.

`total_length` MUST be present on EVERY window, not only the last: a client allocates its
reassembly buffer from it before it has seen the last window. `next_offset` MUST be present on
every window as an explicit `null` when complete, so a client ending its loop on
`next_offset == null` can distinguish "the resource is complete" from "this server omitted the
field". Both requirements are load-bearing rather than cosmetic — omitting them took every
`*.on.dig.net` subdomain dark while this node returned correct ciphertext and a correct,
verifying inclusion proof, and reported no error anywhere (#2071).

`inclusion_proof` MUST ride EVERY window, and MUST always be PRESENT — as the empty string when
the served resource carries no proof, never as an absent key. It describes the whole resource, so a
client that resumes, or begins its stream at a non-zero offset, has no other source for it; sending
it only on window 0 leaves every later window of a multi-window resource unverifiable, which is
#2071's failure mode relocated to large resources rather than fixed. Present-and-empty is a fact a
client can act on; absent is one it must guess at.

The proof verifies the resource, NOT the window: verification requires
`proof.leaf == SHA-256(the whole reassembled ciphertext)`, so a client cannot check a window in
isolation and MUST hold the complete resource before verifying. Every window carries the proof so
that whichever window a client happens to receive first can supply it — not so that windows can be
verified independently.

`chunk_lens` is a PROLOGUE field: it describes how to split the REASSEMBLED resource, so a client
cannot act on it until it holds every window, and a client that begins mid-resource cannot decrypt a
multi-chunk resource and MUST fetch from the start. It is sent once per stream and MUST NOT be
repeated. On the peer length-prefixed frame stream it is **PAGED**: a layout exceeding
`dig_nat::MAX_CHUNK_LENS_PER_FRAME` (2048) entries cannot state itself on one frame, so it is split
into pages of at most 2048 entries each, and every frame carrying a page is stamped with the
`chunk_lens_offset` at which its page begins. When the requested bytes are exhausted before the
layout is fully sent, the remaining pages ride trailing **prologue-only continuation frames** — a
frame with a zero-length data payload that carries byte-`offset = 0` (NOT the ascending byte cursor,
which by then equals the resource length and would trip a reader's `offset >= max_len` establish
guard) and NO `chunk_index` (it begins no chunk, and a stale index would trip the reader's
ascending-index rewind guard). A prologue-only frame does NOT terminate the stream; the stream is
complete only once the bytes are exhausted AND every prologue page has been sent. (The single-frame
JSON-RPC `dig.fetchRange` response is not framing-bound and carries the whole layout on its one
frame.)

**Window size.** A window is at most **3 MiB** of ciphertext. This node currently IGNORES the
`length` request parameter and always serves a full window (or the remainder), where
`openrpc.json` documents `length` as a requested size clamped to the server maximum; a client MUST
therefore size its stride from the `length` it is GIVEN, never from the one it asked for. The
3 MiB figure is presently defined independently in three places — `WINDOW`
(`crates/dig-node-core/src/lib.rs`), `RPC_MAX_CHUNK` (hub.dig.net's retrieval Lambda) and
`RPC_CHUNK` (on.dig.net's resolver service worker) — and a client stride LARGER than the server
window produces gapped buffers. Consolidating it into `dig-constants` is tracked in DIG-Network/dig_ecosystem#2076; until
then any change to it MUST be made in all three.

**One builder, with one honest exception.** The locally-held read and the peer fetch-through MUST
both emit this envelope from the single shared builder (`content_window_envelope`) — a second
implementation of a shared wire shape is what produced #2071. The response-window cache is the
exception: it replays a previously-proxied UPSTREAM `result` verbatim, so a window cached from a
non-conforming upstream is re-served with whatever fields that upstream sent. The cache preserves
provenance rather than rewriting it; conformance there is the upstream's obligation.

Because a replayed window is indistinguishable on the wire from a freshly built one (it is stamped
`source: "local"` like any other local serve), the response-cache key MUST carry an envelope SCHEMA
version, and that version MUST be bumped whenever this envelope's shape changes. Without it an
upgraded node would keep serving windows captured under the OLD shape until they aged out of the
LRU — so "the fix is deployed" would not imply "the fix is what clients receive". Bumping the
version strands every prior entry by construction; no eviction pass or migration is required.

#### 5.5.1. `dig.getManifest` (#176 Phase C)

Resolves the store's normalized **PUBLIC MANIFEST** — the `.dig` format's data-section id 13
(digstore SPEC.md § the `.dig` format), the store's complete public file surface (the LATEST
version per path) as of a given capsule's commit. PUBLIC, unencrypted data; no `retrieval_key`.

- **Params**: `{ store_id, root }` — both 64-hex, a capsule identifier (`storeId:rootHash`),
  matching the shape of the other capsule-scoped read methods (`dig.getAvailability` items,
  `dig.fetchRange`).
- **Result on a hit with a manifest**: `{ schema_version, entries: [ { path, latest_root,
  generation_index, sha256_latest, version_count } ] }`, entries sorted ascending by `path`.
  Byte-identical to `PublicManifest::to_json` (the same renderer the digstore CLI's `manifest
  --json` and the `dig-client-wasm` `readPublicManifest` reader use).
- **Result when the module carries no `PublicManifest` section** (an older `.dig`, or a PRIVATE
  store whose paths must stay opaque): `result: null` — **NEVER an error**. Store-format §5.1: an
  optional section's absence is a normal, backwards-compatible outcome.
- **When this node does not hold the requested capsule at all**: `-32004` (the same
  `RESOURCE_NOT_AVAILABLE_AT_ROOT`/unavailable code `dig.fetchRange` reports on a miss) — distinct
  from the "held but no manifest" case above.
- Malformed `store_id`/`root` (not 64-hex) → `-32602` before any filesystem access.

##### Decoded-manifest memo — a BYTE budget, not an entry count (DoS bound, #2145)

`dig.getManifest`, `dig.getPublicManifest`, and `dig.getMetadata` all decode from the SAME whole-`.dig`
read (the public/metadata data sections share the wasm data section with the content chunk pool, so
the parse cannot seek past them). All three are on the ANONYMOUS public-read allowlist, so that decode
is memoized per `(cache_dir, store, root)` to keep a ~200-byte unauthenticated request from re-reading a
128 MiB capsule per call.

The memo is bounded in **total BYTES**, never in entry COUNT. A manifest entry's size is
publisher-controlled and unbounded (a `PublicManifest` is one row per public path; a
`MetadataManifest`'s `custom`/`links`/`authors`/… are open-ended), so an entry-count cap would let one
hostile capsule pin arbitrary memory. The memo MUST therefore:

- retain only the RENDERED JSON of each section (an exact byte length, never a hand-estimated size of a
  decoded attacker-shaped tree);
- bound the SUM of retained bytes across all entries to a fixed budget (`MANIFEST_MEMO_MAX_BYTES`,
  32 MiB — a hard RAM bound, NOT scaled by publisher input), evicting least-recently-used entries on
  insertion until within budget;
- REFUSE to retain any single entry over a per-entry ceiling (`MANIFEST_ENTRY_MAX_BYTES`, 4 MiB) — an
  oversized capsule is re-decoded per request under a process-wide serialization lock instead of pinned;
- a memo MISS always recomputes and MUST still succeed (never an error);
- `cache.clear` MUST DRAIN the memo (it is a process-lifetime residency with no idle TTL), so an
  operator can reclaim its RAM.

##### `dig.getMetadata` — the response ceiling (DoS bound, #2145)

`dig.getMetadata` renders the WHOLE publisher metadata section into one JSON-RPC response — it cannot be
windowed like `dig.getContent`/`dig.getCapsule`, whose 3 MiB windows seek the module. Because `custom`/
`links` are publisher-controlled, an oversized section is REFUSED with `METADATA_TOO_LARGE` (`-32015`)
when its rendered length exceeds `METADATA_RESPONSE_MAX_BYTES` (3 MiB, the same ceiling as a content
window), rather than rendered + re-serialized (3–4 in-RAM copies) into a ~100 MB response. The refusal is
a bounded error, never the oversized body. A normal (kilobyte) metadata section is served unchanged — the
ceiling only bites the hostile case.

##### `dig.getMetadata` — pre-decode input caps (memory-DoS bound, #2160)

The response ceiling above bounds the RENDERED output, but the danger is the DECODE that precedes it:
decoding the metadata section materializes each `custom` value from JSON TEXT into a `serde_json::Value`
tree, and the flat-numeric shape (`[0,0,…]`) expands ~16× (a 40 KB `custom` → ~640 KB of `Value` nodes).
A hostile `custom` filling a 128 MiB section therefore reaches ~2 GiB of transient `Value` on a ~1.9 GiB
host — BEFORE the rendered-length check can fire. Sizing that decoded output by hand is intractable
(five failed attempts); the node instead caps the INPUT structurally, before decode:

- **Section size** — an ENCODED metadata section over `METADATA_SECTION_MAX_BYTES` (3 MiB, equal to the
  response ceiling) is refused with `METADATA_TOO_LARGE` (`-32015`) without decoding. Rendering does not
  shrink these shapes, so any section whose encoded body clears 3 MiB would fail the response ceiling
  anyway — this only moves the same refusal ahead of the ~16× expansion. A section this size decodes to
  at most ~48 MiB of transient `Value`, and the cold decode is SERIALIZED so at most one runs at once.
- **`custom` shape** — before any `custom` value is parsed, its raw JSON text is streamed (never
  materialized) and refused with `-32015` if the map carries more than `MAX_CUSTOM_ENTRIES` (4 096)
  entries, or any value nests past `MAX_CUSTOM_JSON_DEPTH` (32) or exceeds `MAX_CUSTOM_JSON_ELEMENTS`
  (65 536) structural nodes. These bound the amplifier shapes that fit under the size cap.

Both caps run BEFORE `MetadataManifest::decode`, and the refusal verdict is memoized like any other, so a
repeated hostile request cannot re-drive the decode. A normal (kilobyte) metadata section decodes and
serves BYTE-IDENTICALLY — the caps only bite oversized or hostile-shaped input.

#### 5.5.2. Chat subsystem — `chat.send` / `chat.poll` (epic #793)

The node is the directed-message **TRANSPORT** for dig-chat: an application seals its own opaque
`DIGCHAT1` message body and the node wraps that blob in an e2e-sealed `dig-message` envelope
addressed to the recipient's `0x0010` BLS identity key, then dig-gossip directed-sends it over
opcode 220 (`DIG_MESSAGE`). The node NEVER parses the `DIGCHAT1` body — it is carried verbatim in
`dig_chat_protocol::ChatMessage::envelope` (message type id `0x0000_0200`, dig-message's dig-chat
band).

**Double seal (NC-1, content-blindness).** Two independent seals stack: the inner `DIGCHAT1` seal
the app applies, and the outer `dig-message` seal to the recipient's BLS key. A relay or on-path
peer sees only the outer ciphertext; a peer that terminates the outer seal still faces the inner
one. The node cannot expose chat plaintext even in principle. A conformance test asserts neither
the plaintext body nor the plaintext message id appears in the on-wire sealed bytes.

- **`chat.send`** — seal + directed-send. Params `{ recipient_did (64-hex), recipient_pub (base64,
  the recipient's 48-byte BLS G1 sealing key), peer_id (64-hex, the gossip directed-send target),
  envelope (base64, the opaque `DIGCHAT1` bytes) }`. Result `{ message_id }` (64-hex, a
  node-minted `SHA-256(sender_did ‖ counter ‖ envelope)`). Each send stamps a strictly-monotonic
  per-node anti-replay counter and a 5-minute expiry (dig-message §5.6/§5.6b). Errors: `-32050`
  (no node identity key), `-32602` (missing/malformed param), `-32051` (no peer network), `-32052`
  (seal or directed-send failed). The node seals as the node identity DID
  `SHA-256(node BLS G1 public key)`.
- **`chat.poll`** — drain the inbound inbox. No params. Result `{ messages: [{ sender_did (64-hex,
  the verified envelope sender), message_id (64-hex), envelope (base64, the opaque `DIGCHAT1`
  body) }] }`, in arrival order, leaving the inbox empty. The inbox is bounded (oldest evicted at
  capacity) so a paired peer cannot grow node memory without bound.

**Authorization (F1, #1946).** BOTH `chat.send` and `chat.poll` are **control-token gated** on every
transport (HTTP `POST /` and the `/ws` request plane), exactly like a `control.*` mutation: the caller
MUST present the master control token (§7.3) OR a valid paired controller token (§7a). A loopback
address does not authorize them — any local process can reach the RPC plane — because `chat.send`
wields the node's OWN `0x0010` signing identity to seal + BLS-sign an arbitrary directed message, and
`chat.poll` DRAINS (deletes) the inbound inbox, which an unauthorized process could otherwise use to
steal or delete another app's queued ciphertext. An unauthorized call is rejected with `-32030`
`UNAUTHORIZED` BEFORE any seal/send or inbox drain runs (the fail-closed empty-token rule of §7.2
applies — a blank/absent token is never a credential on either transport).

**Inbound path.** A received opcode-220 frame is opened (`dig-message` unseal → BLS-G2 signature
verify → anti-replay → expiry), routed through the chat `MessageRegistry`, and the decoded
`ChatMessage` is queued into the inbox. A sender the node cannot resolve to a BLS key is rejected,
never queued (fail-closed). This describes the inbound handler (`process_inbound_frame`), which is
implemented and unit-tested; the **live peer-network feed that invokes it is not yet wired** into
`run_peer_network` (see Deferred), so in the shipped build `chat.poll` returns empty until that
loop lands.

**Deferred (epic #793):** the **live inbound feed** — the `run_peer_network` loop that drains
`GossipHandle::inbound_receiver()` into `process_inbound_frame` — is not yet wired (the handler is
implemented + unit-tested but nothing in production calls it, so `chat.poll` is always empty until
this lands; it is gated on the sender-key resolver below). The sealing-key directory
(`resolveSealingKey`) that maps a recipient DID to its attested `0x0010` BLS key + gossip `PeerId`,
and the inbound sender-key resolver, are NOT in this MVP — the app supplies `recipient_pub` +
`peer_id` on `chat.send`, and the inbound resolver is caller-supplied. Group chat, onion routing, and receipt UX are out of scope; the five
chat message types (message, delivery/read receipts, typing, presence) are defined in
`dig-chat-protocol` but only `ChatMessage` surfaces to `chat.poll`.

#### 5.5.3. `cache.pushCapsule` — the publish→seed push (#1476)

The seed leg of the content-replication flywheel: the store owner hands a FRESHLY-COMMITTED `.dig`
capsule straight to their own node so the node becomes a discoverable DHT holder the instant the
content is published, instead of waiting to be asked for it first. It is the reverse of
`dig.getCapsule` (§5.5 served LOCALLY — one bounded window per request): the bytes are PUSHED
in windows the node reassembles, then verified and landed through the ONE shared land site every
other cache path uses (so a seeded capsule is discoverable byte-for-byte identically to a pulled one,
and lands + announces exactly once — SPEC §14.1/§14.3).

**Chunked wire.** A capsule exceeds the ~6 MB inline JSON-RPC ceiling, so it is pushed in ≤3 MiB
base64 windows (mirroring `dig.getCapsule`'s `CAPSULE_WINDOW_BYTES`). Params:
`{ store_id (64-hex), root (64-hex), data (base64, this window's bytes), offset? (u64, default 0),
total_length? (u64, default = this window's decoded length ⇒ single-shot), signature? (192-hex, a
96-byte BLS signature — required only in open mode, below) }`. Pushes are STRICTLY forward: the only
accepted `offset` is exactly the assembled length so far (no gaps, no overlaps); `total_length` is a
commitment fixed on the first window and constant after; and `total_length` may not exceed the
whole-capsule ceiling (`MAX_CAPSULE_BYTES`, 4 GiB). Result mirrors the chunk-ack shape:
`{ offset, complete (bool), next_offset (u64 | null), size_bytes }`, plus `served_root` on completion
and `already_cached: true` for an idempotent re-push. The client repeats with `offset = next_offset`
until `complete: true`.

**Verification, on the completing window (before landing).** (1) INTEGRITY: the reassembled bytes
MUST be a genuine `.dig` module committing exactly the requested `(store_id, root)` — checked with the
same digstore-bound verifier every other land runs. (2) IDEMPOTENCE: a capsule already held is a
no-op that neither re-writes nor re-announces (no double-announce). Only on a fresh, verified land
does the node write `<cache>/modules/<store>/<root>.dig` and announce itself a DHT holder.

**Trust posture — local-only by default (SECURITY-CRITICAL).** `cache.pushCapsule` is a MUTATOR with
a durable holder side effect. It is **absent from the peer allowlist**, so an inbound mTLS peer is
answered `-32601` before dispatch (audit #179), exactly like every `cache.*`/`control.*` method. Over
the loopback HTTP surface it carries the SAME control-token landing gate as `cache.fetchAndCache`
(master control token or a paired controller token — §7): a loopback address alone does not prove the
operator authorized it. The in-process FFI path is trusted-by-locality and ungated.

**Open mode — `DIG_NODE_PUSH_OPEN` (default `false`).** Setting `DIG_NODE_PUSH_OPEN=true` admits
`cache.pushCapsule` to the peer/mTLS surface. Locality no longer implies authority there, so an
OPENED push MUST additionally prove the caller is the store's **§21.6/§21.9 authorized writer** for
the target store: the pushed module commits a publisher public key whose `SHA-256` DERIVES `store_id`
(`store_id = sha256(publisher_pubkey)`, the DIG store-identity derivation), AND the request carries a
BLS signature over `SHA-256(root || store_id)` that verifies under that key. The merkle-integrity
check RECOMPUTES the merkle root from the capsule's own SERVED CONTENT — for each **current-generation**
`KeyTable` entry, `leaf = resource_leaf(concat_output(its ChunkPool ciphertexts))`, the leaves sorted
ASCENDING by `static_key`, folded with `MerkleTree::from_leaves` — and refuses the push unless it
reproduces the committed `CurrentRoot`. The recompute is SCOPED TO THE CURRENT GENERATION: the embedded
`KeyTable` is multi-generation (the producer stores one entry per (generation, resource), each stamped
with THAT generation's root), but the committed `CurrentRoot` is folded over the CURRENT generation only
(`current_generation_leaves(generations.last())`), whose `gen.root()` equals `CurrentRoot`. So the
recompute folds ONLY entries whose `entry.generation == CurrentRoot`; folding every generation's entries
over-counts and would false-reject the genuine current content of any store published then updated even
once (#2246). The recompute is also BOUNDED against a remote pre-auth OOM/CPU-DoS: `chunk_indices` is
attacker-controlled and permits repeated indices (the producer dedups chunks), so the TOTAL referenced
ciphertext bytes across the module is capped at `MAX_STORE_BYTES` and each resource's leaf is hashed by
STREAMING its ciphertexts into an incremental SHA-256 (O(1) memory) rather than materializing their
concatenation — without which a ~1 MB module addressing one chunk N times could reference gigabytes and
abort the allocator (#2246). The recompute resolves each reference through a `ChunkPool` PRE-INDEX built
in ONE linear pass (per-chunk byte ranges), so the whole recompute is O(pool + references), NOT the
Θ(references × pool) it would be if each reference re-walked the pool from offset 0 (the canonical
`read_chunk` is O(global_index)); an attacker could otherwise pin a CPU core for ≈Θ(module²) with a pool
of ZERO-LENGTH chunks + one entry referencing the highest index N times — and because zero-length chunks
add 0 bytes, the byte cap alone never fired. As additional defense-in-depth the CUMULATIVE reference
count across the current generation is capped at `MAX_STORE_BYTES / 4` (a genuine store cannot frame more
chunks than that 4-byte-minimum-framing ceiling permits), bounding scan+hash work even for zero-length
chunks (#2246). The attacker-supplied `MerkleNodes` digests are NEVER trusted for this
decision (retained only as a defense-in-depth cross-check that the served inclusion proofs match the
content): a single-leaf `from_leaves(vec![x]).root() == x` meant a `MerkleNodes = [chain_root]` plus an
empty/garbage `ChunkPool` recomputed to the committed root for free, admitting a contentless
phantom-holder capsule (#2246/#2240). An absent `KeyTable`/`ChunkPool`, a chunk index the pool cannot
satisfy, an undecodable section (including malformed `ChunkPool` framing), a `MerkleNodes`↔content
mismatch, referenced content exceeding `MAX_STORE_BYTES`, or references exceeding `MAX_STORE_BYTES / 4`
fails closed; a legitimately EMPTY store folds to `from_leaves(vec![]).root() == sha256(&[])` and passes. A header naming the chain root is
not proof the bytes hash to it. This
check gives INTEGRITY, never AUTHORITY — without the writer check an opened node would be an
unauthenticated cache-poison + DHT-announce-amplification surface (the #179/#1576 class). A push that
arrives on the peer surface with no signature, a signature under a key that does not derive
`store_id`, or a signature the store key does not verify is rejected (`-32001`) before landing.
`DIG_NODE_PUSH_OPEN` is dig-node-LOCAL (only dig-node reads it; deliberately NOT a `dig-constants`
value).

### 5.6. OpenRPC drift guard (conformance test)

`tests/openrpc_drift_guard.rs` pins the catalogue to reality and MUST be kept passing:

- every `served: "local"` method, dispatched through the real `handle_rpc`, MUST NOT return
  `-32601`;
- every `served: "passthrough"` method MUST return `-32601` from the node (the relay cue).

When a node-library change moves a method between `local` and `passthrough`, the catalogue MUST be
flipped in the same change or this test fails. The test is hermetic (empty params fail validation
before any network I/O; `dig.getContent` and `cache.fetchAndCache`, which would reach the network,
are asserted by classification only).

---

## 6. Discovery surface

### 6.1. `GET /health`

Returns `{ status: "ok", service, version, commit, mode: "local-node", addr, upstream, cache:
{ dir, cap_bytes, used_bytes, shared }, sync: { available }, peer_tier: { attached },
methods: [names…] }`. The fields `status`, `version`,
`mode`, `upstream`, `cache` are the stable probe contract (the v0.2 server's health shape);
additions MUST be additive. `cache.shared` reports whether the effective cache dir is the shared
canonical one (`true`) or a process-private fallback (`false`), from the read path's resolver.

`peer_tier.attached` (#1763) reports whether the P2P content engine is attached RIGHT NOW — the same
state a served response reports as `X-Dig-Peer-Tier` (§4.6). `status: "ok"` means the node is live and
answering; it does NOT imply a usable peer tier, since the HTTP surface opens before the peer network
attaches (§7.8). A client or harness that needs the peer tier MUST poll `peer_tier.attached` until it
is `true` rather than waiting a fixed interval.

### 6.2. `GET /version`

Returns `{ service, version, commit, protocol }` (§2; `version` is the one canonical version).

### 6.3. `GET /openrpc.json` and `rpc.discover`

Both return the same OpenRPC (spec version `1.2.6`) document generated from the method catalogue
and error enum. Each method object carries the machine-readable `x-requires-auth` extension; the
`info` object carries `x-control-auth` describing the control-token scheme (§7.3). Every method's
`errors` array is the full catalogue of §10.

### 6.4. `GET /.well-known/dig-node.json`

The canonical first-fetch discovery document: service identity + versions + protocol, the bound
`addr`, `upstream`, the live cache block (dir, cap/used bytes, shared), the full method catalogue
(name/served/summary/requires_auth), the full error catalogue, and pointers to `/health`,
`/version`, `/openrpc.json`, and the `rpc.discover` method. Its `endpoints` map also carries
`ws_status: "/ws/status"` (§4.5).

### 6.5. `GET /ws/status`

The WebSocket status/liveness channel — see §4.5 for the full message contract (this is the
discovery-surface cross-reference; §4.5 is normative).

---

## 7. Control plane (`control.*`)

This section is the **canonical node-control interface** — the ONE contract every node
controller speaks (the DIG Chrome extension's node UI, the DIG Browser "My Node" surface, the CLI,
any local tool). It is the cross-repo source of truth mirrored in the superproject `SYSTEM.md`
("dig-node control interface"); a consumer's node-control UI conforms to the method names, params,
result shapes, health/status schema, error codes, token model, and served port defined here — never
a parallel interface. A change to any of them is a coordinated cross-repo change (§4.1 in the
ecosystem contract) updating this SPEC, `SYSTEM.md`, and every consumer in one unit.

### 7.1. Role split

The read methods (`dig.*`, `cache.*`, `rpc.discover`) are open to any local consumer. The
`control.*` namespace MANAGES the node (pins, cache, sync, config, status) and is gated so a web
page a user merely visits — which can reach loopback but cannot read local files — cannot drive
the node.

The read methods (`dig.*`, `cache.*`, `rpc.discover`) are open to any local consumer. The
`control.*` namespace MANAGES the node (pins, cache, sync, config, status) and is gated so a web
page a user merely visits — which can reach loopback but cannot read local files — cannot drive
the node.

### 7.2. Authorization model — loopback + local capability token

Two layers, both REQUIRED:

1. **Loopback-only**: the whole server binds loopback (§4.1), so nothing off-machine reaches any
   method.
2. **Local token**: a `control.*` call MUST present a valid control credential — the master control
   token (§7.3) OR, for a non-administrative method, a paired controller token (§7.11); a missing or
   mismatched credential is answered `UNAUTHORIZED` (`-32030`, §10). Token comparison MUST be
   constant-time (`ct_eq`) so verification cannot be probed via a timing oracle.

Exactly the `control.` method prefix is gated (`is_control_method`); unknown `control.*` methods
still pass the auth gate first, then yield `METHOD_NOT_FOUND`. The pairing-administration methods
(`control.pairing.list`/`approve`/`revoke`, §7.11) require the MASTER token specifically — a paired
token is NOT accepted for them. The ONE exception is `control.wallet.balance` (`is_open_control_read`):
a READ-ONLY chain read of a PUBLIC address with no custody, so it is served WITHOUT a token like the
other reads — it still routes through `dispatch_control` (so it stays in the control catalog and gets
its CLI verb) but the server skips the token requirement. No mutation or custody method is ever open.

### 7.3. The control token

- **File: `<state_dir>/control-token`** (§7.3a), where `<state_dir>` is the machine-wide, identity-
  INDEPENDENT daemon state dir — NOT the per-user config dir. This is REQUIRED (#501): on a real
  install the daemon runs as a service under a different OS account (Windows LocalSystem, a root
  daemon) than the operator's interactive CLI. A per-user path resolves DIFFERENTLY for the two
  identities, so the CLI would never see the token the service wrote (and would mint a phantom the
  daemon never trusts). Resolving a machine-wide dir independently of the running user makes the
  daemon and the CLI read the SAME token.
- Value: 32 bytes drawn from the operating-system CSPRNG rendered as 64 lowercase hex characters.
  Generated at first run; subsequent runs (and other same-host processes/users) read the same
  value. The token MUST never be committed or logged.
- Presentation, either of (header preferred): the `X-Dig-Control-Token` request header, or the
  `params._control_token` field. Blank presentations are treated as absent.
- **The daemon MAY create the token (write); an operator CLI MUST NOT mint one.** The CLI
  (`dig-node pair` / any control tool) reads the token READ-ONLY; if it is missing or unreadable it
  MUST fail with a precise remedy (§7.3a) rather than write a fresh token the daemon does not trust.
- **The operator control client MUST connect DIRECT to loopback, ignoring proxy environment.** The
  HTTP client that carries the master control token to the node's loopback address MUST be pinned to
  a direct connection (`no_proxy`), so an `HTTP_PROXY`/`HTTPS_PROXY` in the operator's environment
  can NEVER route the token-bearing `control.*` POST through an interposed proxy. (The default HTTP
  proxy behaviour has no automatic loopback bypass.)
- **Trust a pre-existing token file ONLY when it is owned by a TRUSTED principal (owner
  verification).** Before the daemon loads and trusts the bytes of an EXISTING `control-token`, it
  MUST verify the file's OWNER; a foreign-owned token is DELETED and REGENERATED, never returned.
  This closes the residual where an unprivileged local user plants a KNOWN token in the machine-wide
  state dir (a `%PROGRAMDATA%` squat, or the narrow window during a service harden) so the daemon
  (LocalSystem) reads + trusts it and the attacker learns the control token → full local control
  (local privilege escalation). Trusted owners: **Windows** — `S-1-5-18` (SYSTEM) or `S-1-5-32-544`
  (Administrators) always; a NON-service (dev/operator) run ALSO trusts the CURRENT process user's
  own SID (so a dev token in the legacy per-user dir keeps working), and a SERVICE run requires
  SYSTEM/Administrators. **Unix** — owner uid `0` (root) always, else the CURRENT effective uid AND
  mode `0600` (owner-only); a group/other-readable or foreign-uid token is untrusted. This is layered
  BENEATH the §7.3a state-dir hardening (which already purges a squatter-owned dir on a service run)
  as defense-in-depth: it also guards the non-hardened dev path and any harden gap.
- If the token cannot be persisted (unwritable state dir) OR cannot be minted (the OS CSPRNG is
  unavailable), the daemon MUST fall back to an in-memory token that no controller can read — the
  control plane fails **closed**; the read plane is unaffected. It MUST NEVER emit a guessable
  token in place of a CSPRNG-drawn one.
- **The authorization gate MUST NEVER accept an empty or absent token, on ANY transport.** A blank
  presentation is treated as absent (HTTP header/`params._control_token` AND the WS frame `token`
  field alike), and a node whose configured token is the empty fail-closed sentinel authorizes
  NOTHING — the empty string is never a valid credential (a constant-time comparison of two empty
  strings would otherwise match). This holds identically for the master control token and the paired
  controller tokens; a node with no usable token gates every `control.*`/custody call closed.
- Randomness source: the operating-system CSPRNG on EVERY platform (`getrandom` — `getrandom(2)`/
  `/dev/urandom` on Unix, `BCryptGenRandom` on Windows). There is NO software (non-CSPRNG) fallback:
  when the OS CSPRNG is unavailable the daemon fails closed (above) rather than derive a token from
  time/PID/ASLR entropy. The same CSPRNG source mints the pairing ids/tokens (§7.11) and, layered on
  loopback bind + same-host-readable-file possession, is the token's secrecy guarantee — not an
  attacker's inability to estimate mint time/PID/ASLR.

### 7.3a. The daemon state dir — location, ACL, threat model (#501)

The state dir holds ONLY the control/auth state — the control token (§7.3) and the paired-token
store (`paired-tokens.json`, §7.11). The bulk per-user `.dig` cache and `config.json` (§3.5–3.6) do
NOT move; they stay per-user (shared with the browser/digstore, #96).

**Resolution order** (the daemon and every operator CLI MUST resolve this identically, so it MUST
NOT depend on `$HOME`/`%LOCALAPPDATA%`/the running user):

1. `DIG_NODE_STATE_DIR` (env override) — wins outright (tests + custom deploys).
2. The first machine-wide candidate that already EXISTS — Windows `%PROGRAMDATA%\DigNode`
   (`C:\ProgramData\DigNode`); Linux `/var/lib/dig-node` then `/etc/dig-node`; macOS
   `/Library/Application Support/DigNode`.
3. Only for a SERVICE run (self-identified via `DIG_NODE_RUN_CONTEXT=service`): the first
   machine-wide candidate it can create. A bare CLI MUST NOT create a machine-wide dir.
4. Else the LEGACY per-user dir (the parent of `config.json`) — the back-compat fallback that keeps
   a non-service `dig-node run` as a normal user working exactly as before (additive).

**Service data dirs — identity + cache MUST NOT live under `$HOME`.** On a SERVICE run the node MUST
resolve its persistent identity seed and its content cache UNDER the resolved state dir
(`<state_dir>/identity`, `<state_dir>/cache`) rather than under the invoking user's home, and MUST do
so before the identity is first loaded.

Both otherwise default to a home-relative path (`dirs::config_dir()/dig` for the seed, `$HOME/DigNode/
cache` for the cache), which a system service cannot use: the packaged Linux unit runs with
`ProtectHome=true`, so `$HOME` is unreadable, seed creation fails with `EROFS`, the node starts with
NO identity, and the peer network refuses to come up — a stock package install never joins the
network. The same reasoning binds the macOS launchd daemon and the Windows service, which is why this
is a property of a SERVICE RUN and not of one packaging target.

An `DIG_IDENTITY_DIR` / `DIG_NODE_CACHE` value the operator set explicitly MUST be preserved; a CLI
run MUST be left untouched, keeping the user's identity shared with their other DIG tools.

**Creation + ACL — the HARDENING CONTRACT.** The state dir holds the control token that grants FULL
local control, so its ACL MUST NOT be world/all-users-readable. On Windows this is the HARD case:
`%PROGRAMDATA%` grants `BUILTIN\Users` "create subfolder", so ANY low-priv user can pre-create
`C:\ProgramData\DigNode`, become its CREATOR OWNER, and keep `WRITE_DAC` forever — a naive
`icacls /inheritance:r /grant:r` (which never resets OWNER nor purges foreign explicit ACEs) leaves
that squatter able to rewrite the DACL and read the token → local privilege escalation. A
pre-existing machine dir MUST therefore NOT be trusted blindly.

On a SERVICE run (self-identified via `DIG_NODE_RUN_CONTEXT=service`), BEFORE the daemon writes or
reads the control token, the resolved MACHINE state dir MUST be HARDENED and READBACK-VERIFIED:

1. Resolve the interactive read-grant principal as a real SID from the CURRENT PROCESS TOKEN
   (`whoami /user`), NEVER the spoofable `%USERNAME%`/`%USERDOMAIN%` env. REJECT it if it is a
   well-known group/broad SID (`S-1-1-0` Everyone, `S-1-5-11` Authenticated Users, `S-1-5-7`
   Anonymous, `S-1-5-32-545` Users) or SYSTEM (`S-1-5-18`). A LocalSystem service thus resolves NO
   interactive grant; it instead PRESERVES an installer-set interactive read grant if one is
   discoverable on a TRUSTED (SYSTEM/Administrators-owned) pre-existing dir.
2. Create the dir if absent — but NEVER early-return when it already exists (a squatter may have
   pre-created it); always run steps 3-6.
3. Take ownership so the squatter loses `WRITE_DAC`: `icacls D /setowner *S-1-5-18 /T` (owner ⇒
   SYSTEM). A pre-existing dir with an UNTRUSTED owner is PURGED (`remove_dir_all`) and recreated.
4. Purge ALL foreign explicit ACEs: `icacls D /reset /T`.
5. Lock the DACL: `icacls D /inheritance:r /grant:r *S-1-5-18:(OI)(CI)F *S-1-5-32-544:(OI)(CI)F` and,
   only when a valid interactive read grant survived step 1, append `<user_sid>:(OI)(CI)R` (READ only
   for the interactive user, never full). Principals are always addressed by SID literal, never the
   localized name.
6. READBACK-VERIFY as the acceptance gate, reading the owner SID + DACL ACEs directly through the
   Win32 security API (`GetNamedSecurityInfoW` → owner + DACL, `GetAce`, `ConvertSidToStringSidW`),
   SID-based and launching NO process. (It MUST NOT shell out to a PowerShell `Get-Acl`: on a host
   that cannot autoload `Microsoft.PowerShell.Security` that spawn throws, which used to be
   misread as a hardening failure and destroy a correctly-hardened dir.) The gate asserts: NO
   Everyone/Users/Authenticated-Users/Anonymous ACE; owner is SYSTEM (or Administrators); SYSTEM +
   Administrators present with full; the interactive read grant present iff one was applied; NO
   principal beyond those; and inheritance disabled. A readable-but-violating DACL FAILS.
7. FAIL CLOSED on a genuine failure: if step 3, 4, or 5 (the SET path) fails, OR step 6 reads a
   DACL that VIOLATES the gate, hardening returns an error, the dir is best-effort DELETED, and the
   daemon MUST NOT write the token there — it falls back to an ephemeral, unshared dir + a random
   in-memory token so the control plane is UNAUTHORIZABLE (never served from an attacker-controlled
   dir). The read plane is unaffected. But when step 6 cannot READ the DACL AT ALL (a transient
   condition), hardening treats the applied lockdown (the step 3-5 SET commands that already
   succeeded) as authoritative and PRESERVES the dir — the defense-in-depth readback never gates
   the applied lockdown, so a correctly-hardened dir is never destroyed merely because it could not
   be read back, and the service converges to a hardened dir with a minted control token.

`dig-node install` (run elevated by the interactive user) applies the SAME hardening as the
installing user, setting owner = SYSTEM and granting THAT user READ, so the LocalSystem service's
startup harden later sees a TRUSTED dir and PRESERVES the grant. Idempotency: running the harden
twice on a legit dir yields the same final ACL. On Unix the dir is `0700` and the token file `0600`,
owned by the daemon identity (root on a real install under root-owned `/var/lib`, which is not
squattable); the installer additionally best-effort `setfacl`s READ for the `SUDO_USER`.

The CLI (non-service) NEVER hardens (it is not elevated) — it only READS an existing machine dir,
else falls back to the LEGACY per-user dir. A non-service dev run on the legacy per-user dir does NOT
invoke the machine-dir hardening (that dir is already user-scoped).

**Threat model.** The control token grants full local control of the node (mint controller tokens,
change pins, drive wallet-adjacent control). A machine-wide file readable by every local user, or one
sitting in a squatter-controlled dir, would be a local privilege-escalation vector — any user could
seize control of a node running as another identity. The invariant that MUST hold either way is: NO
Users/Everyone/Authenticated-Users ACE and owner = SYSTEM. The ACL is defense-in-depth layered on the
loopback bind + token-possession model, BUT because a loose ACL is itself a priv-esc, the SERVICE-run
harden is FAIL-CLOSED (unlike the best-effort dev/self-create path, where an `icacls`-unavailable
tighten failure does not hard-fail startup).

**Degraded case + remedy.** When the daemon bootstraps the dir itself as SYSTEM/root (the installer
did not pre-create it), the interactive user is not a trustee and cannot read the token. The
`UNAUTHORIZED` (`-32030`) error and the operator CLI MUST then print the PRECISE remedy — the exact
token path, and that it needs elevation (Administrator / `sudo`) or the install-user read ACL —
rather than a generic hint. The CLI distinguishes token-present-but-unreadable (the service-vs-user
split → "elevate / grant read") from token-absent ("start the node so it mints one"). This
distinction MUST be made by the READ error KIND, NOT by `path.exists()`: under a locked-down DACL the
invoking user cannot even STAT the file, so `path.exists()` reports `false` and would misclassify an
ACL denial as "not found" (#772). A `PermissionDenied` read ⇒ present-but-unreadable; any other read
error ⇒ absent. The token-absent remedy MUST also name the STALE-service recovery: a service left
over from an older build (installed before the machine-wide state dir) never mints the token at this
path, so reinstalling the current binary (`dig-node uninstall`, then an elevated `dig-node install`,
then `dig-node start`) is the fix for a "service running yet token missing" report on an in-place
upgrade.

### 7.4. Control methods

All results/errors use the standard envelopes of §5.1. `storeId` and `rootHash` are canonical
lowercase 64-hex; a capsule reference is `storeId:rootHash`. Malformed refs yield
`INVALID_PARAMS`; runtime failures yield `CONTROL_ERROR`; capability absences yield
`NOT_SUPPORTED`.

| Method | Params | Result (essentials) |
|---|---|---|
| `control.status` | — | `running`, `service`, `version`, `commit`, `protocol`, `uptime_secs`, `addr`, `upstream`, `cache`, `hosted_store_count`, `cached_capsule_count`, `pinned_store_count`, `sync.available` |
| `control.config.get` | — | `addr`, `port`, `upstream`, `upstream_override`, `cache_dir`, `cache_shared`, `config_path`, `sync_available` |
| `control.config.setUpstream` | `upstream` (URL string; blank clears) | `upstream` (normalized), `requires_restart: true` — persisted, effective on next start (§3.4) |
| `control.log.setLevel` | `filter` (an `EnvFilter` directive, e.g. `debug` or `info,dig_node_core=debug`) | `filter` (echoed) — live-applied via the `dig-logging` reload handle, effective immediately, NOT persisted (§11); `INVALID_PARAMS` on a missing/malformed directive, `CONTROL_ERROR` when logging is not installed in the process |
| `control.cache.get` | — | `cap_bytes`, `used_bytes`, `capsule_bytes`, `response_bytes`, `dir`, `shared` |
| `control.cache.setCap` | `cap_bytes` (number) | `cap_bytes` (floored at 64 MiB) |
| `control.cache.clear` | — | `cleared: true` |
| `control.hostedStores.list` | — | `stores[]`: `store_id`, `pinned`, `capsule_count`, `total_bytes`, `capsules[]` (capsule, root, size_bytes, last_used_unix_ms) — cached stores ∪ pinned stores |
| `control.hostedStores.pin` | `store` = `storeId[:rootHash]` | `store_id`, `root`, `pinned: true`, `fetch` = `{status: cached\|failed\|skipped, …}` (pre-fetch attempted only with a concrete root AND sync available; a skipped fetch reports `reason`) |
| `control.hostedStores.unpin` | `store` = `storeId[:rootHash]` | `store_id`, `unpinned` (whether a pin was removed), `evicted_capsules` — MUST evict every cached capsule of the store |
| `control.hostedStores.status` | `store` = `storeId[:rootHash]` | `store_id`, `pinned`, `capsule_count`, `total_bytes`, `capsules[]` |
| `control.sync.status` | — | `available` (always `true` — the chunked capsule download needs no identity), `method: "chunked-capsule-download-with-section-21-clone-fallback"`, `identity_loaded`, `pinned_total`, `pinned_synced`, `whole_store_trigger_supported` (`true` — a store id alone is enough) |
| `control.sync.trigger` | `store` = `storeId[:rootHash]`, or `store_id` [+ `root`] — the root is OPTIONAL; without one the node resolves the store's CHAIN-ANCHORED tip and syncs that generation | `status: "synced"`, `root`, `size_bytes`, `served_root` |
| `control.wallet.balance` | `address` (bech32m string), `asset` (`"xch"` \| `"dig"`, default `"xch"`) | `balance` (confirmed, spendable — JSON NUMBER, u64 base units), `pending` (unspent + unconfirmed — JSON NUMBER, u64 base units), `source` (`"db"` \| `"fallback"` — which tier produced the figure, §18.7b), `synced` (bool), `peak_height` (`u32` or `null`). Matches `dig-node-control-interface` 0.3.0's `WalletBalanceResult { balance: u64, pending: u64, .. }` and dig-app's `BalanceResponse { balance: u64 }` — a Rust-to-Rust numeric contract, never a decimal string. The wallet backend tracks the base-unit total as `u128` (headroom for summed intermediate math); the wire boundary saturating-casts to `u64` (a single address's balance can never exceed `u64::MAX` mojos, ~18.4M XCH). READ-ONLY chain read of a PUBLIC address (no seed/signing key). Reuses the B.6 sync-state routing: the local DB when the address is the wallet's own and the DB is synced, else the coinset fallback. Per §18.7b, `source`/`synced`/`peak_height` describe the TIER that answered: a `"db"` answer reports `synced: true` and the node's own peak; a `"fallback"` answer reports `synced: false` and `peak_height: null`. This is an OPEN read (`is_open_control_read`, no token); the cheap local-DB fast path is unbounded, but the EXPENSIVE coinset-fallback leg is subject to a GLOBAL token-bucket rate bound (defense-in-depth against an open-read amplification/oracle sweep — #1957): a burst of arbitrary-address fallback reads beyond the bound is refused with `WALLET_RATE_LIMITED` (§10), while any single honest read (DB fast path or one fallback) always succeeds. `$DIG` scopes by the canonical CAT asset id `digstore_chain::dig::DIG_ASSET_ID`. A synced empty address is a SUCCESS `{balance:0, synced:true}`, never an error; the read-failure shapes are DISTINCT errors `WALLET_NO_CHAIN_SOURCE`/`WALLET_NOT_SYNCED`/`WALLET_READ_FAILED`/`WALLET_RATE_LIMITED` (§10), never a fabricated `0`. `INVALID_PARAMS` on a missing/malformed `address` or a bad `asset`. |
| `control.peers.ping` | `peer` (a 64-hex `peer_id`, or a dialable `host:port` with IPv6 bracketed), `peer_id` (OPTIONAL 64-hex — pins the identity the presented certificate MUST derive) | The connection-ladder report — see §7.4a. `INVALID_PARAMS` on a missing/blank `peer`; `CONTROL_ERROR` when no peer network is running; `PEER_PING_REFUSED` (§10) when the anti-amplification gate refuses before dialing. |

### 7.4a. `control.peers.ping` — the connection-ladder diagnostic

Given a peer, the node MUST attempt EVERY rung of the §19.1 traversal ladder against it and report
each one, then grade the run. It answers "is this peer reachable, and HOW?" — the question a raw TCP
port probe cannot answer, since an open port says nothing about whether the mTLS handshake succeeds
or whether the certificate binds the identity asked for.

**Result shape.**

```json
{
  "peer": "<the argument as given>",
  "expected_peer_id": "<64-hex>|null",
  "verdict": "direct" | "relayed-only" | "unreachable" | "identity-mismatch" | "unresolved",
  "severity": "ok" | "warn" | "error",
  "summary": "<one line of plain language>",
  "ladder": [
    { "tier": "direct", "result": "connected", "remote_addr": "[2001:db8::1]:9444",
      "family": "ipv6", "observed_peer_id": "<64-hex>", "elapsed_ms": 41 },
    { "tier": "hole-punch", "result": "failed", "reason": "<dig-nat's own text>", "elapsed_ms": 5000 },
    { "tier": "upnp", "result": "unavailable", "reason": "<the local precondition that is missing>" },
    { "tier": "relayed", "result": "skipped", "reason": "overall deadline of 45s reached first" }
  ]
}
```

`tier` is one of `direct` / `upnp` / `nat-pmp` / `pcp` / `hole-punch` / `relayed`, in §19.1 rank
order with the relay LAST. A rung's `result` is one of `connected` / `failed` / `identity-mismatch` /
`unavailable` / `skipped`; only `connected`, `failed` and `identity-mismatch` carry `elapsed_ms`,
since the other two dialed nothing. `family` distinguishes `ipv6` from `ipv4`, so an IPv4-only
success is visible as the §5.2 finding it is.

**Normative requirements.**

- **Report the LADDER, not the winner.** Every rung MUST appear. A rung the deadline pre-empted is
  reported `skipped` with a reason, never dropped. Probing MUST NOT stop at the first success:
  "relayed succeeded" is only actionable next to "direct failed, and why".
- **"Not configured here" is NOT "failed there".** A tier the node cannot compose at all — UPnP with
  no local port mapping, NAT-PMP/PCP with no IPv4 gateway, hole-punch with no reflexive address or
  coordinator, relayed with no reservation — MUST be reported `unavailable`, with a reason naming the
  missing LOCAL precondition, and MUST NOT carry an `elapsed_ms` (nothing was dialed). On an ordinary
  node several rungs compose to nothing, so reporting them as failures would blame the peer for this
  node's configuration and show a healthy result as several red rows. `unavailable` never changes the
  verdict, which is decided only by what CONNECTED.
- **Identity outranks reachability — including over UNreachability.** When `peer_id` is known or
  pinned, a rung that reaches a certificate deriving a DIFFERENT `peer_id` MUST grade
  `identity-mismatch` / `severity: "error"`. Note the mechanism, because it inverts the naive
  expectation: dig-tls pins the expected id inside its certificate verifier, so a mismatch ABORTS the
  handshake and no connection is ever produced. The mismatch therefore arrives as a dial FAILURE, and
  an implementation that only inspects successful connections will report an impersonation — or a
  stale address-book entry — as `unreachable`, which is the reading a user would act on backwards. A
  rung MUST report `result: "identity-mismatch"` with the answering `observed_peer_id` where the
  handshake error discloses it; the classification MUST NOT depend on recovering that id. An explicit
  `peer_id` param always wins over what the node believes is at that address.
- **A relay-only success is `warn`, never `error`.** Most peers are behind NAT and are relay-
  reachable only; that is the normal shape of the network, and grading it as failure would report a
  healthy network as broken.
- **No anonymous dial.** dig-nat pins the expected `peer_id` in its TLS verifier, so an address the
  node cannot name an identity for MUST be answered `verdict: "unresolved"` explaining that `peer_id`
  is required — NEVER downgraded to a bare TCP probe, which would give exactly the "an open port
  means connected" answer this method exists to replace. Identities are resolved ONLY from the
  connected pool (mTLS-authenticated) or the caller's explicit pin.
- **Read-only on the DIG network.** Each rung's connection MUST be dropped as soon as it is graded:
  no pooled session, no announcement, no retained relay reservation, no stored state. One documented
  exception, because it is a real side effect: the UPnP rung is a PORT-MAPPING method, so composing it
  calls `add_port_mapping` and leaves a ~2h mapping on the operator's OWN router, once per ping. That
  is this node's NAT device rather than network state, and the ordinary dial ladder does the same on
  every peer dial — but it MUST NOT be described as "writes nothing".
- **Authorization: the control token, master OR paired.** `control.peers.ping` is a `control.*` method
  and is NEVER peer-reachable (absent from `dig_rpc_protocol::Method`, so the mTLS peer wire answers
  `-32601`) and never on the public-read allowlist. It is NOT a pairing-admin method, so a PAIRED
  controller token may drive it as well as the master token — deliberate, since a paired local UI
  (dig-app) is the intended consumer of the diagnostic and the method is read-shaped. Target
  restriction is a separate, tracked concern shared with `control.peers.connect`.
- **Bounded.** Each rung is bounded by the node's per-tier dial timeout (5s) and the run by an
  overall deadline (45s), so a black-holed address cannot hang the caller. A consumer MUST allow for
  the full deadline: this is the one control method that can legitimately take tens of seconds, and
  a client timeout below it would report a healthy ladder as a transport failure.
- **Not an amplifier.** The method makes the node dial a caller-supplied address, so it MUST be
  bounded: at most ONE ladder runs at a time, and at most 6 runs START per 60s. A refusal is
  `PEER_PING_REFUSED` (§10) and MUST NOT be reported as a ladder result — nothing was dialed. A
  refusal for concurrency MUST NOT consume rate budget, and an unresolvable argument MUST NOT
  consume it either.
- **One implementation.** The rungs MUST be dialed through the same NAT config builder every other
  node dial uses, narrowed only by `enabled_methods`, so the diagnostic cannot drift into a parallel
  prober that disagrees with what the node really does.

### 7.5. Ownership boundary

Cache and sync operations MUST proxy to the node library
(`cache_list_cached`/`cache_remove_cached`/`cache_fetch_and_cache`/`clear_cache`/
`set_cache_cap_bytes`/`cache_cap_bytes`/`cache_used_bytes`/`cache_usage`/`sync_whole_store`); the shell never duplicates read/cache
logic. The shell owns only the pin registry and the upstream override.

### 7.6. Pin registry

Persisted under the shell-namespaced `pinned_stores` key in `config.json` (§3.6) as an array of
`{ store_id, root? }` objects (lowercase 64-hex). `pin` is idempotent (re-pinning replaces the
entry, never duplicates); `unpin` of an absent store is a no-op reporting `unpinned: false`. Pins
survive cache eviction: a pinned-but-uncached store MUST still appear in
`control.hostedStores.list`.

### 7.7. Consumer conformance (the cross-repo parity contract)

A node controller is any local surface that queries or manages a running dig-node. All consume the
one interface above; what differs is only how far each reaches, gated by whether it can read the
same-host control token.

- **Open status/discovery surface (no token — every consumer, including a sandboxed web extension).**
  A consumer that cannot read a local file (a Manifest V3 browser extension, a visited web page) is
  limited to the UNGATED surface: `GET /health`, `GET /version`, `GET /.well-known/dig-node.json`,
  `rpc.discover`/`GET /openrpc.json`, and the read methods (`dig.*`/`cache.*`). This is sufficient to
  render node liveness, identity (service/version/commit), the bound addr, upstream, and cache
  cap/used. Node detection uses the §5.3 ladder (explicit `server.host` override > `dig.local` >
  `localhost:9778` > `rpc.dig.net`); the localhost tier MUST target the §3.2 default port `9778`.
- **Token-gated management (a same-host process controller).** The mutating + privacy-sensitive
  `control.*` methods require the control token from `<state_dir>/control-token` (§7.3/§7.3a). Only a
  process that can read that file — the DIG Browser "My Node" UI (a native process), the CLI, a local
  tool — can drive them. A sandboxed extension MUST NOT attempt to read the token; it MAY still CALL
  `control.status` and, on the canonical `-32030 UNAUTHORIZED` (§10), fall back to deep-linking a
  same-host controller for management. It MUST branch on the machine `data.code` (`"UNAUTHORIZED"`),
  never the numeric value alone.
- **`control.status` is the canonical status shape (a stable consumer contract).** A status consumer
  MUST be able to read these fields from `control.status` `result` (snake_case, additive-only): the
  store/capsule counters `hosted_store_count`, `pinned_store_count`, `cached_capsule_count`; the
  nested `cache.used_bytes` (and `cache.cap_bytes`); the nested `sync.available`; and `upstream`.
  Renaming or removing any of them is a breaking cross-repo change. The `control.status` field-name
  conformance is pinned by an integration test (`tests/server.rs`).
- **Lifecycle (start/stop/restart) is the CLI/OS-service contract, NOT an RPC.** A controller starts,
  stops, or restarts a node through the §8 CLI subcommands (`install`/`uninstall`/`start`/`stop`/
  `status`) and the §9 OS-service manager — never a `control.*` RPC (a node cannot RPC-restart itself,
  and lifecycle is an OS-service-manager concern). Liveness is observed via `GET /health` (`status:
  "ok"`) and `control.status` (`running: true`); `dig-node status` probes `/health` (§8.3). There is
  no `control.start`/`control.stop`/`control.restart`.

### 7.8. Integration-test launch surface

To let a consumer's end-to-end test exercise parity against a REAL node, `dig-node run` MUST bring up
a clean foreground node with zero out-of-band setup: it binds `127.0.0.1:$DIG_NODE_PORT` (default
`9778`), prints its readiness line to stderr, serves `GET /health` immediately, and exits gracefully
on Ctrl-C/SIGTERM (§9.5) so a test harness can `spawn → poll GET /health → drive control.* / read →
signal-stop`. `DIG_NODE_PORT` MUST be honored so a test picks a free port; `DIG_NODE_DIGLOCAL=0`
SHOULD be set in tests to skip the privileged `:80` dig.local bind. The control token for a
token-gated test is read from `<state_dir>/control-token` after startup; a test SHOULD set
`DIG_NODE_STATE_DIR` to an isolated temp dir (§7.3a) so its token/paired-token state is hermetic
regardless of any real machine-wide state dir on the host.

**The peer tier is NOT up when `/health` first answers (#1763).** The HTTP surface opens immediately,
while the peer network attaches seconds later, so a read issued as soon as `/health` responds skips
Tier 2 — reaching a configured upstream, or MISSING outright when none is configured (the default).
A harness that intends to exercise the P2P path MUST poll
`peer_tier.attached` on `/health` (§6.1) until it is `true` — a fixed sleep is neither sufficient nor
checkable — and MUST confirm `X-Dig-Peer-Tier: attached` on the response it measures (§4.6). A result
gathered from a response carrying `unattached` is a measurement of the gateway, not of peer replication.

### 7.9. Cache-method families (open `cache.*` vs gated `control.cache.*`)

The node exposes cache operations under TWO method families, BY DESIGN — a consumer picks the one
its transport/authorization permits. This is a deliberate dual surface, not a duplication to
collapse:

- **`cache.*` — open, node-engine-native (no token).** `cache.getConfig`, `cache.setCapBytes`,
  `cache.clear`, `cache.listCached`, `cache.removeCached`, `cache.fetchAndCache` — the node ENGINE's
  own cache RPC (dispatched by `dig_node_core::handle_rpc`, `served: "local"`, §5.5), reachable by
  any local consumer over `POST /` AND over the in-process FFI (`dig_rpc`) the DIG Browser's
  `chrome://settings` `DigCacheHandler` calls. Loopback-only is the only boundary; these are NOT
  token-gated.
- **`control.cache.*` — token-gated operator aliases.** `control.cache.get`, `control.cache.setCap`,
  `control.cache.clear` (§7.4) — the control plane's cache view/cap/clear, requiring the control
  token (§7.2). They wrap the SAME node-library cache operations behind the control-plane gate so a
  same-host process controller manages the cache through the one authorized `control.*` surface.

The name differences are intentional and STABLE: `getConfig`/`setCapBytes` are the engine's
long-standing FFI/RPC names; `get`/`setCap` are the control plane's terse aliases. Neither family is
renamed (backwards-compat). Guidance: a controller holding the token SHOULD use `control.cache.*`
(uniform control surface); a consumer without the token — a sandboxed extension, or the in-process
FFI — uses `cache.*`. `control.cache.get` mirrors `cache.getConfig`, `control.cache.setCap` mirrors
`cache.setCapBytes`, `control.cache.clear` mirrors `cache.clear`.

The full authoritative method + error set (both families, the `control.*` operator methods, and the
read/peer methods) is the one defined by this SPEC and mirrored in `SYSTEM.md`; consumers implement
SUBSETS of it (the extension drives `control.status` + `dig.getContent`; the browser a wider subset)
but MUST NOT diverge names or shapes. The eventual single shared home for this catalogue is the
`dig-rpc-protocol` crate (§1.4/§1.5); the node's dispatch + peer allowlist are adopted from it.

### 7.10. Cache LRU order + telemetry (#279)

The OPEN `cache.*` family is the surface a browser controller (the DIG Chrome extension's control
panel) uses to MANAGE how much disk space is reserved for cached `.dig` content under the node's LRU
eviction. These additive fields/methods complete that surface; all are `served: "local"`,
`requires_auth: false`, and additive-only (§5.1 — an older reader ignores the new fields).

- **`cache.listCached` — per-entry `lru_rank`.** Each entry in the `cached` array carries, beside
  `capsule` / `store_id` / `root` / `size_bytes` / `last_used_unix_ms`, an integer **`lru_rank`**:
  `0` is the LEAST-recently-used capsule (the NEXT one the size cap would evict), increasing with
  recency, forming a strict `0..n` permutation over the listed entries. The order is exactly the
  oldest-`last_used_unix_ms`-first order `plan_eviction` applies (ties broken by list position), so a
  controller renders the eviction queue directly without re-deriving it. `last_used_unix_ms` is the
  file mtime, bumped to now on every local serve.

- **`cache.setCapBytes { cap_bytes }` — the RESERVED cap.** Sets the reserved disk space for cached
  content, **floored at 64 MiB** (a `cap_bytes` below the floor is raised to it), and returns the
  applied `{ cap_bytes }`. `cache.getConfig` returns the live `{ cap_bytes, used_bytes, cache_dir,
  shared }`.

- **`cache.stats` — session cache telemetry (new).** Result:
  `{ cap_bytes, used_bytes, entry_count, total_bytes, evicted_count, evicted_bytes, refetch_count,
  content_cache: { hits, misses }, tiers: { tier0_precache, tier1_demand, tier2_bribed } }`.
  `entry_count`/`total_bytes` are the count and summed on-disk size of cached capsules;
  `evicted_count`/`evicted_bytes` are the disk-cache LRU evictions since the node started;
  `content_cache.hits`/`misses` are the decoded-content (RAM) cache lookups since start. All
  counters are process-lifetime (reset each start), never persisted. See §7.10e for
  `refetch_count` and `tiers`.

### 7.10e. Cache observability metrics (#1991, epic #1934)

`cache.stats` (§7.10) exposes the metrics a controller (the dig-chrome-extension control panel; the
relay-globe per-location cached-store count, #1933) needs to observe cache HEALTH, not just its
current contents. Each field is sourced from a REAL counter or, where the underlying signal does not
exist yet, an honestly-stubbed placeholder — never a fabricated number.

- **`refetch_count`** — whole-capsule NETWORK lands since process start: bytes actually pulled over
  the wire and written to disk, as opposed to a RAM decode-cache miss (`content_cache.misses`, which
  can hit an already-on-disk capsule with no network at all). There are exactly TWO landing write
  paths in the crate, and each bumps this counter once at its own successful write, together
  covering every genuine re-download with no overlap: `Node::sync_module_from` — the choke-point
  every ON-DEMAND path (`cache.fetchAndCache`, chain gap-fill, fetch-side backfill §7.10d(a))
  funnels through — and `module_reshare::promote_into_cache`, the reshare-warm land, which is a
  SEPARATE write-then-rename that never calls `sync_module_from`. A failed sync/promotion (no
  upstream reachable, verification rejected, a tampered/mismatched artifact) never increments it.

- **`tiers.{tier0_precache,tier1_demand,tier2_bribed}`** — per-`CacheTier` (§7.10a) occupancy, each
  shaped `{ occupancy, wired }`. `wired: false` means the tier has no live occupancy source yet — its
  `occupancy` is a fixed `0`, never a guess — and `wired: true` means the figure is real:
  - **`tier1_demand`** is **`wired: true`** today: `occupancy` is the inbound-demand ledger's
    (§7.10d) own bounded-LRU entry count — the number of DISTINCT stores currently tagged
    `Tier1Demand` by real peer/local demand. This needs no cache wiring to be honest; the ledger
    already tracks exactly this.
  - **`tier0_precache`** and **`tier2_bribed`** are **`wired: false`**: no tier-0 prefetch loop and
    no tier-2 bribed-retention mechanism exists yet (later epic-#1934 children), so there is nothing
    to count. The shape is fixed now (`occupancy`/`wired` fields present) so a controller written
    against it today needs no change when those children wire a real source — only `wired` flips to
    `true` and `occupancy` starts moving.

All `cache.stats` counters remain process-lifetime (reset each start, never persisted) and additive
(§5.1) — an older reader that does not know `refetch_count`/`tiers` still parses the fields it does.

### 7.10a. Cache relevance + tier model + eviction precedence (#1986, epic #1934)

The `relevance` module (`crates/dig-node-core/src/relevance.rs`) is the PURE, deterministic scoring
core the disk cache consults to decide WHAT is worth keeping, WHAT to sacrifice first, and WHEN a
fresh candidate may displace an incumbent. It performs NO I/O and reads NO clock — time enters only
as caller-supplied tick counters — so its decisions are reproducible and auditable. This subsection
specifies the contract; the live wiring into the on-disk LRU (§3.4/§7.10) is delivered by later
children of epic #1934 and is out of scope here.

**Tiers + eviction precedence.** Every cached entry belongs to a `CacheTier`:
`Tier0Precache` (speculatively fetched), `Tier1Demand` (fetched for a real local read), or
`Tier2Bribed` (retained because a backer paid). Cross-tier eviction precedence is fixed by the tier
ALONE — **tier2 > tier1 > tier0**, i.e. Tier0 is sacrificed first and Tier2 last — so speculative
precache can never evict content a user or a paying backer asked for. Relevance score orders entries
only WITHIN a tier, never across tiers. `evict_key(entry) -> (tier_rank, last_access_ticks)` yields
the eviction sort key: sorting entries by it ASCENDING gives exactly tier0-oldest → tier1-oldest →
tier2-oldest (LRU within each tier), which is the order the cap MUST evict in. `tier_rank` is
`Tier0Precache = 0`, `Tier1Demand = 1`, `Tier2Bribed = 2`.

**Relevance score.** `relevance(store: &RelevanceInputs, node: &NodeContext) -> RelevanceValue` is a
weighted sum:
`xor·proximity + scarcity·scarcity_term + demand·demand_term + recency·recency_term
+ pin_adjacent·[adjacent] + pinned·[pinned]`.

- **XOR proximity is the PRIMARY, ungameable signal.** Proximity is derived from
  `content_id XOR peer_id` and MUST be a strictly decreasing function of that distance (closer =
  higher). The reference map is `1 - (hi128 / 2^128)` over the top 128 bits of the distance. It is
  ungameable because an attacker cannot choose the victim's `peer_id` and cannot cheaply grind a
  `content_id` that lands near it (a 256-bit preimage search), so junk cannot be made to look like
  "this node's responsibility". Every other signal is a bounded ADDITIVE bonus.
- **Replication scarcity is CLAMPED (load-bearing anti-gaming).** `known_provider_count` is UNTRUSTED
  and MUST be clamped to `[1, 32]` before use; the resulting term lies in `[0, 1]` (fewer providers →
  higher) and is scaled by a weight strictly smaller than the XOR weight. A flooded count (→ `u32::MAX`)
  clamps to the ceiling (scarcity → 0) and a deflated count (0) clamps to the floor (scarcity → 1), so
  a lie can neither DOMINATE the score nor ZERO it — the XOR + demand terms survive regardless.
- **Local demand + recency + pin adjacency** are bounded additive bonuses: demand saturates at 16
  reads, recency decays as `1/(1 + age/1000)` (age in ticks; `None` ⇒ 0), and pin-adjacency adds a
  fixed small bonus. An explicit pin (`is_pinned`) adds a large bonus that deliberately overrides the
  heuristics (a pin is a direct operator instruction).
- **Weight invariant.** The default weights keep the XOR term strictly dominant over the sum of the
  gameable secondary bonuses, so proximity always leads.

**Displacement hysteresis.** `should_displace(incumbent, candidate, margin) -> bool` returns true
only when `candidate > incumbent + margin` (strict). The margin is an anti-thrash band: without it,
two near-equal stores would ping-pong in and out of the cache each sweep. At or below the margin the
incumbent stays.

### 7.10b. Tier-0 knapsack selector (#1988, epic #1934)

The `tier0_selector` module (`crates/dig-node-core/src/tier0_selector.rs`) is a PURE, deterministic
selector that decides WHICH speculative-precache candidates are worth keeping under a small
sub-budget, given each candidate's size and a relevance score already computed by §7.10a's
`relevance`. Like `relevance`, it performs NO I/O and reads NO clock. It does NOT sample the DHT for
candidates (a later epic-#1934 child) or fetch/evict anything against the live cache — that wiring
is out of scope here.

**Sub-budget.** Tier-0 speculative precache is bounded to `TIER0_BUDGET_FRACTION` (0.10) of the
node's WHOLE cache cap (`DIG_NODE_CACHE_CAP`/§7.10 `cache_cap_bytes`), never the whole cap —
`tier0_budget_bytes(whole_cache_cap_bytes) -> u64` computes this fraction as pure arithmetic over a
caller-supplied cap (the cap lookup itself is I/O and stays outside this module). Tier-0 is an
opportunistic bet, and reserving only a slice of the cap keeps it from crowding out real Tier1/Tier2
retention even before the tier-based eviction precedence (§7.10a) has to bite.

**Selection.** `select_within_budget(candidates: &[Candidate], budget_bytes: u64) -> Vec<usize>`
returns the indices of the candidates to keep, using GREEDY selection by value-density
(`relevance / size_bytes`, descending) rather than an exact 0/1 dynamic-programming knapsack — DP is
`O(n * budget)`, which is disproportionate at a GiB-scale budget; greedy is `O(n log n)` and
near-optimal (it can only under-fill the last unit of budget by at most one candidate's size). The
selected set's total size MUST NOT exceed `budget_bytes`. A candidate with `size_bytes == 0` is
treated as infinitely dense (free to keep) and is always included rather than causing a
divide-by-zero.

**Displacement hysteresis.** `should_displace_tier0(incumbent, candidate, margin) -> bool` is a
thin, named wrapper over §7.10a's `should_displace`, reusing its `candidate > incumbent + margin`
rule so tier-0 re-selection against an existing held set does not thrash a fetch/evict/refetch cycle
on marginal score differences. The tier-0 selector's own default margin is
`DEFAULT_HYSTERESIS_MARGIN` (0.05), overridable per call.

### 7.10c. DHT candidate sampling + anti-Sybil quorum reconciliation (#1987, epic #1934)

The `dht_sampling` module (`crates/dig-node-core/src/dht_sampling.rs`) produces the CANDIDATE SET that
feeds §7.10a's `RelevanceInputs` (each candidate's `content_id` + an untrusted `known_provider_count`).
It does NOT score candidates (§7.10a) or select/fetch them (§7.10b + the fetch child) — discovery and
reconciliation ONLY. It splits a PURE reconciliation policy from the network I/O so the
security-critical logic is unit-tested with no sockets.

**Observation model.** A `PeerObservation { peer_id: [u8;32], holdings: Vec<ObservedCandidate> }` is
ONE peer's reported provider view — the shape of a dig-dht `DhtService::provider_snapshot` (the RLY-009
`get_dht_records` view, #1935): each `ObservedCandidate { content_id: [u8;32], provider_count: u32,
size_hint: Option<u64> }` is that peer's untrusted claim about one content KEY (the 32-byte
`ContentId::to_key` keyspace point). The DHT provider snapshot carries no size, so `size_hint` is
optional; the true size is learned at fetch time.

**Random keyspace sampling.** `sample_keyspace_points(rng: &mut impl KeyspaceRng, k) -> Vec<[u8;32]>`
picks `k` keyspace points to probe. Randomness enters ONLY through the injected `KeyspaceRng`
(a self-contained non-cryptographic `SplitMix64` seeded from node state — MUST NOT be used for keys or
nonces), so coverage is deterministic under a seed. Points are reached in production with the dig-dht
routing primitive `find_node`/`known_closest`, which accepts ANY key — so sampling probes arbitrary
regions rather than only ids the node already holds, spreading coverage across the whole keyspace.
`DEFAULT_SAMPLE_POINTS` = 8.

**Anti-Sybil quorum reconciliation.** `reconcile(observations: &[PeerObservation], policy:
&QuorumPolicy) -> Vec<Candidate>` admits a content key ONLY when at least `policy.min_distinct_peers`
(`DEFAULT_QUORUM_MIN_PEERS` = 3) DISTINCT peers independently report it. Observations are collapsed per
peer FIRST — one peer listing a key many times (or across regions) is a SINGLE vote — so a lone
lying/Sybil peer's unique injections never reach the candidate set. Each admitted key's
`known_provider_count` is the LOWER MEDIAN of the reporting peers' claimed counts (NEVER the max): a
single peer inflating its count to `u32::MAX` moves only one tail sample and cannot drag the median
while honest peers outnumber it; the mirror deflation-to-zero attack fails the same way. `size_hint`
is the lower median of the supplied sizes, or `None`. Output is sorted by `content_id`. §7.10a's
`[1, 32]` provider-count clamp remains the final defense on whatever count survives here.

**Residual model (stated, not hidden).** Distinct-peer quorum is a COST MULTIPLIER, not proof of
honesty: an attacker minting `M` distinct mTLS identities that all corroborate one key still clears the
bar. That residual is bounded by the surrounding layers — keyspace sampling forces the attacker to
cover the whole space, the §7.10a XOR proximity primary means a corroborated junk key scores by an id
the attacker cannot grind toward this node, and the `[1, 32]` clamp caps the surviving count.

**Composition seam.** `sample_candidates(probe: &dyn NeighbourhoodProbe, rng, sample_points, policy)`
ties sampling + probing + reconciliation over a `NeighbourhoodProbe` seam (`observe_near(point) ->
Vec<PeerObservation>`), reconciling ALL probed regions TOGETHER so the quorum is whole-round.

**Concrete probe (`neighbourhood_probe` module, #1989 child 4a).** `DhtNeighbourhoodProbe` implements
`observe_near`: it routes toward `point` with dig-dht `find_node`, then for each returned `Contact`
opens/uses an mTLS peer connection and calls the `dig.getProviderSnapshot` peer RPC (§7.4 in
dig-node-core `SPEC.md`), turning each RESPONDING peer into ONE `PeerObservation`. Two properties are
normative and security-critical:

- **Identity comes from the verified session, never the wire.** A `PeerObservation.peer_id` is the
  anti-Sybil VOTE identity, so it is set from `SHA-256(verified mTLS server-cert SPKI DER)` of that
  session — NEVER from `Contact.peer_id` and NEVER from any field of the snapshot payload (the
  `DhtRecordsAnswer` is deliberately identity-free). A peer lying about its id in its `Contact` either
  fails the pinned handshake (contributing nothing) or is attributed to the cert it actually presented.
  An unreachable/silent/erroring peer yields NOTHING (never an error), matching the seam contract.
- **Volume caps before reconcile.** Each peer's holdings are truncated at `MAX_HOLDINGS_PER_PEER` (=
  the server's 512-key cap) and the whole round's observation volume at `MAX_OBS_PER_ROUND` (4 096),
  so neither a single verbose peer nor a Sybil cluster can exhaust memory in `reconcile`.

The server half — answering `dig.getProviderSnapshot` from this node's local provider store, counts
only, `max_keys` clamped — is specified in dig-node-core `SPEC.md` §7.4/§7.4a. The prefetch loop that
DRIVES the probe (selection, fetch, cache writes) is child 4b, not this module.

### 7.10d. Tier-1 caching triggers — fetch-side backfill AND inbound demand (#1990, epic #1934)

A store earns the `Tier1Demand` tier (§7.10a) — real, non-speculative demand, evicted only after all
`Tier0Precache` — from EITHER of two independent triggers. Both are the same conclusion ("this content
is genuinely wanted here") reached from opposite directions:

- **(a) Fetch-side backfill (SPEC §5.6 / §14.3b).** THIS node reads a resource it does not hold, is
  served it from another node/upstream, and background-pulls the whole `.dig` so its NEXT read is
  local. This is what THIS node fetched. It is gated `ReadOrigin::Local`: a REMOTE peer's read served
  through this node MUST NOT trigger it, or a stranger could drive this node into pulling + caching +
  DHT-announcing content of the peer's choosing (an amplification primitive).

- **(b) Inbound demand (this section).** A remote PEER asks this node to serve a resource from a store
  (a `dig.fetchRange`/`dig.fetchModuleRange` request over the peer surface). That request is direct
  evidence this node's keyspace neighbourhood WANTS the content, so the demanded store is recorded in
  the in-memory INBOUND-DEMAND LEDGER (`crates/dig-node-core/src/inbound_demand.rs`), which tags it
  `Tier1Demand` and bumps a saturating demand count. The ledger is the FIRST live tier-tagging: the
  on-disk LRU cache (§3.4/§7.10) keys entries by path and orders them by file mtime alone and carries
  NO per-entry acquisition tier, so this in-memory, process-lifetime map (never persisted, additive
  over the `.dig` format and the LRU layout) is the source the relevance demand term
  (`RelevanceInputs.local_read_count`, §7.10a) and the tier-based eviction precedence consult for
  peer-demanded stores.

**The ledger is BOUNDED (memory is not remotely amplifiable).** Recording is always-on and fed by a
remote peer's on-wire store id, and the format check accepts any 64-hex value (not only stores that
exist), so a peer could otherwise mint permanent entries from the 2^256 keyspace until the node OOMs.
The ledger MUST therefore be a bounded LRU: at most `MAX_DEMAND_ENTRIES` (default 65_536) distinct
stores, evicting the least-recently-demanded entry on overflow (a re-demanded store is refreshed and
survives over colder entries). Worst-case memory is bounded by the cap — on the order of ten-odd MiB
— REGARDLESS of remote request volume; distinct-id spam churns through the fixed footprint rather
than growing it.

**What is always on vs. opt-in.** Recording inbound demand (the count + `Tier1Demand` tag) is
UNCONDITIONAL — it moves no content bytes and pulls no capsule, and its memory is bounded by the cap
above, so it carries no bandwidth/content amplification risk and always runs. The whole-`.dig` PULL on
inbound demand is OPT-IN, default OFF, gated by
`DIG_NODE_INBOUND_DEMAND_CACHE` (only an explicit `on`/`1`/`true`/`yes` enables it). A peer-triggered
pull is an amplification primitive of exactly the shape trigger (a)'s `ReadOrigin::Local` gate exists
to close.

**XOR-proximity admission on the pull (ENFORCED, #2014).** The opt-in pull is gated a SECOND time by a
keyspace-proximity admission that binds even when the flag is on: the pull fires ONLY when the demanded
capsule's DHT key (`ContentId::capsule(store_id, root).to_key()`) lies in THIS node's keyspace
neighbourhood — its XOR proximity to the node's own `peer_id` clears
`relevance::INBOUND_DEMAND_MIN_PROXIMITY` (the keyspace midpoint, `0.5`: the content id is closer to
this node's `peer_id` than a uniformly-random point, i.e. shares the top keyspace bit). This is the
same `xor_proximity` primitive and the same reference `peer_id` the tier-0 precache selector (§7.10a /
§7.10b) scores against, so both paths share ONE neighbourhood definition. What the gate binds — and
what it does NOT: an attacker cannot move this node's `peer_id`, so the gate confines peer-steerable
demand-caching to keys NEAR this node's own identity — never an arbitrary far-keyspace target. It does
NOT make naming a near key cost an on-chain mint: a peer may name any `(store, root)` whose key falls
near our `peer_id` and, on an opted-in node, drive a CHEAP DHT provider-lookup for it (a key that names
no real store simply finds no providers and the pull fails there — the low cost is "no providers", not
a per-key mint). The on-chain-mint + merkle cost binds a LATER step — actually becoming a cached
HOLDER: a pulled module is bound to its `root` by merkle verification — the admit gate
(`ChainAnchoredModuleVerifier`, shared by the reshare-admit pull AND the `cache.pushCapsule` land via
`verify_capsule_integrity`) RECOMPUTES the merkle root from the capsule's own SERVED CONTENT (per
`KeyTable` entry, `leaf = resource_leaf(concat_output(its ChunkPool ciphertexts))`, leaves sorted
ASCENDING by `static_key`, folded via `MerkleTree::from_leaves`) and refuses (`NotAnchored`) unless it
equals the committed `CurrentRoot`. The attacker-supplied `MerkleNodes` digests are NEVER trusted for
the admit decision (only cross-checked for served-proof consistency): trusting them let a single-leaf
`MerkleNodes = [chain_root]` plus an empty/garbage `ChunkPool` recompute to the committed root for free
and admit a contentless phantom-holder capsule (#2246/#2240). So a header-matching but
tampered/incomplete `.dig` (or one with an absent `KeyTable`/`ChunkPool`, an out-of-range chunk index,
or an undecodable section) is never admitted; a legitimately EMPTY store folds to `sha256(&[])` and is.
It is never SERVED as current
unless `root` equals the chain-anchored tip (the serve-time read-path pin, §7.10d(a) / §14.4). So the
worst a near-key attacker extracts from an opted-in node is a bounded, single-flighted, byte-capped
pull of REAL near-neighbourhood content of a possibly-old generation — never caching of fabricated,
junk, or out-of-neighbourhood content. The gate FAILS CLOSED: a node with no known self-identity (the
FFI/consumer path) or a non-canonical `(store, root)` admits no pull. The read itself is still served normally — the gate governs only the demand-driven
CACHE. The DEFAULT stays OFF; flipping it on (and any tightening of the midpoint bar toward a
routing-aware k-closest test, which depends on live network size) is a separate deliberate pass.

**Shared pull machinery.** When the opt-in pull fires, it reuses the SAME whole-capsule backfill body
as trigger (a) (`Node::spawn_capsule_backfill`): the `DIG_NODE_BACKFILL_ON_MISS` kill switch + a live
P2P content engine, an owned self-reference to spawn the detached task, a concrete `(store, root)`, an
already-held skip, and the ONE shared `(store, root)` single-flight acquisition gate (§21.3 / #1614) —
so both tier-1 triggers and the reshare warm can never drift in how they pull, dedupe, verify, or
announce, and an already-held store is never re-pulled.

### 7.10f. Tier-0 eager-precache loop — the governed round (#1989 child 4b, epic #1934)

The `tier0_prefetch` module (`crates/dig-node-core/src/tier0_prefetch.rs`) is the GOVERNED
orchestration that turns the DHT-sampling flywheel into actually-cached speculative content. It ties
the pure/seam pieces — §7.10c sampling+reconcile, §7.10a relevance, §7.10b knapsack selection — into
one self-driven ROUND: `sample_candidates` → size resolution → relevance score → `select_within_budget`
→ governed fetch (merkle-verify + hard byte-cap + cache tagged `Tier0Precache` + announce). The loop
is self-driven (it reads NO attacker-supplied trigger), so it is not the amplification vector the
inbound-demand pull (§7.10d(b)) is; every value an attacker can influence (they populate DHT provider
snapshots) is nonetheless bounded BEFORE it costs bandwidth or disk. The following governors are
NORMATIVE:

- **Off-switch, DEFAULT-ON.** `tier0_precache_enabled()` reads `DIG_TIER0_PRECACHE`; the loop is ON
  unless an explicit falsy value (`0`/`off`/`false`/`no`, case-insensitive) disables it. DEFAULT-ON is
  the deliberate stance for a self-driven, quorum-corroborated, XOR-relevant, byte-capped pull (unlike
  the inbound-demand pull, which is default-OFF because it is peer-triggered). `run_round` takes the
  resolved enablement as an injected `bool` parameter (the caller reads the env once per round), so the
  round is a pure function of its arguments.
- **Small-disk no-op (#1927).** `should_run_loop(cache_cap_bytes)` is `false` when the derived tier-0
  sub-budget (§7.10b `tier0_budget_bytes`, 10% of cache) is below `MIN_USEFUL_TIER0` (64 MiB); the
  caller checks this ONCE at bring-up and does not spawn the loop, degrading gracefully on a tiny disk.
- **Backoff-when-serving.** A round yields ENTIRELY (`RoundSkip::Busy`) when the `LoadSignal` reports
  the node is serving real inbound reads — speculative precache always defers to genuine demand.
- **Rate limit.** `RoundRateLimiter` is a token bucket on BOTH stores/window AND bytes/window (bytes is
  the load-bearing limit; bandwidth is the real cost). A fetch proceeds only when both buckets admit it,
  atomically (a refused byte-take never consumes a store token).
- **Size resolution — NEVER zero an unknown.** A candidate's size is the reconciled median `size_hint`
  when present; otherwise an ADMITTED candidate spends at most ONE bounded metadata probe (capped at
  `MAX_SIZE_PROBES_PER_ROUND` = 32 per round), else it is DROPPED for the round. An unresolved size is
  never treated as 0 (which would make it maximally dense in the knapsack).
- **Hard byte-cap at fetch.** Each selected store is fetched under a hard cap of
  `min(reported_hint, remaining_sub_budget)`; the fetcher enforces the TRUE store size against that cap
  and ABORTS + discards an over-size store (`DiscardReason::ExceededByteCap`) — the
  under-report-size-then-bloat defence. The selected total never exceeds the tier-0 sub-budget.
- **Merkle-verify before cache; never execute.** The fetch reuses the existing verified download path,
  so content is verified against the confirmed root before it lands and is never opened/executed;
  verification failure discards (`DiscardReason::VerifyFailed`).
- **Tier precedence.** Cached stores are tagged `Tier0Precache` and sacrificed FIRST. `effective_tier`
  is the MAX-across-ledgers rule (§7.10a `CacheTier::rank`): a store this loop precached that a peer
  later demands is promoted to `Tier1Demand`, so precache can never evict genuinely-demanded content.
- **Anti-Sybil identity carries forward from §7.10c/4a unchanged** — candidates come ONLY from
  `sample_candidates`, whose votes are attributed to the probe's mTLS-verified session `peer_id`.

**Size + wiring status (normative gap — the fetch seam's preimage requirement).** `run_round` is
complete as the governed orchestration over three concrete seams: `SizeProbe`, `Tier0Fetcher`, and
`LoadSignal`. A candidate carries a DHT `content_id` = `SHA-256(ContentId::canonical_bytes)` (§7.10c) —
a ONE-WAY key. Every merkle-verified fetch path (`find_providers`/`fetch_resource`/
`Node::gap_fill_generation`) is addressed by the `ContentId` PREIMAGE `(store_id, root)`, and merkle
verification itself requires the confirmed `root`. A concrete `Tier0Fetcher` therefore REQUIRES a
`content_key → (store_id, root)` resolution that the counts-only `dig.getProviderSnapshot` surface
(§7.10c, §7.4a) deliberately does not carry, and that the node otherwise holds only for stores it
already knows (subscriptions/chain-watch §7.10c/§14.2). That resolution is supplied by the
`dig.resolveCapsule` peer RPC (dig-node-core `SPEC.md` §7.4): a HOLDER answers a one-way `content_key`
with the verifiable `(store_id, root, size_bytes)` preimage it recomputes from its own holdings
(`ContentId::capsule(store, root).to_key()` equals the requested key), disclosing only the preimages of
capsules it already publicly provides. The SERVER half of that resolve is child PR-1 of the flywheel
live-wiring; the client resolver and the `Tier0Fetcher`/spawn wiring that consume it are the following
children (PR-2/PR-3). Until those land the governed round + its seams are the normative contract,
exercised end-to-end against injected seams.

### 7.11. Control-token pairing for browser controllers (#280)

An MV3 browser extension cannot read the `<state_dir>/control-token` file, so it cannot drive
token-gated `control.*` mutations. PAIRING lets it obtain its OWN scoped, revocable controller token
after LOCAL operator approval, WITHOUT ever exposing the master token. Two OPEN bootstrap methods +
three MASTER-gated administration methods, all loopback-only.

**OPEN methods (no token):**

- **`pairing.request { client_name }`** → `{ pairing_id, pairing_code, expires_ms }`. Creates a
  PENDING pairing. `pairing_id` is a 32-hex secret returned only to the requester; `pairing_code` is
  a 6-digit compare-codes value the requester DISPLAYS. Pending requests expire after 5 minutes; the
  node caps concurrent pendings (oldest evicted past the cap).
- **`pairing.poll { pairing_id }`** → `{ status, token? }` where `status` ∈
  `"pending" | "approved" | "expired" | "unknown"`. On `"approved"` the minted `token` is returned
  and the pending entry is CONSUMED (the token is delivered exactly once). The extension stores the
  token and presents it as `X-Dig-Control-Token` on subsequent `control.*` calls.

**MASTER-token-gated administration** (a paired token is NEVER accepted here — §7.2):

- **`control.pairing.list`** → `{ pending: [{ pairing_id, pairing_code, client_name, created_ms,
  expires_ms }], tokens: [{ id, client_name, created_ms }] }`. The token VALUE is never listed.
- **`control.pairing.approve { pairing_id }`** → `{ approved: true, client_name, token_id }`. Mints a
  fresh 64-hex scoped token, PERSISTS it to `<state_dir>/paired-tokens.json` (§7.3a, restricted,
  atomic), and marks the pending entry approved so the requester's next `pairing.poll` returns it. Approval is
  the CONSENT step: it requires the master token (a local file read), so only the machine's operator
  can grant a pairing.
- **`control.pairing.revoke { token_id }`** → `{ revoked: bool, token_id }`. Removes the token; the
  gate rejects it on the very next request (the store is consulted per request).

**Flow (compare-codes consent).** (1) The extension calls `pairing.request` and shows
`pairing_code`. (2) The operator runs `dig-node pair` (which reads the master token), sees the
pending request + its code + `client_name`, CONFIRMS the code matches the extension, and runs
`dig-node pair approve <pairing_id>`. (3) The extension's `pairing.poll` returns its scoped token.
(4) The extension drives `control.*` mutations with it. `dig-node pair revoke <token_id>` undoes it.

**Security properties (MUST hold).** Loopback-only, same as `control.*`. Approval requires the master
token, so consent is gated on local-machine control; the compare-codes step defeats a concurrent
rogue request (a visited page's) being approved by mistake. The `pairing.poll` response carrying the
token is readable only by an allowed CORS origin (`chrome-extension://…`, §4.3) — a foreign web
origin is CORS-blocked from reading it (and blocked at preflight from sending a `control.*` token
header). A paired token is SCOPED (it authorizes `control.*` mutations but not pairing administration)
and REVOCABLE. All token comparisons are constant-time.

**Paired-token store.** `<state_dir>/paired-tokens.json` (§7.3a) = `{ "tokens": [{ id, token,
client_name, created_ms }] }`, restricted (dir ACL), atomic writes. The auth gate accepts the master token OR any token in
this store (except for the pairing-administration methods).

### 7.12. Paired-token authorization for wallet methods (#370)

The pairing framework (§7.11) authorizes `control.*` mutations. The thin-client model (epic #365)
extends the SAME paired-token gate to the **wallet method surface**: over the authorized loopback
surface, every wallet MUTATION and every custody-lifecycle method (§18.20) requires the master control
token OR a valid paired token; an unauthorized caller (no token, a wrong token, or a revoked token) is
rejected with `-32030 UNAUTHORIZED` before the method runs.

**Gated wallet methods (MUST present a token).** The custody-lifecycle group (§18.20 —
`wallet.create` / `wallet.import` / `wallet.restore` / `wallet.unlock` / `wallet.lock` /
`wallet.status` / `wallet.list` / `wallet.select` / `wallet.delete`), the node-managed unlock-auth group
(§18.24 — EVERY `auth.*` method: `auth.status` / `auth.get_method` / `auth.set_method` / `auth.set_mode` /
`auth.enroll_totp` / `auth.enroll_passkey_begin` / `auth.enroll_passkey_finish` / `auth.unlock` /
`auth.sign_unlock` / `auth.lock`), and the mutation group (the send/spend group §18.9, the offer suite
+ DID/NFT mint & transfer §18.9a, and the state-changing record-update actions §18.16) are all gated.
These methods are NEVER relayed upstream — a signing/custody request must never leave the loopback node;
an authorized call is served locally by the node-custodied wallet (or, until the wallet surface is served
on a given transport, returns a catalogued error — it is never proxied to the public gateway).

**Open wallet methods (no token).** Wallet READ methods (`get_*`) follow the read plane (§7.2): open to
local consumers. The recommendation of epic #365 is that the whole wallet WS session be paired-gated once
the bidirectional WS transport (#369) carries it; the security-critical MUST is that no mutation or
custody op ever runs unauthorized.

**Node-local backup is not a wallet method.** Seed/mnemonic reveal (§18.20 backup) is reachable ONLY on
the node-local self-origin surface (§16.3) / a `dig-node wallet backup` CLI — NEVER over the paired
boundary, so key material never crosses to a paired caller even with a valid token.

**Classification is pure + tested.** `wallet_authz::classify` maps a method to its class
(read | mutation | custody | pairing-admin | non-wallet) and `wallet_authz::authorize` decides allow/deny,
unit-tested exhaustively: an unpaired caller is denied on every mutation/custody method; a paired token
authorizes a mutation but NOT pairing administration; a revoked token is denied on the next request.

### 7.13. DIG auto-update beacon proxy (`control.updater.*`, #515)

The DIG auto-update beacon (`dig-updater`, a separate installable service — DIG-Network/dig-updater
SPEC §§1–13) checks daily for new releases of the DIG binaries and installs them behind a signed
trust chain. dig-node exposes a THIN proxy to it over the SAME `control.*` gate (§7.2) — it never
re-verifies the beacon's signed manifest and never decides what to install; it only reads the
beacon's world-readable status mirror and shells its own elevation-gated CLI.

| Method | Params | Result (essentials) |
|---|---|---|
| `control.updater.status` | — | `installed: false` when the beacon has no status.json yet (never an error); else `installed: true`, `status` = the beacon's `status.json` verbatim (dig-updater SPEC §13.2: `schema`, `version`, `channel`, `paused`, `paused_until`, `last_check`, `last_check_kind`, `last_outcome`, `last_reason`, `last_detail`, `components[]`, `next_wake`, `trust_state`) |
| `control.updater.setChannel` | `channel` (string: `"nightly"` or `"stable"`; `"alpha"` is a deprecated alias for `nightly`) | The beacon CLI's `channel set <channel> --json` output verbatim (dig-updater SPEC §13.3). Thin passthrough — the token is forwarded VERBATIM and the beacon CLI is the sole validator; an unknown token is forwarded and its decline surfaces as `CONTROL_ERROR` |
| `control.updater.pause` | `until?` (unix seconds) | The beacon CLI's `pause [--until <ts>] --json` output verbatim |
| `control.updater.resume` | — | The beacon CLI's `resume --json` output verbatim |
| `control.updater.checkNow` | — | The beacon CLI's `check --now --json` output verbatim — a full pass; the call blocks until it completes |

**Status is read directly off disk, never through the CLI** — `control.updater.status` is the
method a controller polls, and a file read is far cheaper than a process spawn on every poll. The
status directory is a WORLD-READABLE sibling of the beacon's own Admin/SYSTEM-only state directory
(dig-updater SPEC §13.2: `%ProgramData%\DIG\updater-status` on Windows, `/var/lib/dig-updater-status`
on Unix), so dig-node needs no elevation to read it. A present-but-corrupt `status.json` is reported
as `CONTROL_ERROR` (a genuine anomaly); an ABSENT one is `{ "installed": false }` (the beacon may
simply never have been installed on this machine) — never an error either way.

**Mutations shell the `dig-updater` CLI** — `setChannel`/`pause`/`resume`/`checkNow` invoke the
already elevation-gated operator CLI (dig-updater SPEC §13.3: `channel set`/`pause`/`resume` require
Administrator/root) rather than writing the beacon's Admin-only `config.json` directly. This service
runs privileged (Windows LocalSystem / a root daemon), so it satisfies that elevation check the same
way a human operator running an elevated terminal would. The CLI is resolved by an ABSOLUTE path —
an explicit override, else beside this running `dig-node` binary (the shared bin dir dig-installer
places `digstore`/`dig-node`/`dig-dns` into, and where the beacon installer, #514, is expected to
place `dig-updater`), else a per-OS conventional install root — NEVER a bare name resolved through
`PATH`. No binary resolves → `NOT_SUPPORTED` ("the DIG auto-update beacon is not installed on this
machine"); the CLI runs but declines (a bad channel, a missing elevation) → `CONTROL_ERROR` carrying
the CLI's own `detail` message; the CLI produces unparsable output (a crash) → `CONTROL_ERROR`.

**Opaque passthrough by design.** Both the status file and every CLI `--json` result are forwarded
as opaque JSON, never re-typed into a dig-node-owned shape — the beacon's schema-versioned wire
contract exists precisely so an independent reader can do this safely: a field the beacon adds later
passes through unchanged, with no shape to keep in sync on this side.

### 7.14. Always-on self-heal driver (#584 beacon re-arm + #651 ext-forcelist reconcile)

On a **privileged service run** (Windows LocalSystem / a root daemon), dig-node MUST run a detached,
best-effort self-heal driver: one pass on startup, then a pass every `SELF_HEAL_TICK` (**6 hours**).
It is NOT run on a dev/CLI (non-service) run. A pass performs two independent repairs; neither
failing ever blocks the serve path or the other repair:

- **Beacon re-arm (#584).** Kicks `dig-updater schedule ensure --json` — the idempotent verb
  (dig-updater ≥ v0.13.0) that re-registers a provably-ABSENT daily schedule. This closes the
  chicken-and-egg where an already-dead schedule cannot resurrect itself because nothing runs the
  beacon. `schedule ensure` itself respects a DELIBERATE opt-out (dig-updater writes an Admin-only
  sentinel on `schedule uninstall`; `ensure` short-circuits to `SuppressedByOptOut`), so dig-node
  keeps NO sentinel of its own — kicking `ensure` never re-arms an intentional uninstall.
- **Ext-forcelist reconcile (#651).** Reads the persisted channel (`dig-updater channel get --json` →
  `{ "channel": "stable"|"nightly" }`) and re-applies it to every detected browser via `dig-installer
  --set-ext-forcelist-channel <channel> --json` (idempotent). This recovers the post-remove-failure
  uninstall gap in the #613 staged channel switch (a crash after REMOVE but before RE-ADD leaves the
  extension uninstalled with the new channel already persisted, so an operator's `channel set` no-ops
  `Unchanged` and never retries).

**Security — absolute, privileged-root resolution only (#565 LPE).** Because the service spawns these
binaries with SYSTEM/root privilege, the sibling CLI MUST be resolved by an ABSOLUTE path beside the
running `dig-node` binary (the admin-only #565 install root), and that root MUST be REJECTED when it
is user-writable — on Unix a non-root owner or any group/world write bit; on Windows an owner other
than SYSTEM/Administrators. Resolution NEVER consults `$PATH` and NEVER accepts a bare name. A missing
sibling or a user-writable root is a benign/logged skip, never a spawn. The user-writable-root check
is the SAME spawn-free owner gate the TLS-root check uses (§4.1a) — one shared owner check, so the
two never drift.

**Bounded per-child timeout (#693).** Every self-heal child spawn (`dig-updater`/`dig-installer`)
carries a bounded wall-clock timeout (120 s). A hung child (a wedged scheduler API, a stuck policy
write) is cancelled and reported as a failed kick, so it can never block the pass or starve future
6-hourly ticks — the pass logs the timeout and continues, and the serve path is never affected.

### 7.15. Engine-side identity session (NODE-1 / U2, #910, #1080)

The engine exposes a transport-agnostic session half (`dig_node_core::session`) that verifies an
identity-authenticated IPC session on behalf of the `control.session.*` handshake. The engine is
**identity-agnostic**: it holds NO user signing key and can NEVER mint a signature with one. A dig-app
proves possession of a profile's slot-`0x0010` identity key; the engine only VERIFIES that proof and
tracks the resulting session in memory.

**Contract source of truth — `dig-ipc-protocol` (#1080).** The session/signing wire contract
(the `EngineSessionRegistry` state machine, the domain-separated message builders, the
`control.session.*` JSON-RPC types, the resource bounds, and the frame transport) is owned by the leaf
crate **`dig-ipc-protocol`**, the SINGLE source of truth shared byte-identically with the app half
(dig-app). `dig_node_core::session` RE-EXPORTS the crate's engine role-half at the established module
path and adds the engine's own **production** `DidSigningKeyResolver` (below). The two halves consume
one crate rather than each maintaining a copy, so they can never silently drift; a KAT cross-check
pins the crate's builders to the frozen golden bytes.

**Production DID resolver (#1080, over dig-identity #778).** `ChainDidSigningKeyResolver<S: ChainSource>`
resolves a profile DID to its published slot-`0x0010` key by CHAIN-AUTHENTICATED on-chain lookup,
delegating to `dig_identity::resolve_bls_public_key` (WU3): it walks the DID singleton lineage to its
authentic tip, finds the DID-paired store, binds the fetched profile body to the store's current
on-chain root, and returns the published key — failing CLOSED (`None`) on every ambiguity, staleness,
or mismatch. It never echoes the caller-presented key and never accepts a caller-supplied lineage; the
`ChainSource` it is built over MUST be a genuine forward lineage walk (coinset / full node), NEVER a
`SingletonLineage::single` echo. The concrete engine `ChainSource` (a coinset / full-node backed
DataLayer store-discovery reader) and the `control.session.*` WIRE transport (the per-user pipe/UDS +
its ACL, enforcing the re-exported frame bounds) remain the NODE-1 engine-carve follow-up.

**Domain-separated signed messages (byte-identical across halves, HARD RULE).** Two, and ONLY two,
messages are signed by the identity key. Their builders (now the `dig-ipc-protocol` builders) MUST
agree byte-for-byte with dig-app's half (a shared KAT proves it):

- **Attach challenge:** `SESSION_CHALLENGE_DOMAIN ‖ nonce ‖ profile_did`, where
  `SESSION_CHALLENGE_DOMAIN = "DIGNET-SESSION-v1"` and `nonce` is 32 bytes of OS randomness.
- **Sign callback:** `SIGN_CALLBACK_DOMAIN ‖ len16(payload_type) ‖ payload_type ‖ payload`, where
  `SIGN_CALLBACK_DOMAIN = "DIGNET-SIGN-v1"` and `len16` is the big-endian `u16` byte length of
  `payload_type` (rejected when `payload_type` exceeds `u16::MAX` bytes).

The distinct domain tags close the cross-protocol signing oracle: a signature minted for one purpose
can NEVER validate as the other.

**Handshake (engine's view).**

1. `begin { profile_did, signing_pubkey_hex }` → the engine validates the DID + 48-byte hex key, mints
   a random nonce + `session_candidate`, and remembers the pending `{ nonce, profile_did,
   presented_pubkey }`. Returns `{ nonce_b64, session_candidate }`.
2. `attach { session_candidate, signature_b64, profile }` → the engine consumes the candidate (one
   nonce, one attempt), then: resolves the DID's on-record slot-`0x0010` key via a
   `DidSigningKeyResolver`; **REQUIRES** the resolved key to equal the presented key; BLS12-381 G2 AugScheme-verifies
   the challenge signature against it; only then opens an in-memory session. Returns `{ session_id,
   engine_capabilities }` (`["content.serve", "content.fetch", "sync", "subscribe"]` — keyless by
   construction; the app MUST tolerate capabilities it does not recognize).
3. `detach { session_id }` → drops the in-memory session.

**Custody invariants (HARD RULE).**

- The engine only ever VERIFIES signatures; it never holds or derives a user key (VERIFY-ONLY).
- Attach binds to the key the engine RESOLVED for the DID, not merely the key the caller presented — a
  substituted key is rejected (`KeyMismatch`).
- A DID the resolver cannot resolve FAILS CLOSED (`UnknownDid`): no session opens. An "echo"
  resolver that returned the presented key is FORBIDDEN — it would let any caller attach as any DID.
- The attach candidate is consumed whether or not attach succeeds, so a nonce cannot be replayed.

**Bounds.** `MAX_FRAME_BYTES` (1 MiB) and `MAX_INTERLEAVED_CALLBACKS` (64) are the contracts the
(follow-up) transport MUST enforce. The registry itself bounds `MAX_PENDING_CANDIDATES` (256)
begun-but-not-attached handshakes: once at capacity, the OLDEST outstanding candidate is EVICTED so a
flood of never-attached `begin`s cannot grow engine state without bound.

---

## 8. CLI contract

### 8.1. Subcommands

`run` (default when no subcommand; serves in the foreground and is the unix-service entrypoint) ·
`run-service` (hidden; the Windows SCM entrypoint, §9.4; behaves as `run` off Windows) ·
`install` · `uninstall` · `start` · `stop` (each accepting `--scope <auto|system|user>`, §9.1) ·
`status` · `pair` (§7.11) · `open` (§8.5) ·
the **control-parity** subcommands `info` · `config` · `cache` · `stores` · `sync` · `updater` ·
`subscriptions` (§8.6) · `peers` (§8.7) · `logs` (§11).

The `dign` alias binary (§2.1a) exposes this SAME subcommand set with the SAME semantics — `dign
<subcommand>` is equivalent to `dig-node <subcommand>` in every respect except the reported program
name.

### 8.6. Control-parity subcommands (#426)

For EVERY gated `control.*` method the DIG Chrome extension drives (§7), the CLI exposes an
equivalent subcommand, so an operator/agent can drive the node from a terminal exactly as the
extension drives it from a browser. Each subcommand is a THIN dispatch — it calls the SAME
`control.*` method over the node's loopback endpoint, presenting the MASTER control token
(`X-Dig-Control-Token`, read WITHOUT minting — §7.11/#501); no CLI logic is forked from the control
plane. A mutating CLI control is therefore gated by the identical capability as the WS surface (the
on-disk master token = local-machine control), never an unauthenticated backdoor.

- `info` → `control.status` — the rich node status (version, uptime, cache, hosted-store +
  cached-capsule counts, §21 sync availability). DISTINCT from `status` (§8.3), which is an
  unauthenticated `/health` liveness probe; `info` is the token-gated detailed view.
- `config [get]` → `control.config.get`; `config set-upstream <url>` → `control.config.setUpstream`.
- `cache [get]` → `control.cache.get`; `cache set-cap <bytes>` → `control.cache.setCap`;
  `cache clear` → `control.cache.clear`.
- `stores [list]` → `control.hostedStores.list`; `stores pin|unpin|status <store>` →
  `control.hostedStores.pin|unpin|status`.
- `sync [status]` → `control.sync.status`; `sync trigger <store>` → `control.sync.trigger`.
- `updater [status]` → `control.updater.status`; `updater set-channel <ch>` / `pause [--until <s>]`
  / `resume` / `check-now` → the matching `control.updater.*`.
- `subscriptions [list]` → `control.listSubscriptions`; `subscriptions add|remove <store_id>` →
  `control.subscribe`/`control.unsubscribe`.

**Parity is enforced mechanically.** `control::CONTROL_METHODS` is the canonical set of every
`control.*` method the node resolves; a compile-time-adjacent test asserts every method in it is
reachable from a CLI verb, so a new node control method cannot ship without a CLI subcommand.

### 8.7. `peers` — view + manage peer connections (#559)

`peers` reaches parity with the extension's peer surface (`src/features/peers/peersApi.ts`):

- `peers [list]` → `control.peerStatus` — the live peer status: running flag, connected count,
  relay reservation, and a **per-peer array** `peers[]`, each element
  `{ peer_id, address, via, direction }` where `via ∈ {"direct","relay"}` is the REAL per-peer
  transport (a peer whose gossip rides the relay's RLY-002 forwarder reports `"relay"`, every other
  peer `"direct"`, sourced from dig-gossip's `connected_pool_peers_with_via`) and
  `direction ∈ {"outbound","inbound"}`.
  The array is present whenever a peer network is running and
  omitted (count only) on the in-process FFI path / before bring-up. The per-peer `peer_id` is the
  machine-checkable proof of a mutual A↔B connection (each side lists the other's `peer_id`). Peer
  addresses are displayed **IPv6-first, IPv4 second** per the ecosystem §5.2 address-family policy.
- `peers connect <peer>` → `control.peers.connect` — dial a peer via the live gossip pool. `peer` is
  EITHER a dialable socket address (`host:port`, IPv6 in brackets) dialed over the full NAT ladder, OR
  a `peer_id` (64-hex) honoured only if already connected (idempotent). Returns
  `{ connected: true, peer_id }`; a bare unknown `peer_id`, a malformed argument, a dial failure, or no
  running peer network each return a deterministic control error. CONTROL-plane — reachable only from
  the loopback admin / in-process dispatch, NEVER over the mTLS peer surface.
- `peers disconnect <peer>` → `control.peers.disconnect` — drop a pooled peer, closing its mTLS link
  (the inverse of `connect`). `peer` is a `peer_id` (64-hex); the pool then replenishes toward target.
  Returns `{ disconnected: true, peer_id }`. Idempotent — disconnecting a `peer_id` that is not (or no
  longer) connected succeeds as a no-op. A malformed `peer_id` or no running peer network returns a
  deterministic control error. CONTROL-plane — loopback admin / in-process dispatch only, NEVER over
  the mTLS peer surface.
- `peers ping <peer> [--peer-id <64hex>]` → `control.peers.ping` — test EVERY rung of the connection
  ladder against a peer and report which one reached it (§7.4a). `peer` is a 64-hex `peer_id` or a
  dialable address; `--peer-id` pins the identity the certificate must derive, which is required for
  an address the node cannot already name an identity for. The human output leads with an
  `[OK]`/`[WARN]`/`[FAIL]` marker matching the graded severity, then one line per rung; `--json`
  emits the §7.4a result verbatim. Read-only and bounded — see §7.4a for the full contract.
- `peers ban <peer> --state <ban|blacklist|none>` → `control.peers.setBan`; `peers pool-config
  --max-connections <n>` → `control.peers.setPoolConfig` remain a **known node-side gap**: until the
  node ships those RPCs those verbs surface the node's METHOD_NOT_FOUND. The CLI verbs exist now so the
  surface reaches parity and lights up with NO CLI change once the node implements them.

### 8.5. `open` — the OS scheme handler (#389)

`dig-node open <link>` is the target the installer registers for the OS `chia://` and
`urn:dig:chia:` protocol handlers (`dig-node open "%1"`). It is the OS-level fallback resolver for a
DIG link that no in-browser DIG extension intercepted.

- **Input.** Accepts ONLY `chia://<storeId>[:<root>][/<path>]` and
  `urn:dig:chia:<storeId>[:<root>][/<path>]` (scheme match is case-insensitive). The store reference
  MUST be canonical 64-hex (`storeId` or `storeId:root`).
- **Untrusted-input validation (MUST).** The argument arrives from an OS handler and may be
  attacker-influenced (a hostile page can invoke a registered scheme). The command MUST reject every
  other scheme (`file:`, `javascript:`, `data:`, `http(s):`, …), shell metacharacters, control
  characters, whitespace, and `..` path traversal, and MUST NOT pass the argument to a shell — the
  resolved URL is launched via the OS "open a URL" facility with the URL as a SINGLE, non-shell argv
  entry (Windows `rundll32 url.dll,FileProtocolHandler`, Linux `xdg-open`, macOS `open`). A rejected
  link exits `USAGE` (2) and launches nothing.
- **Resolution (MUST route through the canonical resolver, #745).** `open` is a CLIENT operation, so
  it MUST resolve the link through the shared **`dig-urn-resolver`** — the canonical §5.3 ladder
  (`dig.local` → `localhost:9778` → `rpc.dig.net`) with FAIL-CLOSED integrity verification — exactly
  like every other URN-consuming client (the extension URN bar, the SDK). It MUST NOT hard-roll a
  single `localhost:9778/s/…` URL, and MUST NOT surface a raw upstream error string (e.g. a `502`) to
  the user. The resolver — never this command — decides whether the content is loadable and NEVER
  returns unverified bytes. This dependency lives ONLY in the service shell's open-command path, never
  in the node engine (`dig-node-core`), where it would be a dependency cycle.
- **Behavior on a verified `Success`.** Opens the user's DEFAULT browser at the best
  browser-navigable form, in §5.3 preference order, opening the first tier that actually SERVES the
  content (each cheaply probed):
  1. `http://<storeId>.dig/<path>` — offered ONLY for a rootless link (the host cannot pin a root);
  2. `http://dig.local/s/<storeId>[:<root>]/<path>`;
  3. `http://<host>:<port>/s/<storeId>[:<root>]/<path>` (host/port from config, default `localhost:9778`).
  If NO browser tier can serve the content (e.g. the local `/s/` chain-read is 502-ing) but the
  resolver still returned VERIFIED bytes via `rpc.dig.net`, the command serves those verified bytes
  over an EPHEMERAL LOOPBACK HTTP endpoint (`http://127.0.0.1:<port>/…`) and opens THAT — so the user
  always sees the exact verified content, never a raw error.
- **Resolved bytes MUST NOT be written to disk or OS-opened as a file (SECURITY, #745).** The resolved
  bytes, their content type, and the resource name are ALL attacker-controlled (anyone may publish a
  store), and a verified `Success` proves only chain-inclusion, NOT safety. Writing them to a temp file
  and handing that to the OS default-open would bypass the browser's download protections and let an
  attacker store execute code (e.g. a `.hta`/`.js` written without Mark-of-the-Web → RCE; HTML would
  also gain a privileged `file://` origin). The command MUST therefore serve the bytes over a loopback
  `http://127.0.0.1:<ephemeral>` origin instead (short-lived, `X-Content-Type-Options: nosniff`,
  attacker-influenced header values sanitized of CR/LF), so the browser applies its normal
  render-vs-download / Mark-of-the-Web / origin-sandbox handling.
- **Behavior on a non-success / hard error.** On `IntegrityFailure`, `Unreachable`, or a hard resolve
  error (not-found / rpc error / **root-required** — a ROOTLESS link the untrusted `rpc.dig.net` tier
  refuses to resolve without a chain-anchored root), the command MUST show a BRANDED DIG error asset
  from the resolver (`dig_urn_resolver::images`), served over the same loopback endpoint — NEVER a
  hand-rolled page and never a raw error string. A branded page is shown only for a link that PARSES as
  a valid DIG URN but fails to RESOLVE; a link that fails the untrusted-input validation above still
  exits `USAGE` and shows nothing.
- **The branded asset's served filename MUST be OUTCOME-SPECIFIC** — `dig-error-<outcome>.png` (e.g.
  `dig-error-root_required.png`, `dig-error-unreachable.png`, `dig-error-integrity_failure.png`), never
  a single opaque `dig-error.png` for every outcome — so the opened `http://127.0.0.1:<port>/…` URL
  itself names WHY the open failed. The command MUST also emit a one-line stderr diagnostic naming the
  resolved URN + the outcome that fired, so a failing `open` is diagnosable (it MUST NOT log resolved
  bytes).
- It NEVER opens `chia://` at the OS level (dig-node is itself the OS `chia://` handler, so that would
  recurse) and NEVER opens a dig-node GUI (it has none). Under `--json`:
  `{ opened: true, mode: "browser"|"content"|"error", outcome, url, store_id, root, path }` (`url` is
  always an `http(s)` URL — never a local file path).

### 8.2. `--json` (global flag)

Under `--json` every subcommand MUST emit exactly ONE structured JSON object to **stdout** and
route human prose to **stderr**.

- Success envelope: `{ ok: true, action, service: "dig-node", version, …result-fields }` (result
  fields folded in at top level).
- Error envelope: `{ ok: false, action, error: { code, exit_code, message, hint } }` where `code`
  is the symbolic exit-code name and `exit_code` the numeric code; the process still exits with
  that code.

Without `--json`: success summaries print to stdout; errors print `error: …` (and optional
`hint: …`) to stderr.

### 8.3. `status` semantics

`status` probes `GET /health` on the configured address (blocking HTTP/1.0 probe, 2 s timeouts).
"Serving" means the response **status line** is 2xx (parsed from the status code token — never a
substring match). A refused connection is `serving: false`, not an error. `serving: false` maps to
exit `1` (`NOT_SERVING`) so scripts can gate on liveness; the JSON result carries `serving`,
`addr`, `health_url`.

### 8.4. Exit-code table (stable)

| Exit | Name | Meaning |
|---|---|---|
| 0 | `OK` | Success. |
| 1 | `NOT_SERVING` | `status`: the node is not responding. |
| 2 | `USAGE` | Bad arguments / usage error. |
| 3 | `PERMISSION_DENIED` | Elevation required (Windows `install`/`uninstall`). |
| 4 | `SERVICE_FAILED` | A service-manager operation failed. |
| 5 | `BIND_FAILED` | `run`: could not bind the loopback address. |
| 6 | `IO_ERROR` | Other I/O error. |

I/O-error mapping: `PermissionDenied` → 3; `AddrInUse`/`AddrNotAvailable` → 5; anything else → 6.
Numeric values and symbolic names are a stable contract and MUST NOT be renumbered.

---

## 9. OS-service contract

9.1. **Service scope (`--scope`, #526).** A registration lives in exactly ONE of two scopes, and
`install`, `uninstall`, `start` and `stop` all accept `--scope <auto|system|user>`, default `auto`.

| Scope | Where the registration lands | Runs as | Survives a reboot with NO login session | Requires |
| --- | --- | --- | --- | --- |
| `system` | systemd system unit (`/etc/systemd/system/dignetwork-dig-node.service`, `WantedBy=multi-user.target`) · launchd daemon (`/Library/LaunchDaemons/net.dignetwork.dig-node.plist`, `system` domain) · Windows SCM service | root / LocalSystem | **YES** — starts at boot | root / Administrator |
| `user` | systemd user unit (`~/.config/systemd/user/dignetwork-dig-node.service`) · launchd agent (`gui/<uid>` domain) | the installing user | NO — starts with that user's session | nothing |

- **Resolution (normative).** Given the operator's choice, whether the OS HAS a user scope, and
  whether the process is root, the resolved scope MUST be: `system` whenever the OS has no user
  scope (Windows SCM) — **including for an explicit `--scope user`, which cannot be honoured
  there**; otherwise the explicit `--scope system`/`--scope user` **verbatim** (an explicit choice is
  authoritative and MUST NEVER be silently overridden by the privilege level); otherwise, for
  `auto`, `system` when running as root and `user` when not.
- **`auto` is the default**, so a caller that passes no flag — including a dig-installer release
  predating this flag — gets the historical behaviour: user scope for an unelevated desktop install,
  and now system scope for an ELEVATED install, which is what makes a headless install survive a
  reboot. Root has no `systemd --user`/D-Bus session, so a user-scope registration attempted as root
  cannot succeed at all.
- **A system scope requested without root MUST be refused** (`PERMISSION_DENIED`) with a message
  naming the missing privilege and the `--scope user` alternative — never silently downgraded to
  user scope (a silent downgrade produces a registration that does not survive a reboot, which the
  operator asked to avoid). On Windows, the equivalent up-front check is elevation itself:
  `install`/`uninstall` MUST fail fast with a clear `PERMISSION_DENIED` when the console is not
  elevated (probed up front, not deep inside `sc.exe`).
- **Cross-scope migration (`install`).** Before registering at the resolved scope, `install` clears
  this service label at the OTHER scope, so a host upgrading from a previous user-level install does
  not end up with two registrations both starting a node bound to the same port. TWO mechanisms, with
  different reach, and the difference is normative because the first one CANNOT work as root:
  1. **The OS-manager sweep** asks the current process's own service manager about the other scope.
     It is PROBE-GATED (a scope holding no registration is never written to) and therefore only ever
     sees the CURRENT account: root has no systemd `--user` session, and `gui/<uid>` is uid 0's
     domain, so as root this mechanism sees nothing and does nothing. Reported as
     `result.migrated_from_scope { scope, found, removed, indeterminate, error }`.
  2. **The per-account FILESYSTEM sweep**, which runs when the resolved scope is `System` on a
     user-capable OS, because that is the case mechanism 1 cannot cover. It enumerates real
     registration FILES under the fixed account roots `/home`, `/root` and `/Users` — the systemd
     user unit `<home>/.config/systemd/user/dignetwork-dig-node.service` together with its
     `default.target.wants/` enablement symlink, and the launchd agent
     `<home>/Library/LaunchAgents/net.dignetwork.dig-node.plist` — best-effort STOPS each running
     instance (`launchctl bootout gui/<uid>/<label>`, `systemctl --user --machine=<account>@.host
     stop <unit>`), then unlinks them. Reported per account as
     `result.user_scope_sweep { removed_accounts, failed_accounts, residual }`. Stopping matters as
     much as unlinking: a still-running user-level node holds the node's port, and the `dig-node
     start` an installer treats as fatal would fail with `EADDRINUSE`.
     - **Root deleting inside user-owned directories is symlink-refusing.** No intermediate
       DIRECTORY component of a removal path below the account root may be a symlink (checked with
       `lstat`, which does not follow); if one is, that registration is refused and REPORTED rather
       than removed, because as root a redirected walk would be an arbitrary-delete primitive. The
       FINAL component MAY be a symlink — systemd's `default.target.wants/` enablement entry always
       is, and refusing it would leave the unit ENABLED — because it is only ever unlinked, which
       removes the link and never follows it. Only individual files and symlinks are ever unlinked —
       never a directory tree.
     - **Stated residual (NOT covered).** A user-scope registration under a home directory outside
       `/home`, `/root` or `/Users`, or under a non-default `XDG_CONFIG_HOME`, is not discoverable
       and is NOT removed; that residual is stated in the install output, and the affected user
       removes it with `dig-node uninstall --scope user`.
  Both sweeps are best-effort and a failure in either MUST NOT fail an otherwise-good install — but a
  registration that was seen and could not be removed MUST be reported as a `WARN` in the human
  summary and in `--json`, never silently dropped.
- **The existence probe is ADVISORY; the OS deregistration is AUTHORITATIVE.**
  `launchctl print gui/<uid>/<label>` cannot see a per-user agent from a session with no Aqua/GUI
  domain (a headless CI runner, an ssh login), so it reports absence for a service that IS
  registered. Therefore the scope the operator NAMED (or `auto` resolved to) MUST be deregistered
  **unconditionally**, without gating on the probe — a probe false-negative MUST NEVER turn an
  uninstall into a silent no-op. A scope merely being SWEPT (the other scope during `install`, the
  second scope of `uninstall --scope auto`) MUST be probe-gated, so a scope nobody asked about is
  never written to.
- **`uninstall` scope sweep.** An explicit `--scope` removes exactly that scope. `--scope auto`
  removes the resolved scope and then sweeps the other, so an uninstall does not leave the other
  scope's registration of the CURRENT account behind (the residual above applies here too: another
  account's user-scope registration is that user's own `dig-node uninstall --scope user`). Every
  scope is reported
  (`result.removed_scopes: ["system", "user"]`). Anything short of a complete removal MUST be an
  error naming the scope, never a silent success. A scope is **indeterminate** — unknown, and
  therefore reported as unresolved — when the removal did not succeed AND its failure was not the OS
  positively reporting absence: the classification is by the removal error's KIND, where `NOT_FOUND`
  is the ONLY honest "there was nothing here" signal and anything else (a permission failure on a
  root-owned unit, an unreadable domain, a tool that could not be located in a privileged directory)
  leaves a registration that may still be present. Only when nothing was
  removed anywhere AND nothing is unresolved is the result `NOT_FOUND` ("nothing to uninstall"),
  carrying the underlying removal error as context.
- **The existence probe is THREE-VALUED, and only the OS may say "absent".** The probe answers
  `present`, `absent`, or `unknown` — there is no fourth outcome — and it MUST NOT report `absent`
  for a scope it could not READ. The three answers are decided in a fixed order, and the ORDER is
  normative:

  1. **A probe that SUCCEEDED is `present`**, tested before any absence test. Success outranks the
     stderr entirely: a probe that exits 0 is `present` even if its stderr carries an absence
     phrase (a warning about some other unit) or an absence exit code.
  2. Otherwise, a **positive OS absence signal** (exhaustively enumerated below) is `absent`.
  3. Otherwise the outcome is **`unknown`, carrying the tool's own message** verbatim.

  The absence signals are EXACTLY these, per backend, and a reimplementation MUST recognise every
  one of them — the set is closed, and nothing outside it may become `absent`:

  | Backend (probe) | `absent` iff |
  | --- | --- |
  | systemd (`systemctl [--user] cat <unit>`) | stderr contains `no files found for` **or** `could not be found`. **No exit-code condition** — systemd's exit codes are not a reliable absence signal, so the phrasing alone decides. |
  | launchd (`launchctl print <domain>/<label>`) | exit code `113` **or** stderr contains `could not find service`, `no such process`, or `no such file`. The code and the phrases are INDEPENDENTLY sufficient: either one alone is `absent`. |
  | Windows SCM (`sc query <name>`) | exit code `1060` (`ERROR_SERVICE_DOES_NOT_EXIST`) **only**. No stderr phrasing participates, and no neighbouring code does: `1059`/`1061` are `unknown`, as is `5` (`ERROR_ACCESS_DENIED`). |

  **The stderr match is a CASE-INSENSITIVE SUBSTRING search**, never equality and never a prefix:
  the phrase above must be found anywhere within a case-folded copy of the tool's stderr, because
  the OS embeds it mid-sentence and capitalises it its own way (`No files found for
  dignetwork-dig-node.service.`, `Unit dignetwork-dig-node.service could not be found.`). Matching
  on equality, on a prefix, or case-sensitively would classify a genuinely-absent service as
  `unknown`.

  Every other outcome is `unknown` and carries the tool's own message: `systemctl --user` with no
  reachable bus (its state when run as root), a launchd domain that cannot be bootstrapped from a
  session with no Aqua domain, a permission failure, a signal-terminated probe, or an OS tool that
  could not be located in a privileged directory. `unknown` MUST NOT be collapsed into "not
  registered" ANYWHERE. Concretely: the "is there something here" accessor is false for `unknown`
  exactly as it is for `absent` (it answers only "positively present", so no caller can read a
  `false` as "nothing is registered"), and the accessor that demands certainty — used by the
  clean-reinstall and the post-delete removal wait — MUST return an ERROR on `unknown` rather than
  either boolean. It makes a swept scope **indeterminate** (above), and where a caller cannot
  proceed without certainty — the clean-reinstall, and confirming a deletion took effect — it is an
  ERROR, never a `false` that would create over a registration that may be live. This state is
  therefore reachable from the real OS backend, not only from a test double.
- **Native packages register system scope**, consistently with `--scope system`: the `.deb`'s static
  systemd unit is `WantedBy=multi-user.target` running as root, and the macOS `postinstall`
  bootstraps into the `system` launchd domain (§9.7).

9.1a. **Privileged execution hygiene (HARD RULES).** Every service verb now resolves the scope from
the process's privilege level, so all of the following execute while root during the prescribed
`sudo dig-node install --scope system`:

- **The effective uid MUST come from `geteuid()`**, never from a spawned `id`. A bare program name is
  resolved through `$PATH`, and `/usr/local/bin` — group-writable `root:staff 2775` on Debian/Ubuntu
  and user-owned under Intel Homebrew — leads sudo's default `secure_path`, while macOS sets no
  `secure_path` at all. A planted `id` would therefore run AS ROOT; and one printing a non-zero uid
  would additionally resolve the scope to `user`, which is exempt from the privileged-target gate
  (§9.2c) — one writable `PATH` entry would switch that gate OFF.
- **Every OS tool MUST be executed from an ABSOLUTE path resolved out of a fixed list of privileged
  directories** (`/usr/sbin`, `/usr/bin`, `/sbin`, `/bin`; `%SystemRoot%\System32` and
  `%SystemRoot%` on Windows). `/usr/local/bin` MUST NOT appear in that list. A tool that cannot be
  found in it MUST NOT be run at all (fail closed), and the failure is reported.
- **The process `PATH` MUST be pinned to that same list, and `WINSW_PATH` removed, for the duration of
  a service verb.** Unix resolves a bare name with `execvp` against the CALLING process's `PATH`, so
  this is the only place spawns made by DEPENDENCIES can be constrained — and the service-manager
  library selects a **WinSW** backend whenever a `winsw.exe` is on `$PATH` or `%WINSW_PATH%` names an
  existing file, then executes it as the elevated installer, which would hand an attacker the entire
  service definition.
- **No baked service-environment key or value may contain a control character** (newline,
  carriage return or NUL)
  when the resolved scope is `System`. Each entry is written verbatim as one `Environment="K=V"` line
  of a root-owned systemd unit file, so a line terminator appends further DIRECTIVES that run as root
  (`ExecStartPre=` may appear repeatedly and runs before `ExecStart`). The refusal names the offending
  key and is stated over the CLASS of control characters, not over any particular directive. Such a
  value is also rejected at its SOURCE (`normalize_upstream`, `control.config.setUpstream`) so it
  cannot persist in `config.json` and be baked by a later install. User scope is exempt: that unit is
  written by, and runs as, the user who already controls the values.

9.2. **Recorded environment.** `install` MUST register the absolute path of the currently-running
executable (never a PATH lookup) and record the resolved config as service environment variables:
`DIG_NODE_PORT`, `DIG_NODE_HOST`, `DIG_RPC_UPSTREAM`, and — **only when explicitly
configured** — `DIG_NODE_CACHE` (omitting it preserves the shared-cache default, §3.5). The
service is registered with `autostart: true`.

9.2a. **Restart-on-crash recovery (all 3 platforms).** A crashed `dig-node` service MUST come back
up on its own, not sit stopped until a human restarts it:
  - **Linux (systemd)** and **macOS (launchd)** get this from `service-manager`'s own install
    defaults with no extra step — systemd's generated unit sets `Restart=on-failure`; launchd's
    generated plist sets `KeepAlive: true` (alongside `RunAtLoad: true` from `autostart`).
  - **Windows (SCM)** has no such default: `sc create` alone leaves recovery actions at "Take No
    Action". `install` MUST additionally configure them after a successful `mgr.install`, by
    invoking `sc.exe failure <SERVICE_LABEL> reset= 86400 actions=
    restart/5000/restart/10000/restart/30000` (reset the failure counter after 1 day with no
    further crashes; restart after 5s/10s/30s on the 1st/2nd/subsequent failure in that window) —
    `<SERVICE_LABEL>` here is `net.dignetwork.dig-node` used literally (§2.4's `to_qualified_name`
    rejoins its 3 segments unchanged, so it is the exact registered SCM service name). This step is
    **best-effort**: a failure to configure recovery actions MUST NOT fail the whole `install` (the
    service is still registered and usable) — it surfaces as a `note` in the human summary and
    `result.recovery_configured: false` in `--json` output (`true` otherwise, and always `true` on
    Linux/macOS since their defaults already apply).

9.2b. **Display name + clean-reinstall (`install`, #494).** `install` is a stop→delete→wait→create
CLEAN-REINSTALL, never a reconfigure-in-place, so re-running it against an already-registered
service does not hit Windows `CreateService` error 1073 ("the specified service already exists"):

- If the service is not yet registered, `install` simply creates it.
- If it IS already registered, `install` best-effort stops it, deletes (deregisters) it, polls for
  the deregistration to actually take effect (bounded, `TimedOut` if it never does — a lingering
  Windows deletion can hold on until open handles close), and only THEN recreates it.
- **`install` never starts the service** (fresh or reinstalled) — it only registers
  `autostart: true` for the next boot/login. A caller starts it explicitly with `dig-node start`.
  This is deliberate: the dig-installer calls `install` then, when configured to start it, a
  SEPARATE `start` and treats a `start` failure as fatal for that step; if `install` also started
  the service, that second `start` would hit "already running" and could flip the installer's
  reported outcome to failed even though the service is up.
- **Windows display name.** `sc create` (via `service-manager`) always sets the SCM display name to
  the service id; `install` follows it with `sc config <id> displayname= "DIG NETWORK: NODE"`, then
  reads the config back with `sc qc <id>` to CONFIRM the override took (rather than trusting the
  `sc config` exit code alone). Both steps are best-effort — a failure leaves the service
  registered and usable, just possibly showing its id instead of the friendly name in the Services
  console; `result.display_name_verified` (`--json`) reports whether the read-back confirmed it.
- **macOS/Linux friendly name.** launchd has no display-name-equivalent plist key, so the daemon is
  identified by its `Label` (`net.dignetwork.dig-node`) only. systemd's `Description=` DOES carry a
  friendly name; the native `.deb`'s STATIC unit file (§9.7) already sets
  `Description=DIG NETWORK: NODE`. A bare `dig-node install` (not via the `.deb`) registers a
  service-manager-generated unit whose `Description` is the service id, matching `dig-dns`'s own
  established precedent for the CLI-only path.

9.2c. **Privileged-target gate (`install`, #565 LPE).** A **system-level** registration (Windows
SCM, always LocalSystem; a root systemd/launchd daemon) records the currently-running binary as its
`ExecStart` / SCM `binPath` / launchd `ProgramArguments` (§9.2). If that binary sits in a
user-writable directory, a non-privileged local user could replace it and gain persistent
SYSTEM/root code execution on the next service start — a privilege-escalation vector. So before
registering a system-level service, `install` MUST verify the program's directory is
**privileged-owned across its whole path** (§ the shared whole-path owner check — every ancestor
component privileged-owned, non-reparse) and **refuse with `PERMISSION_DENIED`** otherwise, before any
side effect (no state-dir harden, no service create). This is the SAME spawn-free owner gate the
self-heal spawn root (§7 #565) and the TLS material root (§4.1a #661) use — one shared check,
fail-closed on an indeterminate owner. The refusal MUST NAME the offending path
LEVEL (the first ancestor that fails the check), not merely the program path: the check walks the
whole chain, so a privileged-owned leaf under a user-writable parent is refused, and an operator
cannot act on a refusal that does not say which level failed. A **user-scope** install runs as the
very user who owns the binary, crosses no privilege boundary, and is always allowed. The canonical
install paths (native OS package, §9.7; the dig-installer's root-owned `/opt/dig/bin`) place the
binary in a protected admin-owned location (`%ProgramFiles%\DIG\bin\`, `/usr/…`), so
they satisfy the gate; a manual system-scope `dig-node install` from a user-writable download
directory is what the gate refuses — and it is refused loudly, never downgraded to user scope. **The program FILE itself MUST also clear the bar** — owned by root/SYSTEM, no group/other write
bit, not a symlink/reparse point — and not merely sit inside a privileged directory: directory
permissions prevent unlink/rename of the entry, but a binary whose OWN mode permits it can be
rewritten in place, and the daemon would execute the new contents at next boot. The two checks are
independent and both required; the refusal names which one failed.

A single explicit, **default-off** opt-out — the `DIG_NODE_ALLOW_INSECURE_SERVICE_TARGET`
env var (truthy `1`/`true`/`yes`) — bypasses the gate with a loud warning, intended ONLY for a
controlled test/dev install of an unreleased build from a build directory (e.g. the `service-smoke`
CI); it MUST NOT be set on an end-user machine. **It is INERT when the resolved scope is `System` and
the process is genuinely root**: that combination is a root boot daemon on a real machine, the env var
is inheritable (`sudo -E`, an export in a root profile, a CI value leaking into an operator shell),
and no inherited variable may disable this gate for it.

9.3. **Entrypoint per platform.** The installed service runs `dig-node run-service` on Windows and
`dig-node run` on systemd/launchd (which exec the foreground process directly).

9.4. **Windows SCM protocol.** `run-service` MUST connect to the SCM via
`StartServiceCtrlDispatcher` under the exact §2.4 label, register a control handler, report
`Running` (accepting `Stop`) promptly — otherwise the SCM kills the process with error 1053 —
serve until the SCM `Stop` control, drive the same graceful shutdown as a signal, and finally
report `Stopped` (Win32 exit 0 on success, 1 on error).

9.4a. **`start` is IDEMPOTENT (#772).** `dig-node start` requests the OS service manager start the
registered service and reports SUCCESS (exit 0) when the service is EITHER freshly started OR
ALREADY RUNNING — a running node is the desired end state, never an error. It MUST recognise the
per-OS already-running signal, which surfaces only in the service manager's output: Windows SCM
error **1056** ("An instance of the service is already running"), launchd "already loaded" /
"already in progress", systemd "already active" (systemd `start` of an active unit is normally a
silent no-op). `--json` reports `already_running: true|false` to distinguish the two success cases.
Any OTHER start failure (e.g. the service is not registered) MUST still surface as an error. This is
what lets the dig-installer call `install` then a separate `start` (§9.2b) without a spurious
failure when the service is already up.

9.5. **Graceful shutdown.** In the foreground, the serve loop MUST stop gracefully on Ctrl-C (all
platforms) or SIGTERM (unix — how systemd/launchd stop the service). One shutdown event MUST fan
out to both listeners (§4.1).

9.6. **Uninstall.** `uninstall` performs a best-effort `stop` first, then removes the registration.

### 9.7. Native install packages (#503)

The canonical end-user install path is a NATIVE OS PACKAGE built by this repo's CI (`package.yml`),
published as GitHub Release assets on each `vX.Y.Z` tag. `dig-updater` fetches + runs the right
package on every update; on Windows `dig-installer` currently places a raw binary instead of running
the `.msi` (unifying that is planned, and until it lands the `.msi` MUST tolerate a foreign binary
already present in the install root — see the Windows entry below). Each package installs the binary,
registers the OS service, registers the `chia://` scheme handler (→ `dig-node open`, §8.5), creates
the machine-wide state dir (§7.3a), and sets the `dig.local` → `127.0.0.2` hosts entry (via the
idempotent, no-shell `dig-node ensure-hosts`, §8.1). The `dig-node install`/`uninstall` CLI (§9.1)
remains for manual/dev use.

- **Windows `.msi`** (WiX; `dig-node-<ver>-windows-x64.msi`). **`dig-updater` runs this package on
  every Windows update** (`msiexec /i <pkg> /qn /norestart`; dig-node's Windows `InstallMethod` is
  `WindowsMsi`), so it is load-bearing for auto-update. `dig-installer` does NOT currently run it —
  it places a raw binary in the install root itself.

  Installs `dig-node.exe` under `%ProgramFiles%\DIG\bin\` — the CANONICAL protected install root.
  That root is MANDATORY for two independent reasons:

  1. **Auto-update convergence.** `dig-updater` reads the installed version from
     `<install-root>\dig-node.exe` after running the package. If the package installs anywhere else,
     the probe reads a file the install never wrote: the probed version never changes, every beacon
     cycle re-runs the same install, and the host never advances — a non-convergent update loop, not
     a cosmetic path difference.
  2. **The installer's own audit.** `dig-installer` verifies the registered service image and the
     fresh-session PATH resolution of `dig-node.exe` against that root, so a package installing
     elsewhere makes every install fail a check against its own payload.

  `ServiceInstall`+`ServiceControl` register
  `net.dignetwork.dig-node` (DisplayName **"DIG NETWORK: NODE"**) running `dig-node.exe run-service`
  as LocalSystem, auto-start, STARTED on install, STOPPED+REMOVED on uninstall; creates
  `C:\ProgramData\DigNode` with a **restrictive DACL — inheritance broken, only SYSTEM +
  Administrators (never Users)** so the token is not world-readable (§7.3a; dig-node leaves a
  pre-existing dir's ACL intact); registers `chia://` under `HKLM\Software\Classes\chia`
  (`shell\open\command` = `"…\dig-node.exe" open "%1"`); MUST NOT modify the machine `PATH` (the
  install root's PATH entry has exactly ONE owner, `dig-installer`, which writes it in the USER hive
  — a machine-hive entry from this package precedes it in a fresh session and shadows it);
  runs `dig-node ensure-hosts` as a deferred (SYSTEM) custom action. A stable `UpgradeCode` +
  `MajorUpgrade` give clean in-place upgrades.

  **Upgrade sequencing (normative).** `MajorUpgrade` MUST schedule `RemoveExistingProducts` BEFORE
  the new files install (`afterInstallValidate`). The previous product's binary, machine-`PATH` row
  and `net.dignetwork.dig-node` registration are then removed, and the service reinstalled and
  started, inside ONE transaction: an interrupted upgrade rolls back to the previous product with
  its service intact, and a completed upgrade ends with the service registered against the new
  image. No reachable resting state has a registered product and no service. Scheduling the removal
  LATER is forbidden: the previous product's `ServiceControl Remove="uninstall"` matches the service
  by NAME and would delete the service the new product had just registered. `REINSTALLMODE=amus`
  MUST NOT be used to force file replacement: it turns a repair into a silent downgrade.

  The package MUST also remove any pre-existing `dig-node.exe` in the shared root before installing
  its own (`RemoveFile`, on install). The root is shared and this package is not its only writer —
  `dig-installer` drops a raw `dig-node.exe` there — and Windows Installer's file-versioning rules
  KEEP such a foreign, unversioned-looking file rather than overwrite it. Without the removal the
  package completes over a binary it did not install, and the version `dig-updater` probes next is
  the stale file's. The removal MUST be scoped to that one file by name: the root also holds
  `digstore`, `dig-dns`, `dig-updater` and `dig-app`.

  All four requirements above — root, no machine `PATH` row, removal schedule, and the scoped
  `RemoveFile` — are asserted by `scripts/tests/msi-install-root.test.sh`.
- **macOS `.pkg`** (`dig-node-<ver>-macos.pkg`, universal arm64+x86_64). Installs `dig-node` to
  `/usr/local/bin`; a LaunchDaemon `/Library/LaunchDaemons/net.dignetwork.dig-node.plist`
  (`RunAtLoad`+`KeepAlive`, `run` with `DIG_NODE_RUN_CONTEXT=service`); a tiny AppleScript app
  (`/Applications/DIG Network.app`, `CFBundleURLTypes` for the `chia` scheme) forwards URL opens to
  `dig-node open`; `postinstall` creates the restrictive state dir, `launchctl bootstrap`s the
  daemon, and registers the handler with LaunchServices.
- **Ubuntu `.deb`** (`dig-node_<ver>_amd64.deb`; `Package: dig-node`, `Depends: libc6`). Installs
  `/usr/bin/dig-node`; a systemd system unit `net.dignetwork.dig-node.service` (auto-start,
  `Restart=on-failure`, `DIG_NODE_RUN_CONTEXT=service`); a `.desktop` with
  `MimeType=x-scheme-handler/chia` registered as the system default handler; `postinst` creates
  `/var/lib/dig-node` (root-owned `0700`), the hosts entry, and enables+starts the unit; `prerm`
  stops+disables it. The filename + control metadata are **apt-correct + stable** so apt.dig.net
  ingests the Release asset to build its signed apt repo (the repo is GPG-signed by apt.dig.net; the
  `.deb` itself needs no code-signing cert).
- **Scheme registration scope.** All three register the DIG-specific **`chia://`** scheme. The
  `urn:dig:chia:` textual form is accepted by `dig-node open` (§8.5) but is NOT registered as a
  global OS handler — doing so would hijack the entire `urn:` scheme (every URN on the machine).
- **Unix service identity.** The systemd/launchd services run as **root**, so `/var/lib/dig-node`
  and `/Library/Application Support/DigNode` are root-owned `0700` and a non-root operator drives
  control with `sudo dig-node pair` (the remedy the CLI prints, §7.3a).

---

## 10. Error-code catalogue (JSON-RPC wire)

Stable contract: numeric codes, symbolic names, and origins MUST NOT be renumbered or repurposed;
additions are allowed. This catalogue is the canonical set from **`dig-rpc-protocol`** (§1.4) — it
MUST match that crate exactly. `origin` distinguishes who minted the error: `shell` (this service),
`node` (the node library), `upstream` (relayed from the upstream DIG RPC), `boundary` (the
method-not-found cue).

**Canonical control-code assignment.** The control-plane errors are `-32030`/`-32031`/`-32032`.
`-32020`/`-32021`/`-32022` are RESERVED for onion-routing errors (`onion_circuit_unavailable` /
`privacy_requires_local_node` / `onion_hops_out_of_range`) — the published normative contract on
docs.dig.net — and MUST NOT be used for control. (`dig-rpc-protocol` is the source of this resolution;
any client that branched on the old control numbers keys on the symbolic `data.code`, not the
number.) The wallet-read errors occupy `-3204x` (`WALLET_NO_CHAIN_SOURCE` / `WALLET_NOT_SYNCED` /
`WALLET_READ_FAILED` / `WALLET_RATE_LIMITED`); `-3205x` is owned by the chat plane (§ chat) and MUST
NOT collide; `-3206x` is owned by the peer plane (`PEER_PING_REFUSED`).

| Code | Name | Origin | Meaning |
|---|---|---|---|
| -32700 | `PARSE_ERROR` | shell | Request body was not valid JSON. |
| -32600 | `INVALID_REQUEST` | shell | Not a single JSON-RPC object (batch arrays unsupported); also the 421 Host-rejection body. |
| -32601 | `METHOD_NOT_FOUND` | boundary | Not resolved locally or by the upstream (internally: the passthrough cue). |
| -32602 | `INVALID_PARAMS` | node | Invalid/missing method parameters (also minted by the control plane for bad control params). |
| -32000 | `DISPATCH_FAILED` | shell | The shell failed to dispatch the request to the read path. |
| -32004 | `RESOURCE_NOT_AVAILABLE_AT_ROOT` | upstream | Genuine content miss at the requested root (relayed); distinct from transport failure. Also minted directly by the node library for a LOCAL miss at this same root — `dig.fetchRange` ("resource not held") and `dig.getManifest` ("capsule not held locally") — never a fabricated result. |
| -32005 | `ROOT_NOT_ANCHORED` | node | The node's mandatory read-path anchored-root pin (§14.4) fails closed: the requested root does not match the chain-anchored tip, the store has no confirmed on-chain generation, the chain is unreachable, or a rootless request cannot be resolved under enforcement. Minted by the node library on `dig.getContent`. |
| -32008 | `CONTENT_REDIRECT` | node | The node does not (or, under §17's throttle, will not right now) serve the requested content itself, but the DHT located peer(s) that hold it — `error.data.redirect` names them (`content`, `providers[].peer_id`/`addresses`, `redirect_depth`, `max_redirects`) so the caller re-requests there. The candidate set is CAPPED at `MAX_REDIRECT_PROVIDERS` (= dig-dht's `MAX_ADDRESSES_PER_RECORD`): a redirect NAMES holders (the requestor dials them over its own §5.2 reachability ladder — this node does NOT dial/probe them), so a few candidates suffice and probing-on-miss would itself be an amplification vector. Minted on a content miss (`dig.getContent`/`dig.fetchRange`/the peer range-stream) and on outgoing-bandwidth saturation (§17), bounded by the same redirect-hop cap either way. |
| -32003 | `CONTENT_MISS_RATE_LIMITED` | node | The requested content is not held, and the miss → DHT-lookup path is being driven too fast BY THIS REQUESTOR (§10.4). Minted instead of a redirect/fetch when the per-requestor token-bucket budget is exhausted, so an abusive caller backs off while a DIFFERENT requestor (its own bucket) is unaffected. A well-formed JSON-RPC error, never a silent empty success. Matches `dig_rpc_protocol::ErrorCode::ContentMissRateLimited` (`-32003`, canonical since dig-rpc-protocol 0.7). |
| -32009 | `RANGE_METADATA_UNREPRESENTABLE` | node | A holder cannot frame a conforming range stream for this resource (an inclusion proof over `MAX_INCLUSION_PROOF_B64` is the real case): the resource's own range metadata cannot fit a conforming frame, so this holder can NEVER serve the range. Named explicitly on the peer range-stream serve instead of truncating the stream with a bare `Err`. Matches `dig_rpc_protocol::ErrorCode::RangeMetadataUnrepresentable` (`-32009`). |
| -32010 | `UPSTREAM_ERROR` | shell | The blind-passthrough relay failed (unreachable / non-JSON). |
| -32015 | `METADATA_TOO_LARGE` | node | `dig.getMetadata` refused: the publisher metadata section is too large or too complex to render safely. Refused when the ENCODED section exceeds `METADATA_SECTION_MAX_BYTES` (3 MiB) or its `custom` exceeds `MAX_CUSTOM_ENTRIES`/`MAX_CUSTOM_JSON_DEPTH`/`MAX_CUSTOM_JSON_ELEMENTS` (both checked BEFORE decode, #2160), or the RENDERED body exceeds `METADATA_RESPONSE_MAX_BYTES` (3 MiB, #2145). This section is rendered WHOLE — it cannot be windowed like `dig.getCapsule` — and `custom`/`links` are publisher-controlled, so an oversized/hostile capsule is refused with this bounded error rather than expanded ~16× in memory or blasted into a ~100 MB response (§5.5.1). A normal (kilobyte) metadata section is served unchanged. |
| -32020 | *(reserved: onion `onion_circuit_unavailable`)* | — | Reserved for the onion-routing contract; NOT minted by the control plane. |
| -32021 | *(reserved: onion `privacy_requires_local_node`)* | — | Reserved for the onion-routing contract. |
| -32022 | *(reserved: onion `onion_hops_out_of_range`)* | — | Reserved for the onion-routing contract. |
| -32030 | `UNAUTHORIZED` | shell | `control.*` called without a valid local control token. |
| -32031 | `NOT_SUPPORTED` | shell | A control operation this build/pin cannot perform (e.g. §21 sync without an identity). |
| -32032 | `CONTROL_ERROR` | shell | A control operation failed at runtime (distinct from bad input / absent capability). |
| -32040 | `WALLET_NO_CHAIN_SOURCE` | node | `control.wallet.balance` (§ control catalog) had NO live chain source able to answer an arbitrary (non-wallet) address. Distinct from a truthful `0`. |
| -32041 | `WALLET_NOT_SYNCED` | node | `control.wallet.balance` of the wallet's OWN address while the local DB is still syncing and no live fallback is attached (nothing can answer yet). |
| -32042 | `WALLET_READ_FAILED` | node | `control.wallet.balance` failed at the underlying DB / chain-source layer. Distinct from `WALLET_NO_CHAIN_SOURCE` and `WALLET_NOT_SYNCED`. |
| -32043 | `WALLET_RATE_LIMITED` | node | `control.wallet.balance` refused: the GLOBAL coinset-fallback rate bound is exhausted (too many arbitrary-address reads hit the expensive fallback in a short window). Defense-in-depth against an open-read amplification/oracle sweep; back off and retry. The cheap local-DB fast path is never gated. |
| -32060 | `PEER_PING_REFUSED` | node | `control.peers.ping` (§7.4a) refused BEFORE dialing: a ladder is already running on this node (single-flight), or the start-rate bound for the window is exhausted. Anti-amplification — the method makes this node dial a caller-supplied address. Distinct from a ladder that ran and reached nothing, which is a RESULT (`verdict: "unreachable"`), not an error. |

Read-path and upstream errors outside this table are relayed verbatim; this catalogue governs what
the **shell** mints plus the cross-boundary codes a client must be able to branch on.

### 10.4. Miss-path amplification bounds and the explicit proxy fallback (dig_ecosystem#2007)

The content miss handler (`crate::Node::miss_outcome`, feeding `content_miss_envelope` /
`range_miss_envelope` / the peer range-stream miss) runs a DHT `find_providers` lookup — and, on an
explicit `proxy`, a full multi-source fetch — on behalf of the CALLER. The `dig.getAvailability`
batch's not-held → holder-hint enrichment (`Node::availability_answer`) runs the SAME
`find_providers` lookup per not-held item. Both spend this node's network bandwidth, so a caller who
cannot name any content it actually wants could otherwise amplify this node by naming arbitrary
`(store_id, root, retrieval_key)` triples — and a `getAvailability` batch is the LARGEST such vector,
naming up to `MAX_AVAILABILITY_ITEMS` (= 512) content ids in one request. Three bounds govern the path:

10.4.1. **Per-requestor rate limit.** A token-bucket limiter (default burst
`DEFAULT_MISS_LOOKUP_BURST` = 16, refill `DEFAULT_MISS_LOOKUP_REFILL_PER_SEC` = 4/s) sits in FRONT of
both the DHT lookup and the proxy fetch, keyed by REQUESTOR identity — the mTLS-verified `peer_id`
for a peer-origin request, the connection IP for an anonymous/gateway HTTP request, one shared bucket
for the trusted operator loopback. An over-budget requestor's miss is refused with `-32003`
`CONTENT_MISS_RATE_LIMITED`; a DIFFERENT requestor draws from its own bucket and is unaffected. The
tracked-requestor table is bounded (`MAX_TRACKED_REQUESTORS`), evicting only idle (full) buckets so
eviction can never weaken a live bound. The oracle bound is enforced upstream: a caller that cannot
name a concrete 64-hex `ContentId` (`miss_content_for` returns `None`) triggers no lookup at all.

The SAME budget bounds the `dig.getAvailability` enrichment, spent **one token per not-held item**
that would trigger a lookup (NOT one token per batch — a single per-batch check would still admit 512
lookups for one token and re-open the hole). When the requestor's bucket is exhausted, the remaining
items answer not-available WITHOUT a lookup — the redirect/`providers` hint is best-effort enrichment,
so dropping it leaves the availability answer itself (held vs not-held from local inventory)
unchanged. So the number of `find_providers` lookups a single requestor can cause via
`getAvailability` — across ANY batch size and ANY call rate — is bounded by its per-requestor token
budget, identical to the single-item legs.

10.4.2. **Candidate cap.** A redirect names at most `MAX_REDIRECT_PROVIDERS` (= dig-dht's
`MAX_ADDRESSES_PER_RECORD`) holders (§10 `-32008`); `find_providers` already caps the addresses per
record. This node NAMES holders but never dials/probes them — reachability is the requestor's job via
its own §5.2 ladder (NAT asymmetry: "peers I can reach" ≠ "peers the requestor can reach", and
probing-on-miss would itself be the amplification vector).

10.4.3. **Explicit proxy fallback (`params.proxy`, default OFF).** A requestor that cannot itself
reach any named holder (NAT asymmetry) MAY set `proxy: true` on `dig.getContent`/`dig.fetchRange`.
Under the §10.4.1 budget, the node then fetches the resource over the identical chain-anchored,
merkle-verified fetch path and serves the bytes back, instead of redirecting. Automatic
fetch-on-miss stays OFF — the caller must ask. The proxy serves bytes but the middle node does NOT
become a holder (a remote/`Peer`-origin read never triggers reshare/backfill — the reshare
amplification boundary, §14.3/§19), so proxying cannot be used to plant attacker-chosen inventory.

10.4.4. **Privacy.** A miss discloses the requested `(store_id, root, retrieval_key)` to the middle
node (it must, to locate holders). The `proxy` path additionally discloses to the serving holder that
the requestor wanted that resource — the SAME disclosure a direct read from that holder would make.
No NEW party learns the request beyond those the direct read would already involve (cross-ref
dig_ecosystem#2006/#1934 on read-path metadata exposure).

---

## 11. Release and CI contract

11.1. **Nightly cron + manual dispatch (NOT per-merge).** Releases are batched to a nightly cron
plus manual dispatch — NOT cut on every merge to `main` (dig_ecosystem #590/#592; the shape is
copied from the reference `dig-updater`). One orchestrator, `.github/workflows/nightly-release.yml`,
triggers ONLY on `schedule: cron '0 0 * * *'` (midnight UTC — GitHub cron is always UTC, and a
top-of-hour cron MAY be delayed under load, which is acceptable since both channels are idempotent)
and `workflow_dispatch` (inputs `channel` = `both`|`stable`|`nightly`, default `both`; `force`
boolean, default `false`). It MUST NOT trigger on `push` to `main`.

- **Stable channel:** cuts a `vX.Y.Z` release when — and only when — the `[workspace.package].version`
  in the root `Cargo.toml` has advanced beyond the newest `vX.Y.Z` tag (the skip-if-already-tagged
  check IS the version-changed check). Cutting = `git-cliff` regenerates `CHANGELOG.md`, commits it
  to `main` as `chore(release): vX.Y.Z`, tags THAT commit, and pushes commit + tag with
  `RELEASE_TOKEN`. The pushed `v*` tag fires `release.yml` (§11.2/§11.3), which publishes a GitHub
  Release with `prerelease: false` + `make_latest: true` — the ONLY release that moves `latest`.
- **Force re-cut (guarded).** `force: true` bypasses skip-if-tagged and re-cuts the current version
  (moving the tag onto a fresh changelog commit; `main` is never force-pushed). It MUST be refused
  — non-zero exit, clear error — when BOTH: (a) a PUBLISHED (non-draft) Release exists at the tag,
  AND (b) the tag points at a commit DIFFERENT from the one this run would build (that would
  overwrite shipped binaries with unreviewed code under the same version). Force MAY proceed for a
  same-commit re-cut (failed-build retry) or a tag with no published release (a tag repair). A
  force-moved tag breaks git tag-immutability; because dig-node updates are gated by the dig-updater
  signed feed (an Ed25519 signature over the update descriptor, verified before apply), that
  signature — not the mutable tag — is the integrity anchor. Ship new code by bumping the version.
- **The tag push is a request, not a guarantee.** Creating a workflow run from a pushed tag is an
  event delivery this repo does not control, and it has been observed to not occur even though the
  push succeeded. After pushing the tag the stable job MUST confirm that both `release.yml` and
  `package.yml` have a run for that tag, and MUST dispatch — against the tag ref — whichever is
  absent. Both workflows gate publication on `github.ref_type == 'tag'`, which a dispatch against a
  tag satisfies, so the dispatched run is equivalent to the event-triggered one. The confirmation
  MUST be idempotent: where the event was delivered normally, it dispatches nothing.
- **A stable release MUST carry the native install packages.** dig-updater's feedsign resolves
  dig-node by the `.deb`/`.pkg`/`.msi` file names and fails closed on the ENTIRE signed manifest
  when they are absent, so a stable release of bare binaries does not ship a partial dig-node — it
  freezes auto-update for every component on the channel. The stable path MUST therefore verify the
  published release's asset list (`verify-release-assets.yml`) and MUST fail the release run when
  `dig-node_<version>_amd64.deb`, `dig-node_<version>_arm64.deb`, `dig-node-<version>-macos.pkg`, or
  `dig-node-<version>-windows-x64.msi` is missing. Repairing a failed release by publishing only the
  binaries is NOT a repair.

11.1a. **Doc-only commits never release** (the version is unchanged → the tag exists → the stable
job is a no-op). The manual-dispatch `workflow_dispatch` on `release.yml` is a build-only "does main
still build?" canary — it never publishes (publish is gated on a tag ref).

11.2. **Asset naming (HARD RULE).** Every per-OS/arch binary MUST be published under the canonical
name:

- **`dig-node-<ver>-<os>-<arch>[.exe]`** — the canonical name every downstream consumer resolves:
  the dig-installer thin-shim's preferred stem AND apt.dig.net's Linux packaging template
  (`dig-node-{ver}-linux-{arch}`, bare binary).

`<ver>` is the tag without the leading `v`. The duplicate legacy `dig-companion-*` copy (dig-node
was formerly dig-companion, #209) is NO LONGER published (#585): no consumer resolves that name from
a dig-node release — the installer's pre-rename fallback targets the SEPARATE
`DIG-Network/dig-companion` repo's own frozen historical releases, not this asset name — so it was
pure release-noise.

11.3. **Matrix + the Linux platform floor (HARD RULE).** Five assets are published:
`windows-x64` (x86_64-pc-windows-msvc), `linux-x64` (x86_64-unknown-linux-gnu), `linux-arm64`
(aarch64-unknown-linux-gnu), `macos-arm64` (aarch64-apple-darwin), and `macos-x64`
(x86_64-apple-darwin, cross-compiled on macos-14). The apt `.deb` is published for both `amd64` and
`arm64`.

**Every published Linux artifact — the raw binaries AND the `.deb` — MUST run on glibc 2.31 or
newer.** 2.31 is the supported floor, and it is a floor on the whole Linux delivery surface, not a
per-workflow choice. It clears Ubuntu 20.04+, Debian 11+, Amazon Linux 2023 and RHEL 9.

A glibc-linked binary runs on its BUILD glibc and anything newer, never anything older, so the
BUILDER IMAGE alone determines this floor. Every job producing a Linux artifact therefore builds
inside a pinned old-glibc container (`debian:11`) via `.github/actions/setup-linux-build`, which is
the single place the floor is declared. It is enforced in three ways, all of which MUST hold:

- the action asserts the container's own glibc equals the declared floor, so the image and the
  number cannot drift apart;
- `scripts/check-glibc-floor.sh` asserts every produced binary's highest glibc requirement is at or
  below the floor, and additionally FAILS a binary that carries no versioned glibc symbols at all
  (the musl substitution below); the release job re-runs it against an impossible floor to prove the
  gate can still fail;
- `verify-linux-floor` EXECUTES each published binary in `ubuntu:22.04`, `debian:12` and
  `amazonlinux:2023` containers on both architectures — a link-time claim is not proof that a binary
  starts.

**Every Linux artifact MUST be built for a `*-unknown-linux-gnu` target. A `*-unknown-linux-musl`
target is REJECTED**, and is not an acceptable substitute for the old-glibc container even though it
would satisfy the floor trivially. musl's built-in resolver is not a drop-in for glibc's: it supports
no NSS modules, handles a much narrower subset of `resolv.conf`, and historically does not fall back
to TCP when a UDP answer exceeds 512 bytes — precisely the shape of a DNS-seed record set carrying
many A/AAAA entries, which the node depends on to find its first peers. Meeting the glibc floor by
changing the C library therefore changes node behaviour and is a breaking change, not a build detail.

Raising the floor is a DELIBERATE, coordinated act: the declared value, every calling job's
`container:` image, this section, and the published docs move together. Both Linux architectures
build NATIVELY (aarch64 on the arm64 runner), so no vendored-OpenSSL cross-compile is involved.

11.3a. **The `dig-constants` genesis floor (HARD RULE).** A stable tag MUST NOT be cut while any
`dig-constants` copy in the resolved workspace lock is below **0.4.0**.

0.4.0 is the first release carrying the real DIG L2 mainnet genesis challenge. `dig-constants` 0.1.0
shipped an all-zeros PLACEHOLDER, with all six AGG_SIG additional-data domains correctly DERIVED from
that placeholder — a self-consistent set, and therefore invisible to every test, because each runtime
check compares the constant against itself. A copy below the floor puts a different chain identity
inside the binary. The rule is stated as a FLOOR over the whole pre-0.4.0 CLASS, not as an inequality
against 0.1.0: 0.2.x and 0.3.x carry the same placeholder.

It is enforced at two levels, and both MUST hold:

- `crates/dig-node-core/tests/dependency_tree.rs` asserts it against the workspace lock on every
  build, so a dependency edit that reintroduces a pre-0.4.0 copy fails CI, not the release;
- `scripts/check-dig-constants-current.sh` re-asserts it in the stable release job, BEFORE version
  resolution, so a breach means no tag exists to deploy. It fails closed on the lock: a missing
  lockfile, or one carrying no `dig-constants` at all, is refused rather than vacuously passed.

The gate additionally REPORTS, without blocking, that several `dig-constants` versions resolve at
once, naming the package that pins each. That stays advisory because those pins live in published
metadata this repo cannot edit, and every copy at or above the floor agrees on the chain identity.
Currency against the published crates.io tip is NOT required and MUST NOT be gated on: a
`dig-constants` release that advances the `chia-protocol`/`chia-wallet-sdk` line cannot be adopted
here while `dig-gossip`'s vendored `chia-protocol` fork is patched in, so a currency gate would ban
releasing rather than protect a property.

11.4. **Release hardening.** The release profile keeps `overflow-checks = true` (the read path
does offset/length arithmetic over untrusted serialized input).

11.5. **Nightly channel.** Every night (and on demand) the orchestrator builds `main` HEAD for
every OS/arch and publishes a GitHub **pre-release** — so a fresh nightly always exists regardless
of a version bump. It synthesizes a build-time version `X.Y.Z-nightly.YYYYMMDD.<shortsha>` (nothing
is committed; as a semver prerelease it sorts BELOW the plain `X.Y.Z`), publishes under a dated tag
`nightly-YYYYMMDD` AND force-moves a rolling `nightly` tag, with `prerelease: true` and **never**
`latest`. Retention keeps the newest **14** dated nightlies plus the rolling `nightly`, pruning
older dated pre-releases AND their tags together (`gh release delete --cleanup-tag`); `v*` stable
tags/releases and the rolling `nightly` are NEVER pruned. Neither `nightly-*` nor `nightly` matches
`release.yml`'s `v*` trigger, so the nightly channel never fires the stable build.

11.5a. **Both channels publish the NATIVE INSTALL PACKAGES (HARD RULE).** A release — stable OR
nightly — MUST carry the three native packages, not raw binaries alone. The beacon installs dig-node
by handing a native package to `msiexec`/`installer`/`dpkg`, and dig-updater's feed resolves
dig-node's artifacts by their native-package file NAMES, so a package-less release is one the update
system cannot resolve at all: it fails closed and no host on that channel can install or update.
Every release MUST therefore publish, under exactly these names (`<ver>` = the release's version,
which for a nightly is the synthesized `X.Y.Z-nightly.YYYYMMDD.<shortsha>`):

- `dig-node_<ver>_amd64.deb`
- `dig-node-<ver>-macos.pkg`
- `dig-node-<ver>-windows-x64.msi`

The nightly publish step MUST verify all three are present and FAIL rather than publish an
incomplete release. The packages are built by `.github/workflows/package.yml`
(`on: workflow_call`, inputs `version`, `deb_arches`, `ref` — all optional, so its `pull_request`
and `v*` tag triggers are unaffected), which both channels call, so the definitions cannot diverge.
The nightly `.deb` is **amd64 only** — the feed resolves a single Linux platform; the stable tag path
keeps both `amd64` and `arm64` because apt.dig.net serves both (§11.3).

11.5b. **The version is validated at ONE boundary, and the MSI version is derived.** Every package
build passes its version through `scripts/package-version.sh` before it reaches a dpkg control file,
`pkgbuild --version`, or the WiX `-d Version=` argument — all of which end up inside a package that
runs with elevated privilege. The script accepts, by whitelist, ONLY `X.Y.Z` or
`X.Y.Z-nightly.YYYYMMDD.<shortsha>`, and rejects everything else with a non-zero exit; it MUST also
reject a component exceeding Windows Installer's field limits (major/minor > 255, patch > 65535).

It emits two values, which differ on purpose:

- **`file_version`** — the version VERBATIM. The package file name MUST carry it unchanged, because
  the rolling `nightly` tag names no version and the feed recovers it from the asset name alone.
- **`msi_product_version`** — a numeric `major.minor.build`, since Windows Installer accepts no
  prerelease suffix. For a nightly this is `X.Y.<days since 2020-01-01>`. The date MUST occupy the
  BUILD field rather than a fourth field: Windows Installer compares only `major.minor.build`, so a
  fourth field is parsed and then ignored — the date would stop being comparison-significant at all.

The version whitelist also means a prerelease-shaped STABLE tag (`v1.0.0-rc.1`) is REJECTED rather
than packaged. That is intended: §2.4 of the ecosystem contract admits only `X.Y.Z` stable versions,
and an `-rc` MSI would carry the same ProductVersion hazards as a nightly with none of the handling.

11.5c. **The MSI upgrade invariant (HARD RULE).** For any two distinct nightly builds, the later one
MUST NOT compare LOWER than the earlier, and any pair that compares EQUAL MUST be made safe by an
explicit same-version-upgrade policy. The beacon installs with a bare `msiexec /i <pkg> /qn
/norestart`, so a violation of either half is a broken host: a LOWER comparison aborts on
`DowngradeErrorMessage`, and an EQUAL comparison falls outside `MajorUpgrade`'s `[0.0.0,
ProductVersion)` detect range — matching neither the upgrade nor the downgrade case, so the build
installs as a SECOND product under a fresh auto `ProductCode`, leaving two entries that both own the
`net.dignetwork.dig-node` service.

The mapping alone CANNOT satisfy this. The synthesized nightly version carries a DATE and a commit
sha and nothing else, so the ProductVersion is day-granular by construction, and 16 bits of build
field cannot hold a finer monotonic counter over any useful epoch (minute resolution exhausts the
field in 45 days; a sha-derived tiebreak is not ordered, which would produce the far worse LOWER
case). Two builds on one UTC day are reachable on supported paths — the `force` re-cut, and a manual
`channel: nightly` dispatch on a day the cron already ran.

The invariant is therefore held JOINTLY, and both halves are required:

- **the mapping** never decreases across builds (the day count is monotonic, and a base-version bump
  raises `major`/`minor` first);
- **`packaging/windows/dig-node.wxs`** sets `MajorUpgrade/@AllowSameVersionUpgrades="yes"`, so an
  equal version upgrades in place. This also repairs the same hazard for a stable re-install of an
  unchanged `vX.Y.Z`. WiX raises ICE61 for this by design; the warning IS the decision.

**Known consequence — a nightly Windows host cannot install a stable release of the same
`major.minor`.** Because the nightly build field is a day count, it sits above every real patch
number, so `0.96.<days>` outranks every stable `0.96.z`: `msiexec` aborts on
`DowngradeErrorMessage`, and the beacon cannot detect this because anti-rollback state is kept per
channel. This is not a regression — no nightly `.msi` existed before — but it is newly reachable. A
host switched from `nightly` back to `stable` on Windows requires an uninstall of the nightly
package before the stable one installs, until the version scheme distinguishes channels.

11.6. **Reusable build.** The cross-OS build lives once in `.github/workflows/build-binaries.yml`
(`on: workflow_call`, inputs `version` + `ref`). Both `release.yml` (stable) and the nightly channel
call it, so the two paths can never diverge on HOW a binary is produced — including the canonical
`dig-node-*` naming (§11.2) and the `dign` alias.

11.7. **RELEASE_TOKEN posture + 60-day cron caveat.** Releasing uses the `RELEASE_TOKEN` org PAT,
not `GITHUB_TOKEN` (a tag pushed by `GITHUB_TOKEN` does not trigger downstream workflows, and it
cannot push a changelog commit past branch protection). If `RELEASE_TOKEN` is absent, EVERY channel
NO-OPS with a clear `::warning::` — never a half-release. A `concurrency: nightly-release` group
(cancel-in-progress `false`) serializes runs. GitHub auto-disables a `schedule:` trigger after 60
days with no repo activity on a public repo, with no auto-re-enable — and since this cron is now the
ONLY automatic release trigger, a quiet repo can silently stop releasing. Detect with
`gh api repos/DIG-Network/dig-node/actions/workflows/nightly-release.yml --jq .state`
(`disabled_inactivity` = auto-disabled) and recover with `gh workflow enable nightly-release.yml`
(see `runbooks/release.md`).

---

## 12. Security properties (summary)

- **Never LAN-exposed:** loopback-only binds (§4.1); no `0.0.0.0` or `[::]`.
- **Anti-DNS-rebinding:** Host allowlist with 421 rejection (§4.2); CORS reflects only local
  origins (§4.3).
- **Read/control split:** read methods open to local consumers; `control.*` requires possession of
  the same-host capability file, compared in constant time, failing closed when unpersistable
  (§7.2–7.3).
- **Machine-wide auth state, not world-readable:** the control token + paired-token store live in a
  machine-wide state dir resolved identically by the daemon and the operator CLI, restricted by ACL
  to SYSTEM + Administrators + the creating user (Unix `0700`/`0600`) — never all-users-readable, so
  it is not a local privilege-escalation vector (§7.3a). The operator CLI reads the token read-only
  and never mints a rival token.
- **Untrusted scheme-handler input:** `dig-node open` (the OS `chia://`/`urn:dig:chia:` handler,
  §8.5) strictly validates its argument and launches the resolved URL without a shell.
- **Blind serving:** content reads return ciphertext + proofs; verification/decryption is the
  client's job (§1.3). The node never returns plaintext for content reads.
- **A filesystem path is never built from unvalidated caller input:** every cache/staging path is
  constructed from a VALIDATED capsule key — two canonical 64-hex ids — and a caller-supplied
  `store_id`/`root` pair that is not canonical is REFUSED (answered not-held) without any filesystem
  access. The validation is a TYPE that only the validating constructor can produce and that the path
  builders exclusively accept, so the check cannot be omitted at a new call site rather than a predicate
  each site must remember to call. Canonical 64-hex is a whitelist over an ALPHABET containing no `/`,
  `\`, `.`, `:`, NUL or control character, so it is complete by construction — unlike a blacklist of
  `..`, absolute prefixes and UNC roots, which would have to be complete against every platform's path
  grammar. Merkle verification is NOT a substitute: it proves provenance, not that a path is safe.
- **No secrets in artifacts:** the control token is generated at runtime, ACL-restricted (§7.3a),
  and never committed or logged.

---

## 13. Conformance summary

| # | Contract | Must match | Where enforced / specified |
|---|---|---|---|
| 1 | Read-plane wire contract | `rpc.dig.net` byte-for-byte (dispatch IS `dig_node_core::handle_rpc`) | §1.3, §5; `dig-rpc-protocol` + docs.dig.net Protocol pages |
| 2 | `DIG_NODE_PORT` / `DIG_NODE_HOST` names | dig-installer + apt.dig.net expectations — never renamed | §3.1 |
| 3 | Shared cache default | Byte-identical dir to the DIG Browser's in-process node when `DIG_NODE_CACHE` unset | §3.5 |
| 4 | `dig.local` addressing | dig-installer hosts entry `127.0.0.2  dig.local`; listener `127.0.0.2:80`, best-effort | §4.1–4.2 |
| 5 | Host/CORS allowlist | `dig.local` / `localhost` / `127.0.0.1` / `127.0.0.2` / `::1` (+ `chrome-extension://` origins) | §4.2–4.3 |
| 6 | Method catalogue ↔ read path | drift guard: `local` resolves, `passthrough` returns `-32601` at the pinned rev | §5.5–5.6; `tests/openrpc_drift_guard.rs` |
| 7 | Error codes | Table §10 — stable numbers + UPPER_SNAKE names + origins | §10; `src/meta.rs` |
| 8 | CLI exit codes + `--json` envelopes | Table §8.4; one JSON object on stdout | §8; `src/cli.rs`, `tests/cli.rs` |
| 9 | Service label | `net.dignetwork.dig-node` across install/uninstall/start/stop/SCM dispatcher | §2.4, §9.4 |
| 10 | Release assets | Canonical `dig-node-*` (+ `dign-*` alias), per §11.3 matrix | §11; `.github/workflows/release.yml` |
| 11 | Control-token scheme | `<state_dir>/control-token` (machine-wide, ACL-restricted, §7.3a), 64-hex, `X-Dig-Control-Token` / `params._control_token`, constant-time | §7.2–7.3a |
| 12 | Health/version/well-known shapes | §6 fields; additions additive only | §6; `src/meta.rs`, `src/server.rs` |
| 13 | Subscription persistence | `<cache>/subscriptions.json` schema-versioned, atomic, cross-process-locked | §14.1; `subscription.rs` |
| 14 | Autonomous sync fail-closed | chain-watch + gap-fill + read-path pin never serve/pull against an unconfirmable root | §14.2–14.4; `chainwatch.rs`, `lib.rs` |
| 15 | FFI C-ABI | `dig_runtime_start`/`dig_runtime_start_wallet` (wallet-only vs full) + `dig_rpc`/`dig_wallet_rpc`/`dig_free` + read-crypto `dig_read_verify_decrypt`/`dig_bytes_free` (`DIG_READ_*` codes) signatures + ownership/threading | §15, §15.1; `dig-runtime/src/lib.rs` |
| 16 | Wallet broadcast gate | dry-run default; mainnet push requires `DIG_WALLET_ALLOW_BROADCAST=1`; a dapp cannot force it | §16; `dig-wallet/src/lib.rs` |

---

## 14. Autonomous sync — subscriptions, chain-watch, generation gap-fill

The node engine keeps its held content current WITHOUT being asked: it watches the chain for the
stores it subscribes to, proactively pulls the generations it is missing, and pins every serve to the
chain-anchored root. All of this fails **closed** — an unconfirmable root is never served against or
pulled.

**Bring-up.** The chain-watch + gap-fill loop is started by the OS-service bring-up as part of the
peer network: `dig-node run` (and the Windows SCM entrypoint) call `peer::spawn_peer_network`, which
installs the P2P content engine + the DHT inventory refresher and spawns the chain-watch loop
(`crate::chainwatch`). It is gated by `DIG_PEER_NETWORK` — ON by default; `off`/`0`/`false` opts a
standalone read-only node out of the whole peer network (pool + DHT + watcher), leaving the HTTP read
path serving. Bring-up is best-effort and detached: a failure is recorded on `control.peerStatus` and
never blocks reads. The in-process FFI host (`dig-runtime`, §15) does NOT run this — the browser is a
consumer, so its node installs no P2P content and runs no watcher (its in-process trust boundary).

### 14.1. Subscriptions

A **subscription** is a store the node intends to actively HOLD, WATCH, SYNC, and PUBLISH. It is
DISTINCT from the durable capsule inventory (the `.dig` modules under the cache dir): the inventory
answers "what does this node currently hold?", the subscription set answers "what does this node
intend to keep current?". A store MAY be subscribed before any of its modules are held (the watcher
pulls them down), and a module MAY be held without a subscription (a one-off cached read).

- **Persistence.** The set is persisted to `<cache>/subscriptions.json` (next to `config.json`, so it
  shares the cache's writability + lock handling). The on-disk document is
  `{ "version": <u32, currently 1>, "stores": [<lower-case 64-hex store id>, …] }`. The schema is
  **additive-only** (a future per-store option is a backwards-compatible field; a bump never removes or
  repurposes a field).
- **Normalization.** Store ids are trimmed + lower-cased on insert, de-duplicated, and kept in
  insertion order. A malformed (non-64-hex) entry MUST be dropped on load, never admitted to the
  watched set.
- **Tolerant load.** A missing, empty, or unparseable file is an EMPTY set (never an error). A legacy
  bare `{ "stores": [...] }` document (no `version`) MUST still load.
- **Atomicity.** Writes MUST be atomic (temp-file + rename) and serialized by the SAME cross-process
  advisory lock the `config.json` read-modify-write uses, so two DIG processes sharing the cache (the
  browser's in-process node + the standalone node) cannot lose each other's subscription updates.
- **Management.** The set is managed by the node-owned control methods `control.subscribe`,
  `control.unsubscribe`, and `control.listSubscriptions` (delegated to the node by the shell, §5.5/§7).
  `subscribe` is idempotent (re-subscribing is a no-op); `unsubscribe` of a store that is not
  subscribed is a no-op; the RPC echoes the EXACT normalized id it persisted so the echo can never
  disagree with `listSubscriptions`.

### 14.2. Chain-watch loop

A background loop polls each SUBSCRIBED store's CHIP-0035 singleton to detect a newly-confirmed
generation.

- **Interval.** The poll interval is `DIG_NODE_WATCH_INTERVAL` seconds, defaulting to `30` and
  **floored at `1` s** (a `0`/unparsable/unset value ⇒ default; the floor prevents a mis-set value from
  flooding coinset).
- **Per-store decision (fail-closed).** After resolving the store's chain-anchored tip root — using the
  SAME anchored-root resolver the read path uses (§14.4) — the watcher decides:
  - chain read failed (`Err`) → **Skip** (never gap-fill against an unconfirmable root);
  - no confirmed generation (`Ok(None)`) → **Skip**;
  - the confirmed tip is already held locally → **Skip**;
  - the confirmed tip is NOT held → **GapFill** `(store_id, tip)` (§14.3).
- A failed pull is simply retried on the next tick.

### 14.3. Generation gap-fill

Gap-fill is the actuator that pulls a missing generation for `(store_id, root)` from another node,
VERIFIES it against the chain-anchored root, and lands it in the node's cache. A module that arrives at
a root OTHER than the confirmed root MUST be rejected (never cached or served).

- **Two triggers.** (a) **Proactive** — the chain-watch loop (§14.2) for subscribed stores, so the node
  *actively seeks other nodes to pull missing generations* rather than only reacting to reads.
  (b) **Backfill-on-miss** — when a read is satisfied from another node or the upstream rather than
  from local disk, the node background-backfills the whole capsule so the NEXT read of that resource is
  served locally (deduplicated: a backfill already in flight for `store:root` is not started twice). This
  dedup spans BOTH whole-capsule transports: the §21 backfill here and the §21.3 P2P reshare warm claim
  ONE shared single-flight gate keyed `(store, root)`, so a read starts at most one whole-capsule pull no
  matter which leg wins, and the shared cap bounds concurrent distinct-generation acquisitions across the
  two legs together. Enabled by default; toggle with the `DIG_NODE_BACKFILL_ON_MISS` environment variable.
- **Fail-closed.** Gap-fill never pulls against an unconfirmable root (the §14.2 decision gates it).
- **Verification invariant.** Every served module is verified against the chain-anchored root at SERVE,
  no matter how it arrived — a client read, a §21 whole-store sync, or a proactive/backfill gap-fill.
- **Verify-before-announce invariant.** A synced capsule MUST ALSO pass the chain-anchored verification
  BEFORE it lands in the cache, because landing a capsule makes this node a DISCOVERABLE holder of it
  (§14.1) — an announcement, not merely a local copy. The node resolves the store's chain-anchored root,
  re-hashes the downloaded module against it, and refuses anything that is not the store's confirmed
  generation, so the module never reaches disk and is never announced. The serve-time gate is not
  sufficient on its own: a node that advertises a capsule poisons holder reputation and multiplies it
  through the reshare flywheel whether or not any later read verifies it. This is the SAME chain-anchored
  check the reshare leg applies at its own seam — one verification shape at every seam that admits a capsule.

### 14.3a. Whole-capsule download — two paths, chunked first

Landing a whole `.dig` for `(store_id, root)` is the mechanism BOTH gap-fill triggers and the
control-plane sync run on. The node MUST attempt these paths in this order:

1. **The chunked `dig.getCapsule` JSON-RPC** (`POST` on the upstream base URL). The node pages the
   capsule in windows of at most **3 MiB** — the upstream's own per-response ceiling — following the
   server's `next_offset` until `complete`. This path is ANONYMOUS: it MUST work on a node holding
   no §21.9 identity.
2. **The §21.9 authenticated clone** (`GET /stores/{id}/module`), attempted only when an identity is
   loaded. Retained for §21 hosts exposing no `dig` JSON-RPC.

The chunked path MUST lead, not serve as a fallback: a single-response clone cannot carry a
production-sized capsule across an HTTPS edge that caps a response body, so for real stores it is
the only path that completes.

The node MUST send the CONCRETE root it resolved and MUST NOT send `"latest"`. A server-chosen
generation would be a server choosing which generation this node caches, reshares, and announces
itself a holder of; the chain is the only authority for a store's tip.

Every window is validated before it is trusted. The node MUST reject a download whose declared
`total_length` exceeds **4 GiB**, whose `total_length` changes between windows, whose served offset
differs from the requested one, whose `next_offset` fails to advance, or whose reassembled length
differs from the declared length. Rejection is required BEFORE the bytes are gathered where the
declaration alone is disqualifying, so a dishonest upstream cannot drive an unbounded allocation or
an endless loop.

A failed download MUST be reported with the ACTUAL failure — the upstream's HTTP status, its
JSON-RPC error code and message, or the specific validation that rejected it. A diagnostic naming
causes that were not checked is non-conformant.

### 14.4. Read-path anchored-root pin

Every `dig.getContent` serve is PINNED to the store's chain-anchored tip root (#127): the node serves
against the on-chain current root or fails closed — it NEVER trusts an upstream-/host-reported root.

- For an **explicit-root** request the requested root MUST equal the resolved anchored tip; a mismatch
  is rejected. For a **rootless** request the node resolves the tip and serves against it.
- The anchored tip is resolved by the store's singleton-lineage walk. For an **explicit-root** request,
  a walk aborted by a single unparseable intermediate generation (#747 "parse next store: missing
  child") MUST NOT block a valid pinned root: the pin falls back to a BOUNDED verify that reads only the
  CURRENT unspent generation (one launcher-hint query — `digstore_chain::verify_pinned_root`), accepting
  the pinned root only when it equals the live on-chain root. This is fail-closed and preserves #127
  anti-rollback (a stale/never-anchored root is still rejected). A rootless request has no candidate to
  bounded-verify and relies on the walk.
- The pin fails closed with `-32005 ROOT_NOT_ANCHORED` (§10) on: a root mismatch, an unreachable chain,
  a store with no confirmed generation, or a rootless request under enforcement.
- The pin is ENFORCED by default. The ONLY opt-out is the explicit `DIG_NODE_PIN=off` (also `0`/`false`)
  environment variable, a named offline/local-development escape hatch — never the default. The pin is
  a NODE-side gate; clients still verify the returned proof against their own trust root regardless, so
  the opt-out only relaxes the node's serve gate for local dev.

### 14.4a. Per-path generation resolution (#2088) — serve TIP-AUTHORITATIVE, redirect only on a genuine tip miss (#2211)

A resource UNCHANGED since an earlier commit lives in an OLDER capsule whose own root ≠ the tip;
serving it at the tip (where its ciphertext is absent) folds to the constant-time decoy and reads as
a miss. The tip capsule's §13 `PublicManifest` records, per public path, the `latest_root` of the
generation that actually holds the file plus its `sha256_latest` leaf, so the serve CAN redirect to
that older generation — reporting the resolved generation as `X-Dig-Generation`.

**The serve is TIP-AUTHORITATIVE (fail-closed, #127/#2211 anti-rollback).** The `PublicManifest`
(§13) is an ADDITIVE `.dig` section that is NOT committed into the chain-anchored `current_root` and
NOT checked by the capsule anchor gate, so a malicious holder can serve a genuine, anchor-passing tip
capsule carrying a FORGED §13 whose per-path `latest_root`/`sha256_latest` redirect the read at other
content. To defeat this, the node MUST resolve the read in this order:

1. **Tip first, with NO §13 leaf binding.** Attempt the serve against the chain-anchored tip
   (`serve_root == tip`, `expected_leaf` absent), binding the bytes SOLELY by `proof.root == tip`.
   The tip's own `current_root` commits exactly the tip generation's leaves, so a path whose CURRENT
   version the tip holds is served from the tip — the §13 redirect is never consulted for it, and a
   §13 forged to name a genuine-but-superseded prior generation for that path CANNOT downgrade it.
2. **§13 redirect only on a genuine tip MISS, and only from a tip capsule that BACKS its committed
   root.** When the path is ABSENT from the tip capsule (its latest version legitimately lives in an
   older generation, so the tip serve folds to the decoy), the node consults the §13 entry and MAY
   redirect to that older `serve_root`. The redirect is honoured ONLY when BOTH hold:
   - **(a) the tip capsule genuinely backs its committed `current_root`.** The node re-derives the tip
     capsule and requires the merkle root recomputed from its own `MerkleNodes` to equal the committed
     `CurrentRoot`, AND that committed root to equal the chain-anchored tip. The capsule anchor gate
     compares only the 32-byte `CurrentRoot` HEADER against the chain, so it admits a capsule whose
     header still names the genuine tip while its data was tampered so a tip-committed path no longer
     folds to it — which would turn a forged tip MISS into a §13 redirect (a rollback). A tip capsule
     whose data does not fold to its committed tip is refused as a redirect source: its misses are
     untrustworthy, so the read stays a clean miss rather than a downgrade. (Implemented
     dig-node-locally by recomputing the tree via digstore's `verify_module_root`; the premise that "a
     tip MISS means the path is legitimately absent from the tip generation" is thereby ENFORCED, not
     assumed.)
   - **(b) `serve_root` is a GENUINE root in the store's authenticated on-chain singleton lineage** —
     the SAME lineage authority the §14.4 pin walks (`sync_datastore_with_history` membership). A root
     NOT in the lineage (fabricated, or unconfirmable) MUST NOT be served from.

   On this redirect path `expected_leaf` (= the tip manifest's `sha256_latest`) IS additionally
   enforced fail-closed on every tier so the older, non-chain-anchored capsule cannot substitute other
   bytes for the path. A non-Served tip outcome — a decoy MISS or an upstream ERROR — is deferred while
   a §13 redirect candidate remains, so a tip-pass upstream error never pre-empts a legitimate
   older-generation read (#2088).

- `serve_root` is NEVER client-derivable: a superseded root named in the REQUEST still fails
  `-32005` (§14.4) — only the node's own trusted tip manifest, cross-checked against the lineage, may
  redirect the read.
- **Case A is CLOSED (including against a tampered tip capsule).** A path whose CURRENT version the
  tip commits is served from the chain-anchored tip (forged redirect never reached), and a redirect is
  refused entirely when the tip capsule does not back its committed root — so a holder cannot forge a
  tip MISS to force the downgrade (#2211). **Case B remains OPEN:** a path whose current version
  genuinely lives in an OLDER generation than the one a forged §13 names — here the tip capsule
  legitimately backs its root and the path is genuinely absent from the tip, so the redirect is
  honoured and a §13 forged to name a genuine-but-superseded prior generation still rolls that path
  back, a downgrade BOUNDED to owner-committed content. Full closure requires a per-path current-state
  commitment the tip anchors (tracked in digstore #2203); `expected_leaf` binds the served bytes to
  *a* genuine lineage generation, it does NOT prove that generation is the path's canonical current one.
- **`X-Dig-Generation` is advisory, not trusted.** It is stamped from the §13 `generation_index`,
  which is additive/uncommitted and thus attacker-forgeable — a forged §13 can misreport the
  generation NUMBER even for a Case-A serve whose BYTES are the correct chain-anchored tip. The served
  bytes stay safe; only this cosmetic header can be spoofed. Closed by the same #2203 per-path
  commitment.
- No manifest / no entry (legacy `.dig`, private store, or a key outside the public surface) ⇒ serve at
  the tip with no leaf binding, byte-identical to the pre-#2088 behaviour.

### 14.5. Store-melt propagation (receive → on-chain-verify → delete → rebroadcast, #1316)

When a store's CHIP-0035 singleton is MELTED (the store-lifecycle delete), the deletion PROPAGATES
across the peer network so every holder stops hosting the store's `.dig` content and reclaims disk.
The wire is dig-gossip opcode **221** (`STORE_MELTED`, a `StoreMeltedAnnounce`: `store_id`,
advisory `melt_height`, `sender_peer_id`, BLS signature). It is a **public all-peers broadcast**
(Plumtree flood, Bulk priority), **§5.4-EXEMPT** from recipient-sealing: a store deletion is
public-by-nature and addressed to everyone, like L2 consensus gossip. It is mTLS-authenticated +
signed, never recipient-sealed.

**The on-chain melt proof is the SOLE delete authority (NC-9, fail-closed).** A node MUST NEVER delete
unless the chain POSITIVELY confirms the melt — a forged/replayed announcement, or a chain the node
cannot reach, deletes NOTHING. The announcement's signature is attribution/anti-spam ONLY (never delete
authority), and `melt_height` is an advisory hint the receiver never trusts on its face.

A store is confirmed MELTED only by walking its singleton lineage along real COIN PARENTAGE:

1. **Identity + minted.** The launcher coin whose `coin_id == store_id` MUST exist and be SPENT.
   `coin_id == store_id` is a 256-bit hash preimage an attacker cannot grind, so it pins the walk to
   the real store — never to a look-alike singleton that merely *curries* `launcher_id == store_id`,
   which IS forgeable. `spent` proves the store was ever minted (the launcher is spent exactly once,
   to create the eve singleton). An UNSPENT launcher is `Live`: not minted yet is the opposite of
   melted. This fact discriminates nothing on its own — it holds for every minted store — it anchors
   the walk's starting point.
2. **Walk forward by parentage.** At each hop, read the children of the current coin, DISCARD any
   returned coin whose `parent_coin_info` is not the current coin (the soundness argument is that
   parentage is fixed by which coin was actually spent — taking the server's word for membership of a
   "children of X" page would hand that argument back to whatever answered), and follow the
   single ODD-amount child (the singleton, whose amount is invariant across generations). An UNSPENT
   successor is `Live`. A spent coin with NO successor is `Melted` — the lineage terminated.

A coin's `parent_coin_info` is fixed by which coin was actually spent to create it, so **placing a
coin anywhere in this walk requires spending a generation of the store, which requires the owner's
authority.** The walk is unwritable by anyone but the owner.

Everything else is `Unknown` (fail-closed): any chain read that errors or times out — including
MID-WALK, which MUST NOT read as "the lineage ended here" — more than one odd child (ambiguous; never
guess which continues the lineage), an absent launcher coin, and exceeding the hop ceiling.

**Only a COMPLETELY EMPTY children page may conclude a melt, and never at hop 0.** Both halves are
load-bearing:

- *Hop 0.* A minted launcher always created the eve singleton, so an empty first hop means the answer
  is untrustworthy — a non-datastore launcher, or a chain-read implementation that does not implement
  the parent-ids query.
- *Completeness.* The children query honours a server-side limit, and truncation surfaces SPENT
  records first. Measured on coinset against the sibling hint query: no limit returns 349 records of
  which 243 are unspent, while `limit=5` returns 5 records of which **zero** are unspent. A truncated
  page that kept an even change coin but dropped the odd successor would read exactly like a
  terminated lineage. Requiring the page to be *entirely* empty is what asserts COMPLETENESS instead
  of trusting a page — truncation cannot turn a non-empty result set into an empty one short of a
  zero limit, which is never sent. Children present with no singleton among them is `Unknown`.

Two cheaper signals MUST NOT be used, both having shipped and been found unsound:

- **`anchored_root() == Ok(None)`** means *no confirmed generation* (fail-closed) everywhere else in
  the node, and is produced for a store that is **not minted yet**. A genuine melt does not even
  produce it — the lineage walk errors for a tip spent without a datastore child.
- **The `store_id` hint index.** A hint is an unauthenticated `CREATE_COIN` memo over an arbitrary
  32-byte value, so ANY party can place a record under ANY store's hint for the price of a dust coin.
  Measured against mainnet: of the 53 DataLayer stores, **30 live stores have a completely EMPTY
  `store_id` hint index** — their generations are not hinted to `store_id` at all — so for each of
  them one planted spent coin would make the index non-empty and entirely spent, indistinguishable
  from a terminated lineage. `get_coin_records_by_hint` is also truncatable, and truncation surfaces
  spent records first: the exact order that manufactures a false melt. The hint index MUST NOT carry
  a delete decision.

**Operator kill switch.** Store-melt propagation MUST be disableable at runtime via
`DIG_NODE_STORE_MELT` (default ON; only an explicit `off`/`0`/`false`/`no` disables it), matching the
shape of `DIG_NODE_BACKFILL_ON_MISS`. This is the node's only path that irreversibly deletes content
in response to chain state, and it propagates, so a fault is correlated across holders rather than
isolated; an operator MUST be able to stop the deleting without downgrading the node. Disabling is
lossless — melted stores simply keep costing disk, and nothing else depends on melt propagation
having run.

**Conformance to real chain state (measured, not derived).** Across all 53 DataLayer launcher coins
on mainnet this rule yields 51 `Live` (deepest lineage 599 generations; 29 stores have their tip one
hop from the launcher) and 1 `Melted` — the one genuinely terminated store, which ends at hop 1. No
lineage produced an ambiguous fork. Because the walk costs one chain read per generation and the
receive path runs per inbound announcement, verdicts are memoised for a short TTL so a flood of
announcements for one held store cannot multiply into repeated walks; a stale verdict can only DELAY
a real melt, never cause a delete.

- **Holder path (the melting node).** For a store the node HOLDS whose singleton the chain confirms
  closed, and which is not already tombstoned: delete EVERY held generation (the audited cache-remove
  path — path-containment guarded, content-cache invalidating, idempotent), broadcast a signed
  `StoreMeltedAnnounce`, and tombstone the store. Live/Unknown ⇒ no-op (retried next tick).
- **Receiver path (a peer).** Per inbound opcode-221 frame, in strictly-increasing cost order (so an
  un-held flood is O(local) per message and can never amplify into chain work): (1) **held-check FIRST**
  — if the store is not held, drop with NO chain read, NO signature verification, NO rebroadcast; (2)
  **tombstone check** — a re-receipt drops with no chain read; (3) **NC-9 on-chain verify** — only a
  confirmed melt proceeds (fail-closed on Live/Unknown); (4) **delete + rebroadcast ONCE** — gated on a
  compare-and-set into the shared tombstone, so only the holding→deleted transition re-emits (excluding
  the sender).
- **Termination.** Each node broadcasts at most once per store (the CAS admits one transition), the
  tombstone is set-once (never cleared in-run), and dig-gossip's Plumtree seen-set dedups frames
  network-wide — so the epidemic quiesces after every holder has deleted once.
- **§5.1 preserved.** Deleting a CACHED `.dig` is safe: the on-chain anchor is permanent and this
  touches no history/anchor. Melt does not rewrite or break any older `.dig` format.

The receive/holder policy is unit-tested against spy seams (chain / cache / broadcast) with the eight
adversarial cases: forged-melt-for-live, chain-error-fail-closed, genuine-melt (delete-all +
rebroadcast-once), never-held (no chain call), already-tombstoned, verify-cost DoS (held-check before
chain), multi-node convergence-terminates, and holder fail-closed on transient error. The chain-fact →
verdict mapping is separately tested against the real chain-read trait with a crafted lineage, whose
mock PANICS if either hint query is touched: a terminated lineage is the ONLY shape that yields
`Melted`; an unspent tip at 1/2/7/60 hops, an unspent launcher, an absent launcher, an empty hop 0, an
even-amount child, an ambiguous two-odd-child fork, a transport failure on the launcher read OR
mid-walk, and an endless lineage all resolve to `Live` or `Unknown`. The composition that broke the
previous design — an empty hint index plus one planted spent coin — is covered explicitly and asserts
`Live`.

---

## 15. FFI — dig-runtime C-ABI (in-process host)

`dig-runtime` is a Cargo `cdylib` (`dig_runtime`, e.g. `dig_runtime.dll` shipped beside the browser
executable) exposing three C-ABI surfaces the DIG Browser links directly IN-PROCESS — no loopback
server, no socket, no `dig-node` sidecar:

- the **built-in wallet** (`dig_wallet_rpc`, §16) — the browser's reason to load the DLL;
- the **read-crypto** (`dig_read_verify_decrypt`, §15.1) — the digstore `.dig` verify+decrypt, the SAME
  `digstore-core` Rust the webpage `dig-client-wasm` wraps (ONE impl, two bindings: native FFI for the
  native browser, wasm for webpages — the browser NEVER uses wasm);
- the **full node RPC** (`dig_rpc`) — the SAME `dig_node_core::handle_rpc` dispatch the OS-service
  binary runs, retained for consumers that want an in-process node.

The runtime has TWO start modes, fixed by whichever `dig_runtime_start*` runs FIRST (idempotent
`OnceLock`):

- **wallet-only** (`dig_runtime_start_wallet`) — brings up the wallet host (§16) + tokio runtime with
  NO node engine (no P2P, no cache, no `dig_rpc` dispatch). This is the DIG Browser's mode: it links the
  wallet + read-crypto FFI and resolves `chia://`/`dig://` content from an EXTERNAL dig-node over RPC
  (the §5.3 ladder), running no in-process node.
- **full** (`dig_runtime_start`, or lazily on the first `dig_rpc`/`dig_wallet_rpc`) — builds the node
  engine + wallet host, for non-browser consumers that want an in-process node.

The C-ABI exports (all `#[no_mangle] extern "C"`, and panic-safe — a panic is caught and never crosses
the FFI boundary):

| Export | Signature | Behavior |
|---|---|---|
| `dig_runtime_start` | `void dig_runtime_start(void)` | Initialize the runtime FULLY: build the node engine + tokio runtime, load the §21.9 identity, prepare the cache, and start the wallet host. Idempotent; the FIRST `dig_runtime_start*` call fixes the mode. |
| `dig_runtime_start_wallet` | `void dig_runtime_start_wallet(void)` | Initialize the runtime WALLET-ONLY: bring up the wallet host + tokio runtime with NO node engine (no P2P/cache/`dig_rpc`). What the DIG Browser calls at startup. Idempotent; the FIRST `dig_runtime_start*` call fixes the mode. |
| `dig_rpc` | `char* dig_rpc(const char* request_json)` | Execute ONE DIG JSON-RPC request in-process and return the JSON-RPC response text. In WALLET-ONLY mode there is no node engine, so it returns a well-formed JSON-RPC error (`code -32000`, "node engine not available: dig-runtime started wallet-only") rather than spinning one up. Returns NULL only on a null/invalid input pointer or allocation failure. |
| `dig_wallet_rpc` | `char* dig_wallet_rpc(const char* origin, const char* request_json)` | Execute ONE wallet request (§16) for the calling page's web origin and return a JSON ENVELOPE `{"status": <u16>, "body": <raw JSON>}`, where `status` is the HTTP-equivalent status (200 ok / 202 pending / 403 not-approved / 4xx–5xx error) and `body` is the dispatch's JSON body embedded as RAW JSON (never a double-encoded string). Present in BOTH start modes. A null pointer or invalid UTF-8 in either argument yields a well-formed error envelope, never undefined behavior. |
| `dig_free` | `void dig_free(char* ptr)` | Free a string previously returned by `dig_rpc`/`dig_wallet_rpc`. NULL is ignored. |

- **String ownership.** `request_json` and `origin` are NUL-terminated UTF-8 strings OWNED BY THE
  CALLER for the duration of the call. Each non-NULL return value is a newly-allocated NUL-terminated
  UTF-8 string OWNED BY THE LIBRARY; the caller MUST return it to `dig_free` EXACTLY ONCE. Passing any
  other pointer to `dig_free`, or freeing twice, is undefined behavior.
- **Threading.** `dig_rpc` and `dig_wallet_rpc` BLOCK until the request completes on the shared runtime,
  so callers MUST invoke them from a thread allowed to block (e.g. a `base::MayBlock` task), NEVER the
  browser UI/IO thread. Concurrent calls are safe.
- **Shared state.** `dig_wallet_rpc` runs the SAME `dig_wallet::wallet_dispatch` the loopback
  `/api/wc/request` handler runs, against the SAME process-global wallet state — so the per-origin
  approval gate, the unlocked session, and the signer source are shared between the FFI path and the
  loopback wallet UI. The `origin` argument is supplied first-hand by the browser and is therefore
  UNSPOOFABLE (unlike a header a page could forge); the approval gate (§16) keys on it.

### 15.1. Read-crypto FFI — dig_read_verify_decrypt

The browser is NATIVE, so it verifies + decrypts served `.dig` content by calling the `digstore-core`
read-crypto Rust DIRECTLY over this C-ABI — NOT wasm (wasm is ONLY for webpages: hub / extension / SDK).
It is the SAME `digstore-core` crypto the webpage `dig-client-wasm` wraps as `decryptResource`, so a
native browser read and a webpage read derive the IDENTICAL key and enforce the IDENTICAL proof — ONE
Rust impl, two bindings. This call needs NO runtime and NO node engine: it is pure crypto over bytes the
caller already fetched from an external node (§5.3), so it works whether or not a `dig_runtime_start*`
has run.

| Export | Signature | Behavior |
|---|---|---|
| `dig_read_verify_decrypt` | `int32_t dig_read_verify_decrypt(const char* store_id_hex, const char* resource_key, const uint8_t* ciphertext, size_t ciphertext_len, const char* proof_b64, const char* trusted_root_hex, const char* salt_hex, const uint32_t* chunk_lens, size_t chunk_lens_len, uint8_t** out_ptr, size_t* out_len)` | Verify the served `ciphertext`'s Merkle inclusion against the chain-anchored `trusted_root_hex`, THEN AES-256-GCM-SIV-decrypt it — fail-closed (verify gates decrypt). On success returns `DIG_READ_OK` and writes a heap plaintext buffer to `*out_ptr`/`*out_len`; on ANY failure returns a `DIG_READ_*` code and leaves `*out_ptr`/`*out_len` null/0 (nothing to free). |
| `dig_bytes_free` | `void dig_bytes_free(uint8_t* ptr, size_t len)` | Free a plaintext buffer returned by `dig_read_verify_decrypt`. The `(ptr, len)` pair MUST be exactly one success's output. NULL is ignored. |

- **Inputs.** `store_id_hex` and `trusted_root_hex` are 64-hex (required). `resource_key` is the
  resource path (required; EMPTY resolves to the §8.5 default view `index.html`). `ciphertext` is the
  plain concatenation of the per-chunk ciphertexts (`ciphertext_len == 0` allowed with a null pointer).
  `proof_b64` is the base64 `X-Dig-Inclusion-Proof` header wire form (the Chia streamable `MerkleProof`
  codec). `salt_hex` is the 64-hex private-store secret salt, or NULL/empty for a PUBLIC store.
  `chunk_lens` are the per-chunk CIPHERTEXT byte lengths in order (NULL/0 ⇒ a single chunk) and MUST sum
  to `ciphertext_len`.
- **Status codes.** `DIG_READ_OK = 0`; `DIG_READ_BAD_INPUT = 1` (malformed argument — bad hex/base64,
  or `chunk_lens` not summing to `ciphertext_len`); `DIG_READ_VERIFY_FAILED = 2` (the served bytes'
  proof does NOT chain to the chain-anchored root — a tampered chunk or a decoy/wrong-store response);
  `DIG_READ_DECRYPT_FAILED = 3` (AES-256-GCM-SIV tag failure — a wrong key/salt or tampered ciphertext);
  `DIG_READ_INTERNAL = 4` (a caught panic or allocation failure). Every failure is fail-closed.
- **Buffer ownership.** The `out_ptr` buffer is OWNED BY THE LIBRARY; the caller MUST return it to
  `dig_bytes_free` EXACTLY ONCE with the matching `out_len`. This is a DISTINCT allocator discipline from
  the `dig_free` C-string path — never cross the two (a `dig_read_verify_decrypt` buffer to `dig_free`,
  or a `dig_rpc` string to `dig_bytes_free`, is undefined behavior).

---

## 16. Built-in wallet host — dig-wallet

`dig-wallet` is the DIG Browser's built-in Chia wallet host: a loopback `axum` server bound
`127.0.0.1:<DIG_WALLET_PORT>` (default `9777`) serving the wallet UI and a dapp-facing JSON-RPC
surface, with native BLS signing. In the native browser it ALSO runs in-process via the §15 FFI
(`dig_wallet_rpc`), sharing one process-global wallet state with the loopback UI.

### 16.1. Method surface + dispatch

The advertised dapp JSON-RPC method catalogue is the crate's `WC_METHOD_CATALOGUE` — the single source
of truth (a drift test enforces that every advertised method has a real dispatch arm). Dispatch is a
`match` on the method-name string in `wallet_dispatch` → `wc_dispatch`, reached identically from the
loopback `/api/wc/request` handler and the §15 FFI. The surface groups as:

- **CHIP-0002 handshake/introspection** — `chip0002_chainId`, `chip0002_connect`, `chip0002_getMethods`
  (introspection returns the full catalogue).
- **CHIP-0002 keys + signing** — `chip0002_getPublicKeys`, `chip0002_signMessage`,
  `chip0002_signCoinSpends`, `chip0002_getAssetBalance`, `chip0002_getAssetCoins`.
- **`chia_*` wallet surface** — address + sign (`chia_getAddress`, `chia_signMessageByAddress`),
  payments (`chia_send`), history (`chia_getTransactions`), NFTs (`chia_getNfts`, `chia_transferNft`,
  `chia_mintNft`, `chia_bulkMintNfts`), DIDs (`chia_getDids`, `chia_createDidWallet`, `chia_transferDid`),
  and offers (`chia_getOfferSummary`, `chia_createOffer`, `chia_takeOffer`, `chia_cancelOffer`).
- **CHIP-0035 store lifecycle** — `chia_mintStore`, `chia_advanceStore`, `chia_meltStore`,
  `chia_setStoreDelegation`, `chia_setStoreOwnership`.
- **`dig_*` advanced coin types** — clawback (`dig_clawbackSend`/`Claim`/`Recover`), options
  (`dig_optionCreate`), streams (`dig_streamCreate`/`Claim`/`Clawback`), vaults (`dig_vaultCreate`), and
  verifiable credentials (`dig_vcVerify`).

A method that is not in the advertised catalogue (including deliberately-unsupported advanced methods)
MUST return `501 Not Implemented` with an explanatory message — an HONEST "unsupported in this build",
never a fabricated result.

### 16.2. Authorization — two independent gates

A spend reaches mainnet ONLY when BOTH gates pass:

1. **Per-origin consent gate.** The caller's web origin — the unspoofable HTTP `Origin` header on the
   loopback path, or the first-hand origin over FFI (§15) — is checked: public methods
   (`chip0002_chainId`/`getMethods`) need no approval; `chip0002_connect` from an unapproved origin is
   PARKED as pending (`202`); any key/sign method from an unapproved origin is FORBIDDEN (`403`); an
   approved origin proceeds. Approvals persist to `connections.json`.
2. **Broadcast gate (dry-run default).** A signed spend bundle is pushed to mainnet ONLY when
   broadcasting is explicitly enabled by the process env `DIG_WALLET_ALLOW_BROADCAST=1`. The DEFAULT is
   a DRY RUN: the bundle is built and BLS-signed but NOT pushed (response status `"signed"`), spending
   no real funds. A dapp CANNOT force a broadcast — the request-level `broadcast` flag exists only on
   the local `/api/send` REST path; dapp-originated spends pass broadcast-intent internally and are
   gated SOLELY by the server-side env. With broadcasting disabled, a broadcast-intent local send is
   refused (`403` "broadcasting is disabled — set `DIG_WALLET_ALLOW_BROADCAST=1` to spend real mainnet
   funds") and a dapp spend degrades to a dry run.

### 16.3. Secret custody

Seed-reveal / private-key-export class methods (`export`, `exportMnemonic`, `chip0002_export`,
`chia_export`, `getMnemonic`, `getSecretKeys`, `getPrivateKey(s)`, `revealSeed`) are HARD-BLOCKED from
the dapp dispatch surface — they are absent from dispatch (fall to `501`) and are refused before any
forward to a delegated signer. The mnemonic is revealed ONLY through the local, password-gated,
self-origin `/api/export` UI route, never over the dapp/WC surface.

---

## 17. Outgoing-bandwidth throttle and redirect-on-saturation

The standalone node's P2P content engine (`crate::download`, #164/#165) redirects a caller to another
holder when this node does NOT hold the requested content ("redirect-on-miss," `-32008`
`CONTENT_REDIRECT`, §10). This section extends that mechanism from "not held" to "held, but serving it
now would exceed this node's configured outgoing-bandwidth budget."

17.1. **Configuration.** `DIG_NODE_MAX_OUTGOING_BYTES_PER_SEC` (§3.2) sets a bytes/second cap on the
node's outgoing serve traffic. `0`, unset, or unparsable is UNLIMITED — the throttle is opt-in; an
unconfigured node's serve path is byte-identical to before this feature. The cap is resolved once at
node construction (`bandwidth::OutgoingThrottle::from_env`).

17.2. **Accounting.** The throttle tracks bytes served in a fixed 1-second window (`served_bytes`
against `window_start`), rolling to a fresh window once a full second has elapsed. Before writing a
chunk the serve path asks whether `served_bytes + this_chunk` would exceed the cap
(`OutgoingThrottle::would_exceed`) — a peek, not a reservation; on any serve (including the graceful
fallback, §17.4) it then records the bytes actually sent (`OutgoingThrottle::record_served`).

17.3. **Serve-path integration.** The check runs on every surface that returns resource bytes this
node already holds locally, immediately before the bytes would be written:

- `dig.getContent`'s LOCAL-FIRST serve (a cold cache hit and the post-§21-sync hit alike);
- `dig.fetchRange`'s local frame serve;
- the mTLS peer range-stream (`stream_range`) — the busiest outgoing surface, since multi-source
  downloaders fan byte-ranges across it.

When the check trips, the node resolves alternate holders via the DHT
(`download::NodeContent::find_providers`, self excluded) and, if any exist, answers with the SAME
`CONTENT_REDIRECT` error object shape redirect-on-miss uses
(`download::redirect_error_object` — `error.data.redirect.{content,providers,redirect_depth,max_redirects}`)
instead of writing the over-budget bytes. `providers[].addresses` follow the candidate ordering the DHT
returns, which is IPv6-first (§5.2 — dig-dht orders reflexive/candidate addresses IPv6-first; the
throttle does not reorder them).

17.4. **Hop budget (shared with redirect-on-miss).** A bandwidth-redirect consumes the SAME
`redirect_depth`/`REDIRECT_HOP_CAP` budget as a miss-redirect (§10's `-32008` entry): the caller echoes
the depth a redirect served it, and a request already at the hop cap is served locally rather than
redirected again, so saturated nodes can never bounce a caller in a loop regardless of which mechanism
(miss or bandwidth) issued the prior redirects.

17.5. **Graceful fallback — never fail closed.** The node serves the request normally (recording the
bytes against the throttle) whenever a redirect is not possible: under budget; no P2P content engine is
attached (the in-process FFI/DIG-Browser path never redirects, having no peer network to redirect to);
the hop budget is exhausted; or the DHT knows of no alternate holder. The throttle changes WHERE a
request is served from when it can, never WHETHER it is served — an over-budget request with no known
alternate still goes out rather than being dropped or erroring.

## 18. Sage-parity wallet RPC — direct-peer sync, local wallet DB, fallback tier

This section specifies the dig-node's **Sage-parity wallet RPC**: a byte-compatible replica of the
[Sage](https://github.com/xch-dev/sage) wallet RPC surface (`endpoints.json`, **pinned v0.12.11**,
commit `a84d7dfc`) backed by a direct-peer chain sync into a local wallet database, with a
`chia-query`/coinset fallback tier. A Sage RPC client can point at the dig-node interchangeably with
Sage. It is a new surface, additive to and DISTINCT from the built-in wallet host (§16), the read/control
JSON-RPC (§5/§7), and the CHIP-0002 `window.chia` dapp responder. It lives in the `dig-wallet` crate
(`crate::sage`). #215 shipped the READ + sync foundation; #216 added NFT/DID/CAT reconstruction (§18.11)
and the send/spend method group (§18.9); #218 added the offer suite + DID/NFT mint & transfer (§18.9a);
#205 PR4 added the `SyncEvent` stream (§18.14), the option-contract suite (§18.15), record-update
actions + the theme store (§18.16), network/peer settings (§18.17), the dig-keystore seed migration
(§18.18), and the generated-OpenAPI conformance vector (§18.19) — completing the served method surface
to 75 of the 100 Sage `endpoints.json` methods (the remaining 25 are secret-touching, gated per §18.10,
or Sage-desktop-only per design Part F MAY/N-A, e.g. `delete_database`/`perform_database_maintenance`).

18.1. **Transport — one method surface, two transports.** Byte-compatibility with Sage is required at
the application layer (method names + JSON request/response shapes); the transport is adapted per client
class. Both listeners dispatch the SAME handler set (`WalletBackend::dispatch`), so their bodies are
byte-identical by construction:

- **mTLS `9257`** (default; configurable). `POST /{method}` over TLS with Sage's shared-self-signed-cert
  MUTUAL-TLS model: the server accepts a client cert iff its DER is byte-identical to the server's own
  cert (a local-possession auth model — whoever can read the cert+key is authorized). Loopback only.
- **Plain-HTTP + CORS** (browser mirror). A browser/MV3 extension cannot present a client cert, so the
  identical surface is served over the loopback plain-HTTP transport with permissive CORS. Loopback only.

On the shipped `dig-node` binary this surface IS served (#368): the service bring-up assembles ONE live
`WalletBackend` (`sage::service::WalletService` — the wallet DB + a graceful fallback tier + a shared
`EventBus` + the node custody) and (a) integrates the browser mirror onto the SAME loopback service router
as `POST /{method}` on the default port `9778` — the exact base the extension's `node-wallet` client
targets — with the wallet authz gate (§7.12) applied, and (b) brings up the mTLS `9257` sibling listener
(best-effort, non-fatal) for node-class/Sage-drop-in parity. The bidirectional `/ws` transport (§4.8) also
dispatches to this same backend. Wallet methods are NEVER relayed to the upstream gateway.

18.2. **Request/response model.** Every endpoint is `POST /{endpoint}` where `{endpoint}` is the exact
snake_case method name. There is NO JSON-RPC envelope, NO batching — the path IS the method. Request body
= the method's request struct as a single JSON object (an empty body is treated as `{}`). Success →
`200 OK` with the response struct as JSON (`content-type: application/json`). Error → a non-200 status
with the error message as a **plain-text** body (NOT a JSON error object), reproducing Sage's model.

18.3. **Wire types (byte-parity invariants).** The request/response/record types match `sage-api`
byte-for-byte:

- **`Amount`** — an untagged enum serializing as a JSON **number** when `<= 9_007_199_254_740_991`
  (`MAX_JS_SAFE_INTEGER`), else a JSON **string**; deserializes from either. This exact threshold MUST be
  reproduced (JS clients depend on it). Amounts are in the asset's smallest unit (mojos for XCH).
- **Casing** — struct fields are snake_case (Rust idents already are; no `rename_all` on structs); enums
  carry `#[serde(rename_all = "snake_case")]`.
- **Optional fields** — `Option<T>` serializes as `null` when `None` (Sage does NOT omit them); field
  order equals declaration order.

18.4. **Error model.** `ErrorKind` → HTTP status: `api` → `400`, `not_found` → `404`, `unauthorized` →
`401`, `wallet`/`internal` → `500`. An unknown/unsupported method is `404`; a malformed request body is
`400`.

18.5. **Local wallet database (SQLite).** The sync loop persists the wallet's chain state to a local
SQLite database (via `sqlx`), mirroring `sage-wallet`'s relational store: coins/CATs/derivations (and
NFT/DID/collection tables, plus an `offers` table for imported/built offers, #218) keyed by the wallet's
hardened AND unhardened HD puzzle hashes + CAT hints, plus the synced peak height. SQLite (NOT RocksDB): the workload is relational, multi-index, query-rich
and small (one wallet). Indexes on `puzzle_hash`, `asset_id`, a PARTIAL index on unspent
(`spent_height IS NULL`), and `created_height`; WAL enabled. Amounts are stored as decimal TEXT (full
`u64`/`u128` range, no `i64` overflow). This DB is the source of truth for a SYNCED wallet's data.

18.6. **Direct-peer sync (primary path).** Wallet chain data is obtained by connecting directly to Chia
full-node peers over the light-wallet protocol on `chia-wallet-sdk 0.30` `Peer` (`NodeType::Wallet`,
protocol `0.0.37`, the four DNS introducers, multi-peer, IPv6-first per §5.2), exactly as Sage does — NOT
via coinset for the wallet-data path. The node subscribes the wallet's puzzle hashes (BOTH hardened and
unhardened + CAT hints) with `request_puzzle_state(subscribe = true)`, applies the returned coin states,
then consumes `coin_state_update` pushes into the DB. A reorg (a `coin_state_update` whose `fork_height`
is below the current peak) rolls the DB back above the fork — coins created above it are deleted, coins
spent above it become unspent again — then applies the update's coin states and advances the peak.

18.7. **Fallback tier + sync-state-gated routing.** `chia-query` (coinset.org + non-subscribing peer
point-reads) is reused AS-IS as a fallback tier — never the primary. The B.3 subscription loop is NOT
added to `chia-query`. Every wallet-data read selects its source:

| Condition                                            | Source           |
|------------------------------------------------------|------------------|
| Wallet's own data, DB synced to peak                 | Local wallet DB  |
| Wallet's own data, DB still syncing                  | Fallback tier    |
| Chain data not scoped to this wallet, not in the DB  | Fallback tier    |

So a caller never blocks on an unsynced replica. `get_sync_status` reports the gating sync state.

18.7a. **Identity-scoped reads + honest sync state (#407).** The dig-node answers wallet-data reads for
the CLIENT's connected self-custody wallet, scoped by that wallet's PUBLIC identity — NEVER the node's
own coins, and NEVER holding the client's private key (the node receives only public puzzle
hashes/addresses).

- **Session identity via `login`.** `login` accepts, in addition to `fingerprint`, an OPTIONAL
  `puzzle_hashes` (hex) and/or `addresses` (bech32m, decoded to puzzle hashes). When either is present
  the node records a per-session identity (the set of PUBLIC puzzle hashes) and scopes subsequent reads
  to it; `logout` clears it. These fields are additive — a Sage client sending only `fingerprint`
  deserializes unchanged and seeds no identity. The node MUST subscribe the declared puzzle hashes for
  chain-watch so the local DB converges to the client's coins.
- **Read scoping.** `get_sync_status` (XCH balance), `get_cats`/`get_token`/`get_all_cats` (CAT
  balances), and `get_coins`/`get_spendable_coin_count` filter to the session identity's coins: XCH
  coins by `puzzle_hash ∈ identity`, CAT coins by `hint ∈ identity` (a CAT sits at the outer CAT puzzle
  hash and is hinted to the owner p2). Absent a session identity, reads fall back to the node's own
  configured puzzle hashes (legacy); when BOTH are empty the node is tracking no wallet and scoped reads
  return nothing.
- **Honest sync state (never a silent synced-zero).** `get_sync_status` reports `synced_coins`/
  `total_coins` TRUTHFULLY. A client derives "synced" as `synced_coins >= total_coins` (treating
  `total_coins == 0` as synced). The node reports synced ONLY when it is tracking the identity AND the
  DB has completed initial catch-up (`is_synced()`); otherwise it reports `synced_coins < total_coins`
  (`0` of at-least-`1`), so an empty or not-yet-caught-up DB, and a wallet the node is not tracking,
  read as NOT synced and never as a synced-zero. `selectable_balance` is the identity-scoped unspent XCH
  balance (0 when not tracking).

18.7b. **Tier disclosure — the reported state describes the ANSWER, not the node (#2233).** Every
wallet read that chooses a source per the §18.7 routing table MUST disclose the tier that actually
answered, and MUST derive every freshness field from that tier.

- **`source` is additive and REQUIRED on the result.** `control.wallet.balance` returns
  `source: "db" | "fallback"` alongside its figures. `"db"` means the node's own chain replica
  produced the figure; `"fallback"` means a third-party coinset HTTP oracle did, which additionally
  means the queried address WAS DISCLOSED off-node — a fact a caller on a metered or private
  connection has a legitimate interest in. The field is additive per §5.1: a consumer that does not
  read it parses unchanged.
- **`synced` and `peak_height` are properties of the tier.** A `"db"` answer reports `synced: true`
  and the replica's own peak. A `"fallback"` answer reports `synced: false` and `peak_height: null`,
  **regardless of the local DB's state** — the DB neither produced that figure nor bounds its
  freshness, so its flag and peak say nothing about it. Implementations MUST NOT read those two
  fields outside the tier decision.
- **Rationale — this is the falsifiability instrument for §18.6.** A success criterion phrased as a
  flag value rather than as the path taken is satisfiable with the goal unmet: once the §18.6 sync
  loop sets `initial_sync_complete`, a read still served by the oracle would report itself as a
  synced local read. Acceptance for any sync work MUST name the `source` tier, never the `synced`
  flag alone.
- **Operator visibility.** The routing branch emits a `tracing` event carrying `tier=db|fallback`,
  so `dig-node.jsonl` records the same tier the wire reports. Diagnostics go through `tracing`,
  never stderr (a Windows service discards it).

  **The FALLBACK tier MUST be logged at a level a stock node actually emits.** `dig-logging`'s
  baked-in default is `info` and a default install sets none of the overrides, so a `debug!` here is
  invisible in the field — which would make the sentence above false on every stock node, and would
  let an acceptance run reading `dig-node.jsonl` mistake silence for "no fallback occurred". Fallback
  is therefore `info`; it is the exceptional path and it means the read was disclosed to a
  third-party oracle. The DB tier stays `debug`: once the §18.6 sync loop lands it is the ordinary
  path, and logging every local read at `info` would turn an OPEN unauthenticated loopback endpoint
  into a log-volume lever.

18.8. **Method surface — reads (served).** `login`, `logout`, `get_version`,
`get_sync_status`, `check_address`, `get_derivations`, `get_are_coins_spendable`,
`get_spendable_coin_count`, `get_coins`, `get_coins_by_ids`, `get_cats`, `get_all_cats`, `get_token`,
`get_dids`, `get_nfts`, `get_nft`, `get_nft_data`, `get_nft_collections`, `get_nft_collection`,
`get_transactions`, `get_transaction`, `get_pending_transactions`, `is_asset_owned`, `get_key`,
`get_keys`. Coins and CAT balances/records are fully synced and served; transactions are derived from the
coin table grouped by created/spent height; NFT/DID/collection reads return the rows the sync
reconstruction populates (§18.11). `get_pending_transactions` is empty (no pending-tracking store yet).

18.9. **Method surface — send/spend group (served, #216).** `send_xch`, `bulk_send_xch`, `send_cat`,
`bulk_send_cat`, `combine`, `split`, `multi_send`, `sign_coin_spends`, `view_coin_spends`,
`submit_transaction`. Spends are built with the canonical `chia-wallet-sdk` driver constructors
(`StandardLayer`/`SpendContext`/`Cat::spend_all`) — never hand-rolled CLVM — over coins selected from the
wallet DB; the built bundle is validated by `dig-clvm` (`validate_spend_bundle`) BEFORE any broadcast
(fail-closed). Because `dig-clvm` is the DIG **L2** consensus engine, its aggregate-signature check uses
the DIG-L2 domain (not the Chia **L1** domain a wallet spend is signed for), so pre-broadcast validation
runs with `DONT_VALIDATE_SIGNATURE` (CLVM execution + conservation + structure) and the **L1 broadcast
target** (the Chia peer's `send_transaction`) verifies the signature against L1 constants. `auto_submit`
broadcasts only when a broadcaster is attached; there is NEVER an auto-broadcast in tests/CI (a real
mainnet broadcast is a separate, explicitly-gated live pass). Spend methods require the node-custodied
signer; a locked wallet returns an error. `multi_send` covers XCH payments (CAT payments via `send_cat`).

18.9a. **Method surface — offer suite + DID/NFT mint & transfer (served, #218).** `make_offer`,
`take_offer`, `view_offer`, `combine_offers`, `get_offers`, `get_offer`, `cancel_offer`, `create_did`,
`bulk_mint_nfts`, `transfer_nfts`, `transfer_dids`. Offers are built with the canonical `chia-wallet-sdk`
action system (`Spends`/`Action`/`RequestedPayments`/`Offer`): `make_offer` spends the offered coins into
the settlement puzzle and asserts the requested notarized payments (nonce = tree-hash of the sorted
offered coin ids), signs the maker side, and encodes the `offer1…` string; `take_offer` decodes the
offer, funds the requested payments from the wallet, signs the taker side, and returns the COMBINED
(maker + taker) signed bundle; `view_offer` decodes to the two-sided `OfferSummary` without settling;
`combine_offers` aggregates several offers' spend bundles into one; `cancel_offer` reclaims the offer's
still-cancellable offered coins back to the wallet. DID/NFT mint & transfer use the driver primitives
(`Launcher::create_simple_did`, one `IntermediateLauncher` per NFT + `Nft`/`Did` `TransferNft`
attribution, `Nft::transfer`/`Did::transfer`) — never hand-rolled CLVM. `bulk_mint_nfts` launches every
NFT off the minting DID coin and spends the DID once to acknowledge all attributions atomically, funding
the per-NFT launcher mojos + the fee from an XCH funding coin (Chia enforces conservation over the whole
bundle). Every built bundle is validated by `dig-clvm` (`DONT_VALIDATE_SIGNATURE`, as §18.9) before any
broadcast; `auto_submit` broadcasts only when a broadcaster is attached (never in CI). `make_offer`
persists the built offer to a local `offers` table when `auto_import` is set; `get_offers`/`get_offer`
read it back, `cancel_offer` marks it cancelled. Sage's per-endpoint `auto_submit` defaults are matched
(offers/mint/transfer default `false`; `make_offer.auto_import` defaults `true`).

18.10. **Signing + custody (C.6).** The node signs with its custodied seed only for node-class /
DIG-Browser callers (a `WalletSigner` over the wallet's synthetic p2 keys). Secret-touching endpoints
(`get_secret_key`/`generate_mnemonic`/`import_key`/exportMnemonic/revealSeed) stay 501'd + loopback+token
gated, NEVER reachable from a dapp/non-loopback origin. The MV3 extension self-custodies and does NOT use
the node's sign/spend path. (SUPERSEDED for the PAIRED-extension thin-client path by §18.20/§18.21: there
the node custodies the key and signs + broadcasts on behalf of a paired caller, gated per §7.12.)

18.11. **NFT/DID/CAT reconstruction.** A raw `CoinState` does not reveal a coin's asset kind — that lives
in the coin's puzzle, revealed only when its parent is spent. Reconstruction uncurries the parent spend
(via the `Nft`/`Did`/`Cat` driver parsers) to populate the `nfts`/`dids`/`nft_collections` tables and to
attribute CAT coins to their asset id (TAIL hash) in the `coins` table (so `get_cats`/`get_token` become
complete). Parent spends are fetched through a `LineageSource` (out-of-DB lineage reads, B.5). Reads only.
The sync loop runs this attribution as a post-apply step (`sync::CatAttributor`, threaded into
`run_update_loop`): every `coin_state_update` is followed by an attribution pass that uncurries the
newly-synced candidate coins, so a synced CAT coin — stored initially with `asset_id: None` — gains its
TAIL and surfaces in `get_cats` (this is how `$DIG` resolves from the node).

18.12. **Live broadcaster bring-up — real mainnet $DIG spends behind a config gate (#428).** The
node-custodied wallet BUILDS + SIGNS + VALIDATES spends (§18.9/§18.21) and the tip engine (§18.23)
reserves + caps them, but on the shipped node NO broadcaster is attached, so no `$DIG` moves. This
unit wires the LIVE path, gated so it is OFF by default (money-safe) and ON only by explicit opt-in.

- **Config gate (`enable_live_broadcast`, default OFF).** Sourced from
  `DIG_WALLET_ENABLE_LIVE_BROADCAST` (`1`/`true`/`yes`/`on` ⇒ enabled; **anything else, including
  unset, ⇒ OFF** — the OPPOSITE default to the dig.local toggle: money movement is never on by
  accident). OFF reproduces today's behaviour exactly (no broadcaster attached; a tip / sign-on-
  behalf / send cleanly reports unavailable and nothing is spent). ON assembles the live wiring.
- **Live wiring (`WalletService::build_with`).** When enabled, the bring-up builds ONE shared
  `chia_query::ChiaQuery` client (mainnet; decentralized peers + coinset.org fallback, §5.2) and
  attaches, all over that one client: a real `spend::ChiaQueryBroadcaster` (`chia_query::push_tx`),
  a `spend::ChiaQueryConfirmer` (on-chain confirmation poll), a `fallback::ChiaQueryLineage`
  (CAT/singleton parent-spend reads via `get_puzzle_and_solution`), and a `fallback::CoinsetFallback`
  read tier. A client-construction failure (offline / no peer reachable) is NON-FATAL and DISABLES
  live broadcast (logged) — a half-built client can never send.
- **The chain source MUST require nothing from the filesystem.** The peer TLS identity is generated
  in memory (`chia_query::TlsIdentity::Generated`, the `ChiaQueryConfig::default()`), never loaded
  from `~/.chia`. Chia full nodes accept any well-formed client certificate, so a file-backed
  identity buys nothing and costs correctness: the node runs as an OS service, whose account has no
  populated `~/.chia` (on Windows, `…\config\systemprofile`), so a file-backed identity made client
  construction fail and every `control.wallet.balance` answer `WALLET_NO_CHAIN_SOURCE` (§10). The
  coinset tier MUST also stay enabled, which keeps peers OPTIONAL: an empty peer pool degrades to
  keyless HTTP reads rather than failing construction outright. Requires `chia-query` ≥ 0.6.
- **A construction failure MUST be reported through the process log sink** (`tracing` ⇒
  `dig-logging`), never `stderr`: a service has no stderr attached, and this is the only account of
  why subsequent balance reads answer `WALLET_NO_CHAIN_SOURCE`.
- **Broadcaster split (no double-confirm).** The GENERAL wallet surface (send/offer/mint,
  `finalize_spend`/`submit_transaction`/`sign_coin_spends`) gets a `spend::ConfirmingBroadcaster`
  wrapping the raw broadcaster: it pushes to the mempool (the money boundary — a push error
  propagates) then BEST-EFFORT confirms on-chain (a miss/timeout is logged, NOT an error — the money
  already moved; the Sage responses carry no confirmation field). The TIP path gets the RAW
  broadcaster PLUS the confirmer directly, because it surfaces confirmation ITSELF in its ledger
  (below) and must not double-confirm.
- **Confirmation semantics (poll for a created coin).** `Confirmer::confirm(created_coin_ids)` polls
  `chia_query::wait_for_confirmation` for a created OUTPUT coin (a created coin with a non-zero
  confirmed height proves the spend was included in a block). `Ok(true)` = confirmed on-chain;
  `Ok(false)` = accepted into the mempool but not confirmed within the window (money moved —
  confirmation is asynchronous, NOT a failure). A confirmation READ error folds into `Ok(false)`:
  a failed read after a successful broadcast is never reported as a spend failure.
- **Tip ledger surfacing (confirm-before-marking-confirmed).** `WalletBackend::build_and_broadcast_dig_tip`
  returns `TipSpendOutcome::Broadcast { txid, confirmed }`. The engine reconcile (§18.23) maps
  `confirmed:true` ⇒ ledger status `Confirmed`, `confirmed:false` ⇒ `Pending` (txid recorded —
  broadcast, awaiting on-chain inclusion). Either way the persisted reservation blocks a same-day
  retry and its amount counts toward the caps, so a pending (unconfirmed) tip can NEVER enable a
  double-spend. An AMBIGUOUS broadcast error is still `Failed` (never retried that day, §18.23).
- **Coin selection over live-synced state (the wallet coin-DB sync contract).**
  `WalletBackend::refresh_tracked_coins` is a best-effort point-read sync that FEEDS coin selection:
  it reads the wallet's OWN coins from the fallback tier for every tracked p2 puzzle hash — XCH coins
  sitting AT the puzzle hash (`coin_records_by_puzzle_hashes`) AND CAT coins HINTED to it
  (`coin_records_by_hints`, since a CAT is hinted to the owner p2) — upserts them into the local coin
  DB (`unspent_coins`/`select_cats` read this), attributes each CAT to its TAIL by uncurrying the
  parent spend via the lineage source (so a `$DIG` coin, stored initially with `asset_id: None`, gains
  its asset id and becomes selectable), and marks the DB synced. It runs on the SPEND path: the live
  tip spender (and any node-custodied send) invokes it BEFORE selecting, so the spend builds over
  current chain state. Idempotent + non-destructive (upsert-only; a re-sync marks a now-spent coin
  spent so it drops out of selection). A sync failure is NOT a spend failure — selection then reports
  `NotExecutable`/insufficient-balance (retryable, never a false spend). A no-op under the graceful
  `EmptyFallback`.
- **Canonical query hex.** All coin-record queries into `chia_query` (the fallback tier: peers +
  coinset.org) MUST pass hashes/hints as lowercased **`0x`-prefixed** hex. The coinset RPC matches
  ONLY `0x`-prefixed hex (the peer tier tolerantly strips an optional `0x`); a bare-hex query silently
  reads back zero coins. `refresh_tracked_coins` builds tracked puzzle hashes with bare `hex::encode`,
  so the `CoinsetFallback` adapter normalizes them to the `0x` form at the query boundary (the DB and
  internal comparisons stay bare-hex). Omitting this normalization is the live "have 0 $DIG" failure
  (#430): the mock/peer paths accept bare hex, so it surfaces only when a bring-up falls through to
  coinset.
- **Live-funds e2e (env-gated, SKIPPED by default).** A documented, runnable end-to-end test
  (`crates/dig-node-service/tests/live_funds_tip_e2e.rs` + `runbooks/live-funds-tip-e2e.md`) drives a
  real mainnet `$DIG` tip to the DIG treasury (`digstore_chain::dig::treasury_inner_puzzle_hash()`).
  It is SKIPPED unless `DIG_LIVE_FUNDS_TEST=1` AND the funded test wallet is provided (via
  `/.test-credentials`, referenced by path — NEVER inlined). **CI never broadcasts to mainnet**: all
  automated tests use the `chia-sdk-test` simulator (real consensus incl. BLS) or the recording
  `MockBroadcaster`/`MockConfirmer`; the live path is exercised only by this explicit, capped,
  operator-run pass.

18.12a. **Deferred to follow-on units.** The off-chain NFT data-blob/CHIP-0015 metadata fetch
(`get_nft_data` returns on-chain fields; the metadata JSON surfaces when fetched), `exercise_options`
(§18.15 — a documented, non-silent follow-on), and real image-derived theme content (§18.16 — this
backend stores a placeholder). The point-read live sync above populates the DB for the spend path;
the richer live direct-peer SUBSCRIPTION sync loop (§18.6) — feeding the shared `EventBus` from real
chain `coin_state_update` pushes for continuous wallet-data reads — remains the follow-on integration
(until it is spawned, wallet-data reads outside a live spend use the fallback tier / point-read sync).

18.13. **Security.** Both listeners bind loopback only. The mTLS listener enforces the shared-cert mutual
TLS. Multi-peer sync is a correctness/censorship property (never collapse to one peer). Reads tolerate
unknown/forward-incompatible fields (additive, §5.1 spirit). Spend submission is validated via `dig-clvm`
before broadcast (fail-closed) and never auto-broadcasts without an attached broadcaster.

18.14. **`SyncEvent` stream (design A.9, #205 PR4).** An in-process [`crate::sage::events::EventBus`]
(a `tokio::sync::broadcast` channel) the direct-peer sync loop (§18.6) publishes lifecycle events to:
`start{ip}` (sync begins on a peer), `subscribed` (puzzle-hash subscription acknowledged),
`puzzle_batch_synced` (once per initial-catch-up batch applied), `coin_state` (a `coin_state_update`
applied), `stop` (the peer connection ended). Streamed over `GET /events` (Server-Sent Events) on BOTH
transports (the shared router, §18.1) — the `event:` field is the Sage `type` tag, `data:` is the
event's JSON. A best-effort push channel: publishing with zero subscribers is a no-op, and a lagging
subscriber (broadcast-channel overflow) simply misses the gap rather than erroring the stream —
`get_sync_status` polling remains the authoritative source of truth regardless of whether anything is
subscribed. `derivation`/`transaction_failed`/`cat_info`/`did_info`/`nft_data` are defined on the wire
(byte-parity with Sage's tagged union) but not yet published by any producer — reserved for the
respective follow-on work.

18.15. **Option-contract suite (design A.5, #205 PR4).** `get_options`/`get_option` (DB reads, paginated/
sorted/filtered like `get_nfts`), `mint_option`/`transfer_options` (real `chia-wallet-sdk`
`OptionLauncher`/`OptionContract` driver builders — never hand-rolled CLVM, §4.1) are served.
`mint_option` in this backend mints an **XCH-underlying** option only (the underlying lock coin holds
plain XCH); the strike may be XCH or a CAT (a pure enum tag with no extra coin-construction cost at mint
time — the exerciser funds it later). A CAT/NFT-underlying mint returns a clear `400` naming the
limitation, never a mis-built spend. `exercise_options` is accepted on the wire but returns a clear,
named `500` (`crate::sage::options::exercise_options_unimplemented`) — exercising requires tracking the
underlying-lock coin's OWN lineage (a derived, non-HD puzzle hash outside the wallet's ordinary
subscription set) plus the `MipsSpend`/merkle-proof machinery `OptionUnderlying::exercise_spend` needs; a
tracked follow-on, not a silent gap. The `OptionRecord` wire shape (`launcher_id`/`amount`/
`underlying_asset`/`strike_asset`/`name`/`created_timestamp` alongside the coin/visibility/expiration
fields) is verified field-name-identical against the pinned v0.12.11 generated OpenAPI (§18.19) — an
initial guess used `option_id` instead of the real `launcher_id`, caught and fixed by that vector.

18.16. **Record-update actions + the theme store (design A.5, #205 PR4).** `resync_cat` (clears a CAT's
cached display metadata, forcing a re-fetch — balance/coins untouched), `update_cat` (persists a
caller-supplied `TokenRecord`'s display metadata; requires `asset_id`), `update_did`/`update_option`/
`update_nft`/`update_nft_collection` (name/visibility, patching both the indexed DB column and the
stored wire-record JSON so subsequent reads reflect it immediately), `redownload_nft` (clears cached
off-chain metadata JSON, forcing a re-fetch), `increase_derivation_index` (raises a per-tree derivation-
index FLOOR so `get_sync_status`/`get_derivations` report at least the requested coverage — never
lowers an existing floor; requires `hardened` and/or `unhardened` be requested). The theme store
(`get_user_themes`/`get_user_theme`/`save_user_theme`/`delete_user_theme`, Sage-desktop-UI origin,
design Part F MAY/N-A) is DB-backed, keyed by NFT id. **Verified against the generated OpenAPI
(§18.19):** the real `save_user_theme` request carries ONLY `nft_id` — Sage derives the theme from the
NFT's own artwork (color extraction) rather than accepting caller-supplied content (an initial guess
added a `theme: String` field, caught and fixed). This backend has no image/color-extraction pipeline,
so `save_user_theme` persists a fixed placeholder (`crate::sage::themes::DERIVED_THEME_PLACEHOLDER`)
rather than a real derived theme — `get_user_theme(s)` still correctly reports "is this NFT themed",
just not a real color scheme; real derivation is a tracked follow-on.

18.17. **Network / peer / sync settings (design A.5, #205 PR4).** `get_peers`/`add_peer`/`remove_peer`
are DB-backed: `add_peer` persists a user-managed entry at the standard Chia full-node port (design
B.1, `8444`) surviving restarts (mirroring Sage); `remove_peer{ban:true}` keeps the row but excludes it
from `get_peers`; `peak_height` reports `0` until live per-peer telemetry is wired to the sync loop —
never fabricated. `set_discover_peers`/`set_target_peers`/`set_delta_sync`/`set_delta_sync_override`/
`set_change_address` persist to a `network_settings` row. `set_network`/`set_network_override` both set
the same stored network override (this backend tracks one active wallet key; a genuine per-fingerprint
override is a follow-on for multi-key support). `get_networks`/`get_network` report the two networks
this backend can sync against (design Part B): mainnet and testnet11. `NetworkKind` is a 3-variant enum
(`mainnet`/`testnet`/`unknown`) — verified against the generated OpenAPI (§18.19); an initial guess had
only 2 variants, caught and fixed. The real Sage `Network`/`NetworkList`/`get_network`/`get_networks`
response schemas are opaque (untyped `object`) in the generated OpenAPI, so this backend's `Network`
shape (`name`/`ticker`/`address_prefix`/`precision`/`default_port`) is a best-effort, not byte-verified,
representation — documented as such.

18.18. **dig-keystore seed migration (design C.2, #205 PR4).** The wallet's on-disk seed file
(`seed_path()`, §16) is now encrypted at rest via the `dig-keystore` crate's `opaque` container
(Argon2id + AES-256-GCM, versioned/magic-tagged/CRC-guarded — the SAME primitives the bespoke
`digstore_chain::seed` format used, now consolidated onto the ecosystem's canonical keystore crate,
Appendix B) for every NEW write (`crate::seed_store::encrypt_seed`). Reads accept EITHER format: the
on-disk magic (`DIGVK1`/`DIGLW1`/`DIGOP1` = a `dig-keystore` container; anything else = the legacy
layout) selects the decoder, so a seed file written before this migration keeps opening
(`crate::seed_store::decrypt_seed`) — proven by a golden-fixture test that encrypts a mnemonic with the
ACTUAL legacy `digstore_chain::seed::encrypt_seed` and asserts the new unified reader still recovers it.

18.19. **Generated-OpenAPI conformance vector (design A.10, #205 PR4).** `sage-cli` (a pure CLI/RPC
crate, no Tauri/desktop dependency) was built from the pinned `xch-dev/sage` `v0.12.11` tag and
`cargo run --bin sage rpc generate_openapi` run to produce the golden vector, committed as
`crates/dig-wallet/tests/vectors/sage-openapi-v0.12.11.json` (100 paths, matching the design's method
count) — no build step is needed to re-derive it; re-pinning to a newer Sage tag regenerates it the same
way. `crates/dig-wallet/tests/conformance.rs` asserts every served method has a real path in it, and
cross-checks representative request/response schemas field-name-identical against it — this caught the
three real drifts documented in §18.15/§18.16/§18.17. The hand-authored `sage-endpoints-v0.12.11.json`
(method-name-only) vector from #215 remains as a lighter first check.

18.20. **Node-custodied MULTI-wallet provisioning + custody lifecycle (#370/#427).** For the thin-client
model (epic #365) the node HOLDS the wallet keys: it generates or imports one or MORE independent seeds,
encrypts each at rest via `dig-keystore` (§18.18 `seed_store`), and loads an in-memory `WalletSigner` on
unlock. This is a distinct custody locus from the read-only path of #217/#407 (where the node holds only
the client's PUBLIC puzzle hashes and NEVER a key) and supersedes, for the PAIRED-extension path, §18.10's
"the extension self-custodies and never uses the node's sign path". The node custodies MULTIPLE wallets so
the extension's multi-wallet registry (`WalletEntry[]`, each its own seed) can be migrated IN one wallet at
a time (#374). `crate::sage::custody::WalletCustody` owns the lifecycle, each op authorized per §7.12.

**Wallet identity — the master-key fingerprint (§18.20a).** Each custodied wallet has a stable id: the
decimal string of its BIP-39 seed's Chia BLS **master public-key fingerprint** (a `u32`, the canonical Chia
wallet identifier Sage/`get_keys`/CHIP-0002 use). The id is deterministic (same seed ⇒ same id on any
device), non-secret (public-key-derived), and lets a paired caller correlate a node wallet to its
extension `WalletEntry` by fingerprint. Importing a seed whose fingerprint already exists is REFUSED (no
double-custody of one key). One wallet is the ACTIVE wallet; id-taking methods default to it when the `id`
is omitted, so single-wallet callers are unchanged.

Lifecycle methods (a `?`-suffixed `id` argument defaults to the active wallet):

- **create(password, label?)** — generate a fresh 24-word BIP-39 mnemonic, derive its fingerprint id,
  encrypt the mnemonic under `password` (`seed_store::encrypt_seed`), persist it to `<id>.seed`, record a
  non-secret manifest entry, make it the active wallet if none is, and load the signer. Returns `{ id,
  address }` — NEVER the mnemonic (backup is node-local, below).
- **import(mnemonic, password, label?)** / **restore(mnemonic, password, label?)** — validate the mnemonic,
  derive its fingerprint id (refused if that wallet already exists), encrypt + persist it under `password`,
  record the manifest entry, and load the signer. This is the per-wallet migration path that accepts an
  extension seed IN (epic §migration); it is the only inbound key path, loopback-only + gated.
- **unlock(id?, password)** — decrypt the addressed wallet's on-disk seed and load its in-memory signer
  (derived over the wallet's synthetic p2 keys for HD indices `0..N`); enables signing (§18.21). MULTIPLE
  wallets may be unlocked at once. Wrong password fails closed. This is the runtime signer load that
  replaces the bring-up-only `with_signer`.
- **lock(id?)** — drop the addressed wallet's in-memory signer (its encrypted seed stays on disk); signing
  with it is disabled until the next unlock. Other wallets are unaffected.
- **list()** — enumerate every custodied wallet: `[{ id, address?, label?, state, active }]` where `state`
  is `locked`|`unlocked` per wallet. Non-secret only (no seed, no key). The address is present once known
  (recorded at create/import, or cached on the wallet's first unlock).
- **select(id)** — make `id` the active wallet (must exist). The active wallet is the one the Sage-parity
  sign/spend surface (§18.21) signs with, so `select` is how a paired caller scopes signing to a specific
  wallet WITHOUT adding a wallet-id argument to the Sage request schemas (Sage byte-parity, §18.19).
- **status(id?)** — the addressed (default active) wallet's state: `none` (no wallets on this device),
  `locked` (encrypted seed present, no signer loaded), or `unlocked` (a signer is loaded), plus its address
  when known and (additively) its `id` + whether it is `active`.
- **delete(id?, password)** — verify `password` against the addressed wallet's on-disk seed, then remove
  ONLY that wallet's seed file + manifest entry + in-memory signer. Other wallets are untouched; if the
  removed wallet was active, the active pointer moves to another remaining wallet (or clears when none
  remain).

**Key at rest + never exported.** Each seed is Argon2id + AES-256-GCM encrypted at rest under its OWN
password (§18.18), never logged, never returned by any lifecycle op, and never crosses the paired boundary.
The manifest holds NON-SECRET data only (id, receive address, optional label, creation timestamp, the
active id). The ONLY seed egress is the node-local, password-gated backup
(`WalletCustody::reveal_mnemonic(id?)`, surfaced on the self-origin `/api/export` UI §16.3 or a `dig-node
wallet backup` CLI) — never a wallet/`control.*` method (§7.12).

18.20a. **Multi-wallet on-disk layout + back-compat (#427).** Custodied wallets live under
`<config_dir>/wallets/`: one `dig-keystore` container per wallet at `<config_dir>/wallets/<id>.seed`
(owner-only, `0600` on Unix), plus a non-secret JSON manifest `<config_dir>/wallets/index.json` =
`{ "active": "<id>"|null, "wallets": [{ "id", "address"?, "label"?, "created_ms" }] }` (atomic,
owner-only writes). A seed file is encrypted INDEPENDENTLY of every other, so unlocking, signing with, or
removing one wallet cannot decrypt or affect another; every custody error fails closed (a missing wallet
→ not-found, a wrong password → unauthorized, and neither mutates other wallets).

**Legacy single-wallet back-compat + canonicalization (HARD).** A pre-existing single seed at the legacy
path `<config_dir>/wallet-seed.bin` (the #370 single-wallet layout) is adopted as the active wallet under
the reserved TRANSIENT id `default` when the manifest names no other — its real fingerprint id is
unknowable while the seed is encrypted (no password at construction). An existing single-wallet setup
keeps unlocking, signing, and backing up exactly as before: a caller that omits `id` on every method
observes the identical single-wallet behaviour. New wallets always receive a fingerprint id under
`wallets/`.

The legacy wallet is **canonicalized to its real fingerprint id** the first time its mnemonic becomes
knowable — on its first `unlock` (or `restore`/`import` of the same key): the encrypted seed is moved
`wallet-seed.bin` → `wallets/<fp>.seed` (its at-rest password preserved — the file is moved, not
re-encrypted), the manifest entry is renamed `default` → `<fp>` (preserving the active pointer, label,
timestamp, address), and any in-memory session is re-keyed. After canonicalization there is no
`default`-vs-`<fp>` split: exactly ONE id per key. **A key is never custodied twice** — a re-import of the
legacy key under the same password (the #374 migration re-push) canonicalizes the legacy entry FIRST and
is then refused as a duplicate; a re-import under a different password (the legacy password being unknown,
the only case a transient second entry can form) is collapsed to the single canonical entry on the next
unlock of the legacy wallet.

The manifest is self-healing: a missing or corrupt `index.json` is rebuilt from the seed files present at
construction (adopting a legacy `wallet-seed.bin` as `default`), so a seed file is never orphaned and the
reconciled active pointer never dangles.

18.21. **Sign + broadcast on behalf of the paired caller + per-op consent (#371).** With a wallet unlocked
(§18.20), the node is the SIGNER + BROADCASTER for a paired caller (§7.12): a spend request (or a
wasm-built unsigned bundle) is built with the canonical `chia-wallet-sdk` driver constructors (§18.9),
signed with the node-custodied `WalletSigner` of the ACTIVE wallet (native BLS; a paired caller scopes
signing to a specific custodied wallet via `wallet.select`, §18.20 — the Sage request schemas gain no
wallet-id argument), validated by `dig-clvm`
(`validate_spend_bundle`, `DONT_VALIDATE_SIGNATURE` — §18.9) BEFORE broadcast (fail-closed on a tampered or
over-spending bundle), and broadcast to mainnet via `crate::sage::spend::ChiaQueryBroadcaster` (the real
`Broadcaster`, wrapping `chia_query::push_tx` = decentralized peers + coinset fallback, mirroring Sage's
peer `send_transaction`).

**Per-op consent gate.** A broadcast reaches mainnet ONLY when it is BOTH authorized (a paired/master
token, §7.12) AND explicitly consented for that specific operation. Consent is enforced at the
`Broadcaster` seam by `crate::sage::spend::ConsentBroadcaster`: it forwards to the real broadcaster only
when a one-shot consent has been ARMED for the pending op (the extension surfaces the confirm; the served
layer arms consent on the confirmed op) and DISARMS after one broadcast; an unarmed (unconsented) broadcast
fails closed and the inner broadcaster is never called. This is the §16.2 broadcast-gate model adapted for
the authorized-extension path (distinct from the `DIG_WALLET_ALLOW_BROADCAST` dapp dry-run env of §16.2):
an unconsented op builds + signs + validates but does NOT broadcast (nothing is spent). CI NEVER broadcasts
to mainnet — tests drive the `chia-sdk-test` simulator (real consensus incl. BLS) or the recording
`MockBroadcaster`; a real mainnet broadcast is a separate, explicitly-gated live pass.

18.22. **Served on the shipped node + runtime signer load + custody dispatch (#368/#369).** The
`WalletBackend` is BUILT and SERVED by the shipped `dig-node` (§18.1): the `POST /{method}` HTTP mirror on
`9778`, the mTLS `9257` sibling listener, and the bidirectional `/ws` transport (§4.8) all dispatch to the
one live backend.

- **Runtime signer load.** The served backend resolves its signer from the node custody (§18.20) at
  RUNTIME: `require_signer` returns the bring-up-injected signer if present, else the signer of the
  currently-UNLOCKED custody session. A paired `wallet.unlock` therefore enables signing/spend immediately,
  WITHOUT reconstructing the backend; `wallet.lock`/`delete` disable it again. (The test/simulator path
  still injects a fixed signer via `with_signer`, which wins when present.)
- **Custody lifecycle dispatch.** The `wallet.*` methods (`wallet.status`/`list`/`create`/`import`/
  `restore`/`unlock`/`lock`/`select`/`delete`, §18.20) are dispatched by `WalletBackend::dispatch` to the
  attached `WalletCustody`. `wallet.create`/`import`/`restore`/`unlock`/`select` return `{ "address":
  "xch1…", "id": "<fingerprint>" }`; `wallet.status` returns the custody status (`{ "state":
  "none"|"locked"|"unlocked", "address"?, "id"?, "active"? }`); `wallet.list` returns `{ "active":
  "<id>"|null, "wallets": [{ "id", "address"?, "label"?, "state", "active" }] }`; `wallet.lock`/`delete`
  return the resulting state. A `wallet.unlock`/`lock`/`status`/`delete` with no `id` addresses the ACTIVE
  wallet (single-wallet back-compat). The effective signer (`current_signer`) resolves to the ACTIVE
  wallet's unlocked signer, so `wallet.select` scopes the sign/spend surface to a chosen wallet. All are
  gated (§7.12).
- **Sync-status snapshot.** `WalletBackend::sync_status()` derives the `{ state, peak_height, target_height }`
  tri-state (`SyncStatus`, `crate::sage::events`) from the wallet DB — `synced` iff the initial catch-up
  completed, else `syncing`; it is the body the `/ws` transport pushes (§4.8) and re-pushes on transition.

## 18.23. Tipping subsystem — owner lookup, auto-tip policy engine, $DIG spend, tip ledger (#377/#378)

The node OWNS tipping: it holds the wallet/keys and builds+signs+broadcasts the $DIG tip spend; a thin
client (the extension, #379/#380) only CONFIGURES + DISPLAYS it over the WS wallet/control transport
(§4.8). The client NEVER hand-rolls a tip spend. Implemented in `crate::sage::tipping`
(`TippingEngine`), attached to the served `WalletBackend` (`with_tipping`).

**Owner-PH lookup.** A store's on-chain OWNER puzzle hash is resolved from its CHIP-0035 singleton
(the launcher id) via `digstore_chain::singleton::sync_datastore(...).info.owner_puzzle_hash` — the SAME
DataStore parser the node uses for store sync (never re-parses a singleton by hand). The result is
cached per store. The chain client is a `digstore_chain::coinset::ChainReads` (coinset.org) behind the
`OwnerResolver` seam; a `chia-query`-backed `ChainReads` (decentralized peers + coinset fallback — the
substrate that already backs the coin-read fallback tier, §18.5) is a drop-in.

**Config (`tipping-config.json`, persisted, durable atomic write).** `{ creator: AutoTipPolicy, dev:
AutoTipPolicy, daily_total_cap, fee }` where `AutoTipPolicy = { enabled, dig_amount, mode, per_site_cap,
per_site_overrides }` and `mode ∈ { per-site-per-day, daily-budget }`. Amounts are $DIG base units (1
$DIG = 1000 base units, `DIG_DECIMALS = 3`). **Both creator and dev auto-tip are DEFAULT-ON** (#377) —
each has a real recipient (the on-chain-resolved store owner / the DIG treasury), so default-on is safe
paired with the honest-default disclosure + one-click-off (§6.0, #207).

**DIG dev-account daily tip.** The SAME engine, a SEPARATE toggle. Recipient = the **canonical DIG
treasury inner puzzle hash** — the EXISTING byte-identical shared contract that receives every
per-capsule $DIG payment (`digstore_chain::dig::treasury_inner_puzzle_hash()`, decoded from
`TREASURY_ADDRESS` `xch1a37rq3cgcl2ecpudttsf35x75qzdan68lgw2l6ajvmqs44jxdn5qv6pk3y` =
`ec7c304708c7d59c078d5ae098d0dea004decf47fa1cafebb266c10ad6466ce8`; mirrored byte-identical in chip35 +
dighub-core). It is sourced from the shared contract (NEVER re-hardcoded, so a payment-critical value can
never drift into a divergent copy) and is a REAL recipient — so the dev tip is DEFAULT-ON with a small
default daily amount + the same hard caps. Its CAT spend targets this inner PH exactly as the per-capsule
payment does (`Cat::spend_all` CAT-wraps it).

**Money-safety invariants (real mainnet $DIG) — FAIL CLOSED.**
- **Hard caps.** A per-site/day cap (in `per-site-per-day` mode) AND a daily total cap spanning creator +
  dev. Reserved (`Pending`), `Confirmed`, AND ambiguous-`Failed` amounts all count toward the caps, so an
  in-flight or unknown-outcome tip can never be double-counted into an over-spend. A tip that would exceed
  a cap is SKIPPED (`over-per-site-cap` / `over-daily-cap`), never trimmed-and-sent.
- **Crash-safe idempotency.** At most ONE auto tip per `(kind, owner/site, UTC-day)`. The ledger
  reservation (a `Pending` entry) is persisted to `tip-ledger.json` IMMEDIATELY BEFORE the broadcast
  (the only money-moving step). A crash at any point leaves ≤1 reserved entry for that key; on restart the
  engine (re-loaded from the ledger file) treats the key as already tipped and SKIPS — erring toward
  under-tipping, never a double-spend. A definitively PRE-broadcast failure (`TipSpendOutcome::NotExecutable`
  — locked wallet / not-yet-synced / insufficient $DIG) rolls the reservation back (retryable); an
  AMBIGUOUS broadcast error keeps it as `Failed` (never retried that day).
- **Fail-closed on unreadable persisted state.** Load distinguishes an ABSENT file (a genuine first run:
  config → DEFAULT-ON, ledger → empty) from a file that is PRESENT but unreadable/unparseable
  (locked / corrupt / truncated / forward-incompatible). A present-but-unreadable **ledger** POISONS the
  engine — EVERY tip (auto + manual) and config mutation is REFUSED (skip `state-unreadable: …`) until the
  operator resolves the file and restarts — so a corrupt ledger can NEVER reset the cap + idempotency
  accounting to "empty → tip freely" (an N×cap over-spend / same-day double-spend). A present-but-unreadable
  **config** never silently falls back to the DEFAULT-ON default: it fails closed to DISABLED (never
  re-enables an auto-tip the user turned off) and also poisons. `unwrap_or_default()` on the persisted read
  is forbidden.
- **Durable writes.** `tip-ledger.json` / `tipping-config.json` are written to a temp file that is
  `fsync`ed, atomically `rename`d into place, then the parent directory is `fsync`ed (best-effort) — so a
  crash/power-loss can never leave a truncated/zero-length ledger that would then trip the fail-closed
  read path.

**The $DIG spend.** `WalletBackend::build_and_broadcast_dig_tip` selects input $DIG CAT coins
(`asset_id = digstore_chain::dig::DIG_ASSET_ID`) + XCH fee coins, builds via the canonical
`chia-wallet-sdk` `Cat::spend_all` (`spend::build_cat_send` — never hand-rolled CLVM), validates with
`dig-clvm` (`DONT_VALIDATE_SIGNATURE`, §18.9, fail-closed), signs with the node-custodied `WalletSigner`,
and broadcasts through an injected `Broadcaster` (the engine passes its own — so enabling tips does NOT
enable live broadcast for the whole wallet surface). Unattended auto tips need NO per-op user interaction:
the standing config consent (enabled + caps) IS the authorization (the honest-default model, §6.0/#207).
CI NEVER broadcasts to mainnet — tests drive the `chia-sdk-test` simulator + a recording `MockBroadcaster`.

**Method surface (`tip.*`, dispatched by `WalletBackend::dispatch`).** Reads are OPEN; mutations are
paired-token gated (§7.12, `wallet_authz::GATED_WALLET_MUTATIONS`):
- `tip.get_config` (read) → the `TippingConfig`.
- `tip.set_config` (gated) → replace + persist config; returns the stored config.
- `tip.get_ledger { since_ts? }` (read) → the ledger, newest first (each entry `{ id, recipient_ph,
  store_id?, dig_amount, ts, day, txid?, trigger: auto|manual, kind: creator|dev, status:
  pending|confirmed|failed }`).
- `tip.notify_consumed { store_id }` (gated) → run the creator auto-tip for a consumed store.
- `tip.dev_tick` (gated) → run the dev-account daily tip (pays the DIG treasury shared contract).
- `tip.manual { store_id }` (gated) → one-tap manual tip to the store's owner (explicit consent: NOT
  bounded by the auto caps, NOT subject to the once-per-day idempotency).
Each returns a `TipOutcome` — `{ result: "tipped", txid, dig_amount, recipient_ph }` or `{ result:
"skipped", reason }` (stable reason tokens: `disabled`, `owner-unresolved`, `already-tipped-today`,
`over-per-site-cap`, `over-daily-cap`, `state-unreadable: …`, `wallet-unavailable: …`,
`spend-failed-not-retried: …`).

**WS push (§4.8 extension).** When a tip is recorded the engine publishes a `TipEvent` on a DEDICATED
`TipEventBus` (kept OUT of the Sage-parity `SyncEvent` union so tip events never leak into the `GET /events`
Sage stream). Each `/ws` session forwards it as a `{ "type": "tip", "tip": <ledger-entry> }` push frame,
alongside the `sync_status` + `event` frames.

## 18.24. Node-managed unlock authentication + per-transaction sign-unlock (#431/#432)

The node is the LOCAL authority that gates the node-custodied signer (§18.21). There is **NO central
server**: enrollment + verification are entirely local, credential material is encrypted at rest via
`dig-keystore`, and no auth secret is ever logged or returned over any transport. This makes signing
SAFE BY DEFAULT: the decrypted private key MUST NOT persist in memory beyond a single signature.

`crate::sage::auth::UnlockAuth` owns the auth+unlock state machine; it holds a handle to the
`WalletCustody` (§18.20) and mediates the effective signer. When an `UnlockAuth` is attached to the
served `WalletBackend` (`with_auth`), it GOVERNS `current_signer()` — the §18.21 sign/broadcast-on-behalf
path obtains a signer ONLY through the auth gate. When no `UnlockAuth` is attached (the simulator /
bring-up-injected-signer path), behaviour is unchanged (back-compat).

**Unlock mode (the ONLY policy knob).**

- **`per_transaction` (DEFAULT, secure).** A successful `unlock` grants a READ-ONLY session
  (balances/history/reads). It loads NO signer — `current_signer()` is `None`. **Each signing operation
  requires a fresh `sign_unlock`**: the node decrypts the seed, builds a one-shot signer, signs exactly
  ONE operation, and the signer is DROPPED (not resident) immediately after. The key never persists
  beyond that single operation.
- **`session_unlock_all` (OPT-OUT, convenience, OFF by default).** One `unlock` at session start builds
  and HOLDS the signer for the session lifetime; `current_signer()` returns it until `lock`. Set via
  `auth.set_mode`.

**Auth model — per-wallet password + NODE-LEVEL second factor.** One method is active at a time; the user
may add TOTP or a passkey on top of the password.

- The **password is PER-WALLET**: it is the at-rest KDF root that decrypts THAT wallet's seed
  (`dig-keystore` Argon2id, §18.18/§18.20). Every `unlock`/`sign_unlock` requires the TARGET wallet's
  password (`WalletCustody::verify_password`).
- The **second factor (TOTP / passkey) is NODE-LEVEL** — a single node authentication that authorizes the
  unlock across EVERY custodied wallet (#431). Its secret is sealed at rest under a node-level device key
  (`auth/node.key`, owner-only), NOT under any wallet password, so 2FA works uniformly for every wallet.
  When a second factor is enrolled, `unlock`/`sign_unlock` require BOTH the target wallet's password AND
  the node-level factor. A `Credential` carries the password plus, per the active method, a TOTP code or a
  WebAuthn assertion; verification requires every factor the active method mandates. (This is an honest,
  strong-at-rest design for a keyless local node; true passwordless replacement via WebAuthn PRF or a
  TPM-sealed key is a scoped follow-up.)

- **`password` (default).** Verified by decrypting the addressed wallet's seed.
- **`totp` (RFC-6238, `totp-rs`).** `auth.enroll_totp` generates a fresh node-level secret, seals it under
  `auth/node.key`, sets the method to `totp`, and returns the base32 secret + `otpauth://` URI EXACTLY
  ONCE. Thereafter `unlock`/`sign_unlock` require the target wallet's password AND a current 6-digit code
  (±1 step skew). **A code is ONE-TIME-USE** (RFC-6238 §5.2): the last-accepted time-step is persisted and
  a code at a step `<=` it is rejected as a REPLAY (`401`). The check-and-advance is ATOMIC — the
  find-step → compare-to-last → advance runs under a single exclusive lock — so two CONCURRENT verifies of
  the same code cannot both pass (the replay window holds under concurrency, not just sequentially).
- **`passkey` (WebAuthn).** `auth.enroll_passkey_begin`/`finish` register a node-level credential.
  Thereafter `unlock`/`sign_unlock` require the password AND a valid assertion. The real `webauthn-rs`
  ceremony is finalized with the paired-extension origin (#433 follow-up) — it fails closed until then, so
  the active method never becomes `passkey` on this node.

**Enrolling or replacing a factor re-verifies the CURRENT factor.** `auth.enroll_totp` /
`auth.enroll_passkey_begin` / `auth.set_method` and switching mode to `session_unlock_all` all run the
FULL current-factor verification (`verify(id, cred)` — password AND, when a second factor is already
active, the live code/assertion) BEFORE rotating/weakening. So an attacker holding the paired token + a
stolen password — the exact threat 2FA backstops — cannot rotate the factor to their own authenticator or
silently downgrade the posture. Password-only enrollment is permitted ONLY while the active method is
`password`.

**State machine + the §18.21 gate.**

- `unlock(id?, cred)` → verify per the active method → set the session READ-ONLY (`per_transaction`), or
  build + hold the session signer BOUND to that wallet (`session_unlock_all`). Never returns a signer or
  key. A wrong/expired/replayed credential is denied (`401`), leaves the state unchanged, loads nothing.
- `sign_unlock(id?, cred)` → verify (FRESH) → decrypt the target wallet's seed, build a one-shot signer
  BOUND to that wallet, and ARM it for exactly ONE signing operation.
- **Grants/session signers are BOUND to their wallet id (§18.20a multi-wallet).** `current_signer()` for a
  signing op returns the armed grant (or the held session signer) ONLY when its bound wallet id equals the
  node's currently-ACTIVE wallet; otherwise it fails closed — a grant armed for wallet A can never sign
  when B is active. `current_signer()` resolves: bring-up-injected signer (tests) → the wallet-matched auth
  gate signer → (only when NO auth is attached) the legacy held custody signer.
- **Signing dispatch is SERIALIZED + the one-shot grant is consumed panic-safely.** Every key-touching
  signing method (`send_xch`/`send_cat`/`combine`/`split`/`sign_coin_spends`/`submit_transaction`/
  `make_offer`/`take_offer`/mint/transfer/… AND `tip.manual`/`tip.dev_tick`/`tip.notify_consumed`, which
  sign a $DIG tip) is dispatched under a signing mutex held from before the handler THROUGH grant
  consumption, so two concurrent signing calls can never both observe one armed grant (a gate TOCTOU) —
  ONE `sign_unlock` authorizes EXACTLY ONE signature. Consumption is via an RAII guard that runs on normal
  return AND on a panic unwind, so a panicking handler can never leave the key armed + reusable.
- `lock()` → clear the read-only session, drop the session signer AND any armed grant.

**No sibling resident key over the paired boundary.** When the auth gate is attached it is the ONLY
signer-loading path: `wallet.create`/`import`/`restore` verify-and-persist but leave NO resident custody
signer (the custody session is locked immediately after provisioning), and `wallet.unlock` is redirected
to `auth.unlock`/`auth.sign_unlock` rather than loading a session-long resident key.

**Zeroize / residency invariant (adversarial-verified).** In `per_transaction` mode no signer is resident
between signatures: after a `sign_unlock` + one signing operation the one-shot signer is dropped and
`current_signer()` returns `None` — a fresh `sign_unlock` is required for the next signature. Decrypted
mnemonic material is held only in `zeroize::Zeroizing` for the duration of a build and dropped
immediately. (`chia-bls` 0.26 `SecretKey` does not itself zeroize-on-drop; the delivered guarantee is
non-retention — the signer allocation is dropped promptly — plus zeroization of the mnemonic buffer.
Byte-level scrub of the derived scalar via a key wrapper is a scoped follow-up.)

**WS/RPC surface (paired-token gated, §7.12).** Every `auth.*` method requires the master control token
OR a valid paired token, on every transport (`POST /{method}`, `/ws`, mTLS `9257`). Methods:
`auth.status` (mode, method, session state, whether a sign-grant is armed) · `auth.get_method` /
`auth.set_method` (switch active method — `password` resets to password-only) · `auth.set_mode`
(`per_transaction` | `session_unlock_all`) · `auth.enroll_totp` · `auth.enroll_passkey_begin` /
`auth.enroll_passkey_finish` · `auth.unlock` (read-only session) · `auth.sign_unlock` (per-transaction,
authorizes exactly one signature) · `auth.lock`. Auth secrets are NEVER returned except the one-time TOTP
enrollment secret/URI at `enroll_totp` (needed to provision the authenticator). No auth material crosses
as a wallet/`control.*` result.

## 19. Peer network — NAT traversal, discovery, address book, and content location

The standalone `dig-node` binary runs an L7 peer network (the in-process FFI/browser host does not —
§1, §15): a dig-gossip connected peer pool + relay reservation + introducer, a dig-dht content-location
index, node↔node PEX, and multi-source download — all over ONE mTLS identity
(`peer_id = SHA-256(TLS SPKI DER)`) on the dual-stack `[::]` listener (§4.1). This section is the
normative contract for how the node USES its P2P crates. All peer communication is IPv6-first with IPv4
as the fallback (§5.2 ecosystem HARD RULE).

### 19.1. NAT traversal — the full ladder (dig-nat)

Every outbound peer dial (DHT RPCs, multi-source range fetches, PEX candidate verification) MUST use the
FULL dig-nat traversal ladder, tried in canonical rank order:

> Direct → UPnP → NAT-PMP → PCP → hole-punch → Relayed

The relay tier (`Relayed`, via `relay.dig.net`) is the LAST resort — reached only after every direct +
port-mapping + hole-punch tier has failed. A node MUST NOT cap dials to `[Direct, Relayed]` (which skips
port-mapping + hole-punch and over-loads the relay). One shared config constructor
(`net::full_nat_config(per_method_timeout, stun_server)`, built from `dig_nat::NatConfig::default`) is
used at every dial site, so a new dig-nat tier is picked up everywhere at once. Each tier is bounded by a
per-method timeout so a dial never hangs.

### 19.2. STUN reflexive-address discovery

The node discovers its server-reflexive (public) transport address via STUN (RFC 5389) against the STUN
server co-located with the relay (`<relay-host>:3478`, derived from `DIG_RELAY_URL`). The STUN endpoints
are resolved across **both address families** (every A + AAAA record) and the Binding transaction is run
**IPv6-first with IPv4 fallback** (§5.2): the IPv6 STUN server is attempted first and IPv4 is used only
when the IPv6 server is absent/unreachable — the reflexive address is never nulled merely because IPv6
failed.

The reflexive query is run from a UDP socket bound to the node's **ACTUAL listen port** (the peer-RPC
port peers dial), not a throwaway ephemeral socket. The advertised candidate is therefore
`<reflexive-ip>:<listen-port>` — the reflexive public IP paired with the real listen port. The raw STUN
result's own port (the transient socket's NAT-mapping port) is deliberately DISCARDED: advertising it
would be undialable (a remote peer dialing an ephemeral binding reaches no listener). Pairing the
reflexive IP with the listen port yields the form a peer behind a different NAT can dial once the mapping
for that port is open (via UPnP/NAT-PMP/PCP or an endpoint-independent NAT).

The reflexive address is (a) configured on the NAT config so dig-nat's hole-punch tier can use it, and
(b) merged into the node's advertised DHT candidate set **IPv6-first** — a reflexive IPv6 address leads
the whole set; a reflexive IPv4 address leads the IPv4 fallback group — so a peer behind a different NAT
can dial or hole-punch to it. Discovery is best-effort + bounded; on failure the node advertises its
local addresses only. The wildcard bind address (`[::]`/`0.0.0.0`) is never advertised as a candidate.

The advertise path — candidate aggregation, family keying, de-duplication, and the IPv6-first family
ordering — is delegated to the canonical [`dig-ip`](https://crates.io/crates/dig-ip) crate (CLAUDE.md
§5.2, the ecosystem's single source of truth for the address-family / IPv6-first contract). Advertised
candidates are aggregated + source-tagged (`dig_ip::CandidateSource::StunReflexive` / `ListenAddr`) +
de-duplicated by `dig_ip::PeerCandidates`, then emitted in `dig_ip::Family` preference order (V6 before
V4); the node MUST NOT hand-roll a family sort in the advertise path. The DIAL path inherits the
local∩peer family intersection from dig-nat (which itself uses dig-ip), so the node does not duplicate
that intersection logic.

### 19.3. Content location — dig-dht is the sole locator

Content location ("which peers hold capsule X?") is the dig-dht provider index: the live locator is
`DhtProviderLocator → find_providers` inside the content engine (`NodeContent`). The
REDIRECT-ON-MISS / `dig.getAvailability` hint path uses this dig-dht locator EXCLUSIVELY (a redirect
must name genuine announced holders). The node keeps its own held-inventory provider records current
(announce / republish / refresh / gc) and withdraws them on shutdown.

**Download-side connected-pool fetch source (`PoolProviderLocator`, #1590).** The multi-source FETCH
path (`peer_serve_plaintext` → `NodeContent::fetch_resource`) uses a locator that UNIONS the dig-dht
locator with the node's currently-CONNECTED gossip-pool peers. This closes the #836 read-leg gap: on a
relayed / isolated network a holder is discovered in the DHT but its advertised provider record carries
addresses the reader cannot dial, so a DHT-only locate yields no REACHABLE source and the read
dead-ends at the §21 upstream backfill (404) even though the reader is ALREADY CONNECTED to that holder.
Offering every connected pool peer as a fetch candidate lets the download reach the holder over the
established connection. A pool peer's candidate MUST list its addresses newest-session-first: dig-gossip
republishes `PoolEvent::PeerAdded` when a freshly authenticated session SUPERSEDES a stale slot for the
same `peer_id` (newest-wins re-adoption), and that is typically a MOVE — a dead relay circuit replaced by
a direct dial. The superseded addresses are RETAINED as trailing fallbacks (a still-working older path is
not discarded) but MUST NOT be dialed first. Re-adoption MUST NOT grow the candidate set: the pool is
keyed by `peer_id`, so a republished `PeerAdded` upserts one entry — a re-adopted peer is one candidate,
never two. A connected-pool holder is NOT gated behind a separate `dig.getAvailability`
confirm probe: the download transport short-circuits the confirm to *available* for any provider whose
`peer_id` is currently in the connected pool (`PoolConfirmTransport`, #836), so the fetch proceeds
straight to `dig.fetchRange`. This is required because dig-download's `locate_and_confirm` DROPS any
provider whose availability answer is not *available*, and a connected holder can answer
not-available as a FALSE NEGATIVE on a relayed / isolated net (a cache-inventory lag, a
resource-vs-capsule granularity quirk) or have its probe transiently fail — either of which would drop
the connected holder, issue ZERO `dig.fetchRange`, and dead-end the read at the §21 upstream backfill
(404) despite a connected, serving holder. Safety is preserved by the whole-resource merkle check, which
binds every served byte to the chain-anchored root: a connected NON-holder simply fails its ranges and
is dropped there, a safe pool-bounded probe. A DHT-only (non-pool) provider still goes through the real
`dig.getAvailability` confirm. This source is DOWNLOAD-only — it never feeds the redirect/availability
hint above.

**The availability answer MUST agree with what the node can SERVE (#1592).** `dig.getAvailability` is
the gate every DHT-discovered holder must pass — dig-download's `locate_and_confirm` DROPS a provider
whose answer is not *available* BEFORE any `dig.fetchRange` — so at ROOT / RESOURCE granularity the
answer is DERIVED FROM THE SERVABLE SOURCE: the existence of the very capsule module
(`<cache>/modules/<store>/<root>.dig`) the serve path reads. It MUST NOT be derived from an
inventory snapshot that can lag a write, and any cache retained for cost MUST be invalidated on every
inventory-changing write (pin, §21 sync, on-demand fetch-and-cache, gap-fill, backfill, eviction).
A snapshot lags in BOTH damaging directions: a capsule that landed after the snapshot was taken (a
gap-fill / §21 sync / fetch-through / pin write concurrent with the peer-facing inventory walk) is
already servable, and answering *not available* for it drops a holder that would have served the bytes
— the DHT-only discover→read leg's false negative; conversely a snapshot that lags an EVICTION would
claim availability the node cannot serve. Consequently: a capsule gained at runtime is IMMEDIATELY
reported available, an evicted one IMMEDIATELY is not, and a capsule genuinely not held is still
reported not available (the answer is never weakened to an unconditional *available* — the merkle
verify remains the integrity gate downstream, but availability MUST NOT lie in either direction).
STORE granularity (`root` absent) still enumerates the held `roots` from the inventory walk, which a
single-path existence check cannot answer; that `roots` list is ordered CANONICALLY (by root hex),
NEVER by an access-time/recency field, so the permissionless peer surface leaks no read-recency
ranking of the operator's interests. Because this method is peer-reachable (§7.4), the
per-request cost is bounded: one path existence check per queried item, and the whole-cache directory
walk is performed AT MOST once per batch and ONLY when some item asks at store granularity. Every
caller-supplied `store_id`/`root` is validated canonical 64-hex before any path is built from it (the
same path-traversal guard `cache.removeCached` applies), so a crafted key answers *not available*
without touching the filesystem.

A `dig.fetchRange` answer is a stream of `u32`-BE length-prefixed JSON frames, each frame's `bytes`
field the **base64** encoding of that window's ciphertext (the canonical
`dig_rpc_protocol::types::RangeFrame` wire this node's serve path emits). A reader MUST base64-decode
it; reading the field as raw bytes yields the base64 TEXT and every frame is rejected as
over-length — the #1586 read-leg blocker, which required dig-nat >= 0.11.2 to fix.

**Per-range verification metadata — EVERY frame, not just the first.** A served frame MUST carry the
metadata that makes it independently checkable against the chain-anchored generation root:
`total_length`, `root`, `chunk_count`, and — when the window begins exactly on a chunk boundary —
`first_chunk_index` (with `chunk_index` as its pre-existing alias for the same value). `chunk_lens` and
`inclusion_proof` are the resource-scaling PROLOGUE and ride the stream once rather than every frame
(see the framing rules below). A downloading peer fetches ranges in parallel from many holders, so a frame that
declared no `root` (as only-the-first-frame metadata left every later range doing) could not be checked
for generation consistency on arrival: a wrong-generation source was detectable only after the whole
resource had been paid for in bandwidth. A frame whose window starts MID-chunk MUST omit
`first_chunk_index`/`chunk_index` entirely rather than assert an index the caller's own alignment check
would contradict.

The served window is EXACTLY the requested span, never widened to a chunk boundary: a verifying client
fails a range closed on any length but the one it planned.

**A `dig.fetchRange` STREAM MUST NOT serve past the requested `[offset, offset+length)` span, however
far the resource itself continues (#1619).** The per-frame window cap above bounds one FRAME; a holder
answering a request whose span exceeds one node window still streams MULTIPLE frames (advancing
`offset`) to cover it, and that multi-frame loop MUST stop the instant the requested span is satisfied
— NOT merely when the frame's own `complete` flag reports the resource exhausted. `complete: false` on
the LAST frame of a satisfied request is normal and expected: it means the RESOURCE continues past the
request, not that more of the STREAM is still to come. A holder that keeps streaming past the requested
`length` turns a client's small probe range (e.g. `{offset:0, length:1}` — dig-download's own
metadata-probe pattern, sent on every download) into an unbounded amplification: hundreds of bytes in
for the WHOLE resource's verification-metadata-laden frames out. The client-side clip
(dig-download's own defensive re-clamp of an over-length frame) is defense in depth, never a substitute
for the holder's own bound — re-introducing a client-side REJECTION of an over-long frame is the #836
class of defect (a false negative that makes an honest holder look like a liar) and MUST NOT return.

**A FRAME is bounded by `MAX_RANGE_FRAME_PAYLOAD`, not by the request window.** A serving node MUST
split a requested span into frames carrying at most `dig_nat::MAX_RANGE_FRAME_PAYLOAD` (32,768) raw
payload bytes each, and MUST write each frame through `dig_nat::RangeFrame::encode`. `RANGE_WINDOW`
(3 MiB) is the default and maximum a single REQUEST may ask for; it is NOT a valid per-frame size. The
two are 96x apart, and `bytes` travels base64, so a frame sized by the request window produces a body
past `dig_nat::MAX_FRAMED_BODY` (65,536) which a conforming receiver is REQUIRED to reject — making
every resource over roughly 48 KiB unserveable by any holder (dig_ecosystem#1640/#1668). The same
ceiling binds `dig.fetchModuleRange`, whose frames the puller also decodes with `dig_nat::RangeFrame`.

Frames MUST be produced through the dig-nat type rather than hand-built as JSON and written with an
uncapped framer. The encoder's refusal is what makes an unserveable frame impossible to emit rather
than merely unlikely: a sender that builds its own JSON has no way to learn it produced something the
receiver must reject, so the divergence can only surface as a failed read in production.

**Which metadata rides which frame.** The metadata splits by whether it scales with the RESOURCE
(dig-nat `SPEC.md` §5.1.1 is normative):

- The **identity set** — `root`, `total_length`, `chunk_count`, plus `chunk_index`/`first_chunk_index`
  where the window is chunk-aligned — is fixed-size and MUST ride EVERY frame. It is what lets a reader
  reject a wrong-generation or wrong-layout holder the moment a frame arrives.
- The **prologue** — `chunk_lens` and `inclusion_proof` — scales with the resource and MUST be sent
  once per range stream, never repeated on later frames. A layout exceeding
  `dig_nat::MAX_CHUNK_LENS_PER_FRAME` (2,048) entries MUST be sent as a **paged prologue**: successive
  frames each carrying at most that many entries, each stamped with the `chunk_lens_offset` at which its
  page begins. Pages MUST tile the array exactly — no page may be empty, and every page except the tail
  MUST be exactly `MAX_CHUNK_LENS_PER_FRAME` entries, since a short non-tail page leaves a gap no
  page-aligned page can ever fill.
- A stream MUST NOT report `complete` while prologue pages are still owed, and MUST NOT end before the
  prologue is delivered whole — including when the requested span needs FEWER frames than the prologue
  does, in which case the remaining pages ride zero-payload frames. `chunk_lens` is a DECRYPT input
  whose entries must sum to `total_length`, so a reader MUST discard a partial layout entirely: a
  layout short even one entry cannot decrypt the resource, making it unusable rather than partially
  useful.
- A request MAY set `skip_layout` when the client already holds the commitment for this `root`; a
  holder honouring it omits the resource-scaling set and ONLY that. The identity set is never
  suppressed, because it is what detects a wrong-generation holder on arrival. `skip_layout` absent or
  false preserves the earlier behaviour, so a holder that does not understand the field is never broken
  by it.

Every frame's declared `length` MUST equal its own payload length. A frame whose `length` disagrees
with its `bytes` is one a reader distrusts, and no receiver in this tree validates the relation, so the
obligation is the sender's alone.

**`dig.fetchModuleRange` frames** obey the same framing ceiling, and carry `total_length` — the served
window's length — on EVERY frame rather than only the first. They carry no `root` or `chunk_count`: a
`.dig` capsule is self-verifying against the chain anchor on install (§the module-anchor gate), and this
leg has no per-resource chunk layout to count, so a `chunk_count` here would be a claim about a structure
that is not present.

**KNOWN CONSTRAINT — the paged prologue has no RECEIVER in this dependency tree.** dig-download 0.11
reads `chunk_lens` from the first frame only and ignores `chunk_lens_offset` and every later page
(`ChunkLensAssembler` ships in dig-nat 0.14 / dig-download 0.12; this node is held at 0.13 / 0.11 by
dig-gossip and dig-peer-selector — see `crates/dig-node-core/Cargo.toml`). So a resource whose layout
exceeds `MAX_CHUNK_LENS_PER_FRAME` — roughly **128 MiB** at the 64 KiB chunk target — is served
correctly by this node but still fails at the reader, now at its `chunk_lens`-sum check rather than at
frame decode. This is FAIL-CLOSED and cannot mis-verify: a partial layout is refused, never used. It is
resolved by the same cascade as the rest of the 0.14 move (dig_ecosystem#1686).

`chunk_count`, `chunk_lens_offset` and `skip_layout` are additive wire fields (§5.1 backwards
compatibility): an older reader ignores them, and a newer reader parses an older frame with each absent.

A serve MUST NOT emit a per-CHUNK inclusion proof (`range_proof`). No such proof is derivable from the
store format: the generation root's merkle leaves are per-RESOURCE (`resource_leaf(ciphertext)` =
SHA-256 of a resource's WHOLE ciphertext, folded by `MerkleTree::from_leaves`), so a single chunk has no
committed digest to prove and recomputing the leaf requires every other chunk's bytes. The
chain-anchored binding is therefore established once, over the assembled resource, via
`inclusion_proof`; a per-chunk proof would be unverifiable decoration inviting a client to trust bytes it
cannot check, and is REFUSED rather than fabricated. Real per-chunk proofs require a store-format
prerequisite: a per-resource chunk-commitment structure added as a NEW leaf-kind / data-section id with
version dispatch (or carried as a parallel commitment alongside today's leaf) — NEVER a redefinition of
`resource_leaf` itself, since `dig-client-wasm`/`dig-capsule-wasm` check that value byte-identically and
`PublicManifest.sha256_latest` is normatively pinned to it (digs `SPEC.md` §8), so existing capsules keep
reading unchanged. Out of scope until that prerequisite exists (dig_ecosystem#1601).

The download locator (dig-dht ∪ connected pool) is itself SELF-EXCLUDED: THIS node's own `peer_id`
(hex) is dropped from the fetch-candidate set before any dial, exactly as the DISCOVERY leg is (#1584).
A relay-introduced self-connection can surface this node in its own gossip pool (`peer_id == local`);
offered as a fetch candidate it would self-dial (Direct → own IP → connection refused; Relayed →
refused self-dial), starving the download's confirm round and dead-ending the read at HTTP 404 despite a
reachable holder being connected. Two defenses hold this: a self `PeerAdded` is dropped at the pool feed
(`on_pool_event`) so self never enters the connected pool OR the selector registry, and the whole
download locator is wrapped so NO source — DHT or pool — can ever offer self on the fetch/dial path
(#836/#92, run e2e-836-arb-20260725-084501).

**Announce vs. locate granularity (resource→capsule fallback).** Inventory is announced at STORE and
CAPSULE (`store_id:root`) granularity ONLY; per-RESOURCE provider records are deliberately NOT announced
(a capsule holder serves every resource inside it, so per-resource records would be redundant and would
explode DHT write volume). A `/s` resource read miss, however, locates by a RESOURCE content id. The
node's locator therefore MUST bridge the two: on a `ContentId::Resource` lookup it ALSO queries the
parent `ContentId::capsule(store_id, root)` and unions the holders (deduped by `peer_id`, resource-key
hits first), so Tier-2 peer fetch resolves the announced capsule holder and proceeds to
`dig.getAvailability` + `dig.fetchRange` for the specific resource. Without this bridge a resource read
finds no providers and dead-ends at the public-RPC tier even when a holder is discoverable
(`CapsuleFallbackLocator`, #1580).

**Announce-on-inventory-gain (the reshare / flywheel invariant).** A node that GAINS a capsule at runtime
— by ANY path: a hosted pin, a §21 whole-store sync, a chain-watch gap-fill, or the read-side
backfill-cache (a reader that caches what it just fetched) — MUST re-announce its DHT inventory so peers
immediately discover it as a NEW holder of that capsule (§14.1). This is the discoverability half of the
content-replication flywheel (#1423/#1425): every read makes content more available because the reader,
on caching, becomes a discoverable holder. The re-announce is fired ONCE per freshly-landed capsule at the
single centralized landing site (`CapsuleStore::cache_fetch_and_cache`, through which every runtime
capsule-gain path flows), guarded so an already-held capsule is a no-op (unchanged inventory → no
re-announce). It is best-effort and a no-op on the in-process FFI path (no peer network / inventory
refresher installed).

### 19.3a. Real-time holdings announce — dig-gossip opcode 222 (#1429)

Beside the DURABLE provider records above, the node maintains a REAL-TIME holder signal. The durable
records converge only as fast as the last PUT reached and a departed holder lingers for its record's TTL;
the announce closes that gap.

**Egress (MUST).** Every inventory reconcile MUST derive both effects from ONE delta: the DHT records
(announce gained ids, ACTIVELY retract lost ids via `retract_own_provider`, never the passive
`withdraw_provider` — a passively withdrawn record keeps answering `find_providers` with this node for
content it can no longer serve, costing each reader a wasted dial), AND a signed opcode-222
`HoldingsAnnounce` carrying `Add`/`Remove` deltas for exactly those ids. A reconcile larger than
`HOLDINGS_MAX_CHANGES` (256) deltas MUST be SPLIT across frames, never truncated — truncation would drop
retracts and leave this node advertising content it does not hold.

- The announcement MUST be signed by the node's own `NodeCert` leaf (ECDSA-P256), because the wire
  derives `provider_peer_id` from `SHA-256(provider_spki)`; signing with any other key announces an
  identity no peer can dial.
- The advertised addresses MUST be the SAME advertised candidate set the DHT provider records carry.
- `seq` MUST strictly increase per node, and MUST NOT restart from zero — a node resuming from zero has
  every announcement dropped as a replay by peers that remember its previous watermark. The
  implementation seeds from the wall clock and increments once per batch. Note the two limits of that
  seed, neither of which a receiver can be harmed by: it does NOT guarantee the seed exceeds every value
  previously announced (a node averaging more than one batch per second outruns its own clock, so the
  seed after a restart can be below the counter it reached), and a backwards clock adjustment has the
  same effect. The consequence is self-inflicted silence — this node's announcements are ignored until
  the counter it left behind is passed — never an accepted replay. Seeding above the last value
  announced requires persisting the counter, which is deferred (#1477).
- A degraded node (no signable leaf, no inbound receiver) MUST remain discoverable through the durable
  DHT records — the real-time layer is additive and MUST NOT be a hard dependency of discoverability.

**Peer-presence re-announce (MUST, #1734).** A node MUST re-announce its CURRENT holdings in full — every
held content id as an `Add`, with no diff — whenever its connected peer pool rises from ZERO peers to one
or more, including the first such observation after bring-up. It MUST NOT re-announce merely because an
already-peered pool grew.

The reconcile delta above is computed against this node's OWN local provider records, so it answers "what
changed here", never "what do my peers know". Those two diverge silently as soon as an inventory change
happens with nobody connected: the local records move, the flood reaches zero peers, and every later
reconcile of the same inventory is a no-op. Without this rule a node that pinned before its first peer — or
that RESTARTED with content already cached, where the remembered inventory is seeded from disk before any
peer connects — holds the content, has recorded it as announced, and is invisible to every peer it later
connects to, with a restart re-entering the same state. Re-stating the whole inventory is safe because an
`Add` is idempotent at every receiver under an advancing `seq`.

**Ingress (MUST).** An inbound announcement is applied ONLY after all of the following, fail-closed, at a
single chokepoint. dig-dht is crypto-free by design, and `ingest_verified_provider` is the sole sanctioned
bypass of its mTLS self-announce check, so these are the whole of the authentication:

0. **DECODE refuses a frame whose declared counts exceed the protocol maxima, BEFORE reserving for them**
   (#1723). The wire states its batch size and each `Add`'s address count as `u16`, so both are the
   sender's to choose; decode MUST check them against `HOLDINGS_MAX_CHANGES` (256) and
   `MAX_ADDRS_PER_CHANGE` (32) before any allocation is sized from them. This gate is stated separately
   from gate 1 because it necessarily runs BEFORE it: decode precedes the signature check, so an
   allocation sized here is one an UNAUTHENTICATED peer commissioned. A ~200-byte frame declaring
   65,535 addresses would otherwise reserve ~2 MiB, and no later gate can refund it. The general rule
   this instantiates: **never size an allocation from a number a peer supplied.**
1. `verify_holdings_announce` passes (batch cap, `SHA-256(provider_spki) == provider_peer_id`, P-256 SPKI,
   valid signature over the `dig:holdings:v1` domain-separated message).
2. `provider_peer_id` is CANONICALIZED (decoded to 32 bytes, re-encoded lowercase) and every subsequent
   comparison, map key and provider argument uses ONLY that value. This is normative, not hygiene: hex
   decoding is case-insensitive and the signature covers the DECODED bytes, so one identity has many
   spellings that all verify. A receiver that keys on the raw wire text gives each spelling its own replay
   watermark and misses a lowercase self-identity comparison, turning gates 3 and 5 into no-ops at zero
   cryptographic cost. A `provider_peer_id` that is not 64 hex characters MUST be refused before it is
   compared, keyed, or logged.
3. The announcement is NOT attributed to this node's own (canonicalized) `peer_id` — the network MUST NOT
   be able to tell a node what it holds.
4. `announced_at` is within **±300 s** of the receiver's clock; otherwise the announcement is refused as
   stale. REQUIRED, not defence in depth: a `Remove` delta carries no expiry of its own, so without this
   the only barrier to replaying a captured retract indefinitely is the in-memory watermark of gate 5 —
   which a restart clears and a capacity eviction drops, letting anyone de-list an honest holder by
   replaying that holder's own old retract at a freshly started peer. The signature binds WHO announced;
   only this bound binds WHEN. The check is symmetric, because a future-dated frame stays replayable
   longer than it should.
5. `seq` strictly advances beyond the highest already applied for that CANONICAL provider identity;
   otherwise the announcement is dropped (a replayed older frame MUST NOT resurrect a retracted record).
   A provider not yet seen has NO watermark, which is distinct from a watermark of zero — `seq` is not
   required to start at 1. A rate window elapsing MUST NOT reset the watermark: replay protection is not
   a rate limit.
6. Two token buckets, both within a 60-second window: at most **10 announcements per PROVIDER**, and at
   most **1,024 (`4 × HOLDINGS_MAX_CHANGES`) deltas per TRANSPORT SENDER**. They are keyed differently on
   purpose — a provider id is attacker-minted so its bucket map must be capacity-bounded and is therefore
   evictable, whereas the sender key space is the connected pool and cannot be inflated from off-network,
   making it the unbypassable backstop. A REJECTED announcement MUST charge neither bucket, or the
   limiter itself becomes the denial of service.

**Bounded state (MUST).** A rejected announcement MUST NOT allocate tracking state. Admission is decided
in full BEFORE any per-provider or per-sender entry is created, because every rejection path returns early
and would otherwise skip the eviction step, letting an attacker-minted key space grow the maps for the
price of one ~180-byte frame per entry. Admitted entries are capacity-bounded (1,024 senders, 8,192
providers) with least-recently-seen eviction.

**Untrusted fields (MUST).** `provider_peer_id` is a `u16`-length-prefixed wire string and may carry tens
of kilobytes of arbitrary UTF-8, including newlines and terminal escapes. No peer-supplied field may be
emitted to the log; only the canonicalized identity may be. Bounding log LEVEL bounds volume, not content.
An `Add` delta's address list MUST be truncated to `MAX_ADDRESSES_PER_RECORD` before it is mapped, since
its length is an attacker-declared `u16`.

**Operator control (SHOULD).** `DIG_HOLDINGS_INGEST=0` disables the ingress while leaving egress intact;
discovery then degrades to the durable DHT records rather than failing.

**Attribution (MUST).** The provider identity used for both `ingest_verified_provider` and
`remove_provider_record` MUST be the VERIFIED signer and nothing else. A retract therefore removes only
the signer's own record and can never de-list another holder of the same content key. The wire carries no
per-delta peer field, so this holds structurally: the receive path accepts no caller-supplied provider id.

**No amplification (MUST).** The ingress performs NO egress — it never re-broadcasts, dials, probes or
fetches. One inbound announcement costs the receiver bounded local map work only, so a cheap anonymous
message can never make honest peers do more work than the sender did.

**Reach is ONE HOP (normative, and deliberate).** An announcement is delivered to the announcer's directly
connected peers and is NOT re-flooded onward: dig-gossip's Plumtree eager/lazy dissemination applies to
frames a node ORIGINATES via `broadcast`, and the opcode-222 receive path does not re-broadcast. The
real-time layer is therefore a NEIGHBOURHOOD freshness signal, and the DHT provider records (PUT to the
k-closest peers and republished) remain the only network-wide discovery mechanism. This is sufficient for
the layer's purpose:

- For an ADD, one hop covers the highest-value case. A node's direct peers are exactly who is positioned
  to fetch from it, and the fetch path already prefers connected-pool holders over a DHT record. Peers
  further away discover the new holder through the durable records, as they always did.
- For a REMOVE, one hop leaves peers more than one hop away holding a stale record until TTL. That is a
  LATENCY gap, not a correctness gap: the local record is deleted at once by `retract_own_provider`, the
  k-closest copies age out, and the cost of a stale record is one failed dial that the peer-selector
  deranks.

Re-flooding verified announcements would close the remaining gap but MUST NOT be added at the ingress:
that would make one inbound message produce N outbound, which is precisely the amplification this layer is
built to avoid. The correct shape, if wider reach is later required, is for dig-gossip to relay verified
opcode-222 frames through its EXISTING Plumtree seen-set (which already provides dedup and flood control),
never a re-broadcast from the receive path.

**False claims.** A peer MAY announce content it does not hold. This is bounded by cost asymmetry rather
than prevented: the liar pays a signature and a flood, and buys at most one failed dial or a
`dig.getAvailability` answering "no", after which the peer-selector deranks it. No merkle- or
chain-verification decision ever rests on an announcement.

### 19.4. Address book — durable, IPv6-first, provenance + TTL

The node maintains a durable peer address book: every learned peer candidate — from PEX, `dig.getPeers`,
the relay introducer, or an observed pool peer — is INGESTED into the book (keyed by `peer_id`) rather
than dialed-and-dropped. The book:

- unions each peer's directly-dialable addresses, ordered **IPv6-first**;
- records provenance (a first-hand pool / `getPeers` sighting is not downgraded by a later PEX hint) and
  a freshen timestamp;
- persists relay-only / not-currently-dialable hints (they survive to seed a later dial);
- reads back a ranked, non-stale candidate list (IPv6-dialable peers first, then other dialable, then
  relay-only; ties by recency), evicting the stalest entry at a capacity bound and dropping entries past
  a staleness TTL.

### 19.5. PEX candidate handling

PEX-discovered candidates are HINTS (proven only by a successful mTLS dial). On receiving a PEX candidate
batch the node offers EVERY candidate (including relay-only) to the address book (§19.4), then dials a
bounded number selected from the book — verifying each over the full ladder (§19.1) and adopting the
verified connection into the pool. A failed dial keeps the hint in the book for a later retry; a peer
already in the pool is skipped.

### 19.6. Selector-driven dial ordering

The shared self-optimizing peer selector (dig-peer-selector) that ranks download SOURCES also orders
which address-book candidates the node DIALS first: dials are ranked by the selector's content-agnostic
per-peer quality (reliability blended with throughput; a banned peer sinks to the bottom; a cold peer is
explored at a neutral rank). The node reuses the ONE selector instance; IPv6-first order is preserved
among equally-ranked peers. In PRIVACY mode the selector does not apply (the onion path uses its own).

### 19.7. Crate-API integration status (release-first follow-ups)

Two intended crate-side integrations are pending a release-first dig-gossip change and are realized
node-side in the interim:

- dig-gossip exposes no PUBLIC production API to ingest external addresses into its `AddressManager`
  (only a hidden test hook), so the durable address book (§19.4) lives in the node; when dig-gossip ships
  a public `offer_addresses` ingest API the book flushes into the crate `AddressManager` (one source of
  truth).
- dig-gossip's `PeerPoolConfig` exposes no dial-priority hook, so selector-driven ordering (§19.6)
  applies to the node's PEX candidate dials; when dig-gossip ships a pool dial-priority hook the same
  ranking drives the pool's own maintenance dial loop.

Exercising the connected pool end-to-end is gated on the network-genesis bring-up (the pre-launch
placeholder genesis is rejected by `GossipService::start`); these behaviors are unit-tested
independently of a live pool.

### 19.8. Relay reservation — control dial + advertised listen candidates

The node holds ONE persistent relay reservation (dig-nat `run_relay_connection`) sharing a single
`Arc<RelayStatus>` with the gossip pool. The reservation advertises the node's real gossip listen
candidates in the RLY-001 `Register` message (`listen_addrs`, dig-nat 0.3.0's `Register.listen_addrs`
field): the node offers its `gossip_port` on the IPv6 unspecified address FIRST, then the IPv4
unspecified address (§5.2 IPv6-first). The relay performs reflexive-IP substitution — it pairs the
advertised PORT with the source IP it observes — so a peer behind a different NAT receives a DIALABLE
`<reflexive-ip>:<gossip-port>` candidate. dig-nat 0.3.0 is adopted now that dig-dht, dig-download, and
dig-peer-selector are republished accepting dig-nat `>=0.2,<0.4`, so the graph unifies at exactly one
dig-nat 0.3.0.

The node retains the live `GossipHandle` for the pool so the CONTROL surface can act on it:
`control.peers.connect` dials a discovered/known peer into the connected pool, `control.peers.disconnect`
drops a pooled peer, and `control.peerStatus` enumerates the pool as the per-peer array (§8.7). The
in-process FFI host runs no peer network, so it retains no handle — connect/disconnect report "no peer
network" and the peer array is omitted.

## 20. Logging — structured JSONL file + human stderr (#553)

The node adopts the shared `dig-logging` building block (`dig-logging` crate, `dig_ecosystem` #547),
so its sink layout, JSONL schema, log directory, rotation, level control, correlation ids, redaction,
and `logs` verbs are byte-identical to every other DIG service binary. `dig-logging`'s own `SPEC.md`
is the normative contract for those; this section records what dig-node MUST do.

### 20.1. Where the subscriber is installed

The node MUST install the `dig-logging` subscriber exactly once, at a SERVE entrypoint, and hold the
returned guard for the process lifetime:

- the foreground `run` path and the unix daemon (`serve` via the CLI entrypoint) install it as run
  context `service` when the process is an installed OS-service run, else `cli`;
- the Windows service body (`run-service`, §9.4) installs it as run context `service` immediately
  after marking the process a service, BEFORE building the runtime — a Windows service has no
  console, so the JSONL file is the only log.

A one-shot CLI command (`status`, `pair`, `config`, …) does NOT install the subscriber: it neither
needs a rolling log file nor the maintenance thread. Installation is best-effort — a logging failure
(unwritable dir, subscriber already set) is reported on stderr and MUST NOT stop the node serving.

The log directory follows `dig-logging` SPEC §3: the machine root `<…>/DigNetwork/logs/dig-node`
(`C:\ProgramData\DigNetwork\logs\dig-node`, `/Library/Logs/DigNetwork/dig-node`,
`/var/log/dig/dig-node`) for a service run, the per-user dev-fallback for an unprivileged `dig-node
run`, and `DIG_LOG_DIR` overrides both — mirroring the #501 daemon/CLI state-dir split.

### 20.2. Levels — used by MEANING

Events are emitted at the level that matches their operational meaning, not uniformly: `error!`
(operation failed / broken invariant), `warn!` (recoverable, degraded, or a fallback taken — a
listener that failed to bind non-fatally, a TLS/plaintext downgrade, a control-token persist
falling back to an in-memory token), `info!` (sparse operator lifecycle — the node listening with
its bound addresses + upstream, a listener up, leaf renewed, shutting down), `debug!` (developer
diagnosis — per-request RPC dispatch, a per-tick self-heal pass, a config-disabled surface),
`trace!` (firehose). The default filter is `dig-logging`'s noise-trimmed `info`.

### 20.2a. Peer-facing serves MUST announce their outcome

Every inbound peer-facing serve MUST record its OUTCOME in the log, so a read can be diagnosed from
logs alone and never requires a packet capture. Concretely:

- An inbound `dig.fetchRange` MUST emit one `info!` line per request naming the requesting `peer_id`,
  the content id (`store_id`, `root`, `retrieval_key`), the requested `offset`, and the outcome — one of
  `served` (with the total `served_bytes`, the `frames` those bytes were split into, and whether a proof
  was attached), `not-held`, `bad-range`, or `redirect` (each with the catalogued error code the caller
  was given and a short reason). The reported `offset` is always the offset the caller REQUESTED, never
  how far a partial stream advanced. Per-frame detail (offset, byte count, chunk index, chunk alignment)
  is `debug!`, and a frame whose window does not start on a chunk boundary OMITS `first_chunk_index`
  rather than reporting `0` — the same omit-what-cannot-be-stated-truthfully rule the frame metadata
  itself follows (§19.3, *Per-range verification metadata*).
- `served` means bytes were streamed. A serve path that answers an unsatisfiable range with an error
  frame (the fetch-through miss path, §19.3) MUST report that refusal, NOT `served` with a zero byte count,
  and `frames` MUST be the frame count actually written. An outcome line that says `served` for a
  request that served nothing reintroduces the exact ambiguity this section removes.
- An inbound `dig.getAvailability` MUST emit one `info!` line per answered item naming the queried
  content id, the `available` answer, and the REASON for it: `held`, `not-held`,
  `rejected-non-canonical-key` (a `root` that is not canonical 64-hex, refused without a filesystem
  touch), or `store-roots` (a store-granularity query, with the count of held roots).

These lines carry **ids, counts, and outcomes ONLY** — never a served byte, never a proof, never a
secret (§20.4 / the never-log rule). A silent serve is a specification violation: silence is
indistinguishable from a request that never arrived, which is exactly the ambiguity that made the
read-leg bring-up dependent on `tcpdump`.

**A peer-supplied identifier MUST NOT be logged verbatim.** Every id on this surface arrives inside an
untrusted, 64 KiB-capped frame, so a verbatim id would let any peer amplify the operator's log by
~64 KiB per request and — since a JSON string may contain `\n` — FORGE an additional record, including a
counterfeit `served` outcome. An id therefore MUST be recorded only when it is a canonical 64-hex content
id; otherwise a short fixed sentinel (`<non-canonical>` for an unusable id, `<absent>` for one the request
did not carry) MUST be recorded in its place. This applies to `store_id`, `root`, AND `retrieval_key` on
both the `dig.fetchRange` and `dig.getAvailability` paths. Nothing diagnostic is lost: a non-canonical id
could never have named held content, and the outcome/reason on the same line already states why the
request failed.

**Free-form explanatory text MUST be neutralized and bounded.** A `reason` string has no canonical shape
to check against, so it cannot be rejected the way an id is — it MUST instead have every control
character replaced (one glyph per character, so the bound below survives substitution) and MUST be
truncated to at most 200 characters. This covers the `reason` on every `dig.fetchRange` refusal and any
advisory `message` returned to a peer whose text derives from that peer's own bytes — notably the
malformed-DHT-frame reply, where the deserializer quotes the offending input back.

**Both guards MUST be enforced by the TYPE that holds the field, not at the log call site.** The record
structures MUST store the validated/neutralized wrappers, so a raw peer-supplied `&str`/`String` cannot be
placed in a log record however the record is constructed. Sanitizing where a value is REPORTED is not
sanitizing it: the next construction of the same record starts again from the raw value, and a test whose
fixture happens to use a benign id will not notice. A guard that depends on every future caller
remembering it is not a guard.

### 20.3. `control.log.setLevel` — runtime level control

`control.log.setLevel` (§7.4) live-swaps the process level filter via the `dig-logging` reload
handle (`dig-logging` SPEC §5). It is a gated `control.*` method (loopback + control-token or paired
token, §7.2), takes `params.filter` (an `EnvFilter` directive), applies immediately, and does NOT
persist. A missing/malformed directive is `INVALID_PARAMS`; a process without logging installed is
`CONTROL_ERROR`.

### 20.4. `dig-node logs …` verbs

The node mounts `dig-logging`'s shared subcommand verbatim as `dig-node logs …` (also `dign logs
…`), so `logs path`, `logs tail [-f] [-n N] [--level L] [--json]`, `logs level [<filter>]`, and
`logs bundle [-o out.zip] [--all] [--since <dur>]` behave identically to every DIG binary
(`dig-logging` SPEC §8.1). `logs level <filter>` PERSISTS the directive (effective on the next node
start) AND additionally live-applies it to a running node via `control.log.setLevel` (best-effort —
a node that is not running leaves the persisted level in place and reports it, never an error). `logs
bundle` writes a redacted zip safe to attach to a bug report (`dig-logging` SPEC §8.2).

### 20.5. Never-log at source (SPEC §7 of dig-logging)

No secret — a BIP39 mnemonic/seed, a wallet private key, the control token, a paired/session token,
a passphrase — is EVER passed to a `tracing` field or message, at any level. Bundle-time redaction
is only the second line of defence. The transport's per-request logging records ONLY the method name
and a correlation `op_id`, never the request `params` (which for a control/pairing call carry a
token); this is enforced by the request-logger's signature and a never-log regression test.

## 21. Reshare — the whole-`.dig`-module pull (a reader becomes a holder)

A node that reads content MUST be able to become a complete resharer of the capsule it read from. A
resource read fetches only the bytes requested, which leaves the reader faster but the network no
stronger: a `.dig` module is served WHOLE (every retrieval key, with proofs), so a node holding one
resource can serve nothing. The reshare leg pulls the entire module for the generation that was read, and
only then does the node become a holder — so each read leaves the content MORE available than it found it.

This closes the content-replication flywheel: `install -> connect -> discover -> read -> cache -> reshare`.

### 21.1. Wire surface (peer tier)

Two peer-reachable methods, both public-read (unsealed §5.4 exemption — the content is public-by-nature
and content-addressed):

- **`dig.getModuleInfo` `{store_id, root}` → `ModuleInfo`** — the transfer descriptor of a module the
  answering node HOLDS: `total_size`, `module_hash` (SHA-256 of the whole blob, 64-hex), and per-chunk
  `chunk_hashes` + `chunk_lens` in ascending order. `chunk_lens` MUST have the same length as
  `chunk_hashes` and MUST sum to `total_size`. A node that does not hold the module (including a 0-byte
  local file, which is not a module) MUST answer the `RESOURCE_UNAVAILABLE` error, never a descriptor.
- **`dig.fetchModuleRange` `{store_id, root, offset?, length}`** — a byte window of the module blob,
  answered as a STREAM of `RangeFrame`-shaped frames (`bytes` base64), `total_length` on the first frame
  only, terminated by a frame with `complete: true`. A server MUST send a terminating frame even for an
  empty window, or a caller waits forever. A server MAY answer at its own, narrower frame granularity; a
  caller MUST read until `complete`.

**Routing (normative).** `dig.fetchModuleRange` is dispatched by its METHOD NAME, not by request shape:
its response is a frame stream rather than one envelope, and its shape cannot express that. The client
half records the same contract (dig-peer SPEC §3.5), so the two cannot drift.

**Chunking.** The descriptor is one framed response inside the 64 KiB control-frame cap, and each chunk
costs descriptor bytes. A server therefore scales its chunk size with the module — at least 1 MiB, and
always large enough to keep the chunk count at or below 512 — so the descriptor is bounded BY
CONSTRUCTION and no capsule is made unpullable by a framing limit unrelated to its content. A single
`fetchModuleRange` window is clamped to 4 MiB, so one request never sizes the server's work.

### 21.2. The anchor verifier is the ONLY root of trust (MUST)

Every check before the anchor gate compares peer-supplied bytes against peer-supplied hashes. Those
checks prove SELF-CONSISTENCY, not authenticity: a holder that fabricates a module and describes it
correctly passes all of them. Whatever the anchor gate admits, the node then caches, SERVES, and
ANNOUNCES itself a holder of — so a weak gate makes an honest node an authoritative-looking source of
corrupt content network-wide. Therefore:

1. **The expected generation root MUST be resolved from the CHAIN, before any peer is contacted**, via
   the anchored-root resolver (`verify_pinned_root`, the bounded check). It MUST NOT be taken from, or
   influenced by, the peer that serves the module. If the anchor came from the serving peer, the entire
   fail-closed property is void.
2. **Comparisons MUST be over decoded 32-byte values, never hex text.** Hex is case-insensitive and
   length-forgiving in a way byte equality is not; a peer that influences either side of a TEXT
   comparison gets a bypass for free.
3. **An unparseable or 0-byte blob MUST be rejected explicitly.** Both hash gates pass TRIVIALLY for the
   empty module (SHA-256 of no bytes is a declarable `module_hash`), so the verifier is the only check.
4. **The module MUST commit the store and generation it claims to be.** Its embedded `StoreId` (data
   section 1) and `CurrentRoot` (section 2) MUST equal the store being pulled and the CHAIN's root. A
   section of the wrong width, or an absent one, MUST be rejected — never zero-extended or truncated
   into a comparison it could pass. A module committing a DIFFERENT real generation is a rollback
   primitive and MUST fail closed.
5. A verifier is bound to ONE generation and MUST refuse a pull of any other, so it can never be reused
   to check the wrong anchor.

The production verifier MUST NOT be, or be replaceable by, a fail-open one. dig-download's
`AcceptAnyModuleAnchor` exists only under its `testkit` feature; that feature MUST NOT be enabled on a
production dependency edge.

### 21.3. Becoming a holder — promote, then announce (MUST)

This node's DHT provider records are derived from its CACHE INVENTORY (§19), so the moment a module file
appears at `<cache>/modules/<store>/<root>.dig` this node is advertising itself network-wide as an
authoritative source of that capsule. The promotion ladder is therefore:

```
<downloads>/modules/<store>-<root>.dig.download.tmp   staging
<downloads>/modules/<store>-<root>.dig                verified, NOT yet a holder
<cache>/modules/<store>/<root>.dig                    CACHED == ANNOUNCED AS HOLDER
```

The cached artifact and the `.dig` it was staged from now share ONE extension end-to-end (#1896). A
reader MUST accept a legacy `<root>.module` cache a prior binary wrote — the availability answer, the
serve path, the held-check, and the inventory scan all treat `.dig` and `.module` as the same held
capsule — so an in-place upgrade never drops a holder. At bring-up, BEFORE its first inventory announce,
the node MUST run an idempotent, crash-safe pass that renames each legacy `<root>.module` to `<root>.dig`
(deleting the redundant `.module` where the `.dig` already exists), converging the cache onto the unified
artifact; reader-tolerance covers any file a partial run leaves behind. This is a CACHE-FILENAME
convergence only — it is NOT a change to the immutable `.dig` byte format (§5.1 does not apply).

- **A pull MUST stage OUTSIDE the cache**, so a partial or failed pull is never a candidate for
  announcement — there is no window in which a half-pulled capsule sits at the cache path.
- **The move into the cache MUST happen only on the pull returning success** — never on
  finalize-observed, never on partial staging, never after a failure.
- **Success MUST NOT be taken on faith.** Before the move, the artifact on disk MUST be re-hashed and
  compared against the digest of the bytes the anchor gate actually ADMITTED. Both sides of that
  comparison are then the node's own; a re-hash against the descriptor's `module_hash` would compare
  against a value the serving peer chose. A mismatch MUST abandon the promotion (never "repair" it) and
  MUST NOT announce.
- The move into the cache MUST be write-then-rename, so a reader never observes a partial module at the
  path whose existence is the holder claim.
- **The announce MUST reuse the node's one inventory-reconcile path** (§19), never a bespoke announce, so
  the reshare leg cannot advertise a content-id shape the rest of the node does not.
- A failed pull MUST leave no staging artifact behind that a later run could mistake for progress.
- **Abandoned staging MUST be reaped, and total staging MUST be bounded in bytes.** A pull whose process
  dies mid-flight cannot clean up after itself, so the node MUST sweep the capsule-staging directory
  (`<downloads>/modules`, a SUBDIRECTORY — a sweep of the parent directory alone does not reach it) on
  startup and on an interval, removing each staging file older than the staleness TTL together with its
  resume-state sidecar. Because a TTL bounds staging only by what one TTL window can accumulate, the node
  MUST additionally enforce a fixed BYTE ceiling, derived from the per-warm size cap times the
  concurrent-warm cap plus one generation of headroom — a ceiling below that product would evict healthy
  in-flight work.
  Reaping MUST be by age and ownership only, and its permitted scope is narrow BY DESIGN: it MUST NOT
  remove a staging file the node reports as live or paused-resumable (whatever its age), and it MUST NOT
  touch `<cache>/modules` — the operator's held capsules. Those two exclusions are what make oldest-first
  eviction acceptable here: everything in scope is re-fetchable download scratch, so a peer driving reads
  can at worst destroy incomplete partial pulls. Applied to CACHED content the same ordering would be a
  remote eviction primitive, letting a peer walk an operator's own oldest capsules off the disk simply by
  causing reads of others.

### 21.4. The warm is a background pull (MUST NOT slow the read)

The read that triggers a warm MUST NOT wait for it, and a failed warm MUST NOT fail that read: a
whole-capsule pull is orders of magnitude larger than the resource that revealed the capsule, and the
read's latency is user-facing. Serving a module range is paced by the SAME FCFS outbound limiter
`dig.fetchRange` uses (§17) — a whole-capsule pull is the largest thing a node serves, so exempting it
would leave the biggest transfer as the one path able to starve every other peer.

A single read triggers AT MOST ONE whole-capsule acquisition for a `(store, root)` generation, regardless
of tier. Two transports can pull the SAME capsule down — the §21 authenticated whole-store backfill
(`maybe_backfill_capsule` → `gap_fill_generation`, the peerless-network fallback that acquires from the
RPC upstream when no peer serves) and the §21.3 P2P reshare warm — and they are two routes to the same
artifact, so they claim ONE shared single-flight gate keyed `(store, root)`. Whichever leg claims the key
first runs the pull; the other, and any further read of the same not-yet-held capsule, is refused. A
burst of reads across a capsule's resources therefore cannot start N concurrent pulls of the same module,
and the two legs cannot double-pull it between them. The shared gate ALSO bounds how many DISTINCT
generations may acquire concurrently (a fixed cap across BOTH legs, not each in isolation): claims beyond
the cap are SKIPPED, not queued — the next read simply tries again. A store-granularity read starts no
warm: it does not name WHICH generation to pull, and guessing would reshare a capsule nobody asked for.

### 21.5. Dial path (MUST)

A module dial MUST resolve candidate addresses through the shared candidate resolver — IPv6 first, then
IPv4 (§5.2), each socket CONSTRUCTED from a parsed IP rather than a formatted string — and MUST try every
candidate in order before reporting failure, so one unusable IPv6 candidate cannot mask a working IPv4
one. Building a socket address by formatting host and port into a string and reparsing it is FORBIDDEN:
it is invalid for every IPv6 literal, whose grammar requires brackets. The live connected pool is
consulted before DHT hints (a connection-verified address before an untrusted advertisement), and a DHT
failure MUST NOT discard a pool address.

A failure reason MUST NOT embed peer-supplied text; ids reaching a log MUST go through the serve log's
sentinel (§19).

### 21.6. Serve observability

Both module methods emit the §19 serve vocabulary: an INFO outcome line per request (`described` /
`not-held` for the descriptor; `served` with byte + frame counts, or `not-held`, for a range) plus DEBUG
detail. Every id is rendered through the serve log's sentinel, so a peer can neither bloat a log line nor
forge a record. No module bytes are ever logged.

### 21.7. Only the operator's own read may effect the network (MUST)

A read can trigger background legs that spend this node's bandwidth and disk and change what it
advertises network-wide: the whole-capsule warm (`maybe_backfill_capsule`, §21.4) and the reshare pull
plus holder-announce (§21.3). Those legs MUST be reachable only from a read this node's OWN OPERATOR
made. A read that arrived from the network is SERVED normally and effects NOTHING: it starts no warm, no
reshare, no promotion, and no announce. These two legs share ONE single-flight acquisition gate (§21.4),
so the origin/config/held gates on EACH leg run BEFORE it can claim that gate — a gated-out read never
consumes a slot, and the two legs dedup against each other rather than each pulling the capsule.

The rule is not optional hardening. Every peer-facing read surface is unauthenticated in the sense that
matters here — any well-formed self-signed mTLS leaf is accepted (§13), and the plaintext `/s/` surface
carries no token at all — so an ungated leg lets a stranger name a capsule and have this node pull it,
cache it, evict the operator's own content to make room, and then advertise itself as an authoritative
holder of the stranger's choosing, at a cost to the stranger of a few hundred bytes.

Therefore:

1. **Every read carries a read-origin label**, and only a `Local` label may reach a network-effecting
   leg. The label MUST be threaded from the surface that accepted the request down to the leg — a
   function that starts a warm or a reshare MUST take the label as a parameter and MUST NOT assert one.
2. **The label MUST be DERIVED from the accepting connection's real remote address** (loopback ⇒ `Local`,
   anything else ⇒ `Peer`), and from nothing else. Deriving it from the identity of the endpoint or the
   handler is FORBIDDEN, because "this handler is the loopback server" is not a fact: the operator-facing
   `DIG_NODE_HOST` override replaces the loopback bind with any address, and the whole router — the
   JSON-RPC plane, `GET /s/*path`, and the router fallback alike — is served on every listener. The
   Host-header allowlist (§4.2) is a DNS-rebinding defense and MUST NOT be read as an origin check: a
   remote client can send `Host: localhost`.
3. **The derivation MUST fail closed.** A request from which the remote address cannot be recovered MUST
   be rejected, never defaulted to `Local`. An IPv4-mapped IPv6 address MUST NOT satisfy the loopback
   test (IPv6 loopback is `::1` alone), so a remote peer cannot forge a `Local` label by address family.
4. **The operator's off switch still wins.** `DIG_NODE_BACKFILL_ON_MISS=off` refuses these legs even for
   a `Local` read; the origin gate narrows them further and never re-enables them.

The peer-tier read (`dig.fetchRange` / `dig.getContent` on the peer wire) and the local plaintext serve
(`GET /s/…`, and the root-absolute reroot that shares its path) are BOTH subject to this rule — the
serve path reaches the same legs through its P2P tier, so gating one door and not the other leaves the
property unheld.

### 21.8. Landing has a SECOND axis — request provenance (MUST)

A loopback remote address proves the CONNECTION is local; it does NOT prove the OPERATOR authorized the
request. A browser running an attacker's page can issue a cross-site `GET dig.local/s/<capsule>`: the
address is loopback, so §21.7 alone would label the read `Local` and let the attacker's chosen capsule
LAND (warm + reshare + holder-announce). The read itself is harmless — the bytes are public — but the
durable holder side effect is a remotely-triggerable amplification.

Landing therefore gates on BOTH axes:

1. **Every browser-reachable read surface derives a request-provenance label from the `Sec-Fetch-Site`
   request header**, orthogonal to the §21.7 read-origin label. This covers BOTH the `/s/` plaintext
   serve surface AND the `POST /` JSON-RPC read methods (`dig.getContent`, `dig.fetchRange`), whose
   miss-path landing legs (the implicit warm/backfill/reshare fired when the resource is not held
   locally) would otherwise let a SAME-ORIGIN capsule page `POST dig.getContent` and drive landing —
   the loopback address labels it `Local`, so §21.7 alone permits it. ONLY an explicit, case-insensitive
   `cross-site` value is `CrossSite`; `same-origin`, `same-site`, `none`, an unknown value, AND an ABSENT
   header are all `FirstParty`. Absence MUST map to `FirstParty` — non-browser clients (the CLI, the SDK)
   send no `Sec-Fetch-*` header, and treating absence as cross-site would silently stop every CLI/SDK
   read from landing.
2. **A read lands only when it is BOTH `Local` (§21.7) AND `FirstParty`.** A `CrossSite` request collapses
   its landing origin to `Peer`: the bytes are served identically, but no warm, reshare, promotion, or
   announce fires. The READ MUST NEVER be blocked, throttled, or altered by provenance — only the side
   effect is suppressed.
3. **The collapse is applied ONCE per landing site via the shared `landing_origin(origin, provenance)`
   fold**, and the collapsed `land_origin` flows to the landing legs; the leaf gates (§21.7) are
   unchanged. On the `/s/` path the fold is applied at the serve seam; on the `POST /` JSON-RPC path it
   is applied at the top of each read handler and the collapsed origin replaces the raw origin at every
   landing site (`content_miss_envelope`/`range_miss_envelope` → the reshare chain, AND
   `maybe_backfill_capsule`) — the raw read-origin is used everywhere else. Each transport threads the
   provenance EXPLICITLY through `handle_rpc`/`dispatch` (a required argument, never inferred): the
   browser-facing HTTP POST classifies the header, every trusted/non-browser caller (the control
   surface, the in-process FFI, the peer-RPC server) passes `FirstParty`. This axis applies only to
   browser-reachable HTTP surfaces; the peer wire remains gated by §21.7's read-origin alone
   (`landing_origin(Peer, FirstParty) == Peer`, so a peer read still never lands). It complements §21.9's
   token-gate on the EXPLICIT `cache.fetchAndCache` landing method.

Honest residuals: a browser predating `Sec-Fetch-Site` (all current major browsers send it) presents no
header and is treated as first-party; and a same-origin store-to-store request within a shared serving
origin is first-party by construction. These are accepted — the axis closes the cross-site CSRF door,
not every conceivable same-origin confusion.

### 21.9. The `cache.fetchAndCache` HTTP surface is token-gated (MUST)

`cache.fetchAndCache` explicitly makes this node fetch, cache, and DHT-announce a capsule of the
CALLER'S naming — the §21.3 holder side effect on demand. Over the HTTP `POST /` surface a loopback
address does not prove operator intent (a cross-site page can POST to `dig.local`), so the method MUST
require the local control token (the `X-Dig-Control-Token` header or `params._control_token`) OR a valid
paired controller token, exactly like a `control.*` method; an unauthorized call is rejected
`UNAUTHORIZED` (-32030) before any landing work. The in-process FFI `cache.*` path is the operator's own
process and MUST stay open — it never traverses this HTTP handler. Anonymous public CONTENT reads remain
ungated.

The same HTTP token-gate MUST also bind `cache.pushCapsule` (§5.5.3, the same holder side effect) and
`cache.listCached` (#2108). `cache.listCached` is a READ, but a HOLDINGS-revealing one: it enumerates the
operator's full cached-capsule inventory (`storeId:rootHash`, sizes, LRU order), which deanonymizes what
content the user has consumed. Over the loopback HTTP surface a cross-site page (DNS-rebinding /
local-service attack) could otherwise POST here and read it, so `cache.listCached` MUST require the same
control/paired token and is rejected `UNAUTHORIZED` (-32030) with no inventory in the body when
unauthorized. The FFI path stays open, and `cache.*` is not routable over the `/ws` transport (the
wallet-backend fall-through has no `cache.*` arm), so the HTTP gate is the only reachable surface.

### 21.10. Reverse-proxy trust caveat (informative)

The `Local` label trusts the loopback boundary. Behind a loopback-terminating reverse proxy every remote
client appears to the node as a `Local` connection; `X-Forwarded-For` is explicitly NOT trusted for the
origin label (a remote client can forge it). An operator who deliberately fronts the node with a proxy
would need a future explicit trusted-proxy configuration — an allowlist of proxy addresses plus an
authenticated proxy-supplied client-address header — before any forwarded address could be believed. No
such configuration exists today; running the node behind an untrusted-header proxy forfeits the origin
gate.