@forgeax/engine-ecs 0.0.0-dev.8d955ade1c79

package/src/execution/shared-kernel.ts

@@ -0,0 +1,392 @@
+import type { Component, SchemaFieldType } from '../component';
+import { componentId, componentSchema } from '../component';
+import type { QueryDescriptor, QuerySpan } from '../query/query';
+import type { SystemHandle } from '../schedule';
+import { worldInternal } from '../world-internal';
+
+export const SHARED_KERNEL_EXECUTOR_RESOURCE_KEY = 'SharedKernelExecutor';
+
+export interface KernelDispatchResult {
+  readonly mode: 'forced-inline' | 'shared';
+  readonly dispatched: number;
+  readonly completed: number;
+  readonly waitMs: number;
+}
+
+export interface KernelDispatchFailure {
+  readonly cause: unknown;
+  readonly dispatched: number;
+  readonly completed: number;
+  readonly partialWrite: boolean;
+}
+
+export interface KernelDispatchSpan {
+  readonly queryIndex: number;
+  readonly span: QuerySpan;
+}
+
+export interface SharedKernelExecutor {
+  warmup?(kernel: SharedKernelDispatch): void;
+  execute(
+    kernel: SharedKernelDispatch,
+    spans: readonly KernelDispatchSpan[],
+  ): KernelDispatchResult | KernelDispatchFailure;
+}
+
+export function isKernelDispatchFailure(
+  value: KernelDispatchResult | KernelDispatchFailure,
+): value is KernelDispatchFailure {
+  return 'cause' in value;
+}
+
+export const SHARED_KERNEL_ELIGIBILITY_REASONS = [
+  'callback-not-module-function',
+  'dom-access',
+  'missing-access-declaration',
+  'descriptor-conflict',
+  'object-field',
+  'span-unavailable',
+] as const;
+export type SharedKernelEligibilityReason = (typeof SHARED_KERNEL_ELIGIBILITY_REASONS)[number];
+
+export type WorldExecutionHealth = 'healthy' | 'poisoned';
+
+export interface WorldExecutionFault {
+  readonly code: 'shared-kernel-failed';
+  readonly kernelName: string;
+  readonly cause: unknown;
+  readonly partialWrite: boolean;
+  readonly retryable: false;
+}
+
+export interface WorldExecutionState {
+  readonly identity: string;
+  readonly health: WorldExecutionHealth;
+  readonly fault: WorldExecutionFault | null;
+}
+
+let nextWorldIdentity = 1;
+
+export function createWorldIdentity(): string {
+  const identity = `world-${nextWorldIdentity}`;
+  nextWorldIdentity += 1;
+  return identity;
+}
+
+export function healthyWorldExecutionState(identity: string): WorldExecutionState {
+  return Object.freeze({ identity, health: 'healthy', fault: null });
+}
+
+export function poisonedWorldExecutionState(
+  identity: string,
+  fault: WorldExecutionFault,
+): WorldExecutionState {
+  return Object.freeze({ identity, health: 'poisoned', fault: Object.freeze(fault) });
+}
+
+export interface SharedKernelDefinition<Qs extends readonly QueryDescriptor[]> {
+  readonly name: string;
+  readonly queries: Qs;
+  readonly run: (spans: readonly QuerySpan[]) => void;
+  readonly minimumRows?: number;
+  readonly before?: readonly (string | import('../schedule-token').ScheduleToken)[];
+  readonly after?: readonly (string | import('../schedule-token').ScheduleToken)[];
+}
+
+export interface SharedKernelDispatch<
+  Qs extends readonly QueryDescriptor[] = readonly QueryDescriptor[],
+> {
+  readonly kind: 'shared-kernel';
+  readonly moduleUrl: string;
+  readonly name: string;
+  readonly minimumRows: number;
+  readonly queries: Qs;
+  readonly run: (spans: readonly QuerySpan[]) => void;
+}
+
+export interface SharedKernelHandle<
+  Qs extends readonly QueryDescriptor[] = readonly QueryDescriptor[],
+> extends SystemHandle<Qs>,
+    SharedKernelDispatch<Qs> {}
+
+export class SharedKernelEligibilityError extends Error {
+  readonly code = 'shared-kernel-ineligible' as const;
+  readonly expected =
+    'a module-loadable named kernel with one or more numeric QuerySpan read/write declarations';
+  readonly hint =
+    'export a named function from the kernel module and use only dense numeric QuerySpan columns';
+  readonly detail: { readonly kernelName: string; readonly reason: SharedKernelEligibilityReason };
+
+  constructor(kernelName: string, reason: SharedKernelEligibilityReason) {
+    super(`Shared kernel "${kernelName}" is ineligible: ${reason}.`);
+    this.name = 'SharedKernelEligibilityError';
+    this.detail = { kernelName, reason };
+  }
+}
+
+export class SharedKernelFailureError extends Error {
+  readonly code = 'shared-kernel-failed' as const;
+  readonly expected = 'every dispatched shard completes without a possible partial write';
+  readonly hint =
+    'do not retry this World; inspect detail.cause and rebuild with a new World identity';
+  readonly detail: {
+    readonly kernelName: string;
+    readonly worldIdentity: string;
+    readonly cause: unknown;
+    readonly partialWrite: boolean;
+    readonly retryable: false;
+  };
+
+  constructor(kernelName: string, worldIdentity: string, cause: unknown, partialWrite: boolean) {
+    super(`Shared kernel "${kernelName}" failed; World ${worldIdentity} is poisoned.`);
+    this.name = 'SharedKernelFailureError';
+    this.detail = { kernelName, worldIdentity, cause, partialWrite, retryable: false };
+  }
+}
+
+export class WorldPoisonedError extends Error {
+  readonly code = 'world-poisoned' as const;
+  readonly expected = 'World health is healthy before update';
+  readonly hint = 'stop scheduling this World and explicitly bootstrap a new World identity';
+  readonly detail: { readonly worldIdentity: string; readonly fault: unknown };
+
+  constructor(worldIdentity: string, fault: unknown) {
+    super(`World ${worldIdentity} is poisoned and cannot update.`);
+    this.name = 'WorldPoisonedError';
+    this.detail = { worldIdentity, fault };
+  }
+}
+
+const NUMERIC_FIELDS = new Set<SchemaFieldType>([
+  'f32',
+  'f64',
+  'i32',
+  'u32',
+  'i16',
+  'u16',
+  'i8',
+  'u8',
+  'bool',
+  'enum',
+  'ref',
+  'entity',
+]);
+
+function components(descriptor: QueryDescriptor): readonly Component[] {
+  return [
+    ...(descriptor.read ?? []),
+    ...(descriptor.write ?? []),
+    ...(descriptor.optional ?? []),
+    ...(descriptor.with ?? []),
+    ...(descriptor.without ?? []),
+    ...(descriptor.changed ?? []),
+    ...(descriptor.added ?? []),
+  ];
+}
+
+function descriptorReason(descriptor: QueryDescriptor): SharedKernelEligibilityReason | undefined {
+  if ((descriptor.read?.length ?? 0) + (descriptor.write?.length ?? 0) === 0) {
+    return 'missing-access-declaration';
+  }
+  if (
+    (descriptor.optional?.length ?? 0) > 0 ||
+    (descriptor.changed?.length ?? 0) > 0 ||
+    (descriptor.added?.length ?? 0) > 0
+  ) {
+    return 'span-unavailable';
+  }
+  const seen = new Set<number>();
+  for (const component of components(descriptor)) {
+    if (seen.has(componentId(component))) return 'descriptor-conflict';
+    seen.add(componentId(component));
+    if (component.storage === 'sparse') return 'span-unavailable';
+    if (Object.values(componentSchema(component)).some((field) => !NUMERIC_FIELDS.has(field))) {
+      return 'object-field';
+    }
+  }
+  return undefined;
+}
+
+export function sharedKernelEligibility(
+  moduleUrl: string,
+  definition: SharedKernelDefinition<readonly QueryDescriptor[]>,
+): SharedKernelEligibilityReason | undefined {
+  try {
+    new URL(moduleUrl);
+  } catch {
+    return 'callback-not-module-function';
+  }
+  const source = Function.prototype.toString.call(definition.run);
+  if (definition.run.name.length === 0 || source.includes('=>')) {
+    return 'callback-not-module-function';
+  }
+  if (/\b(?:document|window|globalThis|HTMLElement|GPUDevice|AudioContext)\b/u.test(source)) {
+    return 'dom-access';
+  }
+  for (const query of definition.queries) {
+    const reason = descriptorReason(query);
+    if (reason !== undefined) return reason;
+  }
+  return undefined;
+}
+
+export function defineSharedKernel<const Qs extends readonly QueryDescriptor[]>(
+  moduleUrl: string,
+  definition: SharedKernelDefinition<Qs>,
+): SharedKernelHandle<Qs> {
+  const reason = sharedKernelEligibility(moduleUrl, definition);
+  if (reason !== undefined) throw new SharedKernelEligibilityError(definition.name, reason);
+
+  const handle: SharedKernelHandle<Qs> = Object.freeze({
+    kind: 'shared-kernel' as const,
+    moduleUrl,
+    name: definition.name,
+    queries: definition.queries,
+    minimumRows: definition.minimumRows ?? 16_384,
+    run: definition.run,
+    ...(definition.before !== undefined ? { before: definition.before } : {}),
+    ...(definition.after !== undefined ? { after: definition.after } : {}),
+    fn: (world: import('../world').World, queries: Parameters<SystemHandle<Qs>['fn']>[1]) => {
+      const dispatchSpans: KernelDispatchSpan[] = [];
+      for (const [queryIndex, query] of queries.entries()) {
+        const result = query.spans();
+        if (!result.ok) throw new SharedKernelEligibilityError(definition.name, 'span-unavailable');
+        for (const span of result.value) dispatchSpans.push({ queryIndex, span });
+      }
+      const spans = dispatchSpans.map((entry) => entry.span);
+      const totalRows = spans.reduce((sum, span) => sum + span.length, 0);
+      try {
+        if (
+          totalRows < (definition.minimumRows ?? 16_384) ||
+          !world.hasResource(SHARED_KERNEL_EXECUTOR_RESOURCE_KEY)
+        ) {
+          definition.run(spans);
+          return;
+        }
+        const executor = world.getResource<SharedKernelExecutor>(
+          SHARED_KERNEL_EXECUTOR_RESOURCE_KEY,
+        );
+        const result = executor.execute(handle, dispatchSpans);
+        if (isKernelDispatchFailure(result)) {
+          if (!result.partialWrite) {
+            definition.run(spans);
+            return;
+          }
+          world[worldInternal].poisonExecution({
+            code: 'shared-kernel-failed',
+            kernelName: definition.name,
+            cause: result.cause,
+            partialWrite: result.partialWrite,
+            retryable: false,
+          });
+          throw new SharedKernelFailureError(
+            definition.name,
+            world.execution.identity,
+            result.cause,
+            result.partialWrite,
+          );
+        }
+      } catch (cause) {
+        if (world.execution.health !== 'poisoned') {
+          world[worldInternal].poisonExecution({
+            code: 'shared-kernel-failed',
+            kernelName: definition.name,
+            cause,
+            partialWrite: true,
+            retryable: false,
+          });
+        }
+        if (cause instanceof SharedKernelFailureError) throw cause;
+        throw new SharedKernelFailureError(definition.name, world.execution.identity, cause, true);
+      }
+    },
+  });
+  return handle;
+}
+
+export type SharedFieldView =
+  | Float32Array
+  | Float64Array
+  | Int32Array
+  | Uint32Array
+  | Int16Array
+  | Uint16Array
+  | Int8Array
+  | Uint8Array;
+
+export interface SharedSpanBinding {
+  readonly entities: Readonly<Uint32Array>;
+  readonly length: number;
+  readonly read: Readonly<Record<string, Readonly<Record<string, SharedFieldView>>>>;
+  readonly write: Readonly<Record<string, Readonly<Record<string, SharedFieldView>>>>;
+}
+
+function sliceFields(
+  fields: Readonly<Record<string, SharedFieldView>>,
+  start: number,
+  end: number,
+): Readonly<Record<string, SharedFieldView>> {
+  return Object.fromEntries(
+    Object.entries(fields).map(([name, view]) => [name, view.subarray(start, end)]),
+  );
+}
+
+export function bindSharedSpan(
+  kernel: SharedKernelDispatch,
+  span: QuerySpan,
+  queryIndex: number,
+): SharedSpanBinding {
+  const descriptor = kernel.queries[queryIndex];
+  if (descriptor === undefined) throw new Error(`Missing query descriptor ${queryIndex}.`);
+  const read = Object.fromEntries(
+    (descriptor.read ?? []).map((component) => [
+      component.name,
+      span.get(component) as unknown as Record<string, SharedFieldView>,
+    ]),
+  );
+  const write = Object.fromEntries(
+    (descriptor.write ?? []).map((component) => [
+      component.name,
+      span.mut(component) as unknown as Record<string, SharedFieldView>,
+    ]),
+  );
+  return { entities: span.entities, length: span.length, read, write };
+}
+
+export function splitSharedSpan(
+  binding: SharedSpanBinding,
+  shardCount: number,
+): readonly SharedSpanBinding[] {
+  if (binding.length === 0 || shardCount <= 0) return [];
+  const count = Math.min(binding.length, shardCount);
+  const shards: SharedSpanBinding[] = [];
+  for (let index = 0; index < count; index += 1) {
+    const start = Math.floor((binding.length * index) / count);
+    const end = Math.floor((binding.length * (index + 1)) / count);
+    shards.push({
+      entities: binding.entities.subarray(start, end),
+      length: end - start,
+      read: Object.fromEntries(
+        Object.entries(binding.read).map(([component, fields]) => [
+          component,
+          sliceFields(fields, start, end),
+        ]),
+      ),
+      write: Object.fromEntries(
+        Object.entries(binding.write).map(([component, fields]) => [
+          component,
+          sliceFields(fields, start, end),
+        ]),
+      ),
+    });
+  }
+  return shards;
+}
+
+export function isSharedSpan(binding: SharedSpanBinding): boolean {
+  if (typeof SharedArrayBuffer === 'undefined') return false;
+  if (!(binding.entities.buffer instanceof SharedArrayBuffer)) return false;
+  return [...Object.values(binding.read), ...Object.values(binding.write)].every((fields) =>
+    Object.values(fields).every((view) => view.buffer instanceof SharedArrayBuffer),
+  );
+}

