@mindees/data 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import { DataError, DataErrorCode } from "./errors.js";
 import { Clock, ClockOptions, Hlc, compareHlc, createClock, decodeHlc, encodeHlc } from "./hlc.js";
 import { LwwMap, LwwRegister, lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, mergeLwwMap, mergeRegister } from "./lww.js";
 import { OrSet, emptyOrSet, mergeOrSet, orAdd, orHas, orRemove, orValues } from "./or-set.js";
-import { Persistence, createMemoryPersistence } from "./persist.js";
 import { Cursor, MutationLog, Op, SyncEngine, SyncEngineOptions, SyncSnapshot, SyncTransport, createMemoryHub, createMutationLog, createSyncEngine } from "./sync.js";
+import { Persistence, PersistentEngineOptions, WebStorageLike, createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine } from "./persist.js";
 import { VersionVector, vvDominates, vvEquals, vvGet, vvMerge, vvObserve } from "./version-vector.js";
 import { Maturity, NotImplementedError, PackageInfo, notImplemented } from "@mindees/core";
 
@@ -12,7 +12,7 @@ import { Maturity, NotImplementedError, PackageInfo, notImplemented } from "@min
 /** The npm package name. */
 declare const name = "@mindees/data";
 /** The package version. All `@mindees/*` packages share one locked version line. */
-declare const VERSION = "0.4.0";
+declare const VERSION = "0.5.0";
 /** Current maturity of this package. See the repository `STATUS.md`. */
 declare const maturity: Maturity;
 /**
@@ -22,5 +22,5 @@ declare const maturity: Maturity;
  */
 declare const info: PackageInfo;
 //#endregion
-export { type Clock, type ClockOptions, type Collection, type CollectionOptions, type Cursor, DataError, type DataErrorCode, type Hlc, type Id, type LwwMap, type LwwRegister, type Maturity, type MutationLog, NotImplementedError, type Op, type OptimisticChange, type OrSet, type PackageInfo, type Persistence, type SyncEngine, type SyncEngineOptions, type SyncSnapshot, type SyncTransport, VERSION, type VersionVector, compareHlc, createClock, createCollection, createMemoryHub, createMemoryPersistence, createMutationLog, createSyncEngine, decodeHlc, emptyOrSet, encodeHlc, info, lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, maturity, mergeLwwMap, mergeOrSet, mergeRegister, name, notImplemented, orAdd, orHas, orRemove, orValues, vvDominates, vvEquals, vvGet, vvMerge, vvObserve };
+export { type Clock, type ClockOptions, type Collection, type CollectionOptions, type Cursor, DataError, type DataErrorCode, type Hlc, type Id, type LwwMap, type LwwRegister, type Maturity, type MutationLog, NotImplementedError, type Op, type OptimisticChange, type OrSet, type PackageInfo, type Persistence, type PersistentEngineOptions, type SyncEngine, type SyncEngineOptions, type SyncSnapshot, type SyncTransport, VERSION, type VersionVector, type WebStorageLike, compareHlc, createClock, createCollection, createMemoryHub, createMemoryPersistence, createMutationLog, createPersistentEngine, createSyncEngine, createWebStoragePersistence, decodeHlc, emptyOrSet, encodeHlc, info, loadSnapshot, lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, maturity, mergeLwwMap, mergeOrSet, mergeRegister, name, notImplemented, orAdd, orHas, orRemove, orValues, persistEngine, vvDominates, vvEquals, vvGet, vvMerge, vvObserve };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,15 +3,15 @@ import { createCollection } from "./collection.js";
 import { compareHlc, createClock, decodeHlc, encodeHlc } from "./hlc.js";
 import { lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, mergeLwwMap, mergeRegister } from "./lww.js";
 import { emptyOrSet, mergeOrSet, orAdd, orHas, orRemove, orValues } from "./or-set.js";
-import { createMemoryPersistence } from "./persist.js";
 import { createMemoryHub, createMutationLog, createSyncEngine } from "./sync.js";
