@openlup/platform 0.21.0 → 0.22.0

package/src/fulfillment/providerStockSyncWorker.ts

@@ -0,0 +1,222 @@
+import { aggregateAtpCompatibleStock, emptyLocal, stockMovementWindow } from "./providerStockAvailability.js";
+import type { FulfillmentStockSyncPort, FulfillmentStockSyncProvider, LocalStock, StockSnapshot, StockMovement } from "./contracts/index.js";
+type Threshold = Parameters<FulfillmentStockSyncPort["resolveLowStockEvidence"]>[0]["activeThresholdKinds"][number];
+interface StockSyncResult {
+  ok: boolean; checked: number; updated: number; mismatches: number; reservationCoverage: number;
+  unclassified: number; lowStock: number; movements: number; replayed: number; failures: number;
+  providerCalls: number; readBacks: number; skipped: boolean; syncRunId: string;
+  lastMovementOccurredAt: string | null; reason?: string;
+}
+export async function runFulfillmentStockSyncWorker(input: {
+  port: FulfillmentStockSyncPort;
+  provider: FulfillmentStockSyncProvider;
+  movementBatchSize: number;
+  staleSyncThresholdHours?: number;
+  now?: () => Date;
+  compatibility: {
+    syncRunId(now: Date): string; staleEvidenceSku: string; timeZone: string;
+    currentKey(run: string, sku: string): string; snapshotKey(run: string, sku: string): string;
+    lowStockKey(sku: string, threshold: Threshold): string; staleKey(lastSyncedAt: string): string;
+  };
+}): Promise<StockSyncResult> {
+  const now = input.now?.() ?? new Date();
+  const staleThresholdHours = input.staleSyncThresholdHours && input.staleSyncThresholdHours > 0
+    ? input.staleSyncThresholdHours
+    : 6;
+  const syncRunId = input.compatibility.syncRunId(now);
+  const result: StockSyncResult = {
+    ok: true,
+    checked: 0,
+    updated: 0,
+    mismatches: 0,
+    reservationCoverage: 0,
+    unclassified: 0,
+    lowStock: 0,
+    movements: 0,
+    replayed: 0,
+    failures: 0,
+    providerCalls: 0,
+    readBacks: 0,
+    skipped: false,
+    syncRunId,
+    lastMovementOccurredAt: null,
+  };
+
+  const previousCursor = await input.port.readCursor();
+
+  // Stale-sync alert: if the last successful sync aged past the threshold, open a stale_sync
+  // low-stock evidence row (evidence/warn — never blocks sales); a healthy run resolves it
+  // below. A never-synced state (no prior cursor) is not "stale".
+  const lastSyncedMs = previousCursor?.lastStockSyncedAt ? Date.parse(previousCursor.lastStockSyncedAt) : null;
+  const staleGapHours =
+    lastSyncedMs !== null && !Number.isNaN(lastSyncedMs) ? (now.getTime() - lastSyncedMs) / 3_600_000 : null;
+  const syncIsStale = staleGapHours !== null && staleGapHours >= staleThresholdHours;
+  if (syncIsStale) {
+    await input.port.recordLowStockEvidence({
+      requestKey: input.compatibility.staleKey(previousCursor!.lastStockSyncedAt!),
+      skuRef: input.compatibility.staleEvidenceSku,
+      thresholdKind: "stale_sync",
+      severity: "warning",
+      providerForSaleQuantity: 0,
+      localAvailableQuantity: 0,
+      syncRunId,
+    });
+  }
+
+  await input.port.recordCursor({
+    status: "running",
+    lastStockSyncedAt: null,
+    lastMovementOccurredAt: null,
+    continuation: { nextRef: null, startLocalDate: null, endLocalDate: null },
+    coverageGapSkus: [], refusal: null,
+  });
+
+  const [localStock, providerStock] = await Promise.all([
+    input.port.readLocalInventoryStock(now.toISOString()),
+    input.provider.getStock(),
+  ]);
+  result.providerCalls += 1;
+
+  const stockItems = providerStock.filter((item) => item.skuRef.trim());
+  const skus = [...new Set(stockItems.map((item) => item.skuRef))];
+  const [inventoryClasses, activeReservations] = await Promise.all([
+    input.port.readSkuInventoryClasses(skus),
+    input.port.readActiveReservations(skus, now.toISOString()),
+  ]);
+
+  const movements = await input.provider.getStockMovements({ ...stockMovementWindow(previousCursor, now, input.compatibility.timeZone), size: input.movementBatchSize });
+  result.providerCalls += 1;
+  result.movements = movements.length;
+  result.lastMovementOccurredAt = latestOccurredAt(movements);
+
+  const localBySku = aggregateAtpCompatibleStock(localStock, now);
+  const coverageCandidates: Array<{
+    stock: StockSnapshot;
+    local: LocalStock;
+    activeReserved: number;
+  }> = [];
+  const currentCoverageGapSkus = new Set<string>();
+  const packagingSkus = new Set<string>();
+  const previousCoverageGapSkus = previousCursor?.status === "succeeded"
+    ? readStringSet(previousCursor.coverageGapSkus)
+    : new Set<string>();
+
+  for (const stock of stockItems) {
+    try {
+      const local = localBySku.get(stock.skuRef) ?? emptyLocal(stock.skuRef);
+      const inventoryClass = inventoryClasses.get(stock.skuRef) ?? null;
+      const activeReserved = activeReservations.get(stock.skuRef) ?? 0;
+      const staleAfter = new Date(now.getTime() + staleThresholdHours * 3_600_000).toISOString();
+      const current = await input.port.recordProviderStockCurrent({
+        requestKey: input.compatibility.currentKey(syncRunId, stock.skuRef),
+        snapshot: stock, inventoryClass, lastSyncedAt: now.toISOString(), staleAfter,
+      });
+      const snapshot = await input.port.recordStockSnapshot({
+        requestKey: input.compatibility.snapshotKey(syncRunId, stock.skuRef),
+        snapshot: stock, local, mismatchKind: "none", inventoryClass,
+      });
+
+      result.checked += 1;
+      result.updated += (snapshot.replayed ? 0 : 1) + (current.replayed ? 0 : 1);
+      if (snapshot.replayed) result.replayed += 1;
+      if (current.replayed) result.replayed += 1;
+      if (snapshot.readBack) result.readBacks += 1;
+      if (current.readBack) result.readBacks += 1;
+      if (inventoryClass === null) result.unclassified += 1;
+      if (inventoryClass === "packaging") packagingSkus.add(stock.skuRef);
+      if (inventoryClass === "sellable") {
+        coverageCandidates.push({ stock, local, activeReserved });
+        if (activeReserved > stock.forSaleQuantity) currentCoverageGapSkus.add(stock.skuRef);
+      }
+    } catch (error) {
+      result.ok = false;
+      result.failures += 1;
+      result.reason = result.reason ?? "stock_sync_operation_failed";
+    }
+  }
+
+  if (result.ok) {
+    for (const { stock, local, activeReserved } of coverageCandidates) {
+      const localAvailable = availableQuantity(local);
+      const confirmedCoverageGap = currentCoverageGapSkus.has(stock.skuRef) && previousCoverageGapSkus.has(stock.skuRef);
+      const lowStockSignals = lowStockSignalsFor(stock, local, activeReserved, confirmedCoverageGap);
+      const activeThresholdKinds: Threshold[] = lowStockSignals.map((signal) => signal.thresholdKind);
+      if (currentCoverageGapSkus.has(stock.skuRef) && !activeThresholdKinds.includes("reservation_coverage")) {
+        activeThresholdKinds.push("reservation_coverage");
+      }
+      for (const signal of lowStockSignals) {
+        const evidence = await input.port.recordLowStockEvidence({
+          requestKey: input.compatibility.lowStockKey(stock.skuRef, signal.thresholdKind),
+          skuRef: stock.skuRef, thresholdKind: signal.thresholdKind, severity: signal.severity,
+          providerForSaleQuantity: stock.forSaleQuantity, localAvailableQuantity: localAvailable, syncRunId,
+        });
+        if (evidence.replayed) result.replayed += 1;
+        result.lowStock += evidence.replayed ? 0 : 1;
+        if (signal.thresholdKind === "reservation_coverage") result.reservationCoverage += 1;
+      }
+      await input.port.resolveLowStockEvidence({
+        skuRef: stock.skuRef,
+        activeThresholdKinds,
+        syncRunId,
+      });
+    }
+    for (const sku of packagingSkus) {
+      await input.port.resolveLowStockEvidence({
+        skuRef: sku,
+        activeThresholdKinds: [],
+        syncRunId,
+      });
+    }
+  }
+
+  await input.port.recordCursor({
+    status: result.ok ? "succeeded" : "failed",
+    lastStockSyncedAt: result.ok ? now.toISOString() : null,
+    lastMovementOccurredAt: result.lastMovementOccurredAt,
+    continuation: { nextRef: null, startLocalDate: null, endLocalDate: null },
+    coverageGapSkus: result.ok ? [...currentCoverageGapSkus].sort() : [],
+    refusal: result.ok ? null : { reason: "io_failure", phase: "sync", retryable: true },
+  });
+
+  // Recovery: a healthy run (succeeded, not itself stale) closes any open stale_sync row.
+  if (result.ok && !syncIsStale) {
+    await input.port.resolveLowStockEvidence({
+      skuRef: input.compatibility.staleEvidenceSku,
+      activeThresholdKinds: [],
+      syncRunId,
+
+    });
+  }
+
+  return result;
+}
+
+function lowStockSignalsFor(
+  stock: StockSnapshot,
+  local: LocalStock,
+  activeReserved: number,
+  confirmedCoverageGap: boolean,
+): Array<{ thresholdKind: "safety_stock" | "reservation_coverage"; severity: "warning" | "critical" }> {
+  const signals: Array<{ thresholdKind: "safety_stock" | "reservation_coverage"; severity: "warning" | "critical" }> = [];
+  const remainingAfterReservations = Math.max(0, stock.forSaleQuantity - activeReserved);
+  if (local.safetyStock > 0 && remainingAfterReservations <= local.safetyStock) {
+    signals.push({ thresholdKind: "safety_stock", severity: remainingAfterReservations <= 0 ? "critical" : "warning" });
+  }
+  if (confirmedCoverageGap) signals.push({ thresholdKind: "reservation_coverage", severity: "critical" });
+  return signals;
+}
+
+function readStringSet(value: unknown): Set<string> {
+  return new Set(Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.trim().length > 0) : []);
+}
+
+function availableQuantity(balance: LocalStock): number {
+  return Math.max(0, balance.onHand - balance.reserved - balance.unavailable - balance.safetyStock);
+}
+
+function latestOccurredAt(movements: StockMovement[]): string | null {
+  return movements
+    .map((movement) => movement.occurredAt)
+    .filter((value): value is string => Boolean(value))
+    .sort((a, b) => Date.parse(b) - Date.parse(a))[0] ?? null;
+}

