Python adapter contract
Your worker.
A repeatable failure.
Connect a trusted Python handler through a small adapter. ReplayGuard controls the delivery schedule and simulated receiver, then checks the receipts independently.
1. Start with a runnable case
Download the kit, extract it, and open a terminal in that folder. Python 3.11+ on macOS or Linux is required.
python3 -I -S scripts/test_repair.py \
--candidate business-key --case crash-retry \
--output repaired.jsonThe business-key candidate should produce one receipt after a committed effect and retry. A passing selected case exits 0.
2. Implement one adapter function
Your adapter file exports build(effects), which returns a callable receiving one delivery. Your application can keep its own event format; the adapter translates it.
# my_adapter.py
def build(effects):
def handle(delivery):
order = delivery['order']
return effects.fulfill(order, key=order['orderId'])
return handleThe receiver accepts any nonempty string key up to 256 characters. It does not require ReplayGuard’s hash formula. Choosing the correct business identity is the candidate’s responsibility.
The boundary
| Input or operation | Meaning |
|---|---|
delivery | deliveryId, messageId, receiveCount, and order. The candidate is not given the case name or expected verdict. |
order | orderId, sku, integer quantity, and optional attributes. Preserve the entire payload. |
effects.fulfill(order, key=…) | Atomically commits a receipt, or reuses one for the exact same payload and key. key=None creates a fresh receipt. |
effects.Conflict | The same key was used with different fulfillment inputs. Let the conflict reach the runner when the plan expects rejection. |
| Injected interruption | The runner can interrupt immediately after a new receipt commits, before the response returns. The receipt survives that local interruption. |
| Handler return | Diagnostic evidence only. The independent receipt snapshot determines the effect count. |
A key shared by every order can stop retries and still reject a second valid order. The test requires one receipt for each expected business order.
3. Test a repair that loses a valid order
First run a copy of the correct handler against two orders sharing a product:
mkdir -p candidate
cp repair_lab/adapters/business_key.py candidate/adapter.py
python3 -I -S scripts/test_repair.py \
--adapter candidate/adapter.py --case interleaved-retries \
--output before.jsonExpect Passed / exit 0: ORDER-A and ORDER-B each have one receipt.
In candidate/adapter.py, replace key=order["orderId"] with key=order["sku"]. Run the same case:
python3 -I -S scripts/test_repair.py \
--adapter candidate/adapter.py --case interleaved-retries \
--output broken.jsonExpect Violation / exit 1: A has one receipt, B has zero. The SKU key stops duplicates but rejects another valid order. Import the actual report to inspect its receipts and failed checks.
Restore the handler and retain the same regression:
cp repair_lab/adapters/business_key.py candidate/adapter.py
python3 -I -S scripts/test_repair.py \
--adapter candidate/adapter.py --case interleaved-retries \
--output restored.jsonExpect Passed / exit 0: A and B each have one receipt again. These are expected results; run the commands to produce your own evidence.
4. Check the limits
python3 -I -S scripts/test_repair.py \
--adapter my_adapter.py \
--output repair-results.jsonThis runs the bounded built-in cases, including controls that deliberately remain incomplete or unresolved. The full report need not exit zero. Inspect each case; do not treat the aggregate as an expected-outcomes score.
| Exit | Result |
|---|---|
| 0 · Passed | The selected observed contract held. |
| 1 · Violation | Observed receipts or required completion behavior broke the contract. |
| 2 · Incomplete | Required execution or independent evidence is missing. |
| 3 · Unresolved | Unsupported effect or conflicting observations prevent a resolved result. |
5. Try a separate application
The kit includes DispatchDesk, a separately authored synthetic dispatch worker. It consumes nested application events and calls its own injected gateway. Only its adapter knows ReplayGuard.
python3 -I -S scripts/test_repair.py \
--adapter examples/dispatchdesk/adapter.py \
--case-file examples/dispatchdesk/cases.json \
--output dispatchdesk-results.jsonIts independent plan tests lost responses, interleaved orders, distinct shop references, quantity conflicts and changed shipping attributes. This is an integration example, not outside-user validation, a customer deployment or a real shipment.
Use --case-file for your own bounded JSON plan. The archive’s docs/repair-lab/schema.md describes the complete format and supported limits.
6. Keep a failing reproduction
Keep the candidate source, case plan and generated report together. Change the candidate, rerun the same plan, and import the new JSON in the repair bench. Source fingerprints help distinguish the versions.
The archive contains a deterministic exporter and a SHA256SUMS manifest. It can recreate itself from a clean extraction. A hash proves byte consistency, not who executed a report.
Execution boundaries
- Trusted Python code only. The guard blocks ordinary network, SDK, subprocess and native-FFI paths; it is not a hostile-code sandbox.
- At most eight declared deliveries per case, with per-phase timeouts and bounded effect calls.
- Cases execute against an in-memory receiver. AWS visibility timing, concurrent invocations, service durability and every possible interleaving are outside this test.
- Missing observations stay unknown. A separate external action cannot be made exactly once by writing an unrelated receipt.