@oasys/oecs 0.4.0 → 0.5.0

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

@@ -0,0 +1,235 @@
+import { BitSet, TypedArrayTag } from '../../type_primitives/index.js';
+import { Archetype } from './archetype.js';
+import { EntityID } from './entity.js';
+import { RelationDef, RelationOptions, RelationStore } from './relation.js';
+import { SparseComponentDef, SparseComponentID, SparseComponentStore } from './sparse_store.js';
+/** What the relation service needs from `Store` — nothing more. The accessor
+ * members re-read the live field on every call, so capacity growth that
+ * reallocates `entityGenerations` / `entityArchetype` / `entityRow` is always
+ * observed; never cache their return values across mutations. */
+export interface RelationServiceHost {
+    isAlive(id: EntityID): boolean;
+    hasSparse(entityId: EntityID, def: SparseComponentDef): boolean;
+    pushSparseStore(fieldNames: string[], fieldTypes: TypedArrayTag[]): SparseComponentDef;
+    sparseStoreOf(def: SparseComponentDef): SparseComponentStore;
+    sparseStores(): readonly SparseComponentStore[];
+    entityGenerations(): Int32Array;
+    entityArchetype(): Int32Array;
+    entityRow(): Int32Array;
+    archetypes(): readonly Archetype[];
+    forEachSparseMatch(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], denseArchetypes: readonly Archetype[], cb: (entityId: EntityID) => void, includeDisabled: boolean): void;
+}
+export declare class RelationService {
+    private readonly host;
+    private readonly relations;
+    private _hasTargetCleanup;
+    private readonly _hierarchyRadixOut;
+    private readonly _hierarchyRadixC0;
+    private readonly _hierarchyRadixC1;
+    constructor(host: RelationServiceHost);
+    /** The registry, indexed by RelationID — the read-only view the Store's
+     * `stateHash` / snapshot / restore paths iterate. */
+    get stores(): readonly RelationStore[];
+    /** Number of registered relations. */
+    get count(): number;
+    /** Whether any relation registered a non-`orphan` `onDeleteTarget` policy —
+     * the destroy paths' gate for `cleanupTarget` (#473). */
+    get hasTargetCleanup(): boolean;
+    /** Register a relation kind. `exclusive` (the default) → one target per
+     * source, stored in a backing `{ target: f64 }` sparse component, so the
+     * forward index rides the sparse store and inherits query membership (#469),
+     * `stateHash` + snapshot/restore (#470) for free. `multi` → a set of
+     * targets per source, backed by a sparse tag for membership plus a side
+     * forward index the relation owns. The two cardinalities are mutually
+     * exclusive. `onDeleteTarget` selects the cleanup policy run when a target
+     * is destroyed — `delete` (cascade-destroy sources), `clear` (drop the link,
+     * sources survive), or `orphan` (default: leave it dangling, #473). See
+     * ADR-0011 and `relation.ts`.
+     *
+     * The backing sparse store is resolved and handed to the relation so it can
+     * drive forward/membership rows directly — the cardinality-specific
+     * interaction is `ExclusiveRelationStore` / `MultiRelationStore`'s, not a
+     * branch here (#498). */
+    registerRelation(opts?: RelationOptions): RelationDef;
+    private relationOf;
+    /** Add a `(R, tgt)` pair to `src`. No archetype transition. Exclusive:
+     * replaces any existing target (engine-enforced one-per-source), a no-op if
+     * `tgt` is already the target. Multi: adds `tgt` to the set, a no-op if
+     * already present. A dead `src` *or* `tgt` is caller error: it throws in
+     * `DEV` and is a no-op in production — symmetric, so a production build
+     * never links a reverse-index entry keyed by a destroyed handle (#495). */
+    addRelation(src: EntityID, def: RelationDef, tgt: EntityID): void;
+    /** Remove a `(R, tgt)` pair from `src`. No archetype transition. Exclusive:
+     * `tgt` is optional and the removal is a no-op when it names a target other
+     * than the current one. Multi: omitting `tgt` removes *all* of `src`'s
+     * targets; passing one removes just that pair (dropping membership when the
+     * set empties). */
+    removeRelation(src: EntityID, def: RelationDef, tgt?: EntityID): void;
+    /** The single target of `src` under an exclusive relation, or `undefined`.
+     * Throws in `DEV` on a multi-target relation (use `targetsOf`). */
+    targetOf(src: EntityID, def: RelationDef): EntityID | undefined;
+    /** All targets of `src` under `R` — one or zero for exclusive, the full set
+     * for multi — ascending by id. */
+    targetsOf(src: EntityID, def: RelationDef): EntityID[];
+    /** Sources that point at `tgt` under `R` (the reverse index), ascending by
+     * id; empty when none. */
+    sourcesOf(tgt: EntityID, def: RelationDef): EntityID[];
+    /** Whether `src` holds any pair under `R`. */
+    hasRelation(src: EntityID, def: RelationDef): boolean;
+    /** All `(source, target)` pairs of relation `R` — the `(R, *)` wildcard
+     * (#472). Sources are emitted in **canonical entity-index order** (the #470
+     * determinism convention): exclusive relations ride the backing sparse
+     * store's `canonicalIndices`, multi relations ride the same
+     * `forEachCanonicalTargetSet` traversal `stateHash` / `snapshotRelations`
+     * use; a multi source's targets follow ascending by id. Empty when the
+     * relation holds no pairs. Cold path — allocates the result array (and, for
+     * multi, sorts each source's target set); not for per-tick use. The
+     * point-query forms are `targetOf` / `targetsOf`. */
+    pairsOf(def: RelationDef): readonly (readonly [EntityID, EntityID])[];
+    /** Every `(relation, source)` pointing at `tgt`, across **all** registered
+     * relation kinds — the `(*, T)` wildcard (#472). Walks the relation registry
+     * in id order (each relation's reverse index already returns sources
+     * ascending by id), so the result is ordered by relation id then source id.
+     * Empty when nothing targets `tgt`. The single-relation form is
+     * `sourcesOf(tgt, def)`. */
+    sourcesOfAny(tgt: EntityID): readonly (readonly [RelationDef, EntityID])[];
+    /** The backing sparse component id of relation `R` — the membership store a
+     * `(R, *)` wildcard term (`Query.withRelation`) drives through the shared
+     * sparse-match path. Exclusive relations back a `{ target: f64 }` sparse
+     * component, multi a tag; both carry per-source membership, so "has any
+     * `(R, *)` pair" is exactly membership in this store (including an
+     * orphan-dangling source, whose membership row persists — consistent with
+     * `pairsOf`). The def is engine-owned and never handed to callers; this hands
+     * the query builder only its erased id for the `sparseInclude` list. */
+    relationBackingSparseId(def: RelationDef): SparseComponentID;
+    /** Drive a `(*, T)` wildcard query (`Query.forEachRelatedTo`): every source
+     * related to `target` under **any** relation, intersected with the query's
+     * dense mask + sparse require/exclude terms + the default enabled-row filter,
+     * each source yielded once. Unions `sourcesOf(target, R)` across every
+     * relation into a `Set` (dedup by full `EntityID` — a source related to `T`
+     * via two relations is yielded once), then sorts ascending: the cross-relation
+     * union has no inherent order, so one cold sort gives a deterministic,
+     * canonical `(*, T)` order matching `sourcesOf` / `sourcesOfAny` (which sort
+     * the same way). Cold/structural — not a per-tick hot loop over many targets.
+     * `sparseInclude`/`sparseExclude` carry both raw sparse terms and the backing
+     * stores of any composed `(R, *)` terms, so it intersects with them uniformly. */
+    forEachRelationTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], includeDisabled: boolean, cb: (entityId: EntityID) => void): void;
+    /** Reclaim reverse-index memory: drop every relation's reverse entries whose
+     * **target** has been destroyed, returning the total dropped across all
+     * relations (#491). Under the default `orphan` policy a destroyed target
+     * leaves its reverse entry intact until each source re-targets or dies, so a
+     * long-lived source that orphan-points at a churn of short-lived targets and
+     * never re-targets accumulates dead-target keys without bound. This cold-path
+     * hook drops them on demand — call it at scene or snapshot boundaries.
+     *
+     * Purely a memory reclaim with no observable state change: forward links stay
+     * dangling (so `orphan`'s `targetOf`-returns-the-dead-handle contract is
+     * unchanged), `stateHash` is unaffected (the reverse index is derived, never
+     * folded), and the dropped entries are faithfully rebuilt by snapshot/restore
+     * from the surviving forward links (`Store._rebuildRelationIndices`). The only
+     * difference a caller can see is `sourcesOf(deadHandle, R)` going from the
+     * dangling sources to `[]` — both meaningless once the target is gone.
+     * No-op (returns 0) when no relations are registered. */
+    compactRelations(): number;
+    /** Walk exclusive relation `R` from `src` toward the root, returning the
+     * **up**-chain `[src, parent, grandparent, …, root]` (nearest-ancestor-first,
+     * inclusive of both endpoints). A source with no target returns `[src]`. The
+     * root is the first entity in the chain with no `R`-target, **or** a dangling
+     * dead target handle (see below). Throws `RELATION_MODE_MISMATCH` on a multi
+     * relation and `RELATION_CYCLE` on a cycle (both `DEV`-only; in production
+     * a cycle stops at the repeated node).
+     *
+     * **Dangling links terminate the chain.** Under the `orphan` policy a source
+     * keeps pointing at a destroyed target (a dead handle). The walk must *not*
+     * advance through such a handle: the backing store is keyed by entity
+     * **index**, so reading the dead handle's index would return whatever now
+     * occupies that recycled slot — splicing the chain onto an unrelated entity
+     * (the ABA the `EntityID`-keyed reverse index avoids for `cascadeOf`). So a
+     * dead next-hop is appended as the chain's (dangling) terminus and the walk
+     * stops; the caller can detect it with `isAlive`, exactly as `targetOf`
+     * returns a dead handle. */
+    ancestorsOf(src: EntityID, def: RelationDef): EntityID[];
+    /** The root of `src`'s exclusive-relation chain — the last entity of
+     * `ancestorsOf` (the one with no `R`-target). `src` itself when it has no
+     * target. If the chain ends in a dangling dead target handle (orphan policy),
+     * that handle is the root — `isAlive`-check the result if dangling links are
+     * possible. Same `DEV` guards as `ancestorsOf`. */
+    rootOf(src: EntityID, def: RelationDef): EntityID;
+    /** Walk exclusive relation `R` **down** from `root` over the reverse index,
+     * returning the subtree (including `root`) breadth-first — **parents before
+     * children** (the `cascade` order). Children of each node come from
+     * `sourcesOf` (ascending by id), so the traversal is deterministic. Throws
+     * `RELATION_MODE_MISMATCH` on a multi relation and `RELATION_CYCLE` on a cycle
+     * (both `DEV`-only; in production an already-visited node is skipped, so
+     * it never hangs). */
+    cascadeOf(root: EntityID, def: RelationDef): EntityID[];
+    /** Purge a destroyed entity from the relation indices — its **source** role
+     * only: drop its forward target(s) and unlink it from every target's reverse
+     * set. The backing sparse membership row is dropped separately by the Store's
+     * `_purgeSparse`, so this must run *before* it (it reads the sparse target
+     * field for exclusive relations). The entity's **target** role is left
+     * intact: the reverse index is keyed by full `EntityID`, so a recycled slot
+     * never aliases the dead target's sources. The destroyed entity's **target**
+     * role is handled separately by `cleanupTarget` per each relation's
+     * `OnDeleteTarget` policy (#473). Gated by the caller on `count > 0`. */
+    purgeSource(entityId: EntityID): void;
+    /** Apply each relation's `OnDeleteTarget` policy for a destroyed **target**
+     * `targetId` (#473). Walks the registry; for every relation whose reverse
+     * index has sources pointing at the dead target:
+     *
+     *  - **`delete`** — append each source to `cascade`; the caller destroys them
+     *    through the same path, so chains/trees cascade recursively. The sources'
+     *    own source-role purge (`purgeSource`) drops their forward link and
+     *    unlinks them from `targetId`'s reverse set, so no reverse entry leaks.
+     *  - **`clear`** — drop each source's link to the dead target in place via
+     *    `rs.unlink(src, targetId)` (exclusive drops the row; multi removes the
+     *    target from the set, dropping membership when it empties). Sources
+     *    survive — the cardinality bookkeeping is the relation's, not branched here.
+     *  - **`orphan`** — skipped (the link is left dangling; safe because the
+     *    reverse key carries the generation).
+     *
+     * `sourcesOf` returns a fresh snapshot, so mutating the reverse index while
+     * iterating is safe. Gated by the caller on `hasTargetCleanup`, so the
+     * whole walk is skipped when no relation opts into a non-`orphan` policy. */
+    cleanupTarget(targetId: EntityID, cascade: EntityID[]): void;
+    /** Fourth query-match path (#581): yield the matched entities — the exact
+     * sparse-match intersection (dense mask + sparse require/exclude + the
+     * default enabled-row filter) — in canonical **hierarchy depth order** over
+     * exclusive relation `R`: depth ascending (parents before children), **entity
+     * index ascending within each depth band**. Entities deeper than `maxDepth`
+     * are skipped (`Infinity` = unbounded). Only reached via `Query.forEachEntity`
+     * on a query carrying a `.hierarchy(R)` term.
+     *
+     * `.hierarchy(R)` does not narrow the matched set — it reorders it — so an
+     * entity with no `R`-parent is a root (depth 0) and is yielded first. Depth is a
+     * structural property of the *full* tree (an ancestor outside the matched set
+     * still counts toward depth), computed by a memoised upward walk shared across
+     * the whole batch, so a shared/deep chain costs O(nodes), not O(nodes²).
+     *
+     * The canonical order is produced without a comparator sort (which the observer
+     * bench measured at 2–4× — `observer.ts`): (1) collect the matched ids via
+     * the host's `forEachSparseMatch`; (2) `radixSortByIndex` → entity-index
+     * ascending; (3) stable-bucket by depth — since the input is index-ascending
+     * and the bucket append is stable, each depth band stays index-ascending.
+     * Tuned for the motivating per-tick case (transform propagation): the radix
+     * scratch is reused instance state (`_hierarchyRadix*`), so a per-tick pass
+     * churns no histograms; the working set (`matched` / `buckets` / `depthMemo` /
+     * `visiting`) is still allocated per call, as it must stay call-local for
+     * re-entrancy.
+     *
+     * Exclusive-only — a multi relation throws `RELATION_MODE_MISMATCH` in `DEV`
+     * (mirrors `cascadeOf` / `ancestorsOf`); a cycle is a loud `RELATION_CYCLE` in
+     * `DEV` and a safe break in production. */
+    forEachHierarchyMatch(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, sparseInclude: readonly SparseComponentID[], sparseExclude: readonly SparseComponentID[], denseArchetypes: readonly Archetype[], relation: RelationDef, maxDepth: number, includeDisabled: boolean, cb: (entityId: EntityID) => void): void;
+    /** Depth of entity index `idx` in the exclusive-relation tree backing `store`
+     * (root = 0), for `forEachHierarchyMatch`. Memoised across the batch (`memo`),
+     * so a shared ancestor chain is walked once. Walks upward via the backing store's
+     * target field 0 (mirroring `ancestorsOf`), stopping at: a root (no target), an
+     * already-memoised node, or a dangling/dead parent (the child is then treated as
+     * a root — never advance through a recycled slot, the ABA `ancestorsOf` guards).
+     * `visiting` flags the nodes on the current upward path to catch a cycle —
+     * `RELATION_CYCLE` in `DEV`, treated as a root in production — and is emptied
+     * on the way back down so it can be reused for the next entity. */
+    private _hierarchyDepthOf;
+}
+//# sourceMappingURL=relation_service.d.ts.map

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

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

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

