The reservation cap bounds continuous hold, not aggregate hold: a pruned row re-anchors on the next re-push

[MichaelTaylor3d]

Task

The coin-reservation cap added in #505 bounds continuous
hold, not aggregate hold. Decide whether that is the behaviour we want, and either implement the
aggregate bound or record the decision to accept the current one.

Context

prune_reservations DELETEs the pending_transactions row when expires_at <= now
(crates/dig-wallet/src/sage/db.rs). submitted_at -- the anchor the cap is computed from -- lives on
that row and nowhere else. So once the cap fires and the row is pruned, the next re-push of the same
bundle re-INSERTs with submitted_at = now and gets a fresh MAX_RESERVATION_HOLD_MS.

The result is a sawtooth: hold for an hour, free, hold for another hour. A caller retrying tightly
therefore holds its inputs for all but a narrow window each hour, indefinitely. #502's acceptance bar
is met -- the coins genuinely do return to selection -- but "bounded total hold" is true only per row.

Found by the adversarial gate on PR #505 (R2) and independently by the correctness gate (finding 5),
which is why it is filed rather than argued about. PR #505 pins the behaviour with a test and states it
in the MAX_RESERVATION_HOLD_MS doc, so it is known and measured, not a surprise.

The fork, which is why this is a ticket and not a fix

Bounding aggregate hold means REMEMBERING that a given bundle already had its hour -- a tombstone, or
retaining the row past expiry with the reservation released. Either way the consequence is that the
wallet permanently declines to protect that bundle's inputs, even though the bundle may still be in
a mempool and may still land. That is the double-spend direction, and it is the direction
#348 and
#497 both deliberately closed.

So this is a genuine trade-off between the two failure modes, not a defect with an obvious fix, and it
was out of scope for #502's "smallest thing that works".

Worth weighing when deciding:

• How a bundle that has failed for an hour differs, if at all, from one pushed for the first time --
  from the DB's point of view they are identical, and that is exactly the question.
• Whether a retention window (remember for N hours, then forget) is the honest middle, and what N is
  anchored to. Chia block time is ~18.75 s, so an hour is already ~190 blocks.
• Whether the right surface is a bound at all rather than an operator-visible signal that a bundle has
  been re-pushed past its cap -- a caller looping forever on a dead bundle is a bug worth reporting, not
  only worth absorbing.

Scope

The deliverable is the DECISION plus whichever of these it selects:

• implement the aggregate bound (with the retention/GC story stated), or
• close this as accepted behaviour with the reasoning recorded on the ticket and the SPEC.md §18.9a
  clause worded to say the bound is per-row.

Either outcome closes it. Do not leave it open as a standing observation.

Evidence

Read against dig-node PR #505 head. prune_reservations' DELETE and the absence of submitted_at
from the upsert's DO UPDATE SET are the two facts the sawtooth follows from; both are directly
readable in crates/dig-wallet/src/sage/db.rs. Not fired against a live repushing caller.

Cross-reference

Parent behaviour this came out of: #502 ·
#505 ·
prior art on the failure direction: #348 ·
#497

[MichaelTaylor3d]

Verdict: ACCEPT the per-row bound. No second fix. The deliverable is already written on PR #505.

Decided 2026-09-02 against origin/main (0.252.4) and PR #505 head fce2358 (0.256.0). No code was
written for this ticket, deliberately, and the reason is below.

1. The premise exists only on #505's branch

On origin/main there is no sawtooth, because there is no tooth. reserve_spend's upsert is still
ON CONFLICT(transaction_id) DO UPDATE SET expires_at = excluded.expires_at
(crates/dig-wallet/src/sage/db.rs:2769-2772) with no cap of any kind, so the hold is indefinite and
never releases at all -- that is #502, unfixed. The one-hour cap this ticket refines does not exist
outside loop/502-reservation-total-hold.

So this is not a defect that can be fixed against main. Implementing an aggregate bound here would
mean building the refinement of a cap before the cap, in a second PR, editing the same
reserve_spend SQL that #505 is actively rewriting. That is a rival implementation by construction.

2. Outcome (b) is already implemented, in the commit that came 22 minutes after this ticket

This ticket offers two closing outcomes. The second -- "close as accepted behaviour with the
reasoning recorded and the SPEC.md §18.9a clause worded to say the bound is per-row" -- is done, on
fce2358 (2026-09-02T15:08:49Z). This ticket was filed at 14:46:43Z. The #505 lane read it and
answered it in place:

• SPEC.md gained the per-row clause verbatim: "This bound is on CONTINUOUS hold. Once the
  deadline passes, the reservation and its coin claims are released and the inputs become selectable
  again; a subsequent push of the same transaction is a new reservation with a new anchor and MAY
  hold the inputs for a further full period. A node MUST NOT refuse to re-hold a transaction on the
  grounds that it has already held one..." The clause is present in fce2358 and absent from all
  four earlier commits on the branch (grep pattern control-tested against a known hit in the same
  file).
• MAX_RESERVATION_HOLD_MS's doc (crates/dig-wallet/src/sage/rpc.rs) carries the sawtooth as
  named limitation 1 of 3, with the reasoning and the pinning test named.
