@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/lib/admin/orderClient.ts

@@ -0,0 +1,146 @@
+/**
+ * Server-side client for tot-foxycart's order READ API (card 8585 / U2).
+ *
+ * Calls `GET /commerce/orders[/:orderId]` with the tenant's per-tenant bearer key
+ * (the ToT `partnerApi.apiKey`, held as a Worker secret — NEVER shipped to the
+ * browser). Returns the frozen DTO shapes from `@tot/public-runtime`. Read-only
+ * (scope-locks); no write paths.
+ *
+ * The fetch runs on the Cloudflare Worker (server), so the call is same-origin →
+ * cross-service server-to-server; it is NOT browser-originated and therefore not
+ * CSP-governed — the U2 CSP connect-src entry is intentionally skipped (board
+ * decision `u2-csp-server-side-fetch`).
+ *
+ * `fetchImpl` is injectable so the client is unit-testable offline.
+ */
+import type {
+  FoxyOrderDetail,
+  FoxyOrderDetailResponse,
+  FoxyOrderListFilters,
+  FoxyOrderListResponse,
+} from "@tot/public-runtime";
+import type { CustomizationEnv } from "@tot/public-runtime";
+
+/** Fetch shape we depend on — the platform `fetch`, injectable for tests. */
+export type FetchLike = (
+  input: string,
+  init?: { method?: string; headers?: Record<string, string> },
+) => Promise<{ ok: boolean; status: number; text: () => Promise<string> }>;
+
+/** Stable error codes surfaced by the order API (see contract §9). */
+export type OrderApiErrorCode =
+  | "missing_app_domain"
+  | "missing_bearer"
+  | "unknown_tenant"
+  | "not_provisioned"
+  | "invalid_partner_key"
+  | "order_not_found"
+  | "bad_gateway"
+  | "unexpected";
+
+/** A typed failure from the order API — carries an HTTP status + a stable code. */
+export class OrderApiError extends Error {
+  constructor(
+    readonly code: OrderApiErrorCode,
+    readonly status: number,
+    message?: string,
+  ) {
+    super(message ?? code);
+    this.name = "OrderApiError";
+  }
+}
+
+export interface FoxyOrderClient {
+  listOrders(filters?: FoxyOrderListFilters): Promise<FoxyOrderListResponse>;
+  getOrder(orderId: string): Promise<FoxyOrderDetail>;
+}
+
+export interface FoxyOrderClientConfig {
+  /** tot-foxycart proxy base, e.g. `https://foxycart-test.tokenoftrust.com`. */
+  baseUrl: string;
+  /** The tenant, sent as `?appDomain=` (e.g. `sample-store.example`). */
+  appDomain: string;
+  /** The tenant's `partnerApi.apiKey` — the `Authorization: Bearer` token. */
+  bearer: string;
+  fetchImpl?: FetchLike;
+}
+
+/**
+ * Resolve the tot-foxycart proxy base URL for an environment (contract §2).
+ * qa runs `NODE_ENV=test` → the `foxycart-test` proxy; `live` → prod. Kept
+ * private so it does not collide with U11b's exported `foxyProxyBaseUrl` before
+ * the units fold; the integrator can dedup into one shared export.
+ */
+export function orderApiBaseUrl(env: CustomizationEnv): string {
+  return env === "live"
+    ? "https://foxycart.tokenoftrust.com"
+    : "https://foxycart-test.tokenoftrust.com";
+}
+
+/** Map an HTTP status + endpoint body to a stable OrderApiError code. */
+function toError(status: number, body: string): OrderApiError {
+  const detail = body.slice(0, 300);
+  if (status === 400) return new OrderApiError("missing_app_domain", 400, detail);
+  if (status === 401) {
+    // The endpoint distinguishes these in the body; pass it through for logging.
+    const code: OrderApiErrorCode = /not_provisioned/.test(body)
+      ? "not_provisioned"
+      : /unknown_tenant/.test(body)
+        ? "unknown_tenant"
+        : /missing_bearer/.test(body)
+          ? "missing_bearer"
+          : "invalid_partner_key";
+    return new OrderApiError(code, 401, detail);
+  }
+  if (status === 404) return new OrderApiError("order_not_found", 404, detail);
+  if (status >= 500) return new OrderApiError("bad_gateway", 502, detail);
+  return new OrderApiError("unexpected", status, detail);
+}
+
+/** Build the list querystring: appDomain (required) + any provided filters. */
+function listQuery(appDomain: string, filters?: FoxyOrderListFilters): string {
+  const p = new URLSearchParams({ appDomain });
+  if (filters) {
+    if (filters.queue) p.set("queue", filters.queue);
+    if (filters.status) p.set("status", filters.status);
+    if (filters.from) p.set("from", filters.from);
+    if (filters.to) p.set("to", filters.to);
+    if (filters.limit != null) p.set("limit", String(filters.limit));
+    if (filters.cursor) p.set("cursor", filters.cursor);
+  }
+  return p.toString();
+}
+
+/** Create a per-request order client bound to one tenant + env. */
+export function createFoxyOrderClient(
+  config: FoxyOrderClientConfig,
+): FoxyOrderClient {
+  const doFetch = config.fetchImpl ?? (globalThis.fetch as unknown as FetchLike);
+  const base = config.baseUrl.replace(/\/+$/, "");
+  const headers = { authorization: `Bearer ${config.bearer}` };
+
+  async function getJson<T>(url: string): Promise<T> {
+    const res = await doFetch(url, { method: "GET", headers });
+    const body = await res.text();
+    if (!res.ok) throw toError(res.status, body);
+    try {
+      return JSON.parse(body) as T;
+    } catch {
+      throw new OrderApiError("unexpected", res.status, "malformed JSON");
+    }
+  }
+
+  return {
+    async listOrders(filters) {
+      const qs = listQuery(config.appDomain, filters);
+      return getJson<FoxyOrderListResponse>(`${base}/commerce/orders?${qs}`);
+    },
+    async getOrder(orderId) {
+      const qs = new URLSearchParams({ appDomain: config.appDomain }).toString();
+      const { order } = await getJson<FoxyOrderDetailResponse>(
+        `${base}/commerce/orders/${encodeURIComponent(orderId)}?${qs}`,
+      );
+      return order;
+    },
+  };
+}

