@intentius/chant 0.124.12 → 0.124.14

package/dist/lifecycle/live-diff.js

@@ -0,0 +1,274 @@
+const TRACKED_FIELDS = [
+    "status",
+    "physicalId",
+    "lastUpdated",
+];
+function compareMetadata(oldMeta, newMeta) {
+    const changes = [];
+    for (const field of TRACKED_FIELDS) {
+        if (oldMeta[field] !== newMeta[field]) {
+            changes.push({ path: field, oldValue: oldMeta[field], newValue: newMeta[field] });
+        }
+    }
+    const oldAttrs = oldMeta.attributes ?? {};
+    const newAttrs = newMeta.attributes ?? {};
+    const allAttrKeys = new Set([...Object.keys(oldAttrs), ...Object.keys(newAttrs)]);
+    for (const key of allAttrKeys) {
+        const oldValue = oldAttrs[key];
+        const newValue = newAttrs[key];
+        if (!shallowEqual(oldValue, newValue)) {
+            changes.push({ path: `attributes.${key}`, oldValue, newValue });
+        }
+    }
+    return changes;
+}
+/**
+ * Value equality that does not care what order a provider listed the keys in.
+ *
+ * This compared with `JSON.stringify`, which is key-order sensitive. That held
+ * while observed attributes were flat strings, and broke the moment they carried
+ * nested objects (#1279): a provider returning `{AvailabilityZone, Tenancy}` on
+ * one read and `{Tenancy, AvailabilityZone}` on the next made an unchanged
+ * instance drift on every single run. Order is not a fact about the resource,
+ * and reporting it as drift is exactly the noise this module exists to remove.
+ *
+ * Arrays stay order-sensitive — for a list, order is part of the value.
+ */
+function shallowEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a == null || b == null)
+        return false;
+    if (typeof a !== "object" || typeof b !== "object")
+        return false;
+    return canonical(a) === canonical(b);
+}
+/** JSON with object keys sorted at every depth, so equal values stringify equally. */
+function canonical(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    const entries = Object.entries(value).sort(([x], [y]) => (x < y ? -1 : x > y ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+}
+/**
+ * Diff two **observed** snapshots (#822) — `prev` vs `next`, each a resources map
+ * read from the orphan branch. A two-way diff (no "declared" axis), so it answers
+ * "what changed in the cloud between two points" independent of source. Pure and
+ * deterministic (results sorted). Feeds the deployment-lanes frame-pair diff.
+ */
+export function diffSnapshots(prev, next) {
+    const added = [];
+    const removed = [];
+    const changed = [];
+    const unchanged = [];
+    for (const name of [...new Set([...Object.keys(prev), ...Object.keys(next)])].sort()) {
+        const a = prev[name];
+        const b = next[name];
+        if (!a && b)
+            added.push(name);
+        else if (a && !b)
+            removed.push(name);
+        else if (a && b) {
+            const changes = compareMetadata(a, b);
+            if (changes.length > 0)
+                changed.push({ name, type: b.type ?? a.type, changes });
+            else
+                unchanged.push(name);
+        }
+    }
+    return { added, removed, changed, unchanged };
+}
+export function diffLive(input) {
+    const { declared, observedNow, observedThen } = input;
+    const observedThenMap = observedThen ?? {};
+    const observedNowNames = new Set(Object.keys(observedNow));
+    const observedThenNames = new Set(Object.keys(observedThenMap));
+    // A resource the lexicon returned is observed, whatever it also said about
+    // it — present beats not-observed.
+    const unobservedMap = input.unobserved ?? {};
+    const unobservedNames = new Set(Object.keys(unobservedMap).filter((n) => !observedNowNames.has(n)));
+    const missing = [];
+    const orphan = [];
+    const runtimeChildren = [];
+    const disappeared = [];
+    const newlyObserved = [];
+    const driftedSinceSnapshot = [];
+    const unchanged = [];
+    const unobserved = [];
+    for (const name of unobservedNames) {
+        const entry = unobservedMap[name];
+        const queriedAddress = entry.queried ?? input.queried?.[name];
+        unobserved.push({
+            name,
+            ...(entry.type ? { type: entry.type } : {}),
+            reason: entry.reason,
+            ...(entry.detail ? { detail: entry.detail } : {}),
+            ...(queriedAddress ? { queried: queriedAddress } : {}),
+        });
+    }
+    // Declared, looked at, and the provider said it isn't there → missing.
+    // Declared but never looked at is `unobserved`, not missing — the whole point
+    // of #1089: "we didn't check" must not read as "it isn't there".
+    for (const name of declared) {
+        if (!observedNowNames.has(name) && !unobservedNames.has(name)) {
+            missing.push(name);
+        }
+    }
+    // In cloud right now but not declared → orphan, unless its owner-reference
+    // chain reaches a declared entity (#1077), in which case it is expected
+    // runtime rather than drift. An `unknown` chain (unreadable hop, cycle, or
+    // depth bound) is deliberately NOT escalated to runtime — it stays orphan,
+    // same as `unowned`/`foreign` — composing with #1168's tri-state precedent:
+    // an incomplete read never earns the more confident classification.
+    const runtimeChildNames = new Set();
+    const dependencyNames = new Set();
+    for (const name of observedNowNames) {
+        if (declared.has(name))
+            continue;
+        // A referenced dependency (#1273) is observed only because something
+        // declared points at it — an account's default VPC route table, a shared
+        // subnet. Offering it as a delete/adopt candidate is wrong: it is not
+        // yours, and it changes on its own, so counting it as drift is noise.
+        // Same treatment as a runtime child, for the same reason, arrived at from
+        // the other direction — a child is something declared created, a
+        // dependency is something declared relies on.
+        if ((observedNow[name]?.referencedBy?.length ?? 0) > 0) {
+            dependencyNames.add(name);
+            continue;
+        }
+        // Ambient (#1278): observed because it exists, not because anything points
+        // at it. Reported so a caller can ask about it — "which of these are
+        // unused" is the whole point — but never counted as drift, since chant
+        // neither created it nor tracks its changes.
+        if (observedNow[name]?.ambient) {
+            dependencyNames.add(name);
+            continue;
+        }
+        const chain = observedNow[name]?.ownerChain;
+        if (chain?.root === "declared") {
+            runtimeChildNames.add(name);
+            runtimeChildren.push({ name, type: observedNow[name].type, owner: chain.entity });
+        }
+        else {
+            orphan.push(name);
+        }
+    }
+    // In previous snapshot but not observed now → disappeared. An entity nobody
+    // could look at has not disappeared; it is unobserved. A resource the
+    // *previous* snapshot recorded as a runtime child (#1077) rolling to a new
+    // name (a Pod replaced by its controller) is not disappearance either — it
+    // is the same expected churn `runtimeChildren` excludes above, and counting
+    // it here would recreate the drift noise this module exists to remove.
+    for (const name of observedThenNames) {
+        if (observedNowNames.has(name) || unobservedNames.has(name))
+            continue;
+        if (!declared.has(name) && observedThenMap[name]?.ownerChain?.root === "declared")
+            continue;
+        disappeared.push(name);
+    }
+    // Observed now: classify drift relative to previous snapshot. Runtime
+    // children (#1077) are excluded entirely — a controller-owned object's
+    // transient status is not drift chant should surface, and a snapshot that
+    // happened to record the same name (e.g. a StatefulSet's stable pod
+    // identity) must not turn its ordinary churn into `driftedSinceSnapshot`.
+    for (const name of observedNowNames) {
+        // Referenced dependencies (#1273) are excluded for the same reason runtime
+        // children are: they are observed to complete the picture, not to be
+        // governed, and their ordinary churn is somebody else's.
+        if (runtimeChildNames.has(name) || dependencyNames.has(name))
+            continue;
+        const now = observedNow[name];
+        const then = observedThenMap[name];
+        if (!then) {
+            if (declared.has(name)) {
+                newlyObserved.push(name);
+            }
+            // else: orphan, already classified above
+            continue;
+        }
+        const changes = compareMetadata(then, now);
+        if (changes.length === 0) {
+            unchanged.push(name);
+        }
+        else {
+            driftedSinceSnapshot.push({
+                name,
+                type: now.type,
+                changes,
+            });
+        }
+    }
+    return {
+        missing: missing.sort(),
+        orphan: orphan.sort(),
+        runtimeChildren: runtimeChildren.sort((a, b) => a.name.localeCompare(b.name)),
+        disappeared: disappeared.sort(),
+        newlyObserved: newlyObserved.sort(),
+        driftedSinceSnapshot: driftedSinceSnapshot.sort((a, b) => a.name.localeCompare(b.name)),
+        unchanged: unchanged.sort(),
+        unobserved: unobserved.sort((a, b) => a.name.localeCompare(b.name)),
+        ...(input.queried && Object.keys(input.queried).length > 0 ? { queried: input.queried } : {}),
+        ...missingDefinitions(missing, input.definitions),
+    };
+}
+/**
+ * One row of a live diff's MISSING section, as `chant lifecycle diff --live`
+ * prints it. The address the read went to (#1620) is the line between "not
+ * there" and "looked in the wrong place". The definition's fingerprint
+ * (#3652) is what the create would create: `ApplyOp` digests these rows, and
+ * a row naming the entity alone left an approval standing after the
+ * declaration changed.
+ */
+export function missingRow(diff, name) {
+    const queried = diff.queried?.[name];
+    const definition = diff.definitions?.[name];
+    return `  - ${name}${queried ? ` [queried ${queried}]` : ""}${definition ? ` [definition ${definition}]` : ""}`;
+}
+/** `{ definitions }` for the missing entities that have one, or nothing at all. */
+function missingDefinitions(missing, definitions) {
+    if (!definitions)
+        return {};
+    const out = {};
+    for (const name of [...missing].sort()) {
+        const d = definitions[name];
+        if (d !== undefined)
+            out[name] = d;
+    }
+    return Object.keys(out).length > 0 ? { definitions: out } : {};
+}
+export function diffLiveArtifacts(input) {
+    const observedThenMap = input.observedThen ?? {};
+    const nowNames = new Set(Object.keys(input.observedNow));
+    const thenNames = new Set(Object.keys(observedThenMap));
+    const added = [];
+    const removed = [];
+    const changed = [];
+    const unchanged = [];
+    for (const name of nowNames) {
+        if (!thenNames.has(name)) {
+            added.push(name);
+            continue;
+        }
+        const now = input.observedNow[name];
+        const then = observedThenMap[name];
+        const diffs = compareMetadata(then, now);
+        if (diffs.length === 0) {
+            unchanged.push(name);
+        }
+        else {
+            changed.push({ name, type: now.type, changes: diffs });
+        }
+    }
+    for (const name of thenNames) {
+        if (!nowNames.has(name))
+            removed.push(name);
+    }
+    return {
+        added: added.sort(),
+        removed: removed.sort(),
+        changed: changed.sort((a, b) => a.name.localeCompare(b.name)),
+        unchanged: unchanged.sort(),
+    };
+}

package/dist/lifecycle/local-note.js

@@ -0,0 +1,15 @@
+/**
+ * What a ledger write shows when the checkout has no remote (#3677), kept
+ * apart from `./git.ts` so the run renderers can name it without loading git.
+ */
+/**
+ * The line a write shows when this checkout has no remote for the ledger.
+ * Nothing went wrong: the record is in the local branch, and with no remote
+ * the person who will approve or read it is the one at this machine. A
+ * renderer prints it as a note, never as a warning ({@link isLifecycleLocalNote}).
+ */
+export const LIFECYCLE_LOCAL_NOTE = "recorded locally (no remote for chant/lifecycle)";
+/** Whether a push warning is {@link LIFECYCLE_LOCAL_NOTE}: no remote, rather than a push that failed. */
+export function isLifecycleLocalNote(warning) {
+    return warning === LIFECYCLE_LOCAL_NOTE;
+}

package/dist/lifecycle/member-ledger.js

@@ -0,0 +1,122 @@
+/**
+ * Where a project's lifecycle ledger lives on the `chant/lifecycle` branch
+ * (#2538, #2524 D7, ws-036).
+ *
+ * A workspace member writes every lifecycle store under
+ * `_members/<member>/` on the one existing branch: releases, snapshots, runs,
+ * converge records and observation baselines under `<env>/`, gates under
+ * `_gates/`, build records under `_builds/`, release plans under `_plans/`
+ * (ws-055, #2733). Its operator leases move the same way, to
+ * `refs/chant/lease/_members/<member>/<op>`. Push, fetch, lease and
+ * staleness code are untouched: they still see one branch and plain refs.
+ *
+ * Everything else keeps today's flat layout, byte for byte:
+ *
+ * - a project with no `chant.workspace.json` between it and the git root
+ *   (level 0);
+ * - the root member `.`;
+ * - a directory no member owns;
+ * - an example group's match, since a group has no ledger of its own (ws-051).
+ *
+ * A member of kind `workspace` holds a nested declaration. The nested
+ * workspace's ledgers sit inside the outer member's, so its member `api` in
+ * the outer member `platform` writes under `_members/platform/_members/api/`,
+ * and the nested root member `.` writes under `_members/platform/`.
+ *
+ * Level 0 pays one upward `existsSync` walk here and nothing more. The
+ * declaration reader under `../workspace/` is imported only once a
+ * declaration has been found, so a project without one never loads workspace
+ * code (#2525 rule 5, pinned by #2526's goldens).
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { findWorkspaceRoot } from "../project-root.js";
+/** The directory on `chant/lifecycle` that holds every member's ledger. */
+export const MEMBERS_DIR = "_members";
+/**
+ * The first chant that writes member ledgers. A member whose own toolchain
+ * resolves an older chant still writes the flat layout; `chant workspace
+ * check` fails when two flat writers share an environment name (#2524 D7).
+ */
+export const MEMBER_LEDGER_FLOOR = "0.81.0";
+const FLAT = { members: [], prefix: "" };
+/** The branch prefix for a path of member names. */
+export function memberLedgerPrefix(members) {
+    return members.map((m) => `${MEMBERS_DIR}/${m}/`).join("");
+}
+/**
+ * Thrown when a project sits in a workspace whose declaration cannot be read.
+ * Writing the flat layout then could land in another member's ledger, so no
+ * lifecycle store guesses.
+ */
+export class MemberLedgerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MemberLedgerError";
+    }
+}
+const cache = new Map();
+/**
+ * The ledger of the project at `projectDir` (any directory inside it will do;
+ * ownership goes to the deepest member directory holding it). Results are
+ * cached per directory for the life of the process.
+ */
+export function resolveMemberLedger(projectDir) {
+    const dir = resolve(projectDir);
+    let hit = cache.get(dir);
+    if (!hit) {
+        hit = resolveUncached(dir);
+        cache.set(dir, hit);
+        // A failure is not remembered: the next call reads the declaration again.
+        hit.catch(() => cache.delete(dir));
+    }
+    return hit;
+}
+/** Forget cached resolutions, for tests that write a declaration mid-run. */
+export function clearMemberLedgerCache() {
+    cache.clear();
+}
+function treePath(root, dir) {
+    const rel = relative(root, dir);
+    return rel === "" ? "" : rel.split(sep).join("/");
+}
+async function resolveUncached(dir) {
+    const found = findWorkspaceRoot(dir);
+    if (!found)
+        return FLAT;
+    return ledgerIn(found.dir, dir);
+}
+/**
+ * The ledger of `dir` in the workspace whose declaration sits in `root`. When
+ * that workspace is nested, its whole ledger sits inside the ledger of the
+ * outer member holding `root`. The git root ends the walk outwards, as it
+ * ends {@link findWorkspaceRoot}'s.
+ */
+async function ledgerIn(root, dir) {
+    // Only now does workspace code load.
+    const { readDeclaration, resolveGroups, ownerOf, WorkspaceReadError } = await import("../workspace/declaration.js");
+    const { workingTree } = await import("../workspace/tree.js");
+    let own;
+    try {
+        const tree = workingTree(root);
+        const declaration = readDeclaration(tree);
+        const owner = ownerOf(declaration, resolveGroups(declaration, tree), treePath(root, dir));
+        own = owner && "member" in owner && owner.member.dir !== "." ? [owner.member.name] : [];
+    }
+    catch (err) {
+        if (!(err instanceof WorkspaceReadError))
+            throw err;
+        throw new MemberLedgerError(`cannot place this project's lifecycle ledger: ${err.describe()}. ` +
+            `A project inside a workspace writes under ${MEMBERS_DIR}/<member>/ on chant/lifecycle, ` +
+            `and chant does not guess the member. Fix the declaration and retry.`);
+    }
+    let outer = FLAT;
+    const parent = dirname(root);
+    if (parent !== root && !existsSync(join(root, ".git"))) {
+        const outerFound = findWorkspaceRoot(parent);
+        if (outerFound)
+            outer = await ledgerIn(outerFound.dir, root);
+    }
+    const members = [...outer.members, ...own];
+    return { members, prefix: memberLedgerPrefix(members) };
+}

