@oasys/oecs 0.4.0 → 0.5.0

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

@@ -1,6 +1,6 @@
-import { ComponentDef } from './component';
-import { ResourceKey } from './resource';
-import { Query } from './query';
+import { ComponentDef } from './component.js';
+import { ResourceKey } from './resource.js';
+import { Query } from './query.js';
 /**
  * The read-only slice of `SystemContext` a run condition is handed. Deliberately
  * narrow — a condition can read the ECS tick and resources, but has no path to
@@ -11,7 +11,7 @@ import { Query } from './query';
 export interface ConditionContext {
     /** Current ECS tick — the deterministic clock built-ins key off. */
     readonly ecsTick: number;
-    /** Read a resource value (checked against `resourceReads` in `__DEV__`). */
+    /** Read a resource value (checked against `resourceReads` in `DEV`). */
     resource<T>(key: ResourceKey<T>): T;
     /** Membership probe for a resource — unchecked, mirrors `hasComponent`. */
     hasResource<T>(key: ResourceKey<T>): boolean;
@@ -32,14 +32,14 @@ export interface RunCondition {
      *  not runtime-checkable today, but it is the read-edge a parallel scheduler
      *  will consume. */
     readonly reads?: readonly ComponentDef[];
-    /** Resources the predicate reads. Validated at runtime in `__DEV__` when the
+    /** Resources the predicate reads. Validated at runtime in `DEV` when the
      *  condition evaluates inside `accessCheck.enterCondition`. */
-    readonly resourceReads?: readonly ResourceKey<unknown>[];
+    readonly resourceReads?: readonly ResourceKey<any>[];
 }
 /**
  * Run the gated system(s) only while a resource equals `expected` (strict `===`,
  * so reference identity for objects). The canonical "feature flag / game phase"
- * gate — flip `world.setResource(key, …)` and the whole group toggles.
+ * gate — flip `ecs.resources.set(key, …)` and the whole group toggles.
  */
 export declare function runIfResourceEq<T>(key: ResourceKey<T>, expected: T): RunCondition;
 /**
@@ -66,10 +66,16 @@ export declare function runEveryNTicks(n: number, offset?: number): RunCondition
  * its component defs are declared as `reads`. `count()` is a membership sum over
  * matching archetypes (no column reads), so it trips no `accessCheck` read.
  *
- * The query must be **dense-only**: `count()` asserts this in `__DEV__`
- * (`_assertDenseOnly`), so pass a plain `world.query(...)` — a query carrying
+ * The query must be **dense-only**: `entityCount` asserts this in `DEV`
+ * (`_assertDenseOnly`), so pass a plain `ecs.query(...)` — a query carrying
  * `.optional(...)` or sparse terms throws. Gate on sparse membership with a
  * custom predicate over `forEachEntity` instead.
  */
 export declare function runIfAnyMatch(query: Query<readonly ComponentDef[]>): RunCondition;
+/** Invert a condition: run exactly when `cond` would skip. */
+export declare function not(cond: RunCondition): RunCondition;
+/** Run only when EVERY condition passes (`&&`, short-circuit). */
+export declare function allOf(...conds: RunCondition[]): RunCondition;
+/** Run when ANY condition passes (`||`, short-circuit). */
+export declare function anyOf(...conds: RunCondition[]): RunCondition;
 //# sourceMappingURL=run_condition.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"run_condition.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/run_condition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA8BK;AAEL,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACpC,2EAA2E;IAC3E,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACtD;;;wBAGoB;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC;mEAC+D;IAC/D,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;CACzD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,YAAY,CAMjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,YAAY,CAclE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,YAAY,EAAE,CAAC,GAAG,YAAY,CAMjF"}
+{"version":3,"file":"run_condition.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/run_condition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA8BK;AAEL,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIrC;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACpC,2EAA2E;IAC3E,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACtD;;;wBAGoB;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC;mEAC+D;IAC/D,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,YAAY,CAcjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,YAAY,CAoBlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,YAAY,EAAE,CAAC,GAAG,YAAY,CAMjF;AA4BD,8DAA8D;AAC9D,wBAAgB,GAAG,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CAMpD;AAED,kEAAkE;AAClE,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CAM5D;AAED,2DAA2D;AAC3D,wBAAgB,KAAK,CAAC,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CAM5D"}

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

