@oasys/oecs 0.3.1 → 0.5.0

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

@@ -0,0 +1,85 @@
+import { ArchetypeViews } from '../store/index.cjs';
+/** Magic for the combined world-snapshot frame (`"WRS0"` little-endian). Distinct
+ * from the SAB `STORE_MAGIC` so a bare dense snapshot fed to `restoreInto` is
+ * rejected with a clear error instead of being mis-parsed as a combined frame. */
+export declare const WORLD_SNAPSHOT_MAGIC = 810766935;
+/** Combined-frame format version. Bumped if the section framing or host-state
+ * layout changes. Independent of `SIM_ABI_VERSION` (which gates the dense bytes). */
+export declare const ECS_SNAPSHOT_VERSION = 1;
+/** Thrown by `Store.restoreInto` (and the helpers here) when a combined snapshot
+ * is malformed, carries the wrong magic/version, or targets a world whose
+ * archetype/component registration doesn't match the snapshot. Mirrors
+ * `StoreRestoreError` / `SparseRestoreError` so callers see one error class per
+ * restore failure mode. */
+export declare class ECSRestoreError extends Error {
+    constructor(message: string);
+}
+/** Per-archetype host-side row bookkeeping the SAB doesn't carry authoritatively. */
+export interface ArchetypeRowState {
+    readonly archetypeId: number;
+    /** Total live rows (enabled + disabled). */
+    readonly length: number;
+    /** Enabled-row partition boundary (#577): rows `[0, enabledCount)` enabled. */
+    readonly enabledCount: number;
+}
+/** The host-side state a snapshot captures alongside the dense + sparse bytes. */
+export interface HostState {
+    /** World tick at snapshot time (`Store._tick`). */
+    readonly tick: number;
+    /** Entity-index high-water (count of slots ever issued). Also mirrored in the
+     * SAB region's `length` header; carried here for a cross-check on restore. */
+    readonly entityHighWater: number;
+    /** Live entity count. */
+    readonly entityAliveCount: number;
+    /** Recycle free-list in live order (LIFO: the last element is the next slot
+     * `createEntity` hands out). */
+    readonly freeIndices: readonly number[];
+    /** Per-archetype row state, one entry per SAB-backed archetype. */
+    readonly archetypeRows: readonly ArchetypeRowState[];
+}
+/** Serialize host-state to a self-contained little-endian byte buffer. Layout:
+ *
+ *   [u32 tick][u32 highWater][u32 alive_count]
+ *   [u32 freeCount][u32 free_index × freeCount]
+ *   [u32 archCount][(u32 id, u32 length, u32 enabled_count) × archCount]
+ */
+export declare function serializeHostState(hs: HostState): Uint8Array;
+/** Parse host-state bytes produced by `serializeHostState`. Throws
+ * `ECSRestoreError` on truncation or a trailing-byte (non-canonical) buffer. */
+export declare function parseHostState(bytes: Uint8Array): HostState;
+/** Assemble the combined world-snapshot frame from its three sections. Layout:
+ *
+ *   [u32 magic][u32 version][u32 denseLen][u32 sparseLen][u32 hostLen]
+ *   [dense][sparse][host]
+ */
+export declare function frameWorldSnapshot(dense: Uint8Array, sparse: Uint8Array, host: Uint8Array): Uint8Array;
+/** The three sections of a combined frame, as zero-copy subviews over `bytes`. */
+export interface WorldSnapshotSections {
+    readonly dense: Uint8Array;
+    readonly sparse: Uint8Array;
+    readonly host: Uint8Array;
+}
+/** Split a combined frame back into its sections. Validates magic, version, and
+ * an exact (no trailing bytes) frame; throws `ECSRestoreError` otherwise. */
+export declare function unframeWorldSnapshot(bytes: Uint8Array): WorldSnapshotSections;
+/**
+ * Fail-closed registration guard, read **directly from the snapshot's dense
+ * bytes** so it can run BEFORE the dense backing is touched. `restoreInto`
+ * builds the restored store through the live world's in-place allocator
+ * (ADR-0008), which reuses the live backing buffer — so validating a
+ * *materialised* `ColumnStore` would already have overwritten live column data
+ * (the buffer is overwritten inside `restoreColumnStore`, before any post-build
+ * check could run). Parsing the descriptors off the raw `dense` `Uint8Array`
+ * keeps the check non-mutating, so a mismatch leaves the live world untouched.
+ *
+ * Asserts: the dense section's SAB magic + ABI, that its archetype set +
+ * per-archetype `componentMask` + per-column `(componentId, fieldId, typeTag)`
+ * match the live store's exactly (so every live `Archetype.refreshViews` finds
+ * its region and no snapshot archetype is orphaned), and that the entity-index
+ * capacity matches (the region is sized once at construction). The archetype
+ * graph is rebuilt from registration code, not the snapshot (mirroring
+ * `restoreSparse`'s "registered in the same order" contract). Throws
+ * `ECSRestoreError` on any mismatch / malformed section.
+ */
+export declare function assertDenseLayoutMatchesLive(dense: Uint8Array, live: ReadonlyMap<number, ArchetypeViews>, liveEntityIndexCapacity: number): void;
+//# sourceMappingURL=resume.d.ts.map

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

