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

package/README.md

@@ -10,6 +10,8 @@
 
 <!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
+> **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
+
 <br />
 
 <div align="center">

package/dist/adapters/better-sqlite3.d.mts

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.mjs";
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuAWjEY5.mjs";
 /**
 * Create a {@link SqliteAdapter} backed by [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)
 * (a synchronous SQLite3 binding for Node.js).
@@ -11,6 +11,7 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.mjs";
 * @param database.exec Execute one or more SQL statements (no params, no results).
 * @param database.prepare Prepare a SQL statement for repeated execution.
 * @param database.transaction Wrap a function so its statements run in a transaction.
+* @experimental
 */
 declare const createBetterSqlite3Adapter: (database: {
   close: () => void;

package/dist/adapters/better-sqlite3.d.ts

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.js";
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuAWjEY5.js";
 /**
 * Create a {@link SqliteAdapter} backed by [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)
 * (a synchronous SQLite3 binding for Node.js).
@@ -11,6 +11,7 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.js";
 * @param database.exec Execute one or more SQL statements (no params, no results).
 * @param database.prepare Prepare a SQL statement for repeated execution.
 * @param database.transaction Wrap a function so its statements run in a transaction.
+* @experimental
 */
 declare const createBetterSqlite3Adapter: (database: {
   close: () => void;

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

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.mjs";
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuAWjEY5.mjs";
 /**
 * Create a {@link SqliteAdapter} backed by the [official SQLite Wasm](https://www.npmjs.com/package/@sqlite.org/sqlite-wasm)
 * (a WebAssembly build of SQLite that runs in browsers and Node.js).
@@ -10,6 +10,7 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.mjs";
 * @param database.close Tear down the database connection.
 * @param database.exec Execute SQL with optional bind params and return rows
 * as `{ columns, values }` result objects.
+* @experimental
 */
 declare const createSqliteWasmAdapter: (database: {
   close: () => void;

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

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.js";
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuAWjEY5.js";
 /**
 * Create a {@link SqliteAdapter} backed by the [official SQLite Wasm](https://www.npmjs.com/package/@sqlite.org/sqlite-wasm)
 * (a WebAssembly build of SQLite that runs in browsers and Node.js).
@@ -10,6 +10,7 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.js";
 * @param database.close Tear down the database connection.
 * @param database.exec Execute SQL with optional bind params and return rows
 * as `{ columns, values }` result objects.
+* @experimental
 */
 declare const createSqliteWasmAdapter: (database: {
   close: () => void;

package/dist/adapters/sqljs.d.mts

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.mjs";
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuAWjEY5.mjs";
 /**
 * Create a {@link SqliteAdapter} backed by [sql.js](https://sql.js.org)
 * (a WebAssembly build of SQLite that runs in browsers, Node, and
@@ -7,6 +7,7 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.mjs";
 * @param database.run Execute a parameterised SQL statement (no results).
 * @param database.exec Execute SQL and return result rows.
 * @param database.close Tear down the database connection.
+* @experimental
 */
 declare const createSqlJsAdapter: (database: {
   close: () => void;

package/dist/adapters/sqljs.d.ts

@@ -1,4 +1,4 @@
-import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.js";
+import { S as SqliteAdapter } from "../packem_shared/types.d-BuAWjEY5.js";
 /**
 * Create a {@link SqliteAdapter} backed by [sql.js](https://sql.js.org)
 * (a WebAssembly build of SQLite that runs in browsers, Node, and
@@ -7,6 +7,7 @@ import { S as SqliteAdapter } from "../packem_shared/types.d-VfJ76cK4.js";
 * @param database.run Execute a parameterised SQL statement (no results).
 * @param database.exec Execute SQL and return result rows.
 * @param database.close Tear down the database connection.
+* @experimental
 */
 declare const createSqlJsAdapter: (database: {
   close: () => void;

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 export { 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-VfJ76cK4.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-Bp19ueGy.mjs";
-export { type C as ClientSeq, type b as EventLogSnapshot, type G as GlobalSeq, type c as LocalMirrorOptions, type M as MirrorTableDef, type R as RowChange, d as classifyChanges, e as createTableDiff, f as diffSize, i as isClientSeq, g as isDiffEmpty, h as isGlobalSeq, j as isInputEvent, m as mergeDiffs } from "./packem_shared/local-mirror.d-Bp19ueGy.mjs";
+import { S as SqliteAdapter } from "./packem_shared/types.d-BuAWjEY5.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-BUeOe5KC.mjs";
+export { type C as ClientSeq, type b as EventLogSnapshot, type G as GlobalSeq, type c as LocalMirrorOptions, type M as MirrorTableDef, type R as RowChange, d as classifyChanges, e as createTableDiff, f as diffSize, i as isClientSeq, g as isDiffEmpty, h as isGlobalSeq, j as isInputEvent, m as mergeDiffs } from "./packem_shared/local-mirror.d-BUeOe5KC.mjs";
 /**
 * Apply a single {@link TableDiff} to an in-memory row map and return
 * the updated map.
@@ -24,6 +24,7 @@ export { type C as ClientSeq, type b as EventLogSnapshot, type G as GlobalSeq, t
 * updated.get("id-1")?.name // "alice-updated"
 * updated.get("id-2")?.name // "bob"
 * ```
+* @experimental
 */
 declare const applyDiff: (current: ReadonlyMap<string, Record<string, unknown>>, diff: TableDiff) => Map<string, Record<string, unknown>>;
 /**
@@ -31,6 +32,7 @@ declare const applyDiff: (current: ReadonlyMap<string, Record<string, unknown>>,
 *
 * This is equivalent to calling {@link applyDiff} repeatedly but avoids
 * intermediate map copies.
+* @experimental
 */
 declare const applyDiffs: (current: ReadonlyMap<string, Record<string, unknown>>, diffs: ReadonlyArray<TableDiff>) => Map<string, Record<string, unknown>>;
 /**
@@ -39,6 +41,7 @@ declare const applyDiffs: (current: ReadonlyMap<string, Record<string, unknown>>
 * @param snapshot Current snapshot, e.g. `{ users: Map&lt;id, row>, posts: Map&lt;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
 */
 declare const applyDiffToSnapshot: (snapshot: ReadonlyMap<string, ReadonlyMap<string, Record<string, unknown>>>, diff: TableDiff) => Map<string, Map<string, Record<string, unknown>>>;
 /** Map a namespace-and-name pair to a qualified event type string. */
@@ -66,6 +69,7 @@ type EventTypeMap<TDefinition extends Record<string, Record<string, unknown>>> =
 *
 * The returned event has no `seq` — it is an optimistic / command payload
 * that the event log will assign a sequence number to on append.
+* @experimental
 */
 interface EventFactory<Type extends string, Payload> {
   (payload: Payload): InputEvent<Type, Payload>;
@@ -74,10 +78,12 @@ interface EventFactory<Type extends string, Payload> {
 }
 /**
 * The namespace object returned for each group of events.
+* @experimental
 */
 type EventNamespace<Ns extends string, TDefinition extends Record<string, unknown>> = { [Name in keyof TDefinition & string]: EventFactory<QualifiedType<Ns, Name>, PayloadOf<TDefinition[Name]>> };
 /**
 * The full result of {@link defineEvents}.
+* @experimental
 */
 type EventsDefinition<TDefinition extends Record<string, Record<string, unknown>>> = { [Ns in keyof TDefinition & string]: EventNamespace<Ns, TDefinition[Ns]> } & {
   /** Type-level map of event type → payload shape. Useful for generic code. */
@@ -107,12 +113,17 @@ interface DefineEventsOptions {
   */
   readonly version?: string;
 }
+/**
+* `defineEvents` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+* @experimental
+*/
 declare const defineEvents: <TDefinition extends Record<string, Record<string, unknown>>>(definition: TDefinition, options?: DefineEventsOptions) => EventsDefinition<TDefinition>;
 /**
 * Shape of the `events[]` items sent in a POST `/append` body.
 *
 * Like {@link InputEvent} but with `timestamp` optional — omit it to
 * let the server assign the timestamp.
+* @experimental
 */
 interface AppendEventInput {
   /** Globally-unique client identifier (for offline/optimistic support). */
@@ -128,7 +139,10 @@ interface AppendEventInput {
   /** Event type discriminator. */
   readonly type: string;
 }
-/** Options for constructing an {@link EventLogDOClient}. */
+/**
+* Options for constructing an {@link EventLogDOClient}.
+* @experimental
+*/
 interface EventLogDOClientOptions {
   /**
   * A function that dispatches an HTTP request to the target EventLogDO
@@ -145,6 +159,7 @@ interface EventLogDOClientOptions {
 *
 * Each method maps to one of the DO's endpoints, throws on non-OK status,
 * and returns the parsed response body.
+* @experimental
 */
 declare class EventLogDOClient {
   #private;
@@ -191,6 +206,7 @@ declare class EventLogDOClient {
 * emitter.on("userCreated", (payload) => console.log(payload.name));
 * emitter.emit("userCreated", { id: "1", name: "alice" });
 * ```
+* @experimental
 */
 declare class EventEmitter<EventMap extends Record<string, unknown>> {
   #private;
@@ -240,6 +256,7 @@ declare class EventEmitter<EventMap extends Record<string, unknown>> {
 * - `"fail"` — throw an error, halting the apply / replay cycle.
 * - A **callback** — invoked with the entry; return truthy to mark it as
 * handled (no warning), falsy to fall through to the configured fallback.
+* @experimental
 */
 type UnknownEventHandling = "warn" | "ignore" | "fail" | ((entry: EventLogEntry) => boolean);
 /**
@@ -248,6 +265,7 @@ type UnknownEventHandling = "warn" | "ignore" | "fail" | ((entry: EventLogEntry)
 * 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>`.
+* @experimental
 */
 type EventSourceEvents = {
   /** Fired (once) after the initial replay completes. */
@@ -270,10 +288,12 @@ type EventSourceEvents = {
 *
 * Pure functions are strongly encouraged: given the same event payload
 * and state, they must produce the same next state.
+* @experimental
 */
 type EventReducer<S> = (state: S, entry: EventLogEntry) => S;
 /**
 * Options for constructing an {@link EventSource}.
+* @experimental
 */
 interface EventSourceOptions {
   /**
@@ -295,6 +315,7 @@ interface EventSourceOptions {
 * const entry = source.applyEvent("user-created", { id: "1", name: "alice" });
 * console.log(source.state); // updated state
 * ```
+* @experimental
 */
 declare class EventSource<S extends Record<string, unknown> = Record<string, unknown>> {
   #private;
@@ -366,6 +387,7 @@ declare class EventSource<S extends Record<string, unknown> = Record<string, unk
 * the {@link InMemorySnapshotStore} is used for the offline-first
 * local mirror, while a production client would implement this
 * over IndexedDB or OPFS.
+* @experimental
 */
 interface SnapshotStore {
   /** Delete all snapshots. */
@@ -383,6 +405,7 @@ interface SnapshotStore {
 * In-memory snapshot store. Useful for testing and for the local
 * offline-first mirror where persistence is handled at a higher
 * layer (IndexedDB adapter).
+* @experimental
 */
 declare class InMemorySnapshotStore implements SnapshotStore {
   #private;
@@ -397,10 +420,12 @@ declare class InMemorySnapshotStore implements SnapshotStore {
 *
 * Pure functions are strongly encouraged: given the same event and state,
 * they must produce the same next state for deterministic replay.
+* @experimental
 */
 type MaterializerReducer<S> = (state: S, entry: EventLogEntry) => S;
 /**
 * Options for defining a single materializer.
+* @experimental
 */
 interface MaterializerDef<S> {
   /**
@@ -416,6 +441,7 @@ interface MaterializerDef<S> {
 }
 /**
 * A constructed materializer ready to be used with a {@link MaterializerRuntime}.
+* @experimental
 */
 interface Materializer<S> {
   /** Apply a single event entry through the reducer. */
@@ -433,6 +459,7 @@ interface Materializer<S> {
 *
 * The returned {@link Materializer} object can be used standalone or passed
 * to a {@link MaterializerRuntime} for automatic log subscription.
+* @experimental
 */
 declare const defineMaterializer: <S>(definition: MaterializerDef<S>) => Materializer<S>;
 /**
@@ -446,6 +473,7 @@ declare const defineMaterializer: <S>(definition: MaterializerDef<S>) => Materia
 type AnyMaterializer = Materializer<any>;
 /**
 * Options for constructing a {@link MaterializerRuntime}.
+* @experimental
 */
 interface MaterializerRuntimeOptions {
   /**
@@ -472,6 +500,7 @@ interface MaterializerRuntimeOptions {
 * - Applying new events as they arrive
 * - Periodic snapshot persistence
 * - Recovery from snapshots (replay only what's missing)
+* @experimental
 */
 declare class MaterializerRuntime {
   #private;
@@ -539,6 +568,7 @@ declare class MaterializerRuntime {
 * @param database SQLite adapter the statements run against.
 * @param diff The table diff to apply.
 * @param pkColumn Primary key column for DELETE/UPDATE (default `"id"`).
+* @experimental
 */
 declare const applyDiffToDatabase: (database: SqliteAdapter, diff: TableDiff, pkColumn?: string) => void;
 /**
@@ -546,6 +576,7 @@ declare const applyDiffToDatabase: (database: SqliteAdapter, diff: TableDiff, pk
 *
 * Each diff uses `"id"` as the primary key column. For tables with a custom
 * PK, use {@link applyDiffToDatabase} per-diff and pass the PK explicitly.
+* @experimental
 */
 declare const applyDiffsToDatabase: (database: SqliteAdapter, diffs: ReadonlyArray<TableDiff>) => void;
 interface EventLogDOState {
@@ -555,6 +586,10 @@ interface EventLogDOState {
     };
   };
 }
+/**
+* `EventLogDO` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+* @experimental
+*/
 declare class EventLogDO {
   #private;
   protected state: EventLogDOState;
@@ -588,6 +623,7 @@ type Middleware<ContextIn, ContextOut> = (options: {
 *
 * Each method delegates to the corresponding {@link EventLogDOClient} method,
 * so handlers never need to import or reference the DO client directly.
+* @experimental
 */
 interface EventsFacade {
   /**
@@ -624,6 +660,7 @@ interface EventsFacade {
 }
 /**
 * The context shape produced by {@link eventsContext}.
+* @experimental
 */
 interface EventsContextOutput {
   /** Typed event log facade backed by an {@link EventLogDOClient}. */
@@ -654,12 +691,14 @@ interface EventsContextOutput {
 * return entry;
 * });
 * ```
+* @experimental
 */
 declare const eventsContext: <Context>(client: EventLogDOClient) => Middleware<Context, Context & EventsContextOutput>;
 /**
 * A dependency-light subscription sink interface that mirrors what
 * `LunoraClient.subscribe` expects, so the mirror helper doesn't
 * need to import `@lunora/client`.
+* @experimental
 */
 interface SubscriptionClient {
   subscribe: (functionRef: {
@@ -693,16 +732,19 @@ interface SubscriptionClient {
 * // Later:
 * unsub();
 * ```
+* @experimental
 */
 declare const subscribeToMirror: (client: SubscriptionClient, mirror: LocalMirror, functionRef: {
   __lunoraRef: string;
 }, args: Record<string, unknown>, shardKey?: string) => (() => void);
 /**
 * Callback signature for state-change subscriptions.
+* @experimental
 */
 type StateChangeCallback = (state: Readonly<Record<string, unknown>>) => void;
 /**
 * Callback signature for event-type subscriptions.
+* @experimental
 */
 type EventCallback = (entry: EventLogEntry) => void;
 /**
@@ -730,6 +772,7 @@ type EventCallback = (entry: EventLogEntry) => void;
 * unsub1();
 * unsub2();
 * ```
+* @experimental
 */
 declare class SubscriptionManager {
   #private;
@@ -764,6 +807,7 @@ declare class SubscriptionManager {
 }
 /**
 * Options for constructing an {@link EventsSync}.
+* @experimental
 */
 interface EventsSyncOptions {
   /**
@@ -830,6 +874,7 @@ interface EventsSyncOptions {
 *
 * The current watermark is exposed via `watermark` and advances
 * monotonically as events are applied.
+* @experimental
 */
 declare class EventsSync {
   #private;

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { 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-VfJ76cK4.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-GhuZAKgm.js";
-export { type C as ClientSeq, type b as EventLogSnapshot, type G as GlobalSeq, type c as LocalMirrorOptions, type M as MirrorTableDef, type R as RowChange, d as classifyChanges, e as createTableDiff, f as diffSize, i as isClientSeq, g as isDiffEmpty, h as isGlobalSeq, j as isInputEvent, m as mergeDiffs } from "./packem_shared/local-mirror.d-GhuZAKgm.js";
+import { S as SqliteAdapter } from "./packem_shared/types.d-BuAWjEY5.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-Cd8tAg-W.js";
+export { type C as ClientSeq, type b as EventLogSnapshot, type G as GlobalSeq, type c as LocalMirrorOptions, type M as MirrorTableDef, type R as RowChange, d as classifyChanges, e as createTableDiff, f as diffSize, i as isClientSeq, g as isDiffEmpty, h as isGlobalSeq, j as isInputEvent, m as mergeDiffs } from "./packem_shared/local-mirror.d-Cd8tAg-W.js";
 /**
 * Apply a single {@link TableDiff} to an in-memory row map and return
 * the updated map.
@@ -24,6 +24,7 @@ export { type C as ClientSeq, type b as EventLogSnapshot, type G as GlobalSeq, t
 * updated.get("id-1")?.name // "alice-updated"
 * updated.get("id-2")?.name // "bob"
 * ```
+* @experimental
 */
 declare const applyDiff: (current: ReadonlyMap<string, Record<string, unknown>>, diff: TableDiff) => Map<string, Record<string, unknown>>;
 /**
@@ -31,6 +32,7 @@ declare const applyDiff: (current: ReadonlyMap<string, Record<string, unknown>>,
 *
 * This is equivalent to calling {@link applyDiff} repeatedly but avoids
 * intermediate map copies.
+* @experimental
 */
 declare const applyDiffs: (current: ReadonlyMap<string, Record<string, unknown>>, diffs: ReadonlyArray<TableDiff>) => Map<string, Record<string, unknown>>;
 /**
@@ -39,6 +41,7 @@ declare const applyDiffs: (current: ReadonlyMap<string, Record<string, unknown>>
 * @param snapshot Current snapshot, e.g. `{ users: Map&lt;id, row>, posts: Map&lt;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
 */
 declare const applyDiffToSnapshot: (snapshot: ReadonlyMap<string, ReadonlyMap<string, Record<string, unknown>>>, diff: TableDiff) => Map<string, Map<string, Record<string, unknown>>>;
 /** Map a namespace-and-name pair to a qualified event type string. */
@@ -66,6 +69,7 @@ type EventTypeMap<TDefinition extends Record<string, Record<string, unknown>>> =
 *
 * The returned event has no `seq` — it is an optimistic / command payload
 * that the event log will assign a sequence number to on append.
+* @experimental
 */
 interface EventFactory<Type extends string, Payload> {
   (payload: Payload): InputEvent<Type, Payload>;
@@ -74,10 +78,12 @@ interface EventFactory<Type extends string, Payload> {
 }
 /**
 * The namespace object returned for each group of events.
+* @experimental
 */
 type EventNamespace<Ns extends string, TDefinition extends Record<string, unknown>> = { [Name in keyof TDefinition & string]: EventFactory<QualifiedType<Ns, Name>, PayloadOf<TDefinition[Name]>> };
 /**
 * The full result of {@link defineEvents}.
+* @experimental
 */
 type EventsDefinition<TDefinition extends Record<string, Record<string, unknown>>> = { [Ns in keyof TDefinition & string]: EventNamespace<Ns, TDefinition[Ns]> } & {
   /** Type-level map of event type → payload shape. Useful for generic code. */
@@ -107,12 +113,17 @@ interface DefineEventsOptions {
   */
   readonly version?: string;
 }
+/**
+* `defineEvents` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+* @experimental
+*/
 declare const defineEvents: <TDefinition extends Record<string, Record<string, unknown>>>(definition: TDefinition, options?: DefineEventsOptions) => EventsDefinition<TDefinition>;
 /**
 * Shape of the `events[]` items sent in a POST `/append` body.
 *
 * Like {@link InputEvent} but with `timestamp` optional — omit it to
 * let the server assign the timestamp.
+* @experimental
 */
 interface AppendEventInput {
   /** Globally-unique client identifier (for offline/optimistic support). */
@@ -128,7 +139,10 @@ interface AppendEventInput {
   /** Event type discriminator. */
   readonly type: string;
 }
-/** Options for constructing an {@link EventLogDOClient}. */
+/**
+* Options for constructing an {@link EventLogDOClient}.
+* @experimental
+*/
 interface EventLogDOClientOptions {
   /**
   * A function that dispatches an HTTP request to the target EventLogDO
@@ -145,6 +159,7 @@ interface EventLogDOClientOptions {
 *
 * Each method maps to one of the DO's endpoints, throws on non-OK status,
 * and returns the parsed response body.
+* @experimental
 */
 declare class EventLogDOClient {
   #private;
@@ -191,6 +206,7 @@ declare class EventLogDOClient {
 * emitter.on("userCreated", (payload) => console.log(payload.name));
 * emitter.emit("userCreated", { id: "1", name: "alice" });
 * ```
+* @experimental
 */
 declare class EventEmitter<EventMap extends Record<string, unknown>> {
   #private;
@@ -240,6 +256,7 @@ declare class EventEmitter<EventMap extends Record<string, unknown>> {
 * - `"fail"` — throw an error, halting the apply / replay cycle.
 * - A **callback** — invoked with the entry; return truthy to mark it as
 * handled (no warning), falsy to fall through to the configured fallback.
+* @experimental
 */
 type UnknownEventHandling = "warn" | "ignore" | "fail" | ((entry: EventLogEntry) => boolean);
 /**
@@ -248,6 +265,7 @@ type UnknownEventHandling = "warn" | "ignore" | "fail" | ((entry: EventLogEntry)
 * 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>`.
+* @experimental
 */
 type EventSourceEvents = {
   /** Fired (once) after the initial replay completes. */
@@ -270,10 +288,12 @@ type EventSourceEvents = {
 *
 * Pure functions are strongly encouraged: given the same event payload
 * and state, they must produce the same next state.
+* @experimental
 */
 type EventReducer<S> = (state: S, entry: EventLogEntry) => S;
 /**
 * Options for constructing an {@link EventSource}.
+* @experimental
 */
 interface EventSourceOptions {
   /**
@@ -295,6 +315,7 @@ interface EventSourceOptions {
 * const entry = source.applyEvent("user-created", { id: "1", name: "alice" });
 * console.log(source.state); // updated state
 * ```
+* @experimental
 */
 declare class EventSource<S extends Record<string, unknown> = Record<string, unknown>> {
   #private;
@@ -366,6 +387,7 @@ declare class EventSource<S extends Record<string, unknown> = Record<string, unk
 * the {@link InMemorySnapshotStore} is used for the offline-first
 * local mirror, while a production client would implement this
 * over IndexedDB or OPFS.
+* @experimental
 */
 interface SnapshotStore {
   /** Delete all snapshots. */
@@ -383,6 +405,7 @@ interface SnapshotStore {
 * In-memory snapshot store. Useful for testing and for the local
 * offline-first mirror where persistence is handled at a higher
 * layer (IndexedDB adapter).
+* @experimental
 */
 declare class InMemorySnapshotStore implements SnapshotStore {
   #private;
@@ -397,10 +420,12 @@ declare class InMemorySnapshotStore implements SnapshotStore {
 *
 * Pure functions are strongly encouraged: given the same event and state,
 * they must produce the same next state for deterministic replay.
+* @experimental
 */
 type MaterializerReducer<S> = (state: S, entry: EventLogEntry) => S;
 /**
 * Options for defining a single materializer.
+* @experimental
 */
 interface MaterializerDef<S> {
   /**
@@ -416,6 +441,7 @@ interface MaterializerDef<S> {
 }
 /**
 * A constructed materializer ready to be used with a {@link MaterializerRuntime}.
+* @experimental
 */
 interface Materializer<S> {
   /** Apply a single event entry through the reducer. */
@@ -433,6 +459,7 @@ interface Materializer<S> {
 *
 * The returned {@link Materializer} object can be used standalone or passed
 * to a {@link MaterializerRuntime} for automatic log subscription.
+* @experimental
 */
 declare const defineMaterializer: <S>(definition: MaterializerDef<S>) => Materializer<S>;
 /**
@@ -446,6 +473,7 @@ declare const defineMaterializer: <S>(definition: MaterializerDef<S>) => Materia
 type AnyMaterializer = Materializer<any>;
 /**
 * Options for constructing a {@link MaterializerRuntime}.
+* @experimental
 */
 interface MaterializerRuntimeOptions {
   /**
@@ -472,6 +500,7 @@ interface MaterializerRuntimeOptions {
 * - Applying new events as they arrive
 * - Periodic snapshot persistence
 * - Recovery from snapshots (replay only what's missing)
+* @experimental
 */
 declare class MaterializerRuntime {
   #private;
@@ -539,6 +568,7 @@ declare class MaterializerRuntime {
 * @param database SQLite adapter the statements run against.
 * @param diff The table diff to apply.
 * @param pkColumn Primary key column for DELETE/UPDATE (default `"id"`).
+* @experimental
 */
 declare const applyDiffToDatabase: (database: SqliteAdapter, diff: TableDiff, pkColumn?: string) => void;
 /**
@@ -546,6 +576,7 @@ declare const applyDiffToDatabase: (database: SqliteAdapter, diff: TableDiff, pk
 *
 * Each diff uses `"id"` as the primary key column. For tables with a custom
 * PK, use {@link applyDiffToDatabase} per-diff and pass the PK explicitly.
+* @experimental
 */
 declare const applyDiffsToDatabase: (database: SqliteAdapter, diffs: ReadonlyArray<TableDiff>) => void;
 interface EventLogDOState {
@@ -555,6 +586,10 @@ interface EventLogDOState {
     };
   };
 }
+/**
+* `EventLogDO` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+* @experimental
+*/
 declare class EventLogDO {
   #private;
   protected state: EventLogDOState;
@@ -588,6 +623,7 @@ type Middleware<ContextIn, ContextOut> = (options: {
 *
 * Each method delegates to the corresponding {@link EventLogDOClient} method,
 * so handlers never need to import or reference the DO client directly.
+* @experimental
 */
 interface EventsFacade {
   /**
@@ -624,6 +660,7 @@ interface EventsFacade {
 }
 /**
 * The context shape produced by {@link eventsContext}.
+* @experimental
 */
 interface EventsContextOutput {
   /** Typed event log facade backed by an {@link EventLogDOClient}. */
@@ -654,12 +691,14 @@ interface EventsContextOutput {
 * return entry;
 * });
 * ```
+* @experimental
 */
 declare const eventsContext: <Context>(client: EventLogDOClient) => Middleware<Context, Context & EventsContextOutput>;
 /**
 * A dependency-light subscription sink interface that mirrors what
 * `LunoraClient.subscribe` expects, so the mirror helper doesn't
 * need to import `@lunora/client`.
+* @experimental
 */
 interface SubscriptionClient {
   subscribe: (functionRef: {
@@ -693,16 +732,19 @@ interface SubscriptionClient {
 * // Later:
 * unsub();
 * ```
+* @experimental
 */
 declare const subscribeToMirror: (client: SubscriptionClient, mirror: LocalMirror, functionRef: {
   __lunoraRef: string;
 }, args: Record<string, unknown>, shardKey?: string) => (() => void);
 /**
 * Callback signature for state-change subscriptions.
+* @experimental
 */
 type StateChangeCallback = (state: Readonly<Record<string, unknown>>) => void;
 /**
 * Callback signature for event-type subscriptions.
+* @experimental
 */
 type EventCallback = (entry: EventLogEntry) => void;
 /**
@@ -730,6 +772,7 @@ type EventCallback = (entry: EventLogEntry) => void;
 * unsub1();
 * unsub2();
 * ```
+* @experimental
 */
 declare class SubscriptionManager {
   #private;
@@ -764,6 +807,7 @@ declare class SubscriptionManager {
 }
 /**
 * Options for constructing an {@link EventsSync}.
+* @experimental
 */
 interface EventsSyncOptions {
   /**
@@ -830,6 +874,7 @@ interface EventsSyncOptions {
 *
 * The current watermark is exposed via `watermark` and advances
 * monotonically as events are applied.
+* @experimental
 */
 declare class EventsSync {
   #private;

package/dist/packem_shared/{local-mirror.d-GhuZAKgm.d.ts → local-mirror.d-BUeOe5KC.d.mts}

@@ -1,9 +1,10 @@
-import { S as SqliteAdapter } from "./types.d-VfJ76cK4.js";
+import { S as SqliteAdapter } from "./types.d-BuAWjEY5.mjs";
 /**
 * 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>;
@@ -22,6 +23,7 @@ type RowChange = {
 * `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. */
@@ -33,18 +35,22 @@ interface TableDiff {
 }
 /**
 * Create a {@link TableDiff} with a snapshot of the current time.
+* @experimental
 */
 declare const createTableDiff: (table: string, changes: ReadonlyArray<RowChange>, timestamp?: number) => 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[];
@@ -55,6 +61,7 @@ declare const classifyChanges: (diff: TableDiff) => {
 * 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;
 /**
@@ -75,6 +82,7 @@ declare const mergeDiffs: (diffs: ReadonlyArray<TableDiff>) => TableDiff | null;
 * Monotonically increasing, assigned by `EventLog` (in-memory) or
 * `EventLogDO` (Durable Object). All confirmed log entries carry a
 * `GlobalSeq`.
+* @experimental
 */
 type GlobalSeq = number;
 /**
@@ -83,6 +91,7 @@ type GlobalSeq = number;
 * 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. */
@@ -94,14 +103,17 @@ interface ClientSeq {
 }
 /**
 * 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;
 /**
@@ -117,6 +129,7 @@ declare const isClientSeq: (seq: Seq) => seq is ClientSeq;
 * const event = events.chat.messageSent({ channelId: "c1", text: "hello" });
 * // event: InputEvent&lt;"chat.messageSent", { channelId: string; text: string }>
 * ```
+* @experimental
 */
 interface InputEvent<Type extends string = string, Payload = unknown> {
   /** Arbitrary JSON-serialisable payload. */
@@ -128,6 +141,7 @@ interface InputEvent<Type extends string = string, Payload = unknown> {
 }
 /**
 * Type guard: check whether `value` is an {@link InputEvent}.
+* @experimental
 */
 declare const isInputEvent: (value: unknown) => value is InputEvent;
 /**
@@ -136,6 +150,7 @@ declare const isInputEvent: (value: unknown) => value is InputEvent;
 * 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 {
   /**
@@ -175,6 +190,7 @@ interface EventLogEntry {
 }
 /**
 * Serialised snapshot of the log — used for persistence and transfer.
+* @experimental
 */
 interface EventLogSnapshot {
   readonly entries: ReadonlyArray<EventLogEntry>;
@@ -184,6 +200,7 @@ interface EventLogSnapshot {
 }
 /**
 * Optional metadata that can accompany an appended event.
+* @experimental
 */
 interface AppendOptions {
   /** Globally-unique client identifier. */
@@ -205,6 +222,7 @@ interface AppendOptions {
 * @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;
@@ -280,12 +298,17 @@ declare class EventLog {
   */
   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. */
@@ -325,6 +348,10 @@ interface LocalMirrorOptions {
 * ```
 */
 type ChangeSubscriber = () => void;
+/**
+* `LocalMirror` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+* @experimental
+*/
 declare class LocalMirror {
   #private;
   /**

package/dist/packem_shared/{local-mirror.d-Bp19ueGy.d.mts → local-mirror.d-Cd8tAg-W.d.ts}

@@ -1,9 +1,10 @@
-import { S as SqliteAdapter } from "./types.d-VfJ76cK4.mjs";
+import { S as SqliteAdapter } from "./types.d-BuAWjEY5.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>;
@@ -22,6 +23,7 @@ type RowChange = {
 * `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. */
@@ -33,18 +35,22 @@ interface TableDiff {
 }
 /**
 * Create a {@link TableDiff} with a snapshot of the current time.
+* @experimental
 */
 declare const createTableDiff: (table: string, changes: ReadonlyArray<RowChange>, timestamp?: number) => 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[];
@@ -55,6 +61,7 @@ declare const classifyChanges: (diff: TableDiff) => {
 * 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;
 /**
@@ -75,6 +82,7 @@ declare const mergeDiffs: (diffs: ReadonlyArray<TableDiff>) => TableDiff | null;
 * Monotonically increasing, assigned by `EventLog` (in-memory) or
 * `EventLogDO` (Durable Object). All confirmed log entries carry a
 * `GlobalSeq`.
+* @experimental
 */
 type GlobalSeq = number;
 /**
@@ -83,6 +91,7 @@ type GlobalSeq = number;
 * 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. */
@@ -94,14 +103,17 @@ interface ClientSeq {
 }
 /**
 * 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;
 /**
@@ -117,6 +129,7 @@ declare const isClientSeq: (seq: Seq) => seq is ClientSeq;
 * const event = events.chat.messageSent({ channelId: "c1", text: "hello" });
 * // event: InputEvent&lt;"chat.messageSent", { channelId: string; text: string }>
 * ```
+* @experimental
 */
 interface InputEvent<Type extends string = string, Payload = unknown> {
   /** Arbitrary JSON-serialisable payload. */
@@ -128,6 +141,7 @@ interface InputEvent<Type extends string = string, Payload = unknown> {
 }
 /**
 * Type guard: check whether `value` is an {@link InputEvent}.
+* @experimental
 */
 declare const isInputEvent: (value: unknown) => value is InputEvent;
 /**
@@ -136,6 +150,7 @@ declare const isInputEvent: (value: unknown) => value is InputEvent;
 * 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 {
   /**
@@ -175,6 +190,7 @@ interface EventLogEntry {
 }
 /**
 * Serialised snapshot of the log — used for persistence and transfer.
+* @experimental
 */
 interface EventLogSnapshot {
   readonly entries: ReadonlyArray<EventLogEntry>;
@@ -184,6 +200,7 @@ interface EventLogSnapshot {
 }
 /**
 * Optional metadata that can accompany an appended event.
+* @experimental
 */
 interface AppendOptions {
   /** Globally-unique client identifier. */
@@ -205,6 +222,7 @@ interface AppendOptions {
 * @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;
@@ -280,12 +298,17 @@ declare class EventLog {
   */
   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. */
@@ -325,6 +348,10 @@ interface LocalMirrorOptions {
 * ```
 */
 type ChangeSubscriber = () => void;
+/**
+* `LocalMirror` is part of the experimental `@lunora/replica` API and may change without a major version bump.
+* @experimental
+*/
 declare class LocalMirror {
   #private;
   /**

package/dist/packem_shared/{types.d-VfJ76cK4.d.mts → types.d-BuAWjEY5.d.mts}

@@ -4,6 +4,7 @@
 * 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. */

package/dist/packem_shared/{types.d-VfJ76cK4.d.ts → types.d-BuAWjEY5.d.ts}

@@ -4,6 +4,7 @@
 * 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. */

package/dist/react.d.mts

@@ -1,7 +1,8 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-Bp19ueGy.mjs";
-import "./packem_shared/types.d-VfJ76cK4.mjs";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-BUeOe5KC.mjs";
+import "./packem_shared/types.d-BuAWjEY5.mjs";
 /**
 * Options for the {@link useLocalQuery} hook.
+* @experimental
 */
 interface UseLocalQueryOptions {
   /**
@@ -60,6 +61,7 @@ interface UseLocalQueryOptions {
 *   return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
 * }
 * ```
+* @experimental
 */
 declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>, _options?: UseLocalQueryOptions) => T[] | undefined;
 export { UseLocalQueryOptions, useLocalQuery };

package/dist/react.d.ts

@@ -1,7 +1,8 @@
-import { L as LocalMirror } from "./packem_shared/local-mirror.d-GhuZAKgm.js";
-import "./packem_shared/types.d-VfJ76cK4.js";
+import { L as LocalMirror } from "./packem_shared/local-mirror.d-Cd8tAg-W.js";
+import "./packem_shared/types.d-BuAWjEY5.js";
 /**
 * Options for the {@link useLocalQuery} hook.
+* @experimental
 */
 interface UseLocalQueryOptions {
   /**
@@ -60,6 +61,7 @@ interface UseLocalQueryOptions {
 *   return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
 * }
 * ```
+* @experimental
 */
 declare const useLocalQuery: <T = Record<string, unknown>>(mirror: LocalMirror, sql: string, params?: ReadonlyArray<unknown>, _options?: UseLocalQueryOptions) => T[] | undefined;
 export { UseLocalQueryOptions, useLocalQuery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/replica",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "description": "Local-first replica runtime + local SQLite mirror for Lunora",
   "keywords": [
     "cloudflare",
@@ -62,7 +62,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@lunora/server": "1.0.0-alpha.24",
+    "@lunora/server": ">=1.0.0-alpha.24 <2.0.0-0",
     "@sqlite.org/sqlite-wasm": "*",
     "better-sqlite3": "*",
     "react": "^18.0.0 || ^19.0.0",