@lunora/db 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/packem_shared/define-collections.d-1z8QtQW8.d.mts

@@ -0,0 +1,166 @@
+import { FunctionReference, SubscriptionError, LunoraClient } from '@lunora/client';
+import { Transaction, Collection } from '@tanstack/db';
+import { OfflineExecutor, StorageDiagnostic } from '@tanstack/offline-transactions';
+import { R as Row } from "./collection-options.d-DgAuvqvn.mjs";
+/** Element type of an array (the row type a `list` query returns). */
+type Element<T> = T extends ReadonlyArray<infer E> ? E : never;
+/** `true` for the `any` type, `false` otherwise. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+* The row type a `list` query syncs. For `TList = any` (the heterogeneous-map
+* constraint) it resolves to the permissive {@link Row}, not `never` — otherwise
+* the constraint would force every `optimistic` to return `never`. For a concrete
+* `FunctionReference` it's the element type of the query's array return.
+*/
+type RowOfList<TList> = IsAny<TList> extends true ? Row : TList extends FunctionReference<infer _K, infer _A, infer R> ? Element<R> & Row : never;
+/** Maps a write through the durable outbox: optimistic insert + a retried mutation. */
+interface InsertBinding<TRow extends Row, TInput> {
+  /** The Lunora mutation that persists the row. */
+  mutation: FunctionReference;
+  /** Build the optimistic row to insert from the action input + the generated client id. */
+  optimistic: (input: TInput, id: string) => TRow;
+  /** Build the mutation args from the persisted optimistic row (forward `_id` as the `clientId`). */
+  toArgs: (row: TRow) => Record<string, unknown>;
+}
+/** Declarative binding of a Lunora table to a live collection (+ optional write action). */
+interface CollectionDef<TList extends FunctionReference, TInput = never> {
+  /** Row key extractor — defaults to `row._id`. */
+  getKey?: (row: RowOfList<TList>) => string;
+  /** Optional write binding — present iff this collection is written through the outbox. */
+  insert?: InsertBinding<RowOfList<TList>, TInput>;
+  /** The Lunora query that lists the rows (the sync source). */
+  list: TList;
+  /**
+  * When this collection starts syncing — `"lazy"` (default) on the first
+  * `useLiveQuery` subscriber, or `"eager"` at creation, for small "instant"
+  * reference data you want warm at boot. Pairs with `scopeBy` for partial
+  * (per-scope) loading — together they give the full lazy/partial/eager
+  * (Linear `lazy`/`partial`/`instant`) load taxonomy declaratively. No effect
+  * on a `scopeBy` collection (nothing to sync until scoped).
+  */
+  load?: "eager" | "lazy";
+  /**
+  * Notified when the underlying `list` subscription errors (e.g. the server
+  * rejects it). Without this the error would be swallowed and the collection
+  * could hang in `loading`; the binding always moves the collection out of
+  * `loading` on error, and forwards the error here if supplied.
+  */
+  onError?: (error: SubscriptionError) => void;
+  /** A field that scopes the list (e.g. a shard key); makes the collection re-pointable via `scope`. */
+  scopeBy?: string;
+  /**
+  * Routes the `list` subscription (and the confirmed-mutation watermark its
+  * frames advance the checkpoint gate from) to a specific shard's DO — so a
+  * sharded collection's overlay gate compares against that shard's mutator
+  * sequence line, not the default ("") watermark bucket.
+  */
+  shardKey?: string;
+}
+type AnyDef = CollectionDef<any, any>;
+/**
+* The public row type a collection exposes — the element type of its `list`
+* query's return, with no `& Row`: a `Collection&lt;T>` is invariant in `T`, so the
+* exposed type must be exactly the document type, not a subtype.
+*/
+type RowOf<C extends AnyDef> = C["list"] extends FunctionReference<infer _K, infer _A, infer R> ? Element<R> : never;
+/** The action input type, inferred structurally from the def's optimistic insert. */
+type InputOf<C> = C extends {
+  insert: {
+    optimistic: (input: infer I, id: string) => unknown;
+  };
+} ? I : never;
+/** A queued write that was permanently dropped, passed to {@link DefineCollectionsOptions.onWriteRejected}. */
+interface WriteRejectedEvent {
+  /**
+  * The machine-readable reason — the server's error `code` (e.g. `CONFLICT`,
+  * `FORBIDDEN`), or `UNKNOWN_MUTATION_FN` when the write referenced a collection
+  * that no longer exists (removed in a deploy). Mirrors the client's
+  * `MutationSettledEvent.code` so a consumer can branch on the verdict.
+  */
+  code?: string;
+  /** The collection/table name the write targeted. */
+  collection: string;
+  /** The error that dropped the write (message carried by the underlying `NonRetriableError`). */
+  error: Error;
+  /**
+  * The optimistic row being rolled back (the rollback follows the callback).
+  * Absent only if the dropped transaction carried no recoverable row (e.g. some
+  * `UNKNOWN_MUTATION_FN` cases).
+  */
+  row?: Row;
+}
+/** Options for {@link defineCollections}. */
+interface DefineCollectionsOptions {
+  /**
+  * Invoked when a leadership change occurs across tabs (only the leader tab
+  * drains the durable outbox). Informational — useful for diagnostics; the
+  * library handles the election itself.
+  */
+  onLeadershipChange?: (isLeader: boolean) => void;
+  /**
+  * Invoked when the durable outbox's storage layer fails — IndexedDB
+  * unavailable (private mode), blocked, or quota exceeded. The standalone
+  * client surfaces this via `offlineQueue.onPersistenceError`; this is the
+  * collection-layer counterpart. A storage failure means a write is NOT durable
+  * and won't survive a reload, so surface it (e.g. "your change may not be
+  * saved if you close this tab").
+  */
+  onStorageFailure?: (diagnostic: StorageDiagnostic) => void;
+  /**
+  * Invoked as a queued write is permanently dropped: a coded application error
+  * from the server (validation, RLS denial, conflict, surfaced as a
+  * `NonRetriableError`), OR a write whose target collection no longer exists —
+  * removed/renamed in a deploy (`code: "UNKNOWN_MUTATION_FN"`). This is the
+  * aggregate, fire-and-forget-safe channel: unlike awaiting the per-action
+  * `transaction` returned by `actions[name](...)`, it fires even when the caller
+  * never retained that handle, so a UI can surface "couldn't save" instead of a
+  * silently vanishing row. Transient failures (offline, 5xx) are retried by the
+  * outbox, not reported here.
+  *
+  * Timing: the callback runs at the point of rejection; the executor's
+  * optimistic-row rollback follows immediately after. The event's `row` is the
+  * (about-to-be-removed) optimistic row, so don't depend on the collection
+  * already reflecting the removal from inside the handler — use `row`/`error`
+  * directly (e.g. for a toast).
+  */
+  onWriteRejected?: (event: WriteRejectedEvent) => void;
+}
+/** The wired data layer `defineCollections` returns. */
+interface LunoraDb<D extends Record<string, AnyDef>> {
+  /** Optimistic, durable, retried write actions — present for `insert` collections. */
+  actions: { [K in keyof D]: D[K] extends {
+    insert: object;
+  } ? (input: InputOf<D[K]>) => {
+    id: string;
+    transaction: Transaction;
+  } : never };
+  /** The live, synced collections — feed these to `useLiveQuery`. */
+  collections: { [K in keyof D]: Collection<RowOf<D[K]>, string> };
+  /** The shared offline executor (the outbox). */
+  executor: OfflineExecutor;
+  /**
+  * Number of writes still pending in the durable outbox — the depth for a
+  * "N changes waiting to sync" indicator. A convenience over reaching through
+  * `executor.getPendingCount()`. **Pull-only** (the underlying TanStack
+  * executor exposes no change subscription): read it after a `db.actions.*`
+  * call and on connection-status changes, or poll. The standalone
+  * `LunoraClient` exposes the reactive `onPendingChange` for its built-in queue.
+  */
+  pendingCount: () => number;
+  /** Re-point a `scopeBy` collection's subscription (omit `args` to detach) — present for scoped collections. */
+  scope: { [K in keyof D]: D[K] extends {
+    scopeBy: string;
+  } ? (args?: Record<string, unknown>) => void : never };
+}
+/**
+* Wire a set of Lunora tables into a TanStack DB data layer in one declaration:
+* each entry becomes a live, auto-indexed collection synced from its `list` query,
+* and `insert` entries get an optimistic write action backed by the
+* offline-transactions outbox (durable, retried, client-id-keyed). Scoped
+* (`scopeBy`) collections are re-pointable for sharded queries.
+*
+* This is the hand-written form; `@lunora/codegen` can emit a fully-typed call to
+* it from `schema.ts`, so an app writes nothing.
+*/
+declare const defineCollections: <D extends Record<string, AnyDef>>(client: LunoraClient, defs: D, options?: DefineCollectionsOptions) => LunoraDb<D>;
+export { CollectionDef as C, DefineCollectionsOptions as D, InsertBinding as I, LunoraDb as L, WriteRejectedEvent as W, defineCollections as d };

