# Artifacts, revisions and scenes

What a delivered 3D artifact records about itself, how the registry keeps its
history so an accepted asset can be restored or branched without regenerating
it, and how a scene stores objects, instances, hierarchy and edits.

Code: `libs/isis/workflows/src/three-d-capabilities/artifact-manifest.ts` (the
manifest), `apps/isis/output-registry` — `services/asset-revisions.ts`, routes
under `/api/v1/assets` and `/api/v1/scenes` — and `@isis/3d-scene-assembly` (the
`isis.3d-scene` document). Tracker: T.04.01–T.04.04. Evidence:
`docs/agents/isis-3d-studio-evidence.md` §§ T.04.

## 1. The artifact manifest

One manifest describes **one delivered 3D artifact**. It is not the
reference-asset registry of T.01.05 (HDRIs and datasets with their rights,
covered in
[capability states and admission](./capability-states-and-admission.md) §5.3);
it is shared by the generation API, which builds it from the file's bytes, and
the output registry, which stores it.

`schema: isis.3d-artifact-manifest`, `version: 1`.

### 1.1 Every section says how it knows what it says

This is the manifest's whole design. Each section is one of three states:

| State        | Meaning                                                              |
| ------------ | -------------------------------------------------------------------- |
| `measured`   | Read from the artifact itself.                                       |
| `absent`     | The file was read and has none — no skin, no clip, no UVs.           |
| `unmeasured` | Nothing here can read that part of this format, **with the reason**. |

There is never a zero, an empty list or a guessed value in place of an
`unmeasured`. "We did not look" and "there is nothing there" are different
facts, and a consumer that cannot tell them apart will report a rig-less mesh
and a format nobody can parse identically.

The sections: `artifacts` (the delivery file with its format, MIME type, bytes
and sha256, plus embedded images), `format`, `representation` (triangle mesh,
lines, points or mixed primitives, from the primitive modes), `units`, `bounds`,
`dimensions`, `topology`, `materials`, `uvs`, `rigs`, `clips`, `lods`,
`collisions`, and `provenance`.

### 1.2 Two places the honesty is specific

**Material channels** distinguish three things a naive reader would collapse: a
value the file writes, glTF's specification default, and a channel the material
does not have at all.

**Real-world size is `unknown` unless a request declared one.** A generator's
output is in metres by the glTF convention — which is a convention, not a
measurement of any object. A declared size keeps its **basis**, so an `inferred`
size never reads as a measured one, and `compareDeclaredDimensions` compares a
declaration against the geometry's actual extents (turning a request's `+z`-up
frame onto glTF's `+Y` up) rather than trusting either alone.

### 1.3 Provenance

Every manifest names the `lane` that made it (`runpod`, `meshy`, `openrouter`,
`worker` or `upload`), the job id, the workflow id, the provider task id, each
input by **role and sha256**, and when it was built. Any of the ids may be null;
none of them may be invented.

**Not claimed:** only GLB is read today. UV and mesh-defect analysis is not in
the manifest.

## 2. Revisions

The output registry holds `asset_revisions`, `asset_heads` and
`asset_head_history`, with routes under `/api/v1/assets`.

A **revision** names:

- its **kind** — source/reference, generated, repaired or exported;
- the **output** holding its bytes, and their sha256;
- its **parent**;
- its **dependency hashes**;
- its **artifact manifest**, which is refused unless it describes those bytes;
- its **editable source**, kept apart from the delivery.

**A revision's identity is a hash over those facts**, so a repeat returns the
first one — concurrent repeats included. Repaired and exported revisions require
a parent.

### 2.1 Moving the head

Accepting a revision moves the head **against the head the caller last saw**. A
caller working from a stale view gets `409 revision_stale` rather than
overwriting newer work. Each move is recorded in the head history as `accepted`,
`branched` or `restored`.

### 2.2 Restore and branch without regenerating

**Restore works only for an accepted revision whose output is still stored with
its hash, and it creates nothing.** That is the point of the whole structure: an
accepted asset comes back from the registry, not from a second run of a paid
generator. A branch does the same for a divergent line of work.

### 2.3 An editable source is resolved on every read

