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

package/dist/MimicServerEngine.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"MimicServerEngine.mjs","names":["documentManagerLayer","presenceManagerLayer"],"sources":["../src/MimicServerEngine.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - MimicServerEngine\n *\n * Core document management service for Mimic real-time collaboration.\n * Handles document lifecycle, storage, presence, and transaction processing.\n *\n * This is the engine layer - for WebSocket routes, use MimicServer.layerHttpLayerRouter().\n */\nimport {\n  Context,\n  Duration,\n  Effect,\n  Layer,\n  Scope,\n  Stream,\n} from \"effect\";\nimport type { Presence, Primitive, Transaction } from \"@voidhash/mimic\";\nimport type {\n  MimicServerEngineConfig,\n  PresenceEntry,\n  PresenceEvent,\n  PresenceSnapshot,\n  ResolvedConfig,\n} from \"./Types\";\nimport type * as Protocol from \"./Protocol\";\nimport { ColdStorageTag } from \"./ColdStorage\";\nimport { HotStorageTag } from \"./HotStorage\";\nimport { MimicAuthServiceTag } from \"./MimicAuthService\";\nimport {\n  DocumentManagerTag,\n  DocumentManagerConfigTag,\n  layer as documentManagerLayer,\n  type SubmitResult,\n} from \"./DocumentManager\";\nimport {\n  PresenceManagerTag,\n  layer as presenceManagerLayer,\n} from \"./PresenceManager\";\n\n// =============================================================================\n// MimicServerEngine Interface\n// =============================================================================\n\n/**\n * MimicServerEngine service interface.\n *\n * Provides document management operations for Mimic collaboration.\n * Use MimicServer.layerHttpLayerRouter() to create WebSocket routes.\n */\nexport interface MimicServerEngine {\n  /**\n   * Submit a transaction to a document.\n   * Authorization is checked against the auth service.\n   */\n  readonly submit: (\n    documentId: string,\n    transaction: Transaction.Transaction\n  ) => Effect.Effect<SubmitResult, never>;\n\n  /**\n   * Get document snapshot (current state and version).\n   */\n  readonly getSnapshot: (\n    documentId: string\n  ) => Effect.Effect<{ state: unknown; version: number }, never>;\n\n  /**\n   * Subscribe to document broadcasts (transactions).\n   * Returns a stream of server messages.\n   * Requires a Scope for cleanup when the subscription ends.\n   */\n  readonly subscribe: (\n    documentId: string\n  ) => Effect.Effect<Stream.Stream<Protocol.ServerMessage, never, never>, never, Scope.Scope>;\n\n  /**\n   * Touch document to prevent idle garbage collection.\n   */\n  readonly touch: (documentId: string) => Effect.Effect<void, never>;\n\n  /**\n   * Get presence snapshot for a document.\n   */\n  readonly getPresenceSnapshot: (\n    documentId: string\n  ) => Effect.Effect<PresenceSnapshot, never>;\n\n  /**\n   * Set presence for a connection.\n   */\n  readonly setPresence: (\n    documentId: string,\n    connectionId: string,\n    entry: PresenceEntry\n  ) => Effect.Effect<void, never>;\n\n  /**\n   * Remove presence for a connection.\n   */\n  readonly removePresence: (\n    documentId: string,\n    connectionId: string\n  ) => Effect.Effect<void, never>;\n\n  /**\n   * Subscribe to presence events for a document.\n   * Requires a Scope for cleanup when the subscription ends.\n   */\n  readonly subscribePresence: (\n    documentId: string\n  ) => Effect.Effect<Stream.Stream<PresenceEvent, never, never>, never, Scope.Scope>;\n\n  /**\n   * Resolved engine configuration.\n   * Used by route layer to access schema, presence config, etc.\n   */\n  readonly config: ResolvedConfig<Primitive.AnyPrimitive>;\n}\n\n// =============================================================================\n// Context Tag\n// =============================================================================\n\n/**\n * Context tag for MimicServerEngine\n */\nexport class MimicServerEngineTag extends Context.Tag(\n  \"@voidhash/mimic-effect/MimicServerEngine\"\n)<MimicServerEngineTag, MimicServerEngine>() {}\n\n// =============================================================================\n// Default Configuration\n// =============================================================================\n\nconst DEFAULT_MAX_IDLE_TIME = Duration.minutes(5);\nconst DEFAULT_MAX_TRANSACTION_HISTORY = 1000;\nconst DEFAULT_SNAPSHOT_INTERVAL = Duration.minutes(5);\nconst DEFAULT_SNAPSHOT_THRESHOLD = 100;\n\n/**\n * Resolve configuration with defaults\n */\nconst resolveConfig = <TSchema extends Primitive.AnyPrimitive>(\n  config: MimicServerEngineConfig<TSchema>\n): ResolvedConfig<TSchema> => ({\n  schema: config.schema,\n  initial: config.initial,\n  presence: config.presence,\n  maxIdleTime: config.maxIdleTime\n    ? Duration.decode(config.maxIdleTime)\n    : DEFAULT_MAX_IDLE_TIME,\n  maxTransactionHistory:\n    config.maxTransactionHistory ?? DEFAULT_MAX_TRANSACTION_HISTORY,\n  snapshot: {\n    interval: config.snapshot?.interval\n      ? Duration.decode(config.snapshot.interval)\n      : DEFAULT_SNAPSHOT_INTERVAL,\n    transactionThreshold:\n      config.snapshot?.transactionThreshold ?? DEFAULT_SNAPSHOT_THRESHOLD,\n  },\n});\n\n// =============================================================================\n// Factory\n// =============================================================================\n\n/**\n * Create a MimicServerEngine layer.\n *\n * This creates the core document management service. To expose it via WebSocket,\n * use MimicServer.layerHttpLayerRouter().\n *\n * @example\n * ```typescript\n * // 1. Create the engine\n * const Engine = MimicServerEngine.make({\n *   schema: DocSchema,\n *   initial: { title: \"Untitled\" },\n *   presence: CursorPresence,\n *   maxIdleTime: \"5 minutes\",\n *   snapshot: { interval: \"5 minutes\", transactionThreshold: 100 },\n * })\n *\n * // 2. Create the WebSocket route\n * const MimicRoute = MimicServer.layerHttpLayerRouter({\n *   path: \"/mimic\",\n * })\n *\n * // 3. Wire together\n * const MimicLive = MimicRoute.pipe(\n *   Layer.provide(Engine),\n *   Layer.provide(ColdStorage.InMemory.make()),\n *   Layer.provide(HotStorage.InMemory.make()),\n *   Layer.provide(MimicAuthService.NoAuth.make()),\n * )\n * ```\n */\nexport const make = <TSchema extends Primitive.AnyPrimitive>(\n  config: MimicServerEngineConfig<TSchema>\n): Layer.Layer<\n  MimicServerEngineTag,\n  never,\n  ColdStorageTag | HotStorageTag | MimicAuthServiceTag\n> => {\n  const resolvedConfig = resolveConfig(config);\n\n  // Create config layer for DocumentManager\n  const configLayer = Layer.succeed(\n    DocumentManagerConfigTag,\n    resolvedConfig as ResolvedConfig<Primitive.AnyPrimitive>\n  );\n\n  // Create internal layers\n  const internalLayers = Layer.mergeAll(\n    documentManagerLayer.pipe(Layer.provide(configLayer)),\n    presenceManagerLayer\n  );\n\n  return Layer.scoped(\n    MimicServerEngineTag,\n    Effect.gen(function* () {\n      const documentManager = yield* DocumentManagerTag;\n      const presenceManager = yield* PresenceManagerTag;\n\n      const engine: MimicServerEngine = {\n        submit: (documentId, transaction) =>\n          documentManager.submit(documentId, transaction),\n\n        getSnapshot: (documentId) => documentManager.getSnapshot(documentId),\n\n        subscribe: (documentId) =>\n          documentManager.subscribe(documentId) as Effect.Effect<\n            Stream.Stream<Protocol.ServerMessage, never, never>,\n            never\n          >,\n\n        touch: (documentId) => documentManager.touch(documentId),\n\n        getPresenceSnapshot: (documentId) =>\n          presenceManager.getSnapshot(documentId),\n\n        setPresence: (documentId, connectionId, entry) =>\n          presenceManager.set(documentId, connectionId, entry),\n\n        removePresence: (documentId, connectionId) =>\n          presenceManager.remove(documentId, connectionId),\n\n        subscribePresence: (documentId) =>\n          presenceManager.subscribe(documentId),\n\n        config: resolvedConfig as ResolvedConfig<Primitive.AnyPrimitive>,\n      };\n\n      return engine;\n    })\n  ).pipe(Layer.provide(internalLayers));\n};\n\n// =============================================================================\n// Re-export namespace\n// =============================================================================\n\nexport const MimicServerEngine = {\n  Tag: MimicServerEngineTag,\n  make,\n};\n\n// =============================================================================\n// Re-export SubmitResult type\n// =============================================================================\n\nexport type { SubmitResult };\n"],"mappings":";;;;;;;;;;;;;;;;AA8HA,IAAa,uBAAb,cAA0C,QAAQ,IAChD,2CACD,EAA2C,CAAC;AAM7C,MAAM,wBAAwB,SAAS,QAAQ,EAAE;AACjD,MAAM,kCAAkC;AACxC,MAAM,4BAA4B,SAAS,QAAQ,EAAE;AACrD,MAAM,6BAA6B;;;;AAKnC,MAAM,iBACJ,WAC4B;;QAAC;EAC7B,QAAQ,OAAO;EACf,SAAS,OAAO;EAChB,UAAU,OAAO;EACjB,aAAa,OAAO,cAChB,SAAS,OAAO,OAAO,YAAY,GACnC;EACJ,gDACE,OAAO,8FAAyB;EAClC,UAAU;GACR,+BAAU,OAAO,8EAAU,YACvB,SAAS,OAAO,OAAO,SAAS,SAAS,GACzC;GACJ,oEACE,OAAO,gFAAU,6FAAwB;GAC5C;EACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCD,MAAa,QACX,WAKG;CACH,MAAM,iBAAiB,cAAc,OAAO;CAG5C,MAAM,cAAc,MAAM,QACxB,0BACA,eACD;CAGD,MAAM,iBAAiB,MAAM,SAC3BA,MAAqB,KAAK,MAAM,QAAQ,YAAY,CAAC,EACrDC,QACD;AAED,QAAO,MAAM,OACX,sBACA,OAAO,IAAI,aAAa;EACtB,MAAM,kBAAkB,OAAO;EAC/B,MAAM,kBAAkB,OAAO;AA+B/B,SA7BkC;GAChC,SAAS,YAAY,gBACnB,gBAAgB,OAAO,YAAY,YAAY;GAEjD,cAAc,eAAe,gBAAgB,YAAY,WAAW;GAEpE,YAAY,eACV,gBAAgB,UAAU,WAAW;GAKvC,QAAQ,eAAe,gBAAgB,MAAM,WAAW;GAExD,sBAAsB,eACpB,gBAAgB,YAAY,WAAW;GAEzC,cAAc,YAAY,cAAc,UACtC,gBAAgB,IAAI,YAAY,cAAc,MAAM;GAEtD,iBAAiB,YAAY,iBAC3B,gBAAgB,OAAO,YAAY,aAAa;GAElD,oBAAoB,eAClB,gBAAgB,UAAU,WAAW;GAEvC,QAAQ;GACT;GAGD,CACH,CAAC,KAAK,MAAM,QAAQ,eAAe,CAAC;;AAOvC,MAAa,oBAAoB;CAC/B,KAAK;CACL;CACD"}
+{"version":3,"file":"MimicServerEngine.mjs","names":["documentManagerLayer","presenceManagerLayer"],"sources":["../src/MimicServerEngine.ts"],"sourcesContent":["/**\n * @voidhash/mimic-effect - MimicServerEngine\n *\n * Core document management service for Mimic real-time collaboration.\n * Handles document lifecycle, storage, presence, and transaction processing.\n *\n * This is the engine layer - for WebSocket routes, use MimicServer.layerHttpLayerRouter().\n */\nimport {\n  Context,\n  Duration,\n  Effect,\n  Layer,\n  Scope,\n  Stream,\n} from \"effect\";\nimport type { Presence, Primitive, Transaction } from \"@voidhash/mimic\";\nimport type {\n  MimicServerEngineConfig,\n  PresenceEntry,\n  PresenceEvent,\n  PresenceSnapshot,\n  ResolvedConfig,\n} from \"./Types\";\nimport type * as Protocol from \"./Protocol\";\nimport { ColdStorageTag } from \"./ColdStorage\";\nimport { HotStorageTag } from \"./HotStorage\";\nimport { MimicAuthServiceTag } from \"./MimicAuthService\";\nimport {\n  DocumentManagerTag,\n  DocumentManagerConfigTag,\n  layer as documentManagerLayer,\n  type SubmitResult,\n  type DocumentManagerError,\n} from \"./DocumentManager\";\nimport {\n  PresenceManagerTag,\n  layer as presenceManagerLayer,\n} from \"./PresenceManager\";\n\n// =============================================================================\n// MimicServerEngine Interface\n// =============================================================================\n\n/**\n * MimicServerEngine service interface.\n *\n * Provides document management operations for Mimic collaboration.\n * Use MimicServer.layerHttpLayerRouter() to create WebSocket routes.\n */\nexport interface MimicServerEngine {\n  /**\n   * Submit a transaction to a document.\n   * Authorization is checked against the auth service.\n   * May fail with DocumentManagerError if storage is unavailable.\n   */\n  readonly submit: (\n    documentId: string,\n    transaction: Transaction.Transaction\n  ) => Effect.Effect<SubmitResult, DocumentManagerError>;\n\n  /**\n   * Get document snapshot (current state and version).\n   * May fail with DocumentManagerError if storage is unavailable.\n   */\n  readonly getSnapshot: (\n    documentId: string\n  ) => Effect.Effect<{ state: unknown; version: number }, DocumentManagerError>;\n\n  /**\n   * Subscribe to document broadcasts (transactions).\n   * Returns a stream of server messages.\n   * Requires a Scope for cleanup when the subscription ends.\n   * May fail with DocumentManagerError if storage is unavailable.\n   */\n  readonly subscribe: (\n    documentId: string\n  ) => Effect.Effect<Stream.Stream<Protocol.ServerMessage, never, never>, DocumentManagerError, Scope.Scope>;\n\n  /**\n   * Touch document to prevent idle garbage collection.\n   */\n  readonly touch: (documentId: string) => Effect.Effect<void, never>;\n\n  /**\n   * Get presence snapshot for a document.\n   */\n  readonly getPresenceSnapshot: (\n    documentId: string\n  ) => Effect.Effect<PresenceSnapshot, never>;\n\n  /**\n   * Set presence for a connection.\n   */\n  readonly setPresence: (\n    documentId: string,\n    connectionId: string,\n    entry: PresenceEntry\n  ) => Effect.Effect<void, never>;\n\n  /**\n   * Remove presence for a connection.\n   */\n  readonly removePresence: (\n    documentId: string,\n    connectionId: string\n  ) => Effect.Effect<void, never>;\n\n  /**\n   * Subscribe to presence events for a document.\n   * Requires a Scope for cleanup when the subscription ends.\n   */\n  readonly subscribePresence: (\n    documentId: string\n  ) => Effect.Effect<Stream.Stream<PresenceEvent, never, never>, never, Scope.Scope>;\n\n  /**\n   * Resolved engine configuration.\n   * Used by route layer to access schema, presence config, etc.\n   */\n  readonly config: ResolvedConfig<Primitive.AnyPrimitive>;\n}\n\n// =============================================================================\n// Context Tag\n// =============================================================================\n\n/**\n * Context tag for MimicServerEngine\n */\nexport class MimicServerEngineTag extends Context.Tag(\n  \"@voidhash/mimic-effect/MimicServerEngine\"\n)<MimicServerEngineTag, MimicServerEngine>() {}\n\n// =============================================================================\n// Default Configuration\n// =============================================================================\n\nconst DEFAULT_MAX_IDLE_TIME = Duration.minutes(5);\nconst DEFAULT_MAX_TRANSACTION_HISTORY = 1000;\nconst DEFAULT_SNAPSHOT_INTERVAL = Duration.minutes(5);\nconst DEFAULT_SNAPSHOT_THRESHOLD = 100;\n\n/**\n * Resolve configuration with defaults\n */\nconst resolveConfig = <TSchema extends Primitive.AnyPrimitive>(\n  config: MimicServerEngineConfig<TSchema>\n): ResolvedConfig<TSchema> => ({\n  schema: config.schema,\n  initial: config.initial,\n  presence: config.presence,\n  maxIdleTime: config.maxIdleTime\n    ? Duration.decode(config.maxIdleTime)\n    : DEFAULT_MAX_IDLE_TIME,\n  maxTransactionHistory:\n    config.maxTransactionHistory ?? DEFAULT_MAX_TRANSACTION_HISTORY,\n  snapshot: {\n    interval: config.snapshot?.interval\n      ? Duration.decode(config.snapshot.interval)\n      : DEFAULT_SNAPSHOT_INTERVAL,\n    transactionThreshold:\n      config.snapshot?.transactionThreshold ?? DEFAULT_SNAPSHOT_THRESHOLD,\n  },\n});\n\n// =============================================================================\n// Factory\n// =============================================================================\n\n/**\n * Create a MimicServerEngine layer.\n *\n * This creates the core document management service. To expose it via WebSocket,\n * use MimicServer.layerHttpLayerRouter().\n *\n * @example\n * ```typescript\n * // 1. Create the engine\n * const Engine = MimicServerEngine.make({\n *   schema: DocSchema,\n *   initial: { title: \"Untitled\" },\n *   presence: CursorPresence,\n *   maxIdleTime: \"5 minutes\",\n *   snapshot: { interval: \"5 minutes\", transactionThreshold: 100 },\n * })\n *\n * // 2. Create the WebSocket route\n * const MimicRoute = MimicServer.layerHttpLayerRouter({\n *   path: \"/mimic\",\n * })\n *\n * // 3. Wire together\n * const MimicLive = MimicRoute.pipe(\n *   Layer.provide(Engine),\n *   Layer.provide(ColdStorage.InMemory.make()),\n *   Layer.provide(HotStorage.InMemory.make()),\n *   Layer.provide(MimicAuthService.NoAuth.make()),\n * )\n * ```\n */\nexport const make = <TSchema extends Primitive.AnyPrimitive>(\n  config: MimicServerEngineConfig<TSchema>\n): Layer.Layer<\n  MimicServerEngineTag,\n  never,\n  ColdStorageTag | HotStorageTag | MimicAuthServiceTag\n> => {\n  const resolvedConfig = resolveConfig(config);\n\n  // Create config layer for DocumentManager\n  const configLayer = Layer.succeed(\n    DocumentManagerConfigTag,\n    resolvedConfig as ResolvedConfig<Primitive.AnyPrimitive>\n  );\n\n  // Create internal layers\n  const internalLayers = Layer.mergeAll(\n    documentManagerLayer.pipe(Layer.provide(configLayer)),\n    presenceManagerLayer\n  );\n\n  return Layer.scoped(\n    MimicServerEngineTag,\n    Effect.gen(function* () {\n      const documentManager = yield* DocumentManagerTag;\n      const presenceManager = yield* PresenceManagerTag;\n\n      const engine: MimicServerEngine = {\n        submit: (documentId, transaction) =>\n          documentManager.submit(documentId, transaction),\n\n        getSnapshot: (documentId) => documentManager.getSnapshot(documentId),\n\n        subscribe: (documentId) =>\n          documentManager.subscribe(documentId) as Effect.Effect<\n            Stream.Stream<Protocol.ServerMessage, never, never>,\n            never\n          >,\n\n        touch: (documentId) => documentManager.touch(documentId),\n\n        getPresenceSnapshot: (documentId) =>\n          presenceManager.getSnapshot(documentId),\n\n        setPresence: (documentId, connectionId, entry) =>\n          presenceManager.set(documentId, connectionId, entry),\n\n        removePresence: (documentId, connectionId) =>\n          presenceManager.remove(documentId, connectionId),\n\n        subscribePresence: (documentId) =>\n          presenceManager.subscribe(documentId),\n\n        config: resolvedConfig as ResolvedConfig<Primitive.AnyPrimitive>,\n      };\n\n      return engine;\n    })\n  ).pipe(Layer.provide(internalLayers));\n};\n\n// =============================================================================\n// Re-export namespace\n// =============================================================================\n\nexport const MimicServerEngine = {\n  Tag: MimicServerEngineTag,\n  make,\n};\n\n// =============================================================================\n// Re-export SubmitResult type\n// =============================================================================\n\nexport type { SubmitResult };\n"],"mappings":";;;;;;;;;;;;;;;;AAkIA,IAAa,uBAAb,cAA0C,QAAQ,IAChD,2CACD,EAA2C,CAAC;AAM7C,MAAM,wBAAwB,SAAS,QAAQ,EAAE;AACjD,MAAM,kCAAkC;AACxC,MAAM,4BAA4B,SAAS,QAAQ,EAAE;AACrD,MAAM,6BAA6B;;;;AAKnC,MAAM,iBACJ,WAC4B;;QAAC;EAC7B,QAAQ,OAAO;EACf,SAAS,OAAO;EAChB,UAAU,OAAO;EACjB,aAAa,OAAO,cAChB,SAAS,OAAO,OAAO,YAAY,GACnC;EACJ,gDACE,OAAO,8FAAyB;EAClC,UAAU;GACR,+BAAU,OAAO,8EAAU,YACvB,SAAS,OAAO,OAAO,SAAS,SAAS,GACzC;GACJ,oEACE,OAAO,gFAAU,6FAAwB;GAC5C;EACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCD,MAAa,QACX,WAKG;CACH,MAAM,iBAAiB,cAAc,OAAO;CAG5C,MAAM,cAAc,MAAM,QACxB,0BACA,eACD;CAGD,MAAM,iBAAiB,MAAM,SAC3BA,MAAqB,KAAK,MAAM,QAAQ,YAAY,CAAC,EACrDC,QACD;AAED,QAAO,MAAM,OACX,sBACA,OAAO,IAAI,aAAa;EACtB,MAAM,kBAAkB,OAAO;EAC/B,MAAM,kBAAkB,OAAO;AA+B/B,SA7BkC;GAChC,SAAS,YAAY,gBACnB,gBAAgB,OAAO,YAAY,YAAY;GAEjD,cAAc,eAAe,gBAAgB,YAAY,WAAW;GAEpE,YAAY,eACV,gBAAgB,UAAU,WAAW;GAKvC,QAAQ,eAAe,gBAAgB,MAAM,WAAW;GAExD,sBAAsB,eACpB,gBAAgB,YAAY,WAAW;GAEzC,cAAc,YAAY,cAAc,UACtC,gBAAgB,IAAI,YAAY,cAAc,MAAM;GAEtD,iBAAiB,YAAY,iBAC3B,gBAAgB,OAAO,YAAY,aAAa;GAElD,oBAAoB,eAClB,gBAAgB,UAAU,WAAW;GAEvC,QAAQ;GACT;GAGD,CACH,CAAC,KAAK,MAAM,QAAQ,eAAe,CAAC;;AAOvC,MAAa,oBAAoB;CAC/B,KAAK;CACL;CACD"}

