@intentius/chant 0.124.40 → 0.124.42

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/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/target-lock.test.ts

@@ -0,0 +1,195 @@
+/**
+ * #4293: target locks a pull request holds, `_locks/<gate>.json` on
+ * `chant/lifecycle`, in one clone and across clones through a bare remote.
+ */
+import { afterAll, describe, expect, test } from "vitest";
+import { execFileSync } from "node:child_process";
+import { chmodSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  describeHeldTargetLocks,
+  heldTargetLocks,
+  parseTargetLocks,
+  readTargetLocks,
+  releaseTargetLocks,
+  renderTargetLocks,
+  takeTargetLocks,
+  targetLockGateProblem,
+  targetLockPath,
+  type TargetLock,
+} from "./target-lock";
+
+const dirs: string[] = [];
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+function tmp(prefix: string): string {
+  const d = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+  dirs.push(d);
+  return d;
+}
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function configure(dir: string): void {
+  git(dir, "config", "user.email", "test@chant.dev");
+  git(dir, "config", "user.name", "Test");
+  git(dir, "config", "commit.gpgsign", "false");
+}
+
+function initRepo(): string {
+  const dir = tmp("chant-target-lock-");
+  git(dir, "init", "-q", "-b", "main");
+  configure(dir);
+  writeFileSync(join(dir, "README.md"), "# t\n");
+  git(dir, "add", "README.md");
+  git(dir, "commit", "-q", "-m", "init");
+  return dir;
+}
+
+const holder = (pr: number, stage: TargetLock["stage"], by = "alice"): TargetLock => ({ pr, by, at: "2026-10-22T10:00:00.000Z", stage, head: "a".repeat(40) });
+
+describe("the lock file", () => {
+  test("parses a version 1 file and drops malformed entries; anything else holds no locks", () => {
+    const text = JSON.stringify({ version: 1, locks: { web: holder(1, "plan"), bad: { pr: "x" }, api: { pr: 2, by: "b", at: "t", stage: "nope" } } });
+    expect(parseTargetLocks(text)).toEqual({ version: 1, locks: { web: holder(1, "plan") } });
+    expect(parseTargetLocks("not json")).toEqual({ version: 1, locks: {} });
+    expect(parseTargetLocks(JSON.stringify({ version: 2, locks: {} }))).toEqual({ version: 1, locks: {} });
+    expect(parseTargetLocks(null)).toEqual({ version: 1, locks: {} });
+  });
+
+  test("renders targets sorted, so the same locks are the same blob", () => {
+    const a = renderTargetLocks({ version: 1, locks: { web: holder(1, "plan"), api: holder(2, "lock") } });
+    const b = renderTargetLocks({ version: 1, locks: { api: holder(2, "lock"), web: holder(1, "plan") } });
+    expect(a).toBe(b);
+    expect(Object.keys(JSON.parse(a).locks)).toEqual(["api", "web"]);
+  });
+
+  test("the path is _locks/<gate>.json under the member prefix, and a gate name must be a file name", () => {
+    expect(targetLockPath("pr-apply")).toBe("_locks/pr-apply.json");
+    expect(targetLockPath("pr-apply", "_members/api/")).toBe("_members/api/_locks/pr-apply.json");
+    expect(targetLockGateProblem("pr-apply")).toBeNull();
+    expect(targetLockGateProblem("../x")).toMatch(/not a lock file name/);
+  });
+
+  test("describes held locks by pull request, with how they were taken", () => {
+    const text = describeHeldTargetLocks([
+      { target: "api", ...holder(7, "plan", "bob") },
+      { target: "web", ...holder(7, "plan", "bob") },
+      { target: "db", ...holder(9, "lock", "carol") },
+    ], (n) => `merge request !${n}`);
+    expect(text).toBe("api, web are locked by merge request !7 (planned by bob); db is locked by merge request !9 (locked with chant lock by carol)");
+  });
+});
+
+describe("target locks in one clone", () => {
+  test("a pull request takes free targets; another is refused with the holder named; unlock frees them", async () => {
+    const cwd = initRepo();
+    const first = await takeTargetLocks("pr-apply", ["web", "api"], holder(1, "plan"), { cwd });
+    expect(first).toEqual({ ok: true, taken: ["api", "web"], released: [], expired: [], pushed: false });
+    expect(JSON.parse(git(cwd, "show", "chant/lifecycle:_locks/pr-apply.json")).locks.web.pr).toBe(1);
+
+    const second = await takeTargetLocks("pr-apply", ["web", "db"], holder(2, "plan", "bob"), { cwd });
+    expect(second).toEqual({ ok: false, held: [{ target: "web", ...holder(1, "plan") }] });
+    // Nothing of the refused pull request was written.
+    expect(Object.keys((await readTargetLocks("pr-apply", { cwd })).locks)).toEqual(["api", "web"]);
+
+    expect(await heldTargetLocks("pr-apply", ["web", "db"], 2, { cwd })).toHaveLength(1);
+    expect(await heldTargetLocks("pr-apply", ["web", "db"], 1, { cwd })).toEqual([]);
+    expect(await heldTargetLocks("pr-apply", ["web"], null, { cwd })).toHaveLength(1);
+
+    expect(await releaseTargetLocks("pr-apply", 1, { cwd, targets: ["api"] })).toEqual({ released: ["api"], pushed: false });
+    expect(await releaseTargetLocks("pr-apply", 1, { cwd })).toEqual({ released: ["web"], pushed: false });
+    expect(await releaseTargetLocks("pr-apply", 1, { cwd })).toEqual({ released: [], pushed: false });
+    expect(await takeTargetLocks("pr-apply", ["web", "db"], holder(2, "plan", "bob"), { cwd })).toMatchObject({ ok: true, taken: ["db", "web"] });
+  });
+
+  test("a lock whose pull request merged or closed is taken over and dropped", async () => {
+    const cwd = initRepo();
+    await takeTargetLocks("pr-apply", ["web", "api"], holder(1, "plan"), { cwd });
+    const isOpen = async (pr: number) => pr !== 1;
+    const taken = await takeTargetLocks("pr-apply", ["web"], holder(2, "lock", "bob"), { cwd, isOpen });
+    expect(taken).toMatchObject({ ok: true, taken: ["web"], expired: ["api", "web"] });
+    expect((await readTargetLocks("pr-apply", { cwd })).locks).toEqual({ web: holder(2, "lock", "bob") });
+    expect(await heldTargetLocks("pr-apply", ["web"], 3, { cwd, isOpen: async () => false })).toEqual([]);
+  });
+
+  test("a plan keeps the pull request's own lock and apply locks; an apply takes over its plan locks", async () => {
+    const cwd = initRepo();
+    await takeTargetLocks("pr-apply", ["web"], holder(1, "lock"), { cwd });
+    await takeTargetLocks("pr-apply", ["web", "api"], holder(1, "plan"), { cwd });
+    let locks = (await readTargetLocks("pr-apply", { cwd })).locks;
+    expect(locks.web.stage).toBe("lock");
+    expect(locks.api.stage).toBe("plan");
+    await takeTargetLocks("pr-apply", ["api"], holder(1, "apply"), { cwd });
+    locks = (await readTargetLocks("pr-apply", { cwd })).locks;
+    expect(locks.api.stage).toBe("apply");
+  });
+
+  test("a plan with releaseStalePlan drops its plan locks on targets the head no longer reaches", async () => {
+    const cwd = initRepo();
+    await takeTargetLocks("pr-apply", ["web", "api"], holder(1, "plan"), { cwd });
+    await takeTargetLocks("pr-apply", ["db"], holder(1, "lock"), { cwd });
+    const again = await takeTargetLocks("pr-apply", ["web"], holder(1, "plan"), { cwd, releaseStalePlan: true });
+    expect(again).toMatchObject({ ok: true, taken: ["web"], released: ["api"] });
+    expect(Object.keys((await readTargetLocks("pr-apply", { cwd })).locks)).toEqual(["db", "web"]);
+  });
+
+  test("each gate keeps its own file", async () => {
+    const cwd = initRepo();
+    await takeTargetLocks("pr-apply", ["web"], holder(1, "plan"), { cwd });
+    expect(await takeTargetLocks("staging-apply", ["web"], holder(2, "plan"), { cwd })).toMatchObject({ ok: true });
+    expect(git(cwd, "ls-tree", "--name-only", "chant/lifecycle", "_locks/").split("\n").sort()).toEqual(["_locks/pr-apply.json", "_locks/staging-apply.json"]);
+  });
+});
+
+describe("target locks across clones, through a bare remote", () => {
+  function setup(): { root: string; remote: string; a: string; b: string } {
+    const root = tmp("chant-target-lock-remote-");
+    const remote = join(root, "remote.git");
+    git(root, "init", "-q", "--bare", "-b", "main", remote);
+    const a = join(root, "a");
+    git(root, "clone", "-q", remote, a);
+    configure(a);
+    writeFileSync(join(a, "README.md"), "# t\n");
+    git(a, "add", "README.md");
+    git(a, "commit", "-q", "-m", "init");
+    git(a, "push", "-q", "origin", "main");
+    const b = join(root, "b");
+    git(root, "clone", "-q", remote, b);
+    configure(b);
+    return { root, remote, a, b };
+  }
+
+  test("a lock reaches the remote, the other clone is refused, and an unlock there frees it", async () => {
+    const { remote, a, b } = setup();
+    expect(await takeTargetLocks("pr-apply", ["web"], holder(1, "plan"), { cwd: a })).toMatchObject({ ok: true, pushed: true });
+    expect(JSON.parse(git(remote, "show", "chant/lifecycle:_locks/pr-apply.json")).locks.web.pr).toBe(1);
+    expect(await takeTargetLocks("pr-apply", ["web"], holder(2, "plan"), { cwd: b })).toMatchObject({ ok: false, held: [{ target: "web", pr: 1 }] });
+    expect(await releaseTargetLocks("pr-apply", 1, { cwd: b })).toEqual({ released: ["web"], pushed: true });
+    expect(await takeTargetLocks("pr-apply", ["web"], holder(2, "plan"), { cwd: a })).toMatchObject({ ok: true, taken: ["web"], pushed: true });
+  });
+
+  test("a push the remote refuses is dropped and decided again: two clones can't both lock one target", async () => {
+    const { root, remote, a, b } = setup();
+    // A writes its lock locally only, with no remote, then pushes it from B's pre-push hook,
+    // so B's first push lands after A's and is refused.
+    git(a, "remote", "remove", "origin");
+    expect(await takeTargetLocks("pr-apply", ["web"], holder(1, "plan"), { cwd: a })).toMatchObject({ ok: true, pushed: false });
+    git(a, "remote", "add", "origin", remote);
+    const marker = join(root, "raced");
+    const hook = join(b, ".git", "hooks", "pre-push");
+    writeFileSync(hook, `#!/bin/sh\nif [ ! -e "${marker}" ]; then touch "${marker}"; git -C "${a}" push -q origin chant/lifecycle:chant/lifecycle; fi\nexit 0\n`);
+    chmodSync(hook, 0o755);
+
+    const lost = await takeTargetLocks("pr-apply", ["web", "api"], holder(2, "plan", "bob"), { cwd: b });
+    expect(lost).toEqual({ ok: false, held: [{ target: "web", ...holder(1, "plan") }] });
+    // B's refused commit is gone: its branch is the remote's, which holds only A's lock.
+    expect(git(b, "rev-parse", "chant/lifecycle")).toBe(git(remote, "rev-parse", "chant/lifecycle"));
+    expect(Object.keys(JSON.parse(git(remote, "show", "chant/lifecycle:_locks/pr-apply.json")).locks)).toEqual(["web"]);
+  });
+});