@voidhash/mimic-effect 1.0.0-beta.7 → 1.0.0-beta.9

package/dist/DocumentInstance.d.mts

@@ -0,0 +1,74 @@
+import { ColdStorageError, HotStorageError } from "./Errors.mjs";
+import { ServerBroadcast } from "./Protocol.mjs";
+import { ColdStorage } from "./ColdStorage.mjs";
+import { HotStorage } from "./HotStorage.mjs";
+import { Duration, Effect, PubSub } from "effect";
+import { Primitive, Transaction } from "@voidhash/mimic";
+import { ServerDocument } from "@voidhash/mimic/server";
+
+//#region src/DocumentInstance.d.ts
+
+/**
+ * Result of submitting a transaction
+ */
+type SubmitResult = {
+  readonly success: true;
+  readonly version: number;
+} | {
+  readonly success: false;
+  readonly reason: string;
+};
+/**
+ * Configuration for a DocumentInstance
+ */
+interface DocumentInstanceConfig<TSchema extends Primitive.AnyPrimitive> {
+  readonly schema: TSchema;
+  readonly initial?: Primitive.InferSetInput<TSchema> | ((ctx: {
+    documentId: string;
+  }) => Effect.Effect<Primitive.InferSetInput<TSchema>>);
+  readonly maxTransactionHistory: number;
+  readonly snapshot: {
+    readonly interval: Duration.Duration;
+    readonly transactionThreshold: number;
+  };
+}
+/**
+ * Snapshot tracking state
+ */
+interface SnapshotTracking {
+  readonly lastSnapshotVersion: number;
+  readonly lastSnapshotTime: number;
+  readonly transactionsSinceSnapshot: number;
+}
+/**
+ * A DocumentInstance manages a single document's lifecycle
+ */
+interface DocumentInstance<TSchema extends Primitive.AnyPrimitive> {
+  /** The underlying ServerDocument */
+  readonly document: ServerDocument.ServerDocument<TSchema>;
+  /** PubSub for broadcasting messages to subscribers */
+  readonly pubsub: PubSub.PubSub<ServerBroadcast>;
+  /** Current snapshot tracking state */
+  readonly getSnapshotTracking: Effect.Effect<SnapshotTracking>;
+  /** Submit a transaction */
+  readonly submit: (transaction: Transaction.Transaction) => Effect.Effect<SubmitResult, ColdStorageError | HotStorageError>;
+  /** Save a snapshot to cold storage */
+  readonly saveSnapshot: () => Effect.Effect<void, ColdStorageError | HotStorageError>;
+  /** Check if snapshot should be triggered and save if needed */
+  readonly checkSnapshotTriggers: () => Effect.Effect<void, ColdStorageError | HotStorageError>;
+  /** Update last activity time (for external tracking) */
+  readonly touch: () => Effect.Effect<void>;
+  /** Get current document version */
+  readonly getVersion: () => number;
+  /** Get document snapshot */
+  readonly getSnapshot: () => {
+    state: unknown;
+    version: number;
+  };
+}
+declare const DocumentInstance: {
+  make: <TSchema extends Primitive.AnyPrimitive>(documentId: string, config: DocumentInstanceConfig<TSchema>, coldStorage: ColdStorage, hotStorage: HotStorage) => Effect.Effect<DocumentInstance<TSchema>, ColdStorageError | HotStorageError>;
+};
+//#endregion
+export { DocumentInstance, SubmitResult };
+//# sourceMappingURL=DocumentInstance.d.mts.map

