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.

Record the fulfillment and order-edit decisions

Damian Legawieccd8538c70679
diff --git a/CLAUDE.md b/CLAUDE.md
index c7edca9c5b..b702410703 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`
+- `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-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)
@@ -52,7 +52,7 @@ Multi-version plans (some phases shipped, some pending):
- `5.6-dashboard-typed-plugin-routes.md` — Plugin file routes compiled into the host's TanStack route tree: `spree.dashboard.routes` marker + virtual-route-config composition in `@spree/dashboard/vite`, `createDashboardRouter` + `<Dashboard router>` ownership inversion, typed cast-free links, cross-package collision pre-flight with package-named errors. Runtime route registry stays for dynamic/in-app cases (catch-all is lowest priority). Implemented; published-tarball spike passed.
Pending design work (drafts, no implementation yet):
-- `6.1-order-change-substrate.md` — `Spree::OrderChange` + `Spree::OrderChangeAction`: one preview-then-apply substrate behind every post-placement mutation (admin order edits, returns, exchanges, claims, draft-order amendments), replacing four per-domain draft models with one `begin → request → confirm → cancel` lifecycle. Actions are typed `kind` + concrete FKs (never polymorphic); **preview is computed in memory and never persisted**; confirm is a workflow with the balance settlement as an `external_step`. Deliberately 6.1 — new schema + new extension API, and 6.0 already carries the Cart/Order split, typed adjustments and the returns rework. 6.0 constraint: don't build a per-domain persisted preview/draft model, and expose post-placement money math through a service returning a value object so it can be re-pointed later.
+- `6.1-order-change-substrate.md` — `Spree::OrderChange` + `Spree::OrderChangeAction`: one preview-then-apply substrate behind every post-placement mutation (admin order edits, returns, exchanges, claims, draft-order amendments), replacing four per-domain draft models with one `begin → request → confirm → cancel` lifecycle. Actions are typed `kind` + concrete FKs (never polymorphic); **preview is computed in memory and never persisted**; confirm is a workflow with the balance settlement as an `external_step`. Deliberately 6.1 — new schema + new extension API, and 6.0 already carries the Cart/Order split, typed adjustments and the returns rework. **Resolved 2026-08-10:** a change set belongs to one `Order`, never an `OrderGroup` (multi-vendor edits = N change sets, each settling against its own order); a pending change set does **not** hold stock (`add_item` takes stock at confirm — reservations are checkout-scoped and would have no expiry trigger here). Phase 3 replaces the **6.0 immediate-write order edit screen** (`/orders/$orderId/edit`, shipped 2026-08-10) — it writes on every interaction and shows no delta, and Phase 3 adds `begin`/preview/`confirm` behind the same route. 6.0 constraints: don't build a per-domain persisted preview/draft model (including a client-side pending-edit buffer in React state), expose post-placement money math through a service returning a value object, and keep line-item mutation on the edit screen rather than the fulfillment card.
- `6.0-payment-method-rules.md` — `Spree::PaymentMethodRule` STI on PaymentMethod (Channel / Market / OrderTotal / CustomerGroup rules), mirroring the PromotionRule/PriceRule/OrderRoutingRule pattern. Enforced solely through `Order#collect_frontend_payment_methods` (listing + `Payments::Create` + payment sessions all flow through it); admin/backoffice bypasses; no rules = available everywhere. Dashboard-only management (nested Admin API CRUD + `/payment_method_rules/types` discovery). Supersedes the "no distribution concept" rationale in `5.6-6.0-single-store-promotions-payment-methods.md`; per-channel provider credentials (multiple Stripe accounts, multi-entity setups) explicitly deferred for grooming — see decisions.md 2026-07-23.
- `6.0-channel-delivery.md` — **Implemented in PR #14404 (2026-08-09).** Optional Channel→StockLocations allowlist (`spree_channel_stock_locations`, empty = all): constrains which fulfillment origins serve a channel's traffic, enforced origin-side (Coordinator allocation + pickup discovery intersect `Channel#serves_location?`) — never on profiles/groups (channel constraint composes from outside; Medusa-shaped transitive delivery). `preferred_stock_location_id` must be a served location. **Per-channel rates** are a separate axis: `DeliveryMethodRules::ChannelRule` (STI, beside ItemTotal/Weight/ExcludedProducts) gates which methods a channel is *offered* from origins it already reaches — origins decide whether a channel can be served, rules decide what it sees.
- `6.0-channel-markets.md` — Optional Channel→Markets allowlist (`spree_channel_markets` join, empty = all markets). Enforced in market resolution (`set_market_from_country` + channel-aware `Spree::Current.market` fallback), channel-filtered Store API `/store/markets`, and order-level `market must be served by channel` validation. Composes with `MarketRule` from the payment-method-rules plan.
diff --git a/docs/plans/6.0-fulfillment-and-delivery.md b/docs/plans/6.0-fulfillment-and-delivery.md
index 4cfbcdbf61..a7ffa9004c 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; **shipped**, including the `fulfillment_types` column), `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` — DeliveryMethod moved off the `Spree::DisplayOn` concern 2026-08-05), `6.0-multi-vendor-marketplace.md` (`vendor_id`, lifecycle events, `delivery_amount`). Gates: `6.0-6.1-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-08-06 (pickup work beyond shipped code deferred to 6.1; interface marked experimental — see Implementation status)
+**Last updated:** 2026-08-10 (partial fulfillment lands as `Fulfillments::Fulfill` — resolved question 12)
## Summary
@@ -364,6 +364,42 @@ Batched, idempotent, resumable — same guarantees as the split-adjustments migr
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`.
+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
+ split-then-ship in an `after_transition` callback is the shape
+ `6.0-service-workflows.md` prohibits. `Spree::Fulfillments::Fulfill` takes
+ `fulfillment:` plus optional per-line-item quantities: absent, it fulfills
+ everything (today's behavior); given a subset, it splits and fulfills the
+ new fulfillment in one transaction. The admin `fulfill` endpoint gains an
+ optional `items` param. The state machine stays exactly as resolved in
+ question 1 — the workflow calls it, mirroring `Fulfillments::Create`'s
+ `mark_shipped`. See decisions.md 2026-08-10.
+
+13. **Fulfillment side effects leave the state machine; the machine keeps the status column** (2026-08-10).
+ Amends question 1's "all transition hooks are preserved". `after_cancel`
+ (restock + `provider.cancel_fulfillment`) and `after_resume` (re-unstock)
+ no longer run as `after_transition` callbacks — they are steps in
+ `Spree::Fulfillments::Cancel` / `::Resume`, with the provider call an
+ `external_step` so carrier I/O never sits inside the transaction holding
+ the stock movements. What the machine keeps: the status column, the
+ transition graph and its guards, and the `publish_*_event` callbacks, which
+ describe the status change itself. `Fulfillment#after_cancel`/`#after_resume`
+ survive one release as deprecated shells and are the *only* trace left on
+ the model. The stock movements live in the workflow steps themselves, not
+ in model methods the workflows call: adding `#restock_units`/`#unstock_units`
+ to Fulfillment was tried and rejected, because new public model surface
+ created for workflows to call is exactly what breaks when the machine is
+ removed later. `Orders::Cancel`/`::Resume` delegate to the fulfillment
+ workflows rather than reimplementing them; Cancel passes
+ `notify_provider: false` so the order flow batches carrier calls into its
+ 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.
+
## Open Questions
None at this time.
diff --git a/docs/plans/6.0-service-workflows.md b/docs/plans/6.0-service-workflows.md
index 2f88f5eee9..c6dea5c8f2 100644
--- a/docs/plans/6.0-service-workflows.md
+++ b/docs/plans/6.0-service-workflows.md
@@ -321,8 +321,29 @@ The precedent is already shipped: the Order state machine is gone in 6.0
The narrow exception: a model whose status genuinely has no side effects at
all — a pure label with no restocking, no money, no fulfillment — may keep a
-machine if the transition graph is doing real validation work. In practice
-this has not come up.
+machine if the transition graph is doing real validation work.
+
+**Fulfillment is that exception, arrived at by subtraction (2026-08-10).** Its
+machine kept the status column, the transition graph and its guards, and the
+`publish_*_event` callbacks — publishing an event describes the status change
+rather than being a side effect of it. Everything else left: restocking and the
+carrier stand-down moved into `Fulfillments::Cancel`/`::Resume`, with the
+provider call an `external_step`. So an existing machine does not have to be
+removed wholesale to stop being dangerous; stripping it to the graph is enough,
+and it is the cheaper move when the guards are conditional. Removing the
+remaining machines outright is a separate planned wave. See decisions.md
+2026-08-10.
+
+**Composition constraint (2026-08-10):** a workflow whose flow contains an
+`external_step` cannot be called from inside another workflow's transaction —
+the guard raises `ContractError`, correctly. The fix is **a flag that defers the
+external half**, not pushing the shared behavior down onto the model:
+`Fulfillments::Cancel` takes `notify_provider:`, and `Orders::Cancel` passes
+false, delegating the database work and batching the carrier calls into its own
+`external_step` after commit. Moving the body to a public model method so both
+layers can call it was tried and rejected — it contradicts "workflows write
+behavior inline as named steps" and leaves model surface that has to be removed
+again later.
## Design Details
diff --git a/docs/plans/6.1-order-change-substrate.md b/docs/plans/6.1-order-change-substrate.md
index f55867ea31..a46bcc15da 100644
--- a/docs/plans/6.1-order-change-substrate.md
+++ b/docs/plans/6.1-order-change-substrate.md
@@ -4,7 +4,7 @@
**Target:** Spree 6.1
**Depends on:** 6.0-service-workflows.md (workflow tier), 6.0-returns-exchanges-claims.md (first consumer), 6.0-cart-order-split.md (Order is immutable-by-default after placement)
**Author:** Damian + Claude
-**Last updated:** 2026-08-02
+**Last updated:** 2026-08-10
## Summary
@@ -82,6 +82,30 @@ The concrete pain it solves for us:
reducing a return to "a view over a change set" would cost merchants the
first-class return entity `6.0-returns-exchanges-claims.md` exists to give
them.
+- **A change set belongs to one `Order`, never to an `OrderGroup`**
+ (RESOLVED 2026-08-10). Under multi-vendor a cart fans out into N child
+ orders under one group, and `6.0-multi-vendor-marketplace.md` (Decision 8) is
+ explicit that line items, fulfillments and totals live on the **children** —
+ the group holds only customer, payment and addresses. A change set mutates
+ exactly those child-owned rows, so it binds to the child order. Editing two
+ vendors' items is two change sets, which is also the correct commercial
+ answer: each vendor's balance settles against its own order. This keeps the
+ partial unique index on `(order_id)` as designed, with no group-level
+ variant. The cost is that a single admin edit spanning vendors is not one
+ atomic operation — accepted, because a cross-vendor atomic edit would need a
+ distributed settle across N gateway captures, which the group cannot offer
+ either.
+- **A pending change set does not hold stock** (RESOLVED 2026-08-10).
+ `6.0-stock-reservations.md` scopes reservations to *checkout* — held against
+ a cart, extended on checkout activity, expired by a background job. A
+ requested change set is an admin editing a placed order, which is neither a
+ cart nor time-boxed by customer activity, so reusing that machinery would
+ mean reservations with no natural expiry trigger. `add_item` therefore takes
+ stock at **confirm**, and confirm is where an out-of-stock action fails.
+ Accepted trade-off: a change set requested against the last unit can fail at
+ confirm if someone else buys it first. That is the same race the current
+ immediate-write path has, and the failure is visible and recoverable rather
+ than silent.
## Design Details
@@ -256,6 +280,28 @@ migrate, it is the simplest financially (add/remove/update items, re-settle the
difference), and it immediately replaces the current post-placement edit path
that writes rows directly and re-sums.
+**What it replaces (shipped in 6.0, 2026-08-10):** a dedicated admin order edit
+screen at `/orders/$orderId/edit` that manages line items — add, remove, change
+quantity — against a placed order. It writes immediately: each mutation hits the
+existing line-item endpoints and the order re-sums server-side, so the merchant
+sees the new totals only *after* committing. There is no preview, no pending
+change set and no persisted draft, because 6.0 cannot project totals without
+writing rows.
+
+That screen exists because merchants need post-placement line-item editing in
+6.0 and the fulfillment card is the wrong home for it (the card manages
+fulfillments; the edit screen manages what the order contains). Its money math
+goes through a value-object-returning service specifically so Phase 3 can
+re-point it at `OrderChanges::Preview` without touching callers, per the
+constraint below.
+
+Phase 3 keeps the screen and its route, and changes what sits behind it:
+`begin` on entry, an action per edit, `Preview` driving a live totals delta, and
+`confirm`/`cancel` on the footer buttons. The immediate-write path becomes the
+`confirm` of a single-action change set. Expect the UI diff to be additive —
+the delta display and the explicit save/discard footer are what 6.0 cannot
+offer.
+
### Phase 4 — returns, exchanges, claims adopt it
Each gains a nullable `order_change_id`. Their existing status flows stay
@@ -285,22 +331,29 @@ These apply during 6.0, before any of this is implemented:
- **New post-placement flows expose their money math through a service that
returns a value object**, so it can be re-pointed at `OrderChanges::Preview`
in 6.1 without changing callers.
+- **The 6.0 order edit screen writes immediately and shows no delta.** Do not
+ add a client-side pending-edit buffer to fake a preview — accumulating edits
+ in React state and submitting them together is a per-domain draft living in
+ the browser, and it would have to be unpicked for Phase 3. One interaction,
+ one request, totals re-read from the server.
+- **Post-placement line-item mutation belongs to the edit screen, not the
+ fulfillment card.** The card manages fulfillments (what ships, from where,
+ under which method); the edit screen manages what the order contains. Keeping
+ the two apart is what lets Phase 3 wrap the edit surface in a change set
+ without touching fulfillment UI.
## Open Questions
- **Does an OrderChange need to survive rejection?** Keeping declined change
sets is good audit but grows a hot table. Leaning toward keeping them with a
- retention rake task.
-- **Multi-vendor interaction.** When an order splits across vendors
- (`6.0-multi-vendor-marketplace.md`), does a change set span vendors or is
- there one per `OrderGroup` member? Needs resolving with that plan before
- Phase 3.
+ retention rake task. *Deferred:* costs nothing to decide at Phase 2 when the
+ schema lands, and the retention story is easier to size once we know how
+ often change sets are abandoned in practice.
- **Does `Preview` need caching?** The order-edit UI will call it on every
keystroke-ish interaction. Probably debounced client-side rather than cached
- server-side, but worth measuring.
-- **Stock reservation during a pending change.** An `add_item` action that sits
- in `requested` for an hour does not hold stock. Whether it should reuse
- `6.0-stock-reservations.md` is unresolved.
+ server-side, but worth measuring. *Deferred:* needs a real `Preview` to
+ measure. The 6.0 screen does not call it at all (no preview), so nothing is
+ blocked.
## References
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index cc601d0fb2..5139d8453d 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -1,3 +1,100 @@
+## 2026-08-10: Fulfillment side effects move to workflows; the state machine keeps the status column
+
+Answers "should Fulfillment follow Order and lose its state machine?" with
+**partly, deliberately**. The side effects move; the machine stays.
+
+`Fulfillment#after_cancel` restocked every unit **and** called
+`provider.cancel_fulfillment` — network I/O (an EasyPost label refund, a 3PL
+stand-down) running inside the save transaction that held the stock movements.
+That is precisely the failure `6.0-service-workflows.md` cites as the reason
+transition callbacks are the wrong place for side effects: a slow carrier holds
+row locks, and a failing one rolls back a restock that already happened at the
+warehouse.
+
+`Spree::Fulfillments::Cancel` and `::Resume` now own that work — restock and
+status inside one transaction, the provider call as an `external_step` after it
+commits. `Fulfillments::Fulfill` (added the same day for partial shipments)
+gained an explicit unstock for the `canceled -> fulfilled` path the resume
+callback used to cover; missing it would have shipped goods without taking them
+off the shelf.
+
+**What the machine keeps:** the status column, the transition graph and its
+guards, and the `publish_*_event` callbacks. Publishing an event *describes* the
+status change rather than being a side effect of it, so it belongs where the
+transition is. The graph is real validation work — the narrow exception
+`6.0-service-workflows.md` already allows.
+
+**Why not remove the machine outright.** Four other models still carry machines
+(Payment, InventoryUnit, ReturnAuthorization, GiftCard). Removing one at a time
+means re-litigating the same design in five separate rounds, and Fulfillment's
+`ready`/`resume` guards are conditional on `determine_state`, so replacing them
+is not mechanical. A full removal is a planned wave with its own document, not a
+refactor folded into fulfillment UI work. This also amends
+`6.0-fulfillment-and-delivery.md` resolved question 1, which had promised all
+transition hooks were preserved.
+
+**Composition constraint, and the wrong turn taken first.** `Orders::Cancel`
+and `Orders::Resume` cancel or resume every fulfillment from inside the order's
+own transaction, and a nested `external_step` raises `ContractError` by design.
+The first attempt worked around this by putting the restock bodies on the model
+as public `#restock_units`/`#unstock_units` and having both layers call them.
+That was wrong twice over: it violates the rule that workflows write behavior
+inline as named steps rather than delegating to model business methods, and it
+plants new public model surface that would have to be torn out again when the
+machine is eventually removed — the opposite of the direction the model is
+moving.
+
+The right shape: the stock movements are written inline in the workflow steps,
+and `Fulfillments::Cancel` takes a `notify_provider:` flag so a caller that
+already holds a transaction can suppress the external step and batch the
+carrier calls into its own. `Orders::Cancel` passes `notify_provider: false`
+and notifies after commit; `Orders::Resume` nests cleanly because Resume has no
+external step. **The general rule: when a workflow with an `external_step` must
+run inside another's transaction, give it a flag to defer the external half —
+do not push the shared behavior down onto the model.**
+
+## 2026-08-10: Order editing splits from fulfillment management; two OrderChange questions resolved
+
+The 6.0 admin order detail page grows a **separate edit screen** at
+`/orders/$orderId/edit` owning post-placement line-item mutation — add, remove,
+change quantity. The order detail page keeps fulfillment management (what ships,
+from where, under which delivery method); it no longer offers line-item editing.
+The split follows the reference layout and, more importantly, matches how
+`6.1-order-change-substrate.md` Phase 3 wants to wrap the edit surface in a
+change set without disturbing fulfillment UI.
+
+The 6.0 screen **writes immediately and shows no totals delta**. Projecting
+totals without writing rows is impossible before the OrderChange substrate
+lands, and the alternative — buffering edits in React state so the UI can fake a
+preview — is a per-domain draft living in the browser, which the substrate plan
+explicitly forbids. The money math still goes through a value-object-returning
+service so Phase 3 re-points it at `OrderChanges::Preview` without touching
+callers.
+
+Two of that plan's open questions are settled as a consequence:
+
+*A change set belongs to one `Order`, never to an `OrderGroup`.* Multi-vendor
+fans a cart into N child orders under one group, and the marketplace plan's
+Decision 8 keeps line items, fulfillments and totals on the children — the group
+holds only customer, payment and addresses. Change sets mutate child-owned rows,
+so they bind to the child. Cross-vendor edits are N change sets, which is also
+where the money belongs: each vendor settles against its own order.
+
+*A pending change set does not hold stock.* Stock reservations are scoped to
+checkout — held against a cart, extended by customer activity, expired by a job.
+An admin editing a placed order is neither, so reusing that machinery would
+create reservations with no expiry trigger. `add_item` takes stock at confirm,
+and confirm is where an out-of-stock action fails.
+
+Also settled for the backend: **partial fulfillment ships as a
+`Spree::Fulfillments::Fulfill` workflow**, not by extending the state machine.
+`Spree::Fulfillment` keeps its machine (preserved deliberately per
+`6.0-fulfillment-and-delivery.md` resolved question 1), but shipping a *subset*
+means splitting first, and split-then-ship inside an `after_transition` callback
+is exactly the shape `6.0-service-workflows.md` prohibits. The workflow wraps the
+machine as a low-level mechanic, mirroring how `Fulfillments::Create` already
+wraps `mark_shipped`.
+
## 2026-08-09: Metadata consolidated to one column — `public_metadata` dropped, `private_metadata` renamed
Implements the 2026-03-16 consolidation decision. All thirty metadata-carrying