@lunora/db 1.0.0-alpha.1 → 1.0.0-alpha.100

package/dist/collections/index.d.mts

@@ -0,0 +1,5 @@
+export { type b as CheckpointRegistry, type L as LunoraCollectionConfig, type f as LunoraCollectionOptions, i as createCheckpointRegistry, m as lunoraCollectionOptions } from "../packem_shared/collection-options.d-bmH3BTGq.mjs";
+export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "../packem_shared/index.d-BzXEOiP5.mjs";
+import '@lunora/client';
+import '@tanstack/db';
+import '@tanstack/offline-transactions';

package/dist/collections/index.d.ts

@@ -0,0 +1,5 @@
+export { type b as CheckpointRegistry, type L as LunoraCollectionConfig, type f as LunoraCollectionOptions, i as createCheckpointRegistry, m as lunoraCollectionOptions } from "../packem_shared/collection-options.d-bmH3BTGq.js";
+export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "../packem_shared/index.d-DlfHbDas.js";
+import '@lunora/client';
+import '@tanstack/db';
+import '@tanstack/offline-transactions';

package/dist/collections/index.mjs

@@ -0,0 +1 @@
+import{createCheckpointRegistry as t,lunoraCollectionOptions as r}from"../packem_shared/CHECKPOINT_FALLBACK_MS-DVkxHO2j.mjs";import{defineCollections as n}from"../packem_shared/defineCollections-Cz4-m1Mp.mjs";export{t as createCheckpointRegistry,n as defineCollections,r as lunoraCollectionOptions};

package/dist/index.d.mts

@@ -1,142 +1,147 @@
-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;
+import { Collection } from '@tanstack/db';
+import { R as Row } from "./packem_shared/collection-options.d-bmH3BTGq.mjs";
+export { C as CHECKPOINT_FALLBACK_MS, type a as CheckpointFallbackEvent, type b as CheckpointRegistry, type c as CheckpointRegistryOptions, type d as CheckpointRegistryStats, type e as CheckpointWatermark, type E as ExecutorOutboxSinkOptions, type L as LunoraCollectionConfig, type f as LunoraCollectionOptions, O as OUTBOX_MUTATION_FN_NAME, type g as OutboxExecutor, type h as OutboxMutationMetadata, type S as SyncWriter, i as createCheckpointRegistry, j as createExecutorOutboxSink, k as createOptimisticOnlineDetector, l as getShardCheckpoints, m as lunoraCollectionOptions, n as makeDiffEmit, r as releaseShardCheckpoints, o as runOutboxMutation, t as toMap } from "./packem_shared/collection-options.d-bmH3BTGq.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/index.d-BzXEOiP5.mjs";
+export { type B as BindMutatorsContext, type a as BoundMutatorApi, type b as BoundMutators, type C as ClientMutatorContext, type c as ClientMutatorDef, type d as CollectionMap, D as DIRECT_TRANSACTION_METADATA_KEY, type M as MutatorReference, type e as MutatorRejectedEvent, f as bindMutators, g as defineMutator, i as initMutators } from "./packem_shared/index.d-DrpzHIoj.mjs";
+import '@lunora/client';
+import '@tanstack/offline-transactions';
+/** One row to insert. `_id` may be pre-minted client-side so the optimistic row keys match the persisted one. */
+interface PlanInsert {
+  /** Row body. Include `_id` to key the row yourself (the server honors it as the `clientId`). */
+  row: Record<string, unknown> & {
+    _id?: string;
+  };
+  table: string;
 }
-/** 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>;
+/** One row to patch, by id. */
+interface PlanPatch {
+  fields: Record<string, unknown>;
+  id: string;
+  table: string;
 }
