@intentius/chant 0.1.7 → 0.1.8

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(),
+  };
+}

package/src/state/snapshot.test.ts

@@ -0,0 +1,171 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import { createMockPlugin, staticDescribeResources, staticListArtifacts } from "@intentius/chant-test-utils";
+import type { BuildResult } from "../build";
+
+const writeSnapshotMock = vi.fn();
+const getHeadCommitMock = vi.fn();
+const pushStateMock = vi.fn();
+
+vi.mock("./git", () => ({
+  writeSnapshot: (...args: unknown[]) => writeSnapshotMock(...args),
+  getHeadCommit: () => getHeadCommitMock(),
+  pushState: () => pushStateMock(),
+}));
+
+const { takeSnapshot } = await import("./snapshot");
+
+function makeBuildResult(entitiesByLexicon: Record<string, string[]>): BuildResult {
+  const entities = new Map();
+  for (const [lexicon, names] of Object.entries(entitiesByLexicon)) {
+    for (const name of names) entities.set(name, { lexicon, entityType: `${lexicon}::Mock`, props: {} });
+  }
+  return {
+    outputs: new Map(Object.keys(entitiesByLexicon).map((l) => [l, "{}"])),
+    entities,
+    dependencies: new Map(),
+    errors: [],
+    warnings: [],
+    manifest: { lexicons: Object.keys(entitiesByLexicon), outputs: {}, deployOrder: [] },
+    sourceFileCount: 1,
+  } as unknown as BuildResult;
+}
+
+describe("takeSnapshot", () => {
+  beforeEach(() => {
+    writeSnapshotMock.mockReset();
+    getHeadCommitMock.mockReset();
+    pushStateMock.mockReset();
+    writeSnapshotMock.mockResolvedValue("commit-sha");
+    getHeadCommitMock.mockResolvedValue("head-sha");
+    pushStateMock.mockResolvedValue(true);
+  });
+
+  test("happy path: writes snapshot per plugin with describeResources", async () => {
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: staticDescribeResources({
+        bucket: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE", physicalId: "bucket-1" },
+      }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["bucket"] }));
+    expect(result.snapshots).toHaveLength(1);
+    expect(result.snapshots[0]).toMatchObject({
+      lexicon: "aws",
+      environment: "prod",
+      commit: "head-sha",
+      resources: { bucket: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE" } },
+    });
+    expect(writeSnapshotMock).toHaveBeenCalledTimes(1);
+    expect(pushStateMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("plugin without describeResources is skipped", async () => {
+    const plugin = createMockPlugin({ name: "aws" });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["x"] }));
+    expect(result.snapshots).toEqual([]);
+    expect(writeSnapshotMock).not.toHaveBeenCalled();
+  });
+
+  test("plugin throws → captured as error, other plugins still proceed", async () => {
+    const broken = createMockPlugin({
+      name: "broken",
+      describeResources: async () => { throw new Error("boom"); },
+    });
+    const ok = createMockPlugin({
+      name: "ok",
+      describeResources: staticDescribeResources({ x: { type: "T", status: "OK" } }),
+    });
+    const result = await takeSnapshot("prod", [broken, ok], makeBuildResult({ broken: ["b"], ok: ["x"] }));
+    expect(result.errors.some((e) => e.includes("broken") && e.includes("boom"))).toBe(true);
+    expect(result.snapshots.map((s) => s.lexicon)).toEqual(["ok"]);
+  });
+
+  test("plugin returns no valid resources → error and no snapshot", async () => {
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: async () => ({}), // empty
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: [] }));
+    expect(result.snapshots).toEqual([]);
+    expect(result.errors.some((e) => e.includes("aws") && e.includes("no valid"))).toBe(true);
+  });
+
+  test("resources missing required type/status are dropped with warning", async () => {
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: staticDescribeResources({
+        valid:   { type: "T", status: "OK" },
+        bad:     { type: "", status: "OK" } as never,
+      }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["valid"] }));
+    expect(result.snapshots[0].resources).toEqual({ valid: { type: "T", status: "OK" } });
+    expect(result.warnings.some((w) => w.includes("Dropped bad"))).toBe(true);
+  });
+
+  test("emits sensitive-data warnings for suspect attribute names", async () => {
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: staticDescribeResources({
+        cred: {
+          type: "T",
+          status: "OK",
+          attributes: { connectionString: "redacted", regularAttr: "x" },
+        },
+      }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["cred"] }));
+    expect(result.warnings.some((w) => w.toLowerCase().includes("sensitive"))).toBe(true);
+  });
+
+  // ── listArtifacts() integration (#51) ─────────────────────────────────────
+
+  test("calls listArtifacts when implemented and stores artifacts in snapshot", async () => {
+    const plugin = createMockPlugin({
+      name: "helm",
+      listArtifacts: staticListArtifacts({
+        "release/default/web": { type: "Helm::Release", physicalId: "default/web", status: "deployed" },
+      }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ helm: [] }));
+    expect(result.snapshots).toHaveLength(1);
+    expect(result.snapshots[0].artifacts).toEqual({
+      "release/default/web": { type: "Helm::Release", physicalId: "default/web", status: "deployed" },
+    });
+    expect(result.snapshots[0].resources).toEqual({});
+  });
+
+  test("plugin can implement both describeResources and listArtifacts", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: staticDescribeResources({
+        web: { type: "K8s::Apps::Deployment", status: "READY" },
+      }),
+      listArtifacts: staticListArtifacts({
+        "release/default/proxy": { type: "Helm::Release", status: "deployed" },
+      }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ k8s: ["web"] }));
+    expect(result.snapshots[0].resources).toEqual({
+      web: { type: "K8s::Apps::Deployment", status: "READY" },
+    });
+    expect(result.snapshots[0].artifacts).toBeDefined();
+    expect(result.snapshots[0].artifacts!["release/default/proxy"]).toBeDefined();
+  });
+
+  test("plugin with neither method is skipped (existing behavior preserved)", async () => {
+    const plugin = createMockPlugin({ name: "noop" });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ noop: ["x"] }));
+    expect(result.snapshots).toEqual([]);
+  });
+
+  test("listArtifacts only, empty result → error 'no valid resources or artifacts returned'", async () => {
+    const plugin = createMockPlugin({
+      name: "helm",
+      listArtifacts: async () => ({}),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ helm: [] }));
+    expect(result.errors.some((e) => e.includes("helm") && e.includes("no valid"))).toBe(true);
+    expect(result.snapshots).toEqual([]);
+  });
+});

