The open 3D studio is twelve capabilities, and each one carries a state that
says, honestly, how far it has got. This document describes that ladder, the
four admission checks that decide what may be on a capability's execution path
at all, and where each is enforced. They are not enforced in the same place.
Submit enforces the ladder: the generation API refuses a job whose
capability is not submittable (assertThreeDCapabilitySubmittable). The
admission checks do not run at submit. The model, tool and asset checks
compute an outcome into their manifests, and a spec fails a manifest that
disagrees with them; the controller check is a policy function with no caller
on a production path yet (§5.4).
Code: libs/isis/workflows/src/three-d-capabilities/capability-state.ts (the
ladder), registry.ts (the twelve records), model-admission.ts,
tool-admission.ts, asset-admission.ts, controller-admission.ts, and
apps/isis/generation-api/src/services/three-d-capabilities.ts (enforcement).
ADR: ADR-0008.
Evidence: docs/agents/isis-3d-studio-evidence.md.
1. Why states exist at all#
The T.00.02 trace followed 38 paths through 30 libraries and found 5 runnable, 2 partially wired, 6 simulated, 25 dead, and 20 defects — with no path taking a prompt or an image to a stored, verified mesh. A capability map alone would have read as a product. The state ladder is what keeps the map honest: a capability claims only the rung its evidence earns, and the API refuses a job for a capability that cannot produce its artifact.
2. The ladder#
Six rungs in order, and each is earned by evidence of the kind that rung claims:
| State | Evidence kind | What the evidence must name |
|---|---|---|
candidate |
candidate |
the named candidate implementations and the record that lists them |
admitted |
admission |
a T.01 item, and every artifact pinned by 40-hex revision and sha256 |
wired |
runtime-path |
the API entry point and the dispatch site, by file and line |
offline-verified |
offline-verification |
a spec file, the command, a pass count and zero failures |
live-rendered |
live-render |
a provider job id and the output artifact's type, sha256 and bytes |
release-qualified |
release-gate |
the capability's own T.17.06 gate id and a passing result per cell |
unavailable sits beside the ladder rather than on it: any record may be
marked unavailable with a non-empty reason and at least one evidence reference.
Leaving unavailable re-enters at candidate and every later rung is earned
again.
Three rules hold the ladder rigid:
- A promotion may not skip a rung.
- Nothing but
unavailablemoves a record down. - A record is valid only if replaying its ladder earns exactly its state.
getThreeDCapabilityRegistryrefuses to hand out a registry that does not replay, so the state field cannot drift from the evidence beneath it.
Only live-rendered and release-qualified are live-ready. A catalog
workflow's proof_level is reconciled against the capability's state
(catalog-proof-reconciliation.ts): it can cap a claim, never make one, and
it never certifies quality.
The nine artifact types a capability may deliver are mesh, textured-mesh,
cad-source, rigged-mesh, motion-clip, scene, export-file,
engine-package and operations-receipt. A live render must return one of the
capability's own types — a GLB does not promote a rigging capability.
3. The twelve capabilities, as of 2026-09-14#
THREE_D_CAPABILITY_REGISTRY_AS_OF records the date the states below were last
established against their evidence.
| Id | Capability | Owner | State |
|---|---|---|---|
| C1 | Image/text/multi-image → 3D | libs/isis/3d-inference-local |
unavailable |
| C2 | Procedural/CAD and hybrid assemblies | libs/isis/3d-scene-assembly |
candidate |
| C3 | Real-photo and multi-object reconstruction | libs/isis/video-to-mesh |
unavailable |
| C4 | PBR/text/image retexturing | libs/isis/3d-post-pipeline |
candidate |
| C5 | Smart-topology-class usability | libs/isis/3d-post-pipeline |
unavailable |
| C6 | Auto-rigging and skin weights | libs/isis/universal-rigging |
unavailable |
| C7 | Text animation/presets/retargeting | libs/isis/universal-rigging |
unavailable |
| C8 | Agent/closed-loop/selective edits | apps/isis/generation-api |
candidate |
| C9 | Scene/workspace/timeline/API | apps/isis/generation-api |
unavailable |
| C10 | Mesh/CAD/print exports | libs/isis/3d-post-pipeline |
unavailable |
| C11 | Three.js/Godot/Unity/Unreal | libs/isis/3d-post-pipeline |
unavailable |
| C12 | Self-hosting, reliability and economics | apps/isis/generation-api |
unavailable |
No capability holds admitted or above. T.01 has admitted nothing, so no
ladder can pass candidate. Evidence that exists but earns no rung — the
T.00.03 package builder's specs, for instance — sits in unpromotedEvidence
with the reason it earns nothing.
A state was chosen from the evidence only: candidate where the matrix names
candidate implementations and an owner and nothing on a public route presents
the capability; unavailable where a public route accepts the request today and
cannot produce the artifact, where a surface presents simulated results as the
capability, or where every path depends on unadmitted or excluded models.
An unavailable reason names the blocking paths and defects. C1's, for example,
names five paths and four defects: text-to-3d resolves to WORKFLOW_NOT_FOUND
(P1); the image-to-3d default saves images only and is certified by a test
double that returns a GLB for any 3D job (P2, D6); hunyuan3d-asset is an
excluded family (P3) and stable-zero123 a non-commercial checkpoint (P4); the
stock worker drops non-image outputs (D1) and the adapter throws on GLB bytes
(D2).
4. Enforcement at the API#
GET /api/v1/workflows/catalog/3d-capabilities is a read-only listing: each
capability's state, reason and evidence, plus how the proof_level of every
workflow claiming it reconciles against its artifact type. Every state carries a
one-line meaning for the listing and the dashboard legend.
At submit, beside the content-policy check and before the model cache is leased or a job row exists:
| Situation | Refusal |
|---|---|
The capability the request needs is unavailable |
422 capability_unavailable |
| A 3D catalog workflow no capability claims | 422 capability_unmapped |
A malformed parameters.threeD block |
422 three_d_request_invalid |
| A hosted-lane request whose type does not match | 422 hosted_lane_type_mismatch |
Any other state is accepted and labelled — the job and the response carry
the capability's state and liveReady, which is true only from live-rendered
up. A client-supplied threeDCapability value in metadata is overwritten.
A job that names a hosted lane mode is judged by the lane's own record, not
by the self-hosted capability its type would match (T.22.03). The self-hosted
record keeps its state — C1 stays unavailable — and such a job is not refused
for it. Its label carries the lane's state (live-rendered for Meshy), the
self-hosted state beside it as hostedLane.selfHostedState, and a liveReady
that is true only for a lane mode whose capability has itself rendered, so a
label can read live-rendered with liveReady: false.
The parameters.threeD block is judged whole, before its stages are mapped
onto capabilities, so a malformed request is told what to fix rather than
which capability happens to be unavailable.
There is no route that changes a state. The registry is checked in and replayed from its evidence.
5. Admission: what may be on the path#
Four checks, three of them over a checked-in manifest. The model, tool and asset
checks each compute the outcome and write it into their manifest
(infra/runpod/volumes/isis-3d-models.manifest.json, -tools, -assets) — a
hand-edited status fails the spec. The controller check has no manifest: its
rows are the constant THREE_D_CONTROLLER_REGISTRY, evaluated against a model
listing that answered, and it writes nothing. All four fail closed.
5.1 Models (model-admission.ts, T.01.01–T.01.02)#
Input: infra/runpod/volumes/isis-3d-models.manifest.json — every artifact an
upstream inference path loads, every package it imports, the code it fetches at
request time, and the licences all of those carry. The check decides, per
inference path and per candidate, whether the whole execution path is
admissible.
Refusal codes:
- Pinning.
hash_missing/hash_malformed(no 64-hex lowercase sha256; a URL-hosted artifact is pinned only by its hash).revision_floating— a Hugging Face revision that is not a 40-hex commit, a URL with no immutable revision, a dependency pinned by branch, tag, default branch, version range or nothing, or code that downloads a model at request time without a revision. - Precision.
precision_unknown/precision_unsupported: the full-precision rule. A weight must state its stored dtypes; quantized or compressed markers and 8/4-bit dtypes are refused, and so is a weight with no floating dtype. - Closure.
closure_incomplete/closure_mismatch: a path that loads, imports or fetches something with no pinned row, or rows claiming a candidate no path uses. - Families.
excluded_family: anything whose identity, source, derivation or licence matches the excluded list — the same list the state machine refuses atadmitted. - Licences.
licence_unknown,licence_non_commercial,licence_terms_unrecorded,licence_review_required,licence_territory_excluded. There is no evaluation tier: the toolbox decision of 2026-09-14 dropped it, so a research or evaluation-only licence has no admissible tier at all. A custom commercial licence is admitted only with its territory, acceptable-use clause and distribution tier recorded, as the licence register does; a territory excluding the EU or the UK is refused. Copyleft needs its obligations recorded; network copyleft needs a recorded review. - Gating.
access_gated: a candidate, artifact or dependency of a gated custom-licence family with no recorded grant.
5.2 Tools (tool-admission.ts, T.01.04)#
Input: infra/runpod/volumes/isis-3d-tools.manifest.json — one row per
executable, library, service or runtime the plan uses or intends to use
(Blender, CadQuery, OpenSCAD, CuMesh, xatlas, meshoptimizer, QuadriFlow,
reconstruction tools, engines, controllers, the distributed worker stack). Model
weights and a model path's Python imports stay in the model manifest; a tool row
that is also a model-path dependency names that row in modelManifestRefs.
Beyond the pinning and licence families above, the tool check adds the rules that only make sense for software you run:
pin_floating/pin_malformed: the audited version is not fixed to exact bytes (a commit, an exact PyPI version, a lockfile entry with its integrity, a release archive with its sha256, an image digest).repo_reference_floating: somewhere in this repository installs or resolves the tool by tag, branch,latest, an unpinned apt or pip install, or a binary looked up onPATH.required_proprietary: a tool the open-core profile requires is proprietary and no owner review accepts its terms.required_network_service: a tool the open-core profile requires is a network service. No review can clear this — the open core runs without one.copyleft_linked_review: GPL or AGPL code linked into code the open core distributes, as opposed to a separate executable invoked as a process, with no recorded review.output_rights_unknown/_review_required/_prohibited: what the terms say about the files a user makes with the tool.closure_unexpanded/closure_licence_uncovered: the tool's own dependencies are not listed (a lockfile closure, a read and hashed vendor notice, or none), or list a non-permissive licence no row covers.component_refused: a component bundled into this tool is refused, so the tool is.houdini_dependency,excluded_family: SideFX Houdini is out of scope by the plan, and the excluded families are the shared list.
The published notices are
../runbooks/3d-tool-notices.md with the SBOM
beside it.
5.3 Assets (asset-admission.ts, T.01.05)#
Input: infra/runpod/volumes/isis-3d-assets.manifest.json — reference assets,
HDRIs, motion clip sets, datasets, body models and benchmark inputs.
Each row records three permissions, read from a dated source, plus the same A.04 classification the rest of the chain carries:
redistribution— may Isis ship the file itself (in a worker image, a package, a tenant download)?generationService— may it condition, or be used inside, a hosted generation service tenants use?outputRights— what may outputs derived from it be used for?classification.distribution(service|internal_only) andclassification.content(neutral|racy|explicit) — the same vocabulary and meaning as a catalog option'soption_policyentry, which is what letsasset-lineage.tscarry a boundary through every derivation.
Refusals include the pinning and licence codes above plus the ones specific to
files with permissions: hash_mismatch / file_missing / hash_unverified (an
in-repository file whose bytes differ from the recorded sha256 or size, are
absent, or were never measured); licence_per_item (a collection whose items
carry different licences with no per-item selection); permission_unknown /
_review_required / _conditions_unrecorded; distribution_exceeds_permission
(distribution: service on a row whose generation-service permission is neither
allowed nor conditional); and redistribution_prohibited.
5.4 Controllers (controller-admission.ts, T.08.03)#
The director and the critics are provider-independent — they take an
LLMProviderInterface and do not care what is behind it. That is the right
shape and also the hazard, because "any provider works" quietly becomes
"whichever provider is configured", and the provider that is always configured
is the one that charges. This check is written to decide, before a call,
whether a controller may take a duty at all.
Nothing routes through it yet. evaluateThreeDControllerAdmission and
routeThreeDController are exported and tested, and no production code calls
them: the director and the critics do not consult this check before they call
a controller today. What follows describes what the function decides when it
is asked, not a protection a running request has. Two things the evidence
record also leaves open: discovery against the local transports was never
reached, and no controller benchmark has been run through this path.
- Capabilities are discovered, never assumed. A listing carries
reachable; a modality the listing did not report isunreported, not false; and a modality inferred from a model's id is refused by name. The rule is written down because a neighbouring provider shows exactly what it prevents: it decides vision support from whether a model's name contains "vision" or "llava", asserts tool support for models it has never met, defaults the context window, and returns a checked-in model list when the server does not answer at all. Each of those is a guess wearing a listing's clothes. - Hosted off means hosted off. With hosted providers disabled, a need no
self-hosted controller reports is answered
unavailable, with the hosted controllers that could have served it listed as refused fallbacks. The failure this prevents is the silent one: a local profile that works in testing because a paid key happened to be in the environment. - Astra rides the subscription or it does not ride. By the owner's decision
of 2026-09-18, GPT-6 Astra is reached through the Codex CLI signed in with
ChatGPT and through nothing else. An Astra row on the OpenAI API or on
OpenRouter is refused at admission rather than at call time, and a Codex
run whose child environment carries
OPENAI_API_KEYorCODEX_API_KEYis refused too — a key in that environment moves Codex to API billing, the metered route the decision exists to forbid. - Routine harnesses stay cheap. Every harness binds the pinned cheap model through OpenRouter, so a harness duty on a frontier transport is refused here rather than left for a reviewer to notice.
6. Promoting a capability#
- Do the work, and record the evidence of the kind the next rung claims — an admission with 40-hex revisions and sha256s, a runtime path with file and line, a spec run with its command and pass count, a live render with its provider job id and output sha256, or a gate result per cell.
- Add that rung to the record's
ladder. The rung immediately below must already be there; the replay check enforces it. - Run the registry spec.
getThreeDCapabilityRegistryrefuses a registry whose ladder does not replay to the declared state, so a wrong claim fails a test rather than reaching the API. - Update
THREE_D_CAPABILITY_REGISTRY_AS_OFwhen a pass over the records re-establishes them against evidence.
Marking a capability unavailable needs a reason and at least one evidence
reference, and costs the ladder: re-entry is at candidate.