@oasys/oecs 0.5.3 → 0.6.0

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

@@ -1,39 +1,56 @@
 import { InPlaceBufferAllocator } from '../store/index.js';
-/** Default byte ceiling of the growable backing — mirrors
- * `growableSabAllocator`'s default (see its doc comment for the measured
- * footprint analysis that makes 256 MiB structurally unreachable). */
+/** Default store base for the wasm backing, one WASM page. It clears nothing on
+ * its own. It is the smallest base that keeps the header off address 0, which a
+ * safe Zig or Rust build cannot read. A caller whose module reaches higher
+ * passes a base above that module's `__heap_base`. */
+export declare const WASM_STORE_BASE_BYTES: number;
+/**
+ * A store base that clears a module's own memory, read from the module.
+ *
+ * A compiled module owns the low addresses of its linear memory. Its data
+ * segment, its shadow stack and its heap all start there, and `__heap_base` is
+ * the first address above the segment and the stack. A store based below that
+ * overlaps the module. The loss is silent, because the region that lands under
+ * a module is the entity index and no digest folds it.
+ *
+ * `extraBytes` is the run-time heap the module allocates above `__heap_base`.
+ * Only the module can bound it, so the caller passes it. Pass the module's own
+ * peak, not a guess, because a store based inside the heap fails the same
+ * silent way.
+ *
+ * The result rounds up to a whole WASM page, so a grow of the module's memory
+ * never lands in the middle of the store's first page. Cold path, and a caller
+ * runs it once, between instantiation and `ECS.create`.
+ *
+ * @example
+ * const instance = await WebAssembly.instantiate(module, { env: { memory } });
+ * const ecs = ECS.create({
+ *   memory: {
+ *     backing: { wasm: { memory } },
+ *     storeBase: storeBaseAbove(instance.exports, 4 * 1024 * 1024)
+ *   }
+ * });
+ */
+export declare function storeBaseAbove(exports: Record<string, unknown>, extraBytes?: number): number;
+/** Default byte ceiling of every backing, mirrors `growableSabAllocator`'s
+ * default (see its doc comment for the measured footprint analysis that makes
+ * 256 MiB structurally unreachable). */
 export declare const DEFAULT_ECS_CAP_BYTES: number;
-/** Headroom multiplier applied to a budget's live column bytes: capacity
- * doubling plus abandoned in-place holes bound worst-case footprint at ~3×
- * live data (footprint analysis in `growableSabAllocator`'s doc). */
+/** Headroom multiplier applied to an entity count's live column bytes: capacity
+ * doubling plus abandoned in-place holes bound the worst-case footprint at
+ * this multiple of the live data (footprint analysis in `growableSabAllocator`'s doc). */
 export declare const BUDGET_GROWTH_HEADROOM = 3;
-/** Default average fully-populated row stride assumed by the budget arm.
- * The instrumented 2-party workload measured ~49 B/entity; 64 rounds up. */
+/** Default average fully-populated row stride assumed when the caller gives an
+ * entity count. A workload with two components uses less than this for each
+ * row, thus 64 rounds up and gives headroom. */
 export declare const BUDGET_DEFAULT_BYTES_PER_ENTITY = 64;
-/** Default archetype spread assumed by the budget arm when the consumer
- * doesn't declare one. Drives only the derived per-archetype column
- * capacity, not correctness — an under-declared spread just means earlier
- * (amortised) column doubling. */
+/** Default archetype spread assumed when the caller doesn't declare one. Drives
+ * only the derived per-archetype column capacity, not correctness, an
+ * under-declared spread only means earlier (amortised) column doubling. */
 export declare const BUDGET_DEFAULT_ARCHETYPES = 8;
