@lunora/replica 1.0.0-alpha.4 → 1.0.0-alpha.6

package/dist/packem_shared/{EventsSync-DkVbU0WV.mjs → EventsSync-BP36tC9O.mjs}

@@ -3,8 +3,13 @@ class EventsSync {
   /** The highest `seq + 1` that has been applied. Starts at `0`. */
   #watermark = 0;
   #timer;
-  /** Guards against overlapping poll cycles (e.g. slow fetch). */
-  #running = false;
+  /**
+   * The in-flight poll cycle, or `undefined` when idle. A concurrent
+   * `sync()`/timer tick AWAITS this instead of no-op'ing (REPLICA-08) —
+   * previously a concurrent call returned `0` immediately without waiting
+   * for the in-progress cycle to actually finish.
+   */
+  #inFlight;
   // ── Constructor ─────────────────────────────────────────────────────
   constructor(options) {
     this.#options = options;
@@ -56,34 +61,61 @@ class EventsSync {
   }
   // ── Internal ────────────────────────────────────────────────────────
   /**
-   * One poll cycle: fetch → apply → diff → mirror.
+   * Entry point for a poll cycle. A cycle already in flight is AWAITED
+   * (not restarted, not no-op'd) so a `sync()` racing a timer tick — or two
+   * concurrent `sync()` calls — observes the real outcome of the one cycle
+   * that actually runs (REPLICA-08).
    */
   async #poll() {
-    if (this.#running) {
-      return 0;
+    if (this.#inFlight) {
+      return this.#inFlight;
     }
-    this.#running = true;
+    const promise = this.#pollOnce().finally(() => {
+      this.#inFlight = void 0;
+    });
+    this.#inFlight = promise;
+    return promise;
+  }
+  /**
+   * One poll cycle: fetch → (apply → diff → mirror) per event.
+   *
+   * Each event is driven through the FULL pipeline — `applyEvents`,
+   * `getTableDiffs`, and `mirror.applyDiff` — atomically before the
+   * watermark advances past it (REPLICA-08). Advancing the watermark any
+   * earlier (e.g. right after `applyEvents`) would let a later throw from
+   * `getTableDiffs`/`mirror.applyDiff` skip mirror delivery for that event
+   * PERMANENTLY, since the next poll would never re-fetch it. Keeping the
+   * watermark pinned to the last event whose entire pipeline succeeded
+   * means the next poll re-fetches exactly the unapplied remainder — never
+   * re-applying a fully-succeeded event, never silently dropping one that
+   * partially failed.
+   */
+  async #pollOnce() {
     try {
       const events = await this.#options.fetchEventsSince(this.#watermark);
       if (events.length === 0) {
         return 0;
       }
-      this.#options.applyEvents(events);
-      const lastEvent = events[events.length - 1];
-      if (lastEvent) {
-        this.#watermark = lastEvent.seq + 1;
-      }
-      const diffs = this.#options.getTableDiffs();
-      for (const diff of diffs) {
-        this.#options.mirror.applyDiff(diff);
+      let appliedCount = 0;
+      try {
+        for (const event of events) {
+          this.#options.applyEvents([event]);
+          const diffs = this.#options.getTableDiffs();
+          for (const diff of diffs) {
+            this.#options.mirror.applyDiff(diff);
+          }
+          this.#watermark = event.seq + 1;
+          appliedCount += 1;
+        }
+      } catch (error) {
+        const onError = this.#options.onError ?? console.error;
+        onError(error);
       }
-      return events.length;
+      return appliedCount;
     } catch (error) {
       const onError = this.#options.onError ?? console.error;
       onError(error);
       return 0;
-    } finally {
-      this.#running = false;
     }
   }
 }

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
   );
 };