@intentius/chant 0.1.7 → 0.1.9

package/src/state/git.test.ts

@@ -0,0 +1,191 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  writeSnapshot,
+  readSnapshot,
+  readEnvironmentSnapshots,
+  listSnapshots,
+  getHeadCommit,
+  pushState,
+  StaleStateBranchError,
+} from "./git";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  // Need at least one commit so HEAD exists.
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+describe("state/git", () => {
+  test("writeSnapshot creates the orphan branch and writes JSON addressable by readSnapshot", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const json = JSON.stringify({ resources: { bucket: { type: "T", status: "OK" } } });
+      const sha = await writeSnapshot("prod", "aws", json, { cwd: dir });
+      expect(sha).toMatch(/^[0-9a-f]{40}$/);
+
+      const out = await readSnapshot("prod", "aws", { cwd: dir });
+      expect(out).not.toBeNull();
+      expect(JSON.parse(out!)).toEqual(JSON.parse(json));
+    });
+  });
+
+  test("readSnapshot returns null for missing env/lexicon", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const out = await readSnapshot("prod", "aws", { cwd: dir });
+      expect(out).toBeNull();
+    });
+  });
+
+  test("subsequent writes preserve other env+lexicon entries", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "gcp", JSON.stringify({ b: 2 }), { cwd: dir });
+      await writeSnapshot("staging", "aws", JSON.stringify({ c: 3 }), { cwd: dir });
+
+      expect(await readSnapshot("prod", "aws", { cwd: dir })).toBeTruthy();
+      expect(await readSnapshot("prod", "gcp", { cwd: dir })).toBeTruthy();
+      expect(await readSnapshot("staging", "aws", { cwd: dir })).toBeTruthy();
+    });
+  });
+
+  test("re-writing the same env+lexicon updates the entry rather than duplicating", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 2 }), { cwd: dir });
+      const out = await readSnapshot("prod", "aws", { cwd: dir });
+      expect(JSON.parse(out!)).toEqual({ v: 2 });
+    });
+  });
+
+  test("readEnvironmentSnapshots returns all lexicons for an env", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "gcp", JSON.stringify({ b: 2 }), { cwd: dir });
+      const all = await readEnvironmentSnapshots("prod", { cwd: dir });
+      expect([...all.keys()].sort()).toEqual(["aws", "gcp"]);
+    });
+  });
+
+  test("listSnapshots returns commit history of the orphan branch", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 2 }), { cwd: dir });
+      const log = await listSnapshots({ cwd: dir });
+      expect(log.length).toBe(2);
+      expect(log[0].commit).toMatch(/^[0-9a-f]{40}$/);
+    });
+  });
+
+  test("getHeadCommit returns the working-branch HEAD sha", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const head = await getHeadCommit({ cwd: dir });
+      expect(head).toMatch(/^[0-9a-f]{40}$/);
+    });
+  });
+
+  // ── Concurrent push rejection (#30) ─────────────────────────────────────────
+
+  /**
+   * Build a "remote ↔ clone" pair where `clone` has `remote` configured as
+   * `origin`. Returns the clone path; the caller writes snapshots there.
+   */
+  async function setupClonePair(): Promise<{ clonePath: string; remotePath: string; cleanup: () => Promise<void> }> {
+    const remotePath = join(import.meta.dirname ?? "/tmp", `chant-state-remote-${Date.now()}-${Math.random()}`);
+    const clonePath = join(import.meta.dirname ?? "/tmp", `chant-state-clone-${Date.now()}-${Math.random()}`);
+    const { mkdir, rm } = await import("node:fs/promises");
+    await mkdir(remotePath, { recursive: true });
+    git(["init", "-q", "--bare", "-b", "main"], remotePath);
+    git(["clone", "-q", remotePath, clonePath], import.meta.dirname ?? "/tmp");
+    git(["config", "user.email", "test@chant.dev"], clonePath);
+    git(["config", "user.name", "Test"], clonePath);
+    writeFileSync(join(clonePath, "README.md"), "fixture\n");
+    git(["add", "README.md"], clonePath);
+    git(["commit", "-q", "-m", "init"], clonePath);
+    git(["push", "-q", "origin", "main"], clonePath);
+    return {
+      clonePath,
+      remotePath,
+      cleanup: async () => {
+        await rm(remotePath, { recursive: true, force: true });
+        await rm(clonePath, { recursive: true, force: true });
+      },
+    };
+  }
+
+  test("first push to remote succeeds (no remote ref yet)", async () => {
+    const { clonePath, cleanup } = await setupClonePair();
+    try {
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: clonePath });
+      const ok = await pushState({ cwd: clonePath });
+      expect(ok).toBe(true);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("subsequent push from same clone (after fetch) succeeds via lease", async () => {
+    const { clonePath, cleanup } = await setupClonePair();
+    try {
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: clonePath });
+      expect(await pushState({ cwd: clonePath })).toBe(true);
+
+      // Pull the remote ref into local remote-tracking, then commit + push again
+      git(["fetch", "-q", "origin", "+refs/heads/chant/state:refs/remotes/origin/chant/state"], clonePath);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 2 }), { cwd: clonePath });
+      expect(await pushState({ cwd: clonePath })).toBe(true);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("concurrent write rejected: second push throws StaleStateBranchError", async () => {
+    // Simulate two concurrent operators by setting up two clones of the same remote.
+    const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
+    const cloneB = join(import.meta.dirname ?? "/tmp", `chant-state-clone-b-${Date.now()}-${Math.random()}`);
+    try {
+      git(["clone", "-q", remotePath, cloneB], import.meta.dirname ?? "/tmp");
+      git(["config", "user.email", "test@chant.dev"], cloneB);
+      git(["config", "user.name", "Test"], cloneB);
+
+      // Operator A writes + pushes first.
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: cloneA });
+      expect(await pushState({ cwd: cloneA })).toBe(true);
+
+      // Operator B writes from the same baseline (chant/state doesn't exist
+      // on cloneB's remote-tracking yet) and tries to push — should fail
+      // with StaleStateBranchError because A's push moved the remote ref.
+      await writeSnapshot("staging", "gcp", JSON.stringify({ b: 2 }), { cwd: cloneB });
+      await expect(pushState({ cwd: cloneB })).rejects.toBeInstanceOf(StaleStateBranchError);
+    } finally {
+      await cleanup();
+      const { rm } = await import("node:fs/promises");
+      await rm(cloneB, { recursive: true, force: true });
+    }
+  });
+
+  test("StaleStateBranchError carries the expected SHA used as the lease", async () => {
+    const err = new StaleStateBranchError(null, "stale info: ...");
+    expect(err.name).toBe("StaleStateBranchError");
+    expect(err.expected).toBeNull();
+    expect(err.message).toContain("moved");
+  });
+});