package/dist/DocumentInstance.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentInstance.d.mts","names":[],"sources":["../src/DocumentInstance.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAkDA;AASiB,KA/BL,YAAA,GA+BqB;EAAiB,SAAU,OAAA,EAAA,IAAA;EAET,SAAA,OAAA,EAAA,MAAA;CAA9B,GAAA;EAEY,SAAA,OAAA,EAAA,KAAA;EAAd,SAAO,MAAA,EAAA,MAAA;CAEoB;;;;AAE2C,UAhCxE,sBAgCwE,CAAA,gBAhCjC,SAAA,CAAU,YAgCuB,CAAA,CAAA;EAAmB,SAAA,MAAA,EA/BzF,OA+ByF;EAA/C,SAAO,OAAA,CAAA,EA7B9D,SAAA,CAAU,aA6BoD,CA7BtC,OA6BsC,CAAA,GAAA,CAAA,CAAA,GAAA,EAAA;IAEjB,UAAA,EAAA,MAAA;EAAmB,CAAA,EAAA,GA9B9B,MAAA,CAAO,MA8BuB,CA9BhB,SAAA,CAAU,aA8BM,CA9BQ,OA8BR,CAAA,CAAA,CAAA;EAAvC,SAAO,qBAAA,EAAA,MAAA;EAEsB,SAAA,QAAA,EAAA;IAAmB,SAAA,QAAA,EA7BxD,QAAA,CAAS,QA6B+C;IAAhC,SAAA,oBAAA,EAAA,MAAA;EAEvB,CAAA;;AAwbxB;;;AAjaU,UA9CO,gBAAA,CA8CP;EACK,SAAA,mBAAA,EAAA,MAAA;EACD,SAAA,gBAAA,EAAA,MAAA;EACoB,SAAA,yBAAA,EAAA,MAAA;;;;;AAAlB,UAxCC,gBAwCD,CAAA,gBAxCkC,SAAA,CAAU,YAwC5C,CAAA,CAAA;;qBAtCK,cAAA,CAAe,eAAe;;mBAEhC,MAAA,CAAO,OAAO;;gCAED,MAAA,CAAO,OAAO;;iCAEb,WAAA,CAAY,gBAAgB,MAAA,CAAO,OAAO,cAAc,mBAAmB;;+BAE7E,MAAA,CAAO,aAAa,mBAAmB;;wCAE9B,MAAA,CAAO,aAAa,mBAAmB;;wBAEvD,MAAA,CAAO;;;;;;;;;cAwblB;yBAnawB,SAAA,CAAU,0CAErC,uBAAuB,uBAClB,yBACD,eACX,MAAA,CAAO,OAAO,iBAAiB,UAAU,mBAAmB"}

package/dist/DocumentInstance.mjs

