@teincfood/core 0.9.9 → 0.9.11

package/dist/db/operations.d.ts

@@ -9,7 +9,7 @@ export interface InsertCommandInput {
 }
 export declare function insertCommand(db: SQLiteDatabase, input: InsertCommandInput): Promise<PersistedCommand>;
 export declare function getPendingCommands(db: SQLiteDatabase, limit?: number): Promise<PersistedCommand[]>;
-export declare function updateCommandStatus(db: SQLiteDatabase, commandId: string, status: PersistedCommand["status"], error?: string): Promise<void>;
+export declare function updateCommandStatus(db: SQLiteDatabase, commandId: string, status: PersistedCommand["status"], error?: string, incrementRetry?: boolean): Promise<void>;
 export declare function markCommandInFlight(db: SQLiteDatabase, commandId: string): Promise<void>;
 export declare function deleteCommand(db: SQLiteDatabase, commandId: string): Promise<void>;
 export declare function clearCompletedCommands(db: SQLiteDatabase, olderThanHours?: number): Promise<void>;

package/dist/db/operations.js

@@ -33,7 +33,7 @@ export async function getPendingCommands(db, limit = 100) {
     `, limit);
     return rows.map(rowToPersistedCommand);
 }
-export async function updateCommandStatus(db, commandId, status, error) {
+export async function updateCommandStatus(db, commandId, status, error, incrementRetry) {
     const now = new Date().toISOString();
     if (status === "failed") {
         await db.runAsync(`
@@ -46,6 +46,11 @@ export async function updateCommandStatus(db, commandId, status, error) {
     else if (status === "completed") {
         await db.runAsync("UPDATE commands SET status = ?, error = NULL, updated_at = ? WHERE command_id = ?;", status, now, commandId);
     }
+    else if (incrementRetry) {
+        // Bounded 4xx retries count attempts without failing the row, so
+        // MAX_RETRIES caps blind retries while 5xx/network stay indefinite.
+        await db.runAsync("UPDATE commands SET status = ?, error = ?, retry_count = retry_count + 1, updated_at = ? WHERE command_id = ?;", status, error ?? null, now, commandId);
+    }
     else {
         await db.runAsync("UPDATE commands SET status = ?, error = ?, updated_at = ? WHERE command_id = ?;", status, error ?? null, now, commandId);
     }

package/dist/local-node/service.js

@@ -13,7 +13,7 @@ import { applyReferenceChangeEvent } from "../reference/events";
 import { openSyncDatabase } from "../db/connection";
 import { insertOrder } from "../db/operations";
 import { createLocalOrder, transitionLocalOrder } from "../domain/orders/service";
-import { getConnectivityState, setConnectivityState } from "../adapters/connectivity";
+import { getConnectivityState } from "../adapters/connectivity";
 import { deriveLanSecret as deriveSecretCore } from "./security";
 const KEEP_AWAKE_TAG = "TeincLocalNode";
 const RECONNECT_BASE = 1000;
@@ -742,11 +742,10 @@ class LocalNodeServiceCore {
                     rejectionStatus < 500) {
                     throw error;
                 }
+                // Flag-neutral (probe owns isCloudReachable): a failed forward is
+                // never evidence the cloud is down. Fall back to the queue; the
+                // probe detects real outages and replays trigger on recovery.
                 syncLogger.warn("LocalNodeService", "Cloud forward failed, queueing", { error: String(error) });
-                try {
-                    setConnectivityState({ isCloudReachable: "unreachable" });
-                }
-                catch { }
                 event = await commandQueueService.enqueue(command);
             }
         }

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

@@ -49,6 +49,21 @@ export interface MenuItemEnvelopeInput extends MenuItemRecordInput {
     /** Extra wire-only keys (e.g. entity id). */
     wireExtra?: Record<string, unknown>;
 }
