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.

9.4 KB
Raw Blame

Run receipts: what each stage was expected to do, and what it did

Every generation the free 3D Studio starts (forge_avatar, text_to_avatar, mesh_forge, forge_free, rig_mesh) writes a run receipt. refine_model does not write one. A receipt walks the pipeline stage by stage. For each stage it records:

  • the expected result
  • the observed result
  • a verdict
  • the cause whenever the verdict is not a clean pass

The finished record is hashed and signed with ed25519, so it cannot be edited after the fact without the edit showing.

Browse them at three.ws/runs. Each receipt has its own page, /runs/rr_…, and every Studio result links to its receipt in the text and in structuredContent.receipt.

Why this exists

A generation pipeline that answers "here is your model" and nothing else hides everything that matters when a result is disappointing. When the director model timed out, the prompt went in as written. When the high-detail lane was full, the job ran on the standard tier. When the rigger returned a skeleton with no legs, the walk cycle can never play. A receipt makes each of those visible as it happens, in the same response, written by the pipeline itself rather than reconstructed afterwards.

Verdicts

Verdict Meaning
met The stage did what it was expected to do.
recovered The stage did not do the expected thing, but a named fallback carried the run (a different tier, the prompt used as written, an automatic regeneration).
missed The stage did not do what was expected, and the receipt says why (cause).
skipped The stage did not run (a reference image skips the brief; draft and standard tiers skip the vision check; rig_mesh never checks the subject). A skip is never counted as a pass: the summary of a run with a skipped stage reads "Every stage that ran met its contract" and names the skipped stages.
pending The stage was still running when the tool answered. Only check_job completes the receipt; the server stores a hash of the job handle, not the handle, so it cannot collect the job itself. A receipt still pending an hour later is shown as never collected.

Stages

Stage Expected How it is observed
Input A prompt or reference image that passes the content-safety check. The safety check and image guard. A refused prompt is not stored.
Subject check A humanoid subject, since rigging builds a two-legged skeleton. forge_avatar: the same humanoid classifier the tool already gates on. rig_mesh: always skipped, with the cause stated, because a caller-supplied mesh is rigged as given and nothing checks that it depicts a body. A lamp still receives a full humanoid skeleton, and the receipt says so instead of letting a met Rig stage imply otherwise.
Brief A director-written 3D specification. Whether the director's brief was used, or the exact reason it was set aside (too long, with its length; unfinished; carried a link; added nothing; no reply), or a known-mark brief applied.
Mesh A textured mesh from the requested tier. The engine and tier that actually ran, from the terminal job frame.
Geometry check A valid GLB with real, textured geometry. The deterministic geometry score the forge computes on every file (triangles, vertices, textures).
Visual check A render that reads as a clean, complete subject. The vision QA gate's verdict, score and defects, where the tier runs it.
Rig A skinned humanoid skeleton with torso, arms and legs mapped. Read back from the delivered file, using the same analysis as Rig Doctor (src/rig-report.js), not taken from the rigger's own report.
Delivery A permanent first-party link. Whether the file landed on three.ws storage or only on the engine's temporary link.

Each run's overall outcome is one of the following:

  • delivered
  • delivered_with_issues
  • partial (for example the mesh shipped but the rig failed)
  • pending
  • refused
  • failed

The outcome is derived from the stages. A tool can only state a worse outcome than the stages imply, never a better one.

The receipt object

A real one, from a proof run on 2026-10-11 (stages trimmed to three of eight):

