@oasys/oecs 0.5.3 → 0.6.0

package/dist/plugins/relations/builtin_relations.d.cts

@@ -0,0 +1,48 @@
+import { ECS } from '../../core/ecs/ecs.cjs';
+import { OnDeleteTarget, RelationDef } from '../../core/ecs/relation.cjs';
+import { RelationsPlugin } from './index.cjs';
+/** A world with the relations plugin installed. These helpers register a
+ * relation, so they need it. */
+type RelationalWorld = ECS<RelationsPlugin> & RelationsPlugin;
+/** Options for a built-in relation. `exclusive` and `multi` are fixed (always
+ * exclusive, required for the chain and tree traversal helpers), so only the
+ * target-deletion cleanup policy is tunable. */
+export interface BuiltinRelationOptions {
+    /** What happens to a relation's sources when a target is destroyed.
+     * Defaults per relation (see each registrar). */
+    readonly onDeleteTarget?: OnDeleteTarget;
+}
+/**
+ * Register an **`IsA(instance → exemplar)`** relation, a thin instance-of link.
+ *
+ * - "all instances of exemplar E" is `ecs.relations.sourcesOf(E, IsA)`.
+ * - the IsA chain (`instance → exemplar → …`) is walked with
+ *   `ecs.relations.ancestorsOf(instance, IsA)`, `rootOf` and `cascadeOf(exemplar, IsA)`.
+ * - **No component inheritance**. IsA records the link only. Materialization of
+ *   an instance from its exemplar stays a spawn-time copy on the template path,
+ *   deliberately decoupled. An exemplar is a real entity and not a `Template`,
+ *   because a non-entity template cannot be a relation target.
+ *
+ * Default `onDeleteTarget: "clear"`, destroying an exemplar drops its
+ * instances' IsA link but leaves the instances alive (the thin analog of
+ * flecs's `IsA`-remove, since there is no inherited data to strip). Pass
+ * `"delete"` for strong instance-of (exemplar death cascade-destroys instances).
+ */
+export declare function registerIsA(ecs: RelationalWorld, opts?: BuiltinRelationOptions): RelationDef<"exclusive">;
+/**
+ * Register a **`ChildOf(child → parent)`** relation, a thin hierarchy link.
+ *
+ * - a parent's children are `ecs.relations.sourcesOf(parent, ChildOf)`.
+ * - the hierarchy is walked with `ecs.relations.ancestorsOf(child, ChildOf)` (up to the
+ *   root), `rootOf`, and `cascadeOf(root, ChildOf)` (down, breadth-first,
+ *   parents before children).
+ * - unlike flecs's `ChildOf`, this does **not** scope names or lookup, the engine
+ *   has no name registry. It is purely the structural parent link.
+ *
+ * Default `onDeleteTarget: "delete"`, destroying a parent cascade-destroys
+ * its whole subtree (flecs's default). Pass `"clear"` to let children survive as
+ * roots, or `"orphan"` to leave a dangling `targetOf`.
+ */
+export declare function registerChildOf(ecs: RelationalWorld, opts?: BuiltinRelationOptions): RelationDef<"exclusive">;
+export {};
+//# sourceMappingURL=builtin_relations.d.ts.map

package/dist/plugins/relations/builtin_relations.d.ts

