@openlup/core 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -4,10 +4,29 @@ Notable changes to this public-source workspace package are recorded here.
 “Unreleased” means no npm version carries the change yet; immutable OpenLup
 source previews may already ship some changes, and their release notes say
 which. Declaration snapshots track candidate drift, not a stable API or
-SemVer promise.
+SemVer promise. This file keeps the current release and the two previous ones;
+earlier releases are recorded verbatim in `CHANGELOG-HISTORY.md`
+in the source repository.
 
 ## [Unreleased]
 
+## [0.22.0]
+
+- Publishable on the npm `latest` dist-tag as `0.22.0`, from tag
+  `openlup-core-v0.22.0`.
+
+- Add pure fulfillment status, tracking-progress, current-parcel and canonical
+  fact-parser helpers to the existing `./fulfillment` subpath. Generic fact types
+  retain their names; narrowed fact aliases use the `Canonical` prefix. New
+  fulfillment re-exports carry the same `@beta` annotation as existing facts.
+
+Migration: existing platform fulfillment imports remain compatible re-exports;
+no application import or schema migration is required.
+
+### Known limitations
+
+- `FULFILLMENT_STATUS_MAP` carries localized adopter labels. Replace them with host-injected labels or internationalization keys before any stable-framework claim.
+
 ## [0.21.0]
 
 - Publishable on the npm `latest` dist-tag as `0.21.0`, from tag
@@ -25,345 +44,3 @@ Migration: upgrade the complete set together; core introduces no API or schema m
 - Republish unchanged APIs, runtime behavior and shipped SQL from `0.19.0` as part of the complete `0.20.0` package set.
 
 Migration: upgrade the complete set together; core introduces no API or schema migration in this release.
