@opensip-cli/graph 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/cli/orchestrate/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,qDAAqD;AACrD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC;AAEpG,uEAAuE;AACvE,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAQ7C,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,GAAG,cAAc,CAAC;IAC7D,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wFAAwF;AACxF,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC"}

package/dist/cli/orchestrate/types.js

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+/** Stage order — consumed by the live view to render the checklist. */
+export const GRAPH_STAGES = [
+    'discover',
+    'parse',
+    'walk',
+    'resolve',
+    'index',
+    'features',
+    'rules',
+];
+//# sourceMappingURL=types.js.map

package/dist/cli/orchestrate/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/cli/orchestrate/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAA0B;IACjD,UAAU;IACV,OAAO;IACP,MAAM;IACN,SAAS;IACT,OAAO;IACP,UAAU;IACV,OAAO;CACR,CAAC"}

package/dist/cli/orchestrate/worker-pool.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A tiny fixed-size worker pool — the concurrency primitive shared by the
+ * shard runner and the legacy `--workspace` fan-out.
+ *
+ * Each of `concurrency` slots pulls the next item off a shared queue, runs
+ * `run(item)`, and repeats until the queue is empty. The cap bounds how
+ * many child processes run at once (memory/oversubscription control); the
+ * total number of items is unbounded.
+ *
+ * Results are returned in COMPLETION order, not input order — callers that
+ * need determinism sort afterward (shards sort by shardId).
+ *
+ * @throws {TypeError} When `concurrency` is not a finite number.
+ */
+export declare function runWorkerPool<I, O>(items: readonly I[], concurrency: number, run: (item: I) => Promise<O>): Promise<O[]>;
+//# sourceMappingURL=worker-pool.d.ts.map

package/dist/cli/orchestrate/worker-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-pool.d.ts","sourceRoot":"","sources":["../../../src/cli/orchestrate/worker-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,CAAC,EACtC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,EAAE,CAAC,CAyBd"}

package/dist/cli/orchestrate/worker-pool.js

@@ -0,0 +1,39 @@
+/**
+ * A tiny fixed-size worker pool — the concurrency primitive shared by the
+ * shard runner and the legacy `--workspace` fan-out.
+ *
+ * Each of `concurrency` slots pulls the next item off a shared queue, runs
+ * `run(item)`, and repeats until the queue is empty. The cap bounds how
+ * many child processes run at once (memory/oversubscription control); the
+ * total number of items is unbounded.
+ *
+ * Results are returned in COMPLETION order, not input order — callers that
+ * need determinism sort afterward (shards sort by shardId).
+ *
+ * @throws {TypeError} When `concurrency` is not a finite number.
+ */
+export async function runWorkerPool(items, concurrency, run) {
+    if (!Number.isFinite(concurrency)) {
+        throw new TypeError(`runWorkerPool: concurrency must be a finite number (received ${concurrency})`);
+    }
+    const queue = [...items];
+    const results = [];
+    // Clamp zero/negative to 1 to preserve prior tolerance (some callers/tests
+    // pass 0 expecting "at least one slot"); the dangerous case is NaN which
+    // previously produced zero workers and empty results.
+    const slots = Math.max(1, concurrency);
+    async function worker() {
+        for (;;) {
+            const item = queue.shift();
+            if (item === undefined)
+                return;
+            results.push(await run(item));
+        }
+    }
+    const workers = [];
+    for (let i = 0; i < slots; i++)
+        workers.push(worker());
+    await Promise.all(workers);
+    return results;
+}
+//# sourceMappingURL=worker-pool.js.map

