gitnexus 1.6.8-rc.2 → 1.6.8-rc.21

package/dist/core/ingestion/scope-resolution/pipeline/phase.js

@@ -285,6 +285,12 @@ export const scopeResolutionPhase = {
                 prebuiltNodeLookup: sharedNodeLookup,
                 preExtractedParsedFiles: preExtractedByPath,
                 scopeIndexStorePath: parsedFileStorePath,
+                // CFG/PDG emission (#2081 M1) — opt-in; off ⇒ byte-identical graph.
+                pdg: ctx.options?.pdg === true,
+                pdgMaxEdgesPerFunction: ctx.options?.pdgMaxEdgesPerFunction,
+                pdgMaxReachingDefEdgesPerFunction: ctx.options?.pdgMaxReachingDefEdgesPerFunction,
+                pdgMaxTaintFindingsPerFunction: ctx.options?.pdgMaxTaintFindingsPerFunction,
+                pdgMaxTaintHops: ctx.options?.pdgMaxTaintHops,
                 recordResolutionOutcome: (outcome) => {
                     resolutionOutcomes.push(outcome);
                 },

package/dist/core/ingestion/scope-resolution/pipeline/reconcile-ownership.js

@@ -64,14 +64,39 @@ export function reconcileOwnership(parsedFiles, model) {
     for (const parsed of parsedFiles) {
         for (const def of parsed.localDefs) {
             const ownerId = def.ownerId;
-            if (ownerId === undefined)
-                continue;
             const simple = simpleQualifiedName(def);
             if (simple === undefined)
                 continue;
             if (def.type === 'Method' || def.type === 'Function' || def.type === 'Constructor') {
+                if (ownerId === undefined) {
+                    if (def.isDeleted !== true)
+                        continue;
+                    const existingDef = model.symbols
+                        .lookupExactAll(def.filePath, simple)
+                        .find((candidate) => callableSignatureMatches(candidate, def));
+                    if (existingDef !== undefined) {
+                        existingDef.isDeleted = true;
+                        skippedAlreadyPresent++;
+                        continue;
+                    }
+                    model.symbols.add(def.filePath, simple, def.nodeId, def.type, {
+                        parameterCount: def.parameterCount,
+                        requiredParameterCount: def.requiredParameterCount,
+                        parameterTypes: def.parameterTypes,
+                        parameterTypeClasses: def.parameterTypeClasses,
+                        returnType: def.returnType,
+                        qualifiedName: def.qualifiedName,
+                        isDeleted: true,
+                    });
+                    continue;
+                }
                 const existing = model.methods.lookupAllByOwner(ownerId, simple);
-                if (existing.some((e) => e.nodeId === def.nodeId)) {
+                const existingDef = existing.find((candidate) => candidate.nodeId === def.nodeId ||
+                    (def.isDeleted === true && callableSignatureMatches(candidate, def)));
+                if (existingDef !== undefined) {
+                    if (def.isDeleted === true) {
+                        existingDef.isDeleted = true;
+                    }
                     skippedAlreadyPresent++;
                     continue;
                 }
@@ -103,6 +128,21 @@ export function reconcileOwnership(parsedFiles, model) {
     }
     return { methodsRegistered, fieldsRegistered, nestedTypesRegistered, skippedAlreadyPresent };
 }
+function callableSignatureMatches(left, right) {
+    if (left.filePath !== right.filePath)
+        return false;
+    if (left.parameterCount !== right.parameterCount)
+        return false;
+    if (left.requiredParameterCount !== right.requiredParameterCount)
+        return false;
+    const leftTypes = left.parameterTypes;
+    const rightTypes = right.parameterTypes;
+    if (leftTypes === undefined || rightTypes === undefined) {
+        return leftTypes === rightTypes;
+    }
+    return (leftTypes.length === rightTypes.length &&
+        leftTypes.every((parameterType, index) => parameterType === rightTypes[index]));
+}
 /**
  * Debug-mode parity validator. Runs only when
  * `VALIDATE_SEMANTIC_MODEL !== '0'` AND `NODE_ENV !== 'production'`.

package/dist/core/ingestion/scope-resolution/pipeline/run.d.ts

@@ -58,6 +58,27 @@ interface RunScopeResolutionInput {
     readonly treeCache?: {
         get(filePath: string): unknown;
     };
+    /**
+     * CFG/PDG opt-in (#2081 M1). When true, emit BasicBlock nodes + CFG edges
+     * from each ParsedFile's worker-built `cfgSideChannel` during Phase-4 graph
+     * emission (while the disk store is still live). Default/false ⇒ no CFG
+     * nodes or edges and a byte-identical graph.
+     */
+    readonly pdg?: boolean;
+    /** Per-function CFG edge cap. `undefined` ⇒ {@link DEFAULT_MAX_CFG_EDGES_PER_FUNCTION};
+     *  `0` ⇒ no cap (unlimited). */
+    readonly pdgMaxEdgesPerFunction?: number;
+    /** Per-function REACHING_DEF edge cap (#2082 M2). `undefined` ⇒
+     *  {@link DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION}; `0` ⇒ no cap. */
+    readonly pdgMaxReachingDefEdgesPerFunction?: number;
+    /** Per-function taint findings cap (#2083 M3, consumed by the U4 taint
+     *  emit step in the pdg window). `undefined` ⇒
+     *  `DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION` (200); `0` ⇒ no cap. */
+    readonly pdgMaxTaintFindingsPerFunction?: number;
+    /** Per-finding taint hop cap (#2083 M3 KTD6 — bounds the hop-encoded
+     *  `reason`; consumed by the U4 taint emit step). `undefined` ⇒
+     *  `DEFAULT_PDG_MAX_TAINT_HOPS` (32); `0` ⇒ no cap. */
+    readonly pdgMaxTaintHops?: number;
     /**
      * Optional graph-node lookup built ONCE by the caller and shared across
      * every language pass. `buildGraphNodeLookup` scans the whole graph and is

package/dist/core/ingestion/scope-resolution/pipeline/run.js

@@ -30,6 +30,10 @@ import { extractParsedFile } from '../../scope-extractor-bridge.js';
 import { finalizeScopeModel } from '../../finalize-orchestrator.js';
 import { resolveReferenceSites } from '../../resolve-references.js';
 import { buildGraphNodeLookup } from '../graph-bridge/node-lookup.js';
+import { emitFileCfgs, emitFileReachingDefs, isEmitSafeCfg, DEFAULT_MAX_CFG_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION, REACHING_DEF_FACTS_PER_EDGE_CAP, } from '../../cfg/emit.js';
+import { emitFileTaint, DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from '../../taint/emit.js';
+import { registerBuiltinTaintModels } from '../../taint/typescript-model.js';
+import { getSourceSinkConfig } from '../../taint/source-sink-registry.js';
 import { resolveDefGraphId } from '../graph-bridge/ids.js';
 import { buildPopulatedMethodDispatch } from '../graph-bridge/method-dispatch.js';
 import { propagateImportedReturnTypes } from '../passes/imported-return-types.js';
@@ -454,6 +458,206 @@ export function runScopeResolution(input, provider) {
             resolutionConfig,
         });
     }
+    // ── CFG/PDG emission (#2081 M1, opt-in via `--pdg`) ──────────────────────
+    // Emit BasicBlock nodes + CFG edges from each ParsedFile's worker-built
+    // `cfgSideChannel`, HERE — the last point inside scope-resolution where the
+    // ParsedFiles are still loaded (`emitParsedFiles` carries the channel; the
+    // disk store is cleared right after this orchestrator returns, see phase.ts).
+    // A post-`mro` phase would read empty data (KTD1). Off by default ⇒ zero
+    // BasicBlock/CFG nodes/edges and a byte-identical graph.
+    // Accumulated M2 reaching-defs time (solve + dedup + REACHING_DEF emit),
+    // reported as the PROF `pdg=` segment. It is a SUBSET of `emit=` — the M1
+    // CFG emit and the M2 solve interleave per file, so a separate checkpoint
+    // pair can't bracket them; without this accumulator the M2 cost would
+    // silently disappear into `emit=` and field regressions would be invisible.
+    let pdgMs = 0;
+    // M3 (#2083 U4): accumulated taint time (match + taint-side solve +
+    // propagate + TAINTED/SANITIZES emit), a sibling of `pdgMs` for the same
+    // reason — it interleaves per file inside `emit=`, so only an accumulator
+    // can bracket it. Printed as the PROF `taint=` segment.
+    let taintMs = 0;
+    if (input.pdg === true) {
+        let cfgBlocks = 0;
+        let cfgEdges = 0;
+        let cfgDroppedEdges = 0;
+        let rdEdges = 0;
+        let rdDropped = 0;
+        let rdFacts = 0;
+        let rdTruncated = 0;
+        // ── M3 taint setup (#2083 U4) ────────────────────────────────────────
+        // Explicit model-registration seam (idempotent, cheap) — the registry
+        // stays empty on non-pdg runs, preserving default-run parity. The
+        // registry is keyed by `SupportedLanguages` enum VALUES ('typescript' /
+        // 'javascript'), and `ScopeResolver.language` IS a `SupportedLanguages`
+        // member registered under those same constants — the join is direct
+        // equality, no mapping table. A language without a registered spec
+        // (python, go, …) skips taint entirely: no work, no warn spam (KTD8).
+        registerBuiltinTaintModels();
+        const taintSpec = getSourceSinkConfig(provider.language);
+        // Taint-side solver fact cap: the SAME derivation emitFileReachingDefs
+        // uses for the RD projection (edge cap × headroom factor, 0 ⇒ unlimited),
+        // so taint coverage and RD coverage truncate together — a function is
+        // never a taint coverage gap while its RD projection computed, and the
+        // RD layer's per-function truncation warn already names it.
+        const rdEdgeCap = input.pdgMaxReachingDefEdgesPerFunction ?? DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION;
+        const taintLimits = {
+            maxFindingsPerFunction: input.pdgMaxTaintFindingsPerFunction ?? DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION,
+            maxHops: input.pdgMaxTaintHops ?? DEFAULT_PDG_MAX_TAINT_HOPS,
+            maxFacts: rdEdgeCap > 0 ? rdEdgeCap * REACHING_DEF_FACTS_PER_EDGE_CAP : 0,
+        };
+        // Cross-file aggregate of EVERY TaintEmitResult counter (the M2 emit
+        // result shipped with two fields dropped on the floor — R4 forbids that
+        // here; gaps/drops feed the unconditional warn below, volume feeds the
+        // per-language debug line).
+        const taintTotals = {
+            analyzed: 0,
+            noMatch: 0,
+            unsafeSites: 0,
+            gapTruncated: 0,
+            gapOverflow: 0,
+            gapNoFacts: 0,
+            findings: 0,
+            kills: 0,
+            dropped: 0,
+            hopsTruncated: 0,
+            gapExamples: [],
+            dropExamples: [],
+        };
+        for (const pf of emitParsedFiles) {
+            const cfgs = pf.cfgSideChannel;
+            // Defensive: cfgSideChannel is opaque (`unknown`) and crosses the cache /
+            // durable store. A stale or wrong-shape value (e.g. a pre-SCHEMA_BUMP
+            // shard that slipped the version gate) must skip emission, not throw a
+            // TypeError mid-graph-build and abort scope-resolution for the language.
+            if (!Array.isArray(cfgs) || cfgs.length === 0)
+                continue;
+            try {
+                // Per-element emit-safety filter (mirrors the parsedfile-store
+                // reviver's POLICY: valid elements in a mixed array still emit; junk
+                // is warned and skipped). isEmitSafeCfg lives in cfg/emit.ts next to
+                // the id templating it defends — see its doc for why anchor-field and
+                // endpoint-membership checks are load-bearing. Runs INSIDE the try so
+                // even a predicate-time throw (e.g. a hostile getter) is isolated.
+                const wellFormed = cfgs.filter(isEmitSafeCfg);
+                if (wellFormed.length < cfgs.length) {
+                    logger.warn(`[cfg] ${pf.filePath}: skipped ${cfgs.length - wellFormed.length} malformed ` +
+                        `cfgSideChannel element(s) (bad shape, missing id-anchor fields, or edge ` +
+                        `endpoints matching no block) — CFG for those functions omitted`);
+                }
+                if (wellFormed.length === 0)
+                    continue;
+                const emitted = emitFileCfgs(graph, wellFormed, input.pdgMaxEdgesPerFunction ?? DEFAULT_MAX_CFG_EDGES_PER_FUNCTION, 
+                // Log cap-overflow drops UNCONDITIONALLY (not via input.onWarn, which is
+                // gated behind the semantic-model validator and silent in production) so
+                // the per-function edge cap never truncates the CFG silently (R6/KTD6).
+                (message) => logger.warn(message));
+                cfgBlocks += emitted.blocks;
+                cfgEdges += emitted.edges;
+                cfgDroppedEdges += emitted.droppedEdges;
+                // M2 (#2082 U4): reaching definitions over the same validated CFGs.
+                // In-memory facts are computed per function and dropped after the
+                // bounded (defBlock, useBlock, binding) projection is persisted —
+                // M3 recomputes via the same pure solver in-phase (KTD8). Timing is
+                // PROF-gated like every other checkpoint here (zero cost when off).
+                const t0 = PROF ? performance.now() : 0;
+                const rd = emitFileReachingDefs(graph, wellFormed, input.pdgMaxReachingDefEdgesPerFunction ??
+                    DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION, (message) => logger.warn(message));
+                if (PROF)
+                    pdgMs += performance.now() - t0;
+                rdEdges += rd.edges;
+                rdDropped += rd.droppedEdges;
+                rdFacts += rd.facts;
+                rdTruncated += rd.truncatedFunctions;
+                // M3 (#2083 U4): taint over the SAME validated CFGs, inside the SAME
+                // per-file try (a taint throw costs this file's taint layer only —
+                // its CFG/REACHING_DEF edges above are already in the graph). Skipped
+                // entirely when the language has no registered model.
+                if (taintSpec !== undefined) {
+                    const t1 = PROF ? performance.now() : 0;
+                    const taint = emitFileTaint(graph, wellFormed, pf.parsedImports, taintSpec, taintLimits, (message) => logger.warn(message));
+                    if (PROF)
+                        taintMs += performance.now() - t1;
+                    taintTotals.analyzed += taint.functionsAnalyzed;
+                    taintTotals.noMatch += taint.functionsSkippedNoMatch;
+                    taintTotals.unsafeSites += taint.functionsSkippedUnsafeSites;
+                    taintTotals.gapTruncated += taint.functionsCoverageGap.truncated;
+                    taintTotals.gapOverflow += taint.functionsCoverageGap.overflow;
+                    taintTotals.gapNoFacts += taint.functionsCoverageGap['no-facts'];
+                    taintTotals.findings += taint.findingsEmitted;
+                    taintTotals.kills += taint.killsEmitted;
+                    taintTotals.dropped += taint.findingsDropped;
+                    taintTotals.hopsTruncated += taint.hopsTruncatedFindings;
+                    for (const ex of taint.coverageGapExamples) {
+                        if (taintTotals.gapExamples.length < 5)
+                            taintTotals.gapExamples.push(ex);
+                    }
+                    for (const ex of taint.droppedExamples) {
+                        if (taintTotals.dropExamples.length < 5)
+                            taintTotals.dropExamples.push(ex);
+                    }
+                }
+            }
+            catch (err) {
+                // Last-resort isolation, mirroring the worker-side per-file try/catch:
+                // a shape the predicate misses must cost this one file's CFG, not
+                // abort the language's whole scope-resolution pass mid-graph-build.
+                // NOTE a mid-emit throw can leave this file's already-inserted
+                // BasicBlock nodes in the graph (addNode is not transactional) —
+                // orphaned but inert; the predicate keeps every JSON-representable
+                // bad shape from reaching this path at all.
+                logger.warn(`[cfg] ${pf.filePath}: CFG emission failed (${err instanceof Error ? err.message : String(err)}) — ` +
+                    `this file's CFG is partial or absent`);
+            }
+        }
+        if (cfgBlocks > 0) {
+            logger.debug(`[scope-resolution] CFG emit (lang=${provider.language}): ` +
+                `${cfgBlocks} BasicBlock nodes, ${cfgEdges} CFG edges` +
+                (cfgDroppedEdges > 0 ? `, ${cfgDroppedEdges} edges dropped (per-function cap)` : '') +
+                `; ${rdEdges} REACHING_DEF edges (${rdFacts} facts)` +
+                (rdDropped > 0 ? `, ${rdDropped} REACHING_DEF edges dropped (per-function cap)` : '') +
+                (rdTruncated > 0 ? `, ${rdTruncated} function(s) hit the fact limit` : '') +
+                // M3 volume telemetry — only for languages with a registered model.
+                (taintSpec !== undefined
+                    ? `; taint: ${taintTotals.findings} TAINTED, ${taintTotals.kills} SANITIZES ` +
+                        `(${taintTotals.analyzed} function(s) analyzed, ` +
+                        `${taintTotals.noMatch} skipped: no source/sink match` +
+                        (taintTotals.hopsTruncated > 0
+                            ? `, ${taintTotals.hopsTruncated} finding(s) with truncated hop paths`
+                            : '') +
+                        `)`
+                    : ''));
+        }
+        // R4: taint coverage gaps and cap drops surface UNCONDITIONALLY (never
+        // logger.debug, never input.onWarn) at the per-language aggregate, with
+        // counts and up to 5 example functions. Per-function warns above cover
+        // the rare/actionable cases (unsafe sites, cap drops); solver-status gaps
+        // were already per-function-warned by the RD layer (same solver, same
+        // fact cap), so this aggregate is their single taint-side surface.
+        if (taintSpec !== undefined) {
+            const gapCount = taintTotals.unsafeSites +
+                taintTotals.gapTruncated +
+                taintTotals.gapOverflow +
+                taintTotals.gapNoFacts;
+            if (gapCount > 0 || taintTotals.dropped > 0) {
+                const parts = [];
+                if (gapCount > 0) {
+                    parts.push(`${gapCount} function(s) skipped for taint ` +
+                        `(${taintTotals.gapTruncated} fact-limit, ${taintTotals.gapOverflow} overflow, ` +
+                        `${taintTotals.gapNoFacts} no-facts, ${taintTotals.unsafeSites} malformed sites)` +
+                        (taintTotals.gapExamples.length > 0
+                            ? ` — e.g. ${taintTotals.gapExamples.join(', ')}`
+                            : ''));
+                }
+                if (taintTotals.dropped > 0) {
+                    parts.push(`${taintTotals.dropped} finding(s) dropped by the per-function cap` +
+                        (taintTotals.dropExamples.length > 0
+                            ? ` — e.g. ${taintTotals.dropExamples.join(', ')}`
+                            : ''));
+                }
+                logger.warn(`[taint] lang=${provider.language}: ${parts.join('; ')}`);
+            }
+        }
+    }
     if (PROF) {
         const tEnd = process.hrtime.bigint();
         const ns = (a, b) => Number(b - a) / 1_000_000;
@@ -462,6 +666,9 @@ export function runScopeResolution(input, provider) {
             ` propagate=${ns(tFinalize, tPropagate).toFixed(0)}ms` +
             ` resolve=${ns(tPropagate, tResolve).toFixed(0)}ms` +
             ` emit=${ns(tResolve, tEnd).toFixed(0)}ms` +
+            // pdg ⊆ emit: the M2 reaching-defs share of the emit bucket (#2082 U4).
+            // taint ⊆ emit likewise: the M3 match+solve+propagate+emit share (#2083 U4).
+            (input.pdg === true ? ` pdg=${pdgMs.toFixed(0)}ms taint=${taintMs.toFixed(0)}ms` : '') +
             ` total=${ns(tStart, tEnd).toFixed(0)}ms` +
             ` (${parsedFiles.length} files)`);
     }

package/dist/core/ingestion/scope-resolution/resolution-outcome.d.ts

@@ -1,5 +1,5 @@
 import type { Range } from '../../../_shared/index.js';
-export type ResolutionSuppressionReason = 'adl-ordinary-lookup-blocked' | 'conversion-rank-tied' | 'inline-ns-ambiguous' | 'member-lookup-ambiguous' | 'overload-ambiguous' | 'overload-ambiguous-normalization';
+export type ResolutionSuppressionReason = 'adl-ordinary-lookup-blocked' | 'conversion-rank-tied' | 'inline-ns-ambiguous' | 'member-lookup-ambiguous' | 'selected-callable-deleted' | 'overload-ambiguous' | 'overload-ambiguous-normalization';
 export type ResolutionOutcome = {
     readonly kind: 'resolved';
     readonly targetId: string;

package/dist/core/ingestion/taint/emit.d.ts

@@ -0,0 +1,124 @@
+/**
+ * In-phase taint emission (#2083 M3 U4, plan KTD1/KTD6).
+ *
+ * Per-file driver for the M3 taint pass: gate → match → solve → propagate →
+ * persist sparse `TAINTED` + `SANITIZES` edges. Invoked from the pdg window in
+ * scope-resolution (`pipeline/run.ts`), immediately after `emitFileReachingDefs`
+ * inside the SAME per-file try — per-file isolation for free (KTD1). Mirrors
+ * `emitFileReachingDefs` (cfg/emit.ts) for the budget/dedup/warn discipline and
+ * the telemetry-result shape.
+ *
+ * ## Per-function pipeline (ordering is load-bearing)
+ *
+ * 1. `hasTaintSafeSites` — a corrupted-store site annotation degrades to
+ *    SKIP-TAINT-KEEP-RD for this function (counted + warned), never a crash
+ *    (KTD2; the matcher/propagator dereference indices unvalidated).
+ * 2. `matchFunctionSites` against the language spec (the import index is
+ *    built ONCE per file — imports are a file-level fact).
+ * 3. ZERO-MATCH FAST PATH: the solver runs only when the function has at
+ *    least one matched source AND one matched sink. In a typical repo almost
+ *    no function has both; an unconditional second `computeReachingDefs` per
+ *    function would ship a near-2× solve cost to every `--pdg` user.
+ * 4. `computeReachingDefs` with the taint `maxFacts` — by DEFAULT the M2
+ *    derived `DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION` (deliberate
+ *    reuse, not a new constant: the fact-materialization envelope is a
+ *    memory question, O(defs×uses), orthogonal to the findings cap, and M2
+ *    already validated exactly this envelope on the same solver in the same
+ *    window). The run.ts caller derives `limits.maxFacts` from the SAME
+ *    RD-edge-cap formula `emitFileReachingDefs` uses, so taint coverage and
+ *    RD coverage truncate together — a function is never `truncated` for one
+ *    layer and `computed` for the other.
+ * 5. `computeTaintFlows` — a non-`computed` status is a per-function
+ *    COVERAGE GAP (R4: counted by `gapReason`, function skipped entirely,
+ *    never partially analyzed).
+ * 6. Emit one `TAINTED` edge per finding and one `SANITIZES` edge per kill.
+ *    Kills are emitted even when findings are zero — a fully-sanitized
+ *    function's kills are exactly its evidence of safety.
+ *
+ * ## Identity, dedup, budget (KTD6)
+ *
+ * Findings carry STATEMENT-LEVEL identity — function anchor + sink kind +
+ * source occurrence (point/site/object-binding/property) + sink occurrence
+ * (point/site/arg/binding) — NOT the REACHING_DEF block-level key (block-pair
+ * conflation would drop `exec(req.body, req.query)`'s second finding). The
+ * propagation engine dedups by this exact key BEFORE its deterministic cap
+ * (`maxFindingsPerFunction`) and counts the overflow; this module templates
+ * the same coordinates into the edge id (binding identity via the shared
+ * `bindingKey`; the free-text `property` rides LAST so it can never collide
+ * into another component) and warns with the drop count on truncation.
+ *
+ * `reason` carries the versioned hop encoding (`taint/path-codec.ts` — U6's
+ * `explain` decodes the same module) for `TAINTED`, and the killed binding's
+ * plain name for `SANITIZES` (M0/S1 queryability verdict, like REACHING_DEF).
+ *
+ * ## Warn split (R4 vs noise)
+ *
+ * Unsafe-site skips and cap drops warn PER FUNCTION here (rare, actionable —
+ * mirrors `emitFileReachingDefs`' malformed/cap warns). Solver coverage gaps
+ * (`truncated`/`overflow`) do NOT re-warn per function: the RD layer already
+ * warned for the same function with the same solver status (same `maxFacts`
+ * derivation — see step 4), and a duplicate `[taint]` line per mega-function
+ * would be pure spam. They are counted (+ exampled) in the result and the
+ * run.ts caller aggregates them into ONE unconditional `logger.warn` per
+ * language (R4) — never dropped on the floor (the M2 lesson).
+ */
+import type { ParsedImport } from '../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../graph/types.js';
+import type { FunctionCfg } from '../cfg/types.js';
+export { DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from './propagate.js';
+import type { SourceSinkSanitizerSpec } from './source-sink-config.js';
+export interface TaintEmitLimits {
+    /** Per-function findings cap (post-dedup). `undefined` ⇒
+     *  {@link DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION}; `0` ⇒ unlimited. */
+    readonly maxFindingsPerFunction?: number;
+    /** Per-finding hop cap (source-side prefix kept). `undefined` ⇒
+     *  {@link DEFAULT_PDG_MAX_TAINT_HOPS}; `0` ⇒ unlimited. */
+    readonly maxHops?: number;
+    /**
+     * Solver fact-materialization cap for the taint-side `computeReachingDefs`
+     * call. `undefined` ⇒ {@link DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION}
+     * (the M2 derived default — see the module doc for why it is REUSED rather
+     * than derived from the findings cap); `0` ⇒ unlimited.
+     */
+    readonly maxFacts?: number;
+}
+/**
+ * Full taint-emit telemetry for one file. EVERY counter is surfaced by the
+ * run.ts aggregate (the M2 emit result had two fields dropped on the floor —
+ * the plan names that mistake; don't repeat it).
+ */
+export interface TaintEmitResult {
+    /** Functions fully propagated (`computeTaintFlows` returned `computed`). */
+    functionsAnalyzed: number;
+    /** Functions skipped by the zero-match fast path (no solver call). */
+    functionsSkippedNoMatch: number;
+    /** Functions whose `sites` failed {@link hasTaintSafeSites} (skip-taint-keep-RD). */
+    functionsSkippedUnsafeSites: number;
+    /** Source+sink functions skipped on a non-`computed` solver status (R4). */
+    functionsCoverageGap: {
+        truncated: number;
+        overflow: number;
+        'no-facts': number;
+    };
+    /** TAINTED edges persisted. */
+    findingsEmitted: number;
+    /** SANITIZES edges persisted (emitted even when findings are zero). */
+    killsEmitted: number;
+    /** Findings dropped by the per-function cap (post-dedup), summed. */
+    findingsDropped: number;
+    /** Findings whose persisted hop path is a truncated prefix (hop/byte cap). */
+    hopsTruncatedFindings: number;
+    /** ≤{@link MAX_EXAMPLES} `file:line` anchors of gap/unsafe-site functions. */
+    coverageGapExamples: string[];
+    /** ≤{@link MAX_EXAMPLES} `file:line` anchors of cap-dropped functions. */
+    droppedExamples: string[];
+}
+/**
+ * Run the taint pass over one file's emit-safe CFGs and persist TAINTED +
+ * SANITIZES edges. `cfgs` MUST already be `isEmitSafeCfg`-filtered (the same
+ * `wellFormed` array the caller fed `emitFileCfgs`/`emitFileReachingDefs`) —
+ * block/edge anchors are trusted here; only the M3 `sites` layer is
+ * re-validated (`hasTaintSafeSites`). Never throws on well-formed input;
+ * the caller's per-file try isolates the rest.
+ */
+export declare function emitFileTaint(graph: KnowledgeGraph, cfgs: readonly FunctionCfg[], parsedImports: readonly ParsedImport[], spec: SourceSinkSanitizerSpec, limits?: TaintEmitLimits, onWarn?: (message: string) => void): TaintEmitResult;