Skip to content

3D engine that AI agents drive

41.5 KB
Raw Blame
import './support/load-agent-scene-modules.mjs';
import test from 'node:test';
import assert from 'node:assert/strict';
import { Matrix4, Quaternion, Vector3 } from 'three';
import { createAgentScene, AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, REVISION_HISTORY_LIMIT } from '../src/agent-scene.js';
import * as lightweightCapabilities from '../src/agent-scene-capabilities.js';

test('the plain-data capabilities module matches the scene engine', () => {
  const scene = createAgentScene({ format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [] });
  assert.deepEqual(scene.limits, lightweightCapabilities.AGENT_SCENE_DEFAULT_LIMITS);
  assert.equal(AGENT_SCENE_DEFAULT_LIMITS, lightweightCapabilities.AGENT_SCENE_DEFAULT_LIMITS);
  assert.equal(AGENT_SCENE_CAPABILITIES, lightweightCapabilities.AGENT_SCENE_CAPABILITIES);
  assert.equal(scene.capabilities, lightweightCapabilities.AGENT_SCENE_CAPABILITIES);
});

function recipe() {
  return { format: 'crucible.scene', schemaVersion: 1,
    geometries: [{ id: 'box', type: 'box', bevel: 0 }],
    materials: [{ id: 'finish', color: [0.2, 0.4, 0.6] }],
    nodes: [{ id: 'child', parent: 'root', geometry: 'box', material: 'finish', translation: [1, 2, 0] },
      { id: 'root', label: 'Same label', translation: [3, 0, 0] },
      { id: 'other', label: 'Same label', geometry: 'box', material: 'finish' }] };
}

test('authored look patches preserve resources and undo light, fog, exposure and projector together', () => {
  const session = createAgentScene(recipe());
  const before = session.exportRecipe();
  const parts = session.parts;
  const checkpoint = session.checkpoint();
  session.apply([
    { type: 'set-environment', environment: { world: true, lightDirection: [0, 1, 0], pointLights: [{ position: [1, 2, 3], intensity: 12 }], volumeFog: { density: 0.2 } } },
    { type: 'set-effects', effects: { exposure: 0.8, bloom: { strength: 0.3 } } },
    { type: 'set-shadow', shadow: { extent: 10, far: 40 } },
  ], { expectedRevision: 0 });
  assert.equal(session.parts, parts);
  assert.equal(session.topologyRevision, 0);
  assert.equal(session.environment.volumeFog.density, 0.2);
  assert.deepEqual(session.environment.volumeFog.minimum, before.environment.volumeFog.minimum);
  assert.equal(session.effects.bloom.threshold, before.effects.bloom.threshold);
  const detached = session.environment;
  detached.pointLights[0].position[0] = 999;
  assert.equal(session.environment.pointLights[0].position[0], 1);
  session.apply([{ type: 'set-environment', environment: { pointLights: [] } }], { expectedRevision: 1 });
  assert.equal(session.environment.pointLights.length, 0);
  session.restore(checkpoint, { expectedRevision: 2 });
  assert.deepEqual(session.exportRecipe(), before);
  assert.equal(session.parts, parts);
  assert.equal(session.topologyRevision, 0);
});

test('invalid look in a mixed batch cannot publish transforms, material or render controls', () => {
  const session = createAgentScene(recipe());
  const before = session.exportRecipe();
  const matrix = Array.from(session.parts[0].matrix);
  for (const invalid of [
    { type: 'set-environment', environment: { lightDirection: [0, 0, 0] } },
    { type: 'set-effects', effects: { bloom: { unknown: 1 } } },
    { type: 'set-shadow', shadow: { near: 15, far: 1 } },
  ]) {
    assert.throws(() => session.apply([
      { type: 'set-node', id: 'child', translation: [9, 8, 7] },
      { type: 'set-material', id: 'finish', color: [1, 0, 0] },
      { type: 'set-effects', effects: { exposure: 2 } }, invalid,
    ], { expectedRevision: 0 }));
    assert.equal(session.revision, 0);
    assert.deepEqual(session.exportRecipe(), before);
    assert.deepEqual(Array.from(session.parts[0].matrix), matrix);
  }
});

test('shader arithmetic rejects cancelling product overflow and nonfinite emission atomically', () => {
  const input = recipe();
  const coordinate = Math.fround(1e20);
  const nextCoordinate = Math.fround(coordinate + 1e14);
  input.geometries = [{ id: 'box', type: 'extrude', depth: 1,
    contour: [[coordinate, coordinate], [nextCoordinate, coordinate], [nextCoordinate, nextCoordinate], [coordinate, nextCoordinate]] }];
  input.nodes = [
    { id: 'root' },
    { id: 'child', parent: 'root', geometry: 'box', material: 'finish', rotation: [0, 0, Math.sin(Math.PI / 8), Math.cos(Math.PI / 8)] },
  ];
  const session = createAgentScene(input);
  const before = session.exportRecipe();
  const matrix = Array.from(session.parts[0].matrix);
  assert.throws(() => session.apply([{ type: 'set-node', id: 'root', scale: [1e20, 1e-20, 1] }], { expectedRevision: 0 }), /world geometry bounds/);
  assert.throws(() => session.apply([{ type: 'set-material', id: 'finish', emission: 1e30, emissiveColor: [1e30, 0, 0] }], { expectedRevision: 0 }), /materials\[0\]\.emission: got 1e\+30; expected an emission that keeps color times emission within Float32 range/);
  assert.deepEqual(session.exportRecipe(), before);
  assert.deepEqual(Array.from(session.parts[0].matrix), matrix);
  assert.equal(session.revision, 0);
  input.materials[0].tag = 'unlit';
  input.materials[0].emission = 70000;
  input.materials[0].emissiveColor = [1, 0, 0];
  assert.throws(() => createAgentScene(input), /materials\[0\]\.emission: got 70000; expected an unlit emission that keeps color times emission at or below 65500/);
});

