@openlup/platform 0.21.0 → 0.23.0

package/src/fulfillment/bindings.ts

@@ -0,0 +1,26 @@
+import type { FulfillmentServices, FulfillmentServicesOptions } from './contracts/index.js';
+import { FULFILLMENT_NATIVE_UNSUPPORTED } from './nativeUnsupported.js';
+import { readFulfillmentCapabilities } from './providerCapabilities.js';
+import { runFulfillmentDispatchWorker } from './providerDispatchWorker.js';
+
+/** Explicit selection; no environment readers, implicit provider or automatic dispatch. */
+export function createFulfillmentServices(options: FulfillmentServicesOptions): FulfillmentServices {
+  const { enabled, selection, capability, store, provider, readiness: observe, listCandidates, now } = options;
+  const config = { ...options.config }, keys = { ...options.keys };
+  const readiness: FulfillmentServices['readiness'] = async () => {
+    if (enabled !== true) return { ready: false, refusal: { reason: 'disabled', phase: 'selection', retryable: false } };
+    const selected = readFulfillmentCapabilities(capability ? [capability] : [], selection);
+    if (selected.kind === 'refused') return { ready: false, refusal: selected.refusal };
+    if (!selected.descriptor.operations.dispatch.supported) return { ready: false, refusal: { reason: 'unsupported', phase: 'selection', retryable: false } };
+    if (!store || (config.mode !== "shadow" && !provider)) return { ready: false, refusal: FULFILLMENT_NATIVE_UNSUPPORTED };
+    return observe();
+  };
+  return {
+    readiness,
+    async runDispatch() {
+      const state = await readiness();
+      if (!state.ready) return 'kind' in state.refusal ? state.refusal : { kind: 'refused', refusal: state.refusal };
+      return runFulfillmentDispatchWorker({ store: store!, provider, listCandidates, keys, config, now });
+    },
+  };
+}

package/src/fulfillment/commerceFulfillmentHandlers.ts