+/**
+ * Image value for a menu-item UPDATE wire payload. The server is the source
+ * of truth for the stored key — never re-send a loaded URL and risk
+ * overwriting the key with a URL-shaped value. Returns `undefined` when the
+ * caller must OMIT `image_url` (server keeps its key untouched):
+ * - fresh upload → the bare S3 key;
+ * - user removed the photo (had one, now empty) → explicit null (clear it);
+ * - loaded an un-storable scheme (tfimg:/blob:/file: poison) → null (heal);
+ * - otherwise (loaded URL or bare key, no new upload) → omit (preserve).
+ */
+export declare function imageUrlForUpdateWire(opts: {
+    freshKey?: string | null;
+    loadedUrl?: string | null;
+    hadImage: boolean;
+}): string | null | undefined;
 /**
  * Build the { wire, cacheRecord } pair for a menu item write. Callers pass
  * absolute variant prices (backend model) — the form layer owns the field.

package/dist/reference/menu-record.js

@@ -114,13 +114,34 @@ export function getCachedCategoryName(qc, businessId, categoryId) {
 }
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
- * A variant/extra id is only safe to send when it is a real backend UUID.
- * Form-local ids (e.g. `local-<ts>`) must be omitted: the backend treats a
+ * A variant/extra id is only safe to send when it is a real UUID. Single
+ * global id space: clients generate UUIDs up front and the backend stores
+ * them verbatim. Non-UUID junk must be omitted: the backend treats a
  * missing/empty id as "insert new", but Repo.get/3 raises on a non-UUID.
  */
 function wireId(id) {
     return id && UUID_RE.test(id) ? id : undefined;
 }
+/**
+ * Image value for a menu-item UPDATE wire payload. The server is the source
+ * of truth for the stored key — never re-send a loaded URL and risk
+ * overwriting the key with a URL-shaped value. Returns `undefined` when the
+ * caller must OMIT `image_url` (server keeps its key untouched):
+ * - fresh upload → the bare S3 key;
+ * - user removed the photo (had one, now empty) → explicit null (clear it);
+ * - loaded an un-storable scheme (tfimg:/blob:/file: poison) → null (heal);
+ * - otherwise (loaded URL or bare key, no new upload) → omit (preserve).
+ */
+export function imageUrlForUpdateWire(opts) {
+    if (opts.freshKey)
+        return opts.freshKey;
+    const loaded = opts.loadedUrl ?? null;
+    if (!loaded)
+        return opts.hadImage ? null : undefined;
+    if (toStorableImageUrl(loaded) === null)
+        return null;
+    return undefined;
+}
 /**
  * Build the { wire, cacheRecord } pair for a menu item write. Callers pass
  * absolute variant prices (backend model) — the form layer owns the field.

package/dist/reference/service.js

@@ -19,6 +19,11 @@ import { anchorServerTime } from "./entitlement-clock";
 import { isServerAuthoritativeKey } from "./entitlements";
 import { fetchReferenceVersions, fetchReferenceData, fetchReferenceChanges, } from "./api";
 const DEFAULT_SYNC_KEYS = [
+    // Server-authoritative plan proof first: every gated command evaluates
+    // against this, so it must never starve behind slow/heavy keys (menu
+    // pagination). Capabilities second for the same reason (nav + guards).
+    "subscription:entitlements",
+    "capabilities",
     "menu:items",
     "menu:categories",
     "roles",
@@ -28,8 +33,6 @@ const DEFAULT_SYNC_KEYS = [
     "operating-hours",
     "delivery-settings",
     "payment-settings",
-    "subscription:entitlements",
-    "capabilities",
 ];
 class ReferenceSyncService {
     constructor() {
@@ -193,6 +196,11 @@ class ReferenceSyncService {
                 await anchorServerTime(envelope.server_time);
             }
             catch { }
+            syncLogger.info("ReferenceSync", `Server-authoritative ${key} cached`, {
+                businessId,
+                version: envelope.version,
+                server_time: envelope.server_time,
+            });
             return wrote;
         }
         await mergeReferenceData(db, businessId, key, payload, hlc, `evt_${hlc}`);
@@ -368,7 +376,7 @@ class ReferenceSyncService {
             hash = (hash << 5) - hash + char;
             hash |= 0;
         }
-        return `local-${Math.abs(hash).toString(16)}`;
+        return `hash-${Math.abs(hash).toString(16)}`;
     }
     async getCached(businessId, key) {
         const db = await openSyncDatabase();

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

@@ -24,6 +24,20 @@ declare class CommandQueueService {
      * Try to execute a single pending command through the current transport.
      */
     processCommand(command: PersistedCommand): Promise<void>;