package/src/state/snapshot.ts

@@ -2,7 +2,7 @@
  * Snapshot orchestration: queries plugins for deployed resource metadata,
  * assembles StateSnapshots, computes build digests, and writes to git.
  */
-import type { LexiconPlugin, ResourceMetadata } from "../lexicon";
+import type { LexiconPlugin, ResourceMetadata, ArtifactMetadata } from "../lexicon";
 import type { BuildResult } from "../build";
 import type { SerializerResult } from "../serializer";
 import type { StateSnapshot } from "./types";
@@ -95,7 +95,7 @@ export async function takeSnapshot(
   const digest = computeBuildDigest(buildResult);
 
   for (const plugin of plugins) {
-    if (!plugin.describeResources) continue;
+    if (!plugin.describeResources && !plugin.listArtifacts) continue;
 
     // Get serialized build output for this lexicon
     const rawOutput = buildResult.outputs.get(plugin.name);
@@ -106,33 +106,52 @@ export async function takeSnapshot(
           ? rawOutput
           : (rawOutput as SerializerResult).primary;
 
-    // Get entity names for this lexicon
+    // Get entity names + entity props for this lexicon
     const entityNames: string[] = [];
+    const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
     for (const [name, entity] of buildResult.entities) {
       if (entity.lexicon === plugin.name) {
         entityNames.push(name);
+        entities.set(name, {
+          entityType: entity.entityType,
+          props: ("props" in entity && entity.props != null
+            ? entity.props
+            : {}) as Record<string, unknown>,
+        });
       }
     }
 
-    try {
-      const resources = await plugin.describeResources({
-        environment,
-        buildOutput,
-        entityNames,
-      });
+    let resources: Record<string, ResourceMetadata> = {};
+    let artifacts: Record<string, ArtifactMetadata> = {};
 
-      const { valid, dropped, warnings: validationWarnings } =
-        validateResources(resources);
-      warnings.push(...validationWarnings);
+    try {
+      if (plugin.describeResources) {
+        const raw = await plugin.describeResources({
+          environment,
+          buildOutput,
+          entityNames,
+          entities,
+        });
+        const { valid, dropped, warnings: validationWarnings } = validateResources(raw);
+        warnings.push(...validationWarnings);
+        if (dropped.length > 0) {
+          warnings.push(`${plugin.name}: dropped ${dropped.length} invalid resource(s)`);
+        }
+        resources = valid;
+      }
 
-      if (dropped.length > 0) {
-        warnings.push(
-          `${plugin.name}: dropped ${dropped.length} invalid resource(s)`,
-        );
+      if (plugin.listArtifacts) {
+        const raw = await plugin.listArtifacts({ environment, entities });
+        const { valid, dropped, warnings: validationWarnings } = validateResources(raw);
+        warnings.push(...validationWarnings);
+        if (dropped.length > 0) {
+          warnings.push(`${plugin.name}: dropped ${dropped.length} invalid artifact(s)`);
+        }
+        artifacts = valid;
       }
 
-      if (Object.keys(valid).length === 0) {
-        errors.push(`${plugin.name}: no valid resources returned`);
+      if (Object.keys(resources).length === 0 && Object.keys(artifacts).length === 0) {
+        errors.push(`${plugin.name}: no valid resources or artifacts returned`);
         continue;
       }
 
@@ -141,7 +160,8 @@ export async function takeSnapshot(
         environment,
         commit: headCommit,
         timestamp,
-        resources: valid,
+        resources,
+        ...(Object.keys(artifacts).length > 0 && { artifacts }),
         digest,
       };
 

package/src/state/types.ts

@@ -1,6 +1,6 @@
-import type { ResourceMetadata } from "../lexicon";
+import type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
 
-export type { ResourceMetadata } from "../lexicon";
+export type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
 
 /**
  * State snapshot for a single lexicon in an environment.
@@ -14,6 +14,8 @@ export interface StateSnapshot {
   timestamp: string;
   /** Resource metadata keyed by logical name */
   resources: Record<string, ResourceMetadata>;
+  /** Artifact metadata keyed by server-side identifier (lexicon-specific). */
+  artifacts?: Record<string, ArtifactMetadata>;
   /** Build digest at snapshot time — what was declared when this snapshot was taken */
   digest?: BuildDigest;
 }