@oasys/oecs 0.3.1 → 0.5.0

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

@@ -0,0 +1,274 @@
+import { ComponentDef, ComponentSchema, CompleteFieldValues, FieldValues } from './component.js';
+import { ECS } from './ecs.js';
+import { EntityID } from './entity.js';
+import { SystemContext } from './query.js';
+import { SCHEDULE } from './schedule.js';
+import { PayloadCodec } from '../store/index.js';
+/** 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

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

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

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

@@ -0,0 +1,46 @@
+export { ECS, type ECSOptions } from './ecs.cjs';
+export type { ECSRelations, ECSEvents, ECSResources, ECSSnapshots } from './facades.cjs';
+export { resolveECSMemory, DEFAULT_ECS_CAP_BYTES, BUDGET_GROWTH_HEADROOM, BUDGET_DEFAULT_BYTES_PER_ENTITY, BUDGET_DEFAULT_ARCHETYPES, type ECSMemoryOptions, type ResolvedECSMemory, type ECSMemoryCapContext, type EntityBudget, type WasmMemoryArm } from './ecs_memory.cjs';
+export type { Template, TemplateEntry, TemplateEntries, TemplateOverrides } from './store.cjs';
+export type { StoreLayoutListener } from './store_layout_listener.cjs';
+export type { ComputeBackend, BackendSystemHandle } from './compute_backend.cjs';
+export { SCHEDULE, type SystemEntry, type SystemOrdering, type SystemOrderingTarget, systemSet, type SystemSet, type SystemSetConfig } from './schedule.cjs';
+export { type RunCondition, type ConditionContext, runIfResourceEq, runEveryNTicks, runIfAnyMatch, not, allOf, anyOf } from './run_condition.cjs';
+export { SystemContext } from './query.cjs';
+export type { SystemFn, SystemConfig, SystemDescriptor, SystemAccessConfig, SystemAccessDeclaration, SystemTransition } from './system.cjs';
+export type { SystemAccess, DeclaredAccess, TypedSystemConfig, DeclaredRead, DeclaredWrite, DeclaredAdd, DeclaredRemove, DeclaredSparseRead, DeclaredSparseWrite, DeclaredRelationRead, DeclaredRelationWrite, DeclaredResourceRead, DeclaredResourceWrite, DespawnArg, DenseAccessDecl, SpawnsAccessDecl, DespawnsAccessDecl, TransitionsAccessDecl, SparseAccessDecl, RelationsAccessDecl, ResourcesAccessDecl } from './system.cjs';
+export type { DeclaredBundleOrDef } from './query.cjs';
+export { accessCheck } from './access_check.cjs';
+export type { ObserverConfig, ObserverHandle, ObserverFn, ArchetypeObserverFn, StructuralObserverConfig, EntitySetObserverConfig, ArchetypeSetObserverConfig } from './observer.cjs';
+export { installHostCommandSeam, uninstallHostCommandSeam, applyHostCommand, HostCommandQueue, HostCommandDispatcher, spawnEntry, ringSetFieldCodec, ringDespawnCodec, ringDisableCodec, ringEnableCodec, ringRemoveComponentCodec, HOST_COMMAND_PAYLOAD_BYTES } from './host_commands.cjs';
+export type { HostCommand, SpawnEntry, SpawnEntryFor, SpawnEntries, HostCommandSeamOptions, HostCommandSink, RingCommandApplier } from './host_commands.cjs';
+export { HostCommandRecorder, serializeCommandLog, deserializeCommandLog, replayCommandLog } from './command_log.cjs';
+export type { CommandLog, RecordedTick, ReplayResult, ReplayOptions } from './command_log.cjs';
+export { FrameTraceRecorder } from './frame_trace.cjs';
+export type { FrameTraceSink, FrameTrace, FrameTraceEvent, StructuralOp, ObserverOp } from './frame_trace.cjs';
+export { FrameStepper } from './frame_stepper.cjs';
+export type { FrameStepperOptions } from './frame_stepper.cjs';
+export { ECSRestoreError, ECS_SNAPSHOT_VERSION } from './resume.cjs';
+export type { ComponentRef, ReadonlyComponentRef } from './ref.cjs';
+export { Query, QueryBuilder, ChangedQuery, HIERARCHY_UNBOUNDED } from './query.cjs';
+export type { HierarchyTerm } from './query.cjs';
+export { ChunkColumns, Commands } from './query.cjs';
+export type { ArchetypeView, ArchetypeID } from './archetype.cjs';
+export type { EntityID, ReadonlyEntityIdArray } from './entity.cjs';
+export { getEntityIndex } from './entity.cjs';
+export { createEntityId, getEntityGeneration, MAX_INDEX, MAX_GENERATION, MAX_LIVE_GENERATION, RETIRED_GENERATION, MAX_ENTITY_ID } from './entity.cjs';
+export type { ComponentDef, ComponentHandle, ComponentRegisterOptions, ComponentSchema, SchemaOf, DeclaredQueryTerm, FieldValues, CompleteFieldValues, ValuesArg, AttachValuesArg, TagToTypedArray, ColumnsForSchema, MutableColumnsForSchema, ReadonlyColumn, ReadonlyUint32Array } from './component.cjs';
+export { bundle } from './component.cjs';
+export type { Bundle, BundleOrDef } from './component.cjs';
+export type { SparseComponentDef, SparseComponentID, SparseSchemaOf } from './sparse_store.cjs';
+export { SparseRestoreError } from './sparse_store.cjs';
+export type { RelationDef, RelationID, RelationCardinality, RelationOptions, OnDeleteTarget } from './relation.cjs';
+export { ANY_RELATION } from './relation.cjs';
+export { registerIsA, registerChildOf, type BuiltinRelationOptions } from './builtin_relations.cjs';
+export type { EventReader, EventKey, EventSchema, EventShape, EventFieldsCover, EmptyEventSchema, SignalKey } from './event.cjs';
+export { eventKey, signalKey } from './event.cjs';
+export type { ResourceKey, ResourceValueOf } from './resource.cjs';
+export { resourceKey } from './resource.cjs';
+export { dispatchTrace, type DispatchTraceSnapshot, type DispatchTraceEntry } from './dispatch_trace.cjs';
+export { ECSError, ECS_ERROR, isEcsError } from './utils/error.cjs';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,46 @@
+export { ECS, type ECSOptions } from './ecs.js';
+export type { ECSRelations, ECSEvents, ECSResources, ECSSnapshots } from './facades.js';
+export { resolveECSMemory, DEFAULT_ECS_CAP_BYTES, BUDGET_GROWTH_HEADROOM, BUDGET_DEFAULT_BYTES_PER_ENTITY, BUDGET_DEFAULT_ARCHETYPES, type ECSMemoryOptions, type ResolvedECSMemory, type ECSMemoryCapContext, type EntityBudget, type WasmMemoryArm } from './ecs_memory.js';
+export type { Template, TemplateEntry, TemplateEntries, TemplateOverrides } from './store.js';
+export type { StoreLayoutListener } from './store_layout_listener.js';
+export type { ComputeBackend, BackendSystemHandle } from './compute_backend.js';
+export { SCHEDULE, type SystemEntry, type SystemOrdering, type SystemOrderingTarget, systemSet, type SystemSet, type SystemSetConfig } from './schedule.js';
+export { type RunCondition, type ConditionContext, runIfResourceEq, runEveryNTicks, runIfAnyMatch, not, allOf, anyOf } from './run_condition.js';
+export { SystemContext } from './query.js';
+export type { SystemFn, SystemConfig, SystemDescriptor, SystemAccessConfig, SystemAccessDeclaration, SystemTransition } from './system.js';
+export type { SystemAccess, DeclaredAccess, TypedSystemConfig, DeclaredRead, DeclaredWrite, DeclaredAdd, DeclaredRemove, DeclaredSparseRead, DeclaredSparseWrite, DeclaredRelationRead, DeclaredRelationWrite, DeclaredResourceRead, DeclaredResourceWrite, DespawnArg, DenseAccessDecl, SpawnsAccessDecl, DespawnsAccessDecl, TransitionsAccessDecl, SparseAccessDecl, RelationsAccessDecl, ResourcesAccessDecl } from './system.js';
+export type { DeclaredBundleOrDef } from './query.js';
+export { accessCheck } from './access_check.js';
+export type { ObserverConfig, ObserverHandle, ObserverFn, ArchetypeObserverFn, StructuralObserverConfig, EntitySetObserverConfig, ArchetypeSetObserverConfig } from './observer.js';
+export { installHostCommandSeam, uninstallHostCommandSeam, applyHostCommand, HostCommandQueue, HostCommandDispatcher, spawnEntry, ringSetFieldCodec, ringDespawnCodec, ringDisableCodec, ringEnableCodec, ringRemoveComponentCodec, HOST_COMMAND_PAYLOAD_BYTES } from './host_commands.js';
+export type { HostCommand, SpawnEntry, SpawnEntryFor, SpawnEntries, HostCommandSeamOptions, HostCommandSink, RingCommandApplier } from './host_commands.js';
+export { HostCommandRecorder, serializeCommandLog, deserializeCommandLog, replayCommandLog } from './command_log.js';
+export type { CommandLog, RecordedTick, ReplayResult, ReplayOptions } from './command_log.js';
+export { FrameTraceRecorder } from './frame_trace.js';
+export type { FrameTraceSink, FrameTrace, FrameTraceEvent, StructuralOp, ObserverOp } from './frame_trace.js';
+export { FrameStepper } from './frame_stepper.js';
+export type { FrameStepperOptions } from './frame_stepper.js';
+export { ECSRestoreError, ECS_SNAPSHOT_VERSION } from './resume.js';
+export type { ComponentRef, ReadonlyComponentRef } from './ref.js';
+export { Query, QueryBuilder, ChangedQuery, HIERARCHY_UNBOUNDED } from './query.js';
+export type { HierarchyTerm } from './query.js';
+export { ChunkColumns, Commands } from './query.js';
+export type { ArchetypeView, ArchetypeID } from './archetype.js';
+export type { EntityID, ReadonlyEntityIdArray } from './entity.js';
+export { getEntityIndex } from './entity.js';
+export { createEntityId, getEntityGeneration, MAX_INDEX, MAX_GENERATION, MAX_LIVE_GENERATION, RETIRED_GENERATION, MAX_ENTITY_ID } from './entity.js';
+export type { ComponentDef, ComponentHandle, ComponentRegisterOptions, ComponentSchema, SchemaOf, DeclaredQueryTerm, FieldValues, CompleteFieldValues, ValuesArg, AttachValuesArg, TagToTypedArray, ColumnsForSchema, MutableColumnsForSchema, ReadonlyColumn, ReadonlyUint32Array } from './component.js';
+export { bundle } from './component.js';
+export type { Bundle, BundleOrDef } from './component.js';
+export type { SparseComponentDef, SparseComponentID, SparseSchemaOf } from './sparse_store.js';
+export { SparseRestoreError } from './sparse_store.js';
+export type { RelationDef, RelationID, RelationCardinality, RelationOptions, OnDeleteTarget } from './relation.js';
+export { ANY_RELATION } from './relation.js';
+export { registerIsA, registerChildOf, type BuiltinRelationOptions } from './builtin_relations.js';
+export type { EventReader, EventKey, EventSchema, EventShape, EventFieldsCover, EmptyEventSchema, SignalKey } from './event.js';
+export { eventKey, signalKey } from './event.js';
+export type { ResourceKey, ResourceValueOf } from './resource.js';
+export { resourceKey } from './resource.js';
+export { dispatchTrace, type DispatchTraceSnapshot, type DispatchTraceEntry } from './dispatch_trace.js';
+export { ECSError, ECS_ERROR, isEcsError } from './utils/error.js';
+//# sourceMappingURL=index.d.ts.map

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

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

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

@@ -0,0 +1,173 @@
+import { ArchetypeView } from './archetype.cjs';
+import { ComponentHandle } from './component.cjs';
+import { EntityID } from './entity.cjs';
+import { FrameTraceSink } from './frame_trace.cjs';
+import { SystemContext } from './query.cjs';
+import { StructuralObserverEvents } from './store.cjs';
+import { SystemAccessDeclaration, SystemDescriptor } from './system.cjs';
+/** What the observer registry needs from `Store` — the typed seam replacing
+ * bare underscore-convention reach-through (M1). `Store` implements this; the
+ * registry holds only this view, so the compiler bounds what observer dispatch
+ * can touch. Underscore names are kept so `Store`'s members stay one
+ * declaration (they read as "internal" at every other call site). */
+export interface ObserverHost {
+    /** Current change tick — read for onSet baselines. */
+    readonly _tick: number;
+    /** Dev-only frame-trace sink (`null` when unset; always null in prod). */
+    readonly _trace: FrameTraceSink | null;
+    /** Sync a component's observation flags (add/remove/disable/enable/dirty). */
+    _configureComponentObservation(cid: number, hasAdd: boolean, hasRem: boolean, hasDisable: boolean, hasEnable: boolean, trackDirty: boolean): void;
+    /** Drain the per-entity onSet dirty list for `cid` (clears marks). */
+    _takeDirty(cid: number): EntityID[];
+    /** Visit archetypes whose `cid` column changed since `baseline`, in
+     * canonical (creation-id) order. */
+    _forEachChangedArchetype(cid: number, baseline: number, cb: (arch: ArchetypeView) => void): void;
+    /** Every live entity currently holding `cid` (dispose-on-disable sweep). */
+    _collectEntitiesWithComponent(cid: number): EntityID[];
+    isAlive(id: EntityID): boolean;
+    isDisabled(id: EntityID): boolean;
+    hasComponent(entityId: EntityID, def: ComponentHandle): boolean;
+}
+/** Per-entity observer callback (onAdd / onRemove / onDisable / onEnable, and
+ * per-entity onSet). */
+export type ObserverFn = (eid: EntityID, ctx: SystemContext) => void;
+/** Archetype-granular onSet callback — fires once per changed archetype-column;
+ * the consumer iterates `arch.entityCount` rows itself. */
+export type ArchetypeObserverFn = (arch: ArchetypeView, ctx: SystemContext) => void;
+/** Fields common to every observer registration. `access` drives both the
+ * dev-mode `accessCheck` and the access-topological firing order; it is merged
+ * over an all-empty declaration, so a caller spells out only what it touches. */
+interface ObserverConfigBase {
+    onAdd?: ObserverFn;
+    onRemove?: ObserverFn;
+    /** Fires when an entity carrying this component is *disabled* (#577) — at the
+     * deferred toggle drain, once per net transition (ADR-0023). Mirrors `onRemove`:
+     * a disable is a soft remove of the whole mask from default queries. An immediate
+     * host-side `ecs.disable()` does not fire (like immediate `addComponent`). */
+    onDisable?: ObserverFn;
+    /** Fires when an entity carrying this component is *enabled* (#577), symmetric
+     * with `onDisable` / `onAdd`. */
+    onEnable?: ObserverFn;
+    /** Access surface the callbacks touch (reads / writes / spawns / …). Partial:
+     * merged over `_INTERNAL_EMPTY_ACCESS`. Undeclared access throws in `DEV`. */
+    access?: Partial<SystemAccessDeclaration>;
+    /** flecs-style replay of current matches on registration (onAdd only — seeds the
+     * *enabled* members; a disabled entity is simply absent, matching default-query
+     * semantics), for order-independence of register-vs-spawn. */
+    yieldExisting?: boolean;
+    /** Diagnostic label for this observer, surfaced by the frame-trace seam
+     * (ADR-0030) as the `observer_fired.observer` field — the same role a system's
+     * `name` plays. Optional and observe-only: it never touches `stateHash` or
+     * dispatch. Defaults to `observer(<component debug name>)` when the component
+     * was registered with a name, else `observer(<cid>)`. */
+    name?: string;
+}
+/** Per-entity onSet: `onSet(eid, ctx)` fires once per changed entity, drained
+ * from the opt-in per-row dirty list (registering this enables dirty tracking
+ * for the component — the ADR-0012 list + dedup bit). */
+export interface EntitySetObserverConfig extends ObserverConfigBase {
+    onSet: ObserverFn;
+    granularity: "entity";
+}
+/** Archetype-granular onSet (default): `onSet(arch, ctx)` fires once per
+ * changed archetype-column (the change tick), in canonical archetype order. Free
+ * write path. */
+export interface ArchetypeSetObserverConfig extends ObserverConfigBase {
+    onSet: ArchetypeObserverFn;
+    granularity?: "archetype";
+}
+/** Structural-only observer — no onSet. */
+export interface StructuralObserverConfig extends ObserverConfigBase {
+    onSet?: undefined;
+    granularity?: undefined;
+}
+export type ObserverConfig = StructuralObserverConfig | EntitySetObserverConfig | ArchetypeSetObserverConfig;
+export interface ObserverHandle {
+    dispose(): void;
+    /** `using h = ecs.observe(C, {...})` — explicit-resource-management sugar
+     * over {@link dispose} (TC39 `Symbol.dispose`). */
+    [Symbol.dispose](): void;
+}
+/**
+ * Registry of component observers. Owned by `ECS`; the `Store` calls back into
+ * `dispatchStructural` between fixed-point rounds during `flushStructural`,
+ * and `ECS.update` calls `dispatchSet` at the post-update detection point.
+ */
+export declare class ObserverRegistry {
+    private readonly store;
+    private readonly ctx;
+    private readonly entries;
+    /** ComponentID → its observers (structural + onSet). */
+    private readonly byCid;
+    /** Cached access-topological order; invalidated on register / dispose. */
+    private _topo;
+    private readonly _addBuckets;
+    private readonly _remBuckets;
+    private readonly _disBuckets;
+    private readonly _enaBuckets;
+    private readonly _radixOut;
+    private readonly _radixC0;
+    private readonly _radixC1;
+    private readonly _setDrainCache;
+    constructor(store: ObserverHost, ctx: SystemContext);
+    get count(): number;
+    /** The synthesized `SystemDescriptor`s of every registered observer, in
+     * registration order (`dispose()` splices entries out, so none are stale).
+     * Fed into the `startup()` archetype-prewarm closure so an observer's declared
+     * `spawns` / `transitions` create their target archetypes eagerly, exactly as a
+     * system's do (#768). Without this an observer-spawned/-transitioned archetype
+     * first-touches lazily mid-tick — the one asymmetry left in the otherwise
+     * uniform "no lazy archetypes" prewarm. */
+    descriptors(): SystemDescriptor[];
+    register(def: ComponentHandle, config: ObserverConfig): ObserverHandle;
+    private _dispose;
+    /** Recompute the component's hot-path observation flags from its live
+     * observers and push them to the store (which owns the flags + fast-path
+     * counters). */
+    private _reconfigureComponent;
+    private getTopo;
+    /**
+     * Fire onAdd / onRemove / onDisable / onEnable for one fixed-point round's
+     * effective events, in canonical order: access-topological across observers,
+     * entity-id order (radix) within each observer. Called by
+     * `Store.flushStructural` after the batch commits; observer callbacks may
+     * enqueue further structural ops (or toggles) onto the deferred buffers (the
+     * store loops until quiescent).
+     *
+     * The events arrive as flat `(comp, eid)` parallel arrays collected during the
+     * flush; we bucket by component once (O(K)), then walk observers in topo order
+     * so a producer's writes are visible to a consumer (glitch-free). A round
+     * carries either structural (add/rem) OR toggle (dis/ena) events, never both —
+     * toggles drain only once add/remove/destroy are quiescent (`flushStructural`)
+     * — but we bucket all four uniformly; the empty pairs are no-ops. Within an
+     * observer the fire order is remove, add, disable, enable (the "leaving" edges
+     * before the "entering" edges).
+     */
+    dispatchStructural(ev: StructuralObserverEvents): void;
+    /** Radix-sort `eids` by entity index (canonical within-observer order), then
+     * fire `fn` per entity under the observer's access scope. */
+    private _fireEach;
+    private _bucket;
+    private _clearBuckets;
+    /**
+     * Fire onSet observers for the current tick, in canonical order. Per-entity
+     * onSet drains the opt-in dirty list (once per changed entity); archetype-
+     * granular onSet scans the change tick (once per changed archetype-column).
+     * Called by `ECS.update` after all phases, with `tick === store._tick`.
+     */
+    dispatchSet(tick: number): void;
+    private _dispatchSetEntity;
+    private _dispatchSetArch;
+    private _yieldExisting;
+}
+/**
+ * O(K) LSD radix sort of entity ids by their 20-bit dense index (two 10-bit
+ * passes), in place. This is the canonical within-observer order — *never* a
+ * comparator `Array.sort`, which the bench measured at 2–4× the entire flush
+ * (`observer_dispatch_probe.ts`). Distinct live entities have distinct indices,
+ * so index order is a total canonical order. `out` is scratch (grown to length);
+ * `c0` / `c1` are 1024-entry histograms (reused).
+ */
+export declare function radixSortByIndex(eids: number[], out: number[], c0: Int32Array, c1: Int32Array): void;
+export {};
+//# sourceMappingURL=observer.d.ts.map