@codragraph/cli 1.6.2

package/dist/core/group/sync.js

@@ -0,0 +1,196 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Buffer } from 'node:buffer';
+import { initLbug, closeLbug, executeParameterized } from '../lbug/pool-adapter.js';
+import { readRegistry } from '../../storage/repo-manager.js';
+import { HttpRouteExtractor } from './extractors/http-route-extractor.js';
+import { GrpcExtractor } from './extractors/grpc-extractor.js';
+import { TopicExtractor } from './extractors/topic-extractor.js';
+import { ManifestExtractor } from './extractors/manifest-extractor.js';
+import { runExactMatch } from './matching.js';
+import { detectServiceBoundaries, assignService } from './service-boundary-detector.js';
+import { writeContractRegistry } from './storage.js';
+export function stableRepoPoolId(entry, allEntries) {
+    const base = entry.name.toLowerCase();
+    const resolved = path.resolve(entry.path);
+    for (const other of allEntries) {
+        if (other.name.toLowerCase() === base && path.resolve(other.path) !== resolved) {
+            const hash = Buffer.from(entry.path).toString('base64url').slice(0, 6);
+            return `${base}-${hash}`;
+        }
+    }
+    return base;
+}
+function defaultResolveHandle(allEntries) {
+    return async (registryName, groupPath) => {
+        const e = allEntries.find((en) => en.name === registryName);
+        if (!e)
+            return null;
+        const poolId = stableRepoPoolId(e, allEntries);
+        return {
+            id: poolId,
+            path: groupPath,
+            repoPath: e.path,
+            storagePath: e.storagePath,
+        };
+    };
+}
+/**
+ * Dedupe cross-links that point from the same consumer endpoint to the same
+ * provider endpoint for the same contract. Preserves first-seen order so the
+ * caller controls precedence (e.g., pass manifest links first).
+ */
+function dedupeCrossLinks(links) {
+    const seen = new Set();
+    const out = [];
+    for (const link of links) {
+        const key = `${link.from.repo}::${link.from.symbolUid}|${link.to.repo}::${link.to.symbolUid}|${link.type}|${link.contractId}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(link);
+    }
+    return out;
+}
+export async function syncGroup(config, opts) {
+    const missingRepos = [];
+    const repoSnapshots = {};
+    let autoContracts = [];
+    let manifestCrossLinks = [];
+    let dbExecutors;
+    const eo = opts?.extractorOverride;
+    if (eo && eo.length === 0) {
+        autoContracts = await eo();
+    }
+    else {
+        const entries = await readRegistry();
+        const resolve = opts?.resolveRepoHandle ?? defaultResolveHandle(entries);
+        const httpEx = new HttpRouteExtractor();
+        const grpcEx = new GrpcExtractor();
+        const topicEx = new TopicExtractor();
+        dbExecutors = new Map();
+        const openPoolIds = [];
+        try {
+            for (const [groupPath, regName] of Object.entries(config.repos)) {
+                const handle = await resolve(regName, groupPath);
+                if (!handle) {
+                    missingRepos.push(groupPath);
+                    continue;
+                }
+                const poolId = handle.id;
+                const lbugPath = path.join(handle.storagePath, 'lbug');
+                try {
+                    await initLbug(poolId, lbugPath);
+                    openPoolIds.push(poolId);
+                    const executor = (query, params) => executeParameterized(poolId, query, params ?? {});
+                    dbExecutors.set(groupPath, executor);
+                    const boundaries = await detectServiceBoundaries(handle.repoPath);
+                    if (config.detect.http) {
+                        const extracted = await httpEx.extract(executor, handle.repoPath, handle);
+                        for (const c of extracted) {
+                            autoContracts.push({
+                                ...c,
+                                repo: groupPath,
+                                service: assignService(c.symbolRef.filePath, boundaries),
+                            });
+                        }
+                    }
+                    if (config.detect.grpc) {
+                        const extracted = await grpcEx.extract(executor, handle.repoPath, handle);
+                        for (const c of extracted) {
+                            autoContracts.push({
+                                ...c,
+                                repo: groupPath,
+                                service: assignService(c.symbolRef.filePath, boundaries),
+                            });
+                        }
+                    }
+                    if (config.detect.topics) {
+                        const extracted = await topicEx.extract(executor, handle.repoPath, handle);
+                        for (const c of extracted) {
+                            autoContracts.push({
+                                ...c,
+                                repo: groupPath,
+                                service: assignService(c.symbolRef.filePath, boundaries),
+                            });
+                        }
+                    }
+                    const metaPath = path.join(handle.storagePath, 'meta.json');
+                    try {
+                        const raw = await fs.readFile(metaPath, 'utf-8');
+                        const m = JSON.parse(raw);
+                        repoSnapshots[groupPath] = {
+                            indexedAt: m.indexedAt || '',
+                            lastCommit: m.lastCommit || '',
+                        };
+                    }
+                    catch {
+                        const e = entries.find((en) => en.name === regName);
+                        repoSnapshots[groupPath] = {
+                            indexedAt: e?.indexedAt || '',
+                            lastCommit: e?.lastCommit || '',
+                        };
+                    }
+                }
+                catch {
+                    missingRepos.push(groupPath);
+                }
+            }
+        }
+        finally {
+            for (const id of [...new Set(openPoolIds)]) {
+                await closeLbug(id).catch(() => { });
+            }
+        }
+    }
+    // Process manifest links declared in group.yaml.
+    // ManifestExtractor is fully implemented but was never wired into this
+    // pipeline — config.links were parsed and validated but silently dropped.
+    // Placed after the DB try/finally: resolveSymbol falls back to synthetic
+    // UIDs when dbExecutors is undefined or a pool is closed, so cross-links
+    // are always generated regardless of whether real DB executors are available.
+    if (config.links.length > 0) {
+        // Warn about dangling links that reference repos not declared in config.repos.
+        // They still generate cross-links via synthetic UIDs (determinism is preserved),
+        // but the operator probably meant something that now silently does nothing useful.
+        const knownRepos = new Set(Object.keys(config.repos));
+        for (const link of config.links) {
+            const dangling = [link.from, link.to].filter((r) => !knownRepos.has(r));
+            if (dangling.length > 0) {
+                console.warn(`[group/sync] manifest link ${link.type}:${link.contract} references repos not in config.repos: ${dangling.join(', ')} — cross-links will use synthetic UIDs`);
+            }
+        }
+        const manifestEx = new ManifestExtractor();
+        const manifestResult = await manifestEx.extractFromManifest(config.links, dbExecutors);
+        autoContracts.push(...manifestResult.contracts);
+        manifestCrossLinks = manifestResult.crossLinks;
+        if (opts?.verbose) {
+            console.log(`  manifest: ${manifestCrossLinks.length} cross-links from ${config.links.length} declared links`);
+        }
+    }
+    const { matched, unmatched } = runExactMatch(autoContracts);
+    // Dedupe cross-links. Manifest contracts participate in runExactMatch, so a
+    // manifest-declared link can also emit a matchType:'exact' CrossLink with the
+    // same endpoints. Prefer the manifest version — it reflects operator intent
+    // and carries matchType:'manifest' which downstream consumers may rely on.
+    const crossLinks = dedupeCrossLinks([...manifestCrossLinks, ...matched]);
+    const allContracts = autoContracts;
+    const registry = {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        repoSnapshots,
+        missingRepos,
+        contracts: allContracts,
+        crossLinks,
+    };
+    if (opts?.groupDir && !opts.skipWrite) {
+        await writeContractRegistry(opts.groupDir, registry);
+    }
+    return {
+        contracts: allContracts,
+        crossLinks,
+        unmatched,
+        missingRepos,
+        repoSnapshots,
+    };
+}

package/dist/core/group/types.d.ts

@@ -0,0 +1,160 @@
+export type ContractType = 'http' | 'grpc' | 'topic' | 'lib' | 'custom';
+export type MatchType = 'exact' | 'manifest' | 'wildcard' | 'bm25' | 'embedding';
+export type ContractRole = 'provider' | 'consumer';
+export interface GroupConfig {
+    version: number;
+    name: string;
+    description: string;
+    repos: Record<string, string>;
+    links: GroupManifestLink[];
+    packages: Record<string, Record<string, string>>;
+    detect: DetectConfig;
+    matching: MatchingConfig;
+}
+export interface GroupManifestLink {
+    from: string;
+    to: string;
+    type: ContractType;
+    contract: string;
+    role: ContractRole;
+}
+export interface DetectConfig {
+    http: boolean;
+    grpc: boolean;
+    topics: boolean;
+    shared_libs: boolean;
+    embedding_fallback: boolean;
+}
+export interface MatchingConfig {
+    bm25_threshold: number;
+    embedding_threshold: number;
+    max_candidates_per_step: number;
+}
+export interface SymbolRef {
+    filePath: string;
+    name: string;
+}
+export interface ExtractedContract {
+    contractId: string;
+    type: ContractType;
+    role: ContractRole;
+    symbolUid: string;
+    symbolRef: SymbolRef;
+    symbolName: string;
+    confidence: number;
+    meta: Record<string, unknown>;
+    /** Service boundary within a monorepo (relative path from repo root, e.g. "services/auth"). */
+    service?: string;
+}
+export interface CrossLinkEndpoint {
+    repo: string;
+    /** Service boundary within a monorepo (relative path from repo root). */
+    service?: string;
+    symbolUid: string;
+    symbolRef: SymbolRef;
+}
+export interface CrossLink {
+    from: CrossLinkEndpoint;
+    to: CrossLinkEndpoint;
+    type: ContractType;
+    contractId: string;
+    matchType: MatchType;
+    confidence: number;
+}
+export interface RepoSnapshot {
+    indexedAt: string;
+    lastCommit: string;
+}
+export interface ContractRegistry {
+    version: number;
+    generatedAt: string;
+    repoSnapshots: Record<string, RepoSnapshot>;
+    missingRepos: string[];
+    contracts: StoredContract[];
+    crossLinks: CrossLink[];
+}
+export interface StoredContract extends ExtractedContract {
+    repo: string;
+}
+/** Repo within a group (group path + paths; name collision with MCP RepoHandle — import from group/types only). */
+export interface RepoHandle {
+    id: string;
+    path: string;
+    repoPath: string;
+    storagePath: string;
+}
+/** Why local impact or fan-out stopped early (e.g. wall-clock budget exhausted). */
+export type GroupImpactTruncationReason = 'timeout' | 'partial';
+export interface GroupImpactResult {
+    local: unknown;
+    group: string;
+    cross: CrossRepoImpact[];
+    outOfScope: OutOfScopeLink[];
+    truncated: boolean;
+    truncatedRepos: string[];
+    summary: {
+        direct: number;
+        processes_affected: number;
+        modules_affected: number;
+        cross_repo_hits: number;
+    };
+    risk: string;
+    /**
+     * Milliseconds budget applied to the **Phase 1 local impact** leg (`safeLocalImpact`).
+     * If the walk hits this wall first, expect `truncationReason: 'timeout'` and a partial `local` payload.
+     */
+    timeoutMs?: number;
+    /** Present when local impact or fan-out stopped early (timeout, graph cap, etc.). */
+    truncationReason?: GroupImpactTruncationReason;
+    /**
+     * Human-readable note when `crossDepth` was clamped (e.g. multi-hop not implemented yet).
+     */
+    crossDepthWarning?: string;
+}
+/** One repo’s `context` tool payload in a group-scoped context run. */
+export interface GroupContextRepoEntry {
+    repoPath: string;
+    registryName: string;
+    payload: unknown;
+}
+/**
+ * Aggregated group `context`: explicit per-repo rows (no merged symbol payloads).
+ * Use top-level `error` only for unrecoverable failures, not for “no matches” or service scope misses.
+ */
+export interface GroupContextResult {
+    group: string;
+    target?: string;
+    service?: string;
+    error?: string;
+    results: GroupContextRepoEntry[];
+}
+export interface CrossRepoImpact {
+    repo: string;
+    repo_path: string;
+    contract: {
+        id: string;
+        type: ContractType;
+        match_type: MatchType;
+        confidence: number;
+    };
+    by_depth: Record<string, unknown[]>;
+    affected_processes: string[];
+}
+export interface OutOfScopeLink {
+    from: string;
+    to: string;
+    contractId: string;
+    confidence: number;
+}
+/** Opaque handle to an open bridge LadybugDB. */
+export interface BridgeHandle {
+    /** Internal — do not access directly. */
+    readonly _db: unknown;
+    readonly _conn: unknown;
+    readonly groupDir: string;
+}
+export interface BridgeMeta {
+    version: number;
+    generatedAt: string;
+    missingRepos: string[];
+}

package/dist/core/group/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/ingestion/ast-cache.d.ts

@@ -0,0 +1,26 @@
+import Parser from 'tree-sitter';
+/**
+ * Minimal structural shape consumers need when reading Trees back
+ * through a phase-dependency boundary. Declared here so phases that
+ * receive ASTCache via `getPhaseOutput<...>` don't hand-roll their
+ * own inline structural types that silently drift when ASTCache's
+ * contract changes.
+ *
+ * Typed as `unknown` at the Tree boundary because consumers on the
+ * other side of the phase-output map don't share tree-sitter's type
+ * graph (e.g. COBOL's standalone processor).
+ */
+export interface ASTCacheReader {
+    get(filePath: string): unknown;
+    clear(): void;
+}
+export interface ASTCache extends ASTCacheReader {
+    get: (filePath: string) => Parser.Tree | undefined;
+    set: (filePath: string, tree: Parser.Tree) => void;
+    clear: () => void;
+    stats: () => {
+        size: number;
+        maxSize: number;
+    };
+}
+export declare const createASTCache: (maxSize?: number) => ASTCache;

package/dist/core/ingestion/ast-cache.js

@@ -0,0 +1,47 @@
+import { LRUCache } from 'lru-cache';
+export const createASTCache = (maxSize = 50) => {
+    const effectiveMax = Math.max(maxSize, 1);
+    // Initialize the cache with a 'dispose' handler
+    // This is the magic: When an item is evicted (dropped), this runs automatically.
+    const cache = new LRUCache({
+        max: effectiveMax,
+        dispose: (tree) => {
+            try {
+                // NOTE: web-tree-sitter has tree.delete(); native tree-sitter
+                // trees are GC-managed and .delete is absent (no-op here).
+                //
+                // Single-owner invariant (load-bearing under WASM): a given
+                // Parser.Tree reference must live in AT MOST ONE ASTCache
+                // that disposes. The parse-phase chunk-local cache clears
+                // between chunks; the cross-phase `scopeTreeCache` (also an
+                // ASTCache today) holds the same Tree by reference. Under
+                // native tree-sitter this is benign (dispose is a no-op).
+                // If/when CodraGraph adopts web-tree-sitter for sequential
+                // parsing, the cross-phase cache must either (a) skip
+                // writing Trees that are already owned by a disposing cache,
+                // or (b) use tree.copy() per entry. Failing to pick one
+                // will hand freed memory to scope-resolution.
+                tree.delete?.();
+            }
+            catch (e) {
+                console.warn('Failed to delete tree from WASM memory', e);
+            }
+        },
+    });
+    return {
+        get: (filePath) => {
+            const tree = cache.get(filePath);
+            return tree; // Returns undefined if not found
+        },
+        set: (filePath, tree) => {
+            cache.set(filePath, tree);
+        },
+        clear: () => {
+            cache.clear();
+        },
+        stats: () => ({
+            size: cache.size,
+            maxSize: effectiveMax,
+        }),
+    };
+};

package/dist/core/ingestion/binding-accumulator.d.ts

@@ -0,0 +1,212 @@
+/**
+ * BindingAccumulator — read-append-only accumulator that collects TypeEnv
+ * bindings across files in the CodraGraph 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.
+ */
+export interface BindingEntry {
+    readonly scope: string;
+    readonly varName: string;
+    readonly typeName: string;
+}
+/**
+ * Minimal graph-node shape required by `enrichExportedTypeMap()`. Intentionally
+ * narrower than the full `GraphNode` type in `graph/types.ts` so tests can
+ * construct a minimal mock without depending on the full graph module, and
+ * so the enrichment logic is a pure function over this contract.
+ *
+ * Matches the shape of the real `KnowledgeGraph` node's `properties.isExported`
+ * access path — tests that use a different shape silently pass while
+ * production fails.
+ */
+export interface EnrichmentGraphNode {
+    readonly id: string;
+    readonly properties?: {
+        readonly isExported?: boolean;
+    } | undefined;
+}
+/**
+ * Minimal graph lookup interface used by `enrichExportedTypeMap()`.
+ * Consumes only the method the enrichment loop actually calls.
+ */
+export interface EnrichmentGraphLookup {
+    getNode(id: string): EnrichmentGraphNode | undefined;
+}
+/**
+ * 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 declare function enrichExportedTypeMap(bindingAccumulator: BindingAccumulator, graph: EnrichmentGraphLookup, exportedTypeMap: Map<string, Map<string, string>>): number;
+export declare class BindingAccumulator {
+    private readonly _allByFile;
+    private readonly _fileScopeByFile;
+    private _totalBindings;
+    private _finalized;
+    private _disposed;
+    /**
+     * 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: string, entries: readonly BindingEntry[]): void;
+    /** Lock the accumulator — no further appends. Idempotent. */
+    finalize(): void;
+    /**
+     * 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(): void;
+    /** Get all bindings for a file, or undefined if the file is unknown. */
+    getFile(filePath: string): readonly BindingEntry[] | undefined;
+    /**
+     * 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: string): readonly (readonly [string, string])[];
+    /**
+     * 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: string, name: string): string | undefined;
+    /** Iterate over all file paths in insertion order. */
+    files(): IterableIterator<string>;
+    /** Number of distinct files with at least one binding. */
+    get fileCount(): number;
+    /** Total number of binding entries across all files. */
+    get totalBindings(): number;
+    /** Whether the accumulator has been finalized. */
+    get finalized(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): number;
+}