@oasys/oecs 0.3.1 → 0.4.0

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

@@ -0,0 +1,179 @@
+import { InPlaceBufferAllocator } from '../store';
+/** Default byte ceiling of the growable backing — mirrors
+ * `growableSabAllocator`'s default (see its doc comment for the measured
+ * footprint analysis that makes 256 MiB structurally unreachable). */
+export declare const DEFAULT_ECS_CAP_BYTES: number;
+/** Headroom multiplier applied to a budget's live column bytes: capacity
+ * doubling plus abandoned in-place holes bound worst-case footprint at ~3×
+ * live data (footprint analysis in `growableSabAllocator`'s doc). */
+export declare const BUDGET_GROWTH_HEADROOM = 3;
+/** Default average fully-populated row stride assumed by the budget arm.
+ * The instrumented 2-party workload measured ~49 B/entity; 64 rounds up. */
+export declare const BUDGET_DEFAULT_BYTES_PER_ENTITY = 64;
+/** Default archetype spread assumed by the budget arm when the consumer
+ * doesn't declare one. Drives only the derived per-archetype column
+ * capacity, not correctness — an under-declared spread just means earlier
+ * (amortised) column doubling. */
+export declare const BUDGET_DEFAULT_ARCHETYPES = 8;
+/** Sizing intent: "I expect a world about this big." The engine derives
+ * column capacity, entity-index reservation, and the byte cap from it, and
+ * cap errors are phrased against this budget. */
+export interface EntityBudget {
+    /** Expected peak live entities — the one number most callers know.
+     * Bounded by the EntityID 20-bit index space (1<<20). */
+    readonly entities: number;
+    /** Expected distinct archetypes the entities spread across.
+     * Default `BUDGET_DEFAULT_ARCHETYPES`. */
+    readonly archetypes?: number;
+    /** Average fully-populated row stride in bytes.
+     * Default `BUDGET_DEFAULT_BYTES_PER_ENTITY`. */
+    readonly bytesPerEntity?: number;
+}
+/** WASM-backed memory, first-class (#682). Either bring your own shared
+ * `WebAssembly.Memory` (the server match context does — its sim factory
+ * owns the memory), or declare page bounds and let the engine construct
+ * it — replacing the hand-wired incantation that previously lived only in
+ * `workbench/ecs/scripts/run-memory.ts`. */
+export type WasmMemoryArm = {
+    readonly memory: WebAssembly.Memory;
+    readonly initialPages?: never;
+    readonly maximumPages?: never;
+} | {
+    readonly maximumPages: number;
+    readonly initialPages?: number;
+    readonly memory?: never;
+};
+/** Pure-TS **heap** backing (#643 / ADR-0018 §1B): a plain resizable
+ * `ArrayBuffer` instead of a `SharedArrayBuffer`. Needs no cross-origin
+ * isolation (COOP/COEP) and is the intended default for embedders that can't
+ * set those headers (the oecs profile). Trade-off: no worker offload and no
+ * WASM compute backend — both require a transferable `SharedArrayBuffer`. An
+ * empty `{}` takes the default 256 MiB growable cap. */
+export interface HeapMemoryArm {
+    /** Byte ceiling of the growable heap backing. Default
+     * `DEFAULT_ECS_CAP_BYTES` (256 MiB), same hard-ceiling semantics as the
+     * SAB backing (#380). */
+    readonly maxBytes?: number;
+}
+/** Opt-in **shared-memory** backing (`@oasys/oecs/shared`): a growable
+ * `SharedArrayBuffer` instead of a plain `ArrayBuffer`. Required for worker
+ * offload and a WASM compute backend, but needs cross-origin isolation
+ * (COOP/COEP) in browsers. Empty `{}` takes the default 256 MiB growable cap. */
+export interface SharedMemoryArm {
+    /** Byte ceiling of the growable shared backing. Default
+     * `DEFAULT_ECS_CAP_BYTES` (256 MiB), hard-ceiling semantics (#380). */
+    readonly maxBytes?: number;
+}
+/** Pinnable on every arm: exact initial rows per archetype column. The
+ * budget arm derives one when unpinned; every other arm defaults to
+ * `DEFAULT_COLUMN_CAPACITY`. */
+interface ColumnCapacityPin {
+    readonly columnCapacity?: number;
+}
+/**
+ * The single sizing option on `ECSOptions.memory`. Key-discriminated —
+ * exactly one of `budget` | `maxBytes` | `wasm` | `allocator`, or none for
+ * default sizing. The `never` fields make a two-arm literal a type error;
+ * `resolveECSMemory` backstops untyped JS callers at runtime.
+ */
+export type ECSMemoryOptions = ({
+    readonly budget: EntityBudget;
+    readonly maxBytes?: never;
+    readonly wasm?: never;
+    readonly allocator?: never;
+    readonly heap?: never;
+    readonly shared?: never;
+} & ColumnCapacityPin) | ({
+    readonly maxBytes: number;
+    readonly budget?: never;
+    readonly wasm?: never;
+    readonly allocator?: never;
+    readonly heap?: never;
+    readonly shared?: never;
+} & ColumnCapacityPin) | ({
+    readonly wasm: WasmMemoryArm;
+    readonly budget?: never;
+    readonly maxBytes?: never;
+    readonly allocator?: never;
+    readonly heap?: never;
+    readonly shared?: never;
+} & ColumnCapacityPin) | ({
+    readonly heap: HeapMemoryArm;
+    readonly budget?: never;
+    readonly maxBytes?: never;
+    readonly wasm?: never;
+    readonly allocator?: never;
+    readonly shared?: never;
+} & ColumnCapacityPin) | ({
+    readonly shared: SharedMemoryArm;
+    readonly budget?: never;
+    readonly maxBytes?: never;
+    readonly wasm?: never;
+    readonly allocator?: never;
+    readonly heap?: never;
+} & ColumnCapacityPin) | ({
+    /** Expert escape hatch. Typed `InPlaceBufferAllocator` so only
+     * allocators that statically declare `isInPlace: true` compile —
+     * the ADR-0008 boundary. `DEFAULT_SAB_ALLOCATOR` is rejected by the
+     * type system; non-in-place allocators stay snapshot/test-sizing
+     * utilities. */
+    readonly allocator: InPlaceBufferAllocator;
+    /** The allocator owns its real ceiling; this hint only labels
+     * diagnostics (cap errors, `memoryPlan.derivation`). */
+    readonly capBytesHint?: number;
+    readonly budget?: never;
+    readonly maxBytes?: never;
+    readonly wasm?: never;
+    readonly heap?: never;
+    readonly shared?: never;
+} & ColumnCapacityPin) | ({
+    /** No sizing arm: default growable backing (256 MiB cap), with the
+     * column capacity optionally pinned — the minimal migration from the
+     * removed `initialCapacity` knob. */
+    readonly budget?: never;
+    readonly maxBytes?: never;
+    readonly wasm?: never;
+    readonly allocator?: never;
+    readonly heap?: never;
+    readonly shared?: never;
+} & ColumnCapacityPin);
+/** What the caller's intent resolved to. Exposed as `ECS.memoryPlan` for
+ * diagnostics; `intentLabel`/`budgetEntities`/`capBytes` also travel
+ * into `Store` so cap errors speak the caller's language. */
+export interface ResolvedECSMemory {
+    readonly source: "default" | "budget" | "max_bytes" | "wasm" | "allocator" | "heap" | "shared";
+    readonly allocator: InPlaceBufferAllocator;
+    readonly columnCapacity: number;
+    readonly entityIndexCapacity: number;
+    /** Byte ceiling of the backing, `null` when unknowable from JS (a
+     * bring-your-own `WebAssembly.Memory` hides its `maximum`; a custom
+     * allocator owns its own cap unless hinted). */
+    readonly capBytes: number | null;
+    /** Human phrasing of the declared intent — reused verbatim in cap
+     * errors so the failure names what the caller asked for. */
+    readonly intentLabel: string;
+    /** The declared entity budget when the budget arm was used — drives the
+     * "N× the declared budget" cap-error diagnostic. */
+    readonly budgetEntities: number | null;
+    /** How each derived number was arrived at, one line per decision. */
+    readonly derivation: readonly string[];
+    /** The backing `WebAssembly.Memory` when the wasm arm was used (both
+     * bring-your-own and engine-constructed) — the consumer hands this to
+     * its WASM `ComputeBackend` so the sim and the columns share bytes. */
+    readonly wasmMemory: WebAssembly.Memory | null;
+}
+/** Subset of the plan `Store` needs to phrase cap/overflow errors in the
+ * caller's terms. */
+export interface ECSMemoryCapContext {
+    readonly capBytes: number | null;
+    readonly intentLabel: string;
+    readonly budgetEntities: number | null;
+}
+/**
+ * Turn a consumer's sizing intent into a concrete memory plan. Pure apart
+ * from allocator/Memory construction; throws `INVALID_MEMORY_OPTIONS` on a
+ * malformed option set — at construction, not first-grow.
+ */
+export declare function resolveECSMemory(opts?: ECSMemoryOptions): ResolvedECSMemory;
+export {};
+//# sourceMappingURL=ecs_memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ecs_memory.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/ecs_memory.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,28 @@
+import { Brand } from '../../type_primitives';
+export type EntityID = Brand<number, "entity_id">;
+/**
+ * Compile-time readonly view of a `Uint32Array` whose elements are packed
+ * `EntityID`s — `Archetype.entityIds` returns this, so `ids[i]` is already
+ * branded and consumers don't re-brand by hand. Blocks index writes at the
+ * type layer.
+ *
+ * **Advisory, not a runtime barrier** — same caveat as `ReadonlyColumn`: the
+ * underlying value is the live mutable buffer, and indexing past
+ * `totalCount - 1` reads stale slots (the brand can't catch that).
+ */
+export interface ReadonlyEntityIdArray {
+    readonly [index: number]: EntityID;
+    readonly length: number;
+}
+export declare const INDEX_BITS = 20;
+export declare const INDEX_MASK: number;
+export declare const MAX_INDEX: number;
+export declare const GENERATION_BITS: number;
+export declare const MAX_GENERATION: number;
+export declare const RETIRED_GENERATION: number;
+export declare const MAX_LIVE_GENERATION: number;
+export declare const MAX_ENTITY_ID: number;
+export declare const createEntityId: (index: number, generation: number) => EntityID;
+export declare const getEntityIndex: (id: EntityID) => number;
+export declare const getEntityGeneration: (id: EntityID) => number;
+//# sourceMappingURL=entity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/entity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;KA2BK;AAEL,OAAO,EAAE,KAAK,EAAc,MAAM,uBAAuB,CAAC;AAI1D,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAElD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,UAAU,QAAwB,CAAC;AAChD,eAAO,MAAM,SAAS,QAAa,CAAC;AACpC,eAAO,MAAM,eAAe,QAAiC,CAAC;AAC9D,eAAO,MAAM,cAAc,QAA6B,CAAC;AAQzD,eAAO,MAAM,kBAAkB,QAAiB,CAAC;AAGjD,eAAO,MAAM,mBAAmB,QAAqB,CAAC;AAMtD,eAAO,MAAM,aAAa,QAA6C,CAAC;AAExE,eAAO,MAAM,cAAc,UAAW,MAAM,cAAc,MAAM,KAAG,QAWlE,CAAC;AAEF,eAAO,MAAM,cAAc,OAAQ,QAAQ,KAAG,MAAyB,CAAC;AAExE,eAAO,MAAM,mBAAmB,OAAQ,QAAQ,KAAG,MAAsC,CAAC"}

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

