@intentius/chant 0.50.0 → 0.51.0

package/src/lifecycle/replay.ts

@@ -17,7 +17,7 @@
 import { readEnvironmentSnapshots } from "./git";
 import { unqualifiedKey } from "./identity";
 import type { LiveObservation } from "../graph-ir";
-import type { LifecycleSnapshot } from "./types";
+import type { LifecycleSnapshot, ObservationDepth } from "./types";
 
 /**
  * Rebuild observations from a recorded snapshot (#1266).
@@ -52,7 +52,10 @@ export async function replaySnapshots(
   environment: string,
   ref: string,
   scopedStacks: Set<string>,
-): Promise<{ observations: LiveObservation[]; commit: string; timestamp: string } | { error: string; hint?: string }> {
+): Promise<
+  | { observations: LiveObservation[]; commit: string; timestamp: string; depth: ObservationDepth }
+  | { error: string; hint?: string }
+> {
   if (ref !== "latest" && ref !== "true") {
     return {
       error: `chant search --at only accepts "latest" for now, got "${ref}"`,
@@ -69,6 +72,10 @@ export async function replaySnapshots(
   const observations: LiveObservation[] = [];
   let commit = "";
   let timestamp = "";
+  // "deep" when ANY recorded lexicon read that deep — a consumer comparing
+  // against this replay (#1268) needs to know a richer record exists, even
+  // though a replay itself only ever turns `resources` back into identity.
+  let depth: ObservationDepth = "identity";
   // Ambient and dependency resources are keyed by physical id and are
   // account-level: the default security group three stacks each recorded is one
   // group, not three. Managed resources are stack-qualified below and cannot
@@ -187,6 +194,7 @@ export async function replaySnapshots(
     if (!timestamp || (snapshot.timestamp && snapshot.timestamp < timestamp)) {
       timestamp = snapshot.timestamp ?? timestamp;
     }
+    if (snapshot.depth === "deep") depth = "deep";
   }
-  return { observations, commit, timestamp };
+  return { observations, commit, timestamp, depth };
 }

package/src/op/local-executor.ts

@@ -21,7 +21,13 @@ import { isStepOutputRef } from "./step-output-ref";
 export interface StepRecord {
   phase: string;
   fn: string;
-  args: Record<string, unknown>;
+  /**
+   * Present for a local-executor record. Absent for one reconstructed from
+   * Temporal workflow history (op-progress.ts) — an activity's scheduled
+   * input isn't decoded there, so the field is simply omitted rather than
+   * populated with a guess.
+   */
+  args?: Record<string, unknown>;
   status: "ok" | "fail" | "skipped";
   durationMs: number;
   outcome?: { name: string; value: unknown };

package/src/op/local-output.ts

@@ -33,7 +33,7 @@ export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
       write(`[phase] ${currentPhase}`);
     }
     const mark = record.status === "ok" ? "✓" : record.status === "fail" ? "✗" : "•";
