@openlup/platform 0.21.0 → 0.23.0

package/src/fulfillment/fulfillmentObservationEffects.ts

@@ -0,0 +1,86 @@
+import type { FulfillmentObservation } from "./contracts/index.js";
+/** Ledger effects for an already accepted observation; acceptance and retry belong to the caller. */
+interface FulfillmentObservationPort<TrackingStatus> {
+  markProviderStockConsumed(input: { idempotencyKey: string; fulfillmentOrderId: string }): Promise<{ replayed: boolean }>;
+  markHandedOver(input: { idempotencyKey: string; fulfillmentOrderId: string; suppressDispatched: boolean }): Promise<{ replayed: boolean }>;
+  recordTrackingReference(input: {
+    idempotencyKey: string;
+    orderId: string;
+    fulfillmentOrderId: string;
+    trackingNumber: string;
+    trackingUrl: string | null;
+    carrierKind: string | null;
+    service: string | null;
+    status: TrackingStatus;
+    observation: FulfillmentObservation;
+  }): Promise<{ replayed: boolean; readBack: boolean }>;
+}
+
+interface FulfillmentObservationTrackingReference {
+  trackingNumber: string;
+  trackingUrl?: string | null;
+  carrierKind?: string | null;
+  service?: string | null;
+}
+
+
+interface FulfillmentObservationInput<LocalStatus, TrackingStatus> {
+  port: FulfillmentObservationPort<TrackingStatus>;
+  localStatus: LocalStatus;
+  ids: { orderId: string; fulfillmentOrderId: string };
+  observation: FulfillmentObservation;
+  trackingRefs: readonly FulfillmentObservationTrackingReference[];
+  stockIdempotencyKey: string;
+  handoffIdempotencyKey: string;
+  trackingIdempotencyKey: (trackingNumber: string) => string;
+  issueAccountingInvoice?: () => Promise<void>;
+  onReplayed?: () => void;
+  onTrackingRecorded?: (result: { replayed: boolean; readBack: boolean }) => void;
+}
+
+/** Pure status decisions/projection; the mechanism owns every effect and await. */
+interface FulfillmentObservationStatusPolicy<LocalStatus, TrackingStatus> {
+  consumesStock(status: LocalStatus): boolean;
+  handsOver(status: LocalStatus): boolean;
+  suppressDispatched(status: LocalStatus): boolean;
+  trackingStatus(status: LocalStatus): TrackingStatus;
+}
+
+/** Stock → durable handover → every tracking reference → optional invoice. No catches or retries. */
+export async function applyFulfillmentObservationEffects<LocalStatus, TrackingStatus>(
+  input: FulfillmentObservationInput<LocalStatus, TrackingStatus>,
+  policy: FulfillmentObservationStatusPolicy<LocalStatus, TrackingStatus>,
+): Promise<void> {
+  const { fulfillmentOrderId, orderId } = input.ids;
+  if (policy.consumesStock(input.localStatus)) {
+    const consumed = await input.port.markProviderStockConsumed({
+      idempotencyKey: input.stockIdempotencyKey,
+      fulfillmentOrderId,
+    });
+    if (consumed.replayed) input.onReplayed?.();
+  }
+  if (!policy.handsOver(input.localStatus)) return;
+
+  const handoff = await input.port.markHandedOver({
+    idempotencyKey: input.handoffIdempotencyKey,
+    fulfillmentOrderId,
+    suppressDispatched: policy.suppressDispatched(input.localStatus),
+  });
+  if (handoff.replayed) input.onReplayed?.();
+
+  for (const trackingRef of input.trackingRefs) {
+    const tracking = await input.port.recordTrackingReference({
+      idempotencyKey: input.trackingIdempotencyKey(trackingRef.trackingNumber),
+      orderId,
+      fulfillmentOrderId,
+      trackingNumber: trackingRef.trackingNumber,
+      trackingUrl: trackingRef.trackingUrl ?? null,
+      carrierKind: trackingRef.carrierKind ?? null,
+      service: trackingRef.service ?? null,
+      status: policy.trackingStatus(input.localStatus),
+      observation: input.observation,
+    });
+    input.onTrackingRecorded?.(tracking);
+  }
+  await input.issueAccountingInvoice?.();
+}

package/src/fulfillment/handlerSchemas.ts