@@ -0,0 +1,48 @@
+import { ECS } from '../../core/ecs/ecs.js';
+import { OnDeleteTarget, RelationDef } from '../../core/ecs/relation.js';
+import { RelationsPlugin } from './index.js';
+/** A world with the relations plugin installed. These helpers register a
+ * relation, so they need it. */
+type RelationalWorld = ECS<RelationsPlugin> & RelationsPlugin;
+/** Options for a built-in relation. `exclusive` and `multi` are fixed (always
+ * exclusive, required for the chain and tree traversal helpers), so only the
+ * target-deletion cleanup policy is tunable. */
+export interface BuiltinRelationOptions {
+    /** What happens to a relation's sources when a target is destroyed.
+     * Defaults per relation (see each registrar). */
+    readonly onDeleteTarget?: OnDeleteTarget;
+}
+/**
+ * Register an **`IsA(instance → exemplar)`** relation, a thin instance-of link.
+ *
+ * - "all instances of exemplar E" is `ecs.relations.sourcesOf(E, IsA)`.
+ * - the IsA chain (`instance → exemplar → …`) is walked with
+ *   `ecs.relations.ancestorsOf(instance, IsA)`, `rootOf` and `cascadeOf(exemplar, IsA)`.
+ * - **No component inheritance**. IsA records the link only. Materialization of
+ *   an instance from its exemplar stays a spawn-time copy on the template path,
+ *   deliberately decoupled. An exemplar is a real entity and not a `Template`,
+ *   because a non-entity template cannot be a relation target.
+ *
+ * Default `onDeleteTarget: "clear"`, destroying an exemplar drops its
+ * instances' IsA link but leaves the instances alive (the thin analog of
+ * flecs's `IsA`-remove, since there is no inherited data to strip). Pass
+ * `"delete"` for strong instance-of (exemplar death cascade-destroys instances).
+ */
+export declare function registerIsA(ecs: RelationalWorld, opts?: BuiltinRelationOptions): RelationDef<"exclusive">;
+/**
+ * Register a **`ChildOf(child → parent)`** relation, a thin hierarchy link.
+ *
+ * - a parent's children are `ecs.relations.sourcesOf(parent, ChildOf)`.
+ * - the hierarchy is walked with `ecs.relations.ancestorsOf(child, ChildOf)` (up to the
+ *   root), `rootOf`, and `cascadeOf(root, ChildOf)` (down, breadth-first,
+ *   parents before children).
+ * - unlike flecs's `ChildOf`, this does **not** scope names or lookup, the engine
+ *   has no name registry. It is purely the structural parent link.
+ *
+ * Default `onDeleteTarget: "delete"`, destroying a parent cascade-destroys
+ * its whole subtree (flecs's default). Pass `"clear"` to let children survive as
+ * roots, or `"orphan"` to leave a dangling `targetOf`.
+ */
+export declare function registerChildOf(ecs: RelationalWorld, opts?: BuiltinRelationOptions): RelationDef<"exclusive">;
+export {};
+//# sourceMappingURL=builtin_relations.d.ts.map

package/dist/plugins/relations/builtin_relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin_relations.d.ts","sourceRoot":"","sources":["../../../src/plugins/relations/builtin_relations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;KAsBK;AAEL,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;gCACgC;AAChC,KAAK,eAAe,GAAG,GAAG,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;AAE9D;;gDAEgD;AAChD,MAAM,WAAW,sBAAsB;IACtC;qDACiD;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CACzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAC1B,GAAG,EAAE,eAAe,EACpB,IAAI,CAAC,EAAE,sBAAsB,GAC3B,WAAW,CAAC,WAAW,CAAC,CAK1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC9B,GAAG,EAAE,eAAe,EACpB,IAAI,CAAC,EAAE,sBAAsB,GAC3B,WAAW,CAAC,WAAW,CAAC,CAK1B"}

package/dist/plugins/relations/facade.d.cts

