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

package/src/kinetix-render-projection.mjs

@@ -0,0 +1,28 @@
+import { createHash } from 'node:crypto';
+
+export function createKinetixRenderProjection({ world, products }) {
+  if (typeof world?.deriveTransforms !== 'function' || !Array.isArray(products?.presentation?.records)
+    || !Array.isArray(products?.binding?.records)) {
+    throw new Error('KINETIX_RENDER_PROJECTION_INVALID');
+  }
+  const bindingDigest = createHash('sha256').update(JSON.stringify(products.binding)).digest('hex');
+  return Object.freeze({
+    project: () => {
+      const snapshot = world.snapshot();
+      const transforms = [...world.deriveTransforms()].map(([handle, transform]) => ({ handle, transform }));
+      return products.presentation.records.map((record) => {
+        const sourceId = record.source?.kind === 'entity' ? record.source.id : null;
+        const handle = sourceId === null ? null : world.directHandle(sourceId);
+        const projected = handle === null ? null : transforms.find((entry) => entry.handle.index === handle.index)?.transform ?? null;
+        return {
+          kind: record.kind,
+          source: structuredClone(record.source),
+          component: structuredClone(record.component ?? null),
+          transform: structuredClone(projected),
+          worldTick: snapshot.tick,
+          bindingDigest,
+        };
+      });
+    },
+  });
+}

package/src/kinetix-runtime-adapter-utils.mjs

