@intentius/chant 0.124.13 → 0.124.14

package/dist/lexicon-schema.js

@@ -0,0 +1,136 @@
+/**
+ * Zod schemas for lexicon manifest and registry validation.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Intrinsic definitions
+// ---------------------------------------------------------------------------
+export const IntrinsicDefSchema = z.object({
+    name: z.string().min(1, "intrinsic name must not be empty"),
+    description: z.string().optional(),
+    outputKey: z.string().optional(),
+    // Required (chant #1067) — no silent default for whether an intrinsic
+    // folds. See IntrinsicDef.isTag in ../lexicon.ts for the history.
+    isTag: z.boolean(),
+    // chant #1044 — optional and default-off on purpose: absent means "this
+    // intrinsic's plain-call form does not fold", which is what every
+    // registration written before #1044 means. Only an explicit `true` opts a
+    // call into folding. See IntrinsicDef.foldsAsCall in ../lexicon.ts.
+    foldsAsCall: z.boolean().optional(),
+    // chant #1966 — same default-off shape as foldsAsCall, for the EAGER
+    // call-form opt-in. See IntrinsicDef.foldsEagerly in ../lexicon.ts.
+    foldsEagerly: z.boolean().optional(),
+});
+// ---------------------------------------------------------------------------
+// Lexicon manifest
+// ---------------------------------------------------------------------------
+const semverRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$/;
+export const LexiconManifestSchema = z.object({
+    name: z.string().min(1, "manifest name must not be empty"),
+    version: z.string().regex(semverRegex, "version must be valid semver (X.Y.Z)"),
+    chantVersion: z.string().optional(),
+    namespace: z.string().optional(),
+    intrinsics: z.array(IntrinsicDefSchema).optional(),
+    pseudoParameters: z.record(z.string(), z.string()).optional(),
+});
+// ---------------------------------------------------------------------------
+// Extension constraint schema (matches ExtensionConstraint from lexicon packages)
+// ---------------------------------------------------------------------------
+const ExtensionConstraintSchema = z.object({
+    name: z.string(),
+    type: z.enum(["if_then", "dependent_excluded", "required_or", "required_xor"]),
+    condition: z.unknown().optional(),
+    requirement: z.unknown().optional(),
+});
+// ---------------------------------------------------------------------------
+// Property constraints schema (matches PropertyConstraints from lexicon packages)
+// ---------------------------------------------------------------------------
+const PropertyConstraintsSchema = z.object({
+    pattern: z.string().optional(),
+    minLength: z.number().optional(),
+    maxLength: z.number().optional(),
+    minimum: z.number().optional(),
+    maximum: z.number().optional(),
+    format: z.string().optional(),
+    const: z.unknown().optional(),
+    default: z.unknown().optional(),
+    enum: z.array(z.string()).optional(),
+});
+// ---------------------------------------------------------------------------
+// Lexicon entry (registry entry for a resource or property type)
+// ---------------------------------------------------------------------------
+export const LexiconEntrySchema = z.object({
+    resourceType: z.string(),
+    kind: z.enum(["resource", "property"]),
+    lexicon: z.string(),
+    attrs: z.record(z.string(), z.string()).optional(),
+    constraints: z.array(ExtensionConstraintSchema).optional(),
+    propertyConstraints: z.record(z.string(), PropertyConstraintsSchema).optional(),
+    createOnly: z.array(z.string()).optional(),
+    writeOnly: z.array(z.string()).optional(),
+    primaryIdentifier: z.array(z.string()).optional(),
+    deprecatedProperties: z.array(z.string()).optional(),
+    conditionalCreateOnly: z.array(z.string()).optional(),
+    replacementStrategy: z.enum(["delete_then_create", "create_then_delete"]).optional(),
+    tagging: z.object({
+        taggable: z.boolean(),
+        tagOnCreate: z.boolean(),
+        tagUpdatable: z.boolean(),
+    }).optional(),
+    runtimeDeprecations: z.record(z.string(), z.string()).optional(),
+});
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+/**
+ * Validate a manifest from unknown input (object or JSON string).
+ * Throws a descriptive error on invalid input.
+ */
+export function validateManifest(data) {
+    if (data === null || data === undefined) {
+        throw new Error("manifest data is empty");
+    }
+    if (typeof data === "string") {
+        try {
+            data = JSON.parse(data);
+        }
+        catch (err) {
+            const msg = err instanceof SyntaxError ? err.message : String(err);
+            throw new Error(`invalid JSON in manifest: ${msg}`);
+        }
+    }
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        throw new Error("manifest must be a JSON object");
+    }
+    const result = LexiconManifestSchema.safeParse(data);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const path = issue.path.length > 0 ? issue.path.join(".") : undefined;
+        const prefix = path ? `manifest field ${path}` : "manifest";
+        throw new Error(`${prefix}: ${issue.message}`);
+    }
+    return result.data;
+}
+/**
+ * Validate a registry JSON string into a typed record.
+ * Throws a descriptive error on invalid input.
+ */
+export function validateRegistry(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        const msg = err instanceof SyntaxError ? err.message : String(err);
+        throw new Error(`invalid JSON in registry: ${msg}`);
+    }
+    const schema = z.record(z.string(), LexiconEntrySchema);
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const path = issue.path.length > 0 ? issue.path.join(".") : undefined;
+        const prefix = path ? `registry[${path}]` : "registry";
+        throw new Error(`${prefix}: ${issue.message}`);
+    }
+    return result.data;
+}