test('recipes author liquid, foam and blended glass with batch-safe material handles', () => {
  assert.deepEqual(AGENT_SCENE_CAPABILITIES.materialTags, ['surface', 'unlit', 'liquid', 'foam', 'foliage', 'grass', 'water']);
  const input = recipe();
  input.materials.push({ id: 'water', tag: 'liquid', color: [0.56, 0.84, 0.88], roughness: 0.05 });
  input.materials.push({ id: 'glass', color: [0.9, 0.95, 1], opacity: 0.3, doubleSided: true });
  input.environment = { liquid: { thickness: 0.8 } };
  const session = createAgentScene(input);
  const exported = session.exportRecipe();
  const glass = exported.materials.find(material => material.id === 'glass');
  assert.equal(glass.alphaMode, 'blend', 'opacity below one opts into blending');
  assert.equal(glass.doubleSided, true);
  assert.equal(exported.materials.find(material => material.id === 'finish').alphaMode, 'opaque');
  assert.equal(session.environment.liquid.thickness, 0.8);
  assert.equal(session.environment.liquid.ior, 1.33);
  const finishMaterial = session.parts.find(part => part.name === 'child').material;
  session.apply([{ type: 'set-material', id: 'finish', color: [1, 0, 0] }], { expectedRevision: 0 });
  assert.equal(session.parts.find(part => part.name === 'child').material, finishMaterial, 'a color edit keeps the batch');
  session.apply([{ type: 'set-material', id: 'finish', opacity: 0.5 }], { expectedRevision: 1 });
  const blended = session.parts.find(part => part.name === 'child').material;
  assert.notEqual(blended, finishMaterial, 'blending changes the batch, so the part is replaced');
  assert.equal(blended.alphaMode, 'blend');
  assert.throws(() => session.apply([{ type: 'set-material', id: 'finish', alphaMode: 'mask' }], { expectedRevision: 2 }), /alphaMode/);
  assert.throws(() => session.apply([{ type: 'set-environment', environment: { liquid: { ior: 9 } } }], { expectedRevision: 2 }), /liquid\.ior/);
  assert.throws(() => session.apply([{ type: 'set-environment', environment: { liquid: { depth: 1 } } }], { expectedRevision: 2 }), /Unknown liquid/);
});

test('trailing sparse array holes reject recipes and command batches without commit', () => {
  const input = recipe();
  input.nodes.length++;
  assert.throws(() => createAgentScene(input), /trailing holes/);
  const session = createAgentScene(recipe());
  const before = session.exportRecipe();
  const operations = [{ type: 'set-node', id: 'root', translation: [2, 0, 0] }];
  operations.length++;
  assert.throws(() => session.apply(operations, { expectedRevision: 0 }), /trailing holes/);
  assert.deepEqual(session.exportRecipe(), before);
  assert.equal(session.revision, 0);
});

test('shared resources and retained renderer identities survive apply and restore', () => {
  const input = recipe();
  const session = createAgentScene(input);
  input.nodes[1].translation[0] = 100;
  const parts = session.parts;
  const identities = parts.map(part => [part, part.matrix, part.geometry, part.material]);
  assert.equal(parts[0].geometry, parts[1].geometry);
  assert.equal(parts[0].material, parts[1].material);
  assert.equal(parts[0].matrix[12], 4);
  assert.equal(session.capabilities, AGENT_SCENE_CAPABILITIES);
  const checkpoint = session.checkpoint();
  assert.equal(session.apply([{ type: 'set-node', id: 'root', translation: [7, 0, 0] },
    { type: 'set-material', id: 'finish', color: [1, 0, 0], emission: 2 }], { expectedRevision: 0 }), 1);
  assert.equal(parts[0].matrix[12], 8);
  assert.deepEqual(parts[1].material.color, [1, 0, 0]);
  session.restore(checkpoint, { expectedRevision: 1 });
  assert.equal(session.revision, 2);
  assert.equal(parts[0].matrix[12], 4);
  assert.deepEqual(parts[0].material.color, [0.2, 0.4, 0.6]);
  parts.forEach((part, index) => {
    [part, part.matrix, part.geometry, part.material].forEach((value, component) => {
      assert.equal(value, identities[index][component]);
    });
  });
  assert.equal(parts[0].material.color, parts[0].material.color);
  assert.equal(session.parts, parts);
  const inspection = session.inspect();
  assert.equal(inspection.counts.vertices, 24);
  assert.equal(inspection.geometryBytes, 720);
});

test('transactions reject conflicts and invalid late commands without publishing any changes', () => {
  const session = createAgentScene(recipe());
  const before = session.exportRecipe();
  const matrix = Array.from(session.parts[0].matrix);
  const invalidCommands = [
    { type: 'set-node', id: 'root', parent: 'child' },
    { type: 'set-node', id: 'child', parent: 'missing' },
    { type: 'set-node', id: 'child', scale: [0, 1, 1] },
    { type: 'set-node', id: 'child', rotation: [0, 0, 0, 0] },
    { type: 'set-material', id: 'finish', roughness: 2 },
    { type: 'set-camera', eye: [0, 0, 0], target: [0, 0, 0] },
    { type: 'set-camera', near: 10, far: 1 },
    { type: 'set-node', id: 'child', surprise: true },
    { type: 'set-node', id: 'child', translation: null },
  ];
  for (const command of invalidCommands) {
    assert.throws(() => session.apply([{ type: 'set-node', id: 'root', translation: [9, 0, 0] }, command], { expectedRevision: 0 }));
    assert.deepEqual(session.exportRecipe(), before);
    assert.deepEqual(Array.from(session.parts[0].matrix), matrix);
    assert.equal(session.revision, 0);
  }
  assert.throws(() => session.apply([{ type: 'set-camera', fov: 60 }]));
  assert.throws(() => session.apply([{ type: 'set-camera', fov: 60 }], { expectedRevision: 1 }));
  session.apply([{ type: 'set-camera', fov: 60 }], { expectedRevision: 0 });
  assert.equal(session.camera.fov, 60);
});