@@ -0,0 +1,255 @@
+import { z } from 'zod';
+import { PAYMENT_INTENT_STATUSES } from '@openlup/core/payment';
+const OMS_FULFILLMENT_BLOCK_REASONS = ['order_not_paid','payment_not_succeeded','subscription_cycle_not_paid','active_hold','missing_shipping_address','inventory_review','risk_review'] as const;
+const OMS_INVENTORY_STATUSES = ['not_checked','reserved','missing','released','expired','consumed','review_required'] as const;
+export const COMMERCE_FULFILLMENT_CONTRACT_VERSION = "commerce.fulfillment.v0";
+
+export const COMMERCE_FULFILLMENT_STATUSES = [
+  "created",
+  "packed",
+  "label_pending",
+  "label_created",
+  "handed_over",
+  "in_transit",
+  "delivered",
+  "exception",
+  "cancelled",
+] as const;
+
+export const COMMERCE_FULFILLMENT_OPERATION_TYPES = [
+  "created",
+  "packed",
+  "provider_attempt_recorded",
+  "label_created",
+  "handed_over",
+  "tracking_event_recorded",
+  "cancelled",
+] as const;
+
+export const COMMERCE_FULFILLMENT_PROVIDER_ATTEMPT_STATUSES = [
+  "recorded",
+  "succeeded",
+  "failed",
+] as const;
+
+const uuidSchema = z.guid();
+const datetimeSchema = z.string().datetime({ offset: true });
+
+export const commerceFulfillmentStatusSchema = z.enum(COMMERCE_FULFILLMENT_STATUSES);
+export const commerceFulfillmentOperationTypeSchema = z.enum(COMMERCE_FULFILLMENT_OPERATION_TYPES);
+export const commerceFulfillmentProviderAttemptStatusSchema = z.enum(
+  COMMERCE_FULFILLMENT_PROVIDER_ATTEMPT_STATUSES,
+);
+export const commerceFulfillmentPaymentStatusSchema = z.enum(["not_started", ...PAYMENT_INTENT_STATUSES]);
+export const commerceFulfillmentInventoryStatusSchema = z.enum(OMS_INVENTORY_STATUSES);
+export const commerceFulfillmentBlockReasonSchema = z.enum(OMS_FULFILLMENT_BLOCK_REASONS);
+
+export const commerceFulfillmentShippingAddressSnapshotSchema = z.object({
+  addressId: uuidSchema,
+  clientId: uuidSchema,
+  label: z.string().nullable(),
+  line1: z.string().trim().min(1),
+  line2: z.string().nullable(),
+  city: z.string().trim().min(1),
+  postalCode: z.string().trim().min(1),
+  country: z.string().trim().min(2).max(3),
+}).strict();
+
+export const commerceFulfillmentLineSchema = z.object({
+  id: uuidSchema.nullable(),
+  orderItemId: uuidSchema,
+  skuId: uuidSchema,
+  sku: z.string().trim().min(1),
+  title: z.string().trim().min(1).nullable(),
+  quantity: z.number().int().positive(),
+  inventoryReservationIds: z.array(uuidSchema),
+  productSnapshot: z.record(z.string(), z.unknown()),
+}).strict();
+
+export const commerceFulfillmentPaymentSummarySchema = z.object({
+  paymentIntentId: uuidSchema,
+  paymentStatus: commerceFulfillmentPaymentStatusSchema,
+  providerPaymentId: z.string().nullable(),
+}).strict();
+
+export const commerceFulfillmentInventorySummarySchema = z.object({
+  status: commerceFulfillmentInventoryStatusSchema,
+  reservationId: uuidSchema.nullable(),
+  reservationStatus: z.enum(["reserved", "released", "consumed", "expired"]).nullable(),
+  expiresAt: datetimeSchema.nullable(),
+  locationId: uuidSchema.nullable(),
+  locationCode: z.string().nullable(),
+}).strict();
+
+export const commerceFulfillmentOmsEligibilitySchema = z.object({
+  allowed: z.boolean(),
+  reason: commerceFulfillmentBlockReasonSchema.nullable(),
+}).strict();
+
+export const commerceFulfillmentOperationSchema = z.object({
+  id: uuidSchema,
+  type: commerceFulfillmentOperationTypeSchema,
+  occurredAt: datetimeSchema,
+  actorUserId: uuidSchema.nullable(),
+  payload: z.record(z.string(), z.unknown()),
+}).strict();
+
+export const commerceFulfillmentOrderSchema = z.object({
+  id: uuidSchema,
+  orderId: uuidSchema,
+  clientId: uuidSchema.nullable(),
+  status: commerceFulfillmentStatusSchema,
+  providerKind: z.string().trim().min(1).nullable(),
+  providerTrackingId: z.string().trim().min(1).nullable(),
+  shippingAddress: commerceFulfillmentShippingAddressSnapshotSchema,
+  lines: z.array(commerceFulfillmentLineSchema).min(1),
+  payment: commerceFulfillmentPaymentSummarySchema,
+  inventory: commerceFulfillmentInventorySummarySchema,
+  omsEligibility: commerceFulfillmentOmsEligibilitySchema,
+  latestOperation: commerceFulfillmentOperationSchema.nullable(),
+  createdAt: datetimeSchema,
+  updatedAt: datetimeSchema,
+}).strict();
+
+export const adminCommerceFulfillmentOrdersListRequestSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(25),
+  status: commerceFulfillmentStatusSchema.optional(),
+}).strict();
+
+export const adminCommerceFulfillmentOrderDetailRequestSchema = z
+  .object({
+    fulfillmentOrderId: uuidSchema.optional(),
+    orderId: uuidSchema.optional(),
+  })
+  .strict()
+  .refine((request) => request.fulfillmentOrderId || request.orderId, {
+    message: "fulfillmentOrderId or orderId is required",
+  });
+
+export const adminCommerceFulfillmentCreateRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  orderId: uuidSchema,
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export const adminCommerceFulfillmentRecordProviderAttemptRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  fulfillmentOrderId: uuidSchema,
+  providerKind: z.string().trim().min(1),
+  status: commerceFulfillmentProviderAttemptStatusSchema,
+  requestPayload: z.record(z.string(), z.unknown()).default({}),
+  responsePayload: z.record(z.string(), z.unknown()).default({}),
+  error: z.string().trim().min(1).nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export const adminCommerceFulfillmentRecordLabelRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  fulfillmentOrderId: uuidSchema,
+  providerKind: z.string().trim().min(1),
+  providerTrackingId: z.string().trim().min(1),
+  labelUrl: z.string().trim().min(1).nullable().optional(),
+  deliveryEstimateDays: z.number().int().nonnegative().nullable().optional(),
+  rawProviderPayload: z.record(z.string(), z.unknown()).default({}),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export const adminCommerceFulfillmentHandOffRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  fulfillmentOrderId: uuidSchema,
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export const adminCommerceFulfillmentTrackingEventRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  fulfillmentOrderId: uuidSchema,
+  status: z.enum(["in_transit", "delivered", "exception"]),
+  providerTrackingId: z.string().trim().min(1).optional(),
+  rawEvent: z.record(z.string(), z.unknown()).default({}),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export const adminCommerceFulfillmentCancelRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  fulfillmentOrderId: uuidSchema,
+  reason: z.string().trim().min(1).max(240),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export const adminCommerceFulfillmentOrdersListResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_FULFILLMENT_CONTRACT_VERSION),
+  orders: z.array(commerceFulfillmentOrderSchema),
+  totalCount: z.number().int().min(0),
+  page: z.number().int().min(1),
+  pageSize: z.number().int().min(1),
+}).strict();
+
+export const adminCommerceFulfillmentOrderDetailResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_FULFILLMENT_CONTRACT_VERSION),
+  order: commerceFulfillmentOrderSchema,
+}).strict();
+
+export const adminCommerceFulfillmentMutationResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_FULFILLMENT_CONTRACT_VERSION),
+  fulfillmentOrderId: uuidSchema,
+  orderId: uuidSchema,
+  status: commerceFulfillmentStatusSchema,
+  replayed: z.boolean(),
+}).strict();
+
+export type AdminCommerceFulfillmentOrdersListRequest = z.infer<typeof adminCommerceFulfillmentOrdersListRequestSchema>;
+export type AdminCommerceFulfillmentOrderDetailRequest = z.infer<typeof adminCommerceFulfillmentOrderDetailRequestSchema>;
+export type AdminCommerceFulfillmentCreateRequest = z.infer<typeof adminCommerceFulfillmentCreateRequestSchema>;
+export type AdminCommerceFulfillmentRecordProviderAttemptRequest = z.input<typeof adminCommerceFulfillmentRecordProviderAttemptRequestSchema>;
+export type AdminCommerceFulfillmentRecordLabelRequest = z.input<typeof adminCommerceFulfillmentRecordLabelRequestSchema>;
+export type AdminCommerceFulfillmentHandOffRequest = z.infer<typeof adminCommerceFulfillmentHandOffRequestSchema>;
+export type AdminCommerceFulfillmentTrackingEventRequest = z.input<typeof adminCommerceFulfillmentTrackingEventRequestSchema>;
+export type AdminCommerceFulfillmentCancelRequest = z.infer<typeof adminCommerceFulfillmentCancelRequestSchema>;
+export type AdminCommerceFulfillmentOrdersListResponse = z.infer<typeof adminCommerceFulfillmentOrdersListResponseSchema>;
+export type AdminCommerceFulfillmentOrderDetailResponse = z.infer<typeof adminCommerceFulfillmentOrderDetailResponseSchema>;
+export type AdminCommerceFulfillmentMutationResponse = z.infer<typeof adminCommerceFulfillmentMutationResponseSchema>;
+export type CommerceFulfillmentOrder = z.infer<typeof commerceFulfillmentOrderSchema>;
+export type CommerceFulfillmentStatus = z.infer<typeof commerceFulfillmentStatusSchema>;
+export type CommerceFulfillmentOperationType = z.infer<typeof commerceFulfillmentOperationTypeSchema>;
+
+export const adminCommerceOrderRequestReplacementShipmentRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  orderId: uuidSchema,
+  reason: z.enum(['damaged', 'lost', 'returned_undelivered', 'other']),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+export const omsOperationTypeSchema = z.enum([
+  "hold_created",
+  "hold_released",
+  "fulfillment_reviewed",
+  "support_note",
+  "shipping_address_updated",
+  "order_marked_refunded",
+  "order_cancelled_manual",
+  "replacement_shipment_requested",
+]);
+export const omsOrderOperationSchema = z.object({
+  id: uuidSchema,
+  orderId: uuidSchema,
+  type: omsOperationTypeSchema,
+  holdId: uuidSchema.nullable(),
+  actorUserId: uuidSchema.nullable(),
+  occurredAt: datetimeSchema,
+  payload: z.record(z.string(), z.unknown()),
+});
+
+export const adminCommerceOrderRequestReplacementShipmentResponseSchema = z.object({
+  contractVersion: z.literal('commerce.v0'),
+  operation: omsOrderOperationSchema,
+  replacement: z.object({
+    fulfillmentOrderId: z.string().uuid(),
+    orderId: z.string().uuid(),
+    sequenceNo: z.number().int().min(1),
+    replacesFulfillmentOrderId: z.string().uuid(),
+    reason: z.enum(["damaged", "lost", "returned_undelivered", "other"]),
+    status: z.string(),
+  }),
+  releasedHoldIds: z.array(z.string().uuid()).default([]),
+  replayed: z.boolean(),
+});