{
  "type": "three-run-receipt/v1",
  "id": "rr_81qbfUbiZNqSTD6rVmjCoA",
  "tool": "forge_avatar",
  "plan": { "rig": true, "tier": "high" },
  "started_at": "2026-10-11T02:31:35.330Z",
  "finished_at": "2026-10-11T02:32:52.928Z",
  "duration_ms": 77598,
  "input": { "prompt": "a friendly cartoon astronaut in a white suit with an orange visor", "reference_image": false },
  "stages": [
    { "id": "brief", "label": "Brief", "ms": 7738, "expected": "A director-written brief that frames the whole figure head to toe in a neutral A-pose.", "observed": "The fixed full-body brief was appended to the prompt as written.", "verdict": "recovered", "cause": "The director reply stopped mid-sentence, so it was treated as clipped and set aside. The fixed brief keeps the framing." },
    { "id": "mesh", "label": "Mesh", "ms": 47093, "expected": "A textured 3D mesh from the high-detail tier.", "observed": "A mesh from the high-detail tier on TRELLIS (free).", "verdict": "met", "metrics": { "tier": "high", "engine": "TRELLIS (free)" } },
    { "id": "rig", "label": "Rig", "ms": 22654, "expected": "A skinned humanoid skeleton the animation library can drive: torso, arms and legs mapped.", "observed": "52 joints (Mixamo), 52 mapped to the canonical skeleton; torso, arms and legs all driven.", "verdict": "met", "metrics": { "joints": 52, "mapped": 52, "skinned": true, "convention": "Mixamo" } }
  ],
  "outcome": "delivered",
  "summary": "Delivered as expected. 1 carried by a fallback (Brief).",
  "issues": [ { "stage": "brief", "label": "Brief", "verdict": "recovered", "expected": "…", "observed": "…", "cause": "The director reply stopped mid-sentence, so it was treated as clipped and set aside. The fixed brief keeps the framing." } ],
  "output": { "glb_url": "https://three.ws/cdn/forge/anon/9d23314f-a385-432d-bd4c-41513c5119f6.glb", "viewer_url": "https://three.ws/viewer?src=…" }
}

It is stored inside a signed envelope:

{ "receipt": { … }, "sha256": "<hex of the canonical bytes>", "signature": "<base58 ed25519>", "signer": "<base58 public key>" }

The signature covers three-run-receipt/v1 + \n + the canonical JSON of the receipt (keys sorted, no whitespace).

Verify one yourself

The server verifies every receipt it serves, but you do not have to trust it:

node scripts/run-receipt-verify.mjs rr_81qbfUbiZNqSTD6rVmjCoA
node scripts/run-receipt-verify.mjs https://three.ws/runs/rr_81qbfUbiZNqSTD6rVmjCoA --signer <pinned key>
node scripts/run-receipt-verify.mjs ./downloaded-receipt.json --json

The verifier fetches the envelope (or reads a downloaded file). It then recomputes the hash and checks the ed25519 signature locally, and optionally checks the signer against a key you pinned. It prints every stage and exits non-zero on any failed check. Changing one character of any stage breaks it.

The signing key is the platform attestation key (ATTEST_AGENT_SECRET_KEY). Its public half is returned as signer by GET /api/runs?stats=1. A deployment without the key still writes receipts, hashed but marked unsigned, and the page says so.

API

Call Returns
GET /api/runs?id=rr_… The envelope plus a fresh server-side verification ({ ok, checks[] }). 400 for a malformed id, 404 if unknown.
GET /api/runs?stats=1&days=7 Aggregate counts over 1 to 90 days: outcomes, delivery rate, clean rate, per-tool totals, per-stage verdict counts and met rate, and the most common causes. Counts only; no prompts.

Both are public, CORS-open and keyless.

Privacy

  • A receipt id is an unguessable handle (rr_ plus 16 random bytes in base58). Receipts are not listed individually anywhere. Only the person holding the link can open one.
  • The job handle is stored only as a one-way hash, so a receipt never exposes a job token.
  • A prompt refused by the safety check is not stored.
  • The aggregate view at /runs shows counts and causes, never prompts.

Failure behavior

A receipt never changes a tool's result; it only adds to it.

  • If the database is unreachable, the tool still answers and carries the receipt inline, without a link.
  • Saving waits at most 2.5 s.
  • Reading the rig back has a 10 s budget. If it fails, the rig stage is skipped with the cause, never a guess.
  • A link is only attached once the receipt is actually stored, so a receipt link never 404s.

Code

Related