-/** 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;
+/** One row to delete, by id. */
+interface PlanDelete {
+  id: string;
+  table: 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 };
+ * A change plan: what a mutator intends to write.
+ *
+ * Applied in a fixed order — **deletes, then patches, then inserts** — by both
+ * appliers. The order is part of the contract, not an implementation detail: a plan
+ * that deletes a row and inserts its replacement under the same natural key only
+ * behaves the same on both sides if both sides agree which happens first.
+ */
+interface ChangePlan {
+  deletes?: ReadonlyArray<PlanDelete>;
+  inserts?: ReadonlyArray<PlanInsert>;
+  patches?: ReadonlyArray<PlanPatch>;
+}
+/**
+ * The `ctx.db` methods {@link applyPlanToDb} needs — structural, so any writer
+ * satisfies it.
+ *
+ * The `never` parameter positions are deliberate, not laziness. `ctx.db.delete` is
+ * `<T extends string>(id: Id<T>) => …` over the **branded** `Id<T>`, and under
+ * `strictFunctionTypes` a parameter is contravariant — so declaring `id: string` here
+ * would make the real `ctx.db` un-assignable to `PlanWriter` (`string` is not
+ * assignable to `string & { __table }`), and every caller would need a cast at the
+ * call site instead. `never` accepts any branded id, which keeps `applyPlanToDb(ctx.db,
+ * plan)` cast-free for the caller and confines the two `as never` casts to this module.
+ *
+ * The trade-off is real: argument checking inside `applyPlanToDb` is erased, so a plan
+ * naming a table the schema doesn't have is a runtime error. Use `ctx.db.asId(table,
+ * id)` when building the plan to catch a malformed id at the boundary.
+ */
+interface PlanWriter {
+  delete: (id: never) => Promise<void>;
+  insert: (tableName: never, document: Record<string, unknown>, options?: {
+    clientId?: string;
+  }) => Promise<unknown>;
+  patch: (id: never, patch: Record<string, unknown>) => Promise<void>;
 }
 /**
-* 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>;
+ * Apply `plan` to a map of TanStack collections — the client (optimistic) half.
+ *
+ * A plan naming a table with no wired collection is **skipped, not an error**: an app
+ * legitimately syncs a subset of the tables its mutators write (a server-only audit
+ * row has no client collection), and throwing would make the optimistic body fail on
+ * a write the server handles fine.
+ */
+declare const applyPlanToCollections: (collections: Record<string, Collection<Row, string>>, plan: ChangePlan) => void;
+/**
+ * Apply `plan` to a `ctx.db` writer — the server (authoritative) half.
+ *
+ * Sequential by design: the shard's SQLite is single-threaded and a mutation runs
+ * inside one BEGIN/COMMIT span, so ordering is observable and a mid-plan failure
+ * rolls the whole plan back. An insert carrying an `_id` forwards it as `clientId`,
+ * which is how a client-minted key becomes the persisted primary key.
+ */
+declare const applyPlanToDb: (db: PlanWriter, plan: ChangePlan) => Promise<void>;
 declare const VERSION = "0.0.0";
-export { type CollectionDef, type InsertBinding, type LunoraDb, type Row, type SyncWriter, VERSION, createOptimisticOnlineDetector, defineCollections, makeDiffEmit, runOutboxMutation, toMap };
+export {
+/**
+ * `@lunora/db` — a TanStack DB binding for the Lunora client.
+ *
+ * `defineCollections(client, { … })` wires a set of Lunora tables into live,
+ * auto-indexed TanStack DB collections (reads) plus a durable, retried
+ * offline-transactions outbox (writes) in one declaration. The lower-level
+ * helpers are exported for testing and advanced composition.
+ *
+ * Peer-depends on `@tanstack/db` and `@tanstack/offline-transactions`; the
+ * consuming app pins their versions and supplies React bindings
+ * (`@tanstack/react-db`) itself.
+ */
+type ChangePlan,
+/**
+ * `@lunora/db` — a TanStack DB binding for the Lunora client.
+ *
+ * `defineCollections(client, { … })` wires a set of Lunora tables into live,
+ * auto-indexed TanStack DB collections (reads) plus a durable, retried
+ * offline-transactions outbox (writes) in one declaration. The lower-level
+ * helpers are exported for testing and advanced composition.
+ *
+ * Peer-depends on `@tanstack/db` and `@tanstack/offline-transactions`; the
+ * consuming app pins their versions and supplies React bindings
+ * (`@tanstack/react-db`) itself.
+ */
+type PlanDelete,
+/**
+ * `@lunora/db` — a TanStack DB binding for the Lunora client.
+ *
+ * `defineCollections(client, { … })` wires a set of Lunora tables into live,
+ * auto-indexed TanStack DB collections (reads) plus a durable, retried
+ * offline-transactions outbox (writes) in one declaration. The lower-level
+ * helpers are exported for testing and advanced composition.
+ *
+ * Peer-depends on `@tanstack/db` and `@tanstack/offline-transactions`; the
+ * consuming app pins their versions and supplies React bindings
+ * (`@tanstack/react-db`) itself.
+ */
+type PlanInsert,
+/**
+ * `@lunora/db` — a TanStack DB binding for the Lunora client.
+ *
+ * `defineCollections(client, { … })` wires a set of Lunora tables into live,
+ * auto-indexed TanStack DB collections (reads) plus a durable, retried
+ * offline-transactions outbox (writes) in one declaration. The lower-level
+ * helpers are exported for testing and advanced composition.
+ *
+ * Peer-depends on `@tanstack/db` and `@tanstack/offline-transactions`; the
+ * consuming app pins their versions and supplies React bindings
+ * (`@tanstack/react-db`) itself.
+ */
+type PlanPatch,
+/**
+ * `@lunora/db` — a TanStack DB binding for the Lunora client.
+ *
+ * `defineCollections(client, { … })` wires a set of Lunora tables into live,
+ * auto-indexed TanStack DB collections (reads) plus a durable, retried
+ * offline-transactions outbox (writes) in one declaration. The lower-level
+ * helpers are exported for testing and advanced composition.
+ *
+ * Peer-depends on `@tanstack/db` and `@tanstack/offline-transactions`; the
+ * consuming app pins their versions and supplies React bindings
+ * (`@tanstack/react-db`) itself.
+ */
+type PlanWriter, type Row, VERSION, applyPlanToCollections, applyPlanToDb };

