@oasys/oecs 0.3.1 → 0.5.0

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

@@ -0,0 +1,179 @@
+import { InPlaceBufferAllocator } from '../store/index.cjs';
+/** 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). */
+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). */
+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. */
+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. */
+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`. */
+export type WasmMemoryArm = {
+    readonly memory: WebAssembly.Memory;
+    readonly initialPages?: never;
+    readonly maximumPages?: never;
+} | {
+    readonly maximumPages: number;
+    readonly initialPages?: number;
+    readonly memory?: never;
+};
+/** Pure-TS **heap** backing (#643 / ADR-0018 §1B): a plain resizable
+ * `ArrayBuffer` 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 growable 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.
+ */
+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) | ({
+    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);
+/** 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. */
+export interface ResolvedECSMemory {
+    readonly source: "default" | "budget" | "max_bytes" | "wasm" | "allocator" | "heap" | "shared";
+    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). */
+    readonly capBytes: number | null;
+    /** 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. */
+    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. */
+    readonly wasmMemory: WebAssembly.Memory | null;
+}
+/** Subset of the plan `Store` needs to phrase cap/overflow errors in the
+ * caller's terms. */
+export interface ECSMemoryCapContext {
+    readonly capBytes: number | null;
+    readonly intentLabel: string;
+    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.
+ */
+export declare function resolveECSMemory(opts?: ECSMemoryOptions): ResolvedECSMemory;
+export {};
+//# sourceMappingURL=ecs_memory.d.ts.map

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

@@ -0,0 +1,179 @@
+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). */
+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). */
+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. */
+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. */
+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`. */
+export type WasmMemoryArm = {
+    readonly memory: WebAssembly.Memory;
+    readonly initialPages?: never;
+    readonly maximumPages?: never;
+} | {
+    readonly maximumPages: number;
+    readonly initialPages?: number;
+    readonly memory?: never;
+};
+/** Pure-TS **heap** backing (#643 / ADR-0018 §1B): a plain resizable
+ * `ArrayBuffer` 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 growable 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.
+ */
+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) | ({
+    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);
+/** 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. */
+export interface ResolvedECSMemory {
+    readonly source: "default" | "budget" | "max_bytes" | "wasm" | "allocator" | "heap" | "shared";
+    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). */
+    readonly capBytes: number | null;
+    /** 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. */
+    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. */
+    readonly wasmMemory: WebAssembly.Memory | null;
+}
+/** Subset of the plan `Store` needs to phrase cap/overflow errors in the
+ * caller's terms. */
+export interface ECSMemoryCapContext {
+    readonly capBytes: number | null;
+    readonly intentLabel: string;
+    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.
+ */
+export declare function resolveECSMemory(opts?: ECSMemoryOptions): ResolvedECSMemory;
+export {};
+//# sourceMappingURL=ecs_memory.d.ts.map

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

@@ -0,0 +1 @@
+{"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/entity.d.cts

@@ -0,0 +1,34 @@
+import { Brand } from '../../type_primitives/index.cjs';
+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
+ * 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
+ * underlying value is the live mutable buffer, and indexing past
+ * `totalCount - 1` reads stale slots (the brand can't catch that).
+ */
+export interface ReadonlyEntityIdArray {
+    readonly [index: number]: EntityID;
+    readonly length: number;
+}
+export declare const INDEX_BITS = 20;
+export declare const INDEX_MASK: number;
+export declare const MAX_INDEX: number;
+export declare const GENERATION_BITS: number;
+export declare const MAX_GENERATION: number;
+export declare const RETIRED_GENERATION: number;
+export declare const MAX_LIVE_GENERATION: number;
+export declare const MAX_ENTITY_ID: number;
+export declare const createEntityId: (index: number, generation: number) => EntityID;
+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.
+ * `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

@@ -0,0 +1,34 @@
+import { Brand } from '../../type_primitives/index.js';
+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
+ * 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
+ * underlying value is the live mutable buffer, and indexing past
+ * `totalCount - 1` reads stale slots (the brand can't catch that).
+ */
+export interface ReadonlyEntityIdArray {
+    readonly [index: number]: EntityID;
+    readonly length: number;
+}
+export declare const INDEX_BITS = 20;
+export declare const INDEX_MASK: number;
+export declare const MAX_INDEX: number;
+export declare const GENERATION_BITS: number;
+export declare const MAX_GENERATION: number;
+export declare const RETIRED_GENERATION: number;
+export declare const MAX_LIVE_GENERATION: number;
+export declare const MAX_ENTITY_ID: number;
+export declare const createEntityId: (index: number, generation: number) => EntityID;
+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.
+ * `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.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/entity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;KA2BK;AAEL,OAAO,EAAE,KAAK,EAAc,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAa,QAAQ,EAAE,MAAM,eAAe,CAAC;AAIpD,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAElD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,UAAU,QAAwB,CAAC;AAChD,eAAO,MAAM,SAAS,QAAa,CAAC;AACpC,eAAO,MAAM,eAAe,QAAiC,CAAC;AAC9D,eAAO,MAAM,cAAc,QAA6B,CAAC;AAQzD,eAAO,MAAM,kBAAkB,QAAiB,CAAC;AAGjD,eAAO,MAAM,mBAAmB,QAAqB,CAAC;AAMtD,eAAO,MAAM,aAAa,QAA6C,CAAC;AAExE,eAAO,MAAM,cAAc,UAAW,MAAM,cAAc,MAAM,KAAG,QAWlE,CAAC;AAEF,eAAO,MAAM,cAAc,OAAQ,QAAQ,KAAG,MAAyB,CAAC;AAExE,eAAO,MAAM,mBAAmB,OAAQ,QAAQ,KAAG,MAAsC,CAAC;AAE1F;;;2EAG2E;AAC3E,eAAO,MAAM,mBAAmB,OAAQ,MAAM,MAAM,QAAQ,WAAW,MAAM,KAAG,QAO9E,CAAC"}

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

@@ -0,0 +1,59 @@
+import { EntityID } from './entity.cjs';
+export declare class EntityAllocator {
+    /** SAB-backed per-slot generation counters — replanted on restore. */
+    private _generations;
+    /** Single-slot view over the entity-index region's `length` header field —
+     * replanted on restore. Written on every high-water bump (#368). */
+    private _lengthView;
+    private _highWater;
+    private readonly _freeIndices;
+    private _aliveCount;
+    private readonly _capacity;
+    /** Slot index of the entity allocated by the most recent `alloc` call —
+     * alloc-free out-param, read immediately after the call (the `_spawnIndex`
+     * pattern the pre-extraction Store used). */
+    lastIndex: number;
+    constructor(capacity: number, generations: Int32Array, lengthView: Uint32Array);
+    /** Re-point the SAB views after the backing buffer was reallocated
+     * (grow/extend/restore). Does NOT touch host-side counters. */
+    replantViews(generations: Int32Array, lengthView: Uint32Array): void;
+    /** The live generations view. Hot flush loops hoist this to a local once
+     * per flush; do not cache it across a potential SAB replant. */
+    get generations(): Int32Array;
+    get highWater(): number;
+    get aliveCount(): number;
+    get freeCount(): number;
+    /** Allocate a slot and return its packed id; the slot index is left in
+     * `lastIndex`. This *commits* the slot (bumps counts, stamps the generation
+     * so `isAliveIndex` is already true) — a caller placing the entity into an
+     * archetype row must have reserved column capacity first (#775). */
+    alloc(): EntityID;
+    /** Pre-check that `count` fresh slots fit, so a bulk-spawn commits
+     * all-or-nothing (#775): `alloc`'s own per-call guard would otherwise
+     * throw partway through the loop, leaving committed slots phantom-alive.
+     * Free-list reuse covers the first `freeCount` slots; only the remainder
+     * draws down the high-water headroom. */
+    ensureCapacity(count: number): void;
+    /** Recycle (or retire) a slot whose entity carried `generation`. Bumps the
+     * generation so stale IDs read dead; once the counter would reach the
+     * reserved tombstone the slot is RETIRED, not recycled (#376): stamp
+     * RETIRED_GENERATION (never issued to a live handle) and skip the
+     * free-list push, closing the ABA window. Burning one of 2^20 indices
+     * after 2047 reuses is cheap; the branch is predicted not-taken on
+     * essentially every destroy. */
+    recycle(index: number, generation: number): void;
+    /** Allocation-side liveness: the slot is in the issued range and its
+     * current generation matches the handle's. (`Store.isAlive` layers the
+     * malformed-handle guards (#778) on top of this.) */
+    isAliveIndex(index: number, generation: number): boolean;
+    /** Mirror the current high-water into the SAB `length` header — called
+     * after a buffer replant so the fresh region carries the host value. */
+    publishLength(): void;
+    snapshotFreeIndices(): number[];
+    /** Restore path, step 1: adopt the high-water recovered from the restored
+     * region's length header BEFORE the replant republishes it (#789). */
+    setHighWater(value: number): void;
+    /** Restore path, step 2: adopt the captured free-list + alive count. */
+    restoreHostState(freeIndices: readonly number[], aliveCount: number): void;
+}
+//# sourceMappingURL=entity_allocator.d.ts.map

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

@@ -0,0 +1,59 @@
+import { EntityID } from './entity.js';
+export declare class EntityAllocator {
+    /** SAB-backed per-slot generation counters — replanted on restore. */
+    private _generations;
+    /** Single-slot view over the entity-index region's `length` header field —
+     * replanted on restore. Written on every high-water bump (#368). */
+    private _lengthView;
+    private _highWater;
+    private readonly _freeIndices;
+    private _aliveCount;
+    private readonly _capacity;
+    /** Slot index of the entity allocated by the most recent `alloc` call —
+     * alloc-free out-param, read immediately after the call (the `_spawnIndex`
+     * pattern the pre-extraction Store used). */
+    lastIndex: number;
+    constructor(capacity: number, generations: Int32Array, lengthView: Uint32Array);
+    /** Re-point the SAB views after the backing buffer was reallocated
+     * (grow/extend/restore). Does NOT touch host-side counters. */
+    replantViews(generations: Int32Array, lengthView: Uint32Array): void;
+    /** The live generations view. Hot flush loops hoist this to a local once
+     * per flush; do not cache it across a potential SAB replant. */
+    get generations(): Int32Array;
+    get highWater(): number;
+    get aliveCount(): number;
+    get freeCount(): number;
+    /** Allocate a slot and return its packed id; the slot index is left in
+     * `lastIndex`. This *commits* the slot (bumps counts, stamps the generation
+     * so `isAliveIndex` is already true) — a caller placing the entity into an
+     * archetype row must have reserved column capacity first (#775). */
+    alloc(): EntityID;
+    /** Pre-check that `count` fresh slots fit, so a bulk-spawn commits
+     * all-or-nothing (#775): `alloc`'s own per-call guard would otherwise
+     * throw partway through the loop, leaving committed slots phantom-alive.
+     * Free-list reuse covers the first `freeCount` slots; only the remainder
+     * draws down the high-water headroom. */
+    ensureCapacity(count: number): void;
+    /** Recycle (or retire) a slot whose entity carried `generation`. Bumps the
+     * generation so stale IDs read dead; once the counter would reach the
+     * reserved tombstone the slot is RETIRED, not recycled (#376): stamp
+     * RETIRED_GENERATION (never issued to a live handle) and skip the
+     * free-list push, closing the ABA window. Burning one of 2^20 indices
+     * after 2047 reuses is cheap; the branch is predicted not-taken on
+     * essentially every destroy. */
+    recycle(index: number, generation: number): void;
+    /** Allocation-side liveness: the slot is in the issued range and its
+     * current generation matches the handle's. (`Store.isAlive` layers the
+     * malformed-handle guards (#778) on top of this.) */
+    isAliveIndex(index: number, generation: number): boolean;
+    /** Mirror the current high-water into the SAB `length` header — called
+     * after a buffer replant so the fresh region carries the host value. */
+    publishLength(): void;
+    snapshotFreeIndices(): number[];
+    /** Restore path, step 1: adopt the high-water recovered from the restored
+     * region's length header BEFORE the replant republishes it (#789). */
+    setHighWater(value: number): void;
+    /** Restore path, step 2: adopt the captured free-list + alive count. */
+    restoreHostState(freeIndices: readonly number[], aliveCount: number): void;
+}
+//# sourceMappingURL=entity_allocator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity_allocator.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/entity_allocator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAsC,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAG7E,qBAAa,eAAe;IAC3B,sEAAsE;IACtE,OAAO,CAAC,YAAY,CAAa;IACjC;wEACoE;IACpE,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC;;iDAE6C;IACtC,SAAS,SAAK;gBAET,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW;IAM9E;mEAC+D;IACxD,YAAY,CAAC,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,GAAG,IAAI;IAK3E;oEACgE;IAChE,IAAW,WAAW,IAAI,UAAU,CAEnC;IAED,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED;;;wEAGoE;IAC7D,KAAK,IAAI,QAAQ;IA8BxB;;;;6CAIyC;IAClC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAY1C;;;;;;oCAMgC;IACzB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAWvD;;yDAEqD;IAC9C,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAI/D;4EACwE;IACjE,aAAa,IAAI,IAAI;IAOrB,mBAAmB,IAAI,MAAM,EAAE;IAItC;0EACsE;IAC/D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIxC,wEAAwE;IACjE,gBAAgB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;CAKjF"}

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

@@ -0,0 +1,79 @@
+import { Brand } from '../../type_primitives/index.cjs';
+export type EventID = Brand<number, "event_id">;
+export declare const asEventId: (value: number) => EventID;
+/** Event schema: field name → value type. Every value is a number at
+ * runtime; the declared type may be a branded number (e.g. `EntityID`)
+ * so the brand survives the emit → read round trip at the type layer.
+ * This is the erased/default schema type; the public surfaces constrain
+ * on `EventShape<S>` (below) instead, so schemas may be declared as type
+ * literals OR interfaces — an interface lacks the implicit index
+ * signature literals get (and so isn't assignable to this `Record`
+ * alias), but satisfies the homomorphic `EventShape` check. */
+export type EventSchema = Readonly<Record<string, number>>;
+/**
+ * Homomorphic constraint for event-schema type params (POLISH_AUDIT M9):
+ * `S extends EventShape<S>` checks every property of `S` is a number WITHOUT
+ * requiring an index signature, so `interface`-declared schemas (which lack
+ * the implicit index signature type literals get) are accepted too.
+ */
+export type EventShape<S> = {
+    readonly [K in keyof S]: number;
+};
+/** Schema of a signal — a zero-field event. */
+export type EmptyEventSchema = Readonly<Record<never, number>>;
+declare const __eventSchema: unique symbol;
+export type EventDef<S extends EventShape<S> = EventSchema> = EventID & {
+    readonly [__eventSchema]: (value: S) => S;
+};
+/**
+ * Reader view over an event channel's SoA columns. Columns are read-only
+ * arrays typed per the event schema: consumers index them and read
+ * `.length`. A field declared as a branded number (e.g. `EntityID`) reads
+ * back branded — no cast at the consumer.
+ *
+ * The "cannot mutate the live channel through the reader" property is
+ * **advisory** — the columns are the same live `number[]` objects the channel
+ * mutates (see `EventChannel` below), so the `readonly` typing blocks writes
+ * at the type layer only; a §10c-policed cast can still write through.
+ */
+export type EventReader<S extends EventShape<S>> = {
+    readonly length: number;
+} & {
+    readonly [K in keyof S]: ReadonlyArray<S[K]>;
+};
+export declare class EventChannel {
+    readonly fieldNames: string[];
+    readonly columns: number[][];
+    readonly reader: EventReader<any>;
+    private readonly _readerLen;
+    constructor(fieldNames: string[]);
+    emit(values: Record<string, number>): void;
+    /** Emit a signal (zero-field event). */
+    emitSignal(): void;
+    clear(): void;
+}
+declare const __eventKeySchema: unique symbol;
+export type EventKey<S extends EventShape<S> = EventSchema> = symbol & {
+    readonly [__eventKeySchema]: (value: S) => S;
+};
+declare const __signalKey: unique symbol;
+export type SignalKey = EventKey<EmptyEventSchema> & {
+    readonly [__signalKey]: true;
+};
+/**
+ * Compile-time exact-cover check for `registerEvent`'s `fields` list. The
+ * element type (`keyof S & string`) already rejects foreign fields; this
+ * catches the inverse mistake — an UNDER-registered channel. Registering
+ * `eventKey<{a; b}>` with `["a"]` used to compile, but `emit` requires the
+ * full payload while the channel only has an `a` column, so `b` was silently
+ * dropped and `reader.b` (typed as an array) was `undefined` at runtime.
+ * Resolves to `unknown` (intersection no-op) when `F` covers every key, and
+ * to an impossible tuple naming the missing fields otherwise. A schema with a
+ * string index signature (erased/untyped keys) skips the check — there is no
+ * finite key set to cover.
+ */
+export type EventFieldsCover<S extends EventShape<S>, F extends readonly (keyof S & string)[]> = string extends keyof S ? unknown : Exclude<keyof S & string, F[number]> extends never ? unknown : readonly [`ERROR — missing event field: ${Exclude<keyof S & string, F[number]>}`];
+export declare function eventKey<S extends EventShape<S>>(name: string): EventKey<S>;
+export declare function signalKey(name: string): SignalKey;
+export {};
+//# sourceMappingURL=event.d.ts.map