+import { createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine } from "./persist.js";
 import { vvDominates, vvEquals, vvGet, vvMerge, vvObserve } from "./version-vector.js";
 import { NotImplementedError, notImplemented } from "@mindees/core";
 //#region src/index.ts
 /** The npm package name. */
 const name = "@mindees/data";
 /** The package version. All `@mindees/*` packages share one locked version line. */
-const VERSION = "0.4.0";
+const VERSION = "0.5.0";
 /** Current maturity of this package. See the repository `STATUS.md`. */
 const maturity = "experimental";
 /**
@@ -25,6 +25,6 @@ const info = Object.freeze({
 	maturity
 });
 //#endregion
-export { DataError, NotImplementedError, VERSION, compareHlc, createClock, createCollection, createMemoryHub, createMemoryPersistence, createMutationLog, createSyncEngine, decodeHlc, emptyOrSet, encodeHlc, info, lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, maturity, mergeLwwMap, mergeOrSet, mergeRegister, name, notImplemented, orAdd, orHas, orRemove, orValues, vvDominates, vvEquals, vvGet, vvMerge, vvObserve };
+export { DataError, NotImplementedError, VERSION, compareHlc, createClock, createCollection, createMemoryHub, createMemoryPersistence, createMutationLog, createPersistentEngine, createSyncEngine, createWebStoragePersistence, decodeHlc, emptyOrSet, encodeHlc, info, loadSnapshot, lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, maturity, mergeLwwMap, mergeOrSet, mergeRegister, name, notImplemented, orAdd, orHas, orRemove, orValues, persistEngine, vvDominates, vvEquals, vvGet, vvMerge, vvObserve };
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@mindees/data` (Continuum) — local-first reactive store + sync.\n *\n * Phase 10 ships the **reactive document store**: {@link createCollection}, a\n * signals-native, in-memory collection with fine-grained reactive reads\n * (`get`/`has`/`all`/`where`/`size`), atomic mutations (`insert`/`upsert`/`update`/\n * `delete`/`clear`/`tx`), and {@link Collection.optimistic optimistic} changes that can\n * be rolled back. Built on `@mindees/core` signals only. Hybrid-logical-clock causality,\n * CRDT conflict resolution, the local-first sync engine, a reference sync server on the\n * `@mindees/data/server` subpath, and a persistence contract/export/restore path build\n * on this. Native durable adapters, production sync hardening, and CRDT-library/rich-text\n * interop remain research tracks.\n *\n * @module\n */\n\nimport type { Maturity, PackageInfo } from '@mindees/core'\nimport { NotImplementedError, notImplemented } from '@mindees/core'\n\n/** The npm package name. */\nexport const name = '@mindees/data'\n\n/** The package version. All `@mindees/*` packages share one locked version line. */\nexport const VERSION = '0.4.0'\n\n/** Current maturity of this package. See the repository `STATUS.md`. */\nexport const maturity: Maturity = 'experimental'\n\n/**\n * Static identity + maturity metadata for this package. Frozen so the\n * self-reported identity tooling introspects cannot be mutated at runtime,\n * matching the `readonly` fields of {@link PackageInfo}.\n */\nexport const info: PackageInfo = Object.freeze({ name, version: VERSION, maturity })\n\nexport {\n  type Collection,\n  type CollectionOptions,\n  createCollection,\n  type Id,\n  type OptimisticChange,\n} from './collection'\nexport { DataError, type DataErrorCode } from './errors'\nexport {\n  type Clock,\n  type ClockOptions,\n  compareHlc,\n  createClock,\n  decodeHlc,\n  encodeHlc,\n  type Hlc,\n} from './hlc'\nexport {\n  type LwwMap,\n  type LwwRegister,\n  lwwDelete,\n  lwwGet,\n  lwwHas,\n  lwwKeys,\n  lwwSet,\n  mergeLwwMap,\n  mergeRegister,\n} from './lww'\nexport {\n  emptyOrSet,\n  mergeOrSet,\n  type OrSet,\n  orAdd,\n  orHas,\n  orRemove,\n  orValues,\n} from './or-set'\nexport { createMemoryPersistence, type Persistence } from './persist'\nexport {\n  type Cursor,\n  createMemoryHub,\n  createMutationLog,\n  createSyncEngine,\n  type MutationLog,\n  type Op,\n  type SyncEngine,\n  type SyncEngineOptions,\n  type SyncSnapshot,\n  type SyncTransport,\n} from './sync'\nexport {\n  type VersionVector,\n  vvDominates,\n  vvEquals,\n  vvGet,\n  vvMerge,\n  vvObserve,\n} from './version-vector'\n\nexport type { Maturity, PackageInfo }\nexport { NotImplementedError, notImplemented }\n"],"mappings":";;;;;;;;;;;AAoBA,MAAa,OAAO;;AAGpB,MAAa,UAAU;;AAGvB,MAAa,WAAqB;;;;;;AAOlC,MAAa,OAAoB,OAAO,OAAO;CAAE;CAAM,SAAS;CAAS;AAAS,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@mindees/data` (Continuum) — local-first reactive store + sync.\n *\n * Phase 10 ships the **reactive document store**: {@link createCollection}, a\n * signals-native, in-memory collection with fine-grained reactive reads\n * (`get`/`has`/`all`/`where`/`size`), atomic mutations (`insert`/`upsert`/`update`/\n * `delete`/`clear`/`tx`), and {@link Collection.optimistic optimistic} changes that can\n * be rolled back. Built on `@mindees/core` signals only. Hybrid-logical-clock causality,\n * CRDT conflict resolution, the local-first sync engine, a reference sync server on the\n * `@mindees/data/server` subpath, and a persistence contract/export/restore path build\n * on this. Native durable adapters, production sync hardening, and CRDT-library/rich-text\n * interop remain research tracks.\n *\n * @module\n */\n\nimport type { Maturity, PackageInfo } from '@mindees/core'\nimport { NotImplementedError, notImplemented } from '@mindees/core'\n\n/** The npm package name. */\nexport const name = '@mindees/data'\n\n/** The package version. All `@mindees/*` packages share one locked version line. */\nexport const VERSION = '0.5.0'\n\n/** Current maturity of this package. See the repository `STATUS.md`. */\nexport const maturity: Maturity = 'experimental'\n\n/**\n * Static identity + maturity metadata for this package. Frozen so the\n * self-reported identity tooling introspects cannot be mutated at runtime,\n * matching the `readonly` fields of {@link PackageInfo}.\n */\nexport const info: PackageInfo = Object.freeze({ name, version: VERSION, maturity })\n\nexport {\n  type Collection,\n  type CollectionOptions,\n  createCollection,\n  type Id,\n  type OptimisticChange,\n} from './collection'\nexport { DataError, type DataErrorCode } from './errors'\nexport {\n  type Clock,\n  type ClockOptions,\n  compareHlc,\n  createClock,\n  decodeHlc,\n  encodeHlc,\n  type Hlc,\n} from './hlc'\nexport {\n  type LwwMap,\n  type LwwRegister,\n  lwwDelete,\n  lwwGet,\n  lwwHas,\n  lwwKeys,\n  lwwSet,\n  mergeLwwMap,\n  mergeRegister,\n} from './lww'\nexport {\n  emptyOrSet,\n  mergeOrSet,\n  type OrSet,\n  orAdd,\n  orHas,\n  orRemove,\n  orValues,\n} from './or-set'\nexport {\n  createMemoryPersistence,\n  createPersistentEngine,\n  createWebStoragePersistence,\n  loadSnapshot,\n  type Persistence,\n  type PersistentEngineOptions,\n  persistEngine,\n  type WebStorageLike,\n} from './persist'\nexport {\n  type Cursor,\n  createMemoryHub,\n  createMutationLog,\n  createSyncEngine,\n  type MutationLog,\n  type Op,\n  type SyncEngine,\n  type SyncEngineOptions,\n  type SyncSnapshot,\n  type SyncTransport,\n} from './sync'\nexport {\n  type VersionVector,\n  vvDominates,\n  vvEquals,\n  vvGet,\n  vvMerge,\n  vvObserve,\n} from './version-vector'\n\nexport type { Maturity, PackageInfo }\nexport { NotImplementedError, notImplemented }\n"],"mappings":";;;;;;;;;;;AAoBA,MAAa,OAAO;;AAGpB,MAAa,UAAU;;AAGvB,MAAa,WAAqB;;;;;;AAOlC,MAAa,OAAoB,OAAO,OAAO;CAAE;CAAM,SAAS;CAAS;AAAS,CAAC"}

