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

package/src/shared/kinetix-envelope-v1.mjs

@@ -0,0 +1,589 @@
+import { createHash } from 'node:crypto';
+
+export const kinetixEnvelopeVersion = 'rundot.kinetix-envelope.v1';
+export const kinetixDomains = Object.freeze(['simulation', 'presentation', 'binding']);
+export const kinetixReferenceKinds = Object.freeze([
+  'entity',
+  'component',
+  'prefab',
+  'prefab-local-entity',
+  'prefab-local-component',
+  'asset',
+  'scene',
+]);
+
+const identifierPattern = /^[A-Za-z][A-Za-z0-9._-]*$/u;
+const sha256Pattern = /^[0-9a-f]{64}$/u;
+const prohibitedKeys = Object.freeze([
+  { fragment: 'script', code: 'KINETIX_PROHIBITED_SCRIPT' },
+  { fragment: 'bytecode', code: 'KINETIX_PROHIBITED_BYTECODE' },
+  { fragment: 'wasm', code: 'KINETIX_PROHIBITED_WASM' },
+  { fragment: 'shader', code: 'KINETIX_PROHIBITED_SHADER_SOURCE' },
+]);
+const prohibitedContent = Object.freeze([
+  { code: 'KINETIX_PROHIBITED_SCRIPT', signatures: ['eval(', 'new Function', 'import(', 'require(', '<script', 'javascript:'] },
+  { code: 'KINETIX_PROHIBITED_BYTECODE', signatures: ['\u007fELF', 'MZ'] },
+  { code: 'KINETIX_PROHIBITED_WASM', signatures: ['\u0000asm'] },
+  { code: 'KINETIX_PROHIBITED_SHADER_SOURCE', signatures: ['gl_Position', 'gl_FragColor', '#version ', '[[stage_in]]', 'kernel void'] },
+]);
+const budgetKeys = Object.freeze([
+  'maxDirectEntities',
+  'maxPrefabs',
+  'maxLocalEntitiesPerPrefab',
+  'maxComponents',
+  'maxLiveRuntimeEntities',
+  'maxSimulationRecords',
+  'maxPresentationRecords',
+  'maxBindingRecords',
+  'maxCommandsPerTick',
+]);
+
+function isPlainObject(value) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function addDiagnostic(diagnostics, code, path) {
+  if (!diagnostics.some((entry) => entry.code === code && entry.path === path)) {
+    diagnostics.push({ code, path });
+  }
+}
+
+function validateIdentifier(value, path, diagnostics, code = 'KINETIX_INVALID_ID') {
+  if (typeof value !== 'string' || !identifierPattern.test(value)) {
+    addDiagnostic(diagnostics, code, path);
+    return false;
+  }
+  return true;
+}
+
+function validateUniqueIds(values, path, diagnostics, validateEntry) {
+  if (!Array.isArray(values)) {
+    addDiagnostic(diagnostics, 'KINETIX_INVALID_STRUCTURE', path);
+    return new Map();
+  }
+  const byId = new Map();
+  values.forEach((value, index) => {
+    const entryPath = `${path}[${index}]`;
+    if (!isPlainObject(value)) {
+      addDiagnostic(diagnostics, 'KINETIX_INVALID_STRUCTURE', entryPath);
+      return;
+    }
+    if (validateIdentifier(value.id, `${entryPath}.id`, diagnostics)) {
+      if (byId.has(value.id)) {
+        addDiagnostic(diagnostics, 'KINETIX_DUPLICATE_ID', `${entryPath}.id`);
+      } else {
+        byId.set(value.id, { value, index, path: entryPath });
+      }
+    }
+    validateEntry(value, entryPath, index);
+  });
+  return byId;
+}
+
+function scanSafety(value, path, diagnostics, seen) {
+  const valueType = typeof value;
+  if (value === null || valueType === 'boolean' || valueType === 'string') {
+    if (valueType === 'string') {
+      for (const rule of prohibitedContent) {
+        if (rule.signatures.some((signature) => value.includes(signature))) {
+          addDiagnostic(diagnostics, rule.code, path);
+        }
+      }
+    }
+    return;
+  }
+  if (valueType === 'number') {
+    if (!Number.isFinite(value)) {
+      addDiagnostic(diagnostics, 'KINETIX_UNSAFE_VALUE', path);
+    }
+    return;
+  }
+  if (valueType !== 'object') {
+    addDiagnostic(diagnostics, 'KINETIX_UNSAFE_VALUE', path);
+    return;
+  }
+  if (seen.has(value)) {
+    addDiagnostic(diagnostics, 'KINETIX_UNSAFE_VALUE', path);
+    return;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => scanSafety(entry, `${path}[${index}]`, diagnostics, seen));
+    return;
+  }
+  if (!isPlainObject(value)) {
+    addDiagnostic(diagnostics, 'KINETIX_UNSAFE_VALUE', path);
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    const entryPath = `${path}.${key}`;
+    if (key === '__proto__' || key === 'prototype' || key === 'constructor') {
+      addDiagnostic(diagnostics, 'KINETIX_UNSAFE_KEY', entryPath);
+    }
+    const lowerKey = key.toLowerCase();
+    for (const rule of prohibitedKeys) {
+      if (lowerKey.includes(rule.fragment)) {
+        addDiagnostic(diagnostics, rule.code, entryPath);
+      }
+    }
+    scanSafety(entry, entryPath, diagnostics, seen);
+  }
+}
+
+function validateExactKeys(value, allowedKeys, path, diagnostics) {
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.includes(key)) {
+      addDiagnostic(diagnostics, 'KINETIX_REFERENCE_INVALID', `${path}.${key}`);
+    }
+  }
+  for (const key of allowedKeys) {
+    if (key !== 'prefabId' && !Object.hasOwn(value, key)) {
+      addDiagnostic(diagnostics, 'KINETIX_REFERENCE_INVALID', `${path}.${key}`);
+    }
+  }
+}
+
+function validateAllowedKeys(value, allowedKeys, path, diagnostics) {
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.includes(key)) {
+      addDiagnostic(diagnostics, 'KINETIX_UNKNOWN_FIELD', `${path}.${key}`);
+    }
+  }
+}
+
+function validateReference(reference, path, context, indexes, diagnostics) {
+  const kind = reference.$kinetixRef;
+  if (!kinetixReferenceKinds.includes(kind)) {
+    addDiagnostic(diagnostics, 'KINETIX_REFERENCE_INVALID', `${path}.$kinetixRef`);
+    return;
+  }
+  const shapes = {
+    entity: ['$kinetixRef', 'id'],
+    component: ['$kinetixRef', 'entityId', 'componentId'],
+    prefab: ['$kinetixRef', 'id'],
+    'prefab-local-entity': ['$kinetixRef', 'id', 'prefabId'],
+    'prefab-local-component': ['$kinetixRef', 'entityId', 'componentId', 'prefabId'],
+    asset: ['$kinetixRef', 'id'],
+    scene: ['$kinetixRef', 'id'],
+  };
+  validateExactKeys(reference, shapes[kind], path, diagnostics);
+
+  if (kind === 'entity' || kind === 'component') {
+    if (context.prefabId !== null) {
+      addDiagnostic(diagnostics, 'KINETIX_REFERENCE_SCOPE', path);
+      return;
+    }
+    const entityId = kind === 'entity' ? reference.id : reference.entityId;
+    const entityEntry = indexes.entities.get(entityId);
+    const entityPath = kind === 'entity' ? `${path}.id` : `${path}.entityId`;
+    if (!entityEntry) {
+      addDiagnostic(diagnostics, 'KINETIX_REFERENCE_NOT_FOUND', entityPath);
+      return;
+    }
+    if (context.section !== null && entityEntry.value.section !== context.section && entityEntry.value.section !== 0) {
+      addDiagnostic(diagnostics, 'KINETIX_REFERENCE_SECTION', entityPath);
+    }
+    if (kind === 'component') {
+      const componentExists = Array.isArray(entityEntry.value.components)
+        && entityEntry.value.components.some((component) => component?.id === reference.componentId);
+      if (!componentExists) {
+        addDiagnostic(diagnostics, 'KINETIX_REFERENCE_NOT_FOUND', `${path}.componentId`);
+      }
+    }
+    return;
+  }
+
+  if (kind === 'prefab') {
+    if (!indexes.prefabs.has(reference.id)) {
+      addDiagnostic(diagnostics, 'KINETIX_REFERENCE_NOT_FOUND', `${path}.id`);
+    }
+    return;
+  }
+
+  if (kind === 'asset') {
+    if (!indexes.assets.has(reference.id)) {
+      addDiagnostic(diagnostics, 'KINETIX_REFERENCE_NOT_FOUND', `${path}.id`);
+    }
+    return;
+  }
+
+  if (kind === 'scene') {
+    if (reference.id !== indexes.sceneId && !indexes.scenes.has(reference.id)) {
+      addDiagnostic(diagnostics, 'KINETIX_REFERENCE_NOT_FOUND', `${path}.id`);
+    }
+    return;
+  }
+
+  if (kind === 'prefab-local-entity' && context.prefabId === null) {
+    addDiagnostic(diagnostics, 'KINETIX_REFERENCE_SCOPE', path);
+    return;
+  }
+
+  const explicitPrefabId = reference.prefabId;
+  if (context.prefabId !== null && explicitPrefabId !== undefined && explicitPrefabId !== context.prefabId) {
+    addDiagnostic(diagnostics, 'KINETIX_REFERENCE_SCOPE', `${path}.prefabId`);
+    return;
+  }
+  const prefabId = explicitPrefabId ?? context.prefabId;
+  if (prefabId === null || prefabId === undefined) {
+    addDiagnostic(diagnostics, 'KINETIX_REFERENCE_SCOPE', `${path}.prefabId`);
+    return;
+  }
+  const prefabEntry = indexes.prefabs.get(prefabId);
+  if (!prefabEntry) {
+    addDiagnostic(diagnostics, 'KINETIX_REFERENCE_NOT_FOUND', `${path}.prefabId`);
+    return;
+  }
+  const localEntityId = kind === 'prefab-local-entity' ? reference.id : reference.entityId;
+  const localEntity = Array.isArray(prefabEntry.value.entities)
+    ? prefabEntry.value.entities.find((entity) => entity?.id === localEntityId)
+    : null;
+  if (!localEntity) {
+    const entityPath = kind === 'prefab-local-entity' ? `${path}.id` : `${path}.entityId`;
+    addDiagnostic(diagnostics, 'KINETIX_REFERENCE_NOT_FOUND', entityPath);
+    return;
+  }
+  if (kind === 'prefab-local-component') {
+    const componentExists = Array.isArray(localEntity.components)
+      && localEntity.components.some((component) => component?.id === reference.componentId);
+    if (!componentExists) {
+      addDiagnostic(diagnostics, 'KINETIX_REFERENCE_NOT_FOUND', `${path}.componentId`);
+    }
+  }
+}
+
+function scanReferences(value, path, context, indexes, diagnostics) {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => scanReferences(entry, `${path}[${index}]`, context, indexes, diagnostics));
+    return;
+  }
+  if (!isPlainObject(value)) {
+    return;
+  }
+  if (Object.hasOwn(value, '$kinetixRef')) {
+    validateReference(value, path, context, indexes, diagnostics);
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    scanReferences(entry, `${path}.${key}`, context, indexes, diagnostics);
+  }
+}
+
+function validateComponent(component, path, diagnostics) {
+  if (!isPlainObject(component)) {
+    addDiagnostic(diagnostics, 'KINETIX_INVALID_COMPONENT', path);
+    return;
+  }
+  validateAllowedKeys(component, ['id', 'type', 'schemaVersion', 'domain', 'properties'], path, diagnostics);
+  validateIdentifier(component.id, `${path}.id`, diagnostics);
+  validateIdentifier(component.type, `${path}.type`, diagnostics, 'KINETIX_INVALID_COMPONENT');
+  if (!Number.isSafeInteger(component.schemaVersion) || component.schemaVersion < 1) {
+    addDiagnostic(diagnostics, 'KINETIX_INVALID_SCHEMA_VERSION', `${path}.schemaVersion`);
+  }
+  if (component.domain === 'ui') {
+    addDiagnostic(diagnostics, 'KINETIX_DOMAIN_RESERVED', `${path}.domain`);
+  } else if (!kinetixDomains.includes(component.domain)) {
+    addDiagnostic(diagnostics, 'KINETIX_DOMAIN_UNKNOWN', `${path}.domain`);
+  }
+  if (!isPlainObject(component.properties)) {
+    addDiagnostic(diagnostics, 'KINETIX_INVALID_COMPONENT', `${path}.properties`);
+  }
+}
+
+function validateComponents(components, path, diagnostics) {
+  return validateUniqueIds(components, path, diagnostics, (component, componentPath) => {
+    validateComponent(component, componentPath, diagnostics);
+  });
+}
+
+function validateHierarchy(entries, path, parentKind, diagnostics) {
+  if (!Array.isArray(entries)) {
+    return;
+  }
+  const byId = new Map(entries.filter(isPlainObject).map((entry, index) => [entry.id, { entry, index }]));
+  const states = new Map();
+  function visit(id, stack) {
+    const state = states.get(id);
+    if (state === 'done') {
+      return;
+    }
+    if (state === 'visiting') {
+      return;
+    }
+    states.set(id, 'visiting');
+    stack.push(id);
+    const current = byId.get(id);
+    const parent = current?.entry.parent;
+    if (isPlainObject(parent) && parent.$kinetixRef === parentKind) {
+      const parentId = parentKind === 'entity' ? parent.id : parent.id;
+      if (states.get(parentId) === 'visiting') {
+        const firstCycleId = stack[stack.indexOf(parentId)];
+        addDiagnostic(diagnostics, 'KINETIX_HIERARCHY_CYCLE', `${path}[${byId.get(firstCycleId).index}].parent`);
+      } else if (byId.has(parentId)) {
+        visit(parentId, stack);
+      }
+    }
+    stack.pop();
+    states.set(id, 'done');
+  }
+  for (const id of byId.keys()) {
+    visit(id, []);
+  }
+}
+
+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 validateKinetixEnvelope(envelope) {
+  const diagnostics = [];
+  scanSafety(envelope, '$', diagnostics, new Set());
+  if (!isPlainObject(envelope)) {
+    addDiagnostic(diagnostics, 'KINETIX_INVALID_STRUCTURE', '$');
+    return { valid: false, diagnostics };
+  }
+  if (envelope.version !== kinetixEnvelopeVersion) {
+    addDiagnostic(diagnostics, 'KINETIX_VERSION_UNSUPPORTED', '$.version');
+  }
+  if (Array.isArray(envelope.payloads)) {
+    envelope.payloads.forEach((payload, index) => {
+      if (payload?.name === 'ui') {
+        addDiagnostic(diagnostics, 'KINETIX_DOMAIN_RESERVED', `$.payloads[${index}].name`);
+      }
+    });
+  }
+  validateAllowedKeys(
+    envelope,
+    ['version', 'sceneId', 'sceneDependencies', 'profiles', 'assets', 'budgets', 'prefabs', 'entities', 'compilerProvenance', 'semanticCoverage'],
+    '$',
+    diagnostics,
+  );
+  validateIdentifier(envelope.sceneId, '$.sceneId', diagnostics);
+
+  if (envelope.compilerProvenance !== undefined) {
+    const provenance = envelope.compilerProvenance;
+    if (!isPlainObject(provenance)) {
+      addDiagnostic(diagnostics, 'KINETIX_COMPILER_PROVENANCE_INVALID', '$.compilerProvenance');
+    } else {
+      validateAllowedKeys(provenance, ['compilerVersion', 'targetProfile', 'sourceSnapshot'], '$.compilerProvenance', diagnostics);
+      if (typeof provenance.compilerVersion !== 'string' || provenance.compilerVersion.length === 0
+        || typeof provenance.targetProfile !== 'string' || provenance.targetProfile.length === 0
+        || !isPlainObject(provenance.sourceSnapshot)) {
+        addDiagnostic(diagnostics, 'KINETIX_COMPILER_PROVENANCE_INVALID', '$.compilerProvenance');
+      } else {
+        validateAllowedKeys(provenance.sourceSnapshot, ['commit', 'archiveSha256'], '$.compilerProvenance.sourceSnapshot', diagnostics);
+        if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(provenance.sourceSnapshot.commit ?? '')
+          || !sha256Pattern.test(provenance.sourceSnapshot.archiveSha256 ?? '')) {
+          addDiagnostic(diagnostics, 'KINETIX_COMPILER_PROVENANCE_INVALID', '$.compilerProvenance.sourceSnapshot');
+        }
+      }
+    }
+  }
+
+  if (envelope.semanticCoverage !== undefined) {
+    if (!Array.isArray(envelope.semanticCoverage)) {
+      addDiagnostic(diagnostics, 'KINETIX_SEMANTIC_COVERAGE_INVALID', '$.semanticCoverage');
+    } else {
+      envelope.semanticCoverage.forEach((entry, index) => {
+        const path = `$.semanticCoverage[${index}]`;
+        if (!isPlainObject(entry) || !isPlainObject(entry.source)) {
+          addDiagnostic(diagnostics, 'KINETIX_SEMANTIC_COVERAGE_INVALID', path);
+          return;
+        }
+        validateAllowedKeys(entry, ['source', 'systemId', 'phase', 'order'], path, diagnostics);
+        validateAllowedKeys(entry.source, ['file', 'line', 'column'], `${path}.source`, diagnostics);
+        if (typeof entry.source.file !== 'string' || entry.source.file.length === 0
+          || !Number.isSafeInteger(entry.source.line) || entry.source.line < 1
+          || !Number.isSafeInteger(entry.source.column) || entry.source.column < 1
+          || !identifierPattern.test(entry.systemId ?? '')
+          || !['initialization', 'fixed-simulation', 'post-simulation', 'presentation-projection', 'presentation'].includes(entry.phase)
+          || !Number.isSafeInteger(entry.order) || entry.order < 0) {
+          addDiagnostic(diagnostics, 'KINETIX_SEMANTIC_COVERAGE_INVALID', path);
+        }
+      });
+    }
+  }
+
+  const scenes = validateUniqueIds(envelope.sceneDependencies, '$.sceneDependencies', diagnostics, (scene, path) => {
+    validateAllowedKeys(scene, ['id', 'sha256'], path, diagnostics);
+    if (!sha256Pattern.test(scene.sha256 ?? '')) {
+      addDiagnostic(diagnostics, 'KINETIX_INVALID_SCENE_DEPENDENCY', `${path}.sha256`);
+    }
+  });
+  const profiles = validateUniqueIds(envelope.profiles, '$.profiles', diagnostics, (profile, path) => {
+    validateAllowedKeys(profile, ['id', 'abi'], path, diagnostics);
+    if (typeof profile.abi !== 'string' || profile.abi.length === 0) {
+      addDiagnostic(diagnostics, 'KINETIX_INVALID_PROFILE', `${path}.abi`);
+    }
+  });
+  const assets = validateUniqueIds(envelope.assets, '$.assets', diagnostics, (asset, path) => {
+    validateAllowedKeys(asset, ['id', 'kind', 'sha256', 'sourceSha256', 'byteLength'], path, diagnostics);
+    if (typeof asset.kind !== 'string' || asset.kind.length === 0
+      || !sha256Pattern.test(asset.sha256 ?? '')
+      || !sha256Pattern.test(asset.sourceSha256 ?? '')
+      || !Number.isSafeInteger(asset.byteLength)
+      || asset.byteLength < 0) {
+      addDiagnostic(diagnostics, 'KINETIX_INVALID_ASSET', path);
+    }
+  });
+
+  if (!isPlainObject(envelope.budgets)) {
+    addDiagnostic(diagnostics, 'KINETIX_INVALID_BUDGET', '$.budgets');
+  } else {
+    validateAllowedKeys(envelope.budgets, budgetKeys, '$.budgets', diagnostics);
+    for (const key of budgetKeys) {
+      const value = envelope.budgets[key];
+      const minimum = key === 'maxCommandsPerTick' ? 1 : 0;
+      if (!Number.isSafeInteger(value) || value < minimum) {
+        addDiagnostic(diagnostics, 'KINETIX_INVALID_BUDGET', `$.budgets.${key}`);
+      }
+    }
+  }
+
+  const prefabs = validateUniqueIds(envelope.prefabs, '$.prefabs', diagnostics, (prefab, prefabPath) => {
+    validateAllowedKeys(prefab, ['id', 'profile', 'poolBudget', 'rootLocalEntityId', 'entities'], prefabPath, diagnostics);
+    if (!profiles.has(prefab.profile)) {
+      addDiagnostic(diagnostics, 'KINETIX_UNKNOWN_PROFILE', `${prefabPath}.profile`);
+    }
+    if (!Number.isSafeInteger(prefab.poolBudget) || prefab.poolBudget < 1) {
+      addDiagnostic(diagnostics, 'KINETIX_INVALID_BUDGET', `${prefabPath}.poolBudget`);
+    }
+    const localEntities = validateUniqueIds(prefab.entities, `${prefabPath}.entities`, diagnostics, (entity, entityPath) => {
+      validateAllowedKeys(entity, ['id', 'enabled', 'parent', 'components'], entityPath, diagnostics);
+      if (Object.hasOwn(entity, 'enabled') && typeof entity.enabled !== 'boolean') {
+        addDiagnostic(diagnostics, 'KINETIX_INVALID_ENABLED', `${entityPath}.enabled`);
+      }
+      validateComponents(entity.components, `${entityPath}.components`, diagnostics);
+    });
+    if (!localEntities.has(prefab.rootLocalEntityId)) {
+      addDiagnostic(diagnostics, 'KINETIX_PREFAB_ROOT_MISSING', `${prefabPath}.rootLocalEntityId`);
+    }
+    validateHierarchy(prefab.entities, `${prefabPath}.entities`, 'prefab-local-entity', diagnostics);
+  });
+
+  const entities = validateUniqueIds(envelope.entities, '$.entities', diagnostics, (entity, entityPath) => {
+    validateAllowedKeys(entity, ['id', 'profile', 'lifecycle', 'section', 'parent', 'enabled', 'components'], entityPath, diagnostics);
+    if (!profiles.has(entity.profile)) {
+      addDiagnostic(diagnostics, 'KINETIX_UNKNOWN_PROFILE', `${entityPath}.profile`);
+    }
+    if (entity.lifecycle !== 'static' && entity.lifecycle !== 'slot') {
+      addDiagnostic(diagnostics, 'KINETIX_INVALID_LIFECYCLE', `${entityPath}.lifecycle`);
+    }
+    if (!Number.isSafeInteger(entity.section) || entity.section < 0) {
+      addDiagnostic(diagnostics, 'KINETIX_INVALID_SECTION', `${entityPath}.section`);
+    }
+    if (Object.hasOwn(entity, 'enabled') && typeof entity.enabled !== 'boolean') {
+      addDiagnostic(diagnostics, 'KINETIX_INVALID_ENABLED', `${entityPath}.enabled`);
+    }
+    validateComponents(entity.components, `${entityPath}.components`, diagnostics);
+  });
+
+  const indexes = { assets, entities, prefabs, profiles, scenes, sceneId: envelope.sceneId };
+  if (Array.isArray(envelope.prefabs)) {
+    envelope.prefabs.forEach((prefab, prefabIndex) => {
+      if (!isPlainObject(prefab) || !Array.isArray(prefab.entities)) {
+        return;
+      }
+      prefab.entities.forEach((entity, entityIndex) => {
+        if (!isPlainObject(entity)) {
+          return;
+        }
+        const entityPath = `$.prefabs[${prefabIndex}].entities[${entityIndex}]`;
+        if (entity.parent !== undefined && entity.parent !== null) {
+          if (!isPlainObject(entity.parent) || entity.parent.$kinetixRef !== 'prefab-local-entity') {
+            addDiagnostic(diagnostics, 'KINETIX_REFERENCE_INVALID', `${entityPath}.parent`);
+          } else {
+            validateReference(entity.parent, `${entityPath}.parent`, { prefabId: prefab.id, section: null }, indexes, diagnostics);
+          }
+        }
+        scanReferences(entity.components, `${entityPath}.components`, { prefabId: prefab.id, section: null }, indexes, diagnostics);
+      });
+    });
+  }
+  if (Array.isArray(envelope.entities)) {
+    envelope.entities.forEach((entity, entityIndex) => {
+      if (!isPlainObject(entity)) {
+        return;
+      }
+      const entityPath = `$.entities[${entityIndex}]`;
+      if (entity.parent !== undefined && entity.parent !== null) {
+        if (!isPlainObject(entity.parent) || entity.parent.$kinetixRef !== 'entity') {
+          addDiagnostic(diagnostics, 'KINETIX_REFERENCE_INVALID', `${entityPath}.parent`);
+        } else {
+          validateReference(entity.parent, `${entityPath}.parent`, { prefabId: null, section: entity.section }, indexes, diagnostics);
+          const parentEntry = entities.get(entity.parent.id);
+          if (parentEntry && parentEntry.value.section !== entity.section) {
+            addDiagnostic(diagnostics, 'KINETIX_REFERENCE_SECTION', `${entityPath}.parent.id`);
+          }
+        }
+      }
+      scanReferences(entity.components, `${entityPath}.components`, { prefabId: null, section: entity.section }, indexes, diagnostics);
+    });
+    validateHierarchy(envelope.entities, '$.entities', 'entity', diagnostics);
+  }
+
+  if (isPlainObject(envelope.budgets)) {
+    const directCount = Array.isArray(envelope.entities) ? envelope.entities.length : 0;
+    const prefabCount = Array.isArray(envelope.prefabs) ? envelope.prefabs.length : 0;
+    if (directCount > envelope.budgets.maxDirectEntities) {
+      addDiagnostic(diagnostics, 'KINETIX_BUDGET_EXCEEDED', '$.entities');
+    }
+    if (prefabCount > envelope.budgets.maxPrefabs) {
+      addDiagnostic(diagnostics, 'KINETIX_BUDGET_EXCEEDED', '$.prefabs');
+    }
+    let componentCount = 0;
+    let maxLocalCount = 0;
+    let pooledRuntimeCount = 0;
+    for (const prefab of Array.isArray(envelope.prefabs) ? envelope.prefabs : []) {
+      const localCount = Array.isArray(prefab?.entities) ? prefab.entities.length : 0;
+      maxLocalCount = Math.max(maxLocalCount, localCount);
+      if (Number.isSafeInteger(prefab?.poolBudget)) {
+        pooledRuntimeCount += prefab.poolBudget * localCount;
+      }
+      for (const entity of Array.isArray(prefab?.entities) ? prefab.entities : []) {
+        componentCount += Array.isArray(entity?.components) ? entity.components.length : 0;
+      }
+    }
+    for (const entity of Array.isArray(envelope.entities) ? envelope.entities : []) {
+      componentCount += Array.isArray(entity?.components) ? entity.components.length : 0;
+    }
+    if (maxLocalCount > envelope.budgets.maxLocalEntitiesPerPrefab) {
+      const prefabIndex = envelope.prefabs.findIndex((prefab) => prefab.entities.length === maxLocalCount);
+      addDiagnostic(diagnostics, 'KINETIX_BUDGET_EXCEEDED', `$.prefabs[${prefabIndex}].entities`);
+    }
+    if (componentCount > envelope.budgets.maxComponents) {
+      addDiagnostic(diagnostics, 'KINETIX_BUDGET_EXCEEDED', '$.budgets.maxComponents');
+    }
+    if (directCount + pooledRuntimeCount > envelope.budgets.maxLiveRuntimeEntities) {
+      addDiagnostic(diagnostics, 'KINETIX_BUDGET_EXCEEDED', '$.budgets.maxLiveRuntimeEntities');
+    }
+  }
+
+  return { valid: diagnostics.length === 0, diagnostics };
+}
+
+export function stableKinetixEnvelopeBytes(envelope) {
+  const result = validateKinetixEnvelope(envelope);
+  if (!result.valid) {
+    throw new Error(result.diagnostics[0].code);
+  }
+  return Buffer.from(JSON.stringify(canonicalize(envelope)));
+}
+
+export function kinetixEnvelopeDigest(envelope) {
+  return createHash('sha256').update(stableKinetixEnvelopeBytes(envelope)).digest('hex');
+}