@intentius/chant 0.124.40 → 0.124.41

package/dist/lifecycle/query.js

@@ -0,0 +1,246 @@
+import { parseGateLedger, GATES_DIR } from "./gate-ledger.js";
+import { parseReleaseLedger, releaseLedgerLines } from "./release-read.js";
+import { CUTS_FILE, parseCuts, parseRelease, RELEASES_DIR, verifyReleaseDigest } from "./release-store.js";
+import { opOfRunLedgerFile, parseRunLedger } from "./run-ledger.js";
+/** The version of the table schema below. */
+export const QUERY_SCHEMA_VERSION = 1;
+/**
+ * Each table's columns, in order, with their SQLite type. A column named in
+ * the doc as JSON holds a JSON text, for `json_extract`. Every table starts
+ * with `member`: the workspace member whose ledger the row came from, or NULL
+ * for a project outside a workspace.
+ */
+export const QUERY_TABLES = {
+    /** One row per resource in each environment's newest snapshot. `attributes` is JSON. */
+    resources: [["member", "TEXT"], ["env", "TEXT"], ["stack", "TEXT"], ["lexicon", "TEXT"], ["name", "TEXT"], ["type", "TEXT"], ["physical_id", "TEXT"], ["status", "TEXT"], ["last_updated", "TEXT"], ["ownership", "TEXT"], ["attributes", "TEXT"], ["git_sha", "TEXT"], ["observed_at", "TEXT"]],
+    /** One row per snapshot file: what was observed, when, and how many resources it holds. */
+    snapshots: [["member", "TEXT"], ["env", "TEXT"], ["stack", "TEXT"], ["lexicon", "TEXT"], ["git_sha", "TEXT"], ["observed_at", "TEXT"], ["depth", "TEXT"], ["resources", "INTEGER"], ["unobserved", "INTEGER"]],
+    /** One row per Op run record. `labels` and `outcomes` are JSON. */
+    runs: [["member", "TEXT"], ["id", "TEXT"], ["op", "TEXT"], ["env", "TEXT"], ["started", "TEXT"], ["ended", "TEXT"], ["status", "TEXT"], ["git_sha", "TEXT"], ["forge", "TEXT"], ["run_url", "TEXT"], ["failure_code", "TEXT"], ["failure_reason", "TEXT"], ["failed_phase", "TEXT"], ["gate", "TEXT"], ["steward", "TEXT"], ["labels", "TEXT"], ["outcomes", "TEXT"]],
+    /** One row per gate ledger line: `kind` is `pending` or `resolution`. `signed` is 1 for a sealed approval. */
+    gates: [["member", "TEXT"], ["op", "TEXT"], ["gate", "TEXT"], ["kind", "TEXT"], ["timestamp", "TEXT"], ["resolved_by", "TEXT"], ["relayed_by", "TEXT"], ["approver_kind", "TEXT"], ["plan_digest", "TEXT"], ["environment", "TEXT"], ["release_digest", "TEXT"], ["git_sha", "TEXT"], ["run_id", "TEXT"], ["url", "TEXT"], ["note", "TEXT"], ["expires_at", "TEXT"], ["origin", "TEXT"], ["empty", "INTEGER"], ["signed", "INTEGER"]],
+    /** One row per deploy record in `<env>/releases.jsonl`. `promoted_from`, `restores` and `redeploys` are JSON. */
+    deploys: [["member", "TEXT"], ["env", "TEXT"], ["component", "TEXT"], ["digest", "TEXT"], ["git_sha", "TEXT"], ["run_id", "TEXT"], ["forge", "TEXT"], ["run_url", "TEXT"], ["timestamp", "TEXT"], ["actor", "TEXT"], ["approver", "TEXT"], ["release_digest", "TEXT"], ["digest_kind", "TEXT"], ["promoted_from", "TEXT"], ["restores", "TEXT"], ["redeploys", "TEXT"]],
+    /** One row per release file whose content hashes to its digest. `envs` joins its targets' environments with commas; `artifacts` is JSON. */
+    releases: [["member", "TEXT"], ["release_digest", "TEXT"], ["release_member", "TEXT"], ["git_sha", "TEXT"], ["envs", "TEXT"], ["artifacts", "TEXT"]],
+    /** One row per line of `_releases/cuts.jsonl`. `signed` is 1 for a signed cut. */
+    cuts: [["member", "TEXT"], ["release_digest", "TEXT"], ["label", "TEXT"], ["actor", "TEXT"], ["timestamp", "TEXT"], ["run_id", "TEXT"], ["forge", "TEXT"], ["channel", "TEXT"], ["signed", "INTEGER"], ["composed_base", "TEXT"]],
+};
+/** The table that describes the others: one row per column, with the schema version. */
+export const SCHEMA_TABLE = "chant_schema";
+/** A statement that can't run, or a Node.js with no SQLite. The message is for a person. */
+export class QueryError extends Error {
+}
+const TABLE_NAMES = Object.keys(QUERY_TABLES);
+const empty = (v) => Object.fromEntries(TABLE_NAMES.map((t) => [t, v()]));
+const json = (v) => (v === undefined || v === null ? null : JSON.stringify(v));
+const str = (v) => (typeof v === "string" ? v : null);
+const bit = (v) => (v ? 1 : 0);
+/** Whether a parsed `.json` file under an environment is a snapshot (an observation baseline or another file is not). */
+function isSnapshot(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const s = v;
+    return typeof s.lexicon === "string" && typeof s.environment === "string" && typeof s.commit === "string" && typeof s.timestamp === "string" && !!s.resources && typeof s.resources === "object" && !Array.isArray(s.resources);
+}
+function snapshotRows(member, env, file, s, data) {
+    // The file name folds the stack in as `<stack>__<lexicon>` (git.ts snapshotStorageKey); the record names it too.
+    const key = file.slice(0, -".json".length);
+    const stack = s.stack ?? (key.includes("__") ? key.slice(0, key.lastIndexOf("__")) : null);
+    const at = { git_sha: s.commit, observed_at: s.timestamp };
+    const resources = Object.entries(s.resources);
+    data.snapshots.push({ member, env, stack, lexicon: s.lexicon, ...at, depth: s.depth ?? "identity", resources: resources.length, unobserved: Object.keys(s.unobserved ?? {}).length });
+    for (const [name, r] of resources) {
+        data.resources.push({ member, env, stack, lexicon: s.lexicon, name, type: str(r?.type), physical_id: str(r?.physicalId), status: str(r?.status), last_updated: str(r?.lastUpdated), ownership: str(r?.ownership), attributes: json(r?.attributes), ...at });
+    }
+}
+function gateRow(member, r) {
+    const pending = r.kind === "pending";
+    const res = pending ? undefined : r;
+    const origin = r.origin;
+    return {
+        member,
+        op: r.op,
+        gate: r.gate,
+        kind: pending ? "pending" : "resolution",
+        timestamp: r.timestamp,
+        resolved_by: res?.resolvedBy ?? null,
+        relayed_by: str(res?.relayedBy),
+        approver_kind: str(res?.approver?.kind),
+        plan_digest: str(r.planDigest),
+        environment: str(r.environment),
+        release_digest: str(r.releaseDigest),
+        git_sha: str(r.gitSha),
+        run_id: str(r.runId),
+        url: str(res?.url),
+        note: str(res?.note),
+        expires_at: pending ? str(r.expiresAt) : null,
+        origin: str(origin),
+        empty: bit(res?.empty === true),
+        signed: bit(res?.seal !== undefined),
+    };
+}
+/**
+ * Read every table's rows from the ledgers, in the order given. A ledger
+ * whose branch is absent reads as no rows. A line or file that is not its
+ * kind is counted in `malformed` and left out, as each ledger's own reader
+ * does.
+ */
+export async function loadQueryData(ledgers) {
+    const data = empty(() => []);
+    const malformed = empty(() => 0);
+    for (const { member, port } of ledgers) {
+        const trees = (await port.trees()).sort();
+        for (const env of trees.filter((t) => !t.startsWith("_"))) {
+            for (const file of (await port.list(env)).sort()) {
+                if (file.endsWith(".json")) {
+                    const text = await port.read(env, file);
+                    let parsed;
+                    try {
+                        parsed = text === null ? null : JSON.parse(text);
+                    }
+                    catch {
+                        parsed = null;
+                    }
+                    // Other JSON files live beside the snapshots (the observation baseline); only a snapshot-shaped one is read.
+                    if (isSnapshot(parsed))
+                        snapshotRows(member, env, file, parsed, data);
+                    continue;
+                }
+                if (file === "releases.jsonl") {
+                    const { records, malformed: bad } = parseReleaseLedger(releaseLedgerLines(await port.read(env, file)));
+                    malformed.deploys += bad;
+                    for (const d of records) {
+                        data.deploys.push({ member, env: d.env, component: d.component, digest: d.digest, git_sha: d.gitSha, run_id: d.runId, forge: str(d.runOrigin?.forge), run_url: str(d.runOrigin?.url), timestamp: d.timestamp, actor: d.actor, approver: str(d.approver), release_digest: str(d.releaseDigest), digest_kind: str(d.digestKind), promoted_from: json(d.promotedFrom), restores: json(d.restores), redeploys: json(d.redeploys) });
+                    }
+                    continue;
+                }
+                if (opOfRunLedgerFile(file) !== null) {
+                    const text = await port.read(env, file);
+                    if (text === null)
+                        continue;
+                    const { records, malformed: bad } = parseRunLedger(text);
+                    malformed.runs += bad;
+                    for (const r of records) {
+                        data.runs.push({ member, id: r.id, op: r.op, env: r.env, started: r.started, ended: r.ended, status: r.status, git_sha: str(r.gitSha), forge: str(r.runOrigin?.forge), run_url: str(r.runOrigin?.url), failure_code: str(r.failure?.code), failure_reason: str(r.failure?.reason), failed_phase: str(r.failure?.phase), gate: str(r.gate?.name), steward: str(r.steward), labels: json(r.labels ?? {}), outcomes: json(r.outcomes ?? {}) });
+                    }
+                }
+            }
+        }
+        if (trees.includes(GATES_DIR)) {
+            for (const file of (await port.list(GATES_DIR)).sort()) {
+                if (!file.endsWith(".jsonl"))
+                    continue;
+                const text = await port.read(GATES_DIR, file);
+                if (text === null)
+                    continue;
+                const { resolutions, pending, malformed: bad } = parseGateLedger(text);
+                malformed.gates += bad;
+                // Both kinds share the file; ledger order is time order, so they are merged back by timestamp.
+                const lines = [...pending, ...resolutions].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+                for (const r of lines)
+                    data.gates.push(gateRow(member, r));
+            }
+        }
+        if (trees.includes(RELEASES_DIR)) {
+            for (const file of (await port.list(RELEASES_DIR)).sort()) {
+                if (file === CUTS_FILE) {
+                    const { cuts, malformed: bad } = parseCuts(await port.read(RELEASES_DIR, file));
+                    malformed.cuts += bad;
+                    for (const c of cuts) {
+                        data.cuts.push({ member, release_digest: c.releaseDigest, label: c.label, actor: c.actor, timestamp: c.timestamp, run_id: c.runId, forge: str(c.runOrigin?.forge), channel: str(c.channel), signed: bit(c.signature !== null), composed_base: str(c.composed?.base) });
+                    }
+                    continue;
+                }
+                if (!file.endsWith(".json"))
+                    continue;
+                const text = await port.read(RELEASES_DIR, file);
+                const release = text === null ? null : parseRelease(text);
+                // `readAllReleases` (release-store.ts) counts a file whose content does not hash to its digest as malformed; so does this.
+                if (!release || release.releaseDigest.replace(/:/g, "_") !== file.slice(0, -".json".length) || !verifyReleaseDigest(release)) {
+                    malformed.releases++;
+                    continue;
+                }
+                data.releases.push({ member, release_digest: release.releaseDigest, release_member: release.member, git_sha: release.commit, envs: release.targets.map((t) => t.env).join(","), artifacts: json(release.artifactDigests) });
+            }
+        }
+    }
+    return { data, malformed };
+}
+/** node:sqlite, without the experimental warning some Node.js versions print when it loads. */
+async function sqlite() {
+    const emit = process.emitWarning;
+    process.emitWarning = ((warning, ...rest) => {
+        if (/SQLite/.test(typeof warning === "string" ? warning : warning.message))
+            return;
+        return emit.call(process, warning, ...rest);
+    });
+    try {
+        const name = "node:sqlite";
+        return (await import(name));
+    }
+    catch {
+        throw new QueryError(`chant query runs on the SQLite built into Node.js 22.13 or later; this is Node.js ${process.versions.node}`);
+    }
+    finally {
+        process.emitWarning = emit;
+    }
+}
+/** The first word of a statement, past whitespace and comments. */
+export function firstWord(sql) {
+    const s = sql.replace(/^(\s+|--[^\n]*(\n|$)|\/\*[\s\S]*?\*\/)*/, "");
+    return (/^[A-Za-z]+/.exec(s)?.[0] ?? "").toLowerCase();
+}
+/** Run one read-only statement over the tables. */
+export async function runQuery(sql, load) {
+    if (sql.trim() === "")
+        throw new QueryError('chant query needs a statement: chant query "SELECT * FROM resources"');
+    if (!["select", "with", "values"].includes(firstWord(sql)))
+        throw new QueryError("chant query runs one SELECT (or WITH, or VALUES) statement; it changes nothing");
+    const { DatabaseSync } = await sqlite();
+    const db = new DatabaseSync(":memory:");
+    try {
+        db.exec(`CREATE TABLE ${SCHEMA_TABLE} ("version" INTEGER, "table_name" TEXT, "column_name" TEXT, "type" TEXT, "position" INTEGER)`);
+        const describe = db.prepare(`INSERT INTO ${SCHEMA_TABLE} VALUES (?, ?, ?, ?, ?)`);
+        for (const table of TABLE_NAMES) {
+            const cols = QUERY_TABLES[table];
+            db.exec(`CREATE TABLE ${table} (${cols.map(([c, t]) => `"${c}" ${t}`).join(", ")})`);
+            cols.forEach(([c, t], i) => describe.run(QUERY_SCHEMA_VERSION, table, c, t, i + 1));
+            const insert = db.prepare(`INSERT INTO ${table} VALUES (${cols.map(() => "?").join(", ")})`);
+            db.exec("BEGIN");
+            for (const row of load.data[table])
+                insert.run(...cols.map(([c]) => row[c] ?? null));
+            db.exec("COMMIT");
+        }
+        db.exec("PRAGMA query_only = ON");
+        let stmt;
+        try {
+            stmt = db.prepare(sql);
+        }
+        catch (e) {
+            throw new QueryError(`the query does not run: ${e.message}`);
+        }
+        let rows;
+        try {
+            rows = stmt.all();
+        }
+        catch (e) {
+            throw new QueryError(`the query does not run: ${e.message}`);
+        }
+        const columns = typeof stmt.columns === "function" ? stmt.columns().map((c) => c.name) : Object.keys(rows[0] ?? {});
+        const tables = Object.fromEntries(TABLE_NAMES.map((t) => [t, load.data[t].length]));
+        return { schemaVersion: QUERY_SCHEMA_VERSION, columns, rows: rows.map((r) => ({ ...r })), tables, malformed: load.malformed };
+    }
+    finally {
+        db.close();
+    }
+}
+const cell = (v) => (v === null || v === undefined ? "" : String(v));
+/** The rows as an aligned table, a header and a count. */
+export function formatQueryResult(r) {
+    const widths = r.columns.map((c) => Math.max(c.length, ...r.rows.map((row) => cell(row[c]).length)));
+    const line = (vals) => vals.map((v, i) => v.padEnd(widths[i])).join("  ").trimEnd();
+    const out = [line(r.columns), line(widths.map((w) => "-".repeat(w))), ...r.rows.map((row) => line(r.columns.map((c) => cell(row[c]))))];
+    out.push(`(${r.rows.length} ${r.rows.length === 1 ? "row" : "rows"})`);
+    return out.join("\n");
+}

