@oasys/oecs 0.4.0 → 0.5.0

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

@@ -0,0 +1,243 @@
+import { Brand } from '../../type_primitives/index.cjs';
+import { EntityID } from './entity.cjs';
+import { SparseComponentDef, SparseComponentStore } from './sparse_store.cjs';
+/** Relation handle id. A separate id space from `ComponentID` and
+ * `SparseComponentID` — it indexes the `RelationService` registry. The numeric
+ * value is the registration order, stable for the lifetime of the ECS. */
+export type RelationID = Brand<number, "relation_id">;
+declare const __relationBrand: unique symbol;
+/** A relation's registration-time cardinality: `exclusive` = one target per
+ * source (re-add replaces), `multi` = a target set per source. */
+export type RelationCardinality = "exclusive" | "multi";
+declare const __relationCardinality: unique symbol;
+export type RelationDef<C extends RelationCardinality = RelationCardinality> = RelationID & {
+    readonly [__relationBrand]: "relation";
+    readonly [__relationCardinality]?: [C];
+};
+/** Access sentinel for the `(*, T)` wildcard query iteration
+ * (`Query.forEachRelatedTo`, #579). A `(*, T)` term reads **every** registered
+ * relation's reverse index to find sources of `T`, so it can't name a specific
+ * relation in `relationReads` the way `withRelation(R)` (`(R, *)`) can. A
+ * system that iterates a `(*, T)` wildcard lists `ANY_RELATION` in `relationReads`
+ * instead; `accessCheck.checkRelationReadAny` honors it. The numeric value is a
+ * reserved sentinel far past any real registration-order relation id (relations are
+ * minted from 0 upward), so it can never collide with a registered relation. */
+export declare const ANY_RELATION: RelationDef;
+/** Cleanup policy applied to a relation's **sources** when one of its
+ * **targets** is destroyed (#473). Chosen per-relation at registration, run at
+ * destroy-flush (and the immediate-destroy path) off the reverse index:
+ *
+ *   - **`delete`** — cascade: destroy every source of the dead target too,
+ *     recursively for chains/trees (the canonical ChildOf case).
+ *   - **`clear`** — remove the relation from every source; the sources survive.
+ *   - **`orphan`** — leave the link intact but dangling. Reads stay safe (the
+ *     reverse index is `EntityID`-keyed, so the dead handle never aliases a
+ *     recycled slot); `targetOf` returns a dead handle until the source
+ *     re-targets or is removed. This is the pre-#473 behaviour and the default.
+ */
+export type OnDeleteTarget = "delete" | "clear" | "orphan";
+/** Default on-target-delete policy: leave the link dangling (pre-#473
+ * behaviour, zero change for callers that don't opt in). */
+export declare const DEFAULT_ON_DELETE_TARGET: OnDeleteTarget;
+/** Registration options. `exclusive` (one target per source) is the default;
+ * pass `{ multi: true }` for a multi-target relation. The two are mutually
+ * exclusive — the union makes `{ exclusive: true, multi: true }` a compile
+ * error (it also throws at runtime, for JS callers). `onDeleteTarget` selects
+ * the cleanup policy applied to sources when a target is destroyed (default
+ * `orphan`). */
+export type RelationOptions = {
+    readonly exclusive?: true;
+    readonly multi?: false;
+    readonly onDeleteTarget?: OnDeleteTarget;
+} | {
+    readonly multi: true;
+    readonly exclusive?: false;
+    readonly onDeleteTarget?: OnDeleteTarget;
+};
+/** Field name carrying the target `EntityID` on an exclusive relation's backing
+ * sparse component. Field 0 of a single-field schema. */
+export declare const RELATION_TARGET_FIELD = "target";
+/** Receives one canonical `(source index, sorted targets)` set during a fold
+ * over a multi relation's forward sets. Targets are ascending by id; empty sets
+ * are never yielded (see `forEachCanonicalTargetSet`). */
+export type CanonicalTargetSetFn = (sourceIndex: number, targets: readonly EntityID[]) => void;
+/** Receives one canonical `(source, target)` pair during a fold over a
+ * relation's forward links. Sources ascend by entity index, each source's
+ * targets ascend by id — the #470 determinism order. */
+export type CanonicalPairFn = (source: EntityID, target: EntityID) => void;
+/** Maps a source entity **index** to its full `EntityID` (generation from the
+ * live slot). Supplied by `Store`, which owns entity generations. */
+export type MakeSourceID = (index: number) => EntityID;
+/** One relation's derived side state. **Abstract over cardinality (#498):** the
+ * base owns the cardinality-agnostic **reverse index** (target → sources, keyed
+ * by full `EntityID` so a recycled slot can't alias a dead target's sources) and
+ * a handle on the backing `SparseComponentStore`; the forward representation and
+ * its sparse interaction are owned by the concrete `ExclusiveRelationStore` /
+ * `MultiRelationStore` (built by `makeRelationStore`).
+ *
+ * The registry level (`Store` + `RelationService`) owns what is genuinely its
+ * own — entity liveness, registration, and destroy orchestration — and drives
+ * a relation through the virtual `link` /
+ * `unlink` / `purgeSource` / `forEachCanonicalPair` / … without ever
+ * branching on cardinality. Each cardinality keeps forward link + reverse index
+ * + sparse membership in lockstep inside one method on one class, so the
+ * lockstep can't be broken by missing a scattered `if (rs.exclusive)` site. */
+export declare abstract class RelationStore {
+    /** `true` → one target per source (target in the sparse field); `false` →
+     * a set of targets per source. The cardinality discriminant survives as a
+     * field because it is part of the snapshot header and the traversal/`targetOf`
+     * mode guards — but the forward *mechanics* are virtual, not branched on it. */
+    readonly exclusive: boolean;
+    /** Backing sparse component def: `{ target: f64 }` when exclusive, a tag when
+     * multi. Carries membership (and the target, when exclusive). */
+    readonly sparse: SparseComponentDef;
+    /** Cleanup policy applied to this relation's sources when a target is
+     * destroyed (#473). `orphan` (the default) is a no-op — the link dangles
+     * safely. `Store` reads this at destroy-flush off `sourcesOf`. */
+    readonly onDeleteTarget: OnDeleteTarget;
+    /** The backing sparse store instance. Owned for registration/liveness by
+     * `Store`, but the relation drives the forward/membership rows on it directly
+     * — that is the cardinality interaction this class now encapsulates (#498). */
+    protected readonly _store: SparseComponentStore;
+    /** target `EntityID` → set of source `EntityID`s. Keyed by the full id, not
+     * the index, so a recycled target slot can't alias a dead target's sources.
+     * An entry is dropped the moment its set empties (`unlinkReverse`). */
+    private readonly _reverse;
+    constructor(exclusive: boolean, sparse: SparseComponentDef, store: SparseComponentStore, onDeleteTarget: OnDeleteTarget);
+    /** Record that `src` points at `tgt` in the reverse index. */
+    protected linkReverse(tgt: EntityID, src: EntityID): void;
+    /** Drop the `src → tgt` edge from the reverse index, removing the target's
+     * entry entirely once its last source is gone (so a dead-target key doesn't
+     * linger with an empty set). */
+    protected unlinkReverse(tgt: EntityID, src: EntityID): void;
+    /** Drop every reverse-index entry whose **target** is no longer alive,
+     * returning the count dropped (#491). The `orphan` policy intentionally
+     * leaves a destroyed target's reverse entry intact (the link dangles
+     * safely), so a long-lived source that orphan-points at a stream of
+     * short-lived targets and never re-targets/dies accumulates dead-target keys
+     * without bound. This is the reclaim primitive behind `Store.compactRelations`
+     * — a cold path the host calls at scene/snapshot boundaries. It is
+     * cardinality-free (reverse-index only), so it lives on the base unchanged.
+     *
+     * Pure index reclaim: the **forward** links (the exclusive sparse target
+     * field, the multi forward set) are left untouched, so `targetOf` /
+     * `targetsOf` still return the dangling dead handle exactly as `orphan`
+     * promises. The reverse index is derived, so dropping a dead-target entry
+     * changes nothing observable except `sourcesOf` on that dead handle (which
+     * goes from the dangling sources to `[]` — meaningless either way, the target
+     * is gone) and is faithfully rebuilt by snapshot/restore from the surviving
+     * forward links. Only the **target** role can leak here: a destroyed *source*
+     * is already unlinked from every reverse set by `purgeSource`, so a live
+     * target's set never holds a dead source. `isAlive` is supplied by `Store`,
+     * which owns entity liveness. Deleting during `Map` key iteration is
+     * well-defined — already-visited and not-yet-reached keys are unaffected. */
+    pruneDeadReverse(isAlive: (id: EntityID) => boolean): number;
+    /** Sources that point at `tgt`, ascending by id (deterministic, cold-path
+     * sort) — empty when none. */
+    sourcesOf(tgt: EntityID): EntityID[];
+    /** Drop every derived side index — the reverse index and (for multi) the
+     * forward target sets. Restore path only (`restoreRelations`): the side
+     * indices are rebuilt from scratch, so they're cleared first to stay
+     * idempotent when restoring into a dirty world. The backing sparse store is
+     * cleared separately by `restoreSparseStores`. */
+    resetIndices(): void;
+    /** Clear this relation's forward representation (multi: the side map;
+     * exclusive: nothing — its forward links live in the sparse store, cleared by
+     * `restoreSparseStores`). */
+    protected abstract _resetForward(): void;
+    /** Add a `(R, tgt)` link from `src`, keeping forward link + membership +
+     * reverse index in lockstep. Exclusive: replaces any existing target
+     * (idempotent if `tgt` is already the target). Multi: adds to the set
+     * (idempotent on a duplicate), establishing the membership tag on the first
+     * target. `src` must be live — `Store` checks before delegating (#495). */
+    abstract link(src: EntityID, tgt: EntityID): void;
+    /** Remove `(R, tgt)` from `src` — or, when `tgt` is omitted, every target of
+     * `src` — keeping forward link + membership + reverse index in lockstep. A
+     * no-op when the link isn't present. */
+    abstract unlink(src: EntityID, tgt?: EntityID): void;
+    /** Purge a destroyed **source**: drop its forward link(s) and unlink it from
+     * every target's reverse set, but leave the sparse **membership** row alone —
+     * `Store._purgeSparse` drops that (for every store) right after, so this
+     * runs first and must not double-remove. */
+    abstract purgeSource(src: EntityID): void;
+    /** The single target of source `index`, or `undefined`. Exclusive reads the
+     * sparse field; multi has no single target and returns `undefined` (matching
+     * the production `targetOf`-on-multi read, which the `DEV` guard rejects). */
+    abstract singleTarget(index: number): EntityID | undefined;
+    /** All targets of source `index`, ascending by id — one or zero for
+     * exclusive, the full sorted set for multi. The symmetric counterpart to
+     * `sourcesOf` (#498 item 4). */
+    abstract targetsOf(index: number): EntityID[];
+    /** Whether source `index` holds any target under this relation (sparse
+     * membership). */
+    abstract has(index: number): boolean;
+    /** Fold `cb` over this relation's **multi** forward target sets in canonical
+     * order (sources ascending by index, each source's targets ascending by id),
+     * skipping empty sets. The single source of truth for the canonical multi
+     * traversal shared by `stateHash`, `snapshotRelations`, and `pairsOf`
+     * (#498 item 1). Exclusive relations contribute via the sparse store, so this
+     * is a no-op for them. */
+    abstract forEachCanonicalTargetSet(cb: CanonicalTargetSetFn): void;
+    /** Fold `cb` over every `(source, target)` pair of this relation in canonical
+     * order — the `(R, *)` wildcard drive order (#472). `makeId` maps a source
+     * index to its full `EntityID`. Exclusive rides the backing store's
+     * `canonicalIndices`; multi rides `forEachCanonicalTargetSet`. */
+    abstract forEachCanonicalPair(makeId: MakeSourceID, cb: CanonicalPairFn): void;
+    /** Rebuild the reverse index from the forward links after a restore.
+     * Exclusive reads it back from the just-restored sparse target field (the
+     * reverse index is never serialized); multi already rebuilt its reverse edges
+     * in `restoreAddTarget`, so this is a no-op for it. `makeId` maps a source
+     * index to its full `EntityID`. */
+    abstract rebuildReverseFromForward(makeId: MakeSourceID): void;
+    /** Restore one decoded multi forward edge `(source index → tgt)` plus its
+     * reverse edge (the source's full `EntityID` is `src`). Multi only — the
+     * snapshot header guards exclusive relations out before this is reached, so
+     * the exclusive override throws defensively. */
+    abstract restoreAddTarget(index: number, tgt: EntityID, src: EntityID): void;
+}
+/** Build the right `RelationStore` for a cardinality. The only construction
+ * site is `Store.registerRelation`, which resolves the backing sparse store and
+ * hands it in so the relation can drive forward/membership rows directly. */
+export declare function makeRelationStore(exclusive: boolean, sparse: SparseComponentDef, store: SparseComponentStore, onDeleteTarget: OnDeleteTarget): RelationStore;
+/** Serialize the relation side data that does **not** live in the sparse store
+ * — i.e. each **multi** relation's forward target sets (`Map<source index,
+ * Set<target>>`). Exclusive relations store their target in the backing sparse
+ * field, so they ride `snapshotSparseStores` and contribute only a header
+ * here. The reverse index is fully derivable (from the sparse store for
+ * exclusive, from these sets for multi), so it is never serialized — it is
+ * rebuilt by `restoreRelations` + the caller's exclusive-reverse pass.
+ *
+ * Members are emitted in canonical order (sources ascending by entity index,
+ * each source's targets ascending by id) so the bytes are independent of
+ * add/remove history — the same byte-level determinism invariant the sparse
+ * snapshot holds (#470). Layout (integers little-endian):
+ *
+ *   u32 relationCount
+ *   repeat relationCount times (registration / id order):
+ *     u32 isMulti
+ *     if multi:
+ *       u32 sourceCount
+ *       repeat sourceCount times (ascending source index):
+ *         u32 sourceIndex
+ *         u32 targetCount
+ *         f64 × targetCount   (target EntityIDs, ascending) */
+export declare function snapshotRelations(relations: readonly RelationStore[]): Uint8Array;
+/** Rebuild every relation's side indices from a `snapshotRelations` buffer and
+ * the already-restored sparse stores. Each relation's indices are reset first
+ * (idempotent into a dirty world), then:
+ *
+ *  - **multi** — forward target sets and their reverse edges are rebuilt from
+ *    `bytes` (the sets aren't in the sparse store, so the bytes are the only
+ *    source). `makeId` maps a source entity index to its full `EntityID`
+ *    (generation from the live slot) so reverse edges key correctly.
+ *  - **exclusive** — only the reset happens here; the reverse index is rebuilt
+ *    by the caller from the backing sparse store (which already round-tripped
+ *    through `restoreSparseStores`), since this function can't read it.
+ *
+ * Throws `SparseRestoreError` on any shape mismatch (relation count, an
+ * exclusive/multi flag that disagrees with the registered relation, a multi
+ * source index past `MAX_INDEX`, or a truncated / over-long buffer) rather than
+ * silently building a corrupt index. */
+export declare function restoreRelations(relations: readonly RelationStore[], bytes: Uint8Array, makeId: (index: number) => EntityID): void;
+export {};
+//# sourceMappingURL=relation.d.ts.map

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