@@ -0,0 +1,85 @@
+import { ArchetypeViews } from '../store/index.js';
+/** Magic for the combined world-snapshot frame (`"WRS0"` little-endian). Distinct
+ * from the SAB `STORE_MAGIC` so a bare dense snapshot fed to `restoreInto` is
+ * rejected with a clear error instead of being mis-parsed as a combined frame. */
+export declare const WORLD_SNAPSHOT_MAGIC = 810766935;
+/** Combined-frame format version. Bumped if the section framing or host-state
+ * layout changes. Independent of `SIM_ABI_VERSION` (which gates the dense bytes). */
+export declare const ECS_SNAPSHOT_VERSION = 1;
+/** Thrown by `Store.restoreInto` (and the helpers here) when a combined snapshot
+ * is malformed, carries the wrong magic/version, or targets a world whose
+ * archetype/component registration doesn't match the snapshot. Mirrors
+ * `StoreRestoreError` / `SparseRestoreError` so callers see one error class per
+ * restore failure mode. */
+export declare class ECSRestoreError extends Error {
+    constructor(message: string);
+}
+/** Per-archetype host-side row bookkeeping the SAB doesn't carry authoritatively. */
+export interface ArchetypeRowState {
+    readonly archetypeId: number;
+    /** Total live rows (enabled + disabled). */
+    readonly length: number;
+    /** Enabled-row partition boundary (#577): rows `[0, enabledCount)` enabled. */
+    readonly enabledCount: number;
+}
+/** The host-side state a snapshot captures alongside the dense + sparse bytes. */
+export interface HostState {
+    /** World tick at snapshot time (`Store._tick`). */
+    readonly tick: number;
+    /** Entity-index high-water (count of slots ever issued). Also mirrored in the
+     * SAB region's `length` header; carried here for a cross-check on restore. */
+    readonly entityHighWater: number;
+    /** Live entity count. */
+    readonly entityAliveCount: number;
+    /** Recycle free-list in live order (LIFO: the last element is the next slot
+     * `createEntity` hands out). */
+    readonly freeIndices: readonly number[];
+    /** Per-archetype row state, one entry per SAB-backed archetype. */
+    readonly archetypeRows: readonly ArchetypeRowState[];
+}
+/** Serialize host-state to a self-contained little-endian byte buffer. Layout:
+ *
+ *   [u32 tick][u32 highWater][u32 alive_count]
+ *   [u32 freeCount][u32 free_index × freeCount]
+ *   [u32 archCount][(u32 id, u32 length, u32 enabled_count) × archCount]
+ */
+export declare function serializeHostState(hs: HostState): Uint8Array;
+/** Parse host-state bytes produced by `serializeHostState`. Throws
+ * `ECSRestoreError` on truncation or a trailing-byte (non-canonical) buffer. */
+export declare function parseHostState(bytes: Uint8Array): HostState;
+/** Assemble the combined world-snapshot frame from its three sections. Layout:
+ *
+ *   [u32 magic][u32 version][u32 denseLen][u32 sparseLen][u32 hostLen]
+ *   [dense][sparse][host]
+ */
+export declare function frameWorldSnapshot(dense: Uint8Array, sparse: Uint8Array, host: Uint8Array): Uint8Array;
+/** The three sections of a combined frame, as zero-copy subviews over `bytes`. */
+export interface WorldSnapshotSections {
+    readonly dense: Uint8Array;
+    readonly sparse: Uint8Array;
+    readonly host: Uint8Array;
+}
+/** Split a combined frame back into its sections. Validates magic, version, and
+ * an exact (no trailing bytes) frame; throws `ECSRestoreError` otherwise. */
+export declare function unframeWorldSnapshot(bytes: Uint8Array): WorldSnapshotSections;
+/**
+ * Fail-closed registration guard, read **directly from the snapshot's dense
+ * bytes** so it can run BEFORE the dense backing is touched. `restoreInto`
+ * builds the restored store through the live world's in-place allocator
+ * (ADR-0008), which reuses the live backing buffer — so validating a
+ * *materialised* `ColumnStore` would already have overwritten live column data
+ * (the buffer is overwritten inside `restoreColumnStore`, before any post-build
+ * check could run). Parsing the descriptors off the raw `dense` `Uint8Array`
+ * keeps the check non-mutating, so a mismatch leaves the live world untouched.
+ *
+ * Asserts: the dense section's SAB magic + ABI, that its archetype set +
+ * per-archetype `componentMask` + per-column `(componentId, fieldId, typeTag)`
+ * match the live store's exactly (so every live `Archetype.refreshViews` finds
+ * its region and no snapshot archetype is orphaned), and that the entity-index
+ * capacity matches (the region is sized once at construction). The archetype
+ * graph is rebuilt from registration code, not the snapshot (mirroring
+ * `restoreSparse`'s "registered in the same order" contract). Throws
+ * `ECSRestoreError` on any mismatch / malformed section.
+ */
+export declare function assertDenseLayoutMatchesLive(dense: Uint8Array, live: ReadonlyMap<number, ArchetypeViews>, liveEntityIndexCapacity: number): void;
+//# sourceMappingURL=resume.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resume.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/resume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAUN,KAAK,cAAc,EACnB,MAAM,UAAU,CAAC;AAElB;;kFAEkF;AAClF,eAAO,MAAM,oBAAoB,YAAa,CAAC;AAE/C;qFACqF;AACrF,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC;;;;2BAI2B;AAC3B,qBAAa,eAAgB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI3B;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAED,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACzB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;kFAC8E;IAC9E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,yBAAyB;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;oCACgC;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACrD;AAID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,GAAG,UAAU,CAwB5D;AAED;gFACgF;AAChF,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAqC3D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,GACd,UAAU,CAaZ;AAED,kFAAkF;AAClF,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC1B;AAED;6EAC6E;AAC7E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,qBAAqB,CAuC7E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,4BAA4B,CAC3C,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,EACzC,uBAAuB,EAAE,MAAM,GAC7B,IAAI,CAoGN"}

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

