arceus-s 1.6.4

package/dist/core/ingestion/binding-accumulator.js

@@ -0,0 +1,336 @@
+/**
+ * BindingAccumulator — read-append-only accumulator that collects TypeEnv
+ * bindings across files in the Arceus analyzer pipeline.
+ *
+ * **Current behavior (both execution paths):** The accumulator carries only
+ * file-scope (`scope = ''`) entries. Function-scope bindings are stripped
+ * at both write sites:
+ *
+ * - **Worker path**: `parse-worker.ts` serializes only
+ *   `typeEnv.fileScope()` entries across the IPC boundary.
+ * - **Sequential path**: `type-env.ts::flush()` iterates only the FILE_SCOPE
+ *   entry of the env map and writes `BindingEntry` records with
+ *   `scope: ''` hardcoded.
+ *
+ * The narrowing exists because function-scope bindings have zero downstream
+ * consumers today and were previously costing ~4.9 MB of heap + IPC on
+ * every pipeline run. See `type-env.ts::flush()` and the `FileScopeBindings`
+ * JSDoc in `parse-worker.ts` for the paired Phase 9 reversion checklist.
+ *
+ * **Historical quality asymmetry (Phase 9 consideration):** Even though
+ * both paths now carry only file-scope data, the two paths were built
+ * under different resolution capabilities, and a future Phase 9 reverter
+ * that widens them back to all scopes will inherit that asymmetry:
+ *
+ * - **Sequential path** had (and would regain) access to the full
+ *   `SymbolTable` and `importedBindings`, so its bindings benefit from
+ *   Tier 2 cross-file propagation.
+ * - **Worker path** runs without `SymbolTable` / `importedBindings` and
+ *   can only produce Tier 0 (annotation-declared) and local Tier 1
+ *   (same-file constructor inference) bindings.
+ *
+ * Phase 9 consumers that trust every entry equally will silently produce
+ * worse results for large repos (worker-dominant) than small ones
+ * (sequential-dominant). If Phase 9 needs homogeneous quality, either
+ * (a) tag entries with their tier at insert time so consumers can filter,
+ * or (b) post-process worker-path entries through a follow-up resolution
+ * pass after the main-thread `SymbolTable` is complete.
+ *
+ * **Lifecycle contract**: single-use — `append* → finalize → consume → dispose`.
+ * After `dispose()` the accumulator is permanently dead: any mutating call
+ * (`appendFile`) throws, and read methods return empty/undefined as if the
+ * accumulator had never been appended to. The instance is not recyclable;
+ * construct a new one for a new pipeline run. Finalization and disposal are
+ * orthogonal state dimensions and may be invoked in either order.
+ */
+/**
+ * Merge file-scope bindings from a (finalized) `BindingAccumulator` into an
+ * `exportedTypeMap` for symbols whose graph nodes are marked as exported.
+ *
+ * This is the single source of truth for the worker-path ExportedTypeMap
+ * enrichment loop. Previously the logic lived inline in `pipeline.ts` and
+ * the test suite reimplemented it as a `runEnrichmentLoop` helper — a
+ * drift-prone pattern that meant tests could pass while production regressed.
+ * Extracting it here makes the production code call the same function the
+ * tests call.
+ *
+ * **Node ID candidate order**: `Function:{filePath}:{name}` →
+ * `Variable:{filePath}:{name}` → `Const:{filePath}:{name}`. First match wins.
+ *
+ * **Tier 0 priority**: if `exportedTypeMap` already has an entry for a
+ * `(filePath, name)` pair, the accumulator entry does NOT overwrite it —
+ * the SymbolTable tier-0 pass is authoritative. Without this guard, a
+ * worker-path binding could clobber a higher-quality type from SymbolTable.
+ *
+ * **Finalize precondition**: the accumulator should be finalized before
+ * calling this function. The lifecycle contract is
+ * `append → finalize → enrich → dispose`. Finalization is not asserted
+ * here (the test suite and pipeline both honor it separately), but any
+ * append happening concurrently with this enrichment would be a lifecycle
+ * bug at the caller level.
+ *
+ * @returns The number of new entries written into `exportedTypeMap`
+ *          (0 on empty accumulator or when every candidate was filtered
+ *          out by the export check or the Tier 0 guard).
+ */
+export function enrichExportedTypeMap(bindingAccumulator, graph, exportedTypeMap) {
+    if (bindingAccumulator.fileCount === 0)
+        return 0;
+    let enriched = 0;
+    for (const filePath of bindingAccumulator.files()) {
+        for (const [name, type] of bindingAccumulator.fileScopeEntries(filePath)) {
+            // Three-candidate-ID lookup mirrors the sequential-path export check
+            // in `collectExportedBindings()` (call-processor.ts).
+            const functionNodeId = `Function:${filePath}:${name}`;
+            const variableNodeId = `Variable:${filePath}:${name}`;
+            const constNodeId = `Const:${filePath}:${name}`;
+            const node = graph.getNode(functionNodeId) ??
+                graph.getNode(variableNodeId) ??
+                graph.getNode(constNodeId);
+            if (!node?.properties?.isExported)
+                continue;
+            let fileExports = exportedTypeMap.get(filePath);
+            if (!fileExports) {
+                fileExports = new Map();
+                exportedTypeMap.set(filePath, fileExports);
+            }
+            // Tier 0 priority: SymbolTable-populated entries are authoritative.
+            if (!fileExports.has(name)) {
+                fileExports.set(name, type);
+                enriched++;
+            }
+        }
+    }
+    return enriched;
+}
+const ENTRY_OVERHEAD = 64; // bytes per entry (object overhead + property refs)
+const MAP_ENTRY_OVERHEAD = 80; // bytes per file entry in the map
+export class BindingAccumulator {
+    // Storage is split into two parallel maps so file-scope reads are fast.
+    // - _allByFile holds every BindingEntry (used by getFile, memory estimate).
+    // - _fileScopeByFile is a nested Map<filePath, Map<varName, typeName>> for
+    //   O(1) point-lookup via fileScopeGet(). For iteration-based consumers
+    //   (enrichExportedTypeMap), fileScopeEntries() iterates the inner Map.
+    //   Both maps carry the same key set modulo the `scope === ''` precondition:
+    //   _allByFile has a key as soon as any entry is appended; _fileScopeByFile
+    //   only has a key once a file-scope entry arrives. Code that iterates via
+    //   files() uses _allByFile so files with only function-scope entries
+    //   remain visible.
+    //
+    //   Note: Map.set semantics mean a duplicate varName for the same file
+    //   overwrites the previous value (last-write-wins). This is the correct
+    //   behavior — duplicate top-level bindings in the same file shouldn't
+    //   happen in well-formed source, and if they do the last declaration
+    //   is typically the one the compiler sees.
+    _allByFile = new Map();
+    _fileScopeByFile = new Map();
+    _totalBindings = 0;
+    _finalized = false;
+    _disposed = false;
+    /**
+     * Append bindings for a file. Safe to call multiple times for the same file.
+     * Throws if the accumulator has been finalized. Skips if entries is empty.
+     *
+     * The `entries` parameter is `readonly` — this method never mutates the
+     * caller's array. Internally, the first `appendFile` call per filePath
+     * makes a defensive copy (`slice()`), and subsequent calls push into the
+     * accumulator's own storage.
+     */
+    appendFile(filePath, entries) {
+        if (this._finalized) {
+            throw new Error('[BindingAccumulator] appendFile after finalize — no further appends allowed');
+        }
+        // Single-use lifecycle: once disposed, the accumulator is dead. A
+        // post-dispose append almost always indicates a missed wiring step
+        // (the consumer is reading state that was supposed to be released),
+        // so convert the silent use-after-dispose into a loud failure.
+        if (this._disposed) {
+            throw new Error('BindingAccumulator: use after dispose');
+        }
+        if (entries.length === 0) {
+            return;
+        }
+        // Note on the file-scope-only invariant:
+        // The accumulator does NOT reject function-scope entries at this
+        // boundary. The narrowing contract is enforced by the two production
+        // write sites — `parse-worker.ts` (which uses `typeEnv.fileScope()`
+        // and hardcodes `scope: ''` in the pipeline adapter) and
+        // `type-env.ts::flush()` (which iterates only `env.get(FILE_SCOPE)`).
+        // The class JSDoc documents the invariant and the Phase 9 reversion
+        // path. Making `appendFile` runtime-reject non-file-scope entries
+        // would break the accumulator's own storage-split tests which
+        // legitimately exercise mixed-scope entries. If a future write path
+        // violates the invariant, tests should fail via missing exports in
+        // the enrichment loop, not via an assertion here.
+        // All-scope store.
+        const existingAll = this._allByFile.get(filePath);
+        if (existingAll !== undefined) {
+            for (const e of entries) {
+                existingAll.push(e);
+            }
+        }
+        else {
+            this._allByFile.set(filePath, entries.slice());
+        }
+        // File-scope fast-path store (nested Map for O(1) point-lookup via fileScopeGet).
+        // Populated lazily on first file-scope entry per file.
+        let fileScopeMap = this._fileScopeByFile.get(filePath);
+        for (const e of entries) {
+            if (e.scope === '') {
+                if (fileScopeMap === undefined) {
+                    fileScopeMap = new Map();
+                    this._fileScopeByFile.set(filePath, fileScopeMap);
+                }
+                fileScopeMap.set(e.varName, e.typeName);
+            }
+        }
+        this._totalBindings += entries.length;
+    }
+    /** Lock the accumulator — no further appends. Idempotent. */
+    finalize() {
+        // Dev-mode invariant: verify the parallel storage split is consistent.
+        // `_fileScopeByFile` must be a proper projection of `_allByFile`
+        // where the outer key is a subset and the inner entries are exactly
+        // the `scope === ''` subset of `_allByFile[key]`. A drift would
+        // indicate a bug in `appendFile()` where one map was updated but
+        // not the other.
+        if (process.env.NODE_ENV !== 'production' && !this._finalized) {
+            for (const [filePath, fileScopeMap] of this._fileScopeByFile) {
+                const allEntries = this._allByFile.get(filePath);
+                if (allEntries === undefined) {
+                    throw new Error(`[BindingAccumulator] storage split drift: file ${filePath} has file-scope entries ` +
+                        `but no _allByFile entry`);
+                }
+                // Count unique file-scope varNames in _allByFile (to match Map dedup
+                // semantics in _fileScopeByFile where Map.set deduplicates same-name).
+                const projectedNames = new Set(allEntries.filter((e) => e.scope === '').map((e) => e.varName));
+                if (projectedNames.size !== fileScopeMap.size) {
+                    throw new Error(`[BindingAccumulator] storage split drift: file ${filePath} has ` +
+                        `${fileScopeMap.size} file-scope names in Map but ${projectedNames.size} unique ` +
+                        `file-scope varNames in _allByFile`);
+                }
+            }
+        }
+        this._finalized = true;
+    }
+    /**
+     * Release the accumulator's heap footprint. Clears both internal storage
+     * maps and resets `_totalBindings` to zero. Idempotent — calling twice
+     * is a no-op. Orthogonal to `finalize()` — calling `dispose()` does not
+     * change the finalized state.
+     *
+     * **Single-use lifecycle.** This is a one-way terminal transition: the
+     * accumulator is not recyclable. Any subsequent `appendFile` call throws
+     * (`'BindingAccumulator: use after dispose'`), regardless of whether
+     * `finalize()` was called first. Post-dispose reads do not throw —
+     * they return empty/undefined state matching a never-appended-to
+     * accumulator:
+     *   - `fileCount === 0`
+     *   - `totalBindings === 0`
+     *   - `files()` yields an empty iterator
+     *   - `getFile(x)` returns `undefined` for all `x`
+     *   - `fileScopeEntries(x)` returns `[]` for all `x`
+     *   - `fileScopeGet(x, y)` returns `undefined` for all `x, y`
+     *   - `estimateMemoryBytes()` returns `0`
+     *
+     * Lifecycle note: the pipeline disposes the accumulator inside the
+     * `finally` of the `crossFile` phase, which is scheduled after every
+     * other accumulator consumer (Phase 9 call/assignment processing and
+     * the ExportedTypeMap enrichment loop). The dispose call therefore
+     * runs once, on both the happy path and the throw path of the
+     * crossFile phase.
+     */
+    dispose() {
+        this._allByFile.clear();
+        this._fileScopeByFile.clear();
+        this._totalBindings = 0;
+        this._disposed = true;
+    }
+    /** Get all bindings for a file, or undefined if the file is unknown. */
+    getFile(filePath) {
+        return this._allByFile.get(filePath);
+    }
+    /**
+     * Get only scope='' (file-level) entries as [varName, typeName] tuples.
+     * For iteration-based consumers (e.g., `enrichExportedTypeMap`).
+     * Returns an empty array for an unknown file.
+     *
+     * O(1) map lookup + O(n_file_scope) tuple reconstruction from the inner
+     * Map. Does NOT walk function-scope entries.
+     *
+     * For point-lookup consumers (e.g., Phase 9 fallback), prefer
+     * `fileScopeGet(filePath, name)` — O(1) with no allocation.
+     */
+    fileScopeEntries(filePath) {
+        const map = this._fileScopeByFile.get(filePath);
+        return map ? [...map.entries()] : [];
+    }
+    /**
+     * O(1) point-lookup for a single file-scope binding by (filePath, name).
+     * Returns the typeName if found, `undefined` otherwise.
+     *
+     * This is the preferred lookup path for Phase 9 consumers that resolve
+     * a single callee's return type — avoids the O(n_file_scope) iteration
+     * and defensive-copy allocation of `fileScopeEntries()`.
+     */
+    fileScopeGet(filePath, name) {
+        return this._fileScopeByFile.get(filePath)?.get(name);
+    }
+    /** Iterate over all file paths in insertion order. */
+    files() {
+        return this._allByFile.keys();
+    }
+    /** Number of distinct files with at least one binding. */
+    get fileCount() {
+        return this._allByFile.size;
+    }
+    /** Total number of binding entries across all files. */
+    get totalBindings() {
+        return this._totalBindings;
+    }
+    /** Whether the accumulator has been finalized. */
+    get finalized() {
+        return this._finalized;
+    }
+    /**
+     * Whether the accumulator has been disposed. Exposed for symmetry with
+     * `finalized` so debug tooling and future Phase 9 consumers can detect a
+     * disposed accumulator without inspecting empty state heuristically.
+     *
+     * Disposal and finalization are orthogonal: a disposed accumulator may or
+     * may not be finalized, and vice versa. See `dispose()` for the full
+     * lifecycle contract.
+     */
+    get disposed() {
+        return this._disposed;
+    }
+    /**
+     * Rough memory estimate in bytes (intentionally pessimistic).
+     * Formula: sum of (ENTRY_OVERHEAD + char bytes of scope+varName+typeName) per entry
+     *          + MAP_ENTRY_OVERHEAD + char bytes of filePath per file.
+     *
+     * Note: V8 stores all-ASCII strings as Latin-1 (1 byte/char) and only upgrades
+     * to UCS-2 (2 bytes/char) for non-Latin-1 code points. Source paths and type names
+     * are typically all-ASCII, so actual heap cost is roughly half what this returns.
+     * The pessimistic factor is intentional — better to over-budget than under-budget.
+     *
+     * **⚠ Cost profile**: O(totalBindings) — iterates every entry in
+     * `_allByFile` and reads three string `.length` properties per entry.
+     * At a typical repo scale (10k files × ~20 file-scope bindings) this is
+     * ~200k property reads per call. Call at most once per pipeline run,
+     * NOT per file, per chunk, or per progress tick. The current single
+     * call site is the dev-mode telemetry log at the pipeline finalize
+     * seam. Adding a per-file-progress caller would silently make it
+     * quadratic in repo size.
+     */
+    estimateMemoryBytes() {
+        let total = 0;
+        for (const [filePath, entries] of this._allByFile) {
+            total += MAP_ENTRY_OVERHEAD + filePath.length * 2;
+            for (const e of entries) {
+                total += ENTRY_OVERHEAD + (e.scope.length + e.varName.length + e.typeName.length) * 2;
+            }
+        }
+        return total;
+    }
+}

