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

package/dist/packem_shared/EventLog-CnK-3Wge.mjs

@@ -0,0 +1,264 @@
+class EventLog {
+  #entries = [];
+  /**
+   * Logical index of the first LIVE entry within `#entries` (REPLICA-06
+   * perf): entries at `[0, #headOffset)` have already been evicted by the
+   * cap but are not yet physically removed from the backing array. Bumping
+   * this offset is O(1), so a capped append never pays the O(n) cost of
+   * shifting the retained array — see `#enforceCap`.
+   */
+  #headOffset = 0;
+  #nextSeq = 0;
+  // eslint-disable-next-line unicorn/no-null -- public contract uses `null` for an empty log head
+  #headSeq = null;
+  #maxEntries;
+  constructor(options) {
+    this.#maxEntries = EventLog.#validateMaxEntries(options?.maxEntries);
+  }
+  /**
+   * Validate `maxEntries` as an invariant: `undefined` (uncapped) or a
+   * non-negative safe integer. Negative values would evict everything,
+   * fractional/NaN/Infinity values would leave the log over capacity or
+   * effectively disable the cap.
+   */
+  static #validateMaxEntries(maxEntries) {
+    if (maxEntries === void 0) {
+      return void 0;
+    }
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 0) {
+      throw new RangeError("maxEntries must be a non-negative safe integer");
+    }
+    return maxEntries;
+  }
+  /**
+   * Entries currently considered live (excludes the evicted-but-not-yet-
+   * compacted prefix). ALWAYS returns a fresh copy — never the internal
+   * `#entries` array by reference — so a caller iterating the result (e.g.
+   * `EventSource.replayFromLog` replaying a log into itself) can't observe
+   * later appends made to `#entries` while iterating.
+   */
+  #liveEntries() {
+    return this.#entries.slice(this.#headOffset);
+  }
+  // ── Mutators ──────────────────────────────────────────────────────
+  /**
+   * Evict the oldest entries so the LIVE entry count never exceeds
+   * `#maxEntries`. `headSeq`/`nextSeq` are untouched — they're independent
+   * counters, not derived from the entries array — so appends after an
+   * eviction continue the same sequence.
+   *
+   * Eviction itself is O(1) (bump `#headOffset`) rather than an O(n)
+   * `splice(0, n)` on every capped append. The dead prefix is compacted
+   * away in one pass once it reaches half the backing array, which bounds
+   * memory growth while keeping the amortized cost of both append and
+   * compaction O(1) per entry.
+   */
+  #enforceCap() {
+    if (this.#maxEntries === void 0) {
+      return;
+    }
+    const liveCount = this.#entries.length - this.#headOffset;
+    const overflow = liveCount - this.#maxEntries;
+    if (overflow > 0) {
+      this.#headOffset += overflow;
+    }
+    if (this.#headOffset > 0 && this.#headOffset >= this.#entries.length - this.#headOffset) {
+      this.#entries = this.#entries.slice(this.#headOffset);
+      this.#headOffset = 0;
+    }
+  }
+  append(typeOrEvent, payload, tableDiffs, options) {
+    const type = typeof typeOrEvent === "string" ? typeOrEvent : typeOrEvent.type;
+    const pl = typeof typeOrEvent === "string" ? payload : typeOrEvent.payload;
+    let diffs;
+    let resolvedOptions;
+    if (typeof typeOrEvent === "string") {
+      diffs = tableDiffs;
+      resolvedOptions = options;
+    } else {
+      diffs = void 0;
+      resolvedOptions = payload;
+    }
+    const parentSeqNumber = resolvedOptions?.parentSeqNum ?? this.#headSeq ?? void 0;
+    const seq = this.#nextSeq;
+    this.#nextSeq += 1;
+    const entry = {
+      seq,
+      type,
+      payload: pl,
+      timestamp: resolvedOptions?.timestamp ?? Date.now(),
+      tableDiffs: diffs,
+      clientId: resolvedOptions?.clientId,
+      sessionId: resolvedOptions?.sessionId,
+      parentSeqNum: parentSeqNumber
+    };
+    this.#entries.push(entry);
+    this.#headSeq = entry.seq;
+    this.#enforceCap();
+    return entry;
+  }
+  /**
+   * Atomically append multiple events to the log.
+   *
+   * All events are assigned sequential global sequence numbers and
+   * automatically wired as a causal chain (each event's `parentSeqNum`
+   * points to the previous event in the batch, or to the log head for
+   * the first event).
+   * @param events An array of events to commit atomically.
+   * @returns The newly created entries in order.
+   */
+  commitAll(events) {
+    if (events.length === 0) {
+      return [];
+    }
+    const entries = [];
+    for (const event of events) {
+      const { type } = event;
+      const payload = "payload" in event ? event.payload : void 0;
+      const ts = "timestamp" in event ? event.timestamp : Date.now();
+      const parentSeqNumber = entries.at(-1)?.seq ?? this.#headSeq ?? void 0;
+      const seq = this.#nextSeq;
+      this.#nextSeq += 1;
+      const entry = {
+        seq,
+        type,
+        payload,
+        timestamp: ts,
+        parentSeqNum: parentSeqNumber
+      };
+      this.#entries.push(entry);
+      entries.push(entry);
+    }
+    this.#headSeq = entries.at(-1)?.seq ?? this.#headSeq;
+    this.#enforceCap();
+    return entries;
+  }
+  /**
+   * Replace the log contents with a previously captured snapshot.
+   * 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) {
+    this.#entries = [...snapshot.entries];
+    this.#headOffset = 0;
+    this.#nextSeq = snapshot.nextSeq;
+    this.#headSeq = snapshot.headSeq;
+    this.#enforceCap();
+  }
+  // ── Queries ───────────────────────────────────────────────────────
+  /**
+   * Return **all** entries whose `seq >= sinceSeq`.
+   * Useful for catch-up: "give me everything since my last watermark".
+   */
+  getSince(sinceSeq) {
+    const live = this.#liveEntries();
+    if (sinceSeq <= 0) {
+      return live;
+    }
+    const first = live.findIndex((entry) => entry.seq >= sinceSeq);
+    return first === -1 ? [] : live.slice(first);
+  }
+  /**
+   * Paginated read starting at `fromSeq`.
+   * @returns `{ entries, hasMore }` where `hasMore` is `true` when more
+   * entries exist beyond the requested page.
+   */
+  getFrom(fromSeq, limit = 50) {
+    const entries = this.#entries;
+    const start = this.#headOffset;
+    const first = entries.findIndex((entry, index) => index >= start && entry.seq >= fromSeq);
+    if (first === -1) {
+      return { entries: [], hasMore: false };
+    }
+    const end = Math.min(first + limit, entries.length);
+    return {
+      entries: entries.slice(first, end),
+      hasMore: end < entries.length
+    };
+  }
+  /**
+   * Return all entries as a snapshot suitable for serialisation.
+   */
+  snapshot() {
+    return {
+      entries: this.#liveEntries(),
+      nextSeq: this.#nextSeq,
+      headSeq: this.#headSeq
+    };
+  }
+  /** Number of entries currently in the log. */
+  get size() {
+    return this.#entries.length - this.#headOffset;
+  }
+  /** The next sequence number that will be assigned. */
+  get nextSeq() {
+    return this.#nextSeq;
+  }
+  /** Return `true` when there are no entries. */
+  get isEmpty() {
+    return this.size === 0;
+  }
+  /**
+   * The sequence number of the last (most recent) entry, or `null`
+   * when the log is empty. Used internally for auto-parenting and
+   * exposed for consumers that need the causal head.
+   */
+  get headSeq() {
+    return this.#headSeq;
+  }
+  /** Remove all entries (primarily for testing). */
+  clear() {
+    this.#entries = [];
+    this.#headOffset = 0;
+    this.#nextSeq = 0;
+    this.#headSeq = null;
+  }
+  /**
+   * 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) {
+    if (!Number.isSafeInteger(floorSeq) || floorSeq < 0) {
+      throw new RangeError("floorSeq must be a non-negative safe integer");
+    }
+    const live = this.#liveEntries();
+    const cutoff = live.findIndex((entry) => entry.seq >= floorSeq);
+    this.#entries = cutoff === -1 ? [] : live.slice(cutoff);
+    this.#headOffset = 0;
+  }
+  /**
+   * Return an async generator that yields every entry starting from
+   * `fromSeq` (default `0` = all entries).
+   *
+   * Because `EventLog` is purely in-memory, the generator yields all
+   * matching entries synchronously on first iteration and then completes.
+   * For a streaming / push-based variant see {@link EventSource.events}.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await -- kept async so callers can uniformly `for await` over any event stream
+  async *events(fromSeq = 0) {
+    const entries = this.getSince(fromSeq);
+    for (const entry of entries) {
+      yield entry;
+    }
+  }
+}
+
+export { EventLog };

package/dist/packem_shared/{EventLogDO-CZYUvvSr.mjs → EventLogDO-DqlsVx0H.mjs}

@@ -1,3 +1,31 @@
+const IDEMPOTENCY_CONFLICT = /* @__PURE__ */ Symbol("lunora.replica.event-log-do.idempotency-conflict");
+const createIdempotencyConflictError = (message) => {
+  const error = new Error(message);
+  Object.defineProperty(error, IDEMPOTENCY_CONFLICT, { value: true });
+  return error;
+};
+const isIdempotencyConflictError = (error) => error instanceof Error && IDEMPOTENCY_CONFLICT in error;
+const canonicalizeForFingerprint = (value) => {
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalizeForFingerprint(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] = canonicalizeForFingerprint(record[key]);
+    }
+    return result;
+  }
+  return value;
+};
+const fingerprintBatch = async (events) => {
+  const canonical = JSON.stringify(canonicalizeForFingerprint(events));
+  const bytes = new TextEncoder().encode(canonical);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
 const toArray = (cursor) => {
   if (typeof cursor.toArray === "function") {
     return cursor.toArray();
@@ -85,34 +113,130 @@ class EventLogDO {
         }
       );
     }
-    if (!Array.isArray(body.events) || body.events.length === 0 || body.events.some((eventRecord) => typeof eventRecord.type !== "string" || eventRecord.type.length === 0)) {
+    const validationError = EventLogDO.#validateAppendRequest(body);
+    if (validationError) {
       return Response.json(
-        { error: { code: "BAD_REQUEST", message: "events[] with a non-empty string `type` required" } },
+        { error: { code: "BAD_REQUEST", message: validationError } },
         {
           status: 400,
           headers: { "content-type": "application/json" }
         }
       );
     }
-    const entries = [];
     const { sql } = this.state.storage;
+    const { batchId } = body;
+    const runBatch = () => EventLogDO.#runAppendBatch(sql, body, batchId);
+    const { transaction } = this.state.storage;
+    let entries;
+    try {
+      entries = typeof transaction === "function" ? await transaction(runBatch) : await runBatch();
+    } catch (error) {
+      if (isIdempotencyConflictError(error)) {
+        return Response.json({ error: { code: "CONFLICT", message: error.message } }, { status: 409, headers: { "content-type": "application/json" } });
+      }
+      throw error;
+    }
+    const response = { entries };
+    return Response.json(response, {
+      status: 200,
+      headers: { "content-type": "application/json" }
+    });
+  }
+  /**
+   * Execute one `/append` batch: idempotent lookup (fingerprint-checked) or
+   * insert + record. Extracted out of `#handleAppend` (which only wires up
+   * the HTTP request/response and the transaction wrapper) to keep that
+   * method's cognitive complexity within budget.
+   *
+   * Idempotent replay: a batch already persisted under `batchId` returns
+   * the originally-persisted entries instead of inserting a duplicate copy
+   * — but ONLY when the incoming request's fingerprint matches what was
+   * persisted under that key. A `batchId` reused for a genuinely different
+   * event batch throws an idempotency-conflict error instead of silently
+   * dropping the new events and returning unrelated entries.
+   */
+  static async #runAppendBatch(sql, body, batchId) {
+    let fingerprint;
+    if (typeof batchId === "string") {
+      fingerprint = await fingerprintBatch(body.events);
+      const existing = EventLogDO.#findBatch(sql, batchId);
+      if (existing) {
+        if (existing.fingerprint !== fingerprint) {
+          throw createIdempotencyConflictError(`batchId "${batchId}" was already used for a different event batch`);
+        }
+        return existing.entries;
+      }
+    }
     const now = Date.now();
+    const entries = [];
     for (const eventRecord of body.events) {
       const seq = EventLogDO.#nextSeq(sql);
       const entry = {
         seq,
         type: eventRecord.type,
         payload: eventRecord.payload,
-        timestamp: eventRecord.timestamp ?? now
+        timestamp: eventRecord.timestamp ?? now,
+        clientId: eventRecord.clientId,
+        sessionId: eventRecord.sessionId,
+        parentSeqNum: eventRecord.parentSeqNum
       };
       EventLogDO.#insertEvent(sql, entry);
       entries.push(entry);
     }
-    const response = { entries };
-    return Response.json(response, {
-      status: 200,
-      headers: { "content-type": "application/json" }
-    });
+    if (typeof batchId === "string" && fingerprint !== void 0) {
+      const firstSeq = entries[0]?.seq;
+      const lastSeq = entries.at(-1)?.seq;
+      if (firstSeq !== void 0 && lastSeq !== void 0) {
+        EventLogDO.#recordBatch(sql, batchId, firstSeq, lastSeq, fingerprint);
+      }
+    }
+    return entries;
+  }
+  /**
+   * Validate an `/append` request body up front so malformed input surfaces
+   * as a clean 400 instead of a 500 from the generic catch handler (e.g. a
+   * non-string `type` or a non-finite `timestamp` landing in a NOT NULL /
+   * INTEGER column).
+   * @returns An error message, or `undefined` when the body is valid.
+   */
+  static #validateAppendRequest(body) {
+    if (!Array.isArray(body.events) || body.events.length === 0) {
+      return "events[] with a non-empty string `type` required";
+    }
+    if (body.batchId !== void 0 && (typeof body.batchId !== "string" || body.batchId.length === 0)) {
+      return "batchId must be a non-empty string";
+    }
+    for (const eventRecord of body.events) {
+      const error = EventLogDO.#validateEventRecord(eventRecord);
+      if (error !== void 0) {
+        return error;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Validate a single `/append` event record — split out of
+   * {@link EventLogDO.#validateAppendRequest} to keep each function's
+   * cognitive complexity down.
+   * @returns An error message, or `undefined` when the record is valid.
+   */
+  static #validateEventRecord(eventRecord) {
+    if (typeof eventRecord.type !== "string" || eventRecord.type.length === 0) {
+      return "events[] with a non-empty string `type` required";
+    }
+    if (eventRecord.timestamp !== void 0 && !Number.isFinite(eventRecord.timestamp)) {
+      return "events[].timestamp must be a finite number";
+    }
+    if (eventRecord.clientId !== void 0 && typeof eventRecord.clientId !== "string") {
+      return "events[].clientId must be a string";
+    }
+    if (eventRecord.sessionId !== void 0 && typeof eventRecord.sessionId !== "string") {
+      return "events[].sessionId must be a string";
+    }
+    if (eventRecord.parentSeqNum !== void 0 && (typeof eventRecord.parentSeqNum !== "number" || !Number.isInteger(eventRecord.parentSeqNum) || eventRecord.parentSeqNum < 0)) {
+      return "events[].parentSeqNum must be a non-negative integer";
+    }
+    return void 0;
   }
   /** GET /since?seq=N — return entries with seq >= N. */
   #handleSince(url) {
@@ -203,8 +327,30 @@ class EventLogDO {
     sql.exec(
       "CREATE TABLE IF NOT EXISTS events (seq INTEGER PRIMARY KEY AUTOINCREMENT, type TEXT NOT NULL, payload TEXT NOT NULL, timestamp INTEGER NOT NULL, client_id TEXT, session_id TEXT, parent_seq INTEGER)"
     );
+    sql.exec(
+      "CREATE TABLE IF NOT EXISTS event_batches (batch_id TEXT PRIMARY KEY, first_seq INTEGER NOT NULL, last_seq INTEGER NOT NULL, fingerprint TEXT NOT NULL)"
+    );
     this.#initialized = true;
   }
+  /** Look up a previously-persisted batch by its idempotency key. */
+  static #findBatch(sql, batchId) {
+    const batchCursor = sql.exec("SELECT first_seq, last_seq, fingerprint FROM event_batches WHERE batch_id = ?", batchId);
+    const batchRows = toArray(batchCursor);
+    const batchRow = batchRows[0];
+    if (!batchRow) {
+      return void 0;
+    }
+    const cursor = sql.exec(
+      "SELECT seq, type, payload, timestamp, client_id, session_id, parent_seq FROM events WHERE seq >= ? AND seq <= ? ORDER BY seq ASC",
+      batchRow.first_seq,
+      batchRow.last_seq
+    );
+    return { entries: rowsToEntries(cursor), fingerprint: batchRow.fingerprint };
+  }
+  /** Record a persisted batch's seq range and request fingerprint under its idempotency key. */
+  static #recordBatch(sql, batchId, firstSeq, lastSeq, fingerprint) {
+    sql.exec("INSERT INTO event_batches (batch_id, first_seq, last_seq, fingerprint) VALUES (?, ?, ?, ?)", batchId, firstSeq, lastSeq, fingerprint);
+  }
   /** Get the next available sequence number. */
   static #nextSeq(sql) {
     const cursor = sql.exec("SELECT COALESCE(MAX(seq), -1) + 1 AS next_seq FROM events");

