@intentius/chant 0.121.1 → 0.123.0

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));
+  });
+});