Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Plan the fulfillment status rework: two axes and a delivered state

Damian Legawieca28373302296
diff --git a/CLAUDE.md b/CLAUDE.md
index a130acbe61..022e07f5c8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,7 +22,7 @@ Active plans (6.0 target, work pending):
- `6.0-typed-stock-movements.md` — Replace generic StockMovement with typed kinds + concrete FKs
- `6.0-normalize-state-to-status.md` — Rename state → status on Payment, Shipment, InventoryUnit, ReturnAuthorization, GiftCard
- `6.0-delivery-profiles.md` — **Implemented in PR #14404 (2026-08-09).** `Spree::DeliveryProfile` = ShippingCategory promoted via table rename (`spree_shipping_categories`→`spree_delivery_profiles`, `products.shipping_category_id`→`delivery_profile_id`): store-scoped STI (kinds `DeliveryProfiles::Shipping`/`::Digital` via `Spree.delivery_profile_types`), one default per store, products reference it directly and it's required (auto-assigned: type template else store default; ProductType stamps at creation only — template doctrine). Profile ↔ stock locations (origins, empty=all) + profile→zones + profile→methods; method binds ≤1 zone (m:n join dropped), optional ships-from narrowing per method (no location-group layer — considered, dropped). **Classes only, NO string vocabularies:** method `fulfillment_type` column dropped, `Spree.fulfillment_types` registry + ProductType array deleted; behavior = `FulfillmentProvider` class predicates (`digital?`/`pickup?`/`pickup_point?`/`requires_address?`), rate-provider `requires_address?`, profile kind `digital?`/`requires_shipping_address?` + composition validations. Carts split per profile (`Splitter::DeliveryProfile`); Coordinator allocates only from profile-covered locations. `spree:migrate_delivery_profiles` (5.6→6.0 manifest) does store assignment/kind detection/non-narrowing fold-in/method m:n collapse (`spree_shipping_method_categories` survives to 6.1 as source). ShippingCategory/ShippingMethodCategory classes + associations deleted. Supersedes the string-registry + "named groups 6.1" decisions.
-- `6.0-fulfillment-and-delivery.md` — Shipment→Fulfillment, ShippingMethod→DeliveryMethod, drop ShippingCategory, FulfillmentProvider strategy, pickup (merchant StockLocation) + pickup_point (third-party PickupPointProvider). **Shipped to 6-0-dev (Waves 2+4+6):** renames + deprecated twins, providers (Manual/Digital/Pickup/PickupPoint), dual-emit events, store pickup discovery endpoints, admin delivery_methods/delivery_zones CRUD + dashboard settings pages, FulfillmentMailer; Wave 7 shipping→delivery data migration remains. Pickup work beyond shipped code deferred to 6.1 (2026-08-06): contract hardening (`new(delivery_method)` ctor, `find_nearby` zipcode/query) + how-to guide; `PickupPointProvider::Base` stays **undocumented in 6.0** (v6 docs cover only the delivery rate provider interface) — never add pickup-provider docs in 6.0 work. Delivery mechanics live on provider classes (`pickup_point` provider ships but stays unregistered until 6.1; `local_delivery` cut = shipping + postal-code zone); the string fulfillment-type registry was deleted by `6.0-delivery-profiles.md`. **Partial fulfillment (2026-08-10, resolved question 12):** shipping a subset is `Spree::Fulfillments::Fulfill` (optional per-line-item `items:` + `tracking:` + `notify_customer:`; splits then fulfills in one transaction) — never a state-machine event, since split-then-ship in an `after_transition` is what service-workflows prohibits; the machine stays and the workflow calls it. **Side effects left the machine (2026-08-10, question 13):** `after_cancel`/`after_resume` are gone as transition callbacks — restock + carrier stand-down live in `Fulfillments::Cancel`/`::Resume` as inline steps (provider call is an `external_step`; `notify_provider: false` lets `Orders::Cancel` delegate and batch carrier I/O after its own transaction), `after_cancel`/`after_resume` are deprecated shells and the only trace left on the model — never add public model methods for workflows to call; the machine keeps only the status column, the guards and the `publish_*_event` callbacks
+- `6.0-fulfillment-and-delivery.md` — Shipment→Fulfillment, ShippingMethod→DeliveryMethod, drop ShippingCategory, FulfillmentProvider strategy, pickup (merchant StockLocation) + pickup_point (third-party PickupPointProvider). **Shipped to 6-0-dev (Waves 2+4+6):** renames + deprecated twins, providers (Manual/Digital/Pickup/PickupPoint), dual-emit events, store pickup discovery endpoints, admin delivery_methods/delivery_zones CRUD + dashboard settings pages, FulfillmentMailer; Wave 7 shipping→delivery data migration remains. Pickup work beyond shipped code deferred to 6.1 (2026-08-06): contract hardening (`new(delivery_method)` ctor, `find_nearby` zipcode/query) + how-to guide; `PickupPointProvider::Base` stays **undocumented in 6.0** (v6 docs cover only the delivery rate provider interface) — never add pickup-provider docs in 6.0 work. Delivery mechanics live on provider classes (`pickup_point` provider ships but stays unregistered until 6.1; `local_delivery` cut = shipping + postal-code zone); the string fulfillment-type registry was deleted by `6.0-delivery-profiles.md`. **Partial fulfillment (2026-08-10, resolved question 12):** shipping a subset is `Spree::Fulfillments::Fulfill` (optional per-line-item `items:` + `tracking:` + `notify_customer:`; splits then fulfills in one transaction) — never a state-machine event, since split-then-ship in an `after_transition` is what service-workflows prohibits. **Side effects left the machine (2026-08-10, question 13):** `after_cancel`/`after_resume` are gone as transition callbacks — restock + carrier stand-down live in `Fulfillments::Cancel`/`::Resume` as inline steps (provider call is an `external_step`; `notify_provider: false` lets `Orders::Cancel` delegate and batch carrier I/O after its own transaction), `after_cancel`/`after_resume` are deprecated shells and the only trace left on the model — never add public model methods for workflows to call. **Status model (2026-08-11, question 14): the machine is REMOVED.** `status` = plain `HasStatus` `unfulfilled → fulfilled → delivered | canceled` (`pending`/`ready`/`ready_for_pickup` collapse — payment/stock gating is a `Fulfillments::Fulfill` validate guard, pickup renders modality-aware labels); `delivered` = confirmed receipt (`Fulfillments::MarkDelivered`, `delivered_at`, `fulfillment.delivered`) — the returns window + EU withdrawal anchor; carrier truth is the separate `tracking_status` axis (data, never a machine) written by `Fulfillments::UpdateTracking`, fed by EasyPost tracker webhooks (opt-in trackers for hand-entered numbers). Rollup domain `backorder | canceled | partial | unfulfilled | fulfilled | delivered`. Phase 7, not yet implemented
- `6.0-returns-exchanges-claims.md` — First-class Return, Exchange, Claim models replacing ReturnAuthorization/Reimbursement chain. **COMPLETE (2026-08-05):** all three entities (+ permanent `ReturnLineItem`/`ExchangeLineItem`/`ClaimLineItem` line items), `Spree::HasStatus`, all fifteen workflows (each with a leading `validate` hook), `Refund#originator`, admin + store v3 APIs (transitions as PATCH member actions; no destroy — cancel instead), dashboard pages. Legacy chain **removed**: ReturnAuthorization/CustomerReturn/Reimbursement/ReimbursementType/legacy ReturnItem + eligibility validators + ReturnsCalculator classes all deleted, but their **tables deliberately survive to 6.1** as the data migration's source and rollback path. `spree:upgrade:migrate_returns` (`Spree::ReturnsMigrator`, defined in the rake file like its sibling upgrade tasks; anonymous-AR readers) is in the 5.6→6.0 manifest after the adjustments step; it needs no cursor because the preserved `number` is uniquely indexed on the new tables, so "what's left" is a `where.not(number: ...)` query and an interrupted run resumes for free. `ReturnAuthorizationReason`→`ReturnReason` (alias one release) + new `ClaimReason`; `Metafields` on all three. Capability replacements: `Spree::ReturnMailer#refunded_email` on `return.refunded` (replaces the reimbursement email), `Order#outstanding_balance` drops the reimbursement term (refunds already net out of `payment_total`), `Return#refunded_total` counts store credits too, `StoreCreditCategory.default_refund_category` (alias kept). **Reasons** ship admin-only CRUD (`/api/v3/admin/{return,claim,refund}_reasons`, `settings` scope) + a combined Settings → Reasons dashboard page + reason pickers on the create dialogs; `mutable` is never client-writable and the immutability guard lives on `Spree::NamedType` (`can_be_deleted?` + rename/destroy guards) because secret API keys authorize by scope and never consult CanCanCan. **No state machines (2026-08-02):** plain `status` string + inclusion validation; all fifteen transitions are workflows (`Returns::Receive`, `Exchanges::Fulfill`, `Claims::Resolve`, …) with `validate` hooks for return-eligibility policy and refunds as `external_step`. Nothing happens in a model or transition callback. Statuses live in a `class_attribute` via the core `Spree::HasStatus` concern (`has_status` + additive `add_status(value, after:)`, generating predicates and scopes) — extensible by design, additive only, and no transition graph (that would be a state machine again). **Return eligibility is a hook, not a policy engine (2026-08-03):** no window/restocking-fee/final-sale flag in core — a `validate` handler decides, enforcing for customers while letting staff override (it reads `created_by`), and region-varying policy reads `order.market`. Medusa/Saleor/Vendure ship no policy at all; Shopify's engine has no API. A `ReturnPolicy` model can arrive later behind the same hook.
- `6.0-platform-auth.md` — Drop Devise, own auth stack, User→Customer/Staff rename (RefreshToken shipped in 5.4)
- `6.0-tax-provider.md` — Per-Market TaxProvider, replaces TaxRate.adjust + Calculator; TaxRate gets direct country/state FKs (tax decoupled from Zone; Zone model dropped in 6.0 via `6.0-delivery-zones.md`); reference provider: Avalara (decisions.md 2026-07-30)
diff --git a/docs/plans/6.0-fulfillment-and-delivery.md b/docs/plans/6.0-fulfillment-and-delivery.md
index a7ffa9004c..e81fc01857 100644
--- a/docs/plans/6.0-fulfillment-and-delivery.md
+++ b/docs/plans/6.0-fulfillment-and-delivery.md
@@ -150,7 +150,81 @@ Checkout — where fulfillments and delivery rates are created and selected —
`delivery_amount = cost + discounts.sum(:amount)` — the selected rate's cost net of fulfillment-attached `Discount` rows (negative, from `6.0-6.1-split-adjustments.md`). This is the base `6.0-multi-vendor-marketplace.md` uses for `include_shipping` commission (`CommissionLine` fulfillment-scoped). `cost` remains the denormalized column it is today.
-### Status semantics — corrected against the real machine
+### Status model — two axes, `delivered` is first-class (2026-08-11)
+
+`Fulfillment#status` describes what the merchant did with the package — nothing
+else. Four values, plain string via `Spree::HasStatus`, **state machine
+removed**:
+
+```
+unfulfilled ──► fulfilled ──► delivered
+ └───────► canceled (resume: canceled ──► unfulfilled)
+```
+
+- **`unfulfilled`** replaces both `pending` and `ready`. Those were payment and
+ stock facts wearing a fulfillment costume: `determine_state` re-derived them
+ from `order.paid?` on every recalculation, so a refund flipped a fulfillment
+ between pending and ready with no physical change — the single most
+ misunderstood part of the model. Whether a fulfillment *can* be fulfilled
+ (order paid or auto-capture-on-dispatch, no backordered units) becomes a
+ guard in `Fulfillments::Fulfill`'s validate step — it rejects with a reason
+ and is staff-overridable, like return eligibility. `determine_state` and the
+ `ready`/`pend` events are deleted; cart-side fulfillments are always
+ `unfulfilled`.
+- **`fulfilled`** keeps its meaning: handed over — to the carrier, or ready at
+ the counter for pickup.
+- **`delivered`** is new and terminal: confirmed receipt. Reached by carrier
+ tracking, a staff "mark as delivered" (works with no carrier integration),
+ or later customer confirmation via the Store API. `Fulfillments::MarkDelivered`
+ sets `delivered_at` and publishes `fulfillment.delivered`. The returns
+ eligibility window and the EU 14-day withdrawal period both anchor on a
+ delivery date the model never had — this is where it comes from.
+- **`ready_for_pickup` dies as a status.** For pickup fulfillments `fulfilled`
+ means "ready at the counter" (the provider's fulfill side effect notifies the
+ customer) and `delivered` means picked up. Presentation is modality-aware;
+ the status vocabulary is not.
+
+**The second axis — `tracking_status` — is the carrier's story: data, never a
+machine.** Nullable string + `tracking_details` JSON + `estimated_delivery_at`,
+overwritten on every carrier update, no transition graph: `pre_transit`,
+`in_transit`, `out_for_delivery`, `available_for_pickup`, `delivered`,
+`return_to_sender`, `failure`, `unknown`. Bounced packages, failed delivery
+attempts and damage surface here (and can feed a claim) without ever mutating
+`status`. The core entry point is `Fulfillments::UpdateTracking` — writes the
+axis, calls `MarkDelivered` when the carrier reports delivery. The EasyPost gem
+feeds it from tracker webhooks: every label we buy already has a tracker whose
+updates are currently thrown away (only the public URL is stored). Trackers
+for hand-entered tracking numbers cost money each, so creating them is opt-in
+on the integration.
+
+**Order rollup domain** becomes `backorder | canceled | partial | unfulfilled |
+fulfilled | delivered` (+ nil): `delivered` when every non-canceled fulfillment
+is delivered, `fulfilled` when every one is fulfilled-or-beyond, `partial` for
+mixes; `backorder` still short-circuits (item-level fact, unchanged).
+
+**Removing the machine supersedes "the machine stays" (question 13,
+decisions.md 2026-08-10).** That call was made while the machine still held
+guards worth keeping; with `pending`/`ready` gone it holds two transitions and
+the event publishes — exactly what `HasStatus` + workflows already provide for
+Return/Exchange/Claim. Transition legality moves inline into the workflows
+(`Fulfill` from unfulfilled/canceled, `Cancel` from unfulfilled, `Resume` to
+unfulfilled, `MarkDelivered` from fulfilled). The FulfillmentItem machine
+(on_hand/backordered/shipped/returned) is untouched — stock bookkeeping, owned
+by `6.0-typed-stock-movements.md`.
+
+**Data migration** (both the 6-0-dev mapping and the 5.6→6.0 manifest step):
+`pending|ready → unfulfilled`; `ready_for_pickup → fulfilled`; pickup-modality
+`fulfilled` rows → `delivered` (under the old machine, pickup "fulfilled" meant
+the customer took the package — that *is* confirmed receipt);
+shipping-modality `fulfilled` stays `fulfilled` (delivery genuinely unknown).
+
+### SUPERSEDED (2026-08-11): the section below preserved the pending/ready machine
+
+Superseded by "Status model — two axes" above (decisions.md 2026-08-11):
+`pending`/`ready`/`ready_for_pickup` collapse into `unfulfilled`, the machine
+is removed, and the lifecycle extends past handover to `delivered`.
+
+### Historical — Status semantics — corrected against the real machine
The rename is `shipped` → `fulfilled` (column `state` → `status` per the normalize plan), **preserving** today's guards and hooks, which the earlier draft dropped:
@@ -253,18 +327,13 @@ class Spree::Fulfillment < Spree.base_class
has_many :discounts, class_name: 'Spree::Discount', dependent: :destroy # split-adjustments
has_many :tax_lines, class_name: 'Spree::TaxLine', dependent: :destroy
- # status column (normalize plan). Guards + hooks preserved from today's machine — see Key Decisions.
- state_machine :status, initial: :pending do
- event(:ready) { transition from: :pending, to: :ready, if: ->(f) { f.determine_state(f.order) == 'ready' } }
- event(:pend) { transition from: :ready, to: :pending }
- event(:fulfill) { transition from: %i[ready ready_for_pickup canceled], to: :fulfilled }
- event(:cancel) { transition from: %i[pending ready ready_for_pickup], to: :canceled }
- event(:resume) { transition from: :canceled, to: :ready, if: ->(f) { f.determine_state(f.order) == 'ready' }
- transition from: :canceled, to: :pending }
- event(:mark_ready_for_pickup) { transition from: :ready, to: :ready_for_pickup }
- end
- # after_transition hooks: restock/unstock, StateChange audit, set_fulfilled_at,
- # fulfillment.* events + webhooks (dual-emit shipment.* for one release)
+ # status column — plain string, no machine (2026-08-11 status-model decision).
+ # Transitions live in Fulfillments::{Fulfill,Cancel,Resume,MarkDelivered};
+ # each validates the current status inline and publishes its event.
+ has_status :unfulfilled, :fulfilled, :delivered, :canceled
+
+ # Carrier axis — data written by Fulfillments::UpdateTracking, never a machine:
+ # tracking_status, tracking_details (JSON), estimated_delivery_at, delivered_at
def delivery_method = selected_delivery_rate&.delivery_method
@@ -341,6 +410,14 @@ Batched, idempotent, resumable — same guarantees as the split-adjustments migr
- Also added by the 2026-08-05 work: `DeliveryMethod#display_on` / `#display_on=` / `#available_to_display?`, the `DISPLAY_ON_FRONT_END`/`BACK_END` constants and the `DeliveryMethod.normalize_audience` shim that accepts them, the `deprecated: true` `shipping_method_categories` / `shipping_categories` associations on DeliveryMethod, the `deprecated: true` `shipping_category` / `shipping_methods` associations on Product, `Variant#shipping_category` / `#shipping_category_id`, and the `spree_delivery_methods.display_on` column. Plus the method bridges listed above: `Estimator#shipping_rates`/`#shipping_methods`, `Package#shipping_rates`/`#to_shipment`, `Coordinator#shipments`, `Order#line_items_without_shipping_rates`, `Order#refresh_shipment_rates`, and `LineItem#shipping_cost`/`#display_shipping_cost`. The CSV surface needs no cleanup — it was cut outright in 6.0.
- `FulfillmentSerializer#fulfillment_type` can drop its computed fallback once every install has run `spree:migrate_shipping_to_delivery`.
+### Phase 7 — status model + delivery tracking (decided 2026-08-11, not yet implemented)
+
+- Schema: `tracking_status`, `tracking_details` (JSON), `estimated_delivery_at`, `delivered_at` on `spree_fulfillments`.
+- Swap the machine for `HasStatus`; move transition legality into the four workflows; add `Fulfillments::MarkDelivered` + `Fulfillments::UpdateTracking`; delete `determine_state`.
+- Rollup, serializers, SDK types, dashboard status rendering (modality-aware pickup labels), `fulfillment.delivered` event.
+- EasyPost: tracker webhook endpoint in the gem feeding `UpdateTracking`; opt-in tracker creation for hand-entered tracking numbers.
+- Data mapping (6-0-dev migration + 5.6→6.0 manifest step): see the Key Decisions section for the per-modality rules.
+
## Constraints on Current Work
- **Use "delivery method" / "fulfillment" in all new API v3 code.** No new `shipping_method` / `shipment` references. New tables referencing shipments are born with `fulfillment_id`.
@@ -351,7 +428,7 @@ Batched, idempotent, resumable — same guarantees as the split-adjustments migr
## Resolved Questions
-1. **Fulfillment status naming + rollup.** `shipped` → `fulfilled` (`fulfilled_at`); Order column → `fulfillment_status` with domain `backorder | canceled | partial | pending | ready | fulfilled` (+ nil) — `backorder` **stays** (earlier draft wrongly dropped it). `ready_for_pickup`/`picked_up` roll up as `ready`/`fulfilled`. Guards, `pend`, conditional `resume`, and all transition hooks are preserved.
+1. **Fulfillment status naming + rollup.** *Superseded 2026-08-11 by question 14 — the rename itself stands, the preserved machine does not.* `shipped` → `fulfilled` (`fulfilled_at`); Order column → `fulfillment_status`. The domain and the "guards, `pend`, conditional `resume` preserved" clause are replaced by the two-axis status model.
2. **Store scoping is NOT this plan's.** `store_id` on DeliveryMethod is owned by `6.0-delivery-rate-provider.md` Phase 1 (greenfield + derived backfill — there was never a join table; see decisions.md 2026-03-16 correction). The earlier draft's PaymentMethod claim is obsolete — that shipped in 5.6 and was amended 2026-07-23 (`PaymentMethodRule`).
3. **`fulfillment_types` as JSON column on ProductType** (jsonb-guarded), owned by the `6.0-product-types.md` addendum.
4. **Lifecycle events**: `fulfillment.{ready,fulfilled,canceled,resumed}` + `order.fulfilled`; one-release dual-emit of legacy `shipment.*` webhooks.
@@ -362,7 +439,7 @@ Batched, idempotent, resumable — same guarantees as the split-adjustments migr
9. **Owner shape** (2026-07-27 cart-order-split expansion; refined 2026-07-28): dual `cart_id`/`order_id` exactly-one on `Fulfillment` — no polymorphism; `DeliveryRate` carries no owner columns and derives through its fulfillment. Phase 1b's `cart_id` is unblocked.
10. **Webhook dual-emit window: one release** (2026-07-28) — 6.0 dual-emits `shipment.*` alongside `fulfillment.*` with a deprecation note in webhook docs; 6.1 drops the legacy names.
-11. **`ready_for_pickup` is a first-class Store API status** (2026-07-28) — the fulfillment serializer returns it as-is (it's the one state a pickup customer acts on); the order-level rollup still reports `ready`.
+11. **`ready_for_pickup` is a first-class Store API status** (2026-07-28) — *superseded 2026-08-11 by question 14*: the status dies; a pickup customer acts on `fulfilled` (which for pickup modality means "ready at the counter"), and clients render modality-aware labels. `delivered` = picked up.
12. **Partial fulfillment is a workflow, not a state-machine event** (2026-08-10).
Shipping only some of a fulfillment's units splits it first, and
@@ -395,10 +472,25 @@ Batched, idempotent, resumable — same guarantees as the split-adjustments migr
own `external_step` after the transaction commits (a nested `external_step`
would raise, correctly). `Fulfillments::Fulfill` gained an explicit
unstock for the `canceled → fulfilled` path the resume callback used to
- cover. This is Option 1 of the state-machine question: the dangerous
- callbacks move, the machine stays. Removing the machine outright — and the
- four others (Payment, InventoryUnit, ReturnAuthorization, GiftCard) — is a
- separate planned wave, not a 6.0 refactor. See decisions.md 2026-08-10.
+ cover. *The closing claim of this decision — "the dangerous callbacks move,
+ the machine stays" — is superseded by question 14 (2026-08-11): the
+ Fulfillment machine goes too. The side-effect relocation itself stands and
+ made the removal cheap. The other machines (Payment, InventoryUnit,
+ ReturnAuthorization, GiftCard) remain a separate wave.* See decisions.md
+ 2026-08-10 and 2026-08-11.
+
+14. **Status model simplified to two axes; `delivered` is first-class; the
+ machine is removed** (2026-08-11). `unfulfilled → fulfilled → delivered`
+ plus `canceled`, plain `HasStatus`; payment/stock gating becomes a
+ `Fulfillments::Fulfill` validate guard; carrier truth lives on the separate
+ `tracking_status` axis fed by `Fulfillments::UpdateTracking` (EasyPost
+ tracker webhooks; manual trackers opt-in). Full decision in Key Decisions →
+ "Status model — two axes". Motivation: merchants consistently reported the
+ lifecycle ending at handover — no confirmed receipt, no bounce, no failed
+ attempt — and nobody understood `pending` vs `ready`, which encoded payment
+ state, not fulfillment state. Adds `fulfillment.delivered` to the question-4
+ event list and gives the returns window and EU withdrawal period their
+ anchor (`delivered_at`). See decisions.md 2026-08-11.
## Open Questions
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index b2529c8574..827a28ac30 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -1,3 +1,41 @@
+## 2026-08-11: Fulfillment status model — two axes, `delivered` first-class, machine removed (supersedes part of 2026-08-10)
+
+`Fulfillment#status` collapses to `unfulfilled → fulfilled → delivered` plus
+`canceled`, plain string via `HasStatus`, state machine deleted. `pending` and
+`ready` were payment and stock facts wearing a fulfillment costume —
+`determine_state` re-derived them from `order.paid?` on every recalculation, so
+a refund flipped a fulfillment's status with no physical change, and merchants
+never understood them. That gating becomes a validate guard in
+`Fulfillments::Fulfill` (rejects with a reason, staff-overridable).
+`ready_for_pickup` dies as a status: pickup `fulfilled` means "ready at the
+counter", `delivered` means picked up, presentation is modality-aware.
+
+`delivered` is the new terminal state — confirmed receipt, the thing merchants
+kept asking for (the lifecycle used to end at handover). Set by carrier
+tracking, a staff button, or later customer confirmation, via
+`Fulfillments::MarkDelivered` (`delivered_at`, `fulfillment.delivered` event).
+The returns eligibility window and the EU 14-day withdrawal period anchor on
+`delivered_at`.
+
+Carrier truth is a second axis, data not a machine: `tracking_status` +
+`tracking_details` + `estimated_delivery_at`, overwritten per update
+(`pre_transit … delivered, return_to_sender, failure`), written by
+`Fulfillments::UpdateTracking`. Bounces and failed attempts surface there
+without mutating `status`. The EasyPost gem feeds it from tracker webhooks —
+every purchased label already has a tracker whose updates were being thrown
+away; trackers for hand-entered numbers cost money each, so opt-in.
+
+This supersedes the 2026-08-10 "the dangerous callbacks move, the machine
+stays" conclusion: with `pending`/`ready` gone the machine held two transitions
+and its event publishes, which is what `HasStatus` + workflows already do for
+Return/Exchange/Claim. The side-effect relocation stands and made removal
+cheap. The FulfillmentItem machine and the other machines (Payment,
+ReturnAuthorization, GiftCard) are unaffected. Status mapping for existing
+rows: `pending|ready → unfulfilled`, `ready_for_pickup → fulfilled`,
+pickup-modality `fulfilled → delivered`, shipping-modality `fulfilled` stays.
+Plan: `6.0-fulfillment-and-delivery.md` (Key Decisions → "Status model — two
+axes", Resolved Question 14, Phase 7).
+
## 2026-08-11: The order edit screen stages edits and saves in bulk (reverses 2026-08-10)
The 6.0 admin order edit screen was specified to write immediately — one