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

package/src/execution/kernel-pool.ts

@@ -0,0 +1,236 @@
+import type {
+  KernelDispatchFailure,
+  KernelDispatchResult,
+  KernelDispatchSpan,
+  SharedKernelDispatch,
+  SharedKernelExecutor,
+  SharedSpanBinding,
+} from '@forgeax/engine-ecs/shared';
+import { bindSharedSpan, isSharedSpan, splitSharedSpan } from '@forgeax/engine-ecs/shared';
+
+export interface KernelPool extends SharedKernelExecutor {
+  readonly laneCount: number;
+  ready(): Promise<void>;
+  takeLastDispatch(): KernelDispatchResult | null;
+  dispose(): void;
+}
+
+interface KernelJobMessage {
+  readonly kind: 'kernel-job';
+  readonly moduleUrl: string;
+  readonly binding: SharedSpanBinding;
+  readonly control: Int32Array;
+  readonly status: Int32Array;
+  readonly jobIndex: number;
+}
+
+interface KernelInitMessage {
+  readonly kind: 'kernel-init';
+  readonly ready: Int32Array;
+}
+
+interface KernelPreloadMessage {
+  readonly kind: 'kernel-preload';
+  readonly moduleUrl: string;
+  readonly control: Int32Array;
+  readonly status: Int32Array;
+  readonly jobIndex: number;
+}
+
+interface KernelPreflight {
+  readonly control: Int32Array;
+  readonly status: Int32Array;
+}
+
+export interface KernelPoolOptions {
+  readonly lanes?: number;
+  readonly timeoutMs?: number;
+  readonly workerFactory?: () => Worker;
+}
+
+export function createKernelPool(options: KernelPoolOptions = {}): KernelPool {
+  const hardware = globalThis.navigator?.hardwareConcurrency ?? 2;
+  const laneCount = Math.max(1, Math.min(options.lanes ?? hardware - 1, 8));
+  const timeoutMs = options.timeoutMs ?? 5_000;
+  const workers = Array.from(
+    { length: laneCount },
+    () =>
+      options.workerFactory?.() ??
+      new Worker(new URL('./kernel-worker-runtime.mjs', import.meta.url), {
+        type: 'module',
+        name: 'forgeax-kernel',
+      }),
+  );
+  let latest: KernelDispatchResult | null = null;
+  let ready = false;
+  const preflights = new Map<string, KernelPreflight>();
+  const readyControl = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+  const initMessage: KernelInitMessage = { kind: 'kernel-init', ready: readyControl };
+  for (const worker of workers) worker.postMessage(initMessage);
+  const waitFor = (control: Int32Array, expected: number, label: string): Promise<void> =>
+    new Promise<void>((resolve, reject) => {
+      const started = performance.now();
+      const poll = (): void => {
+        if (Atomics.load(control, 0) === expected) {
+          resolve();
+          return;
+        }
+        if (performance.now() - started >= timeoutMs) {
+          for (const worker of workers) worker.terminate();
+          reject(new Error(`${label} did not complete within ${timeoutMs}ms.`));
+          return;
+        }
+        setTimeout(poll, 1);
+      };
+      poll();
+    });
+
+  const readyPromise = waitFor(
+    readyControl,
+    workers.length,
+    'SharedKernel worker initialization',
+  ).then(async () => {
+    for (const [moduleUrl, preflight] of preflights) {
+      await waitFor(
+        preflight.control,
+        workers.length,
+        `SharedKernel module preflight for ${moduleUrl}`,
+      );
+      if (preflight.status.some((status) => status !== 1)) {
+        throw new Error(`SharedKernel module preflight failed for ${moduleUrl}.`);
+      }
+    }
+    ready = true;
+  });
+
+  return {
+    laneCount,
+    ready: () => readyPromise,
+    warmup(kernel): void {
+      if (preflights.has(kernel.moduleUrl)) return;
+      const control = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+      const status = new Int32Array(
+        new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * workers.length),
+      );
+      preflights.set(kernel.moduleUrl, { control, status });
+      for (const [jobIndex, worker] of workers.entries()) {
+        const message: KernelPreloadMessage = {
+          kind: 'kernel-preload',
+          moduleUrl: kernel.moduleUrl,
+          control,
+          status,
+          jobIndex,
+        };
+        worker.postMessage(message);
+      }
+    },
+    takeLastDispatch: () => {
+      const dispatch = latest;
+      latest = null;
+      return dispatch;
+    },
+    execute(
+      kernel: SharedKernelDispatch,
+      spans: readonly KernelDispatchSpan[],
+    ): KernelDispatchResult | KernelDispatchFailure {
+      const preflight = preflights.get(kernel.moduleUrl);
+      if (preflight === undefined) {
+        this.warmup?.(kernel);
+        latest = { mode: 'forced-inline', dispatched: 0, completed: 0, waitMs: 0 };
+        return {
+          cause: new Error('SharedKernel module was not preflighted before frame dispatch.'),
+          dispatched: 0,
+          completed: 0,
+          partialWrite: false,
+        };
+      }
+      if (
+        Atomics.load(preflight.control, 0) !== workers.length ||
+        preflight.status.some((status) => status !== 1)
+      ) {
+        latest = { mode: 'forced-inline', dispatched: 0, completed: 0, waitMs: 0 };
+        return {
+          cause: new Error('SharedKernel module preflight is incomplete or failed.'),
+          dispatched: 0,
+          completed: 0,
+          partialWrite: false,
+        };
+      }
+      if (!ready && Atomics.load(readyControl, 0) === workers.length) ready = true;
+      if (!ready) {
+        latest = { mode: 'forced-inline', dispatched: 0, completed: 0, waitMs: 0 };
+        return {
+          cause: new Error('SharedKernel workers were not warmed before frame dispatch.'),
+          dispatched: 0,
+          completed: 0,
+          partialWrite: false,
+        };
+      }
+      const bindings = spans.flatMap(({ queryIndex, span }) =>
+        splitSharedSpan(bindSharedSpan(kernel, span, queryIndex), laneCount),
+      );
+      if (bindings.length === 0) {
+        latest = { mode: 'forced-inline', dispatched: 0, completed: 0, waitMs: 0 };
+        return latest;
+      }
+      if (!bindings.every(isSharedSpan)) {
+        latest = { mode: 'forced-inline', dispatched: 0, completed: 0, waitMs: 0 };
+        return {
+          cause: new Error('SharedKernel received a non-SAB QuerySpan.'),
+          dispatched: 0,
+          completed: 0,
+          partialWrite: false,
+        };
+      }
+      const control = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+      const status = new Int32Array(
+        new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * bindings.length),
+      );
+      const started = performance.now();
+      for (const [index, binding] of bindings.entries()) {
+        const message: KernelJobMessage = {
+          kind: 'kernel-job',
+          moduleUrl: kernel.moduleUrl,
+          binding,
+          control,
+          status,
+          jobIndex: index,
+        };
+        workers[index % workers.length]?.postMessage(message);
+      }
+      while (Atomics.load(control, 0) < bindings.length) {
+        const observed = Atomics.load(control, 0);
+        const wait = Atomics.wait(control, 0, observed, timeoutMs);
+        if (wait === 'timed-out') {
+          for (const worker of workers) worker.terminate();
+          return {
+            cause: new Error(`SharedKernel deadline exceeded after ${timeoutMs}ms.`),
+            dispatched: bindings.length,
+            completed: observed,
+            partialWrite: bindings.length > 0,
+          };
+        }
+      }
+      const completed = status.reduce((count, value) => count + (value === 1 ? 1 : 0), 0);
+      const failed = status.some((value) => value === -1);
+      if (failed) {
+        return {
+          cause: new Error('SharedKernel worker failed.'),
+          dispatched: bindings.length,
+          completed,
+          partialWrite: bindings.length > 0,
+        };
+      }
+      latest = {
+        mode: 'shared',
+        dispatched: bindings.length,
+        completed,
+        waitMs: performance.now() - started,
+      };
+      return latest;
+    },
+    dispose(): void {
+      for (const worker of workers) worker.terminate();
+    },
+  };
+}

