@openlup/platform 0.21.0 → 0.22.0

package/src/fulfillment/contracts/sync.ts

@@ -0,0 +1,61 @@
+import type { FulfillmentRefusal } from "./dispatch.js";
+/** Collection identity never masquerades as a monotonic provider revision. */
+interface SyncIdentity {
+  providerRef: string; syncRunId: string; collectedAt: string;
+  sourceRevision: string | null; revisionSource: "provider" | "collection" | "unknown";
+}
+export interface StockSnapshot extends SyncIdentity {
+  skuRef: string; quantityKind: "snapshot"; totalQuantity: number; forSaleQuantity: number; reservedOrUnavailableQuantity: number;
+}
+export interface StockMovement extends SyncIdentity {
+  skuRef: string; quantityKind: "movement"; quantity: number; occurredAt: string | null;
+  operationType: string | null; documentRef: string | null; lotRef: string | null; expirationDate: string | null;
+}
+export interface SyncCursor {
+  status: "idle" | "running" | "succeeded" | "failed";
+  lastStockSyncedAt: string | null; lastMovementOccurredAt: string | null;
+  /** Sanitized continuation only; no credentials, URLs or arbitrary provider payload. */
+  continuation: { nextRef: string | null; startLocalDate: string | null; endLocalDate: string | null };
+  /** G15: successful sellable coverage gaps; legacy absent values read as []. */
+  coverageGapSkus?: readonly string[];
+  refusal: FulfillmentRefusal | null;
+}
+export interface LocalStock { skuRef: string; onHand: number; reserved: number; unavailable: number; safetyStock: number }
+type Threshold = "safety_stock" | "reservation_coverage" | "forecast" | "stale_sync";
+type Conflict = "unknown_sku" | "ean_conflict" | "kind_quantity_conflict";
+export interface FulfillmentStockSyncProvider {
+  getStock(): Promise<StockSnapshot[]>;
+  getStockMovements(input?: { startLocalDate?: string; endLocalDate?: string; size?: number }): Promise<StockMovement[]>;
+}
+export interface FulfillmentStockSyncPort {
+  readCursor(): Promise<SyncCursor | null>;
+  /** G16: unaggregated lines at the worker clock; quantity retains the four local balances. */
+  readLocalInventoryStock(requestedAt: string): Promise<readonly {
+    skuRef: string; quantity: Pick<LocalStock, "onHand" | "reserved" | "unavailable" | "safetyStock">;
+    fulfillable: boolean; locationStatus: "active" | "inactive";
+    lotStatus: "available" | "quarantined" | "expired" | "recalled" | null; expiresAt: string | null;
+  }[]>;
+  readSkuInventoryClasses(skus: string[]): Promise<Map<string, "sellable" | "packaging" | null>>;
+  readActiveReservations(skus: string[], requestedAt: string): Promise<Map<string, number>>;
+  recordCursor(input: SyncCursor): Promise<void>;
+  recordStockSnapshot(input: { requestKey: string; snapshot: StockSnapshot; local: LocalStock; mismatchKind: "none"; inventoryClass: "sellable" | "packaging" | null }): Promise<{ replayed: boolean; readBack: boolean }>;
+  recordProviderStockCurrent(input: { requestKey: string; snapshot: StockSnapshot; inventoryClass: "sellable" | "packaging" | null; lastSyncedAt: string; staleAfter: string }): Promise<{ replayed: boolean; readBack: boolean }>;
+  recordMovement(input: { requestKey: string; movement: StockMovement }): Promise<{ replayed: boolean; readBack: boolean }>;
+  recordLowStockEvidence(input: { requestKey: string; skuRef: string; thresholdKind: Exclude<Threshold, "forecast">; severity: "info" | "warning" | "critical"; providerForSaleQuantity: number; localAvailableQuantity: number; syncRunId: string }): Promise<{ replayed: boolean }>;
+  resolveLowStockEvidence(input: { skuRef: string; activeThresholdKinds: Threshold[]; syncRunId: string }): Promise<{ resolved: number }>;
+}
+interface ProductPack { ean: string; quantity: number }
+export interface FulfillmentProductSyncProvider {
+  /** null means skipped (no private push metadata), never a newly created local SKU. */
+  ensureProduct(sku: string): Promise<{ replayed: boolean } | null>;
+  getProductPacks(sku: string): Promise<ProductPack[]>;
+  addProductPack(sku: string, pack: ProductPack): Promise<void>;
+  listStockedSkus(): Promise<string[]>;
+}
+export interface FulfillmentProductSyncPort {
+  listLocalProductPacks(): Promise<{ sku: string; packs: (ProductPack & { kind: "unit" | "collective" })[] }[]>;
+  markPackSynced(input: { sku: string; ean: string }): Promise<void>;
+  upsertPulledPack(input: { sku: string; ean: string; quantity: number; kind: "unit" | "collective" }): Promise<{ conflict: "none" | "local_locked_mismatch" | "ean_owned_by_other_sku" | "sku_not_found"; replayed: boolean }>;
+  recordReconciliationEvidence(input: { requestKey: string; sku: string; ean: string | null; conflictKind: Conflict; providerQuantity: number; identity: SyncIdentity; refusal: FulfillmentRefusal | null }): Promise<{ replayed: boolean }>;
+  resolveReconciliationEvidence(input: { sku: string; activeConflictKinds: Conflict[]; syncRunId: string }): Promise<{ resolved: number }>;
+}

