@oasys/oecs 0.5.4 → 0.6.0

package/dist/plugins/relations.js

@@ -0,0 +1,553 @@
+import { D as b, R as C, a as m, g as d, c as N, U as w } from "./relation_store-BsoegrZh.js";
+import { r as L } from "./arrays-Dr_1hCjL.js";
+import { ECSError as D, ECS_ERROR as I } from "../index.js";
+import { u as A } from "./assertions-gtDVfbnQ.js";
+class M {
+  constructor(t) {
+    this._host = t;
+  }
+  // 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(t) {
+    const e = t?.multi === !0, s = t?.exclusive === !0;
+    if (e && s)
+      throw new D(
+        I.RELATION_MODE_INVALID,
+        "relations.register: a relation cannot be both exclusive and multi-target"
+      );
+    const r = !e, i = t?.onDeleteTarget ?? b, n = r ? this._host.pushSparseStore([C], ["f64"]) : this._host.pushSparseStore([], []), o = this._relations.length;
+    return this._relations.push(
+      m(r, n, this._host.sparseStoreOf(n), i)
+    ), i !== "orphan" && (this._hasTargetCleanup = !0), A(o);
+  }
+  _relationOf(t) {
+    const e = t, s = this._relations[e];
+    if (s === void 0)
+      throw new D(I.RELATION_NOT_REGISTERED, `relation ${e} 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(t, e, s) {
+    const r = this._relationOf(e);
+    this._host.isAlive(t) && this._host.isAlive(s) && r.link(t, 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(t, e, s) {
+    const r = this._relationOf(e);
+    this._host.isAlive(t) && r.unlink(t, s);
+  }
+  /** The single target of `src` under an exclusive relation, or `undefined`.
+   * Throws in `DEV` on a multi-target relation (use `targetsOf`). */
+  targetOf(t, e) {
+    return this._relationOf(e).singleTargetAt(d(t));
+  }
+  /** All targets of `src` under `R`, one or zero for exclusive, the full set
+   * for multi, ascending by id. */
+  targetsOf(t, e) {
+    return this._relationOf(e).targetsAt(d(t));
+  }
+  /** Sources that point at `tgt` under `R` (the reverse index), ascending by
+   * id. Empty when none. */
+  sourcesOf(t, e) {
+    return this._relationOf(e).sourcesOf(t);
+  }
+  /** Whether `src` holds any pair under `R`. */
+  hasRelation(t, e) {
+    return this._host.hasSparse(t, this._relationOf(e).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(t) {
+    const e = this._relationOf(t), s = [], r = this._host.generations();
+    return e.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(t) {
+    const e = [], s = this._relations;
+    for (let r = 0; r < s.length; r++) {
+      const i = A(r), n = s[r].sourcesOf(t);
+      for (let o = 0; o < n.length; o++) e.push([i, n[o]]);
+    }
+    return e;
+  }
+  // --- 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(t) {
+    return this._relationOf(t).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(t, e, s, r, i, n) {
+    const { sparseIncludes: o, sparseExcludes: l, includesDisabled: a } = i, c = this._relations;
+    if (c.length === 0) return;
+    const _ = /* @__PURE__ */ new Set();
+    for (let h = 0; h < c.length; h++) {
+      const u = c[h].sourcesOf(t);
+      for (let O = 0; O < u.length; O++) _.add(u[O]);
+    }
+    if (_.size === 0) return;
+    const R = Array.from(_).sort((h, u) => h - u), S = this._host.sparseStores(), E = this._host.entityArchetypes(), f = this._host.entityRows(), p = this._host.archetypes();
+    for (let h = 0; h < R.length; h++) {
+      const u = A(R[h]), O = d(u), x = E[O];
+      if (x === w) continue;
+      const k = p[x], y = k.mask;
+      if (!y.contains(e) || s !== null && y.overlaps(s) || r !== null && !y.overlaps(r)) continue;
+      let T = !0;
+      for (let g = 0; g < o.length; g++)
+        if (!S[o[g]].has(O)) {
+          T = !1;
+          break;
+        }
+      if (T) {
+        for (let g = 0; g < l.length; g++)
+          if (S[l[g]].has(O)) {
+            T = !1;
+            break;
+          }
+        if (T) {
+          if (!a) {
+            const g = f[O];
+            if (g !== w && g >= k.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 t = this._relations;
+    if (t.length === 0) return 0;
+    const e = (r) => this._host.isAlive(r);
+    let s = 0;
+    for (let r = 0; r < t.length; r++) s += t[r].pruneDeadReverse(e);
+    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(t, e) {
+    const s = this._relationOf(e), r = this._host.sparseStoreOf(s.sparse), i = [t], n = /* @__PURE__ */ new Set([d(t)]);
+    let o = t;
+    for (; ; ) {
+      const l = r.getField(d(o), 0);
+      if (l === void 0) break;
+      const a = A(l);
+      if (!this._host.isAlive(a)) {
+        i.push(a);
+        break;
+      }
+      const c = d(a);
+      if (n.has(c))
+        break;
+      n.add(c), 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(t, e) {
+    const s = this.ancestorsOf(t, e);
+    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(t, e) {
+    const s = this._relationOf(e), r = [t], i = /* @__PURE__ */ new Set([d(t)]);
+    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], c = d(a);
+        i.has(c) || (i.add(c), 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(t) {
+    const e = this._relations;
+    for (let s = 0; s < e.length; s++) e[s].purgeSource(t);
+  }
+  /** 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(t, e) {
+    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(t);
+      if (n.length !== 0) {
+        if (i.onDeleteTarget === "delete") {
+          for (let o = 0; o < n.length; o++) e.push(n[o]);
+          continue;
+        }
+        for (let o = 0; o < n.length; o++) i.unlink(n[o], t);
+      }
+    }
+  }
+  /** 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(t, e, s, r, i, n, o, l) {
+    const a = this._relationOf(n), c = [];
+    if (this._host.forEachSparseMatch(
+      t,
+      e,
+      s,
+      r,
+      i,
+      (f) => c.push(f)
+    ), c.length === 0) return;
+    this._hierarchyRadixOut = L(
+      c,
+      this._hierarchyRadixOut,
+      this._hierarchyRadixC0,
+      this._hierarchyRadixC1
+    );
+    const _ = this._host.sparseStoreOf(a.sparse), R = /* @__PURE__ */ new Map(), S = /* @__PURE__ */ new Set(), E = [];
+    for (let f = 0; f < c.length; f++) {
+      const p = c[f], h = this._hierarchyDepthOf(d(p), _, R, S);
+      if (h > o) continue;
+      let u = E[h];
+      u === void 0 && (u = [], E[h] = u), u.push(p);
+    }
+    for (let f = 0; f < E.length; f++) {
+      const p = E[f];
+      if (p !== void 0)
+        for (let h = 0; h < p.length; h++) l(p[h]);
+    }
+  }
+  /** 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(t, e, s, r) {
+    const i = [];
+    let n = t, o = 0;
+    for (; ; ) {
+      const a = s.get(n);
+      if (a !== void 0) {
+        o = a;
+        break;
+      }
+      const c = e.getField(n, 0);
+      let _ = -1;
+      if (c !== void 0) {
+        const R = A(c);
+        this._host.isAlive(R) && (_ = d(R));
+      }
+      if (_ === -1) {
+        s.set(n, 0), o = 0;
+        break;
+      }
+      if (r.has(_)) {
+        s.set(n, 0), o = 0;
+        break;
+      }
+      i.push(n), r.add(n), n = _;
+    }
+    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(t);
+  }
+}
+class F {
+  _service;
+  /** @internal constructed by the relations plugin. */
+  constructor(t) {
+    this._service = t;
+  }
+  register(t) {
+    return this._service.registerRelation(t);
+  }
+  /** 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(t, e, s) {
+    return this._service.addRelation(t, e, s), this;
+  }
+  /** Remove a `(R, tgt)` pair from `src`. For multi, omitting `tgt` removes
+   * all of `src`'s targets. No archetype transition. */
+  remove(t, e, s) {
+    return this._service.removeRelation(t, e, s), this;
+  }
+  /** Whether `src` holds any pair under `R`. */
+  has(t, e) {
+    return this._service.hasRelation(t, e);
+  }
+  /** The single target of `src` under an exclusive relation, or `undefined`. */
+  targetOf(t, e) {
+    return this._service.targetOf(t, e);
+  }
+  /** All targets of `src` under `R`, ascending by id. */
+  targetsOf(t, e) {
+    return this._service.targetsOf(t, e);
+  }
+  /** Sources pointing at `tgt` under `R` (the reverse index), ascending by id.
+   * `(entity, def)` order, matching `targetOf` and `targetsOf`. */
+  sourcesOf(t, e) {
+    return this._service.sourcesOf(t, e);
+  }
+  /** All `(source, target)` pairs of relation `R`, the `(R, *)` wildcard.
+   * Sources in canonical entity-index order. Cold path. */
+  pairsOf(t) {
+    return this._service.pairsOf(t);
+  }
+  /** Every `(relation, source)` pointing at `tgt`, across all relation kinds,
+   * the `(*, T)` wildcard. Ordered by relation id then source id. */
+  sourcesOfAny(t) {
+    return this._service.sourcesOfAny(t);
+  }
+  /** Walk relation `R` up from `src` to its chain root, returning
+   * `[src, parent, …, root]` (nearest-ancestor-first). Exclusive only. */
+  ancestorsOf(t, e) {
+    return this._service.ancestorsOf(t, e);
+  }
+  /** The root of `src`'s `R`-chain (`src` itself when it has no target).
+   * Exclusive only. */
+  rootOf(t, e) {
+    return this._service.rootOf(t, e);
+  }
+  /** 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(t, e) {
+    return this._service.cascadeOf(t, e);
+  }
+  /** 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 H(v, t) {
+  return v.relations.register({
+    exclusive: !0,
+    onDeleteTarget: t?.onDeleteTarget ?? "clear"
+  });
+}
+function z(v, t) {
+  return v.relations.register({
+    exclusive: !0,
+    onDeleteTarget: t?.onDeleteTarget ?? "delete"
+  });
+}
+function P() {
+  return {
+    name: "relations",
+    install(v) {
+      const t = v.store, e = new M(t.relationHost());
+      return t.installRelations(e), { relations: new F(e) };
+    }
+  };
+}
+export {
+  F as ECSRelations,
+  z as registerChildOf,
+  H as registerIsA,
+  P as relations
+};

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

@@ -0,0 +1,33 @@
+import { ECSSnapshots } from '../../core/ecs/facades.cjs';
+import { Plugin } from '../../core/ecs/plugin.cjs';
+/** The world surface this plugin adds. `ecs.snapshots` is already an
+ * `ECSSnapshots`, and this widens it: an intersection of the two is the
+ * subclass, so an installed world reaches `capture` and a bare one does not. */
+export interface SnapshotsPlugin {
+    readonly snapshots: ECSSnapshotsFull;
+}
+/** `ECSSnapshots` plus the capture and restore surface. */
+export declare class ECSSnapshotsFull extends ECSSnapshots {
+    /** Capture the full live world (the dense bytes, the sparse stores and
+     * relations, and the host-side bookkeeping) to one self-contained byte
+     * buffer that `restore` can mount back onto a live, ticking world. Version 1
+     * captures no resource, no event and no change-detection baseline. */
+    capture(): Uint8Array;
+    /** Mount a `capture()` buffer onto this live world and keep ticking.
+     * Fails closed on a malformed frame or registration mismatch before
+     * mutating any live state. Requires a matching archetype set and column
+     * layout (prewarm so the set is stable). */
+    restore(bytes: Uint8Array): void;
+    /** Serialize the sparse stores and the relations to a self-contained buffer,
+     * the sparse half of a world snapshot, canonical entity-index order.
+     * Pairs with `restoreSparse`. */
+    captureSparse(): Uint8Array;
+    /** Repopulate the sparse stores and the relation indices from
+     * `captureSparse` bytes. Sparse components must already be registered in the
+     * same order. Throws `SparseRestoreError` on a shape or identity
+     * mismatch. */
+    restoreSparse(bytes: Uint8Array): void;
+}
+/** The snapshot plugin, for `ECS.create({ plugins: [snapshots()] })`. */
+export declare function snapshots(): Plugin<SnapshotsPlugin>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,33 @@
+import { ECSSnapshots } from '../../core/ecs/facades.js';
+import { Plugin } from '../../core/ecs/plugin.js';
+/** The world surface this plugin adds. `ecs.snapshots` is already an
+ * `ECSSnapshots`, and this widens it: an intersection of the two is the
+ * subclass, so an installed world reaches `capture` and a bare one does not. */
+export interface SnapshotsPlugin {
+    readonly snapshots: ECSSnapshotsFull;
+}
+/** `ECSSnapshots` plus the capture and restore surface. */
+export declare class ECSSnapshotsFull extends ECSSnapshots {
+    /** Capture the full live world (the dense bytes, the sparse stores and
+     * relations, and the host-side bookkeeping) to one self-contained byte
+     * buffer that `restore` can mount back onto a live, ticking world. Version 1
+     * captures no resource, no event and no change-detection baseline. */
+    capture(): Uint8Array;
+    /** Mount a `capture()` buffer onto this live world and keep ticking.
+     * Fails closed on a malformed frame or registration mismatch before
+     * mutating any live state. Requires a matching archetype set and column
+     * layout (prewarm so the set is stable). */
+    restore(bytes: Uint8Array): void;
+    /** Serialize the sparse stores and the relations to a self-contained buffer,
+     * the sparse half of a world snapshot, canonical entity-index order.
+     * Pairs with `restoreSparse`. */
+    captureSparse(): Uint8Array;
+    /** Repopulate the sparse stores and the relation indices from
+     * `captureSparse` bytes. Sparse components must already be registered in the
+     * same order. Throws `SparseRestoreError` on a shape or identity
+     * mismatch. */
+    restoreSparse(bytes: Uint8Array): void;
+}
+/** The snapshot plugin, for `ECS.create({ plugins: [snapshots()] })`. */
+export declare function snapshots(): Plugin<SnapshotsPlugin>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/snapshots/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;KAcK;AAGL,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,uBAAuB,CAAC;AAEhE;;gFAEgF;AAChF,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;CACrC;AAED,2DAA2D;AAC3D,qBAAa,gBAAiB,SAAQ,YAAY;IACjD;;;0EAGsE;IAC/D,OAAO,IAAI,UAAU;IAI5B;;;gDAG4C;IACrC,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAIvC;;qCAEiC;IAC1B,aAAa,IAAI,UAAU;IAIlC;;;mBAGe;IACR,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;CAG7C;AAED,yEAAyE;AACzE,wBAAgB,SAAS,IAAI,MAAM,CAAC,eAAe,CAAC,CASnD"}

package/dist/plugins/snapshots/resume.d.cts

@@ -0,0 +1,57 @@
+import { ECS_SNAPSHOT_VERSION, ArchetypeRowState, HostState } from '../../core/ecs/snapshot.cjs';
+import { ArchetypeViews } from '../../core/store/index.cjs';
+import { ECSRestoreError } from '../../core/ecs/utils/error.cjs';
+/** Magic for the combined world-snapshot frame (`"WRS0"` little-endian). Distinct
+ * from the SAB `STORE_MAGIC` so a bare dense snapshot fed to `restore` is
+ * rejected with a clear error instead of being mis-parsed as a combined frame. */
+export declare const WORLD_SNAPSHOT_MAGIC = 810766935;
+export { ECSRestoreError };
+export { ECS_SNAPSHOT_VERSION };
+export type { ArchetypeRowState, HostState };
+/** Serialize host-state to a self-contained little-endian byte buffer. Layout:
+ *
+ *   [u32 tick][u32 highWater][u32 alive_count]
+ *   [u32 freeCount][u32 free_index × freeCount]
+ *   [u32 archCount][(u32 id, u32 length, u32 enabled_count) × archCount]
+ */
+export declare function serializeHostState(hs: HostState): Uint8Array;
+/** Parse host-state bytes produced by `serializeHostState`. Throws
+ * `ECSRestoreError` on truncation or a trailing-byte (non-canonical) buffer. */
+export declare function parseHostState(bytes: Uint8Array): HostState;
+/** Assemble the combined world-snapshot frame from its three sections. Layout:
+ *
+ *   [u32 magic][u32 version][u32 denseLen][u32 sparseLen][u32 hostLen]
+ *   [dense][sparse][host]
+ */
+export declare function frameWorldSnapshot(dense: Uint8Array, sparse: Uint8Array, host: Uint8Array): Uint8Array;
+/** The three sections of a combined frame, as zero-copy subviews over `bytes`. */
+export interface WorldSnapshotSections {
+    readonly dense: Uint8Array;
+    readonly sparse: Uint8Array;
+    readonly host: Uint8Array;
+}
+/** Split a combined frame back into its sections. Validates magic, version, and
+ * an exact (no trailing bytes) frame. Throws `ECSRestoreError` otherwise. */
+export declare function unframeWorldSnapshot(bytes: Uint8Array): WorldSnapshotSections;
+/**
+ * Fail-closed registration guard, read **directly from the snapshot's dense
+ * bytes** so it can run before the dense backing is touched. `restore`
+ * builds the restored store through the live world's in-place allocator,
+ * which reuses the live backing buffer, so validating a
+ * *materialised* `ColumnStore` would already have overwritten live column data
+ * (the buffer is overwritten inside `restoreColumnStore`, before any post-build
+ * check could run). Parsing the descriptors off the raw `dense` `Uint8Array`
+ * keeps the check non-mutating, so a mismatch leaves the live world untouched.
+ *
+ * Asserts: the dense section's SAB magic and ABI, and that its archetype set,
+ * its per-archetype `componentMask` and its per-column
+ * `(componentId, fieldId, typeTag)`
+ * match the live store's exactly (so every live `Archetype.refreshViews` finds
+ * its region and no snapshot archetype is orphaned), and that the entity-index
+ * capacity matches (the region is sized once at construction). The archetype
+ * graph is rebuilt from registration code, not the snapshot (mirroring
+ * `restoreSparse`'s "registered in the same order" contract). Throws
+ * `ECSRestoreError` on any mismatch and malformed section.
+ */
+export declare function assertDenseMatchesLive(dense: Uint8Array, live: ReadonlyMap<number, ArchetypeViews>, liveEntityIndexCapacity: number): void;
+//# sourceMappingURL=resume.d.ts.map