@oasys/oecs 0.5.4 → 0.6.0

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

@@ -1,62 +1,60 @@
-import { ArchetypeView } from './archetype.cjs';
-import { ComponentHandle } from './component.cjs';
+import { ArchetypeView } from './archetype_types.cjs';
+import { ChangeFeed } from './change_feed.cjs';
 import { EntityID } from './entity.cjs';
 import { FrameTraceSink } from './frame_trace.cjs';
-import { SystemContext } from './query.cjs';
-import { StructuralObserverEvents } from './store.cjs';
+import { SystemContext } from './system_context.cjs';
 import { SystemAccessDeclaration, SystemDescriptor } from './system.cjs';
-/** What the observer registry needs from `Store` — the typed seam replacing
- * bare underscore-convention reach-through. `Store` implements this; the
+/** What the observer registry needs from `Store`: the change feed every
+ * consumer shares, plus the dev-only trace sink. `Store` implements this. The
  * registry holds only this view, so the compiler bounds what observer dispatch
- * can touch. Underscore names are kept so `Store`'s members stay one
- * declaration (they read as "internal" at every other call site). */
-export interface ObserverHost {
-    /** Current change tick — read for onSet baselines. */
-    readonly _tick: number;
-    /** Dev-only frame-trace sink (`null` when unset; always null in prod). */
-    readonly _trace: FrameTraceSink | null;
-    /** Sync a component's observation flags (add/remove/disable/enable/dirty). */
-    _configureComponentObservation(cid: number, hasAdd: boolean, hasRem: boolean, hasDisable: boolean, hasEnable: boolean, trackDirty: boolean): void;
-    /** Drain the per-entity onSet dirty list for `cid` (clears marks). */
-    _takeDirty(cid: number): EntityID[];
-    /** Visit archetypes whose `cid` column changed since `baseline`, in
-     * canonical (creation-id) order. */
-    _forEachChangedArchetype(cid: number, baseline: number, cb: (arch: ArchetypeView) => void): void;
-    /** Every live entity currently holding `cid` (dispose-on-disable sweep). */
-    _collectEntitiesWithComponent(cid: number): EntityID[];
-    isAlive(id: EntityID): boolean;
-    isDisabled(id: EntityID): boolean;
-    hasComponent(entityId: EntityID, def: ComponentHandle): boolean;
+ * can touch, and the registry is one consumer of the feed among others. */
+export interface ObserverHost extends ChangeFeed {
+    /** Dev-only frame-trace sink (`null` when unset, always null in prod). */
+    readonly trace: FrameTraceSink | null;
 }
-/** Per-entity observer callback (onAdd / onRemove / onDisable / onEnable, and
+/** What the world calls into an observer registry it did not build.
+ *
+ * `ECS.update` runs `dispatchSet` at the tick-tail detection point, through
+ * the settle hook the install pushed. A `DEV` build reads `descriptors` once
+ * per frame trace. Both are cold. The structural dispatch does not appear
+ * here: the plugin subscribes to it through the change feed. */
+export interface ObserverHooks {
+    /** The synthesized descriptor of each registered observer, for the access
+     * check and the frame trace. */
+    descriptors(): SystemDescriptor[];
+    /** Fire the `onSet` observers for the change tick `run`. */
+    dispatchSet(run: number): void;
+}
+/** Per-entity observer callback (onAdd, onRemove, onDisable and onEnable, and
  * per-entity onSet). */
 export type ObserverFn = (entityId: EntityID, ctx: SystemContext) => void;
-/** Archetype-granular onSet callback — fires once per changed archetype-column;
- * the consumer iterates `arch.entityCount` rows itself. */
+/** Archetype-granular onSet callback, fires once per changed archetype-column.
+ * The consumer iterates `arch.entityCount` rows itself. */
 export type ArchetypeObserverFn = (arch: ArchetypeView, ctx: SystemContext) => void;
 /** Fields common to every observer registration. `access` drives both the
- * dev-mode `accessCheck` and the access-topological firing order; it is merged
+ * dev-mode `accessCheck` and the access-topological firing order. It is merged
  * over an all-empty declaration, so a caller spells out only what it touches. */
 interface ObserverConfigBase {
     onAdd?: ObserverFn;
     onRemove?: ObserverFn;
-    /** Fires when an entity carrying this component is *disabled* — at the
+    /** Fires when an entity carrying this component is *disabled*, at the
      * deferred toggle drain, once per net transition. Mirrors `onRemove`:
      * a disable is a soft remove of the whole mask from default queries. An immediate
      * host-side `ecs.disable()` does not fire (like immediate `addComponent`). */
     onDisable?: ObserverFn;
     /** Fires when an entity carrying this component is *enabled*, symmetric
-     * with `onDisable` / `onAdd`. */
+     * with `onDisable` and `onAdd`. */
     onEnable?: ObserverFn;
-    /** Access surface the callbacks touch (reads / writes / spawns / …). Partial:
+    /** Access surface the callbacks touch (reads, writes, spawns and the rest). Partial:
      * merged over `_INTERNAL_EMPTY_ACCESS`. Undeclared access throws in `DEV`. */
     access?: Partial<SystemAccessDeclaration>;
-    /** flecs-style replay of current matches on registration (onAdd only — seeds the
-     * *enabled* members; a disabled entity is simply absent, matching default-query
-     * semantics), for order-independence of register-vs-spawn. */
+    /** flecs-style replay of current matches on registration, so the order of
+     * register and spawn does not matter. `onAdd` only, and it seeds the
+     * *enabled* members. A disabled entity is absent, which matches the
+     * default-query semantics. */
     yieldExisting?: boolean;
     /** Diagnostic label for this observer, surfaced by the frame-trace seam
-     * as the `observer_fired.observer` field — the same role a system's
+     * as the `observer_fired.observer` field, the same role a system's
      * `name` plays. Optional and observe-only: it never touches `stateHash` or
      * dispatch. Defaults to `observer(<component debug name>)` when the component
      * was registered with a name, else `observer(<cid>)`. */
@@ -64,7 +62,7 @@ interface ObserverConfigBase {
 }
 /** Per-entity onSet: `onSet(eid, ctx)` fires once per changed entity, drained
  * from the opt-in per-row dirty list (registering this enables dirty tracking
- * for the component — the dirty list + dedup bit). */
+ * for the component, the dirty list + dedup bit). */
 export interface EntitySetObserverConfig extends ObserverConfigBase {
     onSet: ObserverFn;
     granularity: "entity";
@@ -76,98 +74,19 @@ export interface ArchetypeSetObserverConfig extends ObserverConfigBase {
     onSet: ArchetypeObserverFn;
     granularity?: "archetype";
 }
-/** Structural-only observer — no onSet. */
+/** Structural-only observer, no onSet. */
 export interface StructuralObserverConfig extends ObserverConfigBase {
     onSet?: undefined;
     granularity?: undefined;
 }
 export type ObserverConfig = StructuralObserverConfig | EntitySetObserverConfig | ArchetypeSetObserverConfig;
+/** Handle returned by `ecs.observe(...)`. `dispose()` unregisters. Safe to
+ * call more than once. */
 export interface ObserverHandle {
     dispose(): void;
-    /** `using h = ecs.observe(C, {...})` — explicit-resource-management sugar
+    /** `using h = ecs.observe(C, {...})`, explicit-resource-management sugar
      * over {@link dispose} (TC39 `Symbol.dispose`). */
     [Symbol.dispose](): void;
 }
-/**
- * Registry of component observers. Owned by `ECS`; the `Store` calls back into
- * `dispatchStructural` between fixed-point rounds during `flushStructural`,
- * and `ECS.update` calls `dispatchSet` at the post-update detection point.
- */
-export declare class ObserverRegistry {
-    private readonly store;
-    private readonly ctx;
-    private readonly entries;
-    /** ComponentID → its observers (structural + onSet). */
-    private readonly byCid;
-    /** Cached access-topological order; invalidated on register / dispose. */
-    private _topo;
-    private readonly _addBuckets;
-    private readonly _remBuckets;
-    private readonly _disBuckets;
-    private readonly _enaBuckets;
-    private readonly _radixOut;
-    private readonly _radixC0;
-    private readonly _radixC1;
-    private readonly _setDrainCache;
-    constructor(store: ObserverHost, ctx: SystemContext);
-    get count(): number;
-    /** The synthesized `SystemDescriptor`s of every registered observer, in
-     * registration order (`dispose()` splices entries out, so none are stale).
-     * Fed into the `startup()` archetype-prewarm closure so an observer's declared
-     * `spawns` / `transitions` create their target archetypes eagerly, exactly as a
-     * system's do. Without this an observer-spawned/-transitioned archetype
-     * first-touches lazily mid-tick — the one asymmetry left in the otherwise
-     * uniform "no lazy archetypes" prewarm. */
-    descriptors(): SystemDescriptor[];
-    register(def: ComponentHandle, config: ObserverConfig): ObserverHandle;
-    private _dispose;
-    /** Recompute the component's hot-path observation flags from its live
-     * observers and push them to the store (which owns the flags + fast-path
-     * counters). */
-    private _reconfigureComponent;
-    private getTopo;
-    /**
-     * Fire onAdd / onRemove / onDisable / onEnable for one fixed-point round's
-     * effective events, in canonical order: access-topological across observers,
-     * entity-id order (radix) within each observer. Called by
-     * `Store.flushStructural` after the batch commits; observer callbacks may
-     * enqueue further structural ops (or toggles) onto the deferred buffers (the
-     * store loops until quiescent).
-     *
-     * The events arrive as flat `(comp, eid)` parallel arrays collected during the
-     * flush; we bucket by component once (O(K)), then walk observers in topo order
-     * so a producer's writes are visible to a consumer (glitch-free). A round
-     * carries either structural (add/rem) OR toggle (dis/ena) events, never both —
-     * toggles drain only once add/remove/destroy are quiescent (`flushStructural`)
-     * — but we bucket all four uniformly; the empty pairs are no-ops. Within an
-     * observer the fire order is remove, add, disable, enable (the "leaving" edges
-     * before the "entering" edges).
-     */
-    dispatchStructural(ev: StructuralObserverEvents): void;
-    /** Radix-sort `eids` by entity index (canonical within-observer order), then
-     * fire `fn` per entity under the observer's access scope. */
-    private _fireEach;
-    private _bucket;
-    private _clearBuckets;
-    /**
-     * Fire onSet observers for the current tick, in canonical order. Per-entity
-     * onSet drains the opt-in dirty list (once per changed entity); archetype-
-     * granular onSet scans the change tick (once per changed archetype-column).
-     * Called by `ECS.update` after all phases, with `tick === store._tick`.
-     */
-    dispatchSet(tick: number): void;
-    private _dispatchSetEntity;
-    private _dispatchSetArch;
-    private _yieldExisting;
-}
-/**
- * O(K) LSD radix sort of entity ids by their 20-bit dense index (two 10-bit
- * passes), in place. This is the canonical within-observer order — *never* a
- * comparator `Array.sort`, which the bench measured as much slower than the
- * entire flush. Distinct live entities have distinct indices,
- * so index order is a total canonical order. `out` is scratch (grown to length);
- * `c0` / `c1` are 1024-entry histograms (reused).
- */
-export declare function radixSortByIndex(eids: number[], out: number[], c0: Int32Array, c1: Int32Array): void;
 export {};
 //# sourceMappingURL=observer.d.ts.map

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

@@ -1,62 +1,60 @@
-import { ArchetypeView } from './archetype.js';
-import { ComponentHandle } from './component.js';
+import { ArchetypeView } from './archetype_types.js';
+import { ChangeFeed } from './change_feed.js';
 import { EntityID } from './entity.js';
 import { FrameTraceSink } from './frame_trace.js';
-import { SystemContext } from './query.js';
-import { StructuralObserverEvents } from './store.js';
+import { SystemContext } from './system_context.js';
 import { SystemAccessDeclaration, SystemDescriptor } from './system.js';
-/** What the observer registry needs from `Store` — the typed seam replacing
- * bare underscore-convention reach-through. `Store` implements this; the
+/** What the observer registry needs from `Store`: the change feed every
+ * consumer shares, plus the dev-only trace sink. `Store` implements this. The
  * registry holds only this view, so the compiler bounds what observer dispatch
- * can touch. Underscore names are kept so `Store`'s members stay one
- * declaration (they read as "internal" at every other call site). */
-export interface ObserverHost {
-    /** Current change tick — read for onSet baselines. */
-    readonly _tick: number;
-    /** Dev-only frame-trace sink (`null` when unset; always null in prod). */
-    readonly _trace: FrameTraceSink | null;
-    /** Sync a component's observation flags (add/remove/disable/enable/dirty). */
-    _configureComponentObservation(cid: number, hasAdd: boolean, hasRem: boolean, hasDisable: boolean, hasEnable: boolean, trackDirty: boolean): void;
-    /** Drain the per-entity onSet dirty list for `cid` (clears marks). */
-    _takeDirty(cid: number): EntityID[];
-    /** Visit archetypes whose `cid` column changed since `baseline`, in
-     * canonical (creation-id) order. */
-    _forEachChangedArchetype(cid: number, baseline: number, cb: (arch: ArchetypeView) => void): void;
-    /** Every live entity currently holding `cid` (dispose-on-disable sweep). */
-    _collectEntitiesWithComponent(cid: number): EntityID[];
-    isAlive(id: EntityID): boolean;
-    isDisabled(id: EntityID): boolean;
-    hasComponent(entityId: EntityID, def: ComponentHandle): boolean;
+ * can touch, and the registry is one consumer of the feed among others. */
+export interface ObserverHost extends ChangeFeed {
+    /** Dev-only frame-trace sink (`null` when unset, always null in prod). */
+    readonly trace: FrameTraceSink | null;
 }
-/** Per-entity observer callback (onAdd / onRemove / onDisable / onEnable, and
+/** What the world calls into an observer registry it did not build.
+ *
+ * `ECS.update` runs `dispatchSet` at the tick-tail detection point, through
+ * the settle hook the install pushed. A `DEV` build reads `descriptors` once
+ * per frame trace. Both are cold. The structural dispatch does not appear
+ * here: the plugin subscribes to it through the change feed. */
+export interface ObserverHooks {
+    /** The synthesized descriptor of each registered observer, for the access
+     * check and the frame trace. */
+    descriptors(): SystemDescriptor[];
+    /** Fire the `onSet` observers for the change tick `run`. */
+    dispatchSet(run: number): void;
+}
+/** Per-entity observer callback (onAdd, onRemove, onDisable and onEnable, and
  * per-entity onSet). */
 export type ObserverFn = (entityId: EntityID, ctx: SystemContext) => void;
-/** Archetype-granular onSet callback — fires once per changed archetype-column;
- * the consumer iterates `arch.entityCount` rows itself. */
+/** Archetype-granular onSet callback, fires once per changed archetype-column.
+ * The consumer iterates `arch.entityCount` rows itself. */
 export type ArchetypeObserverFn = (arch: ArchetypeView, ctx: SystemContext) => void;
 /** Fields common to every observer registration. `access` drives both the
- * dev-mode `accessCheck` and the access-topological firing order; it is merged
+ * dev-mode `accessCheck` and the access-topological firing order. It is merged
  * over an all-empty declaration, so a caller spells out only what it touches. */
 interface ObserverConfigBase {
     onAdd?: ObserverFn;
     onRemove?: ObserverFn;
-    /** Fires when an entity carrying this component is *disabled* — at the
+    /** Fires when an entity carrying this component is *disabled*, at the
      * deferred toggle drain, once per net transition. Mirrors `onRemove`:
      * a disable is a soft remove of the whole mask from default queries. An immediate
      * host-side `ecs.disable()` does not fire (like immediate `addComponent`). */
     onDisable?: ObserverFn;
     /** Fires when an entity carrying this component is *enabled*, symmetric
-     * with `onDisable` / `onAdd`. */
+     * with `onDisable` and `onAdd`. */
     onEnable?: ObserverFn;
-    /** Access surface the callbacks touch (reads / writes / spawns / …). Partial:
+    /** Access surface the callbacks touch (reads, writes, spawns and the rest). Partial:
      * merged over `_INTERNAL_EMPTY_ACCESS`. Undeclared access throws in `DEV`. */
     access?: Partial<SystemAccessDeclaration>;
-    /** flecs-style replay of current matches on registration (onAdd only — seeds the
-     * *enabled* members; a disabled entity is simply absent, matching default-query
-     * semantics), for order-independence of register-vs-spawn. */
+    /** flecs-style replay of current matches on registration, so the order of
+     * register and spawn does not matter. `onAdd` only, and it seeds the
+     * *enabled* members. A disabled entity is absent, which matches the
+     * default-query semantics. */
     yieldExisting?: boolean;
     /** Diagnostic label for this observer, surfaced by the frame-trace seam
-     * as the `observer_fired.observer` field — the same role a system's
+     * as the `observer_fired.observer` field, the same role a system's
      * `name` plays. Optional and observe-only: it never touches `stateHash` or
      * dispatch. Defaults to `observer(<component debug name>)` when the component
      * was registered with a name, else `observer(<cid>)`. */
@@ -64,7 +62,7 @@ interface ObserverConfigBase {
 }
 /** Per-entity onSet: `onSet(eid, ctx)` fires once per changed entity, drained
  * from the opt-in per-row dirty list (registering this enables dirty tracking
- * for the component — the dirty list + dedup bit). */
+ * for the component, the dirty list + dedup bit). */
 export interface EntitySetObserverConfig extends ObserverConfigBase {
     onSet: ObserverFn;
     granularity: "entity";
@@ -76,98 +74,19 @@ export interface ArchetypeSetObserverConfig extends ObserverConfigBase {
     onSet: ArchetypeObserverFn;
     granularity?: "archetype";
 }
-/** Structural-only observer — no onSet. */
+/** Structural-only observer, no onSet. */
 export interface StructuralObserverConfig extends ObserverConfigBase {
     onSet?: undefined;
     granularity?: undefined;
 }
 export type ObserverConfig = StructuralObserverConfig | EntitySetObserverConfig | ArchetypeSetObserverConfig;
+/** Handle returned by `ecs.observe(...)`. `dispose()` unregisters. Safe to
+ * call more than once. */
 export interface ObserverHandle {
     dispose(): void;
-    /** `using h = ecs.observe(C, {...})` — explicit-resource-management sugar
+    /** `using h = ecs.observe(C, {...})`, explicit-resource-management sugar
      * over {@link dispose} (TC39 `Symbol.dispose`). */
     [Symbol.dispose](): void;
 }
-/**
- * Registry of component observers. Owned by `ECS`; the `Store` calls back into
- * `dispatchStructural` between fixed-point rounds during `flushStructural`,
- * and `ECS.update` calls `dispatchSet` at the post-update detection point.
- */
-export declare class ObserverRegistry {
-    private readonly store;
-    private readonly ctx;
-    private readonly entries;
-    /** ComponentID → its observers (structural + onSet). */
-    private readonly byCid;
-    /** Cached access-topological order; invalidated on register / dispose. */
-    private _topo;
-    private readonly _addBuckets;
-    private readonly _remBuckets;
-    private readonly _disBuckets;
-    private readonly _enaBuckets;
-    private readonly _radixOut;
-    private readonly _radixC0;
-    private readonly _radixC1;
-    private readonly _setDrainCache;
-    constructor(store: ObserverHost, ctx: SystemContext);
-    get count(): number;
-    /** The synthesized `SystemDescriptor`s of every registered observer, in
-     * registration order (`dispose()` splices entries out, so none are stale).
-     * Fed into the `startup()` archetype-prewarm closure so an observer's declared
-     * `spawns` / `transitions` create their target archetypes eagerly, exactly as a
-     * system's do. Without this an observer-spawned/-transitioned archetype
-     * first-touches lazily mid-tick — the one asymmetry left in the otherwise
-     * uniform "no lazy archetypes" prewarm. */
-    descriptors(): SystemDescriptor[];
-    register(def: ComponentHandle, config: ObserverConfig): ObserverHandle;
-    private _dispose;
-    /** Recompute the component's hot-path observation flags from its live
-     * observers and push them to the store (which owns the flags + fast-path
-     * counters). */
-    private _reconfigureComponent;
-    private getTopo;
-    /**
-     * Fire onAdd / onRemove / onDisable / onEnable for one fixed-point round's
-     * effective events, in canonical order: access-topological across observers,
-     * entity-id order (radix) within each observer. Called by
-     * `Store.flushStructural` after the batch commits; observer callbacks may
-     * enqueue further structural ops (or toggles) onto the deferred buffers (the
-     * store loops until quiescent).
-     *
-     * The events arrive as flat `(comp, eid)` parallel arrays collected during the
-     * flush; we bucket by component once (O(K)), then walk observers in topo order
-     * so a producer's writes are visible to a consumer (glitch-free). A round
-     * carries either structural (add/rem) OR toggle (dis/ena) events, never both —
-     * toggles drain only once add/remove/destroy are quiescent (`flushStructural`)
-     * — but we bucket all four uniformly; the empty pairs are no-ops. Within an
-     * observer the fire order is remove, add, disable, enable (the "leaving" edges
-     * before the "entering" edges).
-     */
-    dispatchStructural(ev: StructuralObserverEvents): void;
-    /** Radix-sort `eids` by entity index (canonical within-observer order), then
-     * fire `fn` per entity under the observer's access scope. */
-    private _fireEach;
-    private _bucket;
-    private _clearBuckets;
-    /**
-     * Fire onSet observers for the current tick, in canonical order. Per-entity
-     * onSet drains the opt-in dirty list (once per changed entity); archetype-
-     * granular onSet scans the change tick (once per changed archetype-column).
-     * Called by `ECS.update` after all phases, with `tick === store._tick`.
-     */
-    dispatchSet(tick: number): void;
-    private _dispatchSetEntity;
-    private _dispatchSetArch;
-    private _yieldExisting;
-}
-/**
- * O(K) LSD radix sort of entity ids by their 20-bit dense index (two 10-bit
- * passes), in place. This is the canonical within-observer order — *never* a
- * comparator `Array.sort`, which the bench measured as much slower than the
- * entire flush. Distinct live entities have distinct indices,
- * so index order is a total canonical order. `out` is scratch (grown to length);
- * `c0` / `c1` are 1024-entry histograms (reused).
- */
-export declare function radixSortByIndex(eids: number[], out: number[], c0: Int32Array, c1: Int32Array): void;
 export {};
 //# sourceMappingURL=observer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/observer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;KAYK;AAEL,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE1E;;;2EAG2E;AAC3E,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC/C,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;CACtC;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,aAAa;IAC7B;oCACgC;IAChC,WAAW,IAAI,gBAAgB,EAAE,CAAC;IAClC,4DAA4D;IAC5D,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;wBACwB;AACxB,MAAM,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,aAAa,KAAK,IAAI,CAAC;AAC1E;2DAC2D;AAC3D,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,KAAK,IAAI,CAAC;AAEpF;;iFAEiF;AACjF,UAAU,kBAAkB;IAC3B,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB;;;kFAG8E;IAC9E,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB;uCACmC;IACnC,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB;kFAC8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC1C;;;kCAG8B;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;6DAIyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;qDAEqD;AACrD,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IAClE,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,EAAE,QAAQ,CAAC;CACtB;AAED;;iBAEiB;AACjB,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB;IACrE,KAAK,EAAE,mBAAmB,CAAC;IAC3B,WAAW,CAAC,EAAE,WAAW,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;IACnE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,WAAW,CAAC,EAAE,SAAS,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GACvB,wBAAwB,GACxB,uBAAuB,GACvB,0BAA0B,CAAC;AAE9B;0BAC0B;AAC1B,MAAM,WAAW,cAAc;IAC9B,OAAO,IAAI,IAAI,CAAC;IAChB;uDACmD;IACnD,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CACzB"}

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

@@ -0,0 +1,79 @@
+/***
+ * Phase vocabulary. The names a caller uses to point at one slot of the frame.
+ *
+ * This file owns the seven built-in `SCHEDULE` members, the `Phase` handle
+ * `ecs.addPhase` hands back, the loop a phase belongs to, and the two pure
+ * classifiers over either spelling.
+ *
+ * It imports nothing. That is the point, and not an accident. A phase name is
+ * the one piece of schedule vocabulary that `frame_trace.ts` and
+ * `host_commands.ts` need, and reaching it through `schedule.ts` dragged the
+ * whole schedule, the system descriptor and the run condition behind it. With
+ * no import here the module sits outside every type cycle in `src`, and
+ * `import_graph.test.ts` records the smaller tangle.
+ *
+ * It refuses state. `PhaseNode`, the object behind a handle, stays in
+ * `schedule.ts` beside the drive loops that read its `plan` field.
+ ***/
+export declare enum SCHEDULE {
+    PRE_STARTUP = "PRE_STARTUP",
+    STARTUP = "STARTUP",
+    POST_STARTUP = "POST_STARTUP",
+    FIXED_UPDATE = "FIXED_UPDATE",
+    PRE_UPDATE = "PRE_UPDATE",
+    UPDATE = "UPDATE",
+    POST_UPDATE = "POST_UPDATE"
+}
+/** Which drive runs a phase.
+ *
+ * `startup` runs once, from `ecs.startup()`. `fixed` runs once per fixed step,
+ * inside the accumulator loop. `update` runs once per `ecs.update(dt)`. A
+ * phase belongs to one loop for its life, because the loop decides the delta
+ * time it receives and how often it runs. */
+export type PhaseLoop = "startup" | "fixed" | "update";
+/**
+ * An opaque handle for one slot in the schedule, returned by `ecs.addPhase`.
+ *
+ * A phase is identified by **object identity**, not by name, exactly like a
+ * `SystemSet`. Two `addPhase` calls with the same name are two phases. The
+ * handle belongs to the world that made it, so passing one to another world's
+ * `addSystems` is a fault and not silent cross-world scheduling.
+ *
+ * The seven built-ins have no handle. `SCHEDULE.UPDATE` names one directly,
+ * and every place that takes a `SchedulePhase` takes either spelling. A string
+ * enum member is already a string, so the built-in needs no wrapper object,
+ * and a plugin author reads `after: [SCHEDULE.PRE_UPDATE]` without an import
+ * of a handle table.
+ */
+export interface Phase {
+    readonly name: string;
+    readonly loop: PhaseLoop;
+}
+/** Where a new phase sits. `before` and `after` order it against other phases
+ * of the same loop, and a target in another loop is dropped. A phase with
+ * neither runs after every phase declared before it, so an unordered plugin
+ * phase lands at the tail of its loop. */
+export interface PhaseConfig {
+    readonly loop: PhaseLoop;
+    readonly before?: readonly SchedulePhase[];
+    readonly after?: readonly SchedulePhase[];
+}
+/** Either spelling of a phase: a built-in `SCHEDULE` member, or the handle
+ * `addPhase` returned. */
+export type SchedulePhase = SCHEDULE | Phase;
+/** The name a trace event carries for a phase. A built-in spells its `SCHEDULE`
+ * member. A phase from `addPhase` spells the name it was given, so the set of
+ * values is open and a consumer switching on it needs a default arm. */
+export type PhaseName = SCHEDULE | (string & {});
+/** The loop that drives either spelling of a phase.
+ *
+ * A handle from `addPhase` carries its loop. A built-in is one of seven, and
+ * its loop is fixed at construction. Pure and cold, so a caller outside the
+ * schedule classifies a phase without holding the world. `installHostCommandSeam`
+ * is that caller. It refuses a recorder on a fixed-loop phase, and `addPhase`
+ * can put a phase of any name in that loop. */
+export declare function phaseLoopOf(phase: SchedulePhase): PhaseLoop;
+/** The name either spelling of a phase carries, for a diagnostic and for a
+ * system name. Pure and cold. */
+export declare function phaseNameOf(phase: SchedulePhase): PhaseName;
+//# sourceMappingURL=phase.d.ts.map

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

@@ -0,0 +1,79 @@
+/***
+ * Phase vocabulary. The names a caller uses to point at one slot of the frame.
+ *
+ * This file owns the seven built-in `SCHEDULE` members, the `Phase` handle
+ * `ecs.addPhase` hands back, the loop a phase belongs to, and the two pure
+ * classifiers over either spelling.
+ *
+ * It imports nothing. That is the point, and not an accident. A phase name is
+ * the one piece of schedule vocabulary that `frame_trace.ts` and
+ * `host_commands.ts` need, and reaching it through `schedule.ts` dragged the
+ * whole schedule, the system descriptor and the run condition behind it. With
+ * no import here the module sits outside every type cycle in `src`, and
+ * `import_graph.test.ts` records the smaller tangle.
+ *
+ * It refuses state. `PhaseNode`, the object behind a handle, stays in
+ * `schedule.ts` beside the drive loops that read its `plan` field.
+ ***/
+export declare enum SCHEDULE {
+    PRE_STARTUP = "PRE_STARTUP",
+    STARTUP = "STARTUP",
+    POST_STARTUP = "POST_STARTUP",
+    FIXED_UPDATE = "FIXED_UPDATE",
+    PRE_UPDATE = "PRE_UPDATE",
+    UPDATE = "UPDATE",
+    POST_UPDATE = "POST_UPDATE"
+}
+/** Which drive runs a phase.
+ *
+ * `startup` runs once, from `ecs.startup()`. `fixed` runs once per fixed step,
+ * inside the accumulator loop. `update` runs once per `ecs.update(dt)`. A
+ * phase belongs to one loop for its life, because the loop decides the delta
+ * time it receives and how often it runs. */
+export type PhaseLoop = "startup" | "fixed" | "update";
+/**
+ * An opaque handle for one slot in the schedule, returned by `ecs.addPhase`.
+ *
+ * A phase is identified by **object identity**, not by name, exactly like a
+ * `SystemSet`. Two `addPhase` calls with the same name are two phases. The
+ * handle belongs to the world that made it, so passing one to another world's
+ * `addSystems` is a fault and not silent cross-world scheduling.
+ *
+ * The seven built-ins have no handle. `SCHEDULE.UPDATE` names one directly,
+ * and every place that takes a `SchedulePhase` takes either spelling. A string
+ * enum member is already a string, so the built-in needs no wrapper object,
+ * and a plugin author reads `after: [SCHEDULE.PRE_UPDATE]` without an import
+ * of a handle table.
+ */
+export interface Phase {
+    readonly name: string;
+    readonly loop: PhaseLoop;
+}
+/** Where a new phase sits. `before` and `after` order it against other phases
+ * of the same loop, and a target in another loop is dropped. A phase with
+ * neither runs after every phase declared before it, so an unordered plugin
+ * phase lands at the tail of its loop. */
+export interface PhaseConfig {
+    readonly loop: PhaseLoop;
+    readonly before?: readonly SchedulePhase[];
+    readonly after?: readonly SchedulePhase[];
+}
+/** Either spelling of a phase: a built-in `SCHEDULE` member, or the handle
+ * `addPhase` returned. */
+export type SchedulePhase = SCHEDULE | Phase;
+/** The name a trace event carries for a phase. A built-in spells its `SCHEDULE`
+ * member. A phase from `addPhase` spells the name it was given, so the set of
+ * values is open and a consumer switching on it needs a default arm. */
+export type PhaseName = SCHEDULE | (string & {});
+/** The loop that drives either spelling of a phase.
+ *
+ * A handle from `addPhase` carries its loop. A built-in is one of seven, and
+ * its loop is fixed at construction. Pure and cold, so a caller outside the
+ * schedule classifies a phase without holding the world. `installHostCommandSeam`
+ * is that caller. It refuses a recorder on a fixed-loop phase, and `addPhase`
+ * can put a phase of any name in that loop. */
+export declare function phaseLoopOf(phase: SchedulePhase): PhaseLoop;
+/** The name either spelling of a phase carries, for a diagnostic and for a
+ * system name. Pure and cold. */
+export declare function phaseNameOf(phase: SchedulePhase): PhaseName;
+//# sourceMappingURL=phase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"phase.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;KAgBK;AAEL,oBAAY,QAAQ;IACnB,WAAW,gBAAgB;IAC3B,OAAO,YAAY;IACnB,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,UAAU,eAAe;IACzB,MAAM,WAAW;IACjB,WAAW,gBAAgB;CAC3B;AAED;;;;;6CAK6C;AAC7C,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,KAAK;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CACzB;AAED;;;0CAG0C;AAC1C,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CAC1C;AAED;0BAC0B;AAC1B,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE7C;;wEAEwE;AACxE,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEjD;;;;;;+CAM+C;AAC/C,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAc3D;AAED;iCACiC;AACjC,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAE3D"}