+    /**
+     * Mark a command permanently failed: loud toast + optimistic revert, then
+     * replay continues to the next command. Shared by the exhausted-retry and
+     * permanent-rejection paths.
+     */
+    private failPermanently;
+    /**
+     * Already-applied absorb: pull server truth, and if the order is already
+     * at this command's target status, delete the command as success. The
+     * absorb ONLY fires when the pull actually touched the row (hlc change) —
+     * otherwise a stale local optimistic write could mask a genuine race and
+     * delete work the server never applied.
+     */
+    private absorbIfApplied;
     /**
      * Replay all pending commands in order. Stops on the first failure to keep
      * ordering consistent; the next replay will retry from the failed command.

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

@@ -19,7 +19,18 @@ import { generateEventId } from "../utils/uuid";
 import { generateLocalCalloutNumber, generateOrderNumberForBusiness, generateOrderNumber, } from "./order-number";
 import { getConnectivityState, subscribeConnectivity } from "../adapters/connectivity";
 import { canBusinessSync } from "./sync-guard";
+import { backoffDelayMs } from "./backoff";
 const MAX_RETRIES = 5;
+/**
+ * 4xx that deserve another chance: transient races and rate limits, never
+ * permanent verdicts. Anything else 4xx (400 validation, 401 session,
+ * 402 plan, 403 forbidden) fails fast with a toast. 409 ORDER_NUMBER_TAKEN
+ * has its own regen path below and is not capped (every attempt mints a
+ * new order number, so it is never a blind retry).
+ */
+const RETRYABLE_4XX = new Set([404, 408, 409, 422, 429]);
+/** In-memory next-eligible time per command (shared 2s→5min curve). */
+const retryNotBefore = new Map();
 const QUEUED_STATUS_BY_COMMAND = {
     "order:accept": "accepted",
     "order:reject": "cancelled",
@@ -268,6 +279,12 @@ class CommandQueueService {
             await updateCommandStatus(db, command.command_id, "failed", "Max retry count exceeded");
             return;
         }
+        // Backoff pacing for retryable failures: the next replay skips (defers)
+        // this command until its slot, preserving FIFO without a hot loop.
+        const notBefore = retryNotBefore.get(command.command_id);
+        if (notBefore !== undefined && notBefore > Date.now()) {
+            throw new TransitionError(TRANSITION_ERROR_CODES.REPLAY_DEFERRED, "In retry backoff, deferring queued command");
+        }
         if (!this.syncEngine) {
             throw new Error("CommandQueueService: SyncEngine not initialized");
         }
@@ -323,31 +340,45 @@ class CommandQueueService {
                 await updateCommandStatus(db, command.command_id, "failed", `order_number_taken:${message}`);
                 throw error;
             }
-            const isNonRetryable = typeof apiErr?.status === "number" &&
-                apiErr.status >= 400 &&
-                apiErr.status < 500;
-            if (isNonRetryable) {
-                await updateCommandStatus(db, command.command_id, "failed", `permanent:${message}`);
-                syncLogger.warn("CommandQueueService", "Queued command rejected by server (not retrying)", {
-                    command_id: command.command_id,
-                    command_type: command.command_type,
-                    status: apiErr.status,
-                    error: message,
-                });
-                // Loud toast + revert: the optimistic local write is rolled back so
-                // the UI never shows what the backend refused.
+            const status = typeof apiErr?.status === "number" ? apiErr.status : undefined;
+            // Already-applied absorb: a 422/404 against an order the server
+            // already moved (duplicate tap, earlier drain won the race) is
+            // success, not failure. Verified against server truth via pull
+            // (HLC-guarded: pulled rows overwrite local), never the optimistic row.
+            if (status === 422 ||
+                code === "INVALID_TRANSITION" ||
+                (status === 404 && command.command_type !== "order:create")) {
                 try {
-                    const { notifyError } = await import("../adapters/notify");
-                    notifyError(`Server rejected ${command.command_type}: ${message}`);
+                    if (await this.absorbIfApplied(command))
+                        return;
                 }
                 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);
-                    }
+            }
+            // Retryable 4xx (FIFO races, rate limits): back off on the shared
+            // 2s→5min curve, then fail loudly after MAX_RETRIES. Throw a
+            // transport-neutral deferral so replay STOPS here (FIFO ordering) —
+            // rethrowing the 4xx itself would make the loop `continue` past it.
+            if (status !== undefined && RETRYABLE_4XX.has(status)) {
+                const attempts = command.retry_count + 1;
+                if (attempts >= MAX_RETRIES) {
+                    await this.failPermanently(db, command, message, `retryable 4xx exhausted after ${attempts} attempts`);
+                    return;
                 }
-                catch { }
+                retryNotBefore.set(command.command_id, Date.now() + backoffDelayMs(command.retry_count));
+                await updateCommandStatus(db, command.command_id, "pending", `retry_4xx:${message}`, true);
+                syncLogger.warn("CommandQueueService", "Retryable 4xx — backing off", {
+                    command_id: command.command_id,
+                    command_type: command.command_type,
+                    status,
+                    attempt: attempts,
+                });
+                throw new TransitionError(TRANSITION_ERROR_CODES.REPLAY_DEFERRED, `Retryable ${status} on ${command.command_type}, backing off`);
+            }
+            const isNonRetryable = status !== undefined &&
+                status >= 400 &&
+                status < 500;
+            if (isNonRetryable) {
+                await this.failPermanently(db, command, message, "permanent 4xx");
                 // Do not throw — allow replay to continue to next command.
                 return;
             }
