@oasys/oecs 0.5.3 → 0.6.0

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

@@ -1,59 +1,61 @@
 import { EntityID } from './entity.cjs';
 export declare class EntityAllocator {
-    /** SAB-backed per-slot generation counters — replanted on restore. */
+    /** 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). */
+    /** Single-slot view over the entity-index region's `length` header field,
+     * replanted on restore. Written on every high-water bump. */
     private _lengthView;
     private _highWater;
     private readonly _freeIndices;
     private _aliveCount;
     private readonly _capacity;
-    /** Slot index of the entity allocated by the most recent `alloc` call —
+    /** 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. */
+     * (grow, extend and 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. */
+     * 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
+    /** 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). */
+     * so `isAliveIndex` is already true), a caller placing the entity into an
+     * archetype row must have reserved column capacity first. */
     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
+     * all-or-nothing: `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
+     * 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
+    assertCapacity(count: number): void;
+    /** Release a slot whose entity carried `generation`, for reuse or for
+     * retirement. Bumps the generation so stale IDs read dead. Once the counter
+     * would reach the reserved tombstone the slot retires instead of returning
+     * to the free list: 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
+     * after 2047 reuses is cheap. The branch is predicted not-taken on
      * essentially every destroy. */
-    recycle(index: number, generation: number): void;
+    release(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.) */
+     * malformed-handle guards on top of this.) */
     isAliveIndex(index: number, generation: number): boolean;
-    /** Mirror the current high-water into the SAB `length` header — called
+    /** 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). */
+    /** Restore path. Adopt the high-water recovered from the restored
+     * region's length header, before the replant republishes it. */
     setHighWater(value: number): void;
-    /** Restore path, step 2: adopt the captured free-list + alive count. */
+    /** Restore path. Adopt the captured free list and alive count, after
+     * `setHighWater` has taken the high-water. */
     restoreHostState(freeIndices: readonly number[], aliveCount: number): void;
 }
 //# sourceMappingURL=entity_allocator.d.ts.map

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

@@ -1,59 +1,61 @@
 import { EntityID } from './entity.js';
 export declare class EntityAllocator {
-    /** SAB-backed per-slot generation counters — replanted on restore. */
+    /** 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). */
+    /** Single-slot view over the entity-index region's `length` header field,
+     * replanted on restore. Written on every high-water bump. */
     private _lengthView;
     private _highWater;
     private readonly _freeIndices;
     private _aliveCount;
     private readonly _capacity;
-    /** Slot index of the entity allocated by the most recent `alloc` call —
+    /** 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. */
+     * (grow, extend and 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. */
+     * 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
+    /** 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). */
+     * so `isAliveIndex` is already true), a caller placing the entity into an
+     * archetype row must have reserved column capacity first. */
     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
+     * all-or-nothing: `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
+     * 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
+    assertCapacity(count: number): void;
+    /** Release a slot whose entity carried `generation`, for reuse or for
+     * retirement. Bumps the generation so stale IDs read dead. Once the counter
+     * would reach the reserved tombstone the slot retires instead of returning
+     * to the free list: 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
+     * after 2047 reuses is cheap. The branch is predicted not-taken on
      * essentially every destroy. */
-    recycle(index: number, generation: number): void;
+    release(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.) */
+     * malformed-handle guards on top of this.) */
     isAliveIndex(index: number, generation: number): boolean;
-    /** Mirror the current high-water into the SAB `length` header — called
+    /** 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). */
+    /** Restore path. Adopt the high-water recovered from the restored
+     * region's length header, before the replant republishes it. */
     setHighWater(value: number): void;
-    /** Restore path, step 2: adopt the captured free-list + alive count. */
+    /** Restore path. Adopt the captured free list and alive count, after
+     * `setHighWater` has taken the high-water. */
     restoreHostState(freeIndices: readonly number[], aliveCount: number): void;
 }
 //# sourceMappingURL=entity_allocator.d.ts.map

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

