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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(materialize): close out the fulfillment order and correct the stale cron counts
nirholas0da326926384
diff --git a/README.md b/README.mdindex 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 iCron 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.mdindex 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 sourceprovisioned from the `crons` array in `vercel.json` by[scripts/create-gcp-scheduler.mjs](../scripts/create-gcp-scheduler.mjs); thatarray 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 — thereason `audit:deploy` checks the peer tree), and `engines.node` pins Nodediff --git a/prompts/finish/materialize-04-fulfillment-ops.md b/prompts/finish/materialize-04-fulfillment-ops.mddeleted file mode 100644index 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.mdindex 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 recordone 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.