@openlup/core 0.21.0 → 0.22.0

package/dist/fulfillment/statusMap.d.ts

@@ -0,0 +1,220 @@
+import type { CustomerFulfillmentStep } from "./types.js";
+export interface FulfillmentStatusStage {
+    /** Layer C — the provider-neutral customer step. */
+    customerStep: CustomerFulfillmentStep;
+    /** Precedence when several signals disagree — highest rank wins. */
+    rank: number;
+    /** Linear 5-step bar position (paid0 → delivered4); off-track states pinned. */
+    phaseIndex: number;
+    /** Whether this step sits on the normal paid→delivered track. */
+    onTrack: boolean;
+    /** i18n key for the short label (progress bar + cards). */
+    stepLabelKey: string;
+    /** Polish milestone label emitted server-side into the order-detail timeline. */
+    timelineLabel: string;
+    /** Key under `account:dashboard.panels.orders.trackingPhase.*` (start tile). */
+    trackingPhaseKey: string;
+    /** Short display label contributed with the status map. */
+    label: {
+        pl: string;
+        en: string;
+    };
+    /** Layer B `local_status` / durable FSM / order-level statuses resolving here. */
+    localStatus: readonly string[];
+    omsFulfillmentStatus: string[];
+    orderStatus: string[];
+    /** Extra provider/synonym tokens that also resolve here (for token→step). */
+    aliasTokens: string[];
+    /** Contributed effect metadata, pinned by the package test's projection digest. */
+    effects: {
+        stock: string;
+        handover: boolean;
+        customerEmail: string | false;
+    };
+}
+export interface FulfillmentStatusMap {
+    version: number;
+    comment: string;
+    stages: readonly FulfillmentStatusStage[];
+}
+export declare const FULFILLMENT_STATUS_MAP: {
+    readonly version: 1;
+    readonly comment: "SINGLE SOURCE OF TRUTH for fulfillment status across all layers. Layer C (customerStep) is the spine. Providers (Layer A) map ONLY to local_status (Layer B) in their own dictionary; the UI consumes only Layer C. statusMap.test.ts keeps every layer consistent.";
+    readonly stages: readonly [{
+        readonly customerStep: "paid";
+        readonly rank: 1;
+        readonly phaseIndex: 0;
+        readonly onTrack: true;
+        readonly stepLabelKey: "account:dashboard.ordersV2.steps.paid";
+        readonly timelineLabel: "Oplacone";
+        readonly trackingPhaseKey: "paid";
+        readonly label: {
+            readonly pl: "Opłacone";
+            readonly en: "Paid";
+        };
+        readonly localStatus: readonly [];
+        readonly omsFulfillmentStatus: ["created"];
+        readonly orderStatus: ["paid", "fulfillment_pending"];
+        readonly aliasTokens: [];
+        readonly effects: {
+            readonly stock: "reserved";
+            readonly handover: false;
+            readonly customerEmail: false;
+        };
+    }, {
+        readonly customerStep: "accepted";
+        readonly rank: 2;
+        readonly phaseIndex: 1;
+        readonly onTrack: true;
+        readonly stepLabelKey: "account:dashboard.ordersV2.steps.accepted";
+        readonly timelineLabel: "Przyjete do realizacji";
+        readonly trackingPhaseKey: "accepted";
+        readonly label: {
+            readonly pl: "Przyjęte";
+            readonly en: "Accepted";
+        };
+        readonly localStatus: readonly ["provider_received"];
+        readonly omsFulfillmentStatus: ["label_pending", "label_created"];
+        readonly orderStatus: [];
+        readonly aliasTokens: ["new", "accepted", "processing", "provider_attempt_recorded"];
+        readonly effects: {
+            readonly stock: "reserved";
+            readonly handover: false;
+            readonly customerEmail: false;
+        };
+    }, {
+        readonly customerStep: "packing";
+        readonly rank: 3;
+        readonly phaseIndex: 2;
+        readonly onTrack: true;
+        readonly stepLabelKey: "account:dashboard.ordersV2.steps.packing";
+        readonly timelineLabel: "Przygotowane do wysylki";
+        readonly trackingPhaseKey: "preparing";
+        readonly label: {
+            readonly pl: "Przygotowanie";
+            readonly en: "Preparing";
+        };
+        readonly localStatus: readonly ["picking", "packed"];
+        readonly omsFulfillmentStatus: ["packed"];
+        readonly orderStatus: [];
+        readonly aliasTokens: ["picked", "in_fulfillment", "ready_for_packing", "awaiting_courier", "ready_for_pickup"];
+        readonly effects: {
+            readonly stock: "consumed";
+            readonly handover: false;
+            readonly customerEmail: false;
+        };
+    }, {
+        readonly customerStep: "transit";
+        readonly rank: 4;
+        readonly phaseIndex: 3;
+        readonly onTrack: true;
+        readonly stepLabelKey: "account:dashboard.ordersV2.steps.transit";
+        readonly timelineLabel: "W drodze";
+        readonly trackingPhaseKey: "in_transit";
+        readonly label: {
+            readonly pl: "W drodze";
+            readonly en: "In transit";
+        };
+        readonly localStatus: readonly ["in_transit"];
+        readonly omsFulfillmentStatus: ["handed_over", "in_transit"];
+        readonly orderStatus: [];
+        readonly aliasTokens: ["shipped", "shipping", "out_for_delivery", "dispatched"];
+        readonly effects: {
+            readonly stock: "consumed";
+            readonly handover: true;
+            readonly customerEmail: "shipment.dispatched";
+        };
+    }, {
+        readonly customerStep: "delivered";
+        readonly rank: 7;
+        readonly phaseIndex: 4;
+        readonly onTrack: true;
+        readonly stepLabelKey: "account:dashboard.ordersV2.steps.delivered";
+        readonly timelineLabel: "Dostarczono";
+        readonly trackingPhaseKey: "delivered";
+        readonly label: {
+            readonly pl: "Dostarczone";
+            readonly en: "Delivered";
+        };
+        readonly localStatus: readonly ["delivered"];
+        readonly omsFulfillmentStatus: ["delivered"];
+        readonly orderStatus: ["fulfilled"];
+        readonly aliasTokens: ["delivery_delivered"];
+        readonly effects: {
+            readonly stock: "consumed";
+            readonly handover: true;
+            readonly customerEmail: false;
+        };
+    }, {
+        readonly customerStep: "exception";
+        readonly rank: 5;
+        readonly phaseIndex: 1;
+        readonly onTrack: false;
+        readonly stepLabelKey: "account:dashboard.ordersV2.status.exception";
+        readonly timelineLabel: "Wymaga sprawdzenia";
+        readonly trackingPhaseKey: "exception";
+        readonly label: {
+            readonly pl: "Wymaga sprawdzenia";
+            readonly en: "Needs review";
+        };
+        readonly localStatus: readonly ["exception"];
+        readonly omsFulfillmentStatus: ["exception"];
+        readonly orderStatus: [];
+        readonly aliasTokens: ["shipping_failed", "failed", "suspended", "returned_to_sender"];
+        readonly effects: {
+            readonly stock: "held";
+            readonly handover: false;
+            readonly customerEmail: "shipment.exception (provider exception before handoff)";
+        };
+    }, {
+        readonly customerStep: "cancelled";
+        readonly rank: 6;
+        readonly phaseIndex: 0;
+        readonly onTrack: false;
+        readonly stepLabelKey: "account:dashboard.ordersV2.status.cancelled";
+        readonly timelineLabel: "Anulowano";
+        readonly trackingPhaseKey: "cancelled";
+        readonly label: {
+            readonly pl: "Anulowano";
+            readonly en: "Cancelled";
+        };
+        readonly localStatus: readonly ["cancelled"];
+        readonly omsFulfillmentStatus: ["cancelled"];
+        readonly orderStatus: ["cancelled", "refunded"];
+        readonly aliasTokens: ["canceled"];
+        readonly effects: {
+            readonly stock: "released";
+            readonly handover: false;
+            readonly customerEmail: false;
+        };
+    }];
+};
+type CanonicalLocalFulfillmentStatus = import("./types.js").CanonicalLocalFulfillmentStatus;
+export declare const CANONICAL_LOCAL_FULFILLMENT_STATUSES: readonly CanonicalLocalFulfillmentStatus[];
+export declare const CUSTOMER_STEP_SEQUENCE: CustomerFulfillmentStep[];
+export declare function canonicalStatusToken(value: string | null | undefined): string | null;
+/**
+ * Resolve a single raw token (a Layer B `local_status`, an FSM value, an order
+ * status, or a provider/synonym) to a customer step. Exact map lookup first, then
+ * a conservative substring fallback so an unknown FUTURE token never regresses to
+ * a misleading default — it returns null and the caller decides (generic label /
+ * "paid" floor). Never guesses a more-advanced state than the token implies.
+ */
+export declare function stepForToken(token: string | null | undefined): CustomerFulfillmentStep | null;
+/**
+ * The single customer step for an order, from all its real signals (order status,
+ * durable fulfillment status, latest provider evidence). The most-advanced real
+ * signal wins by rank — so the internal `label_created` (set at OUR dispatch) can
+ * never overstate a box the provider has not started, and a real `picking`/
+ * `in_transit` is never held back by a stale internal state. Floors at "paid".
+ */
+export declare function customerStepFromSignals(tokens: Array<string | null | undefined>): CustomerFulfillmentStep;
+export declare function phaseIndexForStep(step: CustomerFulfillmentStep): number;
+/** i18n key for a step's short label (progress bar + cards). */
+export declare function stepLabelKey(step: CustomerFulfillmentStep): string;
+/** Server-emitted Polish milestone label for the order-detail timeline. */
+export declare function timelineLabelForStep(step: CustomerFulfillmentStep): string;
+/** `panels.orders.trackingPhase.*` key for a step (start-page tile). */
+export declare function trackingPhaseKeyForStep(step: CustomerFulfillmentStep): string;
+export declare function stepUsesTruckIcon(step: CustomerFulfillmentStep): boolean;
+export {};