package/dist/core/ingestion/call-extractors/configs/c-cpp.d.ts

@@ -0,0 +1,3 @@
+import type { CallExtractionConfig } from '../../call-types.js';
+export declare const cCallConfig: CallExtractionConfig;
+export declare const cppCallConfig: CallExtractionConfig;

package/dist/core/ingestion/call-extractors/configs/c-cpp.js

@@ -0,0 +1,8 @@
+// arc/src/core/ingestion/call-extractors/configs/c-cpp.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const cCallConfig = {
+    language: SupportedLanguages.C,
+};
+export const cppCallConfig = {
+    language: SupportedLanguages.CPlusPlus,
+};

package/dist/core/ingestion/call-extractors/configs/csharp.d.ts

@@ -0,0 +1,2 @@
+import type { CallExtractionConfig } from '../../call-types.js';
+export declare const csharpCallConfig: CallExtractionConfig;

package/dist/core/ingestion/call-extractors/configs/csharp.js

@@ -0,0 +1,6 @@
+// arc/src/core/ingestion/call-extractors/configs/csharp.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const csharpCallConfig = {
+    language: SupportedLanguages.CSharp,
+    typeAsReceiverHeuristic: true,
+};

package/dist/core/ingestion/call-extractors/configs/dart.d.ts

@@ -0,0 +1,2 @@
+import type { CallExtractionConfig } from '../../call-types.js';
+export declare const dartCallConfig: CallExtractionConfig;

