@opensip-cli/graph 0.1.0

package/dist/cli/orchestrate/shard-model.js

@@ -0,0 +1,23 @@
+/**
+ * Shard model and the serializable worker-boundary contract.
+ *
+ * A sharded build splits a multi-package project into independent shards
+ * (one workspace package, one `--packages` unit, or one flat-monorepo
+ * partition), builds each in its own worker process, and merges the
+ * per-shard catalog fragments — recovering the cross-package edges the
+ * old fan-out modes silently dropped.
+ *
+ * The load-bearing constraint: a worker process cannot hand back a
+ * `ts.Node` / `ts.Program` (not structured-cloneable). So every type that
+ * crosses the worker boundary here is JSON-safe by construction — a
+ * primitive, an array, or a `Catalog` (already the plain shape persisted
+ * to the datastore today). The boundary carries DATA, never ASTs.
+ *
+ * Lifecycle:
+ *   discovery → Shard[]                      (workspace/packages/partition)
+ *   worker(Shard) → ShardBuildResult          (Phase 1, per process)
+ *   merge(fragments) + resolve(boundaryCalls) (Phase 2, main thread)
+ *   cache(fragment by shardId+fingerprint)    (Phase 3)
+ */
+export {};
+//# sourceMappingURL=shard-model.js.map

package/dist/cli/orchestrate/shard-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-model.js","sourceRoot":"","sources":["../../../src/cli/orchestrate/shard-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/cli/orchestrate/shard-runner.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shard runner — drives N shard workers in parallel and collects their
+ * serializable `ShardBuildResult` fragments.
+ *
+ * Each shard is built in its own child process (`graph-shard-worker`), so
+ * heap is isolated per shard: N shards × per-shard budget ≈ total budget,
+ * the same memory-scaling property the legacy `--workspace` runner has.
+ * Concurrency is capped at `cpus()-1` by default. A worker that exits
+ * non-zero is surfaced as a `ShardFailure` attributable to its shard id
+ * rather than aborting the whole build.
+ *
+ * The spec is handed to the worker via a temp FILE (not argv) because a
+ * shard can enumerate thousands of files, well past the OS argv limit.
+ */
+import type { Shard, ShardBuildResult } from './shard-model.js';
+import type { GraphLanguageAdapter } from '../../lang-adapter/types.js';
+import type { CatalogRepo } from '../../persistence/catalog-repo.js';
+import type { ResolutionMode } from '../../types.js';
+export interface RunShardsInput {
+    readonly shards: readonly Shard[];
+    /** Common project root — every fragment's filePaths resolve against it. */
+    readonly projectRoot: string;
+    /** CLI entry script (`process.argv[1]`); children run `node <cliScript> graph-shard-worker <spec>`. */
+    readonly cliScript: string;
+    /** Optional adapter id requested by the parent `graph --language <id>` run. */
+    readonly language?: string;
+    readonly resolutionMode: ResolutionMode;
+    /** Concurrency cap. Default: `max(1, cpus()-1)`. */
+    readonly concurrency?: number;
+}
+/** A shard whose worker exited non-zero — attributable, non-fatal. */
+export interface ShardFailure {
+    readonly shardId: string;
+    readonly exitCode: number;
+    readonly stderr: string;
+}
+export interface RunShardsOutput {
+    readonly fragments: readonly ShardBuildResult[];
+    readonly failures: readonly ShardFailure[];
+}
+/**
+ * Build every shard in a bounded parallel pool. Always resolves; per-shard
+ * failures are collected in `failures` (never thrown) so one bad shard
+ * doesn't sink the build.
+ */
+export declare function runShardsInParallel(input: RunShardsInput): Promise<RunShardsOutput>;
+/** Partition of a build's shards into reusable-from-cache vs needs-rebuild. */
+export interface ShardWorkPlan {
+    /** Fragments loaded verbatim from the per-shard cache — no worker runs. */
+    readonly cached: readonly ShardBuildResult[];
+    /** Shards whose files (or config/mode) changed — a worker must rebuild them. */
+    readonly toBuild: readonly Shard[];
+}
+/**
+ * Decide, per shard, whether its cached fragment is still valid (config
+ * key + files fingerprint match) and can be reused without a worker, or
+ * whether the shard must be rebuilt. This is the incremental-parse fix:
+ * unchanged shards skip parse entirely. With `useCache=false` (or no
+ * repo) every shard is rebuilt.
+ *
+ * Cheap by design — it stats each shard's files (fingerprint) and reads
+ * each shard's config (cacheKey); no parsing, no worker spawn.
+ */
+export declare function planShardWork(shards: readonly Shard[], repo: CatalogRepo | null, adapter: GraphLanguageAdapter, resolutionMode: ResolutionMode, useCache: boolean): ShardWorkPlan;
+//# sourceMappingURL=shard-runner.d.ts.map

