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

package/src/kinetix-project-compiler.mjs

@@ -0,0 +1,1017 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import ts from 'typescript';
+import { kinetixCanonicalSourceDigest } from './kinetix-source-snapshot.mjs';
+
+import {
+  installedSystemFamiliesForProfile,
+  kinetixRuntimeContractForProfile,
+  kinetixInstalledSourceSignatures,
+} from './kinetix-installed-systems.mjs';
+
+const authoritativeDirectoryNames = new Set(['engine', 'sim', 'simulation']);
+const assignmentOperators = new Set([
+  ts.SyntaxKind.EqualsToken,
+  ts.SyntaxKind.PlusEqualsToken,
+  ts.SyntaxKind.MinusEqualsToken,
+  ts.SyntaxKind.AsteriskEqualsToken,
+  ts.SyntaxKind.SlashEqualsToken,
+]);
+
+function git(projectRoot, args, encoding = 'utf8') {
+  return spawnSync('git', ['-C', projectRoot, ...args], {
+    encoding,
+    maxBuffer: 1 << 29,
+  });
+}
+
+function diagnostic(code, file, line, column, message, details = {}) {
+  return { code, file, line, column, message, ...details };
+}
+
+function sourceFilesUnder(root) {
+  const files = [];
+  function visit(directory) {
+    for (const name of readdirSync(directory).sort()) {
+      const path = join(directory, name);
+      const stats = statSync(path);
+      if (stats.isDirectory()) {
+        if (name !== 'node_modules' && name !== '.git' && name !== 'dist' && name !== 'build') {
+          visit(path);
+        }
+      } else if (/\.(?:ts|tsx)$/u.test(name) && !/\.(?:test|spec)\.(?:ts|tsx)$/u.test(name)) {
+        files.push(path);
+      }
+    }
+  }
+  visit(root);
+  return files;
+}
+
+function isAuthoritativeFile(snapshotRoot, filePath) {
+  const segments = relative(snapshotRoot, filePath).split(sep);
+  return segments.some((segment) => authoritativeDirectoryNames.has(segment));
+}
+
+function containsStateMutation(node) {
+  let found = false;
+  function visit(current) {
+    if (found || current === undefined) return;
+    if (Array.isArray(current)) {
+      current.forEach(visit);
+      return;
+    }
+    if (typeof current.kind !== 'number') return;
+    if (ts.isBinaryExpression(current) && assignmentOperators.has(current.operatorToken.kind)
+      && (ts.isPropertyAccessExpression(current.left) || ts.isElementAccessExpression(current.left))) {
+      found = true;
+      return;
+    }
+    ts.forEachChild(current, visit);
+  }
+  visit(node);
+  return found;
+}
+
+function sourceOwnsSerializableState(sourceFile) {
+  let serializes = false;
+  let ticks = false;
+  function visit(node) {
+    if (ts.isMethodDeclaration(node) && ts.isIdentifier(node.name)) {
+      if (node.name.text === 'serialize') serializes = true;
+      if (node.name.text === 'tick') ticks = true;
+    }
+    if (ts.isFunctionDeclaration(node) && node.name?.text === 'step') ticks = true;
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === 'step') ticks = true;
+    if (!serializes || !ticks) ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return serializes || ticks;
+}
+
+function isNonAuthoritativeMember(member) {
+  return member === 'hydrate'
+    || member === 'serialize'
+    || member === 'snapshot'
+    || member === 'testHelpers'
+    || member?.startsWith('render') === true
+    || member?.startsWith('captureRender') === true;
+}
+
+function descendantCallNames(node) {
+  const names = new Set();
+  function visit(current) {
+    if (ts.isCallExpression(current)) {
+      if (ts.isIdentifier(current.expression)) names.add(current.expression.text);
+      if (ts.isPropertyAccessExpression(current.expression)) names.add(current.expression.name.text);
+    }
+    ts.forEachChild(current, visit);
+  }
+  visit(node);
+  return names;
+}
+
+// C2: this predicate must stay free of game symbols. A state-authority boundary is
+// recognized structurally — a branch that mutates nothing but the authority fields
+// themselves is engine plumbing, not gameplay behavior — never by naming a game's
+// authority-advance function.
+function isStateAuthorityBoundary(node, sourceFile) {
+  const authorityFields = new Set(['authoritativeState', 'stateAuthorityEnabled']);
+  const roots = mutatedFieldNames(node.thenStatement, sourceFile).map((field) => (
+    field.split(/[.\[]/u, 1)[0]
+  ));
+  return roots.length > 0 && roots.every((root) => authorityFields.has(root));
+}
+
+function assignedElementRoots(node) {
+  const roots = new Set();
+  function visit(current) {
+    if (ts.isBinaryExpression(current) && assignmentOperators.has(current.operatorToken.kind)
+      && ts.isElementAccessExpression(current.left)) {
+      let expression = current.left.expression;
+      while (ts.isPropertyAccessExpression(expression) || ts.isElementAccessExpression(expression)) {
+        expression = expression.expression;
+      }
+      if (ts.isIdentifier(expression)) roots.add(expression.text);
+    }
+    ts.forEachChild(current, visit);
+  }
+  visit(node);
+  return roots;
+}
+
+function assignedIdentifiers(node) {
+  const identifiers = new Set();
+  function visit(current) {
+    if (ts.isBinaryExpression(current) && assignmentOperators.has(current.operatorToken.kind)
+      && ts.isIdentifier(current.left)) identifiers.add(current.left.text);
+    ts.forEachChild(current, visit);
+  }
+  visit(node);
+  return identifiers;
+}
+
+function mutatedFieldNames(node, sourceFile) {
+  const fields = new Set();
+  function visit(current) {
+    if (ts.isBinaryExpression(current) && assignmentOperators.has(current.operatorToken.kind)
+      && (ts.isPropertyAccessExpression(current.left) || ts.isElementAccessExpression(current.left))) {
+      fields.add(current.left.getText(sourceFile).replace(/^this\./u, ''));
+    }
+    ts.forEachChild(current, visit);
+  }
+  visit(node);
+  return [...fields].sort();
+}
+
+function matchedFixedConditionalFamily(node) {
+  const calls = descendantCallNames(node);
+  const elementRoots = assignedElementRoots(node);
+  const identifiers = assignedIdentifiers(node);
+  if (calls.has('stepVehicle')
+    && ['yawTurns', 'speed', 'drifting', 'carVX', 'carVZ'].every((name) => elementRoots.has(name))) {
+    return 'vehicle-drive-body-build';
+  }
+  if (calls.has('stepLap')
+    && ['lap', 'cellsVisited', 'finishFrame', 'lapProj'].every((name) => elementRoots.has(name))) {
+    return 'vehicle-lap-finish';
+  }
+  if (calls.has('round')
+    && ['carX', 'carZ', 'carVX', 'carVZ'].every((name) => elementRoots.has(name))) {
+    return 'vehicle-physics-step';
+  }
+  const transitionWrites = ['phase', 'phaseStartFrame', 'lobbyDeadlineFrame'];
+  if (transitionWrites.some((name) => identifiers.has(name))
+    && (calls.has('snapToGrid') || calls.has('deriveLobbySpawns') || identifiers.has('phase'))) {
+    return 'match-phase-transition';
+  }
+  return null;
+}
+
+function sourceSemanticFacts(sourceFile) {
+  const identifiers = new Set();
+  const calls = new Set();
+  function visit(node) {
+    if (ts.isIdentifier(node)) identifiers.add(node.text);
+    if (ts.isCallExpression(node)) {
+      if (ts.isIdentifier(node.expression)) calls.add(node.expression.text);
+      if (ts.isPropertyAccessExpression(node.expression)) calls.add(node.expression.name.text);
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return { identifiers, calls };
+}
+
+function matchedF64SourceFamily(sourceFile) {
+  const { identifiers, calls } = sourceSemanticFacts(sourceFile);
+  const hasIdentifiers = (...names) => names.every((name) => identifiers.has(name));
+  if (calls.has('processGateCollisions') && calls.has('consumeBombAndDetonateAt')) {
+    return ['phase-spawn-score-policy', ['processGateCollisions', 'consumeBombAndDetonateAt']];
+  }
+  if (hasIdentifiers('_bombsEarned', '_livesEarned')) {
+    return ['consumable-charge-economy', ['_bombsEarned', '_livesEarned']];
+  }
+  if (hasIdentifiers('_peak', '_decaying', '_decayElapsed')) {
+    return ['score-multiplier-decay', ['_peak', '_decaying', '_decayElapsed']];
+  }
+  if (hasIdentifiers('dodgeCooldown', 'dodgeTimer', 'dodgeDir')) {
+    return ['staged-axis-runner', ['dodgeCooldown', 'dodgeTimer', 'dodgeDir']];
+  }
+  if (hasIdentifiers('pullRadiusPx', 'pullStrength', 'ingestCount') && calls.has('releaseSpawns')) {
+    return ['gravity-well-state-machine', ['pullRadiusPx', 'pullStrength', 'releaseSpawns']];
+  }
+  if (hasIdentifiers('bodySegments', 'trail', 'heading', 'onBodyBulletHit')) {
+    return ['segmented-follow-chain', ['bodySegments', 'trail', 'onBodyBulletHit']];
+  }
+  if (hasIdentifiers('arcSign', 'LIFETIME', 'curveStrength')) {
+    return ['spawn-pellet-growth', ['arcSign', 'LIFETIME', 'curveStrength']];
+  }
+  if (calls.has('gaussian') && hasIdentifiers('rerollTimer', 'REROLL_SECONDS')) {
+    return ['bounded-random-steering', ['gaussian', 'rerollTimer', 'REROLL_SECONDS']];
+  }
+  if (hasIdentifiers('rerollTimer', 'REROLL_SECONDS') && calls.has('rng')) {
+    return ['boundary-crossing-oscillator', ['rng', 'rerollTimer', 'REROLL_SECONDS']];
+  }
+  if (hasIdentifiers('ACCEL_START', 'ACCEL_END', 'TOP_SPEED') && calls.has('hypot')) {
+    return ['target-seeking-drift', ['ACCEL_START', 'ACCEL_END', 'TOP_SPEED']];
+  }
+  if (hasIdentifiers('_fireCooldowns', '_bullets') && calls.has('releaseBullet')) {
+    return ['projectile-lifecycle-collision', ['_fireCooldowns', '_bullets', 'releaseBullet']];
+  }
+  if (hasIdentifiers('shield', 'heading', 'movementVector') && calls.has('atan2')) {
+    return ['axis-drive-fire-control', ['shield', 'heading', 'movementVector']];
+  }
+  if (hasIdentifiers('_sparks', 'fadeAge') && calls.has('releaseSpark')) {
+    return ['pickup-drift-lifecycle', ['_sparks', 'fadeAge', 'releaseSpark']];
+  }
+  return null;
+}
+
+const f64FamilyMutationRoots = new Map([
+  ['phase-spawn-score-policy', new Set([
+    '_deathAnimTimer', '_duration', '_status', 'b', 'ctx', 'e', 'gateSpawnTimer',
+    'pickup', 'previousShipPositions', 'sparkMagnetSurgeMultiplier', 'spawnSuppressionTimer',
+  ])],
+  ['consumable-charge-economy', new Set(['_bombs', '_bombsEarned', '_lives', '_livesEarned'])],
+  ['score-multiplier-decay', new Set(['_decaying', '_peak', '_value'])],
+  ['boundary-crossing-oscillator', new Set(['entity', 'rerollTimer'])],
+  ['staged-axis-runner', new Set(['dodgeCooldown', 'dodgeDir', 'dodgeTimer', 'entity'])],
+  ['target-seeking-drift', new Set(['entity'])],
+  ['gravity-well-state-machine', new Set(['bulletsAbsorbed', 'e', 'entity', 'ingestCount', 'phase'])],
+  ['segmented-follow-chain', new Set(['entity', 'heading', 's', 'seg', 'trail'])],
+  ['spawn-pellet-growth', new Set(['entity'])],
+  ['bounded-random-steering', new Set(['entity', 'rerollTimer'])],
+  ['projectile-lifecycle-collision', new Set(['_bullets', '_fireCooldowns', 'b', 'head', 'impact'])],
+  ['axis-drive-fire-control', new Set(['heading', 'position', 'shield'])],
+  ['pickup-drift-lifecycle', new Set(['_sparks', 's', 'spark'])],
+]);
+
+function f64FamilyMatchesBranch(sourceFamily, node, sourceFile) {
+  if (sourceFamily === null) return false;
+  const allowedRoots = f64FamilyMutationRoots.get(sourceFamily[0]);
+  if (allowedRoots === undefined) return false;
+  const roots = mutatedFieldNames(node.thenStatement, sourceFile).map((field) => (
+    field.split(/[.\[]/u, 1)[0]
+  ));
+  return roots.length > 0 && roots.every((root) => allowedRoots.has(root));
+}
+
+function classifyUnmatched(snapshotRoot, files, targetProfile, classifyInstalledBranches) {
+  const program = ts.createProgram(files, {
+    allowJs: false,
+    jsx: ts.JsxEmit.ReactJSX,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    noEmit: true,
+    skipLibCheck: true,
+    target: ts.ScriptTarget.ES2022,
+  });
+  const unmatched = [];
+  const coverage = [];
+  for (const sourceFile of program.getSourceFiles()) {
+    if (sourceFile.isDeclarationFile || !sourceFile.fileName.startsWith(snapshotRoot)
+      || !isAuthoritativeFile(snapshotRoot, sourceFile.fileName)
+      || !sourceOwnsSerializableState(sourceFile)) {
+      continue;
+    }
+    const f64SourceFamily = targetProfile === 'deterministic-f64' && classifyInstalledBranches
+      ? matchedF64SourceFamily(sourceFile)
+      : null;
+    function visit(node, enclosingMember = null) {
+      if (node === undefined) return;
+      if (Array.isArray(node)) {
+        node.forEach((child) => visit(child, enclosingMember));
+        return;
+      }
+      if (typeof node.kind !== 'number') return;
+      const member = (ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node))
+        && (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name))
+        ? node.name.text
+        : enclosingMember;
+      if (ts.isIfStatement(node) && containsStateMutation(node.thenStatement)
+        && !isNonAuthoritativeMember(member)
+        && !isStateAuthorityBoundary(node, sourceFile)) {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+        const matchedSystemId = targetProfile === 'fixed-1000-3d'
+          ? matchedFixedConditionalFamily(node)
+          : f64FamilyMatchesBranch(f64SourceFamily, node, sourceFile)
+            ? f64SourceFamily[0]
+            : null;
+        if (matchedSystemId !== null) {
+          const installedFamily = installedSystemFamiliesForProfile(targetProfile)
+            .find((family) => family.id === matchedSystemId);
+          coverage.push({
+            source: {
+              file: relative(snapshotRoot, sourceFile.fileName).split(sep).join('/'),
+              line: line + 1,
+              column: character + 1,
+              branch: true,
+            },
+            systemId: matchedSystemId,
+            phase: installedFamily.phase,
+            order: installedFamily.order,
+            match: targetProfile === 'deterministic-f64'
+              ? { kind: 'semantic-source-shape', evidence: f64SourceFamily[1] }
+              : { kind: 'conditional-family' },
+          });
+          ts.forEachChild(node, (child) => visit(child, member));
+          return;
+        }
+        unmatched.push(diagnostic(
+          'KINETIX_SOURCE_BEHAVIOR_UNSUPPORTED',
+          relative(snapshotRoot, sourceFile.fileName).split(sep).join('/'),
+          line + 1,
+          character + 1,
+          'Authoritative conditional state mutation does not match an installed system family.',
+          {
+            enclosingMember: member ?? '<module>',
+            mutatedFields: mutatedFieldNames(node.thenStatement, sourceFile),
+            descendantCalls: [...descendantCallNames(node)].sort(),
+          },
+        ));
+      }
+      ts.forEachChild(node, (child) => visit(child, member));
+    }
+    visit(sourceFile);
+  }
+  unmatched.sort((left, right) => left.file.localeCompare(right.file)
+    || left.line - right.line || left.column - right.column);
+  coverage.sort((left, right) => left.source.file.localeCompare(right.source.file)
+    || left.source.line - right.source.line || left.source.column - right.source.column);
+  return { unmatched, coverage };
+}
+
+function calledName(expression, sourceFile) {
+  if (ts.isIdentifier(expression)) return { call: expression.text, receiver: null };
+  if (ts.isPropertyAccessExpression(expression)) {
+    return { call: expression.name.text, receiver: expression.expression.getText(sourceFile) };
+  }
+  return { call: null, receiver: null };
+}
+
+function collectCalls(snapshotRoot, files) {
+  const program = ts.createProgram(files, {
+    allowJs: false,
+    jsx: ts.JsxEmit.ReactJSX,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    noEmit: true,
+    skipLibCheck: true,
+    target: ts.ScriptTarget.ES2022,
+  });
+  const calls = [];
+  for (const sourceFile of program.getSourceFiles()) {
+    if (sourceFile.isDeclarationFile || !sourceFile.fileName.startsWith(snapshotRoot)
+      || !isAuthoritativeFile(snapshotRoot, sourceFile.fileName)) continue;
+    function visit(node) {
+      if (node === undefined) return;
+      if (Array.isArray(node)) {
+        node.forEach(visit);
+        return;
+      }
+      if (typeof node.kind !== 'number') return;
+      if (ts.isCallExpression(node)) {
+        const name = calledName(node.expression, sourceFile);
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+        calls.push({
+          ...name,
+          arguments: node.arguments.map((argument) => ts.isStringLiteral(argument) ? argument.text : null),
+          source: {
+            file: relative(snapshotRoot, sourceFile.fileName).split(sep).join('/'),
+            line: line + 1,
+            column: character + 1,
+          },
+        });
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+  }
+  return calls;
+}
+
+function matchSignature(calls, signature) {
+  const matches = calls.filter((call) => call.call === signature.call
+    && (signature.receiver === undefined || call.receiver === signature.receiver
+      || call.receiver?.endsWith(`.${signature.receiver}`))
+    && (signature.argument === undefined || call.arguments.includes(signature.argument)));
+  return matches[signature.occurrence ?? 0] ?? null;
+}
+
+function semanticCoverageFor(snapshotRoot, files, targetProfile) {
+  const calls = collectCalls(snapshotRoot, files);
+  return installedSystemFamiliesForProfile(targetProfile).flatMap((installedFamily) => {
+    const signatures = kinetixInstalledSourceSignatures[installedFamily.id] ?? [];
+    const matched = signatures.map((signature) => matchSignature(calls, signature)).find(Boolean);
+    return matched ? [{
+      source: matched.source,
+      systemId: installedFamily.id,
+      phase: installedFamily.phase,
+      order: installedFamily.order,
+    }] : [];
+  });
+}
+
+function sourceDefiningFunction(program, functionName) {
+  for (const sourceFile of program.getSourceFiles()) {
+    if (sourceFile.isDeclarationFile) continue;
+    let found = false;
+    function visit(node) {
+      if (ts.isFunctionDeclaration(node) && node.name?.text === functionName) found = true;
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)
+        && node.name.text === functionName
+        && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) found = true;
+      if (!found) ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    if (found) return sourceFile;
+  }
+  throw new Error(`KINETIX_INSTALLED_SIGNATURE_MISSING ${functionName}`);
+}
+
+function variableInitializer(sourceFile, name) {
+  let initializer = null;
+  function visit(node) {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === name) {
+      initializer = node.initializer ?? null;
+      return;
+    }
+    if (initializer === null) ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  if (initializer === null) throw new Error(`KINETIX_INSTALLED_PARAMETER_MISSING ${name}`);
+  return initializer;
+}
+
+function staticValue(expression, checker, locals = new Map(), stack = new Set()) {
+  if (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
+    || ts.isTypeAssertionExpression(expression) || ts.isNonNullExpression(expression)) {
+    return staticValue(expression.expression, checker, locals, stack);
+  }
+  if (ts.isNumericLiteral(expression)) return Number(expression.text.replaceAll('_', ''));
+  if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) return expression.text;
+  if (expression.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (expression.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (expression.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (ts.isPrefixUnaryExpression(expression)) {
+    const value = staticValue(expression.operand, checker, locals, stack);
+    if (expression.operator === ts.SyntaxKind.MinusToken) return -value;
+    if (expression.operator === ts.SyntaxKind.PlusToken) return +value;
+    throw new Error('KINETIX_STATIC_EXPRESSION_UNSUPPORTED prefix');
+  }
+  if (ts.isIdentifier(expression)) {
+    if (locals.has(expression.text)) return locals.get(expression.text);
+    let symbol = checker.getSymbolAtLocation(expression);
+    if (symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.valueDeclaration ?? symbol?.declarations?.find((candidate) => ts.isVariableDeclaration(candidate));
+    if (!ts.isVariableDeclaration(declaration) || declaration.initializer === undefined) {
+      throw new Error(`KINETIX_STATIC_IDENTIFIER_UNRESOLVED ${expression.text}`);
+    }
+    if (stack.has(declaration)) throw new Error(`KINETIX_STATIC_EXPRESSION_CYCLE ${expression.text}`);
+    stack.add(declaration);
+    const value = staticValue(declaration.initializer, checker, locals, stack);
+    stack.delete(declaration);
+    return value;
+  }
+  if (ts.isArrayLiteralExpression(expression)) {
+    return expression.elements.map((element) => staticValue(element, checker, locals, stack));
+  }
+  if (ts.isObjectLiteralExpression(expression)) {
+    const value = {};
+    for (const property of expression.properties) {
+      if (!ts.isPropertyAssignment(property)) throw new Error('KINETIX_STATIC_OBJECT_PROPERTY_UNSUPPORTED');
+      const name = ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)
+        || ts.isNumericLiteral(property.name)
+        ? property.name.text
+        : String(staticValue(property.name.expression, checker, locals, stack));
+      value[name] = staticValue(property.initializer, checker, locals, stack);
+    }
+    return value;
+  }
+  if (ts.isPropertyAccessExpression(expression)) {
+    const object = staticValue(expression.expression, checker, locals, stack);
+    return object?.[expression.name.text];
+  }
+  if (ts.isElementAccessExpression(expression)) {
+    const object = staticValue(expression.expression, checker, locals, stack);
+    const key = staticValue(expression.argumentExpression, checker, locals, stack);
+    return object?.[key];
+  }
+  if (ts.isBinaryExpression(expression)) {
+    const left = staticValue(expression.left, checker, locals, stack);
+    if (expression.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken) {
+      return left ?? staticValue(expression.right, checker, locals, stack);
+    }
+    const right = staticValue(expression.right, checker, locals, stack);
+    const operations = new Map([
+      [ts.SyntaxKind.PlusToken, () => left + right],
+      [ts.SyntaxKind.MinusToken, () => left - right],
+      [ts.SyntaxKind.AsteriskToken, () => left * right],
+      [ts.SyntaxKind.SlashToken, () => left / right],
+      [ts.SyntaxKind.PercentToken, () => left % right],
+      [ts.SyntaxKind.LessThanToken, () => left < right],
+      [ts.SyntaxKind.GreaterThanToken, () => left > right],
+      [ts.SyntaxKind.EqualsEqualsEqualsToken, () => left === right],
+    ]);
+    const operation = operations.get(expression.operatorToken.kind);
+    if (operation === undefined) throw new Error(`KINETIX_STATIC_BINARY_UNSUPPORTED ${expression.operatorToken.kind}`);
+    return operation();
+  }
+  if (ts.isCallExpression(expression)) {
+    const arguments_ = expression.arguments.map((argument) => staticValue(argument, checker, locals, stack));
+    if (ts.isPropertyAccessExpression(expression.expression)
+      && ts.isIdentifier(expression.expression.expression)
+      && expression.expression.expression.text === 'Math') {
+      const operation = Math[expression.expression.name.text];
+      if (!['trunc', 'round', 'floor', 'ceil', 'min', 'max'].includes(expression.expression.name.text)) {
+        throw new Error(`KINETIX_STATIC_MATH_UNSUPPORTED ${expression.expression.name.text}`);
+      }
+      return operation(...arguments_);
+    }
+    let symbol = checker.getSymbolAtLocation(expression.expression);
+    if (symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.valueDeclaration;
+    const callable = ts.isFunctionDeclaration(declaration)
+      ? declaration
+      : ts.isVariableDeclaration(declaration)
+        && (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer))
+        ? declaration.initializer
+        : null;
+    if (callable === null || callable.body === undefined) throw new Error('KINETIX_STATIC_CALL_UNRESOLVED');
+    const callLocals = new Map(locals);
+    callable.parameters.forEach((parameter, index) => {
+      if (!ts.isIdentifier(parameter.name)) throw new Error('KINETIX_STATIC_PARAMETER_UNSUPPORTED');
+      callLocals.set(parameter.name.text, arguments_[index]);
+    });
+    if (!ts.isBlock(callable.body)) return staticValue(callable.body, checker, callLocals, stack);
+    const returned = callable.body.statements.find((statement) => ts.isReturnStatement(statement));
+    if (!ts.isReturnStatement(returned) || returned.expression === undefined) {
+      throw new Error('KINETIX_STATIC_FUNCTION_BODY_UNSUPPORTED');
+    }
+    return staticValue(returned.expression, checker, callLocals, stack);
+  }
+  throw new Error(`KINETIX_STATIC_EXPRESSION_UNSUPPORTED ${expression.kind}`);
+}
+
+function constantValue(sourceFile, name, checker) {
+  return staticValue(variableInitializer(sourceFile, name), checker);
+}
+
+function encodeGridCells(cells) {
+  const bytes = Buffer.alloc(cells.length * 3);
+  cells.forEach((cell, index) => {
+    bytes[index * 3] = cell.gridX + 128;
+    bytes[index * 3 + 1] = cell.gridZ + 128;
+    bytes[index * 3 + 2] = (cell.typeId << 2) | cell.orientation;
+  });
+  return bytes.toString('base64url');
+}
+
+function encodeFixedProfileBinary(pack, cells) {
+  const chunks = [Buffer.from('KFXDATA1')];
+  const i64 = (value) => {
+    const bytes = Buffer.alloc(8);
+    bytes.writeBigInt64LE(BigInt(value));
+    chunks.push(bytes);
+  };
+  const string = (value) => {
+    const bytes = Buffer.from(value);
+    const length = Buffer.alloc(4);
+    length.writeUInt32LE(bytes.length);
+    chunks.push(length, bytes);
+  };
+  const array = (values) => {
+    const length = Buffer.alloc(4);
+    length.writeUInt32LE(values.length);
+    chunks.push(length);
+    values.forEach(i64);
+  };
+  string(pack.grid.encoded);
+  [
+    pack.scale, pack.slotCount, pack.humanCount,
+    pack.initialPhase === 'lobby' ? 0 : pack.initialPhase === 'countdown' ? 1 : 2,
+    pack.grid.cellRaw, pack.grid.gridScale, pack.grid.finishTypeId,
+    pack.components.arcadeDriftVehicle.maxSpeed,
+    pack.components.arcadeDriftVehicle.accelRate,
+    pack.components.arcadeDriftVehicle.brakeRate,
+    pack.components.arcadeDriftVehicle.maxReverse,
+    pack.components.arcadeDriftVehicle.turnPerTick,
+    pack.components.arcadeDriftVehicle.gripMin,
+    pack.components.arcadeDriftVehicle.slipSpeed,
+    pack.components.arcadeDriftVehicle.tractionSlow,
+    pack.components.arcadeDriftVehicle.tractionFast,
+    pack.components.arcadeDriftVehicle.driftSteer,
+    pack.components.arcadeDriftVehicle.stopDeadband,
+    pack.components.gridTrackCollider.wallHalfThick,
+    pack.components.gridTrackCollider.wallLateral,
+    pack.components.gridTrackCollider.wallY,
+    pack.components.gridTrackCollider.wallHalfHeightRaw,
+    pack.components.gridTrackCollider.halfPiFixed,
+    pack.components.gridTrackCollider.twoPiFixed,
+    pack.components.gridTrackCollider.outerArcSegments,
+    pack.components.gridTrackCollider.innerArcSegments,
+    pack.components.gridTrackCollider.layer,
+    pack.components.gridTrackCollider.mask,
+    pack.components.arenaBounds.halfUnits,
+    pack.components.arenaBounds.wallThick,
+    pack.components.arenaBounds.wallHalfHeight,
+    pack.components.arenaBounds.wallY,
+    pack.components.arenaBounds.centerX,
+    pack.components.arenaBounds.centerZ,
+    pack.components.scatterSpawn.cols,
+    pack.components.scatterSpawn.spacing,
+    pack.components.gridSpawn.lateral,
+    pack.components.gridSpawn.rowBack,
+    pack.components.gridSpawn.minSlots,
+    pack.components.gridSpawn.maxSlots,
+    pack.components.waypointRingDriver.lookahead,
+    pack.components.waypointRingDriver.steerGain,
+    pack.components.waypointRingDriver.sharpTurnThrottle,
+    pack.components.lapProgress.totalLaps,
+    pack.components.lapProgress.maxRaceFrames,
+    pack.components.lapProgress.noTeleport,
+    pack.components.lapProgress.maxRequiredBits,
+    pack.components.matchPhaseMachine.lobbyInitialFrames,
+    pack.components.matchPhaseMachine.lobbyExtendFrames,
+    pack.components.matchPhaseMachine.lobbyMaxFrames,
+    pack.components.matchPhaseMachine.countdownFrames,
+    pack.components.matchPhaseMachine.resultsHoldFrames,
+    pack.components.matchPhaseMachine.maxSlotsAutoStart,
+    pack.components.physicsWriteback.bodyRadius,
+    pack.components.physicsWriteback.bodyY,
+    pack.components.physicsWriteback.layer,
+    pack.components.physicsWriteback.mask,
+  ].forEach(i64);
+  const cellCount = Buffer.alloc(4);
+  cellCount.writeUInt32LE(cells.length);
+  chunks.push(cellCount);
+  cells.forEach((cell) => [cell.gridX, cell.gridZ, cell.typeId, cell.orientation].forEach(i64));
+  array(pack.grid.cornerTypeIds);
+  array(pack.grid.passThroughTypeIds);
+  string(pack.components.gridTrackCollider.bodyIdPrefix);
+  string(pack.components.physicsWriteback.bodyIdPrefix);
+  const bodyIds = pack.components.arenaBounds.bodyIds;
+  const bodyIdCount = Buffer.alloc(4);
+  bodyIdCount.writeUInt32LE(bodyIds.length);
+  chunks.push(bodyIdCount);
+  bodyIds.forEach(string);
+  return Buffer.concat(chunks).toString('base64');
+}
+
+function extractFixedProfileData(snapshotRoot, files) {
+  const program = ts.createProgram(files, {
+    jsx: ts.JsxEmit.ReactJSX,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    noEmit: true,
+    skipLibCheck: true,
+    target: ts.ScriptTarget.ES2022,
+  });
+  const checker = program.getTypeChecker();
+  const stepSource = sourceDefiningFunction(program, 'step');
+  const vehicle = sourceDefiningFunction(program, 'stepVehicle');
+  const track = sourceDefiningFunction(program, 'cookWalls');
+  const arena = sourceDefiningFunction(program, 'cookArena');
+  const scatter = sourceDefiningFunction(program, 'deriveLobbySpawns');
+  const spawn = sourceDefiningFunction(program, 'deriveSpawns');
+  const bot = sourceDefiningFunction(program, 'botDrive');
+  const lap = sourceDefiningFunction(program, 'stepLap');
+  const phases = new Map();
+  for (const name of [
+    'LOBBY_INITIAL_FRAMES', 'LOBBY_EXTEND_FRAMES', 'LOBBY_MAX_FRAMES',
+    'COUNTDOWN_FRAMES', 'RESULTS_HOLD_FRAMES',
+  ]) {
+    const symbol = checker.resolveName(name, stepSource, ts.SymbolFlags.Value, false);
+    const declaration = symbol?.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol).valueDeclaration : symbol?.valueDeclaration;
+    if (!ts.isVariableDeclaration(declaration) || declaration.initializer === undefined) {
+      throw new Error(`KINETIX_INSTALLED_PARAMETER_MISSING ${name}`);
+    }
+    phases.set(name, staticValue(declaration.initializer, checker));
+  }
+  const one = constantValue(sourceDefiningFunction(program, 'fsin'), 'ONE', checker);
+  const pack = {
+    packVersion: 'rundot.kinetix-installed-profile-data.v1',
+    numericProfile: 'fixed-1000',
+    scale: one,
+    tickRate: 30,
+    grid: {
+      codec: 'cell-3byte-base64url',
+      cellRaw: constantValue(track, 'CELL_RAW', checker),
+      gridScale: constantValue(track, 'S', checker),
+      cornerTypeIds: [1],
+      passThroughTypeIds: [2],
+      finishTypeId: constantValue(spawn, 'FINISH_TYPE_ID', checker),
+    },
+    components: {
+      arcadeDriftVehicle: {
+        maxSpeed: constantValue(vehicle, 'MAX_SPEED', checker),
+        accelRate: constantValue(vehicle, 'ACCEL_RATE', checker),
+        brakeRate: constantValue(vehicle, 'BRAKE_RATE', checker),
+        maxReverse: constantValue(vehicle, 'MAX_REVERSE', checker),
+        turnPerTick: constantValue(vehicle, 'TURN_PER_TICK', checker),
+        gripMin: constantValue(vehicle, 'GRIP_MIN', checker),
+        slipSpeed: constantValue(vehicle, 'SLIP_SPEED', checker),
+        tractionSlow: constantValue(vehicle, 'TRACTION_SLOW', checker),
+        tractionFast: constantValue(vehicle, 'TRACTION_FAST', checker),
+        driftSteer: constantValue(vehicle, 'DRIFT_STEER', checker),
+        stopDeadband: 2,
+      },
+      gridTrackCollider: {
+        wallHalfThick: constantValue(track, 'WALL_HALF_THICK', checker),
+        wallLateral: constantValue(track, 'WALL_X', checker),
+        wallY: constantValue(track, 'WALL_Y', checker),
+        wallHalfHeightRaw: 1500,
+        halfPiFixed: constantValue(track, 'HALF_PI', checker),
+        twoPiFixed: constantValue(track, 'TWO_PI', checker),
+        outerArcSegments: constantValue(track, 'OUTER_SEG', checker),
+        innerArcSegments: constantValue(track, 'INNER_SEG', checker),
+        bodyIdPrefix: 'w', layer: 1, mask: 0xffff,
+      },
+      arenaBounds: {
+        halfUnits: constantValue(arena, 'ARENA_HALF', checker),
+        wallThick: constantValue(arena, 'WALL_THICK_F', checker),
+        wallHalfHeight: constantValue(arena, 'WALL_HALF_H_F', checker),
+        wallY: constantValue(arena, 'WALL_Y_F', checker),
+        centerX: constantValue(arena, 'ARENA_CX', checker),
+        centerZ: constantValue(arena, 'ARENA_CZ', checker),
+        bodyIds: ['a-n', 'a-s', 'a-w', 'a-e'], layer: 1, mask: 0xffff,
+      },
+      scatterSpawn: {
+        cols: constantValue(scatter, 'cols', checker),
+        spacing: constantValue(scatter, 'spacing', checker),
+      },
+      gridSpawn: {
+        lateral: constantValue(spawn, 'LATERAL', checker),
+        rowBack: constantValue(spawn, 'ROW_BACK', checker), minSlots: 1, maxSlots: 8,
+      },
+      waypointRingDriver: {
+        lookahead: constantValue(bot, 'LOOKAHEAD', checker),
+        steerGain: constantValue(bot, 'STEER_GAIN', checker),
+        sharpTurnThrottle: constantValue(bot, 'SHARP_TURN_THROTTLE', checker),
+      },
+      lapProgress: {
+        totalLaps: constantValue(lap, 'TOTAL_LAPS', checker),
+        maxRaceFrames: constantValue(lap, 'MAX_RACE_FRAMES', checker),
+        noTeleport: constantValue(lap, 'NO_TELEPORT', checker),
+        maxRequiredBits: constantValue(lap, 'MAX_REQUIRED_BITS', checker),
+      },
+      matchPhaseMachine: {
+        lobbyInitialFrames: phases.get('LOBBY_INITIAL_FRAMES'),
+        lobbyExtendFrames: phases.get('LOBBY_EXTEND_FRAMES'),
+        lobbyMaxFrames: phases.get('LOBBY_MAX_FRAMES'),
+        countdownFrames: phases.get('COUNTDOWN_FRAMES'),
+        resultsHoldFrames: phases.get('RESULTS_HOLD_FRAMES'),
+        maxSlotsAutoStart: constantValue(stepSource, 'MAX_PLAYERS', checker),
+      },
+      physicsWriteback: {
+        bodyRadius: constantValue(stepSource, 'CAR_RADIUS', checker),
+        bodyY: constantValue(stepSource, 'CAR_Y', checker),
+        bodyIdPrefix: 'car', layer: 1, mask: 0xffff, gravityY: 0,
+      },
+    },
+  };
+  return pack;
+}
+
+function extractF64ProfileData(snapshotRoot, files) {
+  const program = ts.createProgram(files, {
+    jsx: ts.JsxEmit.ReactJSX,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    noEmit: true,
+    skipLibCheck: true,
+    target: ts.ScriptTarget.ES2022,
+  });
+  const checker = program.getTypeChecker();
+  const parameters = [];
+  for (const sourceFile of program.getSourceFiles()) {
+    if (sourceFile.isDeclarationFile || !sourceFile.fileName.startsWith(snapshotRoot)
+      || !isAuthoritativeFile(snapshotRoot, sourceFile.fileName)) continue;
+    for (const statement of sourceFile.statements) {
+      if (!ts.isVariableStatement(statement)) continue;
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined) continue;
+        try {
+          const value = staticValue(declaration.initializer, checker);
+          JSON.stringify(value);
+          if (/(?:track|room|human|player|seed|initial.*mode)/iu.test(declaration.name.text)) continue;
+          parameters.push({
+            source: relative(snapshotRoot, sourceFile.fileName).split(sep).join('/'),
+            name: declaration.name.text,
+            value,
+          });
+        } catch {
+          // Runtime-only expressions are deliberately absent from data products.
+        }
+      }
+    }
+  }
+  parameters.sort((left, right) => left.source.localeCompare(right.source)
+    || left.name.localeCompare(right.name));
+  const parameterBytes = Buffer.from(JSON.stringify(parameters));
+  return {
+    packVersion: 'rundot.kinetix-installed-profile-data.v1',
+    numericProfile: 'deterministic-f64',
+    sourceParameterDigest: createHash('sha256').update(parameterBytes).digest('hex'),
+    parameters,
+  };
+}
+
+function envelopeFor(targetProfile, expectedCommit, archiveSha256, semanticCoverage, installedProfileData) {
+  const profile = targetProfile === 'deterministic-f64'
+    ? { id: 'deterministic-f64-2d', abi: 'deterministic-f64-2d.v1' }
+    : { id: 'fixed-1000-3d', abi: 'fixed-1000-3d.v1' };
+  return {
+    version: 'rundot.kinetix-envelope.v1',
+    compilerProvenance: {
+      compilerVersion: 'rundot.kinetix-project-compiler.v1',
+      targetProfile,
+      sourceSnapshot: { commit: expectedCommit, archiveSha256 },
+    },
+    semanticCoverage: semanticCoverage.map((entry) => ({
+      source: {
+        file: entry.source.file,
+        line: entry.source.line,
+        column: entry.source.column,
+      },
+      systemId: entry.systemId,
+      phase: entry.phase,
+      order: entry.order,
+    })),
+    sceneId: `compiled-${archiveSha256.slice(0, 16)}`,
+    sceneDependencies: [],
+    profiles: [profile],
+    assets: [],
+    budgets: {
+      maxDirectEntities: 1,
+      maxPrefabs: 1,
+      maxLocalEntitiesPerPrefab: 1,
+      maxComponents: 3,
+      maxLiveRuntimeEntities: 1,
+      maxSimulationRecords: 1,
+      maxPresentationRecords: 1,
+      maxBindingRecords: 1,
+      maxCommandsPerTick: 1,
+    },
+    prefabs: [],
+    entities: [{
+      id: 'runtime-root',
+      profile: profile.id,
+      lifecycle: 'static',
+      section: 0,
+      components: [
+        {
+          id: 'state',
+          type: 'KinetixRuntimeState',
+          schemaVersion: 1,
+          domain: 'simulation',
+          properties: { numericProfile: targetProfile, installedProfileData },
+        },
+        {
+          id: 'render-record',
+          type: 'KinetixRenderRecord',
+          schemaVersion: 1,
+          domain: 'presentation',
+          properties: { primitive: 'point', sourceSemanticDigest: archiveSha256 },
+        },
+        {
+          id: 'render-binding',
+          type: 'KinetixRenderBinding',
+          schemaVersion: 1,
+          domain: 'binding',
+          properties: {
+            source: { $kinetixRef: 'component', entityId: 'runtime-root', componentId: 'state' },
+            target: { $kinetixRef: 'component', entityId: 'runtime-root', componentId: 'render-record' },
+          },
+        },
+      ],
+    }],
+  };
+}
+
+function treeFingerprint(projectRoot) {
+  const status = git(projectRoot, ['status', '--porcelain=v1', '--untracked-files=all']);
+  const diff = git(projectRoot, ['diff', '--binary']);
+  if (status.status !== 0 || diff.status !== 0) {
+    throw new Error('KINETIX_SOURCE_TREE_UNREADABLE');
+  }
+  return createHash('sha256').update(status.stdout).update('\0').update(diff.stdout).digest('hex');
+}
+
+export function compileKinetixProject({
+  projectRoot,
+  expectedCommit,
+  targetProfile,
+  classifyInstalledBranches = true,
+}) {
+  if (typeof projectRoot !== 'string' || typeof expectedCommit !== 'string' || typeof targetProfile !== 'string') {
+    throw new Error('KINETIX_PROJECT_OPTIONS_INVALID');
+  }
+  const beforeFingerprint = treeFingerprint(projectRoot);
+  const archive = git(projectRoot, [
+    '-c', 'filter.lfs.required=false',
+    '-c', 'filter.lfs.process=',
+    '-c', 'filter.lfs.smudge=',
+    'archive', '--format=tar', expectedCommit,
+  ], null);
+  if (archive.status !== 0) {
+    return {
+      diagnostics: [diagnostic('KINETIX_SOURCE_COMMIT_MISSING', '', 1, 1, `Git commit ${expectedCommit} is unavailable.`)],
+      unmatchedBehaviors: [],
+      sourceSnapshot: { commit: expectedCommit, archiveSha256: '' },
+      semanticCoverage: [],
+      runtimeContract: null,
+      envelope: null,
+    };
+  }
+  const snapshotRoot = mkdtempSync(join(tmpdir(), 'kinetix-project-'));
+  try {
+    const extracted = spawnSync('tar', ['-xf', '-', '-C', snapshotRoot], {
+      input: archive.stdout,
+      encoding: null,
+      maxBuffer: 1 << 29,
+    });
+    if (extracted.status !== 0) {
+      throw new Error('KINETIX_SOURCE_ARCHIVE_INVALID');
+    }
+    const result = compileTrustedKinetixSource({
+      sourceRoot: snapshotRoot,
+      expectedCommit,
+      targetProfile,
+      classifyInstalledBranches,
+    });
+    if (treeFingerprint(projectRoot) !== beforeFingerprint) {
+      throw new Error('KINETIX_SOURCE_TREE_MUTATED');
+    }
+    return result;
+  } finally {
+    rmSync(snapshotRoot, { recursive: true, force: true });
+  }
+}
+
+export function compileTrustedKinetixSource({
+  sourceRoot,
+  expectedCommit,
+  targetProfile,
+  classifyInstalledBranches = true,
+}) {
+  if (typeof sourceRoot !== 'string'
+    || typeof expectedCommit !== 'string'
+    || typeof targetProfile !== 'string') {
+    throw new Error('KINETIX_TRUSTED_SOURCE_OPTIONS_INVALID');
+  }
+  const files = sourceFilesUnder(sourceRoot);
+  const sourceDigest = kinetixCanonicalSourceDigest(sourceRoot);
+  const classified = classifyUnmatched(
+    sourceRoot,
+    files,
+    targetProfile,
+    classifyInstalledBranches,
+  );
+  const unmatchedBehaviors = classified.unmatched;
+  const semanticCoverage = [
+    ...semanticCoverageFor(sourceRoot, files, targetProfile),
+    ...classified.coverage,
+  ];
+  const installedProfileData = unmatchedBehaviors.length === 0
+    ? targetProfile === 'fixed-1000-3d'
+      ? extractFixedProfileData(sourceRoot, files)
+      : extractF64ProfileData(sourceRoot, files)
+    : null;
+  return {
+    diagnostics: [...unmatchedBehaviors],
+    unmatchedBehaviors,
+    sourceSnapshot: { commit: expectedCommit, archiveSha256: sourceDigest },
+    semanticCoverage,
+    runtimeContract: unmatchedBehaviors.length === 0
+      ? kinetixRuntimeContractForProfile(targetProfile)
+      : null,
+    envelope: unmatchedBehaviors.length === 0
+      ? envelopeFor(targetProfile, expectedCommit, sourceDigest, semanticCoverage, installedProfileData)
+      : null,
+  };
+}