-/** Sizing intent: "I expect a world about this big." The engine derives
- * column capacity, entity-index reservation, and the byte cap from it, and
- * cap errors are phrased against this budget. */
-export interface EntityBudget {
-    /** Expected peak live entities — the one number most callers know.
-     * Bounded by the EntityID 20-bit index space (1<<20). */
-    readonly entities: number;
-    /** Expected distinct archetypes the entities spread across.
-     * Default `BUDGET_DEFAULT_ARCHETYPES`. */
-    readonly archetypes?: number;
-    /** Average fully-populated row stride in bytes.
-     * Default `BUDGET_DEFAULT_BYTES_PER_ENTITY`. */
-    readonly bytesPerEntity?: number;
-}
-/** WASM-backed memory, first-class (#682). Either bring your own shared
- * `WebAssembly.Memory` (the server match context does — its sim factory
- * owns the memory), or declare page bounds and let the engine construct
- * it — replacing the hand-wired incantation that previously lived only in
- * `workbench/ecs/scripts/run-memory.ts`. */
+/** WASM-backed memory. Either bring your own shared `WebAssembly.Memory`, which
+ * a consumer that instantiates the module itself already owns, or declare page
+ * bounds and let the engine construct it. */
 export type WasmMemoryArm = {
     readonly memory: WebAssembly.Memory;
     readonly initialPages?: never;
@@ -43,126 +60,108 @@ export type WasmMemoryArm = {
     readonly initialPages?: number;
     readonly memory?: never;
 };
-/** Pure-TS **heap** backing (#643 / ADR-0018 §1B): a plain fixed (non-resizable)
- * `ArrayBuffer` reserved at the cap up front, instead of a `SharedArrayBuffer`.
- * Needs no cross-origin isolation (COOP/COEP) and is the intended default for
- * embedders that can't set those headers (the oecs profile). Trade-off: no
- * worker offload and no WASM compute backend — both require a transferable
- * `SharedArrayBuffer`. An empty `{}` takes the default 256 MiB cap. */
-export interface HeapMemoryArm {
-    /** Byte ceiling of the growable heap backing. Default
-     * `DEFAULT_ECS_CAP_BYTES` (256 MiB), same hard-ceiling semantics as the
-     * SAB backing (#380). */
-    readonly maxBytes?: number;
-}
-/** Opt-in **shared-memory** backing (`@oasys/oecs/shared`): a growable
- * `SharedArrayBuffer` instead of a plain `ArrayBuffer`. Required for worker
- * offload and a WASM compute backend, but needs cross-origin isolation
- * (COOP/COEP) in browsers. Empty `{}` takes the default 256 MiB growable cap. */
-export interface SharedMemoryArm {
-    /** Byte ceiling of the growable shared backing. Default
-     * `DEFAULT_ECS_CAP_BYTES` (256 MiB), hard-ceiling semantics (#380). */
-    readonly maxBytes?: number;
-}
-/** Pinnable on every arm: exact initial rows per archetype column. The
- * budget arm derives one when unpinned; every other arm defaults to
- * `DEFAULT_COLUMN_CAPACITY`. */
-interface ColumnCapacityPin {
-    readonly columnCapacity?: number;
-}
 /**
- * The single sizing option on `ECSOptions.memory`. Key-discriminated —
- * exactly one of `budget` | `maxBytes` | `wasm` | `allocator`, or none for
- * default sizing. The `never` fields make a two-arm literal a type error;
- * `resolveECSMemory` backstops untyped JS callers at runtime.
+ * What backs the world's bytes. This is the only axis with real exclusivity: a
+ * world has exactly one buffer, so these genuinely cannot combine. Sizing is a
+ * separate field and combines with all of them.
+ *
+ *   "heap"        a plain fixed `ArrayBuffer` reserved at the cap. No
+ *                 cross-origin isolation needed, and the default. Trade-off: no
+ *                 worker offload and no WASM compute backend, because both need
+ *                 a transferable `SharedArrayBuffer`.
+ *   "shared"      a growable `SharedArrayBuffer` (`@oasys/oecs/shared`).
+ *                 Enables worker offload and a WASM compute backend, and needs
+ *                 COOP and COEP in a browser. See `growableSabAllocator`'s doc for
+ *                 the JavaScriptCore write cost this backing carries.
+ *   { wasm }      the buffer is a `WebAssembly.Memory`, zero-copy with a WASM
+ *                 `ComputeBackend`.
+ *   { allocator } expert escape hatch. Typed `InPlaceBufferAllocator` so only
+ *                 allocators that statically declare `isInPlace: true` compile.
+ *                 Give `maxBytes` beside it to declare the ceiling, which the
+ *                 index derivation then respects.
  */
-export type ECSMemoryOptions = ({
-    readonly budget: EntityBudget;
-    readonly maxBytes?: never;
-    readonly wasm?: never;
-    readonly allocator?: never;
-    readonly heap?: never;
-    readonly shared?: never;
-} & ColumnCapacityPin) | ({
-    readonly maxBytes: number;
-    readonly budget?: never;
-    readonly wasm?: never;
-    readonly allocator?: never;
-    readonly heap?: never;
-    readonly shared?: never;
-} & ColumnCapacityPin) | ({
+export type MemoryBacking = "heap" | "shared" | {
     readonly wasm: WasmMemoryArm;
-    readonly budget?: never;
-    readonly maxBytes?: never;
     readonly allocator?: never;
-    readonly heap?: never;
-    readonly shared?: never;
-} & ColumnCapacityPin) | ({
-    readonly heap: HeapMemoryArm;
-    readonly budget?: never;
-    readonly maxBytes?: never;
-    readonly wasm?: never;
-    readonly allocator?: never;
-    readonly shared?: never;
-} & ColumnCapacityPin) | ({
-    readonly shared: SharedMemoryArm;
-    readonly budget?: never;
-    readonly maxBytes?: never;
-    readonly wasm?: never;
-    readonly allocator?: never;
-    readonly heap?: never;
-} & ColumnCapacityPin) | ({
-    /** Expert escape hatch. Typed `InPlaceBufferAllocator` so only
-     * allocators that statically declare `isInPlace: true` compile —
-     * the ADR-0008 boundary. `DEFAULT_SAB_ALLOCATOR` is rejected by the
-     * type system; non-in-place allocators stay snapshot/test-sizing
-     * utilities. */
+} | {
     readonly allocator: InPlaceBufferAllocator;
-    /** The allocator owns its real ceiling; this hint only labels
-     * diagnostics (cap errors, `memoryPlan.derivation`). */
-    readonly capBytesHint?: number;
-    readonly budget?: never;
-    readonly maxBytes?: never;
-    readonly wasm?: never;
-    readonly heap?: never;
-    readonly shared?: never;
-} & ColumnCapacityPin) | ({
-    /** No sizing arm: default growable backing (256 MiB cap), with the
-     * column capacity optionally pinned — the minimal migration from the
-     * removed `initialCapacity` knob. */
-    readonly budget?: never;
-    readonly maxBytes?: never;
     readonly wasm?: never;
-    readonly allocator?: never;
-    readonly heap?: never;
-    readonly shared?: never;
-} & ColumnCapacityPin);
+};
+/**
+ * How the world is sized and what backs it. Every field is optional and every
+ * combination is legal, the two axes do not police each other.
+ *
+ * Give `entities` when you know roughly how many the world holds. Give
+ * `maxBytes` when you know the ceiling instead. Give both when you know both:
+ * the count sizes the columns and the entity index, and the cap is yours.
+ */
+export interface ECSMemoryOptions {
+    /** Expected peak live entities, the one number most callers know. Sizes the
+     * column capacity, the entity-index reservation and (unless `maxBytes` says
+     * otherwise) the byte cap. Bounded by the EntityID 20-bit index space
+     * (1<<20). */
+    readonly entities?: number;
+    /** Expected distinct archetypes the entities spread across. Shapes the
+     * derived column capacity only. Needs `entities`. Default
+     * `BUDGET_DEFAULT_ARCHETYPES`. */
+    readonly archetypes?: number;
+    /** Average fully-populated row stride in bytes. Shapes the derived cap only.
+     * Needs `entities`. Default `BUDGET_DEFAULT_BYTES_PER_ENTITY`. */
+    readonly bytesPerEntity?: number;
+    /** Byte ceiling of the backing, with hard-ceiling semantics and no
+     * grow-beyond fallback. Wins over a cap derived from `entities`. For the
+     * allocator backing this is a declaration: the allocator owns the real
+     * ceiling, but the index derivation believes this number. Default
+     * `DEFAULT_ECS_CAP_BYTES` (256 MiB). */
+    readonly maxBytes?: number;
+    /** Exact initial rows per archetype column. Overrides the derived value. */
+    readonly columnCapacity?: number;
+    /** What holds the bytes. Default `"heap"`. */
+    readonly backing?: MemoryBacking;
+    /** Byte offset inside the backing where the store header goes. Every offset
+     * the store writes is relative to it, and the store writes only inside
+     * `[storeBase, storeBase + capacity)`.
+     *
+     * Default 0 for the heap, shared and allocator backings. Default
+     * `WASM_STORE_BASE_BYTES` for the wasm backing, because a module owns the
+     * low addresses of its own linear memory and a safe Zig or Rust build traps
+     * on a read of address 0. Raise it above the module's `__heap_base` plus
+     * whatever the module allocates at run time.
+     *
+     * Must be an integer >= 0 and a multiple of `STORE_BASE_ALIGNMENT`. */
+    readonly storeBase?: number;
+}
 /** What the caller's intent resolved to. Exposed as `ECS.memoryPlan` for
- * diagnostics; `intentLabel`/`budgetEntities`/`capBytes` also travel
- * into `Store` so cap errors speak the caller's language. */
+ * diagnostics. `intentLabel`, `budgetEntities` and `capBytes` also travel into
+ * `Store` so cap errors speak the caller's language. */
 export interface ResolvedECSMemory {
-    readonly source: "default" | "budget" | "max_bytes" | "wasm" | "allocator" | "heap" | "shared";
+    /** Which backing holds the bytes, the axis-B answer. */
+    readonly source: "heap" | "shared" | "wasm" | "allocator";
+    /** Which sizing input drove the numbers, the axis-A answer. */
+    readonly sizing: "default" | "entities" | "maxBytes" | "entities+maxBytes";
     readonly allocator: InPlaceBufferAllocator;
     readonly columnCapacity: number;
     readonly entityIndexCapacity: number;
     /** Byte ceiling of the backing, `null` when unknowable from JS (a
-     * bring-your-own `WebAssembly.Memory` hides its `maximum`; a custom
-     * allocator owns its own cap unless hinted). */
+     * bring-your-own `WebAssembly.Memory` hides its `maximum`. A custom allocator
+     * owns its own cap unless `maxBytes` declared one). */
     readonly capBytes: number | null;
-    /** Human phrasing of the declared intent — reused verbatim in cap
-     * errors so the failure names what the caller asked for. */
+    /** Human phrasing of the declared intent, reused verbatim in cap errors so
+     * the failure names what the caller asked for. */
     readonly intentLabel: string;
-    /** The declared entity budget when the budget arm was used — drives the
-     * "N× the declared budget" cap-error diagnostic. */
+    /** The declared entity count when one was given, drives the "N× the
+     * declared budget" cap-error diagnostic. */
     readonly budgetEntities: number | null;
     /** How each derived number was arrived at, one line per decision. */
     readonly derivation: readonly string[];
-    /** The backing `WebAssembly.Memory` when the wasm arm was used (both
-     * bring-your-own and engine-constructed) — the consumer hands this to
-     * its WASM `ComputeBackend` so the sim and the columns share bytes. */
+    /** Byte offset of the store header inside the backing. */
+    readonly storeBase: number;
+    /** The backing `WebAssembly.Memory` when the wasm backing was used (both
+     * bring-your-own and engine-constructed), the consumer hands this to its
+     * WASM `ComputeBackend` so the module and the columns share bytes. */
     readonly wasmMemory: WebAssembly.Memory | null;
 }
