@teincfood/core 0.8.4 → 0.9.1

package/dist/db/operations.d.ts

@@ -88,6 +88,14 @@ export declare function updateOrderPayment(db: SQLiteDatabase, businessId: strin
     is_paid: boolean;
     paid_at: string | null;
 }): Promise<void>;
+/**
+ * Patch delivery linkage from realtime delivery events (delivery.assigned /
+ * delivery.status_changed / delivery.pickup_confirmed) so every terminal
+ * converges on assign-vs-handover branching without a refetch.
+ */
+export declare function updateOrderDelivery(db: SQLiteDatabase, businessId: string, orderId: string, patch: {
+    delivery_id?: string | null;
+}): Promise<void>;
 export declare function clearAllSyncData(db: SQLiteDatabase): Promise<void>;
 export declare function wipeForNewInstall(db: SQLiteDatabase): Promise<void>;
 export declare function clearReferenceData(db: SQLiteDatabase): Promise<void>;

package/dist/db/operations.js

@@ -284,6 +284,17 @@ export async function updateOrderPayment(db, businessId, orderId, patch) {
     await db.runAsync(`UPDATE orders SET payment = ?, hlc = ? WHERE business_id = ? AND (id = ? OR order_number = ?);`, JSON.stringify(payment), new Date().toISOString(), businessId, orderId, orderId);
     notifyDbChange(businessId, "orders");
 }
+/**
+ * Patch delivery linkage from realtime delivery events (delivery.assigned /
+ * delivery.status_changed / delivery.pickup_confirmed) so every terminal
+ * converges on assign-vs-handover branching without a refetch.
+ */
+export async function updateOrderDelivery(db, businessId, orderId, patch) {
+    if (patch.delivery_id === undefined)
+        return;
+    await db.runAsync(`UPDATE orders SET delivery_id = ?, hlc = ? WHERE business_id = ? AND (id = ? OR order_number = ?);`, patch.delivery_id, new Date().toISOString(), businessId, orderId, orderId);
+    notifyDbChange(businessId, "orders");
+}
 // ─────────────────────────────────────────────────────────────
 // Maintenance — clear stale local data (used by Diagnostics)
 // ─────────────────────────────────────────────────────────────

package/dist/domain/orders/service.js

@@ -12,6 +12,7 @@ import { getConnectivityState } from "../../adapters/connectivity";
 import { assertOnlineFor } from "../../sync/online-gates";
 import { assertBusinessOpenForCreate } from "../../utils/business-hours";
 import { canTransition } from "../../utils/order-transitions";
+import { TRANSITION_ERROR_CODES, TransitionError } from "../../sync/transition-errors";
 import { validateOrderCreateInput } from "../../validation/offline";
 import { drainOne, pullRemoteOrders } from "../../sync/sync-jobs.service";
 import { getAuthToken } from "../../adapters/auth";
