@oasys/oecs 0.5.3 → 0.6.0

package/dist/core/ecs/system_set.d.cts

@@ -0,0 +1,48 @@
+import { RunCondition } from './run_condition.cjs';
+import { SystemDescriptor } from './system.cjs';
+/**
+ * An opaque handle for a named group of systems. A set carries a shared
+ * run condition and shared ordering that every member inherits. Sets are
+ * identified by **object identity**, not by name, create one with
+ * `systemSet(name)`, hold the handle, and reuse it across `addSystems`
+ * (`SystemEntry.set`) and `Schedule.configureSet`. The `name` is for
+ * diagnostics only.
+ */
+export interface SystemSet {
+    readonly name: string;
+}
+/** Create a `SystemSet` handle. Two calls with the same name are two
+ * distinct sets, keep the returned handle and pass it around. */
+export declare function systemSet(name: string): SystemSet;
+/** A `before` and `after` ordering target: either a concrete system or a whole set
+ * (expanded to its members within the same phase at sort time). */
+export type SystemOrderingTarget = SystemDescriptor | SystemSet;
+/** Shared configuration applied to a `SystemSet` via `configureSet`.
+ * It accumulates across calls. Conditions combine with and, and ordering
+ * targets union. */
+export interface SystemSetConfig {
+    /** Condition(s) every member is gated by (ANDed with each member's own). */
+    runIf?: RunCondition | readonly RunCondition[];
+    /** Every member runs before each of these targets. */
+    before?: readonly SystemOrderingTarget[];
+    /** Every member runs after each of these targets. */
+    after?: readonly SystemOrderingTarget[];
+}
+export interface SystemOrdering {
+    before?: readonly SystemOrderingTarget[];
+    after?: readonly SystemOrderingTarget[];
+}
+export interface SystemEntry {
+    system: SystemDescriptor;
+    ordering?: SystemOrdering;
+    /** Run condition(s) gating only this system. ANDed with any set conditions
+     * it inherits. A `false` verdict skips the body that tick. */
+    runIf?: RunCondition | readonly RunCondition[];
+    /** Set membership, the system inherits each set's shared condition and
+     * ordering. */
+    set?: SystemSet | readonly SystemSet[];
+}
+/** A `SystemOrderingTarget` is a set iff it is not a system descriptor. A
+ * descriptor always carries `fn` (its update function), a set never does. */
+export declare function isSystemSet(target: SystemOrderingTarget): target is SystemSet;
+//# sourceMappingURL=system_set.d.ts.map

package/dist/core/ecs/system_set.d.ts

@@ -0,0 +1,48 @@
+import { RunCondition } from './run_condition.js';
+import { SystemDescriptor } from './system.js';
+/**
+ * An opaque handle for a named group of systems. A set carries a shared
+ * run condition and shared ordering that every member inherits. Sets are
+ * identified by **object identity**, not by name, create one with
+ * `systemSet(name)`, hold the handle, and reuse it across `addSystems`
+ * (`SystemEntry.set`) and `Schedule.configureSet`. The `name` is for
+ * diagnostics only.
+ */
+export interface SystemSet {
+    readonly name: string;
+}
+/** Create a `SystemSet` handle. Two calls with the same name are two
+ * distinct sets, keep the returned handle and pass it around. */
+export declare function systemSet(name: string): SystemSet;
+/** A `before` and `after` ordering target: either a concrete system or a whole set
+ * (expanded to its members within the same phase at sort time). */
+export type SystemOrderingTarget = SystemDescriptor | SystemSet;
+/** Shared configuration applied to a `SystemSet` via `configureSet`.
+ * It accumulates across calls. Conditions combine with and, and ordering
+ * targets union. */
+export interface SystemSetConfig {
+    /** Condition(s) every member is gated by (ANDed with each member's own). */
+    runIf?: RunCondition | readonly RunCondition[];
+    /** Every member runs before each of these targets. */
+    before?: readonly SystemOrderingTarget[];
+    /** Every member runs after each of these targets. */
+    after?: readonly SystemOrderingTarget[];
+}
+export interface SystemOrdering {
+    before?: readonly SystemOrderingTarget[];
+    after?: readonly SystemOrderingTarget[];
+}
+export interface SystemEntry {
+    system: SystemDescriptor;
+    ordering?: SystemOrdering;
+    /** Run condition(s) gating only this system. ANDed with any set conditions
+     * it inherits. A `false` verdict skips the body that tick. */
+    runIf?: RunCondition | readonly RunCondition[];
+    /** Set membership, the system inherits each set's shared condition and
+     * ordering. */
+    set?: SystemSet | readonly SystemSet[];
+}
+/** A `SystemOrderingTarget` is a set iff it is not a system descriptor. A
+ * descriptor always carries `fn` (its update function), a set never does. */
+export declare function isSystemSet(target: SystemOrderingTarget): target is SystemSet;
+//# sourceMappingURL=system_set.d.ts.map

package/dist/core/ecs/system_set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system_set.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/system_set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;KAcK;AAEL,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;iEACiE;AACjE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAEjD;AAED;mEACmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAEhE;;oBAEoB;AACpB,MAAM,WAAW,eAAe;IAC/B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,YAAY,EAAE,CAAC;IAC/C,sDAAsD;IACtD,MAAM,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACzC,qDAAqD;IACrD,KAAK,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC9B,MAAM,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACzC,KAAK,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;kEAC8D;IAC9D,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,YAAY,EAAE,CAAC;IAC/C;mBACe;IACf,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,SAAS,EAAE,CAAC;CACvC;AAED;6EAC6E;AAC7E,wBAAgB,WAAW,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,IAAI,SAAS,CAE7E"}