• a_repushed_bundle_gets_a_fresh_anchor_after_the_cap_prunes_its_row
  (crates/dig-wallet/src/sage/db.rs:6699) pins it, non-vacuously: it drives a second push to
  first + 100 * TTL, asserts the clamp binds at the cap, prunes at the cap, asserts the coin is
  back in unreserved_unspent_coins, then asserts the fresh row's submitted_at, attempts == 1
  and expires_at. It would fail if the re-push resurrected the old anchor.

3. Why ACCEPT is right on the merits, verified independently rather than inherited from #505

The release is real, not nominal. coin_reservations.transaction_id REFERENCES pending_transactions(transaction_id) ON DELETE CASCADE (db.rs:568) with foreign_keys(true) on
both the file pool (db.rs:911) and in-memory (db.rs:918), so pruning the parent cascade-deletes
the coin claims.

The release is observable to a selector. Every reader of reserved_coin_ids prunes first --
rpc.rs:829, 847, 2828, 3095, 3562 -- and unreserved_unspent_coins (db.rs:3057) filters on that
set.

The cap bites regardless of retry cadence, which is the property an aggregate bound would have to
disprove. Past the cap the upsert computes
MAX(existing, MIN(now + TTL, submitted_at + MAX_RESERVATION_HOLD_MS)). Since
submitted_at + CAP <= now past the cap, MIN yields the cap and MAX returns it unchanged, so
expires_at stays <= now and the row stays prunable however tightly the caller retries. A re-push
cannot resurrect an expired-but-unpruned row.

4. Which way each version errs

	direction it errs
origin/main today	LOCKOUT. Unbounded hold; the user's own coins are stranded with no recovery path. RESERVATION_TTL_MS's own doc names this the worse of the two.
PR #505	Neither. A bounded one-hour sawtooth with a genuine cascade-backed release at each tooth. It never refuses to re-protect a bundle.
The aggregate bound (option a)	DOUBLE-SPEND. It requires remembering that a bundle already had its hour -- a tombstone, or a retained row -- which means permanently declining to protect the inputs of a bundle that may still sit in a mempool and may still land.

That third row is the direction #348 and #497 closed on purpose. Building option (a) would quietly
undo #497, and this ticket's own text says so. The one-hour sawtooth is the honest middle already:
the coins are genuinely selectable at each release, and the caller pays a fresh hour only by
continuing to transmit a bundle it still believes in.

The third surface this ticket floats -- an operator-visible signal that a bundle has been re-pushed
past its cap -- is a real and better idea than a bound, but it is additive, it is not needed to close
the trade-off, and attempts (incremented, never read) is the natural place for it. Recorded here as
a comment rather than opened as a ticket, per the inflow rule.

5. Disposition

Closes when #505 merges. #505 is a dig-node PR and this is a dig-node issue, so Closes #511 in its
body will autoclose it -- recommended to the orchestrator sequencing #505 rather than applied here,
because #505 is a live lane and its body is not mine to edit.

Nothing further is owed on this ticket. It is not left as a standing observation: the decision is
made, the reasoning is on the record here, and the normative wording is in the diff that will carry
it.

[MichaelTaylor3d]

Accepted as designed, with the reasoning recorded — closing via #505 (dig-node PR #505).

This ticket reports that the reservation cap bounds CONTINUOUS hold rather than AGGREGATE hold. That is accurate, and it is the intended shape rather than an oversight. Recording why here rather than only in the PR body, so the decision is findable from the ticket.

The premise exists only on the #502 branch. On origin/main, reserve_spend is still a bare expires_at = excluded.expires_at (crates/dig-wallet/src/sage/db.rs), so today there is no cap at all and no sawtooth to refine — the hold is simply unbounded. #505 introduces the cap that this ticket then characterises.

An aggregate bound was considered and rejected on the merits. Bounding total hold across a bundle's whole life requires remembering bundles whose rows have already been pruned — a tombstone. A node holding that tombstone would permanently decline to re-protect a bundle it had already held for an hour, even though that bundle may still be admitted to a mempool. That converts a bounded lockout into a permanent refusal to protect, which is the double-select direction #497 deliberately chose against.

What the sawtooth actually costs. At the cap, prune_reservations DELETEs the pending_transactions row, coin_reservations cascades via ON DELETE CASCADE, and the coins genuinely return to unreserved_unspent_coins. At each release the inputs were really selectable again, so a subsequent push is a new spend attempt rather than a continuation of the old one, and giving it a fresh anchor is the honest reading.

It is now normative rather than folklore. SPEC.md §18.9a states the bound and then states its scope explicitly:

This bound is on CONTINUOUS hold. Once the deadline passes, the reservation and its coin claims are released and the inputs become selectable again; a subsequent push of the same transaction is a new reservation with a new anchor and MAY hold the inputs for a further full period.

The three limitations of the bound — the sawtooth, a timelocked bundle whose maturity is later than the cap, and a re-push near the cap buying less than a full TTL — are each enumerated on MAX_RESERVATION_HOLD_MS' own doc-comment, so the next reader is not left to rediscover them.

Reopen if the sawtooth turns out to be drivable by a party other than the coin owner; that would make it a denial primitive rather than an accepted trade-off, and it would be a different defect from the one described here.