@intentius/chant 0.124.12 → 0.124.14

package/dist/lifecycle/identity.js

@@ -0,0 +1,58 @@
+/**
+ * What makes an unqualified resource one resource (#1416).
+ *
+ * Managed resources are stack-qualified (`${stack}::${id}`, #1162) and cannot
+ * collide. Everything else — dependencies (#1273) and ambient resources (#1278)
+ * — is keyed by physical id and merged across stacks, because the account's
+ * default VPC route table is one resource however many stacks route through it.
+ *
+ * That is right for a resource that really is account-level, and wrong for a
+ * regional one. A VPC, subnet or security group in `us-west-1` is a different
+ * resource from one in `us-east-1`, and merging them by id drops all but the
+ * first sighting.
+ *
+ * On AWS the difference is invisible: VPC, subnet and security-group ids are
+ * globally unique, so keying by id and keying by (region, id) give the same
+ * answer. It shows up against an emulator that reuses ids across regions
+ * (lex00/floci#21), where a three-region estate's nine default subnets merged
+ * to three and "how many subnets are empty" came back 2 instead of 8.
+ *
+ * The rule is deliberately not a table of regional kinds. A lexicon stamps a
+ * region on a resource when region is part of that resource's identity — the
+ * AWS lexicon does it in `stampRegion` for ambient resources and its own
+ * property reads — and this reads that stamp back. A genuinely account-level
+ * resource carries no region and keeps merging as it always did, which is why
+ * dependencies (never stamped) are untouched by this.
+ */
+/**
+ * The region a resource records itself as being in, if it records one.
+ *
+ * Read from `attributes.region`, which is where a lexicon stamps it. Absent
+ * means the resource is account-level, or the lexicon has no region to give —
+ * both of which are read the same way, as "region is not part of this id".
+ */
+export function regionOf(meta) {
+    const region = meta.attributes?.region;
+    return typeof region === "string" && region.length > 0 ? region : undefined;
+}
+/**
+ * The key an unqualified resource merges under.
+ *
+ * `${region}::${id}` for a resource that carries a region, matching the shape
+ * stack qualification already uses, and the bare id for one that does not.
+ *
+ * Applied only where results from more than one region are actually merged —
+ * `collectAmbient` across stacks, `replaySnapshots` across recorded stacks.
+ * Recording one region's observation qualifies nothing, so a stored snapshot
+ * keeps the keys it has always had and the first snapshot taken after this
+ * lands does not diff as "every ambient resource replaced".
+ *
+ * Idempotent, so an id that already carries this region survives a second pass
+ * unchanged rather than becoming `us-east-1::us-east-1::sg-1`.
+ */
+export function unqualifiedKey(id, meta) {
+    const region = regionOf(meta);
+    if (!region)
+        return id;
+    return id.startsWith(`${region}::`) ? id : `${region}::${id}`;
+}

package/dist/lifecycle/index.js

@@ -0,0 +1,26 @@
+export * from "./types.js";
+export * from "./git.js";
+export * from "./digest.js";
+export * from "./snapshot.js";
+export * from "./live-diff.js";
+export * from "./deep-diff.js";
+export * from "./deep-observe.js";
+export * from "./observation-baseline.js";
+export * from "./change-set.js";
+export * from "./disruption.js";
+export * from "./unobserved-gate.js";
+export * from "./receipt-plan.js";
+export * from "./affected.js";
+export * from "./release-ledger.js";
+export * from "./build-ledger.js";
+export * from "./build-ledger-store.js";
+export * from "./oras-referrer-lookup.js";
+export * from "./status.js";
+export * from "./teardown.js";
+export * from "./assert-live.js";
+export * from "./symptoms.js";
+export * from "./converge-ledger.js";
+export * from "./run-ledger.js";
+export * from "./scenario.js";
+export * from "./scenario-eval.js";
+export * from "./plan-digest.js";