-/** Subset of the plan `Store` needs to phrase cap/overflow errors in the
+/** Subset of the plan `Store` needs to phrase cap and overflow errors in the
  * caller's terms. */
 export interface ECSMemoryCapContext {
     readonly capBytes: number | null;
@@ -170,10 +169,9 @@ export interface ECSMemoryCapContext {
     readonly budgetEntities: number | null;
 }
 /**
- * Turn a consumer's sizing intent into a concrete memory plan. Pure apart
- * from allocator/Memory construction; throws `INVALID_MEMORY_OPTIONS` on a
- * malformed option set — at construction, not first-grow.
+ * Turn a consumer's sizing intent into a concrete memory plan. Pure apart from
+ * allocator and Memory construction. Throws `INVALID_MEMORY_OPTIONS` on a malformed
+ * option set, at construction, not first-grow.
  */
 export declare function resolveECSMemory(opts?: ECSMemoryOptions): ResolvedECSMemory;
-export {};
 //# sourceMappingURL=ecs_memory.d.ts.map

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

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

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

@@ -0,0 +1,89 @@
+import { StoreRegionSpec } from '../store/index.cjs';
+import { ECSMemoryOptions } from './ecs_memory.cjs';
+/** Every key `ECSOptions` accepts, the constructor's dev-mode typo tripwire
+ * checks unknown keys against this (kept adjacent so additions stay in sync). */
+export declare const ECS_OPTION_KEYS: ReadonlySet<string>;
+export interface ECSOptions {
+    fixedTimestep?: number;
+    maxFixedSteps?: number;
+    /** Sink for dev-mode engine diagnostics (currently the schedule's
+     * dropped-ordering-edge warning). Defaults to `console.warn`. Mirrors the
+     * `FrameTraceSink` seam's injectable style, no global logger. */
+    onWarn?: (message: string) => void;
+    /** How the world's memory is sized and backed. Two independent axes, two
+     * independent fields, every combination of them is legal.
+     *
+     * How big: `entities` (with optional `archetypes` and `bytesPerEntity` to
+     * shape the derivation) or `maxBytes`, or both. Give both when you know
+     * both: the count sizes the columns and the entity index, the cap is yours.
+     *
+     * What backs it: `backing`, `"heap"` (default, a plain fixed ArrayBuffer),
+     * `"shared"` (a SharedArrayBuffer, for worker offload or a WASM backend),
+     * `{ wasm }` (the buffer is a WebAssembly.Memory) or `{ allocator }` (the
+     * expert escape hatch, in-place-typed).
+     *
+     * `columnCapacity` pins the rows per archetype column on any combination.
+     * Omitted ⇒ heap backing, a fixed 256 MiB reservation and 1024-row columns.
+     * The resolved plan is exposed as `ECS.memoryPlan`. */
+    memory?: ECSMemoryOptions;
+    /** Consumer-declared SAB regions, forwarded to `Store`. Each
+     * `StoreRegionSpec` carries an opaque `region_id`, a precomputed byte size,
+     * and an `init` closure. The engine lays them out generically and exposes
+     * them through `regionHandle(id)` and `regionOffset(id)`. A consumer
+     * supplies the specs. The engine ships no region of its own. Replaces the
+     * eight game-named region options
+     * (`terrain_map_radius`, `spatial_grid_*`, `army_*`, `flow_field_*`,
+     * `actionRingCapacitySlots`) the ECS used to carry. */
+    regions?: readonly StoreRegionSpec[];
+    /** Byte size of the opt-in bindings region, forwarded to `Store`.
+     * A consumer that attaches a WASM `ComputeBackend` passes its own size,
+     * computed from its own binding manifest, so the host can publish the
+     * `(component_id, field_id)` ids the accelerated systems read. Omitted or
+     * 0 ⇒ no region, and a pure-TS world pays
+     * nothing for the WASM seam. The size is a runtime input, not an engine ABI
+     * constant. It is de-welded from the generated ABI. */
+    bindingsRegionBytes?: number;
+    /** Opt into the **determinism surface**, forwarded to
+     * `Store`. Default `false`. When `false`, the canonical-ordering methods
+     * (`stateHash`, `snapshotSparse`, `restoreSparse`) throw
+     * `DETERMINISM_DISABLED`. When `true`, today's replay and hash behavior is
+     * reproduced bit-for-bit. Determinism is the implementer's choice. A host
+     * that verifies a replay opts in. A host that rolls back with diffs, and
+     * never re-runs the frame, leaves it off. The flag gates only that
+     * surface: memory-safety
+     * invariants (the in-place SAB allocator) and the `enabled_count`
+     * partition are always-on regardless. */
+    deterministic?: boolean;
+}
+/** The fixed-timestep drives the `while (accumulator >= dt)` catch-up loop in
+ * `update()`. A non-positive `dt` makes that loop non-terminating (the
+ * accumulator never decreases), and a non-finite `dt` poisons `fixedAlpha`,
+ * so reject both at the configuration boundary rather than hanging mid-tick. */
+export declare function validateFixedTimestep(value: number): number;
+/** The spiral-of-death clamp in `update()` is `maxAcc = maxFixedSteps *
+ * fixedTimestep; if (accumulator > maxAcc) accumulator = maxAcc`. A non-finite
+ * `maxFixedSteps` makes `maxAcc` non-finite so the clamp never fires and a large
+ * `dt` runs `while (accumulator >= fixedTimestep)` unboundedly, the exact hang
+ * the clamp exists to prevent. A `0` clamps the accumulator to 0, so no fixed
+ * system runs. Validate it as a finite integer ≥ 1, the way `fixedTimestep` is. */
+export declare function validateMaxFixedSteps(value: number): number;
+/**
+ * DEV-only: reject a value that is not a template.
+ *
+ * `spawn` and `spawnMany` take a template from `ECS.template(...)`. Two
+ * mistakes are usual. The caller gives a component definition (`ecs.spawn(Pos)`).
+ * Or the caller gives a bundle (`ecs.spawn(Pos({ x: 0 }))`). The types reject
+ * both. An untyped call site does not.
+ *
+ * Without this check the value goes to the store. The store then reads
+ * `template.archetypeId`, which is `undefined`. The failure is a `TypeError`
+ * about `materializesRows`, from a frame deep in the store. That error names
+ * the wrong place, and it does not tell the caller what to do.
+ *
+ * A template is a plain object with a numeric `archetypeId`. A component
+ * definition is a function. A bundle is an object with `values` and no
+ * `archetypeId`. The test below separates all three, and it names the
+ * alternative for each one.
+ */
+export declare function assertTemplate(value: unknown, op: string): void;
+//# sourceMappingURL=ecs_options.d.ts.map

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

@@ -0,0 +1,89 @@
+import { StoreRegionSpec } from '../store/index.js';
+import { ECSMemoryOptions } from './ecs_memory.js';
+/** Every key `ECSOptions` accepts, the constructor's dev-mode typo tripwire
+ * checks unknown keys against this (kept adjacent so additions stay in sync). */
+export declare const ECS_OPTION_KEYS: ReadonlySet<string>;
+export interface ECSOptions {
+    fixedTimestep?: number;
+    maxFixedSteps?: number;
+    /** Sink for dev-mode engine diagnostics (currently the schedule's
+     * dropped-ordering-edge warning). Defaults to `console.warn`. Mirrors the
+     * `FrameTraceSink` seam's injectable style, no global logger. */
+    onWarn?: (message: string) => void;
+    /** How the world's memory is sized and backed. Two independent axes, two
+     * independent fields, every combination of them is legal.
+     *
+     * How big: `entities` (with optional `archetypes` and `bytesPerEntity` to
+     * shape the derivation) or `maxBytes`, or both. Give both when you know
+     * both: the count sizes the columns and the entity index, the cap is yours.
+     *
+     * What backs it: `backing`, `"heap"` (default, a plain fixed ArrayBuffer),
+     * `"shared"` (a SharedArrayBuffer, for worker offload or a WASM backend),
+     * `{ wasm }` (the buffer is a WebAssembly.Memory) or `{ allocator }` (the
+     * expert escape hatch, in-place-typed).
+     *
+     * `columnCapacity` pins the rows per archetype column on any combination.
+     * Omitted ⇒ heap backing, a fixed 256 MiB reservation and 1024-row columns.
+     * The resolved plan is exposed as `ECS.memoryPlan`. */
+    memory?: ECSMemoryOptions;
+    /** Consumer-declared SAB regions, forwarded to `Store`. Each
+     * `StoreRegionSpec` carries an opaque `region_id`, a precomputed byte size,
+     * and an `init` closure. The engine lays them out generically and exposes
+     * them through `regionHandle(id)` and `regionOffset(id)`. A consumer
+     * supplies the specs. The engine ships no region of its own. Replaces the
+     * eight game-named region options
+     * (`terrain_map_radius`, `spatial_grid_*`, `army_*`, `flow_field_*`,
+     * `actionRingCapacitySlots`) the ECS used to carry. */
+    regions?: readonly StoreRegionSpec[];
+    /** Byte size of the opt-in bindings region, forwarded to `Store`.
+     * A consumer that attaches a WASM `ComputeBackend` passes its own size,
+     * computed from its own binding manifest, so the host can publish the
+     * `(component_id, field_id)` ids the accelerated systems read. Omitted or
+     * 0 ⇒ no region, and a pure-TS world pays
+     * nothing for the WASM seam. The size is a runtime input, not an engine ABI
+     * constant. It is de-welded from the generated ABI. */
+    bindingsRegionBytes?: number;
+    /** Opt into the **determinism surface**, forwarded to
+     * `Store`. Default `false`. When `false`, the canonical-ordering methods
+     * (`stateHash`, `snapshotSparse`, `restoreSparse`) throw
+     * `DETERMINISM_DISABLED`. When `true`, today's replay and hash behavior is
+     * reproduced bit-for-bit. Determinism is the implementer's choice. A host
+     * that verifies a replay opts in. A host that rolls back with diffs, and
+     * never re-runs the frame, leaves it off. The flag gates only that
+     * surface: memory-safety
+     * invariants (the in-place SAB allocator) and the `enabled_count`
+     * partition are always-on regardless. */
+    deterministic?: boolean;
+}
+/** The fixed-timestep drives the `while (accumulator >= dt)` catch-up loop in
+ * `update()`. A non-positive `dt` makes that loop non-terminating (the
+ * accumulator never decreases), and a non-finite `dt` poisons `fixedAlpha`,
+ * so reject both at the configuration boundary rather than hanging mid-tick. */
+export declare function validateFixedTimestep(value: number): number;
+/** The spiral-of-death clamp in `update()` is `maxAcc = maxFixedSteps *
+ * fixedTimestep; if (accumulator > maxAcc) accumulator = maxAcc`. A non-finite
+ * `maxFixedSteps` makes `maxAcc` non-finite so the clamp never fires and a large
+ * `dt` runs `while (accumulator >= fixedTimestep)` unboundedly, the exact hang
+ * the clamp exists to prevent. A `0` clamps the accumulator to 0, so no fixed
+ * system runs. Validate it as a finite integer ≥ 1, the way `fixedTimestep` is. */
+export declare function validateMaxFixedSteps(value: number): number;
+/**
+ * DEV-only: reject a value that is not a template.
+ *
+ * `spawn` and `spawnMany` take a template from `ECS.template(...)`. Two
+ * mistakes are usual. The caller gives a component definition (`ecs.spawn(Pos)`).
+ * Or the caller gives a bundle (`ecs.spawn(Pos({ x: 0 }))`). The types reject
+ * both. An untyped call site does not.
+ *
+ * Without this check the value goes to the store. The store then reads
+ * `template.archetypeId`, which is `undefined`. The failure is a `TypeError`
+ * about `materializesRows`, from a frame deep in the store. That error names
+ * the wrong place, and it does not tell the caller what to do.
+ *
+ * A template is a plain object with a numeric `archetypeId`. A component
+ * definition is a function. A bundle is an object with `values` and no
+ * `archetypeId`. The test below separates all three, and it names the
+ * alternative for each one.
+ */
+export declare function assertTemplate(value: unknown, op: string): void;
+//# sourceMappingURL=ecs_options.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ecs_options.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/ecs_options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;KAaK;AAEL,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD;iFACiF;AACjF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAW9C,CAAC;AAEH,MAAM,WAAW,UAAU;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;qEAEiE;IACjE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;;;;;;;;;;;;;;2DAcuD;IACvD,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;;;;2DAOuD;IACvD,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC;;;;;;2DAMuD;IACvD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;6CASyC;IACzC,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;gFAGgF;AAChF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ3D;AAED;;;;;mFAKmF;AACnF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CA6B/D"}

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

@@ -3,11 +3,11 @@ import { ECSError } from './utils/error.cjs';
 export type EntityID = Brand<number, "entity_id">;
 /**
  * Compile-time readonly view of a `Uint32Array` whose elements are packed
- * `EntityID`s — `Archetype.entityIds` returns this, so `ids[i]` is already
+ * `EntityID`s, `Archetype.entityIds` returns this, so `ids[i]` is already
  * branded and consumers don't re-brand by hand. Blocks index writes at the
  * type layer.
  *
- * **Advisory, not a runtime barrier** — same caveat as `ReadonlyColumn`: the
+ * **Advisory, not a runtime barrier**, same caveat as `ReadonlyColumn`: the
  * underlying value is the live mutable buffer, and indexing past
  * `totalCount - 1` reads stale slots (the brand can't catch that).
  */
@@ -27,8 +27,8 @@ export declare const createEntityId: (index: number, generation: number) => Enti
 export declare const getEntityIndex: (id: EntityID) => number;
 export declare const getEntityGeneration: (id: EntityID) => number;
 /** Build the `ENTITY_NOT_ALIVE` error every dev-mode liveness guard throws:
- * names the failing operation, the packed id, and its decoded index/generation
- * so the user can see WHICH handle went stale without decoding by hand.
+ * names the failing operation, the packed id, and its decoded index and generation
+ * so the user can see which handle went stale without decoding by hand.
  * `detail` appends op-specific context (e.g. the component being read). */
 export declare const entityNotAliveError: (op: string, id: EntityID, detail?: string) => ECSError;
 //# sourceMappingURL=entity.d.ts.map

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

@@ -3,11 +3,11 @@ import { ECSError } from './utils/error.js';
 export type EntityID = Brand<number, "entity_id">;
 /**
  * Compile-time readonly view of a `Uint32Array` whose elements are packed
- * `EntityID`s — `Archetype.entityIds` returns this, so `ids[i]` is already
+ * `EntityID`s, `Archetype.entityIds` returns this, so `ids[i]` is already
  * branded and consumers don't re-brand by hand. Blocks index writes at the
  * type layer.
  *
- * **Advisory, not a runtime barrier** — same caveat as `ReadonlyColumn`: the
+ * **Advisory, not a runtime barrier**, same caveat as `ReadonlyColumn`: the
  * underlying value is the live mutable buffer, and indexing past
  * `totalCount - 1` reads stale slots (the brand can't catch that).
  */
@@ -27,8 +27,8 @@ export declare const createEntityId: (index: number, generation: number) => Enti
 export declare const getEntityIndex: (id: EntityID) => number;
 export declare const getEntityGeneration: (id: EntityID) => number;
 /** Build the `ENTITY_NOT_ALIVE` error every dev-mode liveness guard throws:
- * names the failing operation, the packed id, and its decoded index/generation
- * so the user can see WHICH handle went stale without decoding by hand.
+ * names the failing operation, the packed id, and its decoded index and generation
+ * so the user can see which handle went stale without decoding by hand.
  * `detail` appends op-specific context (e.g. the component being read). */
 export declare const entityNotAliveError: (op: string, id: EntityID, detail?: string) => ECSError;
 //# sourceMappingURL=entity.d.ts.map