-    const call = `${record.fn}(${formatArgs(record.args)})`;
+    const call = `${record.fn}(${formatArgs(record.args ?? {})})`;
     if (record.status === "skipped") {
       write(`  ${mark} ${call}   skipped`);
     } else {

package/src/testing.test.ts

@@ -3,8 +3,14 @@ import { mkdir, writeFile, rm } from "node:fs/promises";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { createMockPlugin } from "@intentius/chant-test-utils";
-import { deployStack, testEnvName, TeardownIncompleteError } from "./testing";
+import { createMockPlugin, staticObservation } from "@intentius/chant-test-utils";
+import {
+  deployStack,
+  testEnvName,
+  TeardownIncompleteError,
+  LiveAssertionError,
+  UnobservedAssertionError,
+} from "./testing";
 import type { ActivityFn } from "./op/activity-registry";
 import type { TeardownExecution } from "./lexicon";
 
@@ -258,4 +264,85 @@ describe("deployStack", () => {
     await expect(deployStack(harness(nativeApply, { applyTargets: {} }))).rejects.toThrow(/nothing to deploy/);
     expect(nativeApply).not.toHaveBeenCalled();
   });
+
+  describe("assertLive", () => {
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => ({ applied: 1, pruned: 0, notAttempted: 0 }));
+
+    test("resolves the metadata for an entity observed present and marker-matched", async () => {
+      await writeProject(dir);
+      const plugin = createMockPlugin({
+        name: "mock",
+        describeResources: (opts) =>
+          Promise.resolve({
+            bucket: { type: "Mock::Bucket", status: "READY", marker: { stack: "harness-fixture", env: opts.environment } },
+          }),
+      });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      const meta = await stack.assertLive("bucket");
+      expect(meta.status).toBe("READY");
+    });
+
+    test("checks status when given", async () => {
+      await writeProject(dir);
+      const plugin = createMockPlugin({
+        name: "mock",
+        describeResources: (opts) =>
+          Promise.resolve({
+            bucket: { type: "Mock::Bucket", status: "READY", marker: { stack: "harness-fixture", env: opts.environment } },
+          }),
+      });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      await expect(stack.assertLive("bucket", { status: "READY" })).resolves.toBeDefined();
+      await expect(stack.assertLive("bucket", { status: "GONE" })).rejects.toThrow(LiveAssertionError);
+    });
+
+    test("throws naming the entity when observed absent", async () => {
+      await writeProject(dir);
+      const plugin = createMockPlugin({ name: "mock", describeResources: staticObservation({}) });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      await expect(stack.assertLive("bucket")).rejects.toThrow(/bucket.*observed absent/s);
+    });
+
+    test("throws UnobservedAssertionError, not a plain failure, when NOT-OBSERVED", async () => {
+      await writeProject(dir);
+      const plugin = createMockPlugin({
+        name: "mock",
+        describeResources: staticObservation({}, { bucket: { reason: "no-binding", type: "Mock::Bucket" } }),
+      });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      const err = await stack.assertLive("bucket").then(
+        () => undefined,
+        (e: unknown) => e,
+      );
+      expect(err).toBeInstanceOf(UnobservedAssertionError);
+      expect(err).not.toBeInstanceOf(LiveAssertionError);
+    });
+
+    test("throws when the observed resource carries another environment's marker — a same-named leftover cannot satisfy it", async () => {
+      await writeProject(dir);
+      const plugin = createMockPlugin({
+        name: "mock",
+        describeResources: staticObservation({
+          bucket: { type: "Mock::Bucket", status: "READY", marker: { stack: "harness-fixture", env: "test-someone-else-000000" } },
+        }),
+      });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      await expect(stack.assertLive("bucket")).rejects.toThrow(/not this deploy's/);
+    });
+
+    test("an unknown entity name throws before any read is attempted", async () => {
+      await writeProject(dir);
+      const describeResources = vi.fn(staticObservation({}));
+      const plugin = createMockPlugin({ name: "mock", describeResources });
+      const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+      await expect(stack.assertLive("nope")).rejects.toThrow(/no such entity/);
+      expect(describeResources).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/testing.ts

@@ -15,6 +15,12 @@
  *   in-process for exactly this suite's environment. Stateless by design:
  *   a crashed suite's environment is recovered by calling destroy again (or
  *   `chant lifecycle teardown <env> --yes`).
+ * - **assertLive** (#1857) — `describeResources()` against exactly one
+ *   declared entity, turned into a pass or a thrown failure. Preserves
+ *   #1089's tri-state rather than collapsing it: NOT-OBSERVED throws {@link
+ *   UnobservedAssertionError}, never a silent pass and never an ordinary
+ *   failure, because chant could not read the entity is not the same claim
+ *   as chant read it and it is gone.
  *
  * ## Isolation
  *
@@ -44,7 +50,7 @@ import { basename, join, resolve } from "node:path";
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { build } from "./build";
-import type { Declarable } from "./declarable";
+import { isResourceDeclarable, type Declarable } from "./declarable";
 import type { SerializerResult } from "./serializer";
 import {
   loadChantConfigUpward,
@@ -55,12 +61,20 @@ import { resolveBuildParams, type BuildParamValue } from "./build-params";
 import { ENV_VAR, unknownEnvError } from "./env";
 import { applyLiveEndpoint } from "./live-endpoint";
 import { loadPlugins, resolveProjectLexicons, collectBuildRootContributors } from "./cli/plugins";
-import type { LexiconPlugin } from "./lexicon";
+import type { LexiconPlugin, ResourceMetadata } from "./lexicon";
 import type { OwnershipMarker } from "./ownership";
 import { runOpLocally } from "./op/local-executor";
 import { loadActivities, loadProfiles, type ActivityFn, type ActivityProfile } from "./op/activity-registry";
 import type { OpConfig, ActivityStep } from "./op/types";
 import { executeTeardown, type TeardownReport } from "./lifecycle/teardown";
+import {
+  assertLiveEntity,
+  LiveAssertionError,
+  UnobservedAssertionError,
+  type AssertLiveOptions,
+} from "./lifecycle/assert-live";
+
+export { LiveAssertionError, UnobservedAssertionError, type AssertLiveOptions };
 
 /**
  * Which `nativeApply` target deploys each lexicon's built output. Only these
@@ -118,6 +132,19 @@ export interface DeployedStack {
   entities: Map<string, Declarable>;
   /** The environment this deploy targeted — the teardown key. */
   env: string;
+  /**
+   * Assert that a declared entity is live: observed present in this
+   * deploy's environment, not confirmed as another stack/env's resource,
+   * and — when `status` is given — reporting that status.
+   *
+   * Rides the observation contract (#1089): an entity `describeResources`
+   * could not cover throws {@link UnobservedAssertionError}, never a pass
+   * and never a plain failure — NOT-OBSERVED is not the same claim as
+   * absent. Observed-absent, a confirmed-foreign identity, or a status
+   * mismatch throws {@link LiveAssertionError}. Resolves to the entity's
+   * `ResourceMetadata` on success.
+   */
+  assertLive(name: string, options?: AssertLiveOptions): Promise<ResourceMetadata>;
   /**
    * Tear down everything carrying this suite's marker `{ stack, env }`.
    * Throws {@link TeardownIncompleteError} when any candidate failed to
@@ -321,6 +348,39 @@ export async function deployStack(options: DeployStackOptions): Promise<Deployed
     applied.restore();
   }
 
+  const assertLive = async (name: string, assertOptions: AssertLiveOptions = {}): Promise<ResourceMetadata> => {
+    const entity = result.entities.get(name);
+    if (!entity) {
+      throw new LiveAssertionError(
+        `assertLive("${name}"): no such entity — this deploy built ${[...result.entities.keys()].join(", ") || "nothing"}.`,
+      );
+    }
+    const entityPlugin = plugins.find((p) => p.name === entity.lexicon);
+    if (!entityPlugin) {
+      throw new LiveAssertionError(`assertLive("${name}"): no loaded lexicon named "${entity.lexicon}".`);
+    }
+    const entityOutput = result.outputs.get(entity.lexicon);
+    const entityBuildOutput =
+      entityOutput === undefined ? "" : typeof entityOutput === "string" ? entityOutput : entityOutput.primary;
+    const props = isResourceDeclarable(entity) ? ((entity.props ?? {}) as Record<string, unknown>) : {};
+
+    const endpointForAssert = applyLiveEndpoint(config.environments, env, plugins);
+    try {
+      return await assertLiveEntity({
+        plugin: entityPlugin,
+        name,
+        entityType: entity.entityType,
+        props,
+        buildOutput: entityBuildOutput,
+        environment: env,
+        marker,
+        ...assertOptions,
+      });
+    } finally {
+      endpointForAssert.restore();
+    }
+  };
+
   const destroy = async (): Promise<TeardownReport> => {
     const endpointForTeardown = applyLiveEndpoint(config.environments, env, plugins);
     let report: TeardownReport;
@@ -334,5 +394,5 @@ export async function deployStack(options: DeployStackOptions): Promise<Deployed
     return report;
   };
 
-  return { outputs: result.outputs, entities: result.entities, env, destroy };
+  return { outputs: result.outputs, entities: result.entities, env, assertLive, destroy };
 }