@lunora/replica 1.0.0-alpha.7 → 1.0.0-alpha.71

package/LICENSE.md

@@ -227,5 +227,219 @@ Repository: git+https://github.com/anolilab/lunora.git
 >
 > <!-- DEPENDENCIES -->
 > <!-- /DEPENDENCIES -->
+>
+>
+>
+> # Licenses of bundled types
+> The published @lunora/server artifact additionally contains code with the following licenses:
+> Apache-2.0
+>
+> # Bundled types:
+> ## @opentelemetry/api
+> License: Apache-2.0
+> By: OpenTelemetry Authors
+> Repository: open-telemetry/opentelemetry-js
+>
+> > Apache License
+> >                            Version 2.0, January 2004
+> >                         http://www.apache.org/licenses/
+> >
+> >    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+> >
+> >    1. Definitions.
+> >
+> >       "License" shall mean the terms and conditions for use, reproduction,
+> >       and distribution as defined by Sections 1 through 9 of this document.
+> >
+> >       "Licensor" shall mean the copyright owner or entity authorized by
+> >       the copyright owner that is granting the License.
+> >
+> >       "Legal Entity" shall mean the union of the acting entity and all
+> >       other entities that control, are controlled by, or are under common
+> >       control with that entity. For the purposes of this definition,
+> >       "control" means (i) the power, direct or indirect, to cause the
+> >       direction or management of such entity, whether by contract or
+> >       otherwise, or (ii) ownership of fifty percent (50%) or more of the
+> >       outstanding shares, or (iii) beneficial ownership of such entity.
+> >
+> >       "You" (or "Your") shall mean an individual or Legal Entity
+> >       exercising permissions granted by this License.
+> >
+> >       "Source" form shall mean the preferred form for making modifications,
+> >       including but not limited to software source code, documentation
+> >       source, and configuration files.
+> >
+> >       "Object" form shall mean any form resulting from mechanical
+> >       transformation or translation of a Source form, including but
+> >       not limited to compiled object code, generated documentation,
+> >       and conversions to other media types.
+> >
+> >       "Work" shall mean the work of authorship, whether in Source or
+> >       Object form, made available under the License, as indicated by a
+> >       copyright notice that is included in or attached to the work
+> >       (an example is provided in the Appendix below).
+> >
+> >       "Derivative Works" shall mean any work, whether in Source or Object
+> >       form, that is based on (or derived from) the Work and for which the
+> >       editorial revisions, annotations, elaborations, or other modifications
+> >       represent, as a whole, an original work of authorship. For the purposes
+> >       of this License, Derivative Works shall not include works that remain
+> >       separable from, or merely link (or bind by name) to the interfaces of,
+> >       the Work and Derivative Works thereof.
+> >
+> >       "Contribution" shall mean any work of authorship, including
+> >       the original version of the Work and any modifications or additions
+> >       to that Work or Derivative Works thereof, that is intentionally
+> >       submitted to Licensor for inclusion in the Work by the copyright owner
+> >       or by an individual or Legal Entity authorized to submit on behalf of
+> >       the copyright owner. For the purposes of this definition, "submitted"
+> >       means any form of electronic, verbal, or written communication sent
+> >       to the Licensor or its representatives, including but not limited to
+> >       communication on electronic mailing lists, source code control systems,
+> >       and issue tracking systems that are managed by, or on behalf of, the
+> >       Licensor for the purpose of discussing and improving the Work, but
+> >       excluding communication that is conspicuously marked or otherwise
+> >       designated in writing by the copyright owner as "Not a Contribution."
+> >
+> >       "Contributor" shall mean Licensor and any individual or Legal Entity
+> >       on behalf of whom a Contribution has been received by Licensor and
+> >       subsequently incorporated within the Work.
+> >
+> >    2. Grant of Copyright License. Subject to the terms and conditions of
+> >       this License, each Contributor hereby grants to You a perpetual,
+> >       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+> >       copyright license to reproduce, prepare Derivative Works of,
+> >       publicly display, publicly perform, sublicense, and distribute the
+> >       Work and such Derivative Works in Source or Object form.
+> >
+> >    3. Grant of Patent License. Subject to the terms and conditions of
+> >       this License, each Contributor hereby grants to You a perpetual,
+> >       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+> >       (except as stated in this section) patent license to make, have made,
+> >       use, offer to sell, sell, import, and otherwise transfer the Work,
+> >       where such license applies only to those patent claims licensable
+> >       by such Contributor that are necessarily infringed by their
+> >       Contribution(s) alone or by combination of their Contribution(s)
+> >       with the Work to which such Contribution(s) was submitted. If You
+> >       institute patent litigation against any entity (including a
+> >       cross-claim or counterclaim in a lawsuit) alleging that the Work
+> >       or a Contribution incorporated within the Work constitutes direct
+> >       or contributory patent infringement, then any patent licenses
+> >       granted to You under this License for that Work shall terminate
+> >       as of the date such litigation is filed.
+> >
+> >    4. Redistribution. You may reproduce and distribute copies of the
+> >       Work or Derivative Works thereof in any medium, with or without
+> >       modifications, and in Source or Object form, provided that You
+> >       meet the following conditions:
+> >
+> >       (a) You must give any other recipients of the Work or
+> >           Derivative Works a copy of this License; and
+> >
+> >       (b) You must cause any modified files to carry prominent notices
+> >           stating that You changed the files; and
+> >
+> >       (c) You must retain, in the Source form of any Derivative Works
+> >           that You distribute, all copyright, patent, trademark, and
+> >           attribution notices from the Source form of the Work,
+> >           excluding those notices that do not pertain to any part of
+> >           the Derivative Works; and
+> >
+> >       (d) If the Work includes a "NOTICE" text file as part of its
+> >           distribution, then any Derivative Works that You distribute must
+> >           include a readable copy of the attribution notices contained
+> >           within such NOTICE file, excluding those notices that do not
+> >           pertain to any part of the Derivative Works, in at least one
+> >           of the following places: within a NOTICE text file distributed
+> >           as part of the Derivative Works; within the Source form or
+> >           documentation, if provided along with the Derivative Works; or,
+> >           within a display generated by the Derivative Works, if and
+> >           wherever such third-party notices normally appear. The contents
+> >           of the NOTICE file are for informational purposes only and
+> >           do not modify the License. You may add Your own attribution
+> >           notices within Derivative Works that You distribute, alongside
+> >           or as an addendum to the NOTICE text from the Work, provided
+> >           that such additional attribution notices cannot be construed
+> >           as modifying the License.
+> >
+> >       You may add Your own copyright statement to Your modifications and
+> >       may provide additional or different license terms and conditions
+> >       for use, reproduction, or distribution of Your modifications, or
+> >       for any such Derivative Works as a whole, provided Your use,
+> >       reproduction, and distribution of the Work otherwise complies with
+> >       the conditions stated in this License.
+> >
+> >    5. Submission of Contributions. Unless You explicitly state otherwise,
+> >       any Contribution intentionally submitted for inclusion in the Work
+> >       by You to the Licensor shall be under the terms and conditions of
+> >       this License, without any additional terms or conditions.
+> >       Notwithstanding the above, nothing herein shall supersede or modify
+> >       the terms of any separate license agreement you may have executed
+> >       with Licensor regarding such Contributions.
+> >
+> >    6. Trademarks. This License does not grant permission to use the trade
+> >       names, trademarks, service marks, or product names of the Licensor,
+> >       except as required for reasonable and customary use in describing the
+> >       origin of the Work and reproducing the content of the NOTICE file.
+> >
+> >    7. Disclaimer of Warranty. Unless required by applicable law or
+> >       agreed to in writing, Licensor provides the Work (and each
+> >       Contributor provides its Contributions) on an "AS IS" BASIS,
+> >       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+> >       implied, including, without limitation, any warranties or conditions
+> >       of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+> >       PARTICULAR PURPOSE. You are solely responsible for determining the
+> >       appropriateness of using or redistributing the Work and assume any
+> >       risks associated with Your exercise of permissions under this License.
+> >
+> >    8. Limitation of Liability. In no event and under no legal theory,
+> >       whether in tort (including negligence), contract, or otherwise,
+> >       unless required by applicable law (such as deliberate and grossly
+> >       negligent acts) or agreed to in writing, shall any Contributor be
+> >       liable to You for damages, including any direct, indirect, special,
+> >       incidental, or consequential damages of any character arising as a
+> >       result of this License or out of the use or inability to use the
+> >       Work (including but not limited to damages for loss of goodwill,
+> >       work stoppage, computer failure or malfunction, or any and all
+> >       other commercial damages or losses), even if such Contributor
+> >       has been advised of the possibility of such damages.
+> >
+> >    9. Accepting Warranty or Additional Liability. While redistributing
+> >       the Work or Derivative Works thereof, You may choose to offer,
+> >       and charge a fee for, acceptance of support, warranty, indemnity,
+> >       or other liability obligations and/or rights consistent with this
+> >       License. However, in accepting such obligations, You may act only
+> >       on Your own behalf and on Your sole responsibility, not on behalf
+> >       of any other Contributor, and only if You agree to indemnify,
+> >       defend, and hold each Contributor harmless for any liability
+> >       incurred by, or claims asserted against, such Contributor by reason
+> >       of your accepting any such warranty or additional liability.
+> >
+> >    END OF TERMS AND CONDITIONS
+> >
+> >    APPENDIX: How to apply the Apache License to your work.
+> >
+> >       To apply the Apache License to your work, attach the following
+> >       boilerplate notice, with the fields enclosed by brackets "[]"
+> >       replaced with your own identifying information. (Don't include
+> >       the brackets!)  The text should be enclosed in the appropriate
+> >       comment syntax for the file format. We also recommend that a
+> >       file or class name and description of purpose be included on the
+> >       same "printed page" as the copyright notice for easier
+> >       identification within third-party archives.
+> >
+> >    Copyright [yyyy] [name of copyright owner]
+> >
+> >    Licensed under the Apache License, Version 2.0 (the "License");
+> >    you may not use this file except in compliance with the License.
+> >    You may obtain a copy of the License at
+> >
+> >        http://www.apache.org/licenses/LICENSE-2.0
+> >
+> >    Unless required by applicable law or agreed to in writing, software
+> >    distributed under the License is distributed on an "AS IS" BASIS,
+> >    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+> >    See the License for the specific language governing permissions and
+> >    limitations under the License.
 
 <!-- /TYPE_DEPENDENCIES -->