package/dist/lexicon.js

@@ -0,0 +1,130 @@
+/**
+ * Whether `chant build --fold` can ever fold a use of this intrinsic
+ * (chant #1062, epic #1019) — in EITHER authored form.
+ *
+ * Two disjoint ways to qualify, one per form:
+ *
+ *   - a registered tagged-template intrinsic (`Sub\`...\``) folds because
+ *     `foldTaggedTemplate` recognizes its tag and recurses into the interior
+ *     ({@link intrinsicTagFolds});
+ *   - a registered plain-call intrinsic (`Ref(...)`, `Concat(...)`) folds
+ *     only when its lexicon opted it in with `foldsAsCall`
+ *     ({@link intrinsicCallFolds}, chant #1044). Before #1044 no plain call
+ *     folded at all, whatever it was named or registered as.
+ *
+ * This function is the single predicate the generated per-lexicon intrinsics
+ * page (`../codegen/docs-sections.ts`'s "Folds?" column) calls — never a
+ * restated copy that could silently drift from the code. `fold()` itself
+ * calls the two form-specific predicates below rather than this one, because
+ * it always knows which form it is looking at, and a tag must not fold as a
+ * call (or vice versa) merely because the other form was opted in.
+ *
+ * Takes a structural `{ isTag?, foldsAsCall? }` rather than
+ * `Pick<IntrinsicDef, ...>` deliberately: `IntrinsicDef.isTag` is required
+ * for new registrations (chant #1067), but these predicates also read off
+ * untrusted, possibly-older parsed JSON (`ManifestJSON` in
+ * `./codegen/docs-types.ts`, on disk as a published lexicon's
+ * `dist/manifest.json`) that may predate either field. `undefined` there
+ * means what it always did — not a tag, not opted in.
+ */
+export function intrinsicFolds(def) {
+    return intrinsicTagFolds(def) || intrinsicCallFolds(def) || intrinsicCallFoldsEagerly(def);
+}
+/** True when this intrinsic's TAGGED-TEMPLATE form folds (`Sub\`...\``) — see {@link intrinsicFolds}. */
+export function intrinsicTagFolds(def) {
+    return def.isTag === true;
+}
+/**
+ * True when this intrinsic's PLAIN-CALL form folds (`Ref(...)`) — i.e. the
+ * lexicon opted it in via {@link IntrinsicDef.foldsAsCall} (chant #1044).
+ *
+ * `isTag: true` disqualifies regardless: a tagged template is invoked as
+ * `` Name`...` ``, so a call to it isn't the registered authoring form at
+ * all. Keeping that here rather than trusting registrations means a lexicon
+ * that declares both flags cannot quietly widen `fold()`'s call case — and
+ * `chant dev check-lexicon` fails the registration outright.
+ */
+export function intrinsicCallFolds(def) {
+    return def.isTag !== true && def.foldsAsCall === true;
+}
+/**
+ * True when this intrinsic's PLAIN-CALL form folds EAGERLY (chant #1966) —
+ * i.e. the lexicon opted it in via {@link IntrinsicDef.foldsEagerly}.
+ * `isTag: true` disqualifies, same as {@link intrinsicCallFolds}.
+ */
+export function intrinsicCallFoldsEagerly(def) {
+    return def.isTag !== true && def.foldsEagerly === true;
+}
+/** `path` (relative to the member's directory) made relative to the repository root. Absolute paths pass through. */
+export function memberRepoPath(member, path) {
+    if (path.startsWith("/") || member.dir === "." || member.dir === "")
+        return path;
+    const rest = path.replace(/^\.\/+/, "").replace(/\/+$/, "");
+    return rest === "" || rest === "." ? member.dir : `${member.dir}/${rest}`;
+}
+/**
+ * The path filter for a member's `push` or `pull_request` trigger in GitHub
+ * Actions syntax (also Forgejo's): the member's directory and the pipeline
+ * file. A member at
+ * `"."` gets every path, minus the other members' directories.
+ */
+export function memberPathFilter(member, file = member.file) {
+    const paths = member.dir === "." || member.dir === ""
+        ? ["**", ...(member.exclude ?? []).map((d) => `!${d}/**`)]
+        : [`${member.dir}/**`];
+    if (file && !paths.includes(file))
+        paths.push(file);
+    return paths;
+}
+/**
+ * The `rules: changes:` list for a member's GitLab jobs, or undefined for a
+ * member at `"."`: GitLab's `changes` has no exclusions, so the root member's
+ * jobs run on every change.
+ */
+export function memberGitlabChanges(member, file = member.file) {
+    if (member.dir === "." || member.dir === "")
+        return undefined;
+    return [`${member.dir}/**/*`, ...(file ? [file] : [])];
+}
+/** A shell word for `cd` into the member's directory. */
+export function memberShellDir(member) {
+    return /^[A-Za-z0-9._\/-]+$/.test(member.dir) ? member.dir : `'${member.dir.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Resolve a `ScheduledOpSpec`'s effective trigger, most specific first:
+ * `trigger` when given; else the backward-compatible `{ kind: "cron",
+ * schedule }` built from this spec's own `schedule` — every pre-#2084 caller
+ * (`WorkflowAuditOp`, `PipelineAuditOp`, `ReconcileOp`, …, and their tests)
+ * sets only that and keeps meaning cron unchanged; else the declaring Op's
+ * own `schedule.cron` (#2120), so an Op that already carries its cadence
+ * needs no second cron declaration on the CI side. Throws when none of the
+ * three is present — a `ScheduledOpSpec` needs exactly one trigger.
+ */
+export function resolveOpTrigger(spec) {
+    if (spec.trigger)
+        return spec.trigger;
+    if (spec.schedule)
+        return { kind: "cron", schedule: spec.schedule };
+    if (spec.opSchedule)
+        return { kind: "cron", schedule: spec.opSchedule.cron };
+    throw new Error(`Scheduled Op "${spec.name}" has neither \`trigger\` nor \`schedule\`, and the Op itself declares no \`schedule\` — one is required.`);
+}
+/**
+ * Type guard to check if a value is a LexiconPlugin.
+ * Checks for required lifecycle methods in addition to name/serializer.
+ */
+export function isLexiconPlugin(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        !("name" in value) ||
+        typeof value.name !== "string" ||
+        !("serializer" in value) ||
+        typeof value.serializer !== "object") {
+        return false;
+    }
+    const obj = value;
+    return (typeof obj.generate === "function" &&
+        typeof obj.validate === "function" &&
+        typeof obj.coverage === "function" &&
+        typeof obj.package === "function");
+}