test('hierarchy and actual vertex bounds agree with an independent double precision transform', () => {
  const input = recipe();
  const rotation = [0, 0, Math.sin(Math.PI / 8) * 2, Math.cos(Math.PI / 8) * 2];
  input.nodes[1].rotation = rotation;
  input.nodes[1].scale = [2, 3, 4];
  input.nodes[0].scale = [0.5, 1.5, 0.75];
  const session = createAgentScene(input);
  const root = new Matrix4().compose(new Vector3(3, 0, 0), new Quaternion(...rotation).normalize(), new Vector3(2, 3, 4));
  const child = new Matrix4().compose(new Vector3(1, 2, 0), new Quaternion(), new Vector3(0.5, 1.5, 0.75));
  const world = root.multiply(child);
  const minimum = [Infinity, Infinity, Infinity];
  const maximum = [-Infinity, -Infinity, -Infinity];
  for (const x of [-0.5, 0.5]) {
    for (const y of [-0.5, 0.5]) {
      for (const z of [-0.5, 0.5]) {
        const point = new Vector3(x, y, z).applyMatrix4(world).toArray();
        for (let axis = 0; axis < 3; axis++) {
          minimum[axis] = Math.min(minimum[axis], point[axis]);
          maximum[axis] = Math.max(maximum[axis], point[axis]);
        }
      }
    }
  }
  const actual = session.inspect({ ids: ['child'], includeBounds: true }).nodes[0].bounds;
  for (let axis = 0; axis < 3; axis++) {
    assert.ok(Math.abs(actual.min[axis] - minimum[axis]) < 1e-5);
    assert.ok(Math.abs(actual.max[axis] - maximum[axis]) < 1e-5);
  }
  session.parts[0].matrix.fill(NaN);
  assert.deepEqual(session.inspect({ ids: ['child'], includeBounds: true }).nodes[0].bounds, actual);
  const exported = session.exportRecipe();
  exported.nodes[0].translation[0] = 999;
  const camera = session.camera;
  camera.eye[0] = 999;
  session.apply([{ type: 'set-node', id: 'child', label: 'Renamed' }], { expectedRevision: 0 });
  assert.ok(session.parts[0].matrix.every(Number.isFinite));
  assert.equal(session.inspect({ ids: ['child'] }).nodes[0].label, 'Renamed');
  assert.equal(session.parts[0].name, 'child');
});

test('depth and world overflow checks reject an entire candidate and allow recovery', () => {
  const session = createAgentScene(recipe(), { maxDepth: 2 });
  assert.throws(() => session.apply([{ type: 'set-node', id: 'other', parent: 'child' }], { expectedRevision: 0 }), /maxDepth/);
  assert.throws(() => session.apply([{ type: 'set-node', id: 'root', scale: [1e30, 1e30, 1e30] },
    { type: 'set-node', id: 'child', scale: [1e30, 1e30, 1e30] }], { expectedRevision: 0 }), /finite Float32/);
  assert.equal(session.revision, 0);
  session.apply([{ type: 'set-node', id: 'other', parent: 'root' }], { expectedRevision: 0 });
  assert.equal(session.inspect({ ids: ['other'] }).nodes[0].parent, 'root');
});

test('checkpoints are private, bounded, session-specific and releaseable', () => {
  const session = createAgentScene(recipe(), { maxCheckpoints: 1 });
  const checkpoint = session.checkpoint();
  assert.ok(Object.isFrozen(checkpoint));
  assert.throws(() => session.checkpoint(), /checkpoints: got "1 saved"; expected at most 1 saved checkpoints/);
  const foreign = createAgentScene(recipe()).checkpoint();
  assert.throws(() => session.restore(foreign, { expectedRevision: 0 }), /checkpointId: got \{\}; expected a checkpointId that scene_checkpoint returned/);
  assert.throws(() => session.releaseCheckpoint(foreign), /checkpointId: got \{\}; expected a checkpointId that scene_checkpoint returned/);
  session.apply([{ type: 'set-node', id: 'root', translation: [8, 0, 0] }], { expectedRevision: 0 });
  assert.throws(() => session.restore(checkpoint, { expectedRevision: 0 }), /expectedRevision/);
  session.restore(checkpoint, { expectedRevision: 1 });
  session.releaseCheckpoint(checkpoint);
  assert.throws(() => session.restore(checkpoint, { expectedRevision: 2 }), /checkpointId: got \{\}; .*you have not released/);
  assert.throws(() => session.releaseCheckpoint(checkpoint), /checkpointId: got \{\}; .*you have not released/);
  assert.ok(session.checkpoint());
});

test('camera supports explicit top views and rejects degenerate or collapsed projection ranges', () => {
  const session = createAgentScene(recipe());
  for (const camera of [{ eye: [0, 3, 0], target: [0, 0, 0] }, { up: [0, 0, 0] },
    { near: 1e-100 }, { near: 1, far: 1 + 1e-10 }, { fov: 1e-40 }]) {
    assert.throws(() => session.apply([{ type: 'set-camera', ...camera }], { expectedRevision: 0 }));
    assert.equal(session.revision, 0);
  }
  session.apply([{ type: 'set-camera', eye: [0, 3, 0], target: [0, 0, 0], up: [0, 0, -2] }], { expectedRevision: 0 });
  assert.deepEqual(session.camera.up, [0, 0, -1]);
});