@@ -0,0 +1,168 @@
+import { assertKinetixRuntimeIdentity } from './kinetix-runtime-contract.mjs';
+import { kinetixSessionConfigDigest } from './kinetix-session-config.mjs';
+import { sha256Hex } from './shared/sha256.mjs';
+
+const encoder = new TextEncoder();
+const decoder = 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 tagged(value) {
+  if (typeof value === 'bigint') return { $kinetix: 'bigint', value: value.toString() };
+  if (value instanceof Map) {
+    const entries = [...value.entries()].map(([key, entry]) => [tagged(key), tagged(entry)]);
+    entries.sort((left, right) => JSON.stringify(left[0]).localeCompare(JSON.stringify(right[0])));
+    return { $kinetix: 'map', entries };
+  }
+  if (Array.isArray(value)) return value.map(tagged);
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, tagged(value[key])]));
+  }
+  if (value === null || typeof value === 'string' || typeof value === 'boolean'
+    || (typeof value === 'number' && Number.isFinite(value))) return value;
+  fail('KINETIX_RUNTIME_CHECKPOINT_INVALID');
+}
+
+function untagged(value) {
+  if (Array.isArray(value)) return value.map(untagged);
+  if (isPlainObject(value)) {
+    if (value.$kinetix === 'bigint' && typeof value.value === 'string') return BigInt(value.value);
+    if (value.$kinetix === 'map' && Array.isArray(value.entries)) {
+      return new Map(value.entries.map(([key, entry]) => [untagged(key), untagged(entry)]));
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, untagged(entry)]));
+  }
+  return value;
+}
+
+export function encodeRuntimeCheckpoint(value) {
+  return encoder.encode(JSON.stringify(tagged(value)));
+}
+
+export function decodeRuntimeCheckpoint(bytes) {
+  if (!ArrayBuffer.isView(bytes) || bytes.BYTES_PER_ELEMENT !== 1) {
+    fail('KINETIX_RUNTIME_CHECKPOINT_INVALID');
+  }
+  const normalized = Uint8Array.from(bytes);
+  try {
+    const decoded = untagged(JSON.parse(decoder.decode(normalized)));
+    const canonical = encodeRuntimeCheckpoint(decoded);
+    if (canonical.length !== normalized.length || canonical.some((byte, index) => byte !== normalized[index])) {
+      fail('KINETIX_RUNTIME_CHECKPOINT_INVALID');
+    }
+    return decoded;
+  } catch (error) {
+    if (error instanceof Error && error.message === 'KINETIX_RUNTIME_CHECKPOINT_INVALID') throw error;
+    fail('KINETIX_RUNTIME_CHECKPOINT_INVALID');
+  }
+}
+
+export function createInstalledRuntimeAdapter({
+  identity,
+  sessionConfigBytes,
+  captureState,
+  restoreState,
+  frameOf,
+  step,
+  checksumBytes = encodeRuntimeCheckpoint,
+  capturedStateIsDetached = false,
+  inspectState = (state) => state,
+}) {
+  assertKinetixRuntimeIdentity(identity);
+  const checkpoints = new WeakMap();
+
+  function makeCheckpoint(state) {
+    const copy = capturedStateIsDetached ? state : structuredClone(state);
+    const frame = frameOf(copy);
+    if (!Number.isSafeInteger(frame) || frame < 0) fail('KINETIX_RUNTIME_FRAME_MISMATCH');
+    const checkpoint = Object.freeze({ frame });
+    checkpoints.set(checkpoint, { frame, state: copy, serialized: null });
+    return checkpoint;
+  }
+
+  function data(checkpoint) {
+    const selected = isPlainObject(checkpoint) ? checkpoints.get(checkpoint) : undefined;
+    if (!selected) fail('KINETIX_RUNTIME_CHECKPOINT_INVALID');
+    return selected;
+  }
+
+  let currentCheckpoint = makeCheckpoint(captureState());
+  const runtime = {
+    identity: Object.freeze(structuredClone(identity)),
+    sessionConfigDigest: kinetixSessionConfigDigest(sessionConfigBytes),
+    get currentFrame() {
+      return data(currentCheckpoint).frame;
+    },
+    sessionConfigBytes() {
+      return sessionConfigBytes.slice();
+    },
+    capture() {
+      return makeCheckpoint(data(currentCheckpoint).state);
+    },
+    advance(requests) {
+      if (!Array.isArray(requests)) fail('KINETIX_RUNTIME_BATCH_INVALID');
+      let expected = this.currentFrame + 1;
+      for (const request of requests) {
+        if (!isPlainObject(request) || request.frame !== expected
+          || !Array.isArray(request.inputs) || !Array.isArray(request.commands)
+          || request.commands.length !== 0 || typeof request.checksum !== 'boolean') {
+          fail('KINETIX_RUNTIME_FRAME_MISMATCH');
+        }
+        expected += 1;
+      }
+      const starting = data(currentCheckpoint);
+      const results = [];
+      try {
+        for (const request of requests) {
+          step(request.inputs);
+          const state = captureState();
+          if (frameOf(state) !== request.frame) fail('KINETIX_RUNTIME_FRAME_MISMATCH');
+          currentCheckpoint = makeCheckpoint(state);
+          const result = { frame: request.frame, checkpoint: currentCheckpoint };
+          if (request.checksum) result.checksum = this.checksum(currentCheckpoint);
+          results.push(result);
+        }
+        return results;
+      } catch (error) {
+        restoreState(structuredClone(starting.state));
+        currentCheckpoint = makeCheckpoint(starting.state);
+        throw error;
+      }
+    },
+    restore(checkpoint) {
+      const selected = data(checkpoint);
+      restoreState(structuredClone(selected.state));
+      currentCheckpoint = makeCheckpoint(captureState());
+      if (this.currentFrame !== selected.frame) fail('KINETIX_RUNTIME_FRAME_MISMATCH');
+    },
+    inspect(checkpoint) {
+      return structuredClone(inspectState(data(checkpoint).state));
+    },
+    serializeCheckpoint(checkpoint) {
+      const selected = data(checkpoint);
+      selected.serialized ??= encodeRuntimeCheckpoint(selected.state);
+      return selected.serialized.slice();
+    },
+    hydrateCheckpoint(frame, bytes) {
+      const state = decodeRuntimeCheckpoint(bytes);
+      if (frameOf(state) !== frame) fail('KINETIX_RUNTIME_FRAME_MISMATCH');
+      return makeCheckpoint(state);
+    },
+    checksum(checkpoint) {
+      return sha256Hex(checksumBytes(data(checkpoint).state));
+    },
+    wireChecksum(checkpoint) {
+      return sha256Hex(checksumBytes(data(checkpoint).state));
+    },
+    release(checkpoint) {
+      if (checkpoint !== currentCheckpoint) checkpoints.delete(checkpoint);
+    },
+  };
+  return Object.freeze(runtime);
+}

package/src/kinetix-runtime-contract.mjs

@@ -0,0 +1,54 @@
+export const kinetixRuntimeAbiVersion = 1;
+
+const runtimeMethods = [
+  'sessionConfigBytes',
+  'capture',
+  'advance',
+  'restore',
+  'inspect',
+  'serializeCheckpoint',
+  'hydrateCheckpoint',
+  'checksum',
+  'wireChecksum',
+  'release',
+];
+
+const identityStringFields = [
+  'inputSchemaId',
+  'stateSchemaId',
+  'deterministicVersion',
+  'engineIdentityHash',
+];
+
+const supportedTickRates = [10, 20, 30, 60];
+
+export function assertKinetixRuntime(runtime) {
+  if (
+    runtime === null
+    || typeof runtime !== 'object'
+    || !Number.isSafeInteger(runtime.currentFrame)
+    || runtime.currentFrame < 0
+    || typeof runtime.sessionConfigDigest !== 'string'
+    || runtime.sessionConfigDigest.length !== 64
+    || runtimeMethods.some((name) => typeof runtime[name] !== 'function')
+  ) {
+    throw new Error('KINETIX_RUNTIME_INVALID');
+  }
+  assertKinetixRuntimeIdentity(runtime.identity);
+  return runtime;
+}
+
+export function assertKinetixRuntimeIdentity(identity) {
+  if (
+    identity === null
+    || typeof identity !== 'object'
+    || identity.abiVersion !== kinetixRuntimeAbiVersion
+    || !supportedTickRates.includes(identity.tickRate)
+    || identityStringFields.some(
+      (key) => typeof identity[key] !== 'string' || identity[key].length === 0,
+    )
+  ) {
+    throw new Error('KINETIX_RUNTIME_IDENTITY_INVALID');
+  }
+  return identity;
+}

