@oasys/oecs 0.5.3 → 0.6.0

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

@@ -0,0 +1,36 @@
+import { ArchetypeView } from './archetype.cjs';
+import { ComponentDef } from './component.cjs';
+import { Query } from './query.cjs';
+import { ChunkColumns } from './chunk_columns.cjs';
+export declare class ChangedQuery<Defs extends readonly ComponentDef[]> {
+    private readonly _query;
+    private readonly _changedIds;
+    constructor(query: Query<Defs>, changedIds: number[]);
+    /** Also require these components (mirrors `Query.and`). */
+    and<D extends ComponentDef[]>(...comps: D): ChangedQuery<[...Defs, ...D]>;
+    /** Exclude archetypes holding any of these (mirrors `Query.not`). */
+    not(...comps: ComponentDef[]): ChangedQuery<Defs>;
+    /** Require at least one of these (mirrors `Query.or`). */
+    or(...comps: ComponentDef[]): ChangedQuery<Defs>;
+    /** Permit optional-component data access in the loop (mirrors `Query.optional`). */
+    optional(...defs: ComponentDef[]): ChangedQuery<Defs>;
+    forEach(cb: (arch: ArchetypeView<Defs>) => void): void;
+    /** The chunk form of `forEach`: the changed archetypes, as column groups.
+     * The row grain sits inside: `cols.ticksRead(def)` is the row tick column,
+     * and a row above `cols.since` changed since the previous run of the
+     * system. `def` needs row ticks (`ecs.trackRows`). Same include-disabled
+     * handling as `Query.forEachChunk`. */
+    forEachChunk(cb: (cols: ChunkColumns<Defs>, count: number) => void): void;
+    /** @internal, the body of `forEachChunk`: `Query._forEachChunkInner` with
+     * the change-tick filter of `forEach` in front of each archetype. */
+    private _forEachChunkInner;
+    /** @internal, cold `includeDisabled` wrapper, split out of `forEach`
+     * so the all-rows flag dance stays out of the inlined hot body. */
+    private _forEachIncludeDisabled;
+    /** @internal, the `includeDisabled` delegate for `forEach`. The
+     * default path inlines this body directly into `forEach` to dodge a
+     * megamorphic delegate hop. This copy survives only for the rare all-rows
+     * path, which needs the `_setIterAllRows` `finally` wrap. */
+    private _forEachInner;
+}
+//# sourceMappingURL=changed_query.d.ts.map

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

@@ -0,0 +1,36 @@
+import { ArchetypeView } from './archetype.js';
+import { ComponentDef } from './component.js';
+import { Query } from './query.js';
+import { ChunkColumns } from './chunk_columns.js';
+export declare class ChangedQuery<Defs extends readonly ComponentDef[]> {
+    private readonly _query;
+    private readonly _changedIds;
+    constructor(query: Query<Defs>, changedIds: number[]);
+    /** Also require these components (mirrors `Query.and`). */
+    and<D extends ComponentDef[]>(...comps: D): ChangedQuery<[...Defs, ...D]>;
+    /** Exclude archetypes holding any of these (mirrors `Query.not`). */
+    not(...comps: ComponentDef[]): ChangedQuery<Defs>;
+    /** Require at least one of these (mirrors `Query.or`). */
+    or(...comps: ComponentDef[]): ChangedQuery<Defs>;
+    /** Permit optional-component data access in the loop (mirrors `Query.optional`). */
+    optional(...defs: ComponentDef[]): ChangedQuery<Defs>;
+    forEach(cb: (arch: ArchetypeView<Defs>) => void): void;
+    /** The chunk form of `forEach`: the changed archetypes, as column groups.
+     * The row grain sits inside: `cols.ticksRead(def)` is the row tick column,
+     * and a row above `cols.since` changed since the previous run of the
+     * system. `def` needs row ticks (`ecs.trackRows`). Same include-disabled
+     * handling as `Query.forEachChunk`. */
+    forEachChunk(cb: (cols: ChunkColumns<Defs>, count: number) => void): void;
+    /** @internal, the body of `forEachChunk`: `Query._forEachChunkInner` with
+     * the change-tick filter of `forEach` in front of each archetype. */
+    private _forEachChunkInner;
+    /** @internal, cold `includeDisabled` wrapper, split out of `forEach`
+     * so the all-rows flag dance stays out of the inlined hot body. */
+    private _forEachIncludeDisabled;
+    /** @internal, the `includeDisabled` delegate for `forEach`. The
+     * default path inlines this body directly into `forEach` to dodge a
+     * megamorphic delegate hop. This copy survives only for the rare all-rows
+     * path, which needs the `_setIterAllRows` `finally` wrap. */
+    private _forEachInner;
+}
+//# sourceMappingURL=changed_query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"changed_query.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/changed_query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;KAYK;AAEL,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAK/C,qBAAa,YAAY,CAAC,IAAI,SAAS,SAAS,YAAY,EAAE;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;gBAE3B,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE;IAwBpD,2DAA2D;IACpD,GAAG,CAAC,CAAC,SAAS,YAAY,EAAE,EAAE,GAAG,KAAK,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IAIhF,qEAAqE;IAC9D,GAAG,CAAC,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC;IAIxD,0DAA0D;IACnD,EAAE,CAAC,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC;IAIvD,oFAAoF;IAC7E,QAAQ,CAAC,GAAG,IAAI,EAAE,YAAY,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC;IAIrD,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,KAAK,IAAI,GAAG,IAAI;IAqD7D;;;;2CAIuC;IAChC,YAAY,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAahF;yEACqE;IACrE,OAAO,CAAC,kBAAkB;IA6C1B;uEACmE;IACnE,OAAO,CAAC,uBAAuB;IAS/B;;;iEAG6D;IAC7D,OAAO,CAAC,aAAa;CAyCrB"}

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

