genesis-compiler 1.7.8 → 1.8.0

package/src/index/architecture.js

@@ -0,0 +1,227 @@
+import path from 'node:path';
+import { connectArchitectureObservations } from './architecture-observations.js';
+import { buildCityPresentation } from './city-presentation.js';
+import { GenesisError } from './errors.js';
+import { sha256, stableJson } from './utils.js';
+
+const owns = (root, file) => root === '.' || file.startsWith(`${root}/`);
+
+function resolveReference(file, reference, filesByPath, packages) {
+  const specifier = reference.specifier;
+  if (!specifier) return { ...reference, resolution: 'unresolved' };
+  let target;
+  if (file.language === 'python') {
+    const dots = specifier.match(/^\.+/u)?.[0].length || 0;
+    const parts = specifier.slice(dots).split('.').join('/');
+    const base = dots ? path.posix.join(path.posix.dirname(file.path), ...Array(dots - 1).fill('..'), parts) : parts;
+    target = [base + '.py', base + '/__init__.py'].find(candidate => filesByPath.has(candidate));
+  } else if (specifier.startsWith('.') || file.language === 'cpp' || file.language === 'shell') {
+    const base = path.posix.normalize(path.posix.join(path.posix.dirname(file.path), specifier));
+    if (base !== '..' && !base.startsWith('../')) {
+      target = [base, ...['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.py', '.rb', '.sh'].map(extension => base + extension), ...['.js', '.ts', '.tsx', '.jsx'].map(extension => base + '/index' + extension)].find(candidate => filesByPath.has(candidate));
+    }
+  }
+  if (!target && file.language === 'javascript' && !specifier.startsWith('.') && !specifier.startsWith('/')) {
+    const candidates = packages.flatMap(entry => (entry.declarations || [{ manifest: entry.manifest }]).filter(declaration => owns(path.posix.dirname(declaration.manifest), file.path) && (specifier === entry.name || specifier.startsWith(`${entry.name}/`))).map(declaration => ({ entry, manifest: declaration.manifest }))).sort((a, b) => b.manifest.length - a.manifest.length);
+    const dependency = candidates[0]?.entry;
+    if (dependency) {
+      const importPath = specifier === dependency.name ? '.' : `.${specifier.slice(dependency.name.length)}`;
+      const publicFiles = [...new Set(dependency.entryPoints.filter(entry => entry.importPath === importPath).map(entry => entry.file).filter(value => filesByPath.has(value)))];
+      return { ...reference, targetPackageId: dependency.id, targetFileId: !dependency.opaque && publicFiles.length === 1 ? filesByPath.get(publicFiles[0]).id : null, importPath, resolution: 'resolved', reason: dependency.opaque ? 'Opaque package boundary; internal dependencies are not indexed.' : 'Project-owned package boundary; conditions can require runtime resolution.' };
+    }
+  }
+  return { ...reference, targetFileId: target ? filesByPath.get(target).id : null, resolution: target ? 'resolved' : 'unresolved', reason: target ? '' : 'Target requires external package, alias, build or language resolution context.' };
+}
+
+// Membership is one root per subsystem, regardless of language or UI role.
+// A ready authored map is the sole owner list. Stack campuses only aid an
+// unexplained project's initial inventory; they never split an authored owner.
+export function buildArchitectureFacts({ machine, subsystemMap, program = null, uiDiscovery, packageDiscovery, packages: discoveredPackages = [], stackHash, diagnostics = [], observations = null, previous = null, inventory = [], cityRegions = [] }) {
+  const indexedPaths = new Set(machine.buildings.map(file => file.path));
+  const sourceFiles = [...machine.buildings, ...inventory.filter(file => !indexedPaths.has(file.path)).map(file => ({ ...file, id: `file:${file.path}`, title: path.posix.basename(file.path), language: 'unknown', analysis: 'unsupported', functionIds: [], dependencies: [] }))].sort((a, b) => a.path.localeCompare(b.path));
+  const presentation = inventory.length ? buildCityPresentation({ files: sourceFiles, districts: [], regions: cityRegions }) : { regions: machine.presentationRegions, campuses: machine.presentationCampuses };
+  const authored = new Map((subsystemMap?.subsystems || []).filter(entry => entry.sourceRoot).map(entry => [entry.sourceRoot, entry]));
+  const regions = new Map(presentation.regions.map(entry => [entry.id, entry]));
+  const roots = new Map((subsystemMap?.status === 'valid' ? [] : presentation.campuses).map(campus => {
+    const root = campus.path || '.';
+    return [root, { root, provenance: regions.get(campus.regionId)?.fallback ? 'fallback' : 'stack' }];
+  }));
+  for (const [root, entry] of authored) roots.set(root, { root, provenance: 'authored', authored: entry });
+  const packages = [...new Map(discoveredPackages.map(entry => [entry.id, { ...entry }])).values()];
+  for (const entry of packages.filter(entry => !entry.opaque)) if (subsystemMap?.status !== 'valid' && !roots.has(entry.root)) roots.set(entry.root, { root: entry.root, provenance: 'package' });
+  if (!roots.size) roots.set('.', { root: '.', provenance: 'fallback' });
+  const subsystems = [...roots.values()].map(entry => {
+    const authoredEntry = authored.get(entry.root);
+    return { id: `directory:${entry.root}`, root: entry.root, title: authoredEntry?.title || (entry.root === '.' ? 'Project' : path.posix.basename(entry.root)), description: authoredEntry?.description || '', authoredId: authoredEntry?.id || null, program: authoredEntry?.program || [], dataOwned: authoredEntry?.dataOwned || [], dataUsed: authoredEntry?.dataUsed || [], provenance: entry.provenance, fileIds: [], parentId: null };
+  }).sort((a, b) => b.root.length - a.root.length || a.root.localeCompare(b.root));
+  const authoritative = subsystems.filter(entry => entry.provenance !== 'fallback');
+  const fallback = subsystems.filter(entry => entry.provenance === 'fallback');
+  const files = sourceFiles.map(file => {
+    let owner = authoritative.find(entry => owns(entry.root, file.path)) || fallback.find(entry => owns(entry.root, file.path));
+    if (!owner) {
+      if (subsystemMap?.status === 'valid') throw new GenesisError('SUBSYSTEM_SOURCE_UNOWNED', `No declared subsystem owns ${file.path}. Add its directory to genesis/subsystems.md or declare a project-root owner.`);
+      owner = subsystems.find(entry => entry.root === '.');
+      if (!owner) { owner = { id: 'directory:.', root: '.', title: 'Project', description: '', authoredId: null, provenance: 'fallback', fileIds: [], parentId: null }; subsystems.push(owner); }
+    }
+    owner.fileIds.push(file.id);
+    return { ...file, subsystemId: owner.id };
+  });
+  const visibleSubsystems = subsystems.filter(entry => entry.fileIds.length || entry.provenance === 'authored');
+  for (const entry of packages) {
+    if (entry.opaque) {
+      entry.subsystemId = entry.id;
+      visibleSubsystems.push({ id: entry.id, root: entry.root, title: entry.name, kind: 'package', packageId: entry.id, opaque: true, provenance: 'package', fileIds: [], parentId: null, description: 'External public boundary. Internal files and dependencies are not indexed.' });
+    } else entry.subsystemId = visibleSubsystems.find(owner => owner.root === entry.root || owns(owner.root, entry.root))?.id;
+  }
+  for (const entry of visibleSubsystems) entry.parentId = visibleSubsystems.find(candidate => candidate.provenance !== 'fallback' && candidate.id !== entry.id && owns(candidate.root, entry.root))?.id || null;
+  const filesByPath = new Map(files.map(file => [file.path, file]));
+  const relations = files.flatMap(file => (file.dependencies || []).map((reference, index) => ({
+    id: `dependency:${file.id}:${index}`, fromFileId: file.id, ...resolveReference(file, reference, filesByPath, packages), evidence: { path: file.path, hash: file.hash, start: reference.start, end: reference.end },
+  })));
+  const symbols = [...machine.functions, ...(machine.symbols || [])].map(symbol => ({ ...symbol, start: symbol.start || { line: symbol.line, column: symbol.column }, rangeAvailable: Boolean(symbol.end) }));
+  const sourceHash = sha256(stableJson(files.map(file => ({ path: file.path, hash: file.hash, mode: file.mode }))));
+  let ui = observations ? connectArchitectureObservations(observations, files, packages) : null;
+  if (!observations && previous?.ui) {
+    // Source-only indexing must not erase unchanged consumer observations.
+    // A changed snapshot requires its inspector; never carry guesses forward.
+    if (previous.sourceHash === sourceHash && previous.stackHash === stackHash) {
+      try { ui = connectArchitectureObservations(previous.ui, files, packages); }
+      catch (error) {
+        if (error.code !== 'ARCHITECTURE_OBSERVATIONS_INVALID') throw error;
+      }
+    }
+    if (!ui) diagnostics.push({ code: 'ARCHITECTURE_UI_STALE', message: 'UI observations need refresh against the current source and Stack.' });
+  }
+  const symbolsByFile = new Map();
+  for (const symbol of symbols) if (symbol.visibility === 'public') {
+    if (!symbolsByFile.has(symbol.fileId)) symbolsByFile.set(symbol.fileId, []);
+    symbolsByFile.get(symbol.fileId).push(symbol);
+  }
+  for (const use of ui?.imports || []) {
+    if (use.resolution !== 'resolved') continue;
+    const from = filesByPath.get(use.fromFile);
+    const target = filesByPath.get(use.targetFile);
+    if (!from || !target) continue;
+    const importedSymbolIds = (symbolsByFile.get(target.id) || []).filter(symbol => use.names.includes(symbol.exportName || symbol.name)).map(symbol => symbol.id);
+    const evidence = use.evidence.find(entry => entry.path === from.path);
+    const matching = relations.find(relation => relation.fromFileId === from.id && relation.specifier === use.specifier
+      && relation.start.line === evidence.start.line && relation.start.column === evidence.start.column);
+    const resolved = { targetFileId: target.id, resolution: 'resolved', reason: 'Resolved by the configured source inspector.', importedNames: use.names, importedSymbolIds, typeOnly: use.typeOnly };
+    if (matching) Object.assign(matching, resolved);
+    else relations.push({ id: `dependency:${use.id}`, fromFileId: from.id, kind: 'import', specifier: use.specifier,
+      start: evidence.start, end: evidence.end, evidence, ...resolved });
+  }
+  const packageIdentity = sha256(stableJson(packages));
+  const programFacts = program ? { status: program.status, hash: program.programHash, diagnostics: program.diagnostics,
+    modules: program.buildings.map(module => ({ ...module, subsystemId: visibleSubsystems.find(owner => owner.authoredId === module.subsystem)?.id || null })) } : null;
+  const snapshotId = sha256(stableJson({ sourceHash, stackHash, subsystemIdentity: subsystemMap?.identity || null, programHash: program?.programHash, packages, observations: ui }));
+  return {
+    schema: 'genesis.architecture.v1', snapshotId, codeHash: machine.codeHash, sourceHash, stackHash,
+    subsystems: visibleSubsystems.sort((a, b) => a.root.localeCompare(b.root)), files, symbols, relations,
+    ui, packages, packageIdentity, program: programFacts,
+    uiDiscovery: uiDiscovery || { status: 'unconfigured', discoveries: [] },
+    packageDiscovery: packageDiscovery || { status: 'unconfigured', discoveries: [] },
+    capabilities: { symbols: 'partial', dependencies: 'partial', pages: ui?.capabilities.pages || (uiDiscovery?.status === 'configured' && !uiDiscovery.discoveries.length ? 'complete' : 'unconfigured'), runtimeCalls: 'unsupported' },
+    diagnostics,
+  };
+}
+
+export function validateArchitectureFacts(snapshot) {
+  const check = (condition, message) => { if (!condition) throw new GenesisError('ARCHITECTURE_INVALID', message); };
+  check(snapshot?.schema === 'genesis.architecture.v1' && typeof snapshot.snapshotId === 'string' && snapshot.snapshotId.length > 0, 'Invalid architecture schema or snapshot identity.');
+  const records = name => {
+    check(Array.isArray(snapshot[name]), `${name} must be an array.`);
+    const map = new Map();
+    for (const record of snapshot[name]) {
+      check(record && typeof record.id === 'string' && record.id.length > 0 && !map.has(record.id), `Invalid or duplicate ${name} id.`);
+      map.set(record.id, record);
+    }
+    return map;
+  };
+  const subsystems = records('subsystems'); const files = records('files'); const symbols = records('symbols'); records('relations');
+  const packages = snapshot.packages === undefined ? new Map() : records('packages');
+  if (snapshot.program) {
+    check(typeof snapshot.program.hash === 'string' && Array.isArray(snapshot.program.modules), 'Invalid Program facts.');
+    const moduleIds = new Set();
+    for (const module of snapshot.program.modules) {
+      const owner = subsystems.get(module.subsystemId);
+      check(typeof module.id === 'string' && !moduleIds.has(module.id), 'Invalid or duplicate Program operation.');
+      moduleIds.add(module.id);
+      check(owner && owner.authoredId === module.subsystem && owner.program?.includes(module.path), 'Program operation requires its one declared subsystem owner.');
+      for (const field of ['path', 'title', 'description', 'publicContract', 'implementationMap']) check(typeof module[field] === 'string', 'Invalid Program explanation.');
+      check(Array.isArray(module.sources) && module.sources.every(source => typeof source === 'string' && source !== '.' && path.posix.normalize(source) === source && !path.posix.isAbsolute(source) && !/[\\\0]/u.test(source) && !source.split('/').includes('..')), 'Invalid Program source references.');
+      // Previously saved v1 indexes remain readable until an explicit re-scan.
+      // New authored modules must supply their anchor in inspectProgram.
+      if (module.mainSource !== undefined) {
+        check(typeof module.mainSource === 'string' && module.sources.includes(module.mainSource), 'Program main source must be a cited source.');
+        const mainOwner = [...subsystems.values()].filter(entry => owns(entry.root, module.mainSource)).sort((a, b) => (b.root === '.' ? 0 : b.root.length) - (a.root === '.' ? 0 : a.root.length))[0];
+        check(mainOwner?.id === owner.id, 'Program main source must belong to its declared subsystem.');
+      }
+    }
+  }
+  const roots = new Set();
+  for (const subsystem of subsystems.values()) {
+    check(typeof subsystem.root === 'string' && subsystem.root.length > 0 && path.posix.normalize(subsystem.root) === subsystem.root && !path.posix.isAbsolute(subsystem.root) && !/[\\\0]/u.test(subsystem.root) && !subsystem.root.split('/').includes('..') && !roots.has(subsystem.root), 'Subsystems require unique canonical directory roots.');
+    roots.add(subsystem.root);
+    check(Array.isArray(subsystem.fileIds) && new Set(subsystem.fileIds).size === subsystem.fileIds.length, 'Invalid subsystem file membership.');
+    for (const id of subsystem.fileIds) check(files.get(id)?.subsystemId === subsystem.id, 'Conflicting subsystem ownership.');
+    if (subsystem.parentId != null) {
+      const parent = subsystems.get(subsystem.parentId);
+      check(parent && parent.id !== subsystem.id && owns(parent.root, subsystem.root), 'Subsystem parent must be an enclosing directory owner.');
+    }
+  }
+  const paths = new Set();
+  for (const file of files.values()) {
+    check(typeof file.path === 'string' && file.path.length > 0 && file.path !== '.' && path.posix.normalize(file.path) === file.path && !path.posix.isAbsolute(file.path) && !/[\\\0]/u.test(file.path) && !file.path.split('/').includes('..') && !paths.has(file.path), 'Invalid or duplicate file path.');
+    paths.add(file.path);
+    const owner = subsystems.get(file.subsystemId);
+    check(owner && owns(owner.root, file.path) && owner.fileIds.includes(file.id), 'File has no matching directory owner.');
+    check(typeof file.hash === 'string' && file.hash.length > 0, 'File requires a content hash.');
+  }
+  function range(start, end, file, label) {
+    const point = value => value && Number.isSafeInteger(value.line) && value.line > 0 && Number.isSafeInteger(value.column) && value.column > 0;
+    check(point(start) && point(end) && (end.line > start.line || (end.line === start.line && end.column > start.column)), `${label} has an impossible source range.`);
+    check(!Number.isInteger(file.lines) || (start.line <= file.lines && (end.line <= file.lines || (end.line === file.lines + 1 && end.column === 1))), `${label} range exceeds its source.`);
+  }
+  for (const symbol of snapshot.symbols) {
+    check(files.has(symbol.fileId) && files.get(symbol.fileId).path === symbol.path, 'Symbol references an unknown file.');
+    check(typeof symbol.name === 'string' && typeof symbol.visibility === 'string', 'Invalid public symbol.');
+    check(symbol.visibilityScope === undefined || (typeof symbol.visibilityScope === 'string' && symbol.visibilityScope.length > 0), 'Invalid symbol visibility scope.');
+    check(typeof symbol.rangeAvailable === 'boolean' && symbol.rangeAvailable === Boolean(symbol.end), 'Symbol range availability disagrees with its declaration.');
+    if (symbol.rangeAvailable) range(symbol.start, symbol.end, files.get(symbol.fileId), 'Symbol');
+  }
+  for (const dependency of packages.values()) {
+    const owner = subsystems.get(dependency.subsystemId);
+    check(owner && (owner.root === dependency.root || (!dependency.opaque && owns(owner.root, dependency.root))) && typeof dependency.opaque === 'boolean' && Boolean(owner.opaque) === dependency.opaque, 'Package requires its directory boundary owner.');
+    check(typeof dependency.name === 'string' && dependency.name.length > 0 && typeof dependency.manager === 'string' && files.has(`file:${dependency.manifest}`), 'Package requires a project declaration.');
+    check(Array.isArray(dependency.evidence) && dependency.evidence.some(entry => files.get(`file:${entry.path}`)?.hash === entry.hash && entry.path === dependency.manifest), 'Package declaration evidence is stale.');
+    if (dependency.declarations !== undefined) check(Array.isArray(dependency.declarations) && dependency.declarations.length > 0 && dependency.declarations.every(declaration => typeof declaration.requested === 'string' && Array.isArray(declaration.dependencyKinds) && dependency.evidence.some(entry => entry.path === declaration.manifest && files.get(`file:${entry.path}`)?.hash === entry.hash)), 'Package declarations require current project evidence.');
+    check(['complete', 'partial', 'unsupported'].includes(dependency.symbolCoverage) && Array.isArray(dependency.entryPoints), 'Invalid package interface coverage.');
+    for (const entry of dependency.entryPoints) {
+      check(typeof entry.importPath === 'string' && typeof entry.target === 'string' && Array.isArray(entry.conditions) && entry.conditions.every(condition => typeof condition === 'string') && Array.isArray(entry.symbols) && ['complete', 'partial', 'unsupported'].includes(entry.coverage), 'Invalid package entry point.');
+      if (entry.file != null) check(typeof entry.file === 'string' && path.posix.normalize(entry.file) === entry.file && !path.posix.isAbsolute(entry.file) && !/[\\\0]/u.test(entry.file) && !entry.file.split('/').includes('..') && owns(dependency.root, entry.file), 'Package entry must stay inside its directory root.');
+      for (const symbol of entry.symbols) {
+        check(typeof symbol.name === 'string' && symbol.visibility === 'public' && typeof entry.hash === 'string' && entry.hash.length > 0, 'Public package symbol requires hashed entry evidence.');
+        if (symbol.sourceFile !== undefined) check(dependency.opaque ? symbol.sourceFile === entry.file && symbol.sourceHash === entry.hash : files.get(`file:${symbol.sourceFile}`)?.hash === symbol.sourceHash && typeof symbol.sourceHash === 'string', 'Public declaration source must match current indexed evidence.');
+        if (symbol.end) range(symbol.start, symbol.end, {}, 'Package symbol');
+      }
+    }
+  }
+  for (const relation of snapshot.relations) {
+    check(files.has(relation.fromFileId) && ['resolved', 'unresolved', 'ambiguous'].includes(relation.resolution), 'Invalid dependency source or resolution.');
+    check(relation.typeOnly === undefined || typeof relation.typeOnly === 'boolean', 'Dependency type-only classification must be boolean when provided.');
+    if (relation.resolution === 'resolved') check(files.has(relation.targetFileId) || packages.has(relation.targetPackageId), 'Dependency references an unknown target.');
+    if (relation.targetPackageId != null) check(packages.has(relation.targetPackageId), 'Dependency references an unknown package.');
+    if (relation.importedNames !== undefined) check(Array.isArray(relation.importedNames) && relation.importedNames.every(name => typeof name === 'string' && name.length > 0), 'Imported names must be explicit.');
+    if (relation.importedSymbolIds !== undefined) check(Array.isArray(relation.importedSymbolIds) && relation.importedSymbolIds.every(id => symbols.get(id)?.fileId === relation.targetFileId && symbols.get(id)?.visibility === 'public'), 'Imported declarations must belong to the resolved target.');
+    check(relation.evidence?.hash === files.get(relation.fromFileId).hash && relation.evidence.path === files.get(relation.fromFileId).path, 'Dependency evidence disagrees with its source.');
+    range(relation.evidence.start, relation.evidence.end, files.get(relation.fromFileId), 'Dependency');
+  }
+  check(snapshot.capabilities && typeof snapshot.capabilities === 'object' && Array.isArray(snapshot.diagnostics), 'Missing architecture coverage or diagnostics.');
+  for (const name of ['symbols', 'dependencies', 'pages', 'runtimeCalls']) check(['complete', 'partial', 'unsupported', 'unconfigured'].includes(snapshot.capabilities[name]), 'Invalid architecture coverage.');
+  if (snapshot.ui) {
+    const recomputed = connectArchitectureObservations(snapshot.ui, snapshot.files, snapshot.packages || []);
+    check(stableJson(recomputed.connections) === stableJson(snapshot.ui.connections), 'Controller connections disagree with their evidence.');
+  }
+  return snapshot;
+}

