@opensip-cli/graph 0.1.4 → 0.1.6

package/dist/cli/graph.js

@@ -4,7 +4,7 @@
 // @fitness-ignore-file performance-anti-patterns -- spread in CLI report aggregation iterates bounded result sets (rule counts, entry-point lists).
 // @fitness-ignore-file no-markdown-references -- docs/plans/* pointers in JSDoc are stable internal references.
 // @fitness-ignore-file public-api-jsdoc -- GraphCommandOptions interface and executeGraph are already documented with rich JSDoc on each field; the check counts the top-level export line, not the fields.
-// @fitness-ignore-file file-length-limit -- top-level graph command handler with rich JSDoc on options; splitting would fragment the unified subcommand surface (gate/persist/output dispatch).
+// @fitness-ignore-file file-length-limit -- remaining top-level graph command handler still coordinates mode dispatch, output delivery, single-run engine selection, and CLI error mapping; large workspace/multi-path modes and sharded engine/session helpers are split out.
 /**
  * `opensip graph` — main subcommand handler.
  *
@@ -25,40 +25,24 @@
  * `--packages` flags were retired in favor of the polyglot surface
  * above; see docs/plans/graph-cli-language-neutral-scoping/.
  */
-import { realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { EXIT_CODES, passRate } from '@opensip-cli/contracts';
-import { ConfigurationError, currentScope, logger, SystemError, ToolError, ValidationError, } from '@opensip-cli/core';
-import { pickAdapter } from '../lang-adapter/registry.js';
-import { CatalogRepo } from '../persistence/catalog-repo.js';
-import { buildGraphSessionPayload } from '../persistence/session-payload.js';
+import { EXIT_CODES } from '@opensip-cli/contracts';
+import { ConfigurationError, currentScope, logger, ToolError, ValidationError, } from '@opensip-cli/core';
 import { resolveRecipeToRules } from '../recipes/resolve.js';
-import { mapOpenSipRuleIdToEngineSlug } from '../render/rule-id-mapping.js';
-import { currentRules } from '../rules/registry.js';
-import { assertFinalizedAcrossBoundary, finalizeGraphSignals, } from './apply-suppressions.js';
+import { finalizeGraphSignals } from './apply-suppressions.js';
 import { buildGraphEnvelope } from './build-envelope.js';
+import { planGraphExecution } from './graph-command-plan.js';
 import { runCatalogJsonMode, runGateMode } from './graph-modes.js';
-import { buildLiveGraphOutput, buildUnifiedReportLines, countFiles, resolutionBannerText, } from './graph-report.js';
-import { resolveCanonicalFileSet } from './orchestrate/canonical-file-set.js';
-import { detectMonorepoLayout, partitionFlatRepo, selectStrategyForLayout, } from './orchestrate/flat-monorepo-strategy.js';
-import { partitionFilesIntoShards } from './orchestrate/partition-files.js';
-import { loadGraphConfig, resolveGraphRecipeSelection, runGraph, runShardedGraph, } from './orchestrate.js';
-import { positionalPathLabel, resolvePositionalPaths } from './positional-paths.js';
+import { executeMultiPathGraph } from './graph-multi-path-mode.js';
+import { buildUnifiedReportLines, resolutionBannerText } from './graph-report.js';
+import { buildGraphSessionContribution } from './graph-session-contribution.js';
+import { executeSinglePathGraph } from './graph-single-run-mode.js';
+import { executeWorkspaceGraph } from './graph-workspace-mode.js';
+import { resolveGraphRecipeSelection } from './orchestrate.js';
 import { MemoryPressureError } from './pressure-monitor.js';
 import { GraphProfileBuilder, writeGraphProfile } from './profile.js';
-import { resolveAdaptersForRun } from './resolve-adapters.js';
-import { buildWorkspaceJsonDocument, writeWorkspaceReport } from './workspace-report.js';
-import { discoverPolyglotUnits, runWorkspaceUnitsInParallel } from './workspace-runner.js';
 const EVT_GRAPH_COMPLETE = 'graph.cli.graph.complete';
 const MODULE_GRAPH_CLI = 'graph:cli';
 const MODULE_GRAPH_RENDER = 'graph:render';
-/**
- * The feature columns the decoupled dashboard renders (ADR-0006): only these
- * are materialized into the persisted catalog, and only on the standard
- * (catalog-producing) `graph` run. Export-only paths (sarif/catalog export)
- * do not go through this dispatch, so they stay lean (no features persisted).
- */
-const DASHBOARD_FEATURE_COLUMNS = ['blast', 'scc', 'packageCoupling'];
 /**
  * Run graph and return the run's {@link GraphRunOutcome} — the deliverable
  * {@link SignalEnvelope} (so the composition root can cloud + `--report-to`
@@ -105,7 +89,7 @@ export async function executeGraph(opts, cli) {
     });
     // (profile / startedAtForProfile already declared at top of fn for branch visibility)
     try {
-        validateMutuallyExclusiveFlags(opts);
+        const plan = planGraphExecution(opts);
         // Resolve the recipe once at the top of the run (CLI layer owns selection;
         // the engine stays recipe-agnostic). Tool-scoped (ADR-0022): precedence is
         // `--recipe` flag > `graph.recipe` > `default`.
@@ -125,107 +109,17 @@ export async function executeGraph(opts, cli) {
         // request-scoped parsed-options bag the pre-action hook already augments, so
         // this is the single point that owns graph's recipe normalization.
         opts.recipe = recipeSelection.name;
-        if (opts.workspace === true) {
+        if (plan.shape === 'workspace') {
             const outcome = await executeWorkspaceGraph(opts, cli, profile);
             writeProfileIfRequested(opts, profile);
             return outcome;
         }
-        const positionalPaths = resolvePositionalScope(opts);
-        if (positionalPaths.length > 1) {
-            const outcome = await executeMultiPathGraph({ opts, cli, rules, startedAt, profile }, positionalPaths);
+        if (plan.shape === 'multi-path') {
+            const outcome = await executeMultiPathGraph({ opts, cli, rules, startedAt, profile, deliverGraphResult }, plan.positionalPaths);
             writeProfileIfRequested(opts, profile);
             return outcome;
         }
-        // Realpath the run root ONCE, before engine selection (F3 path parity). The
-        // EXACT engine normalizes its project dir via realpathSync internally
-        // (graph-typescript normalize-project-dir); the SHARDED worker derives
-        // project-relative `code.file` paths against this `projectRoot`. Under a
-        // symlinked cwd a RAW root would make the sharded paths gain `../..` prefixes
-        // while exact stays canonical → the two engines emit different `code.file`,
-        // and since the engine choice is environment-sensitive, a `--gate-save`
-        // baseline written by one engine would flag everything new under the other.
-        // Canonicalizing here (idempotent for non-symlinks) keeps both engines'
-        // emitted paths byte-identical. Shard discovery already realpaths internally
-        // (discoverFiles → normalizeProjectDir), so the shard files and this root now
-        // share the same canonical base.
-        const runCwd = realpathOrSelf(positionalPaths[0] ?? opts.cwd, opts.cwd);
-        // Honor the project's `graph:` config block (rule knobs like
-        // minCrossPackageDuplicatePackages). Resolved from the original cwd so a
-        // positional subtree run still picks up the project-root config.
-        const config = loadGraphConfig(opts.cwd);
-        // Determinism (ADR-0033, superseding ADR-0032/0031): the build engine is
-        // chosen by an explicit, deterministic policy — the SHARDED engine is the
-        // DEFAULT (both engines resolve through one shared model — exact = the
-        // 1-shard case — held equivalent by the directional soundness invariant +
-        // completeness floor; ADR-0033), and
-        // `--exact` opts OUT to the single-program engine. It is NOT chosen by
-        // `process.stdout.isTTY` or on-disk discovery state, so a bare `graph` builds
-        // the same catalog whether run in a terminal, piped, or under
-        // `--gate-*`/`--json`. When the project can't shard (no worker script,
-        // single-unit, discovery failure) we fall back to the exact engine — the
-        // natural single-package/small-repo path — rather than failing.
-        const resolution = await resolveEngineShards(opts, cli, positionalPaths);
-        const shards = resolution.shards;
-        logger.info({
-            evt: 'graph.cli.graph.engine',
-            module: MODULE_GRAPH_CLI,
-            mode: shards.length > 1 ? 'sharded' : 'exact',
-            requestedExact: opts.exact === true,
-            shards: shards.length,
-            reason: engineSelectionReason(opts, positionalPaths, shards.length > 1),
-        });
-        const profileRun = profile?.startRun({
-            label: positionalPaths.length === 0 ? 'root' : positionalPathLabel(runCwd, opts.cwd),
-            cwd: runCwd,
-            mode: shards.length > 1 ? 'sharded' : 'single-process',
-        });
-        // The synthetic partitioner runs BEFORE the profile run recorder exists
-        // (its `mode` label needs the shard count), so its wall time is measured
-        // where it runs and recorded here (ADR-0045 measurement plane).
-        if (resolution.partition !== undefined) {
-            profileRun?.recordStage('partition', resolution.partition.durationMs, resolution.partition.detail);
-        }
-        const result = shards.length > 1
-            ? await runProfiledShardedBuild(profileRun, {
-                opts,
-                shards,
-                projectRoot: runCwd,
-                cli,
-                config,
-                rules,
-            })
-            : await runGraph({
-                cwd: runCwd,
-                noCache: opts.noCache,
-                resolution: opts.resolution,
-                language: opts.language,
-                config,
-                rules,
-                datastore: cli.scope.datastore(),
-                emitFeatures: DASHBOARD_FEATURE_COLUMNS,
-                onProgress: profileRun?.onProgress,
-            });
-        profileRun?.finish(result);
-        // Propagate shard failures so incomplete catalogs do not silently produce
-        // baselines or pass --gate-compare (per-audit: failedShardIds was computed
-        // but never surfaced to the gate or as a hard error).
-        if (shards.length > 1) {
-            const sharded = result;
-            if (sharded.failedShardIds && sharded.failedShardIds.length > 0) {
-                throw new SystemError(`Sharded graph build had ${sharded.failedShardIds.length} shard failure(s); ` +
-                    `catalog and any --gate-* / baseline artifacts are incomplete. ` +
-                    `See 'graph.sharded.shard_failed' log events for per-shard details.`, { code: 'GRAPH.SHARD.FAILURES' });
-            }
-        }
-        enforceLanguageMismatchPolicy(opts, result.catalog, [runCwd]);
-        currentScope()?.diagnostics?.event('execute', 'debug', 'graph build complete', {
-            mode: shards.length > 1 ? 'sharded' : 'exact',
-            shards: shards.length,
-        });
-        // `runCwd` (= positionalPaths[0] ?? opts.cwd) is the build root the signals
-        // are relative to — the correct base for resolving `@graph-ignore` directive
-        // files. For the sharded build it equals `projectRoot` passed above.
-        const outcome = await dispatchGraphResult(opts, result, cli, startedAt, runCwd);
+        const outcome = await executeSinglePathGraph({ opts, cli, rules, startedAt, profile, dispatchGraphResult }, plan.positionalPaths);
         writeProfileIfRequested(opts, profile);
         return outcome;
     }
@@ -255,277 +149,6 @@ export async function executeGraph(opts, cli) {
  *     no worker script is available — a graceful fall-through to exact, the
  *     natural single-package path.
  */
-/**
- * Resolve a path to absolute (a RELATIVE input resolves against `base` —
- * the command's `opts.cwd`, NOT `process.cwd()`, which may differ when the
- * CLI is hosted), then realpath it (follow symlinks) — the SAME normalization
- * the exact engine's `normalizeProjectDir` applies, so both engines see one
- * canonical run root (F3). Falls back to the absolute path if realpath fails
- * (e.g. the path doesn't exist yet — discovery reports the error downstream).
- * Idempotent on an already-canonical path.
- */
-function realpathOrSelf(input, base) {
-    // `resolve(base, input)` returns `input` unchanged when it is already absolute.
-    const absolute = resolve(base, input);
-    try {
-        return realpathSync(absolute);
-    }
-    catch {
-        /* v8 ignore next */
-        return absolute;
-    }
-}
-async function resolveEngineShards(opts, cli, positionalPaths) {
-    if (opts.exact === true)
-        return { shards: [] };
-    if (positionalPaths.length > 0)
-        return { shards: [] };
-    return resolveShards(opts, cli);
-}
-/**
- * Human-readable explanation of the engine decision for the
- * `graph.cli.graph.engine` observability event. Pure; mirrors
- * {@link resolveEngineShards}'s branches.
- */
-function engineSelectionReason(opts, positionalPaths, sharded) {
-    if (sharded)
-        return 'sharded-default';
-    if (opts.exact === true)
-        return 'exact-opt-out';
-    if (positionalPaths.length > 0)
-        return 'exact-positional-paths';
-    return 'exact-not-shardable';
-}
-/**
- * Resolve a project to its shards (one per workspace package). Returns an
- * empty array — signalling the caller to use the single-process build —
- * when the project isn't multi-package, when no worker script is
- * available to spawn, or when discovery fails. Each unit's file set is
- * enumerated via the graph adapter; partitions with no files are dropped.
- *
- * ADR-0032: reached for any run that did NOT pass `--exact` (see
- * {@link resolveEngineShards}) — sharded is the default. A project that yields
- * ≤1 non-empty shard falls back to the exact single-program engine naturally.
- */
-async function resolveShards(opts, cli) {
-    const cliScript = opts.cliScript ?? process.argv[1];
-    if (typeof cliScript !== 'string' || cliScript.length === 0)
-        return { shards: [] };
-    let units;
-    try {
-        units = await discoverPolyglotUnits(opts.cwd, resolveAdaptersForRun(opts, cli));
-    }
-    catch {
-        /* v8 ignore next */
-        return resolveSyntheticFlatShards(opts);
-    }
-    if (units.length <= 1)
-        return resolveSyntheticFlatShards(opts);
-    // Phase 1 (graph-sharded-exact-parity): enumerate the canonical file set ONCE
-    // from project-wide root discovery — the SAME source + filter the exact engine
-    // uses — then PARTITION it across the discovered unit boundaries. The old loop
-    // re-derived each shard's files from that package's own tsconfig, which
-    // excludes the package's __fixtures__ tree and (for some) its test files, so
-    // the sharded engine silently dropped files the exact engine kept. Partitioning
-    // the canonical set guarantees both engines see the identical files.
-    const adapter = pickAdapter(opts.cwd);
-    let rootDiscovery;
-    try {
-        rootDiscovery = adapter.discoverFiles({ cwd: opts.cwd });
-    }
-    catch {
-        /* v8 ignore next */
-        return resolveSyntheticFlatShards(opts);
-    }
-    const canonicalFiles = resolveCanonicalFileSet(rootDiscovery.files);
-    const shards = partitionFilesIntoShards({
-        canonicalFiles,
-        units: units.map((u) => ({
-            id: u.id,
-            rootDir: u.rootDir,
-            ...(u.configPath === undefined ? {} : { configPathAbs: u.configPath }),
-        })),
-        projectRoot: rootDiscovery.projectDirAbs,
-        rootConfigPathAbs: rootDiscovery.configPathAbs,
-    });
-    // Need at least two non-empty shards to justify the parallel/merge overhead.
-    if (shards.length > 1)
-        return { shards };
-    return resolveSyntheticFlatShards(opts);
-}
-/**
- * Resolve a project's shard set the SAME way a production `graph` run does
- * (workspace units → canonical-file partition, else synthetic flat shards),
- * exposed for the real-repo equivalence guardrail (`graph-equivalence-check`).
- * Returns `[]` when the project isn't shardable (≤1 shard / no worker script) —
- * the guardrail rejects that, since the comparison is only meaningful on a
- * shardable multi-package repo. Reuses the private {@link resolveShards} so
- * there is ONE shard-resolution model, never a drifting copy.
- */
-export async function resolveShardsForCwd(cwd, cliScript, cli) {
-    const resolution = await resolveShards({ cwd, cliScript, noCache: true }, cli);
-    return resolution.shards;
-}
-/**
- * Flat-large fallback for single-tsconfig TypeScript repos. Workspace
- * sharding is preferred because package boundaries are semantically real. When
- * no workspace split exists and the TypeScript file count crosses the same
- * threshold as heap preflight's 12 GB tier, synthesize directory-coherent
- * shards and feed them into the existing sharded build.
- */
-function resolveSyntheticFlatShards(opts) {
-    if (typeof opts.language === 'string' && opts.language.length > 0)
-        return { shards: [] };
-    const adapter = pickAdapter(opts.cwd);
-    if (adapter.id !== 'typescript')
-        return { shards: [] };
-    let discovery;
-    try {
-        discovery = adapter.discoverFiles({ cwd: opts.cwd });
-    }
-    catch {
-        return { shards: [] };
-    }
-    // Canonical set (Phase 1): drop fixtures before partitioning so the flat-large
-    // fallback shards match the exact engine's file set just like the workspace path.
-    const canonicalFiles = resolveCanonicalFileSet(discovery.files);
-    // Measure the partition compute (layout detection + strategy resolution +
-    // partitioning) where it runs — the profile run recorder does not exist yet
-    // (its `mode` label needs the shard count), so executeGraph records the
-    // timing afterwards via `recordStage` (ADR-0045 measurement plane).
-    const partitionStart = Date.now();
-    const layout = detectMonorepoLayout({
-        repoRoot: discovery.projectDirAbs,
-        files: canonicalFiles,
-    });
-    const selection = selectStrategyForLayout(layout);
-    if (layout.kind !== 'flat-large' || selection.mode !== 'synthetic-partition') {
-        return { shards: [] };
-    }
-    // Strategy precedence: `graph.partitionStrategy` (config/env, ADR-0045) >
-    // the layout-recommended default > 'hybrid'. `loadGraphConfig` is
-    // scope-first and cheap, so reading it here (off the hot path) is safe.
-    const graphConfig = loadGraphConfig(opts.cwd);
-    const strategy = graphConfig.partitionStrategy ?? selection.partitionStrategy ?? 'hybrid';
-    const partitions = partitionFlatRepo({
-        files: layout.files,
-        repoRoot: discovery.projectDirAbs,
-        strategy,
-    });
-    const shards = partitions
-        .filter((p) => p.files.length > 0)
-        .map((p) => ({
-        id: `partition:${p.id}`,
-        rootDir: discovery.projectDirAbs,
-        files: p.files,
-        configPathAbs: discovery.configPathAbs,
-    }));
-    if (shards.length <= 1)
-        return { shards: [] };
-    return {
-        shards,
-        partition: {
-            durationMs: Date.now() - partitionStart,
-            detail: `${strategy}: ${String(shards.length)} partition(s)`,
-        },
-    };
-}
-/** Drive the sharded build and adapt it to the RunGraphResult dispatch shape. */
-async function runShardedBuild(ctx) {
-    const { opts, shards, projectRoot, cli, config, rules } = ctx;
-    const datastore = cli.scope.datastore();
-    const sharded = await runShardedGraph({
-        shards,
-        projectRoot,
-        cliScript: opts.cliScript ?? process.argv[1] ?? '',
-        adapter: pickAdapter(projectRoot, opts.language),
-        resolutionMode: opts.resolution ?? 'exact',
-        concurrency: opts.concurrency,
-        useCache: opts.noCache !== true,
-        config,
-        rules,
-        catalogRepo: datastore ? new CatalogRepo(datastore) : null,
-        emitFeatures: DASHBOARD_FEATURE_COLUMNS,
-        ...(ctx.onProgress === undefined ? {} : { onProgress: ctx.onProgress }),
-        ...(opts.language === undefined ? {} : { language: opts.language }),
-    });
-    return {
-        catalog: sharded.catalog,
-        indexes: sharded.indexes,
-        signals: sharded.signals,
-        resolutionStats: sharded.resolutionStats,
-        cacheHit: sharded.cacheHit,
-        features: sharded.features,
-        shardStats: sharded.shardStats,
-    };
-}
-async function runProfiledShardedBuild(profileRun, ctx) {
-    const started = Date.now();
-    const result = await runShardedBuild(ctx);
-    profileRun?.recordStage('sharded-build', Date.now() - started, `${String(ctx.shards.length)} shard(s)`);
-    return result;
-}
-/**
- * Resolve the build engine for the interactive live path — the SAME policy
- * `executeGraph` uses (ADR-0032): the SHARDED engine when `--exact` is absent
- * and the project yields >1 non-empty shard, the EXACT (single-program) engine
- * otherwise. Returns the shard set (`length > 1` ⇒ sharded) so the live runner
- * can choose engine-aware labels and pass the plain-data plan to
- * `graph-run-worker` (ADR-0028). `isTTY` is NEVER consulted — the engine is a
- * pure function of the request + shardability, identical to the static path.
- */
-export async function resolveLiveEngineShards(args, cli) {
-    const opts = {
-        cwd: args.cwd,
-        noCache: args.noCache,
-        resolution: args.resolution,
-        exact: args.exact,
-        ...(args.cliScript === undefined ? {} : { cliScript: args.cliScript }),
-    };
-    // No positional paths in the whole-project live view, so the engine decision
-    // is `--exact` + shardability alone.
-    const resolution = await resolveEngineShards(opts, cli, []);
-    return resolution.shards;
-}
-/**
- * Run the SHARDED live build and reduce it to the slim, serializable
- * {@link LiveGraphOutput} the interactive runner consumes — IDENTICAL in shape
- * to what the exact worker streams back, so live transports converge on one
- * payload. In the normal path this runs inside `graph-run-worker`, keeping the
- * render process free while the worker coordinates shard subprocesses and the
- * synchronous merge/link/rules work. The same function remains the degraded
- * in-process fallback when worker execution is explicitly disabled or unavailable.
- * Progress events flow through `onProgress`, mapped onto the same seven
- * canonical stages the exact engine emits.
- *
- * Crosses the single suppression chokepoint via {@link buildLiveGraphOutput}
- * (against `args.cwd`, the build root) — so the live sharded path waives
- * `@graph-ignore` directives IDENTICALLY to the static/exact paths (ADR-0014/0031).
- */
-export async function runShardedLiveBuild(args, shards, datastore, onProgress) {
-    const result = await runShardedGraph({
-        shards,
-        projectRoot: args.cwd,
-        cliScript: args.cliScript ?? process.argv[1] ?? '',
-        adapter: pickAdapter(args.cwd),
-        resolutionMode: args.resolution ?? 'exact',
-        useCache: args.noCache !== true,
-        config: args.config ?? {},
-        // The live dispatch always resolves the recipe → rules; fall back to the
-        // full registered set if a programmatic caller omits them (parity with the
-        // exact path, where `runGraph` applies the same `?? currentRules()` default).
-        rules: args.rules ?? currentRules(),
-        catalogRepo: datastore ? new CatalogRepo(datastore) : null,
-        emitFeatures: DASHBOARD_FEATURE_COLUMNS,
-        onProgress,
-    });
-    return buildLiveGraphOutput({
-        catalog: result.catalog,
-        indexes: result.indexes,
-        signals: result.signals,
-        cacheHit: result.cacheHit,
-    }, args.cwd);
-}
 /** Profile bucket for the run shape: workspace fan-out, multi-path, or single graph. */
 function profileMode(opts) {
     if (opts.workspace === true)
@@ -557,102 +180,6 @@ function writeProfileIfRequested(opts, profile) {
         output: outPath,
     });
 }