package/src/execution/kernel-worker-runtime.ts

@@ -0,0 +1,103 @@
+import type { QuerySpan } from '@forgeax/engine-ecs';
+import type { SharedSpanBinding } from '@forgeax/engine-ecs/shared';
+
+interface KernelJobMessage {
+  readonly kind: 'kernel-job';
+  readonly moduleUrl: string;
+  readonly binding: SharedSpanBinding;
+  readonly control: Int32Array;
+  readonly status: Int32Array;
+  readonly jobIndex: number;
+}
+
+interface KernelInitMessage {
+  readonly kind: 'kernel-init';
+  readonly ready: Int32Array;
+}
+
+interface KernelPreloadMessage {
+  readonly kind: 'kernel-preload';
+  readonly moduleUrl: string;
+  readonly control: Int32Array;
+  readonly status: Int32Array;
+  readonly jobIndex: number;
+}
+
+interface LoadedKernel {
+  readonly run: (spans: readonly QuerySpan[]) => unknown;
+}
+
+const scope = globalThis as unknown as {
+  onmessage:
+    | ((event: MessageEvent<KernelJobMessage | KernelInitMessage | KernelPreloadMessage>) => void)
+    | null;
+};
+
+const loadedKernels = new Map<string, LoadedKernel>();
+
+async function loadKernel(moduleUrl: string): Promise<LoadedKernel> {
+  const module = await import(/* @vite-ignore */ moduleUrl);
+  const candidate = (module.default ?? module) as { run?: unknown };
+  if (typeof candidate.run !== 'function') {
+    throw new TypeError('SharedKernel module default export has no run function.');
+  }
+  return candidate as LoadedKernel;
+}
+
+function spanFromBinding(binding: SharedSpanBinding): QuerySpan {
+  return {
+    entities: binding.entities,
+    length: binding.length,
+    get(component) {
+      const fields = binding.read[component.name];
+      if (fields === undefined)
+        throw new Error(`Kernel read access is not declared for ${component.name}.`);
+      return fields as never;
+    },
+    mut(component) {
+      const fields = binding.write[component.name];
+      if (fields === undefined)
+        throw new Error(`Kernel write access is not declared for ${component.name}.`);
+      return fields as never;
+    },
+  };
+}
+
+scope.onmessage = (event): void => {
+  const job = event.data;
+  if (job.kind === 'kernel-init') {
+    Atomics.add(job.ready, 0, 1);
+    Atomics.notify(job.ready, 0);
+    return;
+  }
+  if (job.kind === 'kernel-preload') {
+    void loadKernel(job.moduleUrl)
+      .then((kernel) => {
+        loadedKernels.set(job.moduleUrl, kernel);
+        Atomics.store(job.status, job.jobIndex, 1);
+      })
+      .catch(() => {
+        Atomics.store(job.status, job.jobIndex, -1);
+      })
+      .finally(() => {
+        Atomics.add(job.control, 0, 1);
+        Atomics.notify(job.control, 0);
+      });
+    return;
+  }
+  if (job.kind !== 'kernel-job') return;
+  try {
+    const kernel = loadedKernels.get(job.moduleUrl);
+    if (kernel === undefined) {
+      throw new Error(`SharedKernel module was not preloaded: ${job.moduleUrl}`);
+    }
+    const returned = kernel.run([spanFromBinding(job.binding)]);
+    if (returned instanceof Promise) throw new TypeError('SharedKernel run must be synchronous.');
+    Atomics.store(job.status, job.jobIndex, 1);
+  } catch {
+    Atomics.store(job.status, job.jobIndex, -1);
+  } finally {
+    Atomics.add(job.control, 0, 1);
+    Atomics.notify(job.control, 0);
+  }
+};

