@openlup/platform 0.21.0 → 0.23.0

package/dist/fulfillment/handlerSchemas.js

@@ -0,0 +1,213 @@
+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'];
+const OMS_INVENTORY_STATUSES = ['not_checked', 'reserved', 'missing', 'released', 'expired', 'consumed', 'review_required'];
+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",
+];
+export const COMMERCE_FULFILLMENT_OPERATION_TYPES = [
+    "created",
+    "packed",
+    "provider_attempt_recorded",
+    "label_created",
+    "handed_over",
+    "tracking_event_recorded",
+    "cancelled",
+];
+export const COMMERCE_FULFILLMENT_PROVIDER_ATTEMPT_STATUSES = [
+    "recorded",
+    "succeeded",
+    "failed",
+];
+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 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/dist/fulfillment/handlerSupport.d.ts

@@ -0,0 +1,33 @@
+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 declare function isNativeUnsupported(value: unknown): value is FulfillmentNativeUnsupported;
+export declare class CommerceFulfillmentConflictError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+export declare function authorize<Response>(req: FulfillmentHandlerRequest, res: Response, authorizeAdmin: BaseDeps<Response>['authorizeAdmin'], respond: FulfillmentHandlerResponder<Response>): Promise<{
+    userId: string;
+} | null>;

package/dist/fulfillment/handlerSupport.js

