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

package/src/kinetix-world-runtime.mjs

@@ -0,0 +1,171 @@
+import { assertKinetixRuntimeIdentity } from './kinetix-runtime-contract.mjs';
+import { kinetixSessionConfigDigest } from './kinetix-session-config.mjs';
+import { sha256Hex } from './shared/sha256.mjs';
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+
+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 snapshotBytes(snapshot) {
+  return textEncoder.encode(JSON.stringify(canonicalize(snapshot)));
+}
+
+function assertWorld(world) {
+  if (!isPlainObject(world)
+    || typeof world.step !== 'function'
+    || typeof world.snapshot !== 'function'
+    || typeof world.restore !== 'function'
+    || typeof world.canonicalStateBytes !== 'function') {
+    fail('KINETIX_WORLD_INVALID');
+  }
+}
+
+function assertSnapshot(snapshot) {
+  if (!isPlainObject(snapshot) || !Number.isSafeInteger(snapshot.tick) || snapshot.tick < 0) {
+    fail('KINETIX_SNAPSHOT_INVALID');
+  }
+}
+
+export function createKinetixWorldRuntime({ world, identity, sessionConfigBytes = new TextEncoder().encode('{}') }) {
+  assertWorld(world);
+  assertKinetixRuntimeIdentity(identity);
+  if (!(sessionConfigBytes instanceof Uint8Array)
+    || sessionConfigBytes.byteLength < 1
+    || sessionConfigBytes.byteLength > 65_536) {
+    fail('KINETIX_SESSION_CONFIG_INVALID');
+  }
+  const checkpoints = new WeakMap();
+
+  function makeCheckpoint(snapshot) {
+    assertSnapshot(snapshot);
+    const copy = structuredClone(snapshot);
+    const checkpoint = Object.freeze({ frame: copy.tick });
+    checkpoints.set(checkpoint, {
+      frame: copy.tick,
+      snapshot: copy,
+      bytes: snapshotBytes(copy),
+    });
+    return checkpoint;
+  }
+
+  function checkpointData(checkpoint) {
+    const data = isPlainObject(checkpoint) ? checkpoints.get(checkpoint) : undefined;
+    if (!data) fail('KINETIX_RUNTIME_CHECKPOINT_INVALID');
+    return data;
+  }
+
+  const initialSnapshot = world.snapshot();
+  assertSnapshot(initialSnapshot);
+  let currentCheckpoint = makeCheckpoint(initialSnapshot);
+  const canonicalSessionConfig = sessionConfigBytes.slice();
+
+  const runtime = {
+    identity: Object.freeze(structuredClone(identity)),
+    sessionConfigDigest: kinetixSessionConfigDigest(canonicalSessionConfig),
+    get currentFrame() {
+      return checkpointData(currentCheckpoint).frame;
+    },
+    sessionConfigBytes() {
+      return canonicalSessionConfig.slice();
+    },
+    capture() {
+      return makeCheckpoint(checkpointData(currentCheckpoint).snapshot);
+    },
+    advance(requests) {
+      if (!Array.isArray(requests)) fail('KINETIX_RUNTIME_BATCH_INVALID');
+      let expectedFrame = this.currentFrame + 1;
+      for (const request of requests) {
+        if (!isPlainObject(request)
+          || request.frame !== expectedFrame
+          || !Array.isArray(request.inputs)
+          || !Array.isArray(request.commands)
+          || typeof request.checksum !== 'boolean') {
+          fail('KINETIX_RUNTIME_FRAME_MISMATCH');
+        }
+        expectedFrame += 1;
+      }
+
+      const starting = checkpointData(currentCheckpoint);
+      const results = [];
+      try {
+        for (const request of requests) {
+          world.step({
+            frame: request.frame,
+            inputs: structuredClone(request.inputs),
+            commands: structuredClone(request.commands),
+          });
+          const snapshot = world.snapshot();
+          assertSnapshot(snapshot);
+          if (snapshot.tick !== request.frame) fail('KINETIX_RUNTIME_FRAME_MISMATCH');
+          currentCheckpoint = makeCheckpoint(snapshot);
+          const result = {
+            frame: request.frame,
+            checkpoint: currentCheckpoint,
+          };
+          if (request.checksum) result.checksum = this.checksum(currentCheckpoint);
+          results.push(result);
+        }
+        return results;
+      } catch (error) {
+        world.restore(structuredClone(starting.snapshot));
+        currentCheckpoint = makeCheckpoint(starting.snapshot);
+        throw error;
+      }
+    },
+    restore(checkpoint) {
+      const data = checkpointData(checkpoint);
+      world.restore(structuredClone(data.snapshot));
+      const restored = world.snapshot();
+      assertSnapshot(restored);
+      if (restored.tick !== data.frame) fail('KINETIX_RUNTIME_FRAME_MISMATCH');
+      currentCheckpoint = makeCheckpoint(restored);
+    },
+    inspect(checkpoint) {
+      return structuredClone(checkpointData(checkpoint).snapshot);
+    },
+    serializeCheckpoint(checkpoint) {
+      return checkpointData(checkpoint).bytes.slice();
+    },
+    hydrateCheckpoint(frame, bytes) {
+      if (!Number.isSafeInteger(frame) || frame < 0 || !(bytes instanceof Uint8Array)) {
+        fail('KINETIX_RUNTIME_CHECKPOINT_INVALID');
+      }
+      let snapshot;
+      try {
+        snapshot = JSON.parse(textDecoder.decode(bytes));
+      } catch {
+        fail('KINETIX_RUNTIME_CHECKPOINT_INVALID');
+      }
+      assertSnapshot(snapshot);
+      if (snapshot.tick !== frame) fail('KINETIX_RUNTIME_FRAME_MISMATCH');
+      if (!snapshotBytes(snapshot).every((byte, index) => byte === bytes[index])
+        || snapshotBytes(snapshot).length !== bytes.length) {
+        fail('KINETIX_RUNTIME_CHECKPOINT_INVALID');
+      }
+      return makeCheckpoint(snapshot);
+    },
+    checksum(checkpoint) {
+      return sha256Hex(checkpointData(checkpoint).bytes);
+    },
+    wireChecksum(checkpoint) {
+      return sha256Hex(checkpointData(checkpoint).bytes);
+    },
+    release(_checkpoint) {},
+  };
+  return Object.freeze(runtime);
+}