package/dist/index.cjs

@@ -1,11 +1,11 @@
 const require_ColdStorage = require('./ColdStorage.cjs');
+const require_Errors = require('./Errors.cjs');
 const require_HotStorage = require('./HotStorage.cjs');
 const require_Metrics = require('./Metrics.cjs');
 const require_DocumentManager = require('./DocumentManager.cjs');
 const require_PresenceManager = require('./PresenceManager.cjs');
 const require_MimicServerEngine = require('./MimicServerEngine.cjs');
 const require_MimicClusterServerEngine = require('./MimicClusterServerEngine.cjs');
-const require_Errors = require('./Errors.cjs');
 const require_Protocol = require('./Protocol.cjs');
 const require_MimicAuthService = require('./MimicAuthService.cjs');
 const require_MimicServer = require('./MimicServer.cjs');
@@ -38,4 +38,5 @@ Object.defineProperty(exports, 'Protocol', {
     return require_Protocol.Protocol_exports;
   }
 });
-exports.TransactionRejectedError = require_Errors.TransactionRejectedError;
+exports.TransactionRejectedError = require_Errors.TransactionRejectedError;
+exports.WalVersionGapError = require_Errors.WalVersionGapError;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { AuthContext, DurationInput, Initial, InitialContext, InitialFn, MimicClusterServerEngineConfig, MimicServerEngineConfig, MimicServerRouteConfig, Permission, PresenceEntry, PresenceEvent, PresenceRemoveEvent, PresenceSnapshot, PresenceUpdateEvent, ResolvedClusterConfig, ResolvedConfig, ResolvedRouteConfig, SnapshotConfig, StoredDocument, WalEntry } from "./Types.cjs";
-import { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MimicError, MissingDocumentIdError, TransactionRejectedError } from "./Errors.cjs";
+import { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MimicError, MissingDocumentIdError, TransactionRejectedError, WalVersionGapError } from "./Errors.cjs";
 import { Protocol_d_exports } from "./Protocol.cjs";
 import { ColdStorage, ColdStorageTag } from "./ColdStorage.cjs";
 import { HotStorage, HotStorageTag } from "./HotStorage.cjs";
