@lunora/replica 1.0.0-alpha.9 → 1.0.0-alpha.91

package/dist/packem_shared/{local-mirror.d-DTavX_y0.d.mts → local-mirror.d-DzREvGNM.d.mts}

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "./types.d-CkMkSwLJ.mjs";
+import { S as SqliteAdapter } from "./types.d-BuLTPLaQ.mjs";
 /**
  * Row-level change kind within a TableDiff.
  *
@@ -31,13 +31,14 @@ interface TableDiff {
   /**
    * 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.
+   * alone is not a unique diff identity). `createTableDiff` auto-generates
+   * one when omitted.
+   *
+   * **Nothing in the apply path reads it.** `deriveInsertId` (`apply-diff.ts`)
+   * keys an id-less insert off the ROW'S OWN content — hashing the diff id
+   * into it is what made `subscribeToMirror`'s per-frame re-emission mint a
+   * fresh row every second, so that derivation is gone. This field is
+   * carried for consumers that want to recognise a diff they have seen.
    */
   readonly id?: string;
   /** Logical table name (matches the schema table name). */
@@ -140,7 +141,7 @@ declare const isClientSeq: (seq: Seq) => seq is ClientSeq;
  *
  * ```ts
  * const event = events.chat.messageSent({ channelId: "c1", text: "hello" });
- * // event: InputEvent<"chat.messageSent", { channelId: string; text: string }>
+ * // event: InputEvent<"chat.messageSent", { channelId: string; text: string }>
  * ```
  * @experimental
  */
@@ -312,6 +313,11 @@ declare class EventLog {
   getSince(sinceSeq: number): ReadonlyArray<EventLogEntry>;
   /**
    * Paginated read starting at `fromSeq`.
+   *
+   * `limit` must be a positive safe integer, validated like
+   * {@link EventLog#truncateBelow}'s floor and the constructor's `maxEntries`:
+   * a `limit` of `0` returned an empty page with `hasMore: true`, which spins a
+   * paginating caller forever on a page it can never advance past.
    * @returns `{ entries, hasMore }` where `hasMore` is `true` when more
    * entries exist beyond the requested page.
    */
@@ -381,15 +387,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.
+   * Cap the mirror's internal {@link EventLog} to this many entries.
+   * Every applied diff is recorded in the log, so an uncapped log grows by
+   * one entry (holding every changed row) per diff for the life of the
+   * mirror — a leak by construction on a long-lived client.
    *
-   * `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.
+   * Defaults to {@link DEFAULT_MAX_EVENT_LOG_ENTRIES}. On overflow the
+   * OLDEST entries are dropped; nothing in the mirror replays its own log,
+   * so a drop loses nothing the mirror needs. A consumer that does replay
+   * it (`eventLog.getSince(watermark)` from another tab / service worker)
+   * detects a gap when the first returned entry's `seq` is above its
+   * watermark, and should re-seed from the mirror's rows (`query`) instead
+   * of applying the partial window.
    */
   readonly maxEventLogEntries?: number;
   /**
@@ -402,6 +411,15 @@ interface LocalMirrorOptions {
    */
   readonly tables?: Record<string, MirrorTableDef>;
 }
+/**
+ * Why the mirror changed: `"diff"` for the rows an {@link LocalMirror.applyDiff}
+ * wrote, `"clear"` for the wholesale {@link LocalMirror.clearData} sweep.
+ *
+ * A subscriber that caches what it believes the mirror holds has to tell the two
+ * apart: `"diff"` reports a change it usually made itself, while `"clear"` means
+ * every row it was tracking is gone regardless of who wrote it.
+ */
+type MirrorChangeReason = "clear" | "diff";
 /**
  * Local SQLite mirror that maintains a client-side replica of server
  * tables by applying {@link TableDiff} deltas.
@@ -420,13 +438,13 @@ interface LocalMirrorOptions {
  * mirror.applyDiff(someDiff);
  *
  * // Query locally:
- * const rows = mirror.query&lt;{ id: string; name: string }>(
+ * const rows = mirror.query<{ id: string; name: string }>(
  *   "SELECT id, name FROM users WHERE name LIKE ?",
  *   ["alice%"],
  * );
  * ```
  */
-type ChangeSubscriber = () => void;
+type ChangeSubscriber = (reason: MirrorChangeReason) => void;
 /**
  * `LocalMirror` is part of the experimental `@lunora/replica` API and may change without a major version bump.
  * @experimental
@@ -504,8 +522,17 @@ declare class LocalMirror {
    */
   query<T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>): T[];
   /**
-   * Delete every row from all known tables (preserves the event log
-   * and schema). Useful when re-syncing from scratch.
+   * Delete every row from every data table in the adapter's database
+   * (preserves the event log and schema). Useful when re-syncing from scratch.
+   *
+   * **The mirror owns its database.** The sweep is `sqlite_master` minus the
+   * reserved prefixes, NOT {@link LocalMirror.mirroredTables} — a table this
+   * mirror never registered is cleared too, and `#reconcileSchemaVersion`
+   * DROPs on the same list. It cannot be narrowed to the registered set: that
+   * runs from the constructor, before any `applyDiff` has re-registered the
+   * tables a previous session persisted, and those are exactly the
+   * stale-schema tables it exists to drop. So hand the adapter a database
+   * dedicated to the mirror, never one that also holds your own tables.
    *
    * Notifies `onChange` subscribers and bumps {@link LocalMirror.version}
    * (REPLICA-09) even though nothing is appended to the event log — a
@@ -519,9 +546,14 @@ declare class LocalMirror {
   close(): void;
   /**
    * Register a table schema so the mirror can create the table on
-   * first use.
+   * first use. Merges into any definition already registered for `name`
+   * (from the constructor's `tables` or an earlier call), so a helper that
+   * registers `{}` just to make the table known does not erase a
+   * user-supplied `primaryKey`.
    */
   registerTable(name: string, definition: MirrorTableDef): void;
