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

package/dist/collections/index.d.mts

@@ -1,5 +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-CbS3J_Fm.mjs";
-export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "../packem_shared/define-collections.d-DTS0ANuU.mjs";
+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-lJBOVJgq.mjs";
+export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "../packem_shared/define-collections.d-CdORnl3S.mjs";
 import '@lunora/client';
 import '@tanstack/db';
 import '@tanstack/offline-transactions';

package/dist/collections/index.d.ts

@@ -1,5 +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-CbS3J_Fm.js";
-export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "../packem_shared/define-collections.d-Po97lX6i.js";
+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-lJBOVJgq.js";
+export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "../packem_shared/define-collections.d-X2MfU5Es.js";
 import '@lunora/client';
 import '@tanstack/db';
 import '@tanstack/offline-transactions';

package/dist/collections/index.mjs

@@ -1,2 +1,2 @@
-export { createCheckpointRegistry, lunoraCollectionOptions } from '../packem_shared/createCheckpointRegistry-C1kzNWCs.mjs';
-export { defineCollections } from '../packem_shared/defineCollections-DR6fcIkQ.mjs';
+export { createCheckpointRegistry, lunoraCollectionOptions } from '../packem_shared/createCheckpointRegistry-SvwBczzv.mjs';
+export { defineCollections } from '../packem_shared/defineCollections-BJNtgnWB.mjs';

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-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-CbS3J_Fm.mjs";
-export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "./packem_shared/define-collections.d-DTS0ANuU.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-DNVJIpW8.mjs";
+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-lJBOVJgq.mjs";
+export { type C as CollectionDef, type D as DefineCollectionsOptions, type I as InsertBinding, type L as LunoraDb, type W as WriteRejectedEvent, d as defineCollections } from "./packem_shared/define-collections.d-CdORnl3S.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-HWj94_nL.mjs";
 import '@lunora/client';
 import '@tanstack/db';
 import '@tanstack/offline-transactions';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-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-CbS3J_Fm.js";
-export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "./packem_shared/define-collections.d-Po97lX6i.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-C3DO284A.js";
+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-lJBOVJgq.js";
+export { type C as CollectionDef, type D as DefineCollectionsOptions, type I as InsertBinding, type L as LunoraDb, type W as WriteRejectedEvent, d as defineCollections } from "./packem_shared/define-collections.d-X2MfU5Es.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-DhO8mWz0.js";
 import '@lunora/client';
 import '@tanstack/db';
 import '@tanstack/offline-transactions';

package/dist/index.mjs

@@ -1,7 +1,7 @@
-export { createCheckpointRegistry, lunoraCollectionOptions } from './packem_shared/createCheckpointRegistry-C1kzNWCs.mjs';
-export { defineCollections } from './packem_shared/defineCollections-DR6fcIkQ.mjs';
-export { bindMutators, defineMutator } from './packem_shared/bindMutators-Bh6giR9x.mjs';
-export { OUTBOX_MUTATION_FN_NAME, createExecutorOutboxSink, createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation, toMap } from './packem_shared/OUTBOX_MUTATION_FN_NAME-DZrP1gna.mjs';
+export { createCheckpointRegistry, lunoraCollectionOptions } from './packem_shared/createCheckpointRegistry-SvwBczzv.mjs';
+export { defineCollections } from './packem_shared/defineCollections-BJNtgnWB.mjs';
+export { bindMutators, defineMutator } from './packem_shared/bindMutators-DNhICkoy.mjs';
+export { OUTBOX_MUTATION_FN_NAME, createExecutorOutboxSink, createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation, toMap } from './packem_shared/OUTBOX_MUTATION_FN_NAME-Cf8iP6Wa.mjs';
 
 const VERSION = "0.0.0";
 

package/dist/mutators/index.d.mts

@@ -1,5 +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-DNVJIpW8.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-HWj94_nL.mjs";
 import '@lunora/client';
 import '@tanstack/db';
-import "../packem_shared/collection-options.d-CbS3J_Fm.mjs";
+import "../packem_shared/collection-options.d-lJBOVJgq.mjs";
 import '@tanstack/offline-transactions';

package/dist/mutators/index.d.ts

@@ -1,5 +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-C3DO284A.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-DhO8mWz0.js";
 import '@lunora/client';
 import '@tanstack/db';
