@intentius/chant 0.124.12 → 0.124.14

package/dist/lifecycle/converge-ledger.js

@@ -0,0 +1,161 @@
+/**
+ * Converge ledger (#1484) — the append-only record of what a `ConvergeOp`
+ * tick did, one line per tick, at `<env>/converge.jsonl` on the
+ * `chant/lifecycle` orphan branch. Same storage shape as the release ledger
+ * (./release-ledger.ts): immutable, append-only JSONL, reusing
+ * `writeBlobToPath`/`readBlobFromPath` (./git.ts) directly rather than a new
+ * git-plumbing path — the exact reuse `appendReleaseRecordLine` already
+ * demonstrates for a second filename under the same env directory.
+ *
+ * This is also where flap-damping state lives (issue: "consecutive-fire
+ * counts go in the ledger ... not process memory, so damping survives worker
+ * restarts"): each record's `firedRuleIds` names every rule whose predicate
+ * matched this tick, independent of what action was actually taken (run,
+ * report, or skipped for budget/flap reasons) — {@link consecutiveRuleFires}
+ * walks the ledger backward from the newest record and counts how many in a
+ * row include a given rule id, stopping at the first tick where it didn't
+ * fire (the symptom cleared).
+ */
+import { randomUUID } from "node:crypto";
+import { sortedJsonReplacer } from "../utils.js";
+import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git.js";
+const FILENAME = "converge.jsonl";
+/**
+ * Cap a piece of free text to one sanitized line before it goes into a
+ * record. A record here is one line of JSON, so a multi-line or unbounded
+ * string folded into any field would break the line the ledger is built out
+ * of. Every free-text field a tick writes goes through this: a dispatch
+ * failure's `stderr` (a hosting lexicon's own one-line sanitizer delegates
+ * here) and a component verdict's lexicon-authored `detail`.
+ */
+const MAX_LEDGER_TEXT_LEN = 300;
+export function sanitizeLedgerText(raw, maxLen = MAX_LEDGER_TEXT_LEN) {
+    const firstLine = raw.split(/\r?\n/, 1)[0] ?? "";
+    // Strips literal control bytes; it is not matching on a range boundary.
+    const stripped = firstLine.replace(/[\x00-\x1f\x7f]/g, " ").trim();
+    return stripped.length > maxLen ? `${stripped.slice(0, maxLen)}…` : stripped;
+}
+/**
+ * Read-modify-append retry budget for {@link appendConvergeRecord} (#1485).
+ * `writeBlobToPath`'s ref write is now CAS-guarded (./git.ts) — a conflict
+ * (another writer, e.g. a second operator ticking a different env on the
+ * same orphan branch, updated the branch tip between our read and our
+ * write) throws `RefCASConflictError` instead of silently clobbering. This
+ * many attempts, re-reading the ledger fresh each time, absorbs that race
+ * rather than surfacing it as a tick failure — the whole point of the CAS
+ * guard is correctness, not a new way for a tick to fail.
+ */
+const APPEND_RETRY_ATTEMPTS = 5;
+/**
+ * Project the tick's `ComponentStatusRow[]` down to what the ledger keeps.
+ * Pure; row order is preserved, so a consumer sees components in the same
+ * order the status join produced them.
+ */
+export function componentVerdicts(rows) {
+    return rows.map((row) => ({
+        component: row.component,
+        reconciliation: row.reconciliation,
+        detail: sanitizeLedgerText(row.detail ?? ""),
+        ...(row.live !== undefined ? { live: row.live } : {}),
+        ...(row.unobserved
+            ? {
+                unobserved: {
+                    reason: row.unobserved.reason,
+                    ...(row.unobserved.detail !== undefined ? { detail: sanitizeLedgerText(row.unobserved.detail) } : {}),
+                },
+            }
+            : {}),
+    }));
+}
+/**
+ * Append one immutable tick record. Does not push to the remote — call
+ * `pushLifecycle` (./git.ts) afterward, same two-step shape every other
+ * ledger write here uses.
+ *
+ * Mints `record.id` (#2027) when the input doesn't carry one, so every tick
+ * written from here on is referenceable. Unlike `timestamp`, which stays
+ * caller-supplied because library code never calls `Date.now()` internally,
+ * an id has nothing for a caller to decide — the mint lives here so no
+ * writer can forget it. An explicit `input.id` still wins, which is what a
+ * test asserting an exact record uses.
+ *
+ * Retries the whole read-modify-write cycle (#1485) on `RefCASConflictError`
+ * — `writeBlobToPath`'s ref write is CAS-guarded, so a concurrent writer to
+ * a *different* env's file on the same orphan branch (two operators ticking
+ * two environments at once is the ordinary case, not an edge case) can lose
+ * the race and needs to re-read the branch tip and retry, not fail the
+ * tick. Each retry re-reads `existing` fresh, so it always appends onto
+ * whatever the other writer just committed rather than reintroducing a stale
+ * read. Exhausting the budget re-throws the conflict — a real, sustained
+ * pile-up of writers is a signal worth surfacing, not silently swallowing.
+ *
+ * The baseline read must be `readPathSha` + `readBlobBySha` rather than
+ * `readBlobFromPath`, so the exact sha `existing` came from can be passed as
+ * `expectPriorPathSha`. See `writeBlobToPath` (./git.ts) for the race that
+ * closes.
+ */
+export async function appendConvergeRecord(input, opts) {
+    const record = { version: 1, ...input, id: input.id ?? randomUUID() };
+    const json = JSON.stringify(record, sortedJsonReplacer);
+    let lastErr;
+    for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS; attempt++) {
+        try {
+            const priorSha = await readPathSha(record.env, FILENAME, opts);
+            const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+            const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${json}\n`;
+            const commit = await writeBlobToPath(record.env, FILENAME, content, "Converge tick record", {
+                ...opts,
+                expectPriorPathSha: priorSha,
+            });
+            return { commit, record };
+        }
+        catch (err) {
+            if (!(err instanceof RefCASConflictError))
+                throw err;
+            lastErr = err;
+        }
+    }
+    throw lastErr;
+}
+/** Read every tick record for `environment`, oldest first. Malformed lines are skipped, not thrown on — a corrupted or hand-edited ledger degrades gracefully, the same stance `readReleaseLedger` takes. */
+export async function readConvergeLedger(environment, opts) {
+    const content = await readBlobFromPath(environment, FILENAME, opts);
+    if (!content)
+        return { records: [], malformed: 0 };
+    const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
+    const records = [];
+    let malformed = 0;
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed.version !== 1 ||
+                typeof parsed.op !== "string" ||
+                typeof parsed.env !== "string" ||
+                typeof parsed.timestamp !== "string" ||
+                !Array.isArray(parsed.firedRuleIds)) {
+                malformed++;
+                continue;
+            }
+            records.push(parsed);
+        }
+        catch {
+            malformed++;
+        }
+    }
+    return { records, malformed };
+}
+/**
+ * How many consecutive most-recent ticks (newest first) fired `ruleId`,
+ * stopping at the first tick where it did not — the count a rule's
+ * `flapThreshold` is compared against. `0` when the newest tick didn't fire
+ * it (including an empty ledger).
+ */
+export function consecutiveRuleFires(records, ruleId) {
+    let count = 0;
+    for (let i = records.length - 1; i >= 0; i--) {
+        if (!records[i].firedRuleIds.includes(ruleId))
+            break;
+        count++;
+    }
+    return count;
+}

package/dist/lifecycle/deep-diff.js

@@ -0,0 +1,233 @@
+/**
+ * Property-level live drift (#1014) — declared vs live vs accepted baseline.
+ *
+ * The thin diff (./live-diff.ts) compares whole entities on status, physical id
+ * and a few outputs. This compares their property trees, path by path, which is
+ * where a console edit actually shows up. Pure function; the reading happens in
+ * ./deep-observe.ts and the CLI.
+ *
+ * Three axes, and all three matter:
+ *
+ *   - **declared** — the property tree chant synthesized, normalized with the
+ *     lexicon's own hooks so it is in the same shape as the live tree.
+ *   - **live** — what the provider returned, normalized with the same hooks.
+ *   - **baseline** — the value somebody accepted (./observation-baseline.ts). A
+ *     deviation whose live value matches the accepted value is not drift; one
+ *     that has moved away from the accepted value is drift again, and the
+ *     report shows all three so the reader can see what changed and from what.
+ *
+ * A path is skipped entirely when the declared value is
+ * {@link UNRESOLVED} — an unevaluated intrinsic (`Fn::Sub`, `Ref`) has no
+ * source-side value to compare, and reporting one as drift would light up every
+ * interpolated property forever.
+ *
+ * ## The claim decides what counts as drift (#2160)
+ *
+ * The declared tree is not only one side of a comparison, it is a statement of
+ * which fields chant ever set — the claimed-field set (../claimed-fields.ts).
+ * A live value on a path outside it is somebody else's field: an autoscaler's
+ * replica count, a controller's annotation, a value a person typed into a
+ * console. It is reported in {@link DeepDiffResult.unclaimed}, with the
+ * manager's name where the substrate records one, and it is not drift. Only a
+ * claimed path that moved is, and drift is the only thing that may become an
+ * update.
+ */
+import { UNRESOLVED, deepValueEqual, flattenDeepProperties, } from "../deep-observation.js";
+import { claimedFieldsFromPaths, heldBy, isClaimed } from "../claimed-fields.js";
+import { isNormalizedHeldElsewhere } from "../held-elsewhere.js";
+import { originOfPath } from "../provenance.js";
+import { acceptedDeviation } from "./observation-baseline.js";
+/**
+ * Compare declared and live property trees path by path, subtracting accepted
+ * deviations. Deterministic: every list is sorted.
+ */
+export function diffDeep(input) {
+    const baseline = input.baseline ?? {};
+    const drifted = [];
+    const accepted = [];
+    const unclaimed = [];
+    const held = [];
+    const unchanged = [];
+    const unobserved = [];
+    const undeclaredEntities = [];
+    const liveNames = new Set(Object.keys(input.live.resources));
+    for (const [name, entry] of Object.entries(input.live.unobserved)) {
+        // Present beats not-observed, exactly as the thin contract resolves it.
+        if (liveNames.has(name))
+            continue;
+        unobserved.push({
+            name,
+            ...(entry.type ? { type: entry.type } : {}),
+            reason: entry.reason,
+            ...(entry.detail ? { detail: entry.detail } : {}),
+        });
+    }
+    for (const name of liveNames) {
+        if (!(name in input.declared))
+            undeclaredEntities.push(name);
+    }
+    for (const name of Object.keys(input.declared).sort()) {
+        const liveEntity = input.live.resources[name];
+        // Not observed deeply → already recorded above; no properties to compare.
+        // Observed absent by the deep reader is the thin diff's `missing` case and
+        // is not restated here: a resource that does not exist has no property
+        // drift, and reporting every one of its declared properties as `absent`
+        // would bury the one line that matters.
+        if (!liveEntity)
+            continue;
+        const declaredEntity = input.declared[name];
+        const type = liveEntity.type || declaredEntity.type;
+        const declaredFlat = flattenDeepProperties(declaredEntity.properties, {
+            entityType: type,
+            side: "declared",
+            hooks: input.hooks,
+        });
+        const liveFlat = flattenDeepProperties(liveEntity.properties, {
+            entityType: type,
+            side: "live",
+            hooks: input.hooks,
+        });
+        // The claim (#2160): every path this declaration's props flatten to, in the
+        // grammar this loop addresses paths by. Derived here rather than read off
+        // `liveEntity.claimedFields` so `diffDeep` stays a pure function of its two
+        // trees; `lifecycle/deep-observe.ts` computes the identical set from the
+        // identical normalized tree and carries it on the observation for consumers.
+        const claimed = claimedFieldsFromPaths(declaredFlat.keys());
+        const paths = [...new Set([...declaredFlat.keys(), ...liveFlat.keys()])].sort();
+        const reported = [];
+        const suppressed = [];
+        const unclaimedFields = [];
+        const heldHere = [];
+        for (const path of paths) {
+            const hasDeclared = isClaimed(claimed, path);
+            const hasLive = liveFlat.has(path);
+            const declaredValue = declaredFlat.get(path);
+            const liveValue = liveFlat.get(path);
+            // A `heldElsewhere()` marker (#2162): never drift, whatever the live
+            // value is (or isn't) — reported in its own section instead, with its
+            // holder and reason, and never proposed for update. Checked ahead of
+            // the UNRESOLVED/equality shortcuts below: a held path is not "no
+            // source-side value" (UNRESOLVED) and its declared side will never
+            // structurally equal a live value, so without this check every held
+            // property would fall through and report as ordinary `changed` drift.
+            if (hasDeclared && isNormalizedHeldElsewhere(declaredValue)) {
+                heldHere.push({
+                    path,
+                    by: declaredValue.by,
+                    reason: declaredValue.reason,
+                    ...(hasLive ? { live: liveValue } : {}),
+                    // No live value at all is the one thing chant can check in a
+                    // single observation: a claimed hand-over that produced no
+                    // evidence — not even a provider default — is worth a look.
+                    suspicious: !hasLive,
+                    ...(hasLive && liveEntity.fieldOwners?.[path] ? { owner: liveEntity.fieldOwners[path] } : {}),
+                });
+                continue;
+            }
+            // An unevaluated intrinsic has no source-side value to compare against.
+            if (hasDeclared && declaredValue === UNRESOLVED)
+                continue;
+            if (hasDeclared && hasLive && deepValueEqual(declaredValue, liveValue))
+                continue;
+            const acceptedEntry = acceptedDeviation(baseline, name, path);
+            // A live value on a path nobody claimed is somebody else's field, not a
+            // difference chant proposes to close (#2160). Reported, never drift,
+            // never a candidate for an update — and the manager name, where the
+            // substrate records one, is the whole answer an operator wants.
+            if (!hasDeclared) {
+                const { holder, source } = heldBy(liveEntity.fieldOwners, path);
+                unclaimedFields.push({
+                    path,
+                    live: liveValue,
+                    ...(holder ? { heldBy: holder } : {}),
+                    source,
+                    ...(acceptedEntry ? { baseline: acceptedEntry.value } : {}),
+                });
+                continue;
+            }
+            const kind = !hasLive ? "absent" : "changed";
+            // Who owns the path live, where the substrate records it (#1189). Only
+            // meaningful for a path that exists live — an `absent` drift has no live
+            // field for anyone to own.
+            const owner = hasLive ? liveEntity.fieldOwners?.[path] : undefined;
+            // The declared-side counterpart (#1443).
+            const origin = originOfPath(declaredEntity.pathOrigins, path);
+            const drift = {
+                path,
+                kind,
+                declared: declaredValue,
+                ...(hasLive ? { live: liveValue } : {}),
+                ...(owner ? { owner } : {}),
+                ...(origin ? { origin } : {}),
+                ...(hasLive && liveEntity.observedOn ? { seenOn: liveEntity.observedOn } : {}),
+            };
+            if (acceptedEntry) {
+                drift.baseline = acceptedEntry.value;
+                // Value-bound acceptance: the accepted value is not drift, a different
+                // one is drift again.
+                if (hasLive && deepValueEqual(liveValue, acceptedEntry.value)) {
+                    suppressed.push(drift);
+                    continue;
+                }
+            }
+            reported.push(drift);
+        }
+        if (suppressed.length > 0)
+            accepted.push({ name, type, changes: suppressed });
+        if (unclaimedFields.length > 0)
+            unclaimed.push({ name, type, fields: unclaimedFields });
+        if (reported.length > 0)
+            drifted.push({ name, type, changes: reported });
+        // Held fields do not disqualify an entity from `unchanged`: every property
+        // chant declared matches, and the epic's whole point is that a controller's
+        // field stops being a finding chant restates on every tick.
+        else if (suppressed.length === 0)
+            unchanged.push(name);
+        if (heldHere.length > 0)
+            held.push({ name, type, held: heldHere });
+    }
+    return {
+        drifted: drifted.sort((a, b) => a.name.localeCompare(b.name)),
+        accepted: accepted.sort((a, b) => a.name.localeCompare(b.name)),
+        unclaimed: unclaimed.sort((a, b) => a.name.localeCompare(b.name)),
+        held: held.sort((a, b) => a.name.localeCompare(b.name)),
+        unchanged: unchanged.sort(),
+        unobserved: unobserved.sort((a, b) => a.name.localeCompare(b.name)),
+        undeclaredEntities: undeclaredEntities.sort(),
+        ...(input.live.pending && input.live.pending.length > 0
+            ? { pending: [...input.live.pending].sort((a, b) => a.subject.localeCompare(b.subject) || a.change.localeCompare(b.change)) }
+            : {}),
+    };
+}
+/** Total reported property differences across every entity. */
+export function countPropertyDrift(result) {
+    return result.drifted.reduce((n, e) => n + e.changes.length, 0);
+}
+/** The pending changes (#3706): drift, though on no one entity's properties. */
+export function countPending(result) {
+    return result.pending?.length ?? 0;
+}
+/** Total live values on paths no declaration claimed, across every entity (#2160). Never added to the drift count. */
+export function countUnclaimed(result) {
+    return result.unclaimed.reduce((n, e) => n + e.fields.length, 0);
+}
+/** Total held properties (#2162) across every entity. */
+export function countHeld(result) {
+    return result.held.reduce((n, e) => n + e.held.length, 0);
+}
+/**
+ * Every held property whose declaration looks like a hand-over that never
+ * happened — no live value ever showed up for it. Worth a look: either the
+ * named holder never ran, or this is not the field it actually writes.
+ * Sorted by entity name, then path.
+ */
+export function suspiciousHeld(result) {
+    const out = [];
+    for (const entity of result.held) {
+        for (const h of entity.held) {
+            if (h.suspicious)
+                out.push({ name: entity.name, type: entity.type, ...h });
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path));
+}

package/dist/lifecycle/deep-observe.js

@@ -0,0 +1,147 @@
+/**
+ * Deep observation orchestration (#1014) — call one lexicon's
+ * `observeResourcesDeep()`, put the declared trees in the same shape, and diff.
+ *
+ * The sibling of ./observe.ts on the thin path, and it inherits that path's
+ * rules: a reader that throws does not vanish, it reports every declared entity
+ * NOT-OBSERVED with `read-failed` (#1089); a multi-stack read merges with
+ * present > not-observed > absent. A deep read that fails is a hole with a
+ * reason, never a thin-but-clean answer.
+ *
+ * The normalization is applied here, on both sides, with the lexicon's own
+ * hooks. The reader already normalized what it returned — that is the contract
+ * — but only core can normalize the *declared* tree, and only core knows which
+ * paths exist on the other side, which is what
+ * {@link import("../deep-observation.js").DeepNode.counterpart} needs for default
+ * subtraction. Re-running the pass over an already-normalized live tree is
+ * idempotent for every hook that does not consult `counterpart`.
+ */
+import { deepPathSet, normalizeDeepObservation, normalizeDeepProperties, } from "../deep-observation.js";
+import { claimedFieldPaths, claimedFieldsOfTree } from "../claimed-fields.js";
+import { unobservedAll } from "../observation.js";
+import { diffDeep } from "./deep-diff.js";
+/**
+ * Merge several deep observations of the same lexicon (the multi-stack read).
+ * Precedence matches the thin contract: present > not-observed > absent.
+ */
+export function mergeDeepObservations(parts) {
+    const resources = {};
+    const unobserved = {};
+    const pending = [];
+    for (const part of parts) {
+        Object.assign(resources, part.resources);
+        Object.assign(unobserved, part.unobserved);
+        pending.push(...(part.pending ?? []));
+    }
+    for (const name of Object.keys(resources))
+        delete unobserved[name];
+    return { resources, unobserved, ...(pending.length > 0 ? { pending } : {}) };
+}
+/**
+ * Read one lexicon's live property trees. Never throws: a thrown reader becomes
+ * a NOT-OBSERVED verdict for every declared entity, with the error as the
+ * detail, so the caller sees a hole rather than an empty tree that reads as
+ * "no properties drifted".
+ */
+export async function observeDeep(plugin, opts) {
+    const entityNames = Array.from(opts.entities.keys());
+    if (!plugin.observeResourcesDeep) {
+        return { resources: {}, unobserved: {} };
+    }
+    const base = {
+        environment: opts.environment,
+        buildOutput: opts.buildOutput,
+        entityNames,
+        entities: opts.entities,
+        ...(opts.region ? { region: opts.region } : {}),
+        ...(opts.owned !== undefined ? { owned: opts.owned } : {}),
+    };
+    try {
+        if (opts.componentStacks && opts.componentStacks.length > 0) {
+            const parts = [];
+            for (const stack of opts.componentStacks) {
+                parts.push(normalizeDeepObservation(await plugin.observeResourcesDeep({ ...base, stack })));
+            }
+            return mergeDeepObservations(parts);
+        }
+        return normalizeDeepObservation(await plugin.observeResourcesDeep({ ...base, ...(opts.stack ? { stack: opts.stack } : {}) }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            resources: {},
+            unobserved: unobservedAll(entityNames, "read-failed", message, opts.entities),
+        };
+    }
+}
+/**
+ * Normalize both sides into the same shape, then diff.
+ *
+ * Split out from {@link deepDiffForLexicon} so the pure half is testable
+ * without a plugin: given declared entities, a live observation and a baseline,
+ * this is a deterministic function.
+ */
+export function diffDeepObservation(entities, live, hooks, baseline) {
+    const declared = {};
+    const normalizedLive = {};
+    for (const [name, entity] of entities) {
+        const liveEntity = live.resources[name];
+        const declaredRaw = entity.props ?? {};
+        const liveRaw = liveEntity?.properties ?? {};
+        const declaredPaths = deepPathSet(declaredRaw);
+        const livePaths = deepPathSet(liveRaw);
+        const declaredProperties = normalizeDeepProperties(declaredRaw, {
+            entityType: entity.entityType,
+            side: "declared",
+            hooks,
+            counterpartPaths: livePaths,
+        });
+        declared[name] = {
+            type: entity.entityType,
+            properties: declaredProperties,
+            ...(entity.pathOrigins ? { pathOrigins: entity.pathOrigins } : {}),
+        };
+        if (liveEntity) {
+            normalizedLive[name] = {
+                type: liveEntity.type || entity.entityType,
+                ...(liveEntity.physicalId ? { physicalId: liveEntity.physicalId } : {}),
+                // Per-path owners (#1189) ride through unchanged; the diff looks them
+                // up by the flattened path, so a keyed list element (`[#name]`) has
+                // no owner today — its raw index path is what the reader recorded.
+                ...(liveEntity.fieldOwners ? { fieldOwners: liveEntity.fieldOwners } : {}),
+                // Which server's copy was read, when the reader read several (#3664).
+                ...(liveEntity.observedOn ? { observedOn: liveEntity.observedOn } : {}),
+                // The claimed-field set (#2160), computed from the declaration and
+                // carried on the observation so a consumer holding only this envelope
+                // can classify a live value three ways rather than two. Same normalized
+                // tree and same hooks `diffDeep` flattens, so the two never disagree
+                // about a path.
+                claimedFields: claimedFieldPaths(claimedFieldsOfTree(declaredProperties, { entityType: entity.entityType, ...(hooks ? { hooks } : {}) })),
+                properties: normalizeDeepProperties(liveRaw, {
+                    entityType: liveEntity.type || entity.entityType,
+                    side: "live",
+                    hooks,
+                    counterpartPaths: declaredPaths,
+                }),
+            };
+        }
+    }
+    // Live entities nobody declared keep their reader-normalized trees — there is
+    // no declared side to normalize them against, and `diffDeep` reports them as
+    // undeclared entities rather than diffing their properties.
+    for (const [name, liveEntity] of Object.entries(live.resources)) {
+        if (!normalizedLive[name])
+            normalizedLive[name] = liveEntity;
+    }
+    return diffDeep({
+        declared,
+        live: { resources: normalizedLive, unobserved: live.unobserved, ...(live.pending ? { pending: live.pending } : {}) },
+        baseline,
+        hooks,
+    });
+}
+/** Read one lexicon deeply and diff it against source and the accepted baseline. */
+export async function deepDiffForLexicon(plugin, opts) {
+    const live = await observeDeep(plugin, opts);
+    return diffDeepObservation(opts.entities, live, plugin.deepNormalizationHooks, opts.baseline);
+}