@@ -10,4 +10,4 @@ import { MimicClusterServerEngine } from "./MimicClusterServerEngine.cjs";
 import { MimicServer } from "./MimicServer.cjs";
 import { MimicMetrics } from "./Metrics.cjs";
 import { PresenceManager, PresenceManagerTag } from "./PresenceManager.cjs";
-export { type AuthContext, AuthenticationError, AuthorizationError, ColdStorage, ColdStorageError, ColdStorageTag, DocumentManager, DocumentManagerConfigTag, DocumentManagerTag, type DurationInput, HotStorage, HotStorageError, HotStorageTag, type Initial, type InitialContext, type InitialFn, MessageParseError, MimicAuthService, MimicAuthServiceTag, MimicClusterServerEngine, type MimicClusterServerEngineConfig, type MimicError, MimicMetrics, MimicServer, MimicServerEngine, type MimicServerEngineConfig, MimicServerEngineTag, type MimicServerRouteConfig, MissingDocumentIdError, type Permission, type PresenceEntry, type PresenceEvent, PresenceManager, PresenceManagerTag, type PresenceRemoveEvent, type PresenceSnapshot, type PresenceUpdateEvent, Protocol_d_exports as Protocol, type ResolvedClusterConfig, type ResolvedConfig, type ResolvedRouteConfig, type SnapshotConfig, type StoredDocument, type SubmitResult, TransactionRejectedError, type WalEntry };
+export { AuthContext, AuthenticationError, AuthorizationError, ColdStorage, ColdStorageError, ColdStorageTag, DocumentManager, DocumentManagerConfigTag, DocumentManagerTag, DurationInput, HotStorage, HotStorageError, HotStorageTag, Initial, InitialContext, InitialFn, MessageParseError, MimicAuthService, MimicAuthServiceTag, MimicClusterServerEngine, MimicClusterServerEngineConfig, MimicError, MimicMetrics, MimicServer, MimicServerEngine, MimicServerEngineConfig, MimicServerEngineTag, type MimicServerRouteConfig, MissingDocumentIdError, Permission, PresenceEntry, PresenceEvent, PresenceManager, PresenceManagerTag, PresenceRemoveEvent, PresenceSnapshot, PresenceUpdateEvent, Protocol_d_exports as Protocol, ResolvedClusterConfig, ResolvedConfig, ResolvedRouteConfig, SnapshotConfig, StoredDocument, type SubmitResult, TransactionRejectedError, WalEntry, WalVersionGapError };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { AuthContext, DurationInput, Initial, InitialContext, InitialFn, MimicClusterServerEngineConfig, MimicServerEngineConfig, MimicServerRouteConfig, Permission, PresenceEntry, PresenceEvent, PresenceRemoveEvent, PresenceSnapshot, PresenceUpdateEvent, ResolvedClusterConfig, ResolvedConfig, ResolvedRouteConfig, SnapshotConfig, StoredDocument, WalEntry } from "./Types.mjs";
-import { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MimicError, MissingDocumentIdError, TransactionRejectedError } from "./Errors.mjs";
+import { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MimicError, MissingDocumentIdError, TransactionRejectedError, WalVersionGapError } from "./Errors.mjs";
 import { Protocol_d_exports } from "./Protocol.mjs";
 import { ColdStorage, ColdStorageTag } from "./ColdStorage.mjs";
 import { HotStorage, HotStorageTag } from "./HotStorage.mjs";