package/src/fulfillment/providerTrackingReferences.ts

@@ -0,0 +1,31 @@
+import type { FulfillmentTrackingReference } from "./contracts/index.js";
+
+export function trackingReferenceComplete(ref: FulfillmentTrackingReference): boolean {
+  return Boolean(ref.carrierRef && ref.publicUrl && ref.serviceRef);
+}
+/** Provider evidence wins as a unit; private carrier/URL codecs stay injected. */
+export function enrichTrackingReference(
+  ref: FulfillmentTrackingReference,
+  deliveryCarrier: { carrierRef: string | null; serviceRef: string | null } | null,
+  codecs: {
+    normalizeCarrier(input: { carrierRef: string | null; serviceRef: string | null }): string | null;
+    publicUrl(carrierRef: string | null, trackingNumber: string): string | null;
+  },
+): FulfillmentTrackingReference {
+  const providerCarrier = ref.carrierRef ?? codecs.normalizeCarrier(ref);
+  const carrierRef = providerCarrier ?? codecs.normalizeCarrier({ carrierRef: deliveryCarrier?.carrierRef ?? null, serviceRef: deliveryCarrier?.serviceRef ?? null });
+  return { trackingNumber: ref.trackingNumber, publicUrl: ref.publicUrl ?? codecs.publicUrl(carrierRef, ref.trackingNumber),
+    carrierRef, serviceRef: ref.serviceRef ?? (providerCarrier ? null : deliveryCarrier?.serviceRef ?? null) };
+}
+/** First occurrence wins, including its selection, after trimming the number. */
+export function uniqueTrackingReferences(refs: readonly FulfillmentTrackingReference[]): FulfillmentTrackingReference[] {
+  const seen = new Set<string>();
+  const result: FulfillmentTrackingReference[] = [];
+  for (const ref of refs) {
+    const trackingNumber = ref.trackingNumber.trim();
+    if (!trackingNumber || seen.has(trackingNumber)) continue;
+    seen.add(trackingNumber);
+    result.push({ trackingNumber, publicUrl: ref.publicUrl ?? null, carrierRef: ref.carrierRef ?? null, serviceRef: ref.serviceRef ?? null });
+  }
+  return result;
+}