+  /** The primary-key column of a mirrored table (`"id"` unless registered otherwise). */
+  primaryKeyOf(table: string): string;
   /**
    * Return the list of mirrored table names.
    */

package/dist/packem_shared/{local-mirror.d-CyGOpUES.d.ts → local-mirror.d-wbGXkXaE.d.ts}

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "./types.d-CkMkSwLJ.js";
+import { S as SqliteAdapter } from "./types.d-BuLTPLaQ.js";
 /**
  * Row-level change kind within a TableDiff.
  *
@@ -31,13 +31,14 @@ interface TableDiff {
   /**
    * 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.
+   * alone is not a unique diff identity). `createTableDiff` auto-generates
+   * one when omitted.
+   *
+   * **Nothing in the apply path reads it.** `deriveInsertId` (`apply-diff.ts`)
+   * keys an id-less insert off the ROW'S OWN content — hashing the diff id
+   * into it is what made `subscribeToMirror`'s per-frame re-emission mint a
+   * fresh row every second, so that derivation is gone. This field is
+   * carried for consumers that want to recognise a diff they have seen.
    */
   readonly id?: string;
   /** Logical table name (matches the schema table name). */
@@ -140,7 +141,7 @@ declare const isClientSeq: (seq: Seq) => seq is ClientSeq;
  *
  * ```ts
  * const event = events.chat.messageSent({ channelId: "c1", text: "hello" });
- * // event: InputEvent<"chat.messageSent", { channelId: string; text: string }>
+ * // event: InputEvent<"chat.messageSent", { channelId: string; text: string }>
  * ```
  * @experimental
  */