package/src/fulfillment/handlerSupport.ts

@@ -0,0 +1,25 @@
+import type { FulfillmentNativeUnsupported } from './contracts/nativeUnsupported.js';
+export interface FulfillmentHandlerRequest { method?: string; query: Record<string, string | string[] | undefined>; body?: unknown }
+export interface FulfillmentHandlerResponder<Response> {
+  sendMethodNotAllowed(res: Response, methods: readonly string[]): void;
+  sendBffSuccess(res: Response, data: unknown): void;
+  sendBffError(res: Response, code: 'UNAUTHORIZED' | 'FORBIDDEN' | 'BAD_REQUEST' | 'INVALID_RESPONSE' | 'NOT_FOUND' | 'CONFLICT' | 'UPSTREAM_UNAVAILABLE', message: string, options?: { details: unknown }): void;
+}
+export type AdminAuthResult = { ok: false; code: 'UNAUTHORIZED' | 'FORBIDDEN'; message: string } | { ok: true; userId: string };
+export interface BaseDeps<Response> {
+  authorizeAdmin(req: FulfillmentHandlerRequest): Promise<AdminAuthResult>;
+  respond: FulfillmentHandlerResponder<Response>;
+}
+export function isNativeUnsupported(value: unknown): value is FulfillmentNativeUnsupported {
+  return typeof value === 'object' && value !== null && 'kind' in value && value.kind === 'native_unsupported';
+}
+export class CommerceFulfillmentConflictError extends Error {
+  constructor(message = 'Commerce fulfillment conflict', readonly details: Record<string, unknown> = {}) { super(message); this.name = 'CommerceFulfillmentConflictError'; }
+}
+export async function authorize<Response>(req: FulfillmentHandlerRequest, res: Response, authorizeAdmin: BaseDeps<Response>['authorizeAdmin'], respond: FulfillmentHandlerResponder<Response>) {
+  try {
+    const authorization = await authorizeAdmin(req);
+    if (authorization.ok === false) { respond.sendBffError(res, authorization.code, authorization.message); return null; }
+    return { userId: authorization.userId };
+  } catch { respond.sendBffError(res, 'UPSTREAM_UNAVAILABLE', 'Admin authorization failed'); return null; }
+}

