@openlup/platform 0.20.0 → 0.22.0

package/dist/fulfillment/commerceFulfillmentHandlers.d.ts

@@ -0,0 +1,29 @@
+import type { FulfillmentOperatorMutationPort as CommerceFulfillmentMutationPort } from './contracts/operator.js';
+import type { FulfillmentCommerceReadPort as CommerceFulfillmentReadPort } from './contracts/read.js';
+import { type BaseDeps, type FulfillmentHandlerRequest } from './handlerSupport.js';
+type PortRef<T> = T | (() => T);
+export declare function createAdminCommerceFulfillmentOrdersListHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentReadPort, "listCommerceFulfillmentOrders">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentOrderDetailHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentReadPort, "getCommerceFulfillmentOrderDetail">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentCreateOrderHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "createCommerceFulfillmentOrder">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentRecordProviderAttemptHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "recordCommerceFulfillmentProviderAttempt">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentRecordLabelHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "recordCommerceFulfillmentLabel">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentHandOffHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "handOffCommerceFulfillmentOrder">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentTrackingEventHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "recordCommerceFulfillmentTrackingEvent">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentCancelOrderHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "cancelCommerceFulfillmentOrder">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export {};

package/dist/fulfillment/commerceFulfillmentHandlers.js

@@ -0,0 +1,184 @@
+import { adminCommerceFulfillmentCancelRequestSchema, adminCommerceFulfillmentCreateRequestSchema, adminCommerceFulfillmentHandOffRequestSchema, adminCommerceFulfillmentMutationResponseSchema, adminCommerceFulfillmentOrderDetailRequestSchema, adminCommerceFulfillmentOrderDetailResponseSchema, adminCommerceFulfillmentOrdersListRequestSchema, adminCommerceFulfillmentOrdersListResponseSchema, adminCommerceFulfillmentRecordLabelRequestSchema, adminCommerceFulfillmentRecordProviderAttemptRequestSchema, adminCommerceFulfillmentTrackingEventRequestSchema, } from "./handlerSchemas.js";
+import { CommerceFulfillmentConflictError, authorize, isNativeUnsupported } from './handlerSupport.js';
+export function createAdminCommerceFulfillmentOrdersListHandler({ authorizeAdmin, respond, fulfillmentPort, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+    return async function handler(req, res) {
+        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({ authorizeAdmin, respond, fulfillmentPort, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+    return async function handler(req, res) {
+        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({ authorizeAdmin, respond, fulfillmentPort, }) {
+    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({ authorizeAdmin, respond, fulfillmentPort, }) {
+    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({ authorizeAdmin, respond, fulfillmentPort, }) {
+    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({ authorizeAdmin, respond, fulfillmentPort, }) {
+    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({ authorizeAdmin, respond, fulfillmentPort, }) {
+    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({ authorizeAdmin, respond, fulfillmentPort, }) {
+    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(port) {
+    return typeof port === "function" ? port() : port;
+}
+function createMutationHandler({ authorizeAdmin, respond, requestSchema, invalidMessage, execute, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+    return async function handler(req, res) {
+        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/dist/fulfillment/commerceFulfillmentReadModel.d.ts

@@ -0,0 +1,86 @@
+import type { FulfillmentCommerceReadPolicy, FulfillmentPaymentStatus, FulfillmentOrderStatus as OrderStatus } from './contracts/read.js';
+import type { SubscriptionCycleStatus } from '@openlup/core/subscription';
+import { 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 declare 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;
+export declare 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;

package/dist/fulfillment/commerceFulfillmentReadModel.js

@@ -0,0 +1,131 @@
+import { COMMERCE_FULFILLMENT_CONTRACT_VERSION, adminCommerceFulfillmentOrderDetailResponseSchema, adminCommerceFulfillmentOrdersListResponseSchema, } from "./handlerSchemas.js";
+export function buildCommerceFulfillmentOrdersListResponse(input, policy) {
+    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, policy) {
+    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) {
+    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) {
+    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) {
+    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(rows, orderId, label) {
+    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/dist/fulfillment/contracts/alignment.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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/dist/fulfillment/contracts/alignment.js

@@ -0,0 +1 @@
+export {};

package/dist/fulfillment/contracts/bindings.d.ts

@@ -0,0 +1,51 @@
+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/dist/fulfillment/contracts/bindings.js

@@ -0,0 +1 @@
+export {};

package/dist/fulfillment/contracts/capabilities.d.ts

@@ -0,0 +1,29 @@
+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/dist/fulfillment/contracts/capabilities.js

@@ -0,0 +1 @@
+export {};

package/dist/fulfillment/contracts/conformance.d.ts

@@ -0,0 +1,93 @@
+import type { FulfillmentCapabilityDescriptor } from "./capabilities.js";
+import type { FulfillmentDispatchPort, FulfillmentDispatchRequest } from "./dispatch.js";
+import type { FulfillmentLabelPort } from "./label.js";
+import type { FulfillmentObservationPort } 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 {
+    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;
+    }[];
+}
+export {};

package/dist/fulfillment/contracts/conformance.js

@@ -0,0 +1 @@
+export {};

package/dist/fulfillment/contracts/customerAlignment.d.ts

@@ -0,0 +1,6 @@
+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>;

package/dist/fulfillment/contracts/customerAlignment.js

@@ -0,0 +1 @@
+export {};