@voidhash/mimic-effect 0.0.9 → 1.0.0-beta.2

package/dist/DocumentManager.mjs

@@ -1,61 +1,73 @@
-import { __export } from "./_virtual/rolldown_runtime.mjs";
-import { MimicServerConfigTag } from "./MimicConfig.mjs";
-import { MimicDataStorageTag } from "./MimicDataStorage.mjs";
-import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
-import * as PubSub from "effect/PubSub";
-import * as Ref from "effect/Ref";
-import * as HashMap from "effect/HashMap";
-import * as Context from "effect/Context";
-import * as Stream from "effect/Stream";
+import { ColdStorageTag } from "./ColdStorage.mjs";
+import { HotStorageTag } from "./HotStorage.mjs";
+import { documentsActive, documentsCreated, documentsEvicted, documentsRestored, storageSnapshotLatency, storageSnapshots, storageVersionGaps, storageWalAppends, transactionsLatency, transactionsProcessed, transactionsRejected, walAppendFailures } from "./Metrics.mjs";
+import { Context, Duration, Effect, HashMap, Layer, Metric, PubSub, Ref, Schedule, Stream } from "effect";
+import { Document } from "@voidhash/mimic";
 import { ServerDocument } from "@voidhash/mimic/server";
 
 //#region src/DocumentManager.ts
 /**
-* @since 0.0.1
-* Document manager that handles multiple document instances.
+* @voidhash/mimic-effect - DocumentManager
+*
+* Internal service for managing document lifecycle, including:
+* - Document creation and restoration
+* - Transaction processing
+* - WAL management
+* - Snapshot scheduling
+* - Idle document GC
 */
-var DocumentManager_exports = /* @__PURE__ */ __export({
-	DocumentManagerTag: () => DocumentManagerTag,
-	layer: () => layer
-});
 /**
-* Context tag for DocumentManager.
+* Context tag for DocumentManager service
 */
-var DocumentManagerTag = class extends Context.Tag("@voidhash/mimic-server-effect/DocumentManager")() {};
+var DocumentManagerTag = class extends Context.Tag("@voidhash/mimic-effect/DocumentManager")() {};
 /**
-* Create the DocumentManager service.
+* Context tag for DocumentManager configuration
 */
