@intentius/chant 0.53.0 → 0.53.1

package/src/cli/main.ts

@@ -30,7 +30,7 @@ import { runGraph } from "./handlers/graph";
 import { runExplain } from "./handlers/explain";
 import { runSearch } from "./handlers/search";
 import { runOp, runOpList, runOpStatus, runOpSignal, runOpCancel, runOpLog } from "./handlers/run";
-import { runOperator, runOperatorStatus, runApprove } from "./handlers/operator";
+import { runOperator, runOperatorStatus, runOperatorLog, runApprove } from "./handlers/operator";
 import { runEmulator } from "./handlers/emulator";
 import { splitJoinedFlags, dispatchCommandGroup, collectCommandGroups, formatCommandGroupsHelp, type CommandGroup } from "./command-group";
 import type { LexiconPlugin } from "../lexicon";
@@ -388,6 +388,16 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.once = true;
     } else if (arg === "--note") {
       result.note = args[++i];
+    } else if (arg === "--url") {
+      result.url = args[++i];
+    } else if (arg === "--op") {
+      result.op = args[++i];
+    } else if (arg === "--since") {
+      result.since = args[++i];
+    } else if (arg === "--limit") {
+      // Parsed here, validated by the handler — `parseArgs` reports shape, not
+      // policy, the same split every other value flag here uses.
+      result.limit = Number(args[++i]);
     } else if (arg.startsWith("--")) {
       // chant #1127 — every recognized flag is matched above; anything left
       // starting with `--` is unrecognized, whether it arrived bare
@@ -524,11 +534,21 @@ Ops:
                         ConvergeOp, read from the chant/lifecycle orphan
                         branch alone — no daemon needs to be running
                         (--env <env>, --json)
+  operator log           Converge tick history and the gate resolutions
+                        against it, merged into one timestamp-ordered
+                        timeline, from the same orphan branch (--env <env>,
+                        --op <name>, --since <iso>, --limit <n>, --json).
+                        --json also carries the count of ledger lines that
+                        were unreadable, so a short timeline is never
+                        silently short
   approve <op> <gate>    Record a gate's out-of-band resolution fact
-                        (--actor <name>, --note <text>) — the durable
-                        counterpart to a converge tick's gate-as-fact
-                        outcome; see the pending-gates list in operator
-                        status. Does not itself unblock the gated op's local
+                        (--actor <name>, --note <text>, --url <url>) — the
+                        durable counterpart to a converge tick's
+                        gate-as-fact outcome; see the pending-gates list in
+                        operator status. --url is the PR/MR the resolution
+                        happened at, recorded typed rather than as free text,
+                        and defaults to the PR/MR of the surrounding CI job.
+                        Does not itself unblock the gated op's local
                         dispatch (re-run --temporal, or merge its PR)
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
@@ -875,6 +895,7 @@ const registry: CommandDef[] = [
   { name: "run", handler: runOp },
 
   { name: "operator status", handler: runOperatorStatus },
+  { name: "operator log", handler: runOperatorLog },
   { name: "operator", handler: runOperator },
   { name: "approve", handler: runApprove },
 

package/src/cli/registry.ts

@@ -285,8 +285,16 @@ export interface ParsedArgs {
   leaseTtl?: string;
   /** `chant operator --once` (#1485) — run a single round and exit, instead of looping until Ctrl-C. Also the offline test/cron-invoker story. */
   once?: boolean;
-  /** `chant approve <op> <gate> --note <text>` (#1485) — optional free-text context recorded on the gate-resolution fact (e.g. a PR URL). */
+  /** `chant approve <op> <gate> --note <text>` (#1485) — optional free-text prose recorded on the gate-resolution fact. The PR link belongs in `--url` since #2028; this is for everything that isn't the link. */
   note?: string;
+  /** `chant operator log --op <name>` (#2029) — restrict the tick history to one ConvergeOp by name. Omitted, every discovered ConvergeOp's ticks are merged into one timeline. */
+  op?: string;
+  /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. */
+  since?: string;
+  /** `chant operator log --limit <n>` (#2029) — keep only the newest n entries (still printed oldest-first). */
+  limit?: number;
+  /** `chant approve <op> <gate> --url <url>` (#2028) — the address this resolution happened at (the PR/MR that carried the change), recorded typed on the gate-resolution fact so a reader is not sniffing `--note` for something link-shaped. Defaults to the PR/MR the surrounding CI job is for, when there is one. Must be an absolute http/https URL. */
+  url?: string;
 }
 
 /**

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

@@ -7,9 +7,11 @@ import {
   appendConvergeRecord,
   readConvergeLedger,
   consecutiveRuleFires,
+  componentVerdicts,
   type ConvergeTickRecordInput,
   type ConvergeTickRecord,
 } from "./converge-ledger";
+import type { ComponentStatusRow } from "./status";
 
 function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
   const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
@@ -171,6 +173,114 @@ describe("converge-ledger", () => {
     });
   });
 
+  // ── Per-component verdicts and tick id (#2027) ─────────────────────────────
+
+  describe("tick id", () => {
+    test("mints one per record, and two ticks in the same ISO second are still distinguishable", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const a = await appendConvergeRecord(makeInput(), { cwd: dir });
+        const b = await appendConvergeRecord(makeInput(), { cwd: dir });
+
+        expect(a.record.id).toMatch(/^[0-9a-f-]{36}$/);
+        expect(a.record.timestamp).toBe(b.record.timestamp);
+        expect(a.record.id).not.toBe(b.record.id);
+
+        const { records } = await readConvergeLedger("staging", { cwd: dir });
+        expect(records.map((r) => r.id)).toEqual([a.record.id, b.record.id]);
+      });
+    });
+
+    test("an explicitly supplied id wins over the mint", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const { record } = await appendConvergeRecord(makeInput({ id: "tick-fixed" }), { cwd: dir });
+        expect(record.id).toBe("tick-fixed");
+      });
+    });
+
+    test("a pre-#2027 record with no id still reads, rather than being counted malformed", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendConvergeRecord(makeInput(), { cwd: dir });
+        // Hand-write the pre-#2027 shape (no `id`) onto the same ledger,
+        // through the same git plumbing a real writer used before the field
+        // existed.
+        const { readBlobFromPath, writeBlobToPath } = await import("./git");
+        const legacy = JSON.stringify({ version: 1, ...makeInput({ timestamp: "2025-12-31T00:00:00.000Z" }) });
+        const existing = await readBlobFromPath("staging", "converge.jsonl", { cwd: dir });
+        await writeBlobToPath("staging", "converge.jsonl", `${existing}\n${legacy}`, "legacy", { cwd: dir });
+
+        const { records, malformed } = await readConvergeLedger("staging", { cwd: dir });
+        expect(malformed).toBe(0);
+        expect(records).toHaveLength(2);
+        expect(records[1].id).toBeUndefined();
+      });
+    });
+  });
+
+  describe("componentVerdicts", () => {
+    const row = (over: Partial<ComponentStatusRow>): ComponentStatusRow => ({
+      component: "svc",
+      env: "staging",
+      reconciliation: "reconciled",
+      detail: "digest matches live",
+      ...over,
+    } as ComponentStatusRow);
+
+    test("keeps the verdict-bearing subset and drops the heavy release/build fields", () => {
+      const rows = [
+        row({ component: "api", reconciliation: "drifted", detail: "live digest differs", live: true,
+              recorded: { version: 1 } as unknown as ComponentStatusRow["recorded"] }),
+        row({ component: "worker", reconciliation: "unknown", detail: "could not read live state",
+              unobserved: { reason: "no-credentials", detail: "no role assumed" } }),
+      ];
+      expect(componentVerdicts(rows)).toEqual([
+        { component: "api", reconciliation: "drifted", detail: "live digest differs", live: true },
+        {
+          component: "worker",
+          reconciliation: "unknown",
+          detail: "could not read live state",
+          unobserved: { reason: "no-credentials", detail: "no role assumed" },
+        },
+      ]);
+    });
+
+    test("caps a multi-line or oversized detail to one line, so the record stays one line of JSON", () => {
+      const verdicts = componentVerdicts([
+        row({ detail: "first line\nsecond line" }),
+        row({ component: "big", detail: "x".repeat(500) }),
+      ]);
+      expect(verdicts[0].detail).toBe("first line");
+      expect(verdicts[1].detail).toHaveLength(301); // 300 + the ellipsis
+      expect(JSON.stringify(verdicts)).not.toContain("\\n");
+    });
+
+    test("round-trips on a record, naming the component that tripped the tick's aggregate unknown", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const { record } = await appendConvergeRecord(
+          makeInput({
+            components: componentVerdicts([
+              row({ component: "api", reconciliation: "drifted", detail: "live digest differs", live: true }),
+              row({ component: "worker", reconciliation: "unknown", detail: "unreadable",
+                    unobserved: { reason: "no-credentials" } }),
+            ]),
+            summary: { drifted: 1, remediated: 0, reported: 1, skippedBudget: 0, skippedFlap: 0, unobserved: 1, adopted: 0 },
+          }),
+          { cwd: dir },
+        );
+
+        const { records } = await readConvergeLedger("staging", { cwd: dir });
+        expect(records).toEqual([record]);
+        // The count says "1 unobserved"; the verdicts say which one.
+        expect(records[0].summary.unobserved).toBe(1);
+        expect(records[0].components?.filter((c) => c.unobserved).map((c) => c.component)).toEqual(["worker"]);
+        expect(records[0].components?.find((c) => c.reconciliation === "drifted")?.component).toBe("api");
+      });
+    });
+  });
+
   // ── Concurrent local writers (#1485) ────────────────────────────────────────
 
   describe("appendConvergeRecord retries on RefCASConflictError", () => {

package/src/lifecycle/converge-ledger.ts

@@ -16,11 +16,29 @@
  * row include a given rule id, stopping at the first tick where it didn't
  * fire (the symptom cleared).
  */
+import { randomUUID } from "node:crypto";
 import { sortedJsonReplacer } from "../utils";
+import type { ComponentStatusRow } from "./status";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
 const FILENAME = "converge.jsonl";
 
+/**
+ * Cap a piece of free text to one sanitized line before it goes into a
+ * record. A record here is one line of JSON, so a multi-line or unbounded
+ * string folded into any field would break the line the ledger is built out
+ * of. Every free-text field a tick writes goes through this: a dispatch
+ * failure's `stderr` (lexicons/temporal's `sanitizeOneLine`, which delegates
+ * here) and a component verdict's lexicon-authored `detail`.
+ */
+const MAX_LEDGER_TEXT_LEN = 300;
+export function sanitizeLedgerText(raw: string, maxLen = MAX_LEDGER_TEXT_LEN): string {
+  const firstLine = raw.split(/\r?\n/, 1)[0] ?? "";
+  // Strips literal control bytes; it is not matching on a range boundary.
+  const stripped = firstLine.replace(/[\x00-\x1f\x7f]/g, " ").trim();
+  return stripped.length > maxLen ? `${stripped.slice(0, maxLen)}…` : stripped;
+}
+
 /**
  * Read-modify-append retry budget for {@link appendConvergeRecord} (#1485).
  * `writeBlobToPath`'s ref write is now CAS-guarded (./git.ts) — a conflict
@@ -50,14 +68,85 @@ export interface ConvergeRuleOutcome {
   op?: string;
   /** The gate's signal name, for `action: "gated"`. */
   gateName?: string;
+  /**
+   * Where this gate's approval happens (#2028), for `action: "gated"` — the
+   * PR carrying the change in a gate-as-PR flow, or whatever review surface
+   * the dispatching environment knows about.
+   *
+   * The pending fact is the one a human has to act on, and it used to carry
+   * no link at all: `chant operator status`'s pending row was
+   * `{rule, op, gate}` and the only affordance it could print was a shell
+   * command. Absent when there genuinely is no address — a local tick with no
+   * PR behind it — never a synthesized one. See
+   * `./gate-ledger.ts`'s `resolveApprovalUrl` for where it comes from, and
+   * `GateResolutionRecord.url` for the resolved counterpart.
+   */
+  url?: 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 component's verdict as the tick observed it (#2027) — the per-entity
+ * layer behind the tick's single aggregate `status`.
+ *
+ * A deliberate subset of `ComponentStatusRow`: the five verdict-bearing
+ * fields, joined on the same `component` key `chant components status --live
+ * --json` emits, and none of the heavy ones. `recorded`, `build` and
+ * `componentBom` are dropped on purpose — they are release/build-ledger
+ * content, already readable by that same key, and a tick record is one line
+ * of JSON appended every tick forever. `detail` goes through
+ * {@link sanitizeLedgerText} for the same reason.
+ */
+export interface ConvergeComponentVerdict {
+  component: string;
+  reconciliation: ComponentStatusRow["reconciliation"];
+  /** Human-readable detail backing the verdict, capped to one line. */
+  detail: string;
+  /** "Observed live", when live evidence was gathered. Absent means "did not look" or "could not look" — see `unobserved`. */
+  live?: boolean;
+  /** Why live state could not be read for this component (#1089). Mutually exclusive with `live`; this is the row that tripped an aggregate `status: "unknown"`. */
+  unobserved?: { reason: string; detail?: string };
+}
+
+/**
+ * Project the tick's `ComponentStatusRow[]` down to what the ledger keeps.
+ * Pure; row order is preserved, so a consumer sees components in the same
+ * order the status join produced them.
+ */
+export function componentVerdicts(rows: readonly ComponentStatusRow[]): ConvergeComponentVerdict[] {
+  return rows.map((row) => ({
+    component: row.component,
+    reconciliation: row.reconciliation,
+    detail: sanitizeLedgerText(row.detail ?? ""),
+    ...(row.live !== undefined ? { live: row.live } : {}),
+    ...(row.unobserved
+      ? {
+          unobserved: {
+            reason: row.unobserved.reason,
+            ...(row.unobserved.detail !== undefined ? { detail: sanitizeLedgerText(row.unobserved.detail) } : {}),
+          },
+        }
+      : {}),
+  }));
+}
+
 /** One immutable converge-tick record. */
 export interface ConvergeTickRecord {
   /** Schema version, so an incompatible future shape is detected before being misread. */
   version: 1;
+  /**
+   * Stable tick id (#2027) — the one thing an outcome, a gate fact or a
+   * remediation can point at. Before this, a tick's identity was the
+   * `(op, env, timestamp)` triple, so two ticks landing in the same ISO
+   * second were indistinguishable and nothing could reference one.
+   *
+   * Minted by {@link appendConvergeRecord} with `randomUUID()` (the same
+   * mint `./lease.ts` uses for a lease token) when the caller doesn't supply
+   * one. Optional on the type because `version: 1` records written before
+   * #2027 have none — a reader must handle its absence, not assume it.
+   */
+  id?: string;
   /** The ConvergeOp's name (`OpConfig.name`). */
   op: string;
   env: string;
@@ -67,6 +156,18 @@ export interface ConvergeTickRecord {
   firedRuleIds: string[];
   /** Per-rule outcome, for every fired rule. */
   outcomes: ConvergeRuleOutcome[];
+  /**
+   * The per-component verdicts this tick observed (#2027), behind the
+   * aggregate counts in `summary`.
+   *
+   * The tick derives these to compute `summary.drifted` and the whole-tick
+   * `status`, and used to throw them away — so a reader could say "this
+   * environment drifted twice this hour" but could not colour the node that
+   * drifted, or name the single unobserved component whose `unknown` verdict
+   * refused remediation for everything else. Optional because `version: 1`
+   * records written before #2027 have none; absent is not "no components".
+   */
+  components?: ConvergeComponentVerdict[];
   /** Aggregate counts backing the tick's one log line. */
   summary: {
     drifted: number;
@@ -90,6 +191,13 @@ export type ConvergeTickRecordInput = Omit<ConvergeTickRecord, "version">;
  * `pushLifecycle` (./git.ts) afterward, same two-step shape every other
  * ledger write here uses.
  *
+ * Mints `record.id` (#2027) when the input doesn't carry one, so every tick
+ * written from here on is referenceable. Unlike `timestamp`, which stays
+ * caller-supplied because library code never calls `Date.now()` internally,
+ * an id has nothing for a caller to decide — the mint lives here so no
+ * writer can forget it. An explicit `input.id` still wins, which is what a
+ * test asserting an exact record 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
@@ -108,8 +216,8 @@ export type ConvergeTickRecordInput = Omit<ConvergeTickRecord, "version">;
 export async function appendConvergeRecord(
   input: ConvergeTickRecordInput,
   opts?: { cwd?: string },
-): Promise<{ commit: string; record: ConvergeTickRecord }> {
-  const record: ConvergeTickRecord = { version: 1, ...input };
+): Promise<{ commit: string; record: ConvergeTickRecord & { id: string } }> {
+  const record: ConvergeTickRecord & { id: string } = { version: 1, ...input, id: input.id ?? randomUUID() };
   const json = JSON.stringify(record, sortedJsonReplacer);
 
   let lastErr: unknown;

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

@@ -3,7 +3,7 @@ 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 { appendGateResolution, readGateResolutions, latestResolutionSince, resolveApprovalUrl, isApprovalUrl } from "./gate-ledger";
 import { readBlobFromPath } from "./git";
 
 function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
@@ -100,4 +100,84 @@ describe("lifecycle/gate-ledger", () => {
       expect(latestResolutionSince([], "g1", "2026-01-01T00:00:00.000Z")).toBeUndefined();
     });
   });
+  // ── Gate-as-fact carries an address (#2028) ──────────────────────────────
+
+  describe("resolveApprovalUrl", () => {
+    test("a GitHub Actions pull_request run resolves to that PR", () => {
+      expect(resolveApprovalUrl({
+        GITHUB_SERVER_URL: "https://github.com",
+        GITHUB_REPOSITORY: "INTENTIUS/chant",
+        GITHUB_REF_NAME: "2028/merge",
+      })).toBe("https://github.com/INTENTIUS/chant/pull/2028");
+    });
+
+    test("honours a GitHub Enterprise server url, trailing slash and all", () => {
+      expect(resolveApprovalUrl({
+        GITHUB_SERVER_URL: "https://ghe.example.com/",
+        GITHUB_REPOSITORY: "org/repo",
+        GITHUB_REF_NAME: "7/head",
+      })).toBe("https://ghe.example.com/org/repo/pull/7");
+    });
+
+    test("a GitLab merge-request pipeline resolves to that MR", () => {
+      expect(resolveApprovalUrl({
+        CI_MERGE_REQUEST_PROJECT_URL: "https://gitlab.com/org/repo",
+        CI_MERGE_REQUEST_IID: "42",
+      })).toBe("https://gitlab.com/org/repo/-/merge_requests/42");
+    });
+
+    test("a push-event CI run, or no CI at all, has no address — undefined, never a guess", () => {
+      expect(resolveApprovalUrl({ GITHUB_REPOSITORY: "org/repo", GITHUB_REF_NAME: "main" })).toBeUndefined();
+      expect(resolveApprovalUrl({ GITHUB_REF_NAME: "3/merge" })).toBeUndefined();
+      expect(resolveApprovalUrl({ CI_MERGE_REQUEST_PROJECT_URL: "https://gitlab.com/org/repo" })).toBeUndefined();
+      expect(resolveApprovalUrl({})).toBeUndefined();
+    });
+  });
+
+  describe("isApprovalUrl", () => {
+    test("accepts absolute http/https", () => {
+      expect(isApprovalUrl("https://github.com/org/repo/pull/1")).toBe(true);
+      expect(isApprovalUrl("http://localhost:3000/pr/1")).toBe(true);
+    });
+
+    test("refuses anything a reader could not follow as a link", () => {
+      for (const bad of ["", "org/repo/pull/1", "/pull/1", "file:///etc/passwd", "javascript:alert(1)", "not a url"]) {
+        expect(isApprovalUrl(bad)).toBe(false);
+      }
+    });
+  });
+
+  test("a resolution round-trips its typed url alongside free-text note", 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",
+          note: "rolled staging first",
+          url: "https://github.com/INTENTIUS/chant/pull/2028",
+        },
+        { cwd: dir },
+      );
+      const { records } = await readGateResolutions("fountain-apply", { cwd: dir });
+      expect(records).toEqual([record]);
+      expect(records[0].url).toBe("https://github.com/INTENTIUS/chant/pull/2028");
+      expect(records[0].note).toBe("rolled staging first");
+    });
+  });
+
+  test("a pre-#2028 resolution with no url still reads", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await appendGateResolution(
+        { op: "fountain-apply", gate: "g", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+        { cwd: dir },
+      );
+      const { records, malformed } = await readGateResolutions("fountain-apply", { cwd: dir });
+      expect(malformed).toBe(0);
+      expect(records[0].url).toBeUndefined();
+    });
+  });
 });

