@intentius/chant 0.124.45 → 0.124.46

package/dist/cli/handlers/search.js

@@ -2,16 +2,22 @@ import { resolve } from "node:path";
 import { build } from "../../build.js";
 import { buildGraphIr, buildLiveGraphIr, collectUnobserved, sourceOverlayGraphs } from "../../graph-ir.js";
 import { buildDeclaredPerStack } from "../../graph-declared.js";
-import { enrichEffectiveTopology } from "../../graph-effective.js";
+import { enrichEffectiveTopology, terraformResourceType, terraformType } from "../../graph-effective.js";
+import { attachCapabilities, attachView, capabilityEngine, parseCapabilityCall } from "../../capabilities/catalog.js";
+import { CapabilityError } from "../../capabilities/matcher.js";
 import { reconstructEdges, mergeCatalogs } from "../../graph-refs.js";
 import { discover } from "../../discovery/index.js";
-import { observeResources } from "../../lifecycle/observe.js";
+import { carryAnnotations, observeResources } from "../../lifecycle/observe.js";
 import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay.js";
 import { diffLive } from "../../lifecycle/live-diff.js";
 import { formatUnobserved } from "../../observation.js";
+import { readChantPackageVersion } from "../../package-version.js";
 import { loadChantConfig, matchesDeclaredEnvironment } from "../../config.js";
-import { loadPlugins, resolveProjectLexicons } from "../plugins.js";
+import { collectBuildRootContributors, loadPlugins, resolveProjectLexicons } from "../plugins.js";
+import { declaredBuildRootContributors, mergeDeclaredBuildRoots, withLexiconEdges } from "./declared-graph.js";
+import { parseCountBy, countGroups, countsJson, formatCounts, groupMembers, hasManyTerraformRoots } from "./search-count.js";
 import { formatError, formatWarning } from "../format.js";
