@oasys/oecs 0.4.0 → 0.5.0

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

@@ -0,0 +1,96 @@
+import { BitSet } from '../../type_primitives/index.cjs';
+import { Archetype, ArchetypeColumnLayout, ArchetypeID } from './archetype.cjs';
+import { ComponentID } from './component.cjs';
+import { ComponentMeta } from './store.cjs';
+import { ArchetypeSpec } from '../store/index.cjs';
+/** What the graph needs from `Store` — closure-injected. `extendStore` and
+ * `materialize` bind the storage lifecycle (SAB extend + column-store views
+ * + grow handler) on the Store side; `fanIntoQueries` binds query-registry
+ * state. All are creation-path only — never called on an edge-cache hit. */
+export interface ArchetypeGraphHost {
+    /** Component field metadata, indexed by ComponentID — for building a new
+     * archetype's column layouts. */
+    readonly componentMetas: () => readonly ComponentMeta[];
+    /** Row capacity for a new archetype's column region. */
+    readonly initialCapacity: () => number;
+    /** Extend the SAB with the new archetypes' column regions (one call for
+     * the whole batch — the bulk path's O(N²)→O(N) win, #213). */
+    readonly extendStore: (specs: ArchetypeSpec[]) => void;
+    /** Materialise the `Archetype` over the live column store and attach the
+     * store's grow handler. */
+    readonly materialize: (id: ArchetypeID, ownedMask: BitSet, layouts: ArchetypeColumnLayout[]) => Archetype;
+    /** Push a newly-installed archetype into every registered query whose
+     * masks it satisfies. */
+    readonly fanIntoQueries: (archetype: Archetype) => void;
+}
+export declare class ArchetypeGraph {
+    /** All archetypes, indexed by `ArchetypeID` (ids are minted monotonically
+     * and never removed). Store's flush loops hoist this array to a local. */
+    readonly archetypes: Archetype[];
+    /** Inverted index: ComponentID → ascending list of ArchetypeIDs that contain
+     * that component. Indexed POSITIONALLY by component id (a small, dense id
+     * space, 0..STORE_DESCRIPTOR_COMPONENT_LIMIT-1), so a lookup is an array
+     * index, not a Map hash. Used by `getMatchingArchetypes` to start the
+     * superset scan from the smallest bucket. Each bucket is a plain push-only
+     * array — NOT a Set — and deliberately does NOT dedup: a (component,
+     * archetype) pair can be inserted here at most once (see the "no duplicate
+     * pair" invariant on `install` + ADR-0015), so there is nothing for a Set
+     * to collapse. Archetypes are never removed from a Store, so buckets only
+     * grow, in ascending archetype-id order — which is canonical order,
+     * exploited by `_forEachChangedArchetype` to skip a sort. */
+    readonly componentIndex: ArchetypeID[][];
+    private readonly archetypeMap;
+    private nextArchetypeId;
+    private readonly host;
+    constructor(host: ArchetypeGraphHost);
+    get(id: ArchetypeID): Archetype;
+    /**
+     * Find or create an archetype for the given component mask.
+     * Also updates the componentIndex and pushes into matching registered queries.
+     *
+     * Hot single-mask path. The bulk batched variant — used by Phase C
+     * pre-warming at `ecs.startup()` — is `createManyFromMasks`;
+     * see #213 / `ECS.startup()` for how it gets called and why.
+     */
+    getOrCreateFromMask(mask: BitSet): ArchetypeID;
+    /**
+     * Bulk variant of `getOrCreateFromMask` — Phase C of issue #213.
+     *
+     * Given a set of masks, creates Archetypes for the ones not already
+     * planted, in a SINGLE `extendColumnStore` call (instead of one per
+     * archetype). Single-mask creation is O(N) in archetypes-so-far because
+     * the extend has to copy every existing archetype's live rows forward;
+     * N such calls compound to O(N²). Batching collapses the per-archetype
+     * setup-and-copy down to one pass — the per-startup cost the design doc
+     * §5.2 calls out as "O(N²) → O(N)" for in-tree systems whose archetype
+     * set is known at registration time via `spawns` + `transitions`.
+     *
+     * Masks already in the map are skipped. Returns the resolved
+     * `ArchetypeID` per input mask in input order — callers that don't need
+     * the ids can ignore the return value.
+     */
+    createManyFromMasks(masks: readonly BitSet[]): ArchetypeID[];
+    /** Hash-bucketed mask → ArchetypeID lookup; null when the mask isn't planted. */
+    private lookup;
+    /** Walk the mask's set bits and resolve each non-tag component to its
+     * layout. Used by both single and bulk archetype-create paths. */
+    private buildLayouts;
+    /** Materialise the `Archetype` for `id` (via the host, which binds the
+     * live column store + grow handler), register in the archetype map +
+     * component index, and fan into any matching registered queries.
+     *
+     * Clones `mask` before storing — callers may pass scratch BitSets that
+     * they intend to reuse (e.g. `addComponents` / `removeComponents`'s
+     * `_scratchTargetMask`). The Archetype and the archetypeMap bucket
+     * both keep references long-term, so the clone is required for
+     * correctness — and is the previously-implicit guarantee made by the
+     * mask-allocating callers (`copyWithSet`, `copyWithClear`, etc.). */
+    private install;
+    /** Resolve "add component_id to archetype_id" → target ArchetypeID. Caches the edge. */
+    resolveAdd(archetypeId: ArchetypeID, componentId: ComponentID): ArchetypeID;
+    /** Resolve "remove component_id from archetype_id" → target ArchetypeID. Caches the edge. */
+    resolveRemove(archetypeId: ArchetypeID, componentId: ComponentID): ArchetypeID;
+    /** Cache a bidirectional add/remove edge between two archetypes. */
+    private cacheEdge;
+}
+//# sourceMappingURL=archetype_graph.d.ts.map

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