@@ -0,0 +1,53 @@
+/***
+ * Resource — Typed singleton key-value storage.
+ *
+ * Resources are global singletons that don't belong to any entity.
+ * Think: time, input state, camera config, game settings.
+ *
+ * Each resource is identified by a unique symbol (ResourceKey<T>) and
+ * stores an arbitrary typed value. The key carries the value type as a
+ * phantom type parameter, so reads are type-safe at compile time.
+ *
+ * Lifecycle (#798). A resource is register-once *until removed*: a second
+ * `registerResource` for a live key throws RESOURCE_ALREADY_REGISTERED, but
+ * `removeResource(key)` drops it (failing closed on a missing key) and frees the
+ * key to be registered again — the present → absent → present axis. Removal is
+ * access-checked as a *write* (a system must declare the key in `resourceWrites`),
+ * and resources stay out of `stateHash` and snapshot/resume regardless, so a
+ * lifecycle change never perturbs the determinism hash.
+ *
+ * Usage:
+ *
+ *   const TimeRes = resourceKey<{ delta: number; elapsed: number }>("Time");
+ *   ecs.resources.register(TimeRes, { delta: 0, elapsed: 0 });
+ *   const time = ecs.resources.get(TimeRes);
+ *   // time.delta → number, time.elapsed → number
+ *   ecs.resources.remove(TimeRes);                             // present → absent
+ *   ecs.resources.register(TimeRes, { delta: 0, elapsed: 0 }); // → present again
+ *
+ ***/
+/**
+ * `T` is deliberately INVARIANT (via the function-typed phantom — an `in out`
+ * annotation is not legal on an intersection alias, so the structure carries
+ * the variance): a key is used for both reads (`resource`, covariant) and
+ * writes (`setResource`, contravariant), so either one-sided variance is a
+ * soundness hole — a covariant `T` let `ResourceKey<Cat>` widen to
+ * `ResourceKey<Animal>` and `setResource` then stored a `Dog` behind a `Cat`
+ * key. Invariance also makes keys with different `T` mutually unassignable,
+ * which is what the typed system seam's `resourceReads`/`resourceWrites`
+ * narrowing keys on (§typestate). Schema-erased positions (access checks,
+ * declaration lists) must use `ResourceKey<any>` — `ResourceKey<unknown>` no
+ * longer erases.
+ */
+declare const __resourceValue: unique symbol;
+export type ResourceKey<T> = symbol & {
+    readonly [__resourceValue]: (value: T) => T;
+};
+export declare function resourceKey<T>(name: string): ResourceKey<T>;
+/** Recover a key's value type: `ResourceValueOf<typeof TimeRes>` is the Time
+ * shape. The typed `SystemContext` resource surface infers the KEY type (to
+ * check it against the declared-access union) and recovers `T` through this,
+ * instead of taking `ResourceKey<T>` directly. */
+export type ResourceValueOf<K> = K extends ResourceKey<infer T> ? T : never;
+export {};
+//# sourceMappingURL=resource.d.ts.map

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

