@oasys/oecs 0.5.4 → 0.6.0

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

@@ -1,9 +1,8 @@
-import { Brand } from '../../type_primitives/index.cjs';
+import { Brand, BitSet, TypedArrayTag } from '../../type_primitives/index.cjs';
 import { EntityID } from './entity.cjs';
-import { SparseComponentDef, SparseComponentStore } from './sparse_store.cjs';
-/** Relation handle id. A separate id space from `ComponentID` and
- * `SparseComponentID` — it indexes the `RelationService` registry. The numeric
- * value is the registration order, stable for the lifetime of the ECS. */
+import { Archetype } from './archetype.cjs';
+import { QueryTerms } from './query_terms.cjs';
+import { SparseComponentDef, SparseComponentID, SparseComponentStore } from './sparse_store.cjs';
 export type RelationID = Brand<number, "relation_id">;
 declare const __relationBrand: unique symbol;
 /** A relation's registration-time cardinality: `exclusive` = one target per
@@ -17,9 +16,9 @@ export type RelationDef<C extends RelationCardinality = RelationCardinality> = R
 /** Access sentinel for the `(*, T)` wildcard query iteration
  * (`Query.forEachRelatedTo`). A `(*, T)` term reads **every** registered
  * relation's reverse index to find sources of `T`, so it can't name a specific
- * relation in `relationReads` the way `withRelation(R)` (`(R, *)`) can. A
+ * relation in `relationReads` the way `andRelation(R)` (`(R, *)`) can. A
  * system that iterates a `(*, T)` wildcard lists `ANY_RELATION` in `relationReads`
- * instead; `accessCheck.checkRelationReadAny` honors it. The numeric value is a
+ * instead. `accessCheck.assertRelationReadAny` honors it. The numeric value is a
  * reserved sentinel far past any real registration-order relation id (relations are
  * minted from 0 upward), so it can never collide with a registered relation. */
 export declare const ANY_RELATION: RelationDef;
@@ -27,21 +26,21 @@ export declare const ANY_RELATION: RelationDef;
  * **targets** is destroyed. Chosen per-relation at registration, run at
  * destroy-flush (and the immediate-destroy path) off the reverse index:
  *
- *   - **`delete`** — cascade: destroy every source of the dead target too,
- *     recursively for chains/trees (the canonical ChildOf case).
- *   - **`clear`** — remove the relation from every source; the sources survive.
- *   - **`orphan`** — leave the link intact but dangling. Reads stay safe (the
+ *   - **`delete`**, cascade: destroy every source of the dead target too,
+ *     recursively for chains and trees (the canonical ChildOf case).
+ *   - **`clear`**, remove the relation from every source. The sources survive.
+ *   - **`orphan`**, leave the link intact but dangling. Reads stay safe (the
  *     reverse index is `EntityID`-keyed, so the dead handle never aliases a
- *     recycled slot); `targetOf` returns a dead handle until the source
+ *     recycled slot). `targetOf` returns a dead handle until the source
  *     re-targets or is removed. This is the original behaviour and the default.
  */
 export type OnDeleteTarget = "delete" | "clear" | "orphan";
 /** Default on-target-delete policy: leave the link dangling (the original
  * behaviour, zero change for callers that don't opt in). */
 export declare const DEFAULT_ON_DELETE_TARGET: OnDeleteTarget;
-/** Registration options. `exclusive` (one target per source) is the default;
- * pass `{ multi: true }` for a multi-target relation. The two are mutually
- * exclusive — the union makes `{ exclusive: true, multi: true }` a compile
+/** Registration options. `exclusive` (one target per source) is the default.
+ * Pass `{ multi: true }` for a multi-target relation. The two are mutually
+ * exclusive, the union makes `{ exclusive: true, multi: true }` a compile
  * error (it also throws at runtime, for JS callers). `onDeleteTarget` selects
  * the cleanup policy applied to sources when a target is destroyed (default
  * `orphan`). */