package/dist/fulfillment/statusMap.js

@@ -0,0 +1,214 @@
+export const FULFILLMENT_STATUS_MAP = {
+    version: 1,
+    // Contributed metadata below is retained verbatim. The package-local test pins
+    // the projection digest, token round-trips and helpers; it does not check host
+    // provider dictionaries or i18n resources.
+    comment: "SINGLE SOURCE OF TRUTH for fulfillment status across all layers. Layer C (customerStep) is the spine. Providers (Layer A) map ONLY to local_status (Layer B) in their own dictionary; the UI consumes only Layer C. statusMap.test.ts keeps every layer consistent.",
+    stages: [
+        {
+            customerStep: "paid",
+            rank: 1,
+            phaseIndex: 0,
+            onTrack: true,
+            stepLabelKey: "account:dashboard.ordersV2.steps.paid",
+            timelineLabel: "Oplacone",
+            trackingPhaseKey: "paid",
+            label: { pl: "Opłacone", en: "Paid" },
+            localStatus: [],
+            omsFulfillmentStatus: ["created"],
+            orderStatus: ["paid", "fulfillment_pending"],
+            aliasTokens: [],
+            effects: { stock: "reserved", handover: false, customerEmail: false },
+        },
+        {
+            customerStep: "accepted",
+            rank: 2,
+            phaseIndex: 1,
+            onTrack: true,
+            stepLabelKey: "account:dashboard.ordersV2.steps.accepted",
+            timelineLabel: "Przyjete do realizacji",
+            trackingPhaseKey: "accepted",
+            label: { pl: "Przyjęte", en: "Accepted" },
+            localStatus: ["provider_received"],
+            omsFulfillmentStatus: ["label_pending", "label_created"],
+            orderStatus: [],
+            aliasTokens: ["new", "accepted", "processing", "provider_attempt_recorded"],
+            effects: { stock: "reserved", handover: false, customerEmail: false },
+        },
+        {
+            customerStep: "packing",
+            rank: 3,
+            phaseIndex: 2,
+            onTrack: true,
+            stepLabelKey: "account:dashboard.ordersV2.steps.packing",
+            timelineLabel: "Przygotowane do wysylki",
+            trackingPhaseKey: "preparing",
+            label: { pl: "Przygotowanie", en: "Preparing" },
+            localStatus: ["picking", "packed"],
+            omsFulfillmentStatus: ["packed"],
+            orderStatus: [],
+            aliasTokens: ["picked", "in_fulfillment", "ready_for_packing", "awaiting_courier", "ready_for_pickup"],
+            effects: { stock: "consumed", handover: false, customerEmail: false },
+        },
+        {
+            customerStep: "transit",
+            rank: 4,
+            phaseIndex: 3,
+            onTrack: true,
+            stepLabelKey: "account:dashboard.ordersV2.steps.transit",
+            timelineLabel: "W drodze",
+            trackingPhaseKey: "in_transit",
+            label: { pl: "W drodze", en: "In transit" },
+            localStatus: ["in_transit"],
+            omsFulfillmentStatus: ["handed_over", "in_transit"],
+            orderStatus: [],
+            aliasTokens: ["shipped", "shipping", "out_for_delivery", "dispatched"],
+            effects: { stock: "consumed", handover: true, customerEmail: "shipment.dispatched" },
+        },
+        {
+            customerStep: "delivered",
+            rank: 7,
+            phaseIndex: 4,
+            onTrack: true,
+            stepLabelKey: "account:dashboard.ordersV2.steps.delivered",
+            timelineLabel: "Dostarczono",
+            trackingPhaseKey: "delivered",
+            label: { pl: "Dostarczone", en: "Delivered" },
+            localStatus: ["delivered"],
+            omsFulfillmentStatus: ["delivered"],
+            orderStatus: ["fulfilled"],
+            aliasTokens: ["delivery_delivered"],
+            effects: { stock: "consumed", handover: true, customerEmail: false },
+        },
+        {
+            customerStep: "exception",
+            rank: 5,
+            phaseIndex: 1,
+            onTrack: false,
+            stepLabelKey: "account:dashboard.ordersV2.status.exception",
+            timelineLabel: "Wymaga sprawdzenia",
+            trackingPhaseKey: "exception",
+            label: { pl: "Wymaga sprawdzenia", en: "Needs review" },
+            localStatus: ["exception"],
+            omsFulfillmentStatus: ["exception"],
+            orderStatus: [],
+            aliasTokens: ["shipping_failed", "failed", "suspended", "returned_to_sender"],
+            effects: { stock: "held", handover: false, customerEmail: "shipment.exception (provider exception before handoff)" },
+        },
+        {
+            customerStep: "cancelled",
+            rank: 6,
+            phaseIndex: 0,
+            onTrack: false,
+            stepLabelKey: "account:dashboard.ordersV2.status.cancelled",
+            timelineLabel: "Anulowano",
+            trackingPhaseKey: "cancelled",
+            label: { pl: "Anulowano", en: "Cancelled" },
+            localStatus: ["cancelled"],
+            omsFulfillmentStatus: ["cancelled"],
+            orderStatus: ["cancelled", "refunded"],
+            aliasTokens: ["canceled"],
+            effects: { stock: "released", handover: false, customerEmail: false },
+        },
+    ],
+};
+export const CANONICAL_LOCAL_FULFILLMENT_STATUSES = FULFILLMENT_STATUS_MAP.stages.flatMap((stage) => stage.localStatus);
+// Off-track steps render separately and are absent from the progress-bar spine.
+export const CUSTOMER_STEP_SEQUENCE = ["paid", "accepted", "packing", "transit", "delivered"];
+// Provider strings arrive in varied spelling ("IN_FULFILLMENT", "in-fulfillment",
+// "Label Created") — compare on a canonical token so casing/separator drift never
+// silently changes the mapping.
+export function canonicalStatusToken(value) {
+    const token = value?.trim().toLowerCase().replace(/[\s_-]+/g, "_");
+    return token || null;
+}
+const STAGE_BY_STEP = Object.fromEntries(FULFILLMENT_STATUS_MAP.stages.map((stage) => [stage.customerStep, stage]));
+// token → customerStep, derived from the map (localStatus + FSM + orderStatus +
+// aliasTokens). The package-local fulfillment/statusMap.test.ts witness checks
+// that each contributed token round-trips to its declared customer step.
+const STEP_LOOKUP = (() => {
+    const table = {};
+    for (const stage of FULFILLMENT_STATUS_MAP.stages) {
+        for (const token of [
+            ...stage.localStatus,
+            ...stage.omsFulfillmentStatus,
+            ...stage.orderStatus,
+            ...stage.aliasTokens,
+        ]) {
+            const canon = canonicalStatusToken(token);
+            if (canon)
+                table[canon] = stage.customerStep;
+        }
+    }
+    return table;
+})();
+/**
+ * Resolve a single raw token (a Layer B `local_status`, an FSM value, an order
+ * status, or a provider/synonym) to a customer step. Exact map lookup first, then
+ * a conservative substring fallback so an unknown FUTURE token never regresses to
+ * a misleading default — it returns null and the caller decides (generic label /
+ * "paid" floor). Never guesses a more-advanced state than the token implies.
+ */
+export function stepForToken(token) {
+    const canon = canonicalStatusToken(token);
+    if (!canon)
+        return null;
+    const exact = STEP_LOOKUP[canon];
+    if (exact)
+        return exact;
+    if (/deliver/.test(canon))
+        return "delivered";
+    if (/cancel/.test(canon))
+        return "cancelled";
+    if (/exception|fail/.test(canon))
+        return "exception";
+    if (/transit|dispatch|shipp|out_for/.test(canon))
+        return "transit";
+    if (/pack|pick|fulfil/.test(canon))
+        return "packing";
+    if (/label|accept|received|processing/.test(canon) || canon === "new")
+        return "accepted";
+    if (/paid|created/.test(canon))
+        return "paid";
+    return null;
+}
+/**
+ * The single customer step for an order, from all its real signals (order status,
+ * durable fulfillment status, latest provider evidence). The most-advanced real
+ * signal wins by rank — so the internal `label_created` (set at OUR dispatch) can
+ * never overstate a box the provider has not started, and a real `picking`/
+ * `in_transit` is never held back by a stale internal state. Floors at "paid".
+ */
+export function customerStepFromSignals(tokens) {
+    let best = null;
+    let bestRank = -1;
+    for (const token of tokens) {
+        const step = stepForToken(token);
+        if (!step)
+            continue;
+        const rank = STAGE_BY_STEP[step].rank;
+        if (rank > bestRank) {
+            bestRank = rank;
+            best = step;
+        }
+    }
+    return best ?? "paid";
+}
+export function phaseIndexForStep(step) {
+    return STAGE_BY_STEP[step].phaseIndex;
+}
+/** i18n key for a step's short label (progress bar + cards). */
+export function stepLabelKey(step) {
+    return STAGE_BY_STEP[step].stepLabelKey;
+}
+/** Server-emitted Polish milestone label for the order-detail timeline. */
+export function timelineLabelForStep(step) {
+    return STAGE_BY_STEP[step].timelineLabel;
+}
+/** `panels.orders.trackingPhase.*` key for a step (start-page tile). */
+export function trackingPhaseKeyForStep(step) {
+    return STAGE_BY_STEP[step].trackingPhaseKey;
+}
+export function stepUsesTruckIcon(step) {
+    return step === "transit" || step === "delivered";
+}

