@openlup/platform 0.21.0 → 0.23.0

package/src/fulfillment/contracts/dispatch.ts

@@ -0,0 +1,73 @@
+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. Contact PII stays transient; only allowlisted mapped items enter 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; lotRef?: string | null; expirationDate?: string | null }[];
+  selection: FulfillmentSelection;
+}
+/** Allowlisted durable evidence; fingerprint commits to actual adapter command bytes. */
+export interface DispatchEvidence {
+  redactedFieldCount?: number;
+  commandFingerprint: string;
+  contactRevision: FulfillmentDispatchRequest["contactRevision"];
+  providerRef: string;
+  carrierRef: string | null;
+  serviceRef: string | null;
+  transcript?: {
+    itemCount: number;
+    items: readonly { skuRef: string; quantity: number; lotRef: string | null; expirationDate: string | null }[];
+    deliveryKind: DeliveryKind; pickupPointRef: string | null;
+    /** Count of populated reference/date fields redacted by the durable projection. */
+    redactedFieldCount?: number;
+  };
+  mapping?: { source: "dispatch_worker"; mode: "shadow" | "stage" | "live"; shadowMode: boolean };
+}
+export interface FulfillmentOperationError {
+  redactedFieldCount?: number;
+  code: string; status: number | null; retryable: boolean; mayHaveSucceeded: boolean;
+  /** Machine cause only; never an arbitrary exception message. */
+  cause?: string;
+}
+export type FulfillmentDispatchResult = ({ error?: FulfillmentOperationError; redactedFieldCount?: number } & (
+  | { kind: "accepted"; externalRef: string; evidence: DispatchEvidence; providerAttemptKey: string; labelKey: string; recovery?: { source: "persisted_acceptance"; proof: "persisted_external_ref"; noProviderPost: true } }
+  | { 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>;
+}

package/src/fulfillment/contracts/index.ts

@@ -0,0 +1,18 @@
+export type { FulfillmentOperationError, 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, FulfillmentObservationCodecs, FulfillmentObservationPort, FulfillmentTrackingReference } from "./observation.js";
+export type { FulfillmentReadbackResult, FulfillmentReadbackPort, FulfillmentReconciliationObservation, FulfillmentObservationPagePort } 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/src/fulfillment/contracts/label.ts

@@ -0,0 +1,9 @@
+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/src/fulfillment/contracts/nativeUnsupported.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/src/fulfillment/contracts/observation.ts

@@ -0,0 +1,26 @@
+import type { NormalizedFulfillmentFact } from "@openlup/core/fulfillment";
+import type { CanonicalLocalFulfillmentStatus } from "./index.js";
+import type { FulfillmentRefusal } from "./dispatch.js";
+/** Explicit adopter policy, forwarded through each durable observation projection. */
+export interface FulfillmentObservationCodecs {
+  approveReference?(value: string): boolean;
+  /** Overrides the query/fragment default; HTTPS, no credentials and URL approval still apply. */
+  trackingUrl?(url: string): string | null;
+}
+export interface FulfillmentTrackingReference { trackingNumber: string; /** Normalized carrier kind, never a raw provider code. */ 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[];
+  /** Original provider status tokens; canonical status does not identify an occurrence. */
+  providerStatus?: { primary: string | null; subStatus: string | null };
+  diagnostics?: { redactedFieldCount?: number; admission?: { rejectedTrackingRefs: number; rejectedTrackingUrls: number }; 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; diagnostics?: { invalidTimestamp?: true; rejectedCorrelationRefs?: number } }>;
+}

package/src/fulfillment/contracts/operator.ts

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

package/src/fulfillment/contracts/read.ts

@@ -0,0 +1,42 @@
+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/src/fulfillment/contracts/readback.ts

@@ -0,0 +1,24 @@
+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>;
+}
+
+/** Collection observation is separate from authoritative exact lookup. */
+export type FulfillmentReconciliationObservation = FulfillmentReadbackResult | {
+  kind: "unmapped"; externalRef: string | null;
+  evidence: Pick<FulfillmentObservation, "correlation" | "eventKey" | "providerStatus" | "diagnostics">;
+};
+export interface FulfillmentObservationPagePort {
+  readPage(input: { page: number; size: number }): Promise<
+    | { kind: "page"; rows: readonly FulfillmentReconciliationObservation[] }
+    | { kind: "page_exhausted" }
+    | { kind: "failed"; refusal: FulfillmentRefusal; error?: import("./dispatch.js").FulfillmentOperationError }
+  >;
+}

package/src/fulfillment/contracts/replacement.ts

@@ -0,0 +1,15 @@
+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/src/fulfillment/contracts/store.ts

@@ -0,0 +1,27 @@
+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;
+  acceptance?: Extract<FulfillmentDispatchResult, { kind: "accepted" }> | null;
+}
+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/src/fulfillment/contracts/sync.ts

