@openlup/platform 0.20.0 → 0.22.0

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

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

@@ -0,0 +1,110 @@
+import type { SubscriptionCycleStatus } from '@openlup/core/subscription';
+import type { PaymentIntentStatus } from '@openlup/core/payment';
+import type { FulfillmentNativeUnsupported } from './nativeUnsupported.js';
+export type FulfillmentOrderStatus = 'draft' | 'pending_payment' | 'paid' | 'failed' | 'expired' | 'fulfillment_pending' | 'cancelled' | 'fulfilled' | 'refunded';
+export type FulfillmentPaymentStatus = 'not_started' | PaymentIntentStatus;
+export interface FulfillmentCommerceOrder {
+    id: string;
+    orderId: string;
+    clientId: string | null;
+    status: 'created' | 'packed' | 'label_pending' | 'label_created' | 'handed_over' | 'in_transit' | 'delivered' | 'exception' | 'cancelled';
+    providerKind: string | null;
+    providerTrackingId: string | null;
+    shippingAddress: {
+        addressId: string;
+        clientId: string;
+        label: string | null;
+        line1: string;
+        line2: string | null;
+        city: string;
+        postalCode: string;
+        country: string;
+    };
+    lines: {
+        id: string | null;
+        orderItemId: string;
+        skuId: string;
+        sku: string;
+        title: string | null;
+        quantity: number;
+        inventoryReservationIds: string[];
+        productSnapshot: Record<string, unknown>;
+    }[];
+    payment: {
+        paymentIntentId: string;
+        paymentStatus: FulfillmentPaymentStatus;
+        providerPaymentId: string | null;
+    };
+    inventory: {
+        status: 'not_checked' | 'reserved' | 'missing' | 'released' | 'expired' | 'consumed' | 'review_required';
+        reservationId: string | null;
+        reservationStatus: 'reserved' | 'consumed' | 'released' | 'expired' | null;
+        expiresAt: string | null;
+        locationId: string | null;
+        locationCode: string | null;
+    };
+    omsEligibility: {
+        allowed: boolean;
+        reason: 'order_not_paid' | 'payment_not_succeeded' | 'subscription_cycle_not_paid' | 'active_hold' | 'missing_shipping_address' | 'inventory_review' | 'risk_review' | null;
+    };
+    latestOperation: {
+        id: string;
+        type: 'created' | 'packed' | 'provider_attempt_recorded' | 'label_created' | 'handed_over' | 'tracking_event_recorded' | 'cancelled';
+        occurredAt: string;
+        actorUserId: string | null;
+        payload: Record<string, unknown>;
+    } | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface FulfillmentOrdersListRequest {
+    page: number;
+    pageSize: number;
+    status?: FulfillmentCommerceOrder['status'];
+}
+export interface FulfillmentOrderDetailRequest {
+    fulfillmentOrderId?: string;
+    orderId?: string;
+}
+export interface FulfillmentOrdersListResponse {
+    contractVersion: 'commerce.fulfillment.v0';
+    orders: FulfillmentCommerceOrder[];
+    totalCount: number;
+    page: number;
+    pageSize: number;
+}
+export interface FulfillmentOrderDetailResponse {
+    contractVersion: 'commerce.fulfillment.v0';
+    order: FulfillmentCommerceOrder;
+}
+/** Host-owned persisted projections. Payment statuses already come from the payments projection. */
+export interface FulfillmentCommerceReadPort {
+    listCommerceFulfillmentOrders(request: FulfillmentOrdersListRequest): Promise<FulfillmentOrdersListResponse | FulfillmentNativeUnsupported>;
+    getCommerceFulfillmentOrderDetail(request: FulfillmentOrderDetailRequest): Promise<FulfillmentOrderDetailResponse | null | FulfillmentNativeUnsupported>;
+}
+export interface FulfillmentShipmentsOverviewRequest {
+    shippedFilter: 'today' | '7d' | '30d' | 'all';
+}
+/** Bucket rows are opaque host data; native shipment counts cannot replace these buckets. */
+export interface FulfillmentShipmentsOverviewResponse {
+    approved: Record<string, unknown>[];
+    packing: Record<string, unknown>[];
+    shippedToday: number;
+    shipped: Record<string, unknown>[];
+}
+export interface FulfillmentShipmentsOverviewPort {
+    getShipmentsOverview(request: FulfillmentShipmentsOverviewRequest): Promise<FulfillmentShipmentsOverviewResponse | FulfillmentNativeUnsupported>;
+}
+/** Existing commerce eligibility remains host-owned; the read model only supplies its facts. */
+export interface FulfillmentCommerceReadPolicy {
+    evaluateCommerceFulfillmentEligibility(input: {
+        orderMode: 'one_time' | 'subscription_cycle';
+        orderStatus: FulfillmentOrderStatus;
+        paymentStatus: FulfillmentPaymentStatus;
+        subscriptionCycleStatus: SubscriptionCycleStatus | null;
+        activeHoldCount: number;
+        hasShippingAddress: boolean;
+        inventoryStatus: FulfillmentCommerceOrder['inventory']['status'];
+    }): FulfillmentCommerceOrder['omsEligibility'];
+}
+export type { FulfillmentProgressInput, FulfillmentProgressPresentation } from "@openlup/core/fulfillment";

package/dist/fulfillment/contracts/read.js

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

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

@@ -0,0 +1,38 @@
+import type { FulfillmentObservation } from "./observation.js";
+import type { FulfillmentRefusal } from "./dispatch.js";
+export type FulfillmentReadbackResult = {
+    kind: "found";
+    externalRef: string;
+    createdAt: string | null;
+    updatedAt: string | null;
+    observation: FulfillmentObservation;
+} | {
+    kind: "absent";
+    scope: {
+        providerRef: string;
+        requestKey: string;
+        fulfillmentRef: string;
+        externalRef: string | null;
+    };
+    proof: {
+        kind: "authoritative_exact_lookup";
+        evidenceRef: `evidence:${string}`;
+        checkedAt: string;
+    };
+} | {
+    kind: "unknown";
+    refusal: FulfillmentRefusal;
+} | {
+    kind: "unsupported";
+    refusal: FulfillmentRefusal;
+};
+export interface FulfillmentReadbackPort {
+    /** Empty pages and missing local rows cannot certify external absence. */
+    read(input: {
+        providerRef: string;
+        requestKey: string;
+        fulfillmentRef: string;
+        externalRef: string | null;
+        mode: "command" | "parcel";
+    }): Promise<FulfillmentReadbackResult>;
+}

package/dist/fulfillment/contracts/readback.js

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

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

@@ -0,0 +1,34 @@
+import type { FulfillmentNativeUnsupported } from './nativeUnsupported.js';
+export interface FulfillmentReplacementRequest {
+    idempotencyKey: string;
+    actorUserId: string;
+    orderId: string;
+    reason: 'damaged' | 'lost' | 'returned_undelivered' | 'other';
+    metadata?: Record<string, unknown>;
+}
+export interface FulfillmentReplacementResult {
+    contractVersion: 'commerce.v0';
+    operation: {
+        id: string;
+        orderId: string;
+        type: 'hold_created' | 'hold_released' | 'fulfillment_reviewed' | 'support_note' | 'shipping_address_updated' | 'order_marked_refunded' | 'order_cancelled_manual' | 'replacement_shipment_requested';
+        holdId: string | null;
+        actorUserId: string | null;
+        occurredAt: string;
+        payload: Record<string, unknown>;
+    };
+    replacement: {
+        fulfillmentOrderId: string;
+        orderId: string;
+        sequenceNo: number;
+        replacesFulfillmentOrderId: string;
+        reason: FulfillmentReplacementRequest['reason'];
+        status: string;
+    };
+    releasedHoldIds: string[];
+    replayed: boolean;
+}
+/** Host owns atomic paid/contact/current-parcel/hold/reservation checks and actor-bound fingerprint/replay receipts. No confirmation or dispatch operation exists here. */
+export interface FulfillmentReplacementPort {
+    requestReplacementShipment(request: FulfillmentReplacementRequest): Promise<FulfillmentReplacementResult | FulfillmentNativeUnsupported>;
+}

package/dist/fulfillment/contracts/replacement.js

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

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

@@ -0,0 +1,86 @@
+import type { DispatchEvidence, FulfillmentDispatchRequest, FulfillmentDispatchResult, FulfillmentRefusal } from "./dispatch.js";
+export interface DispatchRecord {
+    dispatchRef: string;
+    requestKey: string;
+    fulfillmentRef: string;
+    orderRef: string;
+    parcelRef: string | null;
+    externalRef: string | null;
+    mode: "shadow" | "stage" | "live";
+    status: "draft" | "submitting" | "created" | "uncertain" | "failed" | "cancel_requested" | "cancelled";
+    evidence: DispatchEvidence;
+    replayed: boolean;
+}
+export interface FulfillmentStorePort {
+    read(requestKey: string): Promise<DispatchRecord | null>;
+    readCandidate(fulfillmentRef: string): Promise<FulfillmentDispatchRequest | null>;
+    prepare(fulfillmentRef: string): Promise<{
+        disposition: "ready" | "withheld";
+        contactRevision: number | null;
+    }>;
+    /** Evidence comes from adapter prepare, before any external submission. */
+    claim(input: {
+        requestKey: string;
+        fulfillmentRef: string;
+        orderRef: string;
+        parcelRef: string | null;
+        mode: DispatchRecord["mode"];
+        evidence: DispatchEvidence;
+    }): Promise<{
+        kind: "claimed";
+        record: DispatchRecord;
+    } | {
+        kind: "refused";
+        refusal: FulfillmentRefusal;
+    }>;
+    /** G14: idempotent mapped attempt; persist only prepared, sanitized evidence. */
+    recordProviderAttempt(attemptKey: string, fulfillmentRef: string, preparedEvidence: DispatchEvidence, mode: DispatchRecord["mode"], status: "recorded"): Promise<{
+        replayed: boolean;
+    }>;
+    /** Bind submission to the same prepared command fingerprint recorded by claim. */
+    begin(input: {
+        dispatchRef: string;
+        commandFingerprint: string;
+    }): Promise<{
+        kind: "begun";
+        record: DispatchRecord;
+        begun: boolean;
+        replayed: boolean;
+    } | {
+        kind: "refused";
+        refusal: FulfillmentRefusal;
+    }>;
+    /** Accepted rescue retains externalRef as uncertain; only acknowledge closes the local acceptance atomically. */
+    finalize(input: {
+        dispatchRef: string;
+        result: FulfillmentDispatchResult;
+    }): Promise<DispatchRecord>;
+    acknowledge(input: {
+        dispatchRef: string;
+        acceptance: Extract<FulfillmentDispatchResult, {
+            kind: "accepted";
+        }>;
+    }): Promise<{
+        acknowledged: boolean;
+        replayed: boolean;
+        record: DispatchRecord;
+    }>;
+    markStaleSubmissionsUncertain(staleBefore: string): Promise<number>;
+}
+export interface FulfillmentPaidHandoffPort {
+    ensureObligation(input: {
+        requestKey: string;
+        orderRef: string;
+        paidFactRef: string;
+    }): Promise<{
+        fulfillmentRef: string;
+        replayed: boolean;
+    }>;
+    acknowledge(input: {
+        requestKey: string;
+        fulfillmentRef: string;
+    }): Promise<{
+        acknowledged: boolean;
+        replayed: boolean;
+    }>;
+}

package/dist/fulfillment/contracts/store.js

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