genesis-compiler 1.7.7 → 1.8.0

package/README.md

@@ -49,10 +49,16 @@ genesis/program/notes/list-notes.md
 genesis/program/notes/create-note.md
 ```
 
-The directory is a conceptual subsystem. Each file describes one public
+The directory organizes explanations; `genesis/subsystems.md` assigns each
+module to one directory-bound subsystem. Each file describes one public
 operation provided by that subsystem: an exported method, API action, route,
 command, UI operation, or equivalent entry point. Each module cites one or more
-real files under `## Sources`. There is no 1:1 source mapping: one operation may
+real files under `## Sources`. Every module requires exactly one
+`- Main: \`path/to/source\`` bullet naming its implementation's reading anchor.
+The main source belongs to the module's owning subsystem; other source bullets
+may cite shared libraries. It need not be an executable entry point. Existing
+modules need an explicitly chosen anchor before their Program can validate;
+indexing never guesses from source-list order. There is no 1:1 source mapping: one operation may
 span several files, helper files may be omitted, and one source may support
 multiple operations.
 
@@ -78,7 +84,7 @@ catalog as separate packages:
 npm install --global genesis-compiler genesis-stack
 ```
 
-`genesis-compiler` has no dependency on `genesis-stack` or on any framework.
+`genesis-compiler` has no runtime dependency on `genesis-stack` or on any framework.
 The catalog is static Markdown and contains the complete curated set of
 language, database, UI, and framework pieces. A host may supply another catalog
 through the same contract.
@@ -880,13 +886,23 @@ result. A newer project is never downgraded. Every project-scoped CLI
 invocation warns when the recorded format does not match the running CLI, and
 ordinary project operations stop until the migration is resolved.
 
+## Development
+
+Run `npm ci` in this source checkout, then `npm test`. The test command runs the
+original test files with file concurrency fixed at one. The local first-party
+catalogue is a development-only dependency so catalogue and starter tests work
+after a clean install; it is not required by the published compiler runtime.
+
 ## Public API
 
 ```js
 import {
+  ARCHITECTURE_OBSERVATIONS_SCHEMA,
+  SOURCE_EXPLANATION_PROMPT_VERSION,
   adoptProject,
   addStack,
   check,
+  connectArchitectureObservations,
   generatePrompt,
   getContext,
   indexCodebase,
@@ -904,11 +920,16 @@ import {
   verifyParsers,
   parserEnvironment,
   migrate,
+  mergeArchitectureObservations,
   projectSessionContext,
   projectTurnContext,
   setCollaboration,
   setEngineeringProfile,
+  sourceExplanationGuidance,
+  sourceExplanationReviewGuidance,
   syncSkills,
+  validateArchitectureFacts,
+  validateArchitectureObservations,
   verify,
   withTrustedGitRepository,
 } from 'genesis-compiler';
@@ -942,6 +963,24 @@ text.
 the functions already declared there, selected Stack guidance, available Agent
 Skills, and verification commands. `indexCodebase()` regenerates or returns the
 detailed Machine City and simple Program City projections.
+Its `observations` option accepts either a validated observation document or an
+async callback receiving the fresh architecture facts. A host can run its finite
+inspector inside that callback, avoiding a second source extraction. Genesis
+joins the result and rechecks source, Stack, subsystem and package inputs before
+writing compact derived JSON; failures and cancellation retain the prior index.
+`ARCHITECTURE_OBSERVATIONS_SCHEMA` identifies the neutral inspector document.
+`validateArchitectureObservations()` checks its evidence against supplied files
+and packages; `connectArchitectureObservations()` joins exact owners and
+controller operations. `mergeArchitectureObservations()` combines distinct
+inspectors while rejecting conflicting facts or package snapshots.
+`validateArchitectureFacts()` validates the combined architecture snapshot.
+These operations neither run a framework inspector nor claim complete runtime
+behavior.
+`sourceExplanationGuidance()` and `sourceExplanationReviewGuidance()` supply
+read-only informational interpretation and review prompts. The consumer owns
+bounded source selection, model execution and cache freshness, including
+`SOURCE_EXPLANATION_PROMPT_VERSION`. These explanations do not become Program
+contracts or coding-agent instructions.
 `inspectEnvironment()` returns normalized Stack resource declarations,
 public non-secret defaults, value-free missing-input diagnostics, and dotenv
 projection paths without returning any supplied environment value.
@@ -1008,6 +1047,9 @@ remain evidence; the map does not define application behavior or database DDL.
 
 Owns reusable form authoring, rendering, and answer validation.
 
+### Source
+- Directory `src/forms`
+
 ### Program
 - `genesis/program/forms/render.md`
 
@@ -1019,12 +1061,17 @@ Owns reusable form authoring, rendering, and answer validation.
 ```
 
 Each subsystem has a unique lowercase hyphenated id, title, responsibility
-prose, and exactly the three shown sections. Each Program module is assigned
+prose, and Source, Program, Data owned and Data used sections. Source declares
+exactly one canonical project-relative Directory (`.` is allowed); roots are
+unique. Nested owners take the files beneath their more specific root. Each Program module is assigned
 exactly once, by its complete project-relative path. Each table has at most one
 owner. Data used names a table owned by another declared subsystem. Empty
 sections explicitly say `- Nothing.`; an empty initialized map contains
 `# Subsystems` followed by `- Nothing.`. Data-only and code-only subsystems are
-valid. No subsystem hierarchy is inferred from paths.
+valid. The ready map is the canonical owner list for authored and indexed views. Stack
+directory suggestions never split it. Every indexed source needs an owner.
+Program Sources may include other subsystems’ libraries; that does not change
+the operation’s unique declared owner.
 
 Table references contain three distinct values: declared Stack resource **id**,
 schema, and table. `default` selects that resource's default schema; other schema
@@ -1045,7 +1092,7 @@ changes. Opening context stays concise; detailed associations load on demand.
 Adoption, Program refresh, work prompts, session guidance and installed workflow
 skills maintain the map alongside Program in the same turn. Review checks it
 read-only; Blueprint-only work leaves it alone. Ordinary private helper edits
-need no map change. Existing projects do not need a bulk update: missing or empty maps preserve
-Program access and instruct the agent to author the map from source before its
-next implementation task. Until then, operations have no declared subsystem;
-there is no folder-based compatibility reader or automatic ownership inference. Initialization creates an empty map without replacing one.
+need no map change. Existing maps must declare their source roots. Program modules require a ready
+map and one owner even when the old map was missing or empty. If the map is missing, empty or invalid, Program inspection reports the
+required authoring work instead of assigning operations from folder names.
+Initialization creates an empty map without replacing one.

package/docs/assurance-model.md

@@ -5,8 +5,10 @@ Genesis reports only facts it can establish mechanically:
 1. Blueprint, Engineering approach, Stack, and Program files satisfy their
    small structural formats, and the selected engineering profile exists in
    the installed versioned catalog.
-2. Program operations live in conceptual subsystem directories and cite real
-   source files. Optional helper maps are not mechanically certified.
+2. Each Program operation has one declared directory-bound subsystem owner and
+   cites real source files. It names exactly one main source in that subsystem;
+   supporting citations may cross subsystem boundaries. Optional helper maps
+   and the quality of the chosen reading anchor are not mechanically certified.
 3. Stack-declared environment inputs are present and non-placeholder. This does
    not prove that an external service is reachable; a verification command must
    establish that when it matters.

package/docs/prompt-integration.md

@@ -82,7 +82,25 @@ JSON on stdin:
 ```
 
 For `genesis hook turn`, the input has the same shape with `scope: "turn"`.
-The executable returns only the requested host contribution as text. Codex and Claude Code
+The executable returns exactly one JSON result:
+
+- `{"kind":"unclaimed"}`: this native conversation is not managed by the host;
+  Genesis delivers its standalone guide.
+- `{"kind":"contribution","text":"..."}`: Genesis composes this bounded host
+  contribution with its own session guide (or bounded turn contribution).
+- `{"kind":"delivery","text":"..."}`: the host owns the complete session
+  delivery; Genesis forwards it without adding its standalone copy. Empty text
+  means the host already delivers through a native system field. This result
+  is valid only for session scope.
+
+Malformed results and configured-resolver failures fail the hook. An unavailable
+claimed owner must fail rather than returning `unclaimed`. Ownership belongs to
+the native conversation: these results do not change project hook files, so
+independent CLI and managed conversations can use the same project. The host
+owns durable bindings, ancestry verification and restoration across reconnection.
+No host framework dependency is added to Genesis.
+
+Codex and Claude Code
 hook input and OpenCode's transform callbacks supply the native session id;
 Genesis extracts that id but does not understand the host registry or the
 provider's prompt-placement rules. The Codex and Claude prompt hooks and OpenCode message
@@ -104,8 +122,8 @@ Codex hook settings. A host can render these fields as an actionable failure
 instead of displaying the runtime stack.
 
 The OpenCode session adapter also includes verified native `parentSessionIds`
-in `GENESIS_HOST_CONTEXT_INPUT` for host command shims. The resolver still
-receives the actual child's `providerSessionId`; Genesis does not interpret a
+in `GENESIS_HOST_CONTEXT_INPUT` for host command shims and in the resolver
+request when present (at most 32 IDs). The resolver receives the actual child's `providerSessionId`; Genesis does not interpret a
 host's ownership rules.
 
 After updating Genesis, hosts can inspect all generated integrations with

package/docs/templates.md

@@ -1,5 +1,11 @@
 # Project opening and templates
 
+The official JSKIT choices are **Basic app**, **Database app**, and **Accounts
+app**. Basic keeps the existing `jskit/public` ID and `public` branch. Database
+uses `jskit/database` and the `database` branch, adding MySQL without login.
+Accounts keeps `jskit/accounts` and the `accounts` branch. These are complete
+starter projects with ready tests; importing source still runs no setup commands.
+
 `genesis init` installs the portable Genesis documents, workflow skills, and
 agent integration in an ordinary Git repository. It preserves existing source.
 Initialization is a decision to use Genesis; it is not evidence that an existing
@@ -30,6 +36,11 @@ custom agent tool counts as existing content. Ignored files also count, except
 installed `node_modules` dependencies. Source recognition does not depend on a
 language detector or an AI model.
 
+OpenCode's ignored plugin-install metadata also leaves a blank project eligible:
+its exact generated `.opencode/.gitignore`, plugin-only package manifest and
+matching npm lockfile. These files are read, not deleted or repaired. Tracked or
+customized manifests and other OpenCode files still count as existing content.
+
 Opening a session does not run verification, rebuild the source index, install
 dependencies, prepare a database, or start the application. The inspection is
 repeated as a small read when opening/resuming a session and when a host refreshes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.7.7",
+  "version": "1.8.0",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {
@@ -47,14 +47,16 @@
     "docs/parsers.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test --test-concurrency=1 test/*.test.js"
   },
   "dependencies": {
     "@ast-grep/napi": "^0.45.1",
     "mdast-util-from-markdown": "^2.0.3",
+    "minimatch": "10.2.6",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@ast-grep/lang-python": "0.0.6"
+    "@ast-grep/lang-python": "0.0.6",
+    "genesis-stack": "file:packages/genesis-stack"
   }
 }

package/plugins/genesis/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis",
-  "version": "1.4.0",
+  "version": "1.8.0",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/prompts/describe.txt

@@ -15,6 +15,11 @@ result. Identify anything not inspected or genuinely uncertain.
 Edit only `genesis/blueprint.md`, `genesis/subsystems.md`, and explanatory Markdown below
 `genesis/program/`. Summarize every explanatory file created, updated, or
 removed.
+Write useful subsystem responsibility explanations covering purpose, scope,
+important parts and collaboration. Preserve substantive existing prose rather
+than replacing it with short visual captions. Reconcile changed directory owners,
+Program membership and required main-source anchors together; validate the map
+and Program after regeneration. Consumers reuse this canonical list.
 
 Maintain `genesis/subsystems.md` in the same implementation turn when a change
 adds, removes, or changes a subsystem responsibility, Program membership, or

package/prompts/program.txt

@@ -9,7 +9,15 @@ Delete stale or duplicate modules and do not edit code, tests, configuration,
 Blueprint, Stack, or `.genesis/`.
 
 When finished, summarize Program files created, updated, or removed and report
-genuine ambiguity.
+genuine ambiguity. Every module must designate exactly one main source with
+`- Main: \`path/to/source\`` in Sources. Inspect its implementation and choose a
+reading anchor in its owning subsystem; do not guess from source-list order.
+Treat each subsystem responsibility as the full useful explanation, not a
+one-line map caption. Preserve substantive descriptions. If boundaries change,
+reconcile the prose, Program assignments and required main anchors with the new
+directory owners, including nested roots. Consumers read the current canonical
+map; there is no separate viewer-owned list to maintain. Validate both subsystem
+declarations and Program membership before reporting completion.
 
 Maintain `genesis/subsystems.md` in the same implementation turn when a change
 adds, removes, or changes a subsystem responsibility, Program membership, or

package/skills/genesis-program/SKILL.md

@@ -43,13 +43,22 @@ One short explanation of why the boundary exists.
 
 ## Sources
 
-- `exact/authored/source/path`
+- Main: `exact/authored/main/source/path`
+- `exact/authored/supporting/source/path`
 
 ## Public contract
 
 Meaningful inputs, outputs, effects, failures, and guarantees.
 ```
 
+Every module requires exactly one `- Main:` source bullet. Choose the main
+source explicitly as the place to start reading the implementation; it need not
+be an executable entry point. It must belong to the module's owning subsystem,
+respecting more specific nested directory owners. Other Sources may cite shared
+libraries in other subsystems. Never infer the main file from source-list order,
+imports or file naming. When reconciling older modules, inspect the source and
+mark the anchor explicitly; indexing does not assign one for you.
+
 An optional `## Implementation map` may name only private helpers or seams that
 materially help a future agent change, trace, or debug the operation. It is
 informational, not a public guarantee. Tests are evidence and never
@@ -82,6 +91,9 @@ Use this exact version-zero grammar:
 
 Owns reusable form rendering, validation, and submission capture.
 
+### Source
+- Directory `packages/forms`
+
 ### Program
 - `genesis/program/forms/render.md`
 
@@ -93,10 +105,35 @@ Owns reusable form rendering, validation, and submission capture.
 ```
 
 Use one stable lowercase hyphenated id and a human title per subsystem. Each
-entry needs responsibility prose and exactly the three sections shown. Empty
+entry needs responsibility prose and the Program, Data owned and Data used sections.
+Responsibility prose is the subsystem's full explanation, not a map caption.
+Explain its purpose, scope, important parts and collaboration with other owners.
+Preserve substantive existing descriptions; do not replace them with one-line
+labels to suit a visualisation. A consumer can shorten the displayed preview.
+Simple support directories may need only a short explanation.
+The required Source section contains exactly one `- Directory` entry with a backticked path: a
+canonical project-relative directory, with `.` allowed for the project root.
+Every subsystem has one directory root; never declare dispersed or multiple
+roots. Stack parent-directory rules discover default subsystem roots but are not
+exhaustive. An agent may recognise and declare another root elsewhere from
+actual responsibility and source evidence. The authored declaration persists
+through ordinary indexing. The authored map is the canonical owner list once ready; Stack roots are adoption
+hints and never create additional owners or split an authored boundary. Cover every
+indexed source, using a project-root owner for remaining support files if needed. UI components and Engine code may
+share one root; UI projection does not change ownership. Empty
 sections say `- Nothing.`; a new empty map contains only `# Subsystems` and
-`- Nothing.`. Every Program module belongs to exactly one subsystem. No folder
-inference, globs, duplicated operations, or duplicated table owners.
+`- Nothing.`. Every Program module belongs to exactly one subsystem. Program directory names do not assign ownership. Sources may cite another
+subsystem’s libraries without giving the operation or implementation two owners.
+Do not use globs, duplicate operations or duplicate table owners.
+
+When regenerating or deliberately splitting the map, reconcile the explanations
+with the new directory owners. Transfer the applicable responsibility prose and
+explicit Program assignments together, preserving stable ids where the boundary
+is unchanged. Recheck every Program's required main source against its current
+owner, including nested owners; library references retain their own ownership.
+Use the current declarations rather than an earlier consumer's hardcoded names,
+directory layout or cached list. Inspect subsystems and Program and resolve
+missing/duplicate membership and invalid main anchors before claiming completion.
 
 A table identity is three separate exact backticked values: the declared Stack
 resource id, schema, and table. `default` means the resource's default schema;

package/skills/genesis-project/SKILL.md

@@ -164,8 +164,8 @@ an unrun check passed or that passing checks prove the whole product.
 Maintain `genesis/subsystems.md` in the same implementation turn when a change
 adds, removes, or changes a subsystem responsibility, Program membership, or
 data ownership/use. Read the map before changing related code. Reuse existing
-subsystems unless a distinct responsibility is evidenced. Declare each Program
-module exactly once; folders do not determine membership. Keep table references
+subsystems unless a distinct responsibility is evidenced. Require one Source Directory per subsystem and declare each Program module
+exactly once; Program folder names do not determine membership. Keep table references
 grounded in schema/migrations; Genesis does not inspect databases. Private
 helper changes need no map edit when these associations remain unchanged.
 

package/src/cli.js

@@ -426,8 +426,8 @@ function writeResult(command, result) {
   line(process.stdout, `${command}: ${result.status}`);
 }
 
-async function hookSessionId(environment = process.env) {
-  if (!environment[HOST_CONTEXT_RESOLVER_ENV]) return null;
+async function hookSessionInput(environment = process.env) {
+  if (!environment[HOST_CONTEXT_RESOLVER_ENV]) return {};
   let source = environment[HOST_CONTEXT_INPUT_ENV];
   if (source === undefined && !process.stdin.isTTY) {
     const chunks = [];
@@ -441,7 +441,7 @@ async function hookSessionId(environment = process.env) {
     }
     source = Buffer.concat(chunks).toString('utf8');
   }
-  if (!String(source || '').trim()) return null;
+  if (!String(source || '').trim()) return {};
   let input;
   try {
     input = JSON.parse(source);
@@ -449,7 +449,15 @@ async function hookSessionId(environment = process.env) {
     fail('HOST_CONTEXT_INPUT_INVALID', 'The host hook input must contain JSON.');
   }
   const sessionId = input?.sessionId ?? input?.session_id;
-  return typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : null;
+  const parentSessionIds = input?.parentSessionIds ?? [];
+  if (!Array.isArray(parentSessionIds) || parentSessionIds.length > 32 ||
+      parentSessionIds.some(id => typeof id !== 'string' || !id.trim())) {
+    fail('HOST_CONTEXT_INPUT_INVALID', 'Native parent session ids must be a bounded list of strings.');
+  }
+  return {
+    providerSessionId: typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : null,
+    ...(parentSessionIds.length ? { parentSessionIds } : {}),
+  };
 }
 
 async function cliStackPackages(projectRoot, supplied) {
@@ -574,19 +582,24 @@ async function execute({ command, operands, options }, { signal } = {}) {
     if (scope === 'session' && process.env[SESSION_CONTEXT_INSTALLED_ENV] === '1') {
       return { kind: 'session', status: 'ready', output: '' };
     }
-    const providerSessionId = await hookSessionId();
+    const nativeSession = await hookSessionInput();
     const hostContext = await resolveConfiguredHostContext({
       projectRoot,
-      providerSessionId,
+      ...nativeSession,
       scope,
     });
+    // Ownership is resolved for this native conversation, not for the project.
+    // A host-owned delivery already contains everything its runtime requires.
+    if (hostContext?.kind === 'delivery') {
+      return { kind: 'session', status: 'ready', output: hostContext.text };
+    }
     if (scope === 'turn') {
       return hostContext === null
         ? { kind: 'turn', status: 'ready', output: '' }
         : {
             kind: 'turn',
             ...await projectTurnContext({
-              hostDriver: () => hostContext,
+              hostDriver: () => hostContext.text,
               hostDriverInput: { scope: 'turn' },
             }),
           };
@@ -595,7 +608,7 @@ async function execute({ command, operands, options }, { signal } = {}) {
       kind: 'session',
       ...await projectSessionContext({
         ...(hostContext === null ? {} : {
-          hostDriver: () => hostContext,
+          hostDriver: () => hostContext.text,
           hostDriverInput: { scope: 'session' },
         }),
         projectRoot,

package/src/index/architecture-observations.js

@@ -0,0 +1,167 @@
+import path from 'node:path';
+import { GenesisError } from './errors.js';
+import { sha256, stableJson } from './utils.js';
+
+export const ARCHITECTURE_OBSERVATIONS_SCHEMA = 'genesis.architecture-observations.v1';
+const collections = ['pages', 'registrations', 'components', 'componentUses', 'entryOperations', 'operationUses'];
+const optionalCollections = ['imports'];
+const states = ['complete', 'partial', 'unsupported', 'unconfigured'];
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = value => typeof value === 'string' && value.length > 0 && !/[\0\r\n]/u.test(value);
+const canonical = value => text(value) && value !== '.' && !/[\\]/u.test(value) && !path.posix.isAbsolute(value) && path.posix.normalize(value) === value && !value.split('/').includes('..');
+const point = value => object(value) && Number.isSafeInteger(value.line) && value.line > 0 && Number.isSafeInteger(value.column) && value.column > 0;
+
+function requireFact(condition, message) {
+  if (!condition) throw new GenesisError('ARCHITECTURE_OBSERVATIONS_INVALID', message);
+}
+
+// A finite, framework-independent JSON contract. Inspectors collect evidence;
+// this owner validates identities and joins without executing application code.
+export function validateArchitectureObservations(document, { files = [], packages = [] } = {}) {
+  requireFact(object(document) && document.schema === ARCHITECTURE_OBSERVATIONS_SCHEMA, `Expected ${ARCHITECTURE_OBSERVATIONS_SCHEMA}.`);
+  requireFact(text(document.adapter), 'An adapter identity is required.');
+  requireFact(Array.isArray(document.inputs), 'inputs must be an array.');
+  requireFact(object(document.capabilities), 'capabilities must be an object.');
+  for (const name of ['pages', 'components', 'entryOperations', 'operationUses']) requireFact(states.includes(document.capabilities[name]), `Missing or invalid ${name} capability.`);
+  if (document.capabilities.imports !== undefined) requireFact(states.includes(document.capabilities.imports), 'Invalid import coverage.');
+  requireFact(Array.isArray(document.diagnostics) && document.diagnostics.every(entry => object(entry) && text(entry.code) && text(entry.message)), 'diagnostics must contain code and message.');
+  const filesByPath = new Map(files.map(file => [file.path, file]));
+  const inputs = new Map();
+  for (const input of document.inputs) {
+    requireFact(object(input) && canonical(input.path) && text(input.hash), 'Every input needs a canonical project path and content hash.');
+    requireFact(!inputs.has(input.path), `Duplicate input ${input.path}.`);
+    const file = filesByPath.get(input.path);
+    requireFact(file && file.hash === input.hash, `Input ${input.path} does not match the indexed source. Refresh against the same snapshot.`);
+    inputs.set(input.path, input);
+  }
+  const ids = new Map();
+  for (const name of [...collections, ...optionalCollections]) {
+    requireFact(Array.isArray(document[name]) || (optionalCollections.includes(name) && document[name] === undefined), `${name} must be an array.`);
+    for (const record of document[name] || []) {
+      requireFact(object(record) && text(record.id) && !ids.has(record.id), `Invalid or duplicate ${name} identity.`);
+      requireFact(['resolved', 'unresolved', 'ambiguous'].includes(record.resolution), `${record.id} needs an explicit resolution.`);
+      requireFact(Array.isArray(record.evidence) && record.evidence.length > 0, `${record.id} needs source evidence.`);
+      for (const evidence of record.evidence) {
+        requireFact(object(evidence) && canonical(evidence.path) && inputs.get(evidence.path)?.hash === evidence.hash, `${record.id} evidence must reference a declared input hash.`);
+        requireFact(point(evidence.start) && point(evidence.end) && (evidence.end.line > evidence.start.line || (evidence.end.line === evidence.start.line && evidence.end.column > evidence.start.column)), `${record.id} has an impossible source range.`);
+        const lines = filesByPath.get(evidence.path)?.lines;
+        requireFact(!Number.isInteger(lines) || (evidence.start.line <= lines && (evidence.end.line <= lines || (evidence.end.line === lines + 1 && evidence.end.column === 1))), `${record.id} range exceeds its source.`);
+      }
+      ids.set(record.id, { name, record });
+    }
+  }
+  function reference(value, names, label) {
+    requireFact(ids.has(value) && names.includes(ids.get(value).name), `${label} refers to an unknown definition.`);
+  }
+  function source(value, label) { requireFact(inputs.has(value), `${label} must identify a declared input file.`); }
+  for (const use of document.imports || []) {
+    source(use.fromFile, use.id);
+    requireFact(text(use.specifier) && Array.isArray(use.names) && use.names.every(text) && typeof use.typeOnly === 'boolean', `${use.id} requires imported names, a specifier and type-only classification.`);
+    requireFact(use.evidence.some(evidence => evidence.path === use.fromFile), `${use.id} needs evidence in its importing file.`);
+    if (use.resolution === 'resolved') source(use.targetFile, use.id);
+  }
+  function operation(key, label) {
+    requireFact(object(key) && text(key.protocol) && text(key.scope) && text(key.operation), `${label} requires protocol, scope and operation identity.`);
+    requireFact(Object.values(key).every(text), `${label} fields must be non-empty strings.`);
+    if (key.protocol === 'http') requireFact(text(key.method) && key.method === key.method.toUpperCase(), `${label} requires an uppercase HTTP method.`);
+  }
+  for (const page of document.pages) {
+    requireFact(text(page.title) && text(page.surface) && text(page.kind), `${page.id} requires title, surface and page/screen/scene kind.`);
+    source(page.file, page.id);
+    if (page.parentId != null) reference(page.parentId, ['pages'], page.id);
+  }
+  const packagesById = new Map(packages.map(entry => [entry.id, entry]));
+  let packageIdentity;
+  for (const component of document.components) {
+    requireFact(text(component.title), `${component.id} requires a title.`);
+    if (component.origin?.kind === 'package') {
+      requireFact(component.file == null && packagesById.has(component.origin.packageId) && text(component.origin.importPath) && text(component.origin.symbol), `${component.id} requires a known package boundary and public import identity.`);
+      packageIdentity ??= sha256(stableJson(packages));
+      requireFact(document.packageIdentity === packageIdentity, 'Package-backed UI observations must match the inspected package snapshot.');
+    } else source(component.file, component.id);
+  }
+  for (const registration of document.registrations) {
+    reference(registration.pageId, ['pages'], registration.id);
+    requireFact(text(registration.surface) && text(registration.identity), `${registration.id} requires scoped registration identity.`);
+  }
+  for (const use of document.componentUses) {
+    reference(use.parentId, ['pages', 'components', 'componentUses'], use.id);
+    if (use.resolution === 'resolved') reference(use.componentId, ['components'], use.id);
+  }
+  for (const entry of document.entryOperations) {
+    operation(entry.key, entry.id);
+    if (entry.resolution === 'resolved') source(entry.controllerFile, entry.id);
+    if (entry.controllerSymbol != null) requireFact(text(entry.controllerSymbol), `${entry.id} has an invalid symbol.`);
+  }
+  for (const use of document.operationUses) {
+    reference(use.parentId, ['pages', 'components', 'componentUses'], use.id);
+    if (use.resolution === 'resolved') operation(use.key, use.id);
+  }
+  // Parent graphs must be finite. Shared definitions are not duplicate owners.
+  for (const name of ['pages', 'componentUses']) for (const record of document[name]) {
+    const seen = new Set([record.id]);
+    let parent = ids.get(record.parentId)?.record;
+    while (parent) {
+      requireFact(!seen.has(parent.id), `Containment cycle at ${record.id}.`);
+      seen.add(parent.id); parent = ids.get(parent.parentId)?.record;
+    }
+  }
+  return document;
+}
+
+export function connectArchitectureObservations(document, files, packages = []) {
+  validateArchitectureObservations(document, { files, packages });
+  const byPath = new Map(files.map(file => [file.path, file]));
+  const entries = new Map();
+  for (const entry of document.entryOperations.filter(record => record.resolution === 'resolved')) {
+    const key = stableJson(entry.key);
+    if (!entries.has(key)) entries.set(key, []);
+    entries.get(key).push(entry);
+  }
+  const connections = document.operationUses.map(use => {
+    const matches = use.resolution === 'resolved' ? entries.get(stableJson(use.key)) || [] : [];
+    const entry = matches.length === 1 ? matches[0] : null;
+    return { id: `connection:${use.id}`, useId: use.id, parentId: use.parentId, key: use.key || null, resolution: entry ? 'resolved' : matches.length > 1 ? 'ambiguous' : 'unresolved', entryId: entry?.id || null, controllerFileId: entry ? byPath.get(entry.controllerFile).id : null, controllerSymbol: entry?.controllerSymbol || null, evidence: [...use.evidence, ...(entry?.evidence || [])] };
+  });
+  return {
+    ...document, connections,
+    components: document.components.map(component => ({ ...component, fileId: byPath.get(component.file)?.id || null, subsystemId: component.origin?.kind === 'package' ? packages.find(entry => entry.id === component.origin.packageId).subsystemId : byPath.get(component.file).subsystemId })),
+    pages: document.pages.map(page => ({ ...page, fileId: byPath.get(page.file).id, subsystemId: byPath.get(page.file).subsystemId })),
+  };
+}
+
+export function mergeArchitectureObservations(documents, { files = [], packages = [] } = {}) {
+  requireFact(Array.isArray(documents) && documents.length > 0, 'At least one observation document is required.');
+  const merged = { schema: ARCHITECTURE_OBSERVATIONS_SCHEMA, adapter: '', inputs: [], capabilities: {}, diagnostics: [], ...Object.fromEntries([...collections, ...optionalCollections].map(name => [name, []])) };
+  const adapters = new Set();
+  for (const document of documents) {
+    requireFact(document?.schema === ARCHITECTURE_OBSERVATIONS_SCHEMA && text(document.adapter) && !adapters.has(document.adapter), 'Every inspector needs a unique adapter identity and the observation schema.');
+    adapters.add(document.adapter);
+    if (document.packageIdentity != null) {
+      requireFact(!merged.packageIdentity || merged.packageIdentity === document.packageIdentity, 'Inspectors disagree about the package snapshot.');
+      merged.packageIdentity = document.packageIdentity;
+    }
+    for (const name of ['inputs', ...collections, ...optionalCollections]) {
+      requireFact(Array.isArray(document[name]) || (optionalCollections.includes(name) && document[name] === undefined), `${name} must be an array.`);
+      const byId = new Map(merged[name].map(record => [name === 'inputs' ? record.path : record.id, record]));
+      for (const record of document[name] || []) {
+        requireFact(object(record), `Invalid ${name} record.`);
+        const id = name === 'inputs' ? record.path : record.id;
+        const previous = byId.get(id);
+        requireFact(!previous || stableJson(previous) === stableJson(record), `Conflicting ${name} identity ${id}.`);
+        if (!previous) { merged[name].push(record); byId.set(id, record); }
+      }
+    }
+    requireFact(Array.isArray(document.diagnostics), 'diagnostics must be an array.');
+    merged.diagnostics.push(...document.diagnostics);
+  }
+  merged.adapter = [...adapters].sort().join('+');
+  for (const capability of ['pages', 'components', 'entryOperations', 'operationUses']) {
+    const values = documents.map(document => document.capabilities?.[capability]);
+    requireFact(values.every(value => states.includes(value)), `Invalid ${capability} coverage.`);
+    merged.capabilities[capability] = new Set(values).size === 1 ? values[0] : 'partial';
+  }
+  const importCoverage = documents.map(document => document.capabilities?.imports || 'unconfigured');
+  merged.capabilities.imports = new Set(importCoverage).size === 1 ? importCoverage[0] : 'partial';
+  return validateArchitectureObservations(merged, { files, packages });
+}