@oasys/oecs 0.5.3 → 0.6.0

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

@@ -1,134 +1,122 @@
-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;
+import { BitSet } from '../../type_primitives/index.js';
+import { Archetype } from '../../core/ecs/archetype.js';
+import { QueryTerms } from '../../core/ecs/query_terms.js';
+import { EntityID } from '../../core/ecs/entity.js';
+import { RelationDef, RelationHooks, RelationOptions, RelationServiceHost } from '../../core/ecs/relation.js';
+import { RelationStore } from './relation_store.js';
+import { SparseComponentID } from '../../core/ecs/sparse_store.js';
+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;
 }

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

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

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

@@ -0,0 +1,177 @@
+import { EntityID } from '../../core/ecs/entity.cjs';
+import { SparseComponentDef, SparseComponentStore } from '../../core/ecs/sparse_store.cjs';
+import { CanonicalPairFn, CanonicalTargetSetFn, MakeSourceID, OnDeleteTarget, RelationStoreView } from '../../core/ecs/relation.cjs';
+/** One relation's derived side state. **Abstract over cardinality:** 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` and
+ * `MultiRelationStore` (built by `createRelationStore`).
+ *
+ * The registry level (`Store` and `RelationService`) owns what is genuinely its
+ * own, entity liveness, registration, and destroy orchestration, and drives
+ * a relation through the virtual `link`,
+ * `unlink`, `purgeSource`, `forEachCanonicalPair` and their peers, without ever
+ * branching on cardinality. Each cardinality keeps the forward link, the reverse
+ * index and the 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 implements RelationStoreView {
+    /** `true` → one target per source, held in the sparse field. `false` →
+     * a set of targets per source. The cardinality discriminant survives as a
+     * field because the snapshot header and the traversal and `targetOf`
+     * mode guards carry it. The forward mechanics stay virtual, never 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. `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 and liveness by
+     * `Store`, but the relation drives the forward and membership rows on it directly.
+     * That is the cardinality interaction this class now encapsulates. */
+    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. 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 or dies accumulates dead-target keys
+     * without bound. This is the reclaim primitive behind `ecs.relations.compact`,
+     * a cold path the host calls at scene and 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` and
+     * `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 and 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 clears the side map.
+     * Exclusive clears nothing, because its forward links live in the sparse
+     * store, which `restoreSparseStores` clears. */
+    protected abstract _resetForward(): void;
+    /** Add a `(R, tgt)` link from `src`, keeping the forward link, the membership
+     * row and the 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. */
+    abstract link(src: EntityID, tgt: EntityID): void;
+    /** Remove `(R, tgt)` from `src`, or, when `tgt` is omitted, every target of
+     * `src`, keeping the forward link, the membership row and the 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 singleTargetAt(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`. */
+    abstract targetsAt(index: number): EntityID[];
+    /** Whether source `index` holds any target under this relation (sparse
+     * membership). */
+    abstract hasIndex(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`.
+     * 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. `createId` maps a source
+     * index to its full `EntityID`. Exclusive rides the backing store's
+     * `canonicalIndices`. Multi rides `forEachCanonicalTargetSet`. */
+    abstract forEachCanonicalPair(createId: MakeSourceID, cb: CanonicalPairFn): void;
+    /** Rebuild the reverse index from the forward links after a restore.
+     * Exclusive reads it back from the newly 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. `createId` maps a source
+     * index to its full `EntityID`. */
+    abstract rebuildReverse(createId: 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 and membership rows directly. */
+export declare function createRelationStore(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 and remove history, the same byte-level determinism invariant the sparse
+ * snapshot holds. Layout (integers little-endian):
+ *
+ *   u32 relationCount
+ *   repeat relationCount times (registration and 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 RelationStoreView[]): 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). `createId` 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 or multi flag that disagrees with the registered relation, a multi
+ * source index past `MAX_INDEX`, or a truncated or over-long buffer) rather than
+ * silently building a corrupt index. */
+export declare function restoreRelations(relations: readonly RelationStoreView[], bytes: Uint8Array, createId: (index: number) => EntityID): void;
+//# sourceMappingURL=relation_store.d.ts.map