@@ -0,0 +1,49 @@
+import { Archetype } from './archetype.cjs';
+import { ColumnsForSchema, ComponentDef, DeclaredQueryTerm, MutableColumnsForSchema, SchemaOf } from './component.cjs';
+import { QueryResolver } from './query_cache.cjs';
+/**
+ * forEachChunk cursor. One instance is allocated per `forEachChunk`
+ * pass and reused across every matched archetype in that pass. Only `arch` and
+ * `tick` are re-pointed per archetype, so the inner loop allocates nothing.
+ * Per-call (not cached on the query) so a nested `forEachChunk` on the same query
+ * gets its own cursor and can't re-point an outer pass's position. `.mut(def)`
+ * and `.read(def)` resolve a whole component's columns at once into a field-keyed
+ * object (a per-archetype-per-component cache refreshed in place), hiding the
+ * change tick. Destructure the group immediately. Don't retain it across calls.
+ */
+export declare class ChunkColumns<out Defs extends readonly ComponentDef<any>[] = readonly ComponentDef<any>[]> {
+    /** @internal */ arch: Archetype;
+    /** The change tick this pass stamps. Store it into a row of `ticks(def)`
+     * to record that row for an entity-level `onSet`. */
+    tick: number;
+    /** The change tick of the previous run of the system this pass runs in,
+     * and 0 on its first run or on the host. A row of `ticksRead(def)` above it
+     * changed since that run. */
+    since: number;
+    /** @internal */ resolver: QueryResolver;
+    /** Mutable column group, `const { x, y } = cols.mut(Pos)`. Stamps the tick.
+     * `def` must be a term of the iterating query. */
+    mut<D extends ComponentDef<any>>(def: D & DeclaredQueryTerm<Defs, D>): MutableColumnsForSchema<SchemaOf<D>>;
+    /** Read-only column group, `const { vx, vy } = cols.read(Vel)`. No tick bump.
+     * `def` must be a term of the iterating query. */
+    read<D extends ComponentDef<any>>(def: D & DeclaredQueryTerm<Defs, D>): ColumnsForSchema<SchemaOf<D>>;
+    /** The row tick column of `def` for this archetype, the record a raw column
+     * loop makes for an entity-level `onSet`: `t[i] = cols.tick` beside the
+     * write of row `i`. One typed-array store per row, where `ctx.markChanged`
+     * is a call and a list push. Taking the column marks the archetype changed
+     * and asks the drain of this frame to scan every archetype of `def` that a
+     * writer stamped, so take it only in a loop that stores into it. Throws
+     * when no entity-level `onSet` observer tracks `def`, because the column
+     * exists for tracked components only. `def` must be a term of the
+     * iterating query. */
+    ticks<D extends ComponentDef<any>>(def: D & DeclaredQueryTerm<Defs, D>): Uint32Array;
+    /** The row tick column of `def` for this archetype, read-only: the row
+     * grain of change detection. A row `i` with `t[i] > cols.since` changed
+     * since the previous run of this system, through any write path that
+     * records (`setField`, `ref`, a cursor, `markChanged`, or a store into
+     * `ticks(def)`). No stamp, no scan request. Throws when `def` has no row
+     * ticks: `ecs.trackRows(def)` turns them on. `def` must be a term of the
+     * iterating query. */
+    ticksRead<D extends ComponentDef<any>>(def: D & DeclaredQueryTerm<Defs, D>): Readonly<Uint32Array>;
+}
+//# sourceMappingURL=chunk_columns.d.ts.map

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