package/dist/persist.d.ts

@@ -1,16 +1,6 @@
+import { SyncEngine, SyncEngineOptions, SyncSnapshot } from "./sync.js";
+
 //#region src/persist.d.ts
-/**
- * Persistence (10F) — a minimal async key/value capability so a Continuum replica
- * survives restart (mirrors the CLI's `FileSystem` / Pulse's `UpdateStorage`). Persist a
- * sync engine's {@link "./sync".SyncEngine.export snapshot} through any `Persistence`
- * and restore it on next launch, so `seq` survives and op ids never collide.
- *
- * `createMemoryPersistence` is the reference; `localStorage`/IndexedDB (web) and native
- * SQLite are research-track adapters (see STATUS). See
- * `docs/adr/0016-continuum-server-persistence.md`.
- *
- * @module
- */
 /** A minimal async key/value store for persisting Continuum state. */
 interface Persistence {
   /** Read a value, or `null` if absent. */
@@ -20,6 +10,40 @@ interface Persistence {
 }
 /** An in-memory reference {@link Persistence} for tests and as a contract example. */
 declare function createMemoryPersistence(): Persistence;
+/** The synchronous Web Storage shape (`localStorage`/`sessionStorage`), injected so this stays DOM-free. */
+interface WebStorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+/**
+ * Adapt a Web Storage (`localStorage`/`sessionStorage`) to {@link Persistence}. Inject the storage
+ * (`createWebStoragePersistence(localStorage)`) rather than reaching for a global, so it runs in any
+ * environment and tests. Storage is synchronous; the async contract is satisfied trivially.
+ */
+declare function createWebStoragePersistence(storage: WebStorageLike): Persistence;
+/** Load + parse a persisted {@link SyncSnapshot}, or `undefined` if absent / unparseable. */
+declare function loadSnapshot<T>(persistence: Persistence, key: string): Promise<SyncSnapshot<T> | undefined>;
+/**
+ * Wrap a {@link SyncEngine} so every mutation (`set`/`delete`) and `sync()` auto-saves its snapshot
+ * to `persistence` under `key`. Saves are SERIALIZED (chained) so a burst of edits can't write an
+ * older snapshot last, and failures are swallowed (best-effort durability never breaks a mutation).
+ * To RESTORE on next launch, pass `snapshot: await loadSnapshot(...)` into the engine first —
+ * {@link createPersistentEngine} does both.
+ */
+declare function persistEngine<T>(engine: SyncEngine<T>, persistence: Persistence, key: string): SyncEngine<T>;
+/** Options for {@link createPersistentEngine}: a {@link SyncEngineOptions} minus `snapshot` (loaded here). */
+interface PersistentEngineOptions<T> extends Omit<SyncEngineOptions<T>, 'snapshot'> {
+  /** Where to persist. */
+  readonly persistence: Persistence;
+  /** The storage key for this replica's snapshot. */
+  readonly key: string;
+}
+/**
+ * Create a durable {@link SyncEngine}: restore the persisted snapshot (so `seq`/HLC survive and op
+ * ids never collide across restarts), then auto-save on every change. One call for a replica that
+ * survives restart.
+ */
+declare function createPersistentEngine<T>(options: PersistentEngineOptions<T>): Promise<SyncEngine<T>>;
 //#endregion
-export { Persistence, createMemoryPersistence };
+export { Persistence, PersistentEngineOptions, WebStorageLike, createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine };
 //# sourceMappingURL=persist.d.ts.map

package/dist/persist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persist.d.ts","names":[],"sources":["../src/persist.ts"],"mappings":";;AAcA;;;;;;;;;;;;UAAiB,WAAA;EAQD;EANd,IAAA,CAAK,GAAA,WAAc,OAAA;;EAEnB,IAAA,CAAK,GAAA,UAAa,KAAA,WAAgB,OAAO;AAAA;;iBAI3B,uBAAA,IAA2B,WAAW"}
+{"version":3,"file":"persist.d.ts","names":[],"sources":["../src/persist.ts"],"mappings":";;;;UAqBiB,WAAA;EAI0B;EAFzC,IAAA,CAAK,GAAA,WAAc,OAAA;EAMkB;EAJrC,IAAA,CAAK,GAAA,UAAa,KAAA,WAAgB,OAAO;AAAA;AAIW;AAAA,iBAAtC,uBAAA,IAA2B,WAAW;;UAYrC,cAAA;EACf,OAAA,CAAQ,GAAA;EACR,OAAA,CAAQ,GAAA,UAAa,KAAA;AAAA;;;;;AAAa;iBAQpB,2BAAA,CAA4B,OAAA,EAAS,cAAA,GAAiB,WAAW;;iBAW3D,YAAA,IACpB,WAAA,EAAa,WAAA,EACb,GAAA,WACC,OAAA,CAAQ,YAAA,CAAa,CAAA;;;;;;AAdyD;AAWjF;iBAqBgB,aAAA,IACd,MAAA,EAAQ,UAAA,CAAW,CAAA,GACnB,WAAA,EAAa,WAAA,EACb,GAAA,WACC,UAAA,CAAW,CAAA;;UA+BG,uBAAA,YAAmC,IAAA,CAAK,iBAAA,CAAkB,CAAA;EArDnD;EAAA,SAuDb,WAAA,EAAa,WAAA;EAvDrB;EAAA,SAyDQ,GAAA;AAAA;;;;;;iBAQW,sBAAA,IACpB,OAAA,EAAS,uBAAA,CAAwB,CAAA,IAChC,OAAA,CAAQ,UAAA,CAAW,CAAA"}

package/dist/persist.js

@@ -1,4 +1,17 @@
+import { createSyncEngine } from "./sync.js";
 //#region src/persist.ts
+/**
+* Persistence (10F) — a minimal async key/value capability so a Continuum replica
+* survives restart (mirrors the CLI's `FileSystem` / Pulse's `UpdateStorage`). Persist a
+* sync engine's {@link "./sync".SyncEngine.export snapshot} through any `Persistence`
+* and restore it on next launch, so `seq` survives and op ids never collide.
+*
+* `createMemoryPersistence` is the reference; `createWebStoragePersistence` adapts a Web Storage
+* (`localStorage`/`sessionStorage`); {@link persistEngine} wires auto-save + restore so a replica is
+* durable with one call. See `docs/adr/0016-continuum-server-persistence.md`.
+*
+* @module
+*/
 /** An in-memory reference {@link Persistence} for tests and as a contract example. */
 function createMemoryPersistence() {
 	const store = /* @__PURE__ */ new Map();
@@ -10,7 +23,75 @@ function createMemoryPersistence() {
 		}
 	};
 }
