gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/dist/core/ingestion/pipeline-phases/spring-config.js

@@ -0,0 +1,433 @@
+/**
+ * Phase: springConfig
+ *
+ * Adds key-only nodes for statically readable Spring
+ * `application*.properties` / `application*.yml` / `application*.yaml` files.
+ * Language-specific ScopeResolver hooks attach consumers later. Configuration
+ * values are deliberately never copied into the graph because they may contain
+ * credentials and key identity is sufficient for impact analysis.
+ *
+ * @deps    structure
+ * @reads   Spring application configuration files
+ * @writes  Property nodes and DEFINES edges
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { SPRING_CONFIG_DESCRIPTION } from '../frameworks/spring/config-bindings.js';
+import { generateId } from '../../../lib/utils.js';
+import { getPhaseOutput } from './types.js';
+const require = createRequire(import.meta.url);
+const yaml = require('js-yaml');
+// js-yaml 5 dropped DEFAULT_SCHEMA; CORE plus these tags is what it used to be, so
+// explicitly tagged values keep parsing instead of throwing (an unknown tag aborts
+// the whole file). None of them can execute code.
+const SPRING_YAML_SCHEMA = yaml.CORE_SCHEMA.withTags(yaml.mergeTag, yaml.timestampTag, yaml.binaryTag, yaml.omapTag, yaml.pairsTag, yaml.setTag);
+const MAX_CONFIG_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_YAML_TRAVERSAL_DEPTH = 128;
+const MAX_YAML_TRAVERSAL_NODES = 100_000;
+/** Match only Spring Boot's conventional application config file names. */
+export function classifySpringConfigFile(filePath) {
+    const base = path.posix.basename(filePath.replaceAll('\\', '/'));
+    const match = /^application(?:-([^.]+))?\.(properties|ya?ml)$/i.exec(base);
+    if (match === null)
+        return null;
+    return {
+        filePath,
+        ...(match[1] ? { profile: match[1] } : {}),
+        format: match[2].toLowerCase() === 'properties' ? 'properties' : 'yaml',
+    };
+}
+function unescapePropertyKey(raw) {
+    return raw
+        .replace(/\\u([0-9a-fA-F]{4})/g, (_match, hex) => String.fromCharCode(Number.parseInt(hex, 16)))
+        .replace(/\\([:=#!\\ ])/g, '$1');
+}
+function logicalPropertiesLines(content) {
+    const physical = content.split(/\r?\n/);
+    const logical = [];
+    let current = '';
+    let startLine = 1;
+    for (let index = 0; index < physical.length; index++) {
+        const line = physical[index];
+        if (current.length === 0)
+            startLine = index + 1;
+        current += current.length === 0 ? line : line.trimStart();
+        let trailingBackslashes = 0;
+        for (let cursor = current.length - 1; cursor >= 0 && current[cursor] === '\\'; cursor--) {
+            trailingBackslashes++;
+        }
+        if (trailingBackslashes % 2 === 1) {
+            current = current.slice(0, -1);
+            continue;
+        }
+        logical.push({ text: current, line: startLine });
+        current = '';
+    }
+    if (current.length > 0)
+        logical.push({ text: current, line: startLine });
+    return logical;
+}
+/** Parse `.properties` keys without retaining their values. */
+export function parseSpringProperties(content, filePath, profile) {
+    const keys = [];
+    const seen = new Set();
+    for (const logical of logicalPropertiesLines(content)) {
+        const trimmed = logical.text.trimStart();
+        if (trimmed.length === 0 || trimmed.startsWith('#') || trimmed.startsWith('!'))
+            continue;
+        let separator = -1;
+        let escaped = false;
+        for (let index = 0; index < trimmed.length; index++) {
+            const char = trimmed[index];
+            if (!escaped && (char === '=' || char === ':' || /\s/.test(char))) {
+                separator = index;
+                break;
+            }
+            escaped = !escaped && char === '\\';
+            if (char !== '\\')
+                escaped = false;
+        }
+        const rawKey = (separator === -1 ? trimmed : trimmed.slice(0, separator)).trim();
+        const key = unescapePropertyKey(rawKey);
+        if (key.length === 0 || seen.has(key))
+            continue;
+        seen.add(key);
+        keys.push({
+            key,
+            filePath,
+            line: logical.line,
+            ...(profile ? { profile } : {}),
+            format: 'properties',
+        });
+    }
+    return keys;
+}
+function consumeYamlTraversalBudget(state, depth) {
+    if (depth > MAX_YAML_TRAVERSAL_DEPTH) {
+        throw new Error(`Spring YAML traversal depth exceeds ${MAX_YAML_TRAVERSAL_DEPTH}`);
+    }
+    state.remainingNodes--;
+    if (state.remainingNodes < 0) {
+        throw new Error(`Spring YAML traversal exceeds ${MAX_YAML_TRAVERSAL_NODES} nodes`);
+    }
+}
+function isObjectValue(value) {
+    return value !== null && typeof value === 'object';
+}
+// Aliases are resolved to their anchor event by name while the tree is built,
+// so following one here is a single pointer hop.
+function resolveYamlAliasEvent(event) {
+    return event?.aliasOf ?? event;
+}
+function yamlMappingPairs(event) {
+    const pairs = [];
+    for (let index = 0; index + 1 < event.children.length; index += 2) {
+        const keyEvent = event.children[index];
+        const valueEvent = event.children[index + 1];
+        if (keyEvent.kind !== 'scalar')
+            continue;
+        pairs.push({ key: String(keyEvent.result), keyEvent, valueEvent });
+    }
+    return pairs;
+}
+/**
+ * First match in a pre-order walk of `event`, following sequences and `<<` merge
+ * chains. Iterative: children are pushed in reverse so the explicit stack pops
+ * them in declaration order, which is what makes "first match" mean the same
+ * thing it did when this recursed.
+ */
+function findYamlMappingLocation(event, key, traversal) {
+    const visited = new Set();
+    const stack = [{ event, depth: 0 }];
+    while (stack.length > 0) {
+        const step = stack.pop();
+        if (step === undefined)
+            break;
+        consumeYamlTraversalBudget(traversal, step.depth);
+        const resolved = resolveYamlAliasEvent(step.event);
+        if (resolved === undefined || visited.has(resolved))
+            continue;
+        visited.add(resolved);
+        if (resolved.kind === 'sequence') {
+            for (let index = resolved.children.length - 1; index >= 0; index--) {
+                stack.push({ event: resolved.children[index], depth: step.depth + 1 });
+            }
+            continue;
+        }
+        if (resolved.kind !== 'mapping')
+            continue;
+        const pairs = yamlMappingPairs(resolved);
+        const direct = pairs.find((pair) => pair.key === key);
+        if (direct !== undefined) {
+            return { valueEvent: direct.valueEvent, line: direct.keyEvent.startLine };
+        }
+        const merges = pairs.filter((pair) => pair.key === '<<');
+        for (let index = merges.length - 1; index >= 0; index--) {
+            stack.push({ event: merges[index].valueEvent, depth: step.depth + 1 });
+        }
+    }
+    return undefined;
+}
+/**
+ * Flatten a document to `dotted.key -> line`, iteratively. Children are pushed in
+ * reverse so the stack pops them in declaration order, keeping `out` in the same
+ * insertion order — and the traversal budget consumed in the same sequence — as
+ * the recursive walk this replaced.
+ */
+function flattenYamlValue(value, event, prefix, out, traversal) {
+    const stack = [
+        { kind: 'visit', value, event, prefix, sourceLine: event?.startLine ?? 1, depth: 0 },
+    ];
+    while (stack.length > 0) {
+        const step = stack.pop();
+        if (step === undefined)
+            break;
+        if (step.kind === 'leave') {
+            traversal.activeObjects.delete(step.object);
+            continue;
+        }
+        const { value: current, prefix: currentPrefix, sourceLine, depth } = step;
+        consumeYamlTraversalBudget(traversal, depth);
+        const resolvedEvent = resolveYamlAliasEvent(step.event);
+        const trackedObject = isObjectValue(current) ? current : undefined;
+        if (trackedObject !== undefined) {
+            if (traversal.activeObjects.has(trackedObject))
+                continue;
+            traversal.activeObjects.add(trackedObject);
+            stack.push({ kind: 'leave', object: trackedObject });
+        }
+        if (Array.isArray(current)) {
+            if (current.length === 0 && currentPrefix.length > 0 && !out.has(currentPrefix)) {
+                out.set(currentPrefix, sourceLine);
+            }
+            for (let index = current.length - 1; index >= 0; index--) {
+                stack.push({
+                    kind: 'visit',
+                    value: current[index],
+                    event: resolvedEvent?.children[index],
+                    prefix: `${currentPrefix}[${index}]`,
+                    sourceLine,
+                    depth: depth + 1,
+                });
+            }
+            continue;
+        }
+        if (current !== null &&
+            typeof current === 'object' &&
+            (resolvedEvent?.kind === 'mapping' || resolvedEvent === undefined)) {
+            // js-yaml 5 builds `!!set` as a native Set, whose members are not own
+            // properties; v4 built a plain `{member: null}` object. Enumerate them so a
+            // tagged set still contributes one key per member instead of a bare leaf.
+            const entries = current instanceof Set
+                ? [...current].map((member) => [String(member), null])
+                : Object.entries(current);
+            if (entries.length === 0 && currentPrefix.length > 0 && !out.has(currentPrefix)) {
+                out.set(currentPrefix, sourceLine);
+            }
+            for (let index = entries.length - 1; index >= 0; index--) {
+                const [key, nested] = entries[index];
+                const location = findYamlMappingLocation(resolvedEvent, key, traversal);
+                stack.push({
+                    kind: 'visit',
+                    value: nested,
+                    event: location?.valueEvent,
+                    prefix: currentPrefix.length === 0 ? key : `${currentPrefix}.${key}`,
+                    sourceLine: location?.line ?? sourceLine,
+                    depth: depth + 1,
+                });
+            }
+            continue;
+        }
+        if (currentPrefix.length > 0 && !out.has(currentPrefix))
+            out.set(currentPrefix, sourceLine);
+    }
+}
+// js-yaml 5 reports node positions as source offsets; map them to 1-based lines.
+function makeLineResolver(source) {
+    const lineStarts = [0];
+    for (let index = 0; index < source.length; index++) {
+        if (source[index] === '\n')
+            lineStarts.push(index + 1);
+    }
+    return (offset) => {
+        let low = 0;
+        let high = lineStarts.length - 1;
+        let line = 0;
+        while (low <= high) {
+            const mid = (low + high) >> 1;
+            if (lineStarts[mid] <= offset) {
+                line = mid;
+                low = mid + 1;
+            }
+            else {
+                high = mid - 1;
+            }
+        }
+        return line + 1;
+    };
+}
+/**
+ * Rebuild the parse tree from js-yaml 5's event stream (v4's `listener` option
+ * was removed). Returns each document's root event, with aliases already
+ * resolved to their anchor event so merged/aliased keys keep the line where
+ * they were declared.
+ *
+ * One node per event, so this pass is bounded by MAX_CONFIG_FILE_BYTES alone —
+ * MAX_YAML_TRAVERSAL_NODES governs the later walk, which can revisit a shared
+ * anchor many times and so needs a budget this linear pass does not.
+ */
+function buildYamlEventTree(events, source) {
+    const lineOf = makeLineResolver(source);
+    const anchors = new Map();
+    const stack = [];
+    const documentRoots = [];
+    const anchorName = (start, end) => start >= 0 && end > start ? source.slice(start, end) : null;
+    const attach = (node) => {
+        stack[stack.length - 1]?.children.push(node);
+    };
+    const register = (name, node) => {
+        if (name !== null)
+            anchors.set(name, node);
+    };
+    for (const event of events) {
+        switch (event.type) {
+            case yaml.EVENT_DOCUMENT:
+                // Anchors are document-scoped. constructFromEvents already rejects a
+                // cross-document alias before we get here, so this only keeps the two
+                // layers from disagreeing.
+                anchors.clear();
+                stack.push({
+                    startLine: 1,
+                    kind: null,
+                    result: undefined,
+                    aliasOf: undefined,
+                    children: [],
+                });
+                break;
+            case yaml.EVENT_MAPPING:
+            case yaml.EVENT_SEQUENCE: {
+                const node = {
+                    startLine: lineOf(event.start),
+                    kind: event.type === yaml.EVENT_MAPPING ? 'mapping' : 'sequence',
+                    result: undefined,
+                    aliasOf: undefined,
+                    children: [],
+                };
+                register(anchorName(event.anchorStart, event.anchorEnd), node);
+                attach(node);
+                stack.push(node);
+                break;
+            }
+            case yaml.EVENT_SCALAR: {
+                const node = {
+                    startLine: lineOf(event.valueStart),
+                    kind: 'scalar',
+                    result: yaml.getScalarValue(source, event),
+                    aliasOf: undefined,
+                    children: [],
+                };
+                register(anchorName(event.anchorStart, event.anchorEnd), node);
+                attach(node);
+                break;
+            }
+            case yaml.EVENT_ALIAS: {
+                const target = anchors.get(anchorName(event.anchorStart, event.anchorEnd) ?? '');
+                attach({ startLine: 1, kind: 'alias', result: undefined, aliasOf: target, children: [] });
+                break;
+            }
+            case yaml.EVENT_POP: {
+                const done = stack.pop();
+                // Documents are the only top-level containers, so a pop that empties the
+                // stack closes a document; its single child is the document's root value.
+                if (done !== undefined && stack.length === 0)
+                    documentRoots.push(done.children[0]);
+                break;
+            }
+        }
+    }
+    return documentRoots;
+}
+/** Parse and flatten YAML leaves without retaining their values. */
+export function parseSpringYaml(content, filePath, profile) {
+    const flattened = new Map();
+    const traversal = {
+        remainingNodes: MAX_YAML_TRAVERSAL_NODES,
+        activeObjects: new Set(),
+    };
+    const events = yaml.parseEvents(content, { maxDepth: MAX_YAML_TRAVERSAL_DEPTH });
+    const documents = yaml.constructFromEvents(events, {
+        source: content,
+        schema: SPRING_YAML_SCHEMA,
+        json: true,
+    });
+    const documentEvents = buildYamlEventTree(events, content);
+    documents.forEach((document, index) => flattenYamlValue(document, documentEvents[index], '', flattened, traversal));
+    return [...flattened.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, line]) => ({
+        key,
+        filePath,
+        line,
+        ...(profile ? { profile } : {}),
+        format: 'yaml',
+    }));
+}
+function configKeyNodeId(entry) {
+    return generateId('Property', `spring-config:${entry.filePath}:${entry.key}`);
+}
+async function readConfigKeys(repoPath, scannedFiles) {
+    const keys = [];
+    for (const scanned of scannedFiles) {
+        const classified = classifySpringConfigFile(scanned.path);
+        if (classified === null || scanned.size > MAX_CONFIG_FILE_BYTES)
+            continue;
+        try {
+            const content = await fs.readFile(path.join(repoPath, scanned.path), 'utf8');
+            keys.push(...(classified.format === 'properties'
+                ? parseSpringProperties(content, classified.filePath, classified.profile)
+                : parseSpringYaml(content, classified.filePath, classified.profile)));
+        }
+        catch {
+            // Malformed configuration is not a reason to fail the entire code index.
+            // Fail closed: no keys and therefore no misleading bindings for this file.
+        }
+    }
+    return keys;
+}
+export const springConfigPhase = {
+    name: 'springConfig',
+    deps: ['structure'],
+    async execute(ctx, deps) {
+        const { scannedFiles } = getPhaseOutput(deps, 'structure');
+        const configKeys = await readConfigKeys(ctx.repoPath, scannedFiles);
+        for (const entry of configKeys) {
+            const nodeId = configKeyNodeId(entry);
+            ctx.graph.addNode({
+                id: nodeId,
+                label: 'Property',
+                properties: {
+                    name: entry.key,
+                    filePath: entry.filePath,
+                    startLine: entry.line,
+                    endLine: entry.line,
+                    description: entry.profile
+                        ? `${SPRING_CONFIG_DESCRIPTION} (profile: ${entry.profile})`
+                        : SPRING_CONFIG_DESCRIPTION,
+                },
+            });
+            const fileId = generateId('File', entry.filePath);
+            if (ctx.graph.getNode(fileId) !== undefined) {
+                ctx.graph.addRelationship({
+                    id: generateId('DEFINES', `${fileId}->${nodeId}`),
+                    sourceId: fileId,
+                    targetId: nodeId,
+                    type: 'DEFINES',
+                    confidence: 1,
+                    reason: 'spring-config:key',
+                });
+            }
+        }
+        return { configKeys: configKeys.length };
+    },
+};

package/dist/core/ingestion/pipeline-phases/types.d.ts

@@ -13,6 +13,7 @@
  *  - Compile-time exhaustiveness (adding a phase = type error until wired)
  *  - Each phase is independently testable with mocked inputs
  */
+import type { GraphEmitControl } from '../../lbug/graph-emit-sink.js';
 import type { KnowledgeGraph } from '../../graph/types.js';
 import type { PipelineProgress } from '../../../_shared/index.js';
 import type { PipelineOptions } from '../pipeline.js';
@@ -28,6 +29,12 @@ export interface PipelineContext {
     readonly options?: PipelineOptions;
     /** Pipeline start timestamp (for elapsed-time logging). */
     readonly pipelineStart: number;
+    /**
+     * Streamed structural emit (#2680), present only when `streamGraphEmit` is on.
+     * `parse` calls `beginStreaming()` at its start; `pruneLocalSymbols` consults
+     * `hasStreamedSemanticEdge()`. Absent ⇒ everything stays in the graph.
+     */
+    readonly graphEmit?: GraphEmitControl;
 }
 /** Wraps a phase's output with timing metadata. */
 export interface PhaseResult<T> {

package/dist/core/ingestion/pipeline.d.ts

@@ -25,6 +25,14 @@ export interface PipelineOptions {
      * to retain those nodes under `skipGraphPhases`.
      */
     skipGraphPhases?: boolean;
+    /** Per-advice Spring AOP candidate inspection cap. `0` disables this cap. */
+    springAopMaxCandidateInspectionsPerAdvice?: number;
+    /** Aggregate Spring AOP candidate inspection cap for one analysis. `0` disables this cap. */
+    springAopMaxCandidateInspections?: number;
+    /** Per-advice Spring AOP `ADVISED_BY` edge cap. `0` disables this cap. */
+    springAopMaxAdvisedEdgesPerAdvice?: number;
+    /** Aggregate Spring AOP advice-edge cap for one analysis. `0` disables this cap. */
+    springAopMaxAdvisedEdges?: number;
     /**
      * Build the control-flow-graph / PDG substrate (#2081 M1, opt-in via `--pdg`).
      * Off by default: workers skip all CFG work and emit no `cfgSideChannel`, and
@@ -113,6 +121,22 @@ export interface PipelineOptions {
      * whole-graph emit.
      */
     streamPdgEmit?: boolean;
+    /**
+     * Streamed structural graph emit (#2680). When true, relationships that no
+     * mid-pipeline phase reads back (CALLS, IMPORTS, ACCESSES, CONTAINS, ...) are
+     * streamed to CSV-on-disk from the parse boundary onward instead of being
+     * retained in the in-memory graph — measured ~2.9x reduction of graph heap.
+     *
+     * NOT free: the `communities`, `processes`, `taintSummaries` and
+     * `callSummaries` phases all consume the whole CALLS graph and are disabled
+     * under this flag. The caller (`run-analyze`) gates it to full rebuilds.
+     * Requires `graphEmitCsvDir`.
+     */
+    streamGraphEmit?: boolean;
+    /** Directory for the streamed structural CSVs. Required when
+     *  `streamGraphEmit` is on; supplied by the caller, which owns storage-path
+     *  resolution (and its native-safe relocation). */
+    graphEmitCsvDir?: string;
     /** Streamed PDG-emit write buffer (rows) when `streamPdgEmit` is on (#2202).
      *  `undefined` ⇒ `DEFAULT_PDG_EMIT_CHUNK_ROWS`. Memory-only; does not affect
      *  emitted bytes. */
@@ -201,9 +225,9 @@ export interface PipelineOptions {
  *
  * Phase dependency graph:
  *
- *   scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
- *     → crossFile → scopeResolution → pruneLocalSymbols
- *     → mro → di → communities → processes
+ *   scan → structure → [springConfig, markdown, cobol] → parse → [routes, tools, orm]
+ *     → crossFile → scopeResolution → [springAutoConfiguration, springAop] → pruneLocalSymbols
+ *     → mro → springAopInheritance → di → communities → processes
  *
  * To add a new phase: create a file in pipeline-phases/, export the phase
  * object, and `.register()` it at the appropriate position below. Opt-in

package/dist/core/ingestion/pipeline.js

@@ -15,16 +15,17 @@
  * See ARCHITECTURE.md for the full phase dependency diagram.
  */
 import { createKnowledgeGraph } from '../graph/graph.js';
-import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, pruneLocalSymbolsPhase, taintSummariesPhase, callSummariesPhase, mroPhase, diPhase, communitiesPhase, processesPhase, PhaseRegistry, } from './pipeline-phases/index.js';
+import { GraphEmitSink } from '../lbug/graph-emit-sink.js';
+import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, springConfigPhase, springAutoConfigurationPhase, springAopPhase, springAopInheritancePhase, pruneLocalSymbolsPhase, taintSummariesPhase, callSummariesPhase, mroPhase, diPhase, communitiesPhase, processesPhase, PhaseRegistry, } from './pipeline-phases/index.js';
 // ── Phase registry ─────────────────────────────────────────────────────────
 /**
  * All pipeline phases with their dependency relationships.
  *
  * Phase dependency graph:
  *
- *   scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
- *     → crossFile → scopeResolution → pruneLocalSymbols
- *     → mro → di → communities → processes
+ *   scan → structure → [springConfig, markdown, cobol] → parse → [routes, tools, orm]
+ *     → crossFile → scopeResolution → [springAutoConfiguration, springAop] → pruneLocalSymbols
+ *     → mro → springAopInheritance → di → communities → processes
  *
  * To add a new phase: create a file in pipeline-phases/, export the phase
  * object, and `.register()` it at the appropriate position below. Opt-in
@@ -40,6 +41,7 @@ export function buildPhaseList(options) {
     return (new PhaseRegistry()
         .register(scanPhase)
         .register(structurePhase)
+        .register(springConfigPhase)
         .register(markdownPhase)
         .register(cobolPhase)
         .register(parsePhase)
@@ -48,6 +50,8 @@ export function buildPhaseList(options) {
         .register(ormPhase)
         .register(crossFilePhase)
         .register(scopeResolutionPhase)
+        .register(springAutoConfigurationPhase)
+        .register(springAopPhase)
         .register(pruneLocalSymbolsPhase)
         // M4 (#2084): interprocedural taint fixpoint — the first real opt-in
         // pdg-gated phase. Off ⇒ absent ⇒ byte-identical graph. No always-on
@@ -55,6 +59,7 @@ export function buildPhaseList(options) {
         .register(taintSummariesPhase, { enabledWhen: (o) => o.pdg === true })
         .register(callSummariesPhase, { enabledWhen: (o) => o.pdg === true })
         .register(mroPhase, { enabledWhen: (o) => !o.skipGraphPhases })
+        .register(springAopInheritancePhase, { enabledWhen: (o) => !o.skipGraphPhases })
         .register(diPhase, { enabledWhen: (o) => !o.skipGraphPhases })
         .register(communitiesPhase, { enabledWhen: (o) => !o.skipGraphPhases })
         .register(processesPhase, { enabledWhen: (o) => !o.skipGraphPhases })
@@ -66,23 +71,59 @@ export function buildPhaseList(options) {
 export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
     const graph = createKnowledgeGraph();
     const pipelineStart = Date.now();
+    // Streamed structural emit (#2680). The sink is a write-routing façade over
+    // `graph`; it streams nothing until `beginStreaming()` fires at the parse
+    // boundary.
+    //
+    // A missing `graphEmitCsvDir` is a caller bug, not a reason to quietly skip
+    // streaming: this is on by default, so a programmatic host that builds its own
+    // `PipelineOptions` (eval-server, the MCP daemon, a test) would otherwise ask
+    // for streaming, silently not get it, and still see a successful run. Fail
+    // loudly instead — the whole point of the surrounding work is that a degraded
+    // outcome must never look like a clean one.
+    let graphEmitSink;
+    if (options?.streamGraphEmit === true) {
+        if (options.graphEmitCsvDir === undefined) {
+            throw new Error('streamGraphEmit was requested but graphEmitCsvDir is missing. The caller owns ' +
+                'storage-path resolution (see resolveNativeSafeStorageDir in run-analyze.ts); ' +
+                'pass the directory, or leave streamGraphEmit unset to run without streaming.');
+        }
+        graphEmitSink = new GraphEmitSink(graph, options.graphEmitCsvDir);
+    }
     const phases = buildPhaseList(options);
-    const results = await runPipeline(phases, {
-        repoPath,
-        graph,
-        onProgress,
-        options,
-        pipelineStart,
-    });
+    let graphEmitManifest;
+    let results;
+    try {
+        results = await runPipeline(phases, {
+            repoPath,
+            graph: graphEmitSink ?? graph,
+            onProgress,
+            options,
+            pipelineStart,
+            graphEmit: graphEmitSink,
+        });
+        graphEmitManifest = graphEmitSink?.finalize();
+    }
+    finally {
+        // Release per-pair fds when the pipeline threw before finalize ran.
+        graphEmitSink?.close();
+    }
     // Extract final results for the PipelineResult contract
     const { totalFiles, usedWorkerPool } = getPhaseOutput(results, 'parse');
     let communityResult;
     let processResult;
     const scopeResolutionOutput = getPhaseOutput(results, 'scopeResolution');
     const resolutionOutcomes = scopeResolutionOutput.resolutionOutcomes;
+    const undecidedSatisfaction = scopeResolutionOutput.undecidedSatisfaction;
     // Streamed PDG-emit manifest (#2202): present only when streaming was on.
     const pdgEmitManifest = scopeResolutionOutput.pdgEmitManifest;
-    if (!options?.skipGraphPhases) {
+    const propertyInference = scopeResolutionOutput.propertyInference;
+    // Presence check, not `!skipGraphPhases`: phases can now be filtered out by
+    // any `enabledWhen` predicate (streamGraphEmit disables communities/processes
+    // too), and `getPhaseOutput` THROWS on a phase that was never resolved. Keying
+    // off the options flag alone made every filtered-out combination crash here
+    // rather than return undefined results.
+    if (results.has('communities') && results.has('processes')) {
         communityResult = getPhaseOutput(results, 'communities').communityResult;
         processResult = getPhaseOutput(results, 'processes').processResult;
     }
@@ -99,13 +140,22 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
         },
     });
     return {
+        // The RAW graph, deliberately — NOT `graphEmitSink`. Phases above received
+        // the sink so their reads are complete, but `loadGraphToLbug` feeds this to
+        // `streamAllCSVsToDisk`, and the sink's complete iterator would then emit
+        // every streamed edge a SECOND time on top of the per-pair CSVs the sink
+        // already wrote and the manifest already COPYs. Returning the sink here
+        // silently doubles every streamed relationship in the persisted graph.
         graph,
         repoPath,
         totalFileCount: totalFiles,
+        graphEmitManifest,
         communityResult,
         processResult,
         resolutionOutcomes,
+        undecidedSatisfaction,
         usedWorkerPool,
         pdgEmitManifest,
+        propertyInference,
     };
 };