@@ -312,6 +313,11 @@ declare class EventLog {
   getSince(sinceSeq: number): ReadonlyArray<EventLogEntry>;
   /**
    * Paginated read starting at `fromSeq`.
+   *
+   * `limit` must be a positive safe integer, validated like
+   * {@link EventLog#truncateBelow}'s floor and the constructor's `maxEntries`:
+   * a `limit` of `0` returned an empty page with `hasMore: true`, which spins a
+   * paginating caller forever on a page it can never advance past.
    * @returns `{ entries, hasMore }` where `hasMore` is `true` when more
    * entries exist beyond the requested page.
    */
@@ -381,15 +387,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.
+   * Cap the mirror's internal {@link EventLog} to this many entries.
+   * Every applied diff is recorded in the log, so an uncapped log grows by
+   * one entry (holding every changed row) per diff for the life of the
+   * mirror — a leak by construction on a long-lived client.
    *
-   * `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.
+   * Defaults to {@link DEFAULT_MAX_EVENT_LOG_ENTRIES}. On overflow the
+   * OLDEST entries are dropped; nothing in the mirror replays its own log,
+   * so a drop loses nothing the mirror needs. A consumer that does replay
+   * it (`eventLog.getSince(watermark)` from another tab / service worker)
+   * detects a gap when the first returned entry's `seq` is above its
+   * watermark, and should re-seed from the mirror's rows (`query`) instead
+   * of applying the partial window.
    */
   readonly maxEventLogEntries?: number;
   /**
@@ -402,6 +411,15 @@ interface LocalMirrorOptions {
    */
   readonly tables?: Record<string, MirrorTableDef>;
 }
+/**
+ * Why the mirror changed: `"diff"` for the rows an {@link LocalMirror.applyDiff}
+ * wrote, `"clear"` for the wholesale {@link LocalMirror.clearData} sweep.
+ *
+ * A subscriber that caches what it believes the mirror holds has to tell the two
+ * apart: `"diff"` reports a change it usually made itself, while `"clear"` means
+ * every row it was tracking is gone regardless of who wrote it.
+ */
+type MirrorChangeReason = "clear" | "diff";
 /**
  * Local SQLite mirror that maintains a client-side replica of server
  * tables by applying {@link TableDiff} deltas.
@@ -420,13 +438,13 @@ interface LocalMirrorOptions {
  * mirror.applyDiff(someDiff);
  *
  * // Query locally:
- * const rows = mirror.query&lt;{ id: string; name: string }>(
+ * const rows = mirror.query<{ id: string; name: string }>(
  *   "SELECT id, name FROM users WHERE name LIKE ?",
  *   ["alice%"],
  * );
  * ```
  */
-type ChangeSubscriber = () => void;
+type ChangeSubscriber = (reason: MirrorChangeReason) => void;
 /**
  * `LocalMirror` is part of the experimental `@lunora/replica` API and may change without a major version bump.
  * @experimental
@@ -504,8 +522,17 @@ declare class LocalMirror {
    */
   query<T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>): T[];
   /**
-   * Delete every row from all known tables (preserves the event log
-   * and schema). Useful when re-syncing from scratch.
+   * Delete every row from every data table in the adapter's database
+   * (preserves the event log and schema). Useful when re-syncing from scratch.
+   *
+   * **The mirror owns its database.** The sweep is `sqlite_master` minus the
+   * reserved prefixes, NOT {@link LocalMirror.mirroredTables} — a table this
+   * mirror never registered is cleared too, and `#reconcileSchemaVersion`
+   * DROPs on the same list. It cannot be narrowed to the registered set: that
+   * runs from the constructor, before any `applyDiff` has re-registered the
+   * tables a previous session persisted, and those are exactly the
+   * stale-schema tables it exists to drop. So hand the adapter a database
+   * dedicated to the mirror, never one that also holds your own tables.
    *
    * Notifies `onChange` subscribers and bumps {@link LocalMirror.version}
    * (REPLICA-09) even though nothing is appended to the event log — a
@@ -519,9 +546,14 @@ declare class LocalMirror {
   close(): void;
   /**
    * Register a table schema so the mirror can create the table on
-   * first use.
+   * first use. Merges into any definition already registered for `name`
+   * (from the constructor's `tables` or an earlier call), so a helper that
+   * registers `{}` just to make the table known does not erase a
+   * user-supplied `primaryKey`.
    */
   registerTable(name: string, definition: MirrorTableDef): void;
