@convex-localfirst/core 0.1.0

package/dist/manifest.d.ts

@@ -0,0 +1,84 @@
+import type { FunctionName, OperationPlan, RowValue, SyncScope, TableName } from "./types.js";
+/**
+ * Per-table conflict policy. Only REAL, server-enforced policies live here — declaring one
+ * that silently no-ops would be a footgun, so unimplemented options are not offered (they'd
+ * be a compile error, not a silent surprise).
+ *
+ * - `fieldLww` (default): field-level last-writer-wins. Patches are field-scoped deltas, so
+ *   concurrent edits to *different* fields both survive; same-field collisions resolve by
+ *   arrival order at the server. Free — falls out of `ctx.db.patch` + client replay.
+ * - `timestampLww`: same field-level merge, but same-field collisions resolve by the op's
+ *   logical timestamp (+ clientId tiebreaker) instead of arrival order — a NEWER edit wins
+ *   regardless of arrival, backed by per-field write clocks on the server. The offline-first fix.
+ *
+ * Orthogonal convergent merges are declared per FIELD, not as a whole-row policy:
+ * `setFields` (array add/remove) and `counterFields` (numeric increments). They compose with
+ * either policy above (delta fields are exempt from the LWW rule — they never clobber).
+ */
+export type ConflictPolicyName = "fieldLww" | "timestampLww";
+export type ScopeDefinition = {
+    readonly kind: "byUser";
+    readonly field: string;
+} | {
+    readonly kind: "byWorkspace";
+    readonly workspaceIdField: string;
+    readonly membershipTable: string;
+} | {
+    readonly kind: "byProject";
+    readonly projectIdField: string;
+    readonly membershipTable: string;
+};
+export type LocalTableDefinition = {
+    readonly table: TableName;
+    readonly idField: string;
+    readonly scope: ScopeDefinition;
+    readonly conflict: ConflictPolicyName;
+    readonly indexes: Record<string, readonly string[]>;
+    readonly setFields?: readonly string[];
+    readonly counterFields?: readonly string[];
+};
+export type LocalQueryContext = {
+    readonly now: number;
+};
+export type LocalQueryDefinition<TArgs = unknown, TResult = unknown> = {
+    readonly kind: "query";
+    readonly name: FunctionName;
+    readonly table: TableName;
+    readonly initial?: TResult;
+    readonly scope?: (args: TArgs) => SyncScope;
+    readonly run: (rows: readonly RowValue[], args: TArgs, context: LocalQueryContext) => TResult;
+};
+export type LocalMutationContext = {
+    readonly now: number;
+    readonly clientId: string;
+    readonly userId: string | null;
+    readonly localId: (table: TableName) => string;
+};
+export type LocalMutationDefinition<TArgs = unknown, TResult = unknown> = {
+    readonly kind: "mutation";
+    readonly name: FunctionName;
+    readonly table: TableName;
+    readonly serverResult?: TResult;
+    readonly plan: (args: TArgs, context: LocalMutationContext) => OperationPlan;
+};
+export type LocalFirstManifest = {
+    readonly schemaVersion: number;
+    readonly tables: Record<TableName, LocalTableDefinition>;
+    readonly queries: Record<FunctionName, LocalQueryDefinition<any, any>>;
+    readonly mutations: Record<FunctionName, LocalMutationDefinition<any, any>>;
+};
+export declare function defineLocalFirstManifest<T extends LocalFirstManifest>(manifest: T): T;
+export declare function localTable(definition: LocalTableDefinition): LocalTableDefinition;
+export declare function localQuery<TArgs, TResult>(definition: LocalQueryDefinition<TArgs, TResult>): LocalQueryDefinition<TArgs, TResult>;
+export declare function localMutation<TArgs, TResult = unknown>(definition: LocalMutationDefinition<TArgs, TResult>): LocalMutationDefinition<TArgs, TResult>;
+export declare function byUser(field: string): ScopeDefinition;
+export declare function byWorkspace(input: {
+    workspaceIdField: string;
+    membershipTable: string;
+}): ScopeDefinition;
+export declare function byProject(input: {
+    projectIdField: string;
+    membershipTable: string;
+}): ScopeDefinition;
+export declare function fieldLww(): ConflictPolicyName;
+export declare function timestampLww(): ConflictPolicyName;

