Commit

Scope

This page defines commit-time validation, pricing, and settlement behavior for lease-backed usage.

Required inputs

• Idempotency-Key is required.
• lease is required and is resolved inside the current billing account/user namespace.
• feature_code must match the lease feature.
• quantity_minor is required and must be > 0.
• meters[] is optional; when omitted, primary activity meter is used.

Validation sequence

1. Resolve and lock the lease by its caller-owned or Vluna-generated reference.
2. Validate feature match against lease metadata.
3. Validate lease state and expiry status.
4. Resolve quota windows from lease metadata; missing/mismatched window metadata causes quarantine semantics.
5. Validate meter set against feature-meter allowlist for activity semantic kind.
6. Resolve pricing for each meter line.
7. Build aggregate pricing and apply settlement.

Quarantine semantics

Commit supports non-fatal quarantine behavior:

• Invalid or disallowed meter mapping
• Missing policy window metadata at commit time
• Missing pricing for one or more meters
• Lease not active or late commit beyond grace

When quarantined:

• application_status is quarantined
• applied quantity is set to 0
• settlement amount is set to 0
• rating/line records are still written for traceability
• hints and reason codes are returned

Pricing and settlement semantics

• Pricing is resolved at commit time (floating model).
• Feature quantity and meter quantities are separate dimensions.
• Rated lines are a discriminator-based union:
  • rating_status=priced carries exact rational revenue and cost rates, identities, fingerprints, and snapshots;
  • rating_status=missing_price carries explicit missing-price snapshots and zero amounts, with no synthetic zero rate.
• A rational snapshot uses schema=gate/rational-pricing-snapshot:v1 and algorithm=integer_rational_floor_v1. A missing snapshot uses schema=gate/missing-pricing-snapshot:v1 and algorithm=not_rated_missing_price_v1.
• unit_price_xusd / unit_quantity_minor and unit_cost_xusd / cost_unit_quantity_minor are exact rates. The reference quantities are divisors, not billing blocks or minimum charge quantities.
• Revenue and cost each expose a stable rate_identity (the cost side is cost_rate_identity) and their own remainder chain.
• Residual numerators are scoped by billing user + meter + pricing kind + rate identity. Changing a resolved rate starts a distinct remainder chain instead of carrying fractions across unlike rates.
• Settlement allocates funding sources and persists pending settlement facts.

Hint semantics at commit

Commit may emit:

• lease.closed_at_commit
• lease.expired
• policy.window_not_found
• feature.meter_not_allowed
• pricing.not_configured
• pricing.meter_price_missing
• pricing.contract_term_invalid
• pricing.changed
• quota.remaining
• budget.low_headroom

Idempotency behavior

• Commit idempotency is scoped to lease + key.
• Same key + same request hash returns stored response snapshot.
• Same key + different request hash returns 409.

Verify checklist

• Replayed idempotent commit returns stable commit id and lines.
• Quarantined commits write traceable facts but do not settle.
• Missing pricing meters are reflected in hints and reason codes.
• Late commit within grace emits hint; beyond grace quarantines application.