@oasys/oecs 0.5.3 → 0.6.0

package/dist/plugins/relations.development.js

@@ -0,0 +1,603 @@
+import { D as M, R as k, a as L, e as w, g, c as N, U as m } from "./relation_store-RqW5Snx6.js";
+import { r as b } from "./arrays-Dr_1hCjL.js";
+import { ECSError as O, ECS_ERROR as p } from "../index.development.js";
+import { u as x } from "./assertions-gtDVfbnQ.js";
+class H {
+  constructor(e) {
+    this._host = e;
+  }
+  // Parallel array indexed by RelationID. Each entry owns a backing sparse
+  // component (membership + the target field when exclusive) plus the reverse
+  // index and multi-target forward sets. Layered on the sparse storage class,
+  // so add, remove and re-target of a pair cause no archetype transition.
+  _relations = [];
+  // True once any relation registers a non-`orphan` `onDeleteTarget` policy.
+  // Gates the target-role cleanup branch in both of the Store's
+  // destroy paths so the common case (no cleanup policies) leaves the destroy
+  // hot path untouched, mirrors the Store's `count > 0` and sparse-store gates.
+  _hasTargetCleanup = !1;
+  // Reused radix scratch for the hierarchy depth-ordering driver.
+  // The motivating use case, transform propagation, is a per-tick depth-ordered
+  // pass, so `forEachHierarchyMatch` allocating two 1024-entry histograms and
+  // an `out` array per call would be per-tick GC churn. `radixSortByIndex` fully
+  // consumes these three before any `cb` fires, so unlike
+  // the call-local `matched`, `buckets`, `depthMemo` and `visiting` (which stay
+  // live across the emit loop and would corrupt under a re-entrant callback) they
+  // are safe to share as instance state. The observers plugin keeps the same
+  // scratch privately, so this one cannot be shared with it.
+  _hierarchyRadixOut = new Uint32Array(1024);
+  _hierarchyRadixC0 = new Int32Array(1024);
+  _hierarchyRadixC1 = new Int32Array(1024);
+  /** The registry, indexed by RelationID, the read-only view the Store's
+   * `stateHash`, snapshot and restore paths iterate. */
+  get stores() {
+    return this._relations;
+  }
+  /** Number of registered relations. */
+  get count() {
+    return this._relations.length;
+  }
+  /** Whether any relation registered a non-`orphan` `onDeleteTarget` policy,
+   * the destroy paths' gate for `cleanupTarget`. */
+  get hasTargetCleanup() {
+    return this._hasTargetCleanup;
+  }
+  /** 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,
+   * `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). See
+   * `relation_store.ts`.
+   *
+   * The backing sparse store is resolved and handed to the relation so it can
+   * drive forward and membership rows directly, the cardinality-specific
+   * interaction belongs to `ExclusiveRelationStore` and `MultiRelationStore`, not to a
+   * branch here. */
+  registerRelation(e) {
+    const t = e?.multi === !0, s = e?.exclusive === !0;
+    if (t && s)
+      throw new O(
+        p.RELATION_MODE_INVALID,
+        "relations.register: a relation cannot be both exclusive and multi-target"
+      );
+    const r = !t, i = e?.onDeleteTarget ?? M, n = r ? this._host.pushSparseStore([k], ["f64"]) : this._host.pushSparseStore([], []), o = this._relations.length;
+    return this._relations.push(
+      L(r, n, this._host.sparseStoreOf(n), i)
+    ), i !== "orphan" && (this._hasTargetCleanup = !0), x(o);
+  }
+  _relationOf(e) {
+    const t = e, s = this._relations[t];
+    if (s === void 0)
+      throw new O(p.RELATION_NOT_REGISTERED, `relation ${t} is not registered`);
+    return s;
+  }
+  /** 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. */
+  addRelation(e, t, s) {
+    const r = this._relationOf(t);
+    if (!this._host.isAlive(e))
+      throw w("addRelation", e, "source");
+    if (!this._host.isAlive(s))
+      throw w("addRelation", s, "target");
+    r.link(e, s);
+  }
+  /** 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 only that pair (dropping membership when the
+   * set empties). */
+  removeRelation(e, t, s) {
+    const r = this._relationOf(t);
+    if (!this._host.isAlive(e))
+      throw w("removeRelation", e, "source");
+    r.unlink(e, s);
+  }
+  /** The single target of `src` under an exclusive relation, or `undefined`.
+   * Throws in `DEV` on a multi-target relation (use `targetsOf`). */
+  targetOf(e, t) {
+    const s = this._relationOf(t);
+    {
+      if (!s.exclusive)
+        throw new O(
+          p.RELATION_MODE_MISMATCH,
+          "targetOf: relation is multi-target, use targetsOf"
+        );
+      if (!this._host.isAlive(e)) throw w("targetOf", e);
+    }
+    return s.singleTargetAt(g(e));
+  }
+  /** All targets of `src` under `R`, one or zero for exclusive, the full set
+   * for multi, ascending by id. */
+  targetsOf(e, t) {
+    const s = this._relationOf(t);
+    if (!this._host.isAlive(e)) throw w("targetsOf", e);
+    return s.targetsAt(g(e));
+  }
+  /** Sources that point at `tgt` under `R` (the reverse index), ascending by
+   * id. Empty when none. */
+  sourcesOf(e, t) {
+    return this._relationOf(t).sourcesOf(e);
+  }
+  /** Whether `src` holds any pair under `R`. */
+  hasRelation(e, t) {
+    return this._host.hasSparse(e, this._relationOf(t).sparse);
+  }
+  /** 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 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(e) {
+    const t = this._relationOf(e), s = [], r = this._host.generations();
+    return t.forEachCanonicalPair(
+      (i) => N(i, r[i]),
+      (i, n) => s.push([i, n])
+    ), s;
+  }
+  /** Every `(relation, source)` pointing at `tgt`, across **all** registered
+   * 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(e) {
+    const t = [], s = this._relations;
+    for (let r = 0; r < s.length; r++) {
+      const i = x(r), n = s[r].sourcesOf(e);
+      for (let o = 0; o < n.length; o++) t.push([i, n[o]]);
+    }
+    return t;
+  }
+  // --- Wildcard query terms ---
+  // `(R, *)` and `(*, T)` as composable query terms (vs the cold materializing
+  // helpers `pairsOf` and `sourcesOfAny` above). Membership semantics: each
+  // matching source is yielded once. Fetch its targets on demand with
+  // `targetsOf`. Insertion order, consistent with the `andSparse` path
+  // (deterministic by construction across lockstep peers, canonical sorting is
+  // reserved for `stateHash` and for snapshot). Canonical ordering costs far
+  // more for each iteration and buys no determinism here.
+  /** 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
+   * `(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 `sparseIncludes` list. */
+  relationBackingSparseId(e) {
+    return this._relationOf(e).sparse;
+  }
+  /** Drive a `(*, T)` wildcard query (`Query.forEachRelatedTo`): every source
+   * related to `target` under **any** relation, intersected with the query's
+   * 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`
+   * 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` 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. */
+  forEachTargetMatch(e, t, s, r, i, n) {
+    const { sparseIncludes: o, sparseExcludes: l, includesDisabled: a } = i, h = this._relations;
+    if (h.length === 0) return;
+    const f = /* @__PURE__ */ new Set();
+    for (let c = 0; c < h.length; c++) {
+      const u = h[c].sourcesOf(e);
+      for (let R = 0; R < u.length; R++) f.add(u[R]);
+    }
+    if (f.size === 0) return;
+    const E = Array.from(f).sort((c, u) => c - u), y = this._host.sparseStores(), T = this._host.entityArchetypes(), _ = this._host.entityRows(), v = this._host.archetypes();
+    for (let c = 0; c < E.length; c++) {
+      const u = x(E[c]), R = g(u), C = T[R];
+      if (C === m) continue;
+      const D = v[C], S = D.mask;
+      if (!S.contains(t) || s !== null && S.overlaps(s) || r !== null && !S.overlaps(r)) continue;
+      let I = !0;
+      for (let d = 0; d < o.length; d++)
+        if (!y[o[d]].has(R)) {
+          I = !1;
+          break;
+        }
+      if (I) {
+        for (let d = 0; d < l.length; d++)
+          if (y[l[d]].has(R)) {
+            I = !1;
+            break;
+          }
+        if (I) {
+          if (!a) {
+            const d = _[R];
+            if (d !== m && d >= D.enabledCount) continue;
+          }
+          n(u);
+        }
+      }
+    }
+  }
+  /** Reclaim reverse-index memory: drop every relation's reverse entries whose
+   * **target** has been destroyed, returning the total dropped across all
+   * 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.
+   *
+   * 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 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.
+   * No-op (returns 0) when no relations are registered. */
+  compactRelations() {
+    const e = this._relations;
+    if (e.length === 0) return 0;
+    const t = (r) => this._host.isAlive(r);
+    let s = 0;
+    for (let r = 0; r < e.length; r++) s += e[r].pruneDeadReverse(t);
+    return s;
+  }
+  // --- Traversal (parent and IsA chains over an exclusive relation) ---
+  // Traversal is **exclusive-only**: an exclusive relation gives each source at
+  // most one target ("parent"), so the forward direction is a chain and the
+  // reverse index (`sourcesOf`) gives children, together a proper tree. A
+  // multi relation is a dag with no single parent chain, so these throw
+  // `RELATION_MODE_MISMATCH` in `DEV` (mirroring `targetOf`). Acyclicity
+  // is assumed. Every walk carries a visited set so a malformed (cyclic) chain
+  // is a loud `RELATION_CYCLE` in `DEV` and a safe early-out (never a hang)
+  // in production. Cold path, allocates the result array. Not for per-tick use.
+  /** 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(e, t) {
+    const s = this._relationOf(t);
+    {
+      if (!s.exclusive)
+        throw new O(
+          p.RELATION_MODE_MISMATCH,
+          "ancestorsOf: relation is multi-target, traversal needs an exclusive (parent) chain"
+        );
+      if (!this._host.isAlive(e)) throw w("ancestorsOf", e);
+    }
+    const r = this._host.sparseStoreOf(s.sparse), i = [e], n = /* @__PURE__ */ new Set([g(e)]);
+    let o = e;
+    for (; ; ) {
+      const l = r.getField(g(o), 0);
+      if (l === void 0) break;
+      const a = x(l);
+      if (!this._host.isAlive(a)) {
+        i.push(a);
+        break;
+      }
+      const h = g(a);
+      if (n.has(h))
+        throw new O(
+          p.RELATION_CYCLE,
+          `ancestorsOf: cycle in relation chain at entity index ${h}`
+        );
+      n.add(h), o = a, i.push(o);
+    }
+    return i;
+  }
+  /** 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(e, t) {
+    const s = this.ancestorsOf(e, t);
+    return s[s.length - 1];
+  }
+  /** 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(e, t) {
+    const s = this._relationOf(t);
+    {
+      if (!s.exclusive)
+        throw new O(
+          p.RELATION_MODE_MISMATCH,
+          "cascadeOf: relation is multi-target, traversal needs an exclusive (parent) chain"
+        );
+      if (!this._host.isAlive(e)) throw w("cascadeOf", e);
+    }
+    const r = [e], i = /* @__PURE__ */ new Set([g(e)]);
+    for (let n = 0; n < r.length; n++) {
+      const o = s.sourcesOf(r[n]);
+      for (let l = 0; l < o.length; l++) {
+        const a = o[l], h = g(a);
+        if (i.has(h))
+          throw new O(
+            p.RELATION_CYCLE,
+            `cascadeOf: cycle in relation chain at entity index ${h}`
+          );
+        i.add(h), r.push(a);
+      }
+    }
+    return r;
+  }
+  /** 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. Gated by the caller on `count > 0`. */
+  purgeSource(e) {
+    const t = this._relations;
+    for (let s = 0; s < t.length; s++) t[s].purgeSource(e);
+  }
+  /** Apply each relation's `OnDeleteTarget` policy for a destroyed **target**
+   * `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 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
+   *    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(e, t) {
+    const s = this._relations;
+    for (let r = 0; r < s.length; r++) {
+      const i = s[r];
+      if (i.onDeleteTarget === "orphan") continue;
+      const n = i.sourcesOf(e);
+      if (n.length !== 0) {
+        if (i.onDeleteTarget === "delete") {
+          for (let o = 0; o < n.length; o++) t.push(n[o]);
+          continue;
+        }
+        for (let o = 0; o < n.length; o++) i.unlink(n[o], e);
+      }
+    }
+  }
+  /** 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
+   * 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 or deep chain costs O(nodes), not O(nodes²).
+   *
+   * 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`
+   * 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` and `ancestorsOf`). A cycle is a loud `RELATION_CYCLE`
+   * in `DEV` and a safe break in production. */
+  forEachHierarchyMatch(e, t, s, r, i, n, o, l) {
+    const a = this._relationOf(n);
+    if (!a.exclusive)
+      throw new O(
+        p.RELATION_MODE_MISMATCH,
+        "hierarchy(): relation is multi-target, depth ordering needs an exclusive (parent) chain"
+      );
+    const h = [];
+    if (this._host.forEachSparseMatch(
+      e,
+      t,
+      s,
+      r,
+      i,
+      (_) => h.push(_)
+    ), h.length === 0) return;
+    this._hierarchyRadixOut = b(
+      h,
+      this._hierarchyRadixOut,
+      this._hierarchyRadixC0,
+      this._hierarchyRadixC1
+    );
+    const f = this._host.sparseStoreOf(a.sparse), E = /* @__PURE__ */ new Map(), y = /* @__PURE__ */ new Set(), T = [];
+    for (let _ = 0; _ < h.length; _++) {
+      const v = h[_], c = this._hierarchyDepthOf(g(v), f, E, y);
+      if (c > o) continue;
+      let u = T[c];
+      u === void 0 && (u = [], T[c] = u), u.push(v);
+    }
+    for (let _ = 0; _ < T.length; _++) {
+      const v = T[_];
+      if (v !== void 0)
+        for (let c = 0; c < v.length; c++) l(v[c]);
+    }
+  }
+  /** 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 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. */
+  _hierarchyDepthOf(e, t, s, r) {
+    const i = [];
+    let n = e, o = 0;
+    for (; ; ) {
+      const a = s.get(n);
+      if (a !== void 0) {
+        o = a;
+        break;
+      }
+      const h = t.getField(n, 0);
+      let f = -1;
+      if (h !== void 0) {
+        const E = x(h);
+        this._host.isAlive(E) && (f = g(E));
+      }
+      if (f === -1) {
+        s.set(n, 0), o = 0;
+        break;
+      }
+      if (r.has(f))
+        throw new O(
+          p.RELATION_CYCLE,
+          `hierarchy(): cycle in relation chain at entity index ${f}`
+        );
+      i.push(n), r.add(n), n = f;
+    }
+    let l = o;
+    for (let a = i.length - 1; a >= 0; a--)
+      l += 1, s.set(i[a], l), r.delete(i[a]);
+    return s.get(e);
+  }
+}
+class F {
+  _service;
+  /** @internal constructed by the relations plugin. */
+  constructor(e) {
+    this._service = e;
+  }
+  register(e) {
+    return this._service.registerRelation(e);
+  }
+  /** Count of registered relations. */
+  get count() {
+    return this._service.count;
+  }
+  /** Add a `(R, tgt)` pair to `src`. Exclusive replaces the existing target
+   * multi adds to the set. No archetype transition. */
+  add(e, t, s) {
+    return this._service.addRelation(e, t, s), this;
+  }
+  /** Remove a `(R, tgt)` pair from `src`. For multi, omitting `tgt` removes
+   * all of `src`'s targets. No archetype transition. */
+  remove(e, t, s) {
+    return this._service.removeRelation(e, t, s), this;
+  }
+  /** Whether `src` holds any pair under `R`. */
+  has(e, t) {
+    return this._service.hasRelation(e, t);
+  }
+  /** The single target of `src` under an exclusive relation, or `undefined`. */
+  targetOf(e, t) {
+    return this._service.targetOf(e, t);
+  }
+  /** All targets of `src` under `R`, ascending by id. */
+  targetsOf(e, t) {
+    return this._service.targetsOf(e, t);
+  }
+  /** Sources pointing at `tgt` under `R` (the reverse index), ascending by id.
+   * `(entity, def)` order, matching `targetOf` and `targetsOf`. */
+  sourcesOf(e, t) {
+    return this._service.sourcesOf(e, t);
+  }
+  /** All `(source, target)` pairs of relation `R`, the `(R, *)` wildcard.
+   * Sources in canonical entity-index order. Cold path. */
+  pairsOf(e) {
+    return this._service.pairsOf(e);
+  }
+  /** Every `(relation, source)` pointing at `tgt`, across all relation kinds,
+   * the `(*, T)` wildcard. Ordered by relation id then source id. */
+  sourcesOfAny(e) {
+    return this._service.sourcesOfAny(e);
+  }
+  /** Walk relation `R` up from `src` to its chain root, returning
+   * `[src, parent, …, root]` (nearest-ancestor-first). Exclusive only. */
+  ancestorsOf(e, t) {
+    return this._service.ancestorsOf(e, t);
+  }
+  /** The root of `src`'s `R`-chain (`src` itself when it has no target).
+   * Exclusive only. */
+  rootOf(e, t) {
+    return this._service.rootOf(e, t);
+  }
+  /** 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(e, t) {
+    return this._service.cascadeOf(e, t);
+  }
+  /** 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() {
+    return this._service.compactRelations();
+  }
+}
+function j(A, e) {
+  return A.relations.register({
+    exclusive: !0,
+    onDeleteTarget: e?.onDeleteTarget ?? "clear"
+  });
+}
+function B(A, e) {
+  return A.relations.register({
+    exclusive: !0,
+    onDeleteTarget: e?.onDeleteTarget ?? "delete"
+  });
+}
+function z() {
+  return {
+    name: "relations",
+    install(A) {
+      const e = A.store, t = new H(e.relationHost());
+      return e.installRelations(t), { relations: new F(t) };
+    }
+  };
+}
+export {
+  F as ECSRelations,
+  B as registerChildOf,
+  j as registerIsA,
+  z as relations
+};