package/src/fulfillment/index.ts

@@ -0,0 +1,39 @@
+export { FULFILLMENT_STATUS_MAP, CANONICAL_LOCAL_FULFILLMENT_STATUSES, CUSTOMER_STEP_SEQUENCE, canonicalStatusToken, stepForToken, customerStepFromSignals, phaseIndexForStep, stepLabelKey, timelineLabelForStep, trackingPhaseKeyForStep, stepUsesTruckIcon } from "./statusMap.js";
+export { parseFulfillmentFact, parseFulfillmentTransitionConflict } from "./normalizedFulfillmentFacts.js";
+export { readFulfillmentCapabilities } from "./providerCapabilities.js";
+export { createOutboxOrderPaidFulfillmentHandler } from "./paidHandoff.js";
+export { collectPaidFulfillmentRecoveryCandidates } from "./paidFulfillmentRecovery.js";
+export { runFulfillmentDispatchWorker } from "./providerDispatchWorker.js";
+export { createFulfillmentCommandLedger } from "./providerCommandLedger.js";
+export type { FulfillmentIngressCounts, FulfillmentIngressResult } from "./verifiedIngress.js";
+export { verifyAndNormalizeFulfillmentObservation, fulfillmentIngressHttpResult } from "./verifiedIngress.js";
+export { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+export { reconcileFulfillmentObservations, runFulfillmentReconciliationPage } from "./providerReconciliationWorker.js";
+export { runFulfillmentStockSyncWorker } from "./providerStockSyncWorker.js";
+export { runFulfillmentProductSyncWorker } from "./providerProductSyncWorker.js";
+export { createFulfillmentLowStockEvidenceHandler } from "./lowStockEvidenceHandler.js";
+export { createProductReconciliationEvidenceHandler } from "./productReconciliationEvidenceHandler.js";
+export { runFulfillmentAdapterConformance } from "./adapterConformance.js";
+export { createPostgresFulfillmentShipmentSpinePort } from './postgresShipmentSpine.js';
+export { createPostgresFulfillmentLowStockEvidencePort } from './postgresEvidenceReadPort.js';
+export { createPostgresFulfillmentStockSyncPort } from './postgresStockSyncPort.js';
+export { createPostgresPaidFulfillmentRecoveryOpsPort } from './postgresPaidFulfillmentRecovery.js';
+export { createPostgresFulfillmentDispatchStore } from './postgresDispatchStore.js';
+export { createPostgresPaidFulfillmentHandoffStore } from './postgresPaidHandoffStore.js';
+export { createPostgresDeliveryAlignmentPort } from './postgresDeliveryAlignment.js';
+export { readDeliveryAlignment } from './deliveryAlignmentReadModel.js';
+export { FULFILLMENT_NATIVE_CAPABILITIES } from './schemaCapabilities.js';
+export { FULFILLMENT_MIGRATIONS } from './migrations.js';
+
+export { createAdminCommerceFulfillmentOrdersListHandler, createAdminCommerceFulfillmentOrderDetailHandler, createAdminCommerceFulfillmentCreateOrderHandler, createAdminCommerceFulfillmentRecordProviderAttemptHandler, createAdminCommerceFulfillmentRecordLabelHandler, createAdminCommerceFulfillmentHandOffHandler, createAdminCommerceFulfillmentTrackingEventHandler, createAdminCommerceFulfillmentCancelOrderHandler } from './commerceFulfillmentHandlers.js';
+export { createAdminCommerceOrderRequestReplacementShipmentHandler } from './replacementShipmentHandler.js';
+export { CommerceFulfillmentConflictError } from './handlerSupport.js';
+export { readFulfillmentDelay } from './delayReadModel.js';
+export { readFulfillmentLabel, cleanupFulfillmentLabel } from './labelLifecycle.js';
+export { currentParcel, currentParcelFor, currentParcelPerOrder, currentParcelFirst, belongsToParcel, rowsForParcel, parcelSequenceNo, compareParcelPrecedence } from './currentFulfillmentParcel.js';
+export { FULFILLMENT_NATIVE_UNSUPPORTED, createNativeUnsupportedFulfillmentPorts } from './nativeUnsupported.js';
+export { FULFILLMENT_REPLACEMENT_REFUSALS } from './replacementRefusals.js';
+export { buildCommerceFulfillmentOrdersListResponse, buildCommerceFulfillmentOrderDetailResponse } from './commerceFulfillmentReadModel.js';
+export { createFulfillmentShipmentsOverviewHandler } from './shipmentsOverviewHandler.js';
+export { fulfillmentProgressPresentation } from './trackingProgress.js';
+export { createFulfillmentServices } from './bindings.js';

package/src/fulfillment/labelLifecycle.ts

@@ -0,0 +1,11 @@
+import type { FulfillmentLabelPort, LabelDocument } from './contracts/label.js';
+/** Storage-only read: a missing cached label never proves the parcel absent. Signed URLs are transient. */
+export async function readFulfillmentLabel(port: Pick<FulfillmentLabelPort, 'read'>, document: LabelDocument | null) {
+  if (!document) return { kind: 'refused' as const, refusal: { reason: 'local_missing' as const, phase: 'readback' as const, retryable: false } };
+  return port.read(document);
+}
+/** Provider and storage deletion remain host-owned; canProceed never asserts either deletion. */
+type LabelCleanupInput = Parameters<FulfillmentLabelPort['void']>[0] & { actorUserId: string; idempotencyKey: string };
+export async function cleanupFulfillmentLabel(port: { void(input: LabelCleanupInput): ReturnType<FulfillmentLabelPort['void']> }, input: LabelCleanupInput) {
+  return port.void(input);
+}

package/src/fulfillment/lowStockEvidenceHandler.ts

@@ -0,0 +1,60 @@
+/** Read-only evidence boundary; parsing remains with the owning host schema. */
+export function createFulfillmentLowStockEvidenceHandler<Request extends { method?: string; query: Record<string, string | string[] | undefined> }, Response, Query, Result>({ evidencePort, authorizeAdmin, requestSchema, responseSchema, respond }: {
+  evidencePort: { getLowStockEvidence(query: Query): Promise<unknown> };
+  authorizeAdmin(request: Request): Promise<boolean>;
+  requestSchema: { safeParse(input: unknown): { success: true; data: Query } | { success: false; error: { flatten(): unknown } } };
+  responseSchema: { safeParse(input: unknown): { success: true; data: Result } | { success: false } };
+  respond: {
+    sendBffError(res: Response, code: "UPSTREAM_UNAVAILABLE" | "UNAUTHORIZED" | "BAD_REQUEST" | "INVALID_RESPONSE", message: string, options?: { details: unknown }): void;
+    sendBffSuccess(res: Response, data: Result): void;
+    sendMethodNotAllowed(res: Response, methods: readonly string[]): void;
+  };
+}) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async function handler(req: Request, 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 = requestSchema.safeParse({
+      statusFilter: scalarQuery(req.query.statusFilter),
+    });
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid low-stock evidence request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await evidencePort.getLowStockEvidence(request.data);
+      const response = responseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Low-stock evidence returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Low-stock evidence read failed");
+    }
+  };
+}
+
+function scalarQuery(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}

