Eve library

Capability states and admission

Guide

Revision 9

On this page

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 unavailable moves a record down.
  • A record is valid only if replaying its ladder earns exactly its state. getThreeDCapabilityRegistry refuses 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 at admitted.
  • 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 on PATH.
  • 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) and classification.content (neutral | racy | explicit) — the same vocabulary and meaning as a catalog option's option_policy entry, which is what lets asset-lineage.ts carry 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 is unreported, 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_KEY or CODEX_API_KEY is 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#

  1. 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.
  2. Add that rung to the record's ladder. The rung immediately below must already be there; the replay check enforces it.
  3. Run the registry spec. getThreeDCapabilityRegistry refuses a registry whose ladder does not replay to the declared state, so a wrong claim fails a test rather than reaching the API.
  4. Update THREE_D_CAPABILITY_REGISTRY_AS_OF when 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.