@neurcode-ai/cli 0.14.0 → 0.15.0

package/dist/utils/structural-understanding.js

@@ -0,0 +1,2316 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONSEQUENCE_UNDERSTANDING_SCHEMA_VERSION = exports.STRUCTURAL_UNDERSTANDING_SCHEMA_VERSION = void 0;
+exports.structuralUnderstandingPath = structuralUnderstandingPath;
+exports.buildStructuralUnderstanding = buildStructuralUnderstanding;
+exports.writeStructuralUnderstanding = writeStructuralUnderstanding;
+exports.readStructuralUnderstanding = readStructuralUnderstanding;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const ts = __importStar(require("typescript"));
+const governance_runtime_1 = require("@neurcode-ai/governance-runtime");
+const import_edge_extractor_1 = require("./import-edge-extractor");
+exports.STRUCTURAL_UNDERSTANDING_SCHEMA_VERSION = 'neurcode.structural-understanding.v1';
+exports.CONSEQUENCE_UNDERSTANDING_SCHEMA_VERSION = 'neurcode.consequence-understanding.v1';
+const TS_LIKE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/i;
+const SKIP_DIR = /^(node_modules|\.git|dist|build|out|coverage|\.next|vendor)$/i;
+const EFFECT_REGISTRY = [
+    {
+        category: 'filesystem-write',
+        callees: new Set([
+            'writeFile',
+            'writeFileSync',
+            'appendFile',
+            'appendFileSync',
+            'mkdir',
+            'mkdirSync',
+            'rename',
+            'renameSync',
+            'rm',
+            'rmSync',
+            'unlink',
+            'unlinkSync',
+        ]),
+    },
+    {
+        category: 'session-evidence-write',
+        callees: new Set(['writeAIChangeRecord', 'writeStructuralUnderstanding', 'appendEvent', 'finishSession']),
+    },
+    {
+        category: 'network-send',
+        callees: new Set(['fetch', 'sendBeacon']),
+    },
+];
+const GENERATED_FINGERPRINTS = [
+    { needle: 'webpackBootstrap', reasonCode: 'webpack_bootstrap' },
+    { needle: '__webpack_modules__', reasonCode: 'webpack_modules' },
+    { needle: 'sourceMappingURL=', reasonCode: 'source_map_marker' },
+    { needle: '@generated', reasonCode: 'generated_marker' },
+    { needle: 'Code generated by', reasonCode: 'generated_marker' },
+];
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function hash(value, length = 24) {
+    return (0, crypto_1.createHash)('sha256').update(typeof value === 'string' ? value : stableStringify(value)).digest('hex').slice(0, length);
+}
+function repoRel(projectRoot, absPath) {
+    return (0, path_1.relative)(projectRoot, absPath).split(path_1.sep).join('/');
+}
+function normalizeRepoPath(value) {
+    return value.replace(/\\/g, '/').replace(/^\.\//, '').trim();
+}
+function isTestFile(file) {
+    const normalized = normalizeRepoPath(file).toLowerCase();
+    return (normalized.includes('/__tests__/') ||
+        normalized.includes('/test/') ||
+        normalized.includes('/tests/') ||
+        /\.(test|spec)\.[tj]sx?$/.test(normalized));
+}
+function uniqueSorted(values) {
+    return Array.from(new Set(Array.from(values, (value) => String(value ?? '').trim()).filter(Boolean)))
+        .sort((a, b) => a.localeCompare(b));
+}
+function emptyDigest(generatedAt, changedSymbolCount = 0, referenceCount = 0, testReferenceCount = 0) {
+    return {
+        schemaVersion: 'neurcode.structural-digest.v1',
+        generatedAt,
+        provenance: 'deterministic-ranking',
+        modelUsed: false,
+        topSymbols: [],
+        topConsequences: [],
+        topReferences: [],
+        hidden: {
+            references: referenceCount,
+            testReferences: testReferenceCount,
+            lowSignalReferences: referenceCount,
+            sameFileReferences: 0,
+        },
+        summary: {
+            changedSymbolCount,
+            referenceCount,
+            topConsequenceCount: 0,
+            topReferenceCount: 0,
+            crossPackageReferenceCount: 0,
+            nonTestReferenceCount: Math.max(0, referenceCount - testReferenceCount),
+            testReferenceCount,
+        },
+        limitations: [
+            'Digest ranking is deterministic and facts-only; it is not an LLM judgment.',
+            'No source text, diff hunks, patch content, or shell command bodies are stored.',
+        ],
+    };
+}
+function artifactHashInput(artifact) {
+    const maybeConsequence = artifact['consequenceUnderstanding'];
+    return {
+        ...artifact,
+        generatedAt: null,
+        artifactHash: null,
+        digest: artifact.digest ? { ...artifact.digest, generatedAt: null } : artifact.digest,
+        consequenceUnderstanding: maybeConsequence && typeof maybeConsequence === 'object'
+            ? { ...maybeConsequence, generatedAt: null, artifactHash: null }
+            : maybeConsequence,
+    };
+}
+function consequenceHashInput(artifact) {
+    return { ...artifact, generatedAt: null, artifactHash: null };
+}
+function emptyConsequenceUnderstanding(generatedAt, reason = null) {
+    const core = {
+        schemaVersion: exports.CONSEQUENCE_UNDERSTANDING_SCHEMA_VERSION,
+        generatedAt,
+        analyzed: reason === null,
+        reason,
+        confidence: reason === null ? 'deterministic-static' : 'not-analyzed',
+        modelUsed: false,
+        effectDeltas: [],
+        contractDeltas: [],
+        inheritorProjections: [],
+        topFindings: [],
+        topImpacts: [],
+        summary: {
+            effectDeltaCount: 0,
+            contractDeltaCount: 0,
+            inheritorProjectionCount: 0,
+            topFindingCount: 0,
+            topImpactCount: 0,
+            escapingConsequenceCount: 0,
+            highestExternalConsumerCount: 0,
+            headline: '0 symbols changed; 0 escaping TypeScript-static consequences found (effects checked: allowlisted filesystem/network/session evidence; SQL, dependency injection, dynamic dispatch, route wiring, and cross-language behavior not analyzed).',
+        },
+        limitations: [
+            'Known-effect detection is allowlist-bounded; effects via unrecognized wrappers, dynamic dispatch, or dependency injection are not claimed.',
+            'Contract detection is TypeScript/JavaScript static analysis only.',
+            'No LLM or probabilistic judgment is used in this artifact.',
+            'No source text, diff hunks, patch content, or shell command bodies are stored.',
+        ],
+        factProvenance: {
+            effectDeltas: 'effect-registry',
+            contractDeltas: 'typescript-checker',
+            inheritorProjections: 'inheritance-projection',
+            topFindings: 'deterministic-ranking',
+            topImpacts: 'deterministic-impact-grouping',
+        },
+    };
+    return { ...core, artifactHash: hash(consequenceHashInput(core)) };
+}
+function none(projectRoot, diffFiles, reason, generatedAt, suppressedArtifacts = []) {
+    const core = {
+        schemaVersion: exports.STRUCTURAL_UNDERSTANDING_SCHEMA_VERSION,
+        generatedAt,
+        repoRootHash: hash(projectRoot),
+        privacy: privacyBlock(),
+        analysis: {
+            language: 'typescript',
+            analyzed: false,
+            reason,
+            confidence: 'not-analyzed',
+            filesAnalyzed: 0,
+            changedFileCount: diffFiles.length,
+            changedSymbolCount: 0,
+            referenceCount: 0,
+            testReferenceCount: 0,
+        },
+        changedFiles: changedFileFacts(diffFiles),
+        changedSymbols: [],
+        references: [],
+        importEdgesChanged: importEdgeFacts(diffFiles, suppressedArtifacts),
+        suppressedArtifacts,
+        testReferences: [],
+        digest: emptyDigest(generatedAt),
+        consequenceUnderstanding: emptyConsequenceUnderstanding(generatedAt, reason),
+        planAlignment: null,
+        boundaryImpact: [],
+        limitations: commonLimitations(),
+        factProvenance: provenanceMap(),
+    };
+    return { ...core, artifactHash: hash(artifactHashInput(core)) };
+}
+function privacyBlock() {
+    return {
+        sourceUploaded: false,
+        sourceStored: false,
+        diffStored: false,
+        modelUsed: false,
+        factsOnly: true,
+        outputContains: ['repo-relative paths', 'symbol names', 'line numbers', 'import targets', 'owner tokens', 'hashes'],
+        outputOmits: ['source text', 'diff hunks', 'patch content', 'shell command bodies', 'model judgments'],
+    };
+}
+function commonLimitations() {
+    return [
+        'TypeScript/JavaScript static analysis only.',
+        'Dynamic dispatch, reflection, dependency injection, runtime wiring, and generated code may be under-counted.',
+        'Test references mean a test file statically references a changed symbol; this does not claim behavioral coverage.',
+        'No LLM or probabilistic judgment is used in this artifact.',
+    ];
+}
+function provenanceMap() {
+    return {
+        changedFiles: 'git-diff',
+        changedSymbols: 'typescript-compiler',
+        references: 'typescript-compiler',
+        importEdgesChanged: 'git-diff',
+        testReferences: 'typescript-compiler',
+        suppressedArtifacts: 'generated-artifact-heuristic',
+        digest: 'deterministic-ranking',
+        consequenceUnderstanding: 'typescript-checker',
+        planAlignment: 'session-plan',
+        boundaryImpact: 'codeowners-profile',
+    };
+}
+function changedFileFacts(diffFiles) {
+    return diffFiles.map((file) => ({
+        path: normalizeRepoPath(file.path),
+        changeType: file.changeType,
+        addedLines: file.addedLines || 0,
+        removedLines: file.removedLines || 0,
+        provenance: 'git-diff',
+    })).sort((a, b) => a.path.localeCompare(b.path));
+}
+function importEdgeFacts(diffFiles, suppressedArtifacts = []) {
+    const suppressed = new Set(suppressedArtifacts.map((item) => item.path));
+    return (0, import_edge_extractor_1.extractImportEdgesFromDiff)(diffFiles.filter((file) => !suppressed.has(normalizeRepoPath(file.path))))
+        .map((edge) => ({
+        sourceFile: normalizeRepoPath(edge.sourceFile),
+        sourceLine: edge.sourceLine,
+        importTarget: edge.importTarget,
+        importKind: edge.importKind,
+        language: edge.language,
+        provenance: 'git-diff',
+    }))
+        .sort((a, b) => a.sourceFile.localeCompare(b.sourceFile) ||
+        a.sourceLine - b.sourceLine ||
+        a.importTarget.localeCompare(b.importTarget));
+}
+function loadNeurcodeIgnorePatterns(projectRoot) {
+    const path = (0, path_1.join)(projectRoot, '.neurcodeignore');
+    if (!(0, fs_1.existsSync)(path))
+        return [];
+    try {
+        return (0, fs_1.readFileSync)(path, 'utf8')
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !line.startsWith('#'))
+            .map((line) => normalizeRepoPath(line.replace(/^\//, '')))
+            .map((line) => line.endsWith('/') ? `${line}**` : line);
+    }
+    catch {
+        return [];
+    }
+}
+function classifyGeneratedArtifact(projectRoot, file, ignorePatterns) {
+    const normalized = normalizeRepoPath(file);
+    if (ignorePatterns.some((pattern) => matchesSimpleGlob(normalized, pattern) || normalized === pattern)) {
+        return { path: normalized, reasonCode: 'neurcodeignore', provenance: 'generated-artifact-heuristic' };
+    }
+    const segments = normalized.split('/');
+    if (segments.includes('dist'))
+        return { path: normalized, reasonCode: 'dist_directory', provenance: 'generated-artifact-heuristic' };
+    if (segments.includes('build'))
+        return { path: normalized, reasonCode: 'build_directory', provenance: 'generated-artifact-heuristic' };
+    if (segments.includes('out'))
+        return { path: normalized, reasonCode: 'out_directory', provenance: 'generated-artifact-heuristic' };
+    if (/\.min\.js$/i.test(normalized))
+        return { path: normalized, reasonCode: 'minified_javascript', provenance: 'generated-artifact-heuristic' };
+    if (/\.bundle\.js$/i.test(normalized))
+        return { path: normalized, reasonCode: 'bundled_javascript', provenance: 'generated-artifact-heuristic' };
+    const abs = (0, path_1.join)(projectRoot, normalized);
+    if (!(0, fs_1.existsSync)(abs))
+        return null;
+    let firstLines;
+    try {
+        firstLines = (0, fs_1.readFileSync)(abs, 'utf8').split(/\r?\n/, 4).join('\n');
+    }
+    catch {
+        return null;
+    }
+    for (const fingerprint of GENERATED_FINGERPRINTS) {
+        if (firstLines.includes(fingerprint.needle)) {
+            return { path: normalized, reasonCode: fingerprint.reasonCode, provenance: 'generated-artifact-heuristic' };
+        }
+    }
+    return null;
+}
+function classifyGeneratedArtifacts(projectRoot, changedFiles) {
+    const ignorePatterns = loadNeurcodeIgnorePatterns(projectRoot);
+    const byPath = new Map();
+    for (const file of changedFiles) {
+        const item = classifyGeneratedArtifact(projectRoot, file, ignorePatterns);
+        if (item)
+            byPath.set(item.path, item);
+    }
+    return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+function scopeRoots(projectRoot, changedRepoRelFiles) {
+    const roots = new Set();
+    for (const file of changedRepoRelFiles) {
+        const parts = file.split('/');
+        const pkgIdx = parts.indexOf('packages');
+        const servicesIdx = parts.indexOf('services');
+        const webIdx = parts.indexOf('web');
+        const appsIdx = parts.indexOf('apps');
+        const srcIdx = parts.indexOf('src');
+        let depth;
+        if (pkgIdx >= 0 && parts[pkgIdx + 1] !== undefined)
+            depth = pkgIdx + 2;
+        else if (servicesIdx >= 0 && parts[servicesIdx + 1] !== undefined)
+            depth = servicesIdx + 2;
+        else if (webIdx >= 0 && parts[webIdx + 1] !== undefined)
+            depth = webIdx + 2;
+        else if (appsIdx >= 0 && parts[appsIdx + 1] !== undefined)
+            depth = appsIdx + 2;
+        else if (srcIdx >= 0)
+            depth = srcIdx + 1;
+        else
+            depth = Math.max(1, parts.length - 1);
+        roots.add((0, path_1.join)(projectRoot, parts.slice(0, depth).join('/')));
+    }
+    return [...roots].filter((root) => (0, fs_1.existsSync)(root));
+}
+function gatherSourceFiles(dir, out, cap) {
+    if (out.length > cap)
+        return;
+    let names;
+    try {
+        names = (0, fs_1.readdirSync)(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (out.length > cap)
+            return;
+        const path = (0, path_1.join)(dir, name);
+        let stat;
+        try {
+            stat = (0, fs_1.statSync)(path);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            if (!SKIP_DIR.test(name))
+                gatherSourceFiles(path, out, cap);
+        }
+        else if (TS_LIKE.test(name) && !/\.d\.ts$/i.test(name)) {
+            out.push(path);
+        }
+    }
+}
+/** Discover workspace packages and their internal dependency edges from package.json. */
+function loadWorkspacePackages(projectRoot) {
+    const groups = ['packages', 'services', 'web', 'apps'];
+    const packages = [];
+    const names = new Set();
+    for (const group of groups) {
+        let entries;
+        try {
+            entries = (0, fs_1.readdirSync)((0, path_1.join)(projectRoot, group));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const dirRel = `${group}/${entry}`;
+            const absDir = (0, path_1.join)(projectRoot, group, entry);
+            const pjPath = (0, path_1.join)(absDir, 'package.json');
+            if (!(0, fs_1.existsSync)(pjPath))
+                continue;
+            let pj;
+            try {
+                pj = JSON.parse((0, fs_1.readFileSync)(pjPath, 'utf8'));
+            }
+            catch {
+                continue;
+            }
+            const name = typeof pj.name === 'string' ? pj.name : null;
+            if (!name)
+                continue;
+            const srcEntryRel = ['src/index.ts', 'src/index.tsx', 'src/index.js']
+                .map((file) => `${dirRel}/${file}`)
+                .find((file) => (0, fs_1.existsSync)((0, path_1.join)(projectRoot, file))) ?? null;
+            const deps = new Set();
+            for (const key of ['dependencies', 'devDependencies', 'peerDependencies']) {
+                const block = pj[key];
+                if (block && typeof block === 'object') {
+                    for (const dep of Object.keys(block))
+                        deps.add(dep);
+                }
+            }
+            packages.push({ name, dirRel, absDir, srcEntryRel, deps });
+            names.add(name);
+        }
+    }
+    // Retain only workspace-internal dependency edges.
+    for (const pkg of packages) {
+        pkg.deps = new Set([...pkg.deps].filter((dep) => names.has(dep)));
+    }
+    return packages;
+}
+/** Which workspace packages contain the changed files (most specific dir wins). */
+function changedWorkspacePackages(workspace, changedFiles) {
+    const byName = new Map();
+    for (const file of changedFiles) {
+        let best = null;
+        for (const pkg of workspace) {
+            if (file === pkg.dirRel || file.startsWith(`${pkg.dirRel}/`)) {
+                if (!best || pkg.dirRel.length > best.dirRel.length)
+                    best = pkg;
+            }
+        }
+        if (best)
+            byName.set(best.name, best);
+    }
+    return [...byName.values()];
+}
+/** Packages that (transitively) depend on any changed package — the reverse-dep closure. */
+function reverseDepConsumers(workspace, changedNames) {
+    const consumers = new Set();
+    let added = true;
+    while (added) {
+        added = false;
+        for (const pkg of workspace) {
+            if (changedNames.has(pkg.name) || consumers.has(pkg.name))
+                continue;
+            for (const dep of pkg.deps) {
+                if (changedNames.has(dep) || consumers.has(dep)) {
+                    consumers.add(pkg.name);
+                    added = true;
+                    break;
+                }
+            }
+        }
+    }
+    return workspace.filter((pkg) => consumers.has(pkg.name));
+}
+/** Source files in a consumer package that directly import a changed package by name. */
+function gatherDirectImporterFiles(consumer, changedPackageNames, out, cap) {
+    const srcDir = (0, path_1.join)(consumer.absDir, 'src');
+    const base = (0, fs_1.existsSync)(srcDir) ? srcDir : consumer.absDir;
+    const candidates = [];
+    gatherSourceFiles(base, candidates, cap);
+    for (const file of candidates) {
+        if (out.length > cap)
+            return;
+        let text;
+        try {
+            text = (0, fs_1.readFileSync)(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (changedPackageNames.some((name) => text.includes(`'${name}'`) ||
+            text.includes(`"${name}"`) ||
+            text.includes(`'${name}/`) ||
+            text.includes(`"${name}/`))) {
+            out.push(file);
+        }
+    }
+}
+/** Map workspace package imports to their source entry so refs resolve to src, not dist/*.d.ts. */
+function buildWorkspacePaths(workspace) {
+    const paths = {};
+    for (const pkg of workspace) {
+        if (!pkg.srcEntryRel)
+            continue;
+        paths[pkg.name] = [pkg.srcEntryRel];
+        paths[`${pkg.name}/*`] = [`${pkg.dirRel}/src/*`];
+    }
+    return paths;
+}
+function resolveModuleRepoFile(projectRoot, containingFile, moduleSpecifier, compilerOptions) {
+    const resolved = ts.resolveModuleName(moduleSpecifier, containingFile.fileName, compilerOptions, ts.sys).resolvedModule?.resolvedFileName;
+    if (!resolved || /\.d\.ts$/i.test(resolved))
+        return null;
+    const normalized = normalizeRepoPath(repoRel(projectRoot, resolved));
+    return normalized.startsWith('..') ? null : normalized;
+}
+function hasDefaultExportModifier(node) {
+    return Boolean(ts.canHaveModifiers(node) && ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword));
+}
+function buildImportExportTargetGraph(input) {
+    const sourceFilesByRel = new Map();
+    for (const sourceFile of input.program.getSourceFiles()) {
+        if (sourceFile.isDeclarationFile || sourceFile.fileName.includes('node_modules'))
+            continue;
+        sourceFilesByRel.set(repoRel(input.projectRoot, sourceFile.fileName), sourceFile);
+    }
+    const targetByFileAndName = new Map();
+    const localExportsByFile = new Map();
+    for (const target of input.targets) {
+        targetByFileAndName.set(`${target.file}\0${target.name}`, target);
+        if (!target.declaration || !isExportedDeclaration(target.declaration))
+            continue;
+        const bucket = localExportsByFile.get(target.file) ?? new Map();
+        bucket.set(target.name, target);
+        if (hasDefaultExportModifier(target.declaration))
+            bucket.set('default', target);
+        localExportsByFile.set(target.file, bucket);
+    }
+    const exportTargetsByFile = new Map();
+    const resolveExportsForFile = (file, visiting = new Set()) => {
+        const cached = exportTargetsByFile.get(file);
+        if (cached)
+            return cached;
+        if (visiting.has(file))
+            return new Map();
+        visiting.add(file);
+        const out = new Map(localExportsByFile.get(file) ?? []);
+        const sourceFile = sourceFilesByRel.get(file);
+        if (sourceFile) {
+            for (const statement of sourceFile.statements) {
+                if (!ts.isExportDeclaration(statement))
+                    continue;
+                const moduleFile = statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier)
+                    ? resolveModuleRepoFile(input.projectRoot, sourceFile, statement.moduleSpecifier.text, input.compilerOptions)
+                    : file;
+                const moduleExports = moduleFile ? resolveExportsForFile(moduleFile, new Set(visiting)) : out;
+                if (statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+                    for (const specifier of statement.exportClause.elements) {
+                        const importedName = (specifier.propertyName ?? specifier.name).text;
+                        const exportedName = specifier.name.text;
+                        const target = moduleExports.get(importedName) ?? targetByFileAndName.get(`${moduleFile ?? file}\0${importedName}`);
+                        if (target)
+                            out.set(exportedName, target);
+                    }
+                }
+                else if (!statement.exportClause && moduleFile) {
+                    for (const [name, target] of moduleExports) {
+                        if (name !== 'default')
+                            out.set(name, target);
+                    }
+                }
+            }
+        }
+        exportTargetsByFile.set(file, out);
+        visiting.delete(file);
+        return out;
+    };
+    for (const file of sourceFilesByRel.keys())
+        resolveExportsForFile(file);
+    const importsByFile = new Map();
+    const namespaceImportsByFile = new Map();
+    for (const [file, sourceFile] of sourceFilesByRel) {
+        const imports = new Map();
+        const namespaces = new Map();
+        for (const statement of sourceFile.statements) {
+            if (!ts.isImportDeclaration(statement) || !statement.importClause)
+                continue;
+            if (!ts.isStringLiteralLike(statement.moduleSpecifier))
+                continue;
+            const moduleFile = resolveModuleRepoFile(input.projectRoot, sourceFile, statement.moduleSpecifier.text, input.compilerOptions);
+            if (!moduleFile)
+                continue;
+            const moduleExports = resolveExportsForFile(moduleFile);
+            const importClause = statement.importClause;
+            if (importClause.name) {
+                const target = moduleExports.get('default') ?? moduleExports.get(importClause.name.text);
+                if (target)
+                    imports.set(importClause.name.text, target);
+            }
+            const namedBindings = importClause.namedBindings;
+            if (namedBindings && ts.isNamedImports(namedBindings)) {
+                for (const specifier of namedBindings.elements) {
+                    const importedName = (specifier.propertyName ?? specifier.name).text;
+                    const target = moduleExports.get(importedName);
+                    if (target)
+                        imports.set(specifier.name.text, target);
+                }
+            }
+            else if (namedBindings && ts.isNamespaceImport(namedBindings)) {
+                namespaces.set(namedBindings.name.text, moduleExports);
+            }
+        }
+        if (imports.size > 0)
+            importsByFile.set(file, imports);
+        if (namespaces.size > 0)
+            namespaceImportsByFile.set(file, namespaces);
+    }
+    return { importsByFile, namespaceImportsByFile, exportTargetsByFile };
+}
+function importExportGraphTargetForIdentifier(node, sourceRel, graph) {
+    if (ts.isPropertyAccessExpression(node.parent) &&
+        node.parent.name === node &&
+        ts.isIdentifier(node.parent.expression)) {
+        const namespaces = graph.namespaceImportsByFile.get(sourceRel);
+        const namespaceExports = namespaces?.get(node.parent.expression.text);
+        const target = namespaceExports?.get(node.text);
+        if (target)
+            return target;
+    }
+    return graph.importsByFile.get(sourceRel)?.get(node.text);
+}
+function normalizedHunkLines(hunk) {
+    const out = [];
+    let oldCursor = hunk.oldStart ?? 1;
+    let newCursor = hunk.newStart ?? 1;
+    for (const line of (hunk.lines ?? [])) {
+        if (line.type === 'added') {
+            const newLine = line.lineNumber ?? newCursor;
+            out.push({ type: line.type, content: line.content ?? '', oldLine: null, newLine });
+            newCursor += 1;
+            continue;
+        }
+        if (line.type === 'removed') {
+            const oldLine = line.lineNumber ?? oldCursor;
+            out.push({ type: line.type, content: line.content ?? '', oldLine, newLine: null });
+            oldCursor += 1;
+            continue;
+        }
+        const explicitLine = typeof line.lineNumber === 'number' ? line.lineNumber : null;
+        out.push({
+            type: line.type,
+            content: line.content ?? '',
+            oldLine: explicitLine ?? oldCursor,
+            newLine: explicitLine ?? newCursor,
+        });
+        oldCursor += 1;
+        newCursor += 1;
+    }
+    return out;
+}
+function changedNewLines(file) {
+    const out = [];
+    for (const hunk of file.hunks ?? []) {
+        for (const line of normalizedHunkLines(hunk)) {
+            if (line.type === 'added' && line.newLine !== null)
+                out.push(line.newLine);
+        }
+    }
+    return uniqueSorted(out.map(String)).map(Number).filter((value) => Number.isFinite(value));
+}
+function addedLineSet(file) {
+    return new Set(changedNewLines(file));
+}
+function rightmostIdentifierText(node) {
+    if (ts.isIdentifier(node))
+        return node.text;
+    if (ts.isPropertyAccessExpression(node))
+        return rightmostIdentifierText(node.name);
+    if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) {
+        return node.argumentExpression.text;
+    }
+    return null;
+}
+function effectCategoryForCalleeName(name) {
+    if (!name)
+        return null;
+    for (const entry of EFFECT_REGISTRY) {
+        if (entry.callees.has(name))
+            return entry.category;
+    }
+    return null;
+}
+function effectMatchesFromLineContent(content) {
+    const out = [];
+    for (const entry of EFFECT_REGISTRY) {
+        for (const callee of entry.callees) {
+            const escaped = callee.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            if (new RegExp(`(?:\\b|\\.)${escaped}\\s*\\(`).test(content)) {
+                out.push({ calleeName: callee, effectCategory: entry.category });
+            }
+        }
+    }
+    return out;
+}
+function diffFileByPath(diffFiles) {
+    return new Map(diffFiles.map((file) => [normalizeRepoPath(file.path), file]));
+}
+function oldFileTextFromDiff(projectRoot, diffFile) {
+    const path = normalizeRepoPath(diffFile.path);
+    const abs = (0, path_1.join)(projectRoot, path);
+    if (!(0, fs_1.existsSync)(abs))
+        return null;
+    let currentLines;
+    try {
+        currentLines = (0, fs_1.readFileSync)(abs, 'utf8').split(/\r?\n/);
+    }
+    catch {
+        return null;
+    }
+    const hunks = [...(diffFile.hunks ?? [])].sort((a, b) => (b.newStart ?? 1) - (a.newStart ?? 1));
+    for (const hunk of hunks) {
+        const newStart = Math.max(1, hunk.newStart ?? 1);
+        const newLines = Math.max(0, hunk.newLines ?? 0);
+        const oldLines = (hunk.lines ?? [])
+            .filter((line) => line.type === 'context' || line.type === 'removed')
+            .map((line) => line.content ?? '');
+        currentLines.splice(newStart - 1, newLines, ...oldLines);
+    }
+    return currentLines.join('\n');
+}
+function isExportedDeclaration(node) {
+    const hasExportModifier = (candidate) => Boolean(ts.canHaveModifiers(candidate) && ts.getModifiers(candidate)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword));
+    if (hasExportModifier(node))
+        return true;
+    if (ts.isVariableDeclaration(node)) {
+        const statement = node.parent?.parent;
+        return Boolean(statement && hasExportModifier(statement));
+    }
+    return false;
+}
+function declarationContractShape(node) {
+    const name = declarationName(node);
+    const kind = declarationKind(node);
+    if (!name || !kind)
+        return null;
+    const sourceFile = node.getSourceFile();
+    const paramTypes = [];
+    let returnType = null;
+    if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) {
+        for (const param of node.parameters) {
+            paramTypes.push(param.type ? param.type.getText(sourceFile) : 'implicit');
+        }
+        returnType = node.type ? node.type.getText(sourceFile) : null;
+    }
+    else if (ts.isVariableDeclaration(node) && node.initializer && ts.isArrowFunction(node.initializer)) {
+        for (const param of node.initializer.parameters) {
+            paramTypes.push(param.type ? param.type.getText(sourceFile) : 'implicit');
+        }
+        returnType = node.initializer.type ? node.initializer.type.getText(sourceFile) : null;
+    }
+    const members = [];
+    const pushMember = (memberName) => {
+        if (!memberName)
+            return;
+        if (ts.isIdentifier(memberName) || ts.isStringLiteral(memberName) || ts.isNumericLiteral(memberName)) {
+            members.push(memberName.text);
+        }
+    };
+    if (ts.isInterfaceDeclaration(node) || ts.isClassDeclaration(node)) {
+        for (const member of node.members)
+            pushMember(member.name);
+    }
+    else if (ts.isTypeAliasDeclaration(node) && ts.isTypeLiteralNode(node.type)) {
+        for (const member of node.type.members)
+            pushMember(member.name);
+    }
+    return {
+        name: name.text,
+        kind,
+        exported: isExportedDeclaration(node),
+        paramTypes,
+        returnType,
+        members: uniqueSorted(members),
+    };
+}
+function contractShapesFromSourceText(text, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const shapes = new Map();
+    const visit = (node) => {
+        const shape = declarationContractShape(node);
+        if (shape)
+            shapes.set(`${shape.kind}#${shape.name}`, shape);
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sourceFile, visit);
+    return shapes;
+}
+function contractShapeFromTarget(target) {
+    return target.declaration ? declarationContractShape(target.declaration) : null;
+}
+function compareContractShapes(target, current, previous) {
+    if (!current.exported && !previous?.exported)
+        return null;
+    const changes = [];
+    const push = (change, memberName = null) => {
+        changes.push({ change, memberName, line: target.lineStart });
+    };
+    if (current.exported && !previous?.exported)
+        push('export_added');
+    if (!current.exported && previous?.exported)
+        push('export_removed');
+    if (previous && previous.kind !== current.kind)
+        push('kind_changed');
+    if (previous) {
+        if (current.paramTypes.length > previous.paramTypes.length)
+            push('param_added');
+        if (current.paramTypes.length < previous.paramTypes.length)
+            push('param_removed');
+        if (current.paramTypes.length === previous.paramTypes.length &&
+            current.paramTypes.some((type, index) => type !== previous.paramTypes[index])) {
+            push('param_type_changed');
+        }
+        if (current.returnType !== previous.returnType)
+            push('return_type_changed');
+        const currentMembers = new Set(current.members);
+        const previousMembers = new Set(previous.members);
+        for (const member of current.members) {
+            if (!previousMembers.has(member))
+                push('member_added', member);
+        }
+        for (const member of previous.members) {
+            if (!currentMembers.has(member))
+                push('member_removed', member);
+        }
+    }
+    const uniqueChanges = new Map();
+    for (const change of changes) {
+        uniqueChanges.set(`${change.change}:${change.memberName ?? ''}`, change);
+    }
+    const rows = [...uniqueChanges.values()].sort((a, b) => a.change.localeCompare(b.change) ||
+        String(a.memberName ?? '').localeCompare(String(b.memberName ?? '')));
+    if (rows.length === 0)
+        return null;
+    return {
+        symbol: target.name,
+        file: target.file,
+        kind: target.kind,
+        line: target.lineStart,
+        changes: rows,
+        consumers: [],
+        externalConsumers: [],
+        provenance: 'typescript-checker',
+    };
+}
+function declarationKind(node) {
+    if (ts.isFunctionDeclaration(node))
+        return 'function';
+    if (ts.isClassDeclaration(node))
+        return 'class';
+    if (ts.isInterfaceDeclaration(node))
+        return 'interface';
+    if (ts.isTypeAliasDeclaration(node))
+        return 'type';
+    if (ts.isEnumDeclaration(node))
+        return 'enum';
+    if (ts.isMethodDeclaration(node))
+        return 'method';
+    if (ts.isVariableDeclaration(node) &&
+        ts.isVariableDeclarationList(node.parent) &&
+        ts.isVariableStatement(node.parent.parent) &&
+        ts.isSourceFile(node.parent.parent.parent)) {
+        return 'const';
+    }
+    return null;
+}
+function declarationName(node) {
+    if ((ts.isFunctionDeclaration(node) ||
+        ts.isClassDeclaration(node) ||
+        ts.isInterfaceDeclaration(node) ||
+        ts.isTypeAliasDeclaration(node) ||
+        ts.isEnumDeclaration(node)) &&
+        node.name) {
+        return node.name;
+    }
+    if ((ts.isMethodDeclaration(node) || ts.isVariableDeclaration(node)) && ts.isIdentifier(node.name)) {
+        return node.name;
+    }
+    return undefined;
+}
+function collectDeclarations(sourceFile, checker, projectRoot) {
+    const out = [];
+    const file = repoRel(projectRoot, sourceFile.fileName);
+    const visit = (node) => {
+        const kind = declarationKind(node);
+        const name = declarationName(node);
+        if (kind && name) {
+            const start = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+            const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd()).line + 1;
+            out.push({
+                name: name.text,
+                kind,
+                file,
+                startLine: start,
+                endLine: end,
+                node,
+                symbol: checker.getSymbolAtLocation(name),
+            });
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sourceFile, visit);
+    return out;
+}
+function smallestContaining(declarations, line) {
+    return declarations
+        .filter((decl) => line >= decl.startLine && line <= decl.endLine)
+        .sort((a, b) => (a.endLine - a.startLine) - (b.endLine - b.startLine))[0] ?? null;
+}
+function resolveAlias(checker, symbol) {
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
+        try {
+            return checker.getAliasedSymbol(symbol);
+        }
+        catch {
+            return symbol;
+        }
+    }
+    return symbol;
+}
+function symbolKey(file, kind, name) {
+    return `${file}::${kind}::${name}`;
+}
+function matchesSimpleGlob(file, pattern) {
+    const normalizedFile = normalizeRepoPath(file);
+    const normalizedPattern = normalizeRepoPath(pattern);
+    if (!normalizedPattern)
+        return false;
+    if (normalizedPattern === normalizedFile)
+        return true;
+    if (normalizedPattern.endsWith('/**')) {
+        const prefix = normalizedPattern.slice(0, -3);
+        return normalizedFile === prefix || normalizedFile.startsWith(`${prefix}/`);
+    }
+    if (normalizedPattern.endsWith('/*')) {
+        const prefix = normalizedPattern.slice(0, -2);
+        if (!normalizedFile.startsWith(`${prefix}/`))
+            return false;
+        return normalizedFile.slice(prefix.length + 1).indexOf('/') === -1;
+    }
+    return false;
+}
+function buildPlanAlignment(session, changedFiles, changedSymbols) {
+    const plan = session?.contract.agentPlan ?? null;
+    const intent = session?.contract.intentContract ?? null;
+    if (!plan && !intent)
+        return null;
+    const plannedFiles = uniqueSorted([...(plan?.expectedFiles ?? []), ...(intent?.target.pathTokens ?? [])].map(normalizeRepoPath));
+    const plannedGlobs = uniqueSorted([
+        ...(plan?.expectedGlobs ?? []),
+        ...(intent?.target.expectedPathGlobs ?? []),
+        ...plannedFiles,
+    ].map(normalizeRepoPath));
+    const plannedFilesTouched = changedFiles.filter((file) => plannedGlobs.some((pattern) => matchesSimpleGlob(file, pattern) || pattern === file));
+    const unplannedFilesTouched = changedFiles.filter((file) => !plannedFilesTouched.includes(file));
+    const planText = [
+        plan?.summary,
+        ...(plan?.steps ?? []),
+        ...(plan?.constraints ?? []),
+        ...(plan?.risks ?? []),
+        session?.contract.goal,
+    ].filter(Boolean).join('\n');
+    const changedSymbolsMentionedInPlan = changedSymbols
+        .filter((symbol) => new RegExp(`\\b${symbol.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(planText))
+        .map((symbol) => `${symbol.file}#${symbol.name}`);
+    return {
+        plannedFiles,
+        plannedGlobs,
+        plannedFilesTouched,
+        unplannedFilesTouched,
+        changedSymbolsMentionedInPlan: uniqueSorted(changedSymbolsMentionedInPlan),
+        provenance: 'session-plan',
+    };
+}
+function buildBoundaryImpact(profile, changedFiles) {
+    if (!profile)
+        return [];
+    return changedFiles.map((file) => {
+        const approvalRequiredGlobs = profile.approvalRequiredPaths.filter((glob) => matchesSimpleGlob(file, glob));
+        return {
+            file,
+            owners: (0, governance_runtime_1.ownersForPath)(file, profile.ownershipBoundaries),
+            approvalRequired: approvalRequiredGlobs.length > 0,
+            approvalRequiredGlobs,
+            provenance: 'codeowners-profile',
+        };
+    }).filter((item) => item.owners.length > 0 || item.approvalRequired)
+        .sort((a, b) => a.file.localeCompare(b.file));
+}
+function packageForFile(workspace, file) {
+    let best = null;
+    for (const pkg of workspace) {
+        if (file === pkg.dirRel || file.startsWith(`${pkg.dirRel}/`)) {
+            if (!best || pkg.dirRel.length > best.dirRel.length)
+                best = pkg;
+        }
+    }
+    return best;
+}
+function isRegistrationOrConfigReference(ref) {
+    const file = normalizeRepoPath(ref.referencingFile).toLowerCase();
+    const symbol = (ref.referencingSymbol ?? '').toLowerCase();
+    return (/(^|\/)(index|app|main|routes?|setup|config|registry|register)\.[tj]sx?$/.test(file) ||
+        symbol.includes('register') ||
+        symbol.includes('route'));
+}
+function ownersForReference(profile, file) {
+    return profile ? (0, governance_runtime_1.ownersForPath)(file, profile.ownershipBoundaries) : [];
+}
+function approvalRequiredForReference(profile, file) {
+    return profile ? profile.approvalRequiredPaths.some((glob) => matchesSimpleGlob(file, glob)) : false;
+}
+function sensitiveForReference(profile, file) {
+    return profile ? profile.sensitiveBoundaries.some((boundary) => matchesSimpleGlob(file, boundary.glob)) : false;
+}
+function runtimeGovernanceConsumer(consumer) {
+    const haystack = [
+        consumer.file,
+        consumer.symbol ?? '',
+        consumer.kind ?? '',
+    ].join(' ').toLowerCase();
+    return /\b(runtime|governance|approval|approv|session|evidence|ledger|hook|control-plane|controlplane|audit|receipt|policy)\b/.test(haystack);
+}
+function profileFromSession(session) {
+    if (!session)
+        return null;
+    return {
+        ownershipBoundaries: session.contract.ownershipRules ?? [],
+        approvalRequiredPaths: session.contract.approvalRequiredGlobs ?? [],
+        sensitiveBoundaries: (session.contract.sensitiveGlobs ?? []).map((glob) => ({
+            glob,
+            reason: 'session-contract',
+        })),
+    };
+}
+function plannedFileMatches(planAlignment, file) {
+    if (!planAlignment)
+        return false;
+    return planAlignment.plannedGlobs.some((glob) => matchesSimpleGlob(file, glob) || normalizeRepoPath(glob) === file);
+}
+function rankReference(ref, context) {
+    const targetPkg = packageForFile(context.workspace, ref.targetFile);
+    const referencingPkg = packageForFile(context.workspace, ref.referencingFile);
+    const targetPackageName = targetPkg?.name ?? null;
+    const referencingPackageName = referencingPkg?.name ?? null;
+    const crossPackage = Boolean(targetPackageName && referencingPackageName && targetPackageName !== referencingPackageName);
+    const outsideChangedPackage = Boolean(referencingPackageName && !context.changedPackageNames.has(referencingPackageName));
+    const outsideChangedFile = ref.targetFile !== ref.referencingFile;
+    const owners = ownersForReference(context.profile, ref.referencingFile);
+    const approvalRequired = approvalRequiredForReference(context.profile, ref.referencingFile);
+    const inChangedFiles = context.changedFileSet.has(ref.referencingFile);
+    const registrationOrConfig = isRegistrationOrConfigReference(ref);
+    const importOnly = ref.referencingSymbol === null;
+    const planUnmentioned = context.planAlignment ? !plannedFileMatches(context.planAlignment, ref.referencingFile) : false;
+    const reasonCodes = [];
+    let score = 0;
+    if (crossPackage) {
+        reasonCodes.push('cross_package_reference');
+        score += 40;
+    }
+    if (outsideChangedPackage) {
+        reasonCodes.push('outside_changed_package');
+        score += 20;
+    }
+    if (outsideChangedFile) {
+        reasonCodes.push('outside_changed_file');
+        score += 15;
+    }
+    if (!ref.isTestFile) {
+        reasonCodes.push('non_test_reference');
+        score += 28;
+    }
+    else {
+        reasonCodes.push('test_reference');
+        score -= 22;
+    }
+    if (owners.length > 0) {
+        reasonCodes.push('owned_path');
+        score += 18;
+    }
+    if (approvalRequired) {
+        reasonCodes.push('approval_required_path');
+        score += 35;
+    }
+    if (!inChangedFiles) {
+        reasonCodes.push('not_in_changed_files');
+        score += 12;
+    }
+    if (planUnmentioned) {
+        reasonCodes.push('plan_unmentioned_file');
+        score += 10;
+    }
+    if (!outsideChangedFile) {
+        reasonCodes.push('same_file_reference');
+        score -= 25;
+    }
+    if (registrationOrConfig) {
+        reasonCodes.push('registration_or_config_surface');
+        score -= 12;
+    }
+    if (importOnly) {
+        reasonCodes.push('import_or_declaration_reference');
+        score -= 25;
+    }
+    return {
+        rank: 0,
+        score,
+        targetFile: ref.targetFile,
+        targetSymbol: ref.targetSymbol,
+        targetKind: ref.targetKind,
+        referencingFile: ref.referencingFile,
+        referencingSymbol: ref.referencingSymbol,
+        referencingKind: ref.referencingKind,
+        line: ref.line,
+        isTestFile: ref.isTestFile,
+        owners,
+        approvalRequired,
+        reasonCodes: uniqueSorted(reasonCodes),
+        provenance: 'deterministic-ranking',
+    };
+}
+function combineReasonCodes(items) {
+    return uniqueSorted(items.flatMap((item) => item.reasonCodes));
+}
+function buildConsequences(rankedReferences) {
+    const byKey = new Map();
+    for (const ref of rankedReferences) {
+        const key = `${ref.targetFile}#${ref.targetKind}#${ref.targetSymbol}<-${ref.referencingFile}`;
+        const bucket = byKey.get(key) ?? [];
+        bucket.push(ref);
+        byKey.set(key, bucket);
+    }
+    return [...byKey.values()].map((items) => {
+        const first = items[0];
+        const nonTest = items.filter((item) => !item.isTestFile);
+        const tests = items.filter((item) => item.isTestFile);
+        const importOnly = items.filter((item) => item.reasonCodes.includes('import_or_declaration_reference'));
+        const owners = uniqueSorted(items.flatMap((item) => item.owners));
+        const reasonCodes = combineReasonCodes(items);
+        const maxScore = Math.max(...items.map((item) => item.score));
+        const score = maxScore +
+            Math.min(30, items.length * 4) +
+            nonTest.length * 6 -
+            tests.length * 2 -
+            importOnly.length * 3;
+        return {
+            rank: 0,
+            score,
+            targetFile: first.targetFile,
+            targetSymbol: first.targetSymbol,
+            targetKind: first.targetKind,
+            referencingFile: first.referencingFile,
+            referenceCount: items.length,
+            nonTestReferenceCount: nonTest.length,
+            testReferenceCount: tests.length,
+            representativeLines: Array.from(new Set(items.map((item) => item.line)))
+                .sort((a, b) => a - b)
+                .slice(0, 3),
+            representativeSymbols: uniqueSorted(items.map((item) => item.referencingSymbol)).slice(0, 3),
+            owners,
+            approvalRequired: items.some((item) => item.approvalRequired),
+            reasonCodes,
+            provenance: 'deterministic-ranking',
+        };
+    }).sort((a, b) => b.score - a.score ||
+        b.nonTestReferenceCount - a.nonTestReferenceCount ||
+        b.referenceCount - a.referenceCount ||
+        a.targetFile.localeCompare(b.targetFile) ||
+        a.targetSymbol.localeCompare(b.targetSymbol) ||
+        a.referencingFile.localeCompare(b.referencingFile)).map((item, index) => ({ ...item, rank: index + 1 }));
+}
+function buildStructuralDigest(input) {
+    const changedFileSet = new Set(input.changedFiles);
+    const changedPackageNameSet = new Set(input.changedPackageNames);
+    const rankedReferences = input.references
+        .map((ref) => rankReference(ref, {
+        workspace: input.workspace,
+        changedFileSet,
+        changedPackageNames: changedPackageNameSet,
+        profile: input.profile,
+        planAlignment: input.planAlignment,
+    }))
+        .sort((a, b) => b.score - a.score ||
+        a.targetFile.localeCompare(b.targetFile) ||
+        a.targetSymbol.localeCompare(b.targetSymbol) ||
+        a.referencingFile.localeCompare(b.referencingFile) ||
+        a.line - b.line)
+        .map((ref, index) => ({ ...ref, rank: index + 1 }));
+    const consequences = buildConsequences(rankedReferences);
+    const topConsequences = consequences.slice(0, 6);
+    const topReferences = rankedReferences.slice(0, 8);
+    const symbolRows = input.changedSymbols.map((symbol) => {
+        const refs = input.references.filter((ref) => ref.targetFile === symbol.file &&
+            ref.targetKind === symbol.kind &&
+            ref.targetSymbol === symbol.name);
+        const nonTest = refs.filter((ref) => !ref.isTestFile);
+        const tests = refs.filter((ref) => ref.isTestFile);
+        const targetPkg = packageForFile(input.workspace, symbol.file);
+        const crossPackageCount = refs.filter((ref) => {
+            const referencingPkg = packageForFile(input.workspace, ref.referencingFile);
+            return Boolean(targetPkg?.name && referencingPkg?.name && targetPkg.name !== referencingPkg.name);
+        }).length;
+        const reasonCodes = [];
+        let score = refs.length + nonTest.length * 3 + crossPackageCount * 5 - tests.length;
+        if (crossPackageCount > 0) {
+            reasonCodes.push('cross_package_reference');
+            score += 12;
+        }
+        if (nonTest.length > 0)
+            reasonCodes.push('non_test_reference');
+        if (tests.length > 0)
+            reasonCodes.push('test_reference');
+        const owners = ownersForReference(input.profile, symbol.file);
+        if (owners.length > 0) {
+            reasonCodes.push('owned_path');
+            score += 4;
+        }
+        if (approvalRequiredForReference(input.profile, symbol.file)) {
+            reasonCodes.push('approval_required_path');
+            score += 10;
+        }
+        return {
+            rank: 0,
+            score,
+            file: symbol.file,
+            name: symbol.name,
+            kind: symbol.kind,
+            referenceCount: refs.length,
+            nonTestReferenceCount: nonTest.length,
+            testReferenceCount: tests.length,
+            crossPackageReferenceCount: crossPackageCount,
+            reasonCodes: uniqueSorted(reasonCodes),
+            provenance: 'deterministic-ranking',
+        };
+    }).sort((a, b) => b.score - a.score ||
+        b.crossPackageReferenceCount - a.crossPackageReferenceCount ||
+        b.nonTestReferenceCount - a.nonTestReferenceCount ||
+        a.file.localeCompare(b.file) ||
+        a.name.localeCompare(b.name)).map((symbol, index) => ({ ...symbol, rank: index + 1 }));
+    const crossPackageReferenceCount = rankedReferences.filter((ref) => ref.reasonCodes.includes('cross_package_reference')).length;
+    const nonTestReferenceCount = rankedReferences.filter((ref) => !ref.isTestFile).length;
+    const sameFileReferences = rankedReferences.filter((ref) => ref.reasonCodes.includes('same_file_reference')).length;
+    const lowSignalReferences = rankedReferences.filter((ref) => ref.score < 35 ||
+        ref.reasonCodes.includes('test_reference') ||
+        ref.reasonCodes.includes('same_file_reference')).length;
+    return {
+        schemaVersion: 'neurcode.structural-digest.v1',
+        generatedAt: input.generatedAt,
+        provenance: 'deterministic-ranking',
+        modelUsed: false,
+        topSymbols: symbolRows.slice(0, 6),
+        topConsequences,
+        topReferences,
+        hidden: {
+            references: Math.max(0, input.references.length - topReferences.length),
+            testReferences: input.testReferences.length,
+            lowSignalReferences,
+            sameFileReferences,
+        },
+        summary: {
+            changedSymbolCount: input.changedSymbols.length,
+            referenceCount: input.references.length,
+            topConsequenceCount: topConsequences.length,
+            topReferenceCount: topReferences.length,
+            crossPackageReferenceCount,
+            nonTestReferenceCount,
+            testReferenceCount: input.testReferences.length,
+        },
+        limitations: [
+            'Digest ranking is deterministic and facts-only; it is not an LLM judgment.',
+            'Ranking reflects static reference shape, ownership metadata, path surfaces, and plan/path alignment only.',
+            'A high-ranked reference is a place to inspect; it is not a claim that behavior is broken.',
+            'No source text, diff hunks, patch content, or shell command bodies are stored.',
+        ],
+    };
+}
+function inferRemovedEffectTargets(targets, hunk) {
+    const touchedLines = new Set();
+    for (const line of normalizedHunkLines(hunk)) {
+        if (line.type !== 'context' && line.type !== 'added')
+            continue;
+        if (line.newLine !== null)
+            touchedLines.add(line.newLine);
+    }
+    return targets.filter((target) => target.lineStart !== null &&
+        target.lineEnd !== null &&
+        [...touchedLines].some((line) => line >= target.lineStart && line <= target.lineEnd));
+}
+function externalNonTestConsumers(consumers) {
+    return consumers.filter((consumer) => !consumer.isTestFile &&
+        !consumer.inChangedFile &&
+        !isPackageEntrypointFile(consumer.file));
+}
+function isPackageEntrypointFile(file) {
+    return /(^|\/)index\.(cjs|cts|js|jsx|mjs|mts|ts|tsx)$/.test(file);
+}
+function consumerReferencesForTarget(target, references) {
+    const byKey = new Map();
+    for (const ref of references) {
+        if (ref.targetFile !== target.file || ref.targetKind !== target.kind || ref.targetSymbol !== target.symbol)
+            continue;
+        const row = {
+            file: ref.referencingFile,
+            symbol: ref.referencingSymbol,
+            kind: ref.referencingKind,
+            line: ref.line,
+            isTestFile: ref.isTestFile,
+            inChangedFile: ref.inChangedFile,
+            provenance: 'typescript-compiler',
+        };
+        const key = row.file;
+        const existing = byKey.get(key);
+        if (!existing ||
+            (existing.symbol === null && row.symbol !== null) ||
+            (existing.symbol === row.symbol && row.line < existing.line)) {
+            byKey.set(key, row);
+        }
+    }
+    return [...byKey.values()].sort((a, b) => Number(a.isTestFile) - Number(b.isTestFile) ||
+        Number(a.inChangedFile) - Number(b.inChangedFile) ||
+        a.file.localeCompare(b.file) ||
+        a.line - b.line);
+}
+function buildEffectDeltas(input) {
+    const byFile = diffFileByPath(input.diffFiles);
+    const targetByKey = new Map(input.targets.map((target) => [symbolKey(target.file, target.kind, target.name), target]));
+    const added = new Map();
+    const removed = new Map();
+    const addCount = (map, target, effectCategory, calleeName, line) => {
+        const key = `${symbolKey(target.file, target.kind, target.name)}:${effectCategory}:${calleeName}`;
+        const current = map.get(key) ?? { target, effectCategory, calleeName, count: 0, lines: [] };
+        current.count += 1;
+        if (line !== null)
+            current.lines.push(line);
+        map.set(key, current);
+    };
+    for (const target of input.targets) {
+        const diffFile = byFile.get(target.file);
+        if (!diffFile || !target.declaration)
+            continue;
+        const addedLines = addedLineSet(diffFile);
+        const sourceFile = target.declaration.getSourceFile();
+        const visit = (node) => {
+            if (ts.isCallExpression(node)) {
+                const line = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+                if (addedLines.has(line)) {
+                    const calleeName = rightmostIdentifierText(node.expression);
+                    const effectCategory = effectCategoryForCalleeName(calleeName);
+                    if (calleeName && effectCategory)
+                        addCount(added, target, effectCategory, calleeName, line);
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        ts.forEachChild(target.declaration, visit);
+    }
+    const targetsByFile = new Map();
+    for (const target of input.targets) {
+        const bucket = targetsByFile.get(target.file) ?? [];
+        bucket.push(target);
+        targetsByFile.set(target.file, bucket);
+    }
+    for (const diffFile of input.diffFiles) {
+        const file = normalizeRepoPath(diffFile.path);
+        const fileTargets = targetsByFile.get(file) ?? [];
+        if (fileTargets.length === 0)
+            continue;
+        for (const hunk of diffFile.hunks ?? []) {
+            const removedTargets = inferRemovedEffectTargets(fileTargets, hunk);
+            if (removedTargets.length === 0)
+                continue;
+            for (const line of normalizedHunkLines(hunk)) {
+                if (line.type !== 'removed')
+                    continue;
+                for (const match of effectMatchesFromLineContent(line.content)) {
+                    for (const target of removedTargets)
+                        addCount(removed, target, match.effectCategory, match.calleeName, line.oldLine ?? target.lineStart);
+                }
+            }
+        }
+    }
+    const keys = uniqueSorted([...added.keys(), ...removed.keys()]);
+    const out = [];
+    for (const key of keys) {
+        const add = added.get(key);
+        const remove = removed.get(key);
+        const addCountValue = add?.count ?? 0;
+        const removeCountValue = remove?.count ?? 0;
+        if (addCountValue === removeCountValue)
+            continue;
+        const row = add ?? remove;
+        if (!row)
+            continue;
+        const baseRow = {
+            symbol: row.target.name,
+            file: row.target.file,
+            kind: row.target.kind,
+            line: row.lines.length ? Math.min(...row.lines) : row.target.lineStart,
+            effectCategory: row.effectCategory,
+            direction: addCountValue > removeCountValue ? 'added' : 'removed',
+            calleeName: row.calleeName,
+            count: Math.abs(addCountValue - removeCountValue),
+            provenance: 'effect-registry',
+        };
+        const consumers = consumerReferencesForTarget(baseRow, input.references);
+        out.push({
+            ...baseRow,
+            consumers,
+            externalConsumers: externalNonTestConsumers(consumers),
+        });
+    }
+    return out.sort((a, b) => a.file.localeCompare(b.file) ||
+        a.symbol.localeCompare(b.symbol) ||
+        a.effectCategory.localeCompare(b.effectCategory) ||
+        a.calleeName.localeCompare(b.calleeName));
+}
+function buildContractDeltas(projectRoot, diffFiles, targets) {
+    const byPath = diffFileByPath(diffFiles);
+    const oldShapesByFile = new Map();
+    const out = [];
+    for (const target of targets) {
+        const current = contractShapeFromTarget(target);
+        if (!current)
+            continue;
+        const diffFile = byPath.get(target.file);
+        if (!diffFile)
+            continue;
+        let oldShapes = oldShapesByFile.get(target.file);
+        if (!oldShapes) {
+            const oldText = oldFileTextFromDiff(projectRoot, diffFile);
+            oldShapes = oldText ? contractShapesFromSourceText(oldText, target.file) : new Map();
+            oldShapesByFile.set(target.file, oldShapes);
+        }
+        const previous = oldShapes.get(`${target.kind}#${target.name}`) ?? oldShapes.get(`${current.kind}#${current.name}`) ?? null;
+        const delta = compareContractShapes(target, current, previous);
+        if (delta)
+            out.push(delta);
+    }
+    return out.sort((a, b) => a.file.localeCompare(b.file) || a.symbol.localeCompare(b.symbol));
+}
+function attachContractConsumers(contractDeltas, references) {
+    return contractDeltas.map((delta) => {
+        const consumers = consumerReferencesForTarget(delta, references);
+        return {
+            ...delta,
+            consumers,
+            externalConsumers: externalNonTestConsumers(consumers),
+        };
+    });
+}
+function effectSeverityScore(effect) {
+    const external = effect.externalConsumers.length;
+    const nonTest = effect.consumers.filter((consumer) => !consumer.isTestFile).length;
+    const base = effect.direction === 'added' ? 24 : 18;
+    let score = base;
+    if (effect.effectCategory === 'session-evidence-write')
+        score += 45;
+    else if (effect.effectCategory === 'filesystem-write')
+        score += 38;
+    else if (effect.effectCategory === 'network-send')
+        score += 42;
+    else
+        score += 30;
+    score += Math.min(90, external * 28);
+    score += Math.min(18, nonTest * 3);
+    if (external === 0)
+        score -= 65;
+    if (isTestFile(effect.file))
+        score -= 70;
+    if (external === 0 && effect.consumers.some((consumer) => consumer.isTestFile))
+        score -= 15;
+    return score;
+}
+function contractSeverityScore(delta) {
+    const changes = new Set(delta.changes.map((change) => change.change));
+    let score = 20;
+    if (changes.has('param_removed') || changes.has('return_type_changed') || changes.has('kind_changed'))
+        score += 55;
+    if (changes.has('member_removed') || changes.has('param_type_changed'))
+        score += 45;
+    if (changes.has('param_added') || changes.has('member_added'))
+        score += 28;
+    if (changes.has('export_removed'))
+        score += 65;
+    if (changes.has('export_added'))
+        score -= 15;
+    const nonTest = delta.consumers.filter((consumer) => !consumer.isTestFile);
+    const outsideChanged = contractEscapingConsumers(delta);
+    score += Math.min(60, outsideChanged.length * 16);
+    score += Math.min(20, nonTest.length * 4);
+    if (outsideChanged.length === 0)
+        score -= 42;
+    if (nonTest.length === 0 && delta.consumers.length > 0)
+        score -= 20;
+    return score;
+}
+function contractHasEscapingShape(delta) {
+    const changes = new Set(delta.changes.map((change) => change.change));
+    return (changes.has('export_removed') ||
+        changes.has('param_removed') ||
+        changes.has('param_type_changed') ||
+        changes.has('return_type_changed') ||
+        changes.has('kind_changed') ||
+        changes.has('member_removed'));
+}
+function contractEscapingConsumers(delta) {
+    return contractHasEscapingShape(delta) ? delta.externalConsumers : [];
+}
+function effectReasonCodes(effect) {
+    const out = [];
+    out.push(effect.direction === 'added' ? 'effect_added' : 'effect_removed');
+    if (effect.effectCategory === 'filesystem-write')
+        out.push('filesystem_write');
+    if (effect.effectCategory === 'session-evidence-write')
+        out.push('session_evidence_write');
+    if (effect.effectCategory === 'network-send')
+        out.push('network_send');
+    if (effect.consumers.length > 0)
+        out.push('has_consumers');
+    if (effect.externalConsumers.length > 0)
+        out.push('external_consumers');
+    else
+        out.push('changed_file_only');
+    if (isTestFile(effect.file))
+        out.push('test_file_effect');
+    return out;
+}
+function contractReasonCodes(delta) {
+    const out = ['contract_changed'];
+    if (contractHasEscapingShape(delta)) {
+        out.push('breaking_contract_shape');
+    }
+    if (delta.consumers.length > 0)
+        out.push('has_consumers');
+    if (contractEscapingConsumers(delta).length > 0)
+        out.push('external_consumers');
+    else
+        out.push('changed_file_only');
+    if (delta.consumers.some((consumer) => !consumer.isTestFile))
+        out.push('non_test_consumers');
+    else if (delta.consumers.length > 0)
+        out.push('test_only_consumers');
+    return out;
+}
+function consumerSummaryReasonCodes(summary) {
+    const out = [];
+    if (summary.reachableProductionConsumerCount > 0)
+        out.push('reachable_production_consumers');
+    if (summary.changedProductionConsumerCount > 0)
+        out.push('changed_production_consumers');
+    if (summary.sensitiveConsumerCount > 0)
+        out.push('sensitive_consumers');
+    if (summary.approvalRequiredConsumerCount > 0)
+        out.push('approval_required_consumers');
+    if (summary.runtimeGovernanceConsumerCount > 0)
+        out.push('runtime_governance_consumers');
+    if (summary.highFanout)
+        out.push('high_fanout');
+    if (summary.architectureRelevant)
+        out.push('architecture_relevant');
+    return out;
+}
+function orderedConsequenceReasonCodes(values) {
+    return Array.from(new Set(values));
+}
+function buildConsumerSummary(input) {
+    const production = input.consumers.filter((consumer) => !consumer.isTestFile);
+    const tests = input.consumers.filter((consumer) => consumer.isTestFile);
+    const reachableProduction = production.filter((consumer) => consumer.file !== input.targetFile &&
+        !isPackageEntrypointFile(consumer.file));
+    const externalProduction = input.externalConsumers.filter((consumer) => !consumer.isTestFile);
+    const changedProduction = reachableProduction.filter((consumer) => consumer.inChangedFile);
+    const sensitive = input.consumers.filter((consumer) => sensitiveForReference(input.profile, consumer.file));
+    const approvalRequired = input.consumers.filter((consumer) => approvalRequiredForReference(input.profile, consumer.file));
+    const runtimeGovernance = input.consumers.filter(runtimeGovernanceConsumer);
+    const highFanout = externalProduction.length >= 3 || reachableProduction.length >= 5 || production.length >= 5;
+    const architectureRelevant = highFanout ||
+        reachableProduction.length >= 2 ||
+        sensitive.length > 0 ||
+        approvalRequired.length > 0 ||
+        runtimeGovernance.length > 0;
+    return {
+        productionConsumerCount: production.length,
+        testConsumerCount: tests.length,
+        reachableProductionConsumerCount: reachableProduction.length,
+        externalProductionConsumerCount: externalProduction.length,
+        changedProductionConsumerCount: changedProduction.length,
+        sensitiveConsumerCount: sensitive.length,
+        approvalRequiredConsumerCount: approvalRequired.length,
+        runtimeGovernanceConsumerCount: runtimeGovernance.length,
+        productionFiles: uniqueSorted(reachableProduction.map((consumer) => consumer.file)).slice(0, 12),
+        changedProductionFiles: uniqueSorted(changedProduction.map((consumer) => consumer.file)).slice(0, 12),
+        testFiles: uniqueSorted(tests.map((consumer) => consumer.file)).slice(0, 12),
+        sensitiveFiles: uniqueSorted(sensitive.map((consumer) => consumer.file)).slice(0, 12),
+        approvalRequiredFiles: uniqueSorted(approvalRequired.map((consumer) => consumer.file)).slice(0, 12),
+        runtimeGovernanceFiles: uniqueSorted(runtimeGovernance.map((consumer) => consumer.file)).slice(0, 12),
+        highFanout,
+        architectureRelevant,
+        provenance: 'typescript-compiler+governance-profile+path-classifier',
+    };
+}
+function externalConsumerSummary(consumers, max = 3) {
+    const files = uniqueSorted(consumers.map((consumer) => consumer.file));
+    if (files.length === 0)
+        return '';
+    const shown = files.slice(0, max).join(', ');
+    const hidden = files.length > max ? `; +${files.length - max} more external caller file(s)` : '';
+    return `${shown}${hidden}`;
+}
+function summarizeEffect(effect) {
+    const base = `${effect.file}#${effect.symbol} ${effect.direction} ${effect.effectCategory} (${effect.calleeName}${effect.line ? ` @ line ${effect.line}` : ''})`;
+    if (effect.externalConsumers.length === 0) {
+        return `${base}; no non-test callers outside this change`;
+    }
+    const callers = externalConsumerSummary(effect.externalConsumers);
+    return `${base}; reached by ${effect.externalConsumers.length} external non-test caller${effect.externalConsumers.length === 1 ? '' : 's'}: ${callers}`;
+}
+function summarizeContract(delta) {
+    const changes = delta.changes.slice(0, 4).map((change) => change.memberName ? `${change.change}:${change.memberName}` : change.change).join(', ');
+    const escapingConsumers = contractEscapingConsumers(delta);
+    if (escapingConsumers.length === 0) {
+        if (delta.externalConsumers.length > 0 && !contractHasEscapingShape(delta)) {
+            return `${delta.file}#${delta.symbol} contract changed: ${changes}; additive/non-breaking external consumers are not counted as escaping consequences`;
+        }
+        return `${delta.file}#${delta.symbol} contract changed: ${changes}; no non-test consumers outside this change`;
+    }
+    return `${delta.file}#${delta.symbol} contract changed: ${changes}; reached by ${escapingConsumers.length} external non-test consumer${escapingConsumers.length === 1 ? '' : 's'}: ${externalConsumerSummary(escapingConsumers)}`;
+}
+function buildTopFindings(input) {
+    const rows = [];
+    for (const effect of input.effectDeltas) {
+        const consumerSummary = buildConsumerSummary({
+            targetFile: effect.file,
+            consumers: effect.consumers,
+            externalConsumers: effect.externalConsumers,
+            profile: input.profile,
+        });
+        rows.push({
+            rank: 0,
+            score: effectSeverityScore(effect),
+            findingType: 'effect-delta',
+            file: effect.file,
+            symbol: effect.symbol,
+            summary: summarizeEffect(effect),
+            consumerCount: effect.consumers.length,
+            nonTestConsumerCount: effect.consumers.filter((consumer) => !consumer.isTestFile).length,
+            testConsumerCount: effect.consumers.filter((consumer) => consumer.isTestFile).length,
+            externalConsumerCount: effect.externalConsumers.length,
+            externalConsumerFiles: uniqueSorted(effect.externalConsumers.map((consumer) => consumer.file)),
+            consumerSummary,
+            reasonCodes: orderedConsequenceReasonCodes([
+                ...effectReasonCodes(effect),
+                ...consumerSummaryReasonCodes(consumerSummary),
+            ]),
+            provenance: 'deterministic-ranking',
+        });
+    }
+    for (const delta of input.contractDeltas) {
+        const tests = delta.consumers.filter((consumer) => consumer.isTestFile);
+        const escapingConsumers = contractEscapingConsumers(delta);
+        const consumerSummary = buildConsumerSummary({
+            targetFile: delta.file,
+            consumers: delta.consumers,
+            externalConsumers: escapingConsumers,
+            profile: input.profile,
+        });
+        rows.push({
+            rank: 0,
+            score: contractSeverityScore(delta),
+            findingType: 'contract-delta',
+            file: delta.file,
+            symbol: delta.symbol,
+            summary: summarizeContract(delta),
+            consumerCount: delta.consumers.length,
+            nonTestConsumerCount: delta.consumers.filter((consumer) => !consumer.isTestFile).length,
+            testConsumerCount: tests.length,
+            externalConsumerCount: escapingConsumers.length,
+            externalConsumerFiles: uniqueSorted(escapingConsumers.map((consumer) => consumer.file)),
+            consumerSummary,
+            reasonCodes: orderedConsequenceReasonCodes([
+                ...contractReasonCodes(delta),
+                ...consumerSummaryReasonCodes(consumerSummary),
+            ]),
+            provenance: 'deterministic-ranking',
+        });
+    }
+    for (const projection of input.inheritorProjections) {
+        const consumer = {
+            file: projection.inheritorFile,
+            symbol: projection.inheritorSymbol,
+            kind: null,
+            line: 0,
+            isTestFile: projection.isTestFile,
+            inChangedFile: false,
+            provenance: 'typescript-compiler',
+        };
+        const consumerSummary = buildConsumerSummary({
+            targetFile: projection.baseFile,
+            consumers: [consumer],
+            externalConsumers: projection.isTestFile ? [] : [consumer],
+            profile: input.profile,
+        });
+        const projectionReasonCodes = projection.isTestFile
+            ? ['inheritor_affected', 'test_only_consumers']
+            : ['inheritor_affected', 'non_test_consumers'];
+        rows.push({
+            rank: 0,
+            score: projection.isTestFile ? 15 : 45,
+            findingType: 'inheritor-projection',
+            file: projection.baseFile,
+            symbol: projection.baseSymbol,
+            summary: `${projection.baseFile}#${projection.baseSymbol} ${projection.relationship} -> ${projection.inheritorFile}#${projection.inheritorSymbol}`,
+            consumerCount: 1,
+            nonTestConsumerCount: projection.isTestFile ? 0 : 1,
+            testConsumerCount: projection.isTestFile ? 1 : 0,
+            externalConsumerCount: projection.isTestFile ? 0 : 1,
+            externalConsumerFiles: projection.isTestFile ? [] : [projection.inheritorFile],
+            consumerSummary,
+            reasonCodes: orderedConsequenceReasonCodes([
+                ...projectionReasonCodes,
+                ...consumerSummaryReasonCodes(consumerSummary),
+            ]),
+            provenance: 'deterministic-ranking',
+        });
+    }
+    return rows.sort((a, b) => b.score - a.score ||
+        b.nonTestConsumerCount - a.nonTestConsumerCount ||
+        a.file.localeCompare(b.file) ||
+        a.symbol.localeCompare(b.symbol) ||
+        a.summary.localeCompare(b.summary)).map((row, index) => ({ ...row, rank: index + 1 }));
+}
+function impactSummary(input) {
+    const parts = [];
+    if (input.productionFiles.length > 0) {
+        parts.push(`${input.productionFiles.length} production consumer file${input.productionFiles.length === 1 ? '' : 's'}`);
+    }
+    if (input.changedProductionFiles.length > 0) {
+        parts.push(`${input.changedProductionFiles.length} consumer file${input.changedProductionFiles.length === 1 ? '' : 's'} also changed`);
+    }
+    if (input.testFiles.length > 0) {
+        parts.push(`${input.testFiles.length} test consumer file${input.testFiles.length === 1 ? '' : 's'}`);
+    }
+    if (input.sensitiveFiles.length > 0) {
+        parts.push(`${input.sensitiveFiles.length} sensitive consumer${input.sensitiveFiles.length === 1 ? '' : 's'}`);
+    }
+    if (input.approvalRequiredFiles.length > 0) {
+        parts.push(`${input.approvalRequiredFiles.length} approval-required consumer${input.approvalRequiredFiles.length === 1 ? '' : 's'}`);
+    }
+    if (input.runtimeGovernanceFiles.length > 0) {
+        parts.push(`${input.runtimeGovernanceFiles.length} runtime/governance consumer${input.runtimeGovernanceFiles.length === 1 ? '' : 's'}`);
+    }
+    const typeText = input.findingTypes.join('+');
+    return `${input.file}#${input.symbol} has ${parts.length > 0 ? parts.join(', ') : 'no external consumer files'} (${typeText})`;
+}
+function buildTopImpacts(topFindings) {
+    const bySymbol = new Map();
+    for (const finding of topFindings) {
+        const key = `${finding.file}\0${finding.symbol}`;
+        const bucket = bySymbol.get(key) ?? [];
+        bucket.push(finding);
+        bySymbol.set(key, bucket);
+    }
+    const groups = [...bySymbol.values()].map((findings) => {
+        const first = findings
+            .slice()
+            .sort((a, b) => a.file.localeCompare(b.file) ||
+            a.symbol.localeCompare(b.symbol) ||
+            a.rank - b.rank)[0];
+        const findingTypes = uniqueSorted(findings.map((finding) => finding.findingType));
+        const productionFiles = uniqueSorted(findings.flatMap((finding) => finding.consumerSummary.productionFiles));
+        const changedProductionFiles = uniqueSorted(findings.flatMap((finding) => finding.consumerSummary.changedProductionFiles));
+        const testFiles = uniqueSorted(findings.flatMap((finding) => finding.consumerSummary.testFiles));
+        const sensitiveFiles = uniqueSorted(findings.flatMap((finding) => finding.consumerSummary.sensitiveFiles));
+        const approvalRequiredFiles = uniqueSorted(findings.flatMap((finding) => finding.consumerSummary.approvalRequiredFiles));
+        const runtimeGovernanceFiles = uniqueSorted(findings.flatMap((finding) => finding.consumerSummary.runtimeGovernanceFiles));
+        const reasonCodes = orderedConsequenceReasonCodes(findings.flatMap((finding) => finding.reasonCodes));
+        const reachableProductionConsumerCount = productionFiles.length;
+        const externalProductionConsumerCount = Math.max(0, ...findings.map((finding) => finding.consumerSummary.externalProductionConsumerCount));
+        const changedProductionConsumerCount = changedProductionFiles.length;
+        const sensitiveConsumerCount = sensitiveFiles.length;
+        const approvalRequiredConsumerCount = approvalRequiredFiles.length;
+        const runtimeGovernanceConsumerCount = runtimeGovernanceFiles.length;
+        const productionConsumerCount = Math.max(productionFiles.length, ...findings.map((finding) => finding.consumerSummary.productionConsumerCount));
+        const testConsumerCount = Math.max(testFiles.length, ...findings.map((finding) => finding.consumerSummary.testConsumerCount));
+        const highFanout = findings.some((finding) => finding.consumerSummary.highFanout) || productionFiles.length >= 5 || externalProductionConsumerCount >= 3;
+        const architectureRelevant = highFanout ||
+            sensitiveConsumerCount > 0 ||
+            approvalRequiredConsumerCount > 0 ||
+            runtimeGovernanceConsumerCount > 0 ||
+            findings.some((finding) => finding.consumerSummary.architectureRelevant);
+        const baseScore = Math.max(...findings.map((finding) => finding.score));
+        const score = baseScore +
+            Math.min(60, externalProductionConsumerCount * 12) +
+            Math.min(40, sensitiveConsumerCount * 14) +
+            Math.min(40, approvalRequiredConsumerCount * 16) +
+            Math.min(40, runtimeGovernanceConsumerCount * 14) +
+            (highFanout ? 18 : 0) +
+            (architectureRelevant ? 10 : 0) +
+            (findingTypes.length > 1 ? 8 : 0);
+        return {
+            rank: 0,
+            score,
+            file: first.file,
+            symbol: first.symbol,
+            summary: impactSummary({
+                file: first.file,
+                symbol: first.symbol,
+                findingTypes,
+                productionFiles,
+                changedProductionFiles,
+                testFiles,
+                sensitiveFiles,
+                approvalRequiredFiles,
+                runtimeGovernanceFiles,
+            }),
+            findingTypes,
+            findingRanks: findings.map((finding) => finding.rank).sort((a, b) => a - b),
+            findingCount: findings.length,
+            productionConsumerCount,
+            testConsumerCount,
+            reachableProductionConsumerCount,
+            externalProductionConsumerCount,
+            changedProductionConsumerCount,
+            sensitiveConsumerCount,
+            approvalRequiredConsumerCount,
+            runtimeGovernanceConsumerCount,
+            productionFiles: productionFiles.slice(0, 12),
+            changedProductionFiles: changedProductionFiles.slice(0, 12),
+            testFiles: testFiles.slice(0, 12),
+            sensitiveFiles: sensitiveFiles.slice(0, 12),
+            approvalRequiredFiles: approvalRequiredFiles.slice(0, 12),
+            runtimeGovernanceFiles: runtimeGovernanceFiles.slice(0, 12),
+            highFanout,
+            architectureRelevant,
+            reasonCodes,
+            provenance: 'deterministic-impact-grouping',
+        };
+    });
+    return groups.sort((a, b) => b.score - a.score ||
+        b.externalProductionConsumerCount - a.externalProductionConsumerCount ||
+        b.runtimeGovernanceConsumerCount - a.runtimeGovernanceConsumerCount ||
+        b.sensitiveConsumerCount - a.sensitiveConsumerCount ||
+        b.approvalRequiredConsumerCount - a.approvalRequiredConsumerCount ||
+        a.file.localeCompare(b.file) ||
+        a.symbol.localeCompare(b.symbol)).map((group, index) => ({ ...group, rank: index + 1 }));
+}
+function consequenceHeadline(changedSymbolCount, topFindings) {
+    const escaping = topFindings.filter((finding) => finding.externalConsumerCount > 0);
+    const highest = escaping
+        .sort((a, b) => b.externalConsumerCount - a.externalConsumerCount ||
+        b.score - a.score ||
+        a.file.localeCompare(b.file) ||
+        a.symbol.localeCompare(b.symbol))[0] ?? null;
+    if (!highest) {
+        return {
+            escapingConsequenceCount: 0,
+            highestExternalConsumerCount: 0,
+            headline: `${changedSymbolCount} symbols changed; 0 escaping TypeScript-static consequences found (effects checked: allowlisted filesystem/network/session evidence; SQL, dependency injection, dynamic dispatch, route wiring, and cross-language behavior not analyzed).`,
+        };
+    }
+    return {
+        escapingConsequenceCount: escaping.length,
+        highestExternalConsumerCount: highest.externalConsumerCount,
+        headline: `${changedSymbolCount} symbols changed; ${escaping.length} consequence${escaping.length === 1 ? '' : 's'} ${escaping.length === 1 ? 'reaches' : 'reach'} non-test callers outside this change; highest-fanout: ${highest.file}#${highest.symbol} (${highest.externalConsumerCount} external caller${highest.externalConsumerCount === 1 ? '' : 's'}).`,
+    };
+}
+function heritageRelationship(token) {
+    if (token.token === ts.SyntaxKind.ExtendsKeyword)
+        return 'extends';
+    return 'implements';
+}
+function buildInheritorProjections(input) {
+    const deltaKeys = new Set(input.contractDeltas.map((delta) => symbolKey(delta.file, delta.kind, delta.symbol)));
+    const targetByResolvedSymbol = new Map();
+    for (const target of input.targets) {
+        if (!deltaKeys.has(symbolKey(target.file, target.kind, target.name)))
+            continue;
+        if (target.kind !== 'interface' && target.kind !== 'class' && target.kind !== 'type')
+            continue;
+        if (target.symbol) {
+            targetByResolvedSymbol.set(target.symbol, target);
+            const aliased = resolveAlias(input.checker, target.symbol);
+            if (aliased)
+                targetByResolvedSymbol.set(aliased, target);
+        }
+    }
+    if (targetByResolvedSymbol.size === 0)
+        return [];
+    const byKey = new Map();
+    for (const sourceFile of input.program.getSourceFiles()) {
+        if (sourceFile.isDeclarationFile || sourceFile.fileName.includes('node_modules'))
+            continue;
+        const file = repoRel(input.projectRoot, sourceFile.fileName);
+        if (input.changedFileSet.has(file))
+            continue;
+        const visit = (node) => {
+            if ((ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node)) && node.name && node.heritageClauses) {
+                for (const clause of node.heritageClauses) {
+                    for (const type of clause.types) {
+                        const symbol = resolveAlias(input.checker, input.checker.getSymbolAtLocation(type.expression));
+                        const target = symbol ? targetByResolvedSymbol.get(symbol) : undefined;
+                        if (!target)
+                            continue;
+                        const relationship = ts.isInterfaceDeclaration(node) && clause.token === ts.SyntaxKind.ExtendsKeyword
+                            ? 'type-extends'
+                            : heritageRelationship(clause);
+                        const row = {
+                            baseSymbol: target.name,
+                            baseFile: target.file,
+                            inheritorSymbol: node.name.text,
+                            inheritorFile: file,
+                            relationship,
+                            isTestFile: isTestFile(file),
+                            provenance: 'inheritance-projection',
+                        };
+                        byKey.set(`${row.baseFile}#${row.baseSymbol}<-${row.inheritorFile}#${row.inheritorSymbol}`, row);
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        ts.forEachChild(sourceFile, visit);
+    }
+    return [...byKey.values()].sort((a, b) => a.baseFile.localeCompare(b.baseFile) ||
+        a.baseSymbol.localeCompare(b.baseSymbol) ||
+        a.inheritorFile.localeCompare(b.inheritorFile) ||
+        a.inheritorSymbol.localeCompare(b.inheritorSymbol));
+}
+function buildConsequenceUnderstanding(input) {
+    if (input.targets.length === 0) {
+        return emptyConsequenceUnderstanding(input.generatedAt, 'no changed symbols available for consequence analysis');
+    }
+    if (input.suppressedArtifacts.length > 0 && input.targets.length === 0) {
+        return emptyConsequenceUnderstanding(input.generatedAt, 'no analyzable symbols after generated-artifact suppression');
+    }
+    const effectDeltas = buildEffectDeltas({
+        diffFiles: input.diffFiles,
+        targets: input.targets,
+        references: input.references,
+    });
+    const contractDeltas = attachContractConsumers(buildContractDeltas(input.projectRoot, input.diffFiles, input.targets), input.references);
+    const inheritorProjections = buildInheritorProjections({
+        program: input.program,
+        checker: input.checker,
+        projectRoot: input.projectRoot,
+        targets: input.targets,
+        contractDeltas,
+        changedFileSet: input.changedFileSet,
+    });
+    const topFindings = buildTopFindings({
+        effectDeltas,
+        contractDeltas,
+        inheritorProjections,
+        profile: input.profile,
+    });
+    const topImpacts = buildTopImpacts(topFindings);
+    const headline = consequenceHeadline(input.targets.length, topFindings);
+    const core = {
+        schemaVersion: exports.CONSEQUENCE_UNDERSTANDING_SCHEMA_VERSION,
+        generatedAt: input.generatedAt,
+        analyzed: true,
+        reason: null,
+        confidence: 'deterministic-static',
+        modelUsed: false,
+        effectDeltas,
+        contractDeltas,
+        inheritorProjections,
+        topFindings,
+        topImpacts,
+        summary: {
+            effectDeltaCount: effectDeltas.length,
+            contractDeltaCount: contractDeltas.length,
+            inheritorProjectionCount: inheritorProjections.length,
+            topFindingCount: topFindings.length,
+            topImpactCount: topImpacts.length,
+            escapingConsequenceCount: headline.escapingConsequenceCount,
+            highestExternalConsumerCount: headline.highestExternalConsumerCount,
+            headline: headline.headline,
+        },
+        limitations: [
+            'Known-effect detection is allowlist-bounded; effects via unrecognized wrappers, dynamic dispatch, or dependency injection are not claimed.',
+            'Contract detection is TypeScript/JavaScript static analysis only.',
+            'Contract consumers are static symbol references; HTTP, serialization, and dynamic runtime consumers are not proven.',
+            'Inheritor projection only follows static TypeScript extends/implements relationships outside changed files.',
+            'Generated artifacts are skipped entirely and reported through suppressedArtifacts.',
+            'No LLM or probabilistic judgment is used in this artifact.',
+            'No source text, diff hunks, patch content, or shell command bodies are stored.',
+        ],
+        factProvenance: {
+            effectDeltas: 'effect-registry',
+            contractDeltas: 'typescript-checker',
+            inheritorProjections: 'inheritance-projection',
+            topFindings: 'deterministic-ranking',
+            topImpacts: 'deterministic-impact-grouping',
+        },
+    };
+    return { ...core, artifactHash: hash(consequenceHashInput(core)) };
+}
+function structuralUnderstandingPath(projectRoot, sessionId) {
+    return (0, path_1.join)(projectRoot, '.neurcode', 'understanding', `${sessionId}.json`);
+}
+function buildStructuralUnderstanding(projectRoot, diffFiles, options = {}) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const changedFiles = diffFiles.map((file) => normalizeRepoPath(file.path));
+    const profile = options.profile ?? profileFromSession(options.session);
+    const suppressedArtifacts = classifyGeneratedArtifacts(projectRoot, changedFiles);
+    const suppressedArtifactPaths = new Set(suppressedArtifacts.map((item) => item.path));
+    const tsChanged = changedFiles.filter((file) => TS_LIKE.test(file) &&
+        !/\.d\.ts$/i.test(file) &&
+        !suppressedArtifactPaths.has(file));
+    if (tsChanged.length === 0) {
+        const reason = suppressedArtifacts.length > 0
+            ? 'no analyzable TypeScript/JavaScript files after generated-artifact suppression'
+            : 'no TypeScript/JavaScript files in change set';
+        const artifact = none(projectRoot, diffFiles, reason, generatedAt, suppressedArtifacts);
+        artifact.planAlignment = buildPlanAlignment(options.session ?? null, changedFiles, []);
+        artifact.boundaryImpact = buildBoundaryImpact(profile, changedFiles);
+        artifact.artifactHash = hash(artifactHashInput(artifact));
+        return artifact;
+    }
+    const maxFiles = options.maxProgramFiles ?? 6000;
+    const timeBudgetMs = options.timeBudgetMs ?? 12000;
+    const started = Date.now();
+    const roots = scopeRoots(projectRoot, tsChanged);
+    if (roots.length === 0)
+        return none(projectRoot, diffFiles, 'no resolvable TypeScript scope roots', generatedAt, suppressedArtifacts);
+    const sourceFiles = new Set();
+    for (const root of roots) {
+        const gathered = [];
+        gatherSourceFiles(root, gathered, maxFiles + 1);
+        for (const file of gathered)
+            sourceFiles.add(file);
+        if (sourceFiles.size > maxFiles)
+            return none(projectRoot, diffFiles, `program too large (>${maxFiles} files)`, generatedAt, suppressedArtifacts);
+    }
+    for (const file of tsChanged) {
+        const abs = (0, path_1.join)(projectRoot, file);
+        if ((0, fs_1.existsSync)(abs) && (0, fs_1.statSync)(abs).isFile())
+            sourceFiles.add(abs);
+    }
+    // ── Cross-package recall ──────────────────────────────────────────────────────
+    // A program scoped to the changed package alone can never see callers that live
+    // in OTHER workspace packages. Add the direct importer files of every package that
+    // (transitively) depends on the changed package(s), and map workspace imports to
+    // source so those callers resolve to the same declaration we changed — not the
+    // built .d.ts (which would be a different symbol and silently match nothing).
+    const workspace = loadWorkspacePackages(projectRoot);
+    const changedPackages = changedWorkspacePackages(workspace, tsChanged);
+    const changedPackageNames = changedPackages.map((pkg) => pkg.name);
+    const reverseDepConsumerNames = new Set(changedPackageNames.length
+        ? reverseDepConsumers(workspace, new Set(changedPackageNames)).map((pkg) => pkg.name)
+        : []);
+    const consumerPackages = [];
+    let directImporterFilesAdded = 0;
+    for (const consumer of changedPackageNames.length
+        ? workspace.filter((pkg) => !changedPackageNames.includes(pkg.name))
+        : []) {
+        const before = sourceFiles.size;
+        const gathered = [];
+        gatherDirectImporterFiles(consumer, changedPackageNames, gathered, maxFiles + 1);
+        for (const file of gathered)
+            sourceFiles.add(file);
+        const added = sourceFiles.size - before;
+        directImporterFilesAdded += added;
+        if (added > 0 || reverseDepConsumerNames.has(consumer.name))
+            consumerPackages.push(consumer);
+        if (sourceFiles.size > maxFiles)
+            break;
+    }
+    const workspacePaths = buildWorkspacePaths(workspace);
+    const crossPackageResolved = changedPackageNames.length > 0 && Object.keys(workspacePaths).length > 0;
+    const files = [...sourceFiles];
+    if (files.length === 0)
+        return none(projectRoot, diffFiles, 'no TypeScript source files gathered', generatedAt, suppressedArtifacts);
+    const compilerOptions = {
+        target: ts.ScriptTarget.ES2020,
+        module: ts.ModuleKind.CommonJS,
+        moduleResolution: ts.ModuleResolutionKind.Node10,
+        allowJs: true,
+        noEmit: true,
+        skipLibCheck: true,
+        noResolve: false,
+        ...(crossPackageResolved ? { baseUrl: projectRoot, paths: workspacePaths } : {}),
+    };
+    const program = ts.createProgram(files, compilerOptions);
+    const checker = program.getTypeChecker();
+    if (Date.now() - started > timeBudgetMs)
+        return none(projectRoot, diffFiles, 'time budget exceeded during program build', generatedAt);
+    const declarationsByFile = new Map();
+    for (const sourceFile of program.getSourceFiles()) {
+        if (sourceFile.isDeclarationFile || sourceFile.fileName.includes('node_modules'))
+            continue;
+        declarationsByFile.set(repoRel(projectRoot, sourceFile.fileName), collectDeclarations(sourceFile, checker, projectRoot));
+    }
+    const targets = new Map();
+    const targetBySymbol = new Map();
+    for (const diffFile of diffFiles) {
+        const file = normalizeRepoPath(diffFile.path);
+        if (suppressedArtifactPaths.has(file))
+            continue;
+        if (!TS_LIKE.test(file) || /\.d\.ts$/i.test(file))
+            continue;
+        const declarations = declarationsByFile.get(file) ?? [];
+        for (const line of changedNewLines(diffFile)) {
+            const decl = smallestContaining(declarations, line);
+            if (!decl)
+                continue;
+            const key = symbolKey(decl.file, decl.kind, decl.name);
+            const existing = targets.get(key);
+            const action = diffFile.changeType === 'add' ? 'add' : 'modify';
+            const candidate = {
+                name: decl.name,
+                kind: decl.kind,
+                file: decl.file,
+                lineStart: decl.startLine,
+                lineEnd: decl.endLine,
+                action,
+                symbol: decl.symbol,
+                declaration: decl.node,
+            };
+            if (!existing || existing.action !== 'add')
+                targets.set(key, candidate);
+        }
+    }
+    for (const target of targets.values()) {
+        if (target.symbol) {
+            targetBySymbol.set(target.symbol, target);
+            const aliased = resolveAlias(checker, target.symbol);
+            if (aliased)
+                targetBySymbol.set(aliased, target);
+        }
+    }
+    const changedSymbols = [...targets.values()]
+        .map((target) => ({
+        name: target.name,
+        kind: target.kind,
+        file: target.file,
+        action: target.action,
+        lineStart: target.lineStart,
+        lineEnd: target.lineEnd,
+        provenance: 'typescript-compiler',
+    }))
+        .sort((a, b) => a.file.localeCompare(b.file) || a.lineStart - b.lineStart || a.name.localeCompare(b.name));
+    const referenceMap = new Map();
+    const changedFileSet = new Set(tsChanged);
+    const importExportGraph = buildImportExportTargetGraph({
+        program,
+        projectRoot,
+        compilerOptions,
+        targets: [...targets.values()],
+    });
+    let budgetExceeded = false;
+    for (const sourceFile of program.getSourceFiles()) {
+        if (sourceFile.isDeclarationFile || sourceFile.fileName.includes('node_modules'))
+            continue;
+        if (Date.now() - started > timeBudgetMs) {
+            budgetExceeded = true;
+            break;
+        }
+        const sourceRel = repoRel(projectRoot, sourceFile.fileName);
+        const sourceDeclarations = declarationsByFile.get(sourceRel) ?? [];
+        const visit = (node) => {
+            if (ts.isIdentifier(node)) {
+                const symbol = resolveAlias(checker, checker.getSymbolAtLocation(node));
+                const checkerTarget = symbol ? targetBySymbol.get(symbol) : undefined;
+                const graphTarget = importExportGraphTargetForIdentifier(node, sourceRel, importExportGraph);
+                const target = checkerTarget ?? graphTarget;
+                if (target && node !== target.declaration && node.parent !== target.declaration) {
+                    const line = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+                    const enclosing = smallestContaining(sourceDeclarations, line);
+                    const ref = {
+                        targetSymbol: target.name,
+                        targetKind: target.kind,
+                        targetFile: target.file,
+                        referencingFile: sourceRel,
+                        referencingSymbol: enclosing?.name ?? null,
+                        referencingKind: enclosing?.kind ?? null,
+                        line,
+                        isTestFile: isTestFile(sourceRel),
+                        inChangedFile: changedFileSet.has(sourceRel),
+                        provenance: checkerTarget ? 'typescript-compiler' : 'import-export-graph',
+                    };
+                    referenceMap.set(`${ref.targetFile}#${ref.targetKind}#${ref.targetSymbol}:${ref.referencingFile}:${ref.line}:${ref.referencingSymbol ?? ''}`, ref);
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        ts.forEachChild(sourceFile, visit);
+    }
+    const references = [...referenceMap.values()]
+        .filter((ref) => !(ref.inChangedFile && ref.referencingFile === ref.targetFile))
+        .sort((a, b) => a.targetFile.localeCompare(b.targetFile) ||
+        a.targetSymbol.localeCompare(b.targetSymbol) ||
+        a.referencingFile.localeCompare(b.referencingFile) ||
+        a.line - b.line);
+    const testReferences = references.filter((ref) => ref.isTestFile);
+    const planAlignment = buildPlanAlignment(options.session ?? null, changedFiles, changedSymbols);
+    const boundaryImpact = buildBoundaryImpact(profile, changedFiles);
+    const digest = buildStructuralDigest({
+        generatedAt,
+        changedSymbols,
+        references,
+        testReferences,
+        workspace,
+        changedPackageNames,
+        changedFiles,
+        profile,
+        planAlignment,
+    });
+    const consequenceUnderstanding = buildConsequenceUnderstanding({
+        projectRoot,
+        generatedAt,
+        diffFiles,
+        targets: [...targets.values()],
+        references,
+        program,
+        checker,
+        changedFileSet,
+        suppressedArtifacts,
+        profile,
+    });
+    const core = {
+        schemaVersion: exports.STRUCTURAL_UNDERSTANDING_SCHEMA_VERSION,
+        generatedAt,
+        repoRootHash: hash(projectRoot),
+        privacy: privacyBlock(),
+        analysis: {
+            language: 'typescript',
+            analyzed: true,
+            reason: null,
+            confidence: 'deterministic-static',
+            filesAnalyzed: files.length,
+            changedFileCount: changedFiles.length,
+            changedSymbolCount: changedSymbols.length,
+            referenceCount: references.length,
+            testReferenceCount: testReferences.length,
+            crossPackage: {
+                changedPackages: changedPackageNames,
+                consumerPackagesScanned: consumerPackages.map((pkg) => pkg.name),
+                directImporterFilesAdded,
+                resolvedToSource: crossPackageResolved,
+            },
+        },
+        changedFiles: changedFileFacts(diffFiles),
+        changedSymbols,
+        references,
+        importEdgesChanged: importEdgeFacts(diffFiles, suppressedArtifacts),
+        suppressedArtifacts,
+        testReferences,
+        digest,
+        consequenceUnderstanding,
+        planAlignment,
+        boundaryImpact,
+        limitations: [
+            ...commonLimitations(),
+            ...(changedPackageNames.length
+                ? [
+                    `Cross-package references resolved for direct importers of [${changedPackageNames.join(', ')}] across ${consumerPackages.length} consumer package(s). Transitive re-export chains and consumers that do not import the changed package directly may be under-counted.`,
+                ]
+                : []),
+            ...(budgetExceeded ? ['Analysis stopped at the time budget; reference recall may be partial.'] : []),
+            ...(suppressedArtifacts.length
+                ? [
+                    `${suppressedArtifacts.length} generated artifact(s) were excluded from symbol/reference analysis. Suppression is path/fingerprint based and visible in suppressedArtifacts.`,
+                ]
+                : []),
+        ],
+        factProvenance: provenanceMap(),
+    };
+    return {
+        ...core,
+        artifactHash: hash(artifactHashInput(core)),
+    };
+}
+function writeStructuralUnderstanding(projectRoot, sessionId, artifact) {
+    const path = structuralUnderstandingPath(projectRoot, sessionId);
+    (0, fs_1.mkdirSync)((0, path_1.join)(projectRoot, '.neurcode', 'understanding'), { recursive: true });
+    (0, fs_1.writeFileSync)(path, JSON.stringify(artifact, null, 2) + '\n', 'utf8');
+    return path;
+}
+function readStructuralUnderstanding(projectRoot, sessionId) {
+    const path = structuralUnderstandingPath(projectRoot, sessionId);
+    if (!(0, fs_1.existsSync)(path))
+        return null;
+    try {
+        return JSON.parse((0, fs_1.readFileSync)(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=structural-understanding.js.map