@@ -1 +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"}
+{"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,qEAAqE;IACrE,OAAO,CAAC,YAAY,CAAa;IACjC;iEAC6D;IAC7D,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;wEACoE;IAC7D,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;;;iEAG6D;IACtD,KAAK,IAAI,QAAQ;IA8BxB;;;;6CAIyC;IAClC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAY1C;;;;;;;oCAOgC;IACzB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAWvD;;kDAE8C;IACvC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAI/D;4EACwE;IACjE,aAAa,IAAI,IAAI;IAOrB,mBAAmB,IAAI,MAAM,EAAE;IAItC;oEACgE;IACzD,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIxC;kDAC8C;IACvC,gBAAgB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;CAKjF"}

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

@@ -2,24 +2,24 @@ 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`)
+ * 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
+ * This is the erased and 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
+ * 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
+ * Homomorphic constraint for event-schema type params:
+ * `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. */
+/** 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 & {
@@ -29,28 +29,42 @@ export type EventDef<S extends EventShape<S> = EventSchema> = EventID & {
  * 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.
+ * 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.
+ * **advisory**, the columns are the same live `number[]` objects the channel
+ * mutates, so the `readonly` typing blocks writes at the type layer only. A
+ * deliberate 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;
+/** The event registry, as everything outside the plugin sees it.
+ *
+ * `Store.events` is public, so this is the whole crossing surface. The
+ * plugin's class implements it, and the compiler holds the two in step.
+ *
+ * `SystemContext` resolves a key and emits or reads through this. `ECS.update`
+ * clears the channels at the tick tail, and a `DEV` build samples the buffered
+ * count either side of the observer drain. */
+export interface EventHooks {
+    /** Register a channel and take its def. The key form is what a caller
+     * uses, and this is the anonymous one the key form builds on. */
+    register<S extends EventShape<S>>(fields: readonly (keyof S & string)[]): EventDef<S>;
+    /** Register a channel under a module-scope key. Throws on a repeat. */
+    registerByKey<S extends EventShape<S>>(key: symbol, fields: readonly (keyof S & string)[]): EventDef<S>;
+    /** The def a key was registered under. Throws when it was not. */
+    defByKey(key: symbol): EventDef<any>;
+    hasKey(key: symbol): boolean;
+    emit(def: EventDef<any>, values: Record<string, number>): void;
+    emitSignal(def: EventDef<EmptyEventSchema>): void;
+    reader<S extends EventShape<S>>(def: EventDef<S>): EventReader<S>;
+    /** Drop every channel emitted to this tick. Runs once per `update()`. */
     clear(): void;
+    /** `DEV` only. Events buffered across the dirty channels right now. */
+    devBufferedCount(): number;
 }
 declare const __eventKeySchema: unique symbol;
 export type EventKey<S extends EventShape<S> = EventSchema> = symbol & {
@@ -62,17 +76,17 @@ export type SignalKey = EventKey<EmptyEventSchema> & {
 };
 /**
  * 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
+ * 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
+ * string index signature (erased or 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 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 {};

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

@@ -2,24 +2,24 @@ import { Brand } from '../../type_primitives/index.js';
 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`)
+ * 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
+ * This is the erased and 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
+ * 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
+ * Homomorphic constraint for event-schema type params:
+ * `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. */
+/** 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 & {
@@ -29,28 +29,42 @@ export type EventDef<S extends EventShape<S> = EventSchema> = EventID & {
  * 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.
+ * 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.
+ * **advisory**, the columns are the same live `number[]` objects the channel
+ * mutates, so the `readonly` typing blocks writes at the type layer only. A
+ * deliberate 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;
+/** The event registry, as everything outside the plugin sees it.
+ *
+ * `Store.events` is public, so this is the whole crossing surface. The
+ * plugin's class implements it, and the compiler holds the two in step.
+ *
+ * `SystemContext` resolves a key and emits or reads through this. `ECS.update`
+ * clears the channels at the tick tail, and a `DEV` build samples the buffered
+ * count either side of the observer drain. */
+export interface EventHooks {
+    /** Register a channel and take its def. The key form is what a caller
+     * uses, and this is the anonymous one the key form builds on. */
+    register<S extends EventShape<S>>(fields: readonly (keyof S & string)[]): EventDef<S>;
+    /** Register a channel under a module-scope key. Throws on a repeat. */
+    registerByKey<S extends EventShape<S>>(key: symbol, fields: readonly (keyof S & string)[]): EventDef<S>;
+    /** The def a key was registered under. Throws when it was not. */
+    defByKey(key: symbol): EventDef<any>;
+    hasKey(key: symbol): boolean;
+    emit(def: EventDef<any>, values: Record<string, number>): void;
+    emitSignal(def: EventDef<EmptyEventSchema>): void;
+    reader<S extends EventShape<S>>(def: EventDef<S>): EventReader<S>;
+    /** Drop every channel emitted to this tick. Runs once per `update()`. */
     clear(): void;
+    /** `DEV` only. Events buffered across the dirty channels right now. */
+    devBufferedCount(): number;
 }
 declare const __eventKeySchema: unique symbol;
 export type EventKey<S extends EventShape<S> = EventSchema> = symbol & {
@@ -62,17 +76,17 @@ export type SignalKey = EventKey<EmptyEventSchema> & {
 };
 /**
  * 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
+ * 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
+ * string index signature (erased or 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 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 {};

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

@@ -1 +1 @@
-{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/event.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmCK;AAEL,OAAO,EAAE,KAAK,EAAc,MAAM,uBAAuB,CAAC;AAI1D,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAKhD,eAAO,MAAM,SAAS,UAAW,MAAM,KAAG,OAQzC,CAAC;AAEF;;;;;;;+DAO+D;AAC/D,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;CAAE,CAAC;AAEhE,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;AAQ/D,OAAO,CAAC,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC;AAE3C,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,GAAG,WAAW,IAAI,OAAO,GAAG;IACvE,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;CAC1C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,IAAI;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAErD;;;;;;;8CAO8C;AAC9C,MAAM,WAAW,UAAU;IAC1B;qEACiE;IACjE,QAAQ,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtF,uEAAuE;IACvE,aAAa,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EACpC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,GACnC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACf,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC/D,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC;IAClD,MAAM,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAClE,yEAAyE;IACzE,KAAK,IAAI,IAAI,CAAC;IACd,uEAAuE;IACvE,gBAAgB,IAAI,MAAM,CAAC;CAC3B;AAUD,OAAO,CAAC,MAAM,gBAAgB,EAAE,OAAO,MAAM,CAAC;AAE9C,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,GAAG,WAAW,IAAI,MAAM,GAAG;IACtE,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;CAC7C,CAAC;AAQF,OAAO,CAAC,MAAM,WAAW,EAAE,OAAO,MAAM,CAAC;AAEzC,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,gBAAgB,CAAC,GAAG;IACpD,QAAQ,CAAC,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,CAC3B,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EACvB,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,IACpC,MAAM,SAAS,MAAM,CAAC,GACvB,OAAO,GACP,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,KAAK,GACjD,OAAO,GACP,SAAS,CAAC,+BAA+B,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;AAErF,wBAAgB,QAAQ,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAE3E;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAEjD"}

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

@@ -1,110 +1,14 @@
 import { Store } from './store.cjs';
-import { EntityID } from './entity.cjs';
-import { OnDeleteTarget, RelationDef, RelationOptions } from './relation.cjs';
 import { ResourceKey } from './resource.cjs';
-import { EventFieldsCover, EventKey, EventReader, EventShape, SignalKey } from './event.cjs';
-/** Relations — sparse `(relation, target)` pairs and hierarchy traversal
- * (#471 / #474, ADR-0011). Add/remove/re-target cause no archetype
- * transition; ops are immediate and safe mid-tick. Traversal and wildcard
- * reads are cold-path. */
-export declare class ECSRelations {
-    private readonly store;
-    /** @internal constructed by `ECS`. */
-    constructor(store: Store);
-    /** Register a relation kind. Exclusive (default) stores one target per
-     * source; `{ multi: true }` stores a target set per source.
-     * `{ onDeleteTarget: "delete" | "clear" | "orphan" }` selects target-death
-     * cleanup (default `orphan`, #473).
-     *
-     * The overloads stamp the CARDINALITY into the handle type (typestate
-     * a173382 / POLISH_AUDIT #7), exactly like the flat `registerRelation`:
-     * the exclusive-only surfaces (`targetOf`, `ancestorsOf`/`rootOf`/
-     * `cascadeOf`, `Query.hierarchy`) accept only `RelationDef<"exclusive">`,
-     * so passing a `{ multi: true }` relation is a compile error. A
-     * dynamically-built options value falls to the erased overload and keeps
-     * the runtime check as its only guard. */
-    register(opts?: {
-        readonly exclusive?: true;
-        readonly multi?: false;
-        readonly onDeleteTarget?: OnDeleteTarget;
-    }): RelationDef<"exclusive">;
-    register(opts: {
-        readonly multi: true;
-        readonly exclusive?: false;
-        readonly onDeleteTarget?: OnDeleteTarget;
-    }): RelationDef<"multi">;
-    register(opts?: RelationOptions): RelationDef;
-    /** Count of registered relations. */
-    get count(): number;
-    /** Add a `(R, tgt)` pair to `src`. Exclusive replaces the existing target;
-     * multi adds to the set. No archetype transition. */
-    add(src: EntityID, def: RelationDef, tgt: EntityID): this;
-    /** Remove a `(R, tgt)` pair from `src`. For multi, omitting `tgt` removes
-     * all of `src`'s targets. No archetype transition. */
-    remove(src: EntityID, def: RelationDef, tgt?: EntityID): this;
-    /** Whether `src` holds any pair under `R`. */
-    has(src: EntityID, def: RelationDef): boolean;
-    /** The single target of `src` under an exclusive relation, or `undefined`. */
-    targetOf(src: EntityID, def: RelationDef<"exclusive">): EntityID | undefined;
-    /** All targets of `src` under `R`, ascending by id. */
-    targetsOf(src: EntityID, def: RelationDef): EntityID[];
-    /** Sources pointing at `tgt` under `R` (the reverse index), ascending by id.
-     * `(entity, def)` order, matching `targetOf` / `targetsOf`. */
-    sourcesOf(tgt: EntityID, def: RelationDef): EntityID[];
-    /** All `(source, target)` pairs of relation `R` — the `(R, *)` wildcard
-     * (#472). Sources in canonical entity-index order. Cold path. */
-    pairsOf(def: RelationDef): readonly (readonly [EntityID, EntityID])[];
-    /** Every `(relation, source)` pointing at `tgt`, across all relation kinds —
-     * the `(*, T)` wildcard (#472). Ordered by relation id then source id. */
-    sourcesOfAny(tgt: EntityID): readonly (readonly [RelationDef, EntityID])[];
-    /** Walk relation `R` up from `src` to its chain root, returning
-     * `[src, parent, …, root]` (nearest-ancestor-first). Exclusive only. */
-    ancestorsOf(src: EntityID, def: RelationDef<"exclusive">): EntityID[];
-    /** The root of `src`'s `R`-chain (`src` itself when it has no target).
-     * Exclusive only. */
-    rootOf(src: EntityID, def: RelationDef<"exclusive">): EntityID;
-    /** Walk relation `R` down from `root` over the reverse index, returning the
-     * subtree (including `root`) breadth-first — parents before children (the
-     * `cascade` order). Exclusive only. */
-    cascadeOf(root: EntityID, def: RelationDef<"exclusive">): EntityID[];
-    /** Reclaim relation reverse-index memory: drop every reverse entry whose
-     * target has been destroyed, returning the total dropped (#491). Purely
-     * cold-path, no observable state change — call at scene/snapshot
-     * boundaries. */
-    compact(): number;
-}
-/** Event channels and signals. Emit during one `update()`, visible to every
- * later system in that call, cleared before the next. System-side reads and
- * emits go through `ctx` — this facade is the HOST-side surface. */
-export declare class ECSEvents {
-    private readonly store;
-    /** @internal constructed by `ECS`. */
-    constructor(store: Store);
-    /** Register an event channel at world setup, before anything emits on it.
-     * `fields` must name EVERY schema key — an under-registered channel would
-     * silently drop the missing fields at emit (see `EventFieldsCover`).
-     *
-     * @example
-     * const Damaged = eventKey<{ target: EntityID; amount: number }>("Damaged");
-     * ecs.events.register(Damaged, ["target", "amount"]);
-     * ecs.events.emit(Damaged, { target: e, amount: 10 }); // or ctx.emit inside a system
-     */
-    register<S extends EventShape<S>, const F extends readonly (keyof S & string)[]>(key: EventKey<S>, fields: F & EventFieldsCover<S, F>): void;
-    /** Register a signal (empty-payload event channel). */
-    registerSignal(key: SignalKey): void;
-    emit(key: SignalKey): void;
-    emit<S extends EventShape<S>>(key: EventKey<S>, values: NoInfer<S>): void;
-    read<S extends EventShape<S>>(key: EventKey<S>): EventReader<S>;
-}
-/** World resources — singleton values keyed by `ResourceKey<T>`. Runtime
- * mutations (`set` / `remove`) are access-checked as resource writes inside
- * a system span; `register` is a one-time world-setup op. */
+/** World resources, singleton values keyed by `ResourceKey<T>`. Runtime
+ * mutations (`set` and `remove`) are access-checked as resource writes inside
+ * a system span. `register` is a one-time world-setup op. */
 export declare class ECSResources {
-    private readonly store;
+    private readonly _store;
     /** @internal constructed by `ECS`. */
     constructor(store: Store);
-    /** Register a resource at world setup. Reading/writing an unregistered
-     * key throws (fail-closed) — registration is the explicit "this world has
+    /** Register a resource at world setup. Reading and writing an unregistered
+     * key throws (fail-closed), registration is the explicit "this world has
      * this singleton" declaration, not a lazy default.
      *
      * @example
@@ -115,44 +19,26 @@ export declare class ECSResources {
     register<T>(key: ResourceKey<T>, value: NoInfer<T>): void;
     get<T>(key: ResourceKey<T>): T;
     set<T>(key: ResourceKey<T>, value: NoInfer<T>): void;
-    /** Drop a resource from the world (#798). Access-checked as a *write*;
+    /** Drop a resource from the world. Access-checked as a *write*, and it
      * fails closed on a missing key. Afterwards the key is free to `register`
-     * again — the present → absent → present lifecycle. */
+     * again, the present → absent → present lifecycle. */
     remove<T>(key: ResourceKey<T>): void;
     has<T>(key: ResourceKey<T>): boolean;
 }
-/** The determinism surface (#626 / ADR-0020): world snapshot/resume and the
+/** The determinism surface: world snapshot and resume and the
  * canonical state digest. Every member except `deterministic` throws
  * `DETERMINISM_DISABLED` unless the world was constructed with
- * `{ deterministic: true }`. All cold-path — take captures at tick
+ * `{ deterministic: true }`. All cold-path, take captures at tick
  * boundaries (between `update()`s). */
 export declare class ECSSnapshots {
-    private readonly store;
+    protected readonly _store: Store;
     /** @internal constructed by `ECS`. */
     constructor(store: Store);
     /** Whether the determinism surface is enabled. */
     get deterministic(): boolean;
-    /** FNV-1a 32 digest over every archetype's live rows in id order — the
+    /** FNV-1a 32 digest over every archetype's live rows in id order, the
      * canonical "live ECS state digest". Per-call cost scales with live
      * entity count, not SAB capacity. */
     stateHash(): number;
-    /** Capture the full live world (dense + sparse/relations + host-side
-     * bookkeeping) to one self-contained byte buffer that `restore` can mount
-     * back onto a live, ticking world (#789). v1 does NOT capture resources,
-     * events, or change-detection baselines (ADR-0031). */
-    capture(): Uint8Array;
-    /** Mount a `capture()` buffer onto this live world and keep ticking.
-     * Fails closed on a malformed frame or registration mismatch BEFORE
-     * mutating any live state. Requires a matching archetype set + column
-     * layout (prewarm so the set is stable). */
-    restore(bytes: Uint8Array): void;
-    /** Serialize the sparse stores + relations to a self-contained buffer —
-     * the sparse half of a world snapshot, canonical entity-index order
-     * (#470). Pairs with `restoreSparse`. */
-    captureSparse(): Uint8Array;
-    /** Repopulate the sparse stores + relation indices from `captureSparse`
-     * bytes. Sparse components must already be registered in the same order;
-     * throws `SparseRestoreError` on a shape or identity mismatch. */
-    restoreSparse(bytes: Uint8Array): void;
 }
 //# sourceMappingURL=facades.d.ts.map