package/src/fulfillment/currentFulfillmentParcel.ts

@@ -0,0 +1,2 @@
+export { parcelSequenceNo, compareParcelPrecedence, currentParcel, currentParcelFor, currentParcelPerOrder, currentParcelFirst, belongsToParcel, rowsForParcel } from "@openlup/core/fulfillment";
+export type { FulfillmentParcelRow, ParcelAttributedRow } from "@openlup/core/fulfillment";

package/src/fulfillment/delayReadModel.ts

@@ -0,0 +1,60 @@
+import type { CustomerDeliveryAlignment, FulfillmentCustomerAlignmentRowsReader } from './contracts/customerAlignment.js';
+import type { FulfillmentNativeUnsupported } from './contracts/nativeUnsupported.js';
+import { isNativeUnsupported } from './handlerSupport.js';
+
+export type DeliveryAlignmentRow = Record<string, unknown>;
+export type DeliveryAlignmentRowsReader = FulfillmentCustomerAlignmentRowsReader;
+
+/**
+ * Reads only customer-safe current cases. An aligned case remains current while
+ * its aligned schedule is still the subscription's next schedule; once a paid
+ * cycle advances `next_cycle_at`, the historical ledger row disappears from UI.
+ */
+export async function readFulfillmentDelay(
+  readRows: DeliveryAlignmentRowsReader | undefined,
+  nextCycleAtBySubscription: ReadonlyMap<string, string | null>,
+): Promise<Map<string, CustomerDeliveryAlignment> | FulfillmentNativeUnsupported> {
+  const subscriptionIds = [...nextCycleAtBySubscription.keys()].filter(Boolean);
+  if (!readRows || subscriptionIds.length === 0) return new Map();
+  const rows = await readRows(subscriptionIds);
+  if (isNativeUnsupported(rows)) return rows;
+  return mapCurrentDeliveryAlignments(rows, nextCycleAtBySubscription);
+}
+
+export function mapCurrentDeliveryAlignments(
+  rows: DeliveryAlignmentRow[],
+  nextCycleAtBySubscription: ReadonlyMap<string, string | null>,
+): Map<string, CustomerDeliveryAlignment> {
+  const result = new Map<string, CustomerDeliveryAlignment>();
+  for (const row of rows) {
+    const subscriptionId = text(row.subscription_id);
+    if (!subscriptionId || result.has(subscriptionId)) continue;
+    const state = text(row.state);
+    if (state === "protected") {
+      result.set(subscriptionId, { state });
+      continue;
+    }
+    if (state === "aligned" && sameInstant(
+      nullableText(row.aligned_next_cycle_at),
+      nextCycleAtBySubscription.get(subscriptionId) ?? null,
+    )) {
+      result.set(subscriptionId, { state });
+    }
+  }
+  return result;
+}
+
+function sameInstant(left: string | null, right: string | null): boolean {
+  if (!left || !right) return false;
+  const leftTime = new Date(left).getTime();
+  const rightTime = new Date(right).getTime();
+  return Number.isFinite(leftTime) && leftTime === rightTime;
+}
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function nullableText(value: unknown): string | null {
+  return typeof value === "string" && value ? value : null;
+}

