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

package/dist/core/ingestion/taint/path-codec.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Taint-path reason codec (#2083 M3 U4/U6, plan KTD6).
+ *
+ * THE one shared encoder/decoder for the hop-encoded `reason` carried on
+ * persisted `TAINTED` edges: the U4 emit path writes it, the U6 MCP `explain`
+ * tool reads it. Two hand-rolled copies of a wire format drift — both sides
+ * MUST import from here.
+ *
+ * ## Wire format (version `1`)
+ *
+ * ```
+ * 1[;<kind>]|<name>:<line>[:<flags>]|<name>:<line>[:<flags>]|…[|~]
+ * ```
+ *
+ * - One-character version prefix (`TAINT_PATH_CODEC_VERSION`), then an
+ *   OPTIONAL `;<kind>` header segment, then ordered source→sink hops, each
+ *   `variable:line[:flags]`.
+ * - `kind` is the finding's sink category (`SinkKind`, e.g.
+ *   `command-injection`). It rides the reason because it is the ONLY
+ *   persisted channel: the CodeRelation columns are
+ *   `type/confidence/reason/step` — `step` is INT32 and the emit-time edge id
+ *   (which embeds the kind) is not a stored column. The U6 `explain` tool
+ *   reads it for finding classification. Charset `[a-z0-9-]` (printable
+ *   ASCII, disjoint from every structural delimiter); `;` itself is printable
+ *   ASCII and never appears in hop names (identifier charset) or flags.
+ *   U6 deviation note: this header was added by U6 WITHIN version `1` —
+ *   U4 and U6 ship in the same release, so no reason string without the
+ *   header was ever persisted by a released build; the decoder still accepts
+ *   header-less strings (`kind` simply decodes as `undefined`).
+ * - `flags` is a lowercase-letter set; only `c` (= the hop passed through an
+ *   unmodeled call, KTD5 `viaCall`) is defined today — the rest of the
+ *   alphabet is RESERVED, and the decoder accepts unknown flag letters so a
+ *   future writer's output stays decodable.
+ * - A trailing `|~` segment is the TRUNCATION MARKER: the encoded path is a
+ *   source-side PREFIX of the real one (hop cap, byte cap, or an unencodable
+ *   hop name). Decoders MUST report it as "path incomplete" — never an error.
+ *
+ * ## Delimiter / round-trip discipline (KTD6)
+ *
+ * Every structural character (`|`, `:`, `~`, digits, flag letters) is
+ * printable ASCII: `sanitizeUTF8` (csv-generator.ts) strips control
+ * characters, lone surrogates, and U+FFFE/FFFF — printable ASCII passes
+ * through byte-exact, so the encoding survives `escapeCSVField ∘
+ * sanitizeUTF8` and the DB load unchanged (pinned by the round-trip test).
+ * None of the delimiters can appear in a JS identifier.
+ *
+ * Hop names are identifier-charset by U1 construction (the harvest records
+ * binding names), but the encoder DEFENDS anyway: a hop whose name falls
+ * outside the safe charset (or whose line is not a non-negative integer) is
+ * never emitted — encoding stops at the offending hop and sets the truncation
+ * marker, preserving the prefix-of-the-true-path invariant rather than
+ * corrupting the format. (`#` is in the charset: JS private names are
+ * `#field`, and the propagation engine's fallback hop names are `#<idx>`.)
+ *
+ * The byte cap (`TAINT_REASON_MAX_BYTES`, KTD6's "absolute reason-byte cap")
+ * bounds the persisted reason column regardless of hop caps: overflow drops
+ * TRAILING hops (keeps the source side) and sets the marker. All structural
+ * chars and valid names are single-byte ASCII, so `string.length` IS the
+ * byte length.
+ */
+/** One-character format version prefix. Bump on any wire-format change. */
+export declare const TAINT_PATH_CODEC_VERSION = "1";
+/**
+ * Absolute cap on the encoded reason's byte length (KTD6). 4096 comfortably
+ * holds ~100 hops of realistic identifiers — far beyond the default hop cap
+ * (32) — while bounding the persisted column even at `maxHops: 0` (unlimited).
+ */
+export declare const TAINT_REASON_MAX_BYTES = 4096;
+/** The truncation-marker segment content (rides as a trailing `|~`). */
+export declare const TAINT_PATH_TRUNCATION_MARKER = "~";
+/** Encoder input hop — shape-compatible with `TaintHop` (propagate.ts). */
+export interface TaintPathHopInput {
+    readonly name: string;
+    readonly line: number;
+    readonly viaCall?: boolean;
+}
+export interface EncodeTaintPathOptions {
+    /**
+     * The hop list is already a truncated prefix (e.g. the propagation engine's
+     * `hopsTruncated` from its hop cap) — emit the marker even when every hop
+     * fits.
+     */
+    readonly truncated?: boolean;
+    /** Byte cap override (tests). Default {@link TAINT_REASON_MAX_BYTES}. */
+    readonly maxBytes?: number;
+    /**
+     * Finding sink category (`SinkKind`) carried in the `;<kind>` header — the
+     * only persisted channel for it (see the module doc). A value outside the
+     * `[a-z0-9-]` charset is DROPPED (header omitted), never corrupted into the
+     * wire string; `SinkKind` is a closed lowercase-hyphen union so this is
+     * purely defensive.
+     */
+    readonly kind?: string;
+}
+export interface EncodedTaintPath {
+    /** The wire string for the TAINTED edge's `reason` column. */
+    readonly reason: string;
+    /** True when the marker was emitted (caller-flagged, byte cap, or bad hop). */
+    readonly truncated: boolean;
+}
+export interface DecodedTaintHop {
+    readonly variable: string;
+    readonly line: number;
+    /** The hop passed through an unmodeled call (flag `c`, KTD5). */
+    readonly viaCall: boolean;
+}
+export interface DecodedTaintPath {
+    readonly ok: true;
+    readonly version: string;
+    /** Finding sink category from the `;<kind>` header; absent when not encoded. */
+    readonly kind?: string;
+    /** Ordered source→sink hops (a PREFIX when `truncated`). */
+    readonly hops: readonly DecodedTaintHop[];
+    /** Path incomplete (trailing `|~`) — informational, NOT an error. */
+    readonly truncated: boolean;
+}
+/** Typed parse failure — the decoder never throws. */
+export interface TaintPathDecodeFailure {
+    readonly ok: false;
+    readonly error: string;
+}
+export type TaintPathDecodeResult = DecodedTaintPath | TaintPathDecodeFailure;
+/**
+ * Encode an ordered hop list into the versioned `reason` wire string.
+ * Deterministic; never throws. See the module doc for the format and the
+ * three truncation triggers (caller flag, unencodable hop, byte cap).
+ */
+export declare function encodeTaintPath(hops: readonly TaintPathHopInput[], options?: EncodeTaintPathOptions): EncodedTaintPath;
+/**
+ * Decode a `reason` wire string. Returns a typed failure for anything that is
+ * not a well-formed version-`1` path — never throws. A truncated path decodes
+ * `ok: true` with `truncated: true` ("path incomplete", per KTD6).
+ */
+export declare function decodeTaintPath(reason: unknown): TaintPathDecodeResult;

package/dist/core/ingestion/taint/path-codec.js

@@ -0,0 +1,190 @@
+/**
+ * Taint-path reason codec (#2083 M3 U4/U6, plan KTD6).
+ *
+ * THE one shared encoder/decoder for the hop-encoded `reason` carried on
+ * persisted `TAINTED` edges: the U4 emit path writes it, the U6 MCP `explain`
+ * tool reads it. Two hand-rolled copies of a wire format drift — both sides
+ * MUST import from here.
+ *
+ * ## Wire format (version `1`)
+ *
+ * ```
+ * 1[;<kind>]|<name>:<line>[:<flags>]|<name>:<line>[:<flags>]|…[|~]
+ * ```
+ *
+ * - One-character version prefix (`TAINT_PATH_CODEC_VERSION`), then an
+ *   OPTIONAL `;<kind>` header segment, then ordered source→sink hops, each
+ *   `variable:line[:flags]`.
+ * - `kind` is the finding's sink category (`SinkKind`, e.g.
+ *   `command-injection`). It rides the reason because it is the ONLY
+ *   persisted channel: the CodeRelation columns are
+ *   `type/confidence/reason/step` — `step` is INT32 and the emit-time edge id
+ *   (which embeds the kind) is not a stored column. The U6 `explain` tool
+ *   reads it for finding classification. Charset `[a-z0-9-]` (printable
+ *   ASCII, disjoint from every structural delimiter); `;` itself is printable
+ *   ASCII and never appears in hop names (identifier charset) or flags.
+ *   U6 deviation note: this header was added by U6 WITHIN version `1` —
+ *   U4 and U6 ship in the same release, so no reason string without the
+ *   header was ever persisted by a released build; the decoder still accepts
+ *   header-less strings (`kind` simply decodes as `undefined`).
+ * - `flags` is a lowercase-letter set; only `c` (= the hop passed through an
+ *   unmodeled call, KTD5 `viaCall`) is defined today — the rest of the
+ *   alphabet is RESERVED, and the decoder accepts unknown flag letters so a
+ *   future writer's output stays decodable.
+ * - A trailing `|~` segment is the TRUNCATION MARKER: the encoded path is a
+ *   source-side PREFIX of the real one (hop cap, byte cap, or an unencodable
+ *   hop name). Decoders MUST report it as "path incomplete" — never an error.
+ *
+ * ## Delimiter / round-trip discipline (KTD6)
+ *
+ * Every structural character (`|`, `:`, `~`, digits, flag letters) is
+ * printable ASCII: `sanitizeUTF8` (csv-generator.ts) strips control
+ * characters, lone surrogates, and U+FFFE/FFFF — printable ASCII passes
+ * through byte-exact, so the encoding survives `escapeCSVField ∘
+ * sanitizeUTF8` and the DB load unchanged (pinned by the round-trip test).
+ * None of the delimiters can appear in a JS identifier.
+ *
+ * Hop names are identifier-charset by U1 construction (the harvest records
+ * binding names), but the encoder DEFENDS anyway: a hop whose name falls
+ * outside the safe charset (or whose line is not a non-negative integer) is
+ * never emitted — encoding stops at the offending hop and sets the truncation
+ * marker, preserving the prefix-of-the-true-path invariant rather than
+ * corrupting the format. (`#` is in the charset: JS private names are
+ * `#field`, and the propagation engine's fallback hop names are `#<idx>`.)
+ *
+ * The byte cap (`TAINT_REASON_MAX_BYTES`, KTD6's "absolute reason-byte cap")
+ * bounds the persisted reason column regardless of hop caps: overflow drops
+ * TRAILING hops (keeps the source side) and sets the marker. All structural
+ * chars and valid names are single-byte ASCII, so `string.length` IS the
+ * byte length.
+ */
+/** One-character format version prefix. Bump on any wire-format change. */
+export const TAINT_PATH_CODEC_VERSION = '1';
+/**
+ * Absolute cap on the encoded reason's byte length (KTD6). 4096 comfortably
+ * holds ~100 hops of realistic identifiers — far beyond the default hop cap
+ * (32) — while bounding the persisted column even at `maxHops: 0` (unlimited).
+ */
+export const TAINT_REASON_MAX_BYTES = 4096;
+/** The truncation-marker segment content (rides as a trailing `|~`). */
+export const TAINT_PATH_TRUNCATION_MARKER = '~';
+/**
+ * Safe hop-name charset: ASCII identifier characters plus `#` (JS private
+ * names / the propagation engine's `#<idx>` fallback). Deliberately ASCII-only
+ * — a Unicode identifier is VALID JS but is skipped (truncation marker) rather
+ * than risking a `sanitizeUTF8` byte change breaking decode (defensive
+ * simplification; documented FN on path completeness, never on the finding).
+ */
+const SAFE_NAME = /^[A-Za-z0-9_$#]+$/;
+/** Decoder-side flags charset — `c` defined, the rest reserved (see module doc). */
+const FLAGS = /^[a-z]*$/;
+/**
+ * Kind-header charset: lowercase + digits + hyphen — covers every `SinkKind`
+ * label and stays disjoint from the structural delimiters (`;|:~`).
+ */
+const SAFE_KIND = /^[a-z0-9-]+$/;
+/**
+ * Encode an ordered hop list into the versioned `reason` wire string.
+ * Deterministic; never throws. See the module doc for the format and the
+ * three truncation triggers (caller flag, unencodable hop, byte cap).
+ */
+export function encodeTaintPath(hops, options) {
+    // Kind header (defensively validated — see EncodeTaintPathOptions.kind).
+    const kindHeader = typeof options?.kind === 'string' && SAFE_KIND.test(options.kind) ? `;${options.kind}` : '';
+    // Floor: version char + kind header + room for the marker — a smaller cap
+    // could not hold even the empty truncated path. The header is identity
+    // material (finding classification), so it is never sacrificed to the byte
+    // cap; trailing hops are.
+    const maxBytes = Math.max(options?.maxBytes ?? TAINT_REASON_MAX_BYTES, TAINT_PATH_CODEC_VERSION.length + kindHeader.length + 2);
+    let truncated = options?.truncated === true;
+    const segments = [];
+    let total = TAINT_PATH_CODEC_VERSION.length + kindHeader.length;
+    for (const hop of hops) {
+        if (typeof hop.name !== 'string' ||
+            !SAFE_NAME.test(hop.name) ||
+            !Number.isInteger(hop.line) ||
+            hop.line < 0) {
+            // Unencodable hop: drop it AND everything after it so the emitted hops
+            // stay a faithful source-side prefix (a silent mid-path gap would lie).
+            truncated = true;
+            break;
+        }
+        const segment = `|${hop.name}:${hop.line}${hop.viaCall === true ? ':c' : ''}`;
+        if (total + segment.length > maxBytes) {
+            truncated = true;
+            break;
+        }
+        segments.push(segment);
+        total += segment.length;
+    }
+    if (truncated) {
+        // Make room for the trailing `|~` marker (drop trailing hops as needed).
+        while (segments.length > 0 && total + 2 > maxBytes) {
+            total -= segments.pop().length;
+        }
+    }
+    const reason = TAINT_PATH_CODEC_VERSION +
+        kindHeader +
+        segments.join('') +
+        (truncated ? `|${TAINT_PATH_TRUNCATION_MARKER}` : '');
+    return { reason, truncated };
+}
+/**
+ * Decode a `reason` wire string. Returns a typed failure for anything that is
+ * not a well-formed version-`1` path — never throws. A truncated path decodes
+ * `ok: true` with `truncated: true` ("path incomplete", per KTD6).
+ */
+export function decodeTaintPath(reason) {
+    if (typeof reason !== 'string' || reason.length === 0) {
+        return { ok: false, error: 'empty or non-string reason' };
+    }
+    const version = reason[0];
+    if (version !== TAINT_PATH_CODEC_VERSION) {
+        return { ok: false, error: `unsupported taint-path version '${version}'` };
+    }
+    let body = reason.slice(1);
+    // Optional `;<kind>` header segment (finding sink category — see module doc).
+    let kind;
+    if (body.startsWith(';')) {
+        const headerEnd = body.indexOf('|');
+        kind = headerEnd === -1 ? body.slice(1) : body.slice(1, headerEnd);
+        if (!SAFE_KIND.test(kind)) {
+            return { ok: false, error: `invalid kind header '${kind}'` };
+        }
+        body = headerEnd === -1 ? '' : body.slice(headerEnd);
+    }
+    const hops = [];
+    if (body.length === 0)
+        return { ok: true, version, ...(kind ? { kind } : {}), hops, truncated: false };
+    if (!body.startsWith('|')) {
+        return { ok: false, error: 'malformed body: expected a hop separator after the version' };
+    }
+    const parts = body.slice(1).split('|');
+    let truncated = false;
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (part === TAINT_PATH_TRUNCATION_MARKER) {
+            if (i !== parts.length - 1) {
+                return { ok: false, error: 'truncation marker not in trailing position' };
+            }
+            truncated = true;
+            break;
+        }
+        const fields = part.split(':');
+        if (fields.length < 2 || fields.length > 3) {
+            return { ok: false, error: `malformed hop segment '${part}'` };
+        }
+        const [name, lineStr, flags = ''] = fields;
+        if (!SAFE_NAME.test(name)) {
+            return { ok: false, error: `invalid hop variable '${name}'` };
+        }
+        if (!/^\d+$/.test(lineStr)) {
+            return { ok: false, error: `invalid hop line '${lineStr}'` };
+        }
+        if (!FLAGS.test(flags)) {
+            return { ok: false, error: `invalid hop flags '${flags}'` };
+        }
+        hops.push({ variable: name, line: Number(lineStr), viaCall: flags.includes('c') });
+    }
+    return { ok: true, version, ...(kind ? { kind } : {}), hops, truncated };
+}

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

@@ -0,0 +1,216 @@
+/**
+ * Pure intra-procedural taint propagation engine (#2083 M3 U3).
+ *
+ * Forward taint reachability over one function's reaching-definition facts
+ * (M2 `computeReachingDefs`) and matched taint sites (U2 `matchFunctionSites`)
+ * — sources in, findings + sanitizer kills + coverage status out. PURE AND
+ * DETERMINISTIC, mirroring the reaching-defs contract: no graph, no I/O, no
+ * logger; insertion-ordered worklist; explicitly sorted outputs; snapshot
+ * tests and content-derived edge ids (U4) rely on it.
+ *
+ * PRECONDITIONS: the caller gates the CFG through `hasTaintSafeSites`
+ * (taint/site-safety.ts) and the emit-safety checks before calling — this
+ * module dereferences binding/site/statement indices without re-validating.
+ *
+ * ## The two-rule model (plan HTD)
+ *
+ * - **Rule (b), statement-local:** a matched SOURCE occurrence (member read)
+ *   whose intra-statement occurrence path — the member-read's `parent` chain —
+ *   reaches a matched SINK argument position produces an immediate single-hop
+ *   finding (`exec(req.body)`). The same statement SEEDS taint: every binding
+ *   the statement defines becomes tainted (see the precision floor below).
+ * - **Rule (a), worklist:** for each tainted `(binding, defPoint)`, every
+ *   def→use fact delivers the taint to a use statement, where occurrences of
+ *   the binding in matched sink argument positions produce findings and the
+ *   statement's own defs are tainted onward. The fact graph contains genuine
+ *   cycles (loop back-edges, same-statement self-facts) — the visited-set
+ *   discipline below is load-bearing, not defensive.
+ *
+ * ## Sanitizer semantics — the KIND-SET exclusion model (KTD4, sharpened)
+ *
+ * The plan sketches a binary kill; this module implements the strictly more
+ * precise SOUND refinement: a taint carries a set of *excluded* (neutralized)
+ * `SinkKind`s accumulated through sanitizer hops, and a sink fires unless its
+ * kind is in the taint's exclusion set. A binary kill is the special case
+ * where the sanitizer neutralizes the sink's kind; the kind-set model
+ * additionally keeps `const b = escape(req.body); db.query(b)` a FINDING
+ * (an HTML escaper does not neutralize SQL — un-tainting `b` outright would
+ * be a suppressed live injection, the forbidden false-negative direction)
+ * while still suppressing `res.send(b)` (xss IS neutralized).
+ *
+ * - **Occurrence interposition (KTD4a):** evaluated over the U1 site
+ *   structure. An occurrence reaching a sink arg / def-feeding position
+ *   through a matched sanitizer site accumulates that sanitizer's
+ *   `neutralizes` kinds on that PATH; a direct occurrence contributes the
+ *   empty set. Per-position narrowing (`entry.args`) is respected; receiver
+ *   flow through a sanitizer is NOT neutralized (the receiver is not the
+ *   sanitized payload), and spread/template positions are never neutralized
+ *   (position unprovable) — both sound-direction choices (under-kill).
+ * - **Intersection over paths:** a def fed by several occurrence paths
+ *   excludes a kind only when EVERY path neutralizes it
+ *   (`const c = cond ? escape(b) : b` taints `c` with NO exclusions — the
+ *   direct arm's ∅ intersects everything away). Equally, a taint re-derived
+ *   along a second route keeps the INTERSECTION of the exclusion sets and is
+ *   re-processed whenever the set SHRINKS — a less-neutralized taint is
+ *   strictly more dangerous. Exclusion sets only shrink over a finite
+ *   lattice, so the worklist terminates.
+ * - **Kill locality (KTD4b):** a kill applies to the def the sanitizer
+ *   produces (`SiteRecord.resultDefs`) only; the flowing binding's own taint
+ *   is untouched (`const c = escape(b); exec(b)` still finds `b`'s flow).
+ *   `x = escape(x)` works because taint keys on the DEF POINT: the
+ *   sanitizer statement's def enters the set with the sanitizer's kinds
+ *   excluded, while the seed def keeps flowing wherever the CFG still
+ *   carries it (zero-iteration loops, conditional sanitizers — may-path
+ *   mechanics need no special handling here, kills are absent from facts).
+ *
+ * ## Statement-coalescing precision floor (documented FP)
+ *
+ * Statement facts conflate multi-declarator statements: a statement that
+ * uses tainted `b` and defines `c` taints `c` with NO exclusions even when
+ * the two are textually unrelated (`const a = clean(z), b = g(t)` floor-
+ * taints `a` from `t` — pinned by a test). The per-declarator `resultDefs`
+ * precision narrows the EXCLUSION computation (and powers kills) only — a
+ * def in a call's `resultDefs` is fed exactly through that call, so its
+ * exclusions come from the paths into it; when the tainted input provably
+ * never flows into that call, the floor still taints the def (sound) but
+ * records no kill (a kill requires evidence of flow through the sanitizer).
+ *
+ * ## Propagate-through (KTD5)
+ *
+ * Taint in any argument or in the receiver of an UNMODELED call flows to
+ * the call's result defs, marked `viaCall` on the hop so `explain` can
+ * express lower confidence. An occurrence that reaches the unmodeled call
+ * only through a sanitizer carries the neutralization through
+ * (`const y = unknownFn(escape(b))` excludes the sanitizer's kinds — the
+ * plan's deliberate precision choice over flat-conservative).
+ *
+ * ## Kills output
+ *
+ * `kills` records every sanitizer that ACTUALLY neutralized kinds on a
+ * flowing taint — U4 emits `SANITIZES` edges from them. Two shapes share the
+ * record: result-def kills (`killedDef` = the def the sanitizer produces;
+ * `bindingIdx` = that def's binding) and value-position interposition kills
+ * (`exec(escape(x))` — no def exists; `killedDef` = the sink statement's own
+ * point, `bindingIdx` = the interposed binding). Interposition kills are
+ * recorded only when the (input, sink, position) produced no finding — a
+ * bypassed sanitizer (`exec(x + escape(x))`) killed nothing.
+ */
+import type { FunctionCfg } from '../cfg/types.js';
+import type { FunctionDefUse, ProgramPoint } from '../cfg/reaching-defs.js';
+import type { FunctionSiteMatches } from './match.js';
+import type { SinkKind, SourceKind } from './source-sink-config.js';
+/**
+ * Default per-function findings cap (U5 config resolution; cfg/emit.ts
+ * DEFAULT_* pattern). Resolved into the RepoMeta `pdg` stamp by
+ * `resolvePdgConfig` so a cap change trips full writeback; `0` = unlimited
+ * is preserved like the other pdg caps. 200 is generous — a real function
+ * with more deduped source→sink findings is a fixture or a disaster, and
+ * the truncation is deterministic + counted (`droppedFindings`).
+ */
+export declare const DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION = 200;
+/**
+ * Default per-finding hop cap (U5; joins the RepoMeta `pdg` stamp like the
+ * findings cap). Bounds the persisted `reason` hop encoding (KTD6 pins the
+ * hop cap in config); 32 intra-procedural def→use hops is far beyond any
+ * legible path — overflow keeps the source-side prefix and sets
+ * `hopsTruncated`, parsed downstream as "path incomplete", never an error.
+ */
+export declare const DEFAULT_PDG_MAX_TAINT_HOPS = 32;
+export interface TaintLimits {
+    /**
+     * Maximum findings per function AFTER dedup; the sorted finding list is
+     * truncated deterministically and the overflow counted in
+     * `droppedFindings`. `undefined`/0 ⇒ unlimited.
+     */
+    readonly maxFindingsPerFunction?: number;
+    /**
+     * Maximum hops retained per finding (source-side prefix kept); overflow
+     * sets `hopsTruncated`. `undefined`/0 ⇒ unlimited.
+     */
+    readonly maxHops?: number;
+}
+/** One hop of a finding's path — enough for U4's reason codec (name, line, flag). */
+export interface TaintHop {
+    /** Index into the function's binding table. */
+    readonly bindingIdx: number;
+    /** Resolved binding name (carried so U4 never re-joins the table). */
+    readonly name: string;
+    readonly point: ProgramPoint;
+    /** The value passed through an unmodeled call to get here (KTD5). */
+    readonly viaCall?: boolean;
+}
+/**
+ * The KTD6 rule-(b) source identity material: the matched member-read
+ * occurrence itself — statement point + site index + object/property. For
+ * worklist findings this is the ROOT source the taint chain was seeded from.
+ */
+export interface TaintSourceOccurrence {
+    readonly point: ProgramPoint;
+    /** Index into the source statement's `sites` array. */
+    readonly siteIndex: number;
+    readonly objectBindingIdx: number;
+    readonly property: string;
+    readonly kind: SourceKind;
+}
+/** The sink side of a finding's identity: point + site + argument + binding. */
+export interface TaintSinkOccurrence {
+    readonly point: ProgramPoint;
+    /** Index into the sink statement's `sites` array. */
+    readonly siteIndex: number;
+    /** Matched sink argument position the tainted occurrence landed in. */
+    readonly argIndex: number;
+    /**
+     * The binding whose occurrence reached the sink position (for rule-(b)
+     * findings: the source member-read's object binding).
+     */
+    readonly bindingIdx: number;
+    /** The matched sink entry's `name` (e.g. `exec`) — finding classification. */
+    readonly entryName: string;
+}
+export interface TaintFinding {
+    readonly sinkKind: SinkKind;
+    readonly source: TaintSourceOccurrence;
+    readonly sink: TaintSinkOccurrence;
+    /**
+     * Ordered source→sink path, one path per finding (the CodeQL
+     * `--max-paths=1` convention): the taint chain's def hops followed by the
+     * sink-use hop. Rule-(b) findings carry the single sink-statement hop.
+     */
+    readonly hops: readonly TaintHop[];
+    readonly hopsTruncated?: boolean;
+}
+/** A sanitizer that neutralized kinds on a flowing taint — U4's SANITIZES rows. */
+export interface SanitizerKill {
+    /** Statement point of the sanitizer call site. */
+    readonly sanitizer: ProgramPoint;
+    /**
+     * The killed def's point (result-def kills — always the sanitizer's own
+     * statement in the intra-statement model) or the suppressed sink
+     * statement's point (value-position interposition kills).
+     */
+    readonly killedDef: ProgramPoint;
+    /** The killed def's binding, or the interposed binding for value-position kills. */
+    readonly bindingIdx: number;
+    /** Sorted, deduped kinds the sanitizer neutralized at that position. */
+    readonly neutralized: readonly SinkKind[];
+}
+export interface FunctionTaintResult {
+    /**
+     * `computed`     — full propagation ran.
+     * `coverage-gap` — the solver result was not `computed`; the function is
+     *                  skipped for findings entirely (R4: never partially
+     *                  analyzed), `gapReason` carries the solver status.
+     */
+    readonly status: 'computed' | 'coverage-gap';
+    readonly gapReason?: 'truncated' | 'overflow' | 'no-facts';
+    /** Deduped (KTD6 identity), deterministically sorted, capped. */
+    readonly findings: readonly TaintFinding[];
+    readonly kills: readonly SanitizerKill[];
+    /** Findings dropped by `maxFindingsPerFunction` (post-dedup). */
+    readonly droppedFindings: number;
+}
+/**
+ * Compute taint flows for one function. See the module doc for the two-rule
+ * model, the kind-set exclusion semantics, and the precision floor.
+ */
+export declare function computeTaintFlows(cfg: FunctionCfg, defUse: FunctionDefUse, matches: FunctionSiteMatches, limits?: TaintLimits): FunctionTaintResult;