Eve library

Artifacts, revisions and scenes

Guide

Revision 1

On this page

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 §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 §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.