@ecsia/core 0.1.0

package/dist/reactivity/observer-commands.d.ts

@@ -0,0 +1,40 @@
+import type { ComponentDef, EntityHandle, RelationDef, RelationId, Schema } from '@ecsia/schema';
+/** The world verbs the deferred buffer replays at flush time (all serial / main-thread). */
+export interface ObserverCommandApply {
+    /** Place an already-minted (alive) handle into its target signature. The handle was reserved when
+     * the observer called spawn (so the observer could configure it); placement is deferred to flush. */
+    placeReserved(handle: EntityHandle, defs: readonly ComponentDef<Schema>[]): void;
+    add(handle: EntityHandle, def: ComponentDef<Schema>): void;
+    remove(handle: EntityHandle, def: ComponentDef<Schema>): void;
+    despawn(handle: EntityHandle): void;
+    isAlive(handle: EntityHandle): boolean;
+    /** Write initializer values through the tracked accessor path (value-carrying spawnWith, Item 8). */
+    writePayload(handle: EntityHandle, def: ComponentDef<Schema>, values: Record<string, unknown>): void;
+    /** Relation apply seams (undefined in a relation-free world). */
+    addPair?(subject: EntityHandle, relationId: RelationId, target: EntityHandle, payload: Record<string, unknown> | undefined): void;
+    removePair?(subject: EntityHandle, relationId: RelationId, target: EntityHandle): void;
+}
+export declare class ObserverCommandBuffer {
+    #private;
+    get deferring(): boolean;
+    get isDraining(): boolean;
+    get pendingCount(): number;
+    beginDeferring(): void;
+    endDeferring(): void;
+    enterDrain(): boolean;
+    exitDrain(): void;
+    stageSpawnWith(handle: EntityHandle, defs: readonly ComponentDef<Schema>[], values?: readonly (readonly [ComponentDef<Schema>, Record<string, unknown>])[]): void;
+    stageAdd(handle: EntityHandle, def: ComponentDef<Schema>): void;
+    stageRemove(handle: EntityHandle, def: ComponentDef<Schema>): void;
+    stageDespawn(handle: EntityHandle): void;
+    stageAddPair(subject: EntityHandle, relation: RelationDef<Schema | void>, relationId: RelationId, target: EntityHandle, payload: Record<string, unknown> | undefined): void;
+    stageRemovePair(subject: EntityHandle, relation: RelationDef<Schema | void>, relationId: RelationId, target: EntityHandle): void;
+    /**
+     * Apply every staged op in FIFO order (deterministic — staging order is the observers' fire order,
+     * which is itself deterministic merge order). Drop-if-dead is honored: a staged op whose subject is
+     * no longer alive at flush time is skipped (the entity was despawned by an earlier staged op or the
+     * intervening frame). Called at the start of the next drain — i.e. the next serial flush.
+     */
+    flush(apply: ObserverCommandApply): void;
+}
+//# sourceMappingURL=observer-commands.d.ts.map

package/dist/reactivity/observer-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-commands.d.ts","sourceRoot":"","sources":["../../src/reactivity/observer-commands.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AA6BhG,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC;yGACqG;IACrG,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAA;IAChF,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,IAAI,CAAA;IAC1D,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,IAAI,CAAA;IAC7D,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;IACnC,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAA;IACtC,qGAAqG;IACrG,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACpG,iEAAiE;IACjE,OAAO,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,CAAA;IACjI,UAAU,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;CACvF;AAED,qBAAa,qBAAqB;;IAOhC,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,cAAc,IAAI,IAAI;IAItB,YAAY,IAAI,IAAI;IAIpB,UAAU,IAAI,OAAO;IAMrB,SAAS,IAAI,IAAI;IAIjB,cAAc,CACZ,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,EACrC,MAAM,GAAE,SAAS,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAO,GACjF,IAAI;IAGP,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,IAAI;IAG/D,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,IAAI;IAGlE,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAGxC,YAAY,CACV,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,WAAW,CAAC,MAAM,GAAG,IAAI,CAAC,EACpC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,IAAI;IAGP,eAAe,CACb,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,WAAW,CAAC,MAAM,GAAG,IAAI,CAAC,EACpC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,YAAY,GACnB,IAAI;IAIP;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI;CAuCzC"}