+/**
+* Adapt a Web Storage (`localStorage`/`sessionStorage`) to {@link Persistence}. Inject the storage
+* (`createWebStoragePersistence(localStorage)`) rather than reaching for a global, so it runs in any
+* environment and tests. Storage is synchronous; the async contract is satisfied trivially.
+*/
+function createWebStoragePersistence(storage) {
+	return {
+		load: (key) => Promise.resolve(storage.getItem(key)),
+		save: (key, value) => {
+			storage.setItem(key, value);
+			return Promise.resolve();
+		}
+	};
+}
+/** Load + parse a persisted {@link SyncSnapshot}, or `undefined` if absent / unparseable. */
+async function loadSnapshot(persistence, key) {
+	const raw = await persistence.load(key);
+	if (raw === null) return void 0;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return;
+	}
+}
+/**
+* Wrap a {@link SyncEngine} so every mutation (`set`/`delete`) and `sync()` auto-saves its snapshot
+* to `persistence` under `key`. Saves are SERIALIZED (chained) so a burst of edits can't write an
+* older snapshot last, and failures are swallowed (best-effort durability never breaks a mutation).
+* To RESTORE on next launch, pass `snapshot: await loadSnapshot(...)` into the engine first —
+* {@link createPersistentEngine} does both.
+*/
+function persistEngine(engine, persistence, key) {
+	let chain = Promise.resolve();
+	const save = () => {
+		const snapshot = JSON.stringify(engine.export());
+		chain = chain.then(() => persistence.save(key, snapshot)).then(() => void 0, () => void 0);
+	};
+	return {
+		...engine,
+		set(collection, recordId, value) {
+			const op = engine.set(collection, recordId, value);
+			save();
+			return op;
+		},
+		delete(collection, recordId) {
+			const op = engine.delete(collection, recordId);
+			save();
+			return op;
+		},
+		async sync(signal) {
+			await engine.sync(signal);
+			save();
+		}
+	};
+}
+/**
+* Create a durable {@link SyncEngine}: restore the persisted snapshot (so `seq`/HLC survive and op
+* ids never collide across restarts), then auto-save on every change. One call for a replica that
+* survives restart.
+*/
+async function createPersistentEngine(options) {
+	const { persistence, key, ...syncOptions } = options;
+	const snapshot = await loadSnapshot(persistence, key);
+	return persistEngine(createSyncEngine(snapshot ? {
+		...syncOptions,
+		snapshot
+	} : syncOptions), persistence, key);
+}
 //#endregion