@@ -164,12 +165,12 @@ export async function createLocalOrder(businessId, input) {
 }
 export async function transitionLocalOrder(businessId, orderId, action) {
     if (!businessId || !canBusinessSync(businessId)) {
-        throw new Error("Transition requires active business/login");
+        throw new TransitionError(TRANSITION_ERROR_CODES.NO_ACTIVE_BUSINESS, "Transition requires active business/login");
     }
     const db = await openSyncDatabase();
     const order = await getOrderById(db, businessId, orderId);
     if (!order)
-        throw new Error("Order not found");
+        throw new TransitionError(TRANSITION_ERROR_CODES.ORDER_NOT_FOUND, "Order not found");
     // Delivery transitions require online (single source: sync/online-gates).
     if (action === "assign_rider")
         assertOnlineFor("order:assign_rider");
@@ -178,7 +179,7 @@ export async function transitionLocalOrder(businessId, orderId, action) {
     else if (order.order_type === "delivery")
         assertOnlineFor("order:create", { order_type: "delivery" });
     if (!canTransition(order, action)) {
-        throw new Error(`Cannot ${action} from ${order.status}`);
+        throw new TransitionError(TRANSITION_ERROR_CODES.INVALID_TRANSITION, `Cannot ${action} from ${order.status}`);
     }
     const map = { accept: "accepted", reject: "cancelled", start_preparing: "preparing", mark_ready: "ready", complete_pickup: "delivered", cancel: "cancelled", assign_rider: "assigned", confirm_handover: "delivered", confirm_cash: order.status, pay: order.status };
     const toStatus = map[action] ?? order.status;

package/dist/hooks/analytics.hooks.d.ts

@@ -11,6 +11,77 @@ export declare const REVENUE_KEYS: {
     all: readonly ["revenue-summary"];
     summary: (businessId?: string, period?: string) => readonly ["revenue-summary", string | undefined, string | undefined];
 };
+interface LocalOrderRow {
+    status: string;
+    total_minor: number;
+    subtotal_minor?: number;
+    inserted_at: string;
+    payment_mode?: string;
+    pos_payment_method?: string;
+    order_type?: string;
+    items?: Array<{
+        quantity?: number;
+        subtotal?: number;
+        total_price_minor?: number;
+        menu_item?: {
+            name?: string;
+        };
+    }>;
+}
+interface AggregateOptions {
+    forRevenueSummary: boolean;
+}
+export declare function aggregateLocal(orders: LocalOrderRow[], period: "today" | "this_week" | "this_month", opts: AggregateOptions): {
+    period: "this_month" | "this_week" | "today";
+    total_revenue_minor: number;
+    total_orders: number;
+    average_order_value_minor: number;
+    by_payment_method: {
+        revenue_minor: number;
+        count: number;
+        method: string;
+        percentage: number;
+    }[];
+    by_order_type: {
+        revenue_minor: number;
+        count: number;
+        type: string;
+    }[];
+    by_day: {
+        revenue_minor: number;
+        count: number;
+        date: string;
+    }[];
+    offline: boolean;
+    total_refunds_minor?: undefined;
+    top_items?: undefined;
+    orders_by_status?: undefined;
+    revenue_by_day?: undefined;
+} | {
+    by_payment_method?: undefined;
+    by_order_type?: undefined;
+    by_day?: undefined;
+    period: "this_month" | "this_week" | "today";
+    total_revenue_minor: number;
+    total_orders: number;
+    average_order_value_minor: number;
+    total_refunds_minor: number;
+    top_items: {
+        name: string;
+        quantity: number;
+        revenue_minor: number;
+    }[];
+    orders_by_status: {
+        delivered: number;
+        cancelled: number;
+        pending: number;
+    };
+    revenue_by_day: {
+        date: string;
+        revenue_minor: number;
+    }[];
+    offline: boolean;
+};
 export declare function useSellerAnalyticsQuery(period?: "today" | "this_week" | "this_month", enabled?: boolean): import("@tanstack/react-query").UseQueryResult<{
     data?: {
         period?: string;
@@ -23,3 +94,4 @@ export declare function useRevenueSummaryQuery(period?: "today" | "this_week" |
         by_day?: unknown[];
     };
 }, Error>;
+export {};

package/dist/hooks/analytics.hooks.js

@@ -50,18 +50,22 @@ function filterByPeriod(orders, period) {
         return d >= startStr && d <= todayStr;
     });
 }
-function aggregateLocal(orders, period, opts) {
+export function aggregateLocal(orders, period, opts) {
     const filtered = filterByPeriod(orders, period);
-    const total_revenue_minor = filtered.reduce((s, o) => s + (o.total_minor ?? 0), 0);
-    const total_orders = filtered.length;
-    const average_order_value_minor = total_orders ? Math.round(total_revenue_minor / total_orders) : 0;
+    // Backend parity (orders.ex get_business_analytics / get_revenue_summary):
+    // revenue-eligible = all EXCEPT cancelled. Cancelled orders must never
+    // inflate revenue, counts, breakdowns, or top items — online and offline.
+    const revenueOrders = filtered.filter((o) => o.status !== "cancelled");
+    const total_revenue_minor = revenueOrders.reduce((s, o) => s + (o.total_minor ?? 0), 0);
+    const total_orders = revenueOrders.length;
+    // Backend uses div (truncation) — mirror, don't round.
+    const average_order_value_minor = total_orders ? Math.floor(total_revenue_minor / total_orders) : 0;
     const byMethod = new Map();
     const byType = new Map();
     const byDay = new Map();
-    const byStatus = {};
     const itemQty = new Map();
     const itemRev = new Map();
-    for (const o of filtered) {
+    for (const o of revenueOrders) {
         const method = o.pos_payment_method ?? o.payment_mode ?? "cash";
         const m = byMethod.get(method) ?? { revenue_minor: 0, count: 0 };
         m.revenue_minor += o.total_minor ?? 0;
@@ -77,7 +81,6 @@ function aggregateLocal(orders, period, opts) {
         d.revenue_minor += o.total_minor ?? 0;
         d.count += 1;
         byDay.set(day, d);
-        byStatus[o.status] = (byStatus[o.status] ?? 0) + 1;
         for (const it of o.items ?? []) {
             const name = it.menu_item?.name ?? "Unknown";
             const qty = it.quantity ?? 0;
@@ -87,6 +90,12 @@ function aggregateLocal(orders, period, opts) {
         }
     }
     const pct = (v) => (total_revenue_minor > 0 ? Math.round((v / total_revenue_minor) * 1000) / 10 : 0);
+    // Backend orders_by_status counts over ALL period orders (not revenue-only).
+    const orders_by_status = {
+        delivered: filtered.filter((o) => o.status === "delivered").length,
+        cancelled: filtered.filter((o) => o.status === "cancelled").length,
+        pending: filtered.filter((o) => o.status === "pending").length,
+    };
     if (opts.forRevenueSummary) {
         return {
             period,
@@ -115,7 +124,7 @@ function aggregateLocal(orders, period, opts) {
             .map(([name, quantity]) => ({ name, quantity, revenue_minor: itemRev.get(name) ?? 0 }))
             .sort((a, b) => b.revenue_minor - a.revenue_minor)
             .slice(0, 10),
-        orders_by_status: byStatus,
+        orders_by_status,
         revenue_by_day: [...byDay.entries()]
             .map(([date, v]) => ({ date, revenue_minor: v.revenue_minor }))
             .sort((a, b) => a.date.localeCompare(b.date)),

package/dist/hooks/dashboard.hooks.d.ts

@@ -10,6 +10,19 @@ export declare const SELLER_DASHBOARD_KEYS: {
     recentOrders: (businessId?: string) => readonly ["seller-dashboard", "recent-orders", string | undefined];
     full: (businessId?: string) => readonly ["seller-dashboard", "full", string | undefined];
 };
+interface LocalOrderRow {
+    status: string;
+    total_minor: number;
+    inserted_at: string;
+    order_number: string;
+    id: string;
+}
+/**
+ * Pure metrics aggregation — exported for tests. Mirrors backend
+ * get_business_dashboard: revenue = delivered-only, today_orders = all,
+ * pending = pending-only, active = accepted/preparing/ready.
+ */
+export declare function computeDashboardMetrics(orders: LocalOrderRow[], todayStr: string): SellerDashboardMetrics;
 export declare function useSellerDashboardMetricsQuery(businessId: string, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<SellerDashboardMetrics, Error>;
 export declare function useSellerDashboardRecentOrdersQuery(businessId: string, enabled?: boolean): import("@tanstack/react-query").UseQueryResult<{
     id: string;
@@ -28,3 +41,4 @@ export declare function useSellerDashboardQuery(businessId: string, enabled?: bo
         item_count: number;
     }[];
 }, Error>;
+export {};

package/dist/hooks/dashboard.hooks.js

@@ -21,23 +21,30 @@ const EMPTY_METRICS = {
     average_rating: 0,
 };
 /**
- * Local SQLite aggregates — instant, even online. Single source for all
- * three dashboard queries so metrics/recent/full never diverge.
+ * Pure metrics aggregation — exported for tests. Mirrors backend
+ * get_business_dashboard: revenue = delivered-only, today_orders = all,
+ * pending = pending-only, active = accepted/preparing/ready.
  */
+export function computeDashboardMetrics(orders, todayStr) {
+    const todayOrders = orders.filter((o) => (o.inserted_at ?? "").slice(0, 10) === todayStr);
+    const todayRevenue = todayOrders
+        .filter((o) => o.status === "delivered")
+        .reduce((sum, o) => sum + (o.total_minor ?? 0), 0);
+    const pending = orders.filter((o) => o.status === "pending").length;
+    const active = orders.filter((o) => ["accepted", "preparing", "ready"].includes(o.status)).length;
+    return { today_orders: todayOrders.length, today_revenue_minor: todayRevenue, pending_orders: pending, active_orders: active, average_rating: 0 };
+}
 async function computeLocalDashboard(businessId) {
     const { data } = await listLocalOrders(businessId, {}, 1, 200);
     const orders = (data ?? []);
     const todayStr = new Date().toISOString().slice(0, 10);
-    const todayOrders = orders.filter((o) => (o.inserted_at ?? "").slice(0, 10) === todayStr);
-    const todayRevenue = todayOrders.reduce((sum, o) => sum + (o.total_minor ?? 0), 0);
-    const pending = orders.filter((o) => ["pending", "awaiting_payment", "accepted"].includes(o.status)).length;
-    const active = orders.filter((o) => !["delivered", "cancelled", "rejected"].includes(o.status)).length;
+    const metrics = computeDashboardMetrics(orders, todayStr);
     const recent = [...orders]
         .sort((a, b) => (b.inserted_at ?? "").localeCompare(a.inserted_at ?? ""))
         .slice(0, 5)
         .map((o) => ({ id: o.id, order_number: o.order_number, status: o.status, total_minor: o.total_minor, item_count: 1 }));
     return {
-        metrics: { today_orders: todayOrders.length, today_revenue_minor: todayRevenue, pending_orders: pending, active_orders: active, average_rating: 0 },
+        metrics,
         recent_orders: recent,
     };
 }

package/dist/hooks/members.hooks.d.ts

@@ -38,6 +38,10 @@ export declare function useAcceptFleetInvitationMutation(): import("@tanstack/re
 export declare function useAcceptBusinessInvitationMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, {
     code: string;
 }, unknown>;
+export declare function useDeclineBusinessInvitationMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, {
+    code: string;
+}, unknown>;
+export declare function useResendMemberInvitationMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, string, unknown>;
 export declare function useBusinessRolesQuery(enabled?: boolean): import("@tanstack/react-query").UseQueryResult<unknown, Error>;
 export declare function useBusinessTaxRulesQuery(enabled?: boolean): import("@tanstack/react-query").UseQueryResult<unknown, Error>;
 export declare function useCreateTaxRuleMutation(): import("@tanstack/react-query").UseMutationResult<unknown, Error, Record<string, unknown>, unknown>;

package/dist/hooks/members.hooks.js

@@ -209,6 +209,39 @@ export function useAcceptBusinessInvitationMutation() {
         },
     });
 }
+export function useDeclineBusinessInvitationMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (data) => {
+            assertOnlineFor("member:manage");
+            return businessService.declineBusinessInvitation(data);
+        },
+        onSuccess: () => {
+            notifySuccess("Invitation declined");
+            queryClient.invalidateQueries({ queryKey: INVITATION_KEYS.list() });
+        },
+        onError: (error) => {
+            notifyError(extractApiErrorMessage(error));
+        },
+    });
+}
+export function useResendMemberInvitationMutation() {
+    const queryClient = useQueryClient();
+    const businessId = useBusinessId();
+    return useMutation({
+        mutationFn: (invitationId) => {
+            assertOnlineFor("member:manage");
+            return businessService.resendBusinessMemberInvitation(businessId, invitationId);
+        },
+        onSuccess: () => {
+            notifySuccess("Invitation resent");
+            queryClient.invalidateQueries({ queryKey: MEMBER_KEYS.invitations(businessId ?? "") });
+        },
+        onError: (error) => {
+            notifyError(extractApiErrorMessage(error));
+        },
+    });
+}
 // ─── Roles ───
 export function useBusinessRolesQuery(enabled = true) {
     const businessId = useBusinessId();

package/dist/hooks/orders.hooks.js

@@ -8,7 +8,8 @@ import { getActiveBusiness, subscribeBusiness } from "../adapters/business";
 import { useSyncExternalStore } from "react";
 import { listLocalOrders, getLocalOrder } from "../domain/orders/service";
 import { getDeviceNumber, ensureLease } from "../sync/device-lease.service";
-import { assertOnlineFor } from "../sync/online-gates";
+import { assertOnlineFor, isOnlineCapable } from "../sync/online-gates";
+import { localNodeTransport } from "../sync/transport-local-node";
 import { SELLER_DASHBOARD_KEYS } from "../adapters/query-keys";
 import { openSyncDatabase } from "../db/connection";
 import { getReferenceData } from "../reference/operations";
@@ -157,13 +158,15 @@ export function useConfirmHandoverMutation() {
     const bid = useBusinessId();
     const qc = useQueryClient();
     return useMutation({ mutationFn: (deliveryId) => { if (!bid)
-            throw new Error("No business"); assertOnlineFor("order:confirm_handover"); return orderRepository.confirmHandover({ deliveryId, businessId: bid }); }, onSuccess: () => { qc.invalidateQueries({ queryKey: SELLER_KEYS.all }); qc.invalidateQueries({ queryKey: POS_KEYS.all }); qc.invalidateQueries({ queryKey: SELLER_DASHBOARD_KEYS.all }); } });
+            throw new Error("No business"); if (!isOnlineCapable() && !localNodeTransport.isAvailable())
+            assertOnlineFor("order:confirm_handover"); return orderRepository.confirmHandover({ deliveryId, businessId: bid }); }, onSuccess: () => { qc.invalidateQueries({ queryKey: SELLER_KEYS.all }); qc.invalidateQueries({ queryKey: POS_KEYS.all }); qc.invalidateQueries({ queryKey: SELLER_DASHBOARD_KEYS.all }); } });
 }
 export function useAssignRiderMutation() {
     const bid = useBusinessId();
     const qc = useQueryClient();
     return useMutation({ mutationFn: ({ orderId, riderId }) => { if (!bid)
-            throw new Error("No business"); assertOnlineFor("order:assign_rider"); return orderRepository.assignRider({ orderId, riderId, businessId: bid }); }, onSuccess: () => { qc.invalidateQueries({ queryKey: SELLER_KEYS.all }); qc.invalidateQueries({ queryKey: SELLER_DASHBOARD_KEYS.all }); } });
+            throw new Error("No business"); if (!isOnlineCapable() && !localNodeTransport.isAvailable())
+            assertOnlineFor("order:assign_rider"); return orderRepository.assignRider({ orderId, riderId, businessId: bid }); }, onSuccess: () => { qc.invalidateQueries({ queryKey: SELLER_KEYS.all }); qc.invalidateQueries({ queryKey: POS_KEYS.all }); qc.invalidateQueries({ queryKey: SELLER_DASHBOARD_KEYS.all }); } });
 }
 export function useConfirmCashPaymentMutation() {
     const bid = useBusinessId();

package/dist/hooks/realtime-stubs.js

@@ -16,7 +16,11 @@ import { orderSnapshotsService } from "../sync/order-snapshots.service";
 import { syncEngine } from "../sync/engine";
 import { generateEventId } from "../utils/uuid";
 import { getAppInstanceId } from "../adapters/devices";
+import { getActiveBusiness } from "../adapters/business";
+import { openSyncDatabase } from "../db/connection";
+import { getOrderById } from "../db/operations";
 const INVALIDATE_DEBOUNCE_MS = 400;
+const UNKNOWN_ORDER_PULL_DEBOUNCE_MS = 1500;
 /**
  * Subscribe to real-time order events and invalidate all queries under the
  * given root key prefix (e.g. ['seller'], ['pos'], ['kiosk']).
@@ -49,6 +53,16 @@ export function useOrderRealtimeUpdates(rootKey) {
             if (event.order_id)
                 pendingOrderIds.add(event.order_id);
             const payload = { ...event };
+            // Delivery events carry no business_id — the socket already filtered by
+            // business, so stamp the active one for read-model patching.
+            if (!payload.business_id && !payload.businessId) {
+                try {
+                    const bid = getActiveBusiness()?.id;
+                    if (bid)
+                        payload.business_id = bid;
+                }
+                catch { }
+            }
             const domainEvent = {
                 event_id: payload.event_id ?? generateEventId(),
                 event_type: event.type,
@@ -61,6 +75,24 @@ export function useOrderRealtimeUpdates(rootKey) {
             };
             // Persist to durable offline read model (entity_snapshots table).
             orderSnapshotsService.persistOrderEvent(domainEvent, "cloud").catch(() => { });
+            // order.created from another terminal is summary-only (no full body):
+            // invalidate alone can't surface it because SQLite has no row. Pull
+            // once (debounced) when the order is unknown locally. Event-driven —
+            // no polling.
+            if (event.type === "order.created" && event.order_id) {
+                const bid = payload.business_id;
+                if (bid) {
+                    void (async () => {
+                        try {
+                            const db = await openSyncDatabase();
+                            const known = await getOrderById(db, bid, event.order_id);
+                            if (!known)
+                                scheduleUnknownOrderPull(bid);
+                        }
+                        catch { }
+                    })();
+                }
+            }
             // Publish through the Sync Engine so useSyncReconciliation + LAN relay
             // fire without waiting for the next poll.
             try {
@@ -77,6 +109,22 @@ export function useOrderRealtimeUpdates(rootKey) {
         };
     }, [queryClient, rootKey]);
 }
+/**
+ * Debounced pull for remotely-created orders (one timer per business).
+ * Module-level so bursts across screens coalesce into a single pull.
+ */
+const unknownOrderPullTimers = new Map();
+function scheduleUnknownOrderPull(businessId) {
+    if (unknownOrderPullTimers.has(businessId))
+        return;
+    const t = setTimeout(() => {
+        unknownOrderPullTimers.delete(businessId);
+        void import("../sync/sync-jobs.service")
+            .then((m) => m.pullRemoteOrders(businessId))
+            .catch(() => { });
+    }, UNKNOWN_ORDER_PULL_DEBOUNCE_MS);
+    unknownOrderPullTimers.set(businessId, t);
+}
 /**
  * Global realtime invalidation — currently handled entirely by
  * useOrderRealtimeUpdates + useSyncReconciliation. Kept as a no-op for

package/dist/index.d.ts

@@ -97,6 +97,9 @@ export { referenceSyncService } from "./reference/service";
 export * from "./reference/menu-record";
 export * from "./reference/menu-apply";
 export * from "./reference/capabilities";
+export * from "./reference/entitlements";
+export * from "./reference/entitlement-clock";
+export { hmacSha256Hex, sha256Hex } from "./reference/entitlement-crypto";
 export * from "./adapters/sqlite";
 export { KVDriver, setKVDriver, getKVDriver, kvGetItem, kvSetItem, kvRemoveItem, getItem, setItem, removeItem, getItemSync, setItemSync } from "./adapters/kv";
 export * from "./adapters/connectivity";
@@ -125,6 +128,8 @@ export * from "./cart/store";
 export * from "./cart/hooks";
 export * from "./catalog/hooks";
 export * from "./utils/order-transitions";
+export * from "./sync/transition-errors";
+export * from "./sync/transition-endpoints";
 export * from "./utils/business-hours";
 export * from "./hooks/business-hours.hooks";
 export * from "./domain/orders/service";

package/dist/index.js

@@ -99,6 +99,9 @@ export { referenceSyncService } from "./reference/service";
 export * from "./reference/menu-record";
 export * from "./reference/menu-apply";
 export * from "./reference/capabilities";
+export * from "./reference/entitlements";
+export * from "./reference/entitlement-clock";
+export { hmacSha256Hex, sha256Hex } from "./reference/entitlement-crypto";
 // ── Adapters (for host apps to supply) ──
 export * from "./adapters/sqlite";
 export { setKVDriver, getKVDriver, kvGetItem, kvSetItem, kvRemoveItem, getItem, setItem, removeItem, getItemSync, setItemSync } from "./adapters/kv";
@@ -135,6 +138,8 @@ export * from "./cart/hooks";
 export * from "./catalog/hooks";
 // ── Order transitions (shared business logic — single source) ──
 export * from "./utils/order-transitions";
+export * from "./sync/transition-errors";
+export * from "./sync/transition-endpoints";
 // ── Business hours gate (single source — mirrors backend is_open?) ──
 export * from "./utils/business-hours";
 export * from "./hooks/business-hours.hooks";

package/dist/reference/api.js

@@ -30,8 +30,18 @@ export async function fetchReferenceData(businessId, keys) {
         const cached = await localNodeFetcher({ businessId, keys });
         const out = {};
         for (const key of keys) {
-            if (cached[key]?.payload != null)
-                out[key] = cached[key].payload;
+            const rec = cached[key];
+            if (rec?.payload == null)
+                continue;
+            // LAN relays are untrusted for server-authoritative keys: only forward
+            // payloads carrying a signed envelope; signature is verified at
+            // evaluation time and the monotonic clock anchors to server_time.
+            if (key === "subscription:entitlements") {
+                const envelope = rec.payload?.envelope;
+                if (!envelope?.version || !envelope?.server_time || !envelope?.signature)
+                    continue;
+            }
+            out[key] = rec.payload;
         }
         return out;
     }

package/dist/reference/entitlement-clock.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Monotonic entitlement clock — own counter, never device wall-clock.
+ *
+ * Clients anchor to backend `server_time` on every entitlements sync and
+ * advance with a monotonic source (`performance.now()`). Wall-clock
+ * backdating cannot extend a trial: time only moves forward from the last
+ * anchored/seen server instant, and survives restarts via KV persistence.
+ */
+export interface EntitlementClockAnchor {
+    /** Trusted server instant (ms since epoch) from the last envelope. */
+    serverMs: number;
+    /** Monotonic reading at the moment of anchoring. */
+    monoBase: number;
+}
+type MonoSource = () => number;
+/** Test seam: inject a deterministic monotonic source. */
+export declare function setMonoSource(fn: MonoSource | null): void;
+export declare function monoNow(): number;
+/**
+ * Anchor the clock to a trusted backend server_time.
+ * Always moves forward: a stale or replayed server_time (older than the
+ * current anchor) never rewinds the clock AND never resets the monotonic
+ * base — otherwise re-reading a cached envelope would erase elapsed
+ * offline time and grant perpetual access.
+ */
+export declare function anchorServerTime(serverTimeIso: string): Promise<number>;
+/**
+ * Current server-anchored instant (ms). Monotonic non-decreasing within
+ * what persistence allows. Falls back to wall-clock only when never anchored
+ * (first launch before any sync) — callers treat unanchored as unverified.
+ */
+export declare function getServerNowMs(): Promise<number>;
+/** True once at least one trusted server_time has been anchored. */
+export declare function isAnchored(): Promise<boolean>;
+/** Last trusted anchor instant (ms), or null when never synced. */
+export declare function getLastAnchorMs(): Promise<number | null>;
+/** Test seam: clear persisted clock state. */
+export declare function resetEntitlementClock(): Promise<void>;
+export {};

package/dist/reference/entitlement-clock.js

@@ -0,0 +1,116 @@
+/**
+ * Monotonic entitlement clock — own counter, never device wall-clock.
+ *
+ * Clients anchor to backend `server_time` on every entitlements sync and
+ * advance with a monotonic source (`performance.now()`). Wall-clock
+ * backdating cannot extend a trial: time only moves forward from the last
+ * anchored/seen server instant, and survives restarts via KV persistence.
+ */
+import { kvGetItem, kvSetItem } from "../adapters/kv";
+const ANCHOR_KEY = "sub:clock-anchor";
+const LAST_SEEN_KEY = "sub:clock-last-seen";
+let monoSource = null;
+/** Test seam: inject a deterministic monotonic source. */
+export function setMonoSource(fn) {
+    monoSource = fn;
+}
+export function monoNow() {
+    try {
+        if (monoSource)
+            return monoSource();
+        const g = globalThis;
+        if (typeof g.performance?.now === "function")
+            return g.performance.now();
+    }
+    catch {
+        /* fall through */
+    }
+    return Date.now();
+}
+async function readAnchor() {
+    try {
+        const raw = await kvGetItem(ANCHOR_KEY);
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (!Number.isFinite(parsed.serverMs) || !Number.isFinite(parsed.monoBase))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+async function readLastSeen() {
+    try {
+        const raw = await kvGetItem(LAST_SEEN_KEY);
+        if (raw == null)
+            return null;
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Anchor the clock to a trusted backend server_time.
+ * Always moves forward: a stale or replayed server_time (older than the
+ * current anchor) never rewinds the clock AND never resets the monotonic
+ * base — otherwise re-reading a cached envelope would erase elapsed
+ * offline time and grant perpetual access.
+ */
+export async function anchorServerTime(serverTimeIso) {
+    const serverMs = Date.parse(serverTimeIso);
+    const now = monoNow();
+    if (!Number.isFinite(serverMs))
+        return getServerNowMs();
+    const prev = await readAnchor();
+    const lastSeen = await readLastSeen();
+    if (prev && serverMs <= prev.serverMs)
+        return getServerNowMs();
+    const base = Math.max(serverMs, prev?.serverMs ?? -Infinity, lastSeen ?? -Infinity);
+    const anchor = { serverMs: base, monoBase: now };
+    try {
+        await kvSetItem(ANCHOR_KEY, JSON.stringify(anchor));
+        await kvSetItem(LAST_SEEN_KEY, String(base));
+    }
+    catch {
+        /* persistence is best-effort; in-memory math still holds for the session */
+    }
+    return base;
+}
+/**
+ * Current server-anchored instant (ms). Monotonic non-decreasing within
+ * what persistence allows. Falls back to wall-clock only when never anchored
+ * (first launch before any sync) — callers treat unanchored as unverified.
+ */
+export async function getServerNowMs() {
+    const anchor = await readAnchor();
+    const lastSeen = await readLastSeen();
+    if (!anchor)
+        return lastSeen ?? Date.now();
+    let elapsed = monoNow() - anchor.monoBase;
+    // After a process restart performance.now() resets: elapsed goes negative.
+    // Clamp to zero so time never runs backwards; lastSeen still bounds it.
+    if (!Number.isFinite(elapsed) || elapsed < 0)
+        elapsed = 0;
+    const candidate = anchor.serverMs + elapsed;
+    const now = Math.max(candidate, lastSeen ?? -Infinity, anchor.serverMs);
+    return now;
+}
+/** True once at least one trusted server_time has been anchored. */
+export async function isAnchored() {
+    return (await readAnchor()) != null;
+}
+/** Last trusted anchor instant (ms), or null when never synced. */
+export async function getLastAnchorMs() {
+    const anchor = await readAnchor();
+    return anchor?.serverMs ?? null;
+}
+/** Test seam: clear persisted clock state. */
+export async function resetEntitlementClock() {
+    const { kvRemoveItem } = await import("../adapters/kv");
+    await kvRemoveItem(ANCHOR_KEY);
+    await kvRemoveItem(LAST_SEEN_KEY);
+}