package/dist/manifest.js

@@ -0,0 +1,28 @@
+export function defineLocalFirstManifest(manifest) {
+    return manifest;
+}
+export function localTable(definition) {
+    return definition;
+}
+export function localQuery(definition) {
+    return definition;
+}
+export function localMutation(definition) {
+    return definition;
+}
+export function byUser(field) {
+    return { kind: "byUser", field };
+}
+export function byWorkspace(input) {
+    return { kind: "byWorkspace", ...input };
+}
+export function byProject(input) {
+    return { kind: "byProject", ...input };
+}
+// These helpers tag a table with a conflict policy — see ConflictPolicyName for what each does.
+export function fieldLww() {
+    return "fieldLww";
+}
+export function timestampLww() {
+    return "timestampLww";
+}

package/dist/memoryStore.d.ts

@@ -0,0 +1,33 @@
+import type { LocalStore, StoreListener, StoreUnsubscribe } from "./storage.js";
+import type { Cursor, LocalId, LocalOperation, OperationStatus, RowValue, ScopeKey, ServerChange, TableName } from "./types.js";
+/**
+ * In-memory implementation of the canonical-centric store. The live view is
+ * never stored; it is derived on every read from the canonical snapshot plus a
+ * deterministic replay of the pending operation log (see Invariant I1).
+ */
+export declare class MemoryLocalStore implements LocalStore {
+    private readonly canonical;
+    private readonly operations;
+    private readonly cursors;
+    private readonly listeners;
+    getRows(table: TableName): Promise<readonly RowValue[]>;
+    getRow(table: TableName, id: LocalId): Promise<RowValue | null>;
+    getCanonicalRows(table: TableName): Promise<readonly RowValue[]>;
+    applyServerChange(change: ServerChange): Promise<void>;
+    applyServerChanges(changes: readonly ServerChange[]): Promise<void>;
+    private applyOne;
+    enqueueOperation(operation: LocalOperation): Promise<void>;
+    getPendingOperations(): Promise<readonly LocalOperation[]>;
+    getAllOperations(): Promise<readonly LocalOperation[]>;
+    getOperation(opId: string): Promise<LocalOperation | null>;
+    updateOperationStatus(opId: string, status: OperationStatus, error?: string): Promise<void>;
+    dropOperation(opId: string): Promise<void>;
+    getCursor(scopeKey: ScopeKey): Promise<Cursor>;
+    setCursor(scopeKey: ScopeKey, cursor: string): Promise<void>;
+    clear(): Promise<void>;
+    subscribe(listener: StoreListener): StoreUnsubscribe;
+    notify(): void;
+    /** Derive the live view for one table: canonical + deterministic replay of active ops. */
+    private deriveTable;
+    private tableMap;
+}

package/dist/memoryStore.js