@@ -0,0 +1,263 @@
+import {
+  adminCommerceFulfillmentCancelRequestSchema,
+  adminCommerceFulfillmentCreateRequestSchema,
+  adminCommerceFulfillmentHandOffRequestSchema,
+  adminCommerceFulfillmentMutationResponseSchema,
+  adminCommerceFulfillmentOrderDetailRequestSchema,
+  adminCommerceFulfillmentOrderDetailResponseSchema,
+  adminCommerceFulfillmentOrdersListRequestSchema,
+  adminCommerceFulfillmentOrdersListResponseSchema,
+  adminCommerceFulfillmentRecordLabelRequestSchema,
+  adminCommerceFulfillmentRecordProviderAttemptRequestSchema,
+  adminCommerceFulfillmentTrackingEventRequestSchema,
+} from "./handlerSchemas.js";
+import type { FulfillmentOperatorMutationPort as CommerceFulfillmentMutationPort } from './contracts/operator.js';
+import type { FulfillmentCommerceReadPort as CommerceFulfillmentReadPort } from './contracts/read.js';
+import { CommerceFulfillmentConflictError, authorize, isNativeUnsupported, type BaseDeps, type FulfillmentHandlerRequest } from './handlerSupport.js';
+type PortRef<T> = T | (() => T);
+
+export function createAdminCommerceFulfillmentOrdersListHandler<Response>({
+  authorizeAdmin,
+  respond,
+  fulfillmentPort,
+}: BaseDeps<Response> & {
+  fulfillmentPort: PortRef<Pick<CommerceFulfillmentReadPort, "listCommerceFulfillmentOrders">>;
+}) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async function handler(req: FulfillmentHandlerRequest, res: Response): Promise<void> {
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    if (!(await authorize(req, res, authorizeAdmin, respond))) return;
+
+    const request = adminCommerceFulfillmentOrdersListRequestSchema.safeParse(req.query);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin commerce fulfillment orders request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const port = resolvePort(fulfillmentPort);
+      const result = await port.listCommerceFulfillmentOrders(request.data);
+      if (isNativeUnsupported(result)) {
+        sendBffError(res, "UPSTREAM_UNAVAILABLE", "Native fulfillment operation unsupported", { details: result });
+        return;
+      }
+      const response = adminCommerceFulfillmentOrdersListResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin commerce fulfillment orders response invalid");
+        return;
+      }
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin commerce fulfillment orders read failed");
+    }
+  };
+}
+
+export function createAdminCommerceFulfillmentOrderDetailHandler<Response>({
+  authorizeAdmin,
+  respond,
+  fulfillmentPort,
+}: BaseDeps<Response> & {
+  fulfillmentPort: PortRef<Pick<CommerceFulfillmentReadPort, "getCommerceFulfillmentOrderDetail">>;
+}) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async function handler(req: FulfillmentHandlerRequest, res: Response): Promise<void> {
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    if (!(await authorize(req, res, authorizeAdmin, respond))) return;
+
+    const request = adminCommerceFulfillmentOrderDetailRequestSchema.safeParse(req.query);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin commerce fulfillment detail request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const port = resolvePort(fulfillmentPort);
+      const result = await port.getCommerceFulfillmentOrderDetail(request.data);
+      if (isNativeUnsupported(result)) {
+        sendBffError(res, "UPSTREAM_UNAVAILABLE", "Native fulfillment operation unsupported", { details: result });
+        return;
+      }
+      if (!result) {
+        sendBffError(res, "NOT_FOUND", "Commerce fulfillment order not found");
+        return;
+      }
+      const response = adminCommerceFulfillmentOrderDetailResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin commerce fulfillment detail response invalid");
+        return;
+      }
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin commerce fulfillment detail read failed");
+    }
+  };
+}
+
+export function createAdminCommerceFulfillmentCreateOrderHandler<Response>({
+  authorizeAdmin,
+  respond,
+  fulfillmentPort,
+}: BaseDeps<Response> & {
+  fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "createCommerceFulfillmentOrder">>;
+}) {
+  return createMutationHandler({
+    authorizeAdmin,
+    respond,
+    requestSchema: adminCommerceFulfillmentCreateRequestSchema,
+    invalidMessage: "Invalid admin commerce fulfillment create request",
+    execute: (request, actorUserId) => {
+      const port = resolvePort(fulfillmentPort);
+      return port.createCommerceFulfillmentOrder({ ...request, actorUserId });
+    },
+  });
+}
+
+export function createAdminCommerceFulfillmentRecordProviderAttemptHandler<Response>({
+  authorizeAdmin,
+  respond,
+  fulfillmentPort,
+}: BaseDeps<Response> & {
+  fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "recordCommerceFulfillmentProviderAttempt">>;
+}) {
+  return createMutationHandler({
+    authorizeAdmin,
+    respond,
+    requestSchema: adminCommerceFulfillmentRecordProviderAttemptRequestSchema,
+    invalidMessage: "Invalid admin commerce fulfillment provider attempt request",
+    execute: (request, actorUserId) => {
+      const port = resolvePort(fulfillmentPort);
+      return port.recordCommerceFulfillmentProviderAttempt({ ...request, actorUserId });
+    },
+  });
+}
+
+export function createAdminCommerceFulfillmentRecordLabelHandler<Response>({
+  authorizeAdmin,
+  respond,
+  fulfillmentPort,
+}: BaseDeps<Response> & {
+  fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "recordCommerceFulfillmentLabel">>;
+}) {
+  return createMutationHandler({
+    authorizeAdmin,
+    respond,
+    requestSchema: adminCommerceFulfillmentRecordLabelRequestSchema,
+    invalidMessage: "Invalid admin commerce fulfillment label request",
+    execute: (request, actorUserId) => {
+      const port = resolvePort(fulfillmentPort);
+      return port.recordCommerceFulfillmentLabel({ ...request, actorUserId });
+    },
+  });
+}
+
+export function createAdminCommerceFulfillmentHandOffHandler<Response>({
+  authorizeAdmin,
+  respond,
+  fulfillmentPort,
+}: BaseDeps<Response> & {
+  fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "handOffCommerceFulfillmentOrder">>;
+}) {
+  return createMutationHandler({
+    authorizeAdmin,
+    respond,
+    requestSchema: adminCommerceFulfillmentHandOffRequestSchema,
+    invalidMessage: "Invalid admin commerce fulfillment handoff request",
+    execute: (request, actorUserId) => {
+      const port = resolvePort(fulfillmentPort);
+      return port.handOffCommerceFulfillmentOrder({ ...request, actorUserId });
+    },
+  });
+}
+
+export function createAdminCommerceFulfillmentTrackingEventHandler<Response>({
+  authorizeAdmin,
+  respond,
+  fulfillmentPort,
+}: BaseDeps<Response> & {
+  fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "recordCommerceFulfillmentTrackingEvent">>;
+}) {
+  return createMutationHandler({
+    authorizeAdmin,
+    respond,
+    requestSchema: adminCommerceFulfillmentTrackingEventRequestSchema,
+    invalidMessage: "Invalid admin commerce fulfillment tracking event request",
+    execute: (request, actorUserId) => {
+      const port = resolvePort(fulfillmentPort);
+      return port.recordCommerceFulfillmentTrackingEvent({ ...request, actorUserId });
+    },
+  });
+}
+
+export function createAdminCommerceFulfillmentCancelOrderHandler<Response>({
+  authorizeAdmin,
+  respond,
+  fulfillmentPort,
+}: BaseDeps<Response> & {
+  fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "cancelCommerceFulfillmentOrder">>;
+}) {
+  return createMutationHandler({
+    authorizeAdmin,
+    respond,
+    requestSchema: adminCommerceFulfillmentCancelRequestSchema,
+    invalidMessage: "Invalid admin commerce fulfillment cancel request",
+    execute: (request, actorUserId) => {
+      const port = resolvePort(fulfillmentPort);
+      return port.cancelCommerceFulfillmentOrder({ ...request, actorUserId });
+    },
+  });
+}
+
+function resolvePort<T>(port: PortRef<T>): T {
+  return typeof port === "function" ? (port as () => T)() : port;
+}
+
+function createMutationHandler<T, Response>({
+  authorizeAdmin,
+  respond,
+  requestSchema,
+  invalidMessage,
+  execute,
+}: BaseDeps<Response> & {
+  requestSchema: { safeParse: (input: unknown) => { success: true; data: T } | { success: false; error: { flatten: () => unknown } } };
+  invalidMessage: string;
+  execute: (request: T, actorUserId: string) => Promise<unknown>;
+}) {
+  const { sendBffError, sendBffSuccess, 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 = requestSchema.safeParse(req.body ?? {});
+    if (request.success === false) {
+      sendBffError(res, "BAD_REQUEST", invalidMessage, { details: request.error.flatten() });
+      return;
+    }
+
+    try {
+      const result = await execute(request.data, auth.userId);
+      if (isNativeUnsupported(result)) {
+        sendBffError(res, "UPSTREAM_UNAVAILABLE", "Native fulfillment operation unsupported", { details: result });
+        return;
+      }
+      const response = adminCommerceFulfillmentMutationResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin commerce fulfillment mutation response invalid");
+        return;
+      }
+      sendBffSuccess(res, response.data);
+    } catch (error) {
+      if (error instanceof CommerceFulfillmentConflictError) {
+        sendBffError(res, "CONFLICT", error.message, { details: error.details });
+        return;
+      }
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin commerce fulfillment mutation failed", {
+        details: { reason: "fulfillment_mutation_failed" },
+      });
+    }
+  };
+}

