@intentius/chant 0.122.0 → 0.123.0

package/src/lifecycle/gate-audit.ts

@@ -0,0 +1,438 @@
+/**
+ * An audit trail from the gate ledger (#3764, decision #3756). Pure: ledger
+ * lines (and, if the product has them, the applies that ran under a gate) go
+ * in; typed entries and the gaps they show come out. It reads no git, no
+ * clock and no file, so it bundles into a product's single CI file
+ * (`gate-audit-bundle.test.ts` holds the import graph).
+ *
+ * Both products derived this themselves: terragucci's `report/audit.ts` and
+ * SQL Yodeler's `report/audit.ts` each parse `_gates/<op>.jsonl`. Storage
+ * (an append-only record, a bucket, a history table) and rendering stay with
+ * them.
+ *
+ * ## Entries
+ *
+ * | kind                 | source line                                                      |
+ * |----------------------|------------------------------------------------------------------|
+ * | `approval-requested` | a pending fact of a gate that is not an override                 |
+ * | `approved`           | a resolution of such a gate (seal, approver, review, relay)      |
+ * | `override-requested` | a pending fact of an override gate: a denial that waits          |
+ * | `override-recorded`  | a resolution of an override gate (reason in `note`)              |
+ * | `revoked`            | a resolution a commit removed from the file (`subject` says which) |
+ * | `applied`            | an apply the caller passes in, with the approval it ran under    |
+ * | `override-spent`     | an override an apply the caller passes in cites                  |
+ *
+ * An override gate is, by default, any gate of the op `policy-override`
+ * (terragucci writes one gate per root) or named `override-<rule>` (SQL
+ * Yodeler's `yodel override`). chant's override gate (#3760,
+ * `../override-gate.ts`) records under the op `policy-override`, so the
+ * default reads it, and its `overrideAuditApplies` turns applied records into
+ * applies that cite the override they spent. {@link GateAuditOptions.isOverride}
+ * replaces the rule. Anything a line carries beyond the typed fields is kept in
+ * `detail`, and `kind` is checked against {@link GATE_AUDIT_KINDS} only by
+ * the type, never by the reader.
+ *
+ * ## Gaps
+ *
+ * - `approval-without-request`: a resolution with no pending fact of its gate
+ *   before it (or none for its digest). Overrides are exempt: both products
+ *   may record one without a denial on file.
+ * - `unsealed`: an approval or override with neither a seal nor a pull
+ *   request review, where {@link GateAuditOptions.sealed} says the gate needs
+ *   one.
+ * - `approval`: an apply with a digest that no approval of its gate holds
+ *   for that digest, recorded at or before the apply. Needs `approval:
+ *   "not-required"` to be waived, as a baseline or a policy that asked for
+ *   no approval does.
+ * - `override`: an apply cites an override that no line holds.
+ * - `malformed-line`: a line that is not a gate record. Its content is lost
+ *   to the trail, so it is said.
+ */
+import { canonicalJson } from "../effect-receipt";
+import { contentDigest } from "../content-digest";
+import { samePlanDigest } from "./plan-digest";
+import type { GateLedgerPort } from "../op/gate";
+
+export const GATE_AUDIT_KINDS = [
+  "approval-requested",
+  "approved",
+  "override-requested",
+  "override-recorded",
+  "revoked",
+  "applied",
+  "override-spent",
+] as const;
+export type GateAuditKind = (typeof GATE_AUDIT_KINDS)[number];
+
+/** How an approval was authenticated: an ssh seal, a forge review, or neither. */
+export type GateAuditSeal = "sealed" | "review" | "unsigned";
+
+/**
+ * One line of a ledger file. Give the `text` as it is on disk, or the parsed
+ * `record` a {@link GateLedgerPort} returns. A line a commit removed carries
+ * `removed`, with when and by whom (the commit's date and author).
+ */
+export interface GateLedgerLine {
+  text?: string;
+  record?: unknown;
+  commit?: string;
+  removed?: { at: string; by?: string };
+}
+
+/** One op's ledger file. */
+export interface GateAuditLedger {
+  op: string;
+  /** For the entries' source, such as `_gates/<op>.jsonl`. Default that. */
+  path?: string;
+  /** Oldest first. */
+  lines: readonly GateLedgerLine[];
+}
+
+/** An apply, from the product's own records (a wave report, a history row). */
+export interface GateAuditApply {
+  /** Where it was recorded: a report path, a history row. Goes into the id, so the same source gives the same id. */
+  ref: string;
+  at: string;
+  /** The gate it ran under. */
+  gate: string;
+  /** Narrows the approval to one ledger. Default any. */
+  op?: string;
+  /** The plan digest it applied. Without one (a baseline) no approval is looked for. */
+  digest?: string;
+  by?: string;
+  /** `not-required` when a policy at base let it through with no approval. Default `required`. */
+  approval?: "required" | "not-required";
+  /** Overrides it was let through by. */
+  overrides?: ReadonlyArray<{ gate: string; digest?: string }>;
+  detail?: Record<string, unknown>;
+}
+
+export interface GateAuditSource {
+  /** The ledger file, or the apply's `ref` for an apply. */
+  path: string;
+  op?: string;
+  commit?: string;
+  change: "added" | "removed" | "apply";
+}
+
+export interface GateAuditEntry {
+  /** `sha256:` over where the entry came from: the same sources give the same id. */
+  id: string;
+  kind: GateAuditKind;
+  /** When it happened: the line's timestamp, the removing commit's date, or the apply's. */
+  at: string;
+  gate: string;
+  op?: string;
+  /** The plan digest the line binds. */
+  digest?: string;
+  /** Who: the approver or overrider, whoever removed the line, or for an apply, whoever ran it. */
+  by?: string;
+  /** Resolutions and revocations: sealed, reviewed, or unsigned. */
+  seal?: GateAuditSeal;
+  /** The ssh signer, when sealed. */
+  signer?: string;
+  /** Who carried the approval to chant (`chant approve --relayed-by`). */
+  relayedBy?: string;
+  /** A person or an agent, and the roles claimed. */
+  approver?: { kind: string; roles?: string[] };
+  /** The free text: an override's reason, an approval's note. */
+  note?: string;
+  url?: string;
+  /** The forge review an approval came from. */
+  review?: { pr?: number; head?: string; approvers?: string[] };
+  /** Pending facts: the run that reached the gate, when it expires, what it describes. */
+  runId?: string;
+  expiresAt?: string;
+  description?: string;
+  /** Overrides: the rules the denial named (from the denial line when there is one). */
+  rules?: string[];
+  /** A revoked entry: what was revoked. */
+  subject?: "approval" | "override";
+  /** An applied entry: the approval entry it ran under, if one is held. An override-spent entry: the override entry. */
+  under?: string;
+  /** Everything else the line carries, such as `members`, `via` or a product's own fields. */
+  detail: Record<string, unknown>;
+  source: GateAuditSource;
+}
+
+export interface GateAuditGap {
+  kind: "approval-without-request" | "unsealed" | "approval" | "override" | "malformed-line";
+  op?: string;
+  gate?: string;
+  digest?: string;
+  detail: string;
+}
+
+export interface GateAuditOptions {
+  /** Whether a gate is an override gate. Default: op `policy-override`, or a gate named `override-...`. */
+  isOverride?: (op: string, gate: string) => boolean;
+  /** Whether approvals of a gate need a seal or a review. Default none. */
+  sealed?: (op: string, gate: string) => boolean;
+}
+
+export interface GateAuditInput extends GateAuditOptions {
+  ledgers: readonly GateAuditLedger[];
+  applies?: readonly GateAuditApply[];
+}
+
+export const POLICY_OVERRIDE_OP = "policy-override";
+
+/** The default {@link GateAuditOptions.isOverride}. */
+export function isOverrideGate(op: string, gate: string): boolean {
+  return op === POLICY_OVERRIDE_OP || gate.startsWith("override-");
+}
+
+type Row = Record<string, unknown>;
+
+const KNOWN = new Set([
+  "version", "kind", "op", "gate", "resolvedBy", "relayedBy", "timestamp", "note", "url", "planDigest", "environment",
+  "approver", "seal", "review", "runId", "expiresAt", "description", "rules", "pr", "head", "reviewers",
+]);
+
+const str = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : undefined);
+const strings = (v: unknown): string[] | undefined => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : undefined);
+const time = (iso: string): number => Date.parse(iso) || 0;
+
+function rowOf(line: GateLedgerLine): Row | undefined {
+  let v: unknown = line.record;
+  if (v === undefined && line.text !== undefined) {
+    try {
+      v = JSON.parse(line.text);
+    } catch {
+      return undefined;
+    }
+  }
+  return v && typeof v === "object" && !Array.isArray(v) ? (v as Row) : undefined;
+}
+
+function sealOf(r: Row): { seal: GateAuditSeal; signer?: string } {
+  const s = r.seal as { signature?: unknown; signer?: unknown } | null | undefined;
+  if (s && s.signature) return { seal: "sealed", ...(str(s.signer) ? { signer: str(s.signer) } : {}) };
+  if (r.review || r.via === "pr-review") return { seal: "review" };
+  return { seal: "unsigned" };
+}
+
+function reviewOf(r: Row): GateAuditEntry["review"] {
+  const rv = (r.review ?? undefined) as Row | undefined;
+  const pr = typeof rv?.pr === "number" ? rv.pr : typeof r.pr === "number" ? r.pr : undefined;
+  const head = str(rv?.head) ?? str(r.head);
+  const approvers = strings(rv?.approvers) ?? strings(r.reviewers);
+  if (pr === undefined && head === undefined && approvers === undefined) return undefined;
+  return { ...(pr !== undefined ? { pr } : {}), ...(head ? { head } : {}), ...(approvers ? { approvers } : {}) };
+}
+
+function approverOf(r: Row): GateAuditEntry["approver"] {
+  const a = r.approver as { kind?: unknown; roles?: unknown } | undefined;
+  if (!a || typeof a.kind !== "string") return undefined;
+  const roles = strings(a.roles);
+  return { kind: a.kind, ...(roles ? { roles } : {}) };
+}
+
+const drop = <T extends object>(o: T): T => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as T;
+
+const idOf = (...parts: unknown[]): string => contentDigest(canonicalJson(parts));
+
+interface Seen {
+  op: string;
+  gate: string;
+  at: number;
+  digest?: string;
+  environment?: string;
+}
+
+/** Whether two digests, either absent, can be the same plan: absent matches anything, as an old line records none. */
+const compatible = (a: string | undefined, b: string | undefined): boolean => a === undefined || b === undefined || samePlanDigest(a, b);
+
+/** The entries `input` adds up to, oldest first, and the gaps they show. */
+export function deriveGateAudit(input: GateAuditInput): { entries: GateAuditEntry[]; gaps: GateAuditGap[] } {
+  const isOverride = input.isOverride ?? isOverrideGate;
+  const entries: GateAuditEntry[] = [];
+  const gaps: GateAuditGap[] = [];
+
+  for (const ledger of input.ledgers) {
+    const path = ledger.path ?? `_gates/${ledger.op}.jsonl`;
+    const parsed: { line: GateLedgerLine; r: Row; pending: boolean }[] = [];
+    for (const line of ledger.lines) {
+      const r = rowOf(line);
+      const pending = r?.kind === "pending";
+      const ok = r && r.version === 1 && typeof r.gate === "string" && typeof r.timestamp === "string" && (pending || typeof r.resolvedBy === "string");
+      if (!r || !ok) {
+        gaps.push({ kind: "malformed-line", op: ledger.op, detail: `${path} holds a line that is not a gate record${line.commit ? ` (commit ${line.commit})` : ""}: ${(line.text ?? JSON.stringify(line.record) ?? "").slice(0, 80)}` });
+        continue;
+      }
+      parsed.push({ line, r, pending });
+    }
+
+    // Each denial an override answers: the newest pending fact of its gate and digest.
+    const denials = new Map<string, Row>();
+    const requests: Seen[] = [];
+    for (const p of parsed) {
+      if (!p.pending || p.line.removed) continue;
+      const digest = str(p.r.planDigest);
+      denials.set(`${String(p.r.gate)}\n${digest ?? ""}`, p.r);
+      requests.push({ op: ledger.op, gate: String(p.r.gate), at: time(String(p.r.timestamp)), ...(digest ? { digest } : {}), ...(str(p.r.environment) ? { environment: str(p.r.environment) } : {}) });
+    }
+
+    for (const { line, r, pending } of parsed) {
+      const gate = String(r.gate);
+      const override = isOverride(ledger.op, gate);
+      const removed = line.removed;
+      if (pending && removed) continue;
+      const digest = str(r.planDigest);
+      const source: GateAuditSource = { path, op: ledger.op, ...(line.commit ? { commit: line.commit } : {}), change: removed ? "removed" : "added" };
+      const id = idOf(removed ? "removed" : "ledger", path, line.commit ?? null, r);
+      const extra = Object.fromEntries(Object.entries(r).filter(([k]) => !KNOWN.has(k)));
+      const base = { id, gate, op: ledger.op, ...(digest ? { digest } : {}), source } as const;
+
+      if (pending) {
+        entries.push({
+          ...base,
+          kind: override ? "override-requested" : "approval-requested",
+          at: String(r.timestamp),
+          ...drop({ runId: str(r.runId), expiresAt: str(r.expiresAt), description: str(r.description), url: str(r.url), rules: strings(r.rules) }),
+          detail: extra,
+        });
+        continue;
+      }
+
+      const { seal, signer } = sealOf(r);
+      if (removed) {
+        entries.push({
+          ...base,
+          kind: "revoked",
+          at: removed.at,
+          ...(removed.by ? { by: removed.by } : {}),
+          subject: override ? "override" : "approval",
+          seal,
+          detail: { ...extra, approvedBy: r.resolvedBy, approvedAt: r.timestamp, ...(signer ? { signer } : {}) },
+        });
+        continue;
+      }
+
+      const denial = override ? denials.get(`${gate}\n${digest ?? ""}`) : undefined;
+      const rules = strings(denial?.rules) ?? (override && gate.startsWith("override-") ? [gate.slice("override-".length)] : undefined);
+      const entry: GateAuditEntry = {
+        ...base,
+        kind: override ? "override-recorded" : "approved",
+        at: String(r.timestamp),
+        by: String(r.resolvedBy),
+        seal,
+        ...drop({ signer, relayedBy: str(r.relayedBy), approver: approverOf(r), note: str(r.note), url: str(r.url), review: reviewOf(r), rules }),
+        detail: extra,
+      };
+      entries.push(entry);
+
+      if (!override) {
+        const at = time(entry.at);
+        const env = str(r.environment);
+        const asked = requests.some((q) => q.gate === gate && q.at <= at && compatible(q.digest, digest) && (q.environment === undefined || env === undefined || q.environment === env));
+        if (!asked) {
+          gaps.push({ kind: "approval-without-request", op: ledger.op, gate, ...(digest ? { digest } : {}), detail: `${path} holds an approval of ${gate} by ${entry.by} at ${entry.at} with no pending fact of that gate${digest ? " and digest" : ""} before it` });
+        }
+      }
+      if (seal === "unsigned" && input.sealed?.(ledger.op, gate)) {
+        gaps.push({ kind: "unsealed", op: ledger.op, gate, ...(digest ? { digest } : {}), detail: `${path} holds ${override ? "an override" : "an approval"} of ${gate} by ${entry.by} at ${entry.at} with no seal and no review, and the gate needs one` });
+      }
+    }
+  }
+
+  const held = entries.filter((e) => e.kind === "approved" || e.kind === "override-recorded");
+  for (const a of input.applies ?? []) {
+    const base = { gate: a.gate, ...(a.op ? { op: a.op } : {}), ...(a.digest ? { digest: a.digest } : {}), source: { path: a.ref, ...(a.op ? { op: a.op } : {}), change: "apply" as const } };
+    const at = time(a.at);
+    const find = (kind: GateAuditKind, gate: string, digest: string | undefined, before: boolean): GateAuditEntry | undefined =>
+      held
+        .filter((e) => e.kind === kind && e.gate === gate && (a.op === undefined || e.op === a.op) && (digest === undefined ? true : e.digest !== undefined && samePlanDigest(e.digest, digest)) && (!before || time(e.at) <= at))
+        .sort((x, y) => time(y.at) - time(x.at))[0];
+
+    const approval = a.digest !== undefined && a.approval !== "not-required" ? find("approved", a.gate, a.digest, true) : undefined;
+    if (a.digest !== undefined && a.approval !== "not-required" && !approval) {
+      gaps.push({ kind: "approval", ...(a.op ? { op: a.op } : {}), gate: a.gate, digest: a.digest, detail: `${a.ref} applied under ${a.digest}, but the ledger holds no approval of ${a.gate} for that digest before ${a.at}` });
+    }
+    entries.push({
+      ...base,
+      id: idOf("apply", a.ref, a.at, a.gate, a.digest ?? null),
+      kind: "applied",
+      at: a.at,
+      ...(a.by ? { by: a.by } : {}),
+      ...(approval ? { under: approval.id } : {}),
+      detail: { ...(a.detail ?? {}), approval: a.approval ?? "required" },
+    });
+
+    for (const o of a.overrides ?? []) {
+      const recorded = find("override-recorded", o.gate, o.digest, false);
+      if (!recorded) {
+        gaps.push({ kind: "override", ...(a.op ? { op: a.op } : {}), gate: o.gate, ...(o.digest ? { digest: o.digest } : {}), detail: `${a.ref} cites the override ${o.gate}${o.digest ? ` for ${o.digest}` : ""}, but the ledger holds none` });
+        continue;
+      }
+      entries.push({
+        ...base,
+        id: idOf("spent", a.ref, a.at, recorded.id),
+        kind: "override-spent",
+        gate: o.gate,
+        at: a.at,
+        ...(recorded.by ? { by: recorded.by } : {}),
+        ...(recorded.digest ? { digest: recorded.digest } : {}),
+        under: recorded.id,
+        detail: {},
+      });
+    }
+  }
+
+  entries.sort((x, y) => time(x.at) - time(y.at));
+  return { entries, gaps };
+}
+
+/** The lines of one ledger file's text, all added. Blank lines are skipped. */
+export function gateLedgerLines(content: string): GateLedgerLine[] {
+  return content.split("\n").map((l) => l.trim()).filter(Boolean).map((text) => ({ text }));
+}
+
+/**
+ * The lines each commit added to and removed from a ledger file, oldest first,
+ * from `git log -p --unified=0 --no-renames` written with
+ * `--format=%x1e%H%x1f%an%x1f%aI` over the file. The caller runs git; this
+ * reads the text. A line removed and added again in one commit (a newline
+ * fixed at the end of the file) is neither. A removed line is what
+ * {@link deriveGateAudit} reports as a revocation.
+ */
+export function gateLedgerLinesFromLog(log: string): GateLedgerLine[] {
+  const out: GateLedgerLine[] = [];
+  for (const block of log.split("\x1e").slice(1)) {
+    const [head = "", ...rest] = block.split("\n");
+    const [commit = "", author = "", date = ""] = head.split("\x1f");
+    const net = new Map<string, number>();
+    const order: string[] = [];
+    for (const l of rest) {
+      const sign = l[0];
+      if ((sign !== "+" && sign !== "-") || l[1] !== "{") continue;
+      const text = l.slice(1).trim();
+      if (!net.has(text)) order.push(text);
+      net.set(text, (net.get(text) ?? 0) + (sign === "+" ? 1 : -1));
+    }
+    const when = Date.parse(date.trim());
+    const at = Number.isNaN(when) ? date.trim() : new Date(when).toISOString();
+    for (const text of order) {
+      const n = net.get(text)!;
+      for (let i = 0; i < Math.abs(n); i++) {
+        out.push(n > 0 ? { text, commit: commit.trim() } : { text, commit: commit.trim(), removed: { at, ...(author ? { by: author } : {}) } });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * The thin reader: each op's ledger through a {@link GateLedgerPort} (the git
+ * port, or the in-memory one in a test), as input for {@link deriveGateAudit}.
+ * The port holds the file as it stands, so nothing here is revoked; add
+ * history through {@link gateLedgerLinesFromLog} for that.
+ */
+export async function readGateAuditLedgers(port: Pick<GateLedgerPort, "read">, ops: readonly string[]): Promise<GateAuditLedger[]> {
+  const out: GateAuditLedger[] = [];
+  for (const op of ops) {
+    const { resolutions, pending } = await port.read(op);
+    out.push({ op, lines: [...pending, ...resolutions].map((record) => ({ record })) });
+  }
+  return out;
+}

package/src/lifecycle/gate-ledger-select.ts

@@ -0,0 +1,113 @@
+/**
+ * The rules a gate is decided by, over gate ledger lines already read (#2119,
+ * #2300): the pending fact a resolution must be newer than, and the
+ * resolution that answers a gate for a plan. They read no git, so
+ * `@intentius/chant/gate-decision` bundles them without the ledger's git
+ * code (#3763). `./gate-ledger.ts` re-exports them.
+ */
+
+import { samePlanDigest } from "./plan-digest";
+import type { GateResolutionRecord, PendingGateRecord } from "./gate-ledger";
+
+/** Whether a pending fact has aged out of relevance at `nowIso`. */
+export function isPendingGateExpired(record: PendingGateRecord, nowIso: string): boolean {
+  return new Date(record.expiresAt).getTime() <= new Date(nowIso).getTime();
+}
+
+/** The most recent pending fact for `gate`, expired or not — the anchor {@link latestResolutionSince} measures a resolution against. `undefined` when the gate has never been recorded pending. */
+export function latestPendingGate(
+  records: PendingGateRecord[],
+  gate: string,
+): PendingGateRecord | undefined {
+  let latest: PendingGateRecord | undefined;
+  for (const r of records) {
+    if (r.gate !== gate) continue;
+    if (!latest || new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime()) latest = r;
+  }
+  return latest;
+}
+
+/** The most recent resolution for `gate` recorded after `sinceIso` (a gated tick's own timestamp) — what `chant operator status` uses to tell a resolved gate from a still-pending one. `undefined` when no such resolution exists. */
+export function latestResolutionSince(
+  records: GateResolutionRecord[],
+  gate: string,
+  sinceIso: string,
+): GateResolutionRecord | undefined {
+  const since = new Date(sinceIso).getTime();
+  let latest: GateResolutionRecord | undefined;
+  for (const r of records) {
+    if (r.gate !== gate) continue;
+    if (new Date(r.timestamp).getTime() < since) continue;
+    if (!latest || new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime()) latest = r;
+  }
+  return latest;
+}
+
+/** What {@link latestResolutionForPlan} found for the plan a run is holding. */
+export interface PlanBoundResolution {
+  /** The resolution that answers this gate for this plan. Absent when nothing does. */
+  resolution?: GateResolutionRecord;
+  /**
+   * Present instead of {@link PlanBoundResolution.resolution} when a
+   * resolution stands for this gate but for a different plan — the newest
+   * such record, so a refusal can name who approved what and when. Its
+   * `planDigest` is `undefined` for a record written before #2300.
+   */
+  mismatched?: GateResolutionRecord;
+}
+
+/**
+ * The resolution that answers `gate` for the plan `planDigest` identifies
+ * (#2300).
+ *
+ * The criterion is the digest; recency is only the tiebreak between several
+ * resolutions that all match it. That inversion is the whole point of the
+ * issue: {@link latestResolutionSince} asks "is there a newer approval",
+ * which a run answers yes to no matter what has changed since, and this asks
+ * "is there an approval of *this*".
+ *
+ * - `planDigest` `undefined` — the gate binds no plan (an Op `gate` step
+ *   authored with no `plan`). Falls straight through to
+ *   {@link latestResolutionSince}: gates that never claimed to bind a plan
+ *   behave exactly as they did before #2300.
+ * - A resolution whose `planDigest` equals `planDigest` answers the gate.
+ * - A resolution for a different plan does not, and comes back as
+ *   `mismatched` so the caller can name both digests.
+ * - A resolution with no `planDigest` at all — every record written before
+ *   #2300 — does not either, and comes back as `mismatched` with an absent
+ *   `planDigest`. This is the safe reading of the migration: such a record
+ *   proves someone approved something, and nothing about what. Accepting it
+ *   once would silently apply the very change this check exists to catch, on
+ *   exactly the estates that have been running longest. The cost is one
+ *   further `chant approve` per gate after the upgrade, which the refusal
+ *   says out loud.
+ */
+export function latestResolutionForPlan(
+  records: GateResolutionRecord[],
+  gate: string,
+  sinceIso: string,
+  planDigest: string | undefined,
+): PlanBoundResolution {
+  if (planDigest === undefined) {
+    const resolution = latestResolutionSince(records, gate, sinceIso);
+    return resolution ? { resolution } : {};
+  }
+
+  const since = new Date(sinceIso).getTime();
+  let matched: GateResolutionRecord | undefined;
+  let mismatched: GateResolutionRecord | undefined;
+  for (const r of records) {
+    if (r.gate !== gate) continue;
+    if (new Date(r.timestamp).getTime() < since) continue;
+    const newest = (best: GateResolutionRecord | undefined) =>
+      !best || new Date(r.timestamp).getTime() >= new Date(best.timestamp).getTime();
+    if (samePlanDigest(r.planDigest, planDigest)) {
+      if (newest(matched)) matched = r;
+    } else if (newest(mismatched)) {
+      mismatched = r;
+    }
+  }
+
+  if (matched) return { resolution: matched };
+  return mismatched ? { mismatched } : {};
+}

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

@@ -419,3 +419,25 @@ describe("readGateLedger — a corrupted planDigest is malformed (#2300)", () =>
     });
   });
 });
