@lunora/replica 0.0.0 → 1.0.0-alpha.100

package/dist/packem_shared/local-mirror.d-wbGXkXaE.d.ts

@@ -0,0 +1,562 @@
+import { S as SqliteAdapter } from "./types.d-BuLTPLaQ.js";
+/**
+ * Row-level change kind within a TableDiff.
+ *
+ * Each change represents one row that was inserted, updated, or deleted on
+ * the server since the last sync tick.
+ * @experimental
+ */
+type RowChange = {
+  data: Record<string, unknown>;
+  type: "insert";
+} | {
+  data: Record<string, unknown>;
+  id: string;
+  type: "update";
+} | {
+  id: string;
+  type: "delete";
+};
+/**
+ * A scoped, ordered set of row changes for a single table.
+ *
+ * `TableDiff` is the unit of replication between the server and the local
+ * SQLite mirror. The server pushes diffs over the poke protocol; the
+ * client applies them via `applyDiff`.
+ * @experimental
+ */
+interface TableDiff {
+  /** Ordered row changes — insert/update/delete, earliest first. */
+  readonly changes: ReadonlyArray<RowChange>;
+  /**
+   * Optional stable identity for this diff, distinct from `timestamp`
+   * (multiple diffs can legitimately share a millisecond, so `timestamp`
+   * alone is not a unique diff identity). `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). */
+  readonly table: string;
+  /** Monotonic server timestamp (ms since epoch) when this diff was emitted. */
+  readonly timestamp: number;
+}
+/**
+ * Create a {@link TableDiff} with a snapshot of the current time and a
+ * fresh stable `id` (unless one is explicitly provided).
+ * @experimental
+ */
+declare const createTableDiff: (table: string, changes: ReadonlyArray<RowChange>, timestamp?: number, id?: string) => TableDiff;
+/**
+ * Return `true` when the diff contains no row changes.
+ * @experimental
+ */
+declare const isDiffEmpty: (diff: TableDiff) => boolean;
+/**
+ * Return the number of rows touched by the diff (inserts + updates + deletes).
+ * @experimental
+ */
+declare const diffSize: (diff: TableDiff) => number;
+/**
+ * Partition a {@link TableDiff} into three categories for batch processing.
+ * @experimental
+ */
+declare const classifyChanges: (diff: TableDiff) => {
+  deletes: RowChange[];
+  inserts: RowChange[];
+  updates: RowChange[];
+};
+/**
+ * Merge several diffs for the same table into one (ordering preserved).
+ *
+ * Returns `null` when the input list is empty.
+ * @experimental
+ */
+declare const mergeDiffs: (diffs: ReadonlyArray<TableDiff>) => TableDiff | null;
+/**
+ * Sequence-number types for the event log.
+ *
+ * Three namespaces match the vocabulary established by event-sourcing:
+ *
+ * | Namespace | Shape              | Producer                  | Consumer                     |
+ * |-----------|--------------------|---------------------------|------------------------------|
+ * | `Global`  | `number`           | `EventLog` / `EventLogDO` | Materializers, subscribers   |
+ * | `Input`   | No seq (optimistic) | `defineEvents` factories  | `EventLog.append` / DO client|
+ * | `Client`  | `{generation,seq}`  | _(future: rebase engine)_ | _(future: rebase-aware code)_|
+ * @module
+ */
+/**
+ * A server-authoritative (global) sequence number.
+ *
+ * Monotonically increasing, assigned by `EventLog` (in-memory) or
+ * `EventLogDO` (Durable Object). All confirmed log entries carry a
+ * `GlobalSeq`.
+ * @experimental
+ */
+type GlobalSeq = number;
+/**
+ * A client-originated composite sequence number designed to survive rebase.
+ *
+ * Carries the last-confirmed `global` seq, a monotonically increasing
+ * `client` counter, and a `rebaseGeneration` that increments whenever the
+ * client's local events are rebased onto a new upstream baseline.
+ * @experimental
+ */
+interface ClientSeq {
+  /** Client-local monotonically increasing counter. */
+  readonly client: number;
+  /** The last-confirmed global sequence number. 0 for unconfirmed events. */
+  readonly global: number;
+  /** Incremented on every rebase. */
+  readonly rebaseGeneration: number;
+}
+/**
+ * Discriminated union of all sequence-number types.
+ * @experimental
+ */
+type Seq = GlobalSeq | ClientSeq;
+/**
+ * Narrow `Seq` to `GlobalSeq`.
+ * @experimental
+ */
+declare const isGlobalSeq: (seq: Seq) => seq is GlobalSeq;
+/**
+ * Narrow `Seq` to `ClientSeq`.
+ * @experimental
+ */
+declare const isClientSeq: (seq: Seq) => seq is ClientSeq;
+/**
+ * An event that has **not** yet been assigned a sequence number.
+ *
+ * Input events represent optimistic / command payloads before the server
+ * confirms them. They carry `type`, `payload`, and `timestamp` but no
+ * `seq` — the log assigns one on append.
+ *
+ * Create input events via `defineEvents` factories:
+ *
+ * ```ts
+ * const event = events.chat.messageSent({ channelId: "c1", text: "hello" });
+ * // event: InputEvent<"chat.messageSent", { channelId: string; text: string }>
+ * ```
+ * @experimental
+ */
+interface InputEvent<Type extends string = string, Payload = unknown> {
+  /** Arbitrary JSON-serialisable payload. */
+  readonly payload: Payload;
+  /** Millisecond timestamp (epoch) when the event was created. */
+  readonly timestamp: number;
+  /** Event type discriminator (e.g. `"chat.messageSent"`). */
+  readonly type: Type;
+}
+/**
+ * Type guard: check whether `value` is an {@link InputEvent}.
+ * @experimental
+ */
+declare const isInputEvent: (value: unknown) => value is InputEvent;
+/**
+ * A single entry in the append-only {@link EventLog}.
+ *
+ * Entries are immutable once appended; the `seq` field is assigned
+ * monotonically by the log and doubles as a watermark for catch-up
+ * replication between tabs or service-worker instances.
+ * @experimental
+ */
+interface EventLogEntry {
+  /**
+   * Globally-unique client identifier that originated this event.
+   * Set by clients that support offline / optimistic writes.
+   * `undefined` when the event was created server-side.
+   */
+  readonly clientId?: string;
+  /**
+   * The sequence number of the causal parent event.
+   *
+   * A {@link GlobalSeq} for events confirmed by the server (pointing
+   * to the previous confirmed event), or a {@link ClientSeq} for
+   * optimistic / offline events pointing to the local predecessor.
+   * `undefined` for the first event in a log.
+   */
+  readonly parentSeqNum?: Seq;
+  /** Arbitrary JSON-serialisable payload. */
+  readonly payload: unknown;
+  /** Monotonically increasing sequence number (0-based). A {@link GlobalSeq}. */
+  readonly seq: GlobalSeq;
+  /**
+   * Session identifier from the originating client.
+   * Paired with `clientId` to disambiguate concurrent sessions.
+   */
+  readonly sessionId?: string;
+  /**
+   * Optional table diffs that this event produced.
+   * When present, a consumer can re-play the event by applying the diffs
+   * to its local mirror without re-executing the originating mutation.
+   */
+  readonly tableDiffs?: ReadonlyArray<TableDiff>;
+  /** Millisecond timestamp (epoch) when the entry was appended. */
+  readonly timestamp: number;
+  /** Event type discriminator (e.g. "row-insert", "mutation-apply"). */
+  readonly type: string;
+}
+/**
+ * Serialised snapshot of the log — used for persistence and transfer.
+ * @experimental
+ */
+interface EventLogSnapshot {
+  readonly entries: ReadonlyArray<EventLogEntry>;
+  /** The sequence number of the last entry (head), or `null` for an empty log. */
+  readonly headSeq: GlobalSeq | null;
+  readonly nextSeq: number;
+}
+/**
+ * Optional metadata that can accompany an appended event.
+ * @experimental
+ */
+interface AppendOptions {
+  /** Globally-unique client identifier. */
+  readonly clientId?: string;
+  /**
+   * Causal parent sequence number.
+   * Automatically set to the previous entry's seq when omitted.
+   */
+  readonly parentSeqNum?: Seq;
+  /** Session identifier within the client. */
+  readonly sessionId?: string;
+  /**
+   * Override the entry's `timestamp` instead of stamping `Date.now()` at
+   * append time.
+   *
+   * Used by callers (e.g. {@link import("./event-source").EventSource | EventSource})
+   * that must commit the EXACT entry a reducer already observed — a
+   * second, independently-drawn `Date.now()` at append time could produce
+   * a persisted entry a timestamp-dependent reducer cannot reproduce on
+   * replay.
+   */
+  readonly timestamp?: number;
+}
+/**
+ * Options for constructing an {@link EventLog}.
+ * @experimental
+ */
+interface EventLogOptions {
+  /**
+   * Cap the number of entries retained in memory (REPLICA-06). When an
+   * append would exceed the cap, the OLDEST entries are evicted (ring
+   * buffer) — a `getSince`/`getFrom` call for a watermark below the oldest
+   * retained `seq` then returns only what's left, silently missing
+   * anything evicted.
+   *
+   * `undefined` (the default) preserves the original unbounded behavior.
+   * Set this only when you have another durable source of truth for
+   * anything older than the cap (a snapshot, a server-side `EventLogDO`) —
+   * see {@link EventLog#truncateBelow} for the caller-driven equivalent
+   * tied to snapshot persistence.
+   */
+  readonly maxEntries?: number;
+}
+/**
+ * An append-only, in-memory event log for local event sourcing.
+ *
+ * The log is the single source of truth for "what happened" and drives
+ * catch-up replication: a new tab or service worker asks for entries
+ * since its known `seq` watermark and re-applies them.
+ * @remarks This class is intentionally **not** a full SQLite-backed log.
+ * Persistence is the caller's responsibility (write the snapshot
+ * to IndexedDB / OPFS via {@link EventLog#snapshot}).
+ * @experimental
+ */
+declare class EventLog {
+  #private;
+  constructor(options?: EventLogOptions);
+  /**
+   * Append a new entry to the log.
+   *
+   * Accepts either an {@link InputEvent} (e.g. from a `defineEvents` factory)
+   * or the traditional `(type, payload, tableDiffs?)` triple.
+   * @returns The newly created entry (already written to the log).
+   */
+  append(event: InputEvent, options?: AppendOptions): EventLogEntry;
+  append(type: string, payload: unknown, tableDiffs?: ReadonlyArray<TableDiff>, options?: AppendOptions): EventLogEntry;
+  /**
+   * 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: ReadonlyArray<InputEvent | {
+    payload: unknown;
+    type: string;
+  }>): EventLogEntry[];
+  /**
+   * 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: EventLogSnapshot): void;
+  /**
+   * Return **all** entries whose `seq >= sinceSeq`.
+   * Useful for catch-up: "give me everything since my last watermark".
+   */
+  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.
+   */
+  getFrom(fromSeq: number, limit?: number): {
+    entries: ReadonlyArray<EventLogEntry>;
+    hasMore: boolean;
+  };
+  /**
+   * Return all entries as a snapshot suitable for serialisation.
+   */
+  snapshot(): EventLogSnapshot;
+  /** Number of entries currently in the log. */
+  get size(): number;
+  /** The next sequence number that will be assigned. */
+  get nextSeq(): number;
+  /** Return `true` when there are no entries. */
+  get isEmpty(): boolean;
+  /**
+   * 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(): GlobalSeq | null;
+  /** Remove all entries (primarily for testing). */
+  clear(): void;
+  /**
+   * Discard all entries with `seq < floorSeq` (REPLICA-06).
+   *
+   * `headSeq`/`nextSeq` are untouched (they're independent counters), so
+   * appends after a truncation continue the same sequence uninterrupted.
+   *
+   * **Caller-driven, not automatic**: only call this after the truncated
+   * range has already been durably captured elsewhere (a snapshot, a
+   * server-side `EventLogDO`) — truncating without such a floor makes any
+   * future `getSince`/`getFrom`/`EventSource.replayFromLog` call for a
+   * watermark below `floorSeq` silently miss the discarded entries. This is
+   * the hook the caller ties to snapshot persistence; the log itself has no
+   * concept of "already durably persisted".
+   *
+   * `floorSeq` must be a non-negative safe integer — `NaN` would make
+   * every comparison false and silently clear the entire log.
+   */
+  truncateBelow(floorSeq: number): void;
+  /**
+   * Return an async generator that yields every entry starting from
+   * `fromSeq` (default `0` = all entries).
+   *
+   * 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}.
+   */
+  events(fromSeq?: number): AsyncGenerator<EventLogEntry>;
+}
+/**
+ * `MirrorTableDef` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+ * @experimental
+ */
+interface MirrorTableDef {
+  /** Primary key column name (defaults to `"id"`). */
+  readonly primaryKey?: string;
+}
+/**
+ * Options for constructing a {@link LocalMirror}.
+ * @experimental
+ */
+interface LocalMirrorOptions {
+  /** Platform-specific SQLite adapter. */
+  readonly db: SqliteAdapter;
+  /**
+   * 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.
+   *
+   * 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;
+  /**
+   * Table schemas the mirror should manage.
+   *
+   * On first use the mirror creates any missing tables automatically
+   * based on the columns observed in the first diff/row applied.
+   * If you want a fixed schema, pass it here with explicit column
+   * definitions in `columns`.
+   */
+  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.
+ *
+ * Usage:
+ * ```ts
+ * import { createSqlJsAdapter } from "@lunora/replica/adapters/sqljs";
+ * import initSqlJs from "sql.js";
+ *
+ * const SQL = await initSqlJs();
+ * const db = createSqlJsAdapter(new SQL.Database());
+ *
+ * const mirror = new LocalMirror({ db });
+ *
+ * // Apply a server diff:
+ * mirror.applyDiff(someDiff);
+ *
+ * // Query locally:
+ * const rows = mirror.query<{ id: string; name: string }>(
+ *   "SELECT id, name FROM users WHERE name LIKE ?",
+ *   ["alice%"],
+ * );
+ * ```
+ */
+type ChangeSubscriber = (reason: MirrorChangeReason) => void;
+/**
+ * `LocalMirror` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+ * @experimental
+ */
+declare class LocalMirror {
+  #private;
+  /**
+   * Convenience factory that creates a {@link LocalMirror} backed by a
+   * {@link createSqlJsAdapter sql.js adapter} without needing to import
+   * and wire sql.js manually.
+   *
+   * The caller provides an initialised sql.js database — this method wraps
+   * it in an adapter and constructs the mirror.
+   * @example
+   * ```ts
+   * import initSqlJs from "sql.js";
+   *
+   * const SQL = await initSqlJs();
+   * const mirror = LocalMirror.create(new SQL.Database(), {
+   *   tables: { todos: { primaryKey: "id" } },
+   * });
+   * ```
+   */
+  static create(sqlJsDatabase: {
+    close: () => void;
+    exec: (sql: string) => {
+      columns: string[];
+      values: unknown[][];
+    }[];
+    run: (sql: string, params?: unknown[]) => void;
+  }, options?: {
+    tables?: Record<string, MirrorTableDef>;
+  }): LocalMirror;
+  constructor(options: LocalMirrorOptions);
+  /**
+   * Subscribe to data-change notifications. Fires after every {@link applyDiff}.
+   * Returns an unsubscribe function.
+   */
+  onChange(callback: ChangeSubscriber): () => void;
+  /**
+   * The in-memory event log tracking every diff applied to this mirror.
+   * Use {@link EventLog.getSince} for catch-up replication across tabs
+   * or service-worker instances.
+   */
+  get eventLog(): EventLog;
+  /**
+   * The raw SQLite adapter. Advanced consumers (e.g. the React hook)
+   * can use it for ad-hoc queries or bulk operations.
+   */
+  get db(): SqliteAdapter;
+  /**
+   * Monotonically increasing version counter, bumped on every operation
+   * that changes mirrored data (`applyDiff`, `clearData`). Use this — not
+   * `eventLog.size` — as a `useSyncExternalStore` snapshot so operations
+   * that don't append to the log still trigger a re-render.
+   */
+  get version(): number;
+  /**
+   * Apply a server-side diff to the local SQLite mirror.
+   *
+   * The diff is applied in a transaction and recorded in the event log
+   * so other tabs or the SW can catch up.
+   */
+  applyDiff(diff: TableDiff): void;
+  /**
+   * Run an arbitrary SQL query against the local mirror and return
+   * typed results.
+   * @example
+   * ```ts
+   * const users = mirror.query<{ id: string; name: string }>(
+   *   "SELECT id, name FROM users WHERE active = ?",
+   *   [true],
+   * );
+   * ```
+   */
+  query<T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>): T[];
+  /**
+   * 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
+   * consumer keyed only on `eventLog.size` would otherwise never learn the
+   * mirror was cleared and keep rendering deleted rows.
+   */
+  clearData(): void;
+  /**
+   * Dispose the mirror and close the database connection.
+   */
+  close(): void;
+  /**
+   * Register a table schema so the mirror can create the table on
+   * 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.
+   */
+  get mirroredTables(): ReadonlyArray<string>;
+}
+export { AppendOptions as A, ClientSeq as C, EventLogEntry as E, GlobalSeq as G, InputEvent as I, LocalMirror as L, MirrorTableDef as M, RowChange as R, Seq as S, TableDiff as T, EventLog as a, EventLogOptions as b, EventLogSnapshot as c, LocalMirrorOptions as d, classifyChanges as e, createTableDiff as f, diffSize as g, isDiffEmpty as h, isClientSeq as i, isGlobalSeq as j, isInputEvent as k, mergeDiffs as m };

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-BuLTPLaQ.d.mts

