@tokenoftrust/storefront-runner 2.4.50 → 2.4.52

package/apps/storefront/src/lib/admin/services/orders.ts

@@ -1,49 +1,163 @@
 /**
- * REAL orders view model — the Orders tab's data source. Fetches the tenant's
- * checkout orders via the order client and maps the frozen DTO
- * (`@tot/public-runtime` checkout-orders) into the `OrdersViewModel` shape that
- * `OrdersWorkspace.astro` renders. Read-only (scope-locks) — no write paths.
- *
- * The mapping is a pure function (`mapOrdersToViewModel`) for testability; the
- * orchestration (`getOrdersViewModel`) lists orders, eagerly fetches each order's
- * detail (OrdersWorkspace renders `detailsById[row.id]` for every row), and maps.
- * On ANY upstream failure it returns a valid EMPTY view model so the tab renders.
- * The live "real qa data" path is gated on ToT-core exposing
- * `GET /api/exciseTax/orders`; until that exists this yields the empty model on qa.
- *
- * Identity/age fields (riskLevel, readiness "identity_and_age", evidence) are
- * derived provisionally from commerce facts here; the tot20 verification join
- * fills them authoritatively via the DTO's null `verification` /
- * `verificationDetail` slots.
+ * Orders view model. Maps checkout order DTOs into `OrdersViewModel`.
+ * Null `verification` is UNKNOWN and held — not a pass, not collected tax,
+ * and not low risk. Payment, tax, verification, risk, stock, and fulfillment
+ * stay independent. Read-only.
  */
 import type {
   CheckoutOrderDetail,
+  CheckoutOrderFulfillment,
   CheckoutOrderListFilters,
   CheckoutOrderPage,
+  CheckoutOrderPayment,
   CheckoutOrderSummary,
   CheckoutOrderVerification,
+  CommerceActor,
+  CommerceEvidence,
+  CommerceScope,
+  CommerceStage,
+  ComplianceState,
+  EvidenceState,
+  FulfillmentState,
+  LabelState,
+  MinorTotals,
+  PaymentState,
+  ProviderOutcome,
+  PublicCommerceEvent,
+  StockState,
+} from "@tot/public-runtime";
+import {
+  actorMayCommand,
+  decideCommerceCommand,
+  evidencePermitsRelease,
+  paginateOrders,
+  paymentIsCaptured,
+  publicCommerceEvent,
+  readOwnerAddress,
+  sumMinor,
+  totalsMatch,
 } from "@tot/public-runtime";
 import type {
+  OrderAccounting,
   OrderDetail,
   OrderEvidenceEvent,
+  OrderMoneyScope,
   OrderQueueSummary,
   OrderReadinessCheck,
+  OrderReadinessColumn,
+  OrderRelease,
   OrderRow,
   OrderShipState,
   OrdersViewModel,
 } from "../viewmodels/orders";
 import type { CheckoutOrderClient } from "../orderClient";
 
