giles
79fa28e55d
Some checks failed
Test, Build, and Deploy / test-build-deploy (push) Failing after 57s
promo.sx — four promo types as tagged tuples; per-promo discount is pure
integer arithmetic, but enumeration is relational: promo-discounto and
promo-applieso run forward ("which codes apply, for how much?") and backward
("which code yields this discount?"). project grounds the membero-bound promo.
applicable-promos / promo-amount-for deterministic helpers. Total 83/83.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
114 lines
6.3 KiB
Markdown
114 lines
6.3 KiB
Markdown
# 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` → **83/83** (5 suites: catalog, cart, price, api, promo) — Phase 1 done, Phase 2 in progress
|
||
|
||
## 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
|
||
- [x] `catalog.sx` — product/variant/stock as facts
|
||
- [x] `cart.sx` — line items, add/remove/qty
|
||
- [x] `price.sx` — base pricing relation, subtotal; tax
|
||
- [x] `api.sx` + tests + scoreboard + conformance.sh
|
||
|
||
## Phase 2 — Promotions (relational)
|
||
- [x] 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 — `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)
|