@lunora/db 1.0.0-alpha.4 → 1.0.0-alpha.5

package/README.md

@@ -85,6 +85,18 @@ export const createCollections = (client: LunoraClient) =>
 
 > `vis generate lunora-collections` scaffolds this from your `schema.ts` + functions.
 
+### Local-first sync engine
+
+Beyond whole-table collections, the `@lunora/db/collections` and
+`@lunora/db/mutators` subpaths expose the local-first sync engine:
+`lunoraCollectionOptions({ shape })` syncs a **partial replication shape** (only
+the rows a client needs, scoped by a server-resolved predicate) over the poke
+diff protocol, and `defineMutator` + `bindMutators` run **optimistic custom
+mutators** (a local body first, a server-authoritative impl second, rebased on
+every sync tick). The framework adapters add a `useMutator` / `createMutator` /
+`mutator` hook over a bound handle. See the
+**[local-first guide](https://lunora.sh/docs/concepts/local-first)**.
+
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/addons/db)**.
 
 ## Related

package/dist/collections/index.d.mts

@@ -0,0 +1,5 @@
+export { type C as CheckpointRegistry, type L as LunoraCollectionConfig, type a as LunoraCollectionOptions, c as createCheckpointRegistry, l as lunoraCollectionOptions } from "../packem_shared/collection-options.d-B3YaP49K.mjs";
+export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "../packem_shared/define-collections.d-L5DVcLnj.mjs";
+import '@lunora/client';
+import '@tanstack/db';
+import '@tanstack/offline-transactions';

package/dist/collections/index.d.ts

@@ -0,0 +1,5 @@
+export { type C as CheckpointRegistry, type L as LunoraCollectionConfig, type a as LunoraCollectionOptions, c as createCheckpointRegistry, l as lunoraCollectionOptions } from "../packem_shared/collection-options.d-B3YaP49K.js";
+export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "../packem_shared/define-collections.d-DKc3vPUv.js";
+import '@lunora/client';
+import '@tanstack/db';
+import '@tanstack/offline-transactions';

package/dist/collections/index.mjs

@@ -0,0 +1,2 @@
+export { createCheckpointRegistry, lunoraCollectionOptions } from '../packem_shared/createCheckpointRegistry-CR_q270X.mjs';
+export { defineCollections } from '../packem_shared/defineCollections-it3wN-49.mjs';

package/dist/index.d.mts

