@tokenoftrust/storefront-runner 6.5.2 → 6.5.3

package/apps/storefront/src/lib/fulfillment/admin/commerceDesk.ts

@@ -1,6 +1,7 @@
 /** Operational browser client. All authority and state changes remain in the authenticated APIs. */
 import type { FulfillmentView } from "../fulfillmentService.js";
 import { parseCommerceDeskApiRoot } from "./commerceDeskRouting.js";
+import { trackingUrlAllowed } from "../carrierEvidence.js";
 export function mountCommerceDesk(root: HTMLElement): void {
   const status = root.querySelector<HTMLElement>("[data-desk-status]")!;
   const rows = root.querySelector<HTMLElement>("[data-desk-orders]")!;
@@ -31,6 +32,30 @@ export function mountCommerceDesk(root: HTMLElement): void {
     parent.append(node);
     return node;
   }
+  /** Label and handoff state, carrier and tracking. The link is set only for an allowlisted https tracking URL. */
+  function renderShipment(shipment: NonNullable<FulfillmentView["shipment"]>, card: HTMLElement): void {
+    const block = document.createElement("div");
+    block.dataset.shipment = "";
+    card.append(block);
+    const state = text("p", `Label ${shipment.labelPurchaseState} · Handoff ${shipment.handoffState}`, block);
+    state.dataset.labelState = shipment.labelPurchaseState;
+    state.dataset.handoffState = shipment.handoffState;
+    if (shipment.carrier) {
+      const carrier = text("p", [shipment.carrier, shipment.service].filter(Boolean).join(" · "), block);
+      carrier.dataset.carrier = shipment.carrier;
+    }
+    if (shipment.trackingNumber) {
+      const tracking = text("a", `Tracking ${shipment.trackingNumber}`, block) as HTMLAnchorElement;
+      tracking.dataset.trackingNumber = shipment.trackingNumber;
+      tracking.rel = "noopener noreferrer";
+      tracking.referrerPolicy = "no-referrer";
+      if (trackingUrlAllowed(shipment.carrier, shipment.trackingUrl)) {
+        tracking.href = shipment.trackingUrl;
+        tracking.target = "_blank";
+        tracking.dataset.trackingUrl = shipment.trackingUrl;
+      }
+    }
+  }
   function render(order: FulfillmentView): void {
     const card = document.createElement("section");
     card.dataset.orderId = order.orderId;
@@ -43,6 +68,7 @@ export function mountCommerceDesk(root: HTMLElement): void {
       const owner = text("p", `Assigned to processor ${order.assignment.installId} · ${order.assignment.state}`, card);
       owner.dataset.assignmentState = order.assignment.state;
     }
+    if (order.shipment) renderShipment(order.shipment, card);
     const actions = order.batch
       ? [
           ["pick", "Confirm pick"],

package/apps/storefront/src/lib/fulfillment/admin/viewmodels/fulfillment.ts

@@ -21,11 +21,11 @@ import {
   type PublicCommerceEvent,
   type StockState,
 } from "@tot/public-runtime";
+import { trackingHostsFor } from "../../carrierEvidence.js";
 
 export const SCRAPPY_FULFILLMENT_PATH = "/scrappy-fulfillment";
 export const WORKSPACE_PAGE_LIMIT = 4;
 export const TEST_ADAPTER_QUOTE_MINOR = 640;
-export const TRACKING_HOSTS = ["tracking.example"] as const;
 
 export const WORKSPACE_QUEUES = ["ready", "held", "in_progress", "shipped"] as const;
 export type WorkspaceQueue = (typeof WORKSPACE_QUEUES)[number];
@@ -98,6 +98,7 @@ interface WorkspaceOrder {
   purchaseKey: string | null;
   purchaseId: string | null;
   labelCostMinor: number | null;
+  carrier: string | null;
   trackingNumber: string | null;
   trackingUrl: string | null;
   ownerDestination: string;
@@ -353,6 +354,7 @@ export function initialWorkspaceState(tenantId: string, stage: CommerceStage = "
     purchaseKey: extra.purchaseKey ?? null,
     purchaseId: extra.purchaseId ?? null,
     labelCostMinor: extra.labelCostMinor ?? null,
+    carrier: extra.carrier ?? null,
     trackingNumber: extra.trackingNumber ?? null,
     trackingUrl: extra.trackingUrl ?? null,
     ownerDestination: `dest-${id}`,
@@ -445,8 +447,9 @@ export function initialWorkspaceState(tenantId: string, stage: CommerceStage = "
         purchaseKey: "key-shipped",
         purchaseId: "test-key-shipped",
         labelCostMinor: TEST_ADAPTER_QUOTE_MINOR,
+        carrier: "UPS",
         trackingNumber: "TRK-ord-shipped",
-        trackingUrl: "https://tracking.example/label/ord-shipped",
+        trackingUrl: "https://www.ups.com/track?tracknum=TRKORDSHIPPED",
       }),
     ],
     events: [],
@@ -471,7 +474,7 @@ function projectOrder(state: WorkspaceState, order: WorkspaceOrder, actor: Comme
       actor,
       resource: scope,
       trackingUrl: order.trackingUrl,
-      allowedHosts: TRACKING_HOSTS,
+      allowedHosts: trackingHostsFor(order.carrier),
     });
     if (admitted.ok) trackingUrl = order.trackingUrl;
   }
@@ -740,8 +743,9 @@ function applyToOrder(state: WorkspaceState, order: WorkspaceOrder, command: Wor
     });
     if (!decision.admit) return refuse(decision.reason);
     order.fulfillment = "handed_off";
+    order.carrier = "UPS";
     order.trackingNumber = `TRK-${order.id}`;
-    order.trackingUrl = `https://tracking.example/label/${encodeURIComponent(order.id)}`;
+    order.trackingUrl = `https://www.ups.com/track?tracknum=${encodeURIComponent(order.id)}`;
     return finish({ ...blankResult(command.command, order.id, "admitted", "handed-off"), purchaseId: order.purchaseId });
   }
 

package/apps/storefront/src/lib/fulfillment/appShipmentEvidence.ts

