gitnexus 1.6.2-rc.9 → 1.6.2

package/dist/core/ingestion/model/heritage-map.js

@@ -64,8 +64,12 @@ const DEFAULT_HERITAGE_STRATEGY = { defaultEdge: 'EXTENDS' };
  * paths) used by interface-dispatch in call resolution.
  */
 export const buildHeritageMap = (heritage, ctx, getHeritageStrategy) => {
-    // childNodeId → Set<parentNodeId>  (Set to deduplicate cross-chunk duplicates)
+    // childNodeId → insertion-ordered array of { parentId, kind }.
+    // Ordered array (not Set) because Ruby MRO walk depends on declaration
+    // order. A parallel `seen` map dedupes `(parentId, kind)` pairs without
+    // losing order.
     const directParents = new Map();
+    const seenParents = new Map();
     // interfaceName → Set<filePath>  (implementor lookup for interface dispatch)
     const implementorFiles = new Map();
     for (const h of heritage) {
@@ -80,10 +84,23 @@ export const buildHeritageMap = (heritage, ctx, getHeritageStrategy) => {
                         continue;
                     let parents = directParents.get(child.nodeId);
                     if (!parents) {
-                        parents = new Set();
+                        parents = [];
                         directParents.set(child.nodeId, parents);
                     }
-                    parents.add(parent.nodeId);
+                    let seen = seenParents.get(child.nodeId);
+                    if (!seen) {
+                        seen = new Set();
+                        seenParents.set(child.nodeId, seen);
+                    }
+                    // Dedup by `parentId + kind` so the same parent under two different
+                    // kinds (e.g. a module that is both included and prepended — legal
+                    // Ruby though unusual) is recorded twice; the consumer needs both
+                    // kinds in the walk. A single (parent, kind) pair is deduped.
+                    const key = `${parent.nodeId}|${h.kind}`;
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        parents.push({ parentId: parent.nodeId, kind: h.kind });
+                    }
                 }
             }
         }
@@ -120,9 +137,28 @@ export const buildHeritageMap = (heritage, ctx, getHeritageStrategy) => {
         }
     }
     // --- Public API ---------------------------------------------------
+    /** Internal helper: return the entries array (may be undefined). */
+    const entriesFor = (nodeId) => directParents.get(nodeId);
+    const getParentEntries = (childNodeId) => {
+        const entries = entriesFor(childNodeId);
+        return entries ?? [];
+    };
     const getParents = (childNodeId) => {
-        const parents = directParents.get(childNodeId);
-        return parents ? [...parents] : [];
+        const entries = entriesFor(childNodeId);
+        if (!entries)
+            return [];
+        // Deduplicate parent ids across kinds so the flat-string contract
+        // (used by non-Ruby MRO strategies and by the C3 linearizer) stays
+        // identical to its pre-kind-awareness behavior.
+        const out = [];
+        const seen = new Set();
+        for (const e of entries) {
+            if (!seen.has(e.parentId)) {
+                seen.add(e.parentId);
+                out.push(e.parentId);
+            }
+        }
+        return out;
     };
     const getAncestors = (childNodeId) => {
         const result = [];
@@ -139,11 +175,15 @@ export const buildHeritageMap = (heritage, ctx, getHeritageStrategy) => {
                 visited.add(parentId);
                 result.push(parentId);
                 // Expand parent's own parents for next level
-                const grandparents = directParents.get(parentId);
+                const grandparents = entriesFor(parentId);
                 if (grandparents) {
+                    const gpSeen = new Set();
                     for (const gp of grandparents) {
-                        if (!visited.has(gp))
-                            nextFrontier.push(gp);
+                        if (gpSeen.has(gp.parentId))
+                            continue;
+                        gpSeen.add(gp.parentId);
+                        if (!visited.has(gp.parentId))
+                            nextFrontier.push(gp.parentId);
                     }
                 }
             }
@@ -152,8 +192,69 @@ export const buildHeritageMap = (heritage, ctx, getHeritageStrategy) => {
         }
         return result;
     };
