@lunora/replica 0.0.0 → 1.0.0-alpha.100

package/dist/index.d.ts

@@ -0,0 +1,1074 @@
+export {
+/**
+ * \@lunora/replica — Event sourcing runtime + local SQLite mirror for Lunora
+ *
+ * ## Modules
+ *
+ * - **EventEmitter** — type-safe event emitter with typed + wildcard listeners.
+ * - **EventSource** — event-sourcing runtime that derives state from an
+ * append-only log via a reducer.
+ * - **SubscriptionManager** — manages state and event-type subscriptions.
+ * - **SnapshotStore** — interface + in-memory store for persisting
+ * event-sourced state snapshots.
+ * - **LocalMirror** — local SQLite mirror that applies typed table diffs.
+ * - **EventLog** — append-only log for events and catch-up replication.
+ */
+createBetterSqlite3Adapter } from "./adapters/better-sqlite3.js";
+export { createSqliteWasmAdapter } from "./adapters/sqlite-wasm.js";
+export { createSqlJsAdapter } from "./adapters/sqljs.js";
+import { S as SqliteAdapter } from "./packem_shared/types.d-BuLTPLaQ.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-wbGXkXaE.js";
+export { type C as ClientSeq, type b as EventLogOptions, type c as EventLogSnapshot, type G as GlobalSeq, type d as LocalMirrorOptions, type M as MirrorTableDef, type R as RowChange, e as classifyChanges, f as createTableDiff, g as diffSize, i as isClientSeq, h as isDiffEmpty, j as isGlobalSeq, k as isInputEvent, m as mergeDiffs } from "./packem_shared/local-mirror.d-wbGXkXaE.js";
+/**
+ * Apply a single {@link TableDiff} to an in-memory row map and return
+ * the updated map.
+ *
+ * The function creates a **shallow copy** of the input map so the caller's
+ * reference stays untouched unless they choose to replace it.
+ * @example
+ * ```ts
+ * const rows = new Map<string, Record<string, unknown>>();
+ * rows.set("id-1", { name: "alice" });
+ *
+ * const diff = createTableDiff("users", [
+ *   { type: "insert", data: { id: "id-2", name: "bob" } },
+ *   { type: "update", id: "id-1", data: { name: "alice-updated" } },
+ * ]);
+ *
+ * const updated = applyDiff(rows, diff);
+ * 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>>;
+/**
+ * Apply an array of diffs **in order**, returning the final row map.
+ *
+ * This is equivalent to calling {@link applyDiff} repeatedly but copies the
+ * input map exactly once rather than once per diff — catch-up replay of an
+ * N-diff backlog is a single copy, not N+1.
+ * @experimental
+ */
+declare const applyDiffs: (current: ReadonlyMap<string, Record<string, unknown>>, diffs: ReadonlyArray<TableDiff>) => Map<string, Record<string, unknown>>;
+/**
+ * Merge the row-level effect of a {@link TableDiff} into plain JSON
+ * state keyed by table name, returning a new snapshot.
+ * @param snapshot Current snapshot, e.g. `{ users: Map<id, row>, posts: Map<id, row> }`.
+ * @param diff Contains the target table name and the row-level changes to merge.
+ * @returns A shallow copy of `snapshot` with `diff.table`'s map updated.
+ * @experimental
+ */
+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. */
+type QualifiedType<Ns extends string, Name extends string> = `${Ns}.${Name}`;
+/**
+ * Extract the payload type from an event schema.
+ *
+ * A `@lunora/values` validator (e.g. `v.object(...)`) carries its output type on
+ * the phantom `__type` field (the same hook `Infer` reads), so match that FIRST
+ * — otherwise a validator, being object-shaped, would fall through to the
+ * `Record` branch and resolve to the validator instance itself rather than its
+ * validated `{ … }` output. A bare factory function or plain descriptor object
+ * is still supported as a fallback.
+ */
+type PayloadOf<T> = T extends {
+  readonly __type: infer P;
+} ? P : T extends ((payload: infer P) => unknown) ? P : T extends Record<string, unknown> ? T : never;
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+/**
+ * Produce `{ "ns.name": Payload }` for every event, merged.
+ */
+type EventTypeMap<TDefinition extends Record<string, Record<string, unknown>>> = UnionToIntersection<{ [Ns in keyof TDefinition & string]: { [Name in keyof TDefinition[Ns] & string]: { [K in QualifiedType<Ns, Name>]: PayloadOf<TDefinition[Ns][Name]>; }; }[keyof TDefinition[Ns] & string]; }[keyof TDefinition & string]>;
+/**
+ * A factory function that creates an {@link InputEvent} for a specific event type.
+ *
+ * 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>;
+  /** The fully qualified event type string (e.g. `"chat.messageSent"`). */
+  readonly type: Type;
+}
+/**
+ * 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. */
+  readonly _types: EventTypeMap<TDefinition>;
+};
+/**
+ * Declare typed event types for event sourcing.
+ *
+ * Each key under a namespace becomes a factory function that produces
+ * an {@link InputEvent} — an optimistic / command event that the event
+ * log will assign a sequence number to on append.
+ * @param definition A nested object where the outer keys are namespaces
+ * and the inner keys are event names mapped to their
+ * payload schemas (or simple type-descriptor objects).
+ * @returns An object with the same nesting structure, where each leaf is
+ * a factory function plus a `.type` property.
+ */
+interface DefineEventsOptions {
+  /**
+   * Optional version prefix for all event types.
+   *
+   * When set, every qualified event type is prefixed with `"v<N>."`, enabling
+   * versioned event naming like `"v1.chat.messageSent"` or `"v2.chat.messageSent"`.
+   * This allows materializers to evolve their handling logic based on the event
+   * version without breaking backward compatibility.
+   * @example "v1" → event type becomes "v1.chat.messageSent"
+   */
+  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). */
+  readonly clientId?: string;
+  /** Causal parent sequence number (ClientSeq for optimistic, GlobalSeq for confirmed). */
+  readonly parentSeqNum?: Seq;
+  /** Arbitrary JSON-serialisable payload. */
+  readonly payload: unknown;
+  /** Session identifier within the client. */
+  readonly sessionId?: string;
+  /** Millisecond timestamp (epoch) — omit to let the server assign it. */
+  readonly timestamp?: number;
+  /** Event type discriminator. */
+  readonly type: string;
+}
+/**
+ * Options for constructing an {@link EventLogDOClient}.
+ * @experimental
+ */
+interface EventLogDOClientOptions {
+  /**
+   * A function that dispatches an HTTP request to the target EventLogDO
+   * instance. In a Cloudflare Worker this is:
+   *
+   * ```ts
+   * (req) => env.MY_DO_NAMESPACE.get(id).fetch(req)
+   * ```
+   */
+  fetch: (request: Request) => Promise<Response>;
+}
+/**
+ * Lightweight HTTP client for EventLogDO's RPC surface.
+ *
+ * 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;
+  constructor(options: EventLogDOClientOptions);
+  /**
+   * Append one or more events to the log.
+   * @param events The events to append.
+   * @param options Idempotency controls for the batch.
+   * @param options.batchId Optional idempotency key for the whole batch — a
+   * retried `append` call with the same `batchId` (e.g. after a network
+   * timeout that hid a successful response) returns the originally-persisted
+   * entries instead of inserting duplicates.
+   * @returns The persisted entries with their assigned `seq` numbers.
+   */
+  append(events: AppendEventInput[], options?: {
+    batchId?: string;
+  }): Promise<EventLogEntry[]>;
+  /**
+   * Fetch ONE page of entries with `seq >= sinceSeq`.
+   *
+   * The DO bounds every page (500 entries unless `limit` says otherwise, 1000
+   * max), so `getSince(0)` is the START of the log, never all of it — a
+   * catch-up walks pages until `truncated` is `false`:
+   *
+   * ```ts
+   * let seq = 0;
+   * for (;;) {
+   *   const page = await client.getSince(seq);
+   *   apply(page.entries);
+   *   if (!page.truncated || page.cursor === undefined) break;
+   *   seq = page.cursor;
+   * }
+   * ```
+   * @returns `{ entries, truncated, cursor }` — `cursor` is the `sinceSeq`
+   * for the next page and is present exactly when `truncated` is `true`.
+   */
+  getSince(sinceSeq: number, limit?: number): Promise<{
+    cursor?: number;
+    entries: EventLogEntry[];
+    truncated: boolean;
+  }>;
+  /**
+   * Return the total number of entries currently in the log.
+   */
+  getSize(): Promise<number>;
+  /**
+   * Return the full log state — all entries plus the next seq number.
+   *
+   * Only for a log small enough to answer as one body: the DO refuses with a
+   * 413 past its page ceiling, since serialising an unbounded log into one
+   * response is what {@link EventLogDOClient.getSince} was bounded to avoid.
+   * A catch-up walks `getSince` instead.
+   * @throws Error when the log is too large to return in one body
+   */
+  getState(): Promise<{
+    entries: EventLogEntry[];
+    nextSeq: number;
+  }>;
+}
+/**
+ * Type-safe event emitter that powers the event-sourcing runtime.
+ * @example
+ * ```ts
+ * type MyEvents = { userCreated: { id: string; name: string }; error: { message: string } };
+ *
+ * const emitter = new EventEmitter<MyEvents>();
+ * 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;
+  /**
+   * Register a handler for a specific event type.
+   * @returns An unsubscribe function (equivalent to calling {@link off}).
+   */
+  on<K extends keyof EventMap>(event: K, handler: (payload: EventMap[K]) => void): () => void;
+  /**
+   * Remove a previously registered handler.
+   */
+  off<K extends keyof EventMap>(event: K, handler: (payload: EventMap[K]) => void): void;
+  /**
+   * Register a wildcard handler that fires for **every** event type.
+   * @returns An unsubscribe function.
+   */
+  onAny(handler: (event: keyof EventMap, payload: unknown) => void): () => void;
+  /**
+   * Remove a wildcard handler.
+   */
+  offAny(handler: (event: keyof EventMap, payload: unknown) => void): void;
+  /**
+   * 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<K extends keyof EventMap>(event: K, payload: EventMap[K]): boolean;
+  /**
+   * Return `true` when at least one listener is registered for `event`.
+   */
+  hasListeners(event: keyof EventMap): boolean;
+  /**
+   * Return the number of typed listeners for a specific event.
+   */
+  listenerCount(event: keyof EventMap): number;
+  /**
+   * Remove all listeners.
+   */
+  clear(): void;
+}
+/**
+ * Strategy for handling events whose `type` the reducer does not recognise.
+ *
+ * - `"warn"` _(default)_ — log a warning and skip the event (state unchanged).
+ * - `"ignore"` — skip silently (no warning, no error).
+ * - `"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);
+/**
+ * Events emitted by the {@link EventSource} runtime.
+ *
+ * A `type` (not `interface`) so it satisfies `EventEmitter`'s
+ * `Record<string, unknown>` constraint — interfaces have no implicit index
+ * signature and aren't assignable to `Record<string, unknown>`.
+ * @experimental
+ */
+type EventSourceEvents = {
+  /** Fired (once) after the initial replay completes. */
+  ready: {
+    entryCount: number;
+  };
+  /** Fired when a replay error occurs — the runtime will skip the bad entry. */
+  "replay-error": {
+    entry: EventLogEntry;
+    error: Error;
+  };
+  /** Fired after an event has been applied and the state updated. */
+  "state-changed": {
+    entry: EventLogEntry;
+    state: Record<string, unknown>;
+  };
+};
+/**
+ * Sentinel a reducer can return to EXPLICITLY signal it does not handle a
+ * given event's `type` — as opposed to returning the current `state`
+ * reference unchanged to represent a legitimate, idempotent no-op for a type
+ * it DOES recognise.
+ *
+ * Reference equality alone can't tell these two cases apart (REPLICA-07): a
+ * reducer that intentionally returns `state` for a type it fully understands
+ * (e.g. "already applied this event, nothing to do") would otherwise be
+ * misclassified as "unhandled" and trigger {@link UnknownEventHandling} — a
+ * spurious warning, or worse, a thrown error under `"fail"`. Return `UNHANDLED`
+ * only for a `type` your reducer truly does not recognise; every other return
+ * (including a `state` returned by reference) is treated as handled.
+ *
+ * Reducers that always recognise every event they're given (a single
+ * always-matching type, or a catch-all) can ignore this entirely.
+ * @experimental
+ */
+declare const UNHANDLED: unique symbol;
+/**
+ * A function that reduces an event into a state mutation.
+ *
+ * Pure functions are strongly encouraged: given the same event payload
+ * and state, they must produce the same next state. Return {@link UNHANDLED}
+ * to explicitly mark an event `type` this reducer does not process — see
+ * {@link UNHANDLED} for why reference equality against the input `state`
+ * cannot be used for this instead.
+ * @experimental
+ */
+type EventReducer<S> = (state: S, entry: EventLogEntry) => S | typeof UNHANDLED;
+/**
+ * Options for constructing an {@link EventSource}.
+ * @experimental
+ */
+interface EventSourceOptions {
+  /**
+   * Cap this runtime's internal `log` to this many entries (REPLICA-06).
+   * `replayFromLog` copies every entry it replays from the source log into
+   * `this.log` too — a second, uncapped copy of the same history — so a
+   * long-lived `EventSource` fed by repeated replay accumulates entries in
+   * both places forever without a cap.
+   *
+   * `undefined` (the default) preserves unbounded retention.
+   */
+  maxLogEntries?: number;
+  /**
+   * How to handle events whose `type` is not recognised by the reducer.
+   * @default "warn"
+   */
+  unknownEventHandling?: UnknownEventHandling;
+}
+/**
+ * Event-sourcing runtime that maintains a derived state by replaying an
+ * append-only {@link EventLog}.
+ *
+ * Usage:
+ * ```ts
+ * const source = new EventSource(initialState, myReducer);
+ * await source.replayFromLog(existingLog);
+ *
+ * // Later, when a new event arrives:
+ * 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;
+  readonly emitter: EventEmitter<EventSourceEvents>;
+  readonly log: EventLog;
+  constructor(initialState: S, reducer: EventReducer<S>, options?: EventSourceOptions);
+  /**
+   * The current derived state. Read-only snapshot; mutate through events.
+   */
+  get state(): Readonly<S>;
+  /**
+   * Whether the initial replay from an existing log has completed.
+   */
+  get replayed(): boolean;
+  /**
+   * Append a new event to the log and apply it to the current state.
+   *
+   * Accepts either an {@link InputEvent} (e.g. from a `defineEvents` factory)
+   * or the traditional `(type, payload)` pair.
+   * @returns The newly created log entry (with its assigned `seq`).
+   */
+  applyEvent(event: InputEvent, options?: AppendOptions): EventLogEntry;
+  applyEvent(type: string, payload: unknown, options?: AppendOptions): EventLogEntry;
+  /**
+   * Replay all entries from an existing {@link EventLog} to bootstrap
+   * the current state.
+   *
+   * Idempotent across calls: only source entries past the `#lastAppliedSeq`
+   * watermark are applied, so re-invoking picks up just the new entries.
+   * @param log The external log to replay from.
+   */
+  replayFromLog(log: EventLog): void;
+  /**
+   * Reset the runtime to a base state, optionally resuming from a watermark.
+   *
+   * Useful after loading a snapshot from the DO: pass the snapshot's state as
+   * `initialState` and its highest applied source `seq` as `resumeFromSeq`, so
+   * the next {@link replayFromLog} applies ONLY the events after the snapshot
+   * (`getSince(resumeFromSeq + 1)`) rather than replaying the whole log on top
+   * of the snapshot — which would double-apply non-idempotent reducers.
+   *
+   * Omit `resumeFromSeq` (default `-1`) for a full reset that replays from the
+   * beginning.
+   * @param initialState The base state to reset to (e.g. a loaded snapshot).
+   * @param resumeFromSeq Highest source `seq` already baked into `initialState`, or `-1` to replay all.
+   */
+  reset(initialState: S, resumeFromSeq?: number): void;
+  /**
+   * Return an async generator that yields every event as it is applied,
+   * starting from the events currently in the log and continuing with
+   * every future `applyEvent` / `replayFromLog` call.
+   *
+   * The generator runs indefinitely unless given a `signal` — callers
+   * should break out of the `for await` loop or pass an `AbortSignal` to
+   * stop it (an abort settles the generator, `done: true`, on its next
+   * iteration step; it does not throw).
+   * @example
+   * ```ts
+   * for await (const entry of source.events()) {
+   *   console.log("event applied:", entry);
+   * }
+   * ```
+   */
+  events(signal?: AbortSignal): AsyncGenerator<EventLogEntry>;
+}
+/**
+ * Interface for persisting event-sourced state snapshots.
+ *
+ * In a Lunora app the primary implementation is backed by the
+ * SnapshotDO (a Durable Object) on the server side. On the client
+ * 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. */
+  clear: () => Promise<void>;
+  /** Delete a single snapshot. */
+  delete: (key: string) => Promise<void>;
+  /** List all snapshot keys. */
+  list: () => Promise<string[]>;
+  /** Load a previously saved snapshot, or `null` when not found. */
+  load: (key: string) => Promise<unknown>;
+  /** Persist a snapshot under `key`. */
+  save: (key: string, snapshot: unknown) => Promise<void>;
+}
+/**
+ * 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;
+  save(key: string, snapshot: unknown): Promise<void>;
+  load(key: string): Promise<unknown>;
+  list(): Promise<string[]>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+}
+/**
+ * A function that reduces an event entry into a state mutation.
+ *
+ * Pure functions are strongly encouraged: given the same event and state,
+ * they must produce the same next state for deterministic replay.
+ *
+ * Return {@link UNHANDLED} for an event `type` the reducer does not recognise —
+ * that, and only that, is what {@link MaterializerRuntimeOptions.unknownEventHandling}
+ * reacts to. Returning the current `state` is a legitimate, idempotent no-op for
+ * a type the reducer DOES handle; reference equality cannot tell the two apart
+ * (REPLICA-07), and reading it as "unhandled" warned about — or, under `"fail"`,
+ * threw on — an event type the reducer explicitly recognised.
+ * @experimental
+ */
+type MaterializerReducer<S> = (state: S, entry: EventLogEntry) => S | typeof UNHANDLED;
+/**
+ * Options for defining a single materializer.
+ * @experimental
+ */
+interface MaterializerDef<S> {
+  /**
+   * Reducer invoked for every event in the log.
+   *
+   * Return the current state unchanged for a recognised event with nothing to
+   * do; return {@link UNHANDLED} for a `type` this reducer does not process.
+   */
+  handle: MaterializerReducer<S>;
+  /** Factory for the initial (empty) state. */
+  initial: () => S;
+  /** Unique name (used as the snapshot storage key). */
+  readonly name: string;
+}
+/**
+ * A constructed materializer ready to be used with a {@link MaterializerRuntime}.
+ * @experimental
+ */
+interface Materializer<S> {
+  /**
+   * Apply a single event entry through the reducer.
+   * @returns `false` when the reducer returned {@link UNHANDLED} (state left
+   * untouched), `true` otherwise.
+   */
+  apply: (entry: EventLogEntry) => boolean;
+  readonly def: MaterializerDef<S>;
+  /** Reset to the initial state. */
+  reset: () => void;
+  /** Replace the runtime state (used on snapshot restore / replay). */
+  setState: (state: S) => void;
+  /** Current (runtime) derived state. */
+  readonly state: Readonly<S>;
+}
+/**
+ * Declare a materializer — a named reducer that derives state from events.
+ *
+ * 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>;
+/**
+ * A materializer of any state shape. The {@link MaterializerRuntime} holds a
+ * heterogeneous collection and only ever calls `apply(entry)` / `setState(...)`
+ * (with cast values) / reads `def.name` — it never needs the concrete state
+ * type. `Materializer<unknown>` won't do: `setState(state: S)` makes
+ * `Materializer<S>` invariant in `S`, so `Materializer<number>` isn't assignable
+ * to `Materializer<unknown>`. Erasing the type param is the idiomatic fix.
+ */
+type AnyMaterializer = Materializer<any>;
+/**
+ * Options for constructing a {@link MaterializerRuntime}.
+ * @experimental
+ */
+interface MaterializerRuntimeOptions {
+  /**
+   * Optional EventLogDO client for persistent event log integration.
+   *
+   * When provided, the runtime can bootstrap from the DO on startup
+   * (recover from snapshots → catch up via `getSince`) and append
+   * new events through the DO automatically.
+   */
+  doClient?: EventLogDOClient;
+  /** Optional snapshot store for persisting/recovering materialized state. */
+  snapshotStore?: SnapshotStore;
+  /**
+   * How to handle an event that every materializer explicitly DECLINED — one
+   * for which each reducer returned {@link UNHANDLED}.
+   *
+   * A reducer that instead falls through to `return state` for a type it does
+   * not recognise has, as far as the runtime can tell, handled the event: it
+   * changed nothing, but it did not decline. `"fail"` and `"warn"` are inert
+   * for such a reducer, and no option here can make them otherwise — write the
+   * reducer's default branch as `return UNHANDLED` if you want to hear about
+   * unknown types.
+   *
+   * A materializer whose own watermark is already past the entry does not run
+   * for it, and does not count as declining it: an entry that was already
+   * applied has already been classified, so a catch-up replaying it for a
+   * LAGGING materializer alone never re-reports it. Without that, `"fail"`
+   * aborted a catch-up on events a snapshot-recovered sibling had processed.
+   * @default "warn"
+   */
+  unknownEventHandling?: UnknownEventHandling;
+}
+/**
+ * Runtime that drives one or more materializers from an event log.
+ *
+ * Handles:
+ * - Replaying the full log on startup
+ * - Applying new events as they arrive
+ * - Periodic snapshot persistence
+ * - Recovery from snapshots (replay only what's missing)
+ * @experimental
+ */
+declare class MaterializerRuntime {
+  #private;
+  constructor(materializers: AnyMaterializer[], options?: MaterializerRuntimeOptions);
+  /**
+   * The lowest per-materializer watermark — the seq of the next event that
+   * at least one materializer has not yet applied. `0` when there are no
+   * materializers.
+   */
+  get appliedSeq(): number;
+  /**
+   * Replay a batch of entries, applying each entry only to the
+   * materializers whose own watermark is behind it — a materializer at or
+   * past an entry's seq (e.g. recovered from a snapshot, or already caught
+   * up) skips it, so no materializer ever double-applies an event.
+   * @returns The number of entries applied to at least one materializer.
+   */
+  applyEntries(entries: ReadonlyArray<EventLogEntry>): number;
+  /**
+   * Attempt to recover materialized state from a snapshot store.
+   *
+   * When a snapshot is found for a materializer, its state AND its own
+   * watermark are restored from that snapshot. A materializer with no
+   * snapshot keeps its current watermark (`0` for a fresh runtime) — it
+   * does NOT inherit another materializer's watermark, so it still catches
+   * up from the very beginning (REPLICA-04: previously a shared watermark
+   * was bumped to the MAX across snapshots, permanently skipping events 0..N
+   * for any un-snapshotted or lagging materializer).
+   * @returns The highest snapshot `appliedSeq` across all materializers, or
+   * `0` — kept for backward compatibility; callers that need the fetch
+   * watermark for catch-up should use the per-materializer minimum instead
+   * (see `initialize`).
+   */
+  recoverFromSnapshots(): Promise<number>;
+  /**
+   * Persist the current state of all materializers as snapshots, each
+   * tagged with ITS OWN watermark (not a shared one).
+   */
+  persistSnapshots(): Promise<void>;
+  /**
+   * Bootstrap the runtime from the EventLogDO.
+   *
+   * 1. Recover materialized state from snapshots (if a snapshotStore is
+   * configured).
+   * 2. Fetch entries since the MINIMUM per-materializer watermark from
+   * the DO — not the maximum — so a materializer with no snapshot (or a
+   * lower one) still receives every event it hasn't seen (REPLICA-04).
+   * 3. Apply them through the materializers; `applyEntries` skips each
+   * entry for any materializer already past it, so nothing is double-applied.
+   *
+   * The DO answers one BOUNDED page per request, so step 2/3 walk pages until
+   * the log is exhausted — applying each page as it arrives, rather than
+   * holding the whole backlog in memory. Taking only the first page (and
+   * dropping `truncated`) would silently leave every materializer short of
+   * the log's head whenever the backlog exceeds a page.
+   *
+   * The walk is bounded by {@link MAX_CATCHUP_PAGES}: against a log written
+   * faster than it is read, "until the log is exhausted" never arrives and
+   * startup would never finish. Hitting the budget returns what was applied
+   * with every materializer's watermark advanced, so a later `initialize()`
+   * (or the ordinary append path) picks up exactly where this left off.
+   *
+   * Call this once on startup / after the DO binding is available.
+   * @returns The number of entries applied during catch-up.
+   */
+  initialize(): Promise<number>;
+  /**
+   * Append an event to the EventLogDO and apply it through all
+   * materializers.
+   *
+   * This is a convenience over calling `doClient.append(...)` +
+   * `runtime.applyEntries(...)` yourself — it persists the event
+   * **then** applies the returned entry (with its assigned seq).
+   * @returns The persisted entry with its DO-assigned `seq` — always, whether
+   * or not the entry could be applied to the materializers (see below).
+   */
+  appendEvent(input: AppendEventInput): Promise<EventLogEntry>;
+  /**
+   * Reset all materializers to their initial state and clear snapshots.
+   */
+  reset(): void;
+  /**
+   * The list of registered materializers.
+   */
+  get materializers(): ReadonlyArray<Materializer<unknown>>;
+}
+/**
+ * Apply a {@link TableDiff} to the given SQLite database by translating
+ * each row change into an INSERT, UPDATE, or DELETE statement.
+ *
+ * All statements are wrapped in a single transaction.
+ * @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;
+/**
+ * Apply multiple diffs **in order** within a single transaction.
+ *
+ * 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 {
+  storage: {
+    sql: {
+      exec: (query: string, ...params: unknown[]) => unknown;
+    };
+    /**
+     * The DO platform's native atomic-transaction primitive (async;
+     * commits on resolve, rolls back on throw/reject). Test doubles that
+     * omit it fall back to a bare (non-transactional) call — see
+     * `#handleAppend`.
+     */
+    transaction?: <T>(closure: () => Promise<T> | T) => Promise<T>;
+  };
+}
+/**
+ * `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;
+  protected env: unknown;
+  constructor(state: EventLogDOState, env: unknown);
+  fetch(request: Request): Promise<Response>;
+}
+/**
+ * `next()` advances the middleware chain. Called with no argument it forwards
+ * the current context unchanged; called with `{ ctx }` it shallow-merges the
+ * extension, and the result type reflects the widened context.
+ */
+interface MiddlewareNext<ContextIn> {
+  (): Promise<ContextIn>;
+  <Extension extends Record<string, unknown>>(options: {
+    ctx: Extension;
+  }): Promise<ContextIn & Extension>;
+}
+/**
+ * A middleware receives the current context and a `next` continuation. Its
+ * return type becomes the builder's new context, so `return next({ ctx })`
+ * propagates the extension into every downstream `.use()` and the handler.
+ */
+type Middleware<ContextIn, ContextOut> = (options: {
+  ctx: ContextIn;
+  next: MiddlewareNext<ContextIn>;
+}) => ContextOut | Promise<ContextOut>;
+/**
+ * The per-request `ctx.events` facade that {@link eventsContext} attaches.
+ *
+ * Each method delegates to the corresponding {@link EventLogDOClient} method,
+ * so handlers never need to import or reference the DO client directly.
+ * @experimental
+ */
+interface EventsFacade {
+  /**
+   * Append one or more events to the log.
+   * @returns The persisted entries with their assigned `seq` numbers.
+   */
+  append: (events: {
+    payload: unknown;
+    timestamp?: number;
+    type: string;
+  }[]) => Promise<EventLogEntry[]>;
+  /**
+   * Fetch ONE bounded page of entries with `seq >= sinceSeq`.
+   * @returns `{ entries, truncated, cursor }` — pass `cursor` back as
+   * `sinceSeq` while `truncated` is `true` to walk the whole log.
+   */
+  getSince: (sinceSeq: number, limit?: number) => Promise<{
+    cursor?: number;
+    entries: EventLogEntry[];
+    truncated: boolean;
+  }>;
+  /** Return the total number of entries currently in the log. */
+  getSize: () => Promise<number>;
+  /** Return the full log state — all entries plus the next seq number. */
+  getState: () => Promise<{
+    entries: EventLogEntry[];
+    nextSeq: number;
+  }>;
+}
+/**
+ * The context shape produced by {@link eventsContext}.
+ * @experimental
+ */
+interface EventsContextOutput {
+  /** Typed event log facade backed by an {@link EventLogDOClient}. */
+  readonly events: EventsFacade;
+}
+/**
+ * Create a middleware that attaches a typed `ctx.events` facade backed by
+ * the given {@link EventLogDOClient}.
+ *
+ * The facade surfaces `append`, `getSince`, `getSize`, and
+ * `getState` — every method the DO client exposes — so handlers can read
+ * and write the event log without reaching for the DO stub directly.
+ *
+ * The middleware is unopinionated about which context it extends — it works
+ * with `MutationCtx`, `ActionCtx`, or `QueryCtx` equally.
+ * @param client A configured {@link EventLogDOClient} instance.
+ * @returns A Lunora middleware that injects `ctx.events`.
+ *
+ * ```ts
+ * const client = new EventLogDOClient({
+ * fetch: (req) => env.EVENTS.get(id).fetch(req),
+ * });
+ *
+ * export const logEvent = mutation
+ * .use(eventsContext(client))
+ * .mutation(async ({ ctx, args }) => {
+ * const [entry] = await ctx.events.append([{ type: "order.placed", payload: args }]);
+ * 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: {
+    __lunoraRef: string;
+  }, args: Record<string, unknown>, callback: (data: unknown) => void, options?: {
+    shardKey?: string;
+  }) => () => void;
+}
+/**
+ * Subscribe a Lunora-query to the local mirror so every server push
+ * is applied to the local SQLite store.
+ *
+ * Each frame from a Lunora live query is the FULL current result set, so the
+ * callback diffs it against the previous frame: a row that is new or whose
+ * content changed is upserted, a row that dropped out is deleted, and an
+ * unchanged row produces nothing. A frame identical to the last one therefore
+ * applies no diff — no event-log entry, no `version` bump, no re-query for the
+ * hooks subscribed to the mirror.
+ *
+ * Rows are keyed by the table's primary key (`id` unless the table was
+ * registered with another `primaryKey`). A row without one still lands — the
+ * apply path derives a key from the ROW's own content — but it cannot be
+ * diffed: it is re-emitted on every frame, and it is never reconciled on
+ * removal because only keyed rows are recorded for the delete pass. Repeating an
+ * identical frame is therefore a no-op upsert, but each distinct content the
+ * un-keyed row ever holds leaves a row behind for the life of the mirror.
+ * **Mirror a query that selects the primary key.** An un-keyed shape (an
+ * aggregate, or a projection that drops `id`) is supported only so that one such
+ * row cannot take the rest of the frame down with it.
+ *
+ * The mirror table name is derived from the function ref alone (not `args`), so
+ * do NOT mirror two subscriptions to the same function with different `args`
+ * into the same mirror: they'd share one table and the snapshot-delete pass of
+ * one could remove rows still live in the other.
+ *
+ * `mirror.clearData()` resets the remembered frame. Without that reset the next
+ * identical frame diffed clean against a mirror that no longer held the rows —
+ * no changes, no `applyDiff` — and the table stayed empty until some row's
+ * content happened to change or the page reloaded.
+ *
+ * Call the returned unsubscribe function to tear down both the client
+ * subscription and future mirror writes.
+ * @example
+ * ```ts
+ * const unsub = subscribeToMirror(client, mirror, api.todos.list, { userId });
+ * // 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;
+/**
+ * Manages subscriptions to state changes and individual event types
+ * for the event-sourcing runtime.
+ *
+ * Each subscription returns an unsubscribe function — the caller is
+ * expected to call it during cleanup (e.g. in a React `useEffect`
+ * return or a Svelte `onDestroy`).
+ * @example
+ * ```ts
+ * const subs = new SubscriptionManager();
+ *
+ * // Subscribe to every state change
+ * const unsub1 = subs.onStateChange((state) => console.log("new state", state));
+ *
+ * // Subscribe to a specific event type
+ * const unsub2 = subs.onEvent("user-created", (entry) => console.log("user created", entry.payload));
+ *
+ * // Later, when state or events arrive:
+ * subs.notifyState({ users: [] });
+ * subs.notifyEvent({ seq: 1, type: "user-created", payload: { id: "1" }, timestamp: 100 });
+ *
+ * // Cleanup
+ * unsub1();
+ * unsub2();
+ * ```
+ * @experimental
+ */
+declare class SubscriptionManager {
+  #private;
+  /**
+   * Subscribe to every state change emitted by the event source.
+   * @returns Unsubscribe function.
+   */
+  onStateChange(callback: StateChangeCallback): () => void;
+  /**
+   * Subscribe to a specific event type.
+   * @param eventType The event type to listen for (matches `entry.type`).
+   * @param callback Invoked with each matching entry.
+   * @returns Unsubscribe function.
+   */
+  onEvent(eventType: string, callback: EventCallback): () => void;
+  /**
+   * Notify all state-change subscribers with the current state.
+   */
+  notifyState(state: Readonly<Record<string, unknown>>): void;
+  /**
+   * Notify event-type subscribers whose `eventType` matches.
+   */
+  notifyEvent(entry: EventLogEntry): void;
+  /**
+   * Return the total number of active subscriptions.
+   */
+  get size(): number;
+  /**
+   * Remove all subscriptions.
+   */
+  clear(): void;
+}
+/**
+ * Options for constructing an {@link EventsSync}.
+ * @experimental
+ */
+interface EventsSyncOptions {
+  /**
+   * Replay a batch of events through the derived-state machine.
+   *
+   * Called with every batch of new events fetched from the log. The
+   * consumer should feed these events into their state machine
+   * (e.g. an {@link import("@lunora/replica").EventSource | EventSource})
+   * so that the machine's state reflects the latest log position.
+   *
+   * **Must be atomic across the batch: apply every event, or none.** There is
+   * no rollback here and none is possible — the state machine is the
+   * consumer's. A call that mutates derived state and then throws partway is
+   * re-delivered WHOLE on the next poll (the watermark only advances past a
+   * batch that fully succeeded, and a replay that threw is not recorded), so a
+   * non-atomic implementation applies the events before the throw twice. A
+   * call that RETURNS is never re-delivered: {@link EventsSync} tracks the
+   * highest applied `seq` separately from the watermark, so a batch whose
+   * replay succeeded and whose mirror fan-out then failed is not replayed.
+   */
+  applyEvents: (events: ReadonlyArray<EventLogEntry>) => void;
+  /**
+   * Fetch the next batch of events whose `seq >= sinceSeq`.
+   *
+   * It does NOT have to return the whole backlog: a bounded batch is
+   * preferred and is what the DO-backed transport gives you
+   * ({@link import("@lunora/replica").EventLogDOClient.getSince |
+   * EventLogDOClient.getSince()} answers one page). {@link EventsSync} keeps
+   * calling with the advanced watermark until a call returns nothing, so the
+   * whole log is applied either way — one bounded atom at a time.
+   * In a client context this could call a Lunora action that proxies to the
+   * event log, or read from an IndexedDB cache.
+   *
+   * Return an empty array when there are no new events.
+   */
+  fetchEventsSince: (sinceSeq: number) => Promise<ReadonlyArray<EventLogEntry>>;
+  /**
+   * Produce {@link TableDiff | TableDiffs} from the current derived state.
+   *
+   * Called after every batch of events has been applied. The consumer
+   * **recomputes a full diff from the current mirror-vs-source state** and
+   * returns the diffs needed to bring the LocalMirror up to date.
+   *
+   * **MUST be idempotent** — it must NOT advance a one-shot cursor as a side
+   * effect. A batch that fails partway (a `mirror.applyDiff` throws) is
+   * retried on the next poll from the same watermark; if this call consumed a
+   * cursor on the first attempt it would return `[]` on the retry and the
+   * un-mirrored diffs would be lost forever. Recompute-from-current-state has
+   * no such hazard: calling it again with no new events returns the same
+   * diffs, and calling it after a partial mirror write returns exactly the
+   * diffs still missing from the mirror.
+   *
+   * Return an empty array when there are no changes to push to the mirror.
+   */
+  getTableDiffs: () => TableDiff[];
+  /**
+   * The local SQLite mirror to apply diffs to.
+   */
+  mirror: LocalMirror;
+  /**
+   * Called when an error occurs during a poll cycle.
+   *
+   * Defaults to `console.error`. Set to a no-op to suppress error logging.
+   */
+  onError?: (error: unknown) => void;
+  /**
+   * How often to poll for new events (in milliseconds).
+   * @default 5000
+   */
+  pollInterval?: number;
+}
+/**
+ * Periodically polls an event log, replays events through a state machine,
+ * converts the resulting state into {@link TableDiff | TableDiffs}, and
+ * applies them to a {@link LocalMirror}.
+ *
+ * The class is **transport-agnostic** — it accepts a generic
+ * `fetchEventsSince` function rather than coupling to a specific source
+ * (EventLogDO, WebSocket push, IndexedDB, etc.).
+ *
+ * ## Lifecycle
+ *
+ * 1. Call `start()` to begin periodic polling.
+ * 2. Call `sync()` to perform an immediate one-shot sync.
+ * 3. Call `stop()` to halt polling.
+ *
+ * The current watermark is exposed via `watermark` and advances
+ * monotonically as events are applied.
+ * @experimental
+ */
+declare class EventsSync {
+  #private;
+  constructor(options: EventsSyncOptions);
+  /**
+   * The current watermark — the next `seq` the sync will fetch from.
+   *
+   * Starts at `0` (fetch everything). Advances to `max(seq) + 1` after
+   * each successful poll cycle.
+   */
+  get watermark(): number;
+  /**
+   * Start polling for new events on the configured interval.
+   *
+   * Does nothing if polling is already active.
+   * Does **not** perform an initial sync — call {@link sync} once if you
+   * need to catch up immediately.
+   */
+  start(): void;
+  /**
+   * Stop polling for new events.
+   *
+   * Safe to call when not started.
+   */
+  stop(): void;
+  /**
+   * Perform a one-shot sync: fetch events since the current watermark,
+   * apply them through the state machine, and push diffs to the mirror.
+   * @returns The number of events that were fetched and applied.
+   */
+  sync(): Promise<number>;
+}
+export { type AppendEventInput, type AppendOptions, type EventCallback, EventEmitter, type EventFactory, EventLog, EventLogDO, EventLogDOClient, type EventLogDOClientOptions, type EventLogEntry, type EventNamespace, type EventReducer, EventSource, type EventSourceEvents, type EventSourceOptions, type EventsContextOutput, type EventsDefinition, type EventsFacade, EventsSync, type EventsSyncOptions, InMemorySnapshotStore, type InputEvent, LocalMirror, type Materializer, type MaterializerDef, type MaterializerReducer, MaterializerRuntime, type MaterializerRuntimeOptions, type Seq, type SnapshotStore, type SqliteAdapter, type StateChangeCallback, type SubscriptionClient, SubscriptionManager, type TableDiff, UNHANDLED, type UnknownEventHandling, applyDiff, applyDiffToDatabase as applyDiffToDb, applyDiffToSnapshot, applyDiffs, applyDiffsToDatabase as applyDiffsToDb, defineEvents, defineMaterializer, eventsContext, subscribeToMirror };