package/dist/adapters/better-sqlite3.mjs

@@ -1,29 +1 @@
-const createBetterSqlite3Adapter = (database) => {
-  return {
-    exec(sql, params) {
-      if (params && params.length > 0) {
-        database.prepare(sql).run([...params]);
-      } else {
-        database.exec(sql);
-      }
-    },
-    query(sql, params) {
-      const stmt = database.prepare(sql);
-      const rows = params && params.length > 0 ? stmt.all([...params]) : stmt.all();
-      return rows;
-    },
-    transaction(function_) {
-      const wrapped = database.transaction(function_);
-      wrapped();
-    },
-    lastInsertRowId() {
-      const row = database.prepare("SELECT last_insert_rowid() AS id").get();
-      return Number(row?.id ?? -1);
-    },
-    close() {
-      database.close();
-    }
-  };
-};
-
-export { createBetterSqlite3Adapter };
+const c=t=>({exec(e,r){r&&r.length>0?t.prepare(e).run([...r]):t.exec(e)},query(e,r){const n=t.prepare(e);return r&&r.length>0?n.all([...r]):n.all()},transaction(e){t.transaction(e)()},lastInsertRowId(){const e=t.prepare("SELECT last_insert_rowid() AS id").get();return Number(e?.id??-1)},close(){t.close()}});export{c as createBetterSqlite3Adapter};

