@oasys/oecs 0.5.4 → 0.6.0

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

@@ -4,66 +4,67 @@ import { EntityID } from './entity.cjs';
 import { SparseComponentDef } from './sparse_store.cjs';
 import { RelationDef } from './relation.cjs';
 import { ResourceKey } from './resource.cjs';
-import { SystemContext } from './query.cjs';
+import { SystemContext } from './system_context.cjs';
 import { BackendSystemHandle } from './compute_backend.cjs';
-import { Template } from './store.cjs';
+import { Template } from './store_types.cjs';
+import { Query } from './query.cjs';
 export type SystemID = Brand<number, "system_id">;
 export declare const asSystemId: (value: number) => SystemID;
 export type SystemFn = (ctx: SystemContext, deltaTime: number) => void;
 /** A pair describing a mid-tick archetype transition.
  * If an entity has every component in `whenHas`, the system may `add`
- * and/or `remove` the listed components, transitioning the entity to a
+ * or `remove` the listed components, transitioning the entity to a
  * new archetype. Used to pre-warm the archetype graph. */
 export interface SystemTransition {
     readonly whenHas: readonly ComponentDef[];
     readonly add?: readonly ComponentDef[];
     readonly remove?: readonly ComponentDef[];
 }
-/** The access declaration as AUTHORED on a `SystemConfig`. `reads` /
- * `writes` are mandatory (empty arrays are explicit, not missing
- * annotations); the rarer structural and resource fields are optional with
- * absent = empty, mirroring the sparse/relation precedent. `spawns`
+/** The access declaration as authored on a `SystemConfig`. `reads` and
+ * `writes` are mandatory, and an empty array is explicit, not a missing
+ * annotation. The rarer structural and resource fields are optional, and
+ * absent reads as empty, mirroring the sparse and relation precedent. `spawns`
  * entries and `despawns` accept a `Template` wherever a component list is
- * expected — registration expands it via `_normalizeAccess`. */
+ * expected, registration expands it via `_normalizeAccess`. */
 export interface SystemAccessConfig {
-    /** Components the system READS but does not write. */
+    /** Components the system reads but does not write. */
     readonly reads: readonly ComponentDef[];
-    /** Components the system WRITES. A write is implicitly also a read. */
+    /** Components the system writes. A write is implicitly also a read. */
     readonly writes: readonly ComponentDef[];
     /** Archetype masks the system spawns entities into. Each entry is the
-     * union of components a spawned entity carries at flush time — an
+     * union of components a spawned entity carries at flush time, an
      * explicit def list, or a `Template` (expanded at registration). */
     readonly spawns?: readonly (readonly ComponentDef[] | Template)[];
-    /** Components removed via `removeComponent` / `despawn`.
-     * `despawn` counts as removing every component on the entity —
+    /** Components removed with `removeComponent` or `despawn`.
+     * `despawn` counts as removing every component on the entity,
      * declare the superset. A `Template` entry expands to its component
      * list, so a "destroys what the spawner spawns" system references the
      * same declaration. */
     readonly despawns?: readonly (ComponentDef | Template)[];
-    /** Mid-tick archetype transitions; see SystemTransition. */
+    /** Mid-tick archetype transitions. See SystemTransition. */
     readonly transitions?: readonly SystemTransition[];
     /** Resources the system reads. */
     readonly resourceReads?: readonly ResourceKey<any>[];
     /** Resources the system writes. */
     readonly resourceWrites?: readonly ResourceKey<any>[];
-    /** Sparse components the system READS via `getSparseField`
+    /** Sparse components the system reads via `getSparseField`
      * (membership probes `hasSparse` are unchecked, mirroring `hasComponent`). */
     readonly sparseReads?: readonly SparseComponentDef[];
-    /** Sparse components the system MUTATES via `addSparse` / `removeSparse` /
+    /** Sparse components the system mutates with `addSparse`, `removeSparse` or
      * `setSparseField`. A write implies a read. */
     readonly sparseWrites?: readonly SparseComponentDef[];
-    /** Relations the system READS via `targetOf` / `targetsOf` / `sourcesOf`
+    /** Relations the system reads with `targetOf`, `targetsOf` or `sourcesOf`
      * (`hasRelation` is unchecked, mirroring `hasComponent`). */
     readonly relationReads?: readonly RelationDef[];
-    /** Relations the system MUTATES via `addRelation` / `removeRelation`.
+    /** Relations the system mutates with `addRelation` or `removeRelation`.
      * A write implies a read. */
     readonly relationWrites?: readonly RelationDef[];
 }