package/src/state/git.ts

@@ -22,13 +22,8 @@ export async function writeSnapshot(
   const rt = getRuntime();
   const cwd = opts?.cwd;
 
-  // 1. Write blob
-  const hashResult = await rt.spawn(
-    ["git", "hash-object", "-w", "--stdin"],
-    { cwd },
-  );
-  // hash-object reads from stdin, but spawn doesn't support piping directly.
-  // Use a shell pipeline instead.
+  // 1. Write blob — hash-object reads from stdin, but spawn() doesn't expose
+  // a stdin handle, so we run via a shell pipeline (`echo … | git hash-object`).
   const blobResult = await rt.spawn(
     ["sh", "-c", `echo '${json.replace(/'/g, "'\\''")}' | git hash-object -w --stdin`],
     { cwd },
@@ -179,20 +174,77 @@ export async function listSnapshots(
 }
 
 /**
- * Push the state branch to remote.
+ * Thrown by pushState when the remote chant/state branch has moved since
+ * the local snapshot was prepared — i.e. another snapshot for this or a
+ * different env was pushed concurrently. The caller should fetch and retry.
+ */
+export class StaleStateBranchError extends Error {
+  readonly expected: string | null;
+  constructor(expected: string | null, stderr: string) {
+    super(
+      "chant/state remote branch has moved since this run started — " +
+      "another snapshot was pushed concurrently. " +
+      `git stderr: ${stderr.trim()}`,
+    );
+    this.name = "StaleStateBranchError";
+    this.expected = expected;
+  }
+}
+
+/**
+ * Look up the remote-tracking SHA for chant/state, if any. Returns null when
+ * the remote ref doesn't exist locally yet (e.g. first-ever snapshot).
+ */
+export async function getRemoteStateBranchSha(
+  remote: string,
+  opts?: { cwd?: string },
+): Promise<string | null> {
+  const rt = getRuntime();
+  const ref = `refs/remotes/${remote}/${STATE_BRANCH}`;
+  const result = await rt.spawn(["git", "rev-parse", "--verify", ref], { cwd: opts?.cwd });
+  if (result.exitCode !== 0) return null;
+  return result.stdout.trim() || null;
+}
+
+/**
+ * Push the state branch to remote with --force-with-lease.
+ *
+ * If the remote chant/state ref has advanced past the local remote-tracking
+ * SHA captured at the start of this push, the push is rejected and we throw
+ * StaleStateBranchError so the caller can surface a recovery hint.
+ *
+ * Returns false (without throwing) only when no remote is configured at all.
  */
 export async function pushState(opts?: { cwd?: string }): Promise<boolean> {
   const rt = getRuntime();
-  // Check if remote exists
   const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
   if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
 
   const remote = remoteResult.stdout.trim().split("\n")[0];
+
+  // Capture the lease SHA — if null, the remote ref doesn't exist yet
+  // (first-time push) and we send `--force-with-lease=ref:` (empty SHA),
+  // which git interprets as "ref does not exist on remote".
+  const expected = await getRemoteStateBranchSha(remote, opts);
+  const lease = `refs/heads/${STATE_BRANCH}:${expected ?? ""}`;
+
   const pushResult = await rt.spawn(
-    ["git", "push", remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
+    ["git", "push", `--force-with-lease=${lease}`, remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
     { cwd: opts?.cwd },
   );
-  return pushResult.exitCode === 0;
+
+  if (pushResult.exitCode !== 0) {
+    const stderr = pushResult.stderr ?? "";
+    if (
+      stderr.includes("stale info") ||
+      stderr.includes("rejected") ||
+      stderr.includes("non-fast-forward")
+    ) {
+      throw new StaleStateBranchError(expected, stderr);
+    }
+    return false;
+  }
+  return true;
 }
 
 /**

package/src/state/live-diff.test.ts

@@ -0,0 +1,184 @@
+import { describe, test, expect } from "vitest";
+import { diffLive, diffLiveArtifacts } from "./live-diff";
+import type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
+
+const meta = (overrides: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
+  type: "AWS::S3::Bucket",
+  status: "CREATE_COMPLETE",
+  physicalId: "bucket-1",
+  ...overrides,
+});
+
+describe("diffLive", () => {
+  test("empty inputs produce empty result", () => {
+    const result = diffLive({
+      declared: new Set(),
+      observedNow: {},
+      observedThen: undefined,
+    });
+    expect(result).toEqual({
+      missing: [],
+      orphan: [],
+      disappeared: [],
+      newlyObserved: [],
+      driftedSinceSnapshot: [],
+      unchanged: [],
+    });
+  });
+
+  test("declared but not observed → missing", () => {
+    const result = diffLive({
+      declared: new Set(["bucket"]),
+      observedNow: {},
+      observedThen: undefined,
+    });
+    expect(result.missing).toEqual(["bucket"]);
+  });
+
+  test("observed but not declared → orphan", () => {
+    const result = diffLive({
+      declared: new Set(),
+      observedNow: { abandoned: meta() },
+      observedThen: undefined,
+    });
+    expect(result.orphan).toEqual(["abandoned"]);
+  });
+
+  test("in previous snapshot but not observed now → disappeared", () => {
+    const result = diffLive({
+      declared: new Set(["bucket"]),
+      observedNow: {},
+      observedThen: { bucket: meta() },
+    });
+    expect(result.missing).toEqual(["bucket"]);
+    expect(result.disappeared).toEqual(["bucket"]);
+  });
+
+  test("observed for the first time (declared, no previous snapshot) → newlyObserved", () => {
+    const result = diffLive({
+      declared: new Set(["bucket"]),
+      observedNow: { bucket: meta() },
+      observedThen: {},
+    });
+    expect(result.newlyObserved).toEqual(["bucket"]);
+    expect(result.unchanged).toEqual([]);
+    expect(result.driftedSinceSnapshot).toEqual([]);
+  });
+
+  test("attribute changed between snapshots → driftedSinceSnapshot with attribute path", () => {
+    const result = diffLive({
+      declared: new Set(["bucket"]),
+      observedNow: { bucket: meta({ status: "UPDATE_COMPLETE", attributes: { tags: { env: "prod" } } }) },
+      observedThen: { bucket: meta({ status: "CREATE_COMPLETE", attributes: { tags: { env: "stage" } } }) },
+    });
+    expect(result.driftedSinceSnapshot).toHaveLength(1);
+    const drift = result.driftedSinceSnapshot[0];
+    expect(drift.name).toBe("bucket");
+    expect(drift.type).toBe("AWS::S3::Bucket");
+    const paths = drift.changes.map((c) => c.path).sort();
+    expect(paths).toEqual(["attributes.tags", "status"]);
+  });
+
+  test("identical metadata between snapshots → unchanged", () => {
+    const sameMeta = meta({ attributes: { tags: { env: "prod" } } });
+    const result = diffLive({
+      declared: new Set(["bucket"]),
+      observedNow: { bucket: sameMeta },
+      observedThen: { bucket: sameMeta },
+    });
+    expect(result.unchanged).toEqual(["bucket"]);
+    expect(result.driftedSinceSnapshot).toEqual([]);
+  });
+
+  test("mixed: counts add up across all six categories", () => {
+    const result = diffLive({
+      declared: new Set(["a", "b", "c", "d"]),
+      observedNow: {
+        b: meta(),                                // unchanged
+        c: meta({ status: "UPDATE_COMPLETE" }),   // drift
+        d: meta(),                                // newlyObserved
+        e: meta(),                                // orphan
+      },
+      observedThen: {
+        a: meta(),  // disappeared (and missing, since declared)
+        b: meta(),  // unchanged
+        c: meta(),  // drift
+      },
+    });
+    expect(result.missing).toEqual(["a"]);
+    expect(result.orphan).toEqual(["e"]);
+    expect(result.disappeared).toEqual(["a"]);
+    expect(result.newlyObserved).toEqual(["d"]);
+    expect(result.driftedSinceSnapshot.map((d) => d.name)).toEqual(["c"]);
+    expect(result.unchanged).toEqual(["b"]);
+  });
+});
+
+describe("diffLiveArtifacts", () => {
+  const a = (overrides: Partial<ArtifactMetadata> = {}): ArtifactMetadata => ({
+    type: "Helm::Release",
+    physicalId: "default/foo",
+    status: "deployed",
+    ...overrides,
+  });
+
+  test("empty inputs produce empty result", () => {
+    expect(diffLiveArtifacts({ observedNow: {}, observedThen: undefined })).toEqual({
+      added: [], removed: [], changed: [], unchanged: [],
+    });
+  });
+
+  test("observed now, no previous snapshot → added", () => {
+    const result = diffLiveArtifacts({
+      observedNow: { "release/default/foo": a() },
+      observedThen: undefined,
+    });
+    expect(result.added).toEqual(["release/default/foo"]);
+  });
+
+  test("in previous snapshot, gone now → removed", () => {
+    const result = diffLiveArtifacts({
+      observedNow: {},
+      observedThen: { "release/default/foo": a() },
+    });
+    expect(result.removed).toEqual(["release/default/foo"]);
+  });
+
+  test("metadata differs between snapshots → changed", () => {
+    const result = diffLiveArtifacts({
+      observedNow:  { "release/default/foo": a({ status: "failed" }) },
+      observedThen: { "release/default/foo": a({ status: "deployed" }) },
+    });
+    expect(result.changed).toHaveLength(1);
+    expect(result.changed[0].name).toBe("release/default/foo");
+    expect(result.changed[0].changes.map((c) => c.path)).toContain("status");
+  });
+
+  test("identical metadata → unchanged", () => {
+    const same = a();
+    const result = diffLiveArtifacts({
+      observedNow:  { "release/default/foo": same },
+      observedThen: { "release/default/foo": same },
+    });
+    expect(result.unchanged).toEqual(["release/default/foo"]);
+  });
+
+  test("mixed: counts add up across all four categories", () => {
+    const result = diffLiveArtifacts({
+      observedNow: {
+        "release/default/b": a(),                          // unchanged
+        "release/default/c": a({ status: "failed" }),      // changed
+        "release/default/d": a(),                          // added
+      },
+      observedThen: {
+        "release/default/a": a(),                          // removed
+        "release/default/b": a(),                          // unchanged
+        "release/default/c": a(),                          // changed
+      },
+    });
+    expect(result.added).toEqual(["release/default/d"]);
+    expect(result.removed).toEqual(["release/default/a"]);
+    expect(result.changed.map((c) => c.name)).toEqual(["release/default/c"]);
+    expect(result.unchanged).toEqual(["release/default/b"]);
+  });
+});

package/src/state/live-diff.ts

@@ -0,0 +1,215 @@
+/**
+ * Live-state diff: compares declared vs observed-now vs observed-then.
+ *
+ * Produces structured drift signal — *what is in the cloud right now* against
+ * both *what was declared in source* and *what was observed at the last
+ * snapshot*. Pure function; all I/O happens in the caller.
+ *
+ * Two diff flavors:
+ *   - diffLive       — entity-keyed (declared ↔ observedNow ↔ observedThen)
+ *   - diffLiveArtifacts — context-keyed (observedNow ↔ observedThen only;
+ *                        no `declared` axis since artifacts aren't declared
+ *                        as chant entities — they're created by tooling
+ *                        outside chant's entity model)
+ */
+import type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
+
+export interface AttributeChange {
+  /** Attribute path (e.g. "status", "physicalId", "attributes.tags.env"). */
+  path: string;
+  oldValue: unknown;
+  newValue: unknown;
+}
+
+export interface ResourceDrift {
+  name: string;
+  type: string;
+  changes: AttributeChange[];
+}
+
+export interface LiveDiffResult {
+  /** Declared in current build, but not observed in cloud right now. */
+  missing: string[];
+  /** Observed in cloud right now, but not declared. */
+  orphan: string[];
+  /** Was in last snapshot but isn't observed now. */
+  disappeared: string[];
+  /** Observed now and declared, but not in the previous snapshot. */
+  newlyObserved: string[];
+  /** Observed both then and now; metadata changed. */
+  driftedSinceSnapshot: ResourceDrift[];
+  /** Observed both then and now; metadata identical. */
+  unchanged: string[];
+}
+
+export interface DiffLiveInput {
+  /** Entity names from the current build. */
+  declared: Set<string>;
+  /** Resources returned by `plugin.describeResources()` right now. */
+  observedNow: Record<string, ResourceMetadata>;
+  /** Resources captured by the previous snapshot, if any. */
+  observedThen: Record<string, ResourceMetadata> | undefined;
+}
+
+const TRACKED_FIELDS: Array<keyof ResourceMetadata> = [
+  "status",
+  "physicalId",
+  "lastUpdated",
+];
+
+function compareMetadata(
+  oldMeta: ResourceMetadata,
+  newMeta: ResourceMetadata,
+): AttributeChange[] {
+  const changes: AttributeChange[] = [];
+
+  for (const field of TRACKED_FIELDS) {
+    if (oldMeta[field] !== newMeta[field]) {
+      changes.push({ path: field, oldValue: oldMeta[field], newValue: newMeta[field] });
+    }
+  }
+
+  const oldAttrs = oldMeta.attributes ?? {};
+  const newAttrs = newMeta.attributes ?? {};
+  const allAttrKeys = new Set([...Object.keys(oldAttrs), ...Object.keys(newAttrs)]);
+  for (const key of allAttrKeys) {
+    const oldValue = oldAttrs[key];
+    const newValue = newAttrs[key];
+    if (!shallowEqual(oldValue, newValue)) {
+      changes.push({ path: `attributes.${key}`, oldValue, newValue });
+    }
+  }
+
+  return changes;
+}
+
+function shallowEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  if (typeof a !== "object" || typeof b !== "object") return false;
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+export function diffLive(input: DiffLiveInput): LiveDiffResult {
+  const { declared, observedNow, observedThen } = input;
+  const observedThenMap = observedThen ?? {};
+  const observedNowNames = new Set(Object.keys(observedNow));
+  const observedThenNames = new Set(Object.keys(observedThenMap));
+
+  const missing: string[] = [];
+  const orphan: string[] = [];
+  const disappeared: string[] = [];
+  const newlyObserved: string[] = [];
+  const driftedSinceSnapshot: ResourceDrift[] = [];
+  const unchanged: string[] = [];
+
+  // Declared but not observed in cloud right now → missing
+  for (const name of declared) {
+    if (!observedNowNames.has(name)) {
+      missing.push(name);
+    }
+  }
+
+  // In cloud right now but not declared → orphan
+  for (const name of observedNowNames) {
+    if (!declared.has(name)) {
+      orphan.push(name);
+    }
+  }
+
+  // In previous snapshot but not observed now → disappeared
+  for (const name of observedThenNames) {
+    if (!observedNowNames.has(name)) {
+      disappeared.push(name);
+    }
+  }
+
+  // Observed now: classify drift relative to previous snapshot
+  for (const name of observedNowNames) {
+    const now = observedNow[name];
+    const then = observedThenMap[name];
+    if (!then) {
+      if (declared.has(name)) {
+        newlyObserved.push(name);
+      }
+      // else: orphan, already classified above
+      continue;
+    }
+    const changes = compareMetadata(then, now);
+    if (changes.length === 0) {
+      unchanged.push(name);
+    } else {
+      driftedSinceSnapshot.push({
+        name,
+        type: now.type,
+        changes,
+      });
+    }
+  }
+
+  return {
+    missing: missing.sort(),
+    orphan: orphan.sort(),
+    disappeared: disappeared.sort(),
+    newlyObserved: newlyObserved.sort(),
+    driftedSinceSnapshot: driftedSinceSnapshot.sort((a, b) => a.name.localeCompare(b.name)),
+    unchanged: unchanged.sort(),
+  };
+}
+
+// ── Artifact diff (no `declared` axis) ──────────────────────────────────────
+
+export interface LiveArtifactDiffResult {
+  /** Observed now, not in previous snapshot. */
+  added: string[];
+  /** In previous snapshot, not observed now. */
+  removed: string[];
+  /** In both; metadata changed. */
+  changed: ResourceDrift[];
+  /** In both; metadata identical. */
+  unchanged: string[];
+}
+
+export interface DiffLiveArtifactsInput {
+  /** Artifacts returned by `plugin.listArtifacts()` right now. */
+  observedNow: Record<string, ArtifactMetadata>;
+  /** Artifacts captured by the previous snapshot, if any. */
+  observedThen: Record<string, ArtifactMetadata> | undefined;
+}
+
+export function diffLiveArtifacts(input: DiffLiveArtifactsInput): LiveArtifactDiffResult {
+  const observedThenMap = input.observedThen ?? {};
+  const nowNames = new Set(Object.keys(input.observedNow));
+  const thenNames = new Set(Object.keys(observedThenMap));
+
+  const added: string[] = [];
+  const removed: string[] = [];
+  const changed: ResourceDrift[] = [];
+  const unchanged: string[] = [];
+
+  for (const name of nowNames) {
+    if (!thenNames.has(name)) {
+      added.push(name);
+      continue;
+    }
+    const now = input.observedNow[name];
+    const then = observedThenMap[name];
+    const diffs = compareMetadata(then, now);
+    if (diffs.length === 0) {
+      unchanged.push(name);
+    } else {
+      changed.push({ name, type: now.type, changes: diffs });
+    }
+  }
+
+  for (const name of thenNames) {
+    if (!nowNames.has(name)) removed.push(name);
+  }
+
+  return {
+    added: added.sort(),
+    removed: removed.sort(),
+    changed: changed.sort((a, b) => a.name.localeCompare(b.name)),
+    unchanged: unchanged.sort(),
+  };
+}