package/dist/cli/orchestrate/shard-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-runner.d.ts","sourceRoot":"","sources":["../../../src/cli/orchestrate/shard-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAcH,OAAO,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAmB,MAAM,kBAAkB,CAAC;AACjF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uGAAuG;IACvG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,oDAAoD;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAoCzF;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,SAAS,KAAK,EAAE,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,IAAI,EAAE,WAAW,GAAG,IAAI,EACxB,OAAO,EAAE,oBAAoB,EAC7B,cAAc,EAAE,cAAc,EAC9B,QAAQ,EAAE,OAAO,GAChB,aAAa,CA2Bf"}

package/dist/cli/orchestrate/shard-runner.js

@@ -0,0 +1,169 @@
+/**
+ * Shard runner — drives N shard workers in parallel and collects their
+ * serializable `ShardBuildResult` fragments.
+ *
+ * Each shard is built in its own child process (`graph-shard-worker`), so
+ * heap is isolated per shard: N shards × per-shard budget ≈ total budget,
+ * the same memory-scaling property the legacy `--workspace` runner has.
+ * Concurrency is capped at `cpus()-1` by default. A worker that exits
+ * non-zero is surfaced as a `ShardFailure` attributable to its shard id
+ * rather than aborting the whole build.
+ *
+ * The spec is handed to the worker via a temp FILE (not argv) because a
+ * shard can enumerate thousands of files, well past the OS argv limit.
+ */
+import { spawn } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { cpus, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { currentTraceparent, logger } from '@opensip-cli/core';
+import { stampEngineVersion } from '../../cache/engine-version.js';
+import { computeFilesFingerprint } from '../../cache/invalidate.js';
+import { runWorkerPool } from './worker-pool.js';
+/**
+ * Build every shard in a bounded parallel pool. Always resolves; per-shard
+ * failures are collected in `failures` (never thrown) so one bad shard
+ * doesn't sink the build.
+ */
+export async function runShardsInParallel(input) {
+    const concurrency = Math.max(1, input.concurrency ?? Math.max(1, cpus().length - 1));
+    logger.info({
+        evt: 'graph.shard.runner.start',
+        module: 'graph:shard-runner',
+        shards: input.shards.length,
+        concurrency,
+    });
+    const outcomes = await runWorkerPool(input.shards, concurrency, (shard) => spawnShardWorker(shard, input.projectRoot, input.cliScript, input.resolutionMode, input.language));
+    const fragments = [];
+    const failures = [];
+    for (const o of outcomes) {
+        if (o.result)
+            fragments.push(o.result);
+        else
+            failures.push({ shardId: o.shardId, exitCode: o.exitCode, stderr: o.stderr });
+    }
+    // Deterministic order regardless of completion order.
+    fragments.sort((a, b) => Number(a.shardId > b.shardId) - Number(a.shardId < b.shardId));
+    failures.sort((a, b) => Number(a.shardId > b.shardId) - Number(a.shardId < b.shardId));
+    logger.info({
+        evt: 'graph.shard.runner.complete',
+        module: 'graph:shard-runner',
+        built: fragments.length,
+        failed: failures.length,
+    });
+    return { fragments, failures };
+}
+/**
+ * Decide, per shard, whether its cached fragment is still valid (config
+ * key + files fingerprint match) and can be reused without a worker, or
+ * whether the shard must be rebuilt. This is the incremental-parse fix:
+ * unchanged shards skip parse entirely. With `useCache=false` (or no
+ * repo) every shard is rebuilt.
+ *
+ * Cheap by design — it stats each shard's files (fingerprint) and reads
+ * each shard's config (cacheKey); no parsing, no worker spawn.
+ */
+export function planShardWork(shards, repo, adapter, resolutionMode, useCache) {
+    if (!useCache || !repo)
+        return { cached: [], toBuild: [...shards] };
+    const cached = [];
+    const toBuild = [];
+    for (const shard of shards) {
+        const cacheKey = stampEngineVersion(adapter.cacheKey({
+            projectDirAbs: shard.rootDir,
+            configPathAbs: shard.configPathAbs,
+            resolutionMode,
+        }), 
+        // Shard fragments only ever feed the sharded engine; stamp the mode so a
+        // fragment row can never be confused with a single-program (exact) build.
+        'sharded');
+        const fingerprint = computeFilesFingerprint(shard.files);
+        const fragment = repo.loadValidShardFragment(shard.id, cacheKey, fingerprint);
+        if (fragment)
+            cached.push(fragment);
+        else
+            toBuild.push(shard);
+    }
+    logger.info({
+        evt: 'graph.shard.plan',
+        module: 'graph:shard-runner',
+        reused: cached.length,
+        rebuild: toBuild.length,
+    });
+    return { cached, toBuild };
+}
+function spawnShardWorker(shard, projectRoot, cliScript, resolutionMode, language) {
+    return new Promise((resolvePromise) => {
+        const specDir = mkdtempSync(join(tmpdir(), 'graph-shard-'));
+        const specPath = join(specDir, 'spec.json');
+        const spec = {
+            shard,
+            projectRoot,
+            resolutionMode,
+            ...(language ? { language } : {}),
+        };
+        writeFileSync(specPath, JSON.stringify(spec), 'utf8');
+        const cleanup = () => rmSync(specDir, { recursive: true, force: true });
+        // Propagate the active trace context (the parent's sharded-build span) to
+        // the worker as TRACEPARENT, so the worker's per-stage spans nest under our
+        // build trace instead of forming orphan traces. `currentTraceparent()` is
+        // undefined for standalone runs (no SDK), so TRACEPARENT is simply absent
+        // and the worker emits no spans, exactly as before.
+        const traceparent = currentTraceparent();
+        // Inherit the PARENT's cwd (the opensip-cli project dir) so the
+        // child's CLI bootstrap resolves the project + adapter registry. The
+        // shard's own files are built from `shard.rootDir` in the spec, not from
+        // cwd — so the shard need not be a project itself. The full parent env is
+        // forwarded (the child needs PATH/HOME/OTEL_* etc.) into spawn's env option
+        // only — never logged.
+        const child = spawn(process.execPath, [cliScript, 'graph-shard-worker', specPath], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                ...(traceparent ? { TRACEPARENT: traceparent } : {}),
+            },
+        });
+        let stdout = '';
+        let stderr = '';
+        // setEncoding routes chunks through a StringDecoder that buffers
+        // partial multi-byte UTF-8 sequences across 'data' chunk boundaries.
+        // Without it, a non-ASCII char split across two chunks (likely for
+        // large fragments arriving in many chunks) decodes to replacement
+        // chars and corrupts the JSON parsed in the close handler.
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (c) => {
+            stdout += c;
+        });
+        child.stderr.on('data', (c) => {
+            stderr += c;
+        });
+        child.on('error', (err) => {
+            /* v8 ignore start */
+            cleanup();
+            resolvePromise({ shardId: shard.id, exitCode: -1, stderr: `spawn failed: ${err.message}` });
+            /* v8 ignore stop */
+        });
+        child.on('close', (code) => {
+            cleanup();
+            if (code !== 0) {
+                resolvePromise({ shardId: shard.id, exitCode: code ?? -1, stderr });
+                return;
+            }
+            try {
+                const result = JSON.parse(stdout);
+                resolvePromise({ shardId: shard.id, result, exitCode: 0, stderr });
+            }
+            catch (error) {
+                /* v8 ignore start */
+                resolvePromise({
+                    shardId: shard.id,
+                    exitCode: 1,
+                    stderr: `unparseable worker output: ${error instanceof Error ? error.message : String(error)}`,
+                });
+                /* v8 ignore stop */
+            }
+        });
+    });
+}
+//# sourceMappingURL=shard-runner.js.map

