@intentius/chant 0.124.13 → 0.124.14

package/dist/lifecycle/scenario-eval.js

@@ -0,0 +1,204 @@
+/**
+ * Pure evaluation of a plan scenario's `expect` clause against a `ChangeSet`
+ * (#1292).
+ *
+ * `evaluateScenario` reads only what the caller hands it — a `ChangeSet` and
+ * a `ScenarioExpect` — and does no I/O. Building the change set (reading a
+ * fixture, replaying it in place of a live observation) is the CLI handler's
+ * job (../cli/handlers/scenario.ts); this module is the part that stays
+ * testable without a filesystem, a build, or a fixture.
+ *
+ * Built on the same primitives `chant lifecycle plan` already computes from:
+ * `summarize` for counts, a filter over `cs.entries` for named deletes and
+ * ownership, and `evaluateUnobservedGate` (./unobserved-gate.ts, #1568) for
+ * the unobserved clause.
+ */
+import { summarize } from "./change-set.js";
+import { evaluateUnobservedGate } from "./unobserved-gate.js";
+import { unobservedReasonText } from "../observation.js";
+import { isBehaviourRefusalReport, renderBehaviourRefusal } from "../behaviour.js";
+import { formatPerHour } from "../behaviour-delta.js";
+/**
+ * Evaluate `expect` against `cs`. Pure: reads `cs`, `expect` and, for a
+ * `cost` clause, the fixture's `behaviour` block handed over as `behaviour`;
+ * computes nothing else. Every clause present on `expect` is checked
+ * independently and every one contributes to `checks`; `pass` is true only
+ * when all of them are.
+ */
+export function evaluateScenario(cs, expect, behaviour) {
+    const counts = summarize(cs);
+    const checks = [];
+    if (expect.noop) {
+        // An effect receipt's fire (#1832) is a real proposed action — a
+        // migration or seed job about to run — even though it never counts
+        // toward the create/update/delete triad `buildChangeSet` classifies
+        // ordinary resources into. `noop: true` claims the plan does nothing;
+        // a pending effect fire is something, so it offends the claim exactly
+        // like a create/update/delete would.
+        const offenders = { create: counts.create, update: counts.update, delete: counts.delete, effect: counts.effect };
+        const clean = offenders.create === 0 && offenders.update === 0 && offenders.delete === 0 && offenders.effect === 0;
+        checks.push({
+            clause: "noop",
+            pass: clean,
+            ...(clean
+                ? {}
+                : {
+                    detail: `expected noop (no create/update/delete/effect) but the plan proposes ` +
+                        `${offenders.create} create, ${offenders.update} update, ${offenders.delete} delete, ${offenders.effect} effect — ` +
+                        nameList(cs, ["create", "update", "delete", "effect"]),
+                }),
+        });
+    }
+    for (const clause of ["create", "update", "delete"]) {
+        const want = expect[clause];
+        if (want === undefined)
+            continue;
+        const got = counts[clause];
+        const pass = got === want;
+        checks.push({
+            clause,
+            pass,
+            ...(pass ? {} : { detail: `expected ${want} ${clause}, plan proposes ${got} — ${nameList(cs, [clause])}` }),
+        });
+    }
+    if (expect.deletes) {
+        checks.push(evaluateDeletesClause(cs, expect.deletes));
+    }
+    if (expect.unobserved !== undefined) {
+        checks.push(evaluateUnobservedClause(cs, expect.unobserved));
+    }
+    if (expect.cost !== undefined) {
+        checks.push(evaluateCostClause(expect.cost, behaviour));
+    }
+    return { pass: checks.every((c) => c.pass), checks };
+}
+/**
+ * The `cost` clause (#2358). Three refusals before any number is read, each
+ * naming why, because the alternative to each is a bound that passes on
+ * nothing:
+ *
+ *  - no `behaviour` block in the fixture — nothing was predicted;
+ *  - the block is a refusal — the engine was absent, unreachable, out of
+ *    credit, over quota, or refused a credential, and the fixture carries
+ *    that refusal's own text;
+ *  - the named entity is not in the fixture's figures — declined with a
+ *    reason, or never asked about.
+ *
+ * The figure is then one of three, and the detail says which: the named
+ * entity's own rate, the engine's stated total, or chant's sum over every
+ * predicted entity when the engine states no total. The sum is chant's own
+ * arithmetic and is labelled so; it also names every entity the engine
+ * declined, because those are in the estate and not in the sum.
+ */
+function evaluateCostClause(bound, behaviour) {
+    const fail = (detail) => ({ clause: "cost", pass: false, detail });
+    if (behaviour === undefined || "missing" in behaviour) {
+        return fail(`${behaviour?.missing ?? "the fixture carries no `behaviour` block"} — a cost bound is checked against the ` +
+            "fixture's recorded prediction, and there is none. Record one on the snapshot, or drop the clause.");
+    }
+    const result = behaviour.result;
+    if (isBehaviourRefusalReport(result)) {
+        return fail(`the fixture's prediction is a refusal (${result.refusal.cause}), and a bound cannot be checked against no ` +
+            `figure: ${renderBehaviourRefusal(result.refusal, { color: false }).replace(/\n\s*/g, " ")}`);
+    }
+    const declined = Object.entries(result.unpredicted ?? {}).map(([name, u]) => `${name} (${u.reason}${u.detail ? `: ${u.detail}` : ""})`);
+    const declinedNote = declined.length > 0 ? `; ${declined.length} declined and not in the figure: ${declined.join(", ")}` : "";
+    let perHour;
+    let currency;
+    let which;
+    if (bound.entity !== undefined) {
+        const figure = Object.prototype.hasOwnProperty.call(result.entities, bound.entity)
+            ? result.entities[bound.entity]
+            : undefined;
+        if (!figure) {
+            const hole = result.unpredicted?.[bound.entity];
+            return fail(hole
+                ? `"${bound.entity}" was declined by the engine (${hole.reason}${hole.detail ? `: ${hole.detail}` : ""}), so it has no figure to bound`
+                : `"${bound.entity}" is in neither the fixture's figures nor its declined entities — the prediction never asked about it`);
+        }
+        perHour = figure.cost.perHour;
+        currency = figure.cost.currency;
+        which = `${bound.entity}'s own rate (${figure.provenance.engine} ${figure.provenance.version}, ${figure.provenance.tolerance}, ${figure.provenance.basis})`;
+    }
+    else if (result.meta.total) {
+        perHour = result.meta.total.perHour;
+        currency = result.meta.total.currency;
+        which = `the engine's own estate total (${result.meta.engine} ${result.meta.version})${declinedNote}`;
+    }
+    else {
+        const names = Object.keys(result.entities);
+        const currencies = new Set(names.map((n) => result.entities[n].cost.currency));
+        if (currencies.size > 1) {
+            return fail(`the engine states no total and the entities are priced in ${[...currencies].sort().join(", ")} — chant converts ` +
+                "nothing, so there is no one sum to bound");
+        }
+        if (names.length === 0) {
+            return fail(`the engine states no total and predicted no entity${declinedNote} — nothing to bound`);
+        }
+        perHour = names.reduce((sum, n) => sum + result.entities[n].cost.perHour, 0);
+        currency = [...currencies][0];
+        which = `chant's own sum over ${names.length} predicted entit${names.length === 1 ? "y" : "ies"} (the engine states no total)${declinedNote}`;
+    }
+    const level = result.meta.at.traffic;
+    if (currency !== bound.currency) {
+        return fail(`the bound is in ${bound.currency} and the figure is ${formatPerHour(perHour)} ${currency}/hour at "${level}" — ` +
+            `chant converts nothing; read from ${which}`);
+    }
+    const pass = perHour <= bound.maxPerHour;
+    const detail = `${pass ? "" : "exceeded: "}${formatPerHour(perHour)} ${currency}/hour at "${level}" against a bound of ` +
+        `${formatPerHour(bound.maxPerHour)} ${bound.currency}/hour; read from ${which}`;
+    return { clause: "cost", pass, detail };
+}
+/** Names (with type) of every entry matching one of `actions`, for a legible failure message. */
+function nameList(cs, actions) {
+    const names = cs.entries
+        .filter((e) => actions.includes(e.action))
+        .map((e) => `${e.name}${e.type ? ` (${e.type})` : ""} [${e.action}]`);
+    return names.length === 0 ? "(no matching entries)" : names.join(", ");
+}
+function evaluateDeletesClause(cs, wanted) {
+    const actualDeletes = cs.entries.filter((e) => e.action === "delete");
+    const actualByName = new Map(actualDeletes.map((e) => [e.name, e]));
+    const wantedNames = new Set(wanted.map((w) => w.name));
+    const problems = [];
+    for (const want of wanted) {
+        const match = actualByName.get(want.name);
+        if (!match) {
+            problems.push(`"${want.name}" (ownership ${want.ownership}) — not proposed for delete`);
+        }
+        else if (match.ownership !== want.ownership) {
+            problems.push(`"${want.name}" — expected ownership "${want.ownership}", plan proposes ownership "${match.ownership}"`);
+        }
+    }
+    for (const e of actualDeletes) {
+        if (!wantedNames.has(e.name)) {
+            problems.push(`"${e.name}"${e.type ? ` (${e.type})` : ""} [${e.ownership}] — deleted but not expected`);
+        }
+    }
+    return {
+        clause: "deletes",
+        pass: problems.length === 0,
+        ...(problems.length > 0 ? { detail: problems.join("; ") } : {}),
+    };
+}
+function evaluateUnobservedClause(cs, policy) {
+    // evaluateUnobservedGate enumerates every unobserved row regardless of
+    // reason — "refuse" collects the full set to check against below. A
+    // scenario's allow list names ENTITIES, not reasons (./scenario.ts's
+    // ScenarioUnobservedPolicy doc explains why), so the gate's own reason-keyed
+    // policy isn't reused for the pass/fail decision — only for the enumeration.
+    const gate = evaluateUnobservedGate(cs, "refuse");
+    const allowedNames = typeof policy === "object" ? new Set(policy.allow) : undefined;
+    const unallowed = gate.findings.filter((f) => !allowedNames?.has(f.name));
+    return {
+        clause: "unobserved",
+        pass: unallowed.length === 0,
+        ...(unallowed.length > 0
+            ? {
+                detail: unallowed
+                    .map((f) => `${f.name}${f.type ? ` (${f.type})` : ""} — ${unobservedReasonText(f.reason)}${f.detail ? `: ${f.detail}` : ""}`)
+                    .join(", "),
+            }
+            : {}),
+    };
+}