package/dist/packem_shared/define-collections.d-DPgIHAtd.d.ts

@@ -0,0 +1,166 @@
+import { FunctionReference, SubscriptionError, LunoraClient } from '@lunora/client';
+import { Transaction, Collection } from '@tanstack/db';
+import { OfflineExecutor, StorageDiagnostic } from '@tanstack/offline-transactions';
+import { R as Row } from "./collection-options.d-DgAuvqvn.js";
+/** Element type of an array (the row type a `list` query returns). */
+type Element<T> = T extends ReadonlyArray<infer E> ? E : never;
+/** `true` for the `any` type, `false` otherwise. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+* The row type a `list` query syncs. For `TList = any` (the heterogeneous-map
+* constraint) it resolves to the permissive {@link Row}, not `never` — otherwise
+* the constraint would force every `optimistic` to return `never`. For a concrete
+* `FunctionReference` it's the element type of the query's array return.
+*/
+type RowOfList<TList> = IsAny<TList> extends true ? Row : TList extends FunctionReference<infer _K, infer _A, infer R> ? Element<R> & Row : never;
+/** Maps a write through the durable outbox: optimistic insert + a retried mutation. */
+interface InsertBinding<TRow extends Row, TInput> {
+  /** The Lunora mutation that persists the row. */
+  mutation: FunctionReference;
+  /** Build the optimistic row to insert from the action input + the generated client id. */
+  optimistic: (input: TInput, id: string) => TRow;
+  /** Build the mutation args from the persisted optimistic row (forward `_id` as the `clientId`). */
+  toArgs: (row: TRow) => Record<string, unknown>;
+}
+/** Declarative binding of a Lunora table to a live collection (+ optional write action). */
+interface CollectionDef<TList extends FunctionReference, TInput = never> {
+  /** Row key extractor — defaults to `row._id`. */
+  getKey?: (row: RowOfList<TList>) => string;
+  /** Optional write binding — present iff this collection is written through the outbox. */
+  insert?: InsertBinding<RowOfList<TList>, TInput>;
+  /** The Lunora query that lists the rows (the sync source). */
+  list: TList;
+  /**
+  * When this collection starts syncing — `"lazy"` (default) on the first
+  * `useLiveQuery` subscriber, or `"eager"` at creation, for small "instant"
+  * reference data you want warm at boot. Pairs with `scopeBy` for partial
+  * (per-scope) loading — together they give the full lazy/partial/eager
+  * (Linear `lazy`/`partial`/`instant`) load taxonomy declaratively. No effect
+  * on a `scopeBy` collection (nothing to sync until scoped).
+  */
+  load?: "eager" | "lazy";
+  /**
+  * Notified when the underlying `list` subscription errors (e.g. the server
+  * rejects it). Without this the error would be swallowed and the collection
+  * could hang in `loading`; the binding always moves the collection out of
+  * `loading` on error, and forwards the error here if supplied.
+  */
+  onError?: (error: SubscriptionError) => void;
+  /** A field that scopes the list (e.g. a shard key); makes the collection re-pointable via `scope`. */
+  scopeBy?: string;
+  /**
+  * Routes the `list` subscription (and the confirmed-mutation watermark its
+  * frames advance the checkpoint gate from) to a specific shard's DO — so a
+  * sharded collection's overlay gate compares against that shard's mutator
+  * sequence line, not the default ("") watermark bucket.
+  */
+  shardKey?: string;
+}
+type AnyDef = CollectionDef<any, any>;
+/**
+* The public row type a collection exposes — the element type of its `list`
+* query's return, with no `& Row`: a `Collection&lt;T>` is invariant in `T`, so the
+* exposed type must be exactly the document type, not a subtype.
+*/
+type RowOf<C extends AnyDef> = C["list"] extends FunctionReference<infer _K, infer _A, infer R> ? Element<R> : never;
+/** The action input type, inferred structurally from the def's optimistic insert. */
+type InputOf<C> = C extends {
+  insert: {
+    optimistic: (input: infer I, id: string) => unknown;
+  };
+} ? I : never;
+/** A queued write that was permanently dropped, passed to {@link DefineCollectionsOptions.onWriteRejected}. */
+interface WriteRejectedEvent {
+  /**
+  * The machine-readable reason — the server's error `code` (e.g. `CONFLICT`,
+  * `FORBIDDEN`), or `UNKNOWN_MUTATION_FN` when the write referenced a collection
+  * that no longer exists (removed in a deploy). Mirrors the client's
+  * `MutationSettledEvent.code` so a consumer can branch on the verdict.
+  */
+  code?: string;
+  /** The collection/table name the write targeted. */
+  collection: string;
+  /** The error that dropped the write (message carried by the underlying `NonRetriableError`). */
+  error: Error;
+  /**
+  * The optimistic row being rolled back (the rollback follows the callback).
+  * Absent only if the dropped transaction carried no recoverable row (e.g. some
+  * `UNKNOWN_MUTATION_FN` cases).
+  */
+  row?: Row;
+}
+/** Options for {@link defineCollections}. */
+interface DefineCollectionsOptions {
+  /**
+  * Invoked when a leadership change occurs across tabs (only the leader tab
+  * drains the durable outbox). Informational — useful for diagnostics; the
+  * library handles the election itself.
+  */
+  onLeadershipChange?: (isLeader: boolean) => void;
+  /**
+  * Invoked when the durable outbox's storage layer fails — IndexedDB
+  * unavailable (private mode), blocked, or quota exceeded. The standalone
+  * client surfaces this via `offlineQueue.onPersistenceError`; this is the
+  * collection-layer counterpart. A storage failure means a write is NOT durable
+  * and won't survive a reload, so surface it (e.g. "your change may not be
+  * saved if you close this tab").
+  */
+  onStorageFailure?: (diagnostic: StorageDiagnostic) => void;
+  /**
+  * Invoked as a queued write is permanently dropped: a coded application error
+  * from the server (validation, RLS denial, conflict, surfaced as a
+  * `NonRetriableError`), OR a write whose target collection no longer exists —
+  * removed/renamed in a deploy (`code: "UNKNOWN_MUTATION_FN"`). This is the
+  * aggregate, fire-and-forget-safe channel: unlike awaiting the per-action
+  * `transaction` returned by `actions[name](...)`, it fires even when the caller
+  * never retained that handle, so a UI can surface "couldn't save" instead of a
+  * silently vanishing row. Transient failures (offline, 5xx) are retried by the
+  * outbox, not reported here.
+  *
+  * Timing: the callback runs at the point of rejection; the executor's
+  * optimistic-row rollback follows immediately after. The event's `row` is the
+  * (about-to-be-removed) optimistic row, so don't depend on the collection
+  * already reflecting the removal from inside the handler — use `row`/`error`
+  * directly (e.g. for a toast).
+  */
+  onWriteRejected?: (event: WriteRejectedEvent) => void;
+}
+/** The wired data layer `defineCollections` returns. */
+interface LunoraDb<D extends Record<string, AnyDef>> {
+  /** Optimistic, durable, retried write actions — present for `insert` collections. */
+  actions: { [K in keyof D]: D[K] extends {
+    insert: object;
+  } ? (input: InputOf<D[K]>) => {
+    id: string;
+    transaction: Transaction;
+  } : never };
+  /** The live, synced collections — feed these to `useLiveQuery`. */
+  collections: { [K in keyof D]: Collection<RowOf<D[K]>, string> };
+  /** The shared offline executor (the outbox). */
+  executor: OfflineExecutor;
+  /**
+  * Number of writes still pending in the durable outbox — the depth for a
+  * "N changes waiting to sync" indicator. A convenience over reaching through
+  * `executor.getPendingCount()`. **Pull-only** (the underlying TanStack
+  * executor exposes no change subscription): read it after a `db.actions.*`
+  * call and on connection-status changes, or poll. The standalone
+  * `LunoraClient` exposes the reactive `onPendingChange` for its built-in queue.
+  */
+  pendingCount: () => number;
+  /** Re-point a `scopeBy` collection's subscription (omit `args` to detach) — present for scoped collections. */
+  scope: { [K in keyof D]: D[K] extends {
+    scopeBy: string;
+  } ? (args?: Record<string, unknown>) => void : never };
+}
+/**
+* Wire a set of Lunora tables into a TanStack DB data layer in one declaration:
+* each entry becomes a live, auto-indexed collection synced from its `list` query,
+* and `insert` entries get an optimistic write action backed by the
+* offline-transactions outbox (durable, retried, client-id-keyed). Scoped
+* (`scopeBy`) collections are re-pointable for sharded queries.
+*
+* This is the hand-written form; `@lunora/codegen` can emit a fully-typed call to
+* it from `schema.ts`, so an app writes nothing.
+*/
+declare const defineCollections: <D extends Record<string, AnyDef>>(client: LunoraClient, defs: D, options?: DefineCollectionsOptions) => LunoraDb<D>;
+export { CollectionDef as C, DefineCollectionsOptions as D, InsertBinding as I, LunoraDb as L, WriteRejectedEvent as W, defineCollections as d };