package/src/fulfillment/commerceFulfillmentReadModel.ts

@@ -0,0 +1,257 @@
+import type { FulfillmentCommerceReadPolicy, FulfillmentPaymentStatus, FulfillmentOrderStatus as OrderStatus } from './contracts/read.js';
+import type { SubscriptionCycleStatus } from '@openlup/core/subscription';
+import {
+  COMMERCE_FULFILLMENT_CONTRACT_VERSION,
+  adminCommerceFulfillmentOrderDetailResponseSchema,
+  adminCommerceFulfillmentOrdersListResponseSchema,
+  type AdminCommerceFulfillmentOrderDetailResponse,
+  type AdminCommerceFulfillmentOrdersListResponse,
+  type CommerceFulfillmentOrder,
+  type CommerceFulfillmentOperationType,
+  type CommerceFulfillmentStatus,
+} from "./handlerSchemas.js";
+
+export interface CommerceFulfillmentOrderRow {
+  id: string;
+  order_id: string;
+  client_id: string | null;
+  status: CommerceFulfillmentStatus;
+  provider_kind: string | null;
+  shipping_address_snapshot: CommerceFulfillmentOrder["shippingAddress"];
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CommerceFulfillmentLineRow {
+  id: string;
+  fulfillment_order_id: string;
+  order_item_id: string;
+  sku_id: string;
+  sku: string;
+  title: string | null;
+  quantity: number;
+  inventory_reservation_ids: string[];
+  product_snapshot: Record<string, unknown>;
+}
+
+export interface CommerceFulfillmentOperationRow {
+  id: string;
+  fulfillment_order_id: string;
+  operation_type: CommerceFulfillmentOperationType;
+  actor_user_id: string | null;
+  occurred_at: string;
+  payload: Record<string, unknown>;
+}
+
+export interface CommerceFulfillmentOrderContextRow {
+  id: string;
+  status: OrderStatus;
+  mode: "one_time" | "subscription_cycle";
+  shipping_address_id: string | null;
+  subscription_cycle_id: string | null;
+}
+
+export interface CommerceFulfillmentPaymentIntentRow {
+  id: string;
+  order_id: string;
+  status: FulfillmentPaymentStatus;
+  provider_payment_id: string | null;
+}
+
+export interface CommerceFulfillmentInventoryReservationRow {
+  id: string;
+  order_id: string;
+  status: "reserved" | "released" | "consumed" | "expired";
+  expires_at: string | null;
+  location_id: string | null;
+  inventory_locations?: { code?: string | null } | null;
+}
+
+export interface CommerceFulfillmentShipmentRefRow {
+  order_id: string;
+  provider_tracking_id: string;
+  active: boolean;
+  created_at?: string | null;
+}
+
+export function buildCommerceFulfillmentOrdersListResponse(input: {
+  fulfillmentOrders: CommerceFulfillmentOrderRow[];
+  lines: CommerceFulfillmentLineRow[];
+  latestOperations: CommerceFulfillmentOperationRow[];
+  orderContexts: CommerceFulfillmentOrderContextRow[];
+  paymentIntents: CommerceFulfillmentPaymentIntentRow[];
+  inventoryReservations: CommerceFulfillmentInventoryReservationRow[];
+  shipmentRefs: CommerceFulfillmentShipmentRefRow[];
+  activeHoldCounts: Record<string, number>;
+  subscriptionCycleStatuses: Record<string, SubscriptionCycleStatus | null>;
+  totalCount: number;
+  page: number;
+  pageSize: number;
+}, policy: FulfillmentCommerceReadPolicy): AdminCommerceFulfillmentOrdersListResponse {
+  return adminCommerceFulfillmentOrdersListResponseSchema.parse({
+    contractVersion: COMMERCE_FULFILLMENT_CONTRACT_VERSION,
+    orders: input.fulfillmentOrders.map((fulfillmentOrder) =>
+      buildCommerceFulfillmentOrder({
+        fulfillmentOrder,
+        lines: input.lines.filter((line) => line.fulfillment_order_id === fulfillmentOrder.id),
+        latestOperation:
+          input.latestOperations.find((operation) => operation.fulfillment_order_id === fulfillmentOrder.id) ??
+          null,
+        orderContext: findRequired(input.orderContexts, fulfillmentOrder.order_id, "order context"),
+        paymentIntent: findRequired(input.paymentIntents, fulfillmentOrder.order_id, "payment intent"),
+        inventoryReservations: input.inventoryReservations.filter(
+          (reservation) => reservation.order_id === fulfillmentOrder.order_id,
+        ),
+        shipmentRef: input.shipmentRefs.find((ref) => ref.order_id === fulfillmentOrder.order_id && ref.active) ?? null,
+        activeHoldCount: input.activeHoldCounts[fulfillmentOrder.order_id] ?? 0,
+        subscriptionCycleStatuses: input.subscriptionCycleStatuses,
+        policy,
+      }),
+    ),
+    totalCount: input.totalCount,
+    page: input.page,
+    pageSize: input.pageSize,
+  });
+}
+
+export function buildCommerceFulfillmentOrderDetailResponse(input: {
+  fulfillmentOrder: CommerceFulfillmentOrderRow;
+  lines: CommerceFulfillmentLineRow[];
+  latestOperation: CommerceFulfillmentOperationRow | null;
+  orderContext: CommerceFulfillmentOrderContextRow;
+  paymentIntent: CommerceFulfillmentPaymentIntentRow;
+  inventoryReservations: CommerceFulfillmentInventoryReservationRow[];
+  shipmentRef: CommerceFulfillmentShipmentRefRow | null;
+  activeHoldCount: number;
+  subscriptionCycleStatus: SubscriptionCycleStatus | null;
+}, policy: FulfillmentCommerceReadPolicy): AdminCommerceFulfillmentOrderDetailResponse {
+  return adminCommerceFulfillmentOrderDetailResponseSchema.parse({
+    contractVersion: COMMERCE_FULFILLMENT_CONTRACT_VERSION,
+    order: buildCommerceFulfillmentOrder({
+      fulfillmentOrder: input.fulfillmentOrder,
+      lines: input.lines,
+      latestOperation: input.latestOperation,
+      orderContext: input.orderContext,
+      paymentIntent: input.paymentIntent,
+      inventoryReservations: input.inventoryReservations,
+      shipmentRef: input.shipmentRef,
+      activeHoldCount: input.activeHoldCount,
+      policy,
+      subscriptionCycleStatuses: {
+        [input.orderContext.subscription_cycle_id ?? ""]: input.subscriptionCycleStatus,
+      },
+    }),
+  });
+}
+
+function buildCommerceFulfillmentOrder(input: {
+  fulfillmentOrder: CommerceFulfillmentOrderRow;
+  lines: CommerceFulfillmentLineRow[];
+  latestOperation: CommerceFulfillmentOperationRow | null;
+  orderContext: CommerceFulfillmentOrderContextRow;
+  paymentIntent: CommerceFulfillmentPaymentIntentRow;
+  inventoryReservations: CommerceFulfillmentInventoryReservationRow[];
+  shipmentRef: CommerceFulfillmentShipmentRefRow | null;
+  activeHoldCount: number;
+  subscriptionCycleStatuses: Record<string, SubscriptionCycleStatus | null>;
+  policy: FulfillmentCommerceReadPolicy;
+}): CommerceFulfillmentOrder {
+  const paymentStatus = input.paymentIntent.status;
+  const inventory = inventorySummary(input.inventoryReservations);
+  return {
+    id: input.fulfillmentOrder.id,
+    orderId: input.fulfillmentOrder.order_id,
+    clientId: input.fulfillmentOrder.client_id,
+    status: input.fulfillmentOrder.status,
+    providerKind: input.fulfillmentOrder.provider_kind,
+    providerTrackingId: input.shipmentRef?.provider_tracking_id ?? null,
+    shippingAddress: normalizeShippingAddressSnapshot(input.fulfillmentOrder.shipping_address_snapshot),
+    lines: input.lines.map((line) => ({
+      id: line.id,
+      orderItemId: line.order_item_id,
+      skuId: line.sku_id,
+      sku: line.sku,
+      title: line.title,
+      quantity: line.quantity,
+      inventoryReservationIds: line.inventory_reservation_ids,
+      productSnapshot: line.product_snapshot,
+    })),
+    payment: {
+      paymentIntentId: input.paymentIntent.id,
+      paymentStatus,
+      providerPaymentId: input.paymentIntent.provider_payment_id,
+    },
+    inventory,
+    omsEligibility: input.policy.evaluateCommerceFulfillmentEligibility({
+      orderMode: input.orderContext.mode,
+      orderStatus: input.orderContext.status,
+      paymentStatus,
+      subscriptionCycleStatus: input.orderContext.subscription_cycle_id
+        ? input.subscriptionCycleStatuses[input.orderContext.subscription_cycle_id] ?? null
+        : null,
+      activeHoldCount: input.activeHoldCount,
+      hasShippingAddress: Boolean(input.orderContext.shipping_address_id),
+      inventoryStatus: inventory.status,
+    }),
+    latestOperation: input.latestOperation
+      ? {
+          id: input.latestOperation.id,
+          type: input.latestOperation.operation_type,
+          occurredAt: input.latestOperation.occurred_at,
+          actorUserId: input.latestOperation.actor_user_id,
+          payload: input.latestOperation.payload,
+        }
+      : null,
+    createdAt: input.fulfillmentOrder.created_at,
+    updatedAt: input.fulfillmentOrder.updated_at,
+  };
+}
+
+function normalizeShippingAddressSnapshot(
+  snapshot: CommerceFulfillmentOrderRow["shipping_address_snapshot"],
+): CommerceFulfillmentOrder["shippingAddress"] {
+  return {
+    addressId: snapshot.addressId,
+    clientId: snapshot.clientId,
+    label: snapshot.label,
+    line1: snapshot.line1,
+    line2: snapshot.line2,
+    city: snapshot.city,
+    postalCode: snapshot.postalCode,
+    country: snapshot.country,
+  };
+}
+
+function inventorySummary(
+  reservations: CommerceFulfillmentInventoryReservationRow[],
+): CommerceFulfillmentOrder["inventory"] {
+  const reservation = reservations[0] ?? null;
+  if (!reservation) {
+    return {
+      status: "missing",
+      reservationId: null,
+      reservationStatus: null,
+      expiresAt: null,
+      locationId: null,
+      locationCode: null,
+    };
+  }
+  return {
+    status: reservation.status === "reserved" ? "reserved" : reservation.status,
+    reservationId: reservation.id,
+    reservationStatus: reservation.status,
+    expiresAt: reservation.expires_at,
+    locationId: reservation.location_id,
+    locationCode: reservation.inventory_locations?.code ?? null,
+  };
+}
+
+function findRequired<T extends { order_id?: string; id?: string }>(
+  rows: T[],
+  orderId: string,
+  label: string,
+): T {
+  const row = rows.find((candidate) => candidate.order_id === orderId || candidate.id === orderId);
+  if (!row) throw new Error(`Missing commerce fulfillment ${label} for order ${orderId}`);
+  return row;
+}

package/src/fulfillment/contracts/alignment.ts

@@ -0,0 +1,13 @@
+/**
+ * Late delivery extends the next cycle, never stacks deliveries or moves it earlier.
+ * A replacement may settle alignment as aligned only after reaching the customer.
+ * Its superseded predecessor is no longer outstanding; an in-flight or undelivered
+ * replacement still is. Never call subscription_delivery_alignment_confirm_replacement
+ * for a replacement that did not arrive: it records "Parcel delivered" and shifts
+ * the cycle later. That note-only operator attestation remains outside this port;
+ * no automatic caller or new guard is introduced.
+ */
+export interface DeliveryAlignmentPort {
+  recordArrival(input: { requestKey: string; parcelRef: string; deliveredAt: string; evidenceRef: `evidence:${string}` }): Promise<{ disposition: "aligned" | "outstanding" | "manual_review"; nextCycleAt: string | null; replayed: boolean }>;
+  read(fulfillmentRef: string): Promise<{ disposition: "aligned" | "outstanding" | "manual_review"; nextCycleAt: string | null }>;
+}

package/src/fulfillment/contracts/bindings.ts

@@ -0,0 +1,30 @@
+import type { FulfillmentCapabilityDescriptor } from './capabilities.js';
+import type { FulfillmentDispatchPort, FulfillmentDispatchRequest, FulfillmentRefusal, FulfillmentSelection } from './dispatch.js';
+import type { FulfillmentNativeUnsupported } from './nativeUnsupported.js';
+import type { DispatchRecord, FulfillmentStorePort } from './store.js';
+
+/** In-memory ports and host closures only; never serialize options or recipient inputs. */
+export interface FulfillmentServicesOptions {
+  enabled?: boolean;
+  selection: FulfillmentSelection | null;
+  capability: FulfillmentCapabilityDescriptor | null;
+  store: FulfillmentStorePort | null;
+  provider: FulfillmentDispatchPort | null;
+  readiness(): Promise<{ ready: true } | { ready: false; refusal: FulfillmentRefusal | FulfillmentNativeUnsupported }>;
+  listCandidates(limit: number): Promise<readonly FulfillmentDispatchRequest[]>;
+  keys: {
+    request(candidate: FulfillmentDispatchRequest): string;
+    mappedAttempt(requestKey: string, mappedAttemptIndex: number): string;
+    acceptance(fulfillmentRef: string): { providerAttemptKey: string; labelKey: string };
+  };
+  config: { mode: DispatchRecord['mode']; batchLimit: number };
+  now?: () => Date;
+}
+/** Import and construction are inert. Every invocation checks activation before any worker. */
+export interface FulfillmentServices {
+  readiness(): ReturnType<FulfillmentServicesOptions['readiness']>;
+  runDispatch(): Promise<FulfillmentNativeUnsupported | { kind: 'refused'; refusal: FulfillmentRefusal } | {
+    ok: boolean; skipped: boolean; checked: number; updated: number; failures: number;
+    mode: DispatchRecord['mode']; replayed: number; providerCalls: number; readBacks: number; reason: string | undefined;
+  }>;
+}

package/src/fulfillment/contracts/capabilities.ts

@@ -0,0 +1,15 @@
+import type { FulfillmentRefusal } from "./dispatch.js";
+export interface FulfillmentCapabilityDescriptor {
+  providerRef: string;
+  role: "warehouse" | "direct_carrier" | "manual" | "simulator";
+  operations: Readonly<Record<"dispatch" | "readback" | "exactAbsence" | "verifyObservation" | "syncStock" | "syncProducts" | "labelCreate" | "labelRead" | "labelVoid" | "cancel" | "pickupPoint" | "courierPickup", { supported: true } | { supported: false; reason: "not_exposed" | "host_only" | "not_implemented" }>>;
+  authentication: "token" | "authenticated_timestamp" | "none";
+  freshness: "authenticated_timestamp" | "not_available";
+  defaultOff: true;
+  selected: boolean;
+  readiness: { ready: true } | { ready: false; refusal: FulfillmentRefusal };
+  ownsDeliveredNotification: boolean;
+  stockAuthority: "local_atp" | "external_stock_master_with_local_reservations";
+  labelReadOwner: "host_storage" | "adapter" | "none";
+  actionPolicy: { providerSpecificAdminActions: boolean; genericAdminActions: boolean; mutationSurface: "none" | "local_only" | "provider_adapter" };
+}

package/src/fulfillment/contracts/conformance.ts

@@ -0,0 +1,63 @@
+import type { FulfillmentCapabilityDescriptor } from "./capabilities.js";
+import type { FulfillmentDispatchPort, FulfillmentDispatchRequest } from "./dispatch.js";
+import type { FulfillmentLabelPort } from "./label.js";
+import type { FulfillmentObservationPort, FulfillmentObservationCodecs } from "./observation.js";
+import type { FulfillmentReadbackPort } from "./readback.js";
+import type { FulfillmentStockSyncProvider, FulfillmentProductSyncProvider } from "./sync.js";
+import type { FulfillmentStorePort } from "./store.js";
+
+type Fixture<Method extends (...args: never[]) => unknown> = {
+  input: Parameters<Method>; expected: Awaited<ReturnType<Method>>;
+};
+type SyncFixture<Port> = { [K in keyof Port]: Port[K] extends (...args: never[]) => unknown
+  ? { operation: K; input: Parameters<Port[K]>; expected: Awaited<ReturnType<Port[K]>> | { kind: "refused"; refusal: { reason: "unsupported"; phase: "sync"; retryable: false } } } : never }[keyof Port];
+
+/** Offline adapter-owned inputs and exact expected outputs; never real customer data. */
+export interface FulfillmentAdapterConformanceSubject {
+  approveTrackingUrl?(url: string): boolean;
+  observationCodecs?: FulfillmentObservationCodecs;
+  subjectId: string;
+  adapter: {
+    capabilities: FulfillmentCapabilityDescriptor; dispatch: FulfillmentDispatchPort;
+    label?: FulfillmentLabelPort; observation?: FulfillmentObservationPort; readback?: FulfillmentReadbackPort;
+    stockSync?: FulfillmentStockSyncProvider; productSync?: FulfillmentProductSyncProvider;
+  };
+  /** Count external submission I/O, including attempted calls. Preparation/refusals must not increase it. */
+  readIoCount(): number;
+  sensitiveValues: readonly string[];
+  fixtures: {
+    dispatch: readonly {
+      input: FulfillmentDispatchRequest;
+      expectedPrepare: Awaited<ReturnType<FulfillmentDispatchPort["prepare"]>>;
+      expectedDispatch?: Awaited<ReturnType<FulfillmentDispatchPort["dispatch"]>>;
+      /** Repeating this operation must not increase external submission I/O. */
+      replay?: boolean;
+    }[];
+    label?: { create?: readonly Fixture<FulfillmentLabelPort["create"]>[]; read?: readonly Fixture<FulfillmentLabelPort["read"]>[]; void?: readonly Fixture<FulfillmentLabelPort["void"]>[] };
+    observation?: readonly Fixture<FulfillmentObservationPort["verifyAndNormalize"]>[];
+    readback?: readonly (Fixture<FulfillmentReadbackPort["read"]> & { localMissing?: boolean })[];
+    stockSync?: readonly SyncFixture<FulfillmentStockSyncProvider>[];
+    productSync?: readonly SyncFixture<FulfillmentProductSyncProvider>[];
+  };
+  /** A fresh isolated host store per call; no database implementation is supplied by the runner. */
+  store?: {
+    create(): Promise<FulfillmentStorePort & {
+      /** Offline fixture inspection, not a new production store operation. */
+      readMappedAttempts(): Promise<readonly {
+        attemptKey: string; fulfillmentRef: string;
+        preparedEvidence: Parameters<FulfillmentStorePort["recordProviderAttempt"]>[2];
+        mode: Parameters<FulfillmentStorePort["recordProviderAttempt"]>[3]; status: "recorded";
+      }[]>;
+    }>;
+    claim: Parameters<FulfillmentStorePort["claim"]>[0];
+    remappedClaim: Parameters<FulfillmentStorePort["claim"]>[0];
+    mappedAttemptKey: string; remappedAttemptKey: string;
+    request: FulfillmentDispatchRequest; remappedRequest: FulfillmentDispatchRequest;
+  };
+}
+
+/** Sanitized proof only: no fixture inputs, raw responses, transient URLs or credentials. */
+export interface FulfillmentAdapterConformanceEvidence {
+  subjects: readonly { subjectId: string; providerRef: string }[];
+  cases: readonly { subjectId: string; operation: string; passed: true }[];
+}

package/src/fulfillment/contracts/customerAlignment.ts

@@ -0,0 +1,4 @@
+import type { FulfillmentNativeUnsupported } from './nativeUnsupported.js';
+export interface CustomerDeliveryAlignment { state: 'protected' | 'aligned' }
+/** Absence from the map means no current customer case, distinct from protected. */
+export type FulfillmentCustomerAlignmentRowsReader = (subscriptionIds: string[]) => Promise<Record<string, unknown>[] | FulfillmentNativeUnsupported>;