@intentius/chant 0.50.0 → 0.51.0

package/src/cli/handlers/search.ts

@@ -8,7 +8,11 @@ import { discover } from "../../discovery/index";
 
 import { observeResources } from "../../lifecycle/observe";
 import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay";
+import { diffLive, type LiveDiffResult } from "../../lifecycle/live-diff";
 import type { LiveObservation } from "../../graph-ir";
+import type { ResourceMetadata } from "../../lexicon";
+import type { ObservationDepth } from "../../lifecycle/types";
+import { formatUnobserved } from "../../observation";
 import { loadChantConfig, matchesDeclaredEnvironment } from "../../config";
 import { loadPlugins, resolveProjectLexicons } from "../plugins";
 import { formatError, formatWarning } from "../format";
@@ -56,6 +60,31 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
   }
   const show = parseShow(args);
 
+  // Query-scoped drift (#1268): --check-live checks a snapshot answer against
+  // a live read, --check-snapshot checks a live answer against the recorded
+  // snapshot — the direction each needs is the source it does NOT already have.
+  if (args.checkLive && !args.at) {
+    console.error(formatError({
+      message: "chant search --check-live needs --at <ref>",
+      hint: "answer from a snapshot and check the matched rows against a live read: --at latest --check-live --env <name>",
+    }));
+    return 1;
+  }
+  if (args.checkSnapshot && !args.live) {
+    console.error(formatError({
+      message: "chant search --check-snapshot needs --live",
+      hint: "answer live and check the matched rows against the recorded snapshot: --live --check-snapshot --env <name>",
+    }));
+    return 1;
+  }
+  if (args.failOnDrift && !args.checkLive && !args.checkSnapshot) {
+    console.error(formatError({
+      message: "chant search --fail-on-drift needs --check-live or --check-snapshot",
+      hint: "it fails the check those flags run, so it is meaningless without one",
+    }));
+    return 1;
+  }
+
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath);
 
@@ -73,6 +102,14 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
   let ambientKinds: string[] = [];
   // Set only on a replay: whether the recording itself holds ambient resources.
   let replayAmbient: { recordedAmbient: boolean } | undefined;
+  // Query-scoped drift (#1268): the OTHER observation, read only when
+  // --check-live/--check-snapshot asked for one — the declared canvas to
+  // classify against, and whether the exit code should reflect what it found.
+  let checkObservations: LiveObservation[] | undefined;
+  let primaryObservations: LiveObservation[] | undefined;
+  let declaredForDrift: GraphIR | undefined;
+  let snapshotDepth: ObservationDepth | undefined;
+  let driftFailure = false;
   if (args.live || args.at) {
     const environment = args.env;
     if (!environment) {
@@ -126,6 +163,21 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
         ),
       };
       source = { kind: "snapshot", commit: replay.commit, timestamp: replay.timestamp };
