@intentius/chant 0.124.52 → 0.124.54

package/dist/cli/handlers/index-diff.js

@@ -0,0 +1,142 @@
+/**
+ * `chant index diff <a> [<b>] [--store <spec>] [--json]` (#4533): what
+ * changed between two versions of one index scope.
+ *
+ * `<a>` is `<scopeKey>/<version>`, or `<scopeKey>` alone. `<b>` is
+ * `<scopeKey>/<version>`, or a version name in `<a>`'s scope. With no `<b>`,
+ * the version before `<a>` is diffed against `<a>`, and a scope alone diffs
+ * its last two versions.
+ *
+ * Versions are read through #4519's store API, from the store `chant index`
+ * writes to (#4532's {@link planIndexStore}: `--store <spec>`, else the
+ * project's store, else the per-user one), so a git-ref, local or s3 store
+ * diffs the same way. Nothing is built, no lexicon is loaded and no cloud is
+ * queried. The computation is ../../lifecycle/index-diff.ts.
+ */
+import { homedir } from "node:os";
+import { chantUserStoreDir, IndexUsageError, planIndexStore } from "../../lifecycle/cloud-index.js";
+import { diffIndexVersionRefs, IndexScopeMismatch, NotAnIndexVersion, parseIndexVersionRef } from "../../lifecycle/index-diff.js";
+import { createSnapshotStore, resolveSnapshotStore, snapshotStoreConfig } from "../../lifecycle/snapshot-store.js";
+export const INDEX_DIFF_USAGE = `chant index diff <a> [<b>] [--store <spec>] [--json]
+
+What changed between two versions of one index scope: nodes added and
+removed, properties changed, edges added and removed. A node is removed only
+where the later read listed its type and location; elsewhere it is not
+observed. Two versions of different scopes are refused.
+
+  <a>              <scopeKey>/<version>, or <scopeKey> for its latest version
+  <b>              <scopeKey>/<version>, or a version name in <a>'s scope.
+                   Absent: the version before <a> against <a> (a scope alone:
+                   its last two versions)
+  --store <spec>   the store to read, as chant index takes it (local,
+                   local:<dir>, git-ref, git-ref:<ref>, s3,
+                   s3://<bucket>[/<prefix>]). Default: the project's store,
+                   else chant's per-user store
+  --json           the diff as JSON
+`;
+async function openReadStore(plan, cwd) {
+    switch (plan.kind) {
+        case "user":
+            return createSnapshotStore({ store: "local", dir: plan.dir }, { cwd });
+        case "project":
+            return resolveSnapshotStore({ cwd: plan.projectDir });
+        case "spec":
+            return createSnapshotStore(snapshotStoreConfig(plan.configured, plan.env), { cwd, env: plan.env });
+    }
+}
+const show = (v) => (v === undefined ? "(absent)" : JSON.stringify(v));
+/** The diff as text, one line per change. */
+export function renderIndexDiff(d) {
+    const lines = [];
+    lines.push(`Index diff: ${d.scopeKey}`);
+    lines.push(`  from ${d.from.version ?? d.from.digest.slice(0, 12)} (observed ${d.from.observedAt})`);
+    lines.push(`  to   ${d.to.version ?? d.to.digest.slice(0, 12)} (observed ${d.to.observedAt})`);
+    if (d.unchanged) {
+        lines.push("", "Same digest: nothing changed.");
+        return `${lines.join("\n")}\n`;
+    }
+    const c = d.counts;
+    lines.push("", `${c.added} added, ${c.removed} removed, ${c.changed} changed (${c.properties} properties), ${c.notObserved} not observed; edges ${c.edgesAdded} added, ${c.edgesRemoved} removed, ${c.edgesNotObserved} not observed`);
+    for (const n of d.nodes.added)
+        lines.push(`  + ${n.key}`);
+    for (const n of d.nodes.removed)
+        lines.push(`  - ${n.key}`);
+    for (const n of d.nodes.changed) {
+        lines.push(`  ~ ${n.key}`);
+        for (const p of n.properties)
+            lines.push(`      ${p.path}: ${show(p.before)} -> ${show(p.after)}`);
+    }
+    for (const n of d.nodes.notObserved)
+        lines.push(`  ? ${n.key} (not observed in the ${n.side} read: ${n.verdict}${n.detail ? `, ${n.detail}` : ""})`);
+    for (const e of d.edges.added)
+        lines.push(`  + edge ${e.from} -> ${e.to}${e.viaAttr ? ` via ${e.viaAttr}` : ""}`);
+    for (const e of d.edges.removed)
+        lines.push(`  - edge ${e.from} -> ${e.to}${e.viaAttr ? ` via ${e.viaAttr}` : ""}`);
+    for (const e of d.edges.notObserved)
+        lines.push(`  ? edge ${e.from} -> ${e.to} (${e.unobservedEnd} not observed in the ${e.side} read: ${e.verdict})`);
+    for (const v of d.coverage)
+        lines.push(`  coverage ${v.listedType} @ ${v.location}: ${v.before ?? "(none)"} -> ${v.after ?? "(none)"}`);
+    return `${lines.join("\n")}\n`;
+}
+/** `chant index diff`'s argv (the words after `diff`). Exit 0 on a diff, 1 on a refusal, 2 on a usage error. */
+export async function runIndexDiff(argv, o = {}) {
+    const out = o.stdout ?? ((s) => void process.stdout.write(s));
+    const err = o.stderr ?? ((s) => void process.stderr.write(s));
+    const cwd = o.cwd ?? process.cwd();
+    const env = o.env ?? process.env;
+    if (argv.includes("-h") || argv.includes("--help")) {
+        out(INDEX_DIFF_USAGE);
+        return 0;
+    }
+    const refs = [];
+    let store;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--json")
+            json = true;
+        else if (a === "--store") {
+            store = argv[++i];
+            if (!store || store.startsWith("-")) {
+                err(`chant index diff: --store needs a store spec\n\n${INDEX_DIFF_USAGE}`);
+                return 2;
+            }
+        }
+        else if (a.startsWith("--store="))
+            store = a.slice("--store=".length);
+        else if (a.startsWith("-")) {
+            err(`chant index diff: unknown flag ${a}\n\n${INDEX_DIFF_USAGE}`);
+            return 2;
+        }
+        else
+            refs.push(a);
+    }
+    if (refs.length < 1 || refs.length > 2) {
+        err(`chant index diff: name one or two index versions\n\n${INDEX_DIFF_USAGE}`);
+        return 2;
+    }
+    let d;
+    try {
+        const from = parseIndexVersionRef(refs[0]);
+        const to = refs[1] ? parseIndexVersionRef(refs[1], from.scopeKey) : undefined;
+        const plan = planIndexStore({ store, cwd, env, defaultStoreDir: () => chantUserStoreDir(env, o.home ?? homedir()), command: "chant index diff" });
+        const s = await (o.openStore ?? openReadStore)(plan, cwd);
+        await s.fetch();
+        d = await diffIndexVersionRefs(s, from, to);
+    }
+    catch (e) {
+        if (e instanceof IndexUsageError) {
+            err(`${e.message}\n`);
+            return 2;
+        }
+        if (e instanceof IndexScopeMismatch || e instanceof NotAnIndexVersion) {
+            if (json)
+                out(`${JSON.stringify({ error: e.code, message: e.message, ...(e instanceof IndexScopeMismatch ? { fromScopeKey: e.fromScopeKey, toScopeKey: e.toScopeKey } : {}) }, null, 2)}\n`);
+            err(`chant index diff: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+    out(json ? `${JSON.stringify(d, null, 2)}\n` : renderIndexDiff(d));
+    return 0;
+}

package/dist/cli/handlers/lifecycle-drift.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `chant lifecycle drift [--member <name>] [--read <read>] [--resource <addr>]`
+ * (behold#995): the project's drift, as each lexicon's own engine reads it,
+ * printed as the drift-record NDJSON stream (`../../drift-record.ts`).
+ *
+ * This is the member half of `chant workspace drift`. A `terraform` or
+ * `choudoufu` member has no chant config of its own, so the workspace writes
+ * it a reader project (`../../workspace/kind-readers.ts`) and runs this
+ * command there, under the member's own toolchain, the way `workspace graph`
+ * runs `chant graph`. Every lexicon with a `readDrift` is asked; the lines
+ * are printed in the order they came, one JSON object per line. chant core
+ * never imports a lexicon to read drift.
+ *
+ * `--member` names the workspace member the records are for; it defaults to
+ * the project directory's name. A lexicon that refuses the read (a read its
+ * engine has not got, or one resource on an engine that cannot read one on
+ * its own) makes the command print `{"refused": {code, message}}` as its
+ * only stdout line and exit 3, so the workspace command can name the
+ * refusal. No lexicon with a drift read is the refusal `no-drift-read`.
+ */
+import type { CommandContext } from "../registry.js";
+/** The exit status of a refused read. */
+export declare const DRIFT_REFUSED_EXIT = 3;
+export declare function runLifecycleDrift(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=lifecycle-drift.d.ts.map

package/dist/cli/handlers/lifecycle-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-drift.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/lifecycle-drift.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,yCAAyC;AACzC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AASpC,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B5E"}

package/dist/cli/handlers/lifecycle-drift.js

@@ -0,0 +1,64 @@
+/**
+ * `chant lifecycle drift [--member <name>] [--read <read>] [--resource <addr>]`
+ * (behold#995): the project's drift, as each lexicon's own engine reads it,
+ * printed as the drift-record NDJSON stream (`../../drift-record.ts`).
+ *
+ * This is the member half of `chant workspace drift`. A `terraform` or
+ * `choudoufu` member has no chant config of its own, so the workspace writes
+ * it a reader project (`../../workspace/kind-readers.ts`) and runs this
+ * command there, under the member's own toolchain, the way `workspace graph`
+ * runs `chant graph`. Every lexicon with a `readDrift` is asked; the lines
+ * are printed in the order they came, one JSON object per line. chant core
+ * never imports a lexicon to read drift.
+ *
+ * `--member` names the workspace member the records are for; it defaults to
+ * the project directory's name. A lexicon that refuses the read (a read its
+ * engine has not got, or one resource on an engine that cannot read one on
+ * its own) makes the command print `{"refused": {code, message}}` as its
+ * only stdout line and exit 3, so the workspace command can name the
+ * refusal. No lexicon with a drift read is the refusal `no-drift-read`.
+ */
+import { basename, resolve } from "node:path";
+import { loadChantConfig } from "../../config.js";
+import { DRIFT_READS, encodeDriftLine } from "../../drift-record.js";
+import { formatError } from "../format.js";
+/** The exit status of a refused read. */
+export const DRIFT_REFUSED_EXIT = 3;
+const USAGE = "chant lifecycle drift [--member <name>] [--read <state|plan|refresh|live-read|ownership>] [--resource <addr>]";
+function refuse(code, message) {
+    console.log(JSON.stringify({ refused: { code, message } }));
+    return DRIFT_REFUSED_EXIT;
+}
+export async function runLifecycleDrift(ctx) {
+    const { args, plugins } = ctx;
+    const read = args.driftRead;
+    if (read !== undefined && !DRIFT_READS.includes(read)) {
+        console.error(formatError({ message: `--read ${read} is not a drift read; the reads are ${DRIFT_READS.join(", ")}`, hint: USAGE }));
+        return 1;
+    }
+    const projectRoot = resolve(".");
+    const { config } = await loadChantConfig(projectRoot);
+    const member = args.members?.[0] ?? basename(projectRoot);
+    const readers = plugins.filter((p) => typeof p.readDrift === "function");
+    if (readers.length === 0) {
+        return refuse("no-drift-read", `no lexicon this project declares (${plugins.map((p) => p.name).join(", ") || "none"}) has a drift read`);
+    }
+    const observedAt = new Date().toISOString();
+    const lines = [];
+    for (const plugin of readers) {
+        const answer = await plugin.readDrift({
+            member,
+            projectRoot,
+            config: config,
+            ...(read !== undefined ? { read: read } : {}),
+            ...(args.resource !== undefined ? { resource: args.resource } : {}),
+            observedAt,
+        });
+        if ("refused" in answer)
+            return refuse(answer.refused.code, `${plugin.name}: ${answer.refused.message}`);
+        lines.push(...answer.lines);
+    }
+    for (const line of lines)
+        process.stdout.write(encodeDriftLine(line));
+    return 0;
+}

package/dist/cli/handlers/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/lifecycle.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKlD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAE9E;AAED;;cAEc;AACd,UAAU,WAAW;IACnB;iDAC6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;0CACsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb;;;6DAGyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,WAAW,EAAE,CAMxF;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAyH/E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA4C3E;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B/E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA+L3E;AA+sBD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAyR3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2L/E;AAsBD;;GAEG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB1E;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmE7E;AAiCD;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9E;AAkBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8D/E"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/lifecycle.ts"],"names":[],"mappings":"AAkDA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKlD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAE9E;AAED;;cAEc;AACd,UAAU,WAAW;IACnB;iDAC6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;0CACsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb;;;6DAGyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,WAAW,EAAE,CAMxF;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8H/E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6C3E;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B/E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8Q3E;AA8xBD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2R3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2L/E;AAsBD;;GAEG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAoB1E;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmE7E;AAiCD;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9E;AAkBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8D/E"}

package/dist/cli/handlers/lifecycle.js

@@ -1,15 +1,19 @@
 import { lexiconNames } from "../../lexicon-module.js";
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import { commandBuildParams } from "../build-params-cli.js";
 import { build } from "../../build.js";
 import { takeSnapshot } from "../../lifecycle/snapshot.js";
-import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, pushLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git.js";
+import { snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git.js";
+import { readEnvironmentSnapshotsFrom, resolveSnapshotStore } from "../../lifecycle/snapshot-store.js";
 import { deepDiffForLexicon } from "../../lifecycle/deep-observe.js";
 import { countUnclaimed, countPending, countPropertyDrift, countHeld, suspiciousHeld } from "../../lifecycle/deep-diff.js";
 import { describePathOrigin, getPathProvenance, getProvenance } from "../../provenance.js";
 import { resolveDeepDrift, resolveDriftedField } from "../../fold-provenance.js";
-import { acceptDeviations, baselineForLexicon, emptyBaseline, readObservationBaseline, writeObservationBaseline, OBSERVATION_BASELINE_FILE, } from "../../lifecycle/observation-baseline.js";
+import { acceptDeviations, baselineForLexicon, emptyBaseline, readObservationBaseline, saveObservationBaseline, } from "../../lifecycle/observation-baseline.js";
 import { computeBuildDigest, declaredDefinitions, diffDigests } from "../../lifecycle/digest.js";
+import { diffDeclaredAgainstIndex, indexDriftDocument } from "../../lifecycle/index-drift.js";
+import { joinCell, parseIndexRef, readIndexRef } from "../../lifecycle/index-join.js";
+import { CHANT_VERSION } from "../../chant-version.js";
 import { diffLive, diffLiveArtifacts, diffSnapshots, missingRow } from "../../lifecycle/live-diff.js";
 import { buildChangeSet, renderChangeSet, renderChangeSetMarkdown, gitlabMrReport, unobservedPlanNotice } from "../../lifecycle/change-set.js";
 import { mergeReceiptEntries, observedValueResolver, planReceipts, readReceiptValue } from "../../lifecycle/receipt-plan.js";
@@ -100,6 +104,7 @@ export async function runLifecycleSnapshot(ctx) {
     // from its own scoped root — so its logical ids match what it deploys — and
     // snapshots against its own live stack name (#932).
     const targets = resolveStackTargets(args, config);
+    const store = await resolveSnapshotStore({ cwd: projectPath, config });
     let anySnapshotSaved = false;
     let anyHardError = false;
     // #1166 — same self-sufficiency as `chant graph --live`: a snapshot is
@@ -139,6 +144,7 @@ export async function runLifecycleSnapshot(ctx) {
                     deep: args.deep,
                     ambient: args.ambient,
                     ambientKinds: projectKinds,
+                    store,
                 });
             }
             catch (err) {
@@ -163,7 +169,10 @@ export async function runLifecycleSnapshot(ctx) {
                 const counts = result.snapshots
                     .map((s) => `${s.lexicon}(${Object.keys(s.resources).length})`)
                     .join(" ");
-                console.error(formatSuccess(`${prefix}Snapshot saved to chant/lifecycle (${counts})`));
+                // `none` keeps nothing, and says so: the observation still ran (#4519).
+                console.error(result.store && !result.store.written
+                    ? formatWarning({ message: `${prefix}Snapshot observed, not kept: the store is ${result.store.where} (${counts})` })
+                    : formatSuccess(`${prefix}Snapshot saved to ${store.where} (${counts})`));
             }
             if (result.errors.length > 0)
                 anyHardError = true;
@@ -185,9 +194,10 @@ export async function runLifecycleShow(ctx) {
         return 1;
     }
     // Fetch from remote first
-    await fetchLifecycle();
+    const store = await resolveSnapshotStore();
+    await store.fetch();
     if (lexiconFilter) {
-        const content = await readSnapshot(environment, lexiconFilter);
+        const content = await store.readLatest(environment, lexiconFilter);
         if (!content) {
             console.error(formatError({ message: `No snapshot found for ${environment}/${lexiconFilter}` }));
             return 1;
@@ -196,7 +206,7 @@ export async function runLifecycleShow(ctx) {
         printSnapshotTable(snapshot);
     }
     else {
-        const snapshots = await readEnvironmentSnapshots(environment);
+        const snapshots = await readEnvironmentSnapshotsFrom(store, environment);
         if (snapshots.size === 0) {
             console.error(formatError({ message: `No snapshots found for environment "${environment}"` }));
             return 1;
@@ -277,6 +287,21 @@ export async function runLifecycleDiff(ctx) {
             json: !!args.json,
         });
     }
+    // `--index <ref>` (#4526): the observed side is an index version in the
+    // store, not a live read and not a snapshot.
+    const indexMode = args.index !== undefined;
+    if (indexMode && (args.live || (args.betweenA && args.betweenB))) {
+        console.error(formatError({
+            message: `chant lifecycle diff takes --index or ${args.live ? "--live" : "--between"}, not both`,
+            hint: "--index compares source with an index version in the store; --live reads the estate now; --between compares two snapshots",
+        }));
+        return 1;
+    }
+    const indexRef = indexMode ? parseIndexRef(String(args.index)) : undefined;
+    if (indexRef && "error" in indexRef) {
+        console.error(formatError({ message: indexRef.error, hint: indexRef.hint }));
+        return 1;
+    }
     // Filter serializers to target lexicon before building
     const targetSerializers = lexiconFilter
         ? plugins.filter((p) => p.name === lexiconFilter).map((p) => p.serializer)
@@ -288,7 +313,18 @@ export async function runLifecycleDiff(ctx) {
     const declaredParams = await commandBuildParams(config.buildParams, args);
     if (!declaredParams)
         return 1;
-    await fetchLifecycle();
+    const store = await resolveSnapshotStore({ config });
+    await store.fetch();
+    let indexRead;
+    if (indexRef && !("error" in indexRef)) {
+        const read = await readIndexRef(store, indexRef);
+        if ("error" in read) {
+            console.error(formatError({ message: read.error, ...(read.hint ? { hint: read.hint } : {}) }));
+            return 1;
+        }
+        indexRead = read;
+    }
+    const indexResults = [];
     // One target per stack (single-stack projects: exactly one), each built from
     // its own scoped root and diffed against its own live stack name (#932).
     const targets = resolveStackTargets(args, config);
@@ -302,7 +338,7 @@ export async function runLifecycleDiff(ctx) {
     // Accepted-deviation baseline (#1014). Read once for the whole run — it is
     // env-keyed, not stack-keyed, and every deep pass subtracts from the same
     // committed set. Absent is the normal state (nothing accepted yet).
-    const baseline = args.live ? await readObservationBaseline(environment) : null;
+    const baseline = args.live || indexRead ? await readObservationBaseline(environment, { config }) : null;
     const accepted = {};
     // Effect receipts across every target's build (#1833) — `--update-baseline`
     // refuses to accept drift on them (the effect step is their only writer),
@@ -312,7 +348,7 @@ export async function runLifecycleDiff(ctx) {
     // Floci), so `--live` is self-sufficient even when the ambient shell never
     // exported e.g. AWS_ENDPOINT_URL. Ambient always wins when it's already set.
     // Scoped to just the live reads below — restored in `finally`.
-    const liveLexicons = args.live ? plugins.filter((p) => p.describeResources || p.listArtifacts) : [];
+    const liveLexicons = args.live && !indexRead ? plugins.filter((p) => p.describeResources || p.listArtifacts) : [];
     const endpointResult = applyLiveEndpoint(config.environments, environment, liveLexicons);
     if (endpointResult.notice)
         console.error(formatWarning({ message: endpointResult.notice }));
@@ -377,6 +413,7 @@ export async function runLifecycleDiff(ctx) {
                     plugins,
                     buildResult,
                     json,
+                    store,
                     stack: target.stack,
                     region: target.region,
                     componentStacks,
@@ -402,15 +439,69 @@ export async function runLifecycleDiff(ctx) {
                         combinedLexiconsJson = r.byLexicon;
                 }
             }
+            else if (indexRead) {
+                const r = runLifecycleDiffIndex({
+                    read: indexRead,
+                    lexicons: lexiconFilter ? [lexiconFilter] : builtLexicons,
+                    plugins,
+                    buildResult,
+                    baseline,
+                    member: basename(projectRoot),
+                    stack: target.stack,
+                    region: target.region,
+                    json,
+                    projectRoot,
+                });
+                indexResults.push(r);
+                for (const [lexicon, part] of Object.entries(r.byLexicon)) {
+                    if (args.updateBaseline)
+                        (accepted[lexicon] ?? (accepted[lexicon] = [])).push(...deviationsToAccept(part.deep));
+                }
+                if (args.updateBaseline) {
+                    for (const name of collectEffectReceipts(buildResult.entities).keys())
+                        receiptEntities.add(name);
+                }
+            }
             else {
-                await runLifecycleDiffDigest({ environment, lexicons, buildResult, stack: target.stack });
+                await runLifecycleDiffDigest({ environment, lexicons, buildResult, stack: target.stack, store });
             }
         }
         // `--update-baseline` (#1014): record what the deep pass just reported as
         // accepted, so it stops re-alerting. Runs before the summary lines so the
         // "no drift" verdict below still describes the run that produced it.
-        if (args.live && args.updateBaseline) {
-            await recordAcceptedBaseline(environment, baseline, accepted, json, receiptEntities);
+        if ((args.live || indexRead) && args.updateBaseline) {
+            await recordAcceptedBaseline(environment, baseline, accepted, json, receiptEntities, config);
+        }
+        if (indexRead) {
+            // Drift records, drift document v1 (#4526).
+            if (json)
+                console.log(JSON.stringify(indexDriftDocument(indexResults, CHANT_VERSION)));
+            else {
+                const sum = (k) => indexResults.reduce((n, r) => n + r.counts[k], 0);
+                const ref = indexResults[0]?.ref;
+                const declaredCount = sum("declared");
+                const drift = sum("properties") + sum("pending");
+                const notObserved = sum("notObserved");
+                if (anyBuildError) {
+                    // the build error is already printed
+                }
+                else if (declaredCount === 0) {
+                    console.error(formatWarning({ message: "No declared entities to compare with the index" }));
+                }
+                else if (drift === 0) {
+                    console.error(notObserved > 0
+                        ? formatWarning({
+                            message: `No drift detected against index ${ref} across ${sum("bound")} bound entity(ies), but ${notObserved} declared entity(ies) are not observed by it: that part of the estate is unknown, not clean`,
+                        })
+                        : formatSuccess(`No drift detected against index ${ref} across ${declaredCount} declared entity(ies)`));
+                }
+                else {
+                    console.error(formatWarning({
+                        message: `Drift against index ${ref}: ${sum("properties")} property difference(s) on ${sum("drifted")} entity(ies), ${sum("pending")} declared entity(ies) absent from it, ${notObserved} not observed`,
+                    }));
+                }
+            }
+            return anyBuildError ? 1 : 0;
         }
         if (args.live) {
             if (json) {
@@ -451,7 +542,7 @@ export async function runLifecycleDiff(ctx) {
  * count and the storage path, and a failed push says so rather than leaving
  * the operator believing the team's baseline moved.
  */
-async function recordAcceptedBaseline(environment, existing, accepted, json, receipts) {
+async function recordAcceptedBaseline(environment, existing, accepted, json, receipts, config) {
     const total = Object.values(accepted).reduce((n, d) => n + d.length, 0);
     if (total === 0) {
         if (!json) {
@@ -469,11 +560,15 @@ async function recordAcceptedBaseline(environment, existing, accepted, json, rec
         for (const [lexicon, deviations] of Object.entries(accepted)) {
             next = acceptDeviations(next, lexicon, deviations, { receipts });
         }
-        await writeObservationBaseline(next);
-        const pushed = await pushLifecycle();
+        // A file under .chant/observation-baseline/ by default (#4519): commit it
+        // with the change that needed it, so the acceptance is reviewed.
+        const saved = await saveObservationBaseline(next, config ? { config } : undefined);
         if (!json) {
-            console.error(formatSuccess(`--update-baseline: accepted ${total} deviation(s) into ${environment}/${OBSERVATION_BASELINE_FILE} on chant/lifecycle` +
-                (pushed ? " (pushed)" : " (local only — no remote configured or push refused)")));
+            const note = saved.published === "pushed" ? " (pushed)"
+                : saved.published === "file" ? " (commit it to keep it)"
+                    : saved.published === "none" ? " (the baseline store is none: nothing kept)"
+                        : " (local only — no remote configured or push refused)";
+            console.error(formatSuccess(`--update-baseline: accepted ${total} deviation(s) into ${saved.where}${note}`));
         }
     }
     catch (err) {
@@ -489,8 +584,9 @@ async function recordAcceptedBaseline(environment, existing, accepted, json, rec
  * two-way delta per lexicon.
  */
 async function runLifecycleDiffBetween(args) {
-    await fetchLifecycle();
     const { config } = await loadChantConfig(resolve("."));
+    const store = await resolveSnapshotStore({ config });
+    await store.fetch();
     const lexicons = args.lexiconFilter ? [args.lexiconFilter] : lexiconNames(config.lexicons ?? []);
     if (lexicons.length === 0) {
         console.error(formatError({ message: "No lexicons to diff — pass a lexicon or declare `lexicons` in chant.config." }));
@@ -508,8 +604,8 @@ async function runLifecycleDiffBetween(args) {
     };
     const byLexicon = {};
     for (const lexicon of lexicons) {
-        const prev = parseResources(await readSnapshotAt(args.environment, lexicon, args.refA));
-        const next = parseResources(await readSnapshotAt(args.environment, lexicon, args.refB));
+        const prev = parseResources(await store.readAt(args.environment, lexicon, args.refA));
+        const next = parseResources(await store.readAt(args.environment, lexicon, args.refB));
         if (prev === null && next === null) {
             if (!args.json)
                 console.error(formatWarning({ message: `${lexicon}: not captured at either ref — skipping` }));
@@ -542,7 +638,7 @@ async function runLifecycleDiffDigest(args) {
     if (args.stack)
         console.log(`\n${formatBold(`■ stack ${args.stack}`)}`);
     for (const lexicon of args.lexicons) {
-        const content = await readSnapshot(args.environment, snapshotStorageKey(lexicon, args.stack));
+        const content = await args.store.readLatest(args.environment, snapshotStorageKey(lexicon, args.stack));
         let previousDigest = undefined;
         if (content) {
             const snapshot = JSON.parse(content);
@@ -672,7 +768,7 @@ async function runLifecycleDiffLive(args) {
                 : rawOutput.primary;
         // Read previous snapshot once; both flows pull what they need.
         let prevSnapshot;
-        const content = await readSnapshot(args.environment, snapshotStorageKey(lexiconName, args.stack));
+        const content = await args.store.readLatest(args.environment, snapshotStorageKey(lexiconName, args.stack));
         if (content)
             prevSnapshot = JSON.parse(content);
         let lexiconChecked = false;
@@ -790,6 +886,65 @@ async function runLifecycleDiffLive(args) {
     }
     return { byLexicon, totalDrift, totalUnobserved, totalLexiconsChecked, toAccept };
 }
+/**
+ * `chant lifecycle diff <env> --index <ref>` for one stack (#4526): every
+ * declared entity joined to the index version, the bound ones deep-diffed
+ * against their indexed trees, the rest reported with their join verdict.
+ * Reads nothing but the store. See ../../lifecycle/index-drift.ts.
+ */
+function runLifecycleDiffIndex(args) {
+    const entities = new Map();
+    for (const lexicon of args.lexicons)
+        entities.set(lexicon, new Map());
+    for (const [name, entity] of args.buildResult.entities) {
+        const forLexicon = entities.get(entity.lexicon);
+        if (!forLexicon || !isObservableDeclarable(entity))
+            continue;
+        const pathOrigins = getPathProvenance(entity);
+        forLexicon.set(name, {
+            entityType: entity.entityType,
+            props: (entity.props != null ? entity.props : {}),
+            ...(pathOrigins ? { pathOrigins } : {}),
+        });
+    }
+    const result = diffDeclaredAgainstIndex({
+        doc: args.read.doc,
+        version: args.read.version,
+        entities,
+        lexicons: args.plugins,
+        baseline: args.baseline,
+        member: args.member,
+        ...(args.stack ? { stack: args.stack } : {}),
+        ...(args.region ? { region: args.region } : {}),
+        chant: CHANT_VERSION,
+    });
+    if (args.json)
+        return result;
+    const { stamp } = args.read.doc;
+    const by = stamp.source.version ? `${stamp.source.name} ${stamp.source.version}` : stamp.source.name;
+    if (args.stack)
+        console.log(`\n${formatBold(`■ stack ${args.stack}`)}`);
+    console.log(`index ${result.ref}, read ${stamp.observedAt} by ${by}`);
+    const provenanceOf = (name) => {
+        const entity = args.buildResult.entities.get(name);
+        return entity ? getProvenance(entity) : undefined;
+    };
+    for (const [lexicon, part] of Object.entries(result.byLexicon)) {
+        const rows = Object.entries(part.joins).sort(([a], [b]) => a.localeCompare(b));
+        const bound = rows.filter(([, j]) => j.verdict === "bound").length;
+        console.log(formatBold(`\n${lexicon}: ${bound}/${rows.length} declared entity(ies) bound to the index`));
+        const unbound = rows.filter(([, j]) => j.verdict !== "bound");
+        if (unbound.length > 0) {
+            console.log(formatBold("\nNOT COMPARED (the join did not bind; never diffed):"));
+            for (const [name, j] of unbound) {
+                const detail = "detail" in j ? `: ${j.detail}` : j.verdict === "absent" ? ": the index listed its type and location and does not hold it" : "";
+                console.log(`  ? ${name} ${joinCell(j) ?? ""}${detail}`);
+            }
+        }
+        renderDeepDiff(lexicon, part.deep, provenanceOf, args.projectRoot);
+    }
+    return result;
+}
 /**
  * Everything a deep diff reported this run, as deviations to record accepted.
  * `--update-baseline` accepts what was *reported*, never what was already
@@ -1068,7 +1223,8 @@ export async function runLifecyclePlan(ctx) {
         console.error(formatError({ message: "Build failed — fix errors before planning" }));
         return 1;
     }
-    await fetchLifecycle();
+    const store = await resolveSnapshotStore({ config });
+    await store.fetch();
     const lexicons = lexiconFilter ? [lexiconFilter] : Array.from(buildResult.manifest.lexicons);
     // Multi-stack component projects deploy one CFN stack per component, so the
     // single-stack-per-env observe below would see nothing live and plan every
@@ -1219,7 +1375,8 @@ export async function runLifecyclePlan(ctx) {
                     receiptReadings.set(receiptName, { observed: true, present: false, lexicon: lexiconName });
                 }
             }
-            const content = await readSnapshot(environment, lexiconName);
+            // Evidence only (#4519): the change set never makes a decision from it.
+            const content = await store.readLatest(environment, lexiconName);
             const observedThen = content ? JSON.parse(content).resources : undefined;
             const cs = buildChangeSet(environment, {
                 declared,
@@ -1500,15 +1657,18 @@ async function promptProdTeardown(environment) {
  */
 export async function runLifecycleLog(ctx) {
     const environment = ctx.args.extraPositional;
-    await fetchLifecycle();
-    const entries = await listSnapshots({ environment });
+    const store = await resolveSnapshotStore();
+    await store.fetch();
+    const entries = await store.list({ ...(environment ? { environment } : {}) });
     if (entries.length === 0) {
         console.error(formatError({ message: "No state snapshots found" }));
         return 1;
     }
+    // A git store's version is a commit; s3's an object version, local's a time.
+    const isCommit = (v) => /^[0-9a-f]{40}$/.test(v);
     for (const entry of entries) {
         const date = entry.date.split("T")[0];
-        console.log(`${entry.commit.slice(0, 7)}  ${date}  ${entry.message}`);
+        console.log(`${isCommit(entry.version) ? entry.version.slice(0, 7) : entry.version}  ${date}  ${entry.key ?? entry.message}`);
     }
     return 0;
 }

package/dist/cli/handlers/misc.d.ts

@@ -1,7 +1,16 @@
+import type { IndexImportSelection } from "../../lifecycle/index-import.js";
 import type { CommandContext } from "../registry.js";
 export declare function runAudit(ctx: CommandContext): Promise<number>;
 export declare function runList(ctx: CommandContext): Promise<number>;
 export declare function runDescribe(ctx: CommandContext): Promise<number>;
+/**
+ * The selection for `chant import --index` (#4524). `--type` and `--name`
+ * take comma-separated lists, `--tag key=value` repeats, `--select` is a JSON
+ * file of node ids (a list of ids, of `{ id }` or `{ node }` objects, or an
+ * object holding `nodes` or `results`) or a comma-separated list of ids, and
+ * `--all` takes every node.
+ */
+export declare function indexSelectionFromArgs(args: CommandContext["args"]): IndexImportSelection | Error;
 export declare function runImport(ctx: CommandContext): Promise<number>;
 export declare function runUpdate(ctx: CommandContext): Promise<number>;
 export declare function runDoctor(ctx: CommandContext): Promise<number>;

package/dist/cli/handlers/misc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"misc.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/misc.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA8ClD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAqGnE;AAED,wBAAsB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuClE;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CtE;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAqJpE;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAKpE;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBpE"}
+{"version":3,"file":"misc.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/misc.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAQzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA8ClD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAqGnE;AAED,wBAAsB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuClE;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CtE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,oBAAoB,GAAG,KAAK,CAwCjG;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2KpE;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAKpE;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBpE"}