@lunora/db 1.0.0-alpha.3 → 1.0.0-alpha.30

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

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

package/dist/collections/index.d.mts

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

package/dist/collections/index.d.ts

@@ -0,0 +1,5 @@
+export { type C as CheckpointRegistry, type L as LunoraCollectionConfig, type a as LunoraCollectionOptions, c as createCheckpointRegistry, l as lunoraCollectionOptions } from "../packem_shared/collection-options.d-C03Rjjxn.js";
+export { type C as CollectionDef, type I as InsertBinding, type L as LunoraDb, d as defineCollections } from "../packem_shared/define-collections.d-Ds-5C0M9.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-CtPxAU9J.mjs";import{defineCollections as n}from"../packem_shared/defineCollections-CnFdW1Ff.mjs";export{t as createCheckpointRegistry,n as defineCollections,r as lunoraCollectionOptions};

package/dist/index.d.mts

@@ -1,142 +1,82 @@
-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-C03Rjjxn.mjs";
+export { b as CHECKPOINT_FALLBACK_MS, type d as CheckpointFallbackEvent, type C as CheckpointRegistry, type e as CheckpointRegistryOptions, type f as CheckpointRegistryStats, type g as CheckpointWatermark, type E as ExecutorOutboxSinkOptions, type L as LunoraCollectionConfig, type a as LunoraCollectionOptions, O as OUTBOX_MUTATION_FN_NAME, type h as OutboxExecutor, type i as OutboxMutationMetadata, type S as SyncWriter, c as createCheckpointRegistry, j as createExecutorOutboxSink, k as createOptimisticOnlineDetector, m as getShardCheckpoints, l as lunoraCollectionOptions, n as makeDiffEmit, r as releaseShardCheckpoints, o as runOutboxMutation, s as shardCheckpointStats, t as toMap } from "./packem_shared/collection-options.d-C03Rjjxn.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-Y9AaX0yt.mjs";
+export { type B as BindMutatorsContext, type a as BoundMutators, type C as ClientMutatorContext, type b as ClientMutatorDef, D as DIRECT_TRANSACTION_METADATA_KEY, type M as MutatorReference, c as bindMutators, d as defineMutator } from "./packem_shared/define-mutators.d-tPb72T4I.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 { type ChangePlan, type PlanDelete, type PlanInsert, type PlanPatch, type PlanWriter, type Row, VERSION, applyPlanToCollections, applyPlanToDb };

package/dist/index.d.ts

@@ -1,142 +1,82 @@
-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-C03Rjjxn.js";
+export { b as CHECKPOINT_FALLBACK_MS, type d as CheckpointFallbackEvent, type C as CheckpointRegistry, type e as CheckpointRegistryOptions, type f as CheckpointRegistryStats, type g as CheckpointWatermark, type E as ExecutorOutboxSinkOptions, type L as LunoraCollectionConfig, type a as LunoraCollectionOptions, O as OUTBOX_MUTATION_FN_NAME, type h as OutboxExecutor, type i as OutboxMutationMetadata, type S as SyncWriter, c as createCheckpointRegistry, j as createExecutorOutboxSink, k as createOptimisticOnlineDetector, m as getShardCheckpoints, l as lunoraCollectionOptions, n as makeDiffEmit, r as releaseShardCheckpoints, o as runOutboxMutation, s as shardCheckpointStats, t as toMap } from "./packem_shared/collection-options.d-C03Rjjxn.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-Ds-5C0M9.js";
+export { type B as BindMutatorsContext, type a as BoundMutators, type C as ClientMutatorContext, type b as ClientMutatorDef, D as DIRECT_TRANSACTION_METADATA_KEY, type M as MutatorReference, c as bindMutators, d as defineMutator } from "./packem_shared/define-mutators.d-DqkWcDks.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 { type ChangePlan, type PlanDelete, type PlanInsert, type PlanPatch, type PlanWriter, type Row, VERSION, applyPlanToCollections, applyPlanToDb };

package/dist/index.mjs

