@iterativeflow/conformance

The backend-authoring kit for iterativeflow v2. To add a substrate, implement the four ports (store/queue/timer/wakeup) from @iterativeflow/core/backend and prove them against these shared suites — the same tests the built-in memory, Postgres, and DynamoDB backends pass. A real serialization or consistency regression can't hide behind a backend's own tests.

npm install -D @iterativeflow/conformance @iterativeflow/core

import { storeConformance, engineConformance } from "@iterativeflow/conformance";
import { createMyBackend } from "./backend";

storeConformance("my-backend", () => createMyBackend());
engineConformance("my-backend", () => createMyBackend());

Each suite registers describe/it blocks (vitest), so call them at the top level of a test file.

Suites

• Port suites — storeConformance, queueConformance, timerConformance, wakeupConformance: each port's contract in isolation.
• outboxConformance — the atomic multi-port checkpoint write.
• signalConformance, reconcileConformance, cronConformance — the durable behaviors built on the ports.
• engineConformance — the composed engine (retry/dead-letter, signal resume, cancel cascade, fan-out, drift) end-to-end on your backend.
• claimFilterConformance, shardedClaimConformance — flow-name-filtered claims, and concurrent claims across a fleet. shardedClaimConformance is for backends that support concurrent writers; single-writer backends (memory, sqlite, durable-objects) skip it by design.
• pendingWorkConformance — the autoscaling backlog reads (Queue.depth, Timer.dueCount, Store.dueCronCount) that engine.pendingWork composes.

Every suite takes (label, makeBackend) where makeBackend returns a fresh Backend (or a Promise of one) per case.