dign: safety-margin setting with presets, shown with its real cost

[MichaelTaylor3d]

Task

Surface the collateral safety margin in the dign CLI and the DIG App, with its real cost.

Parent epic: https://github.com/DIG-Network/dig_ecosystem/issues/3173

The setting

Default +1%, presets 0.01% / 1% / 5%, persisted, and settable from both surfaces.

User's stated reasoning: under-collateralising means "they will likely be skipped for rewards that
epoch"; over-collateralising has "no penalty… just opportunity cost to use that DIG elsewhere". The
failure is asymmetric, which is why the default errs high.

Two properties that must hold in the implementation

1. The margin is LOCAL, never consensus. It changes what this node locks; it never changes what the
   network requires. Nothing about it enters the census, the controller, or any value another node
   derives. A margin that leaked into a consensus input would fork the network.
2. Apply it to the already-derived integer requirement, and round UP. A margin that rounds down can
   leave a node one mojo short — which is precisely the failure the default exists to prevent, arriving
   through the mechanism meant to avoid it.

Show the cost, not just the percentage

A percentage alone does not tell an operator anything actionable. Show what the margin costs at the
current requirement and the node's current store count — the actual extra DIG locked. The whole point
of the setting is choosing between safety and opportunity cost, and that choice cannot be made from a
bare "5%".

Honesty requirements

• Never imply the margin guarantees inclusion. It reduces the chance of falling short if the
  requirement moves; it is not a promise. The requirement is derived per epoch and can rise.
• If the node cannot currently determine the requirement, say so rather than showing a computed cost
  based on a stale or assumed value. Unknown is a state; a confident wrong number is not.
• The app surface follows §6.1/§6.4 — the four async states, externalised copy, and the professional-ui
  pass. The CLI keeps --json machine output (§6.2).

Method

The dign and dig-app halves are different repos and are separate lanes; keep the persisted
representation and the preset values identical across both — a margin that means 1% in one surface and
something else in the other is a drift bug on a money path.

§2.6 governs: the thinnest path to an operator changing the setting and seeing the cost.

[MichaelTaylor3d]

Parent epic: https://github.com/DIG-Network/dig_ecosystem/issues/3173

The normative specification is the decider's comment on that epic — 16 sections, every constant, every integer expression, every rounding mode, plus a worked 10-epoch table that is the golden-vector seed. Its arithmetic was independently re-verified before these children were filed.

Two rules bind every child: no floating point anywhere in the consensus path (one ULP of divergence in the multiplier propagates into every later epoch and forks the network), and chain-only inputs — no DHT, no wall-clock, no local state, because every node has a different view of those.

[MichaelTaylor3d]

Scope sharpened by a user directive: this is now the SOLE home of the safety margin, not one of two.

"the mirror coin flywheel itself is headless and needs to be in the headless node"

dig-app#301 merged with its own local copy at AgentConfig.collateral.margin_bp. That was the wrong side of the boundary — the node spends, so the node must own the number it spends by — and a headless install with no GUI otherwise has no way to set it. Two independent copies would also drift, and a user seeing 5% in the app while the node locks 1% is the money-lie class.

So: dign holds the setting and the CLI verb; dig-app becomes a remote control for it over the control plane and keeps no local copy (tracked as DIG-Network/dig-app#302).

Keep the representation exactly as merged — u64 basis points, margin_bp, 100 = +1%. That was decided correctly because it is the unit dig_mirror_collateral::apply_safety_margin takes; only its home moves. dig-app SPEC.md §3.7b records it normatively.

The control-plane method for get/set belongs with DIG-Network/dig-node-control-interface#32, which already exists because nothing serves the epoch requirement. One catalog PR carrying both, not two.

[MichaelTaylor3d]

Landed on loop/385-collateral-control, draft PR #395.
Awaiting the gate.

dign collateral margin [set <tight|default|generous|BP>]

Real output from a node built on this branch:

$ dign collateral margin
safety margin 100 bp (default) = +1.00% over the per-store requirement

$ dign collateral margin set 1
safety margin 1 bp (tight) = +0.01% over the per-store requirement

$ dign collateral margin set 10001
error: dig-node: margin_bp must be at most 10000 basis points (+100%); got 10001

$ dign collateral margin            # the refusal changed nothing
safety margin 1 bp (tight) = +0.01% over the per-store requirement

$ dign collateral margin set genrous
error: "genrous" is not a preset (tight, default, generous) nor a basis-point number

Shown with its real cost, as asked: a margin alone is a number of basis points, and beside the
percentage it adds it is a decision. dign collateral buffer (dig-node#389) then shows what it
costs in DIG against the actual served advertisements.

Four things worth recording:

• A preset resolves to dig-mirror-collateral's own constant, never a number spelled out in the
  CLI. A second spelling of "generous" is how two surfaces come to post different amounts for one
  choice an operator believes they made once.
• A typo is refused, not silently taken as the default — falling through would change what the
  node posts without saying so.
• 1 bp renders as +0.01%, not rounded away to zero. Basis points are the stored unit; percent is
  display only.
• Over the ceiling is refused rather than clamped, and .set returns what was actually stored,
  so the caller's intent and the node's behaviour cannot disagree on the money path.