package/dist/index.d.ts

@@ -1,142 +1,147 @@
-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;
+import { Collection } from '@tanstack/db';
+import { R as Row } from "./packem_shared/collection-options.d-bmH3BTGq.js";
+export { C as CHECKPOINT_FALLBACK_MS, type a as CheckpointFallbackEvent, type b as CheckpointRegistry, type c as CheckpointRegistryOptions, type d as CheckpointRegistryStats, type e as CheckpointWatermark, type E as ExecutorOutboxSinkOptions, type L as LunoraCollectionConfig, type f as LunoraCollectionOptions, O as OUTBOX_MUTATION_FN_NAME, type g as OutboxExecutor, type h as OutboxMutationMetadata, type S as SyncWriter, i as createCheckpointRegistry, j as createExecutorOutboxSink, k as createOptimisticOnlineDetector, l as getShardCheckpoints, m as lunoraCollectionOptions, n as makeDiffEmit, r as releaseShardCheckpoints, o as runOutboxMutation, t as toMap } from "./packem_shared/collection-options.d-bmH3BTGq.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/index.d-DlfHbDas.js";
+export { type B as BindMutatorsContext, type a as BoundMutatorApi, type b as BoundMutators, type C as ClientMutatorContext, type c as ClientMutatorDef, type d as CollectionMap, D as DIRECT_TRANSACTION_METADATA_KEY, type M as MutatorReference, type e as MutatorRejectedEvent, f as bindMutators, g as defineMutator, i as initMutators } from "./packem_shared/index.d-DQsjGcjP.js";
+import '@lunora/client';
+import '@tanstack/offline-transactions';
+/** One row to insert. `_id` may be pre-minted client-side so the optimistic row keys match the persisted one. */
+interface PlanInsert {
+  /** Row body. Include `_id` to key the row yourself (the server honors it as the `clientId`). */
+  row: Record<string, unknown> & {
+    _id?: string;
+  };
+  table: string;
 }
-/** 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>;
+/** One row to patch, by id. */
+interface PlanPatch {
+  fields: Record<string, unknown>;
+  id: string;
+  table: string;
 }
