@voidhash/mimic-effect 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/testing/HotStorageTestSuite.mjs

@@ -0,0 +1,820 @@
+import { HotStorageTag } from "../HotStorage.mjs";
+import { assertEmpty, assertEqual, assertLength, assertSortedBy, assertTrue } from "./assertions.mjs";
+import { Effect, Schema } from "effect";
+import { Operation, OperationDefinition, OperationPath, Transaction } from "@voidhash/mimic";
+
+//#region src/testing/HotStorageTestSuite.ts
+/**
+* @voidhash/mimic-effect/testing - HotStorage Test Suite
+*
+* Comprehensive test suite for HotStorage (WAL) adapter implementations.
+* These tests verify that an adapter correctly implements the HotStorage interface
+* and can reliably store/retrieve WAL entries for document recovery.
+*/
+/**
+* Test operation definition for creating proper Operation objects in tests.
+* Using Schema.Unknown allows any payload type for flexibility in testing.
+*/
+const TestSetDefinition = OperationDefinition.make({
+	kind: "test.set",
+	payload: Schema.Unknown,
+	target: Schema.Unknown,
+	apply: (payload) => payload
+});
+/**
+* Custom operation definition for testing operation kind preservation.
+*/
+const CustomOpDefinition = OperationDefinition.make({
+	kind: "custom.operation",
+	payload: Schema.Unknown,
+	target: Schema.Unknown,
+	apply: (payload) => payload
+});
+const Categories = {
+	BasicOperations: "Basic Operations",
+	VersionFiltering: "Version Filtering",
+	OrderingGuarantees: "Ordering Guarantees",
+	TruncationEdgeCases: "Truncation Edge Cases",
+	WalEntryIntegrity: "WAL Entry Integrity",
+	DocumentIsolation: "Document Isolation",
+	LargeScaleOperations: "Large-Scale Operations",
+	DocumentIdEdgeCases: "Document ID Edge Cases",
+	GapChecking: "Gap Checking",
+	TransactionEncoding: "Transaction Encoding"
+};
+const makeEntry = (version, timestamp) => ({
+	transaction: Transaction.make([]),
+	version,
+	timestamp: timestamp !== null && timestamp !== void 0 ? timestamp : Date.now()
+});
+const makeEntryWithData = (version, data, timestamp) => ({
+	transaction: Transaction.make([Operation.fromDefinition(OperationPath.make("data"), TestSetDefinition, data)]),
+	version,
+	timestamp: timestamp !== null && timestamp !== void 0 ? timestamp : Date.now()
+});
+const makeEntryWithPath = (version, pathString, payload, timestamp) => ({
+	transaction: Transaction.make([Operation.fromDefinition(OperationPath.make(pathString), TestSetDefinition, payload)]),
+	version,
+	timestamp: timestamp !== null && timestamp !== void 0 ? timestamp : Date.now()
+});
+const tests = [
+	{
+		name: "getEntries returns empty array for non-existent document",
+		category: Categories.BasicOperations,
+		run: Effect.gen(function* () {
+			yield* assertEmpty(yield* (yield* HotStorageTag).getEntries("non-existent-hot-doc", 0), "Should return empty array for non-existent document");
+		})
+	},
+	{
+		name: "append then getEntries returns the entry",
+		category: Categories.BasicOperations,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntry(1);
+			yield* storage.append("basic-append", entry);
+			const entries = yield* storage.getEntries("basic-append", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			yield* assertEqual(entries[0].version, 1, "Entry version should match");
+		})
+	},
+	{
+		name: "multiple append calls accumulate entries",
+		category: Categories.BasicOperations,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("multi-append", makeEntry(1));
+			yield* storage.append("multi-append", makeEntry(2));
+			yield* storage.append("multi-append", makeEntry(3));
+			yield* assertLength(yield* storage.getEntries("multi-append", 0), 3, "Should have three entries");
+		})
+	},
+	{
+		name: "truncate removes entries with version <= upToVersion",
+		category: Categories.BasicOperations,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("truncate-basic", makeEntry(1));
+			yield* storage.append("truncate-basic", makeEntry(2));
+			yield* storage.append("truncate-basic", makeEntry(3));
+			yield* storage.truncate("truncate-basic", 2);
+			const entries = yield* storage.getEntries("truncate-basic", 0);
+			yield* assertLength(entries, 1, "Should have one entry after truncate");
+			yield* assertEqual(entries[0].version, 3, "Only version 3 should remain");
+		})
+	},
+	{
+		name: "truncate on non-existent document does not error",
+		category: Categories.BasicOperations,
+		run: Effect.gen(function* () {
+			yield* (yield* HotStorageTag).truncate("non-existent-truncate", 100);
+		})
+	},
+	{
+		name: "getEntries(doc, 0) returns all entries",
+		category: Categories.VersionFiltering,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("filter-all", makeEntry(1));
+			yield* storage.append("filter-all", makeEntry(2));
+			yield* storage.append("filter-all", makeEntry(3));
+			yield* assertLength(yield* storage.getEntries("filter-all", 0), 3, "sinceVersion=0 should return all entries");
+		})
+	},
+	{
+		name: "getEntries(doc, n) returns only entries with version > n",
+		category: Categories.VersionFiltering,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("filter-n", makeEntry(1));
+			yield* storage.append("filter-n", makeEntry(2));
+			yield* storage.append("filter-n", makeEntry(3));
+			yield* storage.append("filter-n", makeEntry(4));
+			const entries = yield* storage.getEntries("filter-n", 2);
+			yield* assertLength(entries, 2, "Should return entries with version > 2");
+			yield* assertEqual(entries[0].version, 3, "First entry should be version 3");
+			yield* assertEqual(entries[1].version, 4, "Second entry should be version 4");
+		})
+	},
+	{
+		name: "getEntries(doc, exactVersion) excludes that exact version",
+		category: Categories.VersionFiltering,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("filter-exact", makeEntry(5));
+			yield* storage.append("filter-exact", makeEntry(6));
+			yield* storage.append("filter-exact", makeEntry(7));
+			const entries = yield* storage.getEntries("filter-exact", 6);
+			yield* assertLength(entries, 1, "Should exclude version 6");
+			yield* assertEqual(entries[0].version, 7, "Only version 7 should be returned");
+		})
+	},
+	{
+		name: "getEntries(doc, maxVersion) returns empty array",
+		category: Categories.VersionFiltering,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("filter-max", makeEntry(1));
+			yield* storage.append("filter-max", makeEntry(2));
+			yield* storage.append("filter-max", makeEntry(3));
+			yield* assertEmpty(yield* storage.getEntries("filter-max", 3), "sinceVersion >= maxVersion should return empty");
+		})
+	},
+	{
+		name: "getEntries(doc, MAX_SAFE_INTEGER) returns empty array",
+		category: Categories.VersionFiltering,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("filter-huge", makeEntry(1));
+			yield* storage.append("filter-huge", makeEntry(1e6));
+			yield* assertEmpty(yield* storage.getEntries("filter-huge", Number.MAX_SAFE_INTEGER), "sinceVersion=MAX_SAFE_INTEGER should return empty");
+		})
+	},
+	{
+		name: "entries returned sorted by version ascending",
+		category: Categories.OrderingGuarantees,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("order-test", makeEntry(1));
+			yield* storage.append("order-test", makeEntry(2));
+			yield* storage.append("order-test", makeEntry(3));
+			yield* assertSortedBy(yield* storage.getEntries("order-test", 0), "version", "Entries should be sorted by version");
+		})
+	},
+	{
+		name: "out-of-order appends are sorted correctly on retrieval",
+		category: Categories.OrderingGuarantees,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("ooo-test", makeEntry(3));
+			yield* storage.append("ooo-test", makeEntry(1));
+			yield* storage.append("ooo-test", makeEntry(4));
+			yield* storage.append("ooo-test", makeEntry(2));
+			const entries = yield* storage.getEntries("ooo-test", 0);
+			yield* assertLength(entries, 4, "Should have all 4 entries");
+			yield* assertEqual(entries[0].version, 1, "First should be version 1");
+			yield* assertEqual(entries[1].version, 2, "Second should be version 2");
+			yield* assertEqual(entries[2].version, 3, "Third should be version 3");
+			yield* assertEqual(entries[3].version, 4, "Fourth should be version 4");
+		})
+	},
+	{
+		name: "truncate(doc, 0) removes nothing (versions > 0 kept)",
+		category: Categories.TruncationEdgeCases,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("trunc-0", makeEntry(1));
+			yield* storage.append("trunc-0", makeEntry(2));
+			yield* storage.truncate("trunc-0", 0);
+			yield* assertLength(yield* storage.getEntries("trunc-0", 0), 2, "truncate(0) should keep all entries with version > 0");
+		})
+	},
+	{
+		name: "truncate(doc, maxVersion) removes all entries",
+		category: Categories.TruncationEdgeCases,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("trunc-all", makeEntry(1));
+			yield* storage.append("trunc-all", makeEntry(2));
+			yield* storage.append("trunc-all", makeEntry(3));
+			yield* storage.truncate("trunc-all", 3);
+			yield* assertEmpty(yield* storage.getEntries("trunc-all", 0), "truncate(maxVersion) should remove all entries");
+		})
+	},
+	{
+		name: "truncate(doc, middleVersion) removes correct entries",
+		category: Categories.TruncationEdgeCases,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("trunc-mid", makeEntry(1));
+			yield* storage.append("trunc-mid", makeEntry(2));
+			yield* storage.append("trunc-mid", makeEntry(3));
+			yield* storage.append("trunc-mid", makeEntry(4));
+			yield* storage.append("trunc-mid", makeEntry(5));
+			yield* storage.truncate("trunc-mid", 3);
+			const entries = yield* storage.getEntries("trunc-mid", 0);
+			yield* assertLength(entries, 2, "Should keep versions 4 and 5");
+			yield* assertEqual(entries[0].version, 4, "First remaining should be 4");
+			yield* assertEqual(entries[1].version, 5, "Second remaining should be 5");
+		})
+	},
+	{
+		name: "multiple truncates work correctly",
+		category: Categories.TruncationEdgeCases,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("multi-trunc", makeEntry(1));
+			yield* storage.append("multi-trunc", makeEntry(2));
+			yield* storage.append("multi-trunc", makeEntry(3));
+			yield* storage.append("multi-trunc", makeEntry(4));
+			yield* storage.append("multi-trunc", makeEntry(5));
+			yield* storage.truncate("multi-trunc", 2);
+			yield* storage.truncate("multi-trunc", 4);
+			const entries = yield* storage.getEntries("multi-trunc", 0);
+			yield* assertLength(entries, 1, "Should only have version 5");
+			yield* assertEqual(entries[0].version, 5, "Only version 5 should remain");
+		})
+	},
+	{
+		name: "truncate followed by append works correctly",
+		category: Categories.TruncationEdgeCases,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("trunc-append", makeEntry(1));
+			yield* storage.append("trunc-append", makeEntry(2));
+			yield* storage.truncate("trunc-append", 2);
+			yield* storage.append("trunc-append", makeEntry(3));
+			yield* storage.append("trunc-append", makeEntry(4));
+			const entries = yield* storage.getEntries("trunc-append", 0);
+			yield* assertLength(entries, 2, "Should have versions 3 and 4");
+			yield* assertEqual(entries[0].version, 3, "First should be 3");
+			yield* assertEqual(entries[1].version, 4, "Second should be 4");
+		})
+	},
+	{
+		name: "transaction data is preserved exactly",
+		category: Categories.WalEntryIntegrity,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithData(1, {
+				key: "value",
+				nested: { a: 1 }
+			});
+			yield* storage.append("tx-data", entry);
+			const entries = yield* storage.getEntries("tx-data", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			yield* assertEqual(entries[0].transaction, entry.transaction, "Transaction should be preserved exactly");
+		})
+	},
+	{
+		name: "version number is preserved exactly",
+		category: Categories.WalEntryIntegrity,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const version = 42;
+			const entry = makeEntry(version);
+			yield* storage.append("version-preserve", entry);
+			yield* assertEqual((yield* storage.getEntries("version-preserve", 0))[0].version, version, "Version should be preserved exactly");
+		})
+	},
+	{
+		name: "timestamp is preserved exactly",
+		category: Categories.WalEntryIntegrity,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const timestamp = 17040672e5;
+			const entry = makeEntry(1, timestamp);
+			yield* storage.append("timestamp-preserve", entry);
+			yield* assertEqual((yield* storage.getEntries("timestamp-preserve", 0))[0].timestamp, timestamp, "Timestamp should be preserved exactly");
+		})
+	},
+	{
+		name: "complex transaction operations survive roundtrip",
+		category: Categories.WalEntryIntegrity,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = {
+				transaction: Transaction.make([
+					Operation.fromDefinition(OperationPath.make("a"), TestSetDefinition, 1),
+					Operation.fromDefinition(OperationPath.make("b/c"), TestSetDefinition, "nested"),
+					Operation.fromDefinition(OperationPath.make("arr"), TestSetDefinition, [
+						1,
+						2,
+						3
+					])
+				]),
+				version: 1,
+				timestamp: Date.now()
+			};
+			yield* storage.append("complex-tx", entry);
+			yield* assertEqual((yield* storage.getEntries("complex-tx", 0))[0].transaction, entry.transaction, "Complex transaction should survive roundtrip");
+		})
+	},
+	{
+		name: "different documents have independent entry lists",
+		category: Categories.DocumentIsolation,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("iso-hot-1", makeEntry(1));
+			yield* storage.append("iso-hot-1", makeEntry(2));
+			yield* storage.append("iso-hot-2", makeEntry(10));
+			const entries1 = yield* storage.getEntries("iso-hot-1", 0);
+			const entries2 = yield* storage.getEntries("iso-hot-2", 0);
+			yield* assertLength(entries1, 2, "Doc 1 should have 2 entries");
+			yield* assertLength(entries2, 1, "Doc 2 should have 1 entry");
+			yield* assertEqual(entries1[0].version, 1, "Doc 1 first entry version");
+			yield* assertEqual(entries2[0].version, 10, "Doc 2 first entry version");
+		})
+	},
+	{
+		name: "appending to one doc does not affect others",
+		category: Categories.DocumentIsolation,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("append-iso-1", makeEntry(1));
+			const beforeAppend = yield* storage.getEntries("append-iso-1", 0);
+			yield* storage.append("append-iso-2", makeEntry(100));
+			yield* storage.append("append-iso-2", makeEntry(101));
+			const afterAppend = yield* storage.getEntries("append-iso-1", 0);
+			yield* assertEqual(beforeAppend.length, afterAppend.length, "Appending to doc 2 should not affect doc 1");
+		})
+	},
+	{
+		name: "truncating one doc does not affect others",
+		category: Categories.DocumentIsolation,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("trunc-iso-1", makeEntry(1));
+			yield* storage.append("trunc-iso-1", makeEntry(2));
+			yield* storage.append("trunc-iso-2", makeEntry(1));
+			yield* storage.append("trunc-iso-2", makeEntry(2));
+			yield* storage.truncate("trunc-iso-1", 2);
+			const entries1 = yield* storage.getEntries("trunc-iso-1", 0);
+			const entries2 = yield* storage.getEntries("trunc-iso-2", 0);
+			yield* assertEmpty(entries1, "Doc 1 should be empty after truncate");
+			yield* assertLength(entries2, 2, "Doc 2 should still have 2 entries");
+		})
+	},
+	{
+		name: "handle 1000+ entries per document",
+		category: Categories.LargeScaleOperations,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const count = 1e3;
+			for (let i = 1; i <= count; i++) yield* storage.append("large-entries", makeEntry(i));
+			const entries = yield* storage.getEntries("large-entries", 0);
+			yield* assertLength(entries, count, `Should have ${count} entries`);
+			yield* assertSortedBy(entries, "version", "Should be sorted by version");
+			yield* assertEqual(entries[0].version, 1, "First should be version 1");
+			yield* assertEqual(entries[count - 1].version, count, `Last should be version ${count}`);
+		})
+	},
+	{
+		name: "handle 100+ documents",
+		category: Categories.LargeScaleOperations,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const docCount = 100;
+			for (let i = 0; i < docCount; i++) {
+				yield* storage.append(`multi-doc-${i}`, makeEntry(1));
+				yield* storage.append(`multi-doc-${i}`, makeEntry(2));
+			}
+			let totalEntries = 0;
+			for (let i = 0; i < docCount; i++) {
+				const entries = yield* storage.getEntries(`multi-doc-${i}`, 0);
+				totalEntries += entries.length;
+				yield* assertLength(entries, 2, `Doc ${i} should have 2 entries`);
+			}
+			yield* assertEqual(totalEntries, docCount * 2, "Total entries should match");
+		})
+	},
+	{
+		name: "large transaction data (10KB+) survives roundtrip",
+		category: Categories.LargeScaleOperations,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithData(1, { content: "x".repeat(10 * 1024) });
+			yield* storage.append("large-tx", entry);
+			const entries = yield* storage.getEntries("large-tx", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			yield* assertEqual(entries[0].transaction, entry.transaction, "Large transaction data should survive roundtrip");
+		})
+	},
+	{
+		name: "long documentId (1000+ chars) works",
+		category: Categories.DocumentIdEdgeCases,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const longId = "h".repeat(1e3);
+			const entry = makeEntry(1);
+			yield* storage.append(longId, entry);
+			yield* assertLength(yield* storage.getEntries(longId, 0), 1, "Long documentId should work");
+		})
+	},
+	{
+		name: "unicode documentId works",
+		category: Categories.DocumentIdEdgeCases,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const unicodeId = "hot-doc-id";
+			const entry = makeEntry(1);
+			yield* storage.append(unicodeId, entry);
+			yield* assertLength(yield* storage.getEntries(unicodeId, 0), 1, "Unicode documentId should work");
+		})
+	},
+	{
+		name: "documentId with special chars works",
+		category: Categories.DocumentIdEdgeCases,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const specialId = "hot/path:to.wal";
+			const entry = makeEntry(1);
+			yield* storage.append(specialId, entry);
+			yield* assertLength(yield* storage.getEntries(specialId, 0), 1, "DocumentId with special chars should work");
+		})
+	},
+	{
+		name: "documentId with spaces works",
+		category: Categories.DocumentIdEdgeCases,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const spacedId = "hot doc with spaces";
+			const entry = makeEntry(1);
+			yield* storage.append(spacedId, entry);
+			yield* assertLength(yield* storage.getEntries(spacedId, 0), 1, "DocumentId with spaces should work");
+		})
+	},
+	{
+		name: "version 0 entry is handled correctly",
+		category: Categories.VersionFiltering,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.append("version-0-entry", makeEntry(0));
+			yield* storage.append("version-0-entry", makeEntry(1));
+			yield* assertTrue((yield* storage.getEntries("version-0-entry", -1)).some((e) => e.version === 0), "Version 0 entry should be retrievable with sinceVersion < 0");
+			yield* assertTrue(!(yield* storage.getEntries("version-0-entry", 0)).some((e) => e.version === 0), "Version 0 entry should be excluded with sinceVersion = 0");
+		})
+	},
+	{
+		name: "appendWithCheck succeeds for first entry (expectedVersion=1)",
+		category: Categories.GapChecking,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntry(1);
+			yield* storage.appendWithCheck("gap-check-first", entry, 1);
+			const entries = yield* storage.getEntries("gap-check-first", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			yield* assertEqual(entries[0].version, 1, "Entry version should be 1");
+		})
+	},
+	{
+		name: "appendWithCheck succeeds for consecutive versions",
+		category: Categories.GapChecking,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.appendWithCheck("gap-check-consecutive", makeEntry(1), 1);
+			yield* storage.appendWithCheck("gap-check-consecutive", makeEntry(2), 2);
+			yield* storage.appendWithCheck("gap-check-consecutive", makeEntry(3), 3);
+			const entries = yield* storage.getEntries("gap-check-consecutive", 0);
+			yield* assertLength(entries, 3, "Should have three entries");
+			yield* assertEqual(entries[0].version, 1, "First entry version should be 1");
+			yield* assertEqual(entries[1].version, 2, "Second entry version should be 2");
+			yield* assertEqual(entries[2].version, 3, "Third entry version should be 3");
+		})
+	},
+	{
+		name: "appendWithCheck fails for version gap (skipping version 2)",
+		category: Categories.GapChecking,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.appendWithCheck("gap-check-fail", makeEntry(1), 1);
+			const result = yield* Effect.either(storage.appendWithCheck("gap-check-fail", makeEntry(3), 3));
+			yield* assertTrue(result._tag === "Left", "appendWithCheck should fail when there's a version gap");
+			if (result._tag === "Left") yield* assertTrue(result.left._tag === "WalVersionGapError", "Error should be WalVersionGapError");
+			const entries = yield* storage.getEntries("gap-check-fail", 0);
+			yield* assertLength(entries, 1, "Should only have version 1");
+			yield* assertEqual(entries[0].version, 1, "Only version 1 should exist");
+		})
+	},
+	{
+		name: "appendWithCheck fails if first entry is not version 1",
+		category: Categories.GapChecking,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const result = yield* Effect.either(storage.appendWithCheck("gap-check-not-first", makeEntry(2), 2));
+			yield* assertTrue(result._tag === "Left", "appendWithCheck should fail when first entry is not version 1");
+			if (result._tag === "Left") yield* assertTrue(result.left._tag === "WalVersionGapError", "Error should be WalVersionGapError");
+			yield* assertEmpty(yield* storage.getEntries("gap-check-not-first", 0), "No entries should exist after failed append");
+		})
+	},
+	{
+		name: "appendWithCheck fails when entry already exists at expectedVersion",
+		category: Categories.GapChecking,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.appendWithCheck("gap-check-duplicate", makeEntry(1), 1);
+			yield* assertTrue((yield* Effect.either(storage.appendWithCheck("gap-check-duplicate", makeEntry(1), 1)))._tag === "Left", "appendWithCheck should fail when version already exists");
+			yield* assertLength(yield* storage.getEntries("gap-check-duplicate", 0), 1, "Should still only have one entry");
+		})
+	},
+	{
+		name: "appendWithCheck after truncate works correctly",
+		category: Categories.GapChecking,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			yield* storage.appendWithCheck("gap-check-truncate", makeEntry(1), 1);
+			yield* storage.appendWithCheck("gap-check-truncate", makeEntry(2), 2);
+			yield* storage.appendWithCheck("gap-check-truncate", makeEntry(3), 3);
+			yield* storage.truncate("gap-check-truncate", 2);
+			yield* storage.appendWithCheck("gap-check-truncate", makeEntry(4), 4);
+			const entries = yield* storage.getEntries("gap-check-truncate", 0);
+			yield* assertLength(entries, 2, "Should have versions 3 and 4");
+			yield* assertEqual(entries[0].version, 3, "First should be version 3");
+			yield* assertEqual(entries[1].version, 4, "Second should be version 4");
+		})
+	},
+	{
+		name: "OperationPath has _tag after roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithPath(1, "users/0/name", "Alice");
+			yield* storage.append("op-path-tag", entry);
+			const entries = yield* storage.getEntries("op-path-tag", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			const op = entries[0].transaction.ops[0];
+			yield* assertTrue(op.path._tag === "OperationPath", "path should have _tag 'OperationPath'");
+		})
+	},
+	{
+		name: "OperationPath.toTokens() works after roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithPath(1, "users/0/name", "Alice");
+			yield* storage.append("op-path-tokens", entry);
+			const entries = yield* storage.getEntries("op-path-tokens", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			const op = entries[0].transaction.ops[0];
+			yield* assertTrue(typeof op.path.toTokens === "function", "path.toTokens should be a function");
+			yield* assertEqual(op.path.toTokens(), [
+				"users",
+				"0",
+				"name"
+			], "toTokens() should return correct path tokens");
+		})
+	},
+	{
+		name: "OperationPath.concat() works after roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithPath(1, "users/0", { name: "Alice" });
+			yield* storage.append("op-path-concat", entry);
+			const entries = yield* storage.getEntries("op-path-concat", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			const op = entries[0].transaction.ops[0];
+			yield* assertTrue(typeof op.path.concat === "function", "path.concat should be a function");
+			yield* assertEqual(op.path.concat(OperationPath.make("name")).toTokens(), [
+				"users",
+				"0",
+				"name"
+			], "concat() should work correctly");
+		})
+	},
+	{
+		name: "OperationPath.append() works after roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithPath(1, "users", []);
+			yield* storage.append("op-path-append", entry);
+			const entries = yield* storage.getEntries("op-path-append", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			const op = entries[0].transaction.ops[0];
+			yield* assertTrue(typeof op.path.append === "function", "path.append should be a function");
+			yield* assertEqual(op.path.append("0").toTokens(), ["users", "0"], "append() should work correctly");
+		})
+	},
+	{
+		name: "OperationPath.pop() works after roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithPath(1, "users/0/name", "Alice");
+			yield* storage.append("op-path-pop", entry);
+			const entries = yield* storage.getEntries("op-path-pop", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			const op = entries[0].transaction.ops[0];
+			yield* assertTrue(typeof op.path.pop === "function", "path.pop should be a function");
+			yield* assertEqual(op.path.pop().toTokens(), ["users", "0"], "pop() should remove last token");
+		})
+	},
+	{
+		name: "OperationPath.shift() works after roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithPath(1, "users/0/name", "Alice");
+			yield* storage.append("op-path-shift", entry);
+			const entries = yield* storage.getEntries("op-path-shift", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			const op = entries[0].transaction.ops[0];
+			yield* assertTrue(typeof op.path.shift === "function", "path.shift should be a function");
+			yield* assertEqual(op.path.shift().toTokens(), ["0", "name"], "shift() should remove first token");
+		})
+	},
+	{
+		name: "transaction with multiple operations preserves all OperationPaths",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = {
+				transaction: Transaction.make([
+					Operation.fromDefinition(OperationPath.make("users/0/name"), TestSetDefinition, "Alice"),
+					Operation.fromDefinition(OperationPath.make("users/1/name"), TestSetDefinition, "Bob"),
+					Operation.fromDefinition(OperationPath.make("count"), TestSetDefinition, 2)
+				]),
+				version: 1,
+				timestamp: Date.now()
+			};
+			yield* storage.append("multi-op-paths", entry);
+			const entries = yield* storage.getEntries("multi-op-paths", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			const ops = entries[0].transaction.ops;
+			yield* assertLength([...ops], 3, "Should have 3 operations");
+			for (const op of ops) {
+				yield* assertTrue(op.path._tag === "OperationPath", "Each operation path should have _tag");
+				yield* assertTrue(typeof op.path.toTokens === "function", "Each operation path should have toTokens method");
+			}
+			yield* assertEqual(ops[0].path.toTokens(), [
+				"users",
+				"0",
+				"name"
+			], "First path should be correct");
+			yield* assertEqual(ops[1].path.toTokens(), [
+				"users",
+				"1",
+				"name"
+			], "Second path should be correct");
+			yield* assertEqual(ops[2].path.toTokens(), ["count"], "Third path should be correct");
+		})
+	},
+	{
+		name: "nested path with many segments survives roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithPath(1, "level1/level2/level3/level4/level5", "deep value");
+			yield* storage.append("deep-path", entry);
+			const entries = yield* storage.getEntries("deep-path", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			const op = entries[0].transaction.ops[0];
+			yield* assertEqual(op.path.toTokens(), [
+				"level1",
+				"level2",
+				"level3",
+				"level4",
+				"level5"
+			], "Deep nested path should survive roundtrip");
+		})
+	},
+	{
+		name: "empty path survives roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithPath(1, "", { root: true });
+			yield* storage.append("empty-path", entry);
+			const entries = yield* storage.getEntries("empty-path", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			const op = entries[0].transaction.ops[0];
+			yield* assertTrue(op.path._tag === "OperationPath", "Empty path should still be OperationPath");
+			yield* assertTrue(typeof op.path.toTokens === "function", "Empty path should have toTokens method");
+		})
+	},
+	{
+		name: "transaction id is preserved after roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithPath(1, "test", "value");
+			const originalId = entry.transaction.id;
+			yield* storage.append("tx-id-preserve", entry);
+			const entries = yield* storage.getEntries("tx-id-preserve", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			yield* assertEqual(entries[0].transaction.id, originalId, "Transaction id should be preserved");
+		})
+	},
+	{
+		name: "transaction timestamp is preserved after roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = makeEntryWithPath(1, "test", "value");
+			const originalTimestamp = entry.transaction.timestamp;
+			yield* storage.append("tx-timestamp-preserve", entry);
+			const entries = yield* storage.getEntries("tx-timestamp-preserve", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			yield* assertEqual(entries[0].transaction.timestamp, originalTimestamp, "Transaction timestamp should be preserved");
+		})
+	},
+	{
+		name: "operation kind is preserved after roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const entry = {
+				transaction: Transaction.make([Operation.fromDefinition(OperationPath.make("data"), CustomOpDefinition, "test")]),
+				version: 1,
+				timestamp: Date.now()
+			};
+			yield* storage.append("op-kind-preserve", entry);
+			const entries = yield* storage.getEntries("op-kind-preserve", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			yield* assertEqual(entries[0].transaction.ops[0].kind, "custom.operation", "Operation kind should be preserved");
+		})
+	},
+	{
+		name: "operation payload with complex object survives roundtrip",
+		category: Categories.TransactionEncoding,
+		run: Effect.gen(function* () {
+			const storage = yield* HotStorageTag;
+			const complexPayload = {
+				nested: {
+					value: 42,
+					array: [
+						1,
+						2,
+						3
+					]
+				},
+				nullValue: null,
+				string: "test"
+			};
+			const entry = makeEntryWithPath(1, "data", complexPayload);
+			yield* storage.append("complex-payload", entry);
+			const entries = yield* storage.getEntries("complex-payload", 0);
+			yield* assertLength(entries, 1, "Should have one entry");
+			yield* assertEqual(entries[0].transaction.ops[0].payload, complexPayload, "Complex payload should survive roundtrip");
+		})
+	}
+];
+/**
+* Get all HotStorage test cases.
+*
+* @returns Array of test cases that require HotStorageTag
+*/
+const makeTests = () => tests;
+/**
+* Run all tests and collect results.
+*
+* @returns Effect that produces TestResults
+*/
+const runAll = () => Effect.gen(function* () {
+	const passed = [];
+	const failed = [];
+	for (const test of tests) {
+		const result = yield* Effect.either(test.run);
+		if (result._tag === "Right") passed.push(test);
+		else failed.push({
+			test,
+			error: result.left
+		});
+	}
+	return {
+		passed,
+		failed,
+		total: tests.length,
+		passCount: passed.length,
+		failCount: failed.length
+	};
+});
+const HotStorageTestSuite = {
+	Categories,
+	makeTests,
+	runAll
+};
+
+//#endregion
+export { Categories, HotStorageTestSuite };
+//# sourceMappingURL=HotStorageTestSuite.mjs.map