@forgeax/engine-ecs 0.1.2

package/src/errors/sprite-and-shared-errors.ts

@@ -0,0 +1,231 @@
+/**
+ * feat-20260713-mount-override-component-add-and-shared-ref-round M2 / w9 —
+ * `.code = 'shared-field-invalid-value'`.
+ *
+ * A `shared<T>` scalar / `array<shared<T>>` element must be a resolved numeric
+ * Handle. A raw GUID string / `{ guid }` / `{ kind }` object (the
+ * pre-resolution shape a sidecar hands an AI user) used to be silently coerced
+ * to the all-zero sentinel by the column packer / scalar write path, so a
+ * mis-bound reference read back as `0` / `[0,0,0,0]` and rendered blank with no
+ * error. `validateComponentDataKeys` only checks key NAMES, not value types;
+ * this error closes the value-type gap at all three write entries
+ * (spawn / addComponent / set). `.detail.field` + `.detail.fieldType` name the
+ * offending field; `.detail.index` locates the array element (undefined for the
+ * scalar form).
+ *
+ * `.detail = { component, field, fieldType, actualValue, index? }`
+ * `.hint` — names the field and points at `AssetRegistry.load + allocSharedRef`.
+ */
+export class SharedFieldInvalidValueError extends Error {
+  override readonly name = 'SharedFieldInvalidValueError';
+  readonly code = 'shared-field-invalid-value' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: {
+    readonly component: string;
+    readonly field: string;
+    readonly fieldType: string;
+    readonly actualValue: unknown;
+    readonly index?: number;
+  };
+
+  constructor(
+    componentName: string,
+    fieldName: string,
+    fieldType: string,
+    actualValue: unknown,
+    index?: number,
+  ) {
+    const at = index === undefined ? '' : `[${index}]`;
+    const expected = `a resolved numeric Handle for shared field '${fieldName}${at}'`;
+    const hint =
+      `'${fieldName}${at}' on '${componentName}' is a ${fieldType} reference; ` +
+      `got ${typeof actualValue} (${JSON.stringify(actualValue)}). ` +
+      `Resolve the GUID to a handle first: AssetRegistry.load(guid, kind) then allocSharedRef(...), ` +
+      `and bind the returned numeric handle — not the raw GUID / sidecar object.`;
+    super(
+      `${componentName}.${fieldName}${at}: shared field bound to a non-handle value.\n` +
+        `  code: shared-field-invalid-value\n` +
+        `  component: ${componentName}\n` +
+        `  field: ${fieldName}${at}\n` +
+        `  fieldType: ${fieldType}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail =
+      index === undefined
+        ? { component: componentName, field: fieldName, fieldType, actualValue }
+        : { component: componentName, field: fieldName, fieldType, actualValue, index };
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// feat-20260625-sprite-instances-and-tilemap-terrain-static-batch M1 / w2 —
+// closed-union evolution +3 for the SpriteInstances primitive + tilemap
+// terrain static-batch path. AGENTS.md §Error model evolution contract: minor
+// (add member only).
+//
+// All 3 codes are DECLARED here (M1) but FIRED at the render-system-extract
+// QueryRow loop (M3 w13) — plan-strategy D-6 "fail-fast at the render
+// domain entry, not at ECS spawn-time (avoids reverse dep ECS -> AssetRegistry
+// to look up MaterialAsset.shadingModel)". M1 carries class declarations only;
+// the `_routeError` call sites land in M3.
+//
+// Three codes, three failure shapes:
+//   - 'sprite-instances-count-mismatch' — transforms.length / 16 !==
+//     regions.length / 4 (stride contract; cf. instance-transforms-stride-
+//     mismatch which guards Instances stride 16).
+//   - 'sprite-instances-requires-sprite-shader' — the entity's MaterialAsset's
+//     first pass shader is not 'forgeax::sprite' (extract-time check; AI users
+//     using SpriteInstances must pick a sprite-shaded material).
+//   - 'sprite-instances-mutually-exclusive-with-instances' — the same entity
+//     carries both Instances + SpriteInstances (the two primitives are peers;
+//     SpriteInstances supersedes Instances when per-instance UV region is
+//     needed).
+//
+// .hint follows charter P3: each contains the literal repair step AI users
+// can paste back into spawn code (transforms/regions stride math; shading
+// model field write; component removal).
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Thrown / returned via Layer-3 error route when `SpriteInstances.transforms`
+ * (stride 16 — column-major mat4 per instance) and `SpriteInstances.regions`
+ * (stride 4 — per-instance UV vec4) instance counts disagree at render-system-
+ * extract entry.
+ *
+ * `.code = 'sprite-instances-count-mismatch'`
+ * `.detail = { transformsLength, regionsLength, expectedStride: { transforms: 16, regions: 4 } }`
+ * `.hint` — instructs the AI user to enforce
+ *   `transforms.length / 16 === regions.length / 4`.
+ */
+export class SpriteInstancesCountMismatchError extends Error {
+  override readonly name = 'SpriteInstancesCountMismatchError';
+  readonly code = 'sprite-instances-count-mismatch' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: {
+    readonly code: 'sprite-instances-count-mismatch';
+    readonly transformsLength: number;
+    readonly regionsLength: number;
+    readonly expectedStride: { readonly transforms: 16; readonly regions: 4 };
+  };
+
+  constructor(transformsLength: number, regionsLength: number) {
+    const hint =
+      'SpriteInstances.transforms (stride 16) and SpriteInstances.regions (stride 4) ' +
+      'must describe the same instance count: ensure transforms.length / 16 === regions.length / 4 ' +
+      'at the spawn / set site (resize both arrays together).';
+    const expected = 'transforms.length / 16 === regions.length / 4';
+    super(
+      `SpriteInstances: per-instance count mismatch between transforms and regions.\n` +
+        `  code: sprite-instances-count-mismatch\n` +
+        `  transformsLength: ${transformsLength} (count = ${transformsLength / 16})\n` +
+        `  regionsLength: ${regionsLength} (count = ${regionsLength / 4})\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = {
+      code: 'sprite-instances-count-mismatch',
+      transformsLength,
+      regionsLength,
+      expectedStride: { transforms: 16, regions: 4 },
+    };
+  }
+}
+
+/**
+ * Thrown / returned via Layer-3 error route when an entity carrying
+ * `SpriteInstances` references a MaterialAsset whose first pass shader is not
+ * `'forgeax::sprite'`. Detected at render-system-extract entry (M3 w13).
+ *
+ * `.code = 'sprite-instances-requires-sprite-shader'`
+ * `.detail = { entityId, observedMaterialShaderId }`
+ * `.hint` — instructs the AI user to bind a MaterialAsset whose first pass
+ *   `shader` is `'forgeax::sprite'` or `'forgeax::sprite-lit'`.
+ *
+ * feat-20260624-sprite-lit-shading-model-pure-2d-lighting M1' / t6:
+ * sprite-lit walks the same per-instance UV region vertex path as sprite
+ * (VsOut byte-identical, paramSchema mirror); both shader ids are accepted.
+ */
+export class SpriteInstancesRequiresSpriteShaderError extends Error {
+  override readonly name = 'SpriteInstancesRequiresSpriteShaderError';
+  readonly code = 'sprite-instances-requires-sprite-shader' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: {
+    readonly code: 'sprite-instances-requires-sprite-shader';
+    readonly entityId: number;
+    readonly observedMaterialShaderId: string;
+  };
+
+  constructor(entityId: number, observedMaterialShaderId: string) {
+    const hint =
+      "bind a MaterialAsset whose first pass `shader` is 'forgeax::sprite' " +
+      "or 'forgeax::sprite-lit' to this entity's MeshRenderer (SpriteInstances " +
+      'requires a sprite-family shader so the per-instance UV region is consumed ' +
+      'by the sprite vertex shader path).';
+    const expected =
+      "MaterialAsset.passes[0].shader === 'forgeax::sprite' || 'forgeax::sprite-lit'";
+    super(
+      `SpriteInstances: entity ${entityId} requires a sprite-shaded MaterialAsset.\n` +
+        `  code: sprite-instances-requires-sprite-shader\n` +
+        `  entityId: ${entityId}\n` +
+        `  observedMaterialShaderId: ${observedMaterialShaderId}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = {
+      code: 'sprite-instances-requires-sprite-shader',
+      entityId,
+      observedMaterialShaderId,
+    };
+  }
+}
+
+/**
+ * Thrown / returned via Layer-3 error route when the same entity carries both
+ * `Instances` (3D per-instance mat4) and `SpriteInstances` (2D per-instance
+ * mat4 + UV region). The two primitives are peers — pick one. Detected at
+ * render-system-extract entry (M3 w13).
+ *
+ * `.code = 'sprite-instances-mutually-exclusive-with-instances'`
+ * `.detail = { entityId }`
+ * `.hint` — instructs the AI user to remove one of the two components.
+ */
+export class SpriteInstancesMutuallyExclusiveWithInstancesError extends Error {
+  override readonly name = 'SpriteInstancesMutuallyExclusiveWithInstancesError';
+  readonly code = 'sprite-instances-mutually-exclusive-with-instances' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: {
+    readonly code: 'sprite-instances-mutually-exclusive-with-instances';
+    readonly entityId: number;
+  };
+
+  constructor(entityId: number) {
+    const hint =
+      'remove Instances or replace with SpriteInstances; SpriteInstances supersedes ' +
+      'Instances when per-instance region is needed.';
+    const expected = 'entity carries Instances XOR SpriteInstances (not both)';
+    super(
+      `SpriteInstances: entity ${entityId} carries both Instances and SpriteInstances.\n` +
+        `  code: sprite-instances-mutually-exclusive-with-instances\n` +
+        `  entityId: ${entityId}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = {
+      code: 'sprite-instances-mutually-exclusive-with-instances',
+      entityId,
+    };
+  }
+}

package/src/errors/validation-errors.ts

@@ -0,0 +1,418 @@
+import type { Component, ComponentSchema, FieldReflection } from '../component';
+import { componentDefinition } from '../component-schema';
+
+export class TimeDeltaInvalidError extends Error {
+  override readonly name = 'TimeDeltaInvalidError';
+  readonly code = 'time-delta-invalid' as const;
+  readonly expected = 'a finite delta greater than or equal to 0';
+  readonly hint = 'Call world.update(deltaSeconds) with a finite non-negative delta.';
+  readonly detail: { readonly received: number };
+
+  constructor(received: number) {
+    super(
+      `Invalid world.update delta: ${received}.\n  expected: a finite delta greater than or equal to 0\n  hint: Call world.update(deltaSeconds) with a finite non-negative delta.`,
+    );
+    this.detail = { received };
+  }
+}
+
+export class TimeConfigInvalidError extends Error {
+  override readonly name = 'TimeConfigInvalidError';
+  readonly code = 'time-config-invalid' as const;
+  readonly expected: string;
+  readonly hint = 'Increase maxDeltaSeconds or decrease maxStepsPerUpdate or fixedDeltaSeconds.';
+  readonly detail: {
+    readonly fixedDeltaSeconds: number;
+    readonly maxStepsPerUpdate: number;
+    readonly maxDeltaSeconds: number;
+  };
+
+  constructor(detail: TimeConfigInvalidError['detail']) {
+    const expected = 'maxDeltaSeconds >= (maxStepsPerUpdate + 1) * fixedDeltaSeconds';
+    super(
+      `Invalid World time policy.\n  expected: ${expected}\n  hint: Increase maxDeltaSeconds or decrease maxStepsPerUpdate or fixedDeltaSeconds.`,
+    );
+    this.expected = expected;
+    this.detail = detail;
+  }
+}
+
+export class ScheduleScopeMismatchError extends Error {
+  override readonly name = 'ScheduleScopeMismatchError';
+  readonly code = 'schedule-scope-mismatch' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: {
+    readonly sourceSchedule: string;
+    readonly targetSchedule: string;
+    readonly reference?: string;
+  };
+
+  constructor(sourceSchedule: string, targetSchedule: string, reference?: string) {
+    const expected = `a reference owned by ${sourceSchedule}`;
+    const hint = `The referenced item belongs to ${targetSchedule}; register and order it in ${sourceSchedule}.`;
+    super(`Schedule scope mismatch.\n  expected: ${expected}\n  hint: ${hint}`);
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { sourceSchedule, targetSchedule, ...(reference ? { reference } : {}) };
+  }
+}
+
+/**
+ * Returned when a closed enum field receives a value outside its reflected
+ * labels. The write owner runs this before any archetype or column mutation.
+ */
+export class ComponentFieldInvalidValueError extends Error {
+  override readonly name = 'ComponentFieldInvalidValueError';
+  readonly code = 'component-field-invalid-value' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: {
+    readonly entity: number | undefined;
+    readonly component: string;
+    readonly field: string;
+    readonly received: unknown;
+    readonly allowedValues: Readonly<Record<string, number>>;
+  };
+
+  constructor(
+    entity: number | undefined,
+    component: string,
+    field: string,
+    received: unknown,
+    allowedValues: Readonly<Record<string, number>>,
+  ) {
+    const entries = Object.entries(allowedValues)
+      .map(([label, value]) => `${label}=${value}`)
+      .join(', ');
+    const expected = `${component}.${field} in { ${entries} }`;
+    const hint = `Set ${component}.${field} to one of the reflected enum values: ${entries}`;
+    super(
+      `${component}.${field} received an invalid enum value.\n` +
+        `  code: component-field-invalid-value\n` +
+        `  component: ${component}\n` +
+        `  field: ${field}\n` +
+        `  received: ${String(received)}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { entity, component, field, received, allowedValues };
+  }
+}
+
+/**
+ * Returned before an ECS write when a managed `array<T>` field receives a
+ * value that the storage boundary cannot interpret as an array payload. The
+ * old column writer treated arbitrary objects as an empty payload, which
+ * silently changed the row while retaining no evidence of the caller error.
+ */
+export class ManagedArrayInvalidValueError extends Error {
+  override readonly name = 'ManagedArrayInvalidValueError';
+  readonly code = 'managed-array-invalid-value' as const;
+  readonly expected = 'an Array or TypedArray payload (or null/undefined to clear it)';
+  readonly hint: string;
+  readonly detail: {
+    readonly component: string;
+    readonly field: string;
+    readonly fieldType: string;
+    readonly actualValue: unknown;
+  };
+
+  constructor(componentName: string, fieldName: string, fieldType: string, actualValue: unknown) {
+    const hint =
+      `Set ${componentName}.${fieldName} to a plain array or TypedArray matching ` +
+      `${fieldType}; use null or undefined to clear the managed value.`;
+    super(
+      `${componentName}.${fieldName}: managed array received an invalid value.\n` +
+        `  code: managed-array-invalid-value\n` +
+        `  fieldType: ${fieldType}\n` +
+        `  expected: an Array or TypedArray payload (or null/undefined to clear it)\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.detail = { component: componentName, field: fieldName, fieldType, actualValue };
+  }
+}
+
+/**
+ * Validate the closed enum fields present in a write payload. Enums without
+ * labels remain open numeric fields for compatibility with existing schemas.
+ */
+export function validateEnumFieldValues<S extends ComponentSchema>(
+  component: Component<string, S>,
+  raw: Partial<Record<string, unknown>> | undefined,
+  entity?: number,
+): ComponentFieldInvalidValueError | null {
+  if (raw === undefined) return null;
+  const fields = componentDefinition(component).fields as Readonly<Record<string, FieldReflection>>;
+  const rawValues = raw as Record<string, unknown>;
+  for (const fieldName of Object.keys(rawValues)) {
+    const reflection = fields[fieldName];
+    if (reflection?.type !== 'enum' || reflection.labels === undefined) continue;
+    const value = rawValues[fieldName];
+    const allowedValues = Object.values(reflection.labels);
+    if (typeof value !== 'number' || !Number.isInteger(value) || !allowedValues.includes(value)) {
+      return new ComponentFieldInvalidValueError(
+        entity,
+        component.name,
+        fieldName,
+        value,
+        reflection.labels,
+      );
+    }
+  }
+  return null;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// feat-20260519-light-casters-point-spot-pbr w2 — closed-union evolution +1.
+//
+// Adds 1 new member 'spawn-light-invalid-bounds' to EcsErrorCode (23 -> 24).
+// AGENTS.md section Error model evolution contract: minor (add member only).
+// Triggered by PointLight / SpotLight spawn-time payload validation
+// (plan-strategy D-S3 a). detail.field three-branch
+// ('range' | 'innerOuter' | 'outerNinety') keeps the four bound-violation
+// shapes under one error code so callers narrow first on `.code` then on
+// `.detail.field` (charter P3 progressive disclosure).
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returned via `Result.err` from `world.spawn` when a PointLight or SpotLight
+ * payload field is out of the documented bound. Four bound violations share
+ * one `.code` and discriminate via `.detail.field`:
+ *
+ * - `range` — PointLight / SpotLight `range < 0` or `Number.isNaN(range)`.
+ *   Use `Number.POSITIVE_INFINITY` for an unlimited range or a non-negative
+ *   meter value.
+ * - `innerOuter` — SpotLight `outerConeDeg <= innerConeDeg`. Inner cone is
+ *   the saturated bright region; outer cone is the falloff edge.
+ * - `outerNinety` — SpotLight `outerConeDeg > 90`. KHR_lights_punctual upper
+ *   bound. A spot light cone wider than 90 degrees becomes a point light;
+ *   use PointLight instead.
+ * - `direction` — DirectionalLight / SpotLight `direction` is missing or a
+ *   zero vector `[0, 0, 0]`. Direction has no default (there is no universal
+ *   default direction): omitting it lands the array layer-3 all-zero, which is
+ *   the same illegal state as an explicit zero vector. Supply a non-zero
+ *   direction (feat-20260709 M2 / D-1, add-only union member).
+ *
+ * `.code = 'spawn-light-invalid-bounds'`
+ * `.detail.field` is derived from `keyof typeof SPAWN_LIGHT_INVALID_BOUNDS_POLICY`;
+ * `.detail.got` is `number | readonly number[]`.
+ * `.hint` — names the offending field plus the valid replacement form.
+ */
+const SPAWN_LIGHT_INVALID_BOUNDS_POLICY = {
+  range: {
+    expected: 'range >= 0 or Number.POSITIVE_INFINITY',
+    hint: (componentName: string, got: number | readonly number[]) =>
+      `${componentName}.range = ${got} is invalid; use Number.POSITIVE_INFINITY for unlimited range, or a non-negative meter value`,
+  },
+  innerOuter: {
+    expected: 'outerConeDeg > innerConeDeg',
+    hint: (componentName: string, got: number | readonly number[]) =>
+      `${componentName}.outerConeDeg <= innerConeDeg (got ${got}); inner cone is the saturated bright region, outer cone is the falloff edge; outerConeDeg > innerConeDeg required`,
+  },
+  outerNinety: {
+    expected: 'outerConeDeg <= 90 (KHR_lights_punctual upper bound)',
+    hint: (componentName: string, got: number | readonly number[]) =>
+      `${componentName}.outerConeDeg = ${got} > 90; a spot light cone wider than 90 degrees becomes a point light; use PointLight instead`,
+  },
+  direction: {
+    expected: 'direction is a non-zero [x, y, z] vector',
+    hint: (componentName: string, got: number | readonly number[]) =>
+      `${componentName}.direction is missing or a zero vector (got ${JSON.stringify(got)}); direction has no default, provide a non-zero direction, e.g. [-0.5, -1, -0.3]`,
+  },
+} satisfies Record<
+  string,
+  {
+    readonly expected: string;
+    readonly hint: (componentName: string, got: number | readonly number[]) => string;
+  }
+>;
+
+export class SpawnLightInvalidBoundsError extends Error {
+  override readonly name = 'SpawnLightInvalidBoundsError';
+  readonly code = 'spawn-light-invalid-bounds' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: {
+    readonly field: keyof typeof SPAWN_LIGHT_INVALID_BOUNDS_POLICY;
+    readonly got: number | readonly number[];
+  };
+
+  constructor(
+    componentName: string,
+    field: keyof typeof SPAWN_LIGHT_INVALID_BOUNDS_POLICY,
+    got: number | readonly number[],
+  ) {
+    const policy = SPAWN_LIGHT_INVALID_BOUNDS_POLICY[field];
+    const hint = policy.hint(componentName, got);
+    const expectedStr = policy.expected;
+    super(
+      `${componentName}: spawn payload bound violation.\n` +
+        `  code: spawn-light-invalid-bounds\n` +
+        `  component: ${componentName}\n` +
+        `  field: ${field}\n` +
+        `  got: ${got}\n` +
+        `  expected: ${expectedStr}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expectedStr;
+    this.detail = { field, got };
+  }
+}
+
+/**
+ * Returned via `Result.err` from resource-setter helpers (e.g.
+ * `setTransparentSortConfig`) when a numeric payload field violates the
+ * closed bound declared by the resource contract. The first consumer is
+ * `TransparentSortConfig.mode ∈ {0, 1, 2}` (plan-strategy D-4); future
+ * resource validators with the same shape reuse this code by routing
+ * through `.detail.receivedKey` to disambiguate which resource validator
+ * surfaced the failure.
+ *
+ * Closed-set kebab code consistent with `spawn-light-invalid-bounds`
+ * (feat-20260519 / w2); AI users consume via `switch (err.code)` exhaustive
+ * narrows + `err.detail.receivedMode` (or `err.detail.receivedKey` /
+ * `err.expected`) property access — never string-parse the message.
+ *
+ * `.code = 'resource-invalid-value'`
+ * `.detail = { receivedMode: number; receivedKey?: string }`
+ * `.hint` — direct copy-paste recovery (e.g. "0=layer-z, 1=layer-y,
+ *   2=layer-yz" for the sort-config case).
+ * `.expected` — the bound contract literal (e.g. "mode ∈ {0, 1, 2}").
+ *
+ * @reuses RhiError structured shape — same `.code / .expected / .hint /
+ *   .detail` quadruple AI users consume across rhi + ecs.
+ */
+export class ResourceInvalidValueError extends Error {
+  override readonly name = 'ResourceInvalidValueError';
+  readonly code = 'resource-invalid-value' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: { readonly receivedMode: number; readonly receivedKey?: string };
+
+  constructor(
+    expected: string,
+    hint: string,
+    detail: { readonly receivedMode: number; readonly receivedKey?: string },
+  ) {
+    const keyClause = detail.receivedKey === undefined ? '' : `  key: ${detail.receivedKey}\n`;
+    super(
+      `resource: invalid value.\n` +
+        `  code: resource-invalid-value\n` +
+        keyClause +
+        `  receivedMode: ${detail.receivedMode}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = detail;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// feat-20260521-sprite-atlas-animation M1 T-05 — closed-union evolution +1.
+//
+// Adds 1 new member 'sprite-animation-invalid' to EcsErrorCode (25 -> 26).
+// AGENTS.md §Error model evolution contract: minor (add member only).
+// Same-shape add-only mirror of SpawnLightInvalidBoundsError (feat-20260519
+// w2 line 736-776) and ResourceInvalidValueError (feat-20260520 w13 line
+// 862) — the kebab `'<noun>-invalid-...'` series keeps `switch (err.code)`
+// exhaustive narrows visually consistent (charter P4 consistent abstraction;
+// research F-7 candidate A).
+//
+// Triggered by `spriteAnimationTickSystem` (packages/runtime/src/systems/
+// sprite-animation-tick.ts, landed in M4 T-23) when an entity's
+// `SpriteAnimation` row violates one of two runtime invariants:
+//
+//   - field='regions-length' -> `regions.length !== frameCount * 4`
+//   - field='frame-duration' -> `frameDuration <= 0`
+//
+// `.detail.field` two-branch (charter P3: AI users branch once on
+// `err.code` and once on `err.detail.field` to reach the recovery hint
+// without parsing the message). Plan-strategy section 2 D-1 binds the
+// detail field shape; M4 T-19 / T-20 / T-21 cover the runtime fail-fast
+// paths end-to-end.
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returned via `Result.err` from `spriteAnimationTickSystem` (M4 T-23) when
+ * an entity's `SpriteAnimation` row violates a runtime invariant.
+ * Two invariants share one `.code` and discriminate via `.detail.field`:
+ *
+ * - `regions-length` — `SpriteAnimation.regions.length !== frameCount * 4`.
+ *   `regions` packs `[uMin, vMin, uW, vH]` per frame so the length must be
+ *   exactly `frameCount * 4`. Detail carries the offending `regionsLength`
+ *   alongside the declared `frameCount` so the hint can spell the exact
+ *   delta in callsite-friendly numbers.
+ * - `frame-duration` — `SpriteAnimation.frameDuration <= 0` (covers both
+ *   `frameDuration === 0` and `frameDuration < 0`; T-21 binds the negative
+ *   case to the same arm so AI users handle both via a single
+ *   `if (err.detail.field === 'frame-duration')` branch — charter P4
+ *   consistent abstraction).
+ *
+ * `.code = 'sprite-animation-invalid'`
+ * `.detail = { field: 'regions-length', regionsLength, frameCount } |
+ *            { field: 'frame-duration', frameDuration }`
+ *
+ * Two top-level detail variants give each `.field` branch its own
+ * required sub-field shape so AI users get strong narrowing inside
+ * `switch (err.detail.field)` without optional sub-fields bleeding
+ * across branches (mirrors `SpawnLightInvalidBoundsError`'s shared
+ * `got: number` shape but adapted because regions-length /
+ * frame-duration carry different sub-field counts).
+ *
+ * `.hint` — names the offending invariant plus the valid replacement form.
+ */
+export class SpriteAnimationInvalidError extends Error {
+  override readonly name = 'SpriteAnimationInvalidError';
+  readonly code = 'sprite-animation-invalid' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail:
+    | {
+        readonly field: 'regions-length';
+        readonly regionsLength: number;
+        readonly frameCount: number;
+      }
+    | {
+        readonly field: 'frame-duration';
+        readonly frameDuration: number;
+      };
+
+  private static resolvePolicy(detail: SpriteAnimationInvalidError['detail']): {
+    readonly expected: string;
+    readonly hint: string;
+  } {
+    switch (detail.field) {
+      case 'regions-length':
+        return {
+          expected: 'SpriteAnimation.regions.length === frameCount * 4',
+          hint: `SpriteAnimation.regions.length = ${detail.regionsLength} does not match frameCount * 4 = ${detail.frameCount * 4}; pack 4 floats [uMin, vMin, uW, vH] per frame (see <name>.atlas.meta.json sidecar 'regions' map)`,
+        };
+      case 'frame-duration':
+        return {
+          expected: 'SpriteAnimation.frameDuration > 0',
+          hint: `SpriteAnimation.frameDuration = ${detail.frameDuration} is invalid; use a positive seconds-per-frame value (e.g. 0.1 = 10 fps)`,
+        };
+    }
+  }
+
+  constructor(detail: SpriteAnimationInvalidError['detail']) {
+    const policy = SpriteAnimationInvalidError.resolvePolicy(detail);
+    super(
+      `SpriteAnimation: invariant violated.\n` +
+        `  code: sprite-animation-invalid\n` +
+        `  field: ${detail.field}\n` +
+        `  expected: ${policy.expected}\n` +
+        `  hint: ${policy.hint}`,
+    );
+    this.hint = policy.hint;
+    this.expected = policy.expected;
+    this.detail = detail;
+  }
+}