@farm.js/sync 0.1.0-beta.1 → 0.1.0-beta.11

package/dist/client.d.ts

@@ -35,6 +35,18 @@ export declare function startSyncRuntime(config: SyncRuntimeConfig, options?: Sy
 export declare function getSyncStore(model: string): SyncModelStore;
 /** Fetch rows for a model, incrementally when the schema supports a cursor. */
 export declare function loadModel(model: string): Promise<void>;
+/**
+ * Run a server-defined action with the mutation lifecycle: an optimistic
+ * layer when the effect is predictable, the same offline pause, commit of
+ * whatever rows the server returns, rollback plus a failures entry on
+ * refusal.
+ *
+ * The optimistic patch resolves in tiers: an explicit patch wins; otherwise
+ * input fields that are schema columns form one (when the input carries the
+ * model's key); otherwise the action runs with no preview and the screen
+ * updates when the server's rows land.
+ */
+export declare function runSyncAction(model: string, action: string, invoke: (input: unknown) => Promise<unknown>, input: unknown, explicitPatch?: SyncRow): SyncMutationHandle;
 export type SyncModelClient = {
     insert(input: SyncRow): SyncMutationHandle;
     update(input: SyncRow): SyncMutationHandle;
@@ -48,6 +60,21 @@ export type SyncModelClient = {
     /** @internal */
     readonly __farmSyncModel: string;
 };
+/**
+ * Model row types, filled in by the generated `farm.d.ts` through declaration
+ * merging. Empty here so an app without generated types still compiles with
+ * plain `SyncRow` rows and any model name.
+ */
+export interface SyncModels {
+}
+/** Insert shapes per model: key, defaulted, and nullable columns optional. */
+export interface SyncModelInputs {
+}
+export type SyncModelName = [keyof SyncModels] extends [never] ? string : keyof SyncModels & string;
+export type SyncRowOf<K> = K extends keyof SyncModels ? SyncModels[K] : SyncRow;
+export type SyncInsertOf<K> = K extends keyof SyncModelInputs ? SyncModelInputs[K] : SyncRow;
+/** The per-model client, created lazily. The `db` proxy delegates here. */
+export declare function getSyncModelClient(model: string): SyncModelClient;
 /** Typed per-model client accessor, resolved lazily so imports stay cheap. */
 export declare const db: Record<string, SyncModelClient>;
 /**
@@ -73,7 +100,12 @@ type SyncPersistence = {
 };
 /** Replace the default browser store, for example with an IndexedDB one. */
 export declare function setSyncPersistence(store: SyncPersistence | null): void;
-/** Remove every persisted row. Call on logout so a shared device stays clean. */
+/**
+ * Forget every synced row, on disk and in memory. Call it when the session
+ * changes (sign out, sign in as someone else, switch organization) so the next
+ * account never sees the previous one's rows. Each model reloads in full on its
+ * next use, scoped to the session current at that point.
+ */
 export declare function clearSyncedRows(): void;
 export declare function hydrateModel(model: string): void;
 export {};

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -30,11 +30,31 @@ function requireRuntime() {
     }
     throw new Error("The sync runtime is not started. Add `sync({ ... })` to the plugins in farm.config.ts.");
 }
+const scheduledReloads = new Set();
+/**
+ * A store cleared by clearSyncedRows() reloads on its next use, under whichever
+ * session is current by then. Deferred so the reload's status change never
+ * fires while a component is rendering, and so loadModel's own lookup of the
+ * store does not schedule it again.
+ */
+function scheduleReload(model, store) {
+    if (scheduledReloads.has(model))
+        return;
+    scheduledReloads.add(model);
+    queueMicrotask(() => {
+        if (store.status === "idle")
+            void loadModel(model);
+        scheduledReloads.delete(model);
+    });
+}
 export function getSyncStore(model) {
     const state = requireRuntime();
     let store = state.stores.get(model);
-    if (store)
+    if (store) {
+        if (store.status === "idle" && isBrowser())
+            scheduleReload(model, store);
         return store;
+    }
     const descriptor = state.config.models[model];
     if (!descriptor) {
         if (!isBrowser())
@@ -68,10 +88,13 @@ async function request(body) {
 /** Fetch rows for a model, incrementally when the schema supports a cursor. */
 export async function loadModel(model) {
     const store = getSyncStore(model);
+    const generation = store.generation;
     if (store.status === "idle")
         store.setStatus("loading");
     try {
         const result = await request({ model, operation: "list", since: store.cursor });
+        if (store.generation !== generation)
+            return;
         store.applyServerRows(result.rows ?? [], {
             full: result.full !== false,
             cursor: result.cursor ?? null,
@@ -80,6 +103,8 @@ export async function loadModel(model) {
         persistModel(model);
     }
     catch (cause) {
+        if (store.generation !== generation)
+            return;
         store.setStatus("error", cause instanceof Error ? cause : new Error(String(cause)));
     }
 }
@@ -147,18 +172,30 @@ function runMutation(model, operation, input, optimistic) {
         : { type: "upsert", key: optimistic.key, row: optimistic.row };
     store.addLayer(layer);
     store.trackPending(1);
+    const generation = store.generation;
     let handleState = "pending";
     const isPersisted = (async () => {
         try {
             const result = await dispatchWrite(store, { model, operation, input }, state.options);
-            store.commitLayer(layer, operation === "delete" ? null : result);
             handleState = "completed";
+            // The store was cleared for a new session while this was in flight.
+            if (store.generation !== generation)
+                return result;
+            store.commitLayer(layer, operation === "delete" ? null : result);
             persistModel(model);
             return result;
         }
         catch (error) {
-            store.removeLayer(layer);
             handleState = "failed";
+            if (store.generation !== generation)
+                throw error;
+            store.removeLayer(layer);
+            store.recordFailure({
+                operation,
+                input,
+                error: error instanceof Error ? error : new Error(String(error)),
+                retry: () => runMutation(model, operation, input, optimistic),
+            });
             throw error;
         }
         finally {
@@ -181,7 +218,119 @@ function runMutation(model, operation, input, optimistic) {
         finally: (onFinally) => isPersisted.finally(onFinally),
     };
 }
+/**
+ * Run a server-defined action with the mutation lifecycle: an optimistic
+ * layer when the effect is predictable, the same offline pause, commit of
+ * whatever rows the server returns, rollback plus a failures entry on
+ * refusal.
+ *
+ * The optimistic patch resolves in tiers: an explicit patch wins; otherwise
+ * input fields that are schema columns form one (when the input carries the
+ * model's key); otherwise the action runs with no preview and the screen
+ * updates when the server's rows land.
+ */
+export function runSyncAction(model, action, invoke, input, explicitPatch) {
+    const state = requireRuntime();
+    const store = getSyncStore(model);
+    const keyField = store.descriptor.key;
+    const record = input && typeof input === "object" ? input : undefined;
+    const key = record?.[keyField];
+    let patch = explicitPatch;
+    if (!patch && record && key !== undefined) {
+        const columns = new Set(store.descriptor.fields ?? []);
+        const derived = Object.fromEntries(Object.entries(record).filter(([field]) => field !== keyField && columns.has(field)));
+        if (Object.keys(derived).length > 0)
+            patch = derived;
+    }
+    const layer = patch && key !== undefined
+        ? { type: "upsert", key, row: store.mergeRow(key, patch) }
+        : null;
+    if (layer)
+        store.addLayer(layer);
+    store.trackPending(1);
+    const generation = store.generation;
+    let handleState = "pending";
+    const isPersisted = (async () => {
+        try {
+            if ((state.options.networkMode ?? "online") === "online" && !isOnline()) {
+                store.trackPaused(1);
+                try {
+                    await waitForOnline();
+                }
+                finally {
+                    store.trackPaused(-1);
+                }
+            }
+            const result = await invoke(input);
+            const rows = Array.isArray(result) ? result : [result];
+            if (store.generation !== generation) {
+                handleState = "completed";
+                return (rows[0] ?? null);
+            }
+            let committed = false;
+            for (const row of rows) {
+                if (row && typeof row === "object" && row[keyField] !== undefined) {
+                    // Commit through the layer once so the prediction is replaced, then
+                    // fold any further returned rows straight into the confirmed set.
+                    store.commitLayer(!committed && layer
+                        ? layer
+                        : { type: "upsert", key: row[keyField], row: row }, row);
+                    committed = true;
+                }
+            }
+            if (!committed) {
+                // The action changed something this client cannot address by key;
+                // drop the prediction and converge on the server's truth instead.
+                if (layer)
+                    store.removeLayer(layer);
+                void loadModel(model);
+            }
+            handleState = "completed";
+            persistModel(model);
+            return (rows[0] ?? null);
+        }
+        catch (error) {
+            handleState = "failed";
+            if (store.generation !== generation)
+                throw error;
+            if (layer)
+                store.removeLayer(layer);
+            store.recordFailure({
+                operation: action,
+                input,
+                error: error instanceof Error ? error : new Error(String(error)),
+                retry: () => runSyncAction(model, action, invoke, input, explicitPatch),
+            });
+            throw error;
+        }
+        finally {
+            store.trackPending(-1);
+        }
+    })();
+    void isPersisted.catch(() => undefined);
+    return {
+        key,
+        get state() {
+            return handleState;
+        },
+        get persisted() {
+            return isPersisted;
+        },
+        then: (onFulfilled, onRejected) => isPersisted.then(onFulfilled, onRejected),
+        catch: (onRejected) => isPersisted.catch(onRejected),
+        finally: (onFinally) => isPersisted.finally(onFinally),
+    };
+}
 const clientCache = new Map();
+/** The per-model client, created lazily. The `db` proxy delegates here. */
+export function getSyncModelClient(model) {
+    let client = clientCache.get(model);
+    if (!client) {
+        client = createModelClient(model);
+        clientCache.set(model, client);
+    }
+    return client;
+}
 function createModelClient(model) {
     const client = {
         insert(input) {
@@ -243,12 +392,7 @@ export const db = new Proxy({}, {
     get(_target, property) {
         if (typeof property !== "string")
             return undefined;
-        let client = clientCache.get(property);
-        if (!client) {
-            client = createModelClient(property);
-            clientCache.set(property, client);
-        }
-        return client;
+        return getSyncModelClient(property);
     },
 });
 // ── persistence ────────────────────────────────────────────────────────────
@@ -300,9 +444,16 @@ function getPersistence() {
 export function setSyncPersistence(store) {
     persistence = store;
 }
-/** Remove every persisted row. Call on logout so a shared device stays clean. */
+/**
+ * Forget every synced row, on disk and in memory. Call it when the session
+ * changes (sign out, sign in as someone else, switch organization) so the next
+ * account never sees the previous one's rows. Each model reloads in full on its
+ * next use, scoped to the session current at that point.
+ */
 export function clearSyncedRows() {
     getPersistence()?.clear();
+    for (const store of runtime?.stores.values() ?? [])
+        store.reset();
 }
 function persistModel(model) {
     const store = runtime?.stores.get(model);

package/dist/index.d.ts

@@ -32,6 +32,13 @@ export type SyncPluginOptions = {
      * cannot be detected from its shape.
      */
     dialect?: FarmSqlDialect;
+    /**
+     * Extra origins allowed to call the sync endpoint, using the
+     * `serverActions.allowedOrigins` pattern syntax. Sync writes ride the
+     * caller's cookies, so cross-site requests are rejected unless the origin is
+     * listed here.
+     */
+    allowedOrigins?: readonly string[];
 };
 export type SyncMiddlewareContext = {
     request: Request;
@@ -48,6 +55,7 @@ export declare function sync(options: SyncPluginOptions): import("@farm.js/core"
             access: import("./types.js").SyncAccess;
             persist: boolean;
             cursor: string | null;
+            fields: string[];
         };
     };
 }, unknown, false, import("@farm.js/core").PluginRoutes>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAsB,MAAM,aAAa,CAAC;AAC3F,OAAO,EACL,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EAErB,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wEAAwE;IACxE,MAAM,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACtD,+DAA+D;IAC/D,KAAK,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC1B,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACzC,kEAAkE;IAClE,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACvC,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,qBAAqB,KACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AAE9E,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EACV,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,SAAS,EACT,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAIpB,wBAAgB,IAAI,CAAC,OAAO,EAAE,iBAAiB;;;;;;;;;;yDAuH9C;AAiHD,mCAAmC;AACnC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,CAAC;AACvE,YAAY,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAsB,MAAM,aAAa,CAAC;AAC3F,OAAO,EACL,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EAErB,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wEAAwE;IACxE,MAAM,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACtD,+DAA+D;IAC/D,KAAK,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC1B,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACzC,kEAAkE;IAClE,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACvC,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,qBAAqB,KACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AAE9E,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EACV,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,SAAS,EACT,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAIpB,wBAAgB,IAAI,CAAC,OAAO,EAAE,iBAAiB;;;;;;;;;;;yDAmI9C;AAsOD,mCAAmC;AACnC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,CAAC;AACvE,YAAY,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-import { declareSchemaTables, definePlugin } from "@farm.js/core";
+import { definePlugin, describeIntegrationOriginRejection, resolveIntegrationAllowedOrigins, validateIntegrationRequestOrigin, } from "@farm.js/core";
 import { executeSyncOperation, SyncOperationError } from "./server.js";
 import { resolveSyncModels, } from "./types.js";
 const DEFAULT_PATH = "/_farm/sync";
@@ -11,13 +11,24 @@ export function sync(options) {
     if (models.size === 0) {
         throw new Error("sync(): no models are exposed. Add at least one entry to `models`.");
     }
+    // Resolved once so an invalid pattern fails at startup, not per request.
+    const allowedOrigins = resolveIntegrationAllowedOrigins(options.allowedOrigins, "sync().allowedOrigins");
     let ormPromise;
     const resolveOrm = () => {
         ormPromise ??= resolveSyncClient(options, models);
         return ormPromise;
     };
-    const plugin = definePlugin({
+    return definePlugin({
         name: "farm:sync",
+        // `farm sync migrate` creates the tables of the models the app exposed.
+        // The rest of the app's schema is described, not created: those tables
+        // are the app's.
+        schema: syncOwnedSchema(options.schema, models),
+        // The database the app gave sync, not storage.client.
+        database: {
+            client: () => resolveSyncConnection(options),
+            dialect: options.dialect,
+        },
         client: {
             // Serializable descriptor the browser runtime reads at startup.
             public: {
@@ -29,6 +40,7 @@ export function sync(options) {
                         access: model.access,
                         persist: model.persist,
                         cursor: model.cursorField ?? null,
+                        fields: Object.keys(model.fields),
                     },
                 ])),
             },
@@ -39,12 +51,26 @@ export function sync(options) {
                 scope.__FARM_SYNC__?.start?.(config);
             },
         },
+        // The production runtime only has a Web Request/Response boundary. Keep
+        // the endpoint on the runtime hook so it is handled by both Nitro and the
+        // development server instead of relying solely on the legacy Node hook.
+        runtime: {
+            async before({ request }) {
+                return handleSyncRequest(request, undefined, {
+                    path,
+                    models,
+                    middleware: options.middleware,
+                    resolveOrm,
+                    allowedOrigins,
+                });
+            },
+        },
         async beforeRequest(req, res) {
             const pathname = (req.url ?? "").split("?")[0];
             if (pathname !== path)
                 return;
             if (req.method !== "POST") {
-                sendJson(res, 405, { error: { code: "invalid_input", message: "Sync uses POST." } });
+                await sendNodeResponse(res, jsonResponse(405, { error: { code: "invalid_input", message: "Sync uses POST." } }));
                 return;
             }
             let body;
@@ -52,60 +78,117 @@ export function sync(options) {
                 body = await readJsonBody(req);
             }
             catch {
-                sendJson(res, 400, {
+                await sendNodeResponse(res, jsonResponse(400, {
                     error: { code: "invalid_input", message: "Request body must be JSON." },
-                });
+                }));
                 return;
             }
             if (!body || typeof body.model !== "string" || typeof body.operation !== "string") {
-                sendJson(res, 400, {
-                    error: { code: "invalid_input", message: "Request body needs `model` and `operation`." },
-                });
+                await sendNodeResponse(res, jsonResponse(400, {
+                    error: {
+                        code: "invalid_input",
+                        message: "Request body needs `model` and `operation`.",
+                    },
+                }));
                 return;
             }
             // The operation layer works in web-standard terms, so adapt once here.
             const request = toWebRequest(req, path);
-            try {
-                const context = await runMiddleware(options.middleware, request);
-                const orm = await resolveOrm();
-                const result = await executeSyncOperation({ body, models, orm, request, context });
-                sendJson(res, 200, result);
-            }
-            catch (error) {
-                if (error instanceof SyncOperationError) {
-                    sendJson(res, error.status, { error: { code: error.code, message: error.message } });
-                    return;
-                }
-                // Never leak an internal message to the browser.
-                console.error("[farm:sync] operation failed", error);
-                sendJson(res, 500, {
-                    error: { code: "server_error", message: "The sync operation failed." },
-                });
-            }
+            const response = await handleSyncRequest(request, body, {
+                path,
+                models,
+                middleware: options.middleware,
+                resolveOrm,
+                allowedOrigins,
+            });
+            if (response)
+                await sendNodeResponse(res, response);
         },
     });
-    // Declare the tables sync owns, so `farm sync migrate` can create them
-    // without re-reading or re-validating configuration.
-    return declareSchemaTables(plugin, {
-        name: "sync",
-        schema: options.schema,
-        // A model the app has not opened to the browser is not sync's to create.
-        models: Array.from(models.keys()),
-        dialect: options.dialect,
-        resolveClient: async () => {
-            if (options.client) {
-                return typeof options.client === "function"
-                    ? await options.client()
-                    : options.client;
-            }
-            if (options.storage) {
-                const { getStorage } = await import("@farm.js/core/storage");
-                return getStorage(options.storage);
-            }
+}
+async function handleSyncRequest(request, bodyOverride, options) {
+    const pathname = new URL(request.url).pathname;
+    if (pathname !== options.path)
+        return undefined;
+    if (request.method !== "POST") {
+        return jsonResponse(405, { error: { code: "invalid_input", message: "Sync uses POST." } });
+    }
+    // The development server invokes runtime hooks with a Request that carries
+    // headers but no body stream, and an upstream consumer can leave the body
+    // unreadable. Neither is a client error: fall through so the Node adapter,
+    // which can read the underlying stream, serves the request instead of this
+    // hook answering 400 for a perfectly valid POST. The Node adapter re-enters
+    // this handler with bodyOverride, so the origin check below still guards
+    // every served request exactly once.
+    if (bodyOverride === undefined && request.body === null)
+        return undefined;
+    // Sync operations ride the caller's cookies, and a cross-site page can send
+    // this POST as a simple request with no preflight. Reject foreign origins
+    // before touching the body, mirroring the server-action origin contract.
+    const origin = validateIntegrationRequestOrigin(request, {
+        allowedOrigins: options.allowedOrigins,
+        requireOriginMetadata: true,
+    });
+    if (!origin.ok) {
+        return jsonResponse(403, {
+            error: { code: "unauthorized", message: describeIntegrationOriginRejection(origin.reason) },
+        });
+    }
+    let body;
+    try {
+        body = bodyOverride ?? (await request.clone().json());
+    }
+    catch (error) {
+        if (bodyOverride === undefined && error?.name !== "SyntaxError") {
+            // clone() throws when the body was already consumed elsewhere; that is
+            // the runtime's shape, not the client's JSON.
             return undefined;
-        },
+        }
+        return jsonResponse(400, {
+            error: { code: "invalid_input", message: "Request body must be JSON." },
+        });
+    }
+    if (!body || typeof body.model !== "string" || typeof body.operation !== "string") {
+        return jsonResponse(400, {
+            error: { code: "invalid_input", message: "Request body needs `model` and `operation`." },
+        });
+    }
+    try {
+        const context = await runMiddleware(options.middleware, request);
+        const orm = await options.resolveOrm();
+        const result = await executeSyncOperation({
+            body,
+            models: options.models,
+            orm,
+            request,
+            context,
+        });
+        return jsonResponse(200, result);
+    }
+    catch (error) {
+        if (error instanceof SyncOperationError) {
+            return jsonResponse(error.status, {
+                error: { code: error.code, message: error.message },
+            });
+        }
+        // Never leak an internal message to the browser.
+        console.error("[farm:sync] operation failed", error);
+        return jsonResponse(500, {
+            error: { code: "server_error", message: "The sync operation failed." },
+        });
+    }
+}
+function jsonResponse(status, payload) {
+    return new Response(JSON.stringify(payload), {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8" },
     });
 }
+async function sendNodeResponse(res, response) {
+    res.statusCode = response.status;
+    response.headers.forEach((value, name) => res.setHeader?.(name, value));
+    res.end(Buffer.from(await response.arrayBuffer()));
+}
 async function runMiddleware(middleware, request) {
     let context = {};
     for (const entry of middleware ?? []) {
@@ -115,47 +198,64 @@ async function runMiddleware(middleware, request) {
     }
     return context;
 }
-async function resolveSyncClient(options, models) {
+/**
+ * The app's schema as sync owns it: exposed models are sync's tables, the rest
+ * are described but never created. `extend` is folded into the models first,
+ * so the app composing its own schema is never read as sync asking to add
+ * columns to the app's tables.
+ */
+function syncOwnedSchema(schema, exposed) {
+    const models = { ...schema.models };
+    for (const [key, extension] of Object.entries(schema.extend ?? {})) {
+        const existing = models[key];
+        models[key] = {
+            ...(existing ?? { fields: {} }),
+            ...(extension.name ? { name: extension.name } : {}),
+            ...(extension.description ? { description: extension.description } : {}),
+            fields: { ...existing?.fields, ...extension.fields },
+            constraints: [...(existing?.constraints ?? []), ...(extension.constraints ?? [])],
+            meta: { ...existing?.meta, ...extension.meta },
+        };
+    }
+    return {
+        ...schema,
+        extend: undefined,
+        models: Object.fromEntries(Object.entries(models).map(([key, model]) => [
+            key,
+            { ...model, external: !exposed.has(key) },
+        ])),
+    };
+}
+/** The connection or storage mount the app gave sync. */
+async function resolveSyncConnection(options) {
     if (options.client) {
-        const provided = typeof options.client === "function"
+        return typeof options.client === "function"
             ? await options.client()
             : options.client;
-        // Already model-shaped: an @farming-labs/orm client, or anything exposing
-        // the same four methods. Use it directly.
-        if (isModelClient(provided, models))
-            return provided;
-        return buildOrm(options.schema, provided);
     }
     if (options.storage) {
-        const mount = options.storage;
         // Imported lazily so the storage runtime never reaches a browser bundle.
         const { getStorage } = await import("@farm.js/core/storage");
         // A mount is an unstorage instance, which the orm runtime drives like any
         // other backend — so this is the same code path as a real database.
-        return buildOrm(options.schema, getStorage(mount));
+        return getStorage(options.storage);
     }
     throw new Error("sync(): no data source is configured. Set `storage` to a mount name from " +
         "storage.mounts in farm.config.ts, or pass `client` with your database connection.");
 }
+async function resolveSyncClient(options, models) {
+    const provided = await resolveSyncConnection(options);
+    // Already model-shaped: an @farming-labs/orm client, or anything exposing
+    // the same four methods. Use it directly.
+    if (options.client && isModelClient(provided, models))
+        return provided;
+    return buildOrm(options.schema, provided);
+}
 /** Let the orm runtime detect the driver and build the model client. */
 async function buildOrm(schema, client) {
     const { createIntegrationOrm } = await import("@farm.js/core");
     return (await createIntegrationOrm({ schema, client }));
 }
-/**
- * Write a JSON response using the Node primitives every Farm runtime provides.
- * The richer `res.status().json()` helpers are not present on every path.
- */
-function sendJson(res, status, payload) {
-    if (typeof res.writeHead === "function") {
-        res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
-        res.end(JSON.stringify(payload));
-        return;
-    }
-    res.statusCode = status;
-    res.setHeader?.("content-type", "application/json; charset=utf-8");
-    res.end(JSON.stringify(payload));
-}
 /** True when every exposed model is already reachable with the methods sync calls. */
 function isModelClient(value, models) {
     if (!value || typeof value !== "object")

package/dist/react.d.ts

@@ -1,5 +1,6 @@
-import { type SyncModelClient } from "./client.js";
-import type { SyncRow, SyncStoreStatus } from "./store.js";
+import { type SyncInsertOf, type SyncModelClient, type SyncModelName, type SyncMutationHandle, type SyncRowOf } from "./client.js";
+import type { SyncRow, SyncStoreStatus, SyncWriteFailure } from "./store.js";
+export type { SyncModelInputs, SyncModels } from "./client.js";
 export type LiveQueryOptions<TRow> = {
     orderBy?: (row: TRow) => string | number | Date;
     direction?: "asc" | "desc";
@@ -7,7 +8,7 @@ export type LiveQueryOptions<TRow> = {
     offset?: number;
     enabled?: boolean;
 };
-export type LiveQueryResult<TRow> = {
+export type LiveQueryResult<TRow, TInsert = TRow> = {
     rows: TRow[];
     status: SyncStoreStatus;
     error: Error | null;
@@ -15,8 +16,20 @@ export type LiveQueryResult<TRow> = {
     pending: number;
     /** Writes waiting for the connection to return. */
     paused: number;
+    /** Same as `paused`, named for what the user sees: queued until reconnect. */
+    queued: number;
     isEmpty: boolean;
     refresh(): Promise<void>;
+    /** @deprecated A query result is for reading; write through `useSyncAction(model).insert`. */
+    insert(input: TInsert): SyncMutationHandle<TRow>;
+    /** @deprecated Write through `useSyncAction(model).update`. */
+    update(key: unknown, patch: Partial<TRow>): SyncMutationHandle<TRow>;
+    /** @deprecated Write through `useSyncAction(model).delete`. */
+    delete(key: unknown): SyncMutationHandle<TRow>;
+    /** True once the server confirmed this row; false while it is optimistic. */
+    isPersisted(row: TRow): boolean;
+    /** Rolled-back writes awaiting the user, each with retry() and dismiss(). */
+    failures: readonly SyncWriteFailure[];
 };
 /**
  * Subscribe to rows of a model, filtered in the browser.
@@ -25,7 +38,50 @@ export type LiveQueryResult<TRow> = {
  * the browser, so any expression is fair game. Which rows reach the device is
  * decided separately by the server's row filter.
  */
+export declare function useLiveQuery<K extends SyncModelName>(model: K, predicate?: (row: SyncRowOf<K>) => boolean, options?: LiveQueryOptions<SyncRowOf<K>>): LiveQueryResult<SyncRowOf<K>, SyncInsertOf<K>>;
 export declare function useLiveQuery<TRow extends SyncRow = SyncRow>(model: SyncModelClient, predicate?: (row: TRow) => boolean, options?: LiveQueryOptions<TRow>): LiveQueryResult<TRow>;
 /** Subscribe to a single row by key. */
+export declare function useRow<K extends SyncModelName>(model: K, key: unknown): SyncRowOf<K> | undefined;
 export declare function useRow<TRow extends SyncRow = SyncRow>(model: SyncModelClient, key: unknown): TRow | undefined;
+export type SyncActionOptions<K extends SyncModelName, TInput> = {
+    /**
+     * What to show while the server decides, for transitions the input does not
+     * spell out. Left out, input fields that are schema columns become the
+     * patch; failing that the screen updates when the server's rows arrive.
+     */
+    optimistic?: Partial<SyncRowOf<K>> | ((input: TInput) => Partial<SyncRowOf<K>>);
+    /** Name shown in the failures queue; defaults to the function's name. */
+    name?: string;
+};
+export type SyncAction<TInput, TRow> = ((input: TInput) => SyncMutationHandle<TRow>) & {
+    /** Calls persisting right now. */
+    inFlight: number;
+    /** Calls waiting for the connection to return. */
+    queued: number;
+    /** Rolled-back calls awaiting the user, shared with the model's store. */
+    failures: readonly SyncWriteFailure[];
+};
+/** The plain write surface of a model, with the shared durability counters. */
+export type SyncModelActions<TRow, TInsert = TRow> = {
+    insert(input: TInsert): SyncMutationHandle<TRow>;
+    update(key: unknown, patch: Partial<TRow>): SyncMutationHandle<TRow>;
+    delete(key: unknown): SyncMutationHandle<TRow>;
+    /** Writes persisting right now. */
+    inFlight: number;
+    /** Writes waiting for the connection to return. */
+    queued: number;
+    /** Rolled-back writes awaiting the user, shared with the model's store. */
+    failures: readonly SyncWriteFailure[];
+};
+/**
+ * The mutation side of a model. `useLiveQuery` reads; this writes.
+ *
+ * The model-name form is the plain CRUD surface. The function form binds a
+ * server-defined action so calling it behaves like every other sync write:
+ * an optimistic layer when the effect is predictable, the returned rows
+ * committed into the store every live query reads, rollback into the
+ * failures queue when the server refuses.
+ */
+export declare function useSyncAction<K extends SyncModelName>(model: K): SyncModelActions<SyncRowOf<K>, SyncInsertOf<K>>;
+export declare function useSyncAction<K extends SyncModelName, TInput>(fn: (input: TInput) => Promise<unknown>, model: K, options?: SyncActionOptions<K, TInput>): SyncAction<TInput, SyncRowOf<K>>;
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAGA,OAAO,EAA8B,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAI3D,MAAM,MAAM,gBAAgB,CAAC,IAAI,IAAI;IACnC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAChD,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,eAAe,CAAC,IAAI,IAAI;IAClC,IAAI,EAAE,IAAI,EAAE,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO,EACzD,KAAK,EAAE,eAAe,EACtB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,EAClC,OAAO,GAAE,gBAAgB,CAAC,IAAI,CAAM,GACnC,eAAe,CAAC,IAAI,CAAC,CA6EvB;AAED,wCAAwC;AACxC,wBAAgB,MAAM,CAAC,IAAI,SAAS,OAAO,GAAG,OAAO,EACnD,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,OAAO,GACX,IAAI,GAAG,SAAS,CAYlB"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"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"}

package/dist/react.js

@@ -1,21 +1,14 @@
 "use client";
 import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
-import { getSyncStore, hydrateModel } from "./client.js";
+import { getSyncModelClient, getSyncStore, hydrateModel, runSyncAction, } from "./client.js";
 const EMPTY_ROWS = [];
-/**
- * Subscribe to rows of a model, filtered in the browser.
- *
- * The predicate runs over the model's rows on every change; it never leaves
- * the browser, so any expression is fair game. Which rows reach the device is
- * decided separately by the server's row filter.
- */
+const EMPTY_FAILURES = [];
+function resolveModelName(model) {
+    return typeof model === "string" ? model : model.__farmSyncModel;
+}
 export function useLiveQuery(model, predicate, options = {}) {
-    const name = model.__farmSyncModel;
+    const name = resolveModelName(model);
     const store = getSyncStore(name);
-    const predicateRef = useRef(predicate);
-    predicateRef.current = predicate;
-    const optionsRef = useRef(options);
-    optionsRef.current = options;
     const subscribe = useCallback((listener) => store.subscribe(listener), [store]);
     // Rows live in the browser, so the server has none. Both sides must agree on
     // that first snapshot or hydration mismatches; the real rows arrive on the
@@ -25,47 +18,93 @@ export function useLiveQuery(model, predicate, options = {}) {
     const error = useSyncExternalStore(subscribe, () => store.error, () => null);
     const pending = useSyncExternalStore(subscribe, () => store.pending, () => 0);
     const paused = useSyncExternalStore(subscribe, () => store.paused, () => 0);
+    const failures = useSyncExternalStore(subscribe, () => store.failures, () => EMPTY_FAILURES);
     useEffect(() => {
         if (options.enabled === false)
             return;
         hydrateModel(name);
     }, [name, options.enabled]);
-    // Recompute only when the underlying rows change; the predicate is read from
-    // a ref so an inline arrow does not invalidate the memo every render.
+    // The memo depends on the real predicate and options, not refs: a predicate
+    // that closes over changed state (row => row.status === filter) must produce
+    // fresh rows on the next render, not stay frozen until some row mutates. An
+    // inline arrow recomputes every render, which is the correct trade; a caller
+    // with a large collection keeps memoization by passing a stable predicate.
     const visible = useMemo(() => {
-        const current = predicateRef.current;
-        const opts = optionsRef.current;
-        let result = current ? rows.filter((row) => current(row)) : rows;
-        if (opts.orderBy) {
-            const direction = opts.direction === "desc" ? -1 : 1;
+        let result = predicate ? rows.filter((row) => predicate(row)) : rows;
+        if (options.orderBy) {
+            const direction = options.direction === "desc" ? -1 : 1;
+            const orderBy = options.orderBy;
             result = [...result].sort((a, b) => {
-                const left = opts.orderBy(a);
-                const right = opts.orderBy(b);
+                const left = orderBy(a);
+                const right = orderBy(b);
                 if (left === right)
                     return 0;
                 return (left < right ? -1 : 1) * direction;
             });
         }
-        if (opts.offset || opts.limit !== undefined) {
-            const start = opts.offset ?? 0;
-            result = result.slice(start, opts.limit === undefined ? undefined : start + opts.limit);
+        if (options.offset || options.limit !== undefined) {
+            const start = options.offset ?? 0;
+            result = result.slice(start, options.limit === undefined ? undefined : start + options.limit);
         }
         return result;
-    }, [rows]);
+    }, [rows, predicate, options.orderBy, options.direction, options.offset, options.limit]);
+    const client = useMemo(() => getSyncModelClient(name), [name]);
     return {
         rows: visible,
         status,
         error,
         pending,
         paused,
+        queued: paused,
         isEmpty: visible.length === 0,
-        refresh: () => model.refresh(),
+        refresh: () => client.refresh(),
+        insert: (input) => client.insert(input),
+        update: (key, patch) => client.update({
+            ...patch,
+            [store.descriptor.key]: key,
+        }),
+        delete: (key) => client.delete({ [store.descriptor.key]: key }),
+        isPersisted: (row) => store.isPersisted(row),
+        failures,
     };
 }
-/** Subscribe to a single row by key. */
 export function useRow(model, key) {
-    const store = getSyncStore(model.__farmSyncModel);
+    const store = getSyncStore(resolveModelName(model));
     const subscribe = useCallback((listener) => store.subscribe(listener), [store]);
     const rows = useSyncExternalStore(subscribe, () => store.getRows(), () => store.getRows());
     return useMemo(() => rows.find((row) => String(row[store.descriptor.key]) === String(key)), [rows, key, store.descriptor.key]);
 }
+export function useSyncAction(fnOrModel, maybeModel, options = {}) {
+    const fn = typeof fnOrModel === "function" ? fnOrModel : undefined;
+    const model = (typeof fnOrModel === "string" ? fnOrModel : maybeModel);
+    const store = getSyncStore(model);
+    const subscribe = useCallback((listener) => store.subscribe(listener), [store]);
+    const failures = useSyncExternalStore(subscribe, () => store.failures, () => EMPTY_FAILURES);
+    const inFlight = useSyncExternalStore(subscribe, () => store.pending, () => 0);
+    const queued = useSyncExternalStore(subscribe, () => store.paused, () => 0);
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const fnRef = useRef(fn);
+    fnRef.current = fn;
+    if (!fn) {
+        const client = getSyncModelClient(model);
+        const crud = {
+            insert: (input) => client.insert(input),
+            update: (key, patch) => client.update({ ...patch, [store.descriptor.key]: key }),
+            delete: (key) => client.delete({ [store.descriptor.key]: key }),
+            inFlight,
+            queued,
+            failures,
+        };
+        return crud;
+    }
+    const call = (input) => {
+        const current = optionsRef.current;
+        const bound = fnRef.current;
+        return runSyncAction(model, current.name || bound.name || "action", (value) => bound(value), input, (typeof current.optimistic === "function" ? current.optimistic(input) : current.optimistic));
+    };
+    call.inFlight = inFlight;
+    call.queued = queued;
+    call.failures = failures;
+    return call;
+}

package/dist/server.js

@@ -95,6 +95,9 @@ async function insertRow(client, resolved, scope, input) {
         }
         data[resolved.key] = generated;
     }
+    else {
+        requireScalarKey(resolved, data[resolved.key]);
+    }
     // Scope and cursor columns are server-owned: client-supplied values are
     // discarded so a caller cannot widen its scope or stall everyone's
     // incremental sync by writing a stale timestamp.
@@ -103,8 +106,15 @@ async function insertRow(client, resolved, scope, input) {
 async function updateRow(client, resolved, scope, input) {
     const data = sanitizeInput(resolved, input, { allowKey: false });
     const key = requireKey(resolved, input);
-    const where = { ...scope, [resolved.key]: key };
-    const updated = await client.update({ where, data: { ...data, ...cursorStamp(resolved) } });
+    // Scope columns are server-owned on update just like on insert: a client
+    // sending one must not move the row into another caller's scope.
+    for (const field of Object.keys(scope)) {
+        delete data[field];
+    }
+    const updated = await client.update({
+        where: scopedKeyFilter(resolved, scope, key),
+        data: { ...data, ...cursorStamp(resolved) },
+    });
     if (!updated) {
         throw new SyncOperationError("not_found", `No ${resolved.name} row matched ${String(key)} within the current scope.`, 404);
     }
@@ -112,7 +122,7 @@ async function updateRow(client, resolved, scope, input) {
 }
 async function deleteRow(client, resolved, scope, input) {
     const key = requireKey(resolved, input);
-    const deleted = await client.deleteMany({ where: { ...scope, [resolved.key]: key } });
+    const deleted = await client.deleteMany({ where: scopedKeyFilter(resolved, scope, key) });
     if (deleted === 0) {
         throw new SyncOperationError("not_found", `No ${resolved.name} row matched ${String(key)} within the current scope.`, 404);
     }
@@ -123,8 +133,29 @@ function requireKey(resolved, input) {
     if (key === undefined || key === null || key === "") {
         throw new SyncOperationError("invalid_input", `${resolved.name}.${resolved.key} is required for this operation.`);
     }
+    return requireScalarKey(resolved, key);
+}
+/**
+ * A key must address exactly one row. Objects are rejected because the orm
+ * reads them as operator filters — `{ not: null }` as a delete key would
+ * otherwise match every row in scope.
+ */
+function requireScalarKey(resolved, key) {
+    if (typeof key !== "string" && typeof key !== "number" && typeof key !== "boolean") {
+        throw new SyncOperationError("invalid_input", `${resolved.name}.${resolved.key} must be a single value.`);
+    }
     return key;
 }
+/**
+ * Combine the row filter with the client's key without letting one overwrite
+ * the other: when the filter itself scopes by the key column, a plain merge
+ * would let the client's key replace the scope entirely.
+ */
+function scopedKeyFilter(resolved, scope, key) {
+    if (Object.keys(scope).length === 0)
+        return { [resolved.key]: key };
+    return { AND: [scope, { [resolved.key]: key }] };
+}
 /** Drop unknown columns so a client cannot write outside the declared schema. */
 function sanitizeInput(resolved, input, options) {
     if (input !== undefined &&

package/dist/store.d.ts

@@ -4,12 +4,27 @@ export type SyncModelDescriptor = {
     access: "read" | "write";
     persist: boolean;
     cursor: string | null;
+    /** Schema column names, for deriving an action's optimistic patch from its
+     *  input. Absent on configs emitted before this field existed. */
+    fields?: readonly string[];
 };
 export type SyncRuntimeConfig = {
     path: string;
     models: Record<string, SyncModelDescriptor>;
 };
 export type SyncStoreStatus = "idle" | "loading" | "ready" | "error";
+/** A write the server refused, kept until the user retries or dismisses it. */
+export type SyncWriteFailure = {
+    id: number;
+    /** "insert" | "update" | "delete", or a server action name. */
+    operation: string;
+    input: unknown;
+    error: Error;
+    at: number;
+    /** Re-apply the optimistic state and send the write again. */
+    retry: () => unknown;
+    dismiss: () => void;
+};
 type OptimisticLayer = {
     type: "upsert";
     key: unknown;
@@ -36,6 +51,16 @@ export declare class SyncModelStore {
     cursor: string | null;
     pending: number;
     paused: number;
+    /** Rolled-back writes awaiting the user. Replaced, never mutated, so a
+     *  useSyncExternalStore snapshot of it stays referentially stable. */
+    failures: readonly SyncWriteFailure[];
+    /**
+     * Bumped by reset(). A load or write that started before a reset compares
+     * against it and drops its result, so a response for the previous session
+     * cannot land in the store after it was cleared.
+     */
+    generation: number;
+    private nextFailureId;
     constructor(name: string, descriptor: SyncModelDescriptor);
     subscribe(listener: () => void): () => void;
     /** Stable array identity between changes so `useSyncExternalStore` stays quiet. */
@@ -52,9 +77,24 @@ export declare class SyncModelStore {
     /** Fold a confirmed server row in and drop the layer that predicted it. */
     commitLayer(layer: OptimisticLayer, confirmed: SyncRow | null): void;
     mergeRow(key: unknown, changes: SyncRow): SyncRow;
+    /**
+     * Forget everything this store holds for a session change: confirmed rows,
+     * optimistic layers, recorded failures, and the incremental cursor. The next
+     * load is a full one, scoped to whoever is signed in by then.
+     */
+    reset(): void;
     /** Rows worth persisting: confirmed only, never optimistic guesses. */
     confirmedRows(): SyncRow[];
     hydrate(rows: SyncRow[], cursor: string | null): void;
+    /** True when no optimistic layer still shadows this row's key. */
+    isPersisted(row: SyncRow): boolean;
+    recordFailure(entry: {
+        operation: string;
+        input: unknown;
+        error: Error;
+        retry: () => unknown;
+    }): void;
+    dismissFailure(id: number): void;
     trackPending(delta: number): void;
     trackPaused(delta: number): void;
     private invalidate;

package/dist/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAErE,KAAK,eAAe,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC;AAErC;;;;GAIG;AACH,qBAAa,cAAc;IAcvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,UAAU,EAAE,mBAAmB;IAd1C,OAAO,CAAC,SAAS,CAA8B;IAC/C,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,aAAa,CAAQ;IAE7B,MAAM,EAAE,eAAe,CAAU;IACjC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAQ;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC7B,OAAO,SAAK;IACZ,MAAM,SAAK;gBAGA,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,mBAAmB;IAG1C,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,mFAAmF;IACnF,OAAO,IAAI,OAAO,EAAE;IAepB,GAAG,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS;IAItC,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,GAAE,KAAK,GAAG,IAAW,GAAG,IAAI;IAMpE,+EAA+E;IAC/E,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAWzF,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,IAAI;IAM5C,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAOzC,2EAA2E;IAC3E,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI;IAcpE,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;IAKjD,uEAAuE;IACvE,aAAa,IAAI,OAAO,EAAE;IAI1B,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAUrD,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKjC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKhC,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,IAAI;CAGb"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;sEACkE;IAClE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAErE,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,KAAK,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,KAAK,EAAE,MAAM,OAAO,CAAC;IACrB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,KAAK,eAAe,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC;AAErC;;;;GAIG;AACH,qBAAa,cAAc;IAwBvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,UAAU,EAAE,mBAAmB;IAxB1C,OAAO,CAAC,SAAS,CAA8B;IAC/C,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,aAAa,CAAQ;IAE7B,MAAM,EAAE,eAAe,CAAU;IACjC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAQ;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC7B,OAAO,SAAK;IACZ,MAAM,SAAK;IACX;0EACsE;IACtE,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAM;IAC3C;;;;OAIG;IACH,UAAU,SAAK;IACf,OAAO,CAAC,aAAa,CAAK;gBAGf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,mBAAmB;IAG1C,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,mFAAmF;IACnF,OAAO,IAAI,OAAO,EAAE;IAepB,GAAG,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS;IAItC,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,GAAE,KAAK,GAAG,IAAW,GAAG,IAAI;IAMpE,+EAA+E;IAC/E,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAWzF,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,IAAI;IAM5C,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAOzC,2EAA2E;IAC3E,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI;IAcpE,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;IAKjD;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAWb,uEAAuE;IACvE,aAAa,IAAI,OAAO,EAAE;IAI1B,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAUrD,kEAAkE;IAClE,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO;IAKlC,aAAa,CAAC,KAAK,EAAE;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,OAAO,CAAC;QACf,KAAK,EAAE,KAAK,CAAC;QACb,KAAK,EAAE,MAAM,OAAO,CAAC;KACtB,GAAG,IAAI;IAoBR,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMhC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKjC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKhC,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,IAAI;CAGb"}

package/dist/store.js

@@ -16,6 +16,16 @@ export class SyncModelStore {
     cursor = null;
     pending = 0;
     paused = 0;
+    /** Rolled-back writes awaiting the user. Replaced, never mutated, so a
+     *  useSyncExternalStore snapshot of it stays referentially stable. */
+    failures = [];
+    /**
+     * Bumped by reset(). A load or write that started before a reset compares
+     * against it and drops its result, so a response for the previous session
+     * cannot land in the store after it was cleared.
+     */
+    generation = 0;
+    nextFailureId = 1;
     constructor(name, descriptor) {
         this.name = name;
         this.descriptor = descriptor;
@@ -94,6 +104,21 @@ export class SyncModelStore {
         const current = this.get(key) ?? { [this.descriptor.key]: key };
         return { ...current, ...changes };
     }
+    /**
+     * Forget everything this store holds for a session change: confirmed rows,
+     * optimistic layers, recorded failures, and the incremental cursor. The next
+     * load is a full one, scoped to whoever is signed in by then.
+     */
+    reset() {
+        this.generation += 1;
+        this.confirmed.clear();
+        this.layers = [];
+        this.failures = [];
+        this.cursor = null;
+        this.status = "idle";
+        this.error = null;
+        this.invalidate();
+    }
     /** Rows worth persisting: confirmed only, never optimistic guesses. */
     confirmedRows() {
         return Array.from(this.confirmed.values());
@@ -109,6 +134,36 @@ export class SyncModelStore {
             this.status = "ready";
         this.invalidate();
     }
+    /** True when no optimistic layer still shadows this row's key. */
+    isPersisted(row) {
+        const key = String(row[this.descriptor.key]);
+        return !this.layers.some((layer) => String(layer.key) === key);
+    }
+    recordFailure(entry) {
+        const id = this.nextFailureId++;
+        const failure = {
+            id,
+            operation: entry.operation,
+            input: entry.input,
+            error: entry.error,
+            at: Date.now(),
+            // Retrying is a fresh write; the stale entry goes first so a second
+            // refusal records once instead of stacking duplicates.
+            retry: () => {
+                this.dismissFailure(id);
+                return entry.retry();
+            },
+            dismiss: () => this.dismissFailure(id),
+        };
+        this.failures = [...this.failures, failure];
+        this.emit();
+    }
+    dismissFailure(id) {
+        if (!this.failures.some((failure) => failure.id === id))
+            return;
+        this.failures = this.failures.filter((failure) => failure.id !== id);
+        this.emit();
+    }
     trackPending(delta) {
         this.pending = Math.max(0, this.pending + delta);
         this.emit();

package/dist/type-safety.typetest.d.ts

@@ -0,0 +1,35 @@
+declare module "./client.js" {
+    interface SyncModels {
+        tasks: {
+            id: string;
+            title: string;
+            status: "open" | "done" | "archived";
+        };
+        lists: {
+            id: string;
+            name: string;
+        };
+    }
+    interface SyncModelInputs {
+        tasks: {
+            id?: string;
+            title: string;
+            status?: "open" | "done" | "archived";
+        };
+        lists: {
+            id?: string;
+            name: string;
+        };
+    }
+}
+export declare function compileTimeContract(): {
+    title: string;
+    persisted: boolean;
+    handle: import("./client.js").SyncMutationHandle<{
+        id: string;
+        title: string;
+        status: "open" | "done" | "archived";
+    }>;
+    counts: number;
+};
+//# sourceMappingURL=type-safety.typetest.d.ts.map

package/dist/type-safety.typetest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-safety.typetest.d.ts","sourceRoot":"","sources":["../src/type-safety.typetest.ts"],"names":[],"mappings":"AAOA,OAAO,QAAQ,aAAa,CAAC;IAC3B,UAAU,UAAU;QAClB,KAAK,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAA;SAAE,CAAC;QAC3E,KAAK,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;KACrC;IACD,UAAU,eAAe;QACvB,KAAK,EAAE;YAAE,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAA;SAAE,CAAC;QAC7E,KAAK,EAAE;YAAE,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;KACtC;CACF;AAED,wBAAgB,mBAAmB;;;;YATlB,MAAM;eAAS,MAAM;gBAAU,MAAM,GAAG,MAAM,GAAG,UAAU;;;EA2D3E"}

package/dist/type-safety.typetest.js

@@ -0,0 +1,50 @@
+/**
+ * Compile-time contract for the generated SyncModels map. Never imported at
+ * runtime; `pnpm --filter @farm.js/sync type-check` fails if any expectation
+ * breaks. Mirrors what the generated farm.d.ts does in an app.
+ */
+import { useLiveQuery, useSyncAction } from "./react.js";
+export function compileTimeContract() {
+    const tasks = useLiveQuery("tasks", (t) => t.status === "open");
+    // Rows and writes are typed from the model the first argument names.
+    const title = tasks.rows[0].title;
+    tasks.insert({ title: "typed" }); // id and status optional per the input map
+    tasks.update("t1", { status: "done" });
+    const persisted = tasks.isPersisted(tasks.rows[0]);
+    // @ts-expect-error unknown model name
+    useLiveQuery("task", () => true);
+    // @ts-expect-error no such field on tasks
+    useLiveQuery("tasks", (t) => t.stauts === "open");
+    // @ts-expect-error "opne" is outside the enum union
+    useLiveQuery("tasks", (t) => t.status === "opne");
+    // @ts-expect-error the row type follows the named model: lists has no status
+    useLiveQuery("lists", (t) => t.status === "open");
+    // @ts-expect-error unknown insert field
+    tasks.insert({ titel: "typo" });
+    // @ts-expect-error title is required on insert
+    tasks.insert({ status: "open" });
+    // The model-name form is the plain write surface; reads never mutate.
+    const writes = useSyncAction("tasks");
+    writes.insert({ title: "typed" });
+    writes.update("t1", { status: "done" });
+    const counts = writes.inFlight + writes.queued;
+    // @ts-expect-error unknown insert field on the CRUD form
+    writes.insert({ titel: "typo" });
+    // @ts-expect-error unknown model on the CRUD form
+    useSyncAction("task");
+    const complete = useSyncAction((input) => Promise.resolve(input), "tasks", {
+        optimistic: { status: "done" },
+    });
+    const handle = complete({ id: "t1" });
+    // The function form works too when the patch depends on the input.
+    useSyncAction((input) => Promise.resolve(input), "tasks", {
+        optimistic: (input) => ({ title: input.note }),
+    });
+    // @ts-expect-error unknown model on an action binding
+    useSyncAction((input) => Promise.resolve(input), "task");
+    useSyncAction((input) => Promise.resolve(input), "tasks", {
+        // @ts-expect-error the optimistic patch is checked against the model's row
+        optimistic: { status: "opne" },
+    });
+    return { title, persisted, handle, counts };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farm.js/sync",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.11",
   "description": "Local-first collections for Farm.js: schema-driven reads, optimistic writes, offline queueing",
   "keywords": [
     "farm.js",
@@ -40,15 +40,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@farm.js/core": "0.1.0-beta.103"
+    "@farm.js/core": "0.1.6"
   },
   "devDependencies": {
     "@farming-labs/orm": "0.0.62",
     "@farming-labs/orm-runtime": "0.0.62",
     "@types/node": "^20.10.5",
     "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "jsdom": "^25.0.0",
     "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "typescript": "^5.3.3",
     "unstorage": "^1.16.1",
     "vitest": "^3.2.7"