+      snapshotDepth = replay.depth;
+      if (args.checkLive) {
+        // A fresh live read, additional to the snapshot the answer itself came
+        // from — this is what the matched rows get checked against.
+        const liveCheck = await observeResources(environment, observing, buildResult, {
+          owned: true,
+          stacks,
+          ambient: args.ambient === true,
+        });
+        for (const e of liveCheck.errors) {
+          liveFailures.push(e);
+          console.error(formatError({ message: `live read failed — ${e}` }));
+        }
+        checkObservations = liveCheck.observations;
+      }
     } else {
       const observed = await observeResources(environment, observing, buildResult, {
         owned: true,
@@ -142,7 +194,22 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
       observations = observed.observations;
       liveNotes = observed.notes ?? [];
       source = { kind: "live" };
+      if (args.checkSnapshot) {
+        // The reverse direction: answer live, check the matched rows against
+        // the most recently recorded snapshot. Missing entirely is not a
+        // failure of THIS command — the live answer already stands — so it is
+        // a note, not an error.
+        const scoped = new Set(stacks.filter((st) => st.src).map((st) => st.name));
+        const checkReplay = await replaySnapshots(environment, "latest", scoped);
+        if ("error" in checkReplay) {
+          console.error(formatWarning({ message: `--check-snapshot: ${checkReplay.error}` }));
+        } else {
+          checkObservations = checkReplay.observations;
+          snapshotDepth = checkReplay.depth;
+        }
+      }
     }
+    primaryObservations = observations;
     let live = buildLiveGraphIr(observations);
     // Containment edges, kept aside until after the overlay (see below).
     let containmentEdges: IREdge[] = [];
@@ -206,6 +273,7 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
       stacks.length > 0
         ? await buildDeclaredPerStack(stacks, projectPath)
         : buildGraphIr((await discover(resolve(args.src ?? config.sourceDir ?? "."))).entities, projectPath);
+    declaredForDrift = declared;
     // Carry the NOT-OBSERVED half of the tri-state (#1089) onto the rows, so a
     // declared entity nobody could read is painted `_unobserved` and a row can
     // say so instead of printing blank where a physical id would go (#1263).
@@ -279,6 +347,29 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
   // Qualifies the provenance line, so it sits with it: one line per distinct
   // note for the whole run, not one per stack, and after the rows (#1265).
   for (const n of liveNotes) console.error(formatWarning({ message: n }));
+  // Query-scoped drift (#1268): the matched rows, and only the matched rows,
+  // checked against the observation the primary answer did NOT use. Scoping
+  // both sides of diffLive() to the matched ids is what keeps a query-scoped-
+  // out resource from reading as `missing` or `unobserved` — it was never
+  // asked about, which is a third thing from both.
+  if (checkObservations && declaredForDrift && primaryObservations) {
+    const declaredIds = new Set(declaredForDrift.nodes.map((n) => n.id));
+    const matchedIds = new Set(matches.map((n) => n.id));
+    const nowObservations = args.checkLive ? checkObservations : primaryObservations;
+    const thenObservations = args.checkLive ? primaryObservations : checkObservations;
+    const driftCount = renderDrift(
+      diffLive({
+        declared: new Set([...matchedIds].filter((id) => declaredIds.has(id))),
+        observedNow: pickResources(mergeResources(nowObservations), matchedIds),
+        observedThen: pickResources(mergeResources(thenObservations), matchedIds),
+        unobserved: pickResources(collectUnobserved(nowObservations), matchedIds),
+      }),
+      matches.length,
+      args.checkLive ? "live" : "snapshot",
+      snapshotDepth,
+    );
+    if (args.failOnDrift && driftCount > 0) driftFailure = true;
+  }
   ambientHint(matches, ambientKinds, args.ambient === true, replayAmbient);
   showMiss(matches, show);
   regionSpread(terms, matches, show);
@@ -297,6 +388,7 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
     }));
     return 1;
   }
+  if (driftFailure) return 1;
   return 0;
 }
 
@@ -463,6 +555,63 @@ function provenance(matches: IRNode[], source: AnswerSource, recorded?: string,
   console.log(`— observed from snapshot${at}${taken} · bound ${bound}/${matches.length}`);
 }
 
