@intentius/chant 0.49.0 → 0.50.0

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

@@ -0,0 +1,199 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  appendConvergeRecord,
+  readConvergeLedger,
+  consecutiveRuleFires,
+  type ConvergeTickRecordInput,
+  type ConvergeTickRecord,
+} from "./converge-ledger";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+function makeInput(overrides?: Partial<ConvergeTickRecordInput>): ConvergeTickRecordInput {
+  return {
+    op: "fountain-converge",
+    env: "staging",
+    timestamp: "2026-01-01T00:00:00.000Z",
+    firedRuleIds: [],
+    outcomes: [],
+    summary: { drifted: 0, remediated: 0, reported: 0, skippedBudget: 0, skippedFlap: 0, unobserved: 0, adopted: 0 },
+    log: "converge(staging): drifted=0 remediated=0 reported=0 skipped-budget=0 skipped-flap=0 unobserved=0 adopted=0",
+    ...overrides,
+  };
+}
+
+describe("converge-ledger", () => {
+  describe("appendConvergeRecord / readConvergeLedger", () => {
+    test("round-trips a single record", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const { record } = await appendConvergeRecord(makeInput(), { cwd: dir });
+        expect(record.version).toBe(1);
+
+        const { records, malformed } = await readConvergeLedger("staging", { cwd: dir });
+        expect(malformed).toBe(0);
+        expect(records).toEqual([record]);
+      });
+    });
+
+    test("appends without clobbering prior records", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendConvergeRecord(makeInput({ timestamp: "2026-01-01T00:00:00.000Z" }), { cwd: dir });
+        await appendConvergeRecord(makeInput({ timestamp: "2026-01-01T00:10:00.000Z" }), { cwd: dir });
+        await appendConvergeRecord(makeInput({ timestamp: "2026-01-01T00:20:00.000Z" }), { cwd: dir });
+
+        const { records } = await readConvergeLedger("staging", { cwd: dir });
+        expect(records).toHaveLength(3);
+        expect(records.map((r) => r.timestamp)).toEqual([
+          "2026-01-01T00:00:00.000Z",
+          "2026-01-01T00:10:00.000Z",
+          "2026-01-01T00:20:00.000Z",
+        ]);
+      });
+    });
+
+    test("empty ledger for an environment with no records — never throws", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const { records, malformed } = await readConvergeLedger("nowhere", { cwd: dir });
+        expect(records).toEqual([]);
+        expect(malformed).toBe(0);
+      });
+    });
+
+    test("skips malformed lines but reports the count", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendConvergeRecord(makeInput(), { cwd: dir });
+        // Directly corrupt the ledger by writing a second, non-JSON line via a
+        // second append whose "record" is actually malformed content — simulate
+        // by reading, then re-appending raw garbage through the same git path
+        // a hand-edited ledger would produce. We reuse appendConvergeRecord's
+        // underlying git plumbing indirectly by writing a second valid record,
+        // then asserting the reader tolerates an out-of-schema line mixed in
+        // at read time isn't directly expressible via the public API, so this
+        // test instead exercises the schema-validation branch: a record
+        // missing `firedRuleIds` is treated as malformed.
+        const { readBlobFromPath, writeBlobToPath } = await import("./git");
+        const existing = await readBlobFromPath("staging", "converge.jsonl", { cwd: dir });
+        const corrupted = `${existing}\n${JSON.stringify({ version: 1, op: "x", env: "staging" })}`;
+        await writeBlobToPath("staging", "converge.jsonl", corrupted, "corrupt", { cwd: dir });
+
+        const { records, malformed } = await readConvergeLedger("staging", { cwd: dir });
+        expect(records).toHaveLength(1);
+        expect(malformed).toBe(1);
+      });
+    });
+  });
+
+  describe("consecutiveRuleFires", () => {
+    function rec(firedRuleIds: string[]): ConvergeTickRecord {
+      return { ...makeInput({ firedRuleIds }), version: 1 };
+    }
+
+    test("0 for an empty ledger", () => {
+      expect(consecutiveRuleFires([], "r1")).toBe(0);
+    });
+
+    test("0 when the newest tick didn't fire it", () => {
+      const records = [rec(["r1"]), rec(["r1"]), rec([])];
+      expect(consecutiveRuleFires(records, "r1")).toBe(0);
+    });
+
+    test("counts consecutive fires from the newest tick backward", () => {
+      const records = [rec([]), rec(["r1"]), rec(["r1"]), rec(["r1"])];
+      expect(consecutiveRuleFires(records, "r1")).toBe(3);
+    });
+
+    test("stops counting at the first non-firing tick, scanning backward", () => {
+      const records = [rec(["r1"]), rec([]), rec(["r1"]), rec(["r1"])];
+      expect(consecutiveRuleFires(records, "r1")).toBe(2);
+    });
+
+    test("only counts the named rule, ignoring others", () => {
+      const records = [rec(["r2"]), rec(["r1", "r2"])];
+      expect(consecutiveRuleFires(records, "r1")).toBe(1);
+      expect(consecutiveRuleFires(records, "r2")).toBe(2);
+    });
+  });
+
+  // ── Gate-as-fact (#1485) ───────────────────────────────────────────────────
+
+  describe("gated outcome", () => {
+    test("round-trips a 'gated' outcome with its gateName, and a gated count in the summary", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const { record } = await appendConvergeRecord(
+          makeInput({
+            firedRuleIds: ["drift-apply"],
+            outcomes: [
+              {
+                ruleId: "drift-apply",
+                action: "gated",
+                op: "fountain-apply",
+                gateName: "rollout-gate",
+                reason: 'dispatch of "fountain-apply" hit gate "rollout-gate"',
+              },
+            ],
+            summary: { drifted: 1, remediated: 0, reported: 0, skippedBudget: 0, skippedFlap: 0, unobserved: 0, adopted: 0, gated: 1 },
+          }),
+          { cwd: dir },
+        );
+        expect(record.outcomes[0]).toEqual({
+          ruleId: "drift-apply",
+          action: "gated",
+          op: "fountain-apply",
+          gateName: "rollout-gate",
+          reason: 'dispatch of "fountain-apply" hit gate "rollout-gate"',
+        });
+        expect(record.summary.gated).toBe(1);
+
+        const { records } = await readConvergeLedger("staging", { cwd: dir });
+        expect(records).toEqual([record]);
+      });
+    });
+  });
+
+  // ── Concurrent local writers (#1485) ────────────────────────────────────────
+
+  describe("appendConvergeRecord retries on RefCASConflictError", () => {
+    test("a concurrent writer to a different env's file on the same orphan branch doesn't lose either write", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        // Two "operators" appending to two different environments' ledgers on
+        // the same orphan branch, interleaved so their internal git-plumbing
+        // reads race — this is exactly the scenario `writeBlobToPath`'s CAS
+        // guard (chant #1485) now protects against, and `appendConvergeRecord`
+        // retries through rather than surfacing to the caller.
+        const [a, b] = await Promise.all([
+          appendConvergeRecord(makeInput({ env: "staging", op: "staging-converge" }), { cwd: dir }),
+          appendConvergeRecord(makeInput({ env: "prod", op: "prod-converge" }), { cwd: dir }),
+        ]);
+        expect(a.record.env).toBe("staging");
+        expect(b.record.env).toBe("prod");
+
+        const staging = await readConvergeLedger("staging", { cwd: dir });
+        const prod = await readConvergeLedger("prod", { cwd: dir });
+        expect(staging.records).toHaveLength(1);
+        expect(prod.records).toHaveLength(1);
+      });
+    });
+  });
+});