@@ -0,0 +1,245 @@
+/**
+ * The processor's shipment-evidence contract: the closed request schema, the minimized response,
+ * the active-install and active-assignment predicate every app write carries in its first
+ * statement, and the idempotency record a replay returns.
+ */
+import type { LabelState } from "@tot/public-runtime";
+import { PROCESSOR_SCOPE } from "./assignmentStore.js";
+import type { SqlStatement } from "./store.js";
+import { CARRIER_SERVICE, TRACKING_NUMBER, parseCarrierCode, trackingUrlAllowed, type CarrierCode } from "./carrierEvidence.js";
+
+/** The calling install and the assignment it writes under. Every app write requires both. */
+export interface AppAssignmentBinding {
+  readonly installId: string;
+  readonly assignmentId: string;
+}
+
+export type AdultSignatureResult = "accepted" | "refused" | "absent";
+
+export interface LabelOutcomeEvidence {
+  kind: "label-outcome";
+  assignmentId: string;
+  purchaseId: string;
+  outcome: "purchased" | "unknown" | "voided";
+  carrier?: CarrierCode;
+  service?: string;
+  trackingNumber?: string;
+  trackingUrl?: string;
+  adultSignature: AdultSignatureResult;
+  expectedVersion?: number;
+}
+
+export interface HandoffEvidence {
+  kind: "handoff";
+  assignmentId: string;
+  purchaseId: string;
+  carrier: CarrierCode;
+  expectedVersion?: number;
+}
+
+export type ShipmentEvidence = LabelOutcomeEvidence | HandoffEvidence;
+
+export interface AppShipmentView {
+  orderId: string;
+  version: number;
+  label: LabelState;
+  handoff: "none" | "handed_off" | "unknown";
+  purchaseId: string;
+  carrier?: CarrierCode;
+  tracking?: { number: string; url: string };
+}
+
+export interface AppRefusalBody {
+  code: string;
+  error: string;
+  holds?: readonly string[];
+}
+
+export interface AppEvidenceResponse {
+  status: number;
+  body: AppShipmentView | AppRefusalBody;
+}
+
+/** The facts a label-outcome audit row stores, read back by the desk and the app view. */
+export interface StoredLabelFacts {
+  outcome: LabelOutcomeEvidence["outcome"] | null;
+  adultSignature: AdultSignatureResult;
+  carrier: CarrierCode | null;
+  service: string | null;
+  trackingNumber: string | null;
+  trackingUrl: string | null;
+}
+
+const OPAQUE = /^[A-Za-z0-9._:-]{1,128}$/;
+export const IDEMPOTENCY_KEY = /^[\x21-\x7e]{8,128}$/;
+const LABEL_KEYS = new Set([
+  "kind",
+  "assignmentId",
+  "purchaseId",
+  "outcome",
+  "carrier",
+  "service",
+  "trackingNumber",
+  "trackingUrl",
+  "adultSignature",
+  "expectedVersion",
+]);
+const HANDOFF_KEYS = new Set(["kind", "assignmentId", "purchaseId", "carrier", "expectedVersion"]);
+const PURCHASED_REQUIRES = ["carrier", "service", "trackingNumber", "trackingUrl", "adultSignature"] as const;
+
+function opaque(value: unknown): value is string {
+  return typeof value === "string" && OPAQUE.test(value) && !value.includes("@");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The body in the closed schema, or null (400 malformed): unknown keys, a null value, unknown carrier, unsafe URL. */
+export function parseShipmentEvidence(body: unknown): ShipmentEvidence | null {
+  if (!isRecord(body)) return null;
+  const keys = body.kind === "label-outcome" ? LABEL_KEYS : body.kind === "handoff" ? HANDOFF_KEYS : null;
+  if (!keys || Object.keys(body).some((key) => !keys.has(key))) return null;
+  if (Object.values(body).some((value) => value === null)) return null;
+  if (!opaque(body.assignmentId) || !opaque(body.purchaseId)) return null;
+  if (body.expectedVersion !== undefined && (!Number.isSafeInteger(body.expectedVersion) || Number(body.expectedVersion) < 0)) return null;
+  const expected = body.expectedVersion === undefined ? {} : { expectedVersion: Number(body.expectedVersion) };
+  if (body.kind === "handoff") {
+    const carrier = parseCarrierCode(body.carrier);
+    if (!carrier) return null;
+    return { kind: "handoff", assignmentId: body.assignmentId, purchaseId: body.purchaseId, carrier, ...expected };
+  }
+  if (body.outcome !== "purchased" && body.outcome !== "unknown" && body.outcome !== "voided") return null;
+  if (body.outcome === "purchased" && PURCHASED_REQUIRES.some((key) => body[key] === undefined)) return null;
+  const carrier = body.carrier === undefined ? undefined : parseCarrierCode(body.carrier);
+  if (carrier === null) return null;
+  if (body.service !== undefined && (typeof body.service !== "string" || !CARRIER_SERVICE.test(body.service))) return null;
+  if (body.trackingNumber !== undefined && (typeof body.trackingNumber !== "string" || !TRACKING_NUMBER.test(body.trackingNumber))) return null;
+  if (body.trackingUrl !== undefined && !trackingUrlAllowed(carrier, body.trackingUrl)) return null;
+  const adult = body.adultSignature ?? "absent";
+  if (adult !== "accepted" && adult !== "refused" && adult !== "absent") return null;
+  return {
+    kind: "label-outcome",
+    assignmentId: body.assignmentId,
+    purchaseId: body.purchaseId,
+    outcome: body.outcome,
+    adultSignature: adult,
+    ...(carrier ? { carrier } : {}),
+    ...(typeof body.service === "string" ? { service: body.service } : {}),
+    ...(typeof body.trackingNumber === "string" ? { trackingNumber: body.trackingNumber } : {}),
+    ...(typeof body.trackingUrl === "string" ? { trackingUrl: body.trackingUrl } : {}),
+    ...expected,
+  };
+}
+
+/** The label-outcome audit `to_state`: closed keys, absent facts omitted. */
+export function labelOutcomeRecord(evidence: LabelOutcomeEvidence): Record<string, string> {
+  return {
+    outcome: evidence.outcome,
+    adultSignature: evidence.adultSignature,
+    ...(evidence.carrier ? { carrier: evidence.carrier } : {}),
+    ...(evidence.service ? { service: evidence.service } : {}),
+    ...(evidence.trackingNumber ? { trackingNumber: evidence.trackingNumber } : {}),
+    ...(evidence.trackingUrl ? { trackingUrl: evidence.trackingUrl } : {}),
+  };
+}
+
+/** A stored label-outcome audit `to_state`, re-validated on read. Facts that fail their shape read as absent. */
+export function parseStoredLabelFacts(value: unknown): StoredLabelFacts | null {
+  if (!isRecord(value)) return null;
+  if (value.adultSignature !== "accepted" && value.adultSignature !== "refused" && value.adultSignature !== "absent") return null;
+  const carrier = parseCarrierCode(value.carrier);
+  const outcome = value.outcome === "purchased" || value.outcome === "unknown" || value.outcome === "voided" ? value.outcome : null;
+  return {
+    outcome,
+    adultSignature: value.adultSignature,
+    carrier,
+    service: typeof value.service === "string" && CARRIER_SERVICE.test(value.service) ? value.service : null,
+    trackingNumber: typeof value.trackingNumber === "string" && TRACKING_NUMBER.test(value.trackingNumber) ? value.trackingNumber : null,
+    trackingUrl: trackingUrlAllowed(carrier, value.trackingUrl) ? value.trackingUrl : null,
+  };
+}
+
+/** True when a recorded purchase carries exactly these facts. */
+export function sameLabelFacts(stored: StoredLabelFacts | null, evidence: LabelOutcomeEvidence): boolean {
+  return (
+    stored !== null &&
+    stored.adultSignature === evidence.adultSignature &&
+    stored.carrier === (evidence.carrier ?? null) &&
+    stored.service === (evidence.service ?? null) &&
+    stored.trackingNumber === (evidence.trackingNumber ?? null) &&
+    stored.trackingUrl === (evidence.trackingUrl ?? null)
+  );
+}
+
+/**
+ * SQL condition (no leading AND) every app write carries in statements[0]: the calling install is
+ * active on the host tenant with the processor scope, and the bound assignment of this order names
+ * it and is active.
+ */
+export function appWritePredicate(
+  binding: AppAssignmentBinding,
+  scope: { tenantId: string; stage: string; orderId: string },
+): SqlStatement {
+  return {
+    sql: `EXISTS (
+        SELECT 1 FROM app_installs AS ai
+        WHERE ai.install_id = ? AND ai.tenant_id = ? AND ai.status = 'active'
+          AND EXISTS (SELECT 1 FROM json_each(ai.scopes) WHERE json_each.value = '${PROCESSOR_SCOPE}')
+      ) AND EXISTS (
+        SELECT 1 FROM fulfillment_assignments AS fa
+        WHERE fa.assignment_id = ? AND fa.tenant_id = ? AND fa.stage = ? AND fa.order_id = ?
+          AND fa.install_id = ? AND fa.state = 'active'
+      )`,
+    params: [
+      binding.installId,
+      scope.tenantId,
+      binding.assignmentId,
+      scope.tenantId,
+      scope.stage,
+      scope.orderId,
+      binding.installId,
+    ],
+  };
+}
+
+const STATUS: Record<string, number> = {
+  malformed: 400,
+  invalid_token: 401,
+  scope_denied: 403,
+  denied: 403,
+  "not-assigned": 404,
+  unavailable: 503,
+};
+
+/** A refusal response: `{ code, error }`, plus `holds` on a handoff refusal. */
+export function appRefusal(code: string, holds?: readonly string[]): AppEvidenceResponse {
+  if (code === "invalid_token") return { status: 401, body: { error: "Unauthorized", code } };
+  const body: AppRefusalBody = holds && holds.length > 0 ? { code, error: code, holds: [...holds] } : { code, error: code };
+  return { status: STATUS[code] ?? 409, body };
+}
+
+/** The idempotency record: the response status and body a same-key, same-body retry returns. */
+export function idempotencyRecord(response: AppEvidenceResponse): string {
+  return JSON.stringify({ status: response.status, body: response.body });
+}
+
+/** A recorded response, or null when the record is not one this route wrote. */
+export function replayedResponse(recorded: unknown): AppEvidenceResponse | null {
+  if (!isRecord(recorded) || !Number.isSafeInteger(recorded.status) || !isRecord(recorded.body)) return null;
+  return { status: Number(recorded.status), body: recorded.body as unknown as AppShipmentView | AppRefusalBody };
+}
+
+/** The batch key insert: a plain INSERT, so a same-key race rolls the whole batch back. */
+export function idempotencyInsertStatement(input: {
+  installId: string;
+  key: string;
+  bodyHash: string;
+  response: AppEvidenceResponse;
+  now: string;
+}): SqlStatement {
+  return {
+    sql: `INSERT INTO idempotency_keys (install_id, idempotency_key, body_hash, response_body, created_at) VALUES (?, ?, ?, ?, ?)`,
+    params: [input.installId, input.key, input.bodyHash, idempotencyRecord(input.response), input.now],
+  };
+}

package/apps/storefront/src/lib/fulfillment/carrierEvidence.ts

@@ -0,0 +1,65 @@
+/**
+ * Carrier evidence a fulfillment processor reports: a closed set of canonical carrier codes and,
+ * per carrier, the tracking hosts a tracking URL may name. The same allowlist validates an app's
+ * write and gates the merchant desk's tracking link. Tracking URLs are never fetched.
+ */
+export const CARRIER_CODES = ["UPS", "FEDEX", "USPS", "DHL"] as const;
+export type CarrierCode = (typeof CARRIER_CODES)[number];
+
+export const CARRIER_TRACKING_HOSTS: Readonly<Record<CarrierCode, readonly string[]>> = {
+  UPS: ["www.ups.com"],
+  FEDEX: ["www.fedex.com"],
+  USPS: ["tools.usps.com"],
+  DHL: ["www.dhl.com"],
+};
+
+export const TRACKING_NUMBER = /^[A-Z0-9]{6,40}$/;
+export const CARRIER_SERVICE = /^[A-Z0-9_]{1,40}$/;
+export const TRACKING_URL_MAX = 2048;
+export const TRACKING_PART_MAX = 512;
+
+/** The canonical form every carrier comparison uses: trimmed and uppercased. */
+export function canonicalCarrier(value: string): string {
+  return value.trim().toUpperCase();
+}
+
+/** A supplied carrier as its canonical code, or null when it is not in the closed set. */
+export function parseCarrierCode(value: unknown): CarrierCode | null {
+  if (typeof value !== "string") return null;
+  const canonical = canonicalCarrier(value);
+  return (CARRIER_CODES as readonly string[]).includes(canonical) ? (canonical as CarrierCode) : null;
+}
+
+/** The tracking hosts allowed for `carrier`; none for a value outside the closed set. */
+export function trackingHostsFor(carrier: unknown): readonly string[] {
+  const code = parseCarrierCode(carrier);
+  return code ? CARRIER_TRACKING_HOSTS[code] : [];
+}
+
+/**
+ * True when `url` is an https URL on one of `carrier`'s tracking hosts: at most 2048 characters,
+ * printable ASCII only, the authority exactly an allowed host (so no userinfo, port or IP literal),
+ * no fragment, and a path and query of at most 512 characters each.
+ */
+export function trackingUrlAllowed(carrier: unknown, url: unknown): url is string {
+  if (typeof url !== "string" || url.length > TRACKING_URL_MAX) return false;
+  if (!/^[\x21-\x7e]+$/.test(url) || url.includes("#") || url.includes("\\")) return false;
+  if (!url.startsWith("https://")) return false;
+  const authority = url.slice("https://".length).split(/[/?]/, 1)[0] ?? "";
+  if (!trackingHostsFor(carrier).includes(authority)) return false;
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "https:" || parsed.username !== "" || parsed.password !== "" || parsed.port !== "") return false;
+  if (parsed.host !== authority || parsed.hash !== "") return false;
+  return parsed.pathname.length <= TRACKING_PART_MAX && parsed.search.replace(/^\?/, "").length <= TRACKING_PART_MAX;
+}
+
+/** True when `carrier` is in either prohibited set, both compared in canonical form. */
+export function carrierProhibited(carrier: string, ...prohibited: ReadonlyArray<readonly string[]>): boolean {
+  const canonical = canonicalCarrier(carrier);
+  return prohibited.some((set) => set.some((item) => canonicalCarrier(item) === canonical));
+}