package/src/runtime.mjs

@@ -0,0 +1,14 @@
+export {
+  assertKinetixRuntime,
+  assertKinetixRuntimeIdentity,
+  kinetixRuntimeAbiVersion,
+} from './kinetix-runtime-contract.mjs';
+export { createKinetixWorldRuntime } from './kinetix-world-runtime.mjs';
+export { createInstalledF64Runtime } from './kinetix-installed-f64-runtime-adapter.mjs';
+export { createInstalledSurvivalRuntime } from './kinetix-survival-runtime-adapter.mjs';
+export { createFixed1000Runtime } from './kinetix-fixed1000-runtime-adapter.mjs';
+export {
+  decodeKinetixSessionConfig,
+  encodeKinetixSessionConfig,
+  kinetixSessionConfigDigest,
+} from './kinetix-session-config.mjs';

package/src/shared/f64-bits.mjs

@@ -0,0 +1,14 @@
+// Exact f64 <-> u64-bit-pattern hex helpers. Browser-safe (no node imports);
+// the single source for pack v2 scalar encoding.
+
+const scratch = new DataView(new ArrayBuffer(8));
+
+export function f64FromHex(hex) {
+  scratch.setBigUint64(0, BigInt(hex), true);
+  return scratch.getFloat64(0, true);
+}
+
+export function hexFromF64(value) {
+  scratch.setFloat64(0, value, true);
+  return `0x${scratch.getBigUint64(0, true).toString(16).padStart(16, '0')}`;
+}