test('finite matrices still reject world geometry overflow using cached local bounds', () => {
  const input = recipe();
  input.geometries = [{ id: 'box', type: 'lathe', profile: [[1e30, -1], [1e30, 1]], segments: 8 }];
  const session = createAgentScene(input);
  const before = session.exportRecipe();
  assert.throws(() => session.apply([{ type: 'set-node', id: 'child', scale: [1e30, 1, 1] }], { expectedRevision: 0 }), /world geometry/);
  assert.deepEqual(session.exportRecipe(), before);
  assert.equal(session.revision, 0);
});

test('recipe boundary rejects malformed JSON, unknown keys and oversized geometry before generation', () => {
  assert.throws(() => createAgentScene({ ...recipe(), eval: 'code' }), /recipe\.eval: got "code"; expected one of the fields format/);
  assert.throws(() => createAgentScene(recipe(), { maxNodes: 4097 }), /4096/);
  assert.throws(() => createAgentScene(recipe(), { maxRecipeBytes: 100 }), /maxRecipeBytes/);
  assert.throws(() => createAgentScene(recipe(), { maxGeometryBytes: 100 }), /preflight/);
  const huge = recipe();
  huge.geometries = [{ id: 'box', type: 'sphere', segments: 2048, rings: 2048 }];
  assert.throws(() => createAgentScene(huge), /preflight/);
  const cyclic = recipe();
  cyclic.camera = cyclic;
  assert.throws(() => createAgentScene(cyclic), /acyclic/);
  const accessor = recipe();
  Object.defineProperty(accessor, 'camera', {
    enumerable: true,
    get() {
      throw new Error('must not execute');
    },
  });
  assert.throws(() => createAgentScene(accessor), /accessors/);
  const bad = recipe();
  bad.nodes[0].rotation = [0, 0, NaN, 1];
  assert.throws(() => createAgentScene(bad), /JSON/);
});

test('command and resource budgets, bounded inspection and missing IDs report failures', () => {
  assert.throws(() => createAgentScene(recipe(), { maxNodes: 2 }), /nodes: got "3 entries"; expected an array of at most 2 entries/);
  const extra = recipe();
  extra.geometries.push({ id: 'sphere', type: 'sphere', segments: 8, rings: 4 });
  assert.throws(() => createAgentScene(extra, { maxGeometries: 1 }), /geometries: got "2 entries"; expected an array of at most 1 entries/);
  const duplicate = recipe();
  duplicate.nodes[2].id = 'root';
  assert.throws(() => createAgentScene(duplicate), /nodes\[2\]\.id: got "root"; expected an ID no other nodes entry uses/);
  const session = createAgentScene(recipe(), { maxOperations: 1 });
  assert.throws(() => session.apply([{ type: 'set-camera', fov: 60 }, { type: 'set-camera', fov: 70 }], { expectedRevision: 0 }), /operations: got "2 operations"; expected a list of 1 to 1 operations/);
  assert.throws(() => session.apply([], { expectedRevision: 0 }), /operations: got "0 operations"; expected a list of 1 to 1 operations/);
  const inspection = session.inspect({ limit: 1 });
  assert.equal(inspection.nodes.length, 1);
  assert.equal(inspection.truncated, true);
  assert.equal(inspection.counts.nodes, 3);
  assert.throws(() => session.inspect({ ids: ['missing'] }), /ids: got "missing"; expected IDs of existing nodes/);
  assert.throws(() => session.inspect({ includeBounds: 'yes' }), /includeBounds: got "yes"; expected true or false/);
  assert.equal(session.revision, 0);
});

test('detached privileged adapter matrices cannot partially publish a transaction', () => {
  const session = createAgentScene(recipe());
  const before = session.exportRecipe();
  const checkpoint = session.checkpoint();
  structuredClone(session.parts[1].matrix.buffer, { transfer: [session.parts[1].matrix.buffer] });
  assert.throws(() => session.apply([{ type: 'set-node', id: 'root', translation: [10, 0, 0] },
    { type: 'set-material', id: 'finish', color: [1, 0, 0] }], { expectedRevision: 0 }), /detached/);
  assert.equal(session.revision, 0);
  assert.deepEqual(session.exportRecipe(), before);
  assert.deepEqual(session.parts[0].material.color, [0.2, 0.4, 0.6]);
  assert.equal(session.parts[0].matrix[12], 4);
  assert.throws(() => session.restore(checkpoint, { expectedRevision: 0 }), /detached/);
  assert.equal(session.revision, 0);
});

test('all seven generators remain within conservative aggregate vertex and byte estimates', () => {
  const input = { format: 'crucible.scene', schemaVersion: 1, materials: [{ id: 'material' }], nodes: [], geometries: [
    { id: 'box', type: 'box', subdivisions: 2 },
    { id: 'cylinder', type: 'cylinder', segments: 8, bevelSegments: 2 },
    { id: 'sphere', type: 'sphere', segments: 8, rings: 4 },
    { id: 'torus', type: 'torus', segments: 8, sides: 4, arc: Math.PI },
    { id: 'lathe', type: 'lathe', profile: [[0.5, -1], [1, 0], [0.5, 1]], segments: 8 },
    { id: 'extrude', type: 'extrude', contour: [[0, 0], [1, 0], [1, 1], [0, 1]], depth: 0.5 },
    { id: 'tube', type: 'tube', path: [[0, 0, 0], [0, 1, 0], [1, 2, 0]], segments: 8, radialSegments: 4 },
  ] };
  input.nodes = input.geometries.map(geometry => ({ id: geometry.id, geometry: geometry.id, material: 'material' }));
  const session = createAgentScene(input);
  const inspection = session.inspect({ includeBounds: true });
  assert.equal(inspection.counts.geometries, 7);
  assert.ok(inspection.geometryBytes <= inspection.estimatedGeometryBytes);
  assert.ok(inspection.nodes.every(node => node.bounds.min.every(Number.isFinite)));
  assert.deepEqual(createAgentScene(session.exportRecipe()).inspect(), session.inspect());
  const originalBox = session.parts[0];
  session.apply([{ type: 'set-node', id: 'box', geometry: 'sphere' }], { expectedRevision: 0 });
  assert.notEqual(session.parts[0], originalBox);
  assert.equal(session.parts[0].geometry, session.parts[2].geometry);
  assert.equal(session.topologyRevision, 1);
  assert.throws(() => session.apply([{ type: 'set-material', id: 'material', tag: 'unlit' }], { expectedRevision: 1 }), /operation\.tag: got "unlit"; expected one of the fields type, id/);
});