@@ -19,15 +19,35 @@
  * Usage:
  *
  *   const TimeRes = resourceKey<{ delta: number; elapsed: number }>("Time");
- *   world.registerResource(TimeRes, { delta: 0, elapsed: 0 });
- *   const time = world.resource(TimeRes);
+ *   ecs.resources.register(TimeRes, { delta: 0, elapsed: 0 });
+ *   const time = ecs.resources.get(TimeRes);
  *   // time.delta → number, time.elapsed → number
- *   world.removeResource(TimeRes);                             // present → absent
- *   world.registerResource(TimeRes, { delta: 0, elapsed: 0 }); // → present again
+ *   ecs.resources.remove(TimeRes);                             // present → absent
+ *   ecs.resources.register(TimeRes, { delta: 0, elapsed: 0 }); // → present again
  *
  ***/
+/**
+ * `T` is deliberately INVARIANT (via the function-typed phantom — an `in out`
+ * annotation is not legal on an intersection alias, so the structure carries
+ * the variance): a key is used for both reads (`resource`, covariant) and
+ * writes (`setResource`, contravariant), so either one-sided variance is a
+ * soundness hole — a covariant `T` let `ResourceKey<Cat>` widen to
+ * `ResourceKey<Animal>` and `setResource` then stored a `Dog` behind a `Cat`
+ * key. Invariance also makes keys with different `T` mutually unassignable,
+ * which is what the typed system seam's `resourceReads`/`resourceWrites`
+ * narrowing keys on (§typestate). Schema-erased positions (access checks,
+ * declaration lists) must use `ResourceKey<any>` — `ResourceKey<unknown>` no
+ * longer erases.
+ */
+declare const __resourceValue: unique symbol;
 export type ResourceKey<T> = symbol & {
-    readonly __phantom: T;
+    readonly [__resourceValue]: (value: T) => T;
 };
 export declare function resourceKey<T>(name: string): ResourceKey<T>;
