@teincfood/core 0.7.8 → 0.8.0

package/dist/reference/operations.d.ts

@@ -3,6 +3,7 @@
  */
 import type { SQLiteDatabase } from "../adapters/sqlite";
 import type { ReferenceDataKey, ReferenceDataRecord } from "./types";
+import type { OperatingHoursEntry } from "../types/api/business.api";
 export declare function getReferenceData<T>(db: SQLiteDatabase, businessId: string, key: ReferenceDataKey): Promise<ReferenceDataRecord<T> | null>;
 export declare function getReferenceVersion(db: SQLiteDatabase, businessId: string, key: ReferenceDataKey): Promise<string | null>;
 export declare function setReferenceData<T>(db: SQLiteDatabase, businessId: string, record: ReferenceDataRecord<T>): Promise<void>;
@@ -10,3 +11,5 @@ export declare function mergeReferenceData<T extends Record<string, unknown>>(db
 export declare function deleteReferenceData(db: SQLiteDatabase, businessId: string, key: ReferenceDataKey): Promise<void>;
 export declare function deleteReferenceDataForBusiness(db: SQLiteDatabase, businessId: string): Promise<void>;
 export declare function getAllReferenceDataKeys(db: SQLiteDatabase, businessId: string): Promise<ReferenceDataKey[]>;
+export declare function setOperatingHoursLocal(businessId: string, entries: OperatingHoursEntry[]): Promise<void>;
+export declare function setBusinessProfileLocal(businessId: string, profile: Record<string, unknown>): Promise<void>;

package/dist/reference/operations.js

@@ -1,6 +1,11 @@
 /**
  * SQLite operations for the business-scoped reference data cache.
  */
+import { compareHLCString, hlcToString, tickHLC, hlcFromString } from "../utils/hlc";
+import { generateUUID } from "../utils/uuid";
+import { openSyncDatabase } from "../db/connection";
+import { getAppInstanceId } from "../adapters/devices";
+import { notifyDbChange } from "../db/operations";
 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)