package/dist/adapters/sqlite-wasm.d.mts

@@ -10,7 +10,7 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.mjs";
  * IMPORTANT (REPLICA-01): the real `oo1.DB.exec()` does NOT return sql.js's
  * `{ columns, values }[]` result shape — with `rowMode: "object"` and
  * `returnValue: "resultRows"` it returns the rows directly, as
- * `Record<string, unknown>[]`. This adapter is written against that real
+ * `Record<string, unknown>[]`. This adapter is written against that real
  * shape; `lastInsertRowId` uses the driver's `selectValue()` convenience
  * method (a single-scalar query helper) rather than parsing a result-row
  * array.
@@ -18,7 +18,7 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.mjs";
  * @param database.close Tear down the database connection.
  * @param database.exec Execute SQL with optional bind params. With
  * `{ returnValue: "resultRows", rowMode: "object" }` it returns the matched
- * rows directly (`Record&lt;string, unknown>[]`); otherwise (DDL/DML/BEGIN/
+ * rows directly (`Record<string, unknown>[]`); otherwise (DDL/DML/BEGIN/
  * COMMIT/ROLLBACK) its return value is unused here.
  * @param database.selectValue Run a query and return the first column of the
  * first row as a single scalar — used for `SELECT last_insert_rowid()`.

package/dist/adapters/sqlite-wasm.d.ts

@@ -10,7 +10,7 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.js";
  * IMPORTANT (REPLICA-01): the real `oo1.DB.exec()` does NOT return sql.js's
  * `{ columns, values }[]` result shape — with `rowMode: "object"` and
  * `returnValue: "resultRows"` it returns the rows directly, as
- * `Record<string, unknown>[]`. This adapter is written against that real
+ * `Record<string, unknown>[]`. This adapter is written against that real
  * shape; `lastInsertRowId` uses the driver's `selectValue()` convenience
  * method (a single-scalar query helper) rather than parsing a result-row
  * array.
@@ -18,7 +18,7 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-CkMkSwLJ.js";
  * @param database.close Tear down the database connection.
  * @param database.exec Execute SQL with optional bind params. With
  * `{ returnValue: "resultRows", rowMode: "object" }` it returns the matched
- * rows directly (`Record&lt;string, unknown>[]`); otherwise (DDL/DML/BEGIN/
+ * rows directly (`Record<string, unknown>[]`); otherwise (DDL/DML/BEGIN/
  * COMMIT/ROLLBACK) its return value is unused here.
  * @param database.selectValue Run a query and return the first column of the
  * first row as a single scalar — used for `SELECT last_insert_rowid()`.

package/dist/adapters/sqlite-wasm.mjs

@@ -1,44 +1 @@
-const createSqliteWasmAdapter = (database) => {
-  return {
-    exec(sql, params) {
-      if (params && params.length > 0) {
-        database.exec(sql, { bind: [...params] });
-      } else {
-        database.exec(sql);
-      }
-    },
-    query(sql, params) {
-      const rows = database.exec(sql, {
-        bind: params && params.length > 0 ? [...params] : void 0,
-        returnValue: "resultRows",
-        rowMode: "object"
-      });
-      return rows ?? [];
-    },
-    transaction(function_) {
-      database.exec("BEGIN");
-      try {
-        function_();
-        database.exec("COMMIT");
-      } catch (error) {
-        database.exec("ROLLBACK");
-        throw error;
-      }
-    },
-    lastInsertRowId() {
-      const value = database.selectValue("SELECT last_insert_rowid()");
-      if (typeof value === "number") {
-        return value;
-      }
-      if (typeof value === "bigint") {
-        return Number(value);
-      }
-      return -1;
-    },
-    close() {
-      database.close();
-    }
-  };
-};
-
-export { createSqliteWasmAdapter };
+const n=t=>({exec(e,r){r&&r.length>0?t.exec(e,{bind:[...r]}):t.exec(e)},query(e,r){return t.exec(e,{bind:r&&r.length>0?[...r]:void 0,returnValue:"resultRows",rowMode:"object"})??[]},transaction(e){t.exec("BEGIN");try{e(),t.exec("COMMIT")}catch(r){throw t.exec("ROLLBACK"),r}},lastInsertRowId(){const e=t.selectValue("SELECT last_insert_rowid()");return typeof e=="number"?e:typeof e=="bigint"?Number(e):-1},close(){t.close()}});export{n as createSqliteWasmAdapter};

package/dist/adapters/sqljs.mjs

@@ -1,55 +1 @@
-const createSqlJsAdapter = (database) => {
-  return {
-    exec(sql, params) {
-      if (params && params.length > 0) {
-        database.run(sql, [...params]);
-      } else {
-        database.exec(sql);
-      }
-    },
-    query(sql, params) {
-      const result = params && params.length > 0 ? database.exec(sql, [...params]) : database.exec(sql);
-      const first = result[0];
-      if (!first) {
-        return [];
-      }
-      const colNames = first.columns;
-      const rows = [];
-      for (const row of first.values) {
-        const object = {};
-        for (const [i, column] of colNames.entries()) {
-          object[column] = row[i];
-        }
-        rows.push(object);
-      }
-      return rows;
-    },
-    transaction(function_) {
-      database.run("BEGIN");
-      try {
-        function_();
-        database.run("COMMIT");
-      } catch (error) {
-        database.run("ROLLBACK");
-        throw error;
-      }
-    },
-    lastInsertRowId() {
-      const result = database.exec("SELECT last_insert_rowid() AS id");
-      const firstRow = result[0];
-      if (result.length === 0 || !firstRow || firstRow.values.length === 0) {
-        return -1;
-      }
-      const value = firstRow.values[0];
-      if (!value || value.length === 0) {
-        return -1;
-      }
-      return Number(value[0]);
-    },
-    close() {
-      database.close();
-    }
-  };
-};
-
-export { createSqlJsAdapter };
+const h=n=>({exec(r,e){e&&e.length>0?n.run(r,[...e]):n.exec(r)},query(r,e){const o=(e&&e.length>0?n.exec(r,[...e]):n.exec(r))[0];if(!o)return[];const l=o.columns,c=[];for(const s of o.values){const u={};for(const[i,f]of l.entries())u[f]=s[i];c.push(u)}return c},transaction(r){n.run("BEGIN");try{r(),n.run("COMMIT")}catch(e){throw n.run("ROLLBACK"),e}},lastInsertRowId(){const r=n.exec("SELECT last_insert_rowid() AS id"),e=r[0];if(r.length===0||!e||e.values.length===0)return-1;const t=e.values[0];return!t||t.length===0?-1:Number(t[0])},close(){n.close()}});export{h as createSqlJsAdapter};

package/dist/index.d.mts

@@ -1,9 +1,24 @@
-export { createBetterSqlite3Adapter } from "./adapters/better-sqlite3.mjs";
+export {
+/**
+ * \@lunora/replica — Event sourcing runtime + local SQLite mirror for Lunora
+ *
+ * ## Modules
+ *
+ * - **EventEmitter** — type-safe event emitter with typed + wildcard listeners.
+ * - **EventSource** — event-sourcing runtime that derives state from an
+ * append-only log via a reducer.
+ * - **SubscriptionManager** — manages state and event-type subscriptions.
+ * - **SnapshotStore** — interface + in-memory store for persisting
+ * event-sourced state snapshots.
+ * - **LocalMirror** — local SQLite mirror that applies typed table diffs.
+ * - **EventLog** — append-only log for events and catch-up replication.
+ */
+createBetterSqlite3Adapter } from "./adapters/better-sqlite3.mjs";
 export { createSqliteWasmAdapter } from "./adapters/sqlite-wasm.mjs";
 export { createSqlJsAdapter } from "./adapters/sqljs.mjs";
 import { S as SqliteAdapter } from "./packem_shared/types.d-CkMkSwLJ.mjs";
-import { T as TableDiff, I as InputEvent, S as Seq, E as EventLogEntry, a as EventLog, A as AppendOptions, L as LocalMirror } from "./packem_shared/local-mirror.d-DTavX_y0.mjs";
-export { type C as ClientSeq, type b as EventLogOptions, type c as EventLogSnapshot, type G as GlobalSeq, type d as LocalMirrorOptions, type M as MirrorTableDef, type R as RowChange, e as classifyChanges, f as createTableDiff, g as diffSize, i as isClientSeq, h as isDiffEmpty, j as isGlobalSeq, k as isInputEvent, m as mergeDiffs } from "./packem_shared/local-mirror.d-DTavX_y0.mjs";
+import { T as TableDiff, I as InputEvent, S as Seq, E as EventLogEntry, a as EventLog, A as AppendOptions, L as LocalMirror } from "./packem_shared/local-mirror.d-Cip3QuMf.mjs";
+export { type C as ClientSeq, type b as EventLogOptions, type c as EventLogSnapshot, type G as GlobalSeq, type d as LocalMirrorOptions, type M as MirrorTableDef, type R as RowChange, e as classifyChanges, f as createTableDiff, g as diffSize, i as isClientSeq, h as isDiffEmpty, j as isGlobalSeq, k as isInputEvent, m as mergeDiffs } from "./packem_shared/local-mirror.d-Cip3QuMf.mjs";
 /**
  * Apply a single {@link TableDiff} to an in-memory row map and return
  * the updated map.
@@ -30,15 +45,16 @@ declare const applyDiff: (current: ReadonlyMap<string, Record<string, unknown>>,
 /**
  * Apply an array of diffs **in order**, returning the final row map.
  *
- * This is equivalent to calling {@link applyDiff} repeatedly but avoids
- * intermediate map copies.
+ * This is equivalent to calling {@link applyDiff} repeatedly but copies the
+ * input map exactly once rather than once per diff — catch-up replay of an
+ * N-diff backlog is a single copy, not N+1.
  * @experimental
  */
 declare const applyDiffs: (current: ReadonlyMap<string, Record<string, unknown>>, diffs: ReadonlyArray<TableDiff>) => Map<string, Record<string, unknown>>;
 /**
  * Merge the row-level effect of a {@link TableDiff} into plain JSON
  * state keyed by table name, returning a new snapshot.
- * @param snapshot Current snapshot, e.g. `{ users: Map&lt;id, row>, posts: Map&lt;id, row> }`.
+ * @param snapshot Current snapshot, e.g. `{ users: Map<id, row>, posts: Map<id, row> }`.
  * @param diff Contains the target table name and the row-level changes to merge.
  * @returns A shallow copy of `snapshot` with `diff.table`'s map updated.
  * @experimental
@@ -105,7 +121,7 @@ interface DefineEventsOptions {
   /**
    * Optional version prefix for all event types.
    *
-   * When set, every qualified event type is prefixed with `"v&lt;N>."`, enabling
+   * When set, every qualified event type is prefixed with `"v<N>."`, enabling
    * versioned event naming like `"v1.chat.messageSent"` or `"v2.chat.messageSent"`.
    * This allows materializers to evolve their handling logic based on the event
    * version without breaking backward compatibility.
@@ -271,8 +287,8 @@ type UnknownEventHandling = "warn" | "ignore" | "fail" | ((entry: EventLogEntry)
  * Events emitted by the {@link EventSource} runtime.
  *
  * A `type` (not `interface`) so it satisfies `EventEmitter`'s
- * `Record&lt;string, unknown>` constraint — interfaces have no implicit index
- * signature and aren't assignable to `Record&lt;string, unknown>`.
+ * `Record<string, unknown>` constraint — interfaces have no implicit index
+ * signature and aren't assignable to `Record<string, unknown>`.
  * @experimental
  */
 type EventSourceEvents = {
@@ -408,8 +424,10 @@ declare class EventSource<S extends Record<string, unknown> = Record<string, unk
    * starting from the events currently in the log and continuing with
    * every future `applyEvent` / `replayFromLog` call.
    *
-   * The generator runs indefinitely — it never returns. Callers should
-   * break out of the `for await` loop or use an `AbortSignal` to stop.
+   * The generator runs indefinitely unless given a `signal` — callers
+   * should break out of the `for await` loop or pass an `AbortSignal` to
+   * stop it (an abort settles the generator, `done: true`, on its next
+   * iteration step; it does not throw).
    * @example
    * ```ts
    * for await (const entry of source.events()) {
@@ -506,9 +524,9 @@ declare const defineMaterializer: <S>(definition: MaterializerDef<S>) => Materia
  * A materializer of any state shape. The {@link MaterializerRuntime} holds a
  * heterogeneous collection and only ever calls `apply(entry)` / `setState(...)`
  * (with cast values) / reads `def.name` — it never needs the concrete state
- * type. `Materializer&lt;unknown>` won't do: `setState(state: S)` makes
- * `Materializer&lt;S>` invariant in `S`, so `Materializer&lt;number>` isn't assignable
- * to `Materializer&lt;unknown>`. Erasing the type param is the idiomatic fix.
+ * type. `Materializer<unknown>` won't do: `setState(state: S)` makes
+ * `Materializer<S>` invariant in `S`, so `Materializer<number>` isn't assignable
+ * to `Materializer<unknown>`. Erasing the type param is the idiomatic fix.
  */
 type AnyMaterializer = Materializer<any>;
 /**
@@ -895,8 +913,17 @@ interface EventsSyncOptions {
    * Produce {@link TableDiff | TableDiffs} from the current derived state.
    *
    * Called after every batch of events has been applied. The consumer
-   * compares the state _before_ and _after_ the batch and returns the
-   * diffs needed to bring the LocalMirror up to date.
+   * **recomputes a full diff from the current mirror-vs-source state** and
+   * returns the diffs needed to bring the LocalMirror up to date.
+   *
+   * **MUST be idempotent** — it must NOT advance a one-shot cursor as a side
+   * effect. A batch that fails partway (a `mirror.applyDiff` throws) is
+   * retried on the next poll from the same watermark; if this call consumed a
+   * cursor on the first attempt it would return `[]` on the retry and the
+   * un-mirrored diffs would be lost forever. Recompute-from-current-state has
+   * no such hazard: calling it again with no new events returns the same
+   * diffs, and calling it after a partial mirror write returns exactly the
+   * diffs still missing from the mirror.
    *
    * Return an empty array when there are no changes to push to the mirror.
    */

package/dist/index.d.ts

@@ -1,9 +1,24 @@
-export { createBetterSqlite3Adapter } from "./adapters/better-sqlite3.js";
+export {
+/**
+ * \@lunora/replica — Event sourcing runtime + local SQLite mirror for Lunora
+ *
+ * ## Modules
+ *
+ * - **EventEmitter** — type-safe event emitter with typed + wildcard listeners.
+ * - **EventSource** — event-sourcing runtime that derives state from an
+ * append-only log via a reducer.
+ * - **SubscriptionManager** — manages state and event-type subscriptions.
+ * - **SnapshotStore** — interface + in-memory store for persisting
+ * event-sourced state snapshots.
+ * - **LocalMirror** — local SQLite mirror that applies typed table diffs.
+ * - **EventLog** — append-only log for events and catch-up replication.
+ */
+createBetterSqlite3Adapter } from "./adapters/better-sqlite3.js";
 export { createSqliteWasmAdapter } from "./adapters/sqlite-wasm.js";
 export { createSqlJsAdapter } from "./adapters/sqljs.js";
 import { S as SqliteAdapter } from "./packem_shared/types.d-CkMkSwLJ.js";
-import { T as TableDiff, I as InputEvent, S as Seq, E as EventLogEntry, a as EventLog, A as AppendOptions, L as LocalMirror } from "./packem_shared/local-mirror.d-CyGOpUES.js";
-export { type C as ClientSeq, type b as EventLogOptions, type c as EventLogSnapshot, type G as GlobalSeq, type d as LocalMirrorOptions, type M as MirrorTableDef, type R as RowChange, e as classifyChanges, f as createTableDiff, g as diffSize, i as isClientSeq, h as isDiffEmpty, j as isGlobalSeq, k as isInputEvent, m as mergeDiffs } from "./packem_shared/local-mirror.d-CyGOpUES.js";
+import { T as TableDiff, I as InputEvent, S as Seq, E as EventLogEntry, a as EventLog, A as AppendOptions, L as LocalMirror } from "./packem_shared/local-mirror.d-ByrYTq4z.js";
+export { type C as ClientSeq, type b as EventLogOptions, type c as EventLogSnapshot, type G as GlobalSeq, type d as LocalMirrorOptions, type M as MirrorTableDef, type R as RowChange, e as classifyChanges, f as createTableDiff, g as diffSize, i as isClientSeq, h as isDiffEmpty, j as isGlobalSeq, k as isInputEvent, m as mergeDiffs } from "./packem_shared/local-mirror.d-ByrYTq4z.js";
 /**
  * Apply a single {@link TableDiff} to an in-memory row map and return
  * the updated map.
@@ -30,15 +45,16 @@ declare const applyDiff: (current: ReadonlyMap<string, Record<string, unknown>>,
 /**
  * Apply an array of diffs **in order**, returning the final row map.
  *
- * This is equivalent to calling {@link applyDiff} repeatedly but avoids
- * intermediate map copies.
+ * This is equivalent to calling {@link applyDiff} repeatedly but copies the
+ * input map exactly once rather than once per diff — catch-up replay of an
+ * N-diff backlog is a single copy, not N+1.
  * @experimental
  */
 declare const applyDiffs: (current: ReadonlyMap<string, Record<string, unknown>>, diffs: ReadonlyArray<TableDiff>) => Map<string, Record<string, unknown>>;
 /**
  * Merge the row-level effect of a {@link TableDiff} into plain JSON
  * state keyed by table name, returning a new snapshot.
- * @param snapshot Current snapshot, e.g. `{ users: Map&lt;id, row>, posts: Map&lt;id, row> }`.
+ * @param snapshot Current snapshot, e.g. `{ users: Map<id, row>, posts: Map<id, row> }`.
  * @param diff Contains the target table name and the row-level changes to merge.
  * @returns A shallow copy of `snapshot` with `diff.table`'s map updated.
  * @experimental
@@ -105,7 +121,7 @@ interface DefineEventsOptions {
   /**
    * Optional version prefix for all event types.
    *
-   * When set, every qualified event type is prefixed with `"v&lt;N>."`, enabling
+   * When set, every qualified event type is prefixed with `"v<N>."`, enabling
    * versioned event naming like `"v1.chat.messageSent"` or `"v2.chat.messageSent"`.
    * This allows materializers to evolve their handling logic based on the event
    * version without breaking backward compatibility.
@@ -271,8 +287,8 @@ type UnknownEventHandling = "warn" | "ignore" | "fail" | ((entry: EventLogEntry)
  * Events emitted by the {@link EventSource} runtime.
  *
  * A `type` (not `interface`) so it satisfies `EventEmitter`'s
- * `Record&lt;string, unknown>` constraint — interfaces have no implicit index
- * signature and aren't assignable to `Record&lt;string, unknown>`.
+ * `Record<string, unknown>` constraint — interfaces have no implicit index
+ * signature and aren't assignable to `Record<string, unknown>`.
  * @experimental
  */
 type EventSourceEvents = {
@@ -408,8 +424,10 @@ declare class EventSource<S extends Record<string, unknown> = Record<string, unk
    * starting from the events currently in the log and continuing with
    * every future `applyEvent` / `replayFromLog` call.
    *
-   * The generator runs indefinitely — it never returns. Callers should
-   * break out of the `for await` loop or use an `AbortSignal` to stop.
+   * The generator runs indefinitely unless given a `signal` — callers
+   * should break out of the `for await` loop or pass an `AbortSignal` to
+   * stop it (an abort settles the generator, `done: true`, on its next
+   * iteration step; it does not throw).
    * @example
    * ```ts
    * for await (const entry of source.events()) {
@@ -506,9 +524,9 @@ declare const defineMaterializer: <S>(definition: MaterializerDef<S>) => Materia
  * A materializer of any state shape. The {@link MaterializerRuntime} holds a
  * heterogeneous collection and only ever calls `apply(entry)` / `setState(...)`
  * (with cast values) / reads `def.name` — it never needs the concrete state
- * type. `Materializer&lt;unknown>` won't do: `setState(state: S)` makes
- * `Materializer&lt;S>` invariant in `S`, so `Materializer&lt;number>` isn't assignable
- * to `Materializer&lt;unknown>`. Erasing the type param is the idiomatic fix.
+ * type. `Materializer<unknown>` won't do: `setState(state: S)` makes
+ * `Materializer<S>` invariant in `S`, so `Materializer<number>` isn't assignable
+ * to `Materializer<unknown>`. Erasing the type param is the idiomatic fix.
  */
 type AnyMaterializer = Materializer<any>;
 /**
@@ -895,8 +913,17 @@ interface EventsSyncOptions {
    * Produce {@link TableDiff | TableDiffs} from the current derived state.
    *
    * Called after every batch of events has been applied. The consumer
-   * compares the state _before_ and _after_ the batch and returns the
-   * diffs needed to bring the LocalMirror up to date.
+   * **recomputes a full diff from the current mirror-vs-source state** and
+   * returns the diffs needed to bring the LocalMirror up to date.
+   *
+   * **MUST be idempotent** — it must NOT advance a one-shot cursor as a side
+   * effect. A batch that fails partway (a `mirror.applyDiff` throws) is
+   * retried on the next poll from the same watermark; if this call consumed a
+   * cursor on the first attempt it would return `[]` on the retry and the
+   * un-mirrored diffs would be lost forever. Recompute-from-current-state has
+   * no such hazard: calling it again with no new events returns the same
+   * diffs, and calling it after a partial mirror write returns exactly the
+   * diffs still missing from the mirror.
    *
    * Return an empty array when there are no changes to push to the mirror.
    */

package/dist/index.mjs

@@ -1,20 +1 @@
-export { createBetterSqlite3Adapter } from './adapters/better-sqlite3.mjs';
-export { createSqliteWasmAdapter } from './adapters/sqlite-wasm.mjs';
-export { createSqlJsAdapter } from './adapters/sqljs.mjs';
-export { applyDiff, applyDiffToSnapshot, applyDiffs } from './packem_shared/applyDiff-98tKzmiW.mjs';
-export { defineEvents } from './packem_shared/defineEvents-DiBkPTh_.mjs';
-export { MaterializerRuntime, defineMaterializer } from './packem_shared/MaterializerRuntime-BoIrsMYB.mjs';
-export { applyDiffToDb, applyDiffsToDb } from './packem_shared/applyDiffToDb-DQ1xZp5J.mjs';
-export { EventEmitter } from './packem_shared/EventEmitter-CMZfct03.mjs';
-export { EventLog } from './packem_shared/EventLog-CnK-3Wge.mjs';
-export { EventLogDO } from './packem_shared/EventLogDO-DqlsVx0H.mjs';
-export { EventLogDOClient } from './packem_shared/EventLogDOClient-F4FO8Si4.mjs';
-export { EventSource, UNHANDLED } from './packem_shared/EventSource-D5yO9_aI.mjs';
-export { eventsContext } from './packem_shared/eventsContext-Bk_p48hj.mjs';
-export { LocalMirror } from './packem_shared/LocalMirror-a-5jEqFN.mjs';
-export { isClientSeq, isGlobalSeq, isInputEvent } from './packem_shared/isClientSeq-C46BkzqJ.mjs';
-export { InMemorySnapshotStore } from './packem_shared/InMemorySnapshotStore-BHVAD-Bp.mjs';
-export { subscribeToMirror } from './packem_shared/subscribeToMirror-CiaM-nQ7.mjs';
-export { SubscriptionManager } from './packem_shared/SubscriptionManager-C5xbw0pg.mjs';
-export { EventsSync } from './packem_shared/EventsSync-BP36tC9O.mjs';
-export { classifyChanges, createTableDiff, diffSize, isDiffEmpty, mergeDiffs } from './packem_shared/classifyChanges-RcqLBpLs.mjs';
+import{createBetterSqlite3Adapter as o}from"./adapters/better-sqlite3.mjs";import{createSqliteWasmAdapter as f}from"./adapters/sqlite-wasm.mjs";import{createSqlJsAdapter as i}from"./adapters/sqljs.mjs";import{applyDiff as m,applyDiffToSnapshot as n,applyDiffs as x}from"./packem_shared/applyDiff-Da160K7_.mjs";import{defineEvents as l}from"./packem_shared/defineEvents-DHo-VK7G.mjs";import{MaterializerRuntime as S,defineMaterializer as E}from"./packem_shared/MaterializerRuntime-D0HOAe24.mjs";import{applyDiffToDb as v,applyDiffsToDb as y}from"./packem_shared/applyDiffToDb-C6ek5Elp.mjs";import{EventEmitter as d}from"./packem_shared/EventEmitter-uo75adUL.mjs";import{EventLog as M}from"./packem_shared/EventLog-B1-yhArT.mjs";import{EventLogDO as u}from"./packem_shared/EventLogDO-CaZvpgJN.mjs";import{EventLogDOClient as T}from"./packem_shared/EventLogDOClient-DGDMj5L5.mjs";import{EventSource as C,UNHANDLED as h}from"./packem_shared/EventSource-BC0hKJSA.mjs";import{eventsContext as I}from"./packem_shared/eventsContext-Dxow9Y7S.mjs";import{LocalMirror as O}from"./packem_shared/LocalMirror-BIURA-He.mjs";import{isClientSeq as G,isGlobalSeq as H,isInputEvent as J}from"./packem_shared/isClientSeq-D2Xm0_lj.mjs";import{InMemorySnapshotStore as U}from"./packem_shared/InMemorySnapshotStore-C4taIG5K.mjs";import{subscribeToMirror as j}from"./packem_shared/subscribeToMirror-CX10AaP3.mjs";import{SubscriptionManager as w}from"./packem_shared/SubscriptionManager-AhPw3lFc.mjs";import{EventsSync as K}from"./packem_shared/EventsSync-DWyGGZQZ.mjs";import{classifyChanges as Q,createTableDiff as V,diffSize as X,isDiffEmpty as Y,mergeDiffs as Z}from"./packem_shared/classifyChanges-ioMfjjbU.mjs";export{d as EventEmitter,M as EventLog,u as EventLogDO,T as EventLogDOClient,C as EventSource,K as EventsSync,U as InMemorySnapshotStore,O as LocalMirror,S as MaterializerRuntime,w as SubscriptionManager,h as UNHANDLED,m as applyDiff,v as applyDiffToDb,n as applyDiffToSnapshot,x as applyDiffs,y as applyDiffsToDb,Q as classifyChanges,o as createBetterSqlite3Adapter,i as createSqlJsAdapter,f as createSqliteWasmAdapter,V as createTableDiff,l as defineEvents,E as defineMaterializer,X as diffSize,I as eventsContext,G as isClientSeq,Y as isDiffEmpty,H as isGlobalSeq,J as isInputEvent,Z as mergeDiffs,j as subscribeToMirror};