design: milestone revocation — decided, no revocation

[jayteemoney]

Closes #17. First of Track A (#34).

Decision: a met milestone cannot be revoked. Milestone state is monotonic and Met is terminal.

The deciding argument is arithmetic, not preference

The intuitive option — revocation re-locks the tranche, prior withdrawals stand — sounds fair and isn't. Run it against the worked example, with the approver revoking at day 19:

Day	streamed_total	held	claimable
19	19,000,000,000	7,600,000,000	−6,600,000,000
22	22,000,000,000	8,800,000,000	−4,800,000,000
26	26,000,000,000	10,400,000,000	−2,400,000,000
30	30,000,000,000	12,000,000,000	0

Claimable goes negative and only reaches zero on the final day. Clamped at zero, as any implementation must, Bob receives nothing for the remaining twelve days — on a base tranche that was never gated.

The mechanism is that withdrawn is a single stream-wide counter, so re-imposing held after a withdrawal has settled charges the shortfall against whatever the recipient's other tranches earn next. A milestone decision reaches across tranche boundaries and cancels income the milestone never governed. Money Bob was unambiguously entitled to when he withdrew it becomes a debt against his future earnings.

Restricting revocation to "before anything is withdrawn" avoids that, and replaces it with a race between approver and recipient decided by who submits first — which rewards whoever is running a bot rather than whoever is right.

What it protects

• The no-custody claim becomes structurally true. The approver's power moves value in one direction only. Under revocation they could reduce what the recipient ultimately receives, which is custody in substance, and concepts.md would need amending to something much weaker.
• The milestone struct stays small. A revocable milestone needs a released-amount field and a revocation counter per milestone, inside the stream entry — pushing directly against threat-model T2 and T8, the read budget and restore cost that MAX_MILESTONES_PER_STREAM exists to manage.
• The indexer's fold never walks backwards. claimable is non-decreasing in approvals.

What it gives up, stated plainly

No in-protocol remedy for an approval that turns out to be wrong. That was never StelFlow's to handle — architecture.md already draws the line where Trustless Work decides whether a condition is met and StelFlow decides how fast money moves. A grant program needing disputes names a TW escrow as approver, and that escrow withholds approval until its process concludes. Revocation's real use case, solved by not approving yet, in the contract that has the machinery.

Changes

• docs/research/milestone-revocation.md — decision, four options considered, the arithmetic, and what's given up
• docs/concepts.md — rule stated in Milestone gates; TODO(maintainer) removed; "flips a flag" sharpened to "flips a flag, once, in one direction"
• docs/architecture.md — open question 2 marked settled; storage consequence recorded
• docs/specs/behaviour.md — UNDECIDED docs: write the three use-case pages #3 resolved, and it narrows design: settle the four remaining UNDECIDED cases in behaviour.md #32's case 1

Acceptance criteria

• A decision with reasoning written down, not just the conclusion
• concepts.md states the rule; TODO removed
• architecture.md reflects the storage consequence
• The "does not give the approver custody" claim checked — still true, and strengthened

Makes T3 more urgent, not less. With no revocation and no deadline, a non-cancelable stream whose approver disappears has no recovery path for anyone. Deciding deadlines is now the outstanding half of the milestone lifecycle.