@lunora/db 1.0.0-alpha.8 → 1.0.0-alpha.80

package/dist/packem_shared/collection-options.d-BA8jp3ji.d.ts

@@ -0,0 +1,357 @@
+import { OutboxSink, LunoraClient, FunctionReference, SubscriptionError } from '@lunora/client';
+import { CollectionConfig } from '@tanstack/db';
+import { OnlineDetector } from '@tanstack/offline-transactions';
+/**
+ * Reserved `mutationFns` key the unified outbox routes raw `client.mutation`
+ * offline writes through. `defineCollections` registers a handler under this
+ * name that reads `transaction.metadata` (functionPath + args) and replays the
+ * write, so a db app's direct mutations ride the same durable executor as its
+ * collection inserts instead of the standalone {@link OutboxSink} fallback.
+ */
+declare const OUTBOX_MUTATION_FN_NAME = "__lunora_outbox__";
+/**
+ * Provenance stamped on a durable write at enqueue time: the two questions a
+ * replay cannot answer from the persisted row once the write outlives the
+ * session that made it — WHO queued it, and WHICH shard it belongs to.
+ *
+ * Shared so both replay paths (`db.actions.*` and the reserved
+ * `__lunora_outbox__` handler) check the same fields; they drifted apart once
+ * already, and only one of them had the identity guard.
+ */
+interface WriteProvenance extends Record<string, unknown> {
+  /** Issuing identity fingerprint; a replay drops the write when it no longer matches. */
+  identity: string | null;
+  /** Captured, not re-read at replay: a queued write follows the shard it was made against even if the app reboots pointed at another. */
+  shardKey?: string;
+}
+/** The metadata an outbox-routed transaction carries so its replay can call `client.mutation`. */
+interface OutboxMutationMetadata extends WriteProvenance {
+  args: Record<string, unknown>;
+  clientId: string;
+  functionPath: string;
+  /** Stable `${clientId}:${mutationId}` replay key; passed back as the mutation id so a committed-but-unacked replay is server-idempotent. */
+  idempotencyKey: string;
+  mutationId: number;
+}
+/** A committable outbox transaction handle (the `OfflineTransaction` the executor mints). */
+interface OutboxTransaction {
+  commit?: () => Promise<unknown>;
+  mutate: (callback: () => void) => unknown;
+}
+/**
+ * The slice of the TanStack `OfflineExecutor` the {@link createExecutorOutboxSink}
+ * drives. Declared structurally so `@lunora/db`'s outbox glue doesn't widen its
+ * coupling to the executor's full surface (and stays unit-testable with a fake).
+ */
+interface OutboxExecutor {
+  createOfflineTransaction: (options: {
+    autoCommit?: boolean;
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+    mutationFnName: string;
+  }) => OutboxTransaction;
+  getPendingCount: () => number;
+}
+/** Tuning for {@link createExecutorOutboxSink}. */
+interface ExecutorOutboxSinkOptions {
+  /** Max persisted-but-unconfirmed writes before `enqueue` rejects with `OFFLINE_QUEUE_OVERFLOW` (default 1000, matching `OfflineQueue`). */
+  maxItems?: number;
+  /** `mutationFns` key the replay handler is registered under (default {@link OUTBOX_MUTATION_FN_NAME}). */
+  mutationFnName?: string;
+}
+/**
+ * The blessed {@link OutboxSink} over the TanStack `OfflineExecutor` — the single
+ * durable write path for a `@lunora/db` app. It persists each offline write as an
+ * executor transaction carrying the `client.mutation` target in `metadata`, then
+ * ports the two semantics the executor lacks vs the built-in `OfflineQueue`.
+ *
+ * First: a `maxItems` cap that **rejects** a new write at capacity with an
+ * `OFFLINE_QUEUE_OVERFLOW`-coded error — the {@link OutboxSink} contract, matching
+ * `OfflineQueue`. Rejecting (rather than evicting the oldest) preserves the
+ * at-least-once promise: an already-persisted write is never silently dropped, and
+ * the caller surfaces back-pressure to the issuing mutation (which rolls its
+ * optimistic write back).
+ * Second: the identity guard lives in the replay handler (`defineCollections`), which drops a write whose captured `identity` no longer matches — see {@link OutboxMutationMetadata}.
+ */
+declare const createExecutorOutboxSink: (executor: OutboxExecutor, options?: ExecutorOutboxSinkOptions) => OutboxSink;
+/** 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 `syncedJson`.
+ *
+ * Change detection compares rows by `JSON.stringify`, which is key-order
+ * sensitive — safe here because server snapshots have stable column order
+ * across reconnects (same query projection). A sync source with unstable key
+ * ordering would need a structural compare instead.
+ *
+ * `syncedJson` holds the JSON-serialized form of each last-synced row, keyed
+ * by row id. It is the **sole** synced-state map — no parallel row-object map
+ * is kept. Each incoming value is serialized exactly once per tick (for both
+ * comparison and cache update), so the previous value is never re-serialized.
+ *
+ * Lifecycle: `syncedJson` must be owned by the caller at the same scope as any
+ * other per-collection state (e.g. outside the `sync.sync` callback), so the
+ * cache persists correctly across sync restarts. A new `makeDiffEmit` closure
+ * created on restart receives the same map reference and starts from the
+ * committed synced state — no spurious diffs on reconnect.
+ */
+declare const makeDiffEmit: <T extends object>(syncedJson: Map<string, string>, 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;
+/** A watermark pair — the two monotonic lines a checkpoint registry gates on. */
+interface CheckpointWatermark {
+  /** Op-log cursor the server has durably applied. */
+  checkpoint?: number;
+  /** Highest `clientSeq` the server has echoed back for this client. */
+  mutationId?: number;
+}
+/** Reported when the fallback releases an overlay the sync stream never confirmed. */
+interface CheckpointFallbackEvent {
+  /** Which gate released. */
+  kind: "checkpoint" | "mutationId";
+  /** How long the release waited past the server acknowledgement, in ms. */
+  waitedMs: number;
+  /** The watermark that was acknowledged but never confirmed by a sync frame. */
+  watermark: number;
+}
+/** Counters for {@link CheckpointRegistry.stats} — feeds a debug/diagnostics surface. */
+interface CheckpointRegistryStats {
+  /** How many times the fallback timer released an overlay (a non-zero value means sync frames are being lost). */
+  fallbacks: number;
+  /** Overlays currently waiting on a checkpoint cursor. */
+  pendingCheckpointWaiters: number;
+  /** Overlays currently waiting on a mutation id. */
+  pendingMutationWaiters: number;
+}
+/** Tuning for {@link createCheckpointRegistry}. */
+interface CheckpointRegistryOptions {
+  /**
+   * How long an {@link CheckpointRegistry.acknowledge}d watermark waits for the
+   * authoritative sync frame before the overlay is released anyway. Default 3000.
+   * `0` disables the fallback (an overlay then waits forever for the frame — the
+   * pre-fallback behavior, which hangs on a dropped poke).
+   */
+  fallbackMs?: number;
+  /**
+   * Notified each time the fallback fires. A fallback is never *correct* — it
+   * means a poke or `settled` frame that should have confirmed the write never
+   * arrived — so this is the hook for a warning or a metric. Defaults to a
+   * one-shot `console.warn`.
+   */
+  onFallback?: (event: CheckpointFallbackEvent) => void;
+}
+/**
+ * Resolves the TanStack optimistic-overlay drop against the server's confirmed
+ * watermarks. A mutator's optimistic transaction returns `awaitMutationId(id)`
+ * (or `awaitCheckpoint(cursor)`); TanStack keeps the overlay until that promise
+ * settles, so the row de-duplicates exactly as the synced server value lands — no
+ * flash of the optimistic row disappearing then reappearing.
+ *
+ * Two inputs, deliberately distinct:
+ *
+ * - {@link CheckpointRegistry.resolve} is the **authoritative** advance, called by whoever owns
+ * the watermark stream — a `data`/`delta` frame's `lastMutationId`, or a shape poke's
+ * `checkpoint`. The synced rows have landed, so gates open immediately.
+ * - {@link CheckpointRegistry.acknowledge} is the **provisional** advance, called when the server
+ * has accepted the write (the mutator RPC ack) but the matching rows have not
+ * necessarily been delivered yet. Releasing here would drop the overlay before
+ * the synced row exists — a visible flicker — so instead it arms a bounded
+ * fallback. If the authoritative frame lands first the fallback is cancelled;
+ * if it never lands, the overlay is released after `fallbackMs` and the event is
+ * reported rather than hanging forever.
+ *
+ * That pairing is why a lost poke degrades to a late overlay drop instead of a
+ * permanently stuck `isPersisted` promise.
+ */
+interface CheckpointRegistry {
+  /**
+   * Record a server-accepted watermark whose rows may not have synced yet: arms
+   * the bounded fallback described on {@link CheckpointRegistry}. Safe to call
+   * repeatedly; a watermark already passed is a no-op.
+   */
+  acknowledge: (watermark: CheckpointWatermark) => void;
+  /** Resolve once the server has acknowledged the op-log `cursor`. */
+  awaitCheckpoint: (cursor: number) => Promise<void>;
+  /** Resolve once the server has echoed a `lastMutationId >= id` for this client. */
+  awaitMutationId: (id: number) => Promise<void>;
+  /**
+   * Tear the registry down: `clearTimeout` every armed fallback timer and empty
+   * the armed set. Idempotent. A discarded registry (Vite HMR dispose, sign-out)
+   * can otherwise hold up to `fallbackMs` of pending `setTimeout`s alive through
+   * their closures — keeping a Node/SSR event loop from draining. Distinct from
+   * {@link CheckpointRegistry.resolve}: `resolve` settles parked *waiters* (and disarms the timers it
+   * subsumes as a side effect); `dispose` guarantees no armed timer survives,
+   * independent of any watermark.
+   */
+  dispose: () => void;
+  /** Advance the gates from a sync frame's watermark; later callers past the mark settle immediately. */
+  resolve: (watermark: CheckpointWatermark) => void;
+  /** Diagnostics counters — notably how often the fallback had to fire. */
+  stats: () => CheckpointRegistryStats;
+}
+/** Default fallback window: long enough that a slow-but-arriving poke wins, short enough that a UI isn't visibly stuck. */
+declare const CHECKPOINT_FALLBACK_MS = 3e3;
+/**
+ * A standalone checkpoint/mutation-id registry. Prefer {@link getShardCheckpoints}
+ * unless you are wiring a bespoke watermark stream — a registry must be shared by
+ * every collection on a shard (see that function for why).
+ */
+declare const createCheckpointRegistry: (options?: CheckpointRegistryOptions) => CheckpointRegistry;
+/**
+ * Release every pending overlay gate for `client` and drop its shard registries.
+ *
+ * The hot-reload / teardown escape hatch. When a module that owns collections and
+ * mutators is replaced — a Vite HMR update, a sign-out that rebuilds the data layer
+ * — the *old* bindings may still have transactions parked in `awaitMutationId`. The
+ * subscriptions that would have resolved them are gone with the old module, so
+ * without this those promises never settle and every one of their
+ * `transaction.isPersisted` waiters hangs forever.
+ *
+ * Resolving to `Infinity` settles the parked waiters (the writes were already sent;
+ * the server is authoritative regardless), and dropping the registries means the
+ * replacement module's bindings start from a clean per-shard gate.
+ *
+ * ```ts
+ * // In the module that owns the data layer:
+ * import.meta.hot?.dispose(() => releaseShardCheckpoints(client));
+ * ```
+ */
+declare const releaseShardCheckpoints: (client: LunoraClient) => void;
+/**
+ * The shared checkpoint registry for `client` + `shardKey` — created on first use.
+ * This is the registry {@link lunoraCollectionOptions} and
+ * {@link import("./define-mutators").bindMutators} default to, which is what makes
+ * a multi-collection shard work without the caller relaying pokes between
+ * registries by hand.
+ *
+ * `options` applies **only when the registry is created**. Because the point is that
+ * every collection and mutator on a shard shares one gate, a later call cannot
+ * retune an existing registry — it returns the existing one and `options` is ignored.
+ * To control `fallbackMs` / `onFallback`, build the registry yourself with
+ * {@link createCheckpointRegistry} and pass it explicitly to every
+ * `lunoraCollectionOptions` and `bindMutators` call for that shard.
+ */
+declare const getShardCheckpoints: (client: LunoraClient, shardKey?: string, options?: CheckpointRegistryOptions) => CheckpointRegistry;
+/**
+ * A replication-shape sync source (the local-first partial-replication path).
+ * Mutually exclusive with {@link LunoraCollectionConfig.list}: the collection
+ * live-syncs the named shape's rowset via the client's poke protocol
+ * (`subscribeShape`) instead of a full-table `list` query subscription.
+ */
+interface ShapeSource {
+  /** Validated shape parameters (the partition selector — e.g. `{ channelId }`). */
+  args?: Record<string, unknown>;
+  /** The `defineShape` export name registered in `LUNORA_SHAPES`. */
+  name: string;
+  /** Routes the subscription to a specific shard's DO when the table is sharded. */
+  shardKey?: string;
+}
+/** Declarative inputs for {@link lunoraCollectionOptions}. */
+interface LunoraCollectionConfig<TRow extends Row> {
+  /**
+   * The registry optimistic overlays are gated on. Defaults to the shared
+   * per-shard registry ({@link getShardCheckpoints}), which is what a
+   * multi-collection shard needs — pass one explicitly only to isolate a
+   * collection's gate (tests) or to supply custom {@link CheckpointRegistryOptions}.
+   */
+  checkpoints?: CheckpointRegistry;
+  /** The Lunora client to subscribe through. */
+  client: LunoraClient;
+  /** Row key extractor — defaults to `row._id`. */
+  getKey?: (row: TRow) => string;
+  /** Collection id (TanStack identity) — defaults to the `list` function path (or `shape:` + the shape name). */
+  id?: string;
+  /** The Lunora query that lists the rows (the full-table sync source). Mutually exclusive with {@link LunoraCollectionConfig.shape}. */
+  list?: FunctionReference;
+  /**
+   * When the collection starts syncing. `"lazy"` (default) starts on the first
+   * `useLiveQuery` subscriber; `"eager"` starts at creation (TanStack's
+   * `startSync`) — for small "instant" reference data you want warm at boot.
+   * No effect on a `scopeBy` collection, which has nothing to sync until scoped.
+   * (Even eager, TanStack pauses sync while there are no subscribers, per its
+   * `gcTime` lifecycle — "warm while referenced", not pinned forever.)
+   */
+  load?: "eager" | "lazy";
+  /** Notified when the underlying subscription errors; the collection always leaves `loading` regardless. */
+  onError?: (error: SubscriptionError) => void;
+  /** When set, the collection stays empty until {@link LunoraCollectionOptions.scope} points it at args (sharded). */
+  scopeBy?: string;
+  /** A replication shape as the sync source (partial replication). Mutually exclusive with {@link LunoraCollectionConfig.list}. */
+  shape?: ShapeSource;
+  /**
+   * Routes the `list` subscription — and the confirmed-mutation watermark its
+   * data/`settled` frames advance the checkpoint gate from — to a specific
+   * shard's DO. Applies to the `list` source; a `shape` carries its own
+   * {@link ShapeSource.shardKey}. Without it the list path falls back to the
+   * default ("") watermark bucket, which must not be compared against a
+   * per-shard mutator's sequence line (it would drop a sharded overlay early or
+   * hang it forever).
+   */
+  shardKey?: string;
+}
+/** The result of {@link lunoraCollectionOptions}: a TanStack collection config plus its sync controls. */
+interface LunoraCollectionOptions<TRow extends Row> {
+  /** Resolves optimistic-overlay drops against the server's confirmed watermarks. */
+  checkpoints: CheckpointRegistry;
+  /** Pass to TanStack's `createCollection`. */
+  config: CollectionConfig<TRow, string>;
+  /** Re-point a `scopeBy` collection's subscription (omit `args` to detach). No-op for unscoped collections. */
+  scope: (args?: Record<string, unknown>) => void;
+}
+/**
+ * Build a TanStack DB collection config (+ sync controls) that live-syncs a
+ * Lunora `list` query through the client. This is the reusable core lifted out of
+ * {@link import("./define-collections").defineCollections}: the same `makeDiffEmit`
+ * diff-into-channel, `autoIndex:"eager"` + B-tree indexes, scoped-resubscribe, and
+ * fail-safe `markReady`-on-error behavior, exposed as a standalone
+ * collection-options creator so apps (and codegen) can compose it directly.
+ *
+ * The returned `checkpoints` registry lets a mutator runtime resolve optimistic
+ * overlays against confirmed server watermarks (see {@link CheckpointRegistry}).
+ */
+declare const lunoraCollectionOptions: <TRow extends Row>(options: LunoraCollectionConfig<TRow>) => LunoraCollectionOptions<TRow>;
+export { CHECKPOINT_FALLBACK_MS as C, ExecutorOutboxSinkOptions as E, LunoraCollectionConfig as L, OUTBOX_MUTATION_FN_NAME as O, Row as R, SyncWriter as S, CheckpointFallbackEvent as a, CheckpointRegistry as b, CheckpointRegistryOptions as c, CheckpointRegistryStats as d, CheckpointWatermark as e, LunoraCollectionOptions as f, OutboxExecutor as g, OutboxMutationMetadata as h, createCheckpointRegistry as i, createExecutorOutboxSink as j, createOptimisticOnlineDetector as k, getShardCheckpoints as l, lunoraCollectionOptions as m, makeDiffEmit as n, runOutboxMutation as o, releaseShardCheckpoints as r, toMap as t };

package/dist/packem_shared/defineCollections-Czhhf-A8.mjs

@@ -0,0 +1 @@
+import{lunoraCollectionOptions as T}from"./CHECKPOINT_FALLBACK_MS-DAWfz0yD.mjs";import{createCollection as M,safeRandomUUID as U}from"@tanstack/db";import{startOfflineExecutor as _,NonRetriableError as g}from"@tanstack/offline-transactions";import{createOutboxCarrier as B,createOptimisticOnlineDetector as R,OUTBOX_MUTATION_FN_NAME as K,registerOutboxCarrier as A,runOutboxMutation as I}from"./OUTBOX_MUTATION_FN_NAME-BfFCughR.mjs";const N=new WeakMap,D=(n,r)=>{let e=N.get(n);e===void 0&&(e=new Map,N.set(n,e));const a=e.get(r)??0;e.set(r,a+1),a===1&&console.warn(`[@lunora/db] table "${r}" is bound by more than one defineCollections call on this client. Each call creates its own live collection and outbox for the table, so the two can drift and derived indexes built from one can silently read stale rows. Bind every table in a single defineCollections call (see the "One source of truth per table" docs section).`)},p=(n,r)=>{try{n.onWriteRejected?.(r)}catch{}},v=(n,r)=>{const e=n.replayIdentityVerdict(r?.identity);if(e==="mismatch")throw new g("outbox write dropped: identity changed since it was queued");if(e==="unknown")throw new Error("outbox write deferred: no identity established yet")},k=(n,r,e={})=>{const a={},w={},m={},b=Object.entries(r);for(const[o,t]of b){const i=t.insert;D(n,o);const{config:d,scope:h}=T({client:n,getKey:t.getKey,id:o,list:t.list,...t.load===void 0?{}:{load:t.load},onError:t.onError,scopeBy:t.scopeBy,shardKey:t.shardKey});a[o]=M(d),t.scopeBy!==void 0&&(w[o]=h),i&&(m[o]=async({idempotencyKey:l,transaction:u})=>{const c=u.metadata;for(const[y,F]of u.mutations.entries()){const x=F.modified,E=`${l}:${String(y)}`;try{v(n,c),await I(()=>n.mutation(i.mutation,i.toArgs(x),{mutationId:E,shardKey:c.shardKey}))}catch(f){throw f instanceof g&&p(e,{code:f.code,collection:o,error:f,row:x}),f}}})}m[K]=async({transaction:o})=>{const t=o.metadata;if(t)try{v(n,t),await I(()=>n.mutation({__lunoraRef:t.functionPath},t.args,{mutationId:t.idempotencyKey,shardKey:t.shardKey}))}catch(i){throw i instanceof g&&p(e,{code:i.code,collection:t.functionPath,error:i}),i}};const O=B(),s=_({collections:{...a,[K]:O},mutationFns:m,onlineDetector:R(),...e.onLeadershipChange?{onLeadershipChange:e.onLeadershipChange}:{},...e.onStorageFailure?{onStorageFailure:e.onStorageFailure}:{},onUnknownMutationFn:(o,t)=>{p(e,{code:"UNKNOWN_MUTATION_FN",collection:o,error:new Error(`offline write dropped: mutation "${o}" no longer exists (removed or renamed in a deploy?)`),row:t.mutations[0]?.modified})}});A(s,O);const C={};for(const[o,t]of b){const i=t.insert,d=a[o];!i||!d||(C[o]=h=>{const l=U(),u={identity:n.currentIdentity(),shardKey:t.shardKey},c=s.createOfflineTransaction({autoCommit:!1,metadata:u,mutationFnName:o}),y=c.mutate(()=>{d.insert(i.optimistic(h,l))});return c.commit().catch(()=>{}),{id:l,transaction:y}})}return{actions:C,collections:a,executor:s,pendingCount:()=>s.getPendingCount(),scope:w}};export{k as defineCollections};

package/dist/packem_shared/index.d-BCKTZhCD.d.mts

@@ -0,0 +1,235 @@
+import { LunoraClient } from '@lunora/client';
+import { Collection, Transaction } from '@tanstack/db';
+import { b as CheckpointRegistry } from "./collection-options.d-BA8jp3ji.mjs";
+/**
+ * TanStack DB's "direct transaction" marker.
+ *
+ * A completed transaction's optimistic rows are discarded as **stale** unless
+ * either a synced transaction for the same key is already queued, or the
+ * transaction carried this flag (`CollectionStateManager.recomputeOptimisticState`
+ * → `pendingOptimisticDirectUpserts`). Marked rows instead survive until a sync
+ * operation for that key actually lands, which is precisely the semantics a Lunora
+ * custom mutator needs: the server is the linearization point, so the prediction
+ * must stay visible until the authoritative row arrives. Without it, a text edit
+ * visibly reverts to the last synced value the moment the push is acked.
+ *
+ * The literal is pinned here because `@tanstack/db` does not re-export the constant
+ * from its package root (it lives in the unexported
+ * `collection/transaction-metadata` module). `__tests__/define-mutators.test.ts`
+ * reads that module off disk and fails if the upstream value ever changes.
+ */
+declare const DIRECT_TRANSACTION_METADATA_KEY = "__tanstack_db_direct";
+/**
+ * A map of wired collections, keyed by the name the optimistic bodies address them
+ * by.
+ *
+ * The row type is `any` on purpose. `Collection<T, string>` is **invariant** in
+ * `T` (its methods both consume and produce rows), so a concrete
+ * `Collection<Doc<"nodes"> & Row>` is NOT assignable to `Collection<Row>` — which
+ * is why the previous `Record<string, Collection<Row, string>>` forced an
+ * `as never` cast on every entry, and left `context.collections.<name>` too
+ * untyped to be worth using. Projects recover the concrete types by binding them
+ * once through {@link initMutators}.
+ */
+type CollectionMap = Record<string, Collection<any, string>>;
+/** The local store a client mutator's optimistic body writes against. */
+interface ClientMutatorContext<TCollections extends CollectionMap = CollectionMap> {
+  /** The wired collections, keyed by name — apply optimistic inserts/updates/deletes here. */
+  collections: TCollections;
+}
+/**
+ * A generated mutator reference (`api.mutators.sendMessage`), accepted by
+ * {@link defineMutator} in place of a hand-written path string.
+ *
+ * Declared structurally rather than imported from `@lunora/client` so this module
+ * keeps its narrow dependency surface; the shape matches `FunctionReference`, and
+ * the phantom marker carries the server mutator's arg type so the client body's
+ * args are **inferred** instead of restated.
+ */
+interface MutatorReference<TArgs = unknown> {
+  readonly __lunoraPhantom?: {
+    args: TArgs;
+    kind: unknown;
+    returns: unknown;
+  };
+  readonly __lunoraRef: string;
+}
+/** A client-side custom mutator: an optimistic body plus the path of its authoritative server impl. */
+interface ClientMutatorDef<TArgs, TCollections extends CollectionMap = CollectionMap> {
+  /** 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<TCollections>, 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.
+ *
+ * **Pass a generated reference, not a string.** `serverRef: api.mutators.sendMessage`
+ * both binds the path at compile time — a rename, a typo, or a moved file becomes a
+ * type error instead of a mutation that silently fails at runtime — and **infers
+ * `TArgs` from the server mutator's own validators**, so the arg type is declared
+ * once on the server rather than restated in every client body:
+ *
+ * ```ts
+ * // Typed + checked: args inferred from the server mutator.
+ * defineMutator({
+ *     apply: ({ collections }, args) => { … },   // args: { channelId: Id<"channels">; text: string }
+ *     serverRef: api.mutators.sendMessage,
+ * });
+ *
+ * // Escape hatch: a path string still works, but nothing checks it and you must
+ * // restate the args yourself.
+ * defineMutator<{ text: string }>({ apply, serverRef: "mutators:sendMessage" });
+ * ```
+ *
+ * `context.collections` is typed by whatever map it is bound to — which for this
+ * standalone form is the widest one. Bind the concrete collections once with
+ * {@link initMutators} to get `collections.<name>` typed inside `apply`.
+ */
+declare const defineMutator: {
+  <TArgs = Record<string, unknown>>(definition: {
+    apply: (context: ClientMutatorContext, args: TArgs) => void;
+    serverRef: string;
+  }): ClientMutatorDef<TArgs>;
+  <TArgs>(definition: {
+    apply: (context: ClientMutatorContext, args: TArgs) => void;
+    serverRef: MutatorReference<TArgs>;
+  }): ClientMutatorDef<TArgs>;
+};
+/**
+ * A mutator map whose defs are bound to `TCollections`, arg types erased — the
+ * `TCollections`-pinned counterpart of {@link AnyMutatorMap}, and `any` for the
+ * same variance reason.
+ */
+type MutatorMapFor<TCollections extends CollectionMap> = Record<string, ClientMutatorDef<any, TCollections>>;
+type AnyMutatorMap = Record<string, ClientMutatorDef<any, any>>;
+/** Args type of a mutator definition, whatever collections map it was bound to. */
+type ArgsOf<M> = M extends ClientMutatorDef<infer A, infer _C> ? A : never;
+/** A mutator write that was permanently rejected, passed to {@link BindMutatorsContext.onWriteRejected}. */
+interface MutatorRejectedEvent {
+  /** The args the rejected call was made with. */
+  args: unknown;
+  /**
+   * The machine-readable reason when the server supplied one (e.g. `CONFLICT`,
+   * `FORBIDDEN`). Mirrors {@link import("./define-collections").WriteRejectedEvent.code}.
+   */
+  code?: string;
+  /** The error that rejected the write. */
+  error: Error;
+  /** The bound mutator's key in the map passed to `bindMutators`. */
+  mutator: string;
+  /** The `namespace:fn` path the push targeted. */
+  serverRef: string;
+}
+interface BindMutatorsContext<TCollections extends CollectionMap = CollectionMap> {
+  /**
+   * Resolves the optimistic-overlay drop against confirmed server watermarks: a
+   * mutation's overlay is held until the sync stream echoes
+   * `lastMutationId >= clientSeq` (via {@link CheckpointRegistry.resolve}), so the
+   * row never flashes out and back.
+   *
+   * Defaults to the shared per-shard registry for `client` + {@link BindMutatorsContext.shardKey}
+   * ({@link getShardCheckpoints}) — the same one
+   * {@link import("./collection-options").lunoraCollectionOptions} defaults to, so
+   * a shard's collections and its mutators gate on one watermark line without the
+   * caller wiring them together. Pass `false` to drop the overlay as soon as the
+   * server accepts the write (the by-value sync diff then converges the synced row
+   * in place).
+   */
+  checkpoints?: CheckpointRegistry | false;
+  /** The wired collections the optimistic bodies write against. */
+  collections: TCollections;
+  /**
+   * Called when a mutator's server push is permanently rejected — the aggregate
+   * failure channel for writes, symmetric with
+   * {@link import("./define-collections").DefineCollectionsOptions.onWriteRejected}
+   * on the outbox path.
+   *
+   * Supplying it also makes a **fire-and-forget** call safe: a bound handle
+   * returns a `Transaction` whose `isPersisted` promise rejects on failure, so a
+   * caller that neither awaits it nor attaches a `.catch` leaves an unhandled
+   * rejection. With this hook set, `bindMutators` consumes that rejection itself
+   * after reporting it — a caller that DOES await still sees the rejection, so
+   * per-call handling is unaffected.
+   *
+   * A throwing listener is swallowed: reporting a failure must not manufacture a
+   * second one.
+   */
+  onWriteRejected?: (event: MutatorRejectedEvent) => void;
+  /** 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, TCollections extends CollectionMap = CollectionMap>(client: LunoraClient, context: BindMutatorsContext<TCollections>, mutators: M) => BoundMutators<M>;
+/** `defineMutator` + `bindMutators`, both bound to one project's collections map. */
+interface BoundMutatorApi<TCollections extends CollectionMap> {
+  /** {@link bindMutators}, with `collections` pinned to `TCollections`. */
+  bindMutators: <M extends MutatorMapFor<TCollections>>(client: LunoraClient, context: BindMutatorsContext<TCollections>, mutators: M) => BoundMutators<M>;
+  /** {@link defineMutator}, with `context.collections` typed as `TCollections`. */
+  defineMutator: {
+    <TArgs = Record<string, unknown>>(definition: {
+      apply: (context: ClientMutatorContext<TCollections>, args: TArgs) => void;
+      serverRef: string;
+    }): ClientMutatorDef<TArgs, TCollections>;
+    <TArgs>(definition: {
+      apply: (context: ClientMutatorContext<TCollections>, args: TArgs) => void;
+      serverRef: MutatorReference<TArgs>;
+    }): ClientMutatorDef<TArgs, TCollections>;
+  };
+}
+/**
+ * Bind the mutator surface to **this project's** collections map, once.
+ *
+ * `Collection` is invariant in its row type, so a shared
+ * `Record<string, Collection<Row, string>>` could neither accept a generated
+ * collection without an `as never` cast nor hand a usable type back to `apply` —
+ * which is why optimistic bodies tended to ignore `context.collections` and close
+ * over module-scope collection variables instead. Declaring the map once here
+ * fixes both ends: `bindMutators` takes the concrete collections cast-free, and
+ * `apply` reads `collections.<name>` at its real row type.
+ *
+ * Runtime-identical to the standalone {@link defineMutator} / {@link bindMutators}
+ * (this returns those very functions); only the types narrow.
+ * @example
+ * const { bindMutators, defineMutator } = initMutators<{ nodes: typeof wholeOutlineCollection }>();
+ * const setText = defineMutator({ apply: ({ collections }, args) => collections.nodes.update(args.id, setter), serverRef: api.mutators.setText });
+ */
+declare const initMutators: <TCollections extends CollectionMap>() => BoundMutatorApi<TCollections>;
+export { BindMutatorsContext as B, ClientMutatorContext as C, DIRECT_TRANSACTION_METADATA_KEY as D, MutatorReference as M, BoundMutatorApi as a, BoundMutators as b, ClientMutatorDef as c, CollectionMap as d, MutatorRejectedEvent as e, bindMutators as f, defineMutator as g, initMutators as i };