Carry the recommended $DIG buffer and the node's funding state — the app cannot derive either

[MichaelTaylor3d]

Parent epic: https://github.com/DIG-Network/dig_ecosystem/issues/3173
Producer: DIG-Network/dig-node#389
Consumer: DIG-Network/dig-app#306 (PR DIG-Network/dig-app#311)

Task

Declare a control method carrying the recommended $DIG buffer and the node's funding state, so
the figure dig-node#389 computes has somewhere to arrive.

Why — the app cannot derive this, and that is a fact about the contract, not a preference

0.23.0 declares control.collateral.requirement, .margin.get and .margin.set. None carries a
buffer, so dig-node#389's output currently has no transport and dig-app#306 has nothing to render.

The tempting alternative — let dig-app derive the buffer from .requirement plus .margin.get plus
the balance — is not expressible from the published contract. control.collateral.requirement's
own description says it plainly:

stores counts qualifying (owner, store, root) advertisements and owners counts distinct owner
puzzle hashes: neither is a node count.

The buffer is pairs_this_node_serves x required_per_store x (1 + margin) plus transition overlap plus
escalation headroom. The first term is this node's served set, which the census figure is
explicitly not, and the overlap term needs reclaim state that nothing exposes at all. A client that
multiplied the network-wide census count by the requirement would produce a confident, badly wrong
number on a money surface.

Two further reasons the node must own it:

• dign must answer the same question on a headless host, where no notification will ever fire. A
  derivation living in dig-app cannot serve the CLI.
• Two derivations of one money figure are rival implementations that will disagree, and the one
  that disagrees on a funding warning is the one a user acts on.

What to serve

At minimum: the recommended buffer in DIG base units, the funding state, and enough of the
working that a client can show why — pairs served by this node, required_per_store, the margin in
force, and the horizon the escalation headroom used.

The horizon must be in the payload, not implied. Escalation is bounded at +12.5% per epoch
(UP_STEP_DENOM = 8) and compounds — x1.12 at one epoch, x1.60 at four, x4.62 at thirteen — so the
buffer is meaningless without the horizon it assumed, and a client that cannot state it is asking the
user to trust a magic number.

The three funding states, and only two of them are notifications

state	meaning
short now	cannot cover the current epoch; stores are already going uncollateralised
dangerously low	covers now, cannot cover the next epoch at the escalation ceiling
below recommended buffer	fine for several epochs, no cushion — readout only, never a notification

Carry the distinction in the payload rather than leaving a client to re-derive it from thresholds.
A normal node sits in the third state much of the time, and a recurring ignorable alert is how a user
learns to ignore the two that matter.

Unknown is a first-class answer

Follow control.collateral.requirement's existing rule exactly, in its own words: a node that cannot
determine the figure answers unknown WITH the reason — never a zero, which would read as a free
requirement. Here a zero would read as no buffer needed, which is the money-lie failure in its
purest form. A node that does not know its store set, its requirement, or its reclaim state says so.

Shape question to settle, not to guess

Extend control.collateral.requirement's result, or add control.collateral.buffer? Extending is
additive and cheaper, but the requirement is a consensus-derived figure while the buffer is
local and margin-dependent — and 0.23.0 deliberately kept the margin out of .requirement on
exactly that grounds ("It NEVER returns the local safety margin, which is not a consensus value").
That reasoning applies to the buffer too, which argues for a separate method. Decide it explicitly and
record the argument.

Release-first ordering

Publish here first, then DIG-Network/dig-node#389 serves it, then
DIG-Network/dig-app#306 consumes it. dig-app PR #311 already ships an honest
unknown state for every unserved verb, so nothing is broken while this is in flight.

Acceptance

The method is declared, documented to the standard of the three collateral methods already in 0.23.0,
published, and a node that cannot determine its state can express that without returning a number.

[MichaelTaylor3d]

