@intentius/chant 0.1.13 → 0.1.15

package/src/cli/handlers/{state.test.ts → lifecycle.test.ts}

@@ -5,7 +5,7 @@ import type { BuildResult } from "../../build";
 import type { ParsedArgs } from "../registry";
 
 const buildMock = vi.fn();
-const fetchStateMock = vi.fn();
+const fetchLifecycleMock = vi.fn();
 const readSnapshotMock = vi.fn();
 const readEnvironmentSnapshotsMock = vi.fn();
 const listSnapshotsMock = vi.fn();
@@ -13,20 +13,20 @@ const takeSnapshotMock = vi.fn();
 const loadChantConfigMock = vi.fn();
 
 vi.mock("../../build", () => ({ build: (...args: unknown[]) => buildMock(...args) }));
-vi.mock("../../state/git", () => ({
-  fetchState: () => fetchStateMock(),
+vi.mock("../../lifecycle/git", () => ({
+  fetchLifecycle: () => fetchLifecycleMock(),
   readSnapshot: (...args: unknown[]) => readSnapshotMock(...args),
   readEnvironmentSnapshots: (...args: unknown[]) => readEnvironmentSnapshotsMock(...args),
   listSnapshots: (...args: unknown[]) => listSnapshotsMock(...args),
 }));
-vi.mock("../../state/snapshot", () => ({
+vi.mock("../../lifecycle/snapshot", () => ({
   takeSnapshot: (...args: unknown[]) => takeSnapshotMock(...args),
 }));
 vi.mock("../../config", () => ({
   loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args),
 }));
 
-const { runStateDiff, runStateSnapshot, runStateShow, runStateLog, runStateUnknown } = await import("./state");
+const { runLifecycleDiff, runLifecycleSnapshot, runLifecycleShow, runLifecycleLog, runLifecycleUnknown } = await import("./lifecycle");
 
 function makeArgs(overrides: Partial<ParsedArgs>): ParsedArgs {
   return {
@@ -71,7 +71,7 @@ const meta = (overrides: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
   ...overrides,
 });
 
-describe("runStateDiff --live", () => {
+describe("runLifecycleDiff --live", () => {
   let stdoutSpy: ReturnType<typeof vi.spyOn>;
   let stderrSpy: ReturnType<typeof vi.spyOn>;
   let stdoutBuf: string[];
@@ -83,13 +83,13 @@ describe("runStateDiff --live", () => {
     stdoutSpy = vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
     stderrSpy = vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
     buildMock.mockReset();
-    fetchStateMock.mockReset();
+    fetchLifecycleMock.mockReset();
     readSnapshotMock.mockReset();
   });
 
   test("surfaces drift between previous snapshot and live state", async () => {
     buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
-    fetchStateMock.mockResolvedValue(undefined);
+    fetchLifecycleMock.mockResolvedValue(undefined);
     readSnapshotMock.mockResolvedValue(JSON.stringify({
       lexicon: "aws",
       environment: "prod",
@@ -113,7 +113,7 @@ describe("runStateDiff --live", () => {
       serializers: plugins.map((p) => p.serializer),
     };
 
-    const exit = await runStateDiff(ctx);
+    const exit = await runLifecycleDiff(ctx);
 
     expect(exit).toBe(0);
     const output = stdoutBuf.join("\n");
@@ -126,7 +126,7 @@ describe("runStateDiff --live", () => {
 
   test("warns and skips lexicons without describeResources", async () => {
     buildMock.mockResolvedValue(makeBuildResult({ k8s: ["pod"] }));
-    fetchStateMock.mockResolvedValue(undefined);
+    fetchLifecycleMock.mockResolvedValue(undefined);
     readSnapshotMock.mockResolvedValue(null);
 
     const plugins: LexiconPlugin[] = [
@@ -139,7 +139,7 @@ describe("runStateDiff --live", () => {
       serializers: plugins.map((p) => p.serializer),
     };
 
-    const exit = await runStateDiff(ctx);
+    const exit = await runLifecycleDiff(ctx);
 
     expect(exit).toBe(1);
     const stderr = stderrBuf.join("\n");
@@ -149,7 +149,7 @@ describe("runStateDiff --live", () => {
 
   test("--live with a listArtifacts-only plugin diffs artifacts (no resources path)", async () => {
     buildMock.mockResolvedValue(makeBuildResult({ helm: [] }));
-    fetchStateMock.mockResolvedValue(undefined);
+    fetchLifecycleMock.mockResolvedValue(undefined);
     // Previous snapshot has no artifact entry for the new release → expect ARTIFACTS ADDED
     readSnapshotMock.mockResolvedValue(JSON.stringify({
       lexicon: "helm",
@@ -175,7 +175,7 @@ describe("runStateDiff --live", () => {
       serializers: plugins.map((p) => p.serializer),
     };
 
-    const exit = await runStateDiff(ctx);
+    const exit = await runLifecycleDiff(ctx);
 
     expect(exit).toBe(0);
     const output = stdoutBuf.join("\n");
@@ -185,7 +185,7 @@ describe("runStateDiff --live", () => {
 
   test("legacy digest mode still works without --live", async () => {
     buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
-    fetchStateMock.mockResolvedValue(undefined);
+    fetchLifecycleMock.mockResolvedValue(undefined);
     readSnapshotMock.mockResolvedValue(null);
 
     const plugins: LexiconPlugin[] = [createMockPlugin({ name: "aws" })];
@@ -196,7 +196,7 @@ describe("runStateDiff --live", () => {
       serializers: plugins.map((p) => p.serializer),
     };
 
-    const exit = await runStateDiff(ctx);
+    const exit = await runLifecycleDiff(ctx);
 
     expect(exit).toBe(0);
     const output = stdoutBuf.join("\n");
@@ -206,7 +206,7 @@ describe("runStateDiff --live", () => {
   });
 });
 
-describe("runStateSnapshot", () => {
+describe("runLifecycleSnapshot", () => {
   let stdoutBuf: string[];
   let stderrBuf: string[];
 
@@ -227,7 +227,7 @@ describe("runStateSnapshot", () => {
       plugins: [],
       serializers: [],
     };
-    const exit = await runStateSnapshot(ctx);
+    const exit = await runLifecycleSnapshot(ctx);
     expect(exit).toBe(1);
     expect(stderrBuf.join("\n")).toContain("Environment is required");
   });
@@ -238,7 +238,7 @@ describe("runStateSnapshot", () => {
       plugins: [],
       serializers: [],
     };
-    const exit = await runStateSnapshot(ctx);
+    const exit = await runLifecycleSnapshot(ctx);
     expect(exit).toBe(1);
     expect(stderrBuf.join("\n")).toContain('Unknown environment "unknown"');
   });
@@ -251,7 +251,7 @@ describe("runStateSnapshot", () => {
       plugins,
       serializers: plugins.map((p) => p.serializer),
     };
-    const exit = await runStateSnapshot(ctx);
+    const exit = await runLifecycleSnapshot(ctx);
     expect(exit).toBe(1);
     expect(stderrBuf.join("\n")).toContain("No plugins implement describeResources");
   });
@@ -275,14 +275,14 @@ describe("runStateSnapshot", () => {
       plugins,
       serializers: plugins.map((p) => p.serializer),
     };
-    const exit = await runStateSnapshot(ctx);
+    const exit = await runLifecycleSnapshot(ctx);
     expect(exit).toBe(0);
     expect(stderrBuf.join("\n")).toContain("Snapshot saved");
     expect(takeSnapshotMock).toHaveBeenCalledTimes(1);
   });
 });
 
-describe("runStateShow", () => {
+describe("runLifecycleShow", () => {
   let stdoutBuf: string[];
   let stderrBuf: string[];
 
@@ -291,7 +291,7 @@ describe("runStateShow", () => {
     stderrBuf = [];
     vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
     vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
-    fetchStateMock.mockReset();
+    fetchLifecycleMock.mockReset();
     readSnapshotMock.mockReset();
     readEnvironmentSnapshotsMock.mockReset();
   });
@@ -301,12 +301,12 @@ describe("runStateShow", () => {
       args: makeArgs({ command: "state", path: "show" }),
       plugins: [], serializers: [],
     };
-    expect(await runStateShow(ctx)).toBe(1);
+    expect(await runLifecycleShow(ctx)).toBe(1);
     expect(stderrBuf.join("\n")).toContain("Environment is required");
   });
 
   test("specific lexicon: prints snapshot table when found", async () => {
-    fetchStateMock.mockResolvedValue(undefined);
+    fetchLifecycleMock.mockResolvedValue(undefined);
     readSnapshotMock.mockResolvedValue(JSON.stringify({
       lexicon: "aws", environment: "prod", commit: "x", timestamp: "t",
       resources: { bucket: { type: "AWS::S3::Bucket", physicalId: "b-1", status: "OK" } },
@@ -315,25 +315,25 @@ describe("runStateShow", () => {
       args: makeArgs({ command: "state", path: "show", extraPositional: "prod", extraPositional2: "aws" }),
       plugins: [], serializers: [],
     };
-    expect(await runStateShow(ctx)).toBe(0);
+    expect(await runLifecycleShow(ctx)).toBe(0);
     const out = stdoutBuf.join("\n");
     expect(out).toContain("bucket");
     expect(out).toContain("AWS::S3::Bucket");
   });
 
   test("specific lexicon: returns 1 when no snapshot found", async () => {
-    fetchStateMock.mockResolvedValue(undefined);
+    fetchLifecycleMock.mockResolvedValue(undefined);
     readSnapshotMock.mockResolvedValue(null);
     const ctx = {
       args: makeArgs({ command: "state", path: "show", extraPositional: "prod", extraPositional2: "aws" }),
       plugins: [], serializers: [],
     };
-    expect(await runStateShow(ctx)).toBe(1);
+    expect(await runLifecycleShow(ctx)).toBe(1);
     expect(stderrBuf.join("\n")).toContain("No snapshot found");
   });
 
   test("no lexicon: lists all lexicons in env", async () => {
-    fetchStateMock.mockResolvedValue(undefined);
+    fetchLifecycleMock.mockResolvedValue(undefined);
     readEnvironmentSnapshotsMock.mockResolvedValue(new Map([
       ["aws", JSON.stringify({ lexicon: "aws", environment: "prod", commit: "x", timestamp: "t", resources: {} })],
       ["gcp", JSON.stringify({ lexicon: "gcp", environment: "prod", commit: "x", timestamp: "t", resources: {} })],
@@ -342,14 +342,14 @@ describe("runStateShow", () => {
       args: makeArgs({ command: "state", path: "show", extraPositional: "prod" }),
       plugins: [], serializers: [],
     };
-    expect(await runStateShow(ctx)).toBe(0);
+    expect(await runLifecycleShow(ctx)).toBe(0);
     const out = stdoutBuf.join("\n");
     expect(out).toContain("prod/aws");
     expect(out).toContain("prod/gcp");
   });
 });
 
-describe("runStateLog", () => {
+describe("runLifecycleLog", () => {
   let stdoutBuf: string[];
   let stderrBuf: string[];
 
@@ -358,23 +358,23 @@ describe("runStateLog", () => {
     stderrBuf = [];
     vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
     vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
-    fetchStateMock.mockReset();
+    fetchLifecycleMock.mockReset();
     listSnapshotsMock.mockReset();
   });
 
   test("returns 1 with message when no entries exist", async () => {
-    fetchStateMock.mockResolvedValue(undefined);
+    fetchLifecycleMock.mockResolvedValue(undefined);
     listSnapshotsMock.mockResolvedValue([]);
     const ctx = {
       args: makeArgs({ command: "state", path: "log" }),
       plugins: [], serializers: [],
     };
-    expect(await runStateLog(ctx)).toBe(1);
+    expect(await runLifecycleLog(ctx)).toBe(1);
     expect(stderrBuf.join("\n")).toContain("No state snapshots");
   });
 
   test("prints commit / date / message rows for each entry", async () => {
-    fetchStateMock.mockResolvedValue(undefined);
+    fetchLifecycleMock.mockResolvedValue(undefined);
     listSnapshotsMock.mockResolvedValue([
       { commit: "abcdef1234567890", date: "2026-05-01T00:00:00Z", message: "Snapshot prod" },
       { commit: "fedcba9876543210", date: "2026-05-02T00:00:00Z", message: "Snapshot staging" },
@@ -383,7 +383,7 @@ describe("runStateLog", () => {
       args: makeArgs({ command: "state", path: "log" }),
       plugins: [], serializers: [],
     };
-    expect(await runStateLog(ctx)).toBe(0);
+    expect(await runLifecycleLog(ctx)).toBe(0);
     const out = stdoutBuf.join("\n");
     expect(out).toContain("abcdef1");
     expect(out).toContain("Snapshot prod");
@@ -391,7 +391,7 @@ describe("runStateLog", () => {
   });
 });
 
-describe("runStateUnknown", () => {
+describe("runLifecycleUnknown", () => {
   test("returns 1 with subcommand list", async () => {
     const stderrBuf: string[] = [];
     vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
@@ -399,7 +399,7 @@ describe("runStateUnknown", () => {
       args: makeArgs({ command: "state", path: "garbage" }),
       plugins: [], serializers: [],
     };
-    expect(await runStateUnknown(ctx)).toBe(1);
+    expect(await runLifecycleUnknown(ctx)).toBe(1);
     const stderr = stderrBuf.join("\n");
     expect(stderr).toContain("snapshot");
     expect(stderr).toContain("show");

package/src/cli/handlers/{state.ts → lifecycle.ts}

@@ -1,27 +1,28 @@
 import { resolve } from "node:path";
 import { build } from "../../build";
-import { takeSnapshot } from "../../state/snapshot";
-import { readSnapshot, readEnvironmentSnapshots, listSnapshots, fetchState, StaleStateBranchError } from "../../state/git";
-import { computeBuildDigest, diffDigests } from "../../state/digest";
-import { diffLive, diffLiveArtifacts, type LiveDiffResult, type LiveArtifactDiffResult } from "../../state/live-diff";
+import { takeSnapshot } from "../../lifecycle/snapshot";
+import { readSnapshot, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, StaleLifecycleBranchError } from "../../lifecycle/git";
+import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
+import { diffLive, diffLiveArtifacts, type LiveDiffResult, type LiveArtifactDiffResult } from "../../lifecycle/live-diff";
+import { buildChangeSet, renderChangeSet, type ChangeSet } from "../../lifecycle/change-set";
 import { loadChantConfig } from "../../config";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
-import type { StateSnapshot } from "../../state/types";
+import type { LifecycleSnapshot } from "../../lifecycle/types";
 import type { SerializerResult } from "../../serializer";
-import type { LexiconPlugin, ResourceMetadata, ArtifactMetadata } from "../../lexicon";
+import type { ObservationLexicon, ResourceMetadata, ArtifactMetadata } from "../../lexicon";
 import type { BuildResult } from "../../build";
 
 /**
- * chant state snapshot <environment> [lexicon]
+ * chant lifecycle snapshot <environment> [lexicon]
  */
-export async function runStateSnapshot(ctx: CommandContext): Promise<number> {
+export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number> {
   const { args, plugins } = ctx;
   const environment = args.extraPositional;
   const lexiconFilter = args.extraPositional2;
 
   if (!environment) {
-    console.error(formatError({ message: "Environment is required: chant state snapshot <environment> [lexicon]" }));
+    console.error(formatError({ message: "Environment is required: chant lifecycle snapshot <environment> [lexicon]" }));
     return 1;
   }
 
@@ -62,10 +63,10 @@ export async function runStateSnapshot(ctx: CommandContext): Promise<number> {
   try {
     result = await takeSnapshot(environment, observingPlugins, buildResult);
   } catch (err) {
-    if (err instanceof StaleStateBranchError) {
+    if (err instanceof StaleLifecycleBranchError) {
       console.error(formatError({
-        message: `Another snapshot completed for chant/state after this run started (env: ${environment}).`,
-        hint: `Pull and retry: \`git fetch origin ${"chant/state"}:${"chant/state"}\` && \`chant state snapshot ${environment}\`.`,
+        message: `Another snapshot completed for chant/lifecycle after this run started (env: ${environment}).`,
+        hint: `Pull and retry: \`git fetch origin ${"chant/lifecycle"}:${"chant/lifecycle"}\` && \`chant lifecycle snapshot ${environment}\`.`,
       }));
       return 1;
     }
@@ -83,26 +84,26 @@ export async function runStateSnapshot(ctx: CommandContext): Promise<number> {
     const counts = result.snapshots
       .map((s) => `${s.lexicon}(${Object.keys(s.resources).length})`)
       .join(" ");
-    console.error(formatSuccess(`Snapshot saved to chant/state (${counts})`));
+    console.error(formatSuccess(`Snapshot saved to chant/lifecycle (${counts})`));
   }
 
   return result.errors.length > 0 && result.snapshots.length === 0 ? 1 : 0;
 }
 
 /**
- * chant state show <environment> [lexicon]
+ * chant lifecycle show <environment> [lexicon]
  */
-export async function runStateShow(ctx: CommandContext): Promise<number> {
+export async function runLifecycleShow(ctx: CommandContext): Promise<number> {
   const environment = ctx.args.extraPositional;
   const lexiconFilter = ctx.args.extraPositional2;
 
   if (!environment) {
-    console.error(formatError({ message: "Environment is required: chant state show <environment> [lexicon]" }));
+    console.error(formatError({ message: "Environment is required: chant lifecycle show <environment> [lexicon]" }));
     return 1;
   }
 
   // Fetch from remote first
-  await fetchState();
+  await fetchLifecycle();
 
   if (lexiconFilter) {
     const content = await readSnapshot(environment, lexiconFilter);
@@ -111,7 +112,7 @@ export async function runStateShow(ctx: CommandContext): Promise<number> {
       return 1;
     }
 
-    const snapshot: StateSnapshot = JSON.parse(content);
+    const snapshot: LifecycleSnapshot = JSON.parse(content);
     printSnapshotTable(snapshot);
   } else {
     const snapshots = await readEnvironmentSnapshots(environment);
@@ -121,7 +122,7 @@ export async function runStateShow(ctx: CommandContext): Promise<number> {
     }
 
     for (const [lexicon, content] of snapshots) {
-      const snapshot: StateSnapshot = JSON.parse(content);
+      const snapshot: LifecycleSnapshot = JSON.parse(content);
       console.log(`\n${formatBold(`${environment}/${lexicon}`)} — ${Object.keys(snapshot.resources).length} resources — ${snapshot.timestamp}`);
       printSnapshotTable(snapshot);
     }
@@ -131,15 +132,15 @@ export async function runStateShow(ctx: CommandContext): Promise<number> {
 }
 
 /**
- * chant state diff <environment> [lexicon]
+ * chant lifecycle diff <environment> [lexicon]
  */
-export async function runStateDiff(ctx: CommandContext): Promise<number> {
+export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
   const { args, plugins, serializers } = ctx;
   const environment = args.extraPositional;
   const lexiconFilter = args.extraPositional2;
 
   if (!environment) {
-    console.error(formatError({ message: "Environment is required: chant state diff <environment> [lexicon]" }));
+    console.error(formatError({ message: "Environment is required: chant lifecycle diff <environment> [lexicon]" }));
     return 1;
   }
 
@@ -157,17 +158,17 @@ export async function runStateDiff(ctx: CommandContext): Promise<number> {
   }
 
   // Fetch and read previous snapshot
-  await fetchState();
+  await fetchLifecycle();
 
   const lexicons = lexiconFilter
     ? [lexiconFilter]
     : Array.from(buildResult.manifest.lexicons);
 
   if (args.live) {
-    return runStateDiffLive({ environment, lexicons, plugins, buildResult });
+    return runLifecycleDiffLive({ environment, lexicons, plugins, buildResult });
   }
 
-  return runStateDiffDigest({ environment, lexicons, buildResult });
+  return runLifecycleDiffDigest({ environment, lexicons, buildResult });
 }
 
 interface DigestDiffArgs {
@@ -176,14 +177,14 @@ interface DigestDiffArgs {
   buildResult: BuildResult;
 }
 
-async function runStateDiffDigest(args: DigestDiffArgs): Promise<number> {
+async function runLifecycleDiffDigest(args: DigestDiffArgs): Promise<number> {
   const currentDigest = computeBuildDigest(args.buildResult);
 
   for (const lexicon of args.lexicons) {
     const content = await readSnapshot(args.environment, lexicon);
     let previousDigest = undefined;
     if (content) {
-      const snapshot: StateSnapshot = JSON.parse(content);
+      const snapshot: LifecycleSnapshot = JSON.parse(content);
       previousDigest = snapshot.digest;
     }
 
@@ -213,11 +214,11 @@ async function runStateDiffDigest(args: DigestDiffArgs): Promise<number> {
 interface LiveDiffArgs {
   environment: string;
   lexicons: string[];
-  plugins: LexiconPlugin[];
+  plugins: ObservationLexicon[];
   buildResult: BuildResult;
 }
 
-async function runStateDiffLive(args: LiveDiffArgs): Promise<number> {
+async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<number> {
   let totalDrift = 0;
   let totalLexiconsChecked = 0;
 
@@ -256,7 +257,7 @@ async function runStateDiffLive(args: LiveDiffArgs): Promise<number> {
           : (rawOutput as SerializerResult).primary;
 
     // Read previous snapshot once; both flows pull what they need.
-    let prevSnapshot: StateSnapshot | undefined;
+    let prevSnapshot: LifecycleSnapshot | undefined;
     const content = await readSnapshot(args.environment, lexiconName);
     if (content) prevSnapshot = JSON.parse(content);
 
@@ -403,12 +404,123 @@ function renderLiveArtifactDiff(lexiconName: string, environment: string, diff:
 }
 
 /**
- * chant state log [environment]
+ * chant lifecycle plan <environment> [lexicon]
+ *
+ * Promote the live diff to a typed, read-only change set: per-entity
+ * create / update / delete / adopt / noop. Strictly read-only — never
+ * mutates, never deploys. Deletes are never proposed without ownership
+ * data (added in #121); an undeclared live resource is `adopt`.
  */
-export async function runStateLog(ctx: CommandContext): Promise<number> {
+export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
+  const { args, plugins, serializers } = ctx;
+  const environment = args.extraPositional;
+  const lexiconFilter = args.extraPositional2;
+
+  if (!environment) {
+    console.error(formatError({ message: "Environment is required: chant lifecycle plan <environment> [lexicon]" }));
+    return 1;
+  }
+
+  const targetSerializers = lexiconFilter
+    ? plugins.filter((p) => p.name === lexiconFilter).map((p) => p.serializer)
+    : serializers;
+
+  const projectPath = resolve(".");
+  const buildResult = await build(projectPath, targetSerializers);
+  if (buildResult.errors.length > 0) {
+    console.error(formatError({ message: "Build failed — fix errors before planning" }));
+    return 1;
+  }
+
+  await fetchLifecycle();
+
+  const lexicons = lexiconFilter ? [lexiconFilter] : Array.from(buildResult.manifest.lexicons);
+
+  const merged: ChangeSet = { env: environment, entries: [] };
+  let checked = 0;
+
+  for (const lexiconName of lexicons) {
+    const plugin = plugins.find((p) => p.name === lexiconName);
+    if (!plugin) continue;
+    if (!plugin.describeResources) {
+      // Plan is entity-keyed; artifact-only lexicons have no declared axis.
+      if (!args.json) {
+        console.error(formatWarning({
+          message: `${lexiconName}: lexicon does not implement describeResources — skipping (no declared axis to plan against)`,
+        }));
+      }
+      continue;
+    }
+
+    const declared = new Set<string>();
+    const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+    for (const [name, entity] of buildResult.entities) {
+      if (entity.lexicon === lexiconName) {
+        declared.add(name);
+        entities.set(name, {
+          entityType: entity.entityType,
+          props: ("props" in entity && entity.props != null ? entity.props : {}) as Record<string, unknown>,
+        });
+      }
+    }
+
+    const rawOutput = buildResult.outputs.get(lexiconName);
+    const buildOutput =
+      rawOutput === undefined
+        ? ""
+        : typeof rawOutput === "string"
+          ? rawOutput
+          : (rawOutput as SerializerResult).primary;
+
+    let observedNow: Record<string, ResourceMetadata>;
+    try {
+      observedNow = await plugin.describeResources({
+        environment,
+        buildOutput,
+        entityNames: Array.from(declared),
+        entities,
+        owned: args.owned,
+      });
+    } catch (err) {
+      console.error(formatError({
+        message: `${lexiconName}: describeResources failed — ${err instanceof Error ? err.message : String(err)}`,
+      }));
+      continue;
+    }
+
+    const content = await readSnapshot(environment, lexiconName);
+    const observedThen = content ? (JSON.parse(content) as LifecycleSnapshot).resources : undefined;
+
+    const cs = buildChangeSet(environment, { declared, observedNow, observedThen });
+    merged.entries.push(...cs.entries);
+    checked++;
+  }
+
+  if (checked === 0) {
+    console.error(formatWarning({
+      message: "No lexicons implement describeResources — nothing to plan",
+    }));
+    return 1;
+  }
+
+  merged.entries.sort((a, b) => a.name.localeCompare(b.name));
+
+  if (args.json) {
+    console.log(JSON.stringify(merged, null, 2));
+  } else {
+    console.log(renderChangeSet(merged));
+  }
+
+  return 0;
+}
+
+/**
+ * chant lifecycle log [environment]
+ */
+export async function runLifecycleLog(ctx: CommandContext): Promise<number> {
   const environment = ctx.args.extraPositional;
 
-  await fetchState();
+  await fetchLifecycle();
 
   const entries = await listSnapshots({ environment });
   if (entries.length === 0) {
@@ -427,15 +539,15 @@ export async function runStateLog(ctx: CommandContext): Promise<number> {
 /**
  * Fallback for unknown state subcommands.
  */
-export async function runStateUnknown(ctx: CommandContext): Promise<number> {
+export async function runLifecycleUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: `Unknown state subcommand: ${ctx.args.extraPositional ?? ctx.args.path}`,
-    hint: "Available: chant state snapshot, chant state show, chant state diff, chant state log",
+    hint: "Available: chant lifecycle snapshot, chant lifecycle show, chant lifecycle diff, chant lifecycle plan, chant lifecycle log",
   }));
   return 1;
 }
 
-function printSnapshotTable(snapshot: StateSnapshot): void {
+function printSnapshotTable(snapshot: LifecycleSnapshot): void {
   console.log("RESOURCE".padEnd(20) + "TYPE".padEnd(28) + "PHYSICAL ID".padEnd(44) + "STATUS");
   console.log("-".repeat(100));
 

package/src/cli/handlers/misc.ts

@@ -1,6 +1,7 @@
 import { listCommand, printListResult } from "../commands/list";
-import { importCommand, printImportResult } from "../commands/import";
-import { formatError, formatSuccess } from "../format";
+import { importCommand, importFromLive, printImportResult } from "../commands/import";
+import type { ResourceSelector } from "../../lexicon";
+import { formatError, formatSuccess, formatWarning } from "../format";
 import type { CommandContext } from "../registry";
 
 export async function runList(ctx: CommandContext): Promise<number> {
@@ -21,6 +22,34 @@ export async function runList(ctx: CommandContext): Promise<number> {
 }
 
 export async function runImport(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+
+  // `--from <env>` switches import from a template file to a live source.
+  if (args.migrateFrom) {
+    const selector: ResourceSelector | undefined =
+      args.selectType || args.selectName
+        ? { type: args.selectType, name: args.selectName }
+        : undefined;
+
+    // Live config may carry secrets into generated source — warn before writing.
+    console.error(formatWarning({
+      message: "Live import may emit sensitive values (keys, tokens, passwords) into generated source. Review before committing.",
+    }));
+
+    const result = await importFromLive({
+      environment: args.migrateFrom,
+      lexicon: args.lexicon,
+      output: args.output,
+      force: args.force,
+      selector,
+      owned: args.owned,
+      verbatim: args.verbatim,
+    });
+
+    printImportResult(result);
+    return result.success ? 0 : 1;
+  }
+
   const result = await importCommand({
     templatePath: ctx.args.path,
     output: ctx.args.output,