@oasys/oecs 0.4.0 → 0.5.0

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

@@ -0,0 +1,176 @@
+import { Brand, TypedArrayTag } from '../../type_primitives/index.cjs';
+export type ComponentID = Brand<number, "component_id">;
+export declare const asComponentId: (value: number) => ComponentID;
+/** Core schema type: maps field names to typed array tags. */
+export type ComponentSchema = Readonly<Record<string, TypedArrayTag>>;
+/** Compile-time tag → TypedArray mapping. */
+export type TagToTypedArray = {
+    f32: Float32Array;
+    f64: Float64Array;
+    i8: Int8Array;
+    i16: Int16Array;
+    i32: Int32Array;
+    u8: Uint8Array;
+    u16: Uint16Array;
+    u32: Uint32Array;
+};
+/** Maps schema fields to their value object: { x: number, y: number }. */
+export type FieldValues<S extends ComponentSchema> = {
+    readonly [K in keyof S]: number;
+};
+/**
+ * Values argument tuple for attaching a component of schema `S` — empty for a
+ * tag, a single optional partial-values map otherwise. A tag schema
+ * (`Record<string, never>`) would otherwise degenerate: `keyof` an
+ * index-signature record is `string`, so `Partial<FieldValues<…>>` collapses to
+ * `Record<string, number>` and `Frozen({ anything: 1 })` compiles. The
+ * conditional forbids values on tags outright; a schema-erased `ComponentDef`
+ * falls into the valued branch, so untyped call sites keep the loose shape.
+ */
+export type ValuesArg<S extends ComponentSchema> = S extends Record<string, never> ? [] : [values?: Partial<FieldValues<S>>];
+/**
+ * `FieldValues` for APIs where the values object is required and complete
+ * (`addComponent`'s valued overload, the host-seam `SpawnEntry`). Guards the
+ * same tag degeneracy as `ValuesArg`: a tag accepts only the empty object
+ * (`Record<string, never>` — every property typed `never`), so
+ * `addComponent(e, Frozen, { x: 1 })` is a compile error while the
+ * tag-overload-less call sites can still pass `{}`.
+ */
+export type CompleteFieldValues<S extends ComponentSchema> = S extends Record<string, never> ? Record<string, never> : FieldValues<S>;
+/**
+ * Trailing-argument tuple for the attach surfaces (`ctx.commands.add`'s
+ * explicit-values form, `ctx.addSparse`): a tag takes NO values argument, a valued schema REQUIRES a
+ * complete one. Encodes the former tag/valued overload pair as one signature,
+ * which the typed system seam needs — its `def` parameter is a single
+ * declared-access-constrained type param, and per-schema overloads would
+ * re-introduce the tag-vs-valued split on top of it.
+ */
+export type AttachValuesArg<S extends ComponentSchema> = S extends Record<string, never> ? [] : [values: CompleteFieldValues<S>];
+/** Maps schema fields to their specific typed array columns. */
+export type ColumnsForSchema<S extends ComponentSchema> = {
+    readonly [K in keyof S]: TagToTypedArray[S[K]];
+};
+/**
+ * Mutable sibling of `ColumnsForSchema` — the field-keyed column group handed
+ * back by `eachChunk`'s `cols.mut(def)` (no `readonly`, since the whole point
+ * is in-place writes). The change-tick is stamped once when the group is
+ * resolved, so the per-row loop is plain typed-array indexing (§eachChunk).
+ */
+export type MutableColumnsForSchema<S extends ComponentSchema> = {
+    [K in keyof S]: TagToTypedArray[S[K]];
+};
+declare const __schema: unique symbol;
+/**
+ * A component handle. **Callable**: `Pos({ x, y })` produces a `Bundle` (omitted
+ * fields zero-fill at attach), so one varargs shape — `spawn(Pos({x,y}),
+ * Vel({vx:1}), IsEnemy)` — replaces the older incompatible attach shapes. A bare
+ * `Pos` (uncalled) still stands in for a tag / all-zero values wherever a
+ * `BundleOrDef` is accepted.
+ *
+ * The numeric component id lives on `.id` (registration order). Consumers treat
+ * the def as an opaque handle; internal code reads `def.id` where it needs the
+ * raw id. The call signature's `S` makes `ComponentDef<{x:"f64"}>` distinct from
+ * `ComponentDef<{vx:"f64"}>`.
+ *
+ * The optional `[__schema]` slot never exists at runtime; it re-states `S` in a
+ * covariant tuple position so that a TAG def type is not a universal assignment
+ * sink. Through the call signature alone every def is assignable to
+ * `ComponentDef<Record<string, never>>` (the tag callable takes no required
+ * args and any `Bundle` satisfies its return), which would let ONE tag in a
+ * system's declared-access union admit every component at compile time
+ * (§typestate — `DeclaredRead` and friends in system.ts). With the slot, a
+ * valued schema is not assignable to the tag schema (`"f64" ⊀ never`), while
+ * schema erasure (`ComponentDef<S>` → bare `ComponentDef`) still works because
+ * every schema is assignable to `ComponentSchema`.
+ *
+ * Build one with `makeComponentDef`; never construct by hand.
+ */
+export interface ComponentDef<S extends ComponentSchema = ComponentSchema> {
+    (...values: ValuesArg<S>): Bundle<S>;
+    readonly id: ComponentID;
+    readonly [__schema]?: [S];
+}
+/**
+ * Recover a def's schema type: `SchemaOf<typeof Pos>` is `{x:"f64", y:"f64"}`.
+ * The typed `SystemContext` methods (§typestate) constrain their `def`
+ * parameter to the system's declared-access union and use this to type the
+ * field argument, in place of taking `ComponentDef<S>` directly.
+ */
+export type SchemaOf<D> = D extends ComponentDef<infer S extends ComponentSchema> ? S : never;
+/**
+ * `unknown` if `D` is one of the query's declared terms, else an error tuple —
+ * the query-seam sibling of system.ts's `DeclaredRead` (§typestate,
+ * POLISH_AUDIT #6). `Query.eachChunk`'s cursor and `ArchetypeView`'s column
+ * accessors intersect this into their `def` parameter so fetching a component
+ * that is NOT a term of the iterating query fails to compile (previously
+ * caught only by the dev-mode access check, and only when the system's
+ * declaration was itself wrong). Same encoding rules as the system asserts:
+ * stable `D extends ComponentDef<any>` constraints keep instantiations
+ * mutually assignable, and the conditional keys on the signature's own `D`.
+ */
+export type DeclaredQueryTerm<Defs extends readonly ComponentDef<any>[], D> = [D] extends [
+    Defs[number]
+] ? unknown : ["component is not a term of this query — add it with .and(...)", D];
+/** Options bag accepted by `registerComponent` / `registerSparseComponent`. */
+export interface ComponentRegisterOptions {
+    /** Debug label for diagnostics — errors then read `'Pos' (component 5)`
+     * instead of `component 5`. Never affects behaviour, layout, or hashing. */
+    readonly name?: string;
+}
+/**
+ * Schema-erased component handle — just the `.id`. Internal, schema-agnostic
+ * code (access checks, dirty-set notes, field-id lookup) takes this instead of
+ * `ComponentDef`: the callable signature makes `ComponentDef<S>` *invariant* in
+ * `S` (a generic `ComponentDef<S>` is not assignable to `ComponentDef`), but
+ * every `ComponentDef<S>` is assignable to `ComponentHandle` because it carries
+ * `.id`. Use it wherever only the id is read.
+ */
+export type ComponentHandle = {
+    readonly id: ComponentID;
+};
+/**
+ * Mint a callable `ComponentDef` for a freshly-registered component id. The
+ * returned function produces a `Bundle` when called (`Pos({x,y})`) and carries
+ * its numeric id on a non-enumerable `.id` (invisible to spreads / `JSON`).
+ * The single cast bridges the function value to the branded handle type — the
+ * `.id` is installed at runtime by `defineProperty` (§10c branded-ID boundary).
+ */
+export declare function makeComponentDef<S extends ComponentSchema>(id: ComponentID): ComponentDef<S>;
+export interface Bundle<S extends ComponentSchema = ComponentSchema> {
+    readonly def: ComponentDef<S>;
+    readonly values: Partial<FieldValues<S>>;
+}
+/** Either a populated bundle or a bare def (tag / all-fields-zero). */
+export type BundleOrDef<S extends ComponentSchema = ComponentSchema> = Bundle<S> | ComponentDef<S>;
+/** Pair a component def with field values to attach. Omitted fields zero-fill;
+ * a tag def takes no values (see `ValuesArg`). */
+export declare function bundle<S extends ComponentSchema>(def: ComponentDef<S>, ...values: ValuesArg<S>): Bundle<S>;
+/** Extract the def from a `BundleOrDef`. A bare def is the callable; a bundle a plain object. */
+export declare function bundleDef(item: BundleOrDef): ComponentDef;
+/** Extract the values from a `BundleOrDef` (a bare def contributes no values). */
+export declare function bundleValues(item: BundleOrDef): Readonly<Record<string, number>>;
+/**
+ * Compile-time readonly view of a typed array column. Blocks index writes at
+ * the type layer.
+ *
+ * **Advisory, not a runtime barrier:** the value behind this type is the live
+ * mutable backing `TypedArray` (`Archetype.getColumnRead` returns
+ * `.buf as unknown as ReadonlyColumn`), so a §10c-policed cast can still write
+ * through. For mutation use the mutable `Archetype.getColumn` (tick-bumping).
+ * Enforced by the escape-hatch lint, not the runtime.
+ */
+export interface ReadonlyColumn {
+    readonly [index: number]: number;
+    readonly length: number;
+}
+/**
+ * Compile-time readonly view of a Uint32Array. Blocks index writes at the type
+ * layer. **Advisory, not a runtime barrier** — same caveat as `ReadonlyColumn`:
+ * the underlying value is the live mutable buffer.
+ */
+export interface ReadonlyUint32Array {
+    readonly [index: number]: number;
+    readonly length: number;
+}
+export {};
+//# sourceMappingURL=component.d.ts.map

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