@@ -0,0 +1,142 @@
+import { SystemContext } from './query.cjs';
+import { SystemDescriptor } from './system.cjs';
+import { ComputeBackend } from './compute_backend.cjs';
+import { RunCondition } from './run_condition.cjs';
+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[];
+}
+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 _backend;
+    /** Dev-diagnostic sink (`ECSOptions.onWarn`); defaults to `console.warn`.
+     * The only schedule diagnostic today is `warnDroppedEdge`. */
+    private readonly onWarn;
+    constructor(onWarn?: (message: string) => void);
+    addSystems(label: SCHEDULE, ...entries: (SystemDescriptor | SystemEntry)[]): void;
+    /**
+     * Configure a `SystemSet` (#576) — its shared run condition(s) and/or
+     * 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
+     * `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;
+    hasFixedSystems(): boolean;
+    getAllSystems(): SystemDescriptor[];
+    hasSystem(system: SystemDescriptor): boolean;
+    clear(): void;
+    private runLabel;
+    /**
+     * 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
+     * `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.
+     */
+    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;
+}
+//# sourceMappingURL=schedule.d.ts.map

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

@@ -1,7 +1,7 @@
-import { SystemContext } from './query';
-import { SystemDescriptor } from './system';
-import { ComputeBackend } from './compute_backend';
-import { RunCondition } from './run_condition';
+import { SystemContext } from './query.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",
@@ -62,7 +62,10 @@ export declare class Schedule {
     private readonly setOrdering;
     private nextInsertionOrder;
     private _backend;
-    constructor();
+    /** Dev-diagnostic sink (`ECSOptions.onWarn`); defaults to `console.warn`.
+     * The only schedule diagnostic today is `warnDroppedEdge`. */
+    private readonly onWarn;
+    constructor(onWarn?: (message: string) => void);
     addSystems(label: SCHEDULE, ...entries: (SystemDescriptor | SystemEntry)[]): void;
     /**
      * Configure a `SystemSet` (#576) — its shared run condition(s) and/or
@@ -91,6 +94,12 @@ export declare class Schedule {
      * set uniformly; a `configureSet` between phases is still honored because the
      * memo lives only for a single `runLabel` 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.
      */
     private shouldRun;
     /** Evaluate a condition list with AND semantics. Each predicate runs inside a
@@ -126,7 +135,7 @@ export declare class Schedule {
      * 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.
+     * out of production builds by the `DEV` guards at the call sites.
      */
     private warnDroppedEdge;
 }

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

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

