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

package/src/kinetix-installed-f64-reference.mjs

@@ -0,0 +1,157 @@
+// TypeScript-reference wrapper for the deterministic-f64 component runtime:
+// canonical hashing + replay execution on top of the installed sim core.
+// The canonical hash layout is documented beside the installed runtime and
+// mirrored by its portable implementation.
+
+import { createHash } from 'node:crypto';
+import {
+  createF64Runtime,
+  detMath,
+  f64FromHex,
+  liveEntities,
+  mulberry32Next,
+  tickF64Runtime,
+} from './kinetix-installed-f64-runtime.mjs';
+
+export { createF64Runtime, detMath, liveEntities, mulberry32Next, tickF64Runtime };
+
+function decodeF64(value) {
+  return f64FromHex(value);
+}
+
+function writeString(chunks, value) {
+  const bytes = Buffer.from(value, 'utf8');
+  const length = Buffer.alloc(4);
+  length.writeUInt32LE(bytes.length);
+  chunks.push(length, bytes);
+}
+
+function writeF64(chunks, value) {
+  const bytes = Buffer.alloc(8);
+  bytes.writeDoubleLE(value);
+  chunks.push(bytes);
+}
+
+function writeU64(chunks, value) {
+  const bytes = Buffer.alloc(8);
+  bytes.writeBigUInt64LE(BigInt(value));
+  chunks.push(bytes);
+}
+
+function writeI64(chunks, value) {
+  const bytes = Buffer.alloc(8);
+  bytes.writeBigInt64LE(BigInt(value));
+  chunks.push(bytes);
+}
+
+export function canonicalF64TickHash(runtime) {
+  const chunks = [];
+  writeU64(chunks, BigInt(runtime.tick));
+  for (const streamId of runtime.rngStreamOrder) {
+    writeString(chunks, streamId);
+    const state = Buffer.alloc(4);
+    state.writeUInt32LE(runtime.rngStreams.get(streamId).state);
+    chunks.push(state);
+  }
+  const ordered = [
+    ...runtime.staticEntities.filter((entity) => entity.alive),
+    ...runtime.pooled.filter((entity) => entity.alive).sort((a, b) => (a.spawnId < b.spawnId ? -1 : 1)),
+  ];
+  for (const entity of ordered) {
+    writeString(chunks, entity.ref);
+    writeU64(chunks, entity.spawnId);
+    for (const component of entity.components) {
+      writeString(chunks, component.type);
+      switch (component.type) {
+        case 'Transform2D':
+          writeF64(chunks, component.position.x);
+          writeF64(chunks, component.position.y);
+          writeF64(chunks, component.velocity.x);
+          writeF64(chunks, component.velocity.y);
+          writeF64(chunks, component.heading);
+          break;
+        case 'TwinStickInput':
+          writeF64(chunks, component.move.x);
+          writeF64(chunks, component.move.y);
+          writeF64(chunks, component.aim.x);
+          writeF64(chunks, component.aim.y);
+          chunks.push(Buffer.from([component.fire ? 1 : 0]));
+          break;
+        case 'SpawnShield':
+          writeF64(chunks, component.remaining);
+          break;
+        case 'Telegraph':
+          writeF64(chunks, component.remaining);
+          break;
+        case 'WanderMover':
+          writeF64(chunks, component.rerollTimer);
+          break;
+        case 'SeekMover':
+          writeF64(chunks, component.aliveSeconds);
+          break;
+        case 'AutoFireWeapon':
+          writeF64(chunks, component.cooldown);
+          writeU64(chunks, BigInt(component.nextBulletId));
+          break;
+        case 'Lifetime':
+          writeF64(chunks, component.age);
+          break;
+        case 'Health':
+          writeI64(chunks, BigInt(component.hp));
+          break;
+        case 'ResourceCounter':
+          writeI64(chunks, component.score);
+          writeI64(chunks, component.deaths);
+          break;
+        default:
+          break;
+      }
+    }
+  }
+  return createHash('sha256').update(Buffer.concat(chunks)).digest('hex');
+}
+
+export function runF64Replay(pack, replay, options = {}) {
+  const hashEveryTick = options.hashEveryTick !== false;
+  const runtime = createF64Runtime(pack, options);
+  const inputsByTick = new Map();
+  for (const frame of replay.inputFrames ?? []) {
+    inputsByTick.set(frame.tick, frame.slots);
+  }
+  let currentInputs = Array.from({ length: pack.inputSlots }, () => ({ movement: { x: 0, y: 0 }, aim: { x: 0, y: 0 }, fire: false }));
+
+  const tickHashes = [];
+  const streamHash = createHash('sha256');
+  const startedAt = process.hrtime.bigint();
+  for (let tick = 0; tick < replay.tickCount; tick += 1) {
+    const frame = inputsByTick.get(tick);
+    if (frame) {
+      currentInputs = frame.map((slot) => ({
+        movement: { x: decodeF64(slot.movement[0]), y: decodeF64(slot.movement[1]) },
+        aim: { x: decodeF64(slot.aim[0]), y: decodeF64(slot.aim[1]) },
+        fire: slot.fire === true,
+      }));
+    }
+    tickF64Runtime(runtime, currentInputs);
+    if (hashEveryTick || tick === replay.tickCount - 1) {
+      const tickHash = canonicalF64TickHash(runtime);
+      if (hashEveryTick) tickHashes.push(tickHash);
+      else tickHashes[0] = tickHash;
+      streamHash.update(tickHash);
+    }
+  }
+  const elapsedMs = Number(process.hrtime.bigint() - startedAt) / 1e6;
+  return {
+    tickHashes,
+    finalDigest: streamHash.digest('hex'),
+    metrics: {
+      runtime: 'typescript-reference-f64',
+      tickCount: replay.tickCount,
+      elapsedMs,
+      ticksPerSecond: elapsedMs > 0 ? Math.round((replay.tickCount / elapsedMs) * 1000) : null,
+      liveEntitiesAtEnd: liveEntities(runtime).length,
+      finalScore: String(runtime.staticEntities.find((entity) => entity.byType.get('ResourceCounter'))?.byType.get('ResourceCounter').score ?? 0n),
+      shipDeaths: String(runtime.staticEntities.find((entity) => entity.byType.get('ResourceCounter'))?.byType.get('ResourceCounter').deaths ?? 0n),
+    },
+  };
+}

