@oasys/oecs 0.3.1 → 0.5.0

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

@@ -0,0 +1,43 @@
+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. */
+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.map

@@ -0,0 +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,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

@@ -0,0 +1,116 @@
+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 `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.map

@@ -0,0 +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,+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"}

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

@@ -0,0 +1,176 @@
+import { Brand, TypedArrayTag } from '../../type_primitives/index.cjs';
+export type ComponentID = Brand<number, "component_id">;
+export declare const asComponentId: (value: number) => ComponentID;
+/** Core schema type: maps field names to typed array tags. */
+export type ComponentSchema = Readonly<Record<string, TypedArrayTag>>;
+/** Compile-time tag → TypedArray mapping. */
+export type TagToTypedArray = {
+    f32: Float32Array;
+    f64: Float64Array;
+    i8: Int8Array;
+    i16: Int16Array;
+    i32: Int32Array;
+    u8: Uint8Array;
+    u16: Uint16Array;
+    u32: Uint32Array;
+};
+/** Maps schema fields to their value object: { x: number, y: number }. */
+export type FieldValues<S extends ComponentSchema> = {
+    readonly [K in keyof S]: number;
+};
+/**
+ * Values argument tuple for attaching a component of schema `S` — empty for a
+ * tag, a single optional partial-values map otherwise. A tag schema
+ * (`Record<string, never>`) would otherwise degenerate: `keyof` an
+ * index-signature record is `string`, so `Partial<FieldValues<…>>` collapses to
+ * `Record<string, number>` and `Frozen({ anything: 1 })` compiles. The
+ * conditional forbids values on tags outright; a schema-erased `ComponentDef`
+ * falls into the valued branch, so untyped call sites keep the loose shape.
+ */
+export type ValuesArg<S extends ComponentSchema> = S extends Record<string, never> ? [] : [values?: Partial<FieldValues<S>>];
+/**
+ * `FieldValues` for APIs where the values object is required and complete
+ * (`addComponent`'s valued overload, the host-seam `SpawnEntry`). Guards the
+ * same tag degeneracy as `ValuesArg`: a tag accepts only the empty object
+ * (`Record<string, never>` — every property typed `never`), so
+ * `addComponent(e, Frozen, { x: 1 })` is a compile error while the
+ * tag-overload-less call sites can still pass `{}`.
+ */
+export type CompleteFieldValues<S extends ComponentSchema> = S extends Record<string, never> ? Record<string, never> : FieldValues<S>;
+/**
+ * Trailing-argument tuple for the attach surfaces (`ctx.commands.add`'s
+ * explicit-values form, `ctx.addSparse`): a tag takes NO values argument, a valued schema REQUIRES a
+ * complete one. Encodes the former tag/valued overload pair as one signature,
+ * which the typed system seam needs — its `def` parameter is a single
+ * declared-access-constrained type param, and per-schema overloads would
+ * re-introduce the tag-vs-valued split on top of it.
+ */
+export type AttachValuesArg<S extends ComponentSchema> = S extends Record<string, never> ? [] : [values: CompleteFieldValues<S>];
+/** Maps schema fields to their specific typed array columns. */
+export type ColumnsForSchema<S extends ComponentSchema> = {
+    readonly [K in keyof S]: TagToTypedArray[S[K]];
+};
+/**
+ * Mutable sibling of `ColumnsForSchema` — the field-keyed column group handed
+ * back by `eachChunk`'s `cols.mut(def)` (no `readonly`, since the whole point
+ * is in-place writes). The change-tick is stamped once when the group is
+ * resolved, so the per-row loop is plain typed-array indexing (§eachChunk).
+ */
+export type MutableColumnsForSchema<S extends ComponentSchema> = {
+    [K in keyof S]: TagToTypedArray[S[K]];
+};
+declare const __schema: unique symbol;
+/**
+ * A component handle. **Callable**: `Pos({ x, y })` produces a `Bundle` (omitted
+ * fields zero-fill at attach), so one varargs shape — `spawn(Pos({x,y}),
+ * Vel({vx:1}), IsEnemy)` — replaces the older incompatible attach shapes. A bare
+ * `Pos` (uncalled) still stands in for a tag / all-zero values wherever a
+ * `BundleOrDef` is accepted.
+ *
+ * The numeric component id lives on `.id` (registration order). Consumers treat
+ * the def as an opaque handle; internal code reads `def.id` where it needs the
+ * raw id. The call signature's `S` makes `ComponentDef<{x:"f64"}>` distinct from
+ * `ComponentDef<{vx:"f64"}>`.
+ *
+ * The optional `[__schema]` slot never exists at runtime; it re-states `S` in a
+ * covariant tuple position so that a TAG def type is not a universal assignment
+ * sink. Through the call signature alone every def is assignable to
+ * `ComponentDef<Record<string, never>>` (the tag callable takes no required
+ * args and any `Bundle` satisfies its return), which would let ONE tag in a
+ * system's declared-access union admit every component at compile time
+ * (§typestate — `DeclaredRead` and friends in system.ts). With the slot, a
+ * valued schema is not assignable to the tag schema (`"f64" ⊀ never`), while
+ * schema erasure (`ComponentDef<S>` → bare `ComponentDef`) still works because
+ * every schema is assignable to `ComponentSchema`.
+ *
+ * Build one with `makeComponentDef`; never construct by hand.
+ */
+export interface ComponentDef<S extends ComponentSchema = ComponentSchema> {
+    (...values: ValuesArg<S>): Bundle<S>;
+    readonly id: ComponentID;
+    readonly [__schema]?: [S];
+}
+/**
+ * Recover a def's schema type: `SchemaOf<typeof Pos>` is `{x:"f64", y:"f64"}`.
+ * The typed `SystemContext` methods (§typestate) constrain their `def`
+ * parameter to the system's declared-access union and use this to type the
+ * field argument, in place of taking `ComponentDef<S>` directly.
+ */
+export type SchemaOf<D> = D extends ComponentDef<infer S extends ComponentSchema> ? S : never;
+/**
+ * `unknown` if `D` is one of the query's declared terms, else an error tuple —
+ * the query-seam sibling of system.ts's `DeclaredRead` (§typestate,
+ * POLISH_AUDIT #6). `Query.eachChunk`'s cursor and `ArchetypeView`'s column
+ * accessors intersect this into their `def` parameter so fetching a component
+ * that is NOT a term of the iterating query fails to compile (previously
+ * caught only by the dev-mode access check, and only when the system's
+ * declaration was itself wrong). Same encoding rules as the system asserts:
+ * stable `D extends ComponentDef<any>` constraints keep instantiations
+ * mutually assignable, and the conditional keys on the signature's own `D`.
+ */
+export type DeclaredQueryTerm<Defs extends readonly ComponentDef<any>[], D> = [D] extends [
+    Defs[number]
+] ? unknown : ["component is not a term of this query — add it with .and(...)", D];
+/** Options bag accepted by `registerComponent` / `registerSparseComponent`. */
+export interface ComponentRegisterOptions {
+    /** Debug label for diagnostics — errors then read `'Pos' (component 5)`
+     * instead of `component 5`. Never affects behaviour, layout, or hashing. */
+    readonly name?: string;
+}
+/**
+ * Schema-erased component handle — just the `.id`. Internal, schema-agnostic
+ * code (access checks, dirty-set notes, field-id lookup) takes this instead of
+ * `ComponentDef`: the callable signature makes `ComponentDef<S>` *invariant* in
+ * `S` (a generic `ComponentDef<S>` is not assignable to `ComponentDef`), but
+ * every `ComponentDef<S>` is assignable to `ComponentHandle` because it carries
+ * `.id`. Use it wherever only the id is read.
+ */
+export type ComponentHandle = {
+    readonly id: ComponentID;
+};
+/**
+ * Mint a callable `ComponentDef` for a freshly-registered component id. The
+ * returned function produces a `Bundle` when called (`Pos({x,y})`) and carries
+ * its numeric id on a non-enumerable `.id` (invisible to spreads / `JSON`).
+ * The single cast bridges the function value to the branded handle type — the
+ * `.id` is installed at runtime by `defineProperty` (§10c branded-ID boundary).
+ */
+export declare function makeComponentDef<S extends ComponentSchema>(id: ComponentID): ComponentDef<S>;
+export interface Bundle<S extends ComponentSchema = ComponentSchema> {
+    readonly def: ComponentDef<S>;
+    readonly values: Partial<FieldValues<S>>;
+}
+/** Either a populated bundle or a bare def (tag / all-fields-zero). */
+export type BundleOrDef<S extends ComponentSchema = ComponentSchema> = Bundle<S> | ComponentDef<S>;
+/** Pair a component def with field values to attach. Omitted fields zero-fill;
+ * a tag def takes no values (see `ValuesArg`). */
+export declare function bundle<S extends ComponentSchema>(def: ComponentDef<S>, ...values: ValuesArg<S>): Bundle<S>;
+/** Extract the def from a `BundleOrDef`. A bare def is the callable; a bundle a plain object. */
+export declare function bundleDef(item: BundleOrDef): ComponentDef;
+/** Extract the values from a `BundleOrDef` (a bare def contributes no values). */
+export declare function bundleValues(item: BundleOrDef): Readonly<Record<string, number>>;
+/**
+ * Compile-time readonly view of a typed array column. Blocks index writes at
+ * the type layer.
+ *
+ * **Advisory, not a runtime barrier:** the value behind this type is the live
+ * mutable backing `TypedArray` (`Archetype.getColumnRead` returns
+ * `.buf as unknown as ReadonlyColumn`), so a §10c-policed cast can still write
+ * through. For mutation use the mutable `Archetype.getColumn` (tick-bumping).
+ * Enforced by the escape-hatch lint, not the runtime.
+ */
+export interface ReadonlyColumn {
+    readonly [index: number]: number;
+    readonly length: number;
+}
+/**
+ * Compile-time readonly view of a Uint32Array. Blocks index writes at the type
+ * layer. **Advisory, not a runtime barrier** — same caveat as `ReadonlyColumn`:
+ * the underlying value is the live mutable buffer.
+ */
+export interface ReadonlyUint32Array {
+    readonly [index: number]: number;
+    readonly length: number;
+}
+export {};
+//# sourceMappingURL=component.d.ts.map