@@ -0,0 +1,72 @@
+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;
+  /** Per-entry bounded diagnostics and run evidence in the existing cursor JSON, never raw errors. */
+  syncRunId?: string;
+  counts?: { checked: number; updated: number; movements: number; rejected: number; failures: number; providerCalls: number; readBacks: number };
+  items?: readonly { kind?: "stock" | "movement"; itemIndex: number; skuRef: string | null; status: "recorded" | "failed" | "rejected"; reason?: string;
+    activeReserved?: number; sellableNow?: number | null; coverageGapQuantity?: number }[];
+  alerts?: readonly { skuRef: string; thresholdKind: Exclude<Threshold, "forecast">; severity: "info" | "warning" | "critical";
+    providerForSaleQuantity: number; localAvailableQuantity: number; detectedAt: string;
+    activeReserved?: number; coverageGapQuantity?: number; gapHours?: number; thresholdHours?: number }[];
+  staleSync?: { gapHours: number; thresholdHours: number; detectedAt: string };
+  error?: { reason: string; providerError?: { operation: "get_stock" | "get_stock_movements"; status: number | null; code: string; retryable: boolean } } | 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 {
+  /** Rejected rows carry only their input index and a closed reason, never an unsafe reference. */
+  getStock(): Promise<(StockSnapshot | { kind: "rejected"; itemIndex: number; reason: "invalid_sku_ref" })[]>;
+  getStockMovements(input?: { startLocalDate?: string; endLocalDate?: string; size?: number }): Promise<(StockMovement | { kind: "rejected"; itemIndex: number; reason: "invalid_sku_ref" })[]>;
+}
+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 }>;
+}

package/src/fulfillment/currentFulfillmentParcel.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/src/fulfillment/delayReadModel.ts

