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
chore(prompts): retire order 437, CDN image placeholder fallback shipped
nirholasbd174170653e
diff --git a/prompts/finish/437-auto-cdn-image-placeholder-fallback.md b/prompts/finish/437-auto-cdn-image-placeholder-fallback.mddeleted file mode 100644index 45f9815ff..000000000--- a/prompts/finish/437-auto-cdn-image-placeholder-fallback.md+++ /dev/null@@ -1,118 +0,0 @@-# 437. Stop serving a raw JSON 502 for images when both object-storage lanes are down--How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now, no gate, no owner action required.--## Operating clause (binding)--- Read CLAUDE.md first. CLAUDE.md overrides everything, including this file.-- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan.-- This is a bug fix: follow the test-first rule (CLAUDE.md, "Bug fixes are test-first"). Write the failing test first, confirm it fails for the stated reason, then fix the code, then confirm it passes. Commit the test with the fix.-- The only permitted stops are the CLAUDE.md stop-and-ask gates (spend/on-chain writes, push/deploy, posting externally, committing content referencing a crypto project other than `$THREE`, destroying unrecoverable data). This order touches none of them.-- Concurrent agents share this worktree: stage explicit paths only (never `git add -A` or `git add .`), re-check `git status` and `git diff --staged` before committing.-- The em-dash and en-dash characters are banned in everything you write.--## Why this matters (measured 2026-10-25)--Production's Cloudflare R2 bucket is fully disabled at the account level right now:-- curl -s https://three.ws/api/healthz | python3 -c "import json,sys; d=json.load(sys.stdin); print([s for s in d['subsystems']['subsystems'] if s['name']=='object_storage'])"- # {"name":"object_storage","label":"Object storage (Cloudflare R2)","status":"down",- # "detail":"bucket unreachable: Please enable R2 through the Cloudflare Dashboard.",- # "hint":"...reads fail over to the public bucket domain meanwhile, writes do not fail over at all.", ...}--This is already tracked and owner-gated: `prompts/RUN-ORDER.md` line 55, OWNER-ACTIONS row 36 ("Check Cloudflare's own R2 dashboard for the bucket behind `S3_BUCKET`... Flapping since 2026-09-08"). **This order does not touch R2 and does not attempt to fix the outage.** It closes a separate, code-fixable gap that is live right now and will recur on any future full-storage outage regardless of whether this one is R2-wide or just the signed-credential rot the fallback was originally built for (2026-09-07).--The gap: `api/cdn-object.js` already has a correct two-lane read path (signed R2 read, then `publicUrlOrNull(key)` streamed as a fallback when `isStorageInfrastructureError(err)` is true, lines 196-253). When R2 is disabled at the account level, BOTH lanes point at the same disabled product, so the fallback also throws, and the handler falls through to `return error(res, 502, 'upstream_error', 'failed to fetch object')` at line 254, a `cache-control: no-store` JSON body (`api/_lib/http.js:70`). The same two-lane-both-down path exists in `api/avatars/[id]/[action].js`'s `handleGlb` (lines ~707-742) for `/api/avatars/:id/glb`; that one is explicitly out of scope below.--Live confirmation, right now:-- curl -s -o /dev/null -w "HTTP %{http_code}\n" "https://three.ws/cdn/thumb/52f128e3-0367-415b-9e09-42ce9c1f159e.png"- # HTTP 502- curl -s -o /dev/null -w "HTTP %{http_code}\n" "https://three.ws/api/avatars/d39c5db1-779c-47eb-9c8c-e30231519cf3/glb"- # HTTP 502--Blast radius, from the unauthenticated live-page sweep (`reports/page-audit-2026-10-24T20-43-27-109Z.md`, generated by `npm run audit:web`): this is not dozens of independent page bugs, it is one shared root cause rendering as a broken `<img>` icon on nearly every page that shows a thumbnail, forge preview, or avatar. `/rankings` alone logs 47 distinct `http-502` entries against `/cdn/thumb/*`, `/cdn/forge/*`, `/cdn/u/*` and `/api/avatars/*/glb`; `/monitor` logs 46 more against the same four path shapes plus a client-side `[agent-3d] boot failed` console-error when a GLB 502s. Same-day Cloud Run request logs confirm it server-side and at volume:-- gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="three-ws-api" AND httpRequest.status=502 AND timestamp>="2026-10-24T00:00:00Z"' --format="value(timestamp)" --project=aerial-vehicle-466722-p5 | wc -l- # 72182- # top paths in a 50-row sample: 16x /cdn/thumb/<id>.png, 5x /api/avatars/<id>/glb,- # 3x /cdn/forge/<id>/<id>.jpg, several /cdn/u/<id>/...--A root-cause trace (not a guess) confirmed the fallback itself is correctly wired and is not the bug: `publicUrl`/`publicUrlOrNull` (`api/_lib/r2.js` lines ~338-362) build `${env.S3_PUBLIC_DOMAIN}/${encodeR2Key(key)}`, and both `api/cdn-object.js` (line 196, streamed at 200-238) and `api/avatars/[id]/[action].js`'s `handleGlb` (line 707, streamed at 711-727) call it identically. Neither handler bypasses it. The gap is structural: there is no third lane for "the whole storage product is disabled," so the fallback fails the same way the primary did, and today the only thing left to do is answer `502 upstream_error`, `cache-control: no-store`. That `no-store` also means a page with 40 thumbnails re-hits the dead storage on every repeat view for as long as the outage lasts, with zero caching of the failure.--This is distinct from and not already covered by any open order: `401` (vitest), `403` (docs freshness), `433` (account_link_codes migration), `435` (sentiment-pulse LKG) and `436` (forge-finalize TTL reap) do not touch `cdn-object.js`, `r2.js`, or any image-serving path. It is also distinct from the R2-outage itself: the Cloudflare dashboard action in OWNER-ACTIONS row 36 is the fix for *why* storage is down; this order is the fix for *what the site shows users while it is*, which stays broken even after this specific outage clears, on the next one.--## Task--1. Re-derive the current state before changing anything:- - `curl -s https://three.ws/api/healthz | python3 -c "import json,sys; d=json.load(sys.stdin); print([s for s in d['subsystems']['subsystems'] if s['name']=='object_storage'])"`, confirm `object_storage` is still `down` (if it is back to `ok`, the live symptom is gone, but the code gap this order fixes is still real and still worth closing for the next outage; proceed with the fix either way and say so in the report).- - `curl -s -o /dev/null -w "%{http_code}\n" "https://three.ws/cdn/thumb/52f128e3-0367-415b-9e09-42ce9c1f159e.png"` to confirm the live symptom.-2. Read `api/cdn-object.js` in full (254 lines), focused on: `contentTypeFor`/`CONTENT_TYPES` (lines 32-85), the main `catch (err)` block (lines 151-254), the `fallback` computation (line 196) and the inner `catch (fallbackErr)` branch (lines 239-253).-3. Add a same-origin, zero-dependency placeholder image constant near the top of `api/cdn-object.js` (module scope, built once, not read from disk on every request):-- const PLACEHOLDER_PNG = Buffer.from(- 'iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAATElEQVR42u3PMQ0AAAwDoPqXWSWVsHsJOCB9LgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIClwEaOGJ3yOGdeQAAAABJRU5ErkJggg==',- 'base64',- );-- This is a real, verified-valid 64x64 flat `#e2e2e2` PNG (133 bytes), generated with:-- python3 -c "- import struct, zlib- def chunk(tag, data):- return struct.pack('>I', len(data)) + tag + data + struct.pack('>I', zlib.crc32(tag + data) & 0xffffffff)- width, height = 64, 64- row = bytes([0xe2, 0xe2, 0xe2]) * width- raw = (b'\x00' + row) * height- compressed = zlib.compress(raw, 9)- png = b'\x89PNG\r\n\x1a\n' + chunk(b'IHDR', struct.pack('>IIBBBBB', width, height, 8, 2, 0, 0, 0)) + chunk(b'IDAT', compressed) + chunk(b'IEND', b'')- open('/tmp/placeholder-check.png', 'wb').write(png)- "-- Re-run this snippet and `diff /tmp/placeholder-check.png <(base64 -d <<< 'iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAATElEQVR42u3PMQ0AAAwDoPqXWSWVsHsJOCB9LgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIClwEaOGJ3yOGdeQAAAABJRU5ErkJggg==')` to confirm the constant decodes to a valid PNG before using it (do not trust the literal transcribed here without checking it decodes and that `file /tmp/placeholder-check.png` reports a valid 64x64 PNG).-4. In the main `catch (err)` block, compute the storage-infra-fault boolean once (`const isInfraFault = isStorageInfrastructureError(err);`) and reuse it for the existing `fallback` line (`const fallback = isInfraFault ? publicUrlOrNull(key) : null;`) so behavior there is unchanged.-5. Add the third lane. Immediately before the final `return error(res, 502, 'upstream_error', 'failed to fetch object');` at line 254 (which is reached both when `fallback` was falsy from the start and from the inner `catch (fallbackErr)` branch after the fallback itself failed), add: if `isInfraFault` is true AND `contentTypeFor(key, null).startsWith('image/')`, respond with the placeholder instead of 502:- - `res.statusCode = 200`- - `res.setHeader('content-type', 'image/png')`- - `res.setHeader('cross-origin-resource-policy', 'cross-origin')`- - `res.setHeader('cache-control', 'public, max-age=30, s-maxage=30')` (short, so real content starts serving again within 30s of either lane recovering, and so a sustained outage does not get hammered on every repeat view the way `no-store` does today)- - clear any stale `content-length`/`content-range`/`etag` headers the way the existing `fallbackErr` branch already does, before writing the body- - write `PLACEHOLDER_PNG` and return (`HEAD` gets the same headers with no body, matching the existing `HEAD` handling earlier in the file)- - Non-image keys (`.glb`, `.gltf`, `.usdz`, audio, video, json) fall through unchanged to the existing `502 upstream_error`. A placeholder GLB is not a sensible response for a 3D viewer and is explicitly out of scope (see "Never blocked" below).-6. `/api/avatars/[id]/[action].js`'s `handleGlb` is explicitly OUT OF SCOPE for this order: it only ever serves `model/gltf-binary`, there is no sensible image placeholder for a binary model, and `src/game/*` already has a working client-side fallback for this exact case (confirmed live in the page-audit console-warn: `[walk] avatar "..." failed to load, falling back to "robot" fetch`). Do not touch that file.-7. Write the failing test first, in `tests/cdn-object-storage-failover.test.js`:- - Locate the existing test `'502s once the public domain fails too, with no length left pinned to the object'` (uses key `'thumb/abc.png'`, an image key). Run `npx vitest run tests/cdn-object-storage-failover.test.js` now and confirm the whole file passes against the current, unfixed code (this is the pre-fix baseline, not a red test yet, because the assertion matches today's actual 502 behavior).- - Add a new test in the same `describe` block asserting the fixed behavior for an image key: `send.mockRejectedValue(CREDENTIAL_FAULT)`, `fetchUpstream.mockRejectedValue(new Error('r2.dev unreachable'))`, call the handler with `req('thumb/abc.png')`, and assert `res.statusCode === 200`, `res.getHeader('content-type') === 'image/png'`, `res.written().length > 0`, and `res.getHeader('cache-control') === 'public, max-age=30, s-maxage=30'`. Run it now against the unfixed code and confirm it fails (this is the required pre-fix red run).- - Add a second new test proving the GLB/non-image path is unchanged: same mocked double failure, key `'u/1/model.glb'`, assert `res.statusCode === 502` still (this should already pass before the fix, since the fix only branches on image content types; keep it to lock the boundary).- - Update the existing `'502s once the public domain fails too...'` test to use a non-image key (e.g. `'u/1/model.glb'` instead of `'thumb/abc.png'`) so its assertion (`statusCode === 502`, no stale `content-length`) stays accurate to the new, narrower scope of when a 502 is still correct; keep its "no length left pinned to the object" assertion.-8. Fix the code per tasks 4-5, re-run the full file (`npx vitest run tests/cdn-object-storage-failover.test.js`) and confirm every test passes, including the two existing ones not about this fix (`tests/cdn-object-content-type.test.js` is a different file, not expected to change, but run it too: `npx vitest run tests/cdn-object-content-type.test.js`).-9. Run `npm run check:rules -- --paths api/cdn-object.js tests/cdn-object-storage-failover.test.js` and fix anything it flags.-10. Read the full diff (`git diff api/cdn-object.js tests/cdn-object-storage-failover.test.js`) and confirm every changed line traces to a task above.-11. This fix cannot be verified against production from this session (no deploy in an evolve lane). The report must say plainly that the live `/rankings`, `/monitor`, etc. broken-image symptom is unverified-fixed in production until this ships; do not claim the live site is already showing placeholders.--## Done when--- A new test in `tests/cdn-object-storage-failover.test.js` proves an image key gets a `200` with the placeholder PNG and a 30-second cache-control when both the signed read and the public-domain fallback fail with a storage-infrastructure fault, confirmed to fail against the pre-fix code first.-- A second new test proves a non-image key (`.glb`) still gets `502` in the same double-failure scenario, unchanged.-- The pre-existing `'502s once the public domain fails too...'` test is updated to a non-image key so its `502` assertion stays correct under the new, narrower scope.-- `api/cdn-object.js` serves the bundled placeholder PNG (not a raw JSON 502) for any image-content-type key when `isStorageInfrastructureError(err)` is true and the public-domain fallback also fails; non-image keys and non-infrastructure faults are unchanged.-- `api/avatars/[id]/[action].js` is untouched (confirm with `git diff --stat` showing no changes to that file).-- `npx vitest run tests/cdn-object-storage-failover.test.js tests/cdn-object-content-type.test.js` passes in full.-- `npm run check:rules -- --paths api/cdn-object.js tests/cdn-object-storage-failover.test.js` passes.-- `git diff` reviewed; every changed line traces to a task above.-- The fix is committed on `evolve` with explicit paths (`api/cdn-object.js`, `tests/cdn-object-storage-failover.test.js`) and a commit message naming the bug and the fix.-- The report states plainly that the live production symptom's actual resolution is unverified until this ships (no deploy happens in this lane).-- This file is removed, with a dated entry added to `prompts/finish/_context/production-100-PROGRESS.md` citing the fix commit SHA and what was verified (and noting the live-site drain is pending a deploy).--## Never blocked--| Looks like a blocker | It is not | Do this |-|---|---|---|-| "The real fix is re-enabling R2 in the Cloudflare dashboard, so this whole order is owner-gated" | That is a separate, already-tracked fix (`RUN-ORDER.md` OWNER-ACTIONS row 36) for a different question (why storage is down). This order answers a different question (what the site shows users while it is, on this outage or the next) and needs zero Cloudflare access | Ship the placeholder fallback. Do not wait on or reference the R2 dashboard action as a precondition |-| "GLB/avatar models need a placeholder too, for parity" | A static image cannot stand in for a binary 3D model in `agent-3d` or `model-viewer`; the `/walk` lane already has a working client-side fallback for exactly this (`falling back to "robot" fetch`, confirmed live). Building a second, server-side GLB placeholder is a different, larger, lower-value task (which GLB, animated how) that doesn't fit this order's scope | Leave `api/avatars/[id]/[action].js` and all `.glb`/`.gltf`/`.usdz` handling untouched. If the owner wants client-side GLB-boot resilience for `agent-3d` specifically (the `[agent-3d] boot failed` console-error seen on `/monitor`), that is a candidate for a future, separately-scoped order, not this one |-| "Serving a 200 for a failed object could hide the outage from monitoring" | `console.error('[cdn-object] public bucket domain failed too:', ...)` at line 240 still fires before the new branch runs; `/api/healthz`'s `object_storage` subsystem is a separate, already-correct signal (`api/_lib/ops/object-storage-health.js`) untouched by this change. This order only changes what the HTTP response body and status look like to a browser `<img>` tag, not what gets logged or what healthz reports | Keep the existing `console.error` calls exactly as they are; only add the new response branch after them |-| "This needs a real icon/design asset, not a flat gray square" | A flat-color placeholder is sufficient to stop a broken-image icon and a `no-store` retry storm; it is not a design deliverable. Swapping in a nicer asset later is a pure drop-in (same `Buffer.from(...)` constant) and does not change this order's done-when criteria | Ship the flat `#e2e2e2` PNG as specified. Do not spend session time designing a nicer placeholder |--## Report format--State: the measured re-derivation from task 1, the failing tests' first (red) run output, the fix, the passing test run output (both files), the `check:rules` result, the diff, and the commit SHA. End with one explicit line: "Live production symptom: unverified, pending deploy."diff --git a/prompts/finish/_context/production-100-PROGRESS.md b/prompts/finish/_context/production-100-PROGRESS.mdindex 1f010ac57..2c8f897ce 100644--- a/prompts/finish/_context/production-100-PROGRESS.md+++ b/prompts/finish/_context/production-100-PROGRESS.md@@ -1874,3 +1874,17 @@ Verification: `npm run check:rules -- --paths api/cron/forge-finalize.js tests/fProduction backlog drain: unverified, pending deploy. This is the evolve lane; no deploy happens here. The next deploy of `three-ws-api` is the step that lets the already-stalled ~893 rows (and any new ones) start draining to the designed 45-minute TTL instead of the observed ~24h average.Left: nothing for this order's own scope. `prompts/finish/436-auto-forge-finalize-ttl-reap-decoupling.md` deleted in this closing commit.++## 2026-10-25: order 437 (CDN image placeholder fallback) closed++Step 0 re-derived the live symptom exactly as the order measured: `curl -s https://three.ws/api/healthz | python3 -c "..."` still showed `object_storage` status `down`, detail `bucket unreachable: Please enable R2 through the Cloudflare Dashboard.`; `curl -s -o /dev/null -w "%{http_code}" https://three.ws/cdn/thumb/52f128e3-0367-415b-9e09-42ce9c1f159e.png` still returned `502`.++Did: read `api/cdn-object.js` in full. Added a module-scope `PLACEHOLDER_PNG` constant (a 64x64 flat `#e2e2e2` PNG, 133 bytes, base64-decoded once at load time), verified by regenerating the same PNG with the order's own `zlib`/`struct` recipe and diffing it byte-for-byte against the literal before using it, then confirming its signature, 64x64 dimensions, 8-bit truecolor header independently in Python. Hoisted `isStorageInfrastructureError(err)` into a named `isInfraFault` constant reused unchanged by the existing `fallback` line. Added a third lane immediately before the final `return error(res, 502, ...)`: when `isInfraFault` is true and `contentTypeFor(key, null)` starts with `image/`, clear any stale `content-length`/`content-range`/`etag`, respond `200` with `content-type: image/png`, `cross-origin-resource-policy: cross-origin`, `cache-control: public, max-age=30, s-maxage=30`, and either end the response (HEAD) or write `PLACEHOLDER_PNG` (GET). Non-image keys (`.glb` etc.) fall through to the unchanged `502`. `api/avatars/[id]/[action].js` was not touched (confirmed via `git diff --stat`, two files only).++Test-first: in `tests/cdn-object-storage-failover.test.js`, ran the file first against unfixed code (9/9 passed, the documented pre-fix baseline). Changed the pre-existing `'502s once the public domain fails too...'` test's key from `'thumb/abc.png'` to `'u/1/model.glb'` so its 502 assertion stays accurate to the new, narrower scope. Added `'serves the placeholder image instead of a 502 for an image key once both lanes fail'` (image key, asserts `200`/`image/png`/non-empty body/the 30s cache-control) and ran it red first: failed with `expected 502 to be 200`, the exact reason named by the order. Added `'still 502s a non-image key (GLB) once both lanes fail, no placeholder swap'` to lock the boundary. Applied the fix, reran: `npx vitest run tests/cdn-object-storage-failover.test.js tests/cdn-object-content-type.test.js` passed 19/19.++Verification: `npm run check:rules -- --paths api/cdn-object.js tests/cdn-object-storage-failover.test.js` exited 0 ("no hard-rule violations"). `git diff` reviewed: every changed line traces to a task in the order (the placeholder constant, the `isInfraFault` hoist, the new third-lane branch, the two new tests, and the one updated test's key). `git status`/`git diff --staged --stat` showed only the two intended files staged before committing. Fix commit: `52eb1b083`.++Live production symptom: unverified, pending deploy. This is the evolve lane; no deploy happens here. `/rankings`, `/monitor` and every other page showing a broken `<img>` icon against `/cdn/thumb/*` stay broken until `three-ws-api` is redeployed with this change, at which point the same pages fall back to the flat placeholder instead of a broken-image icon for as long as the R2 outage (OWNER-ACTIONS row 36) lasts.++Left: nothing for this order's own scope. `prompts/finish/437-auto-cdn-image-placeholder-fallback.md` deleted in this closing commit.