rose-ash/plans/commerce-on-sx.md

commerce-on-sx: Catalog, cart, pricing & orders on miniKanren

DRAFT outline. The revenue vertical. Depends on persist-on-sx (durable orders) and flow-on-sx (checkout as a durable flow). Don't start before persist-on-sx Phase 1 is green.

rose-ash's revenue engine — market (catalog), cart (checkout), orders (SumUp payment, reconciliation) — has no SX subsystem. The hard part of commerce isn't CRUD; it's pricing: discounts, bundles, tax, membership rates, promotions that stack (or don't). These are relations, and a relational engine can run them in multiple directions — forward ("what's the total?") and backward ("what promo code yields this total?", "which line item triggered the discount?").

That's a miniKanren fit. Pricing/promotion rules are relational; cart and order lifecycle (reserve → pay → fulfil → reconcile) is a durable flow; the order ledger is a persist stream. Commerce is the first real composition subsystem.

End-state: a catalog model, a relational pricing/promotion engine, a cart with deterministic totals, and an order lifecycle flow with payment-webhook reconciliation — all auditable via the event log.

Status (rolling)

bash lib/commerce/conformance.sh → 132/132 (8 suites: catalog, cart, price, api, promo, stack, quote, ledger) — Phases 1-2 done; Phase 3 ledger done

Ground rules

• Scope: only lib/commerce/** and plans/commerce-on-sx.md. May import from lib/minikanren/, and (once they exist) lib/persist/ + lib/flow/. Do not edit substrates.
• Architecture: prices/promotions are miniKanren relations over catalog facts; a cart total is a deterministic query result (first solution under a fixed rule order). Order lifecycle is a flow that suspends at the payment IO boundary. Money is integer minor units — never floats.
• Determinism: promotion stacking must have explicit, tested precedence; totals must be reproducible from the cart + catalog snapshot.
• Commits: one feature per commit. Progress log + tick boxes.

Architecture sketch

Catalog + cart                          Total / order
  product(id,price,tags)                  {:subtotal :discounts :tax :total}
        │                                       ▲
        ▼                                       │
lib/commerce/catalog.sx                 lib/commerce/price.sx
  — product / variant / stock facts       — miniKanren pricing relations
        │                                  — promo stacking, membership rates
        ▼                                       ▲
lib/commerce/cart.sx                    lib/commerce/order.sx  (flow + store)
  — line items, quantities                — reserve→pay→fulfil→reconcile
        │                                  — SumUp webhook = flow resume
        ▼                                       │
lib/commerce/api.sx ── (commerce/add) (commerce/total) (commerce/checkout) ──┘

Phase 1 — Catalog + cart + deterministic totals

• catalog.sx — product/variant/stock as facts
• cart.sx — line items, add/remove/qty
• price.sx — base pricing relation, subtotal; tax
• api.sx + tests + scoreboard + conformance.sh

Phase 2 — Promotions (relational)

• promo rules: percentage, fixed, bundle, member rate
• explicit stacking precedence; "best price" backward query
• tests: stacking order, mutually-exclusive promos, member vs guest

Phase 3 — Order lifecycle (flow + store)

• order flow: reserve stock → await payment → fulfil
• payment webhook resumes the suspended flow
• order ledger as a persist stream; idempotent reconciliation

Phase 4 — Reconciliation + federation

• mismatch detection (paid≠ordered) as queries over the ledger
• cross-instance catalog (federated marketplace) — out-of-scope stub
• tests: webhook replay, partial refund, double-charge guard

Progress log

• 2026-06-07 — ledger.sx (Phase 3 piece, checkbox 3): order ledger as a persist event stream "order/". Status/total/paid/recon are projections (folds) over events — ledger is the single source of truth. order-pay/ order-refund are idempotent via persist/append-once keyed on the payment ref, so a replayed SumUp webhook records once (no double-charge). order-recon-of classifies :unpaid/:ok/:underpaid/:overpaid on net (paid−refunded) vs total; ledger-mismatches finds genuine paid≠ordered across all streams. Verified minikanren+scheme/flow+persist all coexist in one sx_server process. ledger suite 20/20; total 132/132. Next: order flow (reserve→pay→fulfil) as a Scheme flow-on-sx flow with webhook resume (checkboxes 1-2) — needs SX↔Scheme quote marshalling.
• 2026-06-07 — quote.sx (pricing capstone, bridges Phase 2→3): cart-quote composes price+promo+stacking into the deterministic priced quote {:subtotal :discount :tax :total :codes} with `total = subtotal - discount
  • tax`. Explicit tax policy: tax on GROSS per-line amounts (discount reduces payable, not tax base) — documented for the determinism contract. This quote is the value the Phase-3 order flow will carry. quote suite 13/13; total 112/112.
• 2026-06-07 — stack.sx (Phase 2 complete): stacking precedence as a separate selection layer (precedence NOT in the rules, per the miniKanren design rule). Exclusivity = unordered code pairs; valid-stackings enumerates every legal subset of applicable promos (powerset ∖ excluded combos); best-stacking is the deterministic max-total-discount selection (stable on ties). stacking-by-totalo is the best-price backward query ("which legal stacking yields total D?"). Member vs guest falls out of applicable-promos. stack suite 16/16; total 99/99.
• 2026-06-07 — promo.sx (Phase 2 piece 1): four promo types as tagged tuples (:percent code class bps)/(:fixed code threshold amount)/(:bundle code sku n)/(:member code class bps). Per-promo discount is pure integer arithmetic; promo-discounto/promo-applieso enumerate (code, amount) relationally — forward ("which apply?") and backward ("which code yields 2000?" → run* over applieso). applicable-promos/promo-amount-for deterministic helpers. promo amounts via project to ground the membero-bound promo. promo suite 17/17; total 83/83. Next: stacking precedence + best-price (stack.sx).
• 2026-06-06 — api.sx (Phase 1 complete): session facade {:ctx :cart} with commerce-add/-remove/-set-qty/-total/-count/ -lines, commerce-can-add? catalog validation, commerce-explain per-line audit breakdown ({:sku :variant :qty :unit :extended :tax}), and a commerce-checkout Phase-3 stub. api suite 12/12; total 66/66.
• 2026-06-06 — price.sx: deterministic cart-subtotal (Σ unit×qty, variant delta defaults 0) + jurisdiction-relational tax. taxo facts indexed by (jurisdiction, product-class, customer-class)→bps, queried multidirectionally; apply-bps rounds half-up with integer arithmetic only. cart-total returns {:subtotal :discounts :tax :total} (discounts 0 until Phase 2), reproducible from (context, cart). = does structural dict equality (order-independent), so total dicts compare directly. price suite 20/20; total 54/54.
• 2026-06-06 — cart.sx: cart as an ordered list of (sku variant qty) lines. Pure ops cart-add (merges same line / appends), cart-set-qty (0 removes), cart-remove, plus cart-qty/cart-count/cart-skus/cart-empty?. cart-lineo is the relational view (membero over the cart) — forward and backward. cart suite 18/18; total 34/34.
• 2026-06-06 — catalog.sx: catalog snapshot (products/variants/stock as fact tuples) + multidirectional accessor relations (producto/varianto/stocko, derived priceo/classo/unit-priceo) + deterministic catalog-price/ -class/-has? helpers. conformance.sh harness + scoreboard. catalog suite 16/16. Gotcha: minikanren run-n macro binds s internally — query vars must avoid s; tests compare reified results with = (not equal?, which fails on reified lists). Money = integer minor units throughout.

Blockers

(none)