+    /**
+     * Lazy-computed per-owner split of direct parents into instance-dispatch
+     * (non-`extend`) and singleton-dispatch (`extend`-only) views. Memoized on
+     * first request so the `.filter()` pass happens at most once per owner per
+     * HeritageMap lifetime, not per call-site dispatch.
+     *
+     * Shared empty-array sentinels for owners with no entries in a given view
+     * avoid per-call allocation when the split is asymmetric (common Ruby case:
+     * a class has `include` but no `extend`, so its singleton view is empty).
+     */
+    const EMPTY_PARENT_ENTRIES = [];
+    const splitCache = new Map();
+    const splitForOwner = (childNodeId) => {
+        let cached = splitCache.get(childNodeId);
+        if (cached)
+            return cached;
+        const entries = entriesFor(childNodeId);
+        if (!entries || entries.length === 0) {
+            cached = { instance: EMPTY_PARENT_ENTRIES, singleton: EMPTY_PARENT_ENTRIES };
+        }
+        else {
+            const instance = [];
+            const singleton = [];
+            for (const e of entries) {
+                if (e.kind === 'extend')
+                    singleton.push(e);
+                else
+                    instance.push(e);
+            }
+            cached = {
+                instance: instance.length === 0 ? EMPTY_PARENT_ENTRIES : instance,
+                singleton: singleton.length === 0 ? EMPTY_PARENT_ENTRIES : singleton,
+            };
+        }
+        splitCache.set(childNodeId, cached);
+        return cached;
+    };
+    /**
+     * Instance-dispatch ancestry walk. Excludes `extend` (singleton-only).
+     * For kind-aware consumers (Ruby MRO): walks parents in source-insertion
+     * order. The consumer is responsible for interleaving self / reversing
+     * prepend order / etc. This method preserves raw declaration order.
+     *
+     * Result is cached per owner; repeat calls return the same array.
+     */
+    const getInstanceAncestry = (childNodeId) => splitForOwner(childNodeId).instance;
+    /**
+     * Singleton-dispatch ancestry walk. Only `extend` parents. For non-Ruby
+     * languages this is always empty (no language currently produces `extend`
+     * heritage records outside Ruby).
+     *
+     * Result is cached per owner; repeat calls return the same array.
+     */
+    const getSingletonAncestry = (childNodeId) => splitForOwner(childNodeId).singleton;
     const getImplementorFiles = (interfaceName) => {
         return implementorFiles.get(interfaceName) ?? EMPTY_SET;
     };
-    return { getParents, getAncestors, getImplementorFiles };
+    return {
+        getParents,
+        getAncestors,
+        getParentEntries,
+        getInstanceAncestry,
+        getSingletonAncestry,
+        getImplementorFiles,
+    };
 };

package/dist/core/ingestion/model/index.d.ts

@@ -10,11 +10,11 @@
  * `SymbolTable` by design.
  */
 export { type SemanticModel, type MutableSemanticModel, createSemanticModel, } from './semantic-model.js';
-export { type SymbolTableReader, type SymbolTableWriter, createSymbolTable, } from './symbol-table.js';
+export { type SymbolTableReader, type SymbolTableWriter, createSymbolTable, type SymbolDefinition, type AddMetadata, CLASS_TYPES, CLASS_TYPES_TUPLE, type ClassLikeLabel, FREE_CALLABLE_TYPES, FREE_CALLABLE_TUPLE, type FreeCallableLabel, CALL_TARGET_TYPES, } from './symbol-table.js';
 export { type TypeRegistry, type MutableTypeRegistry, createTypeRegistry, } from './type-registry.js';
 export { type MethodRegistry, type MutableMethodRegistry, createMethodRegistry, } from './method-registry.js';
 export { type FieldRegistry, type MutableFieldRegistry, createFieldRegistry, } from './field-registry.js';
 export { lookupMethodByOwnerWithMRO } from './resolve.js';
 export { type NamedImportBinding, type NamedImportMap, isFileInPackageDir, } from './resolution-context.js';
