@rulvar/store-conformance 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import { JournalEntry, JournalStore, LeasableStore } from "@rulvar/core";
+
+//#region src/types.d.ts
+/**
+* Conformance kit surface (M2-T11, DEF-4): an executable suite
+* parameterized by a store factory. A store implementation passes or it
+* is not a rulvar store (docs/11, section "Conformance tier"; docs/03,
+* section "Conformance obligations").
+*/
+/** One mandatory check; `run` rejects with a descriptive Error on violation. */
+interface ConformanceCheck {
+  id: string;
+  title: string;
+  run(): Promise<void>;
+}
+interface ConformanceSuite {
+  name: string;
+  checks: readonly ConformanceCheck[];
+  /** Runs every check sequentially; throws on the first violation. */
+  run(): Promise<void>;
+}
+/**
+* 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).
+*/
+type StoreFactory<S> = () => Promise<S> | S;
+/** Structural subset of the Vitest/Jest registration API. */
+interface TestRegistrar {
+  describe(name: string, factory: () => void): void;
+  it(name: string, fn: () => Promise<void>): void;
+}
+/** Registers the suite as one `describe` block with one `it` per check. */
+declare function registerConformance(suite: ConformanceSuite, api: TestRegistrar): void;
+declare function makeSuite(name: string, checks: readonly ConformanceCheck[]): ConformanceSuite;
+/** Canonical JSON with recursively sorted keys (fold-state hashing). */
+declare function stableStringify(value: unknown): string;
+//#endregion
+//#region src/journal.d.ts
+declare function journalStoreConformance(mk: StoreFactory<JournalStore>): ConformanceSuite;
+//#endregion
+//#region src/leasable.d.ts
+declare function leasableStoreConformance(mk: StoreFactory<LeasableStore>, options?: {
+  /**
+  * The store's configured lease TTL, when known: enables the
+  * wall-clock expiry and renew-keeps-held checks.
+  */
+  ttlMs?: number;
+}): ConformanceSuite;
+//#endregion
+//#region src/fixtures/golden-fold.d.ts
+/**
+* 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)
+*/
+declare const GOLDEN_FOLD_JOURNAL: readonly JournalEntry[];
+/**
+* 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.
+*/
+declare function materializeFoldState(entries: readonly JournalEntry[]): Record<string, unknown>;
+declare function foldStateSha256(entries: readonly JournalEntry[]): string;
+/** The reference hash; computed once from the kernel fold and frozen. */
+declare const GOLDEN_FOLD_STATE_SHA256 = "81e6ccff549fb3e6c1de4d34ba65b912162eba6f66403b5d5f23a3e1ec69243c";
+//#endregion
+export { type ConformanceCheck, type ConformanceSuite, GOLDEN_FOLD_JOURNAL, GOLDEN_FOLD_STATE_SHA256, type StoreFactory, type TestRegistrar, foldStateSha256, journalStoreConformance, leasableStoreConformance, makeSuite, materializeFoldState, registerConformance, stableStringify };

package/dist/index.js