@@ -0,0 +1,96 @@
+import { BitSet } from '../../type_primitives/index.js';
+import { Archetype, ArchetypeColumnLayout, ArchetypeID } from './archetype.js';
+import { ComponentID } from './component.js';
+import { ComponentMeta } from './store.js';
+import { ArchetypeSpec } from '../store/index.js';
+/** What the graph needs from `Store` — closure-injected. `extendStore` and
+ * `materialize` bind the storage lifecycle (SAB extend + column-store views
+ * + grow handler) on the Store side; `fanIntoQueries` binds query-registry
+ * state. All are creation-path only — never called on an edge-cache hit. */
+export interface ArchetypeGraphHost {
+    /** Component field metadata, indexed by ComponentID — for building a new
+     * archetype's column layouts. */
+    readonly componentMetas: () => readonly ComponentMeta[];
+    /** Row capacity for a new archetype's column region. */
+    readonly initialCapacity: () => number;
+    /** Extend the SAB with the new archetypes' column regions (one call for
+     * the whole batch — the bulk path's O(N²)→O(N) win, #213). */
+    readonly extendStore: (specs: ArchetypeSpec[]) => void;
+    /** Materialise the `Archetype` over the live column store and attach the
+     * store's grow handler. */
+    readonly materialize: (id: ArchetypeID, ownedMask: BitSet, layouts: ArchetypeColumnLayout[]) => Archetype;
+    /** Push a newly-installed archetype into every registered query whose
+     * masks it satisfies. */
+    readonly fanIntoQueries: (archetype: Archetype) => void;
+}
+export declare class ArchetypeGraph {
+    /** All archetypes, indexed by `ArchetypeID` (ids are minted monotonically
+     * and never removed). Store's flush loops hoist this array to a local. */
+    readonly archetypes: Archetype[];
+    /** Inverted index: ComponentID → ascending list of ArchetypeIDs that contain
+     * that component. Indexed POSITIONALLY by component id (a small, dense id
+     * space, 0..STORE_DESCRIPTOR_COMPONENT_LIMIT-1), so a lookup is an array
+     * index, not a Map hash. Used by `getMatchingArchetypes` to start the
+     * superset scan from the smallest bucket. Each bucket is a plain push-only
+     * array — NOT a Set — and deliberately does NOT dedup: a (component,
+     * archetype) pair can be inserted here at most once (see the "no duplicate
+     * pair" invariant on `install` + ADR-0015), so there is nothing for a Set
+     * to collapse. Archetypes are never removed from a Store, so buckets only
+     * grow, in ascending archetype-id order — which is canonical order,
+     * exploited by `_forEachChangedArchetype` to skip a sort. */
+    readonly componentIndex: ArchetypeID[][];
+    private readonly archetypeMap;
+    private nextArchetypeId;
+    private readonly host;
+    constructor(host: ArchetypeGraphHost);
+    get(id: ArchetypeID): Archetype;
+    /**
+     * Find or create an archetype for the given component mask.
+     * Also updates the componentIndex and pushes into matching registered queries.
+     *
+     * Hot single-mask path. The bulk batched variant — used by Phase C
+     * pre-warming at `ecs.startup()` — is `createManyFromMasks`;
+     * see #213 / `ECS.startup()` for how it gets called and why.
+     */
+    getOrCreateFromMask(mask: BitSet): ArchetypeID;
+    /**
+     * Bulk variant of `getOrCreateFromMask` — Phase C of issue #213.
+     *
+     * Given a set of masks, creates Archetypes for the ones not already
+     * planted, in a SINGLE `extendColumnStore` call (instead of one per
+     * archetype). Single-mask creation is O(N) in archetypes-so-far because
+     * the extend has to copy every existing archetype's live rows forward;
+     * N such calls compound to O(N²). Batching collapses the per-archetype
+     * setup-and-copy down to one pass — the per-startup cost the design doc
+     * §5.2 calls out as "O(N²) → O(N)" for in-tree systems whose archetype
+     * set is known at registration time via `spawns` + `transitions`.
+     *
+     * Masks already in the map are skipped. Returns the resolved
+     * `ArchetypeID` per input mask in input order — callers that don't need
+     * the ids can ignore the return value.
+     */
+    createManyFromMasks(masks: readonly BitSet[]): ArchetypeID[];
+    /** Hash-bucketed mask → ArchetypeID lookup; null when the mask isn't planted. */
+    private lookup;
+    /** Walk the mask's set bits and resolve each non-tag component to its
+     * layout. Used by both single and bulk archetype-create paths. */
+    private buildLayouts;
+    /** Materialise the `Archetype` for `id` (via the host, which binds the
+     * live column store + grow handler), register in the archetype map +
+     * component index, and fan into any matching registered queries.
+     *
+     * Clones `mask` before storing — callers may pass scratch BitSets that
+     * they intend to reuse (e.g. `addComponents` / `removeComponents`'s
+     * `_scratchTargetMask`). The Archetype and the archetypeMap bucket
+     * both keep references long-term, so the clone is required for
+     * correctness — and is the previously-implicit guarantee made by the
+     * mask-allocating callers (`copyWithSet`, `copyWithClear`, etc.). */
+    private install;
+    /** Resolve "add component_id to archetype_id" → target ArchetypeID. Caches the edge. */
+    resolveAdd(archetypeId: ArchetypeID, componentId: ComponentID): ArchetypeID;
+    /** Resolve "remove component_id from archetype_id" → target ArchetypeID. Caches the edge. */
+    resolveRemove(archetypeId: ArchetypeID, componentId: ComponentID): ArchetypeID;
+    /** Cache a bidirectional add/remove edge between two archetypes. */
+    private cacheEdge;
+}
+//# sourceMappingURL=archetype_graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archetype_graph.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/archetype_graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,MAAM,EAAsB,MAAM,uBAAuB,CAAC;AACnE,OAAO,EACN,SAAS,EAGT,KAAK,qBAAqB,EAE1B,KAAK,WAAW,EAChB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,EAGN,KAAK,aAAa,EAElB,MAAM,UAAU,CAAC;AAGlB;;;4EAG4E;AAC5E,MAAM,WAAW,kBAAkB;IAClC;qCACiC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,SAAS,aAAa,EAAE,CAAC;IACxD,wDAAwD;IACxD,QAAQ,CAAC,eAAe,EAAE,MAAM,MAAM,CAAC;IACvC;kEAC8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;IACvD;+BAC2B;IAC3B,QAAQ,CAAC,WAAW,EAAE,CACrB,EAAE,EAAE,WAAW,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,qBAAqB,EAAE,KAC5B,SAAS,CAAC;IACf;6BACyB;IACzB,QAAQ,CAAC,cAAc,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;CACxD;AAED,qBAAa,cAAc;IAC1B;8EAC0E;IAC1E,SAAgB,UAAU,EAAE,SAAS,EAAE,CAAM;IAC7C;;;;;;;;;;iEAU6D;IAC7D,SAAgB,cAAc,EAAE,WAAW,EAAE,EAAE,CAAM;IAErD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;IACtE,OAAO,CAAC,eAAe,CAAK;IAE5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;gBAE9B,IAAI,EAAE,kBAAkB;IAI7B,GAAG,CAAC,EAAE,EAAE,WAAW,GAAG,SAAS;IAStC;;;;;;;OAOG;IACI,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IAkBrD;;;;;;;;;;;;;;;OAeG;IACI,mBAAmB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,EAAE;IA4DnE,iFAAiF;IACjF,OAAO,CAAC,MAAM;IASd;sEACkE;IAClE,OAAO,CAAC,YAAY;IAkBpB;;;;;;;;;yEASqE;IACrE,OAAO,CAAC,OAAO;IA0Df,wFAAwF;IACjF,UAAU,CAAC,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,GAAG,WAAW;IAYlF,6FAA6F;IACtF,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,GAAG,WAAW;IAYrF,oEAAoE;IACpE,OAAO,CAAC,SAAS;CAuBjB"}

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

