@intentius/chant 0.124.13 → 0.124.15

package/dist/lifecycle/status.js

@@ -0,0 +1,447 @@
+/**
+ * Status surface — reconciles the release ledger against live truth (#568,
+ * epic #551 "Build & deploy observability").
+ *
+ * Two ledgers, joined by one key. What's been built lives in the
+ * content-addressed `BuildArchive` (../components/verbs/build-archive.ts,
+ * ./build-ledger.ts). What we *recorded* deploying lives in the release
+ * ledger (./release-ledger.ts). What's *actually running* is live truth:
+ * ownership markers (../ownership.ts) plus `lifecycle diff --live`
+ * (./live-diff.ts). This module is the join: for each component/env, line up
+ * the latest recorded release against whatever live evidence is available,
+ * and flag the four things that matter —
+ *
+ *  - **unrecorded** — something is live/owned but no release record exists
+ *    for it. Someone (or some pipeline) deployed outside the recorded path.
+ *  - **stale** — a release record exists but nothing live corresponds to it
+ *    anymore (the component disappeared from observation).
+ *  - **drifted** — a release record exists and the component is observed
+ *    live, but a positive live observation contradicts the record (#2513):
+ *    the live identity a lexicon reports (`attributes.digest` /
+ *    `attributes.gitSha`) differs from the recorded release's, the ownership
+ *    marker went from chant's to someone else's, or the live configuration
+ *    changed against a lifecycle snapshot taken at or after the release (the
+ *    `update` verdict `lifecycle plan` gives). Only things chant saw count:
+ *    a resource it could not read, or one that reports no identity, never
+ *    makes a component drifted.
+ *  - **reconciled** — a release record exists and live evidence (via
+ *    ownership) confirms the component is present and owned by chant.
+ *  - **unknown** — live evidence was requested and could not be read (#1089),
+ *    or was not requested at all. A component chant could not observe is never
+ *    reported `stale`: "the read failed" and "it is gone" are different facts.
+ *
+ * This is deliberately a light-touch reconciliation: chant's lexicons report
+ * resource-level status (`ResourceMetadata`), not "the digest currently
+ * running" (most lexicons have no notion of image digest at all — a
+ * CloudFormation stack doesn't expose "the ECS task's image digest" through
+ * `describeResources`). So the live axis here is presence/ownership, not a
+ * digest re-derivation; digest-level truth is what the *release ledger*
+ * itself provides, and cross-environment digest comparison
+ * (`buildIsInBothEnvs`) is the query the epic actually asks for ("which
+ * build is in prod, and is it the one tested in staging").
+ */
+import { latestPerComponent } from "./release-ledger.js";
+import { isLegacyContentDigest } from "./legacy-digest.js";
+import { unobservedReasonText } from "../observation.js";
+/**
+ * The `ResourceMetadata.attributes` keys a lexicon sets to report which build
+ * a live resource is running (#2513), and the release-record field each one is
+ * compared with. Opt-in: a lexicon that sets neither is reconciled on presence,
+ * ownership and snapshot drift alone, exactly as before.
+ *
+ * - `digest` — the artifact digest serving now (`sha256:...`). Matches the
+ *   record's `digest`, or its `inputDigest` when the record has one.
+ * - `gitSha` — the commit the live build came from. Matches the record's
+ *   `gitSha`; an abbreviated sha (7+ characters) matches by prefix.
+ */
+export const LIVE_IDENTITY_ATTRIBUTES = { digest: "digest", gitSha: "gitSha" };
+function identityOf(entity, meta) {
+    const attrs = meta?.attributes;
+    if (!attrs)
+        return undefined;
+    const digest = attrs[LIVE_IDENTITY_ATTRIBUTES.digest];
+    const gitSha = attrs[LIVE_IDENTITY_ATTRIBUTES.gitSha];
+    const d = typeof digest === "string" && digest.length > 0 ? digest : undefined;
+    const g = typeof gitSha === "string" && gitSha.length > 0 ? gitSha : undefined;
+    if (!d && !g)
+        return undefined;
+    return { entity, ...(d ? { digest: d } : {}), ...(g ? { gitSha: g } : {}) };
+}
+/**
+ * An ownership transition between the snapshot and now that contradicts a
+ * chant release. `unknown` on either side answers nothing and is skipped, the
+ * same way the change set never escalates `unknown` (#1089, #1168).
+ */
+function ownershipChange(then, now) {
+    if (!then || !now)
+        return undefined;
+    if (then.ownership === "owned" && now.ownership === "foreign") {
+        return "ownership marker was chant's at the last snapshot and is gone now";
+    }
+    const a = then.marker;
+    const b = now.marker;
+    if (a && b && (a.stack !== b.stack || (a.env !== undefined && b.env !== undefined && a.env !== b.env))) {
+        return `ownership marker changed from ${a.stack}${a.env ? `/${a.env}` : ""} to ${b.stack}${b.env ? `/${b.env}` : ""}`;
+    }
+    return undefined;
+}
+/**
+ * Overlay per-component stack-presence evidence onto change-set evidence.
+ *
+ * The change-set axis (`liveEvidenceFromChangeSet`) is entity-keyed and, for
+ * AWS, single-stack-per-env — it can't see a multi-stack component project where
+ * each component owns its own stack (#57). `supplement` carries the direct
+ * per-component stack observation (from a lexicon's `describeStackStatus`), which
+ * is authoritative for **presence** (`live`) and **ownership**; the change-set's
+ * `action` is kept, since drift is still assessed from the diff. A component in
+ * only one map passes through unchanged.
+ *
+ * The change-set's `rollup` is kept too (behold#100). This merge rebuilds the
+ * evidence object field by field, so anything not named here is dropped — and
+ * `describeStackStatus` reports a stack, never per-resource counts, so the
+ * supplement has no rollup to contribute. Before this, every component on a
+ * lexicon that implements `describeStackStatus` lost the counts #1300 had just
+ * computed. That is AWS and only AWS, which made the rollup absent on exactly
+ * the substrate it was meant to be verified against: behold#98 shipped its
+ * consumer against floci-az/floci-gcp rows, where no stack observer runs and
+ * the field survived.
+ */
+export function mergeLiveEvidence(base, supplement) {
+    const merged = new Map(base ?? []);
+    for (const [component, sup] of supplement) {
+        const b = merged.get(component);
+        merged.set(component, {
+            live: sup.live,
+            // A direct stack observation that succeeded answers the question the
+            // change-set axis could not — so it clears an inherited "not observed".
+            // A supplement that itself could not read keeps the hole.
+            ...(sup.unobserved ? { unobserved: sup.unobserved } : {}),
+            ownership: sup.ownership ?? b?.ownership,
+            action: b?.action,
+            stack: sup.stack ?? b?.stack,
+            // The unit split rides the same direct observation `live` came from —
+            // dropping it here would resurrect the lie the field exists to fix.
+            ...(sup.partial ? { partial: sup.partial } : {}),
+            // Base first: the counts come from the change set, and a stack
+            // observation has none to offer.
+            ...(b?.rollup ?? sup.rollup ? { rollup: b?.rollup ?? sup.rollup } : {}),
+            // Identity and snapshot drift come from the per-resource reads; a stack
+            // observation carries neither, so dropping them here would make
+            // `drifted` unreachable again on every lexicon with a stack observer.
+            ...(b?.identities ? { identities: b.identities } : {}),
+            ...(b?.driftSignals ? { driftSignals: b.driftSignals } : {}),
+        });
+    }
+    return merged;
+}
+/** Resolve the live entity/resource name(s) a component owns: its explicit mapping, or `[component]` when none is given. */
+export function resolveLiveNames(component, mapping) {
+    const mapped = mapping?.get(component);
+    return mapped && mapped.length > 0 ? mapped : [component];
+}
+/** Count a component's entity verdicts without collapsing them (behold#98). */
+function rollUp(entries) {
+    let present = 0;
+    let absent = 0;
+    let unobserved = 0;
+    for (const e of entries) {
+        if (e.unobserved)
+            unobserved += 1;
+        else if (e.live)
+            present += 1;
+        else
+            absent += 1;
+    }
+    return { total: entries.length, present, absent, unobserved };
+}
+/**
+ * Merge live evidence for several entity/resource names owned by one
+ * component into a single verdict. `live` and `ownership` favor the
+ * most-actionable signal (present/owned) over "nothing here"; `action`
+ * favors `update` so that drift on *any* owned entity surfaces as drift for
+ * the component as a whole, matching `reconcileStatus`'s single check for
+ * `action === "update"`.
+ *
+ * The per-entity counts survive as {@link LiveComponentEvidence.rollup}, so a
+ * consumer that needs the shape rather than the verdict is not forced to redo
+ * this join on the far side of a CLI boundary.
+ */
+function mergeEvidence(entries) {
+    if (entries.length === 0)
+        return undefined;
+    if (entries.length === 1)
+        return { ...entries[0], rollup: rollUp(entries) };
+    const live = entries.some((e) => e.live);
+    const ownership = entries.some((e) => e.ownership === "owned")
+        ? "owned"
+        : entries.some((e) => e.ownership === "foreign")
+            ? "foreign"
+            : "unknown";
+    const action = entries.some((e) => e.action === "update")
+        ? "update"
+        : entries.find((e) => e.action !== undefined)?.action;
+    // A component whose entities were partly readable is still partly unknown, so
+    // any unobserved entity keeps the hole — unless something under it was
+    // actually seen live, which already answers "is this deployed".
+    const unobserved = live ? undefined : entries.find((e) => e.unobserved)?.unobserved;
+    const identities = entries.flatMap((e) => e.identities ?? []);
+    const driftSignals = entries.flatMap((e) => e.driftSignals ?? []);
+    return {
+        live,
+        ownership,
+        action,
+        ...(unobserved ? { unobserved } : {}),
+        rollup: rollUp(entries),
+        ...(identities.length ? { identities } : {}),
+        ...(driftSignals.length ? { driftSignals } : {}),
+    };
+}
+/**
+ * Build a `component -> live evidence` map from a `ChangeSet`. Components and
+ * chant entities are different namespaces (a component's `name` need not
+ * equal any single lexicon entity name), so callers that want live
+ * reconciliation for a component whose live name(s) differ from its own name
+ * pass `nameMapping` (typically projected from `Component.liveNames`, see
+ * ../components/component.ts) — e.g. `new Map([["search-svc",
+ * ["search-service-v2"]]])`. Without a mapping (or for a component with no
+ * entry in it), the component's own name is used as its sole live name — the
+ * identity-keyed join that was this function's only behavior before #598,
+ * preserved here as the fallback so existing callers see no change.
+ */
+export function liveEvidenceFromChangeSet(cs, nameMapping, opts) {
+    const evidenceByName = new Map();
+    for (const entry of cs.entries) {
+        const obs = opts?.observations?.get(entry.name);
+        // Identity and marker transitions only from a resource that was actually
+        // read present. An unobserved or absent entity contributes nothing.
+        const identity = entry.evidence.live ? identityOf(entry.name, obs?.now) : undefined;
+        const driftSignals = [];
+        if (obs && entry.action === "update") {
+            driftSignals.push({
+                entity: entry.name,
+                kind: "attributes",
+                ...(obs.thenAt ? { since: obs.thenAt } : {}),
+                ...(entry.deltas?.length ? { detail: entry.deltas.map((d) => d.path).join(", ") } : {}),
+            });
+        }
+        const ownershipDetail = obs && entry.evidence.live ? ownershipChange(obs.then, obs.now) : undefined;
+        if (ownershipDetail) {
+            driftSignals.push({
+                entity: entry.name,
+                kind: "ownership",
+                ...(obs?.thenAt ? { since: obs.thenAt } : {}),
+                detail: ownershipDetail,
+            });
+        }
+        evidenceByName.set(entry.name, {
+            rollup: rollUp([
+                {
+                    live: entry.evidence.live,
+                    ...(entry.action === "unobserved" && entry.unobservedReason
+                        ? { unobserved: { reason: entry.unobservedReason } }
+                        : {}),
+                },
+            ]),
+            live: entry.evidence.live,
+            action: entry.action,
+            ownership: entry.ownership,
+            // Carry the plan's "could not look" verdict through so the status join
+            // reports a hole instead of reading `live: false` as "gone" (#1089).
+            ...(entry.action === "unobserved" && entry.unobservedReason
+                ? {
+                    unobserved: {
+                        reason: entry.unobservedReason,
+                        ...(entry.unobservedDetail ? { detail: entry.unobservedDetail } : {}),
+                    },
+                }
+                : {}),
+            ...(identity ? { identities: [identity] } : {}),
+            ...(driftSignals.length ? { driftSignals } : {}),
+        });
+    }
+    if (!nameMapping)
+        return evidenceByName;
+    // Re-key by component: for each component that has an explicit mapping,
+    // aggregate evidence across every live name it owns. Components with no
+    // mapping entry keep their identity-keyed evidence as-is (already present
+    // in evidenceByName under their own name).
+    const result = new Map(evidenceByName);
+    for (const [component, liveNames] of nameMapping) {
+        if (!liveNames || liveNames.length === 0)
+            continue;
+        const merged = mergeEvidence(liveNames
+            .map((n) => evidenceByName.get(n))
+            .filter((e) => e !== undefined));
+        if (merged) {
+            result.set(component, merged);
+        }
+        else {
+            result.delete(component);
+        }
+    }
+    return result;
+}
+/**
+ * Reconcile the release ledger against live evidence for one environment.
+ * Pure — no I/O. Callers assemble `records` (./release-ledger.ts's
+ * `readReleaseLedger`), `liveEvidence` (from a `ChangeSet` via
+ * `liveEvidenceFromChangeSet`, or `undefined` when `--live` wasn't
+ * requested), `builds` (a `component -> BuildLedgerEntry` lookup keyed by
+ * digest, from ./build-ledger.ts), and `componentBomByDigest` (#614, a
+ * `digest -> ComponentBomSummary` lookup, also from ./build-ledger.ts) ahead
+ * of time.
+ */
+export function reconcileStatus(env, records, opts) {
+    const latest = latestPerComponent(records);
+    const liveEvidence = opts?.liveEvidence;
+    const componentNames = new Set([...latest.keys(), ...(opts?.allComponents ?? [])]);
+    const rows = [];
+    for (const component of [...componentNames].sort()) {
+        const recorded = latest.get(component);
+        const evidence = liveEvidence?.get(component);
+        const build = recorded ? opts?.buildsByDigest?.get(recorded.digest) : undefined;
+        const componentBom = recorded ? opts?.componentBomByDigest?.get(recorded.digest) : undefined;
+        let reconciliation;
+        let detail;
+        let contradiction;
+        if (!liveEvidence) {
+            // No live evidence requested at all (digest-only / offline mode) — the
+            // ledger is the only signal available, so recorded-vs-unrecorded still
+            // makes sense but drift can't be assessed.
+            reconciliation = recorded ? "unknown" : "unrecorded";
+            detail = recorded
+                ? "recorded; live status not queried (pass --live to reconcile)"
+                : "no release record found";
+        }
+        else if (evidence?.unobserved) {
+            // Live evidence was requested and could not be read (#1089). Neither
+            // `stale` (which claims the component is gone) nor `reconciled` is
+            // supportable — the honest verdict is that nothing is known.
+            reconciliation = "unknown";
+            const why = `${unobservedReasonText(evidence.unobserved.reason)}${evidence.unobserved.detail ? `: ${evidence.unobserved.detail}` : ""}`;
+            detail = recorded
+                ? `recorded ${recorded.timestamp} (digest ${recorded.digest}), but live state could not be observed — ${why}`
+                : `no release record, and live state could not be observed — ${why}`;
+        }
+        else if (!recorded && evidence?.live) {
+            reconciliation = "unrecorded";
+            detail = `live${evidence.ownership === "owned" ? " and chant-owned" : ""}, but no release record exists — deployed outside the recorded path`;
+        }
+        else if (!recorded && !evidence?.live) {
+            reconciliation = "unrecorded";
+            // "Nothing observed live" was a lie for a partially-present component
+            // (#1528) — say what was seen and name what was not.
+            detail = evidence?.partial
+                ? `no release record; ${evidence.partial.present} of ${evidence.partial.total} deploy units observed live (missing: ${evidence.partial.missing.join(", ")})`
+                : "no release record and nothing observed live";
+        }
+        else if (recorded && !evidence?.live) {
+            reconciliation = "stale";
+            detail = evidence?.partial
+                ? `recorded ${recorded.timestamp} (digest ${recorded.digest}), but only ${evidence.partial.present} of ${evidence.partial.total} deploy units observed live now (missing: ${evidence.partial.missing.join(", ")})`
+                : `recorded ${recorded.timestamp} (digest ${recorded.digest}), but nothing observed live now`;
+        }
+        else if (recorded && (contradiction = contradictsRecord(recorded, evidence))) {
+            reconciliation = "drifted";
+            detail = `recorded ${recorded.timestamp} (digest ${recorded.digest}), but ${contradiction}`;
+        }
+        else {
+            reconciliation = "reconciled";
+            detail = `recorded ${recorded.timestamp} (digest ${recorded.digest}), live and consistent`;
+        }
+        rows.push({
+            component,
+            env,
+            recorded,
+            build,
+            componentBom,
+            reconciliation,
+            detail,
+            // `live` is only emitted when it is a real answer: requested AND read.
+            // An unread component leaves it absent (= unknown to every consumer)
+            // rather than reporting `false`, which would read as "not deployed".
+            ...(liveEvidence && !evidence?.unobserved ? { live: !!evidence?.live } : {}),
+            ...(evidence?.unobserved ? { unobserved: evidence.unobserved } : {}),
+            ...(evidence?.stack ? { stack: evidence.stack } : {}),
+            ...(evidence?.rollup ? { resources: evidence.rollup } : {}),
+            ...(evidence?.partial ? { partial: evidence.partial } : {}),
+        });
+    }
+    return rows;
+}
+/** `sha256:abc` and `abc` name the same digest; anything else compares exactly. */
+function sameDigest(a, b) {
+    const bare = (d) => d.replace(/^sha256:/, "");
+    return a === b || bare(a) === bare(b);
+}
+/** Full shas compare exactly; an abbreviated one (7+ chars) matches by prefix. */
+function sameGitSha(a, b) {
+    if (a === b)
+        return true;
+    const [short, long] = a.length <= b.length ? [a, b] : [b, a];
+    return short.length >= 7 && long.startsWith(short);
+}
+function notBefore(since, recordedAt) {
+    const s = Date.parse(since);
+    const r = Date.parse(recordedAt);
+    // An unparseable timestamp cannot place the change after the release, so
+    // it is not attributed to drift since it.
+    return !Number.isNaN(s) && !Number.isNaN(r) && s >= r;
+}
+/**
+ * Does live evidence for a present, recorded component contradict its latest
+ * release record (#2513)? Returns why, or `undefined` when nothing seen says
+ * so. Every rule reads a positive observation; a missing identity, an
+ * `unknown` ownership or a resource nobody read is not a contradiction.
+ */
+function contradictsRecord(recorded, evidence) {
+    for (const id of evidence.identities ?? []) {
+        if (id.digest !== undefined) {
+            const matches = sameDigest(id.digest, recorded.digest) ||
+                (recorded.inputDigest !== undefined && sameDigest(id.digest, recorded.inputDigest));
+            if (!matches)
+                return `live ${id.entity} reports digest ${id.digest}`;
+        }
+        if (id.gitSha !== undefined && !sameGitSha(id.gitSha, recorded.gitSha)) {
+            return `live ${id.entity} reports git sha ${id.gitSha}, recorded ${recorded.gitSha}`;
+        }
+    }
+    if (evidence.driftSignals) {
+        // A signal against a snapshot taken before the release may be the release
+        // itself, so only a change seen since the release counts. A signal with no
+        // `since` was produced by a caller that did not say, and counts.
+        const since = evidence.driftSignals.filter((d) => d.since === undefined || notBefore(d.since, recorded.timestamp));
+        const first = since[0];
+        if (first) {
+            const what = first.kind === "ownership" ? first.detail ?? "ownership marker changed" : `live configuration of ${first.entity} changed${first.detail ? ` (${first.detail})` : ""}`;
+            const more = since.length > 1 ? ` (+${since.length - 1} more)` : "";
+            return `${what} since the snapshot of ${first.since ?? "an earlier read"}${more}`;
+        }
+        return undefined;
+    }
+    // Evidence assembled without per-entity observations: the change set's own
+    // `update` verdict is the only drift signal there is.
+    if (evidence.action === "update")
+        return "live configuration has drifted since";
+    return undefined;
+}
+/** Compare the latest recorded digest for `component` between two environments' release records. */
+export function compareAcrossEnvironments(component, envA, envB) {
+    const latestA = latestPerComponent(envA.records).get(component);
+    const latestB = latestPerComponent(envB.records).get(component);
+    const idA = latestA ? latestA.inputDigest ?? latestA.digest : undefined;
+    const idB = latestB ? latestB.inputDigest ?? latestB.digest : undefined;
+    const comparedOnInputs = (latestA?.inputDigest ?? latestB?.inputDigest) !== undefined;
+    return {
+        component,
+        envA: envA.name,
+        envB: envB.name,
+        digestA: latestA?.digest,
+        digestB: latestB?.digest,
+        same: !!idA && !!idB && idA === idB,
+        ...(comparedOnInputs && idA && idB ? { comparedOn: { a: idA, b: idB } } : {}),
+        ...(idA && idB && idA !== idB && isLegacyContentDigest(idA) !== isLegacyContentDigest(idB)
+            ? { mixedDigestForms: true }
+            : {}),
+    };
+}

