@openlup/platform 0.21.0 → 0.22.0

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 {};

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

@@ -0,0 +1,105 @@
+type DeliveryKind = "parcel-locker" | "courier";
+type PickupPoint = {
+    id: string;
+    provider: string;
+    name: string;
+    address: {
+        line1: string;
+        postalCode: string;
+        city: string;
+        country: string;
+    };
+};
+export interface FulfillmentSelection {
+    providerRef: string | null;
+    carrierRef: string | null;
+    serviceRef: string | null;
+    deliveryKind: DeliveryKind;
+    pickupPoint: PickupPoint | null;
+}
+export interface FulfillmentRefusal {
+    reason: "not_dispatchable" | "selection_required" | "provider_mismatch" | "carrier_service_required" | "disabled" | "not_ready" | "unsupported" | "withheld" | "claim_conflict" | "contact_stale" | "stock_contention" | "local_missing" | "io_failure" | "malformed" | "untrusted" | "unsupported_event" | "stale" | "missing_correlation";
+    phase: "selection" | "prepare" | "claim" | "begin" | "dispatch" | "acknowledge" | "verify" | "normalize" | "apply" | "readback" | "sync";
+    retryable: boolean;
+}
+/** Frozen domain input, never copied into command evidence. Credentials stay in adapter closures. */
+export interface FulfillmentDispatchRequest {
+    requestKey: string;
+    fulfillmentRef: string;
+    orderRef: string;
+    orderNumber: string | null;
+    parcelRef: string | null;
+    contactRevision: {
+        schemaVersion: number;
+        source: string;
+        revision: number;
+    };
+    recipient: {
+        name: string | null;
+        email: string | null;
+        phone: string | null;
+        line1: string;
+        line2: string | null;
+        city: string;
+        postalCode: string;
+        country: string;
+        deliveryInstructions: string | null;
+        courierInstructions: string | null;
+    };
+    lines: readonly {
+        skuRef: string;
+        title: string | null;
+        quantity: number;
+        productRef: string | null;
+        packRef: string | null;
+    }[];
+    selection: FulfillmentSelection;
+}
+/** Allowlisted durable evidence; fingerprint commits to actual adapter command bytes. */
+export interface DispatchEvidence {
+    commandFingerprint: string;
+    contactRevision: FulfillmentDispatchRequest["contactRevision"];
+    providerRef: string;
+    carrierRef: string | null;
+    serviceRef: string | null;
+}
+export type FulfillmentDispatchResult = {
+    kind: "accepted";
+    externalRef: string;
+    evidence: DispatchEvidence;
+    providerAttemptKey: string;
+    labelKey: string;
+} | {
+    kind: "not_dispatched";
+    effectMayHaveSucceeded: false;
+    refusal: FulfillmentRefusal;
+} | {
+    kind: "unknown";
+    effectMayHaveSucceeded: true;
+    refusal: FulfillmentRefusal;
+};
+export type FulfillmentDispatchPrepareResult = {
+    kind: "prepared";
+    evidence: DispatchEvidence;
+} | {
+    kind: "refused";
+    refusal: FulfillmentRefusal;
+};
+export interface FulfillmentDispatchPort {
+    /**
+     * Without external submission, build the actual command and fingerprint its bytes
+     * before store claim/begin. Return only sanitized evidence; keep the raw command
+     * transient inside the adapter. Refuse not_dispatchable or the exact selection
+     * refusal when preparation cannot proceed. A contact_stale remap requires a new
+     * prepare of the rebuilt request/command before another claim/begin.
+     */
+    prepare(request: FulfillmentDispatchRequest): Promise<FulfillmentDispatchPrepareResult>;
+    /**
+     * Send exactly the prepared command identified by this evidence. Never silently
+     * rebuild a different command; absent/mismatched preparation refuses before I/O.
+     * Absent/mismatched preparation: not_dispatchable, phase dispatch, retryable false.
+     * Unknown submission outcomes require readback, never blind re-submission.
+     */
+    dispatch(request: FulfillmentDispatchRequest, evidence: DispatchEvidence): Promise<FulfillmentDispatchResult>;
+}
+export {};

package/dist/fulfillment/contracts/dispatch.js

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

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

