Engineering notes · 10 October 2026

A timeout does not tell you whether an action happened

A worker asks a provider to create an issue. The provider commits it, but the connection closes before the response arrives. The worker sees a timeout. That timeout describes the connection; it does not establish whether the issue exists.

Give the intent a stable identity

Choose one operation key for one logical action and persist it before sending the request. A transport retry must reuse that key and the original parameters. Generating a fresh UUID inside every retry turns a connection failure into a new action.

intent = load_or_create_intent(job_id)
result = submit(intent.operation_key, intent.parameters)
if connection_failed:
    inspect(intent.operation_key)
    reconcile_with_provider_evidence()
    retry_only_if_evidence_permits()

This is pseudocode for the control flow, not an executable ONCE client. A durable intent alone does not make an external provider participate in your database transaction.

Keep uncertainty visible

Observation	What follows
The response confirms the provider object	Record the object and the successful outcome.
The response was lost	Preserve uncertainty and look for provider evidence.
No object was found in one lookup	Absence alone does not prove the provider did not commit.
Evidence is ambiguous	Stop automatic redispatch and surface the uncertainty.

What ONCE adds

Provider-native idempotency may already be enough for one integration. ONCE adds a durable operation record, explicit outcomes and recovery paths for two supported actions: GitHub issue creation and unconfirmed Stripe test PaymentIntents. Reusing an operation key retrieves the existing logical operation; changing its input produces a conflict. UNKNOWN and AMBIGUOUS states do not permit blind redispatch.

ONCE does not provide a universal exactly-once guarantee, capture live payments, undo provider actions or execute arbitrary HTTP requests. GitHub creation is a real repository write. Repository selection stays pinned to the operation; credentials remain request-scoped.

Try the supported path

Create a free project and confirm your email.
Keep its API key in server-side configuration.
Run the Stripe sandbox quickstart with your own test credential, or configure a repository-restricted GitHub token.
Replay the same key and input. Inspect the existing operation instead of starting a new logical action.
Read the failure boundaries before adding automatic retries.

Free access includes 1,000 ordinary request units per UTC month. ONCE is £9/month for 10,000 ordinary units. Reconciliation has a separate reserved allowance. Review the complete offer and service terms.

Useful feedback is a supported integration you actually ran, the observed state and whether recovery clarified the outcome. Send a redacted report to accounts@aiagenthuddle.com; keep provider tokens and request contents private.

This product explanation was prepared with AI assistance and checked against the implemented API and recorded acceptance tests.