@@ -10,4 +10,4 @@ import { MimicClusterServerEngine } from "./MimicClusterServerEngine.mjs";
 import { MimicServer } from "./MimicServer.mjs";
 import { MimicMetrics } from "./Metrics.mjs";
 import { PresenceManager, PresenceManagerTag } from "./PresenceManager.mjs";
-export { type AuthContext, AuthenticationError, AuthorizationError, ColdStorage, ColdStorageError, ColdStorageTag, DocumentManager, DocumentManagerConfigTag, DocumentManagerTag, type DurationInput, HotStorage, HotStorageError, HotStorageTag, type Initial, type InitialContext, type InitialFn, MessageParseError, MimicAuthService, MimicAuthServiceTag, MimicClusterServerEngine, type MimicClusterServerEngineConfig, type MimicError, MimicMetrics, MimicServer, MimicServerEngine, type MimicServerEngineConfig, MimicServerEngineTag, type MimicServerRouteConfig, MissingDocumentIdError, type Permission, type PresenceEntry, type PresenceEvent, PresenceManager, PresenceManagerTag, type PresenceRemoveEvent, type PresenceSnapshot, type PresenceUpdateEvent, Protocol_d_exports as Protocol, type ResolvedClusterConfig, type ResolvedConfig, type ResolvedRouteConfig, type SnapshotConfig, type StoredDocument, type SubmitResult, TransactionRejectedError, type WalEntry };
+export { AuthContext, AuthenticationError, AuthorizationError, ColdStorage, ColdStorageError, ColdStorageTag, DocumentManager, DocumentManagerConfigTag, DocumentManagerTag, DurationInput, HotStorage, HotStorageError, HotStorageTag, Initial, InitialContext, InitialFn, MessageParseError, MimicAuthService, MimicAuthServiceTag, MimicClusterServerEngine, MimicClusterServerEngineConfig, MimicError, MimicMetrics, MimicServer, MimicServerEngine, MimicServerEngineConfig, MimicServerEngineTag, type MimicServerRouteConfig, MissingDocumentIdError, Permission, PresenceEntry, PresenceEvent, PresenceManager, PresenceManagerTag, PresenceRemoveEvent, PresenceSnapshot, PresenceUpdateEvent, Protocol_d_exports as Protocol, ResolvedClusterConfig, ResolvedConfig, ResolvedRouteConfig, SnapshotConfig, StoredDocument, type SubmitResult, TransactionRejectedError, WalEntry, WalVersionGapError };

