genesis-compiler 1.5.2 → 1.7.0

package/src/index/code-indexers/ast-grep.js

@@ -1,18 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
-import bashLanguage from '@ast-grep/lang-bash';
-import cLanguage from '@ast-grep/lang-c';
-import cppLanguage from '@ast-grep/lang-cpp';
-import csharpLanguage from '@ast-grep/lang-csharp';
-import goLanguage from '@ast-grep/lang-go';
-import javaLanguage from '@ast-grep/lang-java';
-import kotlinLanguage from '@ast-grep/lang-kotlin';
-import phpLanguage from '@ast-grep/lang-php';
-import pythonLanguage from '@ast-grep/lang-python';
-import rubyLanguage from '@ast-grep/lang-ruby';
-import rustLanguage from '@ast-grep/lang-rust';
-import { parseAsync, registerDynamicLanguage } from '@ast-grep/napi';
+import { fileURLToPath } from 'node:url';
+import { asDiagnostic } from '../errors.js';
+import { runProcess } from '../process.js';
+import { parserAbortSignal, prepareCodeParsers } from './parsers.js';
 
 const MAX_SOURCE_BYTES = 4 * 1024 * 1024;
 const OPENING_PARAMETER_DELIMITERS = '([{<';
@@ -22,20 +14,6 @@ const EXCLUDED_DIRECTORIES = new Set([
   'node_modules', 'storage', 'target', 'vendor',
 ]);
 
