@forgeax/engine-animation 0.1.2

package/src/graph/define-animation-graph.ts

@@ -0,0 +1,193 @@
+// @forgeax/engine-animation -- defineAnimationGraph builder + construction-time
+// topology validation.
+//
+// feat-20260713-animation-state-machine-plugin M2 / w14 (plan D-4 landing (2),
+// D-5 construct-time validation):
+//
+//   const g = defineAnimationGraph((b) => {
+//     const walk = b.clip(walkGuid);
+//     const run = b.clip(runGuid);
+//     const loco = b.blend([walk, run]);       // normalizing
+//     const overlay = b.clip(overlayGuid, 0.3);
+//     return b.add(loco, [overlay]);           // non-normalizing; returns root
+//   });                                        // -> Result<AnimationGraph, AnimationGraphError>
+//   if (!g.ok) return; // g.error.code / g.error.hint (AC-11)
+//
+// This is a pure library: NO evaluation system, NO AnimationPlayer change, NO
+// loader/serialization (those are M3/M4). The builder assembles a flat node
+// array and validates topology BEFORE returning ok(graph) -- an illegal graph
+// (empty / out-of-range ref / cycle / invalid weight) fails fast with a
+// structured error (charter P3, requirements AC-11) so it can never be minted
+// into a GUID handle or serialized into a pack (AC-14).
+
+import type { AnimationGraph, AnimationGraphNode } from '@forgeax/engine-types';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  AnimationGraphCycleError,
+  AnimationGraphEmptyError,
+  type AnimationGraphError,
+  AnimationGraphNodeOutOfRangeError,
+  AnimationGraphNodeWeightInvalidError,
+} from '../errors';
+
+/**
+ * Opaque reference to a node inside the graph under construction. Branded so a
+ * raw number cannot be passed where a node ref is expected without an explicit
+ * cast (the illegal-graph tests forge refs deliberately). At runtime it is the
+ * node's index in {@link AnimationGraph.nodes}.
+ */
+export type AnimationGraphNodeRef = number & {
+  readonly __animationGraphNodeRef: unique symbol;
+};
+
+/**
+ * Declarative builder handed to the `defineAnimationGraph` callback. Exposes
+ * exactly the three node kinds (clip / blend / add) + nesting -- no FSM /
+ * transition / mask surface is reserved (OOS-1..4, charter F4). Each method
+ * appends a node and returns its {@link AnimationGraphNodeRef}.
+ */
+export interface AnimationGraphBuilder {
+  /** Add a Clip leaf sampling `clip` with the given static `weight` (default 1). */
+  clip(clip: string, weight?: number): AnimationGraphNodeRef;
+  /** Add a Blend node (normalizing lerp) over `children` with static `weight` (default 1). */
+  blend(children: readonly AnimationGraphNodeRef[], weight?: number): AnimationGraphNodeRef;
+  /** Add an Add node (non-normalizing) stacking `additive` layers onto `base`; static `weight` default 1. */
+  add(
+    base: AnimationGraphNodeRef,
+    additive: readonly AnimationGraphNodeRef[],
+    weight?: number,
+  ): AnimationGraphNodeRef;
+}
+
+/**
+ * Enumerate the child node indices a node references: clip -> none; blend ->
+ * its children; add -> `[base, ...additive]`. Exhaustive over the closed node
+ * union (charter P3). Shared by the validator here and describeAnimationGraph.
+ */
+export function animationGraphNodeChildren(node: AnimationGraphNode): readonly number[] {
+  switch (node.type) {
+    case 'clip':
+      return [];
+    case 'blend':
+      return node.children;
+    case 'add':
+      return [node.base, ...node.additive];
+  }
+}
+
+function makeBuilder(nodes: AnimationGraphNode[]): AnimationGraphBuilder {
+  return {
+    clip(clip, weight = 1) {
+      const index = nodes.length;
+      nodes.push({ type: 'clip', clip, weight });
+      return index as AnimationGraphNodeRef;
+    },
+    blend(children, weight = 1) {
+      const index = nodes.length;
+      nodes.push({ type: 'blend', children: children.slice(), weight });
+      return index as AnimationGraphNodeRef;
+    },
+    add(base, additive, weight = 1) {
+      const index = nodes.length;
+      nodes.push({ type: 'add', base, additive: additive.slice(), weight });
+      return index as AnimationGraphNodeRef;
+    },
+  };
+}
+
+function findInvalidWeight(
+  nodes: readonly AnimationGraphNode[],
+): AnimationGraphNodeWeightInvalidError | null {
+  for (let i = 0; i < nodes.length; i++) {
+    const weight = nodes[i]?.weight ?? Number.NaN;
+    if (!Number.isFinite(weight) || weight < 0) {
+      return new AnimationGraphNodeWeightInvalidError({ node: i, weight });
+    }
+  }
+  return null;
+}
+
+function isRef(ref: number, nodeCount: number): boolean {
+  return Number.isInteger(ref) && ref >= 0 && ref < nodeCount;
+}
+
+function findOutOfRangeRef(
+  nodes: readonly AnimationGraphNode[],
+  root: number,
+): AnimationGraphNodeOutOfRangeError | null {
+  const nodeCount = nodes.length;
+  if (!isRef(root, nodeCount)) {
+    return new AnimationGraphNodeOutOfRangeError({ node: root, ref: root, nodeCount });
+  }
+  for (let i = 0; i < nodeCount; i++) {
+    const node = nodes[i];
+    if (node === undefined) continue;
+    for (const ref of animationGraphNodeChildren(node)) {
+      if (!isRef(ref, nodeCount)) {
+        return new AnimationGraphNodeOutOfRangeError({ node: i, ref, nodeCount });
+      }
+    }
+  }
+  return null;
+}
+
+function findCycle(nodes: readonly AnimationGraphNode[]): AnimationGraphCycleError | null {
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Uint8Array(nodes.length);
+  let cycleNode = -1;
+
+  const visit = (i: number): boolean => {
+    color[i] = GRAY;
+    const node = nodes[i];
+    const children = node === undefined ? [] : animationGraphNodeChildren(node);
+    for (const child of children) {
+      if (color[child] === GRAY) {
+        cycleNode = child;
+        return true;
+      }
+      if (color[child] === WHITE && visit(child)) return true;
+    }
+    color[i] = BLACK;
+    return false;
+  };
+
+  for (let i = 0; i < nodes.length; i++) {
+    if (color[i] === WHITE && visit(i)) {
+      return new AnimationGraphCycleError({ node: cycleNode });
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate a graph's topology (order: empty -> invalid weight -> out-of-range
+ * ref -> cycle). Returns the first structured error found, or null when the
+ * graph is a well-formed DAG. Runs before a handle is minted (plan D-5).
+ */
+function validateAnimationGraph(
+  nodes: readonly AnimationGraphNode[],
+  root: number,
+): AnimationGraphError | null {
+  if (nodes.length === 0) return new AnimationGraphEmptyError();
+  return findInvalidWeight(nodes) ?? findOutOfRangeRef(nodes, root) ?? findCycle(nodes);
+}
+
+/**
+ * Construct an {@link AnimationGraph} declaratively. The callback receives a
+ * builder, adds clip/blend/add nodes, and returns the ref of the root node.
+ * The graph's topology is validated at construction time; on success the POD is
+ * returned in `ok(graph)` ready to be minted into a `shared<AnimationGraph>`
+ * handle (AC-02) and serialized (AC-14). On an illegal topology a structured
+ * {@link AnimationGraphError} is returned in `err(...)` (AC-11).
+ */
+export function defineAnimationGraph(
+  build: (builder: AnimationGraphBuilder) => AnimationGraphNodeRef,
+): Result<AnimationGraph, AnimationGraphError> {
+  const nodes: AnimationGraphNode[] = [];
+  const root = build(makeBuilder(nodes)) as number;
+  const error = validateAnimationGraph(nodes, root);
+  if (error) return err(error);
+  return ok({ kind: 'animation-graph', nodes, root });
+}

package/src/graph/describe-animation-graph.ts

@@ -0,0 +1,74 @@
+// @forgeax/engine-animation -- describeAnimationGraph machine-readable introspection.
+//
+// feat-20260713-animation-state-machine-plugin M2 / w15 (plan §8.4, AC-12):
+//
+//   const desc = describeAnimationGraph(graph);
+//   desc.root;           // index of the output node (construction order)
+//   desc.nodes;          // per-node { index, type, weight, children }
+//   desc.staticWeights;  // per-node static weight, construction order
+//
+// AI users discover a graph's structure (nodes / topology / root / per-node
+// static weights) WITHOUT reading implementation source -- mirroring the
+// World-local component catalog reflection (research Finding H, charter F1/P1).
+//
+// Presentation order matches the graph POD construction order so that
+// `desc.nodes[i].index === i` aligns with runtime `nodeWeights[i]` /
+// `nodeTimes[i]` / `nodeSpeeds[i]` (verify V-1: introspect-then-drive path for
+// shared/deserialized graphs must not silently remap indices). The builder must
+// create a child ref before referencing it, so construction order is already a
+// valid topological order. This is a pure, read-only projection of the validated
+// POD -- no evaluation, no mutation.
+
+import type { AnimationGraph, AnimationGraphNode } from '@forgeax/engine-types';
+import { animationGraphNodeChildren } from './define-animation-graph';
+
+/**
+ * Machine-readable description of a single graph node: its index in the
+ * construction order, its `type` discriminant, its static `weight`, and the
+ * child node indices it references (construction order, canonical child ordering).
+ */
+export interface AnimationGraphNodeDescription {
+  /** Index of this node in {@link AnimationGraphDescription.nodes} (construction order). */
+  readonly index: number;
+  /** Node kind discriminant (clip / blend / add). */
+  readonly type: AnimationGraphNode['type'];
+  /** The node's static weight (effective weight = runtime weight x static). */
+  readonly weight: number;
+  /** Child node indices referenced by this node (clip -> []), construction order. */
+  readonly children: readonly number[];
+}
+
+/**
+ * Machine-readable description of an entire {@link AnimationGraph}: the ordered
+ * per-node descriptions (construction order), the root node index, and the
+ * per-node static weights (a flat projection of each node's `weight`).
+ */
+export interface AnimationGraphDescription {
+  /** Per-node descriptions, in graph POD construction order. */
+  readonly nodes: readonly AnimationGraphNodeDescription[];
+  /** Index of the graph's root (output) node, in construction order. */
+  readonly root: number;
+  /** Per-node static weights, in construction order. */
+  readonly staticWeights: readonly number[];
+}
+
+/**
+ * Enumerate a validated {@link AnimationGraph}'s nodes, topology, root, and
+ * per-node static weights for machine-readable introspection (AC-12). Pure and
+ * read-only -- returns a fresh description derived from the POD in construction
+ * order so described indices match runtime `nodeWeights` indices.
+ */
+export function describeAnimationGraph(graph: AnimationGraph): AnimationGraphDescription {
+  const nodes = graph.nodes.map((node, index) => ({
+    index,
+    type: node.type,
+    weight: node.weight,
+    children: animationGraphNodeChildren(node),
+  }));
+
+  return {
+    nodes,
+    root: graph.root,
+    staticWeights: nodes.map((node) => node.weight),
+  };
+}

package/src/graph/serialize-animation-graph.ts

@@ -0,0 +1,90 @@
+// @forgeax/engine-animation -- AnimationGraph POD -> pack payload serialization.
+//
+// feat-20260713-animation-state-machine-plugin M4 / w29 (plan D-4 landing (2),
+// §6.3 serialize seam):
+//
+//   const out = serializeAnimationGraph(graph, (clipGuid) => clipGuid);
+//   if (out === undefined) return; // a durable clip GUID was unavailable
+//   // out.payload -> the pack `payload` object; out.refs -> the pack `refs[]`.
+//
+// The inverse of the animation owner's graph contribution:
+// serialize rewrites each Clip leaf's durable GUID into a deduped `refs[]`
+// array (the payload stores the refs INDEX, not a runtime handle) -- the exact
+// "GUID in refs, index in payload" contract
+// the scene/material serialize paths use (plan D-4, asset-registry D-19). Blend
+// and Add nodes carry only intra-graph node indices, which are position-stable
+// under round-trip, so they pass through unchanged. `root` is a node index and
+// passes through too.
+//
+// OOS-7: this serializes only the topology of an engine-authored
+// `defineAnimationGraph` graph (nodes / static weights / clip refs); there is no
+// DCC-import metadata surface.
+
+import type { AnimationGraph } from '@forgeax/engine-types';
+
+/**
+ * Resolves a Clip leaf's durable GUID string to the form stored in Pack
+ * `refs[]`. Returns `undefined` when the GUID is unavailable, which aborts
+ * serialization.
+ * The caller supplies this so serialize stays free of AssetRegistry / World
+ * coupling; the graph already carries durable GUID strings at this boundary.
+ */
+export type ClipGuidResolver = (clip: string) => string | undefined;
+
+/**
+ * Output of {@link serializeAnimationGraph}: the pack `payload` object (a flat
+ * `{ nodes, root }` shape where Clip leaves reference `refs[]` by index) plus the
+ * deduped `refs[]` array of clip GUID strings.
+ */
+export interface SerializedAnimationGraph {
+  readonly payload: Record<string, unknown>;
+  readonly refs: readonly string[];
+}
+
+/**
+ * Serialize an {@link AnimationGraph} POD into a pack payload + refs pair. Clip
+ * leaves are rewritten from durable GUIDs to deduped `refs[]` GUID indices via
+ * `resolveClipGuid`; Blend/Add node references and `root` (all intra-graph node
+ * indices) pass through. Returns `undefined` if any durable clip GUID cannot be
+ * resolved -- an unresolvable clip means the graph cannot be persisted losslessly.
+ */
+export function serializeAnimationGraph(
+  graph: AnimationGraph,
+  resolveClipGuid: ClipGuidResolver = (clip) => clip,
+): SerializedAnimationGraph | undefined {
+  const refs: string[] = [];
+  const guidToIndex = new Map<string, number>();
+  const internRef = (guid: string): number => {
+    const existing = guidToIndex.get(guid);
+    if (existing !== undefined) return existing;
+    const index = refs.length;
+    refs.push(guid);
+    guidToIndex.set(guid, index);
+    return index;
+  };
+
+  const nodes: Array<Record<string, unknown>> = [];
+  for (const node of graph.nodes) {
+    switch (node.type) {
+      case 'clip': {
+        const guid = resolveClipGuid(node.clip);
+        if (guid === undefined || guid.length === 0) return undefined;
+        nodes.push({ type: 'clip', clip: internRef(guid), weight: node.weight });
+        break;
+      }
+      case 'blend':
+        nodes.push({ type: 'blend', children: [...node.children], weight: node.weight });
+        break;
+      case 'add':
+        nodes.push({
+          type: 'add',
+          base: node.base,
+          additive: [...node.additive],
+          weight: node.weight,
+        });
+        break;
+    }
+  }
+
+  return { payload: { nodes, root: graph.root }, refs };
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Animation graphs, players, and stable Transform targets.
+ *
+ * AI consumers should collect explicit entities, call
+ * {@link bindAnimationTargets} once, then configure the existing
+ * {@link AnimationPlayer} directly or through {@link defineAnimationGraph}.
+ * Binding failures expose stable `code`, `hint`, and `detail` fields.
+ *
+ * @see ../README.md
+ */
+export type {
+  AnimationDiagnostic,
+  AnimationDiagnosticCode,
+  AnimationDiagnosticDetail,
+  AnimationDiagnosticListener,
+} from './animation-diagnostic';
+export { subscribeAnimationDiagnostics } from './animation-diagnostic';
+export { AnimationPlayer } from './animation-player';
+/** Stable target identity, explicit ownership, and atomic batch binding. */
+export {
+  AnimatedBy,
+  AnimationTargetId,
+  AnimationTargets,
+  type BindAnimationTargetsErrorCode,
+  bindAnimationTargets,
+} from './animation-target';
+export { animationClipContribution, animationGraphContribution } from './assets/animation-decoder';
+/** Build the existing graph-to-player slot path; this is not an animation FSM. */
+export {
+  type AnimationGraphNodeRef,
+  animationGraphNodeChildren,
+  defineAnimationGraph,
+} from './graph/define-animation-graph';
+export { describeAnimationGraph } from './graph/describe-animation-graph';
+export { serializeAnimationGraph } from './graph/serialize-animation-graph';
+export { animationPayloadsPlugin, animationPlugin, animationRuntimePlugin } from './plugin';
+export {
+  AnimationAssetError,
+  type AnimationAssetErrorCode,
+  type AnimationAssetErrorDetail,
+  resolveAnimationAsset,
+} from './resolve-animation-asset';
+export {
+  _resetAnimationWarnsForTests,
+  ADVANCE_ANIMATION_PLAYER_SYSTEM,
+  AdvanceAnimationPlayer,
+  AnimationSet,
+  advanceAnimationPlayer,
+  registerAdvanceAnimationPlayer,
+} from './systems/advance-animation-player';
+export type { AnimationPayloadLookup } from './systems/evaluate-animation-graph';
+export {
+  EvaluateAnimationGraph,
+  evaluateAnimationGraph,
+} from './systems/evaluate-animation-graph';
+/** Derive or validate the canonical 32-lowercase-hex animation target wire. */
+export { deriveAnimationTargetId, isAnimationTargetId } from './target-id';

package/src/player-errors.ts

@@ -0,0 +1,72 @@
+// @forgeax/engine-animation -- AnimationPlayer cluster error classes.
+//
+// feat-20260713-animation-state-machine-plugin M1 / w5: the AnimationPlayer SoA
+// columns (clips / times / weights / speeds) became variable `array<T>` when the
+// fixed 4-slot cap was retired (w4). Variable columns are set field-by-field
+// (release-then-alloc per field, plan D-5), so the ECS layer cannot cross-check
+// that the four parallel columns stay length-synced. advanceAnimationPlayer
+// validates the four lengths once per row at its evaluation entry (the single
+// chokepoint, D-5) and rejects a mismatch with the structured error below rather
+// than silently zero-padding or truncating (requirements AC-11).
+
+// -- AnimationPlayerSlotLengthMismatchError --------------------------------------
+
+/**
+ * Detail for `'animation-player-slot-length-mismatch'`.
+ *
+ * Carries the observed length of each of the four parallel SoA columns so an
+ * AI consumer can see which column desynced without parsing prose.
+ */
+export interface AnimationPlayerSlotLengthMismatchDetail {
+  readonly entity: number;
+  readonly clips: number;
+  readonly times: number;
+  readonly weights: number;
+  readonly speeds: number;
+}
+
+/**
+ * Structured error for AnimationPlayer parallel-column length disagreement.
+ *
+ * Emitted at advanceAnimationPlayer's evaluation entry when an entity's
+ * `clips` / `times` / `weights` / `speeds` columns do not all share the same
+ * length. Four-field surface (mirrors the errors/skin.ts convention):
+ *   - `.code = 'animation-player-slot-length-mismatch'`
+ *   - `.expected` -- clips/times/weights/speeds share one length
+ *   - `.hint` -- write all four columns length-synced on every AnimationPlayer
+ *     write (variable columns do not tail-pad a short write)
+ *   - `.detail = { entity, clips, times, weights, speeds }`
+ */
+export class AnimationPlayerSlotLengthMismatchError extends Error {
+  readonly code = 'animation-player-slot-length-mismatch' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: AnimationPlayerSlotLengthMismatchDetail;
+
+  constructor(detail: AnimationPlayerSlotLengthMismatchDetail) {
+    const { entity, clips, times, weights, speeds } = detail;
+    const expected = 'AnimationPlayer clips/times/weights/speeds columns share one length';
+    const hint = `entity ${entity} AnimationPlayer columns are length-desynced (clips=${clips}, times=${times}, weights=${weights}, speeds=${speeds}); write all four parallel columns at the same length on every AnimationPlayer write -- a variable array<T> column does not tail-pad a short write`;
+    super(
+      `AnimationPlayer slot length mismatch on entity ${entity}: clips=${clips}, times=${times}, weights=${weights}, speeds=${speeds}`,
+    );
+    this.name = 'AnimationPlayerSlotLengthMismatchError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = detail;
+  }
+}
+
+// -- AnimationPlayerErrorCode / AnimationPlayerError closed unions ----------------
+
+/**
+ * Closed union of AnimationPlayer-cluster error codes. AI users perform
+ * exhaustive `switch (err.code)` without default; TS guards completeness.
+ */
+export type AnimationPlayerErrorCode = 'animation-player-slot-length-mismatch';
+
+/**
+ * Closed union of the AnimationPlayer-cluster structured error classes, each
+ * carrying an `AnimationPlayerErrorCode` discriminant on `.code`.
+ */
+export type AnimationPlayerError = AnimationPlayerSlotLengthMismatchError;

package/src/plugin.ts

@@ -0,0 +1,73 @@
+import type { Component, World } from '@forgeax/engine-ecs';
+import type { Plugin } from '@forgeax/engine-plugin';
+import { AnimationPlayer } from './animation-player';
+import { AnimatedBy, AnimationTargetId, AnimationTargets } from './animation-target';
+import { registerAdvanceAnimationPlayer } from './systems/advance-animation-player';
+import {
+  type AnimationPayloadLookup,
+  registerEvaluateAnimationGraph,
+} from './systems/evaluate-animation-graph';
+
+const ANIMATION_COMPONENTS: readonly Component[] = [
+  AnimationPlayer,
+  AnimatedBy,
+  AnimationTargetId,
+  AnimationTargets,
+];
+
+function registerAnimationComponents(world: World): () => void {
+  const leases = ANIMATION_COMPONENTS.map((component) =>
+    world.components.register(component).unwrap(),
+  );
+  return () => {
+    for (let index = leases.length - 1; index >= 0; index -= 1) leases[index]?.dispose();
+  };
+}
+
+declare module '@forgeax/engine-plugin' {
+  interface EngineContextServices {
+    animationPayloads?: AnimationPayloadLookup;
+  }
+}
+
+/** Provide the realm's asset-backed animation payload resolver. */
+export function animationPayloadsPlugin(lookup: AnimationPayloadLookup): Plugin {
+  return {
+    name: 'animation-payloads',
+    provide: 'animationPayloads',
+    apply(ctx) {
+      ctx.provide('animationPayloads', lookup);
+    },
+  };
+}
+
+/** Install animation behavior from declared World and payload services. */
+export function animationRuntimePlugin(): Plugin {
+  return {
+    name: 'animation',
+    inject: ['world', 'animationPayloads'],
+    apply(ctx) {
+      ctx.effect(() => registerAnimationComponents(ctx.world), 'animation/components');
+      ctx.effect(
+        () => registerEvaluateAnimationGraph(ctx.world, ctx.animationPayloads),
+        'animation/evaluate-graph',
+      );
+      ctx.effect(() => registerAdvanceAnimationPlayer(ctx.world), 'animation/advance-player');
+    },
+  };
+}
+
+export function animationPlugin(lookup?: AnimationPayloadLookup): Plugin {
+  return {
+    name: 'animation',
+    inject: ['world'],
+    apply(ctx) {
+      ctx.effect(() => registerAnimationComponents(ctx.world), 'animation/components');
+      ctx.effect(
+        () => registerEvaluateAnimationGraph(ctx.world, lookup),
+        'animation/evaluate-graph',
+      );
+      ctx.effect(() => registerAdvanceAnimationPlayer(ctx.world), 'animation/advance-player');
+    },
+  };
+}

package/src/resolve-animation-asset.ts

@@ -0,0 +1,128 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { Asset, Handle, Result } from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+
+/** Closed animation-domain failure codes for durable GUID projection. */
+export type AnimationAssetErrorCode =
+  | 'animation-asset-not-found'
+  | 'animation-asset-stale'
+  | 'animation-asset-kind-mismatch';
+
+export interface AnimationAssetErrorDetail {
+  readonly guid: string;
+  readonly expectedKind: string;
+  readonly actualKind?: string;
+  readonly lookupCode: string;
+}
+
+type AnimationAssetTarget<T extends Asset> = T extends { readonly kind: 'animation-clip' }
+  ? 'AnimationClip'
+  : 'AnimationGraph';
+
+/** Structured failure at the animation consumer boundary. */
+export class AnimationAssetError extends Error {
+  readonly code: AnimationAssetErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: AnimationAssetErrorDetail;
+
+  constructor(args: {
+    code: AnimationAssetErrorCode;
+    expected: string;
+    hint: string;
+    detail: AnimationAssetErrorDetail;
+  }) {
+    super(`[AnimationAssetError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = 'AnimationAssetError';
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+}
+
+export interface ResolvedAnimationAsset<T extends Asset> {
+  readonly guid: string;
+  readonly asset: T;
+  readonly handle: Handle<AnimationAssetTarget<T>, 'shared'>;
+}
+
+export type AnimationAssetLookup<T extends Asset> = T | { readonly code: 'stale' } | undefined;
+
+/**
+ * Resolve a durable GUID through the caller's existing payload owner, then
+ * project that payload into the current World. The callback is deliberately a
+ * lookup seam, not a registry: AssetRegistry remains GUID -> payload only.
+ */
+export function resolveAnimationAsset<T extends Asset>(
+  world: World,
+  guid: string,
+  expectedKind: T['kind'],
+  lookup: (guid: string) => AnimationAssetLookup<T>,
+): Result<ResolvedAnimationAsset<T>, AnimationAssetError> {
+  if (guid.length === 0) {
+    return err(
+      new AnimationAssetError({
+        code: 'animation-asset-not-found',
+        expected: `a durable ${expectedKind} GUID`,
+        hint: 'load the animation asset by GUID before evaluating the graph',
+        detail: { guid, expectedKind, lookupCode: 'guid-empty' },
+      }),
+    );
+  }
+  let asset: AnimationAssetLookup<T>;
+  try {
+    asset = lookup(guid);
+  } catch {
+    return err(
+      new AnimationAssetError({
+        code: 'animation-asset-not-found',
+        expected: `a loaded ${expectedKind} payload for GUID ${guid}`,
+        hint: 'repair the animation asset lookup provider and retry resolution',
+        detail: { guid, expectedKind, lookupCode: 'lookup-threw' },
+      }),
+    );
+  }
+  if (asset !== undefined && 'code' in asset && asset.code === 'stale') {
+    return err(
+      new AnimationAssetError({
+        code: 'animation-asset-stale',
+        expected: `a current ${expectedKind} payload for GUID ${guid}`,
+        hint: 'rebuild the stale asset projection before evaluating the graph',
+        detail: { guid, expectedKind, lookupCode: 'asset-stale' },
+      }),
+    );
+  }
+  if (asset === undefined) {
+    return err(
+      new AnimationAssetError({
+        code: 'animation-asset-not-found',
+        expected: `a loaded ${expectedKind} payload for GUID ${guid}`,
+        hint: 'load or retain the referenced animation asset before evaluating the graph',
+        detail: { guid, expectedKind, lookupCode: 'asset-not-found' },
+      }),
+    );
+  }
+  const payload = asset as T;
+  if (payload.kind !== expectedKind) {
+    return err(
+      new AnimationAssetError({
+        code: 'animation-asset-kind-mismatch',
+        expected: `asset kind '${expectedKind}'`,
+        hint: `replace GUID ${guid} with a loaded ${expectedKind} asset`,
+        detail: {
+          guid,
+          expectedKind,
+          actualKind: payload.kind,
+          lookupCode: 'asset-kind-mismatch',
+        },
+      }),
+    );
+  }
+  const target = expectedKind === 'animation-clip' ? 'AnimationClip' : 'AnimationGraph';
+  const handle = world.internSharedRef(target, payload) as Handle<
+    AnimationAssetTarget<T>,
+    'shared'
+  >;
+  return ok({ guid, asset: payload, handle });
+}