@@ -0,0 +1,130 @@
+import { compareOperations } from "./ordering.js";
+import { deriveView, nextCanonicalRow } from "./view.js";
+function clone(value) {
+    // structuredClone (Node 18+/browsers) preserves the full Convex value range —
+    // int64 (bigint), bytes (ArrayBuffer), and `undefined` properties — which a
+    // JSON round-trip throws on or silently drops.
+    return structuredClone(value);
+}
+const OWED_STATUSES = new Set(["pending", "pushing"]);
+/**
+ * In-memory implementation of the canonical-centric store. The live view is
+ * never stored; it is derived on every read from the canonical snapshot plus a
+ * deterministic replay of the pending operation log (see Invariant I1).
+ */
+export class MemoryLocalStore {
+    canonical = new Map();
+    operations = new Map();
+    cursors = new Map();
+    listeners = new Set();
+    async getRows(table) {
+        return this.deriveTable(table).map(clone);
+    }
+    async getRow(table, id) {
+        const row = this.deriveTable(table).find((candidate) => candidate._id === id);
+        return row ? clone(row) : null;
+    }
+    async getCanonicalRows(table) {
+        return Array.from(this.tableMap(table).values()).map(clone);
+    }
+    async applyServerChange(change) {
+        this.applyOne(change);
+        this.notify();
+    }
+    async applyServerChanges(changes) {
+        if (changes.length === 0) {
+            return;
+        }
+        for (const change of changes) {
+            this.applyOne(change);
+        }
+        this.notify(); // one notify for the whole batch — see LocalStore.applyServerChanges
+    }
+    applyOne(change) {
+        const table = this.tableMap(change.table);
+        const next = nextCanonicalRow(table.get(change.id) ?? null, change);
+        if (next !== "stale") {
+            table.set(change.id, next);
+        }
+        // The op that produced this change is now part of canonical: stop replaying it.
+        if (change.opId) {
+            this.operations.delete(change.opId);
+        }
+    }
+    async enqueueOperation(operation) {
+        if (!this.operations.has(operation.opId)) {
+            this.operations.set(operation.opId, clone(operation));
+            this.notify();
+        }
+    }
+    async getPendingOperations() {
+        return Array.from(this.operations.values())
+            .filter((operation) => OWED_STATUSES.has(operation.status))
+            .sort(compareOperations)
+            .map(clone);
+    }
+    async getAllOperations() {
+        return Array.from(this.operations.values()).sort(compareOperations).map(clone);
+    }
+    async getOperation(opId) {
+        const operation = this.operations.get(opId);
+        return operation ? clone(operation) : null;
+    }
+    async updateOperationStatus(opId, status, error) {
+        const current = this.operations.get(opId);
+        if (!current) {
+            return;
+        }
+        this.operations.set(opId, { ...current, status, error });
+        this.notify();
+    }
+    async dropOperation(opId) {
+        if (this.operations.delete(opId)) {
+            this.notify();
+        }
+    }
+    async getCursor(scopeKey) {
+        return this.cursors.get(scopeKey) ?? null;
+    }
+    async setCursor(scopeKey, cursor) {
+        // Monotonic (I5): cursors only advance. Concurrent same-scope pulls (multiple
+        // mounted hooks + the reactive watch) can resolve out of order; a write that
+        // would move the cursor backward is ignored, since it would cause redundant
+        // re-delivery and destabilize the reactive resubscribe window.
+        const current = this.cursors.get(scopeKey);
+        if (current !== undefined && cursor <= current) {
+            return;
+        }
+        this.cursors.set(scopeKey, cursor);
+    }
+    async clear() {
+        this.canonical.clear();
+        this.operations.clear();
+        this.cursors.clear();
+        this.notify();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    notify() {
+        for (const listener of Array.from(this.listeners)) {
+            listener();
+        }
+    }
+    /** Derive the live view for one table: canonical + deterministic replay of active ops. */
+    deriveTable(table) {
+        return deriveView(table, Array.from(this.tableMap(table).values()), Array.from(this.operations.values()));
+    }
+    tableMap(table) {
+        const current = this.canonical.get(table);
+        if (current) {
+            return current;
+        }
+        const next = new Map();
+        this.canonical.set(table, next);
+        return next;
+    }
+}

package/dist/multiTab.d.ts

@@ -0,0 +1,69 @@
+import { type LockManagerLike } from "./leadership.js";
+import type { LocalStore } from "./storage.js";
+/** The slice of BroadcastChannel the cross-tab poke channel uses. */
+export type BroadcastChannelLike = {
+    postMessage(message: unknown): void;
+    close(): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+};
+/**
+ * Multi-tab sync coordination. Two independent jobs over one BroadcastChannel:
+ *
+ *  1. Leadership gate — elect a single leader among the tabs sharing this user's
+ *     local data; only the leader runs the engine's BACKGROUND batch push, so the
+ *     shared outbox is pushed once, not N times. (Pull/watch stay per-tab so every
+ *     tab still sees fresh data for its own scopes — no divergent-scope staleness.)
+ *
+ *  2. Cross-tab data poke — IndexedDB has no cross-tab change event, so whenever a
+ *     tab applies changes to the shared DB it broadcasts "changed"; the others
+ *     re-derive their mounted queries (pokeLocalChange).
+ *
+ * The leader does NOT re-push a follower's queued op on "changed": a follower pushes
+ * its OWN explicit mutations (pushSingleOperation is never gated) and flushes its own
+ * backlog on reconnect, so leader re-push would only DOUBLE-push an op the follower is
+ * already pushing — a concurrent same-opId race (idempotency TOCTOU + a call.server that
+ * the leader could prune out from under the follower). The leader's normal background
+ * push still drains anything genuinely stuck in the shared outbox.
+ */
+/** The slice of the engine the coordinator drives (keeps it unit-testable). */
+export type MultiTabEngine = {
+    setSyncEnabled(enabled: boolean): void;
+    pokeLocalChange(): void;
+    subscribe(listener: () => void): () => void;
+};
+/** The slice of TabLeadership the coordinator drives (so tests can inject a fake). */
+export type TabLeadershipLike = {
+    start(): Promise<void>;
+    stop(): void;
+    isLeader(): boolean;
+};
+export type MultiTabSyncOptions = {
+    /** Coordination boundary — tabs sharing the SAME local data (deployment + user) must
+     *  share this name and no others. The provider derives it from the authed user. */
+    readonly name: string;
+    /** Stable id for this tab (the engine's clientId). */
+    readonly id: string;
+    /** Injected for tests; defaults to a real BroadcastChannel. */
+    readonly createChannel?: (name: string) => BroadcastChannelLike;
+    /** Injected for tests; defaults to a real TabLeadership over the same lock name. */
+    readonly createLeadership?: (onChange: (isLeader: boolean) => void) => TabLeadershipLike;
+    /** Passed through to the default TabLeadership (Web Locks manager; null → this tab self-leads). */
+    readonly locks?: LockManagerLike | null;
+};
+/**
+ * The multi-tab coordination key for a store. It MUST equal the shared-data boundary so
+ * tabs over the SAME data elect one leader, and tabs over DIFFERENT data (a second
+ * deployment on one origin, or a different user) never elect a shared leader that can't
+ * drain the other's outbox. An IndexedDbStore's (databaseName, namespace) IS that
+ * partition (Rule 7: namespaced by deployment + authenticated user). Non-IndexedDb
+ * stores are per-instance (not shared across tabs), so the user id is a safe fallback.
+ * JSON-encoded so a ':' inside any segment can't merge two distinct boundaries into one.
+ */
+export declare function coordinationName(store: LocalStore | undefined, userId: string | null): string;
+/**
+ * Wire one engine into multi-tab coordination. Returns a dispose that tears down the
+ * channel + leadership and restores the engine to the un-gated (every-tab-sync) default.
+ */
+export declare function createMultiTabSync(engine: MultiTabEngine, options: MultiTabSyncOptions): () => void;

package/dist/multiTab.js

@@ -0,0 +1,96 @@
+import { IndexedDbStore } from "./indexedDbStore.js";
+import { TabLeadership } from "./leadership.js";
+/**
+ * The multi-tab coordination key for a store. It MUST equal the shared-data boundary so
+ * tabs over the SAME data elect one leader, and tabs over DIFFERENT data (a second
+ * deployment on one origin, or a different user) never elect a shared leader that can't
+ * drain the other's outbox. An IndexedDbStore's (databaseName, namespace) IS that
+ * partition (Rule 7: namespaced by deployment + authenticated user). Non-IndexedDb
+ * stores are per-instance (not shared across tabs), so the user id is a safe fallback.
+ * JSON-encoded so a ':' inside any segment can't merge two distinct boundaries into one.
+ */
+export function coordinationName(store, userId) {
+    if (store instanceof IndexedDbStore) {
+        return `idb:${JSON.stringify([store.options.databaseName, store.options.namespace])}`;
+    }
+    return `user:${JSON.stringify(userId ?? "anon")}`;
+}
+/**
+ * Wire one engine into multi-tab coordination. Returns a dispose that tears down the
+ * channel + leadership and restores the engine to the un-gated (every-tab-sync) default.
+ */
+export function createMultiTabSync(engine, options) {
+    const channelName = `convex-localfirst:multitab:${options.name}`;
+    const channelFactory = options.createChannel ?? ((name) => new BroadcastChannel(name));
+    const channel = channelFactory(channelName);
+    let stopped = false;
+    // Echo suppression: a received poke fires the store's listeners; without this flag
+    // that local notify would re-broadcast, ping-ponging "changed" between tabs forever.
+    let applyingPoke = false;
+    let broadcastQueued = false;
+    // 1) Leadership gates the background push.
+    const leadershipFactory = options.createLeadership ??
+        ((onChange) => new TabLeadership({
+            name: channelName,
+            id: options.id,
+            locks: options.locks,
+            onChange
+        }));
+    const leadership = leadershipFactory((isLeader) => {
+        if (!stopped) {
+            engine.setSyncEnabled(isLeader);
+        }
+    });
+    // Gate EVERY tab up front, then let leadership re-enable only the actual leader.
+    // TabLeadership fires onChange(true) when a tab BECOMES leader but never fires
+    // onChange(false) for a tab that merely starts as a follower (a queued Web Locks
+    // waiter that begins non-leader and only transitions if the holder releases).
+    // Without this, a follower keeps the engine's default syncEnabled=true and still runs
+    // the background batch push — defeating the single-leader invariant. setSyncEnabled is
+    // idempotent, and the leader's onChange(true) flips it back on.
+    engine.setSyncEnabled(false);
+    // 2) Cross-tab data poke. Broadcast on a genuine local change; on receipt every tab
+    //    re-derives from the shared store (pokeLocalChange). The leader does NOT re-push
+    //    here — see the header note (it would double-push an op the follower is pushing).
+    channel.onmessage = (event) => {
+        if (stopped) {
+            return;
+        }
+        const data = event.data;
+        if (data?.type !== "changed") {
+            return;
+        }
+        applyingPoke = true;
+        try {
+            engine.pokeLocalChange();
+        }
+        finally {
+            applyingPoke = false;
+        }
+    };
+    const unsubscribe = engine.subscribe(() => {
+        if (stopped || applyingPoke || broadcastQueued) {
+            return;
+        }
+        // Coalesce a burst of writes into ONE cross-tab poke per microtask.
+        broadcastQueued = true;
+        queueMicrotask(() => {
+            broadcastQueued = false;
+            if (!stopped) {
+                channel.postMessage({ type: "changed" });
+            }
+        });
+    });
+    void leadership.start();
+    return () => {
+        if (stopped) {
+            return;
+        }
+        stopped = true;
+        unsubscribe();
+        leadership.stop();
+        channel.close();
+        // A follower's engine was gated; restore the default so a remount/HMR isn't stuck off.
+        engine.setSyncEnabled(true);
+    };
+}

package/dist/mutationCall.d.ts

@@ -0,0 +1,20 @@
+import type { LocalCommit, MutationStatus } from "./types.js";
+export type LocalFirstMutationCall<T> = Promise<T> & {
+    readonly opId: string;
+    readonly local: Promise<LocalCommit>;
+    readonly server: Promise<T>;
+    readonly status: () => MutationStatus;
+};
+export declare function createLocalFirstMutationCall<T>(input: {
+    opId: string;
+    local: Promise<LocalCommit>;
+    server: Promise<T>;
+    status: () => MutationStatus;
+}): LocalFirstMutationCall<T>;
+/**
+ * Wrap a plain Convex mutation promise in the hybrid-call shape so useMutation
+ * has ONE return type. await behaves exactly like Convex (resolves to the server
+ * result); .local resolves immediately (nothing is stored locally for fallback);
+ * .server is the Convex promise. Fallback never breaks existing Convex code.
+ */
+export declare function createFallbackMutationCall<T>(promise: Promise<T>): LocalFirstMutationCall<T>;

package/dist/mutationCall.js

@@ -0,0 +1,40 @@
+export function createLocalFirstMutationCall(input) {
+    const promise = input.server;
+    Object.defineProperties(promise, {
+        opId: {
+            enumerable: true,
+            configurable: false,
+            value: input.opId
+        },
+        local: {
+            enumerable: true,
+            configurable: false,
+            value: input.local
+        },
+        server: {
+            enumerable: true,
+            configurable: false,
+            value: input.server
+        },
+        status: {
+            enumerable: false,
+            configurable: false,
+            value: input.status
+        }
+    });
+    return promise;
+}
+/**
+ * Wrap a plain Convex mutation promise in the hybrid-call shape so useMutation
+ * has ONE return type. await behaves exactly like Convex (resolves to the server
+ * result); .local resolves immediately (nothing is stored locally for fallback);
+ * .server is the Convex promise. Fallback never breaks existing Convex code.
+ */
+export function createFallbackMutationCall(promise) {
+    return createLocalFirstMutationCall({
+        opId: "convex-fallback",
+        local: promise.then(() => ({ opId: "convex-fallback", table: "", id: "", committedAt: 0 })),
+        server: promise,
+        status: () => ({ opId: "convex-fallback", status: "pushing" })
+    });
+}

package/dist/ordering.d.ts

@@ -0,0 +1,14 @@
+import type { LocalOperation } from "./types.js";
+/**
+ * Total, stable order for replaying pending operations (Invariant I4).
+ * Primary: creation time. Tiebreak: opId (lexicographic) so the order is
+ * identical across reloads, tabs, and repeated derivations.
+ */
+export declare function compareOperations(left: LocalOperation, right: LocalOperation): number;
+/**
+ * Stable comparison for client-side query order-by (the chainable `collection`
+ * builder and the declarative query interpreter). null/undefined sort LAST so a
+ * missing field never wins an ascending sort; numbers compare numerically; everything
+ * else compares by locale. One shared definition so the two query paths can't drift.
+ */
+export declare function compareValues(left: unknown, right: unknown): number;

package/dist/ordering.js

@@ -0,0 +1,35 @@
+/**
+ * Total, stable order for replaying pending operations (Invariant I4).
+ * Primary: creation time. Tiebreak: opId (lexicographic) so the order is
+ * identical across reloads, tabs, and repeated derivations.
+ */
+export function compareOperations(left, right) {
+    if (left.createdAt !== right.createdAt) {
+        return left.createdAt - right.createdAt;
+    }
+    if (left.opId < right.opId) {
+        return -1;
+    }
+    if (left.opId > right.opId) {
+        return 1;
+    }
+    return 0;
+}
+/**
+ * Stable comparison for client-side query order-by (the chainable `collection`
+ * builder and the declarative query interpreter). null/undefined sort LAST so a
+ * missing field never wins an ascending sort; numbers compare numerically; everything
+ * else compares by locale. One shared definition so the two query paths can't drift.
+ */
+export function compareValues(left, right) {
+    if (left == null && right == null)
+        return 0;
+    if (left == null)
+        return 1;
+    if (right == null)
+        return -1;
+    if (typeof left === "number" && typeof right === "number") {
+        return left - right;
+    }
+    return String(left).localeCompare(String(right));
+}

package/dist/rebase.d.ts

@@ -0,0 +1,14 @@
+import type { LocalOperation, RowValue, ServerChange } from "./types.js";
+export type RebaseInput = {
+    readonly canonicalRows: readonly RowValue[];
+    readonly serverChanges: readonly ServerChange[];
+    readonly pendingOperations: readonly LocalOperation[];
+};
+export type RebaseOutput = {
+    readonly rows: readonly RowValue[];
+    readonly conflicts: readonly {
+        opId: string;
+        message: string;
+    }[];
+};
+export declare function rebaseAndReplay(input: RebaseInput): RebaseOutput;

package/dist/rebase.js

@@ -0,0 +1,54 @@
+import { mergePatch } from "./setMerge.js";
+export function rebaseAndReplay(input) {
+    const rows = new Map();
+    const conflicts = [];
+    for (const row of input.canonicalRows) {
+        rows.set(`${row._table ?? ""}:${row._id}`, { ...row });
+    }
+    for (const change of input.serverChanges) {
+        const key = `${change.table}:${change.id}`;
+        if (change.kind === "delete") {
+            const current = rows.get(key) ?? { _id: change.id, _table: change.table };
+            rows.set(key, { ...current, _deleted: true, _version: change.version });
+            continue;
+        }
+        const current = rows.get(key) ?? { _id: change.id, _table: change.table };
+        // Server patches are pre-materialized (the server resolves set/counter deltas before
+        // appending), so this matches a plain spread today — but routing through mergePatch (the
+        // one shared apply rule, same as the pending-op path below) makes server changes delta-safe
+        // by construction, so a re-delivered or future delta-bearing change can never clobber.
+        const next = change.kind === "patch" ? mergePatch(current, change.patch ?? {}) : { ...current, ...change.value };
+        rows.set(key, { ...next, _id: change.id, _table: change.table, _version: change.version, _deleted: false });
+    }
+    for (const operation of input.pendingOperations) {
+        const key = `${operation.table}:${operation.id}`;
+        const current = rows.get(key);
+        if (operation.kind === "insert") {
+            rows.set(key, {
+                ...(operation.value ?? {}),
+                _id: operation.id,
+                _table: operation.table,
+                _pending: true,
+                _deleted: false
+            });
+            continue;
+        }
+        if (operation.kind === "patch") {
+            if (!current || current._deleted) {
+                conflicts.push({ opId: operation.opId, message: "Cannot replay patch over a missing row" });
+                continue;
+            }
+            // mergePatch set-merges any SetDelta field (declared set fields, computed at commit)
+            // and LWW-overwrites the rest — so a pending set-field add replays as a merge over
+            // the current value, not a clobber. For plain patches it's identical to a spread.
+            rows.set(key, { ...mergePatch(current, operation.patch ?? {}), _pending: true });
+            continue;
+        }
+        if (!current) {
+            conflicts.push({ opId: operation.opId, message: "Cannot replay delete over a missing row" });
+            continue;
+        }
+        rows.set(key, { ...current, _deleted: true, _pending: true });
+    }
+    return { rows: Array.from(rows.values()), conflicts };
+}

package/dist/relations.d.ts

@@ -0,0 +1,42 @@
+import type { RowValue } from "./types.js";
+/**
+ * Client-side relations for the local query builder. Because sync is scope-based
+ * (every authorized row is already on the device), a "join" is just an in-memory
+ * association across collections that are already local — no SQL, no extra round
+ * trip, reactive through the same store subscription. We do NOT compile relations
+ * to a serializable form (Zero/TanStack must, to drive query-driven sync); we
+ * resolve them locally, which is simpler and more flexible.
+ *
+ * Three shapes cover what an app like Linear needs:
+ *  - one          issue.project   (issue.projectId -> projects._id)
+ *  - many         issue.comments  (comments.issueId -> issue._id)
+ *  - manyToMany   issue.labels    (via an issue_labels join table)
+ */
+export type RelationSpec<_Target = unknown, _Many extends boolean = boolean> = {
+    readonly kind: "one" | "many" | "manyToMany";
+    readonly table: string;
+    /** one: the base row's FK field -> target._id. many: the target row's FK field -> base._id. */
+    readonly foreignKey: string;
+    /** manyToMany only: the join table and its two FK fields. */
+    readonly through?: string;
+    readonly localKey?: string;
+    readonly targetKey?: string;
+};
+/** base[foreignKey] === target._id. Returns the single target (or undefined). */
+export declare function one<Target extends Record<string, unknown> = RowValue>(table: string, foreignKey: string): RelationSpec<Target, false>;
+/** target[foreignKey] === base._id. Returns the matching targets as an array. */
+export declare function many<Target extends Record<string, unknown> = RowValue>(table: string, foreignKey: string): RelationSpec<Target, true>;
+/** base._id -> through[localKey], through[targetKey] -> target._id. Returns targets. */
+export declare function manyToMany<Target extends Record<string, unknown> = RowValue>(table: string, through: string, localKey: string, targetKey: string): RelationSpec<Target, true>;
+export type RelationEntry = {
+    readonly name: string;
+    readonly spec: RelationSpec;
+};
+/** Every table a set of relations reads from (targets + join tables). */
+export declare function relationTables(relations: readonly RelationEntry[]): string[];
+/**
+ * Attach related rows to each base row, in memory. `rowsByTable` must hold every
+ * relation's target (and `through`) table. Each relation is indexed once, so the
+ * whole attach is O(base + targets), not O(base × targets). Pure.
+ */
+export declare function attachRelations(baseRows: readonly Record<string, unknown>[], relations: readonly RelationEntry[], rowsByTable: Record<string, readonly RowValue[]>): Record<string, unknown>[];