-const makeDocumentManager = Effect.gen(function* () {
-	const config = yield* MimicServerConfigTag;
-	const storage = yield* MimicDataStorageTag;
-	const documents = yield* Ref.make(HashMap.empty());
-	const getOrCreateDocument = (documentId) => Effect.gen(function* () {
-		const current = yield* Ref.get(documents);
-		const existing = HashMap.get(current, documentId);
-		if (existing._tag === "Some") {
-			yield* Ref.update(existing.value.refCount, (n) => n + 1);
-			return existing.value;
-		}
-		const rawState = yield* Effect.catchAll(storage.load(documentId), () => Effect.succeed(void 0));
-		const initialState = rawState !== void 0 ? yield* storage.onLoad(rawState) : config.initial !== void 0 ? yield* config.initial({ documentId }) : void 0;
+var DocumentManagerConfigTag = class extends Context.Tag("@voidhash/mimic-effect/DocumentManagerConfig")() {};
+/**
+* Create the DocumentManager layer.
+* Requires ColdStorage, HotStorage, and DocumentManagerConfig.
+*/
+const layer = Layer.scoped(DocumentManagerTag, Effect.gen(function* () {
+	const coldStorage = yield* ColdStorageTag;
+	const hotStorage = yield* HotStorageTag;
+	const config = yield* DocumentManagerConfigTag;
+	const store = yield* Ref.make(HashMap.empty());
+	const SCHEMA_VERSION = 1;
+	/**
+	* Compute initial state for a new document
+	*/
+	const computeInitialState = (documentId) => {
+		if (config.initial === void 0) return Effect.succeed(void 0);
+		if (typeof config.initial === "function") return config.initial({ documentId });
+		return Effect.succeed(config.initial);
+	};
+	/**
+	* Restore a document from storage
+	*/
+	const restoreDocument = (documentId) => Effect.gen(function* () {
+		const storedDoc = yield* coldStorage.load(documentId);
+		let initialState;
+		let initialVersion = 0;
+		if (storedDoc) {
+			initialState = storedDoc.state;
+			initialVersion = storedDoc.version;
+		} else initialState = yield* computeInitialState(documentId);
 		const pubsub = yield* PubSub.unbounded();
-		const serverDocument = ServerDocument.make({
+		const lastSnapshotVersion = yield* Ref.make(initialVersion);
+		const lastSnapshotTime = yield* Ref.make(Date.now());
+		const transactionsSinceSnapshot = yield* Ref.make(0);
+		const lastActivityTime = yield* Ref.make(Date.now());
+		const document = ServerDocument.make({
 			schema: config.schema,
 			initialState,
+			initialVersion,
 			maxTransactionHistory: config.maxTransactionHistory,
-			onBroadcast: (transactionMessage) => {
-				const currentState = serverDocument.get();
-				Effect.runFork(Effect.gen(function* () {
-					if (currentState !== void 0) {
-						const transformedState = yield* storage.onSave(currentState);
-						yield* Effect.catchAll(storage.save(documentId, transformedState), (error) => Effect.logError("Failed to save document", error));
-					}
-				}));
+			onBroadcast: (message) => {
 				Effect.runSync(PubSub.publish(pubsub, {
 					type: "transaction",
-					transaction: transactionMessage.transaction,
-					version: transactionMessage.version
+					transaction: message.transaction,
+					version: message.version
 				}));
 			},
 			onRejection: (transactionId, reason) => {
@@ -66,40 +78,220 @@ const makeDocumentManager = Effect.gen(function* () {
 				}));
 			}
 		});
+		const walEntries = yield* hotStorage.getEntries(documentId, initialVersion);
+		if (walEntries.length > 0) {
+			const firstWalVersion = walEntries[0].version;
+			const expectedFirst = initialVersion + 1;
+			if (firstWalVersion !== expectedFirst) {
+				yield* Effect.logWarning("WAL version gap detected", {
+					documentId,
+					snapshotVersion: initialVersion,
+					firstWalVersion,
+					expectedFirst
+				});
+				yield* Metric.increment(storageVersionGaps);
+			}
+			for (let i = 1; i < walEntries.length; i++) {
+				const prev = walEntries[i - 1].version;
+				const curr = walEntries[i].version;
+				if (curr !== prev + 1) yield* Effect.logWarning("WAL internal gap detected", {
+					documentId,
+					previousVersion: prev,
+					currentVersion: curr
+				});
+			}
+		}
+		for (const entry of walEntries) {
+			const result = document.submit(entry.transaction);
+			if (!result.success) yield* Effect.logWarning("Skipping corrupted WAL entry", {
+				documentId,
+				version: entry.version,
+				reason: result.reason
+			});
+		}
 		const instance = {
-			document: serverDocument,
+			document,
 			pubsub,
-			refCount: yield* Ref.make(1)
+			lastSnapshotVersion,
+			lastSnapshotTime,
+			transactionsSinceSnapshot,
+			lastActivityTime
 		};
-		yield* Ref.update(documents, (map) => HashMap.set(map, documentId, instance));
+		if (storedDoc) yield* Metric.increment(documentsRestored);
+		else yield* Metric.increment(documentsCreated);
+		yield* Metric.incrementBy(documentsActive, 1);
 		return instance;
 	});
-	const submit = (documentId, transaction) => Effect.gen(function* () {
-		return (yield* getOrCreateDocument(documentId)).document.submit(transaction);
-	});
-	const getSnapshot = (documentId) => Effect.gen(function* () {
-		return (yield* getOrCreateDocument(documentId)).document.getSnapshot();
+	/**
+	* Get or create a document instance
+	*/
+	const getOrCreateDocument = (documentId) => Effect.gen(function* () {
+		const current = yield* Ref.get(store);
+		const existing = HashMap.get(current, documentId);
+		if (existing._tag === "Some") {
+			yield* Ref.set(existing.value.lastActivityTime, Date.now());
+			return existing.value;
+		}
+		const instance = yield* restoreDocument(documentId);
+		yield* Ref.update(store, (map) => HashMap.set(map, documentId, instance));
+		return instance;
 	});
-	const subscribe = (documentId) => Effect.gen(function* () {
-		const instance = yield* getOrCreateDocument(documentId);
-		const queue = yield* PubSub.subscribe(instance.pubsub);
-		yield* Effect.addFinalizer(() => Effect.gen(function* () {
-			yield* Ref.updateAndGet(instance.refCount, (n) => n - 1);
+	/**
+	* Save a snapshot to ColdStorage derived from WAL entries.
+	* This ensures snapshots are always based on durable WAL data.
+	* Idempotent: skips save if already snapshotted at target version.
+	* Truncate failures are non-fatal and will be retried on next snapshot.
+	*/
+	const saveSnapshot = (documentId, instance, targetVersion) => Effect.gen(function* () {
+		var _baseSnapshot$version;
+		if (targetVersion <= (yield* Ref.get(instance.lastSnapshotVersion))) return;
+		const snapshotStartTime = Date.now();
+		const baseSnapshot = yield* coldStorage.load(documentId);
+		const baseVersion = (_baseSnapshot$version = baseSnapshot === null || baseSnapshot === void 0 ? void 0 : baseSnapshot.version) !== null && _baseSnapshot$version !== void 0 ? _baseSnapshot$version : 0;
+		const baseState = baseSnapshot === null || baseSnapshot === void 0 ? void 0 : baseSnapshot.state;
+		const relevantEntries = (yield* hotStorage.getEntries(documentId, baseVersion)).filter((e) => e.version <= targetVersion);
+		if (relevantEntries.length === 0 && !baseSnapshot) return;
+		let snapshotState = baseState;
+		for (const entry of relevantEntries) {
+			const tempDoc = Document.make(config.schema, { initialState: snapshotState });
+			tempDoc.apply(entry.transaction.ops);
+			snapshotState = tempDoc.get();
+		}
+		if (snapshotState === void 0) return;
+		const snapshotVersion = relevantEntries.length > 0 ? relevantEntries[relevantEntries.length - 1].version : baseVersion;
+		if (snapshotVersion <= (yield* Ref.get(instance.lastSnapshotVersion))) return;
+		const storedDoc = {
+			state: snapshotState,
+			version: snapshotVersion,
+			schemaVersion: SCHEMA_VERSION,
+			savedAt: Date.now()
+		};
+		yield* coldStorage.save(documentId, storedDoc);
+		const snapshotDuration = Date.now() - snapshotStartTime;
+		yield* Metric.increment(storageSnapshots);
+		yield* Metric.update(storageSnapshotLatency, snapshotDuration);
+		yield* Ref.set(instance.lastSnapshotVersion, snapshotVersion);
+		yield* Ref.set(instance.lastSnapshotTime, Date.now());
+		yield* Ref.set(instance.transactionsSinceSnapshot, 0);
+		yield* Effect.catchAll(hotStorage.truncate(documentId, snapshotVersion), (e) => Effect.logWarning("WAL truncate failed - will retry on next snapshot", {
+			documentId,
+			version: snapshotVersion,
+			error: e
 		}));
-		return Stream.fromQueue(queue);
 	});
+	/**
+	* Check if snapshot should be triggered
+	*/
+	const checkSnapshotTriggers = (documentId, instance) => Effect.gen(function* () {
+		const txCount = yield* Ref.get(instance.transactionsSinceSnapshot);
+		const lastTime = yield* Ref.get(instance.lastSnapshotTime);
+		const now = Date.now();
+		const currentVersion = instance.document.getVersion();
+		const intervalMs = Duration.toMillis(config.snapshot.interval);
+		if (txCount >= config.snapshot.transactionThreshold) {
+			yield* saveSnapshot(documentId, instance, currentVersion);
+			return;
+		}
+		if (now - lastTime >= intervalMs) {
+			yield* saveSnapshot(documentId, instance, currentVersion);
+			return;
+		}
+	});
+	yield* Effect.gen(function* () {
+		yield* Effect.gen(function* () {
+			const current = yield* Ref.get(store);
+			const now = Date.now();
+			const maxIdleMs = Duration.toMillis(config.maxIdleTime);
+			for (const [documentId, instance] of current) if (now - (yield* Ref.get(instance.lastActivityTime)) >= maxIdleMs) {
+				const currentVersion = instance.document.getVersion();
+				yield* Effect.catchAll(saveSnapshot(documentId, instance, currentVersion), (e) => Effect.logError("Failed to save snapshot during eviction", {
+					documentId,
+					error: e
+				}));
+				yield* Ref.update(store, (map) => HashMap.remove(map, documentId));
+				yield* Metric.increment(documentsEvicted);
+				yield* Metric.incrementBy(documentsActive, -1);
+				yield* Effect.logInfo("Document evicted due to idle timeout", { documentId });
+			}
+		}).pipe(Effect.repeat(Schedule.spaced("1 minute")), Effect.fork);
+	});
+	yield* Effect.addFinalizer(() => Effect.gen(function* () {
+		const current = yield* Ref.get(store);
+		for (const [documentId, instance] of current) {
+			const currentVersion = instance.document.getVersion();
+			yield* Effect.catchAll(saveSnapshot(documentId, instance, currentVersion), (e) => Effect.logError("Failed to save snapshot during shutdown", {
+				documentId,
+				error: e
+			}));
+		}
+		yield* Effect.logInfo("DocumentManager shutdown complete");
+	}));
 	return {
-		submit,
-		getSnapshot,
-		subscribe
+		submit: (documentId, transaction) => Effect.gen(function* () {
+			const instance = yield* getOrCreateDocument(documentId);
+			const submitStartTime = Date.now();
+			const validation = instance.document.validate(transaction);
+			if (!validation.valid) {
+				yield* Metric.increment(transactionsRejected);
+				const latency$1 = Date.now() - submitStartTime;
+				yield* Metric.update(transactionsLatency, latency$1);
+				return {
+					success: false,
+					reason: validation.reason
+				};
+			}
+			const walEntry = {
+				transaction,
+				version: validation.nextVersion,
+				timestamp: Date.now()
+			};
+			const appendResult = yield* Effect.either(hotStorage.appendWithCheck(documentId, walEntry, validation.nextVersion));
+			if (appendResult._tag === "Left") {
+				yield* Effect.logError("WAL append failed", {
+					documentId,
+					version: validation.nextVersion,
+					error: appendResult.left
+				});
+				yield* Metric.increment(walAppendFailures);
+				const latency$1 = Date.now() - submitStartTime;
+				yield* Metric.update(transactionsLatency, latency$1);
+				return {
+					success: false,
+					reason: "Storage unavailable. Please retry."
+				};
+			}
+			instance.document.apply(transaction);
+			const latency = Date.now() - submitStartTime;
+			yield* Metric.update(transactionsLatency, latency);
+			yield* Metric.increment(transactionsProcessed);
+			yield* Metric.increment(storageWalAppends);
+			yield* Ref.update(instance.transactionsSinceSnapshot, (n) => n + 1);
+			yield* checkSnapshotTriggers(documentId, instance);
+			return {
+				success: true,
+				version: validation.nextVersion
+			};
+		}),
+		getSnapshot: (documentId) => Effect.gen(function* () {
+			return (yield* getOrCreateDocument(documentId)).document.getSnapshot();
+		}),
+		subscribe: (documentId) => Effect.gen(function* () {
+			const instance = yield* getOrCreateDocument(documentId);
+			return Stream.fromPubSub(instance.pubsub);
+		}),
+		touch: (documentId) => Effect.gen(function* () {
+			const current = yield* Ref.get(store);
+			const existing = HashMap.get(current, documentId);
+			if (existing._tag === "Some") yield* Ref.set(existing.value.lastActivityTime, Date.now());
+		})
 	};
-});
-/**
-* Layer that provides DocumentManager.
-* Requires MimicServerConfigTag and MimicDataStorageTag.
-*/
-const layer = Layer.effect(DocumentManagerTag, makeDocumentManager);
+}));
+const DocumentManager = {
+	Tag: DocumentManagerTag,
+	ConfigTag: DocumentManagerConfigTag,
+	layer
+};
 
 //#endregion
-export { DocumentManagerTag, DocumentManager_exports, layer };
+export { DocumentManager, DocumentManagerConfigTag, DocumentManagerTag, layer };
 //# sourceMappingURL=DocumentManager.mjs.map

package/dist/DocumentManager.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"DocumentManager.mjs","names":["instance: DocumentInstance","layer: Layer.Layer<\n  DocumentManagerTag,\n  never,\n  MimicServerConfigTag | MimicDataStorageTag\n>"],"sources":["../src/DocumentManager.ts"],"sourcesContent":["/**\n * @since 0.0.1\n * Document manager that handles multiple document instances.\n */\nimport * as Effect from \"effect/Effect\";\nimport * as Layer from \"effect/Layer\";\nimport * as PubSub from \"effect/PubSub\";\nimport * as Ref from \"effect/Ref\";\nimport * as HashMap from \"effect/HashMap\";\nimport * as Context from \"effect/Context\";\nimport * as Scope from \"effect/Scope\";\nimport * as Stream from \"effect/Stream\";\nimport type { Primitive, Transaction } from \"@voidhash/mimic\";\nimport { ServerDocument } from \"@voidhash/mimic/server\";\n\nimport * as Protocol from \"./DocumentProtocol.js\";\nimport { MimicServerConfigTag } from \"./MimicConfig.js\";\nimport { MimicDataStorageTag } from \"./MimicDataStorage.js\";\nimport { DocumentNotFoundError } from \"./errors.js\";\n\n// =============================================================================\n// Document Instance\n// =============================================================================\n\n/**\n * A managed document instance that holds state and manages subscribers.\n */\ninterface DocumentInstance {\n  /** The underlying ServerDocument */\n  readonly document: ServerDocument.ServerDocument<Primitive.AnyPrimitive>;\n  /** PubSub for broadcasting messages to subscribers */\n  readonly pubsub: PubSub.PubSub<Protocol.ServerBroadcast>;\n  /** Reference count for cleanup */\n  readonly refCount: Ref.Ref<number>;\n}\n\n// =============================================================================\n// Document Manager Service\n// =============================================================================\n\n/**\n * Service interface for the DocumentManager.\n */\nexport interface DocumentManager {\n  /**\n   * Submit a transaction to a document.\n   */\n  readonly submit: (\n    documentId: string,\n    transaction: Transaction.Transaction\n  ) => Effect.Effect<Protocol.SubmitResult>;\n\n  /**\n   * Get a snapshot of a document.\n   */\n  readonly getSnapshot: (\n    documentId: string\n  ) => Effect.Effect<Protocol.SnapshotMessage>;\n\n  /**\n   * Subscribe to broadcasts for a document.\n   * Returns a Stream of server broadcasts.\n   */\n  readonly subscribe: (\n    documentId: string\n  ) => Effect.Effect<\n    Stream.Stream<Protocol.ServerBroadcast>,\n    never,\n    Scope.Scope\n  >;\n}\n\n/**\n * Context tag for DocumentManager.\n */\nexport class DocumentManagerTag extends Context.Tag(\n  \"@voidhash/mimic-server-effect/DocumentManager\"\n)<DocumentManagerTag, DocumentManager>() {}\n\n// =============================================================================\n// Document Manager Implementation\n// =============================================================================\n\n/**\n * Create the DocumentManager service.\n */\nconst makeDocumentManager = Effect.gen(function* () {\n  const config = yield* MimicServerConfigTag;\n  const storage = yield* MimicDataStorageTag;\n  \n  // Map of document ID to document instance\n  const documents = yield* Ref.make(\n    HashMap.empty<string, DocumentInstance>()\n  );\n\n  // Get or create a document instance\n  const getOrCreateDocument = (\n    documentId: string\n  ): Effect.Effect<DocumentInstance> =>\n    Effect.gen(function* () {\n      const current = yield* Ref.get(documents);\n      const existing = HashMap.get(current, documentId);\n\n      if (existing._tag === \"Some\") {\n        // Increment ref count\n        yield* Ref.update(existing.value.refCount, (n) => n + 1);\n        return existing.value;\n      }\n\n      // Load initial state from storage\n      const rawState = yield* Effect.catchAll(\n        storage.load(documentId),\n        () => Effect.succeed(undefined)\n      );\n\n      // Transform loaded state with onLoad hook, or compute initial state for new docs\n      const initialState = rawState !== undefined\n        ? yield* storage.onLoad(rawState)\n        : config.initial !== undefined\n          ? yield* config.initial({ documentId })\n          : undefined;\n\n      // Create PubSub for broadcasting\n      const pubsub = yield* PubSub.unbounded<Protocol.ServerBroadcast>();\n\n      // Create ServerDocument with broadcast callback\n      const serverDocument = ServerDocument.make({\n        schema: config.schema,\n        initialState: initialState as Primitive.InferSetInput<typeof config.schema> | undefined,\n        maxTransactionHistory: config.maxTransactionHistory,\n        onBroadcast: (transactionMessage) => {\n          // Get current state and save to storage\n          const currentState = serverDocument.get();\n          \n          // Run save in background (fire-and-forget with error logging)\n          Effect.runFork(\n            Effect.gen(function* () {\n              if (currentState !== undefined) {\n                const transformedState = yield* storage.onSave(currentState);\n                yield* Effect.catchAll(\n                  storage.save(documentId, transformedState),\n                  (error) => Effect.logError(\"Failed to save document\", error)\n                );\n              }\n            })\n          );\n\n          // Broadcast to subscribers\n          Effect.runSync(\n            PubSub.publish(pubsub, {\n              type: \"transaction\",\n              transaction: transactionMessage.transaction as Protocol.Transaction,\n              version: transactionMessage.version,\n            })\n          );\n        },\n        onRejection: (transactionId, reason) => {\n          Effect.runSync(\n            PubSub.publish(pubsub, {\n              type: \"error\",\n              transactionId,\n              reason,\n            })\n          );\n        },\n      });\n\n      const refCount = yield* Ref.make(1);\n\n      const instance: DocumentInstance = {\n        document: serverDocument,\n        pubsub,\n        refCount,\n      };\n\n      // Store in map\n      yield* Ref.update(documents, (map) =>\n        HashMap.set(map, documentId, instance)\n      );\n\n      return instance;\n    });\n\n  // Submit a transaction\n  const submit = (\n    documentId: string,\n    transaction: Transaction.Transaction\n  ): Effect.Effect<Protocol.SubmitResult> =>\n    Effect.gen(function* () {\n      const instance = yield* getOrCreateDocument(documentId);\n      const result = instance.document.submit(transaction);\n      return result;\n    });\n\n  // Get a snapshot\n  const getSnapshot = (\n    documentId: string\n  ): Effect.Effect<Protocol.SnapshotMessage> =>\n    Effect.gen(function* () {\n      const instance = yield* getOrCreateDocument(documentId);\n      const snapshot = instance.document.getSnapshot();\n      return snapshot;\n    });\n\n  // Subscribe to broadcasts\n  const subscribe = (\n    documentId: string\n  ): Effect.Effect<\n    Stream.Stream<Protocol.ServerBroadcast>,\n    never,\n    Scope.Scope\n  > =>\n    Effect.gen(function* () {\n      const instance = yield* getOrCreateDocument(documentId);\n\n      // Subscribe to the PubSub\n      const queue = yield* PubSub.subscribe(instance.pubsub);\n\n      // Ensure cleanup on scope close\n      yield* Effect.addFinalizer(() =>\n        Effect.gen(function* () {\n          // Decrement ref count\n          const count = yield* Ref.updateAndGet(\n            instance.refCount,\n            (n) => n - 1\n          );\n\n          // If no more subscribers, we could clean up the document\n          // For now, we keep it alive (could add idle timeout)\n        })\n      );\n\n      // Convert queue to stream\n      return Stream.fromQueue(queue);\n    });\n\n  const manager: DocumentManager = {\n    submit,\n    getSnapshot,\n    subscribe,\n  };\n\n  return manager;\n});\n\n/**\n * Layer that provides DocumentManager.\n * Requires MimicServerConfigTag and MimicDataStorageTag.\n */\nexport const layer: Layer.Layer<\n  DocumentManagerTag,\n  never,\n  MimicServerConfigTag | MimicDataStorageTag\n> = Layer.effect(DocumentManagerTag, makeDocumentManager);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA2EA,IAAa,qBAAb,cAAwC,QAAQ,IAC9C,gDACD,EAAuC,CAAC;;;;AASzC,MAAM,sBAAsB,OAAO,IAAI,aAAa;CAClD,MAAM,SAAS,OAAO;CACtB,MAAM,UAAU,OAAO;CAGvB,MAAM,YAAY,OAAO,IAAI,KAC3B,QAAQ,OAAiC,CAC1C;CAGD,MAAM,uBACJ,eAEA,OAAO,IAAI,aAAa;EACtB,MAAM,UAAU,OAAO,IAAI,IAAI,UAAU;EACzC,MAAM,WAAW,QAAQ,IAAI,SAAS,WAAW;AAEjD,MAAI,SAAS,SAAS,QAAQ;AAE5B,UAAO,IAAI,OAAO,SAAS,MAAM,WAAW,MAAM,IAAI,EAAE;AACxD,UAAO,SAAS;;EAIlB,MAAM,WAAW,OAAO,OAAO,SAC7B,QAAQ,KAAK,WAAW,QAClB,OAAO,QAAQ,OAAU,CAChC;EAGD,MAAM,eAAe,aAAa,SAC9B,OAAO,QAAQ,OAAO,SAAS,GAC/B,OAAO,YAAY,SACjB,OAAO,OAAO,QAAQ,EAAE,YAAY,CAAC,GACrC;EAGN,MAAM,SAAS,OAAO,OAAO,WAAqC;EAGlE,MAAM,iBAAiB,eAAe,KAAK;GACzC,QAAQ,OAAO;GACD;GACd,uBAAuB,OAAO;GAC9B,cAAc,uBAAuB;IAEnC,MAAM,eAAe,eAAe,KAAK;AAGzC,WAAO,QACL,OAAO,IAAI,aAAa;AACtB,SAAI,iBAAiB,QAAW;MAC9B,MAAM,mBAAmB,OAAO,QAAQ,OAAO,aAAa;AAC5D,aAAO,OAAO,SACZ,QAAQ,KAAK,YAAY,iBAAiB,GACzC,UAAU,OAAO,SAAS,2BAA2B,MAAM,CAC7D;;MAEH,CACH;AAGD,WAAO,QACL,OAAO,QAAQ,QAAQ;KACrB,MAAM;KACN,aAAa,mBAAmB;KAChC,SAAS,mBAAmB;KAC7B,CAAC,CACH;;GAEH,cAAc,eAAe,WAAW;AACtC,WAAO,QACL,OAAO,QAAQ,QAAQ;KACrB,MAAM;KACN;KACA;KACD,CAAC,CACH;;GAEJ,CAAC;EAIF,MAAMA,WAA6B;GACjC,UAAU;GACV;GACA,UALe,OAAO,IAAI,KAAK,EAAE;GAMlC;AAGD,SAAO,IAAI,OAAO,YAAY,QAC5B,QAAQ,IAAI,KAAK,YAAY,SAAS,CACvC;AAED,SAAO;GACP;CAGJ,MAAM,UACJ,YACA,gBAEA,OAAO,IAAI,aAAa;AAGtB,UAFiB,OAAO,oBAAoB,WAAW,EAC/B,SAAS,OAAO,YAAY;GAEpD;CAGJ,MAAM,eACJ,eAEA,OAAO,IAAI,aAAa;AAGtB,UAFiB,OAAO,oBAAoB,WAAW,EAC7B,SAAS,aAAa;GAEhD;CAGJ,MAAM,aACJ,eAMA,OAAO,IAAI,aAAa;EACtB,MAAM,WAAW,OAAO,oBAAoB,WAAW;EAGvD,MAAM,QAAQ,OAAO,OAAO,UAAU,SAAS,OAAO;AAGtD,SAAO,OAAO,mBACZ,OAAO,IAAI,aAAa;AAER,UAAO,IAAI,aACvB,SAAS,WACR,MAAM,IAAI,EACZ;IAID,CACH;AAGD,SAAO,OAAO,UAAU,MAAM;GAC9B;AAQJ,QANiC;EAC/B;EACA;EACA;EACD;EAGD;;;;;AAMF,MAAaC,QAIT,MAAM,OAAO,oBAAoB,oBAAoB"}
+{"version":3,"file":"DocumentManager.mjs","names":["initialState: Primitive.InferSetInput<typeof config.schema> | undefined","Metrics.storageVersionGaps","instance: DocumentInstance<typeof config.schema>","Metrics.documentsRestored","Metrics.documentsCreated","Metrics.documentsActive","snapshotState: Primitive.InferState<typeof config.schema> | undefined","storedDoc: StoredDocument","Metrics.storageSnapshots","Metrics.storageSnapshotLatency","Metrics.documentsEvicted","Metrics.transactionsRejected","latency","Metrics.transactionsLatency","walEntry: WalEntry","Metrics.walAppendFailures","Metrics.transactionsProcessed","Metrics.storageWalAppends"],"sources":["../src/DocumentManager.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - DocumentManager\n *\n * Internal service for managing document lifecycle, including:\n * - Document creation and restoration\n * - Transaction processing\n * - WAL management\n * - Snapshot scheduling\n * - Idle document GC\n */\nimport {\n  Context,\n  Duration,\n  Effect,\n  HashMap,\n  Layer,\n  Metric,\n  PubSub,\n  Ref,\n  Schedule,\n  Scope,\n  Stream,\n} from \"effect\";\nimport { Document, Primitive, Transaction } from \"@voidhash/mimic\";\nimport { ServerDocument } from \"@voidhash/mimic/server\";\nimport type {\n  ResolvedConfig,\n  StoredDocument,\n  WalEntry,\n} from \"./Types\";\nimport type { SnapshotMessage, ServerBroadcast } from \"./Protocol\";\nimport { ColdStorageTag } from \"./ColdStorage\";\nimport { HotStorageTag } from \"./HotStorage\";\nimport { ColdStorageError, HotStorageError } from \"./Errors\";\nimport * as Metrics from \"./Metrics\";\n\n// =============================================================================\n// Submit Result Types\n// =============================================================================\n\n/**\n * Result of submitting a transaction\n */\nexport type SubmitResult =\n  | { readonly success: true; readonly version: number }\n  | { readonly success: false; readonly reason: string };\n\n// =============================================================================\n// DocumentManager Interface\n// =============================================================================\n\n/**\n * Error type for DocumentManager operations\n */\nexport type DocumentManagerError = ColdStorageError | HotStorageError;\n\n/**\n * Internal service for managing document lifecycle.\n */\nexport interface DocumentManager {\n  /**\n   * Submit a transaction to a document.\n   * May fail with ColdStorageError or HotStorageError if storage is unavailable.\n   */\n  readonly submit: (\n    documentId: string,\n    transaction: Transaction.Transaction\n  ) => Effect.Effect<SubmitResult, DocumentManagerError>;\n\n  /**\n   * Get a snapshot of a document.\n   * May fail with ColdStorageError or HotStorageError if storage is unavailable.\n   */\n  readonly getSnapshot: (documentId: string) => Effect.Effect<SnapshotMessage, DocumentManagerError>;\n\n  /**\n   * Subscribe to broadcasts for a document.\n   * May fail with ColdStorageError or HotStorageError if storage is unavailable.\n   */\n  readonly subscribe: (\n    documentId: string\n  ) => Effect.Effect<Stream.Stream<ServerBroadcast>, DocumentManagerError, Scope.Scope>;\n\n  /**\n   * Touch a document to update its last activity time.\n   * Call this on any client activity to prevent idle GC.\n   */\n  readonly touch: (documentId: string) => Effect.Effect<void>;\n}\n\n// =============================================================================\n// Context Tag\n// =============================================================================\n\n/**\n * Context tag for DocumentManager service\n */\nexport class DocumentManagerTag extends Context.Tag(\n  \"@voidhash/mimic-effect/DocumentManager\"\n)<DocumentManagerTag, DocumentManager>() {}\n\n// =============================================================================\n// Internal Types\n// =============================================================================\n\n/**\n * Document instance state\n */\ninterface DocumentInstance<TSchema extends Primitive.AnyPrimitive> {\n  /** The underlying ServerDocument */\n  readonly document: ServerDocument.ServerDocument<TSchema>;\n  /** PubSub for broadcasting messages */\n  readonly pubsub: PubSub.PubSub<ServerBroadcast>;\n  /** Version at last snapshot */\n  readonly lastSnapshotVersion: Ref.Ref<number>;\n  /** Timestamp of last snapshot (ms) */\n  readonly lastSnapshotTime: Ref.Ref<number>;\n  /** Transactions since last snapshot */\n  readonly transactionsSinceSnapshot: Ref.Ref<number>;\n  /** Last activity timestamp (ms) */\n  readonly lastActivityTime: Ref.Ref<number>;\n}\n\n// =============================================================================\n// Config Context Tag\n// =============================================================================\n\n/**\n * Context tag for DocumentManager configuration\n */\nexport class DocumentManagerConfigTag extends Context.Tag(\n  \"@voidhash/mimic-effect/DocumentManagerConfig\"\n)<DocumentManagerConfigTag, ResolvedConfig<Primitive.AnyPrimitive>>() {}\n\n// =============================================================================\n// Layer Implementation\n// =============================================================================\n\n/**\n * Create the DocumentManager layer.\n * Requires ColdStorage, HotStorage, and DocumentManagerConfig.\n */\nexport const layer = Layer.scoped(\n  DocumentManagerTag,\n  Effect.gen(function* () {\n    const coldStorage = yield* ColdStorageTag;\n    const hotStorage = yield* HotStorageTag;\n    const config = yield* DocumentManagerConfigTag;\n\n    // Store: documentId -> DocumentInstance\n    const store = yield* Ref.make(\n      HashMap.empty<string, DocumentInstance<Primitive.AnyPrimitive>>()\n    );\n\n    // Current schema version (hard-coded to 1 for now)\n    const SCHEMA_VERSION = 1;\n\n    /**\n     * Compute initial state for a new document\n     */\n    const computeInitialState = (\n      documentId: string\n    ): Effect.Effect<Primitive.InferSetInput<typeof config.schema> | undefined> => {\n      if (config.initial === undefined) {\n        return Effect.succeed(undefined);\n      }\n\n      // Check if it's a function or static value\n      if (typeof config.initial === \"function\") {\n        return (config.initial as (ctx: { documentId: string }) => Effect.Effect<Primitive.InferSetInput<typeof config.schema>>)({ documentId });\n      }\n\n      return Effect.succeed(config.initial as Primitive.InferSetInput<typeof config.schema>);\n    };\n\n    /**\n     * Restore a document from storage\n     */\n    const restoreDocument = (\n      documentId: string\n    ): Effect.Effect<DocumentInstance<typeof config.schema>, ColdStorageError | HotStorageError> =>\n      Effect.gen(function* () {\n        // 1. Load snapshot from ColdStorage (errors propagate - do not silently fallback)\n        const storedDoc = yield* coldStorage.load(documentId);\n\n        let initialState: Primitive.InferSetInput<typeof config.schema> | undefined;\n        let initialVersion = 0;\n\n        if (storedDoc) {\n          // Use stored state\n          initialState = storedDoc.state as Primitive.InferSetInput<typeof config.schema>;\n          initialVersion = storedDoc.version;\n        } else {\n          // Compute initial state\n          initialState = yield* computeInitialState(documentId);\n        }\n\n        // 2. Create PubSub for broadcasting\n        const pubsub = yield* PubSub.unbounded<ServerBroadcast>();\n\n        // 3. Create refs for tracking\n        const lastSnapshotVersion = yield* Ref.make(initialVersion);\n        const lastSnapshotTime = yield* Ref.make(Date.now());\n        const transactionsSinceSnapshot = yield* Ref.make(0);\n        const lastActivityTime = yield* Ref.make(Date.now());\n\n        // 4. Create ServerDocument with callbacks\n        const document = ServerDocument.make({\n          schema: config.schema,\n          initialState,\n          initialVersion,\n          maxTransactionHistory: config.maxTransactionHistory,\n          onBroadcast: (message: ServerDocument.TransactionMessage) => {\n            // This is called synchronously by ServerDocument\n            // We need to publish to PubSub\n            Effect.runSync(\n              PubSub.publish(pubsub, {\n                type: \"transaction\",\n                transaction: message.transaction,\n                version: message.version,\n              })\n            );\n          },\n          onRejection: (transactionId: string, reason: string) => {\n            Effect.runSync(\n              PubSub.publish(pubsub, {\n                type: \"error\",\n                transactionId,\n                reason,\n              })\n            );\n          },\n        });\n\n        // 5. Load WAL entries (errors propagate - do not silently fallback)\n        const walEntries = yield* hotStorage.getEntries(documentId, initialVersion);\n\n        // 6. Verify WAL continuity (warning only, non-blocking)\n        if (walEntries.length > 0) {\n          const firstWalVersion = walEntries[0]!.version;\n          const expectedFirst = initialVersion + 1;\n\n          if (firstWalVersion !== expectedFirst) {\n            yield* Effect.logWarning(\"WAL version gap detected\", {\n              documentId,\n              snapshotVersion: initialVersion,\n              firstWalVersion,\n              expectedFirst,\n            });\n            yield* Metric.increment(Metrics.storageVersionGaps);\n          }\n\n          // Check internal gaps\n          for (let i = 1; i < walEntries.length; i++) {\n            const prev = walEntries[i - 1]!.version;\n            const curr = walEntries[i]!.version;\n            if (curr !== prev + 1) {\n              yield* Effect.logWarning(\"WAL internal gap detected\", {\n                documentId,\n                previousVersion: prev,\n                currentVersion: curr,\n              });\n            }\n          }\n        }\n\n        // 7. Replay WAL entries\n        for (const entry of walEntries) {\n          const result = document.submit(entry.transaction);\n          if (!result.success) {\n            yield* Effect.logWarning(\"Skipping corrupted WAL entry\", {\n              documentId,\n              version: entry.version,\n              reason: result.reason,\n            });\n          }\n        }\n\n        const instance: DocumentInstance<typeof config.schema> = {\n          document,\n          pubsub,\n          lastSnapshotVersion,\n          lastSnapshotTime,\n          transactionsSinceSnapshot,\n          lastActivityTime,\n        };\n\n        // Track metrics - determine if restored or created\n        if (storedDoc) {\n          yield* Metric.increment(Metrics.documentsRestored);\n        } else {\n          yield* Metric.increment(Metrics.documentsCreated);\n        }\n        yield* Metric.incrementBy(Metrics.documentsActive, 1);\n\n        return instance;\n      });\n\n    /**\n     * Get or create a document instance\n     */\n    const getOrCreateDocument = (\n      documentId: string\n    ): Effect.Effect<DocumentInstance<typeof config.schema>, ColdStorageError | HotStorageError> =>\n      Effect.gen(function* () {\n        const current = yield* Ref.get(store);\n        const existing = HashMap.get(current, documentId);\n\n        if (existing._tag === \"Some\") {\n          // Update activity time\n          yield* Ref.set(existing.value.lastActivityTime, Date.now());\n          return existing.value as DocumentInstance<typeof config.schema>;\n        }\n\n        // Restore document\n        const instance = yield* restoreDocument(documentId);\n\n        // Store it\n        yield* Ref.update(store, (map) =>\n          HashMap.set(map, documentId, instance)\n        );\n\n        return instance;\n      });\n\n    /**\n     * Save a snapshot to ColdStorage derived from WAL entries.\n     * This ensures snapshots are always based on durable WAL data.\n     * Idempotent: skips save if already snapshotted at target version.\n     * Truncate failures are non-fatal and will be retried on next snapshot.\n     */\n    const saveSnapshot = (\n      documentId: string,\n      instance: DocumentInstance<typeof config.schema>,\n      targetVersion: number\n    ): Effect.Effect<void, ColdStorageError | HotStorageError> =>\n      Effect.gen(function* () {\n        const lastSnapshotVersion = yield* Ref.get(instance.lastSnapshotVersion);\n\n        // Idempotency check: skip if already snapshotted at this version\n        if (targetVersion <= lastSnapshotVersion) {\n          return;\n        }\n\n        const snapshotStartTime = Date.now();\n\n        // Load base snapshot from cold storage\n        const baseSnapshot = yield* coldStorage.load(documentId);\n        const baseVersion = baseSnapshot?.version ?? 0;\n        const baseState = baseSnapshot?.state as Primitive.InferState<typeof config.schema> | undefined;\n\n        // Load WAL entries from base to target\n        const walEntries = yield* hotStorage.getEntries(documentId, baseVersion);\n        const relevantEntries = walEntries.filter(e => e.version <= targetVersion);\n\n        if (relevantEntries.length === 0 && !baseSnapshot) {\n          // Nothing to snapshot\n          return;\n        }\n\n        // Rebuild state by replaying WAL on base\n        let snapshotState: Primitive.InferState<typeof config.schema> | undefined = baseState;\n        for (const entry of relevantEntries) {\n          // Create a temporary document to apply the transaction\n          const tempDoc = Document.make(config.schema, { initialState: snapshotState });\n          tempDoc.apply(entry.transaction.ops);\n          snapshotState = tempDoc.get();\n        }\n\n        if (snapshotState === undefined) {\n          return;\n        }\n\n        const snapshotVersion = relevantEntries.length > 0\n          ? relevantEntries[relevantEntries.length - 1]!.version\n          : baseVersion;\n\n        // Re-check before saving (in case another snapshot completed while we were working)\n        // This prevents a slower snapshot from overwriting a more recent one\n        const currentLastSnapshot = yield* Ref.get(instance.lastSnapshotVersion);\n        if (snapshotVersion <= currentLastSnapshot) {\n          return;\n        }\n\n        const storedDoc: StoredDocument = {\n          state: snapshotState,\n          version: snapshotVersion,\n          schemaVersion: SCHEMA_VERSION,\n          savedAt: Date.now(),\n        };\n\n        // Save to ColdStorage - let errors propagate\n        yield* coldStorage.save(documentId, storedDoc);\n\n        // Track snapshot metrics\n        const snapshotDuration = Date.now() - snapshotStartTime;\n        yield* Metric.increment(Metrics.storageSnapshots);\n        yield* Metric.update(Metrics.storageSnapshotLatency, snapshotDuration);\n\n        // Update tracking BEFORE truncate (for idempotency on retry)\n        yield* Ref.set(instance.lastSnapshotVersion, snapshotVersion);\n        yield* Ref.set(instance.lastSnapshotTime, Date.now());\n        yield* Ref.set(instance.transactionsSinceSnapshot, 0);\n\n        // Truncate WAL - non-fatal, will be retried on next snapshot\n        yield* Effect.catchAll(hotStorage.truncate(documentId, snapshotVersion), (e) =>\n          Effect.logWarning(\"WAL truncate failed - will retry on next snapshot\", {\n            documentId,\n            version: snapshotVersion,\n            error: e,\n          })\n        );\n      });\n\n    /**\n     * Check if snapshot should be triggered\n     */\n    const checkSnapshotTriggers = (\n      documentId: string,\n      instance: DocumentInstance<typeof config.schema>\n    ): Effect.Effect<void, ColdStorageError | HotStorageError> =>\n      Effect.gen(function* () {\n        const txCount = yield* Ref.get(instance.transactionsSinceSnapshot);\n        const lastTime = yield* Ref.get(instance.lastSnapshotTime);\n        const now = Date.now();\n        const currentVersion = instance.document.getVersion();\n\n        const intervalMs = Duration.toMillis(config.snapshot.interval);\n        const threshold = config.snapshot.transactionThreshold;\n\n        // Check transaction threshold\n        if (txCount >= threshold) {\n          yield* saveSnapshot(documentId, instance, currentVersion);\n          return;\n        }\n\n        // Check time interval\n        if (now - lastTime >= intervalMs) {\n          yield* saveSnapshot(documentId, instance, currentVersion);\n          return;\n        }\n      });\n\n    /**\n     * Start background GC fiber\n     */\n    const startGCFiber = Effect.gen(function* () {\n      const gcLoop = Effect.gen(function* () {\n        const current = yield* Ref.get(store);\n        const now = Date.now();\n        const maxIdleMs = Duration.toMillis(config.maxIdleTime);\n\n        for (const [documentId, instance] of current) {\n          const lastActivity = yield* Ref.get(instance.lastActivityTime);\n          if (now - lastActivity >= maxIdleMs) {\n            // Save final snapshot before eviction (best effort)\n            const currentVersion = instance.document.getVersion();\n            yield* Effect.catchAll(saveSnapshot(documentId, instance, currentVersion), (e) =>\n              Effect.logError(\"Failed to save snapshot during eviction\", {\n                documentId,\n                error: e,\n              })\n            );\n\n            // Remove from store\n            yield* Ref.update(store, (map) => HashMap.remove(map, documentId));\n\n            // Track eviction metrics\n            yield* Metric.increment(Metrics.documentsEvicted);\n            yield* Metric.incrementBy(Metrics.documentsActive, -1);\n\n            yield* Effect.logInfo(\"Document evicted due to idle timeout\", {\n              documentId,\n            });\n          }\n        }\n      });\n\n      // Run GC every minute\n      yield* gcLoop.pipe(\n        Effect.repeat(Schedule.spaced(\"1 minute\")),\n        Effect.fork\n      );\n    });\n\n    // Start GC fiber\n    yield* startGCFiber;\n\n    // Cleanup on shutdown\n    yield* Effect.addFinalizer(() =>\n      Effect.gen(function* () {\n        const current = yield* Ref.get(store);\n        for (const [documentId, instance] of current) {\n          // Best effort save - don't fail shutdown if storage is unavailable\n          const currentVersion = instance.document.getVersion();\n          yield* Effect.catchAll(saveSnapshot(documentId, instance, currentVersion), (e) =>\n            Effect.logError(\"Failed to save snapshot during shutdown\", {\n              documentId,\n              error: e,\n            })\n          );\n        }\n        yield* Effect.logInfo(\"DocumentManager shutdown complete\");\n      })\n    );\n\n    return {\n      submit: (documentId, transaction) =>\n        Effect.gen(function* () {\n          const instance = yield* getOrCreateDocument(documentId);\n          const submitStartTime = Date.now();\n\n          // Phase 1: Validate (no side effects)\n          const validation = instance.document.validate(transaction);\n\n          if (!validation.valid) {\n            // Track rejection\n            yield* Metric.increment(Metrics.transactionsRejected);\n            const latency = Date.now() - submitStartTime;\n            yield* Metric.update(Metrics.transactionsLatency, latency);\n\n            return {\n              success: false as const,\n              reason: validation.reason,\n            };\n          }\n\n          // Phase 2: Append to WAL with gap check (BEFORE state mutation)\n          const walEntry: WalEntry = {\n            transaction,\n            version: validation.nextVersion,\n            timestamp: Date.now(),\n          };\n\n          const appendResult = yield* Effect.either(\n            hotStorage.appendWithCheck(documentId, walEntry, validation.nextVersion)\n          );\n\n          if (appendResult._tag === \"Left\") {\n            // WAL append failed - do NOT apply, state unchanged\n            yield* Effect.logError(\"WAL append failed\", {\n              documentId,\n              version: validation.nextVersion,\n              error: appendResult.left,\n            });\n            yield* Metric.increment(Metrics.walAppendFailures);\n\n            const latency = Date.now() - submitStartTime;\n            yield* Metric.update(Metrics.transactionsLatency, latency);\n\n            // Return failure - client must retry\n            return {\n              success: false as const,\n              reason: \"Storage unavailable. Please retry.\",\n            };\n          }\n\n          // Phase 3: Apply (state mutation + broadcast)\n          instance.document.apply(transaction);\n\n          // Track metrics\n          const latency = Date.now() - submitStartTime;\n          yield* Metric.update(Metrics.transactionsLatency, latency);\n          yield* Metric.increment(Metrics.transactionsProcessed);\n          yield* Metric.increment(Metrics.storageWalAppends);\n\n          // Increment transaction count\n          yield* Ref.update(\n            instance.transactionsSinceSnapshot,\n            (n) => n + 1\n          );\n\n          // Check snapshot triggers\n          yield* checkSnapshotTriggers(documentId, instance);\n\n          return {\n            success: true as const,\n            version: validation.nextVersion,\n          };\n        }),\n\n      getSnapshot: (documentId) =>\n        Effect.gen(function* () {\n          const instance = yield* getOrCreateDocument(documentId);\n          return instance.document.getSnapshot();\n        }),\n\n      subscribe: (documentId) =>\n        Effect.gen(function* () {\n          const instance = yield* getOrCreateDocument(documentId);\n          return Stream.fromPubSub(instance.pubsub);\n        }),\n\n      touch: (documentId) =>\n        Effect.gen(function* () {\n          const current = yield* Ref.get(store);\n          const existing = HashMap.get(current, documentId);\n          if (existing._tag === \"Some\") {\n            yield* Ref.set(existing.value.lastActivityTime, Date.now());\n          }\n        }),\n    };\n  })\n);\n\n// =============================================================================\n// Re-export namespace\n// =============================================================================\n\nexport const DocumentManager = {\n  Tag: DocumentManagerTag,\n  ConfigTag: DocumentManagerConfigTag,\n  layer,\n};\n"],"mappings":"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"}

package/dist/Errors.cjs

@@ -0,0 +1,54 @@
+let effect = require("effect");
+
+//#region src/Errors.ts
+/**
+* @voidhash/mimic-effect - Error Types
+*
+* All error types used throughout the mimic-effect package.
+*/
+/**
+* Error when ColdStorage (snapshot storage) operations fail
+*/
+var ColdStorageError = class extends effect.Data.TaggedError("ColdStorageError") {};
+/**
+* Error when HotStorage (WAL storage) operations fail
+*/
+var HotStorageError = class extends effect.Data.TaggedError("HotStorageError") {};
+/**
+* Error when WAL append detects a version gap.
+* This indicates either:
+* - A bug in the application (skipped a version)
+* - Concurrent writes to the same document
+* - Data corruption in WAL storage
+*/
+var WalVersionGapError = class extends effect.Data.TaggedError("WalVersionGapError") {};
+/**
+* Error when authentication fails (invalid token, expired, etc.)
+*/
+var AuthenticationError = class extends effect.Data.TaggedError("AuthenticationError") {};
+/**
+* Error when authorization fails (user doesn't have required permission)
+*/
+var AuthorizationError = class extends effect.Data.TaggedError("AuthorizationError") {};
+/**
+* Error when document ID is missing from WebSocket request path
+*/
+var MissingDocumentIdError = class extends effect.Data.TaggedError("MissingDocumentIdError") {};
+/**
+* Error when WebSocket message cannot be parsed
+*/
+var MessageParseError = class extends effect.Data.TaggedError("MessageParseError") {};
+/**
+* Error when a transaction is rejected by the document
+*/
+var TransactionRejectedError = class extends effect.Data.TaggedError("TransactionRejectedError") {};
+
+//#endregion
+exports.AuthenticationError = AuthenticationError;
+exports.AuthorizationError = AuthorizationError;
+exports.ColdStorageError = ColdStorageError;
+exports.HotStorageError = HotStorageError;
+exports.MessageParseError = MessageParseError;
+exports.MissingDocumentIdError = MissingDocumentIdError;
+exports.TransactionRejectedError = TransactionRejectedError;
+exports.WalVersionGapError = WalVersionGapError;

package/dist/Errors.d.cts

@@ -0,0 +1,96 @@
+import * as effect_Types0 from "effect/Types";
+import * as effect_Cause0 from "effect/Cause";
+
+//#region src/Errors.d.ts
+declare const ColdStorageError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "ColdStorageError";
+} & Readonly<A>;
+/**
+ * Error when ColdStorage (snapshot storage) operations fail
+ */
+declare class ColdStorageError extends ColdStorageError_base<{
+  readonly documentId: string;
+  readonly operation: "load" | "save" | "delete";
+  readonly cause: unknown;
+}> {}
+declare const HotStorageError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "HotStorageError";
+} & Readonly<A>;
+/**
+ * Error when HotStorage (WAL storage) operations fail
+ */
+declare class HotStorageError extends HotStorageError_base<{
+  readonly documentId: string;
+  readonly operation: "append" | "getEntries" | "truncate" | "appendWithCheck";
+  readonly cause: unknown;
+}> {}
+declare const WalVersionGapError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "WalVersionGapError";
+} & Readonly<A>;
+/**
+ * Error when WAL append detects a version gap.
+ * This indicates either:
+ * - A bug in the application (skipped a version)
+ * - Concurrent writes to the same document
+ * - Data corruption in WAL storage
+ */
+declare class WalVersionGapError extends WalVersionGapError_base<{
+  readonly documentId: string;
+  readonly expectedVersion: number;
+  readonly actualPreviousVersion: number | undefined;
+}> {}
+declare const AuthenticationError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "AuthenticationError";
+} & Readonly<A>;
+/**
+ * Error when authentication fails (invalid token, expired, etc.)
+ */
+declare class AuthenticationError extends AuthenticationError_base<{
+  readonly reason: string;
+}> {}
+declare const AuthorizationError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "AuthorizationError";
+} & Readonly<A>;
+/**
+ * Error when authorization fails (user doesn't have required permission)
+ */
+declare class AuthorizationError extends AuthorizationError_base<{
+  readonly reason: string;
+  readonly required: "read" | "write";
+  readonly actual: "read" | "write";
+}> {}
+declare const MissingDocumentIdError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "MissingDocumentIdError";
+} & Readonly<A>;
+/**
+ * Error when document ID is missing from WebSocket request path
+ */
+declare class MissingDocumentIdError extends MissingDocumentIdError_base<{
+  readonly path: string;
+}> {}
+declare const MessageParseError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "MessageParseError";
+} & Readonly<A>;
+/**
+ * Error when WebSocket message cannot be parsed
+ */
+declare class MessageParseError extends MessageParseError_base<{
+  readonly cause: unknown;
+}> {}
+declare const TransactionRejectedError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "TransactionRejectedError";
+} & Readonly<A>;
+/**
+ * Error when a transaction is rejected by the document
+ */
+declare class TransactionRejectedError extends TransactionRejectedError_base<{
+  readonly transactionId: string;
+  readonly reason: string;
+}> {}
+/**
+ * Union of all mimic-effect errors
+ */
+type MimicError = ColdStorageError | HotStorageError | WalVersionGapError | AuthenticationError | AuthorizationError | MissingDocumentIdError | MessageParseError | TransactionRejectedError;
+//#endregion
+export { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MimicError, MissingDocumentIdError, TransactionRejectedError, WalVersionGapError };
+//# sourceMappingURL=Errors.d.cts.map

package/dist/Errors.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Errors.d.cts","names":[],"sources":["../src/Errors.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;cAca,gBAAA,SAAyB;;;;;cAIjC;;;;;AAJL;AAIK,cAKQ,eAAA,SAAwB,oBALhC,CAAA;;;;;cASA;;;;;;;AAJL;AAIK;;cASQ,kBAAA,SAA2B;;;;;cAInC;;;;;AAJL;AAIK,cASQ,mBAAA,SAA4B,wBATpC,CAAA;;;cAaA;;;;;;cAKQ,kBAAA,SAA2B;;;EAT3B,SAAA,MAAA,EAAA,MAAoB,GAAA,OAAA;AAI5B,CAAA,CAAA,CAAA;cASA;;;;;;cASQ,sBAAA,SAA+B;;;cAIvC;EAjBQ,SAAA,IAAA,EAAA,mBAA2B;AAInC,CAAA,WAAA,EAAA,CAAA;;;;cAkBQ,iBAAA,SAA0B;;;cAElC;;;;;AAXL;AAIK,cAgBQ,wBAAA,SAAiC,6BAhBzC,CAAA;;;;;;;KA8BO,UAAA,GACR,mBACA,kBACA,qBACA,sBACA,qBACA,yBACA,oBACA"}