@series-inc/rundot-kinetix 0.0.0-bootstrap.0

package/src/kinetix-world-kernel.mjs

@@ -0,0 +1,580 @@
+import { sha256Hex } from './shared/sha256.mjs';
+
+const phases = Object.freeze([
+  'initialization',
+  'fixed-simulation',
+  'post-simulation',
+  'presentation-projection',
+  'presentation',
+]);
+
+function fail(code) {
+  throw new Error(code);
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+  }
+  return value;
+}
+
+function stableBytes(value) {
+  return new TextEncoder().encode(JSON.stringify(canonicalize(value)));
+}
+
+function digest(value) {
+  return sha256Hex(stableBytes(value));
+}
+
+function handleFor(worldId, index, generation) {
+  return { worldId, index, generation };
+}
+
+function compareSortKey(left, right) {
+  if (typeof left === 'number' && typeof right === 'number') {
+    return left - right;
+  }
+  return String(left).localeCompare(String(right));
+}
+
+function hydrateComponentSources(products) {
+  const direct = new Map();
+  const prefabs = new Map();
+  for (const payloadName of ['simulation', 'presentation', 'binding']) {
+    for (const record of products[payloadName].records) {
+      if (record.kind !== 'component') {
+        continue;
+      }
+      if (record.source.kind === 'entity') {
+        if (!direct.has(record.source.id)) {
+          direct.set(record.source.id, []);
+        }
+        direct.get(record.source.id).push(structuredClone(record.component));
+      } else if (record.source.kind === 'prefab-local-entity') {
+        const key = `${record.source.prefabId}:${record.source.id}`;
+        if (!prefabs.has(key)) {
+          prefabs.set(key, []);
+        }
+        prefabs.get(key).push(structuredClone(record.component));
+      }
+    }
+  }
+  return { direct, prefabs };
+}
+
+function createInitialState(worldId, products, componentSources) {
+  const slots = products.manifest.directEntities.map((entity) => ({
+    generation: 1,
+    active: true,
+    enabled: entity.enabled,
+    sourceId: entity.sourceId,
+    profile: entity.profile,
+    archetypeId: entity.archetypeId,
+    components: structuredClone(componentSources.direct.get(entity.sourceId) ?? []),
+    closureId: null,
+    localEntityId: null,
+    identity: { kind: 'direct', sourceId: entity.sourceId },
+  }));
+  return {
+    worldId,
+    tick: 0,
+    lastInputFrame: null,
+    slots,
+    freeIndices: [],
+    closures: new Map(),
+    nextSpawnId: 1,
+  };
+}
+
+function activeCount(state) {
+  return state.slots.reduce((count, slot) => count + (slot?.active ? 1 : 0), 0);
+}
+
+function validateHandle(state, handle) {
+  if (!isPlainObject(handle) || !Number.isSafeInteger(handle.index) || !Number.isSafeInteger(handle.generation)) {
+    fail('KINETIX_INVALID_HANDLE');
+  }
+  if (handle.worldId !== state.worldId) {
+    fail('KINETIX_WRONG_WORLD');
+  }
+  const slot = state.slots[handle.index];
+  if (!slot) {
+    fail('KINETIX_INVALID_HANDLE');
+  }
+  if (!slot.active || slot.generation !== handle.generation) {
+    fail('KINETIX_STALE_HANDLE');
+  }
+  return slot;
+}
+
+function allocateIndex(state) {
+  if (state.freeIndices.length > 0) {
+    return state.freeIndices.shift();
+  }
+  const index = state.slots.length;
+  state.slots.push({ generation: 1, active: false });
+  return index;
+}
+
+function authoritativeSnapshot(state) {
+  return {
+    worldId: state.worldId,
+    tick: state.tick,
+    lastInputFrame: structuredClone(state.lastInputFrame),
+    nextSpawnId: state.nextSpawnId,
+    freeIndices: [...state.freeIndices],
+    slots: state.slots.map((slot) => structuredClone(slot)),
+    closures: [...state.closures.entries()].map(([id, closure]) => [id, structuredClone(closure)]),
+  };
+}
+
+function authoritativeView(state) {
+  const snapshot = authoritativeSnapshot(state);
+  snapshot.slots = snapshot.slots.map((slot) => ({
+    ...slot,
+    components: Array.isArray(slot.components)
+      ? slot.components.filter((component) => component.domain === 'simulation')
+      : slot.components,
+  }));
+  return snapshot;
+}
+
+function stateFromSnapshot(snapshot, componentSources) {
+  const closures = new Map(snapshot.closures.map(([id, closure]) => [id, structuredClone(closure)]));
+  const slots = snapshot.slots.map((slot) => {
+    const restored = structuredClone(slot);
+    if (!restored?.active) return restored;
+    const closure = restored.closureId === null ? null : closures.get(restored.closureId);
+    const authored = restored.sourceId !== null
+      ? componentSources.direct.get(restored.sourceId) ?? []
+      : componentSources.prefabs.get(`${closure?.prefabId}:${restored.localEntityId}`) ?? [];
+    restored.components.push(...authored.filter((component) => component.domain !== 'simulation').map((component) => structuredClone(component)));
+    return restored;
+  });
+  return {
+    worldId: snapshot.worldId,
+    tick: snapshot.tick,
+    lastInputFrame: structuredClone(snapshot.lastInputFrame),
+    nextSpawnId: snapshot.nextSpawnId,
+    freeIndices: [...snapshot.freeIndices],
+    slots,
+    closures,
+  };
+}
+
+export function createKinetixWorld(options) {
+  if (!isPlainObject(options) || typeof options.worldId !== 'string' || !isPlainObject(options.products)
+    || !(options.installedProfiles instanceof Map)) {
+    fail('KINETIX_WORLD_INVALID');
+  }
+  for (const key of ['maxCommandsPerTick', 'maxLiveRuntimeEntities', 'budgets', 'envelope']) {
+    if (Object.hasOwn(options, key)) {
+      fail('KINETIX_BUDGET_OVERRIDE');
+    }
+  }
+  const { worldId, products, installedProfiles } = options;
+  const initialization = options.initialization === undefined ? {} : structuredClone(options.initialization);
+  if (!isPlainObject(initialization)) fail('KINETIX_INITIALIZATION_INVALID');
+  const manifest = products.manifest;
+  if (!isPlainObject(manifest) || !Array.isArray(manifest.directEntities) || !Array.isArray(manifest.prefabs)) {
+    fail('KINETIX_PRODUCTS_INVALID');
+  }
+  if (!Array.isArray(manifest.systems) || manifest.systems.some((system) => (
+    !Number.isSafeInteger(system.phaseIndex)
+    || system.phaseIndex !== phases.indexOf(system.phase)
+    || !Number.isSafeInteger(system.order)
+  ))) {
+    fail('KINETIX_SYSTEM_ORDER_INVALID');
+  }
+  for (const payloadEntry of manifest.payloads) {
+    if (!products[payloadEntry.name] || digest(products[payloadEntry.name]) !== payloadEntry.digest
+      || stableBytes(products[payloadEntry.name]).length !== payloadEntry.byteLength) {
+      fail('KINETIX_PAYLOAD_DIGEST_MISMATCH');
+    }
+  }
+
+  const componentSources = hydrateComponentSources(products);
+  let state = createInitialState(worldId, products, componentSources);
+  const prefabById = new Map(manifest.prefabs.map((prefab) => [prefab.id, prefab]));
+  const systemById = new Map(manifest.systems.map((system) => [system.id, system]));
+  const directBySource = new Map(manifest.directEntities.map((entity) => [entity.sourceId, entity.index]));
+  const queues = new Map(phases.map((phase) => [phase, []]));
+  const queueSequences = new Map(phases.map((phase) => [phase, 0]));
+  const closedPhases = new Set();
+  const resolvedSpawns = new Map();
+  let nextTokenId = 1;
+  let queuedCommandCount = 0;
+  let iterating = false;
+
+  function clearTransientState() {
+    for (const phase of phases) {
+      queues.set(phase, []);
+      queueSequences.set(phase, 0);
+    }
+    closedPhases.clear();
+    resolvedSpawns.clear();
+    queuedCommandCount = 0;
+  }
+
+  function enqueue(system, command) {
+    if (!isPlainObject(command) || !system.structuralCommands.includes(command.kind)) {
+      fail('KINETIX_COMMAND_NOT_DECLARED');
+    }
+    if (!phases.includes(command.phase)) {
+      fail('KINETIX_PHASE_INVALID');
+    }
+    if (closedPhases.has(command.phase)) {
+      fail('KINETIX_PHASE_CLOSED');
+    }
+    if (queuedCommandCount >= manifest.budgets.maxCommandsPerTick) {
+      fail('KINETIX_COMMAND_BOUND_EXCEEDED');
+    }
+    if (typeof command.sortKey !== 'number' && typeof command.sortKey !== 'string') {
+      fail('KINETIX_COMMAND_INVALID');
+    }
+    const sequence = queueSequences.get(command.phase);
+    queueSequences.set(command.phase, sequence + 1);
+    const token = command.kind === 'spawnPrefab' ? { worldId, tokenId: nextTokenId } : null;
+    nextTokenId += command.kind === 'spawnPrefab' ? 1 : 0;
+    queues.get(command.phase).push({
+      ...structuredClone(command),
+      recordingPhaseIndex: system.phaseIndex,
+      systemOrder: system.order,
+      sequence,
+      token,
+    });
+    queuedCommandCount += 1;
+    return token;
+  }
+
+  function applySpawn(shadow, command, stagedSpawns) {
+    const prefab = prefabById.get(command.prefabId);
+    if (!prefab) {
+      fail('KINETIX_PREFAB_NOT_FOUND');
+    }
+    const liveForPrefab = [...shadow.closures.values()].filter((closure) => closure.prefabId === prefab.id).length;
+    if (liveForPrefab >= prefab.poolBudget
+      || activeCount(shadow) + prefab.entities.length > manifest.budgets.maxLiveRuntimeEntities) {
+      fail('KINETIX_BUDGET_EXCEEDED');
+    }
+    const spawnId = shadow.nextSpawnId;
+    shadow.nextSpawnId += 1;
+    const closureId = `${prefab.id}:${spawnId}`;
+    const handles = new Map();
+    const indices = [];
+    for (const localEntity of prefab.entities) {
+      const index = allocateIndex(shadow);
+      const prior = shadow.slots[index];
+      const generation = prior.generation ?? 1;
+      shadow.slots[index] = {
+        generation,
+        active: true,
+        enabled: localEntity.enabled,
+        sourceId: null,
+        profile: prefab.profile,
+        archetypeId: localEntity.archetypeId,
+        components: structuredClone(componentSources.prefabs.get(`${prefab.id}:${localEntity.localEntityId}`) ?? []),
+        closureId,
+        localEntityId: localEntity.localEntityId,
+        identity: {
+          kind: 'prefab',
+          prefabId: prefab.id,
+          monotonicSpawnId: spawnId,
+          localEntityId: localEntity.localEntityId,
+        },
+      };
+      indices.push(index);
+      handles.set(localEntity.localEntityId, handleFor(worldId, index, generation));
+    }
+    const rootHandle = handles.get(prefab.rootLocalEntityId);
+    shadow.closures.set(closureId, {
+      prefabId: prefab.id,
+      monotonicSpawnId: spawnId,
+      rootIndex: rootHandle.index,
+      indices,
+    });
+    stagedSpawns.set(command.token.tokenId, handles);
+  }
+
+  function applyDespawn(shadow, command, despawnedClosures, despawnedHandles) {
+    if (isPlainObject(command.handle) && Object.hasOwn(command.handle, 'tokenId')) {
+      fail('KINETIX_UNSPAWNED_TARGET');
+    }
+    const handleKey = `${command.handle?.worldId}:${command.handle?.index}:${command.handle?.generation}`;
+    if (despawnedHandles.has(handleKey)) {
+      fail('KINETIX_COMMAND_CONFLICT');
+    }
+    const slot = validateHandle(shadow, command.handle);
+    if (slot.closureId === null) {
+      fail('KINETIX_NOT_PREFAB_INSTANCE');
+    }
+    const closure = shadow.closures.get(slot.closureId);
+    if (closure.rootIndex !== command.handle.index) {
+      fail('KINETIX_NOT_CLOSURE_ROOT');
+    }
+    if (despawnedClosures.has(slot.closureId)) {
+      fail('KINETIX_COMMAND_CONFLICT');
+    }
+    despawnedClosures.add(slot.closureId);
+    closure.indices.forEach((index) => {
+      const member = shadow.slots[index];
+      despawnedHandles.add(`${worldId}:${index}:${member.generation}`);
+    });
+    for (const index of closure.indices) {
+      const member = shadow.slots[index];
+      member.active = false;
+      member.generation += 1;
+      shadow.freeIndices.push(index);
+    }
+    shadow.freeIndices.sort((left, right) => left - right);
+    shadow.closures.delete(slot.closureId);
+  }
+
+  function applySetEnabled(shadow, command, enabledWrites, despawnedClosures, despawnedHandles) {
+    if (isPlainObject(command.handle) && Object.hasOwn(command.handle, 'tokenId')) {
+      fail('KINETIX_UNSPAWNED_TARGET');
+    }
+    const handleKey = `${command.handle?.worldId}:${command.handle?.index}:${command.handle?.generation}`;
+    if (despawnedHandles.has(handleKey)) {
+      fail('KINETIX_COMMAND_CONFLICT');
+    }
+    const slot = validateHandle(shadow, command.handle);
+    if (typeof command.enabled !== 'boolean') {
+      fail('KINETIX_COMMAND_INVALID');
+    }
+    if (slot.closureId !== null && despawnedClosures.has(slot.closureId)) {
+      fail('KINETIX_COMMAND_CONFLICT');
+    }
+    const targetKey = slot.closureId ?? `direct:${command.handle.index}`;
+    if (enabledWrites.has(targetKey) && enabledWrites.get(targetKey) !== command.enabled) {
+      fail('KINETIX_COMMAND_CONFLICT');
+    }
+    enabledWrites.set(targetKey, command.enabled);
+    const indices = slot.closureId === null ? [command.handle.index] : shadow.closures.get(slot.closureId).indices;
+    indices.forEach((index) => { shadow.slots[index].enabled = command.enabled; });
+  }
+
+  function playback(phase) {
+    if (iterating) {
+      fail('KINETIX_MUTATION_DURING_QUERY');
+    }
+    if (!phases.includes(phase)) {
+      fail('KINETIX_PHASE_INVALID');
+    }
+    if (closedPhases.has(phase)) {
+      fail('KINETIX_PHASE_CLOSED');
+    }
+    const batch = queues.get(phase).sort((left, right) => (
+      left.recordingPhaseIndex - right.recordingPhaseIndex
+      || left.systemOrder - right.systemOrder
+      || compareSortKey(left.sortKey, right.sortKey)
+      || left.sequence - right.sequence
+    ));
+    const shadow = structuredClone(state);
+    const stagedSpawns = new Map();
+    const despawnedClosures = new Set();
+    const despawnedHandles = new Set();
+    const enabledWrites = new Map();
+    try {
+      for (const command of batch) {
+        if (command.kind === 'spawnPrefab') {
+          applySpawn(shadow, command, stagedSpawns);
+        } else if (command.kind === 'despawnPrefab') {
+          applyDespawn(shadow, command, despawnedClosures, despawnedHandles);
+        } else if (command.kind === 'setEnabled') {
+          applySetEnabled(shadow, command, enabledWrites, despawnedClosures, despawnedHandles);
+        }
+      }
+    } catch (error) {
+      queuedCommandCount -= batch.length;
+      queues.set(phase, []);
+      throw error;
+    }
+    state = shadow;
+    stagedSpawns.forEach((handles, tokenId) => resolvedSpawns.set(tokenId, handles));
+    queuedCommandCount -= batch.length;
+    queues.set(phase, []);
+    closedPhases.add(phase);
+  }
+
+  function recorderForTest(systemId) {
+    const system = systemById.get(systemId);
+    if (!system) {
+      fail('KINETIX_SYSTEM_NOT_INSTALLED');
+    }
+    return Object.freeze({ enqueue: (command) => enqueue(system, command) });
+  }
+
+  function directHandle(sourceId) {
+    const index = directBySource.get(sourceId);
+    if (index === undefined) {
+      fail('KINETIX_SOURCE_NOT_FOUND');
+    }
+    const slot = state.slots[index];
+    return handleFor(worldId, index, slot.generation);
+  }
+
+  function read(handle) {
+    const slot = validateHandle(state, handle);
+    return structuredClone({
+      enabled: slot.enabled,
+      identity: slot.identity,
+      components: slot.components,
+      archetypeId: slot.archetypeId,
+    });
+  }
+
+  function resolveSpawn(token, localEntityId) {
+    if (!isPlainObject(token) || token.worldId !== worldId) {
+      fail('KINETIX_UNSPAWNED_TARGET');
+    }
+    const handles = resolvedSpawns.get(token.tokenId);
+    if (!handles || !handles.has(localEntityId)) {
+      fail('KINETIX_UNSPAWNED_TARGET');
+    }
+    return structuredClone(handles.get(localEntityId));
+  }
+
+  function query(querySpec) {
+    const all = querySpec?.all ?? [];
+    const none = querySpec?.none ?? [];
+    return (function* iterate() {
+      if (iterating) {
+        fail('KINETIX_QUERY_REENTRANT');
+      }
+      iterating = true;
+      try {
+        for (let index = 0; index < state.slots.length; index += 1) {
+          const slot = state.slots[index];
+          if (!slot?.active || !slot.enabled) {
+            continue;
+          }
+          const types = new Set(slot.components.map((component) => component.type));
+          if (all.every((type) => types.has(type)) && none.every((type) => !types.has(type))) {
+            yield handleFor(worldId, index, slot.generation);
+          }
+        }
+      } finally {
+        iterating = false;
+      }
+    }());
+  }
+
+  function simulationComponent(sourceId, componentType) {
+    const index = directBySource.get(sourceId);
+    const slot = index === undefined ? null : state.slots[index];
+    const component = slot?.components.find((candidate) => (
+      candidate.domain === 'simulation' && candidate.type === componentType
+    ));
+    if (component === undefined) fail('KINETIX_SIMULATION_COMPONENT_NOT_FOUND');
+    return component;
+  }
+
+  const simulationAccess = Object.freeze({
+    read: (sourceId, componentType) => structuredClone(
+      simulationComponent(sourceId, componentType).properties,
+    ),
+    write: (sourceId, componentType, properties) => {
+      if (!isPlainObject(properties)) fail('KINETIX_SIMULATION_COMPONENT_INVALID');
+      simulationComponent(sourceId, componentType).properties = structuredClone(properties);
+    },
+  });
+
+  function deriveTransforms() {
+    const projected = new Map();
+    const worldValues = new Map();
+    function deriveIndex(index, parentIndex) {
+      const slot = state.slots[index];
+      if (!slot?.active) {
+        return;
+      }
+      const profile = installedProfiles.get(slot.profile);
+      const semantics = profile?.transformSemantics;
+      if (!semantics) {
+        return;
+      }
+      const local = slot.components.find((component) => component.type === semantics.localType)?.properties;
+      if (local === undefined) {
+        return;
+      }
+      const parentWorld = parentIndex === null ? null : worldValues.get(parentIndex) ?? null;
+      const worldValue = semantics.composeWorld({ parentWorld: structuredClone(parentWorld), local: structuredClone(local) });
+      worldValues.set(index, structuredClone(worldValue));
+      projected.set(handleFor(worldId, index, slot.generation), structuredClone(worldValue));
+    }
+    const parentByChild = new Map(manifest.parentEdges.map((edge) => [edge.childIndex, edge.parentIndex]));
+    manifest.directEntities
+      .filter((entity) => !parentByChild.has(entity.index))
+      .forEach((entity) => deriveIndex(entity.index, null));
+    manifest.parentEdges.forEach((edge) => deriveIndex(edge.childIndex, edge.parentIndex));
+    for (const closure of state.closures.values()) {
+      const prefab = prefabById.get(closure.prefabId);
+      const localToRuntime = new Map(prefab.entities.map((entity, index) => [index, closure.indices[index]]));
+      const prefabParentByChild = new Map(prefab.parentEdges.map((edge) => [edge.childLocalIndex, edge.parentLocalIndex]));
+      prefab.entities
+        .filter((entity) => !prefabParentByChild.has(entity.localIndex))
+        .forEach((entity) => deriveIndex(localToRuntime.get(entity.localIndex), null));
+      prefab.parentEdges.forEach((edge) => {
+        deriveIndex(localToRuntime.get(edge.childLocalIndex), localToRuntime.get(edge.parentLocalIndex));
+      });
+    }
+    return projected;
+  }
+
+  function step(inputFrame) {
+    if (!isPlainObject(inputFrame)) {
+      fail('KINETIX_INPUT_FRAME_INVALID');
+    }
+    clearTransientState();
+    for (const phase of phases.slice(0, 3)) {
+      for (const system of manifest.systems.filter((entry) => entry.phase === phase)) {
+        const profile = installedProfiles.get(system.profileId);
+        profile.executeSystem?.({
+          systemId: system.id,
+          inputFrame: structuredClone(inputFrame),
+          recorder: Object.freeze({ enqueue: (command) => enqueue(system, command) }),
+          simulation: simulationAccess,
+          initialization: structuredClone(initialization),
+        });
+      }
+      playback(phase);
+    }
+    state.tick += 1;
+    state.lastInputFrame = structuredClone(inputFrame);
+    return stableBytes(authoritativeView(state));
+  }
+
+  return Object.freeze({
+    directHandle,
+    read,
+    resolveSpawn,
+    recorderForTest,
+    playback,
+    beginTick: clearTransientState,
+    query,
+    deriveTransforms,
+    step,
+    snapshot: () => authoritativeView(state),
+    restore: (snapshot) => {
+      if (!isPlainObject(snapshot) || snapshot.worldId !== worldId
+        || !Number.isSafeInteger(snapshot.tick) || snapshot.tick < 0
+        || !Number.isSafeInteger(snapshot.nextSpawnId) || snapshot.nextSpawnId < 1
+        || !Array.isArray(snapshot.slots) || !Array.isArray(snapshot.closures)
+        || !Array.isArray(snapshot.freeIndices)) {
+        fail('KINETIX_SNAPSHOT_INVALID');
+      }
+      state = stateFromSnapshot(structuredClone(snapshot), componentSources);
+      clearTransientState();
+    },
+    authoritativeBytes: () => stableBytes(authoritativeView(state)),
+    canonicalStateBytes: () => stableBytes(authoritativeView(state)),
+  });
+}