package/src/externalization/index.ts

@@ -0,0 +1,170 @@
+// @forgeax/engine-ecs — externalization module public barrel.
+//
+// Pure ECS kernel: projection, portable validation, and entity remap.
+// No network, peer, wire, profile, or codec policy.
+
+import type { Component, ComponentSchema } from '../component';
+import { componentSchema } from '../component';
+import { fillComponentDefaults } from '../component-default-fallback';
+import { componentDefinition } from '../component-schema';
+
+export type EntityFieldKind =
+  | { readonly kind: 'entity'; readonly isArray: false }
+  | { readonly kind: 'entity'; readonly isArray: true };
+
+export interface EntityRemapOptions {
+  readonly missing?: 'identity' | 'error';
+}
+
+export function classifyEntityField(token: Component, fieldName: string): EntityFieldKind | null {
+  const field = componentDefinition(token).fields[fieldName];
+  if (field === undefined) return null;
+  if (field.arrayMeta !== undefined) {
+    return field.arrayMeta.elementType === 'entity' ? { kind: 'entity', isArray: true } : null;
+  }
+  return componentSchema(token)[fieldName] === 'entity' ? { kind: 'entity', isArray: false } : null;
+}
+
+export function remapEntityFieldValue(
+  value: unknown,
+  kind: EntityFieldKind | null,
+  remapFn: (entity: number) => number,
+): unknown {
+  if (kind === null) return value;
+  if (kind.isArray) return Array.isArray(value) ? value.map((entity) => remapFn(entity)) : value;
+  return typeof value === 'number' ? remapFn(value) : value;
+}
+
+export function createEntityRemap(
+  mapping: Uint32Array | readonly number[],
+  options: EntityRemapOptions = {},
+): (entity: number) => number {
+  return (entity) => {
+    const mapped = entity >= 0 && entity < mapping.length ? mapping[entity] : undefined;
+    if (mapped !== undefined) return mapped;
+    if (options.missing === 'error') {
+      throw new Error(`Entity mapping is missing source entity ${entity}.`);
+    }
+    return entity;
+  };
+}
+
+function deepCopyValue(value: unknown): unknown {
+  if (Array.isArray(value)) return [...value];
+  if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+    const view = value as unknown as ArrayLike<number>;
+    const ViewCtor = value.constructor as unknown as new (v: ArrayLike<number>) => unknown;
+    return new ViewCtor(view);
+  }
+  return value;
+}
+
+function projectComponentDataInMode<S extends ComponentSchema>(
+  token: Component<string, S>,
+  raw: Partial<Record<string, unknown>> | undefined,
+  entityRemap?: (entity: number) => number,
+): Record<string, unknown> {
+  const definition = componentDefinition(token);
+  if (definition.policy.transient) return {};
+  const fields = definition.fields;
+  const rawObj = raw as Record<string, unknown> | undefined;
+  const filtered: Record<string, unknown> = {};
+  for (const fieldName of Object.keys(componentSchema(token))) {
+    const reflection = fields?.[fieldName];
+    if (reflection?.transient === true || rawObj === undefined || !(fieldName in rawObj)) continue;
+    const value = rawObj[fieldName];
+    if (value === undefined) continue;
+    const kind = classifyEntityField(token, fieldName);
+    if (kind?.isArray && (Array.isArray(value) || ArrayBuffer.isView(value))) {
+      filtered[fieldName] = Array.from(value as ArrayLike<number>, (entity) =>
+        entityRemap === undefined ? entity : entityRemap(entity),
+      );
+    } else if (kind !== null && typeof value === 'number') {
+      filtered[fieldName] = entityRemap === undefined ? value : entityRemap(value);
+    } else {
+      filtered[fieldName] = deepCopyValue(value);
+    }
+  }
+  const result = fillComponentDefaults(token, filtered as Partial<Record<string, unknown>>);
+  for (const fieldName of Object.keys(componentSchema(token))) {
+    if (fields?.[fieldName]?.transient === true) delete result[fieldName];
+  }
+  return result;
+}
+
+export function projectComponentData<S extends ComponentSchema>(
+  token: Component<string, S>,
+  raw: Partial<Record<string, unknown>> | undefined,
+  entityRemap?: (entity: number) => number,
+): Record<string, unknown> {
+  return projectComponentDataInMode(token, raw, entityRemap);
+}
+
+export function isComponentPortable(token: Component): boolean {
+  const definition = componentDefinition(token);
+  if (definition.policy.transient) return false;
+  const fields = definition.fields;
+  if (fields === undefined) return true;
+  return Object.keys(componentSchema(token)).some((name) => fields[name]?.transient !== true);
+}
+
+export function isComponentFullyTransient(token: Component): boolean {
+  return !isComponentPortable(token);
+}
+
+export function isFieldPortable(fieldType: string): boolean {
+  if (fieldType === 'ref' || fieldType.startsWith('unique<') || fieldType.startsWith('shared<')) {
+    return false;
+  }
+  if (fieldType.startsWith('array<') && fieldType.endsWith('>')) {
+    const body = fieldType
+      .slice(6, -1)
+      .replace(/,\s*\d+$/u, '')
+      .trim();
+    return body.length > 0 && isFieldPortable(body);
+  }
+  return true;
+}
+
+export interface ProfileComponentError {
+  readonly component: string;
+  readonly code: 'component-fully-transient' | 'field-not-portable';
+  readonly field?: string;
+  readonly fieldType?: string;
+  readonly expected: string;
+  readonly hint: string;
+}
+
+export function validateProfileComponents(components: readonly Component[]): {
+  readonly valid: boolean;
+  readonly errors: readonly ProfileComponentError[];
+} {
+  const errors: ProfileComponentError[] = [];
+  for (const token of components) {
+    if (isComponentFullyTransient(token)) {
+      errors.push({
+        component: token.name,
+        code: 'component-fully-transient',
+        expected: `Component '${token.name}' must have at least one non-transient, portable field`,
+        hint: 'Remove the component-level transient flag or declare a non-transient field',
+      });
+      continue;
+    }
+    const fields = componentDefinition(token).fields;
+    for (const fieldName of Object.keys(componentSchema(token))) {
+      const fieldType = componentSchema(token)[fieldName];
+      if (fieldType === undefined || fields?.[fieldName]?.transient === true) continue;
+      if (!isFieldPortable(fieldType)) {
+        errors.push({
+          component: token.name,
+          code: 'field-not-portable',
+          field: fieldName,
+          fieldType,
+          expected: `Field '${fieldName}' of component '${token.name}' must be portable`,
+          hint: `Field type '${fieldType}' is a process-local reference`,
+        });
+      }
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}