+/** Union `LiveObservation.resources` across lexicons into one name-keyed map. */
+function mergeResources(observations: LiveObservation[]): Record<string, ResourceMetadata> {
+  const out: Record<string, ResourceMetadata> = {};
+  for (const o of observations) Object.assign(out, o.resources);
+  return out;
+}
+
+/** Restrict a name-keyed map to the matched ids — the whole of "query-scoped". */
+function pickResources<T>(map: Record<string, T>, ids: Set<string>): Record<string, T> {
+  const out: Record<string, T> = {};
+  for (const id of ids) if (id in map) out[id] = map[id];
+  return out;
+}
+
+/**
+ * Render the query-scoped drift check (#1268) — one line per matched resource
+ * whose {@link diffLive} verdict is not `unchanged`, then a summary.
+ *
+ * Reuses `diffLive` unmodified, so every category means exactly what it means
+ * in `lifecycle diff --live`: `missing`/`orphan`/`disappeared`/`drifted` count
+ * as drift, the same set `lifecycle diff` totals; `newlyObserved` and runtime
+ * children are reported but do not, and `unobserved` — a read that could not
+ * look — stays distinct from both, the same #1089 tri-state everywhere else.
+ */
+function renderDrift(
+  diff: LiveDiffResult,
+  checked: number,
+  direction: "live" | "snapshot",
+  depth?: ObservationDepth,
+): number {
+  for (const name of diff.missing) console.log(`⚠ ${name} — missing (declared, not found by this check)`);
+  for (const name of diff.orphan) console.log(`⚠ ${name} — orphan (observed, not declared)`);
+  for (const name of diff.disappeared) console.log(`⚠ ${name} — disappeared since the recorded snapshot`);
+  for (const drift of diff.driftedSinceSnapshot) {
+    for (const change of drift.changes) {
+      console.log(`⚠ ${drift.name}  ${change.path}: ${formatValue(change.oldValue)} → ${formatValue(change.newValue)} — drifted`);
+    }
+  }
+  for (const name of diff.newlyObserved) console.log(`  · ${name} — newly observed since the recorded snapshot`);
+  for (const r of diff.runtimeChildren) console.log(`  · ${r.name} (${r.type}) — runtime, owned by ${r.owner}`);
+  for (const u of diff.unobserved) console.log(`  ? ${formatUnobserved(u.name, u)}`);
+  const driftCount = diff.missing.length + diff.orphan.length + diff.disappeared.length + diff.driftedSinceSnapshot.length;
+  const label = direction === "live" ? "a live read" : "the recorded snapshot";
+  const depthNote = depth === "deep" ? " · snapshot recorded at deep depth, compared here at identity" : "";
+  console.log(
+    `— checked against ${label} · ${driftCount > 0 ? `${driftCount} of ${checked} matched drifted` : `no drift across ${checked} matched`}${depthNote}`,
+  );
+  return driftCount;
+}
+
+function formatValue(v: unknown): string {
+  if (v === undefined) return "<unset>";
+  if (typeof v === "string") return v.length > 60 ? v.slice(0, 57) + "..." : v;
+  const json = JSON.stringify(v);
+  return json.length > 60 ? json.slice(0, 57) + "..." : json;
+}
+
 /**
  * Name the facts chant computed for the kinds in this result that the query did not use.
  *
@@ -815,4 +964,4 @@ function formatRow(n: IRNode, show: string[]): string {
 }
 
 /** Internals exposed for unit tests. */
-export const __searchInternals = { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs, ambientHint, regionSpread, showMiss, provenance };
+export const __searchInternals = { parseQuery, matchTerm, formatRow, explain, describeTerm, derivedSurface, availableAttrs, ambientHint, regionSpread, showMiss, provenance, renderDrift, mergeResources, pickResources };

package/src/cli/main.ts

