@davesheffer/hunch 1.38.1 → 1.39.1

package/dist/extractors/git.js

@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import { MEMLOG_FORMAT } from "../core/memorylog.js";
 import { hunchAttributesAreSafe, hunchTreeAttributesAreSafe, safeOverlayTree } from "../core/overlaySafety.js";
 import { createRepoFileReader } from "../core/safeRepoFile.js";
+import { DIFF_TRUNCATED_LINE } from "./diff.js";
 import { initiatorChildEnv } from "../synthesis/initiator.js";
 // `git` exports these repository-local variables to hooks. They outrank cwd/-C,
 // so carrying them from the code repository into a command for the memory
@@ -71,6 +72,26 @@ function gitSafe(args, cwd, maxBuffer) {
         return "";
     }
 }
+/** Untrimmed stdout with the same child environment as git(); null on ANY failure
+ *  (non-zero exit, spawn error, output over maxBuffer). For callers that must tell
+ *  "git produced nothing" apart from "git could not answer". */
+function gitOutputOrNull(args, cwd, maxBuffer = 64 * 1024 * 1024) {
+    try {
+        return execFileSync("git", args, {
+            cwd, encoding: "utf8", maxBuffer,
+            env: initiatorChildEnv(),
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/** Split `-z` path output. NUL-delimited paths are never C-quoted, so a path
+ *  holding `"`, `\`, a tab or a newline enumerates as its literal spelling. */
+function nulPaths(out) {
+    return out ? out.split("\0").filter(Boolean) : [];
+}
 /** Object-identity reads must not inherit clone-local replacement refs/grafts.
  * Most Git helpers intentionally preserve ordinary repository behavior; use
  * this narrower path only where a cross-clone canonical identity is minted. */
@@ -1808,6 +1829,14 @@ export function gitUntrackCached(cwd, paths) {
     }
     catch { /* best-effort: not a repo / nothing tracked */ }
 }
+/** Tracked files under the given pathspecs (repo-relative, POSIX). Best-effort:
+ *  `[]` when not a repository or nothing is tracked there. */
+export function gitTrackedPaths(cwd, paths) {
+    if (paths.length === 0)
+        return [];
+    const out = gitSafe(["-c", "core.quotePath=false", "ls-files", "--", ...paths], cwd);
+    return out ? out.split("\n").filter(Boolean) : [];
+}
 /** Resolve any commit-ish (short sha / HEAD / branch) to a canonical full sha.
  *  Returns the input unchanged if it can't be resolved (e.g. not a git repo). */
 export function revParse(ref, cwd) {
@@ -1851,8 +1880,7 @@ export function currentBranch(cwd) {
 /** Files changed in a single commit. `--root` makes the initial commit (which
  *  has no parent) report its files as additions instead of returning nothing. */
 export function commitFiles(sha, cwd) {
-    const out = gitSafe(["-c", "core.quotePath=false", "diff-tree", "--no-commit-id", "--name-only", "-r", "--root", sha], cwd);
-    return out ? out.split("\n").filter(Boolean) : [];
+    return nulPaths(gitOutputOrNull(["-c", "core.quotePath=false", "diff-tree", "--no-commit-id", "--name-only", "-z", "-r", "--root", sha], cwd));
 }
 /** Raw `git log` over `.hunch/`, paired with parseMemoryLog — the memory-move
  *  timeline (each commit that changed the graph). Newest first; empty on any error
@@ -2302,12 +2330,55 @@ const DIFF_NOISE = [
     ":(exclude,glob)**/__snapshots__/**",
     ":(exclude,glob)**/*.generated.*",
 ];
-/** The unified diff for a commit, truncated to keep synthesis prompts bounded.
+/** Byte budget for a diff embedded in a SYNTHESIS prompt. Gates never use it: a
+ *  constraint check over a prefix of a change would read every file past the
+ *  cutoff as "no added lines" and pass it. */
+export const SYNTHESIS_DIFF_BUDGET = 60_000;
+function capDiff(out, maxBytes) {
+    return out.length > maxBytes ? out.slice(0, maxBytes) + `\n${DIFF_TRUNCATED_LINE}` : out;
+}
+/** Output ceiling for a gating diff. Past it git's output cannot be captured; the
+ *  diff is then reported incomplete and the gate fails closed (dec_20db57c576). */
+const GATE_DIFF_MAX_BUFFER = 256 * 1024 * 1024;
+/** Pinned so user/repo config cannot change what the diff parser sees: literal
+ *  UTF-8 paths (issue #50) and a/ b/ prefixes regardless of diff.noprefix or
+ *  diff.mnemonicPrefix. */
+const GATE_DIFF_FLAGS = ["--no-ext-diff", "--no-textconv", "--no-color", "--unified=2", "--src-prefix=a/", "--dst-prefix=b/"];
+function gateDiff(args, cwd, what) {
+    const out = gitOutputOrNull(["-c", "core.quotePath=false", ...args], cwd, GATE_DIFF_MAX_BUFFER);
+    return out === null
+        ? { diff: "", incomplete: `git could not produce the ${what} diff (git error, or output over ${GATE_DIFF_MAX_BUFFER / (1024 * 1024)} MB)` }
+        : { diff: out };
+}
+/** C-quote a path the way git does when it holds `"`, `\`, or a control character,
+ *  so a synthetic diff header round-trips through analyzeDiff's unquoting. */
+function quoteDiffPath(path) {
+    if (!/["\\\x00-\x1f\x7f]/.test(path))
+        return path;
+    const named = { '"': '\\"', "\\": "\\\\", "\t": "\\t", "\n": "\\n", "\r": "\\r" };
+    let out = "";
+    for (const ch of path) {
+        const code = ch.charCodeAt(0);
+        if (named[ch])
+            out += named[ch];
+        else if (code < 0x20 || code === 0x7f)
+            out += "\\" + code.toString(8).padStart(3, "0");
+        else
+            out += ch;
+    }
+    return `"${out}"`;
+}
+/** Complete gating diff of one commit (see GateDiff). */
+export function commitGateDiff(sha, cwd) {
+    return gateDiff(["show", sha, "--format=", ...GATE_DIFF_FLAGS], cwd, `commit ${sha}`);
+}
+/** The unified diff for a commit, truncated to keep SYNTHESIS prompts bounded.
  *  Machine-generated noise (see DIFF_NOISE) is excluded so the model spends its
- *  budget on code that encodes intent, not on regenerated lockfiles/build output. */
-export function commitDiff(sha, cwd, maxBytes = 60_000) {
-    const out = gitSafe(["show", sha, "--no-color", "--format=", "--unified=2", "--", ...DIFF_NOISE], cwd);
-    return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
+ *  budget on code that encodes intent, not on regenerated lockfiles/build output.
+ *  Not for gating: use commitGateDiff. */
+export function commitDiff(sha, cwd, maxBytes = SYNTHESIS_DIFF_BUDGET) {
+    const out = gitSafe(["-c", "core.quotePath=false", "show", sha, "--no-color", "--format=", "--unified=2", "--", ...DIFF_NOISE], cwd);
+    return capDiff(out, maxBytes);
 }
 /** Number of commits touching a file in the last `days` (churn). */
 export function fileChurn(file, cwd, days = 90) {
@@ -2438,15 +2509,14 @@ export function fileGitMetrics(cwd, want, days = 90) {
  *  POSIX paths nor constraint scope globs — a blocking constraint over such a
  *  file graded as a vacuous PASS, and its churn/last-commit metrics read zero. */
 export function stagedFiles(cwd) {
-    const out = gitSafe(["-c", "core.quotePath=false", "diff", "--cached", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd);
-    return out ? out.split("\n").filter(Boolean) : [];
+    return nulPaths(gitOutputOrNull(["-c", "core.quotePath=false", "diff", "--cached", "--no-ext-diff", "--no-textconv", "--name-only", "-z", "--diff-filter=ACMR"], cwd));
 }
 /** Files changed anywhere in the working tree compared with HEAD: both staged
  * and unstaged tracked files, plus untracked files. This powers the local,
  * pre-commit Change Gate; it never mutates the index or asks an agent/model. */
 export function workingFiles(cwd) {
-    const changed = gitSafe(["-c", "core.quotePath=false", "diff", "HEAD", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean);
-    const untracked = gitSafe(["-c", "core.quotePath=false", "ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter(Boolean);
+    const changed = nulPaths(gitOutputOrNull(["-c", "core.quotePath=false", "diff", "HEAD", "--no-ext-diff", "--no-textconv", "--name-only", "-z", "--diff-filter=ACMR"], cwd));
+    const untracked = nulPaths(gitOutputOrNull(["-c", "core.quotePath=false", "ls-files", "-z", "--others", "--exclude-standard"], cwd));
     return [...new Set([...changed, ...untracked])].sort();
 }
 /** Does a ref resolve to a commit in this repo? Lets `--base` fail LOUDLY on an
@@ -2458,8 +2528,7 @@ export function revExists(ref, cwd) {
 /** Files a PR/branch changes vs `base` (3-dot: changes on HEAD since the merge-base,
  *  i.e. exactly the PR's own commits — the CI Constraint Guard's surface). */
 export function rangeFiles(base, cwd, head = "HEAD") {
-    const out = gitSafe(["-c", "core.quotePath=false", "diff", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR", `${base}...${head}`], cwd);
-    return out ? out.split("\n").filter(Boolean) : [];
+    return nulPaths(gitOutputOrNull(["-c", "core.quotePath=false", "diff", "--no-ext-diff", "--no-textconv", "--name-only", "-z", "--diff-filter=ACMR", `${base}...${head}`], cwd));
 }
 /** Commit subjects on `head` since `base` (2-dot: commits added by the task),
  *  oldest-first, for distilling a runbook's ordered steps (roadmap #5). */
@@ -2467,43 +2536,78 @@ export function rangeSubjects(base, cwd, head = "HEAD", max = 50) {
     const out = gitSafe(["log", "--reverse", `-n${max}`, "--format=%s", `${base}..${head}`], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
-/** The PR's unified diff vs `base` (3-dot), for the Regression Guard's structural
- *  analysis. Same noise-exclusion + truncation budget as commit/staged diffs. */
-export function rangeDiff(base, cwd, head = "HEAD", maxBytes = 60_000) {
-    const out = gitSafe(["diff", "--no-ext-diff", "--no-textconv", "--no-color", "--unified=2", `${base}...${head}`, "--", ...DIFF_NOISE], cwd);
-    return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
+/** Complete gating diff of a PR vs `base` (3-dot: the CI Constraint Guard's surface). */
+export function rangeGateDiff(base, cwd, head = "HEAD") {
+    return gateDiff(["diff", ...GATE_DIFF_FLAGS, `${base}...${head}`], cwd, `${base}...${head}`);
+}
+/** The PR's unified diff vs `base` (3-dot), noise-excluded and capped at the
+ *  synthesis budget. Bounded-prompt use only; gates use rangeGateDiff. */
+export function rangeDiff(base, cwd, head = "HEAD", maxBytes = SYNTHESIS_DIFF_BUDGET) {
+    const out = gitSafe(["-c", "core.quotePath=false", "diff", "--no-ext-diff", "--no-textconv", "--no-color", "--unified=2", `${base}...${head}`, "--", ...DIFF_NOISE], cwd);
+    return capDiff(out, maxBytes);
 }
-/** Unified diff of the staged changes (for the Regression Guard's structural
- *  analysis). Excludes machine-generated noise and truncates at the SAME budget as
- *  commitDiff, so the staged and `--commit` guard paths can't diverge on big diffs. */
-export function stagedDiff(cwd, maxBytes = 60_000) {
-    const out = gitSafe(["diff", "--cached", "--no-ext-diff", "--no-textconv", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
-    return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
+/** Complete gating diff of the staged changes (pre-commit `hunch check`). */
+export function stagedGateDiff(cwd) {
+    return gateDiff(["diff", "--cached", ...GATE_DIFF_FLAGS], cwd, "staged");
 }
-/** Unified diff of the complete local working tree vs HEAD. Git's normal diff
+/** Unified diff of the staged changes, noise-excluded and capped at the synthesis
+ *  budget. Bounded-prompt use only; gates use stagedGateDiff. */
+export function stagedDiff(cwd, maxBytes = SYNTHESIS_DIFF_BUDGET) {
+    const out = gitSafe(["-c", "core.quotePath=false", "diff", "--cached", "--no-ext-diff", "--no-textconv", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
+    return capDiff(out, maxBytes);
+}
+/** Complete gating diff of the local working tree vs HEAD. Git's normal diff
  * includes both staged and unstaged tracked edits; untracked text files are
- * appended as synthetic additions so guards can also see their added symbols.
- * Binary/unreadable files remain in workingFiles (scope checks still apply) but
- * intentionally contribute no synthetic content to regression analysis. */
-export function workingDiff(cwd, maxBytes = 60_000) {
-    let out = gitSafe(["diff", "HEAD", "--no-ext-diff", "--no-textconv", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
-    const tracked = new Set(gitSafe(["-c", "core.quotePath=false", "diff", "HEAD", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean));
-    const untracked = gitSafe(["-c", "core.quotePath=false", "ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter((f) => f && !tracked.has(f));
+ * appended as synthetic additions so guards can also see their added lines.
+ * Binary files and non-regular paths (symlinks) contribute no content, as in a
+ * git diff; an untracked regular file that cannot be read is listed in
+ * `unreadFiles`, so content checks over it fail closed. */
+export function workingGateDiff(cwd) {
+    // An unborn HEAD has no tracked diff (workingFiles enumerates only untracked
+    // files there); any other failure to diff makes the gate input incomplete.
+    const hasHead = revExists("HEAD", cwd);
+    const tracked = hasHead ? gateDiff(["diff", "HEAD", ...GATE_DIFF_FLAGS], cwd, "working-tree") : { diff: "" };
+    const trackedNames = hasHead
+        ? gitOutputOrNull(["-c", "core.quotePath=false", "diff", "HEAD", "--no-ext-diff", "--no-textconv", "--name-only", "-z", "--diff-filter=ACMR"], cwd)
+        : "";
+    const untrackedNames = gitOutputOrNull(["-c", "core.quotePath=false", "ls-files", "-z", "--others", "--exclude-standard"], cwd);
+    const incomplete = tracked.incomplete
+        ?? (trackedNames === null || untrackedNames === null ? "git could not enumerate the working-tree changes" : undefined);
+    const trackedSet = new Set(nulPaths(trackedNames));
+    const untracked = nulPaths(untrackedNames).filter((f) => !trackedSet.has(f));
     const readWorkingFile = createRepoFileReader(cwd);
+    const unreadFiles = [];
+    let out = tracked.diff;
     for (const file of untracked) {
+        let regular = false;
         try {
-            const text = readWorkingFile(file);
-            if (text === null)
-                continue;
-            if (text.includes("\0"))
-                continue;
-            const lines = text.split("\n");
-            const add = lines.map((line) => `+${line}`).join("\n");
-            out += `${out ? "\n" : ""}diff --git a/${file} b/${file}\nnew file mode 100644\n--- /dev/null\n+++ b/${file}\n@@ -0,0 +1,${lines.length} @@\n${add}\n`;
+            regular = lstatSync(join(cwd, file)).isFile();
         }
-        catch { /* unreadable / directory / binary: scope-only is still safe */ }
-    }
-    return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
+        catch { /* vanished: nothing to inspect */ }
+        if (!regular)
+            continue; // symlink / directory / gone: no file content to add
+        const text = readWorkingFile(file);
+        if (text === null) {
+            unreadFiles.push(file);
+            continue;
+        }
+        if (text.includes("\0"))
+            continue; // binary: git shows no text hunks for it either
+        const lines = text.split("\n");
+        const add = lines.map((line) => `+${line}`).join("\n");
+        const newPath = quoteDiffPath(`b/${file}`);
+        out += `${out && !out.endsWith("\n") ? "\n" : ""}diff --git ${quoteDiffPath(`a/${file}`)} ${newPath}\nnew file mode 100644\n--- /dev/null\n+++ ${newPath}\n@@ -0,0 +1,${lines.length} @@\n${add}\n`;
+    }
+    return {
+        diff: out,
+        ...(incomplete ? { incomplete } : {}),
+        ...(unreadFiles.length ? { unreadFiles } : {}),
+    };
+}
+/** Working-tree diff vs HEAD capped at the synthesis budget. Bounded-prompt use
+ *  only; gates and rule verification use workingGateDiff. */
+export function workingDiff(cwd, maxBytes = SYNTHESIS_DIFF_BUDGET) {
+    return capDiff(workingGateDiff(cwd).diff, maxBytes);
 }
 /** Resolve a time-travel ref (commit / tag / branch / HEAD~n) to the ISO author-
  *  date of that commit — the instant valid-time windows are filtered against.

package/dist/extractors/helm.d.ts

@@ -1,31 +1,20 @@
-/**
- * Deterministic text scan for Helm's `define`/`include`/`template` Go-template
- * actions — NOT a Go-template parser, and NOT a tree-sitter query. tree-sitter-yaml
- * has no notion of `{{ }}` content: parsing `{{ include "x" . }}` inside a real
- * YAML mapping value produces only stray `{` flow-mapping-open tokens, with the
- * enclosed text lost to ERROR recovery (verified directly against this repo's
- * tree-sitter-yaml bundle). There is nothing for a tree-sitter query to capture,
- * so this runs as a sidecar text scan over the raw source — invoked only for
- * files under a Helm chart (indexer.ts's chart-root detection), never for
- * arbitrary YAML.
- *
- * Known bounded limitation: this is a token scan, not a full parser. A literal
- * `}}` inside a quoted argument, or an include/define-shaped string inside a
- * `{{/* comment *}}`, can misattribute a byte range or produce a phantom call.
- * Both are bounded failure modes (a stray reference to a real symbol name, or a
- * slightly-long symbol range) — the same class of accepted limitation
- * `toleratedErrorScopes` documents for the tree-sitter grammars, not a silent gap.
- * The chart-wide `importedFiles` widening this module's output flows through
- * (indexer.ts) also lets a YAML alias resolve to an anchor in a sibling chart
- * file, even though YAML anchors are properly document-scoped; this only fires
- * when the alias has no matching anchor in its own file (i.e. only on input
- * that's already invalid YAML on its own terms), so it's bounded, but it's a
- * real, disclosed side effect of the chart-scoping mechanism, not something to
- * silently rely on.
- */
-import { type ParsedSymbol, type ParsedCall } from "./parse.js";
+import type { ParsedSymbolKind } from "./languages.js";
+export interface HelmSymbol {
+    name: string;
+    kind: ParsedSymbolKind;
+    startChar: number;
+    endChar: number;
+    loc: number;
+    bodyText: string;
+}
+export interface HelmCall {
+    callee: string;
+    atChar: number;
+    endChar: number;
+    member: boolean;
+}
 export interface HelmExtraction {
-    symbols: ParsedSymbol[];
-    calls: ParsedCall[];
+    symbols: HelmSymbol[];
+    calls: HelmCall[];
 }
 export declare function extractHelmDirectives(source: string): HelmExtraction;

package/dist/extractors/helm.js

@@ -11,7 +11,7 @@
  *
  * Known bounded limitation: this is a token scan, not a full parser. A literal
  * `}}` inside a quoted argument, or an include/define-shaped string inside a
- * `{{/* comment *}}`, can misattribute a byte range or produce a phantom call.
+ * `{{/* comment *}}`, can misattribute a char range or produce a phantom call.
  * Both are bounded failure modes (a stray reference to a real symbol name, or a
  * slightly-long symbol range) — the same class of accepted limitation
  * `toleratedErrorScopes` documents for the tree-sitter grammars, not a silent gap.
@@ -39,20 +39,20 @@ export function extractHelmDirectives(source) {
     const stack = [];
     for (const m of source.matchAll(ACTION)) {
         const raw = m[1];
-        // "{{" is 2 chars; a trim-marker "{{-" is 3 — this is the byte offset of
-        // `raw`'s first character within `source`, needed for call-site atByte math.
+        // "{{" is 2 chars; a trim-marker "{{-" is 3 — this is the char offset of
+        // `raw`'s first character within `source`, needed for call-site atChar math.
         const innerStart = m.index + (source[m.index + 2] === "-" ? 3 : 2);
-        const endByte = m.index + m[0].length;
+        const endChar = m.index + m[0].length;
         const body = raw.trim();
         const spaceIdx = body.search(/\s/);
         const keyword = spaceIdx === -1 ? body : body.slice(0, spaceIdx);
         if (keyword === "define") {
             const name = NAME_ARG.exec(body.slice(spaceIdx + 1).trim())?.[1];
-            stack.push({ name, startByte: m.index });
+            stack.push({ name, startChar: m.index });
         }
         else if (BLOCK_OPEN.has(keyword)) {
             // if/range/with/block: depth marker only, no symbol on its own.
-            stack.push({ startByte: m.index });
+            stack.push({ startChar: m.index });
         }
         else if (keyword === "end") {
             const open = stack.pop();
@@ -60,16 +60,16 @@ export function extractHelmDirectives(source) {
                 symbols.push({
                     name: open.name,
                     kind: "variable",
-                    startByte: open.startByte,
-                    endByte,
-                    loc: source.slice(open.startByte, endByte).split("\n").length,
-                    bodyText: source.slice(open.startByte, endByte).slice(0, MAX_BODY_TEXT_CHARS),
+                    startChar: open.startChar,
+                    endChar,
+                    loc: source.slice(open.startChar, endChar).split("\n").length,
+                    bodyText: source.slice(open.startChar, endChar).slice(0, MAX_BODY_TEXT_CHARS),
                 });
             }
         }
         for (const call of raw.matchAll(CALL_SITE)) {
-            const atByte = innerStart + call.index;
-            calls.push({ callee: call[1], atByte, endByte: atByte + call[0].length, member: false });
+            const atChar = innerStart + call.index;
+            calls.push({ callee: call[1], atChar, endChar: atChar + call[0].length, member: false });
         }
     }
     return { symbols, calls };

package/dist/extractors/indexer.js

@@ -10,8 +10,9 @@
  */
 import { readFileSync } from "node:fs";
 import { dirname, join, posix } from "node:path";
-import { parseSource, attributeCalls, attributeRelations } from "./parse.js";
+import { parseSource, attributeCalls, attributeRelations, MAX_BODY_TEXT_CHARS } from "./parse.js";
 import { extractHelmDirectives } from "./helm.js";
+import { extractK8sManifest } from "./k8sManifest.js";
 import { symbolId, componentId, edgeId, sha1 } from "../core/ids.js";
 import { externalImportNodeId, externalPackage } from "../core/externalImports.js";
 import { resolveRelativeImport } from "../core/relativeImports.js";
@@ -100,6 +101,10 @@ export function scanRepo(store, root, opts = {}) {
     const perFileCalls = [];
     const perFileImports = [];
     const perFileRelations = [];
+    const k8sResourceIndex = [];
+    const k8sReferenceCandidates = [];
+    const k8sSelectors = [];
+    const k8sWorkloadLabels = [];
     const phpNamespaces = new Map();
     const phpUseDeclarations = new Map();
     // Batched per-file git metrics (churn + last commit) in TWO `git log` spawns
@@ -113,7 +118,7 @@ export function scanRepo(store, root, opts = {}) {
         const chartRoot = chartRootFor(path);
         if (chartRoot === null)
             continue;
-        (chartFiles.get(chartRoot) ?? chartFiles.set(chartRoot, []).get(chartRoot)).push(path);
+        pushInto(chartFiles, chartRoot, path);
     }
     const gitMeta = useGit ? fileGitMetrics(root, rels, opts.churn === false ? 0 : 90) : null;
     let skipped = 0;
@@ -165,8 +170,50 @@ export function scanRepo(store, root, opts = {}) {
         // JS-falsy — `if (chartRoot)` would silently skip every repo-root chart.
         if (chartRoot !== null) {
             const helm = extractHelmDirectives(src);
-            parsed.symbols = [...parsed.symbols, ...helm.symbols].sort((a, b) => a.startByte - b.startByte);
-            parsed.calls = [...parsed.calls, ...helm.calls];
+            // helm.ts's own offsets are named *Char (they're JS char indices, not
+            // UTF-8 bytes -- see its module doc comment); mapped here into
+            // parsed.symbols/calls's startByte/endByte/atByte fields, which carry
+            // the same char-index values under the shared ParsedSymbol/ParsedCall
+            // naming this merge target already uses.
+            const helmSymbols = helm.symbols.map((s) => ({
+                name: s.name, kind: s.kind, startByte: s.startChar, endByte: s.endChar, loc: s.loc, bodyText: s.bodyText,
+            }));
+            const helmCalls = helm.calls.map((c) => ({
+                callee: c.callee, atByte: c.atChar, endByte: c.endChar, member: c.member,
+            }));
+            parsed.symbols = [...parsed.symbols, ...helmSymbols].sort((a, b) => a.startByte - b.startByte);
+            parsed.calls = [...parsed.calls, ...helmCalls];
+        }
+        // Runs for EVERY yaml file, chart or not (unlike the Helm merge above) --
+        // raw manifests with no Chart.yaml are still in scope; what varies below is
+        // resolution SCOPE (chartRoot ?? this file), not whether extraction runs.
+        let k8sDocs = [];
+        // THIS file's K8s resource symbol OBJECTS (identity, not their byte
+        // offsets) -- scopes the id lookup below to exactly the symbols this pass
+        // creates. Identity, not a Set<number> of startBytes, because a byte
+        // value is not a reliable per-symbol key: a Helm `define` symbol that
+        // happens to share a startByte with a K8s doc symbol in the same .yaml
+        // file (both legitimately synthetic, both can start at byte 0) would
+        // otherwise be indistinguishable by offset alone, and the wrong (Helm)
+        // symbol id could get recorded instead of the K8s one.
+        const k8sSymbolObjects = new Set();
+        if (languageFor(rel)?.id === "yaml") {
+            k8sDocs = extractK8sManifest(src);
+            const k8sSymbols = k8sDocs
+                .filter((d) => d.resource !== null)
+                // k8sManifest.ts's own offsets are named *Char; mapped here into the
+                // shared startByte/endByte fields, same as the Helm merge above.
+                .map((d) => ({
+                name: `${d.resource.kind}/${displayNameText(d.resource.name)}`,
+                kind: "variable",
+                startByte: d.resource.startChar,
+                endByte: d.resource.endChar,
+                loc: src.slice(d.resource.startChar, d.resource.endChar).split("\n").length,
+                bodyText: src.slice(d.resource.startChar, d.resource.endChar).slice(0, MAX_BODY_TEXT_CHARS),
+            }));
+            for (const s of k8sSymbols)
+                k8sSymbolObjects.add(s);
+            parsed.symbols = [...parsed.symbols, ...k8sSymbols].sort((a, b) => a.startByte - b.startByte);
         }
         const m = gitMeta?.get(rel);
         const churn = opts.churn === false ? (preservedChurn.get(rel) ?? 0) : (m?.churn ?? 0);
@@ -174,6 +221,7 @@ export function scanRepo(store, root, opts = {}) {
         const idsInFile = [];
         const symbolIndexId = new Map();
         const idCounts = new Map(); // disambiguate same (file,name,kind)
+        const k8sSymbolIdByStartByte = new Map();
         for (const [index, ps] of parsed.symbols.entries()) {
             const base = symbolId(rel, ps.name, ps.kind);
             const n = idCounts.get(base) ?? 0;
@@ -182,7 +230,7 @@ export function scanRepo(store, root, opts = {}) {
             const id = n === 0 ? base : `${base}_${n}`;
             idsInFile.push(id);
             symbolIndexId.set(index, id);
-            (nameIndex.get(ps.name) ?? nameIndex.set(ps.name, []).get(ps.name)).push(id);
+            pushInto(nameIndex, ps.name, id);
             symbols.push({
                 id, file: rel, name: ps.name, kind: ps.kind,
                 signature_hash: sha1(ps.bodyText).slice(0, 16),
@@ -190,6 +238,27 @@ export function scanRepo(store, root, opts = {}) {
                 metrics: { loc: ps.loc, churn_90d: churn, bug_count: 0, fan_in: 0, fan_out: 0 },
                 last_changed: last,
             });
+            if (k8sSymbolObjects.has(ps))
+                k8sSymbolIdByStartByte.set(ps.startByte, id);
+        }
+        for (const doc of k8sDocs) {
+            if (!doc.resource)
+                continue;
+            const fromId = k8sSymbolIdByStartByte.get(doc.resource.startChar);
+            if (!fromId)
+                continue;
+            const scope = chartRoot ?? rel;
+            k8sResourceIndex.push({ symbolId: fromId, scope, kind: doc.resource.kind, nameKey: nameKeyText(doc.resource.name) });
+            for (const ref of doc.references) {
+                k8sReferenceCandidates.push({
+                    fromSymbolId: fromId, scope, refKind: ref.refKind, nameKey: nameKeyText(ref.name),
+                    reason: `${doc.resource.kind}/${displayNameText(doc.resource.name)} references ${ref.refKind}/${displayNameText(ref.name)}`,
+                });
+            }
+            if (doc.selector)
+                k8sSelectors.push({ symbolId: fromId, scope, selector: doc.selector });
+            if (doc.labels)
+                k8sWorkloadLabels.push({ symbolId: fromId, scope, labels: doc.labels });
         }
         fileSymbols.set(rel, idsInFile);
         fileSymbolIndexId.set(rel, symbolIndexId);
@@ -285,6 +354,77 @@ export function scanRepo(store, root, opts = {}) {
             }
         }
     }
+    // ---- K8s manifest cross-resource references (Phase 1: name-keyed) --------
+    // Own resolver, not resolveName(): resolveName() indexes by bare symbol name
+    // only, with no concept of Kubernetes kind -- a ConfigMap and a Secret that
+    // happen to share a name would incorrectly conflate. Same ambiguity contract
+    // as resolveName() though: 0 matches or 2+ matches -> no edge, never guess.
+    const kindNameIndex = new Map();
+    for (const r of k8sResourceIndex) {
+        const key = `${r.scope}:${r.kind}:${r.nameKey}`;
+        pushInto(kindNameIndex, key, r.symbolId);
+    }
+    for (const ref of k8sReferenceCandidates) {
+        const candidates = kindNameIndex.get(`${ref.scope}:${ref.refKind}:${ref.nameKey}`) ?? [];
+        if (candidates.length !== 1)
+            continue; // 0 or 2+ -> ambiguous or absent, don't guess
+        const toId = candidates[0];
+        if (toId === ref.fromSymbolId)
+            continue;
+        addEdge({
+            schema: "hunch.edge/1",
+            id: edgeId(ref.fromSymbolId, toId, "references"),
+            from: ref.fromSymbolId, to: toId, type: "references",
+            reason: ref.reason, strength: 0.7,
+            provenance: extracted(0.7, [ref.scope]),
+            environment: null,
+            metadata: {},
+        });
+    }
+    // ---- K8s manifest cross-resource references (Phase 2: label-selector) ----
+    // Structurally different from Phase 1: no name to look up, a SUBSET match
+    // between a Service's selector and a workload's pod-template labels, within
+    // the same scope. Only ever fires on LITERAL selector/labels (k8sSelectors/
+    // k8sWorkloadLabels are already filtered to literal-only by k8sManifest.ts --
+    // a block-form templated value is never guessed at).
+    //
+    // Deliberately NO ambiguity guard here, unlike Phase 1's "0 or 2+ candidates
+    // -> no edge": a Service legitimately fronting multiple workloads (blue/green,
+    // canary, a shared-label pair of Deployments) is normal, intentional
+    // Kubernetes usage, not an ambiguous match to decline -- Phase 1's guard
+    // exists because a ConfigMap named X is exactly one resource by definition,
+    // which has no analogue here. Fan-out is the correct behavior, not a gap.
+    const selectorsByScope = new Map();
+    for (const s of k8sSelectors)
+        pushInto(selectorsByScope, s.scope, s);
+    const labelsByScope = new Map();
+    for (const l of k8sWorkloadLabels)
+        pushInto(labelsByScope, l.scope, l);
+    for (const [scope, selectors] of selectorsByScope) {
+        const workloads = labelsByScope.get(scope) ?? [];
+        for (const svc of selectors) {
+            for (const wl of workloads) {
+                // Defensive, not currently reachable: k8sSelectors only ever holds
+                // Service symbols and k8sWorkloadLabels only ever holds symbols for
+                // kinds in LABELS_PATH_BY_KIND, which excludes Service -- so the two
+                // ids can never collide today.
+                if (svc.symbolId === wl.symbolId)
+                    continue;
+                const isSubset = Object.entries(svc.selector).every(([k, v]) => wl.labels[k] === v);
+                if (!isSubset)
+                    continue;
+                addEdge({
+                    schema: "hunch.edge/1",
+                    id: edgeId(svc.symbolId, wl.symbolId, "references"),
+                    from: svc.symbolId, to: wl.symbolId, type: "references",
+                    reason: "Service selector matches workload pod-template labels", strength: 0.6,
+                    provenance: extracted(0.6, [scope]),
+                    environment: null,
+                    metadata: {},
+                });
+            }
+        }
+    }
     // PHP's static type relationships use the same symbol graph and conservative
     // resolver as calls. Ambiguous or dynamic targets produce no edge.
     for (const { file, bySym } of perFileRelations) {
@@ -441,6 +581,16 @@ export function indexRepo(store, root, opts = {}) {
     return scan.result;
 }
 // ---- helpers --------------------------------------------------------------
+/** Append `value` to the array at `key`, creating the array on first use.
+ *  Function declaration (not `const`) so it's usable from pass-1 code above
+ *  this section via hoisting, without reordering. */
+function pushInto(map, key, value) {
+    const bucket = map.get(key);
+    if (bucket)
+        bucket.push(value);
+    else
+        map.set(key, [value]);
+}
 /** Nearest-ancestor Chart.yaml lookup, memoized per directory: walks a file's
  *  own directory upward through the tracked-file set until it finds
  *  `<dir>/Chart.yaml`, or returns null if the file isn't under any chart.
@@ -449,8 +599,9 @@ export function indexRepo(store, root, opts = {}) {
  *  approximation, not full Helm semantics: Helm's template namespace is
  *  actually release-global, so a parent chart can legitimately include a
  *  subchart's define — nearest-ancestor scoping will miss that edge rather
- *  than fabricate a wrong one. No test currently covers the nested
- *  charts/<sub>/Chart.yaml case — tracked as issue #42. */
+ *  than fabricate a wrong one (test coverage: indexer.test.ts's nested-subchart
+ *  and subchart-miss cases). Modeling the release-global namespace itself
+ *  remains open — issue #42. */
 function nearestChartRoot(rels) {
     const tracked = new Set(rels);
     const cache = new Map();
@@ -466,6 +617,19 @@ function nearestChartRoot(rels) {
     };
     return (file) => resolveDir(file.includes("/") ? file.slice(0, file.lastIndexOf("/")) : "");
 }
+/** Human-readable text for a name/kind field -- a literal value as-is, or a
+ *  template's exact raw `{{ }}` source text (never evaluated). Used for
+ *  display (symbol names, edge reasons); NOT for resolution-key equality --
+ *  see nameKeyText below for that. */
+function displayNameText(ref) {
+    return ref.form === "literal" ? ref.value : ref.sourceText;
+}
+/** Normalized resolution-key text for a name/kind field: a literal value or a
+ *  template's exact raw source text, EACH PREFIXED so a literal "foo" can
+ *  never collide with a template whose source text happens to read "foo". */
+function nameKeyText(ref) {
+    return ref.form === "literal" ? `L:${ref.value}` : `T:${ref.sourceText}`;
+}
 /** Resolve a callee name to a symbol id: prefer same-file, otherwise require a
  * unique symbol in a statically imported local file. A unique repository-wide
  * name is not evidence of a binding: callback parameters and built-ins often