+
+describe("applied approvals on chant/lifecycle (#3784)", () => {
+  test("the git port appends and reads _gates/<op>/applied.jsonl, which the gate ledger reader never sees", async () => {
+    const { gitGateLedgerPort } = await import("../op/gate");
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const port = gitGateLedgerPort({ cwd: dir });
+      await appendGateResolution({ op: "migrations", gate: "migrations-wave-1", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00.000Z", planDigest: "sha256:aa" }, { cwd: dir });
+      const line = {
+        version: 1 as const, kind: "applied" as const, op: "migrations", gate: "migrations-wave-1", planDigest: "sha256:aa",
+        approvedAt: "2026-10-10T00:00:00.000Z", approvedBy: "alice", timestamp: "2026-10-11T00:00:00.000Z",
+      };
+      await port.appendApplied!(line);
+      await port.appendApplied!({ ...line, timestamp: "2026-10-11T01:00:00.000Z" });
+      expect(await port.readApplied!("migrations")).toEqual([line, { ...line, timestamp: "2026-10-11T01:00:00.000Z" }]);
+      expect(await readBlobFromPath("_gates/migrations", "applied.jsonl", { cwd: dir })).toMatch(/^\{.*\}\n\{.*\}\n$/);
+      const ledger = await port.read("migrations");
+      expect(ledger.resolutions).toHaveLength(1);
+      expect(ledger.pending).toHaveLength(0);
+    });
+  });
+});