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

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  /** Check if document has unsnapshot transactions that need persisting */\n  readonly needsSnapshot: () => Effect.Effect<boolean>;\n  /** Get the last activity timestamp for idle detection */\n  readonly getLastActivityTime: () => Effect.Effect<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    const needsSnapshot = () =>\n      Effect.map(Ref.get(transactionsSinceSnapshotRef), (n) => n > 0);\n\n    const getLastActivityTime = () => Ref.get(lastActivityTimeRef);\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      needsSnapshot,\n      getLastActivityTime,\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/Errors.cjs

@@ -15,6 +15,14 @@ var ColdStorageError = class extends effect.Data.TaggedError("ColdStorageError")
 */
 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") {};
@@ -42,4 +50,5 @@ exports.ColdStorageError = ColdStorageError;
 exports.HotStorageError = HotStorageError;
 exports.MessageParseError = MessageParseError;
 exports.MissingDocumentIdError = MissingDocumentIdError;
-exports.TransactionRejectedError = TransactionRejectedError;
+exports.TransactionRejectedError = TransactionRejectedError;
+exports.WalVersionGapError = WalVersionGapError;

package/dist/Errors.d.cts

@@ -21,9 +21,24 @@ declare const HotStorageError_base: new <A extends Record<string, any> = {}>(arg
  */
 declare class HotStorageError extends HotStorageError_base<{
   readonly documentId: string;
-  readonly operation: "append" | "getEntries" | "truncate";
+  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>;
@@ -75,7 +90,7 @@ declare class TransactionRejectedError extends TransactionRejectedError_base<{
 /**
  * Union of all mimic-effect errors
  */
-type MimicError = ColdStorageError | HotStorageError | AuthenticationError | AuthorizationError | MissingDocumentIdError | MessageParseError | TransactionRejectedError;
+type MimicError = ColdStorageError | HotStorageError | WalVersionGapError | AuthenticationError | AuthorizationError | MissingDocumentIdError | MessageParseError | TransactionRejectedError;
 //#endregion
-export { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MimicError, MissingDocumentIdError, TransactionRejectedError };
+export { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MimicError, MissingDocumentIdError, TransactionRejectedError, WalVersionGapError };
 //# sourceMappingURL=Errors.d.cts.map

package/dist/Errors.d.cts.map

@@ -1 +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;;;;;;cASQ,mBAAA,SAA4B;EAb5B,SAAA,MAAA,EAAA,MAAgB;AAIxB,CAAA,CAAA,CAAA;cAaA;;;;;;cAKQ,kBAAA,SAA2B;;;;;AALnC,cASA,2BATA,EAAA,IAAA,CAAA,gBAAA,CAAA,MAAA,EAAA,GAAA,CAAA,GAAA,CAAA,CAAA,CAAA,CAAA,IAAA,sBAAA,EAAA,EAAA,CAAA,CAAA,CAAA,SAAA,IAAA,GAAA,IAAA,GAAA,iBAAA,OAAA,KAAA,SAAA,MAAA,GAAA,KAAA,IAAA,IAAA,EAAA,CAAA,EAAA,EAAA,kCAAA;;;;;;cAkBQ,sBAAA,SAA+B;;;cAIvC;;;AAjBL;AAIK;;cAkBQ,iBAAA,SAA0B;;;cAElC;;;;;;cASQ,wBAAA,SAAiC;EApBjC,SAAA,aAAA,EAAA,MAAuB;EAI/B,SAAA,MAAA,EAAA,MAAA;;;;;KA8BO,UAAA,GACR,mBACA,kBACA,sBACA,qBACA,yBACA,oBACA"}
+{"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"}

package/dist/Errors.d.mts

@@ -21,9 +21,24 @@ declare const HotStorageError_base: new <A extends Record<string, any> = {}>(arg
  */
 declare class HotStorageError extends HotStorageError_base<{
   readonly documentId: string;
-  readonly operation: "append" | "getEntries" | "truncate";
+  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>;
@@ -75,7 +90,7 @@ declare class TransactionRejectedError extends TransactionRejectedError_base<{
 /**
  * Union of all mimic-effect errors
  */
-type MimicError = ColdStorageError | HotStorageError | AuthenticationError | AuthorizationError | MissingDocumentIdError | MessageParseError | TransactionRejectedError;
+type MimicError = ColdStorageError | HotStorageError | WalVersionGapError | AuthenticationError | AuthorizationError | MissingDocumentIdError | MessageParseError | TransactionRejectedError;
 //#endregion
-export { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MimicError, MissingDocumentIdError, TransactionRejectedError };
+export { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MimicError, MissingDocumentIdError, TransactionRejectedError, WalVersionGapError };
 //# sourceMappingURL=Errors.d.mts.map

package/dist/Errors.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"Errors.d.mts","names":[],"sources":["../src/Errors.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;cAca,gBAAA,SAAyB;;;;;cAIjC;;;;;AAJL;AAIK,cAKQ,eAAA,SAAwB,oBALhC,CAAA;;;;;cASA;;;;;;cASQ,mBAAA,SAA4B;EAb5B,SAAA,MAAA,EAAA,MAAgB;AAIxB,CAAA,CAAA,CAAA;cAaA;;;;;;cAKQ,kBAAA,SAA2B;;;;;AALnC,cASA,2BATA,EAAA,IAAA,CAAA,gBAAA,CAAA,MAAA,EAAA,GAAA,CAAA,GAAA,CAAA,CAAA,CAAA,CAAA,IAAA,sBAAA,EAAA,EAAA,CAAA,CAAA,CAAA,SAAA,IAAA,GAAA,IAAA,GAAA,iBAAA,OAAA,KAAA,SAAA,MAAA,GAAA,KAAA,IAAA,IAAA,EAAA,CAAA,EAAA,EAAA,kCAAA;;;;;;cAkBQ,sBAAA,SAA+B;;;cAIvC;;;AAjBL;AAIK;;cAkBQ,iBAAA,SAA0B;;;cAElC;;;;;;cASQ,wBAAA,SAAiC;EApBjC,SAAA,aAAA,EAAA,MAAuB;EAI/B,SAAA,MAAA,EAAA,MAAA;;;;;KA8BO,UAAA,GACR,mBACA,kBACA,sBACA,qBACA,yBACA,oBACA"}
+{"version":3,"file":"Errors.d.mts","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"}

package/dist/Errors.mjs

@@ -15,6 +15,14 @@ var ColdStorageError = class extends Data.TaggedError("ColdStorageError") {};
 */
 var HotStorageError = class extends 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 Data.TaggedError("WalVersionGapError") {};
+/**
 * Error when authentication fails (invalid token, expired, etc.)
 */
 var AuthenticationError = class extends Data.TaggedError("AuthenticationError") {};
@@ -36,5 +44,5 @@ var MessageParseError = class extends Data.TaggedError("MessageParseError") {};
 var TransactionRejectedError = class extends Data.TaggedError("TransactionRejectedError") {};
 
 //#endregion
-export { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MissingDocumentIdError, TransactionRejectedError };
+export { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MissingDocumentIdError, TransactionRejectedError, WalVersionGapError };
 //# sourceMappingURL=Errors.mjs.map

package/dist/Errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Errors.mjs","names":[],"sources":["../src/Errors.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - Error Types\n *\n * All error types used throughout the mimic-effect package.\n */\nimport { Data } from \"effect\";\n\n// =============================================================================\n// Storage Errors\n// =============================================================================\n\n/**\n * Error when ColdStorage (snapshot storage) operations fail\n */\nexport class ColdStorageError extends Data.TaggedError(\"ColdStorageError\")<{\n  readonly documentId: string;\n  readonly operation: \"load\" | \"save\" | \"delete\";\n  readonly cause: unknown;\n}> {}\n\n/**\n * Error when HotStorage (WAL storage) operations fail\n */\nexport class HotStorageError extends Data.TaggedError(\"HotStorageError\")<{\n  readonly documentId: string;\n  readonly operation: \"append\" | \"getEntries\" | \"truncate\";\n  readonly cause: unknown;\n}> {}\n\n// =============================================================================\n// Auth Errors\n// =============================================================================\n\n/**\n * Error when authentication fails (invalid token, expired, etc.)\n */\nexport class AuthenticationError extends Data.TaggedError(\n  \"AuthenticationError\"\n)<{\n  readonly reason: string;\n}> {}\n\n/**\n * Error when authorization fails (user doesn't have required permission)\n */\nexport class AuthorizationError extends Data.TaggedError(\"AuthorizationError\")<{\n  readonly reason: string;\n  readonly required: \"read\" | \"write\";\n  readonly actual: \"read\" | \"write\";\n}> {}\n\n// =============================================================================\n// Connection Errors\n// =============================================================================\n\n/**\n * Error when document ID is missing from WebSocket request path\n */\nexport class MissingDocumentIdError extends Data.TaggedError(\n  \"MissingDocumentIdError\"\n)<{\n  readonly path: string;\n}> {}\n\n/**\n * Error when WebSocket message cannot be parsed\n */\nexport class MessageParseError extends Data.TaggedError(\"MessageParseError\")<{\n  readonly cause: unknown;\n}> {}\n\n// =============================================================================\n// Transaction Errors\n// =============================================================================\n\n/**\n * Error when a transaction is rejected by the document\n */\nexport class TransactionRejectedError extends Data.TaggedError(\n  \"TransactionRejectedError\"\n)<{\n  readonly transactionId: string;\n  readonly reason: string;\n}> {}\n\n// =============================================================================\n// Union Type\n// =============================================================================\n\n/**\n * Union of all mimic-effect errors\n */\nexport type MimicError =\n  | ColdStorageError\n  | HotStorageError\n  | AuthenticationError\n  | AuthorizationError\n  | MissingDocumentIdError\n  | MessageParseError\n  | TransactionRejectedError;\n"],"mappings":";;;;;;;;;;;AAcA,IAAa,mBAAb,cAAsC,KAAK,YAAY,mBAAmB,CAIvE;;;;AAKH,IAAa,kBAAb,cAAqC,KAAK,YAAY,kBAAkB,CAIrE;;;;AASH,IAAa,sBAAb,cAAyC,KAAK,YAC5C,sBACD,CAEE;;;;AAKH,IAAa,qBAAb,cAAwC,KAAK,YAAY,qBAAqB,CAI3E;;;;AASH,IAAa,yBAAb,cAA4C,KAAK,YAC/C,yBACD,CAEE;;;;AAKH,IAAa,oBAAb,cAAuC,KAAK,YAAY,oBAAoB,CAEzE;;;;AASH,IAAa,2BAAb,cAA8C,KAAK,YACjD,2BACD,CAGE"}
+{"version":3,"file":"Errors.mjs","names":[],"sources":["../src/Errors.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - Error Types\n *\n * All error types used throughout the mimic-effect package.\n */\nimport { Data } from \"effect\";\n\n// =============================================================================\n// Storage Errors\n// =============================================================================\n\n/**\n * Error when ColdStorage (snapshot storage) operations fail\n */\nexport class ColdStorageError extends Data.TaggedError(\"ColdStorageError\")<{\n  readonly documentId: string;\n  readonly operation: \"load\" | \"save\" | \"delete\";\n  readonly cause: unknown;\n}> {}\n\n/**\n * Error when HotStorage (WAL storage) operations fail\n */\nexport class HotStorageError extends Data.TaggedError(\"HotStorageError\")<{\n  readonly documentId: string;\n  readonly operation: \"append\" | \"getEntries\" | \"truncate\" | \"appendWithCheck\";\n  readonly cause: unknown;\n}> {}\n\n/**\n * Error when WAL append detects a version gap.\n * This indicates either:\n * - A bug in the application (skipped a version)\n * - Concurrent writes to the same document\n * - Data corruption in WAL storage\n */\nexport class WalVersionGapError extends Data.TaggedError(\"WalVersionGapError\")<{\n  readonly documentId: string;\n  readonly expectedVersion: number;\n  readonly actualPreviousVersion: number | undefined;\n}> {}\n\n// =============================================================================\n// Auth Errors\n// =============================================================================\n\n/**\n * Error when authentication fails (invalid token, expired, etc.)\n */\nexport class AuthenticationError extends Data.TaggedError(\n  \"AuthenticationError\"\n)<{\n  readonly reason: string;\n}> {}\n\n/**\n * Error when authorization fails (user doesn't have required permission)\n */\nexport class AuthorizationError extends Data.TaggedError(\"AuthorizationError\")<{\n  readonly reason: string;\n  readonly required: \"read\" | \"write\";\n  readonly actual: \"read\" | \"write\";\n}> {}\n\n// =============================================================================\n// Connection Errors\n// =============================================================================\n\n/**\n * Error when document ID is missing from WebSocket request path\n */\nexport class MissingDocumentIdError extends Data.TaggedError(\n  \"MissingDocumentIdError\"\n)<{\n  readonly path: string;\n}> {}\n\n/**\n * Error when WebSocket message cannot be parsed\n */\nexport class MessageParseError extends Data.TaggedError(\"MessageParseError\")<{\n  readonly cause: unknown;\n}> {}\n\n// =============================================================================\n// Transaction Errors\n// =============================================================================\n\n/**\n * Error when a transaction is rejected by the document\n */\nexport class TransactionRejectedError extends Data.TaggedError(\n  \"TransactionRejectedError\"\n)<{\n  readonly transactionId: string;\n  readonly reason: string;\n}> {}\n\n// =============================================================================\n// Union Type\n// =============================================================================\n\n/**\n * Union of all mimic-effect errors\n */\nexport type MimicError =\n  | ColdStorageError\n  | HotStorageError\n  | WalVersionGapError\n  | AuthenticationError\n  | AuthorizationError\n  | MissingDocumentIdError\n  | MessageParseError\n  | TransactionRejectedError;\n"],"mappings":";;;;;;;;;;;AAcA,IAAa,mBAAb,cAAsC,KAAK,YAAY,mBAAmB,CAIvE;;;;AAKH,IAAa,kBAAb,cAAqC,KAAK,YAAY,kBAAkB,CAIrE;;;;;;;;AASH,IAAa,qBAAb,cAAwC,KAAK,YAAY,qBAAqB,CAI3E;;;;AASH,IAAa,sBAAb,cAAyC,KAAK,YAC5C,sBACD,CAEE;;;;AAKH,IAAa,qBAAb,cAAwC,KAAK,YAAY,qBAAqB,CAI3E;;;;AASH,IAAa,yBAAb,cAA4C,KAAK,YAC/C,yBACD,CAEE;;;;AAKH,IAAa,oBAAb,cAAuC,KAAK,YAAY,oBAAoB,CAEzE;;;;AASH,IAAa,2BAAb,cAA8C,KAAK,YACjD,2BACD,CAGE"}

package/dist/HotStorage.cjs

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

package/dist/HotStorage.d.cts

@@ -1,5 +1,5 @@
 import { WalEntry } from "./Types.cjs";
-import { HotStorageError } from "./Errors.cjs";
+import { HotStorageError, WalVersionGapError } from "./Errors.cjs";
 import { Context, Effect, Layer } from "effect";
 
 //#region src/HotStorage.d.ts
@@ -16,6 +16,22 @@ interface HotStorage {
    * Append a WAL entry for a document.
    */
   readonly append: (documentId: string, entry: WalEntry) => Effect.Effect<void, HotStorageError>;
+  /**
+   * Append a WAL entry with version gap checking.
+   *
+   * This is an atomic operation that:
+   * 1. Verifies the previous entry has version = expectedVersion - 1
+   *    (or this is the first entry if expectedVersion === 1)
+   * 2. Appends the entry if check passes
+   *
+   * Use this for two-phase commit to guarantee WAL ordering at write time.
+   *
+   * @param documentId - Document ID
+   * @param entry - WAL entry to append
+   * @param expectedVersion - The version this entry should have (entry.version)
+   * @returns Effect that fails with WalVersionGapError if gap detected
+   */
+  readonly appendWithCheck: (documentId: string, entry: WalEntry, expectedVersion: number) => Effect.Effect<void, HotStorageError | WalVersionGapError>;
   /**
    * Get all WAL entries for a document since a given version.
    * Returns entries with version > sinceVersion, ordered by version.

package/dist/HotStorage.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"HotStorage.d.cts","names":[],"sources":["../src/HotStorage.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AA8CC,UA1BgB,UAAA,CA0BhB;;;;+CApBU,aACJ,MAAA,CAAO,aAAa;EA4Bd;AAuDb;AAkDA;;EAhEwB,SAAA,UAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,YAAA,EAAA,MAAA,EAAA,GA5DjB,MAAA,CAAO,MA4DU,CA5DH,QA4DG,EAAA,EA5DS,eA4DT,CAAA;EAAY;;;;EACN,SAAA,QAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,WAAA,EAAA,MAAA,EAAA,GApDvB,MAAA,CAAO,MAoDgB,CAAA,IAAA,EApDH,eAoDG,CAAA;;cAnD7B,kBAmDQ,kBAAA,cAAA,EAAA,mCAAA,YAAA,CAAA;;;;cA1CI,aAAA,SAAsB,kBAAA;;;;;;;kBAuDlB,QAAA;;;;oBAIS,KAAA,CAAM,MAAM;;cA8CzB;;uBAhEH,MAAA,CAAO,OAAO,YAAY,GAAG,OACpC,KAAA,CAAM,MAAM,eAAe,GAAG"}
+{"version":3,"file":"HotStorage.d.cts","names":[],"sources":["../src/HotStorage.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAyDO,UArCU,UAAA,CAqCH;EASa;;;EAC1B,SAAA,MAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,KAAA,EAzCU,QAyCV,EAAA,GAxCM,MAAA,CAAO,MAwCb,CAAA,IAAA,EAxC0B,eAwC1B,CAAA;;;;;AASD;AAuDA;AAwHA;;;;;;;;;EArIG,SAAM,eAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,KAAA,EAxEE,QAwEF,EAAA,eAAA,EAAA,MAAA,EAAA,GAtEF,MAAA,CAAO,MAsEL,CAAA,IAAA,EAtEkB,eAsElB,GAtEoC,kBAsEpC,CAAA;;;;;qEA7DF,MAAA,CAAO,OAAO,YAAY;;;;;kEAS1B,MAAA,CAAO,aAAa;;cAC1B;;;;cASY,aAAA,SAAsB,kBAAA;;;;;;;kBAuDlB,QAAA;;;;oBAIS,KAAA,CAAM,MAAM;;cAoHzB;;uBAtIH,MAAA,CAAO,OAAO,YAAY,GAAG,OACpC,KAAA,CAAM,MAAM,eAAe,GAAG"}

package/dist/HotStorage.d.mts

@@ -1,5 +1,5 @@
 import { WalEntry } from "./Types.mjs";
-import { HotStorageError } from "./Errors.mjs";
+import { HotStorageError, WalVersionGapError } from "./Errors.mjs";
 import { Context, Effect, Layer } from "effect";
 
 //#region src/HotStorage.d.ts
@@ -16,6 +16,22 @@ interface HotStorage {
    * Append a WAL entry for a document.
    */
   readonly append: (documentId: string, entry: WalEntry) => Effect.Effect<void, HotStorageError>;
+  /**
+   * Append a WAL entry with version gap checking.
+   *
+   * This is an atomic operation that:
+   * 1. Verifies the previous entry has version = expectedVersion - 1
+   *    (or this is the first entry if expectedVersion === 1)
+   * 2. Appends the entry if check passes
+   *
+   * Use this for two-phase commit to guarantee WAL ordering at write time.
+   *
+   * @param documentId - Document ID
+   * @param entry - WAL entry to append
+   * @param expectedVersion - The version this entry should have (entry.version)
+   * @returns Effect that fails with WalVersionGapError if gap detected
+   */
+  readonly appendWithCheck: (documentId: string, entry: WalEntry, expectedVersion: number) => Effect.Effect<void, HotStorageError | WalVersionGapError>;
   /**
    * Get all WAL entries for a document since a given version.
    * Returns entries with version > sinceVersion, ordered by version.

package/dist/HotStorage.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"HotStorage.d.mts","names":[],"sources":["../src/HotStorage.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AA8CC,UA1BgB,UAAA,CA0BhB;;;;+CApBU,aACJ,MAAA,CAAO,aAAa;EA4Bd;AAuDb;AAkDA;;EAhEwB,SAAA,UAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,YAAA,EAAA,MAAA,EAAA,GA5DjB,MAAA,CAAO,MA4DU,CA5DH,QA4DG,EAAA,EA5DS,eA4DT,CAAA;EAAY;;;;EACN,SAAA,QAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,WAAA,EAAA,MAAA,EAAA,GApDvB,MAAA,CAAO,MAoDgB,CAAA,IAAA,EApDH,eAoDG,CAAA;;cAnD7B,kBAmDQ,kBAAA,cAAA,EAAA,mCAAA,YAAA,CAAA;;;;cA1CI,aAAA,SAAsB,kBAAA;;;;;;;kBAuDlB,QAAA;;;;oBAIS,KAAA,CAAM,MAAM;;cA8CzB;;uBAhEH,MAAA,CAAO,OAAO,YAAY,GAAG,OACpC,KAAA,CAAM,MAAM,eAAe,GAAG"}
+{"version":3,"file":"HotStorage.d.mts","names":[],"sources":["../src/HotStorage.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAyDO,UArCU,UAAA,CAqCH;EASa;;;EAC1B,SAAA,MAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,KAAA,EAzCU,QAyCV,EAAA,GAxCM,MAAA,CAAO,MAwCb,CAAA,IAAA,EAxC0B,eAwC1B,CAAA;;;;;AASD;AAuDA;AAwHA;;;;;;;;;EArIG,SAAM,eAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,KAAA,EAxEE,QAwEF,EAAA,eAAA,EAAA,MAAA,EAAA,GAtEF,MAAA,CAAO,MAsEL,CAAA,IAAA,EAtEkB,eAsElB,GAtEoC,kBAsEpC,CAAA;;;;;qEA7DF,MAAA,CAAO,OAAO,YAAY;;;;;kEAS1B,MAAA,CAAO,aAAa;;cAC1B;;;;cASY,aAAA,SAAsB,kBAAA;;;;;;;kBAuDlB,QAAA;;;;oBAIS,KAAA,CAAM,MAAM;;cAoHzB;;uBAtIH,MAAA,CAAO,OAAO,YAAY,GAAG,OACpC,KAAA,CAAM,MAAM,eAAe,GAAG"}

package/dist/HotStorage.mjs

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

package/dist/HotStorage.mjs.map

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

package/dist/Metrics.cjs

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

package/dist/Metrics.d.cts

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

package/dist/Metrics.d.cts.map

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

package/dist/Metrics.d.mts

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

package/dist/Metrics.d.mts.map

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