@teincfood/core 0.10.26 → 0.10.28

package/dist/catalog/hooks.d.ts

@@ -17,19 +17,36 @@ export declare function useMenuItemsQuery(filters?: {
     data: unknown[] | undefined;
 };
 export declare function useMenuCategoriesQuery(): ReturnType<typeof useQuery>;
-export declare function useCreateMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, Record<string, unknown>, unknown>;
-export declare function useUpdateMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, {
+type QuerySnapshot = Array<[readonly unknown[], unknown]>;
+export declare function useCreateMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, Record<string, unknown>, {
+    prev: QuerySnapshot;
+}>;
+export declare function useUpdateMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, {
     id: string;
     payload: Record<string, unknown>;
-}, unknown>;
-export declare function useDeleteMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, string, unknown>;
-export declare function useToggleItemAvailabilityMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, {
+}, {
+    prev: QuerySnapshot;
+}>;
+export declare function useDeleteMenuItemMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, string, {
+    prev: QuerySnapshot;
+}>;
+export declare function useToggleItemAvailabilityMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, {
     id: string;
     available: boolean;
-}, unknown>;
-export declare function useCreateMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, Record<string, unknown>, unknown>;
-export declare function useUpdateMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, {
+    cacheRecord?: unknown;
+}, {
+    prev: QuerySnapshot;
+}>;
+export declare function useCreateMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, Record<string, unknown>, {
+    prev: QuerySnapshot;
+}>;
+export declare function useUpdateMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, {
     id: string;
     payload: Record<string, unknown>;
-}, unknown>;
-export declare function useDeleteMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, string, unknown>;
+}, {
+    prev: QuerySnapshot;
+}>;
+export declare function useDeleteMenuCategoryMutation(): import("@tanstack/react-query").UseMutationResult<import("..").DomainEvent<unknown>, Error, string, {
+    prev: QuerySnapshot;
+}>;
+export {};

package/dist/catalog/hooks.js

@@ -11,8 +11,7 @@ import { menuService } from "../adapters/services";
 import { getReferenceData } from "../reference/operations";
 import { openSyncDatabase } from "../db/connection";
 import { referenceSyncService } from "../reference/service";
-import { emitReferenceChanged } from "../reference/events";
-import { runOfflineCapableMutation } from "../sync/offline-capable";
+import { commitMenuMutationLocal } from "../sync/offline-capable";
 import { useIsEffectivelyOnline } from "../hooks/use-infinite-list";
 export const CATALOG_KEYS = {
     all: ["menu"],
@@ -72,10 +71,21 @@ export function useMenuItemsQuery(filters, enabled = true) {
     const networkData = networkQuery.data?.pages
         ? networkQuery.data.pages.flatMap((p) => p.data)
         : undefined;
-    const data = isOnline && networkData !== undefined ? networkData : enabled ? filtered : undefined;
     // A local snapshot (even an empty list) means the POS has something to
     // render: never gate the whole screen on the in-flight network refresh.
     const hasLocalSnapshot = cachedQuery.data != null;
+    // Local SQLite is the read model whenever it has a snapshot. The network
+    // query is only a cold-start fallback; it must never resurrect a row that
+    // was deleted/updated locally and is still waiting to sync.
+    const data = hasLocalSnapshot
+        ? enabled
+            ? filtered
+            : undefined
+        : isOnline && networkData !== undefined
+            ? networkData
+            : enabled
+                ? filtered
+                : undefined;
     const pending = cachedQuery.isPending || (!hasLocalSnapshot && networkQuery.isFetching);
     return {
         data,
@@ -119,9 +129,14 @@ export function useMenuCategoriesQuery() {
         retry: false,
         networkMode: "offlineFirst",
     });
-    const usingNetwork = isOnline && networkQuery.data;
-    const data = usingNetwork ? networkQuery.data : cachedQuery.data;
     const hasCache = cachedQuery.data != null;
+    // Local categories are authoritative once a snapshot exists. The network
+    // response must not re-show a category that was just deleted offline.
+    const data = hasCache
+        ? cachedQuery.data
+        : isOnline
+            ? networkQuery.data
+            : cachedQuery.data;
     // Only report "loading" when there is nothing local to show; the network
     // refresh must never hide an already-cached category list.
     const pending = cachedQuery.isPending || (!hasCache && networkQuery.isFetching);
@@ -134,107 +149,229 @@ export function useMenuCategoriesQuery() {
         error: hasCache ? null : networkQuery.error,
     };
 }
-// Mutations — offline-capable
+function restoreQuerySnapshots(qc, snapshot) {
+    if (!snapshot)
+        return;
+    for (const [key, data] of snapshot) {
+        qc.setQueryData(key, data);
+    }
+}
+function recordId(record) {
+    const id = record?.id;
+    return id == null ? undefined : String(id);
+}
+/**
+ * Patch a menu query payload regardless of shape: the SQLite-backed query is
+ * `{ data: [...] }`, the network query is `{ pages: [{ data: [...] }] }`.
+ * This lets one optimistic patch update every mounted variant at once.
+ */
+function patchMenuRows(old, patch) {
+    if (Array.isArray(old))
+        return patch(old);
+    if (!old || typeof old !== "object")
+        return old;
+    const obj = old;
+    if (Array.isArray(obj.data)) {
+        return { ...obj, data: patch(obj.data) };
+    }
+    if (Array.isArray(obj.pages)) {
+        return {
+            ...obj,
+            pages: obj.pages.map((page) => {
+                if (!page || typeof page !== "object")
+                    return page;
+                const p = page;
+                return Array.isArray(p.data) ? { ...p, data: patch(p.data) } : page;
+            }),
+        };
+    }
+    return old;
+}
+function upsertMenuRow(rows, record) {
+    const id = recordId(record);
+    if (!id)
+        return rows;
+    const index = rows.findIndex((row) => recordId(row) === id);
+    if (index >= 0) {
+        return rows.map((row, i) => i === index ? { ...row, ...record } : row);
+    }
+    return [record, ...rows];
+}
+function removeMenuRow(rows, id) {
+    return rows.filter((row) => recordId(row) !== id);
+}
+function useOptimisticMenuPatch() {
+    const qc = useQueryClient();
+    const snapshot = (queryKey) => qc.getQueriesData({ queryKey });
+    return { qc, snapshot, restore: (s) => restoreQuerySnapshots(qc, s) };
+}
+// Mutations — local-first.
+//
+// The only work on the mutation path is the local SQLite commit. Reference
+// fan-out and cloud/LAN replay are scheduled by commitMenuMutationLocal AFTER
+// the outbox row exists, so a slow or absent network can never delay a save.
+// Invalidating the cached query key makes the committed row render immediately.
 export function useCreateMenuItemMutation() {
     const businessId = useBusinessId();
-    const qc = useQueryClient();
+    const { qc, snapshot, restore } = useOptimisticMenuPatch();
     return useMutation({
-        mutationFn: (payload) => {
-            // cacheRecord is local-cache only — never on the wire.
-            const { cacheRecord: _omit, ...wire } = payload;
-            void _omit;
-            return runOfflineCapableMutation({ run: () => menuService.createMenuItem(wire), commandType: "menu:create_item", businessId: businessId, entityId: payload.id, payload });
+        mutationFn: (payload) => commitMenuMutationLocal({
+            commandType: "menu:create_item",
+            businessId: businessId,
+            entityId: payload.id,
+            payload,
+        }),
+        onMutate: (payload) => {
+            const record = payload.cacheRecord;
+            const prev = snapshot(CATALOG_KEYS.items(businessId));
+            if (record) {
+                qc.setQueriesData({ queryKey: CATALOG_KEYS.items(businessId) }, (old) => patchMenuRows(old, (rows) => upsertMenuRow(rows, record)));
+            }
+            return { prev };
         },
+        onError: (_error, _vars, ctx) => restore(ctx?.prev),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:items"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
         },
     });
 }
 export function useUpdateMenuItemMutation() {
     const businessId = useBusinessId();
-    const qc = useQueryClient();
+    const { qc, snapshot, restore } = useOptimisticMenuPatch();
     return useMutation({
-        mutationFn: ({ id, payload }) => {
-            const { cacheRecord: _omit, ...wire } = payload;
-            void _omit;
-            return runOfflineCapableMutation({ run: () => menuService.updateMenuItem(id, wire), commandType: "menu:update_item", businessId: businessId, entityId: id, payload });
+        mutationFn: ({ id, payload }) => commitMenuMutationLocal({
+            commandType: "menu:update_item",
+            businessId: businessId,
+            entityId: id,
+            payload,
+        }),
+        onMutate: ({ payload }) => {
+            const record = payload.cacheRecord;
+            const prev = snapshot(CATALOG_KEYS.items(businessId));
+            if (record) {
+                qc.setQueriesData({ queryKey: CATALOG_KEYS.items(businessId) }, (old) => patchMenuRows(old, (rows) => upsertMenuRow(rows, record)));
+            }
+            return { prev };
         },
+        onError: (_error, _vars, ctx) => restore(ctx?.prev),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:items"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
         },
     });
 }
 export function useDeleteMenuItemMutation() {
     const businessId = useBusinessId();
-    const qc = useQueryClient();
+    const { qc, snapshot, restore } = useOptimisticMenuPatch();
     return useMutation({
-        mutationFn: (id) => runOfflineCapableMutation({ run: () => menuService.deleteMenuItem(id), commandType: "menu:delete_item", businessId: businessId, entityId: id, payload: { id } }),
+        mutationFn: (id) => commitMenuMutationLocal({
+            commandType: "menu:delete_item",
+            businessId: businessId,
+            entityId: id,
+            payload: { id },
+        }),
+        onMutate: (id) => {
+            const prev = snapshot(CATALOG_KEYS.items(businessId));
+            qc.setQueriesData({ queryKey: CATALOG_KEYS.items(businessId) }, (old) => patchMenuRows(old, (rows) => removeMenuRow(rows, id)));
+            return { prev };
+        },
+        onError: (_error, _vars, ctx) => restore(ctx?.prev),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:items"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
         },
     });
 }
 export function useToggleItemAvailabilityMutation() {
     const businessId = useBusinessId();
-    const qc = useQueryClient();
+    const { qc, snapshot, restore } = useOptimisticMenuPatch();
     return useMutation({
-        // Availability is an update_item with an availability patch — same engine
-        // route (cloud → LAN → queue), same cache convergence.
-        mutationFn: ({ id, available }) => runOfflineCapableMutation({ run: () => menuService.updateMenuItem(id, { available }), commandType: "menu:update_item", businessId: businessId, entityId: id, payload: { id, available } }),
+        mutationFn: ({ id, available, cacheRecord }) => commitMenuMutationLocal({
+            commandType: "menu:update_item",
+            businessId: businessId,
+            entityId: id,
+            payload: cacheRecord ? { id, available, cacheRecord } : { id, available },
+        }),
+        onMutate: ({ id, available, cacheRecord }) => {
+            const prev = snapshot(CATALOG_KEYS.items(businessId));
+            const record = cacheRecord && typeof cacheRecord === "object"
+                ? { ...cacheRecord, id, available }
+                : undefined;
+            qc.setQueriesData({ queryKey: CATALOG_KEYS.items(businessId) }, (old) => patchMenuRows(old, (rows) => rows.map((row) => recordId(row) === id
+                ? record ?? { ...row, available }
+                : row)));
+            return { prev };
+        },
+        onError: (_error, _vars, ctx) => restore(ctx?.prev),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:items"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.items(businessId) });
         },
     });
 }
 export function useCreateMenuCategoryMutation() {
     const businessId = useBusinessId();
-    const qc = useQueryClient();
+    const { qc, snapshot, restore } = useOptimisticMenuPatch();
     return useMutation({
-        mutationFn: (payload) => {
-            const { cacheRecord: _omit, ...wire } = payload;
-            void _omit;
-            return runOfflineCapableMutation({ run: () => menuService.createCategory(businessId, wire), commandType: "menu:create_category", businessId: businessId, entityId: payload.id, payload });
+        mutationFn: (payload) => commitMenuMutationLocal({
+            commandType: "menu:create_category",
+            businessId: businessId,
+            entityId: payload.id,
+            payload,
+        }),
+        onMutate: (payload) => {
+            const record = payload.cacheRecord;
+            const prev = snapshot(CATALOG_KEYS.categories(businessId));
+            if (record) {
+                qc.setQueriesData({ queryKey: CATALOG_KEYS.categories(businessId) }, (old) => patchMenuRows(old, (rows) => upsertMenuRow(rows, record)));
+            }
+            return { prev };
         },
+        onError: (_error, _vars, ctx) => restore(ctx?.prev),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:categories"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
         },
     });
 }
 export function useUpdateMenuCategoryMutation() {
     const businessId = useBusinessId();
-    const qc = useQueryClient();
+    const { qc, snapshot, restore } = useOptimisticMenuPatch();
     return useMutation({
-        mutationFn: ({ id, payload }) => {
-            const { cacheRecord: _omit, ...wire } = payload;
-            void _omit;
-            return runOfflineCapableMutation({ run: () => menuService.updateCategory(id, wire), commandType: "menu:update_category", businessId: businessId, entityId: id, payload: { ...payload, id } });
+        mutationFn: ({ id, payload }) => commitMenuMutationLocal({
+            commandType: "menu:update_category",
+            businessId: businessId,
+            entityId: id,
+            payload: { ...payload, id },
+        }),
+        onMutate: ({ payload }) => {
+            const record = payload.cacheRecord;
+            const prev = snapshot(CATALOG_KEYS.categories(businessId));
+            if (record) {
+                qc.setQueriesData({ queryKey: CATALOG_KEYS.categories(businessId) }, (old) => patchMenuRows(old, (rows) => upsertMenuRow(rows, record)));
+            }
+            return { prev };
         },
+        onError: (_error, _vars, ctx) => restore(ctx?.prev),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:categories"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
         },
     });
 }
 export function useDeleteMenuCategoryMutation() {
     const businessId = useBusinessId();
-    const qc = useQueryClient();
+    const { qc, snapshot, restore } = useOptimisticMenuPatch();
     return useMutation({
-        mutationFn: (id) => runOfflineCapableMutation({ run: () => menuService.deleteCategory(id), commandType: "menu:delete_category", businessId: businessId, entityId: id, payload: { id } }),
+        mutationFn: (id) => commitMenuMutationLocal({
+            commandType: "menu:delete_category",
+            businessId: businessId,
+            entityId: id,
+            payload: { id },
+        }),
+        onMutate: (id) => {
+            const prev = snapshot(CATALOG_KEYS.categories(businessId));
+            qc.setQueriesData({ queryKey: CATALOG_KEYS.categories(businessId) }, (old) => patchMenuRows(old, (rows) => removeMenuRow(rows, id)));
+            return { prev };
+        },
+        onError: (_error, _vars, ctx) => restore(ctx?.prev),
         onSuccess: () => {
-            qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
-            if (businessId)
-                emitReferenceChanged(businessId, ["menu:categories"]);
+            void qc.invalidateQueries({ queryKey: CATALOG_KEYS.categories(businessId) });
         },
     });
 }

