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

package/dist/errors.d.ts

@@ -0,0 +1,763 @@
+import type { QuerySpanUnavailableReason } from './errors/query-and-component-errors';
+export { ComponentNotDefinedError, QueryDataRequiresFieldsError, QueryDescriptorConflictError, QueryIterationActiveError, QueryIterationInvalidatedError, QuerySpanUnavailableError, type QuerySpanUnavailableReason, RemoveEssentialComponentError, SpawnDataUnknownFieldError, } from './errors/query-and-component-errors';
+export { RelationshipDetachMismatchError, RelationshipMirrorComponentNotRegisteredError, RelationshipMirrorFieldTypeMismatchError, RelationshipSelfCycleError, RelationshipTargetReadonlyError, } from './errors/relationship-errors';
+export { SharedFieldInvalidValueError, SpriteInstancesCountMismatchError, SpriteInstancesMutuallyExclusiveWithInstancesError, SpriteInstancesRequiresSpriteShaderError, } from './errors/sprite-and-shared-errors';
+export { ComponentFieldInvalidValueError, ComponentNumericValueInvalidError, ManagedArrayInvalidValueError, ResourceInvalidValueError, ScheduleScopeMismatchError, SpawnLightInvalidBoundsError, SpriteAnimationInvalidError, TimeConfigInvalidError, TimeDeltaInvalidError, validateEnumFieldValues, validateNumericFieldValues, } from './errors/validation-errors';
+export { SharedKernelEligibilityError, SharedKernelFailureError, WorldPoisonedError, } from './execution/shared-kernel';
+/**
+ * Thrown when an attempt is made to encode an entity index that does not fit
+ * in 24 bits (i.e. >= 2^24 = 16_777_216).
+ *
+ * `.code = 'entity-index-overflow'`
+ * `.hint` — suggests reducing entity count or investigating leaks.
+ */
+export declare class EntityIndexOverflowError extends RangeError {
+    readonly name = "EntityIndexOverflowError";
+    readonly code: "entity-index-overflow";
+    readonly hint: string;
+    constructor(index: number);
+}
+/**
+ * Thrown when `defineComponent` is given a field type that is not in the
+ * supported scalar field type set.
+ *
+ * `.code = 'schema-unsupported-field'`
+ * `.hint` — lists all supported scalar field types.
+ */
+export declare class SchemaUnsupportedFieldError extends Error {
+    readonly name = "SchemaUnsupportedFieldError";
+    readonly code: "schema-unsupported-field";
+    readonly hint: string;
+    constructor(fieldName: string, fieldType: string);
+}
+export declare class SparseStorageRequiresTagError extends Error {
+    readonly name = "SparseStorageRequiresTagError";
+    readonly code: "sparse-storage-requires-tag";
+    readonly expected = "sparse components have an empty schema and no relationship metadata";
+    readonly hint = "remove all fields and relationship metadata, or use storage: table";
+    readonly detail: {
+        readonly componentName: string;
+    };
+    constructor(componentName: string);
+}
+/**
+ * Thrown (or returned via the `Result` err branch — `r.ok === false`, `r.error`)
+ * when get/set/addComponent/removeComponent is called on an entity that has
+ * been despawned (stale handle).
+ *
+ * `.code = 'stale-entity'`
+ * `.hint` — includes operation name, expected/actual generation, and component name.
+ * Enhanced fields: `.component`, `.operation`, `.expectedGeneration`, `.actualGeneration`.
+ */
+export declare class StaleEntityError extends Error {
+    readonly name = "StaleEntityError";
+    readonly code: "stale-entity";
+    readonly hint: string;
+    /** Component name involved in the operation (undefined when the operation does not target a specific component). */
+    readonly component: string | undefined;
+    /** The component-level operation that triggered this error (e.g. 'get' / 'set' / 'add' / 'remove'). Entity-level operations like `despawn` are not surfaced here — see `EntityHandle` lifecycle errors. */
+    readonly operation: string | undefined;
+    /** The generation the caller expected (from the entity handle). */
+    readonly expectedGeneration: number | undefined;
+    /**
+     * The actual generation found in the entity pool. `-1` is the sentinel
+     * value for entities never allocated (slot was never occupied), as opposed
+     * to allocated-then-despawned entities which carry a real (incremented)
+     * generation number.
+     */
+    readonly actualGeneration: number | undefined;
+    constructor(entityId: number, index: number, generation: number, enhanced?: {
+        component?: string;
+        operation: string;
+        expectedGeneration: number;
+        actualGeneration: number;
+    });
+}
+/**
+ * Returned via the `Result` err branch (`r.ok === false`, `r.error`) when
+ * addComponent tries to add a component that the entity already possesses.
+ *
+ * `.code = 'component-already-present'`
+ * `.hint` — suggests using `set()` to update values instead.
+ */
+export declare class ComponentAlreadyPresentError extends Error {
+    readonly name = "ComponentAlreadyPresentError";
+    readonly code: "component-already-present";
+    readonly hint: string;
+    constructor(entityId: number, componentName: string);
+}
+/**
+ * Returned via the `Result` err branch (`r.ok === false`, `r.error`) when
+ * removeComponent / set is called for a component the entity does not possess.
+ *
+ * `.code = 'component-not-present'`
+ * `.hint` — suggests checking with query or inspect().
+ */
+export declare class ComponentNotPresentError extends Error {
+    readonly name = "ComponentNotPresentError";
+    readonly code: "component-not-present";
+    readonly hint: string;
+    constructor(entityId: number, componentName: string);
+}
+/**
+ * Thrown when DAG Schedule detects a cyclic dependency among systems.
+ *
+ * `.code = 'cyclic-dependency'`
+ * `.hint` — includes the cycle path and suggests removing one constraint.
+ * `.detail` — `{ code: 'cyclic-dependency'; cycle: readonly string[] }` contains the
+ *    structured cycle path for programmatic consumption.
+ */
+export declare class CyclicDependencyError extends Error {
+    readonly name = "CyclicDependencyError";
+    readonly code: "cyclic-dependency";
+    readonly expected = "the schedule dependency graph is acyclic";
+    readonly hint: string;
+    /** Structured cycle path — programmatic consumers read this, not the message. */
+    readonly detail: {
+        readonly code: 'cyclic-dependency';
+        readonly cycle: readonly string[];
+    };
+    constructor(cycle: readonly string[]);
+}
+/**
+ * Returned via `Result.err` from `world.addSystems`
+ * when a SystemSet token fails local structural validation.
+ *
+ * The sole public invalid-token error type (D-2a). Covers all rejection
+ * scenarios: plain-object cast, unregistered name, stale token after
+ * overwrite, and cross-realm copies.
+ *
+ * `.code = 'system-set-not-registered'`
+ * `.expected` — the name of the unregistered token.
+ * `.hint` — suggests passing the current token to the owning World schedule.
+ * `.detail` — `{ code, name, registered }` where `registered` is a deterministic snapshot
+ *    of the current World-local schedule keys.
+ */
+export declare class SystemSetNotRegisteredError extends Error {
+    readonly name = "SystemSetNotRegisteredError";
+    readonly code: "system-set-not-registered";
+    /** The name carried by the rejected token. */
+    readonly expected: string;
+    readonly hint: string;
+    /** Deterministic snapshot of the current World-local schedule for repair. */
+    readonly detail: {
+        readonly code: 'system-set-not-registered';
+        readonly name: string;
+        readonly registered: readonly string[];
+    };
+    constructor(name: string, registered: readonly string[]);
+}
+/**
+ * Factory for {@link SystemSetNotRegisteredError}. Consumed by
+ * {@link validateSystemSetTokens} (w4) and the two mutation entry points.
+ */
+export declare function systemSetNotRegistered(name: string, registered: readonly string[]): SystemSetNotRegisteredError;
+/**
+ * Closed-set ScheduleMutationError code union (M2 — plan-strategy D-3).
+ *
+ * Schedule add-only API (`removeSystem` / `replaceSystem`) returns
+ * `Result<void, ScheduleMutationError>` carrying one of these codes. The
+ * `@forgeax/engine-remote` layer (M3) bridges these strings to JSON-RPC
+ * `RemoteErrorCode` 1:1 — keeping ECS free of console / wire dependencies.
+ *
+ * - `system-before-unknown` — name argument does not match any registered system.
+ * - `system-name-conflict`  — reserved for the M3 inject path; surfaced from
+ *   schedule when callers inject a name that already exists.
+ * - `cyclic-injection`      — schedule build detected a cycle introduced by
+ *   the mutation; carries the cycle path in `.detail.cycle`.
+ */
+export type ScheduleMutationErrorCode = 'system-before-unknown';
+export interface ScheduleMutationErrorDetail {
+    readonly cycle?: readonly string[];
+    readonly candidates?: readonly string[];
+}
+/**
+ * Returned via `Result.err` from `world.removeSystem` / `world.replaceSystem`.
+ *
+ * `.code` is the closed-set string SSOT consumed by the M3 console bridge;
+ * `.hint` carries an AI-friendly self-repair suggestion; `.detail` is the
+ * discriminated payload (cycle path for `cyclic-injection`, candidate list
+ * for `system-before-unknown`).
+ */
+export declare class ScheduleMutationError extends Error {
+    readonly name = "ScheduleMutationError";
+    readonly code: ScheduleMutationErrorCode;
+    readonly hint: string;
+    readonly detail: ScheduleMutationErrorDetail;
+    constructor(code: ScheduleMutationErrorCode, message: string, hint: string, detail?: ScheduleMutationErrorDetail);
+}
+/**
+ * Thrown when getResource is called with a key that does not exist.
+ *
+ * `.code = 'resource-not-found'`
+ * `.hint` — suggests using `world.insertResource()` first.
+ */
+export declare class ResourceNotFoundError extends Error {
+    readonly name = "ResourceNotFoundError";
+    readonly code: "resource-not-found";
+    readonly hint: string;
+    constructor(key: string);
+}
+export declare class ChangeEpochExhaustedError extends Error {
+    readonly name = "ChangeEpochExhaustedError";
+    readonly code: "change-epoch-exhausted";
+    readonly expected = "mutationEpoch < Number.MAX_SAFE_INTEGER";
+    readonly hint = "Rebuild the World before performing another mutation.";
+    readonly detail: {
+        readonly epoch: number;
+    };
+    constructor(epoch: number);
+}
+/**
+ * Thrown when insertResource/removeResource is called on a World-owned
+ * protected resource (Time or FixedTime).
+ *
+ * `.code = 'resource-protected'`
+ * `.hint` — suggests using `world.update(delta)` or reading the resource.
+ * `.expected` — the resource name that was rejected.
+ */
+export declare class ProtectedResourceError extends Error {
+    readonly name = "ProtectedResourceError";
+    readonly code: "resource-protected";
+    readonly hint: string;
+    readonly expected: string;
+    constructor(resourceName: string, operation: 'insert' | 'remove');
+}
+/**
+ * Thrown / returned via `Result.err` when UniqueRefStore.alloc encounters a
+ * slot whose refcount has already dropped to zero (sentinel for a released
+ * slot reused without re-init).
+ *
+ * `.code = 'unique-ref-released'`
+ * `.detail = { handle, target }`
+ * `.hint` — recommends checking handle lifetime against owner despawn.
+ */
+export declare class UniqueRefReleasedError extends Error {
+    readonly name = "UniqueRefReleasedError";
+    readonly code: "unique-ref-released";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly handle: number;
+        readonly target: string;
+    };
+    constructor(handle: number, target: string);
+}
+/**
+ * Thrown / returned via `Result.err` when UniqueRefStore.release is called on
+ * a handle whose refcount is already zero (double-free).
+ *
+ * `.code = 'unique-ref-double-release'`
+ * `.detail = { handle, target }`
+ * `.hint` — recommends auditing the release-loop entry points (set / removeComponent / despawn).
+ */
+export declare class UniqueRefDoubleReleaseError extends Error {
+    readonly name = "UniqueRefDoubleReleaseError";
+    readonly code: "unique-ref-double-release";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly handle: number;
+        readonly target: string;
+    };
+    constructor(handle: number, target: string);
+}
+/**
+ * Thrown / returned via `Result.err` when SharedRefStore.resolve / .retain is
+ * called on a handle whose refcount has already dropped to zero (slot released).
+ *
+ * `.code = 'shared-ref-released'`
+ * `.detail = { handle, target }`
+ * `.hint` — recommends checking handle lifetime against owner / consumer release.
+ */
+export declare class SharedRefReleasedError extends Error {
+    readonly name = "SharedRefReleasedError";
+    readonly code: "shared-ref-released";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly handle: number;
+        readonly target: string;
+    };
+    constructor(handle: number, target: string);
+}
+/**
+ * Thrown / returned via `Result.err` when SharedRefStore.release is called on
+ * a handle whose refcount is already zero (double-release). Distinct from the
+ * UniqueRef family because shared release is rc--, not direct slot drop —
+ * AI users debug this by reading `.detail.rc` (always 0 here) alongside the
+ * payload-presence signal.
+ *
+ * `.code = 'shared-ref-double-release'`
+ * `.detail = { handle, target, rc }`
+ * `.hint` — recommends auditing the producer / consumer release pairs.
+ */
+export declare class SharedRefDoubleReleaseError extends Error {
+    readonly name = "SharedRefDoubleReleaseError";
+    readonly code: "shared-ref-double-release";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly handle: number;
+        readonly target: string;
+        readonly rc: number;
+    };
+    constructor(handle: number, target: string, rc: number);
+}
+/** Raised before SharedRefStore mutates slot state for a nullish payload. */
+export declare class SharedRefPayloadInvalidError extends Error {
+    readonly name = "SharedRefPayloadInvalidError";
+    readonly code: "shared-ref-payload-invalid";
+    readonly expected = "a non-null, non-undefined shared payload";
+    readonly hint = "Allocate a concrete payload and let its owning effect dispose it.";
+    readonly detail: {
+        readonly target: string;
+        readonly actual: 'null' | 'undefined';
+    };
+    constructor(target: string, actual: 'null' | 'undefined');
+}
+/**
+ * Returned via `Result.err` when a builtin-tier slot (`slot < BUILTIN_BASE`)
+ * is passed to SharedRefStore.alloc / retain / release / resolve
+ * (feat-20260614 M6 D-15). The SharedRefStore manages ONLY user-tier slots
+ * (`>= BUILTIN_BASE`); builtin asset payloads are process-static and owned by
+ * the package that authored their builtin handle, never reference-counted by
+ * this World store.
+ *
+ * `.code = 'builtin-slot-not-owned'`
+ * `.detail = { slot }`
+ * `.hint` — points the caller back to the builtin handle owner.
+ */
+export declare class BuiltinSlotNotOwnedError extends Error {
+    readonly name = "BuiltinSlotNotOwnedError";
+    readonly code: "builtin-slot-not-owned";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly slot: number;
+    };
+    constructor(slot: number);
+}
+/**
+ * Returned via `Result.err` when SharedRefStore.resolve / .retain / .release
+ * is called with a handle whose generation no longer matches the store's
+ * current generation for that slot — the slot was released and re-allocated
+ * to a different payload. Distinct from `'shared-ref-released'` (slot empty,
+ * never re-allocated): stale means the slot IS live but belongs to a newer
+ * allocation.
+ *
+ * `.code = 'shared-ref-stale'`
+ * `.detail = { slot, expectedGeneration, actualGeneration }`
+ * `.hint` — recommends re-acquiring the handle from AssetRegistry.
+ */
+export declare class SharedRefStaleError extends Error {
+    readonly name = "SharedRefStaleError";
+    readonly code: "shared-ref-stale";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly slot: number;
+        readonly expectedGeneration: number;
+        readonly actualGeneration: number;
+    };
+    constructor(slot: number, expectedGeneration: number, actualGeneration: number);
+}
+/**
+ * Returned via `Result.err` when UniqueRefStore.resolve / .release is
+ * called with a handle whose generation no longer matches the store's
+ * current generation for that slot — the slot was released and re-allocated.
+ * Distinct from `'unique-ref-released'` (slot empty). UniqueRefStore has
+ * no retain method; the stale surface is resolve + release only.
+ *
+ * `.code = 'unique-ref-stale'`
+ * `.detail = { slot, expectedGeneration, actualGeneration }`
+ * `.hint` — recommends re-acquiring the handle from the producing system.
+ */
+export declare class UniqueRefStaleError extends Error {
+    readonly name = "UniqueRefStaleError";
+    readonly code: "unique-ref-stale";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly slot: number;
+        readonly expectedGeneration: number;
+        readonly actualGeneration: number;
+    };
+    constructor(slot: number, expectedGeneration: number, actualGeneration: number);
+}
+/**
+ * Thrown / returned via `Result.err` when BufferPool indexing reads or writes
+ * an offset outside the slot's `[0, size)` byte range. Triggers are limited
+ * to the `buffer:<N>` and managed-array-element-buffer paths; the
+ * `'string'` schema vocab no longer routes through this code (collapsed onto
+ * the managed-ref dispatch by feat-20260515-string-managed-collapse — JS
+ * string capacity is bounded by the host runtime, not by BufferPool buckets).
+ *
+ * `.code = 'managed-buffer-out-of-bounds'`
+ * `.detail = { index, size }`
+ * `.hint` — points at the field's `'buffer'` / `buffer<N>` schema declaration.
+ */
+export declare class ManagedBufferOutOfBoundsError extends RangeError {
+    readonly name = "ManagedBufferOutOfBoundsError";
+    readonly code: "managed-buffer-out-of-bounds";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly index: number;
+        readonly size: number;
+    };
+    constructor(index: number, size: number);
+}
+/**
+ * Thrown / returned via `Result.err` when BufferPool resize is asked to shrink
+ * a slot below its current allocated size — the pool only grows.
+ *
+ * `.code = 'managed-buffer-shrink-not-supported'`
+ * `.detail = { requested, current }`
+ * `.hint` — directs callers to allocate a fresh slot if a smaller buffer is needed.
+ */
+export declare class ManagedBufferShrinkNotSupportedError extends Error {
+    readonly name = "ManagedBufferShrinkNotSupportedError";
+    readonly code: "managed-buffer-shrink-not-supported";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly requested: number;
+        readonly current: number;
+    };
+    constructor(requested: number, current: number);
+}
+/**
+ * Returned via `Result.err` from `world.set` when a `buffer<N>` field is
+ * written with a `Uint8Array` whose `byteLength` does not equal the
+ * schema-declared fixed size `N`. AI users resize their payload to exactly
+ * `N` bytes (zero-pad or truncate at the producer) before calling `world.set`.
+ *
+ * `.code = 'fixed-size-mismatch'`
+ * `.detail = { expected, actual }`
+ * `.hint` — points at the producer's payload sizing.
+ */
+export declare class FixedSizeMismatchError extends Error {
+    readonly name = "FixedSizeMismatchError";
+    readonly code: "fixed-size-mismatch";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly expected: number;
+        readonly actual: number;
+    };
+    constructor(fieldName: string, expected: number, actual: number);
+}
+/**
+ * Surfaced via the Layer-3 ErrorHandler from
+ * `packages/runtime/src/render-system-extract.ts` defensive entry when an
+ * `Instances.transforms` array<f32> length violates the column-major mat4
+ * stride contract (`length % 16 === 0`). Locates the failure adjacent to the
+ * extract pipeline rather than at GPU upload (plan-strategy §2.4 D-P2 +
+ * §8.3 hint SSOT).
+ *
+ * `.code = 'instance-transforms-stride-mismatch'`
+ * `.detail = { actualLength, expectedStride: 16 }`
+ * `.hint` — names the stride invariant + the call sites to audit.
+ */
+export declare class InstanceTransformsStrideMismatchError extends Error {
+    readonly name = "InstanceTransformsStrideMismatchError";
+    readonly code: "instance-transforms-stride-mismatch";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly actualLength: number;
+        readonly expectedStride: 16;
+    };
+    constructor(actualLength: number);
+}
+/**
+ * Thrown by `defineComponent` when an `array<T>` / `array<T,N>` schema field
+ * carries an element type outside the legal whitelist (scalars + entity).
+ * Forms like `array<ref<X>>` / `array<handle<X>>` / `array<buffer:N>` /
+ * `array<array<...>>` are rejected (AC-03 runtime fail-safe). The TS layer
+ * blocks these forms at compile time; this error is the runtime backstop for
+ * `as unknown as SchemaFieldType` casts.
+ *
+ * `.code = 'managed-array-element-type-not-allowed'`
+ * `.detail = { fieldName, elementType, hint }`
+ * `.hint` — lists the whitelist of legal element types.
+ */
+export declare class ManagedArrayElementTypeNotAllowedError extends Error {
+    readonly name = "ManagedArrayElementTypeNotAllowedError";
+    readonly code: "managed-array-element-type-not-allowed";
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: {
+        readonly fieldName: string;
+        readonly elementType: string;
+        readonly hint: string;
+    };
+    constructor(fieldName: string, elementType: string);
+}
+/** Closed union of every `.code` literal carried by EcsError instances. */
+export type EcsErrorCode = 'stale-entity' | 'component-already-present' | 'component-not-present' | 'cyclic-dependency' | 'resource-not-found' | 'time-delta-invalid' | 'time-config-invalid' | 'schedule-scope-mismatch' | ScheduleMutationErrorCode | 'unique-ref-released' | 'unique-ref-double-release' | 'shared-ref-released' | 'shared-ref-double-release' | 'shared-ref-payload-invalid' | 'builtin-slot-not-owned' | 'shared-ref-stale' | 'unique-ref-stale' | 'managed-buffer-out-of-bounds' | 'managed-buffer-shrink-not-supported' | 'fixed-size-mismatch' | 'relationship-self-cycle' | 'relationship-detach-mismatch' | 'remove-essential-component' | 'spawn-data-unknown-field' | 'shared-field-invalid-value' | 'system-set-not-registered' | 'component-field-invalid-value' | 'component-numeric-value-invalid' | 'managed-array-invalid-value' | 'shared-kernel-ineligible' | 'shared-kernel-failed' | 'world-poisoned' | 'command-failed' | 'system-failed';
+/**
+ * Discriminated `.detail` payload per `.code`.
+ *
+ * Narrowed via `switch (err.code)` against `EcsErrorCode`. Empty-detail entries
+ * (legacy errors without `.detail`) are intentionally omitted from this map —
+ * only the w5 family + `cyclic-injection` carry structured payloads today.
+ */
+export type EcsErrorDetail = {
+    readonly code: 'shared-kernel-ineligible';
+    readonly kernelName: string;
+    readonly reason: string;
+} | {
+    readonly code: 'shared-kernel-failed';
+    readonly kernelName: string;
+    readonly worldIdentity: string;
+    readonly cause: unknown;
+    readonly partialWrite: boolean;
+    readonly retryable: false;
+} | {
+    readonly code: 'world-poisoned';
+    readonly worldIdentity: string;
+    readonly fault: unknown;
+} | {
+    readonly code: 'sparse-storage-requires-tag';
+    readonly componentName: string;
+} | {
+    readonly code: 'query-descriptor-conflict';
+    readonly componentName: string;
+    readonly roles: readonly string[];
+} | {
+    readonly code: 'query-data-requires-fields';
+    readonly componentName: string;
+} | {
+    readonly code: 'query-span-unavailable';
+    readonly reason: QuerySpanUnavailableReason;
+} | {
+    readonly code: 'query-iteration-invalidated';
+    readonly expectedStructureEpoch: number;
+    readonly actualStructureEpoch: number;
+} | {
+    readonly code: 'query-iteration-active';
+} | {
+    readonly code: 'change-epoch-exhausted';
+    readonly epoch: number;
+} | {
+    readonly code: 'unique-ref-released';
+    readonly handle: number;
+    readonly target: string;
+} | {
+    readonly code: 'unique-ref-double-release';
+    readonly handle: number;
+    readonly target: string;
+} | {
+    readonly code: 'shared-ref-released';
+    readonly handle: number;
+    readonly target: string;
+} | {
+    readonly code: 'shared-ref-double-release';
+    readonly handle: number;
+    readonly target: string;
+    readonly rc: number;
+} | {
+    readonly code: 'shared-ref-payload-invalid';
+    readonly target: string;
+    readonly actual: 'null' | 'undefined';
+} | {
+    readonly code: 'builtin-slot-not-owned';
+    readonly slot: number;
+} | {
+    readonly code: 'shared-ref-stale';
+    readonly slot: number;
+    readonly expectedGeneration: number;
+    readonly actualGeneration: number;
+} | {
+    readonly code: 'unique-ref-stale';
+    readonly slot: number;
+    readonly expectedGeneration: number;
+    readonly actualGeneration: number;
+} | {
+    readonly code: 'managed-buffer-out-of-bounds';
+    readonly index: number;
+    readonly size: number;
+} | {
+    readonly code: 'managed-buffer-shrink-not-supported';
+    readonly requested: number;
+    readonly current: number;
+} | {
+    readonly code: 'managed-array-element-type-not-allowed';
+    readonly fieldName: string;
+    readonly elementType: string;
+    readonly hint: string;
+} | {
+    readonly code: 'fixed-size-mismatch';
+    readonly expected: number;
+    readonly actual: number;
+} | {
+    readonly code: 'instance-transforms-stride-mismatch';
+    readonly actualLength: number;
+    readonly expectedStride: 16;
+} | {
+    readonly code: 'spawn-light-invalid-bounds';
+    readonly field: 'range' | 'innerOuter' | 'outerNinety';
+    readonly got: number;
+} | {
+    readonly code: 'resource-invalid-value';
+    readonly receivedMode: number;
+    readonly receivedKey?: string;
+} | {
+    readonly code: 'sprite-animation-invalid';
+    readonly field: 'regions-length';
+    readonly regionsLength: number;
+    readonly frameCount: number;
+} | {
+    readonly code: 'sprite-animation-invalid';
+    readonly field: 'frame-duration';
+    readonly frameDuration: number;
+} | {
+    readonly code: 'relationship-self-cycle';
+    readonly component: string;
+    readonly entity: number;
+    readonly ancestor: number;
+} | {
+    readonly code: 'relationship-mirror-component-not-registered';
+    readonly component: string;
+    readonly mirror: string;
+} | {
+    readonly code: 'relationship-mirror-field-type-mismatch';
+    readonly component: string;
+    readonly mirror: string;
+    readonly field: string;
+    readonly actualType: string;
+} | {
+    readonly code: 'relationship-detach-mismatch';
+    readonly component: string;
+    readonly child: number;
+    readonly expectedParent: number;
+    readonly actualParent: number;
+} | {
+    readonly code: 'component-not-defined';
+    readonly name: string;
+} | {
+    readonly code: 'remove-essential-component';
+    readonly componentName: string;
+} | {
+    readonly code: 'scene-override-type-mismatch';
+    readonly comp: string;
+    readonly field: string;
+    readonly expectedType: string;
+    readonly actualType: unknown;
+} | {
+    readonly code: 'spawn-data-unknown-field';
+    readonly component: string;
+    readonly field: string;
+    readonly knownFields: readonly string[];
+} | {
+    readonly code: 'sprite-instances-count-mismatch';
+    readonly transformsLength: number;
+    readonly regionsLength: number;
+    readonly expectedStride: {
+        readonly transforms: 16;
+        readonly regions: 4;
+    };
+} | {
+    readonly code: 'sprite-instances-requires-sprite-shader';
+    readonly entityId: number;
+    readonly observedMaterialShaderId: string;
+} | {
+    readonly code: 'sprite-instances-mutually-exclusive-with-instances';
+    readonly entityId: number;
+} | {
+    readonly code: 'shared-field-invalid-value';
+    readonly component: string;
+    readonly field: string;
+    readonly fieldType: string;
+    readonly actualValue: unknown;
+    readonly index?: number;
+} | {
+    readonly code: 'system-set-not-registered';
+    readonly name: string;
+    readonly registered: readonly string[];
+} | {
+    readonly code: 'component-field-invalid-value';
+    readonly entity: number | undefined;
+    readonly component: string;
+    readonly field: string;
+    readonly received: unknown;
+    readonly allowedValues: Readonly<Record<string, number>>;
+} | {
+    readonly code: 'component-numeric-value-invalid';
+    readonly entity: number | undefined;
+    readonly component: string;
+    readonly field: string;
+    readonly received: number;
+    readonly index?: number;
+} | {
+    readonly code: 'managed-array-invalid-value';
+    readonly component: string;
+    readonly field: string;
+    readonly fieldType: string;
+    readonly actualValue: unknown;
+} | {
+    readonly code: 'cyclic-dependency';
+    readonly cycle: readonly string[];
+} | {
+    readonly code: 'command-failed';
+    readonly systemName: string;
+    readonly schedule: string;
+    readonly commandIndex: number;
+    readonly commandKind: CommandKind;
+    readonly cause: unknown;
+} | {
+    readonly code: 'system-failed';
+    readonly systemName: string;
+    readonly schedule: string;
+    readonly cause: unknown;
+    readonly lastCommittedCommand: CommandCommitEvidence | null;
+};
+/**
+ * Layer-3 error envelope routed through managed-storage callbacks. Callers
+ * narrow `detail` through the source-owned `EcsErrorDetail` union.
+ */
+export interface ManagedArrayErrorEnvelope {
+    readonly code: EcsErrorCode;
+    readonly hint: string;
+    readonly expected: string;
+    readonly detail: unknown;
+}
+export type CommandKind = 'spawn' | 'despawn' | 'addComponent' | 'removeComponent';
+export interface CommandCommitEvidence {
+    readonly index: number;
+    readonly kind: CommandKind;
+}
+/** Expected command preflight failure, with the exact batch location. */
+export declare class CommandFailedError extends Error {
+    readonly name = "CommandFailedError";
+    readonly code: "command-failed";
+    readonly expected = "all deferred commands pass preflight before commit";
+    readonly hint = "Inspect detail.cause, repair the command at detail.commandIndex, and run the World again.";
+    readonly cause: unknown;
+    readonly detail: {
+        readonly systemName: string;
+        readonly schedule: string;
+        readonly commandIndex: number;
+        readonly commandKind: CommandKind;
+        readonly cause: unknown;
+    };
+    constructor(systemName: string, schedule: string, commandIndex: number, commandKind: CommandKind, cause: unknown);
+}
+/** Unknown system failure. The World is poisoned because row writes may exist. */
+export declare class SystemFailedError extends Error {
+    readonly name = "SystemFailedError";
+    readonly code: "system-failed";
+    readonly expected = "a system completes without throwing or returning a failed Result";
+    readonly hint = "Inspect detail.cause, stop using this poisoned World, and rebuild it from the owning App.";
+    readonly cause: unknown;
+    readonly detail: {
+        readonly systemName: string;
+        readonly schedule: string;
+        readonly cause: unknown;
+        readonly lastCommittedCommand: CommandCommitEvidence | null;
+    };
+    constructor(systemName: string, schedule: string, cause: unknown, lastCommittedCommand?: CommandCommitEvidence | null);
+}
+//# sourceMappingURL=errors.d.ts.map