package/dist/reactivity/observer-commands.js

@@ -0,0 +1,111 @@
+// Deferred observer command buffer. An observer handler MAY call
+// world.spawn()/despawn()/add()/remove()/addPair()/removePair() during observerDrain. Because the
+// drain runs at a serial slot — iterating a FROZEN log snapshot — those structural ops must NOT be
+// direct-applied mid-drain (a synchronous despawn shuffle-pops a row a later observer in the same
+// drain still needs to read, and a synchronous spawn would extend the wave the drain is replaying).
+//
+// Instead they are STAGED here and applied at the NEXT serial flush (the start of the next drain).
+// This is the main-thread analogue of the worker command buffer: the observer sees a quiescent world,
+// stages intent, and the intent lands deterministically one flush later. Consequence: an
+// entity spawned inside an onChange handler is observed by onAdd observers NEXT frame, never
+// re-entrantly this frame.
+export class ObserverCommandBuffer {
+    #pending = [];
+    /** Set while observerDrain is executing — structural verbs route here instead of direct-applying. */
+    #deferring = false;
+    /** Re-entrancy guard: observerDrain must never re-enter itself (a flush could trigger a drain). */
+    #draining = false;
+    get deferring() {
+        return this.#deferring;
+    }
+    get isDraining() {
+        return this.#draining;
+    }
+    get pendingCount() {
+        return this.#pending.length;
+    }
+    beginDeferring() {
+        this.#deferring = true;
+    }
+    endDeferring() {
+        this.#deferring = false;
+    }
+    enterDrain() {
+        if (this.#draining)
+            return false;
+        this.#draining = true;
+        return true;
+    }
+    exitDrain() {
+        this.#draining = false;
+    }
+    stageSpawnWith(handle, defs, values = []) {
+        this.#pending.push({ kind: 'spawnWith', handle, defs: defs.slice(), values: values.slice() });
+    }
+    stageAdd(handle, def) {
+        this.#pending.push({ kind: 'add', handle, def });
+    }
+    stageRemove(handle, def) {
+        this.#pending.push({ kind: 'remove', handle, def });
+    }
+    stageDespawn(handle) {
+        this.#pending.push({ kind: 'despawn', handle });
+    }
+    stageAddPair(subject, relation, relationId, target, payload) {
+        this.#pending.push({ kind: 'addPair', subject, relation, relationId, target, payload });
+    }
+    stageRemovePair(subject, relation, relationId, target) {
+        this.#pending.push({ kind: 'removePair', subject, relation, relationId, target });
+    }
+    /**
+     * Apply every staged op in FIFO order (deterministic — staging order is the observers' fire order,
+     * which is itself deterministic merge order). Drop-if-dead is honored: a staged op whose subject is
+     * no longer alive at flush time is skipped (the entity was despawned by an earlier staged op or the
+     * intervening frame). Called at the start of the next drain — i.e. the next serial flush.
+     */
+    flush(apply) {
+        if (this.#pending.length === 0)
+            return;
+        // Snapshot + clear FIRST so a re-entrant stage during apply (defensive) lands in the next batch,
+        // never extends this loop.
+        const ops = this.#pending;
+        this.#pending = [];
+        for (const op of ops) {
+            switch (op.kind) {
+                case 'spawnWith': {
+                    // The handle was reserved-alive when the observer called spawn; place it now, then write any
+                    // value-carrying initializers through the tracked path (Item 8).
+                    if (apply.isAlive(op.handle)) {
+                        apply.placeReserved(op.handle, op.defs);
+                        for (const [def, values] of op.values)
+                            apply.writePayload(op.handle, def, values);
+                    }
+                    break;
+                }
+                case 'add':
+                    if (apply.isAlive(op.handle))
+                        apply.add(op.handle, op.def);
+                    break;
+                case 'remove':
+                    if (apply.isAlive(op.handle))
+                        apply.remove(op.handle, op.def);
+                    break;
+                case 'despawn':
+                    if (apply.isAlive(op.handle))
+                        apply.despawn(op.handle);
+                    break;
+                case 'addPair':
+                    if (apply.addPair !== undefined && apply.isAlive(op.subject) && apply.isAlive(op.target)) {
+                        apply.addPair(op.subject, op.relationId, op.target, op.payload);
+                    }
+                    break;
+                case 'removePair':
+                    if (apply.removePair !== undefined && apply.isAlive(op.subject)) {
+                        apply.removePair(op.subject, op.relationId, op.target);
+                    }
+                    break;
+            }
+        }
+    }
+}
+//# sourceMappingURL=observer-commands.js.map

package/dist/reactivity/observer-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-commands.js","sourceRoot":"","sources":["../../src/reactivity/observer-commands.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,kGAAkG;AAClG,mGAAmG;AACnG,kGAAkG;AAClG,oGAAoG;AACpG,EAAE;AACF,mGAAmG;AACnG,sGAAsG;AACtG,yFAAyF;AACzF,6FAA6F;AAC7F,2BAA2B;AA+C3B,MAAM,OAAO,qBAAqB;IAChC,QAAQ,GAAiB,EAAE,CAAA;IAC3B,qGAAqG;IACrG,UAAU,GAAG,KAAK,CAAA;IAClB,mGAAmG;IACnG,SAAS,GAAG,KAAK,CAAA;IAEjB,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAA;IACxB,CAAC;IAED,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAA;IAC7B,CAAC;IAED,cAAc;QACZ,IAAI,CAAC,UAAU,GAAG,IAAI,CAAA;IACxB,CAAC;IAED,YAAY;QACV,IAAI,CAAC,UAAU,GAAG,KAAK,CAAA;IACzB,CAAC;IAED,UAAU;QACR,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO,KAAK,CAAA;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,SAAS;QACP,IAAI,CAAC,SAAS,GAAG,KAAK,CAAA;IACxB,CAAC;IAED,cAAc,CACZ,MAAoB,EACpB,IAAqC,EACrC,SAAgF,EAAE;QAElF,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IAC/F,CAAC;IACD,QAAQ,CAAC,MAAoB,EAAE,GAAyB;QACtD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IAClD,CAAC;IACD,WAAW,CAAC,MAAoB,EAAE,GAAyB;QACzD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IACrD,CAAC;IACD,YAAY,CAAC,MAAoB;QAC/B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAA;IACjD,CAAC;IACD,YAAY,CACV,OAAqB,EACrB,QAAoC,EACpC,UAAsB,EACtB,MAAoB,EACpB,OAA4C;QAE5C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAA;IACzF,CAAC;IACD,eAAe,CACb,OAAqB,EACrB,QAAoC,EACpC,UAAsB,EACtB,MAAoB;QAEpB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAA;IACnF,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAA2B;QAC/B,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QACtC,iGAAiG;QACjG,2BAA2B;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAA;QACzB,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAA;QAClB,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;gBAChB,KAAK,WAAW,CAAC,CAAC,CAAC;oBACjB,6FAA6F;oBAC7F,iEAAiE;oBACjE,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;wBAC7B,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,CAAA;wBACvC,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM;4BAAE,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;oBACnF,CAAC;oBACD,MAAK;gBACP,CAAC;gBACD,KAAK,KAAK;oBACR,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC;wBAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,CAAA;oBAC1D,MAAK;gBACP,KAAK,QAAQ;oBACX,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC;wBAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,CAAA;oBAC7D,MAAK;gBACP,KAAK,SAAS;oBACZ,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC;wBAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAA;oBACtD,MAAK;gBACP,KAAK,SAAS;oBACZ,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;wBACzF,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,CAAA;oBACjE,CAAC;oBACD,MAAK;gBACP,KAAK,YAAY;oBACf,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;wBAChE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,MAAM,CAAC,CAAA;oBACxD,CAAC;oBACD,MAAK;YACT,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/reactivity/observers.d.ts

@@ -0,0 +1,50 @@
+import type { ComponentDef, ComponentId, Schema } from '@ecsia/schema';
+import type { EntityRef } from '../entity/index.js';
+export type ObserverKind = 'add' | 'remove' | 'change';
+export interface ObserverHandle {
+    readonly id: number;
+    dispose(): void;
+}
+/** A typed observer subscription term (the component set + the kind), mirroring the query DSL. */
+export interface ObserverTerm {
+    readonly kind: ObserverKind;
+    readonly components: readonly ComponentDef<Schema>[];
+}
+export interface ObserverContext {
+    readonly kind: ObserverKind;
+    readonly component: ComponentId;
+    readonly tick: number;
+}
+export type ObserverHandler = (e: EntityRef, ctx: ObserverContext) => void;
+export declare function onAdd(...components: ComponentDef<Schema>[]): ObserverTerm;
+export declare function onRemove(...components: ComponentDef<Schema>[]): ObserverTerm;
+export declare function onChange(...components: ComponentDef<Schema>[]): ObserverTerm;
+export interface ObserverDeps {
+    /** Resolve a registered def's dense id (throws if not registered with this world). */
+    idOf(def: ComponentDef<Schema>): ComponentId;
+    /** Does `index` currently hold ALL of `componentIds`? (multi-component add satisfaction). */
+    holdsAll(index: number, componentIds: readonly ComponentId[]): boolean;
+    /** The pooled EntityRef bound to the current (index, generation) for `index`. */
+    refOf(index: number): EntityRef;
+    /** The current frame tick. */
+    tick(): number;
+}
+export declare class ObserverRegistry {
+    #private;
+    constructor(deps: ObserverDeps);
+    get hasObservers(): boolean;
+    /** True iff any `change`-kind observer is registered — gates the write-log push fast-out. */
+    get hasChangeObservers(): boolean;
+    /** True iff any observer subscribes to `kind` events on `componentId` — gates deferred-row reclaim. */
+    hasKindFor(kind: ObserverKind, componentId: number): boolean;
+    observe(term: ObserverTerm, handler: ObserverHandler): ObserverHandle;
+    /** Fire a structural (add/remove) event for one (index, componentId). */
+    dispatchStructural(kind: 'add' | 'remove', index: number, componentId: number): void;
+    /** Fire a change event for one (index, componentId), deduped per frame. */
+    dispatchChange(index: number, componentId: number): void;
+    /**: an overflow forces every change observer to assume worst-case. */
+    fireAllChangeConservatively(current: Iterable<number>): void;
+    /** Clear per-frame change dedup state (called at the start of each observer drain). */
+    resetChangeDedup(): void;
+}
+//# sourceMappingURL=observers.d.ts.map

package/dist/reactivity/observers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observers.d.ts","sourceRoot":"","sources":["../../src/reactivity/observers.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAEnD,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAEtD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,CAAA;CACrD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;AAY1E,wBAAgB,KAAK,CAAC,GAAG,UAAU,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,YAAY,CAEzE;AACD,wBAAgB,QAAQ,CAAC,GAAG,UAAU,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,YAAY,CAE5E;AACD,wBAAgB,QAAQ,CAAC,GAAG,UAAU,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,YAAY,CAE5E;AAED,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,WAAW,CAAA;IAC5C,6FAA6F;IAC7F,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAAA;IACtE,iFAAiF;IACjF,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,8BAA8B;IAC9B,IAAI,IAAI,MAAM,CAAA;CACf;AAED,qBAAa,gBAAgB;;gBAQf,IAAI,EAAE,YAAY;IAI9B,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,6FAA6F;IAC7F,IAAI,kBAAkB,IAAI,OAAO,CAEhC;IAED,uGAAuG;IACvG,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO;IAK5D,OAAO,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc;IA8BrE,yEAAyE;IACzE,kBAAkB,CAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAepF,2EAA2E;IAC3E,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAYxD,sEAAsE;IACtE,2BAA2B,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI;IAgB5D,uFAAuF;IACvF,gBAAgB,IAAI,IAAI;CAOzB"}

package/dist/reactivity/observers.js

@@ -0,0 +1,127 @@
+// Deferred observers. onAdd/onRemove/onChange register a handler in a
+// (kind, componentId) dispatch table. They fire ONLY from observerDrain at a serial slot —
+// NEVER synchronously from a setter or a migration. The drain walks the shape log (add/remove) and
+// the write log (change) once, looking up the bucket per entry (no per-event Array.from/reduce).
+export function onAdd(...components) {
+    return { kind: 'add', components };
+}
+export function onRemove(...components) {
+    return { kind: 'remove', components };
+}
+export function onChange(...components) {
+    return { kind: 'change', components };
+}
+export class ObserverRegistry {
+    #deps;
+    /** (kind, componentId) → observers. Key is `${kind}:${componentId}`. */
+    #table = new Map();
+    #seq = 0;
+    #count = 0;
+    #changeCount = 0;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    get hasObservers() {
+        return this.#count > 0;
+    }
+    /** True iff any `change`-kind observer is registered — gates the write-log push fast-out. */
+    get hasChangeObservers() {
+        return this.#changeCount > 0;
+    }
+    /** True iff any observer subscribes to `kind` events on `componentId` — gates deferred-row reclaim. */
+    hasKindFor(kind, componentId) {
+        const bucket = this.#table.get(`${kind}:${componentId}`);
+        return bucket !== undefined && bucket.length > 0;
+    }
+    observe(term, handler) {
+        const componentIds = term.components.map((d) => this.#deps.idOf(d));
+        const obs = { id: this.#seq++, term, handler, componentIds, dedup: new Set() };
+        for (const cid of componentIds) {
+            const key = `${term.kind}:${cid}`;
+            let bucket = this.#table.get(key);
+            if (bucket === undefined) {
+                bucket = [];
+                this.#table.set(key, bucket);
+            }
+            bucket.push(obs);
+        }
+        this.#count += 1;
+        if (term.kind === 'change')
+            this.#changeCount += 1;
+        return {
+            id: obs.id,
+            dispose: () => {
+                for (const cid of componentIds) {
+                    const key = `${term.kind}:${cid}`;
+                    const bucket = this.#table.get(key);
+                    if (bucket === undefined)
+                        continue;
+                    const i = bucket.indexOf(obs);
+                    if (i >= 0)
+                        bucket.splice(i, 1);
+                }
+                this.#count -= 1;
+                if (term.kind === 'change')
+                    this.#changeCount -= 1;
+            },
+        };
+    }
+    /** Fire a structural (add/remove) event for one (index, componentId). */
+    dispatchStructural(kind, index, componentId) {
+        const bucket = this.#table.get(`${kind}:${componentId}`);
+        if (bucket === undefined)
+            return;
+        const tick = this.#deps.tick();
+        for (const obs of bucket) {
+            // Multi-component terms: fire only if the entity now satisfies the whole term (add) — a remove
+            // fires per just-removed component (the entity no longer satisfies, by construction).
+            if (kind === 'add' && obs.componentIds.length > 1 && !this.#deps.holdsAll(index, obs.componentIds)) {
+                continue;
+            }
+            const ref = this.#deps.refOf(index);
+            obs.handler(ref, { kind, component: componentId, tick });
+        }
+    }
+    /** Fire a change event for one (index, componentId), deduped per frame. */
+    dispatchChange(index, componentId) {
+        const bucket = this.#table.get(`change:${componentId}`);
+        if (bucket === undefined)
+            return;
+        const tick = this.#deps.tick();
+        for (const obs of bucket) {
+            if (obs.dedup.has(index))
+                continue;
+            obs.dedup.add(index);
+            const ref = this.#deps.refOf(index);
+            obs.handler(ref, { kind: 'change', component: componentId, tick });
+        }
+    }
+    /**: an overflow forces every change observer to assume worst-case. */
+    fireAllChangeConservatively(current) {
+        const tick = this.#deps.tick();
+        for (const [key, bucket] of this.#table) {
+            if (!key.startsWith('change:'))
+                continue;
+            const componentId = Number(key.slice('change:'.length));
+            for (const index of current) {
+                for (const obs of bucket) {
+                    if (obs.dedup.has(index))
+                        continue;
+                    obs.dedup.add(index);
+                    const ref = this.#deps.refOf(index);
+                    obs.handler(ref, { kind: 'change', component: componentId, tick });
+                }
+            }
+        }
+    }
+    /** Clear per-frame change dedup state (called at the start of each observer drain). */
+    resetChangeDedup() {
+        for (const bucket of this.#table.values()) {
+            for (const obs of bucket) {
+                if (obs.term.kind === 'change')
+                    obs.dedup.clear();
+            }
+        }
+    }
+}
+//# sourceMappingURL=observers.js.map

package/dist/reactivity/observers.js.map

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

package/dist/reactivity/reactivity.d.ts

@@ -0,0 +1,141 @@
+import type { Buffers } from '../memory/index.js';
+import type { ComponentDef, ComponentId, EntityHandle, Schema } from '@ecsia/schema';
+import type { EntityRef } from '../entity/index.js';
+import type { LiveQuery } from '../query/index.js';
+import { ShapeKind } from './log.js';
+import type { StructuralRecord } from './structural-journal.js';
+import type { ObserverHandle, ObserverHandler, ObserverTerm } from './observers.js';
+export interface ReactivityDeps {
+    readonly buffers: Buffers;
+    readonly maxEntities: number;
+    readonly indexBits: number;
+    readonly logEntryWords: 1 | 2;
+    readonly maxWritesPerFrame: number;
+    readonly maxShapeChangesPerFrame: number;
+    readonly shrinkRings: boolean;
+    readonly dev: boolean;
+    /** index → its (archetypeId, row) — for changeVersion stamping + the public predicate. */
+    resolveLocation(index: number): {
+        archetypeId: number;
+        row: number;
+    };
+    /** The world frame tick (world owns it; reactivity reads it, never holds it). */
+    tick(): number;
+    /** Advance the world frame tick (world.advanceTick). Called at frameReset. */
+    advanceTick(): void;
+    /** Resolve a registered def's dense id. */
+    idOf(def: ComponentDef<Schema>): ComponentId;
+    /** Does `index` currently hold ALL of `componentIds`? */
+    holdsAll(index: number, componentIds: readonly ComponentId[]): boolean;
+    /** The pooled EntityRef bound to the current (index, generation) for `index` (observer dispatch). */
+    refOf(index: number): EntityRef;
+    /** index → its current FULL (generational) handle — for the structural journal's portable handles. */
+    resolveHandle(index: number): number;
+    /** The accessor's shared write-path fast-out cell. Reactivity flips `.active` whenever a write consumer
+     * (changed-flavor pointer / change observer) or changeVersion stamping (de)registers, so the setter's
+     * `track()` can skip the handleIndex decode + closure hops when no consumer is present. */
+    readonly tracking: {
+        active: boolean;
+    };
+}
+export declare class Reactivity {
+    #private;
+    constructor(deps: ReactivityDeps);
+    /** Late-bind the single-entity maintenance hook (the query engine's maintainEntity). */
+    setMaintainHook(fn: (index: number, componentId: number) => void): void;
+    /** Late-bind a "current matching members across all queries" source for the conservative path. */
+    setCurrentMembersSource(fn: () => Iterable<number>): void;
+    /** +: push the write entry (when a consumer exists) and stamp changeVersion (when enabled).
+     * Single-thread. The write log is read ONLY by changed-flavor query pointers and change observers; with
+     * neither present every appended word is dead (rewound at frame-recycle), so the push is a pure cost on
+     * the iteration hot path. Gate it on `#writeLogActive` (recomputed on flavor/observer (de)registration) —
+     * a semantics-preserving fast-out, since a later-attached changed flavor's pointer starts at the live head
+     * and sees only writes after it attaches. Pack the word inline (no per-write array). */
+    trackWrite(index: number, componentId: ComponentId, fieldIndex?: number): void;
+    /**: append one shape entry. Main thread only, O(1). */
+    trackShape(index: number, componentId: ComponentId, kind: ShapeKind): void;
+    /**: carries the target index in word B/C. */
+    trackShapePair(index: number, pairId: ComponentId, targetIndex: number, kind: ShapeKind.AddPair | ShapeKind.RemovePair): void;
+    /**
+     * _PAYLOAD: a non-exclusive overflow pair's payload changed on an already-live pair. This is
+     * NOT a membership change (no shape-log entry, no add/remove observer), but it IS a structural delta
+     * the since-T stream must carry, so we record it in the persistent journal only
+     * (overflow payload changes are explicit OP_PAIR_PAYLOAD records).
+     */
+    trackShapeSetPayload(index: number, pairId: ComponentId, targetIndex: number): void;
+    /**
+     * The enqueueRemoveLog stub body: storage calls this for each component in fromArch \ toArch at
+     * a migration, and for each held component at despawn (BEFORE removeRow + identity invalidation,
+     * ). It emits a shape-log Remove entry — the single source for onRemove dispatch + Removed
+     * delta maintenance.
+     */
+    enqueueRemoveLog(index: number, componentId: ComponentId): void;
+    /** Enable per-row changeVersion stamping (a `.changed` predicate consumer / serializer exists). */
+    enableChangeVersion(): void;
+    /**
+     * Enable the persistent structural journal (the since-T STRUCTURAL source). A delta serializer
+     * that includes the structural section calls this once at construction — it is the structural twin of
+     * `enableChangeVersion`. Until then, zero record cost.
+     */
+    enableStructuralJournal(): void;
+    /**
+     * /: the structural ops committed with tick > since, in commit order, as portable full-handle
+     * records. `gap` is true when `since` predates the bounded journal's live window (the caller must
+     * resync from a fresh snapshot — the no-partial-apply delta-gap rule).
+     */
+    drainStructuralSince(since: number): {
+        records: StructuralRecord[];
+        gap: boolean;
+    };
+    /**: "did any component on `handle` change since tick `since`?" (strict >). */
+    changedSince(handle: EntityHandle, since: number): boolean;
+    /**
+     * /: rows of `archetypeId` whose ENTITY's stamp is > since (the delta-serializer scan).
+     * `indexOfRow` maps a live row of the archetype to its entity index — the stamp is keyed by entity
+     * index (it follows the entity across relocations), so we resolve each row's current occupant.
+     */
+    changedRows(_archetypeId: number, since: number, count: number, indexOfRow: (row: number) => number): Iterable<number>;
+    currentTick(): number;
+    observe(term: ObserverTerm, handler: ObserverHandler): ObserverHandle;
+    /**: is there a remove-observer on `componentId` (gates deferred row reclaim)? */
+    hasRemoveObserver(componentId: number): boolean;
+    /**
+     *: allocate the `changed` flavor's LogPointer + dedup bitset for `q`. `added`/`removed` lists
+     * are owned by the LiveQuery itself and filled by maintenance; this hook wires only `changed`.
+     */
+    attachChangedFlavor(q: LiveQuery, componentIds: Iterable<number>): void;
+    /**
+     * _CHANGED: drain `q`'s write-log pointer, returning this frame's changed indices (deduped,
+     * intersected with `q.current` and the query's filtered components). Write-log driven — never
+     * consults changeVersion.
+     */
+    drainChanged(q: LiveQuery): Uint32Array;
+    /**: start of frame — advance the world tick, snapshot peak, recycle the rings. */
+    frameReset(): void;
+    /**: merge per-worker write corrals into the shared ring (deterministic). No-op single-thread. */
+    mergeCorrals(): void;
+    /**
+     * /+: merge ONE worker's staged value writes into the shared write log. `pairs` is a
+     * flat `[index, componentId, index, componentId, …]` buffer (the worker's raw corral payload); the
+     * caller drives this in ASCENDING worker-index order so the merged stream is deterministic. We
+     * (re)pack each pair through the module's own packWrite so single/wide layout stays the single
+     * source of truth — the worker never duplicates the packing scheme. Writes flow into the SAME ring
+     * the main thread appends to, so `.changed` filters and onChange observers fire for worker writes
+     * exactly as for single-thread writes.: when changeVersion is enabled we also
+     * stamp each row here (the worker hot path stays atomic-free; the stamp lands at the serial merge).
+     */
+    mergeWorkerWrites(pairs: Int32Array | Uint32Array, count: number): void;
+    /**
+     * _STRUCTURAL: drain the shape log, re-testing each affected entity against the queries
+     * referencing the changed component. In single-thread mode already maintains `current`
+     * synchronously at the commit point, so this re-runs the same idempotent re-test off the log (the
+     * drain is the spec's serial mechanism; the synchronous path is the optimization that agrees with
+     * it). Add/remove coalesce within the frame because the drain happens once.
+     */
+    maintainStructural(): void;
+    /** _DRAIN: fire deferred observers from the saved shape/write pointers. */
+    observerDrain(): void;
+    /** _LOGS: drain/merge spill (consumers already drained it), schedule next-frame resize. */
+    flushLogs(): void;
+}
+//# sourceMappingURL=reactivity.d.ts.map

package/dist/reactivity/reactivity.d.ts.map

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