package/dist/db/migrations.js

@@ -497,4 +497,29 @@ export const MIGRATIONS = [
         `);
         },
     },
+    {
+        version: 15,
+        up: async (db) => {
+            // Delete tombstones for mutable reference collections.
+            //
+            // A full-array reference pull from the cloud/LAN must never resurrect a
+            // row that was deleted locally while offline. Tombstones are retained
+            // until a newer record with the same id arrives or the row is recreated
+            // locally. This is the delete half of LWW; mutable-record versioning
+            // will build on the same table.
+            await db.execAsync(`
+          CREATE TABLE IF NOT EXISTS record_tombstones (
+            business_id TEXT NOT NULL,
+            collection TEXT NOT NULL,
+            entity_id TEXT NOT NULL,
+            deleted_at TEXT NOT NULL,
+            device_id TEXT,
+            PRIMARY KEY (business_id, collection, entity_id)
+          );
+
+          CREATE INDEX IF NOT EXISTS idx_record_tombstones_collection
+            ON record_tombstones(business_id, collection);
+        `);
+        },
+    },
 ];

package/dist/db/operations.js

@@ -516,6 +516,10 @@ export async function wipeForNewInstall(db) {
         await db.execAsync(`DELETE FROM reference_data;`);
     }
     catch { }
+    try {
+        await db.execAsync(`DELETE FROM record_tombstones;`);
+    }
+    catch { }
     try {
         await db.execAsync(`DELETE FROM commands;`);
     }
@@ -531,6 +535,12 @@ export async function wipeForNewInstall(db) {
 }
 export async function clearReferenceData(db) {
     await db.execAsync(`DELETE FROM reference_data;`);
+    try {
+        await db.execAsync(`DELETE FROM record_tombstones;`);
+    }
+    catch {
+        // Older schema before migration 15.
+    }
 }
 const dbChangeListeners = new Set();
 export function subscribeDbChanges(listener) {

package/dist/index.d.ts

@@ -73,8 +73,8 @@ export { localNodeTransport } from "./sync/transport-local-node";
 export * from "./sync/transport-local-node";
 export * from "./sync/order-snapshots.service";
 export { hydratePendingOrders, applyPendingOrderEvent, applyOrderStateChangeEvent } from "./sync/pending-orders.service";
-export { runOfflineCapableMutation } from "./sync/offline-capable";
-export type { OfflineCapableOptions } from "./sync/offline-capable";
+export { commitMenuMutationLocal, runOfflineCapableMutation } from "./sync/offline-capable";
+export type { LocalMenuMutationOptions, OfflineCapableOptions } from "./sync/offline-capable";
 export { orderRepository } from "./repositories/order.repository";
 export type { CreateOrderInput, AssignRiderInput, OrderActionInput } from "./repositories/order.repository";
 export { posRepository } from "./repositories/pos.repository";

package/dist/index.js

@@ -75,7 +75,7 @@ export { localNodeTransport } from "./sync/transport-local-node";
 export * from "./sync/transport-local-node";
 export * from "./sync/order-snapshots.service";
 export { hydratePendingOrders, applyPendingOrderEvent, applyOrderStateChangeEvent } from "./sync/pending-orders.service";
-export { runOfflineCapableMutation } from "./sync/offline-capable";
+export { commitMenuMutationLocal, runOfflineCapableMutation } from "./sync/offline-capable";
 // ── Repositories ──
 export { orderRepository } from "./repositories/order.repository";
 export { posRepository } from "./repositories/pos.repository";

package/dist/reference/menu-apply.d.ts

@@ -7,7 +7,7 @@ export declare const MENU_CATEGORY_KEY: ReferenceDataKey;
  * (for reference_data.changed fan-out) and whether anything was written.
  * Idempotent by entity id: re-applying the same command converges.
  */
-export declare function applyMenuCommandLocal(businessId: string, command: Pick<Command, "command_type" | "entity_id" | "command_id" | "payload">): Promise<{
+export declare function applyMenuCommandLocal(businessId: string, command: Pick<Command, "command_type" | "entity_id" | "command_id" | "payload" | "timestamp">): Promise<{
     keys: ReferenceDataKey[];
     applied: boolean;
 }>;

package/dist/reference/menu-apply.js

@@ -18,6 +18,7 @@ import { syncLogger } from "../utils/sync-logger";
 import { generateUUID } from "../utils/uuid";
 import { hlcToString, tickHLC, hlcFromString } from "../utils/hlc";
 import { getAppInstanceId } from "../adapters/devices";
+import { clearRecordTombstone, markRecordDeleted } from "./tombstones";
 export const MENU_ITEM_KEY = "menu:items";
 export const MENU_CATEGORY_KEY = "menu:categories";
 function asArray(payload) {
@@ -90,6 +91,7 @@ async function patchKey(businessId, key, patch) {
 export async function applyMenuCommandLocal(businessId, command) {
     const payload = (command.payload ?? {});
     const idOf = (v) => (typeof v === "string" && v ? v : null);
+    const stamp = command.timestamp ?? new Date().toISOString();
     switch (command.command_type) {
         case "menu:create_item": {
             const id = idOf(command.entity_id) ?? idOf(payload.id) ?? generateUUID();
@@ -103,6 +105,7 @@ export async function applyMenuCommandLocal(businessId, command) {
                 stashPrior(arr, businessId, id);
                 return arr.some((o) => String(o.id) === id) ? arr.map((o) => (String(o.id) === id ? item : o)) : [...arr, item];
             });
+            await clearRecordTombstone(await openSyncDatabase(), businessId, MENU_ITEM_KEY, id);
             return { keys: [MENU_ITEM_KEY], applied };
         }
         case "menu:update_item": {
@@ -118,6 +121,7 @@ export async function applyMenuCommandLocal(businessId, command) {
                 stashPrior(arr, businessId, id);
                 return arr.map((o) => (String(o.id) === id ? { ...record, id } : o));
             });
+            await clearRecordTombstone(await openSyncDatabase(), businessId, MENU_ITEM_KEY, id);
             return { keys: [MENU_ITEM_KEY], applied };
         }
         case "menu:delete_item": {
@@ -125,6 +129,7 @@ export async function applyMenuCommandLocal(businessId, command) {
             if (!id)
                 return { keys: [MENU_ITEM_KEY], applied: false };
             const applied = await patchKey(businessId, MENU_ITEM_KEY, (arr) => arr.filter((o) => String(o.id) !== id));
+            await markRecordDeleted(await openSyncDatabase(), businessId, MENU_ITEM_KEY, id, stamp);
             return { keys: [MENU_ITEM_KEY], applied };
         }
         case "menu:create_category": {
@@ -139,6 +144,7 @@ export async function applyMenuCommandLocal(businessId, command) {
                 stashPrior(arr, businessId, id);
                 return arr.some((o) => String(o.id) === id) ? arr.map((o) => (String(o.id) === id ? cat : o)) : [...arr, cat];
             });
+            await clearRecordTombstone(await openSyncDatabase(), businessId, MENU_CATEGORY_KEY, id);
             return { keys: [MENU_CATEGORY_KEY], applied };
         }
         case "menu:update_category": {
@@ -154,6 +160,7 @@ export async function applyMenuCommandLocal(businessId, command) {
                 stashPrior(arr, businessId, id);
                 return arr.map((o) => (String(o.id) === id ? { ...record, id } : o));
             });
+            await clearRecordTombstone(await openSyncDatabase(), businessId, MENU_CATEGORY_KEY, id);
             return { keys: [MENU_CATEGORY_KEY], applied };
         }
         case "menu:delete_category": {
@@ -161,6 +168,7 @@ export async function applyMenuCommandLocal(businessId, command) {
             if (!id)
                 return { keys: [MENU_CATEGORY_KEY], applied: false };
             const applied = await patchKey(businessId, MENU_CATEGORY_KEY, (arr) => arr.filter((o) => String(o.id) !== id));
+            await markRecordDeleted(await openSyncDatabase(), businessId, MENU_CATEGORY_KEY, id, stamp);
             return { keys: [MENU_CATEGORY_KEY], applied };
         }
         default:

package/dist/reference/operations.js

@@ -7,6 +7,7 @@ import { openSyncDatabase } from "../db/connection";
 import { getAppInstanceId } from "../adapters/devices";
 import { notifyDbChange } from "../db/operations";
 import { isServerAuthoritativeKey } from "./entitlements";
+import { applyTombstonesToPayload } from "./tombstones";
 export async function getReferenceData(db, businessId, key) {
     const row = await db.getFirstAsync("SELECT * FROM reference_data WHERE business_id = ? AND key = ?;", businessId, key);
     if (!row)
@@ -44,11 +45,14 @@ export async function mergeReferenceData(db, businessId, key, incoming, hlc, eve
     if (isServerAuthoritativeKey(key))
         return;
     const existing = await getReferenceData(db, businessId, key);
+    // Local deletes win over stale full-array pulls. This must run before the
+    // cache is written so a deleted menu row can never be resurrected.
+    const incomingWithoutTombstones = await applyTombstonesToPayload(db, businessId, key, incoming);
     if (!existing) {
         await setReferenceData(db, businessId, {
             key,
             version: hlc,
-            payload: incoming,
+            payload: incomingWithoutTombstones,
             downloadedAt: new Date().toISOString(),
             lastEventId: eventId,
             lastHlc: hlc,
@@ -63,7 +67,7 @@ export async function mergeReferenceData(db, businessId, key, incoming, hlc, eve
     await setReferenceData(db, businessId, {
         key,
         version: hlc,
-        payload: incoming,
+        payload: incomingWithoutTombstones,
         downloadedAt: new Date().toISOString(),
         lastEventId: eventId,
         lastHlc: hlc,

package/dist/reference/tombstones.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Delete tombstones for mutable reference collections.
+ *
+ * LWW alone is not enough for deletes: a stale full-array pull would simply
+ * re-add a row that was removed on this device. A tombstone records the
+ * deletion locally so every reference write filters it out until either:
+ *
+ *   - a newer record with the same id arrives (server clock wins), or
+ *   - the user recreates the row locally (explicit local intent wins).
+ *
+ * Collections are keyed by reference-data key today. The same table will be
+ * used by the per-record HLC migration for menu/category/settings data.
+ */
+import type { SQLiteDatabase } from "../adapters/sqlite";
+import type { ReferenceDataKey } from "./types";
+export declare function tombstoneCollectionFor(key: ReferenceDataKey): string | null;
+export declare function markRecordDeleted(db: SQLiteDatabase, businessId: string, key: ReferenceDataKey, entityId: string, deletedAt: string, deviceId?: string): Promise<void>;
+export declare function clearRecordTombstone(db: SQLiteDatabase, businessId: string, key: ReferenceDataKey, entityId: string): Promise<void>;
+/**
+ * Filter a reference payload against local delete tombstones.
+ *
+ * A row whose `updated_at` is newer than the tombstone is a real recreation
+ * (for example, another device re-created the same id) and wins; its
+ * tombstone is cleared. Everything else stays deleted locally.
+ */
+export declare function applyTombstonesToPayload<T>(db: SQLiteDatabase, businessId: string, key: ReferenceDataKey, payload: T): Promise<T>;

package/dist/reference/tombstones.js

@@ -0,0 +1,97 @@
+/**
+ * Delete tombstones for mutable reference collections.
+ *
+ * LWW alone is not enough for deletes: a stale full-array pull would simply
+ * re-add a row that was removed on this device. A tombstone records the
+ * deletion locally so every reference write filters it out until either:
+ *
+ *   - a newer record with the same id arrives (server clock wins), or
+ *   - the user recreates the row locally (explicit local intent wins).
+ *
+ * Collections are keyed by reference-data key today. The same table will be
+ * used by the per-record HLC migration for menu/category/settings data.
+ */
+import { getAppInstanceId } from "../adapters/devices";
+const TOMBSTONE_COLLECTIONS = {
+    "menu:items": "menu:items",
+    "menu:categories": "menu:categories",
+};
+export function tombstoneCollectionFor(key) {
+    return TOMBSTONE_COLLECTIONS[key] ?? null;
+}
+export async function markRecordDeleted(db, businessId, key, entityId, deletedAt, deviceId = getAppInstanceId()) {
+    const collection = tombstoneCollectionFor(key);
+    if (!collection || !businessId || !entityId)
+        return;
+    await db.runAsync(`
+      INSERT INTO record_tombstones (
+        business_id, collection, entity_id, deleted_at, device_id
+      ) VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(business_id, collection, entity_id) DO UPDATE SET
+        deleted_at = excluded.deleted_at,
+        device_id = excluded.device_id
+      WHERE excluded.deleted_at > record_tombstones.deleted_at;
+    `, businessId, collection, String(entityId), deletedAt, deviceId);
+}
+export async function clearRecordTombstone(db, businessId, key, entityId) {
+    const collection = tombstoneCollectionFor(key);
+    if (!collection || !businessId || !entityId)
+        return;
+    await db.runAsync("DELETE FROM record_tombstones WHERE business_id = ? AND collection = ? AND entity_id = ?;", businessId, collection, String(entityId));
+}
+function rowId(row) {
+    const id = row?.id;
+    return id == null ? null : String(id);
+}
+function rowStamp(row) {
+    const rec = row;
+    const raw = rec?.updated_at ?? rec?.inserted_at;
+    const parsed = typeof raw === "string" ? Date.parse(raw) : NaN;
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+/**
+ * Filter a reference payload against local delete tombstones.
+ *
+ * A row whose `updated_at` is newer than the tombstone is a real recreation
+ * (for example, another device re-created the same id) and wins; its
+ * tombstone is cleared. Everything else stays deleted locally.
+ */
+export async function applyTombstonesToPayload(db, businessId, key, payload) {
+    const collection = tombstoneCollectionFor(key);
+    if (!collection || !businessId || payload == null)
+        return payload;
+    const tombstones = await db.getAllAsync("SELECT entity_id, deleted_at FROM record_tombstones WHERE business_id = ? AND collection = ?;", businessId, collection);
+    if (tombstones.length === 0)
+        return payload;
+    const deletedAt = new Map(tombstones.map((row) => [row.entity_id, row.deleted_at]));
+    const resurrected = [];
+    const filterRows = (rows) => rows.filter((row) => {
+        const id = rowId(row);
+        if (!id)
+            return true;
+        const deleted = deletedAt.get(id);
+        if (!deleted)
+            return true;
+        if (rowStamp(row) > Date.parse(deleted)) {
+            resurrected.push(id);
+            return true;
+        }
+        return false;
+    });
+    let next = payload;
+    if (Array.isArray(payload)) {
+        next = filterRows(payload);
+    }
+    else if (typeof payload === "object") {
+        const obj = payload;
+        if (Array.isArray(obj.data)) {
+            next = { ...obj, data: filterRows(obj.data) };
+        }
+    }
+    if (resurrected.length > 0) {
+        for (const id of resurrected) {
+            await clearRecordTombstone(db, businessId, key, id);
+        }
+    }
+    return next;
+}

package/dist/sync/offline-capable.d.ts

@@ -10,6 +10,7 @@
  *
  * Keeps the online path and its result shape unchanged.
  */
+import type { DomainEvent } from "./types";
 export interface OfflineCapableOptions<TService, TCommandPayload> {
     /** Direct REST call — used online. */
     run: () => Promise<TService>;
@@ -19,4 +20,24 @@ export interface OfflineCapableOptions<TService, TCommandPayload> {
     entityId?: string;
     payload: TCommandPayload;
 }
+export interface LocalMenuMutationOptions<TCommandPayload> {
+    /** Must be a `menu:*` command. */
+    commandType: string;
+    businessId: string;
+    entityId?: string;
+    payload: TCommandPayload;
+}
+/**
+ * The ONLY menu write path.
+ *
+ * Local SQLite is the source of truth: capability/entitlement checks read the
+ * cached proof, the menu row is applied to the reference cache, and the
+ * command is inserted into the durable outbox. All of that completes before
+ * this promise resolves. No HTTP, connectivity probe, image upload, reference
+ * pull, LAN call, or replay is allowed here.
+ *
+ * Consumers must treat the returned event as the committed local state and
+ * close the form immediately. Sync is a separate background worker.
+ */
+export declare function commitMenuMutationLocal<TCommandPayload>(options: LocalMenuMutationOptions<TCommandPayload>): Promise<DomainEvent>;
 export declare function runOfflineCapableMutation<TService, TCommandPayload>(options: OfflineCapableOptions<TService, TCommandPayload>): Promise<TService>;

package/dist/sync/offline-capable.js

@@ -46,49 +46,97 @@ async function assertCachedCapability(businessId, required) {
             throw e;
     }
 }
-export async function runOfflineCapableMutation(options) {
-    // Online-required gate first: these commands can never succeed offline —
-    // throw loud immediately instead of queuing what no transport can fulfill.
-    assertOnlineFor(options.commandType, options.payload);
-    // Per-command capability guard before touching local state or the network.
-    const required = CAPABILITY_BY_COMMAND[options.commandType];
-    // Local-first for engine-routed domains (menu:*): persist to SQLite and the
-    // durable outbox immediately, update the local reference cache, and let
-    // replay upload to the cloud/LAN in the background. A slow or absent
-    // network must never hold the form open.
-    if (options.commandType.startsWith("menu:")) {
-        if (required)
-            await assertCachedCapability(options.businessId, required);
-        // Preserve the entitlement gate that the engine normally applies before
-        // queueing: local-first must not weaken subscription enforcement.
-        await assertEntitledForCommand(options.businessId, options.commandType);
-        const command = buildCommand({
-            commandType: options.commandType,
-            businessId: options.businessId,
-            entityId: options.entityId,
-            payload: options.payload,
-        });
-        try {
-            const { keys } = await applyMenuCommandLocal(options.businessId, command);
-            if (keys.length)
-                emitReferenceChanged(options.businessId, keys);
-        }
-        catch (error) {
-            syncLogger.debug("OfflineCapable", "menu local apply failed", {
-                error: String(error),
-            });
+/**
+ * Publish fan-out only after the local transaction has committed.
+ *
+ * This is deliberately scheduled off the mutation's promise: reference sync
+ * and replay are downstream of SQLite, never a prerequisite for it. If either
+ * fails, the local row and outbox stay intact for the next retry.
+ */
+function scheduleMenuPostCommit(businessId, keys) {
+    setTimeout(() => {
+        if (keys.length > 0) {
+            try {
+                emitReferenceChanged(businessId, keys);
+            }
+            catch (error) {
+                syncLogger.debug("OfflineCapable", "menu reference fan-out failed", {
+                    error: String(error),
+                });
+            }
         }
-        const event = await commandQueueService.enqueue(command);
         if (isOnlineCapable()) {
-            // Background only: save must return now.
             void syncEngine.replayQueuedCommands().catch((error) => {
                 syncLogger.debug("OfflineCapable", "menu background replay failed", {
                     error: String(error),
                 });
             });
         }
+    }, 0);
+}
+/**
+ * The ONLY menu write path.
+ *
+ * Local SQLite is the source of truth: capability/entitlement checks read the
+ * cached proof, the menu row is applied to the reference cache, and the
+ * command is inserted into the durable outbox. All of that completes before
+ * this promise resolves. No HTTP, connectivity probe, image upload, reference
+ * pull, LAN call, or replay is allowed here.
+ *
+ * Consumers must treat the returned event as the committed local state and
+ * close the form immediately. Sync is a separate background worker.
+ */
+export async function commitMenuMutationLocal(options) {
+    if (!options.commandType.startsWith("menu:")) {
+        throw new Error(`commitMenuMutationLocal only accepts menu:* commands, got ${options.commandType}`);
+    }
+    // Cached permission proof — local reads only. The backend remains the final
+    // authority when the queued command replays.
+    const required = CAPABILITY_BY_COMMAND[options.commandType];
+    if (required)
+        await assertCachedCapability(options.businessId, required);
+    await assertEntitledForCommand(options.businessId, options.commandType);
+    const command = buildCommand({
+        commandType: options.commandType,
+        businessId: options.businessId,
+        entityId: options.entityId,
+        payload: options.payload,
+    });
+    // 1) local read model, 2) durable outbox. Both are local writes.
+    let keys = [];
+    try {
+        const applied = await applyMenuCommandLocal(options.businessId, command);
+        keys = applied.keys;
+    }
+    catch (error) {
+        // The outbox row is still authoritative and will re-apply on replay.
+        syncLogger.debug("OfflineCapable", "menu local apply failed", {
+            error: String(error),
+        });
+    }
+    const event = await commandQueueService.enqueue(command);
+    // 3) only now may the rest of the system hear about it.
+    scheduleMenuPostCommit(options.businessId, keys);
+    return event;
+}
+export async function runOfflineCapableMutation(options) {
+    // Menu writes have a dedicated local-first API. Keep this branch for legacy
+    // callers (e.g. image upload follow-ups) but route it through the same
+    // commit-only implementation.
+    if (options.commandType.startsWith("menu:")) {
+        const event = await commitMenuMutationLocal({
+            commandType: options.commandType,
+            businessId: options.businessId,
+            entityId: options.entityId,
+            payload: options.payload,
+        });
         return event.payload;
     }
+    // Online-required gate first: these commands can never succeed offline —
+    // throw loud immediately instead of queuing what no transport can fulfill.
+    assertOnlineFor(options.commandType, options.payload);
+    // Per-command capability guard before touching local state or the network.
+    const required = CAPABILITY_BY_COMMAND[options.commandType];
     if (required)
         await assertCachedCapability(options.businessId, required);
     try {

package/dist/test-helpers/memory-driver.js

@@ -7,6 +7,7 @@ export function createMemoryDriver() {
         events: [],
         orders: [],
         sync_jobs: [],
+        record_tombstones: [],
     };
     let autoId = { commands: 1, events: 1, migrations: 1, sync_jobs: 1 };
     const driver = {
@@ -23,6 +24,34 @@ export function createMemoryDriver() {
                 tables.migrations.push({ version, applied_at: args[1] });
                 return { lastInsertRowId: autoId.migrations++, changes: 1 };
             }
+            // record_tombstones upsert
+            if (s.includes("INSERT INTO record_tombstones")) {
+                const [business_id, collection, entity_id, deleted_at, device_id] = args;
+                const existing = tables.record_tombstones.find((r) => r.business_id === business_id &&
+                    r.collection === collection &&
+                    r.entity_id === entity_id);
+                if (existing) {
+                    if (String(deleted_at) > String(existing.deleted_at)) {
+                        existing.deleted_at = deleted_at;
+                        existing.device_id = device_id;
+                    }
+                }
+                else {
+                    tables.record_tombstones.push({ business_id, collection, entity_id, deleted_at, device_id });
+                }
+                return { lastInsertRowId: 1, changes: 1 };
+            }
+            if (s.includes("DELETE FROM record_tombstones WHERE business_id = ? AND collection = ? AND entity_id = ?")) {
+                const [business_id, collection, entity_id] = args;
+                tables.record_tombstones = tables.record_tombstones.filter((r) => !(r.business_id === business_id &&
+                    r.collection === collection &&
+                    r.entity_id === entity_id));
+                return { lastInsertRowId: 0, changes: 1 };
+            }
+            if (s.includes("DELETE FROM record_tombstones")) {
+                tables.record_tombstones = [];
+                return { lastInsertRowId: 0, changes: 1 };
+            }
             // reference_data insert
             if (s.includes("INSERT INTO reference_data")) {
                 const [business_id, key, version, payload, downloaded_at, last_event_id, last_hlc] = args;
@@ -389,6 +418,18 @@ export function createMemoryDriver() {
         },
         async getAllAsync(sql, ...args) {
             const s = sql.replace(/\s+/g, " ").trim();
+            if (s.includes("SELECT entity_id, deleted_at FROM record_tombstones WHERE business_id = ? AND collection = ?")) {
+                const [business_id, collection] = args;
+                return tables.record_tombstones
+                    .filter((r) => r.business_id === business_id && r.collection === collection)
+                    .map((r) => ({ entity_id: r.entity_id, deleted_at: r.deleted_at }));
+            }
+            if (s.includes("SELECT entity_id FROM record_tombstones WHERE business_id = ? AND entity_id = ?")) {
+                const [business_id, entity_id] = args;
+                return tables.record_tombstones
+                    .filter((r) => r.business_id === business_id && r.entity_id === entity_id)
+                    .map((r) => ({ entity_id: r.entity_id }));
+            }
             if (s.includes("SELECT key FROM reference_data WHERE business_id = ? ORDER BY key")) {
                 const [business_id] = args;
                 return tables.reference_data.filter((r) => r.business_id === business_id).map((r) => ({ key: r.key }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teincfood/core",
-  "version": "0.10.26",
+  "version": "0.10.28",
   "description": "TeincFood shared offline-first core — types, sync engine, local DB, reference data, and repositories for mobile + desktop",
   "type": "module",
   "main": "dist/index.js",