+  /** The primary-key column of a mirrored table (`"id"` unless registered otherwise). */
+  primaryKeyOf(table: string): string;
   /**
    * Return the list of mirrored table names.
    */

package/dist/packem_shared/subscribeToMirror-DSn8n1IR.mjs

@@ -0,0 +1 @@
+import{s as A}from"./wire-key-DfMHAtqH.mjs";const _=e=>`fn_${e.replaceAll(/[/:.]/g,"_")}`,k=e=>Array.isArray(e)?e:e!==null&&typeof e=="object"?[e]:[],x=(e,o,l,y,g)=>{const a=_(l.__lunoraRef);o.registerTable(a,{});const d=o.primaryKeyOf(a);let r=new Map,f=0;const w=o.onChange(p=>{p==="clear"&&(f+=1,r=new Map)}),h=e.subscribe(l,y,p=>{const M=f,c=new Map,b=new Map,s=[];for(const t of k(p)){const n=t,i=n[d];if(typeof i!="string"&&typeof i!="number"&&typeof i!="bigint"){s.push({type:"insert",data:n});continue}const u=String(i),m=A(n);c.set(u,m),b.set(u,n)}for(const[t,n]of c)r.get(t)!==n&&s.push({data:b.get(t),type:"insert"});for(const t of r.keys())c.has(t)||s.push({type:"delete",id:t});s.length>0&&o.applyDiff({table:a,changes:s,timestamp:Date.now()}),M===f&&(r=c)},{shardKey:g});return()=>{w(),h()}};export{x as subscribeToMirror};

package/dist/packem_shared/{types.d-CkMkSwLJ.d.mts → types.d-BuLTPLaQ.d.mts}

