ReplayGuardDownload regression kit

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.

This is a local test of a declared effect contract. The receiver’s receipt is the complete simulated fulfillment. No payment, email or shipment is sent.

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.json

The 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 handle

The 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 operationMeaning
deliverydeliveryId, messageId, receiveCount, and order. The candidate is not given the case name or expected verdict.
orderorderId, 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.ConflictThe same key was used with different fulfillment inputs. Let the conflict reach the runner when the plan expects rejection.
Injected interruptionThe runner can interrupt immediately after a new receipt commits, before the response returns. The receipt survives that local interruption.
Handler returnDiagnostic 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.json

Expect 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.json

Expect 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.json

Expect 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.json

This 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.

ExitResult
0 · PassedThe selected observed contract held.
1 · ViolationObserved receipts or required completion behavior broke the contract.
2 · IncompleteRequired execution or independent evidence is missing.
3 · UnresolvedUnsupported 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.json

Its 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.

Open the repair bench Download regression kit

Execution boundaries