@@ -0,0 +1,49 @@
+import { Archetype } from './archetype.js';
+import { ColumnsForSchema, ComponentDef, DeclaredQueryTerm, MutableColumnsForSchema, SchemaOf } from './component.js';
+import { QueryResolver } from './query_cache.js';
+/**
+ * forEachChunk cursor. One instance is allocated per `forEachChunk`
+ * pass and reused across every matched archetype in that pass. Only `arch` and
+ * `tick` are re-pointed per archetype, so the inner loop allocates nothing.
+ * Per-call (not cached on the query) so a nested `forEachChunk` on the same query
+ * gets its own cursor and can't re-point an outer pass's position. `.mut(def)`
+ * and `.read(def)` resolve a whole component's columns at once into a field-keyed
+ * object (a per-archetype-per-component cache refreshed in place), hiding the
+ * change tick. Destructure the group immediately. Don't retain it across calls.
+ */
+export declare class ChunkColumns<out Defs extends readonly ComponentDef<any>[] = readonly ComponentDef<any>[]> {
+    /** @internal */ arch: Archetype;
+    /** The change tick this pass stamps. Store it into a row of `ticks(def)`
+     * to record that row for an entity-level `onSet`. */
+    tick: number;
+    /** The change tick of the previous run of the system this pass runs in,
+     * and 0 on its first run or on the host. A row of `ticksRead(def)` above it
+     * changed since that run. */
+    since: number;
+    /** @internal */ resolver: QueryResolver;
+    /** Mutable column group, `const { x, y } = cols.mut(Pos)`. Stamps the tick.
+     * `def` must be a term of the iterating query. */
+    mut<D extends ComponentDef<any>>(def: D & DeclaredQueryTerm<Defs, D>): MutableColumnsForSchema<SchemaOf<D>>;
+    /** Read-only column group, `const { vx, vy } = cols.read(Vel)`. No tick bump.
+     * `def` must be a term of the iterating query. */
+    read<D extends ComponentDef<any>>(def: D & DeclaredQueryTerm<Defs, D>): ColumnsForSchema<SchemaOf<D>>;
+    /** The row tick column of `def` for this archetype, the record a raw column
+     * loop makes for an entity-level `onSet`: `t[i] = cols.tick` beside the
+     * write of row `i`. One typed-array store per row, where `ctx.markChanged`
+     * is a call and a list push. Taking the column marks the archetype changed
+     * and asks the drain of this frame to scan every archetype of `def` that a
+     * writer stamped, so take it only in a loop that stores into it. Throws
+     * when no entity-level `onSet` observer tracks `def`, because the column
+     * exists for tracked components only. `def` must be a term of the
+     * iterating query. */
+    ticks<D extends ComponentDef<any>>(def: D & DeclaredQueryTerm<Defs, D>): Uint32Array;
+    /** The row tick column of `def` for this archetype, read-only: the row
+     * grain of change detection. A row `i` with `t[i] > cols.since` changed
+     * since the previous run of this system, through any write path that
+     * records (`setField`, `ref`, a cursor, `markChanged`, or a store into
+     * `ticks(def)`). No stamp, no scan request. Throws when `def` has no row
+     * ticks: `ecs.trackRows(def)` turns them on. `def` must be a term of the
+     * iterating query. */
+    ticksRead<D extends ComponentDef<any>>(def: D & DeclaredQueryTerm<Defs, D>): Readonly<Uint32Array>;
+}
+//# sourceMappingURL=chunk_columns.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_columns.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/chunk_columns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;KASK;AAEL,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EACX,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,EACvB,QAAQ,EACR,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAMnD;;;;;;;;;GASG;AACH,qBAAa,YAAY,CACxB,GAAG,CAAC,IAAI,SAAS,SAAS,YAAY,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,YAAY,CAAC,GAAG,CAAC,EAAE;IAE5E,gBAAgB,CAAC,IAAI,EAAG,SAAS,CAAC;IAClC;yDACqD;IACrD,IAAI,SAAK;IACT;;iCAE6B;IAC7B,KAAK,SAAK;IACV,gBAAgB,CAAC,QAAQ,EAAG,aAAa,CAAC;IAE1C;sDACkD;IAC3C,GAAG,CAAC,CAAC,SAAS,YAAY,CAAC,GAAG,CAAC,EACrC,GAAG,EAAE,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,GACjC,uBAAuB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAIvC;sDACkD;IAC3C,IAAI,CAAC,CAAC,SAAS,YAAY,CAAC,GAAG,CAAC,EACtC,GAAG,EAAE,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,GACjC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAIhC;;;;;;;;0BAQsB;IACf,KAAK,CAAC,CAAC,SAAS,YAAY,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,WAAW;IAW3F;;;;;;0BAMsB;IACf,SAAS,CAAC,CAAC,SAAS,YAAY,CAAC,GAAG,CAAC,EAC3C,GAAG,EAAE,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,GACjC,QAAQ,CAAC,WAAW,CAAC;CAQxB"}

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