+import { SEARCH_CONTRACT_VERSION, SEARCH_OUTPUT_SCHEMA_ID } from "../../workspace/search-contract.js";
 /**
  * `chant search <query> [--live --env <name>]` — answer an estate question with
  * a COMPACT result instead of the whole graph. The point (measured on aws-bench,
@@ -20,11 +26,14 @@ import { formatError, formatWarning } from "../format.js";
  *
  * Query grammar (space-separated terms, all must match — AND):
  *   bare word            case-insensitive substring over id, kind, and attrs
- *   kind:<substr>        node kind contains <substr> (e.g. kind:EC2::Instance)
+ *   kind:<substr>        node kind contains <substr> (e.g. kind:EC2::Instance);
+ *                        on a terraform resource, its type (kind:aws_instance, kind:aws_iam_)
  *   tag:<key>=<val>      a Tags entry with Key=key and Value containing val
  *   attr:<name>=<val>    attribute <name> equals/contains <val>
  *   ->kind:X / ->attr:.. this node has an edge TO a node matching the right side
  *   <-kind:X / <-attr:.. this node has an edge FROM a node matching the right side
+ *   ->*X, ->{n}X, ->{m,n}X  the far end is any depth / n / m..n hops away (#4359)
+ *   ->[via=a]X, ->[to=a]X   only edges through consumer attr a / reading producer attr a
  *
  * The edge operators are the point of "edge-aware" search (#1139): a small
  * model shouldn't hand-join instance→subnet→public across many results — one
@@ -38,46 +47,36 @@ import { formatError, formatWarning } from "../format.js";
 export async function runSearch(ctx) {
     const { args } = ctx;
     const query = (args.path ?? "").trim();
-    if (!query) {
-        console.error(formatError({ message: "chant search needs a query: chant search \"<terms>\" [--live --env <name>]" }));
+    // A refusal (#4367): the error on stderr as always, and under --json the
+    // same message and hint as the one document on stdout, so a program reading
+    // stdout sees why there are no rows. Exit 1 either way. The code is from the
+    // read contract's closed list (#4374).
+    const refuse = (error) => {
+        console.error(formatError(error));
+        if (args.json)
+            console.log(JSON.stringify(searchErrorJson(query, error)));
         return 1;
+    };
+    // The capability catalog (#4375): the `capabilities` document, not an answer.
+    if (args.capabilities)
+        return printCapabilities(args, query, await resolveProjectLexicons(resolve(".")).catch(() => []));
+    // The snapshot to replay (#4374): `--snapshot <ref>`, or `--at <ref>`, which
+    // plain search keeps for compatibility. Everywhere else in the read contract
+    // `--at` is a git revision, so the workspace form takes only `--snapshot`.
+    if (args.snapshot !== undefined && args.at !== undefined && String(args.snapshot) !== String(args.at)) {
+        return refuse({
+            code: "usage-invalid",
+            message: `chant search was given --snapshot ${args.snapshot} and --at ${args.at}`,
+            hint: "they name the same thing, the recorded snapshot to answer from; give one",
+        });
     }
-    let terms;
-    try {
-        terms = parseQuery(query);
-    }
-    catch (err) {
-        if (err instanceof QueryError) {
-            console.error(formatError({ message: err.message, hint: err.hint }));
-            return 1;
-        }
-        throw err;
-    }
+    const snapshotRef = args.snapshot ?? (args.at !== undefined ? String(args.at) : undefined);
+    const snapshotFlag = args.snapshot !== undefined ? "--snapshot" : "--at";
+    const checked = checkSearchArgs(args, query, { ref: snapshotRef, flag: snapshotFlag });
+    if ("error" in checked)
+        return refuse(checked.error);
+    const { terms, countBy } = checked;
     const show = parseShow(args);
-    // Query-scoped drift (#1268): --check-live checks a snapshot answer against
-    // a live read, --check-snapshot checks a live answer against the recorded
-    // snapshot — the direction each needs is the source it does NOT already have.
-    if (args.checkLive && !args.at) {
-        console.error(formatError({
-            message: "chant search --check-live needs --at <ref>",
-            hint: "answer from a snapshot and check the matched rows against a live read: --at latest --check-live --env <name>",
-        }));
-        return 1;
-    }
-    if (args.checkSnapshot && !args.live) {
-        console.error(formatError({
-            message: "chant search --check-snapshot needs --live",
-            hint: "answer live and check the matched rows against the recorded snapshot: --live --check-snapshot --env <name>",
-        }));
-        return 1;
-    }
-    if (args.failOnDrift && !args.checkLive && !args.checkSnapshot) {
-        console.error(formatError({
-            message: "chant search --fail-on-drift needs --check-live or --check-snapshot",
-            hint: "it fails the check those flags run, so it is meaningless without one",
-        }));
-        return 1;
-    }
     const projectPath = resolve(".");
     const { config } = await loadChantConfig(projectPath);
     let ir;
@@ -89,6 +88,9 @@ export async function runSearch(ctx) {
     // on this path" — printed with the provenance footer, after the rows, so the
     // answer is not preceded by what qualifies it.
     let liveNotes = [];
+    // Which read answered each entity (#2267), from a live read.
+    let readSources = {};
+    let rootReads = {};
     // Kinds that can exist in the account without being declared (#1278). Known
     // without a scan, so it costs nothing to mention.
     let ambientKinds = [];
@@ -102,58 +104,51 @@ export async function runSearch(ctx) {
     let declaredForDrift;
     let snapshotDepth;
     let driftFailure = false;
-    if (args.live || args.at) {
-        const environment = args.env;
-        if (!environment) {
-            const flag = args.at ? "--at" : "--live";
-            console.error(formatError({ message: `chant search ${flag} needs an environment: ${flag} --env <name>` }));
-            return 1;
-        }
-        if (args.live && args.at) {
-            // Two different observations of the same estate, and no rule for which
-            // wins. Comparing them is a real question (#1268) but it is not this one.
-            console.error(formatError({
-                message: "chant search takes --live or --at, not both",
-                hint: "--live reads the estate now; --at answers from a recorded snapshot",
-            }));
-            return 1;
-        }
+    // Why --check-snapshot had nothing to check against, for --json (#4367).
+    let driftUnavailable;
+    if (args.live || snapshotRef) {
+        // checkSearchArgs refused a live or snapshot read without one.
+        const environment = String(args.env);
         // Membership via matchesDeclaredEnvironment (#1221): handles `{ name,
         // endpoint }` entries (#1166) — a plain `.includes` never matched those —
         // and glob-pattern entries like `"pr-*"`.
         if (config.environments && config.environments.length > 0 && !matchesDeclaredEnvironment(config.environments, environment)) {
-            console.error(formatError({ message: `Unknown environment "${environment}"` }));
-            return 1;
+            return refuse({ code: "environment-unknown", message: `Unknown environment "${environment}"` });
         }
         const plugins = ctx.plugins.length > 0 ? ctx.plugins : await loadPlugins(await resolveProjectLexicons(projectPath));
+        // Build roots too (#4358), as `chant graph --live` does: a terraform
+        // root's blocks are entities only once its root is rendered, and an
+        // entity the build never produced is never observed.
+        const buildRoots = collectBuildRootContributors(plugins, config, projectPath);
         const buildResult = await build(resolve(args.src ?? config.sourceDir ?? "."), plugins.map((p) => p.serializer), undefined, {
+            buildRoots,
             config: config,
         });
         if (buildResult.errors.length > 0) {
-            console.error(formatError({ message: "Build failed — fix errors before searching live state" }));
-            return 1;
+            return refuse({ code: "build-failed", message: "Build failed — fix errors before searching live state" });
         }
         const observing = plugins.filter((p) => p.describeResources);
         ambientKinds = observing.flatMap((p) => p.ambientKinds?.() ?? []);
         const stacks = (config.stacks ?? []).map((s) => ({ name: s.name, region: s.region, src: s.src }));
         let observations;
+        // Facts about absent entities (#4372): a planned create's plan attributes.
+        let annotations;
         const liveAttrs = {};
-        if (args.at) {
+        if (snapshotRef) {
             // Answer from a recorded observation (#1266). Everything downstream is
             // the live path's — the point is that a snapshot replays into the same
             // shape a live read produces, so one pipeline serves both and a fold
             // improvement reaches an old snapshot for free.
             const scoped = new Set(stacks.filter((st) => st.src).map((st) => st.name));
-            const replay = await replaySnapshots(environment, String(args.at), scoped);
+            const replay = await replaySnapshots(environment, snapshotRef, scoped);
             if ("error" in replay) {
-                console.error(formatError({ message: replay.error, ...(replay.hint ? { hint: replay.hint } : {}) }));
-                return 1;
+                return refuse({ code: "snapshot-unavailable", message: replay.error, ...(replay.hint ? { hint: replay.hint } : {}) });
             }
             observations = replay.observations;
             replayAmbient = {
                 recordedAmbient: replay.observations.some((o) => Object.values(o.resources).some((m) => m.ambient === true)),
             };
-            source = { kind: "snapshot", commit: replay.commit, timestamp: replay.timestamp };
+            source = { kind: "snapshot", snapshot: snapshotRef, commit: replay.commit, timestamp: replay.timestamp };
             snapshotDepth = replay.depth;
             if (args.checkLive) {
                 // A fresh live read, additional to the snapshot the answer itself came
@@ -184,6 +179,9 @@ export async function runSearch(ctx) {
                 console.error(formatError({ message: `live read failed — ${e}` }));
             }
             observations = observed.observations;
+            annotations = observed.annotations;
+            readSources = observed.sources ?? {};
+            rootReads = observed.rootReads ?? {};
             liveNotes = observed.notes ?? [];
             source = { kind: "live" };
             if (args.checkSnapshot) {
@@ -195,6 +193,7 @@ export async function runSearch(ctx) {
                 const checkReplay = await replaySnapshots(environment, "latest", scoped);
                 if ("error" in checkReplay) {
                     console.error(formatWarning({ message: `--check-snapshot: ${checkReplay.error}` }));
+                    driftUnavailable = checkReplay.error;
                 }
                 else {
                     checkObservations = checkReplay.observations;
@@ -208,7 +207,7 @@ export async function runSearch(ctx) {
         let containmentEdges = [];
         // Live-only: enrichment is a provider call, so it has no place in a replay.
         // A recorded answer that quietly reached for the API would stop being one.
-        if (!args.at) {
+        if (!snapshotRef) {
             for (const p of observing) {
                 if (!p.enrichLiveAttrs)
                     continue;
@@ -265,9 +264,16 @@ export async function runSearch(ctx) {
         // `${stack}::${id}` — matching how observation qualifies. A flat whole-
         // project discovery would disambiguate colliding names by module path
         // (UsEast1Src…), which never matches the observed bare LogicalResourceIds.
+        //
+        // The flat canvas is the declared path's graph (#4365, #4358): discovery
+        // plus the build-root contributions (a terraform root's blocks, a rendered
+        // kustomize root) plus the lexicon edges, so a live answer over a Terraform
+        // root overlays onto a canvas that has the root's resources on it.
         const declared = stacks.length > 0
-            ? await buildDeclaredPerStack(stacks, projectPath)
-            : buildGraphIr((await discover(resolve(args.src ?? config.sourceDir ?? "."))).entities, projectPath);
+            ? await buildDeclaredPerStack(stacks, projectPath, (g, entities) => withLexiconEdges(g, plugins, entities))
+            : await declaredGraph(ctx, projectPath, resolve(args.src ?? config.sourceDir ?? "."), plugins);
+        if (!declared)
+            return refuse(BUILD_ROOT_FAILED);
         declaredForDrift = declared;
         // Carry the NOT-OBSERVED half of the tri-state (#1089) onto the rows, so a
         // declared entity nobody could read is painted `_unobserved` and a row can
@@ -305,21 +311,102 @@ export async function runSearch(ctx) {
         // account's default VPC, whose route table chant does not model). The
         // overlay copies physical identity but not attrs, so merge them here.
         ir = { ...ir, nodes: ir.nodes.map((n) => (liveAttrs[n.id] ? { ...n, attrs: { ...n.attrs, ...liveAttrs[n.id] } } : n)) };
+        // And what the read learned about an entity it found absent (#4372), so
+        // `attr:planAction=create` matches a block the plan will create. The node
+        // stays pending: only its attributes change.
+        ir = { ...ir, nodes: carryAnnotations(ir.nodes, annotations) };
     }
     else {
-        const discovered = await discover(resolve(args.src ?? config.sourceDir ?? "."));
-        ir = buildGraphIr(discovered.entities);
+        const declared = await declaredGraph(ctx, projectPath, resolve(args.src ?? config.sourceDir ?? "."));
+        if (!declared)
+            return refuse(BUILD_ROOT_FAILED);
+        ir = declared;
     }
     // Fold derived reachability facts (effectiveIngress, internetFacing) onto
     // instance nodes so multi-hop/launch-template joins are one node predicate (#1139).
     ir = enrichEffectiveTopology(ir);
+    // Capability terms (#4375) read the graph through the lexicons' mappings.
+    if (terms.some(usesCapability)) {
+        const refused = await bindCapabilities(ctx, projectPath, ir, terms);
+        if (refused)
+            return refuse({ code: "query-invalid", ...refused });
+    }
     // Resolve `kind:` terms against what is actually in this graph, before any
     // node is tested against them.
     resolveKindTerms(terms, ir.nodes);
     const nodeById = new Map(ir.nodes.map((n) => [n.id, n]));
     const matches = ir.nodes.filter((n) => terms.every((t) => matchTerm(n, t, ir, nodeById)));
+    // Query-scoped drift (#1268): the matched rows, and only the matched rows,
+    // checked against the observation the primary answer did NOT use. Scoping
+    // both sides of diffLive() to the matched ids is what keeps a query-scoped-
+    // out resource from reading as `missing` or `unobserved` — it was never
+    // asked about, which is a third thing from both.
+    let drift;
+    if (checkObservations && declaredForDrift && primaryObservations) {
+        const declaredIds = new Set(declaredForDrift.nodes.map((n) => n.id));
+        const matchedIds = new Set(matches.map((n) => n.id));
+        const nowObservations = args.checkLive ? checkObservations : primaryObservations;
+        const thenObservations = args.checkLive ? primaryObservations : checkObservations;
+        drift = diffLive({
+            declared: new Set([...matchedIds].filter((id) => declaredIds.has(id))),
+            observedNow: pickResources(mergeResources(nowObservations), matchedIds),
+            observedThen: pickResources(mergeResources(thenObservations), matchedIds),
+            unobserved: pickResources(collectUnobserved(nowObservations), matchedIds),
+        });
+    }
+    // Name the plan read when it answered (#4384).
+    if (source.kind === "live")
+        source = withReadDepth(source, matches, readSources, rootReads);
+    const driftAgainst = args.checkLive ? "live" : "snapshot";
+    // Machine-readable answer (#4359, #4367): the rows, their paths, and every
+    // footer the text prints as prose, as one document for a caller that draws
+    // it (behold#913). Same exit codes as the text path.
+    if (args.json) {
+        const recorded = source.kind === "live" && !matches.some((n) => n.physicalId) && args.env
+            ? (await hasSnapshot(String(args.env))) ? "yes" : undefined
+            : undefined;
+        const env = args.env && source.kind !== "declared" ? String(args.env) : undefined;
+        const provenanceText = provenanceLine(matches, source, recorded, liveFailures, [...derivedUsed(terms, matches, ir), ...capabilitiesUsed(terms)]).replace(/^— /, "");
+        const capNotes = capabilityNotes(terms, ir, source);
+        const plannedCreates = source.kind !== "declared" && liveFailures.length === 0 ? plannedCreateCount(matches) : 0;
+        const driftJson = drift
+            ? searchDriftJson(drift, matches.length, driftAgainst, snapshotDepth)
+            : driftUnavailable !== undefined
+                ? { against: driftAgainst, unavailable: driftUnavailable }
+                : undefined;
+        // With --count-by (#4360) the object carries the groups and the total in
+        // place of the matches, the same answer the grouped lines give, with the
+        // provenance line beside it (#4367).
+        const head = { ...searchHead(), ...(await workspaceIdentity(projectPath)) };
+        const payload = countBy
+            ? {
+                ...head,
+                ...countsJson(query, env ? { ...source, env } : source, groupMembers(matches, countBy, hasManyTerraformRoots(ir)), countBy, liveFailures),
+                provenance: provenanceText,
+                ...(plannedCreates > 0 ? { plannedCreates } : {}),
+                ...(driftJson ? { drift: driftJson } : {}),
+            }
+            : {
+                ...head,
+                ...searchJson(query, source, matches, terms, ir, nodeById, liveFailures, {
+                    ...(env ? { env } : {}),
+                    show,
+                    provenance: provenanceText,
+                    ...(plannedCreates > 0 ? { plannedCreates } : {}),
+                    ...(capNotes.length > 0 ? { capabilities: capNotes } : {}),
+                    ...(args.explain ? { explain: explainData(terms, matches, ir, nodeById) } : {}),
+                    ...(driftJson ? { drift: driftJson } : {}),
+                }),
+            };
+        console.log(JSON.stringify(payload));
+        for (const n of liveNotes)
+            console.error(formatWarning({ message: n }));
+        if (liveFailures.length > 0)
+            return 1;
+        return args.failOnDrift && drift && driftCountOf(drift) > 0 ? 1 : 0;
+    }
     if (matches.length === 0) {
-        console.log("(no matches)");
+        console.log(countBy ? "(no matches) · 0 total" : "(no matches)");
         availableAttrs(terms, ir);
         if (args.explain)
             explain(terms, matches, ir, nodeById, query);
@@ -327,8 +414,14 @@ export async function runSearch(ctx) {
             console.error(formatWarning({ message: n }));
         return 0;
     }
-    for (const n of matches) {
-        console.log(formatRow(n, show));
+    if (countBy) {
+        for (const line of formatCounts(countGroups(matches, countBy, hasManyTerraformRoots(ir)), countBy))
+            console.log(line);
+    }
+    else {
+        for (const n of matches) {
+            console.log(formatRow(n, show));
+        }
     }
     const backed = source.kind === "declared" || matches.some((n) => n.physicalId);
     // Only worth asking when the live read came back empty — that is the one case
@@ -336,33 +429,26 @@ export async function runSearch(ctx) {
     const recorded = source.kind === "live" && !matches.some((n) => n.physicalId) && args.env
         ? (await hasSnapshot(String(args.env))) ? "yes" : undefined
         : undefined;
-    provenance(matches, source, recorded, liveFailures);
+    provenance(matches, source, recorded, liveFailures, [...derivedUsed(terms, matches, ir), ...capabilitiesUsed(terms)]);
+    for (const c of capabilityNotes(terms, ir, source)) {
+        if (c.notEvaluated.length > 0)
+            console.log(`— ${c.name} does not evaluate: ${c.notEvaluated.join("; ")}`);
+    }
     // Qualifies the provenance line, so it sits with it: one line per distinct
     // note for the whole run, not one per stack, and after the rows (#1265).
     for (const n of liveNotes)
         console.error(formatWarning({ message: n }));
-    // Query-scoped drift (#1268): the matched rows, and only the matched rows,
-    // checked against the observation the primary answer did NOT use. Scoping
-    // both sides of diffLive() to the matched ids is what keeps a query-scoped-
-    // out resource from reading as `missing` or `unobserved` — it was never
-    // asked about, which is a third thing from both.
-    if (checkObservations && declaredForDrift && primaryObservations) {
-        const declaredIds = new Set(declaredForDrift.nodes.map((n) => n.id));
-        const matchedIds = new Set(matches.map((n) => n.id));
-        const nowObservations = args.checkLive ? checkObservations : primaryObservations;
-        const thenObservations = args.checkLive ? primaryObservations : checkObservations;
-        const driftCount = renderDrift(diffLive({
-            declared: new Set([...matchedIds].filter((id) => declaredIds.has(id))),
-            observedNow: pickResources(mergeResources(nowObservations), matchedIds),
-            observedThen: pickResources(mergeResources(thenObservations), matchedIds),
-            unobserved: pickResources(collectUnobserved(nowObservations), matchedIds),
-        }), matches.length, args.checkLive ? "live" : "snapshot", snapshotDepth);
+    if (drift) {
+        const driftCount = renderDrift(drift, matches.length, driftAgainst, snapshotDepth);
         if (args.failOnDrift && driftCount > 0)
             driftFailure = true;
     }
     ambientHint(matches, ambientKinds, args.ambient === true, replayAmbient);
-    showMiss(matches, show);
-    regionSpread(terms, matches, show);
+    // Both point at `--show`, which a grouped count does not print (#4360).
+    if (!countBy) {
+        showMiss(matches, show);
+        regionSpread(terms, matches, show);
+    }
     derivedSurface(terms, matches, ir, backed);
     if (args.explain)
         explain(terms, matches, ir, nodeById, query);
@@ -383,6 +469,317 @@ export async function runSearch(ctx) {
         return 1;
     return 0;
 }
+/**
+ * Check a search's query and flags before anything is read (#4374): the
+ * grammar, `--count-by`, and the flags that need or exclude each other. The
+ * rules `chant search` and `chant workspace search` share, so the workspace
+ * form refuses once, with the same code and message, instead of once per
+ * member. `snapshot` is the snapshot asked for and the flag that asked:
+ * `--snapshot`, or plain search's `--at`.
+ */
+export function checkSearchArgs(args, query, snapshot) {
+    const flag = snapshot.flag;
+    // `--count-by` groups the matched set (#4360). It takes any query, and no
+    // query at all counts the whole graph: "which kinds does this estate hold".
+    let countBy;
+    if (args.countBy !== undefined) {
+        const parsed = parseCountBy(args.countBy);
+        if ("error" in parsed)
+            return { error: { code: "query-invalid", message: parsed.error, hint: parsed.hint } };
+        countBy = parsed;
+    }
+    if (!query && !countBy) {
+        return { error: { code: "query-invalid", message: "chant search needs a query: chant search \"<terms>\" [--live --env <name>]" } };
+    }
+    let terms;
+    try {
+        terms = parseQuery(query);
+    }
+    catch (err) {
+        if (err instanceof QueryError)
+            return { error: { code: "query-invalid", message: err.message, hint: err.hint } };
+        throw err;
+    }
+    // Query-scoped drift (#1268): --check-live checks a snapshot answer against
+    // a live read, --check-snapshot checks a live answer against the recorded
+    // snapshot — the direction each needs is the source it does NOT already have.
+    if (args.checkLive && !snapshot.ref) {
+        return {
+            error: {
+                code: "usage-invalid",
+                message: `chant search --check-live needs ${flag} <ref>`,
+                hint: `answer from a snapshot and check the matched rows against a live read: ${flag} latest --check-live --env <name>`,
+            },
+        };
+    }
+    if (args.checkSnapshot && !args.live) {
+        return {
+            error: {
+                code: "usage-invalid",
+                message: "chant search --check-snapshot needs --live",
+                hint: "answer live and check the matched rows against the recorded snapshot: --live --check-snapshot --env <name>",
+            },
+        };
+    }
+    if (args.failOnDrift && !args.checkLive && !args.checkSnapshot) {
+        return {
+            error: {
+                code: "usage-invalid",
+                message: "chant search --fail-on-drift needs --check-live or --check-snapshot",
+                hint: "it fails the check those flags run, so it is meaningless without one",
+            },
+        };
+    }
+    if ((args.live || snapshot.ref) && !args.env) {
+        const needs = snapshot.ref ? flag : "--live";
+        return { error: { code: "usage-invalid", message: `chant search ${needs} needs an environment: ${needs} --env <name>` } };
+    }
+    if (args.live && snapshot.ref) {
+        // Two different observations of the same estate, and no rule for which
+        // wins. Comparing them is a real question (#1268) but it is not this one.
+        return {
+            error: {
+                code: "usage-invalid",
+                message: `chant search takes --live or ${flag}, not both`,
+                hint: `--live reads the estate now; ${flag} answers from a recorded snapshot`,
+            },
+        };
+    }
+    return { terms, ...(countBy ? { countBy } : {}) };
+}
+/** Why a search over a project whose build root failed refuses (#4365), as the refusal prints it. */
+const BUILD_ROOT_FAILED = {
+    code: "build-failed",
+    message: "chant search: a build root failed to render, so the graph it would answer over is incomplete",
+    hint: "fix the error above; `chant graph . --format ir` reports the same one",
+};
+/**
+ * The declared graph a search answers over (#4362, #4365, #4368): discovery,
+ * plus the build-root entities (a terraform root's blocks, a rendered
+ * kustomize root), plus the edges the lexicons' `graphEdges` hooks add. The
+ * same join and the same edges `chant graph --format ir` draws, through the
+ * same helpers (`./declared-graph.ts`), so a node's id here is its id there.
+ *
+ * Returns undefined, having printed the build root's own errors, when a build
+ * root failed to render or collided with a discovered name; the caller refuses
+ * with {@link BUILD_ROOT_FAILED}. A search over the rest would answer
+ * `(no matches)` for a root it never read, which is a wrong answer stated as
+ * a fact.
+ */
+async function declaredGraph(ctx, projectPath, srcDir, loaded) {
+    const discovered = await discover(srcDir);
+    if (!(await mergeDeclaredBuildRoots(discovered.entities, await declaredBuildRootContributors(ctx, projectPath))))
+        return undefined;
+    let plugins = loaded ?? ctx.plugins;
+    if (plugins.length === 0) {
+        try {
+            plugins = await loadPlugins(await resolveProjectLexicons(projectPath));
+        }
+        catch {
+            plugins = [];
+        }
+    }
+    return withLexiconEdges(buildGraphIr(discovered.entities, projectPath), plugins, discovered.entities);
+}
+/**
+ * Print the capability catalog (#4375): the `capabilities` document under
+ * `--json`, a line per capability otherwise. It takes no query and no other
+ * search flag, since it answers nothing about the estate. Shared by `chant
+ * search` and `chant workspace search`, which differ only in the lexicons
+ * they report on.
+ */
+export async function printCapabilities(args, query, lexicons) {
+    const { capabilitiesDocument, capabilitiesFailure, formatCapabilities } = await import("../../workspace/capabilities-contract.js");
+    const extra = [
+        // `args.path` is "." when no query was given.
+        ...(query && query !== "." ? [`the query "${query}"`] : []),
+        ...["live", "env", "snapshot", "at", "countBy", "explain", "show"]
+            .filter((k) => args[k] !== undefined && args[k] !== false)
+            .map((k) => `--${k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`),
+    ];
+    if (extra.length > 0) {
+        const error = {
+            code: "usage-invalid",
+            message: `--capabilities prints the catalog, so it takes no query and no other search flag; it was given ${extra.join(", ")}`,
+            hint: "ask with a capability instead: chant search \"cap:internet-reachable(22)\"",
+        };
+        console.error(formatError(error));
+        if (args.json)
+            console.log(JSON.stringify(await capabilitiesFailure(error)));
+        return 1;
+    }
+    const doc = await capabilitiesDocument(lexicons);
+    if (args.json)
+        console.log(JSON.stringify(doc));
+    else
+        for (const line of formatCapabilities(doc))
+            console.log(line);
+    return 0;
+}
+/** The capabilities a query names, in query order, for the provenance line (#4375). */
+function capabilitiesUsed(terms) {
+    const out = [];
+    const walk = (t) => {
+        if (t.negated)
+            return;
+        const call = t.kind === "cap" ? t.a : t.capability;
+        const name = call !== undefined ? parseCapabilityCall(call)?.name : undefined;
+        if (name && !out.includes(name))
+            out.push(name);
+        if (t.sub)
+            walk(t.sub);
+    };
+    terms.forEach(walk);
+    return out;
+}
+/**
+ * What each capability the query used could not evaluate (#4375), with a
+ * count where this graph holds the thing left out: an answer computed from
+ * declared references says what it skipped, so a caller knows the rows are a
+ * floor, not the whole of it.
+ */
+function capabilityNotes(terms, ir, source) {
+    const names = capabilitiesUsed(terms);
+    if (names.length === 0)
+        return [];
+    const engine = capabilityEngine(ir);
+    const statements = [...engine.view.nodes.values()].filter((n) => n.label === "Statement" && n.attrs.effect === "Allow");
+    const counts = {
+        'Resource "*"': statements.filter((n) => n.attrs.anyResource).length,
+        "IAM Condition keys": statements.filter((n) => n.attrs.condition).length,
+        "resources the graph holds but can't resolve, such as an expression naming nothing declared": statements.filter((n) => n.attrs.unresolved).length,
+    };
+    return names.map((name) => ({
+        name,
+        source: source.kind,
+        notEvaluated: (engine.rule(name)?.meta["not-evaluated"] ?? "")
+            .split(/;|\n/)
+            .map((x) => x.trim())
+            .filter(Boolean)
+            .map((x) => (counts[x] ? `${x} (${counts[x]} statement${counts[x] === 1 ? "" : "s"} here)` : x)),
+    }));
+}
+/**
+ * Answer capability terms over a graph that is not this project's own (#4375):
+ * `chant workspace search` composes its members' graphs and views and asks
+ * here, so the rules run once over the whole of it. Given packs, the view is
+ * built here; given a view, it is the one the members' own chants mapped
+ * (#4378). Returns the rows
+ * as `--json` carries them, or the refusal for a capability the query names
+ * wrongly.
+ */
+export function answerOverGraph(ir, terms, query, packsOrView) {
+    // A workspace hands over the view its members' chants mapped (#4378).
+    const engine = Array.isArray(packsOrView) ? attachCapabilities(ir, packsOrView) : attachView(ir, packsOrView);
+    const refused = checkCapabilityTerms(engine, terms);
+    if (refused)
+        return { error: refused };
+    resolveKindTerms(terms, ir.nodes);
+    const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+    const matches = ir.nodes.filter((n) => terms.every((t) => matchTerm(n, t, ir, byId)));
+    const doc = searchJson(query, { kind: "declared" }, matches, terms, ir, byId);
+    return { matches: doc.matches, capabilities: capabilityNotes(terms, ir, { kind: "declared" }) };
+}
+/** Whether a term, or the leaf under it, names a capability (#4375). */
+export function usesCapability(t) {
+    return t.kind === "cap" || t.capability !== undefined || (t.sub !== undefined && usesCapability(t.sub));
+}
+/**
+ * Bind the graph to its lexicons' capability packs and check every capability
+ * the query names (#4375): an unknown name, a set used as an edge or the
+ * wrong arguments is a refusal, never an empty answer.
+ */
+async function bindCapabilities(ctx, projectPath, ir, terms) {
+    let plugins = ctx.plugins;
+    if (plugins.length === 0) {
+        try {
+            plugins = await loadPlugins(await resolveProjectLexicons(projectPath));
+        }
+        catch {
+            plugins = [];
+        }
+    }
+    const engine = attachCapabilities(ir, plugins.map((p) => p.capabilityPack).filter((p) => !!p));
+    return checkCapabilityTerms(engine, terms);
+}
+/** Refuse a capability the query names that doesn't exist, a set used as an edge, or the wrong arguments. */
+function checkCapabilityTerms(engine, terms) {
+    const known = [...new Set(engine.publicNames())].join(", ");
+    const check = (t) => {
+        if (t.sub) {
+            const inner = check(t.sub);
+            if (inner)
+                return inner;
+        }
+        const call = t.kind === "cap" ? t.a : t.capability;
+        if (call === undefined)
+            return undefined;
+        const parsed = parseCapabilityCall(call);
+        if (!engine.has(parsed.name)) {
+            return { message: `no capability "${parsed.name}"`, hint: `the capabilities are ${known}; chant search --capabilities describes each` };
+        }
+        const shape = engine.rule(parsed.name).vars.length === 1 ? "set" : "edge";
+        if (t.capability !== undefined && shape === "set") {
+            return { message: `"${parsed.name}" is a set, not an edge`, hint: `test it as a term: cap:${call}` };
+        }
+        try {
+            engine.bind(parsed.name, parsed.args);
+        }
+        catch (err) {
+            if (err instanceof CapabilityError)
+                return { message: `cap:${call}: ${err.message}`, hint: "chant search --capabilities lists each capability's parameters" };
+            throw err;
+        }
+        return undefined;
+    };
+    for (const t of terms) {
+        const r = check(t);
+        if (r)
+            return r;
+    }
+    return undefined;
+}
+/**
+ * The read a plan-depth root fell back to, from the lexicon's structured
+ * per-root report. Never from note text. "state" wins over "declared" when
+ * roots disagree, because some read still answered.
+ */
+function planFallback(rootReads) {
+    const falls = Object.values(rootReads)
+        .filter((r) => (r.depth === "plan" || r.depth === "live+plan") && r.fellBackTo)
+        .map((r) => r.fellBackTo);
+    if (falls.includes("state"))
+        return "state";
+    if (falls.includes("live"))
+        return "live";
+    if (falls.includes("declared"))
+        return "declared";
+    return undefined;
+}
+/**
+ * Add the read depth to a live source (#4384). Only bound matches count: a
+ * row nobody read has no read to name. Nothing is added when no match was
+ * answered by the plan and the plan did not fall back.
+ */
+function withReadDepth(source, matches, sources, rootReads) {
+    const reads = [...new Set(matches.filter((n) => n.physicalId).map((n) => sources[n.id]).filter((r) => !!r))].sort();
+    const fellBack = planFallback(rootReads);
+    const planned = reads.filter((r) => r === "plan" || r === "live+plan");
+    if (planned.length === 0 && !fellBack)
+        return source;
+    return {
+        ...source,
+        ...(planned.length > 0 ? { depth: reads.length === 1 ? reads[0] : "mixed" } : {}),
+        ...(reads.length > 0 ? { reads } : {}),
+        ...(fellBack ? { planFellBackTo: fellBack } : {}),
+    };
+}
+const READ_PHRASE = {
+    plan: "at the plan depth (terraform plan -lock=false)",
+    "live+plan": "live and at the plan depth (live-plan -json, terraform plan -lock=false)",
+    state: "from state",
+    live: "live",
+};
 /**
  * Name the `--show` columns nothing carries (#1279).
  *
@@ -479,10 +876,25 @@ function ambientHint(matches, ambientKinds, asked, replay) {
  * already done. That is a fact about the query, printed for every query, and it
  * encodes no expected answer.
  */