@@ -0,0 +1,54 @@
+import { Brand } from '../../type_primitives';
+export type EventID = Brand<number, "event_id">;
+export declare const asEventId: (value: number) => EventID;
+/** Event schema: field name → value type. Every value is a number at
+ * runtime; the declared type may be a branded number (e.g. `EntityID`)
+ * so the brand survives the emit → read round trip at the type layer.
+ * Declare schemas as type literals (`eventKey<{ a: EntityID }>`), not
+ * interfaces — assignability to the `EventSchema` constraint relies on
+ * the implicit index signature literals get and interfaces don't. */
+export type EventSchema = Readonly<Record<string, number>>;
+/** Schema of a signal — a zero-field event. */
+export type EmptyEventSchema = Readonly<Record<never, number>>;
+declare const __eventSchema: unique symbol;
+export type EventDef<S extends EventSchema = EventSchema> = EventID & {
+    readonly [__eventSchema]: S;
+};
+/**
+ * Reader view over an event channel's SoA columns. Columns are read-only
+ * arrays typed per the event schema: consumers index them and read
+ * `.length`. A field declared as a branded number (e.g. `EntityID`) reads
+ * back branded — no cast at the consumer.
+ *
+ * The "cannot mutate the live channel through the reader" property is
+ * **advisory** — the columns are the same live `number[]` objects the channel
+ * mutates (see `EventChannel` below), so the `readonly` typing blocks writes
+ * at the type layer only; a §10c-policed cast can still write through.
+ */
+export type EventReader<S extends EventSchema> = {
+    length: number;
+} & {
+    readonly [K in keyof S]: ReadonlyArray<S[K]>;
+};
+export declare class EventChannel {
+    readonly fieldNames: string[];
+    readonly columns: number[][];
+    readonly reader: EventReader<any>;
+    constructor(fieldNames: string[]);
+    emit(values: Record<string, number>): void;
+    /** Emit a signal (zero-field event). */
+    emitSignal(): void;
+    clear(): void;
+}
+declare const __eventKeySchema: unique symbol;
+export type EventKey<S extends EventSchema = EventSchema> = symbol & {
+    readonly [__eventKeySchema]: S;
+};
+declare const __signalKey: unique symbol;
+export type SignalKey = EventKey<EmptyEventSchema> & {
+    readonly [__signalKey]: true;
+};
+export declare function eventKey<S extends EventSchema>(name: string): EventKey<S>;
+export declare function signalKey(name: string): SignalKey;
+export {};
+//# sourceMappingURL=event.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA+BK;AAEL,OAAO,EACN,KAAK,EAIL,MAAM,uBAAuB,CAAC;AAG/B,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAChD,eAAO,MAAM,SAAS,UAAW,MAAM,YAKrC,CAAC;AAEH;;;;;qEAKqE;AACrE,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;AAG/D,OAAO,CAAC,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC;AAE3C,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,IAAI,OAAO,GAAG;IACrE,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,WAAW,IAAI;IAChD,MAAM,EAAE,MAAM,CAAC;CACf,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAErD,qBAAa,YAAY;IACxB,SAAgB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrC,SAAgB,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC;IAEpC,SAAgB,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;gBAE7B,UAAU,EAAE,MAAM,EAAE;IAoBzB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAsBjD,wCAAwC;IACjC,UAAU,IAAI,IAAI;IAIlB,KAAK,IAAI,IAAI;CAOpB;AAMD,OAAO,CAAC,MAAM,gBAAgB,EAAE,OAAO,MAAM,CAAC;AAE9C,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,IAAI,MAAM,GAAG;IACpE,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;CAC/B,CAAC;AAQF,OAAO,CAAC,MAAM,WAAW,EAAE,OAAO,MAAM,CAAC;AAEzC,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,gBAAgB,CAAC,GAAG;IACpD,QAAQ,CAAC,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;CAC7B,CAAC;AAEF,wBAAgB,QAAQ,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEzE;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAEjD"}

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

