tests and mutation docs

pkg/cart/MUTATIONS.md

@@ -0,0 +1,89 @@
+# `pkg/cart` — mutation inventory
+
+Every mutation file under `pkg/cart/mutation_*.go` plus the slice of cart
+state it touches. The grouping is **subjective** ("Subscription lifecycle",
+"Discount surface", etc.) — used as a starting point for collapsing the
+file-per-mutation pattern flagged in `agents.md`. Move two related
+mutations into one file first; if the test surface stays smaller than the
+two-file version, the grouping is real.
+
+| File                                                | Concern              | State it READS                | State it WRITES                          |
+| --------------------------------------------------- | -------------------- | ----------------------------- | ---------------------------------------- |
+| `mutation_items.go` (`mutation_add_item.go` and `mutation_remove_item.go` merged; tests stay in `mutation_add_item_test.go` + `mutation_remove_item_test.go`) | Line item add/remove  | `state.Items`                   | `state.Items`, `state.UpdatedAt`         |
+| `mutation_change_quantity.go`                       | Line item quantity   | `state.Items[idx]`             | `state.Items[idx]`, `state.UpdatedAt`    |
+| `mutation_clear_cart.go`                            | Wholesale clear      | —                             | `state.Items`, `state.Vouchers`, `state.UpdatedAt` |
+| `mutation_set_user_id.go`                           | Ownership            | —                             | `state.UserID`, `state.UpdatedAt`        |
+| `mutation_set_cart_type.go` (+ test)                | Cart type            | —                             | `state.Type`, `state.UpdatedAt`          |
+| `mutation_add_voucher.go`                           | Discount surface     | `state.Vouchers`              | `state.Vouchers`, `state.LineTotals` (re-eval), `state.UpdatedAt` |
+| `mutation_set_custom_fields.go` (+ tests)           | Custom K/V           | `state.CustomFields`          | `state.CustomFields`, `state.UpdatedAt`  |
+| `mutation_set_recovery_contact.go` (+ tests)        | Recovery             | —                             | `state.Recovery`, `state.UpdatedAt`      |
+| `mutation_subscription_added.go`                    | Subscription         | `state.Items`                 | `state.Subscriptions`, `state.UpdatedAt` |
+| `mutation_upsert_subscriptiondetails.go`            | Subscription details | `state.Subscriptions`         | `state.Subscriptions`, `state.UpdatedAt` |
+| `mutation_remove_line_item_marking.go`              | Markings             | `state.Items[idx].Markings`   | `state.Items[idx].Markings`, `state.UpdatedAt` |
+| `mutation_line_item_marking.go`                     | Markings apply       | `state.Items[idx].Markings`   | `state.Items[idx].Markings`, `state.UpdatedAt` |
+
+## Delete-test quick check
+
+For any proposed grouping (e.g. merge all `marking*` mutations into one
+file), ask: does deleting the merged file concentrate complexity, or just
+move lines? For markings — yes, the shared logic (cascade to pricing) makes
+the merge worthwhile. For `voucher` vs `custom_fields` — no, those read
+different state and have different error contracts; keep separate.
+
+### What is already merged
+
+`pkg/cart/mutation_items.go` (added 2025-07) — AddItem and RemoveItem
+both touch `state.Items` and share the `ErrPaymentInProgress`,
+`decodeExtra`, and `getOrgPrice` helpers. Merge passed the delete-test
+checks: the receiver `*CartMutationContext`, same grain (`*CartGrain`),
+same mutation-registry dispatch. Both `mutation_*_test.go` files remain
+because they assert specific method behaviour, not generic package
+behaviour. Verified: `go test -count=1 ./pkg/cart/...` clean (voucher test
+which references `ErrPaymentInProgress` still green).
+
+#### Table corrections when merging
+
+When the two source rows collapsed into one, two corrections landed in
+the merge:
+
+  - AddItem's old READS column listed `state.Vouchers (for stacking)`.
+    That clause was **incorrect** — voucher stacking is `AddVoucher`'s
+    concern, not AddItem's. The merge drops the clause because reading
+    `mutation_add_item.go` confirms AddItem only reads `state.Items`.
+    This is a documentation correction, not a behaviour change.
+  - Both `State it READS / WRITES` columns originally had `(both)`
+    annotations to remind that two distinct mutations were sharing the
+    row. After collapse the row already says `Line item add/remove`, so
+    the `(both)` markers are noise — dropped.
+
+If a future merge lands, follow the same pattern: read the actual source
+to verify the row's claimed state surface, and prune label-noise before
+compressing two rows into one.
+
+### NOT to merge next
+
+`mutation_change_quantity.go` looks like an obvious candidate for the next
+merge (same receiver, same grain, same `state.Items` write surface). It
+is **not** — quantity has a partial-line-drop arithmetic contract that
+add/remove do not:
+
+  - `AddItem` always merges or appends; never sets quantity down.
+  - `RemoveItem` always removes whole lines; never decrements quantity.
+  - `ChangeQuantity` may drop a line entirely if quantity reaches 0.
+
+If you merge `ChangeQuantity` first, doing the same delete-test check
+yields: deleting the merged file leaves the partial-line arithmetic
+logic stranded in `Apply`, which IS a real concentration (good). But
+the inverse: if `AddItem` later grows a "decrement" edge case, the
+merged file will balloon and a re-split becomes expensive. Either
+keep `ChangeQuantity` separate, OR merge all three with the merge
+scoped to a "line item lifecycle" package and the partial-line
+arithmetic under a clearly-named helper.
+
+## How this maps onto a refactor
+
+1. Pick a row with shared logic (markings, subscription details).
+2. Move related mutations + their tests into one file under
+   `pkg/cart/<concern>.go`.
+3. Re-run `go test ./pkg/cart/...` — same assertions, smaller surface.
+4. Update this table to reflect the new file layout.