@@ -0,0 +1,25 @@
+export function isNativeUnsupported(value) {
+    return typeof value === 'object' && value !== null && 'kind' in value && value.kind === 'native_unsupported';
+}
+export class CommerceFulfillmentConflictError extends Error {
+    details;
+    constructor(message = 'Commerce fulfillment conflict', details = {}) {
+        super(message);
+        this.details = details;
+        this.name = 'CommerceFulfillmentConflictError';
+    }
+}
+export async function authorize(req, res, authorizeAdmin, respond) {
+    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/dist/fulfillment/index.d.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 type { FulfillmentIngressCounts, FulfillmentIngressResult } from "./verifiedIngress.js";
+export { verifyAndNormalizeFulfillmentObservation, fulfillmentIngressHttpResult } from "./verifiedIngress.js";
+export { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+export { reconcileFulfillmentObservations, runFulfillmentReconciliationPage } from "./providerReconciliationWorker.js";
+export { runFulfillmentStockSyncWorker } from "./providerStockSyncWorker.js";
+export { runFulfillmentProductSyncWorker } from "./providerProductSyncWorker.js";
+export { createFulfillmentLowStockEvidenceHandler } from "./lowStockEvidenceHandler.js";
+export { createProductReconciliationEvidenceHandler } from "./productReconciliationEvidenceHandler.js";
+export { runFulfillmentAdapterConformance } from "./adapterConformance.js";
+export { createPostgresFulfillmentShipmentSpinePort } from './postgresShipmentSpine.js';
+export { createPostgresFulfillmentLowStockEvidencePort } from './postgresEvidenceReadPort.js';
+export { createPostgresFulfillmentStockSyncPort } from './postgresStockSyncPort.js';
+export { createPostgresPaidFulfillmentRecoveryOpsPort } from './postgresPaidFulfillmentRecovery.js';
+export { createPostgresFulfillmentDispatchStore } from './postgresDispatchStore.js';
+export { createPostgresPaidFulfillmentHandoffStore } from './postgresPaidHandoffStore.js';
+export { createPostgresDeliveryAlignmentPort } from './postgresDeliveryAlignment.js';
+export { readDeliveryAlignment } from './deliveryAlignmentReadModel.js';
+export { FULFILLMENT_NATIVE_CAPABILITIES } from './schemaCapabilities.js';
+export { FULFILLMENT_MIGRATIONS } from './migrations.js';
+export { createAdminCommerceFulfillmentOrdersListHandler, createAdminCommerceFulfillmentOrderDetailHandler, createAdminCommerceFulfillmentCreateOrderHandler, createAdminCommerceFulfillmentRecordProviderAttemptHandler, createAdminCommerceFulfillmentRecordLabelHandler, createAdminCommerceFulfillmentHandOffHandler, createAdminCommerceFulfillmentTrackingEventHandler, createAdminCommerceFulfillmentCancelOrderHandler } from './commerceFulfillmentHandlers.js';
+export { createAdminCommerceOrderRequestReplacementShipmentHandler } from './replacementShipmentHandler.js';
+export { CommerceFulfillmentConflictError } from './handlerSupport.js';
+export { readFulfillmentDelay } from './delayReadModel.js';
+export { readFulfillmentLabel, cleanupFulfillmentLabel } from './labelLifecycle.js';
+export { currentParcel, currentParcelFor, currentParcelPerOrder, currentParcelFirst, belongsToParcel, rowsForParcel, parcelSequenceNo, compareParcelPrecedence } from './currentFulfillmentParcel.js';
+export { FULFILLMENT_NATIVE_UNSUPPORTED, createNativeUnsupportedFulfillmentPorts } from './nativeUnsupported.js';
+export { FULFILLMENT_REPLACEMENT_REFUSALS } from './replacementRefusals.js';
+export { buildCommerceFulfillmentOrdersListResponse, buildCommerceFulfillmentOrderDetailResponse } from './commerceFulfillmentReadModel.js';
+export { createFulfillmentShipmentsOverviewHandler } from './shipmentsOverviewHandler.js';
+export { fulfillmentProgressPresentation } from './trackingProgress.js';
+export { createFulfillmentServices } from './bindings.js';

package/dist/fulfillment/index.js

@@ -0,0 +1,37 @@
+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, fulfillmentIngressHttpResult } from "./verifiedIngress.js";
+export { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+export { reconcileFulfillmentObservations, runFulfillmentReconciliationPage } from "./providerReconciliationWorker.js";
+export { runFulfillmentStockSyncWorker } from "./providerStockSyncWorker.js";
+export { runFulfillmentProductSyncWorker } from "./providerProductSyncWorker.js";
+export { createFulfillmentLowStockEvidenceHandler } from "./lowStockEvidenceHandler.js";
+export { createProductReconciliationEvidenceHandler } from "./productReconciliationEvidenceHandler.js";
+export { runFulfillmentAdapterConformance } from "./adapterConformance.js";
+export { createPostgresFulfillmentShipmentSpinePort } from './postgresShipmentSpine.js';
+export { createPostgresFulfillmentLowStockEvidencePort } from './postgresEvidenceReadPort.js';
+export { createPostgresFulfillmentStockSyncPort } from './postgresStockSyncPort.js';
+export { createPostgresPaidFulfillmentRecoveryOpsPort } from './postgresPaidFulfillmentRecovery.js';
+export { createPostgresFulfillmentDispatchStore } from './postgresDispatchStore.js';
+export { createPostgresPaidFulfillmentHandoffStore } from './postgresPaidHandoffStore.js';
+export { createPostgresDeliveryAlignmentPort } from './postgresDeliveryAlignment.js';
+export { readDeliveryAlignment } from './deliveryAlignmentReadModel.js';
+export { FULFILLMENT_NATIVE_CAPABILITIES } from './schemaCapabilities.js';
+export { FULFILLMENT_MIGRATIONS } from './migrations.js';
+export { createAdminCommerceFulfillmentOrdersListHandler, createAdminCommerceFulfillmentOrderDetailHandler, createAdminCommerceFulfillmentCreateOrderHandler, createAdminCommerceFulfillmentRecordProviderAttemptHandler, createAdminCommerceFulfillmentRecordLabelHandler, createAdminCommerceFulfillmentHandOffHandler, createAdminCommerceFulfillmentTrackingEventHandler, createAdminCommerceFulfillmentCancelOrderHandler } from './commerceFulfillmentHandlers.js';
+export { createAdminCommerceOrderRequestReplacementShipmentHandler } from './replacementShipmentHandler.js';
+export { CommerceFulfillmentConflictError } from './handlerSupport.js';
+export { readFulfillmentDelay } from './delayReadModel.js';
+export { readFulfillmentLabel, cleanupFulfillmentLabel } from './labelLifecycle.js';
+export { currentParcel, currentParcelFor, currentParcelPerOrder, currentParcelFirst, belongsToParcel, rowsForParcel, parcelSequenceNo, compareParcelPrecedence } from './currentFulfillmentParcel.js';
+export { FULFILLMENT_NATIVE_UNSUPPORTED, createNativeUnsupportedFulfillmentPorts } from './nativeUnsupported.js';
+export { FULFILLMENT_REPLACEMENT_REFUSALS } from './replacementRefusals.js';
+export { buildCommerceFulfillmentOrdersListResponse, buildCommerceFulfillmentOrderDetailResponse } from './commerceFulfillmentReadModel.js';
+export { createFulfillmentShipmentsOverviewHandler } from './shipmentsOverviewHandler.js';
+export { fulfillmentProgressPresentation } from './trackingProgress.js';
+export { createFulfillmentServices } from './bindings.js';

package/dist/fulfillment/labelLifecycle.d.ts

@@ -0,0 +1,24 @@
+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 declare function readFulfillmentLabel(port: Pick<FulfillmentLabelPort, 'read'>, document: LabelDocument | null): Promise<{
+    kind: "available";
+    url: string;
+    expiresAt: string | null;
+} | {
+    kind: "refused";
+    refusal: import("./contracts/dispatch.js").FulfillmentRefusal;
+}>;
+/** Provider and storage deletion remain host-owned; canProceed never asserts either deletion. */
+type LabelCleanupInput = Parameters<FulfillmentLabelPort['void']>[0] & {
+    actorUserId: string;
+    idempotencyKey: string;
+};
+export declare function cleanupFulfillmentLabel(port: {
+    void(input: LabelCleanupInput): ReturnType<FulfillmentLabelPort['void']>;
+}, input: LabelCleanupInput): Promise<{
+    providerDeletion: "confirmed" | "unconfirmed";
+    labelDeleted: boolean;
+    canProceed: boolean;
+    refusal?: import("./contracts/dispatch.js").FulfillmentRefusal;
+}>;
+export {};

package/dist/fulfillment/labelLifecycle.js

@@ -0,0 +1,9 @@
+/** Storage-only read: a missing cached label never proves the parcel absent. Signed URLs are transient. */
+export async function readFulfillmentLabel(port, document) {
+    if (!document)
+        return { kind: 'refused', refusal: { reason: 'local_missing', phase: 'readback', retryable: false } };
+    return port.read(document);
+}
+export async function cleanupFulfillmentLabel(port, input) {
+    return port.void(input);
+}

package/dist/fulfillment/lowStockEvidenceHandler.d.ts

@@ -0,0 +1,36 @@
+/** Read-only evidence boundary; parsing remains with the owning host schema. */
+export declare 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;
+    };
+}): (req: Request, res: Response) => Promise<void>;