@@ -1,142 +1,8 @@
-import { FunctionReference, SubscriptionError, LunoraClient } from '@lunora/client';
-import { Transaction, Collection } from '@tanstack/db';
-import { OnlineDetector, OfflineExecutor } from '@tanstack/offline-transactions';
-/** A row carrying the Lunora document id. */
-type Row = Record<string, unknown> & {
-  _id: string;
-};
-/** The subset of a TanStack DB sync write channel that {@link makeDiffEmit} drives. */
-interface SyncWriter<T extends object> {
-  begin: () => void;
-  commit: () => void;
-  write: (message: {
-    type: "insert" | "update";
-    value: T;
-  } | {
-    key: string;
-    type: "delete";
-  }) => void;
-}
-/** Index a row list into a keyed map. */
-declare const toMap: <T extends object>(rows: ReadonlyArray<T>, getKey: (row: T) => string) => Map<string, T>;
-/**
-* Build an `emit(next)` that diffs a desired keyed snapshot into a collection's
-* sync channel — only changed rows are written, so a reconnect snapshot or a
-* scope change never churns the synced view out from under a pending optimistic
-* row. The last-synced base is tracked in `synced`.
-*
-* Change detection compares rows by `JSON.stringify`, which is key-order
-* sensitive — safe here because `synced` only ever holds server snapshots, whose
-* column order is stable across reconnects (same query projection). A sync source
-* with unstable key ordering would need a structural compare instead.
-*/
-declare const makeDiffEmit: <T extends object>(synced: Map<string, T>, writer: SyncWriter<T>) => (next: Map<string, T>) => void;
-/**
-* Run a Lunora mutation under the outbox's retry policy.
-*
-* The retryable/permanent split keys on whether the failure carries a server
-* application error `code` (set by `@lunora/client`'s rpc when the server returns
-* a `{ error: { code, … } }` envelope — validation, conflict, etc.). A coded
-* error is a definite verdict: surface it as a `NonRetriableError` so the executor
-* stops and TanStack DB rolls the optimistic insert back. Everything without a
-* code is transient — a `fetch` network failure (`TypeError`) or an HTTP/infra
-* blip the rpc surfaces as a code-less `Error` (a 5xx gateway page, a non-JSON
-* body) — so it's rethrown as-is and the durable outbox replays it. Keying on
-* `error instanceof TypeError` alone would wrongly drop the latter.
-*/
-declare const runOutboxMutation: (mutate: () => Promise<unknown>) => Promise<void>;
-/**
-* An "always attempt" online detector. We deliberately don't trust
-* `navigator.onLine`: some environments (and Playwright's `setOffline` under
-* Firefox) leave it stuck, which would freeze the outbox. Instead the executor
-* always tries the send and {@link runOutboxMutation}'s transient-error retry
-* handles real offline; the periodic tick nudges the executor to drain the outbox
-* so a queued write replays promptly once connectivity returns.
-*
-* `isOnline` is therefore intentionally always `true` — it gates the executor's
-* attempts, not a UI signal. A consumer that wants to show real connectivity
-* should read `navigator.onLine` itself, separately from this detector.
-*/
-declare const createOptimisticOnlineDetector: () => OnlineDetector;
-/** 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;
-  /**
-  * 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;
-}
-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;
-/** 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;
-  /** 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) => LunoraDb<D>;
+export { type C as CheckpointRegistry, type E as ExecutorOutboxSinkOptions, type L as LunoraCollectionConfig, type a as LunoraCollectionOptions, O as OUTBOX_MUTATION_FN_NAME, type b as OutboxExecutor, type d as OutboxMutationMetadata, type R as Row, type S as SyncWriter, c as createCheckpointRegistry, e as createExecutorOutboxSink, f as createOptimisticOnlineDetector, l as lunoraCollectionOptions, m as makeDiffEmit, r as runOutboxMutation, t as toMap } from "./packem_shared/collection-options.d-B3YaP49K.mjs";
+export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "./packem_shared/define-collections.d-L5DVcLnj.mjs";
+export { type B as BindMutatorsContext, type a as BoundMutators, type C as ClientMutatorContext, type b as ClientMutatorDef, c as bindMutators, d as defineMutator } from "./packem_shared/define-mutators.d-Bqd-o1Zp.mjs";
+import '@lunora/client';
+import '@tanstack/db';
+import '@tanstack/offline-transactions';
 declare const VERSION = "0.0.0";
-export { type CollectionDef, type InsertBinding, type LunoraDb, type Row, type SyncWriter, VERSION, createOptimisticOnlineDetector, defineCollections, makeDiffEmit, runOutboxMutation, toMap };
+export { VERSION };

package/dist/index.d.ts

@@ -1,142 +1,8 @@
-import { FunctionReference, SubscriptionError, LunoraClient } from '@lunora/client';
-import { Transaction, Collection } from '@tanstack/db';
-import { OnlineDetector, OfflineExecutor } from '@tanstack/offline-transactions';
-/** A row carrying the Lunora document id. */
-type Row = Record<string, unknown> & {
-  _id: string;
-};
-/** The subset of a TanStack DB sync write channel that {@link makeDiffEmit} drives. */
-interface SyncWriter<T extends object> {
-  begin: () => void;
-  commit: () => void;
-  write: (message: {
-    type: "insert" | "update";
-    value: T;
-  } | {
-    key: string;
-    type: "delete";
-  }) => void;
-}
-/** Index a row list into a keyed map. */
-declare const toMap: <T extends object>(rows: ReadonlyArray<T>, getKey: (row: T) => string) => Map<string, T>;
-/**
-* Build an `emit(next)` that diffs a desired keyed snapshot into a collection's
-* sync channel — only changed rows are written, so a reconnect snapshot or a
-* scope change never churns the synced view out from under a pending optimistic
-* row. The last-synced base is tracked in `synced`.
-*
-* Change detection compares rows by `JSON.stringify`, which is key-order
-* sensitive — safe here because `synced` only ever holds server snapshots, whose
-* column order is stable across reconnects (same query projection). A sync source
-* with unstable key ordering would need a structural compare instead.
-*/
-declare const makeDiffEmit: <T extends object>(synced: Map<string, T>, writer: SyncWriter<T>) => (next: Map<string, T>) => void;
-/**
-* Run a Lunora mutation under the outbox's retry policy.
-*
-* The retryable/permanent split keys on whether the failure carries a server
-* application error `code` (set by `@lunora/client`'s rpc when the server returns
-* a `{ error: { code, … } }` envelope — validation, conflict, etc.). A coded
-* error is a definite verdict: surface it as a `NonRetriableError` so the executor
-* stops and TanStack DB rolls the optimistic insert back. Everything without a
-* code is transient — a `fetch` network failure (`TypeError`) or an HTTP/infra
-* blip the rpc surfaces as a code-less `Error` (a 5xx gateway page, a non-JSON
-* body) — so it's rethrown as-is and the durable outbox replays it. Keying on
-* `error instanceof TypeError` alone would wrongly drop the latter.
-*/
-declare const runOutboxMutation: (mutate: () => Promise<unknown>) => Promise<void>;
-/**
-* An "always attempt" online detector. We deliberately don't trust
-* `navigator.onLine`: some environments (and Playwright's `setOffline` under
-* Firefox) leave it stuck, which would freeze the outbox. Instead the executor
-* always tries the send and {@link runOutboxMutation}'s transient-error retry
-* handles real offline; the periodic tick nudges the executor to drain the outbox
-* so a queued write replays promptly once connectivity returns.
-*
-* `isOnline` is therefore intentionally always `true` — it gates the executor's
-* attempts, not a UI signal. A consumer that wants to show real connectivity
-* should read `navigator.onLine` itself, separately from this detector.
-*/
-declare const createOptimisticOnlineDetector: () => OnlineDetector;
-/** 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;
-  /**
-  * 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;
-}
-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;
-/** 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;
-  /** 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) => LunoraDb<D>;
+export { type C as CheckpointRegistry, type E as ExecutorOutboxSinkOptions, type L as LunoraCollectionConfig, type a as LunoraCollectionOptions, O as OUTBOX_MUTATION_FN_NAME, type b as OutboxExecutor, type d as OutboxMutationMetadata, type R as Row, type S as SyncWriter, c as createCheckpointRegistry, e as createExecutorOutboxSink, f as createOptimisticOnlineDetector, l as lunoraCollectionOptions, m as makeDiffEmit, r as runOutboxMutation, t as toMap } from "./packem_shared/collection-options.d-B3YaP49K.js";
+export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "./packem_shared/define-collections.d-DKc3vPUv.js";
+export { type B as BindMutatorsContext, type a as BoundMutators, type C as ClientMutatorContext, type b as ClientMutatorDef, c as bindMutators, d as defineMutator } from "./packem_shared/define-mutators.d-BqsA6_pd.js";
+import '@lunora/client';
+import '@tanstack/db';
+import '@tanstack/offline-transactions';
 declare const VERSION = "0.0.0";
-export { type CollectionDef, type InsertBinding, type LunoraDb, type Row, type SyncWriter, VERSION, createOptimisticOnlineDetector, defineCollections, makeDiffEmit, runOutboxMutation, toMap };
+export { VERSION };

package/dist/index.mjs

@@ -1,5 +1,7 @@
-export { defineCollections } from './packem_shared/defineCollections-BAmslSrF.mjs';
-export { createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation, toMap } from './packem_shared/createOptimisticOnlineDetector-CRulWqZ7.mjs';
+export { createCheckpointRegistry, lunoraCollectionOptions } from './packem_shared/createCheckpointRegistry-CR_q270X.mjs';
+export { defineCollections } from './packem_shared/defineCollections-it3wN-49.mjs';
+export { bindMutators, defineMutator } from './packem_shared/bindMutators-DWGJhyt3.mjs';
+export { OUTBOX_MUTATION_FN_NAME, createExecutorOutboxSink, createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation, toMap } from './packem_shared/OUTBOX_MUTATION_FN_NAME-3cxtwP39.mjs';
 
 const VERSION = "0.0.0";
 

package/dist/mutators/index.d.mts

@@ -0,0 +1,5 @@
+export { type B as BindMutatorsContext, type a as BoundMutators, type C as ClientMutatorContext, type b as ClientMutatorDef, c as bindMutators, d as defineMutator } from "../packem_shared/define-mutators.d-Bqd-o1Zp.mjs";
+import '@lunora/client';
+import '@tanstack/db';
+import "../packem_shared/collection-options.d-B3YaP49K.mjs";
+import '@tanstack/offline-transactions';

package/dist/mutators/index.d.ts

@@ -0,0 +1,5 @@
+export { type B as BindMutatorsContext, type a as BoundMutators, type C as ClientMutatorContext, type b as ClientMutatorDef, c as bindMutators, d as defineMutator } from "../packem_shared/define-mutators.d-BqsA6_pd.js";
+import '@lunora/client';
+import '@tanstack/db';
+import "../packem_shared/collection-options.d-B3YaP49K.js";
+import '@tanstack/offline-transactions';

package/dist/mutators/index.mjs

@@ -0,0 +1 @@
+export { bindMutators, defineMutator } from '../packem_shared/bindMutators-DWGJhyt3.mjs';

package/dist/packem_shared/{createOptimisticOnlineDetector-CRulWqZ7.mjs → OUTBOX_MUTATION_FN_NAME-3cxtwP39.mjs}

@@ -1,6 +1,39 @@
 import { NonRetriableError } from '@tanstack/offline-transactions';
 
 const OUTBOX_DRAIN_INTERVAL_MS = 1e3;
+const OUTBOX_MUTATION_FN_NAME = "__lunora_outbox__";
+const createExecutorOutboxSink = (executor, options = {}) => {
+  const maxItems = options.maxItems ?? 1e3;
+  const mutationFunctionName = options.mutationFnName ?? OUTBOX_MUTATION_FN_NAME;
+  return {
+    enqueue(mutation) {
+      if (executor.getPendingCount() >= maxItems) {
+        const error = new Error("offline outbox is full");
+        error.code = "OFFLINE_QUEUE_OVERFLOW";
+        return Promise.reject(error);
+      }
+      const metadata = {
+        args: mutation.args,
+        clientId: mutation.clientId,
+        functionPath: mutation.functionPath,
+        // Persist the stable replay key so a committed-but-unacked retry
+        // resends the same `x-lunora-mutation-id` and the server dedups it.
+        idempotencyKey: mutation.idempotencyKey,
+        identity: mutation.identity,
+        mutationId: mutation.mutationId,
+        shardKey: mutation.shardKey
+      };
+      const transaction = executor.createOfflineTransaction({
+        autoCommit: true,
+        idempotencyKey: mutation.idempotencyKey,
+        metadata,
+        mutationFnName: mutationFunctionName
+      });
+      transaction.mutate(() => void 0);
+      return Promise.resolve();
+    }
+  };
+};
 const toMap = (rows, getKey) => {
   const map = /* @__PURE__ */ new Map();
   for (const row of rows) {
@@ -62,4 +95,4 @@ const createOptimisticOnlineDetector = () => {
   };
 };
 