package/dist/packem_shared/define-mutators.d-10NiOBqm.d.ts

@@ -0,0 +1,80 @@
+import { LunoraClient } from '@lunora/client';
+import { Collection, Transaction } from '@tanstack/db';
+import { C as CheckpointRegistry, R as Row } from "./collection-options.d-DgAuvqvn.js";
+/** The local store a client mutator's optimistic body writes against. */
+interface ClientMutatorContext {
+  /** The wired collections, keyed by name — apply optimistic inserts/updates/deletes here. */
+  collections: Record<string, Collection<Row, string>>;
+}
+/** A client-side custom mutator: an optimistic body plus the path of its authoritative server impl. */
+interface ClientMutatorDef<TArgs> {
+  /** Brand so codegen / `bindMutators` can recognize a mutator definition. */
+  __lunoraClientMutator: true;
+  /** The optimistic update applied to the local collections before the server confirms. */
+  apply: (context: ClientMutatorContext, args: TArgs) => void;
+  /** The Lunora function path of the server-authoritative mutator (`defineMutator` on the server). */
+  serverRef: string;
+}
+/**
+* Declare a client-side custom mutator. `apply` runs optimistically against the
+* local TanStack collections; `serverRef` names the authoritative server mutator
+* the write is pushed to over the watermark protocol. The server impl is the
+* linearization point — this body is a prediction the server can override.
+*/
+declare const defineMutator: <TArgs = Record<string, unknown>>(definition: {
+  apply: (context: ClientMutatorContext, args: TArgs) => void;
+  serverRef: string;
+}) => ClientMutatorDef<TArgs>;
+type AnyMutatorMap = Record<string, ClientMutatorDef<any>>;
+/** Args type of a mutator definition. */
+type ArgsOf<M> = M extends ClientMutatorDef<infer A> ? A : never;
+/** Inputs `bindMutators` needs to run a mutator: the local store + how the overlay drops. */
+interface BindMutatorsContext {
+  /**
+  * Resolves the optimistic-overlay drop against confirmed server watermarks.
+  * When supplied, a mutation's overlay is held until the sync stream echoes
+  * `lastMutationId >= clientSeq` (via {@link CheckpointRegistry.resolve}) — no
+  * flicker. When omitted, the overlay drops as soon as the server accepts the
+  * write (the by-value sync diff then converges the synced row in place).
+  */
+  checkpoints?: CheckpointRegistry;
+  /** The wired collections the optimistic bodies write against. */
+  collections: Record<string, Collection<Row, string>>;
+  /** Optional shard key the mutator's server push is routed to. */
+  shardKey?: string;
+}
+/** Calling a bound mutator runs the optimistic body + pushes the server write; returns the TanStack transaction. */
+type BoundMutators<M extends AnyMutatorMap> = { [K in keyof M]: (args: ArgsOf<M[K]>) => Transaction };
+/**
+* Bind a set of client mutators to a client + local store. Each returned handle,
+* when called, opens a TanStack optimistic transaction: the mutator's `apply`
+* body writes the predicted rows into the collections, and the transaction's
+* `mutationFn` pushes the authoritative write through
+* {@link LunoraClient.callMutator} under a monotonic per-client `clientSeq`.
+*
+* Rebase-on-poke is free — TanStack DB re-derives every pending optimistic overlay
+* over the latest synced base on each sync tick. The overlay is dropped when the
+* server confirms the write (and, if `checkpoints` is supplied, once it echoes the
+* matching watermark so the synced row has landed).
+*
+* The `clientSeq` generator is seeded from the server's echoed watermark
+* ({@link LunoraClient.confirmedMutationWatermark}) on every issue, so a reload —
+* which resets this in-memory counter while the server keeps a durable per-client
+* watermark — never reissues a sequence the DO has already applied. As a backstop
+* for the very first push of a fresh session (before any ack has taught the client
+* the watermark), a push the DO swallows as a replay (`applied === false`) is
+* reissued above the now-known watermark instead of being mistaken for a confirmed
+* write — closing the silent-drop window without risking a double-apply (a fresh
+* session's first stale push provably cannot be an honest replay).
+*
+* Pushes are **serialized per binding** (a FIFO chain): the DO rejects any push
+* with `clientSeq > watermark + 1` as `OUT_OF_ORDER` and drops the write, so two
+* mutators fired concurrently must not race the network into a gap. Each push
+* waits for the previous one's ack and assigns its `clientSeq` *inside* the
+* critical section — from the live watermark — so the sequence is always exactly
+* `watermark + 1`. Because a failed mutation never advances the server watermark,
+* a permanently-rejected predecessor can't wedge the chain: the next push simply
+* reclaims the same `watermark + 1` instead of leaving a hole the DO waits on.
+*/
+declare const bindMutators: <M extends AnyMutatorMap>(client: LunoraClient, context: BindMutatorsContext, mutators: M) => BoundMutators<M>;
+export { BindMutatorsContext as B, ClientMutatorContext as C, BoundMutators as a, ClientMutatorDef as b, bindMutators as c, defineMutator as d };