package/apps/storefront/src/lib/admin/seed.ts

@@ -0,0 +1,54 @@
+/**
+ * Deterministic seeding for mock admin data. All mock services derive their
+ * randomness from `seededRandom(key)`, where `key` includes `targetTenant` — so
+ * the same tenant always produces the same rows/values (data-view-contracts
+ * acceptance: "same tenant ⇒ same data"), with no reliance on wall-clock time.
+ */
+
+function hashString(input: string): number {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i += 1) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+/** mulberry32 PRNG — small, fast, deterministic for a given integer seed. */
+function mulberry32(seed: number): () => number {
+  let state = seed | 0;
+  return () => {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** A `() => number` in `[0, 1)` that is stable for a given string key. */
+export function seededRandom(key: string): () => number {
+  return mulberry32(hashString(key));
+}
+
+export function pick<T>(rng: () => number, items: readonly T[]): T {
+  const value = items[Math.floor(rng() * items.length) % items.length];
+  if (value === undefined) throw new Error("pick() called with an empty list");
+  return value;
+}
+
+export function randomInt(rng: () => number, min: number, max: number): number {
+  return min + Math.floor(rng() * (max - min + 1));
+}
+
+export function randomBool(rng: () => number, probabilityTrue = 0.5): boolean {
+  return rng() < probabilityTrue;
+}
+
+/** Deterministic ISO timestamp: a fixed anchor plus a seed-derived offset. */
+export function offsetIso(anchorIso: string, offsetMinutes: number): string {
+  const anchor = new Date(anchorIso).getTime();
+  return new Date(anchor + offsetMinutes * 60_000).toISOString();
+}
+
+/** Anchor instant every mock service builds relative timestamps from — never `Date.now()`. */
+export const MOCK_ANCHOR_ISO = "2026-07-14T16:00:00.000Z";

package/apps/storefront/src/lib/admin/services/mock/aiWorkflows.ts

@@ -0,0 +1,59 @@
+import type { AdminTenantEnvelope } from "../../envelope";
+import { memoizeByEnvelope } from "../../memoizeByEnvelope";
+import { MOCK_ANCHOR_ISO, offsetIso, pick, randomInt, seededRandom } from "../../seed";
+import { AI_WORKFLOW_NAMES, OPERATIONAL_WORKFLOW_KEYS, type AiWorkflowsViewModel, type ApprovalMode, type WorkflowRecord, type WorkflowStatus } from "../../viewmodels/aiWorkflows";
+
+const OWNERS = ["Ops", "Trust & Safety", "Growth", "Fulfillment"];
+const APPROVAL_MODES: ApprovalMode[] = ["draft_only", "approval_required", "guarded_automation"];
+// Operational workflows are human-acted recommendation flows, never auto-actions,
+// so they can never be assigned guarded_automation (invariant in ai/approvalMode.ts,
+// ai/operationalRuns.ts, and OrdersWorkspace.astro).
+const OPERATIONAL_APPROVAL_MODES: ApprovalMode[] = ["draft_only", "approval_required"];
+const STATUSES: WorkflowStatus[] = ["scheduled", "needs_review", "planned"];
+const SYSTEM_OPERATOR = "system:ai-workflows";
+
+function slugify(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+
+function computeAiWorkflowsViewModel(envelope: AdminTenantEnvelope): AiWorkflowsViewModel {
+  const { targetTenant } = envelope;
+  const rng = seededRandom(`ai-workflows:${targetTenant}`);
+
+  const workflows: WorkflowRecord[] = AI_WORKFLOW_NAMES.map((name) => {
+    const key = slugify(name);
+    const lastRunAt = offsetIso(MOCK_ANCHOR_ISO, -randomInt(rng, 60, 4000));
+    const owner = pick(rng, OWNERS);
+    const isOperational = (OPERATIONAL_WORKFLOW_KEYS as readonly string[]).includes(key);
+    const approvalMode = pick(rng, isOperational ? OPERATIONAL_APPROVAL_MODES : APPROVAL_MODES);
+    const evidenceLinks = [`evidence:${targetTenant}:workflow:${key}-latest`];
+    const scaffoldedEvent = { operator: SYSTEM_OPERATOR, targetTenant, action: "workflow.scaffolded", at: lastRunAt };
+
+    return {
+      key,
+      name,
+      cadence: pick(rng, ["Hourly", "Daily", "Weekly"]),
+      triggerType: pick(rng, ["Scheduled", "Event: new order", "Event: catalog change"]),
+      owner,
+      status: pick(rng, STATUSES),
+      approvalMode,
+      lastRunAt,
+      nextRunAt: offsetIso(lastRunAt, randomInt(rng, 60, 1440)),
+      sourceData: ["orders", "products"].slice(0, randomInt(rng, 1, 2)),
+      evidenceLinks,
+      suggestedAction: {
+        summary: `Review ${name.toLowerCase()} findings for ${targetTenant}.`,
+        confidence: Math.round((0.55 + rng() * 0.4) * 100) / 100,
+        evidenceRefs: evidenceLinks,
+        owner,
+        approvalMode,
+        auditTrail: [scaffoldedEvent],
+      },
+      auditTrail: [scaffoldedEvent],
+    };
+  });
+
+  return { targetTenant, workflows };
+}
+
+export const getAiWorkflowsViewModel = memoizeByEnvelope(computeAiWorkflowsViewModel);

package/apps/storefront/src/lib/admin/services/mock/customers.ts

@@ -0,0 +1,86 @@
+import type { AdminTenantEnvelope } from "../../envelope";
+import { memoizeByEnvelope } from "../../memoizeByEnvelope";
+import { MOCK_ANCHOR_ISO, offsetIso, pick, randomBool, randomInt, seededRandom } from "../../seed";
+import type {
+  BlockedReason,
+  CustomerBlockedQueueRow,
+  CustomerDetail,
+  CustomerRow,
+  CustomersViewModel,
+  VerificationState,
+} from "../../viewmodels/customers";
+
+// Must stay index-aligned with orders.ts's CUSTOMER_NAMES: a customer's id is
+// `cust-<tenant>-<position here>`, and orders.ts derives each order's customerId
+// from the same position, so the evidence graph can join order→customer by id.
+const NAMES = [
+  "Riley Harper",
+  "Jordan Lee",
+  "Casey Nguyen",
+  "Morgan Blake",
+  "Sam Ortiz",
+  "Avery Chen",
+  "Quinn Sullivan",
+  "Reese Patel",
+];
+
+const BLOCKED_REASONS: { blocker: BlockedReason; detail: string; action: string }[] = [
+  { blocker: "verification", detail: "Age/identity verification is pending re-check.", action: "Resend verification" },
+  { blocker: "destination", detail: "Destination state restricts this product category.", action: "Review destination policy" },
+  { blocker: "address", detail: "Shipping address failed carrier validation.", action: "Confirm address" },
+  { blocker: "support", detail: "Open support ticket is blocking fulfillment.", action: "Resolve ticket" },
+];
+
+function computeCustomersViewModel(envelope: AdminTenantEnvelope): CustomersViewModel {
+  const { targetTenant } = envelope;
+  const rng = seededRandom(`customers:${targetTenant}`);
+
+  const directory: CustomerRow[] = NAMES.map((name, index) => {
+    const orderCount = randomInt(rng, 1, 12);
+    const verificationState: VerificationState = index === 0 ? "pending" : randomBool(rng, 0.85) ? "verified" : "blocked";
+    return {
+      id: `cust-${targetTenant}-${index}`,
+      name,
+      email: `${name.toLowerCase().replace(/\s+/g, ".")}@example.com`,
+      orderCount,
+      lifetimeValue: orderCount * randomInt(rng, 45, 220),
+      lastOrderAt: offsetIso(MOCK_ANCHOR_ISO, -randomInt(rng, 60, 90_000)),
+      segment: orderCount > 6 ? "vip" : orderCount > 1 ? "returning" : "new",
+      supportFlags: randomBool(rng, 0.2) ? ["Open ticket"] : [],
+      verificationState,
+    };
+  });
+
+  const detailsById: Record<string, CustomerDetail> = {};
+  for (const row of directory) {
+    detailsById[row.id] = {
+      ...row,
+      orders: Array.from({ length: Math.min(row.orderCount, 4) }, (_, i) => ({
+        orderId: `#${2_200_000_000 + Math.floor(rng() * 90_000_000)}`,
+        placedAt: offsetIso(MOCK_ANCHOR_ISO, -randomInt(rng, 60, 90_000) - i * 1440),
+        total: randomInt(rng, 45, 380),
+      })),
+      activity: [{ title: "Account created", detail: "Customer record created from first checkout.", at: row.lastOrderAt ?? MOCK_ANCHOR_ISO }],
+      notes: [],
+    };
+  }
+
+  const valuableButBlocked: CustomerBlockedQueueRow[] = directory
+    .filter((row) => row.verificationState === "blocked" || row.verificationState === "pending")
+    .map((row) => {
+      const reason = pick(rng, BLOCKED_REASONS);
+      return {
+        customerId: row.id,
+        name: row.name,
+        recoverableValue: row.lifetimeValue,
+        blocker: reason.blocker,
+        blockerDetail: reason.detail,
+        action: reason.action,
+      };
+    })
+    .sort((a, b) => b.recoverableValue - a.recoverableValue);
+
+  return { targetTenant, directory, detailsById, valuableButBlocked };
+}
+
+export const getCustomersViewModel = memoizeByEnvelope(computeCustomersViewModel);

package/apps/storefront/src/lib/admin/services/mock/evidence.ts

@@ -0,0 +1,99 @@
+import type { AdminTenantEnvelope } from "../../envelope";
+import { memoizeByEnvelope } from "../../memoizeByEnvelope";
+import type { EvidenceReference } from "../../evidence/evidenceReference";
+import { getCustomersViewModel } from "./customers";
+import { getOrdersViewModel } from "./orders";
+import { getProductsViewModel } from "./products";
+
+/**
+ * Deterministic evidence graph, built by connecting the domains already
+ * shipped in data-view-contracts: each order's evidence ref links to its
+ * customer and to the product(s) mentioned in its line items — the "graph"
+ * edges the baseline's Evidence Graph section asks for, without inventing a
+ * fifth mock dataset to disagree with the other four.
+ *
+ * Order→customer and order→product edges join on the shared ids
+ * (`OrderRow.customerId` / `OrderRow.productId`), which orders.ts derives from
+ * the same name-pool positions customers.ts/products.ts use for their ids — a
+ * stable id join, not a fragile display-name string match.
+ */
+function computeEvidenceViewModel(envelope: AdminTenantEnvelope): EvidenceReference[] {
+  const { targetTenant } = envelope;
+  const orders = getOrdersViewModel(envelope);
+  const customers = getCustomersViewModel(envelope);
+  const products = getProductsViewModel(envelope);
+
+  const customerIds = new Set(customers.directory.map((c) => c.id));
+  const productIds = new Set(products.rows.map((p) => p.id));
+
+  const orderRef = (orderId: string) => `evidence:${targetTenant}:order:${orderId}`;
+  const customerRef = (customerId: string) => `evidence:${targetTenant}:customer:${customerId}`;
+  const productRef = (productId: string) => `evidence:${targetTenant}:product:${productId}`;
+
+  const refs: EvidenceReference[] = [];
+
+  for (const row of orders.rows) {
+    const detail = orders.detailsById[row.id];
+    const related: string[] = [];
+    if (customerIds.has(row.customerId)) related.push(customerRef(row.customerId));
+    if (productIds.has(row.productId)) related.push(productRef(row.productId));
+
+    refs.push({
+      id: orderRef(row.id),
+      kind: "order",
+      recordId: row.id,
+      label: `Order ${row.id}`,
+      at: row.placedAt,
+      relatedRefs: related,
+    });
+
+    if (detail?.evidenceTimeline.length) {
+      refs.push({
+        id: `evidence:${targetTenant}:verification:${row.id}`,
+        kind: row.blocker === "Age verification hold" ? "verification_event" : "policy_acceptance",
+        recordId: row.id,
+        label: `Checkout assurance for ${row.id}`,
+        at: row.placedAt,
+        relatedRefs: [orderRef(row.id)],
+      });
+    }
+  }
+
+  for (const customer of customers.directory) {
+    refs.push({
+      id: customerRef(customer.id),
+      kind: "customer",
+      recordId: customer.id,
+      label: customer.name,
+      at: customer.lastOrderAt ?? new Date(0).toISOString(),
+      relatedRefs: [],
+    });
+  }
+
+  for (const product of products.rows) {
+    const detail = products.detailsById[product.id];
+    const at = detail?.activity[0]?.at ?? new Date(0).toISOString();
+    refs.push({
+      id: productRef(product.id),
+      kind: "product",
+      recordId: product.id,
+      label: product.name,
+      at,
+      relatedRefs: [],
+    });
+    if (product.missingExciseCount > 0) {
+      refs.push({
+        id: `evidence:${targetTenant}:tax_excise:${product.id}`,
+        kind: "tax_excise",
+        recordId: product.id,
+        label: `Excise metadata gaps — ${product.name}`,
+        at,
+        relatedRefs: [productRef(product.id)],
+      });
+    }
+  }
+
+  return refs;
+}
+
+export const getEvidenceViewModel = memoizeByEnvelope(computeEvidenceViewModel);

package/apps/storefront/src/lib/admin/services/mock/foxyCartSettings.ts

@@ -0,0 +1,78 @@
+/**
+ * Mock service for the admin "Cart & Checkout appearance" section. Resolves the
+ * TARGET tenant's theme (the style-guide) and any saved overrides into the flat
+ * field list the panel renders — so each row shows its theme default, current
+ * value, provenance (theme vs override), and a reset affordance.
+ *
+ * The target tenant's config is INJECTED by the panel boundary (resolved through
+ * the `TenantResolver` seam via `config/adminTargetTenant`), never looked up from
+ * the static tenant map here: `lib/**` stays behind the `tenancy-resolver-fence`
+ * so a single-tenant extraction stays a drop-in. A null tenant (or one with no
+ * FoxyCart store) renders the panel's inert "no store" state.
+ *
+ * Overrides are read from a mock store here (no live persistence yet — the save
+ * hop is the tot-foxycart `/theme/foxy` PUT/refresh + Foxy color PATCH seam). One
+ * example override is seeded so the panel demonstrates the theme/override/reset
+ * states without a backend.
+ */
+import { resolveFoxyCommerce } from "@tot/public-runtime";
+import type { TenantConfig } from "@tot/public-runtime";
+import { referenceTheme } from "@/themes/reference";
+import { mergeTheme } from "@/themes/schema";
+import type { AdminTenantEnvelope } from "../../envelope";
+import {
+  buildFoxySettingsFields,
+  deriveFoxyCartSettings,
+  type FoxyCartSettingsOverrides,
+  type FoxySettingsField,
+} from "@/lib/commerce/foxyCartSettings";
+
+export interface FoxyCartSettingsViewModel {
+  targetTenant: string;
+  /** True when the tenant has a FoxyCart store (else the section is inert). */
+  hasStore: boolean;
+  fields: FoxySettingsField[];
+  overrideCount: number;
+}
+
+/**
+ * Mock override store. Keyed by tenant id. Seeded with one override for the
+ * generic sample tenant so the panel shows a mixed theme/override state out of
+ * the box. Real overrides would come from the tenant's saved cart settings.
+ */
+const MOCK_OVERRIDES: Record<string, FoxyCartSettingsOverrides> = {
+  "sample-store.example": {
+    // Example: the merchant pinned a custom tertiary accent, overriding the
+    // theme's --color-sale default — the panel renders this row as "Overridden"
+    // with a Reset control.
+    colors: { tertiary: "#e11d48" },
+  },
+};
+
+/**
+ * Build the FoxyCart cart-appearance view model from the resolved TARGET tenant
+ * config. `tenant` is the target's resolved `TenantConfig` (or null when no
+ * tenant claims the id) — resolved by the caller through the resolver seam.
+ */
+export function getFoxyCartSettingsViewModel(
+  envelope: AdminTenantEnvelope,
+  tenant: TenantConfig | null,
+): FoxyCartSettingsViewModel {
+  const { targetTenant } = envelope;
+  const foxy = tenant?.commerce?.foxy ?? null;
+
+  if (!tenant || !foxy) {
+    return { targetTenant, hasStore: false, fields: [], overrideCount: 0 };
+  }
+
+  const theme = mergeTheme(referenceTheme, tenant.theme_tokens);
+  const commerce = resolveFoxyCommerce(foxy);
+  const defaults = deriveFoxyCartSettings(theme, commerce, {
+    originBase: `https://${targetTenant}`,
+  });
+  const overrides = MOCK_OVERRIDES[targetTenant] ?? {};
+  const fields = buildFoxySettingsFields(defaults, overrides);
+  const overrideCount = fields.filter((f) => f.source === "override").length;
+
+  return { targetTenant, hasStore: true, fields, overrideCount };
+}

package/apps/storefront/src/lib/admin/services/mock/fulfillment.ts

@@ -0,0 +1,62 @@
+import type { AdminTenantEnvelope } from "../../envelope";
+import { memoizeByEnvelope } from "../../memoizeByEnvelope";
+import { pick, randomBool, randomInt, seededRandom } from "../../seed";
+import type {
+  FulfillmentAssistDraft,
+  FulfillmentQueueKey,
+  FulfillmentQueueSummary,
+  FulfillmentViewModel,
+  ShipmentRow,
+} from "../../viewmodels/fulfillment";
+
+const QUEUE_DEFS: { key: FulfillmentQueueKey; label: string }[] = [
+  { key: "ready_to_ship", label: "Ready to Ship" },
+  { key: "holds", label: "Holds" },
+  { key: "picked", label: "Picked" },
+  { key: "packed", label: "Packed" },
+  { key: "label_needed", label: "Label needed" },
+  { key: "shipped", label: "Shipped" },
+  { key: "exceptions", label: "Exceptions" },
+];
+
+const CARRIERS = ["USPS", "UPS", "FedEx"];
+const DESTINATIONS = ["Minneapolis, MN", "Portland, OR", "Austin, TX", "Columbus, OH", "Denver, CO"];
+
+function computeFulfillmentViewModel(envelope: AdminTenantEnvelope): FulfillmentViewModel {
+  const { targetTenant } = envelope;
+  const rng = seededRandom(`fulfillment:${targetTenant}`);
+
+  const shipments: ShipmentRow[] = QUEUE_DEFS.flatMap((def) =>
+    Array.from({ length: randomInt(rng, 1, 3) }, () => {
+      const labelLocked = def.key === "label_needed" || (def.key === "holds" && randomBool(rng, 0.6));
+      return {
+        orderId: `#${2_200_000_000 + Math.floor(rng() * 90_000_000)}`,
+        queue: def.key,
+        carrier: pick(rng, CARRIERS),
+        destination: pick(rng, DESTINATIONS),
+        slaAgeHours: randomInt(rng, 1, 48),
+        labelLocked,
+        labelLockReason: labelLocked ? pick(rng, ["Shipping restriction on destination", "Payment not yet captured", "Age verification pending"]) : null,
+        carrierReady: !labelLocked && randomBool(rng, 0.9),
+        destinationReady: randomBool(rng, 0.85),
+      };
+    }),
+  );
+
+  const queues: FulfillmentQueueSummary[] = QUEUE_DEFS.map((def) => ({
+    key: def.key,
+    label: def.label,
+    count: shipments.filter((s) => s.queue === def.key).length,
+  }));
+
+  const exceptionShipments = shipments.filter((s) => s.queue === "exceptions" || s.labelLocked);
+  const assistDrafts: FulfillmentAssistDraft[] = exceptionShipments.map((s) => ({
+    orderId: s.orderId,
+    kind: "blocker_explanation",
+    summary: s.labelLockReason ? `${s.labelLockReason} — resolve to unlock the label for ${s.orderId}.` : `Exception queue: ${s.orderId} needs manual review.`,
+  }));
+
+  return { targetTenant, queues, shipments, assistDrafts };
+}
+
+export const getFulfillmentViewModel = memoizeByEnvelope(computeFulfillmentViewModel);

package/apps/storefront/src/lib/admin/services/mock/index.ts

@@ -0,0 +1,12 @@
+export { getOrdersViewModel } from "./orders";
+export { getProductsViewModel } from "./products";
+export { getCustomersViewModel } from "./customers";
+export { getFulfillmentViewModel } from "./fulfillment";
+export { getReportingViewModel } from "./reporting";
+export { getSettingsViewModel } from "./settings";
+export { getFoxyCartSettingsViewModel } from "./foxyCartSettings";
+export type { FoxyCartSettingsViewModel } from "./foxyCartSettings";
+export { getAiWorkflowsViewModel } from "./aiWorkflows";
+export { getEvidenceViewModel } from "./evidence";
+export { SEEDED_TENANTS, tenantProfile } from "./tenants";
+export type { SeededTenantProfile, MockVertical } from "./tenants";