package/src/fulfillment/replacementRefusals.ts

@@ -0,0 +1,43 @@
+export const FULFILLMENT_REPLACEMENT_COMMAND_REFUSALS = [
+  "invalid_input",
+  "idempotency_conflict",
+  "order_not_found",
+  "order_not_replaceable",
+  "missing_client",
+  "missing_shipping_address",
+  "shipping_address_not_found",
+  "payment_not_succeeded",
+  "subscription_cycle_not_paid",
+  "no_parcel_to_replace",
+  "undispatched_replacement_exists",
+  "missing_order_items",
+  "missing_catalog_sku",
+  "missing_inventory_reservation",
+  "blocked_by_payment_not_succeeded_hold",
+  "blocked_by_inventory_review_hold",
+  "blocked_by_risk_review_hold",
+  "blocked_by_address_review_hold",
+  "blocked_by_manual_support_hold",
+] as const;
+
+export const FULFILLMENT_REPLACEMENT_RESERVATION_REFUSALS = [
+  "inventory_external_provider_insufficient_available_stock",
+  "inventory_external_provider_stock_stale",
+  "inventory_external_provider_stock_missing",
+  "inventory_external_provider_sku_not_found",
+  "inventory_external_provider_location_missing",
+  "inventory_reservation_insufficient_available_stock",
+  "inventory_reservation_allocation_incomplete",
+  "inventory_reservation_payment_status_not_reservable",
+  "inventory_reservation_invalid_quantity",
+] as const;
+
+export const UNSPECIFIED_FULFILLMENT_REPLACEMENT_REFUSAL = "unspecified_refusal";
+
+export const FULFILLMENT_REPLACEMENT_REFUSALS = [
+  ...FULFILLMENT_REPLACEMENT_COMMAND_REFUSALS,
+  ...FULFILLMENT_REPLACEMENT_RESERVATION_REFUSALS,
+  UNSPECIFIED_FULFILLMENT_REPLACEMENT_REFUSAL,
+] as const;
+
+export type FulfillmentReplacementRefusal = (typeof FULFILLMENT_REPLACEMENT_REFUSALS)[number];