@@ -0,0 +1,22 @@
+/**
+ * Abstract SQLite driver interface used by the local mirror.
+ *
+ * Each runtime (browser via sql.js, React Native via expo-sqlite,
+ * Node via better-sqlite3) provides its own adapter implementing this
+ * interface so the rest of `@lunora/replica` stays platform-agnostic.
+ * @experimental
+ */
+interface SqliteAdapter {
+  /** Close the database connection. */
+  close: () => void;
+  /** Execute a SQL statement (with optional bound params). */
+  exec: (sql: string, params?: ReadonlyArray<unknown>) => void;
+  /**
+   * Execute a SQL statement and return the result rows.
+   * Columns can be accessed by index or by name.
+   */
+  query: <T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>) => T[];
+  /** Run all statements in a transaction. */
+  transaction: (function_: () => void) => void;
+}
+export { SqliteAdapter as S };

package/dist/packem_shared/types.d-BuLTPLaQ.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Abstract SQLite driver interface used by the local mirror.
+ *
+ * Each runtime (browser via sql.js, React Native via expo-sqlite,
+ * Node via better-sqlite3) provides its own adapter implementing this
+ * interface so the rest of `@lunora/replica` stays platform-agnostic.
+ * @experimental
+ */
+interface SqliteAdapter {
+  /** Close the database connection. */
+  close: () => void;
+  /** Execute a SQL statement (with optional bound params). */
+  exec: (sql: string, params?: ReadonlyArray<unknown>) => void;
+  /**
+   * Execute a SQL statement and return the result rows.
+   * Columns can be accessed by index or by name.
+   */
+  query: <T = Record<string, unknown>>(sql: string, params?: ReadonlyArray<unknown>) => T[];
+  /** Run all statements in a transaction. */
+  transaction: (function_: () => void) => void;
+}
+export { SqliteAdapter as S };

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