-export { type ExtractedHeritage, type HeritageResolutionStrategy, type HeritageStrategyLookup, } from './heritage-map.js';
+export { type ExtractedHeritage, type HeritageMap, type HeritageResolutionStrategy, type HeritageStrategyLookup, } from './heritage-map.js';
 export { CALLABLE_ONLY_LABELS, INERT_LABELS, DISPATCH_LABELS, ALL_NODE_LABELS, type LabelBehavior, } from './registration-table.js';

package/dist/core/ingestion/model/index.js

@@ -16,7 +16,7 @@ export { createSemanticModel, } from './semantic-model.js';
 // SymbolTable is exclusively owned by SemanticModel. Re-exported here
 // for the rare caller that needs the file/callable interface in
 // isolation (e.g. tests).
-export { createSymbolTable, } from './symbol-table.js';
+export { createSymbolTable, CLASS_TYPES, CLASS_TYPES_TUPLE, FREE_CALLABLE_TYPES, FREE_CALLABLE_TUPLE, CALL_TARGET_TYPES, } from './symbol-table.js';
 // Type registry (classes, structs, interfaces, enums, records, impls)
 export { createTypeRegistry, } from './type-registry.js';
 // Method registry (owner-scoped methods with arity-aware overload lookup)

package/dist/core/ingestion/model/resolve.d.ts

@@ -12,6 +12,9 @@ import type { MroStrategy } from '../../../_shared/index.js';
 /**
  * Gather all ancestor IDs in BFS / topological order.
  * Returns the linearized list of ancestor IDs (excluding the class itself).
+ *
+ * Uses a head-pointer BFS (`queue[head++]`) instead of `Array.shift()` to
+ * avoid O(n) per-dequeue re-indexing — matching `buildParentMapFromHeritage`.
  */
 declare function gatherAncestors(classId: string, parentMap: Map<string, string[]>): string[];
 /**
@@ -25,32 +28,34 @@ declare function gatherAncestors(classId: string, parentMap: Map<string, string[
 export declare function c3Linearize(classId: string, parentMap: Map<string, string[]>, cache: Map<string, string[] | null>, inProgress?: Set<string>): string[] | null;
 export { gatherAncestors };
 /**
- * Look up a method on an owner class, walking the parent chain via HeritageMap
- * when the method isn't found on the direct owner.
- *
- * Respects the 5 per-language MRO strategies:
- * - `first-wins`:       BFS ancestor walk, first match wins (default)
- * - `leftmost-base`:    BFS ancestor walk, leftmost base in declaration order wins (C++);
- *                        HeritageMap preserves insertion order matching source declaration,
- *                        so BFS order is equivalent to leftmost-base semantics
- * - `c3`:               C3-linearized ancestor order, first match wins (Python)
- * - `implements-split`: BFS ancestor walk, first match wins (Java/C#) —
- *                        full ambiguity detection for multiple interface defaults
- *                        is handled by computeMRO at graph level
- * - `qualified-syntax`: No auto-resolution (Rust) — returns undefined
- *
- * Uses the `c3Linearize` defined in this file (also consumed by
- * mro-processor.ts for graph-level MRO emission) for the `c3` strategy.
- *
- * Depends only on {@link SemanticModel} + {@link HeritageMap} + an
- * {@link MroStrategy} literal — NO dependency on SymbolTable, the language
- * registry, or resolution-context, which keeps the `model/` module free of
- * cross-layer imports. Callers derive the strategy from their language
- * provider before invoking this function.
- *
- * @internal This is the low-level MRO walker. Exported so call-processor's
- * higher-level resolvers (and unit tests) can invoke it directly. Callers
- * outside `core/ingestion/` should use the higher-level resolvers in
- * call-processor.ts instead of depending on this function.
+ * DAG stage 5 helper: look up a method on an owner class via MRO walk.
+ *
+ * Low-level resolver; no dependency on SymbolTable, language registry, or
+ * resolution-context (keeps model/ layer free of cross-layer imports).
+ * All strategies respect `argCount` for overload narrowing.
+ * `ancestryOverride` replaces the default walk; caller must compute it correctly.
+ *
+ * Strategy summary (full docs in gitnexus-shared/mro-strategy.ts):
+ * - `first-wins` / `leftmost-base` / `implements-split`: BFS, first match wins.
+ * - `c3`: C3-linearized order; falls back to BFS on cycle/inconsistency.
+ * - `qualified-syntax`: returns undefined immediately (Rust requires explicit syntax).
+ * - `ruby-mixin`: kind-aware walk — see inline comments below.
+ *
+ * Internal API: exported for call-processor resolvers and tests.
+ * External callers should use resolveMemberCall instead.
+ *
+ * @see gitnexus-shared/mro-strategy.ts § 'ruby-mixin'
+ * @see call-processor.ts § resolveMemberCall
+ */
+export declare const lookupMethodByOwnerWithMRO: (ownerNodeId: string, methodName: string, heritageMap: HeritageMap, model: SemanticModel, strategy: MroStrategy, argCount?: number, 
+/**
+ * Optional pre-computed ancestry list. When provided, overrides the default
+ * per-strategy ancestry source. Primarily used by Ruby singleton dispatch:
+ * the caller supplies `heritageMap.getSingletonAncestry(ownerNodeId)` as
+ * node-id array so this walker resolves against `extend` providers only.
+ *
+ * For `ruby-mixin` strategy, passing an override switches the walker into
+ * a no-prepend-no-direct linear scan (the caller has already decided the
+ * order), which is the correct semantics for singleton dispatch.
  */
-export declare const lookupMethodByOwnerWithMRO: (ownerNodeId: string, methodName: string, heritageMap: HeritageMap, model: SemanticModel, strategy: MroStrategy, argCount?: number) => SymbolDefinition | undefined;
+ancestryOverride?: readonly string[]) => SymbolDefinition | undefined;