@@ -0,0 +1,133 @@
+import { EntityID } from './entity';
+import { SystemDescriptor } from './system';
+import { SCHEDULE } from './schedule';
+/** A deferred structural command issued through `ctx.commands.*` (`query.ts`).
+ * `spawn`/`despawn`/`enable`/`disable` carry a `null` component; `add`/`remove`
+ * carry the affected component's id. */
+export type StructuralOp = "spawn" | "despawn" | "add" | "remove" | "enable" | "disable";
+/** An observer edge that fired at a flush (`add`/`remove`/`enable`/`disable`) or
+ * at the post-update onSet detection point (`set`). */
+export type ObserverOp = "add" | "remove" | "set" | "enable" | "disable";
+/**
+ * The push sink. All callers are `__DEV__`-gated, so the methods receive raw ids
+ * and descriptor references (no string-building on the hot path); the recorder
+ * decides what to retain. Implementations must be side-effect-free with respect
+ * to the ECS — they observe, never mutate.
+ */
+export interface FrameTraceSink {
+    /** Opens a frame. Fired first in `world.update`, before any phase runs. */
+    tickBegin(tick: number, dt: number): void;
+    /** Closes the frame opened by `tickBegin` (after onSet + `clearEvents`). */
+    tickEnd(tick: number): void;
+    /** A scheduled system is about to run, in the given phase. */
+    systemStart(system: SystemDescriptor, phase: SCHEDULE): void;
+    /** The system that last `systemStart`'d has returned. */
+    systemEnd(system: SystemDescriptor): void;
+    /** A deferred structural command was enqueued (applied at the next flush). */
+    commandQueued(op: StructuralOp, entity: EntityID, component: number | null): void;
+    /** The deferred command buffer is about to drain for this phase. */
+    flushBegin(phase: SCHEDULE): void;
+    /** The deferred command buffer (and any observer cascade) has settled. */
+    flushEnd(phase: SCHEDULE): void;
+    /**
+     * A schedule phase has fully settled — every system in `phase` ran and the
+     * deferred command buffer (plus any observer cascade) flushed — so the live
+     * world sits at a consistent, fingerprint-able point WITHIN the frame. Fired
+     * once per phase that runs (each startup phase, each fixed step, and each
+     * update phase), immediately after `flushEnd(phase)`.
+     *
+     * This is the blessed seam for a consumer to read `stateHash()` between the
+     * phases of one `update()` and bisect a divergence to the exact phase that
+     * introduced it (#797 / ADR-0032). `flushEnd` marks the same instant, but it
+     * is an observation of the flush *mechanism*, not a "safe to read consistent
+     * state" contract — so per-phase fingerprinting binds to this method, not to a
+     * flush-internal name. Like every sink method the call is read-only w.r.t. the
+     * ECS: reading `stateHash()` here cannot perturb the per-tick hash or ordering.
+     *
+     * Caveat: the POST_UPDATE boundary fires BEFORE the tick-tail onSet-observer
+     * dispatch + `clearEvents`, so for a world with onSet observers the final
+     * per-tick `stateHash` (after `update()` returns) may differ from the
+     * POST_UPDATE phase hash. A world with no onSet observers reconciles exactly.
+     */
+    phaseBoundary(phase: SCHEDULE): void;
+    /** An observer callback fired for one entity (`entity === -1` for an
+     * archetype-granular onSet, which has no per-entity id). */
+    observerFired(op: ObserverOp, component: number, entity: number, observer: SystemDescriptor): void;
+    /** A system emitted an event on `key` (the channel's symbol description). */
+    eventEmitted(key: string): void;
+    /** A system read an event channel; `count` is how many events it saw. */
+    eventRead(key: string, count: number): void;
+}
+/** One captured event, as plain JSON-serialisable data (string names + numeric
+ * ids), so a `FrameTrace[]` streams straight to a browser renderer. */
+export type FrameTraceEvent = {
+    readonly kind: "system_start";
+    readonly system: string;
+    readonly phase: SCHEDULE;
+} | {
+    readonly kind: "system_end";
+    readonly system: string;
+} | {
+    readonly kind: "command_queued";
+    readonly op: StructuralOp;
+    readonly entity: number;
+    readonly component: number | null;
+} | {
+    readonly kind: "flush_begin";
+    readonly phase: SCHEDULE;
+} | {
+    readonly kind: "flush_end";
+    readonly phase: SCHEDULE;
+} | {
+    readonly kind: "observer_fired";
+    readonly op: ObserverOp;
+    readonly component: number;
+    readonly entity: number;
+    readonly observer: string;
+} | {
+    readonly kind: "event_emitted";
+    readonly key: string;
+} | {
+    readonly kind: "event_read";
+    readonly key: string;
+    readonly count: number;
+};
+/** One frame's captured internals, in causal order. */
+export interface FrameTrace {
+    readonly tick: number;
+    readonly dt: number;
+    readonly events: FrameTraceEvent[];
+}
+/**
+ * The in-tree `FrameTraceSink`. Mirrors `command_log.ts`'s `openTick` /
+ * `RecordedTick` shape: `tickBegin` opens a fresh `FrameTrace`, every other
+ * method appends to it, `tickEnd` closes it. Events arriving with no open
+ * frame (e.g. a stray pre-`update` flush) are ignored rather than throwing —
+ * the recorder is a passive observer.
+ */
+export declare class FrameTraceRecorder implements FrameTraceSink {
+    private readonly _frames;
+    private _current;
+    tickBegin(tick: number, dt: number): void;
+    tickEnd(_tick: number): void;
+    systemStart(system: SystemDescriptor, phase: SCHEDULE): void;
+    systemEnd(system: SystemDescriptor): void;
+    commandQueued(op: StructuralOp, entity: EntityID, component: number | null): void;
+    flushBegin(phase: SCHEDULE): void;
+    flushEnd(phase: SCHEDULE): void;
+    /** No-op (#797 / ADR-0032). The recorder already marks this instant with
+     * `flushEnd`, and a per-phase fingerprint is a consumer concern — the recorder
+     * holds no world reference to hash. The seam exists so a consumer's OWN sink can
+     * run code (e.g. `stateHash()`) at the safe post-flush point; the in-tree
+     * event-stream recorder has nothing to add, so it stays a stream of causal
+     * events, not fingerprints. */
+    phaseBoundary(_phase: SCHEDULE): void;
+    observerFired(op: ObserverOp, component: number, entity: number, observer: SystemDescriptor): void;
+    eventEmitted(key: string): void;
+    eventRead(key: string, count: number): void;
+    /** The captured frames, in `update()` order. */
+    frames(): readonly FrameTrace[];
+    /** Drop all captured frames (reuse the recorder for a fresh run). */
+    reset(): void;
+}
+//# sourceMappingURL=frame_trace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frame_trace.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/frame_trace.ts"],"names":[],"mappings":"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"}