package/dist/index.mjs

@@ -1,13 +1,13 @@
 import { ColdStorage, ColdStorageTag } from "./ColdStorage.mjs";
+import { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MissingDocumentIdError, TransactionRejectedError, WalVersionGapError } from "./Errors.mjs";
 import { HotStorage, HotStorageTag } from "./HotStorage.mjs";
 import { MimicMetrics } from "./Metrics.mjs";
 import { DocumentManager, DocumentManagerConfigTag, DocumentManagerTag } from "./DocumentManager.mjs";
 import { PresenceManager, PresenceManagerTag } from "./PresenceManager.mjs";
 import { MimicServerEngine, MimicServerEngineTag } from "./MimicServerEngine.mjs";
 import { MimicClusterServerEngine } from "./MimicClusterServerEngine.mjs";
-import { AuthenticationError, AuthorizationError, ColdStorageError, HotStorageError, MessageParseError, MissingDocumentIdError, TransactionRejectedError } from "./Errors.mjs";
 import { Protocol_exports } from "./Protocol.mjs";
 import { MimicAuthService, MimicAuthServiceTag } from "./MimicAuthService.mjs";
 import { MimicServer } from "./MimicServer.mjs";
 
-export { AuthenticationError, AuthorizationError, ColdStorage, ColdStorageError, ColdStorageTag, DocumentManager, DocumentManagerConfigTag, DocumentManagerTag, HotStorage, HotStorageError, HotStorageTag, MessageParseError, MimicAuthService, MimicAuthServiceTag, MimicClusterServerEngine, MimicMetrics, MimicServer, MimicServerEngine, MimicServerEngineTag, MissingDocumentIdError, PresenceManager, PresenceManagerTag, Protocol_exports as Protocol, TransactionRejectedError };
+export { AuthenticationError, AuthorizationError, ColdStorage, ColdStorageError, ColdStorageTag, DocumentManager, DocumentManagerConfigTag, DocumentManagerTag, HotStorage, HotStorageError, HotStorageTag, MessageParseError, MimicAuthService, MimicAuthServiceTag, MimicClusterServerEngine, MimicMetrics, MimicServer, MimicServerEngine, MimicServerEngineTag, MissingDocumentIdError, PresenceManager, PresenceManagerTag, Protocol_exports as Protocol, TransactionRejectedError, WalVersionGapError };

