@dailephd/my-dev-kit-lab 0.6.0 → 0.6.2

package/dist/src/evaluation/affectedNeighborhood.js

@@ -0,0 +1,712 @@
+import path from "node:path";
+import { resolveWithinRoot } from "../core/pathSafety.js";
+import { compareCodeUnits, interpretIndexManifest, readJson } from "./indexSnapshot.js";
+export const AFFECTED_NEIGHBORHOOD_GRAPH_EVIDENCE_SCHEMA_VERSION = "my-dev-kit-lab-affected-neighborhood-graph-evidence-v1";
+export const AFFECTED_NEIGHBORHOOD_SEED_MAPPING_SCHEMA_VERSION = "my-dev-kit-lab-affected-neighborhood-seed-mapping-v1";
+const MANIFEST_FILE = "manifest.json";
+const SUPPORTED_SYMBOL_INDEX_SCHEMA_VERSION = "2";
+const SUPPORTED_CODE_GRAPH_ARTIFACT_KIND = "code-graph";
+const SUPPORTED_CODE_GRAPH_VERSION_PATTERN = /^1\./;
+// Same bounds as the v0.6.0 freshness/snapshot evidence lists.
+const MAX_WARNINGS = 50;
+const MAX_UNRESOLVED = 50;
+const MAX_REPORTED_TEXT_LENGTH = 260;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function boundedText(value) {
+    return value.length > MAX_REPORTED_TEXT_LENGTH ? `${value.slice(0, MAX_REPORTED_TEXT_LENGTH)}...` : value;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, "/");
+}
+/** The upstream stable file-node identity. */
+export function fileNodeId(filePath) {
+    return `file:${filePath}`;
+}
+/** The upstream stable symbol-node identity: file path + symbol name. */
+export function symbolNodeId(filePath, symbolName) {
+    return `symbol:${filePath}#${symbolName}`;
+}
+function emptyEvidence(indexRoot) {
+    return {
+        schemaVersion: AFFECTED_NEIGHBORHOOD_GRAPH_EVIDENCE_SCHEMA_VERSION,
+        status: "unavailable",
+        unavailable: null,
+        indexRoot,
+        manifest: null,
+        symbolIndex: null,
+        codeGraph: null,
+        indexedFilePaths: [],
+        symbolFiles: new Map(),
+        nodes: new Map(),
+        edges: [],
+        duplicateEdgeRecordCount: 0,
+        warningCount: 0,
+        warnings: [],
+        warningsTruncated: false,
+    };
+}
+function unavailableEvidence(indexRoot, code, message, manifest = null) {
+    return { ...emptyEvidence(indexRoot), unavailable: { code, message: boundedText(message) }, manifest };
+}
+function sortWarnings(warnings) {
+    return [...warnings].sort((left, right) => compareCodeUnits(left.code, right.code) || compareCodeUnits(left.subject ?? "", right.subject ?? "") || compareCodeUnits(left.message, right.message));
+}
+/**
+ * Policy: reads indexed-file membership and baseline symbols from a symbol-index artifact. Only
+ * schema version 2 is understood. A file entry whose symbol list is malformed keeps its
+ * membership but yields no symbol record; a malformed symbol entry is dropped with a warning.
+ * Pure.
+ */
+export function interpretSymbolIndexForNeighborhood(symbolIndex) {
+    if (!isRecord(symbolIndex)) {
+        return { ok: false, message: "Symbol index is not a JSON object." };
+    }
+    if (symbolIndex.schemaVersion !== SUPPORTED_SYMBOL_INDEX_SCHEMA_VERSION) {
+        return { ok: false, message: `Symbol index schemaVersion is not the supported ${SUPPORTED_SYMBOL_INDEX_SCHEMA_VERSION}.` };
+    }
+    if (!Array.isArray(symbolIndex.files)) {
+        return { ok: false, message: "Symbol index does not list indexed files." };
+    }
+    const warnings = [];
+    const records = new Map();
+    const paths = new Set();
+    for (const entry of symbolIndex.files) {
+        if (!isRecord(entry) || !nonEmptyString(entry.path)) {
+            return { ok: false, message: "Symbol index contains a file entry without a path." };
+        }
+        const filePath = normalizePath(entry.path);
+        if (paths.has(filePath)) {
+            return { ok: false, message: "Symbol index lists the same file path more than once." };
+        }
+        paths.add(filePath);
+        if (!Array.isArray(entry.symbols)) {
+            warnings.push({
+                code: "invalid-symbol-file-entry",
+                subject: boundedText(filePath),
+                message: "Symbol index file entry has no symbol list; no baseline symbols are recorded for it.",
+            });
+            continue;
+        }
+        const seen = new Set();
+        const duplicates = new Set();
+        for (const symbol of entry.symbols) {
+            if (!isRecord(symbol) || !nonEmptyString(symbol.name)) {
+                warnings.push({ code: "invalid-symbol-entry", subject: boundedText(filePath), message: "Symbol index entry lacks a symbol name and was ignored." });
+                continue;
+            }
+            if (seen.has(symbol.name)) {
+                duplicates.add(symbol.name);
+            }
+            seen.add(symbol.name);
+        }
+        records.set(filePath, {
+            symbolNames: [...seen].sort(compareCodeUnits),
+            duplicateSymbolNames: [...duplicates].sort(compareCodeUnits),
+        });
+    }
+    const indexedFilePaths = [...paths].sort(compareCodeUnits);
+    const symbolFiles = new Map();
+    for (const key of [...records.keys()].sort(compareCodeUnits)) {
+        symbolFiles.set(key, records.get(key));
+    }
+    return { ok: true, value: { indexedFilePaths, symbolFiles, warnings } };
+}
+/**
+ * Policy: validates the structure of a code-graph artifact and preserves its nodes and edges by
+ * their actual IDs and kinds. Edge kinds are not filtered. Structurally invalid entries are dropped
+ * with a warning; identical repeated edge records collapse silently into a count. Pure.
+ */
+export function interpretCodeGraphForNeighborhood(codeGraph) {
+    if (!isRecord(codeGraph)) {
+        return { ok: false, message: "Code graph is not a JSON object." };
+    }
+    if (codeGraph.artifactKind !== SUPPORTED_CODE_GRAPH_ARTIFACT_KIND) {
+        return { ok: false, message: `Code graph artifactKind is not ${SUPPORTED_CODE_GRAPH_ARTIFACT_KIND}.` };
+    }
+    if (typeof codeGraph.schemaVersion !== "string" || !SUPPORTED_CODE_GRAPH_VERSION_PATTERN.test(codeGraph.schemaVersion)) {
+        return { ok: false, message: "Code graph schemaVersion is missing or not a supported 1.x version." };
+    }
+    if (!Array.isArray(codeGraph.nodes) || !Array.isArray(codeGraph.edges)) {
+        return { ok: false, message: "Code graph does not list nodes and edges." };
+    }
+    const warnings = [];
+    const unsorted = new Map();
+    for (const entry of codeGraph.nodes) {
+        if (!isRecord(entry) || !nonEmptyString(entry.id) || !nonEmptyString(entry.kind)) {
+            warnings.push({ code: "invalid-node-entry", subject: null, message: "Code graph node lacks an id or kind and was ignored." });
+            continue;
+        }
+        const node = {
+            id: entry.id,
+            kind: entry.kind,
+            path: typeof entry.path === "string" ? entry.path : null,
+            label: typeof entry.label === "string" ? entry.label : null,
+        };
+        const existing = unsorted.get(node.id);
+        if (existing) {
+            if (existing.kind !== node.kind || existing.path !== node.path) {
+                warnings.push({ code: "duplicate-node-id", subject: boundedText(node.id), message: "Code graph repeats a node ID with different content; the first record was kept." });
+            }
+            continue;
+        }
+        unsorted.set(node.id, node);
+    }
+    const nodes = new Map();
+    for (const key of [...unsorted.keys()].sort(compareCodeUnits)) {
+        nodes.set(key, unsorted.get(key));
+    }
+    const edgesById = new Map();
+    let duplicateEdgeRecordCount = 0;
+    for (const entry of codeGraph.edges) {
+        if (!isRecord(entry) || !nonEmptyString(entry.id) || !nonEmptyString(entry.source) || !nonEmptyString(entry.target) || !nonEmptyString(entry.kind)) {
+            warnings.push({ code: "invalid-edge-entry", subject: null, message: "Code graph edge lacks an id, source, target, or kind and was ignored." });
+            continue;
+        }
+        const edge = { id: entry.id, source: entry.source, target: entry.target, kind: entry.kind };
+        const existing = edgesById.get(edge.id);
+        if (existing) {
+            if (existing.source === edge.source && existing.target === edge.target && existing.kind === edge.kind) {
+                duplicateEdgeRecordCount += 1;
+            }
+            else {
+                warnings.push({ code: "conflicting-duplicate-edge-id", subject: boundedText(edge.id), message: "Code graph repeats an edge ID with different content; the first record was kept." });
+            }
+            continue;
+        }
+        if (!nodes.has(edge.source) || !nodes.has(edge.target)) {
+            warnings.push({ code: "dangling-edge", subject: boundedText(edge.id), message: "Code graph edge references a node that is not in the graph and was ignored." });
+            continue;
+        }
+        edgesById.set(edge.id, edge);
+    }
+    const edges = [...edgesById.values()].sort((left, right) => compareCodeUnits(left.id, right.id));
+    return {
+        ok: true,
+        value: { artifactKind: codeGraph.artifactKind, schemaVersion: codeGraph.schemaVersion, nodes, edges, duplicateEdgeRecordCount, warnings },
+    };
+}
+/**
+ * Loads the baseline graph evidence of one prepared index once. Reads only manifest-referenced
+ * artifacts inside `indexDir`; never enumerates the index, reads `cache-metadata.json`, walks
+ * source roots, runs my-dev-kit, or throws. `indexSnapshot` is the session's already captured v0.6.0
+ * snapshot, which proves the manifest was accepted for this target; an unavailable snapshot yields
+ * unavailable evidence rather than a re-derived one.
+ */
+export async function loadAffectedNeighborhoodGraphEvidence(options) {
+    const { indexDir, sourceRoots, indexSnapshot } = options;
+    const indexRoot = path.resolve(indexDir);
+    try {
+        if (indexSnapshot.status === "unavailable" || !indexSnapshot.manifest) {
+            return unavailableEvidence(indexRoot, "index-snapshot-unavailable", indexSnapshot.unavailable?.message ?? "The index snapshot is unavailable, so the index contract was not accepted.");
+        }
+        const manifestRead = await readJson(path.join(indexDir, MANIFEST_FILE));
+        if (!manifestRead.ok) {
+            return unavailableEvidence(indexRoot, manifestRead.missing ? "manifest-missing" : "manifest-unreadable", `Index manifest ${manifestRead.message}.`);
+        }
+        const manifest = interpretIndexManifest(manifestRead.value, { sourceRoots });
+        if (!manifest.ok) {
+            return unavailableEvidence(indexRoot, "manifest-unsupported", manifest.message);
+        }
+        const manifestSummary = {
+            path: MANIFEST_FILE,
+            artifactKind: manifest.contract.manifestArtifactKind,
+            schemaVersion: manifest.contract.manifestVersion,
+        };
+        let symbolIndexFile;
+        try {
+            symbolIndexFile = resolveWithinRoot(indexDir, manifest.contract.symbolIndexRelativePath);
+        }
+        catch {
+            return unavailableEvidence(indexRoot, "artifact-path-escapes-index", "Index manifest symbolIndex path escapes the index directory.", manifestSummary);
+        }
+        const symbolIndexRead = await readJson(symbolIndexFile);
+        if (!symbolIndexRead.ok) {
+            return unavailableEvidence(indexRoot, symbolIndexRead.missing ? "symbol-index-missing" : "symbol-index-unreadable", `Symbol index ${symbolIndexRead.message}.`, manifestSummary);
+        }
+        const symbols = interpretSymbolIndexForNeighborhood(symbolIndexRead.value);
+        if (!symbols.ok) {
+            return unavailableEvidence(indexRoot, "symbol-index-unsupported", symbols.message, manifestSummary);
+        }
+        const symbolIndexSummary = {
+            path: normalizePath(path.relative(path.resolve(indexDir), symbolIndexFile)),
+            schemaVersion: SUPPORTED_SYMBOL_INDEX_SCHEMA_VERSION,
+        };
+        const warnings = [...symbols.value.warnings];
+        let codeGraphSummary = null;
+        let graph = null;
+        const rawCodeGraph = isRecord(manifestRead.value) && isRecord(manifestRead.value.artifacts) ? manifestRead.value.artifacts.codeGraph : undefined;
+        if (!nonEmptyString(rawCodeGraph)) {
+            warnings.push({ code: "code-graph-not-referenced", subject: null, message: "Index manifest does not name a codeGraph artifact." });
+        }
+        else {
+            let codeGraphFile = null;
+            try {
+                codeGraphFile = resolveWithinRoot(indexDir, rawCodeGraph);
+            }
+            catch {
+                warnings.push({ code: "code-graph-path-escapes-index", subject: null, message: "Index manifest codeGraph path escapes the index directory." });
+            }
+            if (codeGraphFile !== null) {
+                const codeGraphRead = await readJson(codeGraphFile);
+                if (!codeGraphRead.ok) {
+                    warnings.push({
+                        code: codeGraphRead.missing ? "code-graph-missing" : "code-graph-unreadable",
+                        subject: null,
+                        message: boundedText(`Code graph ${codeGraphRead.message}.`),
+                    });
+                }
+                else {
+                    const interpreted = interpretCodeGraphForNeighborhood(codeGraphRead.value);
+                    if (!interpreted.ok) {
+                        warnings.push({ code: "code-graph-unsupported", subject: null, message: boundedText(interpreted.message) });
+                    }
+                    else {
+                        graph = interpreted.value;
+                        warnings.push(...graph.warnings);
+                        codeGraphSummary = {
+                            path: normalizePath(path.relative(path.resolve(indexDir), codeGraphFile)),
+                            artifactKind: graph.artifactKind,
+                            schemaVersion: graph.schemaVersion,
+                        };
+                    }
+                }
+            }
+        }
+        const sorted = sortWarnings(warnings);
+        return {
+            schemaVersion: AFFECTED_NEIGHBORHOOD_GRAPH_EVIDENCE_SCHEMA_VERSION,
+            status: sorted.length === 0 ? "complete" : "partial",
+            unavailable: null,
+            indexRoot,
+            manifest: manifestSummary,
+            symbolIndex: symbolIndexSummary,
+            codeGraph: codeGraphSummary,
+            indexedFilePaths: symbols.value.indexedFilePaths,
+            symbolFiles: symbols.value.symbolFiles,
+            nodes: graph?.nodes ?? new Map(),
+            edges: graph?.edges ?? [],
+            duplicateEdgeRecordCount: graph?.duplicateEdgeRecordCount ?? 0,
+            warningCount: sorted.length,
+            warnings: sorted.slice(0, MAX_WARNINGS),
+            warningsTruncated: sorted.length > MAX_WARNINGS,
+        };
+    }
+    catch (error) {
+        return unavailableEvidence(indexRoot, "graph-evidence-load-failed", `Affected-neighborhood graph evidence load failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function lookupNode(evidence, expectedNodeId, kind) {
+    const node = evidence.nodes.get(expectedNodeId);
+    if (!node)
+        return { ok: false, expectedNodeId, reason: "graph-node-missing" };
+    return node.kind === kind ? { ok: true, nodeId: node.id } : { ok: false, expectedNodeId, reason: "graph-node-kind-mismatch" };
+}
+/** Exact file-path lookup of the baseline file node. Never falls back to another path. */
+export function lookupFileNode(evidence, filePath) {
+    return lookupNode(evidence, fileNodeId(filePath), "file");
+}
+/** Same-file symbol lookup. Never searches for a same-named symbol in another file. */
+export function lookupSymbolNode(evidence, filePath, symbolName) {
+    return lookupNode(evidence, symbolNodeId(filePath, symbolName), "symbol");
+}
+/**
+ * Maps confirmed changed indexed files, and the baseline symbols belonging to them, onto baseline
+ * graph nodes. Pure and deterministic: consumes only the v0.6.0 snapshot and freshness assessment
+ * plus the prepared index's graph evidence; never touches the filesystem, current source, or
+ * my-dev-kit, and never falls back to fuzzy or cross-file matching.
+ */
+export function mapAffectedNeighborhoodSeeds(input) {
+    const { indexSnapshot, freshness, graph } = input;
+    const warnings = [];
+    const unresolved = [];
+    const warn = (code, message, warnPath = null) => {
+        warnings.push({ code, path: warnPath === null ? null : boundedText(warnPath), message });
+    };
+    const snapshotPaths = new Set(indexSnapshot.files.map((file) => normalizePath(file.path)));
+    const changesByPath = new Map();
+    for (const change of freshness.changes) {
+        const changePath = normalizePath(change.path);
+        if (!snapshotPaths.has(changePath)) {
+            unresolved.push({ subject: "changed-file", path: boundedText(changePath), name: null, reason: "not-in-index-snapshot" });
+            continue;
+        }
+        // Duplicate change records collapse deterministically: a missing file outranks a modified one.
+        const existing = changesByPath.get(changePath);
+        if (existing === undefined || (existing === "modified" && change.changeType === "missing")) {
+            changesByPath.set(changePath, change.changeType);
+        }
+    }
+    const changedPaths = [...changesByPath.keys()].sort(compareCodeUnits);
+    const totalConfirmed = freshness.changedFileCount + freshness.missingFileCount;
+    const changesTruncated = freshness.changesTruncated;
+    const freshnessGivesBasis = freshness.status !== "unknown" || changedPaths.length > 0;
+    const changedFileCount = !freshnessGivesBasis ? null : changesTruncated ? Math.max(totalConfirmed, changedPaths.length) : changedPaths.length;
+    const codeGraphLoaded = graph.codeGraph !== null && graph.status !== "unavailable";
+    const symbolIndexAvailable = graph.status !== "unavailable";
+    if (freshness.status === "unknown")
+        warn("freshness-unknown", "Freshness is unknown; no changed-file basis exists.");
+    if (freshness.status === "partially-stale")
+        warn("freshness-partially-stale", "Freshness comparison is incomplete; confirmed changes are preserved but the mapping stays partial.");
+    if (changesTruncated)
+        warn("freshness-changes-truncated", `Freshness listed ${changedPaths.length} of ${totalConfirmed} confirmed changes; the remainder is not mapped.`);
+    if (graph.status === "unavailable")
+        warn("graph-evidence-unavailable", graph.unavailable?.message ?? "Graph evidence is unavailable.");
+    else if (graph.status === "partial")
+        warn("graph-evidence-incomplete", `Graph evidence is partial (${graph.warningCount} warning(s)).`);
+    if (symbolIndexAvailable && !codeGraphLoaded)
+        warn("code-graph-not-loaded", "The code graph could not be loaded, so no node mapping is possible.");
+    const changedFiles = [];
+    const changedSymbols = [];
+    const seeds = new Set();
+    let mappedFileCount = 0;
+    let mappedSymbolCount = 0;
+    let symbolIdentityCount = 0;
+    for (const filePath of changedPaths) {
+        const changeType = changesByPath.get(filePath);
+        const expectedNodeId = fileNodeId(filePath);
+        let resolvedNodeId = null;
+        let reason = null;
+        if (!codeGraphLoaded) {
+            reason = "graph-unavailable";
+        }
+        else {
+            const lookup = lookupFileNode(graph, filePath);
+            if (lookup.ok)
+                resolvedNodeId = lookup.nodeId;
+            else
+                reason = lookup.reason;
+        }
+        if (resolvedNodeId !== null) {
+            mappedFileCount += 1;
+            seeds.add(resolvedNodeId);
+        }
+        else {
+            unresolved.push({ subject: "changed-file", path: boundedText(filePath), name: null, reason: reason });
+        }
+        changedFiles.push({
+            path: filePath,
+            changeType,
+            expectedNodeId,
+            resolvedNodeId,
+            status: resolvedNodeId === null ? "unresolved" : "mapped",
+            unresolvedReason: reason,
+        });
+        if (!symbolIndexAvailable)
+            continue;
+        const record = graph.symbolFiles.get(filePath);
+        if (!record) {
+            unresolved.push({ subject: "symbol-index-record", path: boundedText(filePath), name: null, reason: "symbol-index-record-missing" });
+            continue;
+        }
+        if (record.duplicateSymbolNames.length > 0) {
+            warn("duplicate-symbol-records", `Baseline symbol index lists ${record.duplicateSymbolNames.length} symbol name(s) more than once; each counts as one identity.`, filePath);
+        }
+        for (const name of record.symbolNames) {
+            symbolIdentityCount += 1;
+            const symbolExpectedId = symbolNodeId(filePath, name);
+            let symbolResolvedId = null;
+            let symbolReason = null;
+            if (!codeGraphLoaded) {
+                symbolReason = "graph-unavailable";
+            }
+            else {
+                const lookup = lookupSymbolNode(graph, filePath, name);
+                if (lookup.ok)
+                    symbolResolvedId = lookup.nodeId;
+                else
+                    symbolReason = lookup.reason;
+            }
+            if (symbolResolvedId !== null) {
+                mappedSymbolCount += 1;
+                seeds.add(symbolResolvedId);
+            }
+            else {
+                unresolved.push({ subject: "changed-symbol", path: boundedText(filePath), name: boundedText(name), reason: symbolReason });
+            }
+            changedSymbols.push({
+                path: filePath,
+                name,
+                expectedNodeId: symbolExpectedId,
+                resolvedNodeId: symbolResolvedId,
+                status: symbolResolvedId === null ? "unresolved" : "mapped",
+                unresolvedReason: symbolReason,
+            });
+        }
+    }
+    const symbolCountEstablished = symbolIndexAvailable && freshnessGivesBasis;
+    const changedSymbolCount = symbolCountEstablished ? symbolIdentityCount : null;
+    if (unresolved.length > 0)
+        warn("mapping-unresolved", `${unresolved.length} changed-file or changed-symbol mapping(s) could not be resolved.`);
+    unresolved.sort((left, right) => compareCodeUnits(left.path, right.path) ||
+        compareCodeUnits(left.name ?? "", right.name ?? "") ||
+        compareCodeUnits(left.subject, right.subject) ||
+        compareCodeUnits(left.reason, right.reason));
+    warnings.sort((left, right) => compareCodeUnits(left.code, right.code) || compareCodeUnits(left.path ?? "", right.path ?? "") || compareCodeUnits(left.message, right.message));
+    let status;
+    if (!freshnessGivesBasis || !codeGraphLoaded) {
+        status = "unavailable";
+    }
+    else if ((freshness.status === "fresh" || freshness.status === "stale") &&
+        graph.status === "complete" &&
+        !changesTruncated &&
+        unresolved.length === 0) {
+        status = "complete";
+    }
+    else {
+        status = "partial";
+    }
+    const seedNodeIds = [...seeds].sort(compareCodeUnits);
+    return {
+        schemaVersion: AFFECTED_NEIGHBORHOOD_SEED_MAPPING_SCHEMA_VERSION,
+        status,
+        freshnessStatus: freshness.status,
+        graphEvidenceStatus: graph.status,
+        changedFileCount,
+        changedSymbolCount,
+        mappedChangedFileNodeCount: mappedFileCount,
+        mappedChangedSymbolNodeCount: mappedSymbolCount,
+        seedNodeCount: seedNodeIds.length,
+        changesTruncated,
+        changedFiles,
+        changedSymbols,
+        seedNodeIds,
+        unresolvedCount: unresolved.length,
+        unresolved: unresolved.slice(0, MAX_UNRESOLVED),
+        unresolvedTruncated: unresolved.length > MAX_UNRESOLVED,
+        warningCount: warnings.length,
+        warnings: warnings.slice(0, MAX_WARNINGS),
+        warningsTruncated: warnings.length > MAX_WARNINGS,
+    };
+}
+export const AFFECTED_NEIGHBORHOOD_ASSESSMENT_SCHEMA_VERSION = "my-dev-kit-lab-affected-neighborhood-assessment-v1";
+function uniqueSorted(values) {
+    return [...new Set(values)].sort(compareCodeUnits);
+}
+function normalizeExpectedPath(value) {
+    return normalizePath(value).replace(/^(\.\/)+/, "");
+}
+/**
+ * Policy: maps a task's expected files and symbols to baseline graph nodes. Files resolve only to
+ * their exact `file:` node. A symbol resolves only within the task's own expected files and only
+ * when exactly one same-name node exists there; zero matches is unresolved and several is
+ * ambiguous (no winner is picked, no node is added). Never searches the rest of the graph. Pure.
+ */
+export function mapAffectedNeighborhoodTask(input) {
+    const { graph } = input;
+    const unresolved = [];
+    const ambiguous = [];
+    const empty = () => ({
+        status: "unavailable",
+        expectedFiles: [],
+        expectedSymbols: [],
+        resolvedFiles: [],
+        resolvedSymbols: [],
+        unresolvedCount: 0,
+        unresolved: [],
+        unresolvedTruncated: false,
+        ambiguousCount: 0,
+        ambiguousSymbols: [],
+        ambiguousTruncated: false,
+        duplicateEntryCount: 0,
+        resolvedTaskNodeIds: [],
+        resolvableTaskNodeCount: 0,
+    });
+    if (!Array.isArray(input.expectedFiles) || !Array.isArray(input.expectedSymbols)) {
+        return empty();
+    }
+    let duplicateEntryCount = 0;
+    const collect = (entries, subject) => {
+        const seen = new Set();
+        for (const entry of entries) {
+            const value = typeof entry === "string" ? (subject === "expected-file" ? normalizeExpectedPath(entry) : entry) : "";
+            if (value.length === 0) {
+                unresolved.push({ subject, name: typeof entry === "string" ? "" : boundedText(String(entry)), reason: "invalid-entry" });
+                continue;
+            }
+            if (seen.has(value))
+                duplicateEntryCount += 1;
+            seen.add(value);
+        }
+        return [...seen].sort(compareCodeUnits);
+    };
+    const expectedFiles = collect(input.expectedFiles, "expected-file");
+    const expectedSymbols = collect(input.expectedSymbols, "expected-symbol");
+    const graphUsable = graph.status !== "unavailable" && graph.codeGraph !== null;
+    if (!graphUsable || (expectedFiles.length === 0 && expectedSymbols.length === 0)) {
+        // No truthful mapping exists, but invalid metadata entries stay visible as diagnostics.
+        unresolved.sort((left, right) => compareCodeUnits(left.subject, right.subject) || compareCodeUnits(left.name, right.name));
+        return {
+            ...empty(),
+            expectedFiles,
+            expectedSymbols,
+            duplicateEntryCount,
+            unresolvedCount: unresolved.length,
+            unresolved: unresolved.slice(0, MAX_UNRESOLVED),
+            unresolvedTruncated: unresolved.length > MAX_UNRESOLVED,
+        };
+    }
+    const resolvedFiles = [];
+    for (const filePath of expectedFiles) {
+        const lookup = lookupFileNode(graph, filePath);
+        if (lookup.ok)
+            resolvedFiles.push({ path: filePath, nodeId: lookup.nodeId });
+        else
+            unresolved.push({ subject: "expected-file", name: boundedText(filePath), reason: lookup.reason });
+    }
+    const resolvedSymbols = [];
+    for (const name of expectedSymbols) {
+        // Scope is the task's expected files, whether or not their own file node resolved.
+        const candidates = uniqueSorted(expectedFiles.flatMap((filePath) => {
+            const lookup = lookupSymbolNode(graph, filePath, name);
+            return lookup.ok ? [lookup.nodeId] : [];
+        }));
+        if (candidates.length === 1) {
+            resolvedSymbols.push({ name, nodeId: candidates[0] });
+        }
+        else if (candidates.length === 0) {
+            unresolved.push({ subject: "expected-symbol", name: boundedText(name), reason: "graph-node-missing" });
+        }
+        else {
+            ambiguous.push({ name: boundedText(name), candidateNodeIds: candidates });
+        }
+    }
+    const resolvedTaskNodeIds = uniqueSorted([...resolvedFiles.map((entry) => entry.nodeId), ...resolvedSymbols.map((entry) => entry.nodeId)]);
+    unresolved.sort((left, right) => compareCodeUnits(left.subject, right.subject) || compareCodeUnits(left.name, right.name) || compareCodeUnits(left.reason, right.reason));
+    ambiguous.sort((left, right) => compareCodeUnits(left.name, right.name));
+    const status = resolvedTaskNodeIds.length === 0
+        ? "unavailable"
+        : graph.status === "complete" && unresolved.length === 0 && ambiguous.length === 0
+            ? "complete"
+            : "partial";
+    return {
+        status,
+        expectedFiles,
+        expectedSymbols,
+        resolvedFiles,
+        resolvedSymbols,
+        unresolvedCount: unresolved.length,
+        unresolved: unresolved.slice(0, MAX_UNRESOLVED),
+        unresolvedTruncated: unresolved.length > MAX_UNRESOLVED,
+        ambiguousCount: ambiguous.length,
+        ambiguousSymbols: ambiguous.slice(0, MAX_UNRESOLVED),
+        ambiguousTruncated: ambiguous.length > MAX_UNRESOLVED,
+        duplicateEntryCount,
+        resolvedTaskNodeIds,
+        resolvableTaskNodeCount: resolvedTaskNodeIds.length,
+    };
+}
+/**
+ * Policy: exactly one graph hop, bidirectional, over every retained structurally valid edge
+ * regardless of kind. Affected nodes are the resolved seeds plus the opposite endpoint of every
+ * edge incident to a seed. Affected edges are only those incident to a seed: an edge between two
+ * non-seed neighbors is not part of the frontier. A single scan of the sorted edge list, O(E); the
+ * graph evidence is not mutated.
+ */
+export function traverseAffectedNeighborhood(graph, seedNodeIds) {
+    const seeds = new Set(seedNodeIds.filter((id) => graph.nodes.has(id)));
+    const affected = new Set(seeds);
+    const edgeIds = new Set();
+    for (const edge of graph.edges) {
+        if (!seeds.has(edge.source) && !seeds.has(edge.target))
+            continue;
+        edgeIds.add(edge.id);
+        affected.add(edge.source);
+        affected.add(edge.target);
+    }
+    return { affectedNodeIds: [...affected].sort(compareCodeUnits), participatingEdgeIds: [...edgeIds].sort(compareCodeUnits) };
+}
+/**
+ * Assesses one task against the affected neighborhood of the confirmed changed seeds. Pure and
+ * deterministic; uses only the baseline graph evidence, the Batch 1 seed mapping, and the task's
+ * expected metadata. It never reads files, runs my-dev-kit, or classifies from task locality labels.
+ *
+ * Evidence rules: positive overlap is `related` (and `recommended`) even under partial evidence;
+ * zero overlap is `unrelated` (and `not-indicated`) only when seed mapping, neighborhood, and task
+ * mapping are all complete. Zero overlap under any incomplete evidence is `unknown`, never
+ * `unrelated`. "Not indicated" means only that this experiment's bounded evidence does not point
+ * to reindexing for this task.
+ */
+export function assessAffectedNeighborhood(input) {
+    const { graph, seedMapping, task } = input;
+    const warnings = [];
+    const warn = (code, message) => {
+        warnings.push({ code, message });
+    };
+    const graphUsable = graph.status !== "unavailable" && graph.codeGraph !== null;
+    const neighborhoodUsable = graphUsable && seedMapping.status !== "unavailable";
+    let neighborhoodStatus = "unavailable";
+    let affectedNodeIds = [];
+    let participatingEdgeIds = [];
+    if (neighborhoodUsable) {
+        ({ affectedNodeIds, participatingEdgeIds } = traverseAffectedNeighborhood(graph, seedMapping.seedNodeIds));
+        neighborhoodStatus = seedMapping.status === "complete" && graph.status === "complete" ? "complete" : "partial";
+    }
+    const taskMapping = mapAffectedNeighborhoodTask({ graph, expectedFiles: task.expectedFiles, expectedSymbols: task.expectedSymbols });
+    const overlapEvaluable = neighborhoodStatus !== "unavailable" && taskMapping.status !== "unavailable";
+    let taskOverlapNodeIds = [];
+    let taskOverlapCount = null;
+    let taskOverlapPercent = null;
+    if (overlapEvaluable) {
+        const affected = new Set(affectedNodeIds);
+        taskOverlapNodeIds = taskMapping.resolvedTaskNodeIds.filter((id) => affected.has(id));
+        taskOverlapCount = taskOverlapNodeIds.length;
+        taskOverlapPercent = taskMapping.resolvableTaskNodeCount > 0 ? (taskOverlapCount / taskMapping.resolvableTaskNodeCount) * 100 : null;
+    }
+    const allComplete = seedMapping.status === "complete" && neighborhoodStatus === "complete" && taskMapping.status === "complete";
+    let relationship;
+    if (taskOverlapCount !== null && taskOverlapCount > 0) {
+        relationship = "related";
+    }
+    else if (taskOverlapCount === 0 && allComplete) {
+        relationship = "unrelated";
+    }
+    else {
+        relationship = "unknown";
+    }
+    const reindexRecommendation = relationship === "related" ? "recommended" : relationship === "unrelated" ? "not-indicated" : "unknown";
+    if (seedMapping.status === "unavailable")
+        warn("seed-mapping-unavailable", "Seed mapping is unavailable; no neighborhood was established.");
+    else if (seedMapping.status === "partial")
+        warn("seed-mapping-partial", "Seed mapping is partial; only resolved seeds were traversed.");
+    if (!graphUsable)
+        warn("graph-evidence-unavailable", "Baseline graph evidence is not usable for traversal.");
+    else if (graph.status === "partial")
+        warn("graph-evidence-partial", "Baseline graph evidence is partial; only validated nodes and edges were used.");
+    if (taskMapping.status === "unavailable")
+        warn("task-mapping-unavailable", "No task node could be resolved from the expected files and symbols.");
+    else if (taskMapping.status === "partial")
+        warn("task-mapping-partial", "Some expected files or symbols are unresolved or ambiguous; overlap covers resolvable task nodes only.");
+    if (relationship === "unknown" && taskOverlapCount === 0) {
+        warn("zero-overlap-under-incomplete-evidence", "No overlap was observed, but incomplete evidence cannot prove the task unrelated.");
+    }
+    warnings.sort((left, right) => compareCodeUnits(left.code, right.code));
+    return {
+        schemaVersion: AFFECTED_NEIGHBORHOOD_ASSESSMENT_SCHEMA_VERSION,
+        status: allComplete ? "complete" : overlapEvaluable ? "partial" : "unavailable",
+        freshnessStatus: seedMapping.freshnessStatus,
+        seedMappingStatus: seedMapping.status,
+        graphEvidenceStatus: graph.status,
+        neighborhoodStatus,
+        changedFileCount: seedMapping.changedFileCount,
+        changedSymbolCount: seedMapping.changedSymbolCount,
+        seedNodeCount: seedMapping.seedNodeCount,
+        affectedNodeCount: neighborhoodUsable ? affectedNodeIds.length : null,
+        affectedEdgeCount: neighborhoodUsable ? participatingEdgeIds.length : null,
+        affectedNodeIds,
+        participatingEdgeIds,
+        taskMapping,
+        taskOverlapCount,
+        taskOverlapNodeIds,
+        taskOverlapPercent,
+        relationship,
+        reindexRecommendation,
+        warningCount: warnings.length,
+        warnings: warnings.slice(0, MAX_WARNINGS),
+        warningsTruncated: warnings.length > MAX_WARNINGS,
+    };
+}