package/dist/core/ingestion/call-extractors/configs/dart.js

@@ -0,0 +1,5 @@
+// arc/src/core/ingestion/call-extractors/configs/dart.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const dartCallConfig = {
+    language: SupportedLanguages.Dart,
+};

package/dist/core/ingestion/call-extractors/configs/go.d.ts

@@ -0,0 +1,2 @@
+import type { CallExtractionConfig } from '../../call-types.js';
+export declare const goCallConfig: CallExtractionConfig;

package/dist/core/ingestion/call-extractors/configs/go.js

@@ -0,0 +1,5 @@
+// arc/src/core/ingestion/call-extractors/configs/go.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const goCallConfig = {
+    language: SupportedLanguages.Go,
+};

package/dist/core/ingestion/call-extractors/configs/jvm.d.ts

@@ -0,0 +1,3 @@
+import type { CallExtractionConfig } from '../../call-types.js';
+export declare const javaCallConfig: CallExtractionConfig;
+export declare const kotlinCallConfig: CallExtractionConfig;

package/dist/core/ingestion/call-extractors/configs/jvm.js

@@ -0,0 +1,51 @@
+// arc/src/core/ingestion/call-extractors/configs/jvm.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+// ---------------------------------------------------------------------------
+// Java method_reference (::) parsing — absorbs call-sites/java.ts
+// ---------------------------------------------------------------------------
+/**
+ * Parse Java `method_reference` nodes (`expr::method`, `Type::new`,
+ * `this::m`, `super::m`).
+ */
+function parseJavaMethodReference(callNode) {
+    if (callNode.type !== 'method_reference')
+        return null;
+    const recv = callNode.namedChild(0);
+    if (!recv)
+        return null;
+    // Type::new  →  constructor call
+    for (const c of callNode.children) {
+        if (c.type === 'new') {
+            if (recv.type !== 'identifier')
+                return null;
+            return { calledName: recv.text, callForm: 'constructor' };
+        }
+    }
+    // expr::method  →  member call with receiver
+    const rhs = callNode.child(callNode.childCount - 1);
+    if (!rhs || rhs.type !== 'identifier')
+        return null;
+    const methodName = rhs.text;
+    if (recv.type === 'identifier') {
+        return { calledName: methodName, callForm: 'member', receiverName: recv.text };
+    }
+    if (recv.type === 'this') {
+        return { calledName: methodName, callForm: 'member', receiverName: 'this' };
+    }
+    if (recv.type === 'super') {
+        return { calledName: methodName, callForm: 'member', receiverName: 'super' };
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Configs
+// ---------------------------------------------------------------------------
+export const javaCallConfig = {
+    language: SupportedLanguages.Java,
+    extractLanguageCallSite: parseJavaMethodReference,
+    typeAsReceiverHeuristic: true,
+};
+export const kotlinCallConfig = {
+    language: SupportedLanguages.Kotlin,
+    typeAsReceiverHeuristic: true,
+};

package/dist/core/ingestion/call-extractors/configs/php.d.ts

@@ -0,0 +1,2 @@
+import type { CallExtractionConfig } from '../../call-types.js';
+export declare const phpCallConfig: CallExtractionConfig;

package/dist/core/ingestion/call-extractors/configs/php.js

@@ -0,0 +1,5 @@
+// arc/src/core/ingestion/call-extractors/configs/php.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const phpCallConfig = {
+    language: SupportedLanguages.PHP,
+};

package/dist/core/ingestion/call-extractors/configs/python.d.ts

@@ -0,0 +1,2 @@
+import type { CallExtractionConfig } from '../../call-types.js';
+export declare const pythonCallConfig: CallExtractionConfig;

package/dist/core/ingestion/call-extractors/configs/python.js

@@ -0,0 +1,5 @@
+// arc/src/core/ingestion/call-extractors/configs/python.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const pythonCallConfig = {
+    language: SupportedLanguages.Python,
+};