package/dist/lifecycle/scenario.js

@@ -0,0 +1,214 @@
+/**
+ * Plan scenarios (chant #1292): a declared expectation about what a change
+ * SHOULD do, checkable offline against a fixture snapshot.
+ *
+ * Everything else chant validates is about shape — is this declaration
+ * well-formed, does this reference resolve. Nothing answers "what will this
+ * change do" as something source can assert about itself, until now. A
+ * `Scenario` pairs a `given` (a stand-in for live observation) with an
+ * `expect` (a claim about the resulting change set) — `chant scenario check`
+ * (../cli/handlers/scenario.ts) builds the project, replays `given` in place
+ * of a live read, and evaluates `expect` against the resulting `ChangeSet`
+ * (./change-set.ts) via `evaluateScenario` (./scenario-eval.ts).
+ *
+ * Modeled precisely on the other non-resource Declarables (../effect-receipt.ts,
+ * ../secret-provenance.ts): discovery collects a `Scenario` like any entity
+ * (it is a Declarable), but it carries no resource payload and no serializer
+ * ever emits it — `partitionByLexicon` (../build.ts) excludes it from every
+ * lexicon's partition, the same way it excludes a secret declaration.
+ *
+ * This module is pure and does no I/O: `snapshot()` records where the fixture
+ * comes from without reading it, and the factory validates and freezes. The
+ * CLI handler is where the fixture is actually read, replayed, and compared —
+ * the same synthesis/plan split every other lifecycle primitive here follows.
+ */
+import { DECLARABLE_MARKER } from "../declarable.js";
+/** Marker symbol identifying a scenario declaration. `Symbol.for` so it
+ * survives the entity-wire codec, the same reason ../effect-receipt.ts and
+ * ../secret-provenance.ts use `Symbol.for` for their markers. */
+export const SCENARIO_MARKER = Symbol.for("chant.scenario");
+/** The `entityType` every scenario declaration carries. */
+export const SCENARIO_ENTITY_TYPE = "Chant::Scenario";
+/**
+ * Declare `given` from a single string. Pure and offline: no filesystem
+ * access, no git — the factory only classifies the string's SHAPE, never
+ * checks whether it exists. That is what keeps `Scenario` foldable under
+ * `--sandbox`, the same discipline `declareSecret`'s committed-encrypted path
+ * validation follows (../secret-provenance.ts).
+ *
+ * The classification is structural: a string containing a path separator or
+ * ending in `.json` is a fixture file; anything else (a bare token like
+ * `"prod"`) is an environment name. A `chant.config.ts` environment name that
+ * happens to contain a slash or end in `.json` is not supported by this
+ * heuristic — pass `{ kind: "env", env }` directly in that unlikely case.
+ */
+export function snapshot(source) {
+    if (typeof source !== "string" || source.length === 0) {
+        throw new Error("snapshot: `source` must be a non-empty string");
+    }
+    const looksLikeFile = source.includes("/") || source.includes("\\") || source.toLowerCase().endsWith(".json");
+    return looksLikeFile ? { kind: "file", path: source } : { kind: "env", env: source };
+}
+/** Every recognized `expect` clause key — for the excess-key check below and
+ * for exhaustiveness at call sites. */
+export const EXPECT_KEYS = ["noop", "create", "update", "delete", "deletes", "unobserved", "cost"];
+const OWNERSHIP_VALUES = ["owned", "foreign", "unknown"];
+/**
+ * Declare a plan scenario. The returned object is a locked Declarable:
+ * declared fields are immutable and nested structures are frozen, the same
+ * shape ../effect-receipt.ts and ../secret-provenance.ts lock down; the
+ * top-level object stays extensible so discovery can still stamp its own
+ * symbol-keyed metadata.
+ */
+export function Scenario(name, options) {
+    if (typeof name !== "string" || name.length === 0) {
+        throw new Error("Scenario: `name` must be a non-empty string");
+    }
+    const given = validateGiven(name, options?.given);
+    const expect = validateExpect(name, options?.expect);
+    const decl = {
+        [DECLARABLE_MARKER]: true,
+        [SCENARIO_MARKER]: true,
+        lexicon: "chant",
+        entityType: SCENARIO_ENTITY_TYPE,
+        name,
+        given,
+        expect,
+    };
+    for (const key of Object.keys(decl)) {
+        Object.defineProperty(decl, key, { writable: false, configurable: false });
+    }
+    return decl;
+}
+function validateGiven(name, given) {
+    if (typeof given !== "object" || given === null) {
+        throw new Error(`Scenario("${name}"): \`given\` is required — use snapshot(path) or snapshot(env)`);
+    }
+    const g = given;
+    if (g.kind === "file") {
+        if (typeof g.path !== "string" || g.path.length === 0) {
+            throw new Error(`Scenario("${name}"): \`given\` of kind "file" requires a non-empty \`path\``);
+        }
+        return Object.freeze({ kind: "file", path: g.path });
+    }
+    if (g.kind === "env") {
+        if (typeof g.env !== "string" || g.env.length === 0) {
+            throw new Error(`Scenario("${name}"): \`given\` of kind "env" requires a non-empty \`env\``);
+        }
+        return Object.freeze({ kind: "env", env: g.env });
+    }
+    throw new Error(`Scenario("${name}"): \`given\` must come from snapshot(path) or snapshot(env), got kind "${String(g.kind)}"`);
+}
+function validateExpect(name, expect) {
+    if (typeof expect !== "object" || expect === null || Array.isArray(expect)) {
+        throw new Error(`Scenario("${name}"): \`expect\` must be a plain object`);
+    }
+    const e = expect;
+    for (const key of Object.keys(e)) {
+        if (!EXPECT_KEYS.includes(key)) {
+            throw new Error(`Scenario("${name}"): unknown \`expect\` clause "${key}" — expected one of ${EXPECT_KEYS.join(", ")}`);
+        }
+    }
+    if (Object.keys(e).length === 0) {
+        throw new Error(`Scenario("${name}"): \`expect\` must include at least one clause (${EXPECT_KEYS.join(", ")}) — an empty expect asserts nothing`);
+    }
+    const out = {};
+    if ("noop" in e) {
+        if (e.noop !== true) {
+            throw new Error(`Scenario("${name}"): \`expect.noop\`, when present, must be exactly \`true\``);
+        }
+        out.noop = true;
+    }
+    for (const countKey of ["create", "update", "delete"]) {
+        if (countKey in e) {
+            const v = e[countKey];
+            if (typeof v !== "number" || !Number.isInteger(v) || v < 0) {
+                throw new Error(`Scenario("${name}"): \`expect.${countKey}\`, when present, must be a non-negative integer`);
+            }
+            out[countKey] = v;
+        }
+    }
+    if ("deletes" in e) {
+        if (!Array.isArray(e.deletes)) {
+            throw new Error(`Scenario("${name}"): \`expect.deletes\` must be an array`);
+        }
+        out.deletes = Object.freeze(e.deletes.map((d, i) => {
+            if (typeof d !== "object" || d === null) {
+                throw new Error(`Scenario("${name}"): \`expect.deletes[${i}]\` must be an object`);
+            }
+            const { name: deleteName, ownership } = d;
+            if (typeof deleteName !== "string" || deleteName.length === 0) {
+                throw new Error(`Scenario("${name}"): \`expect.deletes[${i}].name\` must be a non-empty string`);
+            }
+            if (!OWNERSHIP_VALUES.includes(ownership)) {
+                throw new Error(`Scenario("${name}"): \`expect.deletes[${i}].ownership\` must be one of ${OWNERSHIP_VALUES.join(", ")}`);
+            }
+            return Object.freeze({ name: deleteName, ownership: ownership });
+        }));
+    }
+    if ("unobserved" in e) {
+        const u = e.unobserved;
+        if (u === "refuse") {
+            out.unobserved = "refuse";
+        }
+        else if (typeof u === "object" && u !== null && Array.isArray(u.allow)) {
+            const allow = u.allow;
+            allow.forEach((entry, i) => {
+                if (typeof entry !== "string" || entry.length === 0) {
+                    throw new Error(`Scenario("${name}"): \`expect.unobserved.allow[${i}]\` must be a non-empty string`);
+                }
+            });
+            out.unobserved = Object.freeze({ allow: Object.freeze([...allow]) });
+        }
+        else {
+            throw new Error(`Scenario("${name}"): \`expect.unobserved\` must be "refuse" or { allow: [names] }`);
+        }
+    }
+    if ("cost" in e) {
+        const c = e.cost;
+        if (typeof c !== "object" || c === null || Array.isArray(c)) {
+            throw new Error(`Scenario("${name}"): \`expect.cost\` must be { maxPerHour, currency, entity? }`);
+        }
+        const { maxPerHour, currency, entity } = c;
+        if (typeof maxPerHour !== "number" || !Number.isFinite(maxPerHour) || maxPerHour < 0) {
+            throw new Error(`Scenario("${name}"): \`expect.cost.maxPerHour\` must be a non-negative finite number`);
+        }
+        if (typeof currency !== "string" || currency.trim() === "") {
+            throw new Error(`Scenario("${name}"): \`expect.cost.currency\` must be a non-empty ISO 4217 code — chant converts nothing, so a bound needs its currency`);
+        }
+        if (entity !== undefined && (typeof entity !== "string" || entity.length === 0)) {
+            throw new Error(`Scenario("${name}"): \`expect.cost.entity\`, when present, must be a non-empty string`);
+        }
+        for (const key of Object.keys(c)) {
+            if (!["maxPerHour", "currency", "entity"].includes(key)) {
+                throw new Error(`Scenario("${name}"): unknown \`expect.cost\` field "${key}" — expected maxPerHour, currency, entity`);
+            }
+        }
+        out.cost = Object.freeze({
+            maxPerHour,
+            currency: currency.trim(),
+            ...(entity !== undefined ? { entity } : {}),
+        });
+    }
+    return Object.freeze(out);
+}
+/** Type guard for a scenario declaration. */
+export function isScenario(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        SCENARIO_MARKER in value &&
+        value[SCENARIO_MARKER] === true);
+}
+/**
+ * Extract the scenario declarations from a discovered entity map — the read
+ * surface `chant scenario check` (../cli/handlers/scenario.ts) uses. Keyed by
+ * entity name (export name), the same key `DiscoveryResult.entities` uses.
+ */
+export function collectScenarios(entities) {
+    const out = new Map();
+    for (const [name, entity] of entities) {
+        if (isScenario(entity))
+            out.set(name, entity);
+    }
+    return out;
+}