+/** Recover a key's value type: `ResourceValueOf<typeof TimeRes>` is the Time
+ * shape. The typed `SystemContext` resource surface infers the KEY type (to
+ * check it against the declared-access union) and recovers `T` through this,
+ * instead of taking `ResourceKey<T>` directly. */
+export type ResourceValueOf<K> = K extends ResourceKey<infer T> ? T : never;
+export {};
 //# sourceMappingURL=resource.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;KA2BK;AAIL,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,MAAM,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAA;CAAE,CAAC;AAEhE,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAE3D"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;KA2BK;AAIL;;;;;;;;;;;;GAYG;AACH,OAAO,CAAC,MAAM,eAAe,EAAE,OAAO,MAAM,CAAC;AAE7C,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAA;CAAE,CAAC;AAEtF,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAE3D;AAED;;;kDAGkD;AAClD,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC"}

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

@@ -0,0 +1,20 @@
+/***
+ * ResourceRegistry — the world's symbol-keyed resource dictionary (H1 step 2).
+ *
+ * Extracted from `Store`, which keeps one-line delegations; fully
+ * self-contained (no Store reach-back). Resources stay out of `stateHash` and
+ * out of snapshot/resume — this is host-side state, not simulation state.
+ ***/
+export declare class ResourceRegistry {
+    private readonly map;
+    register(key: symbol, value: unknown): void;
+    get(key: symbol): unknown;
+    set(key: symbol, value: unknown): void;
+    /** Drop a resource from the world. Fails closed on a missing key (mirrors
+     * `get` / `set`); afterwards the key is free to `register` again — the
+     * present → absent → present lifecycle (#798). Purely a host-side
+     * dictionary delete with no determinism-hash effect. */
+    remove(key: symbol): void;
+    has(key: symbol): boolean;
+}
+//# sourceMappingURL=resource_registry.d.ts.map

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

