@teincfood/core 0.8.4 → 0.9.0

package/dist/reference/entitlement-crypto.js

@@ -0,0 +1,111 @@
+/**
+ * Minimal SHA-256 + HMAC-SHA256 (pure TS, no dependencies).
+ *
+ * Used to verify server-signed entitlement envelopes on every platform
+ * (Hermes / Tauri / Node) without relying on `crypto.subtle` availability.
+ * Test vectors: SHA256("") = e3b0c442...7852b855, HMAC per RFC 4231.
+ */
+function rotr(x, n) {
+    return (x >>> n) | (x << (32 - n));
+}
+const K = [
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+function utf8Bytes(input) {
+    const bytes = [];
+    for (let i = 0; i < input.length; i++) {
+        let code = input.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff && i + 1 < input.length) {
+            const next = input.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                code = 0x10000 + ((code - 0xd800) << 10) + (next - 0xdc00);
+                i++;
+            }
+        }
+        if (code < 0x80)
+            bytes.push(code);
+        else if (code < 0x800)
+            bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+        else if (code < 0x10000)
+            bytes.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+        else
+            bytes.push(0xf0 | (code >> 18), 0x80 | ((code >> 12) & 0x3f), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+    }
+    return bytes;
+}
+export function sha256Bytes(message) {
+    let h0 = 0x6a09e667, h1 = 0xbb67ae85, h2 = 0x3c6ef372, h3 = 0xa54ff53a;
+    let h4 = 0x510e527f, h5 = 0x9b05688c, h6 = 0x1f83d9ab, h7 = 0x5be0cd19;
+    const bitLen = message.length * 8;
+    const padded = [...message, 0x80];
+    while (padded.length % 64 !== 56)
+        padded.push(0);
+    // 64-bit length: high 32 bits assumed 0 (payloads far below 2^32 bits)
+    padded.push(0, 0, 0, 0, (bitLen >>> 24) & 0xff, (bitLen >>> 16) & 0xff, (bitLen >>> 8) & 0xff, bitLen & 0xff);
+    const w = new Array(64);
+    for (let off = 0; off < padded.length; off += 64) {
+        for (let i = 0; i < 16; i++) {
+            w[i] = ((padded[off + i * 4] << 24) | (padded[off + i * 4 + 1] << 16) | (padded[off + i * 4 + 2] << 8) | padded[off + i * 4 + 3]) | 0;
+        }
+        for (let i = 16; i < 64; i++) {
+            const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+            const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+        }
+        let a = h0, b = h1, c = h2, d = h3, e = h4, f = h5, g = h6, h = h7;
+        for (let i = 0; i < 64; i++) {
+            const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (h + S1 + ch + K[i] + w[i]) | 0;
+            const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (S0 + maj) | 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        h0 = (h0 + a) | 0;
+        h1 = (h1 + b) | 0;
+        h2 = (h2 + c) | 0;
+        h3 = (h3 + d) | 0;
+        h4 = (h4 + e) | 0;
+        h5 = (h5 + f) | 0;
+        h6 = (h6 + g) | 0;
+        h7 = (h7 + h) | 0;
+    }
+    const out = [];
+    for (const v of [h0, h1, h2, h3, h4, h5, h6, h7]) {
+        out.push((v >>> 24) & 0xff, (v >>> 16) & 0xff, (v >>> 8) & 0xff, v & 0xff);
+    }
+    return out;
+}
+export function sha256Hex(input) {
+    return sha256Bytes(utf8Bytes(input))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+export function hmacSha256Hex(key, message) {
+    let keyBytes = utf8Bytes(key);
+    if (keyBytes.length > 64)
+        keyBytes = sha256Bytes(keyBytes);
+    while (keyBytes.length < 64)
+        keyBytes.push(0);
+    const oKey = keyBytes.map((b) => b ^ 0x5c);
+    const iKey = keyBytes.map((b) => b ^ 0x36);
+    const inner = sha256Bytes([...iKey, ...utf8Bytes(message)]);
+    return sha256Bytes([...oKey, ...inner])
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}

package/dist/reference/entitlements.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Subscription entitlements — offline evaluation with own counter.
+ *
+ * Rules (fail-closed):
+ * - Envelope signature must verify, else NOT entitled (tamper-proof cache).
+ * - Expiry uses the monotonic entitlement clock anchored to backend
+ *   `server_time`, never `Date.now()` / device wall-clock.
+ * - Stale cache beyond `max_offline_days` (7) forces reconnect (read-only).
+ * - Unknown/missing state => not entitled. The backend remains the authority
+ *   (HTTP 402 on gated calls); this is the offline UX gate that cannot be
+ *   bypassed by editing SQLite, backdating the clock, or poisoning HLC.
+ */
+export declare const ENTITLEMENTS_KEY: "subscription:entitlements";
+/** Keys that only the server may write (no local merge, no LAN override). */
+export declare const SERVER_AUTHORITATIVE_KEYS: readonly string[];
+export declare function isServerAuthoritativeKey(key: string): boolean;
+export interface EntitlementEnvelope {
+    version: string;
+    server_time: string;
+    expires_at: string | null;
+    grace_until: string | null;
+    max_offline_days: number;
+    algorithm: string;
+    signature: string;
+}
+export type EntitlementState = "active" | "trialing" | "grace" | "expired" | "stale-blocked" | "unverified" | "no-plan";
+export interface EntitlementEvaluation {
+    state: EntitlementState;
+    /** May the gated feature be used offline right now? */
+    entitled: boolean;
+    /** Anchored server instant used for the decision (ms). */
+    serverNowMs: number;
+    /** True when the cache is too stale and the user must reconnect. */
+    mustReconnect: boolean;
+    reason: string;
+}
+export declare function canonicalEnvelopePayload(businessId: string, envelope: Pick<EntitlementEnvelope, "version" | "server_time" | "expires_at" | "grace_until">): string;
+export declare function signEntitlementEnvelope(businessId: string, envelope: Pick<EntitlementEnvelope, "version" | "server_time" | "expires_at" | "grace_until">, secret: string): string;
+export declare function verifyEntitlementEnvelope(businessId: string, envelope: EntitlementEnvelope | null | undefined, secret: string): boolean;
+export interface EvaluateInput {
+    businessId: string;
+    envelope: EntitlementEnvelope | null | undefined;
+    /** Raw entitlements payload (`data` map with features + subscription_status). */
+    features: Record<string, unknown> | null | undefined;
+    secret: string;
+}
+export declare function evaluateEntitlements(input: EvaluateInput): Promise<EntitlementEvaluation>;
+/** Fail-closed feature read: unknown/expired/unverified => false. */
+export declare function getEntitledFeature(evaluation: EntitlementEvaluation, features: Record<string, unknown> | null | undefined, key: string): boolean;
+/** Fail-closed numeric limit read: unknown/expired/unverified => 0. */
+export declare function getEntitledLimit(evaluation: EntitlementEvaluation, features: Record<string, unknown> | null | undefined, key: string): number;

package/dist/reference/entitlements.js

@@ -0,0 +1,124 @@
+/**
+ * Subscription entitlements — offline evaluation with own counter.
+ *
+ * Rules (fail-closed):
+ * - Envelope signature must verify, else NOT entitled (tamper-proof cache).
+ * - Expiry uses the monotonic entitlement clock anchored to backend
+ *   `server_time`, never `Date.now()` / device wall-clock.
+ * - Stale cache beyond `max_offline_days` (7) forces reconnect (read-only).
+ * - Unknown/missing state => not entitled. The backend remains the authority
+ *   (HTTP 402 on gated calls); this is the offline UX gate that cannot be
+ *   bypassed by editing SQLite, backdating the clock, or poisoning HLC.
+ */
+import { hmacSha256Hex } from "./entitlement-crypto";
+import { anchorServerTime, getLastAnchorMs, getServerNowMs } from "./entitlement-clock";
+export const ENTITLEMENTS_KEY = "subscription:entitlements";
+/** Keys that only the server may write (no local merge, no LAN override). */
+export const SERVER_AUTHORITATIVE_KEYS = [ENTITLEMENTS_KEY];
+export function isServerAuthoritativeKey(key) {
+    return SERVER_AUTHORITATIVE_KEYS.includes(key);
+}
+export function canonicalEnvelopePayload(businessId, envelope) {
+    return [businessId, envelope.version, envelope.server_time, envelope.expires_at ?? "", envelope.grace_until ?? ""].join("|");
+}
+export function signEntitlementEnvelope(businessId, envelope, secret) {
+    return hmacSha256Hex(secret, canonicalEnvelopePayload(businessId, envelope));
+}
+/** Constant-time-ish comparison to avoid trivial timing shortcuts. */
+function signaturesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+export function verifyEntitlementEnvelope(businessId, envelope, secret) {
+    if (!envelope || !secret)
+        return false;
+    if (!envelope.version || !envelope.server_time || !envelope.signature)
+        return false;
+    const expected = signEntitlementEnvelope(businessId, envelope, secret);
+    return signaturesEqual(expected, envelope.signature.toLowerCase()) ||
+        signaturesEqual(expected, envelope.signature);
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+export async function evaluateEntitlements(input) {
+    const { businessId, envelope, features, secret } = input;
+    if (!envelope || !verifyEntitlementEnvelope(businessId, envelope, secret)) {
+        return {
+            state: "unverified",
+            entitled: false,
+            serverNowMs: await getServerNowMs(),
+            mustReconnect: true,
+            reason: "Entitlement signature invalid — reconnect to verify subscription",
+        };
+    }
+    // Anchor the monotonic clock to this trusted server instant.
+    // Stale envelopes never reset the anchor (see anchorServerTime).
+    await anchorServerTime(envelope.server_time);
+    const serverNowMs = await getServerNowMs();
+    const lastAnchorMs = await getLastAnchorMs();
+    const maxOfflineDays = Number.isFinite(envelope.max_offline_days) ? envelope.max_offline_days : 7;
+    if (lastAnchorMs != null && serverNowMs - lastAnchorMs > maxOfflineDays * DAY_MS) {
+        return {
+            state: "stale-blocked",
+            entitled: false,
+            serverNowMs,
+            mustReconnect: true,
+            reason: `Subscription not verified for ${maxOfflineDays} days — reconnect required`,
+        };
+    }
+    const status = String(features?.["subscription_status"] ?? "none");
+    const expiresMs = envelope.expires_at ? Date.parse(envelope.expires_at) : NaN;
+    const graceMs = envelope.grace_until ? Date.parse(envelope.grace_until) : NaN;
+    if (!Number.isFinite(expiresMs)) {
+        // Legacy row without a period: entitled only when backend says so.
+        const entitled = status === "active" || status === "trialing";
+        return {
+            state: entitled ? status : "no-plan",
+            entitled,
+            serverNowMs,
+            mustReconnect: false,
+            reason: entitled ? "Active subscription (no period bound)" : "No subscription plan",
+        };
+    }
+    if (serverNowMs <= expiresMs) {
+        return {
+            state: status === "trialing" ? "trialing" : "active",
+            entitled: true,
+            serverNowMs,
+            mustReconnect: false,
+            reason: "Subscription in period",
+        };
+    }
+    if (Number.isFinite(graceMs) && serverNowMs <= graceMs) {
+        return {
+            state: "grace",
+            entitled: true,
+            serverNowMs,
+            mustReconnect: false,
+            reason: "Within grace period — renew soon",
+        };
+    }
+    return {
+        state: "expired",
+        entitled: false,
+        serverNowMs,
+        mustReconnect: false,
+        reason: "Subscription expired — upgrade to continue",
+    };
+}
+/** Fail-closed feature read: unknown/expired/unverified => false. */
+export function getEntitledFeature(evaluation, features, key) {
+    if (!evaluation.entitled || !features)
+        return false;
+    return features[key] === true;
+}
+/** Fail-closed numeric limit read: unknown/expired/unverified => 0. */
+export function getEntitledLimit(evaluation, features, key) {
+    if (!evaluation.entitled || !features)
+        return 0;
+    const v = Number(features[key]);
+    return Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
+}

package/dist/reference/operations.d.ts

@@ -8,6 +8,13 @@ export declare function getReferenceData<T>(db: SQLiteDatabase, businessId: stri
 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>;
 export declare function mergeReferenceData<T extends Record<string, unknown>>(db: SQLiteDatabase, businessId: string, key: ReferenceDataKey, incoming: Record<string, unknown>, hlc: string, eventId: string): Promise<void>;
+/**
+ * Server-authoritative write for verified payloads (subscription:entitlements).
+ * Overwrites only when the incoming server version is newer — a stale or
+ * replayed envelope can never rewind the cache. Local callers must never use
+ * set/mergeReferenceData for these keys.
+ */
+export declare function writeServerReferenceData<T>(db: SQLiteDatabase, businessId: string, key: ReferenceDataKey, payload: T, serverVersion: string): Promise<boolean>;
 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[]>;

package/dist/reference/operations.js

@@ -6,6 +6,7 @@ import { generateUUID } from "../utils/uuid";
 import { openSyncDatabase } from "../db/connection";
 import { getAppInstanceId } from "../adapters/devices";
 import { notifyDbChange } from "../db/operations";
+import { isServerAuthoritativeKey } from "./entitlements";
 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)
@@ -37,6 +38,11 @@ export async function setReferenceData(db, businessId, record) {
     notifyDbChange(businessId, `reference_data:${record.key}`);
 }
 export async function mergeReferenceData(db, businessId, key, incoming, hlc, eventId) {
+    // Server-authoritative keys (subscription:entitlements) never merge locally:
+    // LWW poisoning via a forged future HLC would otherwise stick forever.
+    // Use writeServerReferenceData() for the verified server path instead.
+    if (isServerAuthoritativeKey(key))
+        return;
     const existing = await getReferenceData(db, businessId, key);
     if (!existing) {
         await setReferenceData(db, businessId, {
@@ -63,6 +69,26 @@ export async function mergeReferenceData(db, businessId, key, incoming, hlc, eve
         lastHlc: hlc,
     });
 }
+/**
+ * Server-authoritative write for verified payloads (subscription:entitlements).
+ * Overwrites only when the incoming server version is newer — a stale or
+ * replayed envelope can never rewind the cache. Local callers must never use
+ * set/mergeReferenceData for these keys.
+ */
+export async function writeServerReferenceData(db, businessId, key, payload, serverVersion) {
+    const existing = await getReferenceData(db, businessId, key);
+    if (existing && compareHLCString(serverVersion, existing.version) <= 0)
+        return false;
+    await setReferenceData(db, businessId, {
+        key,
+        version: serverVersion,
+        payload,
+        downloadedAt: new Date().toISOString(),
+        lastEventId: `server_${serverVersion}`,
+        lastHlc: serverVersion,
+    });
+    return true;
+}
 export async function deleteReferenceData(db, businessId, key) {
     await db.runAsync("DELETE FROM reference_data WHERE business_id = ? AND key = ?;", businessId, key);
 }

package/dist/reference/service.js

@@ -14,7 +14,9 @@ import { menuService, businessService, rolesService } from "../adapters/services
 import { cacheImageBatch, pruneImageCache } from "../adapters/image-cache";
 import { getConnectivityState } from "../adapters/connectivity";
 import { canBusinessSync } from "../sync/sync-guard";
-import { getReferenceData, getReferenceVersion, mergeReferenceData, } from "./operations";
+import { getReferenceData, getReferenceVersion, mergeReferenceData, writeServerReferenceData, } from "./operations";
+import { anchorServerTime } from "./entitlement-clock";
+import { isServerAuthoritativeKey } from "./entitlements";
 import { fetchReferenceVersions, fetchReferenceData, fetchReferenceChanges, } from "./api";
 const DEFAULT_SYNC_KEYS = [
     "menu:items",
@@ -173,7 +175,26 @@ class ReferenceSyncService {
             version = fallback.version;
         }
         // LWW: newer HLC wins — local edits that are newer than server are preserved.
+        // Server-authoritative keys (subscription:entitlements) bypass LWW merge:
+        // only a newer verified server version overwrites, and the monotonic
+        // clock anchors to the envelope server_time. Never wall-clock.
         const hlc = version ?? generateUUID();
+        if (isServerAuthoritativeKey(key)) {
+            const record = payload;
+            const envelope = record && typeof record === "object" ? record.envelope : undefined;
+            if (!envelope?.version || !envelope?.server_time) {
+                syncLogger.error("ReferenceSync", `Refusing unverified ${key} payload (no envelope)`, {
+                    businessId,
+                });
+                throw new Error("Missing entitlement envelope");
+            }
+            const wrote = await writeServerReferenceData(db, businessId, key, payload, envelope.version);
+            try {
+                await anchorServerTime(envelope.server_time);
+            }
+            catch { }
+            return wrote;
+        }
         await mergeReferenceData(db, businessId, key, payload, hlc, `evt_${hlc}`);
         return true;
     }
@@ -283,6 +304,17 @@ class ReferenceSyncService {
                     version: this.hashPayload(payload),
                 };
             }
+            case "subscription:entitlements": {
+                // Direct full fetch; the syncKey server path requires the signed
+                // envelope and anchors the monotonic clock. Never fabricate one here.
+                const data = await fetchReferenceData(businessId, ["subscription:entitlements"]);
+                const payload = data["subscription:entitlements"];
+                const envelope = payload?.envelope;
+                return {
+                    payload,
+                    version: envelope?.version ?? this.hashPayload(payload),
+                };
+            }
             default:
                 throw new Error(`No fallback fetch available for ${key}`);
         }

package/dist/repositories/order.repository.js

@@ -9,6 +9,8 @@
  */
 import { syncEngine } from "../sync/engine";
 import { buildCommand } from "../sync/command-builder";
+import { assertOnlineFor, isOnlineCapable } from "../sync/online-gates";
+import { localNodeTransport } from "../sync/transport-local-node";
 import { generateUUID } from "../utils/uuid";
 async function executeCommand(command) {
     console.debug("[OrderRepository] Dispatching command", JSON.stringify({
@@ -112,6 +114,10 @@ export const orderRepository = {
         return executeCommand(command);
     },
     async confirmHandover(input) {
+        // Handover confirm is strictly online (dual merchant/rider confirm).
+        // A connected Local Node may relay; otherwise fail loudly, never queue.
+        if (!isOnlineCapable() && !localNodeTransport.isAvailable())
+            assertOnlineFor("delivery:confirm_handover");
         const command = buildCommand({
             commandType: "delivery:confirm_handover",
             businessId: input.businessId,
@@ -126,6 +132,11 @@ export const orderRepository = {
         return event.payload;
     },
     async assignRider(input) {
+        // Delivery assignment is strictly online: auto rider-match, GPS proximity
+        // and merchant/rider dual-confirm all require the backend. A connected
+        // Local Node may relay to the cloud; otherwise fail loudly — never queue.
+        if (!isOnlineCapable() && !localNodeTransport.isAvailable())
+            assertOnlineFor("delivery:assign");
         const command = buildCommand({
             commandType: "delivery:assign",
             businessId: input.businessId,

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

@@ -12,6 +12,8 @@ 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 { TransitionError, isReplayDeferred, TRANSITION_ERROR_CODES } from "./transition-errors";
+import { extractApiErrorCode } from "../utils/error";
 import { generateEventId } from "../utils/uuid";
 import { generateLocalCalloutNumber, generateOrderNumberForBusiness, generateOrderNumber, } from "./order-number";
 import { getConnectivityState, subscribeConnectivity } from "../adapters/connectivity";
@@ -239,7 +241,7 @@ class CommandQueueService {
     async processCommand(command) {
         if (!canBusinessSync(command.business_id)) {
             // No active business/session — defer until login+selection.
-            throw new Error("ReplayDeferred: no business/auth, deferring queued command");
+            throw new TransitionError(TRANSITION_ERROR_CODES.REPLAY_DEFERRED, "No business/auth, deferring queued command");
         }
         const db = getSyncDatabase();
         const parsedCommand = {
@@ -277,19 +279,19 @@ 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")) {
+            if (isReplayDeferred(error)) {
                 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")) {
+            const message = error instanceof Error ? error.message : String(error);
+            // 409 ORDER_NUMBER_TAKEN is retryable once with new RRR (exact backend code, any envelope)
+            const code = extractApiErrorCode(error);
+            if (apiErr?.status === 409 && code === "ORDER_NUMBER_TAKEN") {
                 if (command.command_type === "order:create") {
                     try {
                         const payload = command.payload;
@@ -312,8 +314,7 @@ class CommandQueueService {
                 await updateCommandStatus(db, command.command_id, "failed", `order_number_taken:${message}`);
                 throw error;
             }
-            const isNonRetryable = apiErr?.name === "ApiError" &&
-                typeof apiErr.status === "number" &&
+            const isNonRetryable = typeof apiErr?.status === "number" &&
                 apiErr.status >= 400 &&
                 apiErr.status < 500;
             if (isNonRetryable) {
@@ -388,11 +389,10 @@ class CommandQueueService {
                     await this.processCommand(command);
                 }
                 catch (e) {
-                    const apiErr = e;
-                    const isNonRetryable = apiErr?.name === "ApiError" &&
-                        typeof apiErr.status === "number" &&
-                        apiErr.status >= 400 &&
-                        apiErr.status < 500;
+                    const replayErr = e;
+                    const isNonRetryable = typeof replayErr?.status === "number" &&
+                        replayErr.status >= 400 &&
+                        replayErr.status < 500;
                     if (isNonRetryable) {
                         // Already marked permanent in processCommand — continue to next.
                         continue;

package/dist/sync/engine.js

@@ -16,12 +16,14 @@ import { localNodeTransport } from "./transport-local-node";
 import { commandQueueService } from "./command-queue.service";
 import { getConnectivityState, setConnectivityState } from "../adapters/connectivity";
 import { ApiError } from "../adapters/http";
+import { errorCodeOf } from "./transition-errors";
 import { syncLogger } from "../utils/sync-logger";
 import { CLOUD_COMMAND_TIMEOUT_MS } from "../utils/constants";
 import { CAPABILITY_BY_COMMAND } from "../reference/capabilities";
 import { getReferenceData } from "../reference/operations";
 import { openSyncDatabase } from "../db/connection";
 import { canBusinessSync } from "./sync-guard";
+import { TRANSITION_ERROR_CODES, TransitionError } from "./transition-errors";
 function withTimeout(promise, ms) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
@@ -56,7 +58,7 @@ export class SyncEngine {
     async execute(command, opts) {
         if (!command.business_id || !canBusinessSync(command.business_id)) {
             // No active business/auth — don't route to cloud/LAN or queue with empty bid.
-            throw new Error("Sync requires active business and login — business_id missing or not authenticated");
+            throw new TransitionError(TRANSITION_ERROR_CODES.NO_ACTIVE_BUSINESS, "Sync requires active business and login — business_id missing or not authenticated");
         }
         syncLogger.command(command, "issued");
         // Perms guard (offline-capable): block before routing
@@ -93,7 +95,7 @@ export class SyncEngine {
             // itself without executing). If no real transport is available, leave
             // the row untouched for a later trigger.
             if (opts?.forReplay) {
-                throw new Error("ReplayDeferred: no transport available, keeping command queued");
+                throw new TransitionError(TRANSITION_ERROR_CODES.REPLAY_DEFERRED, "No transport available, keeping command queued");
             }
             const event = await commandQueueService.enqueue(command);
             this.broadcast(event);
@@ -148,15 +150,22 @@ export class SyncEngine {
             }
             catch (error) {
                 // Definitive server rejection (4xx): the backend answered with a real
-                // decision (e.g. PAYMENT_REQUIRED, FORBIDDEN). Surface it to the
-                // caller instead of masking it as a connectivity problem and silently
-                // queueing a command that can never succeed.
-                if (error instanceof ApiError && error.status >= 400 && error.status < 500) {
+                // decision (e.g. INVALID_TRANSITION, PAYMENT_REQUIRED, FORBIDDEN).
+                // Surface it instead of masking it as a connectivity problem and
+                // silently queueing a command that can never succeed. Shape-based
+                // (status range), never instanceof: apps throw their own ApiError
+                // class, and TransitionError guards carry no HTTP status.
+                const rejectionStatus = typeof error?.status === "number"
+                    ? error.status
+                    : undefined;
+                if (rejectionStatus !== undefined && rejectionStatus >= 400 && rejectionStatus < 500) {
+                    const code = errorCodeOf(error);
                     syncLogger.warn("SyncEngine", "Cloud command rejected by server", {
                         command_type: command.command_type,
                         command_id: command.command_id,
-                        status: error.status,
-                        message: error.message,
+                        status: rejectionStatus,
+                        code,
+                        message: error instanceof Error ? error.message : String(error),
                     });
                     throw error;
                 }
@@ -173,7 +182,7 @@ export class SyncEngine {
                     // itself without executing). If no real transport is available, leave
                     // the row untouched for a later trigger.
                     if (opts?.forReplay) {
-                        throw new Error("ReplayDeferred: no transport available, keeping command queued");
+                        throw new TransitionError(TRANSITION_ERROR_CODES.REPLAY_DEFERRED, "No transport available, keeping command queued");
                     }
                     const event = await commandQueueService.enqueue(command);
                     this.broadcast(event);

package/dist/sync/online-gates.d.ts

@@ -15,3 +15,12 @@ export declare function isOnlineCapable(): boolean;
  * and delivery/order transitions the domain already gates.
  */
 export declare function assertOnlineFor(commandType: string, payload?: Record<string, unknown>): void;
+/**
+ * Offline entitlement gate (fail-closed). Host apps evaluate the cached
+ * signed envelope via `evaluateEntitlements` and pass `entitled` here for
+ * gated commands (menu/member/promo/terminal/dispatch creation, online
+ * orders). Expired, stale (> max_offline_days), or unverified => throw.
+ * RBAC (`hasCapabilitySync`) stays fail-open (backend 403 backstop);
+ * entitlements are the opposite: no proof => no access.
+ */
+export declare function assertEntitledFor(commandType: string, entitled: boolean, evaluationReason?: string): void;