package/src/fulfillment/replacementShipmentHandler.ts

@@ -0,0 +1,47 @@
+import { adminCommerceOrderRequestReplacementShipmentRequestSchema, adminCommerceOrderRequestReplacementShipmentResponseSchema } from './handlerSchemas.js';
+import { authorize, CommerceFulfillmentConflictError, isNativeUnsupported, type BaseDeps, type FulfillmentHandlerRequest, type FulfillmentHandlerResponder } from './handlerSupport.js';
+import type { FulfillmentReplacementPort } from './contracts/replacement.js';
+export function createAdminCommerceOrderRequestReplacementShipmentHandler<Response>({
+  authorizeAdmin,
+  respond,
+  omsPort,
+}: BaseDeps<Response> & {
+  omsPort: FulfillmentReplacementPort;
+}) {
+  const { sendMethodNotAllowed } = respond;
+  return async function handler(req: FulfillmentHandlerRequest, res: Response): Promise<void> {
+    if (req.method !== "POST") return sendMethodNotAllowed(res, ["POST"]);
+    const auth = await authorize(req, res, authorizeAdmin, respond);
+    if (!auth) return;
+
+    const request = parseOmsRequest(res, respond, adminCommerceOrderRequestReplacementShipmentRequestSchema, req.body ?? {}, "Invalid admin commerce replacement shipment request");
+    if (request === undefined) return;
+
+    await sendOmsMutationResponse(
+      res,
+      respond,
+      () => omsPort.requestReplacementShipment({ ...request, actorUserId: auth.userId }),
+      adminCommerceOrderRequestReplacementShipmentResponseSchema,
+      "Admin commerce replacement shipment returned invalid response",
+      "Admin commerce replacement shipment failed",
+    );
+  };
+}
+
+function parseOmsRequest<Response, T>(res: Response, respond: FulfillmentHandlerResponder<Response>, schema: { safeParse(input: unknown): { success: true; data: T } | { success: false; error: { flatten(): unknown } } }, input: unknown, message: string): T | undefined {
+  const request = schema.safeParse(input);
+  if (!request.success) { respond.sendBffError(res, 'BAD_REQUEST', message, { details: request.error.flatten() }); return undefined; }
+  return request.data;
+}
+async function sendOmsMutationResponse<Response>(res: Response, respond: FulfillmentHandlerResponder<Response>, action: () => Promise<unknown>, schema: typeof adminCommerceOrderRequestReplacementShipmentResponseSchema, invalidMessage: string, failureMessage: string) {
+  try {
+    const result = await action();
+    if (isNativeUnsupported(result)) { respond.sendBffError(res, 'UPSTREAM_UNAVAILABLE', 'Native fulfillment operation unsupported', { details: result }); return; }
+    const response = schema.safeParse(result);
+    if (!response.success) { respond.sendBffError(res, 'INVALID_RESPONSE', invalidMessage); return; }
+    respond.sendBffSuccess(res, response.data);
+  } catch (error) {
+    if (error instanceof CommerceFulfillmentConflictError) { respond.sendBffError(res, 'CONFLICT', error.message, { details: error.details }); return; }
+    respond.sendBffError(res, 'UPSTREAM_UNAVAILABLE', failureMessage);
+  }
+}

