@opensip-cli/graph 0.1.5 → 0.1.7

package/dist/cli/orchestrate/__tests__/shard-runner-correlation.test.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shard runner — the spawn-path CORRELATION + failure-taxonomy contract
+ * (subprocess-correlation telemetry spec, Phase 1). Drives REAL child processes
+ * via a fixture "CLI" worker (the same harness pattern as `shard-runner-spawn`):
+ *
+ *   - the worker inherits the PARENT run via `OPENSIP_RUN_ID` env (B1) — the spec
+ *     JSON carries `correlation` WITHOUT `runId`, and the child sees the parent's
+ *     `OPENSIP_RUN_ID` in its env;
+ *   - a non-zero exit yields a `ShardFailure { failureClass: 'exit_nonzero' }` and
+ *     a structured `graph.shard.runner.shard_failed` event whose `stderrPreview`
+ *     is capped at 500 chars while the returned `ShardFailure.stderr` stays FULL
+ *     (M4);
+ *   - a hung shard past a SHORT injected kill-timeout settles as
+ *     `failureClass: 'timeout'` (M3) — never an indefinite hang;
+ *   - an OLD-build spec WITHOUT a `correlation` field still builds (wire-compat,
+ *     GAP a) — the worker tolerates `spec.correlation === undefined`.
+ *
+ * The fixture echoes the env + spec it saw back through its stdout JSON so the
+ * test can assert what the runner forwarded without standing up a real build.
+ */
+export {};
+//# sourceMappingURL=shard-runner-correlation.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shard-runner-correlation.test.d.ts","sourceRoot":"","sources":["../../../../src/cli/orchestrate/__tests__/shard-runner-correlation.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/dist/cli/orchestrate/__tests__/shard-runner-correlation.test.js