package/dist/cli/orchestrate/worker-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-pool.js","sourceRoot":"","sources":["../../../src/cli/orchestrate/worker-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAmB,EACnB,WAAmB,EACnB,GAA4B;IAE5B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,SAAS,CACjB,gEAAgE,WAAW,GAAG,CAC/E,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IACzB,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,2EAA2E;IAC3E,yEAAyE;IACzE,sDAAsD;IACtD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAEvC,KAAK,UAAU,MAAM;QACnB,SAAS,CAAC;YACR,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;YAC3B,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO;YAC/B,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE;QAAE,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACvD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cli/orchestrate.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Pipeline orchestrator — threads stages 0–5 together.
+ *
+ * The single module that wires adapter outputs into the rule pipeline.
+ * Per spec §5, the orchestrator is straight-line code; every
+ * interesting decision happens inside one of the stages.
+ *
+ * PR 3 of plan docs/plans/10-graph-language-pluggability.md: this
+ * module no longer imports `'typescript'` directly. The orchestrator
+ * looks up an adapter from the lang-adapter registry and routes
+ * file-discovery / parse / walk / resolution through its method
+ * surface. The TypeScript adapter is the only one registered today;
+ * future adapters slot in via `currentAdapterRegistry().register(...)`
+ * at bootstrap.
+ *
+ * Stage decomposition (siblings under `./orchestrate/`):
+ *   - `catalog-builder.ts`    — full + incremental rebuild paths
+ *   - `cache-orchestrator.ts` — cache hit/miss/incremental routing
+ *   - `incremental-merge.ts`  — Wave-4 closure expansion + edge merge
+ * This file keeps `runGraph()` (entry), `runStage()` (the
+ * progress/pressure-monitor wrapper threaded into siblings), and the
+ * public type surface.
+ */
+import { type Signal } from '@opensip-cli/core';
+import type { Catalog, FeatureColumn, FeatureTable, GraphConfig, Indexes, ResolutionMode, ResolutionStats, Rule } from '../types.js';
+import type { ShardRunStats } from './orchestrate/shard-model.js';
+import type { GraphProgressCallback } from './orchestrate/types.js';
+import type { DataStore } from '@opensip-cli/datastore';
+export { GRAPH_STAGES } from './orchestrate/types.js';
+export type { GraphProgressCallback, GraphProgressEvent, GraphStage } from './orchestrate/types.js';
+export { runShardedGraph } from './orchestrate/sharded-graph.js';
+export { loadGraphConfig, resolveGraphRecipeSelection } from './graph-config.js';
+export type { RunShardedInput, RunShardedResult } from './orchestrate/sharded-graph.js';
+/** Input bundle for {@link runGraph}: project scope, optional overrides, and progress callback. */
+export interface RunGraphInput {
+    readonly cwd: string;
+    readonly noCache?: boolean;
+    readonly config?: GraphConfig;
+    /** Override the rule set (tests, custom invocations). */
+    readonly rules?: readonly Rule[];
+    /** Override the adapter's config-file path (e.g. tsconfig.json). */
+    readonly tsConfigPath?: string;
+    /**
+     * Optional canonical adapter id (`typescript`, `python`, `rust`,
+     * etc.). When set, bypasses `pickAdapter`'s file-extension dominance
+     * heuristic and selects the named adapter directly. The graph CLI
+     * surfaces this via the `--language` flag.
+     */
+    readonly language?: string;
+    /**
+     * Edge resolution tier. `'exact'` (default, or absent) runs the
+     * semantic type-checker-backed resolvers; `'fast'` runs the syntactic
+     * resolver with no type checker. Normalized to `'exact'` at the
+     * orchestrator boundary and folded into the cacheKey so the two tiers
+     * never collide in the catalog cache. Surfaced by the `--resolution`
+     * CLI flag.
+     */
+    readonly resolution?: ResolutionMode;
+    /**
+     * Optional structured progress callback. The orchestrator emits one
+     * `stage-start` + one of `stage-done` / `stage-cached` per pipeline
+     * stage (discover, parse, walk, resolve, index, rules). Used by the
+     * Ink live view; non-interactive callers (json/gate/report) leave it
+     * undefined.
+     */
+    readonly onProgress?: GraphProgressCallback;
+    /**
+     * Datastore for catalog persistence. v2: replaces the v1
+     * `paths.graphCatalogPath` JSON file. Optional so legacy callers
+     * (acceptance tests pre-Phase-3) can still drive the orchestrator
+     * without a DataStore — the catalog will be rebuilt every run.
+     */
+    readonly datastore?: DataStore;
+    /**
+     * Columns to materialize into the persisted catalog for the decoupled
+     * dashboard (ADR-0006). Absent/empty ⇒ no features persisted. The standard
+     * interactive run requests `['blast','scc','packageCoupling']`; export-only
+     * paths omit it. Unioned with every enabled rule's `featureDeps` to decide
+     * what the features stage computes.
+     */
+    readonly emitFeatures?: readonly FeatureColumn[];
+}
+/** Output of {@link runGraph}: catalog, indexes, signals, resolution stats, and cache state. */
+export interface RunGraphResult {
+    readonly catalog: Catalog | null;
+    readonly indexes: Indexes | null;
+    readonly signals: readonly Signal[];
+    readonly resolutionStats: ResolutionStats | null;
+    readonly cacheHit: boolean;
+    /** The engine-computed feature table for this run (only the requested
+     *  columns are populated). `null` only on a path that produced no catalog. */
+    readonly features: FeatureTable | null;
+    /**
+     * Per-run sharded-build statistics (ADR-0045 measurement plane), mirrored
+     * into the `--profile` summary. Present only on the sharded path; the exact
+     * (`runGraph`) single-program path leaves it undefined.
+     */
+    readonly shardStats?: ShardRunStats;
+}
+/**
+ * Run the pipeline end-to-end. Each stage runs in isolation; the
+ * orchestrator wires their outputs together and consults the cache
+ * before redoing stages 1+2.
+ */
+export declare function runGraph(input: RunGraphInput): Promise<RunGraphResult>;
+//# sourceMappingURL=orchestrate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate.d.ts","sourceRoot":"","sources":["../../src/cli/orchestrate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAmB/D,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,YAAY,EACZ,WAAW,EACX,OAAO,EACP,cAAc,EACd,eAAe,EACf,IAAI,EACL,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAUxD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAKpG,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACjF,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAExF,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CAClD;AAED,gGAAgG;AAChG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,eAAe,GAAG,IAAI,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;kFAC8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;CACrC;AAiDD;;;;GAIG;AAEH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CA2H5E"}

