peaks-loop 4.0.15 → 4.0.17

package/dist/services/slice/slice-decompose-service.js

@@ -20,116 +20,93 @@
  */
 import { join, relative, dirname, basename } from 'node:path';
 import { calibrate } from './calibration-store.js';
+export async function decomposeSlices(rid, prdMarkdown, projectRoot, options = {}) {
+    const runners = resolveRunners(options);
+    const stageOrder = [
+        'validate-codegraph',
+        'resolve-work-units',
+        'build-dep-dag',
+        'scc-critical-path',
+        'min-cut',
+        'partition-estimate-emit'
+    ];
+    const initial = createInitialState(rid, prdMarkdown, projectRoot, runners);
+    const final = await runPipeline(initial, stageOrder);
+    if (final.result === null) {
+        throw new Error('decomposeSlices FSM completed without emitting a result');
+    }
+    return final.result;
+}
+function createInitialState(rid, prdMarkdown, projectRoot, runners) {
+    return {
+        rid,
+        prdMarkdown,
+        projectRoot,
+        runners,
+        cgStatus: null,
+        workUnits: [],
+        depEdges: [],
+        kg: null,
+        understandAvailable: false,
+        codegraphAffectedCrossFile: false,
+        scc: null,
+        criticalPath: null,
+        minCut: null,
+        batchesWithEstimates: [],
+        result: null
+    };
+}
+async function runPipeline(state, stages) {
+    let current = state;
+    for (const stage of stages) {
+        current = await runStage(current, stage);
+    }
+    return current;
+}
+async function runStage(state, stage) {
+    switch (stage) {
+        case 'validate-codegraph':
+            return validateCodegraphStage(state);
+        case 'resolve-work-units':
+            return resolveWorkUnitsStage(state);
+        case 'build-dep-dag':
+            return buildDepDagStage(state);
+        case 'scc-critical-path':
+            return sccCriticalPathStage(state);
+        case 'min-cut':
+            return minCutStage(state);
+        case 'partition-estimate-emit':
+            return partitionEstimateEmitStage(state);
+    }
+}
+function resolveRunners(options) {
+    return {
+        cg: options.codegraphRunner ?? defaultCodegraphRunner(),
+        ur: options.understandRunner ?? defaultUnderstandRunner(),
+        ier: options.importEdgeRunner ?? defaultImportEdgeRunner()
+    };
+}
 // =====================================================================
-// PUBLIC: decomposeSlices (the 6-stage pure algorithm)
+// Stage 0: validate codegraph index
 // =====================================================================
