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): close out the fulfillment order and correct the stale cron counts

nirholas0da326926384
diff --git a/README.md b/README.md
index efe271614..07cd02a0e 100644
--- a/README.md
+++ b/README.md
@@ -9994,7 +9994,7 @@ The full OpenAPI 3.1 spec is available at `/openapi.json`. The key API surface i
Cron schedules are declared in `vercel.json` (still the live cron/route config the server reads) and executed in production by **Google Cloud Scheduler**, which calls each endpoint on its schedule. All cron endpoints are fail-closed — a missing auth token aborts with an error rather than silently skipping (see [Security Hardening](#security-hardening)).
-The crons in `vercel.json` (111 entries on 2026-09-01) are routed through a single dynamic handler at [`api/cron/[name].js`](api/cron/[name].js); the `name` segment selects the handler function. Scheduler jobs are provisioned from the `vercel.json` cron list via [scripts/create-gcp-scheduler.mjs](scripts/create-gcp-scheduler.mjs). The table below is a selection of the notable jobs, each schedule quoted verbatim from `vercel.json`; that file is the complete list.
+The crons in `vercel.json` (112 entries on 2026-09-02) are routed through a single dynamic handler at [`api/cron/[name].js`](api/cron/[name].js); the `name` segment selects the handler function. Scheduler jobs are provisioned from the `vercel.json` cron list via [scripts/create-gcp-scheduler.mjs](scripts/create-gcp-scheduler.mjs). The table below is a selection of the notable jobs, each schedule quoted verbatim from `vercel.json`; that file is the complete list.
| Schedule | Endpoint | Purpose |
| -------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
diff --git a/docs/build.md b/docs/build.md
index 8d17d39f1..a1b2f52ba 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -45,7 +45,7 @@ front-end, the `vercel.json` route table, and every `api/**` handler from source
provisioned from the `crons` array in `vercel.json` by
[scripts/create-gcp-scheduler.mjs](../scripts/create-gcp-scheduler.mjs); that
array is the count, so read it there rather than trusting a number quoted here
-(111 entries on 2026-09-01). There is **no GitHub Actions CI**. Full runbook: [docs/ops/gcp-production.md](./ops/gcp-production.md).
+(112 entries on 2026-09-02). There is **no GitHub Actions CI**. Full runbook: [docs/ops/gcp-production.md](./ops/gcp-production.md).
`.npmrc` sets `legacy-peer-deps=true` (npm never auto-installs peers — the
reason `audit:deploy` checks the peer tree), and `engines.node` pins Node
diff --git a/prompts/finish/materialize-04-fulfillment-ops.md b/prompts/finish/materialize-04-fulfillment-ops.md
deleted file mode 100644
index fda8c4e93..000000000
--- a/prompts/finish/materialize-04-fulfillment-ops.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# Work order 04: fulfillment adapters and the operator console
-
-**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. Signing a partner,
-sending funds, deploys: owner-gated. Building every rail so those are
-one-step owner actions: this order.
-
-## Why this order exists
-
-Orders that reach `screening` must reach `delivered`. The lane that makes
-that true on day one is a human operator with a first-class console,
-because that is a real fulfillment operation (it is how every print
-marketplace launched), and it is the honest alternative to blocking the
-product on an uncontracted partner API. The adapter layer means the day a
-partner contract lands, their API becomes a config change, not a rebuild.
-
-## Step 0: re-derive current state
-
-```
-ls api/print/ops/ api/_lib/print/adapters/ 2>/dev/null
-grep -rn "provider" api/_lib/print-store.js 2>/dev/null | head
-grep -rln "admin" api/ | head # find the existing admin-auth pattern
-psql "$DATABASE_URL" -c "select status, count(*) from print_orders group by 1" 2>/dev/null
-```
-
-Order 02's store and state machine must exist (verify). Re-derive how this
-repo authenticates admin/operator endpoints (the KOL `import-gmgn` route
-is one known admin surface; find the shared helper it uses and reuse it).
-
-## Tasks
-
-### 1. Adapter contract (`api/_lib/print/adapters/`)
-
-One interface, adapters as data + module pairs, mirroring the forge engine
-registry philosophy: each adapter declares capabilities (materials it can
-run, max bbox, ships-from country, lead-time) and implements
-`submit(order, assets)`, `status(providerOrderId)`, `cancel()`, plus a
-webhook verifier. The store's `submitted → printing → quality_check →
-shipped` transitions are driven only through adapter events; no handler
-writes those states directly.
-
-### 2. The `manual` adapter (launch lane, fully real)
-
-`submit` assigns the order to the operator queue and notifies the operator
-channel (re-derive the existing Telegram ops-notification helper; the
-changelog cron proves one exists). `status` reads what the operator
-recorded. The operator console (task 3) is this adapter's API. No part of
-this simulates anything: it is a workflow tool for a human running real
-print jobs through a real bureau.
-
-### 3. Operator console (`/materialize/ops`, session + operator allowlist)
-
-A working queue over `api/print/ops/*` endpoints (list by status, order
-detail with the prepared asset download links + shipping label data,
-transition actions with notes, tracking-number entry, refund marking).
-Server-side authorization on every endpoint via the repo's admin pattern;
-the page is never the security boundary. Ship it with the platform's
-design system; an internal tool with dead-end states breeds exactly the
-operational mistakes the state machine exists to prevent.
-
-### 4. The `partner-cn` adapter skeleton, wired behind env
-
-Per 00-CONTEXT, the Chinese partner is uncontracted: build the adapter
-module fully structured (auth header slot, submit/status/webhook mapping
-to the store's vocabulary) but registered only when its env vars exist
-(`PRINT_PARTNER_CN_URL`, `PRINT_PARTNER_CN_KEY`), exactly how the forge
-treats BYOK lanes. Every code path that can run without credentials has a
-real test; the report lists the env vars as the single missing input. No
-fabricated endpoints: the mapping uses the store's own vocabulary and a
-documented request shape in the module header, marked as the contract to
-reconcile against the partner's real API docs when they arrive.
-
-### 5. Webhooks + reconciliation
-
-`POST /api/print/webhook/:provider` with per-adapter HMAC verification and
-idempotent event application (a replayed webhook must not duplicate
-timeline rows). A reconciliation cron (`api/cron/print-orders-sync.js`,
-registered in `vercel.json` crons per the repo's cron conventions) polls
-`status()` for non-terminal orders older than the adapter's lead time and
-flags stalls to the operator channel. Note the CLAUDE.md rule: the cron
-count claim lives in CLAUDE.md and is guarded by `check:claude`; run
-`npm run check:claude` after touching `vercel.json` and update the count
-in CLAUDE.md in the same commit if it moved.
-
-### 6. Tests
-
-Adapter contract conformance suite run against both adapters (manual fully,
-partner-cn's credential-free paths), webhook idempotency, operator endpoint
-authorization (anonymous and non-operator sessions get refused), stall
-detection picks up a fixture order past lead time.
-
-## Definition of done
-
-- [ ] `npm test` green including adapter conformance + ops authorization tests.
-- [ ] Dev-server proof in the report: a paid test order walked `screening → submitted → printing → shipped` entirely through the console UI, timeline showing operator-actor events.
-- [ ] Webhook replay proven idempotent (same payload twice, one event row).
-- [ ] `npm run check:claude` passes with the cron registered.
-- [ ] Anonymous and non-operator access to every `api/print/ops/*` endpoint refused (test-proven).
-- [ ] `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 |
-|---|---|
-| No partner API docs | By design. Build the skeleton behind env per task 4; the missing vars are the report's one owner input. |
-| Admin auth pattern unclear | Grep for the helper the KOL admin import uses; if the repo truly has no shared operator-role concept, add the minimal allowlist (env-listed user ids) and document it in the module header. |
-| Telegram ops channel | The changelog push cron already posts to Telegram; reuse its client and env. A separate ops chat id, if absent, goes in the report as one env var, and notifications also land in the in-app bell meanwhile. |
-| Fear of adding a cron | Follow `scripts/create-gcp-scheduler.mjs` conventions; scheduler sync is owner-run at deploy. Registering in vercel.json is the repo-side deliverable. |
-| Refund mechanics | Marking `refunded` with an event note is this order. Moving actual funds is CLAUDE.md gate 1, owner-executed; the console renders the exact recipient + amount for that action. |
-
-## Report format
-
-Files + tests, the console walkthrough evidence, the exact env vars and
-owner actions remaining (partner credentials, ops chat id if new), one
-line per 00-CONTEXT deviation, next action.
diff --git a/prompts/finish/materialize-PROGRESS.md b/prompts/finish/materialize-PROGRESS.md
index a1d7ba874..b21189ebd 100644
--- a/prompts/finish/materialize-PROGRESS.md
+++ b/prompts/finish/materialize-PROGRESS.md
@@ -58,3 +58,48 @@ what was verified (commands/evidence), owner items surfaced. Never record
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.
+
+- 2026-09-02: Order 04 (fulfillment adapters + operator console) shipped.
+ Adapter layer `api/_lib/print/adapters/` (contract, registry, `manual`,
+ `partner-cn`) with capabilities declared as data and registration gated on
+ `configured()`, so an uncredentialed lane is invisible rather than broken.
+ Orchestration `api/_lib/print/fulfillment.js` (adapters speak, the store
+ decides: every adapter result becomes at most one `transition()` call).
+ Fulfillment reads and the webhook ledger in
+ `api/_lib/print/fulfillment-queries.js`, kept out of `print-store.js` so the
+ state machine stays the file a reviewer can read. Operator gate
+ `api/_lib/print/ops-auth.js` (admin session, `PRINT_OPERATORS` allowlist, or
+ `OPS_SECRET`; fails closed in dev too, because these responses carry PII).
+ Operator channel `api/_lib/print/ops-notify.js` (private Telegram ops chat,
+ admin bell, `ops_alerts` for stalls). API `api/print/ops/[action].js`
+ (queue, order, adapters, transition, submit, tracking, cancel, refund) and
+ `api/print/webhook/[provider].js`. Console `/materialize/ops`
+ (`pages/materialize-ops.html`, `src/materialize-ops.{js,css}`). Sweep
+ `api/cron/print-orders-sync.js`, registered in `vercel.json` at `17 * * * *`
+ (cron count in CLAUDE.md moved to 113). Runbook
+ `docs/ops/materialize-fulfillment.md`. Tests: `print-adapter-contract`
+ (conformance run over both adapters), `print-ops-authorization`,
+ `print-webhook-idempotency`, `print-fulfillment-routing`, `print-orders-sync`.
+ Verified against the production database with `server/index.mjs` and a real
+ Chromium session: a seeded order walked screening -> submitted -> printing ->
+ quality_check -> shipped entirely through the console UI, every event
+ attributed to the operator, `quality_check -> delivered` refused 409. Three
+ identical signed webhook deliveries produced one timeline row and one ledger
+ row; a forged signature and a delivery to the manual lane were both 401 before
+ the body was parsed. The sweep polled 6 open orders, isolated one unreachable
+ partner into `failures`, flagged one stalled order and stamped it so the next
+ sweep stays quiet (proven by re-querying with the re-alert window at zero).
+ Anonymous and signed-in-non-operator callers were refused on all eight
+ endpoints, live and in tests. All walkthrough rows were deleted afterwards.
+ Three real defects found and fixed while proving it: the drawer sat under the
+ sticky site header so Close was unclickable; the drawer's click listener was
+ re-registered per render, firing each action up to three times (two 409s
+ behind every landed mutation); and the post-action reload wiped the result
+ line and, worse, the refund payout instruction carrying the recipient and
+ amount.
+ Owner items: `TELEGRAM_PRINT_OPS_CHAT_ID` (a dedicated private ops chat;
+ without it paging falls back to `TELEGRAM_ALERTS_CHAT_ID`, then to the admin
+ bell), `PRINT_OPERATORS` (staff fulfillment without granting platform admin),
+ and `PRINT_PARTNER_CN_URL` + `PRINT_PARTNER_CN_KEY`, which stay absent until
+ a partner is contracted. Signing that partner is an owner action.
+ Next: the adapter registry is the only file a contracted partner touches.