package/dist/lifecycle/symptoms.js

@@ -0,0 +1,117 @@
+import { summarize } from "./change-set.js";
+import { unobservedReasonText } from "../observation.js";
+/**
+ * Verdict priority, most-cautious first: if anything is `unknown`, the tick
+ * as a whole must be treated as `unknown` — "unknown never remediates" is a
+ * whole-tick property, not a per-component one, since a rule table has no
+ * way to act on "some of the environment" only. `drifted` outranks `stale`/
+ * `unrecorded` because it is the actionable case ApplyOp's re-apply fixes;
+ * `reconciled` is the quiet-environment default.
+ */
+const STATUS_PRIORITY = [
+    "unknown",
+    "drifted",
+    "stale",
+    "unrecorded",
+    "reconciled",
+];
+/** The worst (most-cautious) reconciliation verdict across a set of component rows. `"reconciled"` for an empty set — nothing to converge is a quiet environment. */
+export function worstStatus(rows) {
+    const present = new Set(rows.map((r) => r.reconciliation));
+    for (const candidate of STATUS_PRIORITY) {
+        if (present.has(candidate))
+            return candidate;
+    }
+    return "reconciled";
+}
+/**
+ * Join a `ChangeSet` and `ComponentStatusRow[]` for one tick into a
+ * `ConvergeSymptom`. Pure — no I/O.
+ */
+export function deriveSymptoms(env, cs, statusRows) {
+    const counts = summarize(cs);
+    const unobservedReasons = [
+        ...new Set(cs.entries
+            .filter((e) => e.action === "unobserved" && e.unobservedReason !== undefined)
+            .map((e) => e.unobservedReason)),
+    ].sort((a, b) => unobservedReasonText(a).localeCompare(unobservedReasonText(b)));
+    return {
+        env,
+        status: worstStatus(statusRows),
+        components: statusRows,
+        createCount: counts.create,
+        updateCount: counts.update,
+        deleteCount: counts.delete,
+        adoptCount: counts.adopt,
+        runtimeCount: counts.runtime,
+        effectCount: counts.effect,
+        unobservedCount: counts.unobserved,
+        unobservedReasons,
+        totalCount: cs.entries.length,
+    };
+}
+/** Every field name a `ConvergeSymptom` produces — the runtime whitelist `OPS014` (packages/core/src/lint/rules/op/ops014-converge-rule-refusals.ts) re-validates a serialized rule table's predicates against. Kept in sync with {@link ConvergeSymptom} by hand (deliberately small, changes rarely). */
+export const CONVERGE_SYMPTOM_FIELDS = new Set([
+    "env",
+    "status",
+    "components",
+    "createCount",
+    "updateCount",
+    "deleteCount",
+    "adoptCount",
+    "runtimeCount",
+    "effectCount",
+    "unobservedCount",
+    "unobservedReasons",
+    "totalCount",
+]);
+/**
+ * The environment variable a dispatched Op reads the resource from, when a
+ * ConvergeOp with an observer step fired its rule for one resource (#2778).
+ */
+export const CONVERGE_RESOURCE_ENV = "CHANT_CONVERGE_RESOURCE";
+/** Every field a {@link ResourceSymptom} produces: OPS014's whitelist for a ConvergeOp with an observer step. */
+export const RESOURCE_SYMPTOM_FIELDS = new Set(["env", "resource", "status", "detail"]);
+const RESOURCE_STATUSES = new Set(["in-sync", "drifted", "unknown"]);
+/**
+ * Read an observer step's result as a {@link ResourceObservation}. The
+ * result is the observation itself, or a `shell()` step's result whose
+ * stdout is the observation as JSON. Throws, naming what is wrong, on
+ * anything else: a tick must not converge from a reading it can't parse.
+ */
+export function parseResourceObservation(value) {
+    let candidate = value;
+    if (candidate && typeof candidate === "object" && !("resources" in candidate) && typeof candidate.stdout === "string") {
+        const stdout = candidate.stdout;
+        try {
+            candidate = JSON.parse(stdout);
+        }
+        catch {
+            throw new Error(`the observer step's stdout is not JSON: ${stdout.slice(0, 120)}`);
+        }
+    }
+    const resources = candidate?.resources;
+    if (!Array.isArray(resources)) {
+        throw new Error("the observer step returned no `resources` array: it must return { resources: [{ name, status }] }, or print it as JSON");
+    }
+    const seen = new Set();
+    const out = [];
+    for (const [i, r] of resources.entries()) {
+        const entry = r;
+        if (!entry || typeof entry.name !== "string" || entry.name === "") {
+            throw new Error(`the observer step's resources[${i}] has no name`);
+        }
+        if (typeof entry.status !== "string" || !RESOURCE_STATUSES.has(entry.status)) {
+            throw new Error(`the observer step's resource "${entry.name}" has status ${JSON.stringify(entry.status)}: it must be in-sync, drifted or unknown`);
+        }
+        if (seen.has(entry.name))
+            throw new Error(`the observer step reported resource "${entry.name}" twice`);
+        seen.add(entry.name);
+        out.push({
+            name: entry.name,
+            status: entry.status,
+            ...(typeof entry.detail === "string" && entry.detail !== "" ? { detail: entry.detail } : {}),
+        });
+    }
+    return { resources: out };
+}