gitnexus 1.6.12-rc.2 → 1.6.12-rc.21

package/dist/core/ingestion/scope-resolution/scope/walkers.js

@@ -160,6 +160,8 @@ export function namesAtScope(scopeId, scopes) {
  */
 export function isClassLike(t) {
     return (t === 'Class' ||
+        t === 'Protocol' ||
+        t === 'Category' ||
         t === 'Interface' ||
         t === 'Struct' ||
         t === 'Record' ||
@@ -323,6 +325,82 @@ export function isNamespaceNameShadowed(namespaceName, inScope, scopes) {
     }
     return true;
 }
+/**
+ * Does something between `inScope` and its module scope bind `name` to
+ * ANYTHING other than `def`?
+ *
+ * `isNamespaceNameShadowed` asks the same question for a namespace handle,
+ * where any local binding of the name is by definition not the import. A
+ * CONTAINER receiver needs the extra clause: the container may itself be the
+ * local declaration (`fn make() { const Local = struct {…}; … Local.go … }`),
+ * and reading that as its own shadow would suppress exactly the resolutions it
+ * is meant to permit — the #2723 mistake, one channel over.
+ *
+ * So a scope that binds the name answers immediately, and the answer is "not
+ * shadowed" only when one of that scope's bindings IS `def`. A name bound in a
+ * nearer scope to something else — a parameter, a local, a type binding — wins
+ * the lexical race, which is the whole point: `findClassBindingInScope` filters
+ * the chain by `isClassLike` and therefore cannot see that it lost it.
+ *
+ * The MODULE scope is inspected too, unlike `isNamespaceNameShadowed`, and the
+ * exemption is what makes that safe. That guard stops one rung short because a
+ * namespace import writes its own name into the module scope and would read as
+ * its own shadow (#2723); here the owner is compared by identity, so the binding
+ * that IS the owner exempts itself and only a binding to something ELSE answers
+ * `true`. Stopping short would leave the exact hole this walk exists to close:
+ * `findClassBindingInScope` steps over a module-scope binding that is not
+ * class-like and then answers from a WORKSPACE-wide qualified-name index, so
+ * `const Gauge = @import("other.zig").SOME_CONST;` in a file that never imports
+ * `Gauge.zig` would still resolve `Gauge.read` to that file's container.
+ * `lookupBindingsAt` is used at that scope and only there, because an imported
+ * alias lives in the finalized channel rather than in `scope.bindings`.
+ *
+ * Fail-closed like its sibling: a missing scope or a parent cycle answers
+ * `true`, because suppressing a resolution costs a missing edge while trusting a
+ * corrupt chain costs a wrong one.
+ */
+export function isOwnerNameShadowedBySomethingElse(name, def, inScope, scopes) {
+    let currentId = inScope;
+    const visited = new Set();
+    while (currentId !== null) {
+        if (visited.has(currentId))
+            return true;
+        visited.add(currentId);
+        const scope = scopes.scopeTree.getScope(currentId);
+        if (scope === undefined)
+            return true;
+        if (scope.kind !== 'Object') {
+            const isModule = scope.kind === 'Module';
+            const imported = isModule ? lookupBindingsAt(currentId, name, scopes) : [];
+            const bindsHere = scope.bindings.has(name) ||
+                scope.typeBindings.has(name) ||
+                scope.lexicalNames?.has(name) === true ||
+                imported.length > 0 ||
+                scope.ownedDefs.some((d) => {
+                    const qualifiedName = d.qualifiedName;
+                    if (qualifiedName === undefined)
+                        return false;
+                    const dot = qualifiedName.lastIndexOf('.');
+                    return (dot === -1 ? qualifiedName : qualifiedName.slice(dot + 1)) === name;
+                });
+            if (bindsHere) {
+                if ((scope.bindings.get(name) ?? []).some((b) => b.def.nodeId === def.nodeId))
+                    return false;
+                if (scope.ownedDefs.some((d) => d.nodeId === def.nodeId))
+                    return false;
+                if (imported.some((b) => b.def.nodeId === def.nodeId))
+                    return false;
+                return true;
+            }
+        }
+        // The module scope is the last rung, not a rung to skip: nothing above it
+        // can shadow a name for this file.
+        if (scope.kind === 'Module')
+            return false;
+        currentId = scope.parent;
+    }
+    return true;
+}
 export function findReceiverTypeBinding(startScope, receiverName, scopes) {
     let currentId = startScope;
     const visited = new Set();
@@ -401,9 +479,10 @@ export function moduleScopeIdOf(startScope, scopes) {
 /**
  * Look up a class-like binding by name in the given scope's chain.
  *
- * "Class-like" covers `Class | Interface | Struct | Record | Enum |
- * Trait` via the shared `isClassLike` predicate — every kind that
- * collapses to `@scope.class` in the scope-extractor query contract.
+ * "Class-like" covers `Class | Interface | Struct | Record | Enum | Trait |
+ * Protocol | Category` via the shared `isClassLike` predicate. Objective-C
+ * protocol and category definitions are graph-side containers rather than
+ * `@scope.class` captures.
  *
  * Walks the scope chain upward and consults TWO sources at each step:
  *   1. `scope.bindings` — populated during scope-extraction Pass 2 with

package/dist/core/ingestion/scope-resolution/value-ref-edges.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The `reason` text stamped on the USES edge a `value-ref` site emits.
+ *
+ * A leaf module on purpose. Two modules need this string and they sit on
+ * opposite sides of the product: `passes/property-dispatch.ts` writes it at
+ * analysis time, and `mcp/local/local-backend.ts` reads it back at query time
+ * to decide whether an answer is `exact`. Re-typing the literal in the reader
+ * would make the epistemic signal fail SILENTLY the day the writer's text is
+ * reworded — the query would simply match nothing and every answer would go
+ * back to claiming certainty, which is the exact defect (#3399) this constant
+ * exists to close. Importing `property-dispatch.ts` for it instead would drag
+ * the whole scope-resolution emit graph into the MCP backend for one string.
+ */
+export declare const VALUE_REF_EDGE_REASON = "scope-resolution: value-ref";

package/dist/core/ingestion/scope-resolution/value-ref-edges.js

@@ -0,0 +1,14 @@
+/**
+ * The `reason` text stamped on the USES edge a `value-ref` site emits.
+ *
+ * A leaf module on purpose. Two modules need this string and they sit on
+ * opposite sides of the product: `passes/property-dispatch.ts` writes it at
+ * analysis time, and `mcp/local/local-backend.ts` reads it back at query time
+ * to decide whether an answer is `exact`. Re-typing the literal in the reader
+ * would make the epistemic signal fail SILENTLY the day the writer's text is
+ * reworded — the query would simply match nothing and every answer would go
+ * back to claiming certainty, which is the exact defect (#3399) this constant
+ * exists to close. Importing `property-dispatch.ts` for it instead would drag
+ * the whole scope-resolution emit graph into the MCP backend for one string.
+ */
+export const VALUE_REF_EDGE_REASON = 'scope-resolution: value-ref';

package/dist/core/ingestion/tree-sitter-queries.js

@@ -2592,12 +2592,14 @@ export const ZIG_QUERIES = `
     member: (identifier) @call.name)) @call
 `;
 import { SupportedLanguages } from '../../_shared/index.js';
+const OBJECTIVE_C_QUERIES = `((translation_unit) @objc.root)`;
 export const LANGUAGE_QUERIES = {
     [SupportedLanguages.TypeScript]: TYPESCRIPT_QUERIES,
     [SupportedLanguages.JavaScript]: JAVASCRIPT_QUERIES,
     [SupportedLanguages.Python]: PYTHON_QUERIES,
     [SupportedLanguages.Java]: JAVA_QUERIES,
     [SupportedLanguages.C]: C_QUERIES,
+    [SupportedLanguages.ObjectiveC]: OBJECTIVE_C_QUERIES,
     [SupportedLanguages.Go]: GO_QUERIES,
     [SupportedLanguages.CPlusPlus]: CPP_QUERIES,
     [SupportedLanguages.CSharp]: CSHARP_QUERIES,

package/dist/core/ingestion/utils/symbol-labels.js

@@ -21,6 +21,8 @@ export const SYMBOL_NODE_LABELS = new Set([
     'Function',
     'Method',
     'Class',
+    'Protocol',
+    'Category',
     'Interface',
     'CodeElement',
     'Struct',

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

@@ -29,7 +29,7 @@ interface ParsedRelationship {
     id: string;
     sourceId: string;
     targetId: string;
-    type: 'DEFINES' | 'HAS_METHOD' | 'HAS_PROPERTY';
+    type: 'DEFINES' | 'DECLARES' | 'HAS_METHOD' | 'HAS_PROPERTY';
     confidence: number;
     reason: string;
 }

package/dist/core/ingestion/workers/parse-worker.js

@@ -14,7 +14,7 @@ import PHP from 'tree-sitter-php';
 import Ruby from 'tree-sitter-ruby';
 import { requireVendoredGrammar } from '../../tree-sitter/vendored-grammars.js';
 import { SupportedLanguages } from '../../../_shared/index.js';
-import { getProvider } from '../languages/index.js';
+import { getLanguageForFileContent, getProvider } from '../languages/index.js';
 import { getTreeSitterBufferSize, getTreeSitterContentByteLength, TREE_SITTER_MAX_BUFFER, } from '../constants.js';
 import { ARRAY_METHOD_HOC_BLOCKLIST_SET, DEFAULT_EXPORT_IDENTIFIER_BLOCKLIST_SET, deriveDefaultExportHocName, } from '../ts-js-hoc-utils.js';
 import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
@@ -63,6 +63,11 @@ try {
     Zig = requireVendoredGrammar('tree-sitter-zig');
 }
 catch { }
+let ObjectiveC = null;
+try {
+    ObjectiveC = requireVendoredGrammar('tree-sitter-objc');
+}
+catch { }
 import { getLanguageFromFilename } from '../../../_shared/index.js';
 import { buildDefinitionPreScan, FUNCTION_NODE_TYPES, findAncestorBeforeBoundary, findSplitBodyCallableAncestor, SPLIT_SIGNATURE_NODE_TYPES, getDefinitionNodeFromCaptures, findEnclosingClassInfo, findObjectLiteralBindingInfo, isArrayContainedObjectLiteralMember, findReturnShapeOwnerInfo, isReturnShapeProperty, findMemberAssignmentOwnerInfo, isCjsDefaultExportAssignment, getLabelFromCaptures, genericFuncName, inferFunctionLabel, isSuppressedConcreteTypedefDuplicate, isValueDefinitionLabel, isQualifiableScopeLabel, MEMBER_OWNER_NODE_TYPES, qualifyByEnclosingModScope, qualifyRustImplTargetByModScope, CLASS_CONTAINER_TYPES, PARAMETER_LIST_NODE_TYPES, LOCAL_SCOPE_BODY_NODE_TYPES, } from '../utils/ast-helpers.js';
 import { isPositionQualifiedLocalLabel } from '../utils/callable-labels.js';
@@ -140,6 +145,7 @@ const languageMap = {
     [SupportedLanguages.Java]: Java,
     ...(C ? { [SupportedLanguages.C]: C } : {}),
     [SupportedLanguages.CPlusPlus]: CPP,
+    ...(ObjectiveC ? { [SupportedLanguages.ObjectiveC]: ObjectiveC } : {}),
     [SupportedLanguages.CSharp]: CSharp,
     [SupportedLanguages.Go]: Go,
     [SupportedLanguages.Rust]: Rust,
@@ -741,7 +747,7 @@ const processBatch = (files, onProgress) => {
     // Group by language to minimize setLanguage calls
     const byLanguage = new Map();
     for (const file of files) {
-        const lang = getLanguageFromFilename(file.path);
+        const lang = getLanguageForFileContent(file.path, file.content);
         if (!lang)
             continue;
         let list = byLanguage.get(lang);
@@ -993,11 +999,22 @@ function reportWarning(message) {
         logger.warn(message);
     }
 }
+// Keep compiled queries across jobs in this worker. A language can select
+// multiple native grammars, so both grammar identity and query text matter.
+const compiledQueries = new WeakMap();
 const processFileGroup = (files, language, queryString, result, onFileProcessed) => {
     let query;
     try {
         const lang = parser.getLanguage();
-        query = new Parser.Query(lang, queryString);
+        let queries = compiledQueries.get(lang);
+        if (!queries) {
+            queries = new Map();
+            compiledQueries.set(lang, queries);
+        }
+        const cached = queries.get(queryString);
+        query = cached ?? new Parser.Query(lang, queryString);
+        if (!cached)
+            queries.set(queryString, query);
     }
     catch (err) {
         reportWarning(`Query compilation failed for ${language}: ${err instanceof Error ? err.message : String(err)}`);
@@ -1139,6 +1156,49 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             }
             result.parsedFiles.push(withChannels);
         }
+        const semanticGraph = provider.extractSemanticGraph?.(tree, file.path, parseContent);
+        if (semanticGraph !== undefined) {
+            for (const node of semanticGraph.nodes) {
+                result.nodes.push({
+                    id: node.id,
+                    label: node.label,
+                    properties: { ...node.properties },
+                });
+            }
+            for (const relationship of semanticGraph.relationships) {
+                if (relationship.type === 'DECLARES' ||
+                    relationship.type === 'DEFINES' ||
+                    relationship.type === 'HAS_METHOD' ||
+                    relationship.type === 'HAS_PROPERTY') {
+                    result.relationships.push({ ...relationship, type: relationship.type });
+                }
+            }
+            for (const symbol of semanticGraph.symbols) {
+                result.symbols.push({
+                    filePath: symbol.filePath,
+                    name: symbol.name,
+                    nodeId: symbol.nodeId,
+                    type: symbol.type,
+                    ...(symbol.qualifiedName !== undefined ? { qualifiedName: symbol.qualifiedName } : {}),
+                    ...(symbol.parameterCount !== undefined ? { parameterCount: symbol.parameterCount } : {}),
+                    ...(symbol.requiredParameterCount !== undefined
+                        ? { requiredParameterCount: symbol.requiredParameterCount }
+                        : {}),
+                    ...(symbol.parameterTypes !== undefined
+                        ? { parameterTypes: [...symbol.parameterTypes] }
+                        : {}),
+                    ...(symbol.parameterTypeClasses !== undefined
+                        ? { parameterTypeClasses: [...symbol.parameterTypeClasses] }
+                        : {}),
+                    ...(symbol.returnType !== undefined ? { returnType: symbol.returnType } : {}),
+                    ...(symbol.declaredType !== undefined ? { declaredType: symbol.declaredType } : {}),
+                    ...(symbol.ownerId !== undefined ? { ownerId: symbol.ownerId } : {}),
+                    ...(symbol.visibility !== undefined ? { visibility: symbol.visibility } : {}),
+                    ...(symbol.isStatic !== undefined ? { isStatic: symbol.isStatic } : {}),
+                    ...(symbol.isReadonly !== undefined ? { isReadonly: symbol.isReadonly } : {}),
+                });
+            }
+        }
         // Build per-file type environment + constructor bindings in a single AST walk.
         // The legacy heritage pre-pass that seeded a file-local parentMap for
         // buildTypeEnv was removed in RING4-1 (#942) along with the rest of the

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

@@ -1,8 +1,44 @@
 import { Worker } from 'node:worker_threads';
+/**
+ * One content-addressed parse-cache chunk's worth of work inside a pool round.
+ * See {@link WorkerPool.dispatchGroups}.
+ */
+export interface DispatchGroup<TInput> {
+    readonly items: readonly TInput[];
+    /**
+     * Chunk hash tagged onto every job derived from `items`, exactly as the
+     * `chunkHash` argument of {@link WorkerPool.dispatch} does for a lone chunk.
+     */
+    readonly chunkHash?: string;
+}
 export interface WorkerPool {
     /**
-     * Dispatch items across workers. Items are split into bounded jobs, each job
-     * is committed independently, and stalled jobs are split/retried locally.
+     * Dispatch several content-addressed chunks in ONE pool round.
+     *
+     * `dispatch` is a barrier: it resolves only once every job it created has
+     * committed, so dispatching one small parse-cache pack at a time leaves most
+     * slots idle for the whole round-trip. Stable packs are keyed by
+     * `(language, hash(path) % 128)`, which routinely yields packs far below the
+     * byte budget — on this repo, 1285 packs where the budget alone needs 16, and
+     * 549 of them hold a single file. Batching packs into one round removes those
+     * barriers without touching pack identity: jobs are still cut at group
+     * boundaries, so each job carries exactly one `chunkHash` and every result
+     * stays attributable to the pack that owns its cache key.
+     *
+     * Returns one result array per input group, in input order. A group whose
+     * items were all quarantined yields an empty array.
+     *
+     * Required, not optional. `getQuarantinedPaths?` and `getStats?` below are
+     * marked optional as a compatibility accommodation for `WorkerPool` shapes
+     * that predate them — not as a convention for new members. Making this one
+     * optional would force a `?.` plus a fallback branch at its only production
+     * call site, and that branch could never run.
+     */
+    dispatchGroups<TInput, TResult>(groups: readonly DispatchGroup<TInput>[], onProgress?: (filesProcessed: number) => void): Promise<TResult[][]>;
+    /**
+     * Dispatch ONE chunk across workers — {@link WorkerPool.dispatchGroups} with
+     * a single group. Items are split into bounded jobs, each job is committed
+     * independently, and stalled jobs are split/retried locally.
      *
      * Files in {@link WorkerPool.getQuarantinedPaths} are filtered out before
      * dispatch — they have already caused a worker death this pool lifetime and
@@ -230,6 +266,17 @@ interface ResolvedWorkerPoolOptions {
     workerReadyTimeoutMs: number;
 }
 export declare function resolveWorkerPoolOptions(options?: WorkerPoolOptions, poolSize?: number): ResolvedWorkerPoolOptions;
+/**
+ * The pool size requested via the `GITNEXUS_WORKER_POOL_SIZE` env var, or
+ * `undefined` when unset, empty/whitespace, or invalid. Module-internal sizing
+ * reader consumed by {@link resolveAutoPoolSize} (the env override) and
+ * {@link workerPoolDisabledByEnv} (the disabled-channel check). Reads only —
+ * never mutates `process.env`. Empty/whitespace is treated as *unset* (falls
+ * through to the auto formula), not as 0 — an empty assignment (`export
+ * GITNEXUS_WORKER_POOL_SIZE=`) is an accident, not a request for zero workers;
+ * only a literal `0` disables the pool.
+ */
+export declare function envWorkerPoolSize(): number | undefined;
 /**
  * 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
@@ -255,6 +302,13 @@ export declare function workerPoolDisabledByEnv(): boolean;
  * on the env / default.
  */
 export declare function resolveAutoPoolSize(): number;
+/**
+ * Usable parallelism for this process. Prefers `os.availableParallelism` so
+ * cgroup CPU limits are honored, falling back to `os.cpus().length` on older
+ * Node. Exported so callers that size work against the host (rather than
+ * against the pool default) do not re-derive the fallback.
+ */
+export declare function resolveHostParallelism(): number;
 export declare function startHeartbeatStallTracker(): {
     read: () => number;
     stop: () => void;

package/dist/core/ingestion/workers/worker-pool.js

@@ -124,7 +124,9 @@ const DEFAULT_WORKER_READY_TIMEOUT_MS = 5_000;
  * extraction / structured-clone overhead, and the marginal worker adds
  * memory pressure (tree-sitter state + sub-batch buffer) without much
  * throughput gain. Operators on bigger machines override via
- * `GITNEXUS_WORKER_POOL_SIZE` or `--workers <N>`.
+ * `GITNEXUS_WORKER_POOL_SIZE` or `--workers <N>`; both are deliberate
+ * operator input and bypass the work-proportional sizing in `parse-impl`,
+ * which only bounds the AUTO default.
  */
 const DEFAULT_POOL_SIZE_CAP = 16;
 // ── Self-healing startup restart policy (#1741) ──────────────────────────────
@@ -263,7 +265,7 @@ export function resolveWorkerPoolOptions(options = {}, poolSize) {
  * GITNEXUS_WORKER_POOL_SIZE=`) is an accident, not a request for zero workers;
  * only a literal `0` disables the pool.
  */
-function envWorkerPoolSize() {
+export function envWorkerPoolSize() {
     const raw = process.env.GITNEXUS_WORKER_POOL_SIZE;
     if (raw === undefined || raw.trim() === '')
         return undefined;
@@ -307,8 +309,18 @@ export function resolveAutoPoolSize() {
     // pool cap exists to prevent. Falls back to os.cpus().length on
     // older Node versions. Mirrors `capabilities.ts:85`
     // (`defaultEmbeddingThreads`).
-    const cores = typeof os.availableParallelism === 'function' ? os.availableParallelism() : os.cpus().length;
-    return Math.min(DEFAULT_POOL_SIZE_CAP, Math.max(1, cores - 1));
+    return Math.min(DEFAULT_POOL_SIZE_CAP, Math.max(1, resolveHostParallelism() - 1));
+}
+/**
+ * Usable parallelism for this process. Prefers `os.availableParallelism` so
+ * cgroup CPU limits are honored, falling back to `os.cpus().length` on older
+ * Node. Exported so callers that size work against the host (rather than
+ * against the pool default) do not re-derive the fallback.
+ */
+export function resolveHostParallelism() {
+    return typeof os.availableParallelism === 'function'
+        ? os.availableParallelism()
+        : os.cpus().length;
 }
 /**
  * Max characters of a worker's stderr retained for crash diagnostics. A
@@ -488,9 +500,14 @@ function inFlightExcludePath(job, lastProgress) {
     const path = itemPath(job.items[lastProgress]);
     return path ? [path] : [];
 }
-function createJobs(items, maxItems, maxBytes, timeoutMs, chunkHash) {
+/**
+ * Cut `items` into bounded jobs. `startIndexOffset` places those jobs on a
+ * shared index space so several groups can be laid out end to end in one
+ * dispatch round and every result still sorts back into global input order.
+ */
+function createJobs(items, maxItems, maxBytes, timeoutMs, chunkHash, startIndexOffset = 0) {
     const jobs = [];
-    let startIndex = 0;
+    let startIndex = startIndexOffset;
     let batch = [];
     let batchBytes = 0;
     const flush = () => {
@@ -827,7 +844,31 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
     // First dispatch awaits this; it settles every slot's bounded retry loop in
     // parallel and drops the unrecoverable ones before any dispatch can fire.
     const initialReadyGate = Promise.allSettled(workers.map((_, i) => bringSlotReady(i))).then(() => undefined);
-    const dispatch = async (items, onProgress, chunkHash) => {
+    /**
+     * Guards the one-dispatch-at-a-time contract. The dispatch machinery keeps
+     * its jobs/busy-slot/in-flight state per call, so two concurrent dispatches
+     * hand the same slots out twice: both stall, and the failure surfaces only
+     * when every worker hits its idle timeout (10s+ of a wedged pool with no
+     * indication of the cause). Fail loudly at the call instead.
+     */
+    let dispatchInFlight = false;
+    /**
+     * Claim the pool synchronously, then run the dispatch. The claim CANNOT be
+     * taken inside `dispatchGroupsInner`: its first statement awaits the
+     * readiness gate, so two calls made in the same tick would both get past the
+     * check before either set the flag.
+     */
+    const dispatchGroups = (groups, onProgress) => {
+        if (dispatchInFlight) {
+            return Promise.reject(new WorkerPoolDispatchError('Worker pool dispatch is already in flight. `dispatch`/`dispatchGroups` is not ' +
+                'reentrant — await the previous call before starting another on the same pool.', []));
+        }
+        dispatchInFlight = true;
+        return dispatchGroupsInner(groups, onProgress).finally(() => {
+            dispatchInFlight = false;
+        });
+    };
+    const dispatchGroupsInner = async (groups, onProgress) => {
         // Await the initial-spawn readiness gate (F13). On first dispatch
         // this blocks for up to poolOptions.workerReadyTimeoutMs while every initial
         // worker's `{type:'ready'}` handshake is checked; on subsequent
@@ -842,8 +883,9 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
             throw new WorkerPoolDispatchError(`Worker pool circuit breaker tripped${reason}. ` +
                 `Subsequent dispatches require a fresh pool instance.`, []);
         }
-        if (items.length === 0)
-            return [];
+        const emptyPerGroup = () => groups.map(() => []);
+        if (groups.every((group) => group.items.length === 0))
+            return emptyPerGroup();
         if (activeSlots.size === 0) {
             const detail = initialReadinessFailures.length > 0
                 ? ` after initial ready handshake: ${initialReadinessFailures.join('; ')}`
@@ -859,17 +901,42 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
         // Layer 3: filter out quarantined paths so a known-bad file never reaches
         // a worker again this pool lifetime. The caller queries
         // `getQuarantinedPaths` after dispatch to route filtered items.
-        const dispatchableItems = [];
-        for (const item of items) {
-            const path = itemPath(item);
-            if (path !== undefined && quarantine.has(path))
-                continue;
-            dispatchableItems.push(item);
+        // Quarantine is empty on every run that has not had a worker die, so the
+        // filter below would be an identity copy of every group's items. Skip it.
+        const dispatchableGroups = quarantine.size === 0
+            ? groups
+            : groups.map((group) => {
+                const items = [];
+                for (const item of group.items) {
+                    const path = itemPath(item);
+                    if (path !== undefined && quarantine.has(path))
+                        continue;
+                    items.push(item);
+                }
+                return { items, chunkHash: group.chunkHash };
+            });
+        const dispatchableCount = dispatchableGroups.reduce((sum, group) => sum + group.items.length, 0);
+        if (dispatchableCount === 0)
+            return emptyPerGroup();
+        // Stable cache packs can be much smaller than either job ceiling. Split
+        // those packs across the live slots too, otherwise each serial dispatch
+        // feeds only one worker. Keep both configured ceilings as upper bounds.
+        const maxItemsPerJob = Math.min(poolOptions.subBatchSize, Math.max(1, Math.floor(dispatchableCount / activeSlots.size)));
+        // Lay the groups end to end on one index space and cut jobs at every group
+        // boundary. A job therefore belongs to exactly one group, which is what
+        // lets a result be attributed back to the parse-cache chunk that owns it
+        // (and what keeps `chunkHash` a per-job constant through splits/requeues).
+        const jobs = [];
+        const groupEnds = [];
+        let groupStart = 0;
+        for (const group of dispatchableGroups) {
+            for (const job of createJobs(group.items, maxItemsPerJob, poolOptions.subBatchMaxBytes, poolOptions.subBatchIdleTimeoutMs, group.chunkHash, groupStart)) {
+                jobs.push(job);
+            }
+            groupStart += group.items.length;
+            groupEnds.push(groupStart);
         }
-        if (dispatchableItems.length === 0)
-            return [];
-        const jobs = createJobs(dispatchableItems, poolOptions.subBatchSize, poolOptions.subBatchMaxBytes, poolOptions.subBatchIdleTimeoutMs, chunkHash);
-        return new Promise((resolve, reject) => {
+        return await new Promise((resolve, reject) => {
             const results = [];
             const inFlightProgress = new Array(size).fill(0);
             // Tracks which slots are currently mid-job so the "wake idle slots"
@@ -899,7 +966,7 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                 if (!onProgress)
                     return;
                 const inFlight = inFlightProgress.reduce((sum, value) => sum + value, 0);
-                const next = Math.min(dispatchableItems.length, Math.max(maxReported, completedFiles + inFlight));
+                const next = Math.min(dispatchableCount, Math.max(maxReported, completedFiles + inFlight));
                 if (next === maxReported)
                     return;
                 maxReported = next;
@@ -984,7 +1051,13 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                     retireWorkerAfterTimeout(existing, workerIndex, reason);
                     return;
                 }
-                await existing.terminate().catch(() => undefined);
+                // Recovery must settle before dispatch returns, but a failed thread
+                // may never acknowledge termination. Bound that wait as in shutdown.
+                const termination = existing.terminate().then(() => undefined, () => undefined);
+                if (!(await settledWithin(termination, poolOptions.shutdownDrainMs))) {
+                    existing.unref?.();
+                    logger.warn({ workerIndex, drainMs: poolOptions.shutdownDrainMs, reason }, `Worker ${workerIndex} did not finish terminating within the shutdown drain; continuing recovery.`);
+                }
             };
             const replaceWorker = async (workerIndex, mode = 'terminate', reason = 'replacing worker') => {
                 await removeWorkerFromSlot(workerIndex, mode, reason);
@@ -1057,9 +1130,20 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                 if (jobs.length === 0 && activeWorkers === 0) {
                     stopped = true;
                     results.sort((a, b) => a.startIndex - b.startIndex);
-                    if (onProgress && maxReported < dispatchableItems.length)
-                        onProgress(dispatchableItems.length);
-                    resolve(results.map((result) => result.data));
+                    if (onProgress && maxReported < dispatchableCount)
+                        onProgress(dispatchableCount);
+                    // Partition back per group. Job (and split sub-job) start indices
+                    // stay inside their group's span, so a single forward walk over the
+                    // sorted results assigns every result to exactly one group.
+                    const perGroup = groupEnds.map(() => []);
+                    let groupIdx = 0;
+                    for (const result of results) {
+                        while (groupIdx < groupEnds.length - 1 && result.startIndex >= groupEnds[groupIdx]) {
+                            groupIdx++;
+                        }
+                        perGroup[groupIdx].push(result.data);
+                    }
+                    resolve(perGroup);
                 }
             };
             // Re-queue the non-quarantined remainder of a dead worker's job so a
@@ -1357,11 +1441,13 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                 // (`error`, `exit`, msg-channel error). Bridges the per-job teardown
                 // into the pool-level handleWorkerDeath recovery + breaker logic.
                 const recoverAndResume = async (reason, excludePaths) => {
-                    activeWorkers--;
                     busySlots.delete(workerIndex);
                     inFlightProgress[workerIndex] = 0;
                     requeueRemainder(job, excludePaths);
+                    // Keep recovery in flight so another slot finishing cannot settle
+                    // this dispatch before the replacement is ready for the next one.
                     await handleWorkerDeath(workerIndex, reason, excludePaths);
+                    activeWorkers--;
                     if (stopped)
                         return;
                     // Slot may have been dropped or respawned. Kick the current slot
@@ -1406,10 +1492,10 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                                 // is respawned (or dropped) and can dispatch the next
                                 // job deterministically.
                                 void (async () => {
-                                    activeWorkers--;
                                     busySlots.delete(workerIndex);
                                     requeueRemainder(job, decision.excludePaths);
                                     await handleWorkerDeath(workerIndex, decision.reason, decision.excludePaths, 'retire');
+                                    activeWorkers--;
                                     if (stopped)
                                         return;
                                     if (activeSlots.has(workerIndex))
@@ -1689,8 +1775,13 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
         workers.length = 0;
         activeSlots.clear();
     };
+    const dispatch = async (items, onProgress, chunkHash) => {
+        const [result] = await dispatchGroups([{ items, chunkHash }], onProgress);
+        return result ?? [];
+    };
     return {
         dispatch,
+        dispatchGroups,
         terminate,
         size,
         getQuarantinedPaths: () => quarantine.snapshot(),

package/dist/core/lbug/csv-generator.js

@@ -455,6 +455,8 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseCo
         const multiLangHeader = 'id,name,filePath,startLine,endLine,content,description';
         const constHeader = `${multiLangHeader},convexEndpointFactory`;
         const MULTI_LANG_TYPES = [
+            'Protocol',
+            'Category',
             'Struct',
             'Enum',
             'Macro',

package/dist/core/lbug/schema.d.ts

@@ -15,6 +15,8 @@ export declare const FILE_SCHEMA = "\nCREATE NODE TABLE File (\n  id STRING,\n
 export declare const FOLDER_SCHEMA = "\nCREATE NODE TABLE Folder (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  PRIMARY KEY (id)\n)";
 export declare const FUNCTION_SCHEMA = "\nCREATE NODE TABLE Function (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  convexEndpointFactory STRING,\n  PRIMARY KEY (id)\n)";
 export declare const CLASS_SCHEMA = "\nCREATE NODE TABLE Class (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  frameworkAnnotations STRING[],\n  PRIMARY KEY (id)\n)";
+export declare const PROTOCOL_SCHEMA = "\nCREATE NODE TABLE Protocol (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
+export declare const CATEGORY_SCHEMA = "\nCREATE NODE TABLE Category (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const INTERFACE_SCHEMA = "\nCREATE NODE TABLE Interface (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const METHOD_SCHEMA = "\nCREATE NODE TABLE Method (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  parameterCount INT32,\n  returnType STRING,\n  PRIMARY KEY (id)\n)";
 export declare const CODE_ELEMENT_SCHEMA = "\nCREATE NODE TABLE CodeElement (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
@@ -94,7 +96,7 @@ export declare const BASICBLOCK_SCHEMA = "\nCREATE NODE TABLE BasicBlock (\n  id
  * `test/integration/structural-pair-coverage.test.ts` guards this half from a
  * corpus — that is the guard, not this comment.
  */
-export declare const STRUCTURAL_PAIR_DDL = "  FROM File TO Folder,\n  FROM File TO CodeElement,\n  FROM File TO `Typedef`,\n  FROM File TO `Namespace`,\n  FROM File TO `Impl`,\n  FROM File TO `Static`,\n  FROM File TO `Template`,\n  FROM File TO Section,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO `Template`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `Impl`,\n  FROM Function TO `Typedef`,\n  FROM Function TO CodeElement,\n  FROM Class TO `Template`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO CodeElement,\n  FROM Method TO `Template`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Impl`,\n  FROM Method TO CodeElement,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO CodeElement,\n  FROM `Module` TO `Namespace`,\n  FROM `Namespace` TO Function,\n  FROM CodeElement TO CodeElement,\n  FROM CodeElement TO `Module`,\n  FROM CodeElement TO `Property`,\n  FROM Section TO Section,\n  FROM Interface TO CodeElement,\n  FROM `Namespace` TO `Struct`,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO Function,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Typedef`,\n  FROM Route TO Process,\n  FROM Tool TO Process,\n  FROM Destination TO `Property`,\n  FROM BasicBlock TO BasicBlock";
+export declare const STRUCTURAL_PAIR_DDL = "  FROM File TO Folder,\n  FROM File TO CodeElement,\n  FROM File TO `Typedef`,\n  FROM File TO `Namespace`,\n  FROM File TO `Impl`,\n  FROM File TO `Static`,\n  FROM File TO `Template`,\n  FROM File TO Section,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO `Template`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `Impl`,\n  FROM Function TO `Typedef`,\n  FROM Function TO CodeElement,\n  FROM Class TO `Template`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO CodeElement,\n  FROM Method TO `Template`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Impl`,\n  FROM Method TO CodeElement,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO CodeElement,\n  FROM `Module` TO `Namespace`,\n  FROM `Namespace` TO Function,\n  FROM CodeElement TO CodeElement,\n  FROM CodeElement TO Class,\n  FROM CodeElement TO Category,\n  FROM CodeElement TO Method,\n  FROM CodeElement TO `Module`,\n  FROM CodeElement TO `Property`,\n  FROM Section TO Section,\n  FROM Interface TO CodeElement,\n  FROM `Namespace` TO `Struct`,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO Function,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Typedef`,\n  FROM Route TO Process,\n  FROM Tool TO Process,\n  FROM Destination TO `Property`,\n  FROM BasicBlock TO BasicBlock";
 export declare const RELATION_SCHEMA: string;
 export declare const EMBEDDING_DIMS: number;
 /** HNSW vector index name for the CodeEmbedding table. */