-/** 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;
+/** One row to delete, by id. */
+interface PlanDelete {
+  id: string;
+  table: 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 };
+ * A change plan: what a mutator intends to write.
+ *
+ * Applied in a fixed order — **deletes, then patches, then inserts** — by both
+ * appliers. The order is part of the contract, not an implementation detail: a plan
+ * that deletes a row and inserts its replacement under the same natural key only
+ * behaves the same on both sides if both sides agree which happens first.
+ */
+interface ChangePlan {
+  deletes?: ReadonlyArray<PlanDelete>;
+  inserts?: ReadonlyArray<PlanInsert>;
+  patches?: ReadonlyArray<PlanPatch>;
+}
+/**
+ * The `ctx.db` methods {@link applyPlanToDb} needs — structural, so any writer
+ * satisfies it.
+ *
+ * The `never` parameter positions are deliberate, not laziness. `ctx.db.delete` is
+ * `<T extends string>(id: Id<T>) => …` over the **branded** `Id<T>`, and under
+ * `strictFunctionTypes` a parameter is contravariant — so declaring `id: string` here
+ * would make the real `ctx.db` un-assignable to `PlanWriter` (`string` is not
+ * assignable to `string & { __table }`), and every caller would need a cast at the
+ * call site instead. `never` accepts any branded id, which keeps `applyPlanToDb(ctx.db,
+ * plan)` cast-free for the caller and confines the two `as never` casts to this module.
+ *
+ * The trade-off is real: argument checking inside `applyPlanToDb` is erased, so a plan
+ * naming a table the schema doesn't have is a runtime error. Use `ctx.db.asId(table,
+ * id)` when building the plan to catch a malformed id at the boundary.
+ */
+interface PlanWriter {
+  delete: (id: never) => Promise<void>;
+  insert: (tableName: never, document: Record<string, unknown>, options?: {
+    clientId?: string;
+  }) => Promise<unknown>;
+  patch: (id: never, patch: Record<string, unknown>) => Promise<void>;
 }
 /**
-* 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>;
+ * Apply `plan` to a map of TanStack collections — the client (optimistic) half.
+ *
+ * A plan naming a table with no wired collection is **skipped, not an error**: an app
+ * legitimately syncs a subset of the tables its mutators write (a server-only audit
+ * row has no client collection), and throwing would make the optimistic body fail on
+ * a write the server handles fine.
+ */
+declare const applyPlanToCollections: (collections: Record<string, Collection<Row, string>>, plan: ChangePlan) => void;
+/**
+ * Apply `plan` to a `ctx.db` writer — the server (authoritative) half.
+ *
+ * Sequential by design: the shard's SQLite is single-threaded and a mutation runs
+ * inside one BEGIN/COMMIT span, so ordering is observable and a mid-plan failure
+ * rolls the whole plan back. An insert carrying an `_id` forwards it as `clientId`,
+ * which is how a client-minted key becomes the persisted primary key.
+ */
+declare const applyPlanToDb: (db: PlanWriter, plan: ChangePlan) => Promise<void>;
 declare const VERSION = "0.0.0";
-export { type CollectionDef, type InsertBinding, type LunoraDb, type Row, type SyncWriter, VERSION, createOptimisticOnlineDetector, defineCollections, makeDiffEmit, runOutboxMutation, toMap };
+export {
+/**
+ * `@lunora/db` — a TanStack DB binding for the Lunora client.
+ *
+ * `defineCollections(client, { … })` wires a set of Lunora tables into live,
+ * auto-indexed TanStack DB collections (reads) plus a durable, retried
+ * offline-transactions outbox (writes) in one declaration. The lower-level
+ * helpers are exported for testing and advanced composition.
+ *
+ * Peer-depends on `@tanstack/db` and `@tanstack/offline-transactions`; the
+ * consuming app pins their versions and supplies React bindings
+ * (`@tanstack/react-db`) itself.
+ */
+type ChangePlan,
+/**
+ * `@lunora/db` — a TanStack DB binding for the Lunora client.
+ *
+ * `defineCollections(client, { … })` wires a set of Lunora tables into live,
+ * auto-indexed TanStack DB collections (reads) plus a durable, retried
+ * offline-transactions outbox (writes) in one declaration. The lower-level
+ * helpers are exported for testing and advanced composition.
+ *
+ * Peer-depends on `@tanstack/db` and `@tanstack/offline-transactions`; the
+ * consuming app pins their versions and supplies React bindings
+ * (`@tanstack/react-db`) itself.
+ */
+type PlanDelete,
+/**
+ * `@lunora/db` — a TanStack DB binding for the Lunora client.
+ *
+ * `defineCollections(client, { … })` wires a set of Lunora tables into live,
+ * auto-indexed TanStack DB collections (reads) plus a durable, retried
+ * offline-transactions outbox (writes) in one declaration. The lower-level
+ * helpers are exported for testing and advanced composition.
+ *
+ * Peer-depends on `@tanstack/db` and `@tanstack/offline-transactions`; the
+ * consuming app pins their versions and supplies React bindings
+ * (`@tanstack/react-db`) itself.
+ */
+type PlanInsert,
+/**
+ * `@lunora/db` — a TanStack DB binding for the Lunora client.
+ *
+ * `defineCollections(client, { … })` wires a set of Lunora tables into live,
+ * auto-indexed TanStack DB collections (reads) plus a durable, retried
+ * offline-transactions outbox (writes) in one declaration. The lower-level
+ * helpers are exported for testing and advanced composition.
+ *
+ * Peer-depends on `@tanstack/db` and `@tanstack/offline-transactions`; the
+ * consuming app pins their versions and supplies React bindings
+ * (`@tanstack/react-db`) itself.
+ */
+type PlanPatch,
+/**
+ * `@lunora/db` — a TanStack DB binding for the Lunora client.
+ *
+ * `defineCollections(client, { … })` wires a set of Lunora tables into live,
+ * auto-indexed TanStack DB collections (reads) plus a durable, retried
+ * offline-transactions outbox (writes) in one declaration. The lower-level
+ * helpers are exported for testing and advanced composition.
+ *
+ * Peer-depends on `@tanstack/db` and `@tanstack/offline-transactions`; the
+ * consuming app pins their versions and supplies React bindings
+ * (`@tanstack/react-db`) itself.
+ */
+type PlanWriter, type Row, VERSION, applyPlanToCollections, applyPlanToDb };