@@ -0,0 +1,81 @@
+import { ComponentDef } from './component.cjs';
+import { ResourceKey } from './resource.cjs';
+import { Query } from './query.cjs';
+/**
+ * The read-only slice of `SystemContext` a run condition is handed. Deliberately
+ * narrow — a condition can read the ECS tick and resources, but has no path to
+ * mutate the world or read component columns directly (component reads go
+ * through a captured `Query`). `SystemContext` structurally satisfies this, so
+ * the schedule passes the live context unchanged.
+ */
+export interface ConditionContext {
+    /** Current ECS tick — the deterministic clock built-ins key off. */
+    readonly ecsTick: number;
+    /** Read a resource value (checked against `resourceReads` in `DEV`). */
+    resource<T>(key: ResourceKey<T>): T;
+    /** Membership probe for a resource — unchecked, mirrors `hasComponent`. */
+    hasResource<T>(key: ResourceKey<T>): boolean;
+}
+/**
+ * A per-tick gate. `evaluate` returns `true` to run the gated system(s), `false`
+ * to skip them this tick. `reads` / `resourceReads` declare the predicate's
+ * read surface for `accessCheck` (dev) and the future parallel scheduler's
+ * read-edge graph; both are optional (absent reads as empty).
+ */
+export interface RunCondition {
+    /** Human-readable label, surfaced in dev access-violation diagnostics. */
+    readonly name: string;
+    /** Pure, deterministic predicate. See the two hard rules in the file header. */
+    readonly evaluate: (ctx: ConditionContext) => boolean;
+    /** Components the predicate reads (via a captured query). Forward-looking
+     *  metadata — `ConditionContext` exposes no direct column read, so this is
+     *  not runtime-checkable today, but it is the read-edge a parallel scheduler
+     *  will consume. */
+    readonly reads?: readonly ComponentDef[];
+    /** Resources the predicate reads. Validated at runtime in `DEV` when the
+     *  condition evaluates inside `accessCheck.enterCondition`. */
+    readonly resourceReads?: readonly ResourceKey<any>[];
+}
+/**
+ * Run the gated system(s) only while a resource equals `expected` (strict `===`,
+ * so reference identity for objects). The canonical "feature flag / game phase"
+ * gate — flip `ecs.resources.set(key, …)` and the whole group toggles.
+ */
+export declare function runIfResourceEq<T>(key: ResourceKey<T>, expected: T): RunCondition;
+/**
+ * Run the gated system(s) once every `n` ticks — on ticks congruent to `offset`
+ * mod `n`. Keyed off the deterministic ECS tick, so it carries no private
+ * state and replays bit-identically. `offset` is a **phase shift taken mod `n`**
+ * (default `0` ⇒ fires on tick 0, n, 2n, …; `offset` and `offset + n` are the
+ * same phase, and a negative offset wraps), normalized once here into `[0, n)`.
+ * `n` must be a positive integer and `offset` an integer.
+ *
+ * The normalization isn't cosmetic: `(ecsTick - offset) % n` with a raw
+ * `offset ≥ n` (or negative) leans on JS's signed `%` yielding `-0` for a
+ * negative multiple (and `-0 === 0`) to stay congruent — correct, but load-
+ * bearing on a quirk. Folding `offset` into `[0, n)` up front makes the phase
+ * explicit: the per-tick dividend `ecsTick - phase` may still be negative
+ * (when `ecsTick < phase`), but with `phase ∈ [0, n)` it is never a *negative
+ * multiple* of `n` — it lands in `[-(n-1), -1]`, which holds no multiple of `n`
+ * — so `%` never produces `-0` and the check needs no signed-zero reliance.
+ */
+export declare function runEveryNTicks(n: number, offset?: number): RunCondition;
+/**
+ * Run the gated system(s) only when a query matches at least one (enabled)
+ * entity — flecs `runIf` over a query. The query is captured at config time;
+ * its component defs are declared as `reads`. `count()` is a membership sum over
+ * matching archetypes (no column reads), so it trips no `accessCheck` read.
+ *
+ * The query must be **dense-only**: `entityCount` asserts this in `DEV`
+ * (`_assertDenseOnly`), so pass a plain `ecs.query(...)` — a query carrying
+ * `.optional(...)` or sparse terms throws. Gate on sparse membership with a
+ * custom predicate over `forEachEntity` instead.
+ */
+export declare function runIfAnyMatch(query: Query<readonly ComponentDef[]>): RunCondition;
+/** Invert a condition: run exactly when `cond` would skip. */
+export declare function not(cond: RunCondition): RunCondition;
+/** Run only when EVERY condition passes (`&&`, short-circuit). */
+export declare function allOf(...conds: RunCondition[]): RunCondition;
+/** Run when ANY condition passes (`||`, short-circuit). */
+export declare function anyOf(...conds: RunCondition[]): RunCondition;
+//# sourceMappingURL=run_condition.d.ts.map

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