@@ -0,0 +1,18 @@
+export type { DispatchEvidence, FulfillmentDispatchPrepareResult, FulfillmentSelection, FulfillmentDispatchRequest, FulfillmentDispatchResult, FulfillmentDispatchPort, FulfillmentRefusal } from "./dispatch.js";
+export type { LabelDocument, FulfillmentLabelPort } from "./label.js";
+/** G17 local reads/ingress persistence are inline runtime worker inputs; this provider envelope is unchanged. */
+export type { FulfillmentObservation, FulfillmentObservationPort, FulfillmentTrackingReference } from "./observation.js";
+export type { FulfillmentReadbackResult, FulfillmentReadbackPort } from "./readback.js";
+export type { SyncCursor, StockSnapshot, StockMovement, LocalStock, FulfillmentStockSyncProvider, FulfillmentStockSyncPort, FulfillmentProductSyncProvider, FulfillmentProductSyncPort } from "./sync.js";
+export type { FulfillmentCapabilityDescriptor } from "./capabilities.js";
+export type { DispatchRecord, FulfillmentStorePort, FulfillmentPaidHandoffPort } from "./store.js";
+export type { DeliveryAlignmentPort } from "./alignment.js";
+export type { FulfillmentAdapterConformanceSubject, FulfillmentAdapterConformanceEvidence } from "./conformance.js";
+export type { FulfillmentNativeUnsupported } from './nativeUnsupported.js';
+export type { FulfillmentReplacementPort, FulfillmentReplacementRequest, FulfillmentReplacementResult } from './replacement.js';
+export type { FulfillmentOperatorMutationPort, FulfillmentOperatorMutationResult } from './operator.js';
+export type { CustomerDeliveryAlignment, FulfillmentCustomerAlignmentRowsReader } from './customerAlignment.js';
+export type { FulfillmentCommerceReadPort, FulfillmentCommerceReadPolicy, FulfillmentOrderStatus, FulfillmentPaymentStatus, FulfillmentCommerceOrder, FulfillmentOrdersListRequest, FulfillmentOrdersListResponse, FulfillmentOrderDetailRequest, FulfillmentOrderDetailResponse, FulfillmentShipmentsOverviewPort, FulfillmentShipmentsOverviewRequest, FulfillmentShipmentsOverviewResponse } from './read.js';
+export type { FulfillmentProgressInput, FulfillmentProgressPresentation } from './read.js';
+export type { FulfillmentServicesOptions, FulfillmentServices } from './bindings.js';
+export type { CanonicalLocalFulfillmentStatus, CustomerFulfillmentStep } from "@openlup/core/fulfillment";

package/dist/fulfillment/contracts/index.js

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

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

@@ -0,0 +1,35 @@
+import type { FulfillmentDispatchRequest, FulfillmentRefusal } from "./dispatch.js";
+/** Durable storage pointer. No signed URL or credential belongs here. */
+export interface LabelDocument {
+    objectRef: string;
+    mediaType: "application/pdf";
+    externalRef: string | null;
+}
+export interface FulfillmentLabelPort {
+    create(input: FulfillmentDispatchRequest): Promise<{
+        kind: "created";
+        parcelRef: string;
+        document: LabelDocument | null;
+    } | {
+        kind: "refused";
+        refusal: FulfillmentRefusal;
+    }>;
+    /** Transient host response only; never part of a store record. */
+    read(document: LabelDocument): Promise<{
+        kind: "available";
+        url: string;
+        expiresAt: string | null;
+    } | {
+        kind: "refused";
+        refusal: FulfillmentRefusal;
+    }>;
+    void(input: {
+        parcelRef: string;
+        document: LabelDocument | null;
+    }): Promise<{
+        providerDeletion: "confirmed" | "unconfirmed";
+        labelDeleted: boolean;
+        canProceed: boolean;
+        refusal?: FulfillmentRefusal;
+    }>;
+}

package/dist/fulfillment/contracts/label.js

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

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

@@ -0,0 +1,6 @@
+/** Shared refusal for host-owned operations without native parity. No partial write is permitted. */
+export interface FulfillmentNativeUnsupported {
+    readonly kind: 'native_unsupported';
+    readonly reason: 'host_binding_required';
+    readonly retryable: false;
+}

package/dist/fulfillment/contracts/nativeUnsupported.js

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

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