package/dist/lifecycle/affected.js

@@ -0,0 +1,224 @@
+/**
+ * Selective change-set scoping — which stacks does a change affect?
+ *
+ * "Affected" is two distinct things, because chant serializes cross-stack
+ * references symbolically:
+ *   1. **Directly changed** — the stack's built artifact differs between base
+ *      and head. Caught by artifact diff over deterministic builds, so it
+ *      ignores comment-only / refactor-with-no-output-change edits.
+ *   2. **Operationally affected (dependents)** — a stack whose own artifact is
+ *      unchanged but which consumes an upstream export whose value changed. Its
+ *      bytes don't move, yet it may need re-apply. Caught by walking the
+ *      cross-stack graph (#200) from the directly-changed set; opt-in.
+ *
+ * A stack whose inputs come from outside synthesis (deploy-time params) cannot
+ * be judged from a source diff — reported as **indeterminate**, not silently
+ * included or excluded.
+ *
+ * ## What "stack" means here depends on the project
+ *
+ * A project that declares `stacks` in `chant.config.ts` gets each declared
+ * stack's own source built, and the answer names stacks. A single-root project
+ * has no such partition to build, so its answer names lexicon partitions, which
+ * is the only granularity it has. The difference matters downstream: a
+ * component's deploy step names a stack, so only the first kind of answer can
+ * be joined to components (#2420).
+ *
+ * This returns the set; it does not act. `chant components fan-out`
+ * (../cli/handlers/fan-out.ts) is the command that acts on it, and fanning
+ * `lifecycle plan` / `ApplyOp` over it by hand is still an Op the user
+ * composes.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtempSync, rmSync, existsSync, symlinkSync, realpathSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { build } from "../build.js";
+import { getPrimaryOutput } from "../lint/post-synth.js";
+const execFileAsync = promisify(execFile);
+// ── Pure model ──────────────────────────────────────────────────────────────
+/** Stacks whose serialized output differs between the two builds (added/removed count). */
+export function changedStacks(base, head) {
+    const names = new Set([...base.keys(), ...head.keys()]);
+    const changed = [];
+    for (const name of names) {
+        if (base.get(name) !== head.get(name))
+            changed.push(name);
+    }
+    return changed.sort();
+}
+/**
+ * Walk the cross-stack graph backwards from `changed` to find every stack that
+ * (transitively) consumes a changed stack. Edge `from → to` means `from`
+ * depends on `to`, so a changed `to` makes `from` a dependent.
+ */
+export function dependentStacks(changed, graph) {
+    const consumersOf = new Map();
+    for (const { from, to } of graph.edges) {
+        (consumersOf.get(to) ?? consumersOf.set(to, []).get(to)).push(from);
+    }
+    const seen = new Set(changed);
+    const queue = [...changed];
+    const dependents = new Set();
+    while (queue.length > 0) {
+        const node = queue.shift();
+        for (const consumer of consumersOf.get(node) ?? []) {
+            if (seen.has(consumer))
+                continue;
+            seen.add(consumer);
+            dependents.add(consumer);
+            queue.push(consumer);
+        }
+    }
+    return [...dependents].sort();
+}
+/**
+ * Compute the affected set from two per-stack artifact maps and the cross-stack
+ * graph. Pure — no builds, no git — so the model is independently testable.
+ */
+export function computeAffected(base, head, graph, opts = {}) {
+    const changed = changedStacks(base, head);
+    const dependents = opts.includeDependents ? dependentStacks(changed, graph) : [];
+    const indeterminate = [...(opts.externalInput ?? [])].sort();
+    return { changed, dependents, indeterminate };
+}
+// ── Build + git plumbing ──────────────────────────────────────────────────────
+/** A built BuildResult's per-stack (lexicon) primary output, keyed by stack. */
+export function artifactMap(outputs) {
+    const map = new Map();
+    for (const [stack, output] of outputs)
+        map.set(stack, getPrimaryOutput(output));
+    return map;
+}
+/** Stacks (lexicons) that declare a deploy-time parameter — external input. */
+export function externalInputStacks(entities) {
+    const stacks = new Set();
+    for (const [, entity] of entities) {
+        if ("parameterType" in entity && typeof entity.parameterType === "string") {
+            stacks.add(entity.lexicon);
+        }
+    }
+    return [...stacks].sort();
+}
+async function gitTopLevel(cwd) {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd });
+    return stdout.trim();
+}
+/**
+ * Check out `ref` into a throwaway worktree, symlink the repo's node_modules so
+ * lexicon imports resolve, run `fn`, then remove the worktree. At most one
+ * worktree exists at a time.
+ */
+async function withWorktree(repoRoot, ref, fn) {
+    const dir = mkdtempSync(join(tmpdir(), "chant-affected-"));
+    await execFileAsync("git", ["worktree", "add", "--detach", dir, ref], { cwd: repoRoot });
+    try {
+        const nm = join(repoRoot, "node_modules");
+        const linked = join(dir, "node_modules");
+        if (existsSync(nm) && !existsSync(linked))
+            symlinkSync(nm, linked, "dir");
+        return await fn(dir);
+    }
+    finally {
+        await execFileAsync("git", ["worktree", "remove", "--force", dir], { cwd: repoRoot }).catch(() => {
+            rmSync(dir, { recursive: true, force: true });
+        });
+    }
+}
+/**
+ * Build each declared stack's own source directory and key the result by
+ * **stack name**.
+ *
+ * Without this, one build of the project root produces a map keyed by lexicon
+ * partition, so an aws-only estate of fifteen stacks answers "aws changed" no
+ * matter which one moved. That answer cannot be joined to anything: a
+ * component's deploy step names a stack, not a lexicon, so
+ * `componentsForUnits` (../components/fan-out.ts) would claim none of it and
+ * a fan-out derived from it would be empty. The two halves have to speak the
+ * same names for either to be worth having.
+ *
+ * A stack that serializes through more than one lexicon folds its partitions
+ * into one artifact, because the unit being deployed is the stack.
+ */
+async function stackArtifacts(root, serializers, stacks, 
+/**
+ * Whether a missing `src` is an error. True for the head side, where every
+ * declared stack must exist; false for the base side, where a stack added
+ * since then legitimately has no source yet and reads as an empty artifact,
+ * which is what makes it `changed`.
+ */
+requireSrc) {
+    const artifacts = new Map();
+    const externalInput = [];
+    for (const stack of stacks) {
+        const src = resolve(root, stack.src);
+        // `build()` on a directory that is not there returns empty outputs rather
+        // than throwing, so a typo in `src` would make both sides build nothing,
+        // match, and report the stack as unchanged forever. A silent answer of
+        // exactly that shape is what this whole path exists to prevent.
+        if (requireSrc && !existsSync(src)) {
+            throw new Error(`stack "${stack.name}" declares src "${stack.src}", which does not exist under ${root}. ` +
+                `Fix chant.config.ts's stacks[] entry: a source directory that is not there builds to nothing, ` +
+                `and a stack that builds to nothing can never be reported as changed.`);
+        }
+        const built = await build(src, serializers);
+        artifacts.set(stack.name, [...built.outputs.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([lexicon, output]) => `${lexicon}\n${getPrimaryOutput(output)}`)
+            .join("\n"));
+        if (externalInputStacks(built.entities).length > 0)
+            externalInput.push(stack.name);
+    }
+    return { artifacts, externalInput: externalInput.sort() };
+}
+/**
+ * Compute the affected stacks for a change. Head is built in place (the working
+ * tree); base is built from `baseDir` if supplied, else from `baseRef` via a
+ * single throwaway worktree. Builds are deterministic, so a cached/supplied base
+ * is as trustworthy as a rebuild.
+ */
+export async function affectedStacks(opts) {
+    const projectPath = resolve(opts.projectPath);
+    const needsWorktree = Boolean(opts.headRef) || Boolean(opts.baseRef && !opts.baseDir);
+    const repoRoot = needsWorktree ? await gitTopLevel(projectPath) : projectPath;
+    // Canonicalize via realpath so the worktree-relative path is correct even when
+    // the temp dir is a symlink (macOS /var → /private/var) and `git
+    // rev-parse --show-toplevel` reports the real path.
+    const relProject = needsWorktree ? relative(repoRoot, realpathSync(projectPath)) : "";
+    // Head: the in-place build of the working tree, unless an explicit headRef is
+    // given (then a throwaway worktree — removed before the base worktree, so at
+    // most one exists at a time).
+    const perStack = opts.stacks && opts.stacks.length > 0 ? opts.stacks : undefined;
+    // No cross-stack graph in per-stack mode, by construction: see `stacks` above.
+    const EMPTY_GRAPH = { nodes: [], edges: [], order: [], waves: [], cycles: [] };
+    /** One build root in, its artifact map and external-input set out, at whichever granularity applies. */
+    const readArtifacts = async (root, isHead) => {
+        if (perStack)
+            return { ...(await stackArtifacts(root, opts.serializers, perStack, isHead)), graph: EMPTY_GRAPH };
+        const built = await build(root, opts.serializers);
+        return {
+            artifacts: artifactMap(built.outputs),
+            externalInput: externalInputStacks(built.entities),
+            graph: built.manifest.stackGraph,
+        };
+    };
+    const head = opts.headRef
+        ? await withWorktree(repoRoot, opts.headRef, (dir) => readArtifacts(join(dir, relProject), true))
+        : await readArtifacts(projectPath, true);
+    // Base: caller-supplied dir (cheapest), else a single worktree at baseRef.
+    let baseMap;
+    if (opts.baseDir) {
+        baseMap = (await readArtifacts(resolve(opts.baseDir), false)).artifacts;
+    }
+    else if (opts.baseRef) {
+        baseMap = await withWorktree(repoRoot, opts.baseRef, async (dir) => (await readArtifacts(join(dir, relProject), false)).artifacts);
+    }
+    else {
+        throw new Error("affectedStacks requires either baseDir or baseRef");
+    }
+    return computeAffected(baseMap, head.artifacts, head.graph, {
+        includeDependents: opts.includeDependents,
+        externalInput: head.externalInput,
+    });
+}