@@ -0,0 +1,208 @@
+/**
+ * Shard runner — the spawn-path CORRELATION + failure-taxonomy contract
+ * (subprocess-correlation telemetry spec, Phase 1). Drives REAL child processes
+ * via a fixture "CLI" worker (the same harness pattern as `shard-runner-spawn`):
+ *
+ *   - the worker inherits the PARENT run via `OPENSIP_RUN_ID` env (B1) — the spec
+ *     JSON carries `correlation` WITHOUT `runId`, and the child sees the parent's
+ *     `OPENSIP_RUN_ID` in its env;
+ *   - a non-zero exit yields a `ShardFailure { failureClass: 'exit_nonzero' }` and
+ *     a structured `graph.shard.runner.shard_failed` event whose `stderrPreview`
+ *     is capped at 500 chars while the returned `ShardFailure.stderr` stays FULL
+ *     (M4);
+ *   - a hung shard past a SHORT injected kill-timeout settles as
+ *     `failureClass: 'timeout'` (M3) — never an indefinite hang;
+ *   - an OLD-build spec WITHOUT a `correlation` field still builds (wire-compat,
+ *     GAP a) — the worker tolerates `spec.correlation === undefined`.
+ *
+ * The fixture echoes the env + spec it saw back through its stdout JSON so the
+ * test can assert what the runner forwarded without standing up a real build.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { configureLogger, RunScope, runWithScope } from '@opensip-cli/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { runShardsInParallel } from '../shard-runner.js';
+// The fixture worker, invoked as `node <script> graph-shard-worker <specPath>`.
+//  - `fail:<id>`  → exit 3 with a LONG stderr (proves the 500-char preview cap
+//                   while the full stderr survives on the ShardFailure).
+//  - `sleep:<id>` → sleep well past the injected short kill-timeout (proves M3).
+//  - anything else → emit a ShardBuildResult whose `fragment.cacheKey` carries an
+//    env+spec snapshot: the OPENSIP_RUN_ID the child saw and whether the spec had
+//    a `correlation` (and, if so, its runId-stripped shape).
+const WORKER_SCRIPT = String.raw `
+const { readFileSync } = require('node:fs');
+const specPath = process.argv[3];
+const spec = JSON.parse(readFileSync(specPath, 'utf8'));
+const id = spec.shard.id;
+if (id.startsWith('fail:')) {
+  process.stderr.write('boom '.repeat(200) + 'for ' + id + '\n');
+  process.exit(3);
+}
+if (id.startsWith('sleep:')) {
+  // Hang past the injected short kill-timeout; the parent SIGKILLs us.
+  setTimeout(() => process.exit(0), 60_000);
+  return;
+}
+const snapshot = {
+  runIdEnv: process.env.OPENSIP_RUN_ID ?? null,
+  specHasCorrelation: spec.correlation !== undefined,
+  specCorrelation: spec.correlation ?? null,
+};
+const result = {
+  shardId: id,
+  fragment: {
+    version: '3.0', tool: 'graph', language: spec.language ?? 'typescript',
+    builtAt: 'x', cacheKey: JSON.stringify(snapshot), resolutionMode: 'exact', functions: {},
+  },
+  fingerprint: 'fp-' + id,
+  boundaryCalls: [],
+  parseErrors: [],
+};
+process.stdout.write(JSON.stringify(result));
+process.exit(0);
+`;
+const PARENT_CORRELATION = {
+    runId: 'RUN_test',
+    tool: 'graph',
+    parentCommand: 'graph',
+    repo: '/work/acme',
+};
+describe('runShardsInParallel — spawn-path correlation + failure taxonomy', () => {
+    let dir;
+    let cliScript;
+    const stderrCalls = [];
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'shard-corr-'));
+        cliScript = join(dir, 'fake-cli.cjs');
+        writeFileSync(cliScript, WORKER_SCRIPT, 'utf8');
+        stderrCalls.length = 0;
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+        vi.restoreAllMocks();
+        // Restore the singleton logger to its quiet default so capture state can't
+        // leak into sibling suites.
+        configureLogger({ debugMode: false, silent: true, runId: '' });
+    });
+    function shard(id) {
+        return { id, rootDir: dir, files: [join(dir, `${id}.ts`)] };
+    }
+    /**
+     * Capture the singleton logger's JSONL by enabling stderr output (the runner
+     * emits through the imported `logger` singleton) and routing stderr through a
+     * spy. `silent: false` + `debugMode: true` is the only mode in which the
+     * singleton writes its structured lines to stderr (the SAME gate the
+     * run-id-log-isolation test uses).
+     */
+    function captureLogs() {
+        vi.spyOn(process.stderr, 'write').mockImplementation((chunk) => {
+            stderrCalls.push(String(chunk));
+            return true;
+        });
+        configureLogger({ debugMode: true, silent: false, runId: '' });
+    }
+    function loggedEvents(evt) {
+        return stderrCalls
+            .flatMap((c) => c.split('\n'))
+            .filter((line) => line.trim().length > 0)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return {};
+            }
+        })
+            .filter((e) => e.evt === evt);
+    }
+    /** Run the pool inside a scope carrying the parent correlation bag. */
+    function runWithCorrelation(shards, opts = {}) {
+        const scope = new RunScope({
+            runId: PARENT_CORRELATION.runId,
+            correlation: PARENT_CORRELATION,
+        });
+        return runWithScope(scope, () => runShardsInParallel({
+            shards: [...shards],
+            projectRoot: dir,
+            cliScript,
+            resolutionMode: 'exact',
+            ...(opts.hardKillTimeoutMs === undefined
+                ? {}
+                : { hardKillTimeoutMs: opts.hardKillTimeoutMs }),
+        }));
+    }
+    it('forwards OPENSIP_RUN_ID to the child (B1) and writes correlation sans runId into the spec', async () => {
+        const out = await runWithCorrelation([shard('pkg:a')]);
+        expect(out.failures).toHaveLength(0);
+        const snap = JSON.parse(out.fragments[0].fragment.cacheKey);
+        // The child inherited the PARENT run via env (B1) — not via the spec JSON.
+        expect(snap.runIdEnv).toBe('RUN_test');
+        // The spec carries correlation, but NOT runId (it is env-only).
+        expect(snap.specHasCorrelation).toBe(true);
+        expect(snap.specCorrelation).not.toBeNull();
+        expect(snap.specCorrelation).not.toHaveProperty('runId');
+        // The rest of the bag rode along in the spec, plus this shard's id/workerKind.
+        expect(snap.specCorrelation?.tool).toBe('graph');
+        expect(snap.specCorrelation?.parentCommand).toBe('graph');
+        expect(snap.specCorrelation?.shardId).toBe('pkg:a');
+        expect(snap.specCorrelation?.workerKind).toBe('shard');
+    });
+    it('emits graph.shard.runner.shard_failed (exit_nonzero) with a ≤500-char preview; full stderr untruncated (M4)', async () => {
+        captureLogs();
+        const out = await runWithCorrelation([shard('fail:x')]);
+        expect(out.failures).toHaveLength(1);
+        const failure = out.failures[0];
+        expect(failure.shardId).toBe('fail:x');
+        expect(failure.exitCode).toBe(3);
+        expect(failure.failureClass).toBe('exit_nonzero');
+        // The returned ShardFailure.stderr is the FULL captured output (M4): the
+        // fixture writes ~1000 chars of 'boom ' — well over the 500-char preview cap.
+        expect(failure.stderr.length).toBeGreaterThan(500);
+        expect(failure.stderr).toContain('for fail:x');
+        const [event] = loggedEvents('graph.shard.runner.shard_failed');
+        expect(event).toBeDefined();
+        expect(event?.shardId).toBe('fail:x');
+        expect(event?.exitCode).toBe(3);
+        expect(event?.failureClass).toBe('exit_nonzero');
+        expect(event?.runId).toBe('RUN_test');
+        // The structured event's preview is independently capped at 500 chars.
+        expect((event?.stderrPreview ?? '').length).toBeLessThanOrEqual(500);
+    });
+    it('kills a hung shard at the injected timeout → failureClass timeout (M3)', async () => {
+        captureLogs();
+        // A 200ms injected kill-timeout: the fixture sleeps 60s, so the parent must
+        // SIGKILL it and settle as `timeout` — the test itself completes far under
+        // the 10-minute production default (proving no indefinite hang).
+        const out = await runWithCorrelation([shard('sleep:hang')], { hardKillTimeoutMs: 200 });
+        expect(out.fragments).toHaveLength(0);
+        expect(out.failures).toHaveLength(1);
+        expect(out.failures[0]?.shardId).toBe('sleep:hang');
+        expect(out.failures[0]?.failureClass).toBe('timeout');
+        expect(out.failures[0]?.stderr).toContain('hard kill-timeout');
+        const [event] = loggedEvents('graph.shard.runner.shard_failed');
+        expect(event?.failureClass).toBe('timeout');
+        expect(event?.shardId).toBe('sleep:hang');
+    }, 15_000);
+    it('builds a spec WITHOUT a correlation field (wire-compat, GAP a) — no throw, valid result', async () => {
+        // Run OUTSIDE any scope correlation: spawnShardWorker reads
+        // currentScope()?.correlation === undefined, so the spec omits `correlation`
+        // entirely. The worker must tolerate that and still produce a ShardBuildResult.
+        const out = await runShardsInParallel({
+            shards: [shard('pkg:nocorr')],
+            projectRoot: dir,
+            cliScript,
+            resolutionMode: 'exact',
+        });
+        expect(out.failures).toHaveLength(0);
+        expect(out.fragments).toHaveLength(1);
+        const snap = JSON.parse(out.fragments[0].fragment.cacheKey);
+        // GAP a: no scope correlation ⇒ the runner omits `correlation` from the spec,
+        // and the worker tolerates `spec.correlation === undefined` (no throw — proven
+        // by the valid ShardBuildResult above).
+        expect(snap.specHasCorrelation).toBe(false);
+        expect(snap.specCorrelation).toBeNull();
+    });
+});
+//# sourceMappingURL=shard-runner-correlation.test.js.map

