Idempotency and leases

Scope

This page defines idempotency boundaries and lease lifecycle behavior across gate operations.

Idempotency scopes

Operation	Scope	Key behavior
authorize	billing account + key (lease lookup)	Returns existing lease for same key and matching hash
commit	lease + key	Replays stored response snapshot on match
ingest	billing account + key	Replays stored response snapshot on match
cancel	lease token	Cancel is lease-state transition, not response replay

Request-hash rule

• Same key with same normalized request hash is replay-safe.
• Same key with different hash is rejected as idempotency conflict (409).

Lease token model

• Lease token is opaque and bound to a lease id.
• Commit resolves token to lease id and verifies token hash against stored lease metadata.
• Commit also verifies feature match and optional seat match against lease context.

Lease lifecycle

Lease states:

• active: usable for commit
• closed: finalized by successful commit close
• expired: time window ended
• canceled: explicit cancel path used

State transitions:

• authorize issues active
• commit closes lease to closed (single commit) or closes after batch item loop
• cancel transitions active -> canceled

Late commit semantics

• Commit after lease expiry emits lease.expired.
• If delay exceeds the accepted late-arrival window, the commit is held for reconciliation instead of normal settlement.
• The late-arrival window follows deployment policy.

Batch commit lease-close behavior

• Each batch item has its own idempotency key.
• Lease close is deferred during per-item processing and applied after items complete.
• Item-level failures do not prevent successful items from closing their leases.

Verify checklist

• Same request + same key returns stable replay.
• Different payload + same key returns 409.
• Invalid lease token format fails with 422.
• Closed/canceled/expired leases surface expected commit hints and outcomes.