Faultline

Deterministic simulation that classifies whether an external side effect is safe to retry — and under which of five honest guarantees. It never claims exactly-once.

 MIT · zero-dependency core · byte-identical across Node 20/22

Quickstart

npx faultline-demo

Offline, no config, no keys, seed-locked (byte-identical every run). It runs one charge two ways under the same injected failure and prints the verdict:

ACT 1  naive charge, no idempotency key
       retried under a lost ACK → 2 effects → customer double-charged
       classification: unsafe

ACT 2  same seed, idempotency key + reconcile
       retry reconciled → 1 effect → no double charge
       classification: reconcile_before_retry

Same seed, same failure: the fix climbs from unsafe to reconcile_before_retry. Faultline never reports a class stronger than the run proves.

What it is

Retries are easy. Knowing whether an external side effect is safe to retry is not.

Faultline runs one developer-defined action through the ten canonical ways a distributed call fails. It does this as deterministic simulation against an in-process modeled provider: no network, no wall-clock, byte-identical from a seed. From the results it classifies the action's retry-safety into one of five honest classes.

It never claims exactly-once, and it does not inject faults into a live provider — that is future work (see packages/core).

Packages

Package	What it is
@aliqubit/core	The deterministic engine + 5-class honest classifier (the primitive).
@aliqubit/registry	Verification-gated SideEffectContracts for real providers (Stripe, DynamoDB).
@aliqubit/ci-gate	CI gate that blocks PRs whose actions aren't proven retry-safe (attestation-verified).
@aliqubit/generate	Scaffold honest, mock-only contracts from an OpenAPI spec.
@aliqubit/runtime	Fail-closed production executor (automate reconcile-before-retry; never fake a 200).
@aliqubit/verify	Recorded (VCR-style) verification + Ed25519 attestation of the verification tier.
@aliqubit/gateway	Language-agnostic HTTP gateway over the runtime.
faultline-demo	The offline demo shown above.

The core is a single primitive and works standalone; every other package is optional and builds on it. The core depends on none of them.

Develop

npm install        # one workspace install, one lockfile
npm run build      # build packages in dependency order
npm test           # 117 tests across the workspace

CI runs build + test + a cross-version determinism gate on Node 20 and 22 — it fails if seed-locked output diverges between versions.

License

MIT — see LICENSE.