package/src/fulfillment/migrations.ts

@@ -0,0 +1,9 @@
+/** Byte-identical sparse projections; install the complete canonical catalogue. */
+export const FULFILLMENT_MIGRATIONS = [
+  { position: 5, catalogPath: "db/platform/migrations/20260808210000_fulfillment_shipment_rail.sql", sha256: "eb5824551903717f3868690909fcc2cb6a7f845abe5cb19bd4cff13103b1383d", url: new URL("../../sql/20260808210000_fulfillment_shipment_rail.sql", import.meta.url) },
+  { position: 27, catalogPath: "db/platform/migrations/20260814000000_fulfillment_stock_evidence.sql", sha256: "df20c2491cb0196b4e28d19e7578c95bfa5c87b8f89fb0b6284c0e0695a3cc1d", url: new URL("../../sql/20260814000000_fulfillment_stock_evidence.sql", import.meta.url) },
+  { position: 51, catalogPath: "db/platform/migrations/20260819150000_fulfillment_shipment_sequence.sql", sha256: "906706cf66a6a555aa1219b12eb674d937eaa099abde6da18766310af43aaa9f", url: new URL("../../sql/20260819150000_fulfillment_shipment_sequence.sql", import.meta.url) },
+  { position: 73, catalogPath: "db/platform/migrations/20261022080000_fulfillment_command_ledger.sql", sha256: "c6806906cdb0b6931b29f7a5c7c800016e98d04e6ea956f3c1e219a6cdb7e9d1", url: new URL("../../sql/20261022080000_fulfillment_command_ledger.sql", import.meta.url) },
+  { position: 74, catalogPath: "db/platform/migrations/20261022090000_fulfillment_delivery_alignment.sql", sha256: "d9966ae79fe77a0feae8317dc5b46ef2d8196dd0790b1cd0ee1b06ab58061499", url: new URL("../../sql/20261022090000_fulfillment_delivery_alignment.sql", import.meta.url) },
+  { position: 76, catalogPath: "db/platform/migrations/20261022165000_fulfillment_stock_evidence_replay_reopen.sql", sha256: "6d132dec2820047f4e337bcf752b3d884600ccc12de03887fe6d6aa5575bc1db", url: new URL("../../sql/20261022165000_fulfillment_stock_evidence_replay_reopen.sql", import.meta.url) },
+] as const;