package/dist/lifecycle/run-ledger.d.ts

@@ -60,4 +60,17 @@ export declare function readRunLedger(environment: string, op: string, opts?: {
     records: OpRunRecord[];
     malformed: number;
 }>;
+/** The run ledger file name for `op` under `<env>/`, `runs__<op>.jsonl`. */
+export declare function runLedgerFile(op: string): string;
+/** The op a run ledger file name holds, or null when `file` is not one. */
+export declare function opOfRunLedgerFile(file: string): string | null;
+/**
+ * Parse the text of one run ledger file the way {@link readRunLedger} reads
+ * it (#4297): a reader that fetches the file itself, such as `chant query`,
+ * gets the same records and the same malformed count.
+ */
+export declare function parseRunLedger(content: string): {
+    records: OpRunRecord[];
+    malformed: number;
+};
 //# sourceMappingURL=run-ledger.d.ts.map

package/dist/lifecycle/run-ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-ledger.d.ts","sourceRoot":"","sources":["../../src/lifecycle/run-ledger.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAkB,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAA+C,MAAM,eAAe,CAAC;AASrI,0EAA0E;AAC1E,eAAO,MAAM,eAAe,UAAU,CAAC;AAMvC,8FAA8F;AAC9F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,MAAM,CAEjE;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC,EACzC,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACjC,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACrC,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC,GACA,gBAAgB,CAkDlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,gBAAgB,EACvB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC,CAsBlD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAkCxD"}
+{"version":3,"file":"run-ledger.d.ts","sourceRoot":"","sources":["../../src/lifecycle/run-ledger.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAkB,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAA+C,MAAM,eAAe,CAAC;AASrI,0EAA0E;AAC1E,eAAO,MAAM,eAAe,UAAU,CAAC;AAMvC,8FAA8F;AAC9F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,MAAM,CAEjE;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC,EACzC,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACjC,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACrC,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC,GACA,gBAAgB,CAkDlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,gBAAgB,EACvB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC,CAsBlD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAIxD;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CA+B7F"}

package/dist/lifecycle/run-ledger.js

@@ -163,6 +163,22 @@ export async function readRunLedger(environment, op, opts) {
     const content = await readBlobFromPath(environment, fileFor(op), opts);
     if (!content)
         return { records: [], malformed: 0 };
+    return parseRunLedger(content);
+}
+/** The run ledger file name for `op` under `<env>/`, `runs__<op>.jsonl`. */
+export function runLedgerFile(op) {
+    return fileFor(op);
+}
+/** The op a run ledger file name holds, or null when `file` is not one. */
+export function opOfRunLedgerFile(file) {
+    return file.startsWith(PREFIX) && file.endsWith(".jsonl") && file.length > PREFIX.length + ".jsonl".length ? file.slice(PREFIX.length, -".jsonl".length) : null;
+}
+/**
+ * Parse the text of one run ledger file the way {@link readRunLedger} reads
+ * it (#4297): a reader that fetches the file itself, such as `chant query`,
+ * gets the same records and the same malformed count.
+ */
+export function parseRunLedger(content) {
     const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
     const records = [];
     let malformed = 0;

package/dist/lifecycle/target-lock.d.ts

@@ -0,0 +1,97 @@
+/** The directory on `chant/lifecycle` that holds the lock files. */
+export declare const LOCKS_DIR = "_locks";
+/**
+ * How a lock was taken. `plan`: the pull request's plan took it (`ci.locks:
+ * plan`). `apply`: its apply took it. `lock`: someone ran `chant lock`.
+ */
+export type TargetLockStage = "plan" | "apply" | "lock";
+export declare const TARGET_LOCK_STAGES: readonly ["plan", "apply", "lock"];
+/** One target's lock: the pull request that holds it, who took it, when, how, and the head it took it at. */
+export interface TargetLock {
+    pr: number;
+    by: string;
+    at: string;
+    stage: TargetLockStage;
+    /** The pull request's head commit when the lock was taken. Absent when the caller did not say. */
+    head?: string;
+}
+/** `_locks/<gate>.json`. */
+export interface TargetLockFile {
+    version: 1;
+    locks: Record<string, TargetLock>;
+}
+/** A lock another open pull request holds on a target the caller needs. */
+export interface HeldTargetLock extends TargetLock {
+    target: string;
+}
+/** Says whether pull request `pr` is still open. */
+export type PullRequestOpen = (pr: number) => Promise<boolean>;
+export interface TargetLockOptions {
+    cwd?: string;
+    /** Whether a holder is still open. Absent: every holder counts as open. */
+    isOpen?: PullRequestOpen;
+}
+export type TakeTargetLocksResult = {
+    ok: true;
+    /** The targets now locked, sorted. */
+    taken: string[];
+    /** Plan locks of the same pull request on targets it no longer reaches, released (`releaseStalePlan`). */
+    released: string[];
+    /** Locks of merged or closed pull requests that this write dropped. */
+    expired: string[];
+    /** Whether the remote has the write. False with no remote, or when recording is off. */
+    pushed: boolean;
+} | {
+    ok: false;
+    held: HeldTargetLock[];
+};
+/** The path of `gate`'s lock file on `chant/lifecycle`, under a member's prefix when it has one. */
+export declare function targetLockPath(gate: string, memberPrefix?: string): string;
+/** A gate name that is safe as a file name. */
+export declare function targetLockGateProblem(gate: string): string | null;
+/** Parse a lock file. Anything that is not a version 1 file with a map of locks reads as no locks; a malformed entry is dropped. */
+export declare function parseTargetLocks(text: string | null): TargetLockFile;
+/** The file's text: targets sorted, so two writes of the same locks are the same blob. */
+export declare function renderTargetLocks(file: TargetLockFile): string;
+/** The locks of `gate` as the remote holds them now, fetched first. */
+export declare function readTargetLocks(gate: string, opts?: {
+    cwd?: string;
+}): Promise<TargetLockFile>;
+/**
+ * The locks on `targets` that an open pull request other than `pr` holds.
+ * Reads only: an apply calls this to refuse a target another pull request
+ * holds. `pr` null (an apply of a green commit) counts every open holder.
+ */
+export declare function heldTargetLocks(gate: string, targets: readonly string[], pr: number | null, opts?: TargetLockOptions): Promise<HeldTargetLock[]>;
+/**
+ * Lock `targets` for pull request `holder.pr`. A target locked by another
+ * pull request that is still open is held, and nothing is locked. A target
+ * locked by one that merged or closed is taken over, and its lock dropped.
+ * Targets this pull request already holds stay its own, with the new head.
+ * An apply or a `chant lock` takes over the pull request's own plan locks;
+ * a plan keeps its own apply and `chant lock` locks as they are. With
+ * `releaseStalePlan`, the pull request's plan locks on targets it no longer
+ * reaches are released.
+ */
+export declare function takeTargetLocks(gate: string, targets: readonly string[], holder: TargetLock, opts?: TargetLockOptions & {
+    releaseStalePlan?: boolean;
+}): Promise<TakeTargetLocksResult>;
+/**
+ * Release the locks pull request `pr` holds on `gate`: every one, or only
+ * those on `targets`. Returns the targets released, sorted.
+ */
+export declare function releaseTargetLocks(gate: string, pr: number, opts?: {
+    cwd?: string;
+    targets?: readonly string[];
+}): Promise<{
+    released: string[];
+    pushed: boolean;
+}>;
+/** The lock file's path for the project at `cwd`, for messages. */
+export declare function targetLockPathAt(gate: string, cwd?: string): Promise<string>;
+/**
+ * One line naming the targets others hold, for a refusal or a note.
+ * `name` says how the forge names a holder (GitLab: `merge request !7`).
+ */
+export declare function describeHeldTargetLocks(held: readonly HeldTargetLock[], name?: (pr: number) => string): string;
+//# sourceMappingURL=target-lock.d.ts.map

package/dist/lifecycle/target-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-lock.d.ts","sourceRoot":"","sources":["../../src/lifecycle/target-lock.ts"],"names":[],"mappings":"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"}