package/src/index/code-index.js

@@ -1,13 +1,16 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, lstat } from 'node:fs/promises';
 import path from 'node:path';
 
 import { extractCodeIndexes } from './code-indexers/ast-grep.js';
-import { asDiagnostic } from './errors.js';
+import { inspectNpmPackages, recheckNpmInputs } from './code-indexers/npm-packages.js';
+import { asDiagnostic, GenesisError } from './errors.js';
 import { buildCityPresentation } from './city-presentation.js';
 import { cityPathExcluded } from './stack-city-presentation.js';
 import { gitContext } from './git.js';
 import { isProjectContentPath } from './paths.js';
 import { inspectProgram } from './program.js';
+import { inspectSubsystems } from './subsystems.js';
+import { buildArchitectureFacts } from './architecture.js';
 import { gitVisibleFileStates } from './project-files.js';
 import { readStack } from './stack.js';
 import { sha256, stableJson, writeFileAtomic } from './utils.js';
@@ -83,6 +86,7 @@ function normalizedFunction(entry, file, extractor) {
     qualifiedName,
     kind: entry.kind,
     visibility: entry.visibility,
+    ...(entry.visibilityScope ? { visibilityScope: entry.visibilityScope } : {}),
     container: entry.container || null,
     path: file.path,
     fileId: fileId(file.path),
@@ -92,6 +96,7 @@ function normalizedFunction(entry, file, extractor) {
     async: entry.async === true,
     generator: entry.generator === true,
     static: entry.static === true,
+    ...(entry.start && entry.end ? { start: entry.start, end: entry.end } : {}),
     role: file.role,
     language: file.language,
     extractor,
@@ -101,6 +106,7 @@ function normalizedFunction(entry, file, extractor) {
 function mergeIndexedFiles(contributions) {
   const files = new Map();
   const functions = [];
+  const symbols = [];
   for (const contribution of contributions) {
     for (const file of contribution.files || []) {
       const existing = files.get(file.path);
@@ -115,6 +121,7 @@ function mergeIndexedFiles(contributions) {
         hash: file.hash,
         extractors: [],
         functionIds: [],
+        dependencies: file.dependencies || [],
       };
       if (!record.extractors.includes(contribution.extractor)) record.extractors.push(contribution.extractor);
       for (const entry of file.functions || []) {
@@ -122,11 +129,13 @@ function mergeIndexedFiles(contributions) {
         functions.push(normalized);
         record.functionIds.push(normalized.id);
       }
+      for (const entry of file.symbols || []) symbols.push({ ...entry, id: `symbol:${file.path}:${entry.qualifiedName}:${entry.kind}:${entry.line}:${entry.column}`, fileId: fileId(file.path), path: file.path, language: file.language, extractor: contribution.extractor });
       files.set(file.path, record);
     }
   }
   return {
     files: [...files.values()].sort((left, right) => left.path.localeCompare(right.path)),
+    symbols,
     functions: functions.sort((left, right) => (
       left.path.localeCompare(right.path) || left.line - right.line || left.qualifiedName.localeCompare(right.qualifiedName)
     )),
@@ -158,6 +167,7 @@ function machineCity({ cityRegions, components, contributions, diagnostics, inde
     indexers,
     diagnostics,
     functions: merged.functions,
+    symbols: merged.symbols,
     districts: structuralDistricts.map((district) => ({
       ...district,
       ...presentation.placementForPath(district.path),
@@ -187,6 +197,7 @@ async function programCity(projectRoot) {
       subsystem: module.subsystem,
       districtId: module.subsystem === null ? null : subsystemId(module.subsystem),
       sources: module.sources,
+      mainSource: module.mainSource,
       sourceFileIds: module.sources.map(fileId),
     }));
     return {
@@ -219,7 +230,7 @@ async function programCity(projectRoot) {
 
 async function writeIfChanged(projectRoot, relativePath, value) {
   const location = path.join(projectRoot, relativePath);
-  const source = stableJson(value);
+  const source = stableJson(value, { space: 0 });
   try {
     if (await readFile(location, 'utf8') === source) return false;
   } catch (error) {
@@ -246,10 +257,17 @@ export async function buildProjectIndex({
   queries = [],
   stackPackages = [],
   write = true,
+  observations = null,
+  signal,
 } = {}) {
+  signal?.throwIfAborted();
+  const observationReader = typeof observations === 'function' ? observations : null;
+  if (observationReader) observations = null;
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root, { stackPackages });
-  const states = await gitVisibleFileStates(root, { includePath: isProjectContentPath });
+  const packageRoots = stack.packageDiscovery.discoveries.flatMap(discovery => discovery.manifests.map(manifest => path.posix.join(path.posix.dirname(manifest), discovery.packageRoot)));
+  const includePath = filePath => isProjectContentPath(filePath) && !packageRoots.some(directory => filePath === directory || filePath.startsWith(`${directory}/`));
+  const states = await gitVisibleFileStates(root, { includePath });
   const files = [...states]
     .filter(([filePath, state]) => (
       state.exists
@@ -260,7 +278,7 @@ export async function buildProjectIndex({
     ))
     .map(([filePath, state]) => ({ path: filePath, hash: state.hash, mode: state.mode }));
   const indexers = [...new Set(stack.components.flatMap((component) => component.indexers || []))].sort();
-  const { contributions, diagnostics } = await extractCodeIndexes({ indexers, files, projectRoot: root });
+  const { contributions, diagnostics } = await extractCodeIndexes({ indexers, files, projectRoot: root, signal });
   const machine = machineCity({
     cityRegions: stack.cityRegions,
     components: stack.components.map(({ id }) => id),
@@ -269,13 +287,55 @@ export async function buildProjectIndex({
     indexers,
   });
   const program = await programCity(root);
+  const subsystemMap = await inspectSubsystems({ projectRoot: root });
+  const architectureDiagnostics = [];
+  for (const entry of subsystemMap.subsystems) {
+    try {
+      const parts = entry.sourceRoot === '.' ? [] : entry.sourceRoot.split('/');
+      for (let index = 0; index <= parts.length; index++) {
+        const info = await lstat(path.join(root, ...parts.slice(0, index)));
+        if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('Source root must be a real project directory without symbolic links.');
+      }
+    } catch (error) { architectureDiagnostics.push({ code: 'SUBSYSTEM_SOURCE_UNAVAILABLE', path: entry.sourceRoot, message: error.message }); }
+  }
+  const packages = []; const packageInputs = [];
+  for (const discovery of stack.packageDiscovery.discoveries) {
+    signal?.throwIfAborted();
+    if (discovery.adapter !== 'npm') { architectureDiagnostics.push({ code: 'PACKAGE_ADAPTER_UNSUPPORTED', path: discovery.manifests[0], message: `Package adapter ${discovery.adapter} has no installed inspector; public boundaries are unavailable.` }); continue; }
+    const inspected = await inspectNpmPackages({ projectRoot: root, discovery, files, indexedFiles: contributions.flatMap(contribution => contribution.files), signal });
+    packages.push(...inspected.packages); packageInputs.push(...inspected.inputs); architectureDiagnostics.push(...inspected.diagnostics);
+  }
+  let previous;
+  if (!observations && !observationReader) {
+    try { previous = JSON.parse(await readFile(path.join(root, MACHINE_CITY_PATH), 'utf8')).architecture; }
+    catch (error) { if (!(error instanceof SyntaxError) && !['ENOENT', 'ENOTDIR'].includes(error.code)) throw error; }
+  }
+  machine.architecture = buildArchitectureFacts({ machine, subsystemMap, program, uiDiscovery: stack.uiDiscovery, packageDiscovery: stack.packageDiscovery, packages, stackHash: stack.identityHash, diagnostics: architectureDiagnostics, observations, previous, inventory: files, cityRegions: stack.cityRegions });
+  if (observationReader) {
+    signal?.throwIfAborted();
+    observations = await observationReader(machine.architecture);
+    signal?.throwIfAborted();
+    if (!observations) throw new GenesisError('ARCHITECTURE_OBSERVATIONS_INVALID', 'An architecture inspector must return its observation document.');
+    machine.architecture = buildArchitectureFacts({ machine, subsystemMap, program, uiDiscovery: stack.uiDiscovery, packageDiscovery: stack.packageDiscovery, packages, stackHash: stack.identityHash, diagnostics: architectureDiagnostics, observations, inventory: files, cityRegions: stack.cityRegions });
+  }
+  // Do not publish a join from different revisions or destroy the previous
+  // valid artifact after an inspector/parser read racing a source change.
+  const finalStates = await gitVisibleFileStates(root, { includePath });
+  const finalFiles = [...finalStates].filter(([filePath, state]) => state.exists && !state.symlink && !state.special && state.hash && !cityPathExcluded(filePath, stack.cityExclusions)).map(([filePath, state]) => ({ path: filePath, hash: state.hash, mode: state.mode }));
+  const finalStack = await readStack(root, { stackPackages });
+  const finalMap = await inspectSubsystems({ projectRoot: root }).catch(() => null);
+  if (stableJson(finalFiles) !== stableJson(files) || finalStack.identityHash !== stack.identityHash || (finalMap?.identity || null) !== (subsystemMap?.identity || null)) {
+    throw new GenesisError('ARCHITECTURE_SOURCE_CHANGED', 'Source or Stack changed during architecture analysis. The previous index is retained; refresh after the changes settle.');
+  }
+  signal?.throwIfAborted();
+  await recheckNpmInputs(root, packageInputs, signal);
   const changedFiles = [];
   if (write) {
     if (await writeIfChanged(root, MACHINE_CITY_PATH, machine)) changedFiles.push(MACHINE_CITY_PATH);
     if (await writeIfChanged(root, PROGRAM_CITY_PATH, program)) changedFiles.push(PROGRAM_CITY_PATH);
   }
   const allMatches = machine.functions.filter((entry) => functionMatches(entry, queries));
-  const allDiagnostics = [...diagnostics, ...program.diagnostics];
+  const allDiagnostics = [...diagnostics, ...program.diagnostics, ...architectureDiagnostics];
   return {
     status: allDiagnostics.length > 0 ? 'completed-with-warning' : 'ready',
     summary: [