@@ -0,0 +1,43 @@
+import { ECS } from './ecs.cjs';
+import { OnDeleteTarget, RelationDef } from './relation.cjs';
+/** Options for a built-in relation. `exclusive` / `multi` are fixed (always
+ * exclusive — required for the chain/tree traversal helpers), so only the
+ * target-deletion cleanup policy is tunable. */
+export interface BuiltinRelationOptions {
+    /** What happens to a relation's sources when a target is destroyed.
+     * Defaults per relation (see each registrar). */
+    readonly onDeleteTarget?: OnDeleteTarget;
+}
+/**
+ * Register an **`IsA(instance → exemplar)`** relation — a thin instance-of link.
+ *
+ * - "all instances of exemplar E" is `ecs.relations.sourcesOf(E, IsA)`.
+ * - the IsA chain (`instance → exemplar → …`) is walked with
+ *   `ecs.relations.ancestorsOf(instance, IsA)` / `rootOf` / `cascadeOf(exemplar, IsA)`.
+ * - **No component inheritance** — IsA records the link only; materialization of
+ *   an instance from its exemplar stays a spawn-time copy (the template path,
+ *   #462), deliberately decoupled (#477 / #478). An exemplar is a real entity,
+ *   not a `Template` (a non-entity template can't be a relation target).
+ *
+ * Default `onDeleteTarget: "clear"` — destroying an exemplar drops its
+ * instances' IsA link but leaves the instances alive (the thin analog of
+ * flecs's `IsA`-remove, since there is no inherited data to strip). Pass
+ * `"delete"` for strong instance-of (exemplar death cascade-destroys instances).
+ */
+export declare function registerIsA(ecs: ECS, opts?: BuiltinRelationOptions): RelationDef<"exclusive">;
+/**
+ * Register a **`ChildOf(child → parent)`** relation — a thin hierarchy link.
+ *
+ * - a parent's children are `ecs.relations.sourcesOf(parent, ChildOf)`.
+ * - the hierarchy is walked with `ecs.relations.ancestorsOf(child, ChildOf)` (up to the
+ *   root), `rootOf`, and `cascadeOf(root, ChildOf)` (down, breadth-first,
+ *   parents before children).
+ * - unlike flecs's `ChildOf`, this does **not** scope names/lookup — the engine
+ *   has no name registry; it is purely the structural parent link.
+ *
+ * Default `onDeleteTarget: "delete"` — destroying a parent cascade-destroys
+ * its whole subtree (flecs's default). Pass `"clear"` to let children survive as
+ * roots, or `"orphan"` to leave a dangling `targetOf`.
+ */
+export declare function registerChildOf(ecs: ECS, opts?: BuiltinRelationOptions): RelationDef<"exclusive">;
+//# sourceMappingURL=builtin_relations.d.ts.map

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