package/apps/storefront/src/lib/fulfillment/fulfillmentService.ts

@@ -38,6 +38,7 @@ import { readViewerSession } from "@/lib/access/auth/route";
 import type { SessionRecord } from "@/lib/access/auth/session";
 import {
   canRelease,
+  carrierEvidenceRefusal,
   carrierPolicyForTenant,
   carrierSelectionRefusal,
   handoffRefusal,
@@ -52,6 +53,7 @@ import {
   type SqlStatement,
 } from "./store.js";
 import {
+  PROCESSOR_SCOPE,
   assignmentAtGate,
   insertAssignmentStatement,
   moveAssignmentStatement,
@@ -70,6 +72,24 @@ import {
 import { dispatchCommerceDeliveries } from "./commerceRuntime.js";
 import type { CommerceTopic } from "../integrations/webhooks/commercePayloads.js";
 import { claimedByEventGate, handoffClaimStatement } from "../integrations/webhooks/orderFulfilledClaim.js";
+import { checkIdempotency, computeBodyHash } from "../integrations/apps/orders/idempotency.js";
+import type { Queryable } from "../catalog/d1/catalog.js";
+import {
+  IDEMPOTENCY_KEY,
+  appRefusal,
+  appWritePredicate,
+  idempotencyInsertStatement,
+  labelOutcomeRecord,
+  parseStoredLabelFacts,
+  replayedResponse,
+  sameLabelFacts,
+  type AppAssignmentBinding,
+  type AppEvidenceResponse,
+  type AppShipmentView,
+  type HandoffEvidence,
+  type LabelOutcomeEvidence,
+  type StoredLabelFacts,
+} from "./appShipmentEvidence.js";
 
 export const OPAQUE_ID = /^[A-Za-z0-9._:-]{1,128}$/;
 
@@ -121,6 +141,11 @@ export interface ShipmentIntentView {
   carrierAccountId: string | null;
   adultSignatureRequired: boolean;
   prohibitedCarriers: string[];
+  /** The recorded label's carrier, service and tracking, as the processor reported them. */
+  carrier: string | null;
+  service: string | null;
+  trackingNumber: string | null;
+  trackingUrl: string | null;
 }
 
 export interface FulfillmentView {
@@ -201,7 +226,7 @@ interface LoadedOrder {
   packingSlip: PackingSlip | null;
   shipment: { labelPurchaseState: string; handoffState: string } | null;
   provider: { purchaseId: string; outcome: ProviderOutcome } | null;
-  labelOutcome: { adultSignature: "accepted" | "refused" | "absent" } | null;
+  labelOutcome: StoredLabelFacts | null;
   carrierAccountId: string | null;
   prohibitedCarriers: string[];
   adultSignatureRequired: boolean;
@@ -230,6 +255,27 @@ type CommitPlan =
       assignment?: boolean;
     };
 
+/** One app write: the install actor (built only by the route), the order, the key, the raw and parsed body. */
+export interface AppEvidenceRequest<T> {
+  actor: FulfillmentActor;
+  orderId: string;
+  idempotencyKey: string;
+  body: unknown;
+  evidence: T;
+}
+
+type AppPlan =
+  | { type: "done"; view: AppShipmentView }
+  | { type: "refuse"; code: string; holds?: readonly string[] }
+  | {
+      type: "write";
+      statements: SqlStatement[];
+      sourceAdvance: boolean;
+      deliveries: readonly PlannedDelivery[];
+      /** The planned post-state: the response and the idempotency record. */
+      view: AppShipmentView;
+    };
+
 /** Statement and delivery accumulator for a plan that may carry commerce events. */
 interface PlanStatements {
   statements: SqlStatement[];
@@ -955,66 +1001,306 @@ export class FulfillmentService {
         return { type: "refuse", code: "label" };
       }
       const version = state.order.eventVersion + 1;
+      const plan: PlanStatements = { deliveries: [], statements: this.handoffStatements(state, actor.actorId, version) };
+      await this.appendOrderFulfilled(plan, state, version);
+      return { type: "write", minimumChanges: 1, sourceAdvance: true, statements: plan.statements, deliveries: plan.deliveries };
+    });
+  }
+
+  /**
+   * The processor's label outcome under its assignment, from `app:<installId>` only. The first
+   * outcome opens the whole-order shipment and its label operation under the platform purchase id.
+   */
+  async appRecordLabelOutcome(request: AppEvidenceRequest<LabelOutcomeEvidence>): Promise<AppEvidenceResponse> {
+    const evidence = request.evidence;
+    return this.appCommit(request, async (state, binding, purchaseId) => {
+      if (evidence.purchaseId !== purchaseId || (state.provider && state.provider.purchaseId !== purchaseId)) {
+        return { type: "refuse", code: "conflict" };
+      }
+      const current = state.shipment?.labelPurchaseState ?? "none";
+      const unchanged = { type: "done", view: appShipmentView(state, purchaseId) } as const;
+      if (current === "purchased") {
+        if (evidence.outcome !== "purchased") return { type: "refuse", code: "label-regress" };
+        return sameLabelFacts(state.labelOutcome, evidence) ? unchanged : { type: "refuse", code: "conflict" };
+      }
+      if (current === "voided") return evidence.outcome === "voided" ? unchanged : { type: "refuse", code: "label-regress" };
+      if (current === "unknown" && evidence.outcome === "unknown") return unchanged;
+      if (state.order.fulfillment === "handed_off") return { type: "refuse", code: "fulfillment" };
+      if (evidence.carrier) {
+        const carrier = carrierEvidenceRefusal({ carrier: evidence.carrier, policy: this.policy, snapshotProhibited: state.prohibitedCarriers });
+        if (carrier) return { type: "refuse", code: carrier };
+      }
+      const mapped = labelOutcomeColumns(evidence.outcome);
+      const version = state.order.eventVersion + 1;
+      const { order } = state;
+      const actorId = request.actor.actorId;
+      let n = state.auditCount;
+      const nextStamp = () => stamp(this.now(), ++n);
+      const predicate = appWritePredicate(binding, order);
+      const statements: SqlStatement[] = [
+        {
+          sql: `UPDATE scrappy_commerce_orders
+            SET label_state = ?, event_version = event_version + 1
+            WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+              AND fulfillment_state != 'handed_off' AND label_state = ?
+              AND ${predicate.sql}`,
+          params: [mapped.order, order.tenantId, order.stage, order.orderId, order.eventVersion, order.label, ...predicate.params],
+        },
+      ];
+      if (!state.shipment) statements.push(...(await this.intentStatements(state, actorId, version, nextStamp, { assigned: true })));
+      statements.push(
+        {
+          sql: `UPDATE scrappy_shipments
+            SET label_purchase_state = ?
+            WHERE tenant_id = ? AND stage = ? AND order_id = ? AND handoff_state = 'none'
+              AND EXISTS (
+                SELECT 1 FROM scrappy_commerce_orders
+                WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+              )`,
+          params: [mapped.shipment, order.tenantId, order.stage, order.orderId, order.tenantId, order.stage, order.orderId, version],
+        },
+        {
+          sql: `UPDATE scrappy_provider_operations
+            SET outcome = ?
+            WHERE tenant_id = ? AND stage = ? AND order_id = ? AND kind = 'label_purchase'
+              AND provider = 'unselected' AND purchase_id = ?
+              AND EXISTS (
+                SELECT 1 FROM scrappy_commerce_orders
+                WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+              )`,
+          params: [mapped.provider, order.tenantId, order.stage, order.orderId, purchaseId, order.tenantId, order.stage, order.orderId, version],
+        },
+        auditStatement(state, actorId, "label-outcome", order.label, jsonText(labelOutcomeRecord(evidence)), version, nextStamp()),
+      );
+      return {
+        type: "write",
+        statements,
+        sourceAdvance: evidence.outcome === "purchased",
+        deliveries: [],
+        view: appShipmentView(state, purchaseId, { version, label: mapped.order, facts: parseStoredLabelFacts(labelOutcomeRecord(evidence)) }),
+      };
+    });
+  }
+
+  /** The processor's confirmed handoff under its assignment: every desk handoff gate, the label carrier, one order.fulfilled. */
+  async appConfirmHandoff(request: AppEvidenceRequest<HandoffEvidence>): Promise<AppEvidenceResponse> {
+    const evidence = request.evidence;
+    return this.appCommit(request, async (state, binding, purchaseId) => {
+      if (evidence.purchaseId !== purchaseId || (state.provider && state.provider.purchaseId !== purchaseId)) {
+        return { type: "refuse", code: "conflict" };
+      }
+      const labelCarrier = state.labelOutcome?.carrier ?? null;
+      if (state.shipment?.handoffState === "handed_off" || state.order.fulfillment === "handed_off") {
+        return labelCarrier === evidence.carrier
+          ? { type: "done", view: appShipmentView(state, purchaseId) }
+          : { type: "refuse", code: "carrier-mismatch" };
+      }
+      const prohibited = carrierEvidenceRefusal({ carrier: evidence.carrier, policy: this.policy, snapshotProhibited: state.prohibitedCarriers });
+      if (prohibited) return { type: "refuse", code: prohibited };
+      const readiness = this.readiness(state);
+      const code = handoffRefusal(readiness);
+      if (code) return { type: "refuse", code, holds: releaseHolds(readiness) };
+      if (state.shipment?.labelPurchaseState !== "purchased" || state.provider?.outcome !== "accepted") return { type: "refuse", code: "label" };
+      const mismatch = carrierEvidenceRefusal({
+        carrier: evidence.carrier,
+        policy: this.policy,
+        snapshotProhibited: state.prohibitedCarriers,
+        labelCarrier,
+      });
+      if (mismatch) return { type: "refuse", code: mismatch };
+      const version = state.order.eventVersion + 1;
+      const [first, ...rest] = this.handoffStatements(state, request.actor.actorId, version);
+      const predicate = appWritePredicate(binding, state.order);
       const plan: PlanStatements = {
         deliveries: [],
-        statements: [
-          {
-            sql: `UPDATE scrappy_commerce_orders
-              SET fulfillment_state = 'handed_off', event_version = event_version + 1
-              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
-                AND payment_state = 'captured' AND stock_state = 'confirmed'
-                AND fulfillment_state = 'ready' AND label_state IN ('purchased', 'printed')
-                AND EXISTS (
-                  SELECT 1 FROM scrappy_shipments
-                  WHERE tenant_id = ? AND stage = ? AND order_id = ?
-                    AND scope = 'whole-order' AND label_purchase_state = 'purchased' AND handoff_state = 'none'
-                )`,
-            params: [
-              state.order.tenantId,
-              state.order.stage,
-              state.order.orderId,
-              state.order.eventVersion,
-              state.order.tenantId,
-              state.order.stage,
-              state.order.orderId,
-            ],
-          },
-          {
-            sql: `UPDATE scrappy_shipments
-              SET handoff_state = 'handed_off'
-              WHERE tenant_id = ? AND stage = ? AND order_id = ?
-                AND scope = 'whole-order' AND label_purchase_state = 'purchased' AND handoff_state = 'none'
-                AND EXISTS (
-                  SELECT 1 FROM scrappy_commerce_orders
-                  WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
-                )`,
-            params: [
-              state.order.tenantId,
-              state.order.stage,
-              state.order.orderId,
-              state.order.tenantId,
-              state.order.stage,
-              state.order.orderId,
-              version,
-            ],
-          },
-          auditStatement(state, actor.actorId, "transition", state.order.fulfillment, "handed_off", version, stamp(this.now(), state.auditCount + 1)),
-          terminalTransitionExpiryStatement(state.order, version, new Date(this.now())),
-        ],
+        statements: [{ sql: `${first!.sql} AND ${predicate.sql}`, params: [...first!.params, ...predicate.params] }, ...rest],
       };
       await this.appendOrderFulfilled(plan, state, version);
-      return { type: "write", minimumChanges: 1, sourceAdvance: true, statements: plan.statements, deliveries: plan.deliveries };
+      return {
+        type: "write",
+        statements: plan.statements,
+        sourceAdvance: true,
+        deliveries: plan.deliveries,
+        view: appShipmentView(state, purchaseId, { version, handoff: "handed_off" }),
+      };
     });
   }
 
+  /**
+   * The app write path: the key ledger first, the assignment binding, the plan, then one batch whose
+   * first statement carries the install and assignment predicate and whose last records the key.
+   * A plan-time answer records the key alone. A batch that does not commit is re-classified.
+   */
+  private async appCommit(
+    request: AppEvidenceRequest<LabelOutcomeEvidence | HandoffEvidence>,
+    build: (state: LoadedOrder, binding: AppAssignmentBinding, purchaseId: string) => AppPlan | Promise<AppPlan>,
+  ): Promise<AppEvidenceResponse> {
+    const binding = appBinding(request.actor, request.evidence.assignmentId);
+    if (!binding) return appRefusal("denied");
+    if (!IDEMPOTENCY_KEY.test(request.idempotencyKey)) return appRefusal("malformed");
+    const { tenantId, stage } = request.actor;
+    const { orderId, idempotencyKey: key } = request;
+    if (!isOpaqueId(orderId)) return appRefusal("not-assigned");
+    const bodyHash = await computeBodyHash({ body: request.body, assignmentId: binding.assignmentId, orderId });
+    const prior = await this.priorResponse(binding.installId, key, bodyHash);
+    if (prior) return prior;
+    const state = await this.load(tenantId, stage, orderId);
+    const assigned = await this.assignmentRefusal(binding, tenantId, stage, orderId, state?.assignment ?? null);
+    if (assigned || !state) return appRefusal(assigned ?? "not-assigned");
+    const expected = request.evidence.expectedVersion;
+    if (expected !== undefined && state.order.eventVersion !== expected) return appRefusal("conflict");
+    const purchaseId = await purchaseIdFor(tenantId, stage, orderId);
+    let plan: AppPlan;
+    try {
+      plan = await build(state, binding, purchaseId);
+    } catch (error) {
+      if (error instanceof CommercePayloadRefused) return appRefusal("malformed");
+      throw error;
+    }
+    if (plan.type === "done") return this.recordAppAnswer(binding.installId, key, bodyHash, { status: 200, body: plan.view });
+    if (plan.type === "refuse") return this.recordAppAnswer(binding.installId, key, bodyHash, appRefusal(plan.code, plan.holds));
+    const response: AppEvidenceResponse = { status: 200, body: plan.view };
+    const fence = authorityFence(state.sourceAuthority, this.now(), plan.sourceAdvance);
+    const [first, ...rest] = plan.statements;
+    if (!first) return appRefusal("unavailable");
+    const changes = await this.write([
+      { sql: `${first.sql} AND (${fence.sql})`, params: [...first.params, ...fence.params] },
+      ...rest,
+      idempotencyInsertStatement({ installId: binding.installId, key, bodyHash, response, now: this.now() }),
+    ]);
+    if (changes && (changes[0] ?? 0) >= 1) {
+      await this.notifyCommitted(tenantId, plan.deliveries, changes);
+      return response;
+    }
+    return this.classifyUncommitted(binding, state, plan.sourceAdvance, key, bodyHash, changes === null);
+  }
+
+  /** Why an app batch did not commit, read once after it: install, scope, assignment, authority, key, version. */
+  private async classifyUncommitted(
+    binding: AppAssignmentBinding,
+    original: LoadedOrder,
+    sourceAdvance: boolean,
+    key: string,
+    bodyHash: string,
+    failed: boolean,
+  ): Promise<AppEvidenceResponse> {
+    const { tenantId, stage, orderId } = original.order;
+    const install = await this.db.get<{ status: string; scopes: string }>(
+      `SELECT status, scopes FROM app_installs WHERE install_id = ? AND tenant_id = ?`,
+      [binding.installId, tenantId],
+    );
+    if (!install || install.status !== "active") return appRefusal("invalid_token");
+    if (!scopeListIncludes(install.scopes, PROCESSOR_SCOPE)) return appRefusal("scope_denied");
+    const current = await this.load(tenantId, stage, orderId);
+    const assigned = await this.assignmentRefusal(binding, tenantId, stage, orderId, current?.assignment ?? null);
+    if (assigned || !current) return appRefusal(assigned ?? "not-assigned");
+    const fence = authorityFence(original.sourceAuthority, this.now(), sourceAdvance);
+    const fenced = await this.db.get<{ ok: number }>(
+      `SELECT 1 AS ok FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ? AND (${fence.sql})`,
+      [tenantId, stage, orderId, ...fence.params],
+    );
+    if (!fenced) return appRefusal(current.sourceHolds[0] ?? "source-check-pending");
+    const prior = await this.priorResponse(binding.installId, key, bodyHash);
+    if (prior) return prior;
+    return appRefusal(failed ? "unavailable" : "conflict");
+  }
+
+  /** A same-key request already answered: its recorded response, or idempotency-conflict for another body. */
+  private async priorResponse(installId: string, key: string, bodyHash: string): Promise<AppEvidenceResponse | null> {
+    const check = await checkIdempotency(this.ledger(), installId, key, bodyHash);
+    if (check.status === "proceed") return null;
+    if (check.status === "conflict") return appRefusal("idempotency-conflict");
+    return replayedResponse(check.responseBody) ?? appRefusal("idempotency-conflict");
+  }
+
+  /** Records a plan-time answer under its key; a same-key race answers with whatever won. */
+  private async recordAppAnswer(installId: string, key: string, bodyHash: string, response: AppEvidenceResponse): Promise<AppEvidenceResponse> {
+    let changes: number[];
+    try {
+      changes = await this.db.batch([idempotencyInsertStatement({ installId, key, bodyHash, response, now: this.now() })]);
+    } catch {
+      return appRefusal("unavailable");
+    }
+    if ((changes[0] ?? 0) >= 1) return response;
+    return (await this.priorResponse(installId, key, bodyHash)) ?? appRefusal("unavailable");
+  }
+
+  /** The order's assignment as the calling install sees it: null when its bound assignment is active. */
+  private async assignmentRefusal(
+    binding: AppAssignmentBinding,
+    tenantId: string,
+    stage: CommerceStage,
+    orderId: string,
+    open: OpenAssignment | null,
+  ): Promise<"not-assigned" | "assignment-ended" | "assignment-held" | null> {
+    if (open && open.installId === binding.installId) {
+      if (open.assignmentId !== binding.assignmentId) return "assignment-ended";
+      return open.state === "held" ? "assignment-held" : null;
+    }
+    const named = await this.db.get<{ n: number }>(
+      `SELECT 1 AS n FROM fulfillment_assignments WHERE tenant_id = ? AND stage = ? AND order_id = ? AND install_id = ? LIMIT 1`,
+      [tenantId, stage, orderId, binding.installId],
+    );
+    return named ? "assignment-ended" : "not-assigned";
+  }
+
+  /** The idempotency ledger over this store. */
+  private ledger(): Queryable {
+    const db = this.db;
+    return {
+      all: async <T,>(sql: string, ...params: unknown[]) => (await db.all(sql, params)) as T[],
+      first: async <T,>(sql: string, ...params: unknown[]) => ((await db.get(sql, params)) ?? null) as T | null,
+      run: async (sql: string, ...params: unknown[]) => {
+        await db.batch([{ sql, params }]);
+      },
+      exec: async () => {
+        throw new Error("storage");
+      },
+    };
+  }
+
+  /** The whole-order handoff: order CAS, shipment move, transition audit, and the contact expiry. */
+  private handoffStatements(state: LoadedOrder, actorId: string, version: number): SqlStatement[] {
+    const { order } = state;
+    return [
+      {
+        sql: `UPDATE scrappy_commerce_orders
+          SET fulfillment_state = 'handed_off', event_version = event_version + 1
+          WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+            AND payment_state = 'captured' AND stock_state = 'confirmed'
+            AND fulfillment_state = 'ready' AND label_state IN ('purchased', 'printed')
+            AND EXISTS (
+              SELECT 1 FROM scrappy_shipments
+              WHERE tenant_id = ? AND stage = ? AND order_id = ?
+                AND scope = 'whole-order' AND label_purchase_state = 'purchased' AND handoff_state = 'none'
+            )`,
+        params: [order.tenantId, order.stage, order.orderId, order.eventVersion, order.tenantId, order.stage, order.orderId],
+      },
+      {
+        sql: `UPDATE scrappy_shipments
+          SET handoff_state = 'handed_off'
+          WHERE tenant_id = ? AND stage = ? AND order_id = ?
+            AND scope = 'whole-order' AND label_purchase_state = 'purchased' AND handoff_state = 'none'
+            AND EXISTS (
+              SELECT 1 FROM scrappy_commerce_orders
+              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+            )`,
+        params: [order.tenantId, order.stage, order.orderId, order.tenantId, order.stage, order.orderId, version],
+      },
+      auditStatement(state, actorId, "transition", order.fulfillment, "handed_off", version, stamp(this.now(), state.auditCount + 1)),
+      terminalTransitionExpiryStatement(order, version, new Date(this.now())),
+    ];
+  }
+
   /** Returns are not automated. This records nothing. */
   createReturn(actor: FulfillmentActor, _orderId: string): FulfillmentResult<never> {
     if (!this.commandScope(actor)) return refuse("denied");
     return refuse("returns-not-automated");
   }
 
+  /** Merchant and desk commands. An install actor (`app:`) commands only through the app methods. */
   private commandScope(actor: FulfillmentActor): { tenantId: string; stage: CommerceStage } | null {
-    if (!isOpaqueId(actor.actorId)) return null;
+    if (!isOpaqueId(actor.actorId) || actor.actorId.startsWith(APP_ACTOR_PREFIX)) return null;
     const scope = { tenantId: actor.tenantId, stage: actor.stage };
     return actorMayCommand(actor, scope) ? scope : null;
   }
@@ -1122,6 +1408,8 @@ export class FulfillmentService {
     actorId: string,
     version: number,
     nextStamp: () => string,
+    /** The assigned processor's first label outcome opens the shipment under its own assignment. */
+    options: { assigned?: boolean } = {},
   ): Promise<SqlStatement[]> {
     const purchaseId = state.provider?.purchaseId ?? (await purchaseIdFor(state.order.tenantId, state.order.stage, state.order.orderId));
     const intent = {
@@ -1144,12 +1432,12 @@ export class FulfillmentService {
             SELECT 1 FROM scrappy_shipments AS s
             WHERE s.tenant_id = o.tenant_id AND s.stage = o.stage AND s.order_id = o.order_id
           )
-          AND NOT EXISTS (
+          AND (? = 1 OR NOT EXISTS (
             SELECT 1 FROM fulfillment_assignments AS fa
             WHERE fa.tenant_id = o.tenant_id AND fa.stage = o.stage AND fa.order_id = o.order_id
               AND fa.state IN ('active', 'held')
-          )`,
-        params: [order.tenantId, order.stage, order.orderId, version],
+          ))`,
+        params: [order.tenantId, order.stage, order.orderId, version, options.assigned ? 1 : 0],
       },
       {
         sql: `INSERT INTO scrappy_provider_operations (
@@ -1659,7 +1947,7 @@ export class FulfillmentService {
       else if (audit.kind === "operator-hold") operatorHold = audit.to_state === "open";
       else if (audit.kind === "pending-cancel") cancelPending = audit.to_state === "open";
       else if (audit.kind === "packing-slip") packingSlip = parseSlip(parseJson(audit.to_state));
-      else if (audit.kind === "label-outcome") labelOutcome = parseLabelOutcome(parseJson(audit.to_state));
+      else if (audit.kind === "label-outcome") labelOutcome = parseStoredLabelFacts(parseJson(audit.to_state));
       else if (audit.kind === "label-intent") {
         const intent = parseJson(audit.to_state);
         if (isRecord(intent)) {
@@ -1759,6 +2047,10 @@ export class FulfillmentService {
           carrierAccountId: loaded.carrierAccountId,
           adultSignatureRequired: loaded.adultSignatureRequired,
           prohibitedCarriers: loaded.prohibitedCarriers,
+          carrier: labelOutcome?.carrier ?? null,
+          service: labelOutcome?.service ?? null,
+          trackingNumber: labelOutcome?.trackingNumber ?? null,
+          trackingUrl: labelOutcome?.trackingUrl ?? null,
         }
       : null;
     return loaded;
@@ -1990,10 +2282,45 @@ function parseSlip(value: unknown): PackingSlip | null {
   };
 }
 
-function parseLabelOutcome(value: unknown): { adultSignature: "accepted" | "refused" | "absent" } | null {
-  if (!isRecord(value)) return null;
-  if (value.adultSignature !== "accepted" && value.adultSignature !== "refused" && value.adultSignature !== "absent") return null;
-  return { adultSignature: value.adultSignature };
+const APP_ACTOR_PREFIX = "app:";
+
+/** The binding an install actor writes under; null for any other actor or an unusable id. */
+function appBinding(actor: FulfillmentActor, assignmentId: string): AppAssignmentBinding | null {
+  if (actor.role !== "caller" || !actor.actorId.startsWith(APP_ACTOR_PREFIX)) return null;
+  const installId = actor.actorId.slice(APP_ACTOR_PREFIX.length);
+  if (!isOpaqueId(installId) || !isOpaqueId(assignmentId)) return null;
+  if (!actorMayCommand(actor, { tenantId: actor.tenantId, stage: actor.stage })) return null;
+  return { installId, assignmentId };
+}
+
+function scopeListIncludes(scopes: unknown, scope: string): boolean {
+  const parsed = typeof scopes === "string" ? parseJson(scopes) : null;
+  return Array.isArray(parsed) && parsed.includes(scope);
+}
+
+/** The minimized app view of `state`, or of its planned successor when `next` is given. */
+function appShipmentView(
+  state: LoadedOrder,
+  purchaseId: string,
+  next: { version?: number; label?: LabelState; handoff?: AppShipmentView["handoff"]; facts?: StoredLabelFacts | null } = {},
+): AppShipmentView {
+  const handoff =
+    next.handoff ??
+    (state.shipment?.handoffState === "handed_off" || state.order.fulfillment === "handed_off"
+      ? "handed_off"
+      : state.order.fulfillment === "UNKNOWN"
+        ? "unknown"
+        : "none");
+  const facts = next.facts === undefined ? state.labelOutcome : next.facts;
+  return {
+    orderId: state.order.orderId,
+    version: next.version ?? state.order.eventVersion,
+    label: next.label ?? state.order.label,
+    handoff,
+    purchaseId,
+    ...(facts?.carrier ? { carrier: facts.carrier } : {}),
+    ...(facts?.trackingNumber && facts.trackingUrl ? { tracking: { number: facts.trackingNumber, url: facts.trackingUrl } } : {}),
+  };
 }
 
 /** A stored audit state that is not JSON parses to null, which every caller fails closed on. */

package/apps/storefront/src/lib/fulfillment/readiness.ts

@@ -20,6 +20,7 @@ import {
 } from "@tot/public-runtime";
 import type { SourceReadiness } from "../orders/data/sourceAuthorityStore.js";
 import { COMPLIANCE_RULE_PROFILES } from "@/config/compliance/rulesets";
+import { canonicalCarrier, carrierProhibited, type CarrierCode } from "./carrierEvidence.js";
 
 export const RELEASE_HOLDS = [
   "source-check-pending",
@@ -167,3 +168,20 @@ export function carrierSelectionRefusal(
   if (policy.prohibitedCarriers.some((item) => item.toUpperCase() === normalized)) return "carrier-prohibited";
   return "vendor-not-selected";
 }
+
+/**
+ * A processor's reported carrier. Prohibited when it is in the current policy's set or the order's
+ * label-intent snapshot; a handoff carrier must equal the carrier its label was bought with.
+ */
+export function carrierEvidenceRefusal(input: {
+  carrier: CarrierCode;
+  policy: CarrierPolicy;
+  snapshotProhibited: readonly string[];
+  labelCarrier?: string | null;
+}): "carrier-prohibited" | "carrier-mismatch" | null {
+  if (carrierProhibited(input.carrier, input.policy.prohibitedCarriers, input.snapshotProhibited)) return "carrier-prohibited";
+  if (input.labelCarrier !== undefined && (input.labelCarrier === null || canonicalCarrier(input.labelCarrier) !== input.carrier)) {
+    return "carrier-mismatch";
+  }
+  return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "6.5.2",
+  "version": "6.5.3",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",