@mindees/data 0.1.0

package/LICENSE

@@ -0,0 +1,31 @@
+# License
+
+MindeesNative is dual-licensed under either of:
+
+- **Apache License, Version 2.0** ([LICENSE-APACHE](./LICENSE-APACHE) or
+  <https://www.apache.org/licenses/LICENSE-2.0>)
+- **MIT license** ([LICENSE-MIT](./LICENSE-MIT) or
+  <https://opensource.org/licenses/MIT>)
+
+at your option.
+
+This `MIT OR Apache-2.0` dual-license is the same model used by the Rust
+ecosystem and many modern open-source projects. It gives downstream users
+maximum flexibility: the MIT option is short and permissive, while the Apache
+option adds an explicit patent grant.
+
+## SPDX identifier
+
+```
+SPDX-License-Identifier: MIT OR Apache-2.0
+```
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the Apache-2.0
+license, shall be dual-licensed as above, without any additional terms or
+conditions.
+
+Contributions are accepted under the **Developer Certificate of Origin (DCO)**.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on signing off your commits.

package/README.md

@@ -0,0 +1,70 @@
+# @mindees/data
+
+**Continuum** — a local-first reactive store + sync for MindeesNative.
+
+> Status: 🧪 **Experimental** — Continuum Phases 10A–10F are implemented and tested:
+> the reactive document store, Hybrid Logical Clock causality, CRDT conflict resolution
+> (per-field LWW + add-wins OR-Set), a local-first delta-sync engine where two peers
+> converge offline, a capability-injected reference sync server, and a persistence
+> contract with export/restore. Native durable adapters, production sync hardening, and
+> CRDT-library/rich-text interop are 🔬 research tracks. See the repository
+> [STATUS.md](../../STATUS.md).
+
+## What works today
+
+`createCollection<T>()` — a reactive, in-memory collection of records keyed by `id`,
+built on `@mindees/core` signals (zero third-party dependencies):
+
+- **Fine-grained reactive reads** — `get(id)` / `has(id)` subscribe to *that record*
+  (per-record version signal); `all()` / `where(pred)` / `size()` subscribe to the
+  collection. A query is just a `() => T[]` accessor the renderer treats as a reactive
+  region, so `get`/`update` re-render exactly what changed. `snapshot()` reads
+  non-reactively.
+- **Atomic mutations** — `insert` (insert-only), `upsert`, `update(id, patch | fn)`,
+  `delete`, `clear`, and `tx(fn)` to batch many mutations into one notification.
+  Records are treated as immutable (update produces a new object).
+- **Optimistic changes** — `optimistic(fn)` applies immediately and returns
+  `{ commit(), rollback() }`; `rollback()` restores the prior state in one batch.
+- **Stable errors** — `DataError` with a `DataErrorCode`
+  (`DUPLICATE_ID` / `RECORD_NOT_FOUND` / `ID_IMMUTABLE`).
+
+The package also ships the sync and durability pieces that build on the store:
+
+- **Causality primitives** — `createClock`, HLC encode/decode/compare helpers, and
+  version vectors for drift-guarded causal ordering.
+- **CRDT conflict helpers** — per-field LWW Register/Map and add-wins OR-Set merge
+  utilities, property-tested for convergence.
+- **Delta sync** — `createSyncEngine`, `createMutationLog`, `createMemoryHub`, and the
+  `SyncTransport` contract for optimistic local writes plus push/pull/merge.
+- **Reference sync server** — `createSyncServer` from `@mindees/data/server` over an
+  injected `OpLogStore`, with a runnable `node:http` example in
+  [`examples/data-sync-server`](../../examples/data-sync-server).
+- **Persistence contract** — `Persistence`, `createMemoryPersistence`, and engine
+  `export()`/restore so replicas keep stable identity across restarts.
+
+```ts
+import { createCollection } from '@mindees/data'
+import { effect } from '@mindees/core'
+
+const todos = createCollection<{ id: string; text: string; done: boolean }>()
+todos.insert({ id: 't1', text: 'Ship Continuum', done: false })
+
+// A fine-grained reactive query — re-runs only when t1 changes:
+effect(() => console.log(todos.get('t1')?.done))
+
+todos.update('t1', { done: true }) // logs: true
+
+// Optimistic update with rollback on server reject:
+const change = todos.optimistic(() => todos.update('t1', { text: 'edited' }))
+// …later: change.commit()  // or change.rollback()
+```
+
+Design rationale: [ADR-0012](../../docs/adr/0012-continuum-reactive-store.md),
+[ADR-0013](../../docs/adr/0013-continuum-hlc-causality.md),
+[ADR-0014](../../docs/adr/0014-continuum-crdt.md),
+[ADR-0015](../../docs/adr/0015-continuum-sync-engine.md), and
+[ADR-0016](../../docs/adr/0016-continuum-server-persistence.md).
+
+## License
+
+`MIT OR Apache-2.0`

package/dist/collection.d.ts

@@ -0,0 +1,76 @@
+//#region src/collection.d.ts
+/**
+ * The Continuum reactive document store — a signals-native, in-memory collection of
+ * records keyed by `id`. Reads subscribe fine-grained (per record + per collection),
+ * mutations are atomic + coalescing, and optimistic changes can be rolled back. It is
+ * the substrate the later sub-phases extend: per-field CRDT merge (10C) operates on a
+ * record's fields, and the sync queue (10D) captures these mutations as ops.
+ *
+ * Built on `@mindees/core` signals only (zero third-party deps), using the same
+ * `signal(0, { equals: false })` notify-source idiom as core/router — so a query is
+ * just a `() => T[]` accessor the renderer already treats as a reactive region.
+ *
+ * See `docs/adr/0012-continuum-reactive-store.md`.
+ *
+ * @module
+ */
+/** A record identifier. */
+type Id = string | number;
+/** Options for {@link createCollection}. */
+interface CollectionOptions<T> {
+  /** Records to seed the collection with (ids must be unique). */
+  readonly initial?: readonly T[];
+}
+/** A handle to an optimistic change (see {@link Collection.optimistic}). */
+interface OptimisticChange {
+  /** Keep the change (drop the recorded inverse). */
+  commit(): void;
+  /** Undo the change, restoring the prior state in one batch. */
+  rollback(): void;
+}
+/** A reactive, in-memory collection of records keyed by `id`. */
+interface Collection<T extends {
+  id: Id;
+}> {
+  /** Reactively read a record by id (subscribes to that record). */
+  get(id: Id): T | undefined;
+  /** Reactively test membership (subscribes to that record). */
+  has(id: Id): boolean;
+  /** Reactively read all records (subscribes to the collection). */
+  all(): readonly T[];
+  /** Reactively read the records matching `predicate` (linear scan; subscribes to the collection). */
+  where(predicate: (record: T) => boolean): readonly T[];
+  /** Reactively read the record count (subscribes to the collection). */
+  size(): number;
+  /** A non-reactive snapshot of all records (does not subscribe). */
+  snapshot(): readonly T[];
+  /** Insert a new record. Throws `DUPLICATE_ID` if the id already exists. */
+  insert(record: T): void;
+  /** Insert or replace a record. */
+  upsert(record: T): void;
+  /**
+   * Patch an existing record (object patch or updater fn). Throws `RECORD_NOT_FOUND`
+   * if absent and `ID_IMMUTABLE` if the patch changes `id`. The updater fn must return
+   * a NEW record — do not mutate `prev` in place (it backs optimistic rollback).
+   */
+  update(id: Id, patch: Partial<T> | ((prev: T) => T)): void;
+  /** Delete a record. Returns whether it existed. */
+  delete(id: Id): boolean;
+  /** Remove every record. */
+  clear(): void;
+  /** Run several mutations as one atomic, single-notification transaction. */
+  tx<R>(fn: () => R): R;
+  /**
+   * Apply mutations now, returning a handle to `commit()` or `rollback()` them. The
+   * block is **atomic** (a throw inside `fn` rolls back its partial mutations and
+   * rethrows) and **not reentrant** (throws `OPTIMISTIC_NESTED` if nested).
+   */
+  optimistic(fn: () => void): OptimisticChange;
+}
+/** Create a reactive {@link Collection}. */
+declare function createCollection<T extends {
+  id: Id;
+}>(options?: CollectionOptions<T>): Collection<T>;
+//#endregion
+export { Collection, CollectionOptions, Id, OptimisticChange, createCollection };
+//# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","names":[],"sources":["../src/collection.ts"],"mappings":";;AAoBA;;;;AAAc;AAGd;;;;;;;;AAE+B;AAI/B;AAAA,KATY,EAAA;;UAGK,iBAAA;EAUP;EAAA,SARC,OAAA,YAAmB,CAAC;AAAA;;UAId,gBAAA;EAUP;EARR,MAAA;EAUQ;EARR,QAAQ;AAAA;;UAIO,UAAA;EAAuB,EAAA,EAAI,EAAA;AAAA;EAsB/B;EApBX,GAAA,CAAI,EAAA,EAAI,EAAA,GAAK,CAAA;EAoBS;EAlBtB,GAAA,CAAI,EAAA,EAAI,EAAA;EAkByC;EAhBjD,GAAA,aAAgB,CAAA;EAsBA;EApBhB,KAAA,CAAM,SAAA,GAAY,MAAA,EAAQ,CAAA,wBAAyB,CAAA;EA0BvB;EAxB5B,IAAA;EAwB4C;EAtB5C,QAAA,aAAqB,CAAA;EAZiB;EActC,MAAA,CAAO,MAAA,EAAQ,CAAA;EAZf;EAcA,MAAA,CAAO,MAAA,EAAQ,CAAA;EAdX;;;;;EAoBJ,MAAA,CAAO,EAAA,EAAI,EAAA,EAAI,KAAA,EAAO,OAAA,CAAQ,CAAA,MAAO,IAAA,EAAM,CAAA,KAAM,CAAA;EAhBjC;EAkBhB,MAAA,CAAO,EAAA,EAAI,EAAA;EAhBe;EAkB1B,KAAA;EAlBM;EAoBN,EAAA,IAAM,EAAA,QAAU,CAAA,GAAI,CAAA;EAlBpB;;;;;EAwBA,UAAA,CAAW,EAAA,eAAiB,gBAAA;AAAA;;iBAId,gBAAA;EAA6B,EAAA,EAAI,EAAA;AAAA,GAC/C,OAAA,GAAU,iBAAA,CAAkB,CAAA,IAC3B,UAAA,CAAW,CAAA"}

package/dist/collection.js

@@ -0,0 +1,171 @@
+import { DataError } from "./errors.js";
+import { batch, signal } from "@mindees/core";
+//#region src/collection.ts
+/**
+* The Continuum reactive document store — a signals-native, in-memory collection of
+* records keyed by `id`. Reads subscribe fine-grained (per record + per collection),
+* mutations are atomic + coalescing, and optimistic changes can be rolled back. It is
+* the substrate the later sub-phases extend: per-field CRDT merge (10C) operates on a
+* record's fields, and the sync queue (10D) captures these mutations as ops.
+*
+* Built on `@mindees/core` signals only (zero third-party deps), using the same
+* `signal(0, { equals: false })` notify-source idiom as core/router — so a query is
+* just a `() => T[]` accessor the renderer already treats as a reactive region.
+*
+* See `docs/adr/0012-continuum-reactive-store.md`.
+*
+* @module
+*/
+/** Create a reactive {@link Collection}. */
+function createCollection(options) {
+	const records = /* @__PURE__ */ new Map();
+	const recordVersions = /* @__PURE__ */ new Map();
+	const collectionVersion = signal(0, { equals: false });
+	let undoLog = null;
+	const recordVersion = (id) => {
+		let v = recordVersions.get(id);
+		if (!v) {
+			v = signal(0, { equals: false });
+			recordVersions.set(id, v);
+		}
+		return v;
+	};
+	const recordInverse = (inverse) => {
+		if (undoLog) undoLog.push(inverse);
+	};
+	const doSet = (record) => {
+		records.set(record.id, record);
+		recordVersion(record.id).update((n) => n + 1);
+		collectionVersion.update((n) => n + 1);
+	};
+	const doDelete = (id) => {
+		records.delete(id);
+		recordVersion(id).update((n) => n + 1);
+		recordVersions.delete(id);
+		collectionVersion.update((n) => n + 1);
+	};
+	if (options?.initial) for (const record of options.initial) {
+		if (records.has(record.id)) throw new DataError("DUPLICATE_ID", `duplicate id ${String(record.id)} in initial records`);
+		records.set(record.id, record);
+	}
+	return {
+		get(id) {
+			if (records.has(id)) {
+				recordVersion(id)();
+				return records.get(id);
+			}
+			collectionVersion();
+		},
+		has(id) {
+			if (records.has(id)) {
+				recordVersion(id)();
+				return true;
+			}
+			collectionVersion();
+			return false;
+		},
+		all() {
+			collectionVersion();
+			return [...records.values()];
+		},
+		where(predicate) {
+			collectionVersion();
+			const out = [];
+			for (const record of records.values()) if (predicate(record)) out.push(record);
+			return out;
+		},
+		size() {
+			collectionVersion();
+			return records.size;
+		},
+		snapshot() {
+			return [...records.values()];
+		},
+		insert(record) {
+			if (records.has(record.id)) throw new DataError("DUPLICATE_ID", `record ${String(record.id)} already exists`);
+			batch(() => {
+				recordInverse(() => doDelete(record.id));
+				doSet(record);
+			});
+		},
+		upsert(record) {
+			const prev = records.get(record.id);
+			batch(() => {
+				recordInverse(prev !== void 0 ? () => doSet(prev) : () => doDelete(record.id));
+				doSet(record);
+			});
+		},
+		update(id, patch) {
+			const prev = records.get(id);
+			if (prev === void 0) throw new DataError("RECORD_NOT_FOUND", `no record ${String(id)} to update`);
+			if (typeof patch !== "function" && "id" in patch && patch.id !== id) throw new DataError("ID_IMMUTABLE", `cannot change the id of record ${String(id)}`);
+			const next = typeof patch === "function" ? patch(prev) : {
+				...prev,
+				...patch,
+				id
+			};
+			if (next.id !== id) throw new DataError("ID_IMMUTABLE", `cannot change the id of record ${String(id)}`);
+			batch(() => {
+				recordInverse(() => doSet(prev));
+				doSet(next);
+			});
+		},
+		delete(id) {
+			const prev = records.get(id);
+			if (prev === void 0) return false;
+			batch(() => {
+				recordInverse(() => doSet(prev));
+				doDelete(id);
+			});
+			return true;
+		},
+		clear() {
+			if (records.size === 0) return;
+			const prevAll = [...records.values()];
+			batch(() => {
+				recordInverse(() => {
+					for (const record of prevAll) doSet(record);
+				});
+				for (const id of [...records.keys()]) doDelete(id);
+			});
+		},
+		tx(fn) {
+			return batch(fn);
+		},
+		optimistic(fn) {
+			if (undoLog !== null) throw new DataError("OPTIMISTIC_NESTED", "optimistic() cannot be nested");
+			const log = [];
+			const replay = () => {
+				batch(() => {
+					for (let i = log.length - 1; i >= 0; i--) log[i]?.();
+				});
+				log.length = 0;
+			};
+			undoLog = log;
+			try {
+				batch(fn);
+			} catch (error) {
+				replay();
+				throw error;
+			} finally {
+				undoLog = null;
+			}
+			let settled = false;
+			return {
+				commit() {
+					settled = true;
+					log.length = 0;
+				},
+				rollback() {
+					if (settled) return;
+					settled = true;
+					replay();
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { createCollection };
+
+//# sourceMappingURL=collection.js.map

package/dist/collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.js","names":[],"sources":["../src/collection.ts"],"sourcesContent":["/**\n * The Continuum reactive document store — a signals-native, in-memory collection of\n * records keyed by `id`. Reads subscribe fine-grained (per record + per collection),\n * mutations are atomic + coalescing, and optimistic changes can be rolled back. It is\n * the substrate the later sub-phases extend: per-field CRDT merge (10C) operates on a\n * record's fields, and the sync queue (10D) captures these mutations as ops.\n *\n * Built on `@mindees/core` signals only (zero third-party deps), using the same\n * `signal(0, { equals: false })` notify-source idiom as core/router — so a query is\n * just a `() => T[]` accessor the renderer already treats as a reactive region.\n *\n * See `docs/adr/0012-continuum-reactive-store.md`.\n *\n * @module\n */\n\nimport { batch, type Signal, signal } from '@mindees/core'\nimport { DataError } from './errors'\n\n/** A record identifier. */\nexport type Id = string | number\n\n/** Options for {@link createCollection}. */\nexport interface CollectionOptions<T> {\n  /** Records to seed the collection with (ids must be unique). */\n  readonly initial?: readonly T[]\n}\n\n/** A handle to an optimistic change (see {@link Collection.optimistic}). */\nexport interface OptimisticChange {\n  /** Keep the change (drop the recorded inverse). */\n  commit(): void\n  /** Undo the change, restoring the prior state in one batch. */\n  rollback(): void\n}\n\n/** A reactive, in-memory collection of records keyed by `id`. */\nexport interface Collection<T extends { id: Id }> {\n  /** Reactively read a record by id (subscribes to that record). */\n  get(id: Id): T | undefined\n  /** Reactively test membership (subscribes to that record). */\n  has(id: Id): boolean\n  /** Reactively read all records (subscribes to the collection). */\n  all(): readonly T[]\n  /** Reactively read the records matching `predicate` (linear scan; subscribes to the collection). */\n  where(predicate: (record: T) => boolean): readonly T[]\n  /** Reactively read the record count (subscribes to the collection). */\n  size(): number\n  /** A non-reactive snapshot of all records (does not subscribe). */\n  snapshot(): readonly T[]\n  /** Insert a new record. Throws `DUPLICATE_ID` if the id already exists. */\n  insert(record: T): void\n  /** Insert or replace a record. */\n  upsert(record: T): void\n  /**\n   * Patch an existing record (object patch or updater fn). Throws `RECORD_NOT_FOUND`\n   * if absent and `ID_IMMUTABLE` if the patch changes `id`. The updater fn must return\n   * a NEW record — do not mutate `prev` in place (it backs optimistic rollback).\n   */\n  update(id: Id, patch: Partial<T> | ((prev: T) => T)): void\n  /** Delete a record. Returns whether it existed. */\n  delete(id: Id): boolean\n  /** Remove every record. */\n  clear(): void\n  /** Run several mutations as one atomic, single-notification transaction. */\n  tx<R>(fn: () => R): R\n  /**\n   * Apply mutations now, returning a handle to `commit()` or `rollback()` them. The\n   * block is **atomic** (a throw inside `fn` rolls back its partial mutations and\n   * rethrows) and **not reentrant** (throws `OPTIMISTIC_NESTED` if nested).\n   */\n  optimistic(fn: () => void): OptimisticChange\n}\n\n/** Create a reactive {@link Collection}. */\nexport function createCollection<T extends { id: Id }>(\n  options?: CollectionOptions<T>,\n): Collection<T> {\n  const records = new Map<Id, T>()\n  const recordVersions = new Map<Id, Signal<number>>()\n  const collectionVersion = signal(0, { equals: false })\n  // When set, mutations push an inverse here (drives optimistic rollback).\n  let undoLog: Array<() => void> | null = null\n\n  const recordVersion = (id: Id): Signal<number> => {\n    let v = recordVersions.get(id)\n    if (!v) {\n      v = signal(0, { equals: false })\n      recordVersions.set(id, v)\n    }\n    return v\n  }\n\n  const recordInverse = (inverse: () => void): void => {\n    if (undoLog) undoLog.push(inverse)\n  }\n\n  // Raw write + reactivity (no inverse capture). Used by mutations and inverses alike.\n  const doSet = (record: T): void => {\n    records.set(record.id, record)\n    recordVersion(record.id).update((n) => n + 1)\n    collectionVersion.update((n) => n + 1)\n  }\n  const doDelete = (id: Id): void => {\n    records.delete(id)\n    recordVersion(id).update((n) => n + 1) // notify observers BEFORE GC\n    recordVersions.delete(id) // GC the version signal so removed records don't leak\n    collectionVersion.update((n) => n + 1)\n  }\n\n  if (options?.initial) {\n    for (const record of options.initial) {\n      if (records.has(record.id)) {\n        throw new DataError('DUPLICATE_ID', `duplicate id ${String(record.id)} in initial records`)\n      }\n      records.set(record.id, record) // no observers yet at construction — skip reactivity\n    }\n  }\n\n  return {\n    get(id) {\n      // Present id → subscribe fine-grained to that record. Absent id → subscribe to\n      // the collection version (a missing id can only appear via a mutation, which bumps\n      // it), so reads of never-existing ids never materialize a permanent per-record signal.\n      if (records.has(id)) {\n        recordVersion(id)()\n        return records.get(id)\n      }\n      collectionVersion()\n      return undefined\n    },\n    has(id) {\n      if (records.has(id)) {\n        recordVersion(id)()\n        return true\n      }\n      collectionVersion()\n      return false\n    },\n    all() {\n      collectionVersion()\n      return [...records.values()]\n    },\n    where(predicate) {\n      collectionVersion()\n      const out: T[] = []\n      for (const record of records.values()) if (predicate(record)) out.push(record)\n      return out\n    },\n    size() {\n      collectionVersion()\n      return records.size\n    },\n    snapshot() {\n      return [...records.values()]\n    },\n\n    insert(record) {\n      if (records.has(record.id)) {\n        throw new DataError('DUPLICATE_ID', `record ${String(record.id)} already exists`)\n      }\n      batch(() => {\n        recordInverse(() => doDelete(record.id))\n        doSet(record)\n      })\n    },\n\n    upsert(record) {\n      const prev = records.get(record.id)\n      batch(() => {\n        recordInverse(prev !== undefined ? () => doSet(prev) : () => doDelete(record.id))\n        doSet(record)\n      })\n    },\n\n    update(id, patch) {\n      const prev = records.get(id)\n      if (prev === undefined) {\n        throw new DataError('RECORD_NOT_FOUND', `no record ${String(id)} to update`)\n      }\n      // Reject a foreign id in either form (the object-patch spread would otherwise\n      // silently drop it, making the two forms inconsistent).\n      if (typeof patch !== 'function' && 'id' in patch && (patch as { id?: Id }).id !== id) {\n        throw new DataError('ID_IMMUTABLE', `cannot change the id of record ${String(id)}`)\n      }\n      const next =\n        typeof patch === 'function'\n          ? (patch as (p: T) => T)(prev)\n          : ({ ...prev, ...patch, id } as T)\n      if (next.id !== id) {\n        throw new DataError('ID_IMMUTABLE', `cannot change the id of record ${String(id)}`)\n      }\n      batch(() => {\n        recordInverse(() => doSet(prev))\n        doSet(next)\n      })\n    },\n\n    delete(id) {\n      const prev = records.get(id)\n      if (prev === undefined) return false\n      batch(() => {\n        recordInverse(() => doSet(prev))\n        doDelete(id)\n      })\n      return true\n    },\n\n    clear() {\n      if (records.size === 0) return\n      const prevAll = [...records.values()]\n      batch(() => {\n        recordInverse(() => {\n          for (const record of prevAll) doSet(record)\n        })\n        for (const id of [...records.keys()]) doDelete(id)\n      })\n    },\n\n    tx(fn) {\n      return batch(fn)\n    },\n\n    optimistic(fn) {\n      // Not reentrant: a nested optimistic block's inverses would not reach the outer\n      // log, so the outer rollback couldn't restore them. Fail fast instead.\n      if (undoLog !== null) {\n        throw new DataError('OPTIMISTIC_NESTED', 'optimistic() cannot be nested')\n      }\n      const log: Array<() => void> = []\n      const replay = (): void => {\n        batch(() => {\n          for (let i = log.length - 1; i >= 0; i--) log[i]?.()\n        })\n        log.length = 0\n      }\n      undoLog = log\n      try {\n        batch(fn)\n      } catch (error) {\n        // Keep optimistic application all-or-nothing: undo partial mutations, then rethrow.\n        replay()\n        throw error\n      } finally {\n        undoLog = null\n      }\n      let settled = false\n      return {\n        commit() {\n          settled = true\n          log.length = 0 // release the captured inverses (and their snapshots)\n        },\n        rollback() {\n          if (settled) return\n          settled = true\n          replay()\n        },\n      }\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+//#region src/errors.d.ts
+/**
+ * Errors for `@mindees/data` (Continuum).
+ *
+ * Every failure carries a stable {@link DataErrorCode} so callers can branch on the
+ * cause without string-matching messages.
+ *
+ * @module
+ */
+/** Stable code identifying why a Continuum operation failed. */
+type DataErrorCode = /** `insert` was given an id that already exists (use `upsert` to replace). */'DUPLICATE_ID' /** `update` referenced an id that is not in the collection. */ | 'RECORD_NOT_FOUND' /** A mutation tried to change a record's `id` (ids are immutable). */ | 'ID_IMMUTABLE' /** `optimistic()` was called inside another `optimistic()` block (not reentrant). */ | 'OPTIMISTIC_NESTED';
+/** A Continuum data error carrying a stable {@link DataErrorCode}. */
+declare class DataError extends Error {
+  /** Stable, machine-readable cause. */
+  readonly code: DataErrorCode;
+  constructor(code: DataErrorCode, message: string);
+}
+//#endregion
+export { DataError, DataErrorCode };
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"mappings":";;AAUA;;;;AAAyB;AAWzB;;;KAXY,aAAA;;cAWC,SAAA,SAAkB,KAAA;EAII;EAAA,SAFxB,IAAA,EAAM,aAAA;cAEH,IAAA,EAAM,aAAA,EAAe,OAAA;AAAA"}

package/dist/errors.js

@@ -0,0 +1,15 @@
+//#region src/errors.ts
+/** A Continuum data error carrying a stable {@link DataErrorCode}. */
+var DataError = class extends Error {
+	/** Stable, machine-readable cause. */
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "DataError";
+		this.code = code;
+	}
+};
+//#endregion
+export { DataError };
+
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Errors for `@mindees/data` (Continuum).\n *\n * Every failure carries a stable {@link DataErrorCode} so callers can branch on the\n * cause without string-matching messages.\n *\n * @module\n */\n\n/** Stable code identifying why a Continuum operation failed. */\nexport type DataErrorCode =\n  /** `insert` was given an id that already exists (use `upsert` to replace). */\n  | 'DUPLICATE_ID'\n  /** `update` referenced an id that is not in the collection. */\n  | 'RECORD_NOT_FOUND'\n  /** A mutation tried to change a record's `id` (ids are immutable). */\n  | 'ID_IMMUTABLE'\n  /** `optimistic()` was called inside another `optimistic()` block (not reentrant). */\n  | 'OPTIMISTIC_NESTED'\n\n/** A Continuum data error carrying a stable {@link DataErrorCode}. */\nexport class DataError extends Error {\n  /** Stable, machine-readable cause. */\n  readonly code: DataErrorCode\n\n  constructor(code: DataErrorCode, message: string) {\n    super(message)\n    this.name = 'DataError'\n    this.code = code\n  }\n}\n"],"mappings":";;AAqBA,IAAa,YAAb,cAA+B,MAAM;;CAEnC;CAEA,YAAY,MAAqB,SAAiB;EAChD,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;CACd;AACF"}

package/dist/hlc.d.ts

@@ -0,0 +1,79 @@
+//#region src/hlc.d.ts
+/**
+ * Hybrid Logical Clock (HLC) — the causality primitive for Continuum.
+ *
+ * An {@link Hlc} pairs physical wall-clock milliseconds with a logical counter (and the
+ * replica's `nodeId`), so it tracks real time closely yet guarantees a **monotonic,
+ * total causal order** across replicas with no coordinator (Kulkarni et al.). The
+ * physical clock is **injected**, so behavior is fully deterministic in tests.
+ *
+ * 10C tags every field write with an `Hlc` (its per-field LWW merge key); 10D ships ops
+ * ordered by it. See `docs/adr/0013-continuum-hlc-causality.md`.
+ *
+ * @module
+ */
+/** A Hybrid Logical Clock timestamp. */
+interface Hlc {
+  /** Physical wall-clock milliseconds. */
+  readonly wallMs: number;
+  /** Logical counter that breaks ties when `wallMs` does not advance. */
+  readonly counter: number;
+  /** The replica that produced this timestamp. */
+  readonly nodeId: string;
+}
+/** Options for {@link createClock}. */
+interface ClockOptions {
+  /** This replica's stable id (must be unique per replica). */
+  readonly nodeId: string;
+  /** Injected physical clock in ms. Default `() => Date.now()`. */
+  readonly now?: () => number;
+  /**
+   * Bound how far a received timestamp may push our **local** clock forward (a
+   * corrupt/skewed peer must not be able to drag our clock arbitrarily into the
+   * future). A remote beyond this bound is **clamped** when advancing our clock — it
+   * is *not* rejected, so the op's own stamp is still merged by the data layer and
+   * convergence is preserved under clock skew. Default 24h.
+   */
+  readonly maxClockDriftMs?: number;
+  /**
+   * Seed the clock's high-water mark on creation (e.g. restoring a persisted replica),
+   * so the first {@link Clock.tick} after restart is strictly greater than any stamp
+   * the replica produced before it. Without this a restored clock regresses to 0 and a
+   * post-restart edit can lose the LWW merge to its own pre-restart write.
+   */
+  readonly seed?: {
+    readonly wallMs: number;
+    readonly counter: number;
+  };
+}
+/** A per-replica Hybrid Logical Clock. */
+interface Clock {
+  /** Produce a timestamp for a new local event (or an outgoing message). */
+  tick(): Hlc;
+  /**
+   * Merge a received timestamp into the local clock; returns the new local timestamp
+   * (strictly greater than the previous local one, and greater than the remote unless
+   * the remote is beyond the drift bound, in which case its advance is clamped).
+   * Throws only on a structurally-invalid remote (non-integer/negative/non-encodable).
+   */
+  update(remote: Hlc): Hlc;
+  /** The current local timestamp without advancing the clock. */
+  peek(): Hlc;
+}
+/** Create a {@link Clock} for `nodeId`. */
+declare function createClock(options: ClockOptions): Clock;
+/** Total order over {@link Hlc}: by `wallMs`, then `counter`, then `nodeId`. */
+declare function compareHlc(a: Hlc, b: Hlc): -1 | 0 | 1;
+/**
+ * Encode an {@link Hlc} as a **lexicographically-sortable** string
+ * (`wallMs:counter:nodeId`, zero-padded), so plain string sort matches
+ * {@link compareHlc}. Throws if a field exceeds its fixed width (which would silently
+ * break the sort order) — the clock keeps both within range, so this only fires on a
+ * hand-built/decoded out-of-range value. Inverse of {@link decodeHlc}.
+ */
+declare function encodeHlc(hlc: Hlc): string;
+/** Decode a string produced by {@link encodeHlc} (a `nodeId` may itself contain `:`). */
+declare function decodeHlc(encoded: string): Hlc;
+//#endregion
+export { Clock, ClockOptions, Hlc, compareHlc, createClock, decodeHlc, encodeHlc };
+//# sourceMappingURL=hlc.d.ts.map

package/dist/hlc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hlc.d.ts","names":[],"sources":["../src/hlc.ts"],"mappings":";;AAeA;;;;;;;;AAMiB;AAIjB;;;;UAViB,GAAA;EAcN;EAAA,SAZA,MAAA;EA2BA;EAAA,SAzBA,OAAA;EAyB2C;EAAA,SAvB3C,MAAA;AAAA;AAkCX;AAAA,UA9BiB,YAAA;;WAEN,MAAA;EAqCM;EAAA,SAnCN,GAAA;EAqCD;;;;;;;EAAA,SA7BC,eAAA;EA2BY;;;;AAEV;AAIb;EANuB,SApBZ,IAAA;IAAA,SAAkB,MAAA;IAAA,SAAyB,OAAA;EAAA;AAAA;;UAWrC,KAAA;EAewC;EAbvD,IAAA,IAAQ,GAAA;EA+FgB;;;;;;EAxFxB,MAAA,CAAO,MAAA,EAAQ,GAAA,GAAM,GAAA;EAwFkB;EAtFvC,IAAA,IAAQ,GAAA;AAAA;;iBAIM,WAAA,CAAY,OAAA,EAAS,YAAA,GAAe,KAAK;;iBAkFzC,UAAA,CAAW,CAAA,EAAG,GAAA,EAAK,CAAA,EAAG,GAAG;AA6BzC;;;;AAA+C;;;AAA/C,iBAfgB,SAAA,CAAU,GAAQ,EAAH,GAAG;;iBAelB,SAAA,CAAU,OAAA,WAAkB,GAAG"}

package/dist/hlc.js

@@ -0,0 +1,95 @@
+//#region src/hlc.ts
+/** Max counter value that fits the encoded fixed width; overflow rolls into `wallMs`. */
+const MAX_COUNTER = 999999;
+const WALL_WIDTH = 15;
+const COUNTER_WIDTH = 6;
+/** Largest `wallMs` the fixed-width encoding can represent (~year 33658). */
+const MAX_WALL = 10 ** WALL_WIDTH - 1;
+/** Create a {@link Clock} for `nodeId`. */
+function createClock(options) {
+	const { nodeId } = options;
+	const physical = options.now ?? (() => Date.now());
+	const maxDriftMs = options.maxClockDriftMs ?? 1440 * 60 * 1e3;
+	const seedWall = options.seed?.wallMs;
+	const seedCounter = options.seed?.counter;
+	let wallMs = typeof seedWall === "number" && Number.isInteger(seedWall) && seedWall >= 0 && seedWall <= MAX_WALL ? seedWall : 0;
+	let counter = typeof seedCounter === "number" && Number.isInteger(seedCounter) && seedCounter >= 0 && seedCounter <= MAX_COUNTER ? seedCounter : 0;
+	const commit = (w, c) => {
+		if (c > MAX_COUNTER) {
+			wallMs = w + 1;
+			counter = 0;
+		} else {
+			wallMs = w;
+			counter = c;
+		}
+		return {
+			wallMs,
+			counter,
+			nodeId
+		};
+	};
+	return {
+		tick() {
+			const pt = physical();
+			return pt > wallMs ? commit(pt, 0) : commit(wallMs, counter + 1);
+		},
+		update(remote) {
+			const pt = physical();
+			if (!Number.isInteger(remote.wallMs) || remote.wallMs < 0 || remote.wallMs > MAX_WALL || !Number.isInteger(remote.counter) || remote.counter < 0 || remote.counter > MAX_COUNTER) throw new TypeError(`remote HLC out of bounds: ${remote.wallMs}:${remote.counter}`);
+			const ceiling = Math.max(wallMs, pt + maxDriftMs);
+			const remoteWall = Math.min(remote.wallMs, ceiling);
+			const w = Math.max(wallMs, remoteWall, pt);
+			let c;
+			if (w === wallMs && w === remoteWall) c = Math.max(counter, remote.counter) + 1;
+			else if (w === wallMs) c = counter + 1;
+			else if (w === remoteWall) c = remote.counter + 1;
+			else c = 0;
+			return commit(w, c);
+		},
+		peek() {
+			return {
+				wallMs,
+				counter,
+				nodeId
+			};
+		}
+	};
+}
+/** Total order over {@link Hlc}: by `wallMs`, then `counter`, then `nodeId`. */
+function compareHlc(a, b) {
+	if (a.wallMs !== b.wallMs) return a.wallMs < b.wallMs ? -1 : 1;
+	if (a.counter !== b.counter) return a.counter < b.counter ? -1 : 1;
+	if (a.nodeId !== b.nodeId) return a.nodeId < b.nodeId ? -1 : 1;
+	return 0;
+}
+/**
+* Encode an {@link Hlc} as a **lexicographically-sortable** string
+* (`wallMs:counter:nodeId`, zero-padded), so plain string sort matches
+* {@link compareHlc}. Throws if a field exceeds its fixed width (which would silently
+* break the sort order) — the clock keeps both within range, so this only fires on a
+* hand-built/decoded out-of-range value. Inverse of {@link decodeHlc}.
+*/
+function encodeHlc(hlc) {
+	if (!Number.isInteger(hlc.wallMs) || hlc.wallMs < 0 || hlc.wallMs > MAX_WALL) throw new RangeError(`HLC wallMs out of encodable range: ${hlc.wallMs}`);
+	if (!Number.isInteger(hlc.counter) || hlc.counter < 0 || hlc.counter > MAX_COUNTER) throw new RangeError(`HLC counter out of encodable range: ${hlc.counter}`);
+	return `${String(hlc.wallMs).padStart(WALL_WIDTH, "0")}:${String(hlc.counter).padStart(COUNTER_WIDTH, "0")}:${hlc.nodeId}`;
+}
+const DIGITS = /^\d+$/;
+/** Decode a string produced by {@link encodeHlc} (a `nodeId` may itself contain `:`). */
+function decodeHlc(encoded) {
+	const first = encoded.indexOf(":");
+	const second = encoded.indexOf(":", first + 1);
+	if (first === -1 || second === -1) throw new TypeError(`invalid encoded HLC: ${encoded}`);
+	const wall = encoded.slice(0, first);
+	const counter = encoded.slice(first + 1, second);
+	if (!DIGITS.test(wall) || !DIGITS.test(counter)) throw new TypeError(`invalid encoded HLC numeric field: ${encoded}`);
+	return {
+		wallMs: Number(wall),
+		counter: Number(counter),
+		nodeId: encoded.slice(second + 1)
+	};
+}
+//#endregion
+export { compareHlc, createClock, decodeHlc, encodeHlc };
+
+//# sourceMappingURL=hlc.js.map

package/dist/hlc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hlc.js","names":[],"sources":["../src/hlc.ts"],"sourcesContent":["/**\n * Hybrid Logical Clock (HLC) — the causality primitive for Continuum.\n *\n * An {@link Hlc} pairs physical wall-clock milliseconds with a logical counter (and the\n * replica's `nodeId`), so it tracks real time closely yet guarantees a **monotonic,\n * total causal order** across replicas with no coordinator (Kulkarni et al.). The\n * physical clock is **injected**, so behavior is fully deterministic in tests.\n *\n * 10C tags every field write with an `Hlc` (its per-field LWW merge key); 10D ships ops\n * ordered by it. See `docs/adr/0013-continuum-hlc-causality.md`.\n *\n * @module\n */\n\n/** A Hybrid Logical Clock timestamp. */\nexport interface Hlc {\n  /** Physical wall-clock milliseconds. */\n  readonly wallMs: number\n  /** Logical counter that breaks ties when `wallMs` does not advance. */\n  readonly counter: number\n  /** The replica that produced this timestamp. */\n  readonly nodeId: string\n}\n\n/** Options for {@link createClock}. */\nexport interface ClockOptions {\n  /** This replica's stable id (must be unique per replica). */\n  readonly nodeId: string\n  /** Injected physical clock in ms. Default `() => Date.now()`. */\n  readonly now?: () => number\n  /**\n   * Bound how far a received timestamp may push our **local** clock forward (a\n   * corrupt/skewed peer must not be able to drag our clock arbitrarily into the\n   * future). A remote beyond this bound is **clamped** when advancing our clock — it\n   * is *not* rejected, so the op's own stamp is still merged by the data layer and\n   * convergence is preserved under clock skew. Default 24h.\n   */\n  readonly maxClockDriftMs?: number\n  /**\n   * Seed the clock's high-water mark on creation (e.g. restoring a persisted replica),\n   * so the first {@link Clock.tick} after restart is strictly greater than any stamp\n   * the replica produced before it. Without this a restored clock regresses to 0 and a\n   * post-restart edit can lose the LWW merge to its own pre-restart write.\n   */\n  readonly seed?: { readonly wallMs: number; readonly counter: number }\n}\n\n/** Max counter value that fits the encoded fixed width; overflow rolls into `wallMs`. */\nconst MAX_COUNTER = 999_999\nconst WALL_WIDTH = 15\nconst COUNTER_WIDTH = 6\n/** Largest `wallMs` the fixed-width encoding can represent (~year 33658). */\nconst MAX_WALL = 10 ** WALL_WIDTH - 1\n\n/** A per-replica Hybrid Logical Clock. */\nexport interface Clock {\n  /** Produce a timestamp for a new local event (or an outgoing message). */\n  tick(): Hlc\n  /**\n   * Merge a received timestamp into the local clock; returns the new local timestamp\n   * (strictly greater than the previous local one, and greater than the remote unless\n   * the remote is beyond the drift bound, in which case its advance is clamped).\n   * Throws only on a structurally-invalid remote (non-integer/negative/non-encodable).\n   */\n  update(remote: Hlc): Hlc\n  /** The current local timestamp without advancing the clock. */\n  peek(): Hlc\n}\n\n/** Create a {@link Clock} for `nodeId`. */\nexport function createClock(options: ClockOptions): Clock {\n  const { nodeId } = options\n  const physical = options.now ?? (() => Date.now())\n  const maxDriftMs = options.maxClockDriftMs ?? 24 * 60 * 60 * 1000\n  // Seed the high-water mark (sanitized — a corrupt snapshot must not break the clock).\n  const seedWall = options.seed?.wallMs\n  const seedCounter = options.seed?.counter\n  let wallMs =\n    typeof seedWall === 'number' &&\n    Number.isInteger(seedWall) &&\n    seedWall >= 0 &&\n    seedWall <= MAX_WALL\n      ? seedWall\n      : 0\n  let counter =\n    typeof seedCounter === 'number' &&\n    Number.isInteger(seedCounter) &&\n    seedCounter >= 0 &&\n    seedCounter <= MAX_COUNTER\n      ? seedCounter\n      : 0\n\n  // Commit (wall, candidateCounter), rolling a logical-counter overflow into wall time\n  // so the counter stays within its fixed encoding width while monotonicity holds.\n  const commit = (w: number, c: number): Hlc => {\n    if (c > MAX_COUNTER) {\n      wallMs = w + 1\n      counter = 0\n    } else {\n      wallMs = w\n      counter = c\n    }\n    return { wallMs, counter, nodeId }\n  }\n\n  return {\n    tick(): Hlc {\n      const pt = physical()\n      return pt > wallMs ? commit(pt, 0) : commit(wallMs, counter + 1)\n    },\n\n    update(remote: Hlc): Hlc {\n      const pt = physical()\n      // Reject only a STRUCTURALLY-invalid remote (non-integer/negative, or beyond the\n      // fixed encodable range) — such a stamp can never be ordered or stored, so the\n      // caller skips that op. A merely far-future *but representable* remote is NOT\n      // rejected here: the data merge (mergeRegister) is independent of our clock, so\n      // dropping it would break CRDT convergence. We instead CLAMP how far it advances\n      // our local clock (below) to keep the clock from being poisoned.\n      if (\n        !Number.isInteger(remote.wallMs) ||\n        remote.wallMs < 0 ||\n        remote.wallMs > MAX_WALL ||\n        !Number.isInteger(remote.counter) ||\n        remote.counter < 0 ||\n        remote.counter > MAX_COUNTER\n      ) {\n        throw new TypeError(`remote HLC out of bounds: ${remote.wallMs}:${remote.counter}`)\n      }\n      // Clock-poisoning guard: never let a remote push our local clock more than\n      // maxDriftMs beyond PHYSICAL time. Anchoring to `pt + maxDriftMs` (not\n      // `wallMs + maxDriftMs`) means repeated far-future merges can't ratchet the clock\n      // forward — each is clamped to the same ceiling. The `max(wallMs, …)` floor keeps a\n      // stamp at/below our current clock always adopted (it advances nothing).\n      const ceiling = Math.max(wallMs, pt + maxDriftMs)\n      const remoteWall = Math.min(remote.wallMs, ceiling)\n      const w = Math.max(wallMs, remoteWall, pt)\n      let c: number\n      if (w === wallMs && w === remoteWall) c = Math.max(counter, remote.counter) + 1\n      else if (w === wallMs) c = counter + 1\n      else if (w === remoteWall) c = remote.counter + 1\n      else c = 0\n      return commit(w, c)\n    },\n\n    peek(): Hlc {\n      return { wallMs, counter, nodeId }\n    },\n  }\n}\n\n/** Total order over {@link Hlc}: by `wallMs`, then `counter`, then `nodeId`. */\nexport function compareHlc(a: Hlc, b: Hlc): -1 | 0 | 1 {\n  if (a.wallMs !== b.wallMs) return a.wallMs < b.wallMs ? -1 : 1\n  if (a.counter !== b.counter) return a.counter < b.counter ? -1 : 1\n  if (a.nodeId !== b.nodeId) return a.nodeId < b.nodeId ? -1 : 1\n  return 0\n}\n\n/**\n * Encode an {@link Hlc} as a **lexicographically-sortable** string\n * (`wallMs:counter:nodeId`, zero-padded), so plain string sort matches\n * {@link compareHlc}. Throws if a field exceeds its fixed width (which would silently\n * break the sort order) — the clock keeps both within range, so this only fires on a\n * hand-built/decoded out-of-range value. Inverse of {@link decodeHlc}.\n */\nexport function encodeHlc(hlc: Hlc): string {\n  if (!Number.isInteger(hlc.wallMs) || hlc.wallMs < 0 || hlc.wallMs > MAX_WALL) {\n    throw new RangeError(`HLC wallMs out of encodable range: ${hlc.wallMs}`)\n  }\n  if (!Number.isInteger(hlc.counter) || hlc.counter < 0 || hlc.counter > MAX_COUNTER) {\n    throw new RangeError(`HLC counter out of encodable range: ${hlc.counter}`)\n  }\n  const wall = String(hlc.wallMs).padStart(WALL_WIDTH, '0')\n  const counter = String(hlc.counter).padStart(COUNTER_WIDTH, '0')\n  return `${wall}:${counter}:${hlc.nodeId}`\n}\n\nconst DIGITS = /^\\d+$/\n\n/** Decode a string produced by {@link encodeHlc} (a `nodeId` may itself contain `:`). */\nexport function decodeHlc(encoded: string): Hlc {\n  const first = encoded.indexOf(':')\n  const second = encoded.indexOf(':', first + 1)\n  if (first === -1 || second === -1) {\n    throw new TypeError(`invalid encoded HLC: ${encoded}`)\n  }\n  const wall = encoded.slice(0, first)\n  const counter = encoded.slice(first + 1, second)\n  if (!DIGITS.test(wall) || !DIGITS.test(counter)) {\n    throw new TypeError(`invalid encoded HLC numeric field: ${encoded}`)\n  }\n  return { wallMs: Number(wall), counter: Number(counter), nodeId: encoded.slice(second + 1) }\n}\n"],"mappings":"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"}