package/src/kinetix-session-config.mjs

@@ -0,0 +1,170 @@
+import { sha256Hex } from './shared/sha256.mjs';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+const magic = encoder.encode('KSCFG001');
+const digestDomain = encoder.encode('rundot.kinetix.session-config.v1\0');
+const schemaKeys = new Set(['id', 'version', 'maxBytes', 'fields']);
+const fieldKeys = new Set(['type', 'min', 'max', 'maxBytes', 'values', 'required']);
+
+function fail(code) {
+  throw new Error(code);
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function concatBytes(chunks) {
+  const output = new Uint8Array(chunks.reduce((length, chunk) => length + chunk.length, 0));
+  let offset = 0;
+  for (const chunk of chunks) {
+    output.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return output;
+}
+
+function u32(value) {
+  const bytes = new Uint8Array(4);
+  new DataView(bytes.buffer).setUint32(0, value, true);
+  return bytes;
+}
+
+function readU32(bytes, offset) {
+  if (offset + 4 > bytes.length) fail('KINETIX_SESSION_CONFIG_INVALID');
+  return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(offset, true);
+}
+
+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;
+}
+
+export function normalizeKinetixSessionConfigSchema(schema) {
+  if (!isPlainObject(schema)
+    || Object.keys(schema).some((key) => !schemaKeys.has(key))
+    || typeof schema.id !== 'string'
+    || schema.id.length === 0
+    || !Number.isSafeInteger(schema.version)
+    || schema.version < 1
+    || !Number.isSafeInteger(schema.maxBytes)
+    || schema.maxBytes < 32
+    || !isPlainObject(schema.fields)) {
+    fail('KINETIX_SESSION_SCHEMA_INVALID');
+  }
+  const fields = {};
+  for (const name of Object.keys(schema.fields).sort()) {
+    const descriptor = schema.fields[name];
+    if (!/^[A-Za-z][A-Za-z0-9_]*$/u.test(name)
+      || !isPlainObject(descriptor)
+      || Object.keys(descriptor).some((key) => !fieldKeys.has(key))
+      || !['string', 'integer', 'boolean', 'enum'].includes(descriptor.type)
+      || (descriptor.required !== undefined && typeof descriptor.required !== 'boolean')) {
+      fail('KINETIX_SESSION_SCHEMA_INVALID');
+    }
+    if (descriptor.type === 'string'
+      && (!Number.isSafeInteger(descriptor.maxBytes) || descriptor.maxBytes < 0)) {
+      fail('KINETIX_SESSION_SCHEMA_INVALID');
+    }
+    if (descriptor.type === 'integer'
+      && (!Number.isSafeInteger(descriptor.min) || !Number.isSafeInteger(descriptor.max)
+        || descriptor.min > descriptor.max)) {
+      fail('KINETIX_SESSION_SCHEMA_INVALID');
+    }
+    if (descriptor.type === 'enum'
+      && (!Array.isArray(descriptor.values) || descriptor.values.length === 0
+        || descriptor.values.some((entry) => typeof entry !== 'string')
+        || new Set(descriptor.values).size !== descriptor.values.length
+        || [...descriptor.values].sort().some((entry, index) => entry !== descriptor.values[index]))) {
+      fail('KINETIX_SESSION_SCHEMA_INVALID');
+    }
+    fields[name] = canonicalize(descriptor);
+  }
+  return Object.freeze({ id: schema.id, version: schema.version, maxBytes: schema.maxBytes, fields: Object.freeze(fields) });
+}
+
+function validateValue(schema, value) {
+  if (!isPlainObject(value)) fail('KINETIX_SESSION_CONFIG_VALUE_INVALID');
+  if (Object.keys(value).some((key) => !Object.hasOwn(schema.fields, key))) {
+    fail('KINETIX_SESSION_CONFIG_FIELD_UNKNOWN');
+  }
+  const output = {};
+  for (const [name, descriptor] of Object.entries(schema.fields)) {
+    const entry = value[name];
+    if (entry === undefined && descriptor.required === false) continue;
+    let valid = true;
+    if (descriptor.type === 'string') valid = typeof entry === 'string' && encoder.encode(entry).length <= descriptor.maxBytes;
+    if (descriptor.type === 'integer') valid = Number.isSafeInteger(entry) && entry >= descriptor.min && entry <= descriptor.max;
+    if (descriptor.type === 'boolean') valid = typeof entry === 'boolean';
+    if (descriptor.type === 'enum') valid = typeof entry === 'string' && descriptor.values.includes(entry);
+    if (!valid) {
+      if (name === 'playerCount' || name === 'humanCount') fail('KINETIX_SESSION_CONFIG_PLAYER_COUNT_INVALID');
+      fail('KINETIX_SESSION_CONFIG_FIELD_INVALID');
+    }
+    output[name] = entry;
+  }
+  if (Number.isSafeInteger(output.playerCount)) {
+    if (output.playerCount < 1
+      || (Number.isSafeInteger(output.humanCount) && (output.humanCount < 0 || output.humanCount > output.playerCount))) {
+      fail('KINETIX_SESSION_CONFIG_PLAYER_COUNT_INVALID');
+    }
+  }
+  return canonicalize(output);
+}
+
+export function encodeKinetixSessionConfig(inputSchema, value) {
+  const schema = normalizeKinetixSessionConfigSchema(inputSchema);
+  const canonicalValue = validateValue(schema, value);
+  const schemaId = encoder.encode(schema.id);
+  const payload = encoder.encode(JSON.stringify(canonicalValue));
+  const bytes = concatBytes([magic, u32(schemaId.length), schemaId, u32(schema.version), u32(payload.length), payload]);
+  if (bytes.length > schema.maxBytes) fail('KINETIX_SESSION_CONFIG_SIZE_LIMIT');
+  return bytes;
+}
+
+export function decodeKinetixSessionConfig(inputSchema, bytes) {
+  const schema = normalizeKinetixSessionConfigSchema(inputSchema);
+  if (!(bytes instanceof Uint8Array) || bytes.length > schema.maxBytes || bytes.length < magic.length + 12
+    || magic.some((byte, index) => bytes[index] !== byte)) {
+    fail('KINETIX_SESSION_CONFIG_INVALID');
+  }
+  let offset = magic.length;
+  const schemaIdLength = readU32(bytes, offset);
+  offset += 4;
+  if (offset + schemaIdLength + 8 > bytes.length) fail('KINETIX_SESSION_CONFIG_INVALID');
+  let schemaId;
+  try {
+    schemaId = decoder.decode(bytes.subarray(offset, offset + schemaIdLength));
+  } catch {
+    fail('KINETIX_SESSION_CONFIG_INVALID');
+  }
+  offset += schemaIdLength;
+  const version = readU32(bytes, offset);
+  offset += 4;
+  if (schemaId !== schema.id || version !== schema.version) fail('KINETIX_SESSION_CONFIG_SCHEMA_MISMATCH');
+  const payloadLength = readU32(bytes, offset);
+  offset += 4;
+  if (offset + payloadLength !== bytes.length) fail('KINETIX_SESSION_CONFIG_INVALID');
+  let value;
+  try {
+    value = JSON.parse(decoder.decode(bytes.subarray(offset)));
+  } catch {
+    fail('KINETIX_SESSION_CONFIG_INVALID');
+  }
+  const validated = validateValue(schema, value);
+  const canonical = encodeKinetixSessionConfig(schema, validated);
+  if (canonical.length !== bytes.length || canonical.some((byte, index) => byte !== bytes[index])) {
+    fail('KINETIX_SESSION_CONFIG_NONCANONICAL');
+  }
+  return structuredClone(validated);
+}
+
+export function kinetixSessionConfigDigest(bytes) {
+  if (!(bytes instanceof Uint8Array)) fail('KINETIX_SESSION_CONFIG_INVALID');
+  return sha256Hex(concatBytes([digestDomain, bytes]));
+}

package/src/kinetix-source-snapshot.mjs

@@ -0,0 +1,24 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+export function kinetixCanonicalSourceDigest(sourceRoot) {
+  const hash = createHash('sha256');
+  function visit(directory) {
+    for (const name of readdirSync(directory).sort()) {
+      const path = join(directory, name);
+      const relativePath = relative(sourceRoot, path).split(sep).join('/');
+      const stats = statSync(path);
+      if (stats.isDirectory()) {
+        if (name !== '.git' && name !== 'node_modules' && name !== 'dist' && name !== 'build') visit(path);
+      } else if (!relativePath.endsWith('.product.generated.json')) {
+        hash.update(relativePath);
+        hash.update('\0');
+        hash.update(readFileSync(path));
+        hash.update('\0');
+      }
+    }
+  }
+  visit(sourceRoot);
+  return hash.digest('hex');
+}