function emptyRecipe() {
  return { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [] };
}

test('topology can grow from an empty session while sharing resources and preserving existing part identities', () => {
  const session = createAgentScene(emptyRecipe());
  const emptyParts = session.parts;
  assert.equal(session.topologyRevision, 0);
  assert.equal(session.capabilities.fixedResources, false);
  assert.equal(session.capabilities.dynamicTopology, true);
  session.apply([
    { type: 'add-node', node: { id: 'first', parent: 'group', geometry: 'cube', material: 'red' } },
    { type: 'add-node', node: { id: 'group' } },
    { type: 'add-material', material: { id: 'red', color: [1, 0, 0] } },
    { type: 'add-geometry', geometry: { id: 'cube', type: 'box', bevel: 0 } },
  ], { expectedRevision: 0 });
  assert.notEqual(session.parts, emptyParts);
  assert.equal(session.revision, 1);
  assert.equal(session.topologyRevision, 1);
  const first = session.parts[0];
  session.apply([{ type: 'add-node', node: { id: 'second', geometry: 'cube', material: 'red' } }], { expectedRevision: 1 });
  assert.equal(session.parts[0], first);
  assert.equal(session.parts[1].geometry, first.geometry);
  assert.equal(session.parts[1].material, first.material);
  assert.equal(session.topologyRevision, 2);
  const retainedList = session.parts;
  session.apply([
    { type: 'set-node', id: 'group', translation: [3, 0, 0] },
    { type: 'set-material', id: 'red', roughness: 0.2 },
    { type: 'set-camera', fov: 60 },
    { type: 'add-node', node: { id: 'unused-group' } },
  ], { expectedRevision: 2 });
  assert.equal(session.parts, retainedList);
  assert.equal(first.matrix[12], 3);
  assert.equal(first.material.roughness, 0.2);
  assert.equal(session.topologyRevision, 2);
});

test('topology failures roll back recipes, geometry, materials, matrices and both revisions', () => {
  const session = createAgentScene(recipe());
  const before = session.exportRecipe();
  const parts = session.parts;
  const matrices = parts.map(part => Array.from(part.matrix));
  const invalidBatches = [
    [{ type: 'remove-geometry', id: 'box' }],
    [{ type: 'remove-material', id: 'finish' }],
    [{ type: 'add-node', node: { id: 'cycle', parent: 'child' } }, { type: 'set-node', id: 'root', parent: 'cycle' }],
    [{ type: 'add-node', node: { id: 'mesh', geometry: 'box' } }],
    [{ type: 'add-node', node: { id: 'mesh', geometry: 'missing', material: 'finish' } }],
    [{ type: 'add-node', node: { id: 'mesh', parent: 'missing' } }],
    [{ type: 'add-geometry', geometry: { id: 'box', type: 'sphere' } }],
    [{ type: 'add-material', material: { id: 'finish' } }],
    [{ type: 'add-node', node: { id: 'root' } }],
    [{ type: 'remove-node', id: 'missing' }],
    [{ type: 'remove-geometry', id: 'missing' }],
    [{ type: 'remove-material', id: 'missing' }],
    [{ type: 'add-geometry', geometry: { id: 'invalid', type: 'box', bevel: 2 } }],
    [{ type: 'add-material', material: { id: 'invalid', roughness: 2 } }],
    [{ type: 'add-geometry', geometry: { id: 'huge', type: 'sphere', segments: 2048, rings: 2048 } }],
    [{ type: 'remove-node', id: 'root', recursive: 'true' }],
    [{ type: 'remove-node', id: 'other', extra: true }],
    [{ type: 'add-node', node: { id: 'mesh' }, extra: true }],
    [{ type: 'add-node', node: { id: 'mesh', extra: true } }],
  ];
  for (const operations of invalidBatches) {
    assert.throws(() => session.apply([
      { type: 'set-material', id: 'finish', color: [1, 0, 0] },
      { type: 'set-node', id: 'root', translation: [8, 0, 0] },
      ...operations,
    ], { expectedRevision: 0 }));
    assert.deepEqual(session.exportRecipe(), before);
    assert.equal(session.parts, parts);
    assert.deepEqual(parts.map(part => Array.from(part.matrix)), matrices);
    assert.deepEqual(parts[0].material.color, [0.2, 0.4, 0.6]);
    assert.equal(session.revision, 0);
    assert.equal(session.topologyRevision, 0);
  }
  session.apply([{ type: 'remove-node', id: 'other' }], { expectedRevision: 0 });
  assert.equal(session.parts[0], parts[0]);
  assert.equal(session.topologyRevision, 1);
});

