# Capability states and admission

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](../adr/ADR-0008-open-3d-studio-capability-ownership.md).
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`](../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`.
