Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(materialize): record what order 02 shipped and what it deliberately did not

nirholasab787479dc25
diff --git a/prompts/finish/materialize-02-quote-order-payments.md b/prompts/finish/materialize-02-quote-order-payments.md
deleted file mode 100644
index 9cf4e1d59..000000000
--- a/prompts/finish/materialize-02-quote-order-payments.md
+++ /dev/null
@@ -1,134 +0,0 @@
-# Work order 02: catalog, quotes, orders, and money (human + agent)
-
-**How to run:** paste this whole file into a fresh Claude Code chat in this
-repo, or name its path. Read `prompts/finish/materialize-00-CONTEXT.md` first; its
-decisions bind this order.
-
-**Binding operating clause:** finish 100%. Never end with a question or an
-unexecuted plan. CLAUDE.md hard rules apply: no mocks, no fake data, no
-unfinished markers, no em-dash, explicit-path commits. Two CLAUDE.md gates
-can appear in this order and only these: an irreversible on-chain send
-(none is required here; settle verification is read-only) and production
-deploys (owner-gated). Everything else, do.
-
-## Why this order exists
-
-This is where Materialize becomes commerce: a real catalog, a quote a buyer
-can trust, an order row with a state machine that cannot lie, and two
-checkout lanes. The second lane is the historic one: `POST
-/api/x402/print-order` is, to our knowledge, the first API where an AI
-agent pays to manufacture a physical object. Build it with the same care
-the market-data x402 endpoints got.
-
-## Step 0: re-derive current state
-
-```
-ls api/print/ data/print-catalog.json 2>/dev/null
-ls api/_lib/migrations/ | tail -15
-grep -rn "print" api/_lib/feed.js | head
-ls api/x402/ | grep -i print
-npm test -- tests/api/print 2>/dev/null | tail -5
-```
-
-Order 01 must have landed `/api/print/analyze` and `/api/print/prepare`
-(check, do not assume). Read before writing: one full x402 endpoint with
-dynamic pricing (`api/x402/forge.js` and one `api/x402/market-*.js`), the
-marketplace confirmed-purchase path (how `status='confirmed'` is written
-and why trials poisoned analytics, per STRUCTURE.md's marketplace row), and
-`api/_lib/forge-tiers.js` for the $THREE holder check.
-
-## Tasks
-
-### 1. Catalog (`data/print-catalog.json` + `GET /api/print/catalog`)
-
-Build the catalog per 00-CONTEXT's pricing model. Research current
-published market rates from real print services at execution time and cite
-sources + retrieval date in the file's `_sources` field. Every material
-carries: id, display name, class (resin, sls_nylon, full_color, fdm_draft,
-metal_quote_only), density g/cm3, rate per cm3, setup fee, min wall mm,
-min/max height mm, finish options with fees, lead-time days, margin
-fraction. Shipping zones: CN-domestic, US, EU, ROW with per-kg volumetric
-rates. The handler serves the catalog minus `_sources` and margin fields
-(public output is buyer-facing).
-
-### 2. Quote engine (`api/_lib/print/quote.js`, pure + tested)
-
-Input: printability report + material id + target height + quantity +
-destination country. Output: itemized lines (setup, material with the cm3
-it was computed from, finish, quantity break, $THREE holder discount when
-the session or payer wallet qualifies, shipping, total USDC), lead-time
-estimate, and a rejection with a named reason when the mesh violates the
-material's constraints (too thin walls for resin, too large for the bed).
-`POST /api/print/quote` wraps it and returns the itemization plus an
-HMAC-signed quote token (same signing helper the forge job tokens use)
-with a 24h expiry embedding every priced parameter, so checkout can never
-be replayed at a stale price or altered client-side.
-
-### 3. Schema + store (`api/_lib/print-store.js` + one migration)
-
-Create `print_orders`, `print_order_events`, `print_certificates` exactly
-per 00-CONTEXT. The store module owns the transition whitelist; write the
-state machine as data (a map of legal from/to pairs) with one `transition()`
-function that inserts the event row and publishes the `print` user
-notification in the same transaction. Extend `USER_EVENT_TYPES` in
-`api/_lib/feed.js` with `print`, wiring the bell copy the way `market`
-events did. Run `npm run db:status` before and after; `npm run db:migrate`
-applies immediately, so read what is pending first.
-
-### 4. Human checkout (`POST /api/print/orders`)
-
-Session + CSRF, mirroring an existing session-gated POST (the follow
-endpoint is the reference shape). Body: quote token + shipping fields
-(minimum PII per 00-CONTEXT). Flow: verify token, create `created` row,
-transition to `quoted`, take USDC on Solana through the platform's
-existing self-hosted settle rail (reuse the exact verification path the
-x402 lane uses; payment lands, transition to `paid`, then `screening`).
-`GET /api/print/orders/:id` returns the order + full event timeline to its
-owner. Payment verification is read-only chain work; no gate applies.
-
-### 5. Agent checkout (`POST /api/x402/print-order`)
-
-Dynamic-price 402 quoting the signed quote token's total, per-call
-settlement like the market-data endpoints. Body: quote token + shipping +
-payer wallet. Params rejected pre-settle (422) so a malformed order never
-charges. On settle: same store path as the human lane (user_id null,
-payer wallet recorded). Register it wherever x402 endpoints are cataloged
-(re-derive: grep how `market-pulse` reaches the service catalog and the
-discovery docs, and follow the same wiring).
-
-### 6. Tests
-
-Quote engine: itemization math from a fixture report, holder discount,
-quantity breaks, every constraint rejection, token expiry and tamper
-rejection. Store: every legal transition, every illegal transition throws,
-event rows land, notification published once. Handlers: auth, CSRF,
-pre-settle 422, and that a stale or altered quote token is refused. Follow
-`tests/api/` conventions; the marketplace analytics test shows how to
-fixture Postgres-backed stores here.
-
-## Definition of done
-
-- [ ] `npm test` green including new print quote/store/handler tests.
-- [ ] `npm run db:status` shows the migration applied; the three tables exist.
-- [ ] Dev-server flow proven end to end and pasted in the report: analyze a real creation, quote it, create an order with a real session, watch it reach `screening`, `GET` shows the timeline.
-- [ ] `POST /api/x402/print-order` returns a correct 402 challenge with the quote's exact amount for an unpaid call.
-- [ ] Quote totals rendered anywhere come only from the engine (grep proves no price math in `src/`).
-- [ ] `npm run check:rules -- --paths <files you touched>` passes.
-- [ ] Committed with explicit paths; this file deleted in the closing commit; PROGRESS.md appended.
-
-## Never blocked
-
-| Blocker | Resolution |
-|---|---|
-| How settle verification works | Read `api/x402/README.md` and one settled endpoint end to end. The rail is self-hosted Solana; everything needed is in-repo and in `.env`. |
-| Holder-check mechanics | `api/_lib/forge-tiers.js` already gates the forge High tier on $THREE holdings. Reuse its helper. |
-| A QA session for the dev-server flow | `AUDIT_EMAIL` / `AUDIT_PASSWORD` in `.env` are a real QA account. |
-| Real market pricing research | Public price pages of major print bureaus are indexable; capture numbers + dates in `_sources`. If a datum is unverifiable, price conservatively high and mark the field `estimate: true`. Owner tunes one file later. |
-| Migration ordering fear | `npm run db:status` first, always. It previews every pending migration; yours must be the only surprise. |
-| USDC-only feels narrow | Decided in 00-CONTEXT: Solana first, no card processor without owner approval. State it in UI copy, never apologize for it. |
-
-## Report format
-
-Files + tests + the pasted end-to-end dev flow transcript, the catalog's
-source citations, any 00-CONTEXT deviation (one line + why), and the single
-next action for orders 03/04/05.
diff --git a/prompts/finish/materialize-PROGRESS.md b/prompts/finish/materialize-PROGRESS.md
index 96f6a3b91..a1d7ba874 100644
--- a/prompts/finish/materialize-PROGRESS.md
+++ b/prompts/finish/materialize-PROGRESS.md
@@ -13,3 +13,48 @@ what was verified (commands/evidence), owner items surfaced. Never record
inbound partnership offer from a Chinese high-precision print operator;
campaign deliberately does not block on any partner. No product code
exists yet; order 01 is the first build session.
+
+- 2026-09-02, order 02 (quote, orders, money): checkout is wired on both
+ lanes. NOTE FOR THE NEXT SESSION: this order was run by two sessions at
+ once. A concurrent session landed the catalog (`data/print-catalog.json`,
+ 4 cited sources), the quote engine (`api/_lib/print/quote.js`: pricing,
+ constraint rejections with fixes, alternatives, hollowing, HMAC quote
+ tokens) and the free `GET /api/print/catalog` + `POST /api/print/quote`
+ handlers. This session built the money half on top of it rather than a
+ second copy of the same thing.
+ Shipped here: `api/print/orders.js` (session + CSRF, opens an order from a
+ verified token and returns a Solana Pay intent, gasless when the buyer's
+ wallet is connected), `api/print/orders/[id].js`,
+ `api/print/orders/[id]/confirm.js` (findReference + validateTransfer, a
+ chain READ, then paid -> screening), `api/x402/print-order.js` (the agent
+ lane: every refusal pre-settle, the 402 quotes the token's own total, the
+ post-settlement hook promotes the order), `createOrder` /
+ `normalizeShipping` / `listOrdersForUser` in `api/_lib/print-store.js`,
+ migration `20260902214500_print_order_payment.sql` (payment reference,
+ signature, quote expiry, unique indexes so one transaction cannot settle
+ two orders), `print_update` wired through notify-prefs and the bell,
+ `printOrderIp` rate bucket, ring-catalog + service-catalog registration,
+ tests `tests/print-checkout-store.test.js` and
+ `tests/api/print-checkout-endpoints.test.js`.
+ Two real defects found and fixed while proving it: the edition gate 500'd
+ every direct-GLB order (no creation id means no series to be sold out of),
+ and `paidEndpoint` advertised a FIXED $THREE amount beside a per-request
+ USDC price, so a 39.13 USDC print and a 12 USDC one both offered the same
+ flat token price. `acceptThree: false` now opts print-order and knock out.
+ Also cataloged knock, which had been failing the ring parity test.
+ Verified: local `server/index.mjs` against the production database, real
+ QA session, real GLB. Catalog -> analyze (score 100) -> quote (39.13 USDC,
+ itemized) -> order 201 with a Solana Pay intent -> GET shows the timeline
+ and never the street address -> confirm with no payment answers 202
+ pending -> the store leg reaches `screening` and refuses
+ `screening -> delivered`. The 402 for that order quotes exactly 39130000
+ atomics of USDC and nothing else.
+ NOT verified, and deliberately: no USDC was ever sent. Taking real money
+ is CLAUDE.md gate 1, so the `paid` transition in the transcript was driven
+ through the store with a note saying so, and that QA order was closed out
+ as `rejected` rather than left in the operator queue. The chain-read half
+ is proven by the 202 and by the payment_mismatch unit test.
+ Owner items: `data/print-catalog.json` rates and shipping zones are the
+ one file to tune against a real bureau quote and a real carrier account.
+ Next: order 03 (the /materialize surface) can consume
+ `POST /api/print/orders` and its `payment` block as-is.