@@ -83,6 +83,9 @@ const BOOLEAN_FLAGS = new Set([
   "--yes",
   "--confirm-prod",
   "--once",
+  "--check-live",
+  "--check-snapshot",
+  "--fail-on-drift",
 ]);
 
 /**
@@ -305,6 +308,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.at = args[++i];
     } else if (arg === "--ambient") {
       result.ambient = true;
+    } else if (arg === "--check-live") {
+      result.checkLive = true;
+    } else if (arg === "--check-snapshot") {
+      result.checkSnapshot = true;
+    } else if (arg === "--fail-on-drift") {
+      result.failOnDrift = true;
     } else if (arg === "--run-examples") {
       result.runExamples = true;
     } else if (arg === "--pinned-digest") {

package/src/cli/mcp/op-tools.ts

@@ -1,8 +1,9 @@
 import { resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { makeTemporalClient } from "../handlers/run";
-import { resolveWorkflowId } from "../handlers/run-client";
+import { resolveWorkflowId, fetchNormalizedHistory } from "../handlers/run-client";
 import { generateReport } from "../handlers/run-report";
+import { extractStepRecords, countActivities, queryGateState } from "../handlers/op-progress";
 import type { ToolRegistration } from "./lifecycle-tools";
 
 function workflowFnName(opName: string): string {
@@ -117,14 +118,22 @@ export function createOpStatusTool(): ToolRegistration {
       const name = params.name as string;
       const profile = params.profile as string | undefined;
 
+      const { ops } = await discoverOps();
+      const config = ops.get(name)?.config;
+
       const { client } = await makeTemporalClient(profile, resolve("."));
       const handle = client.workflow.getHandle(resolveWorkflowId(name));
       const desc = await handle.describe();
-      const history = await handle.fetchHistory();
+      const history = await fetchNormalizedHistory(handle);
 
-      const events = history.events ?? [];
-      const activitiesCompleted = events.filter((e) => e.eventType === "ActivityTaskCompleted").length;
-      const activitiesScheduled = events.filter((e) => e.eventType === "ActivityTaskScheduled").length;
+      const { completed: activitiesCompleted, scheduled: activitiesScheduled } = countActivities(history);
+      // Per-phase progress (#1676) — the same StepRecord shape `chant run
+      // <name> --json` uses locally, so a consumer renders one way
+      // regardless of executor. Only buildable when the Op's config was
+      // discoverable (a *.op.ts file on disk); absent otherwise rather than
+      // guessed at.
+      const progress = config ? extractStepRecords(config, history, { final: Boolean(desc.closeTime) }) : undefined;
+      const gate = await queryGateState(handle);
 
       return {
         workflowId: desc.workflowId,
@@ -135,6 +144,8 @@ export function createOpStatusTool(): ToolRegistration {
         taskQueue: desc.taskQueue,
         activitiesCompleted,
         activitiesScheduled,
+        ...(progress ? { progress } : {}),
+        gate: gate ?? null,
       };
     },
   };
@@ -196,7 +207,7 @@ export function createOpReportTool(): ToolRegistration {
       const { client } = await makeTemporalClient(profile, resolve("."));
       const handle = client.workflow.getHandle(resolveWorkflowId(name));
       const desc = await handle.describe();
-      const history = await handle.fetchHistory();
+      const history = await fetchNormalizedHistory(handle);
 
       return generateReport(name, config, desc, history);
     },

package/src/cli/mcp/resource-handlers.ts

@@ -5,7 +5,8 @@ import { getContext } from "./resources/context";
 import { readSnapshot, readEnvironmentSnapshots } from "../../lifecycle/git";
 import { discoverOps } from "../../op/discover";
 import { makeTemporalClient } from "../handlers/run";
-import { resolveWorkflowId } from "../handlers/run-client";
+import { resolveWorkflowId, fetchNormalizedHistory } from "../handlers/run-client";
+import { extractStepRecords, countActivities, queryGateState } from "../handlers/op-progress";
 import { loadOkfBundle } from "../../okf-read";
 import { loadChantConfigUpward, resolveKnowledgeDir } from "../../config";
 
@@ -177,11 +178,16 @@ export async function handleResourcesRead(
   if (uri.startsWith("chant://ops/") && uri.endsWith("/runs/latest")) {
     const name = uri.replace("chant://ops/", "").replace("/runs/latest", "");
     try {
+      const { ops } = await discoverOps();
+      const config = ops.get(name)?.config;
+
       const { client } = await makeTemporalClient(undefined, resolve("."));
       const handle = client.workflow.getHandle(resolveWorkflowId(name));
       const desc = await handle.describe();
-      const history = await handle.fetchHistory();
-      const events = history.events ?? [];
+      const history = await fetchNormalizedHistory(handle);
+      const { completed: activitiesCompleted, scheduled: activitiesScheduled } = countActivities(history);
+      const progress = config ? extractStepRecords(config, history, { final: Boolean(desc.closeTime) }) : undefined;
+      const gate = await queryGateState(handle);
       const result = {
         workflowId: desc.workflowId,
         runId: desc.runId,
@@ -189,8 +195,10 @@ export async function handleResourcesRead(
         startTime: desc.startTime,
         closeTime: desc.closeTime ?? null,
         taskQueue: desc.taskQueue,
-        activitiesCompleted: events.filter((e) => e.eventType === "ActivityTaskCompleted").length,
-        activitiesScheduled: events.filter((e) => e.eventType === "ActivityTaskScheduled").length,
+        activitiesCompleted,
+        activitiesScheduled,
+        ...(progress ? { progress } : {}),
+        gate: gate ?? null,
       };
       return {
         contents: [{ uri, mimeType: "application/json", text: JSON.stringify(result, null, 2) }],

package/src/cli/registry.ts

@@ -26,7 +26,20 @@ export interface ParsedArgs {
   temporal?: boolean;
   /** `chant run` — emit the structured OpRunResult as JSON on stdout. */
   json?: boolean;