@@ -0,0 +1,81 @@
+import { ComponentDef } from './component.js';
+import { ResourceKey } from './resource.js';
+import { Query } from './query.js';
+/**
+ * The read-only slice of `SystemContext` a run condition is handed. Deliberately
+ * narrow — a condition can read the ECS tick and resources, but has no path to
+ * mutate the world or read component columns directly (component reads go
+ * through a captured `Query`). `SystemContext` structurally satisfies this, so
+ * the schedule passes the live context unchanged.
+ */
+export interface ConditionContext {
+    /** Current ECS tick — the deterministic clock built-ins key off. */
+    readonly ecsTick: number;
+    /** Read a resource value (checked against `resourceReads` in `DEV`). */
+    resource<T>(key: ResourceKey<T>): T;
+    /** Membership probe for a resource — unchecked, mirrors `hasComponent`. */
+    hasResource<T>(key: ResourceKey<T>): boolean;
+}
+/**
+ * A per-tick gate. `evaluate` returns `true` to run the gated system(s), `false`
+ * to skip them this tick. `reads` / `resourceReads` declare the predicate's
+ * read surface for `accessCheck` (dev) and the future parallel scheduler's
+ * read-edge graph; both are optional (absent reads as empty).
+ */
+export interface RunCondition {
+    /** Human-readable label, surfaced in dev access-violation diagnostics. */
+    readonly name: string;
+    /** Pure, deterministic predicate. See the two hard rules in the file header. */
+    readonly evaluate: (ctx: ConditionContext) => boolean;
+    /** Components the predicate reads (via a captured query). Forward-looking
+     *  metadata — `ConditionContext` exposes no direct column read, so this is
+     *  not runtime-checkable today, but it is the read-edge a parallel scheduler
+     *  will consume. */
+    readonly reads?: readonly ComponentDef[];
+    /** Resources the predicate reads. Validated at runtime in `DEV` when the
+     *  condition evaluates inside `accessCheck.enterCondition`. */
+    readonly resourceReads?: readonly ResourceKey<any>[];
+}
+/**
+ * Run the gated system(s) only while a resource equals `expected` (strict `===`,
+ * so reference identity for objects). The canonical "feature flag / game phase"
+ * gate — flip `ecs.resources.set(key, …)` and the whole group toggles.
+ */
+export declare function runIfResourceEq<T>(key: ResourceKey<T>, expected: T): RunCondition;
+/**
+ * Run the gated system(s) once every `n` ticks — on ticks congruent to `offset`
+ * mod `n`. Keyed off the deterministic ECS tick, so it carries no private
+ * state and replays bit-identically. `offset` is a **phase shift taken mod `n`**
+ * (default `0` ⇒ fires on tick 0, n, 2n, …; `offset` and `offset + n` are the
+ * same phase, and a negative offset wraps), normalized once here into `[0, n)`.
+ * `n` must be a positive integer and `offset` an integer.
+ *
+ * The normalization isn't cosmetic: `(ecsTick - offset) % n` with a raw
+ * `offset ≥ n` (or negative) leans on JS's signed `%` yielding `-0` for a
+ * negative multiple (and `-0 === 0`) to stay congruent — correct, but load-
+ * bearing on a quirk. Folding `offset` into `[0, n)` up front makes the phase
+ * explicit: the per-tick dividend `ecsTick - phase` may still be negative
+ * (when `ecsTick < phase`), but with `phase ∈ [0, n)` it is never a *negative
+ * multiple* of `n` — it lands in `[-(n-1), -1]`, which holds no multiple of `n`
+ * — so `%` never produces `-0` and the check needs no signed-zero reliance.
+ */
+export declare function runEveryNTicks(n: number, offset?: number): RunCondition;
+/**
+ * Run the gated system(s) only when a query matches at least one (enabled)
+ * entity — flecs `runIf` over a query. The query is captured at config time;
+ * its component defs are declared as `reads`. `count()` is a membership sum over
+ * matching archetypes (no column reads), so it trips no `accessCheck` read.
+ *
+ * The query must be **dense-only**: `entityCount` asserts this in `DEV`
+ * (`_assertDenseOnly`), so pass a plain `ecs.query(...)` — a query carrying
+ * `.optional(...)` or sparse terms throws. Gate on sparse membership with a
+ * custom predicate over `forEachEntity` instead.
+ */
+export declare function runIfAnyMatch(query: Query<readonly ComponentDef[]>): RunCondition;
+/** Invert a condition: run exactly when `cond` would skip. */
+export declare function not(cond: RunCondition): RunCondition;
+/** Run only when EVERY condition passes (`&&`, short-circuit). */
+export declare function allOf(...conds: RunCondition[]): RunCondition;
+/** Run when ANY condition passes (`||`, short-circuit). */
+export declare function anyOf(...conds: RunCondition[]): RunCondition;
+//# sourceMappingURL=run_condition.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run_condition.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/run_condition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA8BK;AAEL,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIrC;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACpC,2EAA2E;IAC3E,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACtD;;;wBAGoB;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC;mEAC+D;IAC/D,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,YAAY,CAcjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,YAAY,CAoBlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,YAAY,EAAE,CAAC,GAAG,YAAY,CAMjF;AA4BD,8DAA8D;AAC9D,wBAAgB,GAAG,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CAMpD;AAED,kEAAkE;AAClE,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CAM5D;AAED,2DAA2D;AAC3D,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CAM5D"}

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