@@ -1,5 +1,5 @@
-import { ECS } from './ecs';
-import { OnDeleteTarget, RelationDef } from './relation';
+import { ECS } from './ecs.js';
+import { OnDeleteTarget, RelationDef } from './relation.js';
 /** Options for a built-in relation. `exclusive` / `multi` are fixed (always
  * exclusive — required for the chain/tree traversal helpers), so only the
  * target-deletion cleanup policy is tunable. */
@@ -11,9 +11,9 @@ export interface BuiltinRelationOptions {
 /**
  * Register an **`IsA(instance → exemplar)`** relation — a thin instance-of link.
  *
- * - "all instances of exemplar E" is `world.sourcesOf(IsA, E)`.
+ * - "all instances of exemplar E" is `ecs.relations.sourcesOf(E, IsA)`.
  * - the IsA chain (`instance → exemplar → …`) is walked with
- *   `world.ancestorsOf(instance, IsA)` / `rootOf` / `cascadeOf(exemplar, IsA)`.
+ *   `ecs.relations.ancestorsOf(instance, IsA)` / `rootOf` / `cascadeOf(exemplar, IsA)`.
  * - **No component inheritance** — IsA records the link only; materialization of
  *   an instance from its exemplar stays a spawn-time copy (the template path,
  *   #462), deliberately decoupled (#477 / #478). An exemplar is a real entity,
@@ -24,12 +24,12 @@ export interface BuiltinRelationOptions {
  * flecs's `IsA`-remove, since there is no inherited data to strip). Pass
  * `"delete"` for strong instance-of (exemplar death cascade-destroys instances).
  */
-export declare function registerIsA(world: ECS, opts?: BuiltinRelationOptions): RelationDef;
+export declare function registerIsA(ecs: ECS, opts?: BuiltinRelationOptions): RelationDef<"exclusive">;
 /**
  * Register a **`ChildOf(child → parent)`** relation — a thin hierarchy link.
  *
- * - a parent's children are `world.sourcesOf(ChildOf, parent)`.
- * - the hierarchy is walked with `world.ancestorsOf(child, ChildOf)` (up to the
+ * - a parent's children are `ecs.relations.sourcesOf(parent, ChildOf)`.
+ * - the hierarchy is walked with `ecs.relations.ancestorsOf(child, ChildOf)` (up to the
  *   root), `rootOf`, and `cascadeOf(root, ChildOf)` (down, breadth-first,
  *   parents before children).
  * - unlike flecs's `ChildOf`, this does **not** scope names/lookup — the engine
@@ -39,5 +39,5 @@ export declare function registerIsA(world: ECS, opts?: BuiltinRelationOptions):
  * its whole subtree (flecs's default). Pass `"clear"` to let children survive as
  * roots, or `"orphan"` to leave a dangling `targetOf`.
  */
-export declare function registerChildOf(world: ECS, opts?: BuiltinRelationOptions): RelationDef;
+export declare function registerChildOf(ecs: ECS, opts?: BuiltinRelationOptions): RelationDef<"exclusive">;
 //# sourceMappingURL=builtin_relations.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"builtin_relations.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/builtin_relations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;KAsBK;AAEL,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D;;gDAEgD;AAChD,MAAM,WAAW,sBAAsB;IACtC;qDACiD;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CACzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,WAAW,CAKlF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,WAAW,CAKtF"}
+{"version":3,"file":"builtin_relations.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/builtin_relations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;KAsBK;AAEL,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D;;gDAEgD;AAChD,MAAM,WAAW,sBAAsB;IACtC;qDACiD;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CACzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,WAAW,CAAC,WAAW,CAAC,CAK7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,WAAW,CAAC,WAAW,CAAC,CAKjG"}

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

@@ -0,0 +1,116 @@
+import { ECS } from './ecs.cjs';
+import { HostCommand, HostCommandQueue, HostCommandSink } from './host_commands.cjs';
+/** One recorded update tick: the commands the apply system drained at this
+ * tick's update-phase head, plus the `dt` passed to `ecs.update(dt)`. Replay
+ * MUST re-issue `update(dt)` for every recorded tick — even an empty one — since
+ * `dt` itself drives the sim (movement, timers), not just the commands. */
+export interface RecordedTick {
+    /** The ECS tick (`ctx.ecsTick`) this bucket belongs to. */
+    readonly tick: number;
+    /** The `dt` `ecs.update(dt)` was called with for this tick. */
+    readonly dt: number;
+    /** Commands applied this tick, in apply order (typed queue first, then ring),
+     * `onSpawned` stripped. */
+    readonly commands: readonly HostCommand[];
+}
+/**
+ * A recorded session: the `seed` it ran under, the seed-time commands drained at
+ * startup, and the per-tick command stream. Plain, serializable data — the
+ * record-side mirror of the typed `HostCommand` vocabulary. Replay it with
+ * {@link replayCommandLog}; persist it with {@link serializeCommandLog}.
+ */
+export interface CommandLog {
+    /** Session seed — the implementer's deterministic input (e.g. an RNG seed).
+     * Opaque to the engine (the core tick takes only `dt`); carried so a replay
+     * rebuilds the world the same way the original was built. */
+    readonly seed: number;
+    /** Commands drained at the PRE_STARTUP head (seed-time edits), applied before
+     * the first update tick. Enqueued BEFORE `ecs.startup()` on replay. */
+    readonly startup: readonly HostCommand[];
+    /** One entry per update tick, in order. */
+    readonly ticks: readonly RecordedTick[];
+}
+/**
+ * The record side of record/replay: a {@link HostCommandSink} the apply system
+ * feeds. Construct one with the session `seed`, hand it to
+ * `installHostCommandSeam(world, { recorder })`, and it accumulates the
+ * command stream as the ECS ticks. Read it back with {@link log} (a live view,
+ * ready to {@link serializeCommandLog serialize}).
+ *
+ * Bucketing: STARTUP-phase drains (which never call {@link openTick}) append to
+ * the {@link startup} bucket; each update-phase drain {@link openTick}s its tick
+ * — multiple update-phase drains in one tick reuse the same bucket (keyed by the
+ * ECS tick), so a frame's commands stay together. The apply system runs every
+ * tick, so every tick's `dt` is recorded even when no commands were applied.
+ *
+ * One recorder per session — don't share across worlds.
+ */
+export declare class HostCommandRecorder implements HostCommandSink {
+    /** Session seed, echoed into the produced {@link CommandLog}. */
+    readonly seed: number;
+    private readonly _startup;
+    private readonly _ticks;
+    /** Where {@link record} appends. Defaults to the startup bucket (seed-time
+     * drains happen before any `openTick`); each `openTick` repoints it. */
+    private sink;
+    constructor(seed?: number);
+    openTick(tick: number, dt: number): void;
+    readonly record: (cmd: HostCommand) => void;
+    /** A live {@link CommandLog} view over the accumulated stream — not a copy.
+     * Serialize it (which deep-copies through JSON) before mutating the world
+     * further if you need a stable snapshot, or use {@link snapshotLog}. */
+    log(): CommandLog;
+    /** A STABLE deep copy of the accumulated stream — safe to hold across
+     * further recording (the safe default; `log()` is the zero-copy live view). */
+    snapshotLog(): CommandLog;
+}
+/** Serialize a {@link CommandLog} to a JSON string. `EntityID` is a plain number
+ * and round-trips as-is; a `ComponentDef` is a callable, so the replacer writes
+ * it as `{ [DEF_TAG]: id }`. (The recorder already stripped `onSpawned`, the
+ * only other non-serializable member.)
+ *
+ * Throws {@link ECS_ERROR.COMMAND_LOG_TAG_COLLISION} if any non-def object in the
+ * log (i.e. a command's `values` map) owns a field named {@link DEF_TAG}: the
+ * reviver tags defs in-band, so such a value would be silently revived as a def,
+ * dropping the real field data. Field names are arbitrary, so this is reachable;
+ * failing here keeps the round-trip lossless instead of corrupting on parse. */
+export declare function serializeCommandLog(log: CommandLog): string;
+/** Parse a {@link CommandLog} from {@link serializeCommandLog} output. */
+export declare function deserializeCommandLog(json: string): CommandLog;
+/** Outcome of {@link replayCommandLog}. */
+export interface ReplayResult {
+    /** Seed-time commands re-applied before the first tick. */
+    readonly startupCommands: number;
+    /** Update ticks replayed. */
+    readonly ticks: number;
+    /** Per-tick `stateHash` captured after each `update`, in tick order — empty
+     * unless the world is deterministic (or `hash` was forced). Compare against
+     * the original run's per-tick hashes to prove the replay matched (ADR-0020). */
+    readonly stateHashes: readonly number[];
+}
+/** Options for {@link replayCommandLog}. */
+export interface ReplayOptions {
+    /** Capture `ecs.snapshots.stateHash()` after each tick. Defaults to the world's
+     * `deterministic` flag — a deterministic world is hashed, a non-deterministic
+     * one is not (its `stateHash` would throw, ADR-0020). Force `true` only on a
+     * deterministic world. */
+    readonly hash?: boolean;
+}
+/**
+ * Replay a recorded {@link CommandLog} against `world`, reproducing the original
+ * session tick-for-tick. `world` must be FRESH and NOT yet started, built
+ * identically to the recorded run (same components registered in the same order,
+ * same systems, same `seed` from `log.seed`) and seam-installed — pass the
+ * `HostCommandQueue` `installHostCommandSeam` returned as `queue`. The driver
+ * owns startup: it enqueues the seed-time commands, calls `ecs.startup()`
+ * (which drains them at PRE_STARTUP), then for each recorded tick enqueues that
+ * tick's commands and calls `ecs.update(dt)` with the recorded `dt`.
+ *
+ * Determinism (ADR-0020): with `{ deterministic: true }` the per-tick
+ * `stateHashes` this returns must equal the original run's — that equality is
+ * replay fidelity. Identity caveat (§85): a despawned-then-respawned entity gets
+ * a fresh id, but because spawn order is reproduced, every recorded id still
+ * resolves to the same entity on replay.
+ */
+export declare function replayCommandLog(ecs: ECS, queue: HostCommandQueue, log: CommandLog, opts?: ReplayOptions): ReplayResult;
+//# sourceMappingURL=command_log.d.ts.map

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

@@ -1,13 +1,13 @@
-import { ECS } from './ecs';
-import { HostCommand, HostCommandQueue, HostCommandSink } from './host_commands';
+import { ECS } from './ecs.js';
+import { HostCommand, HostCommandQueue, HostCommandSink } from './host_commands.js';
 /** One recorded update tick: the commands the apply system drained at this
- * tick's update-phase head, plus the `dt` passed to `world.update(dt)`. Replay
+ * tick's update-phase head, plus the `dt` passed to `ecs.update(dt)`. Replay
  * MUST re-issue `update(dt)` for every recorded tick — even an empty one — since
  * `dt` itself drives the sim (movement, timers), not just the commands. */
 export interface RecordedTick {
     /** The ECS tick (`ctx.ecsTick`) this bucket belongs to. */
     readonly tick: number;
-    /** The `dt` `world.update(dt)` was called with for this tick. */
+    /** The `dt` `ecs.update(dt)` was called with for this tick. */
     readonly dt: number;
     /** Commands applied this tick, in apply order (typed queue first, then ring),
      * `onSpawned` stripped. */
@@ -25,7 +25,7 @@ export interface CommandLog {
      * rebuilds the world the same way the original was built. */
     readonly seed: number;
     /** Commands drained at the PRE_STARTUP head (seed-time edits), applied before
-     * the first update tick. Enqueued BEFORE `world.startup()` on replay. */
+     * the first update tick. Enqueued BEFORE `ecs.startup()` on replay. */
     readonly startup: readonly HostCommand[];
     /** One entry per update tick, in order. */
     readonly ticks: readonly RecordedTick[];
@@ -58,8 +58,11 @@ export declare class HostCommandRecorder implements HostCommandSink {
     readonly record: (cmd: HostCommand) => void;
     /** A live {@link CommandLog} view over the accumulated stream — not a copy.
      * Serialize it (which deep-copies through JSON) before mutating the world
-     * further if you need a stable snapshot. */
+     * further if you need a stable snapshot, or use {@link snapshotLog}. */
     log(): CommandLog;
+    /** A STABLE deep copy of the accumulated stream — safe to hold across
+     * further recording (the safe default; `log()` is the zero-copy live view). */
+    snapshotLog(): CommandLog;
 }
 /** Serialize a {@link CommandLog} to a JSON string. `EntityID` is a plain number
  * and round-trips as-is; a `ComponentDef` is a callable, so the replacer writes
@@ -87,7 +90,7 @@ export interface ReplayResult {
 }
 /** Options for {@link replayCommandLog}. */
 export interface ReplayOptions {
-    /** Capture `world.stateHash()` after each tick. Defaults to the world's
+    /** Capture `ecs.snapshots.stateHash()` after each tick. Defaults to the world's
      * `deterministic` flag — a deterministic world is hashed, a non-deterministic
      * one is not (its `stateHash` would throw, ADR-0020). Force `true` only on a
      * deterministic world. */
@@ -99,9 +102,9 @@ export interface ReplayOptions {
  * identically to the recorded run (same components registered in the same order,
  * same systems, same `seed` from `log.seed`) and seam-installed — pass the
  * `HostCommandQueue` `installHostCommandSeam` returned as `queue`. The driver
- * owns startup: it enqueues the seed-time commands, calls `world.startup()`
+ * owns startup: it enqueues the seed-time commands, calls `ecs.startup()`
  * (which drains them at PRE_STARTUP), then for each recorded tick enqueues that
- * tick's commands and calls `world.update(dt)` with the recorded `dt`.
+ * tick's commands and calls `ecs.update(dt)` with the recorded `dt`.
  *
  * Determinism (ADR-0020): with `{ deterministic: true }` the per-tick
  * `stateHashes` this returns must equal the original run's — that equality is
@@ -109,5 +112,5 @@ export interface ReplayOptions {
  * a fresh id, but because spawn order is reproduced, every recorded id still
  * resolves to the same entity on replay.
  */
-export declare function replayCommandLog(world: ECS, queue: HostCommandQueue, log: CommandLog, opts?: ReplayOptions): ReplayResult;
+export declare function replayCommandLog(ecs: ECS, queue: HostCommandQueue, log: CommandLog, opts?: ReplayOptions): ReplayResult;
 //# sourceMappingURL=command_log.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"command_log.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/command_log.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtF;;;2EAG2E;AAC3E,MAAM,WAAW,YAAY;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;+BAC2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B;;iEAE6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;CACxC;AAiBD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IAC1D,iEAAiE;IACjE,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C;4EACwE;IACxE,OAAO,CAAC,IAAI,CAAgC;gBAEhC,IAAI,SAAI;IAIpB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAaxC,QAAQ,CAAC,MAAM,QAAS,WAAW,KAAG,IAAI,CAExC;IAEF;;gDAE4C;IAC5C,GAAG,IAAI,UAAU;CAGjB;AAYD;;;;;;;;;gFASgF;AAChF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAqB3D;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAW9D;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;oFAEgF;IAChF,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC7B;;;8BAG0B;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,GAAG,EACV,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,UAAU,EACf,IAAI,CAAC,EAAE,aAAa,GAClB,YAAY,CAcd"}
+{"version":3,"file":"command_log.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/command_log.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtF;;;2EAG2E;AAC3E,MAAM,WAAW,YAAY;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;+BAC2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B;;iEAE6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;2EACuE;IACvE,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;CACxC;AAiBD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IAC1D,iEAAiE;IACjE,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C;4EACwE;IACxE,OAAO,CAAC,IAAI,CAAgC;gBAEhC,IAAI,SAAI;IAIpB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAaxC,QAAQ,CAAC,MAAM,QAAS,WAAW,KAAG,IAAI,CAExC;IAEF;;4EAEwE;IACxE,GAAG,IAAI,UAAU;IAIjB;mFAC+E;IAC/E,WAAW,IAAI,UAAU;CAOzB;AAYD;;;;;;;;;gFASgF;AAChF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAqB3D;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAW9D;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;oFAEgF;IAChF,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC7B;;;8BAG0B;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,UAAU,EACf,IAAI,CAAC,EAAE,aAAa,GAClB,YAAY,CAcd"}