package/dist/lifecycle/digest.js

@@ -0,0 +1,143 @@
+import { canonicalJson } from "../effect-receipt.js";
+import { contentDigest } from "../content-digest.js";
+import { isAttrRefLike, LOGICAL_NAME_SYMBOL } from "../utils.js";
+/**
+ * Hash an entity's props deterministically: bare hex SHA-256 over their
+ * `canonicalJson` (chant #2514). Props are first passed through
+ * `JSON.stringify`, which applies `toJSON` and drops what JSON cannot hold
+ * (a function-valued prop, say), so a prop that serialises today still
+ * hashes rather than throwing.
+ */
+export function hashProps(props) {
+    const plain = JSON.parse(JSON.stringify(namedRefs(props)) ?? "null");
+    return contentDigest(canonicalJson(plain)).slice("sha256:".length);
+}
+/**
+ * `props` with each AttrRef that has no logical name of its own written as
+ * the envelope its `toJSON` gives, named by its parent's logical name. The
+ * build names only an entity's top-level AttrRefs; one held in a record,
+ * such as a sql table's `columns`, is never named, and `toJSON` throws on
+ * it (chant#3642). Plain objects and arrays are walked; anything else is
+ * left for `JSON.stringify`, so a named AttrRef hashes as it always has.
+ */
+function namedRefs(value) {
+    if (isAttrRefLike(value)) {
+        if (value.getLogicalName())
+            return value;
+        const parent = value.parent.deref();
+        const entity = parent?.[LOGICAL_NAME_SYMBOL];
+        return { __attrRef: { entity: typeof entity === "string" ? entity : null, attribute: value.attribute } };
+    }
+    if (Array.isArray(value))
+        return value.map(namedRefs);
+    if (value !== null && typeof value === "object") {
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null)
+            return value;
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, namedRefs(v)]));
+    }
+    return value;
+}
+/**
+ * The fingerprint of one entity's declared definition (#3652): its type and
+ * its build props, hashed by {@link hashProps}. A live diff and a lifecycle
+ * plan print it beside each create, so the plan digest a gate binds moves
+ * when what would be created changes, not only when its name does.
+ */
+export function definitionDigest(entityType, props) {
+    return hashProps({ type: entityType, props: props ?? {} });
+}
+/** {@link definitionDigest} for every entity in `entities`, keyed by name. */
+export function declaredDefinitions(entities) {
+    const out = {};
+    for (const [name, entity] of entities)
+        out[name] = definitionDigest(entity.entityType, entity.props);
+    return out;
+}
+/**
+ * Compute a full build digest from a BuildResult.
+ */
+export function computeBuildDigest(buildResult) {
+    const resources = {};
+    for (const [name, entity] of buildResult.entities) {
+        const props = "props" in entity && entity.props != null ? entity.props : {};
+        resources[name] = {
+            type: entity.entityType,
+            lexicon: entity.lexicon,
+            propsHash: hashProps(props),
+        };
+    }
+    // Convert dependency Map<string, Set<string>> to Record<string, string[]>
+    const dependencies = {};
+    for (const [name, deps] of buildResult.dependencies) {
+        dependencies[name] = Array.from(deps);
+    }
+    return {
+        resources,
+        // chant #1442 — what interpreted the declarations, alongside what was
+        // declared. Always present on a freshly computed digest, so "absent"
+        // unambiguously means "recorded before #1442".
+        lexiconVersions: { ...buildResult.lexiconVersions },
+        dependencies,
+        outputs: buildResult.manifest.outputs,
+        deployOrder: buildResult.manifest.deployOrder,
+    };
+}
+/**
+ * Compare two digests and categorize resources.
+ */
+export function diffDigests(current, previous) {
+    const added = [];
+    const removed = [];
+    const changed = [];
+    const unchanged = [];
+    if (!previous) {
+        // No previous digest — everything is added, and there is no version to
+        // have moved away from.
+        added.push(...Object.keys(current.resources));
+        return { added, removed, changed, unchanged, lexiconVersionChanges: [] };
+    }
+    // Check current resources against previous
+    for (const name of Object.keys(current.resources)) {
+        const prev = previous.resources[name];
+        if (!prev) {
+            added.push(name);
+        }
+        else if (current.resources[name].propsHash !== prev.propsHash) {
+            changed.push(name);
+        }
+        else {
+            unchanged.push(name);
+        }
+    }
+    // Check for removed resources
+    for (const name of Object.keys(previous.resources)) {
+        if (!(name in current.resources)) {
+            removed.push(name);
+        }
+    }
+    return { added, removed, changed, unchanged, lexiconVersionChanges: diffLexiconVersions(current, previous) };
+}
+/**
+ * Lexicons whose version moved between two digests (chant #1442).
+ *
+ * A digest recorded before this existed has no `lexiconVersions` at all. That
+ * is reported as no change rather than as every lexicon appearing — comparing
+ * against an older snapshot must not manufacture a difference that the older
+ * build simply never recorded.
+ */
+function diffLexiconVersions(current, previous) {
+    if (!current.lexiconVersions || !previous.lexiconVersions)
+        return [];
+    const changes = [];
+    for (const lexicon of new Set([
+        ...Object.keys(current.lexiconVersions),
+        ...Object.keys(previous.lexiconVersions),
+    ])) {
+        const now = current.lexiconVersions[lexicon];
+        const before = previous.lexiconVersions[lexicon];
+        if (now !== before)
+            changes.push({ lexicon, previous: before, current: now });
+    }
+    return changes.sort((a, b) => a.lexicon.localeCompare(b.lexicon));
+}