-registerDynamicLanguage({
-  bash: bashLanguage,
-  c: cLanguage,
-  cpp: cppLanguage,
-  csharp: csharpLanguage,
-  go: goLanguage,
-  java: javaLanguage,
-  kotlin: kotlinLanguage,
-  php: phpLanguage,
-  python: pythonLanguage,
-  ruby: rubyLanguage,
-  rust: rustLanguage,
-});
-
 function javascriptParser(filePath) {
   if (/\.tsx$/u.test(filePath)) return 'Tsx';
   if (/\.ts$/u.test(filePath)) return 'TypeScript';
@@ -350,7 +328,7 @@ function createIndexer(id) {
   const definition = DEFINITIONS[id];
   return {
     id,
-    async extract({ files, projectRoot }) {
+    async extract({ files, projectRoot, parseAsync, parserErrors = {} }) {
       const indexedFiles = [];
       const diagnostics = [];
       for (const file of files.filter((candidate) => isCandidate(candidate, definition))) {
@@ -377,6 +355,10 @@ function createIndexer(id) {
         const functions = [];
         for (const unit of scriptUnits(source, file.path, definition)) {
           try {
+            if (parserErrors[unit.parser]) {
+              diagnostics.push({ ...parserErrors[unit.parser], path: file.path });
+              continue;
+            }
             const parsed = await parseAsync(unit.parser, unit.source);
             const root = parsed.root();
             functions.push(...functionsInTree(root, definition, {
@@ -386,8 +368,9 @@ function createIndexer(id) {
             }));
             diagnostics.push(...syntaxDiagnostics(root, file.path, unit.lineOffset));
           } catch (error) {
+            if (error.code === 'PROCESS_ABORTED') throw error;
             diagnostics.push({
-              code: 'CODE_INDEX_PARSE_FAILED',
+              code: error.code?.startsWith('PARSER_') ? error.code : 'CODE_INDEX_PARSE_FAILED',
               message: error.message,
               path: file.path,
             });
@@ -412,3 +395,32 @@ function createIndexer(id) {
 export const astGrepCodeIndexers = new Map(
   Object.keys(DEFINITIONS).map((id) => [id, createIndexer(id)]),
 );
+
+// ast-grep permits one registration per process. A finite indexing child loads
+// this request's languages once and releases every native parser when it exits.
+export async function extractCodeIndexes({ indexers, files, projectRoot }) {
+  const selected = indexers.filter(id => astGrepCodeIndexers.has(id));
+  const diagnostics = indexers.filter(id => !astGrepCodeIndexers.has(id)).map(id => ({
+    code: 'CODE_INDEXER_UNAVAILABLE', message: `No installed code indexer exists for ${id}.`,
+  }));
+  const languages = selected.flatMap(id => files.filter(file => isCandidate(file, DEFINITIONS[id]))
+    .map(file => typeof DEFINITIONS[id].parser === 'function'
+      ? DEFINITIONS[id].parser(file.path) : DEFINITIONS[id].parser));
+  if (languages.length === 0) return { contributions: [], diagnostics };
+  const { registrations, errors } = await prepareCodeParsers(languages);
+  let contributions;
+  try {
+    const result = await runProcess(process.execPath, [fileURLToPath(new URL('./worker.js', import.meta.url))], {
+      input: JSON.stringify({ indexers: selected, files, projectRoot, registrations, errors }),
+      signal: parserAbortSignal(), timeoutMs: 180_000, code: 'CODE_INDEXER_FAILED',
+    });
+    contributions = JSON.parse(result.stdout.toString('utf8'));
+  } catch (error) {
+    if (error.code === 'PROCESS_ABORTED') throw error;
+    return { contributions: [], diagnostics: [...diagnostics, {
+      ...asDiagnostic(error), code: 'CODE_INDEXER_FAILED',
+    }] };
+  }
+  return { contributions, diagnostics: [...diagnostics, ...contributions.flatMap(value =>
+    value.diagnostics.map(diagnostic => ({ ...diagnostic, extractor: value.extractor }))) ] };
+}

package/src/index/code-indexers/parsers.js

@@ -0,0 +1,231 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { access, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+
+import { GenesisError, fail } from '../errors.js';
+import { runProcess } from '../process.js';
+
+const require = createRequire(import.meta.url);
+const PACKAGES = Object.freeze({
+  bash: ['0.0.8', 'function example() { echo hello; }'],
+  c: ['0.0.6', 'int example(void) { return 1; }'],
+  cpp: ['0.0.6', 'int example() { return 1; }'],
+  csharp: ['0.0.6', 'class Example { public int Run() { return 1; } }'],
+  go: ['0.0.6', 'package example\nfunc Example() int { return 1 }'],
+  java: ['0.0.7', 'class Example { public int run() { return 1; } }'],
+  kotlin: ['0.0.7', 'fun example(): Int { return 1 }'],
+  php: ['0.0.7', '<?php function example() { return 1; }'],
+  python: ['0.0.6', 'def example():\n    return 1\n'],
+  ruby: ['0.0.7', 'def example\n  1\nend'],
+  rust: ['0.0.7', 'fn example() -> i32 { 1 }'],
+});
+const installations = new Map();
+const cancellation = new AsyncLocalStorage();
+
+export function parserAbortSignal() {
+  return cancellation.getStore();
+}
+
+export function withParserCancellation(signal, operation) {
+  return cancellation.run(signal, operation);
+}
+
+function parserDefinition(language) {
+  if (language === 'javascript') return { language, package: '@ast-grep/napi', version: require('@ast-grep/napi/package.json').version, sample: 'function example() { return 1; }' };
+  if (!Object.hasOwn(PACKAGES, language)) {
+    fail('PARSER_UNKNOWN', `Unknown parser: ${language}. Run genesis parsers list.`);
+  }
+  const [version, sample] = PACKAGES[language];
+  return { language, package: `@ast-grep/lang-${language}`, version, sample };
+}
+
+function parserRoot(directory, environment = process.env) {
+  const root = directory || environment.GENESIS_PARSER_ROOT
+    || path.join(environment.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'genesis', 'parsers');
+  if (!path.isAbsolute(root)) fail('PARSER_ROOT_INVALID', 'The parser directory must be an absolute path.');
+  return root;
+}
+
+export function parserEnvironment({ directory, autoInstall, environment = process.env } = {}) {
+  const automatic = autoInstall === undefined ? environment.GENESIS_PARSER_AUTO_INSTALL ?? '1' : autoInstall ? '1' : '0';
+  if (!['0', '1'].includes(automatic)) fail('PARSER_POLICY_INVALID', 'GENESIS_PARSER_AUTO_INSTALL must be 0 or 1.');
+  return { GENESIS_PARSER_ROOT: parserRoot(directory, environment), GENESIS_PARSER_AUTO_INSTALL: automatic };
+}
+
+function parserLocation(definition, root) {
+  return path.join(root, definition.language, definition.version, `${process.platform}-${process.arch}`);
+}
+
+async function installedParser(definition, directory) {
+  if (definition.language === 'javascript') return { entry: '', packageRoot: null };
+  try {
+    await access(directory);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  const packageRoot = path.join(directory, 'node_modules', definition.package);
+  try {
+    const manifest = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+    if (manifest.name !== definition.package || manifest.version !== definition.version) {
+      throw new Error(`Expected ${definition.package}@${definition.version}.`);
+    }
+    const entry = path.join(packageRoot, 'index.js');
+    await access(entry);
+    return { entry, packageRoot };
+  } catch (error) {
+    throw new GenesisError('PARSER_INSTALL_INVALID', `Parser installation is invalid at ${directory}: ${error.message}`, { directory });
+  }
+}
+
+// Validate in a child so its native library is closed before moving the install,
+// and preparing all languages never loads them into the hosting process.
+async function verifyParser(definition, installation, signal) {
+  const source = `
+    const { createRequire } = await import('node:module');
+    const require = createRequire(import.meta.url);
+    const [core, entry, language, sample] = process.argv.slice(1);
+    const { registerDynamicLanguage, parseAsync } = require(core);
+    const definition = entry ? require(entry) : null;
+    if (definition) registerDynamicLanguage({ [language]: definition });
+    const root = (await parseAsync(definition ? language : 'JavaScript', sample)).root();
+    if (root.findAll({ rule: { kind: 'ERROR' } }).length) throw new Error('Parser smoke check failed.');
+    process.stdout.write(definition?.libraryPath || '');
+  `;
+  const result = await runProcess(process.execPath, [
+    '--input-type=module', '-e', source,
+    require.resolve('@ast-grep/napi'), installation.entry, definition.language, definition.sample,
+  ], { signal, timeoutMs: 30_000, code: 'PARSER_VERIFY_FAILED' });
+  return result.stdout.toString('utf8');
+}
+
+async function installParser(definition, root, { signal, onProgress, environment = process.env }) {
+  const destination = parserLocation(definition, root);
+  const existing = await installedParser(definition, destination);
+  if (existing) return existing;
+  onProgress?.(`Preparing ${definition.language} code indexing (${definition.package}@${definition.version})…`);
+  await mkdir(path.dirname(destination), { recursive: true });
+  const staging = await mkdtemp(`${destination}.install-`);
+  try {
+    await writeFile(path.join(staging, 'package.json'), JSON.stringify({ private: true }));
+    // Windows cannot spawn npm.cmd without a shell; invoke npm's JavaScript
+    // entry with Node so cache paths are never interpreted as shell code.
+    const npmCli = process.platform === 'win32'
+      ? environment.npm_execpath || path.join(path.dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js')
+      : null;
+    await runProcess(npmCli ? process.execPath : 'npm', [
+      ...(npmCli ? [npmCli] : []),
+      'install', '--prefix', staging, '--ignore-scripts', '--no-audit', '--no-fund',
+      '--omit=dev', '--omit=optional', '--package-lock=false', '--save-exact',
+      '--registry=https://registry.npmjs.org', `${definition.package}@${definition.version}`,
+    ], { cwd: staging, env: environment, signal, timeoutMs: 180_000, code: 'PARSER_INSTALL_FAILED' });
+    const installation = await installedParser(definition, staging);
+    const libraryPath = await verifyParser(definition, installation, signal);
+    const prebuilds = path.join(installation.packageRoot, 'prebuilds');
+    const selected = path.dirname(libraryPath);
+    if (path.dirname(selected) !== prebuilds) {
+      fail('PARSER_PLATFORM_UNSUPPORTED', `No packaged parser binary is available for ${process.platform}-${process.arch}.`);
+    }
+    // The prepared cache is for this host. Keep upstream metadata and loader,
+    // but omit build sources and binaries for other operating systems.
+    await rm(path.join(installation.packageRoot, 'src'), { recursive: true, force: true });
+    for (const entry of await readdir(prebuilds)) {
+      if (path.join(prebuilds, entry) !== selected) {
+        await rm(path.join(prebuilds, entry), { recursive: true, force: true });
+      }
+    }
+    await verifyParser(definition, installation, signal);
+    try {
+      await rename(staging, destination);
+    } catch (error) {
+      // Concurrent processes may prepare the same immutable version. Only a
+      // complete, independently verified directory can win the atomic rename.
+      if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error;
+      await installedParser(definition, destination);
+    }
+    return await installedParser(definition, destination);
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}
+
+function ensureInstalled(definition, root, options) {
+  const key = parserLocation(definition, root);
+  if (!installations.has(key)) {
+    const pending = installParser(definition, root, options).finally(() => installations.delete(key));
+    installations.set(key, pending);
+  }
+  return installations.get(key);
+}
+
+function selectedParsers(languages, all) {
+  if (all && languages.length) fail('PARSER_SELECTION_INVALID', 'Choose parser names or --all, not both.');
+  if (!all && !languages.length) fail('PARSER_SELECTION_REQUIRED', 'Name a parser or use --all.');
+  return [...new Set(all ? ['javascript', ...Object.keys(PACKAGES)] : languages)].map(parserDefinition);
+}
+
+export async function listParsers({ directory, environment = process.env } = {}) {
+  const root = parserRoot(directory, environment);
+  const parsers = [{ language: 'javascript', status: 'built-in', package: '@ast-grep/napi' }];
+  for (const language of Object.keys(PACKAGES)) {
+    const definition = parserDefinition(language);
+    try {
+      const installed = await installedParser(definition, parserLocation(definition, root));
+      parsers.push({ language, package: definition.package, version: definition.version, status: installed ? 'installed' : 'missing' });
+    } catch (error) {
+      parsers.push({ language, package: definition.package, version: definition.version, status: 'invalid', message: error.message });
+    }
+  }
+  return { status: 'ready', directory: root, parsers };
+}
+
+export async function installParsers({ languages = [], all = false, directory, environment = process.env, signal, onProgress } = {}) {
+  const definitions = selectedParsers(languages, all);
+  const root = parserRoot(directory, environment);
+  for (const definition of definitions) {
+    const installation = await ensureInstalled(definition, root, { signal, onProgress, environment });
+    await verifyParser(definition, installation, signal);
+  }
+  return { status: 'ready', directory: root, languages: definitions.map(({ language }) => language) };
+}
+
+export async function verifyParsers({ languages = [], all = false, directory, environment = process.env, signal } = {}) {
+  const definitions = selectedParsers(languages, all);
+  const root = parserRoot(directory, environment);
+  for (const definition of definitions) {
+    const installation = await installedParser(definition, parserLocation(definition, root));
+    if (!installation) fail('PARSER_NOT_INSTALLED', `${definition.language} is not installed in ${root}. Run genesis parsers install ${definition.language}.`);
+    await verifyParser(definition, installation, signal);
+  }
+  return { status: 'ready', directory: root, languages: definitions.map(({ language }) => language) };
+}
+
+export async function prepareCodeParsers(languages, { environment = process.env, signal = cancellation.getStore() } = {}) {
+  const policy = parserEnvironment({ environment });
+  const root = policy.GENESIS_PARSER_ROOT;
+  const registrations = {};
+  const errors = {};
+  for (const language of new Set(languages)) {
+    if (['JavaScript', 'TypeScript', 'Tsx'].includes(language)) continue;
+    try {
+      const definition = parserDefinition(language);
+      let installation = await installedParser(definition, parserLocation(definition, root));
+      if (!installation) {
+        if (policy.GENESIS_PARSER_AUTO_INSTALL === '0') {
+          fail('PARSER_NOT_INSTALLED', `${language} is not installed in ${root}; automatic parser installation is disabled.`);
+        }
+        installation = await ensureInstalled(definition, root, {
+          signal, environment, onProgress: (message) => process.stderr.write(`[genesis] ${message}\n`),
+        });
+      }
+      // Read the upstream loader's data without loading the native library.
+      registrations[language] = { ...require(installation.entry) };
+    } catch (error) {
+      if (error.code === 'PROCESS_ABORTED') throw error;
+      errors[language] = { code: error.code || 'PARSER_LOAD_FAILED', message: error.message };
+    }
+  }
+  return { registrations, errors };
+}

package/src/index/code-indexers/worker.js

@@ -0,0 +1,20 @@
+import { parseAsync, registerDynamicLanguage } from '@ast-grep/napi';
+import { astGrepCodeIndexers } from './ast-grep.js';
+
+try {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  if (Object.keys(input.registrations).length) registerDynamicLanguage(input.registrations);
+  const contributions = [];
+  for (const id of input.indexers) {
+    const result = await astGrepCodeIndexers.get(id).extract({
+      files: input.files, projectRoot: input.projectRoot, parseAsync, parserErrors: input.errors,
+    });
+    contributions.push({ ...result, extractor: id });
+  }
+  process.stdout.write(JSON.stringify(contributions));
+} catch (error) {
+  process.stderr.write(`${error.stack || error}\n`);
+  process.exitCode = 1;
+}

package/src/index/context.js

@@ -111,6 +111,11 @@ export async function contextForProjectPaths({ paths, projectRoot, stackPackages
     '',
     'Use Program as a concise, fallible explanation. Code, tests, and runtime behavior remain the evidence.',
     '',
+    '## Relevant subsystems',
+    '',
+    ...(['missing', 'empty'].includes(program.subsystemMap?.status) ? ['The subsystem map needs authoring. Before implementation, create genesis/subsystems.md from source, schema, and existing Program; preserve existing explanations and do not infer ownership from folders.'] : []),
+    ...((program.subsystemMap?.subsystems || []).filter((entry) => targets.includes('') || modules.some((module) => module.subsystem === entry.id)).map((entry) => JSON.stringify(entry, null, 2))),
+    '',
     '## Relevant Program',
     '',
     ...programDetails,
@@ -147,6 +152,7 @@ export async function contextForProjectPaths({ paths, projectRoot, stackPackages
     status: 'ready',
     paths: targets,
     modules: moduleSources.map(({ source: _source, ...module }) => module),
+    subsystems: (program.subsystemMap?.subsystems || []).filter((entry) => targets.includes('') || modules.some((module) => module.subsystem === entry.id)),
     components: stack.components.map(({ id }) => id),
     engineeringProfile: engineering.profile.id,
     verificationCommands: stack.verificationCommands.map(({ label, argv }) => ({ label, argv })),

package/src/index/contracts.js

@@ -1,4 +1,5 @@
 export const GENESIS_CONTRACTS = Object.freeze({
+  subsystems: 'genesis.subsystems.v0',
   projectInspection: 'genesis.project-inspection.v1',
   templates: 'genesis.templates.v1',
   templateApplication: 'genesis.template-application.v1',

package/src/index/init.js

@@ -1,3 +1,4 @@
+import { SUBSYSTEMS_PATH, EMPTY_SUBSYSTEMS_SOURCE } from './subsystems.js';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
@@ -40,6 +41,7 @@ export async function initializeProject({ projectRoot, stackPackages = [] } = {}
   const projectFormat = await inspectProjectFormatAtRoot(root);
   requireCurrentProjectFormat(projectFormat, { allowUninitialized: true });
   const created = (await Promise.all([
+    createIfMissing(root, SUBSYSTEMS_PATH, EMPTY_SUBSYSTEMS_SOURCE),
     createIfMissing(root, BLUEPRINT_PATH, BLUEPRINT_SKELETON_SOURCE),
     createIfMissing(root, COLLABORATION_PATH, COLLABORATION_SKELETON_SOURCE),
     createIfMissing(root, ENGINEERING_PATH, ENGINEERING_SKELETON_SOURCE),

package/src/index/process.js

@@ -38,6 +38,7 @@ function signalProcessTree(child, signal) {
 
 function executeFile(command, args, {
   maxBuffer,
+  input,
   signal,
   terminationGraceMs = DEFAULT_TERMINATION_GRACE_MS,
   timeoutMs,
@@ -130,7 +131,10 @@ function executeFile(command, args, {
       )), timeoutMs);
       timeoutTimer.unref?.();
     }
-    child.stdin?.end();
+    child.stdin?.on('error', (error) => {
+      if (error.code !== 'EPIPE') spawnError = error;
+    });
+    child.stdin?.end(input);
   });
 }
 
@@ -156,6 +160,7 @@ export async function runProcess(command, args, {
   env = process.env,
   maxBytes = 32 * 1024 * 1024,
   code = 'PROCESS_EXEC_FAILED',
+  input,
   signal,
   terminationGraceMs,
   timeoutMs,
@@ -168,6 +173,7 @@ export async function runProcess(command, args, {
       encoding: 'buffer',
       maxBuffer: maxBytes,
       shell: false,
+      input,
       signal,
       terminationGraceMs,
       timeoutMs,

package/src/index/program.js

@@ -1,6 +1,7 @@
 import { readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 
+import { inspectSubsystems } from './subsystems.js';
 import { GenesisError } from './errors.js';
 import { isProjectContentPath, PROGRAM_ROOT } from './paths.js';
 import { normalizeRelative } from './utils.js';
@@ -55,16 +56,15 @@ function moduleIdentity(programPath) {
   const relative = programPath.slice(`${PROGRAM_ROOT}/`.length, -3);
   const normalized = normalizeRelative(relative);
   const segments = normalized.split('/');
-  if (segments.length < 2 || segments.some((segment) => !CONCEPT_NAME.test(segment))) {
+  if (segments.some((segment) => !CONCEPT_NAME.test(segment))) {
     throw new GenesisError(
       'PROGRAM_INVALID',
-      `Program module needs lowercase conceptual subsystem and operation names: ${programPath}.`,
+      `Program module needs lowercase path names: ${programPath}.`,
       { path: programPath },
     );
   }
   return {
     name: segments.at(-1),
-    subsystem: segments.slice(0, -1).join('/'),
   };
 }
 
@@ -93,13 +93,12 @@ function moduleContents(source, programPath) {
   const sources = sourceLines.map((line) => line.match(SOURCE_LINE)?.[1]);
   const nextHeading = headings.find(({ index }) => index > contractHeading[0].index);
   const contractLines = lines
-    .slice(contractHeading[0].index + 1, nextHeading?.index ?? lines.length)
-    .filter((line) => line.trim());
+    .slice(contractHeading[0].index + 1, nextHeading?.index ?? lines.length);
   if (
     sources.length === 0
     || sources.some((sourcePath) => sourcePath === undefined)
     || new Set(sources).size !== sources.length
-    || contractLines.length === 0
+    || !contractLines.some((line) => line.trim())
   ) {
     throw new GenesisError(
       'PROGRAM_INVALID',
@@ -136,8 +135,13 @@ function moduleContents(source, programPath) {
 
 export async function inspectProgram(projectRoot) {
   const { files, found } = await markdownFiles(projectRoot);
+  const subsystemMap = await inspectSubsystems({ projectRoot });
+  const assignments = new Map(subsystemMap.subsystems.flatMap((entry) => entry.program.map((file) => [file, entry.id])));
+  for (const file of assignments.keys()) {
+    if (!files.includes(file)) throw new GenesisError('SUBSYSTEMS_PROGRAM_MISSING', `Subsystem cites missing Program module: ${file}.`);
+  }
   if (!found || files.length === 0) {
-    return { status: 'missing', files: [], modules: [], subsystems: [] };
+    return { status: subsystemMap.status === 'valid' ? 'valid' : 'missing', files: [], modules: [], subsystems: subsystemMap.subsystems.map(({ id }) => id), subsystemMap };
   }
 
   const modules = [];
@@ -150,6 +154,7 @@ export async function inspectProgram(projectRoot) {
     }
     const identity = moduleIdentity(programPath);
     const contents = moduleContents(source, programPath);
+    if (subsystemMap.status === 'valid' && !assignments.has(programPath)) throw new GenesisError('SUBSYSTEMS_PROGRAM_UNASSIGNED', `Program module has no declared subsystem: ${programPath}.`);
     const { sources } = contents;
     for (const sourcePath of sources) {
       if (!sourcePath || !isProjectContentPath(sourcePath) || !await sourceExists(projectRoot, sourcePath)) {
@@ -164,7 +169,7 @@ export async function inspectProgram(projectRoot) {
       path: programPath,
       name: identity.name,
       sources,
-      subsystem: identity.subsystem,
+      subsystem: assignments.get(programPath) ?? null,
       title: contents.title,
       description: contents.description,
       publicContract: contents.publicContract,
@@ -176,6 +181,7 @@ export async function inspectProgram(projectRoot) {
     status: 'valid',
     files,
     modules,
-    subsystems: [...new Set(modules.map(({ subsystem }) => subsystem))].sort(),
+    subsystems: subsystemMap.subsystems.map(({ id }) => id),
+    subsystemMap,
   };
 }

package/src/index/project-inspection.js

@@ -16,6 +16,7 @@ import { readStack } from './stack.js';
 export const GENESIS_BOOTSTRAP_PATHS = Object.freeze([
   'genesis/version',
   'genesis/blueprint.md',
+  'genesis/subsystems.md',
   'genesis/stack.md',
   'genesis/collaboration.md',
   'genesis/engineering.md',

package/src/index/prompt.js

@@ -74,6 +74,7 @@ function programContext(program) {
   return {
     status: program.status,
     files: program.files,
+    subsystemMap: program.subsystemMap,
     subsystems: program.subsystems,
     modules: program.modules.map(({ path, name, sources, subsystem }) => ({
       path,
@@ -90,6 +91,7 @@ function startProgramContext(program) {
     status: program.status,
     subsystems: program.subsystems,
     moduleCount: program.modules.length,
+    subsystemMapStatus: program.subsystemMap?.status,
     ...(program.diagnostic ? { diagnostic: program.diagnostic } : {}),
   };
 }

package/src/index/session-context.js

@@ -149,6 +149,8 @@ export async function projectSessionContext({
     ...skills.diagnostics.map(({ message }) => `- Agent Skill maintenance: ${message}`),
     ...(skills.diagnostics.length > 0 ? ['- Skill inspection is read-only. Synchronization is an explicit source change; follow the current task authorization and host write boundary before running it.'] : []),
     '- After locating source, run `genesis context <path...>`; before adding a helper or public operation, run `genesis index <name-or-path...>` and reuse an existing owner.',
+    '- If genesis/subsystems.md is missing or empty in an existing explained application, author it from source, schema and existing Program before implementation. This is ordinary explanatory adoption, not a startup blocker; do not run tests or application commands merely to create the map.',
+    '- Read genesis/subsystems.md for declared subsystem responsibilities, Program membership, and data ownership/use. Maintain it in the same implementation turn when those facts change; reuse existing boundaries, verify source/schema, and never infer membership from folders.',
     '- Program is fallible explanation; code, tests, and runtime behavior remain evidence.',
     '- Keep Blueprint and affected Program explanations aligned with intentional observable product behavior in the same implementation turn. Private restructuring may need only source citations or no explanatory change.',
     '- Before reporting completion, compare the requested observable behavior, required inputs and resources, declared project operations, and focused evidence with what actually exists. State anything not proven.',

package/src/index/subsystems.js

@@ -0,0 +1,109 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { gitContext } from './git.js';
+import { readStack } from './stack.js';
+import { GenesisError } from './errors.js';
+import { normalizeRelative, sha256, stableJson } from './utils.js';
+
+export const SUBSYSTEMS_PATH = 'genesis/subsystems.md';
+export const EMPTY_SUBSYSTEMS_SOURCE = '# Subsystems\n\n- Nothing.\n';
+
+// Table identities are declarations, never database queries or SQL identifiers.
+export async function inspectSubsystems({ projectRoot = process.cwd() } = {}) {
+  projectRoot = (await gitContext(projectRoot)).repositoryRoot;
+  let source;
+  try { source = await readFile(path.join(projectRoot, SUBSYSTEMS_PATH), 'utf8'); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return { contract: 'genesis.subsystems.v0', status: 'missing', path: SUBSYSTEMS_PATH, subsystems: [] };
+  }
+  const invalid = (message) => { throw new GenesisError('SUBSYSTEMS_INVALID', `${SUBSYSTEMS_PATH}: ${message}`); };
+  const lines = source.replace(/\r\n?/gu, '\n').trim().split('\n');
+  if (lines.shift() !== '# Subsystems') invalid('Expected # Subsystems.');
+  const subsystems = [];
+  let current;
+  let section;
+  const sections = new Set();
+  const finish = () => {
+    if (!current) return;
+    if (!current.description.trim() || sections.size !== 3) invalid(`Subsystem ${current.id} needs a responsibility and Program, Data owned, Data used sections.`);
+    current.description = current.description.trim();
+    subsystems.push(current);
+  };
+  const empty = lines.join('\n').trim() === '- Nothing.';
+  if (!empty && !lines.some((line) => line.trim())) invalid('An empty map must say - Nothing.');
+  if (!empty) for (const line of lines) {
+    if (!line.trim()) {
+      if (current && !section) current.description += '\n';
+      continue;
+    }
+    const heading = line.match(/^## `([a-z0-9]+(?:-[a-z0-9]+)*)` (\S.*)$/u);
+    if (heading) {
+      finish();
+      current = { id: heading[1], title: heading[2], description: '', program: [], dataOwned: [], dataUsed: [] };
+      section = null;
+      sections.clear();
+      continue;
+    }
+    if (!current) invalid('Expected a subsystem heading or - Nothing.');
+    const sectionHeading = line.match(/^### (Program|Data owned|Data used)$/u);
+    if (sectionHeading) {
+      section = { Program: 'program', 'Data owned': 'dataOwned', 'Data used': 'dataUsed' }[sectionHeading[1]];
+      if (sections.has(section)) invalid(`Duplicate ${sectionHeading[1]} section.`);
+      sections.add(section);
+      continue;
+    }
+    if (line.startsWith('#')) invalid(`Unexpected heading: ${line}`);
+    if (!section) { current.description += `${line}\n`; continue; }
+    if (line === '- Nothing.') {
+      if (current[section].length || current[`${section}Empty`]) invalid('Nothing must be the only section entry.');
+      current[`${section}Empty`] = true;
+      continue;
+    }
+    if (current[`${section}Empty`]) invalid('Nothing must be the only section entry.');
+    if (section === 'program') {
+      const match = line.match(/^- `([^`]+)`$/u);
+      if (!match || !/^genesis\/program\/[a-z0-9-]+(?:\/[a-z0-9-]+)*\.md$/u.test(match[1]) || normalizeRelative(match[1]) !== match[1]) invalid(`Invalid Program reference: ${line}`);
+      current.program.push(match[1]);
+    } else {
+      const match = line.match(/^- Table `([^`]+)` `([^`]+)` `([^`]+)`$/u);
+      if (!match) invalid(`Expected Table resource, schema, and table: ${line}`);
+      current[section].push({ resource: match[1], schema: match[2], table: match[3] });
+    }
+  }
+  finish();
+  const ids = new Set();
+  const programs = new Set();
+  const owners = new Map();
+  for (const subsystem of subsystems) {
+    if (ids.has(subsystem.id)) invalid(`Duplicate subsystem ${subsystem.id}.`);
+    ids.add(subsystem.id);
+    for (const key of ['program', 'dataOwned', 'dataUsed']) {
+      if (!subsystem[key].length && !subsystem[`${key}Empty`]) invalid(`${subsystem.id}: empty sections must say - Nothing.`);
+      delete subsystem[`${key}Empty`];
+      const entries = subsystem[key].map((entry) => JSON.stringify(entry));
+      if (new Set(entries).size !== entries.length) invalid(`${subsystem.id}: duplicate ${key} entry.`);
+    }
+    for (const file of subsystem.program) {
+      if (programs.has(file)) invalid(`Program operation has multiple owners: ${file}.`);
+      programs.add(file);
+    }
+    for (const table of subsystem.dataOwned) {
+      const key = JSON.stringify(table);
+      if (owners.has(key)) invalid(`Table has multiple owners: ${key}.`);
+      owners.set(key, subsystem.id);
+    }
+  }
+  const tables = subsystems.flatMap((entry) => [...entry.dataOwned, ...entry.dataUsed]);
+  if (tables.length) {
+    const stack = await readStack(projectRoot);
+    const resources = new Set(stack.resources.map(({ resource }) => resource.id));
+    for (const table of tables) if (!resources.has(table.resource)) invalid(`Undeclared Stack resource: ${table.resource}.`);
+  }
+  for (const subsystem of subsystems) for (const table of subsystem.dataUsed) {
+    const owner = owners.get(JSON.stringify(table));
+    if (!owner || owner === subsystem.id) invalid(`${subsystem.id}: Data used must reference a table owned by another declared subsystem.`);
+  }
+  return { contract: 'genesis.subsystems.v0', status: subsystems.length ? 'valid' : 'empty', path: SUBSYSTEMS_PATH,
+    identity: sha256(stableJson(subsystems)), subsystems };
+}