package/dist/packem_shared/{EventLogDOClient-DGiEdi96.mjs → EventLogDOClient-F4FO8Si4.mjs}

@@ -6,10 +6,16 @@ class EventLogDOClient {
   // ── Append ─────────────────────────────────────────────────────────
   /**
    * Append one or more events to the log.
+   * @param events The events to append.
+   * @param options Idempotency controls for the batch.
+   * @param options.batchId Optional idempotency key for the whole batch — a
+   * retried `append` call with the same `batchId` (e.g. after a network
+   * timeout that hid a successful response) returns the originally-persisted
+   * entries instead of inserting duplicates.
    * @returns The persisted entries with their assigned `seq` numbers.
    */
-  async append(events) {
-    const body = JSON.stringify({ events });
+  async append(events, options) {
+    const body = JSON.stringify({ events, batchId: options?.batchId });
     const response = await this.#fetch(
       new Request("https://do/append", {
         method: "POST",

package/dist/packem_shared/{EventSource-DfV4VoRD.mjs → EventSource-D5yO9_aI.mjs}

@@ -1,10 +1,11 @@
 import { EventEmitter } from './EventEmitter-CMZfct03.mjs';
-import { EventLog } from './EventLog-zMy7AYP4.mjs';
+import { EventLog } from './EventLog-CnK-3Wge.mjs';
 
+const UNHANDLED = /* @__PURE__ */ Symbol("lunora.replica.event-source.unhandled");
 class EventSource {
   // eslint-disable-next-line unicorn/prefer-event-target -- EventEmitter is the library's typed public API
   emitter = new EventEmitter();
-  log = new EventLog();
+  log;
   #state;
   #reducer;
   #replayed = false;
@@ -22,6 +23,7 @@ class EventSource {
     this.#state = { ...initialState };
     this.#reducer = reducer;
     this.#unknownEventHandling = options?.unknownEventHandling ?? "warn";
+    this.log = new EventLog({ maxEntries: options?.maxLogEntries });
   }
   // ── Public API ────────────────────────────────────────────────────
   /**
@@ -49,8 +51,39 @@ class EventSource {
       pl = typeOrEvent.payload;
       resolvedOptions = payload;
     }
-    const entry = this.log.append(type, pl, void 0, resolvedOptions);
-    this.#applyEntry(entry);
+    const candidate = {
+      seq: this.log.nextSeq,
+      type,
+      payload: pl,
+      timestamp: Date.now(),
+      clientId: resolvedOptions?.clientId,
+      sessionId: resolvedOptions?.sessionId,
+      parentSeqNum: resolvedOptions?.parentSeqNum ?? this.log.headSeq ?? void 0
+    };
+    let reduced;
+    try {
+      reduced = this.#reducer(this.#state, candidate);
+    } catch (error) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error));
+      this.emitter.emit("replay-error", {
+        entry: candidate,
+        error: normalizedError
+      });
+      throw normalizedError;
+    }
+    let handledByCallback = true;
+    if (reduced === UNHANDLED) {
+      handledByCallback = this.#handleUnknown(candidate);
+    }
+    const entry = this.log.append(type, pl, void 0, { ...resolvedOptions, timestamp: candidate.timestamp });
+    if (reduced === UNHANDLED) {
+      if (handledByCallback) {
+        this.emitter.emit("state-changed", { state: this.#state, entry });
+      }
+      return entry;
+    }
+    this.#state = reduced;
+    this.emitter.emit("state-changed", { state: this.#state, entry });
     return entry;
   }
   /**
@@ -65,7 +98,10 @@ class EventSource {
     const entries = log.getSince(this.#lastAppliedSeq + 1);
     for (const entry of entries) {
       try {
-        this.#state = this.#reducer(this.#state, entry);
+        const reduced = this.#reducer(this.#state, entry);
+        if (reduced !== UNHANDLED) {
+          this.#state = reduced;
+        }
         this.log.append(entry.type, entry.payload, entry.tableDiffs, {
           clientId: entry.clientId,
           sessionId: entry.sessionId,
@@ -152,22 +188,12 @@ class EventSource {
     }
   }
   // ── Internal ──────────────────────────────────────────────────────
-  #applyEntry(entry) {
-    const stateBefore = this.#state;
-    try {
-      this.#state = this.#reducer(this.#state, entry);
-    } catch (error) {
-      this.emitter.emit("replay-error", {
-        entry,
-        error: error instanceof Error ? error : new Error(String(error))
-      });
-      return;
-    }
-    if (this.#state === stateBefore && !this.#handleUnknown(entry)) {
-      return;
-    }
-    this.emitter.emit("state-changed", { state: this.#state, entry });
-  }
+  /**
+   * Explicit-sentinel detection (not `state === stateBefore` reference
+   * equality) is what lets a reducer legitimately return `state` unchanged
+   * for a type it DOES recognise without being misclassified as unhandled
+   * (REPLICA-07).
+   */
   #handleUnknown(entry) {
     const strategy = this.#unknownEventHandling;
     if (typeof strategy === "function") {
@@ -192,4 +218,4 @@ class EventSource {
   }
 }
 
-export { EventSource };
+export { EventSource, UNHANDLED };

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