package/dist/fulfillment/trackingProgress.d.ts

@@ -0,0 +1,4 @@
+import type { FulfillmentProgressInput, FulfillmentProgressPresentation } from './types.js';
+import type { CustomerFulfillmentStep } from './types.js';
+/** The host resolves its existing step; only actual recorded milestones complete. */
+export declare function fulfillmentProgressPresentation(order: FulfillmentProgressInput, step: CustomerFulfillmentStep): FulfillmentProgressPresentation | null;

package/dist/fulfillment/trackingProgress.js

@@ -0,0 +1,42 @@
+import { CUSTOMER_STEP_SEQUENCE, phaseIndexForStep, stepForToken } from './statusMap.js';
+/** The host resolves its existing step; only actual recorded milestones complete. */
+export function fulfillmentProgressPresentation(order, step) {
+    const status = order.status.toLowerCase();
+    const rawPayment = order.paymentStatus?.toLowerCase() ?? "";
+    const payment = rawPayment === "paid" ? "succeeded" : rawPayment;
+    const paid = payment === "succeeded";
+    const terminal = status === "cancelled" || status === "refunded";
+    const orderMilestone = stepForToken(status);
+    const recordedOrderMilestone = orderMilestone !== null && orderMilestone !== "paid"
+        && CUSTOMER_STEP_SEQUENCE.includes(orderMilestone);
+    const parcelEvidence = recordedOrderMilestone || Boolean(order.fulfillmentStatus)
+        || Boolean(order.customerFulfillmentStep && step !== "paid" && !["draft", "failed", "expired"].includes(status))
+        || order.trackingTimeline.some((event) => {
+            const observed = stepForToken(event.eventType);
+            return observed !== null && observed !== "paid";
+        });
+    const advancedParcel = !terminal && parcelEvidence && step !== "paid";
+    return progressPresentation(order, step, paid, terminal, advancedParcel);
+}
+function progressPresentation(order, step, paid, terminal, advancedParcel) {
+    if (terminal || ["draft", "expired"].includes(order.status.toLowerCase())
+        || step === "exception" || step === "cancelled" || !paid && !advancedParcel)
+        return null;
+    const completed = new Set(paid ? ["paid"] : []);
+    const record = (token) => {
+        const observed = stepForToken(token);
+        // No historical inference from an index, and no payment proof from parcel tokens.
+        if (observed && observed !== "paid" && CUSTOMER_STEP_SEQUENCE.includes(observed)
+            && phaseIndexForStep(observed) <= phaseIndexForStep(step))
+            completed.add(observed);
+    };
+    if (advancedParcel) {
+        record(order.fulfillmentStatus);
+        record(step);
+        order.trackingTimeline.forEach((event) => record(event.eventType));
+    }
+    return {
+        completedSteps: [...completed],
+        currentStep: advancedParcel && step !== "delivered" ? step : null,
+    };
+}