-export { createMemoryPersistence };
+export { createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine };
 
 //# sourceMappingURL=persist.js.map

package/dist/persist.js.map

@@ -1 +1 @@
-{"version":3,"file":"persist.js","names":[],"sources":["../src/persist.ts"],"sourcesContent":["/**\n * Persistence (10F) — a minimal async key/value capability so a Continuum replica\n * survives restart (mirrors the CLI's `FileSystem` / Pulse's `UpdateStorage`). Persist a\n * sync engine's {@link \"./sync\".SyncEngine.export snapshot} through any `Persistence`\n * and restore it on next launch, so `seq` survives and op ids never collide.\n *\n * `createMemoryPersistence` is the reference; `localStorage`/IndexedDB (web) and native\n * SQLite are research-track adapters (see STATUS). See\n * `docs/adr/0016-continuum-server-persistence.md`.\n *\n * @module\n */\n\n/** A minimal async key/value store for persisting Continuum state. */\nexport interface Persistence {\n  /** Read a value, or `null` if absent. */\n  load(key: string): Promise<string | null>\n  /** Write a value. */\n  save(key: string, value: string): Promise<void>\n}\n\n/** An in-memory reference {@link Persistence} for tests and as a contract example. */\nexport function createMemoryPersistence(): Persistence {\n  const store = new Map<string, string>()\n  return {\n    load: (key) => Promise.resolve(store.get(key) ?? null),\n    save: (key, value) => {\n      store.set(key, value)\n      return Promise.resolve()\n    },\n  }\n}\n"],"mappings":";;AAsBA,SAAgB,0BAAuC;CACrD,MAAM,wBAAQ,IAAI,IAAoB;CACtC,OAAO;EACL,OAAO,QAAQ,QAAQ,QAAQ,MAAM,IAAI,GAAG,KAAK,IAAI;EACrD,OAAO,KAAK,UAAU;GACpB,MAAM,IAAI,KAAK,KAAK;GACpB,OAAO,QAAQ,QAAQ;EACzB;CACF;AACF"}
+{"version":3,"file":"persist.js","names":[],"sources":["../src/persist.ts"],"sourcesContent":["/**\n * Persistence (10F) — a minimal async key/value capability so a Continuum replica\n * survives restart (mirrors the CLI's `FileSystem` / Pulse's `UpdateStorage`). Persist a\n * sync engine's {@link \"./sync\".SyncEngine.export snapshot} through any `Persistence`\n * and restore it on next launch, so `seq` survives and op ids never collide.\n *\n * `createMemoryPersistence` is the reference; `createWebStoragePersistence` adapts a Web Storage\n * (`localStorage`/`sessionStorage`); {@link persistEngine} wires auto-save + restore so a replica is\n * durable with one call. See `docs/adr/0016-continuum-server-persistence.md`.\n *\n * @module\n */\n\nimport {\n  createSyncEngine,\n  type SyncEngine,\n  type SyncEngineOptions,\n  type SyncSnapshot,\n} from './sync'\n\n/** A minimal async key/value store for persisting Continuum state. */\nexport interface Persistence {\n  /** Read a value, or `null` if absent. */\n  load(key: string): Promise<string | null>\n  /** Write a value. */\n  save(key: string, value: string): Promise<void>\n}\n\n/** An in-memory reference {@link Persistence} for tests and as a contract example. */\nexport function createMemoryPersistence(): Persistence {\n  const store = new Map<string, string>()\n  return {\n    load: (key) => Promise.resolve(store.get(key) ?? null),\n    save: (key, value) => {\n      store.set(key, value)\n      return Promise.resolve()\n    },\n  }\n}\n\n/** The synchronous Web Storage shape (`localStorage`/`sessionStorage`), injected so this stays DOM-free. */\nexport interface WebStorageLike {\n  getItem(key: string): string | null\n  setItem(key: string, value: string): void\n}\n\n/**\n * Adapt a Web Storage (`localStorage`/`sessionStorage`) to {@link Persistence}. Inject the storage\n * (`createWebStoragePersistence(localStorage)`) rather than reaching for a global, so it runs in any\n * environment and tests. Storage is synchronous; the async contract is satisfied trivially.\n */\nexport function createWebStoragePersistence(storage: WebStorageLike): Persistence {\n  return {\n    load: (key) => Promise.resolve(storage.getItem(key)),\n    save: (key, value) => {\n      storage.setItem(key, value)\n      return Promise.resolve()\n    },\n  }\n}\n\n/** Load + parse a persisted {@link SyncSnapshot}, or `undefined` if absent / unparseable. */\nexport async function loadSnapshot<T>(\n  persistence: Persistence,\n  key: string,\n): Promise<SyncSnapshot<T> | undefined> {\n  const raw = await persistence.load(key)\n  if (raw === null) return undefined\n  try {\n    return JSON.parse(raw) as SyncSnapshot<T>\n  } catch {\n    // A corrupt/partial blob must not wedge startup — start fresh rather than throw.\n    return undefined\n  }\n}\n\n/**\n * Wrap a {@link SyncEngine} so every mutation (`set`/`delete`) and `sync()` auto-saves its snapshot\n * to `persistence` under `key`. Saves are SERIALIZED (chained) so a burst of edits can't write an\n * older snapshot last, and failures are swallowed (best-effort durability never breaks a mutation).\n * To RESTORE on next launch, pass `snapshot: await loadSnapshot(...)` into the engine first —\n * {@link createPersistentEngine} does both.\n */\nexport function persistEngine<T>(\n  engine: SyncEngine<T>,\n  persistence: Persistence,\n  key: string,\n): SyncEngine<T> {\n  let chain: Promise<void> = Promise.resolve()\n  const save = (): void => {\n    const snapshot = JSON.stringify(engine.export())\n    chain = chain\n      .then(() => persistence.save(key, snapshot))\n      .then(\n        () => undefined,\n        () => undefined,\n      )\n  }\n  return {\n    ...engine,\n    set(collection, recordId, value) {\n      const op = engine.set(collection, recordId, value)\n      save()\n      return op\n    },\n    delete(collection, recordId) {\n      const op = engine.delete(collection, recordId)\n      save()\n      return op\n    },\n    async sync(signal) {\n      await engine.sync(signal)\n      save()\n    },\n  }\n}\n\n/** Options for {@link createPersistentEngine}: a {@link SyncEngineOptions} minus `snapshot` (loaded here). */\nexport interface PersistentEngineOptions<T> extends Omit<SyncEngineOptions<T>, 'snapshot'> {\n  /** Where to persist. */\n  readonly persistence: Persistence\n  /** The storage key for this replica's snapshot. */\n  readonly key: string\n}\n\n/**\n * Create a durable {@link SyncEngine}: restore the persisted snapshot (so `seq`/HLC survive and op\n * ids never collide across restarts), then auto-save on every change. One call for a replica that\n * survives restart.\n */\nexport async function createPersistentEngine<T>(\n  options: PersistentEngineOptions<T>,\n): Promise<SyncEngine<T>> {\n  const { persistence, key, ...syncOptions } = options\n  const snapshot = await loadSnapshot<T>(persistence, key)\n  const engine = createSyncEngine<T>(snapshot ? { ...syncOptions, snapshot } : syncOptions)\n  return persistEngine(engine, persistence, key)\n}\n"],"mappings":";;;;;;;;;;;;;;;AA6BA,SAAgB,0BAAuC;CACrD,MAAM,wBAAQ,IAAI,IAAoB;CACtC,OAAO;EACL,OAAO,QAAQ,QAAQ,QAAQ,MAAM,IAAI,GAAG,KAAK,IAAI;EACrD,OAAO,KAAK,UAAU;GACpB,MAAM,IAAI,KAAK,KAAK;GACpB,OAAO,QAAQ,QAAQ;EACzB;CACF;AACF;;;;;;AAaA,SAAgB,4BAA4B,SAAsC;CAChF,OAAO;EACL,OAAO,QAAQ,QAAQ,QAAQ,QAAQ,QAAQ,GAAG,CAAC;EACnD,OAAO,KAAK,UAAU;GACpB,QAAQ,QAAQ,KAAK,KAAK;GAC1B,OAAO,QAAQ,QAAQ;EACzB;CACF;AACF;;AAGA,eAAsB,aACpB,aACA,KACsC;CACtC,MAAM,MAAM,MAAM,YAAY,KAAK,GAAG;CACtC,IAAI,QAAQ,MAAM,OAAO,KAAA;CACzB,IAAI;EACF,OAAO,KAAK,MAAM,GAAG;CACvB,QAAQ;EAEN;CACF;AACF;;;;;;;;AASA,SAAgB,cACd,QACA,aACA,KACe;CACf,IAAI,QAAuB,QAAQ,QAAQ;CAC3C,MAAM,aAAmB;EACvB,MAAM,WAAW,KAAK,UAAU,OAAO,OAAO,CAAC;EAC/C,QAAQ,MACL,WAAW,YAAY,KAAK,KAAK,QAAQ,CAAC,EAC1C,WACO,KAAA,SACA,KAAA,CACR;CACJ;CACA,OAAO;EACL,GAAG;EACH,IAAI,YAAY,UAAU,OAAO;GAC/B,MAAM,KAAK,OAAO,IAAI,YAAY,UAAU,KAAK;GACjD,KAAK;GACL,OAAO;EACT;EACA,OAAO,YAAY,UAAU;GAC3B,MAAM,KAAK,OAAO,OAAO,YAAY,QAAQ;GAC7C,KAAK;GACL,OAAO;EACT;EACA,MAAM,KAAK,QAAQ;GACjB,MAAM,OAAO,KAAK,MAAM;GACxB,KAAK;EACP;CACF;AACF;;;;;;AAeA,eAAsB,uBACpB,SACwB;CACxB,MAAM,EAAE,aAAa,KAAK,GAAG,gBAAgB;CAC7C,MAAM,WAAW,MAAM,aAAgB,aAAa,GAAG;CAEvD,OAAO,cADQ,iBAAoB,WAAW;EAAE,GAAG;EAAa;CAAS,IAAI,WACnD,GAAG,aAAa,GAAG;AAC/C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindees/data",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MindeesNative Continuum - local-first reactive store and sync: a signals-native document store with fine-grained reactive queries, optimistic updates, CRDT conflict resolution, and delta sync.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -27,7 +27,7 @@
     "directory": "packages/data"
   },
   "dependencies": {
-    "@mindees/core": "0.4.0"
+    "@mindees/core": "0.5.0"
   },
   "devDependencies": {
     "fast-check": "4.8.0"