package/src/fulfillment/nativeUnsupported.ts

@@ -0,0 +1,23 @@
+import type { FulfillmentCommerceReadPort, FulfillmentShipmentsOverviewPort } from './contracts/read.js';
+import type { FulfillmentNativeUnsupported } from './contracts/nativeUnsupported.js';
+import type { FulfillmentReplacementPort } from './contracts/replacement.js';
+import type { FulfillmentOperatorMutationPort } from './contracts/operator.js';
+import type { FulfillmentCustomerAlignmentRowsReader } from './contracts/customerAlignment.js';
+export const FULFILLMENT_NATIVE_UNSUPPORTED: FulfillmentNativeUnsupported = Object.freeze({ kind: 'native_unsupported', reason: 'host_binding_required', retryable: false });
+/** Deliberately has no executor: unsupported native parity can never make a partial write. */
+export function createNativeUnsupportedFulfillmentPorts(): FulfillmentReplacementPort & FulfillmentOperatorMutationPort & FulfillmentCommerceReadPort & FulfillmentShipmentsOverviewPort & { readCustomerAlignmentRows: FulfillmentCustomerAlignmentRowsReader } {
+  const unsupported = async () => FULFILLMENT_NATIVE_UNSUPPORTED;
+  return {
+    requestReplacementShipment: unsupported,
+    createCommerceFulfillmentOrder: unsupported,
+    recordCommerceFulfillmentProviderAttempt: unsupported,
+    recordCommerceFulfillmentLabel: unsupported,
+    handOffCommerceFulfillmentOrder: unsupported,
+    recordCommerceFulfillmentTrackingEvent: unsupported,
+    cancelCommerceFulfillmentOrder: unsupported,
+    readCustomerAlignmentRows: unsupported,
+    listCommerceFulfillmentOrders: unsupported,
+    getCommerceFulfillmentOrderDetail: unsupported,
+    getShipmentsOverview: unsupported,
+  };
+}