@@ -2,8 +2,8 @@ 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. */
+ * must re-issue `update(dt)` for every recorded tick, even an empty one, since
+ * `dt` itself drives the sim (movement, timers), not only the commands. */
 export interface RecordedTick {
     /** The ECS tick (`ctx.ecsTick`) this bucket belongs to. */
     readonly tick: number;
@@ -15,35 +15,35 @@ export interface RecordedTick {
 }
 /**
  * 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
+ * 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}.
+ * {@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
+    /** Session seed, the implementer's deterministic input (e.g. an RNG seed).
+     * Opaque to the engine, because 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. */
+    /** 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
+ * The record side of record and 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
+ * Bucketing: a `STARTUP`-phase drain never calls {@link openTick}, so it appends 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.
+ * One recorder per session, don't share across worlds.
  */
 export declare class HostCommandRecorder implements HostCommandSink {
     /** Session seed, echoed into the produced {@link CommandLog}. */
@@ -51,29 +51,29 @@ export declare class HostCommandRecorder implements HostCommandSink {
     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;
+     * 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.
+    /** 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). */
+    /** 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
+ * 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. */
+ * 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;
@@ -83,32 +83,32 @@ export interface ReplayResult {
     readonly startupCommands: number;
     /** Update ticks replayed. */
     readonly ticks: number;
-    /** Per-tick `stateHash` captured after each `update`, in tick order — empty
+    /** 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). */
+     * the original run's per-tick hashes to prove the replay matched. */
     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` flag, a deterministic world is hashed, a non-deterministic
+     * one is not (its `stateHash` would throw). 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
+ * 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
+ * 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
+ * Determinism: with `{ deterministic: true }` the per-tick
+ * `stateHashes` this returns must equal the original run's, that equality is
+ * replay fidelity. Identity caveat: 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.
  */

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

@@ -2,8 +2,8 @@ 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. */
+ * must re-issue `update(dt)` for every recorded tick, even an empty one, since
+ * `dt` itself drives the sim (movement, timers), not only the commands. */
 export interface RecordedTick {
     /** The ECS tick (`ctx.ecsTick`) this bucket belongs to. */
     readonly tick: number;
@@ -15,35 +15,35 @@ export interface RecordedTick {
 }
 /**
  * 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
+ * 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}.
+ * {@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
+    /** Session seed, the implementer's deterministic input (e.g. an RNG seed).
+     * Opaque to the engine, because 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. */
+    /** 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
+ * The record side of record and 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
+ * Bucketing: a `STARTUP`-phase drain never calls {@link openTick}, so it appends 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.
+ * One recorder per session, don't share across worlds.
  */
 export declare class HostCommandRecorder implements HostCommandSink {
     /** Session seed, echoed into the produced {@link CommandLog}. */
@@ -51,29 +51,29 @@ export declare class HostCommandRecorder implements HostCommandSink {
     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;
+     * 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.
+    /** 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). */
+    /** 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
+ * 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. */
+ * 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;
@@ -83,32 +83,32 @@ export interface ReplayResult {
     readonly startupCommands: number;
     /** Update ticks replayed. */
     readonly ticks: number;
-    /** Per-tick `stateHash` captured after each `update`, in tick order — empty
+    /** 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). */
+     * the original run's per-tick hashes to prove the replay matched. */
     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` flag, a deterministic world is hashed, a non-deterministic
+     * one is not (its `stateHash` would throw). 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
+ * 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
+ * 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
+ * Determinism: with `{ deterministic: true }` the per-tick
+ * `stateHashes` this returns must equal the original run's, that equality is
+ * replay fidelity. Identity caveat: 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.
  */

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,+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"}
+{"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,KAAK,CAAgC;gBAEjC,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;;yEAEqE;IACrE,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"}