@tokenoftrust/storefront-runner 6.5.1 → 6.5.3

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/apps/storefront/src/lib/integrations/apps/appContactAuthority.ts

@@ -0,0 +1,27 @@
+/**
+ * Whether a verified Private App request may ask for order contact at all: the only source of the
+ * `app` contact-reader kind. It is separate from `contactReaderAuthority`, whose outcomes stay
+ * owner, staff or none, so no human contact route can ever see an app.
+ *
+ * Every predicate is required: an install record, active, on the host tenant, the token's subject
+ * naming it, and the scope in both the install grant and the token. Consent, assignment and quota
+ * are decided by the audit insert, not here.
+ */
+export type AppContactAuthority = { kind: "app"; installId: string; tenantId: string } | { kind: "none" };
+
+export interface AppContactAuthorityInput {
+  install: { installId: string; tenantId: string; status: string; scopes: readonly string[] } | null | undefined;
+  claims: { sub: string; scopes: readonly string[] } | null | undefined;
+  hostResource: string;
+  scope: string;
+}
+
+export function appContactAuthority(input: AppContactAuthorityInput): AppContactAuthority {
+  const { install, claims, scope } = input;
+  const host = input.hostResource.trim();
+  if (!install || !claims || !host || !scope) return { kind: "none" };
+  if (install.status !== "active" || install.tenantId !== host) return { kind: "none" };
+  if (!install.installId || claims.sub !== install.installId) return { kind: "none" };
+  if (!install.scopes.includes(scope) || !claims.scopes.includes(scope)) return { kind: "none" };
+  return { kind: "app", installId: install.installId, tenantId: host };
+}