package/dist/packem_shared/define-mutators.d-Cq_qr5Z1.d.mts

@@ -0,0 +1,80 @@
+import { LunoraClient } from '@lunora/client';
+import { Collection, Transaction } from '@tanstack/db';
+import { C as CheckpointRegistry, R as Row } from "./collection-options.d-DgAuvqvn.mjs";
+/** The local store a client mutator's optimistic body writes against. */
+interface ClientMutatorContext {
+  /** The wired collections, keyed by name — apply optimistic inserts/updates/deletes here. */
+  collections: Record<string, Collection<Row, string>>;
+}
+/** A client-side custom mutator: an optimistic body plus the path of its authoritative server impl. */
+interface ClientMutatorDef<TArgs> {
+  /** Brand so codegen / `bindMutators` can recognize a mutator definition. */
+  __lunoraClientMutator: true;
+  /** The optimistic update applied to the local collections before the server confirms. */
+  apply: (context: ClientMutatorContext, args: TArgs) => void;
+  /** The Lunora function path of the server-authoritative mutator (`defineMutator` on the server). */
+  serverRef: string;
+}
+/**
+* Declare a client-side custom mutator. `apply` runs optimistically against the
+* local TanStack collections; `serverRef` names the authoritative server mutator
+* the write is pushed to over the watermark protocol. The server impl is the
+* linearization point — this body is a prediction the server can override.
+*/
+declare const defineMutator: <TArgs = Record<string, unknown>>(definition: {
+  apply: (context: ClientMutatorContext, args: TArgs) => void;
+  serverRef: string;
+}) => ClientMutatorDef<TArgs>;
+type AnyMutatorMap = Record<string, ClientMutatorDef<any>>;
+/** Args type of a mutator definition. */
+type ArgsOf<M> = M extends ClientMutatorDef<infer A> ? A : never;
+/** Inputs `bindMutators` needs to run a mutator: the local store + how the overlay drops. */
+interface BindMutatorsContext {
+  /**
+  * Resolves the optimistic-overlay drop against confirmed server watermarks.
+  * When supplied, a mutation's overlay is held until the sync stream echoes
+  * `lastMutationId >= clientSeq` (via {@link CheckpointRegistry.resolve}) — no
+  * flicker. When omitted, the overlay drops as soon as the server accepts the
+  * write (the by-value sync diff then converges the synced row in place).
+  */
+  checkpoints?: CheckpointRegistry;
+  /** The wired collections the optimistic bodies write against. */
+  collections: Record<string, Collection<Row, string>>;
+  /** Optional shard key the mutator's server push is routed to. */
+  shardKey?: string;
+}
+/** Calling a bound mutator runs the optimistic body + pushes the server write; returns the TanStack transaction. */
+type BoundMutators<M extends AnyMutatorMap> = { [K in keyof M]: (args: ArgsOf<M[K]>) => Transaction };
+/**
+* Bind a set of client mutators to a client + local store. Each returned handle,
+* when called, opens a TanStack optimistic transaction: the mutator's `apply`
+* body writes the predicted rows into the collections, and the transaction's
+* `mutationFn` pushes the authoritative write through
+* {@link LunoraClient.callMutator} under a monotonic per-client `clientSeq`.
+*
+* Rebase-on-poke is free — TanStack DB re-derives every pending optimistic overlay
+* over the latest synced base on each sync tick. The overlay is dropped when the
+* server confirms the write (and, if `checkpoints` is supplied, once it echoes the
+* matching watermark so the synced row has landed).
+*
+* The `clientSeq` generator is seeded from the server's echoed watermark
+* ({@link LunoraClient.confirmedMutationWatermark}) on every issue, so a reload —
+* which resets this in-memory counter while the server keeps a durable per-client
+* watermark — never reissues a sequence the DO has already applied. As a backstop
+* for the very first push of a fresh session (before any ack has taught the client
+* the watermark), a push the DO swallows as a replay (`applied === false`) is
+* reissued above the now-known watermark instead of being mistaken for a confirmed
+* write — closing the silent-drop window without risking a double-apply (a fresh
+* session's first stale push provably cannot be an honest replay).
+*
+* Pushes are **serialized per binding** (a FIFO chain): the DO rejects any push
+* with `clientSeq > watermark + 1` as `OUT_OF_ORDER` and drops the write, so two
+* mutators fired concurrently must not race the network into a gap. Each push
+* waits for the previous one's ack and assigns its `clientSeq` *inside* the
+* critical section — from the live watermark — so the sequence is always exactly
+* `watermark + 1`. Because a failed mutation never advances the server watermark,
+* a permanently-rejected predecessor can't wedge the chain: the next push simply
+* reclaims the same `watermark + 1` instead of leaving a hole the DO waits on.
+*/
+declare const bindMutators: <M extends AnyMutatorMap>(client: LunoraClient, context: BindMutatorsContext, mutators: M) => BoundMutators<M>;
+export { BindMutatorsContext as B, ClientMutatorContext as C, BoundMutators as a, ClientMutatorDef as b, bindMutators as c, defineMutator as d };