package/src/fulfillment/schemaCapabilities.ts

@@ -0,0 +1,7 @@
+/** Sparse projections require the full canonical graph and a trusted native binding. */
+export const FULFILLMENT_NATIVE_CAPABILITIES = {
+  shipment: 'supported', commandFence: 'supported', deliveryAlignment: 'supported',
+  stockEvidence: 'supported', observationPersistence: 'supported',
+  localInventoryBalances: 'host_required', dispatchContactPreparation: 'host_required',
+  productPacks: 'unsupported', providerAccess: 'unsupported', automaticReplacementConfirmation: 'unsupported',
+} as const;

package/src/fulfillment/shipmentsOverviewHandler.ts

@@ -0,0 +1,73 @@
+import { isNativeUnsupported, type FulfillmentHandlerRequest, type FulfillmentHandlerResponder } from './handlerSupport.js';
+import { z } from 'zod';
+import type { FulfillmentShipmentsOverviewPort, FulfillmentShipmentsOverviewResponse } from './contracts/read.js';
+
+const adminShipmentsOverviewRequestSchema = z.object({
+  shippedFilter: z.enum(['today', '7d', '30d', 'all']).default('7d'),
+});
+
+export interface FulfillmentShipmentsOverviewHandlerDeps<Response> {
+  respond: FulfillmentHandlerResponder<Response>;
+  overviewPort: FulfillmentShipmentsOverviewPort;
+  responseSchema: { safeParse(input: unknown): { success: true; data: FulfillmentShipmentsOverviewResponse } | { success: false } };
+  authorizeAdmin: (req: FulfillmentHandlerRequest) => Promise<boolean>;
+}
+
+export function createFulfillmentShipmentsOverviewHandler<Response>({
+  respond,
+  overviewPort,
+  responseSchema: adminShipmentsOverviewResponseSchema,
+  authorizeAdmin,
+}: FulfillmentShipmentsOverviewHandlerDeps<Response>) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async function handler(req: FulfillmentHandlerRequest, res: Response): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    let authorized = false;
+    try {
+      authorized = await authorizeAdmin(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return;
+    }
+
+    if (!authorized) {
+      sendBffError(res, "UNAUTHORIZED", "Admin session required");
+      return;
+    }
+
+    const request = adminShipmentsOverviewRequestSchema.safeParse({
+      shippedFilter: scalarQuery(req.query.shippedFilter),
+    });
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid shipments overview request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await overviewPort.getShipmentsOverview(request.data);
+      if (isNativeUnsupported(result)) {
+        sendBffError(res, "UPSTREAM_UNAVAILABLE", "Native fulfillment operation unsupported", { details: result });
+        return;
+      }
+      const response = adminShipmentsOverviewResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Shipments overview returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Shipments overview read failed");
+    }
+  };
+}
+
+function scalarQuery(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}

package/src/fulfillment/statusMap.ts

@@ -0,0 +1,2 @@
+export { FULFILLMENT_STATUS_MAP, CANONICAL_LOCAL_FULFILLMENT_STATUSES, CUSTOMER_STEP_SEQUENCE, canonicalStatusToken, stepForToken, customerStepFromSignals, phaseIndexForStep, stepLabelKey, timelineLabelForStep, trackingPhaseKeyForStep, stepUsesTruckIcon } from "@openlup/core/fulfillment";
+export type { FulfillmentStatusStage, FulfillmentStatusMap } from "@openlup/core/fulfillment";