@@ -1,13 +1,18 @@
-import { Brand } from '../../type_primitives';
-import { EntityID } from './entity';
-import { SparseComponentDef, SparseComponentStore } from './sparse_store';
+import { Brand } from '../../type_primitives/index.js';
+import { EntityID } from './entity.js';
+import { SparseComponentDef, SparseComponentStore } from './sparse_store.js';
 /** Relation handle id. A separate id space from `ComponentID` and
- * `SparseComponentID` — it indexes `Store`'s relation registry. The numeric
+ * `SparseComponentID` — it indexes the `RelationService` registry. The numeric
  * value is the registration order, stable for the lifetime of the ECS. */
 export type RelationID = Brand<number, "relation_id">;
 declare const __relationBrand: unique symbol;
-export type RelationDef = RelationID & {
+/** A relation's registration-time cardinality: `exclusive` = one target per
+ * source (re-add replaces), `multi` = a target set per source. */
+export type RelationCardinality = "exclusive" | "multi";
+declare const __relationCardinality: unique symbol;
+export type RelationDef<C extends RelationCardinality = RelationCardinality> = RelationID & {
     readonly [__relationBrand]: "relation";
+    readonly [__relationCardinality]?: [C];
 };
 /** Access sentinel for the `(*, T)` wildcard query iteration
  * (`Query.forEachRelatedTo`, #579). A `(*, T)` term reads **every** registered
@@ -36,13 +41,19 @@ export type OnDeleteTarget = "delete" | "clear" | "orphan";
 export declare const DEFAULT_ON_DELETE_TARGET: OnDeleteTarget;
 /** Registration options. `exclusive` (one target per source) is the default;
  * pass `{ multi: true }` for a multi-target relation. The two are mutually
- * exclusive — passing both throws. `onDeleteTarget` selects the cleanup
- * policy applied to sources when a target is destroyed (default `orphan`). */
-export interface RelationOptions {
-    readonly exclusive?: boolean;
-    readonly multi?: boolean;
+ * exclusive — the union makes `{ exclusive: true, multi: true }` a compile
+ * error (it also throws at runtime, for JS callers). `onDeleteTarget` selects
+ * the cleanup policy applied to sources when a target is destroyed (default
+ * `orphan`). */
+export type RelationOptions = {
+    readonly exclusive?: true;
+    readonly multi?: false;
     readonly onDeleteTarget?: OnDeleteTarget;
-}
+} | {
+    readonly multi: true;
+    readonly exclusive?: false;
+    readonly onDeleteTarget?: OnDeleteTarget;
+};
 /** Field name carrying the target `EntityID` on an exclusive relation's backing
  * sparse component. Field 0 of a single-field schema. */
 export declare const RELATION_TARGET_FIELD = "target";
@@ -64,8 +75,9 @@ export type MakeSourceID = (index: number) => EntityID;
  * its sparse interaction are owned by the concrete `ExclusiveRelationStore` /
  * `MultiRelationStore` (built by `makeRelationStore`).
  *
- * `Store` owns what is genuinely its own — entity liveness, registration, and
- * destroy orchestration — and drives a relation through the virtual `link` /
+ * The registry level (`Store` + `RelationService`) owns what is genuinely its
+ * own — entity liveness, registration, and destroy orchestration — and drives
+ * a relation through the virtual `link` /
  * `unlink` / `purgeSource` / `forEachCanonicalPair` / … without ever
  * branching on cardinality. Each cardinality keeps forward link + reverse index
  * + sparse membership in lockstep inside one method on one class, so the
@@ -150,7 +162,7 @@ export declare abstract class RelationStore {
     abstract purgeSource(src: EntityID): void;
     /** The single target of source `index`, or `undefined`. Exclusive reads the
      * sparse field; multi has no single target and returns `undefined` (matching
-     * the production `targetOf`-on-multi read, which the `__DEV__` guard rejects). */
+     * the production `targetOf`-on-multi read, which the `DEV` guard rejects). */
     abstract singleTarget(index: number): EntityID | undefined;
     /** All targets of source `index`, ascending by id — one or zero for
      * exclusive, the full sorted set for multi. The symmetric counterpart to

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

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

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

@@ -0,0 +1,235 @@
+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;
+    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