package/dist/core/ecs/utils/arrays.d.cts

@@ -1,7 +1,21 @@
 /***
- * Array utilities — helpers for hash-bucketed maps.
+ * Array utilities. Hash-bucket push, and the canonical entity-id order.
  *
+ * `radixSortByIndex` lives here and not beside one caller, because two plugins
+ * want it and neither may import the other. The observers plugin sorts an
+ * entity-grain drain with it. The relations plugin sorts a hierarchy pass with
+ * it. A core home is what keeps the relation code free of the observer code.
  ***/
 /** Push a value into a hash-bucket map, creating the bucket array if absent. */
 export declare function bucketPush<T>(map: Map<number, T[]>, key: number, value: T): void;
+/**
+ * O(K) LSD radix sort of entity ids by their 20-bit dense index (two 10-bit
+ * passes), in place. This is the canonical within-observer order, *never* a
+ * comparator `Array.sort`, which is far slower than the entire flush.
+ * Distinct live entities have distinct indices,
+ * so index order is a total canonical order. `out` is typed scratch, and the
+ * return value is the scratch to keep: the same buffer, or a larger one when
+ * `K` outgrew it. `c0` and `c1` are 1024-entry histograms, and both are reused.
+ */
+export declare function radixSortByIndex(eids: number[], out: Uint32Array, c0: Int32Array, c1: Int32Array): Uint32Array;
 //# sourceMappingURL=arrays.d.ts.map

package/dist/core/ecs/utils/arrays.d.ts

@@ -1,7 +1,21 @@
 /***
- * Array utilities — helpers for hash-bucketed maps.
+ * Array utilities. Hash-bucket push, and the canonical entity-id order.
  *
+ * `radixSortByIndex` lives here and not beside one caller, because two plugins
+ * want it and neither may import the other. The observers plugin sorts an
+ * entity-grain drain with it. The relations plugin sorts a hierarchy pass with
+ * it. A core home is what keeps the relation code free of the observer code.
  ***/
 /** Push a value into a hash-bucket map, creating the bucket array if absent. */
 export declare function bucketPush<T>(map: Map<number, T[]>, key: number, value: T): void;
+/**
+ * O(K) LSD radix sort of entity ids by their 20-bit dense index (two 10-bit
+ * passes), in place. This is the canonical within-observer order, *never* a
+ * comparator `Array.sort`, which is far slower than the entire flush.
+ * Distinct live entities have distinct indices,
+ * so index order is a total canonical order. `out` is typed scratch, and the
+ * return value is the scratch to keep: the same buffer, or a larger one when
+ * `K` outgrew it. `c0` and `c1` are 1024-entry histograms, and both are reused.
+ */
+export declare function radixSortByIndex(eids: number[], out: Uint32Array, c0: Int32Array, c1: Int32Array): Uint32Array;
 //# sourceMappingURL=arrays.d.ts.map

package/dist/core/ecs/utils/arrays.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arrays.d.ts","sourceRoot":"","sources":["../../../../src/core/ecs/utils/arrays.ts"],"names":[],"mappings":"AAAA;;;KAGK;AAEL,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAOhF"}
+{"version":3,"file":"arrays.d.ts","sourceRoot":"","sources":["../../../../src/core/ecs/utils/arrays.ts"],"names":[],"mappings":"AAAA;;;;;;;KAOK;AAOL,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAOhF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,WAAW,EAChB,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,UAAU,GACZ,WAAW,CA4Bb"}

package/dist/core/ecs/utils/error.d.cts