package/src/execution/measurement.ts

@@ -0,0 +1,39 @@
+import type { ExecutionMeasurement } from './types';
+
+function percentile(sorted: readonly number[], fraction: number): number {
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * fraction) - 1));
+  return sorted[index] ?? 0;
+}
+
+export interface MeasurementSeries {
+  add(value: number): ExecutionMeasurement;
+  clear(): void;
+}
+
+export function createMeasurementSeries(capacity = 240): MeasurementSeries {
+  const values: number[] = [];
+  let samples = 0;
+  return {
+    add(value): ExecutionMeasurement {
+      samples += 1;
+      values.push(value);
+      if (values.length > capacity) values.shift();
+      const sorted = [...values].sort((a, b) => a - b);
+      let jitter = 0;
+      for (let index = 1; index < values.length; index += 1) {
+        jitter += Math.abs((values[index] ?? 0) - (values[index - 1] ?? 0));
+      }
+      return {
+        samples,
+        p50: percentile(sorted, 0.5),
+        p95: percentile(sorted, 0.95),
+        p99: percentile(sorted, 0.99),
+        jitter: values.length < 2 ? 0 : jitter / (values.length - 1),
+      };
+    },
+    clear(): void {
+      values.length = 0;
+      samples = 0;
+    },
+  };
+}