@@ -0,0 +1,94 @@
+import { Archetype } from './archetype.cjs';
+import { EntityAllocator } from './entity_allocator.cjs';
+import { SparseComponentStore } from './sparse_store.cjs';
+import { RelationStore } from './relation.cjs';
+import { ColumnStore, InPlaceBufferAllocator } from '../store/index.cjs';
+import { HostState } from './resume.cjs';
+/** What the snapshot/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[];
+    readonly relationStores: () => readonly RelationStore[];
+    /** 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`/`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 just changed — bump the query epoch and
+     * force the next descriptor publish. */
+    readonly invalidateQueryCaches: () => void;
+}
+export declare class SnapshotService {
+    private readonly host;
+    /** The allocator IS its own snapshot seam (H1 step 3): free-list copy on
+     * capture; `setHighWater` + `restoreHostState` on mount. */
+    private readonly allocator;
+    constructor(host: SnapshotHost, allocator: EntityAllocator);
+    /** Serialize the sparse stores **and** relation side data to a self-contained
+     * byte buffer — the sparse half of a world snapshot (the dense half is the
+     * SAB snapshot). Two framed sections: the sparse stores (`snapshotSparseStores`
+     * — exclusive relation targets + multi membership ride here) followed
+     * by the relation side data (`snapshotRelations` — multi forward target
+     * sets, which live outside the sparse store). Both are written in canonical
+     * entity-index order, so two worlds with identical contents inserted in
+     * different orders snapshot byte-for-byte the same (#470). The reverse index
+     * is derived and never serialized — `restoreSparse` rebuilds it. */
+    snapshotSparse(): Uint8Array;
+    /** Repopulate the sparse stores from `snapshotSparse` bytes, replacing all
+     * current sparse data (full-equality round-trip of membership + data), then
+     * rebuild every relation's derived side indices: multi forward sets from the
+     * relation section, and the reverse index for both cardinalities (exclusive
+     * from the just-restored sparse target field, multi from the rebuilt forward
+     * sets). The sparse components and relations must already be registered in
+     * the same order — restore carries data, not the registration (which is
+     * code). Throws `SparseRestoreError` if the snapshot's shape, field identity,
+     * entity-index bounds, or frame length don't validate. */
+    restoreSparse(bytes: Uint8Array): void;
+    /** Rebuild every relation's derived side indices after the sparse stores have
+     * been restored. `restoreRelations` resets all relations, rebuilds the multi
+     * forward sets + their reverse edges from `relBytes`, and validates shape.
+     * The exclusive reverse index can't be carried in the bytes (it's derivable),
+     * so it's rebuilt here from the backing sparse store: every member row holds
+     * `(source index → target EntityID)`, which is exactly one reverse edge. */
+    private rebuildRelationIndices;
+    /** Capture the full live world to one self-contained byte buffer that
+     * `restoreInto` can mount back onto a live, ticking world (#789). Three
+     * sections (see `resume.ts`): the dense SAB column bytes, the sparse +
+     * relation bytes, and the host-side bookkeeping the SAB omits. */
+    snapshot(): Uint8Array;
+    /** Gather the host-side state a snapshot carries alongside the dense + sparse
+     * bytes — see `snapshot()`. The free-list is copied (it's a live mutable). */
+    private collectHostState;
+    /** Mount a `snapshot()` buffer onto the live world and leave it ready to keep
+     * ticking. Fails closed on a malformed frame or a registration mismatch
+     * BEFORE any live state is touched. */
+    restoreInto(bytes: Uint8Array): void;
+    /** Read-only validation of a `snapshotSparse` SECTION (the framed
+     * `[sparseLen][relLen][sparse][rel]` buffer) against the live registry, used
+     * by `restoreInto` to fail closed on a sparse-registration mismatch BEFORE the
+     * dense mount commits. Mirrors `restoreSparse`'s frame check, then validates the
+     * sparse-stores sub-section without mutating. A relation-registration difference
+     * surfaces here too: every `registerRelation` adds a backing sparse store, so a
+     * differing relation set changes the sparse store count / schema. Throws
+     * `SparseRestoreError` on a mismatch. */
+    private assertSparseSectionMatches;
+}
+//# sourceMappingURL=snapshot_service.d.ts.map

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