@@ -0,0 +1,142 @@
+import { SystemContext } from './query.cjs';
+import { SystemDescriptor } from './system.cjs';
+import { ComputeBackend } from './compute_backend.cjs';
+import { RunCondition } from './run_condition.cjs';
+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"
+}
+/**
+ * An opaque handle for a named group of systems (#576). A set carries a shared
+ * run condition and shared ordering that every member inherits. Sets are
+ * identified by **object identity**, not by name — create one with
+ * `systemSet(name)`, hold the handle, and reuse it across `addSystems`
+ * (`SystemEntry.set`) and `Schedule.configureSet`. The `name` is for
+ * diagnostics only.
+ */
+export interface SystemSet {
+    readonly name: string;
+}
+/** Create a `SystemSet` handle (#576). Two calls with the same name are two
+ * distinct sets — keep the returned handle and pass it around. */
+export declare function systemSet(name: string): SystemSet;
+/** A `before`/`after` ordering target: either a concrete system or a whole set
+ * (expanded to its members within the same phase at sort time). */
+export type SystemOrderingTarget = SystemDescriptor | SystemSet;
+/** Shared configuration applied to a `SystemSet` via `configureSet` (#576).
+ * Accumulates across calls — conditions AND together, ordering targets union. */
+export interface SystemSetConfig {
+    /** Condition(s) every member is gated by (ANDed with each member's own). */
+    runIf?: RunCondition | readonly RunCondition[];
+    /** Every member runs before each of these targets. */
+    before?: readonly SystemOrderingTarget[];
+    /** Every member runs after each of these targets. */
+    after?: readonly SystemOrderingTarget[];
+}
+export interface SystemOrdering {
+    before?: readonly SystemOrderingTarget[];
+    after?: readonly SystemOrderingTarget[];
+}
+export interface SystemEntry {
+    system: SystemDescriptor;
+    ordering?: SystemOrdering;
+    /** Run condition(s) gating just this system — ANDed with any set conditions
+     * it inherits (#576). A `false` verdict skips the body that tick. */
+    runIf?: RunCondition | readonly RunCondition[];
+    /** Set membership — the system inherits each set's shared condition and
+     * ordering (#576). */
+    set?: SystemSet | readonly SystemSet[];
+}
+export declare class Schedule {
+    private readonly labelSystems;
+    private readonly sortedCache;
+    private readonly systemIndex;
+    private readonly systemLastRun;
+    private readonly gatedSystems;
+    private readonly setConditions;
+    private readonly setOrdering;
+    private nextInsertionOrder;
+    private _backend;
+    /** Dev-diagnostic sink (`ECSOptions.onWarn`); defaults to `console.warn`.
+     * The only schedule diagnostic today is `warnDroppedEdge`. */
+    private readonly onWarn;
+    constructor(onWarn?: (message: string) => void);
+    addSystems(label: SCHEDULE, ...entries: (SystemDescriptor | SystemEntry)[]): void;
+    /**
+     * Configure a `SystemSet` (#576) — its shared run condition(s) and/or
+     * ordering, inherited by every member. Additive and order-independent w.r.t.
+     * `addSystems`: conditions accumulate (ANDed), ordering targets union, and
+     * a member added before or after this call picks the configuration up.
+     */
+    configureSet(set: SystemSet, config: SystemSetConfig): void;
+    removeSystem(system: SystemDescriptor): void;
+    /** Attach (or, with `null`, detach) the opt-in compute backend (#622). Driven
+     * by `ECS.attachBackend`; routes any scheduled system carrying a
+     * `backendHandle` to `backend.run(handle)` in place of its `fn`. */
+    setBackend(backend: ComputeBackend | null): void;
+    runStartup(ctx: SystemContext, tick: number): void;
+    runUpdate(ctx: SystemContext, deltaTime: number, tick: number): void;
+    runFixedUpdate(ctx: SystemContext, fixedDt: number, tick: number): void;
+    hasFixedSystems(): boolean;
+    getAllSystems(): SystemDescriptor[];
+    hasSystem(system: SystemDescriptor): boolean;
+    clear(): void;
+    private runLabel;
+    /**
+     * Whether a gated system runs this tick — the AND of its own conditions and
+     * every set it belongs to. A set's conditions are evaluated at most once per
+     * phase (memoized in `setVerdicts`) and the verdict gates every member of the
+     * set uniformly; a `configureSet` between phases is still honored because the
+     * memo lives only for a single `runLabel` pass. Short-circuits on the first
+     * `false`. The system's own conditions evaluate per system, in canonical order.
+     *
+     * #731 SEMANTIC NOTE: this evaluates a set's conditions once-per-set-per-phase
+     * rather than once-per-member. Equivalent for pure RunConditions; observably
+     * different only if a set condition reads state mutated earlier in the SAME
+     * phase (resources write immediately). That is intentional — the set gates as a
+     * unit, so all its members share one verdict for the phase.
+     */
+    private shouldRun;
+    /** Evaluate a condition list with AND semantics. Each predicate runs inside a
+     * reads-only `accessCheck` span (dev), so a condition that reads an
+     * undeclared resource — or attempts any mutation — throws. */
+    private evalConditions;
+    private getSorted;
+    /**
+     * Delegates to the shared topologicalSort utility.
+     * Builds the dependency edge map from before/after constraints, then
+     * catches any cycle TypeError and re-throws as ECSError.
+     */
+    private sortSystems;
+    /**
+     * Add the topo edges for one ordering list (#576). For `"before"` the source
+     * runs before each target (edge source→target); for `"after"` it runs after
+     * each target (edge target→source). A `SystemSet` target expands to every
+     * member within this phase (self-edges skipped, so a member ordered against
+     * its own set is a no-op); a descriptor target absent from this phase is
+     * dropped — with a dev warning only for a concrete system, since a set
+     * legitimately expands to nothing when its members live in another phase.
+     */
+    private resolveEdges;
+    /** Push one directed edge into the adjacency map. Both endpoints are known to
+     * be in this phase (callers guard), so `edges.get(...)` is non-null. */
+    private addDirectedEdge;
+    /**
+     * Dev-only diagnostic for an ordering edge that was dropped during sort.
+     *
+     * Cross-label ordering is impossible by design (`nodeSet` is per-label), so
+     * a target registered in *another* phase is skipped silently — that's the
+     * intended isolation. But a target unknown to *every* phase is almost
+     * certainly a typo or a system that was never scheduled; without this warning
+     * the constraint vanishes and the system runs in insertion-order tiebreak as
+     * if unconstrained, with nothing to distinguish mistake from intent. Compiled
+     * out of production builds by the `DEV` guards at the call sites.
+     */
+    private warnDroppedEdge;
+}
+//# sourceMappingURL=schedule.d.ts.map

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

