@intentius/chant 0.124.52 → 0.124.54

package/dist/cli/handlers/search.js

@@ -19,6 +19,8 @@ import { parseCountBy, countGroups, countsJson, formatCounts, groupMembers, hasM
 import { formatError, formatWarning } from "../format.js";
 import { adjacencyOf, walkBreadthFirst } from "../../graph-walk.js";
 import { SEARCH_CONTRACT_VERSION, SEARCH_OUTPUT_SCHEMA_ID } from "../../workspace/search-contract.js";
+import { isNoLexiconDetected } from "../../detectLexicon.js";
+import { countJoins, formatIndexRef, indexOnlyGraph, joinCell, joinDeclaredToIndex, parseIndexRef, readIndexRef, } from "../../lifecycle/index-join.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,
@@ -31,11 +33,17 @@ import { SEARCH_CONTRACT_VERSION, SEARCH_OUTPUT_SCHEMA_ID } from "../../workspac
  *                        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>
+ *   id:<cloud id>        physicalId or an engine cloudIds value is exactly <cloud id> (#4534)
  *   ->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
  *
+ * `--index <ref>` (#4525) answers from an index version in the store instead
+ * of a live read: the declared rows joined to it through each lexicon's index
+ * match, each row with its verdict, or, with no project, the index alone.
+ * See ../../lifecycle/index-join.ts.
+ *
  * 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
  * query does the traversal. `kind:Instance ->attr:MapPublicIpOnLaunch=true`
@@ -82,6 +90,10 @@ export async function runSearch(ctx) {
     const { config } = await loadChantConfig(projectPath);
     let ir;
     let source = { kind: "declared" };
+    // Each declared row's join verdict against an index version (#4525).
+    let joins;
+    // The lexicons a capability term reads an index-only graph through.
+    let indexPlugins;
     // Lexicons whose live read threw (#1263). "Nothing observed" and "could not
     // observe" are different claims; this is what carries the second one.
     const liveFailures = [];
@@ -107,7 +119,16 @@ export async function runSearch(ctx) {
     let driftFailure = false;
     // Why --check-snapshot had nothing to check against, for --json (#4367).
     let driftUnavailable;
-    if (args.live || snapshotRef) {
+    if (args.index !== undefined) {
+        const answered = await indexAnswer(ctx, String(args.index), projectPath, resolve(args.src ?? config.sourceDir ?? "."), config);
+        if ("error" in answered)
+            return refuse(answered.error);
+        ir = answered.ir;
+        source = answered.source;
+        joins = answered.joins;
+        indexPlugins = answered.plugins;
+    }
+    else if (args.live || snapshotRef) {
         // checkSearchArgs refused a live or snapshot read without one.
         const environment = String(args.env);
         // Membership via matchesDeclaredEnvironment (#1221): handles `{ name,
@@ -328,7 +349,7 @@ export async function runSearch(ctx) {
     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);
+        const refused = await bindCapabilities(ctx, projectPath, ir, terms, indexPlugins);
         if (refused)
             return refuse({ code: "query-invalid", ...refused });
     }
@@ -366,10 +387,10 @@ 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;
-        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 env = args.env && (source.kind === "live" || source.kind === "snapshot") ? String(args.env) : undefined;
+        const provenanceText = provenanceLine(matches, source, recorded, liveFailures, [...derivedUsed(terms, matches, ir), ...capabilitiesUsed(terms)], joins).replace(/^— /, "");
         const capNotes = capabilityNotes(terms, ir, source);
-        const plannedCreates = source.kind !== "declared" && liveFailures.length === 0 ? plannedCreateCount(matches) : 0;
+        const plannedCreates = (source.kind === "live" || source.kind === "snapshot") && liveFailures.length === 0 ? plannedCreateCount(matches) : 0;
         const driftJson = drift
             ? searchDriftJson(drift, matches.length, driftAgainst, snapshotDepth)
             : driftUnavailable !== undefined
@@ -397,6 +418,7 @@ export async function runSearch(ctx) {
                     ...(capNotes.length > 0 ? { capabilities: capNotes } : {}),
                     ...(args.explain ? { explain: explainData(terms, matches, ir, nodeById) } : {}),
                     ...(driftJson ? { drift: driftJson } : {}),
+                    ...(joins ? { joins } : {}),
                 }),
             };
         console.log(JSON.stringify(payload));
@@ -408,6 +430,9 @@ export async function runSearch(ctx) {
     }
     if (matches.length === 0) {
         console.log(countBy ? "(no matches) · 0 total" : "(no matches)");
+        // An index answer names the version it read, rows or not (#4525).
+        if (source.kind === "index")
+            provenance(matches, source, undefined, [], [], joins);
         availableAttrs(terms, ir);
         if (args.explain)
             explain(terms, matches, ir, nodeById, query);
@@ -421,7 +446,7 @@ export async function runSearch(ctx) {
     }
     else {
         for (const n of matches) {
-            console.log(formatRow(n, show));
+            console.log(formatRow(n, show, joins?.[n.id]));
         }
     }
     const backed = source.kind === "declared" || matches.some((n) => n.physicalId);
@@ -430,7 +455,7 @@ 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, [...derivedUsed(terms, matches, ir), ...capabilitiesUsed(terms)]);
+    provenance(matches, source, recorded, liveFailures, [...derivedUsed(terms, matches, ir), ...capabilitiesUsed(terms)], joins);
     for (const c of capabilityNotes(terms, ir, source)) {
         if (c.notEvaluated.length > 0)
             console.log(`— ${c.name} does not evaluate: ${c.notEvaluated.join("; ")}`);
@@ -531,6 +556,23 @@ export function checkSearchArgs(args, query, snapshot) {
             },
         };
     }
+    // An index version (#4525) is a third observation, so it excludes the other
+    // two, and a live read's own flags mean nothing against it.
+    if (args.index !== undefined) {
+        const other = args.live ? "--live" : snapshot.ref ? flag : args.ambient ? "--ambient" : undefined;
+        if (other) {
+            return {
+                error: {
+                    code: "usage-invalid",
+                    message: `chant search takes --index or ${other}, not both`,
+                    hint: "--index answers from an index version in the store; --live reads the estate now; a snapshot replays a chant recording",
+                },
+            };
+        }
+        const ref = parseIndexRef(args.index);
+        if ("error" in ref)
+            return { error: { code: "usage-invalid", message: ref.error, hint: ref.hint } };
+    }
     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>` } };
@@ -554,6 +596,69 @@ const BUILD_ROOT_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",
 };
+/**
+ * Read the index version `--index` names from the project's store and build
+ * the graph the query runs over (#4525). With a project: the declared canvas
+ * `--live` would use (per stack when the config declares stacks, so ids
+ * match), every node joined to the index through its lexicon's index match.
+ * With no project (no lexicon in a config or in source): the index alone.
+ * No cloud is read either way.
+ */
+async function indexAnswer(ctx, refText, projectPath, srcDir, config) {
+    const ref = parseIndexRef(refText);
+    if ("error" in ref)
+        return { error: { code: "usage-invalid", message: ref.error, hint: ref.hint } };
+    const { resolveSnapshotStore } = await import("../../lifecycle/snapshot-store.js");
+    const store = await resolveSnapshotStore({ cwd: projectPath, config: config });
+    await store.fetch();
+    const read = await readIndexRef(store, ref);
+    if ("error" in read)
+        return { error: { code: "index-unavailable", message: read.error, ...(read.hint ? { hint: read.hint } : {}) } };
+    const { doc } = read;
+    const { stamp } = doc;
+    const base = {
+        kind: "index",
+        index: formatIndexRef(stamp.scopeKey, read.version),
+        scopeKey: stamp.scopeKey,
+        version: read.version.replace(/\.json$/, ""),
+        observedAt: stamp.observedAt,
+        ...(stamp.completedAt ? { completedAt: stamp.completedAt } : {}),
+        digest: stamp.digest,
+        by: stamp.source.version ? `${stamp.source.name} ${stamp.source.version}` : stamp.source.name,
+    };
+    let lexicons;
+    try {
+        lexicons = await resolveProjectLexicons(projectPath);
+    }
+    catch (err) {
+        if (!isNoLexiconDetected(err))
+            throw err;
+    }
+    if (!lexicons) {
+        // No project: the index is the graph. Its nodes' lexicons, where they are
+        // installed, still map capability terms onto it.
+        const named = [...new Set(doc.graph.nodes.filter((n) => !n.unmappedKind).map((n) => n.lexicon))].sort();
+        let plugins = [];
+        try {
+            plugins = named.length > 0 ? await loadPlugins(named) : [];
+        }
+        catch {
+            plugins = [];
+        }
+        return { ir: indexOnlyGraph(doc), source: { ...base, project: false }, plugins };
+    }
+    const plugins = ctx.plugins.length > 0 ? ctx.plugins : await loadPlugins(lexicons);
+    const stacks = (config.stacks ?? []).map((s) => ({ name: s.name, region: s.region, src: s.src }));
+    const declared = stacks.length > 0
+        ? await buildDeclaredPerStack(stacks, projectPath, (g, entities) => withLexiconEdges(g, plugins, entities))
+        : await declaredGraph(ctx, projectPath, srcDir, plugins);
+    if (!declared)
+        return { error: BUILD_ROOT_FAILED };
+    const joined = joinDeclaredToIndex(declared, doc, plugins, {
+        regionOf: (id) => stacks.find((st) => id.startsWith(`${st.name}::`))?.region,
+    });
+    return { ir: joined.ir, source: { ...base, project: true }, joins: joined.joins };
+}
 /**
  * The declared graph a search answers over (#4362, #4365, #4368): discovery,
  * plus the build-root entities (a terraform root's blocks, a rendered
@@ -594,7 +699,7 @@ export async function printCapabilities(args, query, lexicons) {
     const extra = [
         // `args.path` is "." when no query was given.
         ...(query && query !== "." ? [`the query "${query}"`] : []),
-        ...["live", "env", "snapshot", "at", "countBy", "explain", "show"]
+        ...["live", "env", "snapshot", "at", "index", "countBy", "explain", "show"]
             .filter((k) => args[k] !== undefined && args[k] !== false)
             .map((k) => `--${k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`),
     ];
@@ -690,8 +795,8 @@ export function usesCapability(t) {
  * 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;
+async function bindCapabilities(ctx, projectPath, ir, terms, given) {
+    let plugins = given ?? ctx.plugins;
     if (plugins.length === 0) {
         try {
             plugins = await loadPlugins(await resolveProjectLexicons(projectPath));
@@ -877,7 +982,9 @@ 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 provenanceLine(matches, source, recorded, liveFailures = [], derived = []) {
+function provenanceLine(matches, source, recorded, liveFailures = [], derived = [], joins) {
+    if (source.kind === "index")
+        return indexProvenance(matches, source, joins);
     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;
@@ -890,6 +997,22 @@ function fellBackText(source) {
     const to = source.planFellBackTo === "live" ? "live-plan alone" : source.planFellBackTo;
     return ` · the plan read fell back to ${to}`;
 }
+/**
+ * The provenance line of an `--index` answer (#4525): the version read and
+ * when, then how the declared rows joined, every verdict counted, so a row
+ * that did not bind is never read as one that did.
+ */
+function indexProvenance(matches, source, joins) {
+    const taken = `taken ${source.observedAt}`;
+    if (!source.project) {
+        return `— index only, no project · ${source.index} ${taken} by ${source.by} · ${matches.length} ${matches.length === 1 ? "row" : "rows"}`;
+    }
+    const counts = countJoins(joins ?? {}, matches.map((n) => n.id));
+    const rest = ["absent", "not-observed", "no-binding", "ambiguous"]
+        .filter((v) => counts[v] > 0)
+        .map((v) => `${v === "not-observed" ? "not observed" : v} ${counts[v]}`);
+    return `— observed from index ${source.index} ${taken} · bound ${counts.bound}/${matches.length}${rest.length > 0 ? ` · ${rest.join(" · ")}` : ""}`;
+}
 function provenanceBase(matches, source, recorded, liveFailures = [], derived = []) {
     if (source.kind === "declared") {
         // A derived fact the query relied on (#4362) was folded from declared
@@ -897,6 +1020,8 @@ function provenanceBase(matches, source, recorded, liveFailures = [], derived =
         const from = derived.length > 0 ? ` · ${derived.join(", ")} derived from declared references` : "";
         return `— declared only · no observation · physical ids unavailable${from}`;
     }
+    if (source.kind === "index")
+        return indexProvenance(matches, source);
     const bound = matches.filter((n) => n.physicalId).length;
     const what = source.kind === "live" ? "live read" : "snapshot";
     if (liveFailures.length > 0) {
@@ -952,8 +1077,8 @@ function plannedCreateCount(matches) {
     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));
+function provenance(matches, source, recorded, liveFailures = [], derived = [], joins) {
+    console.log(provenanceLine(matches, source, recorded, liveFailures, derived, joins));
 }
 /** Union `LiveObservation.resources` across lexicons into one name-keyed map. */
 function mergeResources(observations) {
@@ -1218,7 +1343,7 @@ 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}"`;
+        : x.kind === "tag" ? `tag:${x.a}${x.b !== undefined ? "=" + x.b : ""}` : x.kind === "id" ? `id:${x.a}` : `"${x.a}"`;
 }
 function searchErrorJson(query, error) {
     return { ...searchHead(), query, error: { code: error.code, message: error.message, ...(error.hint ? { hint: error.hint } : {}) } };
@@ -1264,6 +1389,7 @@ function searchJson(query, source, matches, terms, ir, byId, liveFailures = [],
                     hops: p.hops,
                     ...(p.because ? { because: p.because } : {}),
                 })),
+                ...(extra.joins?.[n.id] ? { join: extra.joins[n.id] } : {}),
             };
         }),
         ...(extra.provenance !== undefined ? { provenance: extra.provenance } : {}),