package/dist/core/ingestion/call-extractors/configs/ruby.d.ts

@@ -0,0 +1,2 @@
+import type { CallExtractionConfig } from '../../call-types.js';
+export declare const rubyCallConfig: CallExtractionConfig;

package/dist/core/ingestion/call-extractors/configs/ruby.js

@@ -0,0 +1,5 @@
+// arc/src/core/ingestion/call-extractors/configs/ruby.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const rubyCallConfig = {
+    language: SupportedLanguages.Ruby,
+};

package/dist/core/ingestion/call-extractors/configs/rust.d.ts

@@ -0,0 +1,2 @@
+import type { CallExtractionConfig } from '../../call-types.js';
+export declare const rustCallConfig: CallExtractionConfig;

package/dist/core/ingestion/call-extractors/configs/rust.js

@@ -0,0 +1,5 @@
+// arc/src/core/ingestion/call-extractors/configs/rust.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const rustCallConfig = {
+    language: SupportedLanguages.Rust,
+};

package/dist/core/ingestion/call-extractors/configs/swift.d.ts

@@ -0,0 +1,2 @@
+import type { CallExtractionConfig } from '../../call-types.js';
+export declare const swiftCallConfig: CallExtractionConfig;

package/dist/core/ingestion/call-extractors/configs/swift.js