@@ -1,6 +1 @@
-export { defineCollections } from './packem_shared/defineCollections-BAmslSrF.mjs';
-export { createOptimisticOnlineDetector, makeDiffEmit, runOutboxMutation, toMap } from './packem_shared/createOptimisticOnlineDetector-CRulWqZ7.mjs';
-
-const VERSION = "0.0.0";
-
-export { VERSION };
+import{applyPlanToCollections as r,applyPlanToDb as i}from"./packem_shared/applyPlanToCollections-C29s6OoX.mjs";import{CHECKPOINT_FALLBACK_MS as a,createCheckpointRegistry as p,getShardCheckpoints as c,lunoraCollectionOptions as l,releaseShardCheckpoints as s,shardCheckpointStats as C}from"./packem_shared/CHECKPOINT_FALLBACK_MS-CtPxAU9J.mjs";import{defineCollections as T}from"./packem_shared/defineCollections-CnFdW1Ff.mjs";import{DIRECT_TRANSACTION_METADATA_KEY as x,bindMutators as A,defineMutator as m}from"./packem_shared/DIRECT_TRANSACTION_METADATA_KEY-Cvm6vs5S.mjs";import{OUTBOX_MUTATION_FN_NAME as E,createExecutorOutboxSink as M,createOptimisticOnlineDetector as _,makeDiffEmit as h,runOutboxMutation as N,toMap as S}from"./packem_shared/OUTBOX_MUTATION_FN_NAME-CebgkYw2.mjs";const t="0.0.0";export{a as CHECKPOINT_FALLBACK_MS,x as DIRECT_TRANSACTION_METADATA_KEY,E as OUTBOX_MUTATION_FN_NAME,t as VERSION,r as applyPlanToCollections,i as applyPlanToDb,A as bindMutators,p as createCheckpointRegistry,M as createExecutorOutboxSink,_ as createOptimisticOnlineDetector,T as defineCollections,m as defineMutator,c as getShardCheckpoints,l as lunoraCollectionOptions,h as makeDiffEmit,s as releaseShardCheckpoints,N as runOutboxMutation,C as shardCheckpointStats,S as toMap};

package/dist/mutators/index.d.mts

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

package/dist/mutators/index.d.ts

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

package/dist/mutators/index.mjs

@@ -0,0 +1 @@
+import{bindMutators as r,defineMutator as e}from"../packem_shared/DIRECT_TRANSACTION_METADATA_KEY-Cvm6vs5S.mjs";export{r as bindMutators,e as defineMutator};

package/dist/packem_shared/CHECKPOINT_FALLBACK_MS-CtPxAU9J.mjs