package/dist/cli/orchestrate/shard-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-runner.js","sourceRoot":"","sources":["../../../src/cli/orchestrate/shard-runner.ts"],"names":[],"mappings":"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"}

package/dist/cli/orchestrate/sharded-graph.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Sharded build pipeline (plan #2, Phase 4).
+ *
+ * Ties the shard substrate together into a single unified build:
+ *   plan (reuse cached fragments) → run changed shards in parallel →
+ *   merge fragments + recover cross-package edges → persist → derive
+ *   indexes + run rules → return the same RunGraphResult the
+ *   single-process path produces.
+ *
+ * The result's catalog is unified: intra-shard edges keep their original
+ * (semantic, in exact mode) fidelity; cross-package edges are recovered
+ * by the boundary pass and labeled `crossShard: true` / `'syntactic'`.
+ */
+import { type Signal } from '@opensip-cli/core';
+import type { Shard, ShardRunStats } from './shard-model.js';
+import type { GraphProgressCallback } from './types.js';
+import type { GraphLanguageAdapter } from '../../lang-adapter/types.js';
+import type { CatalogRepo } from '../../persistence/catalog-repo.js';
+import type { Catalog, FeatureColumn, FeatureTable, GraphConfig, Indexes, ResolutionMode, ResolutionStats, Rule } from '../../types.js';
+/**
+ * Input to {@link runShardedGraph}: the planned shards plus the shared build
+ * context (project root, worker entry script, language adapter, resolution
+ * tier, cache/persistence handles, and optional rules/config overrides).
+ */
+export interface RunShardedInput {
+    readonly shards: readonly Shard[];
+    /** Common project root — every fragment's filePaths resolve against it. */
+    readonly projectRoot: string;
+    /** CLI entry script (`process.argv[1]`) for spawning shard workers. */
+    readonly cliScript: string;
+    readonly adapter: GraphLanguageAdapter;
+    /** Optional adapter id requested by the parent `graph --language <id>` run. */
+    readonly language?: string;
+    readonly resolutionMode: ResolutionMode;
+    readonly concurrency?: number;
+    readonly useCache: boolean;
+    readonly catalogRepo: CatalogRepo | null;
+    readonly config?: GraphConfig;
+    readonly rules?: readonly Rule[];
+    /**
+     * Dashboard feature columns to materialize into the persisted catalog
+     * (ADR-0006). The sharded build is the producing run for multi-package
+     * repos, so it persists the same columns as the single path. Unioned with
+     * the rule set's `featureDeps`.
+     */
+    readonly emitFeatures?: readonly FeatureColumn[];
+    /**
+     * Optional structured progress callback (ADR-0032). The sharded build maps its
+     * work onto the SAME seven canonical {@link GraphStage}s the single-program
+     * (`runGraph`) path emits, so the live renderer (`graph-runner.tsx`) shows the
+     * identical "Code Graph" checklist for the sharded default and `--exact`:
+     *   - `discover` — total file count across all shards
+     *   - `parse`    — the parallel shard phase (sub-label: shard count)
+     *   - `walk`     — merge the per-shard fragments into the unified catalog
+     *   - `resolve`  — recover cross-package edges across shard boundaries
+     *   - `index`    — derive reverse indexes over the merged catalog
+     *   - `features` — derive the feature columns
+     *   - `rules`    — evaluate the rule set
+     * Non-interactive callers (json/gate/report) leave it undefined — a no-op.
+     */
+    readonly onProgress?: GraphProgressCallback;
+}
+/**
+ * Result of {@link runShardedGraph}: the unified catalog and derived indexes,
+ * the rule signals evaluated over it, cross-shard resolution stats, and
+ * cache/failure metadata (whether every shard was a cache hit, and the ids of
+ * any shards whose worker failed).
+ */
+export interface RunShardedResult {
+    readonly catalog: Catalog;
+    readonly indexes: Indexes;
+    readonly signals: readonly Signal[];
+    readonly resolutionStats: ResolutionStats;
+    /** True when every shard was reused from cache (no worker ran). */
+    readonly cacheHit: boolean;
+    /** Shard ids whose worker failed (build proceeds with the rest). */
+    readonly failedShardIds: readonly string[];
+    /** Engine-computed feature table over the merged global catalog (only the
+     *  requested columns populated). */
+    readonly features: FeatureTable;
+    /** Per-run sharded-build statistics (mirrored into the --profile summary). */
+    readonly shardStats: ShardRunStats;
+}
+/** Run the full sharded build and return a unified RunGraphResult-shaped value. */
+export declare function runShardedGraph(input: RunShardedInput): Promise<RunShardedResult>;
+//# sourceMappingURL=sharded-graph.d.ts.map

package/dist/cli/orchestrate/sharded-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharded-graph.d.ts","sourceRoot":"","sources":["../../../src/cli/orchestrate/sharded-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAA0C,KAAK,MAAM,EAAa,MAAM,mBAAmB,CAAC;AAqBnG,OAAO,KAAK,EAAE,KAAK,EAAoB,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,KAAK,EAAE,qBAAqB,EAAc,MAAM,YAAY,CAAC;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,YAAY,EACZ,WAAW,EACX,OAAO,EACP,cAAc,EACd,eAAe,EACf,IAAI,EACL,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACjD;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;wCACoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;CACpC;AAED,mFAAmF;AACnF,wBAAsB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAWvF"}

package/dist/cli/orchestrate/sharded-graph.js

@@ -0,0 +1,227 @@
+/**
+ * Sharded build pipeline (plan #2, Phase 4).
+ *
+ * Ties the shard substrate together into a single unified build:
+ *   plan (reuse cached fragments) → run changed shards in parallel →
+ *   merge fragments + recover cross-package edges → persist → derive
+ *   indexes + run rules → return the same RunGraphResult the
+ *   single-process path produces.
+ *
+ * The result's catalog is unified: intra-shard edges keep their original
+ * (semantic, in exact mode) fidelity; cross-package edges are recovered
+ * by the boundary pass and labeled `crossShard: true` / `'syntactic'`.
+ */
+import { logger, ValidationError, withSpanAsync } from '@opensip-cli/core';
+import { buildPackageManifestIndex } from '../../cross-package/export-index.js';
+import { unionFeatureDeps } from '../../pipeline/feature-deps.js';
+import { buildFeatures, isPersistedFeaturesEmpty, toPersistedFeatures, } from '../../pipeline/features.js';
+import { buildIndexes } from '../../pipeline/indexes.js';
+import { currentRules } from '../../rules/registry.js';
+import { GRAPH_TRACER } from '../graph-tracer.js';
+import { countCatalogCallSites, countCatalogFunctions } from './catalog-stats.js';
+import { mergeShardFragments, resolveCrossBoundaryCalls, stampAndConstrainPackages, } from './cross-shard-resolve.js';
+import { planShardWork, runShardsInParallel } from './shard-runner.js';
+/** Run the full sharded build and return a unified RunGraphResult-shaped value. */
+export async function runShardedGraph(input) {
+    // One parent span for the whole sharded build. withSpanAsync keeps it open
+    // across the awaited parallel work, so the per-shard worker spans — which
+    // inherit our context via the TRACEPARENT the runner propagates — nest under
+    // it instead of forming orphan traces. Hard no-op when no SDK is registered.
+    return withSpanAsync(GRAPH_TRACER, 'opensip_cli.graph.sharded_build', (span) => buildShardedGraph(input, span), { 'opensip_cli.graph.shard_count': input.shards.length });
+}
+async function buildShardedGraph(input, span) {
+    const { shards, projectRoot, cliScript, adapter, resolutionMode, useCache, catalogRepo } = input;
+    const onProgress = input.onProgress;
+    // 0. Fail loud on duplicate shard ids. The shard id is the per-shard
+    //    fragment-cache PRIMARY KEY (`graph_shard_fragment.shard_id`); two shards
+    //    sharing an id silently overwrite each other's cache row, so the warm
+    //    build never reaches a stable all-cached state and the function/entry-
+    //    point counts drift run-to-run. A duplicate id is a discovery bug (e.g. a
+    //    workspace-unit id derived by bare basename collapsing nested packages),
+    //    never a recoverable runtime condition — so we throw rather than return a
+    //    quietly-wrong graph.
+    // @fitness-ignore-next-line detached-promises -- assertUniqueShardIds is a synchronous void assertion (throws on a duplicate id); there is no promise to await.
+    assertUniqueShardIds(shards);
+    // The seven canonical stages, mapped onto the sharded work so the live view
+    // shows the same "Code Graph" checklist as the exact engine (ADR-0032). The
+    // file set is fixed before any phase runs (shards are pre-enumerated), so the
+    // `discover` stage is a zero-cost report of the partitioned total.
+    const allFiles = shards.flatMap((s) => s.files);
+    emitStageStart(onProgress, 'discover');
+    emitStage(onProgress, 'discover', 0, `${String(allFiles.length)} files`);
+    // 1. Decide which shards can be reused from cache vs must be rebuilt, then
+    //    2. build the changed shards in parallel worker processes. Both fold into
+    //    the `parse` stage (the heavy per-shard parse/walk/resolve runs inside the
+    //    subprocesses) — its sub-label reflects the shard count.
+    const parseStart = Date.now();
+    emitStageStart(onProgress, 'parse');
+    const plan = planShardWork(shards, catalogRepo, adapter, resolutionMode, useCache);
+    const built = await runShardsInParallel({
+        shards: plan.toBuild,
+        projectRoot,
+        cliScript,
+        resolutionMode,
+        concurrency: input.concurrency,
+        ...(input.language === undefined ? {} : { language: input.language }),
+    });
+    for (const failure of built.failures) {
+        logger.error({
+            evt: 'graph.sharded.shard_failed',
+            module: 'graph:sharded',
+            shardId: failure.shardId,
+            exitCode: failure.exitCode,
+            stderr: failure.stderr.slice(0, 500),
+        });
+    }
+    const shardWord = shards.length === 1 ? 'shard' : 'shards';
+    emitStage(onProgress, 'parse', Date.now() - parseStart, `${String(shards.length)} ${shardWord}`);
+    // 3a. Merge cached + freshly-built fragments — the `walk` stage. Mirrors the
+    //     single-program walk: it assembles the per-file occurrences into one
+    //     catalog, so its sub-label reports the resulting function count.
+    const fragments = [...plan.cached, ...built.fragments];
+    // The export linker keys packages by name; build the manifest index once from
+    // the resolved shard set (each shard.rootDir holds a package.json) so the
+    // boundary resolver can turn a bare specifier into a target package group.
+    const manifestIndex = buildPackageManifestIndex(shards, projectRoot);
+    const walkStart = Date.now();
+    emitStageStart(onProgress, 'walk');
+    const merged = mergeShardFragments(fragments.map((f) => f.fragment), allFiles);
+    emitStage(onProgress, 'walk', Date.now() - walkStart, `${String(countCatalogFunctions(merged))} functions`);
+    // 3b. Resolve the cross-shard boundary calls against the export index — graph's
+    //     main-thread analogue of the single-program `resolve` stage — then stamp
+    //     packages + drop name-guessed cross-package edges that contradict the import
+    //     graph (same correction as the single-program path). Timed for REAL (not a
+    //     hardcoded 0): the per-shard intra-package resolution already ran inside the
+    //     shard subprocesses (the `parse`/build-shards stage), so this stage is the
+    //     cross-package linking + constraint pass. Sub-label is the catalog-derived
+    //     resolved-call-site count, identical metric to the exact path.
+    const resolveStart = Date.now();
+    emitStageStart(onProgress, 'resolve');
+    const boundaryCalls = fragments.flatMap((f) => f.boundaryCalls);
+    const { catalog: resolved, boundaryStats } = resolveCrossBoundaryCalls(merged, boundaryCalls, manifestIndex);
+    const catalog = stampAndConstrainPackages(resolved, projectRoot);
+    emitStage(onProgress, 'resolve', Date.now() - resolveStart, `${String(countCatalogCallSites(catalog))} call site(s)`);
+    // 4. Derive indexes + features over the unified catalog. Features run once
+    //    here on the merged global catalog (not per shard), after merge / before
+    //    rules — the same stage order as the single-program path.
+    const indexStart = Date.now();
+    emitStageStart(onProgress, 'index');
+    const indexes = buildIndexes(catalog);
+    emitStage(onProgress, 'index', Date.now() - indexStart);
+    const ruleSet = input.rules ?? currentRules();
+    const config = input.config ?? {};
+    const requestedColumns = unionFeatureDeps(ruleSet, input.emitFeatures);
+    const featuresStart = Date.now();
+    emitStageStart(onProgress, 'features');
+    const features = buildFeatures(catalog, indexes, config, requestedColumns);
+    emitStage(onProgress, 'features', Date.now() - featuresStart);
+    const persistedFeatures = toPersistedFeatures(features, requestedColumns);
+    const persisted = isPersistedFeaturesEmpty(persistedFeatures) ? undefined : persistedFeatures;
+    // The catalog persisted (and returned) carries the materialized dashboard
+    // columns when requested; otherwise the bare catalog (lean default).
+    const catalogToPersist = persisted ? { ...catalog, features: persisted } : catalog;
+    // 5. Persist: each rebuilt shard's fragment, prune removed shards, and the
+    //    unified full catalog (with materialized features when requested) so
+    //    whole-catalog consumers (incl. the dashboard) still work.
+    if (useCache && catalogRepo) {
+        // @fitness-ignore-next-line detached-promises -- persistShardedCatalog is a synchronous void helper (better-sqlite3/Drizzle writes); there is no promise to await.
+        persistShardedCatalog(catalogRepo, built.fragments, shards, catalogToPersist);
+    }
+    // 6. Run rules over the unified catalog, threading the feature table (5th arg).
+    const rulesStart = Date.now();
+    emitStageStart(onProgress, 'rules');
+    const signals = [];
+    for (const rule of ruleSet) {
+        // Indexed append rather than spread-in-loop — avoids re-allocating the
+        // accumulator on every rule (O(n²)) over a potentially large rule set.
+        const ruleSignals = rule.evaluate(catalog, indexes, config, adapter.ruleHints, features);
+        for (const signal of ruleSignals)
+            signals.push(signal);
+    }
+    emitStage(onProgress, 'rules', Date.now() - rulesStart, `${String(ruleSet.length)} rule(s), ${String(signals.length)} signal(s)`);
+    span.setAttributes({
+        'opensip_cli.graph.shards_built': plan.toBuild.length,
+        'opensip_cli.graph.shards_cached': plan.cached.length,
+        'opensip_cli.graph.shards_failed': built.failures.length,
+    });
+    const shardStats = {
+        shardCount: shards.length,
+        shardsBuilt: plan.toBuild.length,
+        shardsCached: plan.cached.length,
+        shardSizes: shards.map((s) => s.files.length).sort((a, b) => b - a),
+        boundaryCallSites: boundaryCalls.length,
+    };
+    return {
+        catalog: catalogToPersist,
+        indexes,
+        signals,
+        resolutionStats: boundaryStats,
+        cacheHit: plan.toBuild.length === 0,
+        failedShardIds: built.failures.map((f) => f.shardId),
+        features,
+        shardStats,
+    };
+}
+/**
+ * Persist the rebuilt shard fragments, prune fragments for removed shards, and
+ * write the unified catalog — best-effort (a failed catalog write is logged, not
+ * thrown: the freshly-built result is returned regardless). Extracted so
+ * {@link buildShardedGraph} stays under the cognitive-complexity bound.
+ */
+function persistShardedCatalog(catalogRepo, builtFragments, shards, catalogToPersist) {
+    // @fitness-ignore-next-line detached-promises -- CatalogRepo is synchronous (better-sqlite3/Drizzle); upsertShardFragment returns void, not a Promise.
+    for (const fragment of builtFragments)
+        catalogRepo.upsertShardFragment(fragment);
+    // @fitness-ignore-next-line detached-promises -- CatalogRepo is synchronous (better-sqlite3/Drizzle); pruneShardFragmentsExcept returns void, not a Promise.
+    catalogRepo.pruneShardFragmentsExcept(shards.map((s) => s.id));
+    try {
+        catalogRepo.replaceAll(catalogToPersist);
+    }
+    catch (error) {
+        /* v8 ignore next */
+        // Best-effort write: the freshly-built catalog is returned regardless.
+        // replaceAll already logged the underlying error; note the continuation
+        // so the swallow isn't silent.
+        logger.debug({
+            evt: 'graph.sharded.cache_write_skipped',
+            module: 'graph:sharded',
+            err: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/** Emit a `stage-start` for `stage` (no-op when no callback). */
+function emitStageStart(onProgress, stage) {
+    onProgress?.({ type: 'stage-start', stage });
+}
+/** Emit a `stage-done` for `stage` with its duration + optional checklist detail. */
+function emitStage(onProgress, stage, durationMs, detail) {
+    onProgress?.({
+        type: 'stage-done',
+        stage,
+        durationMs,
+        ...(detail === undefined ? {} : { detail }),
+    });
+}
+/**
+ * Throw if any two shards share an id. The shard id is the per-shard
+ * fragment-cache primary key, so a collision corrupts the warm-build cache and
+ * makes the graph non-deterministic — a class of bug that must fail loud, never
+ * silently return a wrong graph. Lists the offending ids in the error.
+ */
+function assertUniqueShardIds(shards) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const shard of shards) {
+        if (seen.has(shard.id))
+            duplicates.add(shard.id);
+        seen.add(shard.id);
+    }
+    if (duplicates.size > 0) {
+        const ids = [...duplicates].sort().join(', ');
+        throw new ValidationError(`Duplicate shard id(s) [${ids}] in the sharded build — shard ids must be ` +
+            `unique (they are the per-shard fragment-cache primary key). This is a ` +
+            `workspace-unit discovery bug (e.g. ids derived by bare basename ` +
+            `collapsing nested packages); fix id derivation to be root-relative.`);
+    }
+}
+//# sourceMappingURL=sharded-graph.js.map

package/dist/cli/orchestrate/sharded-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharded-graph.js","sourceRoot":"","sources":["../../../src/cli/orchestrate/sharded-graph.ts"],"names":[],"mappings":"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"}

package/dist/cli/orchestrate/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared types for the graph orchestration pipeline. Extracted into a
+ * leaf module so the orchestrator (`../orchestrate.ts`) and its
+ * helpers (`cache-orchestrator.ts`, `catalog-builder.ts`) can all
+ * reference the same `GraphStage` / `GraphProgressCallback` shapes
+ * without forming a file-level cycle.
+ *
+ * Previously these lived in `../orchestrate.ts` and the helpers
+ * type-imported them back from there — closing a cycle the
+ * `circular-import-detection` check flagged. Hosting the types here
+ * inverts the dependency: the orchestrator and both helpers now
+ * import from this leaf, and nothing in this file imports back.
+ */
+/** Canonical pipeline stages, in execution order. */
+export type GraphStage = 'discover' | 'parse' | 'walk' | 'resolve' | 'index' | 'features' | 'rules';
+/** Stage order — consumed by the live view to render the checklist. */
+export declare const GRAPH_STAGES: readonly GraphStage[];
+/**
+ * Structured progress event. `stage-cached` fires for parse/walk/resolve
+ * when the on-disk catalog cache satisfies the run; the view renders
+ * those stages as "(cached)" instead of running them.
+ */
+export interface GraphProgressEvent {
+    readonly type: 'stage-start' | 'stage-done' | 'stage-cached';
+    readonly stage: GraphStage;
+    readonly durationMs?: number;
+    readonly detail?: string;
+}
+/** Callback invoked with each {@link GraphProgressEvent} during graph orchestration. */
+export type GraphProgressCallback = (event: GraphProgressEvent) => void;
+//# sourceMappingURL=types.d.ts.map