Rulvar API reference / @rulvar/store-conformance
@rulvar/store-conformance
The executable conformance kit for Rulvar store adapters: append atomicity, total per-run order, read-your-writes, payload opacity, lease fencing, golden fold-state fixtures, the adversarial multi-process soak, and the engine-level kill-point suite (a child process SIGKILLed around each durable write, resumed from another process, with the documented re-pay counts asserted). If you implement a custom store, this suite is the contract your implementation must pass. Exports journalStoreConformance, leasableStoreConformance, runMultiProcessSoak, killPointConformance, and registerConformance.
Part of Rulvar, an embeddable TypeScript engine for durable, budget-bounded multi-agent LLM workflows, where a completed LLM call is never paid for twice. Full documentation: docs.rulvar.com.
Install
bash
pnpm add -D @rulvar/store-conformanceDocumentation
License
Interfaces
| Interface | Description |
|---|---|
| AdmissionConformanceOptions | - |
| AdmissionSchedulerFixture | - |
| ConformanceCheck | One mandatory check; run rejects with a descriptive Error on violation. |
| ConformanceSuite | @rulvar/store-conformance: the executable store conformance kit (M2-T11, DEF-4). A store implementation passes journalStoreConformance (and leasableStoreConformance when it has the lease capability, fencedWritesConformance when it declares the fencedWrites promise, and fencedTranscriptsConformance when its transcript store declares the same promise) or it is not a Rulvar store; the kit is the executable definition of the storage seam frozen at 1.0. Stores meant for multi-process queue deployments additionally run the adversarial multi-process soak (runMultiProcessSoak: real OS processes storm one store location through every fenced write surface and the referee diffs the state against the serial history the epochs promise) and the engine-level kill-point suite (killPointConformance: a child process SIGKILLs itself around each durable write of a scripted run, and the referee resumes over the same store asserting the documented recovery semantics, re-pay counts included). |
| FencedTranscriptsFixture | The paired factory product: the transcript store under test plus the leasable journal store sharing its fencing domain. |
| KillPointConformanceOptions | - |
| KillPointExpectation | The pinned recovery semantics a scenario asserts. |
| KillPointObservation | What a green scenario returns (the observed recovery). |
| KillPointScenario | - |
| KillPointScenarioOptions | - |
| KillPointTarget | Per-scenario isolation a consumer's prepare hands the suite. |
| KillPointWorkerConfig | The per-scenario contract, serialized as JSON into the RULVAR_KILL_POINT_CONFIG environment variable of the spawned worker. |
| KillPointWorkerHooks | Consumer hooks for runKillPointWorker. |
| MultiProcessSoakOptions | - |
| MultiProcessSoakResult | What a green soak returns (the storm's observed coverage). |
| RestorableEffectLaneStore | The store shape under test: the capability plus the restore verb. |
| SoakActivity | Activity counters derived from the merged report events. |
| SoakQuorum | Minimum activity the storm must reach before the referee stops it: run-until-quorum makes the soak adaptive (a slow CI machine storms longer, it never asserts on thin coverage). |
| SoakWriterConfig | The per-writer contract, serialized as JSON into the RULVAR_SOAK_CONFIG environment variable of each spawned writer. |
| SoakWriterHooks | Consumer hooks for runSoakWriter. |
| TestRegistrar | Structural subset of the Vitest/Jest registration API. |
Type Aliases
| Type Alias | Description |
|---|---|
| AdmissionConfig | - |
| KillPointEvent | One JSONL line of a worker's report file. |
| KillPointName | The five durable writes a scenario kills around. |
| KillPointPhase | before = the write is lost; after = everything past it is lost. |
| KillPointWorkflowKind | The two scripted runs: two plain steps, or one tool-capped agent. |
| QuotaLimiterConstructor | Constructs a limiter over the given rules; the suite closes whatever it returns (a close method is called and awaited when present), so factories may open real resources for the negative control. |
| SoakAcceptSurface | Accepted-mutation surfaces of the soaked run (serial-history members). |
| SoakEvent | One JSONL line of a writer's report file (w is the writer index). |
| SoakProbeSurface | Surfaces of the stale-probe sweep; every one must reject typed. |
| StoreFactory | The factory contract: every call MUST return a fresh, isolated store (checks run against independent instances; a JsonlFileStore factory uses a fresh temp directory per call). |
Variables
| Variable | Description |
|---|---|
| DEFAULT_SOAK_QUORUM | Default quorum: a few seconds of storm on a developer machine. |
| GOLDEN_FOLD_JOURNAL | seq 0 agent spawn (running; abandoned by seq 6) seq 1 suspended external gate-a under the spawn's child scope seq 2 suspended external gate-b at the root seq 3 resolution of gate-a: schema-INVALID (never closes) seq 4 resolution of gate-a: applied seq 5 resolution of gate-a: noop (already_resolved) seq 6 abandon of the spawn: applied (covers the agent:0 subtree) seq 7 resolution of gate-b: applied (root scope, not covered) seq 8 abandon of gate-b: noop (already_resolved; first-closing-wins) seq 9 abandon of the spawn again: noop (target_abandoned) |
| GOLDEN_FOLD_STATE_SHA256 | The reference hash; computed once from the kernel fold and frozen. |
| KILL_POINT_SCENARIOS | The full table: both brackets of all five write points. The expected counts ARE the engine's documented recovery semantics; a count moving here means the durability contract moved and the change must be deliberate. |
Functions
| Function | Description |
|---|---|
| admissionConformance | - |
| countSoakActivity | Derives the activity counters the quorum is judged against. |
| effectLaneStoreConformance | - |
| ensure | @rulvar/store-conformance: the executable store conformance kit (M2-T11, DEF-4). A store implementation passes journalStoreConformance (and leasableStoreConformance when it has the lease capability, fencedWritesConformance when it declares the fencedWrites promise, and fencedTranscriptsConformance when its transcript store declares the same promise) or it is not a Rulvar store; the kit is the executable definition of the storage seam frozen at 1.0. Stores meant for multi-process queue deployments additionally run the adversarial multi-process soak (runMultiProcessSoak: real OS processes storm one store location through every fenced write surface and the referee diffs the state against the serial history the epochs promise) and the engine-level kill-point suite (killPointConformance: a child process SIGKILLs itself around each durable write of a scripted run, and the referee resumes over the same store asserting the documented recovery semantics, re-pay counts included). |
| fencedTranscriptsConformance | - |
| fencedWritesConformance | - |
| foldStateSha256 | - |
| journalStoreConformance | - |
| killPointConformance | The whole KILL_POINT_SCENARIOS table as a conformance suite: one check per scenario, each over the fresh isolation prepare returns. Register it with a test API whose it allows at least thirty seconds per case (spawn, run, die, lease lapse, resume). |
| killPointWorkerConfigFromEnv | Reads the worker contract a referee serialized into the child env. |
| leasableStoreConformance | - |
| makeSuite | @rulvar/store-conformance: the executable store conformance kit (M2-T11, DEF-4). A store implementation passes journalStoreConformance (and leasableStoreConformance when it has the lease capability, fencedWritesConformance when it declares the fencedWrites promise, and fencedTranscriptsConformance when its transcript store declares the same promise) or it is not a Rulvar store; the kit is the executable definition of the storage seam frozen at 1.0. Stores meant for multi-process queue deployments additionally run the adversarial multi-process soak (runMultiProcessSoak: real OS processes storm one store location through every fenced write surface and the referee diffs the state against the serial history the epochs promise) and the engine-level kill-point suite (killPointConformance: a child process SIGKILLs itself around each durable write of a scripted run, and the referee resumes over the same store asserting the documented recovery semantics, re-pay counts included). |
| materializeFoldState | Materializes the observable fold state of a journal: ref-entry classifications (invalid details excluded: validator message wording is not contractual), suspension states, and per-seq abandon coverage. |
| parseKillPointReport | Parses one report file, tolerating a torn trailing line. |
| parseSoakReport | Parses one report file, tolerating a torn trailing line. |
| quotaRulesConformance | - |
| registerConformance | @rulvar/store-conformance: the executable store conformance kit (M2-T11, DEF-4). A store implementation passes journalStoreConformance (and leasableStoreConformance when it has the lease capability, fencedWritesConformance when it declares the fencedWrites promise, and fencedTranscriptsConformance when its transcript store declares the same promise) or it is not a Rulvar store; the kit is the executable definition of the storage seam frozen at 1.0. Stores meant for multi-process queue deployments additionally run the adversarial multi-process soak (runMultiProcessSoak: real OS processes storm one store location through every fenced write surface and the referee diffs the state against the serial history the epochs promise) and the engine-level kill-point suite (killPointConformance: a child process SIGKILLs itself around each durable write of a scripted run, and the referee resumes over the same store asserting the documented recovery semantics, re-pay counts included). |
| runKillPointScenario | Spawns the worker, asserts it died AT the configured write by SIGKILL, waits out the dead owner's lease, resumes the run over the referee's own store instance, and asserts the scenario's pinned recovery semantics. Throws one Error naming every violation. |
| runKillPointWorker | The worker protocol: run it in a spawned process against the consumer-constructed store pair. Wraps the journal so the configured write kills the process (before = ahead of the write, after = once it is durable), appends every observation to the report file first (the appends are synchronous, so the report survives the SIGKILL), and reports ran-to-completion when the kill point is never reached, which the referee treats as a violation. |
| runMultiProcessSoak | Spawns the writer processes, stops the storm at quorum (or at the hard cap), verifies the serial history against the store, and throws one Error naming every violation. The returned result is the storm's observed coverage; assert on it if the caller wants a floor beyond the quorum. |
| runSoakWriter | The writer protocol: run it in a spawned process against the consumer-constructed store pair. Appends every observation to the report file; protocol-level anomalies (a stale acceptance, an unexpected error class) are logged as events for the referee, never thrown, so one writer's finding cannot vanish with its process. |
| soakWriterConfigFromEnv | Reads the writer contract a referee serialized into the child env. |
| stableStringify | @rulvar/store-conformance: the executable store conformance kit (M2-T11, DEF-4). A store implementation passes journalStoreConformance (and leasableStoreConformance when it has the lease capability, fencedWritesConformance when it declares the fencedWrites promise, and fencedTranscriptsConformance when its transcript store declares the same promise) or it is not a Rulvar store; the kit is the executable definition of the storage seam frozen at 1.0. Stores meant for multi-process queue deployments additionally run the adversarial multi-process soak (runMultiProcessSoak: real OS processes storm one store location through every fenced write surface and the referee diffs the state against the serial history the epochs promise) and the engine-level kill-point suite (killPointConformance: a child process SIGKILLs itself around each durable write of a scripted run, and the referee resumes over the same store asserting the documented recovery semantics, re-pay counts included). |
| verifySoakHistory | The pure referee: rebuilds the serial history from the merged report events and diffs it against the actual post-storm store state. Returns every violation as a descriptive string; an empty array means the fencing promise held for the whole storm. |