@@ -0,0 +1 @@
+import{LunoraError as y}from"@lunora/errors";import{BTreeIndex as w}from"@tanstack/db";import{toMap as b,makeDiffEmit as C}from"./OUTBOX_MUTATION_FN_NAME-CebgkYw2.mjs";const v=()=>{let e=Number.NEGATIVE_INFINITY;const a=[];return{advance:n=>{if(!(n<=e)){e=n;for(let o=a.length-1;o>=0;o-=1){const r=a[o];r&&r.threshold<=e&&(r.resolve(),a.splice(o,1))}}},await:n=>n<=e?Promise.resolve():new Promise(o=>{a.push({resolve:o,threshold:n})}),passed:n=>n<=e,waiting:()=>a.length}},M=3e3;let I=!1;const N=e=>{I||(I=!0,console.warn(`[@lunora/db] released an optimistic overlay via the ${String(e.waitedMs)}ms checkpoint fallback: the server confirmed ${e.kind} ${String(e.watermark)} but no sync frame ever echoed it. A dropped shape poke or \`settled\` frame is the usual cause — inspect the subscription rather than raising \`fallbackMs\`. (Reported once per process.)`))},S=(e={})=>{const a=e.fallbackMs??M,n=e.onFallback??N,o=v(),r=v();let s=0;const c=new Set,h=(i,t)=>{for(const d of c)d.kind===i&&d.threshold<=t&&(clearTimeout(d.handle),c.delete(d))},l=(i,t)=>{if(a<=0)return;const d=i==="checkpoint"?o:r;if(d.passed(t))return;for(const u of c)if(u.kind===i&&u.threshold>=t)return;const p={handle:setTimeout(()=>{if(c.delete(p),!d.passed(t)){s+=1,d.advance(t);try{n({kind:i,waitedMs:a,watermark:t})}catch{}}},a),kind:i,threshold:t};c.add(p)};return{acknowledge:({checkpoint:i,mutationId:t})=>{i!==void 0&&l("checkpoint",i),t!==void 0&&l("mutationId",t)},awaitCheckpoint:i=>o.await(i),awaitMutationId:i=>r.await(i),resolve:({checkpoint:i,mutationId:t})=>{i!==void 0&&(o.advance(i),h("checkpoint",i)),t!==void 0&&(r.advance(t),h("mutationId",t))},stats:()=>({fallbacks:s,pendingCheckpointWaiters:o.waiting(),pendingMutationWaiters:r.waiting()})}},m=new WeakMap,T=(e,a,n)=>{let o=m.get(e);o||(o=new Map,m.set(e,o));const r=a??"",s=o.get(r);if(s)return s;const c=S(n);return o.set(r,c),c},g=new WeakSet,E=e=>{g.add(e)},R=e=>g.has(e),x=e=>{const a=m.get(e);if(a){for(const n of a.values())n.resolve({checkpoint:Number.POSITIVE_INFINITY,mutationId:Number.POSITIVE_INFINITY});m.delete(e)}},F=e=>{const a=m.get(e),n={};if(a)for(const[o,r]of a)n[o]=r.stats();return n},O=e=>{if(e.list===void 0==(e.shape===void 0))throw new y("INTERNAL","lunoraCollectionOptions: pass exactly one of `list` or `shape`");const a=e.getKey??(t=>t._id),n=e.checkpoints??T(e.client,e.shape?.shardKey??e.shardKey);E(n);const o=new Map;let r,s,c,h;const l=(t,d)=>{const p=k=>{r?.(b(k,a)),d?.(),e.shape===void 0&&n.resolve({mutationId:e.client.confirmedMutationWatermark(e.shardKey)})},u=k=>c?.(k),f=k=>{n.resolve(k)};return e.shape!==void 0?e.client.subscribeShape({args:t,name:e.shape.name},p,{onCheckpoint:f,onError:u,shardKey:e.shape.shardKey}):e.client.subscribe(e.list,t,p,{onCheckpoint:f,onError:u,shardKey:e.shardKey})},i={autoIndex:"eager",defaultIndexType:w,getKey:a,id:e.id??e.list?.__lunoraRef??`shape:${e.shape?.name??""}`,...e.load==="eager"?{startSync:!0}:{},sync:{sync:t=>(r=C(o,t),c=d=>{t.markReady(),e.onError?.(d)},e.scopeBy===void 0?s=l(e.shape?.args??{},()=>{t.markReady()}):(t.markReady(),h!==void 0&&(s=l(h,void 0))),()=>{r=void 0,c=void 0,s?.(),s=void 0,o.clear()})}};return{checkpoints:n,config:i,scope:t=>{e.scopeBy!==void 0&&(h=t,s?.(),s=void 0,r?.(new Map),t!==void 0&&r!==void 0&&(s=l(t,void 0)))}}};export{M as CHECKPOINT_FALLBACK_MS,S as createCheckpointRegistry,T as getShardCheckpoints,R as hasCheckpointsAttached,O as lunoraCollectionOptions,E as markCheckpointsAttached,x as releaseShardCheckpoints,F as shardCheckpointStats};

package/dist/packem_shared/DIRECT_TRANSACTION_METADATA_KEY-Cvm6vs5S.mjs

@@ -0,0 +1 @@
+import{LunoraError as l}from"@lunora/errors";import{createTransaction as y}from"@tanstack/db";import{getShardCheckpoints as R,hasCheckpointsAttached as M}from"./CHECKPOINT_FALLBACK_MS-CtPxAU9J.mjs";import{runOutboxMutation as _}from"./OUTBOX_MUTATION_FN_NAME-CebgkYw2.mjs";const w="__tanstack_db_direct",A="defineMutator: `serverRef` must be a generated mutator reference (api.mutators.*) or a 'namespace:fn' string",g=e=>{const t=typeof e=="string"?e:e?.__lunoraRef;if(typeof t!="string"||t.length===0)throw new l("INTERNAL",A);return t},E=e=>({__lunoraClientMutator:!0,apply:e.apply,serverRef:g(e.serverRef)}),I=(e,t,m)=>{let c=0;const p=()=>(c=Math.max(c,e.confirmedMutationWatermark(t.shardKey))+1,c);let u=Promise.resolve();const d=(r,o)=>{const a=u.then(async()=>{for(let s=0;;s+=1){const n=p(),{applied:i}=await e.callMutator(r,o,{clientSeq:n,shardKey:t.shardKey});if(i)return n;if(s>=32)throw new l("INTERNAL",`lunora: custom mutator "${r}" could not claim a fresh client sequence after ${String(32)} attempts`)}});return u=a.then(()=>{},()=>{}),a},h=()=>{if(t.checkpoints===!1)return;if(t.checkpoints)return t.checkpoints;const r=R(e,t.shardKey);return M(r)?r:void 0},f={};for(const[r,o]of Object.entries(m))f[r]=a=>{const s=y({autoCommit:!0,metadata:{[w]:!0,serverRef:o.serverRef},mutationFn:async()=>{let n=0;await _(async()=>{n=await d(o.serverRef,a)});const i=h();i&&(i.acknowledge({mutationId:n}),await i.awaitMutationId(n))}});return s.mutate(()=>{o.apply({collections:t.collections},a)}),s};return f};export{w as DIRECT_TRANSACTION_METADATA_KEY,I as bindMutators,E as defineMutator};

