@convex-localfirst/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fanzzzd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @convex-localfirst/server
+
+The Convex-side DSL for local-first tables. Declare which tables are local-first with
+`lf.table`, and generate the sync `push`/`pull` functions with `createSyncFunctions` — the
+server enforces scope, ownership, membership, and idempotency. Convex stays authoritative.
+
+```bash
+npm install @convex-localfirst/server
+```
+
+```ts
+import { lf } from "./localfirst";
+import { v } from "convex/values";
+
+const todos = lf.table("todos", {
+  scope: lf.byUser("ownerId"),
+  idField: "localId",
+  conflict: lf.fieldLww(),
+  indexes: { byList: ["ownerId", "listId", "createdAt"] }
+});
+
+export const list = todos.query({ args: { listId: v.string() }, index: "byList", initial: [] });
+export const create = todos.insert({ args: { text: v.string() }, value: ({ auth, args, now }) => ({ ... }) });
+```
+
+Peer dependency: `convex`. MIT

package/dist/createSyncFunctions.d.ts

@@ -0,0 +1,58 @@
+import type { RegisteredMutation, RegisteredQuery } from "convex/server";
+import type { SyncConfig } from "./serverSync.js";
+type AnyCtx = any;
+type ComponentApi = any;
+/** App-supplied membership check (the server decides, never the client — I7). */
+export type IsMember = (ctx: AnyCtx, info: {
+    userId: string;
+    scopeValue: string;
+    membershipTable: string;
+}) => Promise<boolean>;
+export type CreateSyncFunctionsOptions = {
+    /** `components.convexLocalFirst` from your app's generated api. */
+    readonly component: ComponentApi;
+    /** `mutation` / `query` from your app's `_generated/server`. */
+    readonly mutation: (definition: {
+        args: any;
+        handler: (ctx: AnyCtx, args: any) => any;
+    }) => any;
+    readonly query: (definition: {
+        args: any;
+        handler: (ctx: AnyCtx, args: any) => any;
+    }) => any;
+    /** Which app tables are local-first, and how they are scoped. */
+    readonly tables: SyncConfig["tables"];
+    readonly schemaVersion?: number;
+    readonly now?: () => number;
+    /** Required if any table is scoped `byWorkspace` / `byProject`. */
+    readonly isMember?: IsMember;
+    /**
+     * UNSAFE. When Convex auth returns no identity, trust the client-supplied
+     * `userId` instead of failing closed. Only for a local demo backend with no
+     * auth provider — NEVER in production (any client could read another user's
+     * data, violating I7). Defaults to false (fail closed).
+     */
+    readonly devUnsafeAllowClientUserId?: boolean;
+};
+/** The two endpoints local-first clients talk to. Opaque to app code — they are
+ *  driven by the client transport, not called via `useMutation`/`useQuery`. */
+export type SyncFunctions = {
+    readonly push: RegisteredMutation<"public", Record<string, unknown>, unknown>;
+    readonly pull: RegisteredQuery<"public", Record<string, unknown>, unknown>;
+};
+/**
+ * Compose the `push` mutation + `pull` query that local-first clients sync
+ * against. App rows go to `ctx.db`; every sync bookkeeping operation is
+ * delegated to the mounted component. This replaces ~150 lines of hand-written
+ * `ServerStore` wiring with a single call.
+ *
+ * ```ts
+ * export const { push, pull } = createSyncFunctions({
+ *   component: components.convexLocalFirst,
+ *   mutation, query,
+ *   tables: { todos: { scope: { kind: "byUser", field: "ownerId" }, idField: "localId", conflict: "fieldLww" } }
+ * });
+ * ```
+ */
+export declare function createSyncFunctions(options: CreateSyncFunctionsOptions): SyncFunctions;
+export {};

package/dist/createSyncFunctions.js