package/dist/fulfillment/types.d.ts

@@ -0,0 +1,15 @@
+export type CanonicalLocalFulfillmentStatus = "provider_received" | "picking" | "packed" | "in_transit" | "delivered" | "exception" | "cancelled";
+export type CustomerFulfillmentStep = "paid" | "accepted" | "packing" | "transit" | "delivered" | "exception" | "cancelled";
+export interface FulfillmentProgressInput {
+    status: string;
+    paymentStatus?: string | null;
+    fulfillmentStatus?: string | null;
+    customerFulfillmentStep?: CustomerFulfillmentStep | null;
+    trackingTimeline: {
+        eventType: string;
+    }[];
+}
+export interface FulfillmentProgressPresentation {
+    completedSteps: CustomerFulfillmentStep[];
+    currentStep: CustomerFulfillmentStep | null;
+}

package/dist/fulfillment/types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/core",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Neutral D2C subscription and bundle commerce kernels; a development preview with no stable API.",
   "license": "Apache-2.0",
   "repository": {

package/release-gates.json

@@ -75,7 +75,11 @@
       "maturity": "experimental",
       "compatibilityPolicy": "internal-candidate",
       "packageSmokeEvidence": [
-        "smoke/fulfillmentStandalone.test.ts"
+        "smoke/fulfillmentStandalone.test.ts",
+        "test/fulfillmentStatusMap.test.ts",
+        "test/fulfillmentTrackingProgress.test.ts",
+        "test/fulfillmentCurrentParcel.test.ts",
+        "test/fulfillmentNormalizedFacts.test.ts"
       ],
       "entrypoint": "dist/fulfillment/index.d.ts",
       "snapshot": "api/fulfillment.api.md"
@@ -286,8 +290,8 @@
       "release-gates.json"
     ],
     "baseline": {
-      "version": "0.20.0",
-      "packedBytes": 161695
+      "version": "0.21.0",
+      "packedBytes": 161706
     },
     "browserEntries": {}
   },