package/dist/fulfillment/lowStockEvidenceHandler.js

@@ -0,0 +1,46 @@
+/** Read-only evidence boundary; parsing remains with the owning host schema. */
+export function createFulfillmentLowStockEvidenceHandler({ evidencePort, authorizeAdmin, requestSchema, responseSchema, respond }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+    return async function handler(req, res) {
+        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) {
+    return Array.isArray(value) ? value[0] : value;
+}

package/dist/fulfillment/migrations.d.ts

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

package/dist/fulfillment/migrations.js

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

package/dist/fulfillment/nativeUnsupported.d.ts

@@ -0,0 +1,10 @@
+import type { FulfillmentCommerceReadPort, FulfillmentShipmentsOverviewPort } from './contracts/read.js';
+import type { FulfillmentNativeUnsupported } from './contracts/nativeUnsupported.js';
+import type { FulfillmentReplacementPort } from './contracts/replacement.js';
+import type { FulfillmentOperatorMutationPort } from './contracts/operator.js';
+import type { FulfillmentCustomerAlignmentRowsReader } from './contracts/customerAlignment.js';
+export declare const FULFILLMENT_NATIVE_UNSUPPORTED: FulfillmentNativeUnsupported;
+/** Deliberately has no executor: unsupported native parity can never make a partial write. */
+export declare function createNativeUnsupportedFulfillmentPorts(): FulfillmentReplacementPort & FulfillmentOperatorMutationPort & FulfillmentCommerceReadPort & FulfillmentShipmentsOverviewPort & {
+    readCustomerAlignmentRows: FulfillmentCustomerAlignmentRowsReader;
+};

package/dist/fulfillment/nativeUnsupported.js

@@ -0,0 +1,18 @@
+export const FULFILLMENT_NATIVE_UNSUPPORTED = Object.freeze({ kind: 'native_unsupported', reason: 'host_binding_required', retryable: false });
+/** Deliberately has no executor: unsupported native parity can never make a partial write. */
+export function createNativeUnsupportedFulfillmentPorts() {
+    const unsupported = async () => FULFILLMENT_NATIVE_UNSUPPORTED;
+    return {
+        requestReplacementShipment: unsupported,
+        createCommerceFulfillmentOrder: unsupported,
+        recordCommerceFulfillmentProviderAttempt: unsupported,
+        recordCommerceFulfillmentLabel: unsupported,
+        handOffCommerceFulfillmentOrder: unsupported,
+        recordCommerceFulfillmentTrackingEvent: unsupported,
+        cancelCommerceFulfillmentOrder: unsupported,
+        readCustomerAlignmentRows: unsupported,
+        listCommerceFulfillmentOrders: unsupported,
+        getCommerceFulfillmentOrderDetail: unsupported,
+        getShipmentsOverview: unsupported,
+    };
+}

package/dist/fulfillment/normalizedFulfillmentFacts.d.ts

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

package/dist/fulfillment/normalizedFulfillmentFacts.js

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

package/dist/fulfillment/observationProjection.d.ts

@@ -0,0 +1,32 @@
+import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation, FulfillmentObservationCodecs } from "./contracts/index.js";
+export declare function projectCorrelation(value: FulfillmentObservation["correlation"], privacy?: {
+    token(value: string | null | undefined, codec?: (value: string) => string | null): string | null;
+    readonly redactedFieldCount: number;
+}, codecs?: FulfillmentObservationCodecs): FulfillmentObservation["correlation"];
+export declare function projectProviderStatus(value: NonNullable<FulfillmentObservation["providerStatus"]>, privacy?: {
+    token(value: string | null | undefined, codec?: (value: string) => string | null): string | null;
+    readonly redactedFieldCount: number;
+}): NonNullable<FulfillmentObservation["providerStatus"]>;
+export type PollEvidence = Pick<FulfillmentObservation, "correlation" | "eventKey" | "providerStatus" | "diagnostics">;
+/** Unknown-status quarantine/ACK evidence has the same privacy boundary as observations. */
+export declare function projectPollEvidence(value: PollEvidence): PollEvidence;
+/** One URL policy: strict default, optional adopter codec, and approval at every sink. */
+export declare function publicTrackingUrl(value: string, approve?: (url: string) => boolean, codec?: (url: string) => string | null): string | null;
+export declare function projectTrackingReference(value: FulfillmentObservation["trackingRefs"][number], privacy?: {
+    token(value: string | null | undefined, codec?: (value: string) => string | null): string | null;
+    readonly redactedFieldCount: number;
+}, approveTrackingUrl?: (url: string) => boolean, codecs?: FulfillmentObservationCodecs): {
+    trackingNumber: string;
+    carrierRef: string | null;
+    serviceRef: string | null;
+    publicUrl: string | null;
+} | null;
+/** New boundary projection: arbitrary adapter properties are never durable. */
+export declare function projectObservation(value: FulfillmentObservation, approveTrackingUrl?: (url: string) => boolean, codecs?: FulfillmentObservationCodecs): FulfillmentObservation;
+/** Donor finished-picking boundary is narrower than the coarse packing stage. */
+export declare const observationStatusPolicy: {
+    consumesStock: (status: CanonicalLocalFulfillmentStatus) => boolean;
+    handsOver: (status: CanonicalLocalFulfillmentStatus) => boolean;
+    suppressDispatched: (status: CanonicalLocalFulfillmentStatus) => status is "delivered";
+    trackingStatus: (status: CanonicalLocalFulfillmentStatus) => "in_transit" | "delivered";
+};