-
-## [0.19.0]
-
-- Publishable on the npm `latest` dist-tag as `0.19.0`, from tag
-  `openlup-core-v0.19.0`.
-
-- Republish unchanged APIs, runtime behavior and shipped SQL from `0.18.0` as part of the complete `0.19.0` package set.
-
-Migration: upgrade the complete set together; core introduces no API or schema migration in this release.
-
-## [0.18.0]
-
-- Publishable on the npm `latest` dist-tag as `0.18.0`, from tag
-  `openlup-core-v0.18.0`.
-
-- Republish unchanged APIs, runtime behavior and shipped SQL from `0.17.0` as
-  part of the complete `0.18.0` package set.
-
-Migration: upgrade the complete set together; core introduces no API or schema
-migration in this release.
-
-## [0.17.0]
-
-- Publishable on the npm `latest` dist-tag as `0.17.0`, from tag
-  `openlup-core-v0.17.0`.
-
-- Republish unchanged APIs, runtime behavior and shipped SQL as part of the
-  complete `0.17.0` package set.
-
-Baseline evidence (2026-10-20): published `0.16.0` tarball 161,232 packed bytes,
-SHA256 `48abf4ea8ddc446b8d6e2c610801e2cfcbe5575743bd5a61fbb8b8b50a2b36a3`.
-The initial `0.16.0` release-gates baseline is retained under S1 option B.
-
-## [0.16.0]
-
-- Publishable on the npm `latest` dist-tag as `0.16.0`, from tag
-  `openlup-core-v0.16.0`.
-
-- Add optional logical module selection, dependency/entry contracts, module-qualified bindings and module diagnostics to experimental `./readiness`. Each selected module retains an independent schema requirement within one artifact.
-
-Migration: additive API; existing manifests and loaded packages that omit module fields keep byte-identical readiness reports and binding keys. To opt an artifact in, observe `LoadedPackage.modules` and supply exactly one manifest `module` per selected id, with its logical kind, provided entries and in-artifact dependencies. Bind ports, triggers and routes as `package/module:id`; keep artifact kind/version and environment keys unchanged. Mixed modes, missing dependencies/entries and duplicate module/event/schedule/route ownership refuse using existing codes. Empty selections need no contributions; disabled modules need no bindings or schema probe. Inspect optional issue `module` when diagnosing module/schema failures. No release, publication or activation is performed by this change.
-
-## [0.15.0]
-
-- Publishable on the npm `latest` dist-tag as `0.15.0`, from tag
-  `openlup-core-v0.15.0`.
-
-- Republished unchanged.
-
-## [0.14.0]
-
-- Publishable on the npm `latest` dist-tag as `0.14.0`, from tag
-  `openlup-core-v0.14.0`.
-
-- Add experimental `buildGroupedPostgresSchemaProbe`, `decodeGroupedPostgresSchemaRows` and `PostgresSchemaCatalogEntry` on `./readiness` for one ordered, parameterized PostgreSQL catalog read with table, column and exact function-overload shapes. The strict decoder refuses incomplete or malformed rows without exposing catalog bodies.
-
-Migration: additive API; existing scalar probes, observations, readiness codes and deadlines remain unchanged. Catalog rows use jsonb text, definition-string/null aggregates and raw pg_policy values; the decoder accepts text only. Hosts retain connection, snapshot, identity, digest and admission ownership. This preparation targets the 0.14.0 MINOR set; merging it does not publish packages.
-
-## [0.13.1]
-
-- Publishable on the npm `latest` dist-tag as `0.13.1`, from tag
-  `openlup-core-v0.13.1`.
-
-- Republish the unchanged core API and implementation with the repaired outbox publication as the complete `0.13.1` package set.
-
-## [0.13.0]
-
-- Publishable on the npm `latest` dist-tag as `0.13.0`, from tag
-  `openlup-core-v0.13.0`.
-
-- Add experimental outbox envelope/handler descriptors, structural validation, job lease and candidate readiness contracts.
-- Check package inventory, event ownership/coverage, actual bindings and qualified schema observations before admitting a new candidate.
-
-Migration: existing exports remain; compose the selected rail and bind its schema probe before activation. Unknown observations refuse the new candidate and do not stop a serving version.
-
-
-### Changed
-
-- `AGENTS.md` gains a required "Using this package in an application" section: do not edit or
-  patch the installed package, change behaviour through its seams, and upgrade every
-  `@openlup/*` package together. `docs:check` refuses a guide without it.
-
-## [0.12.0]
-
-### Removed
-
-- **API REMOVAL: the `./checkout` subpath.** It held only an
-  `Idempotency-Key` header-shape helper that no checkout path used.
-
-  Migration: replace
-
-  ```ts
-  import { validateCheckoutIdempotencyHeader } from "@openlup/core/checkout";
-  ```
-
-  with an application-owned validator, or delete the call if, like the
-  reference checkout, your checkout carries its idempotency key in the
-  request body.
-
-### Changed
-
-- **BEHAVIOUR CHANGE for the subscription status matrix.** `cancelled` is no
-  longer terminal: `cancelled -> active` is now an allowed edge. This is the
-  owner win-back that the managed SQL guard
-  `public.subscription_guard_status_transition` already admits. Only the new
-  `reactivateSubscription` takes that edge. `resumeSubscription` still leaves
-  `paused` only and still refuses a cancelled subscription. `completed` stays
-  terminal. A caller that treated `cancelled` as final must now expect a
-  reactivated subscription to renew again.
-- **BEHAVIOUR CHANGE: an exhausted retry ladder now has a modelled outcome.** A
-  renewal whose refusals ran past the last rung may pause an active
-  subscription through `pauseSubscriptionForExpiredDunning`, which is the
-  sanctioned non-payment rule. It is the only engine path that suspends a live
-  subscription for a reason the owner did not choose. A ladder cut short by a
-  terminating refusal class, or a failure that still has a retry after it, is
-  refused as `dunning_not_exhausted` and leaves the subscription active.
-  `recordPaymentFailure` is unchanged and still never touches the subscription.
-- `SubscriptionEngineErrorCode` gains `missing_payment_method` and
-  `dunning_not_exhausted`. An exhaustive `switch` over the union must handle
-  both.
-
-- `release-gates.json` sets `packageRelease.versionRule` to `0.N.P`. Below
-  1.0 every `@openlup/*` package carries one set version: a minor set for any
-  API, behaviour or schema change, a patch set for a fix only.
-
-  Migration: a tool that reads `versionRule` expects the set rule. Before:
-  `"versionRule": "0.<n>.0"`. After: `"versionRule": "0.N.P"`.
-
-- Publishable on the npm `latest` dist-tag as `0.12.0`, from tag
-  `openlup-core-v0.12.0`.
-- Publishable on the npm `preview` dist-tag as `0.11.0`, for source preview
-  `openlup-source-preview/11`.
-- Publishable on the npm `preview` dist-tag as `0.10.0`, for source preview
-  `openlup-source-preview/10`.
-- Publishable on the npm `preview` dist-tag as `0.9.0`, for source preview
-  `openlup-source-preview/9`.
-- Publishable on the npm `preview` dist-tag as `0.7.0`, for source preview
-  `openlup-source-preview/7`.
-- Publishable on the npm `preview` dist-tag as `0.6.0`, for source preview
-  `openlup-source-preview/6`. Directory `npm publish` stays refused.
-
-- **BREAKING for `slugSchema`'s accepted language.** The `./catalog` schema no
-  longer trims its input, so a slug with leading or trailing whitespace is now
-  rejected rather than normalised and accepted, which is what the published
-  `catalogSlugFormat` it tests against always described. A caller that relied on
-  that normalisation must trim before validating.
-- **BREAKING for the retry ladder's semantics.** `nextRetryAttemptAt` now
-  TERMINATES past the end of the ladder instead of capping at its last slot: an
-  attempt beyond the configured backoff length answers `null`, which is the pause
-  signal, rather than repeating the final interval forever. The stored schedule
-  this kernel mirrors has always terminated, so the two rails now agree; the
-  previous capping behaviour meant a caller asking for attempt 4 (or 9) was told
-  a fourth charge was scheduled when none was. Callers that guarded with
-  `attempt <= maxRetryAttempts()` before calling should drop the guard — asking
-  for the next slot IS the decision, and a second copy of the budget check is how
-  the two rails drifted apart in the first place.
-
-### Added
-
-- `AGENTS.md` ships in the tarball. It states the package's kind and each
-  subpath's maturity, gives one wiring example that compiles in CI, points to
-  the shipped sources and declarations, and lists the readiness codes the
-  package raises (none yet).
-- `release-gates.json` schema 5 declares the package kind (`"kind": "kernel"`)
-  and splits the pack budget. Code files (dist JavaScript, declarations and
-  shipped sources) and root documentation and metadata files each have their
-  own caps on packed bytes and files; the tarball total stays as a backstop.
-
-  Migration: a tool that reads `release-gates.json` checks `schemaVersion: 5`.
-  Before: `"pack": { "maxPackedBytes": …, "maxFiles": … }`. After: `"pack": {
-  "code": { "maxPackedBytes": …, "maxFiles": … }, "docs": { … },
-  "maxPackedBytes": …, "maxFiles": … }`.
-- Add neutral checkout recovery evidence, method, operation and action contracts
-  to the existing payment surface. They describe guidance only and do not change
-  payment admission, renewal classification or enabled payment methods.
-- Export neutral lookup normalization from `./company-identity` for extensions.
-
-- `SUBSCRIPTION_STATUS_TRANSITIONS`, the frozen status matrix, and
-  `canTransitionSubscriptionStatus` on `./subscription`. The matrix mirrors the
-  managed SQL guard over the engine's four statuses, and a contract test
-  enumerates every ordered pair.
-- `reactivateSubscription`, the win-back from `cancelled`. It needs a stored
-  payment method and restarts the schedule `RESTART_LEAD_DAYS` (two) days out,
-  never earlier than the stored `nextCycleAt`.
-- `isDunningLadderExhausted(cycle, cadence?)` on the retry ladder. It holds when
-  a cycle is `payment_failed`, has nothing scheduled, and its attempt is past
-  `maxRetryAttempts(cadence)`.
-- `pauseSubscriptionForExpiredDunning` and
-  `resumeSubscriptionFromExpiredDunning`. The resume is the customer's recovery
-  from the non-payment pause: it takes an optional replacement method, skips the
-  uncollected cycle, and restarts the schedule like a win-back.
-- `recordPaymentFailure` takes an optional `cadence`, so a deployment ladder
-  reaches the schedule and the exhaustion check alike. Callers that pass none
-  keep the shipped ladder.
-- `recordPaymentFailure` accepts an optional neutral `failureClass` and passes it
-  to the canonical retry-ladder decision. Existing callers remain
-  source-compatible. The shipped terminating-class set is exactly
-  `["hard_do_not_retry"]`: that refusal gets no later rung, while every other
-  class keeps the existing 24h/72h/168h schedule.
-- Class-aware retry termination on `./subscription`.
-  `CycleRetryCadence` gains an optional `terminatingFailureClasses`, the new
-  `ladderTerminatedByClass(failureClass, cadence?)` answers whether the REASON
-  for a refusal ends the ladder, and `nextRetryAttemptAt` / `shouldScheduleRetry`
-  take an optional trailing `failureClass`. `DEFAULT_CYCLE_RETRY_CADENCE` ships
-  only `hard_do_not_retry`. The predicate fails open for an absent or unlisted
-  class, for a listed class the taxonomy does not recognise, and for a listed
-  class that `failureClassDecision` still permits. Only explicit membership plus
-  the taxonomy's existing refusal can end the ladder early.
-- Injectable retry cadence on `./subscription`: `CycleRetryCadence` and the
-  frozen `DEFAULT_CYCLE_RETRY_CADENCE` (24h/72h/168h). `nextRetryAttemptAt`,
-  `shouldScheduleRetry` and `maxRetryAttempts` each take an optional cadence and
-  default to the shipped one, so a deployment can publish its own ladder without
-  forking the kernel and nothing changes for a caller that passes none.
-
-- Pack budgets raised (packed 98 KiB -> 106 KiB, unpacked 448 KiB -> 480 KiB;
-  file count unchanged at 186): the new allocation kernel ships as one source file
-  plus its two build artifacts, and its adopter-facing JSDoc — the floor-clamp
-  rule, the two-line split rationale and the failure-versus-throw split — is most
-  of the added bytes. The docs are the deliverable, so the budget moves rather
-  than the docs. Measured, not estimated: clean base packs 98532/446519/183 and
-  this change packs 106488/475826/186.
-- Experimental bundle target-price allocation on `./pricing`:
-  `allocateBundleTargetPrice`, the pure kernel that turns ONE operator-set price
-  for a composed bundle into exact per-component money. Largest-remainder
-  (Hamilton) split weighted by each component's own reference subtotal, all in
-  BigInt, ties broken by component code so output never depends on input order.
-  Two rules bound it — a component never allocates below its minimum payable per
-  unit (and a component priced under that minimum is held to its own reference
-  price, because no floor may lift a component above what it is worth), and never
-  above its reference unit price. A quantity whose allocated subtotal does not
-  divide evenly emits TWO lines rather than a rounded unit price, so the
-  `unitPrice x quantity === lineSubtotal` identity every quote line refines still
-  holds. The single asserted invariant is that the emitted lines sum to the target
-  exactly. Three refusals stay data rather than exceptions: nothing to weigh
-  against, a target above the sum of the parts, and a target that cannot cover
-  every minimum payable. No clock, no randomness, no I/O.
-- Line-scoped `bundle` component in the pricing breakdown vocabulary, with an
-  optional `bundle_allocated_discount_minor` on the line input: positive on the
-  way in, emitted as one negative component, absent or zero emits nothing. It is
-  line-scoped rather than order-scoped because a bundle prices a subset of the
-  cart, and refunding one line must return exactly what that line was charged.
-- Pack budgets raised (packed 90 KiB -> 94 KiB, unpacked 416 KiB -> 432 KiB,
-  files 180 -> 186): one new kernel module ships as a source file plus its build
-  artifacts and their maps, and its adopter-facing JSDoc is most of the added
-  bytes. The docs are the deliverable, so the budget moves rather than the docs.
-- Experimental payment-method lifecycle vocabulary on `./payment`: the five
-  transitions a rail may report about a method it holds on file
-  (`method_registered`, `method_updated`, `method_revoked`, `method_expired`,
-  `method_suspended`), the neutral event an adapter translates its own event
-  names into, and the three published facts (`schemeLabel`, `lastDigits`,
-  `expiresAt`) a transition may carry — never the instrument number. Plus two
-  pure helpers: `endsStoredMethodUsability`, the single place that answers
-  whether a transition means the method can no longer back a charge (a rotation
-  is not a death), and `expiryInstantFromMonthYear`, which pins the convention
-  that a month-and-year validity runs to the LAST instant of that month in UTC.
-  No rail is named and no clock, network or storage is read.
-- Pack budgets raised (packed 88 KiB -> 90 KiB, unpacked 400 KiB -> 416 KiB): the provider-capability contracts
-  add ~0.9 KiB of shipped declarations and their adopter-facing JSDoc; the
-  docs are the deliverable, so the budget moves rather than the docs.
-- (formatting) the block-reason alias is declared single-line so the
-  generated declaration snapshot carries no trailing whitespace.
-- Experimental payment-provider capability contracts on `./payment`: a
-  descriptor an adapter publishes so renewal and dunning can decide from
-  CAPABILITIES — whether stored consent evidence must be read and whether it
-  is chargeable unattended, which provider flow an unattended charge uses,
-  what payer context the request needs, and what a stored method must satisfy
-  before a charge — plus a registry contract keyed by provider kind. Types
-  only, with no provider named and no runtime consumer yet; branching on
-  provider identity is unchanged.
-- Experimental payment-failure taxonomy on `./payment`: a pure classifier that
-  resolves a refusal into one of seven neutral classes from optional evidence
-  (scheme retry advice, adopter-asserted neutral hints, an opaque decline code
-  read through an adopter-supplied hint table, and the internal reason key),
-  with a documented precedence order, a frozen per-class retry decision record,
-  and a scheme retry ceiling helper pinned at 15 attempts per 30 days. The
-  kernel embeds no acquirer code tables and has no runtime consumer yet; retry
-  scheduling is unchanged.
-- Experimental provider-neutral payment-decline evidence on `./payment`, with
-  a provider code (never free-form prose) and retryability hint that lets
-  adopters classify synchronous PSP refusals without persisting customer data.
-  Extended with optional `declineCode` and `adviceCode`, so a refusal keeps the
-  finer bank reason and the provider's retry recommendation — both codes, never
-  messages — for a later classification policy to read. Extended again with
-  optional `neutralReasonHints`, so an adapter can carry its OWN reading of a
-  refusal — already translated out of its code vocabulary — and a classifier
-  never has to learn which adapter refused.
-- `PAYMENT_FAILURE_CLASSIFICATION_SOURCES` on `./payment`: the classification
-  sources published as a value as well as a type, so a boundary schema can
-  validate `decidedBy` against the kernel's own vocabulary instead of restating
-  it. The type is unchanged and still derives from the same four members.
-- Additive `evaluatePromotionAdjustmentsV2` API in the existing candidate
-  `./promo` subpath. It chooses one best product and shipping adjustment,
-  interprets product percentages as target-effective basis points against a
-  trusted reference subtotal, and requires an adopter-defined product floor.
-  The legacy evaluator and DB-shaped types remain unchanged for compatibility;
-  downstream applications can adopt the package boundary before any separately
-  flagged runtime cutover.
-- Experimental `./fulfillment` normalized-fact contract with explicit schema,
-  strict N/N-1 parsing, adopter-supplied canonical-status validation,
-  discriminated provenance, application-minted evidence references, comparable
-  provider ordinals, deterministic fingerprint/dedupe, and self-contained
-  transition-conflict diagnostics with strict stream/decision validation.
-- The then-current package identity and extracted-root governance evidence;
-  this is historical evidence, not authorization for a separate repository or
-  release channel.
-- Package-local documentation and governance material for the portability
-  boundary.
-- Candidate and experimental maturity metadata for the package surface.
-
-### Changed
-
-- Marked candidate/experimental declarations `@beta` and testing-only
-  declarations `@internal`, without changing package exports or runtime shapes.
-  Removed the private `./testing` neutrality matcher after moving all packaged
-  leak classes into the packed-artifact audit.
-- Reclassified all declaration snapshots as private package-surface drift proof;
-  this changes no exports, runtime behavior, dependencies, or publish refusal.
-- Raised the reviewed packed/unpacked artifact ceilings by 4/16 KiB to admit
-  the additive promo v2 declarations and implementation.
-- Replaced public-surface and freeze language with the private package-surface
-  inventory: 16 current exports have package smoke evidence but no public
-  stability claim.
-
-### Removed
-
-- Removed the unused `./external-effects` API, implementation, snapshot, and
-  self-conformance fixture before any public release. The application
-  one-writer cleanup left no runtime consumer, so external-effect retry
-  semantics stay adopter-owned instead of becoming a fourth core concern.
-
-### Security
-
-- Recorded the private vulnerability-reporting contact for this proof package.
-
-## Release Status
-
-Versions up to `0.11.0` were published on the npm `preview` dist-tag without
-sections of their own, so the `0.12.0` section also lists the changes they
-carried. A release-preparation pull request turns the Unreleased section into
-the next version's section; its release tag and npm record when it is
-published. No version establishes a stable package API or supported upgrade
-channel.