@@ -11,8 +11,6 @@ interface SqliteAdapter {
   close: () => void;
   /** Execute a SQL statement (with optional bound params). */
   exec: (sql: string, params?: ReadonlyArray<unknown>) => void;
-  /** Return the id of the last inserted row. */
-  lastInsertRowId: () => number;
   /**
    * Execute a SQL statement and return the result rows.
    * Columns can be accessed by index or by name.

package/dist/packem_shared/{types.d-CkMkSwLJ.d.ts → types.d-BuLTPLaQ.d.ts}

@@ -11,8 +11,6 @@ interface SqliteAdapter {
   close: () => void;
   /** Execute a SQL statement (with optional bound params). */
   exec: (sql: string, params?: ReadonlyArray<unknown>) => void;
-  /** Return the id of the last inserted row. */
-  lastInsertRowId: () => number;
   /**
    * Execute a SQL statement and return the result rows.
    * Columns can be accessed by index or by name.

package/dist/packem_shared/wire-key-DfMHAtqH.mjs

@@ -0,0 +1 @@
+const m=/["\\\u0000-\u001F\uD800-\uDFFF]/,d=r=>m.test(r)?JSON.stringify(r):`"${r}"`,b=r=>{if(r===void 0)return"null";if(typeof r=="bigint")throw new TypeError("stableStringify: cannot use a bigint in a stable JSON cache key — pass it as a string, or use stableWireKey");if(typeof r=="number"){if(Number.isNaN(r))return"nan";if(r===1/0)return"inf";if(r===-1/0)return"-inf";if(Object.is(r,-0))return"-0"}if(typeof r=="string")return d(r);if(r===null||typeof r!="object")return JSON.stringify(r);if(Array.isArray(r)){let e="[";for(let i=0;i<r.length;i++)i>0&&(e+=","),e+=b(r[i]);return e+"]"}const n=Object.getPrototypeOf(r);if(n!==null&&n!==Object.prototype){const e=r.constructor?.name??"value";throw new TypeError(`stableStringify: cannot use a ${e} in a stable JSON cache key — only plain objects, arrays, and JSON primitives are supported (wire-typed values key via stableWireKey)`)}const y=r,s=Object.keys(y).sort();let f="{",t=!0;for(const e of s){const i=y[e];i!==void 0&&(t?t=!1:f+=",",f+=d(e),f+=":",f+=b(i))}return f+"}"},u=r=>{let n="";for(let s=0;s<r.length;s+=32768)n+=String.fromCharCode(...r.subarray(s,s+32768));return btoa(n)},o="$lunora.wire$";const g="__proto__",w=r=>{if(r===null||typeof r!="object")return!1;const n=Object.getPrototypeOf(r);return n===null||n===Object.prototype},c=(r,n=0)=>{if(n>64)throw new RangeError("wire-codec: value nesting exceeds the 64-level limit");if(r===void 0)return[o,"undefined"];if(r===null)return null;const y=typeof r;if(y==="bigint")return[o,"bigint",r.toString()];if(y==="number"){const t=r;return Number.isNaN(t)?[o,"nan"]:t===1/0?[o,"inf"]:t===-1/0?[o,"-inf"]:t}if(y!=="object")return r;if(r instanceof Date)return[o,"date",c(r.getTime(),n+1)];if(r instanceof Error){const t=r,e={};for(const a of Object.keys(t)){if(t[a]===void 0)continue;const p=c(t[a],n+1);a===g?Object.defineProperty(e,a,{configurable:!0,enumerable:!0,value:p,writable:!0}):e[a]=p}const i=[o,"error",String(t.name),String(t.message),e];return t.cause!==void 0&&i.push(c(t.cause,n+1)),i}if(r instanceof URL)return[o,"url",r.href];if(r instanceof Map)return[o,"map",[...r.entries()].map(([t,e])=>[c(t,n+1),c(e,n+1)])];if(r instanceof Set)return[o,"set",[...r].map(t=>c(t,n+1))];if(r instanceof ArrayBuffer)return[o,"bytes",u(new Uint8Array(r)),"ArrayBuffer"];if(ArrayBuffer.isView(r)){const t=r,e=t.constructor.name,i=new Uint8Array(t.buffer,t.byteOffset,t.byteLength);return e==="Uint8Array"?[o,"bytes",u(i)]:[o,"bytes",u(i),e]}if(Array.isArray(r)){const t=r.map(e=>c(e,n+1));return t.length>0&&t[0]===o?[o,"arr",t]:t}if(!w(r)){const t=r.constructor?.name??"value";throw new TypeError(`wire-codec: cannot encode a ${t} over the Lunora wire — only plain objects, arrays, and the supported built-ins (Date, Error, URL, Map, Set, ArrayBuffer/typed arrays, bigint) round-trip`)}const s=r,f={};for(const t of Object.keys(s)){const e=s[t];if(e===void 0)continue;const i=c(e,n+1);t===g?Object.defineProperty(f,t,{configurable:!0,enumerable:!0,value:i,writable:!0}):f[t]=i}return f},O=r=>b(c(r));export{O as s};

package/dist/react.d.mts

@@ -1,26 +1,36 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-DTavX_y0.mjs";
-import "./packem_shared/types.d-CkMkSwLJ.mjs";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-DzREvGNM.mjs";
+import "./packem_shared/types.d-BuLTPLaQ.mjs";
 /**
- * Options for the {@link useLocalQuery} hook.
+ * Result of {@link useLocalQuery} — a discriminated union so callers get a
+ * typed error instead of a swallowed `undefined`.
  * @experimental
  */
-interface UseLocalQueryOptions {
-  /**
-   * Optional shard key (reserved for future use; currently unused).
-   *
-   * Intended for multi-mirror setups where a single app maintains multiple
-   * SQLite databases sharded by a key (e.g. user id, tenant id). Currently
-   * has no effect — the hook always queries the mirror passed as the first
-   * argument.
-   */
-  shardKey?: string;
-}
+type LocalQueryResult<T> = {
+  readonly data: T[];
+  readonly error?: undefined;
+} | {
+  readonly data?: undefined;
+  readonly error: Error;
+};
 /**
  * React hook that subscribes to a local SQLite query and returns
  * live-updating results whenever the mirror applies a diff.
  *
- * Uses `useSyncExternalStore` to subscribe to the mirror's `onChange`
- * callback — every diff triggers a re-query against the local SQLite.
+ * Uses `useSyncExternalStore` with `getSnapshot` reading {@link LocalMirror.version}
+ * — a plain number, unconditionally `Object.is`-stable across calls with no
+ * mutation in between. The actual query runs in a `useMemo` keyed on
+ * `[mirror, version, sql, stableParamsKey(params)]`, so it only re-executes
+ * when the mirror actually advances (or `sql`/`params` change) — not on
+ * every unrelated re-render.
+ *
+ * This intentionally does NOT cache query results inside {@link LocalMirror}
+ * itself: an LRU-capped cache in the mirror core evicts still-mounted hooks'
+ * entries once more than the cap's worth of distinct live queries are open
+ * on one mirror, which makes `getSnapshot` return a fresh (non-identical)
+ * object on the next read — `useSyncExternalStore` then force-re-renders,
+ * re-inserts, evicts another entry, and so on without bound. Keying the
+ * external-store snapshot on the version primitive instead of a cached
+ * query result has no such cap, so it can't loop.
  *
  * The hook works with React 18+ concurrent features, Suspense, and
  * server-side rendering. During SSR the same value is returned as on
@@ -32,28 +42,28 @@ interface UseLocalQueryOptions {
  * engine without rewriting).
  * @param params Optional positional bound parameters matching `?`
  * placeholders in `sql`.
- * @param _options Optional configuration (currently unused; reserved for
- * future features like shard key routing).
- * @returns An array of result rows typed via the generic parameter `T`, or
- * `undefined` if the query fails (e.g. the target table doesn't exist yet
- * because no matching diff has been applied). Treat `undefined` as a
- * "loading" or "no data yet" signal in your component.
- *
- * **Error handling**: The hook catches SQL errors internally and returns
- * `undefined`. Use a try-catch around `mirror.query(...)` directly if you
- * need finer-grained error diagnostics.
+ * @returns `{ data }` with the result rows typed via the generic parameter
+ * `T`, or `{ error }` when the query fails (e.g. malformed SQL, or the
+ * target table doesn't exist yet because no matching diff has been applied
+ * — that specific case surfaces as a "no such table" `Error`). Never
+ * collapses a failure to `undefined` — check `error` explicitly rather than
+ * treating a missing `data` as "still loading".
  * @example
  * ```tsx
  * import { useLocalQuery } from "@lunora/replica/react";
  * import { mirror } from "./mirror";
  *
  * function UserList() {
- *   const users = useLocalQuery<{ id: string; name: string }>(
+ *   const { data: users, error } = useLocalQuery<{ id: string; name: string }>(
  *     mirror,
  *     "SELECT id, name FROM fn_todos_list WHERE name LIKE ?",
  *     ["%alice%"],
  *   );
  *
+ *   if (error) {
+ *     return <p>Query failed: {error.message}</p>;
+ *   }
+ *
  *   if (users === undefined) {
  *     return <p>Waiting for data…</p>;
  *   }
@@ -63,5 +73,5 @@ interface UseLocalQueryOptions {
  * ```
  * @experimental
  */
-declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>, _options?: UseLocalQueryOptions) => T[] | undefined;
-export { UseLocalQueryOptions, useLocalQuery };
+declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>) => LocalQueryResult<T>;
+export { type LocalQueryResult, useLocalQuery };

