Commit approved return work and its dispatch record together
The application marks a return processing, then publishes a refund job. If it crashes between those steps, the return is stuck forever; publishing first can instead process a refund for a rolled-back decision.
- Focused work estimate
- 3h 30m + prerequisites
- Priority in the scenario
- High
- Engineering practice
- Transactional outbox · Job leases · At-least-once delivery
Estimated field mix
- Distributed systems60%
- Database engineering40%
Field percentages are editorial estimates of the ticket's engineering focus. They total 100%; they are not measured time, proficiency scores, or ownership evidence.
Pattern topics
- Transactional OutboxApply
Bind state and dispatch intent to one commit while accepting repeat delivery and preserving deterministic identities for downstream deduplication.
Review it, then add it to your workspace.
The board opens an editable draft; nothing is saved until you confirm it. Sign-in and workspace permissions apply, and Demo boards remain ephemeral.
Project context
A fictional equipment retailer lets customers choose a refund or replacement after inspection. Its payment and stock providers can time out after accepting an operation, so retrying the whole return is unsafe. Create a local TypeScript application, PostgreSQL state/outbox tables, and synthetic provider doubles with controllable outcomes; no starter code or fixtures are supplied. Use invented orders and integer minor-unit amounts only, with no real payments or external provider calls.
Setup prerequisites
- SQL transactions
- Idempotent commands
- Async failure handling
- State modeling
Preceding work
Complete these dependencies, or supply their agreed outputs before taking this ticket.
Acceptance criteria
- Commit the accepted command, return transition, and outbox record in one database transaction with a deterministic dispatch identity.
- A bounded dispatcher claims due records safely across two instances and retries using the same operation identity.
- Treat dispatch as at-least-once: acknowledgment loss can redeliver, but downstream handling deduplicates the effect and pending records remain observable.
Implementation constraints
- Do not hold the database transaction open during a provider call; use explicit lease expiry and attempt limits for dispatch recovery.
Verification to include
- Crash before and after commit and compare return, command, and outbox records for atomic presence or absence.
- Lose a dispatch acknowledgment and run two dispatchers through lease expiry; assert one logical refund intent despite repeat delivery.
Deliverables
- Transactional outbox write path, dispatcher, and crash-boundary checks
Rollout and recovery
Start with dispatch paused and reconcile synthetic pending counts; enable one dispatcher before rehearsing a second instance and restart.
Value of the work
For the engineer: Practice durable workflow state, ambiguous provider outcomes, compensation, concurrency isolation, and recovery that survives process restarts.
For the team: Inspect whether a proposed workflow preserves refund and inventory invariants, contains provider failures, and gives operators a bounded recovery path.
Evidence boundaries
Outcome Evidence: Tests, patches, and runbooks are requested deliverables. They become Outcome Evidence only through a qualified Mission and immutable Evidence IDs.
Ownership Evidence: Independent adaptation must be observed under a declared verification policy and cite immutable Evidence IDs. Completing a planning ticket establishes no Ownership Evidence.