package/src/kinetix-installed-f64-render-frames.mjs

@@ -0,0 +1,53 @@
+// Node-side frame dump for the installed visual proof: runs a data-only
+// replay, renders every 2nd tick (60Hz sim -> 30fps
+// video) with the deterministic parity renderer, and writes raw RGB24 frames
+// plus per-frame sha256 hashes. This is also the acceptance oracle for the
+// C++ renderer.
+//
+//   node spikes/component-runtime/render-frames-node.mjs <outDir> [packPath replayPath]
+
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createF64Runtime, tickF64Runtime, f64FromHex } from './kinetix-installed-f64-runtime.mjs';
+import { renderF64Frame, FRAME_WIDTH, FRAME_HEIGHT } from './kinetix-installed-f64-renderer.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const prototypeRoot = resolve(here, '../..');
+const outDir = resolve(process.argv[2] ?? join(prototypeRoot, 'artifacts/component-runtime/parity-frames-node'));
+if (process.argv[3] === undefined || process.argv[4] === undefined) throw new Error('KINETIX_F64_RENDER_INPUT_REQUIRED');
+const packPath = resolve(process.argv[3]);
+const replayPath = resolve(process.argv[4]);
+
+const pack = JSON.parse(readFileSync(packPath, 'utf8'));
+const replay = JSON.parse(readFileSync(replayPath, 'utf8'));
+
+mkdirSync(outDir, { recursive: true });
+const runtime = createF64Runtime(pack);
+const inputsByTick = new Map((replay.inputFrames ?? []).map((frame) => [frame.tick, frame.slots]));
+let currentInputs = Array.from({ length: pack.inputSlots }, () => ({ movement: { x: 0, y: 0 }, aim: { x: 0, y: 0 }, fire: false }));
+
+const frame = new Uint8Array(FRAME_WIDTH * FRAME_HEIGHT * 3);
+const hashes = [];
+let frameIndex = 0;
+for (let tick = 0; tick < replay.tickCount; tick += 1) {
+  const slots = inputsByTick.get(tick);
+  if (slots) {
+    currentInputs = slots.map((slot) => ({
+      movement: { x: f64FromHex(slot.movement[0]), y: f64FromHex(slot.movement[1]) },
+      aim: { x: f64FromHex(slot.aim[0]), y: f64FromHex(slot.aim[1]) },
+      fire: slot.fire === true,
+    }));
+  }
+  tickF64Runtime(runtime, currentInputs);
+  if (tick % 2 === 1) {
+    renderF64Frame(runtime, frame);
+    const name = `frame-${String(frameIndex).padStart(3, '0')}.rgb`;
+    writeFileSync(join(outDir, name), frame);
+    hashes.push(createHash('sha256').update(frame).digest('hex'));
+    frameIndex += 1;
+  }
+}
+writeFileSync(join(outDir, 'frame-hashes.json'), `${JSON.stringify({ width: FRAME_WIDTH, height: FRAME_HEIGHT, frames: frameIndex, hashes }, null, 2)}\n`);
+console.log(JSON.stringify({ side: 'node-reference', frames: frameIndex, firstHash: hashes[0], lastHash: hashes[hashes.length - 1] }));

