@openlup/platform 0.21.0 → 0.22.0

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

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

@@ -0,0 +1,170 @@
+import type { FulfillmentRefusal } from "./dispatch.js";
+/** Collection identity never masquerades as a monotonic provider revision. */
+interface SyncIdentity {
+    providerRef: string;
+    syncRunId: string;
+    collectedAt: string;
+    sourceRevision: string | null;
+    revisionSource: "provider" | "collection" | "unknown";
+}
+export interface StockSnapshot extends SyncIdentity {
+    skuRef: string;
+    quantityKind: "snapshot";
+    totalQuantity: number;
+    forSaleQuantity: number;
+    reservedOrUnavailableQuantity: number;
+}
+export interface StockMovement extends SyncIdentity {
+    skuRef: string;
+    quantityKind: "movement";
+    quantity: number;
+    occurredAt: string | null;
+    operationType: string | null;
+    documentRef: string | null;
+    lotRef: string | null;
+    expirationDate: string | null;
+}
+export interface SyncCursor {
+    status: "idle" | "running" | "succeeded" | "failed";
+    lastStockSyncedAt: string | null;
+    lastMovementOccurredAt: string | null;
+    /** Sanitized continuation only; no credentials, URLs or arbitrary provider payload. */
+    continuation: {
+        nextRef: string | null;
+        startLocalDate: string | null;
+        endLocalDate: string | null;
+    };
+    /** G15: successful sellable coverage gaps; legacy absent values read as []. */
+    coverageGapSkus?: readonly string[];
+    refusal: FulfillmentRefusal | null;
+}
+export interface LocalStock {
+    skuRef: string;
+    onHand: number;
+    reserved: number;
+    unavailable: number;
+    safetyStock: number;
+}
+type Threshold = "safety_stock" | "reservation_coverage" | "forecast" | "stale_sync";
+type Conflict = "unknown_sku" | "ean_conflict" | "kind_quantity_conflict";
+export interface FulfillmentStockSyncProvider {
+    getStock(): Promise<StockSnapshot[]>;
+    getStockMovements(input?: {
+        startLocalDate?: string;
+        endLocalDate?: string;
+        size?: number;
+    }): Promise<StockMovement[]>;
+}
+export interface FulfillmentStockSyncPort {
+    readCursor(): Promise<SyncCursor | null>;
+    /** G16: unaggregated lines at the worker clock; quantity retains the four local balances. */
+    readLocalInventoryStock(requestedAt: string): Promise<readonly {
+        skuRef: string;
+        quantity: Pick<LocalStock, "onHand" | "reserved" | "unavailable" | "safetyStock">;
+        fulfillable: boolean;
+        locationStatus: "active" | "inactive";
+        lotStatus: "available" | "quarantined" | "expired" | "recalled" | null;
+        expiresAt: string | null;
+    }[]>;
+    readSkuInventoryClasses(skus: string[]): Promise<Map<string, "sellable" | "packaging" | null>>;
+    readActiveReservations(skus: string[], requestedAt: string): Promise<Map<string, number>>;
+    recordCursor(input: SyncCursor): Promise<void>;
+    recordStockSnapshot(input: {
+        requestKey: string;
+        snapshot: StockSnapshot;
+        local: LocalStock;
+        mismatchKind: "none";
+        inventoryClass: "sellable" | "packaging" | null;
+    }): Promise<{
+        replayed: boolean;
+        readBack: boolean;
+    }>;
+    recordProviderStockCurrent(input: {
+        requestKey: string;
+        snapshot: StockSnapshot;
+        inventoryClass: "sellable" | "packaging" | null;
+        lastSyncedAt: string;
+        staleAfter: string;
+    }): Promise<{
+        replayed: boolean;
+        readBack: boolean;
+    }>;
+    recordMovement(input: {
+        requestKey: string;
+        movement: StockMovement;
+    }): Promise<{
+        replayed: boolean;
+        readBack: boolean;
+    }>;
+    recordLowStockEvidence(input: {
+        requestKey: string;
+        skuRef: string;
+        thresholdKind: Exclude<Threshold, "forecast">;
+        severity: "info" | "warning" | "critical";
+        providerForSaleQuantity: number;
+        localAvailableQuantity: number;
+        syncRunId: string;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    resolveLowStockEvidence(input: {
+        skuRef: string;
+        activeThresholdKinds: Threshold[];
+        syncRunId: string;
+    }): Promise<{
+        resolved: number;
+    }>;
+}
+interface ProductPack {
+    ean: string;
+    quantity: number;
+}
+export interface FulfillmentProductSyncProvider {
+    /** null means skipped (no private push metadata), never a newly created local SKU. */
+    ensureProduct(sku: string): Promise<{
+        replayed: boolean;
+    } | null>;
+    getProductPacks(sku: string): Promise<ProductPack[]>;
+    addProductPack(sku: string, pack: ProductPack): Promise<void>;
+    listStockedSkus(): Promise<string[]>;
+}
+export interface FulfillmentProductSyncPort {
+    listLocalProductPacks(): Promise<{
+        sku: string;
+        packs: (ProductPack & {
+            kind: "unit" | "collective";
+        })[];
+    }[]>;
+    markPackSynced(input: {
+        sku: string;
+        ean: string;
+    }): Promise<void>;
+    upsertPulledPack(input: {
+        sku: string;
+        ean: string;
+        quantity: number;
+        kind: "unit" | "collective";
+    }): Promise<{
+        conflict: "none" | "local_locked_mismatch" | "ean_owned_by_other_sku" | "sku_not_found";
+        replayed: boolean;
+    }>;
+    recordReconciliationEvidence(input: {
+        requestKey: string;
+        sku: string;
+        ean: string | null;
+        conflictKind: Conflict;
+        providerQuantity: number;
+        identity: SyncIdentity;
+        refusal: FulfillmentRefusal | null;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    resolveReconciliationEvidence(input: {
+        sku: string;
+        activeConflictKinds: Conflict[];
+        syncRunId: string;
+    }): Promise<{
+        resolved: number;
+    }>;
+}
+export {};

package/dist/fulfillment/contracts/sync.js

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

package/dist/fulfillment/currentFulfillmentParcel.d.ts

@@ -0,0 +1,2 @@
+export { parcelSequenceNo, compareParcelPrecedence, currentParcel, currentParcelFor, currentParcelPerOrder, currentParcelFirst, belongsToParcel, rowsForParcel } from "@openlup/core/fulfillment";
+export type { FulfillmentParcelRow, ParcelAttributedRow } from "@openlup/core/fulfillment";

package/dist/fulfillment/currentFulfillmentParcel.js

@@ -0,0 +1 @@
+export { parcelSequenceNo, compareParcelPrecedence, currentParcel, currentParcelFor, currentParcelPerOrder, currentParcelFirst, belongsToParcel, rowsForParcel } from "@openlup/core/fulfillment";

package/dist/fulfillment/delayReadModel.d.ts

@@ -0,0 +1,11 @@
+import type { CustomerDeliveryAlignment, FulfillmentCustomerAlignmentRowsReader } from './contracts/customerAlignment.js';
+import type { FulfillmentNativeUnsupported } from './contracts/nativeUnsupported.js';
+export type DeliveryAlignmentRow = Record<string, unknown>;
+export type DeliveryAlignmentRowsReader = FulfillmentCustomerAlignmentRowsReader;
+/**
+ * Reads only customer-safe current cases. An aligned case remains current while
+ * its aligned schedule is still the subscription's next schedule; once a paid
+ * cycle advances `next_cycle_at`, the historical ledger row disappears from UI.
+ */
+export declare function readFulfillmentDelay(readRows: DeliveryAlignmentRowsReader | undefined, nextCycleAtBySubscription: ReadonlyMap<string, string | null>): Promise<Map<string, CustomerDeliveryAlignment> | FulfillmentNativeUnsupported>;
+export declare function mapCurrentDeliveryAlignments(rows: DeliveryAlignmentRow[], nextCycleAtBySubscription: ReadonlyMap<string, string | null>): Map<string, CustomerDeliveryAlignment>;

package/dist/fulfillment/delayReadModel.js

@@ -0,0 +1,45 @@
+import { isNativeUnsupported } from './handlerSupport.js';
+/**
+ * Reads only customer-safe current cases. An aligned case remains current while
+ * its aligned schedule is still the subscription's next schedule; once a paid
+ * cycle advances `next_cycle_at`, the historical ledger row disappears from UI.
+ */
+export async function readFulfillmentDelay(readRows, nextCycleAtBySubscription) {
+    const subscriptionIds = [...nextCycleAtBySubscription.keys()].filter(Boolean);
+    if (!readRows || subscriptionIds.length === 0)
+        return new Map();
+    const rows = await readRows(subscriptionIds);
+    if (isNativeUnsupported(rows))
+        return rows;
+    return mapCurrentDeliveryAlignments(rows, nextCycleAtBySubscription);
+}
+export function mapCurrentDeliveryAlignments(rows, nextCycleAtBySubscription) {
+    const result = new Map();
+    for (const row of rows) {
+        const subscriptionId = text(row.subscription_id);
+        if (!subscriptionId || result.has(subscriptionId))
+            continue;
+        const state = text(row.state);
+        if (state === "protected") {
+            result.set(subscriptionId, { state });
+            continue;
+        }
+        if (state === "aligned" && sameInstant(nullableText(row.aligned_next_cycle_at), nextCycleAtBySubscription.get(subscriptionId) ?? null)) {
+            result.set(subscriptionId, { state });
+        }
+    }
+    return result;
+}
+function sameInstant(left, right) {
+    if (!left || !right)
+        return false;
+    const leftTime = new Date(left).getTime();
+    const rightTime = new Date(right).getTime();
+    return Number.isFinite(leftTime) && leftTime === rightTime;
+}
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+function nullableText(value) {
+    return typeof value === "string" && value ? value : null;
+}

package/dist/fulfillment/deliveryAlignmentReadModel.d.ts

@@ -0,0 +1,4 @@
+import type { DeliveryAlignmentPort } from './contracts/index.js';
+import type { PgExecutor } from './postgresDispatchStore.js';
+/** Server-authorized projection; database browser roles have no direct access. */
+export declare function readDeliveryAlignment(db: PgExecutor, fulfillmentRef: string): ReturnType<DeliveryAlignmentPort['read']>;

package/dist/fulfillment/deliveryAlignmentReadModel.js

@@ -0,0 +1,12 @@
+/** Server-authorized projection; database browser roles have no direct access. */
+export async function readDeliveryAlignment(db, fulfillmentRef) {
+    const result = await db.query(`SELECT alignment.state, alignment.aligned_next_cycle_at
+    FROM public.fulfillment_shipments shipment
+    LEFT JOIN public.subscription_delivery_alignment_cases alignment ON alignment.predecessor_order_id=shipment.order_id
+    WHERE shipment.id=$1::uuid
+    ORDER BY (alignment.state IN ('protected','manual_review')) DESC, alignment.created_at ASC LIMIT 1`, [fulfillmentRef]);
+    const row = result.rows[0];
+    const date = row?.aligned_next_cycle_at;
+    return { disposition: row?.state === 'aligned' ? 'aligned' : row?.state === 'protected' ? 'outstanding' : 'manual_review',
+        nextCycleAt: date instanceof Date ? date.toISOString() : typeof date === 'string' ? date : null };
+}

package/dist/fulfillment/dispatchProjection.d.ts

@@ -0,0 +1,7 @@
+import type { DispatchEvidence, DispatchRecord, FulfillmentDispatchResult } from "./contracts/index.js";
+/** Copy only the durable allowlist, including when an adapter object has extra runtime properties. */
+export declare function dispatchEvidence(evidence: DispatchEvidence): DispatchEvidence;
+export declare function dispatchResult(result: FulfillmentDispatchResult): FulfillmentDispatchResult;
+export declare function acceptedProviderProof(record: DispatchRecord | null): record is DispatchRecord & {
+    externalRef: string;
+};

package/dist/fulfillment/dispatchProjection.js

@@ -0,0 +1,18 @@
+/** Copy only the durable allowlist, including when an adapter object has extra runtime properties. */
+export function dispatchEvidence(evidence) {
+    return {
+        commandFingerprint: evidence.commandFingerprint,
+        contactRevision: { schemaVersion: evidence.contactRevision.schemaVersion, source: evidence.contactRevision.source, revision: evidence.contactRevision.revision },
+        providerRef: evidence.providerRef, carrierRef: evidence.carrierRef, serviceRef: evidence.serviceRef,
+    };
+}
+export function dispatchResult(result) {
+    switch (result.kind) {
+        case "accepted": return { kind: "accepted", externalRef: result.externalRef, providerAttemptKey: result.providerAttemptKey, labelKey: result.labelKey, evidence: dispatchEvidence(result.evidence) };
+        case "not_dispatched": return { kind: "not_dispatched", effectMayHaveSucceeded: false, refusal: { reason: result.refusal.reason, phase: result.refusal.phase, retryable: result.refusal.retryable } };
+        case "unknown": return { kind: "unknown", effectMayHaveSucceeded: true, refusal: { reason: result.refusal.reason, phase: result.refusal.phase, retryable: result.refusal.retryable } };
+    }
+}
+export function acceptedProviderProof(record) {
+    return Boolean(record?.externalRef && (record.status === "created" || record.status === "uncertain"));
+}

package/dist/fulfillment/fulfillmentObservationEffects.d.ts

@@ -0,0 +1,66 @@
+import type { FulfillmentObservation } from "./contracts/index.js";
+/** Ledger effects for an already accepted observation; acceptance and retry belong to the caller. */
+interface FulfillmentObservationPort<TrackingStatus> {
+    markProviderStockConsumed(input: {
+        idempotencyKey: string;
+        fulfillmentOrderId: string;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    markHandedOver(input: {
+        idempotencyKey: string;
+        fulfillmentOrderId: string;
+        suppressDispatched: boolean;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    recordTrackingReference(input: {
+        idempotencyKey: string;
+        orderId: string;
+        fulfillmentOrderId: string;
+        trackingNumber: string;
+        trackingUrl: string | null;
+        carrierKind: string | null;
+        service: string | null;
+        status: TrackingStatus;
+        observation: FulfillmentObservation;
+    }): Promise<{
+        replayed: boolean;
+        readBack: boolean;
+    }>;
+}
+interface FulfillmentObservationTrackingReference {
+    trackingNumber: string;
+    trackingUrl?: string | null;
+    carrierKind?: string | null;
+    service?: string | null;
+}
+interface FulfillmentObservationInput<LocalStatus, TrackingStatus> {
+    port: FulfillmentObservationPort<TrackingStatus>;
+    localStatus: LocalStatus;
+    ids: {
+        orderId: string;
+        fulfillmentOrderId: string;
+    };
+    observation: FulfillmentObservation;
+    trackingRefs: readonly FulfillmentObservationTrackingReference[];
+    stockIdempotencyKey: string;
+    handoffIdempotencyKey: string;
+    trackingIdempotencyKey: (trackingNumber: string) => string;
+    issueAccountingInvoice?: () => Promise<void>;
+    onReplayed?: () => void;
+    onTrackingRecorded?: (result: {
+        replayed: boolean;
+        readBack: boolean;
+    }) => void;
+}
+/** Pure status decisions/projection; the mechanism owns every effect and await. */
+interface FulfillmentObservationStatusPolicy<LocalStatus, TrackingStatus> {
+    consumesStock(status: LocalStatus): boolean;
+    handsOver(status: LocalStatus): boolean;
+    suppressDispatched(status: LocalStatus): boolean;
+    trackingStatus(status: LocalStatus): TrackingStatus;
+}
+/** Stock → durable handover → every tracking reference → optional invoice. No catches or retries. */
+export declare function applyFulfillmentObservationEffects<LocalStatus, TrackingStatus>(input: FulfillmentObservationInput<LocalStatus, TrackingStatus>, policy: FulfillmentObservationStatusPolicy<LocalStatus, TrackingStatus>): Promise<void>;
+export {};