package/dist/packem_shared/defineCollections-yLxJvEsu.mjs

@@ -0,0 +1,107 @@
+import { createCollection, safeRandomUUID } from '@tanstack/db';
+import { startOfflineExecutor, NonRetriableError } from '@tanstack/offline-transactions';
+import { lunoraCollectionOptions } from './createCheckpointRegistry-Bf4JtkVH.mjs';
+import { createOptimisticOnlineDetector, runOutboxMutation, OUTBOX_MUTATION_FN_NAME } from './OUTBOX_MUTATION_FN_NAME-Cf8iP6Wa.mjs';
+
+const defineCollections = (client, defs, options = {}) => {
+  const collections = {};
+  const scope = {};
+  const mutationFns = {};
+  const entries = Object.entries(defs);
+  for (const [name, definition] of entries) {
+    const insert = definition.insert;
+    const { config, scope: scopeFunction } = lunoraCollectionOptions({
+      client,
+      getKey: definition.getKey,
+      id: name,
+      // `AnyDef` erases `list` to `any` (`TList = any`); it's a `FunctionReference` here.
+      list: definition.list,
+      ...definition.load === void 0 ? {} : { load: definition.load },
+      onError: definition.onError,
+      scopeBy: definition.scopeBy,
+      shardKey: definition.shardKey
+    });
+    collections[name] = createCollection(config);
+    if (definition.scopeBy !== void 0) {
+      scope[name] = scopeFunction;
+    }
+    if (insert) {
+      mutationFns[name] = async ({ idempotencyKey, transaction }) => {
+        for (const [mutationIndex, mutation] of transaction.mutations.entries()) {
+          const row = mutation.modified;
+          const mutationId = `${idempotencyKey}:${String(mutationIndex)}`;
+          try {
+            await runOutboxMutation(() => client.mutation(insert.mutation, insert.toArgs(row), { mutationId }));
+          } catch (error) {
+            if (error instanceof NonRetriableError && options.onWriteRejected) {
+              try {
+                options.onWriteRejected({ code: error.code, collection: name, error, row });
+              } catch {
+              }
+            }
+            throw error;
+          }
+        }
+      };
+    }
+  }
+  mutationFns[OUTBOX_MUTATION_FN_NAME] = async ({ transaction }) => {
+    const meta = transaction.metadata;
+    if (!meta) {
+      return;
+    }
+    if (meta.identity !== client.currentIdentity()) {
+      throw new NonRetriableError("outbox write dropped: identity changed since it was queued");
+    }
+    await runOutboxMutation(
+      () => client.mutation({ __lunoraRef: meta.functionPath }, meta.args, { mutationId: meta.idempotencyKey, shardKey: meta.shardKey })
+    );
+  };
+  const executor = startOfflineExecutor({
+    collections,
+    mutationFns,
+    onlineDetector: createOptimisticOnlineDetector(),
+    ...options.onLeadershipChange ? { onLeadershipChange: options.onLeadershipChange } : {},
+    ...options.onStorageFailure ? { onStorageFailure: options.onStorageFailure } : {},
+    // A persisted write whose target collection was removed/renamed in a deploy
+    // hits an unregistered mutationFn. The executor drops it as a
+    // NonRetriableError *before* our per-collection `mutationFns` catch runs, so
+    // this hook is the only place to surface it on `onWriteRejected`.
+    onUnknownMutationFn: (name, tx) => {
+      try {
+        options.onWriteRejected?.({
+          code: "UNKNOWN_MUTATION_FN",
+          collection: name,
+          error: new Error(`offline write dropped: mutation "${name}" no longer exists (removed or renamed in a deploy?)`),
+          // Best-effort recovered row: the persisted `modified` shape isn't a
+          // validated `Row`, and a batched transaction surfaces only its first
+          // mutation's row. Enough to describe the dropped write to the user.
+          row: tx.mutations[0]?.modified
+        });
+      } catch {
+      }
+    }
+  });
+  const actions = {};
+  for (const [name, definition] of entries) {
+    const insert = definition.insert;
+    const collection = collections[name];
+    if (!insert || !collection) {
+      continue;
+    }
+    const action = executor.createOfflineAction({
+      mutationFnName: name,
+      onMutate: ({ id, input }) => {
+        collection.insert(insert.optimistic(input, id));
+      }
+    });
+    actions[name] = (input) => {
+      const id = safeRandomUUID();
+      const transaction = action({ id, input });
+      return { id, transaction };
+    };
+  }
+  return { actions, collections, executor, pendingCount: () => executor.getPendingCount(), scope };
+};
+
+export { defineCollections };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/db",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.21",
   "description": "TanStack DB binding: typed, live-synced collections and a durable offline outbox over the Lunora client",
   "keywords": [
     "cloudflare",
@@ -25,7 +25,7 @@
     "directory": "packages/db"
   },
   "files": [
-    "dist",
+    "./dist",
     "__assets__",
     "README.md",
     "LICENSE.md"
@@ -40,13 +40,22 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs"
     },
+    "./collections": {
+      "types": "./dist/collections/index.d.ts",
+      "import": "./dist/collections/index.mjs"
+    },
+    "./mutators": {
+      "types": "./dist/mutators/index.d.ts",
+      "import": "./dist/mutators/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.2"
+    "@lunora/client": "1.0.0-alpha.21",
+    "@lunora/errors": "1.0.0-alpha.4"
   },
   "peerDependencies": {
     "@tanstack/db": "^0.6.0",