@@ -0,0 +1,588 @@
+import { LeaseHeldError, Replayer, ResolutionFold, agentScope, buildDeriverRegistry, deriveContentKey, dispositionHook } from "@rulvar/core";
+import { createHash } from "node:crypto";
+//#region src/types.ts
+/** Registers the suite as one `describe` block with one `it` per check. */
+function registerConformance(suite, api) {
+	api.describe(suite.name, () => {
+		for (const check of suite.checks) api.it(`${check.id}: ${check.title}`, () => check.run());
+	});
+}
+function makeSuite(name, checks) {
+	return {
+		name,
+		checks,
+		async run() {
+			for (const check of checks) await check.run();
+		}
+	};
+}
+/** Assertion helper: conformance failures are plain Errors naming the check. */
+function ensure(condition, checkId, message) {
+	if (!condition) throw new Error(`store-conformance ${checkId}: ${message}`);
+}
+/** Canonical JSON with recursively sorted keys (fold-state hashing). */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+	if (typeof value === "object" && value !== null) {
+		const record = value;
+		return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+//#endregion
+//#region src/fixtures/golden-fold.ts
+/**
+* Golden fold-state fixture (M2-T11; docs/03, section "Conformance
+* obligations"): a hand-authored journal with applied, noop, and invalid
+* resolutions plus applied and noop abandons. Folding it through the
+* kernel MUST produce a fold state whose canonical hash equals
+* GOLDEN_FOLD_STATE_SHA256 on every store implementation: a store cannot
+* influence replay semantics.
+*
+* FROZEN fixture (docs/11, section "Frozen journal fixtures"): any edit
+* requires an explicit hashVersion-bump changeset
+* (scripts/check-frozen-fixtures.mjs).
+*/
+function entry(partial) {
+	return {
+		hashVersion: 2,
+		scope: "",
+		key: `golden-${partial.seq}`,
+		ordinal: 0,
+		kind: "external",
+		status: "suspended",
+		spanId: "golden-span",
+		startedAt: (/* @__PURE__ */ new Date(17e11 + partial.seq * 1e3)).toISOString(),
+		...partial
+	};
+}
+/**
+* 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)
+*/
+const GOLDEN_FOLD_JOURNAL = [
+	entry({
+		seq: 0,
+		kind: "agent",
+		status: "running"
+	}),
+	entry({
+		seq: 1,
+		scope: "agent:0",
+		value: {
+			key: "gate-a",
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				required: ["ok"],
+				properties: { ok: { type: "boolean" } }
+			}
+		}
+	}),
+	entry({
+		seq: 2,
+		value: { key: "gate-b" }
+	}),
+	entry({
+		seq: 3,
+		kind: "resolution",
+		status: "ok",
+		ref: 1,
+		scope: "agent:0",
+		resolution: {
+			target: 1,
+			by: "external",
+			value: { ok: "yes" }
+		}
+	}),
+	entry({
+		seq: 4,
+		kind: "resolution",
+		status: "ok",
+		ref: 1,
+		scope: "agent:0",
+		resolution: {
+			target: 1,
+			by: "operator",
+			value: { ok: true }
+		}
+	}),
+	entry({
+		seq: 5,
+		kind: "resolution",
+		status: "ok",
+		ref: 1,
+		scope: "agent:0",
+		resolution: {
+			target: 1,
+			by: "timeout",
+			value: { ok: false }
+		}
+	}),
+	entry({
+		seq: 6,
+		kind: "abandon",
+		status: "ok",
+		ref: 0,
+		abandon: {
+			target: 0,
+			authorizedBy: 0,
+			reason: "golden abandon"
+		}
+	}),
+	entry({
+		seq: 7,
+		kind: "resolution",
+		status: "ok",
+		ref: 2,
+		resolution: {
+			target: 2,
+			by: "external",
+			value: { go: 1 }
+		}
+	}),
+	entry({
+		seq: 8,
+		kind: "abandon",
+		status: "ok",
+		ref: 2,
+		abandon: {
+			target: 2,
+			authorizedBy: 6,
+			reason: "late abandon over a resolved gate"
+		}
+	}),
+	entry({
+		seq: 9,
+		kind: "abandon",
+		status: "ok",
+		ref: 0,
+		abandon: {
+			target: 0,
+			authorizedBy: 6,
+			reason: "repeat abandon"
+		}
+	})
+];
+/**
+* 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.
+*/
+function materializeFoldState(entries) {
+	const fold = new ResolutionFold(entries);
+	const abandonFold = fold.abandonFold;
+	const classifications = {};
+	const suspensions = {};
+	const abandoned = {};
+	for (const item of entries) {
+		abandoned[String(item.seq)] = abandonFold.isAbandoned(item.seq);
+		const classification = fold.classificationOf(item.seq);
+		if (classification !== void 0) classifications[String(item.seq)] = classification.classification === "invalid" ? { classification: "invalid" } : classification;
+		if (item.status === "suspended") suspensions[String(item.seq)] = fold.suspensionState(item.seq);
+	}
+	return {
+		classifications,
+		suspensions,
+		abandoned
+	};
+}
+function foldStateSha256(entries) {
+	return createHash("sha256").update(stableStringify(materializeFoldState(entries)), "utf8").digest("hex");
+}
+/** The reference hash; computed once from the kernel fold and frozen. */
+const GOLDEN_FOLD_STATE_SHA256 = "81e6ccff549fb3e6c1de4d34ba65b912162eba6f66403b5d5f23a3e1ec69243c";
+//#endregion
+//#region src/journal.ts
+/**
+* journalStoreConformance (M2-T11, DEF-4): the executable definition of
+* the JournalStore seam. Mandatory checks per docs/03, section
+* "Conformance obligations" and docs/11, section "Conformance tier":
+* A1 append atomicity, A2 total per-run order, A3 read-your-writes,
+* A4 opaque payload, meta separation, the golden fold-state fixture, the
+* end-to-end decide-once oracle, and the abandon fixture (zero live
+* classes inside a skipped subtree, zero ledger increment).
+*
+* The oracle and the abandon fixture drive the kernel (Replayer,
+* ResolutionFold, the DEF-1 predicate) directly over the store under
+* test, in strict mode, so "zero live calls" holds by construction: no
+* dispatch surface exists below the kernel. The engine-level variants
+* (FakeAdapter call counters) live in the M2 cassette suite
+* (@rulvar/testing).
+*/
+const RUN$1 = "conformance-run";
+function baseEntry(seq, overrides) {
+	return {
+		hashVersion: 2,
+		seq,
+		scope: "",
+		key: `conf-key-${seq}`,
+		ordinal: 0,
+		kind: "step",
+		status: "ok",
+		value: { seq },
+		spanId: "conf-span",
+		startedAt: (/* @__PURE__ */ new Date(17e11 + seq * 1e3)).toISOString(),
+		...overrides
+	};
+}
+function sameEntry(a, b) {
+	return stableStringify(a) === stableStringify(b);
+}
+function meta(runId, overrides) {
+	return {
+		runId,
+		status: "running",
+		updatedAt: (/* @__PURE__ */ new Date(17e11)).toISOString(),
+		...overrides
+	};
+}
+function journalStoreConformance(mk) {
+	return makeSuite("journalStoreConformance", [
+		{
+			id: "a1-append-atomicity",
+			title: "an append is all-or-nothing; a torn write is never observable",
+			async run() {
+				const store = await mk();
+				const big = "x".repeat(8192);
+				const submitted = Array.from({ length: 12 }, (_, i) => baseEntry(i, { value: {
+					seq: i,
+					blob: `${big}-${i}`,
+					sentinel: "END-OF-ENTRY"
+				} }));
+				const appends = submitted.map((item) => store.append(RUN$1, item));
+				const midLoads = [store.load(RUN$1), store.load(RUN$1)];
+				await Promise.all([...appends, ...midLoads]);
+				for (const seen of await Promise.all(midLoads)) for (const item of seen) {
+					const original = submitted.find((candidate) => candidate.seq === item.seq);
+					ensure(original !== void 0 && sameEntry(item, original), "a1-append-atomicity", `a load observed a torn or foreign entry at seq ${item.seq}`);
+				}
+				const loaded = await store.load(RUN$1);
+				ensure(loaded.length === submitted.length, "a1-append-atomicity", `expected ${submitted.length} whole entries, loaded ${loaded.length}`);
+				for (const item of loaded) {
+					const original = submitted.find((candidate) => candidate.seq === item.seq);
+					ensure(original !== void 0 && sameEntry(item, original), "a1-append-atomicity", `loaded entry seq ${item.seq} does not equal the appended entry`);
+				}
+			}
+		},
+		{
+			id: "a2-total-order",
+			title: "load returns the order of successful appends, stable across loads",
+			async run() {
+				const store = await mk();
+				const entries = Array.from({ length: 10 }, (_, i) => baseEntry(i));
+				for (const item of entries) await store.append(RUN$1, item);
+				const first = await store.load(RUN$1);
+				ensure(first.map((item) => item.seq).join(",") === entries.map((item) => item.seq).join(","), "a2-total-order", `sequential appends loaded out of order: ${first.map((item) => item.seq).join(",")}`);
+				await Promise.all(Array.from({ length: 8 }, (_, i) => store.append(RUN$1, baseEntry(10 + i))));
+				const second = await store.load(RUN$1);
+				const third = await store.load(RUN$1);
+				ensure(second.map((item) => item.seq).join(",") === third.map((item) => item.seq).join(","), "a2-total-order", "two loads of the same run disagree on entry order");
+				ensure(second.length === 18 && new Set(second.map((item) => item.seq)).size === 18, "a2-total-order", "concurrent appends were lost or duplicated");
+				ensure(second.slice(0, 10).map((item) => item.seq).join(",") === entries.map((item) => item.seq).join(","), "a2-total-order", "later appends reordered the existing prefix");
+			}
+		},
+		{
+			id: "a3-read-your-writes",
+			title: "an acknowledged append is visible to an immediately following load",
+			async run() {
+				const store = await mk();
+				for (let i = 0; i < 5; i += 1) {
+					const item = baseEntry(i);
+					await store.append(RUN$1, item);
+					const loaded = await store.load(RUN$1);
+					const last = loaded[loaded.length - 1];
+					ensure(loaded.length === i + 1 && last !== void 0 && sameEntry(last, item), "a3-read-your-writes", `append of seq ${i} was acknowledged but not visible to load`);
+				}
+			}
+		},
+		{
+			id: "a4-opaque-payload",
+			title: "unknown kinds and unknown fields round-trip byte-exactly, never normalized",
+			async run() {
+				const store = await mk();
+				const exotic = {
+					v: 1,
+					seq: 0,
+					scope: "par:0:1/wormhole",
+					key: "k-exotic",
+					ordinal: 3,
+					kind: "wormhole.v9",
+					status: "ok",
+					value: {
+						unicode: "δοκιμή ☃ 🚀".normalize("NFC"),
+						float: .30000000000000004,
+						nested: { deep: [
+							1,
+							2,
+							{ three: null }
+						] }
+					},
+					futureField: { shape: "unknown" },
+					spanId: "s",
+					startedAt: "2026-01-01T00:00:00.000Z"
+				};
+				await store.append(RUN$1, exotic);
+				const [loaded] = await store.load(RUN$1);
+				ensure(loaded !== void 0 && sameEntry(loaded, exotic), "a4-opaque-payload", "the exotic entry did not round-trip byte-exactly (normalized, stripped, or rewritten)");
+				ensure(loaded.hashVersion === void 0, "a4-opaque-payload", "the store injected hashVersion into a legacy entry (normalization is read-side only)");
+			}
+		},
+		{
+			id: "meta-separation",
+			title: "putMeta replaces the run record; listRuns filters without payload parsing; delete removes both",
+			async run() {
+				const store = await mk();
+				ensure((await store.load("never-written")).length === 0, "meta-separation", "load of an unknown run must return an empty journal");
+				await store.append(RUN$1, baseEntry(0));
+				await store.putMeta(meta(RUN$1, {
+					name: "wf-a",
+					tags: ["team:core"]
+				}));
+				await store.putMeta(meta("other-run", {
+					status: "suspended",
+					name: "wf-b"
+				}));
+				ensure((await store.listRuns()).filter((candidate) => candidate.runId === RUN$1).length === 1, "meta-separation", "putMeta must upsert one record per run");
+				await store.putMeta(meta(RUN$1, {
+					status: "suspended",
+					name: "wf-a",
+					tags: ["team:core"]
+				}));
+				const suspended = await store.listRuns({ status: "suspended" });
+				ensure(suspended.some((candidate) => candidate.runId === RUN$1) && suspended.every((candidate) => candidate.status === "suspended"), "meta-separation", "listRuns must reflect the replaced meta and honor the status filter");
+				const byName = await store.listRuns({ name: "wf-b" });
+				ensure(byName.length === 1 && byName[0]?.runId === "other-run", "meta-separation", "listRuns must honor the name filter");
+				const byTag = await store.listRuns({ tags: ["team:core"] });
+				ensure(byTag.length === 1 && byTag[0]?.runId === RUN$1, "meta-separation", "listRuns must honor the tags filter");
+				await store.delete(RUN$1);
+				ensure((await store.load(RUN$1)).length === 0 && !(await store.listRuns()).some((candidate) => candidate.runId === RUN$1), "meta-separation", "delete must remove the journal and the meta record");
+			}
+		},
+		{
+			id: "golden-fold-state",
+			title: "the kernel fold over the stored golden journal hashes to the reference",
+			async run() {
+				const store = await mk();
+				for (const item of GOLDEN_FOLD_JOURNAL) await store.append(RUN$1, item);
+				const hash = foldStateSha256(await store.load(RUN$1));
+				ensure(hash === GOLDEN_FOLD_STATE_SHA256, "golden-fold-state", `fold state hash ${hash} differs from the reference ${GOLDEN_FOLD_STATE_SHA256}: the store influenced replay semantics`);
+			}
+		},
+		{
+			id: "decide-once-oracle",
+			title: "a scripted race yields exactly one applied classification, then replays with the same winner",
+			async run() {
+				const store = await mk();
+				const writer = new Replayer({
+					runId: RUN$1,
+					store
+				});
+				const suspended = await writer.appendSuspended({
+					scope: "",
+					key: deriveContentKey({
+						kind: "external",
+						key: "decide-once"
+					}),
+					kind: "external",
+					spanId: "conf-span",
+					value: { key: "decide-once" }
+				});
+				const [first, second] = await Promise.all([writer.resolveSuspended(suspended.seq, {
+					by: "external",
+					value: { decision: "primary" }
+				}), writer.resolveSuspended(suspended.seq, {
+					by: "timeout",
+					value: { decision: "fallback" }
+				})]);
+				const outcomes = [first, second];
+				ensure(outcomes.filter((outcome) => outcome.applied).length === 1, "decide-once-oracle", "a race of two resolution attempts must settle exactly one applied");
+				const journaled = await store.load(RUN$1);
+				ensure(journaled.filter((item) => item.kind === "resolution").length === 2, "decide-once-oracle", "both attempts must be journaled (the loser is a journaled noop)");
+				const state = new Replayer({
+					runId: RUN$1,
+					store,
+					priorEntries: journaled,
+					strict: true
+				}).suspensionState(suspended.seq);
+				const winnerSeq = outcomes.find((outcome) => outcome.applied)?.seq;
+				ensure(state.state === "resolved" && state.by === winnerSeq, "decide-once-oracle", "the replayed fold disagrees with the live winner");
+				const reload = await store.load(RUN$1);
+				ensure(foldStateSha256(journaled) === foldStateSha256(reload), "decide-once-oracle", "two loads of the raced journal fold to different states");
+			}
+		},
+		{
+			id: "abandon-derived-skip",
+			title: "a journal with an abandoned branch replays with zero live classes inside the subtree",
+			async run() {
+				const store = await mk();
+				const writer = new Replayer({
+					runId: RUN$1,
+					store
+				});
+				const branchIdentity = {
+					kind: "step",
+					key: "abandoned-branch",
+					deps: []
+				};
+				const spawn = await writer.appendRunning({
+					scope: "",
+					key: deriveContentKey(branchIdentity),
+					kind: "agent",
+					spanId: "conf-span"
+				});
+				const child = await writer.appendRunning({
+					scope: agentScope("", spawn.seq),
+					key: "child-key",
+					kind: "agent",
+					spanId: "conf-span"
+				});
+				await writer.appendTerminal(child.seq, {
+					status: "ok",
+					value: "paid work",
+					usage: {
+						inputTokens: 500,
+						outputTokens: 100,
+						cacheReadTokens: 0,
+						cacheWriteTokens: 0
+					}
+				});
+				ensure((await writer.abandonBranch({
+					target: spawn.seq,
+					authorizedBy: spawn.seq,
+					reason: "conformance abandon"
+				})).applied, "abandon-derived-skip", "the covering abandon must apply");
+				const replayed = new Replayer({
+					runId: RUN$1,
+					store,
+					priorEntries: await store.load(RUN$1),
+					strict: true
+				});
+				replayed.setDisposition(dispositionHook(replayed.fold.abandonFold, buildDeriverRegistry()));
+				const matched = replayed.match("", branchIdentity, "scoped");
+				ensure(matched.kind === "skip", "abandon-derived-skip", `the abandoned dispatch must derive skipped, got '${matched.kind}'`);
+				const ledger = replayed.ledger();
+				ensure(ledger.usage.inputTokens === 0 && ledger.usage.outputTokens === 0 && ledger.agentsSpawned === 0, "abandon-derived-skip", "derived-skipped entries must contribute a zero ledger increment (docs/03, section 13.3)");
+				ensure(replayed.resumeReport().orphaned.length === 0, "abandon-derived-skip", "covered entries must be reported skipped, never orphaned");
+			}
+		}
+	]);
+}
+//#endregion
+//#region src/leasable.ts
+/**
+* leasableStoreConformance (M2-T11, DEF-4): the executable definition of
+* the lease capability (docs/03, section "LeasableStore and leases").
+* Mandatory: acquire on a held lease rejects with the typed
+* LeaseHeldError; the fencing epoch is monotonic per run; an append
+* carrying a stale epoch is rejected AND invisible to subsequent loads;
+* a released lease can neither renew nor append.
+*
+* The renew-cadence rule (at most ttl/3) is a HOLDER obligation; the
+* store-side counterpart checked here (when `ttlMs` is provided) is that
+* a lease renewed at that cadence stays held past the original ttl and
+* that an unrenewed lease becomes reclaimable. The first LeasableStore
+* ships in M5 (@rulvar/store-sqlite); the multi-process soak re-runs
+* these sections under real concurrency in M8.
+*/
+const RUN = "lease-run";
+function leaseEntry(seq) {
+	return {
+		hashVersion: 2,
+		seq,
+		scope: "",
+		key: `lease-key-${seq}`,
+		ordinal: 0,
+		kind: "step",
+		status: "ok",
+		value: { seq },
+		spanId: "lease-span",
+		startedAt: (/* @__PURE__ */ new Date(17e11 + seq * 1e3)).toISOString()
+	};
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function mustReject(operation) {
+	try {
+		await operation();
+	} catch (thrown) {
+		return thrown;
+	}
+}
+function leasableStoreConformance(mk, options) {
+	const checks = [
+		{
+			id: "lease-exclusive-acquire",
+			title: "acquire on a held lease rejects with the typed LeaseHeldError",
+			async run() {
+				const store = await mk();
+				const held = await store.acquire(RUN, "owner-a");
+				ensure(held.runId === RUN && held.owner === "owner-a" && typeof held.epoch === "number", "lease-exclusive-acquire", "acquire must return a Lease with runId, owner, and a numeric fencing epoch");
+				ensure(await mustReject(() => store.acquire(RUN, "owner-b")) instanceof LeaseHeldError, "lease-exclusive-acquire", "a second acquire while held must reject with LeaseHeldError (typed, code lease_held)");
+				await store.release(held);
+				ensure((await store.acquire(RUN, "owner-b")).owner === "owner-b", "lease-exclusive-acquire", "after release, acquire must succeed for a new owner");
+			}
+		},
+		{
+			id: "fencing-stale-epoch",
+			title: "the epoch is monotonic; a stale-epoch append is rejected and invisible",
+			async run() {
+				const store = await mk();
+				const first = await store.acquire(RUN, "owner-a");
+				await store.append(RUN, leaseEntry(0), first);
+				await store.release(first);
+				const second = await store.acquire(RUN, "owner-b");
+				ensure(second.epoch > first.epoch, "fencing-stale-epoch", `the fencing epoch must be monotonic per run (got ${second.epoch} after ${first.epoch})`);
+				await store.append(RUN, leaseEntry(1), second);
+				ensure(await mustReject(() => store.append(RUN, leaseEntry(2), first)) !== void 0, "fencing-stale-epoch", "an append carrying a stale epoch must be rejected");
+				const loaded = await store.load(RUN);
+				ensure(loaded.length === 2 && !loaded.some((item) => item.seq === 2), "fencing-stale-epoch", "a rejected stale-epoch append must never appear in load");
+			}
+		},
+		{
+			id: "lease-release-fences",
+			title: "a released lease can neither renew nor append",
+			async run() {
+				const store = await mk();
+				const lease = await store.acquire(RUN, "owner-a");
+				await store.renew(lease);
+				await store.release(lease);
+				ensure(await mustReject(() => store.renew(lease)) !== void 0, "lease-release-fences", "renew of a released lease must reject");
+				ensure(await mustReject(() => store.append(RUN, leaseEntry(0), lease)) !== void 0, "lease-release-fences", "append under a released lease must reject");
+				ensure((await store.load(RUN)).length === 0, "lease-release-fences", "nothing may be visible after only-rejected appends");
+			}
+		}
+	];
+	const ttlMs = options?.ttlMs;
+	if (ttlMs !== void 0) checks.push({
+		id: "lease-ttl-and-renew-cadence",
+		title: "renew at ttl/3 keeps the lease held past ttl; an unrenewed lease expires",
+		async run() {
+			const store = await mk();
+			const held = await store.acquire(RUN, "owner-a");
+			const cadence = Math.floor(ttlMs / 3);
+			const deadline = Date.now() + Math.ceil(ttlMs * 1.5);
+			while (Date.now() < deadline) {
+				await sleep(cadence);
+				await store.renew(held);
+				ensure(await mustReject(() => store.acquire(RUN, "owner-b")) instanceof LeaseHeldError, "lease-ttl-and-renew-cadence", "a lease renewed at ttl/3 must stay held past the original ttl");
+			}
+			await store.release(held);
+			const abandoned = await store.acquire("expiring-run", "owner-a");
+			await sleep(Math.ceil(ttlMs * 1.2));
+			ensure((await store.acquire("expiring-run", "owner-b")).epoch > abandoned.epoch, "lease-ttl-and-renew-cadence", "reclaiming an expired lease must advance the fencing epoch");
+		}
+	});
+	return makeSuite("leasableStoreConformance", checks);
+}
+//#endregion
+export { GOLDEN_FOLD_JOURNAL, GOLDEN_FOLD_STATE_SHA256, foldStateSha256, journalStoreConformance, leasableStoreConformance, makeSuite, materializeFoldState, registerConformance, stableStringify };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@rulvar/store-conformance",
+  "version": "1.0.0",
+  "description": "rulvar executable store conformance kit (DEF-4).",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@rulvar/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "tsdown": "^0.22.3",
+    "typescript": "~6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/rulvar.git",
+    "directory": "packages/store-conformance"
+  },
+  "homepage": "https://rulvar.com",
+  "bugs": {
+    "url": "https://github.com/o-stepper/rulvar/issues"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "pack-check": "publint --pack pnpm && attw --pack . --profile esm-only"
+  }
+}