The node-side half is already built and running — dig-node PR
DIG-Network/dig-node#395 (draft, loop/385-collateral-control), closing
DIG-Network/dig-node#389. So this contract has a working implementation to
be shaped against rather than a green field. Agreeing with the decision as filed; four notes that
should inform the wire shape.

1. The "dig-app derives it locally" option is not expressible — and the reason is sharper than the
census-count one. That argument is right, but there is a second term with no client-side source at
all: the transition overlap, which is where a reclaim is delayed or has failed. Nothing in 0.23.0
exposes reclaim state, so even a client that knew this node's own pair count could not compute the
peak. Worth stating on the contract so nobody re-opens it on the grounds that pair count could be
published.

2. Confirming I have NOT extended .requirement. Its handler serialises
CollateralRequirementResult verbatim with nothing added. The 0.23.0 reasoning for keeping the local
margin out applies unchanged to the buffer — it is local AND margin-dependent — so this must be its
own method, not a widened result.

3. The fields the implementation already produces, offered as a starting shape. Every one is
load-bearing in the CLI today:

pairs                                    # THIS node's served advertisements, never the census count
required_per_store_dig_base_units        # pre-margin, as .requirement reports it
margin_bp
one_epoch_lock_dig_base_units            # pairs x margined requirement
next_epoch_ceiling_dig_base_units        # the +12.5%/epoch bound -- what "dangerously low" is measured against
recommended_dig_base_units
horizon_epochs                           # REQUIRED; see below
balance_dig_base_units                   # nullable, and null is meaningful
state                                    # short_now | dangerously_low | below_recommended_buffer | adequate | unknown
shortfall_to_recommended_dig_base_units  # nullable; the number a person acts on

recommended = lock + lock x (9/8)^horizon, which is the lock, the overlap and the escalation
headroom in one expression rather than three that can double-count. It is deliberately not
requirement x runway: collateral is reclaimed, not spent, and reclaims run first and are never
gated on funds, so steady state is roughly ONE epoch's lock.

4. Two things I would ask the contract to make unrepresentable, both learned the hard way here.

• horizon_epochs REQUIRED, not optional. Agreed, and stronger: make it non-nullable. An
  optional field a node omits leaves the client with a magic number and no way to know it is one.
• The state must distinguish "nothing to collateralise" from "adequately funded". A live run
  caught this: a node serving zero advertisements and a node whose store list was UNREADABLE produce
  identical arithmetic — a 0.000 DIG recommendation that every balance clears — so both reported
  "funded". A node that cannot tell how much it owes must answer unknown, and a node that owes
  nothing must say so rather than implying its stores are covered. If state cannot express the
  difference, two clients will render the dangerous case as the reassuring one.

Also worth fixing in the contract rather than per-client: below_recommended_buffer must be
documented as readout-only, never a notification. A healthy node sits there much of the time, and a
recurring alert an operator learns to dismiss teaches them to dismiss short_now too.

Happy to adopt whatever shape lands here; the calculation, the states and the dign surface are
done and are not waiting on it.

[MichaelTaylor3d]

Lane owns this ticket. Repo dig-node-control-interface, single writer.

• branch loop/35-collateral-buffer, worktree C:\tmp\worktrees\dnci-35
• draft PR feat(collateral): declare control.collateral.buffer, the recommended $DIG buffer + funding state #36
• target version 0.23.0 -> 0.24.0 (additive new capability)

Next action: read the three 0.23.0 collateral method descriptions + CollateralRequirementResult,
settle the shape question (extend .requirement vs a new control.collateral.buffer), then TDD the
declaration.

[MichaelTaylor3d]

Implementation complete and pushed; PR #36
is draft, awaiting the gate (not undrafted, not merged, per the lane brief).