test('node deletion distinguishes nonrecursive rejection from explicit subtree removal', () => {
  const input = recipe();
  input.nodes.push({ id: 'grandchild', parent: 'child', geometry: 'box', material: 'finish' });
  const session = createAgentScene(input);
  assert.throws(() => session.apply([
    { type: 'remove-node', id: 'root' }, { type: 'remove-node', id: 'child', recursive: true },
  ], { expectedRevision: 0 }), /recursive: got false; expected true for a node with children/);
  session.apply([{ type: 'remove-node', id: 'root', recursive: true }], { expectedRevision: 0 });
  assert.deepEqual(session.exportRecipe().nodes.map(node => node.id), ['other']);
  assert.deepEqual(session.parts.map(part => part.name), ['other']);
  assert.equal(session.inspect().counts.geometries, 1);
  session.apply([
    { type: 'remove-node', id: 'other' },
    { type: 'remove-material', id: 'finish' },
    { type: 'remove-geometry', id: 'box' },
  ], { expectedRevision: 1 });
  assert.equal(session.parts.length, 0);
  assert.equal(session.inspect().geometryBytes, 0);
  assert.equal(session.inspect().residentGeometryBytes, 720, 'the kept earlier revisions still own the removed geometry');
});

test('resource removal and node rebinding resolve final references after sequential commands', () => {
  const session = createAgentScene(recipe());
  const oldParts = session.parts;
  session.apply([
    { type: 'remove-geometry', id: 'box' },
    { type: 'remove-material', id: 'finish' },
    { type: 'add-geometry', geometry: { id: 'sphere', type: 'sphere', segments: 8, rings: 4 } },
    { type: 'add-material', material: { id: 'green', color: [0, 1, 0] } },
    { type: 'set-node', id: 'child', geometry: 'sphere', material: 'green' },
    { type: 'set-node', id: 'other', geometry: 'sphere', material: 'green' },
  ], { expectedRevision: 0 });
  assert.notEqual(session.parts[0], oldParts[0]);
  assert.notEqual(session.parts[0].matrix, oldParts[0].matrix);
  assert.equal(session.parts[0].geometry, session.parts[1].geometry);
  assert.equal(session.parts[0].material, session.parts[1].material);
  assert.equal(session.topologyRevision, 1);
  assert.deepEqual(oldParts[0].material.color, [0.2, 0.4, 0.6]);
  session.apply([{ type: 'set-node', id: 'root', geometry: 'sphere', material: 'green' }], { expectedRevision: 1 });
  assert.equal(session.parts.length, 3);
  assert.equal(session.parts[0].name, 'child');
});

test('unchanged definitions reuse geometry while changed definitions replace bound parts', () => {
  const session = createAgentScene(recipe());
  const originalParts = session.parts;
  session.apply([
    { type: 'remove-geometry', id: 'box' },
    { type: 'add-geometry', geometry: { bevel: 0, type: 'box', id: 'box' } },
  ], { expectedRevision: 0 });
  assert.equal(session.parts, originalParts);
  assert.equal(session.topologyRevision, 0);
  session.apply([
    { type: 'remove-geometry', id: 'box' },
    { type: 'add-geometry', geometry: { id: 'box', type: 'sphere', segments: 8, rings: 4 } },
  ], { expectedRevision: 1 });
  assert.notEqual(session.parts[0].geometry, originalParts[0].geometry);
  assert.notEqual(session.parts[0], originalParts[0]);
  assert.equal(session.parts[0].geometry, session.parts[1].geometry);
  assert.equal(session.topologyRevision, 1);
});

test('checkpoints restore removed geometry and parts with bounded private retained identities', () => {
  const session = createAgentScene(recipe());
  const originalParts = session.parts;
  const checkpoint = session.checkpoint();
  session.apply([
    { type: 'remove-node', id: 'root', recursive: true },
    { type: 'remove-node', id: 'other' },
    { type: 'remove-geometry', id: 'box' },
    { type: 'remove-material', id: 'finish' },
  ], { expectedRevision: 0 });
  assert.equal(session.parts.length, 0);
  assert.equal(session.inspect().geometryBytes, 0);
  assert.equal(session.inspect().residentGeometryBytes, 720);
  session.restore(checkpoint, { expectedRevision: 1 });
  assert.equal(session.parts[0], originalParts[0]);
  assert.equal(session.parts[1], originalParts[1]);
  assert.equal(session.topologyRevision, 2);
  const restoredList = session.parts;
  session.restore(checkpoint, { expectedRevision: 2 });
  assert.equal(session.parts, restoredList);
  assert.equal(session.topologyRevision, 2);
  session.releaseCheckpoint(checkpoint);
  assert.equal(session.inspect().residentGeometryBytes, 720);
});

test('peak geometry budgets count checkpoint ownership and free it on release', () => {
  const session = createAgentScene(recipe(), { maxVertices: 24, maxGeometryBytes: 1344 });
  const originalParts = session.parts;
  const firstCheckpoint = session.checkpoint();
  const secondCheckpoint = session.checkpoint();
  assert.equal(session.inspect().residentGeometryVertices, 24);
  session.apply([
    { type: 'remove-node', id: 'root', recursive: true }, { type: 'remove-node', id: 'other' },
    { type: 'remove-geometry', id: 'box' }, { type: 'remove-material', id: 'finish' },
  ], { expectedRevision: 0 });
  const add = [{ type: 'add-geometry', geometry: { id: 'new', type: 'box', bevel: 0 } }];
  assert.throws(() => session.apply(add, { expectedRevision: 1 }), /peak/);
  assert.equal(session.revision, 1);
  session.releaseCheckpoint(firstCheckpoint);
  assert.throws(() => session.apply(add, { expectedRevision: 1 }), /peak/);
  session.restore(secondCheckpoint, { expectedRevision: 1 });
  assert.equal(session.parts[0], originalParts[0]);
  session.apply([
    { type: 'remove-node', id: 'root', recursive: true }, { type: 'remove-node', id: 'other' },
    { type: 'remove-geometry', id: 'box' }, { type: 'remove-material', id: 'finish' },
  ], { expectedRevision: 2 });
  session.releaseCheckpoint(secondCheckpoint);
  // Kept revisions still own the box; an edit that needs the room drops them oldest first.
  assert.equal(session.inspect().residentGeometryBytes, 720);
  session.apply(add, { expectedRevision: 3 });
  assert.equal(session.inspect().geometryBytes, 720);
  assert.equal(session.topologyRevision, 3);
});