package/dist/index.mjs

@@ -1,6 +1 @@
-export { defineCollections } from './packem_shared/defineCollections-Cqtf9ffi.mjs';
-export { createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation, toMap } from './packem_shared/toMap-CRulWqZ7.mjs';
-
-const VERSION = "0.0.0";
-
-export { VERSION };
+import{applyPlanToCollections as r,applyPlanToDb as i}from"./packem_shared/applyPlanToCollections-C_eyqNF9.mjs";import{CHECKPOINT_FALLBACK_MS as a,createCheckpointRegistry as p,getShardCheckpoints as c,lunoraCollectionOptions as l,releaseShardCheckpoints as s}from"./packem_shared/CHECKPOINT_FALLBACK_MS-DVkxHO2j.mjs";import{defineCollections as O}from"./packem_shared/defineCollections-Cz4-m1Mp.mjs";import{DIRECT_TRANSACTION_METADATA_KEY as f,bindMutators as u,defineMutator as x,initMutators as A}from"./packem_shared/DIRECT_TRANSACTION_METADATA_KEY-O-hmqO42.mjs";import{OUTBOX_MUTATION_FN_NAME as m,createExecutorOutboxSink as E,createOptimisticOnlineDetector as _,makeDiffEmit as N,runOutboxMutation as S,toMap as d}from"./packem_shared/OUTBOX_MUTATION_FN_NAME-BfFCughR.mjs";const t="0.0.0";export{a as CHECKPOINT_FALLBACK_MS,f as DIRECT_TRANSACTION_METADATA_KEY,m as OUTBOX_MUTATION_FN_NAME,t as VERSION,r as applyPlanToCollections,i as applyPlanToDb,u as bindMutators,p as createCheckpointRegistry,E as createExecutorOutboxSink,_ as createOptimisticOnlineDetector,O as defineCollections,x as defineMutator,c as getShardCheckpoints,A as initMutators,l as lunoraCollectionOptions,N as makeDiffEmit,s as releaseShardCheckpoints,S as runOutboxMutation,d as toMap};

package/dist/mutators/index.d.mts

@@ -0,0 +1,5 @@
+export { type B as BindMutatorsContext, type a as BoundMutatorApi, type b as BoundMutators, type C as ClientMutatorContext, type c as ClientMutatorDef, type d as CollectionMap, type e as MutatorRejectedEvent, f as bindMutators, g as defineMutator, i as initMutators } from "../packem_shared/index.d-DrpzHIoj.mjs";
+import '@lunora/client';
+import '@tanstack/db';
+import "../packem_shared/collection-options.d-bmH3BTGq.mjs";
+import '@tanstack/offline-transactions';

package/dist/mutators/index.d.ts

@@ -0,0 +1,5 @@
+export { type B as BindMutatorsContext, type a as BoundMutatorApi, type b as BoundMutators, type C as ClientMutatorContext, type c as ClientMutatorDef, type d as CollectionMap, type e as MutatorRejectedEvent, f as bindMutators, g as defineMutator, i as initMutators } from "../packem_shared/index.d-DQsjGcjP.js";
+import '@lunora/client';
+import '@tanstack/db';
+import "../packem_shared/collection-options.d-bmH3BTGq.js";
+import '@tanstack/offline-transactions';

package/dist/mutators/index.mjs

@@ -0,0 +1 @@
+import{bindMutators as r,defineMutator as i,initMutators as a}from"../packem_shared/DIRECT_TRANSACTION_METADATA_KEY-O-hmqO42.mjs";export{r as bindMutators,i as defineMutator,a as initMutators};