package/src/fulfillment/deliveryAlignmentReadModel.ts

@@ -0,0 +1,15 @@
+import type { DeliveryAlignmentPort } from './contracts/index.js';
+import type { PgExecutor } from './postgresDispatchStore.js';
+
+/** Server-authorized projection; database browser roles have no direct access. */
+export async function readDeliveryAlignment(db: PgExecutor, fulfillmentRef: string): ReturnType<DeliveryAlignmentPort['read']> {
+  const result = await db.query(`SELECT alignment.state, alignment.aligned_next_cycle_at
+    FROM public.fulfillment_shipments shipment
+    LEFT JOIN public.subscription_delivery_alignment_cases alignment ON alignment.predecessor_order_id=shipment.order_id
+    WHERE shipment.id=$1::uuid
+    ORDER BY (alignment.state IN ('protected','manual_review')) DESC, alignment.created_at ASC LIMIT 1`, [fulfillmentRef]);
+  const row = result.rows[0];
+  const date = row?.aligned_next_cycle_at;
+  return { disposition: row?.state === 'aligned' ? 'aligned' : row?.state === 'protected' ? 'outstanding' : 'manual_review',
+    nextCycleAt: date instanceof Date ? date.toISOString() : typeof date === 'string' ? date : null };
+}

package/src/fulfillment/dispatchProjection.ts

@@ -0,0 +1,20 @@
+import type { DispatchEvidence, DispatchRecord, FulfillmentDispatchResult } from "./contracts/index.js";
+
+/** Copy only the durable allowlist, including when an adapter object has extra runtime properties. */
+export function dispatchEvidence(evidence: DispatchEvidence): DispatchEvidence {
+  return {
+    commandFingerprint: evidence.commandFingerprint,
+    contactRevision: { schemaVersion: evidence.contactRevision.schemaVersion, source: evidence.contactRevision.source, revision: evidence.contactRevision.revision },
+    providerRef: evidence.providerRef, carrierRef: evidence.carrierRef, serviceRef: evidence.serviceRef,
+  };
+}
+export function dispatchResult(result: FulfillmentDispatchResult): FulfillmentDispatchResult {
+  switch (result.kind) {
+    case "accepted": return { kind: "accepted", externalRef: result.externalRef, providerAttemptKey: result.providerAttemptKey, labelKey: result.labelKey, evidence: dispatchEvidence(result.evidence) };
+    case "not_dispatched": return { kind: "not_dispatched", effectMayHaveSucceeded: false, refusal: { reason: result.refusal.reason, phase: result.refusal.phase, retryable: result.refusal.retryable } };
+    case "unknown": return { kind: "unknown", effectMayHaveSucceeded: true, refusal: { reason: result.refusal.reason, phase: result.refusal.phase, retryable: result.refusal.retryable } };
+  }
+}
+export function acceptedProviderProof(record: DispatchRecord | null): record is DispatchRecord & { externalRef: string } {
+  return Boolean(record?.externalRef && (record.status === "created" || record.status === "uncertain"));
+}

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,38 @@
+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 { verifyAndNormalizeFulfillmentObservation } from "./verifiedIngress.js";
+export { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+export { reconcileFulfillmentObservations } 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,8 @@
+/** 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) },
+] as const;