package/src/fulfillment/currentFulfillmentParcel.ts

@@ -0,0 +1,94 @@
+// An order may hold more than one fulfilment row: the original at `sequence_no` 0 and a
+// replacement parcel at 1, 2, ... Several reads still have to answer with exactly one, and
+// they must all answer the same way, or the operator, the customer and the support agent
+// each see a different parcel for the same order.
+//
+// The rule, fixed once here: the parcel that *currently represents the order* is the highest
+// `sequence_no`, tie-broken by `id` descending. While every order has exactly one row - which
+// is every order until an operator can request a replacement - each function below returns
+// that row, so the reads calling them are unchanged.
+//
+// This module is the single owner of that rule. It was four near-copies across two adapters
+// and two read models before they were merged; keep it one.
+
+export type FulfillmentParcelRow = { id?: unknown; order_id?: unknown; sequence_no?: unknown };
+
+// A row read without the column, or by a query that does not select it, is the original
+// parcel - `sequence_no` carries a database default of 0 for exactly the same reason.
+export function parcelSequenceNo(row: FulfillmentParcelRow): number {
+  return typeof row.sequence_no === "number" ? row.sequence_no : 0;
+}
+
+// Negative when `left` is the more current parcel, so this sorts the current parcel first.
+// Plain codepoint order on `id`, never `localeCompare`: this has to agree with SQL's
+// `ORDER BY id DESC` over a uuid, and a collation that folds hyphens or case would not.
+export function compareParcelPrecedence(left: FulfillmentParcelRow, right: FulfillmentParcelRow): number {
+  const bySequence = parcelSequenceNo(right) - parcelSequenceNo(left);
+  if (bySequence !== 0) return bySequence;
+  const leftId = String(left.id ?? "");
+  const rightId = String(right.id ?? "");
+  if (leftId === rightId) return 0;
+  return leftId < rightId ? 1 : -1;
+}
+
+export function currentParcel<Row extends FulfillmentParcelRow>(rows: readonly Row[]): Row | null {
+  return rows.reduce<Row | null>(
+    (best, row) => (best === null || compareParcelPrecedence(row, best) < 0 ? row : best),
+    null,
+  );
+}
+
+export function currentParcelFor<Row extends FulfillmentParcelRow>(
+  rows: readonly Row[],
+  orderId: unknown,
+): Row | null {
+  return currentParcel(rows.filter((row) => row.order_id === orderId));
+}
+
+export function currentParcelPerOrder<Row extends FulfillmentParcelRow>(
+  rows: readonly Row[],
+): Map<string, Row> {
+  const byOrder = new Map<string, Row>();
+  for (const row of rows) {
+    const orderId = String(row.order_id ?? "");
+    const incumbent = byOrder.get(orderId);
+    if (!incumbent || compareParcelPrecedence(row, incumbent) < 0) byOrder.set(orderId, row);
+  }
+  return byOrder;
+}
+
+// For consumers that take `[0]` of an order's rows after filtering by `order_id`. Grouping
+// preserves each order's first-appearance position, so a result that already holds one row
+// per order comes back in exactly the order it arrived.
+export function currentParcelFirst<Row extends FulfillmentParcelRow>(rows: readonly Row[]): Row[] {
+  const byOrder = new Map<string, Row[]>();
+  for (const row of rows) {
+    const key = String(row.order_id ?? "");
+    const group = byOrder.get(key);
+    if (group) group.push(row);
+    else byOrder.set(key, [row]);
+  }
+  return [...byOrder.values()].flatMap((group) => (group.length > 1 ? [...group].sort(compareParcelPrecedence) : group));
+}
+
+// A companion row - a tracking ref, an operation, an evidence row - names the parcel it was
+// written for. Attribution is the rule the OMS summary already applies to every other companion;
+// tracking refs only joined it once `shipment_external_refs.fulfillment_order_id` existed.
+//
+// A row whose attribution is absent belongs to whichever parcel is asking. That is exactly the
+// answer every reader gave before the column existed, so no ref a writer left unattributed can
+// vanish from a customer's page - the narrowing can only ever remove a *sibling parcel's* ref.
+export type ParcelAttributedRow = { fulfillment_order_id?: unknown };
+
+export function belongsToParcel(row: ParcelAttributedRow, parcelId: unknown): boolean {
+  const attributed = row.fulfillment_order_id;
+  if (typeof attributed !== "string" || !attributed) return true;
+  return typeof parcelId === "string" && parcelId ? attributed === parcelId : true;
+}
+
+export function rowsForParcel<Row extends ParcelAttributedRow>(
+  rows: readonly Row[],
+  parcelId: unknown,
+): Row[] {
+  return rows.filter((row) => belongsToParcel(row, parcelId));
+}

