@intentius/chant 0.50.0 → 0.52.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/lint/policy-build-parity.test.ts

@@ -0,0 +1,232 @@
+/**
+ * chant #2002 — the `policyGate` Op step must gate on the build `chant build`
+ * produces, not on a different one.
+ *
+ * `evaluateProjectPolicies` used to assemble `build()`'s options itself, two of
+ * them against `buildCommand`'s nine. It built with fold off (the path #1134
+ * retired as the default), without the project's config (so serializers lost
+ * their lexicon-scoped dialect settings) and without `buildRoots` (so
+ * config-declared roots contributed nothing) — a gate could pass a build `chant
+ * build` fails. Both callers now assemble through
+ * `../cli/build-options.ts`'s `resolveProjectBuildOptions`, and the first test
+ * below fails if either ever grows an option the other does not get.
+ *
+ * `build()` is wrapped rather than replaced: every assertion here is about a
+ * real build of a real fixture, and the wrapper only records what each caller
+ * asked for.
+ */
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { BuildOptions, BuildResult } from "../build";
+
+const recorder = vi.hoisted(() => ({
+  options: [] as (BuildOptions | undefined)[],
+  results: [] as BuildResult[],
+}));
+
+vi.mock("../build", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../build")>();
+  return {
+    ...actual,
+    build: async (...args: Parameters<typeof actual.build>) => {
+      recorder.options.push(args[3]);
+      const result = await actual.build(...args);
+      recorder.results.push(result);
+      return result;
+    },
+  };
+});
+
+const { evaluateProjectPolicies } = await import("./policy");
+const { buildCommand } = await import("../cli/commands/build");
+const { resolveProjectLexicons, loadPlugins } = await import("../cli/plugins");
+
+/** Run `chant build` over a fixture the way `cli/main.ts` drives it. */
+async function runChantBuild(dir: string): Promise<{ options: BuildOptions; result: BuildResult }> {
+  const plugins = await loadPlugins(await resolveProjectLexicons(dir));
+  recorder.options.length = 0;
+  recorder.results.length = 0;
+  const outcome = await buildCommand({
+    path: dir,
+    format: "json",
+    output: join(dir, "out", "build.json"),
+    serializers: plugins.map((p) => p.serializer),
+    plugins,
+  });
+  expect(outcome.errors).toEqual([]);
+  return { options: recorder.options[0]!, result: recorder.results[0]! };
+}
+
+/** Run the `policyGate` step's entry point over the same fixture. */
+async function runPolicyGate(dir: string): Promise<{ options: BuildOptions; result: BuildResult }> {
+  recorder.options.length = 0;
+  recorder.results.length = 0;
+  await evaluateProjectPolicies({ path: dir });
+  return { options: recorder.options[0]!, result: recorder.results[0]! };
+}
+
+/** Build-root contributors are freshly bound closures — compare their count. */
+function comparable(options: BuildOptions): Record<string, unknown> {
+  return { ...options, buildRoots: options.buildRoots?.length ?? 0 };
+}
+
+const TRIVIAL_POLICY =
+  `export const check = {\n` +
+  `  id: "ORG-PARITY",\n` +
+  `  description: "records nothing; the build is what is under test",\n` +
+  `  check: () => [],\n` +
+  `};\n`;
+
+describe("policyGate builds the same project chant build does (chant #2002)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-policy-parity-${Date.now()}-${Math.random()}`);
+    await mkdir(join(testDir, "policies"), { recursive: true });
+    await writeFile(join(testDir, "policies", "org.ts"), TRIVIAL_POLICY);
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  /**
+   * A forgejo project: `forgejo.runnerLabels` is read by the serializer off
+   * `SerializeContext.config` (lexicons/forgejo/src/serializer.ts), so a build
+   * that drops `config` emits the default label instead of the project's.
+   */
+  async function writeForgejoProject(): Promise<void> {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default {\n` +
+        `  lexicons: ["forgejo"],\n` +
+        `  forgejo: { runnerLabels: { "ubuntu-latest": "self-hosted-arm64" } },\n` +
+        `  lint: { policies: ["policies/org.ts"] },\n` +
+        `};\n`,
+    );
+    await writeFile(
+      join(testDir, "ci.ts"),
+      `import { Workflow, Job, Step } from "@intentius/chant-lexicon-github";\n` +
+        `export const workflow = new Workflow({ name: "CI", on: { push: {} } });\n` +
+        `export const buildJob = new Job({\n` +
+        `  "runs-on": "ubuntu-latest",\n` +
+        `  steps: [new Step({ name: "Build", run: "npm run build" })],\n` +
+        `});\n`,
+    );
+  }
+
+  test("both callers hand build() the identical option set", async () => {
+    await writeForgejoProject();
+
+    const cli = await runChantBuild(testDir);
+    const gate = await runPolicyGate(testDir);
+
+    // The drift this issue is about is an option one caller passes and the
+    // other does not, so the key sets are asserted on their own — a new option
+    // added at one call site fails here even if its value happens to match.
+    expect(Object.keys(gate.options).sort()).toEqual(Object.keys(cli.options).sort());
+    expect(comparable(gate.options)).toEqual(comparable(cli.options));
+    expect(gate.options.fold).toBe(true);
+  });
+
+  test("the project's lexicon-scoped dialect settings reach the gate's serializers", async () => {
+    await writeForgejoProject();
+
+    const cli = await runChantBuild(testDir);
+    const gate = await runPolicyGate(testDir);
+
+    expect([...gate.result.outputs.entries()]).toEqual([...cli.result.outputs.entries()]);
+    const emitted = JSON.stringify([...gate.result.outputs.values()]);
+    // The project's own label, not `DEFAULT_RUNNER_LABELS`' "docker" — which is
+    // what the gate emitted while it built without `config`.
+    expect(emitted).toContain("self-hosted-arm64");
+    expect(emitted).not.toContain("docker");
+  });
+
+  test("entities from a config-declared build root are in the set the gate sees", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default { lexicons: ["cedar"], lint: { policies: ["policies/org.ts"] } };\n`,
+    );
+    // cedar's buildRoots hook contributes the project's schema as an entity
+    // (lexicons/cedar/src/schema-artifact.ts). Without `buildRoots` the gate
+    // never saw it, so a policy over it could not fail.
+    await writeFile(join(testDir, "schema.cedarschema"), `entity User;\n`);
+
+    const cli = await runChantBuild(testDir);
+    const gate = await runPolicyGate(testDir);
+
+    expect([...gate.result.entities.keys()].sort()).toEqual([...cli.result.entities.keys()].sort());
+    expect([...gate.result.entities.keys()]).toContain("cedarSchema");
+    expect([...gate.result.outputs.entries()]).toEqual([...cli.result.outputs.entries()]);
+  });
+
+  test("a foldable source module does not execute during the gate's build", async () => {
+    delete process.env.CHANT_2002_SOURCE_RAN;
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default { lexicons: ["k8s"], lint: { policies: ["policies/org.ts"] } };\n`,
+    );
+    await writeFile(
+      join(testDir, "ns.ts"),
+      // Module-level: runs if and only if the file is imported. Fold reads the
+      // constructor call statically and never imports the module.
+      `process.env.CHANT_2002_SOURCE_RAN = "1";\n` +
+        `import { Namespace } from "@intentius/chant-lexicon-k8s";\n` +
+        `export const ns = new Namespace({ metadata: { name: "demo" } });\n`,
+    );
+
+    const gate = await runPolicyGate(testDir);
+
+    expect(gate.options.fold).toBe(true);
+    expect(gate.result.foldDecisions.find((d) => d.file.endsWith("ns.ts"))?.mode).toBe("fold");
+    expect(process.env.CHANT_2002_SOURCE_RAN).toBeUndefined();
+  });
+
+  test("build.fold: false is honoured too — the config decides, not the gate", async () => {
+    delete process.env.CHANT_2002_SOURCE_RAN;
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default { lexicons: ["k8s"], build: { fold: false }, lint: { policies: ["policies/org.ts"] } };\n`,
+    );
+    // No lexicon import: with fold off every discovered file is imported, and
+    // this fixture lives outside the repo where a bare `@intentius/*`
+    // specifier does not resolve. The marker is all this test needs.
+    await writeFile(join(testDir, "marker.ts"), `process.env.CHANT_2002_SOURCE_RAN = "1";\nexport const value = 1;\n`);
+
+    const gate = await runPolicyGate(testDir);
+
+    expect(gate.options.fold).toBe(false);
+    expect(process.env.CHANT_2002_SOURCE_RAN).toBe("1");
+    delete process.env.CHANT_2002_SOURCE_RAN;
+  });
+
+  test("build.sandbox: true is reported as a divergence rather than silently ignored", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default { lexicons: ["k8s"], build: { sandbox: true }, lint: { policies: ["policies/org.ts"] } };\n`,
+    );
+    const stderr: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((s: string) => { stderr.push(s); });
+
+    const evaluation = await evaluateProjectPolicies({ path: testDir });
+
+    expect(evaluation.warnings).toHaveLength(1);
+    expect(evaluation.warnings[0]).toContain("build.sandbox is enabled");
+    expect(stderr.join("\n")).toContain("build.sandbox is enabled");
+  });
+
+  test("no sandbox opt-in, no warning", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default { lexicons: ["k8s"], lint: { policies: ["policies/org.ts"] } };\n`,
+    );
+
+    const evaluation = await evaluateProjectPolicies({ path: testDir });
+
+    expect(evaluation.warnings).toEqual([]);
+  });
+});