@@ -0,0 +1,258 @@
+import { documentsActive, documentsCreated, documentsRestored, storageSnapshotLatency, storageSnapshots, storageVersionGaps, storageWalAppends, transactionsLatency, transactionsProcessed, transactionsRejected, walAppendFailures } from "./Metrics.mjs";
+import { Duration, Effect, Metric, PubSub, Ref } from "effect";
+import { Document } from "@voidhash/mimic";
+import { ServerDocument } from "@voidhash/mimic/server";
+
+//#region src/DocumentInstance.ts
+/**
+* @voidhash/mimic-effect - DocumentInstance
+*
+* Manages the lifecycle of a single document including:
+* - Restoration from storage (cold storage + WAL replay)
+* - Transaction submission with WAL persistence
+* - Snapshot saving and trigger checking
+*
+* Used by both MimicServerEngine (single-node) and MimicClusterServerEngine (clustered).
+*/
+/**
+* Create a DocumentInstance for a single document.
+*
+* This handles:
+* - Loading from cold storage or computing initial state
+* - Persisting initial state immediately (crash safety)
+* - Replaying WAL entries
+* - Transaction submission with WAL persistence
+* - Snapshot saving
+*/
+const make = (documentId, config, coldStorage, hotStorage) => Effect.gen(function* () {
+	const SCHEMA_VERSION = 1;
+	const storedDoc = yield* coldStorage.load(documentId);
+	let initialState;
+	let initial;
+	let initialVersion = 0;
+	if (storedDoc) {
+		initialState = storedDoc.state;
+		initialVersion = storedDoc.version;
+	} else initial = yield* computeInitialState(config, documentId);
+	const pubsub = yield* PubSub.unbounded();
+	const lastSnapshotVersionRef = yield* Ref.make(initialVersion);
+	const lastSnapshotTimeRef = yield* Ref.make(Date.now());
+	const transactionsSinceSnapshotRef = yield* Ref.make(0);
+	const lastActivityTimeRef = yield* Ref.make(Date.now());
+	const document = ServerDocument.make({
+		schema: config.schema,
+		initial,
+		initialState,
+		initialVersion,
+		maxTransactionHistory: config.maxTransactionHistory,
+		onBroadcast: (message) => {
+			Effect.runSync(PubSub.publish(pubsub, {
+				type: "transaction",
+				transaction: message.transaction,
+				version: message.version
+			}));
+		},
+		onRejection: (transactionId, reason) => {
+			Effect.runSync(PubSub.publish(pubsub, {
+				type: "error",
+				transactionId,
+				reason
+			}));
+		}
+	});
+	if (!storedDoc) {
+		const initialStoredDoc = createStoredDocument(document.get(), 0, SCHEMA_VERSION);
+		yield* coldStorage.save(documentId, initialStoredDoc);
+		yield* Effect.logDebug("Initial state persisted to cold storage", { documentId });
+	}
+	const walEntries = yield* hotStorage.getEntries(documentId, initialVersion);
+	yield* verifyWalContinuity(documentId, walEntries, initialVersion);
+	yield* replayWalEntries(documentId, document, walEntries);
+	if (storedDoc) yield* Metric.increment(documentsRestored);
+	else yield* Metric.increment(documentsCreated);
+	yield* Metric.incrementBy(documentsActive, 1);
+	const getSnapshotTracking = Effect.gen(function* () {
+		return {
+			lastSnapshotVersion: yield* Ref.get(lastSnapshotVersionRef),
+			lastSnapshotTime: yield* Ref.get(lastSnapshotTimeRef),
+			transactionsSinceSnapshot: yield* Ref.get(transactionsSinceSnapshotRef)
+		};
+	});
+	const saveSnapshot = Effect.fn("document.snapshot.save")(function* () {
+		var _baseSnapshot$version;
+		const targetVersion = document.getVersion();
+		if (targetVersion <= (yield* Ref.get(lastSnapshotVersionRef))) 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 walEntries$1 = yield* hotStorage.getEntries(documentId, baseVersion);
+		const snapshotResult = computeSnapshotState(config.schema, baseState, walEntries$1, targetVersion);
+		if (!snapshotResult) return;
+		const currentLastSnapshot = yield* Ref.get(lastSnapshotVersionRef);
+		if (snapshotResult.version <= currentLastSnapshot) return;
+		const storedDoc$1 = createStoredDocument(snapshotResult.state, snapshotResult.version, SCHEMA_VERSION);
+		yield* coldStorage.save(documentId, storedDoc$1);
+		const snapshotDuration = Date.now() - snapshotStartTime;
+		yield* Metric.increment(storageSnapshots);
+		yield* Metric.update(storageSnapshotLatency, snapshotDuration);
+		yield* Ref.set(lastSnapshotVersionRef, snapshotResult.version);
+		yield* Ref.set(lastSnapshotTimeRef, Date.now());
+		yield* Ref.set(transactionsSinceSnapshotRef, 0);
+		yield* Effect.catchAll(hotStorage.truncate(documentId, snapshotResult.version), (e) => Effect.logWarning("WAL truncate failed - will retry on next snapshot", {
+			documentId,
+			version: snapshotResult.version,
+			error: e
+		}));
+	});
+	const checkSnapshotTriggers = Effect.fn("document.snapshot.check-triggers")(function* () {
+		if (shouldTriggerSnapshot(yield* Ref.get(transactionsSinceSnapshotRef), yield* Ref.get(lastSnapshotTimeRef), config.snapshot)) yield* saveSnapshot();
+	});
+	return {
+		document,
+		pubsub,
+		getSnapshotTracking,
+		submit: Effect.fn("document.transaction.submit")(function* (transaction) {
+			const submitStartTime = Date.now();
+			yield* Ref.set(lastActivityTimeRef, Date.now());
+			const validation = 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."
+				};
+			}
+			document.apply(transaction);
+			const latency = Date.now() - submitStartTime;
+			yield* Metric.update(transactionsLatency, latency);
+			yield* Metric.increment(transactionsProcessed);
+			yield* Metric.increment(storageWalAppends);
+			yield* Ref.update(transactionsSinceSnapshotRef, (n) => n + 1);
+			yield* checkSnapshotTriggers();
+			return {
+				success: true,
+				version: validation.nextVersion
+			};
+		}),
+		saveSnapshot,
+		checkSnapshotTriggers,
+		touch: Effect.fn("document.touch")(function* () {
+			yield* Ref.set(lastActivityTimeRef, Date.now());
+		}),
+		getVersion: () => document.getVersion(),
+		getSnapshot: () => document.getSnapshot()
+	};
+});
+/**
+* Compute initial state for a new document.
+*/
+const computeInitialState = (config, 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);
+};
+/**
+* Verify WAL continuity and log warnings for any gaps.
+*/
+const verifyWalContinuity = Effect.fn("document.wal.verify")(function* (documentId, walEntries, baseVersion) {
+	if (walEntries.length === 0) return;
+	const firstWalVersion = walEntries[0].version;
+	const expectedFirst = baseVersion + 1;
+	if (firstWalVersion !== expectedFirst) {
+		yield* Effect.logWarning("WAL version gap detected", {
+			documentId,
+			snapshotVersion: baseVersion,
+			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
+		});
+	}
+});
+/**
+* Replay WAL entries onto a ServerDocument.
+*/
+const replayWalEntries = Effect.fn("document.wal.replay")(function* (documentId, document, walEntries) {
+	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
+		});
+	}
+});
+/**
+* Compute snapshot state by replaying WAL entries on a base state.
+*/
+const computeSnapshotState = (schema, baseState, walEntries, targetVersion) => {
+	const relevantEntries = walEntries.filter((e) => e.version <= targetVersion);
+	if (relevantEntries.length === 0 && baseState === void 0) return;
+	let snapshotState = baseState;
+	for (const entry of relevantEntries) {
+		const tempDoc = Document.make(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 : 0;
+	return {
+		state: snapshotState,
+		version: snapshotVersion
+	};
+};
+/**
+* Check if a snapshot should be triggered.
+*/
+const shouldTriggerSnapshot = (transactionsSinceSnapshot, lastSnapshotTime, config) => {
+	const now = Date.now();
+	const intervalMs = Duration.toMillis(config.interval);
+	if (transactionsSinceSnapshot >= config.transactionThreshold) return true;
+	if (now - lastSnapshotTime >= intervalMs) return true;
+	return false;
+};
+/**
+* Create a StoredDocument for persistence.
+*/
+const createStoredDocument = (state, version, schemaVersion) => ({
+	state,
+	version,
+	schemaVersion,
+	savedAt: Date.now()
+});
+const DocumentInstance = { make };
+
+//#endregion
+export { DocumentInstance };
+//# sourceMappingURL=DocumentInstance.mjs.map

package/dist/DocumentInstance.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentInstance.mjs","names":["initialState: Primitive.InferState<TSchema> | undefined","initial: Primitive.InferSetInput<TSchema> | undefined","Metrics.documentsRestored","Metrics.documentsCreated","Metrics.documentsActive","walEntries","storedDoc","Metrics.storageSnapshots","Metrics.storageSnapshotLatency","Metrics.transactionsRejected","latency","Metrics.transactionsLatency","walEntry: WalEntry","Metrics.walAppendFailures","Metrics.transactionsProcessed","Metrics.storageWalAppends","Metrics.storageVersionGaps","snapshotState: Primitive.InferState<TSchema> | undefined"],"sources":["../src/DocumentInstance.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - DocumentInstance\n *\n * Manages the lifecycle of a single document including:\n * - Restoration from storage (cold storage + WAL replay)\n * - Transaction submission with WAL persistence\n * - Snapshot saving and trigger checking\n *\n * Used by both MimicServerEngine (single-node) and MimicClusterServerEngine (clustered).\n */\nimport { Duration, Effect, Metric, PubSub, Ref } from \"effect\";\nimport { Document, type Primitive, type Transaction } from \"@voidhash/mimic\";\nimport { ServerDocument } from \"@voidhash/mimic/server\";\nimport type { StoredDocument, WalEntry } from \"./Types\";\nimport type { ServerBroadcast } from \"./Protocol\";\nimport type { ColdStorage } from \"./ColdStorage\";\nimport type { HotStorage } from \"./HotStorage\";\nimport type { ColdStorageError } from \"./Errors\";\nimport type { HotStorageError } from \"./Errors\";\nimport * as Metrics from \"./Metrics\";\n\n// =============================================================================\n// 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 * Configuration for a DocumentInstance\n */\nexport interface DocumentInstanceConfig<TSchema extends Primitive.AnyPrimitive> {\n  readonly schema: TSchema;\n  readonly initial?:\n    | Primitive.InferSetInput<TSchema>\n    | ((ctx: { documentId: string }) => Effect.Effect<Primitive.InferSetInput<TSchema>>);\n  readonly maxTransactionHistory: number;\n  readonly snapshot: {\n    readonly interval: Duration.Duration;\n    readonly transactionThreshold: number;\n  };\n}\n\n/**\n * Snapshot tracking state\n */\nexport interface SnapshotTracking {\n  readonly lastSnapshotVersion: number;\n  readonly lastSnapshotTime: number;\n  readonly transactionsSinceSnapshot: number;\n}\n\n/**\n * A DocumentInstance manages a single document's lifecycle\n */\nexport interface DocumentInstance<TSchema extends Primitive.AnyPrimitive> {\n  /** The underlying ServerDocument */\n  readonly document: ServerDocument.ServerDocument<TSchema>;\n  /** PubSub for broadcasting messages to subscribers */\n  readonly pubsub: PubSub.PubSub<ServerBroadcast>;\n  /** Current snapshot tracking state */\n  readonly getSnapshotTracking: Effect.Effect<SnapshotTracking>;\n  /** Submit a transaction */\n  readonly submit: (transaction: Transaction.Transaction) => Effect.Effect<SubmitResult, ColdStorageError | HotStorageError>;\n  /** Save a snapshot to cold storage */\n  readonly saveSnapshot: () => Effect.Effect<void, ColdStorageError | HotStorageError>;\n  /** Check if snapshot should be triggered and save if needed */\n  readonly checkSnapshotTriggers: () => Effect.Effect<void, ColdStorageError | HotStorageError>;\n  /** Update last activity time (for external tracking) */\n  readonly touch: () => Effect.Effect<void>;\n  /** Get current document version */\n  readonly getVersion: () => number;\n  /** Get document snapshot */\n  readonly getSnapshot: () => { state: unknown; version: number };\n}\n\n// =============================================================================\n// Factory\n// =============================================================================\n\n/**\n * Create a DocumentInstance for a single document.\n *\n * This handles:\n * - Loading from cold storage or computing initial state\n * - Persisting initial state immediately (crash safety)\n * - Replaying WAL entries\n * - Transaction submission with WAL persistence\n * - Snapshot saving\n */\nexport const make = <TSchema extends Primitive.AnyPrimitive>(\n  documentId: string,\n  config: DocumentInstanceConfig<TSchema>,\n  coldStorage: ColdStorage,\n  hotStorage: HotStorage\n): Effect.Effect<DocumentInstance<TSchema>, ColdStorageError | HotStorageError> =>\n  Effect.gen(function* () {\n    // Current schema version (hard-coded to 1 for now)\n    const SCHEMA_VERSION = 1;\n\n    // 1. Load snapshot from ColdStorage\n    const storedDoc = yield* coldStorage.load(documentId);\n\n    // Track initial values - only one will be set:\n    // - initialState: raw state from storage (already in internal format)\n    // - initial: computed from config (needs conversion to state format)\n    let initialState: Primitive.InferState<TSchema> | undefined;\n    let initial: Primitive.InferSetInput<TSchema> | undefined;\n    let initialVersion = 0;\n\n    if (storedDoc) {\n      // Loading from storage - state is already in internal format\n      initialState = storedDoc.state as Primitive.InferState<TSchema>;\n      initialVersion = storedDoc.version;\n    } else {\n      // New document - compute initial value (set input format)\n      initial = yield* computeInitialState(config, 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 lastSnapshotVersionRef = yield* Ref.make(initialVersion);\n    const lastSnapshotTimeRef = yield* Ref.make(Date.now());\n    const transactionsSinceSnapshotRef = yield* Ref.make(0);\n    const lastActivityTimeRef = yield* Ref.make(Date.now());\n\n    // 4. Create ServerDocument with callbacks\n    const document = ServerDocument.make({\n      schema: config.schema,\n      initial,\n      initialState,\n      initialVersion,\n      maxTransactionHistory: config.maxTransactionHistory,\n      onBroadcast: (message: ServerDocument.TransactionMessage) => {\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. If this is a new document, immediately save to cold storage\n    // This ensures the initial state is durable before any transactions are accepted.\n    if (!storedDoc) {\n      const initialStoredDoc = createStoredDocument(document.get(), 0, SCHEMA_VERSION);\n      yield* coldStorage.save(documentId, initialStoredDoc);\n      yield* Effect.logDebug(\"Initial state persisted to cold storage\", { documentId });\n    }\n\n    // 6. Load WAL entries\n    const walEntries = yield* hotStorage.getEntries(documentId, initialVersion);\n\n    // 7. Verify WAL continuity (warning only, non-blocking)\n    yield* verifyWalContinuity(documentId, walEntries, initialVersion);\n\n    // 8. Replay WAL entries\n    yield* replayWalEntries(documentId, document, walEntries);\n\n    // Track metrics\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    // ==========================================================================\n    // Instance Methods\n    // ==========================================================================\n\n    const getSnapshotTracking = Effect.gen(function* () {\n      return {\n        lastSnapshotVersion: yield* Ref.get(lastSnapshotVersionRef),\n        lastSnapshotTime: yield* Ref.get(lastSnapshotTimeRef),\n        transactionsSinceSnapshot: yield* Ref.get(transactionsSinceSnapshotRef),\n      };\n    });\n\n    const saveSnapshot = Effect.fn(\"document.snapshot.save\")(function* () {\n      const targetVersion = document.getVersion();\n      const lastSnapshotVersion = yield* Ref.get(lastSnapshotVersionRef);\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<TSchema> | undefined;\n\n      // Load WAL entries from base to target\n      const walEntries = yield* hotStorage.getEntries(documentId, baseVersion);\n\n      // Compute snapshot state by replaying WAL on base\n      const snapshotResult = computeSnapshotState(\n        config.schema,\n        baseState,\n        walEntries,\n        targetVersion\n      );\n\n      if (!snapshotResult) {\n        return;\n      }\n\n      // Re-check before saving (in case another snapshot completed while we were working)\n      const currentLastSnapshot = yield* Ref.get(lastSnapshotVersionRef);\n      if (snapshotResult.version <= currentLastSnapshot) {\n        return;\n      }\n\n      const storedDoc = createStoredDocument(\n        snapshotResult.state,\n        snapshotResult.version,\n        SCHEMA_VERSION\n      );\n\n      // Save to ColdStorage\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(lastSnapshotVersionRef, snapshotResult.version);\n      yield* Ref.set(lastSnapshotTimeRef, Date.now());\n      yield* Ref.set(transactionsSinceSnapshotRef, 0);\n\n      // Truncate WAL - non-fatal, will be retried on next snapshot\n      yield* Effect.catchAll(hotStorage.truncate(documentId, snapshotResult.version), (e) =>\n        Effect.logWarning(\"WAL truncate failed - will retry on next snapshot\", {\n          documentId,\n          version: snapshotResult.version,\n          error: e,\n        })\n      );\n    });\n\n    const checkSnapshotTriggers = Effect.fn(\"document.snapshot.check-triggers\")(function* () {\n      const txCount = yield* Ref.get(transactionsSinceSnapshotRef);\n      const lastTime = yield* Ref.get(lastSnapshotTimeRef);\n\n      if (shouldTriggerSnapshot(txCount, lastTime, config.snapshot)) {\n        yield* saveSnapshot();\n      }\n    });\n\n    const submit = Effect.fn(\"document.transaction.submit\")(function* (\n      transaction: Transaction.Transaction\n    ) {\n      const submitStartTime = Date.now();\n\n      // Update activity time\n      yield* Ref.set(lastActivityTimeRef, Date.now());\n\n      // Phase 1: Validate (no side effects)\n      const validation = document.validate(transaction);\n\n      if (!validation.valid) {\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        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 {\n          success: false as const,\n          reason: \"Storage unavailable. Please retry.\",\n        };\n      }\n\n      // Phase 3: Apply (state mutation + broadcast)\n      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(transactionsSinceSnapshotRef, (n) => n + 1);\n\n      // Check snapshot triggers\n      yield* checkSnapshotTriggers();\n\n      return {\n        success: true as const,\n        version: validation.nextVersion,\n      };\n    });\n\n    const touch = Effect.fn(\"document.touch\")(function* () {\n      yield* Ref.set(lastActivityTimeRef, Date.now());\n    });\n\n    return {\n      document,\n      pubsub,\n      getSnapshotTracking,\n      submit,\n      saveSnapshot,\n      checkSnapshotTriggers,\n      touch,\n      getVersion: () => document.getVersion(),\n      getSnapshot: () => document.getSnapshot(),\n    };\n  });\n\n// =============================================================================\n// Helper Functions\n// =============================================================================\n\n/**\n * Compute initial state for a new document.\n */\nconst computeInitialState = <TSchema extends Primitive.AnyPrimitive>(\n  config: DocumentInstanceConfig<TSchema>,\n  documentId: string\n): Effect.Effect<Primitive.InferSetInput<TSchema> | undefined> => {\n  if (config.initial === undefined) {\n    return Effect.succeed(undefined);\n  }\n\n  if (typeof config.initial === \"function\") {\n    return (config.initial as (ctx: { documentId: string }) => Effect.Effect<Primitive.InferSetInput<TSchema>>)({\n      documentId,\n    });\n  }\n\n  return Effect.succeed(config.initial as Primitive.InferSetInput<TSchema>);\n};\n\n/**\n * Verify WAL continuity and log warnings for any gaps.\n */\nconst verifyWalContinuity = Effect.fn(\"document.wal.verify\")(function* (\n  documentId: string,\n  walEntries: readonly WalEntry[],\n  baseVersion: number\n) {\n  if (walEntries.length === 0) {\n    return;\n  }\n\n  const firstWalVersion = walEntries[0]!.version;\n  const expectedFirst = baseVersion + 1;\n\n  if (firstWalVersion !== expectedFirst) {\n    yield* Effect.logWarning(\"WAL version gap detected\", {\n      documentId,\n      snapshotVersion: baseVersion,\n      firstWalVersion,\n      expectedFirst,\n    });\n    yield* Metric.increment(Metrics.storageVersionGaps);\n  }\n\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/**\n * Replay WAL entries onto a ServerDocument.\n */\nconst replayWalEntries = Effect.fn(\"document.wal.replay\")(function* (\n  documentId: string,\n  document: ServerDocument.ServerDocument<Primitive.AnyPrimitive>,\n  walEntries: readonly WalEntry[]\n) {\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\n/**\n * Compute snapshot state by replaying WAL entries on a base state.\n */\nconst computeSnapshotState = <TSchema extends Primitive.AnyPrimitive>(\n  schema: TSchema,\n  baseState: Primitive.InferState<TSchema> | undefined,\n  walEntries: readonly WalEntry[],\n  targetVersion: number\n): { state: Primitive.InferState<TSchema>; version: number } | undefined => {\n  const relevantEntries = walEntries.filter((e) => e.version <= targetVersion);\n\n  if (relevantEntries.length === 0 && baseState === undefined) {\n    return undefined;\n  }\n\n  let snapshotState: Primitive.InferState<TSchema> | undefined = baseState;\n  for (const entry of relevantEntries) {\n    const tempDoc = Document.make(schema, { initialState: snapshotState });\n    tempDoc.apply(entry.transaction.ops);\n    snapshotState = tempDoc.get();\n  }\n\n  if (snapshotState === undefined) {\n    return undefined;\n  }\n\n  const snapshotVersion =\n    relevantEntries.length > 0 ? relevantEntries[relevantEntries.length - 1]!.version : 0;\n\n  return { state: snapshotState, version: snapshotVersion };\n};\n\n/**\n * Check if a snapshot should be triggered.\n */\nconst shouldTriggerSnapshot = (\n  transactionsSinceSnapshot: number,\n  lastSnapshotTime: number,\n  config: { interval: Duration.Duration; transactionThreshold: number }\n): boolean => {\n  const now = Date.now();\n  const intervalMs = Duration.toMillis(config.interval);\n\n  if (transactionsSinceSnapshot >= config.transactionThreshold) {\n    return true;\n  }\n\n  if (now - lastSnapshotTime >= intervalMs) {\n    return true;\n  }\n\n  return false;\n};\n\n/**\n * Create a StoredDocument for persistence.\n */\nconst createStoredDocument = (\n  state: unknown,\n  version: number,\n  schemaVersion: number\n): StoredDocument => ({\n  state,\n  version,\n  schemaVersion,\n  savedAt: Date.now(),\n});\n\n// =============================================================================\n// Re-export namespace\n// =============================================================================\n\nexport const DocumentInstance = {\n  make,\n};\n"],"mappings":"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"}