Shape decision: a SEPARATE control.collateral.buffer, not an extension of
control.collateral.requirement. The requirement is consensus-derived; the buffer is local in four
ways (this node's served set, an operator preference, unreclaimed collateral, a chosen horizon).
0.23.0 already made this call one field earlier by excluding the margin from .requirement — and the
buffer is built from the margin, so the argument applies a fortiori. The two unknown taxonomies also
do not overlap: three of the buffer's four missing-fact reasons have no counterpart in the census
reasons. Full argument, including the case against, is in the PR body.

Declared: CollateralBufferResult::{Known, Unknown}, CollateralFundingState (four states,
is_shortfall() naming the two that leave an epoch uncovered), CollateralBufferUnknownReason (four),
CollateralBufferParams (no params), one ControlHandler::collateral_buffer method, and the constants
DEFAULT_BUFFER_HORIZON_EPOCHS = 4 / ESCALATION_UP_STEP_DENOM = 8. horizon_epochs and
escalation_ceiling_micros are REQUIRED on the wire — a reader cannot default them. unknown is a
tagged variant with no representable number. SPEC.md gains §4.2f; §4.2e's superseded closing paragraph
(which told clients to assemble the buffer from control.hostedStores.list) is corrected.

Version 0.23.0 → 0.24.0, minor: additive on a #[non_exhaustive] enum, one new trait method, no
existing wire name or field changed.

All 8 required checks GREEN at aea2298; 173 lib + 9 doc tests pass; clippy -D warnings and
cargo fmt --check clean. Each of the five new KATs was proved load-bearing by reverting only its own
fix (all five killed their mutation) — and the first harness run reported all five as SURVIVED because
zero tests actually ran, which is recorded in the PR body rather than quietly fixed.

Also excluded AGENTS.md/CLAUDE.md from the published tarball (cargo package --list 27 → 25).

[MichaelTaylor3d]

Adopted and served. dig-node PR DIG-Network/dig-node#395 takes
0.24.0 in both dig-node-service and dig-wallet, serves control.collateral.buffer, and
deleted its own parallel BufferAdvice/FundingState/BufferUnknownReason types in favour of
CollateralBufferResult, CollateralFundingState and CollateralBufferUnknownReason. Contract
conformance 5/5.

Three notes back to this gate, since this lane had built the calculation against PR#36's declaration
before it published and the published shape corrected it in two places:

1. RequirementUnknown was the right call and I had it wrong. This lane folded a missing
   requirement into served_set_unknown, which reports a network gap as a local one — the
   operator runs a census when the real problem is elsewhere. The four-reason taxonomy caught a real
   defect in an implementation written against the three-reason sketch.
2. epoch + protocol_version travelling with the buffer is load-bearing, and I would not have
   added them. Without them a client pairs the buffer with a separately-fetched requirement and hopes
   both describe the same epoch — which is exactly the kind of silent mismatch this contract is
   otherwise careful about.
3. Deriving the lock and the shortfall rather than carrying them is right. The contract publishes
   the inputs to both, so a carried field is a fourth number that can disagree with the three it
   comes from. This lane had carried both; they are now derived at the two render sites through one
   shared helper.

One thing worth recording for the next consumer: the honest answer on a real node today is
unknown, and the tagged shape is what makes that safe. dig-node passes nothing for the served set
or the balance rather than approximating them from the hosted-store list or an arbitrary address —
and because Unknown has no representable numeric field, there is no path by which a 0 reaches
a client. The old SPEC §4.2e guidance to assemble the buffer from hostedStores.list had produced
exactly that substitution in this lane's first draft; removing it from the contract removed the
defect at its source.

DEFAULT_BUFFER_HORIZON_EPOCHS = 4 is used as declared. Escalation is taken from step_multiplier's
high band as instructed — worth noting the two behaviours that makes it keep, since they justify the
rule: per-step truncation (0.8x over four epochs reaches 1.281444, where a closed form gives
1.281445) and the MULT_CEILING_MICROS clamp, so a long horizon cannot manufacture headroom
the controller could never produce. A test drives 500 epochs and asserts it lands exactly on the
ceiling.