Evidence and idempotency
How Valqio makes runtime decisions explainable and safe to retry.
Evidence is the record that explains a runtime decision. Idempotency is what keeps retries from turning one product attempt into multiple usage charges.
Evidence
Decision evidence should let a teammate answer:
- Who asked to run work?
- Which generated action, control, meter, or limit was checked?
- What quantity was requested?
- Was the decision allowed or denied?
- Which plan, credit, quota, reservation, or usage window mattered?
- Which request ID or idempotency key ties the record back to app logs?
Store the request ID, idempotency key, reason code, and any reservation ID next to your own request log when possible. That makes support and engineering investigations much faster.
Idempotency keys
Use one idempotency key for one product attempt.
Good keys are stable and specific:
generateText:workspace_acme:req_123
renderVideo:job_987Avoid keys that change on every retry, such as a new timestamp. Avoid keys that are too broad, such as only the customer ID.
Generated actions accept one caller-owned key for the complete product attempt. Valqio derives private begin, claim, commit, and release keys. Do not add a settlement phase suffix in application code.
Retry rules
| Situation | Key behavior |
|---|---|
| The same product attempt retries after a timeout. | Keep the immutable action key and reuse the same idempotency key. |
| The user starts a new product attempt. | Keep the immutable action key and use a new idempotency key. |
| A queued worker claims the transaction. | Pass the transaction ID; the SDK creates a private claim-attempt key. |
| Settlement is uncertain after local work succeeds. | Retry or reconcile the same transaction; never release completed work. |
| Product work fails before completion. | Release the same transaction and preserve the product error. |
The goal is not just correct billing. The goal is explainable runtime behavior when systems retry, time out, or fail halfway through work.