-import "../packem_shared/collection-options.d-CbS3J_Fm.js";
+import "../packem_shared/collection-options.d-lJBOVJgq.js";
 import '@tanstack/offline-transactions';

package/dist/mutators/index.mjs

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

package/dist/packem_shared/{OUTBOX_MUTATION_FN_NAME-DZrP1gna.mjs → OUTBOX_MUTATION_FN_NAME-Cf8iP6Wa.mjs}

@@ -69,7 +69,9 @@ const runOutboxMutation = async (mutate) => {
     await mutate();
   } catch (error) {
     if (typeof error.code === "string") {
-      throw new NonRetriableError(error instanceof Error ? error.message : String(error));
+      const nonRetriable = new NonRetriableError(error instanceof Error ? error.message : String(error));
+      nonRetriable.code = error.code;
+      throw nonRetriable;
     }
     throw error;
   }

package/dist/packem_shared/{bindMutators-Bh6giR9x.mjs → bindMutators-DNhICkoy.mjs}

@@ -1,5 +1,5 @@
 import { createTransaction } from '@tanstack/db';
-import { runOutboxMutation } from './OUTBOX_MUTATION_FN_NAME-DZrP1gna.mjs';
+import { runOutboxMutation } from './OUTBOX_MUTATION_FN_NAME-Cf8iP6Wa.mjs';
 
 const defineMutator = (definition) => {
   return {

package/dist/packem_shared/{collection-options.d-CbS3J_Fm.d.mts → collection-options.d-lJBOVJgq.d.mts}

@@ -176,6 +176,15 @@ interface LunoraCollectionConfig<TRow extends Row> {
   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). */

package/dist/packem_shared/{collection-options.d-CbS3J_Fm.d.ts → collection-options.d-lJBOVJgq.d.ts}

@@ -176,6 +176,15 @@ interface LunoraCollectionConfig<TRow extends Row> {
   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). */

package/dist/packem_shared/{createCheckpointRegistry-C1kzNWCs.mjs → createCheckpointRegistry-SvwBczzv.mjs}

@@ -1,5 +1,5 @@
 import { BTreeIndex } from '@tanstack/db';
-import { toMap, makeDiffEmit } from './OUTBOX_MUTATION_FN_NAME-DZrP1gna.mjs';
+import { toMap, makeDiffEmit } from './OUTBOX_MUTATION_FN_NAME-Cf8iP6Wa.mjs';
 
 const createGate = () => {
   let highest = Number.NEGATIVE_INFINITY;
@@ -82,6 +82,9 @@ const lunoraCollectionOptions = (options) => {
     defaultIndexType: BTreeIndex,
     getKey,
     id: options.id ?? options.list?.__lunoraRef ?? `shape:${options.shape?.name ?? ""}`,
+    // `"eager"` syncs at creation; omitted otherwise so the wire stays
+    // byte-identical to the lazy default (sync on first subscriber).
+    ...options.load === "eager" ? { startSync: true } : {},
     sync: {
       sync: (writer) => {
         emit = makeDiffEmit(syncedJson, writer);

package/dist/packem_shared/{define-collections.d-Po97lX6i.d.ts → define-collections.d-CdORnl3S.d.mts}

@@ -1,7 +1,7 @@
 import { FunctionReference, SubscriptionError, LunoraClient } from '@lunora/client';
 import { Transaction, Collection } from '@tanstack/db';
-import { OfflineExecutor } from '@tanstack/offline-transactions';
-import { R as Row } from "./collection-options.d-CbS3J_Fm.js";
+import { OfflineExecutor, StorageDiagnostic } from '@tanstack/offline-transactions';
+import { R as Row } from "./collection-options.d-lJBOVJgq.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. */
@@ -31,6 +31,15 @@ interface CollectionDef<TList extends FunctionReference, TInput = never> {
   /** 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
@@ -53,6 +62,62 @@ type InputOf<C> = C extends {
     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. */
@@ -81,5 +146,5 @@ interface LunoraDb<D extends Record<string, AnyDef>> {
 * 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 { CollectionDef as C, InsertBinding as I, LunoraDb as L, defineCollections as d };
+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-DTS0ANuU.d.mts → define-collections.d-X2MfU5Es.d.ts}

@@ -1,7 +1,7 @@
 import { FunctionReference, SubscriptionError, LunoraClient } from '@lunora/client';
 import { Transaction, Collection } from '@tanstack/db';
-import { OfflineExecutor } from '@tanstack/offline-transactions';
-import { R as Row } from "./collection-options.d-CbS3J_Fm.mjs";
+import { OfflineExecutor, StorageDiagnostic } from '@tanstack/offline-transactions';
+import { R as Row } from "./collection-options.d-lJBOVJgq.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. */
@@ -31,6 +31,15 @@ interface CollectionDef<TList extends FunctionReference, TInput = never> {
   /** 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
@@ -53,6 +62,62 @@ type InputOf<C> = C extends {
     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. */
@@ -81,5 +146,5 @@ interface LunoraDb<D extends Record<string, AnyDef>> {
 * 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 { CollectionDef as C, InsertBinding as I, LunoraDb as L, defineCollections as d };
+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-C3DO284A.d.ts → define-mutators.d-DhO8mWz0.d.ts}

@@ -1,6 +1,6 @@
 import { LunoraClient } from '@lunora/client';
 import { Collection, Transaction } from '@tanstack/db';
-import { C as CheckpointRegistry, R as Row } from "./collection-options.d-CbS3J_Fm.js";
+import { C as CheckpointRegistry, R as Row } from "./collection-options.d-lJBOVJgq.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. */

package/dist/packem_shared/{define-mutators.d-DNVJIpW8.d.mts → define-mutators.d-HWj94_nL.d.mts}

@@ -1,6 +1,6 @@
 import { LunoraClient } from '@lunora/client';
 import { Collection, Transaction } from '@tanstack/db';
-import { C as CheckpointRegistry, R as Row } from "./collection-options.d-CbS3J_Fm.mjs";
+import { C as CheckpointRegistry, R as Row } from "./collection-options.d-lJBOVJgq.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. */

package/dist/packem_shared/{defineCollections-DR6fcIkQ.mjs → defineCollections-BJNtgnWB.mjs}

@@ -1,9 +1,9 @@
 import { createCollection } from '@tanstack/db';
 import { startOfflineExecutor, NonRetriableError } from '@tanstack/offline-transactions';
-import { lunoraCollectionOptions } from './createCheckpointRegistry-C1kzNWCs.mjs';
-import { createOptimisticOnlineDetector, runOutboxMutation, OUTBOX_MUTATION_FN_NAME } from './OUTBOX_MUTATION_FN_NAME-DZrP1gna.mjs';
+import { lunoraCollectionOptions } from './createCheckpointRegistry-SvwBczzv.mjs';
+import { createOptimisticOnlineDetector, runOutboxMutation, OUTBOX_MUTATION_FN_NAME } from './OUTBOX_MUTATION_FN_NAME-Cf8iP6Wa.mjs';
 
-const defineCollections = (client, defs) => {
+const defineCollections = (client, defs, options = {}) => {
   const collections = {};
   const scope = {};
   const mutationFns = {};
@@ -16,6 +16,7 @@ const defineCollections = (client, defs) => {
       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
     });
@@ -27,7 +28,17 @@ const defineCollections = (client, defs) => {
       mutationFns[name] = async ({ transaction }) => {
         for (const mutation of transaction.mutations) {
           const row = mutation.modified;
-          await runOutboxMutation(() => client.mutation(insert.mutation, insert.toArgs(row)));
+          try {
+            await runOutboxMutation(() => client.mutation(insert.mutation, insert.toArgs(row)));
+          } catch (error) {
+            if (error instanceof NonRetriableError && options.onWriteRejected) {
+              try {
+                options.onWriteRejected({ code: error.code, collection: name, error, row });
+              } catch {
+              }
+            }
+            throw error;
+          }
         }
       };
     }
@@ -47,7 +58,27 @@ const defineCollections = (client, defs) => {
   const executor = startOfflineExecutor({
     collections,
     mutationFns,
-    onlineDetector: createOptimisticOnlineDetector()
+    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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/db",
-  "version": "1.0.0-alpha.8",
+  "version": "1.0.0-alpha.9",
   "description": "TanStack DB binding: typed, live-synced collections and a durable offline outbox over the Lunora client",
   "keywords": [
     "cloudflare",
@@ -54,7 +54,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.8"
+    "@lunora/client": "1.0.0-alpha.9"
   },
   "peerDependencies": {
     "@tanstack/db": "^0.6.0",