package/dist/lifecycle/lease.js

@@ -0,0 +1,283 @@
+/**
+ * Operator lease (#1485, epic #1487) — single-writer coordination for a
+ * `ConvergeOp`'s tick loop, entirely over git. No new state store: the lease
+ * lives on a dedicated ref namespace (`refs/chant/lease/<op>`), separate
+ * from the `chant/lifecycle` orphan branch's own commit history, whose
+ * value IS a lease-record blob — no tree, no commit (./git.ts's
+ * `writeBlob`/`readBlobBySha`). Acquiring or renewing a lease is one
+ * `updateRefCAS` call (./git.ts): the caller reads the ref's current SHA,
+ * and the write only lands if the ref still points there. No `flock` file
+ * either — `git update-ref` is already an atomic local mutex (its own
+ * lockfile-then-rename), so a second local process racing the same acquire
+ * loses outright without any second locking mechanism to reason about.
+ *
+ * Cross-machine contention is settled by pushing/fetching this one ref
+ * through the project's remote (best-effort — see `acquireLease`). A
+ * project with no remote is single-machine by construction: the local CAS
+ * above is then the *entire* coordination story, which is exactly what
+ * issue #1485's open question 5 asks be stated loudly — `chant operator`'s
+ * own docs page says so explicitly; nothing here silently upgrades a
+ * remote-less lease to team-visible durability.
+ *
+ * The record's `token` is the fencing token the issue asks for: a fresh
+ * value is minted only when the lease actually changes hands (first
+ * acquire, or a re-acquire after the previous holder's lease expired or was
+ * released) — never on a same-holder renewal, so an in-flight tick's token
+ * stays valid across the operator loop's own heartbeats. `stillHoldsLease`
+ * is what a caller uses, right before trusting a finished tick's own work,
+ * to notice its token has since changed (the lease was stolen mid-tick,
+ * e.g. the process stalled past its TTL) — see `../op/operator.ts`'s tick
+ * loop for how that's handled: never a hard failure, since a converge tick
+ * is idempotent by design (it re-observes and re-derives everything), so a
+ * late, fenced-out write is redundant, not corrupting.
+ */
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+import { readRefSha, updateRefCAS, deleteRefCAS, writeBlob, readBlobBySha, pushRefStatus, fetchRefIntoStatus, RefCASConflictError, StaleLockError } from "./git.js";
+import { resolveMemberLedger } from "./member-ledger.js";
+export const LEASE_REF_PREFIX = "refs/chant/lease/";
+/**
+ * Side namespace `readLease` fetches remote lease state into (#1959 finding
+ * 3), rather than into `refs/chant/lease/<op>` itself. That ref is the CAS
+ * write path's alone (`acquireLease`/`releaseLease`, both via
+ * `updateRefCAS`/`deleteRefCAS`); a read path force-fetching directly into
+ * it would risk clobbering a just-acquired, not-yet-pushed local lease with
+ * the still-stale remote value — the exact race a concurrent `chant operator
+ * status` in the same clone could hit during the acquire→push window. See
+ * `readLease`'s doc for how the two are reconciled without that risk.
+ */
+export const LEASE_REMOTE_TRACKING_PREFIX = "refs/chant/lease-remote/";
+/**
+ * Default lease TTL — long enough that a normal tick (observe, classify,
+ * a budget-bounded number of dispatches) finishes well inside it; short
+ * enough that a crashed operator's environment resumes converging soon
+ * after, without a human intervening. The operator loop renews well before
+ * this elapses (every round it still owns the lease for), so under normal
+ * operation the TTL is never actually reached.
+ */
+export const DEFAULT_LEASE_TTL_MS = 5 * 60000;
+/**
+ * The lease ref for `opName`. `memberPrefix` is the project's ledger prefix
+ * from ./member-ledger.ts (#2538): empty at level 0 and for the root member
+ * `.`, which keeps `refs/chant/lease/<op>`, and `_members/<member>/` for any
+ * other workspace member, which gives `refs/chant/lease/_members/<member>/<op>`.
+ * Two members may then run Ops of the same name without sharing a lease.
+ */
+export function leaseRef(opName, memberPrefix = "") {
+    return `${LEASE_REF_PREFIX}${memberPrefix}${opName}`;
+}
+function leaseRemoteTrackingRef(opName, memberPrefix = "") {
+    return `${LEASE_REMOTE_TRACKING_PREFIX}${memberPrefix}${opName}`;
+}
+/** The lease refs of `opName` for the project at `opts.cwd` (or the process's directory). */
+async function projectLeaseRefs(opName, opts) {
+    const { prefix } = await resolveMemberLedger(opts?.cwd ?? process.cwd());
+    return { ref: leaseRef(opName, prefix), trackingRef: leaseRemoteTrackingRef(opName, prefix) };
+}
+/**
+ * Sort key for "which of two lease records is more current" — a plain
+ * string comparison works because `acquiredAt`/`expiresAt` are always
+ * `Date.prototype.toISOString()` output (fixed-width, UTC), which sorts
+ * lexicographically in time order. Compares `acquiredAt` first (a genuine
+ * handoff to a new holder always mints a strictly later one; see
+ * `acquireLease`), falling back to `expiresAt` to break a tie between two
+ * renewals of the *same* holder/token, which share `acquiredAt` by design.
+ * `undefined` sorts before every real record.
+ */
+function leaseFreshnessKey(record) {
+    return record ? `${record.acquiredAt} ${record.expiresAt}` : "";
+}
+/** A stable-enough identity for "who holds this lease", for logs and `chant operator status` — hostname:pid, plus a short random suffix so two processes started in the same pid-reuse window never read as the same holder. */
+export function currentHolderId() {
+    return `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`;
+}
+function isExpired(record, now) {
+    return new Date(record.expiresAt).getTime() <= now.getTime();
+}
+function parseLease(raw) {
+    try {
+        const v = JSON.parse(raw);
+        if (typeof v.op === "string" &&
+            typeof v.holder === "string" &&
+            typeof v.token === "string" &&
+            typeof v.acquiredAt === "string" &&
+            typeof v.expiresAt === "string") {
+            return v;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readRecordAt(ref, opts) {
+    const sha = await readRefSha(ref, opts);
+    return { sha, record: sha ? parseLease((await readBlobBySha(sha, opts)) ?? "") : undefined };
+}
+/**
+ * Read the live lease for `opName`, fetching the remote ref first (best-
+ * effort) so a lease held by another machine is visible before deciding
+ * whether to acquire.
+ *
+ * The fetch lands in a side tracking ref (`refs/chant/lease-remote/<op>`),
+ * never directly into `refs/chant/lease/<op>` itself (#1959 finding 3) — the
+ * canonical local ref is written *only* by the CAS path
+ * (`acquireLease`/`releaseLease`), so a read (this function is called
+ * before every `acquireLease`, and directly by `chant operator status`) can
+ * never force it back to a stale remote value out from under a concurrent
+ * local acquirer. The returned `record` is whichever of the local/remote
+ * views is more current by `leaseFreshnessKey` (ties keep local): this
+ * still gives full cross-machine visibility — a genuinely newer remote
+ * holder wins — while a just-acquired, not-yet-pushed local lease (freshest
+ * by construction) always survives a same-clone concurrent read. `sha`
+ * — the CAS anchor a subsequent `acquireLease`/`releaseLease` writes
+ * against — is always the local ref's own actual value; only the local
+ * canonical ref is ever a valid basis for a `updateRefCAS`/`deleteRefCAS`
+ * call against it, regardless of what the comparison decided about `record`.
+ *
+ * When the remote answers without the ref, the lease was released there, and
+ * the tracking ref is dropped so a stale copy of it no longer counts (#2732).
+ * A read-only report that must stay off the network reads the refs itself
+ * (`./work-lease.ts`'s `listWorkLeases`).
+ */
+export async function readLease(opName, opts) {
+    const { ref, trackingRef } = await projectLeaseRefs(opName, opts);
+    const fetched = await fetchRefIntoStatus(ref, trackingRef, opts).catch(() => "failed");
+    if (fetched === "missing") {
+        const stale = await readRefSha(trackingRef, opts);
+        if (stale)
+            await deleteRefCAS(trackingRef, stale, opts).catch(() => undefined);
+    }
+    const { sha, record: localRecord } = await readRecordAt(ref, opts);
+    const { sha: remoteSha, record: remoteRecord } = await readRecordAt(trackingRef, opts);
+    const record = leaseFreshnessKey(remoteRecord) > leaseFreshnessKey(localRecord) ? remoteRecord : localRecord;
+    return { sha, record, remoteSha };
+}
+/**
+ * Acquire or renew the lease for `opName` as `holder`. Succeeds when the ref
+ * doesn't exist yet, is expired, or is already held by `holder` (a renewal:
+ * same token, pushed-out expiry). Fails — returns `acquired: false`, without
+ * throwing — when it's live-held by someone else, or when a concurrent CAS
+ * write is lost to a race that happened between this call's read and its
+ * write ({@link RefCASConflictError}); both read identically to a caller
+ * deciding whether to tick this round ("someone else has it right now,
+ * skip").
+ *
+ * Deliberately does NOT swallow a `StaleLockError` (./git.ts) into that same
+ * "someone else has it" outcome (#1959 finding 2): a leftover `.lock` file
+ * from a killed process is not contention, it's wreckage, and treating it as
+ * "held by someone else" would make `chant operator` back off forever
+ * against a lease nobody can ever actually acquire again without manual
+ * intervention. It propagates instead, so the caller (`../op/operator.ts`'s
+ * `runOperatorRound`) can surface it as its own distinct, diagnosable event
+ * rather than a silent, permanent skip. `lockWaitMs` waits a racing writer's
+ * lock out first.
+ *
+ * `mode`, `token` and `requirePush` are the work lease's (#2732,
+ * ./work-lease.ts); the operator uses none of them.
+ */
+export async function acquireLease(opName, holder, opts) {
+    const deadline = Date.now() + (opts?.lockWaitMs ?? 0);
+    for (;;) {
+        try {
+            return await acquireOnce(opName, holder, opts);
+        }
+        catch (err) {
+            if (!(err instanceof StaleLockError) || Date.now() >= deadline)
+                throw err;
+            await new Promise((r) => setTimeout(r, 20 + Math.floor(Math.random() * 60)));
+        }
+    }
+}
+async function acquireOnce(opName, holder, opts) {
+    const ttlMs = opts?.ttlMs ?? DEFAULT_LEASE_TTL_MS;
+    const now = opts?.now?.() ?? new Date();
+    const mode = opts?.mode ?? "acquire";
+    const { sha, record: current, remoteSha } = await readLease(opName, opts);
+    const expired = !current || isExpired(current, now);
+    const ownedByUs = current?.holder === holder;
+    if (mode === "renew") {
+        if (!current || expired || !ownedByUs)
+            return { acquired: false, reason: current && !expired ? "held" : "not-held", ...(current ? { heldBy: current } : {}) };
+        if (opts?.token !== undefined && current.token !== opts.token)
+            return { acquired: false, reason: "token-mismatch", heldBy: current };
+    }
+    else if (current && !expired && (!ownedByUs || mode === "claim")) {
+        return { acquired: false, heldBy: current, reason: "held" };
+    }
+    const renewing = !!current && ownedByUs && !expired;
+    const record = {
+        op: opName,
+        holder,
+        token: renewing ? current.token : randomUUID(),
+        acquiredAt: renewing ? current.acquiredAt : now.toISOString(),
+        expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+    };
+    const { ref, trackingRef } = await projectLeaseRefs(opName, opts);
+    const blobSha = await writeBlob(JSON.stringify(record), opts);
+    try {
+        await updateRefCAS(ref, blobSha, sha, opts);
+    }
+    catch (err) {
+        if (err instanceof RefCASConflictError) {
+            const retry = await readLease(opName, opts);
+            return { acquired: false, heldBy: retry.record, reason: "race" };
+        }
+        // A StaleLockError (or any other non-CAS failure) is NOT "someone else
+        // has it" — propagate it as its own distinct error rather than folding
+        // it into `heldBy`, per this function's doc.
+        throw err;
+    }
+    const pushed = await pushRefStatus(ref, { ...opts, expect: remoteSha }).catch(() => "rejected");
+    if (pushed === "pushed") {
+        // What the remote holds now; the next push expects it.
+        await updateRefCAS(trackingRef, blobSha, remoteSha, opts).catch(() => undefined);
+    }
+    else if (pushed === "rejected" && opts?.requirePush) {
+        // Undo the local write, which the remote refused, and report who has it there.
+        await (sha === null ? deleteRefCAS(ref, blobSha, opts) : updateRefCAS(ref, sha, blobSha, opts)).catch(() => undefined);
+        const retry = await readLease(opName, opts);
+        const heldBy = retry.record && retry.record.token !== record.token ? retry.record : undefined;
+        return { acquired: false, reason: "push-rejected", ...(heldBy ? { heldBy } : {}) };
+    }
+    return { acquired: true, lease: record };
+}
+/**
+ * Release the lease, but only when `holder`/`token` still match the live
+ * value — releasing a lease this caller no longer actually holds would
+ * silently drop someone else's. Best-effort courtesy: a lease nobody
+ * releases is reclaimed anyway once its TTL passes, so a failed release
+ * (returns `false`, never throws) is not itself a correctness problem.
+ *
+ * The deletion is pushed to the remote, expecting the value last fetched
+ * there, so another clone sees the lease free without waiting out its TTL
+ * (#2732).
+ */
+export async function releaseLease(opName, holder, token, opts) {
+    const { sha, record, remoteSha } = await readLease(opName, opts);
+    if (!record || record.holder !== holder || record.token !== token)
+        return false;
+    const { ref, trackingRef } = await projectLeaseRefs(opName, opts);
+    if (sha) {
+        try {
+            await deleteRefCAS(ref, sha, opts);
+        }
+        catch {
+            return false;
+        }
+    }
+    const pushed = await pushRefStatus(ref, { ...opts, expect: remoteSha }).catch(() => "rejected");
+    if (pushed === "pushed" && remoteSha)
+        await deleteRefCAS(trackingRef, remoteSha, opts).catch(() => undefined);
+    return sha !== null || pushed === "pushed";
+}
+/**
+ * Does `holder`/`token` still match the live lease? The fencing check a
+ * tick uses right before trusting its own work as authoritative (see
+ * `../op/operator.ts`). Fetches first, so a lease stolen by another machine
+ * is detected, not just a stale local read.
+ */
+export async function stillHoldsLease(opName, holder, token, opts) {
+    const { record } = await readLease(opName, opts);
+    return record?.holder === holder && record?.token === token;
+}

package/dist/lifecycle/ledger-port.js

@@ -0,0 +1 @@
+export {};

package/dist/lifecycle/legacy-digest.js

@@ -0,0 +1,91 @@
+/**
+ * Digests recorded before real SHA-256 (chant #2514).
+ *
+ * Up to chant 0.80.0, `contentDigest` labelled its output `sha256:` but
+ * computed a 32-bit string hash and repeated its 8 hex digits eight times.
+ * It now computes real SHA-256 (../content-digest.ts), so every value it
+ * produces changed once. Values already recorded in a project's release
+ * ledger or persisted build manifests keep the old form: they are never
+ * re-keyed or rewritten, because a digest is an identity other records point
+ * at.
+ *
+ * Readers accept both forms. A record read back with an old value carries
+ * `flags: ["legacy-digest"]`, computed on read and never written, and chant
+ * warns once per project, per process, that the ledger holds such values.
+ * Both forms stay accepted through {@link LEGACY_DIGEST_ACCEPTED_THROUGH}.
+ * A later release may stop accepting old values, and it will warn a release
+ * ahead, as #2525 requires of any level-0 change.
+ *
+ * An old value is recognisable by its shape alone. A real SHA-256 hex digest
+ * whose 64 characters are one 8-character block repeated eight times has
+ * probability 2^-224, so the check has no false positives worth considering.
+ */
+import { resolve } from "node:path";
+const LEGACY_DIGEST = /^sha256:([0-9a-f]{8})\1{7}$/;
+/** The flag a record read back with an old-form digest carries. */
+export const LEGACY_DIGEST_FLAG = "legacy-digest";
+/**
+ * The last release series in which readers are guaranteed to accept old-form
+ * digests: every 0.8x release. The first release allowed to refuse them is
+ * 0.90.0, and only after a release that warns about it.
+ */
+export const LEGACY_DIGEST_ACCEPTED_THROUGH = "0.89.x";
+/** Whether `value` is a `sha256:` string made by the old 32-bit `contentDigest`. */
+export function isLegacyContentDigest(value) {
+    return typeof value === "string" && LEGACY_DIGEST.test(value);
+}
+/** Whether any of `values` is an old-form digest. */
+export function hasLegacyContentDigest(values) {
+    for (const value of values) {
+        if (isLegacyContentDigest(value))
+            return true;
+    }
+    return false;
+}
+/**
+ * `record` with `flags: ["legacy-digest"]` added when any of `values` (the
+ * record's own digests) is in the old form, and otherwise unchanged. Other
+ * flags a record carries are kept.
+ */
+export function flagLegacyDigest(record, values) {
+    if (!hasLegacyContentDigest(values))
+        return record;
+    const flags = record.flags ?? [];
+    if (flags.includes(LEGACY_DIGEST_FLAG))
+        return record;
+    return { ...record, flags: [...flags, LEGACY_DIGEST_FLAG] };
+}
+/**
+ * `record` without its read-side `flags`, for writers. Flags describe how a
+ * record reads now, so they are never persisted.
+ */
+export function withoutReadFlags(record) {
+    if (!("flags" in record))
+        return record;
+    const { flags: _flags, ...rest } = record;
+    return rest;
+}
+/** Project roots already warned about in this process. */
+const warnedProjects = new Set();
+/** Forget which projects were warned about. For tests. */
+export function resetLegacyDigestWarnings() {
+    warnedProjects.clear();
+}
+/**
+ * Warn once for the project at `cwd` (default: the working directory) when
+ * any of `values` is an old-form digest. `where` names the record that held
+ * it, for the message. Returns whether a warning was printed.
+ */
+export function warnOnLegacyDigests(values, where, cwd) {
+    const project = resolve(cwd ?? process.cwd());
+    if (warnedProjects.has(project))
+        return false;
+    if (!hasLegacyContentDigest(values))
+        return false;
+    warnedProjects.add(project);
+    console.warn(`[chant] warning: this project's ${where} ${where === "release ledger" ? "holds" : "hold"} sha256: values made by chant's old 32-bit content hash, ` +
+        "not real SHA-256. chant now computes real SHA-256, so a digest recorded from now on will not match " +
+        "an old one for the same content. Old entries are not rewritten: they read back flagged legacy-digest, " +
+        `and chant accepts them through ${LEGACY_DIGEST_ACCEPTED_THROUGH}. See https://github.com/INTENTIUS/chant/issues/2514`);
+    return true;
+}