@alma-harness/testing

The shared storage contract suites of Alma — what "correct" means for every storage adapter, on any backend.

Status: pre-1.0. The API is still moving; see the roadmap for where it stands.

What it owns

• describeSessionStoreContract — the SessionStore contract.
• describeEpisodeStoreContract, describeProfileStoreContract — the memory storage contracts: deterministic ids, three states never conflated, the three-case confidence rule, identity never extracted, a budget on every read.
• describeMemoryErasureContract — the LGPD/GDPR story as a test: content gone, derived data invalidated, every declared copy surface reached. The fixture's watermarks and accessEvents are required: six cases used to return silently without them, green on an in-flight guard and a trail the adapter never proved (spec: erasure-reaches-the-claims).
• describeSpendStoreContract — the SpendStore contract (spec: spend-store): atomic increment-and-return, UTC day bucketing, org-wide day aggregation, no lost increments under concurrency.
• describeRoutineStoreContract — the RoutineStore contract (spec: clock-tick): a routine round-trips with its registration stamp, the stamp survives re-registration, cancel removes, list sees every scope.
• describeRoutineRunStoreContract — the RoutineRunStore contract (spec: postgres-routine-runs, routine-claims-and-memory-json): atomic claims have one winner, collection transitions only from submitted, terminal records survive retries; a run round-trips whole, upserts by key, lists newest first with an inclusive since that compares instants, and is isolated by routine, uid and org.
• The proof tests that run each suite against the reference implementations (@alma-harness/core/testing for sessions, @alma-harness/memory/testing for memory) — which is what proves the contracts are satisfiable at all.

Backend neutrality is enforced by running one suite against every backend — the reason pnpm check:all refuses to pass with no DATABASE_URL rather than letting these suites skip themselves (spec 031). From an adapter's test file:

import { describeEpisodeStoreContract } from "@alma-harness/testing";

describeEpisodeStoreContract("MyEpisodeStore", { create: () => new MyEpisodeStore() });

Requires vitest (peer dependency): a contract suite IS a set of tests.

What it must never do

• Weaken a suite for one backend's convenience — a backend idiom that cannot pass the shared contract is a bug in the adapter, not in the contract.
• Grow assertions an adapter can satisfy by convention only: every normative rule of the memory charter is pinned here, or it is not a rule.
• Ship in a runtime dependency graph. This package is a devDependency of adapters, never a dependency of products.

The routine-run contract also verifies warning metadata through claims, updates and scoped reads, defensive array copies, and empty-array normalization.

describeCostSettlementStoreContract verifies idempotent receipts, concurrent conflicts, original totals, complete normalized usage, scoped bounded reads, consumer acknowledgements and late projection work on memory and Postgres. settlementFixture provides synthetic known priced usage for adapter suites. The Postgres suite additionally verifies real rollback, lost commit acknowledgement, legacy upgrade, retention and a limited login. No provider is called.

Durable execution journal

describeExecutionStoreContract(name, factory) proves claim uniqueness, scoped identity binding, the transition matrix, evidence/pricing preservation, bounded reconciliation/listing and exclusive recovery. executionFixture creates closed metadata without prompts or responses. The same real-clock suite runs on memory and PostgreSQL; lease/deadline observations use bounded polling. PostgreSQL adds actual limited-login RLS, lock waits, lost commit acknowledgements, raw SQL shape checks and erasure/retention compatibility tests.

Documentation

Docs index · Architecture · Invariants

Apache-2.0

describeExecutionResultStoreContract runs the same reservation, immutable binding, closed-envelope, caller ownership, concurrency, scope/session isolation, erasure, expiry and narrowed-policy contract against memory and PostgreSQL. Its factory supplies create(policy) and reopen(store, policy) over the same stored records. The PostgreSQL package additionally exercises real locks, raw payload nulling, commit acknowledgement loss, transaction rollback, SQL shape checks and limited login RLS. This proves the storage seam; provider dispatch adoption is a later slice.

describeUsageInboxContract proves immutable event identity, scoped acknowledgements, snapshot ownership, evidence preservation and both bounded history/pending readers. usageInboxFixture supplies synthetic metadata. The same suite runs on execution's memory reference and real PostgreSQL; PG adds fault, migration, erasure and RLS tests.

describeGovernedCostSettlementStoreContract tests atomic financial decisions, mode/operation/call conflicts and governed projections. Its factory is GovernedCostSettlementStoreFactory; governedSettlementFixture is synthetic. The new memory reference also runs the ordinary cost-settlement contract. Testing now peers on execution for these public types. Real PostgreSQL adds write faults, lost acknowledgements, limited-role RLS and retention/migration compatibility.

describeGovernedExecutionContract supplements the legacy journal suite with policy binding, settled/completed replay, fenced recovery and closed proof checks. describeGovernedInboxContract pins governed input snapshots. Use governedExecutionFixture and executionProof for deterministic journal tests; the latter uses the volatile governed financial reference, not production billing.

The result expiry sweep contract waits for the latest persisted expiry before checking bounded removal counts. A controlled-clock reference invocation pins staggered preparation times; adapter invocations retain real clocks.

The retired TurnStore suite is inventoried in the retirement ledger. Canonical operation admission replaces TTL takeover; historical SQL erasure/retention proofs remain in postgres tests.