Asset Production

A structured, validated request becomes a checked 3D asset: parametric geometry built in code, inspected, written as GLB with its provenance inside, measured, optionally kept in a write-once store, and loaded into the existing Threlte viewer. One engine, one job shape, three callers (HTTP, CLI, MCP tool). Pattern record: asset-production-pipeline.

Contents

• Why this shape - the concerns kept apart
• Engine choice - what was compared, and why plain TypeScript won
• The pipeline - request → check → generate → inspect → encode → verify → keep
• Invariants - what holds, and which test holds it
• Quality gates - what every exported asset must pass
• Execution environments - in-process and isolated worker; GPU not built
• Security and reliability - untrusted input, limits, no overwrite
• AI and MCP - typed operations, never code
• Measurements - real numbers, where they come from
• Showcase - /showcases/3d/produce
• Toward a managed service - proposals, not built
• Anti-patterns
• Proof - the tests and pages behind the record
• Emulating it

Why this shape

"Generate a model" tends to become one function that reads form fields, builds meshes, calls an exporter, writes a file and returns a URL. Each concern then blocks the others: the exporter cannot be swapped, the job cannot move to a worker, an AI cannot call it safely, and nobody can say which code made a file. This pattern keeps ten things apart:

The core (src/lib/asset-production/) imports only its schema, Valibot and Three.js's Vector3: no Svelte, no DOM, no Node API. The same engine runs in a serverless function, a child process, a terminal and a browser — the showcase uses it client-side for the live estimate and the parameter rules before it sends anything.

Vocabulary: asset production — always qualified, because bare production is the deployed environment. AssetRequest, AssetGenerator, AssetProductionEngine, EngineRun, AssetExecutionEnvironment, AssetJob, AssetReport, AssetStore. See docs/naming.md.

Engine choice

Decision principle: the simplest engine that meets the initial requirements — parametric, deterministic, GLB out, cheap to run, no new infrastructure. Compared against those, not against feature lists.

Footprints for B and C are from the projects' published distributions, not measured in this repository; the npm sizes are npm view <pkg> dist.unpackedSize on 2026-10-29.

When Blender earns its place. When a demonstrated requirement needs what only a DCC tool does — importing arbitrary user files (FBX, OBJ, USD), decimation, UV unwrapping, baking, thumbnails rendered with Cycles. Then: a separate CPU container worker (--network=none, memory and CPU caps, read-only image, scratch volume), driven by a closed list of typed operations that map to fixed, versioned Python scripts in the image. Never --python-expr with caller text, never an MCP tool that forwards Python, never add-ons installed at run time. It slots in as another AssetExecutionEnvironment plus an engine adapter; the request schema, report, store and viewer stay.

The pipeline

AssetRequest (untrusted JSON)
  └─ check     strict Valibot parse · cross-parameter rules · exact estimate vs budget
  └─ generate  generator(parameters, checkpoint) → GeneratedMesh { primitives, envelope }
  └─ inspect   counts · bounds · closed + outward shells · finite · unit normals · envelope
  └─ encode    byte-stable GLB · asset.extras.v10r = { transform, requestDigest, derivationKey }
  └─ verify    read the GLB back · byte budget
  └─ keep?     AssetStore.put(owner/derivationKey) — created | reused | conflict
  └─ AssetReport { output, derivation, engine, generator, environment, inspection,
                   diagnostics, measurements, provenance (PROV-DM) }

Stages are timed separately. A refused request never reaches generate; a failed one never returns bytes. Findings are AssetDiagnostics with a fixed severity per code (diagnostics.ts), never exceptions.

The demonstration generator is a structural ring: a square-section truss bent into a ring (Warren, single-direction or X bracing), spokes to a capped hub with docking ports, and boxed modules on the outer chords. Nine bounded numeric parameters and one pick list; from 1,248 to 68,352 triangles. Every strut is a capped tube, every module a box: each is a closed shell.

Derivation and provenance. The derivation key is the repository's derivationKey (src/lib/server/db/content-hash.ts) over procedural-ts@1/structural-ring@1 and the request's canonical JSON (sorted keys, label excluded — it is presentation). Same key ⇒ same bytes; that is what makes a repeat run a cache hit and a byte mismatch a loud store.conflict. The report's provenance is the PROV-DM core of docs/blueprint/integrity/derivation.md: the entity (sha256), the activity (transform, start, end), the agent (human / software / ai, with onBehalfOf) — never an IP or an email.

Invariants

Quality gates

"Closed" is per shell. Overlapping struts are separate closed shells, not one booleaned solid: right for rendering, not for 3D printing (add a CSG union first).

Execution environments

Security and reliability