@@ -7,11 +7,19 @@ export declare enum ECS_ERROR {
     ENTITY_NOT_ALIVE = "ENTITY_NOT_ALIVE",
     CIRCULAR_SYSTEM_DEPENDENCY = "CIRCULAR_SYSTEM_DEPENDENCY",
     DUPLICATE_SYSTEM = "DUPLICATE_SYSTEM",
+    /** A phase handed to `addSystems` or to `addPhase` is not a phase of this
+     * schedule: a name no built-in spells, or a handle another world made. */
+    UNKNOWN_PHASE = "UNKNOWN_PHASE",
+    /** The phase ordering of one loop has a cycle, so no run order exists. */
+    CIRCULAR_PHASE_DEPENDENCY = "CIRCULAR_PHASE_DEPENDENCY",
     ARCHETYPE_NOT_FOUND = "ARCHETYPE_NOT_FOUND",
     RESOURCE_NOT_REGISTERED = "RESOURCE_NOT_REGISTERED",
     RESOURCE_ALREADY_REGISTERED = "RESOURCE_ALREADY_REGISTERED",
     EVENT_ALREADY_REGISTERED = "EVENT_ALREADY_REGISTERED",
     EVENT_NOT_REGISTERED = "EVENT_NOT_REGISTERED",
+    /** An event id is not an integer >= 0. The events plugin mints ids from a
+     * counter, so only a forged id reaches this. Dev-only. */
+    INVALID_EVENT_ID = "INVALID_EVENT_ID",
     FIELD_NOT_REGISTERED = "FIELD_NOT_REGISTERED",
     RELATION_NOT_REGISTERED = "RELATION_NOT_REGISTERED",
     RELATION_MODE_INVALID = "RELATION_MODE_INVALID",
@@ -19,20 +27,32 @@ export declare enum ECS_ERROR {
     RELATION_CYCLE = "RELATION_CYCLE",
     SPARSE_CACHE_KEY_OVERFLOW = "SPARSE_CACHE_KEY_OVERFLOW",
     SPARSE_QUERY_DENSE_PATH = "SPARSE_QUERY_DENSE_PATH",
+    /** A reader that answers from the unfiltered dense archetype list ran on a
+     * query that carries an archetype term. The term narrows the list, so the
+     * reader would answer wider than the query matches. */
+    QUERY_TERM_DENSE_PATH = "QUERY_TERM_DENSE_PATH",
     HIERARCHY_ALREADY_SET = "HIERARCHY_ALREADY_SET",
     HIERARCHY_INVALID_MAX_DEPTH = "HIERARCHY_INVALID_MAX_DEPTH",
     OBSERVER_NON_CONVERGENT = "OBSERVER_NON_CONVERGENT",
     OBSERVER_INVALID_CONFIG = "OBSERVER_INVALID_CONFIG",
     OBSERVER_ONSET_EMIT = "OBSERVER_ONSET_EMIT",
+    ROW_TICKS_NOT_TRACKED = "ROW_TICKS_NOT_TRACKED",
     INVALID_FIXED_TIMESTEP = "INVALID_FIXED_TIMESTEP",
     INVALID_MAX_FIXED_STEPS = "INVALID_MAX_FIXED_STEPS",
     INVALID_RECORDER_SCHEDULE = "INVALID_RECORDER_SCHEDULE",
     EMPTY_ARCHETYPE_MATERIALIZE = "EMPTY_ARCHETYPE_MATERIALIZE",
     COMPONENT_INDEX_INVARIANT = "COMPONENT_INDEX_INVARIANT",
+    /** An Archetype's row bookkeeping is inconsistent with its backing columns:
+     * a reserve that did not deliver the capacity it was asked for, a restore
+     * handed an out-of-range partition boundary, or a cached row plane
+     * (`_bufs` and `_eids`) left pointing at a stale buffer. Dev-only, and an
+     * internal-invariant failure rather than a caller error, distinct from
+     * `STORE_CAP_EXCEEDED`, which is the allocator refusing a legitimate grow. */
+    ARCHETYPE_ROW_INVARIANT = "ARCHETYPE_ROW_INVARIANT",
     OPTIONAL_TERM_NOT_DECLARED = "OPTIONAL_TERM_NOT_DECLARED",
     QUERY_ACCESS_UNDECLARED = "QUERY_ACCESS_UNDECLARED",
-    /** A system touched a component/sparse/relation/resource it didn't declare
-     * in its access surface — distinct from *_NOT_REGISTERED (which means the
+    /** A system touched a component, sparse, relation or resource it did not declare
+     * in its access surface, distinct from *_NOT_REGISTERED (which means the
      * thing was never registered with the world at all). */
     ACCESS_UNDECLARED = "ACCESS_UNDECLARED",
     /** `Query.singleEntity` found 0 or >1 matches (dev-only assertion). */
@@ -40,22 +60,85 @@ export declare enum ECS_ERROR {
     /** A run-condition factory was given invalid arguments (dev-only). */
     INVALID_RUN_CONDITION = "INVALID_RUN_CONDITION",
     SYSTEM_FN_ARITY = "SYSTEM_FN_ARITY",
+    /** A system id is not an integer >= 0. The schedule and the observers plugin
+     * mint ids from a counter, so this catches a forged id. Dev-only. */
+    INVALID_SYSTEM_ID = "INVALID_SYSTEM_ID",
     PARTITION_APPEND_NEEDS_ENTITY_ROW = "PARTITION_APPEND_NEEDS_ENTITY_ROW",
     PARTITION_BULK_INTO_DISABLED = "PARTITION_BULK_INTO_DISABLED",
-    ENTITY_NOT_DISABLED = "ENTITY_NOT_DISABLED",
     STRUCTURAL_DURING_ITERATION = "STRUCTURAL_DURING_ITERATION",
     BACKEND_ALREADY_ATTACHED = "BACKEND_ALREADY_ATTACHED",
     DETERMINISM_DISABLED = "DETERMINISM_DISABLED",
+    /** `ecs.snapshots.restore` refused a frame: too short, the wrong magic or
+     * version, a section that runs past the buffer, or a world whose archetype
+     * and component registration differs from the capture. The live world is
+     * unchanged. In each build. */
+    SNAPSHOT_RESTORE_FAILED = "SNAPSHOT_RESTORE_FAILED",
     NON_DETERMINISTIC_COLUMN_TYPE = "NON_DETERMINISTIC_COLUMN_TYPE",
     INVALID_MEMORY_OPTIONS = "INVALID_MEMORY_OPTIONS",
     STORE_CAP_EXCEEDED = "STORE_CAP_EXCEEDED",
     REGION_NOT_DECLARED = "REGION_NOT_DECLARED",
     COMMAND_LOG_TAG_COLLISION = "COMMAND_LOG_TAG_COLLISION",
-    INVALID_FRAME_STEP = "INVALID_FRAME_STEP"
+    INVALID_FRAME_STEP = "INVALID_FRAME_STEP",
+    /** `spawn` or `spawnMany` got a value that is not a template. A component
+     * definition and a bundle are the two usual mistakes. Dev-only. Without this
+     * check, the value goes to the store. Then the store fails with a `TypeError`
+     * about an internal field. That error names the wrong place. */
+    INVALID_TEMPLATE = "INVALID_TEMPLATE",
+    /** An optional subsystem was used on a world that never installed it.
+     * Distinct from `*_NOT_REGISTERED`, which means the world has the
+     * subsystem but not that particular component, event or relation. */
+    PLUGIN_NOT_INSTALLED = "PLUGIN_NOT_INSTALLED",
+    /** One plugin reached an install seam twice. The second service would
+     * replace the first, and every handle the caller took from the first would
+     * then address state the world no longer reads. */
+    PLUGIN_ALREADY_INSTALLED = "PLUGIN_ALREADY_INSTALLED",
+    /** A plugin's facade names a member the world already carries.
+     * `Object.assign` would overwrite it without a word, and the world would
+     * lose a method it needs. Dev-only. */
+    PLUGIN_SURFACE_COLLISION = "PLUGIN_SURFACE_COLLISION",
+    /** `workers.attach` ran on a world that already holds a pool. One pool per
+     * world, because one control buffer carries one barrier. */
+    WORKERS_ATTACHED = "WORKERS_ATTACHED",
+    /** `workers.attach` ran on a world whose bytes a worker cannot reach. A
+     * worker needs a `SharedArrayBuffer` or a shared `WebAssembly.Memory`. */
+    WORKERS_NEED_SHARED_BACKING = "WORKERS_NEED_SHARED_BACKING",
+    /** The host cannot block on `Atomics.wait`, so it cannot park while the
+     * workers run. A browser main thread is the case. */
+    WORKERS_HOST_CANNOT_PARK = "WORKERS_HOST_CANNOT_PARK",
+    /** `workers.attach` was given a number outside its range. The worker count,
+     * the join timeout and the kernel stack size are the three, and the message
+     * names which. */
+    WORKERS_COUNT_INVALID = "WORKERS_COUNT_INVALID",
+    /** A worker's script did not load, so the worker answered nothing. A
+     * `workerUrl` that points at no file is the case, and a bundled app that
+     * kept the default is where that happens. */
+    WORKERS_ENTRY_UNREACHABLE = "WORKERS_ENTRY_UNREACHABLE",
+    /** A parallel system declares access a worker cannot serve, or a query a
+     * worker cannot resolve from the archetype masks. Dev-only, at
+     * registration. */
+    PARALLEL_ACCESS = "PARALLEL_ACCESS",
+    /** A parallel system names a `wasm` kernel whose module the pool cannot
+     * serve: an import the workers do not supply, a missing memory import, or an
+     * export that is missing or is not a function. Dev-only, at registration. */
+    PARALLEL_KERNEL_MODULE = "PARALLEL_KERNEL_MODULE",
+    /** A kernel would not load, it threw inside a pass, or a worker missed the
+     * join inside `joinTimeoutMs`. The message names the kernel export, and the
+     * worker index when a worker reported the fault itself. A module that cannot
+     * be given one stack region for each worker fails to load here. */
+    PARALLEL_KERNEL_FAILED = "PARALLEL_KERNEL_FAILED"
 }
 export declare class ECSError extends AppError {
     readonly category: ECS_ERROR;
     constructor(category: ECS_ERROR, message?: string, context?: Record<string, unknown>);
 }
 export declare function isEcsError(error: unknown): error is ECSError;
+/** Thrown by `ecs.snapshots.restore` and its helpers when a combined snapshot
+ * is malformed, carries the wrong magic or version, or targets a world whose
+ * archetype and component registration does not match the capture. An
+ * `ECSError` with category `SNAPSHOT_RESTORE_FAILED`, so `isEcsError` answers
+ * true, and its own class beside `StoreRestoreError` and `SparseRestoreError`
+ * so a caller catches one class per restore layer. */
+export declare class ECSRestoreError extends ECSError {
+    constructor(message: string);
+}
 //# sourceMappingURL=error.d.ts.map

package/dist/core/ecs/utils/error.d.ts

@@ -7,11 +7,19 @@ export declare enum ECS_ERROR {
     ENTITY_NOT_ALIVE = "ENTITY_NOT_ALIVE",
     CIRCULAR_SYSTEM_DEPENDENCY = "CIRCULAR_SYSTEM_DEPENDENCY",
     DUPLICATE_SYSTEM = "DUPLICATE_SYSTEM",
+    /** A phase handed to `addSystems` or to `addPhase` is not a phase of this
+     * schedule: a name no built-in spells, or a handle another world made. */
+    UNKNOWN_PHASE = "UNKNOWN_PHASE",
+    /** The phase ordering of one loop has a cycle, so no run order exists. */
+    CIRCULAR_PHASE_DEPENDENCY = "CIRCULAR_PHASE_DEPENDENCY",
     ARCHETYPE_NOT_FOUND = "ARCHETYPE_NOT_FOUND",
     RESOURCE_NOT_REGISTERED = "RESOURCE_NOT_REGISTERED",
     RESOURCE_ALREADY_REGISTERED = "RESOURCE_ALREADY_REGISTERED",
     EVENT_ALREADY_REGISTERED = "EVENT_ALREADY_REGISTERED",
     EVENT_NOT_REGISTERED = "EVENT_NOT_REGISTERED",
+    /** An event id is not an integer >= 0. The events plugin mints ids from a
+     * counter, so only a forged id reaches this. Dev-only. */
+    INVALID_EVENT_ID = "INVALID_EVENT_ID",
     FIELD_NOT_REGISTERED = "FIELD_NOT_REGISTERED",
     RELATION_NOT_REGISTERED = "RELATION_NOT_REGISTERED",
     RELATION_MODE_INVALID = "RELATION_MODE_INVALID",
@@ -19,20 +27,32 @@ export declare enum ECS_ERROR {
     RELATION_CYCLE = "RELATION_CYCLE",
     SPARSE_CACHE_KEY_OVERFLOW = "SPARSE_CACHE_KEY_OVERFLOW",
     SPARSE_QUERY_DENSE_PATH = "SPARSE_QUERY_DENSE_PATH",
+    /** A reader that answers from the unfiltered dense archetype list ran on a
+     * query that carries an archetype term. The term narrows the list, so the
+     * reader would answer wider than the query matches. */
+    QUERY_TERM_DENSE_PATH = "QUERY_TERM_DENSE_PATH",
     HIERARCHY_ALREADY_SET = "HIERARCHY_ALREADY_SET",
     HIERARCHY_INVALID_MAX_DEPTH = "HIERARCHY_INVALID_MAX_DEPTH",
     OBSERVER_NON_CONVERGENT = "OBSERVER_NON_CONVERGENT",
     OBSERVER_INVALID_CONFIG = "OBSERVER_INVALID_CONFIG",
     OBSERVER_ONSET_EMIT = "OBSERVER_ONSET_EMIT",
+    ROW_TICKS_NOT_TRACKED = "ROW_TICKS_NOT_TRACKED",
     INVALID_FIXED_TIMESTEP = "INVALID_FIXED_TIMESTEP",
     INVALID_MAX_FIXED_STEPS = "INVALID_MAX_FIXED_STEPS",
     INVALID_RECORDER_SCHEDULE = "INVALID_RECORDER_SCHEDULE",
     EMPTY_ARCHETYPE_MATERIALIZE = "EMPTY_ARCHETYPE_MATERIALIZE",
     COMPONENT_INDEX_INVARIANT = "COMPONENT_INDEX_INVARIANT",
+    /** An Archetype's row bookkeeping is inconsistent with its backing columns:
+     * a reserve that did not deliver the capacity it was asked for, a restore
+     * handed an out-of-range partition boundary, or a cached row plane
+     * (`_bufs` and `_eids`) left pointing at a stale buffer. Dev-only, and an
+     * internal-invariant failure rather than a caller error, distinct from
+     * `STORE_CAP_EXCEEDED`, which is the allocator refusing a legitimate grow. */
+    ARCHETYPE_ROW_INVARIANT = "ARCHETYPE_ROW_INVARIANT",
     OPTIONAL_TERM_NOT_DECLARED = "OPTIONAL_TERM_NOT_DECLARED",
     QUERY_ACCESS_UNDECLARED = "QUERY_ACCESS_UNDECLARED",
-    /** A system touched a component/sparse/relation/resource it didn't declare
-     * in its access surface — distinct from *_NOT_REGISTERED (which means the
+    /** A system touched a component, sparse, relation or resource it did not declare
+     * in its access surface, distinct from *_NOT_REGISTERED (which means the
      * thing was never registered with the world at all). */
     ACCESS_UNDECLARED = "ACCESS_UNDECLARED",
     /** `Query.singleEntity` found 0 or >1 matches (dev-only assertion). */
@@ -40,22 +60,85 @@ export declare enum ECS_ERROR {
     /** A run-condition factory was given invalid arguments (dev-only). */
     INVALID_RUN_CONDITION = "INVALID_RUN_CONDITION",
     SYSTEM_FN_ARITY = "SYSTEM_FN_ARITY",
+    /** A system id is not an integer >= 0. The schedule and the observers plugin
+     * mint ids from a counter, so this catches a forged id. Dev-only. */
+    INVALID_SYSTEM_ID = "INVALID_SYSTEM_ID",
     PARTITION_APPEND_NEEDS_ENTITY_ROW = "PARTITION_APPEND_NEEDS_ENTITY_ROW",
     PARTITION_BULK_INTO_DISABLED = "PARTITION_BULK_INTO_DISABLED",
-    ENTITY_NOT_DISABLED = "ENTITY_NOT_DISABLED",
     STRUCTURAL_DURING_ITERATION = "STRUCTURAL_DURING_ITERATION",
     BACKEND_ALREADY_ATTACHED = "BACKEND_ALREADY_ATTACHED",
     DETERMINISM_DISABLED = "DETERMINISM_DISABLED",
+    /** `ecs.snapshots.restore` refused a frame: too short, the wrong magic or
+     * version, a section that runs past the buffer, or a world whose archetype
+     * and component registration differs from the capture. The live world is
+     * unchanged. In each build. */
+    SNAPSHOT_RESTORE_FAILED = "SNAPSHOT_RESTORE_FAILED",
     NON_DETERMINISTIC_COLUMN_TYPE = "NON_DETERMINISTIC_COLUMN_TYPE",
     INVALID_MEMORY_OPTIONS = "INVALID_MEMORY_OPTIONS",
     STORE_CAP_EXCEEDED = "STORE_CAP_EXCEEDED",
     REGION_NOT_DECLARED = "REGION_NOT_DECLARED",
     COMMAND_LOG_TAG_COLLISION = "COMMAND_LOG_TAG_COLLISION",
-    INVALID_FRAME_STEP = "INVALID_FRAME_STEP"
+    INVALID_FRAME_STEP = "INVALID_FRAME_STEP",
+    /** `spawn` or `spawnMany` got a value that is not a template. A component
+     * definition and a bundle are the two usual mistakes. Dev-only. Without this
+     * check, the value goes to the store. Then the store fails with a `TypeError`
+     * about an internal field. That error names the wrong place. */
+    INVALID_TEMPLATE = "INVALID_TEMPLATE",
+    /** An optional subsystem was used on a world that never installed it.
+     * Distinct from `*_NOT_REGISTERED`, which means the world has the
+     * subsystem but not that particular component, event or relation. */
+    PLUGIN_NOT_INSTALLED = "PLUGIN_NOT_INSTALLED",
+    /** One plugin reached an install seam twice. The second service would
+     * replace the first, and every handle the caller took from the first would
+     * then address state the world no longer reads. */
+    PLUGIN_ALREADY_INSTALLED = "PLUGIN_ALREADY_INSTALLED",
+    /** A plugin's facade names a member the world already carries.
+     * `Object.assign` would overwrite it without a word, and the world would
+     * lose a method it needs. Dev-only. */
+    PLUGIN_SURFACE_COLLISION = "PLUGIN_SURFACE_COLLISION",
+    /** `workers.attach` ran on a world that already holds a pool. One pool per
+     * world, because one control buffer carries one barrier. */
+    WORKERS_ATTACHED = "WORKERS_ATTACHED",
+    /** `workers.attach` ran on a world whose bytes a worker cannot reach. A
+     * worker needs a `SharedArrayBuffer` or a shared `WebAssembly.Memory`. */
+    WORKERS_NEED_SHARED_BACKING = "WORKERS_NEED_SHARED_BACKING",
+    /** The host cannot block on `Atomics.wait`, so it cannot park while the
+     * workers run. A browser main thread is the case. */
+    WORKERS_HOST_CANNOT_PARK = "WORKERS_HOST_CANNOT_PARK",
+    /** `workers.attach` was given a number outside its range. The worker count,
+     * the join timeout and the kernel stack size are the three, and the message
+     * names which. */
+    WORKERS_COUNT_INVALID = "WORKERS_COUNT_INVALID",
+    /** A worker's script did not load, so the worker answered nothing. A
+     * `workerUrl` that points at no file is the case, and a bundled app that
+     * kept the default is where that happens. */
+    WORKERS_ENTRY_UNREACHABLE = "WORKERS_ENTRY_UNREACHABLE",
+    /** A parallel system declares access a worker cannot serve, or a query a
+     * worker cannot resolve from the archetype masks. Dev-only, at
+     * registration. */
+    PARALLEL_ACCESS = "PARALLEL_ACCESS",
+    /** A parallel system names a `wasm` kernel whose module the pool cannot
+     * serve: an import the workers do not supply, a missing memory import, or an
+     * export that is missing or is not a function. Dev-only, at registration. */
+    PARALLEL_KERNEL_MODULE = "PARALLEL_KERNEL_MODULE",
+    /** A kernel would not load, it threw inside a pass, or a worker missed the
+     * join inside `joinTimeoutMs`. The message names the kernel export, and the
+     * worker index when a worker reported the fault itself. A module that cannot
+     * be given one stack region for each worker fails to load here. */
+    PARALLEL_KERNEL_FAILED = "PARALLEL_KERNEL_FAILED"
 }
 export declare class ECSError extends AppError {
     readonly category: ECS_ERROR;
     constructor(category: ECS_ERROR, message?: string, context?: Record<string, unknown>);
 }
 export declare function isEcsError(error: unknown): error is ECSError;
+/** Thrown by `ecs.snapshots.restore` and its helpers when a combined snapshot
+ * is malformed, carries the wrong magic or version, or targets a world whose
+ * archetype and component registration does not match the capture. An
+ * `ECSError` with category `SNAPSHOT_RESTORE_FAILED`, so `isEcsError` answers
+ * true, and its own class beside `StoreRestoreError` and `SparseRestoreError`
+ * so a caller catches one class per restore layer. */
+export declare class ECSRestoreError extends ECSError {
+    constructor(message: string);
+}
 //# sourceMappingURL=error.d.ts.map

package/dist/core/ecs/utils/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../../src/core/ecs/utils/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,oBAAY,SAAS;IACpB,sBAAsB,2BAA2B;IACjD,oBAAoB,yBAAyB;IAC7C,wBAAwB,6BAA6B;IACrD,wBAAwB,6BAA6B;IACrD,gBAAgB,qBAAqB;IACrC,0BAA0B,+BAA+B;IACzD,gBAAgB,qBAAqB;IACrC,mBAAmB,wBAAwB;IAC3C,uBAAuB,4BAA4B;IACnD,2BAA2B,gCAAgC;IAC3D,wBAAwB,6BAA6B;IACrD,oBAAoB,yBAAyB;IAC7C,oBAAoB,yBAAyB;IAC7C,uBAAuB,4BAA4B;IACnD,qBAAqB,0BAA0B;IAC/C,sBAAsB,2BAA2B;IACjD,cAAc,mBAAmB;IACjC,yBAAyB,8BAA8B;IACvD,uBAAuB,4BAA4B;IACnD,qBAAqB,0BAA0B;IAC/C,2BAA2B,gCAAgC;IAC3D,uBAAuB,4BAA4B;IACnD,uBAAuB,4BAA4B;IACnD,mBAAmB,wBAAwB;IAC3C,sBAAsB,2BAA2B;IACjD,uBAAuB,4BAA4B;IACnD,yBAAyB,8BAA8B;IACvD,2BAA2B,gCAAgC;IAC3D,yBAAyB,8BAA8B;IACvD,0BAA0B,+BAA+B;IACzD,uBAAuB,4BAA4B;IACnD;;4DAEwD;IACxD,iBAAiB,sBAAsB;IACvC,uEAAuE;IACvE,mBAAmB,wBAAwB;IAC3C,sEAAsE;IACtE,qBAAqB,0BAA0B;IAC/C,eAAe,oBAAoB;IACnC,iCAAiC,sCAAsC;IACvE,4BAA4B,iCAAiC;IAC7D,mBAAmB,wBAAwB;IAC3C,2BAA2B,gCAAgC;IAC3D,wBAAwB,6BAA6B;IACrD,oBAAoB,yBAAyB;IAC7C,6BAA6B,kCAAkC;IAC/D,sBAAsB,2BAA2B;IACjD,kBAAkB,uBAAuB;IACzC,mBAAmB,wBAAwB;IAC3C,yBAAyB,8BAA8B;IACvD,kBAAkB,uBAAuB;CACzC;AAED,qBAAa,QAAS,SAAQ,QAAQ;aAEpB,QAAQ,EAAE,SAAS;gBAAnB,QAAQ,EAAE,SAAS,EACnC,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAIlC;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../../src/core/ecs/utils/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,oBAAY,SAAS;IACpB,sBAAsB,2BAA2B;IACjD,oBAAoB,yBAAyB;IAC7C,wBAAwB,6BAA6B;IACrD,wBAAwB,6BAA6B;IACrD,gBAAgB,qBAAqB;IACrC,0BAA0B,+BAA+B;IACzD,gBAAgB,qBAAqB;IACrC;8EAC0E;IAC1E,aAAa,kBAAkB;IAC/B,0EAA0E;IAC1E,yBAAyB,8BAA8B;IACvD,mBAAmB,wBAAwB;IAC3C,uBAAuB,4BAA4B;IACnD,2BAA2B,gCAAgC;IAC3D,wBAAwB,6BAA6B;IACrD,oBAAoB,yBAAyB;IAC7C;8DAC0D;IAC1D,gBAAgB,qBAAqB;IACrC,oBAAoB,yBAAyB;IAC7C,uBAAuB,4BAA4B;IACnD,qBAAqB,0BAA0B;IAC/C,sBAAsB,2BAA2B;IACjD,cAAc,mBAAmB;IACjC,yBAAyB,8BAA8B;IACvD,uBAAuB,4BAA4B;IACnD;;2DAEuD;IACvD,qBAAqB,0BAA0B;IAC/C,qBAAqB,0BAA0B;IAC/C,2BAA2B,gCAAgC;IAC3D,uBAAuB,4BAA4B;IACnD,uBAAuB,4BAA4B;IACnD,mBAAmB,wBAAwB;IAC3C,qBAAqB,0BAA0B;IAC/C,sBAAsB,2BAA2B;IACjD,uBAAuB,4BAA4B;IACnD,yBAAyB,8BAA8B;IACvD,2BAA2B,gCAAgC;IAC3D,yBAAyB,8BAA8B;IACvD;;;;;kFAK8E;IAC9E,uBAAuB,4BAA4B;IACnD,0BAA0B,+BAA+B;IACzD,uBAAuB,4BAA4B;IACnD;;4DAEwD;IACxD,iBAAiB,sBAAsB;IACvC,uEAAuE;IACvE,mBAAmB,wBAAwB;IAC3C,sEAAsE;IACtE,qBAAqB,0BAA0B;IAC/C,eAAe,oBAAoB;IACnC;yEACqE;IACrE,iBAAiB,sBAAsB;IACvC,iCAAiC,sCAAsC;IACvE,4BAA4B,iCAAiC;IAC7D,2BAA2B,gCAAgC;IAC3D,wBAAwB,6BAA6B;IACrD,oBAAoB,yBAAyB;IAC7C;;;mCAG+B;IAC/B,uBAAuB,4BAA4B;IACnD,6BAA6B,kCAAkC;IAC/D,sBAAsB,2BAA2B;IACjD,kBAAkB,uBAAuB;IACzC,mBAAmB,wBAAwB;IAC3C,yBAAyB,8BAA8B;IACvD,kBAAkB,uBAAuB;IACzC;;;oEAGgE;IAChE,gBAAgB,qBAAqB;IACrC;;yEAEqE;IACrE,oBAAoB,yBAAyB;IAC7C;;uDAEmD;IACnD,wBAAwB,6BAA6B;IACrD;;2CAEuC;IACvC,wBAAwB,6BAA6B;IACrD;gEAC4D;IAC5D,gBAAgB,qBAAqB;IACrC;8EAC0E;IAC1E,2BAA2B,gCAAgC;IAC3D;yDACqD;IACrD,wBAAwB,6BAA6B;IACrD;;sBAEkB;IAClB,qBAAqB,0BAA0B;IAC/C;;iDAE6C;IAC7C,yBAAyB,8BAA8B;IACvD;;uBAEmB;IACnB,eAAe,oBAAoB;IACnC;;iFAE6E;IAC7E,sBAAsB,2BAA2B;IACjD;;;uEAGmE;IACnE,sBAAsB,2BAA2B;CACjD;AAED,qBAAa,QAAS,SAAQ,QAAQ;aAEpB,QAAQ,EAAE,SAAS;gBAAnB,QAAQ,EAAE,SAAS,EACnC,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAKlC;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED;;;;;sDAKsD;AACtD,qBAAa,eAAgB,SAAQ,QAAQ;gBAChC,OAAO,EAAE,MAAM;CAI3B"}

package/dist/core/ecs/utils/plugin_error.d.cts

@@ -0,0 +1,10 @@
+import { ECSError } from './error.cjs';
+/** The fault a world raises when a caller uses a subsystem it never installed.
+ * Names the plugin and the import that supplies it, because the remedy is
+ * a construction-site edit and not a call-site one. */
+export declare function pluginMissingError(plugin: string, api: string): ECSError;
+/** The fault a world raises when a plugin reaches its install seam twice.
+ * The install replaces the service, so the second one silently strands every
+ * definition and handle the first one minted. */
+export declare function pluginInstalledTwiceError(plugin: string): ECSError;
+//# sourceMappingURL=plugin_error.d.ts.map

package/dist/core/ecs/utils/plugin_error.d.ts

@@ -0,0 +1,10 @@
+import { ECSError } from './error.js';
+/** The fault a world raises when a caller uses a subsystem it never installed.
+ * Names the plugin and the import that supplies it, because the remedy is
+ * a construction-site edit and not a call-site one. */
+export declare function pluginMissingError(plugin: string, api: string): ECSError;
+/** The fault a world raises when a plugin reaches its install seam twice.
+ * The install replaces the service, so the second one silently strands every
+ * definition and handle the first one minted. */
+export declare function pluginInstalledTwiceError(plugin: string): ECSError;
+//# sourceMappingURL=plugin_error.d.ts.map

package/dist/core/ecs/utils/plugin_error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin_error.d.ts","sourceRoot":"","sources":["../../../../src/core/ecs/utils/plugin_error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;KAYK;AAEL,OAAO,EAAE,QAAQ,EAAa,MAAM,SAAS,CAAC;AAE9C;;uDAEuD;AACvD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAQxE;AAED;;iDAEiD;AACjD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAMlE"}

package/dist/core/restore_errors.d.cts

@@ -0,0 +1,30 @@
+/***
+ * The restore error classes, in one module both core layers import.
+ *
+ * A caller catches a restore failure by class, so there must be exactly one
+ * `StoreRestoreError` and one `SparseRestoreError` in a program. The dense
+ * half throws from `core/store`, the sparse half throws from `core/ecs`, and
+ * the snapshot plugin ships in its own rollup graph. A class declared
+ * beside either thrower would be copied into that graph. `err instanceof
+ * StoreRestoreError` would then answer `false` against the class the package
+ * root exports.
+ *
+ * One module holding both is what the plugin build marks external and
+ * resolves to the core artifact. Keep it free of imports, so the mapping stays
+ * a leaf and the module carries no state beyond the two classes.
+ *
+ * Cold path. A restore failure ends the call.
+ ***/
+/** Thrown when the dense half of a snapshot is malformed: too short for the
+ * header, the wrong magic, an incompatible ABI version, or a layout region
+ * that runs past the buffer. */
+export declare class StoreRestoreError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the sparse half of a snapshot does not match the live world:
+ * truncated bytes, a different store count, or a field schema that differs
+ * from the one the bytes were written against. */
+export declare class SparseRestoreError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=restore_errors.d.ts.map

package/dist/core/restore_errors.d.ts

@@ -0,0 +1,30 @@
+/***
+ * The restore error classes, in one module both core layers import.
+ *
+ * A caller catches a restore failure by class, so there must be exactly one
+ * `StoreRestoreError` and one `SparseRestoreError` in a program. The dense
+ * half throws from `core/store`, the sparse half throws from `core/ecs`, and
+ * the snapshot plugin ships in its own rollup graph. A class declared
+ * beside either thrower would be copied into that graph. `err instanceof
+ * StoreRestoreError` would then answer `false` against the class the package
+ * root exports.
+ *
+ * One module holding both is what the plugin build marks external and
+ * resolves to the core artifact. Keep it free of imports, so the mapping stays
+ * a leaf and the module carries no state beyond the two classes.
+ *
+ * Cold path. A restore failure ends the call.
+ ***/
+/** Thrown when the dense half of a snapshot is malformed: too short for the
+ * header, the wrong magic, an incompatible ABI version, or a layout region
+ * that runs past the buffer. */
+export declare class StoreRestoreError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the sparse half of a snapshot does not match the live world:
+ * truncated bytes, a different store count, or a field schema that differs
+ * from the one the bytes were written against. */
+export declare class SparseRestoreError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=restore_errors.d.ts.map

package/dist/core/restore_errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore_errors.d.ts","sourceRoot":"","sources":["../../src/core/restore_errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;KAgBK;AAEL;;gCAEgC;AAChC,qBAAa,iBAAkB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI3B;AAED;;kDAEkD;AAClD,qBAAa,kBAAmB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI3B"}