-/** The NORMALIZED access declaration a registered system carries — what
- * `SystemDescriptor` exposes and `accessCheck` / prewarm consume. Produced
+/** The normalized access declaration a registered system carries, what
+ * `SystemDescriptor` exposes, and what `accessCheck` and prewarm consume. Produced
  * from the authored `SystemAccessConfig` by `_normalizeAccess`: absent
  * optional fields are the shared frozen empties, and every `Template` in
- * `spawns` / `despawns` is expanded to its component list. */
+ * `spawns` and `despawns` is expanded to its component list. */
 export interface SystemAccessDeclaration extends SystemAccessConfig {
     readonly spawns: readonly (readonly ComponentDef[])[];
     readonly despawns: readonly ComponentDef[];
@@ -71,6 +72,53 @@ export interface SystemAccessDeclaration extends SystemAccessConfig {
     readonly resourceReads: readonly ResourceKey<any>[];
     readonly resourceWrites: readonly ResourceKey<any>[];
 }
+/** A kernel body a worker can load. A worker cannot receive a closure, so a
+ * kernel is addressed by a module and an export name. */
+export type ParallelKernel = {
+    /** A compiled module. It is structured-clone safe, so one module object
+     * is shared with every worker. It imports the world's memory as
+     * `env.memory`, which the wasm backing supplies. */
+    readonly wasm: WebAssembly.Module;
+    readonly export: string;
+    readonly js?: never;
+} | {
+    /** An absolute module URL each worker imports. */
+    readonly js: string;
+    readonly export: string;
+    readonly wasm?: never;
+};
+/** One `(component, field)` pair a kernel takes, with the field name held to
+ * the component's own schema. */
+export type ParallelColumn<D> = D extends ComponentDef<infer S> ? readonly [D, Extract<keyof S, string>] : never;
+/**
+ * How a system runs across a pool of workers.
+ *
+ * The kernel receives, per matched archetype, one argument per declared column,
+ * then `begin`, `end` and `dt`. A js kernel takes a typed array spanning the
+ * whole column and indexes `begin` to `end`. A wasm kernel takes the absolute
+ * byte offset of the column's first row and addresses row `r` at
+ * `ptr + r * stride`, with the stride it knows from the field type.
+ *
+ * A parallel system stays a normal system: the same ordering, the same run
+ * conditions, the same sets. Its `fn` runs below the row threshold, on a world
+ * with no pool, and on a heap world.
+ */
+export interface ParallelConfig<D extends ComponentDef<any> = ComponentDef<any>> {
+    readonly kernel: ParallelKernel;
+    /** The kernel's argument order, one component and field for each. Every
+     * component named must be in `reads` or `writes` and in the query, and every
+     * component in `writes` must appear here. */
+    readonly columns: readonly ParallelColumn<D>[];
+    /** The total matched row count below which the system runs `fn` on the main
+     * thread. The default is a placeholder, and the caller must tune it. The
+     * crossover is a property of the machine and of the kernel, not of the
+     * engine, so no default is right for every world. */
+    readonly minRows?: number;
+    /** The query the kernel runs over. Defaults to the first entry of `queries`,
+     * resolved as a require-only query. Pass one built with `not` to get a
+     * require-and-exclude match. */
+    readonly query?: Query<any>;
+}
 export interface SystemConfig extends SystemAccessConfig {
     fn?(ctx: SystemContext, deltaTime: number): void;
     name?: string;
@@ -79,35 +127,40 @@ export interface SystemConfig extends SystemAccessConfig {
     dispose?: () => void;
     /** Components the system queries (via a captured `ecs.query(...)`), one
      * group per query.
-     * OPTIONAL — when provided, `registerSystem` validates `queries ⊆ reads ∪
+     * Optional, when provided, `registerSystem` validates `queries ⊆ reads ∪
      * writes` in `DEV` (`_assertQueriesDeclared`): a query term
      * reads each listed component, so this fails fast at registration instead of
      * at the first iteration's `accessCheck`. */
     queries?: readonly (readonly ComponentDef[])[];
-    /** Grant this system FULL world access — it may read/write/add/remove/destroy
-     * ANY component, sparse, relation, or resource without declaring them. The
-     * `DEV` access check is bypassed for its whole span (a no-op in
-     * production, where the check is already compiled out). For trusted engine /
-     * host machinery that mutates components not known at registration — the
-     * host→ECS command-apply system is the canonical case; a save/load or
-     * debug system is another. Bevy's "exclusive system" in spirit: full access,
-     * and — under any future parallel scheduler — it would run alone. The schedule
-     * is sequential today, so here it is purely the access grant. Use sparingly;
-     * a normal system should declare exactly what it touches. */
+    /** Grant this system full world access. It may read, write, add, remove and
+     * destroy any component, sparse, relation, or resource without declaring
+     * them. `accessCheck` skips its whole span in `DEV`, and a production build
+     * compiles that check out already. Trusted engine or host machinery that
+     * mutates components unknown at registration needs this. The host→ECS
+     * command-apply system is the canonical case, and a save and load or a debug
+     * system is another. It matches Bevy's "exclusive system" in spirit, where
+     * full access also means the system runs alone. This schedule is sequential
+     * today, so here it is purely the access grant. Use it sparingly. A normal
+     * system declares exactly what it touches. */
     exclusive?: boolean;
     /** Opt this system into pluggable-backend execution. When set **and**
      * a `ComputeBackend` is attached to the ECS, the `Schedule` runs
-     * `backend.run(backendHandle)` in place of `fn`; otherwise `fn` runs as the
+     * `backend.run(backendHandle)` in place of `fn`. Otherwise `fn` runs as the
      * TS fallback (a no-op `fn` ⇒ the system is effectively skipped when no
-     * backend is attached). The handle is opaque to the engine — minted by the
-     * backend. The system still declares its `reads`/`writes` so the access span
+     * backend is attached). The handle is opaque to the engine, minted by the
+     * backend. The system still declares its `reads` and `writes` so the access span
      * around the backend call authorises the shared-memory it touches, and so the
      * scheduler can order it. See `ComputeBackend`. */
     backendHandle?: BackendSystemHandle;
+    /** Opt this system into worker execution. When set **and** a pool is
+     * attached **and** the matched row count clears `parallel.minRows`, the
+     * schedule runs the kernel across the pool in place of `fn`. Otherwise `fn`
+     * runs, and the two must compute the same thing. See `ParallelConfig`. */
+    parallel?: ParallelConfig;
 }
 /**
  * The type-level access record a `SystemContext` is parameterized by. Each
- * field is the UNION of handle types the system declared for that operation
+ * field is the union of handle types the system declared for that operation
  * (`never` = declared nothing). The interface itself is the permissive
  * default: every field `any`-typed, `destroy` undetermined.
  */
@@ -125,29 +178,29 @@ export interface SystemAccess {
     resourceWrite: ResourceKey<any>;
 }
 /** `unknown` if `D` is in the system's declared read surface, else an error tuple. */
-export type DeclaredRead<A extends SystemAccess, D> = [D] extends [A["read"]] ? unknown : ["component is not declared in this system's reads/writes", D];
+export type DeclaredRead<A extends SystemAccess, D> = [D] extends [A["read"]] ? unknown : ["component is not declared in this system's reads or writes", D];
 /** `unknown` if `D` is in the system's declared write surface, else an error tuple. */
 export type DeclaredWrite<A extends SystemAccess, D> = [D] extends [A["write"]] ? unknown : ["component is not declared in this system's writes", D];
 /** `unknown` if `D` is an authorised addComponent target, else an error tuple. */
-export type DeclaredAdd<A extends SystemAccess, D> = [D] extends [A["add"]] ? unknown : ["component is not declared in this system's writes/spawns/transitions.add", D];
+export type DeclaredAdd<A extends SystemAccess, D> = [D] extends [A["add"]] ? unknown : ["component is not declared in this system's writes, spawns or transitions.add", D];
 /** `unknown` if `D` is an authorised removeComponent target, else an error tuple. */
-export type DeclaredRemove<A extends SystemAccess, D> = [D] extends [A["remove"]] ? unknown : ["component is not declared in this system's despawns/transitions.remove", D];
-export type DeclaredSparseRead<A extends SystemAccess, D> = [D] extends [A["sparseRead"]] ? unknown : ["sparse component is not declared in this system's sparseReads/sparseWrites", D];
+export type DeclaredRemove<A extends SystemAccess, D> = [D] extends [A["remove"]] ? unknown : ["component is not declared in this system's despawns or transitions.remove", D];
+export type DeclaredSparseRead<A extends SystemAccess, D> = [D] extends [A["sparseRead"]] ? unknown : ["sparse component is not declared in this system's sparseReads or sparseWrites", D];
 export type DeclaredSparseWrite<A extends SystemAccess, D> = [D] extends [A["sparseWrite"]] ? unknown : ["sparse component is not declared in this system's sparseWrites", D];
 /** Relations are one nominal type, so this only distinguishes "declared some
- * relation access" from "declared none" — the runtime check owns the rest.
+ * relation access" from "declared none", the runtime check owns the rest.
  * Keyed on the call site's inferred `D` (like the component asserts) rather
  * than on `RelationDef` directly: a conditional whose check type is not a
  * signature type parameter resolves under the compiler's variance-annotation
  * validation markers and falsely flags the `out A` declaration (TS2636). */
-export type DeclaredRelationRead<A extends SystemAccess, D> = [D] extends [A["relationRead"]] ? unknown : ["no relation is declared in this system's relationReads/relationWrites"];
+export type DeclaredRelationRead<A extends SystemAccess, D> = [D] extends [A["relationRead"]] ? unknown : ["no relation is declared in this system's relationReads or relationWrites"];
 export type DeclaredRelationWrite<A extends SystemAccess, D> = [D] extends [A["relationWrite"]] ? unknown : ["no relation is declared in this system's relationWrites"];
-export type DeclaredResourceRead<A extends SystemAccess, K> = [K] extends [A["resourceRead"]] ? unknown : ["resource key is not declared in this system's resourceReads/resourceWrites", K];
+export type DeclaredResourceRead<A extends SystemAccess, K> = [K] extends [A["resourceRead"]] ? unknown : ["resource key is not declared in this system's resourceReads or resourceWrites", K];
 export type DeclaredResourceWrite<A extends SystemAccess, K> = [K] extends [A["resourceWrite"]] ? unknown : ["resource key is not declared in this system's resourceWrites", K];
 /** `commands.despawn` argument: blocked (with a readable error) only when
- * the access record PROVES no despawns were declared. */
+ * the access record proves no despawns were declared. */
 export type DespawnArg<A extends SystemAccess> = [A["destroy"]] extends [false] ? {
-    "this system declares no despawns — despawn is not permitted": never;
+    "this system declares no despawns, so despawn is not permitted": never;
 } : EntityID;
 export type DenseAccessDecl = readonly ComponentDef<any>[];
 export type SpawnsAccessDecl = readonly (readonly ComponentDef<any>[] | Template<any>)[];
@@ -165,7 +218,7 @@ type TransitionRemoveDefs<T> = T extends {
     readonly remove: readonly (infer D extends ComponentDef<any>)[];
 } ? D : never;
 /**
- * Compute the `SystemAccess` record for a set of declared access lists —
+ * Compute the `SystemAccess` record for a set of declared access lists,
  * the type-level `computeSets` (access_check.ts).
  */
 export type DeclaredAccess<R extends DenseAccessDecl, W extends DenseAccessDecl, Sp extends SpawnsAccessDecl = readonly never[], De extends DespawnsAccessDecl = readonly never[], Tr extends TransitionsAccessDecl = readonly never[], SR extends SparseAccessDecl = readonly never[], SW extends SparseAccessDecl = readonly never[], RR extends RelationsAccessDecl = readonly never[], RW extends RelationsAccessDecl = readonly never[], QR extends ResourcesAccessDecl = readonly never[], QW extends ResourcesAccessDecl = readonly never[]> = {
@@ -184,10 +237,10 @@ export type DeclaredAccess<R extends DenseAccessDecl, W extends DenseAccessDecl,
 /**
  * The config shape the typed `registerSystem` overload infers. Structurally a
  * `SystemConfig`, but every declaration list is its own type parameter (one
- * inference site each — inferring a single config-object type parameter breaks
+ * inference site each, inferring a single config-object type parameter breaks
  * contextual typing of `fn`), `queries` is constrained to `reads ∪ writes`
- * (the compile-time declared-access lint), and `fn` / `onAdded` receive the narrowed
- * context. `fn` and `onAdded` use METHOD syntax deliberately: methods relate
+ * (the compile-time declared-access lint), and `fn` and `onAdded` receive the narrowed
+ * context. `fn` and `onAdded` use method syntax deliberately: methods relate
  * bivariantly, which is what lets an explicitly-annotated permissive
  * `fn(ctx: SystemContext, dt)` (the escape hatch) keep compiling.
  * `exclusive: true` configs take the dedicated permissive overload instead.
@@ -211,15 +264,26 @@ export interface TypedSystemConfig<R extends DenseAccessDecl, W extends DenseAcc
     onAdded?(ctx: SystemContext<A>): void;
     onRemoved?(): void;
     dispose?(): void;
-    /** `boolean`, not `false`, so a config VALUE typed `SystemConfig` (whose
-     * `exclusive` is `boolean | undefined`) still matches this overload; a
+    /** `boolean`, not `false`, so a config value typed `SystemConfig` (whose
+     * `exclusive` is `boolean | undefined`) still matches this overload. A
      * literal `exclusive: true` config matches the dedicated permissive
      * overload first by declaration order. */
     exclusive?: boolean;
     backendHandle?: BackendSystemHandle;
+    /** The column list is held to `reads ∪ writes` at the type layer, the same
+     * mirror `queries` carries, and each field name to its component's schema. */
+    readonly parallel?: ParallelConfig<R[number] | W[number]>;
 }
 export interface SystemDescriptor extends Readonly<SystemConfig> {
     readonly id: SystemID;
+    /** @internal What one routed dispatch reads, resolved at registration.
+     * It hangs off the descriptor so the dispatch site resolves it with one
+     * property load instead of a keyed lookup. Absent on every system no route
+     * claims, and on every world that installed no route.
+     *
+     * Opaque. The plugin that built it is the only reader, so the core carries
+     * neither the plan's type nor the module that shapes it. */
+    readonly routePlan?: object;
     readonly spawns: readonly (readonly ComponentDef[])[];
     readonly despawns: readonly ComponentDef[];
     readonly transitions: readonly SystemTransition[];
@@ -228,23 +292,44 @@ export interface SystemDescriptor extends Readonly<SystemConfig> {
 }
 /** @internal Normalize an authored access config into the declaration shape
  * a `SystemDescriptor` carries: absent optional fields become shared frozen
- * empties; `Template` references in `spawns` / `despawns` expand to their
- * component lists. Pure — does not mutate `config`. */
+ * empties. A `Template` reference in `spawns` or in `despawns` expands to its
+ * component list. Pure, does not mutate `config`. */
 export declare function _normalizeAccess(config: SystemAccessConfig): SystemAccessDeclaration;
 /** @internal Declared-access lint: in `DEV`, validate that every
  * component a system lists in `queries` is covered by `reads ∪ writes`. A query
- * term reads each listed component's presence/columns, so querying one the
+ * term reads each listed component's presence and columns, so querying one the
  * system never declared read access to would throw at the first iteration
- * (`accessCheck`); this surfaces the drift between the two declarations at
- * registration instead. `exclusive` systems (full access, empty reads/writes)
- * are skipped, as are the bare-fn / 2-arg overloads (no `queries`). Pure —
+ * (`accessCheck`). This surfaces the drift between the two declarations at
+ * registration instead. An `exclusive` system (full access, empty reads and
+ * writes) is skipped, and so is a bare-function or two-argument overload,
+ * which carries no `queries`. Pure,
  * throws `QUERY_ACCESS_UNDECLARED` on a violation, naming the offending ids. */
 export declare function _assertQueriesDeclared(config: SystemConfig): void;
-/** @internal — empty access declaration shared by the bare-fn and 2-arg
+/** @internal, empty access declaration shared by the bare-fn and 2-arg
  * `registerSystem` overloads. Systems registered via those overloads
- * have no declared access and therefore fail any runtime check; use the
- * config form when the system performs any ECS access. NOT exported from
- * the package barrel — call sites should never spread this directly. */
+ * have no declared access and therefore fail any runtime check. Use the
+ * config form when the system performs any ECS access. Not exported from
+ * the package barrel, call sites should never spread this directly. */
 export declare const _INTERNAL_EMPTY_ACCESS: SystemAccessDeclaration;
+/** @internal The config a bare-function registration produces. The access
+ * surface is unannotated, so a component touch fails the runtime check. The
+ * config form is how a system declares its per-system access.
+ *
+ * Footgun guard: a bare `SystemFn` is `(ctx, dt)`, arity
+ * ≤ 2. A 3-param function here is almost certainly the `(q, ctx, dt)`
+ * query form with its `queryFn` second arg forgotten, which would
+ * otherwise silently bind `q := SystemContext`, `ctx := dt`, and
+ * `dt := undefined` (a NaN trap on the first arithmetic). Fail fast
+ * in `DEV` instead. Compiled out of production builds. */
+export declare function _createBareSystemConfig(fn: SystemFn): SystemConfig;
+/** @internal DEV-only: refuse a config that can never run anything. `fn` is
+ * optional only for a backend-executed system, so a config with neither `fn`
+ * nor `backendHandle` is a registration the schedule can do nothing with. */
+export declare function _assertSystemRunnable(config: SystemConfig): void;
+/** @internal Freeze one registration into the handle the schedule orders by.
+ * The world owns the id counter and hands the next value in, so the descriptor
+ * carries the same brand every other system id does. Cold path, one call per
+ * registration. */
+export declare function _createSystemDescriptor(config: SystemConfig, routePlan: object | undefined, nextId: number): SystemDescriptor;
 export {};
 //# sourceMappingURL=system.d.ts.map