@teincfood/core 0.9.22 → 0.9.24

package/dist/sync/sync-jobs.service.js

@@ -4,7 +4,8 @@
  * Core-only, single in_flight per business, coalesced via isOnline gate.
  */
 import { openSyncDatabase } from "../db/connection";
-import { insertOrder, getOrderById, markOrderSyncFailed } from "../db/operations";
+import { markOrderSyncFailed } from "../db/operations";
+import { mergeOrderFromServer } from "./order-merge";
 import { getConnectivityState, subscribeConnectivity } from "../adapters/connectivity";
 import { getRefreshToken, setAuthTokens, clearAuth, subscribeAuth } from "../adapters/auth";
 import { getActiveBusiness, subscribeBusiness } from "../adapters/business";
@@ -267,22 +268,19 @@ async function tryRest(businessId, payload, commandType) {
     }
 }
 /**
- * Already-applied absorb for sync_jobs rows: pull server truth, and if the
- * order is already at this command's target status, complete the job. Only
- * fires when the pull actually touched the row (hlc change) so a stale
- * local optimistic write can never delete work the server never applied.
+ * Already-applied absorb for sync_jobs rows: the server already moved the
+ * order to this command's target status, so the queued job is redundant.
+ *
+ * The comparison uses the SERVER status reported by the pull — never the
+ * local row, which may show the device's own queued intent.
  */
 async function absorbSyncJobIfApplied(db, businessId, entityId, commandType, jobId) {
     const target = getQueuedStatus(commandType);
     if (!target || !entityId)
         return false;
-    const before = await db.getFirstAsync(`SELECT hlc FROM orders WHERE business_id = ? AND id = ?;`, businessId, entityId);
-    await pullRemoteOrders(businessId);
-    const afterHlc = await db.getFirstAsync(`SELECT hlc FROM orders WHERE business_id = ? AND id = ?;`, businessId, entityId);
-    if (!afterHlc || afterHlc.hlc === before?.hlc)
-        return false;
-    const order = await getOrderById(db, businessId, entityId);
-    if (order && order.status === target) {
+    const serverStatuses = await pullRemoteOrders(businessId);
+    const serverStatus = serverStatuses.get(entityId);
+    if (serverStatus === target) {
         await db.runAsync(`UPDATE sync_jobs SET status='completed', updated_at=? WHERE id=?;`, new Date().toISOString(), jobId);
         syncLogger.info("SyncJobs", "Transition already applied on server, absorbing job", {
             businessId,
@@ -379,7 +377,10 @@ export async function drainOne(businessId, entityId) {
     inflight.set(key, new Promise((r) => { resolveInflight = r; }));
     try {
         const db = await openSyncDatabase();
-        const row = await db.getFirstAsync(`SELECT * FROM sync_jobs WHERE business_id = ? AND entity_id = ? AND status='pending' ORDER BY created_at LIMIT 1;`, businessId, entityId);
+        // FIFO with a stable tiebreaker: two commands created in the same
+        // millisecond (fast taps) must still drain in insertion order, otherwise
+        // a transition can overtake the command it depends on.
+        const row = await db.getFirstAsync(`SELECT * FROM sync_jobs WHERE business_id = ? AND entity_id = ? AND status='pending' ORDER BY created_at ASC, rowid ASC LIMIT 1;`, businessId, entityId);
         syncLogger.debug("SyncJobs", "drainOne fetched row", { businessId, entityId, found: !!row, command_type: row?.command_type });
         if (!row) {
             syncLogger.debug("SyncJobs", "drainOne no pending row", { businessId, entityId });
@@ -423,7 +424,7 @@ export async function drainOne(businessId, entityId) {
                 syncLogger.info("SyncJobs", "Drained via PHX", { businessId, entityId });
                 clearRetry(businessId);
                 try {
-                    const next = await db.getFirstAsync(`SELECT id FROM sync_jobs WHERE business_id=? AND entity_id=? AND status='pending' ORDER BY created_at LIMIT 1;`, businessId, entityId);
+                    const next = await db.getFirstAsync(`SELECT id FROM sync_jobs WHERE business_id=? AND entity_id=? AND status='pending' ORDER BY created_at ASC, rowid ASC LIMIT 1;`, businessId, entityId);
                     if (next)
                         setTimeout(() => void drainOne(businessId, entityId), 50);
                 }
@@ -444,7 +445,7 @@ export async function drainOne(businessId, entityId) {
             clearRetry(businessId);
             // Immediately drain next pending for same entity (FIFO chain: create -> prepare -> ready -> pickup should sync in order without waiting for timer)
             try {
-                const next = await db.getFirstAsync(`SELECT id FROM sync_jobs WHERE business_id=? AND entity_id=? AND status='pending' ORDER BY created_at LIMIT 1;`, businessId, entityId);
+                const next = await db.getFirstAsync(`SELECT id FROM sync_jobs WHERE business_id=? AND entity_id=? AND status='pending' ORDER BY created_at ASC, rowid ASC LIMIT 1;`, businessId, entityId);
                 if (next) {
                     syncLogger.debug("SyncJobs", "chaining next job for same entity", { businessId, entityId });
                     // fire next without inflight block — we already cleared inflight for this key, so recurse
@@ -632,27 +633,36 @@ export async function drainOne(businessId, entityId) {
         syncLogger.debug("SyncJobs", "drainOne exit", { businessId, entityId });
     }
 }
+/**
+ * Pull the server's recent orders into the local read model.
+ *
+ * Returns the SERVER status per order id. The local row can show a
+ * different status (a queued transition keeps the device's intent on top of
+ * the server copy), so a caller that needs to know what the server actually
+ * holds must read it from this map — never from the merged local row.
+ */
 export async function pullRemoteOrders(businessId) {
+    const serverStatuses = new Map();
     if (!businessId || !canBusinessSync(businessId)) {
         syncLogger.debug("SyncJobs", "pullRemoteOrders early-return — no business/auth", { businessId });
-        return;
+        return serverStatuses;
     }
     const onlineForRest = isOnlineForRest();
     syncLogger.debug("SyncJobs", "pullRemoteOrders entry", { businessId, onlineForRest, hasToken: isAuthenticated() });
     if (!onlineForRest) {
         syncLogger.debug("SyncJobs", "pullRemoteOrders early-return gate", { businessId, onlineForRest, hasToken: isAuthenticated(), connectivity: getConnectivityState() });
-        return;
+        return serverStatuses;
     }
     // Respect a global 429 cooldown for background pulls.
     if (isRateLimited()) {
         syncLogger.debug("SyncJobs", "pullRemoteOrders skipped — rate limited", { businessId });
-        return;
+        return serverStatuses;
     }
     try {
         const http = getHttpClient();
         if (!http) {
             syncLogger.debug("SyncJobs", "pullRemoteOrders no http client", { businessId });
-            return;
+            return serverStatuses;
         }
         // Gradual recent-first pull for single business — page 1 immediate, then background older pages (max 5 pages = 100 recent)
         let page = 1;
@@ -671,10 +681,14 @@ export async function pullRemoteOrders(businessId) {
                 const db = await openSyncDatabase();
                 for (const o of data) {
                     try {
-                        await insertOrder(db, o);
+                        // Server truth — but a pending local command keeps its intent
+                        // (see order-merge). Never let a pull revert queued work.
+                        await mergeOrderFromServer(db, businessId, o);
+                        if (o?.id && o?.status)
+                            serverStatuses.set(o.id, o.status);
                     }
                     catch (e) {
-                        syncLogger.debug("SyncJobs", "pullRemoteOrders insertOrder fail", { err: String(e) });
+                        syncLogger.debug("SyncJobs", "pullRemoteOrders merge fail", { err: String(e) });
                     }
                 }
                 // persist page 1 to snapshot for offline fallback
@@ -706,6 +720,51 @@ export async function pullRemoteOrders(businessId) {
     catch (e) {
         syncLogger.debug("SyncJobs", "pullRemoteDeliveries error", { err: String(e) });
     }
+    return serverStatuses;
+}
+/**
+ * Fetch exactly ONE order from the server and merge it into the local
+ * read model.
+ *
+ * Used when a realtime `order.created` event arrives for an order this
+ * device has never seen: the event carries only a summary, so the order has
+ * to be fetched — but fetching the whole list (100 orders, several pages,
+ * heavy serialization) for one new order is pure waste on the backend.
+ *
+ * Uses the existing business-scoped list endpoint with an `order_number`
+ * filter, so no backend change is required.
+ */
+export async function fetchRemoteOrderByNumber(businessId, orderNumber) {
+    if (!businessId || !orderNumber)
+        return false;
+    if (!canBusinessSync(businessId))
+        return false;
+    if (!isOnlineForRest())
+        return false;
+    if (isRateLimited())
+        return false;
+    try {
+        const http = getHttpClient();
+        if (!http)
+            return false;
+        await paceSync();
+        const res = await http.get(`/businesses/${businessId}/orders`, { params: { order_number: orderNumber, page_size: 1 } });
+        const payload = res.data;
+        const rows = payload?.data ?? [];
+        const first = rows[0];
+        if (!first?.id) {
+            syncLogger.debug("SyncJobs", "fetchRemoteOrderByNumber — no row returned", { businessId, orderNumber });
+            return false;
+        }
+        const db = await openSyncDatabase();
+        await mergeOrderFromServer(db, businessId, first);
+        syncLogger.info("SyncJobs", "Fetched single remote order", { businessId, orderNumber, id: first.id });
+        return true;
+    }
+    catch (e) {
+        syncLogger.debug("SyncJobs", "fetchRemoteOrderByNumber failed", { businessId, orderNumber, err: String(e) });
+        return false;
+    }
 }
 export async function drainPending(businessId) {
     if (!businessId || !canBusinessSync(businessId)) {
@@ -720,7 +779,7 @@ export async function drainPending(businessId) {
         return;
     }
     const db = await openSyncDatabase();
-    const rows = await db.getAllAsync(`SELECT entity_id FROM sync_jobs WHERE business_id=? AND status='pending' ORDER BY created_at LIMIT 20;`, businessId);
+    const rows = await db.getAllAsync(`SELECT entity_id FROM sync_jobs WHERE business_id=? AND status='pending' ORDER BY created_at ASC, rowid ASC LIMIT 20;`, businessId);
     syncLogger.debug("SyncJobs", "drainPending found rows", { businessId, count: rows.length, rows });
     for (const r of rows) {
         await drainOne(businessId, r.entity_id);

package/dist/sync/types.d.ts

@@ -27,6 +27,13 @@ export interface EventMetadata {
 }
 export interface DomainEvent<T = unknown> extends EventMetadata {
     payload: T;
+    /**
+     * Where the event came from. Optional for backwards compatibility, but the
+     * journal stores it: "local" (this device), "cloud" (Phoenix push) or
+     * "lan" (mesh peer). A cloud event must not be re-hydrated as a pending
+     * local command after a restart.
+     */
+    origin?: "local" | "lan" | "cloud";
 }
 export interface CommandMetadata {
     /** Globally unique command identifier (UUID v4). Used for idempotency. */

package/dist/sync/use-sync-reconciliation.js

@@ -11,6 +11,7 @@ import { useEffect } from "react";
 import { useQueryClient } from "@tanstack/react-query";
 import { syncEngine } from "./engine";
 import { getActiveBusiness } from "../adapters/business";
+import { useGlobalRealtimeBridge } from "../realtime/realtime-bridge";
 import { applyPendingOrderEvent, applyOrderStateChangeEvent, registerPendingOrdersInvalidator, } from "./pending-orders.service";
 import { localNodeService } from "../adapters/local-node";
 import { getSyncDatabase } from "../db/connection";
@@ -29,6 +30,10 @@ function isLocalOrderEvent(event) {
 const RECONCILE_DEBOUNCE_MS = 400;
 export function useSyncReconciliation() {
     const queryClient = useQueryClient();
+    // Single app-wide Phoenix subscription. Mounting it here means one root
+    // `useSyncReconciliation` is enough for the whole app — screens no longer
+    // need their own realtime subscription.
+    useGlobalRealtimeBridge();
     useEffect(() => {
         let timer;
         const pending = new Set();
@@ -102,12 +107,16 @@ export function useSyncReconciliation() {
                 !localNodeService.isLocalNode()) {
                 localNodeService.getClient()?.publishEvent?.(event);
             }
+            // Where the event came from: a Phoenix push is "cloud", a LAN relay is
+            // "lan", everything produced on this device is "local". The journal
+            // stores it so a cloud event is never re-hydrated as pending local work.
+            const origin = event.origin ?? "local";
             // Reference data changed (locally or echoed from the cloud): re-sync the
             // affected keys and refresh caches on this device.
-            await applyReferenceChangeEvent(event, "local");
+            await applyReferenceChangeEvent(event, origin);
             // Order/delivery state changed: refresh order caches so this terminal
             // shows the same order states as the device that made the change.
-            await applyOrderStateChangeEvent(event, "local");
+            await applyOrderStateChangeEvent(event, origin);
             // Any order/delivery event should refresh dashboard recent orders immediately (fresh on transition)
             if (event.event_type.startsWith("order.") || event.event_type.startsWith("delivery.")) {
                 schedule("pending");
@@ -116,7 +125,7 @@ export function useSyncReconciliation() {
             // into the pending-orders store.
             if (event.event_type === "order.create_queued" ||
                 event.event_type === "order.created") {
-                await applyPendingOrderEvent(event, "local");
+                await applyPendingOrderEvent(event, origin);
             }
             if (event.event_type === "order.created" && isLocalOrderEvent(event)) {
                 try {

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

@@ -8,7 +8,7 @@ export function createMemoryDriver() {
         orders: [],
         sync_jobs: [],
     };
-    let autoId = { commands: 1, events: 1, migrations: 1 };
+    let autoId = { commands: 1, events: 1, migrations: 1, sync_jobs: 1 };
     const driver = {
         async execAsync(_sql) {
             // No-op: CREATE TABLE / INDEX / ALTER all just ensure table array exists.
@@ -191,9 +191,12 @@ export function createMemoryDriver() {
             if (s.includes("INSERT INTO orders")) {
                 const [id, business_id, order_number, callout_number, status, order_type, is_pos, items, subtotal_minor, total_minor, tax_minor, tax_lines, payment, customer_name, customer_phone, pos_payment_method, delivery_id, business, user, inserted_at, hlc] = args;
                 const existing = tables.orders.find((r) => r.id === id);
-                // LWW check via hlc (if existing and incoming older, skip)
+                // LWW check via hlc (if existing and incoming older, skip) — only for
+                // the local/LAN write path. The server write path (`upsertServerOrder`)
+                // has no hlc guard: the server copy always wins.
+                const lwwGuarded = s.includes("excluded.hlc >= orders.hlc");
                 if (existing) {
-                    if (hlc && existing.hlc && hlc < existing.hlc)
+                    if (lwwGuarded && hlc && existing.hlc && hlc < existing.hlc)
                         return { lastInsertRowId: 0, changes: 0 };
                     Object.assign(existing, { business_id, order_number, callout_number, status, order_type, is_pos, items, subtotal_minor, total_minor, tax_minor, tax_lines, payment, customer_name, customer_phone, pos_payment_method, delivery_id, business, user, inserted_at, hlc });
                     return { lastInsertRowId: 0, changes: 1 };
@@ -206,7 +209,7 @@ export function createMemoryDriver() {
                 const [id, business_id, command_type, entity_id, payload, created_at, updated_at] = args;
                 if (tables.sync_jobs.find((r) => r.id === id))
                     return { lastInsertRowId: 0, changes: 0 };
-                tables.sync_jobs.push({ id, business_id, command_type, entity_id, payload, status: "pending", attempts: 0, created_at, updated_at });
+                tables.sync_jobs.push({ rowid: autoId.sync_jobs++, id, business_id, command_type, entity_id, payload, status: "pending", attempts: 0, created_at, updated_at });
                 return { lastInsertRowId: 1, changes: 1 };
             }
             // sync_jobs update status=completed
@@ -365,6 +368,15 @@ export function createMemoryDriver() {
                 const row = tables.sync_jobs.find((r) => r.business_id === business_id && r.entity_id === entity_id && r.status === "pending");
                 return row ?? null;
             }
+            // sync_jobs duplicate-command probe (transition coalescing)
+            if (s.includes("SELECT id FROM sync_jobs WHERE business_id = ? AND entity_id = ? AND command_type = ?")) {
+                const [business_id, entity_id, command_type] = args;
+                const row = tables.sync_jobs.find((r) => r.business_id === business_id &&
+                    r.entity_id === entity_id &&
+                    r.command_type === command_type &&
+                    r.status === "pending");
+                return row ?? null;
+            }
             // generic orders exists check for migrations backfill: SELECT * FROM orders WHERE business_id=? (not needed)
             return null;
         },
@@ -479,10 +491,19 @@ export function createMemoryDriver() {
                 const [business_id] = args;
                 const m = s.match(/LIMIT\s+(\d+)/);
                 const lim = m ? parseInt(m[1], 10) : 20;
-                let rows = tables.sync_jobs.filter((r) => r.business_id === business_id && r.status === "pending").sort((a, b) => (a.created_at < b.created_at ? -1 : 1)).map((r) => ({ entity_id: r.entity_id }));
+                let rows = tables.sync_jobs.filter((r) => r.business_id === business_id && r.status === "pending").sort((a, b) => (a.created_at < b.created_at ? -1 : a.created_at > b.created_at ? 1 : a.rowid - b.rowid)).map((r) => ({ entity_id: r.entity_id }));
                 rows = rows.slice(0, lim);
                 return rows;
             }
+            // sync_jobs command list for a single entity (pending intent)
+            if (s.includes("FROM sync_jobs WHERE business_id = ? AND entity_id = ?")) {
+                const [business_id, entity_id] = args;
+                const rows = tables.sync_jobs
+                    .filter((r) => r.business_id === business_id && r.entity_id === entity_id && r.status === "pending")
+                    .sort((a, b) => (a.created_at < b.created_at ? -1 : a.created_at > b.created_at ? 1 : a.rowid - b.rowid))
+                    .map((r) => ({ command_type: r.command_type }));
+                return rows;
+            }
             if (s.includes("SELECT * FROM sync_jobs WHERE") || s.includes("SELECT id, command_type, status, created_at FROM sync_jobs")) {
                 const [business_id] = args;
                 const rows = tables.sync_jobs.filter((r) => r.business_id === business_id);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@teincfood/core",
-  "version": "0.9.22",
-  "description": "TeincFood shared offline-first core — types, sync engine, local DB, reference data, and repositories for mobile + desktop",
+  "version": "0.9.24",
+  "description": "TeincFood shared offline-first core \u2014 types, sync engine, local DB, reference data, and repositories for mobile + desktop",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",