package/src/execution/protocol.ts

@@ -0,0 +1,134 @@
+import type { AudioIntent } from '@forgeax/engine-audio';
+import type { InputBackendSample } from '@forgeax/engine-input';
+import type { CanvasDrawingBufferSize } from '../types';
+import type { ExecutionAssetCatalog } from './types';
+
+export interface ExecutionFrameMessage {
+  readonly kind: 'frame';
+  readonly worldIdentity: string;
+  readonly frameId: number;
+  readonly deltaSeconds: number;
+  readonly inputSample: InputBackendSample;
+  readonly canvasWidth: number;
+  readonly canvasHeight: number;
+}
+
+export interface ExecutionFrameCompletion {
+  readonly kind: 'frame-complete';
+  readonly worldIdentity: string;
+  readonly frameId: number;
+  readonly engineUpdateMs: number;
+  readonly kernelWaitMs: number;
+  readonly audioIntents?: readonly AudioIntent[];
+  readonly kernelDispatch?: {
+    readonly eligible: boolean;
+    readonly usedShared: boolean;
+    readonly reason: import('./types').KernelDispatchReason;
+    readonly dispatched: number;
+    readonly completed: number;
+  };
+}
+
+export type FrameCompletionDisposition = 'accepted' | 'duplicate' | 'stale-world' | 'late';
+
+export class FrameCreditLedger {
+  private nextFrameId = 1;
+  private inFlight: number | null = null;
+  private completed = 0;
+
+  constructor(readonly worldIdentity: string) {}
+
+  issue(
+    deltaSeconds: number,
+    sampleInput: () => InputBackendSample,
+    canvasSize: CanvasDrawingBufferSize = { width: 0, height: 0 },
+  ): ExecutionFrameMessage | undefined {
+    if (this.inFlight !== null) return undefined;
+    const frameId = this.nextFrameId;
+    this.nextFrameId += 1;
+    this.inFlight = frameId;
+    return {
+      kind: 'frame',
+      worldIdentity: this.worldIdentity,
+      frameId,
+      deltaSeconds,
+      inputSample: sampleInput(),
+      canvasWidth: canvasSize.width,
+      canvasHeight: canvasSize.height,
+    };
+  }
+
+  complete(message: ExecutionFrameCompletion): FrameCompletionDisposition {
+    if (message.worldIdentity !== this.worldIdentity) return 'stale-world';
+    if (message.frameId <= this.completed) return 'duplicate';
+    if (message.frameId !== this.inFlight) return 'late';
+    this.completed = message.frameId;
+    this.inFlight = null;
+    return 'accepted';
+  }
+
+  get hasCreditInFlight(): boolean {
+    return this.inFlight !== null;
+  }
+}
+
+export interface ExecutionInitMessage {
+  readonly kind: 'init';
+  readonly canvas: OffscreenCanvas;
+  readonly bootstrapUrl: string;
+  readonly bootstrapData?: import('./types').ExecutionBootstrapValue;
+  readonly bootstrapPort?: MessagePort;
+  /** Realm-serializable asset catalog configuration. */
+  readonly assetCatalog?: ExecutionAssetCatalog;
+  readonly shaderManifestUrl?: string;
+  readonly time?: import('@forgeax/engine-ecs').TimePolicy;
+  readonly tier: import('./types').ExecutionTier;
+}
+
+export interface ExecutionHostControlMessage {
+  readonly kind: 'host-control';
+  readonly command: 'set-pointer-lock-allowed';
+  readonly allowed: boolean;
+}
+
+export interface ExecutionReadyMessage {
+  readonly kind: 'ready';
+  readonly worldIdentity: string;
+  readonly realm: 'worker';
+  readonly workerWebGpu: boolean;
+}
+
+export interface ExecutionFaultMessage {
+  readonly kind: 'fault';
+  readonly worldIdentity: string | null;
+  readonly source: 'bootstrap' | 'handshake' | 'runtime' | 'kernel' | 'world' | 'rebuild';
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: unknown;
+  readonly partialWrite: boolean;
+  readonly retryable: boolean;
+}
+
+export interface ExecutionRebuildMessage {
+  readonly kind: 'rebuild';
+  readonly worldIdentity: string;
+}
+
+export interface ExecutionRebuiltMessage {
+  readonly kind: 'rebuilt';
+  readonly previousWorldIdentity: string;
+  readonly worldIdentity: string;
+}
+
+export type HostToEngineMessage =
+  | ExecutionInitMessage
+  | ExecutionFrameMessage
+  | ExecutionRebuildMessage
+  | { readonly kind: 'dispose' };
+export type EngineToHostMessage =
+  | ExecutionReadyMessage
+  | ExecutionFrameCompletion
+  | ExecutionFaultMessage
+  | ExecutionRebuiltMessage
+  | ExecutionHostControlMessage;

