gitnexus 1.6.6-rc.98 → 1.6.6

package/dist/core/ingestion/workers/worker-pool.d.ts

@@ -32,11 +32,12 @@ export interface WorkerPool {
      *
      * Files in {@link WorkerPool.getQuarantinedPaths} are filtered out before
      * dispatch — they have already caused a worker death this pool lifetime and
-     * are not safe to re-attempt in workers. The caller is responsible for
-     * routing them (e.g. to sequential fallback); inspect the quarantine
-     * snapshot before and after each dispatch.
+     * are not safe to re-attempt in workers. They are dropped from the run (the
+     * sequential fallback that once re-parsed them was removed); inspect the
+     * quarantine snapshot before and after each dispatch to surface skipped files
+     * in diagnostics.
      */
-    dispatch<TInput, TResult>(items: TInput[], onProgress?: (filesProcessed: number) => void): Promise<TResult[]>;
+    dispatch<TInput, TResult>(items: TInput[], onProgress?: (filesProcessed: number) => void, chunkHash?: string): Promise<TResult[]>;
     /** Terminate all workers. Must be called when done. */
     terminate(): Promise<void>;
     /** Number of worker slots originally requested for the pool. */
@@ -113,8 +114,8 @@ export interface WorkerPoolOptions {
      * Hard ceiling on total wall time the pool will spend retrying / splitting
      * any single job. Combined with `timeoutBackoffFactor`, this prevents
      * exponentially-growing retry waits from accumulating into multi-hour
-     * stalls before the pool finally surfaces the bad file to sequential
-     * fallback. Default 5x `subBatchIdleTimeoutMs`.
+     * stalls before the pool finally quarantines the bad file and proceeds
+     * without it. Default 5x `subBatchIdleTimeoutMs`.
      */
     maxCumulativeTimeoutMs?: number;
     /**
@@ -130,6 +131,27 @@ export interface WorkerPoolOptions {
      * code should leave this unset.
      */
     workerFactory?: (workerUrl: URL) => Worker;
+    /**
+     * Storage path for the disk-backed ParsedFile store (#1983 parallel
+     * serialization). When set, it is baked into every spawned worker's
+     * `workerData` so the worker writes its own ParsedFile shards to disk
+     * instead of returning them over the MessageChannel for the main thread to
+     * serialize. Immutable for the run; captured in the default factory closure
+     * so RESPAWNED workers inherit it automatically (all spawn sites reuse the
+     * same factory). `undefined` ⇒ workers fall back to returning ParsedFiles in
+     * the result (small-repo / no-storage path).
+     */
+    parsedFileStoreStoragePath?: string;
+    /**
+     * Directory for the DURABLE, content-addressed ParsedFile store
+     * (`getDurableParsedFileDir`). When set (alongside a chunk hash on the
+     * dispatch), the worker ALSO writes its ParsedFiles to a content-addressed
+     * shard keyed by chunk hash so a future warm parse-cache hit can restore
+     * them without re-parsing (#2038 warm-cache coverage). Baked into every
+     * worker's `workerData` exactly like {@link parsedFileStoreStoragePath}.
+     * `undefined` ⇒ no durable write.
+     */
+    durableParsedFileStoragePath?: string;
 }
 export declare class WorkerPoolDispatchError extends Error {
     /**
@@ -149,10 +171,50 @@ export declare class WorkerPoolDispatchError extends Error {
     readonly quarantinedPaths: readonly string[];
     constructor(message: string, quarantinedPaths?: readonly string[]);
 }
+/**
+ * How a total worker-startup failure was classified by the pool's bounded
+ * self-heal (#1741). Lets the caller render an accurate cause without
+ * inspecting any operator flag:
+ *  - 'deterministic-startup': ≥2 fresh workers crashed with the SAME signature
+ *    before any reached ready (e.g. a missing native binding) — retrying is
+ *    futile, so the pool short-circuited fast.
+ *  - 'transient-exhausted': workers crashed variably and exhausted the bounded
+ *    startup retry budget without ever reaching ready.
+ */
+export type StartupCrashClass = 'deterministic-startup' | 'transient-exhausted';
 export declare class WorkerPoolInitializationError extends WorkerPoolDispatchError {
     readonly readinessFailures: readonly string[];
-    constructor(message: string, quarantinedPaths?: readonly string[], readinessFailures?: readonly string[]);
+    /** Pool's automatic classification of the startup crash (#1741). */
+    readonly crashClass: StartupCrashClass;
+    constructor(message: string, quarantinedPaths?: readonly string[], readinessFailures?: readonly string[], crashClass?: StartupCrashClass);
 }
+/**
+ * Thrown when a caller asks GitNexus to parse without the worker pool —
+ * `--workers 0`, `GITNEXUS_WORKER_POOL_SIZE=0`, or `skipWorkers: true`.
+ *
+ * GitNexus no longer has a sequential parser: the worker pool (with its
+ * quarantine + respawn/recycle + circuit-breaker resilience) is the SOLE
+ * parse path. These channels used to select an in-process fallback; they are
+ * now hard configuration errors so the operator gets an actionable message
+ * instead of silently parsing through a (deleted) slower path.
+ */
+export declare class WorkerPoolDisabledError extends Error {
+    constructor(message: string);
+}
+/**
+ * Normalize a worker crash message into a stable signature so two instances of
+ * the SAME deterministic crash compare equal while unrelated crashes don't.
+ * Strips hex addresses, digit runs (pids / line numbers / timestamps) and
+ * absolute paths. Best-effort by design: the deterministic classification's
+ * correctness rests on the STRUCTURAL signal (zero workers ever ready + startup
+ * budget exhausted), so an imperfect signature only changes how fast the
+ * short-circuit fires, never whether the pool ultimately fails fast. Even a
+ * stderr-less crash normalizes its "exited with code N" message to a stable
+ * key, so the empty-stderr timing case still groups.
+ *
+ * @internal Exported for unit tests; production callers are in this module.
+ */
+export declare function crashSignature(message: string): string;
 interface ResolvedWorkerPoolOptions {
     subBatchSize: number;
     subBatchMaxBytes: number;
@@ -164,12 +226,19 @@ interface ResolvedWorkerPoolOptions {
     consecutiveFailureThreshold: number;
 }
 export declare function resolveWorkerPoolOptions(options?: WorkerPoolOptions, poolSize?: number): ResolvedWorkerPoolOptions;
+/**
+ * True when the operator set `GITNEXUS_WORKER_POOL_SIZE=0` — the env-channel
+ * equivalent of `--workers 0`. The parse phase consults this (only when no
+ * explicit `--workers <N>` was passed) and HARD-ERRORS: sequential parsing was
+ * removed, so a disabled pool is an actionable configuration error, not a
+ * silent fallback. An explicit positive `--workers N` always wins.
+ */
+export declare function workerPoolDisabledByEnv(): boolean;
 /**
  * Resolve the auto-default worker pool size when no explicit `poolSize`
  * arg is passed to `createWorkerPool`. Precedence:
  *
- * 1. `GITNEXUS_WORKER_POOL_SIZE` env var (operator override; set by
- *    `--workers <N>` on the CLI).
+ * 1. `GITNEXUS_WORKER_POOL_SIZE` env var (operator override).
  * 2. `os.cpus().length - 1`, clamped to `[1, DEFAULT_POOL_SIZE_CAP]`.
  *
  * The cap exists because past ~16 workers the main-thread merge /