@@ -0,0 +1,94 @@
+import { Archetype } from './archetype.js';
+import { EntityAllocator } from './entity_allocator.js';
+import { SparseComponentStore } from './sparse_store.js';
+import { RelationStore } from './relation.js';
+import { ColumnStore, InPlaceBufferAllocator } from '../store/index.js';
+import { HostState } from './resume.js';
+/** What the snapshot/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[];
+    readonly relationStores: () => readonly RelationStore[];
+    /** 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`/`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 just changed — bump the query epoch and
+     * force the next descriptor publish. */
+    readonly invalidateQueryCaches: () => void;
+}
+export declare class SnapshotService {
+    private readonly host;
+    /** The allocator IS its own snapshot seam (H1 step 3): free-list copy on
+     * capture; `setHighWater` + `restoreHostState` on mount. */
+    private readonly allocator;
+    constructor(host: SnapshotHost, allocator: EntityAllocator);
+    /** Serialize the sparse stores **and** relation side data to a self-contained
+     * byte buffer — the sparse half of a world snapshot (the dense half is the
+     * SAB snapshot). Two framed sections: the sparse stores (`snapshotSparseStores`
+     * — exclusive relation targets + multi membership ride here) followed
+     * by the relation side data (`snapshotRelations` — multi forward target
+     * sets, which live outside the sparse store). Both are written in canonical
+     * entity-index order, so two worlds with identical contents inserted in
+     * different orders snapshot byte-for-byte the same (#470). The reverse index
+     * is derived and never serialized — `restoreSparse` rebuilds it. */
+    snapshotSparse(): Uint8Array;
+    /** Repopulate the sparse stores from `snapshotSparse` bytes, replacing all
+     * current sparse data (full-equality round-trip of membership + data), then
+     * rebuild every relation's derived side indices: multi forward sets from the
+     * relation section, and the reverse index for both cardinalities (exclusive
+     * from the just-restored sparse target field, multi from the rebuilt forward
+     * sets). The sparse components and relations must already be registered in
+     * the same order — restore carries data, not the registration (which is
+     * code). Throws `SparseRestoreError` if the snapshot's shape, field identity,
+     * entity-index bounds, or frame length don't validate. */
+    restoreSparse(bytes: Uint8Array): void;
+    /** Rebuild every relation's derived side indices after the sparse stores have
+     * been restored. `restoreRelations` resets all relations, rebuilds the multi
+     * forward sets + their reverse edges from `relBytes`, and validates shape.
+     * The exclusive reverse index can't be carried in the bytes (it's derivable),
+     * so it's rebuilt here from the backing sparse store: every member row holds
+     * `(source index → target EntityID)`, which is exactly one reverse edge. */
+    private rebuildRelationIndices;
+    /** Capture the full live world to one self-contained byte buffer that
+     * `restoreInto` can mount back onto a live, ticking world (#789). Three
+     * sections (see `resume.ts`): the dense SAB column bytes, the sparse +
+     * relation bytes, and the host-side bookkeeping the SAB omits. */
+    snapshot(): Uint8Array;
+    /** Gather the host-side state a snapshot carries alongside the dense + sparse
+     * bytes — see `snapshot()`. The free-list is copied (it's a live mutable). */
+    private collectHostState;
+    /** Mount a `snapshot()` buffer onto the live world and leave it ready to keep
+     * ticking. Fails closed on a malformed frame or a registration mismatch
+     * BEFORE any live state is touched. */
+    restoreInto(bytes: Uint8Array): void;
+    /** Read-only validation of a `snapshotSparse` SECTION (the framed
+     * `[sparseLen][relLen][sparse][rel]` buffer) against the live registry, used
+     * by `restoreInto` to fail closed on a sparse-registration mismatch BEFORE the
+     * dense mount commits. Mirrors `restoreSparse`'s frame check, then validates the
+     * sparse-stores sub-section without mutating. A relation-registration difference
+     * surfaces here too: every `registerRelation` adds a backing sparse store, so a
+     * differing relation set changes the sparse store count / schema. Throws
+     * `SparseRestoreError` on a mismatch. */
+    private assertSparseSectionMatches;
+}
+//# sourceMappingURL=snapshot_service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot_service.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/snapshot_service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACN,oBAAoB,EAKpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EAGN,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAC3B,MAAM,UAAU,CAAC;AAClB,OAAO,EAON,KAAK,SAAS,EACd,MAAM,UAAU,CAAC;AAElB;;;;oCAIoC;AACpC,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,SAAS,oBAAoB,EAAE,CAAC;IAC7D,QAAQ,CAAC,cAAc,EAAE,MAAM,SAAS,aAAa,EAAE,CAAC;IACxD;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;;gFAE4E;IAC5E,QAAQ,CAAC,kBAAkB,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;IAC7D;;6DAEyD;IACzD,QAAQ,CAAC,mBAAmB,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACxD;4CACwC;IACxC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,IAAI,CAAC;CAC3C;AAED,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC;gEAC4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;gBAEhC,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,eAAe;IAK1D;;;;;;;;wEAQoE;IAC7D,cAAc,IAAI,UAAU;IAanC;;;;;;;;8DAQ0D;IACnD,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAuB7C;;;;;gFAK4E;IAC5E,OAAO,CAAC,sBAAsB;IAW9B;;;sEAGkE;IAC3D,QAAQ,IAAI,UAAU;IAa7B;kFAC8E;IAC9E,OAAO,CAAC,gBAAgB;IAqBxB;;2CAEuC;IAChC,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IA2C3C;;;;;;;6CAOyC;IACzC,OAAO,CAAC,0BAA0B;CAgBlC"}

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