@@ -29,9 +34,9 @@ export async function setReferenceData(db, businessId, record) {
         last_event_id = excluded.last_event_id,
         last_hlc = excluded.last_hlc;
     `, businessId, record.key, record.version, JSON.stringify(record.payload), record.downloadedAt, record.lastEventId ?? null, record.lastHlc ?? null);
+    notifyDbChange(businessId, `reference_data:${record.key}`);
 }
 export async function mergeReferenceData(db, businessId, key, incoming, hlc, eventId) {
-    const { compareHLCString } = await import("../utils/hlc");
     const existing = await getReferenceData(db, businessId, key);
     if (!existing) {
         await setReferenceData(db, businessId, {
@@ -68,3 +73,32 @@ export async function getAllReferenceDataKeys(db, businessId) {
     const rows = await db.getAllAsync("SELECT key FROM reference_data WHERE business_id = ? ORDER BY key;", businessId);
     return rows.map((r) => r.key);
 }
+async function enqueueReferenceSyncJob(businessId, key, hlc) {
+    try {
+        const db = await openSyncDatabase();
+        const id = generateUUID();
+        const now = new Date().toISOString();
+        await db.runAsync(`INSERT OR IGNORE INTO sync_jobs (id, business_id, command_type, entity_id, payload, status, created_at, updated_at, attempts, last_error) VALUES (?, ?, ?, ?, ?, 'pending', ?, ?, 0, NULL);`, id, businessId, "reference:sync", key, JSON.stringify({ key, hlc }), now, now);
+    }
+    catch { }
+}
+export async function setOperatingHoursLocal(businessId, entries) {
+    const db = await openSyncDatabase();
+    const payload = { data: entries };
+    const now = new Date().toISOString();
+    // HLC ensures local edit wins over stale server pull via LWW
+    const existing = await getReferenceData(db, businessId, "operating-hours");
+    const lastHlc = existing?.lastHlc ? hlcFromString(existing.lastHlc) : null;
+    const hlcStr = hlcToString(tickHLC(Date.now(), lastHlc, getAppInstanceId()));
+    await mergeReferenceData(db, businessId, "operating-hours", payload, hlcStr, `evt_${hlcStr}`);
+    await enqueueReferenceSyncJob(businessId, "operating-hours", hlcStr);
+}
+export async function setBusinessProfileLocal(businessId, profile) {
+    const db = await openSyncDatabase();
+    const payload = { data: profile };
+    const existing = await getReferenceData(db, businessId, "business:profile");
+    const lastHlc = existing?.lastHlc ? hlcFromString(existing.lastHlc) : null;
+    const hlcStr = hlcToString(tickHLC(Date.now(), lastHlc, getAppInstanceId()));
+    await mergeReferenceData(db, businessId, "business:profile", payload, hlcStr, `evt_${hlcStr}`);
+    await enqueueReferenceSyncJob(businessId, "business:profile", hlcStr);
+}

package/dist/reference/service.js

@@ -12,7 +12,8 @@ import { syncLogger } from "../utils/sync-logger";
 import { generateUUID } from "../utils/uuid";
 import { menuService, businessService, rolesService } from "../adapters/services";
 import { cacheImageBatch, pruneImageCache } from "../adapters/image-cache";
-import { getReferenceData, getReferenceVersion, setReferenceData, } from "./operations";
+import { getConnectivityState } from "../adapters/connectivity";
+import { getReferenceData, getReferenceVersion, mergeReferenceData, } from "./operations";
 import { fetchReferenceVersions, fetchReferenceData, fetchReferenceChanges, } from "./api";
 const DEFAULT_SYNC_KEYS = [
     "menu:items",
@@ -22,6 +23,8 @@ const DEFAULT_SYNC_KEYS = [
     "tax-rules",
     "business:profile",
     "operating-hours",
+    "delivery-settings",
+    "payment-settings",
     "subscription:entitlements",
     "capabilities",
 ];
@@ -38,6 +41,20 @@ class ReferenceSyncService {
                 errors: {},
             };
         }
+        const { isOnline, isCloudReachable } = getConnectivityState();
+        if (!isOnline || isCloudReachable === "unreachable") {
+            syncLogger.debug("ReferenceSync", "Skipping sync — cloud not reachable", {
+                businessId: options.businessId,
+                isOnline,
+                isCloudReachable,
+            });
+            return {
+                synced: [],
+                skipped: options.keys ?? DEFAULT_SYNC_KEYS,
+                failed: [],
+                errors: {},
+            };
+        }
         this.isSyncing = true;
         syncLogger.info("ReferenceSync", "Starting reference data sync", {
             businessId: options.businessId,
@@ -143,14 +160,9 @@ class ReferenceSyncService {
             payload = fallback.payload;
             version = fallback.version;
         }
-        await setReferenceData(db, businessId, {
-            key,
-            version: version ?? generateUUID(),
-            payload,
-            downloadedAt: new Date().toISOString(),
-            lastHlc: version ?? generateUUID(),
-            lastEventId: `evt_${version ?? generateUUID()}`,
-        });
+        // LWW: newer HLC wins — local edits that are newer than server are preserved.
+        const hlc = version ?? generateUUID();
+        await mergeReferenceData(db, businessId, key, payload, hlc, `evt_${hlc}`);
         return true;
     }
     async fetchFallback(key, businessId) {
@@ -244,6 +256,21 @@ class ReferenceSyncService {
                     version: this.hashPayload(response),
                 };
             }
+            case "delivery-settings": {
+                const response = await businessService.fetchDeliverySettings?.(businessId) ?? (await (await import("../adapters/http")).getHttpClient().get(`/businesses/${businessId}/delivery-settings`).then((r) => r.data));
+                return {
+                    payload: response,
+                    version: this.hashPayload(response),
+                };
+            }
+            case "payment-settings": {
+                const response = await businessService.fetchBusinessById(businessId);
+                const payload = response?.data?.paymentSettings ?? response;
+                return {
+                    payload,
+                    version: this.hashPayload(payload),
+                };
+            }
             default:
                 throw new Error(`No fallback fetch available for ${key}`);
         }

package/dist/reference/types.d.ts

@@ -8,7 +8,7 @@
  * It is synchronized separately from transactional data through the
  * ReferenceSyncService.
  */
-export type ReferenceDataKey = "menu:items" | "menu:categories" | "roles" | "members" | "tax-rules" | "business:profile" | "operating-hours" | "subscription:entitlements" | "capabilities";
+export type ReferenceDataKey = "menu:items" | "menu:categories" | "roles" | "members" | "tax-rules" | "business:profile" | "operating-hours" | "delivery-settings" | "payment-settings" | "subscription:entitlements" | "capabilities";
 export interface ReferenceDataRecord<T = unknown> {
     key: ReferenceDataKey;
     version: string;

package/dist/repositories/order.repository.d.ts

@@ -24,6 +24,13 @@ export interface OrderActionInput {
     businessId: string;
 }
 export declare const orderRepository: {
+    /**
+     * Single create path: build an `order:create` command and route it through
+     * the SyncEngine (cloud → LAN node → queue). Every path returns an
+     * order-shaped payload: cloud/LAN execute the real create, queue returns
+     * the optimistic order (same UUID + DD-RRR-CCC, replayed idempotently).
+     * Direct `createLocalOrder` bypasses sync — never call it from UI flows.
+     */
     createOrder(input: CreateOrderInput): Promise<SellerOrder>;
     acceptOrder(input: OrderActionInput): Promise<SellerOrder>;
     rejectOrder(input: OrderActionInput): Promise<SellerOrder>;
@@ -41,4 +48,5 @@ export declare const orderRepository: {
     assignRider(input: AssignRiderInput & {
         businessId: string;
     }): Promise<unknown>;
+    confirmCashPayment(input: OrderActionInput): Promise<SellerOrder>;
 };

package/dist/repositories/order.repository.js

@@ -9,6 +9,7 @@
  */
 import { syncEngine } from "../sync/engine";
 import { buildCommand } from "../sync/command-builder";
+import { generateUUID } from "../utils/uuid";
 async function executeCommand(command) {
     console.debug("[OrderRepository] Dispatching command", JSON.stringify({
         command_id: command.command_id,
@@ -35,12 +36,24 @@ async function executeCommand(command) {
     return event.payload;
 }
 export const orderRepository = {
+    /**
+     * Single create path: build an `order:create` command and route it through
+     * the SyncEngine (cloud → LAN node → queue). Every path returns an
+     * order-shaped payload: cloud/LAN execute the real create, queue returns
+     * the optimistic order (same UUID + DD-RRR-CCC, replayed idempotently).
+     * Direct `createLocalOrder` bypasses sync — never call it from UI flows.
+     */
     async createOrder(input) {
+        const entityId = input.entityId ?? generateUUID();
         const command = buildCommand({
             commandType: "order:create",
             businessId: input.businessId,
-            entityId: input.entityId,
-            payload: input.data,
+            entityId,
+            payload: {
+                ...input.data,
+                id: entityId,
+                command_id: entityId,
+            },
         });
         return executeCommand(command);
     },
@@ -126,4 +139,13 @@ export const orderRepository = {
         }
         return event.payload;
     },
+    async confirmCashPayment(input) {
+        const command = buildCommand({
+            commandType: "payment:confirm_cash",
+            businessId: input.businessId,
+            entityId: input.orderId,
+            payload: {},
+        });
+        return executeCommand(command);
+    },
 };

package/dist/repositories/pos.repository.d.ts

@@ -14,6 +14,10 @@ export interface POSOrderPreviewInput {
     customerName?: string;
 }
 export declare const posRepository: {
+    /**
+     * @deprecated Single create path is `createLocalOrder` (domain/orders/service).
+     * Forwards via `orderRepository.createOrder`, which delegates there directly.
+     */
     createOrder(businessId: string, data: POSOrderCreateRequest, entityId?: string): Promise<SellerOrder>;
     fetchPreview(input: POSOrderPreviewInput): Promise<POSOrderPreviewResponse>;
     fetchOrders(businessId: string, params?: Record<string, string>): Promise<SellerOrdersResponse>;

package/dist/repositories/pos.repository.js

@@ -7,6 +7,10 @@
 import { posService } from "../adapters/services";
 import { orderRepository } from "./order.repository";
 export const posRepository = {
+    /**
+     * @deprecated Single create path is `createLocalOrder` (domain/orders/service).
+     * Forwards via `orderRepository.createOrder`, which delegates there directly.
+     */
     async createOrder(businessId, data, entityId) {
         return orderRepository.createOrder({ businessId, data, entityId });
     },

package/dist/sync/backoff.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared retry backoff — one curve everywhere (sync retries, probes stay fixed).
+ *
+ * delay(attempts) = min(MAX, BASE * 2^attempts) + jitter(±20%).
+ * Attempts reset on any success or connectivity regain, so one bad night
+ * never permanently slows the device, and a fleet doesn't thunder-herd a
+ * recovering backend at the same millisecond.
+ */
+export declare const BACKOFF_BASE_MS = 2000;
+export declare const BACKOFF_MAX_MS: number;
+export declare function backoffDelayMs(attempts: number): number;
+/** Deterministic center of the curve (no jitter) — for tests and logging. */
+export declare function backoffCenterMs(attempts: number): number;
+/** Attempt counters keyed by scope (e.g. business id). Reset on success/regain. */
+export declare class BackoffTracker {
+    private attempts;
+    next(scope: string): number;
+    reset(scope: string): void;
+    resetAll(): void;
+    count(scope: string): number;
+}

package/dist/sync/backoff.js

@@ -0,0 +1,42 @@
+/**
+ * Shared retry backoff — one curve everywhere (sync retries, probes stay fixed).
+ *
+ * delay(attempts) = min(MAX, BASE * 2^attempts) + jitter(±20%).
+ * Attempts reset on any success or connectivity regain, so one bad night
+ * never permanently slows the device, and a fleet doesn't thunder-herd a
+ * recovering backend at the same millisecond.
+ */
+export const BACKOFF_BASE_MS = 2000;
+export const BACKOFF_MAX_MS = 5 * 60000;
+const JITTER_RATIO = 0.2;
+export function backoffDelayMs(attempts) {
+    const safe = Math.max(0, Math.floor(attempts));
+    const capped = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * Math.pow(2, safe));
+    const jitter = capped * JITTER_RATIO * (Math.random() * 2 - 1);
+    return Math.max(0, Math.round(capped + jitter));
+}
+/** Deterministic center of the curve (no jitter) — for tests and logging. */
+export function backoffCenterMs(attempts) {
+    const safe = Math.max(0, Math.floor(attempts));
+    return Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * Math.pow(2, safe));
+}
+/** Attempt counters keyed by scope (e.g. business id). Reset on success/regain. */
+export class BackoffTracker {
+    constructor() {
+        this.attempts = new Map();
+    }
+    next(scope) {
+        const n = this.attempts.get(scope) ?? 0;
+        this.attempts.set(scope, n + 1);
+        return backoffDelayMs(n);
+    }
+    reset(scope) {
+        this.attempts.delete(scope);
+    }
+    resetAll() {
+        this.attempts.clear();
+    }
+    count(scope) {
+        return this.attempts.get(scope) ?? 0;
+    }
+}

package/dist/sync/command-builder.js

@@ -11,6 +11,14 @@ export function buildCommand(options) {
     const user = useAuthStore.getState().user;
     const userId = user?.id ?? "anonymous";
     const deviceId = getAppInstanceId();
+    const timestamp = new Date().toISOString();
+    // Inject inserted_at / updated_at into payload so the backend preserves the
+    // original client creation time for offline-first sync.
+    const payload = {
+        ...options.payload,
+        inserted_at: timestamp,
+        updated_at: timestamp,
+    };
     return {
         command_id: generateCommandId(),
         command_type: options.commandType,
@@ -19,8 +27,8 @@ export function buildCommand(options) {
         entity_id: options.entityId,
         user_id: userId,
         device_id: deviceId,
-        timestamp: new Date().toISOString(),
-        payload: options.payload,
+        timestamp,
+        payload,
     };
 }
 export { getAppInstanceId };

package/dist/sync/command-queue.service.d.ts

@@ -37,6 +37,18 @@ declare class CommandQueueService {
      * Return the number of commands currently in the outbox.
      */
     getPendingCount(): Promise<number>;
+    /**
+     * Debug dump of the engine outbox for Diagnostics screens (all statuses,
+     * newest last). Mirrors debugDumpSyncJobs.
+     */
+    debugDumpCommands(businessId: string): Promise<Array<{
+        id: string;
+        command_type: string;
+        status: string;
+        retry_count: number;
+        error: string | null;
+        created_at: string;
+    }>>;
 }
 export declare const commandQueueService: CommandQueueService;
 export {};

package/dist/sync/command-queue.service.js

@@ -11,8 +11,9 @@
 import { getSyncDatabase, openSyncDatabase } from "../db/connection";
 import { insertCommand, getPendingCommands, markCommandInFlight, updateCommandStatus, deleteCommand, insertEvent, } from "../db/operations";
 import { syncLogger } from "../utils/sync-logger";
+import { recordAttempt } from "../utils/attempt-stats";
 import { generateEventId } from "../utils/uuid";
-import { generateLocalCalloutNumber, generateOrderNumberForBusiness, } from "./order-number";
+import { generateLocalCalloutNumber, generateOrderNumberForBusiness, generateOrderNumber, } from "./order-number";
 import { getConnectivityState, subscribeConnectivity } from "../adapters/connectivity";
 const MAX_RETRIES = 5;
 const QUEUED_STATUS_BY_COMMAND = {
@@ -25,6 +26,10 @@ const QUEUED_STATUS_BY_COMMAND = {
     "delivery:assign": "assigned",
     "delivery:confirm_handover": "delivered",
 };
+const PAYMENT_QUEUED_PAYLOAD = {
+    is_paid: true,
+    to_is_paid: true,
+};
 export function getQueuedStatus(commandType) {
     return QUEUED_STATUS_BY_COMMAND[commandType] ?? null;
 }
@@ -42,6 +47,24 @@ function buildOptimisticEvent(command) {
             timestamp: new Date().toISOString(),
         };
     }
+    if (command.command_type === "payment:confirm_cash") {
+        return {
+            event_id: generateEventId(),
+            event_type: "payment.completed_queued",
+            event_version: "1.0",
+            entity_id: command.entity_id ?? command.command_id,
+            user_id: command.user_id,
+            device_id: command.device_id,
+            payload: {
+                ...payload,
+                command_id: command.command_id,
+                is_paid: true,
+                paid_at: new Date().toISOString(),
+                order_id: command.entity_id,
+            },
+            timestamp: new Date().toISOString(),
+        };
+    }
     const queuedStatus = getQueuedStatus(command.command_type);
     return {
         event_id: generateEventId(),
@@ -58,11 +81,13 @@ function buildOptimisticEvent(command) {
             to_status: queuedStatus,
             order_id: command.entity_id,
             delivery_id: command.entity_id,
+            ...(queuedStatus ? {} : {}),
         },
         timestamp: new Date().toISOString(),
     };
 }
 function buildOptimisticOrder(command, payload) {
+    const snapshots = payload.item_snapshots ?? null;
     const items = payload.items ?? [];
     const totalMinor = payload.total_minor ?? 0;
     const subtotalMinor = payload.subtotal_minor ?? totalMinor;
@@ -74,14 +99,14 @@ function buildOptimisticOrder(command, payload) {
     return {
         id: command.entity_id ?? command.command_id,
         order_number: orderNumber,
-        callout_number: generateLocalCalloutNumber(),
+        callout_number: generateLocalCalloutNumber(command.business_id),
         order_type: payload.order_type ?? "takeout",
         is_pos: true,
         customer_name: payload.customer_name ?? null,
         customer_phone: payload.customer_phone ?? null,
         pos_payment_method: payload.pos_payment_method ?? "cash",
         paid_at: null,
-        status: "pending",
+        status: "accepted",
         delivery_id: null,
         delivery_status: null,
         is_paid: payload.pos_payment_method === "cash",
@@ -109,14 +134,22 @@ function buildOptimisticOrder(command, payload) {
         delivery_lat: null,
         delivery_lng: null,
         user: null,
-        items: items.map((item, index) => ({
+        items: (snapshots ? snapshots.map((s, index) => ({
+            id: `tmp-${command.command_id}-${index}`,
+            menu_item: { id: s.menu_item_id, name: s.name },
+            quantity: s.quantity,
+            unit_price: s.unit_price_minor,
+            subtotal: s.unit_price_minor * s.quantity,
+            variant_name: s.variant_name,
+            addons: (s.addons ?? []).map((a) => ({ name: a.name, price_minor: a.price_minor })),
+        })) : items.map((item, index) => ({
             id: `tmp-${command.command_id}-${index}`,
             menu_item: { id: item.menu_item_id, name: "" },
             quantity: item.quantity,
             unit_price: 0,
             subtotal: 0,
             addons: [],
-        })),
+        }))),
         inserted_at: now,
     };
 }
@@ -142,7 +175,7 @@ function injectLocalOrderNumber(command) {
 }
 class CommandQueueService {
     constructor() {
-        this.replaying = false;
+        this.replaying = null;
         this.syncEngine = null;
     }
     setSyncEngine(engine) {
@@ -222,7 +255,7 @@ class CommandQueueService {
         }
         await markCommandInFlight(db, command.command_id);
         try {
-            const events = await this.syncEngine.execute(parsedCommand);
+            const events = await this.syncEngine.execute(parsedCommand, { forReplay: true });
             // Outbox is an ephemeral queue — remove the row on success so the
             // Diagnostics outbox count drops to 0 and old completed rows never
             // accumulate. The optimistic event stays in `events` (marked synced).
@@ -238,11 +271,18 @@ class CommandQueueService {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+            // Replay with no transport available: leave the row exactly as-is for
+            // the next trigger (do not mark, do not count). Must reset the
+            // in_flight flag first — rows stuck in_flight are invisible to the
+            // outbox query and would wedge the queue forever.
+            if (message.includes("ReplayDeferred")) {
+                await updateCommandStatus(db, command.command_id, "pending", "deferred:no-transport");
+                throw error;
+            }
             const apiErr = error;
             // 409 ORDER_NUMBER_TAKEN is retryable once with new RRR
             const code = apiErr?.code ?? apiErr?.data?.code;
             if (apiErr?.status === 409 && String(code).includes("ORDER_NUMBER_TAKEN")) {
-                // Regenerate random part of order_number if this was order:create
                 if (command.command_type === "order:create") {
                     try {
                         const payload = command.payload;
@@ -250,12 +290,14 @@ class CommandQueueService {
                         const parsed = on ? on.match(/^([0-9]{2})-([0-9]{3})-([0-9]{3})$/) : null;
                         if (parsed) {
                             const deviceNumber = parsed[1];
-                            const { generateOrderNumber } = await import("./order-number");
-                            const { orderNumber: newOn } = generateOrderNumber(deviceNumber);
+                            const { orderNumber: newOn } = generateOrderNumber(deviceNumber, command.business_id);
                             const newPayload = { ...payload, order_number: newOn };
-                            await updateCommandStatus(db, command.command_id, "failed", `retry_random:${message}`);
-                            // Update stored payload for retry
-                            await db.runAsync(`UPDATE commands SET payload = ?, retry_count = retry_count WHERE command_id = ?;`, JSON.stringify(newPayload), command.command_id);
+                            await db.runAsync(`UPDATE commands SET payload = ?, error = ?, updated_at = ? WHERE command_id = ?;`, JSON.stringify(newPayload), `retry_random:${message}`, new Date().toISOString(), command.command_id);
+                            syncLogger.info("CommandQueueService", "Regenerated order_number after 409", { command_id: command.command_id, new_order_number: newOn });
+                            // keep retry_count unchanged so next replay retries; do not mark failed twice.
+                            // Reset in_flight → pending so the row stays visible to the outbox query.
+                            await updateCommandStatus(db, command.command_id, "pending", `retry_random:${message}`);
+                            return;
                         }
                     }
                     catch { }
@@ -275,11 +317,29 @@ class CommandQueueService {
                     status: apiErr.status,
                     error: message,
                 });
+                // Loud toast + revert: the optimistic local write is rolled back so
+                // the UI never shows what the backend refused.
+                try {
+                    const { notifyError } = await import("../adapters/notify");
+                    notifyError(`Server rejected ${command.command_type}: ${message}`);
+                }
+                catch { }
+                try {
+                    if (command.command_type.startsWith("menu:") && command.entity_id) {
+                        const { revertMenuCommand } = await import("../reference/menu-apply");
+                        await revertMenuCommand(command.business_id, command.command_type, command.entity_id);
+                    }
+                }
+                catch { }
                 // Do not throw — allow replay to continue to next command.
                 return;
             }
-            await updateCommandStatus(db, command.command_id, "failed", message);
-            syncLogger.command(parsedCommand, "failed", { error: message });
+            // Network/timeout/5xx: NOT a rejection — keep the command retryable
+            // indefinitely (status back to pending, retry_count untouched) so a
+            // long outage never dead-letters the outbox via MAX_RETRIES. Replay
+            // stops here to preserve ordering; the next trigger retries.
+            await updateCommandStatus(db, command.command_id, "pending", `network:${message}`);
+            syncLogger.command(parsedCommand, "queued", { error: message, deferred: true });
             throw error;
         }
     }
@@ -288,11 +348,21 @@ class CommandQueueService {
      * ordering consistent; the next replay will retry from the failed command.
      */
     async replay() {
+        recordAttempt("sync_drain", "replay");
+        // Join an in-flight replay instead of no-op'ing: concurrent replays
+        // (connectivity auto-replay racing an explicit replay) must converge on
+        // the same outcome, otherwise callers observe a drained queue while work
+        // is still flying.
         if (this.replaying) {
-            syncLogger.debug("CommandQueueService", "Replay already in progress");
+            syncLogger.debug("CommandQueueService", "Replay already in progress, joining");
+            try {
+                await this.replaying;
+            }
+            catch { }
             return;
         }
-        this.replaying = true;
+        let resolveReplay;
+        this.replaying = new Promise((r) => { resolveReplay = r; });
         try {
             // Await open (not getSyncDatabase) so a cold-start replay triggered by a
             // connectivity event that fires before the DB open completes does not
@@ -324,7 +394,11 @@ class CommandQueueService {
             }
         }
         finally {
-            this.replaying = false;
+            this.replaying = null;
+            try {
+                resolveReplay();
+            }
+            catch { }
         }
     }
     /**
@@ -345,5 +419,28 @@ class CommandQueueService {
         const commands = await getPendingCommands(db, Number.MAX_SAFE_INTEGER);
         return commands.length;
     }
+    /**
+     * Debug dump of the engine outbox for Diagnostics screens (all statuses,
+     * newest last). Mirrors debugDumpSyncJobs.
+     */
+    async debugDumpCommands(businessId) {
+        try {
+            const db = getSyncDatabase();
+            const rows = await getPendingCommands(db, Number.MAX_SAFE_INTEGER);
+            return rows
+                .filter((c) => !businessId || c.business_id === businessId)
+                .map((c) => ({
+                id: c.command_id,
+                command_type: c.command_type,
+                status: c.status,
+                retry_count: c.retry_count,
+                error: c.error ?? null,
+                created_at: c.created_at ?? "",
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
 }
 export const commandQueueService = new CommandQueueService();

package/dist/sync/device-lease.service.d.ts

@@ -3,7 +3,7 @@
  * Backend authority: POST /businesses/:id/devices/lease
  * KV persists device_number per businessId.
  */
-declare function getAppInstanceId(): string;
+import { getAppInstanceIdAsync } from "../adapters/devices";
 export declare function getDeviceNumber(businessId: string): string | null;
 export declare function isOnlineOnly(businessId: string): boolean;
 export declare function ensureLease(businessId: string): Promise<string | null>;
@@ -14,6 +14,6 @@ export declare const deviceLeaseService: {
     isOnlineOnly: typeof isOnlineOnly;
     ensureLease: typeof ensureLease;
     refreshLease: typeof refreshLease;
-    getAppInstanceId: typeof getAppInstanceId;
+    getAppInstanceId: typeof getAppInstanceIdAsync;
+    getAppInstanceIdAsync: typeof getAppInstanceIdAsync;
 };
-export {};