@@ -1365,23 +1491,46 @@ function resolveTerraformTypes(term, present) {
 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();
-        const rest = m[2];
+/** `name` or `name=value` after a prefix. */
+function keyValueLeaf(kind) {
+    return (rest) => {
         const eq = rest.indexOf("=");
-        if (eq >= 0)
-            return { kind: key, a: rest.slice(0, eq), b: rest.slice(eq + 1) };
-        return { kind: key, a: rest };
-    }
+        return eq >= 0 ? { kind, a: rest.slice(0, eq), b: rest.slice(eq + 1) } : { kind, a: rest };
+    };
+}
+const LEAF_PREFIXES = [
+    { prefix: "kind", listed: true, parse: keyValueLeaf("kind") },
+    { prefix: "attr", listed: true, parse: keyValueLeaf("attr") },
+    { prefix: "tag", listed: true, parse: keyValueLeaf("tag") },
+    {
+        // `id:<cloud id>` (#4534, behold#906 Q3): the whole rest is the id, colons
+        // and `=` included, since an ARN has both.
+        prefix: "id",
+        listed: true,
+        parse: (rest, tok) => {
+            if (rest === "") {
+                throw new QueryError(`"${tok}" needs a cloud id`, "name the id exactly as the cloud prints it: id:i-0abc123, id:arn:aws:s3:::my-bucket");
+            }
+            return { kind: "id", a: rest };
+        },
+    },
+    {
+        prefix: "cap",
+        listed: false,
+        parse: (rest, tok) => {
+            if (!parseCapabilityCall(rest)) {
+                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: rest };
+        },
+    },
+];
+function parseLeaf(tok) {
+    // A prefix is matched case-insensitively, as it always was.
+    const prefixed = /^([A-Za-z][A-Za-z0-9_]*):(.*)$/.exec(tok);
+    const known = prefixed ? LEAF_PREFIXES.find((p) => p.prefix === prefixed[1].toLowerCase()) : undefined;
+    if (prefixed && known)
+        return known.parse(prefixed[2], tok);
     // `name:value` with a prefix the grammar does not have. This parsed as a
     // free-text word and matched nothing, which is the worst available outcome:
     // an agent looking for SSH reachability wrote
@@ -1396,7 +1545,8 @@ function parseLeaf(tok) {
     if (bad) {
         const name = bad[1];
         const value = tok.slice(name.length + 1);
-        throw new QueryError(`"${tok}" is not a term — there is no "${name}:" prefix`, `for an attribute, say attr:${name}=${value || "<value>"}; the prefixes are kind:, attr:, tag:, and ->/<- for edges`);
+        const prefixes = LEAF_PREFIXES.filter((p) => p.listed).map((p) => `${p.prefix}:`).join(", ");
+        throw new QueryError(`"${tok}" is not a term — there is no "${name}:" prefix`, `for an attribute, say attr:${name}=${value || "<value>"}; the prefixes are ${prefixes}, and ->/<- for edges`);
     }
     return { kind: "word", a: tok };
 }
@@ -1575,10 +1725,14 @@ function matchTerm(n, t, ir, byId) {
         const val = attrString(attrs[t.a]);
         return t.b === undefined ? t.a in attrs : val.toLowerCase().includes(t.b.toLowerCase());
     }
+    if (t.kind === "id")
+        return hasCloudId(n, t.a);
     if (t.kind === "tag") {
         const tags = attrs["Tags"];
-        if (!Array.isArray(tags))
-            return false;
+        if (!Array.isArray(tags)) {
+            // An indexed node keeps its tags as a map (#4521), not a Tags list.
+            return Object.entries(n.tags ?? {}).some(([key, val]) => key.toLowerCase() === t.a.toLowerCase() && (t.b === undefined || String(val).toLowerCase().includes(t.b.toLowerCase())));
+        }
         return tags.some((tag) => {
             const key = attrString(tag?.Key);
             const val = attrString(tag?.Value);
@@ -1594,6 +1748,18 @@ function matchTerm(n, t, ir, byId) {
     const hay = [n.id, n.kind, ...values].join(" ").toLowerCase();
     return hay.includes(t.a.toLowerCase());
 }
+/**
+ * Whether a node carries `id` as one of its cloud ids (#4534): its observed
+ * `physicalId`, or any value in its engine facts' `cloudIds` (an ARN, an
+ * import id, a self-link). The match is exact, case included: a cloud id is
+ * an identifier, and a substring of one names another object. A bare word
+ * never reads either field.
+ */
+function hasCloudId(n, id) {
+    if (n.physicalId === id)
+        return true;
+    return (n.facts?.cloudIds ?? []).some((c) => c.value === id);
+}
 const adjacency = new WeakMap();
 function edgeIndex(ir) {
     let idx = adjacency.get(ir);
@@ -1644,7 +1810,15 @@ function findPath(n, t, ir, byId) {
     });
     return found ? found.hops : null;
 }
+/**
+ * A cloud-listed node's path-style id (behold#1025 Q2,
+ * `<substrate>/<scopeId>/<location>/<listedType>/<nativeId>`), printed whole:
+ * its listed type holds `::`, which is not a stack qualification.
+ */
+const INDEX_NODE_ID = /^(aws|azure|gcp|kubernetes)\/[^/]+\/[^/]+\/[^/]+\/./;
 function bareId(id) {
+    if (INDEX_NODE_ID.test(id))
+        return id;
     return id.includes("::") ? id.slice(id.lastIndexOf("::") + 2) : id;
 }
 /**
@@ -1759,16 +1933,22 @@ function formatHops(hops, start) {
     })
         .join("; ");
 }
-function formatRow(n, show) {
+function formatRow(n, show, join) {
     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 displayId = bareId(n.id);
     // 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"];
-    if (physical != null && typeof physical !== "object")
+    // A row joined to an index (#4525) that did not bind says which verdict it
+    // got where the physical id would go: a declared InstanceId is not one the
+    // index confirmed.
+    const cell = join ? joinCell(join) : undefined;
+    if (cell)
+        parts.push(cell);
+    else if (physical != null && typeof physical !== "object")
         parts.push(String(physical));
     // A row nobody could read says so where its physical id would go (#1263). A
     // blank there reads as "declared, not provisioned", which the read never

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAKA,OAAO,EAAkB,KAAK,UAAU,EAAmB,MAAM,YAAY,CAAC;AAa9E,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAgB,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC;AA88CzC;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBzE;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,EAkOvC,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAKA,OAAO,EAAkB,KAAK,UAAU,EAAmB,MAAM,YAAY,CAAC;AAa9E,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAgB,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC;AA++CzC;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBzE;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,EAwOvC,CAAC"}

package/dist/cli/main.js

@@ -160,7 +160,9 @@ Commands:
                         terms, ->* / ->{1,3} for depth, ->[via=attr] / [to=attr]
                         by attribute; --live or --snapshot <ref> (also --at
                         <ref>) with --env <name> reads the estate or a
-                        recorded snapshot; --show <attr>,
+                        recorded snapshot; --index <scope key>[@<version>]
+                        answers from an index version, joined to the
+                        declared rows, or alone with no project; --show <attr>,
                         --count-by kind|module|attr:<name>, --explain prints
                         paths, --json, --check-live,
                         --check-snapshot, --fail-on-drift; cap:<name> and
@@ -178,6 +180,16 @@ Commands:
                         --where <field><op><value> (= != < <= > >= ~,
                         repeatable), --since <time|7d>, --at <rev> of
                         chant/lifecycle, --member <name>, --json
+  index <substrate>     Read one aws account, azure subscription, gcp project
+                        or kubernetes cluster through its inventory API, type
+                        it, derive its edges and write one index version to
+                        the index store. Read-only: refuses action flags.
+                        --account|--subscription|--project|--cluster, --regions,
+                        --types, --tag k=v, --endpoint, --store <spec>, --json
+                        (chant index --help for the rest)
+  index diff <a> [<b>]  What changed between two index versions of one scope:
+                        <scopeKey>/<version>, or <scopeKey> for its last two.
+                        --store <spec>, --json (chant index diff --help)
   generate             Generate typed code from sources chant.config declares
                         (k8s.crds, helm.charts) into src/generated/<lexicon>/
                         (codegen.outDir); --check exits 1 when the committed
@@ -611,6 +623,12 @@ Workspace (level 1, #2524):
                         choudoufu runs live-check and the adoption report;
                         choudoufu or other to chant runs chant import), staged
                         in a worktree and gated on the patch digest like upgrade
+  workspace promote --all [--state-dir <dir>] [--state <member>=<tfstate>]... [--canary <member>] [--wave-size <n>] [--dry-run] [--json]
+                        Adopt every terraform member into choudoufu in waves:
+                        the canary first (default the first member), then
+                        --wave-size roots a wave (default 5), one gate per
+                        root bound to its live-import report digest. A wave
+                        that does not land stops the later ones (#4461)
   workspace ls [dir]    List the declaration's members and example groups.
                         A member that can't be read is listed with a reason
                         code and still exits 0. --at <rev> reads a commit's
@@ -968,6 +986,15 @@ Workspace (level 1, #2524):
                         --no-cache reads every member
                         --capability-view: each member's chant adds its
                         capability view, mapped by its own lexicons
+  workspace drift --member <name> [--read <state|plan|refresh|live-read|ownership>] [--resource <addr>] [--env <name>] [--stream] [-o <file>]
+                        One member's drift, read by its own engine: a chant
+                        member through lifecycle diff --live (needs --env), a
+                        terraform member through its state or a plan, a
+                        choudoufu member through live-plan (and a plan for
+                        --read plan), one resource through choudoufu
+                        live-plan -resource. One drift document, or with
+                        --stream the NDJSON stream (drift-start, records,
+                        drift-settle)
   workspace search "<query>" [--member <name>] [--env <name>] [--snapshot <ref> | --live] [--at <rev>] [--explain] [--count-by ...] [--json]
                         chant search in every chant member, each under its own
                         chant, as one read-contract document: ids are
@@ -1025,6 +1052,8 @@ Lifecycle (alias: lc):
                             (lexicons with a deep reader also report
                             property-level drift; --update-baseline records
                             what it reports as accepted so it stops alerting)
+                            --index <ref>: compare source with an index version
+                            in the store, no deploy and no cloud read (#4526)
   lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
                             --deep: also report properties declared
                             heldElsewhere(). Never changes what the plan
@@ -1037,6 +1066,9 @@ Lifecycle (alias: lc):
                             drift: ECS running vs desired, Route 53 health
                             checks, Container Apps revisions, Cloud Run Ready.
                             A failed read is "not read", never unhealthy (--json)
+  lifecycle drift           Each lexicon's own drift read, as drift-record
+                            NDJSON (--member, --read, --resource); what
+                            workspace drift runs in a member's reader project
   lifecycle whoami <env>    Who chant would act as in each configured lexicon,
                             and what that principal is scoped to — read-only,
                             before anything acts (--json, --strict)
@@ -1341,6 +1373,7 @@ Examples:
   chant import manifest.yaml --lexicon k8s --output ./infra/
   chant import dash.json --lexicon grafana --parser-option acceptLossyV1
   chant import --from prod --name my-bucket --output src/
+  chant import --index index.json --type AWS::S3::Bucket --output src/imported/
   chant lint ./infra/
   chant lint ./infra/ --format sarif
   chant lint ./infra/ --watch
@@ -1547,6 +1580,10 @@ export const commandRegistry = [
     // #4297 — SQL over the snapshots, runs, gates, deploys and releases on chant/lifecycle. Imported on first use.
     { name: "query", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/query.js")).runQueryCommand(ctx) },
     { name: "ledger", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/ledger.js")).runLedgerCommand(ctx) },
+    // chant#4532 — a read-only cloud index. main() hands `index`'s raw argv to
+    // its own parser before parseArgs; this entry answers "is it a verb" and
+    // runs the words a caller already parsed (substrate, --json, --help).
+    { name: "index", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/index-cloud.js")).runIndexCommand(ctx) },
     // chant#2591 — `import --agents` and `audit` read chant.config statically
     // and never evaluate it (chant#2589 for audit, which audits code it must not run).
     { name: "import", handler: runImport, runsNoConfig: (args) => args.agents === true },
@@ -1680,6 +1717,7 @@ export const commandRegistry = [
     { name: "workspace run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/workspace-run.js")).runWorkspaceRun(ctx) },
     // #2554 — a release train: one release of every chant member, pinned in the workspace ledger.
     { name: "workspace train", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/release-train.js")).runWorkspaceTrain(ctx) },
+    { name: "workspace drift", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/drift-cli.js")).runWorkspaceDrift(ctx) },
     { name: "workspace search", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/search-cli.js")).runWorkspaceSearch(ctx) },
     // Each unit decides for itself whether its config is loaded (runCommandInProcess).
     { name: "workspace member-run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-run.js")).runWorkspaceMemberRun(ctx, runCommandInProcess) },
@@ -1707,6 +1745,7 @@ export const commandRegistry = [
     { name: "lifecycle rollback", handler: runLifecycleRollback },
     { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
     { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
+    { name: "lifecycle drift", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/lifecycle-drift.js")).runLifecycleDrift(ctx) },
     { name: "lifecycle whoami", requiresPlugins: true, handler: runLifecycleWhoami },
     // #4177 — runtime health, separate from drift. Imported on first use.
     { name: "lifecycle health", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/lifecycle-health.js")).runLifecycleHealth(ctx) },
@@ -1760,6 +1799,21 @@ async function main() {
     // something imports it. A no-op from source.
     installCompiledCli();
     const rawArgv = process.argv.slice(2);
+    // chant#4532 — `chant index <substrate>` takes its own flags (--account,
+    // --regions, --endpoint, ...) that core's one flat parser does not know, and
+    // must refuse an action flag (--apply, --yes, ...) that the parser would
+    // accept. So its argv goes to its own parser, before parseArgs.
+    if (rawArgv[0] === "index" && rawArgv[1] === "diff") {
+        // #4533 — `chant index diff <a> [<b>]`: two stored versions of one scope.
+        const { runIndexDiff } = await import("./handlers/index-diff.js");
+        await flushAndExit(await runIndexDiff(rawArgv.slice(2)));
+        return;
+    }
+    if (rawArgv[0] === "index") {
+        const { runCloudIndex } = await import("../lifecycle/cloud-index.js");
+        await flushAndExit(await runCloudIndex(rawArgv.slice(1)));
+        return;
+    }
     let args;
     try {
         args = parseArgs(rawArgv);

package/dist/cli/mcp/lifecycle-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle-tools.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/lifecycle-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3D,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,cAAc,CAAC;IAC3B,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,gBAAgB,CA6B7E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,gBAAgB,CAmCzE"}
+{"version":3,"file":"lifecycle-tools.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/lifecycle-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3D,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,cAAc,CAAC;IAC3B,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,gBAAgB,CA6B7E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,gBAAgB,CAoCzE"}

package/dist/cli/mcp/lifecycle-tools.js

@@ -1,5 +1,5 @@
 import { resolve } from "node:path";
-import { readSnapshot } from "../../lifecycle/git.js";
+import { resolveSnapshotStore } from "../../lifecycle/snapshot-store.js";
 import { build } from "../../build.js";
 import { computeBuildDigest, diffDigests } from "../../lifecycle/digest.js";
 import { takeSnapshot } from "../../lifecycle/snapshot.js";
@@ -65,8 +65,9 @@ export function createDiffTool(plugins) {
             const currentDigest = computeBuildDigest(buildResult);
             const lexicons = lexiconFilter ? [lexiconFilter] : buildResult.manifest.lexicons;
             const results = {};
+            const store = await resolveSnapshotStore();
             for (const lex of lexicons) {
-                const content = await readSnapshot(env, lex);
+                const content = await store.readLatest(env, lex);
                 let previousDigest = undefined;
                 if (content) {
                     const snapshot = JSON.parse(content);

package/dist/cli/mcp/resource-handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-handlers.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/resource-handlers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AASnD,KAAK,mBAAmB,GAAG;IAAE,UAAU,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC;AAE9F;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,kBAAkB,EAuDvD,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAChD;IAAE,SAAS,EAAE,kBAAkB,EAAE,CAAA;CAAE,CAMrC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAChD,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAS9C;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACjD,OAAO,GAAE,aAAa,EAAO,GAC5B,OAAO,CAAC,OAAO,CAAC,CA0KlB"}
+{"version":3,"file":"resource-handlers.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/resource-handlers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AASnD,KAAK,mBAAmB,GAAG;IAAE,UAAU,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC;AAE9F;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,kBAAkB,EAuDvD,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAChD;IAAE,SAAS,EAAE,kBAAkB,EAAE,CAAA;CAAE,CAMrC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAChD,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAS9C;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACjD,OAAO,GAAE,aAAa,EAAO,GAC5B,OAAO,CAAC,OAAO,CAAC,CA2KlB"}

package/dist/cli/mcp/resource-handlers.js

@@ -2,7 +2,7 @@ import { resolve, join, dirname } from "node:path";
 import { readFile } from "node:fs/promises";
 import { collectComposites } from "./tools/composites.js";
 import { getContext } from "./resources/context.js";
-import { readSnapshot, readEnvironmentSnapshots } from "../../lifecycle/git.js";
+import { readEnvironmentSnapshotsFrom, resolveSnapshotStore } from "../../lifecycle/snapshot-store.js";
 import { discoverOps } from "../../op/discover.js";
 import { createLocalOpRuntime } from "../../op/runtimes/local.js";
 import { loadOkfBundle } from "../../okf-read.js";
@@ -202,8 +202,9 @@ export async function handleResourcesRead(params, pluginResources, plugins = [])
         const parts = uri.replace("chant://state/", "").split("/");
         const environment = parts[0];
         const lexicon = parts[1];
+        const store = await resolveSnapshotStore();
         if (lexicon) {
-            const content = await readSnapshot(environment, lexicon);
+            const content = await store.readLatest(environment, lexicon);
             if (!content)
                 throw new Error(`No snapshot found for ${environment}/${lexicon}`);
             return {
@@ -211,7 +212,7 @@ export async function handleResourcesRead(params, pluginResources, plugins = [])
             };
         }
         else {
-            const snapshots = await readEnvironmentSnapshots(environment);
+            const snapshots = await readEnvironmentSnapshotsFrom(store, environment);
             const result = {};
             for (const [lex, content] of snapshots) {
                 result[lex] = JSON.parse(content);