package/src/lifecycle/gate-ledger.ts

@@ -42,6 +42,58 @@ import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASCo
 const DIR = "_gates";
 const APPEND_RETRY_ATTEMPTS = 5;
 
+/**
+ * The address of the approval surface for a gate, resolved from the CI
+ * environment (#2028).
+ *
+ * #1485's argument for gate-as-fact was that approval gets an address:
+ * "gate-as-PR gives approval a URL, a review surface, and CODEOWNERS as the
+ * authorization model." What shipped recorded the gate and not the address,
+ * so a pending-approval card had nothing to link to and gate-as-PR stayed a
+ * convention. This is the narrow, honest half of that: when a tick (or a
+ * `chant approve`) runs inside the PR/MR job that carries the change, the
+ * loop genuinely knows where approval happens, and says so. Anywhere else it
+ * returns `undefined` and the field is simply absent — never a guess, never a
+ * synthesized link.
+ *
+ * The env-var fallback chain is the same one `--actor` and `--run-id` already
+ * use (`../cli/handlers/components.ts`): GitHub Actions first, then GitLab CI.
+ *
+ * - GitHub Actions on a `pull_request` event: `GITHUB_SERVER_URL` +
+ *   `GITHUB_REPOSITORY` + the PR number, which `GITHUB_REF_NAME` carries as
+ *   `<n>/merge`. A push-event run has no PR, so it resolves to nothing.
+ * - GitLab CI on a merge-request pipeline: `CI_MERGE_REQUEST_PROJECT_URL` +
+ *   `CI_MERGE_REQUEST_IID`.
+ */
+export function resolveApprovalUrl(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const prNumber = /^(\d+)\/(merge|head)$/.exec(env.GITHUB_REF_NAME ?? "")?.[1];
+  if (prNumber && env.GITHUB_REPOSITORY) {
+    const server = (env.GITHUB_SERVER_URL ?? "https://github.com").replace(/\/$/, "");
+    return `${server}/${env.GITHUB_REPOSITORY}/pull/${prNumber}`;
+  }
+
+  if (env.CI_MERGE_REQUEST_PROJECT_URL && env.CI_MERGE_REQUEST_IID) {
+    return `${env.CI_MERGE_REQUEST_PROJECT_URL.replace(/\/$/, "")}/-/merge_requests/${env.CI_MERGE_REQUEST_IID}`;
+  }
+
+  return undefined;
+}
+
+/**
+ * Whether `raw` is an address worth recording as one: an absolute `http`/
+ * `https` URL. A gate's address is a link a reader is expected to follow, so
+ * a relative path or a `file:`/`javascript:` scheme is refused at the CLI
+ * boundary rather than written into an immutable record.
+ */
+export function isApprovalUrl(raw: string): boolean {
+  try {
+    const parsed = new URL(raw);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
 /** One immutable gate-resolution record. */
 export interface GateResolutionRecord {
   /** Schema version, so an incompatible future shape is detected before being misread. */
@@ -54,8 +106,19 @@ export interface GateResolutionRecord {
   resolvedBy: string;
   /** ISO-8601 timestamp, caller-supplied (library code never calls `Date.now()` internally). */
   timestamp: string;
-  /** Optional free-text context (e.g. a PR URL — "or a merged PR" is the issue's other resolution path; recording its link here keeps both paths visible from one ledger). */
+  /** Optional free-text context. Before #2028 this was also where a PR link went by convention; put the link in {@link GateResolutionRecord.url} instead and leave this for prose. */
   note?: string;
+  /**
+   * The address this resolution happened at (#2028) — the PR that carried the
+   * change, the review thread, whatever the approval surface was. Typed, so
+   * "resolved by this PR" is machine-readable instead of a reader sniffing
+   * `note` for something that looks like a link.
+   *
+   * `chant approve --url` sets it; absent when the resolver genuinely had no
+   * address (a human at a terminal, no PR). Always an absolute `http`/`https`
+   * URL — see {@link isApprovalUrl}.
+   */
+  url?: string;
 }
 
 export type GateResolutionInput = Omit<GateResolutionRecord, "version">;