package/dist/lifecycle/snapshot.js

@@ -0,0 +1,239 @@
+import { observeDeep } from "./deep-observe.js";
+import { computeBuildDigest } from "./digest.js";
+import { collectDependencies, collectAmbient } from "./observe.js";
+import { writeSnapshot, snapshotStorageKey, getHeadCommit, pushLifecycle } from "./git.js";
+import { sortedJsonReplacer } from "../utils.js";
+import { formatUnobserved, normalizeObservation, unobservedAll } from "../observation.js";
+// One list of secret-bearing property names for both observation depths
+// (#1014): the thin path warns on them here, the deep path masks them before a
+// property tree is ever rendered or committed. Two lists would eventually
+// disagree about what counts as a secret.
+import { isSensitiveKey } from "../deep-observation.js";
+import { isObservableDeclarable } from "../declarable.js";
+/**
+ * Check for potential sensitive data in resource attributes and return warnings.
+ */
+function checkSensitiveData(resources) {
+    const warnings = [];
+    for (const [name, meta] of Object.entries(resources)) {
+        if (!meta.attributes)
+            continue;
+        for (const attrName of Object.keys(meta.attributes)) {
+            if (isSensitiveKey(attrName)) {
+                warnings.push(`Potential sensitive data in ${name}.attributes.${attrName} — ensure it is scrubbed`);
+            }
+        }
+    }
+    return warnings;
+}
+/**
+ * Validate ResourceMetadata entries — resources must have at least type and status.
+ * Returns { valid, dropped, warnings }.
+ */
+function validateResources(resources) {
+    const valid = {};
+    const dropped = [];
+    const warnings = [];
+    for (const [name, meta] of Object.entries(resources)) {
+        if (!meta.type || !meta.status) {
+            dropped.push(name);
+            warnings.push(`Dropped ${name}: missing type or status`);
+            continue;
+        }
+        valid[name] = meta;
+    }
+    // Check for sensitive data in valid resources
+    warnings.push(...checkSensitiveData(valid));
+    return { valid, dropped, warnings };
+}
+/**
+ * Take state snapshots for all plugins that implement describeResources.
+ */
+export async function takeSnapshot(environment, plugins, buildResult, opts) {
+    const stack = opts?.stack;
+    const depth = opts?.deep ? "deep" : "identity";
+    // A stack declares the region it deploys to (#1261). Passing it through is
+    // what lets a multi-region estate be observed at all: the reader targets the
+    // stack's own region rather than whichever one the shell happens to be set
+    // to, so out-of-region stacks stop coming back empty.
+    const region = opts?.region;
+    const warnings = [];
+    const errors = [];
+    const snapshots = [];
+    const headCommit = await getHeadCommit(opts);
+    const timestamp = new Date().toISOString();
+    const digest = computeBuildDigest(buildResult);
+    for (const plugin of plugins) {
+        if (!plugin.describeResources && !plugin.listArtifacts)
+            continue;
+        // Get serialized build output for this lexicon
+        const rawOutput = buildResult.outputs.get(plugin.name);
+        const buildOutput = rawOutput === undefined
+            ? ""
+            : typeof rawOutput === "string"
+                ? rawOutput
+                : rawOutput.primary;
+        // Get entity names + entity props for this lexicon
+        const entityNames = [];
+        const entities = new Map();
+        for (const [name, entity] of buildResult.entities) {
+            // Resource declarables only — outputs, parameters and serializer
+            // directives have no live counterpart (see lifecycle/observe.ts).
+            if (entity.lexicon === plugin.name && isObservableDeclarable(entity)) {
+                entityNames.push(name);
+                entities.set(name, {
+                    entityType: entity.entityType,
+                    props: (entity.props != null ? entity.props : {}),
+                });
+            }
+        }
+        let resources = {};
+        let artifacts = {};
+        let unobserved = {};
+        let stackExports;
+        try {
+            if (plugin.describeResources) {
+                const observed = normalizeObservation(await plugin.describeResources({
+                    environment,
+                    buildOutput,
+                    entityNames,
+                    entities,
+                    stack,
+                    region,
+                }));
+                const { valid, dropped, warnings: validationWarnings } = validateResources(observed.resources);
+                warnings.push(...validationWarnings);
+                if (dropped.length > 0) {
+                    warnings.push(`${plugin.name}: dropped ${dropped.length} invalid resource(s)`);
+                }
+                resources = valid;
+                // Record the holes (#1089). A snapshot is evidence of what was seen; an
+                // entity nobody could read must not be recorded as "was not there",
+                // because the next diff would then read it back as absent.
+                unobserved = observed.unobserved;
+                stackExports = observed.stackExports;
+                for (const [name, entry] of Object.entries(unobserved)) {
+                    warnings.push(`${plugin.name}: not observed — ${formatUnobserved(name, entry)}`);
+                }
+            }
+            if (plugin.listArtifacts) {
+                // No region: artifacts are registry/chart objects (docker, helm), not
+                // regional cloud resources, and `listArtifacts` takes no region.
+                const raw = await plugin.listArtifacts({ environment, entities, stack });
+                const { valid, dropped, warnings: validationWarnings } = validateResources(raw);
+                warnings.push(...validationWarnings);
+                if (dropped.length > 0) {
+                    warnings.push(`${plugin.name}: dropped ${dropped.length} invalid artifact(s)`);
+                }
+                artifacts = valid;
+            }
+            if (Object.keys(resources).length === 0 && Object.keys(artifacts).length === 0) {
+                const unreadable = Object.keys(unobserved).length;
+                errors.push(unreadable > 0
+                    ? `${plugin.name}: nothing observed — ${unreadable} declared entity(ies) could not be read (see warnings); not snapshotting an unread environment as empty`
+                    : `${plugin.name}: no valid resources or artifacts returned`);
+                continue;
+            }
+            // The deep read is a second pass, after identity is known to be readable
+            // (#1267). Keeping it separate means a lexicon with no deep reader still
+            // snapshots exactly as before, and a deep read that comes back empty
+            // downgrades the record rather than discarding an identity snapshot that
+            // was already good.
+            let properties;
+            let recordedDepth = "identity";
+            if (depth === "deep") {
+                if (!plugin.observeResourcesDeep) {
+                    warnings.push(`${plugin.name}: no deep reader — recording an identity snapshot; property questions cannot be answered from it`);
+                }
+                else {
+                    const observed = await observeDeep(plugin, {
+                        environment,
+                        buildOutput,
+                        entities,
+                        ...(stack ? { stack } : {}),
+                        ...(region ? { region } : {}),
+                    });
+                    for (const [name, entry] of Object.entries(observed.unobserved)) {
+                        warnings.push(`${plugin.name}: not observed deeply — ${formatUnobserved(name, entry)}`);
+                    }
+                    if (Object.keys(observed.resources).length > 0) {
+                        properties = observed.resources;
+                        recordedDepth = "deep";
+                    }
+                    else {
+                        warnings.push(`${plugin.name}: deep read returned no properties — recording an identity snapshot`);
+                    }
+                }
+            }
+            // What this estate depends on but does not manage (#1273), recorded so a
+            // replayed snapshot can answer the same questions a live read can (#1266).
+            // Without them a snapshot holds the managed resources and no route to the
+            // account's default VPC, so `internetFacing` is unanswerable from it —
+            // which would make `search --at` quietly weaker than `search --live`.
+            const dependencies = await collectDependencies(plugin, {
+                environment,
+                entities,
+                observed: resources,
+                stacks: stack ? [{ name: stack, ...(region ? { region } : {}) }] : [],
+            });
+            for (const message of dependencies.warnings)
+                warnings.push(message);
+            // Ambient resources (#1278) are recorded too when asked for, so a replayed
+            // snapshot can answer "which of these are unused" without a live read.
+            // Without this `search --at --ambient` filters a set that was never
+            // recorded and silently returns nothing.
+            const ambient = opts?.ambient
+                ? await collectAmbient(plugin, {
+                    environment,
+                    kinds: opts?.ambientKinds ?? [...new Set([...entities.values()].map((e) => e.entityType))],
+                    observed: resources,
+                    stacks: stack ? [{ name: stack, ...(region ? { region } : {}) }] : [],
+                    warnings,
+                })
+                : {};
+            const withDependencies = { ...resources, ...dependencies.resources, ...ambient };
+            const snapshot = {
+                lexicon: plugin.name,
+                environment,
+                ...(stack ? { stack } : {}),
+                commit: headCommit,
+                timestamp,
+                resources: withDependencies,
+                ...(dependencies.edges.length > 0 ? { edges: dependencies.edges } : {}),
+                ...(stackExports && Object.keys(stackExports).length > 0 ? { stackExports } : {}),
+                ...(Object.keys(unobserved).length > 0 && { unobserved }),
+                ...(Object.keys(artifacts).length > 0 && { artifacts }),
+                // Only written when deep. An absent field means identity, which is what
+                // every snapshot taken before #1267 was.
+                ...(recordedDepth === "deep" && { depth: recordedDepth, properties }),
+                digest,
+            };
+            snapshots.push(snapshot);
+        }
+        catch (err) {
+            // A thrown read is not an empty environment — record nothing and say so
+            // (#1089). Writing a snapshot here would persist "none of this exists".
+            errors.push(`${plugin.name}: ${err instanceof Error ? err.message : String(err)}`);
+            const message = err instanceof Error ? err.message : String(err);
+            for (const [name, entry] of Object.entries(unobservedAll(entityNames, "read-failed", message, entities))) {
+                warnings.push(`${plugin.name}: not observed — ${formatUnobserved(name, entry)}`);
+            }
+        }
+    }
+    // Write all successful snapshots to git
+    let commitSha = "";
+    for (const snapshot of snapshots) {
+        const json = JSON.stringify(snapshot, sortedJsonReplacer, 2);
+        commitSha = await writeSnapshot(snapshot.environment, snapshotStorageKey(snapshot.lexicon, snapshot.stack), json, opts);
+    }
+    // Push to remote
+    if (snapshots.length > 0) {
+        await pushLifecycle(opts);
+    }
+    return {
+        snapshots,
+        commit: commitSha,
+        warnings,
+        errors,
+    };
+}