@@ -0,0 +1,73 @@
+import { EntityID } from '../../core/ecs/entity.cjs';
+import { OnDeleteTarget, RelationDef, RelationOptions } from '../../core/ecs/relation.cjs';
+import { RelationService } from './relation_service.cjs';
+/** Relations, sparse `(relation, target)` pairs and hierarchy traversal.
+ * Add, remove and re-target cause no archetype
+ * transition. Ops are immediate and safe mid-tick. Traversal and wildcard
+ * reads are cold-path. */
+export declare class ECSRelations {
+    private readonly _service;
+    /** @internal constructed by the relations plugin. */
+    constructor(service: RelationService);
+    /** Register a relation kind. Exclusive (default) stores one target per
+     * source. `{ multi: true }` stores a target set per source.
+     * `{ onDeleteTarget: "delete" | "clear" | "orphan" }` selects target-death
+     * cleanup (default `orphan`).
+     *
+     * The overloads stamp the cardinality into the handle type:
+     * the exclusive-only surfaces (`targetOf`, `ancestorsOf`, `rootOf`,
+     * `cascadeOf` and `Query.hierarchy`) accept only `RelationDef<"exclusive">`,
+     * so passing a `{ multi: true }` relation is a compile error. A
+     * dynamically-built options value falls to the erased overload and keeps
+     * the runtime check as its only guard. */
+    register(opts?: {
+        readonly exclusive?: true;
+        readonly multi?: false;
+        readonly onDeleteTarget?: OnDeleteTarget;
+    }): RelationDef<"exclusive">;
+    register(opts: {
+        readonly multi: true;
+        readonly exclusive?: false;
+        readonly onDeleteTarget?: OnDeleteTarget;
+    }): RelationDef<"multi">;
+    register(opts?: RelationOptions): RelationDef;
+    /** Count of registered relations. */
+    get count(): number;
+    /** Add a `(R, tgt)` pair to `src`. Exclusive replaces the existing target
+     * multi adds to the set. No archetype transition. */
+    add(src: EntityID, def: RelationDef, tgt: EntityID): this;
+    /** Remove a `(R, tgt)` pair from `src`. For multi, omitting `tgt` removes
+     * all of `src`'s targets. No archetype transition. */
+    remove(src: EntityID, def: RelationDef, tgt?: EntityID): this;
+    /** Whether `src` holds any pair under `R`. */
+    has(src: EntityID, def: RelationDef): boolean;
+    /** The single target of `src` under an exclusive relation, or `undefined`. */
+    targetOf(src: EntityID, def: RelationDef<"exclusive">): EntityID | undefined;
+    /** All targets of `src` under `R`, ascending by id. */
+    targetsOf(src: EntityID, def: RelationDef): EntityID[];
+    /** Sources pointing at `tgt` under `R` (the reverse index), ascending by id.
+     * `(entity, def)` order, matching `targetOf` and `targetsOf`. */
+    sourcesOf(tgt: EntityID, def: RelationDef): EntityID[];
+    /** All `(source, target)` pairs of relation `R`, the `(R, *)` wildcard.
+     * Sources in canonical entity-index order. Cold path. */
+    pairsOf(def: RelationDef): readonly (readonly [EntityID, EntityID])[];
+    /** Every `(relation, source)` pointing at `tgt`, across all relation kinds,
+     * the `(*, T)` wildcard. Ordered by relation id then source id. */
+    sourcesOfAny(tgt: EntityID): readonly (readonly [RelationDef, EntityID])[];
+    /** Walk relation `R` up from `src` to its chain root, returning
+     * `[src, parent, …, root]` (nearest-ancestor-first). Exclusive only. */
+    ancestorsOf(src: EntityID, def: RelationDef<"exclusive">): EntityID[];
+    /** The root of `src`'s `R`-chain (`src` itself when it has no target).
+     * Exclusive only. */
+    rootOf(src: EntityID, def: RelationDef<"exclusive">): EntityID;
+    /** Walk relation `R` down from `root` over the reverse index, returning the
+     * subtree (including `root`) breadth-first, parents before children (the
+     * `cascade` order). Exclusive only. */
+    cascadeOf(root: EntityID, def: RelationDef<"exclusive">): EntityID[];
+    /** Reclaim relation reverse-index memory: drop every reverse entry whose
+     * target has been destroyed, returning the total dropped. Purely
+     * cold-path, no observable state change, call it at a scene boundary or at
+     * a snapshot boundary. */
+    compact(): number;
+}
+//# sourceMappingURL=facade.d.ts.map

package/dist/plugins/relations/facade.d.ts