@@ -0,0 +1,110 @@
+import { Brand, TypedArrayTag } from '../../type_primitives/index.cjs';
+import { ComponentSchema } from './component.cjs';
+/** Sparse-component handle id. A separate id space from `ComponentID` — it
+ * indexes `Store`'s `sparseStores`, never the archetype mask, which is the
+ * mechanism by which sparse components escape the 128-bit identity cap. */
+export type SparseComponentID = Brand<number, "sparse_component_id">;
+declare const __sparseSchema: unique symbol;
+export type SparseComponentDef<S extends ComponentSchema = ComponentSchema> = SparseComponentID & {
+    readonly [__sparseSchema]: S;
+};
+/** Recover a sparse def's schema type — the sparse sibling of `SchemaOf`
+ * (component.ts), used by the typed `SystemContext` sparse surface. */
+export type SparseSchemaOf<D> = D extends SparseComponentDef<infer S extends ComponentSchema> ? S : never;
+/** One sparse component's membership + data. Pure data structure — the `Store`
+ * owns liveness checks and dev-mode error throwing; this class only knows
+ * entity indices and field rows. */
+export declare class SparseComponentStore {
+    /** entity index → field-value row (length = field count; `[]` for a tag). */
+    private readonly _data;
+    readonly fieldNames: string[];
+    readonly fieldTypes: TypedArrayTag[];
+    readonly fieldIndex: Record<string, number>;
+    constructor(fieldNames: string[], fieldTypes: TypedArrayTag[]);
+    /** Number of entities holding this sparse component. */
+    get size(): number;
+    /** Live entity indices that hold this component (dense, iteration order is
+     * SparseMap insertion/swap order — NOT canonical). Used by the hot query
+     * integration path (#469); for the determinism surface use
+     * `canonicalIndices` instead. */
+    get indices(): readonly number[];
+    /** Live entity indices in **canonical** (ascending) order — the determinism
+     * ordering for `stateHash` + snapshot/restore (ADR-0011, #470). The native
+     * `indices` getter is insertion/swap order and would make two worlds with
+     * identical contents reached by different add/remove histories diverge, so
+     * the cold determinism paths sort here. Allocates a sorted copy each call;
+     * never call it on the hot query path. Indices are 20-bit entity indices,
+     * so the subtraction comparator can't overflow. */
+    canonicalIndices(): number[];
+    /** The field-value row for `index` (length = field count; `[]` for a tag),
+     * or `undefined` if `index` isn't a member. Read-only view for the
+     * determinism paths (`stateHash`, snapshot); mutate via `setField`. */
+    getRow(index: number): readonly number[] | undefined;
+    /** Drop all membership + data. Restore path only — `restoreSparseStores`
+     * repopulates a cleared store from snapshot bytes. */
+    clear(): void;
+    /** Insert the positional field-value `row` for `index`, taking ownership of
+     * the array. Restore path only; bypasses the name→index mapping `setRow`
+     * does, because snapshot bytes are already positional. */
+    setRawRow(index: number, row: number[]): void;
+    has(index: number): boolean;
+    /** Insert or overwrite the row for `index`, building it from `values`.
+     * Fields absent from `values` default to 0; a tag stores `[]`. */
+    setRow(index: number, values: Record<string, number>): void;
+    /** Drop `index`'s membership + data. Returns whether it was present. */
+    remove(index: number): boolean;
+    /** Read one field, or `undefined` if `index` doesn't hold this component. */
+    getField(index: number, fieldIdx: number): number | undefined;
+    /** Write one field. Returns `false` (no-op) if `index` isn't a member. */
+    setField(index: number, fieldIdx: number, value: number): boolean;
+}
+export declare class SparseRestoreError extends Error {
+    constructor(message: string);
+}
+/** Serialize a registry of sparse stores into a self-contained byte buffer —
+ * the **sparse half** of a world snapshot (the dense half is the SAB snapshot,
+ * `snapshotColumnStore`). Members are emitted in canonical (ascending
+ * entity-index) order so the bytes are independent of insertion / removal
+ * history: two worlds with identical sparse contents reached by different
+ * mutation orders serialize byte-for-byte the same (#470).
+ *
+ * Layout (all integers little-endian, to match the dense SAB snapshot and stay
+ * architecture-independent):
+ *
+ *   u32 storeCount
+ *   repeat storeCount times:
+ *     u32 fieldCount
+ *     u32 schemaHash
+ *     u32 memberCount
+ *     repeat memberCount times (canonical entity-index order):
+ *       u32 entityIndex
+ *       f64 × fieldCount   (the positional field row; none for a tag)
+ *
+ * `fieldCount` is redundant with the registered schema but is written so
+ * `restoreSparseStores` can reject a snapshot whose shape doesn't match the
+ * stores it's restoring into; `schemaHash` (a `schemaFingerprint` over the
+ * field names + types) goes further and rejects a buffer whose shape matches
+ * field-for-field but whose field **identity** doesn't (#494). */
+export declare function snapshotSparseStores(stores: readonly SparseComponentStore[]): Uint8Array;
+/** Repopulate already-registered sparse stores from `snapshotSparseStores`
+ * bytes, giving full-equality round-trip (membership + data). The `stores`
+ * registry must already exist with the same shape the snapshot was taken from
+ * — restore replays data into a world whose sparse components are registered
+ * in the same order (the registration is code, not snapshot state). Each store
+ * is cleared first, so restoring is idempotent and drops any pre-existing rows.
+ *
+ * Throws `SparseRestoreError` on any shape or identity mismatch (store count,
+ * field count, schema-hash field identity, an entity index past `MAX_INDEX`,
+ * or a truncated / over-long buffer) rather than silently corrupting state.
+ * The index bound matters because the index keys a `SparseMap` whose backing
+ * array grows to `index` length — an unvalidated crafted u32 (up to ~4.29e9)
+ * would allocate multi-GB (#494). */
+export declare function restoreSparseStores(stores: readonly SparseComponentStore[], bytes: Uint8Array): void;
+/** Read-only validation of a `snapshotSparseStores` buffer against the live
+ * registry, WITHOUT mutating any store (#789). Mirrors `restoreSparseStores`'s
+ * shape/field-identity/index-bounds/frame checks so `Store.restoreInto` can fail
+ * closed on a sparse-registration mismatch BEFORE the dense mount overwrites live
+ * column data. Throws `SparseRestoreError` on any mismatch / malformed buffer. */
+export declare function validateSparseStores(stores: readonly SparseComponentStore[], bytes: Uint8Array): void;
+export {};
+//# sourceMappingURL=sparse_store.d.ts.map

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

