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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Record the fulfillment and order-edit decisions
Damian Legawieccd8538c70679
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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.mdindex 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 migr10. **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 QuestionsNone at this time.diff --git a/docs/plans/6.0-service-workflows.md b/docs/plans/6.0-service-workflows.mdindex 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.0The narrow exception: a model whose status genuinely has no side effects atall — 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 Detailsdiff --git a/docs/plans/6.1-order-change-substrate.md b/docs/plans/6.1-order-change-substrate.mdindex 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 thefirst-class return entity `6.0-returns-exchanges-claims.md` exists to givethem.+- **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 thedifference), and it immediately replaces the current post-placement edit paththat 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 itEach 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 thatreturns 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 changesets 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 everykeystroke-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.## Referencesdiff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 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` renamedImplements the 2026-03-16 consolidation decision. All thirty metadata-carrying