package/src/lifecycle/converge-ledger.ts

@@ -0,0 +1,179 @@
+/**
+ * Converge ledger (#1484) — the append-only record of what a `ConvergeOp`
+ * tick did, one line per tick, at `<env>/converge.jsonl` on the
+ * `chant/lifecycle` orphan branch. Same storage shape as the release ledger
+ * (./release-ledger.ts): immutable, append-only JSONL, reusing
+ * `writeBlobToPath`/`readBlobFromPath` (./git.ts) directly rather than a new
+ * git-plumbing path — the exact reuse `appendReleaseRecordLine` already
+ * demonstrates for a second filename under the same env directory.
+ *
+ * This is also where flap-damping state lives (issue: "consecutive-fire
+ * counts go in the ledger ... not process memory, so damping survives worker
+ * restarts"): each record's `firedRuleIds` names every rule whose predicate
+ * matched this tick, independent of what action was actually taken (run,
+ * report, or skipped for budget/flap reasons) — {@link consecutiveRuleFires}
+ * walks the ledger backward from the newest record and counts how many in a
+ * row include a given rule id, stopping at the first tick where it didn't
+ * fire (the symptom cleared).
+ */
+import { sortedJsonReplacer } from "../utils";
+import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
+
+const FILENAME = "converge.jsonl";
+
+/**
+ * Read-modify-append retry budget for {@link appendConvergeRecord} (#1485).
+ * `writeBlobToPath`'s ref write is now CAS-guarded (./git.ts) — a conflict
+ * (another writer, e.g. a second operator ticking a different env on the
+ * same orphan branch, updated the branch tip between our read and our
+ * write) throws `RefCASConflictError` instead of silently clobbering. This
+ * many attempts, re-reading the ledger fresh each time, absorbs that race
+ * rather than surfacing it as a tick failure — the whole point of the CAS
+ * guard is correctness, not a new way for a tick to fail.
+ */
+const APPEND_RETRY_ATTEMPTS = 5;
+
+/** One rule's outcome within a tick. */
+export interface ConvergeRuleOutcome {
+  ruleId: string;
+  /**
+   * What actually happened for this fired rule this tick. `"gated"` (#1485)
+   * is gate-as-fact: the dispatched op's own run hit a gate it can't clear
+   * on the local executor, and the tick records that as a terminal, durable
+   * fact — `gateName` names the gate — rather than treating it as a
+   * dispatch failure. Resolution is out-of-band (`chant approve <op>
+   * <gate>`, ./gate-ledger.ts, or a merged PR); the tick itself never
+   * blocks waiting for it.
+   */
+  action: "ran" | "reported" | "skipped-budget" | "skipped-flap" | "gated";
+  /** The dispatched Op name, for `action: "ran"` or `"gated"`. */
+  op?: string;
+  /** The gate's signal name, for `action: "gated"`. */
+  gateName?: string;
+  /** The report reason, for `action: "reported"` (including a flap-damped rule's forced report) — and the human-readable explanation for `action: "gated"`. */
+  reason?: string;
+}
+
+/** One immutable converge-tick record. */
+export interface ConvergeTickRecord {
+  /** Schema version, so an incompatible future shape is detected before being misread. */
+  version: 1;
+  /** The ConvergeOp's name (`OpConfig.name`). */
+  op: string;
+  env: string;
+  /** ISO-8601 timestamp, caller-supplied (same convention as `ReleaseRecord.timestamp` — library code never calls `Date.now()` internally). */
+  timestamp: string;
+  /** Every rule id whose predicate matched this tick, regardless of what action followed — the flap-damping input. */
+  firedRuleIds: string[];
+  /** Per-rule outcome, for every fired rule. */
+  outcomes: ConvergeRuleOutcome[];
+  /** Aggregate counts backing the tick's one log line. */
+  summary: {
+    drifted: number;
+    remediated: number;
+    reported: number;
+    skippedBudget: number;
+    skippedFlap: number;
+    unobserved: number;
+    adopted: number;
+    /** Rules whose dispatch hit a gate this tick (#1485) — a terminal, non-blocking fact; see `ConvergeRuleOutcome.action`'s doc. @default 0, so an older record without this field still reads as zero, not undefined. */
+    gated?: number;
+  };
+  /** The one human-readable log line this tick produced (issue: "one log line and one ledger record per tick"). */
+  log: string;
+}
+
+export type ConvergeTickRecordInput = Omit<ConvergeTickRecord, "version">;
+
+/**
+ * Append one immutable tick record. Does not push to the remote — call
+ * `pushLifecycle` (./git.ts) afterward, same two-step shape every other
+ * ledger write here uses.
+ *
+ * Retries the whole read-modify-write cycle (#1485) on `RefCASConflictError`
+ * — `writeBlobToPath`'s ref write is CAS-guarded, so a concurrent writer to
+ * a *different* env's file on the same orphan branch (two operators ticking
+ * two environments at once is the ordinary case, not an edge case) can lose
+ * the race and needs to re-read the branch tip and retry, not fail the
+ * tick. Each retry re-reads `existing` fresh, so it always appends onto
+ * whatever the other writer just committed rather than reintroducing a stale
+ * read. Exhausting the budget re-throws the conflict — a real, sustained
+ * pile-up of writers is a signal worth surfacing, not silently swallowing.
+ *
+ * The baseline read must be `readPathSha` + `readBlobBySha` rather than
+ * `readBlobFromPath`, so the exact sha `existing` came from can be passed as
+ * `expectPriorPathSha`. See `writeBlobToPath` (./git.ts) for the race that
+ * closes.
+ */
+export async function appendConvergeRecord(
+  input: ConvergeTickRecordInput,
+  opts?: { cwd?: string },
+): Promise<{ commit: string; record: ConvergeTickRecord }> {
+  const record: ConvergeTickRecord = { version: 1, ...input };
+  const json = JSON.stringify(record, sortedJsonReplacer);
+
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS; attempt++) {
+    try {
+      const priorSha = await readPathSha(record.env, FILENAME, opts);
+      const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+      const content = existing ? `${existing.replace(/\n$/, "")}\n${json}` : json;
+      const commit = await writeBlobToPath(record.env, FILENAME, content, "Converge tick record", {
+        ...opts,
+        expectPriorPathSha: priorSha,
+      });
+      return { commit, record };
+    } catch (err) {
+      if (!(err instanceof RefCASConflictError)) throw err;
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}
+
+/** Read every tick record for `environment`, oldest first. Malformed lines are skipped, not thrown on — a corrupted or hand-edited ledger degrades gracefully, the same stance `readReleaseLedger` takes. */
+export async function readConvergeLedger(
+  environment: string,
+  opts?: { cwd?: string },
+): Promise<{ records: ConvergeTickRecord[]; malformed: number }> {
+  const content = await readBlobFromPath(environment, FILENAME, opts);
+  if (!content) return { records: [], malformed: 0 };
+
+  const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
+  const records: ConvergeTickRecord[] = [];
+  let malformed = 0;
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line) as Partial<ConvergeTickRecord>;
+      if (
+        parsed.version !== 1 ||
+        typeof parsed.op !== "string" ||
+        typeof parsed.env !== "string" ||
+        typeof parsed.timestamp !== "string" ||
+        !Array.isArray(parsed.firedRuleIds)
+      ) {
+        malformed++;
+        continue;
+      }
+      records.push(parsed as ConvergeTickRecord);
+    } catch {
+      malformed++;
+    }
+  }
+  return { records, malformed };
+}
+
+/**
+ * How many consecutive most-recent ticks (newest first) fired `ruleId`,
+ * stopping at the first tick where it did not — the count a rule's
+ * `flapThreshold` is compared against. `0` when the newest tick didn't fire
+ * it (including an empty ledger).
+ */
+export function consecutiveRuleFires(records: ConvergeTickRecord[], ruleId: string): number {
+  let count = 0;
+  for (let i = records.length - 1; i >= 0; i--) {
+    if (!records[i].firedRuleIds.includes(ruleId)) break;
+    count++;
+  }
+  return count;
+}