package/src/fulfillment/normalizedFulfillmentFacts.ts

@@ -0,0 +1,2 @@
+export { isCanonicalLocalFulfillmentStatus, parseFulfillmentFact, parseFulfillmentTransitionConflict } from "@openlup/core/fulfillment";
+export type { CanonicalNormalizedFulfillmentFact as NormalizedFulfillmentFact, CanonicalNormalizedFulfillmentFactV1 as NormalizedFulfillmentFactV1, CanonicalNormalizedFulfillmentFactV0 as NormalizedFulfillmentFactV0, CanonicalCompatibleNormalizedFulfillmentFact as CompatibleNormalizedFulfillmentFact, CanonicalFulfillmentTransitionSnapshot as FulfillmentTransitionSnapshot, CanonicalTransitionConflict as TransitionConflict } from "@openlup/core/fulfillment";

package/src/fulfillment/observationProjection.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation, FulfillmentObservationCodecs } from "./contracts/index.js";
+import { parseFulfillmentFact } from "./normalizedFulfillmentFacts.js";
+import { admittedReference, durableStrings, reference } from "./dispatchProjection.js";
+import { FULFILLMENT_STATUS_MAP } from "./statusMap.js";
+
+type Privacy = ReturnType<typeof durableStrings>;
+const timestamp = z.iso.datetime({ offset: true });
+export function projectCorrelation(value: FulfillmentObservation["correlation"], privacy = durableStrings(), codecs: FulfillmentObservationCodecs = {}): FulfillmentObservation["correlation"] {
+  const token = (value: string | null) => privacy.token(value, text => admittedReference(text, codecs.approveReference));
+  return { orderRef: value.orderRef, fulfillmentRef: value.fulfillmentRef, externalRef: token(value.externalRef),
+    orderNumber: token(value.orderNumber), providerFulfillmentRef: token(value.providerFulfillmentRef), parcelRef: value.parcelRef };
+}
+
+export function projectProviderStatus(value: NonNullable<FulfillmentObservation["providerStatus"]>, privacy = durableStrings()): NonNullable<FulfillmentObservation["providerStatus"]> {
+  return { primary: privacy.token(value.primary), subStatus: privacy.token(value.subStatus) };
+}
+export type PollEvidence = Pick<FulfillmentObservation, "correlation" | "eventKey" | "providerStatus" | "diagnostics">;
+function pollEvidence(value: PollEvidence, privacy: Privacy, codecs: FulfillmentObservationCodecs = {}): PollEvidence {
+  // Host identities and keys composed from admitted parts are already authoritative.
+  return { eventKey: value.eventKey, correlation: projectCorrelation(value.correlation, privacy, codecs),
+    ...(value.providerStatus ? { providerStatus: projectProviderStatus(value.providerStatus, privacy) } : {}) };
+}
+/** Unknown-status quarantine/ACK evidence has the same privacy boundary as observations. */
+export function projectPollEvidence(value: PollEvidence): PollEvidence {
+  const privacy = durableStrings(value.diagnostics?.redactedFieldCount);
+  const safe = pollEvidence(value, privacy);
+  return { ...safe, ...(privacy.redactedFieldCount ? { diagnostics: { redactedFieldCount: privacy.redactedFieldCount } } : {}) };
+}
+
+/** One URL policy: strict default, optional adopter codec, and approval at every sink. */
+export function publicTrackingUrl(value: string, approve?: (url: string) => boolean, codec?: (url: string) => string | null): string | null {
+  try {
+    const candidate = codec ? codec(value) : value;
+    if (!candidate) return null;
+    const url = new URL(candidate);
+    return url.protocol === "https:" && !url.username && !url.password && (codec || (!url.search && !url.hash)) && approve?.(url.href) ? url.href : null;
+  } catch { return null; }
+}
+export function projectTrackingReference(value: FulfillmentObservation["trackingRefs"][number], privacy = durableStrings(), approveTrackingUrl?: (url: string) => boolean, codecs: FulfillmentObservationCodecs = {}) {
+  const token = (value: string | null) => privacy.token(value, text => admittedReference(text, codecs.approveReference));
+  const trackingNumber = token(value.trackingNumber);
+  if (trackingNumber === null) return null;
+  const serviceRef = token(value.serviceRef);
+  // Even an opaque-looking derived carrier is unsafe when its service was refused.
+  const carrierRef = privacy.token(value.carrierRef, text => value.serviceRef !== null && serviceRef === null ? null : reference(text));
+  return { trackingNumber, carrierRef, serviceRef,
+    publicUrl: privacy.token(value.publicUrl, url => publicTrackingUrl(url, approveTrackingUrl, codecs.trackingUrl)) };
+}
+
+/** New boundary projection: arbitrary adapter properties are never durable. */
+export function projectObservation(value: FulfillmentObservation, approveTrackingUrl?: (url: string) => boolean, codecs: FulfillmentObservationCodecs = {}): FulfillmentObservation {
+  const privacy = durableStrings(value.diagnostics?.redactedFieldCount), token = privacy.token;
+  const diagnostics: NonNullable<FulfillmentObservation["diagnostics"]> = {};
+  if (value.diagnostics?.admission) {
+    const count = (value: number) => Number.isSafeInteger(value) && value > 0 ? value : 0;
+    diagnostics.admission = { rejectedTrackingRefs: count(value.diagnostics.admission.rejectedTrackingRefs), rejectedTrackingUrls: count(value.diagnostics.admission.rejectedTrackingUrls) };
+  }
+  if (value.diagnostics?.refusal) {
+    const { reason, phase, retryable } = value.diagnostics.refusal;
+    diagnostics.refusal = { reason: token(reason) as typeof reason, phase: token(phase) as typeof phase, retryable };
+  }
+  if (value.diagnostics?.stockContention) diagnostics.stockContention = { sqlState: "55P03", phase: "provider_stock_consumed", retryable: true };
+  if (value.diagnostics?.annotation) diagnostics.annotation = token(value.diagnostics.annotation) as typeof value.diagnostics.annotation;
+  if (value.diagnostics?.recoveredPickedReceipt) {
+    const { receiptRef, closed } = value.diagnostics.recoveredPickedReceipt;
+    diagnostics.recoveredPickedReceipt = { receiptRef, closed };
+  }
+  const fact = parseFulfillmentFact(value.fact);
+  const safe = {
+    ...pollEvidence(value, privacy, codecs),
+    fact: { ...fact, mapperVersion: token(fact.mapperVersion) ?? "redacted" }, eventKind: (token(value.eventKind) ?? "redacted") as FulfillmentObservation["eventKind"],
+    firstReceivedAt: timestamp.parse(value.firstReceivedAt),
+    trackingRefs: value.trackingRefs.flatMap(ref => {
+      const projected = projectTrackingReference(ref, privacy, approveTrackingUrl, codecs);
+      return projected ? [projected] : [];
+    }),
+  };
+  if (privacy.redactedFieldCount) diagnostics.redactedFieldCount = privacy.redactedFieldCount;
+  return { ...safe, ...(Object.keys(diagnostics).length ? { diagnostics } : {}) };
+}
+
+const HANDOVER_STATUSES: ReadonlySet<string> = new Set(
+  FULFILLMENT_STATUS_MAP.stages.filter(stage => stage.effects.handover).flatMap(stage => stage.localStatus),
+);
+/** Donor finished-picking boundary is narrower than the coarse packing stage. */
+export const observationStatusPolicy = {
+  consumesStock: (status: CanonicalLocalFulfillmentStatus) => ["packed", "in_transit", "delivered"].includes(status),
+  handsOver: (status: CanonicalLocalFulfillmentStatus) => HANDOVER_STATUSES.has(status),
+  suppressDispatched: (status: CanonicalLocalFulfillmentStatus) => status === "delivered",
+  trackingStatus: (status: CanonicalLocalFulfillmentStatus) => status as "in_transit" | "delivered",
+};