-/** Next-step label, mirroring the mock's queue semantics. */
-function deriveNextStep(fulfillment: OrderShipState, blocker: string | null): string {
-  if (fulfillment === "hold_review_required") {
-    return blocker === "Payment capture" ? "Capture payment" : "Review risk";
-  }
-  if (fulfillment === "completed") return "View record";
-  return "Create label";
+const EVIDENCE_STATES: readonly EvidenceState[] = ["fresh", "UNKNOWN", "stale", "unreadable", "absent"];
+const REFUND_PAYMENTS: ReadonlySet<PaymentState> = new Set(["refunded", "refund_requested", "refund_unknown"]);
+
+export interface SourcedState<T extends string = string> {
+  state: T;
+  source: string;
+  asOf: string | null;
+}
+
+export type AuthorityState = "fresh" | "expired" | "unreadable" | "absent";
+
+/** One commerce order. Columns do not borrow each other's state, source, or as-of. */
+export interface ScrappyOrderRecord {
+  id: string;
+  placedAt: string;
+  tenantId: string;
+  stage: CommerceStage;
+  currency: string;
+  payment: SourcedState<PaymentState>;
+  tax: SourcedState<EvidenceState>;
+  verification: SourcedState<EvidenceState>;
+  risk: SourcedState<EvidenceState>;
+  stock: SourcedState<StockState>;
+  stockEvidence: SourcedState<EvidenceState>;
+  fulfillment: SourcedState<FulfillmentState>;
+  label: LabelState;
+  compliance: ComplianceState;
+  providerOutcome: ProviderOutcome | null;
+  authority: SourcedState<AuthorityState> | null;
+  totals: MinorTotals;
+  customerId?: string | null;
+  address?: unknown;
 }
 
-/** Provisional risk until the verification join fills `verification`. Prefer a real riskLevel when present. */
+export interface ScrappyOrderFilter {
+  payment?: PaymentState;
+  fulfillment?: FulfillmentState;
+  from?: string;
+  to?: string;
+  queue?: "needs_attention" | "ready_to_ship" | "unfulfilled" | "all" | "completed";
+}
+
+export interface ScrappyOrderQuery {
+  actor: CommerceActor;
+  resource: CommerceScope;
+  orders: readonly ScrappyOrderRecord[];
+  filter?: ScrappyOrderFilter;
+  limit: number;
+  cursor: string | null;
+}
+
+export interface ScrappyOrderView {
+  id: string;
+  placedAt: string;
+  tenantId: string;
+  stage: CommerceStage;
+  currency: string;
+  payment: SourcedState<PaymentState>;
+  tax: SourcedState<EvidenceState>;
+  verification: SourcedState<EvidenceState>;
+  risk: SourcedState<EvidenceState>;
+  stock: SourcedState<StockState>;
+  stockEvidence: SourcedState<EvidenceState>;
+  fulfillment: SourcedState<FulfillmentState>;
+  label: LabelState;
+  compliance: ComplianceState;
+  providerOutcome: ProviderOutcome | null;
+  authority: SourcedState<AuthorityState> | null;
+  totals: MinorTotals;
+  columns: OrderReadinessColumn[];
+  evidence: CommerceEvidence;
+  release: OrderRelease;
+  address?: unknown;
+}
+
+export type ScrappyOrderQueryResult =
+  | {
+      ok: true;
+      orders: ScrappyOrderView[];
+      nextCursor: string | null;
+      invalidCursor: boolean;
+      accounting: OrderAccounting;
+    }
+  | { ok: false; reason: "denied" };
+
+export interface CheckoutReadiness {
+  columns: OrderReadinessColumn[];
+  evidence: CommerceEvidence;
+  release: OrderRelease;
+  riskLevel: OrderRow["riskLevel"];
+}
+
+function evidenceOf(order: ScrappyOrderRecord): CommerceEvidence {
+  return {
+    verification: order.verification.state,
+    tax: order.tax.state,
+    risk: order.risk.state,
+    stock: order.stockEvidence.state,
+  };
+}
+
+function isEvidenceState(value: unknown): value is EvidenceState {
+  return typeof value === "string" && (EVIDENCE_STATES as readonly string[]).includes(value);
+}
+
+/** Display risk. Absent verification is unknown, never a synthetic low. */
 function deriveRisk(
   verification: CheckoutOrderVerification | null,
   blocker: string | null,
@@ -51,85 +165,287 @@ function deriveRisk(
   const r = verification?.riskLevel;
   if (r === "low" || r === "medium" || r === "high") return r;
   if (blocker === "Age verification hold") return "high";
-  return blocker ? "medium" : "low";
+  if (blocker) return "medium";
+  return "unknown";
+}
+
+function deriveNextStep(fulfillment: OrderShipState, blocker: string | null): string {
+  if (fulfillment === "hold_review_required") {
+    return blocker === "Payment capture" ? "Capture payment" : "Review risk";
+  }
+  if (fulfillment === "completed") return "View record";
+  return "Create label";
+}
+
+function fulfillmentFromCheckout(fulfillment: CheckoutOrderFulfillment): FulfillmentState {
+  switch (fulfillment) {
+    case "ready_to_ship":
+      return "ready";
+    case "hold_review_required":
+      return "held";
+    case "completed":
+      return "handed_off";
+    case "unfulfilled":
+      return "UNKNOWN";
+    default: {
+      const unreachable: never = fulfillment;
+      return unreachable;
+    }
+  }
+}
+
+function readSourcedEvidence(
+  verification: CheckoutOrderVerification | null,
+  key: "verification" | "tax" | "risk" | "stock",
+): SourcedState<EvidenceState> {
+  if (verification == null) return { state: "UNKNOWN", source: "absent", asOf: null };
+  const state = isEvidenceState(verification[key]) ? verification[key] : "UNKNOWN";
+  const sourceValue = verification[`${key}Source`];
+  const asOfValue = verification[`${key}AsOf`];
+  return {
+    state,
+    source: typeof sourceValue === "string" && sourceValue.length > 0 ? sourceValue : "checkout-order",
+    asOf: typeof asOfValue === "string" ? asOfValue : null,
+  };
+}
+
+export function readinessColumns(order: ScrappyOrderRecord): OrderReadinessColumn[] {
+  return [
+    { key: "payment", state: order.payment.state, source: order.payment.source, asOf: order.payment.asOf },
+    { key: "tax", state: order.tax.state, source: order.tax.source, asOf: order.tax.asOf },
+    { key: "verification", state: order.verification.state, source: order.verification.source, asOf: order.verification.asOf },
+    { key: "risk", state: order.risk.state, source: order.risk.source, asOf: order.risk.asOf },
+    { key: "stock", state: order.stock.state, source: order.stock.source, asOf: order.stock.asOf },
+    { key: "fulfillment", state: order.fulfillment.state, source: order.fulfillment.source, asOf: order.fulfillment.asOf },
+  ];
+}
+
+/** Release blocks are explicit. Capture does not clear a null or stale column. */
+export function releaseOf(order: ScrappyOrderRecord): OrderRelease {
+  const blocks: string[] = [];
+  const evidence = evidenceOf(order);
+  if (REFUND_PAYMENTS.has(order.payment.state)) blocks.push("refund");
+  if (order.fulfillment.state === "cancelled") blocks.push("cancel");
+  if (order.stock.state === "expired" || order.authority?.state === "expired") blocks.push("expired");
+  if (order.authority?.state === "unreadable") blocks.push("unreadable-authority");
+  if (
+    order.verification.state === "unreadable" ||
+    order.tax.state === "unreadable" ||
+    order.risk.state === "unreadable" ||
+    order.stockEvidence.state === "unreadable"
+  ) {
+    blocks.push("unreadable");
+  }
+  if (!paymentIsCaptured(order.payment.state)) blocks.push("payment");
+  if (!evidencePermitsRelease(evidence)) blocks.push("evidence");
+  if (order.stock.state !== "confirmed" && !blocks.includes("stock")) blocks.push("stock");
+  if (order.fulfillment.state !== "ready" && !blocks.includes("fulfillment")) blocks.push("fulfillment");
+
+  const decision = decideCommerceCommand({
+    command: "hand-off",
+    payment: order.payment.state,
+    stock: order.stock.state,
+    fulfillment: order.fulfillment.state,
+    label: order.label,
+    evidence,
+    providerOutcome: order.providerOutcome,
+  });
+  if (!decision.admit) {
+    if (decision.reason === "payment" && !blocks.includes("payment") && !blocks.includes("refund")) blocks.push("payment");
+    if (decision.reason === "stock" && !blocks.includes("stock") && !blocks.includes("expired")) blocks.push("stock");
+    if (decision.reason === "fulfillment" && !blocks.includes("fulfillment") && !blocks.includes("cancel")) {
+      blocks.push("fulfillment");
+    }
+    if (decision.reason === "evidence" && !blocks.includes("evidence")) blocks.push("evidence");
+    if (decision.reason === "label") blocks.push("label");
+    if (decision.reason === "reconcile") blocks.push("reconcile");
+    if (decision.reason === "reuse") blocks.push("reuse");
+  }
+
+  const ready = blocks.length === 0 && decision.admit && paymentIsCaptured(order.payment.state);
+  return { state: ready ? "ready" : "held", ready, blocks };
+}
+
+function checkoutRecord(order: CheckoutOrderSummary): ScrappyOrderRecord {
+  const payment: PaymentState = order.payment;
+  return {
+    id: order.id,
+    placedAt: order.placedAt,
+    tenantId: "",
+    stage: "preview",
+    currency: order.currency,
+    payment: { state: payment, source: "checkout-order", asOf: order.placedAt },
+    tax: readSourcedEvidence(order.verification, "tax"),
+    verification: readSourcedEvidence(order.verification, "verification"),
+    risk: readSourcedEvidence(order.verification, "risk"),
+    stock: { state: "UNKNOWN", source: "absent", asOf: null },
+    stockEvidence: readSourcedEvidence(order.verification, "stock"),
+    fulfillment: {
+      state: fulfillmentFromCheckout(order.fulfillment),
+      source: "checkout-order",
+      asOf: order.placedAt,
+    },
+    label: "UNKNOWN",
+    compliance: "UNKNOWN",
+    providerOutcome: null,
+    authority: null,
+    totals: { subtotalMinor: 0, shippingMinor: 0, taxMinor: 0, totalMinor: 0 },
+  };
+}
+
+/** Checkout DTO assessment. `verification: null` reports UNKNOWN and held. */
+export function assessCheckoutOrder(order: CheckoutOrderSummary): CheckoutReadiness {
+  const record = checkoutRecord(order);
+  const release = order.verification == null
+    ? heldRelease(releaseOf(record))
+    : releaseOf(record);
+  return {
+    columns: readinessColumns(record),
+    evidence: evidenceOf(record),
+    release,
+    riskLevel: deriveRisk(order.verification, order.blocker),
+  };
+}
+
+function heldRelease(release: OrderRelease): OrderRelease {
+  if (release.state === "held") return release;
+  return { state: "held", ready: false, blocks: [...release.blocks, "evidence"] };
 }
 
-/** Map a DTO summary to the view model's OrderRow. */
 export function mapSummaryToRow(s: CheckoutOrderSummary): OrderRow {
+  const verificationMissing = s.verification == null;
+  const shipState: OrderShipState = verificationMissing ? "hold_review_required" : s.fulfillment;
+  const blocker = s.blocker ?? (verificationMissing ? "Verification unknown" : null);
   return {
     id: s.id,
     placedAt: s.placedAt,
     customerId: s.customer.id ?? "",
     customerName: s.customer.name,
-    customerNote: "", // not carried by the commerce DTO
+    customerNote: "",
     itemsSummary: s.itemsSummary,
-    productId: "", // not carried by the commerce order summary DTO (mock links by product index)
+    productId: "",
     total: s.total,
     payment: s.payment,
-    shipState: s.fulfillment,
-    blocker: s.blocker,
-    nextStep: deriveNextStep(s.fulfillment, s.blocker),
+    shipState,
+    blocker,
+    nextStep: deriveNextStep(shipState, blocker),
     riskLevel: deriveRisk(s.verification, s.blocker),
   };
 }
 
-/** Commerce-derived readiness checks (the verification join enriches the identity dimension). */
+function paymentValue(payment: CheckoutOrderPayment): string {
+  if (payment === "captured") return "Captured";
+  if (payment === "refunded") return "Refunded";
+  return "Authorized";
+}
+
+function columnCheck(
+  column: OrderReadinessColumn,
+  copy: Omit<OrderReadinessCheck, "key" | "value">,
+): OrderReadinessCheck {
+  return { key: column.key, value: column.state, ...copy };
+}
+
 function deriveReadinessChecks(d: CheckoutOrderDetail): OrderReadinessCheck[] {
+  const report = assessCheckoutOrder(d);
+  const column = (key: OrderReadinessColumn["key"]) => report.columns.find((item) => item.key === key)!;
+  const payment = column("payment");
+  const tax = column("tax");
+  const verification = column("verification");
   const ageHold = d.blocker === "Age verification hold";
   return [
     {
       key: "payment_capture",
       label: "Payment capture",
-      value: d.payment === "captured" ? "Captured" : "Authorized",
-      detail: "Capture the authorization before creating the shipping label.",
-      tone: d.payment === "captured" ? "green" : "amber",
+      value: paymentValue(d.payment),
+      detail: payment.state === "captured"
+        ? "Payment is captured."
+        : "Pending or authorized payment is not captured.",
+      tone: payment.state === "captured" ? "green" : payment.state === "refunded" ? "red" : "amber",
       action: "Capture payment",
-      blocking: d.payment !== "captured",
+      blocking: !paymentIsCaptured(payment.state as PaymentState),
     },
     {
       key: "tax_and_fees",
       label: "Tax and fees",
-      value: "Collected",
-      detail: "Required amounts are included in the order total.",
-      tone: "blue",
+      value: tax.state,
+      detail: `Tax evidence is ${tax.state}.`,
+      tone: tax.state === "fresh" ? "blue" : "amber",
       action: "View total",
-      blocking: false,
+      blocking: tax.state !== "fresh",
     },
     {
       key: "identity_and_age",
       label: "Identity and age",
-      value: ageHold ? "Needs review" : "Passed",
-      detail: "Checkout assurance completed before order placement.",
-      tone: ageHold ? "amber" : "green",
+      value: ageHold ? "Needs review" : verification.state,
+      detail: verification.state === "fresh"
+        ? "Verification evidence is fresh."
+        : "Verification evidence does not clear this order.",
+      tone: verification.state === "fresh" && !ageHold ? "green" : "amber",
       action: "View evidence",
-      blocking: ageHold,
+      blocking: ageHold || verification.state !== "fresh",
     },
     {
       key: "address",
       label: "Address",
       value: d.shippingAddress ? "Serviceable" : "Unknown",
-      detail: "Destination is deliverable after any hold is resolved.",
+      detail: d.shippingAddress
+        ? "An address is on the order."
+        : "No address is on the order.",
       tone: d.shippingAddress ? "green" : "amber",
       action: "View address",
       blocking: false,
     },
+    columnCheck(column("risk"), {
+      label: "Risk",
+      detail: `Risk evidence is ${column("risk").state}.`,
+      tone: column("risk").state === "fresh" ? "green" : "amber",
+      action: "View evidence",
+      blocking: column("risk").state !== "fresh",
+    }),
+    columnCheck(column("stock"), {
+      label: "Stock",
+      detail: `Stock is ${column("stock").state}.`,
+      tone: column("stock").state === "confirmed" ? "green" : "amber",
+      action: "View stock",
+      blocking: column("stock").state !== "confirmed",
+    }),
+    columnCheck(column("fulfillment"), {
+      label: "Fulfillment",
+      detail: `Fulfillment is ${column("fulfillment").state}.`,
+      tone: column("fulfillment").state === "ready" ? "green" : "amber",
+      action: "View fulfillment",
+      blocking: column("fulfillment").state !== "ready" && column("fulfillment").state !== "handed_off",
+    }),
   ];
 }
 
-/** Base commerce evidence events (the verification join replaces with the real verification timeline). */
 function deriveEvidenceTimeline(d: CheckoutOrderDetail): OrderEvidenceEvent[] {
   const events: OrderEvidenceEvent[] = [
     { title: "Order imported", detail: "Storefront order became available in the admin queue.", at: d.placedAt },
-    { title: "Payment authorized", detail: "The customer completed checkout and payment was authorized.", at: d.placedAt },
   ];
+  if (d.payment === "authorized") {
+    events.push({ title: "Payment authorized", detail: "Payment is authorized and not captured.", at: d.placedAt });
+  } else if (d.payment === "captured") {
+    events.push({ title: "Payment captured", detail: "Payment is captured.", at: d.placedAt });
+  } else {
+    events.push({ title: "Payment refunded", detail: "A refund blocks release.", at: d.placedAt });
+  }
+  if (d.verification == null) {
+    events.push({
+      title: "Verification unknown",
+      detail: "Verification evidence is absent. Release stays held.",
+      at: d.placedAt,
+    });
+  }
   if (d.blocker) {
     events.push({ title: "Hold added", detail: `${d.blocker} must be resolved before shipment.`, at: d.placedAt });
   }
   return events;
 }
 
-/** Map a DTO detail (its summary already mapped to `row`) to the view model's OrderDetail. */
 export function mapDetailToDetail(d: CheckoutOrderDetail, row: OrderRow): OrderDetail {
+  const report = assessCheckoutOrder(d);
   return {
     ...row,
     lineItems: d.lineItems.map((li) => ({
@@ -143,6 +459,8 @@ export function mapDetailToDetail(d: CheckoutOrderDetail, row: OrderRow): OrderD
     taxesAndFees: d.totals.taxesAndFees,
     readinessChecks: deriveReadinessChecks(d),
     evidenceTimeline: deriveEvidenceTimeline(d),
+    columns: report.columns,
+    release: report.release,
   };
 }
 
@@ -159,18 +477,12 @@ function buildQueues(rows: OrderRow[]): OrderQueueSummary[] {
   ];
 }
 
-/**
- * PURE map of DTO orders → the OrdersViewModel. `details` supplies the per-order
- * detail (line items / totals); a row with no matching detail falls back to a
- * minimal detail built from the row so `detailsById[row.id]` is always present.
- */
 export function mapOrdersToViewModel(
   targetTenant: string,
   summaries: CheckoutOrderSummary[],
   details: Record<string, CheckoutOrderDetail>,
 ): OrdersViewModel {
   const rows = summaries.map(mapSummaryToRow);
-
   const detailsById: Record<string, OrderDetail> = {};
   for (const row of rows) {
     const d = details[row.id];
@@ -188,7 +500,9 @@ export function mapOrdersToViewModel(
   }
 
   const paidOrders = rows.filter((r) => r.payment === "captured");
+  const refunded = rows.filter((r) => r.payment === "refunded");
   const grossSales = paidOrders.reduce((sum, r) => sum + r.total, 0);
+  const refunds = refunded.reduce((sum, r) => sum + r.total, 0);
 
   return {
     targetTenant,
@@ -199,13 +513,12 @@ export function mapOrdersToViewModel(
       grossSales,
       paidOrders: paidOrders.length,
       averageOrder: paidOrders.length ? Math.round((grossSales / paidOrders.length) * 100) / 100 : 0,
-      refunds: 0,
+      refunds,
       oldestOpenAt: rows.length ? rows[rows.length - 1]!.placedAt : null,
     },
   };
 }
 
-/** A valid, empty view model — rendered when nothing is available or a fetch fails. */
 export function emptyOrdersViewModel(targetTenant: string): OrdersViewModel {
   return mapOrdersToViewModel(targetTenant, [], {});
 }
@@ -213,22 +526,9 @@ export function emptyOrdersViewModel(targetTenant: string): OrdersViewModel {
 export interface GetOrdersViewModelOptions {
   targetTenant: string;
   client: CheckoutOrderClient;
-  /** List filters (queue/status/pagination); passed through to the order client. */
   filters?: Parameters<CheckoutOrderClient["listOrders"]>[0];
 }
 
-/**
- * Fetch + map the real orders view model. Lists orders, eagerly fetches each
- * order's detail (bounded by the list page size), and maps. Any upstream error
- * (incl. the not-yet-available ToT-core endpoint) degrades to the empty model so
- * the Orders tab always renders.
- */
-/**
- * Load outcome for the Orders tab — lets the UI pick the right state:
- * `loaded` (rows), `empty` (fetch OK, 0 orders), `error` (upstream failed), and
- * `not_configured` (produced by the caller when no bearer/client is available —
- * the service itself never returns it). `page` carries the pagination cursor.
- */
 export type OrdersLoadStatus = "loaded" | "empty" | "error" | "not_configured";
 
 export interface OrdersLoadResult {
@@ -237,12 +537,6 @@ export interface OrdersLoadResult {
   page: CheckoutOrderPage | null;
 }
 
-/**
- * Parse server-backed list filters from a request's query string. `queue`
- * of `"all"` (or absent) means no server filter. Non-numeric `limit` is ignored.
- * `payment`/search are NOT here — they are client-side refinements (the DTO list
- * API has no payment filter, per contract §9).
- */
 export function parseOrderFilters(params: URLSearchParams): CheckoutOrderListFilters {
   const f: CheckoutOrderListFilters = {};
   const queue = params.get("queue");
@@ -260,14 +554,7 @@ export function parseOrderFilters(params: URLSearchParams): CheckoutOrderListFil
   return f;
 }
 
-/**
- * Fetch + map the orders view model AND report the load outcome. Lists,
- * eagerly fetches per-order detail, maps. Distinguishes empty from error so the
- * tab can degrade gracefully. Never throws.
- */
-export async function getOrdersViewModelResult(
-  opts: GetOrdersViewModelOptions,
-): Promise<OrdersLoadResult> {
+export async function getOrdersViewModelResult(opts: GetOrdersViewModelOptions): Promise<OrdersLoadResult> {
   try {
     const { orders, page } = await opts.client.listOrders(opts.filters);
     const details: Record<string, CheckoutOrderDetail> = {};
@@ -290,9 +577,159 @@ export async function getOrdersViewModelResult(
   }
 }
 
-/** Convenience wrapper: just the view model (see getOrdersViewModelResult). */
-export async function getOrdersViewModel(
-  opts: GetOrdersViewModelOptions,
-): Promise<OrdersViewModel> {
+export async function getOrdersViewModel(opts: GetOrdersViewModelOptions): Promise<OrdersViewModel> {
   return (await getOrdersViewModelResult(opts)).vm;
 }
+
+function moneyScope(orders: readonly ScrappyOrderRecord[]): OrderMoneyScope {
+  const values: number[] = [];
+  const refunds: number[] = [];
+  for (const order of orders) {
+    if (!totalsMatch(order.totals)) throw new Error("totals do not match minor units");
+    if (REFUND_PAYMENTS.has(order.payment.state)) refunds.push(order.totals.totalMinor);
+    else if (paymentIsCaptured(order.payment.state) || order.payment.state === "pending" || order.payment.state === "authorized") {
+      values.push(order.totals.totalMinor);
+    }
+  }
+  return {
+    count: orders.length,
+    valueMinor: sumMinor(values),
+    refundMinor: sumMinor(refunds),
+  };
+}
+
+function matchesFilter(order: ScrappyOrderRecord, filter: ScrappyOrderFilter | undefined): boolean {
+  if (!filter) return true;
+  if (filter.payment && order.payment.state !== filter.payment) return false;
+  if (filter.fulfillment && order.fulfillment.state !== filter.fulfillment) return false;
+  if (filter.from && order.placedAt < filter.from) return false;
+  if (filter.to && order.placedAt >= filter.to) return false;
+  if (filter.queue && filter.queue !== "all") {
+    const release = releaseOf(order);
+    if (filter.queue === "needs_attention" && release.state !== "held") return false;
+    if (filter.queue === "ready_to_ship" && !release.ready) return false;
+    if (filter.queue === "completed" && order.fulfillment.state !== "handed_off") return false;
+    if (filter.queue === "unfulfilled" && (order.fulfillment.state === "handed_off" || order.fulfillment.state === "cancelled")) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function toView(order: ScrappyOrderRecord, address: unknown | undefined): ScrappyOrderView {
+  const view: ScrappyOrderView = {
+    id: order.id,
+    placedAt: order.placedAt,
+    tenantId: order.tenantId,
+    stage: order.stage,
+    currency: order.currency,
+    payment: order.payment,
+    tax: order.tax,
+    verification: order.verification,
+    risk: order.risk,
+    stock: order.stock,
+    stockEvidence: order.stockEvidence,
+    fulfillment: order.fulfillment,
+    label: order.label,
+    compliance: order.compliance,
+    providerOutcome: order.providerOutcome,
+    authority: order.authority,
+    totals: order.totals,
+    columns: readinessColumns(order),
+    evidence: evidenceOf(order),
+    release: releaseOf(order),
+  };
+  if (address !== undefined) view.address = address;
+  return view;
+}
+
+/**
+ * Cursor page over one tenant and stage. Storewide, filter, and page money are
+ * computed separately. A caller sees no address. A mismatched tenant or role
+ * sees nothing.
+ */
+export function queryScrappyOrders(input: ScrappyOrderQuery): ScrappyOrderQueryResult {
+  if (!actorMayCommand(input.actor, input.resource)) return { ok: false, reason: "denied" };
+  const storewide = input.orders.filter(
+    (order) => order.tenantId === input.resource.tenantId && order.stage === input.resource.stage,
+  );
+  const filtered = storewide.filter((order) => matchesFilter(order, input.filter));
+  const page = paginateOrders(filtered, input.limit, input.cursor);
+  return {
+    ok: true,
+    orders: page.orders.map((order) => {
+      const read = readOwnerAddress(input.actor, input.resource, () => order.address);
+      return toView(order, read.ok ? read.address ?? undefined : undefined);
+    }),
+    nextCursor: page.nextCursor,
+    invalidCursor: page.invalidCursor,
+    accounting: {
+      storewide: moneyScope(storewide),
+      filter: moneyScope(filtered),
+      page: moneyScope(page.orders),
+    },
+  };
+}
+
+/** Generic event. Customer and address fields on the input are not copied. */
+export function observeScrappyOrder(order: ScrappyOrderRecord): PublicCommerceEvent {
+  return publicCommerceEvent({
+    eventVersion: 1,
+    orderId: order.id,
+    placedAt: order.placedAt,
+    currency: order.currency,
+    payment: order.payment.state,
+    compliance: order.compliance,
+    stock: order.stock.state,
+    fulfillment: order.fulfillment.state,
+    label: order.label,
+    totals: order.totals,
+    verificationDetail: evidenceOf(order),
+    customerId: order.customerId,
+    address: order.address,
+  });
+}
+
+interface FixtureOrder {
+  id: string;
+  placedAt: string;
+  currency: string;
+  payment: PaymentState;
+  compliance: ComplianceState;
+  stock: StockState;
+  fulfillment: FulfillmentState;
+  label: LabelState;
+  totals: MinorTotals;
+  customer?: { id?: string | null };
+  verificationDetail: CommerceEvidence;
+}
+
+/** Adapt a frozen fixture order. Evidence states are copied, not recomputed. */
+export function scrappyRecordFromFixture(
+  order: FixtureOrder,
+  tenantId: string,
+  stage: CommerceStage,
+): ScrappyOrderRecord {
+  const at = order.placedAt;
+  const source = "scrappy-orders-v1";
+  return {
+    id: order.id,
+    placedAt: at,
+    tenantId,
+    stage,
+    currency: order.currency,
+    payment: { state: order.payment, source, asOf: at },
+    tax: { state: order.verificationDetail.tax, source, asOf: at },
+    verification: { state: order.verificationDetail.verification, source, asOf: at },
+    risk: { state: order.verificationDetail.risk, source, asOf: at },
+    stock: { state: order.stock, source, asOf: at },
+    stockEvidence: { state: order.verificationDetail.stock, source, asOf: at },
+    fulfillment: { state: order.fulfillment, source, asOf: at },
+    label: order.label,
+    compliance: order.compliance,
+    providerOutcome: null,
+    authority: null,
+    totals: order.totals,
+    customerId: order.customer?.id ?? null,
+  };
+}