A "we still have the editable `.blend`" claim decays silently: the file is
deleted, re-uploaded with different bytes, or one of its dependencies goes. So
the editable source and its dependencies are **resolved again on every read**,
and a deleted, re-hashed or missing file reads `broken` with `editable: false`.
The registry never reports an editable source it cannot currently produce.

**Not claimed:** no job writes revisions yet — the job-to-registry producer is
T.04.07, which itself waits on an owner decision about acting for a tenant's
owner. `.blend` dependencies are declared by the producer, not extracted from
the file. Output deletion is not yet blocked for accepted revisions (T.04.05).

## 3. Scenes

`@isis/3d-scene-assembly` defines the `isis.3d-scene` v1 document.

A node carries a **stable id**, a parent and sibling order, TRS with a **unit
quaternion**, and optionally an **asset-revision instance**, a glTF camera and a
`KHR_lights_punctual` light. Instancing is by revision, so the same accepted
asset appears many times without being copied.

`validateThreeDScene` lists — all of them, not the first — duplicate ids,
missing parents, cycles, order conflicts, non-unit rotations, zero scales,
impossible frusta and invalid lights. `worldMatrices` places nested nodes.

### 3.1 Canonical space, and conversion that states itself

Canonical space is glTF's: **metres, +Y up, front +Z, right −X.**

`canonicalAxisConversion` converts from another convention and **states when a
left-handed source is mirrored**, rather than quietly producing a scene that is
inside out. Its Blender, Unity and Unreal presets match those engines' own glTF
exporters' mappings.

This was worth building because the thing it replaced was wrong: the old import
normalizer returned an identity rotation for most axis pairs and sent a Z-up,
Y-forward front to −Z — and its spec asserted that behaviour. The conversion now
requires handedness, and all 48 axis combinations are asserted to compose
correctly.

### 3.2 Round trip

`exportThreeDSceneToGltf` and `importThreeDSceneFromGltf` keep ids, order and
instances in `extras.isis`, share one mesh per instanced revision, and **read
foreign files without inventing instances** — a glTF that Isis did not write
comes back as what it is, not as a scene pretending to have revision instances.

A binary glTF round trip of a nested room — instanced chairs, spot and point
lights, a camera — equals the original, with glTF-Transform's world matrices
agreeing for every node.

## 4. Editing a scene

Scene edits land through `/api/v1/scenes`, and the registry stores **every
revision's whole document** under a head row locked `FOR UPDATE`.

- **One revision or nothing.** Transforms, instances, material overrides,
  cameras, lights, animation bindings, renames, reparenting, adds and removes
  land as a single revision, each naming the revision it was made against.
- **Optimistic revision checks.** A stale edit is refused rather than applied on
  top of newer work.
- **Locks.** Object locks cover subtrees; region locks cover world origins
  **before and after** the edit, so moving something into a locked region is
  caught as well as moving something out of one. Both are expiring leases, and
  they are **held apart for a person and for their agent** (`X-Isis-Actor`) — an
  agent cannot take the lock its own operator is holding, and neither silently
  inherits the other's.
- **Undo, redo and restore write new revisions.** History is append-only;
  nothing is rewound in place, so undo restores geometry, materials, camera and
  animation together because it restores a document.

## 5. Steering, and what it costs

Steering a running 3D job stores the changed request under **its own revision**
and supersedes only the runs whose dependency hash no longer matches. Their jobs
stop and they start new attempts **that retry limits do not count** — a steered
re-run is the operator's change, not a failure. Everything else keeps its work.
The mechanism is in
[stage graphs, budgets and the sandbox](./stage-graph-budgets-and-sandbox.md)
§3.

Two defects this work found, both about attributing an event to the right
attempt: a cancelled stage job's callback used to cancel whatever attempt the
run was on — after a queue-timeout retry it cancelled attempt 2 — so the cancel
event now carries its job and its attempt; and a job created by a dispatch whose
run had already moved on is handled rather than left to confuse the run.

## 6. Where this sits

The registry and the scene document are **built and tested against live Postgres
and MinIO**, and nothing generates into them yet: every 3D capability is
`unavailable` or `candidate`. Reading this document as a description of a
working asset pipeline would be wrong. It describes the shape that pipeline will
have, and the parts of it that already refuse to lie.
