← FlowPatch

ILLUSTRATIVE SAMPLE · NOT CLIENT DATA

Async image-provider boundary diagnostic

Example of the specificity in a $99 diagnostic. Scenario: an agency app submits image jobs to a third-party provider, polls status, receives webhooks, and stores final assets.

Executive finding

The boundary can create duplicate jobs and lose completed assets.

The current design treats a timeout as a failed request even when the provider may have accepted it. Polling and webhooks can then race, while retries have no stable idempotency key. The corrective design needs one local operation record, deterministic request identity, and monotonic state transitions.

Risk matrix

HIGH

Submit timeout

Failure: client times out after provider accepts the job.

Impact: blind retry creates duplicate paid work.

Control: deterministic idempotency key plus reconciliation before resubmit.

HIGH

Webhook/poller race

Failure: both paths finalize the same job.

Impact: duplicate downstream publication or billing.

Control: compare-and-set finalization with a unique effect record.

MEDIUM

Late success

Failure: local timeout marks a job failed before a delayed success webhook.

Impact: completed asset is orphaned.

Control: separate terminal provider state from operator-visible retry eligibility.

LOW

Unknown webhook

Failure: valid event arrives before submit response is stored.

Impact: temporary unmatched event.

Control: persist and replay unmatched events for a bounded window.

Required state model

created → submit_pending → submitted(provider_job_id) → running → succeeded(asset_ref) ─→ finalized(effect_id) ↘ submit_unknown ─→ reconciling ─→ submitted | retry_eligible ↘ failed_retryable ─→ retry_pending ↘ failed_terminal Invariant: finalized may be entered once only. Invariant: a known provider_job_id is never resubmitted.

Concrete retry and reconciliation rules

R1 — Identity. Generate operation_id before the first network call. Derive the provider idempotency key from that stable value; never from attempt number or timestamp.

R2 — Ambiguous submit. On connection reset or timeout, move to submit_unknown. Query by idempotency key or provider job reference before another POST.

R3 — Backoff. Retry only documented transient classes: 408, 429, and selected 5xx. Use exponential backoff with jitter and a bounded attempt/time budget. Honor Retry-After.

R4 — Finalization. Poller and webhook call the same idempotent transition. Store a unique (operation_id, effect_type) record before publishing, charging, or notifying.

R5 — Monotonicity. A late running event cannot overwrite succeeded. A late success may reconcile a locally timed-out operation unless a human explicitly cancelled it.

R6 — Dead letter. Events that fail validation or matching are persisted with reason, payload hash, first-seen time, and replay status.

Failure-path test checklist

Injected condition	Expected assertion
Provider accepts POST; response times out	Exactly one provider job after reconciliation and retry.
Duplicate webhook delivered five times	One final state transition and one downstream effect.
Poll returns success while webhook handler runs	One compare-and-set winner; loser becomes a no-op.
429 with Retry-After	No retry before the server-defined delay; attempt budget remains bounded.
Success arrives after local timeout	Asset is attached; state does not remain terminal-failed.
Malformed signature / unknown operation	No state mutation; event stored with an actionable reason.

Patch plan and estimate

1. Persistence & identity

Operation table, unique constraints, deterministic idempotency key.

Estimate: 2–3 hours

2. Transition service

Shared compare-and-set path for poll and webhook handlers.

Estimate: 3–5 hours

3. Reconciliation worker

Bounded handling for ambiguous submits and unmatched events.

Estimate: 2–4 hours

4. Failure-path tests

Six deterministic tests with provider responses stubbed.

Estimate: 2–3 hours

Total illustrative estimate: 9–15 engineering hours. A real diagnostic would name the exact files, database constraints, provider endpoints, and error classes after reviewing the accepted boundary.

Want this level of specificity for your workflow?

The fixed-fee diagnostic is $99 for one provider boundary and arrives within two business days after written scope acceptance and confirmed payment.

Request a diagnostic