package/README.md

@@ -8,6 +8,12 @@ application" section, which `docs:check` requires, tells an application's agent
 not to edit or patch the installed package and to upgrade every `@openlup/*`
 package together.
 
+The prepared `0.22.0` set adds the pure fulfillment presentation helpers and
+retains compatible platform re-exports. Upgrade all packages together and read
+[the migration and label limitation](CHANGELOG.md#0220). The size baseline is
+the published `0.21.0` artifact; older releases remain in the source-only
+`CHANGELOG-HISTORY.md`. Preparation establishes no npm publication.
+
 ## Channel and stability
 
 - **Channel:** npm, on the `latest` dist-tag. Each version is published with
@@ -80,6 +86,8 @@ ceilings. Its aggregate budgets in `release-gates.json` follow the measured
 decision its `$budgetReason` records; later growth still needs its own
 measured budget decision. Passing a local pack does not authorize publication.
 
+`./fulfillment` owns pure status, tracking-progress, current-parcel and canonical fact-parser helpers.
+
 ## Package Surface Maturity
 
 Every current export is an internal candidate, experimental kernel, or testing
@@ -91,7 +99,7 @@ promise.
 | `./bundle` | kernel | candidate | `smoke/subscriptionBundleStandalone.test.ts` |
 | `./catalog` | kernel | candidate | `smoke/catalogStandalone.test.ts` |
 | `./company-identity` | kernel | experimental | `smoke/companyIdentityStandalone.test.ts` |
-| `./fulfillment` | kernel | experimental | `smoke/fulfillmentStandalone.test.ts` |
+| `./fulfillment` | kernel | experimental | `smoke/fulfillmentStandalone.test.ts`<br>`test/fulfillmentStatusMap.test.ts`<br>`test/fulfillmentTrackingProgress.test.ts`<br>`test/fulfillmentCurrentParcel.test.ts`<br>`test/fulfillmentNormalizedFacts.test.ts` |
 | `./inventory` | kernel | candidate | `smoke/inventoryStandalone.test.ts` |
 | `./marketing/research` | kernel | experimental | `smoke/marketingResearchStandalone.test.ts` |
 | `./partners` | kernel | experimental | `smoke/partnersStandalone.test.ts` |

package/dist/fulfillment/currentFulfillmentParcel.d.ts

@@ -0,0 +1,16 @@
+export type FulfillmentParcelRow = {
+    id?: unknown;
+    order_id?: unknown;
+    sequence_no?: unknown;
+};
+export declare function parcelSequenceNo(row: FulfillmentParcelRow): number;
+export declare function compareParcelPrecedence(left: FulfillmentParcelRow, right: FulfillmentParcelRow): number;
+export declare function currentParcel<Row extends FulfillmentParcelRow>(rows: readonly Row[]): Row | null;
+export declare function currentParcelFor<Row extends FulfillmentParcelRow>(rows: readonly Row[], orderId: unknown): Row | null;
+export declare function currentParcelPerOrder<Row extends FulfillmentParcelRow>(rows: readonly Row[]): Map<string, Row>;
+export declare function currentParcelFirst<Row extends FulfillmentParcelRow>(rows: readonly Row[]): Row[];
+export type ParcelAttributedRow = {
+    fulfillment_order_id?: unknown;
+};
+export declare function belongsToParcel(row: ParcelAttributedRow, parcelId: unknown): boolean;
+export declare function rowsForParcel<Row extends ParcelAttributedRow>(rows: readonly Row[], parcelId: unknown): Row[];

package/dist/fulfillment/currentFulfillmentParcel.js

@@ -0,0 +1,70 @@
+// 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.
+// 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) {
+    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, right) {
+    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(rows) {
+    return rows.reduce((best, row) => (best === null || compareParcelPrecedence(row, best) < 0 ? row : best), null);
+}
+export function currentParcelFor(rows, orderId) {
+    return currentParcel(rows.filter((row) => row.order_id === orderId));
+}
+export function currentParcelPerOrder(rows) {
+    const byOrder = new Map();
+    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(rows) {
+    const byOrder = new Map();
+    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));
+}
+export function belongsToParcel(row, parcelId) {
+    const attributed = row.fulfillment_order_id;
+    if (typeof attributed !== "string" || !attributed)
+        return true;
+    return typeof parcelId === "string" && parcelId ? attributed === parcelId : true;
+}
+export function rowsForParcel(rows, parcelId) {
+    return rows.filter((row) => belongsToParcel(row, parcelId));
+}

