@intentius/chant 0.122.0 → 0.123.0

package/src/gate-decision.ts

@@ -0,0 +1,321 @@
+/**
+ * A gate's decision for a plan digest, and the seal check it needs, for a
+ * tool that runs from one bundled file (#3763, decision #3756).
+ *
+ * `@intentius/chant/gate-decision` holds what a tool needs to decide a
+ * plan-bound gate the way chant's own wave gate does (`chant run wave`,
+ * `./op/op-waves-run.ts`) under each approval mode:
+ *
+ * - `ledger`: an approval of this digest on `chant/lifecycle`, newer than the
+ *   gate's newest pending fact ({@link decideGateApproval}).
+ * - `sealed`: the same, counting only an approval whose seal verifies for its
+ *   approver against the signers file at base ({@link gateSignersAt},
+ *   {@link gateSealRefusal}). The seal is checked with node:crypto, so the job
+ *   needs no ssh-keygen.
+ * - `pr-review`: the same as `ledger`, or else the merged pull request's
+ *   approving review, when its head planned this digest
+ *   ({@link reviewApproval}).
+ *
+ * With `spend` (#3784), an approval a wave already applied under is spent and
+ * counts for nothing, as terragucci's wave gate has it: the caller hands in
+ * the lines of `_gates/<op>/applied.jsonl` ({@link parseAppliedGateLines}).
+ *
+ * The module reads the ledger lines and the review it is handed; reading
+ * them is the caller's. It imports no TypeScript, esbuild, zod, lint, fold or
+ * codegen module, and none of chant's git ledger code, which
+ * `gate-decision-bundle.test.ts` holds it to. Its rules are chant's own:
+ * `./lifecycle/gate-ledger-select.ts` is what `evaluateGate` decides by, and
+ * `gate-decision.test.ts` decides the same ledgers both ways.
+ */
+
+import { spawnSync } from "node:child_process";
+import {
+  isPendingGateExpired,
+  latestPendingGate,
+  latestResolutionForPlan,
+} from "./lifecycle/gate-ledger-select";
+import { samePlanDigest } from "./lifecycle/plan-digest";
+import { isApprovalSpent, type AppliedGateRecord } from "./lifecycle/gate-applied";
+import { gateSealRefusal, type GateSigners } from "./workspace/trust/gate-seal";
+import {
+  DEFAULT_SIGNERS_PATH,
+  TRUST_CONFIG_PATH,
+  parseAllowedSigners,
+  trustConfigProblems,
+} from "./workspace/trust/trust-files";
+import { parseJsonText } from "./workspace/jsonc";
+import type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
+import type { MergedReview } from "./op/gate-review";
+import type { GateApprovalSource } from "./op/op-waves";
+
+export { GATE_APPROVAL_SOURCES, type GateApprovalSource } from "./op/op-waves";
+export {
+  isPendingGateExpired,
+  latestPendingGate,
+  latestResolutionForPlan,
+  latestResolutionSince,
+  type PlanBoundResolution,
+} from "./lifecycle/gate-ledger-select";
+export {
+  GATE_SEAL_NAMESPACE,
+  gateSealPayload,
+  gateSealRefusal,
+  sshKeyFingerprint,
+  verifySshSignatureWith,
+  type GateSigners,
+  type SealedGateApproval,
+  type SshSignatureCheck,
+} from "./workspace/trust/gate-seal";
+export {
+  DEFAULT_SIGNERS_PATH,
+  TRUST_CONFIG_PATH,
+  parseAllowedSigners,
+  trustConfigProblems,
+  type Signer,
+  type SignerSet,
+} from "./workspace/trust/trust-files";
+export type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
+export {
+  appliedGateApplies,
+  appliedGatePath,
+  isApprovalSpent,
+  parseAppliedGateLines,
+  type AppliedGateRecord,
+} from "./lifecycle/gate-applied";
+export type { MergedReview } from "./op/gate-review";
+
+// ── reading at base ──────────────────────────────────────────────────────
+
+function git(repo: string, args: string[]) {
+  return spawnSync("git", args, { cwd: repo, encoding: "utf-8" });
+}
+
+/** A file's text at `base`, or undefined when `base` holds no file at `path`. */
+function showAt(repo: string, base: string, path: string): string | undefined {
+  const r = git(repo, ["cat-file", "blob", `${base}:${path}`]);
+  return r.status === 0 ? r.stdout : undefined;
+}
+
+/**
+ * The commit a gate's rule is read at when the default branch applies its
+ * own commit: the first parent of HEAD, the branch as it stood before the
+ * merge, so a merge that adds a signer or drops a gate does not judge its own
+ * apply. A shallow checkout fetches that one commit from `origin`. A root
+ * commit has no parent and is its own base. Throws when it cannot be read.
+ */
+export function baseCommit(repo: string): string {
+  const head = git(repo, ["rev-parse", "--verify", "-q", "HEAD^{commit}"]);
+  const sha = head.stdout.trim();
+  if (head.status !== 0 || !sha) throw new Error(`${repo} has no commit checked out, so the gate cannot be decided`);
+  // The commit object's first `parent` line: a shallow clone keeps it even when it lacks the parent itself.
+  const header = git(repo, ["cat-file", "commit", sha]).stdout.split("\n\n")[0] ?? "";
+  const parent = /^parent ([0-9a-f]{40,64})$/m.exec(header)?.[1];
+  if (!parent) return sha;
+  const has = () => git(repo, ["cat-file", "-e", `${parent}^{commit}`]).status === 0;
+  if (!has()) git(repo, ["fetch", "-q", "--depth=1", "origin", parent]);
+  if (!has()) throw new Error(`cannot fetch ${parent.slice(0, 12)}, the commit before this one, so the gate cannot be decided`);
+  return parent;
+}
+
+/**
+ * The signers at `base`: the file `.chant/trust.json` names there, else
+ * `.chant/allowed_signers`, read as chant's trust policy reads it. A
+ * trust.json that is not valid (`trustConfigProblems`) turns attestation
+ * off, as it does in chant, so a sealed gate passes nothing. `base` is a
+ * commit the repository holds, such as {@link baseCommit}'s answer.
+ */
+export function gateSignersAt(repo: string, base: string): GateSigners {
+  const off = (problems: string[]): GateSigners => ({ base, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems });
+  const configText = showAt(repo, base, TRUST_CONFIG_PATH);
+  let signersPath = DEFAULT_SIGNERS_PATH;
+  if (configText !== undefined) {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(configText);
+    } catch (err) {
+      return off([`${TRUST_CONFIG_PATH} is not JSON: ${err instanceof Error ? err.message : String(err)}`]);
+    }
+    const problems = trustConfigProblems(raw);
+    if (problems.length > 0) return off([`${TRUST_CONFIG_PATH} is invalid: ${problems.join("; ")}`]);
+    signersPath = (raw as { signers?: string }).signers ?? DEFAULT_SIGNERS_PATH;
+  }
+  const text = showAt(repo, base, signersPath);
+  return { base, signersPath, active: text !== undefined, signers: text === undefined ? [] : parseAllowedSigners(text).signers, problems: [] };
+}
+
+/** A gate the declaration at base names under `identity.gates`, and the principal class its signer must be in, if any. */
+export interface IdentityGate {
+  gate: string;
+  class: string | null;
+}
+
+/**
+ * The gates `chant.workspace.json` (or `.jsonc`) at `base` names under
+ * `identity.gates`: each counts only a sealed approval, from its class when
+ * it names one. chant checks the class against the role grants at base; this
+ * reads the names. Empty when there is no declaration at base. Throws when
+ * the declaration there cannot be parsed, since the gate cannot be decided.
+ */
+export function identityGatesAt(repo: string, base: string): IdentityGate[] {
+  for (const file of ["chant.workspace.json", "chant.workspace.jsonc"]) {
+    const text = showAt(repo, base, file);
+    if (text === undefined) continue;
+    const parsed = parseJsonText(text, { jsonc: file.endsWith(".jsonc") });
+    if (!parsed.ok) throw new Error(`${file} at base is not valid JSON (${parsed.message}), so the gate cannot be decided`);
+    const gates = (parsed.value as { identity?: { gates?: Record<string, { class?: unknown } | null> } } | null)?.identity?.gates ?? {};
+    return Object.entries(gates).map(([gate, entry]) => ({ gate, class: typeof entry?.class === "string" ? entry.class : null }));
+  }
+  return [];
+}
+
+// ── pr-review ────────────────────────────────────────────────────────────
+
+/** What a pull request's review says about a wave, under `pr-review`. */
+export interface ReviewApproval {
+  approved: boolean;
+  review: { pr?: number; head?: string; approvers?: string[]; url?: string; reason?: string };
+}
+
+/**
+ * Whether the merged pull request's review approves `digest` (#3684): a
+ * writer other than its author approved its head, and the head planned this
+ * digest (`headDigest`, from the plans `chant run wave --record-plans`
+ * recorded for the head; undefined when none were). Reading the review and
+ * the plans is the caller's; under `pr-review` the caller records the
+ * approval on the ledger when this approves.
+ */
+export function reviewApproval(merged: MergedReview, headDigest: string | undefined, digest: string): ReviewApproval {
+  const seen = { pr: merged.pr, head: merged.head, ...(merged.url ? { url: merged.url } : {}) };
+  if (merged.approvers.length === 0) {
+    const why = merged.refused.length > 0 ? merged.refused.join("; ") : "nobody approved it";
+    return { approved: false, review: { ...seen, reason: `no writer other than its author approved the head of #${merged.pr}: ${why}` } };
+  }
+  if (headDigest === undefined) {
+    return {
+      approved: false,
+      review: { ...seen, approvers: merged.approvers, reason: `no plans are recorded for the head ${merged.head.slice(0, 12)} of #${merged.pr} (its pipeline runs \`chant run wave --record-plans\`)` },
+    };
+  }
+  if (headDigest !== digest) {
+    return {
+      approved: false,
+      review: { ...seen, approvers: merged.approvers, reason: `the plan moved after the review: the head planned ${headDigest}, and the merge plans ${digest}` },
+    };
+  }
+  return { approved: true, review: { ...seen, approvers: merged.approvers } };
+}
+
+// ── the decision ─────────────────────────────────────────────────────────
+
+/** The gate ledger lines of one op, as `chant/lifecycle` holds them in `_gates/<op>.jsonl`. */
+export interface GateLedgerLines {
+  resolutions: GateResolutionRecord[];
+  pending: PendingGateRecord[];
+  /** The approvals a wave applied under, from `_gates/<op>/applied.jsonl`. Read only with `spend`. */
+  applied?: AppliedGateRecord[];
+}
+
+export interface GateApprovalInput {
+  ledger: GateLedgerLines;
+  gate: string;
+  /** The digest the gate binds: the plan, or a wave's set digest. */
+  planDigest: string;
+  /** On a component gate, the environment: only its pending facts and approvals count. */
+  environment?: string;
+  /** Which approvals count. Default `ledger`. */
+  mode?: GateApprovalSource;
+  /** The signers at base, which a `sealed` gate checks seals against ({@link gateSignersAt}). Absent under `sealed`, nothing counts. */
+  signers?: GateSigners;
+  /** Another rule an approval must pass, such as chant's `identity.gates` rule: why it does not count, or null. */
+  refuses?: (approval: GateResolutionRecord) => string | null;
+  /** Under `pr-review`, what the merged pull request's review says ({@link reviewApproval}); consulted only when no approval on the ledger counts. */
+  review?: ReviewApproval;
+  /** ISO-8601 now, for whether the standing pending fact has expired. */
+  now?: string;
+  /**
+   * An approval a wave applied under is spent (#3784): it neither passes the
+   * digest again nor stands as the approval of another. Default false.
+   */
+  spend?: boolean;
+}
+
+/** An approval of this gate and digest that a rule did not count, and why. */
+export interface UncountedApproval {
+  resolution: GateResolutionRecord;
+  reason: string;
+}
+
+export type GateApprovalDecision =
+  | { status: "approved"; via: "ledger"; resolution: GateResolutionRecord }
+  | { status: "approved"; via: "pr-review"; review: ReviewApproval["review"] }
+  | {
+      status: "waiting";
+      /** The pending fact that still stands for this digest, unexpired: a caller that records one need not record another. */
+      standing?: PendingGateRecord;
+      /** The newest counted approval of this gate for another digest, or for none: the plan moved since it. */
+      mismatched?: GateResolutionRecord;
+      /** Approvals of this digest the mode or `refuses` did not count, newest last. */
+      uncounted: UncountedApproval[];
+      /** Under `pr-review`, why the review did not approve. */
+      review?: ReviewApproval["review"];
+      /** With `spend`, the newest approval of this gate a wave already applied under, which therefore counted for nothing. */
+      spent?: GateResolutionRecord;
+    };
+
+const EPOCH = new Date(0).toISOString();
+
+/**
+ * Decide a plan-bound gate against its ledger lines, as chant's wave gate
+ * does: an approval counts when it names this gate and digest (and
+ * environment, when set), is newer than the gate's newest pending fact, and
+ * passes the mode's rule: any under `ledger` and `pr-review`, a verified seal
+ * under `sealed`. With none, `pr-review` takes the review's answer. Writes
+ * nothing: recording a pending fact, or the review's approval, is the
+ * caller's.
+ */
+export function decideGateApproval(input: GateApprovalInput): GateApprovalDecision {
+  const { gate, planDigest, environment: env } = input;
+  const mode = input.mode ?? "ledger";
+  const pending = env === undefined ? input.ledger.pending : input.ledger.pending.filter((p) => p.environment === env);
+  const mine = (env === undefined ? input.ledger.resolutions : input.ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env)).filter(
+    (r) => r.gate === gate,
+  );
+  const sealed = mode === "sealed";
+  const noSigners: GateSigners = { base: null, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems: ["no signers were read for this sealed gate"] };
+  const why = (r: GateResolutionRecord): string | null =>
+    input.refuses?.(r) ?? (sealed ? gateSealRefusal(input.signers ?? noSigners, r) : null);
+
+  const standingFact = latestPendingGate(pending, gate);
+  const since = standingFact?.timestamp ?? EPOCH;
+  const counted: GateResolutionRecord[] = [];
+  const uncounted: UncountedApproval[] = [];
+  let spent: GateResolutionRecord | undefined;
+  for (const r of mine) {
+    if (input.spend && isApprovalSpent(input.ledger.applied ?? [], r)) {
+      if (new Date(r.timestamp).getTime() >= new Date(since).getTime() && (!spent || new Date(r.timestamp).getTime() >= new Date(spent.timestamp).getTime())) spent = r;
+      continue;
+    }
+    const reason = why(r);
+    if (reason === null) counted.push(r);
+    else if (samePlanDigest(r.planDigest, planDigest) && new Date(r.timestamp).getTime() >= new Date(since).getTime()) uncounted.push({ resolution: r, reason });
+  }
+  const found = latestResolutionForPlan(counted, gate, since, planDigest);
+  if (found.resolution) return { status: "approved", via: "ledger", resolution: found.resolution };
+  const reviewSpent =
+    input.spend === true && input.review?.approved === true &&
+    isApprovalSpent(input.ledger.applied ?? [], { gate, planDigest, review: { ...(input.review.review.head ? { head: input.review.review.head } : {}) } });
+  if (mode === "pr-review" && input.review?.approved && !reviewSpent) return { status: "approved", via: "pr-review", review: input.review.review };
+
+  const now = input.now ?? new Date().toISOString();
+  const standing = standingFact && !isPendingGateExpired(standingFact, now) && samePlanDigest(standingFact.planDigest, planDigest) ? standingFact : undefined;
+  return {
+    status: "waiting",
+    ...(standing ? { standing } : {}),
+    ...(found.mismatched ? { mismatched: found.mismatched } : {}),
+    uncounted: uncounted.sort((a, b) => new Date(a.resolution.timestamp).getTime() - new Date(b.resolution.timestamp).getTime()),
+    ...(mode === "pr-review" && input.review
+      ? { review: reviewSpent ? { ...input.review.review, reason: `a wave already applied this digest under the review of ${input.review.review.head?.slice(0, 12) ?? "its head"}, so the review is spent` } : input.review.review }
+      : {}),
+    ...(spent ? { spent } : {}),
+  };
+}