@@ -0,0 +1,241 @@
+import { convexToJson, jsonToConvex, v } from "convex/values";
+import { handlePull, handlePush } from "./serverSync.js";
+// Lossless Convex-value <-> JSON-string codec for the component's text columns.
+// convexToJson/jsonToConvex preserve bigint/bytes/nested-undefined where JSON.stringify
+// would throw or change shape; plain JSON values pass through unchanged (back-compatible
+// with rows written before this codec existed). Top-level undefined is not a Convex
+// value, so it maps to null (call sites only encode present values anyway).
+const valueCodec = {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    encode: (value) => JSON.stringify(convexToJson((value === undefined ? null : value))),
+    decode: (json) => jsonToConvex(JSON.parse(json))
+};
+function storedFromComponent(r) {
+    return {
+        changeId: r.changeId,
+        scopeKey: r.scopeKey,
+        table: r.table,
+        localId: r.localId,
+        kind: r.kind,
+        data: r.dataJson ? valueCodec.decode(r.dataJson) : undefined,
+        patch: r.patchJson ? valueCodec.decode(r.patchJson) : undefined,
+        version: r.version,
+        serverTime: r.serverTime,
+        opId: r.opId
+    };
+}
+/**
+ * Compose the `push` mutation + `pull` query that local-first clients sync
+ * against. App rows go to `ctx.db`; every sync bookkeeping operation is
+ * delegated to the mounted component. This replaces ~150 lines of hand-written
+ * `ServerStore` wiring with a single call.
+ *
+ * ```ts
+ * export const { push, pull } = createSyncFunctions({
+ *   component: components.convexLocalFirst,
+ *   mutation, query,
+ *   tables: { todos: { scope: { kind: "byUser", field: "ownerId" }, idField: "localId", conflict: "fieldLww" } }
+ * });
+ * ```
+ */
+export function createSyncFunctions(options) {
+    const lf = options.component;
+    const config = {
+        schemaVersion: options.schemaVersion ?? 1,
+        now: options.now ?? (() => Date.now()),
+        tables: options.tables,
+        valueCodec
+    };
+    // I7: the pull side resolves ONE membership table per scope kind (scope keys
+    // are per-value, shared across every table of that kind). Mixed membership
+    // tables within a kind would let a member of one pull another's rows — forbid
+    // that ambiguity at config time rather than fail silently insecure.
+    for (const kind of ["byWorkspace", "byProject"]) {
+        const membershipTables = new Set(Object.values(options.tables)
+            .filter((t) => t.scope.kind === kind)
+            .map((t) => t.scope.membershipTable));
+        if (membershipTables.size > 1) {
+            throw new Error(`createSyncFunctions: all ${kind} tables must share one membershipTable (found: ${[...membershipTables].join(", ")}). Scope keys are shared per value, so mixed membership tables would cross-authorize reads.`);
+        }
+    }
+    const needsMembership = Object.values(options.tables).some((t) => t.scope.kind === "byWorkspace" || t.scope.kind === "byProject");
+    const isMember = options.isMember ??
+        (async () => {
+            if (needsMembership) {
+                throw new Error("createSyncFunctions: a byWorkspace/byProject table requires an `isMember` callback (the server must decide membership — I7).");
+            }
+            return true;
+        });
+    // Push-side store: app rows hit ctx.db; all bookkeeping goes to the component.
+    function pushStore(ctx) {
+        return {
+            async getRow(_table, serverId) {
+                return (await ctx.db.get(serverId)) ?? null;
+            },
+            async insertRow(table, data) {
+                return await ctx.db.insert(table, data);
+            },
+            async patchRow(_table, serverId, patch) {
+                await ctx.db.patch(serverId, patch);
+            },
+            async deleteRow(_table, serverId) {
+                await ctx.db.delete(serverId);
+            },
+            async getLedger(userId, opId) {
+                return await ctx.runQuery(lf.ops.getByOpId, { userId, opId });
+            },
+            async putLedger(userId, clientId, op, entry) {
+                await ctx.runMutation(lf.ops.record, {
+                    userId,
+                    clientId,
+                    opId: op.opId,
+                    schemaVersion: op.schemaVersion,
+                    functionName: op.functionName,
+                    table: op.table,
+                    localId: op.localId,
+                    status: entry.status,
+                    argsJson: valueCodec.encode(op.value ?? op.patch ?? {}),
+                    operationJson: valueCodec.encode(op),
+                    resultJson: entry.resultJson,
+                    changesJson: entry.changesJson,
+                    error: entry.error,
+                    committedAt: config.now ? config.now() : Date.now()
+                });
+            },
+            async getServerId(table, localId) {
+                return await ctx.runQuery(lf.idMaps.get, { table, localId });
+            },
+            async putIdMap(userId, table, localId, serverId) {
+                await ctx.runMutation(lf.idMaps.put, { userId, table, localId, serverId });
+            },
+            async appendChange(change) {
+                return await ctx.runMutation(lf.changes.append, {
+                    scopeKey: change.scopeKey,
+                    table: change.table,
+                    localId: change.localId,
+                    kind: change.kind,
+                    dataJson: change.data ? valueCodec.encode(change.data) : undefined,
+                    patchJson: change.patch ? valueCodec.encode(change.patch) : undefined,
+                    version: change.version,
+                    serverTime: change.serverTime,
+                    opId: change.opId
+                });
+            },
+            async changesAfter(scopeKey, cursor, limit) {
+                const rows = await ctx.runQuery(lf.changes.listAfter, { scopeKey, cursor: cursor ?? undefined, limit });
+                return rows.map(storedFromComponent);
+            },
+            async latestChangeVersion(table, localId) {
+                return await ctx.runQuery(lf.changes.latestVersion, { table, localId });
+            },
+            async scopeForLocalId(table, localId) {
+                return await ctx.runQuery(lf.changes.scopeForLocal, { table, localId });
+            },
+            // Per-field write clocks for `timestampLww` tables. clocks is a plain JSON map
+            // (field -> {ts, tiebreaker}: number + string), so JSON.stringify/parse is lossless —
+            // no valueCodec needed. Absent these two, serverSync rejects a timestamped timestampLww
+            // op (loud) rather than silently degrading to arrival-order.
+            async getFieldClocks(table, localId) {
+                const json = await ctx.runQuery(lf.fieldClocks.get, { table, localId });
+                return json ? JSON.parse(json) : {};
+            },
+            async putFieldClocks(table, localId, clocks) {
+                await ctx.runMutation(lf.fieldClocks.put, { table, localId, clocksJson: JSON.stringify(clocks) });
+            },
+            async isMember(userId, scopeValue, membershipTable) {
+                return await isMember(ctx, { userId, scopeValue, membershipTable });
+            }
+        };
+    }
+    // Pull-side store: read-only, so only the change log + membership are wired.
+    function pullStore(ctx) {
+        const unsupported = () => {
+            throw new Error("pull is read-only");
+        };
+        return {
+            getRow: unsupported,
+            insertRow: unsupported,
+            patchRow: unsupported,
+            deleteRow: unsupported,
+            getLedger: unsupported,
+            putLedger: unsupported,
+            getServerId: unsupported,
+            putIdMap: unsupported,
+            appendChange: unsupported,
+            latestChangeVersion: unsupported,
+            scopeForLocalId: unsupported,
+            async changesAfter(scopeKey, cursor, limit) {
+                const rows = await ctx.runQuery(lf.changes.listAfter, { scopeKey, cursor: cursor ?? undefined, limit });
+                return rows.map(storedFromComponent);
+            },
+            async isMember(userId, scopeValue, membershipTable) {
+                return await isMember(ctx, { userId, scopeValue, membershipTable });
+            }
+        };
+    }
+    const mutationFields = {
+        opId: v.string(),
+        clientId: v.string(),
+        schemaVersion: v.number(),
+        functionName: v.string(),
+        table: v.string(),
+        kind: v.union(v.literal("insert"), v.literal("patch"), v.literal("delete")),
+        localId: v.string(),
+        value: v.optional(v.any()),
+        patch: v.optional(v.any()),
+        // The op's logical timestamp (client monotonic clock). Optional — only `timestampLww`
+        // tables read it; older clients that omit it fall back to arrival-order LWW.
+        timestamp: v.optional(v.number())
+    };
+    async function resolveUserId(ctx, fallback) {
+        // I7: identity comes from auth, never the client. Fail closed when there is
+        // no authenticated identity, unless the app explicitly opts into the unsafe
+        // demo fallback (a local backend with no auth provider).
+        const identity = await ctx.auth.getUserIdentity();
+        if (identity?.subject) {
+            return identity.subject;
+        }
+        if (options.devUnsafeAllowClientUserId) {
+            return fallback;
+        }
+        throw new Error("convex-localfirst: no authenticated identity. Configure Convex auth, or set devUnsafeAllowClientUserId: true for a local demo backend (unsafe).");
+    }
+    const push = options.mutation({
+        args: {
+            clientId: v.string(),
+            userId: v.string(),
+            schemaVersion: v.number(),
+            mutations: v.array(v.object(mutationFields))
+        },
+        handler: async (ctx, args) => {
+            const userId = await resolveUserId(ctx, args.userId);
+            return await handlePush(pushStore(ctx), config, {
+                userId,
+                clientId: args.clientId,
+                schemaVersion: args.schemaVersion,
+                mutations: args.mutations
+            });
+        }
+    });
+    const pull = options.query({
+        args: {
+            clientId: v.string(),
+            userId: v.string(),
+            schemaVersion: v.number(),
+            scopes: v.array(v.object({ kind: v.string(), value: v.optional(v.string()) })),
+            cursors: v.any()
+        },
+        handler: async (ctx, args) => {
+            const userId = await resolveUserId(ctx, args.userId);
+            return await handlePull(pullStore(ctx), config, {
+                userId,
+                clientId: args.clientId,
+                schemaVersion: args.schemaVersion,
+                scopes: args.scopes,
+                cursors: args.cursors ?? {}
+            });
+        }
+    });
+    return { push, pull };
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import type { DataModelFromSchemaDefinition, DocumentByName, GenericSchema, RegisteredMutation, RegisteredQuery, SchemaDefinition, TableNamesInDataModel } from "convex/server";
+import type { ObjectType, PropertyValidators } from "convex/values";
+import type { ConflictPolicyName, ScopeDefinition } from "@convex-localfirst/core";
+import type { ServerTableConfig } from "./serverSync.js";
+export * from "./serverSync.js";
+export * from "./createSyncFunctions.js";
+export type CreateLocalFirstOptions<Schema extends SchemaDefinition<GenericSchema, boolean>> = {
+    readonly schema: Schema;
+    readonly defaults?: {
+        readonly idField?: string;
+        readonly conflict?: ConflictPolicyName;
+    };
+};
+export type TableOptions = {
+    readonly scope: ScopeDefinition;
+    readonly idField?: string;
+    readonly conflict?: ConflictPolicyName;
+    readonly indexes?: Record<string, readonly string[]>;
+    readonly setFields?: readonly string[];
+    readonly counterFields?: readonly string[];
+};
+export type QuerySpec<A extends PropertyValidators, Row> = {
+    readonly args: A;
+    readonly index: string;
+    readonly key: (input: {
+        auth: {
+            userId: string;
+        };
+        args: ObjectType<A>;
+    }) => readonly unknown[];
+    readonly order?: "asc" | "desc";
+    readonly initial?: Row[];
+};
+export type InsertSpec<A extends PropertyValidators, Ctx> = {
+    readonly args: A;
+    readonly value: (input: {
+        ctx: Ctx;
+        auth: {
+            userId: string;
+        };
+        args: ObjectType<A>;
+        now: number;
+        localId: string;
+    }) => Record<string, unknown>;
+};
+export type PatchSpec<A extends PropertyValidators, Ctx> = {
+    readonly args: A;
+    readonly id?: (input: {
+        args: ObjectType<A>;
+    }) => string;
+    readonly patch?: (input: {
+        ctx: Ctx;
+        auth: {
+            userId: string;
+        };
+        args: ObjectType<A>;
+        now: number;
+    }) => Record<string, unknown>;
+};
+export type RemoveSpec<A extends PropertyValidators> = {
+    readonly args: A;
+    readonly id?: (input: {
+        args: ObjectType<A>;
+    }) => string;
+};
+export declare function createLocalFirst<Ctx = unknown, Schema extends SchemaDefinition<GenericSchema, boolean> = SchemaDefinition<GenericSchema, boolean>>(options: CreateLocalFirstOptions<Schema>): {
+    byUser(field: string): ScopeDefinition;
+    byWorkspace(input: {
+        workspaceIdField: string;
+        membershipTable: string;
+    }): ScopeDefinition;
+    byProject(input: {
+        projectIdField: string;
+        membershipTable: string;
+    }): ScopeDefinition;
+    fieldLww(): ConflictPolicyName;
+    /** Timestamp-ordered LWW: a scalar field-write carries the op's logical timestamp +
+     *  clientId tiebreaker, so a NEWER edit wins regardless of arrival order (the offline-first
+     *  fix). Set/counter delta fields stay convergent and are exempt. Requires the bundled
+     *  component (or a store implementing get/putFieldClocks). */
+    timestampLww(): ConflictPolicyName;
+    table<T extends TableNamesInDataModel<DataModelFromSchemaDefinition<Schema>>>(tableName: T, tableOptions: TableOptions): {
+        query<A extends PropertyValidators>(spec: QuerySpec<A, DocumentByName<DataModelFromSchemaDefinition<Schema>, T>>): RegisteredQuery<"public", ObjectType<A>, DocumentByName<DataModelFromSchemaDefinition<Schema>, T>[]>;
+        insert<A extends PropertyValidators>(spec: InsertSpec<A, Ctx>): RegisteredMutation<"public", ObjectType<A>, null>;
+        patch<A extends PropertyValidators>(spec: PatchSpec<A, Ctx>): RegisteredMutation<"public", ObjectType<A>, null>;
+        remove<A extends PropertyValidators>(spec: RemoveSpec<A>): RegisteredMutation<"public", ObjectType<A>, null>;
+    };
+};
+/**
+ * Derive the `createSyncFunctions({ tables })` config from your imported `lf.table`
+ * modules, so scope / idField / conflict live in ONE place instead of being restated (and
+ * drifting) in `sync.ts`:
+ *
+ * ```ts
+ * import * as issues from "./issues";
+ * import * as labels from "./labels";
+ * export const { push, pull } = createSyncFunctions({
+ *   component: components.convexLocalFirst, mutation, query,
+ *   tables: collectTables({ issues, labels }),
+ *   isMember
+ * });
+ * ```
+ *
+ * Throws if two functions of one table carry conflicting config, or if no local-first
+ * tables are found.
+ */
+export declare function collectTables(modules: Record<string, unknown>): Record<string, ServerTableConfig>;

package/dist/index.js

@@ -0,0 +1,148 @@
+import { mutationGeneric as mutation, queryGeneric as query } from "convex/server";
+export * from "./serverSync.js";
+export * from "./createSyncFunctions.js";
+// Non-enumerable key under which each lf.table fn carries its sync config (scope /
+// idField / conflict / …). Shared by attachMetadata (writer) and collectTables
+// (reader) so the magic string lives in exactly one place.
+const LF_METADATA_KEY = "__convexLocalFirst";
+export function createLocalFirst(options) {
+    return {
+        byUser(field) {
+            return { kind: "byUser", field };
+        },
+        byWorkspace(input) {
+            return { kind: "byWorkspace", ...input };
+        },
+        byProject(input) {
+            return { kind: "byProject", ...input };
+        },
+        fieldLww() {
+            return "fieldLww";
+        },
+        /** Timestamp-ordered LWW: a scalar field-write carries the op's logical timestamp +
+         *  clientId tiebreaker, so a NEWER edit wins regardless of arrival order (the offline-first
+         *  fix). Set/counter delta fields stay convergent and are exempt. Requires the bundled
+         *  component (or a store implementing get/putFieldClocks). */
+        timestampLww() {
+            return "timestampLww";
+        },
+        table(tableName, tableOptions) {
+            const idField = tableOptions.idField ?? options.defaults?.idField ?? "localId";
+            const conflict = tableOptions.conflict ?? options.defaults?.conflict ?? "fieldLww";
+            const metadata = {
+                tableName,
+                idField,
+                conflict,
+                scope: tableOptions.scope,
+                indexes: tableOptions.indexes ?? {},
+                setFields: tableOptions.setFields,
+                counterFields: tableOptions.counterFields
+            };
+            return {
+                query(spec) {
+                    const fn = query({
+                        args: spec.args,
+                        handler: async () => unsupportedLocalFirstCall("query", tableName)
+                    });
+                    // ponytail: the handler throws by design (local-first reads run on the
+                    // client); the declared return type is what the engine actually
+                    // delivers, so we assert it here rather than leak `never` to callers.
+                    return attachMetadata(fn, { kind: "query", ...metadata, spec });
+                },
+                insert(spec) {
+                    const fn = mutation({
+                        args: spec.args,
+                        handler: async () => unsupportedLocalFirstCall("insert", tableName)
+                    });
+                    return attachMetadata(fn, { kind: "insert", ...metadata, spec });
+                },
+                patch(spec) {
+                    const fn = mutation({
+                        args: spec.args,
+                        handler: async () => unsupportedLocalFirstCall("patch", tableName)
+                    });
+                    return attachMetadata(fn, { kind: "patch", ...metadata, spec });
+                },
+                remove(spec) {
+                    const fn = mutation({
+                        args: spec.args,
+                        handler: async () => unsupportedLocalFirstCall("remove", tableName)
+                    });
+                    return attachMetadata(fn, { kind: "remove", ...metadata, spec });
+                }
+            };
+        }
+        // I8 "server-only by default" needs no wrapper: a mutation is local-first
+        // ONLY if declared via lf.table(...).insert/patch/remove and present in the
+        // manifest. Every other Convex mutation is server-only — it runs through the
+        // normal Convex client and never enters the local outbox.
+    };
+}
+/**
+ * Local-first table functions are never executed server-side: reads/writes flow
+ * through the generated client (optimistic local) and are synchronized via
+ * sync.push / sync.pull. The function still exists in the deployment — the client
+ * references it by name and codegen introspects its attached metadata — but
+ * invoking the handler directly is a bug, so it refuses loudly instead of
+ * returning fabricated data (GOAL G7: real, or explicitly throw "unsupported").
+ */
+function unsupportedLocalFirstCall(kind, tableName) {
+    throw new Error(`Local-first ${kind} for "${tableName}" is not directly callable server-side. Call it from the ` +
+        `client instead — the React hooks (useMutation/useQuery) or, headless, ` +
+        `engine.mutate(api.<module>.<fn>, args) / engine.query(...) — which applies it optimistically and ` +
+        `synchronizes via sync.push / sync.pull. (Invoking the server handler directly is always a bug.)`);
+}
+function attachMetadata(value, metadata) {
+    Object.defineProperty(value, LF_METADATA_KEY, {
+        value: metadata,
+        enumerable: false,
+        configurable: false
+    });
+    return value;
+}
+/**
+ * Derive the `createSyncFunctions({ tables })` config from your imported `lf.table`
+ * modules, so scope / idField / conflict live in ONE place instead of being restated (and
+ * drifting) in `sync.ts`:
+ *
+ * ```ts
+ * import * as issues from "./issues";
+ * import * as labels from "./labels";
+ * export const { push, pull } = createSyncFunctions({
+ *   component: components.convexLocalFirst, mutation, query,
+ *   tables: collectTables({ issues, labels }),
+ *   isMember
+ * });
+ * ```
+ *
+ * Throws if two functions of one table carry conflicting config, or if no local-first
+ * tables are found.
+ */
+export function collectTables(modules) {
+    const out = {};
+    for (const mod of Object.values(modules)) {
+        if (!mod || (typeof mod !== "object" && typeof mod !== "function"))
+            continue;
+        for (const exported of Object.values(mod)) {
+            const meta = exported?.[LF_METADATA_KEY];
+            if (!meta || typeof meta.tableName !== "string")
+                continue;
+            const config = { scope: meta.scope, idField: meta.idField, conflict: meta.conflict };
+            const existing = out[meta.tableName];
+            if (!existing) {
+                out[meta.tableName] = config;
+            }
+            else if (existing.idField !== config.idField ||
+                existing.conflict !== config.conflict ||
+                JSON.stringify(existing.scope) !== JSON.stringify(config.scope)) {
+                // Fail closed: a divergent config for the same table can only come from
+                // hand-tampering the metadata — never from a single lf.table definition.
+                throw new Error(`collectTables: conflicting config for table "${meta.tableName}" — every lf.table function for a table must share one definition.`);
+            }
+        }
+    }
+    if (Object.keys(out).length === 0) {
+        throw new Error("collectTables: no local-first tables found in the provided modules. Import the table modules and pass them, e.g. collectTables({ issues, labels }).");
+    }
+    return out;
+}

package/dist/serverSync.d.ts

@@ -0,0 +1,159 @@
+import type { ConflictPolicyName, ScopeDefinition } from "@convex-localfirst/core";
+import { type FieldClock } from "@convex-localfirst/core/internal";
+/**
+ * Pure, runtime-agnostic server sync engine. It enforces scope/ownership,
+ * dedupes via the operation ledger, appends to the change log (deletes included),
+ * and maintains the id map. The Convex component supplies a ServerStore backed by
+ * ctx.db; tests supply an in-memory one. Pull cursors are client-driven (sent in the
+ * request, advanced in the response) — the server keeps no per-client cursor state.
+ *
+ * Security invariants enforced here (the client never decides authorization):
+ *  - I7: pull scope and push ownership/membership are derived from the
+ *        authenticated userId, never from client-supplied scope/owner values.
+ *  - I2: a re-pushed opId is idempotent (ledger lookup short-circuits).
+ */
+export type ServerTableConfig = {
+    readonly scope: ScopeDefinition;
+    readonly idField: string;
+    readonly conflict: ConflictPolicyName;
+};
+export type ServerOperation = {
+    readonly opId: string;
+    readonly clientId: string;
+    readonly schemaVersion: number;
+    readonly functionName: string;
+    readonly table: string;
+    readonly kind: "insert" | "patch" | "delete";
+    readonly localId: string;
+    readonly value?: Record<string, unknown>;
+    readonly patch?: Record<string, unknown>;
+    readonly timestamp?: number;
+};
+export type StoredChange = {
+    readonly changeId: string;
+    readonly scopeKey: string;
+    readonly table: string;
+    readonly localId: string;
+    readonly kind: "insert" | "patch" | "delete";
+    readonly data?: Record<string, unknown>;
+    readonly patch?: Record<string, unknown>;
+    readonly version: number;
+    readonly serverTime: number;
+    readonly opId?: string;
+};
+export type LedgerEntry = {
+    readonly status: "accepted" | "rejected";
+    readonly resultJson?: string;
+    readonly error?: string;
+    readonly changesJson?: string;
+};
+/**
+ * Storage contract the sync engine drives. TRANSACTIONAL REQUIREMENT (I2/I5): each push
+ * does read-then-write sequences that need transactional isolation —
+ *  - idempotency: getLedger → apply → putLedger must be atomic, else concurrent pushes of
+ *    the same opId both miss the ledger and double-apply;
+ *  - per-row version monotonicity: latestChangeVersion → appendChange(version+1).
+ * The Convex adapter gets this free (every method shares the parent mutation's tx + OCC).
+ * A CUSTOM ServerStore MUST provide the same per-push isolation or it can race.
+ */
+export type ServerStore = {
+    getRow(table: string, serverId: string): Promise<Record<string, unknown> | null>;
+    insertRow(table: string, data: Record<string, unknown>): Promise<string>;
+    patchRow(table: string, serverId: string, patch: Record<string, unknown>): Promise<void>;
+    deleteRow(table: string, serverId: string): Promise<void>;
+    getLedger(userId: string, opId: string): Promise<LedgerEntry | null>;
+    putLedger(userId: string, clientId: string, op: ServerOperation, entry: LedgerEntry): Promise<void>;
+    getServerId(table: string, localId: string): Promise<string | null>;
+    putIdMap(userId: string, table: string, localId: string, serverId: string): Promise<void>;
+    appendChange(change: Omit<StoredChange, "changeId">): Promise<string>;
+    changesAfter(scopeKey: string, cursor: string | null, limit: number): Promise<readonly StoredChange[]>;
+    /** Highest change version recorded for a row (0 if none). Row versions live in
+     *  the change log, never on the user row, so user schemas stay clean.
+     *
+     *  CONCURRENCY (I5 monotonicity): handlePush reads this then appendChange writes
+     *  `version+1`. In the real Convex adapter both are component calls FROM a mutation,
+     *  which share the parent's transaction + OCC — a concurrent push to the same row
+     *  invalidates this read and retries, so two writers can't commit a duplicate or
+     *  regressing per-row version. (A non-transactional custom/in-memory ServerStore has
+     *  no such guarantee; the bundled tests run sequentially so they never race.) */
+    latestChangeVersion(table: string, localId: string): Promise<number>;
+    /** The scope a row last lived in (from the change log), or null if never seen.
+     *  Authorizes an idempotent no-op delete of an already-gone row (whose scope can
+     *  no longer come from the row itself) so it can't become a cross-scope oracle. */
+    scopeForLocalId(table: string, localId: string): Promise<string | null>;
+    /** OPTIONAL on the type, but REQUIRED for any `timestampLww` table: per-field write clocks
+     *  (field → {ts, tiebreaker}). A timestampLww table whose store lacks these REJECTS the op
+     *  loudly (no silent arrival-order degrade — see applyOp). A store with only `fieldLww` tables
+     *  never needs them. Like the version RMW, the get→put pair must share the push mutation's
+     *  transaction (it does in the real Convex adapter) so concurrent writers can't lose a clock update. */
+    getFieldClocks?(table: string, localId: string): Promise<Record<string, FieldClock>>;
+    putFieldClocks?(table: string, localId: string, clocks: Record<string, FieldClock>): Promise<void>;
+    isMember(userId: string, scopeValue: string, membershipTable: string): Promise<boolean>;
+};
+export type PushOp = ServerOperation;
+export type PushInput = {
+    readonly userId: string;
+    readonly clientId: string;
+    readonly schemaVersion: number;
+    readonly mutations: readonly PushOp[];
+};
+export type PushResult = {
+    readonly accepted: Array<{
+        opId: string;
+        serverResult?: unknown;
+    }>;
+    readonly rejected: Array<{
+        opId: string;
+        message: string;
+    }>;
+    readonly idMaps: Array<{
+        table: string;
+        localId: string;
+        serverId: string;
+    }>;
+    readonly changes: StoredChange[];
+    readonly serverTime: number;
+    readonly schemaMismatch?: boolean;
+};
+export type PullScope = {
+    readonly kind: ScopeDefinition["kind"];
+    readonly value?: string;
+};
+export type PullInput = {
+    readonly userId: string;
+    readonly clientId: string;
+    readonly schemaVersion: number;
+    readonly scopes: readonly PullScope[];
+    readonly cursors: Record<string, string | null>;
+};
+export type PullResult = {
+    readonly changes: StoredChange[];
+    readonly cursors: Record<string, string>;
+    readonly serverTime: number;
+    readonly schemaMismatch?: boolean;
+    /** Per-scope: true when this page hit the pull limit, so more changes remain. */
+    readonly hasMore: Record<string, boolean>;
+};
+/**
+ * Codec for serializing local-first row values to/from the JSON-string columns in
+ * the component. The default is plain JSON (fine for tests + JSON-only values); the
+ * Convex adapter injects one built on convexToJson/jsonToConvex so synced rows can
+ * carry the FULL Convex value range (bigint, bytes, nested undefined) losslessly
+ * rather than throwing (bigint) or silently changing shape.
+ */
+export type ValueCodec = {
+    encode(value: unknown): string;
+    decode(json: string): unknown;
+};
+export declare const JSON_VALUE_CODEC: ValueCodec;
+export type SyncConfig = {
+    readonly schemaVersion: number;
+    readonly tables: Record<string, ServerTableConfig>;
+    readonly now?: () => number;
+    readonly pullLimit?: number;
+    readonly valueCodec?: ValueCodec;
+};
+export declare function scopeKeyForUser(userId: string): string;
+export declare function scopeKeyForValue(kind: string, value: string): string;
+export declare function handlePush(store: ServerStore, config: SyncConfig, input: PushInput): Promise<PushResult>;
+export declare function handlePull(store: ServerStore, config: SyncConfig, input: PullInput): Promise<PullResult>;

package/dist/serverSync.js

@@ -0,0 +1,447 @@
+import { applyCounterDelta, applySetDelta, isCounterDelta, isSetDelta, lwwWins } from "@convex-localfirst/core/internal";
+export const JSON_VALUE_CODEC = {
+    encode: (value) => JSON.stringify(value ?? null),
+    decode: (json) => JSON.parse(json)
+};
+class RejectOp extends Error {
+}
+export function scopeKeyForUser(userId) {
+    return `u:${userId}`;
+}
+export function scopeKeyForValue(kind, value) {
+    return `${kind}:${value}`;
+}
+/** The field that decides a row's partition. A write must never change it (a row
+ * cannot move scopes), otherwise membership — checked against the row's CURRENT
+ * scope — would be bypassed (I7). */
+function partitionFieldOf(scope) {
+    if (scope.kind === "byUser")
+        return scope.field;
+    if (scope.kind === "byWorkspace")
+        return scope.workspaceIdField;
+    if (scope.kind === "byProject")
+        return scope.projectIdField;
+    return null;
+}
+/**
+ * Resolve the scope key for an op, enforcing ownership/membership against the
+ * authenticated userId. CRUCIAL (I7): for a patch/delete the scope is derived
+ * from the EXISTING SERVER ROW, never from client-supplied `op.value` — otherwise
+ * a client could name a scope it belongs to and so authorize a write to a row in
+ * a scope it does not. Only an insert declares its own scope (and membership on
+ * that claimed value is checked).
+ */
+async function resolveScopeForWrite(store, config, userId, op) {
+    const scope = config.scope;
+    const value = { ...(op.value ?? {}) };
+    if (scope.kind === "byUser") {
+        if (op.kind === "insert") {
+            // Ignore any client-supplied owner: ownership is the authenticated user.
+            value[scope.field] = userId;
+            return { scopeKey: scopeKeyForUser(userId), value };
+        }
+        // patch/delete: the row must exist AND be owned by this user. The id map is
+        // global (by table+localId), so without this check a user who guesses another
+        // user's localId could write their row.
+        const existing = await loadRow(store, op);
+        if (existing[scope.field] !== userId) {
+            throw new RejectOp("Not the owner of this row");
+        }
+        return { scopeKey: scopeKeyForUser(userId), value };
+    }
+    if (scope.kind === "byWorkspace" || scope.kind === "byProject") {
+        const field = scope.kind === "byWorkspace" ? scope.workspaceIdField : scope.projectIdField;
+        let scopeValue;
+        if (op.kind === "insert") {
+            // An insert declares the scope it targets; membership on it is checked below.
+            scopeValue = typeof value[field] === "string" ? String(value[field]) : null;
+        }
+        else {
+            // patch/delete: scope comes from the existing row, NEVER from op.value.
+            const existing = await loadRow(store, op);
+            scopeValue = typeof existing[field] === "string" ? String(existing[field]) : null;
+        }
+        if (!scopeValue) {
+            throw new RejectOp(`Missing ${field} for scoped write`);
+        }
+        const member = await store.isMember(userId, scopeValue, scope.membershipTable);
+        if (!member) {
+            throw new RejectOp("Not a member of the target scope");
+        }
+        return { scopeKey: scopeKeyForValue(scope.kind, scopeValue), value };
+    }
+    throw new RejectOp("Custom scopes require a server resolver");
+}
+/** True if `userId` may write rows in `scopeKey`. The boolean core of scope
+ *  authorization — the caller decides whether to throw and with what message, so a
+ *  delete can reject every denial (missing/foreign/gone) with ONE generic message
+ *  and avoid leaking which case it was (an existence/ownership oracle, I7). */
+async function isAuthorizedForScope(store, config, userId, scopeKey) {
+    const scope = config.scope;
+    if (scope.kind === "byUser") {
+        return scopeKey === scopeKeyForUser(userId);
+    }
+    if (scope.kind === "byWorkspace" || scope.kind === "byProject") {
+        const value = scopeKey.slice(scopeKey.indexOf(":") + 1);
+        return await store.isMember(userId, value, scope.membershipTable);
+    }
+    return false; // defensive: fail closed on any unknown scope kind
+}
+/** The scopeKey a stored row belongs to, from its partition field (the inverse of
+ *  resolveScopeForWrite). Returns null if the row lacks a usable partition value. */
+function scopeKeyForRow(config, row) {
+    const scope = config.scope;
+    if (scope.kind === "byUser") {
+        const owner = row[scope.field];
+        return typeof owner === "string" ? scopeKeyForUser(owner) : null;
+    }
+    if (scope.kind === "byWorkspace" || scope.kind === "byProject") {
+        const field = scope.kind === "byWorkspace" ? scope.workspaceIdField : scope.projectIdField;
+        const value = row[field];
+        return typeof value === "string" ? scopeKeyForValue(scope.kind, value) : null;
+    }
+    return null;
+}
+/** Load the existing server row for a non-insert op, or reject if it's gone. */
+async function loadRow(store, op) {
+    const serverId = await store.getServerId(op.table, op.localId);
+    const row = serverId ? await store.getRow(op.table, serverId) : null;
+    if (!row) {
+        throw new RejectOp(`No server row for ${op.table}:${op.localId}`);
+    }
+    return row;
+}
+export async function handlePush(store, config, input) {
+    const now = config.now ?? (() => Date.now());
+    const serverTime = now();
+    const codec = config.valueCodec ?? JSON_VALUE_CODEC;
+    const result = { accepted: [], rejected: [], idMaps: [], changes: [], serverTime };
+    if (input.schemaVersion !== config.schemaVersion) {
+        return { ...result, schemaMismatch: true };
+    }
+    for (const op of input.mutations) {
+        // I2: idempotency — a known opId is never re-applied (keyed by (userId, opId) so a
+        // reload/new-tab replay under a different envelope clientId is still deduped).
+        const prior = await store.getLedger(input.userId, op.opId);
+        if (prior) {
+            if (prior.status === "accepted") {
+                result.accepted.push({ opId: op.opId, serverResult: prior.resultJson ? JSON.parse(prior.resultJson) : undefined });
+                // Re-deliver the confirming change so a replayed (already-committed) op can
+                // leave _pending even if its original ack was lost. The client version-checks
+                // it (nextCanonicalRow), so re-applying a now-stale change is ignored — never a
+                // regression. The server log is NOT re-appended (this is read from the ledger).
+                if (prior.changesJson) {
+                    result.changes.push(...codec.decode(prior.changesJson));
+                }
+            }
+            else {
+                result.rejected.push({ opId: op.opId, message: prior.error ?? "rejected" });
+            }
+            continue;
+        }
+        // I8: an op carries the schema it was BUILT under. The envelope already matches the
+        // server (checked above), so a per-op mismatch means a stale offline op queued before
+        // a client schema upgrade. Applying it under the new schema can silently corrupt
+        // (changed field meaning, new required field). Reject it loudly — the client must
+        // migrate queued ops before pushing — rather than commit semantically stale data.
+        if (op.schemaVersion !== input.schemaVersion) {
+            const message = `Operation ${op.opId} was created under schema v${op.schemaVersion} but the client now declares v${input.schemaVersion}; migrate queued operations before pushing.`;
+            result.rejected.push({ opId: op.opId, message });
+            await store.putLedger(input.userId, input.clientId, op, { status: "rejected", error: message });
+            continue;
+        }
+        const tableConfig = config.tables[op.table];
+        if (!tableConfig) {
+            const message = `Unknown local-first table: ${op.table}`;
+            result.rejected.push({ opId: op.opId, message });
+            await store.putLedger(input.userId, input.clientId, op, { status: "rejected", error: message });
+            continue;
+        }
+        try {
+            const change = await applyOp(store, tableConfig, input.userId, op, serverTime);
+            if (change) {
+                result.changes.push(change);
+            }
+            const serverId = await store.getServerId(op.table, op.localId);
+            if (op.kind === "insert" && serverId) {
+                result.idMaps.push({ table: op.table, localId: op.localId, serverId });
+            }
+            // change === null is an idempotent no-op delete (row already gone): still ack it
+            // so the client stops retrying, and ledger it for opId idempotency. Do NOT echo
+            // serverId on a no-op — the row is gone, so its internal id must not leak.
+            const serverResult = change === null
+                ? { ok: true, localId: op.localId, noop: true }
+                : { ok: true, localId: op.localId, serverId };
+            result.accepted.push({ opId: op.opId, serverResult });
+            await store.putLedger(input.userId, input.clientId, op, {
+                status: "accepted",
+                resultJson: JSON.stringify(serverResult),
+                // Persist the confirming change so a later duplicate replay can recover it.
+                changesJson: change ? codec.encode([change]) : undefined
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            result.rejected.push({ opId: op.opId, message });
+            await store.putLedger(input.userId, input.clientId, op, { status: "rejected", error: message });
+        }
+    }
+    return result;
+}
+// Bound how far a client's logical write-clock may lead the server clock. op.timestamp
+// is the client's own clock (legitimately ahead of serverTime by real skew), so we don't
+// clamp to serverTime exactly — but an UNBOUNDED future timestamp would let an authorized
+// writer pin a timestampLww field forever (every later honest write has a smaller ts and
+// loses). Clamping to serverTime + this bound caps that abuse to a small window while
+// leaving every real write (op.createdAt ≈ now) untouched.
+const MAX_CLOCK_SKEW_MS = 5 * 60_000;
+async function applyOp(store, tableConfig, userId, op, serverTime) {
+    // Delete is fully handled here so EVERY denial — never-seen localId, foreign live
+    // row, foreign already-deleted row — rejects with ONE generic message. Splitting
+    // them ("No server row" vs "Not the owner") would be an existence/ownership oracle
+    // (I7). Authorize against the row's scope: the live row's partition field if it
+    // still exists, else the scope it last lived in (the append-only change log).
+    if (op.kind === "delete") {
+        const existingId = await store.getServerId(op.table, op.localId);
+        const existingRow = existingId ? await store.getRow(op.table, existingId) : null;
+        const scopeKey = existingRow
+            ? scopeKeyForRow(tableConfig, existingRow)
+            : await store.scopeForLocalId(op.table, op.localId);
+        if (scopeKey === null || !(await isAuthorizedForScope(store, tableConfig, userId, scopeKey))) {
+            throw new RejectOp(`Cannot delete ${op.table}:${op.localId}`);
+        }
+        // Deletes commute: an authorized delete of an already-gone row acks as a no-op
+        // (the EXPECTED case for an insert-only log with compaction, where two clients
+        // can concurrently prune the same subsumed rows, and for any replayed delete).
+        if (!existingRow) {
+            return null;
+        }
+        const version = (await store.latestChangeVersion(op.table, op.localId)) + 1;
+        await store.deleteRow(op.table, existingId);
+        const changeId = await store.appendChange({
+            scopeKey,
+            table: op.table,
+            localId: op.localId,
+            kind: "delete",
+            version,
+            serverTime,
+            opId: op.opId
+        });
+        return changeAsStored(changeId, scopeKey, op, "delete", version, serverTime, undefined, undefined);
+    }
+    let scopeKey;
+    let value;
+    try {
+        ({ scopeKey, value } = await resolveScopeForWrite(store, tableConfig, userId, op));
+    }
+    catch (error) {
+        // A patch's denials (never-seen "No server row", foreign owner/member) would be
+        // an existence/ownership oracle — collapse them ALL into one generic message
+        // (mirrors delete). Insert has no such oracle (its row does not exist yet), so
+        // its messages pass through unchanged.
+        if (op.kind === "patch" && error instanceof RejectOp) {
+            throw new RejectOp(`Cannot patch ${op.table}:${op.localId}`);
+        }
+        throw error;
+    }
+    if (op.kind === "insert") {
+        // Record the client's stable local id under the table's idField so the row
+        // satisfies the app schema and can be correlated back to the client.
+        value[tableConfig.idField] = op.localId;
+        // A re-push of the SAME op is short-circuited by the ledger before applyOp, so
+        // reaching here with an existing (table, localId) means a DIFFERENT op reused
+        // the localId. localId must be globally unique — treat a collision as invalid
+        // rather than as license to append a change against an existing row.
+        if (await store.getServerId(op.table, op.localId)) {
+            throw new RejectOp(`Duplicate localId for ${op.table}:${op.localId}`);
+        }
+        const serverId = await store.insertRow(op.table, value);
+        await store.putIdMap(userId, op.table, op.localId, serverId);
+        // First change for a fresh row is version 1 (I5 monotonicity).
+        const version = (await store.latestChangeVersion(op.table, op.localId)) + 1;
+        const changeId = await store.appendChange({
+            scopeKey,
+            table: op.table,
+            localId: op.localId,
+            kind: "insert",
+            data: value,
+            version,
+            serverTime,
+            opId: op.opId
+        });
+        return changeAsStored(changeId, scopeKey, op, "insert", version, serverTime, value, undefined);
+    }
+    const serverId = await store.getServerId(op.table, op.localId);
+    if (!serverId) {
+        // Only patch reaches here (delete/insert returned above), and resolveScopeForWrite
+        // already loaded the row — so this is a defensive guard; keep it generic (no oracle).
+        throw new RejectOp(`Cannot patch ${op.table}:${op.localId}`);
+    }
+    // Row version is derived from the append-only change log — the single source of
+    // truth — never written onto the user row (which has no `_version` column).
+    const version = (await store.latestChangeVersion(op.table, op.localId)) + 1;
+    if (op.kind === "patch") {
+        // I7 defense-in-depth: a patch must never move a row across scopes or rewrite
+        // its id. Membership was checked against the row's CURRENT scope; letting the
+        // patch change the partition field (workspaceId/ownerId/projectId) or idField
+        // would bypass that check and corrupt the change log's scope key.
+        let patch = op.patch ?? {};
+        const guarded = partitionFieldOf(tableConfig.scope);
+        for (const field of [guarded, tableConfig.idField]) {
+            if (field && Object.prototype.hasOwnProperty.call(patch, field)) {
+                throw new RejectOp(`Cannot patch the ${field === tableConfig.idField ? "id" : "scope"} field "${field}"`);
+            }
+        }
+        // Set/counter-field merge: a patch field carrying a SetDelta or CounterDelta is
+        // materialized against the CURRENT row → a plain array/number, so concurrent edits from
+        // other clients merge (not last-writer-wins clobber) and the change log + pull stay
+        // delta-free (clients pull concrete values). Shape-driven (the delta is self-describing),
+        // so no per-table server config; only loads the row when a delta is actually present
+        // (zero overhead otherwise). A delta over a wrong-typed field is a client bug/forge — reject.
+        // Convergent (set/counter) delta fields are merged commutatively below and are EXEMPT
+        // from timestamp-LWW (they never clobber by design). Capture them before materialization.
+        const deltaFields = new Set(Object.keys(patch).filter((f) => isSetDelta(patch[f]) || isCounterDelta(patch[f])));
+        if (deltaFields.size > 0) {
+            const current = await loadRow(store, op);
+            const materialized = { ...patch };
+            for (const [field, value] of Object.entries(patch)) {
+                if (isSetDelta(value)) {
+                    if (current[field] !== undefined && !Array.isArray(current[field])) {
+                        throw new RejectOp(`Set delta on non-array field "${field}" of ${op.table}:${op.localId}`);
+                    }
+                    materialized[field] = applySetDelta(current[field], value.__lfSet);
+                }
+                else if (isCounterDelta(value)) {
+                    if (current[field] !== undefined && typeof current[field] !== "number") {
+                        throw new RejectOp(`Counter delta on non-number field "${field}" of ${op.table}:${op.localId}`);
+                    }
+                    materialized[field] = applyCounterDelta(current[field], value.__lfCounter);
+                }
+            }
+            patch = materialized;
+        }
+        // Timestamp-ordered LWW: for a `timestampLww` table, resolve each plain scalar field-write
+        // against the field's last-write clock so a newer edit wins regardless of arrival order; a
+        // stale write is dropped. Delta fields (set/counter) are exempt (they never clobber), so a
+        // delta-only patch skips this. A patch writing ANY plain field MUST carry a timestamp and a
+        // field-clock store — applying by arrival order without updating the clock would desync it
+        // and wrongly drop a later write — so we fail closed loudly rather than corrupt.
+        if (tableConfig.conflict === "timestampLww") {
+            const plainFields = Object.keys(patch).filter((f) => !deltaFields.has(f));
+            if (plainFields.length > 0) {
+                if (op.timestamp === undefined) {
+                    throw new RejectOp(`Table "${op.table}" uses conflict: "timestampLww" but this op writes scalar field(s) [${plainFields.join(", ")}] without a timestamp — upgrade the client (the local-first transport sends one automatically).`);
+                }
+                if (!store.getFieldClocks || !store.putFieldClocks) {
+                    throw new RejectOp(`Table "${op.table}" uses conflict: "timestampLww" but the ServerStore has no getFieldClocks/putFieldClocks. Use the bundled component or implement both.`);
+                }
+                const ts = Math.min(op.timestamp, serverTime + MAX_CLOCK_SKEW_MS); // cap far-future pinning
+                const incoming = { ts, tiebreaker: op.clientId };
+                const clocks = await store.getFieldClocks(op.table, op.localId);
+                const winners = {};
+                const updated = {};
+                for (const [field, value] of Object.entries(patch)) {
+                    if (deltaFields.has(field)) {
+                        winners[field] = value; // convergent delta — always kept, no clock
+                    }
+                    else if (lwwWins(incoming, clocks[field])) {
+                        winners[field] = value;
+                        updated[field] = incoming;
+                    }
+                    // else: a stale plain field-write — drop it, keeping the current (newer) value.
+                }
+                if (Object.keys(updated).length > 0) {
+                    await store.putFieldClocks(op.table, op.localId, { ...clocks, ...updated });
+                }
+                patch = winners;
+            }
+        }
+        // A patch that resolved to no fields — every plain field lost the timestamp-LWW race,
+        // or the op carried an empty patch — is an ACCEPTED no-op (like an already-gone delete):
+        // skip the write so it never appends a spurious empty change, consumes a version, or
+        // gets re-delivered to every puller. Do NOT leak the serverId (handlePush noop path).
+        if (Object.keys(patch).length === 0) {
+            return null;
+        }
+        await store.patchRow(op.table, serverId, patch);
+        const changeId = await store.appendChange({
+            scopeKey,
+            table: op.table,
+            localId: op.localId,
+            kind: "patch",
+            patch,
+            version,
+            serverTime,
+            opId: op.opId
+        });
+        return changeAsStored(changeId, scopeKey, op, "patch", version, serverTime, undefined, patch);
+    }
+    // insert/patch return above; delete is fully handled at the top. This is
+    // unreachable for the three known kinds — guard any future kind explicitly.
+    throw new RejectOp(`Unsupported op kind for ${op.table}:${op.localId}`);
+}
+function changeAsStored(changeId, scopeKey, op, kind, version, serverTime, data, patch) {
+    return { changeId, scopeKey, table: op.table, localId: op.localId, kind, data, patch, version, serverTime, opId: op.opId };
+}
+/**
+ * The membership table to enforce for a workspace/project scope kind. Scope keys
+ * are per-value and SHARED across every table of a kind, so the kind must map to
+ * exactly one membership table — otherwise a member of the laxer table could pull
+ * the stricter table's changes (I7). Reject the ambiguity here (defense for direct
+ * serverSync callers; createSyncFunctions also asserts this at config time).
+ */
+function membershipTableForScope(config, kind) {
+    const tables = new Set();
+    for (const table of Object.values(config.tables)) {
+        if (table.scope.kind === kind) {
+            tables.add(table.scope.membershipTable);
+        }
+    }
+    if (tables.size > 1) {
+        throw new Error(`serverSync: all ${kind} tables must share one membershipTable (found: ${[...tables].join(", ")}). Mixed membership tables would cross-authorize reads.`);
+    }
+    return tables.size === 1 ? [...tables][0] : null;
+}
+export async function handlePull(store, config, input) {
+    const now = config.now ?? (() => Date.now());
+    const limit = config.pullLimit ?? 500;
+    const out = { changes: [], cursors: {}, hasMore: {}, serverTime: now() };
+    if (input.schemaVersion !== config.schemaVersion) {
+        return { ...out, schemaMismatch: true };
+    }
+    for (const scope of input.scopes) {
+        let scopeKey;
+        if (scope.kind === "byUser") {
+            // I7: derive from identity; ignore any client-supplied user value.
+            scopeKey = scopeKeyForUser(input.userId);
+        }
+        else if (scope.kind === "byWorkspace" || scope.kind === "byProject") {
+            if (!scope.value) {
+                continue;
+            }
+            // Membership is required to read a workspace/project scope. The membership
+            // table must be the SAME one push enforces against (the configured value),
+            // not a synthesized name — otherwise read and write check different tables.
+            const membershipTable = membershipTableForScope(config, scope.kind);
+            if (!membershipTable) {
+                continue;
+            }
+            const member = await store.isMember(input.userId, scope.value, membershipTable);
+            if (!member) {
+                continue;
+            }
+            scopeKey = scopeKeyForValue(scope.kind, scope.value);
+        }
+        else {
+            continue;
+        }
+        const cursor = input.cursors[scopeKey] ?? null;
+        const changes = await store.changesAfter(scopeKey, cursor, limit);
+        out.changes.push(...changes);
+        const last = changes[changes.length - 1];
+        out.cursors[scopeKey] = last ? last.changeId : cursor ?? "";
+        // A full page means the server capped this scope; more may remain past the cursor.
+        out.hasMore[scopeKey] = changes.length >= limit;
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@convex-localfirst/server",
+  "version": "0.1.0",
+  "description": "Convex-side DSL (lf.table) and runtime-agnostic sync engine for local-first tables: scopes, ownership, idempotency.",
+  "license": "MIT",
+  "keywords": [
+    "convex",
+    "local-first",
+    "sync",
+    "server",
+    "dsl"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "convex": ">=1.0.0"
+  },
+  "dependencies": {
+    "@convex-localfirst/core": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --emitDeclarationOnly false",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}