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

package/src/HotStorage.ts

@@ -5,7 +5,7 @@
  */
 import { Context, Effect, HashMap, Layer, Ref } from "effect";
 import type { WalEntry } from "./Types";
-import { HotStorageError } from "./Errors";
+import { HotStorageError, WalVersionGapError } from "./Errors";
 
 // =============================================================================
 // HotStorage Interface
@@ -27,6 +27,32 @@ export interface HotStorage {
     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, accounting for baseVersion)
+   * 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)
+   * @param baseVersion - Optional known snapshot version. When provided, an empty WAL
+   *                      is treated as "at this version" rather than "new document at version 0".
+   *                      This is necessary after truncation or restart to correctly validate
+   *                      that the next entry is baseVersion + 1.
+   * @returns Effect that fails with WalVersionGapError if gap detected
+   */
+  readonly appendWithCheck: (
+    documentId: string,
+    entry: WalEntry,
+    expectedVersion: number,
+    baseVersion?: 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.
@@ -115,20 +141,96 @@ export namespace InMemory {
   export const make = (): Layer.Layer<HotStorageTag> =>
     Layer.effect(
       HotStorageTag,
-      Effect.gen(function* () {
+      Effect.fn("hot-storage.in-memory.create")(function* () {
         const store = yield* Ref.make(HashMap.empty<string, WalEntry[]>());
 
         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: string, entry: WalEntry) {
+              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]);
+              });
+            }
+          ),
+
+          appendWithCheck: Effect.fn("hot-storage.append-with-check")(
+            function* (
+              documentId: string,
+              entry: WalEntry,
+              expectedVersion: number,
+              baseVersion?: number
+            ) {
+              type CheckResult =
+                | { type: "ok" }
+                | { type: "gap"; lastVersion: number | undefined };
+
+              // Use Ref.modify for atomic check + update
+              const result: CheckResult = yield* Ref.modify(
+                store,
+                (map): [CheckResult, HashMap.HashMap<string, WalEntry[]>] => {
+                  const existing = HashMap.get(map, documentId);
+                  const entries =
+                    existing._tag === "Some" ? existing.value : [];
+
+                  // Find the highest version in existing entries
+                  const lastEntryVersion =
+                    entries.length > 0
+                      ? Math.max(...entries.map((e) => e.version))
+                      : 0;
 
-          getEntries: (documentId, sinceVersion) =>
-            Effect.gen(function* () {
+                  // Effective "last version" is max of entries and baseVersion
+                  // This handles the case after truncation or restart where
+                  // WAL is empty but we know the snapshot version
+                  const effectiveLastVersion =
+                    baseVersion !== undefined
+                      ? Math.max(lastEntryVersion, baseVersion)
+                      : lastEntryVersion;
+
+                  // Gap check
+                  if (expectedVersion === 1) {
+                    // First entry: should have no entries with version >= 1
+                    // and baseVersion should be 0 or undefined
+                    if (effectiveLastVersion >= 1) {
+                      return [{ type: "gap", lastVersion: effectiveLastVersion }, map];
+                    }
+                  } else {
+                    // Not first: effective last version should be expectedVersion - 1
+                    if (effectiveLastVersion !== expectedVersion - 1) {
+                      return [
+                        {
+                          type: "gap",
+                          lastVersion: effectiveLastVersion > 0 ? effectiveLastVersion : undefined,
+                        },
+                        map,
+                      ];
+                    }
+                  }
+
+                  // No gap: append and return success
+                  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: string, sinceVersion: number) {
               const current = yield* Ref.get(store);
               const existing = HashMap.get(current, documentId);
               const entries =
@@ -136,21 +238,25 @@ export namespace InMemory {
               return entries
                 .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: string, upToVersion: number) {
+              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);
+              });
+            }
+          ),
         };
-      })
+      })()
     );
 }
 

package/src/Metrics.ts

@@ -99,6 +99,11 @@ export const transactionsLatency = Metric.histogram(
  */
 export const storageSnapshots = Metric.counter("mimic.storage.snapshots");
 
+/**
+ * Snapshots triggered by idle document detection
+ */
+export const storageIdleSnapshots = Metric.counter("mimic.storage.idle_snapshots");
+
 /**
  * Snapshot save duration histogram (milliseconds)
  */
@@ -116,6 +121,26 @@ export const storageSnapshotLatency = Metric.histogram(
  */
 export const storageWalAppends = Metric.counter("mimic.storage.wal_appends");
 
+/**
+ * Version gaps detected during WAL replay
+ */
+export const storageVersionGaps = Metric.counter("mimic.storage.version_gaps");
+
+/**
+ * Failed WAL appends causing transaction rollback
+ */
+export const walAppendFailures = Metric.counter("mimic.storage.wal_append_failures");
+
+/**
+ * ColdStorage load failures during document restore
+ */
+export const coldStorageLoadFailures = Metric.counter("mimic.storage.cold_load_failures");
+
+/**
+ * HotStorage getEntries failures during document restore
+ */
+export const hotStorageLoadFailures = Metric.counter("mimic.storage.hot_load_failures");
+
 // =============================================================================
 // Presence Metrics
 // =============================================================================
@@ -154,8 +179,13 @@ export const MimicMetrics = {
 
   // Storage
   storageSnapshots,
+  storageIdleSnapshots,
   storageSnapshotLatency,
   storageWalAppends,
+  storageVersionGaps,
+  walAppendFailures,
+  coldStorageLoadFailures,
+  hotStorageLoadFailures,
 
   // Presence
   presenceUpdates,