@@ -1,5 +1,5 @@
-import { Brand, TypedArrayTag } from '../../type_primitives';
-import { ComponentSchema } from './component';
+import { Brand, TypedArrayTag } from '../../type_primitives/index.js';
+import { ComponentSchema } from './component.js';
 /** Sparse-component handle id. A separate id space from `ComponentID` — it
  * indexes `Store`'s `sparseStores`, never the archetype mask, which is the
  * mechanism by which sparse components escape the 128-bit identity cap. */
@@ -8,6 +8,9 @@ declare const __sparseSchema: unique symbol;
 export type SparseComponentDef<S extends ComponentSchema = ComponentSchema> = SparseComponentID & {
     readonly [__sparseSchema]: S;
 };
+/** Recover a sparse def's schema type — the sparse sibling of `SchemaOf`
+ * (component.ts), used by the typed `SystemContext` sparse surface. */
+export type SparseSchemaOf<D> = D extends SparseComponentDef<infer S extends ComponentSchema> ? S : never;
 /** One sparse component's membership + data. Pure data structure — the `Store`
  * owns liveness checks and dev-mode error throwing; this class only knows
  * entity indices and field rows. */

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

@@ -1 +1 @@
-{"version":3,"file":"sparse_store.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/sparse_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KA0BK;AAEL,OAAO,EAAE,KAAK,EAAa,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD;;2EAE2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG,KAAK,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;AAOrE,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAE5C,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI,iBAAiB,GAAG;IACjG,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF;;oCAEoC;AACpC,qBAAa,oBAAoB;IAChC,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,SAAgB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrC,SAAgB,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5C,SAAgB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAEvC,UAAU,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE;IAQ7D,wDAAwD;IACxD,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;qCAGiC;IACjC,IAAW,OAAO,IAAI,SAAS,MAAM,EAAE,CAEtC;IAED;;;;;;uDAMmD;IAC5C,gBAAgB,IAAI,MAAM,EAAE;IAInC;;2EAEuE;IAChE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS;IAI3D;0DACsD;IAC/C,KAAK,IAAI,IAAI;IAIpB;;8DAE0D;IACnD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAI7C,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIlC;sEACkE;IAC3D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAUlE,wEAAwE;IACjE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIrC,6EAA6E;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKpE,0EAA0E;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;CAMxE;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI3B;AAuCD;;;;;;;;;;;;;;;;;;;;;;;kEAuBkE;AAClE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,GAAG,UAAU,CAuCxF;AAED;;;;;;;;;;;;qCAYqC;AACrC,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,SAAS,oBAAoB,EAAE,EACvC,KAAK,EAAE,UAAU,GACf,IAAI,CAkEN;AAED;;;;kFAIkF;AAClF,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,SAAS,oBAAoB,EAAE,EACvC,KAAK,EAAE,UAAU,GACf,IAAI,CA4DN"}
+{"version":3,"file":"sparse_store.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/sparse_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KA0BK;AAEL,OAAO,EAAE,KAAK,EAAa,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD;;2EAE2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG,KAAK,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;AAOrE,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAE5C,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI,iBAAiB,GAAG;IACjG,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF;uEACuE;AACvE,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,SAAS,kBAAkB,CAAC,MAAM,CAAC,SAAS,eAAe,CAAC,GAC1F,CAAC,GACD,KAAK,CAAC;AAET;;oCAEoC;AACpC,qBAAa,oBAAoB;IAChC,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,SAAgB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrC,SAAgB,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5C,SAAgB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAEvC,UAAU,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE;IAQ7D,wDAAwD;IACxD,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;qCAGiC;IACjC,IAAW,OAAO,IAAI,SAAS,MAAM,EAAE,CAEtC;IAED;;;;;;uDAMmD;IAC5C,gBAAgB,IAAI,MAAM,EAAE;IAInC;;2EAEuE;IAChE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS;IAI3D;0DACsD;IAC/C,KAAK,IAAI,IAAI;IAIpB;;8DAE0D;IACnD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAI7C,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIlC;sEACkE;IAC3D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAUlE,wEAAwE;IACjE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIrC,6EAA6E;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKpE,0EAA0E;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;CAMxE;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI3B;AAuCD;;;;;;;;;;;;;;;;;;;;;;;kEAuBkE;AAClE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,GAAG,UAAU,CAuCxF;AAED;;;;;;;;;;;;qCAYqC;AACrC,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,SAAS,oBAAoB,EAAE,EACvC,KAAK,EAAE,UAAU,GACf,IAAI,CAkEN;AAED;;;;kFAIkF;AAClF,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,SAAS,oBAAoB,EAAE,EACvC,KAAK,EAAE,UAAU,GACf,IAAI,CA4DN"}