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

package/dist/errors/validation-errors.d.ts

@@ -0,0 +1,229 @@
+import type { Component, ComponentSchema } from '../component';
+export declare class TimeDeltaInvalidError extends Error {
+    readonly name = "TimeDeltaInvalidError";
+    readonly code: "time-delta-invalid";
+    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);
+}
+export declare class TimeConfigInvalidError extends Error {
+    readonly name = "TimeConfigInvalidError";
+    readonly code: "time-config-invalid";
+    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']);
+}
+export declare class ScheduleScopeMismatchError extends Error {
+    readonly name = "ScheduleScopeMismatchError";
+    readonly code: "schedule-scope-mismatch";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly sourceSchedule: string;
+        readonly targetSchedule: string;
+        readonly reference?: string;
+    };
+    constructor(sourceSchedule: string, targetSchedule: string, reference?: string);
+}
+/**
+ * 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 declare class ComponentFieldInvalidValueError extends Error {
+    readonly name = "ComponentFieldInvalidValueError";
+    readonly code: "component-field-invalid-value";
+    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>>);
+}
+export declare class ComponentNumericValueInvalidError extends Error {
+    readonly name = "ComponentNumericValueInvalidError";
+    readonly code: "component-numeric-value-invalid";
+    readonly expected = "a numeric value other than NaN";
+    readonly hint: string;
+    readonly detail: {
+        readonly entity: number | undefined;
+        readonly component: string;
+        readonly field: string;
+        readonly received: number;
+        readonly index?: number;
+    };
+    constructor(entity: number | undefined, component: string, field: string, received: number, index?: number);
+}
+export declare function validateNumericFieldValues<S extends ComponentSchema>(component: Component<string, S>, raw: Partial<Record<string, unknown>> | undefined, entity?: number): ComponentNumericValueInvalidError | null;
+/**
+ * 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 declare class ManagedArrayInvalidValueError extends Error {
+    readonly name = "ManagedArrayInvalidValueError";
+    readonly code: "managed-array-invalid-value";
+    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);
+}
+/**
+ * Validate the closed enum fields present in a write payload. Enums without
+ * labels remain open numeric fields for compatibility with existing schemas.
+ */
+export declare function validateEnumFieldValues<S extends ComponentSchema>(component: Component<string, S>, raw: Partial<Record<string, unknown>> | undefined, entity?: number): ComponentFieldInvalidValueError | null;
+/**
+ * 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.
+ */
+declare const SPAWN_LIGHT_INVALID_BOUNDS_POLICY: {
+    range: {
+        expected: string;
+        hint: (componentName: string, got: number | readonly number[]) => string;
+    };
+    innerOuter: {
+        expected: string;
+        hint: (componentName: string, got: number | readonly number[]) => string;
+    };
+    outerNinety: {
+        expected: string;
+        hint: (componentName: string, got: number | readonly number[]) => string;
+    };
+    direction: {
+        expected: string;
+        hint: (componentName: string, got: number | readonly number[]) => string;
+    };
+};
+export declare class SpawnLightInvalidBoundsError extends Error {
+    readonly name = "SpawnLightInvalidBoundsError";
+    readonly code: "spawn-light-invalid-bounds";
+    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[]);
+}
+/**
+ * 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 declare class ResourceInvalidValueError extends Error {
+    readonly name = "ResourceInvalidValueError";
+    readonly code: "resource-invalid-value";
+    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;
+    });
+}
+/**
+ * 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 declare class SpriteAnimationInvalidError extends Error {
+    readonly name = "SpriteAnimationInvalidError";
+    readonly code: "sprite-animation-invalid";
+    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;
+    constructor(detail: SpriteAnimationInvalidError['detail']);
+}
+export {};
+//# sourceMappingURL=validation-errors.d.ts.map

package/dist/errors/validation-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-errors.d.ts","sourceRoot":"","sources":["../../src/errors/validation-errors.ts"],"names":[],"mappings":"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"}