@llm4ts/flow 2.36.0 → 2.38.0

package/dist/Survey.js

@@ -1,29 +1,247 @@
+import { createHash } from "node:crypto";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
+import { PlanParseError } from "./FlowError.js";
+import { edgeRuleOfSurvey, emptyGraphRules, matchUrl, normalizeUrl } from "./GraphRules.js";
+export const GraphOrigin = Schema.Literals(["scanner", "llm", "external"]);
+export const GraphConfidence = Schema.Literals(["exact", "inferred"]);
+export const GraphMechanism = Schema.Literals([
+    "capture",
+    "join:exact",
+    "join:url",
+    "contraction",
+    "llm",
+    "codegraph"
+]);
+export const JoinMatch = Schema.Literals(["exact", "prefix", "extension"]);
+export class GraphEvidence extends Schema.Class("GraphEvidence")({
+    file: Schema.String,
+    line: Schema.Int,
+    snippet: Schema.String
+}) {
+}
+/**
+ * A node of the estate graph. The four original fields describe a FILE node;
+ * the ADR 0030 fields are optional on the wire so a pre-0030 `graph.json`
+ * decodes and the four-field constructor keeps compiling — read them through
+ * `nodeId`, `nodeKind` and the other helpers below, never directly.
+ */
 export class SurveyNode extends Schema.Class("SurveyNode")({
     path: Schema.String,
     name: Schema.String,
     lines: Schema.Int,
-    units: Schema.Int
+    units: Schema.Int,
+    id: Schema.optionalKey(Schema.String),
+    kind: Schema.optionalKey(Schema.String),
+    label: Schema.optionalKey(Schema.String),
+    lineStart: Schema.optionalKey(Schema.Int),
+    lineEnd: Schema.optionalKey(Schema.Int),
+    attrs: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+    origin: Schema.optionalKey(GraphOrigin),
+    /** A wiring record (a `web.xml` mapping), not a unit: contracted by the file projection. */
+    descriptor: Schema.optionalKey(Schema.Boolean),
+    /** The attr naming the unit this node stands for (a declaration's class). */
+    anchor: Schema.optionalKey(Schema.String)
 }) {
 }
 export class SurveyEdge extends Schema.Class("SurveyEdge")({
     from: Schema.String,
     to: Schema.String,
-    kind: Schema.String
+    kind: Schema.String,
+    origin: Schema.optionalKey(GraphOrigin),
+    confidence: Schema.optionalKey(GraphConfidence),
+    /** The pack section that produced the edge. */
+    rule: Schema.optionalKey(Schema.String),
+    mechanism: Schema.optionalKey(GraphMechanism),
+    join: Schema.optionalKey(JoinMatch),
+    evidence: Schema.optionalKey(GraphEvidence)
+}) {
+}
+export const UnresolvedReason = Schema.Literals([
+    "edge-target",
+    "missing-attr",
+    "join-from",
+    "join-to",
+    "isolated"
+]);
+export class Unresolved extends Schema.Class("Unresolved")({
+    reason: UnresolvedReason,
+    rule: Schema.String,
+    node: Schema.String,
+    reference: Schema.optionalKey(Schema.String),
+    file: Schema.String,
+    line: Schema.Int
+}) {
+}
+/** An attr the LLM pass filled on an existing node, with the line that justifies it. */
+export class Fill extends Schema.Class("Fill")({
+    node: Schema.String,
+    key: Schema.String,
+    value: Schema.String,
+    evidence: GraphEvidence
 }) {
 }
 export class SurveyGraph extends Schema.Class("SurveyGraph")({
     nodes: Schema.Array(SurveyNode),
-    edges: Schema.Array(SurveyEdge)
+    edges: Schema.Array(SurveyEdge),
+    unresolved: Schema.Array(Unresolved).pipe(Schema.withDecodingDefaultKey(Effect.succeed([])), Schema.withConstructorDefault(Effect.succeed([]))),
+    fills: Schema.Array(Fill).pipe(Schema.withDecodingDefaultKey(Effect.succeed([])), Schema.withConstructorDefault(Effect.succeed([])))
 }) {
-    incoming(name) {
-        return this.edges.filter((edge) => edge.to === name);
+    incoming(id) {
+        return indexOf(this).incoming.get(id) ?? [];
     }
-    outgoing(name) {
-        return this.edges.filter((edge) => edge.from === name);
+    outgoing(id) {
+        return indexOf(this).outgoing.get(id) ?? [];
+    }
+    node(id) {
+        return indexOf(this).byId.get(id);
     }
 }
+/**
+ * Adjacency, built once per graph instance and kept in a WeakMap: a graph is
+ * immutable (every change constructs a new one), so the index never goes
+ * stale, and walks over an estate-sized graph stay linear instead of V × E.
+ */
+const indexes = new WeakMap();
+const indexOf = (graph) => {
+    const cached = indexes.get(graph);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const byId = new Map();
+    for (const node of graph.nodes) {
+        const id = nodeId(node);
+        if (!byId.has(id)) {
+            byId.set(id, node);
+        }
+    }
+    const incoming = new Map();
+    const outgoing = new Map();
+    for (const edge of graph.edges) {
+        const into = incoming.get(edge.to);
+        if (into === undefined) {
+            incoming.set(edge.to, [edge]);
+        }
+        else {
+            into.push(edge);
+        }
+        const from = outgoing.get(edge.from);
+        if (from === undefined) {
+            outgoing.set(edge.from, [edge]);
+        }
+        else {
+            from.push(edge);
+        }
+    }
+    const index = { byId, incoming, outgoing };
+    indexes.set(graph, index);
+    return index;
+};
+export const nodeId = (node) => node.id ?? node.name;
+export const nodeKind = (node) => node.kind ?? "file";
+export const nodeLabel = (node) => node.label ?? node.name;
+export const nodeAttrs = (node) => node.attrs ?? {};
+export const nodeLineStart = (node) => node.lineStart ?? 1;
+export const nodeLineEnd = (node) => node.lineEnd ?? node.lines;
+export const isDescriptor = (node) => node.descriptor === true;
+export const edgeOrigin = (edge) => edge.origin ?? "scanner";
+export const edgeConfidence = (edge) => edge.confidence ?? "exact";
+const inferred = "inferred";
+/**
+ * The file-level view every pre-ADR-0030 consumer expects. Each node folds onto
+ * a unit (its `anchor` attr when that names a known unit, else its file's
+ * unit); descriptor nodes with outgoing edges are contracted (`a → d → b`
+ * becomes `a → b` under `a → d`'s kind); self loops drop; duplicates by
+ * (from, to, kind) drop. On a file-only graph this is the identity.
+ */
+export const projectToFiles = (graph) => {
+    const files = graph.nodes.filter((node) => nodeKind(node) === "file");
+    const known = new Set(files.map((node) => node.name));
+    const byId = new Map(graph.nodes.map((node) => [nodeId(node), node]));
+    const unitOf = (id) => {
+        const node = byId.get(id);
+        if (node === undefined) {
+            return id;
+        }
+        if (nodeKind(node) === "file") {
+            return node.name;
+        }
+        const anchored = node.anchor === undefined ? undefined : nodeAttrs(node)[node.anchor];
+        if (anchored !== undefined) {
+            const resolved = resolveUnit(anchored, known);
+            if (known.has(resolved)) {
+                return resolved;
+            }
+        }
+        return unitName(node.path);
+    };
+    const contractible = new Set(graph.nodes
+        .filter((node) => isDescriptor(node) && graph.outgoing(nodeId(node)).length > 0)
+        .map(nodeId));
+    const edgeKey = (edge) => `${edge.from}\u0000${edge.to}\u0000${edge.kind}\u0000${edgeConfidence(edge)}`;
+    let edges = graph.edges;
+    for (let round = 0; round <= graph.nodes.length; round += 1) {
+        if (!edges.some((edge) => contractible.has(edge.to))) {
+            break;
+        }
+        const next = [];
+        const keys = new Set();
+        const push = (edge) => {
+            const key = edgeKey(edge);
+            if (!keys.has(key)) {
+                keys.add(key);
+                next.push(edge);
+            }
+        };
+        for (const edge of edges) {
+            if (!contractible.has(edge.to)) {
+                push(edge);
+                continue;
+            }
+            for (const hop of graph.outgoing(edge.to)) {
+                push(new SurveyEdge({
+                    ...edge,
+                    to: hop.to,
+                    mechanism: "contraction",
+                    ...(edgeConfidence(edge) === "inferred" || edgeConfidence(hop) === "inferred"
+                        ? { confidence: inferred }
+                        : {})
+                }));
+            }
+        }
+        // A descriptor cycle re-derives the same edges forever: stop when a round
+        // adds nothing new; what still ends on a descriptor is cycle residue.
+        if (next.length === edges.length &&
+            next.every((edge, index) => edgeKey(edge) === edgeKey(edges[index]))) {
+            break;
+        }
+        edges = next;
+    }
+    const seen = new Set();
+    const projected = edges.flatMap((edge) => {
+        if (contractible.has(edge.from) || contractible.has(edge.to)) {
+            return [];
+        }
+        const from = unitOf(edge.from);
+        const to = unitOf(edge.to);
+        const key = `${from}\u0000${to}\u0000${edge.kind}`;
+        if (from === to || seen.has(key)) {
+            return [];
+        }
+        seen.add(key);
+        return [new SurveyEdge({ ...edge, from, to })];
+    });
+    return new SurveyGraph({
+        nodes: files,
+        edges: projected,
+        unresolved: graph.unresolved,
+        fills: graph.fills
+    });
+};
+export const graphFromJson = (text) => Effect.try({
+    try: () => JSON.parse(text),
+    catch: (error) => PlanParseError.make({ message: `graph.json is not JSON: ${String(error)}` })
+}).pipe(Effect.flatMap((json) => Schema.decodeUnknownEffect(SurveyGraph)(json).pipe(Effect.mapError((error) => PlanParseError.make({ message: `graph.json does not decode: ${String(error)}` })))));
 /**
  * The transitive dependency closure of `program` as repo-relative paths,
  * breadth-first, excluding the program itself. The `seen` set is required, not
@@ -34,13 +252,14 @@ export class SurveyGraph extends Schema.Class("SurveyGraph")({
  * instead of an unbounded read.
  */
 export const closureFor = (graph, program, maxFiles) => {
-    const pathOf = new Map(graph.nodes.map((node) => [node.name, node.path]));
+    const projected = projectToFiles(graph);
+    const pathOf = new Map(projected.nodes.map((node) => [node.name, node.path]));
     const walk = (frontier, seen, acc) => {
         if (frontier.length === 0 || acc.length >= maxFiles) {
             return acc.slice(0, maxFiles);
         }
         const next = [
-            ...new Set(frontier.flatMap((from) => graph.outgoing(from).map((edge) => edge.to)))
+            ...new Set(frontier.flatMap((from) => projected.outgoing(from).map((edge) => edge.to)))
         ].filter((name) => !seen.has(name));
         return walk(next, new Set([...seen, ...next]), [
             ...acc,
@@ -77,52 +296,433 @@ export const resolveUnit = (reference, known) => {
     const folded = unitName(reference);
     return known.has(folded) ? folded : reference;
 };
-const matches = (regex, contents) => {
-    const expression = new RegExp(regex, "g");
-    return [...contents.matchAll(expression)].map((match) => match[1] ?? match[0]);
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/** 0-based offset → 1-based line, via a precomputed table of line starts. */
+const lineLocator = (text) => {
+    const starts = [0];
+    for (let index = 0; index < text.length; index += 1) {
+        if (text.charCodeAt(index) === 10) {
+            starts.push(index + 1);
+        }
+    }
+    return (offset) => {
+        let low = 0;
+        let high = starts.length - 1;
+        while (low < high) {
+            const mid = (low + high + 1) >> 1;
+            if ((starts[mid] ?? 0) <= offset) {
+                low = mid;
+            }
+            else {
+                high = mid - 1;
+            }
+        }
+        return low + 1;
+    };
 };
-export const surveyGraph = Effect.fn("@llm4ts/flow/Survey.graph")(function* (workspace, sources, units, edgeRules, options = {}) {
-    // The source regex narrows discovery itself, so the workspace's result cap
-    // counts candidate units rather than every jar, image, and generated file
-    // sharing the tree with them.
-    const paths = [
-        ...(yield* workspace.discover("**/*", {
-            matching: new RegExp(sources),
-            ...(options.exclude === undefined ? {} : { excluding: new RegExp(options.exclude) })
-        }))
-    ].sort();
+/** Every match of `pattern` (flags `gm`) with its line and defined named groups. */
+const captures = (pattern, text, locate) => [...text.matchAll(new RegExp(pattern, "gm"))].map((match) => ({
+    line: locate(match.index ?? 0),
+    groups: Object.fromEntries(Object.entries(match.groups ?? {}).flatMap(([key, value]) => value === undefined ? [] : [[key, value]])),
+    first: match[1] ?? match[0]
+}));
+const scanner = "scanner";
+const exact = "exact";
+/** Node ids: `<kind>:<path>#<name>`, `~n` for a repeated name within one file. */
+const scanNodes = (paths, contents, units, rules) => {
     const nodes = [];
-    const contents = new Map();
     for (const path of paths) {
-        const text = yield* workspace.read(path);
-        contents.set(path, text);
+        const text = contents.get(path) ?? "";
+        const lines = text.split(/\r?\n/).length;
+        const locate = lineLocator(text);
         nodes.push(SurveyNode.make({
             path,
             name: unitName(path),
-            lines: text.split(/\r?\n/).length,
+            lines,
             units: units
                 .filter((rule) => new RegExp(rule.files).test(path))
-                .reduce((count, rule) => count + matches(rule.unit, text).length, 0)
+                .reduce((count, rule) => count + captures(rule.unit, text, locate).length, 0),
+            id: unitName(path),
+            kind: "file",
+            lineStart: 1,
+            lineEnd: lines
         }));
+        for (const rule of rules.filter((rule) => new RegExp(rule.files).test(path))) {
+            const seen = new Map();
+            const own = [];
+            for (const hit of captures(rule.pattern, text, locate)) {
+                const name = hit.groups.name ?? `L${hit.line}`;
+                const count = (seen.get(name) ?? 0) + 1;
+                seen.set(name, count);
+                const attrs = Object.fromEntries(Object.entries(hit.groups).filter(([key]) => key !== "name"));
+                for (const [attr, group] of Object.entries(rule.attrs)) {
+                    const value = hit.groups[group];
+                    if (value !== undefined) {
+                        attrs[attr] = value;
+                    }
+                }
+                own.push(SurveyNode.make({
+                    path,
+                    name,
+                    lines: 0,
+                    units: 0,
+                    id: `${rule.kind}:${path}#${name}${count > 1 ? `~${count}` : ""}`,
+                    kind: rule.kind,
+                    label: name,
+                    lineStart: hit.line,
+                    lineEnd: lines,
+                    attrs,
+                    origin: scanner,
+                    descriptor: rule.descriptor,
+                    ...(rule.anchor === undefined ? {} : { anchor: rule.anchor })
+                }));
+            }
+            // A node spans to the line before the next node of the same kind in the file.
+            own.forEach((node, index) => {
+                const next = own[index + 1];
+                nodes.push(next === undefined
+                    ? node
+                    : new SurveyNode({
+                        ...node,
+                        lineEnd: Math.max(nodeLineStart(node), nodeLineStart(next) - 1)
+                    }));
+            });
+        }
+    }
+    return nodes;
+};
+const lookupOf = (nodes) => {
+    const inFile = new Map();
+    const byKindName = new Map();
+    const byPathKindName = new Map();
+    const known = new Set();
+    for (const node of nodes) {
+        const kind = nodeKind(node);
+        if (kind === "file") {
+            known.add(node.name);
+        }
+        const kinds = inFile.get(node.path) ?? new Map();
+        const list = kinds.get(kind) ?? [];
+        list.push(node);
+        kinds.set(kind, list);
+        inFile.set(node.path, kinds);
+        const kindKey = `${kind}\u0000${node.name}`;
+        if (!byKindName.has(kindKey)) {
+            byKindName.set(kindKey, node);
+        }
+        const pathKey = `${node.path}\u0000${kind}\u0000${node.name}`;
+        if (!byPathKindName.has(pathKey)) {
+            byPathKindName.set(pathKey, node);
+        }
+    }
+    for (const kinds of inFile.values()) {
+        for (const list of kinds.values()) {
+            list.sort((left, right) => nodeLineStart(left) - nodeLineStart(right));
+        }
+    }
+    return { inFile, byKindName, byPathKindName, known };
+};
+/** The last node of `kind` in `path` starting at or before `line` (binary search over the file's list). */
+const enclosing = (lookup, path, kind, line) => {
+    const list = lookup.inFile.get(path)?.get(kind) ?? [];
+    let low = 0;
+    let high = list.length - 1;
+    let found;
+    while (low <= high) {
+        const mid = (low + high) >> 1;
+        const candidate = list[mid];
+        if (nodeLineStart(candidate) <= line) {
+            found = candidate;
+            low = mid + 1;
+        }
+        else {
+            high = mid - 1;
+        }
+    }
+    return found;
+};
+const resolveTarget = (lookup, path, kind, reference) => {
+    if (kind === "file") {
+        const unit = resolveUnit(reference, lookup.known);
+        return { id: unit, found: lookup.known.has(unit) };
     }
-    const known = new Set(nodes.map((node) => node.name));
+    const node = lookup.byPathKindName.get(`${path}\u0000${kind}\u0000${reference}`) ??
+        lookup.byKindName.get(`${kind}\u0000${reference}`);
+    return node === undefined ? { id: reference, found: false } : { id: nodeId(node), found: true };
+};
+const scanEdges = (paths, contents, nodes, rules) => {
+    const lookup = lookupOf(nodes);
+    const lineOf = new Map(nodes.map((node) => [nodeId(node), nodeLineStart(node)]));
     const edges = [];
-    for (const rule of edgeRules) {
+    const unresolved = [];
+    const seen = new Set();
+    const push = (edge) => {
+        const key = `${edge.from}\u0000${edge.to}\u0000${edge.kind}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            edges.push(edge);
+        }
+    };
+    for (const rule of rules) {
         const filePattern = new RegExp(rule.files);
         for (const path of paths.filter((path) => filePattern.test(path))) {
-            for (const target of new Set(matches(rule.unit, contents.get(path) ?? ""))) {
-                const edge = SurveyEdge.make({
-                    from: unitName(path),
-                    to: resolveUnit(target, known),
-                    kind: rule.name
+            const text = contents.get(path) ?? "";
+            const locate = lineLocator(text);
+            const lines = text.split(/\r?\n/);
+            for (const hit of captures(rule.pattern, text, locate)) {
+                const reference = rule.positional === true ? hit.first : hit.groups.to;
+                if (reference === undefined) {
+                    continue;
+                }
+                const fromNode = rule.fromKind === "file" ? undefined : enclosing(lookup, path, rule.fromKind, hit.line);
+                const from = fromNode === undefined ? unitName(path) : nodeId(fromNode);
+                const evidence = GraphEvidence.make({
+                    file: path,
+                    line: hit.line,
+                    snippet: (lines[hit.line - 1] ?? "").trim()
                 });
-                if (!edges.some((current) => current.from === edge.from && current.to === edge.to && current.kind === edge.kind)) {
-                    edges.push(edge);
+                const target = resolveTarget(lookup, path, rule.toKind, reference);
+                const targets = [];
+                if (target.found && hit.groups.thru !== undefined && rule.toKind !== "file") {
+                    const end = resolveTarget(lookup, path, rule.toKind, hit.groups.thru);
+                    const startLine = lineOf.get(target.id) ?? 0;
+                    const endLine = end.found ? (lineOf.get(end.id) ?? startLine) : startLine;
+                    targets.push(...(lookup.inFile.get(path)?.get(rule.toKind) ?? [])
+                        .filter((node) => nodeLineStart(node) >= startLine && nodeLineStart(node) <= endLine)
+                        .map(nodeId));
+                }
+                else if (target.found || rule.toKind === "file") {
+                    targets.push(target.id);
+                }
+                if (!target.found) {
+                    unresolved.push(Unresolved.make({
+                        reason: "edge-target",
+                        rule: rule.kind,
+                        node: from,
+                        reference,
+                        file: path,
+                        line: hit.line
+                    }));
+                }
+                for (const to of targets) {
+                    push(SurveyEdge.make({
+                        from,
+                        to,
+                        kind: rule.kind,
+                        origin: scanner,
+                        confidence: exact,
+                        rule: rule.kind,
+                        mechanism: "capture",
+                        evidence
+                    }));
                 }
             }
         }
     }
-    return SurveyGraph.make({ nodes, edges });
+    return { edges, unresolved };
+};
+/** Nodes and captured edges only; joins and the unresolved summary come from `applyFillsAndJoins`. */
+export const scanGraph = (paths, contents, options) => {
+    const nodes = scanNodes(paths, contents, options.coverage, options.rules.nodes);
+    const { edges, unresolved } = scanEdges(paths, contents, nodes, options.rules.edges);
+    return SurveyGraph.make({ nodes, edges, unresolved, fills: [] });
+};
+/** Directories `D` with some scanned path under `D/WEB-INF/`, sorted; the per-app scope of url joins. */
+export const appRoots = (paths) => [
+    ...new Set(paths.flatMap((path) => {
+        const index = path.indexOf("/WEB-INF/");
+        return index < 0 ? [] : [path.slice(0, index)];
+    }))
+].sort();
+/** The longest app root that prefixes `path`, or "" for the estate scope. */
+export const appOf = (path, roots) => [...roots]
+    .filter((root) => path === root || path.startsWith(`${root}/`))
+    .sort((left, right) => right.length - left.length)[0] ?? "";
+const withFills = (nodes, fills) => nodes.map((node) => {
+    const own = fills.filter((fill) => fill.node === nodeId(node));
+    return own.length === 0
+        ? node
+        : new SurveyNode({
+            ...node,
+            attrs: {
+                ...nodeAttrs(node),
+                ...Object.fromEntries(own.map((fill) => [fill.key, fill.value]))
+            }
+        });
+});
+const joinRank = { exact: 0, prefix: 1, extension: 2 };
+/** A join attr: a named group copied into attrs, or the node's own name for `name`. */
+const attrOf = (node, attr) => attr === "name" ? node.name : nodeAttrs(node)[attr];
+const llm = "llm";
+const joinEdges = (nodes, fills, rules, roots) => {
+    const filled = new Set(fills.map((fill) => `${fill.node}\u0000${fill.key}`));
+    const edges = [];
+    const unresolved = [];
+    const seen = new Set();
+    for (const rule of rules) {
+        const sources = nodes.filter((node) => nodeKind(node) === rule.fromKind);
+        const targets = nodes.filter((node) => nodeKind(node) === rule.toKind);
+        for (const source of sources) {
+            const raw = attrOf(source, rule.fromAttr);
+            if (raw === undefined) {
+                unresolved.push(Unresolved.make({
+                    reason: "missing-attr",
+                    rule: rule.kind,
+                    node: nodeId(source),
+                    file: source.path,
+                    line: nodeLineStart(source)
+                }));
+                continue;
+            }
+            const request = rule.match === "url" ? normalizeUrl(raw) : raw.trim();
+            const inScope = targets.filter((target) => rule.scope === "file"
+                ? target.path === source.path
+                : rule.scope === "app"
+                    ? appOf(target.path, roots) === appOf(source.path, roots)
+                    : true);
+            const matched = inScope.flatMap((target) => {
+                const value = attrOf(target, rule.toAttr);
+                if (value === undefined) {
+                    return [];
+                }
+                const how = rule.match === "url"
+                    ? matchUrl(request, value)
+                    : value.trim() === request
+                        ? "exact"
+                        : undefined;
+                return how === undefined ? [] : [{ target, how, value }];
+            });
+            // Servlet-spec order: exact beats the longest prefix beats an extension.
+            const best = matched.sort((left, right) => joinRank[left.how] - joinRank[right.how] || right.value.length - left.value.length)[0];
+            if (best === undefined) {
+                unresolved.push(Unresolved.make({
+                    reason: "join-from",
+                    rule: rule.kind,
+                    node: nodeId(source),
+                    reference: raw,
+                    file: source.path,
+                    line: nodeLineStart(source)
+                }));
+                continue;
+            }
+            const inferred = filled.has(`${nodeId(source)}\u0000${rule.fromAttr}`) ||
+                filled.has(`${nodeId(best.target)}\u0000${rule.toAttr}`);
+            const key = `${nodeId(source)}\u0000${nodeId(best.target)}\u0000${rule.kind}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                edges.push(SurveyEdge.make({
+                    from: nodeId(source),
+                    to: nodeId(best.target),
+                    kind: rule.kind,
+                    origin: inferred ? llm : scanner,
+                    confidence: inferred ? "inferred" : exact,
+                    rule: rule.kind,
+                    mechanism: rule.match === "url" ? "join:url" : "join:exact",
+                    join: best.how,
+                    evidence: GraphEvidence.make({
+                        file: source.path,
+                        line: nodeLineStart(source),
+                        snippet: raw
+                    })
+                }));
+            }
+        }
+    }
+    // A join target nothing reaches, reported once per node whatever the kind:
+    // a mapping hit by a form but by no ajax call is wired, not a hole.
+    const reached = new Set(edges.map((edge) => edge.to));
+    const reportedKinds = new Set();
+    for (const rule of rules) {
+        if (reportedKinds.has(rule.toKind)) {
+            continue;
+        }
+        reportedKinds.add(rule.toKind);
+        for (const target of nodes.filter((node) => nodeKind(node) === rule.toKind)) {
+            if (!reached.has(nodeId(target))) {
+                unresolved.push(Unresolved.make({
+                    reason: "join-to",
+                    rule: rule.kind,
+                    node: nodeId(target),
+                    file: target.path,
+                    line: nodeLineStart(target)
+                }));
+            }
+        }
+    }
+    return { edges, unresolved };
+};
+/**
+ * Pure re-derivation: every `join:*` edge is dropped and rebuilt from the
+ * current attrs plus `fills`; `unresolved` is recomputed from scratch except
+ * for `edge-target` entries, which only the scanner knows. `paths` defaults
+ * to the node paths; pass the scanned list to compute app roots precisely.
+ */
+export const applyFillsAndJoins = (graph, fills, rules, paths = graph.nodes.map((node) => node.path)) => {
+    const nodes = withFills(graph.nodes, fills);
+    const kept = graph.edges.filter((edge) => !(edge.mechanism ?? "").startsWith("join:"));
+    const joined = joinEdges(nodes, fills, rules.joins, appRoots(paths));
+    const edges = [...kept, ...joined.edges];
+    const projected = projectToFiles(SurveyGraph.make({ nodes, edges, unresolved: [], fills }));
+    // A file that only holds wiring records (web.xml) is a descriptor file, not
+    // a unit nothing references: it never counts as isolated.
+    const wiringFiles = new Set(nodes.filter(isDescriptor).map((node) => node.path));
+    const isolated = projected.nodes
+        .filter((node) => !wiringFiles.has(node.path) &&
+        projected.incoming(node.name).length === 0 &&
+        projected.outgoing(node.name).length === 0)
+        .map((node) => Unresolved.make({
+        reason: "isolated",
+        rule: "file",
+        node: node.name,
+        file: node.path,
+        line: 1
+    }));
+    // An edge-target hole retires once a non-scanner edge leaves the same node
+    // from the same line: the seat (or an external index) answered it.
+    const answered = new Set(edges
+        .filter((edge) => edgeOrigin(edge) !== "scanner" && edge.evidence !== undefined)
+        .map((edge) => `${edge.from}\u0000${edge.evidence?.file}\u0000${edge.evidence?.line}`));
+    return SurveyGraph.make({
+        nodes,
+        edges,
+        unresolved: [
+            ...graph.unresolved.filter((item) => item.reason === "edge-target" &&
+                !answered.has(`${item.node}\u0000${item.file}\u0000${item.line}`)),
+            ...joined.unresolved,
+            ...isolated
+        ],
+        fills
+    });
+};
+export const buildCodeGraph = Effect.fn("@llm4ts/flow/Survey.buildCodeGraph")(function* (workspace, options) {
+    // The source regex narrows discovery itself, so the workspace's result cap
+    // counts candidate units rather than every jar, image, and generated file
+    // sharing the tree with them.
+    const paths = [
+        ...(yield* workspace.discover("**/*", {
+            matching: new RegExp(options.sources),
+            ...(options.exclude === undefined ? {} : { excluding: new RegExp(options.exclude) })
+        }))
+    ].sort();
+    const contents = new Map();
+    const files = {};
+    for (const path of paths) {
+        const text = yield* workspace.read(path);
+        contents.set(path, text);
+        files[path] = sha256(text);
+    }
+    const scanned = scanGraph(paths, contents, options);
+    return { graph: applyFillsAndJoins(scanned, [], options.rules, paths), files };
+});
+/** The pre-ADR-0030 entry: Survey rules only, file nodes only. Delegates to `buildCodeGraph`. */
+export const surveyGraph = Effect.fn("@llm4ts/flow/Survey.graph")(function* (workspace, sources, units, edgeRules, options = {}) {
+    const build = yield* buildCodeGraph(workspace, {
+        sources,
+        ...(options.exclude === undefined ? {} : { exclude: options.exclude }),
+        coverage: units,
+        rules: { ...emptyGraphRules, edges: edgeRules.map(edgeRuleOfSurvey) }
+    });
+    return build.graph;
 });
 export const mergeSurveyEdges = (graph, refined) => {
     const known = new Set(graph.nodes.map((node) => node.name));
@@ -150,7 +750,10 @@ export const mergeSurveyEdges = (graph, refined) => {
         edges: [...graph.edges, ...kept]
     });
 };
-export const renderSurveyInventory = (graph) => {
+export const renderSurveyInventory = (full) => {
+    // The inventory is a table of UNITS (files); sub-file nodes and descriptors
+    // fold onto their files first (ADR 0030).
+    const graph = projectToFiles(full);
     const rows = [...graph.nodes]
         .sort((left, right) => left.name.localeCompare(right.name))
         .map((node) => {
@@ -159,7 +762,7 @@ export const renderSurveyInventory = (graph) => {
         const flags = incoming === 0 && outgoing === 0 ? "unreferenced — retire candidate?" : "";
         return `| ${node.name} | ${node.path} | ${node.lines} | ${node.units} | ${incoming} | ${outgoing} | ${flags} |`;
     });
-    const refined = graph.edges.filter((edge) => edge.kind.startsWith("llm-")).length;
+    const refined = full.edges.filter((edge) => edge.kind.startsWith("llm-") || edgeOrigin(edge) === "llm").length;
     return [
         "# Estate inventory",
         "",
@@ -207,8 +810,8 @@ export const surveyRefinePrompt = (graph, context) => [
     '- "notes": references you could not resolve to a unit — indirect targets whose value you',
     "  could not trace, external systems. Empty if none.",
     "",
-    `Units: ${graph.nodes
-        .map((node) => node.name)
+    `Units: ${projectToFiles(graph)
+        .nodes.map((node) => node.name)
         .sort()
         .join(", ")}`,
     "",