package/dist/packem_shared/OUTBOX_MUTATION_FN_NAME-CebgkYw2.mjs

@@ -0,0 +1 @@
+import{createCollection as f,safeRandomUUID as m}from"@tanstack/db";import{NonRetriableError as y}from"@tanstack/offline-transactions";const p=1e3,d="__lunora_outbox__",l=new WeakMap,w=()=>f({getKey:e=>e._id,id:`${d}:${m()}`,startSync:!0,sync:{sync:e=>(e.markReady(),()=>{})}}),x=(e,t)=>{l.set(e,t)};let u=!1;const g=(e,t={})=>{const r=t.maxItems??1e3,n=t.mutationFnName??d;return{enqueue(o){if(e.getPendingCount()>=r){const c=new Error("offline outbox is full");return c.code="OFFLINE_QUEUE_OVERFLOW",Promise.reject(c)}const i={args:o.args,clientId:o.clientId,functionPath:o.functionPath,idempotencyKey:o.idempotencyKey,identity:o.identity,mutationId:o.mutationId,shardKey:o.shardKey},a=l.get(e);!a&&!u&&(u=!0,console.warn("[@lunora/db] createExecutorOutboxSink: no outbox carrier is registered for this executor. On a TanStack OfflineExecutor a zero-mutation transaction is silently dropped, so offline writes may be lost — wire the sink to the executor returned by defineCollections()."));const s=e.createOfflineTransaction({autoCommit:!1,idempotencyKey:o.idempotencyKey,metadata:i,mutationFnName:n});return s.mutate(()=>{a?.insert({_id:o.idempotencyKey})}),s.commit?.().catch(()=>{}),Promise.resolve()}}},h=(e,t)=>{const r=new Map;for(const n of e)r.set(t(n),n);return r},E=(e,t)=>r=>{t.begin();const n=new Map;for(const[o,i]of r){const a=JSON.stringify(i);n.set(o,a),e.has(o)?e.get(o)!==a&&t.write({type:"update",value:i}):t.write({type:"insert",value:i})}for(const o of e.keys())r.has(o)||t.write({key:o,type:"delete"});t.commit(),e.clear();for(const[o,i]of n)e.set(o,i)},_=async e=>{try{await e()}catch(t){if(typeof t.code=="string"){const r=new y(t instanceof Error?t.message:String(t));throw r.code=t.code,r}throw t}},I=()=>{const e=new Set;return{dispose:()=>{for(const t of e)clearInterval(t);e.clear()},isOnline:()=>!0,notifyOnline:()=>{},subscribe:t=>{const r=setInterval(t,p);return e.add(r),()=>{clearInterval(r),e.delete(r)}}}};export{d as OUTBOX_MUTATION_FN_NAME,g as createExecutorOutboxSink,I as createOptimisticOnlineDetector,w as createOutboxCarrier,E as makeDiffEmit,x as registerOutboxCarrier,_ as runOutboxMutation,h as toMap};

package/dist/packem_shared/applyPlanToCollections-C29s6OoX.mjs

@@ -0,0 +1 @@
+const l=t=>({deletes:t.deletes??[],inserts:t.inserts??[],patches:t.patches??[]}),r=(t,o)=>{const{deletes:n,inserts:i,patches:a}=l(o);for(const e of n)t[e.table]?.delete(e.id);for(const e of a){const s=t[e.table];s&&s.update(e.id,c=>{Object.assign(c,e.fields)})}for(const e of i){const s=t[e.table];if(s){if(typeof e.row._id!="string")throw new TypeError(`applyPlanToCollections: insert into "${e.table}" needs an "_id" — mint it client-side so the optimistic row keys match the persisted one`);s.insert(e.row)}}},d=async(t,o)=>{const{deletes:n,inserts:i,patches:a}=l(o);for(const e of n)await t.delete(e.id);for(const e of a)await t.patch(e.id,e.fields);for(const e of i){const{_id:s,...c}=e.row;await t.insert(e.table,c,...typeof s=="string"?[{clientId:s}]:[])}};export{r as applyPlanToCollections,d as applyPlanToDb};