package/dist/lifecycle/observation-baseline.js

@@ -0,0 +1,155 @@
+/**
+ * The accepted-observation baseline (#1014) — a committed record of deviations
+ * somebody looked at and accepted, so they stop re-alerting.
+ *
+ * Deep observation reports every property that differs between source and
+ * cloud, including properties nobody ever declared. Some of those are real
+ * findings. Many are permanent facts of the account — a platform team's
+ * mandatory tag, a bucket setting an org policy flips on, a role an operator
+ * attached by hand and everyone agreed to keep. Without somewhere to record
+ * "yes, we know, leave it", a deep diff is a report nobody reads twice.
+ *
+ * The model is cdk-real-drift's `.cdkrd`: a snapshot of accepted *undeclared*
+ * values that the diff subtracts. Accepting is an explicit act with a git
+ * commit behind it, and the acceptance is value-bound — accept
+ * `VersioningConfiguration.Status = Enabled` and a later change to `Suspended`
+ * is drift again, because what was accepted was that value, not that path.
+ *
+ * ## What this is not
+ *
+ * Not state. The baseline never tells a deploy what to do and is never read on
+ * the write path; deleting it costs you noise suppression and nothing else.
+ * Which is also why it is safe for it to be incomplete or stale.
+ *
+ * ## Where it lives
+ *
+ * `<environment>/observation-baseline.json` on the `chant/lifecycle` orphan
+ * branch — the epic's named candidate home, and the same storage the snapshots
+ * (`<env>/<lexicon>.json`), the release ledger (`<env>/releases.jsonl`) and the
+ * build archive (`_builds/<digest>.json`) already use, through the same
+ * `writeBlobToPath`/`readBlobFromPath` plumbing. One env-keyed namespace for
+ * everything chant records *about* an environment rather than *for* it.
+ *
+ * The parse/serialize/update half below is pure and storage-free, so the
+ * decision is one function call deep if a repo-committed file (`.chant/`) turns
+ * out to be the better review surface.
+ */
+import { readBlobFromPath, writeBlobToPath } from "./git.js";
+import { sortedJsonReplacer } from "../utils.js";
+import { EFFECT_RECEIPT_ENTITY_TYPE } from "../effect-receipt.js";
+/** The file name under `<environment>/` on the orphan branch. */
+export const OBSERVATION_BASELINE_FILE = "observation-baseline.json";
+/** An environment with nothing accepted yet. */
+export function emptyBaseline(environment) {
+    return { baseline: "v1", environment, lexicons: {} };
+}
+/** True when `value` is a well-formed {@link ObservationBaseline}. */
+export function isObservationBaseline(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.baseline === "v1" &&
+        typeof value.lexicons === "object" &&
+        value.lexicons !== null);
+}
+/**
+ * Parse a baseline document. Returns `null` for unparseable or unrecognized
+ * content — a corrupt baseline degrades to "nothing is accepted", which is
+ * noisy but never wrong. Silently treating garbage as a baseline would
+ * suppress real drift.
+ */
+export function parseBaseline(content) {
+    if (!content)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+    if (!isObservationBaseline(parsed))
+        return null;
+    return parsed;
+}
+/** Deterministic on-disk form: sorted keys, trailing newline, reviewable diff. */
+export function serializeBaseline(baseline) {
+    return `${JSON.stringify(baseline, sortedJsonReplacer, 2)}\n`;
+}
+/** The accepted deviations for one lexicon, or an empty map. */
+export function baselineForLexicon(baseline, lexicon) {
+    return baseline?.lexicons?.[lexicon] ?? {};
+}
+/** Look up one accepted deviation by entity + path. */
+export function acceptedDeviation(lexiconBaseline, entity, path) {
+    return lexiconBaseline[entity]?.accepted.find((a) => a.path === path);
+}
+/**
+ * Record deviations as accepted, returning a new baseline (the input is not
+ * mutated). An existing acceptance for the same entity+path is replaced — that
+ * is how re-accepting after a deliberate change works, and it keeps the file
+ * from growing a second entry for every value a path has ever held.
+ *
+ * REFUSES a deviation on an effect receipt (#1833, epic #1703), throwing
+ * before anything is recorded: a receipt is the declared witness that its
+ * effect ran, and the `effect()` step is its only writer — baselining a
+ * receipt's live value would accept "the effect never fired" as the new
+ * normal and silently defuse the effect. The whole acceptance aborts, not
+ * just the receipt's row, so a partial baseline never lands.
+ */
+export function acceptDeviations(baseline, lexicon, deviations, opts) {
+    if (deviations.length === 0)
+        return baseline;
+    for (const dev of deviations) {
+        if (dev.type === EFFECT_RECEIPT_ENTITY_TYPE || opts?.receipts?.has(dev.entity)) {
+            throw new Error(`cannot accept drift on effect receipt "${dev.entity}" (path ${dev.path}): ` +
+                `the effect() step is the receipt's only writer — accepting the live value would ` +
+                `silently defuse the effect. Re-run the effect (or change its inputs) instead of ` +
+                `baselining the receipt.`);
+        }
+    }
+    const now = opts?.now ?? new Date().toISOString();
+    const lexicons = { ...baseline.lexicons };
+    const entities = { ...(lexicons[lexicon] ?? {}) };
+    for (const dev of deviations) {
+        const existing = entities[dev.entity];
+        const accepted = (existing?.accepted ?? []).filter((a) => a.path !== dev.path);
+        accepted.push({
+            path: dev.path,
+            value: dev.value,
+            ...(dev.note ? { note: dev.note } : {}),
+            recordedAt: now,
+        });
+        accepted.sort((a, b) => a.path.localeCompare(b.path));
+        entities[dev.entity] = {
+            ...(dev.type ?? existing?.type ? { type: dev.type ?? existing?.type } : {}),
+            accepted,
+        };
+    }
+    lexicons[lexicon] = entities;
+    return { baseline: "v1", environment: baseline.environment, updated: now, lexicons };
+}
+/** Total accepted deviations across every lexicon — for the "N accepted" line. */
+export function countAccepted(baseline) {
+    if (!baseline)
+        return 0;
+    let n = 0;
+    for (const entities of Object.values(baseline.lexicons)) {
+        for (const entity of Object.values(entities))
+            n += entity.accepted.length;
+    }
+    return n;
+}
+// ── Storage (chant/lifecycle orphan branch) ─────────────────────────────────
+/**
+ * Read the accepted baseline for an environment. Returns `null` when the branch,
+ * the environment, or the file does not exist — every one of which means
+ * "nothing accepted yet", the normal state before anyone runs
+ * `--update-baseline`.
+ */
+export async function readObservationBaseline(environment, opts) {
+    return parseBaseline(await readBlobFromPath(environment, OBSERVATION_BASELINE_FILE, opts));
+}
+/** Write the accepted baseline to the orphan branch. Returns the new commit SHA. */
+export async function writeObservationBaseline(baseline, opts) {
+    return writeBlobToPath(baseline.environment, OBSERVATION_BASELINE_FILE, serializeBaseline(baseline), "Accepted observation baseline", opts);
+}