@@ -0,0 +1,52 @@
+import type { NormalizedFulfillmentFact } from "@openlup/core/fulfillment";
+import type { CanonicalLocalFulfillmentStatus } from "./index.js";
+import type { FulfillmentRefusal } from "./dispatch.js";
+export interface FulfillmentTrackingReference {
+    trackingNumber: string;
+    carrierRef: string | null;
+    serviceRef: string | null;
+    publicUrl: string | null;
+}
+/** Durable normalized envelope. eventKey, not the receivedAt-bearing fact fingerprint, deduplicates retries. */
+export interface FulfillmentObservation {
+    fact: NormalizedFulfillmentFact<CanonicalLocalFulfillmentStatus>;
+    eventKind: "shipment.accepted" | "order.processing_started" | "order.picked" | "order.shipped" | "order.delivered" | "parcel.exception" | "parcel.cancelled";
+    eventKey: string;
+    firstReceivedAt: string;
+    correlation: {
+        orderRef: string | null;
+        fulfillmentRef: string | null;
+        externalRef: string | null;
+        orderNumber: string | null;
+        providerFulfillmentRef: string | null;
+        parcelRef: string | null;
+    };
+    trackingRefs: readonly FulfillmentTrackingReference[];
+    diagnostics?: {
+        refusal?: FulfillmentRefusal;
+        stockContention?: {
+            sqlState: "55P03";
+            phase: "provider_stock_consumed";
+            retryable: true;
+        };
+        annotation?: "recorded" | "failed";
+        recoveredPickedReceipt?: {
+            receiptRef: string;
+            closed: boolean;
+        };
+    };
+}
+export interface FulfillmentObservationPort {
+    /** Authenticate untouched bytes before parsing. Inputs live only during verification. */
+    verifyAndNormalize(input: {
+        rawBody: Uint8Array;
+        headers: Readonly<Record<string, string>>;
+        receivedAt: string;
+    }): Promise<{
+        kind: "verified";
+        observation: FulfillmentObservation;
+    } | {
+        kind: "refused";
+        refusal: FulfillmentRefusal;
+    }>;
+}

package/dist/fulfillment/contracts/observation.js

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

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

@@ -0,0 +1,64 @@
+import type { FulfillmentNativeUnsupported } from './nativeUnsupported.js';
+/** Host transaction inputs. actorUserId and idempotencyKey are required for attribution and replay receipts. */
+interface MutationInput {
+    idempotencyKey: string;
+    actorUserId: string;
+    metadata?: Record<string, unknown>;
+}
+interface ParcelMutationInput extends MutationInput {
+    fulfillmentOrderId: string;
+}
+type AdminCommerceFulfillmentCreateRequest = MutationInput & {
+    orderId: string;
+};
+type AdminCommerceFulfillmentRecordProviderAttemptRequest = ParcelMutationInput & {
+    providerKind: string;
+    status: 'recorded' | 'succeeded' | 'failed';
+    requestPayload?: Record<string, unknown>;
+    responsePayload?: Record<string, unknown>;
+    error?: string | null;
+};
+type AdminCommerceFulfillmentRecordLabelRequest = ParcelMutationInput & {
+    providerKind: string;
+    providerTrackingId: string;
+    labelUrl?: string | null;
+    deliveryEstimateDays?: number | null;
+    rawProviderPayload?: Record<string, unknown>;
+};
+type AdminCommerceFulfillmentHandOffRequest = ParcelMutationInput;
+type AdminCommerceFulfillmentTrackingEventRequest = ParcelMutationInput & {
+    status: 'in_transit' | 'delivered' | 'exception';
+    providerTrackingId?: string;
+    rawEvent?: Record<string, unknown>;
+};
+type AdminCommerceFulfillmentCancelRequest = ParcelMutationInput & {
+    reason: string;
+};
+export interface FulfillmentOperatorMutationResult {
+    contractVersion: 'commerce.fulfillment.v0';
+    fulfillmentOrderId: string;
+    orderId: string;
+    status: 'created' | 'packed' | 'label_pending' | 'label_created' | 'handed_over' | 'in_transit' | 'delivered' | 'exception' | 'cancelled';
+    replayed: boolean;
+}
+export interface FulfillmentOperatorMutationPort {
+    createCommerceFulfillmentOrder(request: AdminCommerceFulfillmentCreateRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+    recordCommerceFulfillmentProviderAttempt(request: AdminCommerceFulfillmentRecordProviderAttemptRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+    recordCommerceFulfillmentLabel(request: AdminCommerceFulfillmentRecordLabelRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+    handOffCommerceFulfillmentOrder(request: AdminCommerceFulfillmentHandOffRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+    recordCommerceFulfillmentTrackingEvent(request: AdminCommerceFulfillmentTrackingEventRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+    cancelCommerceFulfillmentOrder(request: AdminCommerceFulfillmentCancelRequest & {
+        actorUserId: string;
+    }): Promise<FulfillmentOperatorMutationResult | FulfillmentNativeUnsupported>;
+}
+export {};

package/dist/fulfillment/contracts/operator.js

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