genesis-compiler 1.10.6 → 1.10.8

package/src/index/call-web.js

@@ -0,0 +1,419 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { CALL_CERTAINTIES, CALL_METHODS, EXACT_CALL_METHODS, FUNCTION_KINDS, MAX_CALLEE_LENGTH, MAX_CALL_TARGETS, MAX_CALLS_PER_FILE, functionId } from './architecture-observations.js';
+import { GenesisError } from './errors.js';
+import { gitContext } from './git.js';
+import { sha256 } from './utils.js';
+
+export const CALL_WEB_SCHEMA = 'genesis.call-web.v1';
+export const CALL_WEB_PATH = '.genesis/call-web.json';
+const MAX_DIAGNOSTICS_PER_CODE = 100;
+const RE_EXPORT_DEPTH = 4;
+const REJOIN_LINES = 3;
+
+// Language-level knowledge only: names every program in the language can use
+// without declaring them. A project declaration of the same name wins.
+const words = value => new Set(value.trim().split(/\s+/u));
+const BUILTIN_GLOBALS = {
+  javascript: words(`console JSON Math Object Array String Number Boolean Promise Date RegExp Error TypeError RangeError Map Set WeakMap WeakSet Symbol Reflect Proxy Intl BigInt
+    Buffer process globalThis window document navigator location history localStorage sessionStorage performance crypto setTimeout setInterval clearTimeout clearInterval setImmediate
+    clearImmediate queueMicrotask requestAnimationFrame cancelAnimationFrame structuredClone fetch require parseInt parseFloat isNaN isFinite encodeURIComponent decodeURIComponent
+    encodeURI decodeURI atob btoa URL URLSearchParams TextEncoder TextDecoder AbortController AbortSignal Blob File FormData Headers Request Response Event CustomEvent EventTarget
+    Uint8Array Int8Array Uint16Array Int16Array Uint32Array Int32Array Float32Array Float64Array ArrayBuffer DataView WebSocket Worker alert confirm prompt eval import
+    describe it test expect beforeEach afterEach beforeAll afterAll vi jest`),
+  python: words(`print len range enumerate zip map filter sorted reversed sum min max abs any all isinstance issubclass hasattr getattr setattr delattr type super str int float bool
+    list dict set tuple frozenset bytes bytearray object open iter next repr hash id callable vars dir format round divmod pow chr ord hex oct bin input globals locals
+    staticmethod classmethod property compile eval exec memoryview slice __import__ breakpoint ascii aiter anext NotImplemented`),
+  go: words('len cap append make new panic recover print println copy delete close complex real imag min max clear string int int8 int16 int32 int64 uint uint8 uint16 uint32 uint64 uintptr byte rune float32 float64 bool error any'),
+  rust: words('Some Ok Err None Box Vec String Option Result drop'),
+  java: words('System String Math Integer Long Double Float Boolean Character Byte Short Object List Map Set Arrays Collections Objects Optional Stream Thread'),
+  kotlin: words(`println print listOf mapOf setOf arrayOf mutableListOf mutableMapOf mutableSetOf emptyList emptyMap emptySet lazy require requireNotNull check checkNotNull error TODO repeat
+    run with apply also let takeIf maxOf minOf Pair Triple`),
+  csharp: words('Console Math String Convert Int32 Int64 Double Boolean Object Array List Dictionary Task Enumerable Guid DateTime TimeSpan Environment Path File Directory nameof typeof'),
+  php: words(`count strlen str_replace substr strpos stripos explode implode in_array is_array is_string is_int is_numeric is_null is_bool is_object isset unset empty json_encode
+    json_decode sprintf printf vsprintf var_dump print_r var_export trim ltrim rtrim strtolower strtoupper ucfirst lcfirst ucwords preg_match preg_match_all preg_replace preg_split
+    file_get_contents file_put_contents file_exists is_file is_dir mkdir date time strtotime intval floatval boolval strval array_key_exists array_keys array_values array_map
+    array_filter array_merge array_slice array_splice array_search array_unique array_reverse array_push array_pop array_shift array_unshift compact extract define defined
+    function_exists method_exists class_exists property_exists call_user_func call_user_func_array func_get_args sort usort ksort uasort max min abs round floor ceil rand
+    mt_rand random_int htmlspecialchars urlencode rawurlencode base64_encode base64_decode md5 sha1 hash uniqid microtime header http_response_code session_start die exit
+    get_class spl_autoload_register iterator_to_array sprintf number_format str_contains str_starts_with str_ends_with array_combine array_fill range`),
+  ruby: words(`puts print p pp require require_relative load raise fail attr_accessor attr_reader attr_writer include extend prepend private protected public module_function
+    lambda proc loop format sprintf rand sleep catch throw block_given? yield binding caller freeze Integer Float String Array Hash`),
+  cpp: words(`printf fprintf sprintf snprintf scanf malloc calloc realloc free memcpy memset memmove memcmp strcmp strncmp strlen strcpy strncpy strcat strchr strstr exit abort
+    assert fopen fclose fread fwrite fgets fputs puts getchar putchar atoi atof strtol sizeof static_cast dynamic_cast reinterpret_cast const_cast std`),
+  shell: words(''),
+};
+const BUILTIN_MEMBERS = {
+  javascript: words(`push pop shift unshift slice splice concat join map filter reduce reduceRight forEach find findIndex findLast findLastIndex some every includes indexOf lastIndexOf
+    sort reverse flat flatMap fill keys values entries has get set add delete clear then catch finally toString valueOf toLowerCase toUpperCase trim trimStart trimEnd split
+    replace replaceAll match matchAll startsWith endsWith padStart padEnd charAt charCodeAt codePointAt substring substr repeat at test exec call apply bind hasOwnProperty
+    toFixed toISOString toJSON getTime getFullYear assign freeze from of isArray stringify parse log warn error info debug resolve reject all allSettled race any max min floor
+    ceil round abs random now emit on once off addEventListener removeEventListener dispatchEvent querySelector querySelectorAll getElementById appendChild removeChild
+    setAttribute getAttribute preventDefault stopPropagation localeCompare normalize sqrt pow trunc sign`),
+  python: words(`append extend insert remove pop clear index count sort reverse copy keys values items get setdefault update join split rsplit strip lstrip rstrip replace
+    startswith endswith find rfind lower upper format encode decode read write readline readlines close group groups groupdict match search sub findall finditer add discard
+    splitlines partition rpartition isdigit isalpha isalnum isspace isupper islower title capitalize zfill ljust rjust center expandtabs translate fullmatch`),
+  go: words('Error String Lock Unlock RLock RUnlock Close Write Read Len Done Wait Add'),
+  rust: words(`unwrap expect clone to_string to_owned into iter iter_mut into_iter map collect push pop len is_empty as_str as_ref as_mut ok err unwrap_or unwrap_or_else
+    unwrap_or_default and_then or_else filter get get_mut insert remove contains contains_key keys values entry or_insert join split trim format chars bytes lines`),
+  java: words(`println print printf equals hashCode toString get put add remove size isEmpty contains containsKey stream map filter collect forEach append length charAt substring
+    trim split format valueOf parseInt of asList orElse ifPresent getClass compareTo`),
+  kotlin: words(`map filter forEach first firstOrNull last lastOrNull toList toMutableList toSet joinToString add remove get set contains isEmpty isNotEmpty size toString
+    equals hashCode let also apply run takeIf trim split substring format`),
+  csharp: words(`ToString Equals GetHashCode GetType Add Remove Contains ContainsKey Clear WriteLine Write ReadLine Format Select Where ToList ToArray First FirstOrDefault
+    Any All Count Sum OrderBy GroupBy Join Split Trim Replace Substring StartsWith EndsWith IndexOf ConfigureAwait`),
+  php: words(''),
+  ruby: words(`each map select reject find detect each_with_index each_with_object inject reduce to_s to_i to_f to_sym to_a to_h include? empty? nil? length size push pop
+    join split strip gsub sub upcase downcase new call keys values merge first last any? all? sort sort_by min max sum uniq compact flatten freeze dup`),
+  cpp: words(`push_back emplace_back pop_back size begin end cbegin cend c_str insert erase find at front back empty clear reserve resize data substr append count
+    first second get reset swap lock unlock`),
+  shell: words(''),
+};
+const SELF_RECEIVERS = { javascript: ['this'], python: ['self', 'cls'], php: ['$this', 'self', 'static'], ruby: ['self'], java: ['this'], kotlin: ['this'], csharp: ['this'], cpp: ['this'], rust: ['self', 'Self'], go: [], shell: [] };
+const PARENT_RECEIVERS = new Set(['super', 'parent', 'base']);
+// Statements that bind every top-level function of the included file.
+const WILDCARD_LANGUAGES = new Set(['cpp', 'ruby', 'shell', 'php']);
+const NPM_PACKAGE = /^(?:node:|(?:@[a-z0-9~][a-z0-9._~-]*\/)?[a-z0-9~][a-z0-9._~-]*(?:\/|$))/iu;
+
+function externalSpecifier(language, specifier) {
+  if (!specifier) return false;
+  if (language === 'javascript') return !specifier.startsWith('.') && !specifier.startsWith('/') && NPM_PACKAGE.test(specifier);
+  if (language === 'python' || language === 'ruby') return !specifier.startsWith('.');
+  if (language === 'go') return !specifier.split('/')[0].includes('.');
+  if (language === 'rust') return /^(?:std|core|alloc)(?:::|$)/u.test(specifier);
+  if (language === 'java' || language === 'kotlin') return /^(?:java|javax|jakarta|kotlin|kotlinx|android|androidx)\./u.test(specifier);
+  if (language === 'csharp') return /^(?:System|Microsoft)(?:\.|$)/u.test(specifier);
+  return false;
+}
+
+const point = (line, column) => ({ line, column });
+const comparePoints = (left, right) => left.line - right.line || left.column - right.column;
+
+/**
+ * Resolves cached per-file call-site syntax against one snapshot and joins
+ * adapter observations by the §3.1.6 precedence rules. The generic baseline is
+ * name and import scope only, so it never claims an exact edge.
+ */
+export function buildCallWeb({ architecture, extractions, machineFunctions = [], observations = null, sourceIdentity }) {
+  const diagnostics = [];
+  const counted = new Map();
+  const diagnose = (entry) => {
+    const seen = (counted.get(entry.code) || 0) + 1;
+    counted.set(entry.code, seen);
+    if (seen <= MAX_DIAGNOSTICS_PER_CODE) diagnostics.push(entry);
+  };
+  const files = architecture.files.map(file => ({ path: file.path, hash: file.hash, subsystemId: file.subsystemId || null, language: file.language, id: file.id }));
+  const filesByPath = new Map(files.map((file, index) => [file.path, { ...file, index }]));
+  const filesById = new Map(files.map(file => [file.id, file]));
+  const exported = new Set(machineFunctions.filter(entry => entry.visibility === 'public').map(entry => `${entry.path}#${entry.line}:${entry.column}`));
+  const adapterFunctions = (observations?.functions || []).filter(entry => filesByPath.has(entry.file));
+  const adapterOf = entry => entry.adapter || observations.adapter;
+  const adapterFiles = new Map();
+  for (const entry of adapterFunctions) if (!adapterFiles.has(entry.file)) adapterFiles.set(entry.file, adapterOf(entry));
+
+  // Generic function sites for every extracted file, including adapter files:
+  // calls elsewhere may target them before re-joining to adapter functions.
+  const generic = new Map();
+  for (const [filePath, sites] of extractions) {
+    const file = filesByPath.get(filePath);
+    if (!file) continue;
+    const functions = sites.functions.map(entry => ({
+      id: functionId(filePath, entry.start, entry.kind), file: filePath, name: entry.name, kind: entry.kind, start: entry.start, end: entry.end,
+      ...(entry.container ? { container: entry.container } : {}),
+      ...(exported.has(`${filePath}#${entry.start.line}:${entry.start.column}`) ? { exported: true } : {}),
+      parent: entry.parent, default: entry.default === true,
+    }));
+    const ids = new Set();
+    for (const entry of functions) { entry.duplicate = ids.has(entry.id); ids.add(entry.id); }
+    const moduleRecord = comparePoints(point(1, 1), sites.moduleEnd) < 0
+      ? { id: functionId(filePath, point(1, 1), 'module'), file: filePath, name: '', kind: 'module', start: point(1, 1), end: sites.moduleEnd, parent: -1, default: false }
+      : null;
+    generic.set(filePath, { file, sites, functions, moduleRecord, language: file.language });
+  }
+  const projectNames = new Set([...generic.values()].flatMap(entry => entry.functions.map(fn => fn.name)).concat(adapterFunctions.map(entry => entry.name)).filter(Boolean));
+
+  // Per-file lookup tables used by the resolution rules.
+  for (const entry of generic.values()) {
+    entry.byName = new Map(); entry.topByName = new Map(); entry.members = new Map();
+    const add = (map, key, value) => { if (!map.has(key)) map.set(key, []); map.get(key).push(value); };
+    for (const fn of entry.functions) {
+      if (!fn.name || fn.duplicate) continue;
+      add(entry.byName, fn.name, fn);
+      if ((fn.parent < 0 && !fn.container) || fn.exported) add(entry.topByName, fn.name, fn);
+      if (fn.container && ['method', 'constructor'].includes(fn.kind)) add(entry.members, `${fn.container}\0${fn.name}`, fn);
+    }
+    entry.defaults = entry.functions.filter(fn => fn.default && !fn.duplicate);
+  }
+  const relationsByFile = new Map();
+  for (const relation of architecture.relations || []) {
+    const file = filesById.get(relation.fromFileId);
+    if (!file) continue;
+    if (!relationsByFile.has(file.path)) relationsByFile.set(file.path, []);
+    relationsByFile.get(file.path).push(relation);
+  }
+  const packagesById = new Map((architecture.packages || []).map(entry => [entry.id, entry]));
+  const relationTarget = relation => relation.resolution === 'resolved' && relation.targetFileId ? filesById.get(relation.targetFileId)?.path || null : null;
+  const relationExternal = (relation, language) => (relation.targetPackageId != null && packagesById.get(relation.targetPackageId)?.opaque !== false && !relation.targetFileId)
+    || (relation.resolution !== 'resolved' && externalSpecifier(language, relation.specifier));
+  // An included C/C++ header declares what its same-named source file defines.
+  const headerSources = header => /\.(?:h|hh|hpp|hxx)$/u.test(header)
+    ? ['.c', '.cc', '.cpp', '.cxx'].map(extension => header.replace(/\.[^.]+$/u, extension)).filter(candidate => filesByPath.has(candidate))
+    : [];
+  for (const [filePath, entry] of generic) {
+    const relations = relationsByFile.get(filePath) || [];
+    const atStart = new Map(relations.map(relation => [`${relation.start?.line}:${relation.start?.column}`, relation]));
+    entry.named = new Map(); entry.namespaces = new Map(); entry.wildcards = [];
+    for (const binding of entry.sites.bindings) {
+      const relation = atStart.get(`${binding.at.line}:${binding.at.column}`);
+      const resolved = { ...binding, target: relation ? relationTarget(relation) : null, external: relation ? relationExternal(relation, entry.language) : externalSpecifier(entry.language, null) };
+      if (binding.wildcard) entry.wildcards.push(resolved);
+      else (binding.namespace ? entry.namespaces : entry.named).set(binding.local, resolved);
+    }
+    const included = [];
+    if (WILDCARD_LANGUAGES.has(entry.language)) for (const relation of relations) {
+      const target = relationTarget(relation);
+      if (target) included.push(target, ...(entry.language === 'cpp' ? headerSources(target) : []));
+    }
+    for (const target of included) entry.wildcards.push({ target, external: false });
+    entry.imports = new Set([filePath, ...included, ...relations.filter(relation => !relation.typeOnly).map(relationTarget).filter(Boolean)]);
+    entry.reExports = relations.filter(relation => relation.kind === 're-export' && Array.isArray(relation.exports));
+  }
+
+  // A name exported by T, following named bindings and re-exports a few hops.
+  function exportedFunctions(target, name, depth = 0, seen = new Set()) {
+    const entry = generic.get(target);
+    if (!entry || seen.has(target)) return [];
+    const own = entry.topByName.get(name);
+    if (own?.length) return own;
+    if (depth >= RE_EXPORT_DEPTH) return [];
+    seen.add(target);
+    const binding = entry.named.get(name);
+    if (binding?.target) return binding.imported === 'default' ? generic.get(binding.target)?.defaults || [] : exportedFunctions(binding.target, binding.imported, depth + 1, seen);
+    const found = [];
+    for (const relation of entry.reExports) {
+      const next = relationTarget(relation);
+      for (const exported of relation.exports) {
+        if (next && exported.name === '*') found.push(...exportedFunctions(next, name, depth + 1, seen));
+        else if (next && exported.alias === name) found.push(...exportedFunctions(next, exported.name, depth + 1, seen));
+      }
+    }
+    return [...new Set(found)];
+  }
+  // A Python `from package import module` binds the submodule file.
+  function namespaceTarget(entry, receiver) {
+    const namespace = entry.namespaces.get(receiver);
+    if (namespace) return namespace;
+    const binding = entry.named.get(receiver);
+    if (entry.language !== 'python' || !binding?.target?.endsWith('__init__.py') || generic.get(binding.target)?.topByName.has(binding.imported)) return null;
+    const directory = path.posix.dirname(binding.target);
+    const module = [`${directory}/${binding.imported}.py`, `${directory}/${binding.imported}/__init__.py`].find(candidate => filesByPath.has(candidate));
+    return module ? { target: module, external: false } : null;
+  }
+  const rootName = receiver => receiver?.match(/^[$A-Za-z_][\w$]*/u)?.[0] || null;
+
+  function resolve(entry, call, from) {
+    const { language } = entry;
+    const name = call.name;
+    const receiver = call.receiver ?? null;
+    const unresolved = { resolution: 'unresolved', certainty: 'unresolved', method: 'none', targets: [] };
+    const found = (targets, method) => targets.length === 1
+      ? { resolution: 'resolved', certainty: 'probable', method, targets }
+      : { resolution: 'ambiguous', certainty: 'probable', method, targets };
+    if (!name) return language === 'shell' ? null : unresolved;
+    if (receiver && PARENT_RECEIVERS.has(rootName(receiver))) return unresolved;
+    const self = receiver !== null && SELF_RECEIVERS[language]?.includes(receiver);
+    if (!receiver) {
+      const binding = entry.named.get(name);
+      if (binding?.target) {
+        const targets = binding.imported === 'default' ? generic.get(binding.target)?.defaults || [] : exportedFunctions(binding.target, binding.imported);
+        if (targets.length === 1) return found(targets, 'import-scope');
+      } else if (!binding) {
+        const owners = entry.wildcards.map(wildcard => exportedFunctions(wildcard.target, name)).filter(targets => targets.length);
+        if (owners.length === 1 && owners[0].length === 1) return found(owners[0], 'import-scope');
+      }
+    } else if (!self) {
+      const namespace = namespaceTarget(entry, receiver);
+      if (namespace?.target) {
+        const own = generic.get(namespace.target)?.byName.get(name) || [];
+        const targets = own.length ? own : exportedFunctions(namespace.target, name);
+        if (targets.length === 1) return found(targets, 'import-scope');
+      }
+    }
+    if (self && from?.container) {
+      const targets = entry.members.get(`${from.container}\0${name}`) || [];
+      if (targets.length >= 1 && targets.length <= MAX_CALL_TARGETS) return found(targets, 'self');
+    }
+    // Provably external calls are omitted rather than shown as unresolved. A
+    // literal, imported-package or builtin receiver never reaches a project
+    // function, so name matching (rules 4 and 5) does not apply to it.
+    const root = rootName(receiver);
+    const boundExternal = value => value && (entry.named.get(value)?.external || entry.namespaces.get(value)?.external);
+    if (receiver && !self && (call.literal || boundExternal(root) || boundExternal(receiver) || BUILTIN_GLOBALS[language]?.has(root))) return null;
+    const same = entry.byName.get(name) || [];
+    if (same.length === 1) return found(same, 'same-file-name');
+    const candidates = [...entry.imports].flatMap(file => generic.get(file)?.byName.get(name) || []);
+    if (candidates.length >= 2 && candidates.length <= MAX_CALL_TARGETS) return found(candidates, 'receiver-name');
+    if (language === 'shell') return null;
+    if (!receiver && boundExternal(name)) return null;
+    if (!projectNames.has(name)) {
+      if (!receiver && BUILTIN_GLOBALS[language]?.has(name)) return null;
+      if (receiver && BUILTIN_MEMBERS[language]?.has(name)) return null;
+      if (language === 'python' && !receiver && /(?:Error|Exception|Warning|Exit|Interrupt)$/u.test(name)) return null;
+    }
+    return unresolved;
+  }
+
+  // Per-file precedence: an adapter that declares any function in a file
+  // replaces the generic baseline there.
+  const functions = [...adapterFunctions.map(entry => ({ id: entry.id, file: entry.file, name: entry.name, kind: entry.kind, start: entry.start, end: entry.end,
+    ...(entry.container ? { container: entry.container } : {}), ...(typeof entry.exported === 'boolean' ? { exported: entry.exported } : {}) }))];
+  const adapterById = new Map(functions.map(entry => [entry.id, entry]));
+  const adapterByFileName = new Map();
+  for (const entry of functions) {
+    const key = `${entry.file}\0${entry.name}`;
+    if (!adapterByFileName.has(key)) adapterByFileName.set(key, []);
+    adapterByFileName.get(key).push(entry);
+  }
+  for (const [filePath, entry] of generic) {
+    if (adapterFiles.has(filePath)) {
+      for (const fn of [entry.moduleRecord, ...entry.functions].filter(Boolean)) {
+        const adapter = adapterById.get(fn.id);
+        if (adapter && (adapter.name !== fn.name || adapter.kind !== fn.kind || comparePoints(adapter.end, fn.end))) diagnose({ code: 'FUNCTION_CONFLICT', path: filePath, message: `The ${adapterFiles.get(filePath)} inspector and the generic baseline disagree about ${fn.id}; the inspector is kept.` });
+      }
+      continue;
+    }
+    if (entry.moduleRecord) functions.push(entry.moduleRecord);
+    functions.push(...entry.functions.filter(fn => !fn.duplicate));
+  }
+  const rejoin = target => {
+    if (!adapterFiles.has(target.file)) return target.id;
+    if (adapterById.has(target.id)) return target.id;
+    const nearby = (adapterByFileName.get(`${target.file}\0${target.name}`) || [])
+      .map(entry => ({ entry, distance: Math.abs(entry.start.line - target.start.line) }))
+      .filter(entry => target.name && entry.distance <= REJOIN_LINES)
+      .sort((left, right) => left.distance - right.distance);
+    return nearby.length && (nearby.length === 1 || nearby[0].distance < nearby[1].distance) ? nearby[0].entry.id : null;
+  };
+
+  const calls = [];
+  const truncated = [];
+  for (const [filePath, entry] of generic) {
+    if (adapterFiles.has(filePath)) continue;
+    const fileCalls = [];
+    for (const call of entry.sites.calls) {
+      const from = call.from >= 0 ? entry.functions[call.from] : entry.moduleRecord;
+      if (!from || from.duplicate) continue;
+      const result = resolve(entry, call, from);
+      if (!result) continue;
+      let targets = result.targets.map(rejoin);
+      let outcome = result;
+      if (targets.some(target => target === null)) { outcome = { resolution: 'unresolved', certainty: 'unresolved', method: 'none' }; targets = []; }
+      targets = [...new Set(targets)];
+      if (outcome.resolution === 'ambiguous' && targets.length === 1) outcome = { ...outcome, resolution: 'resolved' };
+      fileCalls.push({ fromId: from.id, targets, certainty: outcome.certainty, method: outcome.method, resolution: outcome.resolution, callee: call.callee, site: { start: call.start, end: call.end } });
+    }
+    if (fileCalls.length > MAX_CALLS_PER_FILE) {
+      truncated.push(filePath);
+      diagnose({ code: 'CALLS_TRUNCATED', path: filePath, message: `Only the first ${MAX_CALLS_PER_FILE} calls of this file are recorded.` });
+      fileCalls.length = MAX_CALLS_PER_FILE;
+    }
+    calls.push(...fileCalls);
+  }
+  const functionIds = new Set(functions.map(entry => entry.id));
+  for (const call of observations?.calls || []) {
+    if (!functionIds.has(call.fromFunctionId) || !call.targets.every(target => functionIds.has(target))) continue;
+    calls.push({ fromId: call.fromFunctionId, targets: call.targets, certainty: call.certainty, method: call.method, resolution: call.resolution, callee: call.callee, site: { start: call.evidence[0].start, end: call.evidence[0].end } });
+  }
+  for (const entry of observations?.diagnostics || []) if (entry.code === 'FUNCTION_CONFLICT' || entry.code === 'CALLS_TRUNCATED') diagnose(entry);
+
+  // Each file's module code comes first, then its functions by position.
+  functions.sort((left, right) => filesByPath.get(left.file).index - filesByPath.get(right.file).index
+    || Number(right.kind === 'module') - Number(left.kind === 'module') || comparePoints(left.start, right.start) || left.id.localeCompare(right.id));
+  const indexById = new Map(functions.map((entry, index) => [entry.id, index]));
+  calls.sort((left, right) => indexById.get(left.fromId) - indexById.get(right.fromId) || comparePoints(left.site.start, right.site.start) || comparePoints(left.site.end, right.site.end));
+  const bridges = [];
+  for (const connection of architecture.ui?.connections || []) {
+    if (connection.resolution !== 'resolved' || !indexById.has(connection.fromFunctionId) || !indexById.has(connection.controllerFunctionId)) continue;
+    bridges.push({ from: indexById.get(connection.fromFunctionId), to: indexById.get(connection.controllerFunctionId), kind: 'operation', operationKey: connection.key, certainty: connection.certainty === 'exact' ? 'exact' : 'probable' });
+  }
+  for (const [code, seen] of counted) if (seen > MAX_DIAGNOSTICS_PER_CODE) diagnostics.push({ code, message: `${seen - MAX_DIAGNOSTICS_PER_CODE} more ${code} diagnostics are not listed.` });
+
+  const coverage = { generic: 0, adapters: {} };
+  const document = {
+    schema: CALL_WEB_SCHEMA,
+    sourceIdentity,
+    files: files.map(file => {
+      const adapter = adapterFiles.get(file.path);
+      const value = adapter ? `adapter:${adapter}` : generic.has(file.path) ? 'generic' : 'none';
+      if (adapter) coverage.adapters[adapter] = (coverage.adapters[adapter] || 0) + 1;
+      else if (value === 'generic') coverage.generic++;
+      return { path: file.path, hash: file.hash, subsystemId: file.subsystemId, coverage: value };
+    }),
+    functions: functions.map(({ id, file, name, kind, container, exported: isExported, start, end }) => ({ id, file: filesByPath.get(file).index, name, kind, ...(container ? { container } : {}), ...(typeof isExported === 'boolean' ? { exported: isExported } : {}), start, end })),
+    calls: calls.map(call => ({ from: indexById.get(call.fromId), targets: call.targets.map(target => indexById.get(target)), certainty: call.certainty, method: call.method, callee: call.callee, site: call.site })),
+    bridges,
+    diagnostics,
+  };
+  const counts = { functions: document.functions.length, calls: document.calls.length, exact: 0, probable: 0, unresolved: 0 };
+  for (const call of document.calls) counts[call.certainty]++;
+  return { document, counts, coverage, truncated };
+}
+
+/** Validates a `genesis.call-web.v1` document; `files` (path/hash) pins it to a snapshot. */
+export function validateCallWeb(document, { files } = {}) {
+  const check = (condition, message) => { if (!condition) throw new GenesisError('CALL_WEB_INVALID', message); };
+  const isPoint = value => value && Number.isSafeInteger(value.line) && value.line > 0 && Number.isSafeInteger(value.column) && value.column > 0;
+  const isRange = (start, end) => isPoint(start) && isPoint(end) && comparePoints(start, end) < 0;
+  check(document && typeof document === 'object' && document.schema === CALL_WEB_SCHEMA, `Expected ${CALL_WEB_SCHEMA}.`);
+  check(typeof document.sourceIdentity === 'string' && document.sourceIdentity.length > 0, 'A source identity is required.');
+  for (const name of ['files', 'functions', 'calls', 'bridges', 'diagnostics']) check(Array.isArray(document[name]), `${name} must be an array.`);
+  const known = files ? new Map(files.map(file => [file.path, file.hash])) : null;
+  const paths = new Set();
+  for (const file of document.files) {
+    check(typeof file?.path === 'string' && file.path.length > 0 && !paths.has(file.path) && typeof file.hash === 'string' && (file.subsystemId === null || typeof file.subsystemId === 'string'), 'Invalid or duplicate call-web file.');
+    check(file.coverage === 'generic' || file.coverage === 'none' || /^adapter:.+/u.test(file.coverage), `Invalid coverage for ${file.path}.`);
+    if (known) check(known.get(file.path) === file.hash, `${file.path} does not match the indexed source.`);
+    paths.add(file.path);
+  }
+  const ids = new Set();
+  for (const entry of document.functions) {
+    const file = document.files[entry?.file];
+    check(file && isRange(entry.start, entry.end) && entry.id === functionId(file.path, entry.start, entry.kind) && !ids.has(entry.id), 'Invalid or duplicate call-web function.');
+    check(FUNCTION_KINDS.includes(entry.kind) && typeof entry.name === 'string', `${entry.id} needs a known kind and a name.`);
+    ids.add(entry.id);
+  }
+  const fn = index => document.functions[index];
+  for (const call of document.calls) {
+    const from = fn(call?.from);
+    check(from && Array.isArray(call.targets) && call.targets.every(target => fn(target)), 'A call must reference known functions.');
+    check(CALL_CERTAINTIES.includes(call.certainty) && CALL_METHODS.includes(call.method) && typeof call.callee === 'string' && call.callee.length <= MAX_CALLEE_LENGTH, 'A call needs a known certainty, method and bounded callee.');
+    if (call.certainty === 'exact') check(call.targets.length === 1 && EXACT_CALL_METHODS.includes(call.method), 'An exact call needs one target from a resolver.');
+    if (call.certainty === 'probable') check(call.method !== 'none' && call.targets.length >= 1 && call.targets.length <= MAX_CALL_TARGETS, 'A probable call needs 1-16 targets.');
+    if (call.certainty === 'unresolved') check(call.targets.length === 0 && call.method === 'none', 'An unresolved call has no targets.');
+    check(isRange(call.site?.start, call.site?.end) && comparePoints(from.start, call.site.start) <= 0 && comparePoints(call.site.end, from.end) <= 0, 'A call site must lie inside its caller.');
+  }
+  for (const bridge of document.bridges) check(fn(bridge?.from) && fn(bridge.to) && bridge.kind === 'operation' && ['exact', 'probable'].includes(bridge.certainty) && bridge.operationKey && typeof bridge.operationKey === 'object', 'Invalid call-web bridge.');
+  check(document.diagnostics.every(entry => entry && typeof entry.code === 'string' && typeof entry.message === 'string'), 'diagnostics must contain code and message.');
+  return document;
+}
+
+/**
+ * Reads the current call web. `identity` is Machine City's `callWeb.identity`;
+ * without it the saved Machine City supplies it. Returns null when no call web
+ * matches the current Machine City.
+ */
+export async function readCallWeb({ projectRoot = process.cwd(), identity } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  let expected = identity;
+  if (expected === undefined) {
+    try { expected = JSON.parse(await readFile(path.join(root, '.genesis/machine-city.json'), 'utf8')).architecture?.callWeb?.identity ?? null; }
+    catch (error) { if (error instanceof SyntaxError || ['ENOENT', 'ENOTDIR'].includes(error.code)) expected = null; else throw error; }
+  }
+  if (!expected) return null;
+  let source;
+  try { source = await readFile(path.join(root, CALL_WEB_PATH)); }
+  catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return null; throw error; }
+  if (sha256(source) !== expected) return null;
+  return validateCallWeb(JSON.parse(source.toString('utf8')));
+}