@intentius/chant 0.52.2 → 0.53.1

package/src/index.ts

@@ -53,6 +53,7 @@ export * from "./import/parser";
 export * from "./import/generator";
 export * from "./lexicon";
 export * from "./observation";
+export * from "./identity";
 export * from "./apply";
 export * from "./deep-observation";
 export * from "./owner-chain";

package/src/lexicon.ts

@@ -18,6 +18,7 @@ import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
 import type { IREdge } from "./graph-ir";
 import type { DescribeResourcesResult, UnobservedReason } from "./observation";
+import type { DescribeIdentityOptions, DescribeIdentityResult } from "./identity";
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
 import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption";
 import type { OwnerChainVerdict } from "./owner-chain";
@@ -46,6 +47,18 @@ export type {
   UnobservedReason,
 } from "./observation";
 
+// The identity contract (#1982), re-exported from the same entry so a
+// lexicon's `describeIdentity` types itself without a second import path.
+// Runtime helpers live in `@intentius/chant/identity`.
+export type {
+  DescribeIdentityOptions,
+  DescribeIdentityResult,
+  ResolvedIdentity,
+  UnresolvedIdentity,
+  IdentityRow,
+  IdentityStatus,
+} from "./identity";
+
 // Disruption classification (#1665), re-exported from the same entry so a
 // lexicon's `classifyDisruption` types itself without a second import path.
 // Runtime helpers live in `@intentius/chant/lifecycle/disruption`.
@@ -1083,6 +1096,46 @@ export interface LexiconPlugin {
    */
   describeStackStatus?(options: { environment: string; stack: string }): Promise<StackStatusObservation | null>;
 
+  /**
+   * Report the principal chant would act as in this substrate, and the scope
+   * that principal resolves to (#1982) — what `chant lifecycle whoami <env>`
+   * prints, one row per lexicon, before anything acts.
+   *
+   * Every implementation of {@link describeResources} already resolves this
+   * and throws it away: the bind reaches the provider on the applier's own
+   * transport, the k8s connector resolves a context and knows which binding
+   * produced it, the aws read client resolves a region and an endpoint. The
+   * answer has only ever surfaced as a `no-credentials` hole or, when the
+   * binding was wrong rather than missing, as a clean read of the wrong
+   * account.
+   *
+   * Implement it with the substrate's own cheap self-query —
+   * `sts:GetCallerIdentity`, `SelfSubjectReview`, the token introspection the
+   * forge already exposes. Two rules bind the implementation:
+   *
+   * - **Read-only.** `whoami` is pre-flight and never a gate. The self-query
+   *   must be one the substrate treats as a read of the caller's own identity;
+   *   it creates nothing and changes nothing.
+   * - **No credential in the answer.** An identity is a principal and a scope,
+   *   never a token, key or password. Where a substrate's only identity signal
+   *   IS a secret, report that fact in `source` without the value. Core
+   *   redacts credential material from every field as a backstop, which is not
+   *   a reason to put one there.
+   *
+   * `endpoint` must be the address this lexicon's live read resolves for the
+   * same environment. A whoami that names a binding the read does not use is
+   * worse than no whoami, so a test pins the two together.
+   *
+   * Returning `{ unresolved: { reason, detail } }` is a real answer and the
+   * required one when the identity cannot be resolved — `no-credentials` for
+   * "nothing is configured", `no-binding` for "this environment resolves to no
+   * target", `read-failed` for a self-query that errored. A throw degrades to
+   * `read-failed` for this lexicon alone and never fails the command. Omitting
+   * the method entirely reports `not reported`, which is honest; it is never
+   * rendered as an empty identity.
+   */
+  describeIdentity?(options: DescribeIdentityOptions): Promise<DescribeIdentityResult>;
+
   /**
    * Enumerate the resources this lexicon would delete for one marker identity
    * (#1222). Opt-in, and read-only here: this method names the would-delete

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">;

package/src/terraform/__fixtures__/gcp-estate/main.tf

@@ -0,0 +1,60 @@
+# A small google-provider estate for the carve-out advisor (#2017), mixed the
+# same way the AWS sample estate is: clean leaves, a hub with boundary work, a
+# tier-3 map, and one resource with no native mapping at all.
+
+# Clean leaf: a bucket nothing else reads.
+resource "google_storage_bucket" "assets" {
+  name     = "myapp-assets-prod"
+  location = "US"
+}
+
+# Clean leaf with one inbound edge: the subscription reads the topic.
+resource "google_pubsub_topic" "events" {
+  name = "myapp-events"
+}
+
+resource "google_pubsub_subscription" "worker" {
+  name  = "myapp-worker"
+  topic = google_pubsub_topic.events.name
+}
+
+# The hub: two subnets, a router and the cluster all reference the network, so
+# carving it costs four data-source patches to the surviving Terraform.
+resource "google_compute_network" "main" {
+  name                    = "myapp-vpc"
+  auto_create_subnetworks = false
+}
+
+resource "google_compute_subnetwork" "a" {
+  name          = "myapp-subnet-a"
+  ip_cidr_range = "10.0.1.0/24"
+  network       = google_compute_network.main.id
+}
+
+resource "google_compute_subnetwork" "b" {
+  name          = "myapp-subnet-b"
+  ip_cidr_range = "10.0.2.0/24"
+  network       = google_compute_network.main.id
+}
+
+resource "google_compute_router" "nat" {
+  name    = "myapp-router"
+  network = google_compute_network.main.id
+}
+
+# Tier 3: Config Connector inlines node pools the cluster also declares apart.
+resource "google_container_cluster" "primary" {
+  name       = "myapp-gke"
+  network    = google_compute_network.main.id
+  subnetwork = google_compute_subnetwork.a.id
+}
+
+# Identity lives in account_id here, not name.
+resource "google_service_account" "runner" {
+  account_id = "myapp-runner"
+}
+
+# Leave in Terraform: no native mapping, scored 0.
+resource "random_pet" "suffix" {
+  length = 2
+}