@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/animation-graph-build.unit.test.ts

@@ -0,0 +1,100 @@
+// feat-20260713-animation-state-machine-plugin M2 / w9 — legal graph build +
+// shared handle multi-entity rc (AC-02).
+//
+// AC-02: a legal Clip/Blend/Add/nested graph constructs without error via
+// defineAnimationGraph; the resulting POD is minted into a GUID-addressable
+// shared<AnimationGraph> handle; two entities share the SAME handle and the
+// SharedRefStore refcount retains/releases correctly as entities spawn/despawn
+// (multi-entity sharing). The evaluation system is NOT landed in M2 — this test
+// only exercises the data model + carrier (plan-strategy §7 M2 boundary).
+//
+// TDD red anchor: before w13 (types POD) + w14 (builder), the imports below do
+// not resolve and defineAnimationGraph does not exist — the file fails to
+// compile. After w13/w14 the legal graph constructs and the rc assertions pass.
+
+import { defineAnimationGraph } from '@forgeax/engine-animation';
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+// A test-only component carrying a single shared<AnimationGraph> handle. M2 does
+// NOT extend AnimationPlayer with a graph field (that is M3 / w24), so this
+// minimal holder is the authentic ECS path for exercising the write-barrier
+// retain/release across multiple entities without touching the M2-frozen
+// AnimationPlayer schema.
+const GraphHolder = defineComponent('AnimationGraphHolderW9', {
+  graph: 'shared<AnimationGraph>',
+});
+
+function clipGuid(id: number) {
+  return `test/animation-clip-${id}`;
+}
+
+describe('AnimationGraph — legal build + multi-entity rc (M2 / w9)', () => {
+  it('constructs a nested Clip/Blend/Add graph without error', () => {
+    const walk = clipGuid(1);
+    const run = clipGuid(2);
+    const survey = clipGuid(3);
+    const overlay = clipGuid(4);
+
+    const result = defineAnimationGraph((b) => {
+      const walkNode = b.clip(walk);
+      const runNode = b.clip(run);
+      const surveyNode = b.clip(survey);
+      const loco = b.blend([walkNode, runNode]);
+      const base = b.blend([surveyNode, loco]);
+      const overlayNode = b.clip(overlay, 0.3);
+      return b.add(base, [overlayNode]);
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const graph = result.value;
+    expect(graph.kind).toBe('animation-graph');
+    // 4 clip nodes + 2 blend nodes + 1 add node = 7 nodes; root is the add.
+    expect(graph.nodes.length).toBe(7);
+    expect(graph.nodes[graph.root]?.type).toBe('add');
+  });
+
+  it('mints a GUID-addressable shared handle with rc=1 (alloc grant)', () => {
+    const world = new World();
+    const result = defineAnimationGraph((b) => b.clip(clipGuid(1)));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const handle = world.allocSharedRef('AnimationGraph', result.value);
+    expect(handle).toBeGreaterThan(0);
+    expect(world.sharedRefs.refcount(handle)).toBe(1);
+  });
+
+  it('shares one handle across two entities; rc tracks retain/release', () => {
+    const world = new World();
+    const clipMap = new Map<number, AnimationClip>();
+    clipMap.set(1, { kind: 'animation-clip', duration: 10, channels: [] });
+
+    const result = defineAnimationGraph((b) => {
+      const a = b.clip(clipGuid(1));
+      const c = b.clip(clipGuid(1));
+      return b.blend([a, c]);
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const handle = world.allocSharedRef('AnimationGraph', result.value);
+    // alloc grant = 1.
+    expect(world.sharedRefs.refcount(handle)).toBe(1);
+
+    // Two entities hold the SAME handle — each spawn retains via the write
+    // barrier, so rc climbs to 3 (1 grant + 2 holders).
+    const e0 = world.spawn({ component: GraphHolder, data: { graph: handle } }).unwrap();
+    const e1 = world.spawn({ component: GraphHolder, data: { graph: handle } }).unwrap();
+    expect(world.sharedRefs.refcount(handle)).toBe(3);
+
+    // Despawning one holder releases exactly one ref (independent per entity).
+    world.despawn(e0).unwrap();
+    expect(world.sharedRefs.refcount(handle)).toBe(2);
+
+    world.despawn(e1).unwrap();
+    expect(world.sharedRefs.refcount(handle)).toBe(1);
+  });
+});

package/src/__tests__/animation-graph-clip-missing.unit.test.ts

@@ -0,0 +1,62 @@
+// feat-20260713-animation-state-machine-plugin M3 / w22 — clip-missing
+// structured error (AC-11).
+//
+// AC-11 (clip-missing branch): when a graph node references a shared<AnimationClip>
+// whose handle does not resolve (never registered, or rc released), evaluation
+// fails with a structured `animation-graph-clip-missing` error carrying a
+// machine-readable `.code` / `.hint` — and it must NOT leave a dirty pose (the
+// derived slot columns stay untouched). AI users self-repair by property access,
+// not string parsing (charter P3).
+//
+// TDD red anchor: before w24 + w25 the file fails to compile; after them a
+// dangling clip handle throws the structured error before any slot is written.
+
+import {
+  AnimationPlayer,
+  defineAnimationGraph,
+  evaluateAnimationGraph,
+} from '@forgeax/engine-animation';
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+
+interface StructuredError {
+  code?: unknown;
+  hint?: unknown;
+}
+
+describe('evaluateAnimationGraph — clip-missing structured error (M3 / w22)', () => {
+  it('throws animation-asset-not-found and writes no dirty pose', () => {
+    const world = new World();
+
+    // A durable clip GUID that was never loaded. Construction only validates
+    // topology, so a single-clip graph with a dangling GUID is a
+    // well-formed DAG that fails at evaluation, not at build.
+    const danglingClip = 'test/dangling-animation-clip';
+    const built = defineAnimationGraph((b) => b.clip(danglingClip));
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const graphH = world.allocSharedRef('AnimationGraph', built.value);
+
+    const e = world
+      .spawn({ component: AnimationPlayer, data: { graph: graphH } })
+      .unwrap() as EntityHandle;
+
+    let caught: StructuredError | undefined;
+    try {
+      evaluateAnimationGraph(world, 0);
+    } catch (err) {
+      caught = err as StructuredError;
+    }
+
+    expect(caught).toBeDefined();
+    expect(caught?.code).toBe('animation-asset-not-found');
+    expect(typeof caught?.hint).toBe('string');
+    expect((caught?.hint as string).length).toBeGreaterThan(0);
+
+    // No dirty pose: eval resolves every clip BEFORE writing, so the derived
+    // slot columns were never touched (still empty from the spawn default).
+    const ap = world.get(e, AnimationPlayer).unwrap() as unknown as { weights: Float32Array };
+    expect(ap.weights.length).toBe(0);
+  });
+});

package/src/__tests__/animation-graph-clip.unit.test.ts

@@ -0,0 +1,77 @@
+// feat-20260713-animation-state-machine-plugin M3 / w16 — Clip node sampling
+// (AC-03).
+//
+// AC-03: a single-Clip graph samples its shared<AnimationClip> at the node's
+// seek-time and evaluation outputs ONE slot carrying that clip at full effective
+// weight (runtime weight x static weight = 1 x 1 = 1). evaluateAnimationGraph
+// fills the AnimationPlayer's derived N-slot columns; the slot fill (clip handle
+// + effective weight + resolved time) is the machine-checkable evidence of the
+// Clip node semantics (downstream advanceAnimationPlayer does the actual pose
+// blend, covered by animation-nslot.unit.test.ts).
+//
+// TDD red anchor: before w24 (AnimationPlayer.graph field) + w25
+// (evaluateAnimationGraph), the imports below do not resolve and the file fails
+// to compile. After w24/w25 the single-clip graph fills one slot at weight 1.
+
+import {
+  AnimationPlayer,
+  defineAnimationGraph,
+  evaluateAnimationGraph,
+} from '@forgeax/engine-animation';
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function registerClip(world: World, duration: number) {
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  return world.allocSharedRef('AnimationClip', clip);
+}
+
+const lookupClip = (_guid: string): AnimationClip => ({
+  kind: 'animation-clip',
+  duration: 10,
+  channels: [],
+});
+
+interface Slots {
+  clips: Uint32Array;
+  times: Float32Array;
+  weights: Float32Array;
+  speeds: Float32Array;
+}
+
+function readSlots(world: World, e: EntityHandle): Slots {
+  return world.get(e, AnimationPlayer).unwrap() as unknown as Slots;
+}
+
+describe('evaluateAnimationGraph — Clip node sampling (M3 / w16)', () => {
+  it('fills one slot at full effective weight for a single-Clip graph', () => {
+    const world = new World();
+    registerClip(world, 10);
+
+    const built = defineAnimationGraph((b) => b.clip('test/animation-clip-single'));
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const graphH = world.allocSharedRef('AnimationGraph', built.value);
+
+    const e = world
+      .spawn({ component: AnimationPlayer, data: { graph: graphH } })
+      .unwrap() as EntityHandle;
+
+    evaluateAnimationGraph(world, 0, lookupClip);
+
+    const ap = readSlots(world, e);
+    // Exactly one clip node -> one derived slot.
+    expect(ap.clips.length).toBe(1);
+    expect(ap.weights.length).toBe(1);
+    expect(ap.times.length).toBe(1);
+    expect(ap.speeds.length).toBe(1);
+    // The slot carries the clip handle at full effective weight (1 x 1 = 1).
+    expect(ap.clips[0]).toBeGreaterThan(0);
+    expect(ap.weights[0]).toBeCloseTo(1, 5);
+    // Derived path writes speeds[]=0 so advance does not re-advance the time
+    // (D-7: eval owns the seek-time, advance must not double-drive it).
+    expect(ap.speeds[0]).toBe(0);
+  });
+});

package/src/__tests__/animation-graph-collect-roundtrip.test.ts

@@ -0,0 +1,213 @@
+// feat-20260713-animation-state-machine-plugin M4 / w28 -- graph-holding entity
+// scene collect round-trip (AC-14 part b).
+//
+// AC-14 (part b) metric: an entity carrying a `shared<AnimationGraph>` handle is
+// collected through scene collect; the graph handle resolves to a persistable
+// GUID reference (schema-driven, plan D-4: `classifyFieldSchema` sees the
+// `shared<AnimationGraph>` scalar and routes it through `_guidForAsset` with ZERO
+// special-case in collect-scene-asset.ts, w31 verifies this); a `graph == 0`
+// (no-graph) entity is skipped by the existing 0-sentinel path (lossless); and a
+// graph reloaded from its serialized pack payload evaluates to the SAME derived
+// N-slot weights as the original (round-trip lossless).
+//
+// TDD red anchor: serializeAnimationGraph (w29) + animationGraphLoader (w30) do
+// not resolve until those tasks land; the eval-consistency case then goes green.
+// The collect->GUID cases exercise the already-present schema-driven path (w31 is
+// a verify-only landing that this test is the witness for).
+
+import {
+  AnimationPlayer,
+  defineAnimationGraph,
+  evaluateAnimationGraph,
+  serializeAnimationGraph,
+} from '@forgeax/engine-animation';
+import { AssetRegistry, animationGraphLoader } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { AnimationClip, AnimationGraph, Handle, LoadContext } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { rootsToSceneAsset } from '../collect-scene-asset';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+function makeWorld(): World {
+  const world = new World();
+  world.components.register(AnimationPlayer).unwrap();
+  return world;
+}
+
+const stubCtx = {} as LoadContext;
+
+// Register a clip in the registry catalog + world shared-ref store under the same
+// payload identity, returning both its handle and its GUID string.
+function registerClip(
+  world: World,
+  reg: AssetRegistry,
+  guidStr: string,
+  duration: number,
+): { handle: Handle<'AnimationClip', 'shared'>; guid: string; asset: AnimationClip } {
+  const parsed = AssetGuid.parse(guidStr);
+  if (!parsed.ok) throw new Error(`bad test GUID ${guidStr}`);
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  reg.catalog(parsed.value, clip);
+  const handle = world.allocSharedRef('AnimationClip', clip) as Handle<'AnimationClip', 'shared'>;
+  return { handle, guid: AssetGuid.format(parsed.value), asset: clip };
+}
+
+// Register a graph POD in both stores; returns its handle + GUID string.
+function registerGraph(
+  world: World,
+  reg: AssetRegistry,
+  guidStr: string,
+  graph: AnimationGraph,
+): { handle: Handle<'AnimationGraph', 'shared'>; guid: string } {
+  const parsed = AssetGuid.parse(guidStr);
+  if (!parsed.ok) throw new Error(`bad test GUID ${guidStr}`);
+  reg.catalog(parsed.value, graph);
+  const handle = world.allocSharedRef('AnimationGraph', graph) as Handle<
+    'AnimationGraph',
+    'shared'
+  >;
+  return { handle, guid: AssetGuid.format(parsed.value) };
+}
+
+function apOf(scene: { entities: readonly unknown[] }): Record<string, unknown> | undefined {
+  for (const e of scene.entities) {
+    const comps = (e as { components: Record<string, Record<string, unknown>> }).components;
+    if (comps.AnimationPlayer !== undefined) return comps.AnimationPlayer;
+  }
+  return undefined;
+}
+
+const G_WALK = 'b1000000-0000-4000-8000-000000000001';
+const G_RUN = 'b1000000-0000-4000-8000-000000000002';
+const G_SURVEY = 'b1000000-0000-4000-8000-000000000003';
+const G_GRAPH = 'b1000000-0000-4000-8000-0000000000aa';
+const G_GRAPH2 = 'b1000000-0000-4000-8000-0000000000bb';
+
+// Build the standard test graph: Add(base=Blend(walk, run), additive=[survey@0.3]).
+function buildStandardGraph(walk: string, run: string, survey: string): AnimationGraph {
+  const built = defineAnimationGraph((b) => {
+    const w = b.clip(walk);
+    const r = b.clip(run);
+    const loco = b.blend([w, r]);
+    const overlay = b.clip(survey, 0.3);
+    return b.add(loco, [overlay]);
+  });
+  if (!built.ok) throw new Error('graph build failed');
+  return built.value;
+}
+
+describe('AnimationGraph collect round-trip (M4 / w28, AC-14 part b)', () => {
+  it('collects a graph-holding entity with graph resolved to its GUID (schema-driven, zero special-case)', () => {
+    const world = makeWorld();
+    const reg = makeRegistry();
+    const walk = registerClip(world, reg, G_WALK, 10);
+    const run = registerClip(world, reg, G_RUN, 20);
+    const survey = registerClip(world, reg, G_SURVEY, 30);
+    const graph = buildStandardGraph(walk.guid, run.guid, survey.guid);
+    const g = registerGraph(world, reg, G_GRAPH, graph);
+
+    const e = world
+      .spawn({
+        component: AnimationPlayer,
+        data: { graph: g.handle, nodeWeights: [1, 1, 1, 1, 1] },
+      })
+      .unwrap();
+
+    const collected = rootsToSceneAsset(reg, world, [e]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+
+    const ap = apOf(collected.value);
+    expect(ap).not.toBeUndefined();
+    if (ap === undefined) return;
+    // The graph scalar shared field resolves to the catalogued GUID string.
+    expect(ap.graph).toBe(g.guid);
+  });
+
+  it('skips a graph == 0 (no-graph) entity 0-sentinel: lossless, no graph key emitted', () => {
+    const world = makeWorld();
+    const reg = makeRegistry();
+
+    const e = world
+      .spawn({
+        component: AnimationPlayer,
+        data: { clips: [], times: [], weights: [], speeds: [] },
+      })
+      .unwrap();
+
+    const collected = rootsToSceneAsset(reg, world, [e]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+
+    const ap = apOf(collected.value);
+    expect(ap).not.toBeUndefined();
+    if (ap === undefined) return;
+    // graph == 0 (unset) is dropped by the shared-scalar 0-sentinel skip.
+    expect('graph' in ap).toBe(false);
+  });
+
+  it('a graph reloaded from its serialized pack payload evaluates to identical weights', () => {
+    const world = makeWorld();
+    const reg = makeRegistry();
+    const walk = registerClip(world, reg, G_WALK, 10);
+    const run = registerClip(world, reg, G_RUN, 20);
+    const survey = registerClip(world, reg, G_SURVEY, 30);
+    const original = buildStandardGraph(walk.guid, run.guid, survey.guid);
+    const lookup = (guid: string): AnimationClip | undefined =>
+      new Map([
+        [walk.guid, walk.asset],
+        [run.guid, run.asset],
+        [survey.guid, survey.asset],
+      ]).get(guid);
+
+    // Original graph -> register -> spawn -> eval one frame -> read weights.
+    const g0 = registerGraph(world, reg, G_GRAPH, original);
+    const e0 = world.spawn({ component: AnimationPlayer, data: { graph: g0.handle } }).unwrap();
+    evaluateAnimationGraph(world, 1 / 60, lookup);
+    const w0res = world.get(e0, AnimationPlayer);
+    expect(w0res.ok).toBe(true);
+    if (!w0res.ok) return;
+    const weights0 = Array.from((w0res.value as unknown as { weights: Float32Array }).weights);
+
+    // Serialize -> deserialize -> re-resolve clip GUIDs to their handles -> rebuild.
+    const clipGuidResolver = (clip: string): string | undefined => clip;
+    const out = serializeAnimationGraph(original, clipGuidResolver);
+    expect(out).not.toBeUndefined();
+    if (out === undefined) return;
+    const parsed = animationGraphLoader.load(out.payload, out.refs, stubCtx);
+    if (parsed === undefined || typeof parsed !== 'object' || 'ok' in parsed) {
+      throw new Error('animationGraphLoader returned a non-asset result');
+    }
+    const reloaded = parsed as AnimationGraph;
+
+    const rebuilt: AnimationGraph = reloaded;
+
+    const g1 = registerGraph(world, reg, G_GRAPH2, rebuilt);
+    const e1 = world.spawn({ component: AnimationPlayer, data: { graph: g1.handle } }).unwrap();
+    evaluateAnimationGraph(world, 1 / 60, lookup);
+    const w1res = world.get(e1, AnimationPlayer);
+    expect(w1res.ok).toBe(true);
+    if (!w1res.ok) return;
+    const weights1 = Array.from((w1res.value as unknown as { weights: Float32Array }).weights);
+
+    // Round-trip lossless: reloaded graph evaluates to the same derived weights.
+    expect(weights1).toHaveLength(weights0.length);
+    for (let i = 0; i < weights0.length; i++) {
+      expect(weights1[i]).toBeCloseTo(weights0[i] as number, 6);
+    }
+    // Sanity: the standard graph yields Blend(walk,run)=[0.5,0.5] + Add survey@0.3.
+    // weights[] is a Float32Array column, so 0.3 reads back as its f32 nearest
+    // (0.30000001192...) -- compare per-slot with f32-scale tolerance, not
+    // strict f64 equality.
+    const expectedWeights0 = [0.5, 0.5, 0.3];
+    expect(weights0).toHaveLength(expectedWeights0.length);
+    for (let i = 0; i < expectedWeights0.length; i++) {
+      expect(weights0[i]).toBeCloseTo(expectedWeights0[i] as number, 6);
+    }
+  });
+});

package/src/__tests__/animation-graph-default-path.integration.test.ts

@@ -0,0 +1,65 @@
+// feat-20260713-animation-state-machine-plugin M3 / w23 — default-path eval
+// integration (AC-09).
+//
+// AC-09: DAG evaluation is wired into the DEFAULT animationPlugin (not an opt-in
+// plugin). A host that lists the default animation capability gets automatic
+// per-frame evaluation for free: spawn an entity carrying an AnimationGraph
+// handle, drive a single world.update(), and read back the derived weights[] —
+// no manual evaluateAnimationGraph() call anywhere. This mirrors the assemble
+// form of createApp (a host-owned World running the default plugin set), the
+// harshest headless surface of the "default plugin set" contract, matching the
+// animationPlugin self-owns-resolver regression's approach.
+//
+// TDD red anchor: before w24 + w25 + w26 (plugin registers eval) the graph
+// carrier never gets evaluated, so weights[] stays empty; after them the default
+// plugin fills it automatically.
+
+import { AnimationPlayer, animationPlugin, defineAnimationGraph } from '@forgeax/engine-animation';
+import { createWorldContext, type EntityHandle, World } from '@forgeax/engine-ecs';
+import type { AnimationClip } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function registerClip(world: World, duration: number) {
+  const clip: AnimationClip = { kind: 'animation-clip', duration, channels: [] };
+  return world.allocSharedRef('AnimationClip', clip);
+}
+
+describe('DAG eval — default animationPlugin path (M3 / w23, AC-09)', () => {
+  it('auto-evaluates a graph carrier on world.update() with no opt-in', async () => {
+    const world = new World();
+
+    // Build the DEFAULT animation capability onto a bare host World (assemble
+    // form) — this is exactly what createApp's default plugin set does for the
+    // animation subsystem.
+    // Declare a normalizing Blend(Walk@1, Run@1) graph and register it + its
+    // clips as ordinary payloads retained by the host-owned lookup.
+    const clips = new Map<string, AnimationClip>([
+      ['test/animation-clip-walk', { kind: 'animation-clip', duration: 10, channels: [] }],
+      ['test/animation-clip-run', { kind: 'animation-clip', duration: 10, channels: [] }],
+    ]);
+    registerClip(world, 10);
+    registerClip(world, 10);
+    await createWorldContext(world, [animationPlugin((guid) => clips.get(guid))]);
+    const built = defineAnimationGraph((b) =>
+      b.blend([b.clip('test/animation-clip-walk'), b.clip('test/animation-clip-run')]),
+    );
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    const graphH = world.allocSharedRef('AnimationGraph', built.value);
+
+    const e = world
+      .spawn({ component: AnimationPlayer, data: { graph: graphH } })
+      .unwrap() as EntityHandle;
+
+    // Drive ONE frame through the default schedule. No manual eval call.
+    world.update();
+    expect(world.execution.health).toBe('healthy');
+
+    // The default plugin's evaluateAnimationGraph ran before advance and filled
+    // the derived weights[] with the normalized [0.5, 0.5] distribution.
+    const ap = world.get(e, AnimationPlayer).unwrap() as unknown as { weights: Float32Array };
+    expect(ap.weights.length).toBe(2);
+    expect(ap.weights[0]).toBeCloseTo(0.5, 5);
+    expect(ap.weights[1]).toBeCloseTo(0.5, 5);
+  });
+});

package/src/__tests__/animation-graph-describe.unit.test.ts

@@ -0,0 +1,68 @@
+// feat-20260713-animation-state-machine-plugin M2 / w11 — describeAnimationGraph
+// machine-readable introspection (AC-12).
+//
+// AC-12 + plan §8.4: describeAnimationGraph(g) enumerates the graph's nodes,
+// topology (per-node children), root, and per-node static weights so an AI user
+// discovers the graph structure WITHOUT reading implementation source (mirrors
+// the getRegisteredComponents reflection idiom, research Finding H). The
+// returned set must match the declared graph item-for-item.
+//
+// TDD red anchor: describeAnimationGraph does not exist before w15; the file
+// fails to compile. After w15 the introspection matches the declaration.
+
+import { defineAnimationGraph, describeAnimationGraph } from '@forgeax/engine-animation';
+import { describe, expect, it } from 'vitest';
+
+function clipGuid(id: number) {
+  return `test/animation-clip-${id}`;
+}
+
+describe('describeAnimationGraph — introspection (M2 / w11)', () => {
+  it('enumerates nodes, root, and static weights matching the declaration', () => {
+    const result = defineAnimationGraph((b) => {
+      const walk = b.clip(clipGuid(1), 1);
+      const run = b.clip(clipGuid(2), 1);
+      const loco = b.blend([walk, run], 0.4);
+      const overlay = b.clip(clipGuid(3), 0.3);
+      return b.add(loco, [overlay], 1);
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const desc = describeAnimationGraph(result.value);
+
+    // 3 clips + 1 blend + 1 add = 5 nodes; root is the add (index 4).
+    // Enumeration is CONSTRUCTION order (verbatim builder order), which is the
+    // same index space as the runtime AnimationPlayer.nodeWeights knobs — so an
+    // AI driving by desc.index writes the correct slot (V-1 fix: no reordering).
+    // Construction order: walk(0) run(1) loco/blend(2) overlay(3) add/root(4).
+    expect(desc.nodes.length).toBe(5);
+    expect(desc.root).toBe(4);
+
+    // Per-node type enumeration, construction order.
+    expect(desc.nodes.map((n) => n.type)).toEqual(['clip', 'clip', 'blend', 'clip', 'add']);
+
+    // Static weights read back item-for-item as declared, construction order.
+    expect(desc.staticWeights).toEqual([1, 1, 0.4, 0.3, 1]);
+    expect(desc.nodes.map((n) => n.weight)).toEqual([1, 1, 0.4, 0.3, 1]);
+
+    // desc.index equals the construction position for every node (== nodeWeights slot).
+    expect(desc.nodes.map((n) => n.index)).toEqual([0, 1, 2, 3, 4]);
+
+    // Topology: clips have no children; blend(2) lists its leaves [walk, run];
+    // add(4) lists [base=loco, ...additive=overlay].
+    expect(desc.nodes[0]?.children).toEqual([]);
+    expect(desc.nodes[2]?.children).toEqual([0, 1]);
+    expect(desc.nodes[4]?.children).toEqual([2, 3]);
+  });
+
+  it('exposes node index on each description entry', () => {
+    const result = defineAnimationGraph((b) => b.clip(clipGuid(1)));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const desc = describeAnimationGraph(result.value);
+    expect(desc.nodes[0]?.index).toBe(0);
+    expect(desc.root).toBe(0);
+  });
+});

package/src/__tests__/animation-graph-errors.unit.test.ts

@@ -0,0 +1,75 @@
+// feat-20260713-animation-state-machine-plugin M2 / w10 — illegal graph
+// construction structured errors (AC-11 graph-structure branches).
+//
+// AC-11 + plan D-5: defineAnimationGraph validates topology at CONSTRUCTION time
+// (before a GUID handle is minted) and returns Result.err with a structured
+// `.code` / `.hint` for each illegal shape:
+//   - node reference out of range  -> 'animation-graph-node-out-of-range'
+//   - cycle                        -> 'animation-graph-cycle'
+//   - node weight negative / NaN   -> 'animation-graph-node-weight-invalid'
+//   - empty graph                  -> 'animation-graph-empty'
+// AI users self-repair by property access — no string parsing (charter P3).
+//
+// TDD red anchor: defineAnimationGraph does not exist before w14; the file fails
+// to compile. After w14 each illegal graph returns the matching structured code.
+
+import { type AnimationGraphNodeRef, defineAnimationGraph } from '@forgeax/engine-animation';
+import { describe, expect, it } from 'vitest';
+
+function clipGuid(id: number) {
+  return `test/animation-clip-${id}`;
+}
+
+// Cast a raw index to a node ref — the illegal-graph tests deliberately forge
+// out-of-range / self-referential refs the well-behaved builder never emits.
+function forgeRef(index: number): AnimationGraphNodeRef {
+  return index as unknown as AnimationGraphNodeRef;
+}
+
+describe('AnimationGraph — illegal construction errors (M2 / w10)', () => {
+  it('empty graph -> animation-graph-empty', () => {
+    // The builder creates zero nodes; the returned root ref points nowhere.
+    const result = defineAnimationGraph(() => forgeRef(0));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('animation-graph-empty');
+    expect(typeof result.error.hint).toBe('string');
+    expect(result.error.hint.length).toBeGreaterThan(0);
+  });
+
+  it('out-of-range child reference -> animation-graph-node-out-of-range', () => {
+    const result = defineAnimationGraph((b) => {
+      b.clip(clipGuid(1)); // node 0
+      // A blend that references index 99 (nonexistent).
+      return b.blend([forgeRef(99)]);
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('animation-graph-node-out-of-range');
+    expect(result.error.hint.length).toBeGreaterThan(0);
+  });
+
+  it('cycle -> animation-graph-cycle', () => {
+    // node 0 is a blend that references itself (index 0).
+    const result = defineAnimationGraph((b) => b.blend([forgeRef(0)]));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('animation-graph-cycle');
+    expect(result.error.hint.length).toBeGreaterThan(0);
+  });
+
+  it('negative node weight -> animation-graph-node-weight-invalid', () => {
+    const result = defineAnimationGraph((b) => b.clip(clipGuid(1), -0.5));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('animation-graph-node-weight-invalid');
+    expect(result.error.hint.length).toBeGreaterThan(0);
+  });
+
+  it('NaN node weight -> animation-graph-node-weight-invalid', () => {
+    const result = defineAnimationGraph((b) => b.clip(clipGuid(1), Number.NaN));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('animation-graph-node-weight-invalid');
+  });
+});