package/src/lifecycle/deep-diff.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { countPropertyDrift, diffDeep } from "./deep-diff";
+import { countPropertyDrift, diffDeep, type DeclaredDeepEntity } from "./deep-diff";
 import { UNRESOLVED, type NormalizedDeepObservation } from "../deep-observation";
 import type { BaselineLexicon } from "./observation-baseline";
 
@@ -202,3 +202,81 @@ describe("diffDeep — owning field manager (#1189)", () => {
     expect(change).not.toHaveProperty("owner");
   });
 });
+
+// #1443 — the declared-side counterpart of `owner`. Both sides of one
+// comparison get precise attribution, which is what makes the report actionable.
+describe("diffDeep — declared-side origin (#1443)", () => {
+  // Annotated, not `as const`: the annotation is what keeps `kind` narrowed to
+  // its literal, and it types the fixture as the production shape rather than
+  // whatever the literal happens to infer to.
+  const declared: Record<string, DeclaredDeepEntity> = {
+    web: {
+      type: "K8s::Apps::Deployment",
+      properties: { spec: { replicas: 2, template: { spec: { containers: [{ name: "app", image: "a:1" }] } } } },
+      pathOrigins: {
+        "": { kind: "composite", composite: "WebService", instance: "web" },
+        "spec.replicas": { kind: "build-param", params: ["tier"] },
+      },
+    },
+  };
+
+  test("reports the origin alongside the live owner", () => {
+    const result = diffDeep({
+      declared,
+      live: live({
+        web: {
+          type: "K8s::Apps::Deployment",
+          properties: { spec: { replicas: 5, template: { spec: { containers: [{ name: "app", image: "a:1" }] } } } },
+          fieldOwners: { "spec.replicas": "hpa-controller" },
+        },
+      }),
+    });
+    expect(result.drifted[0].changes[0]).toMatchObject({
+      path: "spec.replicas",
+      owner: "hpa-controller",
+      origin: { kind: "build-param", params: ["tier"] },
+    });
+  });
+
+  test("a path with no origin of its own inherits the nearest recorded ancestor", () => {
+    const result = diffDeep({
+      declared,
+      live: live({
+        web: {
+          type: "K8s::Apps::Deployment",
+          properties: { spec: { replicas: 2, template: { spec: { containers: [{ name: "app", image: "a:2" }] } } } },
+        },
+      }),
+    });
+    const change = result.drifted[0].changes.find((c) => c.path.includes("image"))!;
+    expect(change.origin).toEqual({ kind: "composite", composite: "WebService", instance: "web" });
+  });
+
+  test("is absent on an undeclared path — nothing in source produced it", () => {
+    const result = diffDeep({
+      declared,
+      live: live({
+        web: {
+          type: "K8s::Apps::Deployment",
+          properties: {
+            spec: { replicas: 2, template: { spec: { containers: [{ name: "app", image: "a:1" }] } } },
+            status: { observed: 1 },
+          },
+        },
+      }),
+    });
+    const change = result.drifted[0].changes.find((c) => c.path === "status.observed")!;
+    expect(change.kind).toBe("undeclared");
+    expect(change).not.toHaveProperty("origin");
+  });
+
+  test("is absent when the build recorded no path origins", () => {
+    // The run path, and a sandboxed child: absent means "could not record",
+    // not "nothing governs this field", so the key must not appear at all.
+    const result = diffDeep({
+      declared: { web: { type: "K8s::Apps::Deployment", properties: { spec: { replicas: 2 } } } },
+      live: live({ web: { type: "K8s::Apps::Deployment", properties: { spec: { replicas: 5 } } } }),
+    });
+    expect(result.drifted[0].changes[0]).not.toHaveProperty("origin");
+  });
+});