-function provenance(matches, source, recorded, liveFailures = []) {
+function provenanceLine(matches, source, recorded, liveFailures = [], derived = []) {
+    const line = provenanceBase(matches, source, recorded, liveFailures, derived);
+    // The plan read fell back (#4384): say to what, on whichever line this is.
+    return source.kind === "live" ? line + fellBackText(source) : line;
+}
+/** ` · the plan read fell back to state`, or nothing. */
+function fellBackText(source) {
+    if (!source.planFellBackTo)
+        return "";
+    // A live root has no state read to fall to: live-plan answered alone.
+    const to = source.planFellBackTo === "live" ? "live-plan alone" : source.planFellBackTo;
+    return ` · the plan read fell back to ${to}`;
+}
+function provenanceBase(matches, source, recorded, liveFailures = [], derived = []) {
     if (source.kind === "declared") {
-        console.log("— declared only · no observation · physical ids unavailable");
-        return;
+        // A derived fact the query relied on (#4362) was folded from declared
+        // references alone, so it describes the source, not the account.
+        const from = derived.length > 0 ? ` · ${derived.join(", ")} derived from declared references` : "";
+        return `— declared only · no observation · physical ids unavailable${from}`;
     }
     const bound = matches.filter((n) => n.physicalId).length;
     const what = source.kind === "live" ? "live read" : "snapshot";
@@ -494,10 +906,15 @@ function provenance(matches, source, recorded, liveFailures = []) {
         const rest = recorded
             ? "a snapshot of this environment is recorded — answer from it with --at latest"
             : "answered from the declared graph · physical ids unavailable";
-        console.log(`— live read failed (${lexicons}) · ${unobserved}/${matches.length} rows unobserved · ${rest}`);
-        return;
+        return `— live read failed (${lexicons}) · ${unobserved}/${matches.length} rows unobserved · ${rest}`;
     }
     if (bound === 0) {
+        // Every match a planned create (#4372): absent on purpose, so "returned no
+        // bound resources" reads as a failed read when the read worked.
+        const planned = plannedCreateCount(matches);
+        if (planned > 0) {
+            return `— ${what}: ${planned} planned ${planned === 1 ? "create" : "creates"}, none bound yet · the plan has not been applied`;
+        }
         // The estate was asked for and nothing came back bound. Naming it is the
         // difference between "these do not exist" and "nobody could see them".
         // A snapshot sitting unused is the actionable half of this. Denied network,
@@ -505,21 +922,37 @@ function provenance(matches, source, recorded, liveFailures = []) {
         // retrying `--live` — the tool knew the estate was unreachable AND that a
         // recording of it was on disk, and said only the first half.
         if (recorded) {
-            console.log(`— ${what} returned no bound resources · a snapshot of this environment is recorded — answer from it with --at latest`);
-            return;
+            return (`— ${what} returned no bound resources · a snapshot of this environment is recorded — answer from it with --at latest`);
         }
-        console.log(`— ${what} returned no bound resources · answered from the declared graph · physical ids unavailable`);
-        return;
+        return (`— ${what} returned no bound resources · answered from the declared graph · physical ids unavailable`);
     }
     if (source.kind === "live") {
-        console.log(`— observed live · bound ${bound}/${matches.length}`);
-        return;
+        // The plan answered some or all of it (#4384): say so, and name each read.
+        if (source.depth && source.reads) {
+            return `— observed ${source.reads.map((r) => READ_PHRASE[r] ?? r).join(" and ")} · bound ${bound}/${matches.length}`;
+        }
+        return `— observed live · bound ${bound}/${matches.length}`;
     }
     // Time is the whole risk of a recorded answer, so it leads. A caller can see
     // how old this is and decide, rather than discovering staleness later.
     const taken = source.timestamp ? ` taken ${source.timestamp}` : "";
     const at = source.commit ? ` ${source.commit.slice(0, 7)}` : "";
-    console.log(`— observed from snapshot${at}${taken} · bound ${bound}/${matches.length}`);
+    return `— observed from snapshot${at}${taken} · bound ${bound}/${matches.length}`;
+}
+/**
+ * How many matches there are when every one is a planned create (#4372): an
+ * absent entity (no physical id) carrying `planAction=create`. Zero for no
+ * matches or any other mix, so a real empty read keeps its wording.
+ */
+function plannedCreateCount(matches) {
+    if (matches.length === 0)
+        return 0;
+    const all = matches.every((n) => !n.physicalId && n.attrs?.planAction === "create");
+    return all ? matches.length : 0;
+}
+/** Print {@link provenanceLine}: the text footer. */
+function provenance(matches, source, recorded, liveFailures = [], derived = []) {
+    console.log(provenanceLine(matches, source, recorded, liveFailures, derived));
 }
 /** Union `LiveObservation.resources` across lexicons into one name-keyed map. */
 function mergeResources(observations) {
@@ -564,12 +997,36 @@ function renderDrift(diff, checked, direction, depth) {
         console.log(`  · ${r.name} (${r.type}) — runtime, owned by ${r.owner}`);
     for (const u of diff.unobserved)
         console.log(`  ? ${formatUnobserved(u.name, u)}`);
-    const driftCount = diff.missing.length + diff.orphan.length + diff.disappeared.length + diff.driftedSinceSnapshot.length;
+    const driftCount = driftCountOf(diff);
     const label = direction === "live" ? "a live read" : "the recorded snapshot";
     const depthNote = depth === "deep" ? " · snapshot recorded at deep depth, compared here at identity" : "";
     console.log(`— checked against ${label} · ${driftCount > 0 ? `${driftCount} of ${checked} matched drifted` : `no drift across ${checked} matched`}${depthNote}`);
     return driftCount;
 }
+/** What counts as drift: the set `lifecycle diff` totals (#1268). */
+function driftCountOf(diff) {
+    return diff.missing.length + diff.orphan.length + diff.disappeared.length + diff.driftedSinceSnapshot.length;
+}
+function searchDriftJson(diff, checked, against, depth) {
+    return {
+        against,
+        checked,
+        count: driftCountOf(diff),
+        missing: diff.missing,
+        orphan: diff.orphan,
+        disappeared: diff.disappeared,
+        drifted: diff.driftedSinceSnapshot.flatMap((d) => d.changes.map((c) => ({ id: d.name, path: c.path, old: c.oldValue, new: c.newValue }))),
+        newlyObserved: diff.newlyObserved,
+        runtimeChildren: diff.runtimeChildren.map((r) => ({ id: r.name, type: r.type, owner: r.owner })),
+        unobserved: diff.unobserved.map((u) => ({
+            id: u.name,
+            ...(u.type ? { type: u.type } : {}),
+            reason: u.reason,
+            ...(u.detail ? { detail: u.detail } : {}),
+        })),
+        ...(depth ? { depth } : {}),
+    };
+}
 function formatValue(v) {
     if (v === undefined)
         return "<unset>";
@@ -599,19 +1056,31 @@ function derivedSurface(terms, matches, ir, backed = true) {
         return;
     const used = new Set(terms.filter((t) => t.kind === "attr").map((t) => t.a));
     const unused = new Set();
-    for (const n of matches) {
-        for (const [kind, names] of Object.entries(derived)) {
-            if (!n.kind?.includes(kind))
-                continue;
-            for (const name of names)
-                if (!used.has(name))
-                    unused.add(name);
-        }
-    }
+    for (const n of matches)
+        for (const name of derivedNames(n, ir))
+            if (!used.has(name))
+                unused.add(name);
     if (unused.size === 0)
         return;
     console.log(`— also derived for these resources: ${[...unused].sort().join(", ")}`);
 }
+/** The derived attributes recorded for a node's kind (or its terraform resource type, #4362). */
+function derivedNames(n, ir) {
+    const tfType = terraformResourceType(n);
+    return Object.entries(ir.derivedAttrs ?? {})
+        .filter(([kind]) => n.kind?.includes(kind) || kind === tfType)
+        .flatMap(([, names]) => names);
+}
+/** The derived attributes the query's `attr:` terms relied on, for the provenance line. */
+function derivedUsed(terms, matches, ir) {
+    const queried = new Set(terms.filter((t) => t.kind === "attr" && !t.negated).map((t) => t.a));
+    const out = new Set();
+    for (const n of matches)
+        for (const name of derivedNames(n, ir))
+            if (queried.has(name))
+                out.add(name);
+    return [...out].sort();
+}
 /**
  * `--explain` footer (#1139): a compact, model-DERIVED summary that gives a
  * small model a reason to trust the result instead of re-deriving it with a
@@ -622,33 +1091,70 @@ function derivedSurface(terms, matches, ir, backed = true) {
  * any expected answer, so it stays a fair, question-agnostic capability.
  */
 function explain(terms, matches, ir, byId, query) {
-    const kinds = new Set(matches.map((n) => n.kind).filter((k) => !!k));
-    const universe = kinds.size > 0 ? ir.nodes.filter((n) => n.kind && kinds.has(n.kind)) : ir.nodes;
-    const matched = new Set(matches.map((n) => n.id));
-    const excluded = universe.filter((n) => !matched.has(n.id));
-    const kindLabel = kinds.size > 0 ? [...kinds].join("/") : "nodes";
-    console.log(`— ${matches.length} of ${universe.length} ${kindLabel} matched  (query: ${query})`);
+    const data = explainData(terms, matches, ir, byId);
+    const kindLabel = data.universe.kinds.length > 0 ? data.universe.kinds.join("/") : "nodes";
+    console.log(`— ${data.universe.matched} of ${data.universe.of} ${kindLabel} matched  (query: ${query})`);
     // Inclusion evidence: for a derived fact a CLI can't easily re-verify
     // (internetFacing, resolved across the default VPC's routing), name WHY each
     // match qualifies, so the agent trusts the result instead of dropping it.
+    for (const e of data.evidence)
+        console.log(`  ✓ ${bareId(e.id)} ${e.attr} via ${e.via}`);
+    // The chain each match was reached by (#4359), so a caller can quote the
+    // path instead of re-deriving it with one search per hop.
+    for (const n of matches) {
+        for (const p of matchPaths(n, terms, ir, byId)) {
+            // A capability's path (#4375) turns as the rule does, so each hop says which way it went.
+            if (p.term.kind === "cap" || p.term.capability !== undefined) {
+                // A set a node is in by its own attributes (stores-data) has no path to print.
+                if (p.hops.length === 0 && !p.because)
+                    continue;
+                console.log(`  path ${bareId(n.id)} ${termText({ ...p.term, negated: false })}: ${formatHops(p.hops, n.id) || "(the node itself)"}`);
+                for (const b of p.because ?? []) {
+                    console.log(`    ${b.capability} ${bareId(b.id)}: ${formatHops(b.hops, b.id) || "(an attribute of the node)"}`);
+                }
+            }
+            else
+                console.log(`  path ${formatPath(p.hops, p.term.dir)}`);
+        }
+    }
+    for (const m of data.nearMisses) {
+        console.log(`  · excluded ${bareId(m.id)} — fails ${m.term ? describeTerm(m.term) : "(query)"}`);
+    }
+    if (data.moreExcluded > 0)
+        console.log(`  · …and ${data.moreExcluded} more excluded`);
+}
+/** How many near-misses `--explain` names before summarising the rest. */
+const NEAR_MISS_LIMIT = 8;
+/**
+ * The facts behind the `--explain` footer, shared by the text and `--json`
+ * (#4367). The universe is every node of the matched kinds (every node when
+ * nothing matched); a near-miss is a node of that universe the query
+ * excluded, with the first term it fails.
+ */
+function explainData(terms, matches, ir, byId) {
+    // Counted against a terraform block's type, not `Terraform::Resource` (#4366):
+    // "2 of 2 aws_instance", not "2 of 185 Terraform::Resource".
+    const kinds = new Set(matches.map(displayKind).filter((k) => !!k));
+    const universe = kinds.size > 0 ? ir.nodes.filter((n) => kinds.has(displayKind(n) ?? "")) : ir.nodes;
+    const matched = new Set(matches.map((n) => n.id));
+    const excluded = universe.filter((n) => !matched.has(n.id));
+    const evidence = [];
     for (const t of terms) {
         if (t.kind !== "attr")
             continue;
         for (const n of matches) {
             const via = n.attrs?.[`${t.a}Via`];
-            const id = n.id.includes("::") ? n.id.slice(n.id.lastIndexOf("::") + 2) : n.id;
             if (typeof via === "string")
-                console.log(`  ✓ ${id} ${t.a} via ${via}`);
+                evidence.push({ id: n.id, attr: t.a, via });
         }
     }
-    const shown = excluded.slice(0, 8);
-    for (const n of shown) {
-        const failing = terms.find((t) => !matchTerm(n, t, ir, byId));
-        const id = n.id.includes("::") ? n.id.slice(n.id.lastIndexOf("::") + 2) : n.id;
-        console.log(`  · excluded ${id} — fails ${failing ? describeTerm(failing) : "(query)"}`);
-    }
-    if (excluded.length > shown.length)
-        console.log(`  · …and ${excluded.length - shown.length} more excluded`);
+    const shown = excluded.slice(0, NEAR_MISS_LIMIT);
+    return {
+        universe: { matched: matches.length, of: universe.length, kinds: [...kinds] },
+        evidence,
+        nearMisses: shown.map((n) => ({ id: n.id, term: terms.find((t) => !matchTerm(n, t, ir, byId)) })),
+        moreExcluded: excluded.length - shown.length,
+    };
 }
 /**
  * On a miss, name the attributes the queried kind actually carries. A graph knows
@@ -662,7 +1168,7 @@ function availableAttrs(terms, ir) {
     const kindTerm = terms.find((t) => t.kind === "kind");
     if (!kindTerm)
         return;
-    const of = ir.nodes.filter((n) => n.kind?.includes(kindTerm.a));
+    const of = ir.nodes.filter((n) => matchTerm(n, { ...kindTerm, negated: false }));
     if (of.length === 0)
         return;
     const names = new Set();
@@ -703,11 +1209,86 @@ function describeTerm(t) {
     // the opposite of what it is.
     if (t.negated)
         return `!${describeTerm({ ...t, negated: false })}`;
-    const leaf = (x) => x.kind === "kind" ? `kind:${x.a}` : x.kind === "attr" ? `attr:${x.a}${x.b !== undefined ? "=" + x.b : ""}`
+    if (t.kind === "edge")
+        return `${edgeOperator(t, { out: "→", in: "←" })}${t.sub ? leafText(t.sub) : ""} (no such edge)`;
+    return leafText(t);
+}
+function leafText(x) {
+    if (x.kind === "cap")
+        return `cap:${x.a}`;
+    return x.kind === "kind" ? `kind:${x.a}` : x.kind === "attr" ? `attr:${x.a}${x.b !== undefined ? "=" + x.b : ""}`
         : x.kind === "tag" ? `tag:${x.a}${x.b !== undefined ? "=" + x.b : ""}` : `"${x.a}"`;
-    if (t.kind === "edge" && t.sub)
-        return `${t.dir === "out" ? "→" : "←"}${leaf(t.sub)} (no such edge)`;
-    return leaf(t);
+}
+function searchErrorJson(query, error) {
+    return { ...searchHead(), query, error: { code: error.code, message: error.message, ...(error.hint ? { hint: error.hint } : {}) } };
+}
+/** The head of every `search` document (#4374): the contract, its schema, and the chant that wrote it. */
+function searchHead() {
+    return { $schema: SEARCH_OUTPUT_SCHEMA_ID, contract: SEARCH_CONTRACT_VERSION, chant: readChantPackageVersion() };
+}
+/**
+ * The workspace a project belongs to, when it belongs to one (#4374, ws-016):
+ * its declared name and its root relative to the git root, with `at: null`,
+ * since plain search reads the working tree. Outside a workspace, or when its
+ * declaration can't be read, only `at`.
+ */
+async function workspaceIdentity(cwd) {
+    try {
+        const [{ locateWorkspace }, { readDeclaration }] = await Promise.all([import("../../workspace/which-chant.js"), import("../../workspace/declaration.js")]);
+        const located = locateWorkspace(cwd);
+        return { workspace: { name: readDeclaration(located.tree, "").name, root: located.root }, at: null };
+    }
+    catch {
+        return { at: null };
+    }
+}
+function searchJson(query, source, matches, terms, ir, byId, liveFailures = [], extra = {}) {
+    const show = extra.show ?? [];
+    return {
+        query,
+        source: extra.env ? { ...source, env: extra.env } : source,
+        matches: matches.map((n) => {
+            const attrs = (n.attrs ?? {});
+            const physical = n.physicalId ?? attrs["physicalId"] ?? attrs["InstanceId"] ?? attrs["Id"];
+            return {
+                id: n.id,
+                displayId: bareId(n.id),
+                ...(n.kind ? { kind: n.kind } : {}),
+                ...(physical != null && typeof physical !== "object" ? { physicalId: String(physical) } : {}),
+                ...(typeof attrs["_unobserved"] === "string" ? { unobserved: attrs["_unobserved"] } : {}),
+                ...(show.length > 0 ? { show: Object.fromEntries(showValues(attrs, show)) } : {}),
+                paths: matchPaths(n, terms, ir, byId).map((p) => ({
+                    term: termText({ ...p.term, negated: false }),
+                    dir: p.term.dir ?? "out",
+                    hops: p.hops,
+                    ...(p.because ? { because: p.because } : {}),
+                })),
+            };
+        }),
+        ...(extra.provenance !== undefined ? { provenance: extra.provenance } : {}),
+        ...(extra.plannedCreates ? { plannedCreates: extra.plannedCreates } : {}),
+        ...(extra.capabilities ? { capabilities: extra.capabilities } : {}),
+        ...(liveFailures.length > 0 ? { liveFailures } : {}),
+        ...(extra.explain
+            ? {
+                explain: {
+                    universe: extra.explain.universe,
+                    evidence: extra.explain.evidence,
+                    nearMisses: extra.explain.nearMisses.map((m) => ({ id: m.id, ...(m.term ? { fails: termText(m.term) } : {}) })),
+                    moreExcluded: extra.explain.moreExcluded,
+                },
+            }
+            : {}),
+        ...(extra.drift ? { drift: extra.drift } : {}),
+    };
+}
+/** A term as the query grammar spells it, `!` and ASCII arrows included (#4367). */
+function termText(t) {
+    if (t.negated)
+        return `!${termText({ ...t, negated: false })}`;
+    if (t.kind === "edge")
+        return `${edgeOperator(t, { out: "->", in: "<-" })}${t.sub ? leafText(t.sub) : ""}`;
+    return leafText(t);
 }
 /**
  * Decide which kinds a `kind:` term means, given what is in the graph.
@@ -730,14 +1311,28 @@ function describeTerm(t) {
  * Substring is kept as the fallback, so `kind:Gateway` still finds both
  * `InternetGateway` and `VPCGatewayAttachment` — a genuine substring search
  * that no segment rule would serve. Most specific wins; nothing else changes.
+ *
+ * A terraform resource is `Terraform::Resource` whatever it is, so the term is
+ * also read against each resource's type (#4366), with the same boundary rule
+ * on `_`: `kind:aws_iam_role` means that type exactly and never
+ * `aws_iam_role_policy`, and a term ending in `_` (`kind:aws_iam_`) or a bare
+ * provider name (`kind:aws`) means every type it begins. A data source's type
+ * keeps its `data.` prefix (`kind:data.aws_ami`), the same type `--count-by kind`
+ * groups it under, so `kind:aws_ami` is not a data source. A term that names a
+ * type turns off the substring fallback for the IR kind, so `kind:aws_instance`
+ * is the instances and nothing found by accident.
  */
 export function resolveKindTerms(terms, nodes) {
     const present = [...new Set(nodes.map((n) => n.kind).filter((k) => !!k))];
+    const tfPresent = [...new Set(nodes.map(terraformType).filter((k) => !!k))];
     const walk = (t) => {
         if (t.sub)
             walk(t.sub);
         if (t.kind !== "kind")
             return;
+        const types = resolveTerraformTypes(t.a, tfPresent);
+        if (types.length > 0)
+            t.tfTypes = new Set(types);
         const want = t.a.toLowerCase().split("::").filter(Boolean);
         if (want.length === 0)
             return;
@@ -754,7 +1349,29 @@ export function resolveKindTerms(terms, nodes) {
     };
     terms.forEach(walk);
 }
+/** The terraform resource types a `kind:` term names, by the rule in {@link resolveKindTerms}. */
+function resolveTerraformTypes(term, present) {
+    const want = term.toLowerCase();
+    if (want.length === 0 || want.includes("::"))
+        return [];
+    const exact = present.filter((p) => p === want);
+    if (exact.length > 0)
+        return exact;
+    const prefix = want.endsWith("_") || want.endsWith(".") ? want : /[_.]/.test(want) ? undefined : `${want}_`;
+    return prefix ? present.filter((p) => p.startsWith(prefix)) : [];
+}
+/** What a row and `--explain` call a node's kind: a terraform block's type (#4366), else its IR kind. Same as `--count-by kind`. */
+function displayKind(n) {
+    return terraformType(n) ?? n.kind;
+}
 function parseLeaf(tok) {
+    const cap = /^cap:(.*)$/i.exec(tok);
+    if (cap) {
+        if (!parseCapabilityCall(cap[1])) {
+            throw new QueryError(`"${tok}" is not a capability term`, "name a capability, with arguments in parentheses when it takes any: cap:internet-reachable, cap:open-ingress(22); chant search --capabilities lists them");
+        }
+        return { kind: "cap", a: cap[1] };
+    }
     const m = /^(kind|tag|attr):(.*)$/i.exec(tok);
     if (m) {
         const key = m[1].toLowerCase();
@@ -789,6 +1406,69 @@ class QueryError extends Error {
         this.hint = hint;
     }
 }
+/**
+ * Parse an edge term (#4359): `->` or `<-`, then an optional depth, then an
+ * optional attribute qualifier, then the target leaf.
+ *
+ *   ->kind:X                one hop, as it always was
+ *   ->*kind:X               any number of hops, one or more
+ *   ->{3}kind:X             exactly three hops
+ *   ->{1,3}kind:X           one to three hops ({2,} is two or more)
+ *   <-[via=vpc_id]kind:X    only edges through the consumer attribute vpc_id
+ *   ->[to=id]kind:X         only edges that read the producer attribute id
+ *   <-*[via=subnet_id]      a qualifier may stand without a target: any node
+ *
+ * A qualifier constrains every edge on the path, not only the first one.
+ */
+function parseEdge(tok, negated) {
+    const dir = tok.startsWith("->") ? "out" : "in";
+    const arrow = tok.slice(0, 2);
+    let rest = tok.slice(2);
+    const term = { kind: "edge", a: "", dir };
+    if (rest.startsWith("*")) {
+        term.depth = { min: 1, max: Infinity };
+        rest = rest.slice(1);
+    }
+    else if (rest.startsWith("{")) {
+        const m = /^\{(\d+)(,(\d*))?\}/.exec(rest);
+        const min = m ? Number(m[1]) : NaN;
+        const max = !m ? NaN : m[2] === undefined ? min : m[3] === "" ? Infinity : Number(m[3]);
+        if (!m || min < 1 || max < min) {
+            throw new QueryError(`"${tok}" has a depth this grammar cannot read`, `a depth is {n}, {min,max} or {min,} with 1 <= min <= max, e.g. ${arrow}{1,3}kind:aws_vpc; ${arrow}* is any depth`);
+        }
+        term.depth = { min, max };
+        rest = rest.slice(m[0].length);
+    }
+    if (rest.startsWith("[")) {
+        const close = rest.indexOf("]");
+        // Split on commas outside parentheses, so `[cap=open-ingress(22,tcp)]` is one part.
+        const parts = close < 0 ? [""] : (rest.slice(1, close).match(/(?:[^,(]|\([^)]*\))+/g) ?? [""]).map((p) => p.trim());
+        for (const part of parts) {
+            const c = /^cap=(.+)$/.exec(part);
+            if (c && parseCapabilityCall(c[1])) {
+                term.capability = c[1];
+                continue;
+            }
+            const q = /^(via|to)=(.+)$/.exec(part);
+            if (!q) {
+                throw new QueryError(`"${tok}" has an edge qualifier this grammar cannot read`, `qualify an edge by attribute with [via=<consumer attr>] or [to=<producer attr>], e.g. <-[via=vpc_id]kind:aws_subnet or ->[via=subnet_id,to=id], or walk a capability with [cap=<name>], e.g. ->[cap=reaches]cap:stores-data`);
+            }
+            if (q[1] === "via")
+                term.viaAttr = q[2];
+            else
+                term.toAttr = q[2];
+        }
+        rest = rest.slice(close + 1);
+    }
+    if (rest.trim() === "") {
+        if (term.viaAttr === undefined && term.toAttr === undefined && term.capability === undefined) {
+            const bang = negated ? "!" : "";
+            throw new QueryError(`"${bang}${tok}" needs a target`, `say what the edge reaches: ${bang}${tok}kind:EC2::Instance, or qualify it by attribute: ${bang}${tok}[via=vpc_id]`);
+        }
+        return term;
+    }
+    return { ...term, sub: parseLeaf(rest) };
+}
 function parseQuery(query) {
     // Split on whitespace but keep quoted phrases together.
     const tokens = query.match(/"[^"]*"|\S+/g) ?? [];
@@ -827,11 +1507,7 @@ function parseQuery(query) {
         if (/^(->|<-)\s*$/.test(tok)) {
             throw new QueryError(`"${negated ? "!" : ""}${tok}" needs a target`, `say what the edge reaches: ${negated ? "!" : ""}${tok}kind:EC2::Instance, or ${negated ? "!" : ""}${tok}attr:Name=web`);
         }
-        const term = tok.startsWith("->")
-            ? { kind: "edge", a: "", dir: "out", sub: parseLeaf(tok.slice(2)) }
-            : tok.startsWith("<-")
-                ? { kind: "edge", a: "", dir: "in", sub: parseLeaf(tok.slice(2)) }
-                : parseLeaf(tok);
+        const term = tok.startsWith("->") || tok.startsWith("<-") ? parseEdge(tok, negated) : parseLeaf(tok);
         return negated ? { ...term, negated: true } : term;
     });
 }
@@ -847,12 +1523,30 @@ function attrString(v) {
     }
     return String(v);
 }
+/**
+ * Attributes a bare word does not search, by lexicon (#4368). A terraform
+ * node's `source` is the whole `.tf` file its block came from (the lint
+ * checks need the raw text), so a bare `aws_security_group` matched every
+ * node declared in a file that mentions one: 21 nodes on behold's example
+ * estate, where three are security groups. The block itself is still
+ * searched, through `address` and `body`, and `attr:source=<text>` still
+ * reads the file when that is what the caller means.
+ */
+const BARE_WORD_SKIPS = {
+    terraform: new Set(["source"]),
+};
 function matchTerm(n, t, ir, byId) {
     if (t.negated)
         return !matchTerm(n, { ...t, negated: false }, ir, byId);
     const attrs = n.attrs ?? {};
     if (t.kind === "edge") {
-        if (!ir || !byId || !t.sub)
+        if (!ir || !byId)
+            return false;
+        // Depth and attribute qualifiers (#4359) go through the path search. A
+        // plain one-hop term keeps the original code below, unchanged.
+        if (t.depth || t.viaAttr !== undefined || t.toAttr !== undefined || t.capability !== undefined)
+            return findPath(n, t, ir, byId) !== null;
+        if (!t.sub)
             return false;
         // A node matches if it has an edge (out or in) to a node satisfying `sub`.
         const edges = ir.edges ?? [];
@@ -862,11 +1556,18 @@ function matchTerm(n, t, ir, byId) {
             .filter((x) => !!x);
         return neighbors.some((m) => matchTerm(m, t.sub, ir, byId));
     }
+    if (t.kind === "cap")
+        return !!ir && capabilityEvidence(n, t, ir) !== undefined;
     if (t.kind === "kind") {
         // Resolved kinds when the term lined up with `::` boundaries; the
-        // documented substring otherwise.
+        // documented substring otherwise. A term that named a terraform type
+        // (#4366) matches resources of that type as well, and drops the substring.
+        if (t.tfTypes?.has(terraformType(n) ?? ""))
+            return true;
         if (t.kinds)
             return t.kinds.has(n.kind ?? "");
+        if (t.tfTypes)
+            return false;
         return (n.kind ?? "").toLowerCase().includes(t.a.toLowerCase());
     }
     if (t.kind === "attr") {
@@ -883,15 +1584,213 @@ function matchTerm(n, t, ir, byId) {
             return key.toLowerCase() === t.a.toLowerCase() && (t.b === undefined || val.toLowerCase().includes(t.b.toLowerCase()));
         });
     }
-    // bare word: substring over id, kind, and all attr values
-    const hay = [n.id, n.kind, ...Object.values(attrs).map(attrString)].join(" ").toLowerCase();
+    // bare word: substring over id, kind, and all attr values, less the ones
+    // that hold text about other nodes (see BARE_WORD_SKIPS).
+    const skip = BARE_WORD_SKIPS[n.lexicon];
+    const values = Object.entries(attrs)
+        .filter(([k]) => !skip?.has(k))
+        .map(([, v]) => attrString(v));
+    const hay = [n.id, n.kind, ...values].join(" ").toLowerCase();
     return hay.includes(t.a.toLowerCase());
 }
+const adjacency = new WeakMap();
+function edgeIndex(ir) {
+    let idx = adjacency.get(ir);
+    if (!idx) {
+        idx = { out: new Map(), in: new Map() };
+        for (const e of ir.edges ?? []) {
+            if (!idx.out.has(e.from))
+                idx.out.set(e.from, []);
+            idx.out.get(e.from).push(e);
+            if (!idx.in.has(e.to))
+                idx.in.set(e.to, []);
+            idx.in.get(e.to).push(e);
+        }
+        adjacency.set(ir, idx);
+    }
+    return idx;
+}
+function sameName(a, b) {
+    return a !== undefined && a.toLowerCase() === b.toLowerCase();
+}
+/**
+ * The shortest path by which an edge term reaches `n` (#4359), or null.
+ *
+ * Breadth-first over the edges in the term's direction, keeping only edges
+ * whose attributes satisfy its qualifier, and accepting a node that satisfies
+ * the target leaf (any node when the term has none) at a depth inside the
+ * term's range. A plain `->`/`<-` is the range 1..1.
+ *
+ * Termination on a cycle: a state is (node, depth capped at the range's
+ * minimum). Past the minimum, arriving at a node again by a longer walk can
+ * reach nothing the first arrival could not, so it is not queued twice. The
+ * state space is finite and the walk always ends.
+ */
+function findPath(n, t, ir, byId) {
+    if (t.kind !== "edge")
+        return null;
+    const { min, max } = t.depth ?? { min: 1, max: 1 };
+    const idx = edgeIndex(ir);
+    const out = t.dir === "out";
+    // A capability edge (#4375) stands for the hops that proved it.
+    const steps = (id) => {
+        if (t.capability !== undefined)
+            return capabilitySteps(id, t.capability, out, ir);
+        return (((out ? idx.out.get(id) : idx.in.get(id)) ?? [])
+            .filter((e) => (t.viaAttr === undefined || sameName(e.viaAttr, t.viaAttr)) && (t.toAttr === undefined || sameName(e.toAttr, t.toAttr)))
+            .map((e) => ({
+            far: out ? e.to : e.from,
+            hops: [{ from: e.from, ...(e.viaAttr ? { fromAttr: e.viaAttr } : {}), to: e.to, ...(e.toAttr ? { toAttr: e.toAttr } : {}) }],
+        })));
+    };
+    const seen = new Set([`${n.id}|0`]);
+    let frontier = [{ id: n.id, depth: 0, hops: [] }];
+    while (frontier.length > 0) {
+        const next = [];
+        for (const s of frontier) {
+            if (s.depth >= max)
+                continue;
+            for (const step of steps(s.id)) {
+                const farId = step.far;
+                const far = byId.get(farId);
+                if (!far)
+                    continue;
+                const depth = s.depth + 1;
+                const hops = [...s.hops, ...step.hops];
+                if (depth >= min && (!t.sub || matchTerm(far, t.sub, ir, byId)))
+                    return hops;
+                const key = `${farId}|${Math.min(depth, min)}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                next.push({ id: farId, depth, hops });
+            }
+        }
+        frontier = next;
+    }
+    return null;
+}
+function bareId(id) {
+    return id.includes("::") ? id.slice(id.lastIndexOf("::") + 2) : id;
+}
+/**
+ * A path as one line of `id.attr` steps, read from the match outward (#4359).
+ * Walking `->`, each hop reads `consumer.via -> producer.attr`; walking `<-`,
+ * `producer.attr <- consumer.via`. Hops are joined with `; `.
+ */
+function formatPath(hops, dir) {
+    const end = (id, attr) => (attr ? `${bareId(id)}.${attr}` : bareId(id));
+    return hops
+        .map((h) => dir === "out"
+        ? `${end(h.from, h.fromAttr)} -> ${end(h.to, h.toAttr)}`
+        : `${end(h.to, h.toAttr)} <- ${end(h.from, h.fromAttr)}`)
+        .join("; ");
+}
+/** The edge operator as written: arrow, depth and qualifier, no target. */
+function edgeOperator(t, arrows) {
+    const arrow = t.dir === "out" ? arrows.out : arrows.in;
+    const depth = !t.depth
+        ? ""
+        : t.depth.min === 1 && t.depth.max === Infinity
+            ? "*"
+            : t.depth.min === t.depth.max
+                ? `{${t.depth.min}}`
+                : `{${t.depth.min},${t.depth.max === Infinity ? "" : t.depth.max}}`;
+    const quals = [
+        ...(t.viaAttr !== undefined ? [`via=${t.viaAttr}`] : []),
+        ...(t.toAttr !== undefined ? [`to=${t.toAttr}`] : []),
+        ...(t.capability !== undefined ? [`cap=${t.capability}`] : []),
+    ];
+    return `${arrow}${depth}${quals.length > 0 ? `[${quals.join(",")}]` : ""}`;
+}
+/** Each positive edge term's path to `n`, in query order (#4359). */
+function matchPaths(n, terms, ir, byId) {
+    const out = [];
+    for (const t of terms) {
+        if (t.negated)
+            continue;
+        if (t.kind === "cap") {
+            const ev = capabilityEvidence(n, t, ir);
+            if (ev)
+                out.push({ term: t, hops: ev.hops.map(pathHop), because: becauseOf(ev) });
+            continue;
+        }
+        if (t.kind !== "edge")
+            continue;
+        const hops = findPath(n, t, ir, byId);
+        if (hops)
+            out.push({ term: t, hops });
+    }
+    return out;
+}
+/**
+ * The evidence for a `cap:` term on a node (#4375): its path when the node
+ * is in the set, or the source of an edge capability, else undefined. A
+ * capability or argument the catalog can't take throws a CapabilityError,
+ * which `runSearch` turns into a refusal before any node is tested.
+ */
+function capabilityEvidence(n, t, ir) {
+    const call = parseCapabilityCall(t.a);
+    if (!call)
+        return undefined;
+    const engine = capabilityEngine(ir);
+    const args = engine.bind(call.name, call.args);
+    if (engine.rule(call.name).vars.length === 1)
+        return engine.set(call.name, args).get(n.id);
+    const targets = engine.relation(call.name, args).out.get(n.id);
+    return targets ? targets.values().next().value : undefined;
+}
+/** One step along an edge capability from `id` (#4375), each with the hops that proved it, in walk order. */
+function capabilitySteps(id, call, out, ir) {
+    const parsed = parseCapabilityCall(call);
+    if (!parsed)
+        return [];
+    const engine = capabilityEngine(ir);
+    const rel = engine.relation(parsed.name, engine.bind(parsed.name, parsed.args));
+    const m = (out ? rel.out : rel.in).get(id);
+    if (!m)
+        return [];
+    return [...m].map(([far, ev]) => ({ far, hops: (out ? ev.hops : [...ev.hops].reverse()).map(pathHop) }));
+}
+function pathHop(h) {
+    return { from: h.from, ...(h.fromAttr ? { fromAttr: h.fromAttr } : {}), to: h.to, ...(h.toAttr ? { toAttr: h.toAttr } : {}), edge: h.edge };
+}
+function becauseOf(ev) {
+    const out = [];
+    const walk = (e) => {
+        for (const b of e.because) {
+            out.push({ capability: b.capability, id: b.id, hops: b.evidence.hops.map(pathHop) });
+            walk(b.evidence);
+        }
+    };
+    walk(ev);
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * A capability's path as one line (#4375), in #4359's hop format, read from
+ * `start`: each hop is `consumer.via -> producer.attr` when the walk follows
+ * the reference, `producer.attr <- consumer.via` when it goes against it. A
+ * hop with no IR attribute names the capability edge instead (`-statement->`).
+ */
+function formatHops(hops, start) {
+    const end = (id, attr) => (attr ? `${bareId(id)}.${attr}` : bareId(id));
+    let at = start;
+    return hops
+        .map((h) => {
+        const forward = h.from === at || h.to !== at;
+        at = forward ? h.to : h.from;
+        return forward
+            ? `${end(h.from, h.fromAttr)} -> ${end(h.to, h.toAttr)}`
+            : `${end(h.to, h.toAttr)} <- ${end(h.from, h.fromAttr)}`;
+    })
+        .join("; ");
+}
 function formatRow(n, show) {
     const attrs = (n.attrs ?? {});
     // Display the bare logical id, not the `${stack}::` qualification (#1162).
     const displayId = n.id.includes("::") ? n.id.slice(n.id.lastIndexOf("::") + 2) : n.id;
-    const parts = [displayId, n.kind ?? ""];
+    // A terraform resource shows its type (#4366); its IR kind is `Terraform::Resource` for all of them.
+    const parts = [displayId, displayKind(n) ?? ""];
     // Prefer the node-level live physicalId (set by the overlay), then attrs;
     // skip source-mode AttrRef placeholders (objects).
     const physical = n.physicalId ?? attrs["physicalId"] ?? attrs["InstanceId"] ?? attrs["Id"];
@@ -902,6 +1801,23 @@ function formatRow(n, show) {
     // established; the reason is the tri-state's (#1089).
     else if (typeof attrs["_unobserved"] === "string")
         parts.push(`(unobserved: ${attrs["_unobserved"]})`);
+    for (const [actual, v] of showValues(attrs, show)) {
+        // A column the caller explicitly asked for is shown whatever shape it is.
+        // Skipping non-scalars silently meant `--show effectiveIngress` — the
+        // derived reachability fact, and the reason to reach for chant at all —
+        // printed a blank column, because it is a list. The agent read that as
+        // "chant does not have this" and hand-rolled the answer from raw
+        // security-group rows, which is exactly the work the fold exists to avoid.
+        parts.push(`${actual}=${typeof v === "object" ? JSON.stringify(v) : attrString(v)}`);
+    }
+    return parts.filter(Boolean).join("  ");
+}
+/**
+ * The `--show` columns a row carries, as `[name as the graph spells it, value]`,
+ * in the order asked. Shared by the text row and `--json` (#4367).
+ */
+function showValues(attrs, show) {
+    const out = [];
     for (const key of show) {
         // Match the name case-insensitively, and report what was actually found.
         // AWS attribute names are PascalCase and chant's derived ones are not, so a
@@ -912,15 +1828,9 @@ function formatRow(n, show) {
         const v = actual == null ? undefined : attrs[actual];
         if (v == null)
             continue;
-        // A column the caller explicitly asked for is shown whatever shape it is.
-        // Skipping non-scalars silently meant `--show effectiveIngress` — the
-        // derived reachability fact, and the reason to reach for chant at all —
-        // printed a blank column, because it is a list. The agent read that as
-        // "chant does not have this" and hand-rolled the answer from raw
-        // security-group rows, which is exactly the work the fold exists to avoid.
-        parts.push(`${actual}=${typeof v === "object" ? JSON.stringify(v) : attrString(v)}`);
+        out.push([actual, v]);
     }
-    return parts.filter(Boolean).join("  ");
+    return out;
 }
 /** Internals exposed for unit tests. */
-export const __searchInternals = { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs, ambientHint, regionSpread, showMiss, provenance, renderDrift, mergeResources, pickResources };
+export const __searchInternals = { parseQuery, matchTerm, findPath, formatPath, searchJson, searchErrorJson, explainData, termText, formatRow, explain, describeTerm, derivedSurface, availableAttrs, ambientHint, regionSpread, showMiss, provenance, provenanceLine, renderDrift, searchDriftJson, mergeResources, pickResources };