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.

Add 6.0 core-rewrite task plan and record settled decisions

Damian Legawiecf56f3c845185
diff --git a/docs/plans/6.0-cart-order-split.md b/docs/plans/6.0-cart-order-split.md
index c35ae74489..11ffb29f1c 100644
--- a/docs/plans/6.0-cart-order-split.md
+++ b/docs/plans/6.0-cart-order-split.md
@@ -4,7 +4,7 @@
**Target:** Spree 6.0
**Depends on:** API v3 conventions. **Gates (they depend on this plan):** `6.0-split-adjustments.md` (typed-line owner), `6.0-fulfillment-and-delivery.md` (fulfillment/rate owner), `6.0-multi-vendor-marketplace.md` Phase 3 (split fires inside `Carts::Complete`), `6.0-normalize-state-to-status.md` (Order.state removed here). This is the most upstream unstarted 6.0 refactor.
**Author:** Damian + Claude
-**Last updated:** 2026-07-27
+**Last updated:** 2026-07-28
## Summary
@@ -31,7 +31,7 @@ The codebase is further along than the old stub implied — the split formalizes
### 2. One owner pattern everywhere: dual concrete FKs (`cart_id`/`order_id`, exactly-one) — NOT polymorphic
-Supersedes the original stub's "polymorphic `owner`" (decision 2026-07-27). 6.0's design language is concrete FKs over polymorphic type strings (split-adjustments removes `adjustable_type`, typed-stock-movements removes `originator_type`) — LineItem doesn't get to reintroduce the pattern the release removes. So **every** cart-or-order-owned table uses the same shape: nullable `cart_id` + nullable `order_id`, exactly-one validation, `#owner` as a method (`order || cart`). That covers `spree_line_items` (which only gains `cart_id` — `order_id` already exists and **stays permanently**; the cheapest possible migration), the typed money lines (`TaxLine`/`Discount`/`Fee` — split-adjustments), and `Fulfillment`/`DeliveryRate` (fulfillment plan).
+Supersedes the original stub's "polymorphic `owner`" (decision 2026-07-27). 6.0's design language is concrete FKs over polymorphic type strings (split-adjustments removes `adjustable_type`, typed-stock-movements removes `originator_type`) — LineItem doesn't get to reintroduce the pattern the release removes. So **every** cart-or-order-owned table uses the same shape: nullable `cart_id` + nullable `order_id`, exactly-one validation, `#owner` as a method (`order || cart`). That covers `spree_line_items` (which only gains `cart_id` — `order_id` already exists and **stays permanently**; the cheapest possible migration), the typed money lines (`TaxLine`/`Discount`/`Fee` — split-adjustments), and `Fulfillment` (fulfillment plan). `DeliveryRate` carries **no owner columns** (settled 2026-07-28): a rate belongs to its fulfillment and derives the owner through it — `spree_shipping_rates` has neither FK today, and duplicating the pair would be drift risk at every completion re-pointing.
**Provenance needs no second FK on the row.** `Order#cart_id` (unique — the idempotency key) links every order to its cart; the retained cart keeps its own rows as the frozen at-checkout snapshot, so "which cart did this come from" is answered through the order, and post-placement additions are distinguishable (rows the order has that its cart never had). Both-columns-set was considered and rejected: order-side copies carrying `cart_id` would collide with the cart's own rows in every `cart.line_items`-style association.
@@ -259,11 +259,13 @@ Drop deprecation aliases and the migration task. (`spree_line_items.order_id` is
10. **A completion-recovery sweeper** retries FINALIZE for stale `draft` orders with paid coverage and alerts on persistent failure; transient failures never trigger auto-refund. Pre-capture payment failures compensate by destroying the draft order; post-capture failures never do.
11. **Offline payment methods are first-class, not a gateway special case.** Check, B2B on-account/net-terms, COD, bank transfer, store credit, gift cards, and manual-API-recorded payments perform no external I/O, so PAYMENT collapses into the FINALIZE transaction with nothing to compensate. Completion gates on "a valid payment covers the total", **not** on `paid?` — a net-terms order completes unpaid with a `pending` payment and `payment_status: none/authorized`; capture and dunning are post-completion AR concerns. `allow_checkout_on_gateway_error` applies to external methods only.
+12. **`checkout_flow` is hard-removed in 6.0 — no shim** (2026-07-28). Extensions migrate to `Checkout::Registry` (`register_step`/`add_requirement`) via the migration guide; a translation shim would be leaky (machine transitions have no registry equivalent) and would prolong the dual API.
+13. **`partially_canceled` is a derived predicate** (2026-07-28) computed over child cancellations; the stored `status` domain stays `draft`/`placed`/`canceled`. Ransack filtering, if needed, goes through a whitelisted scope.
+14. **Reaper defaults: guest 30d, customer 90d, empty carts 48h** (2026-07-28) — `Spree::Config` preferences; the money-safety exclusion (never reap carts with authorized/pending payment sessions) is unconditional.
+
## Open Questions
-1. **Extension migration window** — does `checkout_flow`/`insert_checkout_step` get a hard removal in 6.0 or a one-release shim that translates registrations into `Checkout::Registry` entries? (Enterprise checkout customizations are the main consumers.)
-2. **`partially_canceled`** — today a quasi-state in the `canceled` scopes; proposed as a derived predicate. Confirm no report/export depends on it as a stored value.
-3. **Reaper defaults** — 30/90-day tiers are OSS platform B's; confirm against Spree hosting expectations before hardcoding defaults.
+None at this time.
## References
diff --git a/docs/plans/6.0-core-rewrite-tasks.md b/docs/plans/6.0-core-rewrite-tasks.md
new file mode 100644
index 0000000000..9e1e713c79
--- /dev/null
+++ b/docs/plans/6.0-core-rewrite-tasks.md
@@ -0,0 +1,290 @@
+# 6.0 Core Rewrite — Implementation Task List
+
+**This is a working task tracker, not a plan.** Plans of record: `6.0-cart-order-split.md`, `6.0-fulfillment-and-delivery.md`, `6.0-split-adjustments.md`. Where this file and a plan disagree, the plan wins.
+
+**Branch:** `6-0-dev` (verified against HEAD `ee39a89`, 2026-07-28)
+**UI rule:** all admin UI work targets `packages/dashboard` via Admin API v3 + `@spree/admin-sdk`. `spree/admin` is legacy and is not touched — and per Decision 2 it stops loading in the dev server (T0.3).
+**Ordering rule:** data-transformation rake tasks are the **last** wave (user constraint). Schema migrations (renames/additive) are not data migrations and land with their wave.
+
+---
+
+## Scope
+
+**In scope** — the three plans end-to-end, plus the *minimum viable slices* of prerequisite plans they hard-depend on:
+
+| Prerequisite slice | Why it's unavoidable |
+|---|---|
+| `6.0-product-types.md` Phase 1 only | Hard blocker: `ProductType#fulfillment_types` replaces ShippingCategory; `Spree::ProductType` doesn't exist yet |
+| `6.0-delivery-zones.md` Phase A + shipping-side Phase C | `spree_delivery_method_zones` must be **born** joining `DeliveryZone` (never re-migrated); Estimator address check needs a matcher |
+| `6.0-tax-provider.md` minimal `Base` + `Internal` | Split-adjustments forbids reimplementing `TaxRate.adjust`; the provider is the *only* sanctioned TaxLine writer |
+
+**Out of scope** (seams left ready, ride separately): rest of product-types (custom-field-definition join, live-template propagation, its API/dashboard), full tax-provider (per-Market column, real commit/void wiring, exemption certificates, TaxRate country/state decoupling), `6.0-delivery-rate-provider.md` (store_id + rate provider seam), `6.0-typed-stock-movements.md` (unblocked by Wave 2), multi-vendor (F3 split hook ships as a no-op single partition), returns/exchanges/claims, normalize leftovers (Payment/ReturnAuthorization/GiftCard `state`→`status`), the `spree_zones` table drop (blocked on tax decoupling).
+
+---
+
+## Decisions (settled interactively 2026-07-28 — recorded in `decisions.md` + the plans' Resolved Questions)
+
+1. **Product-types: minimal Phase 1 only** — rename + store ownership + `fulfillment_types` + `product_type_id`. Rest of that plan is its own effort.
+2. **`spree_admin` is dropped from the starter Gemfile on the 6.0 line** (→ T0.3). The gem stays in the monorepo untouched (already out of CI); one-release constant aliases still ship for extensions + emails.
+3. **`checkout_flow`: hard removal**, migration guide to `Checkout::Registry`, no shim.
+4. **DeliveryRate gets no owner columns** — owner derives through `fulfillment.owner`.
+5. **Reaper defaults: guest 30d / customer 90d / empty 48h**, config preferences; money-safety exclusion unconditional.
+6. **Webhook dual-emit: exactly one release** (`shipment.*` dropped in 6.1).
+7. **`ready_for_pickup`: first-class Store API status** (rollup still reports `ready`).
+8. **`partially_canceled`: derived predicate**, not a stored status value.
+
+---
+
+## Why this order (the four load-bearing choices)
+
+1. **Fulfillment renames before split-adjustments tables** — the typed tables are *born* with `fulfillment_id` (both plans mandate born-correct, never-migrated columns).
+2. **Split-adjustments + fulfillment providers before the Cart flip** — `Carts::Complete`'s copy contract (line items, addresses, fulfillments + selected rates, typed money lines) is written **once**, against final vocabulary. Flipping first would mean writing throwaway copy code for legacy shipments/polymorphic adjustments.
+3. **Machine removal is its own wave after the flip** — requirements-driven checkout must be live and `RecomputeStatuses` in place before `spree_orders.state` and `Order::Checkout` are deleted.
+4. **Data rake tasks last** — every task reads legacy structures that deliberately stay in place: `spree_adjustments` (read-only through 6.0 as audit/rollback), `spree_zones` (until tax decouples), ShippingCategory tables (drop in 6.1), incomplete orders (converted to carts by `completed_at`, not `state`).
+
+Each wave must land with its engine suites green (`parallel_rspec` core + api + emails, plus dashboard tests where touched) before the next starts.
+
+---
+
+## Wave 0 — Prerequisites (minimum viable slices)
+
+### T0.1 ProductType Phase 1 (`6.0-product-types.md` P1, minimal cut) — ✅ done 2026-07-28
+- [x] Migration: `spree_prototypes` → `spree_product_types` (+ both join-table renames and FK/column renames per the plan's Phase 1 migration verbatim), `add_reference :spree_products, :product_type`, store reference, `fulfillment_types` json/jsonb (nullable, no DB default), `products_count`, unique index fix on the categories join, `spree_product_type_translations` table. (Old indexes dropped up front, re-added under stable names — auto-rename would exceed PG's 63-char limit.)
+- [x] Models: `Spree::ProductType` (store-owned via `SingleStoreResource`, translatable `name`, `Metafields`/`Metadata`, model-level `fulfillment_types` default `['shipping']`, `digital?`, `requires_shipping?`, `dependent: :restrict_with_error` on products), `OptionTypeProductType`, `ProductTypeCategory`; inverse associations on OptionType/Category renamed + `dependent: :destroy` added.
+- [x] Product: `belongs_to :product_type` (optional, counter_cache) + **additive** `sync_associations_from_product_type` replacing the replace-semantics prototype callback; remove `attr_accessor :prototype_id` + `:prototype_id` from PermittedAttributes.
+- [x] `Spree::Prototype = Spree::ProductType` one-release alias; `prototype_factory` → `product_type_factory` (alias kept — testing_support is public API); registries (`Spree.metafields.enabled_resources`, `Spree.translatable_resources`); locale keys; remove dangling `platform_prototype_serializer` registration.
+- [x] **Not here:** `ProductTypeCustomFieldDefinition` join, product-types Admin API/dashboard, live-template propagation callbacks (`after_create`/`after_destroy` on the option-type join). Those ride with the full product-types effort. Store backfill/orphan-cleanup rake task authored in Wave 7.
+
+### T0.2 Drop `spree_admin` from the dev-server stack (Decision 2) — local half done 2026-07-28
+- [ ] Remove `spree_admin` from the spree-starter Gemfile on the 6.0 line — **local `server/Gemfile` edited** (edge + release blocks; only core-auth `Spree::AdminUser` references remain in the starter, unaffected). Pending: the durable commit in the `spree/spree-starter` repo, and boot verification on the next `pnpm server:dev`.
+- [x] Keep the gem in the monorepo untouched; the one-release constant aliases from Waves 2/3 are for extensions and the emails gem, not for it.
+
+### T0.3 DeliveryZone model (`6.0-delivery-zones.md` Phase A) — ✅ done 2026-07-28
+- [x] Tables: `spree_delivery_zones` (single consolidated `metadata` column per the Collection precedent), `spree_delivery_zone_members` (typed `member_type`: country FK / state FK / postal with `country_id` + `postal_code_from/to` range or `postal_code_prefix`).
+- [x] Models: `DeliveryZone` (`dz_`) / `DeliveryZoneMember` (`dzm_`) with `include?`/`match?`, numeric-postal country allowlist gating range members (extensible `class_attribute :range_capable_country_isos`), postal columns normalized on write, `Spree::Address.normalize_zipcode` + `#normalized_zipcode` (single home for zip normalization).
+- [x] `:delivery_zone` factory (+ `:delivery_zone_with_country`, `:delivery_zone_member`). No consumers swapped yet (that's T2.5).
+
+---
+
+## Wave 1 — Cart/Order split: schema + dormant Cart (`6.0-cart-order-split.md` P1 + slices of P3)
+
+Checkout keeps running on Order through Waves 1–4. The Cart table/model exist but are dormant.
+
+### T1.1 Schema — ✅ done 2026-07-28
+- [x] `create_table :spree_carts`: store/market/channel/currency/locale/customer binding (born-correct `customer_id`), email, ship/bill address refs, `accept_marketing`, special instructions, `last_ip_address`, `has_secure_token` column, single `metadata` column, `completed_at`, `completing_at`, `lock_version`, indexed `updated_at`/`completed_at`/`token`. **No status column.**
+- [x] `spree_line_items.cart_id` (nullable, indexed). `order_id` stays permanently.
+- [x] `spree_orders.cart_id` + **unique index** (the completion idempotency key).
+- [x] Rename `spree_orders.payment_state` → `payment_status` (indexed; one-release `alias_attribute :payment_state, :payment_status`). (`shipment_state` waits for T2.1 where it becomes `fulfillment_status`.)
+- [x] Rename `state_lock_version` → `lock_version`, semantics preserved — **plus `self.lock_optimistically = false` on Order and Cart** (a column literally named `lock_version` would otherwise activate Rails' built-in optimistic locking and change save semantics; the API's manual OrderLock concern stays the owner).
+
+### T1.2 Owner pattern + registry ownership — ✅ done 2026-07-28
+- [x] LineItem: exactly-one `cart_id`/`order_id` validation replacing hard `order` presence; `#owner` method (`order || cart`); internal `line_item.order` reads migrated to `owner` (pricing context, tax zone, currency, promo allocation). Order-machine-specific reads (`has_checkout_step?`, `OrderInventory`, `TaxRate.adjust`, reservation exclusion) stay order-guarded (`order&.`) — they're replaced wholesale in Waves 3/5, and passing a Cart into `where(order:)` would id-collide.
+- [x] `Spree::Cart` model skeleton (`cart_` prefix id): associations, validations, token, metadata — not yet the checkout owner. `:cart` factory name reclaimed for `Spree::Cart` (the legacy bare incomplete-Order `:cart` factory deleted; its one usage became `:order` — identical semantics).
+- [x] `Checkout::Registry` owns its ordered step list (`base_step_names`, writer for installs that reorder) — `Order.checkout_step_names` circular dependency cut.
+- [x] **Pulled forward from Wave 5 (forced by the `Spree::Cart` class/namespace collision):** legacy `Spree::Cart::*` services split per Key Decision 8 — 4 actually-dead deleted (`Create`, `Update`, `ChangeCurrency`, `EstimateShippingRates`) along with the zero-caller `OrderContents` façade (sole `Cart::Update` caller); 9 alive moved mechanically to `Spree::Carts::*` (DI registrations repointed, dead registrations + unread api `storefront_cart_*` re-exports removed). Behavioral rework stays in T5.1.
+- [ ] Ability/permission wiring for Cart — **deferred to Wave 5** (nothing serves Cart objects through controllers until the flip; wiring now would be dead code).
+
+---
+
+## Wave 2 — Fulfillment & Delivery renames + eligibility (`6.0-fulfillment-and-delivery.md` P1a/P1b/P3 + delivery-zones shipping-side C)
+
+The big mechanical wave. Whole-suite blast radius via factories; one-release constant aliases keep `spree/admin` and `spree/emails` compiling until their sweeps.
+
+### T2.1 Rename migrations (schema only — P1a)
+- [ ] Tables per rename map: `spree_shipments`→`spree_fulfillments`, `spree_shipping_methods`→`spree_delivery_methods`, `spree_shipping_rates`→`spree_delivery_rates`, `spree_inventory_units`→`spree_fulfillment_items`, `spree_shipping_method_zones`→`spree_delivery_method_zones`.
+- [ ] FK/column renames: `delivery_rates.{shipment_id→fulfillment_id, shipping_method_id→delivery_method_id}`, `fulfillment_items.shipment_id→fulfillment_id`, `delivery_method_zones.{shipping_method_id→delivery_method_id, zone_id→delivery_zone_id}` (born joining DeliveryZone), **`return_items.inventory_unit_id→fulfillment_item_id`**.
+- [ ] `state`→`status` on `spree_fulfillments` and `spree_fulfillment_items` (this wave owns these two normalize renames).
+- [ ] `spree_orders.shipment_state`→`fulfillment_status`, `shipment_total`→`delivery_total` — removing the shipped `alias_attribute` bridges in the same change (one-release deprecation aliases the other way).
+- [ ] `display_on` → `storefront_visible` boolean on `spree_delivery_methods` (schema here; value backfill in Wave 7; scopes/`available_to_display?` swap to the boolean; factories set it directly).
+- [ ] Index renames — `spree_shipping_rates_join_index` keeps its **uniqueness** (one-rate-per-method invariant).
+
+### T2.2 New columns/tables (P1b)
+- [ ] `spree_delivery_methods`: `fulfillment_type` (null: false, default `'shipping'`, indexed), `fulfillment_provider` (null: false, default Manual), `pickup_point_provider`.
+- [ ] `spree_fulfillments`: `fulfillment_type`, `pickup_point_data` (json/jsonb-guarded), `cart_id` (nullable — owner pattern).
+- [ ] `spree_delivery_method_stock_locations` join (unique on the pair) + model with vendor-consistency validation stubbed for the marketplace wave.
+- [ ] `spree_products.excluded_delivery_method_ids` (json/jsonb-guarded).
+- [ ] Settled (Decision 4): no owner columns on `spree_delivery_rates` — owner derives through `fulfillment.owner`.
+- [ ] **Not here** (shipped or other plans): StockLocation pickup columns, `store_id` (delivery-rate plan), `vendor_id` (marketplace wave).
+
+### T2.3 Model renames + behavior (P3)
+- [ ] Models/files: `Fulfillment` (`ful_`), `DeliveryMethod` (`dm_`), `DeliveryRate` (`dr_`), `FulfillmentItem` (`fi_`), `DeliveryMethodZone`; one-release aliases (`Spree::Shipment = Spree::Fulfillment` etc.). **ShippingCategory gets no alias** — `NameError` on reference.
+- [ ] `FulfilmentChanger` → `FulfillmentChanger`; `ShipmentHandler` removed (providers replace it in Wave 4).
+- [ ] Status machine preserved exactly: `ready` guard (#2040), `pend`, conditional `resume`, `ready_for_pickup` reachable from `ready` + cancelable, all `after_transition` hooks (restock/unstock, StateChange rows, `set_fulfilled_at`); `shipped`→`fulfilled`, `shipped_at`→`fulfilled_at`; the three `update_columns` escape hatches rewritten through the machine or documented freeze-safe. New numbers `F`-prefixed; existing `H` numbers untouched.
+- [ ] Raw-SQL/table-literal fixes that survive renames silently: `reverse_chronological`, `with_free_shipping_promotion?`, `Package#shipping_categories` SQL, `determine_state` string literals.
+- [ ] Order side: association renames (`fulfillments`, `delivery_total`), rollup rename with **`backorder` preserved** (domain: `backorder|canceled|partial|pending|ready|fulfilled` + nil; `ready_for_pickup`/`picked_up` roll up as `ready`/`fulfilled`), `not_shipped`-scope and `allow_cancel?` reads updated.
+- [ ] CanCanCan grants, PermittedAttributes, seeds (incl. `Seeds::DigitalDelivery` + the hardcoded `'Digital'`/`'Default'` category readers), factories (`shipment_factory`→`fulfillment_factory` etc. with aliases; `product_factory` stops assigning shipping categories — whole-suite impact).
+
+### T2.4 Eligibility rework — ShippingCategory retired from behavior (needs T0.1)
+- [ ] `Package#eligible_delivery_methods` replaces `Package#shipping_methods`: intersect package items' `fulfillment_types` (via ProductType, `['shipping']` fallback when typeless) with `DeliveryMethod#fulfillment_type`, minus per-product `excluded_delivery_method_ids`. Seam stays **inside `Stock::Estimator#shipping_methods`**.
+- [ ] `Stock::Splitter::ShippingCategory` → `Splitter::FulfillmentType` (homogeneous packages by fulfillment type); `Splitter::Digital` folds in.
+- [ ] Digital discriminator to columns: `DeliveryMethod#digital?/pickup?/pickup_point?/requires_address?`; `.digital` scope; `Product#digital?` + net-new `Product#fulfillment_types` via ProductType; `DigitalDelivery` calculator demoted to plain zero-cost (calculators stay — decisions.md 2026-07-27).
+- [ ] Remove ShippingCategory presence-validation/auto-assign from Product **now** (tables/columns drop in 6.1; products must stay saveable in between).
+- [ ] Parity spec target: mixed carts still split + get rates (`order_routing/strategy/parity_spec.rb:426-452` rewritten to the new inputs).
+
+### T2.5 Delivery-zones shipping consumers (delivery-zones Phase C, shipping slice)
+- [ ] `DeliveryMethod has_many :delivery_zones`; `#include?(address)` over DeliveryZone; Estimator zone-check swap.
+- [ ] `Store#countries_with_shipping_coverage` rewritten on DeliveryZone members.
+- [ ] Factories: delivery methods worldwide-by-default (no zones); `Zone.global` monkey-patch retired from the shipping path (zone factories stay for tax until the tax plan). Permission sets grant DeliveryZone.
+- [ ] `Spree::Zone` itself **stays** (tax + legacy admin) — its removal is tax-provider Phase 5 + delivery-zones Phase D, out of scope.
+
+---
+
+## Wave 3 — Split Adjustments (`6.0-split-adjustments.md` P0/P1/P3 + minimal TaxProvider) — still on the Order-based checkout
+
+Runs after Wave 2 (tables born with `fulfillment_id`). Can proceed in parallel with Wave 4.
+
+### T3.1 Order-level freeze (P0 — precondition, built and tested first)
+- [ ] `OrderUpdater` refuses adjustment recalculation on completed orders. This must exist before the Adjustment state machine goes.
+
+### T3.2 Typed tables (P1)
+- [ ] `spree_tax_lines`: owner XOR `cart_id`/`order_id`, nullable `tax_rate_id`, adjustable XOR `line_item_id`/`fulfillment_id`/`fee_id`, `amount` + `rate` (null: false), `label` (null: false), `included` (null: false), `provider_id`, `data` json, `metadata`. Plain FK indexes, **no** upsert identity.
+- [ ] `spree_discounts`: owner XOR, nullable `promotion_action_id`/`promotion_id`, adjustable XOR, `amount` null: false + **DB CHECK ≤ 0**, `label`, `kind`, `code` (indexed), `value`, `value_type`, `metadata`.
+- [ ] `spree_fees`: owner XOR, `line_item_id`/`fulfillment_id` both-nullable (both nil ⇒ order-level), `amount` null: false + **CHECK ≥ 0**, `label`, `kind` null: false, `metadata`; index `[order_id, kind]`.
+- [ ] `spree_orders.fee_total`.
+
+### T3.3 Models + adjusters
+- [ ] `TaxLine` (`tl_`), `Discount` (`disc_`), `Fee` (`fee_`) per plan code blocks (+ `Spree::Metadata`, XOR validations, scopes); Order/Cart/LineItem/Fulfillment associations incl. the through-associations.
+- [ ] `Spree::Adjusters::Base` + `Adjusters::Promotion`: candidate computation returns **all** candidates; winner-only selection isolated in **one method** (6.1 stacking slots in there); clamping so net never goes below zero; provenance snapshots (`code`/`value`/`value_type`); `dependent: :nullify` from the promotion side.
+- [ ] FreeShipping → fulfillment-attached `Discount`, persisted **even at zero**; `Order#has_free_shipping?` tests row existence.
+- [ ] Order-level discount distribution: largest-remainder, prorated over each line's *remaining discounted* base, weights frozen at placement.
+- [ ] Manual paths: `Discount(kind: 'manual')` (line-targeted or order-distributed) and `Fee` (order-level or attached); ad-hoc credits are manual Discounts, never negative Fees.
+- [ ] Promotion STI namespace rename rides here: `Spree::Promotion::Rules::*`→`Spree::PromotionRules::*`, `Actions::*`→`PromotionActions::*`, `CreateItemAdjustments`→`CreateItemDiscounts` (one-release aliases; `type`-column data task in Wave 7).
+
+### T3.4 Minimal TaxProvider (the sanctioned TaxLine writer)
+- [ ] `Spree::TaxProvider::Base` (estimate required; commit/void/refund no-op stubs; `exempt?` default) + `Spree::TaxProvider::Internal` computing directly from TaxRate data (rate × discounted base; VAT included-in-price math) — **no `Calculator::DefaultTax` indirection**; zone matching stays as today (`TaxRate.match` over `Spree::Zone`) until the tax plan decouples it.
+- [ ] Write contract: **replace-all set semantics** per estimate (delete target items' TaxLines, insert fresh — kills stale tax after address changes); internal rows keep `tax_rate_id` + snapshot `rate`/`label`/`provider_id: 'internal'`.
+- [ ] `Spree.tax_provider` seam (global default → Internal; per-Market resolution arrives with the full tax plan).
+- [ ] Removed: `TaxRate.adjust`, `AdjustmentSource`, `Calculator::DefaultTax`, `Adjuster::Tax`. TaxRate becomes pure configuration.
+
+### T3.5 Typed recalculation + consumer rewrite
+- [ ] `OrderUpdater`: two-pass preserved — discount/fee adjusters persist the discounted taxable base (+ `pre_tax_amount`), then `Spree.tax_provider.estimate`; totals via grouped SUMs from typed tables; all denormalized columns kept (incl. `taxable_adjustment_total`/`non_taxable_adjustment_total`) + new `fee_total`; freeze guard from T3.1.
+- [ ] Consumers rewritten off `source_type`/`eligible`: the ~12 Order readers (`order_level_promo_total`, `shipping_discount`, `valid_promotion_ids`, `cart_promo_total`, `has_free_shipping?`, `fully_discounted?`, `taxable_amount`, …), `Promotion#credits_count` (distinct orders with the promotion's discounts), coupon handlers, `CouponCodesHandler`, `OrderPromotion#amount`, cross-adjustable negative-total guard, `OrderMerger`, `Cart::Empty`, refund calculators (`DefaultRefundAmount` reads the line's own discounts).
+- [ ] Removed: `Spree::Adjustment` model, `Adjustable::AdjustmentsUpdater`, `Adjustable::Adjuster::*`, `PromotionAccumulator` (dead). `spree_adjustments` table **kept read-only** through 6.0 (audit + rollback reference).
+- [ ] CanCanCan: grants on TaxLine/Discount/Fee replace Adjustment grants.
+- [ ] Factories + the ~65 affected spec files.
+
+---
+
+## Wave 4 — Fulfillment providers + lifecycle events (`6.0-fulfillment-and-delivery.md` P4) — parallelizable with Wave 3
+
+- [ ] **T4.1 Provider strategy:** `FulfillmentProvider::{Base,Manual,Digital,Pickup,PickupPoint}`; string class name on DeliveryMethod, constantized at call time; `Spree.fulfillment_providers` + `Spree.fulfillment_types` registries (open strings, no inclusion validation); wired into fulfillment transitions.
+- [ ] **T4.2 Digital auto-fulfillment (new behavior):** `FulfillmentProvider::Digital` fires `fulfill!` on order completion and creates DigitalLinks **idempotently, per quantity** — the non-idempotent checkout-callback link creation is removed here (wired from today's `finalize!`; re-pointed to pipeline step F5 in Wave 5).
+- [ ] **T4.3 Events:** `fulfillment.{ready,fulfilled,canceled,resumed}` + `publishes_lifecycle_events`; `order.fulfilled` when the last fulfillment fulfills + `Order#fully_fulfilled?`; one-release dual-emit of legacy `shipment.*` webhooks (Decision 6 — dropped 6.1); `PickupPointProvider::Base` + `PickupPointOption` struct (`find_nearby`/`find_by_external_id`; ephemeral, frozen into `fulfillment.pickup_point_data` on selection).
+
+---
+
+## Wave 5 — The flip: Cart becomes the checkout owner (`6.0-cart-order-split.md` P3 + P4)
+
+The point of no return; biggest single wave. Everything before it exists so this copy contract is written once.
+
+### T5.1 Cart behavior
+- [ ] Full Cart model: binding settles the three inconsistent creation paths (market/channel/locale always set); recalculation-on-write — address/market change → re-price, re-tax (provider estimate on the cart), **idempotent** delivery-proposal rebuild (destructive `create_proposed_shipments` behavior dies); item changes → totals + reservation Release/Reserve/Extend dispatch carried over from `Carts::Update`.
+- [ ] Fulfillments, delivery rates, and typed money lines are created **cart-owned** during checkout (owner XOR flips to `cart_id`).
+- [ ] `Carts::{Create,Update,UpsertItems}` operate on Cart + get DI registration; `current_order` → `current_cart` built through `Carts::Create`.
+- [ ] Legacy `Spree::Cart::*` services: 8 dead ones deleted; 6 re-homed (AddItem/SetQuantity/RemoveLineItem → carts items flow; Associate; Empty; RemoveOutOfStockItems; CompareLineItems → merge strategy).
+- [ ] Merge strategy seam (`Spree::Dependencies.cart_merge_strategy`) + default preserving OrderMerger behavior minus its bugs (currency-mismatch surfaced, no silent >10 overflow destroy).
+- [ ] Tiered expiry reaper (guest 30d / customer 90d / empty 48h — config preferences, Decision 5) on indexed `updated_at`, batched; **never reaps carts with authorized/pending payment sessions or transactions**.
+- [ ] `Carts::Validate`: full battery (lines present/in stock/not discontinued, email, addresses, delivery selected, payment coverage, guest policy) returning structured `{ step, field, code, message }` errors; also exposed read-only for checkout-readiness rendering.
+
+### T5.2 `Carts::Complete` — three-phase pipeline
+- [ ] **PREPARE** (one txn): replay via `completion_result(cart)` (order or order_group); `with_lock` + `completing_at` with TTL takeover; in-lock recalculation; `expected_total` drift guard (409 `cart_changed`); Validate; reservation availability check + hold extension; draft Order creation with copies (line items re-pointed, typed lines per the split-adjustments copy contract, fulfillments + selected rates, **address copies**, email/currency/locale/market/channel, guest token carried, `R` number) + unique `orders.cart_id`.
+- [ ] **PAYMENT:** offline methods (Check, terms, COD, bank transfer, store credit, gift cards, manual) collapse into FINALIZE — single txn, nothing to compensate; external gateways outside any txn with Y3 compensation (destroy draft + copies, clear `completing_at`, 422 `payment_failed`); completion gates on "valid payment covers total", never `paid?`; store credit recalculated in P3 and voided last; `allow_checkout_on_gateway_error` external-only.
+- [ ] **FINALIZE** (one txn, every step idempotent): inventory finalize + unstock + reservation release (single home — fixes the admin-path asymmetry); counters behind persisted flags (coupon, gift card redeem, promo credits); vendor-split hook F3 (no-op single partition); `draft`→`placed` + `cart.completed_at` + `RecomputeStatuses`; after_commit events (`order.placed`/`order.completed`), digital fulfillment via provider, account creation/newsletter as non-fatal side jobs.
+- [ ] Resumability structural (`status: 'draft'` + `cart_id` + `completed_at: nil` = finalize pending); completion-recovery sweeper job (retries FINALIZE for stale drafts with paid coverage; alerts on persistent failure; **never auto-refunds**); webhook writer (`Payments::HandleWebhook`) converges on the same service — 30s delay becomes latency optimization only.
+- [ ] Mutation guards: `completing_at` → 409 `cart_locked` on item/address/discount writes; `lock_version` → 409 `stale_cart`.
+- [ ] Admin/B2B `Orders::Complete` path reuses the same service (idempotency + inventory + reservation release in one place).
+- [ ] API contract: the full outcome table (200 order/order_group incl. replay; 422 validation errors in requirements shape; 422 `payment_failed`; 409 `cart_changed`/`completion_in_progress`/`cart_locked`).
+
+### T5.3 Machine removal (P4)
+- [ ] Delete `Order::Checkout`, the `spree_orders.state` column, `checkout_flow`/`insert_checkout_step`/`remove_checkout_step`, `next!`/`advance`/`can_go_to_state?` (Decision 3: hard removal + migration guide, no shim).
+- [ ] Order lifecycle without a machine: `status` draft/placed/canceled; `completed?` ≡ `completed_at`; `can_ship?`/`uneditable?`/`allow_cancel?`/`LINE_ITEM_REMOVABLE_STATES`-style predicates re-expressed; `partially_canceled` derived predicate (Decision 8); `awaiting_return`/`returned` **not** carried (returns plan).
+- [ ] `Orders::Cancel/Resume/Approve` flip `status` with today's side effects verbatim (restock/void/refund branches).
+- [ ] `confirmation_required?` computed from data only (config + selected payment methods); no state fallback on confirm failure.
+- [ ] Order `state_changes` writes dropped (lifecycle events are the audit); payment/fulfillment StateChange rows unaffected.
+- [ ] Ransack whitelist: `state` out; `status`/`payment_status`/`fulfillment_status` in.
+- [ ] The six out-of-band `state` writers (address services etc.) become cart-recalculation triggers.
+
+### T5.4 `RecomputeStatuses` (single writer)
+- [ ] `Spree::Orders::RecomputeStatuses` — the only writer of `payment_status` + `fulfillment_status`; quantize to currency precision before comparing; subtract granted/pending refunds; domains incl. `overcharged`/`voided` (payment) and `backorder` (fulfillment, owned by the fulfillment plan); triggered from payment/refund/fulfillment/return event subscribers, never inline from controllers; replaces `OrderUpdater#update_payment_state`/`update_shipment_state`.
+
+### T5.5 Test support rewrite
+- [ ] `order_walkthrough` cart-first; order/cart factories (order factories build completed orders through the real completion service or direct construction — decide pattern here); whole-suite green across engines.
+
+---
+
+## Wave 6 — API / SDK / Dashboard / emails / docs
+
+### T6.1 Store API v3
+- [ ] `carts/fulfillments_controller` requirements-driven (drop the `cart.next` loop); completion endpoint returns the Wave-5 contract.
+- [ ] Pickup flows: `GET /store/delivery_methods?fulfillment_type=pickup`, `…/:id/pickup_locations` (pickup-enabled StockLocations, **package-scoped** stock), `…/:id/pickup_points?latitude&longitude`; selection writes `Order#preferred_stock_location_id` (routing rule) / validated `pickup_point_external_id` frozen into `pickup_point_data`.
+- [ ] `FulfillmentSerializer#fulfillment_type` computed → column-backed; `storefront_visible` exposure; `ready_for_pickup` returned as its own status (Decision 7).
+
+### T6.2 Admin API v3
+- [ ] `/admin/orders/:id/{tax_lines,discounts,fees}` replace `/admin/orders/:id/adjustments`: tax_lines read-only; discounts/fees full CRUD for manual rows (promotion-sourced rows 422 on edit); mutations run recalculation on the changed base — this **is** the sanctioned post-placement edit path and works on completed orders.
+- [ ] Net-new `delivery_methods` CRUD controller (none exists today) + nested `delivery_method_stock_locations`; `delivery_zones` CRUD with typed members.
+- [ ] Fulfillments admin surface completed (create via `Fulfillments::Create`, ready/fulfill/cancel/track through providers); admin Drafts list scoped `cart_id: nil`; status filters (`status`/`payment_status`/`fulfillment_status`).
+- [ ] Scopes (`read_orders`/`write_orders`, delivery settings scopes) + CanCanCan abilities on the typed models.
+
+### T6.3 SDK + Dashboard
+- [ ] admin-sdk: `orders.{taxLines,discounts,fees}` replacing `orders.adjustments` (unreleased — break cleanly); `deliveryMethods`, `deliveryZones`; fulfillments updates. Full type pipeline: typelizer → Zod → integration specs → `rswag:specs:swaggerize` → SDK tests.
+- [ ] Dashboard order detail: typed panels (tax grouped by rate/label, discounts, fees) + "Add fee"/"Add discount" (amount-or-percent via `value`/`value_type`, target picker order/line), `<Can>`-gated, RHF + Zod + `mapSpreeErrorsToForm`; fulfillment vocabulary + status/actions sweep (remaining `shipment` refs: `orders/$orderId.tsx`, `schemas/webhook-endpoint.ts` event list — dual-emit names).
+- [ ] Dashboard settings: Delivery Methods page (fulfillment_type, provider selects, pickup locations, `storefront_visible`, zone picker) and Delivery Zones page (typed member editor incl. postal ranges/prefixes).
+- [ ] i18n keys in **all** locale files (en/de/fr/zh-CN/ar/pl, dashboard + dashboard-core); e2e specs for the new pages.
+
+### T6.4 Emails
+- [ ] Fulfillment vocabulary sweep (~20 files: `shipment_mailer` → fulfillment, subscriber, templates); `_purchased_items_table` partials iterate typed associations (no `.eligible`/`source_type`); payment-link email `checkout_state_url(token, :payment)` → cart checkout URL.
+
+### T6.5 Docs + guides
+- [ ] `adjustments.mdx` rewritten for typed models; `custom-promotion.mdx` (adjusters write Discount/Fee); checkout/requirements docs; **extension migration guide** (`checkout_flow` → `Checkout::Registry`; `ShipmentHandler` → FulfillmentProvider; `shipment.*` → `fulfillment.*` webhooks); CSV import/export `shipping_category` mapping + deprecation window; CLAUDE.md plan-status updates.
+
+---
+
+## Wave 7 — Data migrations (LAST) + upgrade manifest
+
+All batched, idempotent, resumable. They read legacy structures that stay in place (see "Why this order" #4).
+
+- [ ] **T7.1 `spree:migrate_shipping_to_delivery`**: stored polymorphic strings (`spree_state_changes.stateful_type`+`name`, `spree_adjustments.adjustable_type`, `spree_stock_movements.originator_type`: `'Spree::Shipment'`→`'Spree::Fulfillment'`); `fulfillment_type` backfill (DigitalDelivery-calculator methods → `'digital'` + Digital provider, rest `'shipping'`; copied to existing fulfillments); ShippingCategory → ProductType (digital categories → `Digital` ProductType assigned to their products — the sanctioned one-time assignment; everything else rides the `['shipping']` default); `display_on` value conversion.
+- [ ] **T7.2 `spree:migrate_zones_to_delivery_zones`**: shipping-referenced Zones → DeliveryZones (name/description + country/state members); tax-only zones left for the tax plan; unreferenced zones logged + skipped.
+- [ ] **T7.3 Adjustments → typed rows**: mapping table per plan (TaxRate→TaxLine w/ rate copy + `provider_id: 'internal'`; eligible PromotionAction→Discount w/ snapshots; ineligible skipped; nil-source by sign → manual Discount / order-level Fee `'surcharge'`; ReturnAuthorization skipped + order marked recalculation-frozen; unknown sources → Fee with class in metadata); order-level rows distributed largest-remainder; **order totals byte-for-byte untouched**; per-order reconciliation asserts typed sums match legacy totals (non-reconciling orders logged + frozen, never force-balanced); line-level shift logging.
+- [ ] **T7.4 Incomplete orders → Carts**: one Cart per incomplete order (token/binding/addresses); line items re-owned (`cart_id` set, `order_id` nulled); hollow order rows deleted; mid-payment orders converted **last** with payment sessions re-linked; completed orders untouched (`cart_id: nil`).
+- [ ] **T7.5 Small companions**: promotion rules/actions STI `type`-column task (`Spree::Promotion::Rules::*` → `Spree::PromotionRules::*` etc.); product-types backfill (store_id → `Store.default`, orphaned join rows deleted, `reset_counters`).
+- [ ] **T7.6 Upgrade manifest**: documented 5.6→6.0 order (migrate, then tasks in the sequence above), rollback notes (`spree_adjustments` intact and re-derivable through 6.0; `spree_carts` conversion reversible until the old rows age out), operator checklist.
+
+---
+
+## Traceability (plan phase → task)
+
+| Plan | Phase | Task |
+|---|---|---|
+| cart-order-split | P1 schema | T1.1 |
+| cart-order-split | P2 data | T7.4 |
+| cart-order-split | P3 model+services | T1.2, T5.1, T5.2, T5.5 |
+| cart-order-split | P4 machine removal | T5.3, T5.4 |
+| cart-order-split | P5 API/SDK/docs | T6.1, T6.3, T6.4, T6.5 |
+| fulfillment | P0 gates | T0.1, T0.3, T1.1 |
+| fulfillment | P1a/P1b schema | T2.1, T2.2 |
+| fulfillment | P2 data | T7.1 |
+| fulfillment | P3 models+eligibility | T2.3, T2.4, T2.5 |
+| fulfillment | P4 providers+events | T4.1–T4.3 |
+| fulfillment | P5 surfaces | T6.1–T6.4 |
+| split-adjustments | P0 freeze | T3.1 |
+| split-adjustments | P1 tables | T3.2 |
+| split-adjustments | P2 data | T7.3 |
+| split-adjustments | P3 models | T3.3, T3.4, T3.5 |
+| split-adjustments | P4 API/SDK/admin | T6.2, T6.3 |
+| product-types | P1 (minimal) | T0.1, T7.5 |
+| delivery-zones | A + C(shipping) | T0.3, T2.5, T7.2 |
+| tax-provider | minimal Internal | T3.4 |
+
+## Rough sizing
+
+| Wave | Size | Dominant risk |
+|---|---|---|
+| 0 | M | Prototype rename ripples (permitted attrs, factories) |
+| 1 | M | LineItem owner touches pricing/tax/inventory paths |
+| 2 | **XL** | Whole-suite factory churn; silent raw-SQL survivors |
+| 3 | **XL** | Promotion/refund money math parity; ~65 spec files |
+| 4 | M | Digital auto-fulfillment is new behavior |
+| 5 | **XL** | Completion pipeline correctness (idempotency, payment edges); order_walkthrough rewrite |
+| 6 | L | Net-new admin surfaces (delivery methods/zones) + full type pipeline |
+| 7 | L–M | Reconciliation logic in T7.3; ordering guarantees in T7.4 |
diff --git a/docs/plans/6.0-fulfillment-and-delivery.md b/docs/plans/6.0-fulfillment-and-delivery.md
index 20c7dd6b88..9df6163309 100644
--- a/docs/plans/6.0-fulfillment-and-delivery.md
+++ b/docs/plans/6.0-fulfillment-and-delivery.md
@@ -4,7 +4,7 @@
**Target:** Spree 6.0
**Depends on:** `6.0-product-types.md` (`fulfillment_types` addendum 2026-07-27 — ProductType replaces ShippingCategory; **hard blocker**, `Spree::ProductType` does not exist yet), `6.0-cart-order-split.md` (where fulfillments/rates live pre-completion), `6.0-order-routing.md` (packages come from `for_allocation`), `6.0-normalize-state-to-status.md`. Coordinates with: `6.0-delivery-rate-provider.md` (owns `store_id` on DeliveryMethod; calculators stay per decisions.md 2026-07-27), `5.5-6.0-display-on-to-boolean.md` (`storefront_visible` lands in the same migration wave), `6.0-multi-vendor-marketplace.md` (`vendor_id`, lifecycle events, `delivery_amount`). Gates: `6.0-split-adjustments.md` and `6.0-typed-stock-movements.md` are born with `fulfillment_id` — **this plan's Phase 1 must land before both**.
**Author:** Damian + Claude
-**Last updated:** 2026-07-27
+**Last updated:** 2026-07-28
## Summary
@@ -107,7 +107,7 @@ Built-ins: `Manual` (default — current admin-driven behavior), `Digital`, `Pic
### Owner is cart-or-order
-Checkout — where fulfillments and delivery rates are created and selected — happens on the **Cart** under copy-on-completion semantics. `Fulfillment` and `DeliveryRate` follow the split-adjustments house pattern: nullable `cart_id` / `order_id` with an exactly-one validation, re-pointed at `Spree::Carts::Complete` (and again at vendor split). The exact shape is confirmed when `6.0-cart-order-split.md` is fleshed out (Open Question 1) — but `belongs_to :order` hard-required is known-wrong and must not be implemented.
+Checkout — where fulfillments and delivery rates are created and selected — happens on the **Cart** under copy-on-completion semantics. `Fulfillment` follows the house pattern: nullable `cart_id` / `order_id` with an exactly-one validation, re-pointed at `Spree::Carts::Complete` (and again at vendor split). `DeliveryRate` carries **no owner columns** (settled 2026-07-28) — a rate belongs to its fulfillment and derives the owner through it; `spree_shipping_rates` has neither FK today, and duplicating the pair would be drift risk at every re-pointing. `belongs_to :order` hard-required is known-wrong and must not be implemented.
### `Fulfillment#delivery_amount` (commission base)
@@ -304,11 +304,13 @@ Batched, idempotent, resumable — same guarantees as the split-adjustments migr
7. **Pickup selection routes through `Order#preferred_stock_location_id`** and the `PreferredLocation` routing rule; stock checks are package-scoped; `pickup_stock_policy: 'any'` refused for vendor-owned locations.
8. **Fulfillment numbers**: existing `H` numbers stay; new records use `F`.
+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`.
+
## Open Questions
-1. ~~Owner shape~~ — **resolved 2026-07-27** with the cart-order-split expansion: dual `cart_id`/`order_id` exactly-one is the unified pattern (LineItem included, no polymorphism); Phase 1b's `cart_id` is unblocked.
-2. **Webhook dual-emit window** — is one release enough for `shipment.*` subscribers, or does Enterprise need a longer bridge?
-3. **`ready_for_pickup` in the Store API** — expose as its own status or map onto `ready` with `fulfillment_type` disambiguating?
+None at this time.
## References
diff --git a/docs/plans/6.0-split-adjustments.md b/docs/plans/6.0-split-adjustments.md
index 4cb7fd3804..f33f49bc9a 100644
--- a/docs/plans/6.0-split-adjustments.md
+++ b/docs/plans/6.0-split-adjustments.md
@@ -4,7 +4,7 @@
**Target:** Spree 6.0
**Depends on:** `6.0-cart-order-split.md` (owner semantics — typed lines are written during the cart phase and copied on completion), `6.0-fulfillment-and-delivery.md` Phase 1 (tables are born with `fulfillment_id`, never migrated from `shipment_id`). Consumed by: `6.0-tax-provider.md` (providers write TaxLine), `6.0-multi-vendor-marketplace.md` (typed lines re-home at order split), `6.0-returns-exchanges-claims.md`, `6.0-normalize-state-to-status.md`.
**Author:** Damian + Claude
-**Last updated:** 2026-07-27
+**Last updated:** 2026-07-28
## Summary
@@ -406,7 +406,7 @@ Order-level rows (`adjustable_type == 'Spree::Order'`): promotion and manual dis
10. **Discount provenance survives promotion deletion**: `code`/`value`/`value_type` snapshots + `dependent: :nullify` (OSS platform B's SET_NULL-plus-snapshot pattern).
11. **Post-placement admin edits** happen through the typed CRUD endpoints (see "Admin management surface"): manual fees and discounts are created/edited directly and trigger recalculation on the changed base; tax lines are never hand-edited — tax follows from the order's state via the provider.
-12. **Owner shape confirmed** (2026-07-27, with the cart-order-split expansion): the dual `cart_id`/`order_id` exactly-one pattern is the unified owner design for LineItem, the typed lines here, and Fulfillment/DeliveryRate — one pattern everywhere, `#owner` as a method, no polymorphism. Provenance flows through `Order#cart_id`.
+12. **Owner shape confirmed** (2026-07-27, with the cart-order-split expansion): the dual `cart_id`/`order_id` exactly-one pattern is the unified owner design for LineItem, the typed lines here, and Fulfillment — one pattern everywhere, `#owner` as a method, no polymorphism (`DeliveryRate` carries no owner columns and derives through its fulfillment — settled 2026-07-28). Provenance flows through `Order#cart_id`.
## Open Questions
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 9b7587ccdb..ee6083187b 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -408,3 +408,36 @@ same format `has_secure_password` reads — so the rake task migrating
spree-starter installs onto `spree_customers` copies it to `password_digest`
and **no customer resets their password** (task aborts loudly if
`Devise.pepper` is set).
+
+## 2026-07-28: Core-rewrite implementation decisions (cart/order split + fulfillment + split adjustments)
+
+Interactive review settled everything blocking implementation start; task
+sequencing lives in `docs/plans/6.0-core-rewrite-tasks.md` (7 waves, data
+rake tasks last).
+
+1. **ProductType prerequisite is the minimal Phase 1 slice** — rename +
+ store ownership + `fulfillment_types` + `Product#product_type_id`. The
+ rest of `6.0-product-types.md` (custom-field-definition join, live
+ template propagation, its API/dashboard) ships as its own effort.
+2. **`spree_admin` is dropped from the spree-starter Gemfile on the 6.0
+ line.** The legacy admin's adjustments/checkout screens hard-break when
+ `Spree::Adjustment` and the Order state machine are removed; rather than
+ limp on aliases, the dev server stops loading the gem — the React
+ dashboard is the only admin. The gem stays in the monorepo untouched
+ (it's already out of the CI matrix) until its 6.0 deletion; one-release
+ constant aliases (`Spree::Shipment = Spree::Fulfillment`, …) still ship
+ for extensions and the emails gem.
+3. **`checkout_flow`/`insert_checkout_step` are hard-removed in 6.0** — no
+ translation shim (machine transitions have no `Checkout::Registry`
+ equivalent); migration guide instead.
+4. **`DeliveryRate` carries no owner columns** — it derives `owner` through
+ its fulfillment. The dual-FK pattern covers LineItem, the typed money
+ lines, and Fulfillment; rates were never directly order-linked.
+5. **Cart reaper defaults: guest 30d, customer 90d, empty carts 48h**
+ (config preferences; carts with authorized/pending payment sessions are
+ never reaped, unconditionally).
+6. **`shipment.*` webhooks dual-emit for exactly one release**, dropped in 6.1.
+7. **`ready_for_pickup` is a first-class Store API status** (not mapped
+ onto `ready`); the order-level rollup still reports `ready`.
+8. **`partially_canceled` becomes a derived predicate** over child
+ cancellations, not a stored status value.