@@ -0,0 +1,20 @@
+/***
+ * ResourceRegistry — the world's symbol-keyed resource dictionary (H1 step 2).
+ *
+ * Extracted from `Store`, which keeps one-line delegations; fully
+ * self-contained (no Store reach-back). Resources stay out of `stateHash` and
+ * out of snapshot/resume — this is host-side state, not simulation state.
+ ***/
+export declare class ResourceRegistry {
+    private readonly map;
+    register(key: symbol, value: unknown): void;
+    get(key: symbol): unknown;
+    set(key: symbol, value: unknown): void;
+    /** Drop a resource from the world. Fails closed on a missing key (mirrors
+     * `get` / `set`); afterwards the key is free to `register` again — the
+     * present → absent → present lifecycle (#798). Purely a host-side
+     * dictionary delete with no determinism-hash effect. */
+    remove(key: symbol): void;
+    has(key: symbol): boolean;
+}
+//# sourceMappingURL=resource_registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resource_registry.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/resource_registry.ts"],"names":[],"mappings":"AAAA;;;;;;KAMK;AAIL,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmC;IAEhD,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAW3C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAWzB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAW7C;;;4DAGwD;IACjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAWzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAGhC"}

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

@@ -1,17 +1,17 @@
-import { ArchetypeViews } from '../store';
+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 WORLD_SNAPSHOT_VERSION = 1;
+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 WorldRestoreError extends Error {
+export declare class ECSRestoreError extends Error {
     constructor(message: string);
 }
 /** Per-archetype host-side row bookkeeping the SAB doesn't carry authoritatively. */
@@ -45,7 +45,7 @@ export interface HostState {
  */
 export declare function serializeHostState(hs: HostState): Uint8Array;
 /** Parse host-state bytes produced by `serializeHostState`. Throws
- * `WorldRestoreError` on truncation or a trailing-byte (non-canonical) buffer. */
+ * `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:
  *
@@ -60,7 +60,7 @@ export interface WorldSnapshotSections {
     readonly host: Uint8Array;
 }
 /** Split a combined frame back into its sections. Validates magic, version, and
- * an exact (no trailing bytes) frame; throws `WorldRestoreError` otherwise. */
+ * 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
@@ -79,7 +79,7 @@ export declare function unframeWorldSnapshot(bytes: Uint8Array): WorldSnapshotSe
  * 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
- * `WorldRestoreError` on any mismatch / malformed section.
+ * `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

@@ -1 +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,sBAAsB,IAAI,CAAC;AAExC;;;;2BAI2B;AAC3B,qBAAa,iBAAkB,SAAQ,KAAK;gBAC/B,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;kFACkF;AAClF,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;+EAC+E;AAC/E,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"}
+{"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