Context
Runtime v0 ends a reservation with commit or release. That is sufficient while the downstream economic outcome is final, but an integration can later report a refund, dispute, cancellation, pricing correction, partial reversal, or chargeback after Cycles has committed the exposure.
The admin-plane CREDIT operation is not a semantic reversal of a prior commit: it restores available budget while preserving spent. Broad state-correction operations also do not identify or idempotently compensate a specific committed action. Without explicit semantics, the Cycles ledger can diverge from the downstream economic outcome.
This is an accounting/reconciliation question, not a request for Cycles to execute payment-rail refunds. A payment rail moves or reverses funds; Cycles records the resulting economic exposure.
Design questions
- Should post-commit correction be part of the runtime protocol, the operator/admin plane, or both?
- Should corrections be append-only compensating entries or mutations of the original commit?
- How should full, partial, and repeated adjustments be represented?
- What idempotency key and correlation to the original reservation/commit are required?
- How do adjustments affect
spent, remaining, debt, derived scopes, and balance invariants?
- How are external payment/refund identifiers and evidence correlated without making Cycles a payment proxy?
- Which audit events, webhook events, permissions, and conformance tests are required?
- Which term avoids conflating a Cycles ledger correction with a payment-rail
refund (adjust, reverse, or another term)?
Desired outcome
Produce a design decision that:
- preserves deterministic accounting and idempotency;
- keeps payment-rail operations outside Cycles;
- defines reconciliation for post-commit changes, including partial reversals;
- specifies any API, schema, audit-event, and conformance changes required.
Implementation should follow the design decision rather than adding a refund endpoint prematurely.
Related protocol locations:
cycles-protocol-v0.yaml: reservation/commit/release runtime lifecyclecycles-governance-admin-v0.1.25.yaml: budget funding and corrective operations
Context
Runtime v0 ends a reservation with
commitorrelease. That is sufficient while the downstream economic outcome is final, but an integration can later report a refund, dispute, cancellation, pricing correction, partial reversal, or chargeback after Cycles has committed the exposure.The admin-plane
CREDIToperation is not a semantic reversal of a prior commit: it restores available budget while preservingspent. Broad state-correction operations also do not identify or idempotently compensate a specific committed action. Without explicit semantics, the Cycles ledger can diverge from the downstream economic outcome.This is an accounting/reconciliation question, not a request for Cycles to execute payment-rail refunds. A payment rail moves or reverses funds; Cycles records the resulting economic exposure.
Design questions
spent,remaining,debt, derived scopes, and balance invariants?refund(adjust,reverse, or another term)?Desired outcome
Produce a design decision that:
Implementation should follow the design decision rather than adding a refund endpoint prematurely.
Related protocol locations:
cycles-protocol-v0.yaml: reservation/commit/release runtime lifecyclecycles-governance-admin-v0.1.25.yaml: budget funding and corrective operations