package/src/kinetix-installed-f64-renderer.mjs

@@ -0,0 +1,240 @@
+// Deterministic parity renderer for the installed f64 runtime.
+// Pure function of sim state -> 1280x720 RGB24 frame. Browser-safe.
+//
+// Bit-exactness contract (mirrored in the portable installed renderer):
+// - only +,-,*,/ double arithmetic, comparisons, floor/ceil/abs and integer
+//   pixel loops; the ONLY transcendentals are detMath.cos/sin for the ship
+//   heading triangle (battery-proven identical in C++);
+// - hard-edged shapes (no anti-aliasing, no alpha blending except constant
+//   50% mix implemented as integer (a+b)>>1);
+// - draw order: background grid -> arena border -> telegraph rings -> enemies
+//   (statics in pack order, pooled by ascending spawnId) -> bullets -> ship ->
+//   HUD score bar. Within a category the same entity order as hashing.
+//
+// The renderer never mutates runtime state.
+
+import { detMath } from './kinetix-installed-f64-runtime.mjs';
+
+export const FRAME_WIDTH = 1280;
+export const FRAME_HEIGHT = 720;
+
+const COLORS = Object.freeze({
+  background: [10, 10, 18],
+  grid: [20, 20, 40],
+  border: [42, 42, 85],
+  ship: [102, 255, 238],
+  shipShield: [220, 240, 255],
+  bulletCore: [255, 243, 199],
+  bulletGlow: [138, 122, 64],
+  wanderer: [176, 64, 255],
+  shard: [207, 122, 255],
+  grunt: [170, 255, 51],
+  telegraph: [90, 90, 140],
+  scoreBar: [255, 216, 77],
+  deathPip: [255, 80, 80],
+});
+
+function putPixel(frame, x, y, color) {
+  if (x < 0 || y < 0 || x >= FRAME_WIDTH || y >= FRAME_HEIGHT) return;
+  const offset = (y * FRAME_WIDTH + x) * 3;
+  frame[offset] = color[0];
+  frame[offset + 1] = color[1];
+  frame[offset + 2] = color[2];
+}
+
+function mixPixel(frame, x, y, color) {
+  if (x < 0 || y < 0 || x >= FRAME_WIDTH || y >= FRAME_HEIGHT) return;
+  const offset = (y * FRAME_WIDTH + x) * 3;
+  frame[offset] = (frame[offset] + color[0]) >> 1;
+  frame[offset + 1] = (frame[offset + 1] + color[1]) >> 1;
+  frame[offset + 2] = (frame[offset + 2] + color[2]) >> 1;
+}
+
+function fillCircle(frame, cx, cy, radius, color) {
+  const x0 = Math.max(0, Math.floor(cx - radius));
+  const x1 = Math.min(FRAME_WIDTH - 1, Math.ceil(cx + radius));
+  const y0 = Math.max(0, Math.floor(cy - radius));
+  const y1 = Math.min(FRAME_HEIGHT - 1, Math.ceil(cy + radius));
+  const r2 = radius * radius;
+  for (let y = y0; y <= y1; y += 1) {
+    for (let x = x0; x <= x1; x += 1) {
+      const dx = x + 0.5 - cx;
+      const dy = y + 0.5 - cy;
+      if (dx * dx + dy * dy <= r2) putPixel(frame, x, y, color);
+    }
+  }
+}
+
+function ring(frame, cx, cy, innerRadius, outerRadius, color) {
+  const x0 = Math.max(0, Math.floor(cx - outerRadius));
+  const x1 = Math.min(FRAME_WIDTH - 1, Math.ceil(cx + outerRadius));
+  const y0 = Math.max(0, Math.floor(cy - outerRadius));
+  const y1 = Math.min(FRAME_HEIGHT - 1, Math.ceil(cy + outerRadius));
+  const inner2 = innerRadius * innerRadius;
+  const outer2 = outerRadius * outerRadius;
+  for (let y = y0; y <= y1; y += 1) {
+    for (let x = x0; x <= x1; x += 1) {
+      const dx = x + 0.5 - cx;
+      const dy = y + 0.5 - cy;
+      const d2 = dx * dx + dy * dy;
+      if (d2 >= inner2 && d2 <= outer2) putPixel(frame, x, y, color);
+    }
+  }
+}
+
+function fillDiamond(frame, cx, cy, size, color) {
+  const x0 = Math.max(0, Math.floor(cx - size));
+  const x1 = Math.min(FRAME_WIDTH - 1, Math.ceil(cx + size));
+  const y0 = Math.max(0, Math.floor(cy - size));
+  const y1 = Math.min(FRAME_HEIGHT - 1, Math.ceil(cy + size));
+  for (let y = y0; y <= y1; y += 1) {
+    for (let x = x0; x <= x1; x += 1) {
+      const dx = x + 0.5 - cx;
+      const dy = y + 0.5 - cy;
+      const adx = dx < 0 ? -dx : dx;
+      const ady = dy < 0 ? -dy : dy;
+      if (adx + ady <= size) putPixel(frame, x, y, color);
+    }
+  }
+}
+
+function edge(ax, ay, bx, by, px, py) {
+  return (bx - ax) * (py - ay) - (by - ay) * (px - ax);
+}
+
+function fillTriangle(frame, ax, ay, bx, by, cx, cy, color) {
+  const minX = Math.max(0, Math.floor(Math.min(ax, bx, cx)));
+  const maxX = Math.min(FRAME_WIDTH - 1, Math.ceil(Math.max(ax, bx, cx)));
+  const minY = Math.max(0, Math.floor(Math.min(ay, by, cy)));
+  const maxY = Math.min(FRAME_HEIGHT - 1, Math.ceil(Math.max(ay, by, cy)));
+  const area = edge(ax, ay, bx, by, cx, cy);
+  if (area === 0) return;
+  for (let y = minY; y <= maxY; y += 1) {
+    for (let x = minX; x <= maxX; x += 1) {
+      const px = x + 0.5;
+      const py = y + 0.5;
+      const w0 = edge(ax, ay, bx, by, px, py);
+      const w1 = edge(bx, by, cx, cy, px, py);
+      const w2 = edge(cx, cy, ax, ay, px, py);
+      if (area > 0 ? w0 >= 0 && w1 >= 0 && w2 >= 0 : w0 <= 0 && w1 <= 0 && w2 <= 0) {
+        putPixel(frame, x, y, color);
+      }
+    }
+  }
+}
+
+function orderedEntities(runtime) {
+  return [
+    ...runtime.staticEntities.filter((entity) => entity.alive),
+    ...runtime.pooled.filter((entity) => entity.alive).sort((a, b) => (a.spawnId < b.spawnId ? -1 : 1)),
+  ];
+}
+
+export function renderF64Frame(runtime, frame) {
+  // background
+  for (let offset = 0; offset < frame.length; offset += 3) {
+    frame[offset] = COLORS.background[0];
+    frame[offset + 1] = COLORS.background[1];
+    frame[offset + 2] = COLORS.background[2];
+  }
+  // grid every 80 px
+  for (let x = 0; x < FRAME_WIDTH; x += 80) {
+    for (let y = 0; y < FRAME_HEIGHT; y += 1) putPixel(frame, x, y, COLORS.grid);
+  }
+  for (let y = 0; y < FRAME_HEIGHT; y += 80) {
+    for (let x = 0; x < FRAME_WIDTH; x += 1) putPixel(frame, x, y, COLORS.grid);
+  }
+  // arena border (2 px)
+  for (let x = 0; x < FRAME_WIDTH; x += 1) {
+    putPixel(frame, x, 0, COLORS.border);
+    putPixel(frame, x, 1, COLORS.border);
+    putPixel(frame, x, FRAME_HEIGHT - 2, COLORS.border);
+    putPixel(frame, x, FRAME_HEIGHT - 1, COLORS.border);
+  }
+  for (let y = 0; y < FRAME_HEIGHT; y += 1) {
+    putPixel(frame, 0, y, COLORS.border);
+    putPixel(frame, 1, y, COLORS.border);
+    putPixel(frame, FRAME_WIDTH - 2, y, COLORS.border);
+    putPixel(frame, FRAME_WIDTH - 1, y, COLORS.border);
+  }
+
+  const entities = orderedEntities(runtime);
+
+  // telegraph rings (behind bodies)
+  for (const entity of entities) {
+    const telegraph = entity.byType.get('Telegraph');
+    if (!telegraph || telegraph.remaining <= 0) continue;
+    const transform = entity.byType.get('Transform2D');
+    const circle = entity.byType.get('CollisionCircle');
+    const base = circle ? circle.radius : 8;
+    const radius = base * (1.5 + telegraph.remaining);
+    ring(frame, transform.position.x, transform.position.y, radius - 1.5, radius, COLORS.telegraph);
+  }
+
+  // enemies + bullets + ship
+  for (const entity of entities) {
+    const transform = entity.byType.get('Transform2D');
+    if (!transform) continue;
+    const telegraphing = (() => {
+      const telegraph = entity.byType.get('Telegraph');
+      return telegraph ? telegraph.remaining > 0 : false;
+    })();
+
+    if (entity.byType.get('WanderMover')) {
+      if (!telegraphing) {
+        fillCircle(frame, transform.position.x, transform.position.y, 12, COLORS.wanderer);
+      }
+      continue;
+    }
+    if (entity.byType.get('SeekMover')) {
+      if (!telegraphing) {
+        fillDiamond(frame, transform.position.x, transform.position.y, 11, COLORS.grunt);
+      }
+      continue;
+    }
+    if (entity.ref === 'shard') {
+      fillCircle(frame, transform.position.x, transform.position.y, 7.5, COLORS.shard);
+      continue;
+    }
+    if (entity.ref === 'bullet') {
+      ring(frame, transform.position.x, transform.position.y, 4, 7, COLORS.bulletGlow);
+      fillCircle(frame, transform.position.x, transform.position.y, 4, COLORS.bulletCore);
+      continue;
+    }
+    if (entity.byType.get('AxisDriveMover')) {
+      const heading = transform.heading;
+      const cos = detMath.cos(heading);
+      const sin = detMath.sin(heading);
+      const size = 14;
+      const noseX = transform.position.x + cos * size;
+      const noseY = transform.position.y + sin * size;
+      const leftX = transform.position.x + (-cos * 0.7 - sin * 0.6) * size;
+      const leftY = transform.position.y + (-sin * 0.7 + cos * 0.6) * size;
+      const rightX = transform.position.x + (-cos * 0.7 + sin * 0.6) * size;
+      const rightY = transform.position.y + (-sin * 0.7 - cos * 0.6) * size;
+      fillTriangle(frame, noseX, noseY, leftX, leftY, rightX, rightY, COLORS.ship);
+      const shield = entity.byType.get('SpawnShield');
+      if (shield && shield.remaining > 0) {
+        ring(frame, transform.position.x, transform.position.y, 16, 18, COLORS.shipShield);
+      }
+    }
+  }
+
+  // HUD: score bar + death pips (mix 50% over background for a HUD feel)
+  const game = runtime.staticEntities.find((entity) => entity.byType.get('ResourceCounter'));
+  if (game) {
+    const counter = game.byType.get('ResourceCounter');
+    const score = Number(counter.score);
+    const barWidth = Math.floor(Math.min(score, 2000) * 0.15);
+    for (let y = 12; y < 22; y += 1) {
+      for (let x = 16; x < 16 + barWidth; x += 1) mixPixel(frame, x, y, COLORS.scoreBar);
+    }
+    const deaths = Number(counter.deaths);
+    for (let pip = 0; pip < Math.min(deaths, 10); pip += 1) {
+      for (let y = 26; y < 34; y += 1) {
+        for (let x = 16 + pip * 12; x < 24 + pip * 12; x += 1) putPixel(frame, x, y, COLORS.deathPip);
+      }
+    }
+  }
+  return frame;
+}