@@ -360,6 +391,66 @@ class CommandQueueService {
             throw error;
         }
     }
+    /**
+     * Mark a command permanently failed: loud toast + optimistic revert, then
+     * replay continues to the next command. Shared by the exhausted-retry and
+     * permanent-rejection paths.
+     */
+    async failPermanently(db, command, message, reason) {
+        await updateCommandStatus(db, command.command_id, "failed", `permanent:${message}`);
+        syncLogger.warn("CommandQueueService", `Queued command failed (${reason})`, {
+            command_id: command.command_id,
+            command_type: command.command_type,
+            error: message,
+        });
+        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 { }
+    }
+    /**
+     * Already-applied absorb: pull server truth, and if the order is already
+     * at this command's target status, delete the command as success. The
+     * absorb ONLY fires when the pull actually touched the row (hlc change) —
+     * otherwise a stale local optimistic write could mask a genuine race and
+     * delete work the server never applied.
+     */
+    async absorbIfApplied(command) {
+        const target = QUEUED_STATUS_BY_COMMAND[command.command_type];
+        if (!target || !command.entity_id)
+            return false;
+        try {
+            const db = getSyncDatabase();
+            const before = await db.getFirstAsync(`SELECT hlc FROM orders WHERE business_id = ? AND id = ?;`, command.business_id, command.entity_id);
+            const { pullRemoteOrders } = await import("./sync-jobs.service");
+            await pullRemoteOrders(command.business_id);
+            const afterHlc = await db.getFirstAsync(`SELECT hlc FROM orders WHERE business_id = ? AND id = ?;`, command.business_id, command.entity_id);
+            if (!afterHlc || afterHlc.hlc === before?.hlc)
+                return false;
+            const { getOrderById } = await import("../db/operations");
+            const order = await getOrderById(db, command.business_id, command.entity_id);
+            if (order && order.status === target) {
+                await deleteCommand(db, command.command_id);
+                retryNotBefore.delete(command.command_id);
+                syncLogger.info("CommandQueueService", "Transition already applied on server, absorbing", {
+                    command_id: command.command_id,
+                    command_type: command.command_type,
+                    status: target,
+                });
+                return true;
+            }
+        }
+        catch { }
+        return false;
+    }
     /**
      * Replay all pending commands in order. Stops on the first failure to keep
      * ordering consistent; the next replay will retry from the failed command.

package/dist/sync/engine.js

@@ -14,7 +14,7 @@
 import { restTransport } from "./transport-rest";
 import { localNodeTransport } from "./transport-local-node";
 import { commandQueueService } from "./command-queue.service";
-import { getConnectivityState, setConnectivityState } from "../adapters/connectivity";
+import { getConnectivityState } from "../adapters/connectivity";
 import { ApiError } from "../adapters/http";
 import { errorCodeOf } from "./transition-errors";
 import { syncLogger } from "../utils/sync-logger";
@@ -155,9 +155,9 @@ export class SyncEngine {
                 syncLogger.command(command, "completed", {
                     event_count: events.length,
                 });
-                // Cloud just worked: it is reachable again. Mark it so future commands
-                // go cloud-first, and replay anything queued during the outage.
-                setConnectivityState({ isCloudReachable: "reachable" });
+                // Cloud just worked: replay anything queued during the outage.
+                // Flag-neutral: only the health probe writes isCloudReachable — a
+                // single success here is not its decision to make either.
                 this.replayQueuedCommands().catch((error) => {
                     syncLogger.error("SyncEngine", "Replay after cloud success failed", {
                         error: String(error),
@@ -199,13 +199,16 @@ export class SyncEngine {
                     });
                     throw error;
                 }
-                // Cloud is slow or unreachable: mark it and fall back to the Local
-                // Node or the outbox so the terminal stays responsive.
+                // Cloud is slow or unreachable: fall back to the Local Node or the
+                // outbox so the terminal stays responsive. Flag-neutral: only the
+                // health probe writes isCloudReachable — a failed request is never
+                // evidence the cloud is down (it may be a logic rejection without a
+                // numeric status, e.g. TransitionError). The probe detects real
+                // outages; queued work replays when it reports recovery.
                 syncLogger.warn("SyncEngine", "Cloud command timed out, falling back", {
                     command_type: command.command_type,
                     error: String(error),
                 });
-                setConnectivityState({ isCloudReachable: "unreachable" });
                 strategy = this.resolveStrategy(command);
                 if (strategy === "queue") {
                     // Replays must never re-enqueue-then-delete (the command would eat

package/dist/sync/health-probe.d.ts

@@ -1,10 +1,12 @@
 /**
  * Core Health Probe — periodic cloud reachability check.
  *
- * Probes `GET /health` using the injected HttpClient with a short timeout.
- * On success: marks cloud reachable (triggers sync replay via connectivity
- * subscribers). On failure: marks unreachable and schedules a retry with
- * exponential backoff (2s → 5min cap, ±20% jitter).
+ * SOLE OWNER of the `isCloudReachable` flag: success marks reachable
+ * (triggers sync replay via connectivity subscribers), failure marks
+ * unreachable and schedules a retry with exponential backoff (15s floor →
+ * 5min cap, ±20% jitter). No request path may write the flag — a single
+ * failed request is never evidence the cloud is down (see SyncEngine,
+ * LocalNodeService), so all failure handling there is flag-neutral.
  *
  * Started automatically by `createTeincCore()`. Host apps should not need
  * to call this directly.

package/dist/sync/health-probe.js

@@ -1,10 +1,12 @@
 /**
  * Core Health Probe — periodic cloud reachability check.
  *
- * Probes `GET /health` using the injected HttpClient with a short timeout.
- * On success: marks cloud reachable (triggers sync replay via connectivity
- * subscribers). On failure: marks unreachable and schedules a retry with
- * exponential backoff (2s → 5min cap, ±20% jitter).
+ * SOLE OWNER of the `isCloudReachable` flag: success marks reachable
+ * (triggers sync replay via connectivity subscribers), failure marks
+ * unreachable and schedules a retry with exponential backoff (15s floor →
+ * 5min cap, ±20% jitter). No request path may write the flag — a single
+ * failed request is never evidence the cloud is down (see SyncEngine,
+ * LocalNodeService), so all failure handling there is flag-neutral.
  *
  * Started automatically by `createTeincCore()`. Host apps should not need
  * to call this directly.
@@ -62,12 +64,20 @@ export async function probeCloudHealth() {
         return true;
     }
     catch {
-        // Don't mark unreachable here — the sync engine already handles that
-        // when a command times out. This probe only detects recovery.
-        // Log and backoff so we re-check later.
-        syncLogger.debug("HealthProbe", "Probe failed — will retry", {
-            previous: getConnectivityState().isCloudReachable,
-        });
+        // Sole owner rule: the probe is the only writer of isCloudReachable.
+        // A failed probe IS evidence (dedicated check, short timeout), unlike a
+        // failed business request — mark unreachable so readers stop attempting
+        // cloud work until recovery is detected. Backoff bounds the retry rate.
+        const was = getConnectivityState().isCloudReachable;
+        if (was !== "unreachable") {
+            setCloudReachable("unreachable");
+            syncLogger.info("HealthProbe", "Cloud unreachable", { previous: was });
+        }
+        else {
+            syncLogger.debug("HealthProbe", "Probe failed — still unreachable, will retry", {
+                previous: was,
+            });
+        }
         scheduleRetry();
         return false;
     }

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

@@ -4,7 +4,7 @@
  * Core-only, single in_flight per business, coalesced via isOnline gate.
  */
 import { openSyncDatabase } from "../db/connection";