-function validateMutuallyExclusiveFlags(opts) {
-    if (opts.gateSave === true && opts.gateCompare === true) {
-        throw new ConfigurationError('--gate-save and --gate-compare are mutually exclusive.');
-    }
-    if (opts.workspace === true && (opts.paths?.length ?? 0) > 0) {
-        throw new ConfigurationError('--workspace and positional paths are mutually exclusive. Use one or the other.');
-    }
-    if (opts.workspace === true && (opts.gateSave === true || opts.gateCompare === true)) {
-        throw new ConfigurationError('--workspace and --gate-save/--gate-compare are mutually exclusive. ' +
-            'Gates and baselines apply to production code; --workspace intentionally scans the full project (including dependencies and test fixtures).');
-    }
-}
-function resolvePositionalScope(opts) {
-    if (!opts.paths || opts.paths.length === 0)
-        return [];
-    return resolvePositionalPaths(opts.paths, opts.cwd);
-}
-/**
- * D14 mixed policy. When `--language X` was specified and the run
- * discovered zero files matching that adapter, exit 2 with the
- * canonical error. Auto-detection paths (no `--language`) do NOT
- * trigger this check — a "zero files" outcome there is a valid
- * (non-error) state.
- */
-function enforceLanguageMismatchPolicy(opts, catalog, paths) {
-    if (typeof opts.language !== 'string' || opts.language.length === 0)
-        return;
-    const fileCount = catalog === null ? 0 : countFiles(catalog);
-    if (fileCount > 0)
-        return;
-    const pathLabel = paths.map((p) => positionalPathLabel(p, opts.cwd)).join(', ');
-    throw new ConfigurationError(`--language ${opts.language} matched 0 files under ${pathLabel}; check the flag or paths.`);
-}
-async function executeMultiPathGraph(ctx, paths) {
-    const { opts, cli, rules, startedAt, profile } = ctx;
-    const allSignals = [];
-    let combinedFiles = 0;
-    let totalSuppressed = 0;
-    let lastResult = null;
-    const config = loadGraphConfig(opts.cwd);
-    for (const p of paths) {
-        const profileRun = profile?.startRun({
-            label: positionalPathLabel(p, opts.cwd),
-            cwd: p,
-            mode: 'single-process',
-        });
-        const r = await runGraph({
-            cwd: p,
-            noCache: opts.noCache,
-            resolution: opts.resolution,
-            language: opts.language,
-            config,
-            rules,
-            datastore: cli.scope.datastore(),
-            emitFeatures: DASHBOARD_FEATURE_COLUMNS,
-            onProgress: profileRun?.onProgress,
-        });
-        profileRun?.finish(r);
-        lastResult = r;
-        // Each path's signals are relative to THAT path's root — so waive them
-        // against `p` here, before aggregating. A single post-aggregation pass
-        // (the old shape) could only use one base and would leak waivers for every
-        // path but one. Each per-path call crosses the single suppression
-        // chokepoint (finalizeGraphSignals); the aggregate is then re-branded once
-        // below via assertFinalizedAcrossBoundary (an assertion that every member
-        // was finalized, NOT a second suppression pass).
-        const finalized = await finalizeGraphSignals(r.signals, p);
-        totalSuppressed += finalized.suppressedCount;
-        allSignals.push(...finalized.signals);
-        if (r.catalog !== null)
-            combinedFiles += countFiles(r.catalog);
-    }
-    // D14: count files across every analyzed path. Zero files + a
-    // `--language` override → exit 2 with the canonical message.
-    if (typeof opts.language === 'string' && opts.language.length > 0 && combinedFiles === 0) {
-        throw new ConfigurationError(`--language ${opts.language} matched 0 files under ${paths.map((p) => positionalPathLabel(p, opts.cwd)).join(', ')}; check the flag or paths.`);
-    }
-    /* v8 ignore next */
-    if (lastResult === null)
-        return undefined;
-    const combined = {
-        catalog: lastResult.catalog,
-        indexes: lastResult.indexes,
-        signals: allSignals,
-        resolutionStats: lastResult.resolutionStats,
-        cacheHit: lastResult.cacheHit,
-        features: lastResult.features,
-    };
-    // `allSignals` is already waived per-path (each against its own root), so
-    // deliver directly — a second suppression pass would have no single correct
-    // root and risk re-resolving paths under the wrong base. Re-brand the
-    // aggregate FinalizedSignals (each member already crossed finalizeGraphSignals
-    // above) so deliverGraphResult's persist call gets the type it requires.
-    const finalizedAggregate = assertFinalizedAcrossBoundary(allSignals, totalSuppressed);
-    return await deliverGraphResult(opts, combined, cli, startedAt, finalizedAggregate);
-}
 /**
  * Assemble the run's {@link SignalEnvelope} from its raw engine signals
  * (ADR-0011). Centralises `runId`/`createdAt` resolution off the live scope so
@@ -839,198 +366,6 @@ async function renderGraphResult(opts, result, startedAt, cli) {
     });
     return envelope;
 }
-/**
- * `graph --workspace` — fan a graph run out across every workspace
- * unit returned by the adapters' `discoverWorkspaceUnits` hook. Per
- * spec D8b, polyglot repos aggregate units from EVERY detected
- * adapter (or the single adapter named by `--language`).
- */
-async function executeWorkspaceGraph(opts, cli, profile) {
-    const cliScript = opts.cliScript ?? process.argv[1];
-    if (typeof cliScript !== 'string' || cliScript.length === 0) {
-        throw new ConfigurationError('--workspace: could not determine the CLI entry script (process.argv[1] is empty).');
-    }
-    const adapters = resolveAdaptersForRun(opts, cli);
-    const units = await discoverPolyglotUnits(opts.cwd, adapters);
-    if (units.length === 0) {
-        const adapterLabel = adapters.map((a) => a.id).join(', ') || '(no language adapters available)';
-        throw new ConfigurationError(`--workspace: no workspace units detected for [${adapterLabel}]. Use 'opensip graph' for whole-project analysis.`);
-    }
-    const profileRun = profile?.startRun({
-        label: 'workspace',
-        cwd: opts.cwd,
-        mode: 'workspace',
-    });
-    // Internal per-run timer for the workspace REPORT artifact (durationMs in the
-    // JSON document / report header + the profile stage). NOT a session timestamp:
-    // the generic session row's timing is host-owned (host-owned-run-timing Phase
-    // 3), stamped from the host RunTimer after this handler returns.
-    const startedAt = Date.now();
-    const result = await runWorkspaceUnitsInParallel({
-        cwd: opts.cwd,
-        units,
-        cliScript,
-        concurrency: opts.concurrency,
-        noCache: opts.noCache,
-        resolution: opts.resolution,
-        recipe: opts.recipe,
-        ...(opts.language === undefined ? {} : { language: opts.language }),
-    });
-    const durationMs = Date.now() - startedAt;
-    profileRun?.recordStage('workspace-fanout', durationMs, `${String(units.length)} unit(s)`);
-    const allSignals = [];
-    for (const r of result.perUnit)
-        allSignals.push(...r.signals);
-    profileRun?.finishSummary({
-        cacheHit: false,
-        signals: allSignals.length,
-    });
-    // Build exactly one aggregate session contribution for the whole --workspace
-    // invocation (non-json path only). Matches the contract "one human-facing CLI
-    // invocation = one session" that fitness/sim already follow; the per-unit child
-    // processes don't contribute because they always run with --json (see
-    // dispatchGraphResult). The host run plane persists the returned `session`
-    // after this handler resolves — graph never writes the row itself
-    // (host-owned-run-timing Phase 3).
-    //
-    // Cloud signal sync (ADR-0008) is intentionally NOT emitted for --workspace
-    // (audit P1-2): the parent aggregates per-unit signals for the dashboard, not
-    // for the cloud, and the --json children skip emit to avoid fragmented
-    // per-unit batches. So the returned outcome carries a `session` but NO
-    // envelope. A whole-project `graph` run emits normally (the root's
-    // deliverSignals on the returned envelope).
-    let session;
-    if (opts.json === true) {
-        // ADR-0011: emit through the CLI seam, not process.stdout directly.
-        // cli.emitJson applies the same JSON.stringify(_, null, 2) + '\n'.
-        cli.emitJson(buildWorkspaceJsonDocument(result.perUnit, durationMs));
-    }
-    else {
-        await writeWorkspaceReport(result.perUnit, durationMs, cli);
-        session = buildWorkspaceSessionContribution(opts, allSignals);
-    }
-    // If any child failed to spawn or exited with an error, surface it
-    // as a runtime error. The parent itself succeeded if every child
-    // returned exit 0.
-    if (result.anyChildFailed) {
-        cli.setExitCode(EXIT_CODES.RUNTIME_ERROR);
-        process.stderr.write(`graph --workspace: at least one unit run failed; see per-unit output above.\n`);
-    }
-    else {
-        cli.setExitCode(EXIT_CODES.SUCCESS);
-    }
-    logger.info({
-        evt: EVT_GRAPH_COMPLETE,
-        module: MODULE_GRAPH_CLI,
-        units: result.perUnit.length,
-        findings: allSignals.length,
-        failed: result.anyChildFailed,
-        durationMs,
-    });
-    // The aggregate outcome carries the single session (non-json path) but NO
-    // envelope — the parent does not cloud-emit per-unit signals (audit P1-2).
-    // `undefined` on the --json carrier path keeps the host from persisting.
-    return session === undefined ? undefined : { session };
-}
-/**
- * Build the generic-session contribution for a single-process graph run from
- * the branded {@link FinalizedSignals} (host-owned-run-timing Phase 3). The
- * host run plane stamps timing + id and persists the row after the handler
- * returns — graph never writes the generic `StoredSession` itself.
- *
- * Takes the branded {@link FinalizedSignals} (not a raw `Signal[]`): the only
- * way to obtain one is to cross the single suppression chokepoint
- * (`finalizeGraphSignals`, or `assertFinalizedAcrossBoundary` after the worker
- * IPC boundary). This is the compile-time guardrail that makes the TTY-leak bug
- * un-regressable — a caller that hands raw, un-waived signals here does not
- * type-check, so the dashboard history can never record un-waived findings.
- *
- * The single-process path holds the raw engine signals (engine slugs), so the
- * session payload's per-rule keys are engine slugs directly.
- */
-function buildGraphSessionContribution(opts, finalized) {
-    return contributionFromSignals(opts, finalized.signals);
-}
-/**
- * Build the aggregate generic-session contribution for a `--workspace` run.
- *
- * Child envelopes carry Option-A-mapped OpenSIP rule IDs; reverse-map back to
- * engine slugs so the aggregate session payload's per-rule metric columns
- * (keyed on engine slugs in the dashboard) keep working — exactly what the old
- * `persistWorkspaceSession` did before handing off to the shared save.
- */
-function buildWorkspaceSessionContribution(opts, signals) {
-    const engineSignals = signals.map((s) => {
-        const ruleId = mapOpenSipRuleIdToEngineSlug(s.ruleId);
-        return { ...s, ruleId, source: ruleId };
-    });
-    return contributionFromSignals(opts, engineSignals);
-}
-/**
- * Shared contribution builder: derive graph's opaque session payload + the
- * generic verdict (`score`/`passed`) from a run's engine-slug `Signal[]`. The
- * payload is graph-owned detail (summary + rule-grouped per-signal findings);
- * the generic session row holds zero graph vocabulary. `score`/`passed` mirror
- * exactly what the former `saveGraphSession` computed (pass rate over
- * passed/total rules; `passed` ⇔ no error-severity signals).
- */
-/**
- * Engine slugs of every rule a run evaluated — the session payload's full rule
- * list, so a CLEAN run still records a PASS row per rule (the session detail
- * then shows the complete rule list, exactly the way fitness shows every check,
- * not just the failing ones).
- *
- * Prefer the EXPLICITLY-resolved rule set the run actually used (the `--recipe`
- * subset, threaded from the dispatch seam as `args.rules`); otherwise read the
- * current scope's full registry — this mirrors `runGraph`'s own
- * `args.rules ?? currentRules()` resolution, so the recorded set is exactly what
- * ran. Degrades to the empty set (fired-rules-only) when no graph scope is
- * active — e.g. an isolated dispatch unit test; production always runs the
- * handler inside the entered RunScope.
- *
- * Exported so BOTH contribution-building paths derive the evaluated set
- * identically: the static `executeGraph` dispatch (below) AND the live Ink
- * runner (`graph-runner.tsx`). Before it was shared, only the static path
- * threaded it, so a clean run on the live (interactive) path persisted an empty
- * `checks[]` and the report rendered "no results" instead of the rule list.
- */
-export function evaluatedRuleSlugs(explicitRules) {
-    if (explicitRules)
-        return explicitRules.map((r) => r.slug);
-    try {
-        return currentRules().map((r) => r.slug);
-    }
-    catch {
-        // @swallow-ok no graph scope (isolated dispatch unit test); degrade to the
-        // fired-rule set. Production always runs the handler inside a RunScope.
-        return [];
-    }
-}
-/**
- * Build graph's generic-session contribution from a run's engine-slug
- * `Signal[]` plus the engine slugs of the rules it evaluated. The SINGLE
- * assembly point for both the static dispatch path and the live Ink runner, so
- * the contribution shape (and the "every evaluated rule gets a row" behaviour)
- * can never drift between them again. The payload is graph-owned detail
- * (summary + rule-grouped per-signal findings); the generic session row holds
- * zero graph vocabulary. `score`/`passed` follow fit's semantics (pass rate over
- * passed/total rules; `passed` ⇔ no error-severity signal).
- *
- * `evaluatedSlugs` defaults to {@link evaluatedRuleSlugs}() (the scope's full
- * registry) for the static callers, which build inside the entered RunScope; the
- * live runner passes its `args.rules`-derived set explicitly.
- */
-export function contributionFromSignals(opts, signals, evaluatedSlugs = evaluatedRuleSlugs()) {
-    const payload = buildGraphSessionPayload(signals, evaluatedSlugs);
-    return {
-        tool: 'graph',
-        cwd: opts.cwd,
-        ...(opts.recipe === undefined ? {} : { recipe: opts.recipe }),
-        score: passRate(payload.summary),
-        passed: payload.summary.errors === 0,
-        payload,
-    };
-}
 export function handleGraphError(label, error, cli) {
     logger.error({
         evt: `graph.cli.${label}.error`,
@@ -1058,5 +393,7 @@ export function handleGraphError(label, error, cli) {
     }
     process.stderr.write(`${label}: ${error instanceof Error ? error.message : String(error)}\n`);
 }
+export { contributionFromSignals, evaluatedRuleSlugs } from './graph-session-contribution.js';
+export { resolveLiveEngineShards, resolveShardsForCwd, runShardedLiveBuild, } from './graph-sharded-engine.js';
 export { buildUnifiedReportLines, buildLiveGraphOutput } from './graph-report.js';
 //# sourceMappingURL=graph.js.map