package/dist/core/ingestion/model/resolve.js

@@ -15,13 +15,17 @@
 /**
  * Gather all ancestor IDs in BFS / topological order.
  * Returns the linearized list of ancestor IDs (excluding the class itself).
+ *
+ * Uses a head-pointer BFS (`queue[head++]`) instead of `Array.shift()` to
+ * avoid O(n) per-dequeue re-indexing — matching `buildParentMapFromHeritage`.
  */
 function gatherAncestors(classId, parentMap) {
     const visited = new Set();
     const order = [];
     const queue = [...(parentMap.get(classId) ?? [])];
-    while (queue.length > 0) {
-        const id = queue.shift();
+    let head = 0;
+    while (head < queue.length) {
+        const id = queue[head++];
         if (visited.has(id))
             continue;
         visited.add(id);
@@ -229,35 +233,112 @@ const buildParentMapFromHeritage = (startNodeId, heritageMap) => {
 // MRO-aware method lookup
 // ---------------------------------------------------------------------------
 /**
- * Look up a method on an owner class, walking the parent chain via HeritageMap
- * when the method isn't found on the direct owner.
+ * DAG stage 5 helper: look up a method on an owner class via MRO walk.
  *
- * Respects the 5 per-language MRO strategies:
- * - `first-wins`:       BFS ancestor walk, first match wins (default)
- * - `leftmost-base`:    BFS ancestor walk, leftmost base in declaration order wins (C++);
- *                        HeritageMap preserves insertion order matching source declaration,
- *                        so BFS order is equivalent to leftmost-base semantics
- * - `c3`:               C3-linearized ancestor order, first match wins (Python)
- * - `implements-split`: BFS ancestor walk, first match wins (Java/C#) —
- *                        full ambiguity detection for multiple interface defaults
- *                        is handled by computeMRO at graph level
- * - `qualified-syntax`: No auto-resolution (Rust) — returns undefined
+ * Low-level resolver; no dependency on SymbolTable, language registry, or
+ * resolution-context (keeps model/ layer free of cross-layer imports).
+ * All strategies respect `argCount` for overload narrowing.
+ * `ancestryOverride` replaces the default walk; caller must compute it correctly.
  *
- * Uses the `c3Linearize` defined in this file (also consumed by
- * mro-processor.ts for graph-level MRO emission) for the `c3` strategy.
+ * Strategy summary (full docs in gitnexus-shared/mro-strategy.ts):
+ * - `first-wins` / `leftmost-base` / `implements-split`: BFS, first match wins.
+ * - `c3`: C3-linearized order; falls back to BFS on cycle/inconsistency.
+ * - `qualified-syntax`: returns undefined immediately (Rust requires explicit syntax).
+ * - `ruby-mixin`: kind-aware walk — see inline comments below.
  *
- * Depends only on {@link SemanticModel} + {@link HeritageMap} + an
- * {@link MroStrategy} literal — NO dependency on SymbolTable, the language
- * registry, or resolution-context, which keeps the `model/` module free of
- * cross-layer imports. Callers derive the strategy from their language
- * provider before invoking this function.
+ * Internal API: exported for call-processor resolvers and tests.
+ * External callers should use resolveMemberCall instead.
  *
- * @internal This is the low-level MRO walker. Exported so call-processor's
- * higher-level resolvers (and unit tests) can invoke it directly. Callers
- * outside `core/ingestion/` should use the higher-level resolvers in
- * call-processor.ts instead of depending on this function.
+ * @see gitnexus-shared/mro-strategy.ts § 'ruby-mixin'
+ * @see call-processor.ts § resolveMemberCall
  */
-export const lookupMethodByOwnerWithMRO = (ownerNodeId, methodName, heritageMap, model, strategy, argCount) => {
+export const lookupMethodByOwnerWithMRO = (ownerNodeId, methodName, heritageMap, model, strategy, argCount, 
+/**
+ * Optional pre-computed ancestry list. When provided, overrides the default
+ * per-strategy ancestry source. Primarily used by Ruby singleton dispatch:
+ * the caller supplies `heritageMap.getSingletonAncestry(ownerNodeId)` as
+ * node-id array so this walker resolves against `extend` providers only.
+ *
+ * For `ruby-mixin` strategy, passing an override switches the walker into
+ * a no-prepend-no-direct linear scan (the caller has already decided the
+ * order), which is the correct semantics for singleton dispatch.
+ */
+ancestryOverride) => {
+    // ── Ruby mixin strategy ───────────────────────────────────────────
+    // Kind-aware walk — does NOT short-circuit on direct owner first (prepend beats direct).
+    // Instance dispatch: prepend (reverse) → direct → include (reverse) → transitive BFS.
+    // Singleton dispatch: caller supplies ancestryOverride (extend providers only);
+    //   simple left-to-right scan. Miss NEVER falls through to file-scoped fallback.
+    // See gitnexus-shared/mro-strategy.ts § 'ruby-mixin' for full strategy docs.
+    if (strategy === 'ruby-mixin') {
+        if (ancestryOverride) {
+            // Singleton dispatch: scan pre-computed ancestry only. Miss null-routes.
+            for (const ancestorId of ancestryOverride) {
+                const method = model.methods.lookupMethodByOwner(ancestorId, methodName, argCount);
+                if (method)
+                    return method;
+            }
+            return undefined;
+        }
+        // Instance dispatch — kind-aware walk per the pseudocode above.
+        const instanceEntries = heritageMap.getInstanceAncestry(ownerNodeId);
+        // Partition into prepend parents vs other parents (extends / include /
+        // implements / trait-impl), preserving declaration order within each.
+        const prependParents = [];
+        const otherParents = [];
+        for (const e of instanceEntries) {
+            if (e.kind === 'prepend')
+                prependParents.push(e.parentId);
+            else
+                otherParents.push(e.parentId);
+        }
+        // Step 1: Walk prepend parents in REVERSE declaration order (last-prepended wins).
+        for (let i = prependParents.length - 1; i >= 0; i--) {
+            const method = model.methods.lookupMethodByOwner(prependParents[i], methodName, argCount);
+            if (method)
+                return method;
+        }
+        // Step 2: Direct owner lookup (the class's own method).
+        // This is the only difference from other strategies — prepend beats direct.
+        const direct = model.methods.lookupMethodByOwner(ownerNodeId, methodName, argCount);
+        if (direct)
+            return direct;
+        // Step 3: Walk extends + include parents in REVERSE declaration order.
+        // (Ruby `include A; include B` puts B ahead of A in MRO.)
+        for (let i = otherParents.length - 1; i >= 0; i--) {
+            const method = model.methods.lookupMethodByOwner(otherParents[i], methodName, argCount);
+            if (method)
+                return method;
+        }
+        // Step 4: Transitive ancestors (a mixin that itself mixes in another module).
+        // Fall back to the BFS ancestor walk for depth > 1. Order is best-effort;
+        // Ruby's actual MRO for transitive mixins is rare and under-specified
+        // (documented in architecture docs as deferred work).
+        //
+        // O(1) skip-check via Sets:
+        //   - `walkedDirect` covers parents already visited in steps 1-3.
+        //   - `singletonOnly` covers direct `extend` providers: they belong to
+        //     the singleton MRO and must NEVER appear in instance dispatch.
+        // Building Sets once before the BFS loop avoids O(n²) `Array.includes`
+        // on large mixin hierarchies.
+        const walkedDirect = new Set(prependParents);
+        for (const id of otherParents)
+            walkedDirect.add(id);
+        const singletonOnly = new Set(heritageMap.getSingletonAncestry(ownerNodeId).map((e) => e.parentId));
+        for (const ancestorId of heritageMap.getAncestors(ownerNodeId)) {
+            if (ancestorId === ownerNodeId)
+                continue;
+            if (walkedDirect.has(ancestorId))
+                continue;
+            if (singletonOnly.has(ancestorId))
+                continue;
+            const method = model.methods.lookupMethodByOwner(ancestorId, methodName, argCount);
+            if (method)
+                return method;
+        }
+        return undefined;
+    }
+    // ── Non-Ruby strategies: direct-owner-first short-circuit ─────────
     // Direct lookup first (child override — no walk needed).
     // argCount is threaded through so arity-differing overloads on the direct
     // owner can be disambiguated before the MRO walk starts.
@@ -270,7 +351,10 @@ export const lookupMethodByOwnerWithMRO = (ownerNodeId, methodName, heritageMap,
     // Determine ancestor walk order based on MRO strategy.
     // readonly to accept the cached (frozen) c3 linearization without copying.
     let ancestors;
-    if (strategy === 'c3') {
+    if (ancestryOverride) {
+        ancestors = ancestryOverride;
+    }
+    else if (strategy === 'c3') {
         // C3 linearization (memoized per HeritageMap
         // so repeated calls for the same owner within an ingestion run reuse the
         // linearization instead of rebuilding the parent map and re-running C3).

package/dist/core/ingestion/parsing-processor.d.ts

@@ -1,9 +1,8 @@
 import { KnowledgeGraph } from '../graph/types.js';
-import type { SymbolTableWriter } from './model/symbol-table.js';
+import type { SymbolTableWriter, ExtractedHeritage } from './model/index.js';
 import { ASTCache } from './ast-cache.js';
 import { WorkerPool } from './workers/worker-pool.js';
 import type { ExtractedImport, ExtractedCall, ExtractedAssignment, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedToolDef, FileConstructorBindings, FileScopeBindings, ExtractedORMQuery } from './workers/parse-worker.js';
-import type { ExtractedHeritage } from './model/heritage-map.js';
 export type FileProgressCallback = (current: number, total: number, filePath: string) => void;
 export interface WorkerExtractedData {
     imports: ExtractedImport[];

package/dist/core/ingestion/pipeline-phases/parse-impl.d.ts

@@ -43,5 +43,6 @@ export declare function runChunkedParseAndResolve(graph: KnowledgeGraph, scanned
     allORMQueries: ExtractedORMQuery[];
     bindingAccumulator: BindingAccumulator;
     resolutionContext: ReturnType<typeof createResolutionContext>;
+    usedWorkerPool: boolean;
 }>;
 export {};

package/dist/core/ingestion/pipeline-phases/parse-impl.js

@@ -98,9 +98,11 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         message: `Parsing ${totalParseable} files in ${numChunks} chunk${numChunks !== 1 ? 's' : ''}...`,
         stats: { filesProcessed: 0, totalFiles: totalParseable, nodesCreated: graph.nodeCount },
     });
-    // Don't spawn workers for tiny repos — overhead exceeds benefit
-    const MIN_FILES_FOR_WORKERS = 15;
-    const MIN_BYTES_FOR_WORKERS = 512 * 1024;
+    // Don't spawn workers for tiny repos — overhead exceeds benefit.
+    // Test suites may lower the thresholds via `options.workerThresholdsForTest`
+    // to exercise the worker-pool path with small fixtures; see PipelineOptions.
+    const MIN_FILES_FOR_WORKERS = options?.workerThresholdsForTest?.minFiles ?? 15;
+    const MIN_BYTES_FOR_WORKERS = options?.workerThresholdsForTest?.minBytes ?? 512 * 1024;
     const totalBytes = parseableScanned.reduce((s, f) => s + f.size, 0);
     // Create worker pool once, reuse across chunks
     let workerPool;
@@ -433,5 +435,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         allORMQueries,
         bindingAccumulator,
         resolutionContext: ctx,
+        // Whether a worker pool was actually live for this run. False means the
+        // sequential fallback handled every chunk (either due to `skipWorkers`,
+        // the file-count/byte thresholds, or a pool-creation failure).
+        usedWorkerPool: workerPool !== undefined,
     };
 }

package/dist/core/ingestion/pipeline-phases/parse.d.ts

@@ -45,5 +45,12 @@ export interface ParseOutput {
     readonly allPathSet: ReadonlySet<string>;
     /** Pass-through: total file count for progress reporting. */
     totalFiles: number;
+    /**
+     * True if the parse phase spawned a live worker pool for this run.
+     * False means every chunk ran through the sequential fallback (skipWorkers,
+     * thresholds not met, or pool-creation failure). Primarily a test affordance:
+     * see `PipelineOptions.workerThresholdsForTest`.
+     */
+    readonly usedWorkerPool: boolean;
 }
 export declare const parsePhase: PipelinePhase<ParseOutput>;

package/dist/core/ingestion/pipeline.d.ts

@@ -21,5 +21,16 @@ export interface PipelineOptions {
     skipGraphPhases?: boolean;
     /** Force sequential parsing (no worker pool). Useful for testing the sequential path. */
     skipWorkers?: boolean;
+    /**
+     * @internal Test-only override for worker-pool gating thresholds.
+     * When unset, production defaults apply (15 files OR 512 KB total bytes).
+     * Setting either field lowers the corresponding threshold so small test
+     * fixtures can still exercise the worker-pool path. Do not use from
+     * production call sites.
+     */
+    workerThresholdsForTest?: {
+        minFiles?: number;
+        minBytes?: number;
+    };
 }
 export declare const runPipelineFromRepo: (repoPath: string, onProgress: (progress: PipelineProgress) => void, options?: PipelineOptions) => Promise<PipelineResult>;

package/dist/core/ingestion/pipeline.js

@@ -58,7 +58,7 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
         pipelineStart,
     });
     // Extract final results for the PipelineResult contract
-    const { totalFiles } = getPhaseOutput(results, 'parse');
+    const { totalFiles, usedWorkerPool } = getPhaseOutput(results, 'parse');
     let communityResult;
     let processResult;
     if (!options?.skipGraphPhases) {
@@ -77,5 +77,12 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
             nodesCreated: graph.nodeCount,
         },
     });
-    return { graph, repoPath, totalFileCount: totalFiles, communityResult, processResult };
+    return {
+        graph,
+        repoPath,
+        totalFileCount: totalFiles,
+        communityResult,
+        processResult,
+        usedWorkerPool,
+    };
 };