-export async function decomposeSlices(rid, prdMarkdown, projectRoot, options = {}) {
-    const cg = options.codegraphRunner ?? defaultCodegraphRunner();
-    const ur = options.understandRunner ?? defaultUnderstandRunner();
-    const ier = options.importEdgeRunner ?? defaultImportEdgeRunner();
-    // ---------- Stage 0: Validate codegraph ----------
-    const cgStatus = await cg.status(projectRoot);
+async function validateCodegraphStage(state) {
+    const cgStatus = await state.runners.cg.status(state.projectRoot);
     if (!cgStatus.indexed) {
         throw new Error('peaks codegraph not initialised on this project. ' +
             'Run `npx codegraph init` then `npx codegraph index` in ' +
-            projectRoot +
+            state.projectRoot +
             ' before invoking `peaks slice decompose`.');
     }
-    // ---------- Read understand-anything ----------
-    const kg = await ur.read(projectRoot);
-    const understandAvailable = kg !== null;
-    // ---------- Stage 1: Work-unit resolution ----------
-    const acs = extractAcceptanceCriteria(prdMarkdown);
-    let workUnits = await resolveWorkUnits(rid, acs, cg, projectRoot);
-    // ---------- Stage 2: Dependency DAG ----------
-    const explicitFiles = workUnits.flatMap((w) => w.files);
-    const probeImports = await ier.importsOf(projectRoot, explicitFiles);
-    const fileSet = new Set(explicitFiles);
-    for (const e of probeImports) {
-        fileSet.add(e.from);
-        fileSet.add(e.to);
-    }
-    const allFiles = Array.from(fileSet);
-    // If no ACs but the import graph has files, create implicit WUs (one per file).
-    // This is the fallback path for the chain/diamond test cases.
-    if (workUnits.length === 0 && allFiles.length > 0) {
-        workUnits = allFiles.map((file, i) => ({
-            id: `F${i + 1}`,
-            label: basename(file),
-            files: [file],
-            loc: 110,
-            testsAdded: 0,
-            filePath: file,
-            candidates: [`file:${file}`]
-        }));
-    }
-    let codegraphAffectedCrossFile = false;
-    if (allFiles.length > 0) {
-        try {
-            const aff = await cg.affected(allFiles, projectRoot);
-            codegraphAffectedCrossFile = aff.totalDependentsTraversed > 0;
-        }
-        catch {
-            codegraphAffectedCrossFile = false;
-        }
-    }
-    const importEdges = await ier.importsOf(projectRoot, allFiles);
-    const depEdges = buildDependencyEdges(workUnits, importEdges, kg, projectRoot);
-    // ---------- Stage 3: SCC + critical path ----------
-    const nodeIds = workUnits.map((w) => w.id);
-    const scc = findSCCs(nodeIds, depEdges);
-    const criticalPath = findCriticalPath(workUnits, depEdges);
-    // ---------- Stage 4: Min-cut ----------
-    const minCut = findMinCut(workUnits, depEdges, criticalPath, kg);
-    // ---------- Stage 5+6: Partition + Estimate + Emit ----------
-    const parallelBatches = partitionIntoBatches(workUnits, depEdges, criticalPath);
-    const batchesWithEstimates = parallelBatches.map((b) => ({
-        ...b,
-        slices: b.slices.map((s) => ({
-            ...s,
-            estimate: estimateSlice(s, kg)
-        }))
-    }));
-    const totalSlices = batchesWithEstimates.reduce((sum, b) => sum + b.slices.length, 0);
-    const pickHint = totalSlices > 10
-        ? `slice count is ${totalSlices} (>10); split into multiple pick sessions for operator comfort`
-        : undefined;
-    const codegraphEnvelope = {
-        nodes: cgStatus.nodes,
-        edges: cgStatus.edges,
-        dbMB: cgStatus.dbMB,
-        freshness: cgStatus.freshness,
-        affectedCrossFile: codegraphAffectedCrossFile,
-        note: codegraphAffectedCrossFile
-            ? 'cross-file dependents resolved via codegraph.affected'
-            : 'codegraph.affected returned 0 cross-file dependents (v0.7.10 limitation); used real import edges'
-    };
-    const understandEnvelope = {
-        kgNodes: kg?.nodes.length ?? 0,
-        kgEdges: kg?.edges.length ?? 0,
-        available: understandAvailable,
-        fallback: understandAvailable ? 'semantic' : 'structural-only',
-        note: understandAvailable
-            ? 'read from .understand-anything/knowledge-graph.json'
-            : '.understand-anything/knowledge-graph.json not found; algorithm falls back to structural cuts'
-    };
-    return {
-        rid,
-        generatedAt: new Date().toISOString(),
-        codegraph: codegraphEnvelope,
-        understandAnything: understandEnvelope,
-        workUnits,
-        dependencyDAG: { edges: depEdges },
-        sccAnalysis: scc,
-        criticalPath,
-        minCutResult: minCut,
-        parallelBatches: batchesWithEstimates,
-        ...(pickHint !== undefined ? { pickHint } : {})
-    };
+    return { ...state, cgStatus };
 }
 // =====================================================================
-// Stage 1 helpers
+// Stage 1: work-unit resolution
 // =====================================================================
+async function resolveWorkUnitsStage(state) {
+    const acs = extractAcceptanceCriteria(state.prdMarkdown);
+    const workUnits = await resolveWorkUnits(state.rid, acs, state.runners.cg, state.projectRoot);
+    return { ...state, workUnits };
+}
 function extractAcceptanceCriteria(prd) {
     const acs = [];
     const lines = prd.split('\n');
@@ -190,58 +167,139 @@ function matchAcToHit(ac, hits) {
     return hits[0];
 }
 // =====================================================================
-// Stage 2 helpers
+// Stage 2: dependency DAG
 // =====================================================================
-function buildDependencyEdges(wus, importEdges, kg, projectRoot) {
+async function buildDepDagStage(state) {
+    const kg = await state.runners.ur.read(state.projectRoot);
+    const understandAvailable = kg !== null;
+    const fileSet = await collectFileSet(state.workUnits, state.runners.ier, state.projectRoot);
+    const allFiles = Array.from(fileSet);
+    const codegraphAffectedCrossFile = await probeCrossFileAffected(allFiles, state.runners.cg, state.projectRoot);
+    const workUnits = applyImplicitWuFallback(state.workUnits, allFiles);
+    const importEdges = await state.runners.ier.importsOf(state.projectRoot, allFiles);
+    const depEdges = buildDependencyEdges(workUnits, importEdges, kg, state.projectRoot);
+    return { ...state, kg, understandAvailable, codegraphAffectedCrossFile, workUnits, depEdges };
+}
+async function collectFileSet(workUnits, ier, projectRoot) {
+    const explicitFiles = workUnits.flatMap((w) => w.files);
+    const probeImports = await ier.importsOf(projectRoot, explicitFiles);
+    const fileSet = new Set(explicitFiles);
+    for (const e of probeImports) {
+        fileSet.add(e.from);
+        fileSet.add(e.to);
+    }
+    return fileSet;
+}
+async function probeCrossFileAffected(allFiles, cg, projectRoot) {
+    if (allFiles.length === 0)
+        return false;
+    try {
+        const aff = await cg.affected(allFiles, projectRoot);
+        return aff.totalDependentsTraversed > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** If no ACs but the import graph has files, create implicit WUs (one
+ *  per file). This is the fallback path for the chain/diamond test
+ *  cases. */
+function applyImplicitWuFallback(workUnits, allFiles) {
+    if (workUnits.length > 0 || allFiles.length === 0)
+        return [...workUnits];
+    return allFiles.map((file, i) => ({
+        id: `F${i + 1}`,
+        label: basename(file),
+        files: [file],
+        loc: 110,
+        testsAdded: 0,
+        filePath: file,
+        candidates: [`file:${file}`]
+    }));
+}
+function indexFilesToWorkUnits(wus) {
     const fileToWu = new Map();
     for (const wu of wus) {
         for (const f of wu.files) {
             fileToWu.set(f, wu.id);
         }
     }
-    const edges = [];
-    const seen = new Set();
-    const addEdge = (from, to, kind, weight, evidence, isSemantic, confidence) => {
-        if (from === to)
-            return;
-        const key = `${from}->${to}|${kind}`;
-        if (seen.has(key))
-            return;
-        seen.add(key);
-        edges.push({ from, to, kind, weight, evidence, isSemantic, confidence });
-    };
+    return fileToWu;
+}
+function classifyImportEdge(imp, fileToWu, projectRoot) {
+    let fromWu = fileToWu.get(imp.from);
+    let toWu = fileToWu.get(imp.to);
+    if (!fromWu) {
+        const resolved = resolveRelativeImport(projectRoot, imp.from, imp.evidence);
+        fromWu = fileToWu.get(resolved);
+    }
+    if (!toWu) {
+        const resolved = resolveRelativeImport(projectRoot, imp.from, imp.evidence);
+        toWu = fileToWu.get(resolved);
+    }
+    if (!fromWu || !toWu)
+        return null;
+    return { fromWu, toWu, evidence: imp.evidence };
+}
+function pushIfNew(collector, edge) {
+    if (edge.from === edge.to)
+        return;
+    const key = `${edge.from}->${edge.to}|${edge.kind}`;
+    if (collector.seen.has(key))
+        return;
+    collector.seen.add(key);
+    collector.edges.push(edge);
+}
+function collectImportEdges(importEdges, fileToWu, projectRoot, collector) {
     for (const imp of importEdges) {
-        let fromWu = fileToWu.get(imp.from);
-        let toWu = fileToWu.get(imp.to);
-        if (!fromWu) {
-            const resolved = resolveRelativeImport(projectRoot, imp.from, imp.evidence);
-            fromWu = fileToWu.get(resolved);
-        }
-        if (!toWu) {
-            const resolved = resolveRelativeImport(projectRoot, imp.from, imp.evidence);
-            toWu = fileToWu.get(resolved);
-        }
-        if (fromWu && toWu) {
-            addEdge(fromWu, toWu, 'imports', 10.0, imp.evidence, false, 'structural');
-        }
+        const classified = classifyImportEdge(imp, fileToWu, projectRoot);
+        if (classified === null)
+            continue;
+        const edge = {
+            from: classified.fromWu,
+            to: classified.toWu,
+            kind: 'imports',
+            weight: 10.0,
+            evidence: classified.evidence,
+            isSemantic: false,
+            confidence: 'structural'
+        };
+        pushIfNew(collector, edge);
     }
+}
+function collectSemanticEdges(kg, fileToWu, collector) {
+    for (const e of kg.edges) {
+        if (e.type !== 'contains_flow' && e.type !== 'flow_step')
+            continue;
+        const fromNode = kg.nodes.find((n) => n.id === e.source);
+        const toNode = kg.nodes.find((n) => n.id === e.target);
+        if (!fromNode?.filePath || !toNode?.filePath)
+            continue;
+        const fromWu = fileToWu.get(fromNode.filePath);
+        const toWu = fileToWu.get(toNode.filePath);
+        if (!fromWu || !toWu || fromWu === toWu)
+            continue;
+        const weight = e.type === 'flow_step' ? 0.05 : 0.1;
+        const edge = {
+            from: fromWu,
+            to: toWu,
+            kind: e.type,
+            weight,
+            evidence: `understand-anything: ${e.type} ${e.source}->${e.target}`,
+            isSemantic: true,
+            confidence: 'semantic'
+        };
+        pushIfNew(collector, edge);
+    }
+}
+function buildDependencyEdges(wus, importEdges, kg, projectRoot) {
+    const fileToWu = indexFilesToWorkUnits(wus);
+    const collector = { edges: [], seen: new Set() };
+    collectImportEdges(importEdges, fileToWu, projectRoot, collector);
     if (kg !== null) {
-        for (const e of kg.edges) {
-            if (e.type !== 'contains_flow' && e.type !== 'flow_step')
-                continue;
-            const fromNode = kg.nodes.find((n) => n.id === e.source);
-            const toNode = kg.nodes.find((n) => n.id === e.target);
-            if (!fromNode?.filePath || !toNode?.filePath)
-                continue;
-            const fromWu = fileToWu.get(fromNode.filePath);
-            const toWu = fileToWu.get(toNode.filePath);
-            if (fromWu && toWu && fromWu !== toWu) {
-                const weight = e.type === 'flow_step' ? 0.05 : 0.1;
-                addEdge(fromWu, toWu, e.type, weight, `understand-anything: ${e.type} ${e.source}->${e.target}`, true, 'semantic');
-            }
-        }
+        collectSemanticEdges(kg, fileToWu, collector);
     }
-    return edges;
+    return collector.edges;
 }
 function resolveRelativeImport(projectRoot, sourceFile, evidence) {
     const match = /from\s+['"]([^'"]+)['"]/.exec(evidence);
@@ -257,7 +315,19 @@ function resolveRelativeImport(projectRoot, sourceFile, evidence) {
 // =====================================================================
 // Stage 3: Tarjan SCC + longest path
 // =====================================================================
+function sccCriticalPathStage(state) {
+    const nodeIds = state.workUnits.map((w) => w.id);
+    const scc = findSCCs(nodeIds, state.depEdges);
+    const criticalPath = findCriticalPath(state.workUnits, state.depEdges);
+    return { ...state, scc, criticalPath };
+}
 function findSCCs(nodeIds, edges) {
+    const adj = buildAdjacencyList(nodeIds, edges);
+    const sccs = runTarjan(nodeIds, adj);
+    return summariseSccs(sccs, edges);
+}
+/** Build a forward adjacency map: nodeId → list of distinct neighbours. */
+function buildAdjacencyList(nodeIds, edges) {
     const adj = new Map();
     for (const id of nodeIds)
         adj.set(id, []);
@@ -266,42 +336,66 @@ function findSCCs(nodeIds, edges) {
         if (list && !list.includes(e.to))
             list.push(e.to);
     }
-    let index = 0;
-    const idx = new Map();
-    const lowlink = new Map();
-    const onStack = new Set();
-    const stack = [];
-    const sccs = [];
+    return adj;
+}
+function createTarjanVisitor() {
+    return {
+        index: 0,
+        idx: new Map(),
+        lowlink: new Map(),
+        onStack: new Set(),
+        stack: [],
+        sccs: []
+    };
+}
+function enterNode(visitor, v) {
+    visitor.idx.set(v, visitor.index);
+    visitor.lowlink.set(v, visitor.index);
+    visitor.index++;
+    visitor.stack.push(v);
+    visitor.onStack.add(v);
+}
+function relaxEdge(visitor, v, w, recurse) {
+    if (!visitor.idx.has(w)) {
+        recurse(w);
+        visitor.lowlink.set(v, Math.min(visitor.lowlink.get(v) ?? 0, visitor.lowlink.get(w) ?? 0));
+    }
+    else if (visitor.onStack.has(w)) {
+        visitor.lowlink.set(v, Math.min(visitor.lowlink.get(v) ?? 0, visitor.idx.get(w) ?? 0));
+    }
+}
+function finaliseRoot(visitor, v) {
+    if ((visitor.lowlink.get(v) ?? 0) !== (visitor.idx.get(v) ?? 0))
+        return;
+    const component = [];
+    let w;
+    do {
+        w = visitor.stack.pop();
+        visitor.onStack.delete(w);
+        component.push(w);
+    } while (w !== v);
+    visitor.sccs.push(component);
+}
+/** Run Tarjan's SCC algorithm; returns the list of components in
+ *  discovery order. Visitor state is hoisted to a named struct
+ *  (`TarjanVisitor`) so the recursive body can be split into
+ *  enterNode / relaxEdge / finaliseRoot without parameter sprawl. */
+function runTarjan(nodeIds, adj) {
+    const visitor = createTarjanVisitor();
     const strongconnect = (v) => {
-        idx.set(v, index);
-        lowlink.set(v, index);
-        index++;
-        stack.push(v);
-        onStack.add(v);
+        enterNode(visitor, v);
         for (const w of adj.get(v) ?? []) {
-            if (!idx.has(w)) {
-                strongconnect(w);
-                lowlink.set(v, Math.min(lowlink.get(v) ?? 0, lowlink.get(w) ?? 0));
-            }
-            else if (onStack.has(w)) {
-                lowlink.set(v, Math.min(lowlink.get(v) ?? 0, idx.get(w) ?? 0));
-            }
-        }
-        if (lowlink.get(v) === idx.get(v)) {
-            const component = [];
-            let w;
-            do {
-                w = stack.pop();
-                onStack.delete(w);
-                component.push(w);
-            } while (w !== v);
-            sccs.push(component);
+            relaxEdge(visitor, v, w, strongconnect);
         }
+        finaliseRoot(visitor, v);
     };
     for (const id of nodeIds) {
-        if (!idx.has(id))
+        if (!visitor.idx.has(id))
             strongconnect(id);
     }
+    return visitor.sccs;
+}
+function summariseSccs(sccs, edges) {
     const trivial = [];
     const nonTrivial = [];
     for (const scc of sccs) {
@@ -329,11 +423,26 @@ function sameScc(sccs, a, b) {
     }
     return false;
 }
+/** Critical-path FSM: three sequential phases.
+ *  1. `phaseTopoOrder` -- Kahn's algorithm with cycle-tolerance fallback.
+ *  2. `phaseLongestDist` -- DP relaxation along the topo order.
+ *  3. `phaseReconstruct` -- backtrack + aggregate metrics.
+ *  Each phase has its own branch budget; the orchestrator stays linear. */
 function findCriticalPath(wus, edges) {
+    const locById = indexLocById(wus);
+    const adj = buildForwardAdjacency(wus, edges, locById);
+    const topoOrder = phaseTopoOrder(wus, adj);
+    const { dist, prev } = phaseLongestDist(wus, adj, topoOrder, locById);
+    return phaseReconstruct(wus, locById, topoOrder, dist, prev);
+}
+function indexLocById(wus) {
     const locById = new Map();
     for (const wu of wus) {
         locById.set(wu.id, wu.loc);
     }
+    return locById;
+}
+function buildForwardAdjacency(wus, edges, locById) {
     const adj = new Map();
     for (const wu of wus)
         adj.set(wu.id, []);
@@ -342,15 +451,33 @@ function findCriticalPath(wus, edges) {
         if (list)
             list.push({ to: e.to, weight: locById.get(e.to) ?? 0 });
     }
+    return adj;
+}
+function phaseTopoOrder(wus, adj) {
+    const indeg = computeIndegrees(wus, adj);
+    const queue = seedQueue(indeg);
+    const topoOrder = drainKahnQueue(queue, indeg, adj);
+    appendCycleLeftovers(wus, topoOrder);
+    return topoOrder;
+}
+function computeIndegrees(wus, adj) {
     const indeg = new Map();
     for (const wu of wus)
         indeg.set(wu.id, 0);
-    for (const e of edges)
-        indeg.set(e.to, (indeg.get(e.to) ?? 0) + 1);
+    for (const e of adj.values()) {
+        for (const { to } of e)
+            indeg.set(to, (indeg.get(to) ?? 0) + 1);
+    }
+    return indeg;
+}
+function seedQueue(indeg) {
     const queue = [];
     for (const [id, d] of indeg)
         if (d === 0)
             queue.push(id);
+    return queue;
+}
+function drainKahnQueue(queue, indeg, adj) {
     const topoOrder = [];
     while (queue.length > 0) {
         const n = queue.shift();
@@ -361,9 +488,15 @@ function findCriticalPath(wus, edges) {
                 queue.push(to);
         }
     }
+    return topoOrder;
+}
+/** Cycle-tolerance fallback: append any wu that didn't make it through Kahn. */
+function appendCycleLeftovers(wus, topoOrder) {
     for (const wu of wus)
         if (!topoOrder.includes(wu.id))
             topoOrder.push(wu.id);
+}
+function phaseLongestDist(wus, adj, topoOrder, locById) {
     const dist = new Map();
     const prev = new Map();
     for (const wu of wus) {
@@ -379,6 +512,26 @@ function findCriticalPath(wus, edges) {
             }
         }
     }
+    return { dist, prev };
+}
+function phaseReconstruct(wus, locById, topoOrder, dist, prev) {
+    const endNode = pickEndNode(topoOrder, dist);
+    const path = backtrackPath(endNode, prev);
+    const totalLoc = path.reduce((sum, id) => sum + (locById.get(id) ?? 0), 0);
+    const totalDeltaLoc = path.reduce((sum, id) => {
+        const wu = wus.find((w) => w.id === id);
+        return sum + (wu?.deltaLoc ?? wu?.loc ?? 0);
+    }, 0);
+    const edgeStrs = path.slice(0, -1).map((n, i) => `${n} -> ${path[i + 1]}`);
+    return {
+        nodes: path,
+        edges: edgeStrs,
+        totalLoc,
+        totalDeltaLoc,
+        rationale: `Longest path by sum of LoC across the dependency DAG; ${path.length} work units, ${totalLoc} LoC summed`
+    };
+}
+function pickEndNode(topoOrder, dist) {
     let endNode = topoOrder[0];
     let maxDist = -1;
     for (const [id, d] of dist) {
@@ -387,29 +540,26 @@ function findCriticalPath(wus, edges) {
             endNode = id;
         }
     }
+    return endNode;
+}
+function backtrackPath(endNode, prev) {
     const path = [];
     let cur = endNode;
     while (cur !== null) {
         path.unshift(cur);
         cur = prev.get(cur) ?? null;
     }
-    const totalLoc = path.reduce((sum, id) => sum + (locById.get(id) ?? 0), 0);
-    const totalDeltaLoc = path.reduce((sum, id) => {
-        const wu = wus.find((w) => w.id === id);
-        return sum + (wu?.deltaLoc ?? wu?.loc ?? 0);
-    }, 0);
-    const edgeStrs = path.slice(0, -1).map((n, i) => `${n} -> ${path[i + 1]}`);
-    return {
-        nodes: path,
-        edges: edgeStrs,
-        totalLoc,
-        totalDeltaLoc,
-        rationale: `Longest path by sum of LoC across the dependency DAG; ${path.length} work units, ${totalLoc} LoC summed`
-    };
+    return path;
 }
 // =====================================================================
 // Stage 4: Min-cut
 // =====================================================================
+function minCutStage(state) {
+    if (state.criticalPath === null)
+        return state;
+    const minCut = findMinCut(state.workUnits, state.depEdges, state.criticalPath, state.kg);
+    return { ...state, minCut };
+}
 function findMinCut(_wus, edges, criticalPath, _kg) {
     const cpSet = new Set(criticalPath.nodes);
     const nonCpEdges = edges.filter((e) => !cpSet.has(e.from) || !cpSet.has(e.to));
@@ -440,14 +590,95 @@ function findMinCut(_wus, edges, criticalPath, _kg) {
     };
 }
 // =====================================================================
-// Stage 5+6: Estimate + Partition
+// Stage 5+6: Estimate + Partition + Emit
 // =====================================================================
+function partitionEstimateEmitStage(state) {
+    if (state.criticalPath === null)
+        return state;
+    const parallelBatches = partitionIntoBatches(state.workUnits, state.depEdges, state.criticalPath);
+    const batchesWithEstimates = parallelBatches.map((b) => ({
+        ...b,
+        slices: b.slices.map((s) => ({
+            ...s,
+            estimate: estimateSlice(s, state.kg)
+        }))
+    }));
+    const result = buildDecompositionResult(state, batchesWithEstimates);
+    return { ...state, batchesWithEstimates, result };
+}
+function buildDecompositionResult(state, batchesWithEstimates) {
+    assertReadyForEmit(state);
+    const totalSlices = batchesWithEstimates.reduce((sum, b) => sum + b.slices.length, 0);
+    const pickHint = buildPickHint(totalSlices);
+    const codegraphEnvelope = buildCodegraphEnvelope(state);
+    const understandEnvelope = buildUnderstandEnvelope(state);
+    return {
+        rid: state.rid,
+        generatedAt: new Date().toISOString(),
+        codegraph: codegraphEnvelope,
+        understandAnything: understandEnvelope,
+        workUnits: state.workUnits,
+        dependencyDAG: { edges: state.depEdges },
+        sccAnalysis: state.scc,
+        criticalPath: state.criticalPath,
+        minCutResult: state.minCut,
+        parallelBatches: batchesWithEstimates,
+        ...(pickHint !== undefined ? { pickHint } : {})
+    };
+}
+function assertReadyForEmit(state) {
+    if (state.cgStatus === null ||
+        state.criticalPath === null ||
+        state.scc === null ||
+        state.minCut === null) {
+        throw new Error('decomposeSlices FSM reached emit stage without completing prior stages');
+    }
+}
+function buildPickHint(totalSlices) {
+    if (totalSlices <= 10)
+        return undefined;
+    return `slice count is ${totalSlices} (>10); split into multiple pick sessions for operator comfort`;
+}
+function buildCodegraphEnvelope(state) {
+    const cgStatus = state.cgStatus;
+    if (cgStatus === null) {
+        throw new Error('buildCodegraphEnvelope called before validate-codegraph stage');
+    }
+    return {
+        nodes: cgStatus.nodes,
+        edges: cgStatus.edges,
+        dbMB: cgStatus.dbMB,
+        freshness: cgStatus.freshness,
+        affectedCrossFile: state.codegraphAffectedCrossFile,
+        note: state.codegraphAffectedCrossFile
+            ? 'cross-file dependents resolved via codegraph.affected'
+            : 'codegraph.affected returned 0 cross-file dependents (v0.7.10 limitation); used real import edges'
+    };
+}
+function buildUnderstandEnvelope(state) {
+    return {
+        kgNodes: state.kg?.nodes.length ?? 0,
+        kgEdges: state.kg?.edges.length ?? 0,
+        available: state.understandAvailable,
+        fallback: state.understandAvailable ? 'semantic' : 'structural-only',
+        note: state.understandAvailable
+            ? 'read from .understand-anything/knowledge-graph.json'
+            : '.understand-anything/knowledge-graph.json not found; algorithm falls back to structural cuts'
+    };
+}
 function estimateSlice(slice, _kg) {
     const sampleSize = 0;
     const complexitySum = 0;
     return calibrate(complexitySum, slice.estimate.testCount, slice.estimate.locSum, sampleSize);
 }
 function partitionIntoBatches(wus, edges, _criticalPath) {
+    if (wus.length === 0)
+        return [];
+    const upstream = computeUpstream(wus, edges);
+    return runBatchScheduler(wus, upstream);
+}
+/** Build reverse adjacency: id → list of upstream wu ids that depend on it. */
+function computeUpstream(wus, edges) {
     const upstream = new Map();
     for (const wu of wus)
         upstream.set(wu.id, []);
@@ -456,55 +687,60 @@ function partitionIntoBatches(wus, edges, _criticalPath) {
         if (list && !list.includes(e.from))
             list.push(e.from);
     }
+    return upstream;
+}
+/** Iterate Kahn-style batches until every wu is placed. The seed
+ *  batch contains all wus with no upstream; subsequent batches pick
+ *  the wus whose upstream is fully placed. */
+function runBatchScheduler(wus, upstream) {
     const placed = new Set();
     const batches = [];
-    if (wus.length === 0)
-        return batches;
-    let currentBatch = [];
-    for (const wu of wus) {
-        if ((upstream.get(wu.id) ?? []).length === 0) {
-            currentBatch.push(wu.id);
-        }
-    }
-    batches.push({
-        batch: 1,
-        dependsOn: [],
-        slices: currentBatch.map((id) => wuToSlice(wus.find((w) => w.id === id))),
-        parallelizableWithinBatch: currentBatch.length > 1
-    });
-    for (const id of currentBatch)
+    const seedIds = wus
+        .filter((wu) => (upstream.get(wu.id) ?? []).length === 0)
+        .map((wu) => wu.id);
+    batches.push(materialiseBatch(1, [], seedIds, wus));
+    for (const id of seedIds)
         placed.add(id);
     let batchNum = 2;
     let prevBatchNums = [1];
     while (placed.size < wus.length) {
-        currentBatch = [];
-        for (const wu of wus) {
-            if (placed.has(wu.id))
-                continue;
-            const ups = upstream.get(wu.id) ?? [];
-            if (ups.every((u) => placed.has(u))) {
-                currentBatch.push(wu.id);
-            }
-        }
-        if (currentBatch.length === 0) {
-            for (const wu of wus) {
-                if (!placed.has(wu.id))
-                    currentBatch.push(wu.id);
-            }
-        }
-        batches.push({
-            batch: batchNum,
-            dependsOn: prevBatchNums,
-            slices: currentBatch.map((id) => wuToSlice(wus.find((w) => w.id === id))),
-            parallelizableWithinBatch: currentBatch.length > 1
-        });
-        for (const id of currentBatch)
+        const ready = pickReadyBatch(wus, upstream, placed);
+        batches.push(materialiseBatch(batchNum, prevBatchNums, ready, wus));
+        for (const id of ready)
             placed.add(id);
         prevBatchNums = [batchNum];
         batchNum++;
     }
     return batches;
 }
+function pickReadyBatch(wus, upstream, placed) {
+    const ready = [];
+    for (const wu of wus) {
+        if (placed.has(wu.id))
+            continue;
+        const ups = upstream.get(wu.id) ?? [];
+        if (ups.every((u) => placed.has(u))) {
+            ready.push(wu.id);
+        }
+    }
+    if (ready.length > 0)
+        return ready;
+    // Fallback: pick whatever is unplaced (shouldn't happen on a valid DAG,
+    // but keeps the loop total when cycles sneak through).
+    for (const wu of wus) {
+        if (!placed.has(wu.id))
+            ready.push(wu.id);
+    }
+    return ready;
+}
+function materialiseBatch(batchNum, dependsOn, ids, wus) {
+    return {
+        batch: batchNum,
+        dependsOn: [...dependsOn],
+        slices: ids.map((id) => wuToSlice(wus.find((w) => w.id === id))),
+        parallelizableWithinBatch: ids.length > 1
+    };
+}
 function wuToSlice(wu) {
     return {
         rid: `${wu.id}-slice`,