@@ -0,0 +1,73 @@
+import { EntityID } from '../../core/ecs/entity.js';
+import { OnDeleteTarget, RelationDef, RelationOptions } from '../../core/ecs/relation.js';
+import { RelationService } from './relation_service.js';
+/** Relations, sparse `(relation, target)` pairs and hierarchy traversal.
+ * Add, remove and re-target cause no archetype
+ * transition. Ops are immediate and safe mid-tick. Traversal and wildcard
+ * reads are cold-path. */
+export declare class ECSRelations {
+    private readonly _service;
+    /** @internal constructed by the relations plugin. */
+    constructor(service: RelationService);
+    /** Register a relation kind. Exclusive (default) stores one target per
+     * source. `{ multi: true }` stores a target set per source.
+     * `{ onDeleteTarget: "delete" | "clear" | "orphan" }` selects target-death
+     * cleanup (default `orphan`).
+     *
+     * The overloads stamp the cardinality into the handle type:
+     * the exclusive-only surfaces (`targetOf`, `ancestorsOf`, `rootOf`,
+     * `cascadeOf` and `Query.hierarchy`) accept only `RelationDef<"exclusive">`,
+     * so passing a `{ multi: true }` relation is a compile error. A
+     * dynamically-built options value falls to the erased overload and keeps
+     * the runtime check as its only guard. */
+    register(opts?: {
+        readonly exclusive?: true;
+        readonly multi?: false;
+        readonly onDeleteTarget?: OnDeleteTarget;
+    }): RelationDef<"exclusive">;
+    register(opts: {
+        readonly multi: true;
+        readonly exclusive?: false;
+        readonly onDeleteTarget?: OnDeleteTarget;
+    }): RelationDef<"multi">;
+    register(opts?: RelationOptions): RelationDef;
+    /** Count of registered relations. */
+    get count(): number;
+    /** Add a `(R, tgt)` pair to `src`. Exclusive replaces the existing target
+     * multi adds to the set. No archetype transition. */
+    add(src: EntityID, def: RelationDef, tgt: EntityID): this;
+    /** Remove a `(R, tgt)` pair from `src`. For multi, omitting `tgt` removes
+     * all of `src`'s targets. No archetype transition. */
+    remove(src: EntityID, def: RelationDef, tgt?: EntityID): this;
+    /** Whether `src` holds any pair under `R`. */
+    has(src: EntityID, def: RelationDef): boolean;
+    /** The single target of `src` under an exclusive relation, or `undefined`. */
+    targetOf(src: EntityID, def: RelationDef<"exclusive">): EntityID | undefined;
+    /** All targets of `src` under `R`, ascending by id. */
+    targetsOf(src: EntityID, def: RelationDef): EntityID[];
+    /** Sources pointing at `tgt` under `R` (the reverse index), ascending by id.
+     * `(entity, def)` order, matching `targetOf` and `targetsOf`. */
+    sourcesOf(tgt: EntityID, def: RelationDef): EntityID[];
+    /** All `(source, target)` pairs of relation `R`, the `(R, *)` wildcard.
+     * Sources in canonical entity-index order. Cold path. */
+    pairsOf(def: RelationDef): readonly (readonly [EntityID, EntityID])[];
+    /** Every `(relation, source)` pointing at `tgt`, across all relation kinds,
+     * the `(*, T)` wildcard. Ordered by relation id then source id. */
+    sourcesOfAny(tgt: EntityID): readonly (readonly [RelationDef, EntityID])[];
+    /** Walk relation `R` up from `src` to its chain root, returning
+     * `[src, parent, …, root]` (nearest-ancestor-first). Exclusive only. */
+    ancestorsOf(src: EntityID, def: RelationDef<"exclusive">): EntityID[];
+    /** The root of `src`'s `R`-chain (`src` itself when it has no target).
+     * Exclusive only. */
+    rootOf(src: EntityID, def: RelationDef<"exclusive">): EntityID;
+    /** Walk relation `R` down from `root` over the reverse index, returning the
+     * subtree (including `root`) breadth-first, parents before children (the
+     * `cascade` order). Exclusive only. */
+    cascadeOf(root: EntityID, def: RelationDef<"exclusive">): EntityID[];
+    /** Reclaim relation reverse-index memory: drop every reverse entry whose
+     * target has been destroyed, returning the total dropped. Purely
+     * cold-path, no observable state change, call it at a scene boundary or at
+     * a snapshot boundary. */
+    compact(): number;
+}
+//# sourceMappingURL=facade.d.ts.map