-  /** `chant run --components <name|all> --progress-json` — stream one NDJSON `RunProgressEvent` (../../components/run-progress.ts) per line to stdout while the run executes (local executor only), so a consumer can render live wave/component/phase/step progress instead of tailing raw logs. Purely additive: run semantics, ordering, and exit code are unchanged; omitted (undefined, not false) when the flag isn't passed. */
+  /**
+   * `chant run --components <name|all> --progress-json` (local executor) —
+   * stream one NDJSON `RunProgressEvent` (../../components/run-progress.ts)
+   * per line to stdout while the run executes, so a consumer can render live
+   * wave/component/phase/step progress instead of tailing raw logs.
+   *
+   * `chant run <name> --temporal --progress-json` (chant #1676) — the same
+   * flag on an Op's durable path streams one NDJSON `StepRecord`
+   * (../../op/local-executor.ts, reconstructed from workflow history by
+   * ../handlers/op-progress.ts) per settled step instead.
+   *
+   * Both are purely additive: run semantics, ordering, and exit code are
+   * unchanged; omitted (undefined, not false) when the flag isn't passed.
+   */
   progressJson?: boolean;
   live: boolean;
   /** `chant migrate --from <name>` (default "github") */
@@ -185,6 +198,25 @@ export interface ParsedArgs {
    * what is declared, which is a broader read and a different claim.
    */
   ambient?: boolean;
+  /**
+   * `chant search "<q>" --at <ref> --check-live --env <name>` (#1268) —
+   * additionally read the estate live and diff the matched rows against the
+   * snapshot the answer came from, reusing `diffLive` (the same engine
+   * `lifecycle diff --live` uses) scoped to just those rows. Requires `--at`.
+   */
+  checkLive?: boolean;
+  /**
+   * `chant search "<q>" --live --check-snapshot --env <name>` (#1268) — the
+   * reverse of `--check-live`: answer live, diff the matched rows against the
+   * most recently recorded snapshot. Requires `--live`.
+   */
+  checkSnapshot?: boolean;
+  /**
+   * `chant search "<q>" --check-live|--check-snapshot --fail-on-drift`
+   * (#1268) — exit non-zero when the scoped check finds drift, so it is usable
+   * as a CI gate. Meaningless without one of the two flags above.
+   */
+  failOnDrift?: boolean;
 
   /** `chant dev surface-diff --run-examples` — also run the example build harness */
   runExamples?: boolean;

package/src/components/run-progress.ts

@@ -107,11 +107,15 @@ export type RunProgressSink = (event: RunProgressEvent) => void;
 /**
  * Build a sink that writes `JSON.stringify(event) + "\n"` to `write` (default:
  * `process.stdout.write`), one line per event, as they happen — the
- * `--progress-json` CLI wiring's sink (../cli/handlers/run.ts). Kept separate
- * from `driver-output.ts`'s end-of-run renderers: this emits *during* the
- * run, one line at a time; `renderDriverJson`/`renderDriverHuman` render the
- * completed `DriverRunResult` once, after the run finishes.
+ * `--progress-json` CLI wiring's sink (../cli/handlers/run.ts, for both the
+ * `--components` driver's `RunProgressEvent`s and the Temporal Op path's
+ * `StepRecord`s, chant #1676). Kept separate from `driver-output.ts`'s
+ * end-of-run renderers: this emits *during* the run, one line at a time;
+ * `renderDriverJson`/`renderDriverHuman` render the completed
+ * `DriverRunResult` once, after the run finishes.
  */
-export function ndjsonProgressSink(write: (chunk: string) => void = (s) => void process.stdout.write(s)): RunProgressSink {
+export function ndjsonProgressSink<T = RunProgressEvent>(
+  write: (chunk: string) => void = (s) => void process.stdout.write(s),
+): (event: T) => void {
   return (event) => write(JSON.stringify(event) + "\n");
 }

package/src/lexicon.ts

@@ -18,6 +18,7 @@ import type { ReferenceCatalog } from "./graph-refs";
 import type { IREdge } from "./graph-ir";
 import type { DescribeResourcesResult, UnobservedReason } from "./observation";
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
+import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption";
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
 
@@ -44,6 +45,16 @@ export type {
   UnobservedReason,
 } from "./observation";
 
+// Disruption classification (#1665), re-exported from the same entry so a
+// lexicon's `classifyDisruption` types itself without a second import path.
+// Runtime helpers live in `@intentius/chant/lifecycle/disruption`.
+export type {
+  Disruption,
+  DisruptionQuery,
+  DisruptionVerdict,
+  DisruptionClassifier,
+} from "./lifecycle/disruption";
+
 // The deep observation contract (#1014), re-exported for the same reason: a
 // lexicon authoring `observeResourcesDeep` + its pruning/ordering hooks types
 // them from the same entry. Runtime helpers live in
@@ -878,6 +889,46 @@ export interface LexiconPlugin {
     namespace?: string;
   }): Promise<DescribeResourcesResult>;
 
+  /**
+   * Classify how much each pending `update` in a plan hurts (#1665) —
+   * in-place / rolling / replace / destroy, or `unknown`.
+   *
+   * `lifecycle plan` reports WHAT changes. What it costs to apply is a
+   * different question, and the answer is spec knowledge: CloudFormation's
+   * registry schema declares `createOnlyProperties` per type, Kubernetes' SSA
+   * schema knows which field changes roll a workload. Core owns neither, so it
+   * defines the vocabulary and does the reporting, and the lexicon that
+   * compiled the spec answers — the same division `postSynthChecks` draws for
+   * validation. A replacement rule hardcoded in core would be a rule the tool
+   * has to keep in step with a provider it does not generate from.
+   *
+   * Only the lexicon can answer, for a second reason: the `deltas` on an entry
+   * are paths into ITS OWN observation shape (`attributes.<key>` off
+   * {@link describeResources}), which core cannot map back onto spec property
+   * names without knowing how the reader named things.
+   *
+   * Called once per lexicon with that lexicon's `update` entries, before the
+   * plan merges the change sets. Expected to be a table lookup over compiled
+   * spec data — no live API call, no mutation. Returning a `Promise` is
+   * allowed, so a lexicon whose answer needs an await is not shut out.
+   *
+   * **Every degradation lands on `unknown`.** Return a partial map: a name
+   * absent from the result is `unknown`, which is the right answer when the
+   * spec does not say (a conditionally-immutable property, a type with no
+   * schema on record). Core also forces `unknown` when this method is absent,
+   * when it throws, and when it returns a level outside the vocabulary. There
+   * is no path by which a lexicon accidentally produces a confident
+   * `in-place` — that claim has to be made deliberately, and a consumer gating
+   * on `replace` can trust it for exactly that reason.
+   *
+   * Omit for lexicons with no replacement semantics to publish.
+   */
+  classifyDisruption?(options: {
+    environment: string;
+    /** This lexicon's `update` entries — name, type, and the attribute deltas. */
+    changes: DisruptionQuery[];
+  }): Record<string, DisruptionVerdict> | Promise<Record<string, DisruptionVerdict>>;
+
   /**
    * Report the undeclared resources this estate *depends on* (#1273), as
    * opposed to the ones it manages.

package/src/lifecycle/assert-live.test.ts

@@ -0,0 +1,125 @@
+import { describe, test, expect } from "vitest";
+import { createMockPlugin, staticObservation } from "@intentius/chant-test-utils";
+import { observation } from "../observation";
+import { assertLiveEntity, LiveAssertionError, UnobservedAssertionError } from "./assert-live";
+import type { ResourceMetadata } from "../lexicon";
+
+const MARKER = { stack: "shop", env: "test-suite-abc123" };
+
+const meta = (overrides: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
+  type: "Mock::Queue",
+  status: "READY",
+  marker: MARKER,
+  ownership: "owned",
+  ...overrides,
+});
+
+const call = (opts: Partial<Parameters<typeof assertLiveEntity>[0]> = {}) =>
+  assertLiveEntity({
+    plugin: createMockPlugin(),
+    name: "taskQueue",
+    entityType: "Mock::Queue",
+    props: {},
+    buildOutput: "",
+    environment: MARKER.env,
+    marker: MARKER,
+    ...opts,
+  });
+
+describe("assertLiveEntity", () => {
+  test("resolves the metadata for an observed, marker-matched entity", async () => {
+    const plugin = createMockPlugin({ describeResources: staticObservation({ taskQueue: meta() }) });
+    await expect(call({ plugin })).resolves.toEqual(meta());
+  });
+
+  test("checks status when given, passes when it matches", async () => {
+    const plugin = createMockPlugin({ describeResources: staticObservation({ taskQueue: meta({ status: "READY" }) }) });
+    await expect(call({ plugin, status: "READY" })).resolves.toEqual(meta());
+  });
+
+  test("throws naming the entity when observed absent", async () => {
+    const plugin = createMockPlugin({ describeResources: staticObservation({}) });
+    await expect(call({ plugin })).rejects.toThrow(LiveAssertionError);
+    await expect(call({ plugin })).rejects.toThrow(/taskQueue.*observed absent/s);
+  });
+
+  test("throws UnobservedAssertionError, not a plain failure, when NOT-OBSERVED", async () => {
+    const plugin = createMockPlugin({
+      describeResources: staticObservation({}, { taskQueue: { reason: "no-credentials", type: "Mock::Queue" } }),
+    });
+    const err = await call({ plugin }).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(UnobservedAssertionError);
+    expect(err).not.toBeInstanceOf(LiveAssertionError);
+    expect((err as UnobservedAssertionError).reason).toBe("no-credentials");
+  });
+
+  test("a thrown describeResources degrades to NOT-OBSERVED read-failed, never a silent absence", async () => {
+    const plugin = createMockPlugin({
+      describeResources: async () => {
+        throw new Error("ECONNREFUSED");
+      },
+    });
+    const err = await call({ plugin }).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(UnobservedAssertionError);
+    expect((err as UnobservedAssertionError).reason).toBe("read-failed");
+    expect((err as UnobservedAssertionError).detail).toContain("ECONNREFUSED");
+  });
+
+  test("a lexicon with no describeResources is NOT-OBSERVED, unsupported-kind", async () => {
+    const plugin = createMockPlugin();
+    const err = await call({ plugin }).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(UnobservedAssertionError);
+    expect((err as UnobservedAssertionError).reason).toBe("unsupported-kind");
+  });
+
+  test("throws when the observed marker names a foreign stack", async () => {
+    const plugin = createMockPlugin({
+      describeResources: staticObservation({ taskQueue: meta({ marker: { stack: "other-stack", env: MARKER.env } }) }),
+    });
+    await expect(call({ plugin })).rejects.toThrow(/not this deploy's/);
+  });
+
+  test("throws when the observed marker names a foreign env — a same-named leftover from another run", async () => {
+    const plugin = createMockPlugin({
+      describeResources: staticObservation({ taskQueue: meta({ marker: { stack: MARKER.stack, env: "test-other-999999" } }) }),
+    });
+    await expect(call({ plugin })).rejects.toThrow(LiveAssertionError);
+  });
+
+  test("throws when the entity is confirmed foreign (no marker, ownership foreign)", async () => {
+    const plugin = createMockPlugin({
+      describeResources: staticObservation({
+        taskQueue: meta({ marker: undefined, ownership: "foreign" }),
+      }),
+    });
+    await expect(call({ plugin })).rejects.toThrow(/not this deploy's/);
+  });
+
+  test("passes through an entity whose lexicon has no marker channel (ownership unknown, no marker) rather than always failing", async () => {
+    const plugin = createMockPlugin({
+      describeResources: staticObservation({
+        taskQueue: meta({ marker: undefined, ownership: "unknown" }),
+      }),
+    });
+    await expect(call({ plugin })).resolves.toEqual(meta({ marker: undefined, ownership: "unknown" }));
+  });
+
+  test("throws a status mismatch after identity is confirmed", async () => {
+    const plugin = createMockPlugin({ describeResources: staticObservation({ taskQueue: meta({ status: "PENDING" }) }) });
+    await expect(call({ plugin, status: "READY" })).rejects.toThrow(/status "PENDING"/);
+  });
+
+  test("uses the observation() envelope form identically to the bare-map form", async () => {
+    const plugin = createMockPlugin({ describeResources: async () => observation({ taskQueue: meta() }) });
+    await expect(call({ plugin })).resolves.toEqual(meta());
+  });
+});