test('atomic replacement budgets include old active resources until commit', () => {
  const session = createAgentScene(recipe(), { maxGeometryBytes: 1344 });
  assert.throws(() => session.apply([
    { type: 'remove-geometry', id: 'box' },
    { type: 'add-geometry', geometry: { id: 'box', type: 'box', bevel: 0, subdivisions: 1 } },
  ], { expectedRevision: 0 }), /peak/);
  assert.equal(session.revision, 0);
  assert.equal(session.topologyRevision, 0);
  assert.equal(session.inspect().geometryBytes, 720);
});

test('new topology enforces world geometry overflow and depth before publishing', () => {
  const session = createAgentScene(emptyRecipe(), { maxDepth: 1 });
  const emptyParts = session.parts;
  assert.throws(() => session.apply([
    { type: 'add-node', node: { id: 'root' } },
    { type: 'add-node', node: { id: 'child', parent: 'root' } },
  ], { expectedRevision: 0 }), /maxDepth/);
  assert.throws(() => session.apply([
    { type: 'add-geometry', geometry: { id: 'huge', type: 'lathe', profile: [[1e30, -1], [1e30, 1]], segments: 8 } },
    { type: 'add-material', material: { id: 'finish' } },
    { type: 'add-node', node: { id: 'mesh', geometry: 'huge', material: 'finish', scale: [1e30, 1, 1] } },
  ], { expectedRevision: 0 }), /world geometry bounds/);
  assert.equal(session.parts, emptyParts);
  assert.equal(session.revision, 0);
  assert.equal(session.topologyRevision, 0);
});

test('topology rejects stale revisions and detached active or checkpoint matrices atomically', () => {
  const session = createAgentScene(recipe());
  const checkpoint = session.checkpoint();
  const oldParts = session.parts;
  session.apply([{ type: 'remove-node', id: 'other' }], { expectedRevision: 0 });
  assert.throws(() => session.apply([{ type: 'remove-node', id: 'child' }], { expectedRevision: 0 }), /expectedRevision/);
  structuredClone(oldParts[1].matrix.buffer, { transfer: [oldParts[1].matrix.buffer] });
  const before = session.exportRecipe();
  const parts = session.parts;
  assert.throws(() => session.restore(checkpoint, { expectedRevision: 1 }), /detached/);
  assert.deepEqual(session.exportRecipe(), before);
  assert.equal(session.parts, parts);
  assert.equal(session.topologyRevision, 1);
  structuredClone(parts[0].matrix.buffer, { transfer: [parts[0].matrix.buffer] });
  assert.throws(() => session.apply([{ type: 'remove-node', id: 'child' }], { expectedRevision: 1 }), /detached/);
  assert.deepEqual(session.exportRecipe(), before);
  assert.equal(session.revision, 1);
});

test('a node with a geometry and no material gets an explicit default material, deterministically', () => {
  const input = recipe();
  delete input.nodes[0].material;
  const first = createAgentScene(input).exportRecipe();
  const second = createAgentScene(input).exportRecipe();
  assert.deepEqual(first, second);
  assert.equal(first.nodes.find(node => node.id === 'child').material, 'default');
  assert.deepEqual(first.materials.map(material => material.id), ['finish', 'default']);
  assert.deepEqual(createAgentScene(first).exportRecipe(), first);
});

test('an existing default material is reused and a node with only a material still names the fix', () => {
  const input = recipe();
  input.materials.push({ id: 'default', color: [0.9, 0.1, 0.1] });
  delete input.nodes[0].material;
  const exported = createAgentScene(input).exportRecipe();
  assert.equal(exported.materials.filter(material => material.id === 'default').length, 1);
  const orphan = recipe();
  delete orphan.nodes[1].geometry;
  orphan.nodes[1].material = 'finish';
  assert.throws(() => createAgentScene(orphan), /nodes\[1\]\.geometry: got "finish"; expected set together with material/);
});

test('a recipe without a materials or geometries list reads them as empty, and the export lists them', () => {
  const minimal = { format: 'crucible.scene', schemaVersion: 1,
    geometries: [{ id: 'box', type: 'box', bevel: 0 }],
    nodes: [{ id: 'part', geometry: 'box' }] };
  const exported = createAgentScene(minimal).exportRecipe();
  assert.deepEqual(exported.materials.map(material => material.id), ['default']);
  const bare = createAgentScene({ format: 'crucible.scene', schemaVersion: 1, nodes: [{ id: 'group' }] }).exportRecipe();
  assert.deepEqual(bare.geometries, []);
  assert.deepEqual(bare.materials, []);
  assert.throws(() => createAgentScene({ format: 'crucible.scene', schemaVersion: 1 }), /nodes/);
});

test("recipe materials accept alphaMode 'add' and keep it when opacity is below one", () => {
  assert.ok(AGENT_SCENE_CAPABILITIES.alphaModes.includes('add'));
  const input = recipe();
  input.materials.push({ id: 'spark', color: [1, 0.6, 0.2], emission: 4, alphaMode: 'add' });
  input.materials.push({ id: 'faint spark', color: [1, 0.6, 0.2], alphaMode: 'add', opacity: 0.4 });
  const exported = createAgentScene(input).exportRecipe();
  assert.equal(exported.materials.find(material => material.id === 'spark').alphaMode, 'add');
  assert.equal(exported.materials.find(material => material.id === 'faint spark').alphaMode, 'add');
  input.materials.push({ id: 'bad', color: [1, 1, 1], alphaMode: 'multiply' });
  assert.throws(() => createAgentScene(input), /alphaMode: got .*; expected one of opaque, blend, add/);
});