package/src/fulfillment/index.ts

@@ -32,3 +32,23 @@ export type {
   FulfillmentTransitionSnapshot,
   TransitionConflictReason,
 } from "./facts.js";
+
+/** @beta */
+export { FULFILLMENT_STATUS_MAP, CANONICAL_LOCAL_FULFILLMENT_STATUSES, CUSTOMER_STEP_SEQUENCE, canonicalStatusToken, stepForToken, customerStepFromSignals, phaseIndexForStep, stepLabelKey, timelineLabelForStep, trackingPhaseKeyForStep, stepUsesTruckIcon } from "./statusMap.js";
+/** @beta */
+export type { FulfillmentStatusStage, FulfillmentStatusMap } from "./statusMap.js";
+
+/** @beta */
+export { fulfillmentProgressPresentation } from "./trackingProgress.js";
+
+/** @beta */
+export { parcelSequenceNo, compareParcelPrecedence, currentParcel, currentParcelFor, currentParcelPerOrder, currentParcelFirst, belongsToParcel, rowsForParcel } from "./currentFulfillmentParcel.js";
+/** @beta */
+export type { FulfillmentParcelRow, ParcelAttributedRow } from "./currentFulfillmentParcel.js";
+
+/** @beta */
+export { isCanonicalLocalFulfillmentStatus, parseFulfillmentFact, parseFulfillmentTransitionConflict } from "./normalizedFulfillmentFacts.js";
+/** @beta */
+export type { CanonicalNormalizedFulfillmentFact, CanonicalNormalizedFulfillmentFactV1, CanonicalNormalizedFulfillmentFactV0, CanonicalCompatibleNormalizedFulfillmentFact, CanonicalFulfillmentTransitionSnapshot, CanonicalTransitionConflict } from "./normalizedFulfillmentFacts.js";
+/** @beta */
+export type { CanonicalLocalFulfillmentStatus, CustomerFulfillmentStep, FulfillmentProgressInput, FulfillmentProgressPresentation } from "./types.js";