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

package/dist/core/ingestion/languages/zig/scope-resolver.js

@@ -5,17 +5,19 @@
  * Thin wiring: Zig has no inheritance (default MRO linearization over an
  * empty heritage set), no `super`, and is statically typed (field-fallback
  * heuristic off per the contract guidance). Import resolution reuses the
- * same `resolveZigImportInternal` the legacy import-resolver config wraps,
- * with `build.zig.zon` `.path` deps threaded through `loadResolutionConfig`.
+ * same `resolveZigImportInternal` the legacy import-resolver config wraps, with
+ * the repo's Zig build packages threaded through `loadResolutionConfig` and the
+ * one governing each file selected per-file by `zigPackageFor`.
  */
 import { SupportedLanguages } from '../../../../_shared/index.js';
 import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js';
 import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
-import { loadZigBuildConfig } from '../../language-config.js';
+import { loadZigWorkspaceIndex, zigPackageFor, } from '../../language-config.js';
 import { resolveZigImportInternal } from '../../import-resolvers/zig.js';
 import { zigProvider } from '../zig.js';
 import { expandZigWildcardNames, zigArityCompatibility, zigMergeBindings } from './index.js';
 import { populateZigRangeBindings } from './range-binding.js';
+import { populateZigWorkspaceStaticGating } from './workspace-static-gating.js';
 export const zigScopeResolver = {
     language: SupportedLanguages.Zig,
     languageProvider: zigProvider,
@@ -40,14 +42,25 @@ export const zigScopeResolver = {
     // (`opmod.Op.lookup.event_max()`) — walked hop by hop from the verified
     // import; a one-hop split at the last dot resolved none of them.
     resolveNamespaceChains: true,
-    loadResolutionConfig: (repoPath) => loadZigBuildConfig(repoPath),
-    resolveImportTarget: (targetRaw, fromFile, allFilePaths, resolutionConfig) => resolveZigImportInternal(fromFile, targetRaw, allFilePaths, resolutionConfig ?? null),
+    // The whole workspace, not just the root package. A Zig module's import table
+    // is declared by the `build.zig` of the package the file belongs to, so a repo
+    // laying its packages out as `packages/<name>/build.zig` has as many import
+    // tables as packages — and reading only the root one leaves every bare
+    // `@import("<module>")` in such a repo unresolved. Same shape, same reason, as
+    // `loadTsconfigIndex` for a TypeScript monorepo.
+    loadResolutionConfig: (repoPath) => loadZigWorkspaceIndex(repoPath),
+    resolveImportTarget: (targetRaw, fromFile, allFilePaths, resolutionConfig) => resolveZigImportInternal(fromFile, targetRaw, allFilePaths, 
+    // The package governing THIS file — `zigPackageFor` is the `tsconfigFor`
+    // analogue. `resolveZigImportInternal` is handed one package's config and
+    // is unchanged by this: which config it receives is the only difference.
+    zigPackageFor(resolutionConfig, fromFile)),
     // `pub usingnamespace @import("x.zig");` — target decls become local decls.
     expandsWildcardTo: (targetModuleScope, parsedFiles) => expandZigWildcardNames(targetModuleScope, parsedFiles),
     mergeBindings: zigMergeBindings,
     arityCompatibility: zigArityCompatibility,
     buildMro: (graph, parsedFiles, nodeLookup) => buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
     populateOwners: (parsed) => populateClassOwnedMembers(parsed),
+    populateWorkspaceReferences: populateZigWorkspaceStaticGating,
     // Payload captures — `for (items) |it|`, `if (opt) |v|`, `while (it.next())
     // |x|` — typed from the subject's binding after finalize (F6).
     populateRangeBindings: populateZigRangeBindings,

package/dist/core/ingestion/languages/zig/this-alias-bindings.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Bind a Zig `const X = @This();` alias to the container it names (#3219
+ * review round 8).
+ *
+ * `@This()` IS the enclosing container, and Zig code says so constantly: the
+ * single most common spelling is `const Self = @This();`, followed by
+ * `Alias.member` wherever the explicit form is wanted (`Self.width(self)`, a
+ * registration `bridge.accessor(Self.width, …)`, a nested type `Self.Node`).
+ * A compiler resolves `Self` and the container's own name to the same type.
+ * This index did not, for one specific reason:
+ *
+ *   - A container-level alias (`const Self = @This();` inside `struct {…}`)
+ *     mints a `Variable` beside the `Struct`, so `Self` binds to a VALUE. Every
+ *     class-like lookup filters on `isClassLike` and walks straight past it.
+ *   - A FILE-level alias in a file-as-struct mints nothing at all —
+ *     `isZigFileThisAlias` suppresses the Const deliberately, so it cannot
+ *     shadow the type for `x: *Page`. The name is then bound to nothing, while
+ *     the container itself is bound under the FILE STEM.
+ *
+ * So `Self.width` resolved only when the alias happened to be spelled like its
+ * container. Measured on the three Zig corpora on hand: 73 of ghostty's 185
+ * `@This()` files, 93 of tigerbeetle's 94 and 8 of mach's 42 spell it
+ * differently, carrying 302 `Alias.member` references between them, 96 of those
+ * calls. Those were not wrong edges — they were no edges, and a caller list
+ * missing them is exactly the false confidence #3399 is about.
+ *
+ * WHAT THIS ADDS, precisely: one binding of the alias NAME to the container's
+ * own definition, appended to `indexes.bindingAugmentations` (the sanctioned
+ * post-finalize channel, invariant I8 — `indexes.bindings` is frozen). The
+ * augmentation channel is consulted by `lookupBindingsAt` only AFTER a scope's
+ * own `Scope.bindings`, so this can never outrank a real local declaration: the
+ * `Variable` the container-level alias already mints still answers first for
+ * anything that wants a value, and the container answers for anything that
+ * wants a type. Nothing is replaced and nothing is removed.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO. Only aliases declared DIRECTLY in a
+ * container body or at file level are bound, which is the same set
+ * `collectZigThisAliases` recognizes for the type-rewrite path. A function-local
+ * `const Self = @This();` also names the enclosing container, but it belongs in
+ * that function's scope, not the container's, and binding it here would make it
+ * visible to sibling functions that never declared it.
+ */
+import type { ParsedFile } from '../../../../_shared/index.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+/**
+ * Bind every `@This()` alias declared in `parsed` at container or file level.
+ *
+ * Called per file from `populateZigRangeBindings`, which already holds the
+ * parsed tree — a second pass over `parsedFiles` would re-parse every file when
+ * the tree cache is cold. That is the only thing the two share. Ordering
+ * against the payload bindings that follow does not matter, twice over: the
+ * payload walk types its subjects through `findReceiverTypeBinding`, which
+ * never reads the channel written here, and a `@This()` alias is a
+ * container-private name no other file can import, so nothing outside this file
+ * reads it either.
+ */
+export declare function bindZigThisAliases(parsed: ParsedFile, root: SyntaxNode, indexes: ScopeResolutionIndexes): void;

package/dist/core/ingestion/languages/zig/this-alias-bindings.js

@@ -0,0 +1,176 @@
+/**
+ * Bind a Zig `const X = @This();` alias to the container it names (#3219
+ * review round 8).
+ *
+ * `@This()` IS the enclosing container, and Zig code says so constantly: the
+ * single most common spelling is `const Self = @This();`, followed by
+ * `Alias.member` wherever the explicit form is wanted (`Self.width(self)`, a
+ * registration `bridge.accessor(Self.width, …)`, a nested type `Self.Node`).
+ * A compiler resolves `Self` and the container's own name to the same type.
+ * This index did not, for one specific reason:
+ *
+ *   - A container-level alias (`const Self = @This();` inside `struct {…}`)
+ *     mints a `Variable` beside the `Struct`, so `Self` binds to a VALUE. Every
+ *     class-like lookup filters on `isClassLike` and walks straight past it.
+ *   - A FILE-level alias in a file-as-struct mints nothing at all —
+ *     `isZigFileThisAlias` suppresses the Const deliberately, so it cannot
+ *     shadow the type for `x: *Page`. The name is then bound to nothing, while
+ *     the container itself is bound under the FILE STEM.
+ *
+ * So `Self.width` resolved only when the alias happened to be spelled like its
+ * container. Measured on the three Zig corpora on hand: 73 of ghostty's 185
+ * `@This()` files, 93 of tigerbeetle's 94 and 8 of mach's 42 spell it
+ * differently, carrying 302 `Alias.member` references between them, 96 of those
+ * calls. Those were not wrong edges — they were no edges, and a caller list
+ * missing them is exactly the false confidence #3399 is about.
+ *
+ * WHAT THIS ADDS, precisely: one binding of the alias NAME to the container's
+ * own definition, appended to `indexes.bindingAugmentations` (the sanctioned
+ * post-finalize channel, invariant I8 — `indexes.bindings` is frozen). The
+ * augmentation channel is consulted by `lookupBindingsAt` only AFTER a scope's
+ * own `Scope.bindings`, so this can never outrank a real local declaration: the
+ * `Variable` the container-level alias already mints still answers first for
+ * anything that wants a value, and the container answers for anything that
+ * wants a type. Nothing is replaced and nothing is removed.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO. Only aliases declared DIRECTLY in a
+ * container body or at file level are bound, which is the same set
+ * `collectZigThisAliases` recognizes for the type-rewrite path. A function-local
+ * `const Self = @This();` also names the enclosing container, but it belongs in
+ * that function's scope, not the container's, and binding it here would make it
+ * visible to sibling functions that never declared it.
+ */
+import { isClassLike } from '../../scope-resolution/scope/walkers.js';
+import { isZigKeywordDeclaration, ZIG_CONTAINER_TYPES } from './captures.js';
+/** `const X = @This();` — the declaration shape, wherever it sits. */
+function thisAliasName(node) {
+    if (node.type !== 'variable_declaration' || !isZigKeywordDeclaration(node))
+        return undefined;
+    const named = node.namedChildren.filter((c) => c !== null);
+    if (named.length !== 2 || named[0].type !== 'identifier')
+        return undefined;
+    const value = named[1];
+    if (value.type !== 'builtin_function' || value.namedChild(0)?.text !== '@This')
+        return undefined;
+    return named[0].text;
+}
+/** The class-like definition a Class scope is the body of. */
+function containerDefOf(scope) {
+    return scope.ownedDefs.find((d) => isClassLike(d.type));
+}
+/**
+ * The Class scope of the FILE-AS-STRUCT, if this file is one.
+ *
+ * Identified by range rather than by name: it is the only Class scope that both
+ * hangs directly off the module scope AND spans the same lines as it. A
+ * namespace-only file with a top-level `pub const Counter = struct {…}` also
+ * produces a Class scope under the module scope, and it also carries the file
+ * stem when the file is `Counter.zig` — matching on the name would bind that
+ * file's `@This()` alias to `Counter`, which is not what `@This()` means there.
+ */
+function fileStructScope(scopes, moduleScope) {
+    return scopes.find((s) => s.kind === 'Class' &&
+        s.parent === moduleScope.id &&
+        s.range.startLine === moduleScope.range.startLine &&
+        s.range.endLine === moduleScope.range.endLine);
+}
+/**
+ * Innermost Class scope containing `node`.
+ *
+ * Compared on (line, column) rather than line alone, because a Zig container
+ * can nest inside another on ONE line — `const A = struct { const S = @This();
+ * const B = struct { const T = @This(); }; };` gives both scopes the same start
+ * line, and picking between them by line would be a coin toss that binds an
+ * alias to the wrong container. A wrong edge is the one outcome this whole
+ * change set treats as worse than no edge.
+ */
+function enclosingClassScope(scopes, node) {
+    const line = node.startPosition.row + 1;
+    const column = node.startPosition.column;
+    const startsAtOrBefore = (l, c) => l < line || (l === line && c <= column);
+    const endsAtOrAfter = (l, c) => l > line || (l === line && c >= column);
+    let best;
+    for (const s of scopes) {
+        if (s.kind !== 'Class')
+            continue;
+        if (!startsAtOrBefore(s.range.startLine, s.range.startCol))
+            continue;
+        if (!endsAtOrAfter(s.range.endLine, s.range.endCol))
+            continue;
+        if (best === undefined ||
+            s.range.startLine > best.range.startLine ||
+            (s.range.startLine === best.range.startLine && s.range.startCol > best.range.startCol)) {
+            best = s;
+        }
+    }
+    return best;
+}
+/**
+ * Append `alias -> def` at `scopeId`, skipping the append when THIS def is
+ * already bound there. Idempotence, not precedence: a duplicate would be
+ * harmless for lookup (`lookupBindingsAt` dedupes by `def.nodeId`) but would
+ * make the channel's contents depend on how many times the hook ran. Other
+ * bindings under the same name are left alone — the channel is append-only per
+ * I8, and the whole point of the augmentation tier is that a scope's own
+ * `Scope.bindings` are consulted first and still win.
+ */
+function appendBinding(indexes, scopeId, alias, def) {
+    const channel = indexes.bindingAugmentations;
+    let byName = channel.get(scopeId);
+    if (byName === undefined) {
+        byName = new Map();
+        channel.set(scopeId, byName);
+    }
+    const bucket = byName.get(alias);
+    if (bucket === undefined) {
+        byName.set(alias, [{ def, origin: 'local' }]);
+        return;
+    }
+    if (bucket.some((ref) => ref.def.nodeId === def.nodeId))
+        return;
+    bucket.push({ def, origin: 'local' });
+}
+/**
+ * Bind every `@This()` alias declared in `parsed` at container or file level.
+ *
+ * Called per file from `populateZigRangeBindings`, which already holds the
+ * parsed tree — a second pass over `parsedFiles` would re-parse every file when
+ * the tree cache is cold. That is the only thing the two share. Ordering
+ * against the payload bindings that follow does not matter, twice over: the
+ * payload walk types its subjects through `findReceiverTypeBinding`, which
+ * never reads the channel written here, and a `@This()` alias is a
+ * container-private name no other file can import, so nothing outside this file
+ * reads it either.
+ */
+export function bindZigThisAliases(parsed, root, indexes) {
+    const moduleScope = parsed.scopes.find((s) => s.kind === 'Module');
+    if (moduleScope === undefined)
+        return;
+    const fileStruct = fileStructScope(parsed.scopes, moduleScope);
+    const visit = (node) => {
+        const alias = thisAliasName(node);
+        if (alias !== undefined) {
+            const parent = node.parent;
+            if (parent?.type === 'source_file') {
+                // The file-as-struct's own name. Bound at the MODULE scope, which is
+                // where the container is already bound under the file stem, so the
+                // alias and the stem are visible to exactly the same sites.
+                const def = fileStruct === undefined ? undefined : containerDefOf(fileStruct);
+                if (def !== undefined)
+                    appendBinding(indexes, moduleScope.id, alias, def);
+            }
+            else if (parent !== null && ZIG_CONTAINER_TYPES.has(parent.type)) {
+                const scope = enclosingClassScope(parsed.scopes, node);
+                const def = scope === undefined ? undefined : containerDefOf(scope);
+                if (scope !== undefined && def !== undefined)
+                    appendBinding(indexes, scope.id, alias, def);
+            }
+        }
+        for (let i = 0; i < node.namedChildCount; i++) {
+            const child = node.namedChild(i);
+            if (child !== null)
+                visit(child);
+        }
+    };
+    visit(root);
+}

package/dist/core/ingestion/languages/zig/workspace-static-gating.d.ts

@@ -0,0 +1,8 @@
+import type { ParsedFile } from '../../../../_shared/index.js';
+export declare function populateZigWorkspaceStaticGating(parsedFiles: ParsedFile[], ctx: {
+    readonly fileContents: ReadonlyMap<string, string>;
+    readonly treeCache?: {
+        get(filePath: string): unknown;
+    };
+    readonly resolutionConfig?: unknown;
+}): void;

package/dist/core/ingestion/languages/zig/workspace-static-gating.js

@@ -0,0 +1,82 @@
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { zigPackageFor } from '../../language-config.js';
+import { resolveZigImportInternal } from '../../import-resolvers/zig.js';
+import { buildZigBoolConstMap, collectZigStaticGatedRanges, isPositionStaticGated, } from '../../call-extractors/zig-static-gating.js';
+import { parseSourceSafe, ParseTimeoutError } from '../../../tree-sitter/safe-parse.js';
+import { getZigParser } from './query.js';
+export function populateZigWorkspaceStaticGating(parsedFiles, ctx) {
+    const parser = getZigParser();
+    const trees = new Map();
+    const bools = new Map();
+    for (const parsed of parsedFiles) {
+        const source = ctx.fileContents.get(parsed.filePath);
+        if (source === undefined)
+            continue;
+        let tree = ctx.treeCache?.get(parsed.filePath);
+        if (tree === undefined) {
+            try {
+                tree = parseSourceSafe(parser, source, undefined, {
+                    bufferSize: getTreeSitterBufferSize(source),
+                });
+            }
+            catch (err) {
+                if (err instanceof ParseTimeoutError)
+                    continue;
+                throw err;
+            }
+        }
+        trees.set(parsed.filePath, tree);
+        bools.set(parsed.filePath, buildZigBoolConstMap(tree.rootNode));
+    }
+    const knownPaths = new Set(trees.keys());
+    for (const [index, parsed] of parsedFiles.entries()) {
+        const tree = trees.get(parsed.filePath);
+        if (tree === undefined)
+            continue;
+        const aliases = collectImportAliases(tree, parsed.filePath, knownPaths, 
+        // `resolutionConfig` is the whole Zig workspace; the package governing
+        // THIS file is what `resolveZigImportInternal` takes. Selected here rather
+        // than hoisted out of the loop because the answer is per-file: two files
+        // of this pass can belong to different packages.
+        zigPackageFor(ctx.resolutionConfig, parsed.filePath));
+        if (aliases.size === 0)
+            continue;
+        const ranges = collectZigStaticGatedRanges(tree.rootNode, bools.get(parsed.filePath) ?? new Map(), aliases, (filePath) => bools.get(filePath));
+        if (ranges.length === 0)
+            continue;
+        const next = parsed.referenceSites.map((site) => site.kind === 'call' &&
+            site.staticGated !== true &&
+            isPositionStaticGated(site.atRange.startLine, site.atRange.startCol, ranges)
+            ? { ...site, staticGated: true }
+            : site);
+        parsedFiles[index] = Object.freeze({ ...parsed, referenceSites: Object.freeze(next) });
+    }
+}
+function collectImportAliases(tree, fromFile, knownPaths, packageConfig) {
+    const candidates = new Map();
+    const declarationCounts = new Map();
+    for (const decl of tree.rootNode.descendantsOfType('variable_declaration')) {
+        const names = decl.namedChildren.filter((node) => node.type === 'identifier');
+        const binding = names[0]?.text;
+        if (binding === undefined)
+            continue;
+        declarationCounts.set(binding, (declarationCounts.get(binding) ?? 0) + 1);
+        const builtin = decl.namedChildren.find((node) => node.type === 'builtin_function' && node.text.startsWith('@import('));
+        const raw = builtin?.descendantsOfType('string').at(0)?.text;
+        if (raw === undefined)
+            continue;
+        const specifier = raw.replace(/^['"]|['"]$/g, '');
+        const target = resolveZigImportInternal(fromFile, specifier, knownPaths, packageConfig);
+        if (target !== null)
+            candidates.set(binding, target);
+    }
+    const aliases = new Map();
+    for (const [binding, target] of candidates) {
+        // Alias lookup below is name-based rather than position-aware. If a name
+        // is redeclared in another lexical scope, fail open instead of applying
+        // either module's constants to every use of that spelling.
+        if (declarationCounts.get(binding) === 1)
+            aliases.set(binding, target);
+    }
+    return aliases;
+}

package/dist/core/ingestion/model/registration-table.d.ts

@@ -15,11 +15,11 @@
  *       └── symbols (SymbolTable)     ← owns fileIndex + callableByName,
  *                                       calls dispatch() in add()
  *
- * ## Behavior groups (5 hooks, 13 table entries)
+ * ## Behavior groups (4 hooks, 12 table entries)
  *
  * | Group         | NodeLabel values                                  | Hook         | Skip callable? |
  * |---------------|---------------------------------------------------|--------------|----------------|
- * | class-like    | Class, Struct, Interface, Enum, Record, Trait     | classLikeHook    | no             |
+ * | class-like    | Class, Protocol, Category, Struct, Interface, Enum, Record, Trait | classLikeHook    | no             |
  * | method-like   | Method, Constructor                               | methodHook   | no             |
  * | property      | Property                                          | propertyHook | YES            |
  * | impl-block    | Impl                                              | implHook     | no             |
@@ -81,7 +81,7 @@ export interface RegistrationTableDeps {
  * registry (if any) receives the symbol write during `SymbolTable.add()`:
  *
  *   - `dispatch`     — owner-scoped registry write via the dispatch table
- *                      (Class/Struct/Interface/Enum/Record/Trait → types.registerClass,
+ *                      (Class/Protocol/Category/Struct/Interface/Enum/Record/Trait → types.registerClass,
  *                       Method/Constructor → methods.register,
  *                       Property → fields.register,
  *                       Impl → types.registerImpl)

package/dist/core/ingestion/model/registration-table.js

@@ -15,11 +15,11 @@
  *       └── symbols (SymbolTable)     ← owns fileIndex + callableByName,
  *                                       calls dispatch() in add()
  *
- * ## Behavior groups (5 hooks, 13 table entries)
+ * ## Behavior groups (4 hooks, 12 table entries)
  *
  * | Group         | NodeLabel values                                  | Hook         | Skip callable? |
  * |---------------|---------------------------------------------------|--------------|----------------|
- * | class-like    | Class, Struct, Interface, Enum, Record, Trait     | classLikeHook    | no             |
+ * | class-like    | Class, Protocol, Category, Struct, Interface, Enum, Record, Trait | classLikeHook    | no             |
  * | method-like   | Method, Constructor                               | methodHook   | no             |
  * | property      | Property                                          | propertyHook | YES            |
  * | impl-block    | Impl                                              | implHook     | no             |
@@ -79,6 +79,8 @@ import { FREE_CALLABLE_TYPES } from './symbol-table.js';
 const LABEL_BEHAVIOR = {
     // dispatch — owner-scoped registry writes
     Class: 'dispatch',
+    Protocol: 'dispatch',
+    Category: 'dispatch',
     Struct: 'dispatch',
     Interface: 'dispatch',
     Enum: 'dispatch',
@@ -169,8 +171,8 @@ export const DISPATCH_LABELS = new Set(labelsWithBehavior('dispatch'));
  */
 export const createRegistrationTable = (deps) => {
     const { types, methods, fields } = deps;
-    // Hook 1: class-like — Class, Struct, Interface, Enum, Record, Trait.
-    // Shared reference — six table entries point at this one closure.
+    // Hook 1: class-like — Class, Protocol, Category, Struct, Interface, Enum, Record, Trait.
+    // Shared reference — eight table entries point at this one closure.
     const classLikeHook = (name, def) => {
         const qualifiedKey = def.qualifiedName ?? name;
         types.registerClass(name, qualifiedKey, def);
@@ -205,11 +207,13 @@ export const createRegistrationTable = (deps) => {
     // classified as 'dispatch'. This is the compile-time twin of the
     // runtime taxonomy — no drift possible.
     const dispatchByLabel = {
-        // class-like — six labels share the single `classLikeHook` closure,
+        // class-like — eight labels share the single `classLikeHook` closure,
         // kept in lockstep with `CLASS_TYPES_TUPLE` via the
         // `Record<ClassLikeLabel, 'dispatch'>` cross-invariant on
         // `LABEL_BEHAVIOR`.
         Class: classLikeHook,
+        Protocol: classLikeHook,
+        Category: classLikeHook,
         Struct: classLikeHook,
         Interface: classLikeHook,
         Enum: classLikeHook,

package/dist/core/ingestion/model/symbol-table.d.ts

@@ -52,7 +52,7 @@ import type { NodeLabel, ParameterTypeClass, SymbolDefinition } from '../../../_
  * `impl Trait for Struct`, and Scala traits all contribute methods to the
  * hierarchy of their using/implementing type.
  */
-export declare const CLASS_TYPES_TUPLE: readonly ["Class", "Struct", "Interface", "Enum", "Record", "Trait"];
+export declare const CLASS_TYPES_TUPLE: readonly ["Class", "Protocol", "Category", "Struct", "Interface", "Enum", "Record", "Trait"];
 export type ClassLikeLabel = (typeof CLASS_TYPES_TUPLE)[number];
 export declare const CLASS_TYPES: ReadonlySet<NodeLabel>;
 /** Free-callable labels — single source of truth for "callables that have

package/dist/core/ingestion/model/symbol-table.js

@@ -53,6 +53,8 @@
  */
 export const CLASS_TYPES_TUPLE = [
     'Class',
+    'Protocol',
+    'Category',
     'Struct',
     'Interface',
     'Enum',

package/dist/core/ingestion/model/type-registry.d.ts

@@ -8,7 +8,7 @@
 import type { SymbolDefinition } from '../../../_shared/index.js';
 export interface TypeRegistry {
     /**
-     * Look up class-like definitions (Class, Struct, Interface, Enum, Record, Trait)
+     * Look up class-like definitions (Class, Protocol, Category, Struct, Interface, Enum, Record, Trait)
      * by simple name. Returns all matching definitions across files
      * (e.g. partial classes). Returned array is a view into the live
      * internal index — do not mutate.

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

@@ -3,6 +3,7 @@ import type { SymbolTableWriter } from './model/index.js';
 import { type ExportedTypeMap } from './call-processor.js';
 import type { ParsedFile } from '../../_shared/index.js';
 import { WorkerPool } from './workers/worker-pool.js';
+import type { DispatchGroup } from './workers/worker-pool.js';
 import type { ParseWorkerResult, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedModuleConstants, ExtractedToolDef, FileScopeBindings, ExtractedORMQuery, FetchWrapperDef } from './workers/parse-worker.js';
 import type { ExtractedRouterConstructorPrefix, ExtractedRouterImport, ExtractedRouterInclude, ExtractedRouterModuleAlias } from './route-extractors/fastapi-router-bindings.js';
 import type { SharedSpringType } from './route-extractors/spring-shared.js';
@@ -47,12 +48,12 @@ export interface WorkerExtractedData {
  */
 export declare const mergeChunkResults: (graph: KnowledgeGraph, symbolTable: SymbolTableWriter, chunkResults: readonly ParseWorkerResult[], exportedTypeMap?: ExportedTypeMap) => WorkerExtractedData;
 /**
- * Dispatch a chunk's files to the worker pool and return the RAW per-worker
- * results, WITHOUT merging them into the graph. Split out from
- * {@link processParsing} so the parse loop can overlap one chunk's
- * merge (main-thread, via {@link mergeChunkResults}) with the NEXT chunk's
- * worker parse — the merge is the only remaining serial main-thread step once
- * ParsedFile serialization moved into the workers (#worker-idle pipelining).
+ * Dispatch ONE chunk's files to the worker pool and return the RAW per-worker
+ * results, WITHOUT merging them into the graph. A thin single-group wrapper
+ * over {@link dispatchChunkParseRound}, used by {@link processParsing}'s
+ * one-shot path. The chunk-to-chunk overlap this once described now lives in
+ * `parse-impl.ts` at ROUND granularity (`startRound` / `drainRound` /
+ * `closeRound`), which batches several chunks into one dispatch.
  * Returns `[]` for an all-unparseable chunk (the caller merges `[]` → empty).
  */
 export declare const dispatchChunkParse: (files: {
@@ -67,6 +68,21 @@ outRawResults?: ParseWorkerResult[],
  * (#2038). `undefined` ⇒ no durable write (tests / no-cache path).
  */
 chunkHash?: string) => Promise<ParseWorkerResult[]>;
+/**
+ * Dispatch SEVERAL parse-cache chunks as one pool round and return their raw
+ * results, one array per input group in input order.
+ *
+ * `WorkerPool.dispatch` is a barrier, so one round-trip per chunk leaves most
+ * slots idle whenever a chunk is smaller than the pool — which stable
+ * `(language, hash(path) % 128)` packs usually are. Batching chunks into one
+ * `dispatchGroups` call removes those barriers; jobs are still cut at chunk
+ * boundaries, so every result stays attributable to the chunk whose cache key
+ * owns it.
+ */
+export declare const dispatchChunkParseRound: (groups: ReadonlyArray<DispatchGroup<{
+    path: string;
+    content: string;
+}>>, workerPool: WorkerPool, onFileProgress?: FileProgressCallback) => Promise<ParseWorkerResult[][]>;
 export declare const processParsing: (graph: KnowledgeGraph, files: {
     path: string;
     content: string;

package/dist/core/ingestion/parsing-processor.js

@@ -1,4 +1,4 @@
-import { getLanguageFromFilename } from '../../_shared/index.js';
+import { getLanguageForFileContent } from './languages/index.js';
 import { accumulateExportedTypesFromParsedNode } from './call-processor.js';
 import { logger } from '../logger.js';
 function compareText(left, right) {
@@ -147,12 +147,12 @@ export const mergeChunkResults = (graph, symbolTable, chunkResults, exportedType
     };
 };
 /**
- * Dispatch a chunk's files to the worker pool and return the RAW per-worker
- * results, WITHOUT merging them into the graph. Split out from
- * {@link processParsing} so the parse loop can overlap one chunk's
- * merge (main-thread, via {@link mergeChunkResults}) with the NEXT chunk's
- * worker parse — the merge is the only remaining serial main-thread step once
- * ParsedFile serialization moved into the workers (#worker-idle pipelining).
+ * Dispatch ONE chunk's files to the worker pool and return the RAW per-worker
+ * results, WITHOUT merging them into the graph. A thin single-group wrapper
+ * over {@link dispatchChunkParseRound}, used by {@link processParsing}'s
+ * one-shot path. The chunk-to-chunk overlap this once described now lives in
+ * `parse-impl.ts` at ROUND granularity (`startRound` / `drainRound` /
+ * `closeRound`), which batches several chunks into one dispatch.
  * Returns `[]` for an all-unparseable chunk (the caller merges `[]` → empty).
  */
 export const dispatchChunkParse = async (files, workerPool, onFileProgress, 
@@ -164,23 +164,42 @@ outRawResults,
  * (#2038). `undefined` ⇒ no durable write (tests / no-cache path).
  */
 chunkHash) => {
-    const parseableFiles = [];
-    for (const file of files) {
-        const lang = getLanguageFromFilename(file.path);
-        if (lang)
-            parseableFiles.push({ path: file.path, content: file.content });
-    }
-    if (parseableFiles.length === 0)
-        return [];
-    const total = files.length;
-    const chunkResults = await workerPool.dispatch(parseableFiles, (filesProcessed) => {
-        onFileProgress?.(Math.min(filesProcessed, total), total, 'Parsing...');
-    }, chunkHash);
+    const [chunkResults = []] = await dispatchChunkParseRound([{ items: files, chunkHash }], workerPool, onFileProgress);
     // Capture raw results for the incremental parse cache before merging.
     if (outRawResults) {
         for (const r of chunkResults)
             outRawResults.push(r);
     }
+    return chunkResults;
+};
+/**
+ * Dispatch SEVERAL parse-cache chunks as one pool round and return their raw
+ * results, one array per input group in input order.
+ *
+ * `WorkerPool.dispatch` is a barrier, so one round-trip per chunk leaves most
+ * slots idle whenever a chunk is smaller than the pool — which stable
+ * `(language, hash(path) % 128)` packs usually are. Batching chunks into one
+ * `dispatchGroups` call removes those barriers; jobs are still cut at chunk
+ * boundaries, so every result stays attributable to the chunk whose cache key
+ * owns it.
+ */
+export const dispatchChunkParseRound = async (groups, workerPool, onFileProgress) => {
+    const dispatchGroups = groups.map((group) => {
+        const items = [];
+        for (const file of group.items) {
+            const lang = getLanguageForFileContent(file.path, file.content);
+            if (lang)
+                items.push({ path: file.path, content: file.content });
+        }
+        return { items, chunkHash: group.chunkHash };
+    });
+    const total = groups.reduce((sum, group) => sum + group.items.length, 0);
+    if (dispatchGroups.every((group) => group.items.length === 0))
+        return groups.map(() => []);
+    const perGroup = await workerPool.dispatchGroups(dispatchGroups, (filesProcessed) => {
+        onFileProgress?.(Math.min(filesProcessed, total), total, 'Parsing...');
+    });
+    const chunkResults = perGroup.flat();
     // Skipped-language telemetry (worker output, independent of the merge).
     const skippedLanguages = new Map();
     for (const result of chunkResults) {
@@ -238,7 +257,7 @@ chunkHash) => {
         logger.warn(`  Sanitized ${skippedPaths.length} file(s) with non-serializable parse output: ${shown}${more}`);
     }
     onFileProgress?.(total, total, 'done');
-    return chunkResults;
+    return perGroup;
 };
 // ============================================================================
 // Public API

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

@@ -17,7 +17,7 @@
 import { BindingAccumulator } from '../binding-accumulator.js';
 import { type ExportedTypeMap } from '../call-processor.js';
 import { type MutableSemanticModel } from '../model/index.js';
-import { type PipelineProgress } from '../../../_shared/index.js';
+import { type PipelineProgress, SupportedLanguages } from '../../../_shared/index.js';
 import type { ExtractedDecoratorRoute, ExtractedFetchCall, ExtractedORMQuery, ExtractedRoute, ExtractedToolDef, FetchWrapperDef } from '../workers/parse-worker.js';
 import type { ModuleConstants } from '../route-extractors/constant-resolver.js';
 import type { KnowledgeGraph } from '../../graph/types.js';
@@ -104,6 +104,14 @@ export declare function runChunkedParseAndResolve(graph: KnowledgeGraph, scanned
      *  cache analyze run can skip the dominant `extractParsedFile` cost
      *  (otherwise ~58s on a 1000-file repo). */
     parsedFiles: import('../../../_shared/index.js').ParsedFile[];
+    /**
+     * Content-derived language decisions for extension-ambiguous files.
+     *
+     * The source text used to classify these paths is released before parsing
+     * begins. Scope resolution consumes this snapshot instead of reading the
+     * same files again just to repeat classification.
+     */
+    contentLanguageByPath: ReadonlyMap<string, SupportedLanguages | null>;
     /** Repo-wide harvested constants, already prepared per provider. See
      *  `ParseOutput.moduleConstants` for why this leaves the parse phase. */
     moduleConstants: ReadonlyMap<string, ModuleConstants>;