package/dist/testing/ColdStorageTestSuite.cjs

@@ -0,0 +1,508 @@
+const require_ColdStorage = require('../ColdStorage.cjs');
+const require_objectSpread2 = require('../_virtual/_@oxc-project_runtime@0.103.0/helpers/objectSpread2.cjs');
+const require_assertions = require('./assertions.cjs');
+let effect = require("effect");
+
+//#region src/testing/ColdStorageTestSuite.ts
+/**
+* @voidhash/mimic-effect/testing - ColdStorage Test Suite
+*
+* Comprehensive test suite for ColdStorage adapter implementations.
+* These tests verify that an adapter correctly implements the ColdStorage interface
+* and can reliably store/retrieve document snapshots without data loss.
+*/
+const Categories = {
+	BasicOperations: "Basic Operations",
+	DataIntegrity: "Data Integrity",
+	VersionHandling: "Version Handling",
+	TimestampHandling: "Timestamp Handling",
+	DocumentIdEdgeCases: "Document ID Edge Cases",
+	DocumentIsolation: "Document Isolation",
+	ConsistencyGuarantees: "Consistency Guarantees"
+};
+const makeDoc = (overrides = {}) => require_objectSpread2._objectSpread2({
+	state: { title: "Test Document" },
+	version: 1,
+	schemaVersion: 1,
+	savedAt: Date.now()
+}, overrides);
+const generateLargeState = (sizeKB) => {
+	const chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+	const targetBytes = sizeKB * 1024;
+	let content = "";
+	while (content.length < targetBytes) content += chars[Math.floor(Math.random() * 62)];
+	return {
+		content,
+		padding: Array(100).fill("x")
+	};
+};
+const tests = [
+	{
+		name: "load returns undefined for non-existent document",
+		category: Categories.BasicOperations,
+		run: effect.Effect.gen(function* () {
+			yield* require_assertions.assertUndefined(yield* (yield* require_ColdStorage.ColdStorageTag).load("non-existent-doc-id-12345"), "Expected undefined for non-existent document");
+		})
+	},
+	{
+		name: "save then load returns exact same document",
+		category: Categories.BasicOperations,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc();
+			yield* storage.save("test-doc-1", doc);
+			yield* require_assertions.assertEqual(yield* storage.load("test-doc-1"), doc, "Loaded document should match saved document");
+		})
+	},
+	{
+		name: "save overwrites existing document",
+		category: Categories.BasicOperations,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc1 = makeDoc({
+				state: { title: "First" },
+				version: 1
+			});
+			const doc2 = makeDoc({
+				state: { title: "Second" },
+				version: 2
+			});
+			yield* storage.save("test-doc-2", doc1);
+			yield* storage.save("test-doc-2", doc2);
+			yield* require_assertions.assertEqual(yield* storage.load("test-doc-2"), doc2, "Should return the second (overwritten) document");
+		})
+	},
+	{
+		name: "delete removes document",
+		category: Categories.BasicOperations,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc();
+			yield* storage.save("test-doc-3", doc);
+			yield* storage.delete("test-doc-3");
+			yield* require_assertions.assertUndefined(yield* storage.load("test-doc-3"), "Document should be undefined after deletion");
+		})
+	},
+	{
+		name: "delete on non-existent document does not error",
+		category: Categories.BasicOperations,
+		run: effect.Effect.gen(function* () {
+			yield* (yield* require_ColdStorage.ColdStorageTag).delete("definitely-non-existent-doc-xyz");
+		})
+	},
+	{
+		name: "all StoredDocument fields are preserved",
+		category: Categories.DataIntegrity,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = {
+				state: { nested: { value: 42 } },
+				version: 123,
+				schemaVersion: 2,
+				savedAt: 17040672e5
+			};
+			yield* storage.save("fields-test", doc);
+			const definedLoaded = yield* require_assertions.assertDefined(yield* storage.load("fields-test"), "Document should exist");
+			yield* require_assertions.assertEqual(definedLoaded.state, doc.state, "state should be preserved");
+			yield* require_assertions.assertEqual(definedLoaded.version, doc.version, "version should be preserved");
+			yield* require_assertions.assertEqual(definedLoaded.schemaVersion, doc.schemaVersion, "schemaVersion should be preserved");
+			yield* require_assertions.assertEqual(definedLoaded.savedAt, doc.savedAt, "savedAt should be preserved");
+		})
+	},
+	{
+		name: "complex nested state objects survive roundtrip",
+		category: Categories.DataIntegrity,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ state: {
+				level1: {
+					level2: { level3: {
+						value: "deep",
+						array: [
+							1,
+							2,
+							{ nested: true }
+						]
+					} },
+					sibling: "value"
+				},
+				topLevel: 42
+			} });
+			yield* storage.save("complex-state", doc);
+			yield* require_assertions.assertEqual(yield* storage.load("complex-state"), doc, "Complex nested state should survive roundtrip");
+		})
+	},
+	{
+		name: "arrays in state survive roundtrip",
+		category: Categories.DataIntegrity,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ state: {
+				numbers: [
+					1,
+					2,
+					3,
+					4,
+					5
+				],
+				strings: [
+					"a",
+					"b",
+					"c"
+				],
+				mixed: [
+					1,
+					"two",
+					{ three: 3 },
+					[4]
+				],
+				empty: []
+			} });
+			yield* storage.save("arrays-test", doc);
+			yield* require_assertions.assertEqual(yield* storage.load("arrays-test"), doc, "Arrays should survive roundtrip");
+		})
+	},
+	{
+		name: "null values in state survive roundtrip",
+		category: Categories.DataIntegrity,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ state: {
+				nullValue: null,
+				nested: { alsoNull: null },
+				array: [
+					null,
+					1,
+					null
+				]
+			} });
+			yield* storage.save("null-test", doc);
+			yield* require_assertions.assertEqual(yield* storage.load("null-test"), doc, "null values should survive roundtrip");
+		})
+	},
+	{
+		name: "empty object survives roundtrip",
+		category: Categories.DataIntegrity,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ state: {} });
+			yield* storage.save("empty-obj", doc);
+			yield* require_assertions.assertEqual(yield* storage.load("empty-obj"), doc, "Empty object should survive roundtrip");
+		})
+	},
+	{
+		name: "empty array survives roundtrip",
+		category: Categories.DataIntegrity,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ state: [] });
+			yield* storage.save("empty-arr", doc);
+			yield* require_assertions.assertEqual(yield* storage.load("empty-arr"), doc, "Empty array should survive roundtrip");
+		})
+	},
+	{
+		name: "unicode strings in state survive roundtrip",
+		category: Categories.DataIntegrity,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ state: {
+				emoji: "Hello! How are you?",
+				chinese: "Chinese Characters",
+				arabic: "Arabic Letters",
+				special: "Combined: Cafe"
+			} });
+			yield* storage.save("unicode-test", doc);
+			yield* require_assertions.assertEqual(yield* storage.load("unicode-test"), doc, "Unicode strings should survive roundtrip");
+		})
+	},
+	{
+		name: "large state objects (100KB+) survive roundtrip",
+		category: Categories.DataIntegrity,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ state: generateLargeState(100) });
+			yield* storage.save("large-doc", doc);
+			yield* require_assertions.assertEqual(yield* storage.load("large-doc"), doc, "Large documents should survive roundtrip");
+		})
+	},
+	{
+		name: "special JSON characters survive roundtrip",
+		category: Categories.DataIntegrity,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ state: {
+				quotes: "He said \"hello\"",
+				backslash: "path\\to\\file",
+				newline: "line1\nline2",
+				tab: "col1	col2",
+				mixed: "All: \"\\\n	"
+			} });
+			yield* storage.save("special-chars", doc);
+			yield* require_assertions.assertEqual(yield* storage.load("special-chars"), doc, "Special JSON characters should survive roundtrip");
+		})
+	},
+	{
+		name: "version 0 is preserved correctly",
+		category: Categories.VersionHandling,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ version: 0 });
+			yield* storage.save("version-0", doc);
+			yield* require_assertions.assertEqual((yield* require_assertions.assertDefined(yield* storage.load("version-0"), "Document should exist")).version, 0, "Version 0 should be preserved");
+		})
+	},
+	{
+		name: "version 1 is preserved correctly",
+		category: Categories.VersionHandling,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ version: 1 });
+			yield* storage.save("version-1", doc);
+			yield* require_assertions.assertEqual((yield* require_assertions.assertDefined(yield* storage.load("version-1"), "Document should exist")).version, 1, "Version 1 should be preserved");
+		})
+	},
+	{
+		name: "large version numbers are preserved",
+		category: Categories.VersionHandling,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const largeVersion = Number.MAX_SAFE_INTEGER;
+			const doc = makeDoc({ version: largeVersion });
+			yield* storage.save("large-version", doc);
+			yield* require_assertions.assertEqual((yield* require_assertions.assertDefined(yield* storage.load("large-version"), "Document should exist")).version, largeVersion, "Large version number should be preserved exactly");
+		})
+	},
+	{
+		name: "schema version is preserved correctly",
+		category: Categories.VersionHandling,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ schemaVersion: 42 });
+			yield* storage.save("schema-version", doc);
+			yield* require_assertions.assertEqual((yield* require_assertions.assertDefined(yield* storage.load("schema-version"), "Document should exist")).schemaVersion, 42, "Schema version should be preserved");
+		})
+	},
+	{
+		name: "savedAt timestamp is preserved exactly",
+		category: Categories.TimestampHandling,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const timestamp = 17040672e5;
+			const doc = makeDoc({ savedAt: timestamp });
+			yield* storage.save("timestamp-exact", doc);
+			yield* require_assertions.assertEqual((yield* require_assertions.assertDefined(yield* storage.load("timestamp-exact"), "Document should exist")).savedAt, timestamp, "savedAt should be preserved exactly");
+		})
+	},
+	{
+		name: "timestamp 0 is preserved correctly",
+		category: Categories.TimestampHandling,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc = makeDoc({ savedAt: 0 });
+			yield* storage.save("timestamp-0", doc);
+			yield* require_assertions.assertEqual((yield* require_assertions.assertDefined(yield* storage.load("timestamp-0"), "Document should exist")).savedAt, 0, "Timestamp 0 should be preserved");
+		})
+	},
+	{
+		name: "recent timestamps are preserved correctly",
+		category: Categories.TimestampHandling,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const now = Date.now();
+			const doc = makeDoc({ savedAt: now });
+			yield* storage.save("timestamp-recent", doc);
+			yield* require_assertions.assertEqual((yield* require_assertions.assertDefined(yield* storage.load("timestamp-recent"), "Document should exist")).savedAt, now, "Recent timestamp should be preserved");
+		})
+	},
+	{
+		name: "long documentId (1000+ chars) works",
+		category: Categories.DocumentIdEdgeCases,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const longId = "x".repeat(1e3);
+			const doc = makeDoc();
+			yield* storage.save(longId, doc);
+			yield* require_assertions.assertEqual(yield* storage.load(longId), doc, "Long documentId should work correctly");
+		})
+	},
+	{
+		name: "unicode documentId works",
+		category: Categories.DocumentIdEdgeCases,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const unicodeId = "doc-test-id";
+			const doc = makeDoc();
+			yield* storage.save(unicodeId, doc);
+			yield* require_assertions.assertEqual(yield* storage.load(unicodeId), doc, "Unicode documentId should work correctly");
+		})
+	},
+	{
+		name: "documentId with special chars works",
+		category: Categories.DocumentIdEdgeCases,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const specialId = "doc/path:to.file";
+			const doc = makeDoc();
+			yield* storage.save(specialId, doc);
+			yield* require_assertions.assertEqual(yield* storage.load(specialId), doc, "DocumentId with special chars should work");
+		})
+	},
+	{
+		name: "documentId with spaces works",
+		category: Categories.DocumentIdEdgeCases,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const spacedId = "doc with spaces";
+			const doc = makeDoc();
+			yield* storage.save(spacedId, doc);
+			yield* require_assertions.assertEqual(yield* storage.load(spacedId), doc, "DocumentId with spaces should work");
+		})
+	},
+	{
+		name: "different documents are stored independently",
+		category: Categories.DocumentIsolation,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc1 = makeDoc({
+				state: { id: 1 },
+				version: 1
+			});
+			const doc2 = makeDoc({
+				state: { id: 2 },
+				version: 2
+			});
+			yield* storage.save("iso-doc-1", doc1);
+			yield* storage.save("iso-doc-2", doc2);
+			const loaded1 = yield* storage.load("iso-doc-1");
+			const loaded2 = yield* storage.load("iso-doc-2");
+			yield* require_assertions.assertEqual(loaded1, doc1, "First document should be unchanged");
+			yield* require_assertions.assertEqual(loaded2, doc2, "Second document should be unchanged");
+		})
+	},
+	{
+		name: "deleting one document does not affect others",
+		category: Categories.DocumentIsolation,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc1 = makeDoc({ state: { id: 1 } });
+			const doc2 = makeDoc({ state: { id: 2 } });
+			yield* storage.save("del-iso-1", doc1);
+			yield* storage.save("del-iso-2", doc2);
+			yield* storage.delete("del-iso-1");
+			const loaded1 = yield* storage.load("del-iso-1");
+			const loaded2 = yield* storage.load("del-iso-2");
+			yield* require_assertions.assertUndefined(loaded1, "Deleted document should be undefined");
+			yield* require_assertions.assertEqual(loaded2, doc2, "Other document should be unchanged");
+		})
+	},
+	{
+		name: "updating one document does not affect others",
+		category: Categories.DocumentIsolation,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc1v1 = makeDoc({
+				state: {
+					id: 1,
+					v: 1
+				},
+				version: 1
+			});
+			const doc1v2 = makeDoc({
+				state: {
+					id: 1,
+					v: 2
+				},
+				version: 2
+			});
+			const doc2 = makeDoc({ state: { id: 2 } });
+			yield* storage.save("upd-iso-1", doc1v1);
+			yield* storage.save("upd-iso-2", doc2);
+			yield* storage.save("upd-iso-1", doc1v2);
+			const loaded1 = yield* storage.load("upd-iso-1");
+			const loaded2 = yield* storage.load("upd-iso-2");
+			yield* require_assertions.assertEqual(loaded1, doc1v2, "Updated document should have new value");
+			yield* require_assertions.assertEqual(loaded2, doc2, "Other document should be unchanged");
+		})
+	},
+	{
+		name: "multiple saves to same doc, load returns latest",
+		category: Categories.ConsistencyGuarantees,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc1 = makeDoc({
+				state: { v: 1 },
+				version: 1
+			});
+			const doc2 = makeDoc({
+				state: { v: 2 },
+				version: 2
+			});
+			const doc3 = makeDoc({
+				state: { v: 3 },
+				version: 3
+			});
+			yield* storage.save("multi-save", doc1);
+			yield* storage.save("multi-save", doc2);
+			yield* storage.save("multi-save", doc3);
+			yield* require_assertions.assertEqual(yield* storage.load("multi-save"), doc3, "Should return the latest saved document");
+		})
+	},
+	{
+		name: "save-delete-save sequence works correctly",
+		category: Categories.ConsistencyGuarantees,
+		run: effect.Effect.gen(function* () {
+			const storage = yield* require_ColdStorage.ColdStorageTag;
+			const doc1 = makeDoc({
+				state: { phase: "first" },
+				version: 1
+			});
+			const doc2 = makeDoc({
+				state: { phase: "second" },
+				version: 2
+			});
+			yield* storage.save("sds-test", doc1);
+			yield* storage.delete("sds-test");
+			yield* storage.save("sds-test", doc2);
+			yield* require_assertions.assertEqual(yield* storage.load("sds-test"), doc2, "Should return document saved after delete");
+		})
+	}
+];
+/**
+* Get all ColdStorage test cases.
+*
+* @returns Array of test cases that require ColdStorageTag
+*/
+const makeTests = () => tests;
+/**
+* Run all tests and collect results.
+*
+* @returns Effect that produces TestResults
+*/
+const runAll = () => effect.Effect.gen(function* () {
+	const passed = [];
+	const failed = [];
+	for (const test of tests) {
+		const result = yield* effect.Effect.either(test.run);
+		if (result._tag === "Right") passed.push(test);
+		else failed.push({
+			test,
+			error: result.left
+		});
+	}
+	return {
+		passed,
+		failed,
+		total: tests.length,
+		passCount: passed.length,
+		failCount: failed.length
+	};
+});
+const ColdStorageTestSuite = {
+	Categories,
+	makeTests,
+	runAll
+};
+
+//#endregion
+exports.Categories = Categories;
+exports.ColdStorageTestSuite = ColdStorageTestSuite;