function geometryBytes(session) {
  return session.parts.map(part => Buffer.concat([
    Buffer.from(part.geometry.positions.buffer, part.geometry.positions.byteOffset, part.geometry.positions.byteLength),
    Buffer.from(part.geometry.indices.buffer, part.geometry.indices.byteOffset, part.geometry.indices.byteLength),
    Buffer.from(part.matrix.buffer, part.matrix.byteOffset, part.matrix.byteLength),
  ]).toString('hex'));
}

test('restoreRevision undoes the last edits without a checkpoint and restores byte-identical geometry', () => {
  const session = createAgentScene(recipe());
  const before = session.exportRecipe();
  const bytesBefore = geometryBytes(session);
  const originalParts = session.parts;
  session.apply([{ type: 'set-node', id: 'root', translation: [9, 9, 9] }], { expectedRevision: 0 });
  session.apply([
    { type: 'remove-node', id: 'other' },
    { type: 'add-geometry', geometry: { id: 'wide', type: 'box', bevel: 0, subdivisions: 1 } },
    { type: 'add-node', node: { id: 'wide-node', geometry: 'wide', material: 'finish' } },
  ], { expectedRevision: 1 });
  session.apply([{ type: 'set-material', id: 'finish', color: [1, 0, 0] }], { expectedRevision: 2 });
  assert.equal(session.restoreRevision(0, { expectedRevision: 3 }), 4);
  assert.deepEqual(session.exportRecipe(), before);
  assert.deepEqual(geometryBytes(session), bytesBefore);
  assert.equal(session.parts[0], originalParts[0], 'part identities are retained for the renderer');
  assert.throws(() => session.restoreRevision(0, { expectedRevision: 3 }), /expectedRevision/);
});

test('restoreRevision keeps a bounded history, drops the oldest first and names the kept revisions', () => {
  const session = createAgentScene(recipe());
  assert.throws(() => session.restoreRevision(0, { expectedRevision: 0 }), /revision: got 0; expected a revision this session kept, but none is kept yet/);
  const edits = REVISION_HISTORY_LIMIT + 3;
  for (let index = 0; index < edits; index++) {
    session.apply([
      { type: 'add-geometry', geometry: { id: `extra-${index}`, type: 'box', bevel: 0, subdivisions: 1 } },
      ...(index > 0 ? [{ type: 'remove-geometry', id: `extra-${index - 1}` }] : []),
    ], { expectedRevision: index });
    assert.ok(session.inspect().residentGeometryBytes <= (REVISION_HISTORY_LIMIT + 2) * 6000, 'history stays inside a fixed allocation');
  }
  const kept = Array.from({ length: REVISION_HISTORY_LIMIT }, (_, index) => edits - REVISION_HISTORY_LIMIT + index);
  assert.throws(() => session.restoreRevision(0, { expectedRevision: edits }), new RegExp(`expected one of the kept revisions: ${kept.join(', ')}`));
  assert.throws(() => session.restoreRevision(edits, { expectedRevision: edits }), /kept revisions/);
  session.restoreRevision(kept[1], { expectedRevision: edits });
  assert.ok(session.exportRecipe().geometries.some(geometry => geometry.id === `extra-${kept[1] - 1}`));
  // Undoing the undo works: the state before the restore is kept under its own revision.
  session.restoreRevision(edits, { expectedRevision: edits + 1 });
  assert.ok(session.exportRecipe().geometries.some(geometry => geometry.id === `extra-${edits - 1}`));
});

test('kept revisions never block an edit that fits the geometry budget without them', () => {
  const session = createAgentScene(recipe(), { maxVertices: 24, maxGeometryBytes: 1344 });
  session.apply([
    { type: 'remove-node', id: 'root', recursive: true }, { type: 'remove-node', id: 'other' },
    { type: 'remove-geometry', id: 'box' }, { type: 'remove-material', id: 'finish' },
  ], { expectedRevision: 0 });
  session.apply([{ type: 'add-geometry', geometry: { id: 'new', type: 'box', bevel: 0 } }], { expectedRevision: 1 });
  assert.equal(session.inspect().geometryBytes, 720);
  assert.throws(() => session.restoreRevision(0, { expectedRevision: 2 }), /kept revisions: 1/);
});

test('removing a geometry or material that nodes still use names the nodes and the fix', () => {
  const session = createAgentScene(recipe());
  assert.throws(() => session.apply([{ type: 'remove-geometry', id: 'box' }], { expectedRevision: 0 }),
    /id: got "box"; expected geometry box is used by nodes child, other; set-node them to another geometry or remove-node them first./);
  assert.throws(() => session.apply([{ type: 'remove-material', id: 'finish' }], { expectedRevision: 0 }),
    /id: got "finish"; expected material finish is used by nodes child, other; set-node them to another material or remove-node them first./);
  session.apply([{ type: 'add-geometry', geometry: { id: 'spare', type: 'box', bevel: 0 } }, { type: 'remove-geometry', id: 'spare' }], { expectedRevision: 0 });
});

test('the in-use removal error lists at most eight nodes and counts the rest', () => {
  const crowded = recipe();
  for (let index = 0; index < 11; index += 1) {
    crowded.nodes.push({ id: `extra${index}`, geometry: 'box', material: 'finish' });
  }
  const session = createAgentScene(crowded);
  assert.throws(() => session.apply([{ type: 'remove-geometry', id: 'box' }], { expectedRevision: 0 }),
    /nodes child, other, extra0, extra1, extra2, extra3, extra4, extra5 and 5 more;/);
});

test('field errors never print an empty list of choices', () => {
  const session = createAgentScene({ format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [] });
  assert.throws(() => session.apply([{ type: 'add-node', node: { id: 'a', geometry: 'box', material: 'm' } }], { expectedRevision: 0 }),
    error => !/expected one of \./.test(error.message) && /none is defined yet/.test(error.message));
});