package/src/fulfillment/trackingProgress.ts

@@ -0,0 +1 @@
+export { fulfillmentProgressPresentation } from "@openlup/core/fulfillment";

package/src/fulfillment/verifiedIngress.ts

@@ -0,0 +1,80 @@
+import type { FulfillmentObservation, FulfillmentObservationPort, FulfillmentRefusal } from "./contracts/index.js";
+import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+import { observationStatusPolicy, projectObservation } from "./observationProjection.js";
+import { uniqueTrackingReferences } from "./providerTrackingReferences.js";
+
+type EffectInput = Parameters<typeof applyFulfillmentObservationEffects<FulfillmentObservation["fact"]["canonicalStatus"], "in_transit" | "delivered">>[0];
+type DispatchRef = { orderRef: string; fulfillmentRef: string; dispatchRef: string; externalRef: string | null };
+/** Adapter verification owns auth-before-parse; the host owns durable replay. */
+export async function verifyAndNormalizeFulfillmentObservation(input: {
+  enabled: boolean;
+  provider: FulfillmentObservationPort;
+  verification: Parameters<FulfillmentObservationPort["verifyAndNormalize"]>[0];
+  localPersistence: {
+    /** G17: atomic insert by eventKey; retries keep the first stored firstReceivedAt. */
+    recordObservation(observation: FulfillmentObservation): Promise<{ replayed: boolean }>;
+    /** Idempotent; only called after completion or a classified superseding conflict. */
+    markProcessed(eventKey: string, outcome: { status: "processed" | "ignored"; refusal?: FulfillmentRefusal }): Promise<void>;
+  };
+  lifecycle: {
+    findDispatchRef(observation: FulfillmentObservation): Promise<DispatchRef | null>;
+    acknowledgeDispatchAcceptance(ref: DispatchRef, observation: FulfillmentObservation): Promise<void>;
+    recordStatusEvidence(ref: DispatchRef, observation: FulfillmentObservation): Promise<{ replayed: boolean }>;
+    effects: EffectInput["port"];
+    keys: { stock(ref: string): string; handoff(ref: string): string; tracking(eventKey: string, number: string): string };
+    issueAccountingInvoice?(ref: string): Promise<void>;
+    classifyFailure(error: unknown): "stock_contention" | "state_conflict" | "other";
+    annotateStockContention?(eventKey: string, fulfillmentRef: string): Promise<void>;
+  };
+}): Promise<{ kind: "refused"; refusal: FulfillmentRefusal } | { kind: "processed" | "ignored" | "superseded"; observation: FulfillmentObservation; replayed: boolean; trackingRefs: number; trackingReadBacks: number }> {
+  if (!input.enabled) return { kind: "refused", refusal: { reason: "disabled", phase: "verify", retryable: false } };
+  const verified = await input.provider.verifyAndNormalize(input.verification);
+  if (verified.kind === "refused") return verified;
+  const observation = projectObservation(verified.observation);
+  const inbound = await input.localPersistence.recordObservation(observation);
+  const ref = await input.lifecycle.findDispatchRef(observation);
+  if (!ref) {
+    await input.localPersistence.markProcessed(observation.eventKey, { status: "ignored", refusal: { reason: "local_missing", phase: "apply", retryable: false } });
+    return { kind: "ignored", observation, replayed: inbound.replayed, trackingRefs: 0, trackingReadBacks: 0 };
+  }
+  const externalRef = observation.correlation.externalRef?.trim() || ref.externalRef?.trim();
+  if (!externalRef) throw new TypeError("fulfillment_dispatch_acceptance_external_ref_missing");
+  await input.lifecycle.acknowledgeDispatchAcceptance(ref, observation);
+  const statusEvidence = await input.lifecycle.recordStatusEvidence(ref, observation);
+  let trackingRefs = 0;
+  let trackingReadBacks = 0;
+  const effectPort: EffectInput["port"] = {
+    ...input.lifecycle.effects,
+    async markProviderStockConsumed(request) {
+      try { return await input.lifecycle.effects.markProviderStockConsumed(request); }
+      catch (error) {
+        if (input.lifecycle.classifyFailure(error) === "stock_contention") {
+          try {
+            await input.lifecycle.annotateStockContention?.(observation.eventKey, ref.fulfillmentRef);
+          } catch { /* Annotation is best-effort; preserve the original stock failure. */ }
+        }
+        throw error;
+      }
+    },
+  };
+  const localStatus = observation.fact.canonicalStatus;
+  const effects: EffectInput = {
+    port: effectPort, localStatus, ids: { orderId: ref.orderRef, fulfillmentOrderId: ref.fulfillmentRef }, observation,
+    trackingRefs: uniqueTrackingReferences(observation.trackingRefs).map(tracking => ({ trackingNumber: tracking.trackingNumber, trackingUrl: tracking.publicUrl, carrierKind: tracking.carrierRef, service: tracking.serviceRef })),
+    stockIdempotencyKey: input.lifecycle.keys.stock(ref.fulfillmentRef), handoffIdempotencyKey: input.lifecycle.keys.handoff(ref.fulfillmentRef),
+    trackingIdempotencyKey: number => input.lifecycle.keys.tracking(observation.eventKey, number),
+    issueAccountingInvoice: input.lifecycle.issueAccountingInvoice ? () => input.lifecycle.issueAccountingInvoice!(ref.fulfillmentRef) : undefined,
+    onTrackingRecorded: result => { trackingRefs += result.replayed ? 0 : 1; trackingReadBacks += result.readBack ? 1 : 0; },
+  };
+  if (!observationStatusPolicy.handsOver(localStatus)) await applyFulfillmentObservationEffects({ ...effects, trackingRefs: [] }, observationStatusPolicy);
+  else {
+    try { await applyFulfillmentObservationEffects(effects, observationStatusPolicy); }
+    catch (error) {
+      if (input.lifecycle.classifyFailure(error) !== "state_conflict") throw error;
+      await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
+      return { kind: "superseded", observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+    }
+  }
+  await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
+  return { kind: "processed", observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+}

package/src/payments/stripe/index.ts

@@ -233,3 +233,33 @@ function mapVerifiedStripeEvent(raw: Record<string, unknown>): VerificationResul
   return { ...result, fingerprint: createHash("sha256").update(JSON.stringify(result)).digest("hex"),
     providerAuditPayload: normalized.rawPayload };
 }
+
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/stripe/stripeAdapterFactory.ts`.
+ */
+export { createStripeSandboxPaymentExecutionAdapter } from "./stripeSandboxPaymentExecutionAdapter.js";
+
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/runtime/paymentProviderReadbackRegistry.ts`.
+ */
+export { createStripePaymentReconciliationProvider } from "./stripePaymentReconciliationProvider.js";
+
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/infra/stripe/stripeApiClient.ts`.
+ */
+export { mapStripeIntent } from "./intentMapper.js";
+
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/infra/stripe/stripeApiClient.ts`.
+ */
+export { mapSetupIntent } from "./intentMapper.js";
+
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/paymentRecoveryGuidance.ts`.
+ */
+export { normalizeStripeFailureEvidence } from "./stripeFailureEvidence.js";

package/src/payments/tpay/index.ts

@@ -255,3 +255,39 @@ function mapVerifiedTpayEvent(rawBody: string, occurred: string | null, mode: "l
   return { ...evidence, fingerprint: createHash("sha256").update(JSON.stringify(evidence)).digest("hex"),
     providerAuditPayload: payload };
 }
+
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/tpay/tpayAdapterFactory.ts`.
+ */
+export { createTpayPaymentExecutionAdapter } from "./tpayPaymentExecutionAdapter.js";
+
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/runtime/paymentProviderReadbackRegistry.ts`.
+ */
+export { createTpayPaymentReconciliationProvider } from "./tpayPaymentReconciliationProvider.js";
+
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/bff/commerce/tpay-channels.ts`.
+ */
+export { createTpayHttpClient } from "./tpayHttpClient.js";
+
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/paymentRecoveryGuidance.ts`.
+ */
+export { normalizeTpayFailureEvidence } from "./tpayFailureEvidence.js";
+
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/supabase/payment/tpaySubscriptionActivation.ts`.
+ */
+export { aliasValue } from "./tpayCreateTransactionInput.js";
+
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/shared/preparedProviderAttempt.ts`.
+ */
+export { ProviderAttemptPreDispatchError } from "./preparedProviderAttempt.js";