commerce: record Phase 3 flow-integration design + gotchas for next iteration

Settled design for order flow (checkboxes 1-2): Scheme flow carries only the
order-id, SX driver does all ledger IO. Key gotcha captured: never return
flow-make-env from eval (serializer hangs on the cyclic env); run the flow
suite single-process like flow's own conformance with a long timeout.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

plans/commerce-on-sx.md

@@ -135,5 +135,33 @@ lib/commerce/api.sx ── (commerce/add) (commerce/total) (commerce/checkout)
   avoid `s`; tests compare reified results with `=` (not `equal?`, which fails on
   reified lists). Money = integer minor units throughout.
 
+## Phase 3 flow-integration notes (for the next iteration)
+
+Order flow = checkboxes 1-2 (reserve→pay→fulfil as a flow-on-sx flow + webhook
+resume). Design is settled; the remaining work is mechanical but slow to iterate.
+
+- **flow is the Scheme-on-SX guest layer**, not the SX/minikanren host. Load
+  order: `lib/guest/{lex,reflective/env,reflective/quoting}` + `lib/scheme/{parser,
+  eval,runtime}` + `lib/flow/{spec,store,remote,host,api}`. Confirmed it coexists
+  with the minikanren + persist stacks in one sx_server process.
+- **Driver API (SX side):** `(flow-make-env)` builds the env once; `(flow-run-in
+  env "<scheme-src>")` evaluates a Scheme program string. Flows/driving are all
+  Scheme: `(flow/start flow input)`, `(flow/resume id val)`, `(flow/pending)`,
+  `(flow/status id)`, `(flow/result id)`. Host ABI (host.sx): `(request kind
+  payload)` suspends with a typed envelope; `(flow-host-requests)` lists pending.
+- **Settled design:** the Scheme flow carries ONLY the order-id (a string) and is
+  pure orchestration: `(defflow ordf (lambda (oid) (begin (request 'reserve oid)
+  (request 'payment oid) (request 'fulfil oid))))`. All IO/ledger work stays in
+  SX — the SX driver services each request by appending to the persist ledger
+  (ledger.sx) and resuming with a marker. Payment stays suspended until the
+  webhook calls flow/resume. Marshalling is trivial (just strings).
+- **GOTCHA (cost me a turn):** `flow-make-env` returns a large/likely-cyclic env
+  object; returning it from `(eval "...")` makes the harness serializer hang (got
+  exit 0 with NO epoch-2 output). NEVER return the env — wrap as `(begin (define
+  env (flow-make-env)) :ok)`. Structure the flow suite like `lib/flow/conformance.sh`:
+  load once, build env once, run all assertions in ONE process returning small
+  count values. Budget a long timeout (flow's own suite uses 540s); env build is
+  ~150s CPU and balloons under sibling-agent CPU contention.
+
 ## Blockers
 (none)