@oasys/oecs 0.3.1 → 0.5.0

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

@@ -0,0 +1,133 @@
+import { EntityID } from './entity.cjs';
+import { SystemDescriptor } from './system.cjs';
+import { SCHEDULE } from './schedule.cjs';
+/** 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 `ecs.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

@@ -0,0 +1,133 @@
+import { EntityID } from './entity.js';
+import { SystemDescriptor } from './system.js';
+import { SCHEDULE } from './schedule.js';
+/** 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 `ecs.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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"}

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

@@ -0,0 +1,274 @@
+import { ComponentDef, ComponentSchema, CompleteFieldValues, FieldValues } from './component.cjs';
+import { ECS } from './ecs.cjs';
+import { EntityID } from './entity.cjs';
+import { SystemContext } from './query.cjs';
+import { SCHEDULE } from './schedule.cjs';
+import { PayloadCodec } from '../store/index.cjs';
+/** One component to attach to a freshly spawned entity. `values` are required
+ * and complete as a *strictness* choice, not a runtime need: since #716 every
+ * attach path (deferred included — `writeFields`'s `?? 0`) zero-fills omitted
+ * fields, same as templates. A host command is a reified, replayable record,
+ * so it carries explicit intent for every field rather than relying on the
+ * zero-fill; a tag component takes `{}`. Build type-safely with `spawnEntry`. */
+export interface SpawnEntry {
+    readonly def: ComponentDef;
+    readonly values: FieldValues<ComponentSchema>;
+}
+/** Extracts the schema out of a `ComponentDef` handle. */
+type SchemaOf<D extends ComponentDef> = D extends ComponentDef<infer S> ? S : ComponentSchema;
+/** One schema-checked spawn entry: `values` is complete for its own def (see
+ * the `SpawnEntry` doc — explicit intent per field, though the attach path
+ * zero-fills since #716), and a tag takes exactly `{}`. */
+export type SpawnEntryFor<D extends ComponentDef> = {
+    readonly def: D;
+    readonly values: CompleteFieldValues<SchemaOf<D>>;
+};
+/** The entries tuple for `HostCommandQueue.spawn` — each element's `values` is
+ * checked against its own `def`'s schema. Unlike `TemplateEntries` (which
+ * stays `Partial` — a template is a reusable default set), a host command
+ * demands complete values: it is a reified, replayable record, so every
+ * field is explicit even though the attach path would zero-fill (#716). */
+export type SpawnEntries<Defs extends readonly ComponentDef[]> = readonly [
+    ...{
+        [K in keyof Defs]: SpawnEntryFor<Defs[K]>;
+    }
+];
+/** Type-checked `SpawnEntry` constructor — keeps `values` aligned to `def`'s
+ * schema at the call site even though the stored entry is schema-erased. */
+export declare function spawnEntry<S extends ComponentSchema>(def: ComponentDef<S>, values: CompleteFieldValues<S>): SpawnEntry;
+/**
+ * A single world mutation, as plain data. Every transport (typed queue today, a
+ * SAB ring codec tomorrow) and every consumer (editor undo, record/replay)
+ * speaks this one vocabulary, applied by the one `applyHostCommand` dispatch.
+ *
+ * Component fields are `string` / `def: ComponentDef` (schema-erased) so the
+ * union stays flat; the typed `HostCommandQueue` methods preserve type-safety at
+ * the enqueue site. `applyHostCommand` re-applies them through `SystemContext`,
+ * which type-checks because `ComponentDef` defaults its schema to
+ * `ComponentSchema` (whose `keyof` is `string`).
+ */
+export type HostCommand = {
+    readonly kind: "spawn";
+    readonly components: readonly SpawnEntry[];
+    /** Fired with the new id once the spawn applies (the id only exists
+     * after the deferred create) — lets a producer/editor learn it. */
+    readonly onSpawned?: (eid: EntityID) => void;
+} | {
+    readonly kind: "despawn";
+    readonly eid: EntityID;
+} | {
+    readonly kind: "add_component";
+    readonly eid: EntityID;
+    readonly def: ComponentDef;
+    readonly values: FieldValues<ComponentSchema>;
+} | {
+    readonly kind: "remove_component";
+    readonly eid: EntityID;
+    readonly def: ComponentDef;
+} | {
+    readonly kind: "set_field";
+    readonly eid: EntityID;
+    readonly def: ComponentDef;
+    readonly field: string;
+    readonly value: number;
+} | {
+    readonly kind: "disable";
+    readonly eid: EntityID;
+} | {
+    readonly kind: "enable";
+    readonly eid: EntityID;
+};
+/**
+ * THE ONE APPLY DISPATCH. Maps a `HostCommand` onto `SystemContext` ops. Only
+ * ever called from inside the blessed apply system, which holds the `ctx` and is
+ * `exclusive` (full access). Structural changes (`spawn`/`despawn`/component
+ * add-remove) are deferred to the phase flush, exactly like a normal system's;
+ * `setField` is immediate and bumps the change-tick. Returns the new entity for
+ * `spawn`, otherwise `undefined`.
+ *
+ * That immediate/deferred split is a sharp edge: a `setField` targeting a
+ * component the entity does NOT yet have — because an `addComponent`/`spawn`
+ * enqueued in the SAME drain is still pending its flush — would otherwise fail
+ * deep in `getColumn` with an opaque "component not registered". The `DEV`
+ * guard below turns that into an actionable message. The fix is structural, not a
+ * retry: pass the value in `addComponent`/`spawnEntry` (which carries complete
+ * field values), or issue the `setField` on a later frame.
+ */
+export declare function applyHostCommand(ctx: SystemContext, cmd: HostCommand): EntityID | undefined;
+/**
+ * The host-facing write handle. Mutating methods ENQUEUE (off-schedule, pure);
+ * nothing reaches the world until the apply system drains it at the next
+ * schedule head. Mirrors Bevy's `Commands` ergonomics over the flat `HostCommand`
+ * vocabulary. The returned-from-`installHostCommandSeam` instance is the
+ * write counterpart to the reactive bridge's returned `reactiveMap`.
+ */
+export declare class HostCommandQueue {
+    private readonly queued;
+    /** Spawn an entity carrying `components`. `onSpawned` receives the new id
+     * once the spawn applies. Each entry's `values` is checked against its own
+     * `def`'s schema (`SpawnEntries`); the stored command stays schema-erased. */
+    spawn<Defs extends readonly ComponentDef[]>(components: SpawnEntries<Defs>, onSpawned?: (eid: EntityID) => void): void;
+    despawn(eid: EntityID): void;
+    addComponent<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, values: CompleteFieldValues<S>): void;
+    removeComponent(eid: EntityID, def: ComponentDef): void;
+    /** Set `field` of `def` on `eid`. Applied IMMEDIATELY at the drain, unlike the
+     * deferred structural ops — so `def` must already be on `eid`. Do NOT
+     * `addComponent`/`spawn` `def` and `setField` it in the same frame: the add is
+     * still pending its flush when the immediate set runs (carry the value in
+     * `addComponent`/`spawnEntry` instead). `applyHostCommand` throws an
+     * actionable error in `DEV` if you do. */
+    setField<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, field: string & keyof S, value: number): void;
+    disable(eid: EntityID): void;
+    enable(eid: EntityID): void;
+    /** Enqueue a pre-built command. The path for a SAB-ring codec, an editor's
+     * reified inverse, or a replay log — all of which produce `HostCommand` data
+     * directly rather than calling the typed sugar above. */
+    push(cmd: HostCommand): void;
+    /** Commands buffered but not yet applied. */
+    pending(): number;
+    /** Drop every buffered command without applying it (M15) — e.g. abandoning
+     * queued edits on a scene unload. Returns how many were dropped. Does not
+     * touch commands already drained into the world. */
+    clear(): number;
+    /**
+     * Apply and clear every buffered command. Called by the blessed apply system
+     * inside its schedule span; not part of the host-facing surface. Returns the
+     * count applied.
+     *
+     * `tap`, when present, is invoked with each command in apply order just before
+     * it is applied — the record/replay hook ({@link HostCommandRecorder}). It is
+     * an OPT-IN observer: the tap-free path keeps the original tight loop, so an
+     * un-recorded drain pays nothing (#702).
+     */
+    drain(ctx: SystemContext, tap?: (cmd: HostCommand) => void): number;
+}
+/** Bytes of the payload region inside one `command_ring` slot (15). The slot's
+ * leading byte is the opCode; `COMMAND_RING_SLOT_BYTES` (16) is the whole slot. */
+export declare const HOST_COMMAND_PAYLOAD_BYTES: number;
+/**
+ * Ring codec for a `setField` on a FIXED `(def, field)`. The component + field
+ * are bound INTO the codec, not carried in the bytes — the consumer-owned-codec
+ * rule (mirroring `command_dispatch`): the engine ships the mechanism, a
+ * consumer's codec knows which component+field an opcode means.
+ *
+ *   Payload (15 B): `[ eid: u32 LE @0 ][ value: f64 LE @4 ][ _reserved: 3 B @12 ]`
+ *
+ * `value` rides as `f64` (covers every numeric column type losslessly within
+ * range); the trailing 3 bytes stay zero. Packing the id as `u32` is what makes
+ * `setField` fit the 15-byte slot.
+ */
+export declare function ringSetFieldCodec<S extends ComponentSchema>(def: ComponentDef<S>, field: string & keyof S): PayloadCodec<HostCommand>;
+/** Ring codec for `despawn` — `[ eid: u32 LE @0 ]`, trailing 11 B reserved-zero. */
+export declare function ringDespawnCodec(): PayloadCodec<HostCommand>;
+/** Ring codec for `disable` — `[ eid: u32 LE @0 ]`, trailing 11 B reserved-zero. */
+export declare function ringDisableCodec(): PayloadCodec<HostCommand>;
+/** Ring codec for `enable` — `[ eid: u32 LE @0 ]`, trailing 11 B reserved-zero. */
+export declare function ringEnableCodec(): PayloadCodec<HostCommand>;
+/**
+ * Ring codec for `removeComponent` of a FIXED `def` — `[ eid: u32 LE @0 ]`, the
+ * component bound into the codec (consumer-owned-codec rule). `spawn` /
+ * `addComponent` are deliberately absent: they carry component field values
+ * that don't fit the 15-byte slot generically, so they stay typed-transport-only
+ * (the prototype's finding — the in-process queue has no width limit).
+ */
+export declare function ringRemoveComponentCodec(def: ComponentDef): PayloadCodec<HostCommand>;
+/** A ctx-aware applier for one ring opcode: runs on the system `ctx` (which the
+ * apply system holds) with the raw 15-byte payload. `tap`, when present, is the
+ * record/replay hook (#702) — a generic, `onCommand`-bound applier decodes the
+ * slot to a `HostCommand` and feeds it to `tap` before applying, so ring-sourced
+ * commands land in the same log as typed-queue ones. A raw `on` applier (a
+ * consumer's own non-`HostCommand` op, e.g. the game's `spawn_unit`) has no
+ * `HostCommand` to surface and simply ignores `tap`. */
+export type RingCommandApplier = (ctx: SystemContext, payload: Uint8Array, tap?: (cmd: HostCommand) => void) => void;
+/**
+ * Drains the SAB `command_ring` as the second host-command transport, dispatching
+ * each opcode to a bound applier. Two binding styles:
+ *
+ *   - `onCommand(op, codec)` — decode the slot to a `HostCommand` and run it
+ *     through the ONE `applyHostCommand` (the same dispatch the typed queue
+ *     uses). This is the generic cross-thread / wire host-write path.
+ *   - `on(op, applier)` — a raw ctx-aware handler for a consumer's OWN ring ops
+ *     that aren't generic host commands (e.g. the game's `spawn_unit`, which runs
+ *     a BFS placement + game spawn). Same drain, same ring: the "one bus".
+ *
+ * Opcodes + codecs are CONSUMER-supplied — the engine ships the mechanism and the
+ * `ring_*_codec` factories, never the opcode numbers (mirrors `command_dispatch`).
+ *
+ * Exactly ONE dispatcher should drain a given ring — a second drain would consume
+ * the first's slots. The in-process apply system passes its dispatcher via
+ * `installHostCommandSeam({ ring })`; a system that owns a timing-coupled drain
+ * point (e.g. `wave_spawn`, which must drain between the spatial-index build and
+ * the flow-field rebuild) constructs one and calls `drain` itself.
+ */
+export declare class HostCommandDispatcher {
+    private readonly appliers;
+    /** Bind a raw ctx-aware applier to `opCode`. Re-binding replaces. */
+    on(opCode: number, applier: RingCommandApplier): this;
+    /** Unbind `opCode` (M15). Returns whether a binding was removed; subsequent
+     * slots carrying it hit the unknown-opcode path. */
+    off(opCode: number): boolean;
+    /** Bind a `HostCommand` codec to `opCode`: each matching slot is decoded and
+     * run through `applyHostCommand` — the SAME dispatch the typed queue uses.
+     * A drain-time `tap` (record/replay, #702) sees the decoded command before it
+     * applies, so ring-sourced commands share one log with the typed transport. */
+    onCommand(opCode: number, codec: PayloadCodec<HostCommand>): this;
+    /** Drain every pending slot, dispatching each to its bound applier. Unbound
+     * opcodes are skipped (the read head still advances — matching
+     * `drainCommandRing` / `CommandDispatcher`). Returns slots drained. `tap`,
+     * when present, is forwarded to each applier as the record/replay hook (#702);
+     * only `onCommand`-bound (generic `HostCommand`) opcodes surface to it. */
+    drain(ctx: SystemContext, view: DataView, ringOff: number, tap?: (cmd: HostCommand) => void): number;
+}
+/**
+ * A per-tick sink the apply system feeds drained commands into — the record side
+ * of record/replay (#702). Declared structurally HERE (not imported from
+ * `command_log.ts`) so the seam needs no dependency on the recorder: the one-way
+ * edge is `command_log` → `host_commands`, never back. {@link HostCommandRecorder}
+ * is the in-tree implementation.
+ *
+ * The protocol the apply system follows: at each UPDATE-phase drain it calls
+ * `openTick(tick, dt)` to open that tick's bucket; STARTUP-phase drains skip
+ * `openTick`, so seed-time commands land in the recorder's startup bucket. Then
+ * every applied command (both transports) is handed to `record`.
+ */
+export interface HostCommandSink {
+    /** Open (or reuse) the bucket for update `tick` with its `dt`. Multiple drains
+     * in one tick (several update phases) reuse the one bucket. */
+    openTick(tick: number, dt: number): void;
+    /** Record one applied command, in apply order. Pre-bound so it can be passed
+     * straight as a drain `tap` without per-tick closure allocation. */
+    readonly record: (cmd: HostCommand) => void;
+}
+/** Options for {@link installHostCommandSeam}. */
+export interface HostCommandSeamOptions {
+    /** Schedule phases whose head drains the queue. Default
+     * `[PRE_STARTUP, PRE_UPDATE]` — seed-time edits plus every frame. */
+    readonly schedules?: readonly SCHEDULE[];
+    /** Apply-system name (diagnostics). Default `"host_command_apply"`. */
+    readonly name?: string;
+    /** When provided, the apply system ALSO drains the world's SAB `command_ring`
+     * through this dispatcher at each schedule head — the cross-thread / wire
+     * transport, resolving to the same `applyHostCommand` as the typed queue.
+     * The ECS `Store` always allocates a ring; if one is somehow absent
+     * (`command_ring_off === 0`) the ring drain is a no-op. Bind opcodes with the
+     * `ring_*_codec` factories, or `dispatcher.on` for a consumer's own ops. */
+    readonly ring?: HostCommandDispatcher;
+    /** When provided, every command the apply system drains — from BOTH transports
+     * (typed queue + `onCommand`-bound ring ops) — is logged into this sink,
+     * tagged with the tick + `dt`, for record/replay (#702). Off by default: an
+     * un-recorded seam keeps the original tap-free drain and pays nothing.
+     * {@link HostCommandRecorder} is the in-tree sink; replay it with
+     * `replayCommandLog`. */
+    readonly recorder?: HostCommandSink;
+}
+/**
+ * Tear down a seam installed by {@link installHostCommandSeam} (M15): removes
+ * its apply systems from the world's schedule and clears any still-buffered
+ * commands. The queue itself stays usable as a buffer, but nothing drains it
+ * until a new seam is installed. No-op (returns `false`) if `queue` was not
+ * produced by `installHostCommandSeam` on this world.
+ */
+export declare function uninstallHostCommandSeam(ecs: ECS, queue: HostCommandQueue): boolean;
+export declare function installHostCommandSeam(ecs: ECS, opts?: HostCommandSeamOptions): HostCommandQueue;
+export {};
+//# sourceMappingURL=host_commands.d.ts.map