-export { createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation, toMap };
+export { OUTBOX_MUTATION_FN_NAME, createExecutorOutboxSink, createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation, toMap };

package/dist/packem_shared/bindMutators-DWGJhyt3.mjs

@@ -0,0 +1,66 @@
+import { createTransaction } from '@tanstack/db';
+import { runOutboxMutation } from './OUTBOX_MUTATION_FN_NAME-3cxtwP39.mjs';
+
+const defineMutator = (definition) => {
+  return {
+    __lunoraClientMutator: true,
+    apply: definition.apply,
+    serverRef: definition.serverRef
+  };
+};
+const bindMutators = (client, context, mutators) => {
+  const maxReissues = 32;
+  let counter = 0;
+  const nextClientSeq = () => {
+    counter = Math.max(counter, client.confirmedMutationWatermark(context.shardKey)) + 1;
+    return counter;
+  };
+  let pushChain = Promise.resolve();
+  const pushSerialized = (serverRef, args) => {
+    const run = pushChain.then(async () => {
+      for (let attempt = 0; ; attempt += 1) {
+        const clientSeq = nextClientSeq();
+        const { applied } = await client.callMutator(serverRef, args, {
+          clientSeq,
+          shardKey: context.shardKey
+        });
+        if (applied) {
+          return clientSeq;
+        }
+        if (attempt >= maxReissues) {
+          throw new Error(`lunora: custom mutator "${serverRef}" could not claim a fresh client sequence after ${String(maxReissues)} attempts`);
+        }
+      }
+    });
+    pushChain = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  };
+  const bound = {};
+  for (const [name, mutator] of Object.entries(mutators)) {
+    bound[name] = (args) => {
+      const transaction = createTransaction({
+        autoCommit: true,
+        metadata: { serverRef: mutator.serverRef },
+        mutationFn: async () => {
+          let appliedSeq = 0;
+          await runOutboxMutation(async () => {
+            appliedSeq = await pushSerialized(mutator.serverRef, args);
+          });
+          if (context.checkpoints) {
+            await context.checkpoints.awaitMutationId(appliedSeq);
+          }
+        }
+      });
+      transaction.mutate(() => {
+        mutator.apply({ collections: context.collections }, args);
+      });
+      return transaction;
+    };
+  }
+  return bound;
+};
+
+export { bindMutators, defineMutator };