@oasys/oecs 0.5.4 → 0.6.0

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

@@ -2,19 +2,19 @@ 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
+ * "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
+ * 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
+ * `StoreLayoutListener` (the already-clean SAB handshake, `setLayout` is called
+ * once on attach to seed the layout and again after every SAB grow and extend) with
  * a single generic `run` entry point.
  *
  * A backend is attached opt-in via `ECS.attachBackend(backend)`, which also
@@ -25,13 +25,24 @@ 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
+     * `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
+     * `handle` is opaque to the engine. It is one the backend minted and the
      * engine merely round-trips from `SystemConfig.backendHandle`.
+     *
+     * `deltaTime` is the seconds the phase runs with, the same value a TS body
+     * receives. A module body needs it, and it is not in the store bytes, so it
+     * travels as a call argument. `tick` is the world's frame tick, the count of
+     * `update()` calls so far, and it is not in the bytes either. A backend that
+     * stamps its own frame state reads it here rather than counting calls, which
+     * would drift on a frame that runs the phase more than once.
+     *
+     * The engine publishes the descriptor row counts before this call when a
+     * mutation left them stale, so a module that walks the descriptors sees the
+     * live row count of every archetype.
      */
-    run(handle: BackendSystemHandle): void;
+    run(handle: BackendSystemHandle, deltaTime: number, tick: number): void;
 }
 //# sourceMappingURL=compute_backend.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"compute_backend.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/compute_backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;AAEzE;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAe,SAAQ,mBAAmB;IAC1D;;;;;;;;;OASG;IACH,GAAG,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACvC"}
+{"version":3,"file":"compute_backend.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/compute_backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;AAEzE;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAe,SAAQ,mBAAmB;IAC1D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,GAAG,CAAC,MAAM,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACxE"}

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

@@ -1,23 +1,24 @@
 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
+import { StructuralObserverEvents } from './store_types.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. */
+     * drains its buffer(s) and owns its dirty and 0-crossing bookkeeping. */
     readonly applyAdds: () => void;
     readonly applyRemoves: () => void;
     readonly applyDestroys: () => void;
     readonly applyToggles: () => void;
-    /** Hot-path gates — live counts of observed components.
+    /** Hot-path gates, live counts of observed components.
      * 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;
+    /** The consumers of the structural event batches, in install order, empty
+     * until one arrives (a plugin installs after construction, so the list
+     * is re-read per flush). */
+    readonly structuralHooks: () => readonly ((ev: StructuralObserverEvents) => void)[];
 }
 export declare class DeferredCommandBuffer {
     readonly destroyIds: EntityID[];
@@ -29,27 +30,27 @@ export declare class DeferredCommandBuffer {
     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 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;
+    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;
+    private readonly _observerEvents;
     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 addRemoveCount(): 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,
+     * 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;
+    flushDestroys(): void;
     flushStructural(): void;
 }
 //# sourceMappingURL=deferred_commands.d.ts.map

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

@@ -1,23 +1,24 @@
 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
+import { StructuralObserverEvents } from './store_types.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. */
+     * drains its buffer(s) and owns its dirty and 0-crossing bookkeeping. */
     readonly applyAdds: () => void;
     readonly applyRemoves: () => void;
     readonly applyDestroys: () => void;
     readonly applyToggles: () => void;
-    /** Hot-path gates — live counts of observed components.
+    /** Hot-path gates, live counts of observed components.
      * 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;
+    /** The consumers of the structural event batches, in install order, empty
+     * until one arrives (a plugin installs after construction, so the list
+     * is re-read per flush). */
+    readonly structuralHooks: () => readonly ((ev: StructuralObserverEvents) => void)[];
 }
 export declare class DeferredCommandBuffer {
     readonly destroyIds: EntityID[];
@@ -29,27 +30,27 @@ export declare class DeferredCommandBuffer {
     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 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;
+    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;
+    private readonly _observerEvents;
     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 addRemoveCount(): 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,
+     * 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;
+    flushDestroys(): void;
     flushStructural(): void;
 }
 //# sourceMappingURL=deferred_commands.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"deferred_commands.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/deferred_commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;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;CAyF9B"}
+{"version":3,"file":"deferred_commands.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/deferred_commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;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,eAAe,CAAC;AAS9D;;oDAEoD;AACpD,MAAM,WAAW,mBAAmB;IACnC;6EACyE;IACzE,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;;gCAE4B;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,SAAS,CAAC,CAAC,EAAE,EAAE,wBAAwB,KAAK,IAAI,CAAC,EAAE,CAAC;CACpF;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,KAAK,CAAsB;IAC5C;6EACyE;IACzE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2B;gBAE/C,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,cAAc,IAAI,MAAM,CAElC;IAED,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED;;;4EAGwE;IACjE,aAAa,IAAI,IAAI;IAKrB,eAAe,IAAI,IAAI;CA2F9B"}

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

@@ -1,47 +1,48 @@
 /**
  * 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.
+ * Singleton buffer that captures `(callsite, channel, op, key)` for each ECS
+ * dispatch and each action dispatch, while the environment sets
+ * `VISUAL_INTEL_TRACE` to `1` or to `true`. Compile-time gated by `DEV`, so a
+ * production build dead-code-eliminates every `record()` call. The output is a
+ * deterministic JSON snapshot. An analysis tool outside this repository ingests
+ * it as a runtime channel of evidence, beside a static scan of the same code.
  *
  * Identity model. The engine has no access to source-level binding names
- * (`ContactEvent`, `ConfigRes`) at runtime — `eventKey("Contact")` returns
+ * (`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`).
+ *   - ECS events and 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.
+ * Resolution back to bindings happens in that outside tool, which already
+ * extracts `{ binding, label }` declarations for events and 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-
+ * frames, drop every frame inside the engine itself (any path that matches
+ * `ENGINE_FRAME_MARKERS`), 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.
+ * Activation. `record()` is *unconditional*. It records on every call. Each
+ * caller applies the `isActive()` env-var gate itself (`system_context.ts`,
+ * `facades.ts` and the events plugin facade, all
+ * `if (DEV && dispatchTrace.isActive())`), and `record()` does not. 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). */
+    /** Symbol description (events and resources) or numeric `def.id` (actions). */
     readonly key: string | number;
-    /** Repo-relative POSIX path of the calling file. */
+    /** Repo-relative posix path of the calling file. */
     readonly file: string;
     readonly count: number;
 }
@@ -55,16 +56,16 @@ export interface DispatchTraceSnapshot {
     };
 }
 declare class DispatchTrace {
-    private activeCache;
-    private repoRootCache;
-    private buf;
-    private callsiteCache;
+    private _activeCache;
+    private _repoRootCache;
+    private _counts;
+    private _callsiteCache;
     isActive(): boolean;
-    private repoRoot;
-    private resolveCallsite;
-    private record;
-    recordEmit(label: string): void;
-    recordRead(label: string): void;
+    private _repoRoot;
+    private _resolveCallsite;
+    private _record;
+    recordEventEmit(label: string): void;
+    recordEventRead(label: string): void;
     recordResourceRead(label: string): void;
     recordResourceWrite(label: string): void;
     recordResourceRegister(label: string): void;
@@ -77,9 +78,9 @@ declare class DispatchTrace {
 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
+ * 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
+ * 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;

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

@@ -1,47 +1,48 @@
 /**
  * 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.
+ * Singleton buffer that captures `(callsite, channel, op, key)` for each ECS
+ * dispatch and each action dispatch, while the environment sets
+ * `VISUAL_INTEL_TRACE` to `1` or to `true`. Compile-time gated by `DEV`, so a
+ * production build dead-code-eliminates every `record()` call. The output is a
+ * deterministic JSON snapshot. An analysis tool outside this repository ingests
+ * it as a runtime channel of evidence, beside a static scan of the same code.
  *
  * Identity model. The engine has no access to source-level binding names
- * (`ContactEvent`, `ConfigRes`) at runtime — `eventKey("Contact")` returns
+ * (`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`).
+ *   - ECS events and 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.
+ * Resolution back to bindings happens in that outside tool, which already
+ * extracts `{ binding, label }` declarations for events and 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-
+ * frames, drop every frame inside the engine itself (any path that matches
+ * `ENGINE_FRAME_MARKERS`), 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.
+ * Activation. `record()` is *unconditional*. It records on every call. Each
+ * caller applies the `isActive()` env-var gate itself (`system_context.ts`,
+ * `facades.ts` and the events plugin facade, all
+ * `if (DEV && dispatchTrace.isActive())`), and `record()` does not. 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). */
+    /** Symbol description (events and resources) or numeric `def.id` (actions). */
     readonly key: string | number;
-    /** Repo-relative POSIX path of the calling file. */
+    /** Repo-relative posix path of the calling file. */
     readonly file: string;
     readonly count: number;
 }
@@ -55,16 +56,16 @@ export interface DispatchTraceSnapshot {
     };
 }
 declare class DispatchTrace {
-    private activeCache;
-    private repoRootCache;
-    private buf;
-    private callsiteCache;
+    private _activeCache;
+    private _repoRootCache;
+    private _counts;
+    private _callsiteCache;
     isActive(): boolean;
-    private repoRoot;
-    private resolveCallsite;
-    private record;
-    recordEmit(label: string): void;
-    recordRead(label: string): void;
+    private _repoRoot;
+    private _resolveCallsite;
+    private _record;
+    recordEventEmit(label: string): void;
+    recordEventRead(label: string): void;
     recordResourceRead(label: string): void;
     recordResourceWrite(label: string): void;
     recordResourceRegister(label: string): void;
@@ -77,9 +78,9 @@ declare class DispatchTrace {
 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
+ * 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
+ * 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;

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

@@ -1 +1 @@
-{"version":3,"file":"dispatch_trace.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/dispatch_trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAOH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,CAAC;AACrE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AACzC,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,eAAe,CAAC;AACvD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElE,MAAM,WAAW,kBAAkB;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE;QAClB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,UAAU,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,kBAAkB,EAAE,CAAC,CAAC;KAC7D,CAAC;CACF;AAID,cAAM,aAAa;IAClB,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,GAAG,CAA6B;IACxC,OAAO,CAAC,aAAa,CAAoC;IAEzD,QAAQ,IAAI,OAAO;IAWnB,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,MAAM;IAOd,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAG/B,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAG/B,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGvC,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGxC,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAG3C,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGzC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGrC,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIvC,QAAQ,IAAI,qBAAqB;IAmCjC,KAAK,IAAI,IAAI;CAMb;AAMD,iBAAS,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOnD;AAED;;;;;;GAMG;AACH,iBAAS,wBAAwB,CAChC,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAChC,MAAM,GAAG,IAAI,CA0Bf;AAeD,eAAO,MAAM,aAAa,EAAE,aAAmC,CAAC;AAIhE,eAAO,MAAM,uBAAuB;;;;CAInC,CAAC"}
+{"version":3,"file":"dispatch_trace.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/dispatch_trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAOH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,CAAC;AACrE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AACzC,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,eAAe,CAAC;AACvD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElE,MAAM,WAAW,kBAAkB;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE;QAClB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,UAAU,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,kBAAkB,EAAE,CAAC,CAAC;KAC7D,CAAC;CACF;AAcD,cAAM,aAAa;IAClB,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,cAAc,CAAoC;IAE1D,QAAQ,IAAI,OAAO;IAWnB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,OAAO;IAOf,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGpC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGpC,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGvC,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGxC,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAG3C,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGzC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGrC,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIvC,QAAQ,IAAI,qBAAqB;IAmCjC,KAAK,IAAI,IAAI;CAMb;AAMD,iBAAS,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOnD;AAED;;;;;;GAMG;AACH,iBAAS,wBAAwB,CAChC,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAChC,MAAM,GAAG,IAAI,CA0Bf;AAeD,eAAO,MAAM,aAAa,EAAE,aAAmC,CAAC;AAIhE,eAAO,MAAM,uBAAuB;;;;CAInC,CAAC"}