package/src/lifecycle/deep-diff.ts

@@ -29,6 +29,7 @@ import {
   type DeepNormalizationHooks,
   type NormalizedDeepObservation,
 } from "../deep-observation";
+import { originOfPath, type PathOrigin } from "../provenance";
 import type { UnobservedResource } from "./live-diff";
 import { acceptedDeviation, type BaselineLexicon } from "./observation-baseline";
 
@@ -70,6 +71,18 @@ export interface PropertyDrift {
    * with no per-field ownership, which is every substrate but k8s.
    */
   owner?: string;
+  /**
+   * What produced this path on the DECLARED side (#1443) — the counterpart of
+   * {@link owner}, and the reason the two are reported together: "owned live by
+   * `hpa-controller`, governed in source by the `tier` parameter" says where
+   * each half of a disagreement has to be fixed, which neither half says alone.
+   *
+   * Resolved by longest prefix from the entity's recorded path origins, so a
+   * field inside a keyed list element inherits the origin recorded for the
+   * list. Absent when the build recorded none — the run path, and a sandboxed
+   * child, have no expression to attribute (see `EntityProvenance.paths`).
+   */
+  origin?: PathOrigin;
 }
 
 /** Property-level drift for one declared entity. */
@@ -100,6 +113,11 @@ export interface DeepDiffResult {
 export interface DeclaredDeepEntity {
   type: string;
   properties: Record<string, unknown>;
+  /**
+   * The entity's recorded path origins (#1443), as `EntityProvenance.paths`.
+   * Omit for a build that recorded none.
+   */
+  pathOrigins?: Record<string, PathOrigin>;
 }
 
 export interface DiffDeepInput {
@@ -188,12 +206,17 @@ export function diffDeep(input: DiffDeepInput): DeepDiffResult {
       // meaningful for a path that exists live — an `absent` drift has no live
       // field for anyone to own.
       const owner = hasLive ? liveEntity.fieldOwners?.[path] : undefined;
+      // The declared-side counterpart (#1443). Only meaningful for a path
+      // source actually declares — an `undeclared` drift has no authored
+      // expression for anything to have produced.
+      const origin = hasDeclared ? originOfPath(declaredEntity.pathOrigins, path) : undefined;
       const drift: PropertyDrift = {
         path,
         kind,
         ...(hasDeclared ? { declared: declaredValue } : {}),
         ...(hasLive ? { live: liveValue } : {}),
         ...(owner ? { owner } : {}),
+        ...(origin ? { origin } : {}),
       };
 
       const acceptedEntry = acceptedDeviation(baseline, name, path);

package/src/lifecycle/deep-observe.ts

@@ -27,11 +27,21 @@ import {
   type NormalizedDeepObservation,
 } from "../deep-observation";
 import { unobservedAll, type UnobservedEntity } from "../observation";
+import type { PathOrigin } from "../provenance";
 import { diffDeep, type DeclaredDeepEntity, type DeepDiffResult } from "./deep-diff";
 import type { BaselineLexicon } from "./observation-baseline";
 
-/** Declared entities for one lexicon, in the shape the observe paths pass around. */
-export type DeclaredEntities = Map<string, { entityType: string; props: Record<string, unknown> }>;
+/**
+ * Declared entities for one lexicon, in the shape the observe paths pass around.
+ *
+ * `pathOrigins` (#1443) rides alongside `props` rather than being read off the
+ * entity, because callers rebuild this map as plain objects and the symbol-keyed
+ * provenance channel does not survive that copy.
+ */
+export type DeclaredEntities = Map<
+  string,
+  { entityType: string; props: Record<string, unknown>; pathOrigins?: Record<string, PathOrigin> }
+>;
 
 export interface DeepObserveOptions {
   environment: string;
@@ -138,6 +148,7 @@ export function diffDeepObservation(
         hooks,
         counterpartPaths: livePaths,
       }),
+      ...(entity.pathOrigins ? { pathOrigins: entity.pathOrigins } : {}),
     };
     if (liveEntity) {
       normalizedLive[name] = {

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

@@ -0,0 +1,103 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendGateResolution, readGateResolutions, latestResolutionSince } from "./gate-ledger";
+import { readBlobFromPath } from "./git";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+describe("lifecycle/gate-ledger", () => {
+  test("appendGateResolution + readGateResolutions round-trip", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const { record } = await appendGateResolution(
+        { op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+        { cwd: dir },
+      );
+      expect(record.version).toBe(1);
+
+      const { records, malformed } = await readGateResolutions("fountain-apply", { cwd: dir });
+      expect(malformed).toBe(0);
+      expect(records).toEqual([record]);
+    });
+  });
+
+  test("stores under a global _gates namespace, keyed by op — not per-environment", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await appendGateResolution(
+        { op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+        { cwd: dir },
+      );
+      const raw = await readBlobFromPath("_gates", "fountain-apply.jsonl", { cwd: dir });
+      expect(raw).toContain("rollout-gate");
+    });
+  });
+
+  test("readGateResolutions returns [] for an op with no resolutions yet", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      expect(await readGateResolutions("no-such-op", { cwd: dir })).toEqual({ records: [], malformed: 0 });
+    });
+  });
+
+  test("appends without clobbering — multiple gates/resolutions on the same op accumulate", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await appendGateResolution(
+        { op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+        { cwd: dir },
+      );
+      await appendGateResolution(
+        { op: "fountain-apply", gate: "prod-gate", resolvedBy: "sam", timestamp: "2026-01-02T00:00:00.000Z", note: "https://github.com/x/y/pull/1" },
+        { cwd: dir },
+      );
+      const { records } = await readGateResolutions("fountain-apply", { cwd: dir });
+      expect(records.map((r) => r.gate)).toEqual(["rollout-gate", "prod-gate"]);
+      expect(records[1].note).toBe("https://github.com/x/y/pull/1");
+    });
+  });
+
+  describe("latestResolutionSince", () => {
+    test("finds a resolution recorded after the gated tick's own timestamp", () => {
+      const records = [
+        { version: 1 as const, op: "x", gate: "g1", resolvedBy: "a", timestamp: "2026-01-01T00:00:00.000Z" },
+        { version: 1 as const, op: "x", gate: "g1", resolvedBy: "b", timestamp: "2026-01-03T00:00:00.000Z" },
+      ];
+      const found = latestResolutionSince(records, "g1", "2026-01-02T00:00:00.000Z");
+      expect(found?.resolvedBy).toBe("b");
+    });
+
+    test("returns undefined when the only resolution predates the gated tick (a stale, superseded approval)", () => {
+      const records = [
+        { version: 1 as const, op: "x", gate: "g1", resolvedBy: "a", timestamp: "2026-01-01T00:00:00.000Z" },
+      ];
+      expect(latestResolutionSince(records, "g1", "2026-01-02T00:00:00.000Z")).toBeUndefined();
+    });
+
+    test("ignores resolutions for a different gate", () => {
+      const records = [
+        { version: 1 as const, op: "x", gate: "other-gate", resolvedBy: "a", timestamp: "2026-01-05T00:00:00.000Z" },
+      ];
+      expect(latestResolutionSince(records, "g1", "2026-01-01T00:00:00.000Z")).toBeUndefined();
+    });
+
+    test("undefined when there are no resolutions at all", () => {
+      expect(latestResolutionSince([], "g1", "2026-01-01T00:00:00.000Z")).toBeUndefined();
+    });
+  });
+});