package/src/lint/policy.ts

@@ -7,6 +7,8 @@ import { resolve, dirname } from "node:path";
 import { loadChantConfigUpward, resolveOwnershipEnv, resolveOwnershipMarker } from "../config";
 import { resolveBuildParams } from "../build-params";
 import { resolveProjectLexicons, loadPlugins } from "../cli/plugins";
+import { resolveBuildModes, resolveProjectBuildOptions } from "../cli/build-options";
+import { formatWarning } from "../cli/format";
 import { build } from "../build";
 import { runPostSynthChecks, isPostSynthCheck } from "./post-synth";
 import type { PostSynthCheck, PostSynthDiagnostic } from "./post-synth";
@@ -63,6 +65,15 @@ export interface PolicyEvaluation {
    * of the finding just vanishing.
    */
   suppressed: PostSynthDiagnostic[];
+  /**
+   * chant #2002 — divergences between this evaluation and what `chant build`
+   * would do, named rather than left silent. Today that is a project whose
+   * resolved `build.sandbox` is `true`: the gate builds unsandboxed, because
+   * running it inside the boundary needs the per-execution arming decision
+   * tracked on #1157. Also written to stderr — the gate's caller is an
+   * activity wrapper that surfaces output, not a structured result.
+   */
+  warnings: string[];
 }
 
 /**
@@ -70,6 +81,13 @@ export interface PolicyEvaluation {
  * standalone — used by the `policyGate` Op step to gate an apply on the same
  * organizational policy `chant build` enforces. Loads the project's lexicons,
  * builds, then runs the policy pack with `env` (explicit, else `ownership.env`).
+ *
+ * chant #2002 — "the same organizational policy `chant build` enforces" only
+ * holds if it is the same build. The build options are assembled by
+ * `../cli/build-options.ts`'s `resolveProjectBuildOptions`, the single function
+ * `chant build` also calls, rather than by a second list here; a build option
+ * added for one caller and not the other is what let a gate pass a build
+ * `chant build` fails.
  */
 export async function evaluateProjectPolicies(opts: {
   path: string;
@@ -96,10 +114,37 @@ export async function evaluateProjectPolicies(opts: {
   }
   const env = opts.env ?? resolveOwnershipEnv(config, params.provenance);
 
-  const result = await build(buildPath, serializers, undefined, {
-    ownership: resolveOwnershipMarker(config, params.provenance),
-    buildParams: params.provenance,
-  });
+  // chant #2002 — the build options come from the shared assembler
+  // (`../cli/build-options.ts`), the same one `chant build` uses, so the gate
+  // decides on the project `chant build` produces: folded by default (#1134),
+  // with the project's config reaching the serializers, and with
+  // config-declared build roots contributing their entities. Assembling a
+  // second, shorter list here is what let the two drift apart.
+  const modes = resolveBuildModes(config);
+  const warnings: string[] = [];
+  if (modes.sandbox) {
+    // Resolved, reported, and not yet honoured. Building inside the boundary
+    // needs per-execution arming (#1157) — until that lands, saying so is the
+    // difference between a known gap and a silent one.
+    warnings.push(
+      `build.sandbox is enabled for this project, but the policy gate builds it in this process — the project's source files and its lint.policies modules execute here, unsandboxed (chant #1157). Run \`chant build --sandbox\` for a sandboxed build of the same project.`,
+    );
+  }
+  for (const warning of warnings) console.error(formatWarning({ message: warning }));
+
+  const result = await build(
+    buildPath,
+    serializers,
+    undefined,
+    resolveProjectBuildOptions({
+      config,
+      configDir,
+      plugins,
+      modes: { fold: modes.fold, sandbox: false },
+      ownership: resolveOwnershipMarker(config, params.provenance),
+      buildParams: params.provenance,
+    }),
+  );
   if (result.errors.length > 0) {
     throw new Error("Build failed — cannot evaluate policy on a broken build");
   }
@@ -108,7 +153,7 @@ export async function evaluateProjectPolicies(opts: {
     ? await loadPolicyChecks(config.lint.policies, configDir)
     : [];
   if (checks.length === 0) {
-    return { diagnostics: [], violations: [], env, suppressed: [] };
+    return { diagnostics: [], violations: [], env, suppressed: [], warnings };
   }
 
   const raw = runPostSynthChecks(checks, result, env);
@@ -118,5 +163,5 @@ export async function evaluateProjectPolicies(opts: {
   // fails on it either, and vice versa for a check turned UP to "error".
   const { diagnostics, suppressed } = applyConfiguredSeverity(raw, config.lint?.rules);
   const violations = diagnostics.filter((d) => d.severity === "error");
-  return { diagnostics, violations, env, suppressed };
+  return { diagnostics, violations, env, suppressed, warnings };
 }

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 };
@@ -130,6 +136,34 @@ export function findGate(config: OpConfig): GateStep | undefined {
   return undefined;
 }
 
+/**
+ * Find the first `policyGate` step anywhere in the Op (phases + `onFailure`,
+ * including steps nested inside effect steps), if any.
+ *
+ * chant #2003 — `--sandbox` is a GLOBAL flag (`../cli/registry.ts`), and
+ * `../cli/main.ts` arms the process-wide policy latch off it for every command,
+ * `chant run` included. A `policyGate` step then reaches `loadPolicyChecks`,
+ * which refuses while armed with a message written for a chant maintainer —
+ * shown to a user who passed a documented flag. The combination cannot be
+ * honoured until the gate can build and load policies inside the boundary
+ * (#1157), so both `chant run` paths pre-flight it with this and refuse before
+ * any phase executes, the same shape as {@link findGate}'s pre-flight.
+ */
+export function findPolicyGateStep(config: OpConfig): ActivityStep | undefined {
+  const all = [...config.phases, ...(config.onFailure ?? [])];
+  const isPolicyGate = (s: StepDefinition): s is ActivityStep => isActivity(s) && s.fn === "policyGate";
+  for (const phase of all) {
+    for (const step of phase.steps) {
+      if (isPolicyGate(step)) return step;
+      if (isEffect(step)) {
+        const nested = step.steps.find(isPolicyGate);
+        if (nested) return nested;
+      }
+    }
+  }
+  return undefined;
+}
+
 const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
 
 /**

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 };
 }