package/dist/lifecycle/assert-live.js

@@ -0,0 +1,110 @@
+/**
+ * assertLive (#1857) — the read half of the test harness (#1224):
+ * observation-backed assertions against a live deploy, for exactly one
+ * declared entity at a time. Same primitive teardown.ts's fallback path
+ * uses — `describeResources` — turned into a pass/throw instead of a
+ * would-delete set.
+ *
+ * The observation contract (#1089) draws a hard line between OBSERVED-ABSENT
+ * and NOT-OBSERVED: a declared entity the read could not cover is never the
+ * same as one confirmed missing. `assertLiveEntity` preserves that line by
+ * construction — NOT-OBSERVED throws {@link UnobservedAssertionError}, a type
+ * distinct from the {@link LiveAssertionError} an observed-absent, foreign,
+ * or status-mismatched verdict throws, so a caller can tell "could not tell"
+ * from "confirmed wrong" without parsing a message.
+ *
+ * Marker verification is best-effort by the same logic {@link
+ * ResourceMetadata.marker}'s own contract states: a lexicon with no marker
+ * channel on this read path reports no marker at all, which is not the same
+ * claim as "foreign". Enforcing a match whenever the channel exists — a present
+ * mismatch, or `ownership: "foreign"` with no marker to show — catches the
+ * case the harness cares about (a same-named leftover from another env);
+ * an absent channel is passed through unverified rather than making every
+ * lexicon without one unusable.
+ */
+import { normalizeObservation, unobservedAll, unobservedReasonText } from "../observation.js";
+/**
+ * Thrown by {@link assertLiveEntity} for a confirmed failure: observed
+ * absent, a marker that names another stack/env, a resource confirmed
+ * foreign, or a status mismatch. Never thrown for NOT-OBSERVED — see {@link
+ * UnobservedAssertionError}.
+ */
+export class LiveAssertionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LiveAssertionError";
+    }
+}
+/**
+ * Thrown when the entity is NOT-OBSERVED (#1089) rather than confirmed
+ * present or absent. Kept as its own type, not a flag on {@link
+ * LiveAssertionError}: a suite (or a CI policy) that wants to fail loudly on
+ * "could not tell" but treat it differently from a confirmed miss can catch
+ * this one specifically.
+ */
+export class UnobservedAssertionError extends Error {
+    constructor(entity, reason, detail) {
+        super(`assertLive("${entity}") is NOT-OBSERVED — ${unobservedReasonText(reason)}` +
+            `${detail ? `: ${detail}` : ""}. An entity chant could not read is never the same as one confirmed absent.`);
+        this.entity = entity;
+        this.reason = reason;
+        this.detail = detail;
+        this.name = "UnobservedAssertionError";
+    }
+}
+/** True when `meta` names a different stack/env than `marker`, on whichever signal it carries. */
+function isConfirmedForeign(meta, marker) {
+    if (meta.marker)
+        return meta.marker.stack !== marker.stack || meta.marker.env !== marker.env;
+    return meta.ownership === "foreign";
+}
+/**
+ * Assert one declared entity is live: observed present in `environment`, not
+ * a confirmed-foreign resource, and — when `status` is given — reporting
+ * that status. Resolves to the entity's {@link ResourceMetadata} on success.
+ *
+ * Throws {@link UnobservedAssertionError} for NOT-OBSERVED. Throws {@link
+ * LiveAssertionError} for observed-absent, a confirmed-foreign identity, or a
+ * status mismatch.
+ */
+export async function assertLiveEntity(opts) {
+    const { plugin, name, entityType, props, buildOutput, environment, marker, status } = opts;
+    if (!plugin.describeResources) {
+        throw new UnobservedAssertionError(name, "unsupported-kind", `the "${plugin.name}" lexicon implements no describeResources`);
+    }
+    let observed;
+    try {
+        observed = normalizeObservation(await plugin.describeResources({
+            environment,
+            buildOutput,
+            entityNames: [name],
+            entities: new Map([[name, { entityType, props }]]),
+        }));
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        observed = {
+            resources: {},
+            unobserved: unobservedAll([name], "read-failed", detail, { [name]: entityType }),
+            queried: {},
+            sources: {},
+            notes: [],
+        };
+    }
+    const unobserved = observed.unobserved[name];
+    if (unobserved)
+        throw new UnobservedAssertionError(name, unobserved.reason, unobserved.detail);
+    const meta = observed.resources[name];
+    if (!meta) {
+        throw new LiveAssertionError(`assertLive("${name}"): observed absent — chant looked and "${environment}" reported no such resource.`);
+    }
+    if (isConfirmedForeign(meta, marker)) {
+        const found = meta.marker ? `{ stack: "${meta.marker.stack}", env: "${meta.marker.env ?? ""}" }` : "no chant marker";
+        throw new LiveAssertionError(`assertLive("${name}"): observed, but it is not this deploy's — carries ${found}, not ` +
+            `{ stack: "${marker.stack}", env: "${marker.env ?? ""}" }. A same-named resource from another stack or env cannot satisfy this assertion.`);
+    }
+    if (status !== undefined && meta.status !== status) {
+        throw new LiveAssertionError(`assertLive("${name}", { status: "${status}" }): observed with status "${meta.status}".`);
+    }
+    return meta;
+}