gitnexus 1.6.8-rc.8 → 1.6.8

package/dist/core/ingestion/taint/match.js

@@ -0,0 +1,278 @@
+/**
+ * Import-aware taint-site matcher (#2083 M3 U2, plan KTD7).
+ *
+ * Classifies a function's harvested {@link SiteRecord}s against a registered
+ * {@link SourceSinkSanitizerSpec}: which member reads are SOURCES, which
+ * call/new sites are SINKS (and at which argument positions), and which are
+ * SANITIZERS. Pure main-thread data work — sites + bindings come from the U1
+ * worker harvest, imports from `ParsedFile.parsedImports`; no AST, no I/O.
+ *
+ * PRECONDITION: the caller must gate the CFG through `hasTaintSafeSites`
+ * (taint/site-safety.ts) first — this module dereferences binding/site
+ * indices without re-validating them.
+ *
+ * ## Callee resolution precedence (bare and member-rooted calls)
+ *
+ * 1. ESM import join — the callee root's local name is resolved through the
+ *    {@link TaintImportIndex} built from `parsedImports` (`named`/`alias`
+ *    members, `namespace`/default-import module handles); `import { exec as
+ *    run } from 'child_process'` makes `run(c)` resolve to
+ *    `child_process.exec`, and `import * as cp …` makes `cp.exec(c)` resolve
+ *    the same way.
+ * 2. require-literal join — a binding whose in-function defining site carries
+ *    `requireArg` resolves like a namespace handle (`const cp =
+ *    require('child_process'); cp.exec(c)`). A BARE call of a require-joined
+ *    binding is matched under BOTH interpretations, `<module>.default` (the
+ *    module/default export invoked directly) and `<module>.<localName>`
+ *    (non-renamed destructured require — the harvest attaches `resultDefs`
+ *    to destructured bindings without recording the property path, and the
+ *    binding name IS the member name in the non-renamed case).
+ * 3. Bare-name fallback — TRUE GLOBALS only (`global: true` entries: `eval`,
+ *    `new Function`, `encodeURIComponent`), and only when the name is neither
+ *    import-bound nor shadowed. Conventional receiver names (`req`/`request`
+ *    member-read sources, `res.send`, `.query`/`.execute`) are matched
+ *    name-based by their own mechanisms, never via the global fallback.
+ *
+ * ## Shadowing rule (exact)
+ *
+ * A name is treated as function-local — blocking import/global resolution —
+ * iff the function's binding table contains a NON-`synthetic` entry with that
+ * name (an in-function `function exec(){}` / `const exec = …`). Synthetic
+ * bindings (kind `module`, `synthetic: true`) are imports, true globals, or
+ * enclosing-scope captures and do not shadow. Member-call roots use the
+ * harvested `receiver` binding index directly (no name scan).
+ *
+ * ## Documented resolution gaps (direction stated, per plan KTD10)
+ *
+ * - MODULE-LEVEL `const cp = require('child_process')`: the binding is
+ *   synthetic inside the function, produces no `ParsedImport`, and its
+ *   defining site lives outside the function's harvested sites — the
+ *   require join cannot see it. Module-mechanism sinks miss (FN) and
+ *   sanitizers don't kill (FP noise — never a false kill, the safe
+ *   direction). Only in-function requires resolve.
+ * - RENAMED destructured require (`const { exec: run } = require(…)`):
+ *   the dual interpretation resolves `run` to `child_process.run` — no
+ *   match (FN). Non-renamed destructures resolve exactly.
+ * - CONSERVATIVE shadow scan for bare calls: ANY non-synthetic binding of
+ *   the callee name anywhere in the function blocks import/global
+ *   resolution, even when the shadow is block-scoped elsewhere and the call
+ *   site actually sees the import (FN; rare; safe for sanitizers).
+ * - MODULE-LEVEL user declarations are indistinguishable from imports in
+ *   the binding table (both synthetic). ESM forbids a module-level
+ *   declaration colliding with an import name, so the import join is
+ *   authoritative when an import exists; a module-level user function
+ *   shadowing a TRUE GLOBAL (e.g. a local `encodeURIComponent`) is not
+ *   detectable and would still match (pathological; accepted).
+ * - Handle COPIES (`const c2 = cp; c2.exec(…)`) are not followed — joins
+ *   are one level deep (binding → import/require), never through
+ *   assignments (FN).
+ * - `this.`/`super.`-rooted and call-rooted callee chains have no
+ *   resolvable root: only the syntactic `anyReceiver`/`receivers`
+ *   mechanisms can match them.
+ * - `reexport`/`wildcard`/`dynamic-*`/`side-effect` imports introduce no
+ *   matcher-visible local binding and are skipped by the index.
+ */
+const stripNodeScheme = (specifier) => specifier.startsWith('node:') ? specifier.slice('node:'.length) : specifier;
+/**
+ * Build the local-name → module/member index from a file's `parsedImports`.
+ * Only `named`/`alias`/`namespace` kinds bind matcher-visible local names;
+ * `importedName === 'default'` collapses to a module handle.
+ */
+export function buildTaintImportIndex(imports) {
+    const index = new Map();
+    for (const imp of imports) {
+        if (imp.kind === 'named' || imp.kind === 'alias') {
+            const module = stripNodeScheme(imp.targetRaw);
+            index.set(imp.localName, imp.importedName === 'default' ? { module } : { module, member: imp.importedName });
+        }
+        else if (imp.kind === 'namespace') {
+            index.set(imp.localName, { module: stripNodeScheme(imp.targetRaw) });
+        }
+    }
+    return index;
+}
+/**
+ * Classify a function's harvested sites against a language spec. See the
+ * module doc for resolution precedence, the shadowing rule, and gaps.
+ */
+export function matchFunctionSites(cfg, spec, imports) {
+    const bindings = cfg.bindings ?? [];
+    // Non-synthetic (in-function-declared) binding indices by name — the
+    // shadow scan + bare-call require-join lookup.
+    const nonSyntheticByName = new Map();
+    bindings.forEach((b, i) => {
+        if (b.synthetic === true)
+            return;
+        const list = nonSyntheticByName.get(b.name);
+        if (list)
+            list.push(i);
+        else
+            nonSyntheticByName.set(b.name, [i]);
+    });
+    // require-literal join: binding index → module specifier. A binding def'd
+    // by two DIFFERENT require literals is conflicted → dropped (resolving it
+    // either way could fabricate a sanitizer kill).
+    const requireByBinding = new Map();
+    const conflicted = new Set();
+    for (const block of cfg.blocks) {
+        for (const stmt of block.statements ?? []) {
+            for (const site of stmt.sites ?? []) {
+                if (site.requireArg === undefined || site.resultDefs === undefined)
+                    continue;
+                const module = stripNodeScheme(site.requireArg);
+                for (const def of site.resultDefs) {
+                    if (conflicted.has(def))
+                        continue;
+                    const prior = requireByBinding.get(def);
+                    if (prior === undefined)
+                        requireByBinding.set(def, module);
+                    else if (prior !== module) {
+                        requireByBinding.delete(def);
+                        conflicted.add(def);
+                    }
+                }
+            }
+        }
+    }
+    const resolveCallee = (site) => {
+        if (site.callee === undefined)
+            return undefined;
+        const path = site.callee.split('.');
+        const root = path[0];
+        const rest = path.slice(1);
+        const canonical = [];
+        let globalRoot = false;
+        if (site.receiver !== undefined) {
+            // Member chain with an identifier root — origin known by binding index.
+            const rb = bindings[site.receiver];
+            if (rb.synthetic === true) {
+                const imp = imports.get(rb.name);
+                if (imp !== undefined) {
+                    const base = imp.member === undefined ? [imp.module] : [imp.module, imp.member];
+                    canonical.push([...base, ...rest].join('.'));
+                }
+            }
+            else {
+                const module = requireByBinding.get(site.receiver);
+                if (module !== undefined)
+                    canonical.push([module, ...rest].join('.'));
+            }
+        }
+        else if (path.length === 1) {
+            // Bare call. `this`/`super`/call-rooted chains never get here (those
+            // are dotted-without-receiver or callee-less).
+            const locals = nonSyntheticByName.get(root);
+            if (locals !== undefined) {
+                // Shadowed by an in-function declaration — only the require join
+                // applies, under the dual interpretation (module doc).
+                for (const idx of locals) {
+                    const module = requireByBinding.get(idx);
+                    if (module !== undefined)
+                        canonical.push(`${module}.default`, `${module}.${root}`);
+                }
+            }
+            else {
+                const imp = imports.get(root);
+                if (imp !== undefined) {
+                    canonical.push(imp.member === undefined ? `${imp.module}.default` : `${imp.module}.${imp.member}`);
+                }
+                else {
+                    globalRoot = true;
+                }
+            }
+        }
+        return { path, canonical, globalRoot };
+    };
+    /** The spread/template/registered-position rule (see MatchedSinkCall doc). */
+    const positionMatches = (entry, site, p) => {
+        if (site.template === true)
+            return true;
+        if (entry.args === undefined)
+            return true;
+        if (site.spread !== undefined && p >= site.spread) {
+            const spread = site.spread;
+            return entry.args.some((q) => q >= spread);
+        }
+        return entry.args.includes(p);
+    };
+    const sinkMechanismHit = (entry, site, r) => {
+        if (entry.module !== undefined)
+            return r.canonical.includes(`${entry.module}.${entry.name}`);
+        if (entry.global === true) {
+            return (r.globalRoot &&
+                r.path.length === 1 &&
+                r.path[0] === entry.name &&
+                (entry.newOnly !== true || site.kind === 'new'));
+        }
+        if (entry.anyReceiver === true) {
+            return r.path.length >= 2 && r.path[r.path.length - 1] === entry.name;
+        }
+        if (entry.receivers !== undefined) {
+            return r.path.length === 2 && entry.receivers.includes(r.path[0]) && r.path[1] === entry.name;
+        }
+        return false;
+    };
+    // Sanitizers: module + global mechanisms ONLY — never receiver-conventional,
+    // never bare-name for non-globals (a false kill is the forbidden direction).
+    const sanitizerMechanismHit = (entry, r) => {
+        if (entry.module !== undefined)
+            return r.canonical.includes(`${entry.module}.${entry.name}`);
+        if (entry.global === true) {
+            return r.globalRoot && r.path.length === 1 && r.path[0] === entry.name;
+        }
+        return false;
+    };
+    const statements = [];
+    let hasSource = false;
+    let hasSink = false;
+    cfg.blocks.forEach((block, blockIndex) => {
+        block.statements?.forEach((stmt, statementIndex) => {
+            const sites = stmt.sites;
+            if (sites === undefined || sites.length === 0)
+                return;
+            const sources = [];
+            const sinks = [];
+            const sanitizers = [];
+            sites.forEach((site, siteIndex) => {
+                if (site.kind === 'member-read') {
+                    if (site.object === undefined || site.property === undefined)
+                        return;
+                    const objectName = bindings[site.object].name;
+                    const property = site.property;
+                    for (const entry of spec.sources) {
+                        if (entry.objects.includes(objectName) && entry.properties.includes(property)) {
+                            sources.push({ siteIndex, entry });
+                        }
+                    }
+                    return;
+                }
+                // call / new
+                const resolved = resolveCallee(site);
+                if (resolved === undefined)
+                    return;
+                for (const entry of spec.sinks) {
+                    if (!sinkMechanismHit(entry, site, resolved))
+                        continue;
+                    const argPositions = [];
+                    site.args?.forEach((occurrences, p) => {
+                        if (occurrences.length > 0 && positionMatches(entry, site, p))
+                            argPositions.push(p);
+                    });
+                    if (argPositions.length > 0)
+                        sinks.push({ siteIndex, entry, argPositions });
+                }
+                for (const entry of spec.sanitizers) {
+                    if (!sanitizerMechanismHit(entry, resolved))
+                        continue;
+                    sanitizers.push({ siteIndex, entry, resultDefs: site.resultDefs ?? [] });
+                }
+            });
+            if (sources.length === 0 && sinks.length === 0 && sanitizers.length === 0)
+                return;
+            hasSource ||= sources.length > 0;
+            hasSink ||= sinks.length > 0;
+            statements.push({ blockIndex, statementIndex, line: stmt.line, sources, sinks, sanitizers });
+        });
+    });
+    return { statements, hasSource, hasSink };
+}

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 };
+}