-import { insertOrder } from "../db/operations";
+import { insertOrder, getOrderById } from "../db/operations";
 import { getConnectivityState, subscribeConnectivity } from "../adapters/connectivity";
 import { getRefreshToken, setAuthTokens, clearAuth, subscribeAuth } from "../adapters/auth";
 import { getActiveBusiness, subscribeBusiness } from "../adapters/business";
@@ -16,11 +16,14 @@ import { BackoffTracker } from "./backoff";
 import { generateOrderNumber } from "./order-number";
 import { orderSnapshotsService } from "./order-snapshots.service";
 import { getTransitionPath, DELIVERY_COMMANDS } from "./transition-endpoints";
+import { getQueuedStatus } from "../utils/order-transitions";
 import { extractApiErrorCode } from "../utils/error";
 import { canBusinessSync, isAuthenticated } from "./sync-guard";
 const inflight = new Map();
 const retryTimers = new Map();
 const backoffTracker = new BackoffTracker();
+/** Blind 4xx retries stop here, loudly. 5xx/network retry indefinitely. */
+const MAX_SYNC_JOB_ATTEMPTS = 5;
 function isOnline() {
     const s = getConnectivityState();
     return s.isOnline && s.isCloudReachable !== "unreachable";
@@ -215,6 +218,34 @@ 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.
+ */
+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) {
+        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,
+            entityId,
+            commandType,
+            status: target,
+        });
+        return true;
+    }
+    return false;
+}
 export async function drainOne(businessId, entityId) {
     if (!businessId || !canBusinessSync(businessId)) {
         syncLogger.debug("SyncJobs", "drainOne early-return — no business/auth", { businessId, entityId });
@@ -355,14 +386,15 @@ export async function drainOne(businessId, entityId) {
             return;
         }
         // Permanent 4xx: mark failed to stop the retry loop.
-        // 404 is only retryable for order:create (FIFO race: order not yet created
-        // on backend). For transitions, 404 means the order was deleted or never
-        // synced — permanent. 409 handled above for RRR regen. 401/408/429 need
-        // special handling below. Backend codes are exact (no message matching).
+        // Retryable (bounded, 5 attempts): 401 (refresh owns it below), 408,
+        // 409, 422, 429, any 404 (FIFO race: earlier command still in flight),
+        // BUSINESS_CLOSED (pending-by-design). Everything else 4xx (400
+        // validation, 402 plan, 403 forbidden) fails fast. Backend codes are
+        // exact (no message matching).
         const isBusinessClosed = rest.code === "BUSINESS_CLOSED" || rest.code === "HOURS_NOT_SYNCED";
         const is4xx = rest.status && rest.status >= 400 && rest.status < 500;
-        const isRetryable4xx = rest.status === 401 || rest.status === 408 || rest.status === 409 || rest.status === 429
-            || (rest.status === 404 && row.command_type === "order:create")
+        const isRetryable4xx = rest.status === 401 || rest.status === 408 || rest.status === 409
+            || rest.status === 422 || rest.status === 429 || rest.status === 404
             || isBusinessClosed;
         if (is4xx && !isRetryable4xx) {
             syncLogger.warn("SyncJobs", "Permanent 4xx — marking job failed to stop retry loop", { businessId, entityId, status: rest.status, code: rest.code, message: rest.message });
@@ -385,6 +417,37 @@ export async function drainOne(businessId, entityId) {
             }
             return;
         }
+        // Already-applied absorb for transitions: the server already moved the
+        // order (duplicate tap, earlier drain won the race) — complete the job
+        // instead of failing it. Server truth only (hlc-guarded pull), never the
+        // optimistic row.
+        if ((rest.status === 422 || rest.code === "INVALID_TRANSITION" ||
+            (rest.status === 404 && row.command_type !== "order:create")) &&
+            getQueuedStatus(row.command_type) !== null) {
+            try {
+                if (await absorbSyncJobIfApplied(db, businessId, row.entity_id, row.command_type, row.id)) {
+                    clearRetry(businessId);
+                    return;
+                }
+            }
+            catch { }
+        }
+        // Bounded retries: blind 4xx retries stop after 5 attempts with a loud
+        // toast (attempts only increments on the keep-pending path below).
+        if (is4xx && isRetryable4xx && (row.attempts ?? 0) + 1 >= 5) {
+            syncLogger.warn("SyncJobs", "Retryable 4xx exhausted — marking job failed", { businessId, entityId, status: rest.status, code: rest.code, attempts: row.attempts });
+            try {
+                await db.runAsync(`UPDATE sync_jobs SET status='failed', last_error=?, updated_at=? WHERE id=?;`, `${rest.status} ${rest.code ?? ""} ${rest.message ?? ""} (after ${MAX_SYNC_JOB_ATTEMPTS} attempts)`.trim(), new Date().toISOString(), row.id);
+            }
+            catch { }
+            clearRetry(businessId);
+            try {
+                const { notifyError } = await import("../adapters/notify");
+                notifyError(`Server rejected ${row.command_type}: ${rest.message ?? rest.code ?? rest.status} (after retries)`);
+            }
+            catch { }
+            return;
+        }
         if (isBusinessClosed) {
             syncLogger.warn("SyncJobs", "Business closed — keeping pending for retry after hours sync", { businessId, entityId, code: rest.code });
             try {

package/dist/sync/transport-rest.js

@@ -10,6 +10,7 @@ import { syncLogger } from "../utils/sync-logger";
 import { generateEventId } from "../utils/uuid";
 import { createLocalOrder, transitionLocalOrder } from "../domain/orders/service";
 import { isFinalGuardRejection } from "./transition-errors";
+import { getQueuedStatus } from "../utils/order-transitions";
 import { openSyncDatabase } from "../db/connection";
 import { getOrderById, updateOrderStatus } from "../db/operations";
 export class RestTransport {
@@ -143,6 +144,29 @@ export class RestTransport {
      */
     async executeOrderTransition(command, action, timestamp, restFallback, eventType = "order.status_changed") {
         const { business_id, entity_id } = command;
+        // Idempotent absorb: a duplicate tap / replayed command whose target
+        // status is already applied locally succeeds without touching the
+        // guards or the network (this was the "Cannot mark_ready from ready"
+        // error storm: the throw also poisoned global reachability before the
+        // probe-ownership rule). Genuinely invalid transitions still throw
+        // INVALID_TRANSITION from transitionLocalOrder below.
+        const target = getQueuedStatus(command.command_type);
+        if (target && entity_id) {
+            try {
+                const db = await openSyncDatabase();
+                const local = await getOrderById(db, business_id, entity_id);
+                if (local && local.status === target) {
+                    syncLogger.info("RestTransport", "transition already applied, absorbing", {
+                        command_type: command.command_type,
+                        entity_id,
+                        status: target,
+                    });
+                    const data = { ...local, order_id: local.id };
+                    return this.wrapResponse(eventType, data, local.id, timestamp, command);
+                }
+            }
+            catch { }
+        }
         try {
             const order = await transitionLocalOrder(business_id, entity_id, action);
             const data = { ...order, order_id: order.id };

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

@@ -207,6 +207,17 @@ export function createMemoryDriver() {
                 }
                 return { lastInsertRowId: 0, changes: 1 };
             }
+            // sync_jobs update status=failed with last_error (permanent + exhausted retries)
+            if (s.includes("UPDATE sync_jobs SET status='failed'")) {
+                const [last_error, updated_at, id] = args;
+                const row = tables.sync_jobs.find((r) => r.id === id);
+                if (row) {
+                    row.status = "failed";
+                    row.last_error = last_error;
+                    row.updated_at = updated_at;
+                }
+                return { lastInsertRowId: 0, changes: 1 };
+            }
             if (s.includes("UPDATE sync_jobs SET payload=")) {
                 const [payload, updated_at, id] = args;
                 const row = tables.sync_jobs.find((r) => r.id === id);
@@ -321,6 +332,12 @@ export function createMemoryDriver() {
                 const row = tables.orders.find((r) => r.business_id === business_id && (r.id === id1 || r.order_number === id2));
                 return row ?? null;
             }
+            // orders hlc probe (absorb-if-applied touch detection)
+            if (s.includes("SELECT hlc FROM orders WHERE business_id = ? AND id = ?")) {
+                const [business_id, id] = args;
+                const row = tables.orders.find((r) => r.business_id === business_id && r.id === id);
+                return (row ? { hlc: row.hlc } : null);
+            }
             // sync_jobs pending single
             if (s.includes("SELECT * FROM sync_jobs WHERE business_id = ? AND entity_id = ? AND status='pending'")) {
                 const [business_id, entity_id] = args;

package/package.json

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