@@ -1,4 +1,4 @@
-import { Brand, TypedArrayTag } from '../../type_primitives';
+import { Brand, TypedArrayTag } from '../../type_primitives/index.js';
 export type ComponentID = Brand<number, "component_id">;
 export declare const asComponentId: (value: number) => ComponentID;
 /** Core schema type: maps field names to typed array tags. */
@@ -18,6 +18,34 @@ export type TagToTypedArray = {
 export type FieldValues<S extends ComponentSchema> = {
     readonly [K in keyof S]: number;
 };
+/**
+ * Values argument tuple for attaching a component of schema `S` — empty for a
+ * tag, a single optional partial-values map otherwise. A tag schema
+ * (`Record<string, never>`) would otherwise degenerate: `keyof` an
+ * index-signature record is `string`, so `Partial<FieldValues<…>>` collapses to
+ * `Record<string, number>` and `Frozen({ anything: 1 })` compiles. The
+ * conditional forbids values on tags outright; a schema-erased `ComponentDef`
+ * falls into the valued branch, so untyped call sites keep the loose shape.
+ */
+export type ValuesArg<S extends ComponentSchema> = S extends Record<string, never> ? [] : [values?: Partial<FieldValues<S>>];
+/**
+ * `FieldValues` for APIs where the values object is required and complete
+ * (`addComponent`'s valued overload, the host-seam `SpawnEntry`). Guards the
+ * same tag degeneracy as `ValuesArg`: a tag accepts only the empty object
+ * (`Record<string, never>` — every property typed `never`), so
+ * `addComponent(e, Frozen, { x: 1 })` is a compile error while the
+ * tag-overload-less call sites can still pass `{}`.
+ */
+export type CompleteFieldValues<S extends ComponentSchema> = S extends Record<string, never> ? Record<string, never> : FieldValues<S>;
+/**
+ * Trailing-argument tuple for the attach surfaces (`ctx.commands.add`'s
+ * explicit-values form, `ctx.addSparse`): a tag takes NO values argument, a valued schema REQUIRES a
+ * complete one. Encodes the former tag/valued overload pair as one signature,
+ * which the typed system seam needs — its `def` parameter is a single
+ * declared-access-constrained type param, and per-schema overloads would
+ * re-introduce the tag-vs-valued split on top of it.
+ */
+export type AttachValuesArg<S extends ComponentSchema> = S extends Record<string, never> ? [] : [values: CompleteFieldValues<S>];
 /** Maps schema fields to their specific typed array columns. */
 export type ColumnsForSchema<S extends ComponentSchema> = {
     readonly [K in keyof S]: TagToTypedArray[S[K]];
@@ -31,6 +59,7 @@ export type ColumnsForSchema<S extends ComponentSchema> = {
 export type MutableColumnsForSchema<S extends ComponentSchema> = {
     [K in keyof S]: TagToTypedArray[S[K]];
 };
+declare const __schema: unique symbol;
 /**
  * A component handle. **Callable**: `Pos({ x, y })` produces a `Bundle` (omitted
  * fields zero-fill at attach), so one varargs shape — `spawn(Pos({x,y}),
@@ -41,13 +70,52 @@ export type MutableColumnsForSchema<S extends ComponentSchema> = {
  * The numeric component id lives on `.id` (registration order). Consumers treat
  * the def as an opaque handle; internal code reads `def.id` where it needs the
  * raw id. The call signature's `S` makes `ComponentDef<{x:"f64"}>` distinct from
- * `ComponentDef<{vx:"f64"}>`, so no phantom field is needed for nominal typing.
+ * `ComponentDef<{vx:"f64"}>`.
+ *
+ * The optional `[__schema]` slot never exists at runtime; it re-states `S` in a
+ * covariant tuple position so that a TAG def type is not a universal assignment
+ * sink. Through the call signature alone every def is assignable to
+ * `ComponentDef<Record<string, never>>` (the tag callable takes no required
+ * args and any `Bundle` satisfies its return), which would let ONE tag in a
+ * system's declared-access union admit every component at compile time
+ * (§typestate — `DeclaredRead` and friends in system.ts). With the slot, a
+ * valued schema is not assignable to the tag schema (`"f64" ⊀ never`), while
+ * schema erasure (`ComponentDef<S>` → bare `ComponentDef`) still works because
+ * every schema is assignable to `ComponentSchema`.
  *
  * Build one with `makeComponentDef`; never construct by hand.
  */
 export interface ComponentDef<S extends ComponentSchema = ComponentSchema> {
-    (values?: Partial<FieldValues<S>>): Bundle<S>;
+    (...values: ValuesArg<S>): Bundle<S>;
     readonly id: ComponentID;
+    readonly [__schema]?: [S];
+}
+/**
+ * Recover a def's schema type: `SchemaOf<typeof Pos>` is `{x:"f64", y:"f64"}`.
+ * The typed `SystemContext` methods (§typestate) constrain their `def`
+ * parameter to the system's declared-access union and use this to type the
+ * field argument, in place of taking `ComponentDef<S>` directly.
+ */
+export type SchemaOf<D> = D extends ComponentDef<infer S extends ComponentSchema> ? S : never;
+/**
+ * `unknown` if `D` is one of the query's declared terms, else an error tuple —
+ * the query-seam sibling of system.ts's `DeclaredRead` (§typestate,
+ * POLISH_AUDIT #6). `Query.eachChunk`'s cursor and `ArchetypeView`'s column
+ * accessors intersect this into their `def` parameter so fetching a component
+ * that is NOT a term of the iterating query fails to compile (previously
+ * caught only by the dev-mode access check, and only when the system's
+ * declaration was itself wrong). Same encoding rules as the system asserts:
+ * stable `D extends ComponentDef<any>` constraints keep instantiations
+ * mutually assignable, and the conditional keys on the signature's own `D`.
+ */
+export type DeclaredQueryTerm<Defs extends readonly ComponentDef<any>[], D> = [D] extends [
+    Defs[number]
+] ? unknown : ["component is not a term of this query — add it with .and(...)", D];
+/** Options bag accepted by `registerComponent` / `registerSparseComponent`. */
+export interface ComponentRegisterOptions {
+    /** Debug label for diagnostics — errors then read `'Pos' (component 5)`
+     * instead of `component 5`. Never affects behaviour, layout, or hashing. */
+    readonly name?: string;
 }
 /**
  * Schema-erased component handle — just the `.id`. Internal, schema-agnostic
@@ -74,8 +142,9 @@ export interface Bundle<S extends ComponentSchema = ComponentSchema> {
 }
 /** Either a populated bundle or a bare def (tag / all-fields-zero). */
 export type BundleOrDef<S extends ComponentSchema = ComponentSchema> = Bundle<S> | ComponentDef<S>;
-/** Pair a component def with field values to attach. Omitted fields zero-fill. */
-export declare function bundle<S extends ComponentSchema>(def: ComponentDef<S>, values?: Partial<FieldValues<S>>): Bundle<S>;
+/** Pair a component def with field values to attach. Omitted fields zero-fill;
+ * a tag def takes no values (see `ValuesArg`). */
+export declare function bundle<S extends ComponentSchema>(def: ComponentDef<S>, ...values: ValuesArg<S>): Bundle<S>;
 /** Extract the def from a `BundleOrDef`. A bare def is the callable; a bundle a plain object. */
 export declare function bundleDef(item: BundleOrDef): ComponentDef;
 /** Extract the values from a `BundleOrDef` (a bare def contributes no values). */
@@ -103,4 +172,5 @@ export interface ReadonlyUint32Array {
     readonly [index: number]: number;
     readonly length: number;
 }
+export {};
 //# sourceMappingURL=component.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/component.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;KAwBK;AAEL,OAAO,EACN,KAAK,EAGL,KAAK,aAAa,EAClB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACxD,eAAO,MAAM,aAAa,UAAW,MAAM,gBAKzC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;AAEtE,6CAA6C;AAC7C,MAAM,MAAM,eAAe,GAAG;IAC7B,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;IAClB,EAAE,EAAE,SAAS,CAAC;IACd,GAAG,EAAE,UAAU,CAAC;IAChB,GAAG,EAAE,UAAU,CAAC;IAChB,EAAE,EAAE,UAAU,CAAC;IACf,GAAG,EAAE,WAAW,CAAC;IACjB,GAAG,EAAE,WAAW,CAAC;CACjB,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,eAAe,IAAI;IACpD,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;CAC/B,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,eAAe,IAAI;IACzD,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC9C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,eAAe,IAAI;KAC/D,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACrC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe;IACxE,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAC9C,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAA;CAAE,CAAC;AAY3D;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,eAAe,EAAE,EAAE,EAAE,WAAW,GAAG,YAAY,CAAC,CAAC,CAAC,CAO5F;AAED,MAAM,WAAW,MAAM,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe;IAClE,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAG9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;CACzC;AAED,uEAAuE;AACvE,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;AAEnG,kFAAkF;AAClF,wBAAgB,MAAM,CAAC,CAAC,SAAS,eAAe,EAC/C,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAC9B,MAAM,CAAC,CAAC,CAAC,CAEX;AAED,iGAAiG;AACjG,wBAAgB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,YAAY,CAEzD;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAEhF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/component.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,37 @@
+import { Brand } from '../../type_primitives/index.cjs';
+import { StoreLayoutListener } from './store_layout_listener.cjs';
+/**
+ * An opaque token identifying one of a backend's entry points (one
+ * "backend-system"). The engine **never interprets** it — the backend mints it
+ * and is the only thing that maps it back to a concrete computation. Carried on
+ * `SystemConfig.backendHandle` and handed verbatim to `ComputeBackend.run`.
+ *
+ * Branded so a stray `number` can't be mistaken for a handle; consumers mint
+ * one by casting (the backend owns the id space, like flecs's `run` function
+ * pointer or a small index into the backend's entry table).
+ */
+export type BackendSystemHandle = Brand<number, "backend_system_handle">;
+/**
+ * The engine-side contract a compute backend implements. Composes
+ * `StoreLayoutListener` (the already-clean SAB handshake — `setLayout` is called
+ * once on attach to seed the layout and again after every SAB grow/extend) with
+ * a single generic `run` entry point.
+ *
+ * A backend is attached opt-in via `ECS.attachBackend(backend)`, which also
+ * subscribes it as a layout listener, so a backend re-walks the layout on attach
+ * and republish for free.
+ */
+export interface ComputeBackend extends StoreLayoutListener {
+    /**
+     * Execute the backend-system identified by `handle`. Called by the
+     * `Schedule` in place of the system's `fn` closure, inside the same
+     * `accessCheck` span — so the system's declared `writes` authorise whatever
+     * shared-memory columns the backend mutates, exactly as a TS body that calls
+     * out to the backend would be authorised today.
+     *
+     * `handle` is opaque to the engine; it is one the backend minted and the
+     * engine merely round-trips from `SystemConfig.backendHandle`.
+     */
+    run(handle: BackendSystemHandle): void;
+}
+//# sourceMappingURL=compute_backend.d.ts.map

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

@@ -1,5 +1,5 @@
-import { Brand } from '../../type_primitives';
-import { StoreLayoutListener } from './store_layout_listener';
+import { Brand } from '../../type_primitives/index.js';
+import { StoreLayoutListener } from './store_layout_listener.js';
 /**
  * An opaque token identifying one of a backend's entry points (one
  * "backend-system"). The engine **never interprets** it — the backend mints it

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

@@ -0,0 +1,7 @@
+import { ComponentHandle } from './component.cjs';
+export declare function setComponentDebugName(def: ComponentHandle, name: string): void;
+/** The raw registration name (`"Pos"`), or `undefined` when the def is unnamed. */
+export declare function componentDebugName(def: ComponentHandle): string | undefined;
+/** `'Pos' (component 5)` when named at registration, else `component 5`. */
+export declare function componentLabel(def: ComponentHandle): string;
+//# sourceMappingURL=debug_names.d.ts.map

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

@@ -0,0 +1,7 @@
+import { ComponentHandle } from './component.js';
+export declare function setComponentDebugName(def: ComponentHandle, name: string): void;
+/** The raw registration name (`"Pos"`), or `undefined` when the def is unnamed. */
+export declare function componentDebugName(def: ComponentHandle): string | undefined;
+/** `'Pos' (component 5)` when named at registration, else `component 5`. */
+export declare function componentLabel(def: ComponentHandle): string;
+//# sourceMappingURL=debug_names.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"debug_names.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/debug_names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;KAWK;AAEL,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE9E;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAE3E;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAG3D"}

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

@@ -0,0 +1,55 @@
+import { ComponentDef } from './component.cjs';
+import { EntityID } from './entity.cjs';
+import { StructuralObserverEvents } from './store.cjs';
+/** What the drain policy needs from `Store` — closure-injected (the
+ * `RelationServiceHost` style) so nothing new goes public on `Store`. All
+ * calls are flush-granularity, never per-entity. */
+export interface DeferredCommandHost {
+    /** Drain + apply the pending component additions. Each applier fully
+     * drains its buffer(s) and owns its dirty/0-crossing bookkeeping. */
+    readonly applyAdds: () => void;
+    readonly applyRemoves: () => void;
+    readonly applyDestroys: () => void;
+    readonly applyToggles: () => void;
+    /** Hot-path gates — live counts of observed components (#531 / #677).
+     * While both are 0 the flush takes the byte-for-byte fast path. */
+    readonly structuralObserverCount: () => number;
+    readonly toggleObserverCount: () => number;
+    /** The observer-registry dispatch hook, or null (ECS installs it after
+     * construction, so it is re-read per flush). */
+    readonly structuralObserverHook: () => ((ev: StructuralObserverEvents) => void) | null;
+}
+export declare class DeferredCommandBuffer {
+    readonly destroyIds: EntityID[];
+    readonly addIds: EntityID[];
+    readonly addDefs: ComponentDef[];
+    readonly addValues: Record<string, number>[];
+    readonly removeIds: EntityID[];
+    readonly removeDefs: ComponentDef[];
+    readonly toggleIds: EntityID[];
+    readonly toggleDisable: boolean[];
+    /** Re-entrancy guard for the observed fixed-point loop. An observer
+     * callback must enqueue and let the loop settle it — a nested
+     * `ctx.flush()` becomes a no-op; the outer loop drains whatever the
+     * callback queued. */
+    private _flushing;
+    private readonly host;
+    /** Shared effective-event scratch, reset per observed round and handed to
+     * the dispatch hook. Owned by `Store` (its appliers collect into it). */
+    private readonly obsEvents;
+    constructor(host: DeferredCommandHost, obsEvents: StructuralObserverEvents);
+    queueDestroy(id: EntityID): void;
+    queueAdd(id: EntityID, def: ComponentDef, values: Record<string, number>): void;
+    queueRemove(id: EntityID, def: ComponentDef): void;
+    queueToggle(id: EntityID, disable: boolean): void;
+    get destroyCount(): number;
+    get structuralCount(): number;
+    get toggleCount(): number;
+    /** Drain buffered destroys outside the structural flush. No-ops while the
+     * observed fixed point owns the flush — the loop drains destroys itself,
+     * and a re-entrant call would collect into the shared event scratch
+     * mid-dispatch and corrupt it (mirrors the `flushStructural` guard). */
+    flushDestroyed(): void;
+    flushStructural(): void;
+}
+//# sourceMappingURL=deferred_commands.d.ts.map

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

@@ -0,0 +1,55 @@
+import { ComponentDef } from './component.js';
+import { EntityID } from './entity.js';
+import { StructuralObserverEvents } from './store.js';
+/** What the drain policy needs from `Store` — closure-injected (the
+ * `RelationServiceHost` style) so nothing new goes public on `Store`. All
+ * calls are flush-granularity, never per-entity. */
+export interface DeferredCommandHost {
+    /** Drain + apply the pending component additions. Each applier fully
+     * drains its buffer(s) and owns its dirty/0-crossing bookkeeping. */
+    readonly applyAdds: () => void;
+    readonly applyRemoves: () => void;
+    readonly applyDestroys: () => void;
+    readonly applyToggles: () => void;
+    /** Hot-path gates — live counts of observed components (#531 / #677).
+     * While both are 0 the flush takes the byte-for-byte fast path. */
+    readonly structuralObserverCount: () => number;
+    readonly toggleObserverCount: () => number;
+    /** The observer-registry dispatch hook, or null (ECS installs it after
+     * construction, so it is re-read per flush). */
+    readonly structuralObserverHook: () => ((ev: StructuralObserverEvents) => void) | null;
+}
+export declare class DeferredCommandBuffer {
+    readonly destroyIds: EntityID[];
+    readonly addIds: EntityID[];
+    readonly addDefs: ComponentDef[];
+    readonly addValues: Record<string, number>[];
+    readonly removeIds: EntityID[];
+    readonly removeDefs: ComponentDef[];
+    readonly toggleIds: EntityID[];
+    readonly toggleDisable: boolean[];
+    /** Re-entrancy guard for the observed fixed-point loop. An observer
+     * callback must enqueue and let the loop settle it — a nested
+     * `ctx.flush()` becomes a no-op; the outer loop drains whatever the
+     * callback queued. */
+    private _flushing;
+    private readonly host;
+    /** Shared effective-event scratch, reset per observed round and handed to
+     * the dispatch hook. Owned by `Store` (its appliers collect into it). */
+    private readonly obsEvents;
+    constructor(host: DeferredCommandHost, obsEvents: StructuralObserverEvents);
+    queueDestroy(id: EntityID): void;
+    queueAdd(id: EntityID, def: ComponentDef, values: Record<string, number>): void;
+    queueRemove(id: EntityID, def: ComponentDef): void;
+    queueToggle(id: EntityID, disable: boolean): void;
+    get destroyCount(): number;
+    get structuralCount(): number;
+    get toggleCount(): number;
+    /** Drain buffered destroys outside the structural flush. No-ops while the
+     * observed fixed point owns the flush — the loop drains destroys itself,
+     * and a re-entrant call would collect into the shared event scratch
+     * mid-dispatch and corrupt it (mirrors the `flushStructural` guard). */
+    flushDestroyed(): void;
+    flushStructural(): void;
+}
+//# sourceMappingURL=deferred_commands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deferred_commands.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/deferred_commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AASxD;;oDAEoD;AACpD,MAAM,WAAW,mBAAmB;IACnC;yEACqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC;IAClC;uEACmE;IACnE,QAAQ,CAAC,uBAAuB,EAAE,MAAM,MAAM,CAAC;IAC/C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,MAAM,CAAC;IAC3C;oDACgD;IAChD,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC,EAAE,EAAE,wBAAwB,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CACvF;AAED,qBAAa,qBAAqB;IAMjC,SAAgB,UAAU,EAAE,QAAQ,EAAE,CAAM;IAC5C,SAAgB,MAAM,EAAE,QAAQ,EAAE,CAAM;IACxC,SAAgB,OAAO,EAAE,YAAY,EAAE,CAAM;IAC7C,SAAgB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAM;IACzD,SAAgB,SAAS,EAAE,QAAQ,EAAE,CAAM;IAC3C,SAAgB,UAAU,EAAE,YAAY,EAAE,CAAM;IAIhD,SAAgB,SAAS,EAAE,QAAQ,EAAE,CAAM;IAC3C,SAAgB,aAAa,EAAE,OAAO,EAAE,CAAM;IAE9C;;;0BAGsB;IACtB,OAAO,CAAC,SAAS,CAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsB;IAC3C;6EACyE;IACzE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;gBAEzC,IAAI,EAAE,mBAAmB,EAAE,SAAS,EAAE,wBAAwB;IAKnE,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI;IAIhC,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAM/E,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI;IAKlD,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAKxD,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED,IAAW,eAAe,IAAI,MAAM,CAEnC;IAED,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED;;;4EAGwE;IACjE,cAAc,IAAI,IAAI;IAKtB,eAAe,IAAI,IAAI;CA0F9B"}

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

@@ -0,0 +1,93 @@
+/**
+ * Dev-mode dispatch tracer.
+ *
+ * Singleton buffer that captures `(callsite, channel, op, key)` per ECS /
+ * action dispatch when `VISUAL_INTEL_TRACE=1` is set in the environment.
+ * Compile-time gated by `DEV`, so production builds dead-code-eliminate
+ * every record() call. Output is a deterministic JSON snapshot the
+ * `visual-intel` service can ingest as a third channel of evidence
+ * alongside the existing static + symbol-propagation scans.
+ *
+ * Identity model. The engine has no access to source-level binding names
+ * (`ContactEvent`, `ConfigRes`) at runtime — `eventKey("Contact")` returns
+ * `Symbol("Contact")` and the variable name is erased. The tracer records the
+ * runtime-available identifier:
+ *
+ *   - ECS events / resources → the Symbol description (`label`).
+ *   - Actions → the numeric `def.id`.
+ *
+ * Resolution back to bindings happens in `visual-intel`, which already
+ * extracts `{ binding, label }` declarations for events / resources and
+ * `{ binding, id_expr }` for actions; the matching there is unambiguous.
+ *
+ * Callsite resolution. `new Error().stack` inside `record()`, walk the
+ * frames, drop everything inside `packages/engine/src/core/ecs/` (this
+ * file + the dispatcher seam), return the first repo-relative path. Stack-
+ * line strings are cached so repeat dispatches from the same site are
+ * O(1) after the first hit. The walk itself lives in the pure
+ * `resolveCallsiteFromStack()` helper so it can be driven by a synthetic
+ * stack in tests.
+ *
+ * Activation. `record()` is *unconditional* — it records on every call. The
+ * `isActive()` env-var gate is applied by the *callers* (`ecs.ts` /
+ * `query.ts`, all `if (DEV && dispatchTrace.isActive())`), not inside
+ * `record()`. This keeps the gate in one place — the dispatch hot path —
+ * where `DEV === false` dead-code-eliminates the whole branch in prod.
+ */
+export type DispatchChannel = "ecs-events" | "actions" | "resources";
+export type EcsEventOp = "emit" | "read";
+export type ActionOp = "send_action" | "handle_action";
+export type ResourceOp = "read" | "write" | "register" | "remove";
+export interface DispatchTraceEntry {
+    /** Symbol description (events / resources) or numeric `def.id` (actions). */
+    readonly key: string | number;
+    /** Repo-relative POSIX path of the calling file. */
+    readonly file: string;
+    readonly count: number;
+}
+export interface DispatchTraceSnapshot {
+    readonly schemaVersion: 1;
+    readonly capturedAt: string;
+    readonly channels: {
+        readonly "ecs-events": Record<EcsEventOp, DispatchTraceEntry[]>;
+        readonly actions: Record<ActionOp, DispatchTraceEntry[]>;
+        readonly resources: Record<ResourceOp, DispatchTraceEntry[]>;
+    };
+}
+declare class DispatchTrace {
+    private activeCache;
+    private repoRootCache;
+    private buf;
+    private callsiteCache;
+    isActive(): boolean;
+    private repoRoot;
+    private resolveCallsite;
+    private record;
+    recordEmit(label: string): void;
+    recordRead(label: string): void;
+    recordResourceRead(label: string): void;
+    recordResourceWrite(label: string): void;
+    recordResourceRegister(label: string): void;
+    recordResourceRemove(label: string): void;
+    recordSendAction(actId: number): void;
+    recordHandleAction(actId: number): void;
+    snapshot(): DispatchTraceSnapshot;
+    reset(): void;
+}
+declare function parseFrameFile(line: string): string | null;
+/**
+ * Walk a stack string, drop frames inside the engine ECS package, and return
+ * the first non-engine frame as a repo-relative POSIX path (or `null` if the
+ * stack has no attributable frame). Pure so tests can drive it with a
+ * synthetic stack; the optional `cache` memoises per-line results for the hot
+ * dispatch path. Mutates `cache` when supplied.
+ */
+declare function resolveCallsiteFromStack(stack: string | null, repoRoot: string, cache?: Map<string, string | null>): string | null;
+export declare const dispatchTrace: DispatchTrace;
+export declare const _dispatchTraceInternals: {
+    parseFrameFile: typeof parseFrameFile;
+    resolveCallsiteFromStack: typeof resolveCallsiteFromStack;
+    create: () => DispatchTrace;
+};
+export {};
+//# sourceMappingURL=dispatch_trace.d.ts.map

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

@@ -3,7 +3,7 @@
  *
  * Singleton buffer that captures `(callsite, channel, op, key)` per ECS /
  * action dispatch when `VISUAL_INTEL_TRACE=1` is set in the environment.
- * Compile-time gated by `__DEV__`, so production builds dead-code-eliminate
+ * Compile-time gated by `DEV`, so production builds dead-code-eliminate
  * every record() call. Output is a deterministic JSON snapshot the
  * `visual-intel` service can ingest as a third channel of evidence
  * alongside the existing static + symbol-propagation scans.
@@ -30,9 +30,9 @@
  *
  * Activation. `record()` is *unconditional* — it records on every call. The
  * `isActive()` env-var gate is applied by the *callers* (`ecs.ts` /
- * `query.ts`, all `if (__DEV__ && dispatchTrace.isActive())`), not inside
+ * `query.ts`, all `if (DEV && dispatchTrace.isActive())`), not inside
  * `record()`. This keeps the gate in one place — the dispatch hot path —
- * where `__DEV__ === false` dead-code-eliminates the whole branch in prod.
+ * where `DEV === false` dead-code-eliminates the whole branch in prod.
  */
 export type DispatchChannel = "ecs-events" | "actions" | "resources";
 export type EcsEventOp = "emit" | "read";