package/dist/plugins/relations/facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../../../src/plugins/relations/facade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;KASK;AAEL,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC5F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;0BAG0B;AAC1B,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,qDAAqD;gBACzC,OAAO,EAAE,eAAe;IAIpC;;;;;;;;;;8CAU0C;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE;QACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;QAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;QACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;KACzC,GAAG,WAAW,CAAC,WAAW,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE;QACrB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;QACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC;QAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;KACzC,GAAG,WAAW,CAAC,OAAO,CAAC;IACjB,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,WAAW;IAKpD,qCAAqC;IACrC,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED;yDACqD;IAC9C,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI;IAKhE;0DACsD;IAC/C,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,IAAI;IAKpE,8CAA8C;IACvC,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO;IAIpD,8EAA8E;IACvE,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG,QAAQ,GAAG,SAAS;IAInF,uDAAuD;IAChD,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,GAAG,QAAQ,EAAE;IAI7D;qEACiE;IAC1D,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,GAAG,QAAQ,EAAE;IAI7D;6DACyD;IAClD,OAAO,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE;IAI5E;uEACmE;IAC5D,YAAY,CAAC,GAAG,EAAE,QAAQ,GAAG,SAAS,CAAC,SAAS,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,EAAE;IAIjF;4EACwE;IACjE,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG,QAAQ,EAAE;IAI5E;yBACqB;IACd,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG,QAAQ;IAIrE;;2CAEuC;IAChC,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG,QAAQ,EAAE;IAI3E;;;8BAG0B;IACnB,OAAO,IAAI,MAAM;CAGxB"}

package/dist/plugins/relations/index.d.cts

@@ -0,0 +1,11 @@
+import { ECSRelations } from './facade.cjs';
+import { Plugin } from '../../core/ecs/plugin.cjs';
+export { ECSRelations } from './facade.cjs';
+export { registerIsA, registerChildOf, type BuiltinRelationOptions } from './builtin_relations.cjs';
+/** The world surface this plugin adds. */
+export interface RelationsPlugin {
+    readonly relations: ECSRelations;
+}
+/** The relations plugin, for `ECS.create({ plugins: [relations()] })`. */
+export declare function relations(): Plugin<RelationsPlugin>;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/relations/index.d.ts

@@ -0,0 +1,11 @@
+import { ECSRelations } from './facade.js';
+import { Plugin } from '../../core/ecs/plugin.js';
+export { ECSRelations } from './facade.js';
+export { registerIsA, registerChildOf, type BuiltinRelationOptions } from './builtin_relations.js';
+/** The world surface this plugin adds. */
+export interface RelationsPlugin {
+    readonly relations: ECSRelations;
+}
+/** The relations plugin, for `ECS.create({ plugins: [relations()] })`. */
+export declare function relations(): Plugin<RelationsPlugin>;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/relations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/relations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;KAkBK;AAGL,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,uBAAuB,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAEhG,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;CACjC;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,IAAI,MAAM,CAAC,eAAe,CAAC,CAUnD"}

package/dist/{core/ecs → plugins/relations}/relation_service.d.cts

@@ -1,134 +1,122 @@
-import { BitSet, TypedArrayTag } from '../../type_primitives/index.cjs';
-import { Archetype } from './archetype.cjs';
-import { EntityID } from './entity.cjs';
-import { RelationDef, RelationOptions, RelationStore } from './relation.cjs';
-import { SparseComponentDef, SparseComponentID, SparseComponentStore } from './sparse_store.cjs';
-/** 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;
+import { BitSet } from '../../type_primitives/index.cjs';
+import { Archetype } from '../../core/ecs/archetype.cjs';
+import { QueryTerms } from '../../core/ecs/query_terms.cjs';
+import { EntityID } from '../../core/ecs/entity.cjs';
+import { RelationDef, RelationHooks, RelationOptions, RelationServiceHost } from '../../core/ecs/relation.cjs';
+import { RelationStore } from './relation_store.cjs';
+import { SparseComponentID } from '../../core/ecs/sparse_store.cjs';
+export declare class RelationService implements RelationHooks {
+    private readonly _host;
+    private readonly _relations;
     private _hasTargetCleanup;
-    private readonly _hierarchyRadixOut;
+    private _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. */
+    constructor(_host: RelationServiceHost);
+    /** The registry, indexed by RelationID, the read-only view the Store's
+     * `stateHash`, snapshot and 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). */
+    /** Whether any relation registered a non-`orphan` `onDeleteTarget` policy,
+     * the destroy paths' gate for `cleanupTarget`. */
     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
