@intentius/chant 0.124.39 → 0.124.41

package/src/lifecycle/query.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "vitest";
+import type { LedgerReadPort } from "./ledger-port";
+import { firstWord, formatQueryResult, loadQueryData, QUERY_SCHEMA_VERSION, QUERY_TABLES, QueryError, runQuery, SCHEMA_TABLE } from "./query";
+import { makeRelease } from "./release-store";
+
+/** A port over a map of `<dir>/<file>` to text, the shape `gitLedgerReadPort` reads. */
+function port(files: Record<string, string>): LedgerReadPort {
+  const dirs = (): string[] => [...new Set(Object.keys(files).map((p) => p.slice(0, p.indexOf("/"))))];
+  return {
+    read: async (dir, file) => files[`${dir}/${file}`] ?? null,
+    list: async (dir) => Object.keys(files).filter((p) => p.startsWith(`${dir}/`)).map((p) => p.slice(dir.length + 1)),
+    trees: async () => dirs(),
+  };
+}
+
+const lines = (...rows: unknown[]): string => rows.map((r) => (typeof r === "string" ? r : JSON.stringify(r))).join("\n") + "\n";
+
+const release = makeRelease({ member: null, commit: "c".repeat(40), artifactDigests: [{ component: "api", kind: "image", path: "dist/api.tar", digest: "sha256:aa" }], targets: [{ env: "prod", templates: [], params: [] }] });
+
+const ledger = port({
+  "prod/aws.json": JSON.stringify({ lexicon: "aws", environment: "prod", commit: "a".repeat(40), timestamp: "2026-10-01T00:00:00Z", resources: { Bucket: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE", physicalId: "my-bucket", attributes: { Arn: "arn:aws:s3:::my-bucket" } }, Queue: { type: "AWS::SQS::Queue", status: "CREATE_COMPLETE" } } }),
+  "prod/edge__k8s.json": JSON.stringify({ lexicon: "k8s", environment: "prod", commit: "b".repeat(40), timestamp: "2026-10-02T00:00:00Z", depth: "deep", resources: { Web: { type: "K8s::Apps::Deployment", status: "Available", ownership: "owned" } }, unobserved: { Gone: { reason: "not-found" } } }),
+  "prod/observation-baseline.json": JSON.stringify({ version: 1, environment: "prod" }),
+  "prod/releases.jsonl": lines(
+    { version: 1, component: "api", env: "prod", digest: "sha256:aa", gitSha: "c".repeat(40), runId: "r1", runOrigin: { forge: "github", url: "https://example.test/run/1" }, timestamp: "2026-10-03T00:00:00Z", actor: "ci", releaseDigest: release.releaseDigest },
+    "{not json",
+  ),
+  "prod/runs__deploy.jsonl": lines(
+    { version: 1, id: "run-1", op: "deploy", env: "prod", started: "2026-10-03T00:00:00Z", ended: "2026-10-03T00:01:00Z", status: "fail", labels: { Env: "prod" }, outcomes: {}, phases: [], failure: { code: "command-failed", reason: "exit 1", phase: "apply" } },
+    { version: 1, id: "run-2", op: "deploy", env: "prod", started: "2026-10-04T00:00:00Z", ended: "2026-10-04T00:01:00Z", status: "ok", labels: {}, outcomes: { url: "https://x" }, phases: [] },
+  ),
+  "_gates/deploy.jsonl": lines(
+    { version: 1, kind: "pending", op: "deploy", gate: "prod-approval", timestamp: "2026-10-03T00:00:00Z", expiresAt: "2026-10-10T00:00:00Z", planDigest: "sha256:p1", origin: "cli" },
+    { version: 1, op: "deploy", gate: "prod-approval", resolvedBy: "alice", timestamp: "2026-10-03T01:00:00Z", planDigest: "sha256:p1", approver: { kind: "human" } },
+  ),
+  [`_releases/${release.releaseDigest.replace(/:/g, "_")}.json`]: JSON.stringify(release),
+  "_releases/sha256_tampered.json": JSON.stringify({ ...release, releaseDigest: "sha256:tampered" }),
+  "_releases/cuts.jsonl": lines({ version: 1, releaseDigest: release.releaseDigest, label: "v1.0.0", actor: "alice", timestamp: "2026-10-02T12:00:00Z", runId: null, runOrigin: null, signature: null }),
+});
+
+describe("chant query (#4297)", () => {
+  test("loads every ledger into its table and counts what it can't read", async () => {
+    const load = await loadQueryData([{ member: null, port: ledger }]);
+    expect(load.data.snapshots).toHaveLength(2);
+    expect(load.data.resources.map((r) => r.name)).toEqual(["Bucket", "Queue", "Web"]);
+    expect(load.data.resources[2]).toMatchObject({ stack: "edge", lexicon: "k8s", ownership: "owned" });
+    expect(load.data.snapshots[1]).toMatchObject({ depth: "deep", resources: 1, unobserved: 1 });
+    expect(load.data.runs.map((r) => r.status)).toEqual(["fail", "ok"]);
+    expect(load.data.gates.map((g) => g.kind)).toEqual(["pending", "resolution"]);
+    expect(load.data.deploys).toHaveLength(1);
+    expect(load.data.releases).toEqual([expect.objectContaining({ release_digest: release.releaseDigest, envs: "prod" })]);
+    expect(load.data.cuts[0]).toMatchObject({ label: "v1.0.0", signed: 0 });
+    expect(load.malformed).toMatchObject({ deploys: 1, releases: 1, runs: 0, gates: 0 });
+  });
+
+  test("runs SQL over the tables and joins them", async () => {
+    const load = await loadQueryData([{ member: null, port: ledger }]);
+    const byType = await runQuery("SELECT lexicon, count(*) AS n FROM resources GROUP BY lexicon ORDER BY lexicon", load);
+    expect(byType.columns).toEqual(["lexicon", "n"]);
+    expect(byType.rows).toEqual([{ lexicon: "aws", n: 2 }, { lexicon: "k8s", n: 1 }]);
+    const joined = await runQuery("SELECT d.component, c.label FROM deploys d JOIN cuts c ON c.release_digest = d.release_digest", load);
+    expect(joined.rows).toEqual([{ component: "api", label: "v1.0.0" }]);
+    const arn = await runQuery("SELECT json_extract(attributes, '$.Arn') AS arn FROM resources WHERE name = 'Bucket'", load);
+    expect(arn.rows[0].arn).toBe("arn:aws:s3:::my-bucket");
+    expect(arn.schemaVersion).toBe(QUERY_SCHEMA_VERSION);
+    expect(formatQueryResult(arn)).toContain("(1 row)");
+  });
+
+  test("chant_schema lists every column with the schema version", async () => {
+    const load = await loadQueryData([]);
+    const r = await runQuery(`SELECT DISTINCT version, table_name FROM ${SCHEMA_TABLE} ORDER BY table_name`, load);
+    expect(r.rows.map((x) => x.table_name)).toEqual(Object.keys(QUERY_TABLES).sort());
+    expect(new Set(r.rows.map((x) => x.version))).toEqual(new Set([QUERY_SCHEMA_VERSION]));
+  });
+
+  test("each member's rows name the member", async () => {
+    const load = await loadQueryData([{ member: "api", port: ledger }, { member: "web", port: port({}) }]);
+    const r = await runQuery("SELECT DISTINCT member FROM runs", load);
+    expect(r.rows).toEqual([{ member: "api" }]);
+  });
+
+  test("refuses anything but a read", async () => {
+    const load = await loadQueryData([]);
+    await expect(runQuery("DELETE FROM runs", load)).rejects.toBeInstanceOf(QueryError);
+    await expect(runQuery("  ", load)).rejects.toBeInstanceOf(QueryError);
+    // A WITH that writes is stopped by query_only.
+    await expect(runQuery("WITH x AS (SELECT 1) INSERT INTO runs (id) SELECT * FROM x", load)).rejects.toBeInstanceOf(QueryError);
+    await expect(runQuery("SELECT nope FROM runs", load)).rejects.toThrow(/does not run/);
+    expect(firstWord("-- note\n /* c */ select 1")).toBe("select");
+  });
+});

package/src/lifecycle/query.ts

@@ -0,0 +1,315 @@
+/**
+ * `chant query "<sql>"` (#4297): one read-only SQL statement over what
+ * `chant/lifecycle` holds, run in this process with no server.
+ *
+ * The rows come from the ledgers chant already writes:
+ *
+ * - the snapshots, `<env>/<lexicon>.json` and `<env>/<stack>__<lexicon>.json`
+ *   (`./git.ts` `snapshotStorageKey`), each lexicon's `describeResources`
+ *   read, so the inventory works for every lexicon;
+ * - the Op run ledgers, `<env>/runs__<op>.jsonl` (`./run-ledger.ts`);
+ * - the gate ledgers, `_gates/<op>.jsonl` (`./gate-ledger.ts`);
+ * - the deploy records, `<env>/releases.jsonl` (`./release-read.ts`);
+ * - the releases and their cuts, `_releases/<digest>.json` and
+ *   `_releases/cuts.jsonl` (`./release-store.ts`).
+ *
+ * The tables are a contract. {@link QUERY_SCHEMA_VERSION} names it, and the
+ * `chant_schema` table lists every table and column with the version, so a
+ * saved query can check what it runs against. A column is only added within
+ * a version; renaming or removing one, or changing what it holds, is a new
+ * version.
+ *
+ * Everything but {@link runQuery} is pure over a {@link LedgerReadPort}: the
+ * caller decides which members to read and how.
+ *
+ * The engine is `node:sqlite`, the SQLite built into Node.js 22.13 and later.
+ * The database is in memory, takes `PRAGMA query_only`, and only a statement
+ * that begins with SELECT, WITH or VALUES runs. This mirrors terragucci's
+ * `query.ts`, which reads report JSON from a bucket instead.
+ */
+import type { GateOrigin } from "./gate-origin";
+import { parseGateLedger, GATES_DIR, type GateResolutionRecord, type PendingGateRecord } from "./gate-ledger";
+import type { LedgerReadPort } from "./ledger-port";
+import { parseReleaseLedger, releaseLedgerLines } from "./release-read";
+import { CUTS_FILE, parseCuts, parseRelease, RELEASES_DIR, verifyReleaseDigest } from "./release-store";
+import { opOfRunLedgerFile, parseRunLedger } from "./run-ledger";
+import type { LifecycleSnapshot } from "./types";
+
+/** The version of the table schema below. */
+export const QUERY_SCHEMA_VERSION = 1;
+
+type ColumnType = "TEXT" | "INTEGER";
+
+/**
+ * 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"]],
+} as const satisfies Record<string, ReadonlyArray<readonly [string, ColumnType]>>;
+
+export type QueryTable = keyof typeof QUERY_TABLES;
+
+/** The table that describes the others: one row per column, with the schema version. */
+export const SCHEMA_TABLE = "chant_schema";
+
+type Value = string | number | null;
+export type QueryRow = Record<string, Value>;
+
+/** The rows of each table, as loaded. */
+export type QueryData = Record<QueryTable, QueryRow[]>;
+
+/** One ledger to read: a member's, or the project's own with `member` null. */
+export interface QueryLedger {
+  member: string | null;
+  port: LedgerReadPort;
+}
+
+export interface QueryLoad {
+  data: QueryData;
+  /** Lines and files that could not be read as their kind, per table. Left out of the rows. */
+  malformed: Record<QueryTable, number>;
+}
+
+export interface QueryResult {
+  schemaVersion: number;
+  columns: string[];
+  rows: QueryRow[];
+  /** How many rows each table held. */
+  tables: Record<QueryTable, number>;
+  malformed: Record<QueryTable, number>;
+}
+
+/** 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) as QueryTable[];
+const empty = <T>(v: () => T): Record<QueryTable, T> => Object.fromEntries(TABLE_NAMES.map((t) => [t, v()])) as Record<QueryTable, T>;
+const json = (v: unknown): string | null => (v === undefined || v === null ? null : JSON.stringify(v));
+const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
+const bit = (v: boolean): number => (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: unknown): v is LifecycleSnapshot {
+  if (!v || typeof v !== "object") return false;
+  const s = v as Partial<LifecycleSnapshot>;
+  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: string | null, env: string, file: string, s: LifecycleSnapshot, data: QueryData): void {
+  // 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: string | null, r: GateResolutionRecord | PendingGateRecord): QueryRow {
+  const pending = r.kind === "pending";
+  const res = pending ? undefined : (r as GateResolutionRecord);
+  const origin: GateOrigin | undefined = (r as { origin?: GateOrigin }).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 as PendingGateRecord).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: readonly QueryLedger[]): Promise<QueryLoad> {
+  const data = empty<QueryRow[]>(() => []) as QueryData;
+  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: unknown;
+          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 };
+}
+
+/** The part of `node:sqlite` this uses, typed here since the repo's @types/node predates the module. */
+interface SqliteStatement {
+  run(...values: Value[]): unknown;
+  all(): unknown[];
+  columns?(): Array<{ name: string }>;
+}
+interface SqliteModule {
+  DatabaseSync: new (path: string) => { exec(sql: string): void; prepare(sql: string): SqliteStatement; close(): void };
+}
+
+/** node:sqlite, without the experimental warning some Node.js versions print when it loads. */
+async function sqlite(): Promise<SqliteModule> {
+  const emit = process.emitWarning;
+  process.emitWarning = ((warning: string | Error, ...rest: unknown[]) => {
+    if (/SQLite/.test(typeof warning === "string" ? warning : warning.message)) return;
+    return (emit as (...a: unknown[]) => void).call(process, warning, ...rest);
+  }) as typeof process.emitWarning;
+  try {
+    const name = "node:sqlite";
+    return (await import(name)) as SqliteModule;
+  } 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: string): string {
+  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: string, load: QueryLoad): Promise<QueryResult> {
+  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] as ReadonlyArray<readonly [string, ColumnType]>;
+      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: SqliteStatement;
+    try {
+      stmt = db.prepare(sql);
+    } catch (e) {
+      throw new QueryError(`the query does not run: ${(e as Error).message}`);
+    }
+    let rows: QueryRow[];
+    try {
+      rows = stmt.all() as QueryRow[];
+    } catch (e) {
+      throw new QueryError(`the query does not run: ${(e as Error).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])) as Record<QueryTable, number>;
+    return { schemaVersion: QUERY_SCHEMA_VERSION, columns, rows: rows.map((r) => ({ ...r })), tables, malformed: load.malformed };
+  } finally {
+    db.close();
+  }
+}
+
+const cell = (v: Value | undefined): string => (v === null || v === undefined ? "" : String(v));
+
+/** The rows as an aligned table, a header and a count. */
+export function formatQueryResult(r: QueryResult): string {
+  const widths = r.columns.map((c) => Math.max(c.length, ...r.rows.map((row) => cell(row[c]).length)));
+  const line = (vals: string[]): string => 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/src/lifecycle/release-ledger.ts

@@ -242,6 +242,35 @@ export interface ReleaseRecord {
    * deploy that was not made from a release.
    */
   releaseDigest?: string;
+  /**
+   * Optional: what `digest` names when it is not an artifact digest (#4274).
+   * Absent on a record whose digest is the artifact the deploy promoted, and on
+   * every record written before 0.124.35.
+   *
+   * - `plan`: the component published nothing, and the digest is its plan
+   *   digest, the one its approval bound (`pr-apply`).
+   * - `deploy-input`: the component published nothing and planned nothing, and
+   *   the digest is its deploy-input digest (`componentInputDigests`,
+   *   ../components/fan-out-inputs.ts).
+   * - `templates`: the digest of the templates the release records for the
+   *   component (#4222, `releaseTemplatesDigest`).
+   *
+   * A `plan` or `deploy-input` record says the component applied; it names no
+   * artifact, so promote, rollback and redeploy never deploy it
+   * ({@link isApplyRecord}).
+   */
+  digestKind?: ReleaseDigestKind;
+}
+
+/** What a release record's `digest` names when it is not an artifact digest (#4274). */
+export type ReleaseDigestKind = "plan" | "deploy-input" | "templates";
+
+/**
+ * Whether `record` only says its component applied (#4274): its digest is a
+ * plan or deploy-input digest, not one anything can be deployed from again.
+ */
+export function isApplyRecord(record: Pick<ReleaseRecord, "digestKind">): boolean {
+  return record.digestKind === "plan" || record.digestKind === "deploy-input";
 }
 
 /** 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. */
@@ -319,9 +348,21 @@ export function resolveCiRun(env: NodeJS.ProcessEnv = process.env): { runId: str
       },
     };
   }
+  // #4275: a step of a job the chant runner ran. The forge branches come first, and the runner
+  // strips the forge's run variables from its steps, so neither kind of job is taken for the other.
+  if (env[CHANT_CI_RUN_ID_ENV] && env[CHANT_CI_RUN_FORGE_ENV] === "chant") {
+    return { runId: env[CHANT_CI_RUN_ID_ENV], runOrigin: { forge: "chant" } };
+  }
   return undefined;
 }
 
+/** The run id `chant ci run` hands each step of a job it runs (#4275), the id its run index lists. */
+export const CHANT_CI_RUN_ID_ENV = "CHANT_CI_RUN_ID";
+/** The run's origin `chant ci run` hands each step with {@link CHANT_CI_RUN_ID_ENV}: always `chant`. */
+export const CHANT_CI_RUN_FORGE_ENV = "CHANT_CI_RUN_FORGE";
+/** The forge's run variables, which a step of a job the chant runner ran never gets (#4275). */
+export const FORGE_RUN_ENV = ["GITHUB_RUN_ID", "GITHUB_RUN_ATTEMPT", "GITHUB_JOB", "CI_PIPELINE_ID", "CI_PIPELINE_URL", "CI_JOB_ID"] as const;
+
 /**
  * The CI run the environment names, as {@link resolveCiRun} has it, with the
  * job within the run and the run's attempt when the forge gives them
@@ -332,7 +373,7 @@ export function resolveCiJob(env: NodeJS.ProcessEnv = process.env): { runId: str
   const ci = resolveCiRun(env);
   if (!ci) return undefined;
   const github = ci.runOrigin.forge === "github";
-  const jobId = github ? env.GITHUB_JOB : env.CI_JOB_ID;
+  const jobId = github ? env.GITHUB_JOB : ci.runOrigin.forge === "gitlab" ? env.CI_JOB_ID : undefined;
   const attempt = github ? Number(env.GITHUB_RUN_ATTEMPT) : NaN;
   return {
     runId: ci.runId,

package/src/lifecycle/run-ledger.ts

@@ -197,7 +197,25 @@ export async function readRunLedger(
 ): Promise<{ records: OpRunRecord[]; malformed: number }> {
   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: string): string {
+  return fileFor(op);
+}
 
+/** The op a run ledger file name holds, or null when `file` is not one. */
+export function opOfRunLedgerFile(file: string): string | null {
+  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: string): { records: OpRunRecord[]; malformed: number } {
   const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
   const records: OpRunRecord[] = [];
   let malformed = 0;

package/src/lifecycle/status.test.ts

@@ -432,6 +432,16 @@ describe("status", () => {
       expect(result.digestB).toBe("sha256:prod-bytes");
     });
 
+    test("apply records compare on the commit, since their digests take in the environment (#4274)", () => {
+      const apply = (env: string, gitSha: string) =>
+        record({ component: "infra", env, gitSha, digest: `jcs1-sha256:${env.padEnd(64, "0").slice(0, 64)}`, digestKind: "deploy-input" });
+      const same = compareAcrossEnvironments("infra", { name: "staging", records: [apply("staging", "a1")] }, { name: "prod", records: [apply("prod", "a1")] });
+      expect(same.same).toBe(true);
+      expect(same.comparedOn).toEqual({ a: "git:a1", b: "git:a1" });
+      const moved = compareAcrossEnvironments("infra", { name: "staging", records: [apply("staging", "b2")] }, { name: "prod", records: [apply("prod", "a1")] });
+      expect(moved.same).toBe(false);
+    });
+
     test("differing inputDigests are a real difference, whatever the bytes say", () => {
       const result = compareAcrossEnvironments(
         "web",
@@ -671,6 +681,15 @@ describe("drifted: live evidence contradicts the recorded release (#2513)", () =
     expect(row.reconciliation).toBe("reconciled");
   });
 
+  test("reconciled: an apply record's plan digest is never held against a live digest (#4274)", () => {
+    const row = reconcile(
+      [entry()],
+      new Map([["svc", { now: live({ attributes: { digest: "sha256:other", gitSha: "1111111" } }) }]]),
+      { ...released, digest: `jcs1-sha256:${"a".repeat(64)}`, digestKind: "plan" },
+    );
+    expect(row.reconciliation).toBe("reconciled");
+  });
+
   test("drifted: a foreign digest", () => {
     const row = reconcile([entry()], new Map([["svc", { now: live({ attributes: { digest: "sha256:other" } }) }]]));
     expect(row.reconciliation).toBe("drifted");

package/src/lifecycle/status.ts

@@ -43,7 +43,7 @@
 
 import type { ChangeSet, ChangeAction } from "./change-set";
 import type { ResourceMetadata } from "../lexicon";
-import { latestPerComponent, type ReleaseRecord } from "./release-ledger";
+import { isApplyRecord, latestPerComponent, type ReleaseRecord } from "./release-ledger";
 import { isLegacyContentDigest } from "./legacy-digest";
 import type { BuildLedgerEntry, ComponentBomSummary } from "./build-ledger";
 import { unobservedReasonText, type UnobservedReason } from "../observation";
@@ -647,7 +647,8 @@ function notBefore(since: string, recordedAt: string): boolean {
  */
 function contradictsRecord(recorded: ReleaseRecord, evidence: LiveComponentEvidence): string | undefined {
   for (const id of evidence.identities ?? []) {
-    if (id.digest !== undefined) {
+    // #4274: an apply's digest is a plan or deploy-input digest, which no live resource reports.
+    if (id.digest !== undefined && !isApplyRecord(recorded)) {
       const matches =
         sameDigest(id.digest, recorded.digest) ||
         (recorded.inputDigest !== undefined && sameDigest(id.digest, recorded.inputDigest));
@@ -697,7 +698,9 @@ export interface CrossEnvComparison {
    * environments legitimately render to different bytes, so cross-environment
    * "is prod running what staging tested" joins on the input side while
    * `digest` proves the exact bytes each cluster got. Records without it
-   * compare on `digest` exactly as before.
+   * compare on `digest` exactly as before. An apply record (#4274) compares
+   * on its `gitSha`, since its plan or deploy-input digest takes in the
+   * environment and so differs between any two.
    */
   same: boolean;
   /** The identities `same` was decided on (`inputDigest ?? digest` per side), when both sides had one and they differ from the digests shown. */
@@ -711,6 +714,11 @@ export interface CrossEnvComparison {
   mixedDigestForms?: true;
 }
 
+/** What two environments' records of a component are compared on: the input side when there is one, the commit for an apply (#4274). */
+export function comparableIdentity(record: ReleaseRecord): string {
+  return isApplyRecord(record) ? `git:${record.gitSha}` : record.inputDigest ?? record.digest;
+}
+
 /** Compare the latest recorded digest for `component` between two environments' release records. */
 export function compareAcrossEnvironments(
   component: string,
@@ -719,9 +727,9 @@ export function compareAcrossEnvironments(
 ): CrossEnvComparison {
   const latestA = latestPerComponent(envA.records).get(component);
   const latestB = latestPerComponent(envB.records).get(component);
-  const idA = latestA ? latestA.inputDigest ?? latestA.digest : undefined;
-  const idB = latestB ? latestB.inputDigest ?? latestB.digest : undefined;
-  const comparedOnInputs = (latestA?.inputDigest ?? latestB?.inputDigest) !== undefined;
+  const idA = latestA ? comparableIdentity(latestA) : undefined;
+  const idB = latestB ? comparableIdentity(latestB) : undefined;
+  const comparedOnInputs = (latestA !== undefined && idA !== latestA.digest) || (latestB !== undefined && idB !== latestB.digest);
   return {
     component,
     envA: envA.name,