package/src/lifecycle/gate-applied.ts

@@ -0,0 +1,115 @@
+/**
+ * The approvals a wave applied under, and the rule that spends them (#3784).
+ *
+ * terragucci's wave gate writes one line to `_gates/<op>/applied.jsonl` on
+ * `chant/lifecycle` before a wave applies under an approval: the gate, the
+ * digest, and the approval's own timestamp. From then on that approval is
+ * spent. It does not let the same digest through again, and it no longer
+ * stands as the approval of another digest either. Op waves write the same
+ * line, in the same file, when their spec sets `approvals.spend`, and
+ * `decideGateApproval` (`../gate-decision.ts`) and `evaluateGate`
+ * (`../op/gate.ts`) take the lines to leave spent approvals out.
+ *
+ * The file sits in a directory under `_gates/`, so the readers of
+ * `_gates/<op>.jsonl` never see its lines. {@link appliedGateApplies} hands
+ * them to `gate-audit` as applies, each tied to the approval it ran under.
+ *
+ * Pure: no git, no clock, no file. It bundles into `@intentius/chant/gate-decision`.
+ */
+
+import { samePlanDigest } from "./plan-digest";
+import type { GateAuditApply } from "./gate-audit";
+
+/** One approval a wave applied under: the approval of `planDigest` made at `approvedAt` was used. */
+export interface AppliedGateRecord {
+  version: 1;
+  kind: "applied";
+  op: string;
+  gate: string;
+  planDigest: string;
+  /** The approval's own timestamp, as the ledger holds it. Every approval of this gate and digest at or before it is spent. */
+  approvedAt: string;
+  approvedBy: string;
+  /** When the wave recorded it, just before it applied. */
+  timestamp: string;
+  /** The wave, by number and name, for an Op waves record. */
+  wave?: { number: number; name: string };
+  /** The pull request review the approval came from, under `pr-review`. */
+  review?: { pr?: number; head?: string };
+  runId?: string;
+  commit?: string;
+}
+
+/** Where the applied lines of `op` live on `chant/lifecycle`: the directory and the file, as `writeBlobToPath` takes them. */
+export function appliedGatePath(op: string): { dir: string; file: string } {
+  return { dir: `_gates/${op}`, file: "applied.jsonl" };
+}
+
+/** The applied lines of an `applied.jsonl` file, oldest first. A line that is not one is skipped. */
+export function parseAppliedGateLines(text: string): AppliedGateRecord[] {
+  const out: AppliedGateRecord[] = [];
+  for (const line of text.split("\n").map((l) => l.trim()).filter(Boolean)) {
+    let r: Record<string, unknown>;
+    try {
+      r = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (
+      r?.version === 1 && r.kind === "applied" && typeof r.op === "string" && typeof r.gate === "string" &&
+      typeof r.planDigest === "string" && typeof r.approvedAt === "string" && typeof r.timestamp === "string"
+    ) {
+      out.push({ approvedBy: "", ...r } as unknown as AppliedGateRecord);
+    }
+  }
+  return out;
+}
+
+const time = (iso: string): number => new Date(iso).getTime();
+
+/**
+ * Whether an approval is spent: a wave applied under an approval of the same
+ * gate and digest made at or after it. One that names no digest is never
+ * spent. With `review`, an approval that came from a pull request's review
+ * is spent too when a wave applied this digest under a review of the same
+ * head, so the review cannot be recorded again to pass the digest twice. A
+ * review not yet recorded has no `timestamp`.
+ */
+export function isApprovalSpent(
+  applied: readonly AppliedGateRecord[],
+  approval: { gate: string; planDigest?: string; timestamp?: string; review?: { pr?: number; head?: string } },
+): boolean {
+  const digest = approval.planDigest;
+  if (digest === undefined) return false;
+  return applied.some(
+    (a) =>
+      a.gate === approval.gate &&
+      samePlanDigest(a.planDigest, digest) &&
+      ((approval.timestamp !== undefined && time(a.approvedAt) >= time(approval.timestamp)) ||
+        (approval.review?.head !== undefined && a.review?.head === approval.review.head)),
+  );
+}
+
+/**
+ * The applied lines as `gate-audit` applies: each an `applied` entry tied to
+ * the approval it ran under. `ref` names the file, `_gates/<op>/applied.jsonl`
+ * by default; each line's index is appended so ids stay stable.
+ */
+export function appliedGateApplies(records: readonly AppliedGateRecord[], ref?: string): GateAuditApply[] {
+  return records.map((r, i) => ({
+    ref: `${ref ?? `_gates/${r.op}/applied.jsonl`}#${i + 1}`,
+    at: r.timestamp,
+    gate: r.gate,
+    op: r.op,
+    digest: r.planDigest,
+    approval: "required" as const,
+    detail: {
+      approvedAt: r.approvedAt,
+      approvedBy: r.approvedBy,
+      ...(r.wave ? { wave: r.wave } : {}),
+      ...(r.review ? { review: r.review } : {}),
+      ...(r.runId ? { runId: r.runId } : {}),
+      ...(r.commit ? { commit: r.commit } : {}),
+    },
+  }));
+}

package/src/lifecycle/gate-audit-bundle.test.ts

@@ -0,0 +1,47 @@
+/**
+ * The gate audit reader bundles small (#3764, ruling #3421).
+ *
+ * terragucci and SQL Yodeler derive their audit trail from the gate ledger in
+ * one bundled file, with no TypeScript toolchain. So `@intentius/chant/lifecycle/gate-audit`
+ * must not reach `typescript`, esbuild, zod, git, or chant's fold, lint and
+ * codegen modules. This bundles it the way a product would and reads
+ * esbuild's own list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "../workspace/__fixtures__/contract-repo";
+
+const BUDGET_BYTES = 32 * 1024;
+
+const FORBIDDEN = [/node_modules\//, /\/src\/fold\//, /\/src\/lint\//, /\/src\/codegen\//, /\/src\/workspace\//, /\/lifecycle\/git\.ts$/, /\/lifecycle\/gate-ledger\.ts$/, /\/op\//];
+
+describe("the gate audit bundle", () => {
+  test("holds the reader, the digest comparison and nothing heavier", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "lifecycle", "gate-audit.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    for (const pattern of FORBIDDEN) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/content-digest.ts",
+      "packages/core/src/declarable.ts",
+      "packages/core/src/effect-receipt.ts",
+      "packages/core/src/intrinsic.ts",
+      "packages/core/src/lifecycle/gate-audit.ts",
+      "packages/core/src/lifecycle/plan-digest.ts",
+    ]);
+    const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+    expect(bytes).toBeLessThan(BUDGET_BYTES);
+  });
+});

package/src/lifecycle/gate-audit.test.ts

@@ -0,0 +1,134 @@
+import { describe, test, expect } from "vitest";
+import { deriveGateAudit, gateLedgerLines, gateLedgerLinesFromLog, readGateAuditLedgers, isOverrideGate } from "./gate-audit";
+import { memoryGateLedgerPort } from "../op/gate";
+
+const D1 = "jcs1-sha256:" + "a".repeat(64);
+const D2 = "jcs1-sha256:" + "b".repeat(64);
+
+const pending = (o: Record<string, unknown> = {}) =>
+  JSON.stringify({ version: 1, kind: "pending", op: "tf-apply", gate: "wave-1", timestamp: "2026-10-01T10:00:00.000Z", expiresAt: "2026-10-03T10:00:00.000Z", planDigest: D1, runId: "r1", ...o });
+const resolution = (o: Record<string, unknown> = {}) =>
+  JSON.stringify({ version: 1, op: "tf-apply", gate: "wave-1", resolvedBy: "alex", timestamp: "2026-10-01T11:00:00.000Z", planDigest: D1, ...o });
+const ledger = (op: string, ...texts: string[]) => ({ op, lines: texts.map((text) => ({ text })) });
+
+describe("lifecycle/gate-audit", () => {
+  test("a request, then an approval with its seal and approver", () => {
+    const seal = { signer: "alex", key: "SHA256:k", signature: "-----BEGIN" };
+    const { entries, gaps } = deriveGateAudit({
+      ledgers: [ledger("tf-apply", pending(), resolution({ seal, relayedBy: "slack", note: "ok", approver: { kind: "human", roles: ["ops"] }, via: "relay" }))],
+    });
+    expect(gaps).toEqual([]);
+    expect(entries.map((e) => e.kind)).toEqual(["approval-requested", "approved"]);
+    expect(entries[0]).toMatchObject({ gate: "wave-1", digest: D1, runId: "r1", expiresAt: "2026-10-03T10:00:00.000Z" });
+    expect(entries[1]).toMatchObject({ by: "alex", seal: "sealed", signer: "alex", relayedBy: "slack", note: "ok", approver: { kind: "human", roles: ["ops"] }, detail: { via: "relay" } });
+  });
+
+  test("ids are stable and differ per line", () => {
+    const input = { ledgers: [ledger("tf-apply", pending(), resolution())] };
+    const a = deriveGateAudit(input).entries;
+    const b = deriveGateAudit(input).entries;
+    expect(a.map((e) => e.id)).toEqual(b.map((e) => e.id));
+    expect(new Set(a.map((e) => e.id)).size).toBe(2);
+  });
+
+  test("a pull request review counts as signed; a bare approval is unsigned", () => {
+    const review = { pr: 7, head: "abc", approvers: ["bo"] };
+    const { entries } = deriveGateAudit({ ledgers: [ledger("tf-apply", pending(), resolution({ review }), resolution({ timestamp: "2026-10-01T12:00:00.000Z" }))] });
+    expect(entries.filter((e) => e.kind === "approved").map((e) => e.seal)).toEqual(["review", "unsigned"]);
+    expect(entries.find((e) => e.seal === "review")?.review).toEqual(review);
+  });
+
+  test("an approval with no pending fact before it is a gap, also when the digest differs or the fact is later", () => {
+    const none = deriveGateAudit({ ledgers: [ledger("tf-apply", resolution())] });
+    expect(none.gaps.map((g) => g.kind)).toEqual(["approval-without-request"]);
+    const other = deriveGateAudit({ ledgers: [ledger("tf-apply", pending({ planDigest: D2 }), resolution())] });
+    expect(other.gaps.map((g) => g.kind)).toEqual(["approval-without-request"]);
+    const later = deriveGateAudit({ ledgers: [ledger("tf-apply", resolution({ timestamp: "2026-10-01T09:00:00.000Z" }), pending())] });
+    expect(later.gaps.map((g) => g.kind)).toEqual(["approval-without-request"]);
+    const old = deriveGateAudit({ ledgers: [ledger("tf-apply", pending({ planDigest: undefined }), resolution())] });
+    expect(old.gaps).toEqual([]);
+  });
+
+  test("the sealed option flags an unsigned approval and not a sealed or reviewed one", () => {
+    const { gaps } = deriveGateAudit({
+      ledgers: [ledger("tf-apply", pending(), resolution(), resolution({ review: { pr: 1 } }))],
+      sealed: (op) => op === "tf-apply",
+    });
+    expect(gaps.map((g) => g.kind)).toEqual(["unsealed"]);
+  });
+
+  test("overrides: terragucci's denial and SQL Yodeler's override gate", () => {
+    const denial = pending({ op: "policy-override", gate: "root/a", planDigest: "sha256:ov", rules: ["r1", "r2"], members: [{ member: "root/a", planDigest: D1 }] });
+    const rec = resolution({ op: "policy-override", gate: "root/a", planDigest: "sha256:ov", note: "freeze exception" });
+    const yodel = resolution({ op: "migrate", gate: "override-no-drop", note: "legacy table" });
+    const { entries, gaps } = deriveGateAudit({ ledgers: [ledger("policy-override", denial, rec), ledger("migrate", yodel)] });
+    expect(gaps).toEqual([]);
+    expect(entries.map((e) => e.kind)).toEqual(["override-requested", "override-recorded", "override-recorded"]);
+    const recorded = entries.filter((e) => e.kind === "override-recorded");
+    expect(recorded[0]).toMatchObject({ note: "freeze exception", rules: ["r1", "r2"] });
+    expect(recorded[1]).toMatchObject({ note: "legacy table", rules: ["no-drop"] });
+    expect(entries.find((e) => e.kind === "override-requested")?.detail).toMatchObject({ members: [{ member: "root/a", planDigest: D1 }] });
+  });
+
+  test("a removed line is a revocation by whoever removed it", () => {
+    const log = [
+      `\x1ec1\x1falex\x1f2026-10-01T11:00:00+00:00\n\ndiff --git a/x b/x\n+${resolution()}\n`,
+      `\x1ec2\x1fbo\x1f2026-10-02T08:00:00+00:00\n\ndiff --git a/x b/x\n-${resolution()}\n`,
+      `\x1ec3\x1fcy\x1f2026-10-02T09:00:00+00:00\n\ndiff --git a/x b/x\n-${pending({ gate: "gone" })}\n+${pending({ gate: "gone" })}\n`,
+    ].join("");
+    const lines = gateLedgerLinesFromLog(log);
+    expect(lines).toHaveLength(2);
+    const { entries } = deriveGateAudit({ ledgers: [{ op: "tf-apply", lines: [{ text: pending() }, ...lines] }] });
+    const revoked = entries.find((e) => e.kind === "revoked")!;
+    expect(revoked).toMatchObject({ by: "bo", at: "2026-10-02T08:00:00.000Z", subject: "approval", detail: { approvedBy: "alex" } });
+    expect(entries.filter((e) => e.kind === "approved")).toHaveLength(1);
+  });
+
+  test("applies: under an approval, without one, waived, and spending an override", () => {
+    const ledgers = [ledger("tf-apply", pending(), resolution()), ledger("policy-override", resolution({ op: "policy-override", gate: "root/a", planDigest: "sha256:ov" }))];
+    const ok = { ref: "reports/1", at: "2026-10-01T12:00:00.000Z", gate: "wave-1", digest: D1 };
+    const { entries, gaps } = deriveGateAudit({
+      ledgers,
+      applies: [
+        ok,
+        { ...ok, ref: "reports/2", digest: D2 },
+        { ...ok, ref: "reports/3", digest: D2, approval: "not-required" },
+        { ...ok, ref: "reports/4", digest: undefined },
+        { ...ok, ref: "reports/5", at: "2026-10-01T10:30:00.000Z" },
+        { ...ok, ref: "reports/6", overrides: [{ gate: "root/a", digest: "sha256:ov" }, { gate: "root/b" }] },
+      ],
+    });
+    expect(gaps.map((g) => [g.kind, g.detail.split(" ")[0]])).toEqual([
+      ["approval", "reports/2"],
+      ["approval", "reports/5"],
+      ["override", "reports/6"],
+    ]);
+    const approved = entries.find((e) => e.kind === "approved")!;
+    expect(entries.filter((e) => e.kind === "applied" && e.under === approved.id)).toHaveLength(2);
+    const spent = entries.filter((e) => e.kind === "override-spent");
+    expect(spent).toHaveLength(1);
+    expect(spent[0]).toMatchObject({ gate: "root/a", by: "alex", at: "2026-10-01T12:00:00.000Z" });
+  });
+
+  test("malformed lines are gaps and never entries", () => {
+    const { entries, gaps } = deriveGateAudit({ ledgers: [ledger("tf-apply", "{nope", JSON.stringify({ version: 2, gate: "g", timestamp: "t" }), pending())] });
+    expect(entries).toHaveLength(1);
+    expect(gaps.map((g) => g.kind)).toEqual(["malformed-line", "malformed-line"]);
+  });
+
+  test("the override rule is replaceable", () => {
+    const { entries } = deriveGateAudit({ ledgers: [ledger("x", resolution({ op: "x", gate: "ovr/a" }))], isOverride: (_op, gate) => gate.startsWith("ovr/") });
+    expect(entries[0]?.kind).toBe("override-recorded");
+    expect(isOverrideGate("policy-override", "r")).toBe(true);
+    expect(isOverrideGate("a", "b")).toBe(false);
+  });
+
+  test("gateLedgerLines and the port reader feed the same derivation", async () => {
+    const text = `${pending()}\n\n${resolution()}\n`;
+    const port = memoryGateLedgerPort({ pending: [JSON.parse(pending())], resolutions: [JSON.parse(resolution())] });
+    const fromText = deriveGateAudit({ ledgers: [{ op: "tf-apply", lines: gateLedgerLines(text) }] });
+    const fromPort = deriveGateAudit({ ledgers: await readGateAuditLedgers(port, ["tf-apply"]) });
+    expect(fromPort.entries.map((e) => e.kind)).toEqual(["approval-requested", "approved"]);
+    expect(fromPort.entries.map((e) => e.at)).toEqual(fromText.entries.map((e) => e.at));
+  });
+});