package/dist/cli/orchestrate/__tests__/shard-runner-correlation.test.js.map

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

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

@@ -20,6 +20,7 @@
  *   cache(fragment by shardId+fingerprint)    (Phase 3)
  */
 import type { Catalog, CrossBoundaryCall, ParseError, ResolutionMode } from '../../types.js';
+import type { RunCorrelation } from '@opensip-cli/core';
 /**
  * One parallelizable unit of a sharded build. The discovery strategies
  * (workspace units, flat-monorepo partitions) map their output onto this
@@ -62,6 +63,22 @@ export interface ShardWorkerSpec {
     /** Optional adapter id requested by the parent `graph --language <id>` run. */
     readonly language?: string;
     readonly resolutionMode: ResolutionMode;
+    /**
+     * OPTIONAL correlation bag forwarded from the parent run so the shard worker
+     * can stamp `tool`/`parentCommand`/`traceId`/`shardId` on its spans and logs
+     * (subprocess-correlation telemetry spec, Phase 1).
+     *
+     * Wire-compat seam: this field is OPTIONAL on purpose. A mismatched
+     * parent↔worker build during a partial upgrade — an old worker reading a new
+     * spec, or a new worker reading an old spec — MUST NOT break. A required field
+     * would. If a hard contract is ever needed, version the envelope with a
+     * `specVersion` field rather than making this required.
+     *
+     * `runId` is deliberately EXCLUDED (`Omit<…, 'runId'>`): it travels via the
+     * `OPENSIP_RUN_ID` env ONLY (B1), inherited at the worker's pre-action hook
+     * before any spec JSON is parsed.
+     */
+    readonly correlation?: Omit<RunCorrelation, 'runId'>;
 }
 /**
  * The serializable result one shard worker returns. JSON-safe by

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

@@ -1 +1 @@
-{"version":3,"file":"shard-model.d.ts","sourceRoot":"","sources":["../../../src/cli/orchestrate/shard-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE7F;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yGAAyG;IACzG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;CAC7C;AAED;kEACkE;AAClE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,kEAAkE;IAClE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC"}
+{"version":3,"file":"shard-model.d.ts","sourceRoot":"","sources":["../../../src/cli/orchestrate/shard-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yGAAyG;IACzG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;CACtD;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;CAC7C;AAED;kEACkE;AAClE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,kEAAkE;IAClE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC"}

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

@@ -16,6 +16,19 @@ 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';
+/**
+ * The machine-filterable failure taxonomy for a shard worker, stamped on the
+ * parent's `graph.shard.runner.shard_failed` event (subprocess-correlation
+ * telemetry spec, Failure taxonomy). Every value is LIVE — `timeout` became
+ * emittable with the hard kill-timeout below (M3); there is no dead enum value.
+ *
+ *   - `spawn`         — the child process failed to spawn (`child.on('error')`).
+ *   - `exit_nonzero`  — the child spawned but exited with a non-zero code.
+ *   - `stdout_parse`  — the child exited 0 but its stdout was not valid JSON.
+ *   - `timeout`       — the hard kill-timeout fired and SIGKILLed a hung child.
+ *   - `ipc_error`     — reserved for the fork (live-engine) transport (Phase 2).
+ */
+export type FailureClass = 'spawn' | 'exit_nonzero' | 'stdout_parse' | 'timeout' | 'ipc_error';
 export interface RunShardsInput {
     readonly shards: readonly Shard[];
     /** Common project root — every fragment's filePaths resolve against it. */
@@ -27,12 +40,29 @@ export interface RunShardsInput {
     readonly resolutionMode: ResolutionMode;
     /** Concurrency cap. Default: `max(1, cpus()-1)`. */
     readonly concurrency?: number;
+    /**
+     * Hard wall-clock kill-timeout (ms) after which a hung shard worker is
+     * SIGKILLed with `failureClass: 'timeout'` (M3). Defaults to
+     * {@link SHARD_HARD_KILL_TIMEOUT_MS} (10 min) — the conservative production
+     * floor. Exposed as an input ONLY so the timeout path is deterministically
+     * exercisable in tests with a short value (the resilience spec, Q3/M3, will
+     * later make it user-configurable); production never sets it.
+     */
+    readonly hardKillTimeoutMs?: number;
 }
-/** A shard whose worker exited non-zero — attributable, non-fatal. */
+/** A shard whose worker failed — attributable, non-fatal. */
 export interface ShardFailure {
     readonly shardId: string;
     readonly exitCode: number;
+    /**
+     * The FULL captured stderr — drives the user-facing message and stays
+     * UNTRUNCATED here (M4). The parent's structured `shard_failed` event caps a
+     * separate `stderrPreview` (~500c) independently, so a long stderr is never
+     * lost from the failure surface.
+     */
     readonly stderr: string;
+    /** Machine-filterable failure taxonomy ({@link FailureClass}); absent on a clean exit. */
+    readonly failureClass?: FailureClass;
 }
 export interface RunShardsOutput {
     readonly fragments: readonly ShardBuildResult[];

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

@@ -1 +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"}
+{"version":3,"file":"shard-runner.d.ts","sourceRoot":"","sources":["../../../src/cli/orchestrate/shard-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmBH,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;AAGrD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,cAAc,GAAG,cAAc,GAAG,SAAS,GAAG,WAAW,CAAC;AAgF/F,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;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;CACtC;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,CAoGzF;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,CA+Bf"}