@@ -0,0 +1,142 @@
+import { SystemContext } from './query.js';
+import { SystemDescriptor } from './system.js';
+import { ComputeBackend } from './compute_backend.js';
+import { RunCondition } from './run_condition.js';
+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"
+}
+/**
+ * An opaque handle for a named group of systems (#576). A set carries a shared
+ * run condition and shared ordering that every member inherits. Sets are
+ * identified by **object identity**, not by name — create one with
+ * `systemSet(name)`, hold the handle, and reuse it across `addSystems`
+ * (`SystemEntry.set`) and `Schedule.configureSet`. The `name` is for
+ * diagnostics only.
+ */
+export interface SystemSet {
+    readonly name: string;
+}
+/** Create a `SystemSet` handle (#576). Two calls with the same name are two
+ * distinct sets — keep the returned handle and pass it around. */
+export declare function systemSet(name: string): SystemSet;
+/** A `before`/`after` ordering target: either a concrete system or a whole set
+ * (expanded to its members within the same phase at sort time). */
+export type SystemOrderingTarget = SystemDescriptor | SystemSet;
+/** Shared configuration applied to a `SystemSet` via `configureSet` (#576).
+ * Accumulates across calls — conditions AND together, ordering targets union. */
+export interface SystemSetConfig {
+    /** Condition(s) every member is gated by (ANDed with each member's own). */
+    runIf?: RunCondition | readonly RunCondition[];
+    /** Every member runs before each of these targets. */
+    before?: readonly SystemOrderingTarget[];
+    /** Every member runs after each of these targets. */
+    after?: readonly SystemOrderingTarget[];
+}
+export interface SystemOrdering {
+    before?: readonly SystemOrderingTarget[];
+    after?: readonly SystemOrderingTarget[];
+}
+export interface SystemEntry {
+    system: SystemDescriptor;
+    ordering?: SystemOrdering;
+    /** Run condition(s) gating just this system — ANDed with any set conditions
+     * it inherits (#576). A `false` verdict skips the body that tick. */
+    runIf?: RunCondition | readonly RunCondition[];
+    /** Set membership — the system inherits each set's shared condition and
+     * ordering (#576). */
+    set?: SystemSet | readonly SystemSet[];
+}
+export declare class Schedule {
+    private readonly labelSystems;
+    private readonly sortedCache;
+    private readonly systemIndex;
+    private readonly systemLastRun;
+    private readonly gatedSystems;
+    private readonly setConditions;
+    private readonly setOrdering;
+    private nextInsertionOrder;
+    private _backend;
+    /** Dev-diagnostic sink (`ECSOptions.onWarn`); defaults to `console.warn`.
+     * The only schedule diagnostic today is `warnDroppedEdge`. */
+    private readonly onWarn;
+    constructor(onWarn?: (message: string) => void);
+    addSystems(label: SCHEDULE, ...entries: (SystemDescriptor | SystemEntry)[]): void;
+    /**
+     * Configure a `SystemSet` (#576) — its shared run condition(s) and/or
+     * ordering, inherited by every member. Additive and order-independent w.r.t.
+     * `addSystems`: conditions accumulate (ANDed), ordering targets union, and
+     * a member added before or after this call picks the configuration up.
+     */
+    configureSet(set: SystemSet, config: SystemSetConfig): void;
+    removeSystem(system: SystemDescriptor): void;
+    /** Attach (or, with `null`, detach) the opt-in compute backend (#622). Driven
+     * by `ECS.attachBackend`; routes any scheduled system carrying a
+     * `backendHandle` to `backend.run(handle)` in place of its `fn`. */
+    setBackend(backend: ComputeBackend | null): void;
+    runStartup(ctx: SystemContext, tick: number): void;
+    runUpdate(ctx: SystemContext, deltaTime: number, tick: number): void;
+    runFixedUpdate(ctx: SystemContext, fixedDt: number, tick: number): void;
+    hasFixedSystems(): boolean;
+    getAllSystems(): SystemDescriptor[];
+    hasSystem(system: SystemDescriptor): boolean;
+    clear(): void;
+    private runLabel;
+    /**
+     * Whether a gated system runs this tick — the AND of its own conditions and
+     * every set it belongs to. A set's conditions are evaluated at most once per
+     * phase (memoized in `setVerdicts`) and the verdict gates every member of the
+     * set uniformly; a `configureSet` between phases is still honored because the
+     * memo lives only for a single `runLabel` pass. Short-circuits on the first
+     * `false`. The system's own conditions evaluate per system, in canonical order.
+     *
+     * #731 SEMANTIC NOTE: this evaluates a set's conditions once-per-set-per-phase
+     * rather than once-per-member. Equivalent for pure RunConditions; observably
+     * different only if a set condition reads state mutated earlier in the SAME
+     * phase (resources write immediately). That is intentional — the set gates as a
+     * unit, so all its members share one verdict for the phase.
+     */
+    private shouldRun;
+    /** Evaluate a condition list with AND semantics. Each predicate runs inside a
+     * reads-only `accessCheck` span (dev), so a condition that reads an
+     * undeclared resource — or attempts any mutation — throws. */
+    private evalConditions;
+    private getSorted;
+    /**
+     * Delegates to the shared topologicalSort utility.
+     * Builds the dependency edge map from before/after constraints, then
+     * catches any cycle TypeError and re-throws as ECSError.
+     */
+    private sortSystems;
+    /**
+     * Add the topo edges for one ordering list (#576). For `"before"` the source
+     * runs before each target (edge source→target); for `"after"` it runs after
+     * each target (edge target→source). A `SystemSet` target expands to every
+     * member within this phase (self-edges skipped, so a member ordered against
+     * its own set is a no-op); a descriptor target absent from this phase is
+     * dropped — with a dev warning only for a concrete system, since a set
+     * legitimately expands to nothing when its members live in another phase.
+     */
+    private resolveEdges;
+    /** Push one directed edge into the adjacency map. Both endpoints are known to
+     * be in this phase (callers guard), so `edges.get(...)` is non-null. */
+    private addDirectedEdge;
+    /**
+     * Dev-only diagnostic for an ordering edge that was dropped during sort.
+     *
+     * Cross-label ordering is impossible by design (`nodeSet` is per-label), so
+     * a target registered in *another* phase is skipped silently — that's the
+     * intended isolation. But a target unknown to *every* phase is almost
+     * certainly a typo or a system that was never scheduled; without this warning
+     * the constraint vanishes and the system runs in insertion-order tiebreak as
+     * if unconstrained, with nothing to distinguish mistake from intent. Compiled
+     * out of production builds by the `DEV` guards at the call sites.
+     */
+    private warnDroppedEdge;
+}
+//# sourceMappingURL=schedule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/schedule.ts"],"names":[],"mappings":"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"}