package/src/fulfillment/omnipack/capabilities.ts

@@ -0,0 +1,18 @@
+import type { FulfillmentCapabilityDescriptor } from "../contracts/index.js";
+
+/** Offline protocol capabilities; selection and account readiness belong to the host. */
+export const omnipackFulfillmentCapabilities: Readonly<FulfillmentCapabilityDescriptor> = Object.freeze<FulfillmentCapabilityDescriptor>({
+  providerRef: "omnipack", role: "warehouse", defaultOff: true, selected: false,
+  readiness: Object.freeze({ ready: false, refusal: Object.freeze({ reason: "not_ready", phase: "selection", retryable: false }) }),
+  operations: Object.freeze({
+    dispatch: Object.freeze({ supported: true }), readback: Object.freeze({ supported: true }),
+    exactAbsence: Object.freeze({ supported: false, reason: "not_exposed" }), verifyObservation: Object.freeze({ supported: true }),
+    syncStock: Object.freeze({ supported: true }), syncProducts: Object.freeze({ supported: true }),
+    labelCreate: Object.freeze({ supported: false, reason: "not_exposed" }), labelRead: Object.freeze({ supported: false, reason: "host_only" }),
+    labelVoid: Object.freeze({ supported: false, reason: "not_exposed" }), cancel: Object.freeze({ supported: false, reason: "not_exposed" }),
+    pickupPoint: Object.freeze({ supported: true }), courierPickup: Object.freeze({ supported: false, reason: "not_exposed" }),
+  }),
+  authentication: "token", freshness: "not_available", ownsDeliveredNotification: false,
+  stockAuthority: "external_stock_master_with_local_reservations", labelReadOwner: "host_storage",
+  actionPolicy: Object.freeze({ providerSpecificAdminActions: false, genericAdminActions: true, mutationSurface: "provider_adapter" }),
+});