@lunora/replica 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/packem_shared/{LocalMirror-GeJ26eNe.mjs → LocalMirror-a-5jEqFN.mjs}

@@ -1,6 +1,6 @@
 import { createSqlJsAdapter } from '../adapters/sqljs.mjs';
 import { applyDiffToDb as applyDiffToDatabase, escapeIdentifier } from './applyDiffToDb-DQ1xZp5J.mjs';
-import { EventLog } from './EventLog-zMy7AYP4.mjs';
+import { EventLog } from './EventLog-CnK-3Wge.mjs';
 
 const MIRROR_META_TABLE = "__lunora_mirror_meta";
 const ensureMetaTable = (database) => {
@@ -14,8 +14,16 @@ const ensureMetaTable = (database) => {
 class LocalMirror {
   #db;
   #tables;
-  #eventLog = new EventLog();
+  #eventLog;
   #changeListeners = /* @__PURE__ */ new Set();
+  /**
+   * Monotonically increasing counter bumped on every state-changing
+   * operation (`applyDiff`, `clearData`) — independent of `eventLog.size`.
+   * `clearData` doesn't grow the log (REPLICA-09), so a consumer that used
+   * `eventLog.size` as its `useSyncExternalStore` snapshot would never
+   * re-render after a clear; `version` changes on both operations.
+   */
+  #version = 0;
   /**
    * Convenience factory that creates a {@link LocalMirror} backed by a
    * {@link createSqlJsAdapter sql.js adapter} without needing to import
@@ -40,6 +48,7 @@ class LocalMirror {
   constructor(options) {
     this.#db = options.db;
     this.#tables = { ...options.tables };
+    this.#eventLog = new EventLog({ maxEntries: options.maxEventLogEntries });
     ensureMetaTable(this.#db);
   }
   /**
@@ -68,6 +77,15 @@ class LocalMirror {
   get db() {
     return this.#db;
   }
+  /**
+   * Monotonically increasing version counter, bumped on every operation
+   * that changes mirrored data (`applyDiff`, `clearData`). Use this — not
+   * `eventLog.size` — as a `useSyncExternalStore` snapshot so operations
+   * that don't append to the log still trigger a re-render.
+   */
+  get version() {
+    return this.#version;
+  }
   /**
    * Apply a server-side diff to the local SQLite mirror.
    *
@@ -82,6 +100,7 @@ class LocalMirror {
     this.#ensureTableSchema(diff);
     applyDiffToDatabase(this.#db, diff, pkColumn);
     this.#eventLog.append("table-diff", diff, [diff]);
+    this.#version += 1;
     for (const listener of this.#changeListeners) {
       try {
         listener();
@@ -106,16 +125,28 @@ class LocalMirror {
   /**
    * Delete every row from all known tables (preserves the event log
    * and schema). Useful when re-syncing from scratch.
+   *
+   * Notifies `onChange` subscribers and bumps {@link LocalMirror.version}
+   * (REPLICA-09) even though nothing is appended to the event log — a
+   * consumer keyed only on `eventLog.size` would otherwise never learn the
+   * mirror was cleared and keep rendering deleted rows.
    */
   clearData() {
     const tables = this.#db.query(
-      `SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '__lunora_%' AND name NOT LIKE 'sqlite_%'`
+      String.raw`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '\_\_lunora\_%' ESCAPE '\' AND name NOT LIKE 'sqlite\_%' ESCAPE '\'`
     );
     this.#db.transaction(() => {
       for (const { name } of tables) {
         this.#db.exec(`DELETE FROM ${escapeIdentifier(name)}`);
       }
     });
+    this.#version += 1;
+    for (const listener of this.#changeListeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
   }
   /**
    * Dispose the mirror and close the database connection.

package/dist/packem_shared/{MaterializerRuntime-HqNXqJxp.mjs → MaterializerRuntime-BoIrsMYB.mjs}

@@ -22,50 +22,60 @@ class MaterializerRuntime {
   #doClient;
   #unknownEventHandling;
   /**
-   * The highest event seq that has been applied to all materializers.
-   * Starts at `0` and advances monotonically.
+   * Per-materializer watermark: the seq of the next event each materializer
+   * (by index, parallel to `#materializers`) has NOT yet applied. Starts at
+   * `0` for every materializer and advances independently — a materializer
+   * with no snapshot stays at `0` even when a sibling has recovered to a
+   * much higher watermark, so catch-up never skips events for it (REPLICA-04).
    */
-  #appliedSeq = 0;
+  #watermarks;
   constructor(materializers, options = {}) {
     this.#materializers = [...materializers];
+    this.#watermarks = this.#materializers.map(() => 0);
     this.#snapshotStore = options.snapshotStore;
     this.#doClient = options.doClient;
     this.#unknownEventHandling = options.unknownEventHandling ?? "warn";
   }
   // ── Public API ──────────────────────────────────────────────────────
   /**
-   * The sequence number of the last event applied to all materializers.
+   * The lowest per-materializer watermark — the seq of the next event that
+   * at least one materializer has not yet applied. `0` when there are no
+   * materializers.
    */
   get appliedSeq() {
-    return this.#appliedSeq;
+    return this.#watermarks.length > 0 ? Math.min(...this.#watermarks) : 0;
   }
   /**
-   * Replay a batch of entries through all materializers.
-   *
-   * Entries with `seq < this.appliedSeq` are silently skipped (idempotent).
-   * @returns The number of entries actually applied.
+   * Replay a batch of entries, applying each entry only to the
+   * materializers whose own watermark is behind it — a materializer at or
+   * past an entry's seq (e.g. recovered from a snapshot, or already caught
+   * up) skips it, so no materializer ever double-applies an event.
+   * @returns The number of entries applied to at least one materializer.
    */
   applyEntries(entries) {
     let count = 0;
     for (const entry of entries) {
-      if (entry.seq < this.#appliedSeq) {
-        continue;
-      }
-      const statesBefore = this.#materializers.map((m) => m.state);
-      let stateChanged = false;
-      for (const m of this.#materializers) {
-        m.apply(entry);
-      }
-      for (let i = 0; i < this.#materializers.length; i += 1) {
-        if (this.#materializers[i]?.state !== statesBefore[i]) {
-          stateChanged = true;
-          break;
+      let appliedToAny = false;
+      let anyChanged = false;
+      for (const [i, materializer] of this.#materializers.entries()) {
+        const watermark = this.#watermarks[i] ?? 0;
+        if (entry.seq < watermark) {
+          continue;
         }
+        const stateBefore = materializer.state;
+        materializer.apply(entry);
+        appliedToAny = true;
+        if (materializer.state !== stateBefore) {
+          anyChanged = true;
+        }
+        this.#watermarks[i] = entry.seq + 1;
+      }
+      if (!appliedToAny) {
+        continue;
       }
-      if (!stateChanged) {
+      if (!anyChanged) {
         this.#handleUnknownEvent(entry);
       }
-      this.#appliedSeq = entry.seq + 1;
       count += 1;
     }
     return count;
@@ -99,44 +109,50 @@ class MaterializerRuntime {
   /**
    * Attempt to recover materialized state from a snapshot store.
    *
-   * When a snapshot is found for a materializer, its state is restored
-   * and the snapshot's watermark (`appliedSeq`) is returned so the caller
-   * can skip replaying entries up to that point.
-   * @returns The highest `appliedSeq` across all recovered snapshots, or `0`.
+   * When a snapshot is found for a materializer, its state AND its own
+   * watermark are restored from that snapshot. A materializer with no
+   * snapshot keeps its current watermark (`0` for a fresh runtime) — it
+   * does NOT inherit another materializer's watermark, so it still catches
+   * up from the very beginning (REPLICA-04: previously a shared watermark
+   * was bumped to the MAX across snapshots, permanently skipping events 0..N
+   * for any un-snapshotted or lagging materializer).
+   * @returns The highest snapshot `appliedSeq` across all materializers, or
+   * `0` — kept for backward compatibility; callers that need the fetch
+   * watermark for catch-up should use the per-materializer minimum instead
+   * (see `initialize`).
    */
   async recoverFromSnapshots() {
     if (!this.#snapshotStore) {
       return 0;
     }
     let maxSeq = 0;
-    for (const m of this.#materializers) {
-      const raw = await this.#snapshotStore.load(m.def.name);
+    for (const [i, materializer] of this.#materializers.entries()) {
+      const raw = await this.#snapshotStore.load(materializer.def.name);
       if (raw !== null && typeof raw === "object") {
         const snapshot = raw;
         if (snapshot.state !== void 0) {
-          m.setState(snapshot.state);
+          materializer.setState(snapshot.state);
         }
+        this.#watermarks[i] = snapshot.appliedSeq;
         if (snapshot.appliedSeq > maxSeq) {
           maxSeq = snapshot.appliedSeq;
         }
       }
     }
-    if (maxSeq > this.#appliedSeq) {
-      this.#appliedSeq = maxSeq;
-    }
     return maxSeq;
   }
   /**
-   * Persist the current state of all materializers as snapshots.
+   * Persist the current state of all materializers as snapshots, each
+   * tagged with ITS OWN watermark (not a shared one).
    */
   async persistSnapshots() {
     if (!this.#snapshotStore) {
       return;
     }
-    for (const m of this.#materializers) {
-      await this.#snapshotStore.save(m.def.name, {
-        appliedSeq: this.#appliedSeq,
-        state: m.state
+    for (const [i, materializer] of this.#materializers.entries()) {
+      await this.#snapshotStore.save(materializer.def.name, {
+        appliedSeq: this.#watermarks[i] ?? 0,
+        state: materializer.state
       });
     }
   }
@@ -146,8 +162,11 @@ class MaterializerRuntime {
    *
    * 1. Recover materialized state from snapshots (if a snapshotStore is
    * configured).
-   * 2. Fetch all entries since the recovered watermark from the DO.
-   * 3. Apply them through the materializers.
+   * 2. Fetch all entries since the MINIMUM per-materializer watermark from
+   * the DO — not the maximum — so a materializer with no snapshot (or a
+   * lower one) still receives every event it hasn't seen (REPLICA-04).
+   * 3. Apply them through the materializers; `applyEntries` skips each
+   * entry for any materializer already past it, so nothing is double-applied.
    *
    * Call this once on startup / after the DO binding is available.
    * @returns The number of entries applied during catch-up.
@@ -156,8 +175,9 @@ class MaterializerRuntime {
     if (!this.#doClient) {
       return 0;
     }
-    const snapshotSeq = await this.recoverFromSnapshots();
-    const entries = await this.#doClient.getSince(snapshotSeq);
+    await this.recoverFromSnapshots();
+    const minWatermark = this.#watermarks.length > 0 ? Math.min(...this.#watermarks) : 0;
+    const entries = await this.#doClient.getSince(minWatermark);
     if (entries.length === 0) {
       return 0;
     }
@@ -188,9 +208,9 @@ class MaterializerRuntime {
    * Reset all materializers to their initial state and clear snapshots.
    */
   reset() {
-    this.#appliedSeq = 0;
-    for (const m of this.#materializers) {
-      m.reset();
+    for (const [i, materializer] of this.#materializers.entries()) {
+      this.#watermarks[i] = 0;
+      materializer.reset();
     }
   }
   /**

package/dist/packem_shared/applyDiff-98tKzmiW.mjs

@@ -0,0 +1,67 @@
+const canonicalizeForHash = (value) => {
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalizeForHash(item));
+  }
+  if (value !== null && typeof value === "object") {
+    const record = value;
+    const sortedKeys = Object.keys(record).toSorted((a, b) => a.localeCompare(b));
+    const result = {};
+    for (const key of sortedKeys) {
+      result[key] = canonicalizeForHash(record[key]);
+    }
+    return result;
+  }
+  return value;
+};
+const deriveInsertId = (diff, changeIndex, data) => {
+  const diffIdentity = diff.id ?? String(diff.timestamp);
+  const input = `${diff.table}::${diffIdentity}::${String(changeIndex)}::${JSON.stringify(canonicalizeForHash(data))}`;
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x00000100000001b3n;
+  const mask64 = 0xffffffffffffffffn;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= BigInt(input.codePointAt(index) ?? 0);
+    hash = hash * prime & mask64;
+  }
+  return `row-${hash.toString(16).padStart(16, "0")}`;
+};
+const applyDiff = (current, diff) => {
+  const next = new Map(current);
+  for (const [changeIndex, change] of diff.changes.entries()) {
+    switch (change.type) {
+      case "delete": {
+        next.delete(change.id);
+        break;
+      }
+      case "insert": {
+        const rawId = change.data.id;
+        const id = typeof rawId === "string" || typeof rawId === "number" ? String(rawId) : deriveInsertId(diff, changeIndex, change.data);
+        next.set(id, { ...change.data, id });
+        break;
+      }
+      case "update": {
+        const existing = next.get(change.id);
+        if (existing) {
+          next.set(change.id, { ...existing, ...change.data });
+        }
+        break;
+      }
+    }
+  }
+  return next;
+};
+const applyDiffs = (current, diffs) => {
+  let result = new Map(current);
+  for (const diff of diffs) {
+    result = applyDiff(result, diff);
+  }
+  return result;
+};
+const applyDiffToSnapshot = (snapshot, diff) => {
+  const next = new Map(snapshot);
+  const tableMap = next.get(diff.table) ?? /* @__PURE__ */ new Map();
+  next.set(diff.table, applyDiff(tableMap, diff));
+  return next;
+};
+
+export { applyDiff, applyDiffToSnapshot, applyDiffs };

package/dist/packem_shared/{classifyChanges-aZmkxgVI.mjs → classifyChanges-RcqLBpLs.mjs}

@@ -1,8 +1,9 @@
-const createTableDiff = (table, changes, timestamp) => {
+const createTableDiff = (table, changes, timestamp, id) => {
   return {
     table,
     changes,
-    timestamp: timestamp ?? Date.now()
+    timestamp: timestamp ?? Date.now(),
+    id: id ?? crypto.randomUUID()
   };
 };
 const isDiffEmpty = (diff) => diff.changes.length === 0;
@@ -28,10 +29,12 @@ const mergeDiffs = (diffs) => {
   }
   const first = diffs[0];
   const last = diffs[diffs.length - 1];
+  const mergedId = `merge:${diffs.map((d) => d.id ?? String(d.timestamp)).join("|")}`;
   return createTableDiff(
     first.table,
     diffs.flatMap((d) => d.changes),
-    last.timestamp
+    last.timestamp,
+    mergedId
   );
 };
 

package/dist/packem_shared/{local-mirror.d-Cd8tAg-W.d.ts → local-mirror.d-ByIjd7sW.d.ts}

@@ -28,16 +28,29 @@ type RowChange = {
 interface TableDiff {
   /** Ordered row changes — insert/update/delete, earliest first. */
   readonly changes: ReadonlyArray<RowChange>;
+  /**
+  * Optional stable identity for this diff, distinct from `timestamp`
+  * (multiple diffs can legitimately share a millisecond, so `timestamp`
+  * alone is not a unique diff identity). Used by `deriveInsertId` in
+  * `apply-diff.ts` to derive deterministic row ids for id-less inserts:
+  * replaying the SAME diff (same `id`) must always mint the SAME id,
+  * while two DIFFERENT diffs emitted in the same millisecond must not
+  * alias onto the same one. `createTableDiff` auto-generates one when
+  * omitted; diffs built as plain object literals (bypassing the helper)
+  * simply fall back to `timestamp` for that derivation.
+  */
+  readonly id?: string;
   /** Logical table name (matches the schema table name). */
   readonly table: string;
   /** Monotonic server timestamp (ms since epoch) when this diff was emitted. */
   readonly timestamp: number;
 }
 /**
-* Create a {@link TableDiff} with a snapshot of the current time.
+* Create a {@link TableDiff} with a snapshot of the current time and a
+* fresh stable `id` (unless one is explicitly provided).
 * @experimental
 */
-declare const createTableDiff: (table: string, changes: ReadonlyArray<RowChange>, timestamp?: number) => TableDiff;
+declare const createTableDiff: (table: string, changes: ReadonlyArray<RowChange>, timestamp?: number, id?: string) => TableDiff;
 /**
 * Return `true` when the diff contains no row changes.
 * @experimental
@@ -212,6 +225,37 @@ interface AppendOptions {
   readonly parentSeqNum?: Seq;
   /** Session identifier within the client. */
   readonly sessionId?: string;
+  /**
+  * Override the entry's `timestamp` instead of stamping `Date.now()` at
+  * append time.
+  *
+  * Used by callers (e.g. {@link import("./event-source").EventSource | EventSource})
+  * that must commit the EXACT entry a reducer already observed — a
+  * second, independently-drawn `Date.now()` at append time could produce
+  * a persisted entry a timestamp-dependent reducer cannot reproduce on
+  * replay.
+  */
+  readonly timestamp?: number;
+}
+/**
+* Options for constructing an {@link EventLog}.
+* @experimental
+*/
+interface EventLogOptions {
+  /**
+  * Cap the number of entries retained in memory (REPLICA-06). When an
+  * append would exceed the cap, the OLDEST entries are evicted (ring
+  * buffer) — a `getSince`/`getFrom` call for a watermark below the oldest
+  * retained `seq` then returns only what's left, silently missing
+  * anything evicted.
+  *
+  * `undefined` (the default) preserves the original unbounded behavior.
+  * Set this only when you have another durable source of truth for
+  * anything older than the cap (a snapshot, a server-side `EventLogDO`) —
+  * see {@link EventLog#truncateBelow} for the caller-driven equivalent
+  * tied to snapshot persistence.
+  */
+  readonly maxEntries?: number;
 }
 /**
 * An append-only, in-memory event log for local event sourcing.
@@ -226,6 +270,7 @@ interface AppendOptions {
 */
 declare class EventLog {
   #private;
+  constructor(options?: EventLogOptions);
   /**
   * Append a new entry to the log.
   *
@@ -254,6 +299,10 @@ declare class EventLog {
   * This is the restore counterpart of {@link EventLog#snapshot}.
   * Restores `headSeq` from the snapshot so auto-parenting continues
   * after restore.
+  *
+  * Runs `#enforceCap()` after restoring so a snapshot captured under a
+  * different (or no) `maxEntries` can never leave this log over its
+  * configured capacity.
   */
   load(snapshot: EventLogSnapshot): void;
   /**
@@ -289,6 +338,24 @@ declare class EventLog {
   /** Remove all entries (primarily for testing). */
   clear(): void;
   /**
+  * Discard all entries with `seq < floorSeq` (REPLICA-06).
+  *
+  * `headSeq`/`nextSeq` are untouched (they're independent counters), so
+  * appends after a truncation continue the same sequence uninterrupted.
+  *
+  * **Caller-driven, not automatic**: only call this after the truncated
+  * range has already been durably captured elsewhere (a snapshot, a
+  * server-side `EventLogDO`) — truncating without such a floor makes any
+  * future `getSince`/`getFrom`/`EventSource.replayFromLog` call for a
+  * watermark below `floorSeq` silently miss the discarded entries. This is
+  * the hook the caller ties to snapshot persistence; the log itself has no
+  * concept of "already durably persisted".
+  *
+  * `floorSeq` must be a non-negative safe integer — `NaN` would make
+  * every comparison false and silently clear the entire log.
+  */
+  truncateBelow(floorSeq: number): void;
+  /**
   * Return an async generator that yields every entry starting from
   * `fromSeq` (default `0` = all entries).
   *
@@ -314,6 +381,18 @@ interface LocalMirrorOptions {
   /** Platform-specific SQLite adapter. */
   readonly db: SqliteAdapter;
   /**
+  * Cap the mirror's internal {@link EventLog} to this many entries
+  * (REPLICA-06). Every applied diff is recorded in the log — with no cap,
+  * a long-running client accumulates one entry per diff forever.
+  *
+  * `undefined` (the default) preserves unbounded retention. Set this when
+  * catch-up replication only ever needs a bounded recent window; older
+  * entries are silently evicted (oldest-first) once the cap is exceeded.
+  * See {@link EventLog#truncateBelow} for caller-driven truncation tied to
+  * a snapshot instead.
+  */
+  readonly maxEventLogEntries?: number;
+  /**
   * Table schemas the mirror should manage.
   *
   * On first use the mirror creates any missing tables automatically
@@ -399,6 +478,13 @@ declare class LocalMirror {
   */
   get db(): SqliteAdapter;
   /**
+  * Monotonically increasing version counter, bumped on every operation
+  * that changes mirrored data (`applyDiff`, `clearData`). Use this — not
+  * `eventLog.size` — as a `useSyncExternalStore` snapshot so operations
+  * that don't append to the log still trigger a re-render.
+  */
+  get version(): number;
+  /**
   * Apply a server-side diff to the local SQLite mirror.
   *
   * The diff is applied in a transaction and recorded in the event log
@@ -420,6 +506,11 @@ declare class LocalMirror {
   /**
   * Delete every row from all known tables (preserves the event log
   * and schema). Useful when re-syncing from scratch.
+  *
+  * Notifies `onChange` subscribers and bumps {@link LocalMirror.version}
+  * (REPLICA-09) even though nothing is appended to the event log — a
+  * consumer keyed only on `eventLog.size` would otherwise never learn the
+  * mirror was cleared and keep rendering deleted rows.
   */
   clearData(): void;
   /**
@@ -436,4 +527,4 @@ declare class LocalMirror {
   */
   get mirroredTables(): ReadonlyArray<string>;
 }
-export { AppendOptions as A, ClientSeq as C, EventLogEntry as E, GlobalSeq as G, InputEvent as I, LocalMirror as L, MirrorTableDef as M, RowChange as R, Seq as S, TableDiff as T, EventLog as a, EventLogSnapshot as b, LocalMirrorOptions as c, classifyChanges as d, createTableDiff as e, diffSize as f, isDiffEmpty as g, isGlobalSeq as h, isClientSeq as i, isInputEvent as j, mergeDiffs as m };
+export { AppendOptions as A, ClientSeq as C, EventLogEntry as E, GlobalSeq as G, InputEvent as I, LocalMirror as L, MirrorTableDef as M, RowChange as R, Seq as S, TableDiff as T, EventLog as a, EventLogOptions as b, EventLogSnapshot as c, LocalMirrorOptions as d, classifyChanges as e, createTableDiff as f, diffSize as g, isDiffEmpty as h, isClientSeq as i, isGlobalSeq as j, isInputEvent as k, mergeDiffs as m };