@oasys/oecs 0.5.3 → 0.6.0

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

@@ -1,142 +1,126 @@
-import { SystemContext } from './query.js';
+import { SystemEntry, SystemSet, SystemSetConfig } from './system_set.js';
+import { Phase, PhaseConfig, SchedulePhase } from './phase.js';
+import { SystemContext } from './system_context.js';
 import { SystemDescriptor } from './system.js';
 import { ComputeBackend } from './compute_backend.js';
-import { RunCondition } from './run_condition.js';
-export declare enum SCHEDULE {
-    PRE_STARTUP = "PRE_STARTUP",
-    STARTUP = "STARTUP",
-    POST_STARTUP = "POST_STARTUP",
-    FIXED_UPDATE = "FIXED_UPDATE",
-    PRE_UPDATE = "PRE_UPDATE",
-    UPDATE = "UPDATE",
-    POST_UPDATE = "POST_UPDATE"
-}
-/**
- * An opaque handle for a named group of systems (#576). A set carries a shared
- * run condition and shared ordering that every member inherits. Sets are
- * identified by **object identity**, not by name — create one with
- * `systemSet(name)`, hold the handle, and reuse it across `addSystems`
- * (`SystemEntry.set`) and `Schedule.configureSet`. The `name` is for
- * diagnostics only.
- */
-export interface SystemSet {
-    readonly name: string;
-}
-/** Create a `SystemSet` handle (#576). Two calls with the same name are two
- * distinct sets — keep the returned handle and pass it around. */
-export declare function systemSet(name: string): SystemSet;
-/** A `before`/`after` ordering target: either a concrete system or a whole set
- * (expanded to its members within the same phase at sort time). */
-export type SystemOrderingTarget = SystemDescriptor | SystemSet;
-/** Shared configuration applied to a `SystemSet` via `configureSet` (#576).
- * Accumulates across calls — conditions AND together, ordering targets union. */
-export interface SystemSetConfig {
-    /** Condition(s) every member is gated by (ANDed with each member's own). */
-    runIf?: RunCondition | readonly RunCondition[];
-    /** Every member runs before each of these targets. */
-    before?: readonly SystemOrderingTarget[];
-    /** Every member runs after each of these targets. */
-    after?: readonly SystemOrderingTarget[];
-}
-export interface SystemOrdering {
-    before?: readonly SystemOrderingTarget[];
-    after?: readonly SystemOrderingTarget[];
-}
-export interface SystemEntry {
-    system: SystemDescriptor;
-    ordering?: SystemOrdering;
-    /** Run condition(s) gating just this system — ANDed with any set conditions
-     * it inherits (#576). A `false` verdict skips the body that tick. */
-    runIf?: RunCondition | readonly RunCondition[];
-    /** Set membership — the system inherits each set's shared condition and
-     * ordering (#576). */
-    set?: SystemSet | readonly SystemSet[];
+/** What the schedule needs of a worker pool, and nothing more.
+ *
+ * The pool ships in the workers plugin, so a class reference here would pull
+ * the pool, the plan builder and the node threads shim into every program.
+ * This interface is structural, and it erases, so the core graph reaches none
+ * of them. `run` answers false below the row threshold, before the kernel is
+ * loaded, and after a failed join. Then the sequential body runs. */
+export interface RouteDispatch {
+    /** `plan` is the opaque value the descriptor carries. The schedule loads
+     * it and passes it on, and only the route reads inside it. Answering false
+     * puts this dispatch back on the system's own `fn`. */
+    run(plan: object, ctx: SystemContext, deltaTime: number, runTick: number): boolean;
 }
 export declare class Schedule {
-    private readonly labelSystems;
-    private readonly sortedCache;
-    private readonly systemIndex;
-    private readonly systemLastRun;
-    private readonly gatedSystems;
-    private readonly setConditions;
-    private readonly setOrdering;
-    private nextInsertionOrder;
+    private readonly _phases;
+    private readonly _builtins;
+    private _startupOrder;
+    private _fixedOrder;
+    private _updateOrder;
+    private readonly _phaseBySystem;
+    private readonly _lastRunTicks;
+    private readonly _slotBySystem;
+    private readonly _freeSlots;
+    private _driveDepth;
+    private readonly _gatedSystems;
+    private readonly _conditionsBySet;
+    private readonly _orderingBySet;
+    private _nextInsertionOrder;
     private _backend;
-    /** Dev-diagnostic sink (`ECSOptions.onWarn`); defaults to `console.warn`.
-     * The only schedule diagnostic today is `warnDroppedEdge`. */
-    private readonly onWarn;
+    private _route;
+    /** Dev-diagnostic sink (`ECSOptions.onWarn`). Defaults to `console.warn`.
+     * The only schedule diagnostic today is the dropped ordering edge
+     * `schedule_plan.ts` reports. */
+    private readonly _onWarn;
+    private _fixedSystemCount;
+    private _nextPhaseOrder;
     constructor(onWarn?: (message: string) => void);
-    addSystems(label: SCHEDULE, ...entries: (SystemDescriptor | SystemEntry)[]): void;
     /**
-     * Configure a `SystemSet` (#576) — its shared run condition(s) and/or
+     * Add one phase to a loop and hand back its handle. Cold path, setup only.
+     *
+     * `before` and `after` order it against the other phases of the same loop.
+     * A target in another loop is dropped, the way a system ordered against a
+     * system in another phase is dropped. With neither, the phase runs after
+     * every phase declared before it, so it lands at the tail of its loop.
+     *
+     * The handle is this world's. Two calls with one name make two phases, the
+     * rule `systemSet` already follows, so hold the handle rather than the name.
+     */
+    addPhase(name: string, config: PhaseConfig): Phase;
+    private _declarePhase;
+    /** Check that a phase belongs to this schedule, and hand it back unchanged.
+     * Not a dev guard: a handle from another world would push systems into that
+     * world's list, and a production build that scheduled them into nothing is
+     * worse than a named fault on a setup call. */
+    private _checkPhase;
+    /** The node behind either spelling of a phase. Cold path. */
+    private _resolvePhase;
+    /** Sort one loop's phases and cache the result. Kahn's algorithm with
+     * declaration order as the tiebreaker, the same rule the systems inside a
+     * phase follow. Cold path, once per `addPhase`. */
+    private _resolveOrder;
+    addSystems(phase: SchedulePhase, ...entries: (SystemDescriptor | SystemEntry)[]): void;
+    /**
+     * Configure a `SystemSet`, its shared run conditions, or its
      * ordering, inherited by every member. Additive and order-independent w.r.t.
      * `addSystems`: conditions accumulate (ANDed), ordering targets union, and
      * a member added before or after this call picks the configuration up.
      */
     configureSet(set: SystemSet, config: SystemSetConfig): void;
     removeSystem(system: SystemDescriptor): void;
-    /** Attach (or, with `null`, detach) the opt-in compute backend (#622). Driven
-     * by `ECS.attachBackend`; routes any scheduled system carrying a
+    /** Drop every cached plan. Cold path, and the reason each caller needs it
+     * sits at that call site. */
+    private _invalidatePlans;
+    /** Attach (or, with `null`, detach) the opt-in compute backend. Driven
+     * by `ECS.attachBackend`. Routes any scheduled system carrying a
      * `backendHandle` to `backend.run(handle)` in place of its `fn`. */
     setBackend(backend: ComputeBackend | null): void;
-    runStartup(ctx: SystemContext, tick: number): void;
-    runUpdate(ctx: SystemContext, deltaTime: number, tick: number): void;
-    runFixedUpdate(ctx: SystemContext, fixedDt: number, tick: number): void;
+    /** Attach (or, with `null`, detach) the system dispatch route. Driven by
+     * the plugin that installed it. Runs any scheduled system carrying a
+     * `routePlan` through the route in place of its `fn`. */
+    setRoute(dispatch: RouteDispatch | null): void;
+    runStartup(ctx: SystemContext): void;
+    runUpdate(ctx: SystemContext, deltaTime: number): void;
+    runFixedUpdate(ctx: SystemContext, fixedDt: number): void;
     hasFixedSystems(): boolean;
     getAllSystems(): SystemDescriptor[];
     hasSystem(system: SystemDescriptor): boolean;
+    /** Hand `descriptor` its `_lastRunTicks` slot, keeping the array packed (no
+     * holes ⇒ no undefined-check on the read in `_runPhase`, which is the whole
+     * point of it not being a `Map`). Idempotent for a descriptor already in this
+     * schedule, `_getPlan` re-asks for every system it sorts. A descriptor that
+     * was removed and re-added gets a *fresh* slot starting at tick 0, which is
+     * what the previous `Map`-based bookkeeping did (`delete` on remove, `set(…, 0)`
+     * on re-add). */
+    private _assignLastRunSlot;
     clear(): void;
-    private runLabel;
+    private _runPhase;
     /**
-     * Whether a gated system runs this tick — the AND of its own conditions and
+     * Whether a gated system runs this tick, the and of its own conditions and
      * every set it belongs to. A set's conditions are evaluated at most once per
      * phase (memoized in `setVerdicts`) and the verdict gates every member of the
-     * set uniformly; a `configureSet` between phases is still honored because the
-     * memo lives only for a single `runLabel` pass. Short-circuits on the first
+     * set uniformly. A `configureSet` between phases is still honored because the
+     * memo lives only for a single `_runPhase` pass. Short-circuits on the first
      * `false`. The system's own conditions evaluate per system, in canonical order.
      *
-     * #731 SEMANTIC NOTE: this evaluates a set's conditions once-per-set-per-phase
-     * rather than once-per-member. Equivalent for pure RunConditions; observably
-     * different only if a set condition reads state mutated earlier in the SAME
-     * phase (resources write immediately). That is intentional — the set gates as a
-     * unit, so all its members share one verdict for the phase.
+     * This evaluates a set's conditions once for each set in each phase, and not
+     * once for each member. The two agree for a pure `RunCondition`. They differ
+     * only when a set condition reads state a system mutated earlier in the same
+     * phase (a resource writes immediately). That is intentional. The set gates
+     * as a unit, so every member shares one verdict for the phase.
      */
-    private shouldRun;
-    /** Evaluate a condition list with AND semantics. Each predicate runs inside a
+    private _shouldRun;
+    /** Evaluate a condition list with and semantics. Each predicate runs inside a
      * reads-only `accessCheck` span (dev), so a condition that reads an
-     * undeclared resource — or attempts any mutation — throws. */
-    private evalConditions;
-    private getSorted;
-    /**
-     * Delegates to the shared topologicalSort utility.
-     * Builds the dependency edge map from before/after constraints, then
-     * catches any cycle TypeError and re-throws as ECSError.
-     */
-    private sortSystems;
-    /**
-     * Add the topo edges for one ordering list (#576). For `"before"` the source
-     * runs before each target (edge source→target); for `"after"` it runs after
-     * each target (edge target→source). A `SystemSet` target expands to every
-     * member within this phase (self-edges skipped, so a member ordered against
-     * its own set is a no-op); a descriptor target absent from this phase is
-     * dropped — with a dev warning only for a concrete system, since a set
-     * legitimately expands to nothing when its members live in another phase.
-     */
-    private resolveEdges;
-    /** Push one directed edge into the adjacency map. Both endpoints are known to
-     * be in this phase (callers guard), so `edges.get(...)` is non-null. */
-    private addDirectedEdge;
-    /**
-     * Dev-only diagnostic for an ordering edge that was dropped during sort.
-     *
-     * Cross-label ordering is impossible by design (`nodeSet` is per-label), so
-     * a target registered in *another* phase is skipped silently — that's the
-     * intended isolation. But a target unknown to *every* phase is almost
-     * certainly a typo or a system that was never scheduled; without this warning
-     * the constraint vanishes and the system runs in insertion-order tiebreak as
-     * if unconstrained, with nothing to distinguish mistake from intent. Compiled
-     * out of production builds by the `DEV` guards at the call sites.
-     */
-    private warnDroppedEdge;
+     * undeclared resource, or attempts any mutation, throws. */
+    private _evalConditions;
+    /** Sort one phase and cache its plan on the phase. Cold: the drive reads
+     * `phase.plan` and only lands here when an add or a remove nulled it. */
+    private _buildPlan;
 }
 //# sourceMappingURL=schedule.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmCK;AAGL,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAMpD,oBAAY,QAAQ;IACnB,WAAW,gBAAgB;IAC3B,OAAO,YAAY;IACnB,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,UAAU,eAAe;IACzB,MAAM,WAAW;IACjB,WAAW,gBAAgB;CAC3B;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;kEACkE;AAClE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAEjD;AAED;mEACmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAEhE;iFACiF;AACjF,MAAM,WAAW,eAAe;IAC/B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,YAAY,EAAE,CAAC;IAC/C,sDAAsD;IACtD,MAAM,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACzC,qDAAqD;IACrD,KAAK,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC9B,MAAM,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACzC,KAAK,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;yEACqE;IACrE,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,YAAY,EAAE,CAAC;IAC/C;0BACsB;IACtB,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,SAAS,EAAE,CAAC;CACvC;AA8BD,qBAAa,QAAQ;IACpB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0C;IACvE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgD;IAC5E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8C;IAC1E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4C;IAI1E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgD;IAG7E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6C;IAC3E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAGd;IACd,OAAO,CAAC,kBAAkB,CAAK;IAM/B,OAAO,CAAC,QAAQ,CAA+B;IAE/C;kEAC8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;gBAEvC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI;IAWvC,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC,gBAAgB,GAAG,WAAW,CAAC,EAAE,GAAG,IAAI;IAwCxF;;;;;OAKG;IACI,YAAY,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IA0B3D,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IA+BnD;;wEAEoE;IAC7D,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI;IAIhD,UAAU,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAMlD,SAAS,CAAC,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAMpE,cAAc,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIvE,eAAe,IAAI,OAAO;IAK1B,aAAa,IAAI,gBAAgB,EAAE;IAUnC,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;IAI5C,KAAK,IAAI,IAAI;IAYpB,OAAO,CAAC,QAAQ;IA6DhB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,SAAS;IAwBjB;;kEAE8D;IAC9D,OAAO,CAAC,cAAc;IAetB,OAAO,CAAC,SAAS;IAWjB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IA2FnB;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IA4BpB;4EACwE;IACxE,OAAO,CAAC,eAAe;IAevB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,eAAe;CAgBvB"}
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/schedule.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,33 @@
+import { SystemOrderingTarget, SystemSet } from './system_set.cjs';
+import { SystemDescriptor } from './system.cjs';
+import { RunCondition } from './run_condition.cjs';
+/** A phase's execution plan: its topologically sorted systems and, index-aligned,
+ * each one's `_lastRunTicks` slot. Cached as a unit and invalidated together. */
+export interface PhasePlan {
+    readonly sorted: SystemDescriptor[];
+    readonly slots: Int32Array;
+}
+export interface SystemNode {
+    descriptor: SystemDescriptor;
+    insertionOrder: number;
+    before: Set<SystemOrderingTarget>;
+    after: Set<SystemOrderingTarget>;
+    /** This system's own run conditions (set conditions are resolved live from
+     * `_conditionsBySet` at run time so a later `configureSet` is honored). */
+    conditions: readonly RunCondition[];
+    /** Sets this system belongs to. */
+    sets: readonly SystemSet[];
+}
+/** One set's accumulated ordering, as `configureSet` builds it. A `Set` and not
+ * an array, so a target named twice still adds one edge. */
+export interface SetOrdering {
+    before: Set<SystemOrderingTarget>;
+    after: Set<SystemOrderingTarget>;
+}
+/**
+ * Delegates to the shared topologicalSort utility.
+ * Builds the dependency edge map from before and after constraints, then
+ * catches any cycle TypeError and re-throws as ECSError.
+ */
+export declare function sortSystems(nodes: SystemNode[], phase: string, orderingBySet: ReadonlyMap<SystemSet, SetOrdering>, scheduledSystems: ReadonlyMap<SystemDescriptor, unknown>, onWarn: (message: string) => void): SystemDescriptor[];
+//# sourceMappingURL=schedule_plan.d.ts.map

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

@@ -0,0 +1,33 @@
+import { SystemOrderingTarget, SystemSet } from './system_set.js';
+import { SystemDescriptor } from './system.js';
+import { RunCondition } from './run_condition.js';
+/** A phase's execution plan: its topologically sorted systems and, index-aligned,
+ * each one's `_lastRunTicks` slot. Cached as a unit and invalidated together. */
+export interface PhasePlan {
+    readonly sorted: SystemDescriptor[];
+    readonly slots: Int32Array;
+}
+export interface SystemNode {
+    descriptor: SystemDescriptor;
+    insertionOrder: number;
+    before: Set<SystemOrderingTarget>;
+    after: Set<SystemOrderingTarget>;
+    /** This system's own run conditions (set conditions are resolved live from
+     * `_conditionsBySet` at run time so a later `configureSet` is honored). */
+    conditions: readonly RunCondition[];
+    /** Sets this system belongs to. */
+    sets: readonly SystemSet[];
+}
+/** One set's accumulated ordering, as `configureSet` builds it. A `Set` and not
+ * an array, so a target named twice still adds one edge. */
+export interface SetOrdering {
+    before: Set<SystemOrderingTarget>;
+    after: Set<SystemOrderingTarget>;
+}
+/**
+ * Delegates to the shared topologicalSort utility.
+ * Builds the dependency edge map from before and after constraints, then
+ * catches any cycle TypeError and re-throws as ECSError.
+ */
+export declare function sortSystems(nodes: SystemNode[], phase: string, orderingBySet: ReadonlyMap<SystemSet, SetOrdering>, scheduledSystems: ReadonlyMap<SystemDescriptor, unknown>, onWarn: (message: string) => void): SystemDescriptor[];
+//# sourceMappingURL=schedule_plan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schedule_plan.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/schedule_plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;KAkBK;AAIL,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIpD;iFACiF;AACjF,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IAC1B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAClC,KAAK,EAAE,GAAG,CAAC,oBAAoB,CAAC,CAAC;IACjC;+EAC2E;IAC3E,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IACpC,mCAAmC;IACnC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;CAC3B;AAED;4DAC4D;AAC5D,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAClC,KAAK,EAAE,GAAG,CAAC,oBAAoB,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,UAAU,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,WAAW,CAAC,SAAS,EAAE,WAAW,CAAC,EAClD,gBAAgB,EAAE,WAAW,CAAC,gBAAgB,EAAE,OAAO,CAAC,EACxD,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC/B,gBAAgB,EAAE,CAyGpB"}

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

@@ -0,0 +1,77 @@
+import { Archetype } from './archetype.cjs';
+import { RelationStoreView } from './relation.cjs';
+import { SparseComponentStore } from './sparse_store.cjs';
+import { ColumnStore, InPlaceBufferAllocator } from '../store/index.cjs';
+/** Combined-frame format version. Bumped if the section framing or host-state
+ * layout changes. Independent of `SIM_ABI_VERSION` (which gates the dense
+ * bytes). */
+export declare const ECS_SNAPSHOT_VERSION = 1;
+/** Per-archetype host-side row bookkeeping the SAB doesn't carry authoritatively. */
+export interface ArchetypeRowState {
+    readonly archetypeId: number;
+    /** Total live rows (enabled + disabled). */
+    readonly length: number;
+    /** Enabled-row partition boundary: rows `[0, enabledCount)` enabled. */
+    readonly enabledCount: number;
+}
+/** The host-side state a snapshot captures alongside the dense + sparse bytes. */
+export interface HostState {
+    /** World tick at snapshot time (`Store.tick`). */
+    readonly tick: number;
+    /** Entity-index high-water (count of slots ever issued). Also mirrored in the
+     * SAB region's `length` header. Carried here for a cross-check on restore. */
+    readonly entityHighWater: number;
+    /** Live entity count. */
+    readonly entityAliveCount: number;
+    /** Recycle free-list in live order (LIFO: the last element is the next slot
+     * `createEntity` hands out). */
+    readonly freeIndices: readonly number[];
+    /** Per-archetype row state, one entry per SAB-backed archetype. */
+    readonly archetypeRows: readonly ArchetypeRowState[];
+}
+/** What the snapshot and resume orchestration needs from `Store`, closure-
+ * injected (the `RelationServiceHost` style). Accessors re-read live fields
+ * per call (the column store and the entity-index views are replaced on
+ * restore). The three mutation members keep Store-owned state transitions on
+ * the Store side. All cold-path. */
+export interface SnapshotHost {
+    readonly sparseStores: () => readonly SparseComponentStore[];
+    /** The relation stores, narrowed to what the codec folds and rebuilds. A
+     * world without the relations plugin answers with an empty list. */
+    readonly relationStores: () => readonly RelationStoreView[];
+    /** Live SAB generations view (replanted on restore), for rebuilding
+     * relation ids from entity indices. */
+    readonly generations: () => Int32Array;
+    readonly archetypes: () => readonly Archetype[];
+    readonly columnStore: () => ColumnStore;
+    readonly bufferAllocator: () => InPlaceBufferAllocator;
+    readonly entityIndexCapacity: () => number;
+    readonly tick: () => number;
+    readonly setTick: (tick: number) => void;
+    /** Stamp live row counts into the dense descriptors so a bare dense
+     * reader of the snapshot sees self-consistent counts. */
+    readonly publishRowCounts: () => void;
+    /** Adopt a restored dense store: swap the live backing, refresh archetype
+     * views, recover the allocator high-water from the restored region, and
+     * republish (the grow tail). Owned by Store, see `_mountRestoredDense`. */
+    readonly mountRestoredDense: (restored: ColumnStore) => void;
+    /** Rebuild each archetype's host-side `length` and `enabledCount`/entity-id
+     * back-references from the restored entity-index region + captured host
+     * state. Owned by Store, see `_reconstructHostRows`. */
+    readonly reconstructHostRows: (host: HostState) => void;
+    /** Every archetype's membership only changed, bump the query epoch and
+     * force the next descriptor publish. */
+    readonly invalidateCaches: () => void;
+}
+/** What the world calls into a snapshot service it did not build.
+ *
+ * `Store` keeps the `DETERMINISM_DISABLED` gate and delegates the four
+ * captures and mounts through this. A world without the plugin holds `null`
+ * here and answers a reach with the fault that names the import. */
+export interface SnapshotHooks {
+    snapshot(): Uint8Array;
+    restore(bytes: Uint8Array): void;
+    snapshotSparse(): Uint8Array;
+    restoreSparse(bytes: Uint8Array): void;
+}
+//# sourceMappingURL=snapshot.d.ts.map

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

@@ -0,0 +1,77 @@
+import { Archetype } from './archetype.js';
+import { RelationStoreView } from './relation.js';
+import { SparseComponentStore } from './sparse_store.js';
+import { ColumnStore, InPlaceBufferAllocator } from '../store/index.js';
+/** Combined-frame format version. Bumped if the section framing or host-state
+ * layout changes. Independent of `SIM_ABI_VERSION` (which gates the dense
+ * bytes). */
+export declare const ECS_SNAPSHOT_VERSION = 1;
+/** Per-archetype host-side row bookkeeping the SAB doesn't carry authoritatively. */
+export interface ArchetypeRowState {
+    readonly archetypeId: number;
+    /** Total live rows (enabled + disabled). */
+    readonly length: number;
+    /** Enabled-row partition boundary: rows `[0, enabledCount)` enabled. */
+    readonly enabledCount: number;
+}
+/** The host-side state a snapshot captures alongside the dense + sparse bytes. */
+export interface HostState {
+    /** World tick at snapshot time (`Store.tick`). */
+    readonly tick: number;
+    /** Entity-index high-water (count of slots ever issued). Also mirrored in the
+     * SAB region's `length` header. Carried here for a cross-check on restore. */
+    readonly entityHighWater: number;
+    /** Live entity count. */
+    readonly entityAliveCount: number;
+    /** Recycle free-list in live order (LIFO: the last element is the next slot
+     * `createEntity` hands out). */
+    readonly freeIndices: readonly number[];
+    /** Per-archetype row state, one entry per SAB-backed archetype. */
+    readonly archetypeRows: readonly ArchetypeRowState[];
+}
+/** What the snapshot and resume orchestration needs from `Store`, closure-
+ * injected (the `RelationServiceHost` style). Accessors re-read live fields
+ * per call (the column store and the entity-index views are replaced on
+ * restore). The three mutation members keep Store-owned state transitions on
+ * the Store side. All cold-path. */
+export interface SnapshotHost {
+    readonly sparseStores: () => readonly SparseComponentStore[];
+    /** The relation stores, narrowed to what the codec folds and rebuilds. A
+     * world without the relations plugin answers with an empty list. */
+    readonly relationStores: () => readonly RelationStoreView[];
+    /** Live SAB generations view (replanted on restore), for rebuilding
+     * relation ids from entity indices. */
+    readonly generations: () => Int32Array;
+    readonly archetypes: () => readonly Archetype[];
+    readonly columnStore: () => ColumnStore;
+    readonly bufferAllocator: () => InPlaceBufferAllocator;
+    readonly entityIndexCapacity: () => number;
+    readonly tick: () => number;
+    readonly setTick: (tick: number) => void;
+    /** Stamp live row counts into the dense descriptors so a bare dense
+     * reader of the snapshot sees self-consistent counts. */
+    readonly publishRowCounts: () => void;
+    /** Adopt a restored dense store: swap the live backing, refresh archetype
+     * views, recover the allocator high-water from the restored region, and
+     * republish (the grow tail). Owned by Store, see `_mountRestoredDense`. */
+    readonly mountRestoredDense: (restored: ColumnStore) => void;
+    /** Rebuild each archetype's host-side `length` and `enabledCount`/entity-id
+     * back-references from the restored entity-index region + captured host
+     * state. Owned by Store, see `_reconstructHostRows`. */
+    readonly reconstructHostRows: (host: HostState) => void;
+    /** Every archetype's membership only changed, bump the query epoch and
+     * force the next descriptor publish. */
+    readonly invalidateCaches: () => void;
+}
+/** What the world calls into a snapshot service it did not build.
+ *
+ * `Store` keeps the `DETERMINISM_DISABLED` gate and delegates the four
+ * captures and mounts through this. A world without the plugin holds `null`
+ * here and answers a reach with the fault that names the import. */
+export interface SnapshotHooks {
+    snapshot(): Uint8Array;
+    restore(bytes: Uint8Array): void;
+    snapshotSparse(): Uint8Array;
+    restoreSparse(bytes: Uint8Array): void;
+}
+//# sourceMappingURL=snapshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;KAUK;AAEL,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAEpE;;aAEa;AACb,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAED,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACzB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;kFAC8E;IAC9E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,yBAAyB;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;oCACgC;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACrD;AAED;;;;oCAIoC;AACpC,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,SAAS,oBAAoB,EAAE,CAAC;IAC7D;wEACoE;IACpE,QAAQ,CAAC,cAAc,EAAE,MAAM,SAAS,iBAAiB,EAAE,CAAC;IAC5D;2CACuC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,UAAU,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,SAAS,SAAS,EAAE,CAAC;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,WAAW,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,MAAM,sBAAsB,CAAC;IACvD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,MAAM,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC;6DACyD;IACzD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,IAAI,CAAC;IACtC;;+EAE2E;IAC3E,QAAQ,CAAC,kBAAkB,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;IAC7D;;4DAEwD;IACxD,QAAQ,CAAC,mBAAmB,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACxD;4CACwC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,IAAI,CAAC;CACtC;AAED;;;;oEAIoE;AACpE,MAAM,WAAW,aAAa;IAC7B,QAAQ,IAAI,UAAU,CAAC;IACvB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,cAAc,IAAI,UAAU,CAAC;IAC7B,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACvC"}

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

@@ -0,0 +1,42 @@
+import { ColumnStore } from '../store/column_store.cjs';
+import { ArchetypeID } from './archetype_types.cjs';
+import { EntityAllocator } from './entity_allocator.cjs';
+import { HostState } from './snapshot.cjs';
+/** What a restore asks of an archetype. Every live `Archetype` satisfies it. */
+export interface RestorableArchetype {
+    readonly isBufferBacked: boolean;
+    refreshViews(store: ColumnStore): void;
+    resetTicks(): void;
+    restoreHostRows(rows: number[], enabledCount: number): void;
+}
+/** One archetype, by id, for the row reconstruction below. */
+export type ArchetypeLookup = (id: ArchetypeID) => RestorableArchetype;
+/**
+ * Republish every buffer-backed archetype's views over the restored backing,
+ * drop the row ticks, and recover the allocator high-water from the restored
+ * entity-index region.
+ *
+ * The caller assigns the restored store to its own field first, and calls its
+ * buffer-resized handler after. The high-water read has to happen before that
+ * handler, because the handler mirrors the host high-water back into the
+ * header and a stale host value would clobber the restored one.
+ *
+ * The rows under the tick plane belong to the snapshot now, so no record made
+ * before the restore names a write of theirs. That is why every archetype's
+ * ticks reset, buffer-backed or not.
+ */
+export declare function adoptRestoredBacking(restored: ColumnStore, archetypes: readonly RestorableArchetype[], allocator: EntityAllocator): void;
+/**
+ * Rebuild each buffer-backed archetype's host-side `length`, `enabledCount`
+ * and per-row entity ids after a restore swapped the dense backing.
+ *
+ * `length` and the row-to-entity back reference come from a scan of the
+ * restored entity-index region, which says what entity occupies what row.
+ * `enabledCount` comes from the captured host state, because the enabled
+ * partition boundary is positional and has no per-entity byte source.
+ *
+ * The caller guarantees that `entityArchetypes` and `entityRows` are the views
+ * over the restored region, not the views from before the swap.
+ */
+export declare function reconstructHostRows(host: HostState, archetypeAt: ArchetypeLookup, entityArchetypes: Int32Array, entityRows: Int32Array, allocator: EntityAllocator): void;
+//# sourceMappingURL=snapshot_mount.d.ts.map

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

@@ -0,0 +1,42 @@
+import { ColumnStore } from '../store/column_store.js';
+import { ArchetypeID } from './archetype_types.js';
+import { EntityAllocator } from './entity_allocator.js';
+import { HostState } from './snapshot.js';
+/** What a restore asks of an archetype. Every live `Archetype` satisfies it. */
+export interface RestorableArchetype {
+    readonly isBufferBacked: boolean;
+    refreshViews(store: ColumnStore): void;
+    resetTicks(): void;
+    restoreHostRows(rows: number[], enabledCount: number): void;
+}
+/** One archetype, by id, for the row reconstruction below. */
+export type ArchetypeLookup = (id: ArchetypeID) => RestorableArchetype;
+/**
+ * Republish every buffer-backed archetype's views over the restored backing,
+ * drop the row ticks, and recover the allocator high-water from the restored
+ * entity-index region.
+ *
+ * The caller assigns the restored store to its own field first, and calls its
+ * buffer-resized handler after. The high-water read has to happen before that
+ * handler, because the handler mirrors the host high-water back into the
+ * header and a stale host value would clobber the restored one.
+ *
+ * The rows under the tick plane belong to the snapshot now, so no record made
+ * before the restore names a write of theirs. That is why every archetype's
+ * ticks reset, buffer-backed or not.
+ */
+export declare function adoptRestoredBacking(restored: ColumnStore, archetypes: readonly RestorableArchetype[], allocator: EntityAllocator): void;
+/**
+ * Rebuild each buffer-backed archetype's host-side `length`, `enabledCount`
+ * and per-row entity ids after a restore swapped the dense backing.
+ *
+ * `length` and the row-to-entity back reference come from a scan of the
+ * restored entity-index region, which says what entity occupies what row.
+ * `enabledCount` comes from the captured host state, because the enabled
+ * partition boundary is positional and has no per-entity byte source.
+ *
+ * The caller guarantees that `entityArchetypes` and `entityRows` are the views
+ * over the restored region, not the views from before the swap.
+ */
+export declare function reconstructHostRows(host: HostState, archetypeAt: ArchetypeLookup, entityArchetypes: Int32Array, entityRows: Int32Array, allocator: EntityAllocator): void;
+//# sourceMappingURL=snapshot_mount.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot_mount.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/snapshot_mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;KAoBK;AAGL,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAI1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,UAAU,IAAI,IAAI,CAAC;IACnB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5D;AAED,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG,CAAC,EAAE,EAAE,WAAW,KAAK,mBAAmB,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,WAAW,EACrB,UAAU,EAAE,SAAS,mBAAmB,EAAE,EAC1C,SAAS,EAAE,eAAe,GACxB,IAAI,CAWN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,SAAS,EACf,WAAW,EAAE,eAAe,EAC5B,gBAAgB,EAAE,UAAU,EAC5B,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,eAAe,GACxB,IAAI,CAuCN"}