@@ -0,0 +1,5 @@
+// arc/src/core/ingestion/call-extractors/configs/swift.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const swiftCallConfig = {
+    language: SupportedLanguages.Swift,
+};

package/dist/core/ingestion/call-extractors/configs/typescript-javascript.d.ts

@@ -0,0 +1,3 @@
+import type { CallExtractionConfig } from '../../call-types.js';
+export declare const typescriptCallConfig: CallExtractionConfig;
+export declare const javascriptCallConfig: CallExtractionConfig;

package/dist/core/ingestion/call-extractors/configs/typescript-javascript.js

@@ -0,0 +1,8 @@
+// arc/src/core/ingestion/call-extractors/configs/typescript-javascript.ts
+import { SupportedLanguages } from '../../../../_shared/index.js';
+export const typescriptCallConfig = {
+    language: SupportedLanguages.TypeScript,
+};
+export const javascriptCallConfig = {
+    language: SupportedLanguages.JavaScript,
+};

package/dist/core/ingestion/call-extractors/generic.d.ts

@@ -0,0 +1,5 @@
+import type { CallExtractor, CallExtractionConfig } from '../call-types.js';
+/**
+ * Create a CallExtractor from a declarative config.
+ */
+export declare function createCallExtractor(config: CallExtractionConfig): CallExtractor;