package/dist/react.d.ts

@@ -1,26 +1,36 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-CyGOpUES.js";
-import "./packem_shared/types.d-CkMkSwLJ.js";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-wbGXkXaE.js";
+import "./packem_shared/types.d-BuLTPLaQ.js";
 /**
- * Options for the {@link useLocalQuery} hook.
+ * Result of {@link useLocalQuery} — a discriminated union so callers get a
+ * typed error instead of a swallowed `undefined`.
  * @experimental
  */
-interface UseLocalQueryOptions {
-  /**
-   * Optional shard key (reserved for future use; currently unused).
-   *
-   * Intended for multi-mirror setups where a single app maintains multiple
-   * SQLite databases sharded by a key (e.g. user id, tenant id). Currently
-   * has no effect — the hook always queries the mirror passed as the first
-   * argument.
-   */
-  shardKey?: string;
-}
+type LocalQueryResult<T> = {
+  readonly data: T[];
+  readonly error?: undefined;
+} | {
+  readonly data?: undefined;
+  readonly error: Error;
+};
 /**
  * React hook that subscribes to a local SQLite query and returns
  * live-updating results whenever the mirror applies a diff.
  *
- * Uses `useSyncExternalStore` to subscribe to the mirror's `onChange`
- * callback — every diff triggers a re-query against the local SQLite.
+ * Uses `useSyncExternalStore` with `getSnapshot` reading {@link LocalMirror.version}
+ * — a plain number, unconditionally `Object.is`-stable across calls with no
+ * mutation in between. The actual query runs in a `useMemo` keyed on
+ * `[mirror, version, sql, stableParamsKey(params)]`, so it only re-executes
+ * when the mirror actually advances (or `sql`/`params` change) — not on
+ * every unrelated re-render.
+ *
+ * This intentionally does NOT cache query results inside {@link LocalMirror}
+ * itself: an LRU-capped cache in the mirror core evicts still-mounted hooks'
+ * entries once more than the cap's worth of distinct live queries are open
+ * on one mirror, which makes `getSnapshot` return a fresh (non-identical)
+ * object on the next read — `useSyncExternalStore` then force-re-renders,
+ * re-inserts, evicts another entry, and so on without bound. Keying the
+ * external-store snapshot on the version primitive instead of a cached
+ * query result has no such cap, so it can't loop.
  *
  * The hook works with React 18+ concurrent features, Suspense, and
  * server-side rendering. During SSR the same value is returned as on
@@ -32,28 +42,28 @@ interface UseLocalQueryOptions {
  * engine without rewriting).
  * @param params Optional positional bound parameters matching `?`
  * placeholders in `sql`.
- * @param _options Optional configuration (currently unused; reserved for
- * future features like shard key routing).
- * @returns An array of result rows typed via the generic parameter `T`, or
- * `undefined` if the query fails (e.g. the target table doesn't exist yet
- * because no matching diff has been applied). Treat `undefined` as a
- * "loading" or "no data yet" signal in your component.
- *
- * **Error handling**: The hook catches SQL errors internally and returns
- * `undefined`. Use a try-catch around `mirror.query(...)` directly if you
- * need finer-grained error diagnostics.
+ * @returns `{ data }` with the result rows typed via the generic parameter
+ * `T`, or `{ error }` when the query fails (e.g. malformed SQL, or the
+ * target table doesn't exist yet because no matching diff has been applied
+ * — that specific case surfaces as a "no such table" `Error`). Never
+ * collapses a failure to `undefined` — check `error` explicitly rather than
+ * treating a missing `data` as "still loading".
  * @example
  * ```tsx
  * import { useLocalQuery } from "@lunora/replica/react";
  * import { mirror } from "./mirror";
  *
  * function UserList() {
- *   const users = useLocalQuery<{ id: string; name: string }>(
+ *   const { data: users, error } = useLocalQuery<{ id: string; name: string }>(
  *     mirror,
  *     "SELECT id, name FROM fn_todos_list WHERE name LIKE ?",
  *     ["%alice%"],
  *   );
  *
+ *   if (error) {
+ *     return <p>Query failed: {error.message}</p>;
+ *   }
+ *
  *   if (users === undefined) {
  *     return <p>Waiting for data…</p>;
  *   }
@@ -63,5 +73,5 @@ interface UseLocalQueryOptions {
  * ```
  * @experimental
  */
-declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>, _options?: UseLocalQueryOptions) => T[] | undefined;
-export { UseLocalQueryOptions, useLocalQuery };
+declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>) => LocalQueryResult<T>;
+export { type LocalQueryResult, useLocalQuery };

package/dist/react.mjs

@@ -1,15 +1 @@
-import { useSyncExternalStore } from 'react';
-
-const useLocalQuery = (mirror, sql, params, _options) => {
-  const subscribe = (onStoreChange) => mirror.onChange(onStoreChange);
-  const getSnapshot = () => mirror.version;
-  const getServerSnapshot = () => mirror.version;
-  useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
-  try {
-    return mirror.query(sql, params);
-  } catch {
-    return void 0;
-  }
-};
-
-export { useLocalQuery };
+import{useSyncExternalStore as y,useMemo as i}from"react";const u=t=>JSON.stringify(t??[],(r,e)=>typeof e=="bigint"?`${e.toString()}n`:e),S=(t,r,e)=>{const s=n=>t.onChange(n),o=()=>t.version,c=y(s,o,o),a=u(e);return i(()=>{try{return{data:t.query(r,e)}}catch(n){return{error:n instanceof Error?n:new Error(String(n))}}},[t,c,r,a])};export{S as useLocalQuery};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/replica",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0-alpha.91",
   "description": "Local-first replica runtime + local SQLite mirror for Lunora",
   "keywords": [
     "cloudflare",

package/dist/packem_shared/EventEmitter-CMZfct03.mjs

@@ -1,92 +0,0 @@
-class EventEmitter {
-  #listeners = /* @__PURE__ */ new Map();
-  #wildcardListeners = /* @__PURE__ */ new Set();
-  // ── Registration ──────────────────────────────────────────────────
-  /**
-   * Register a handler for a specific event type.
-   * @returns An unsubscribe function (equivalent to calling {@link off}).
-   */
-  on(event, handler) {
-    let set = this.#listeners.get(event);
-    if (!set) {
-      set = /* @__PURE__ */ new Set();
-      this.#listeners.set(event, set);
-    }
-    set.add(handler);
-    return () => {
-      this.off(event, handler);
-    };
-  }
-  /**
-   * Remove a previously registered handler.
-   */
-  off(event, handler) {
-    this.#listeners.get(event)?.delete(handler);
-  }
-  /**
-   * Register a wildcard handler that fires for **every** event type.
-   * @returns An unsubscribe function.
-   */
-  onAny(handler) {
-    this.#wildcardListeners.add(handler);
-    return () => {
-      this.#wildcardListeners.delete(handler);
-    };
-  }
-  /**
-   * Remove a wildcard handler.
-   */
-  offAny(handler) {
-    this.#wildcardListeners.delete(handler);
-  }
-  // ── Emission ──────────────────────────────────────────────────────
-  /**
-   * Emit an event. All registered handlers (typed + wildcard) are invoked
-   * synchronously. Exceptions from handlers are caught and silently
-   * swallowed — they **must not** break the emitter loop.
-   * @returns `true` if at least one handler was called.
-   */
-  emit(event, payload) {
-    let called = false;
-    const typed = this.#listeners.get(event);
-    if (typed) {
-      for (const handler of typed) {
-        try {
-          handler(payload);
-          called = true;
-        } catch {
-        }
-      }
-    }
-    for (const handler of this.#wildcardListeners) {
-      try {
-        handler(event, payload);
-        called = true;
-      } catch {
-      }
-    }
-    return called;
-  }
-  // ── Introspection ─────────────────────────────────────────────────
-  /**
-   * Return `true` when at least one listener is registered for `event`.
-   */
-  hasListeners(event) {
-    return (this.#listeners.get(event)?.size ?? 0) > 0 || this.#wildcardListeners.size > 0;
-  }
-  /**
-   * Return the number of typed listeners for a specific event.
-   */
-  listenerCount(event) {
-    return this.#listeners.get(event)?.size ?? 0;
-  }
-  /**
-   * Remove all listeners.
-   */
-  clear() {
-    this.#listeners.clear();
-    this.#wildcardListeners.clear();
-  }
-}
-
-export { EventEmitter };