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

package/dist/HotStorage.mjs

@@ -1,3 +1,4 @@
+import { WalVersionGapError } from "./Errors.mjs";
 import { Context, Effect, HashMap, Layer, Ref } from "effect";
 
 //#region src/HotStorage.ts
@@ -44,27 +45,54 @@ var HotStorageTag = class extends Context.Tag("@voidhash/mimic-effect/HotStorage
 const make = (effect) => Layer.effect(HotStorageTag, effect);
 let InMemory;
 (function(_InMemory) {
-	_InMemory.make = () => Layer.effect(HotStorageTag, Effect.gen(function* () {
+	_InMemory.make = () => Layer.effect(HotStorageTag, Effect.fn("hot-storage.in-memory.create")(function* () {
 		const store = yield* Ref.make(HashMap.empty());
 		return {
-			append: (documentId, entry) => Ref.update(store, (map) => {
-				const existing = HashMap.get(map, documentId);
-				const entries = existing._tag === "Some" ? existing.value : [];
-				return HashMap.set(map, documentId, [...entries, entry]);
+			append: Effect.fn("hot-storage.append")(function* (documentId, entry) {
+				yield* Ref.update(store, (map) => {
+					const existing = HashMap.get(map, documentId);
+					const entries = existing._tag === "Some" ? existing.value : [];
+					return HashMap.set(map, documentId, [...entries, entry]);
+				});
 			}),
-			getEntries: (documentId, sinceVersion) => Effect.gen(function* () {
+			appendWithCheck: Effect.fn("hot-storage.append-with-check")(function* (documentId, entry, expectedVersion, baseVersion) {
+				const result = yield* Ref.modify(store, (map) => {
+					const existing = HashMap.get(map, documentId);
+					const entries = existing._tag === "Some" ? existing.value : [];
+					const lastEntryVersion = entries.length > 0 ? Math.max(...entries.map((e) => e.version)) : 0;
+					const effectiveLastVersion = baseVersion !== void 0 ? Math.max(lastEntryVersion, baseVersion) : lastEntryVersion;
+					if (expectedVersion === 1) {
+						if (effectiveLastVersion >= 1) return [{
+							type: "gap",
+							lastVersion: effectiveLastVersion
+						}, map];
+					} else if (effectiveLastVersion !== expectedVersion - 1) return [{
+						type: "gap",
+						lastVersion: effectiveLastVersion > 0 ? effectiveLastVersion : void 0
+					}, map];
+					return [{ type: "ok" }, HashMap.set(map, documentId, [...entries, entry])];
+				});
+				if (result.type === "gap") return yield* Effect.fail(new WalVersionGapError({
+					documentId,
+					expectedVersion,
+					actualPreviousVersion: result.lastVersion
+				}));
+			}),
+			getEntries: Effect.fn("hot-storage.get-entries")(function* (documentId, sinceVersion) {
 				const current = yield* Ref.get(store);
 				const existing = HashMap.get(current, documentId);
 				return (existing._tag === "Some" ? existing.value : []).filter((e) => e.version > sinceVersion).sort((a, b) => a.version - b.version);
 			}),
-			truncate: (documentId, upToVersion) => Ref.update(store, (map) => {
-				const existing = HashMap.get(map, documentId);
-				if (existing._tag === "None") return map;
-				const filtered = existing.value.filter((e) => e.version > upToVersion);
-				return HashMap.set(map, documentId, filtered);
+			truncate: Effect.fn("hot-storage.truncate")(function* (documentId, upToVersion) {
+				yield* Ref.update(store, (map) => {
+					const existing = HashMap.get(map, documentId);
+					if (existing._tag === "None") return map;
+					const filtered = existing.value.filter((e) => e.version > upToVersion);
+					return HashMap.set(map, documentId, filtered);
+				});
 			})
 		};
-	}));
+	})());
 })(InMemory || (InMemory = {}));
 const HotStorage = {
 	Tag: HotStorageTag,

package/dist/HotStorage.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"HotStorage.mjs","names":[],"sources":["../src/HotStorage.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - HotStorage\n *\n * Interface and implementations for Write-Ahead Log (WAL) storage.\n */\nimport { Context, Effect, HashMap, Layer, Ref } from \"effect\";\nimport type { WalEntry } from \"./Types\";\nimport { HotStorageError } from \"./Errors\";\n\n// =============================================================================\n// HotStorage Interface\n// =============================================================================\n\n/**\n * HotStorage interface for storing Write-Ahead Log entries.\n *\n * This is the \"hot\" tier of the two-tier storage system.\n * It stores every transaction as a WAL entry for durability between snapshots.\n * WAL entries are small (just the transaction) and writes are append-only.\n */\nexport interface HotStorage {\n  /**\n   * Append a WAL entry for a document.\n   */\n  readonly append: (\n    documentId: string,\n    entry: WalEntry\n  ) => Effect.Effect<void, HotStorageError>;\n\n  /**\n   * Get all WAL entries for a document since a given version.\n   * Returns entries with version > sinceVersion, ordered by version.\n   */\n  readonly getEntries: (\n    documentId: string,\n    sinceVersion: number\n  ) => Effect.Effect<WalEntry[], HotStorageError>;\n\n  /**\n   * Truncate WAL entries up to (and including) a given version.\n   * Called after a snapshot is saved to remove entries that are now in the snapshot.\n   */\n  readonly truncate: (\n    documentId: string,\n    upToVersion: number\n  ) => Effect.Effect<void, HotStorageError>;\n}\n\n// =============================================================================\n// Context Tag\n// =============================================================================\n\n/**\n * Context tag for HotStorage service\n */\nexport class HotStorageTag extends Context.Tag(\"@voidhash/mimic-effect/HotStorage\")<\n  HotStorageTag,\n  HotStorage\n>() {}\n\n// =============================================================================\n// Factory\n// =============================================================================\n\n/**\n * Create a HotStorage layer from an Effect that produces a HotStorage service.\n *\n * This allows you to access other Effect services when implementing custom storage.\n *\n * @example\n * ```typescript\n * const Hot = HotStorage.make(\n *   Effect.gen(function*() {\n *     const redis = yield* RedisService\n *\n *     return {\n *       append: (documentId, entry) =>\n *         redis.rpush(`wal:${documentId}`, JSON.stringify(entry)),\n *       getEntries: (documentId, sinceVersion) =>\n *         redis.lrange(`wal:${documentId}`, 0, -1).pipe(\n *           Effect.map(entries =>\n *             entries\n *               .map(e => JSON.parse(e))\n *               .filter(e => e.version > sinceVersion)\n *               .sort((a, b) => a.version - b.version)\n *           )\n *         ),\n *       truncate: (documentId, upToVersion) =>\n *         // Implementation depends on Redis data structure\n *         Effect.void,\n *     }\n *   })\n * )\n * ```\n */\nexport const make = <E, R>(\n  effect: Effect.Effect<HotStorage, E, R>\n): Layer.Layer<HotStorageTag, E, R> =>\n  Layer.effect(HotStorageTag, effect);\n\n// =============================================================================\n// InMemory Implementation\n// =============================================================================\n\n/**\n * In-memory HotStorage implementation.\n *\n * Useful for testing and development. Not suitable for production\n * as data is lost when the process restarts.\n */\nexport namespace InMemory {\n  /**\n   * Create an in-memory HotStorage layer.\n   */\n  export const make = (): Layer.Layer<HotStorageTag> =>\n    Layer.effect(\n      HotStorageTag,\n      Effect.gen(function* () {\n        const store = yield* Ref.make(HashMap.empty<string, WalEntry[]>());\n\n        return {\n          append: (documentId, entry) =>\n            Ref.update(store, (map) => {\n              const existing = HashMap.get(map, documentId);\n              const entries =\n                existing._tag === \"Some\" ? existing.value : [];\n              return HashMap.set(map, documentId, [...entries, entry]);\n            }),\n\n          getEntries: (documentId, sinceVersion) =>\n            Effect.gen(function* () {\n              const current = yield* Ref.get(store);\n              const existing = HashMap.get(current, documentId);\n              const entries =\n                existing._tag === \"Some\" ? existing.value : [];\n              return entries\n                .filter((e) => e.version > sinceVersion)\n                .sort((a, b) => a.version - b.version);\n            }),\n\n          truncate: (documentId, upToVersion) =>\n            Ref.update(store, (map) => {\n              const existing = HashMap.get(map, documentId);\n              if (existing._tag === \"None\") {\n                return map;\n              }\n              const filtered = existing.value.filter(\n                (e) => e.version > upToVersion\n              );\n              return HashMap.set(map, documentId, filtered);\n            }),\n        };\n      })\n    );\n}\n\n// =============================================================================\n// Re-export namespace\n// =============================================================================\n\nexport const HotStorage = {\n  Tag: HotStorageTag,\n  make,\n  InMemory,\n};\n"],"mappings":";;;;;;;;;;;AAuDA,IAAa,gBAAb,cAAmC,QAAQ,IAAI,oCAAoC,EAGhF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCJ,MAAa,QACX,WAEA,MAAM,OAAO,eAAe,OAAO;;;wBAiBjC,MAAM,OACJ,eACA,OAAO,IAAI,aAAa;EACtB,MAAM,QAAQ,OAAO,IAAI,KAAK,QAAQ,OAA2B,CAAC;AAElE,SAAO;GACL,SAAS,YAAY,UACnB,IAAI,OAAO,QAAQ,QAAQ;IACzB,MAAM,WAAW,QAAQ,IAAI,KAAK,WAAW;IAC7C,MAAM,UACJ,SAAS,SAAS,SAAS,SAAS,QAAQ,EAAE;AAChD,WAAO,QAAQ,IAAI,KAAK,YAAY,CAAC,GAAG,SAAS,MAAM,CAAC;KACxD;GAEJ,aAAa,YAAY,iBACvB,OAAO,IAAI,aAAa;IACtB,MAAM,UAAU,OAAO,IAAI,IAAI,MAAM;IACrC,MAAM,WAAW,QAAQ,IAAI,SAAS,WAAW;AAGjD,YADE,SAAS,SAAS,SAAS,SAAS,QAAQ,EAAE,EAE7C,QAAQ,MAAM,EAAE,UAAU,aAAa,CACvC,MAAM,GAAG,MAAM,EAAE,UAAU,EAAE,QAAQ;KACxC;GAEJ,WAAW,YAAY,gBACrB,IAAI,OAAO,QAAQ,QAAQ;IACzB,MAAM,WAAW,QAAQ,IAAI,KAAK,WAAW;AAC7C,QAAI,SAAS,SAAS,OACpB,QAAO;IAET,MAAM,WAAW,SAAS,MAAM,QAC7B,MAAM,EAAE,UAAU,YACpB;AACD,WAAO,QAAQ,IAAI,KAAK,YAAY,SAAS;KAC7C;GACL;GACD,CACH;;AAOL,MAAa,aAAa;CACxB,KAAK;CACL;CACA;CACD"}
+{"version":3,"file":"HotStorage.mjs","names":["result: CheckResult"],"sources":["../src/HotStorage.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - HotStorage\n *\n * Interface and implementations for Write-Ahead Log (WAL) storage.\n */\nimport { Context, Effect, HashMap, Layer, Ref } from \"effect\";\nimport type { WalEntry } from \"./Types\";\nimport { HotStorageError, WalVersionGapError } from \"./Errors\";\n\n// =============================================================================\n// HotStorage Interface\n// =============================================================================\n\n/**\n * HotStorage interface for storing Write-Ahead Log entries.\n *\n * This is the \"hot\" tier of the two-tier storage system.\n * It stores every transaction as a WAL entry for durability between snapshots.\n * WAL entries are small (just the transaction) and writes are append-only.\n */\nexport interface HotStorage {\n  /**\n   * Append a WAL entry for a document.\n   */\n  readonly append: (\n    documentId: string,\n    entry: WalEntry\n  ) => Effect.Effect<void, HotStorageError>;\n\n  /**\n   * Append a WAL entry with version gap checking.\n   *\n   * This is an atomic operation that:\n   * 1. Verifies the previous entry has version = expectedVersion - 1\n   *    (or this is the first entry if expectedVersion === 1, accounting for baseVersion)\n   * 2. Appends the entry if check passes\n   *\n   * Use this for two-phase commit to guarantee WAL ordering at write time.\n   *\n   * @param documentId - Document ID\n   * @param entry - WAL entry to append\n   * @param expectedVersion - The version this entry should have (entry.version)\n   * @param baseVersion - Optional known snapshot version. When provided, an empty WAL\n   *                      is treated as \"at this version\" rather than \"new document at version 0\".\n   *                      This is necessary after truncation or restart to correctly validate\n   *                      that the next entry is baseVersion + 1.\n   * @returns Effect that fails with WalVersionGapError if gap detected\n   */\n  readonly appendWithCheck: (\n    documentId: string,\n    entry: WalEntry,\n    expectedVersion: number,\n    baseVersion?: number\n  ) => Effect.Effect<void, HotStorageError | WalVersionGapError>;\n\n  /**\n   * Get all WAL entries for a document since a given version.\n   * Returns entries with version > sinceVersion, ordered by version.\n   */\n  readonly getEntries: (\n    documentId: string,\n    sinceVersion: number\n  ) => Effect.Effect<WalEntry[], HotStorageError>;\n\n  /**\n   * Truncate WAL entries up to (and including) a given version.\n   * Called after a snapshot is saved to remove entries that are now in the snapshot.\n   */\n  readonly truncate: (\n    documentId: string,\n    upToVersion: number\n  ) => Effect.Effect<void, HotStorageError>;\n}\n\n// =============================================================================\n// Context Tag\n// =============================================================================\n\n/**\n * Context tag for HotStorage service\n */\nexport class HotStorageTag extends Context.Tag(\"@voidhash/mimic-effect/HotStorage\")<\n  HotStorageTag,\n  HotStorage\n>() {}\n\n// =============================================================================\n// Factory\n// =============================================================================\n\n/**\n * Create a HotStorage layer from an Effect that produces a HotStorage service.\n *\n * This allows you to access other Effect services when implementing custom storage.\n *\n * @example\n * ```typescript\n * const Hot = HotStorage.make(\n *   Effect.gen(function*() {\n *     const redis = yield* RedisService\n *\n *     return {\n *       append: (documentId, entry) =>\n *         redis.rpush(`wal:${documentId}`, JSON.stringify(entry)),\n *       getEntries: (documentId, sinceVersion) =>\n *         redis.lrange(`wal:${documentId}`, 0, -1).pipe(\n *           Effect.map(entries =>\n *             entries\n *               .map(e => JSON.parse(e))\n *               .filter(e => e.version > sinceVersion)\n *               .sort((a, b) => a.version - b.version)\n *           )\n *         ),\n *       truncate: (documentId, upToVersion) =>\n *         // Implementation depends on Redis data structure\n *         Effect.void,\n *     }\n *   })\n * )\n * ```\n */\nexport const make = <E, R>(\n  effect: Effect.Effect<HotStorage, E, R>\n): Layer.Layer<HotStorageTag, E, R> =>\n  Layer.effect(HotStorageTag, effect);\n\n// =============================================================================\n// InMemory Implementation\n// =============================================================================\n\n/**\n * In-memory HotStorage implementation.\n *\n * Useful for testing and development. Not suitable for production\n * as data is lost when the process restarts.\n */\nexport namespace InMemory {\n  /**\n   * Create an in-memory HotStorage layer.\n   */\n  export const make = (): Layer.Layer<HotStorageTag> =>\n    Layer.effect(\n      HotStorageTag,\n      Effect.fn(\"hot-storage.in-memory.create\")(function* () {\n        const store = yield* Ref.make(HashMap.empty<string, WalEntry[]>());\n\n        return {\n          append: Effect.fn(\"hot-storage.append\")(\n            function* (documentId: string, entry: WalEntry) {\n              yield* Ref.update(store, (map) => {\n                const existing = HashMap.get(map, documentId);\n                const entries =\n                  existing._tag === \"Some\" ? existing.value : [];\n                return HashMap.set(map, documentId, [...entries, entry]);\n              });\n            }\n          ),\n\n          appendWithCheck: Effect.fn(\"hot-storage.append-with-check\")(\n            function* (\n              documentId: string,\n              entry: WalEntry,\n              expectedVersion: number,\n              baseVersion?: number\n            ) {\n              type CheckResult =\n                | { type: \"ok\" }\n                | { type: \"gap\"; lastVersion: number | undefined };\n\n              // Use Ref.modify for atomic check + update\n              const result: CheckResult = yield* Ref.modify(\n                store,\n                (map): [CheckResult, HashMap.HashMap<string, WalEntry[]>] => {\n                  const existing = HashMap.get(map, documentId);\n                  const entries =\n                    existing._tag === \"Some\" ? existing.value : [];\n\n                  // Find the highest version in existing entries\n                  const lastEntryVersion =\n                    entries.length > 0\n                      ? Math.max(...entries.map((e) => e.version))\n                      : 0;\n\n                  // Effective \"last version\" is max of entries and baseVersion\n                  // This handles the case after truncation or restart where\n                  // WAL is empty but we know the snapshot version\n                  const effectiveLastVersion =\n                    baseVersion !== undefined\n                      ? Math.max(lastEntryVersion, baseVersion)\n                      : lastEntryVersion;\n\n                  // Gap check\n                  if (expectedVersion === 1) {\n                    // First entry: should have no entries with version >= 1\n                    // and baseVersion should be 0 or undefined\n                    if (effectiveLastVersion >= 1) {\n                      return [{ type: \"gap\", lastVersion: effectiveLastVersion }, map];\n                    }\n                  } else {\n                    // Not first: effective last version should be expectedVersion - 1\n                    if (effectiveLastVersion !== expectedVersion - 1) {\n                      return [\n                        {\n                          type: \"gap\",\n                          lastVersion: effectiveLastVersion > 0 ? effectiveLastVersion : undefined,\n                        },\n                        map,\n                      ];\n                    }\n                  }\n\n                  // No gap: append and return success\n                  return [\n                    { type: \"ok\" },\n                    HashMap.set(map, documentId, [...entries, entry]),\n                  ];\n                }\n              );\n\n              if (result.type === \"gap\") {\n                return yield* Effect.fail(\n                  new WalVersionGapError({\n                    documentId,\n                    expectedVersion,\n                    actualPreviousVersion: result.lastVersion,\n                  })\n                );\n              }\n            }\n          ),\n\n          getEntries: Effect.fn(\"hot-storage.get-entries\")(\n            function* (documentId: string, sinceVersion: number) {\n              const current = yield* Ref.get(store);\n              const existing = HashMap.get(current, documentId);\n              const entries =\n                existing._tag === \"Some\" ? existing.value : [];\n              return entries\n                .filter((e) => e.version > sinceVersion)\n                .sort((a, b) => a.version - b.version);\n            }\n          ),\n\n          truncate: Effect.fn(\"hot-storage.truncate\")(\n            function* (documentId: string, upToVersion: number) {\n              yield* Ref.update(store, (map) => {\n                const existing = HashMap.get(map, documentId);\n                if (existing._tag === \"None\") {\n                  return map;\n                }\n                const filtered = existing.value.filter(\n                  (e) => e.version > upToVersion\n                );\n                return HashMap.set(map, documentId, filtered);\n              });\n            }\n          ),\n        };\n      })()\n    );\n}\n\n// =============================================================================\n// Re-export namespace\n// =============================================================================\n\nexport const HotStorage = {\n  Tag: HotStorageTag,\n  make,\n  InMemory,\n};\n"],"mappings":";;;;;;;;;;;;AAiFA,IAAa,gBAAb,cAAmC,QAAQ,IAAI,oCAAoC,EAGhF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCJ,MAAa,QACX,WAEA,MAAM,OAAO,eAAe,OAAO;;;wBAiBjC,MAAM,OACJ,eACA,OAAO,GAAG,+BAA+B,CAAC,aAAa;EACrD,MAAM,QAAQ,OAAO,IAAI,KAAK,QAAQ,OAA2B,CAAC;AAElE,SAAO;GACL,QAAQ,OAAO,GAAG,qBAAqB,CACrC,WAAW,YAAoB,OAAiB;AAC9C,WAAO,IAAI,OAAO,QAAQ,QAAQ;KAChC,MAAM,WAAW,QAAQ,IAAI,KAAK,WAAW;KAC7C,MAAM,UACJ,SAAS,SAAS,SAAS,SAAS,QAAQ,EAAE;AAChD,YAAO,QAAQ,IAAI,KAAK,YAAY,CAAC,GAAG,SAAS,MAAM,CAAC;MACxD;KAEL;GAED,iBAAiB,OAAO,GAAG,gCAAgC,CACzD,WACE,YACA,OACA,iBACA,aACA;IAMA,MAAMA,SAAsB,OAAO,IAAI,OACrC,QACC,QAA4D;KAC3D,MAAM,WAAW,QAAQ,IAAI,KAAK,WAAW;KAC7C,MAAM,UACJ,SAAS,SAAS,SAAS,SAAS,QAAQ,EAAE;KAGhD,MAAM,mBACJ,QAAQ,SAAS,IACb,KAAK,IAAI,GAAG,QAAQ,KAAK,MAAM,EAAE,QAAQ,CAAC,GAC1C;KAKN,MAAM,uBACJ,gBAAgB,SACZ,KAAK,IAAI,kBAAkB,YAAY,GACvC;AAGN,SAAI,oBAAoB,GAGtB;UAAI,wBAAwB,EAC1B,QAAO,CAAC;OAAE,MAAM;OAAO,aAAa;OAAsB,EAAE,IAAI;gBAI9D,yBAAyB,kBAAkB,EAC7C,QAAO,CACL;MACE,MAAM;MACN,aAAa,uBAAuB,IAAI,uBAAuB;MAChE,EACD,IACD;AAKL,YAAO,CACL,EAAE,MAAM,MAAM,EACd,QAAQ,IAAI,KAAK,YAAY,CAAC,GAAG,SAAS,MAAM,CAAC,CAClD;MAEJ;AAED,QAAI,OAAO,SAAS,MAClB,QAAO,OAAO,OAAO,KACnB,IAAI,mBAAmB;KACrB;KACA;KACA,uBAAuB,OAAO;KAC/B,CAAC,CACH;KAGN;GAED,YAAY,OAAO,GAAG,0BAA0B,CAC9C,WAAW,YAAoB,cAAsB;IACnD,MAAM,UAAU,OAAO,IAAI,IAAI,MAAM;IACrC,MAAM,WAAW,QAAQ,IAAI,SAAS,WAAW;AAGjD,YADE,SAAS,SAAS,SAAS,SAAS,QAAQ,EAAE,EAE7C,QAAQ,MAAM,EAAE,UAAU,aAAa,CACvC,MAAM,GAAG,MAAM,EAAE,UAAU,EAAE,QAAQ;KAE3C;GAED,UAAU,OAAO,GAAG,uBAAuB,CACzC,WAAW,YAAoB,aAAqB;AAClD,WAAO,IAAI,OAAO,QAAQ,QAAQ;KAChC,MAAM,WAAW,QAAQ,IAAI,KAAK,WAAW;AAC7C,SAAI,SAAS,SAAS,OACpB,QAAO;KAET,MAAM,WAAW,SAAS,MAAM,QAC7B,MAAM,EAAE,UAAU,YACpB;AACD,YAAO,QAAQ,IAAI,KAAK,YAAY,SAAS;MAC7C;KAEL;GACF;GACD,EAAE,CACL;;AAOL,MAAa,aAAa;CACxB,KAAK;CACL;CACA;CACD"}

package/dist/Metrics.cjs

@@ -63,6 +63,10 @@ const transactionsLatency = effect.Metric.histogram("mimic.transactions.latency_
 */
 const storageSnapshots = effect.Metric.counter("mimic.storage.snapshots");
 /**
+* Snapshots triggered by idle document detection
+*/
+const storageIdleSnapshots = effect.Metric.counter("mimic.storage.idle_snapshots");
+/**
 * Snapshot save duration histogram (milliseconds)
 */
 const storageSnapshotLatency = effect.Metric.histogram("mimic.storage.snapshot_latency_ms", effect.MetricBoundaries.exponential({
@@ -75,6 +79,22 @@ const storageSnapshotLatency = effect.Metric.histogram("mimic.storage.snapshot_l
 */
 const storageWalAppends = effect.Metric.counter("mimic.storage.wal_appends");
 /**
+* Version gaps detected during WAL replay
+*/
+const storageVersionGaps = effect.Metric.counter("mimic.storage.version_gaps");
+/**
+* Failed WAL appends causing transaction rollback
+*/
+const walAppendFailures = effect.Metric.counter("mimic.storage.wal_append_failures");
+/**
+* ColdStorage load failures during document restore
+*/
+const coldStorageLoadFailures = effect.Metric.counter("mimic.storage.cold_load_failures");
+/**
+* HotStorage getEntries failures during document restore
+*/
+const hotStorageLoadFailures = effect.Metric.counter("mimic.storage.hot_load_failures");
+/**
 * Presence set operations
 */
 const presenceUpdates = effect.Metric.counter("mimic.presence.updates");
@@ -95,8 +115,13 @@ const MimicMetrics = {
 	transactionsRejected,
 	transactionsLatency,
 	storageSnapshots,
+	storageIdleSnapshots,
 	storageSnapshotLatency,
 	storageWalAppends,
+	storageVersionGaps,
+	walAppendFailures,
+	coldStorageLoadFailures,
+	hotStorageLoadFailures,
 	presenceUpdates,
 	presenceActive
 };
@@ -113,9 +138,12 @@ exports.documentsEvicted = documentsEvicted;
 exports.documentsRestored = documentsRestored;
 exports.presenceActive = presenceActive;
 exports.presenceUpdates = presenceUpdates;
+exports.storageIdleSnapshots = storageIdleSnapshots;
 exports.storageSnapshotLatency = storageSnapshotLatency;
 exports.storageSnapshots = storageSnapshots;
+exports.storageVersionGaps = storageVersionGaps;
 exports.storageWalAppends = storageWalAppends;
 exports.transactionsLatency = transactionsLatency;
 exports.transactionsProcessed = transactionsProcessed;
-exports.transactionsRejected = transactionsRejected;
+exports.transactionsRejected = transactionsRejected;
+exports.walAppendFailures = walAppendFailures;

package/dist/Metrics.d.cts

@@ -17,8 +17,13 @@ declare const MimicMetrics: {
   transactionsRejected: Metric.Metric.Counter<number>;
   transactionsLatency: Metric.Metric<effect_MetricKeyType0.MetricKeyType.Histogram, number, effect_MetricState0.MetricState.Histogram>;
   storageSnapshots: Metric.Metric.Counter<number>;
+  storageIdleSnapshots: Metric.Metric.Counter<number>;
   storageSnapshotLatency: Metric.Metric<effect_MetricKeyType0.MetricKeyType.Histogram, number, effect_MetricState0.MetricState.Histogram>;
   storageWalAppends: Metric.Metric.Counter<number>;
+  storageVersionGaps: Metric.Metric.Counter<number>;
+  walAppendFailures: Metric.Metric.Counter<number>;
+  coldStorageLoadFailures: Metric.Metric.Counter<number>;
+  hotStorageLoadFailures: Metric.Metric.Counter<number>;
   presenceUpdates: Metric.Metric.Counter<number>;
   presenceActive: Metric.Metric.Gauge<number>;
 };

package/dist/Metrics.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"Metrics.d.cts","names":[],"sources":["../src/Metrics.ts"],"sourcesContent":[],"mappings":";;;;;;cAwIa"}
+{"version":3,"file":"Metrics.d.cts","names":[],"sources":["../src/Metrics.ts"],"sourcesContent":[],"mappings":";;;;;;cAiKa"}

package/dist/Metrics.d.mts

@@ -17,8 +17,13 @@ declare const MimicMetrics: {
   transactionsRejected: Metric.Metric.Counter<number>;
   transactionsLatency: Metric.Metric<effect_MetricKeyType0.MetricKeyType.Histogram, number, effect_MetricState0.MetricState.Histogram>;
   storageSnapshots: Metric.Metric.Counter<number>;
+  storageIdleSnapshots: Metric.Metric.Counter<number>;
   storageSnapshotLatency: Metric.Metric<effect_MetricKeyType0.MetricKeyType.Histogram, number, effect_MetricState0.MetricState.Histogram>;
   storageWalAppends: Metric.Metric.Counter<number>;
+  storageVersionGaps: Metric.Metric.Counter<number>;
+  walAppendFailures: Metric.Metric.Counter<number>;
+  coldStorageLoadFailures: Metric.Metric.Counter<number>;
+  hotStorageLoadFailures: Metric.Metric.Counter<number>;
   presenceUpdates: Metric.Metric.Counter<number>;
   presenceActive: Metric.Metric.Gauge<number>;
 };

package/dist/Metrics.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"Metrics.d.mts","names":[],"sources":["../src/Metrics.ts"],"sourcesContent":[],"mappings":";;;;;;cAwIa"}
+{"version":3,"file":"Metrics.d.mts","names":[],"sources":["../src/Metrics.ts"],"sourcesContent":[],"mappings":";;;;;;cAiKa"}

package/dist/Metrics.mjs

@@ -63,6 +63,10 @@ const transactionsLatency = Metric.histogram("mimic.transactions.latency_ms", Me
 */
 const storageSnapshots = Metric.counter("mimic.storage.snapshots");
 /**
+* Snapshots triggered by idle document detection
+*/
+const storageIdleSnapshots = Metric.counter("mimic.storage.idle_snapshots");
+/**
 * Snapshot save duration histogram (milliseconds)
 */
 const storageSnapshotLatency = Metric.histogram("mimic.storage.snapshot_latency_ms", MetricBoundaries.exponential({
@@ -75,6 +79,22 @@ const storageSnapshotLatency = Metric.histogram("mimic.storage.snapshot_latency_
 */
 const storageWalAppends = Metric.counter("mimic.storage.wal_appends");
 /**
+* Version gaps detected during WAL replay
+*/
+const storageVersionGaps = Metric.counter("mimic.storage.version_gaps");
+/**
+* Failed WAL appends causing transaction rollback
+*/
+const walAppendFailures = Metric.counter("mimic.storage.wal_append_failures");
+/**
+* ColdStorage load failures during document restore
+*/
+const coldStorageLoadFailures = Metric.counter("mimic.storage.cold_load_failures");
+/**
+* HotStorage getEntries failures during document restore
+*/
+const hotStorageLoadFailures = Metric.counter("mimic.storage.hot_load_failures");
+/**
 * Presence set operations
 */
 const presenceUpdates = Metric.counter("mimic.presence.updates");
@@ -95,12 +115,17 @@ const MimicMetrics = {
 	transactionsRejected,
 	transactionsLatency,
 	storageSnapshots,
+	storageIdleSnapshots,
 	storageSnapshotLatency,
 	storageWalAppends,
+	storageVersionGaps,
+	walAppendFailures,
+	coldStorageLoadFailures,
+	hotStorageLoadFailures,
 	presenceUpdates,
 	presenceActive
 };
 
 //#endregion
-export { MimicMetrics, connectionsActive, connectionsDuration, connectionsErrors, connectionsTotal, documentsActive, documentsCreated, documentsEvicted, documentsRestored, presenceActive, presenceUpdates, storageSnapshotLatency, storageSnapshots, storageWalAppends, transactionsLatency, transactionsProcessed, transactionsRejected };
+export { MimicMetrics, connectionsActive, connectionsDuration, connectionsErrors, connectionsTotal, documentsActive, documentsCreated, documentsEvicted, documentsRestored, presenceActive, presenceUpdates, storageIdleSnapshots, storageSnapshotLatency, storageSnapshots, storageVersionGaps, storageWalAppends, transactionsLatency, transactionsProcessed, transactionsRejected, walAppendFailures };
 //# sourceMappingURL=Metrics.mjs.map

package/dist/Metrics.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Metrics.mjs","names":[],"sources":["../src/Metrics.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - Metrics\n *\n * Observability metrics using Effect's Metric API.\n */\nimport { Metric, MetricBoundaries } from \"effect\";\n\n// =============================================================================\n// Connection Metrics\n// =============================================================================\n\n/**\n * Current active WebSocket connections\n */\nexport const connectionsActive = Metric.gauge(\"mimic.connections.active\");\n\n/**\n * Total connections over lifetime\n */\nexport const connectionsTotal = Metric.counter(\"mimic.connections.total\");\n\n/**\n * Connection duration histogram (milliseconds)\n */\nexport const connectionsDuration = Metric.histogram(\n  \"mimic.connections.duration_ms\",\n  MetricBoundaries.exponential({\n    start: 100,\n    factor: 2,\n    count: 15, // Up to ~3.2 million ms (~53 minutes)\n  })\n);\n\n/**\n * Connection errors (auth failures, etc.)\n */\nexport const connectionsErrors = Metric.counter(\"mimic.connections.errors\");\n\n// =============================================================================\n// Document Metrics\n// =============================================================================\n\n/**\n * Documents currently in memory\n */\nexport const documentsActive = Metric.gauge(\"mimic.documents.active\");\n\n/**\n * New documents created\n */\nexport const documentsCreated = Metric.counter(\"mimic.documents.created\");\n\n/**\n * Documents restored from storage\n */\nexport const documentsRestored = Metric.counter(\"mimic.documents.restored\");\n\n/**\n * Documents garbage collected (evicted)\n */\nexport const documentsEvicted = Metric.counter(\"mimic.documents.evicted\");\n\n// =============================================================================\n// Transaction Metrics\n// =============================================================================\n\n/**\n * Successfully processed transactions\n */\nexport const transactionsProcessed = Metric.counter(\n  \"mimic.transactions.processed\"\n);\n\n/**\n * Rejected transactions\n */\nexport const transactionsRejected = Metric.counter(\n  \"mimic.transactions.rejected\"\n);\n\n/**\n * Transaction processing latency histogram (milliseconds)\n */\nexport const transactionsLatency = Metric.histogram(\n  \"mimic.transactions.latency_ms\",\n  MetricBoundaries.exponential({\n    start: 0.1,\n    factor: 2,\n    count: 15, // Up to ~1638 ms\n  })\n);\n\n// =============================================================================\n// Storage Metrics\n// =============================================================================\n\n/**\n * Snapshots saved to ColdStorage\n */\nexport const storageSnapshots = Metric.counter(\"mimic.storage.snapshots\");\n\n/**\n * Snapshot save duration histogram (milliseconds)\n */\nexport const storageSnapshotLatency = Metric.histogram(\n  \"mimic.storage.snapshot_latency_ms\",\n  MetricBoundaries.exponential({\n    start: 1,\n    factor: 2,\n    count: 12, // Up to ~4 seconds\n  })\n);\n\n/**\n * WAL entries written to HotStorage\n */\nexport const storageWalAppends = Metric.counter(\"mimic.storage.wal_appends\");\n\n// =============================================================================\n// Presence Metrics\n// =============================================================================\n\n/**\n * Presence set operations\n */\nexport const presenceUpdates = Metric.counter(\"mimic.presence.updates\");\n\n/**\n * Active presence entries\n */\nexport const presenceActive = Metric.gauge(\"mimic.presence.active\");\n\n// =============================================================================\n// Export namespace\n// =============================================================================\n\nexport const MimicMetrics = {\n  // Connection\n  connectionsActive,\n  connectionsTotal,\n  connectionsDuration,\n  connectionsErrors,\n\n  // Document\n  documentsActive,\n  documentsCreated,\n  documentsRestored,\n  documentsEvicted,\n\n  // Transaction\n  transactionsProcessed,\n  transactionsRejected,\n  transactionsLatency,\n\n  // Storage\n  storageSnapshots,\n  storageSnapshotLatency,\n  storageWalAppends,\n\n  // Presence\n  presenceUpdates,\n  presenceActive,\n};\n"],"mappings":";;;;;;;;;;;AAcA,MAAa,oBAAoB,OAAO,MAAM,2BAA2B;;;;AAKzE,MAAa,mBAAmB,OAAO,QAAQ,0BAA0B;;;;AAKzE,MAAa,sBAAsB,OAAO,UACxC,iCACA,iBAAiB,YAAY;CAC3B,OAAO;CACP,QAAQ;CACR,OAAO;CACR,CAAC,CACH;;;;AAKD,MAAa,oBAAoB,OAAO,QAAQ,2BAA2B;;;;AAS3E,MAAa,kBAAkB,OAAO,MAAM,yBAAyB;;;;AAKrE,MAAa,mBAAmB,OAAO,QAAQ,0BAA0B;;;;AAKzE,MAAa,oBAAoB,OAAO,QAAQ,2BAA2B;;;;AAK3E,MAAa,mBAAmB,OAAO,QAAQ,0BAA0B;;;;AASzE,MAAa,wBAAwB,OAAO,QAC1C,+BACD;;;;AAKD,MAAa,uBAAuB,OAAO,QACzC,8BACD;;;;AAKD,MAAa,sBAAsB,OAAO,UACxC,iCACA,iBAAiB,YAAY;CAC3B,OAAO;CACP,QAAQ;CACR,OAAO;CACR,CAAC,CACH;;;;AASD,MAAa,mBAAmB,OAAO,QAAQ,0BAA0B;;;;AAKzE,MAAa,yBAAyB,OAAO,UAC3C,qCACA,iBAAiB,YAAY;CAC3B,OAAO;CACP,QAAQ;CACR,OAAO;CACR,CAAC,CACH;;;;AAKD,MAAa,oBAAoB,OAAO,QAAQ,4BAA4B;;;;AAS5E,MAAa,kBAAkB,OAAO,QAAQ,yBAAyB;;;;AAKvE,MAAa,iBAAiB,OAAO,MAAM,wBAAwB;AAMnE,MAAa,eAAe;CAE1B;CACA;CACA;CACA;CAGA;CACA;CACA;CACA;CAGA;CACA;CACA;CAGA;CACA;CACA;CAGA;CACA;CACD"}
+{"version":3,"file":"Metrics.mjs","names":[],"sources":["../src/Metrics.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - Metrics\n *\n * Observability metrics using Effect's Metric API.\n */\nimport { Metric, MetricBoundaries } from \"effect\";\n\n// =============================================================================\n// Connection Metrics\n// =============================================================================\n\n/**\n * Current active WebSocket connections\n */\nexport const connectionsActive = Metric.gauge(\"mimic.connections.active\");\n\n/**\n * Total connections over lifetime\n */\nexport const connectionsTotal = Metric.counter(\"mimic.connections.total\");\n\n/**\n * Connection duration histogram (milliseconds)\n */\nexport const connectionsDuration = Metric.histogram(\n  \"mimic.connections.duration_ms\",\n  MetricBoundaries.exponential({\n    start: 100,\n    factor: 2,\n    count: 15, // Up to ~3.2 million ms (~53 minutes)\n  })\n);\n\n/**\n * Connection errors (auth failures, etc.)\n */\nexport const connectionsErrors = Metric.counter(\"mimic.connections.errors\");\n\n// =============================================================================\n// Document Metrics\n// =============================================================================\n\n/**\n * Documents currently in memory\n */\nexport const documentsActive = Metric.gauge(\"mimic.documents.active\");\n\n/**\n * New documents created\n */\nexport const documentsCreated = Metric.counter(\"mimic.documents.created\");\n\n/**\n * Documents restored from storage\n */\nexport const documentsRestored = Metric.counter(\"mimic.documents.restored\");\n\n/**\n * Documents garbage collected (evicted)\n */\nexport const documentsEvicted = Metric.counter(\"mimic.documents.evicted\");\n\n// =============================================================================\n// Transaction Metrics\n// =============================================================================\n\n/**\n * Successfully processed transactions\n */\nexport const transactionsProcessed = Metric.counter(\n  \"mimic.transactions.processed\"\n);\n\n/**\n * Rejected transactions\n */\nexport const transactionsRejected = Metric.counter(\n  \"mimic.transactions.rejected\"\n);\n\n/**\n * Transaction processing latency histogram (milliseconds)\n */\nexport const transactionsLatency = Metric.histogram(\n  \"mimic.transactions.latency_ms\",\n  MetricBoundaries.exponential({\n    start: 0.1,\n    factor: 2,\n    count: 15, // Up to ~1638 ms\n  })\n);\n\n// =============================================================================\n// Storage Metrics\n// =============================================================================\n\n/**\n * Snapshots saved to ColdStorage\n */\nexport const storageSnapshots = Metric.counter(\"mimic.storage.snapshots\");\n\n/**\n * Snapshots triggered by idle document detection\n */\nexport const storageIdleSnapshots = Metric.counter(\"mimic.storage.idle_snapshots\");\n\n/**\n * Snapshot save duration histogram (milliseconds)\n */\nexport const storageSnapshotLatency = Metric.histogram(\n  \"mimic.storage.snapshot_latency_ms\",\n  MetricBoundaries.exponential({\n    start: 1,\n    factor: 2,\n    count: 12, // Up to ~4 seconds\n  })\n);\n\n/**\n * WAL entries written to HotStorage\n */\nexport const storageWalAppends = Metric.counter(\"mimic.storage.wal_appends\");\n\n/**\n * Version gaps detected during WAL replay\n */\nexport const storageVersionGaps = Metric.counter(\"mimic.storage.version_gaps\");\n\n/**\n * Failed WAL appends causing transaction rollback\n */\nexport const walAppendFailures = Metric.counter(\"mimic.storage.wal_append_failures\");\n\n/**\n * ColdStorage load failures during document restore\n */\nexport const coldStorageLoadFailures = Metric.counter(\"mimic.storage.cold_load_failures\");\n\n/**\n * HotStorage getEntries failures during document restore\n */\nexport const hotStorageLoadFailures = Metric.counter(\"mimic.storage.hot_load_failures\");\n\n// =============================================================================\n// Presence Metrics\n// =============================================================================\n\n/**\n * Presence set operations\n */\nexport const presenceUpdates = Metric.counter(\"mimic.presence.updates\");\n\n/**\n * Active presence entries\n */\nexport const presenceActive = Metric.gauge(\"mimic.presence.active\");\n\n// =============================================================================\n// Export namespace\n// =============================================================================\n\nexport const MimicMetrics = {\n  // Connection\n  connectionsActive,\n  connectionsTotal,\n  connectionsDuration,\n  connectionsErrors,\n\n  // Document\n  documentsActive,\n  documentsCreated,\n  documentsRestored,\n  documentsEvicted,\n\n  // Transaction\n  transactionsProcessed,\n  transactionsRejected,\n  transactionsLatency,\n\n  // Storage\n  storageSnapshots,\n  storageIdleSnapshots,\n  storageSnapshotLatency,\n  storageWalAppends,\n  storageVersionGaps,\n  walAppendFailures,\n  coldStorageLoadFailures,\n  hotStorageLoadFailures,\n\n  // Presence\n  presenceUpdates,\n  presenceActive,\n};\n"],"mappings":";;;;;;;;;;;AAcA,MAAa,oBAAoB,OAAO,MAAM,2BAA2B;;;;AAKzE,MAAa,mBAAmB,OAAO,QAAQ,0BAA0B;;;;AAKzE,MAAa,sBAAsB,OAAO,UACxC,iCACA,iBAAiB,YAAY;CAC3B,OAAO;CACP,QAAQ;CACR,OAAO;CACR,CAAC,CACH;;;;AAKD,MAAa,oBAAoB,OAAO,QAAQ,2BAA2B;;;;AAS3E,MAAa,kBAAkB,OAAO,MAAM,yBAAyB;;;;AAKrE,MAAa,mBAAmB,OAAO,QAAQ,0BAA0B;;;;AAKzE,MAAa,oBAAoB,OAAO,QAAQ,2BAA2B;;;;AAK3E,MAAa,mBAAmB,OAAO,QAAQ,0BAA0B;;;;AASzE,MAAa,wBAAwB,OAAO,QAC1C,+BACD;;;;AAKD,MAAa,uBAAuB,OAAO,QACzC,8BACD;;;;AAKD,MAAa,sBAAsB,OAAO,UACxC,iCACA,iBAAiB,YAAY;CAC3B,OAAO;CACP,QAAQ;CACR,OAAO;CACR,CAAC,CACH;;;;AASD,MAAa,mBAAmB,OAAO,QAAQ,0BAA0B;;;;AAKzE,MAAa,uBAAuB,OAAO,QAAQ,+BAA+B;;;;AAKlF,MAAa,yBAAyB,OAAO,UAC3C,qCACA,iBAAiB,YAAY;CAC3B,OAAO;CACP,QAAQ;CACR,OAAO;CACR,CAAC,CACH;;;;AAKD,MAAa,oBAAoB,OAAO,QAAQ,4BAA4B;;;;AAK5E,MAAa,qBAAqB,OAAO,QAAQ,6BAA6B;;;;AAK9E,MAAa,oBAAoB,OAAO,QAAQ,oCAAoC;;;;AAKpF,MAAa,0BAA0B,OAAO,QAAQ,mCAAmC;;;;AAKzF,MAAa,yBAAyB,OAAO,QAAQ,kCAAkC;;;;AASvF,MAAa,kBAAkB,OAAO,QAAQ,yBAAyB;;;;AAKvE,MAAa,iBAAiB,OAAO,MAAM,wBAAwB;AAMnE,MAAa,eAAe;CAE1B;CACA;CACA;CACA;CAGA;CACA;CACA;CACA;CAGA;CACA;CACA;CAGA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAGA;CACA;CACD"}

package/dist/MimicClusterServerEngine.cjs

@@ -1,10 +1,10 @@
 const require_ColdStorage = require('./ColdStorage.cjs');
 const require_HotStorage = require('./HotStorage.cjs');
 const require_Metrics = require('./Metrics.cjs');
+const require_DocumentInstance = require('./DocumentInstance.cjs');
 const require_objectSpread2 = require('./_virtual/_@oxc-project_runtime@0.103.0/helpers/objectSpread2.cjs');
 const require_MimicServerEngine = require('./MimicServerEngine.cjs');
 let effect = require("effect");
-let _voidhash_mimic_server = require("@voidhash/mimic/server");
 let _effect_cluster = require("@effect/cluster");
 let _effect_rpc = require("@effect/rpc");
 
@@ -21,6 +21,7 @@ const DEFAULT_MAX_IDLE_TIME = effect.Duration.minutes(5);
 const DEFAULT_MAX_TRANSACTION_HISTORY = 1e3;
 const DEFAULT_SNAPSHOT_INTERVAL = effect.Duration.minutes(5);
 const DEFAULT_SNAPSHOT_THRESHOLD = 100;
+const DEFAULT_SNAPSHOT_IDLE_TIMEOUT = effect.Duration.seconds(30);
 const DEFAULT_SHARD_GROUP = "mimic-documents";
 /**
 * Schema for encoded transaction (wire format)
@@ -99,7 +100,7 @@ const MimicDocumentEntity = _effect_cluster.Entity.make("MimicDocument", [
 */
 var MimicClusterConfigTag = class extends effect.Context.Tag("@voidhash/mimic-effect/MimicClusterConfig")() {};
 const resolveClusterConfig = (config) => {
-	var _config$maxTransactio, _config$snapshot, _config$snapshot$tran, _config$snapshot2, _config$shardGroup;
+	var _config$maxTransactio, _config$snapshot, _config$snapshot$tran, _config$snapshot2, _config$snapshot3, _config$shardGroup;
 	return {
 		schema: config.schema,
 		initial: config.initial,
@@ -108,7 +109,8 @@ const resolveClusterConfig = (config) => {
 		maxTransactionHistory: (_config$maxTransactio = config.maxTransactionHistory) !== null && _config$maxTransactio !== void 0 ? _config$maxTransactio : DEFAULT_MAX_TRANSACTION_HISTORY,
 		snapshot: {
 			interval: ((_config$snapshot = config.snapshot) === null || _config$snapshot === void 0 ? void 0 : _config$snapshot.interval) ? effect.Duration.decode(config.snapshot.interval) : DEFAULT_SNAPSHOT_INTERVAL,
-			transactionThreshold: (_config$snapshot$tran = (_config$snapshot2 = config.snapshot) === null || _config$snapshot2 === void 0 ? void 0 : _config$snapshot2.transactionThreshold) !== null && _config$snapshot$tran !== void 0 ? _config$snapshot$tran : DEFAULT_SNAPSHOT_THRESHOLD
+			transactionThreshold: (_config$snapshot$tran = (_config$snapshot2 = config.snapshot) === null || _config$snapshot2 === void 0 ? void 0 : _config$snapshot2.transactionThreshold) !== null && _config$snapshot$tran !== void 0 ? _config$snapshot$tran : DEFAULT_SNAPSHOT_THRESHOLD,
+			idleTimeout: ((_config$snapshot3 = config.snapshot) === null || _config$snapshot3 === void 0 ? void 0 : _config$snapshot3.idleTimeout) ? effect.Duration.decode(config.snapshot.idleTimeout) : DEFAULT_SNAPSHOT_IDLE_TIMEOUT
 		},
 		shardGroup: (_config$shardGroup = config.shardGroup) !== null && _config$shardGroup !== void 0 ? _config$shardGroup : DEFAULT_SHARD_GROUP
 	};
@@ -130,150 +132,53 @@ const encodeTransaction = (tx) => {
 /**
 * Create the entity handler for MimicDocument
 */
-const createEntityHandler = (config, coldStorage, hotStorage) => effect.Effect.gen(function* () {
+const createEntityHandler = (config, coldStorage, hotStorage) => effect.Effect.fn("cluster.entity.handler.create")(function* () {
 	const documentId = (yield* _effect_cluster.Entity.CurrentAddress).entityId;
-	const SCHEMA_VERSION = 1;
-	const computeInitialState = () => {
-		if (config.initial === void 0) return effect.Effect.succeed(void 0);
-		if (typeof config.initial === "function") return config.initial({ documentId });
-		return effect.Effect.succeed(config.initial);
-	};
-	const storedDoc = yield* effect.Effect.catchAll(coldStorage.load(documentId), () => effect.Effect.succeed(void 0));
-	let initialState;
-	let initialVersion = 0;
-	if (storedDoc) {
-		initialState = storedDoc.state;
-		initialVersion = storedDoc.version;
-	} else initialState = yield* computeInitialState();
-	const broadcastPubSub = yield* effect.PubSub.unbounded();
+	const instance = yield* require_DocumentInstance.DocumentInstance.make(documentId, {
+		schema: config.schema,
+		initial: config.initial,
+		maxTransactionHistory: config.maxTransactionHistory,
+		snapshot: config.snapshot
+	}, coldStorage, hotStorage).pipe(effect.Effect.orDie);
 	const presencePubSub = yield* effect.PubSub.unbounded();
 	const stateRef = yield* effect.Ref.make({
-		document: void 0,
-		broadcastPubSub,
+		instance,
 		presences: effect.HashMap.empty(),
-		presencePubSub,
-		lastSnapshotVersion: initialVersion,
-		lastSnapshotTime: Date.now(),
-		transactionsSinceSnapshot: 0
-	});
-	const document = _voidhash_mimic_server.ServerDocument.make({
-		schema: config.schema,
-		initialState,
-		initialVersion,
-		maxTransactionHistory: config.maxTransactionHistory,
-		onBroadcast: (message) => {
-			effect.Effect.runSync(effect.PubSub.publish(broadcastPubSub, {
-				type: "transaction",
-				transaction: message.transaction,
-				version: message.version
-			}));
-		},
-		onRejection: (transactionId, reason) => {
-			effect.Effect.runSync(effect.PubSub.publish(broadcastPubSub, {
-				type: "error",
-				transactionId,
-				reason
-			}));
-		}
+		presencePubSub
 	});
-	yield* effect.Ref.update(stateRef, (s) => require_objectSpread2._objectSpread2(require_objectSpread2._objectSpread2({}, s), {}, { document }));
-	const walEntries = yield* effect.Effect.catchAll(hotStorage.getEntries(documentId, initialVersion), () => effect.Effect.succeed([]));
-	for (const entry of walEntries) {
-		const result = document.submit(entry.transaction);
-		if (!result.success) yield* effect.Effect.logWarning("Skipping corrupted WAL entry", {
-			documentId,
-			version: entry.version,
-			reason: result.reason
-		});
-	}
-	if (storedDoc) yield* effect.Metric.increment(require_Metrics.documentsRestored);
-	else yield* effect.Metric.increment(require_Metrics.documentsCreated);
-	yield* effect.Metric.incrementBy(require_Metrics.documentsActive, 1);
-	/**
-	* Save snapshot to ColdStorage
-	*/
-	const saveSnapshot = effect.Effect.gen(function* () {
-		const state = yield* effect.Ref.get(stateRef);
-		const docState = state.document.get();
-		const version = state.document.getVersion();
-		if (docState === void 0) return;
-		const storedDocument = {
-			state: docState,
-			version,
-			schemaVersion: SCHEMA_VERSION,
-			savedAt: Date.now()
-		};
-		const snapshotStartTime = Date.now();
-		yield* effect.Effect.catchAll(coldStorage.save(documentId, storedDocument), (e) => effect.Effect.logError("Failed to save snapshot", {
-			documentId,
-			error: e
-		}));
-		const snapshotDuration = Date.now() - snapshotStartTime;
-		yield* effect.Metric.increment(require_Metrics.storageSnapshots);
-		yield* effect.Metric.update(require_Metrics.storageSnapshotLatency, snapshotDuration);
-		yield* effect.Effect.catchAll(hotStorage.truncate(documentId, version), (e) => effect.Effect.logError("Failed to truncate WAL", {
+	yield* effect.Effect.addFinalizer(() => effect.Effect.fn("cluster.entity.finalize")(function* () {
+		yield* effect.Effect.catchAll(instance.saveSnapshot(), (e) => effect.Effect.logError("Failed to save snapshot during entity finalization", {
 			documentId,
 			error: e
 		}));
-		yield* effect.Ref.update(stateRef, (s) => require_objectSpread2._objectSpread2(require_objectSpread2._objectSpread2({}, s), {}, {
-			lastSnapshotVersion: version,
-			lastSnapshotTime: Date.now(),
-			transactionsSinceSnapshot: 0
-		}));
-	});
-	/**
-	* Check if snapshot should be triggered
-	*/
-	const checkSnapshotTriggers = effect.Effect.gen(function* () {
-		const state = yield* effect.Ref.get(stateRef);
-		const now = Date.now();
-		const intervalMs = effect.Duration.toMillis(config.snapshot.interval);
-		const threshold = config.snapshot.transactionThreshold;
-		if (state.transactionsSinceSnapshot >= threshold) {
-			yield* saveSnapshot;
-			return;
-		}
-		if (now - state.lastSnapshotTime >= intervalMs) {
-			yield* saveSnapshot;
-			return;
-		}
-	});
-	yield* effect.Effect.addFinalizer(() => effect.Effect.gen(function* () {
-		yield* saveSnapshot;
 		yield* effect.Metric.incrementBy(require_Metrics.documentsActive, -1);
 		yield* effect.Metric.increment(require_Metrics.documentsEvicted);
 		yield* effect.Effect.logDebug("Entity finalized", { documentId });
-	}));
+	})());
+	if (effect.Duration.toMillis(config.snapshot.idleTimeout) > 0) yield* effect.Effect.fn("cluster.entity.snapshot.loop")(function* () {
+		if (yield* instance.needsSnapshot()) {
+			yield* effect.Effect.catchAll(instance.saveSnapshot(), (e) => effect.Effect.logWarning("Periodic snapshot failed in cluster entity", {
+				documentId,
+				error: e
+			}));
+			yield* effect.Metric.increment(require_Metrics.storageIdleSnapshots);
+		}
+	})().pipe(effect.Effect.repeat(effect.Schedule.spaced(config.snapshot.idleTimeout)), effect.Effect.fork);
 	return {
-		Submit: effect.Effect.fnUntraced(function* ({ payload }) {
-			const submitStartTime = Date.now();
-			const state = yield* effect.Ref.get(stateRef);
+		Submit: effect.Effect.fn("cluster.document.transaction.submit")(function* ({ payload }) {
 			const transaction = decodeTransaction(payload.transaction);
-			const result = state.document.submit(transaction);
-			const latency = Date.now() - submitStartTime;
-			yield* effect.Metric.update(require_Metrics.transactionsLatency, latency);
-			if (result.success) {
-				yield* effect.Metric.increment(require_Metrics.transactionsProcessed);
-				const walEntry = {
-					transaction,
-					version: result.version,
-					timestamp: Date.now()
-				};
-				yield* effect.Effect.catchAll(hotStorage.append(documentId, walEntry), (e) => effect.Effect.logError("Failed to append to WAL", {
-					documentId,
-					error: e
-				}));
-				yield* effect.Metric.increment(require_Metrics.storageWalAppends);
-				yield* effect.Ref.update(stateRef, (s) => require_objectSpread2._objectSpread2(require_objectSpread2._objectSpread2({}, s), {}, { transactionsSinceSnapshot: s.transactionsSinceSnapshot + 1 }));
-				yield* checkSnapshotTriggers;
-			} else yield* effect.Metric.increment(require_Metrics.transactionsRejected);
-			return result;
+			return yield* instance.submit(transaction).pipe(effect.Effect.catchAll((error) => effect.Effect.succeed({
+				success: false,
+				reason: `Storage error: ${String(error)}`
+			})));
 		}),
-		GetSnapshot: effect.Effect.fnUntraced(function* () {
-			return (yield* effect.Ref.get(stateRef)).document.getSnapshot();
+		GetSnapshot: effect.Effect.fn("cluster.document.snapshot.get")(function* () {
+			return instance.getSnapshot();
 		}),
-		Touch: effect.Effect.fnUntraced(function* () {}),
-		SetPresence: effect.Effect.fnUntraced(function* ({ payload }) {
+		Touch: effect.Effect.fn("cluster.document.touch")(function* () {
+			yield* instance.touch();
+		}),
+		SetPresence: effect.Effect.fn("cluster.presence.set")(function* ({ payload }) {
 			const { connectionId, entry } = payload;
 			yield* effect.Ref.update(stateRef, (s) => require_objectSpread2._objectSpread2(require_objectSpread2._objectSpread2({}, s), {}, { presences: effect.HashMap.set(s.presences, connectionId, entry) }));
 			yield* effect.Metric.increment(require_Metrics.presenceUpdates);
@@ -287,7 +192,7 @@ const createEntityHandler = (config, coldStorage, hotStorage) => effect.Effect.g
 			};
 			yield* effect.PubSub.publish(state.presencePubSub, event);
 		}),
-		RemovePresence: effect.Effect.fnUntraced(function* ({ payload }) {
+		RemovePresence: effect.Effect.fn("cluster.presence.remove")(function* ({ payload }) {
 			const { connectionId } = payload;
 			const state = yield* effect.Ref.get(stateRef);
 			if (!effect.HashMap.has(state.presences, connectionId)) return;
@@ -299,20 +204,20 @@ const createEntityHandler = (config, coldStorage, hotStorage) => effect.Effect.g
 			};
 			yield* effect.PubSub.publish(state.presencePubSub, event);
 		}),
-		GetPresenceSnapshot: effect.Effect.fnUntraced(function* () {
+		GetPresenceSnapshot: effect.Effect.fn("cluster.presence.snapshot.get")(function* () {
 			const state = yield* effect.Ref.get(stateRef);
 			const presences = {};
 			for (const [id, entry] of state.presences) presences[id] = entry;
 			return { presences };
 		})
 	};
-});
+})();
 var SubscriptionStoreTag = class extends effect.Context.Tag("@voidhash/mimic-effect/SubscriptionStore")() {};
-const subscriptionStoreLayer = effect.Layer.effect(SubscriptionStoreTag, effect.Effect.gen(function* () {
+const subscriptionStoreLayer = effect.Layer.effect(SubscriptionStoreTag, effect.Effect.fn("cluster.subscriptions.layer.create")(function* () {
 	const documentPubSubs = yield* effect.Ref.make(effect.HashMap.empty());
 	const presencePubSubs = yield* effect.Ref.make(effect.HashMap.empty());
 	return {
-		getOrCreatePubSub: (documentId) => effect.Effect.gen(function* () {
+		getOrCreatePubSub: effect.Effect.fn("cluster.subscriptions.pubsub.get-or-create")(function* (documentId) {
 			const current = yield* effect.Ref.get(documentPubSubs);
 			const existing = effect.HashMap.get(current, documentId);
 			if (existing._tag === "Some") return existing.value;
@@ -320,7 +225,7 @@ const subscriptionStoreLayer = effect.Layer.effect(SubscriptionStoreTag, effect.
 			yield* effect.Ref.update(documentPubSubs, (map) => effect.HashMap.set(map, documentId, pubsub));
 			return pubsub;
 		}),
-		getOrCreatePresencePubSub: (documentId) => effect.Effect.gen(function* () {
+		getOrCreatePresencePubSub: effect.Effect.fn("cluster.subscriptions.presence-pubsub.get-or-create")(function* (documentId) {
 			const current = yield* effect.Ref.get(presencePubSubs);
 			const existing = effect.HashMap.get(current, documentId);
 			if (existing._tag === "Some") return existing.value;
@@ -329,7 +234,7 @@ const subscriptionStoreLayer = effect.Layer.effect(SubscriptionStoreTag, effect.
 			return pubsub;
 		})
 	};
-}));
+})());
 /**
 * Create a MimicClusterServerEngine layer.
 *

package/dist/MimicClusterServerEngine.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"MimicClusterServerEngine.d.cts","names":[],"sources":["../src/MimicClusterServerEngine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cAqzBa;yBA3JwB,SAAA,CAAU,sBACrC,+BAA+B,aACtC,KAAA,CAAM,MACP,6BAEA,iBAAiB,gBAAgB,sBAAsB,QAAA,CAAS"}
+{"version":3,"file":"MimicClusterServerEngine.d.cts","names":[],"sources":["../src/MimicClusterServerEngine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cA0pBa;yBA3JwB,SAAA,CAAU,sBACrC,+BAA+B,aACtC,KAAA,CAAM,MACP,6BAEA,iBAAiB,gBAAgB,sBAAsB,QAAA,CAAS"}

package/dist/MimicClusterServerEngine.d.mts

@@ -4,8 +4,8 @@ import { HotStorageTag } from "./HotStorage.mjs";
 import { MimicAuthServiceTag } from "./MimicAuthService.mjs";
 import { MimicServerEngineTag } from "./MimicServerEngine.mjs";
 import { Layer } from "effect";
-import { Sharding } from "@effect/cluster";
 import { Primitive } from "@voidhash/mimic";
+import { Sharding } from "@effect/cluster";
 
 //#region src/MimicClusterServerEngine.d.ts
 

package/dist/MimicClusterServerEngine.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"MimicClusterServerEngine.d.mts","names":[],"sources":["../src/MimicClusterServerEngine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cAqzBa;yBA3JwB,SAAA,CAAU,sBACrC,+BAA+B,aACtC,KAAA,CAAM,MACP,6BAEA,iBAAiB,gBAAgB,sBAAsB,QAAA,CAAS"}
+{"version":3,"file":"MimicClusterServerEngine.d.mts","names":[],"sources":["../src/MimicClusterServerEngine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cA0pBa;yBA3JwB,SAAA,CAAU,sBACrC,+BAA+B,aACtC,KAAA,CAAM,MACP,6BAEA,iBAAiB,gBAAgB,sBAAsB,QAAA,CAAS"}