receipt-recovery

command
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 16 Imported by: 0

README

Receipt-based recovery fixture

This embedding Go host runs the local fixture proposed in issue #90. It uses the real workflow controller and registered-action journal, a separate SQLite fake external counter, and no model credentials, Docker, or GitHub calls. The fake is deliberately non-idempotent: replaying an increment increments twice. This is an example of the existing recovery contract, not a LazyMind integration or a new retry policy.

Run from the repository root with the repository's Go toolchain:

go run ./examples/receipt-recovery > receipt-evidence.json
go test -race ./examples/receipt-recovery

The default command uses disposable temporary storage and removes it on exit. To retain the databases and evidence for inspection:

go run ./examples/receipt-recovery -output /tmp/receipt-fixtures > receipt-evidence.json

-output creates a new receipt-recovery-* directory under the supplied parent; it preserves existing files and prints the owned directory to stderr. Each scenario has an engine/ journal, external.sqlite, and generated workflow. evidence.json contains the same JSON printed to stdout. Remove only that newly created fixture directory when finished inspecting it. Never use these synthetic receipts as evidence of a real external publication.

What it exercises

Scenario Injected failure Explicit resume result External counter
unknown Increment commits, response is lost, reconciliation says unknown Needs attention with both retry acknowledgements Stays 1
lookup_error Increment commits, response is lost, receipt lookup fails Needs attention; the lookup error remains distinct from proof of absence Stays 1
completed Increment commits, response is lost, authoritative fake receipt is recovered Output/evidence/receipt pass checkpoint validation; completion commits without another handler call Stays 1
no_effect Real action admission commits, its acknowledgement is lost before the handler runs Proof of absence commits before a new physical attempt with the same logical operation key 0 before resume, 1 after

Between failure and resume, each scenario stops its controller, closes both SQLite databases, and reconstructs its registered Go host from durable state. Each resume uses POST /runs/<id>/resume with an explicit request_id and retry_uncertain acknowledgement. Repeating the same request returns the same execution generation and creates exactly one run.resume_admitted event. Changing its acknowledgement returns a conflict. A queued resume acknowledgement is recorded separately from the eventual execution status; acceptance is not proof that the mutation completed.

Terminal status may be visible before the controller releases its execution owner. The fixture retries that specific active-owner admission rejection with the same resume identity and acknowledgement, bounded by a ten-second deadline. Other conflicts and request errors fail the scenario immediately.

The evidence includes the run ID, original and subsequent physical action attempts, logical operation key, execution generations, resume identities and acknowledgements, reconciliation observations/proofs, and counter values. The new handler in the no_effect case reads the committed original attempt before incrementing, so an in-memory absence decision alone cannot satisfy the fixture.

For each lost-response case, a separate negative-control.sqlite deliberately performs the same operation twice. The same counter assertion must reject the result; its rejection is retained in negative_control. This keeps each recovered scenario's external.sqlite at one while demonstrating that accidental replay would fail the checker. A failed scenario exits nonzero.

Embedding boundary

The command registers action/increment through workflows.RegisterAction and runs controller.Server with a controller.Client. The stock CLI does not load Go plugins. The admission-loss wrapper delegates the real SQLite admission first and then injects the acknowledgement error; the remaining journal and controller operations use the normal implementation.

The fake provider owns its receipt lookup and authoritative absence proof. A successful lookup, a completed control request, or retry_uncertain=true alone cannot authorize replay of an uncertain registered external mutation. See registered Go actions for the full contract. Starting a different workflow run is outside this fixture: its run-scoped operation key does not implement cross-run application deduplication.

Documentation

Overview

Command receipt-recovery demonstrates caller-driven registered-action recovery using only a local controller, SQLite, and a deliberately non-idempotent fake.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL