The registry sync loop currently ACKs every well-formed handle it pulled,
including settled conflicts such as AlreadyStagedDifferentSpk and
AlreadyCommittedDifferentSpk. The registry therefore cannot distinguish a
successful stage from a request that can never be fulfilled for its requested
script pubkey.
This is safe for retry behavior but insufficient for paid or user-facing
registries: an ACK only removes the item from /pending, while the reason it
was removed exists only in the private subs logs.
Proposed contract
Extend POST /ack with a backwards-compatible structured result per pulled
handle, for example:
{
"handles": [
{ "handle": "alice@example", "outcome": "staged", "script_pubkey": "5120..." },
{ "handle": "bob@example", "outcome": "already_committed_different_spk", "script_pubkey": "5120..." }
]
}Suggested stable outcomes:
stagedalready_staged_same_spkalready_committed_same_spkalready_staged_different_spkalready_committed_different_spkinvalid if invalid pulled entries are ever ACKed rather than skipped
If changing the existing body is undesirable, a negotiated contract version
or separate result endpoint could retain the current {"handles": [...]}
body for older registries.
Acceptance criteria
- Every pulled and ACKed handle has exactly one machine-readable outcome.
- Different-script conflicts are distinguishable from successful/idempotent staging.
- Lost-ACK replay remains idempotent.
- Existing registries using the v1 ACK body continue to work.
REGISTRY.md documents which outcomes are terminal and which are retryable.
The registry would not become authoritative for Spaces state; subs remains the
source of truth for the local staging result.
The registry sync loop currently ACKs every well-formed handle it pulled,
including settled conflicts such as
AlreadyStagedDifferentSpkandAlreadyCommittedDifferentSpk. The registry therefore cannot distinguish asuccessful stage from a request that can never be fulfilled for its requested
script pubkey.
This is safe for retry behavior but insufficient for paid or user-facing
registries: an ACK only removes the item from
/pending, while the reason itwas removed exists only in the private subs logs.
Proposed contract
Extend
POST /ackwith a backwards-compatible structured result per pulledhandle, for example:
{ "handles": [ { "handle": "alice@example", "outcome": "staged", "script_pubkey": "5120..." }, { "handle": "bob@example", "outcome": "already_committed_different_spk", "script_pubkey": "5120..." } ] }Suggested stable outcomes:
stagedalready_staged_same_spkalready_committed_same_spkalready_staged_different_spkalready_committed_different_spkinvalidif invalid pulled entries are ever ACKed rather than skippedIf changing the existing body is undesirable, a negotiated contract version
or separate result endpoint could retain the current
{"handles": [...]}body for older registries.
Acceptance criteria
REGISTRY.mddocuments which outcomes are terminal and which are retryable.The registry would not become authoritative for Spaces state; subs remains the
source of truth for the local staging result.