@@ -58,186 +57,106 @@ export type RelationOptions = {
  * sparse component. Field 0 of a single-field schema. */
 export declare const RELATION_TARGET_FIELD = "target";
 /** Receives one canonical `(source index, sorted targets)` set during a fold
- * over a multi relation's forward sets. Targets are ascending by id; empty sets
+ * over a multi relation's forward sets. Targets are ascending by id. Empty sets
  * are never yielded (see `forEachCanonicalTargetSet`). */
 export type CanonicalTargetSetFn = (sourceIndex: number, targets: readonly EntityID[]) => void;
 /** Receives one canonical `(source, target)` pair during a fold over a
  * relation's forward links. Sources ascend by entity index, each source's
- * targets ascend by id — the determinism order. */
+ * targets ascend by id, the determinism order. */
 export type CanonicalPairFn = (source: EntityID, target: EntityID) => void;
 /** Maps a source entity **index** to its full `EntityID` (generation from the
  * live slot). Supplied by `Store`, which owns entity generations. */
 export type MakeSourceID = (index: number) => EntityID;
-/** One relation's derived side state. **Abstract over cardinality:** the
- * base owns the cardinality-agnostic **reverse index** (target → sources, keyed
- * by full `EntityID` so a recycled slot can't alias a dead target's sources) and
- * a handle on the backing `SparseComponentStore`; the forward representation and
- * its sparse interaction are owned by the concrete `ExclusiveRelationStore` /
- * `MultiRelationStore` (built by `makeRelationStore`).
+/** One relation's side state, as the digest and the snapshot codec see it.
  *
- * The registry level (`Store` + `RelationService`) owns what is genuinely its
- * own — entity liveness, registration, and destroy orchestration — and drives
- * a relation through the virtual `link` /
- * `unlink` / `purgeSource` / `forEachCanonicalPair` / … without ever
- * branching on cardinality. Each cardinality keeps forward link + reverse index
- * + sparse membership in lockstep inside one method on one class, so the
- * lockstep can't be broken by missing a scattered `if (rs.exclusive)` site. */
-export declare abstract class RelationStore {
-    /** `true` → one target per source (target in the sparse field); `false` →
-     * a set of targets per source. The cardinality discriminant survives as a
-     * field because it is part of the snapshot header and the traversal/`targetOf`
-     * mode guards — but the forward *mechanics* are virtual, not branched on it. */
+ * The relations plugin owns the class. Two core-adjacent readers walk it and
+ * neither needs the forward mutators: `Store.stateHash` folds the multi target
+ * sets, and the snapshot service serializes and rebuilds them. The narrow view
+ * is what lets those two speak about a relation store without the plugin. */
+export interface RelationStoreView {
+    /** `true` → one target per source, and the target rides the backing sparse
+     * field. `false` → a target set per source, held beside the sparse tag. */
     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/liveness by
-     * `Store`, but the relation drives the forward/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/dies accumulates dead-target keys
-     * without bound. This is the reclaim primitive behind `Store.compactRelations`
-     * — a cold path the host calls at scene/snapshot boundaries. It is
-     * cardinality-free (reverse-index only), so it lives on the base unchanged.
-     *
-     * Pure index reclaim: the **forward** links (the exclusive sparse target
-     * field, the multi forward set) are left untouched, so `targetOf` /
-     * `targetsOf` still return the dangling dead handle exactly as `orphan`
-     * promises. The reverse index is derived, so dropping a dead-target entry
-     * changes nothing observable except `sourcesOf` on that dead handle (which
-     * goes from the dangling sources to `[]` — meaningless either way, the target
-     * is gone) and is faithfully rebuilt by snapshot/restore from the surviving
-     * forward links. Only the **target** role can leak here: a destroyed *source*
-     * is already unlinked from every reverse set by `purgeSource`, so a live
-     * target's set never holds a dead source. `isAlive` is supplied by `Store`,
-     * which owns entity liveness. Deleting during `Map` key iteration is
-     * well-defined — already-visited and not-yet-reached keys are unaffected. */
-    pruneDeadReverse(isAlive: (id: EntityID) => boolean): number;
-    /** Sources that point at `tgt`, ascending by id (deterministic, cold-path
-     * sort) — empty when none. */
-    sourcesOf(tgt: EntityID): EntityID[];
-    /** Drop every derived side index — the reverse index and (for multi) the
-     * forward target sets. Restore path only (`restoreRelations`): the side
-     * indices are rebuilt from scratch, so they're cleared first to stay
-     * idempotent when restoring into a dirty world. The backing sparse store is
-     * cleared separately by `restoreSparseStores`. */
+    /** Fold `cb` over the multi forward target sets in canonical order, and do
+     * nothing for an exclusive relation. */
+    forEachCanonicalTargetSet(cb: CanonicalTargetSetFn): void;
+    /** Drop every derived side index. The restore path clears before it
+     * rebuilds, so restoring into a dirty world is idempotent. */
     resetIndices(): void;
-    /** Clear this relation's forward representation (multi: the side map;
-     * exclusive: nothing — its forward links live in the sparse store, cleared by
-     * `restoreSparseStores`). */
-    protected abstract _resetForward(): void;
-    /** Add a `(R, tgt)` link from `src`, keeping forward link + membership +
-     * reverse index in lockstep. Exclusive: replaces any existing target
-     * (idempotent if `tgt` is already the target). Multi: adds to the set
-     * (idempotent on a duplicate), establishing the membership tag on the first
-     * target. `src` must be live — `Store` checks before delegating. */
-    abstract link(src: EntityID, tgt: EntityID): void;
-    /** Remove `(R, tgt)` from `src` — or, when `tgt` is omitted, every target of
-     * `src` — keeping forward link + membership + reverse index in lockstep. A
-     * no-op when the link isn't present. */
-    abstract unlink(src: EntityID, tgt?: EntityID): void;
-    /** Purge a destroyed **source**: drop its forward link(s) and unlink it from
-     * every target's reverse set, but leave the sparse **membership** row alone —
-     * `Store._purgeSparse` drops that (for every store) right after, so this
-     * runs first and must not double-remove. */
-    abstract purgeSource(src: EntityID): void;
-    /** The single target of source `index`, or `undefined`. Exclusive reads the
-     * sparse field; multi has no single target and returns `undefined` (matching
-     * the production `targetOf`-on-multi read, which the `DEV` guard rejects). */
-    abstract singleTarget(index: number): EntityID | undefined;
-    /** All targets of source `index`, ascending by id — one or zero for
-     * exclusive, the full sorted set for multi. The symmetric counterpart to
-     * `sourcesOf`. */
-    abstract targetsOf(index: number): EntityID[];
-    /** Whether source `index` holds any target under this relation (sparse
-     * membership). */
-    abstract has(index: number): boolean;
-    /** Fold `cb` over this relation's **multi** forward target sets in canonical
-     * order (sources ascending by index, each source's targets ascending by id),
-     * skipping empty sets. The single source of truth for the canonical multi
-     * traversal shared by `stateHash`, `snapshotRelations`, and `pairsOf`.
-     * 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. `makeId` maps a source
-     * index to its full `EntityID`. Exclusive rides the backing store's
-     * `canonicalIndices`; multi rides `forEachCanonicalTargetSet`. */
-    abstract forEachCanonicalPair(makeId: MakeSourceID, cb: CanonicalPairFn): void;
-    /** Rebuild the reverse index from the forward links after a restore.
-     * Exclusive reads it back from the just-restored sparse target field (the
-     * reverse index is never serialized); multi already rebuilt its reverse edges
-     * in `restoreAddTarget`, so this is a no-op for it. `makeId` maps a source
-     * index to its full `EntityID`. */
-    abstract rebuildReverseFromForward(makeId: MakeSourceID): void;
-    /** Restore one decoded multi forward edge `(source index → tgt)` plus its
-     * reverse edge (the source's full `EntityID` is `src`). Multi only — the
-     * snapshot header guards exclusive relations out before this is reached, so
-     * the exclusive override throws defensively. */
-    abstract restoreAddTarget(index: number, tgt: EntityID, src: EntityID): void;
+    /** Restore one decoded multi forward edge and its reverse edge. */
+    restoreAddTarget(index: number, tgt: EntityID, src: EntityID): void;
+    /** Rebuild the reverse index from the forward links after a restore. */
+    rebuildReverse(createId: MakeSourceID): void;
 }
-/** Build the right `RelationStore` for a cardinality. The only construction
- * site is `Store.registerRelation`, which resolves the backing sparse store and
- * hands it in so the relation can drive forward/membership rows directly. */
-export declare function makeRelationStore(exclusive: boolean, sparse: SparseComponentDef, store: SparseComponentStore, onDeleteTarget: OnDeleteTarget): RelationStore;
-/** Serialize the relation side data that does **not** live in the sparse store
- * — i.e. each **multi** relation's forward target sets (`Map<source index,
- * Set<target>>`). Exclusive relations store their target in the backing sparse
- * field, so they ride `snapshotSparseStores` and contribute only a header
- * here. The reverse index is fully derivable (from the sparse store for
- * exclusive, from these sets for multi), so it is never serialized — it is
- * rebuilt by `restoreRelations` + the caller's exclusive-reverse pass.
- *
- * Members are emitted in canonical order (sources ascending by entity index,
- * each source's targets ascending by id) so the bytes are independent of
- * add/remove history — the same byte-level determinism invariant the sparse
- * snapshot holds. Layout (integers little-endian):
- *
- *   u32 relationCount
- *   repeat relationCount times (registration / id order):
- *     u32 isMulti
- *     if multi:
- *       u32 sourceCount
- *       repeat sourceCount times (ascending source index):
- *         u32 sourceIndex
- *         u32 targetCount
- *         f64 × targetCount   (target EntityIDs, ascending) */
-export declare function snapshotRelations(relations: readonly RelationStore[]): Uint8Array;
-/** Rebuild every relation's side indices from a `snapshotRelations` buffer and
- * the already-restored sparse stores. Each relation's indices are reset first
- * (idempotent into a dirty world), then:
+/** 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 `generations`, `entityArchetypes` or `entityRows` 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[];
+    generations(): Int32Array;
+    entityArchetypes(): Int32Array;
+    entityRows(): Int32Array;
+    archetypes(): readonly Archetype[];
+    forEachSparseMatch(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, terms: QueryTerms, denseArchetypes: readonly Archetype[], cb: (entityId: EntityID) => void): void;
+}
+/** The relation service, as everything outside the plugin sees it.
  *
- *  - **multi** — forward target sets and their reverse edges are rebuilt from
- *    `bytes` (the sets aren't in the sparse store, so the bytes are the only
- *    source). `makeId` maps a source entity index to its full `EntityID`
- *    (generation from the live slot) so reverse edges key correctly.
- *  - **exclusive** — only the reset happens here; the reverse index is rebuilt
- *    by the caller from the backing sparse store (which already round-tripped
- *    through `restoreSparseStores`), since this function can't read it.
+ * `Store.relations` is public, so this is the whole crossing surface and not
+ * the world's half alone. The plugin's class implements it, and the compiler
+ * holds the two in step.
  *
- * Throws `SparseRestoreError` on any shape mismatch (relation count, an
- * exclusive/multi flag that disagrees with the registered relation, a multi
- * source index past `MAX_INDEX`, or a truncated / over-long buffer) rather than
- * silently building a corrupt index. */
-export declare function restoreRelations(relations: readonly RelationStore[], bytes: Uint8Array, makeId: (index: number) => EntityID): void;
+ * `purgeSource` and `cleanupTarget` are the one hot coupling: a dying entity
+ * loses its source role, and a target-death policy may cascade. Both sit
+ * behind a null test the destroy loop hoists, so a world without the plugin
+ * pays neither. Everything else is registration, a query driver or a `ctx`
+ * call, and cold. */
+export interface RelationHooks {
+    /** The registry, in registration order. `Store.stateHash` and the snapshot
+     * service walk it. */
+    readonly stores: readonly RelationStoreView[];
+    /** Registered relation kinds. The destroy paths gate on this. */
+    readonly count: number;
+    /** Whether any relation registered a non-`orphan` `onDeleteTarget`. The
+     * destroy paths gate the reverse-index walk on it. */
+    readonly hasTargetCleanup: boolean;
+    /** Drop a destroyed entity's forward links and its reverse edges, and leave
+     * the sparse membership row to `Store`. Runs before the sparse purge. */
+    purgeSource(entityId: EntityID): void;
+    /** Apply each relation's target-death policy to the sources of a destroyed
+     * target. A `delete` policy appends the doomed sources to `cascade`. */
+    cleanupTarget(targetId: EntityID, cascade: EntityID[]): void;
+    /** Register a relation kind. The facade's typed overloads sit on top. */
+    registerRelation(opts?: RelationOptions): RelationDef;
+    addRelation(src: EntityID, def: RelationDef, tgt: EntityID): void;
+    removeRelation(src: EntityID, def: RelationDef, tgt?: EntityID): void;
+    targetOf(src: EntityID, def: RelationDef): EntityID | undefined;
+    targetsOf(src: EntityID, def: RelationDef): EntityID[];
+    sourcesOf(tgt: EntityID, def: RelationDef): EntityID[];
+    hasRelation(src: EntityID, def: RelationDef): boolean;
+    /** Every `(source, target)` pair of one relation, the `(R, *)` wildcard. */
+    pairsOf(def: RelationDef): readonly (readonly [EntityID, EntityID])[];
+    /** Every `(relation, source)` pointing at `tgt`, the `(*, T)` wildcard. */
+    sourcesOfAny(tgt: EntityID): readonly (readonly [RelationDef, EntityID])[];
+    /** The chain from `src` up to its root, nearest ancestor first. */
+    ancestorsOf(src: EntityID, def: RelationDef): EntityID[];
+    /** The root of the chain `src` sits on. */
+    rootOf(src: EntityID, def: RelationDef): EntityID;
+    /** The subtree under `root`, breadth-first, parents before children. */
+    cascadeOf(root: EntityID, def: RelationDef): EntityID[];
+    /** Drop every reverse entry whose target died, and report the count. */
+    compactRelations(): number;
+    /** The backing sparse component of a relation, which the query terms
+     * compose against. */
+    relationBackingSparseId(def: RelationDef): SparseComponentID;
+    /** Drive a `(*, T)` wildcard query. */
+    forEachTargetMatch(target: EntityID, include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, terms: QueryTerms, cb: (entityId: EntityID) => void): void;
+    /** Drive a `hierarchy(R)` query, parents before children. */
+    forEachHierarchyMatch(include: BitSet, exclude: BitSet | null, anyOf: BitSet | null, terms: QueryTerms, denseArchetypes: readonly Archetype[], relation: RelationDef, maxDepth: number, cb: (entityId: EntityID) => void): void;
+}
 export {};
 //# sourceMappingURL=relation.d.ts.map