package/dist/core/ingestion/call-extractors/generic.js

@@ -0,0 +1,59 @@
+// arc/src/core/ingestion/call-extractors/generic.ts
+import { inferCallForm, extractReceiverName, extractReceiverNode, extractMixedChain, countCallArguments, } from '../utils/call-analysis.js';
+/**
+ * Create a CallExtractor from a declarative config.
+ */
+export function createCallExtractor(config) {
+    return {
+        language: config.language,
+        extract(callNode, callNameNode) {
+            // ── Path 1: Language-specific call site ──────────────────────────
+            // Non-standard call shapes (e.g. Java `::` method references) are
+            // handled entirely by the config hook.  When it returns a result,
+            // the generic path is skipped — no argCount, no mixed chain.
+            //
+            // Note: `extractLanguageCallSite` is called on every `extract()`
+            // invocation — both `extract(callNode, undefined)` (parse-worker
+            // Path 1) and `extract(callNode, callNameNode)` (Path 2).
+            // Language hooks must therefore be idempotent and cheap (e.g. a
+            // single node-type check).
+            if (config.extractLanguageCallSite) {
+                const seed = config.extractLanguageCallSite(callNode);
+                if (seed) {
+                    return {
+                        ...seed,
+                        ...(config.typeAsReceiverHeuristic ? { typeAsReceiverHeuristic: true } : {}),
+                    };
+                }
+            }
+            // ── Path 2: Generic extraction via @call.name ────────────────────
+            if (!callNameNode)
+                return null;
+            const calledName = callNameNode.text;
+            const callForm = inferCallForm(callNode, callNameNode);
+            let receiverName = callForm === 'member' ? extractReceiverName(callNameNode) : undefined;
+            let receiverMixedChain;
+            // When the receiver is a complex expression (call chain, field chain,
+            // or mixed), extractReceiverName returns undefined.  Walk the receiver
+            // node to build a unified mixed chain for deferred resolution.
+            if (callForm === 'member' && receiverName === undefined) {
+                const receiverNode = extractReceiverNode(callNameNode);
+                if (receiverNode) {
+                    const extracted = extractMixedChain(receiverNode);
+                    if (extracted && extracted.chain.length > 0) {
+                        receiverMixedChain = extracted.chain;
+                        receiverName = extracted.baseReceiverName;
+                    }
+                }
+            }
+            return {
+                calledName,
+                ...(callForm !== undefined ? { callForm } : {}),
+                ...(receiverName !== undefined ? { receiverName } : {}),
+                argCount: countCallArguments(callNode),
+                ...(receiverMixedChain !== undefined ? { receiverMixedChain } : {}),
+                ...(config.typeAsReceiverHeuristic ? { typeAsReceiverHeuristic: true } : {}),
+            };
+        },
+    };
+}