genesis-compiler 1.7.8 → 1.8.1

package/src/index/program.js

@@ -6,7 +6,7 @@ import { GenesisError } from './errors.js';
 import { isProjectContentPath, PROGRAM_ROOT } from './paths.js';
 import { normalizeRelative } from './utils.js';
 
-const SOURCE_LINE = /^- `([^`]+)`$/u;
+const SOURCE_LINE = /^- (Main: )?`([^`]+)`$/u;
 const CONCEPT_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 
 async function markdownFiles(projectRoot) {
@@ -90,7 +90,16 @@ function moduleContents(source, programPath) {
   const sourceLines = lines
     .slice(sourcesHeading[0].index + 1, contractHeading[0].index)
     .filter((line) => line.trim());
-  const sources = sourceLines.map((line) => line.match(SOURCE_LINE)?.[1]);
+  const sourceMatches = sourceLines.map((line) => line.match(SOURCE_LINE));
+  const sources = sourceMatches.map((match) => match?.[2]);
+  const mainSources = sourceMatches.filter((match) => match?.[1]).map((match) => match[2]);
+  if (mainSources.length !== 1) {
+    throw new GenesisError(
+      'PROGRAM_MAIN_REQUIRED',
+      `Program module needs exactly one Main source bullet (- Main: \`path/to/source\`): ${programPath}. Choose the reading anchor in its owning subsystem.`,
+      { path: programPath },
+    );
+  }
   const nextHeading = headings.find(({ index }) => index > contractHeading[0].index);
   const contractLines = lines
     .slice(contractHeading[0].index + 1, nextHeading?.index ?? lines.length);
@@ -128,6 +137,7 @@ function moduleContents(source, programPath) {
     title,
     description,
     sources: sources.map((sourcePath) => normalizeRelative(sourcePath)),
+    mainSource: normalizeRelative(mainSources[0]),
     publicContract: contractLines.join('\n').trim(),
     implementationMap,
   };
@@ -144,6 +154,10 @@ export async function inspectProgram(projectRoot) {
     return { status: subsystemMap.status === 'valid' ? 'valid' : 'missing', files: [], modules: [], subsystems: subsystemMap.subsystems.map(({ id }) => id), subsystemMap };
   }
 
+  if (subsystemMap.status !== 'valid') {
+    throw new GenesisError('SUBSYSTEMS_REQUIRED', 'Program needs an authored directory-bound subsystem map. Assign every module once in genesis/subsystems.md.');
+  }
+
   const modules = [];
   for (const programPath of files) {
     const source = await readFile(path.join(projectRoot, programPath), 'utf8');
@@ -154,7 +168,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}.`);
+    if (!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)) {
@@ -165,10 +179,21 @@ export async function inspectProgram(projectRoot) {
         );
       }
     }
+    const mainOwner = subsystemMap.subsystems
+      .filter((entry) => entry.sourceRoot === '.' || contents.mainSource.startsWith(`${entry.sourceRoot}/`))
+      .sort((left, right) => (right.sourceRoot === '.' ? 0 : right.sourceRoot.length) - (left.sourceRoot === '.' ? 0 : left.sourceRoot.length))[0];
+    if (mainOwner?.id !== assignments.get(programPath)) {
+      throw new GenesisError(
+        'PROGRAM_MAIN_OWNER',
+        `Program main source must belong to its owning subsystem: ${contents.mainSource} in ${programPath}. Choose an owned source or correct the Program assignment.`,
+        { path: programPath, mainSource: contents.mainSource, subsystem: assignments.get(programPath) },
+      );
+    }
     modules.push({
       path: programPath,
       name: identity.name,
       sources,
+      mainSource: contents.mainSource,
       subsystem: assignments.get(programPath) ?? null,
       title: contents.title,
       description: contents.description,

package/src/index/project-inspection.js

@@ -46,7 +46,32 @@ export async function inspectProjectContent(projectRoot) {
   const paths = [...new Set([visible, ignored].flatMap(({ stdout }) => stdout.toString('utf8').split('\0').filter(Boolean)))]
     .filter((file) => !absent.has(file) && file !== '.git' && !file.startsWith('.git/'))
     .sort();
-  const existingPaths = paths.filter((file) => !bootstrapPaths.has(file) && !file.split('/').includes('node_modules'));
+  // OpenCode installs its plugin dependency beside the generated guidance plugin.
+  // Recognize only its exact ignored scaffolding, never an authored config tree.
+  const opencodePaths = ['.opencode/.gitignore', '.opencode/package.json', '.opencode/package-lock.json'];
+  const ignoredPaths = new Set(ignored.stdout.toString('utf8').split('\0').filter(Boolean));
+  let opencodeBootstrap = [];
+  if (opencodePaths.every((file) => ignoredPaths.has(file))) {
+    try {
+      const [ignoreSource, packageSource, lockSource] = await Promise.all(
+        opencodePaths.map((file) => readFile(path.join(projectRoot, file), 'utf8')),
+      );
+      const manifest = JSON.parse(packageSource);
+      const lock = JSON.parse(lockSource);
+      const dependencies = manifest?.dependencies;
+      if (manifest && Object.keys(manifest).length === 1 && dependencies && typeof dependencies === 'object' &&
+          Object.keys(dependencies).length === 1 && typeof dependencies['@opencode-ai/plugin'] === 'string' &&
+          ignoreSource === 'node_modules\npackage.json\npackage-lock.json\nbun.lock\n.gitignore' &&
+          lock?.name === '.opencode' && lock.lockfileVersion === 3 &&
+          JSON.stringify(lock.packages?.['']?.dependencies) === JSON.stringify(dependencies)) {
+        opencodeBootstrap = opencodePaths;
+      }
+    } catch (error) {
+      if (!(error instanceof SyntaxError) && !['ENOENT', 'ENOTDIR'].includes(error.code)) throw error;
+    }
+  }
+  const existingPaths = paths.filter((file) => !bootstrapPaths.has(file) &&
+    !opencodeBootstrap.includes(file) && !file.split('/').includes('node_modules'));
   return {
     kind: existingPaths.length ? 'existing' : paths.length ? 'bootstrap' : 'empty',
     existingPaths,

package/src/index/session-context.js

@@ -150,7 +150,7 @@ export async function projectSessionContext({
     ...(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.',
+    '- 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 require one Source Directory per subsystem and assign each Program module once; Program folder names do not assign ownership.',
     '- 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/source-explanation.js

@@ -0,0 +1,31 @@
+// Optional, read-only interpretation. The consumer owns source selection,
+// revision checks, Helper execution and caching; this is not Program material.
+export const SOURCE_EXPLANATION_PROMPT_VERSION = 'informational-source-v1';
+
+export function sourceExplanationGuidance({ presentation = 'description', scope = 'file' } = {}) {
+  if (!['description', 'steps'].includes(presentation) || !['file', 'selection'].includes(scope)) {
+    throw new TypeError('Choose description or steps for a file or declaration.');
+  }
+  return [
+    'Create an informational interpretation of the supplied source, not a design contract or instructions for a coding agent.',
+    'Use only the bounded source context. Do not use tools, inspect repositories, access the network or edit files. State uncertainty and distinguish observed behavior from inferred intent.',
+    scope === 'file'
+      ? 'Explain the file as a unit: responsibility, major operations and how its parts interact. Do not list imports or paraphrase every line.'
+      : 'Explain this declaration: what callers ask it to do, inputs, result, effects, dependencies and meaningful failure conditions. Exports can be internal to a subsystem; do not invent API intent.',
+    'Start with one concrete overview sentence of at most 220 characters, suitable for a signature list. Name the purpose and outcome, not language syntax.',
+    presentation === 'description'
+      ? 'Then write a short plain-English summary of behavior, data flow and constraints. Do not emit pseudocode or pseudo-variables.'
+      : 'Then write concise numbered steps in English as pseudocode: meaningful data names, decisions, ordering, effects and failures. Do not reproduce language-specific source syntax.',
+    'Components, callable operations, values and types need explanations appropriate to what they provide. Do not invent return types, callers or effects absent from the evidence.',
+    'A consumer must compare actual source content and this prompt revision before reuse. Changed source invalidates the interpretation even if an older explanation sounds plausible. Authored architectural intent is reviewed separately.'
+  ].join('\n');
+}
+
+export function sourceExplanationReviewGuidance() {
+  return [
+    'Review an optional informational source explanation against supplied current source evidence.',
+    'Identify claims no longer supported, missing effects or failure conditions, and inferred intent presented as fact. Source or prompt changes invalidate cached freshness; do not certify reuse from prose similarity.',
+    'Recommend regeneration when evidence changed. If source is incomplete, report the limit explicitly. Changes to intended responsibility or API boundaries require a separate human-reviewable design proposal.',
+    'Do not edit source, create mandatory documentation, promote interpretations into Program or supply them as coding-agent context.'
+  ].join('\n');
+}

package/src/index/stack-package-discovery.js

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import { GenesisError } from './errors.js';
+
+export function parsePackageDiscovery(lines) {
+  if (lines === undefined) return { status: 'unconfigured', discoveries: [] };
+  if (lines.join('\n').trim() === '- Nothing.') return { status: 'configured', discoveries: [] };
+  const discoveries = []; let current;
+  const invalid = message => { throw new GenesisError('PACKAGE_DISCOVERY_INVALID', message); };
+  for (const raw of lines) {
+    const line = raw.trim(); if (!line) continue;
+    const heading = line.match(/^### Discovery `([a-z0-9]+(?:-[a-z0-9]+)*)`: (.+)$/u);
+    if (heading) { current = { id: heading[1], title: heading[2], manifests: [] }; discoveries.push(current); continue; }
+    const field = line.match(/^- (Adapter|Manifest|Package root): `([^`]+)`$/u);
+    if (!current || !field) invalid(`Invalid Package discovery entry: ${line}`);
+    const [, name, value] = field;
+    if (name === 'Adapter') { if (current.adapter || !/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u.test(value)) invalid('Invalid or duplicate package adapter.'); current.adapter = value; }
+    else {
+      if (!value || path.posix.normalize(value) !== value || path.posix.isAbsolute(value) || /[\\\0]/u.test(value) || value.split('/').includes('..')) invalid('Package discovery paths must be canonical project paths.');
+      if (name === 'Manifest') { if (value === '.' || current.manifests.includes(value)) invalid('Invalid or duplicate package manifest.'); current.manifests.push(value); }
+      else { if (value === '.' || current.packageRoot) invalid('Package root must be a distinct dependency directory.'); current.packageRoot = value; }
+    }
+  }
+  if (!discoveries.length || new Set(discoveries.map(entry => entry.id)).size !== discoveries.length || discoveries.some(entry => !entry.adapter || !entry.manifests.length || !entry.packageRoot)) invalid('Each unique package discovery needs Adapter, Manifest and Package root.');
+  return { status: 'configured', discoveries };
+}

package/src/index/stack-ui-discovery.js

@@ -0,0 +1,38 @@
+import { GenesisError } from './errors.js';
+
+export function parseUiDiscovery(lines, { path = 'genesis/stack.md' } = {}) {
+  if (lines === undefined) return { status: 'unconfigured', discoveries: [] };
+  if (lines.join('\n').trim() === '- Nothing.') return { status: 'configured', discoveries: [] };
+  const discoveries = [];
+  let current;
+  const invalid = message => { throw new GenesisError('UI_DISCOVERY_INVALID', `${path}: ${message}`); };
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const heading = line.match(/^### Discovery `([a-z0-9]+(?:-[a-z0-9]+)*)`: (\S.*)$/u);
+    if (heading) {
+      current = { id: heading[1], title: heading[2], pageRoots: [], registrations: [], componentRoots: [] };
+      discoveries.push(current);
+      continue;
+    }
+    const field = line.match(/^- (Adapter|Surface|Mode|Page root|Registration|Component root): `([^`]+)`$/u);
+    if (!current || !field) invalid(`Invalid UI discovery entry: ${line}`);
+    const [, name, value] = field;
+    const key = { Adapter: 'adapter', Surface: 'surface', Mode: 'mode', 'Page root': 'pageRoots', Registration: 'registrations', 'Component root': 'componentRoots' }[name];
+    if (Array.isArray(current[key])) {
+      if (value.includes('\0') || value.includes('\\') || value.startsWith('/') || (value !== '.' && value.split('/').some(part => !part || part === '.' || part === '..'))) invalid(`Invalid ${name} path: ${value}`);
+      if (current[key].includes(value)) invalid(`Duplicate ${name}: ${value}`);
+      current[key].push(value);
+    } else {
+      if (Object.hasOwn(current, key)) invalid(`Duplicate ${name}.`);
+      if (!/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u.test(value)) invalid(`Invalid ${name}: ${value}`);
+      current[key] = value;
+    }
+  }
+  if (!discoveries.length || new Set(discoveries.map(entry => entry.id)).size !== discoveries.length) invalid('Supply unique discovery entries or - Nothing.');
+  for (const entry of discoveries) {
+    if (!entry.adapter || !entry.surface || !['registered', 'filesystem'].includes(entry.mode)) invalid(`${entry.id} needs Adapter, Surface and registered/filesystem Mode.`);
+    if (entry.mode === 'registered' && !entry.registrations.length) invalid(`${entry.id} needs Registration.`);
+    if (entry.mode === 'filesystem' && !entry.pageRoots.length) invalid(`${entry.id} needs Page root.`);
+  }
+  return { status: 'configured', discoveries };
+}

package/src/index/stack.js

@@ -8,6 +8,8 @@ import {
   readStackCatalog,
 } from './stack-catalog.js';
 import { composeStackCityPresentation } from './stack-city-presentation.js';
+import { parseUiDiscovery } from './stack-ui-discovery.js';
+import { parsePackageDiscovery } from './stack-package-discovery.js';
 import { resolveStackPieces } from './stack-composition.js';
 import {
   parseStackEnvironmentDefaultLines,
@@ -358,6 +360,8 @@ async function readStackWithContractMode(projectRoot, {
     source: 'project',
     diagnostics: [],
   }));
+  const uiDiscovery = parseUiDiscovery(extensions.find(entry => entry.name === 'UI discovery')?.lines);
+  const packageDiscovery = parsePackageDiscovery(extensions.find(entry => entry.name === 'Package discovery')?.lines);
   return {
     path: STACK_PATH,
     identityHash: sha256(stableJson({
@@ -375,6 +379,8 @@ async function readStackWithContractMode(projectRoot, {
     stackPackages: declaredPackages,
     cityExclusions: cityPresentation.exclusions,
     cityRegions: cityPresentation.regions,
+    uiDiscovery,
+    packageDiscovery,
     verificationCommands,
     environmentDefaults,
     environmentFiles,

package/src/index/subsystems.js

@@ -26,7 +26,8 @@ export async function inspectSubsystems({ projectRoot = process.cwd() } = {}) {
   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.`);
+    if (!current.description.trim() || !['source', 'program', 'dataOwned', 'dataUsed'].every(key => sections.has(key))) invalid(`Subsystem ${current.id} needs a responsibility and Source, Program, Data owned, Data used sections.`);
+    if (current.sourceRoot === undefined) invalid(`Subsystem ${current.id} Source requires one Directory.`);
     current.description = current.description.trim();
     subsystems.push(current);
   };
@@ -46,15 +47,22 @@ export async function inspectSubsystems({ projectRoot = process.cwd() } = {}) {
       continue;
     }
     if (!current) invalid('Expected a subsystem heading or - Nothing.');
-    const sectionHeading = line.match(/^### (Program|Data owned|Data used)$/u);
+    const sectionHeading = line.match(/^### (Source|Program|Data owned|Data used)$/u);
     if (sectionHeading) {
-      section = { Program: 'program', 'Data owned': 'dataOwned', 'Data used': 'dataUsed' }[sectionHeading[1]];
+      section = { Source: 'source', 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 (section === 'source') {
+      const match = line.match(/^- Directory `([^`]+)`$/u);
+      const directory = match?.[1];
+      if (!directory || current.sourceRoot !== undefined || directory.includes('\0') || directory.includes('\\') || directory.startsWith('/') || (directory !== '.' && directory.split('/').some(part => !part || part === '.' || part === '..'))) invalid('Source requires exactly one canonical project-relative Directory.');
+      current.sourceRoot = directory;
+      continue;
+    }
     if (line === '- Nothing.') {
       if (current[section].length || current[`${section}Empty`]) invalid('Nothing must be the only section entry.');
       current[`${section}Empty`] = true;
@@ -75,9 +83,14 @@ export async function inspectSubsystems({ projectRoot = process.cwd() } = {}) {
   const ids = new Set();
   const programs = new Set();
   const owners = new Map();
+  const roots = new Set();
   for (const subsystem of subsystems) {
     if (ids.has(subsystem.id)) invalid(`Duplicate subsystem ${subsystem.id}.`);
     ids.add(subsystem.id);
+    if (subsystem.sourceRoot !== undefined) {
+      if (roots.has(subsystem.sourceRoot)) invalid(`Directory has multiple subsystem owners: ${subsystem.sourceRoot}.`);
+      roots.add(subsystem.sourceRoot);
+    }
     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`];

package/src/index/utils.js

@@ -21,8 +21,8 @@ function stable(value) {
   return value;
 }
 
-export function stableJson(value) {
-  return `${JSON.stringify(stable(value), null, 2)}\n`;
+export function stableJson(value, { space = 2 } = {}) {
+  return `${JSON.stringify(stable(value), null, space)}\n`;
 }
 
 export function uniqueSorted(values = []) {

package/src/index.js

@@ -31,6 +31,7 @@ import { projectSessionContext, projectTurnContext } from './index/session-conte
 import { withTrustedGitRepository } from './index/process.js';
 
 export { inspectProject };
+export { SOURCE_EXPLANATION_PROMPT_VERSION, sourceExplanationGuidance, sourceExplanationReviewGuidance } from './index/source-explanation.js';
 export { inspectClaudeHooks, installClaudeHooks as syncClaudeHooks } from './index/claude-hooks.js';
 export { inspectAgentIntegrations, syncAgentIntegrations } from './index/agent-integrations.js';
 export { listParsers, installParsers, verifyParsers, parserEnvironment } from './index/code-indexers/parsers.js';
@@ -188,8 +189,10 @@ export function indexCodebase({
   queries = [],
   stackPackages = [],
   write = true,
+  observations = null,
+  signal,
 } = {}) {
-  return buildProjectIndex({ projectRoot, queries, stackPackages, write });
+  return buildProjectIndex({ projectRoot, queries, stackPackages, write, observations, signal });
 }
 
 export function inspectDerivedArtifacts() {
@@ -229,3 +232,7 @@ export async function syncSkills(options) {
 
 export { inspectSubsystems } from './index/subsystems.js';
 export { inspectOpenCodePlugin, installOpenCodePlugin as syncOpenCodePlugin } from './index/opencode-plugin.js';
+
+export { ARCHITECTURE_OBSERVATIONS_SCHEMA, validateArchitectureObservations, connectArchitectureObservations, mergeArchitectureObservations } from './index/architecture-observations.js';
+
+export { validateArchitectureFacts } from './index/architecture.js';