package/src/execution/report.ts

@@ -0,0 +1,66 @@
+import type { AudioState } from '@forgeax/engine-audio';
+import { EXECUTION_REPORT_SCHEMA_VERSION } from './schema';
+import type {
+  ExecutionCapabilities,
+  ExecutionReport,
+  ExecutionRequestedTier,
+  ExecutionSelection,
+} from './types';
+
+export function executionAudioReport(state?: AudioState): ExecutionReport['audio'] {
+  const error = state?.lastError ?? null;
+  return {
+    owner: 'host',
+    contextState: state?.contextState ?? 'suspended',
+    activeSourceCount: state?.activeSourceCount ?? 0,
+    lastError:
+      error === null
+        ? null
+        : {
+            code: error.code,
+            expected: error.expected,
+            hint: error.hint,
+            detail: error.detail,
+          },
+  };
+}
+
+export function createExecutionReport(
+  requestedTier: ExecutionRequestedTier,
+  capabilities: ExecutionCapabilities,
+  selection?: ExecutionSelection,
+): ExecutionReport {
+  return {
+    schemaVersion: EXECUTION_REPORT_SCHEMA_VERSION,
+    requestedTier,
+    actualTier: selection?.actualTier ?? null,
+    selectionReason: selection?.selectionReason ?? null,
+    sharedEvidencePassed: selection?.sharedEvidencePassed ?? false,
+    capabilities,
+    engine: {
+      realm: selection?.actualTier === 'main-serial' ? 'host' : 'worker',
+      health: 'idle',
+    },
+    world: {
+      identity: null,
+      health: 'healthy',
+      partialWrite: false,
+      retryable: true,
+    },
+    kernelDispatch: {
+      eligible: false,
+      usedShared: false,
+      reason: 'no-eligible-kernel',
+      dispatched: 0,
+      completed: 0,
+    },
+    performance: {
+      hostFrameMs: null,
+      engineUpdateMs: null,
+      kernelWaitMs: null,
+      hostAudioMs: null,
+    },
+    audio: executionAudioReport(),
+    fault: null,
+  };
+}