package/dist/testing/ColdStorageTestSuite.d.cts

@@ -0,0 +1,36 @@
+import { ColdStorageError } from "../Errors.cjs";
+import { ColdStorageTag } from "../ColdStorage.cjs";
+import { StorageTestCase, TestError, TestResults } from "./types.cjs";
+import { Effect } from "effect";
+
+//#region src/testing/ColdStorageTestSuite.d.ts
+
+/**
+ * Error type for ColdStorage tests - can be either a TestError or a ColdStorageError
+ */
+type ColdStorageTestError = TestError | ColdStorageError;
+declare const Categories: {
+  readonly BasicOperations: "Basic Operations";
+  readonly DataIntegrity: "Data Integrity";
+  readonly VersionHandling: "Version Handling";
+  readonly TimestampHandling: "Timestamp Handling";
+  readonly DocumentIdEdgeCases: "Document ID Edge Cases";
+  readonly DocumentIsolation: "Document Isolation";
+  readonly ConsistencyGuarantees: "Consistency Guarantees";
+};
+declare const ColdStorageTestSuite: {
+  Categories: {
+    readonly BasicOperations: "Basic Operations";
+    readonly DataIntegrity: "Data Integrity";
+    readonly VersionHandling: "Version Handling";
+    readonly TimestampHandling: "Timestamp Handling";
+    readonly DocumentIdEdgeCases: "Document ID Edge Cases";
+    readonly DocumentIsolation: "Document Isolation";
+    readonly ConsistencyGuarantees: "Consistency Guarantees";
+  };
+  makeTests: () => StorageTestCase<ColdStorageTestError, ColdStorageTag>[];
+  runAll: () => Effect.Effect<TestResults<ColdStorageTestError, ColdStorageTag>, never, ColdStorageTag>;
+};
+//#endregion
+export { Categories, ColdStorageTestError, ColdStorageTestSuite };
+//# sourceMappingURL=ColdStorageTestSuite.d.cts.map

package/dist/testing/ColdStorageTestSuite.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ColdStorageTestSuite.d.cts","names":[],"sources":["../../src/testing/ColdStorageTestSuite.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AA6iBE,KAvhBU,oBAAA,GAAuB,SAuhBjC,GAvhB6C,gBAuhB7C;AAHwB,cA9gBb,UA8gBoB,EAAA;EAAM,SAAA,eAAA,EAAA,kBAAA;;;;;;;;cA8B1B;;;;;;;;;;mBAxCgB,gBAC3B,sBACA;gBAQwB,MAAA,CAAO,OAC/B,YAAY,sBAAsB,wBAElC"}