package/dist/cli/orchestrate.js

@@ -0,0 +1,228 @@
+// @fitness-ignore-file detached-promises -- stage hooks (registry registration, logger.info) are synchronous; orchestrator threads them inside an async pipeline
+// @fitness-ignore-file module-coupling-fan-out -- this IS the graph pipeline's composition root: threading stages 0–5 together inherently imports each stage module plus the registries/persistence/rules/tracer they coordinate. High fan-out is the orchestrator's job, not accidental coupling.
+/**
+ * Pipeline orchestrator — threads stages 0–5 together.
+ *
+ * The single module that wires adapter outputs into the rule pipeline.
+ * Per spec §5, the orchestrator is straight-line code; every
+ * interesting decision happens inside one of the stages.
+ *
+ * PR 3 of plan docs/plans/10-graph-language-pluggability.md: this
+ * module no longer imports `'typescript'` directly. The orchestrator
+ * looks up an adapter from the lang-adapter registry and routes
+ * file-discovery / parse / walk / resolution through its method
+ * surface. The TypeScript adapter is the only one registered today;
+ * future adapters slot in via `currentAdapterRegistry().register(...)`
+ * at bootstrap.
+ *
+ * Stage decomposition (siblings under `./orchestrate/`):
+ *   - `catalog-builder.ts`    — full + incremental rebuild paths
+ *   - `cache-orchestrator.ts` — cache hit/miss/incremental routing
+ *   - `incremental-merge.ts`  — Wave-4 closure expansion + edge merge
+ * This file keeps `runGraph()` (entry), `runStage()` (the
+ * progress/pressure-monitor wrapper threaded into siblings), and the
+ * public type surface.
+ */
+import { withSpanAsync } from '@opensip-cli/core';
+import { currentAdapterRegistry } from '../lang-adapter/registry.js';
+import { GraphAdapterSelector } from '../lang-adapter/selector.js';
+import { CatalogRepo } from '../persistence/catalog-repo.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 { obtainCatalog } from './orchestrate/cache-orchestrator.js';
+import { resolveCanonicalFileSet } from './orchestrate/canonical-file-set.js';
+import { createPressureMonitor } from './pressure-monitor.js';
+// Re-export the orchestration types so existing callers (the engine's
+// public `index.ts` barrel, the Ink live view, downstream tooling)
+// continue to import them from `./orchestrate.js`. The canonical
+// declarations now live in `./orchestrate/types.ts` — a leaf module
+// that the orchestrator's helpers (`cache-orchestrator`,
+// `catalog-builder`) also import from. The split breaks the
+// `orchestrate → cache-orchestrator → catalog-builder → orchestrate`
+// file-level cycle the `circular-import-detection` check flagged.
+export { GRAPH_STAGES } from './orchestrate/types.js';
+// The sharded build is an orchestration mode; expose it from the same
+// orchestration facade so dispatchers reach both `runGraph` and
+// `runShardedGraph` through one entry point.
+export { runShardedGraph } from './orchestrate/sharded-graph.js';
+export { loadGraphConfig, resolveGraphRecipeSelection } from './graph-config.js';
+/**
+ * Yield to the event loop once (a macrotask hop). Lets the in-process live view
+ * paint between/within stages so its spinner animates instead of freezing while
+ * a synchronous stage runs (ADR-0016, cooperative-yield). A no-op for cost in
+ * non-interactive runs (one `setImmediate` per stage is negligible).
+ */
+function yieldToEventLoop() {
+    return new Promise((resolve) => {
+        setImmediate(resolve);
+    });
+}
+async function runStage(args) {
+    const { stage, onProgress, monitor, fn, detailFn, attrsFn } = args;
+    monitor?.setStage(stage);
+    // Sample BEFORE the stage starts. The previous stage may have left
+    // the heap near the threshold; bail out before doing more work that
+    // would push us over and forfeit the ability to report cleanly.
+    monitor?.check();
+    onProgress?.({ type: 'stage-start', stage });
+    // Yield so the live view paints the stage-start (the spinner moves to this
+    // row) before a synchronous stage blocks the loop. The cooperative resolve
+    // stage yields again internally, so its spinner keeps ticking throughout.
+    await yieldToEventLoop();
+    const startedAt = Date.now();
+    // Emit one span per stage. withSpanAsync keeps the span open across the
+    // (possibly async) stage work and is a no-op when no SDK is registered.
+    const result = await withSpanAsync(GRAPH_TRACER, `opensip_cli.graph.${stage}`, async (span) => {
+        const out = await fn();
+        if (attrsFn)
+            span.setAttributes(attrsFn(out));
+        return out;
+    }, { 'opensip_cli.graph.stage': stage });
+    const durationMs = Date.now() - startedAt;
+    onProgress?.({
+        type: 'stage-done',
+        stage,
+        durationMs,
+        detail: detailFn?.(result),
+    });
+    return result;
+}
+/**
+ * Run the pipeline end-to-end. Each stage runs in isolation; the
+ * orchestrator wires their outputs together and consults the cache
+ * before redoing stages 1+2.
+ */
+export async function runGraph(input) {
+    const config = input.config ?? {};
+    const ruleSet = input.rules ?? currentRules();
+    const requestedColumns = unionFeatureDeps(ruleSet, input.emitFeatures);
+    const catalogRepo = input.datastore ? new CatalogRepo(input.datastore) : null;
+    // Normalize the tier once at the boundary; absence ⇒ exact (historical).
+    const resolutionMode = input.resolution ?? 'exact';
+    const monitor = createPressureMonitor();
+    try {
+        const adapter = pickAdapterFor(input);
+        const discovery = await runStage({
+            stage: 'discover',
+            onProgress: input.onProgress,
+            monitor,
+            // Reduce raw discovery to the CANONICAL file set (Phase 1, parity): the
+            // root tsconfig declares no exclude, so `discoverFiles` returns every
+            // `.ts(x)` — fixtures included. The sharded engine partitions the SAME
+            // canonical set, so both engines parse/walk an identical file set. Real
+            // test files are kept (needed for test-only-reachable + test→prod edges);
+            // only `__fixtures__/` (synthetic test input) is dropped.
+            fn: () => {
+                const raw = adapter.discoverFiles({
+                    cwd: input.cwd,
+                    configPathOverride: input.tsConfigPath,
+                });
+                return { ...raw, files: resolveCanonicalFileSet(raw.files) };
+            },
+            detailFn: (d) => `${String(d.files.length)} files`,
+            attrsFn: (d) => ({ 'opensip_cli.graph.file_count': d.files.length }),
+        });
+        const { catalog, cacheHit, resolutionStats } = await obtainCatalog({
+            runStage,
+            adapter,
+            discovery,
+            catalogRepo,
+            useCache: input.noCache !== true,
+            resolutionMode,
+            projectRoot: input.cwd,
+            onProgress: input.onProgress,
+            monitor,
+        });
+        const indexes = await runStage({
+            stage: 'index',
+            onProgress: input.onProgress,
+            monitor,
+            fn: () => buildIndexes(catalog),
+            // cacheHit is resolved by obtainCatalog (parse/walk/resolve) above, so it
+            // is known by the time the index stage runs. Surfacing it here gives the
+            // consumer a low-cardinality flag for "was this an incremental/cached run."
+            attrsFn: () => ({ 'opensip_cli.graph.cache_hit': cacheHit }),
+        });
+        // Stage 3.5 — feature derivation. Runs after index / before rules so rules
+        // consume the columns as a plain view (ADR-0006). Computes only the union
+        // of the rule set's featureDeps + the caller's emitFeatures.
+        const features = await runStage({
+            stage: 'features',
+            onProgress: input.onProgress,
+            monitor,
+            fn: () => buildFeatures(catalog, indexes, config, requestedColumns),
+            attrsFn: (f) => ({
+                'opensip_cli.graph.feature_columns': requestedColumns.length,
+                'opensip_cli.graph.scc_count': f.scc.length,
+            }),
+        });
+        const signals = await runStage({
+            stage: 'rules',
+            onProgress: input.onProgress,
+            monitor,
+            fn: () => {
+                const collected = [];
+                for (const rule of ruleSet) {
+                    // Thread the active adapter's RuleHints so non-TypeScript
+                    // languages get their own side-effect primitives, throw
+                    // syntax, generated-file globs, and isTestFile predicate.
+                    // Without this, rules that consult `hints` silently fall
+                    // back to TypeScript-shaped regex on every other language.
+                    // The 5th arg is the engine-computed feature table (Plan C).
+                    const out = rule.evaluate(catalog, indexes, config, adapter.ruleHints, features);
+                    collected.push(...out);
+                }
+                return collected;
+            },
+            detailFn: (sigs) => `${String(ruleSet.length)} rule(s), ${String(sigs.length)} signal(s)`,
+            attrsFn: (sigs) => ({
+                'opensip_cli.graph.rule_count': ruleSet.length,
+                'opensip_cli.graph.signal_count': sigs.length,
+            }),
+        });
+        // Materialize the requested dashboard columns into the persisted catalog
+        // (ADR-0006). obtainCatalog already wrote the feature-LESS catalog; a
+        // second persist attaches features ONLY when columns were requested and
+        // the projection is non-empty (a lean default-run persists no blob).
+        const persistedFeatures = toPersistedFeatures(features, requestedColumns);
+        const persisted = isPersistedFeaturesEmpty(persistedFeatures) ? undefined : persistedFeatures;
+        if (persisted && catalogRepo) {
+            try {
+                catalogRepo.replaceAll({ ...catalog, features: persisted });
+            }
+            catch {
+                /* v8 ignore next */
+                // @swallow-ok feature materialization is best-effort: CatalogRepo.replaceAll
+                // already logs the failure via its own logger, and the run returns the
+                // catalog (with in-memory features) regardless — re-logging here would
+                // only double-report the same error.
+            }
+        }
+        return {
+            catalog: persisted ? { ...catalog, features: persisted } : catalog,
+            indexes,
+            signals,
+            resolutionStats,
+            cacheHit,
+            features,
+        };
+    }
+    finally {
+        monitor.dispose();
+    }
+}
+/**
+ * Pick a graph language adapter for the run. When `language` is set, the
+ * selector fails immediately if that adapter is not registered; implicit runs
+ * still use file-extension dominance plus the deterministic fallback.
+ */
+function pickAdapterFor(input) {
+    return new GraphAdapterSelector(currentAdapterRegistry()).pick({
+        cwd: input.cwd,
+        language: input.language,
+    });
+}
+//# sourceMappingURL=orchestrate.js.map