package/src/kinetix-installed-f64-runtime-adapter.mjs

@@ -0,0 +1,68 @@
+import { createF64Runtime, tickF64Runtime } from './kinetix-installed-f64-runtime.mjs';
+import { createInstalledRuntimeAdapter } from './kinetix-runtime-adapter-utils.mjs';
+import { decodeKinetixSessionConfig } from './kinetix-session-config.mjs';
+
+function entityState(entity) {
+  return {
+    ref: entity.ref,
+    spawnId: entity.spawnId,
+    components: structuredClone(entity.components),
+    fields: [...entity.fields.entries()].map(([key, value]) => [key, structuredClone(value)]),
+    alive: entity.alive,
+    spawnPosition: structuredClone(entity.spawnPosition),
+  };
+}
+
+function restoreEntity(state) {
+  const components = structuredClone(state.components);
+  return {
+    ref: state.ref,
+    spawnId: state.spawnId,
+    components,
+    fields: new Map(state.fields.map(([key, value]) => [key, structuredClone(value)])),
+    alive: state.alive,
+    spawnPosition: structuredClone(state.spawnPosition),
+    byType: new Map(components.map((component) => [component.type, component])),
+  };
+}
+
+export function createInstalledF64Runtime({ pack, identity, sessionConfigSchema, sessionConfigBytes, options = {} }) {
+  const session = decodeKinetixSessionConfig(sessionConfigSchema, sessionConfigBytes);
+  const configuredPack = structuredClone(pack);
+  configuredPack.inputSlots = session.playerCount;
+  configuredPack.rngStreams = configuredPack.rngStreams.map((stream, index) => ({
+    ...stream,
+    seed: (session.seed + index) >>> 0,
+  }));
+  const engine = createF64Runtime(configuredPack, options);
+
+  const captureState = () => ({
+    tick: engine.tick,
+    rngStreams: [...engine.rngStreams.entries()].map(([key, value]) => [key, structuredClone(value)]),
+    staticEntities: engine.staticEntities.map(entityState),
+    pooled: engine.pooled.map(entityState),
+    nextSpawnId: engine.nextSpawnId,
+    poolCounts: [...engine.poolCounts.entries()],
+    spawnsThisTick: engine.spawnsThisTick,
+    frameEvents: structuredClone(engine.frameEvents),
+  });
+  const restoreState = (state) => {
+    engine.tick = state.tick;
+    engine.rngStreams = new Map(state.rngStreams.map(([key, value]) => [key, structuredClone(value)]));
+    engine.staticEntities = state.staticEntities.map(restoreEntity);
+    engine.pooled = state.pooled.map(restoreEntity);
+    engine.nextSpawnId = state.nextSpawnId;
+    engine.poolCounts = new Map(state.poolCounts);
+    engine.spawnsThisTick = state.spawnsThisTick;
+    engine.frameEvents = structuredClone(state.frameEvents);
+  };
+  return createInstalledRuntimeAdapter({
+    identity,
+    sessionConfigBytes,
+    captureState,
+    restoreState,
+    frameOf: (state) => state.tick,
+    step: (inputs) => tickF64Runtime(engine, inputs),
+    capturedStateIsDetached: true,
+  });
+}