@@ -0,0 +1,60 @@
+import type { CustomerDeliveryAlignment, FulfillmentCustomerAlignmentRowsReader } from './contracts/customerAlignment.js';
+import type { FulfillmentNativeUnsupported } from './contracts/nativeUnsupported.js';
+import { isNativeUnsupported } from './handlerSupport.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 async function readFulfillmentDelay(
+  readRows: DeliveryAlignmentRowsReader | undefined,
+  nextCycleAtBySubscription: ReadonlyMap<string, string | null>,
+): Promise<Map<string, CustomerDeliveryAlignment> | FulfillmentNativeUnsupported> {
+  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: DeliveryAlignmentRow[],
+  nextCycleAtBySubscription: ReadonlyMap<string, string | null>,
+): Map<string, CustomerDeliveryAlignment> {
+  const result = new Map<string, CustomerDeliveryAlignment>();
+  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: string | null, right: string | null): boolean {
+  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: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function nullableText(value: unknown): string | null {
+  return typeof value === "string" && value ? value : null;
+}

package/src/fulfillment/deliveryAlignmentReadModel.ts

@@ -0,0 +1,15 @@
+import type { DeliveryAlignmentPort } from './contracts/index.js';
+import type { PgExecutor } from './postgresDispatchStore.js';
+
+/** Server-authorized projection; database browser roles have no direct access. */
+export async function readDeliveryAlignment(db: PgExecutor, fulfillmentRef: string): ReturnType<DeliveryAlignmentPort['read']> {
+  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/src/fulfillment/dispatchProjection.ts

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import type { DispatchEvidence, DispatchRecord, FulfillmentDispatchRequest, FulfillmentDispatchResult, FulfillmentOperationError } from "./contracts/index.js";
+
+/** Machine identities only: arbitrary exception prose, URLs and credentials are omitted. */
+export function safeDiagnosticCode(value: unknown): string | null {
+  return reference(value) && typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_]{0,95}$/u.test(value) ? value : null;
+}
+export function localFailureReason(stage: string, error: unknown, privacy = durableStrings()): string {
+  if (!error || typeof error !== "object") return stage;
+  const fields = error as { code?: unknown; causeCode?: unknown; causeMessage?: unknown; message?: unknown };
+  const diagnostic = (value: unknown) => typeof value === "string" ? privacy.token(value, safeDiagnosticCode) : null;
+  const ownCode = diagnostic(fields.code), causeCode = diagnostic(fields.causeCode), causeMessage = diagnostic(fields.causeMessage);
+  const messagePattern = /^([A-Za-z][A-Za-z0-9_]*)(?::([A-Z0-9]{5}))?$/u;
+  const safeMessage = typeof fields.message === "string" ? privacy.token(fields.message, value => messagePattern.test(value) ? value : null) : null;
+  const message = safeMessage?.match(messagePattern);
+  const cause = causeMessage ?? (message && (message[2] || /_(?:failed|down|missing|invalid|conflict|not_found)$/u.test(message[1]!)) ? safeDiagnosticCode(message[1]) : null);
+  const code = causeCode ?? ownCode ?? message?.[2];
+  return [stage, cause, code].filter(Boolean).join(":");
+}
+export function operationError(error: Omit<FulfillmentOperationError, "cause"> & { cause?: unknown }): FulfillmentOperationError {
+  const privacy = durableStrings(error.redactedFieldCount);
+  const code = privacy.token(error.code, safeDiagnosticCode) ?? "operation_failed";
+  const cause = typeof error.cause === "string" ? privacy.token(error.cause,
+    value => /^ack(?::[A-Za-z0-9_]{1,96}){0,2}$/u.test(value) ? value.slice(0,180) : null) : null;
+  return { code, status: Number.isInteger(error.status) && error.status! >= 100 && error.status! <= 599 ? error.status : null,
+    retryable: error.retryable === true, mayHaveSucceeded: error.mayHaveSucceeded === true,
+    ...(cause ? { cause } : {}), ...(privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {}) };
+}
+// The fulfillment opaque-ID rule; never accept free-form metadata as a reference.
+export const reference = (value: unknown): string | null => typeof value === "string"
+  && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value) ? value : null;
+/** Opaque by default; an explicit allowlist can admit wider incumbent references. */
+export function admittedReference(value: string | null | undefined, approve?: (value: string) => boolean): string | null {
+  if (typeof value !== "string" || /[\p{Cc}\p{Cf}]/u.test(value)) return null;
+  const admitted = approve ? approve(value) : reference(value) !== null;
+  const text = value.trim();
+  return admitted && text && text.length <= 256 && !/[@]|[a-z][a-z0-9+.-]*:\/\//iu.test(text) ? text : null;
+}
+const isoDate = (value: string | null | undefined): string | null => typeof value === "string"
+  && /^\d{4}-\d\d-\d\d$/u.test(value) && Number.isFinite(Date.parse(value))
+  && new Date(value).toISOString().slice(0, 10) === value ? value : null;
+/** One counted sanitizer for durable projections; codecs are explicit host policy. */
+export function durableStrings(priorCount = 0) {
+  let count = Number.isSafeInteger(priorCount) && priorCount > 0 ? priorCount : 0;
+  return {
+    token(value: string | null | undefined, codec: (value: string) => string | null = reference) {
+      if (value == null) return null;
+      const safe = codec(value);
+      if (safe === null) count += 1;
+      return safe;
+    },
+    get redactedFieldCount() { return count; },
+  };
+}
+/** Copy only the durable allowlist, including when an adapter object has extra runtime properties. */
+export function dispatchEvidence(evidence: DispatchEvidence): DispatchEvidence {
+  const privacy = durableStrings(evidence.redactedFieldCount ?? evidence.transcript?.redactedFieldCount);
+  const sanitize = privacy.token;
+  const commandFingerprint = evidence.commandFingerprint;
+  const source = evidence.contactRevision.source;
+  const providerRef = sanitize(evidence.providerRef) ?? "redacted", carrierRef = sanitize(evidence.carrierRef), serviceRef = sanitize(evidence.serviceRef);
+  const mode = evidence.mapping ? (sanitize(evidence.mapping.mode) ?? "shadow") as NonNullable<DispatchEvidence["mapping"]>["mode"] : null;
+  const transcript = evidence.transcript ? {
+    itemCount: evidence.transcript.items.length,
+    items: evidence.transcript.items.map(item => ({ skuRef: sanitize(item.skuRef) ?? "redacted", quantity: Number.isSafeInteger(item.quantity) && item.quantity > 0 ? item.quantity : 0,
+      lotRef: sanitize(item.lotRef), expirationDate: sanitize(item.expirationDate, isoDate) })),
+    deliveryKind: evidence.transcript.deliveryKind === "parcel-locker" ? "parcel-locker" as const : "courier" as const,
+    pickupPointRef: sanitize(evidence.transcript.pickupPointRef),
+    ...(privacy.redactedFieldCount > 0 ? { redactedFieldCount: privacy.redactedFieldCount } : {}),
+  } : null;
+  return {
+    commandFingerprint,
+    contactRevision: { schemaVersion: evidence.contactRevision.schemaVersion, source, revision: evidence.contactRevision.revision },
+    providerRef, carrierRef, serviceRef,
+    ...(transcript ? { transcript } : privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {}),
+    ...(evidence.mapping ? { mapping: { source: "dispatch_worker" as const, mode: mode!, shadowMode: evidence.mapping.mode === "shadow" } } : {}),
+  };
+}
+/** Shadow has a local command identity; it never invokes a provider or resolves credentials. */
+export function shadowDispatchEvidence(request: FulfillmentDispatchRequest): DispatchEvidence {
+  if (!request.selection.providerRef || !request.lines.length || request.lines.some(line => !Number.isSafeInteger(line.quantity) || line.quantity <= 0)) throw new Error("dispatch_shadow_command_invalid");
+  return dispatchEvidence({ commandFingerprint: createHash("sha256").update(JSON.stringify(request)).digest("hex"),
+    contactRevision: request.contactRevision, providerRef: request.selection.providerRef,
+    carrierRef: request.selection.carrierRef, serviceRef: request.selection.serviceRef,
+    transcript: { itemCount: request.lines.length, items: request.lines.map(line => ({ skuRef: line.skuRef, quantity: line.quantity,
+      lotRef: line.lotRef ?? null, expirationDate: line.expirationDate ?? null })),
+      deliveryKind: request.selection.deliveryKind, pickupPointRef: request.selection.pickupPoint?.id ?? null } });
+}
+export function dispatchResult(result: FulfillmentDispatchResult): FulfillmentDispatchResult {
+  const privacy = durableStrings(result.redactedFieldCount);
+  const externalRef = result.kind === "accepted" ? privacy.token(result.externalRef) ?? "redacted" : null;
+  const refusal = result.kind !== "accepted" ? { reason: (privacy.token(result.refusal.reason) ?? "malformed") as typeof result.refusal.reason,
+    phase: (privacy.token(result.refusal.phase) ?? "normalize") as typeof result.refusal.phase, retryable: result.refusal.retryable } : null;
+  const redactions = privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {};
+  const error = result.error ? { error: operationError({ ...result.error, mayHaveSucceeded: result.kind !== "not_dispatched" }) } : {};
+  switch (result.kind) {
+    case "accepted": return { kind: "accepted", externalRef: externalRef!, providerAttemptKey: result.providerAttemptKey, labelKey: result.labelKey, ...redactions, evidence: dispatchEvidence(result.evidence), ...error,
+      ...(result.recovery ? { recovery: { source: "persisted_acceptance", proof: "persisted_external_ref", noProviderPost: true } } : {}) };
+    case "not_dispatched": return { kind: "not_dispatched", effectMayHaveSucceeded: false, refusal: refusal!, ...redactions, ...error };
+    case "unknown": return { kind: "unknown", effectMayHaveSucceeded: true, refusal: refusal!, ...redactions, ...error };
+  }
+}
+export function acceptedProviderProof(record: DispatchRecord | null): record is DispatchRecord & { externalRef: string } {
+  return Boolean(record?.externalRef && (record.status === "created" || record.status === "uncertain"));
+}