package/dist/cli/orchestrate.js.map

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

package/dist/cli/positional-paths.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolve user-supplied positional paths to validated absolute paths
+ * for `opensip graph`. No glob expansion (the shell handles
+ * globs); no workspace-name shortcut (D10). Throws ConfigurationError
+ * on the first invalid input.
+ */
+/**
+ * Resolve user-supplied positional paths to validated absolute paths.
+ *
+ * Each input must be a path to an existing directory (file paths are
+ * deferred). Relative paths resolve against `cwd`. Throws
+ * `ConfigurationError` on the first invalid input.
+ *
+ * Returns paths in the original argument order.
+ */
+export declare function resolvePositionalPaths(paths: readonly string[], cwd: string): readonly string[];
+/**
+ * Produce a short display label for an absolute path — relative to
+ * `process.cwd()` when meaningfully shorter, otherwise the absolute
+ * path. Used in user-facing error messages and reports.
+ */
+export declare function positionalPathLabel(absPath: string, cwd?: string): string;
+//# sourceMappingURL=positional-paths.d.ts.map

package/dist/cli/positional-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"positional-paths.d.ts","sourceRoot":"","sources":["../../src/cli/positional-paths.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CA+B/F;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAKxF"}

package/dist/cli/positional-paths.js

@@ -0,0 +1,64 @@
+/**
+ * Resolve user-supplied positional paths to validated absolute paths
+ * for `opensip graph`. No glob expansion (the shell handles
+ * globs); no workspace-name shortcut (D10). Throws ConfigurationError
+ * on the first invalid input.
+ */
+import { existsSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { ConfigurationError, logger } from '@opensip-cli/core';
+const MODULE_GRAPH_CLI = 'graph:cli';
+/**
+ * Resolve user-supplied positional paths to validated absolute paths.
+ *
+ * Each input must be a path to an existing directory (file paths are
+ * deferred). Relative paths resolve against `cwd`. Throws
+ * `ConfigurationError` on the first invalid input.
+ *
+ * Returns paths in the original argument order.
+ */
+export function resolvePositionalPaths(paths, cwd) {
+    const out = [];
+    for (const p of paths) {
+        const trimmed = p.trim();
+        if (trimmed.length === 0) {
+            throw new ConfigurationError('Positional path is empty.');
+        }
+        const abs = isAbsolute(trimmed) ? trimmed : resolve(cwd, trimmed);
+        if (!existsSync(abs)) {
+            throw new ConfigurationError(`Path does not exist: '${p}' (resolved to ${abs}).`);
+        }
+        let isDir = false;
+        try {
+            isDir = statSync(abs).isDirectory();
+        }
+        catch {
+            /* v8 ignore next */
+            throw new ConfigurationError(`Path is not readable: '${p}' (${abs}).`);
+        }
+        if (!isDir) {
+            throw new ConfigurationError(`Path is not a directory: '${p}'. graph accepts directories only.`);
+        }
+        out.push(abs);
+    }
+    logger.info({
+        evt: 'graph.cli.scope.positional',
+        module: MODULE_GRAPH_CLI,
+        count: out.length,
+    });
+    return out;
+}
+/**
+ * Produce a short display label for an absolute path — relative to
+ * `process.cwd()` when meaningfully shorter, otherwise the absolute
+ * path. Used in user-facing error messages and reports.
+ */
+export function positionalPathLabel(absPath, cwd = process.cwd()) {
+    const rel = relative(cwd, absPath);
+    if (rel.length === 0)
+        return '.';
+    if (!rel.startsWith('..') && !isAbsolute(rel))
+        return rel;
+    return absPath;
+}
+//# sourceMappingURL=positional-paths.js.map

package/dist/cli/positional-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"positional-paths.js","sourceRoot":"","sources":["../../src/cli/positional-paths.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE/D,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAwB,EAAE,GAAW;IAC1E,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,kBAAkB,CAAC,2BAA2B,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAClE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,kBAAkB,CAAC,yBAAyB,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;QACpF,CAAC;QACD,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,IAAI,CAAC;YACH,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,oBAAoB;YACpB,MAAM,IAAI,kBAAkB,CAAC,0BAA0B,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,kBAAkB,CAC1B,6BAA6B,CAAC,oCAAoC,CACnE,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,CAAC;IACD,MAAM,CAAC,IAAI,CAAC;QACV,GAAG,EAAE,4BAA4B;QACjC,MAAM,EAAE,gBAAgB;QACxB,KAAK,EAAE,GAAG,CAAC,MAAM;KAClB,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE;IAC9E,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACnC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACjC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAC1D,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cli/pressure-monitor.d.ts

@@ -0,0 +1,62 @@
+/**
+ * V8 heap pressure monitor.
+ *
+ * Polls `v8.getHeapStatistics()` to catch impending OOMs before V8
+ * itself SIGABRTs the process. The orchestrator calls `check()` at
+ * every stage boundary; for long-running stages the monitor also
+ * self-polls on a 1s interval. When old-gen usage crosses the
+ * configured fraction of the heap limit, `check()` throws
+ * `MemoryPressureError` and the orchestrator surfaces it through the
+ * normal error path.
+ *
+ * The 0.90 default leaves ~10% of headroom for V8 to complete one
+ * last major GC and for the exception to propagate. Below 0.85 we'd
+ * get false positives during normal GC churn; above 0.95 the bail-out
+ * itself runs out of headroom.
+ */
+import { ToolError, type EnvVarSpec, type ToolErrorOptions } from '@opensip-cli/core';
+/**
+ * Graph-engine environment variables (launch, §5.12). Read through the
+ * {@link EnvRegistry} primitive (immutable spec table) so the env surface is
+ * governed and documentable; the `env-via-registry` guardrail forbids raw
+ * `process.env` reads. (`NODE_OPTIONS`, mutated by the heap-preflight before any
+ * opensip module loads, is a documented pre-scope exception, not registered here.)
+ */
+export declare const GRAPH_ENV_SPECS: readonly EnvVarSpec<unknown>[];
+/** Thrown when heap usage crosses the configured pressure threshold during graph work. */
+export declare class MemoryPressureError extends ToolError {
+    readonly usedBytes: number;
+    readonly limitBytes: number;
+    readonly stage: string;
+    constructor(message: string, details: {
+        usedBytes: number;
+        limitBytes: number;
+        stage: string;
+    }, options?: ToolErrorOptions);
+}
+/** Constructor options for {@link createPressureMonitor}: threshold and poll cadence. */
+export interface PressureMonitorOptions {
+    /** Fraction of `heap_size_limit` above which we abort. Default 0.90. */
+    readonly threshold?: number;
+    /** Background poll interval. 0 disables polling (check-only mode). */
+    readonly pollIntervalMs?: number;
+}
+/** Stage-aware heap-pressure monitor that aborts work before the V8 OOM line. */
+export interface PressureMonitor {
+    /**
+     * Bind the monitor to a logical stage. Subsequent `check()` calls and
+     * background polls report this stage in any thrown error.
+     */
+    readonly setStage: (stage: string) => void;
+    /** Synchronous check — throws MemoryPressureError if over threshold. */
+    readonly check: () => void;
+    /** Stop the background poller. Safe to call multiple times. */
+    readonly dispose: () => void;
+}
+/**
+ * Create a pressure monitor. Disabled when `OPENSIP_HEAP_NO_MONITOR=1`
+ * — gives users an escape hatch for false positives in unusual GC
+ * scenarios (REPL embedding, custom allocators).
+ */
+export declare function createPressureMonitor(opts?: PressureMonitorOptions): PressureMonitor;
+//# sourceMappingURL=pressure-monitor.d.ts.map

package/dist/cli/pressure-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pressure-monitor.d.ts","sourceRoot":"","sources":["../../src/cli/pressure-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAe,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,UAAU,CAAC,OAAO,CAAC,EAOzD,CAAC;AAMF,0FAA0F;AAC1F,qBAAa,mBAAoB,SAAQ,SAAS;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAGrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EACjE,OAAO,CAAC,EAAE,gBAAgB;CAQ7B;AAED,yFAAyF;AACzF,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,sBAA2B,GAAG,eAAe,CAiDxF"}