package/dist/MimicClusterServerEngine.cjs

@@ -1,11 +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 = require("@voidhash/mimic");
-let _voidhash_mimic_server = require("@voidhash/mimic/server");
 let _effect_cluster = require("@effect/cluster");
 let _effect_rpc = require("@effect/rpc");
 
@@ -133,224 +132,41 @@ const encodeTransaction = (tx) => {
 */
 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* coldStorage.load(documentId).pipe(effect.Effect.orDie);
-	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
+		presencePubSub
 	});
-	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
-			}));
-		}
-	});
-	yield* effect.Ref.update(stateRef, (s) => require_objectSpread2._objectSpread2(require_objectSpread2._objectSpread2({}, s), {}, { document }));
-	const walEntries = yield* hotStorage.getEntries(documentId, initialVersion).pipe(effect.Effect.orDie);
-	if (walEntries.length > 0) {
-		const firstWalVersion = walEntries[0].version;
-		const expectedFirst = initialVersion + 1;
-		if (firstWalVersion !== expectedFirst) {
-			yield* effect.Effect.logWarning("WAL version gap detected", {
-				documentId,
-				snapshotVersion: initialVersion,
-				firstWalVersion,
-				expectedFirst
-			});
-			yield* effect.Metric.increment(require_Metrics.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.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.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 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 = effect.Effect.fn("cluster.document.snapshot.save")(function* (targetVersion) {
-		var _baseSnapshot$version;
-		if (targetVersion <= (yield* effect.Ref.get(stateRef)).lastSnapshotVersion) return;
-		const snapshotStartTime = Date.now();
-		const baseSnapshotResult = yield* effect.Effect.either(coldStorage.load(documentId));
-		if (baseSnapshotResult._tag === "Left") {
-			yield* effect.Effect.logError("Failed to load base snapshot for WAL replay", {
-				documentId,
-				error: baseSnapshotResult.left
-			});
-			return;
-		}
-		const baseSnapshot = baseSnapshotResult.right;
-		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 walEntriesResult = yield* effect.Effect.either(hotStorage.getEntries(documentId, baseVersion));
-		if (walEntriesResult._tag === "Left") {
-			yield* effect.Effect.logError("Failed to load WAL entries for snapshot", {
-				documentId,
-				error: walEntriesResult.left
-			});
-			return;
-		}
-		const relevantEntries = walEntriesResult.right.filter((e) => e.version <= targetVersion);
-		if (relevantEntries.length === 0 && !baseSnapshot) return;
-		let snapshotState = baseState;
-		for (const entry of relevantEntries) {
-			const tempDoc = _voidhash_mimic.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* effect.Ref.get(stateRef)).lastSnapshotVersion) return;
-		const storedDocument = {
-			state: snapshotState,
-			version: snapshotVersion,
-			schemaVersion: SCHEMA_VERSION,
-			savedAt: 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.Ref.update(stateRef, (s) => require_objectSpread2._objectSpread2(require_objectSpread2._objectSpread2({}, s), {}, {
-			lastSnapshotVersion: snapshotVersion,
-			lastSnapshotTime: Date.now(),
-			transactionsSinceSnapshot: 0
-		}));
-		yield* effect.Effect.catchAll(hotStorage.truncate(documentId, snapshotVersion), (e) => effect.Effect.logWarning("WAL truncate failed - will retry on next snapshot", {
+	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,
-			version: snapshotVersion,
 			error: e
 		}));
-	});
-	/**
-	* Check if snapshot should be triggered
-	*/
-	const checkSnapshotTriggers = effect.Effect.fn("cluster.document.snapshot.check-triggers")(function* () {
-		const state = yield* effect.Ref.get(stateRef);
-		const now = Date.now();
-		const currentVersion = state.document.getVersion();
-		const intervalMs = effect.Duration.toMillis(config.snapshot.interval);
-		const threshold = config.snapshot.transactionThreshold;
-		if (state.transactionsSinceSnapshot >= threshold) {
-			yield* saveSnapshot(currentVersion);
-			return;
-		}
-		if (now - state.lastSnapshotTime >= intervalMs) {
-			yield* saveSnapshot(currentVersion);
-			return;
-		}
-	});
-	yield* effect.Effect.addFinalizer(() => effect.Effect.fn("cluster.entity.finalize")(function* () {
-		yield* saveSnapshot((yield* effect.Ref.get(stateRef)).document.getVersion());
 		yield* effect.Metric.incrementBy(require_Metrics.documentsActive, -1);
 		yield* effect.Metric.increment(require_Metrics.documentsEvicted);
 		yield* effect.Effect.logDebug("Entity finalized", { documentId });
 	})());
 	return {
 		Submit: effect.Effect.fn("cluster.document.transaction.submit")(function* ({ payload }) {
-			const submitStartTime = Date.now();
-			const state = yield* effect.Ref.get(stateRef);
 			const transaction = decodeTransaction(payload.transaction);
-			const validation = state.document.validate(transaction);
-			if (!validation.valid) {
-				yield* effect.Metric.increment(require_Metrics.transactionsRejected);
-				const latency$1 = Date.now() - submitStartTime;
-				yield* effect.Metric.update(require_Metrics.transactionsLatency, latency$1);
-				return {
-					success: false,
-					reason: validation.reason
-				};
-			}
-			const walEntry = {
-				transaction,
-				version: validation.nextVersion,
-				timestamp: Date.now()
-			};
-			const appendResult = yield* effect.Effect.either(hotStorage.appendWithCheck(documentId, walEntry, validation.nextVersion));
-			if (appendResult._tag === "Left") {
-				yield* effect.Effect.logError("WAL append failed", {
-					documentId,
-					version: validation.nextVersion,
-					error: appendResult.left
-				});
-				yield* effect.Metric.increment(require_Metrics.walAppendFailures);
-				const latency$1 = Date.now() - submitStartTime;
-				yield* effect.Metric.update(require_Metrics.transactionsLatency, latency$1);
-				return {
-					success: false,
-					reason: "Storage unavailable. Please retry."
-				};
-			}
-			state.document.apply(transaction);
-			const latency = Date.now() - submitStartTime;
-			yield* effect.Metric.update(require_Metrics.transactionsLatency, latency);
-			yield* effect.Metric.increment(require_Metrics.transactionsProcessed);
-			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();
-			return {
-				success: true,
-				version: validation.nextVersion
-			};
+			return yield* instance.submit(transaction).pipe(effect.Effect.catchAll((error) => effect.Effect.succeed({
+				success: false,
+				reason: `Storage error: ${String(error)}`
+			})));
 		}),
 		GetSnapshot: effect.Effect.fn("cluster.document.snapshot.get")(function* () {
-			return (yield* effect.Ref.get(stateRef)).document.getSnapshot();
+			return instance.getSnapshot();
+		}),
+		Touch: effect.Effect.fn("cluster.document.touch")(function* () {
+			yield* instance.touch();
 		}),
-		Touch: effect.Effect.fn("cluster.document.touch")(function* () {}),
 		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) }));

package/dist/MimicClusterServerEngine.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"MimicClusterServerEngine.d.cts","names":[],"sources":["../src/MimicClusterServerEngine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cA27Ba;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":";;;;;;;;;;;cA8nBa;yBA3JwB,SAAA,CAAU,sBACrC,+BAA+B,aACtC,KAAA,CAAM,MACP,6BAEA,iBAAiB,gBAAgB,sBAAsB,QAAA,CAAS"}

package/dist/MimicClusterServerEngine.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"MimicClusterServerEngine.d.mts","names":[],"sources":["../src/MimicClusterServerEngine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cA27Ba;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":";;;;;;;;;;;cA8nBa;yBA3JwB,SAAA,CAAU,sBACrC,+BAA+B,aACtC,KAAA,CAAM,MACP,6BAEA,iBAAiB,gBAAgB,sBAAsB,QAAA,CAAS"}