package/dist/fulfillment/index.d.ts

@@ -2,3 +2,19 @@
 export { FULFILLMENT_FACT_SOURCE_AUTHORITIES, FULFILLMENT_FACT_SOURCES, PROVIDER_FULFILLMENT_FACT_SOURCES, NORMALIZED_FULFILLMENT_FACT_PREVIOUS_SCHEMA_VERSION, NORMALIZED_FULFILLMENT_FACT_SCHEMA_VERSION, TRANSITION_CONFLICT_REASONS, InvalidFulfillmentFactError, FulfillmentFactCollisionError, UnsupportedFulfillmentFactSchemaError, canonicalFulfillmentFactFingerprint, canonicalizeFulfillmentFacts, parseNormalizedFulfillmentFact, parseTransitionConflict, } from "./facts.js";
 /** @beta */
 export type { CompatibleNormalizedFulfillmentFact, FulfillmentFactSourceAuthority, FulfillmentFactSource, FulfillmentFactProvenance, FulfillmentRawEventReference, FulfillmentProviderSequence, FulfillmentFactParserOptions, ProviderFulfillmentFactSource, NormalizedFulfillmentFact, NormalizedFulfillmentFactV0, NormalizedFulfillmentFactV1, TransitionConflict, TransitionConflictDecision, 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";

package/dist/fulfillment/index.js

@@ -1,2 +1,10 @@
 /** @beta */
 export { FULFILLMENT_FACT_SOURCE_AUTHORITIES, FULFILLMENT_FACT_SOURCES, PROVIDER_FULFILLMENT_FACT_SOURCES, NORMALIZED_FULFILLMENT_FACT_PREVIOUS_SCHEMA_VERSION, NORMALIZED_FULFILLMENT_FACT_SCHEMA_VERSION, TRANSITION_CONFLICT_REASONS, InvalidFulfillmentFactError, FulfillmentFactCollisionError, UnsupportedFulfillmentFactSchemaError, canonicalFulfillmentFactFingerprint, canonicalizeFulfillmentFacts, parseNormalizedFulfillmentFact, parseTransitionConflict, } 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 { fulfillmentProgressPresentation } from "./trackingProgress.js";
+/** @beta */
+export { parcelSequenceNo, compareParcelPrecedence, currentParcel, currentParcelFor, currentParcelPerOrder, currentParcelFirst, belongsToParcel, rowsForParcel } from "./currentFulfillmentParcel.js";
+/** @beta */
+export { isCanonicalLocalFulfillmentStatus, parseFulfillmentFact, parseFulfillmentTransitionConflict } from "./normalizedFulfillmentFacts.js";

package/dist/fulfillment/normalizedFulfillmentFacts.d.ts

@@ -0,0 +1,14 @@
+import { type CompatibleNormalizedFulfillmentFact as CoreCompatibleNormalizedFulfillmentFact, type FulfillmentTransitionSnapshot as CoreFulfillmentTransitionSnapshot, type NormalizedFulfillmentFact as CoreNormalizedFulfillmentFact, type NormalizedFulfillmentFactV0 as CoreNormalizedFulfillmentFactV0, type NormalizedFulfillmentFactV1 as CoreNormalizedFulfillmentFactV1, type TransitionConflict as CoreTransitionConflict } from "./facts.js";
+import type { CanonicalLocalFulfillmentStatus } from "./types.js";
+/** Application binding: core evidence narrowed to the single Layer B status canon. */
+export type CanonicalNormalizedFulfillmentFact = CoreNormalizedFulfillmentFact<CanonicalLocalFulfillmentStatus>;
+export type CanonicalNormalizedFulfillmentFactV1 = CoreNormalizedFulfillmentFactV1<CanonicalLocalFulfillmentStatus>;
+export type CanonicalNormalizedFulfillmentFactV0 = CoreNormalizedFulfillmentFactV0<CanonicalLocalFulfillmentStatus>;
+export type CanonicalCompatibleNormalizedFulfillmentFact = CoreCompatibleNormalizedFulfillmentFact<CanonicalLocalFulfillmentStatus>;
+export type CanonicalFulfillmentTransitionSnapshot = CoreFulfillmentTransitionSnapshot<CanonicalLocalFulfillmentStatus>;
+export type CanonicalTransitionConflict = CoreTransitionConflict<CanonicalLocalFulfillmentStatus>;
+export declare function isCanonicalLocalFulfillmentStatus(value: string): value is CanonicalLocalFulfillmentStatus;
+/** Strict unknown-input parser bound to the existing status canon. */
+export declare function parseFulfillmentFact(value: unknown): CanonicalNormalizedFulfillmentFact;
+/** Strict conflict parser bound to the same status canon. */
+export declare function parseFulfillmentTransitionConflict(value: unknown): CanonicalTransitionConflict;

package/dist/fulfillment/normalizedFulfillmentFacts.js

@@ -0,0 +1,18 @@
+import { parseNormalizedFulfillmentFact, parseTransitionConflict, } from "./facts.js";
+import { CANONICAL_LOCAL_FULFILLMENT_STATUSES, } from "./statusMap.js";
+const CANONICAL_STATUSES = new Set(CANONICAL_LOCAL_FULFILLMENT_STATUSES);
+export function isCanonicalLocalFulfillmentStatus(value) {
+    return CANONICAL_STATUSES.has(value);
+}
+/** Strict unknown-input parser bound to the existing status canon. */
+export function parseFulfillmentFact(value) {
+    return parseNormalizedFulfillmentFact(value, {
+        isCanonicalStatus: isCanonicalLocalFulfillmentStatus,
+    });
+}
+/** Strict conflict parser bound to the same status canon. */
+export function parseFulfillmentTransitionConflict(value) {
+    return parseTransitionConflict(value, {
+        isCanonicalStatus: isCanonicalLocalFulfillmentStatus,
+    });
+}