• Inputs are untrusted. Strict objects, closed numeric ranges, a discriminated generator id. The request cannot name a file, a script, a URL or an engine flag. Bodies over 4 KiB are refused before parsing; the HTTP route rate-limits per IP before any geometry (20 / minute).
• Work is bounded before it starts. The estimate is exact, so an oversized request costs one arithmetic pass. Inside a run the deadline is carved from the request's own Deadline.
• No uncontrolled processes. The isolated worker is killed with SIGKILL at its deadline and its exit is awaited before the job resolves.
• No overwrite, no publish. Write-once by derivation key; a directory store writes to a staging directory renamed into place in one step; keys are [a-z0-9-] segments resolved under the root. A kept asset is a draft; publishing is a separate, explicit act (not built).
• Imported assets. This slice imports none. A future import path reads GLB with the same readGlb gate first, in the isolated environment, with the same byte budget.
• Privacy. The showcase stores nothing and reports no identity; the agent is "showcase visitor".

AI and MCP

createAssetToolRegistry() is a ToolRegistry for the hosted MCP transport with two tools: describe_asset_generators (parameters, bounds, budget) and produce_asset (the request schema as its JSON Schema input; returns the report as text and keeps an owner-scoped draft). An agent creates a variation by changing typed parameters, reads the findings, and tries again — the same propose → check → revise loop as the PIM transform recipe, with no free-form code anywhere.

It is not mounted on the public /api/mcp endpoint, by decision: produce_asset spends CPU per call, and anonymous compute belongs behind the showcase route's rate limit. Mount it on an authenticated endpoint (admin, or per-user with a quota) — one registry line. No AI provider is involved anywhere; everything works without one.

Measurements

bun run asset:bench --runs 20, 2026-10-29, cloud container: Intel Xeon @ 2.80 GHz, 4 vCPUs, Linux x64. p50 / p95 over 20 in-process runs (5 isolated), first run included. Node 22.22 (what Vercel runs) via node --experimental-strip-types scripts/asset-production/bench.ts:

Under Bun 1.3.12 the in-process totals are 10.3 / 24.4 / 103.8 ms. Largest-case stage split on Node: generate 22 ms, inspect 34 ms, encode 3 ms, verify 2 ms. Inspection dominates; it is the price of the shell check. The isolated worker adds ~100–150 ms of process start and module load per run (its RSS after a run: 67–130 MiB).

What this implies, not measured on Vercel: the largest request is ~0.1 s of CPU in a function, so the showcase is cheap per run; the cost risk is volume, which the rate limit bounds. The GLB travels base64 in JSON — 2.5 MB becomes ~3.3 MB, under Vercel's 4.5 MB response cap. Browser parse and paint times are shown live on the page; they are not quoted here because they depend on the visitor's device. Browsers: anything that runs the existing Threlte showcases (WebGL 2); without WebGL the page still produces the asset and shows its report.

Showcase

/showcases/3d/produce: presets (outpost, default, station), a slider per parameter and the bracing pick list, a live estimate and the parameter rules computed in the browser by the same core, Generate / Cancel, the model in a Threlte canvas (on-demand rendering, studio light, <svelte:boundary> fallback), and four panels — validation (every gate, or every finding), output (size, counts, shells, extent, sha256, derivation key, download GLB and report), engine (engine, generator, environment, runtime, budget), measurements (server stages and CPU, round trip, browser parse, time to paint).

Toward a managed service

Proposals — none of this is built, and none needs a paid provider for the slice above.

Anti-patterns

• Unrestricted engine scripting — a tool or form field that forwards Python or OpenSCAD source. Typed operations only.
• A heavy engine for light geometry — Blender or a CAD kernel for meshes plain code builds in milliseconds.
• Exporting from the scene graph — GLTFExporter in the server drags the DOM in and makes bytes depend on renderer state.
• Trusting the estimate alone — the budget is checked again on what was really built.
• Overwriting by name — ring.glb replaced in place. Key by derivation, write once.
• Timestamps in the asset — they break byte identity; times belong in the report.
• Publishing from the job — a job produces a draft; publishing is the owner's act.
• Claiming structural validity — the gates check the file and its surfaces, never strength.

Proof

Emulating it

1. Write the request schema first: a discriminated generator id, strict objects, closed ranges from one bounds table your UI and tool description also read.
2. Write the generator against a mesh intermediate with shells and a declared envelope, plus an exact estimate. Test estimate = actual at every bound.
3. Add inspection and a DOM-free, byte-stable GLB writer with a read-back gate; run the Khronos validator in tests.
4. Wrap it in an engine with timed stages, a budget checked twice and checkpoints.
5. Put the job, report, derivation key and write-once store around it; then the callers (route with a rate limit, CLI, MCP registry).
6. Present last: the viewer loads the GLB the job returned, nothing else.