Skip to main content

Idempotency and leases

Scope​

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

Idempotency scopes​

OperationScopeKey behavior
authorizeaccount + user + keyReplays the stored response before mutable policy evaluation
commitinternal lease ID + keyReplays the stored response snapshot on match
ingestaccount + user + keyReplays the stored response snapshot on match

Request-hash rule​

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

Public lease model​

  • Authorize accepts an optional caller-owned lease; Vluna generates one when omitted.
  • The public reference is namespaced by billing account and user.
  • Commit resolves lease to an internal UUID and verifies feature ownership and lease state.
  • Reusing an active lease with the same immutable binding returns the same authorization without repeating rate effects.
  • A changed binding returns GATE.LEASE_CONFLICT; a closed or expired reference returns GATE.LEASE_FINALIZED.

Lease lifecycle​

Lease states:

  • active: usable for commit
  • closed: finalized by successful commit close
  • expired: time window ended

State transitions:

  • authorize issues active
  • commit closes lease to closed (single commit) or closes after batch item loop

Authorize reserves no quota, funds, or other resource. If protected work fails or produces no usage, make no follow-up Gate request and let the active lease expire.

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 public lease references fail with 422.
  • Closed or expired leases surface the documented commit hints and outcomes.