@intentius/chant 0.124.13 → 0.124.14

package/dist/lifecycle/plan-ledger.js

@@ -0,0 +1,129 @@
+/**
+ * Release plan store (ws-055, #2733, part of the chud retirement epic
+ * #2715): persists a release plan — the work items and evidence a release
+ * ships — to the `chant/lifecycle` orphan branch, content-addressed by the
+ * plan's own digest.
+ *
+ * **Why this exists.** ws-055 (docs/design/decisions/ws-055-dev-model-
+ * ledgers.md) decided where a development model's plans live: "a release
+ * plan is written content-addressed to `_plans/<digest>.json` on
+ * chant/lifecycle, and the release ledger record already names that
+ * digest." A `ReleaseRecord.digest` (../lifecycle/release-ledger.ts) is
+ * ordinarily an artifact digest; for a release a runner (the studio kit
+ * today, chud before it) plans work-item by work-item, that same field
+ * *is* the plan's own digest — the release ledger needs no new field to
+ * point at it, it already names the plan. Reading a release through the
+ * read contract (../workspace/status.ts) resolves that digest to the plan
+ * exactly the way it already resolves a build archive digest to a
+ * `BuildArchiveManifest` (./build-ledger-store.ts) — this module is that
+ * store's plan-shaped sibling, same plumbing, same directory-per-kind
+ * convention on the one orphan branch.
+ *
+ * **Storage.** Reuses `writeBlobToPath`/`readBlobFromPath` (./git.ts) —
+ * the identical hash-object -> mktree -> commit-tree -> update-ref
+ * pipeline `writeSnapshot`/`persistBuildManifest` already use. Plans live
+ * under a fixed top-level `_plans/` directory, a peer of `_builds/` and the
+ * per-env directories, never nested inside one — a plan is not env-scoped,
+ * it is named by its own content. Per #2524 D7 / #2538, `writeBlobToPath`'s
+ * `ledgerDir` already folds a workspace member's own `_members/<member>/`
+ * prefix in ahead of `_plans/`, so a member's plans live at
+ * `_members/<member>/_plans/<digest>.json` the same way its build records
+ * live at `_members/<member>/_builds/` — this module does nothing itself
+ * to earn that; it falls out of reusing the shared plumbing.
+ *
+ * **Content-addressed, keyed by the plan's own `digest`.** One file per
+ * plan, `_plans/<digest-with-":"->"_">.json` (`:` is not usable in a git
+ * tree entry name the way `readBlobFromPath`'s `<ref>:<path>` spelling
+ * reads it back, the same reason `./build-ledger-store.ts` substitutes it
+ * for `_builds/`). The digest is computed by whoever plans the release —
+ * the release Op, or a runner like the studio kit — not by chant; this
+ * module only trusts and stores it, exactly as `persistBuildManifest`
+ * trusts a manifest's own `manifestDigest`.
+ *
+ * **A plan already written is never rewritten (#2733 acceptance).**
+ * Unlike `persistBuildManifest`, which writes unconditionally every call
+ * (safe only because identical content produces an identical blob and,
+ * usually, an identical tree — but still a new, redundant commit on the
+ * branch each time), `persistReleasePlan` reads the path first and returns
+ * without writing when a plan is already stored under that digest. A plan
+ * is immutable by construction (it is named by a hash of its own content),
+ * so there is never a reason to overwrite one — only ever a reason to skip
+ * the write.
+ */
+import { sortedJsonReplacer } from "../utils.js";
+import { writeBlobToPath, readBlobFromPath, RefCASConflictError } from "./git.js";
+/** Fixed top-level directory on the `chant/lifecycle` orphan branch that holds every persisted release plan — a peer of `_builds/` and the per-env directories, never nested inside one (see module doc for why). */
+const PLANS_DIR = "_plans";
+/** Thrown by `persistReleasePlan` when the plan carries no usable `digest` — a plan can't be content-addressed without one. */
+export class InvalidReleasePlanError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidReleasePlanError";
+    }
+}
+/** Turn a `sha256:...`-style digest into a filesystem/git-tree-safe filename stem. */
+function digestToFilenameStem(digest) {
+    return digest.replace(/:/g, "_");
+}
+function planFilename(digest) {
+    return `${digestToFilenameStem(digest)}.json`;
+}
+/**
+ * Persist a release plan to the orphan branch, keyed by its own `digest`.
+ * Does not push to the remote — call `pushLifecycle` (./git.ts) afterward,
+ * the same two-step (`write` then `push`) shape `appendReleaseRecord`/
+ * `persistBuildManifest` use, so a caller persisting a plan alongside the
+ * release record it names can batch both into one push.
+ *
+ * Never rewrites a plan already stored under `plan.digest` (#2733
+ * acceptance) — reads the path first, and returns `{ commit: null, written:
+ * false }` without writing when it is already there. A `RefCASConflictError`
+ * from a genuine race (another writer persisted the same digest's plan
+ * between this call's read and its write) is treated the same way: the
+ * plan is content-addressed, so whatever is already at that path under this
+ * digest is authoritative, never overwritten.
+ */
+export async function persistReleasePlan(plan, opts) {
+    if (typeof plan.digest !== "string" || plan.digest.length === 0) {
+        throw new InvalidReleasePlanError("release plan is missing its own \"digest\" field — a release plan is content-addressed by its own digest");
+    }
+    const filename = planFilename(plan.digest);
+    const existing = await readBlobFromPath(PLANS_DIR, filename, opts);
+    if (existing !== null)
+        return { commit: null, written: false };
+    const json = JSON.stringify(plan, sortedJsonReplacer);
+    try {
+        const commit = await writeBlobToPath(PLANS_DIR, filename, json, "Release plan", { ...opts, expectPriorPathSha: null });
+        return { commit, written: true };
+    }
+    catch (err) {
+        if (err instanceof RefCASConflictError)
+            return { commit: null, written: false };
+        throw err;
+    }
+}
+/**
+ * Read a persisted release plan back by its own digest — the same digest a
+ * `ReleaseRecord.digest` names. Returns `null` when no plan was ever
+ * persisted under that digest (never throws — most releases carry no plan
+ * at all, and reading one for status is a normal, expected miss), and when
+ * the stored blob fails to parse as JSON.
+ *
+ * `prefix` lets a multi-member reader (../workspace/status.ts) resolve a
+ * specific member's plan directory directly, the same way
+ * `readReleaseLedgerLines` is handed an already-member-prefixed path there
+ * — `cwd` alone can't do it, since one status read walks every member from
+ * one process without changing directory per member.
+ */
+export async function readReleasePlan(digest, opts) {
+    const dir = `${opts?.prefix ?? ""}${PLANS_DIR}`;
+    const content = await readBlobFromPath(dir, planFilename(digest), opts);
+    if (!content)
+        return null;
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lifecycle/receipt-plan.js

@@ -0,0 +1,192 @@
+/**
+ * Receipt planning (#1832, epic #1703) — the plan half of the effect-receipt
+ * contract.
+ *
+ * A receipt is declared, diffed, and observed like any resource, but it is
+ * OBSERVE-ONLY to the generic apply path: the `effect()` step (#1834) is the
+ * sole writer, on success, last (epic decision log, item 3). The plan's job is
+ * therefore not "create the receipt" — it is "say whether the effect will
+ * fire". This module compares each declared receipt's live value against its
+ * resolved expectation and classifies:
+ *
+ * - absent or differing → an `effect` entry ("effect will fire") — including
+ *   the crash-between-effect-and-write case, where a stale or missing receipt
+ *   re-proposes the fire on the next plan. That re-proposal is the whole
+ *   at-least-once guarantee; anything that stamps the receipt on the generic
+ *   path silently converts it into never.
+ * - equal → `noop` — the effect has run for these inputs; the plan is clean.
+ * - unobservable → `unobserved`, loudly. A receipt nobody could read is a
+ *   hole in the plan, never a clean row.
+ * - a reference input that cannot resolve at plan time → an `effect` entry
+ *   with an "unresolved input" note, never a guessed digest. The effect step
+ *   resolves again at run and decides there.
+ *
+ * A receipt name is also stripped out of whatever the generic change-set
+ * classification proposed for it ({@link mergeReceiptEntries}): a receipt is
+ * never a `create`, never an `update`, and never a `delete`/`adopt` prune
+ * candidate — the entries built here are the only rows a receipt gets.
+ *
+ * Pure: no I/O. Live state arrives as {@link ReceiptReading}s the caller
+ * built from its observations; reference inputs resolve through the
+ * caller-supplied resolver ({@link observedValueResolver} builds one over the
+ * plan's merged observed values).
+ */
+import { AttrRef } from "../attrref.js";
+import { EXISTENCE_EXPECTATION, resolveReceiptExpectation, } from "../effect-receipt.js";
+/**
+ * The attribute a materialized receipt's live value is read from. A lexicon
+ * receipt row's observation (#1835) maps the stored value onto
+ * `attributes[RECEIPT_VALUE_ATTRIBUTE]`; `Value` is accepted as a fallback for
+ * observations that keep the provider's own casing (SSM's `Value`).
+ */
+export const RECEIPT_VALUE_ATTRIBUTE = "value";
+/** Read a live receipt's stored value off an observation's attributes. */
+export function readReceiptValue(attributes) {
+    if (!attributes)
+        return undefined;
+    if (RECEIPT_VALUE_ATTRIBUTE in attributes)
+        return attributes[RECEIPT_VALUE_ATTRIBUTE];
+    return attributes["Value"];
+}
+/**
+ * A {@link ReceiptInputResolver} over the plan's merged observed values: an
+ * attr-ref resolves to the referenced entity's observed attribute. Anything
+ * that is not among the observed values throws — which `planReceipts` renders
+ * as an effect-will-fire entry with an "unresolved input" note rather than a
+ * guessed expectation.
+ */
+export function observedValueResolver(resources) {
+    return (ref, path) => {
+        if (ref instanceof AttrRef) {
+            const entity = ref.getLogicalName();
+            if (!entity) {
+                throw new Error(`unresolved input at ${path}: attr-ref carries no logical name`);
+            }
+            const attrs = resources[entity]?.attributes;
+            if (!attrs || !(ref.attribute in attrs)) {
+                throw new Error(`unresolved input at ${path}: ${entity}.${ref.attribute} is not among the observed values`);
+            }
+            return attrs[ref.attribute];
+        }
+        throw new Error(`unresolved input at ${path}: reference cannot resolve at plan time`);
+    };
+}
+/**
+ * Classify every declared receipt into its change-set entry. See the module
+ * doc for the classification; entries come back sorted by name.
+ */
+export function planReceipts(receipts, readings, resolver) {
+    const entries = [];
+    for (const [name, receipt] of receipts) {
+        const reading = readings.get(name);
+        const base = {
+            name,
+            type: reading?.type ?? receipt.entityType,
+            ...(reading?.lexicon ? { lexicon: reading.lexicon } : {}),
+            ...(reading?.physicalId ? { physicalId: reading.physicalId } : {}),
+            effect: receipt.effect,
+            ownership: "unknown",
+        };
+        const evidence = {
+            declared: true,
+            inSnapshot: false,
+            live: reading?.present ?? false,
+            observed: reading?.observed ?? false,
+        };
+        if (!reading) {
+            // No loaded lexicon materializes or observes this receipt — a hole,
+            // said loudly, never a silently clean row (#1089's tri-state).
+            entries.push({
+                ...base,
+                action: "unobserved",
+                evidence,
+                unobservedReason: "unsupported-kind",
+                unobservedDetail: `no loaded lexicon materializes or observes this receipt — ` +
+                    `whether effect "${receipt.effect}" has run is unknown, not clean`,
+            });
+            continue;
+        }
+        if (!reading.observed) {
+            entries.push({
+                ...base,
+                action: "unobserved",
+                evidence,
+                unobservedReason: reading.unobservedReason ?? "read-failed",
+                ...(reading.unobservedDetail ? { unobservedDetail: reading.unobservedDetail } : {}),
+            });
+            continue;
+        }
+        // Resolve the expectation. A reference that cannot resolve at plan time
+        // is never guessed around: the fire is proposed with the note, and the
+        // effect step resolves again at run (epic decision log, item 5).
+        let expectation;
+        let unresolved;
+        try {
+            expectation = resolveReceiptExpectation(receipt, resolver);
+        }
+        catch (err) {
+            unresolved = err instanceof Error ? err.message : String(err);
+        }
+        if (!reading.present) {
+            entries.push({
+                ...base,
+                action: "effect",
+                evidence,
+                effectReason: "receipt-absent",
+                effectDetail: `receipt confirmed absent — no run of "${receipt.effect}" is recorded` +
+                    (unresolved ? ` (${unresolved})` : ""),
+            });
+            continue;
+        }
+        if (expectation === undefined) {
+            entries.push({
+                ...base,
+                action: "effect",
+                evidence,
+                effectReason: "unresolved-input",
+                effectDetail: unresolved,
+            });
+            continue;
+        }
+        if (reading.value === expectation) {
+            entries.push({ ...base, action: "noop", evidence });
+            continue;
+        }
+        entries.push({
+            ...base,
+            action: "effect",
+            evidence,
+            effectReason: "receipt-stale",
+            effectDetail: receipt.flavor === "existence"
+                ? `live value ${fmtValue(reading.value)} is not the existence marker "${EXISTENCE_EXPECTATION}"`
+                : `live value ${fmtValue(reading.value)} differs from expected ${expectation}`,
+        });
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    return entries;
+}
+/**
+ * Replace whatever the generic classification proposed for the receipts with
+ * the receipt entries built by {@link planReceipts}, in place.
+ *
+ * This is the plan-side write-exclusion (#1832): the generic change set,
+ * knowing nothing about receipts, classifies a declared-but-absent receipt as
+ * `create` and an undeclared-but-live one as `delete`/`adopt` — proposals the
+ * generic apply path must never act on for a receipt, and prune candidacy a
+ * receipt must never have. Every entry named like a receipt is dropped and
+ * the receipt's own entries stand in.
+ */
+export function mergeReceiptEntries(cs, receipts, receiptEntries) {
+    if (receipts.size === 0)
+        return cs;
+    cs.entries = cs.entries.filter((e) => !receipts.has(e.name));
+    cs.entries.push(...receiptEntries);
+    cs.entries.sort((a, b) => a.name.localeCompare(b.name));
+    return cs;
+}
+function fmtValue(v) {
+    if (v === undefined)
+        return "<unset>";
+    const s = typeof v === "string" ? v : JSON.stringify(v);
+    return s.length > 72 ? `${s.slice(0, 69)}...` : s;
+}

package/dist/lifecycle/release-ledger.js

@@ -0,0 +1,155 @@
+/**
+ * Release ledger — the recorded half of build & deploy observability (#568,
+ * epic #551 "Build & deploy observability").
+ *
+ * chant already has the *live-truth* half: ownership markers stamp stack/env
+ * identity on live resources, `lifecycle diff --live` / `lifecycle plan`
+ * compare declared vs live, and snapshots on `chant/lifecycle` give a
+ * forensic timeline (see ./snapshot.ts, ./live-diff.ts, ./change-set.ts).
+ * What was missing is the *record* half: "what we recorded deploying",
+ * independent of whether the thing is still running.
+ *
+ * A release record is immutable and append-only: each deploy appends one line
+ * to `<env>/releases.jsonl` on the `chant/lifecycle` orphan branch (see
+ * ./git.ts's `appendReleaseRecord`/`readReleaseLedger`) — never rewritten,
+ * never replaced in place, mirroring how the snapshot branch itself is
+ * treated as observational evidence rather than a mutable state file. The
+ * append-only property is what makes "which build was in staging on
+ * Tuesday" answerable months later even after staging has moved on to a
+ * dozen newer digests.
+ *
+ * The binding key is the artifact **digest** (`sha256:...`), the same
+ * identity `BuildArchive` manifests and `publish-image`/`load-image-on-host`
+ * promote by (see ../components/verbs/build-archive.ts,
+ * ../components/verbs/publish.ts). Because publish promotes by digest never
+ * rebuilding, the same identity threads build → dev → staging → prod, so
+ * "which build is in prod, and is it the one tested in staging" is a
+ * straightforward digest comparison over this ledger — never a guess through
+ * CI logs.
+ */
+import { sortedJsonReplacer } from "../utils.js";
+import { warnOnLegacyDigests, withoutReadFlags } from "./legacy-digest.js";
+import { appendReleaseRecordLine, readReleaseLedgerLines, listLedgerEnvironments as gitListLedgerEnvironments } from "./git.js";
+import { parseReleaseLedger, validateReleaseRecord } from "./release-read.js";
+// The pure readers live apart, so a bundle can import them without git (#3865).
+export { validateReleaseRecord, parseReleaseLedger, releaseLedgerLines, readReleaseRecords, listReleaseEnvironmentsOn } from "./release-read.js";
+/** Thrown by `appendReleaseRecord` when the record is missing a required field — a release record can never be recorded partially, since it is never editable afterward. */
+export class InvalidReleaseRecordError extends Error {
+    constructor(missing) {
+        super(`release record is missing required field(s): ${missing.join(", ")}`);
+        this.missing = missing;
+        this.name = "InvalidReleaseRecordError";
+    }
+}
+/**
+ * Resolve a run id and its origin from the same environment, in one step, so
+ * the two cannot skew (#2045). Resolution order mirrors what
+ * `chant components release` always did — explicit id, then
+ * `GITHUB_RUN_ID`, then `CI_PIPELINE_ID`, then a locally minted
+ * `local-<ms>` — but now each source also names its id space:
+ *
+ *  - the GitHub path records `repo` (`GITHUB_REPOSITORY`) and builds the run
+ *    `url` from `GITHUB_SERVER_URL` — which also makes a Forgejo instance's
+ *    runs resolvable, since Forgejo Actions implements the same env contract;
+ *  - the GitLab path records `repo` (`CI_PROJECT_PATH`) and takes
+ *    `CI_PIPELINE_URL` verbatim;
+ *  - the local mint says `local` in a field instead of only in the id's
+ *    spelling.
+ *
+ * An explicit id still gets an origin when it matches the id the environment
+ * itself is advertising (a CI job passing `--run-id $GITHUB_RUN_ID`);
+ * otherwise the caller's id is recorded without one — guessing an origin the
+ * caller did not state would be exactly the inference this field exists to
+ * remove.
+ */
+export function resolveRunId(explicit, env = process.env) {
+    const githubOrigin = (id) => ({
+        forge: "github",
+        ...(env.GITHUB_REPOSITORY ? { repo: env.GITHUB_REPOSITORY } : {}),
+        ...(env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY
+            ? { url: `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${id}` }
+            : {}),
+    });
+    const gitlabOrigin = () => ({
+        forge: "gitlab",
+        ...(env.CI_PROJECT_PATH ? { repo: env.CI_PROJECT_PATH } : {}),
+        ...(env.CI_PIPELINE_URL ? { url: env.CI_PIPELINE_URL } : {}),
+    });
+    if (explicit) {
+        if (env.GITHUB_RUN_ID && explicit === env.GITHUB_RUN_ID)
+            return { runId: explicit, runOrigin: githubOrigin(explicit) };
+        if (env.CI_PIPELINE_ID && explicit === env.CI_PIPELINE_ID)
+            return { runId: explicit, runOrigin: gitlabOrigin() };
+        return { runId: explicit };
+    }
+    if (env.GITHUB_RUN_ID)
+        return { runId: env.GITHUB_RUN_ID, runOrigin: githubOrigin(env.GITHUB_RUN_ID) };
+    if (env.CI_PIPELINE_ID)
+        return { runId: env.CI_PIPELINE_ID, runOrigin: gitlabOrigin() };
+    return { runId: `local-${Date.now()}`, runOrigin: { forge: "local" } };
+}
+/**
+ * Append one immutable release record to the `<env>` ledger on the
+ * `chant/lifecycle` orphan branch. Throws `InvalidReleaseRecordError` before
+ * any git operation runs if a required field is missing — never partially
+ * records, since nothing about a release record is editable after the fact.
+ *
+ * Does not push to the remote; call `pushLifecycle` (./git.ts) afterward, the
+ * same two-step (`write` then `push`) shape `takeSnapshot` (./snapshot.ts)
+ * uses, so a caller recording several releases in one run can batch the push.
+ */
+export async function appendReleaseRecord(input, opts) {
+    const missing = validateReleaseRecord(input);
+    if (missing.length > 0)
+        throw new InvalidReleaseRecordError(missing);
+    // `flags` are read-side only (#2514); a record passed back in never persists them.
+    const record = { version: 1, ...withoutReadFlags(input) };
+    const json = JSON.stringify(record, sortedJsonReplacer);
+    const commit = await appendReleaseRecordLine(record.env, json, opts);
+    return { commit, record };
+}
+/**
+ * Read every release record for `environment`, oldest first. Malformed lines
+ * (a hand-edited or corrupted ledger) are skipped rather than throwing, since
+ * a status query should degrade gracefully rather than fail outright on one
+ * bad line — but each skip is reported so callers/tests can surface it.
+ */
+export async function readReleaseLedger(environment, opts) {
+    const { records, malformed } = parseReleaseLedger(await readReleaseLedgerLines(environment, opts));
+    // chant #2514 — say once that this ledger holds values in the old form.
+    warnOnLegacyDigests(records.flatMap((r) => [r.digest, r.manifestDigest, r.inputDigest]), "release ledger", opts?.cwd);
+    return { records, malformed };
+}
+/**
+ * List every environment that has release records on the orphan branch. With
+ * `member` or `ledgerPrefix` (#3865) it lists that workspace member's, from
+ * wherever `cwd` is; without either, the member `cwd` resolves to.
+ */
+export async function listReleaseEnvironments(opts) {
+    return gitListLedgerEnvironments(opts);
+}
+/**
+ * The latest release record per component in `records` — "what we recorded
+ * deploying" reduces to one row per component by taking the most recent
+ * `timestamp` (ties broken by ledger order, i.e. later append wins), since
+ * a component may have many historical records in one environment's ledger.
+ */
+export function latestPerComponent(records) {
+    const latest = new Map();
+    for (const record of records) {
+        const current = latest.get(record.component);
+        if (!current || record.timestamp >= current.timestamp) {
+            latest.set(record.component, record);
+        }
+    }
+    return latest;
+}
+/**
+ * Find every release record across `records` that references `digest` — the
+ * cross-environment query "is the build in prod the one tested in staging"
+ * reduces to: read both envs' ledgers, then check whether the same digest
+ * appears in each. Sorted oldest first, matching ledger order.
+ */
+export function recordsForDigest(records, digest) {
+    return records.filter((r) => r.digest === digest);
+}

package/dist/lifecycle/release-read.js

@@ -0,0 +1,64 @@
+/**
+ * Reading release records without git (#3865). The parsing and the
+ * environment listing of `release-ledger.ts`, over a {@link LedgerReadPort}
+ * instead of a checkout, so a product bundles them in one file
+ * (`release-read-bundle.test.ts` holds the import graph). Pass
+ * `gitLedgerReadPort({ member })` from `./git.ts` to read a workspace member's
+ * ledger from a checkout, or a port of your own.
+ *
+ * `release-ledger.ts` reads through these too; its `readReleaseLedger` and
+ * `listReleaseEnvironments` also take `member` or `ledgerPrefix`.
+ */
+import { flagLegacyDigest } from "./legacy-digest.js";
+/** Required, non-empty-string fields every `ReleaseRecord` must carry. */
+const REQUIRED_STRING_FIELDS = ["component", "env", "digest", "gitSha", "runId", "timestamp", "actor"];
+/** The required fields a release record lacks as non-empty strings. */
+export function validateReleaseRecord(record) {
+    const missing = [];
+    for (const field of REQUIRED_STRING_FIELDS) {
+        const value = record[field];
+        if (typeof value !== "string" || value.length === 0)
+            missing.push(field);
+    }
+    return missing;
+}
+/** The lines of a `releases.jsonl` file: trimmed, blanks dropped. */
+export function releaseLedgerLines(text) {
+    return text ? text.split("\n").map((line) => line.trim()).filter(Boolean) : [];
+}
+/**
+ * Parse release ledger lines, oldest first. A malformed line is counted and
+ * skipped; a digest recorded by the old 32-bit hash reads back flagged
+ * (#2514), never re-keyed.
+ */
+export function parseReleaseLedger(lines) {
+    const records = [];
+    let malformed = 0;
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed === null || typeof parsed !== "object" || validateReleaseRecord(parsed).length > 0) {
+                malformed++;
+                continue;
+            }
+            records.push(flagLegacyDigest(parsed, [parsed.digest, parsed.manifestDigest, parsed.inputDigest]));
+        }
+        catch {
+            malformed++;
+        }
+    }
+    return { records, malformed };
+}
+/** Every release record of `environment` the port holds, oldest first. */
+export async function readReleaseRecords(port, environment) {
+    return parseReleaseLedger(releaseLedgerLines(await port.read(environment, "releases.jsonl")));
+}
+/** The environments with a `releases.jsonl`, sorted: the port's root directories that hold one. */
+export async function listReleaseEnvironmentsOn(port) {
+    const envs = [];
+    for (const name of await port.trees()) {
+        if (await port.read(name, "releases.jsonl"))
+            envs.push(name);
+    }
+    return envs.sort();
+}