+     * forward index rides the sparse store and inherits query membership,
+     * `stateHash` + snapshot and restore 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`.
+     * is destroyed, `delete` (cascade-destroy sources), `clear` (drop the link,
+     * sources survive), or `orphan` (default: leave it dangling). See
+     * `relation_store.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). */
+     * drive forward and membership rows directly, the cardinality-specific
+     * interaction belongs to `ExclusiveRelationStore` and `MultiRelationStore`, not to a
+     * branch here. */
     registerRelation(opts?: RelationOptions): RelationDef;
-    private relationOf;
+    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). */
+     * `DEV` and is a no-op in production, symmetric, so a production build
+     * never links a reverse-index entry keyed by a destroyed handle. */
     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
+     * targets. Passing one removes only 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. */
+    /** 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. */
+     * 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
+    /** All `(source, target)` pairs of relation `R`, the `(R, *)` wildcard.
+     * Sources are emitted in **canonical entity-index order** (the
      * 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`. */
+     * `forEachCanonicalTargetSet` traversal that `stateHash` and
+     * `snapshotRelations` use. A multi source's targets follow ascending by id.
+     * Empty when the relation holds no pairs. Cold path, it allocates the result
+     * array, and for multi it sorts each source's target set. Not for per-tick
+     * use. The point-query forms are `targetOf` and `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
+     * relation kinds, the `(*, T)` wildcard. 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
+    /** The backing sparse component id of relation `R`, the membership store a
+     * `(R, *)` wildcard term (`Query.andRelation`) 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
+     * 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. */
+     * 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 `sparseIncludes` 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,
+     * dense mask, its sparse require and exclude terms, and 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`
+     * 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
+     * canonical `(*, T)` order matching `sourcesOf` and `sourcesOfAny` (which sort
+     * the same way). Cold and structural, not a per-tick hot loop over many targets.
+     * `sparseIncludes` and `sparseExcludes` 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;
+    forEachTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, terms: QueryTerms, 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
+     * relations. 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.
+     * 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
+     * folded), and the dropped entries are faithfully rebuilt by snapshot and restore
+     * from the surviving forward links (the snapshot plugin's
+     * `_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.
+     * 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
@@ -136,34 +124,34 @@ export declare class RelationService {
      * 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
+     * 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
+     * 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`
+     * 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
+    /** 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
+     * 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
+     * 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
+     * (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
+    /** 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
@@ -171,64 +159,64 @@ export declare class RelationService {
      * 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`. */
+     * `OnDeleteTarget` policy. 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
+     * `targetId`. 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'
+     *  - **`delete`**, append each source to `cascade`. The caller destroys them
+     *    through the same path, so chains and 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
+     *  - **`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
+     *    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
+    /** A query-match path: yield the matched entities, the exact
+     * sparse-match intersection (dense mask, sparse require and exclude, and 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
+     * `.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 whole batch, so a shared or 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
+     * The canonical order is produced without a comparator sort, which is far
+     * slower: (1) collect the matched ids via
+     * the host's `forEachSparseMatch`, (2) `radixSortByIndex` → entity-index
+     * ascending, and (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
+     * churns no histograms. The working set (`matched`, `buckets`, `depthMemo`
+     * and `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;
+     * Exclusive-only, a multi relation throws `RELATION_MODE_MISMATCH` in `DEV`
+     * (mirrors `cascadeOf` and `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, terms: QueryTerms, denseArchetypes: readonly Archetype[], relation: RelationDef, maxDepth: number, 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
+     * already-memoised node, or a dangling or 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;
 }