@intentius/chant 0.100.0 → 0.102.0

package/src/cli/registry.ts

@@ -75,6 +75,8 @@ export interface ParsedArgs {
   migrateFrom?: string;
   /** `chant import --kustomize <dir>` — render the kustomization, then import (#1548) */
   kustomize?: string;
+  /** `chant import --parser-option key[=value]`, repeatable (#2994): options for the lexicon's template parser */
+  parserOption?: string[];
   /** `chant carve advise --state <path>` — opt-in .tfstate for accurate instance counts */
   statePath?: string;
   /** `chant carve emit --select <tf-address>` — the Terraform resource to carve */
@@ -133,6 +135,16 @@ export interface ParsedArgs {
   namespace?: string;
   /** `chant workspace upgrade --allow-code` (#2550) — run migrations whose body is the template's own code. */
   allowCode?: boolean;
+  /** `chant workspace upgrade --source <repo>[#<member>]` (#2551): move the scope to another template. */
+  source?: string;
+  /** `chant workspace adopt-lineage --tags <glob>` and `hash-index --tags` (#2551): the tags to compare. */
+  tags?: string;
+  /** `chant workspace adopt-lineage --index <file>` (#2551): a cached hash index. */
+  index?: string;
+  /** `chant workspace versions --available` (#2551): list each git template's version tags. */
+  available?: boolean;
+  /** `chant workspace import --remove` (#2552): remove the export member instead of writing it again. */
+  remove?: boolean;
   /** `chant lifecycle rollback --dry-run` — compute the rollback delta and print it; open no PR, push nothing, leave no branch. */
   dryRun?: boolean;
   /** `chant lifecycle teardown <env> --yes` — execute the planned deletion
@@ -303,7 +315,7 @@ export interface ParsedArgs {
   noCache?: boolean;
   /** `chant workspace graph --composites` (#2662): print each composite instance with the components that can deploy it. */
   composites?: boolean;
-  /** `chant workspace graph --intent <path[:start-end]>` (#2651): the region the intent graph is over. Empty with `--record`. */
+  /** `chant workspace graph --intent <path[:start-end]|path#symbol>` (#2651): the region the intent graph is over. Empty with `--record`. */
   intent?: string;
   /** `chant workspace graph --intent --record <id>`: walk one decision record over every entry its constrains lists. */
   record?: string;
@@ -319,6 +331,8 @@ export interface ParsedArgs {
   severity?: string;
   /** `chant workspace records --current` (#2546): leave out records a closed record supersedes. */
   current?: boolean;
+  /** `chant workspace records --uncommitted` (#3160): only the records the working tree holds modified or new against HEAD. */
+  uncommitted?: boolean;
   /** `chant workspace records amend <id> --set <file|->` (#2670): the JSON fields to set. */
   set?: string;
   /** `chant workspace records review <id> --verdict <v>` (#2670): agree, dissent or abstain. */
@@ -334,6 +348,7 @@ export interface ParsedArgs {
   /**
    * `chant workspace records review <id> --sign [<key file>]` (#2687): the key that seals the verdict, or true for git's user.signingkey.
    * On `records new` and `records amend`, the key that seals the record's author (#2688).
+   * On `chant approve` and `chant run approve`, the key that seals the gate approval (#3163).
    */
   sign?: string | true;
   /** `chant workspace records review <id> --session <id>` (#2670): the review session the verdict was given in. */
@@ -342,6 +357,18 @@ export interface ParsedArgs {
   prefix?: string;
   /** `chant workspace records|verify --require attested` (#2547): the provenance level a gate requires. */
   require?: string;
+  /** `chant workspace evidence sign --key` (a runner's Ed25519 PEM) and `signers sign --key` (an ssh private key) (#2553). */
+  key?: string;
+  /** `chant workspace evidence sign --check-id <id>` (#2553): the check the evidence is for. */
+  checkId?: string;
+  /** `chant workspace evidence sign --claim <file>` (#2553): hashed into the evidence. */
+  claim?: string;
+  /** `chant workspace evidence sign --environment <file>` (#2553): the runner environment, hashed into the evidence. */
+  environment?: string;
+  /** `chant workspace evidence verify --envelope <file>` (#2553). */
+  envelope?: string;
+  /** `chant workspace signers rotate --threshold <n>` (#2553). */
+  threshold?: string;
   /**
    * `chant build --root-only` and `chant lint --root-only` (#2537): run on the
    * root project of a declared workspace, members left out, instead of
@@ -454,6 +481,10 @@ export interface ParsedArgs {
    * project's only steward.
    */
   steward?: string;
+  /** `chant workspace runs --unit <id>` (#3033): only the agent runs on this work item. */
+  unit?: string;
+  /** `chant workspace runs --decision <id>` (#3033): only the agent runs that carried out this decision. */
+  decision?: string;
   /** `chant workspace work claim|renew|release <id> --holder <name>` (#2732): who holds, or releases, the work lease. */
   holder?: string;
   /** `chant run <op> --work <id>` (#2748): the work item an Op with a work lease runs under. `chant workspace check --changes --work <id>` (#2773): the work item in hand. */
@@ -462,7 +493,7 @@ export interface ParsedArgs {
   ttl?: string;
   /** `chant workspace work renew|release <id> --token <token>` (#2732): the fencing token the caller holds. */
   token?: string;
-  /** `chant workspace work release <id> --outcome <text>` (#2732): how the work ended, such as done or not_done. */
+  /** `chant workspace work release <id> --outcome <outcome>` (#2732): how the work ended, one of the closed list WORK_LEASE_OUTCOMES (#3147). */
   outcome?: 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;

package/src/cli/serve-mcp-workspace.test.ts

@@ -70,7 +70,7 @@ describe("chant serve mcp at a workspace root with no lexicon of its own (#2700)
     expect(init.serverInfo.name).toBe("chant");
     for (const name of CORE_TOOLS) expect(tools).toContain(name);
     expect(tools).toContain("docker:diff");
-    expect(init.instructions).toContain("Member delivery (delivery/) declares docker.");
+    expect(init.instructions).toContain("Member delivery (delivery/) declares docker, otel.");
   }, TIMEOUT);
 
   test("a lexiconless root, lexicons only in a member, serves core and the lexicons that load", () => {

package/src/codegen/pinned-upgrade-multi.test.ts

@@ -0,0 +1,157 @@
+import { describe, test, expect, afterEach, vi } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { loadUpstreamPins, checkPinnedUpgrades, checkPinnedUpgrade, pinsOfPlugin } from "./pinned-upgrade";
+import { printPinnedUpgradeResults } from "../cli/commands/pinned-upgrade";
+import type { UpstreamPin } from "../lexicon";
+
+// The sql lexicon declares ClickHouse's pin and five Postgres pins (#3288).
+const sqlDir = join(__dirname, "../../../../lexicons/sql");
+
+// Recorded shape of GET /repos/postgres/postgres/tags (see pinned-upgrade-tags.test.ts),
+// with two newer minors added so the 14 and 17 pins have something to report.
+const recorded = JSON.parse(readFileSync(join(__dirname, "testdata", "postgres-tags.json"), "utf-8")) as Array<{ name: string }>;
+const tags = [...recorded, { name: "REL_17_12" }, { name: "REL_14_25" }, { name: "REL_19_BETA1" }];
+
+function stubGitHub() {
+  const urls: string[] = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      urls.push(url);
+      const u = new URL(url);
+      if (u.pathname.startsWith("/repos/postgres/postgres/tags")) {
+        const page = Number(u.searchParams.get("page"));
+        return new Response(JSON.stringify(page === 1 ? tags : []), { status: 200 });
+      }
+      if (u.pathname.startsWith("/repos/ClickHouse/ClickHouse/releases")) {
+        return new Response(JSON.stringify([{ tag_name: "v99.1.1.1-lts" }, { tag_name: "v26.8.15.10-lts" }]), { status: 200 });
+      }
+      return new Response("not found", { status: 404 });
+    }),
+  );
+  return urls;
+}
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("pinsOfPlugin", () => {
+  const pin = (label?: string): UpstreamPin => ({
+    ...(label ? { label } : {}),
+    file: "f",
+    pattern: /x/,
+    replace: (v) => v,
+    upstream: { owner: "o", repo: "r", kind: "releases" },
+  });
+
+  test("a lone upstreamPin is labelled by its own label, else the lexicon", () => {
+    expect(pinsOfPlugin({ upstreamPin: pin() }, "k8s").map((p) => p.label)).toEqual(["k8s"]);
+    expect(pinsOfPlugin({ upstreamPin: pin("main") }, "k8s").map((p) => p.label)).toEqual(["main"]);
+  });
+
+  test("upstreamPin comes first, then upstreamPins in order", () => {
+    const labels = pinsOfPlugin({ upstreamPin: pin("a"), upstreamPins: [pin("b"), pin("c")] }, "x").map((p) => p.label);
+    expect(labels).toEqual(["a", "b", "c"]);
+  });
+
+  test("no pins", () => {
+    expect(pinsOfPlugin({}, "aws")).toEqual([]);
+  });
+});
+
+describe("sql declares six pins", () => {
+  test("clickhouse first, then postgres-14 to postgres-18", async () => {
+    const pins = await loadUpstreamPins("sql", sqlDir);
+    expect(pins.map((p) => p.label)).toEqual(["clickhouse", "postgres-14", "postgres-15", "postgres-16", "postgres-17", "postgres-18"]);
+    // The digest sits beside the version in both, so neither is rewritten blind.
+    for (const { pin } of pins) expect(pin.alsoMoves).toMatch(/digest/);
+  });
+});
+
+describe("checkPinnedUpgrades on the sql lexicon (network mocked)", () => {
+  test("reports each pin, in order, and edits nothing", async () => {
+    stubGitHub();
+    const pinFiles = ["src/spec/pin.ts", "src/spec/postgres-pin.ts"].map((f) => join(sqlDir, f));
+    const before = pinFiles.map((f) => readFileSync(f, "utf-8"));
+    const results = await checkPinnedUpgrades({ lexiconDir: sqlDir, lexicon: "sql" });
+    expect(pinFiles.map((f) => readFileSync(f, "utf-8"))).toEqual(before);
+
+    const byPin = Object.fromEntries(results.map((r) => [r.pin, r]));
+    expect(results.map((r) => r.pin)).toEqual(["clickhouse", "postgres-14", "postgres-15", "postgres-16", "postgres-17", "postgres-18"]);
+    expect(results.every((r) => r.fetchError === null)).toBe(true);
+
+    expect(byPin["clickhouse"]).toMatchObject({ hasUpgrade: true, to: "v99.1.1.1-lts" });
+    // Each Postgres pin sees only its own major: 17 reports 17.12, never 18.6.
+    expect(byPin["postgres-14"]).toMatchObject({ hasUpgrade: true, from: "14.24", to: "14.25" });
+    expect(byPin["postgres-15"]).toMatchObject({ hasUpgrade: false, from: "15.19", to: "15.19" });
+    expect(byPin["postgres-16"]).toMatchObject({ hasUpgrade: false, from: "16.15", to: "16.15" });
+    expect(byPin["postgres-17"]).toMatchObject({ hasUpgrade: true, from: "17.11", to: "17.12" });
+    expect(byPin["postgres-18"]).toMatchObject({ hasUpgrade: false, from: "18.6", to: "18.6" });
+
+    // alsoMoves pins are report-only: instructions, no regen.
+    for (const label of ["clickhouse", "postgres-14", "postgres-17"]) {
+      expect(byPin[label]!.validation, label).toBeNull();
+      expect(byPin[label]!.manualPin?.instructions, label).toMatch(/digest/);
+    }
+    expect(byPin["postgres-17"]!.manualPin?.file).toBe("src/spec/postgres-pin.ts");
+    expect(byPin["postgres-15"]!.manualPin).toBeUndefined();
+  });
+
+  test("a pin label checks one pin and queries only its upstream", async () => {
+    const urls = stubGitHub();
+    const results = await checkPinnedUpgrades({ lexiconDir: sqlDir, lexicon: "sql", pin: "postgres-17" });
+    expect(results).toHaveLength(1);
+    expect(results[0]).toMatchObject({ pin: "postgres-17", to: "17.12" });
+    expect(urls.every((u) => u.includes("/repos/postgres/postgres/tags"))).toBe(true);
+
+    const ch = await checkPinnedUpgrades({ lexiconDir: sqlDir, lexicon: "sql", pin: "clickhouse" });
+    expect(ch).toHaveLength(1);
+    expect(ch[0]).toMatchObject({ pin: "clickhouse", hasUpgrade: true });
+  });
+
+  test("an unknown label names the pins there are", async () => {
+    const [r] = await checkPinnedUpgrades({ lexiconDir: sqlDir, lexicon: "sql", pin: "postgres-13" });
+    expect(r!.fetchError).toMatch(/no pin labelled "postgres-13"/);
+    expect(r!.fetchError).toMatch(/clickhouse, postgres-14/);
+  });
+
+  test("a network failure on one pin leaves the others reported", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string) =>
+        url.includes("/repos/ClickHouse/") ? new Response("boom", { status: 404 }) : new Response(JSON.stringify(url.includes("page=1") ? tags : []), { status: 200 }),
+      ),
+    );
+    const results = await checkPinnedUpgrades({ lexiconDir: sqlDir, lexicon: "sql" });
+    expect(results[0]!.fetchError).toBeTruthy();
+    expect(results[4]).toMatchObject({ pin: "postgres-17", to: "17.12", fetchError: null });
+  });
+
+  test("checkPinnedUpgrade (singular) still checks the first pin, ClickHouse", async () => {
+    stubGitHub();
+    const r = await checkPinnedUpgrade({ lexiconDir: sqlDir, lexicon: "sql" });
+    expect(r.pin).toBe("clickhouse");
+  });
+});
+
+describe("printPinnedUpgradeResults", () => {
+  test("several results print as a JSON array carrying each pin", async () => {
+    stubGitHub();
+    const results = await checkPinnedUpgrades({ lexiconDir: sqlDir, lexicon: "sql" });
+    const out: string[] = [];
+    const spy = vi.spyOn(console, "log").mockImplementation((...a: unknown[]) => void out.push(a.join(" ")));
+    try {
+      printPinnedUpgradeResults(results, true);
+      const parsed = JSON.parse(out.join("\n")) as Array<{ pin: string; to: string }>;
+      expect(parsed.map((p) => p.pin)).toEqual(results.map((r) => r.pin));
+      out.length = 0;
+      process.env.NO_COLOR = "1";
+      printPinnedUpgradeResults(results, false);
+      expect(out.join("\n")).toContain("[sql/postgres-17] upgrade available  17.11 -> 17.12");
+      expect(out.join("\n")).toContain("[sql/postgres-18] up to date");
+    } finally {
+      delete process.env.NO_COLOR;
+      spy.mockRestore();
+    }
+  });
+});

package/src/codegen/pinned-upgrade-tags.test.ts

@@ -0,0 +1,112 @@
+import { describe, test, expect, afterEach, vi } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { pickLatest, resolverFor } from "./pinned-upgrade";
+import type { UpstreamPin } from "../lexicon";
+
+// Recorded shape of GET /repos/postgres/postgres/tags: names only, no releases exist.
+const tags = JSON.parse(readFileSync(join(__dirname, "testdata", "postgres-tags.json"), "utf-8")) as Array<{
+  name: string;
+}>;
+
+/** What a postgres pin declares: REL_18_6 maps to 18.6, everything else is skipped. */
+const relTag = (t: string): string | null => {
+  const m = /^REL_(\d+)_(\d+)$/.exec(t);
+  return m ? `${m[1]}.${m[2]}` : null;
+};
+
+describe("pickLatest with tagVersion (postgres REL_ tags)", () => {
+  test("maps REL_18_6 to 18.6 and picks the highest GA version", () => {
+    expect(pickLatest(tags, "tags", { tagVersion: relTag })).toBe("18.6");
+  });
+
+  test("orders numerically, not lexically (17.11 beats 17.9)", () => {
+    const t = ["REL_17_9", "REL_17_11", "REL_17_10"].map((name) => ({ name }));
+    expect(pickLatest(t, "tags", { tagVersion: relTag })).toBe("17.11");
+  });
+
+  test("skips betas and release candidates even if the mapper would take them", () => {
+    const t = ["REL_19_BETA4", "REL_18_RC1", "REL_18_BETA3", "REL_18_5"].map((name) => ({ name }));
+    expect(pickLatest(t, "tags", { tagVersion: (x) => x.replace(/^REL_/, "").replace(/_/g, ".") })).toBe("18.5");
+    expect(pickLatest(t, "tags", { tagVersion: relTag })).toBe("18.5");
+  });
+
+  test("sameMajorAs stays inside one major line", () => {
+    expect(pickLatest(tags, "tags", { tagVersion: relTag, sameMajorAs: "17.9" })).toBe("17.11");
+    expect(pickLatest(tags, "tags", { tagVersion: relTag, sameMajorAs: "14.1" })).toBe("14.24");
+  });
+
+  test("sameMajorAs accepts a pin that holds the raw tag", () => {
+    expect(pickLatest(tags, "tags", { tagVersion: relTag, sameMajorAs: "REL_16_2" })).toBe("16.15");
+  });
+
+  test("a major with no stable tag yields null", () => {
+    expect(pickLatest(tags, "tags", { tagVersion: relTag, sameMajorAs: "19.0" })).toBeNull();
+  });
+});
+
+describe("pickLatest without the new options is unchanged", () => {
+  test("REL_ tags are not versions, so nothing is found", () => {
+    expect(pickLatest(tags, "tags")).toBeNull();
+  });
+
+  test("plain semver tags with a suffix filter and pre-release skip", () => {
+    const t = ["v17.9.0-ee", "v17.10.0-rc1-ee", "v17.8.1-ee", "v18.0.0"].map((name) => ({ name }));
+    expect(pickLatest(t, "tags", { tagSuffix: "-ee" })).toBe("v17.9.0-ee");
+  });
+
+  test("releases honour the prerelease flag", () => {
+    const r = [
+      { tag_name: "v1.33.0", prerelease: true },
+      { tag_name: "v1.32.1" },
+      { tag_name: "v1.32.0" },
+    ];
+    expect(pickLatest(r, "releases")).toBe("v1.32.1");
+  });
+});
+
+describe("resolverFor reads every page of tags when tagVersion is set", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  const pin = (upstream: Partial<UpstreamPin["upstream"]>): UpstreamPin => ({
+    file: "src/spec/pin.ts",
+    pattern: /x/,
+    replace: (v, l) => l + v,
+    upstream: { owner: "postgres", repo: "postgres", kind: "tags", ...upstream },
+  });
+
+  function stubPages(pages: Array<Array<{ name: string }>>) {
+    const urls: string[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string) => {
+        urls.push(url);
+        const n = Number(new URL(url).searchParams.get("page"));
+        return new Response(JSON.stringify(pages[n - 1] ?? []), { status: 200 });
+      }),
+    );
+    return urls;
+  }
+
+  test("finds a version that is only on the second page", async () => {
+    const filler = Array.from({ length: 100 }, (_, i) => ({ name: `REL9_${i}_0` }));
+    const urls = stubPages([filler, [{ name: "REL_18_6" }, { name: "REL_18_BETA1" }]]);
+    const latest = await resolverFor(pin({ tagVersion: relTag }), "18.5")();
+    expect(latest).toBe("18.6");
+    expect(urls).toHaveLength(2);
+    expect(urls[0]).toContain("per_page=100&page=1");
+  });
+
+  test("trackMajor uses the pinned value", async () => {
+    stubPages([tags]);
+    expect(await resolverFor(pin({ tagVersion: relTag, trackMajor: true }), "16.2")()).toBe("16.15");
+    expect(await resolverFor(pin({ tagVersion: relTag }), "16.2")()).toBe("18.6");
+  });
+
+  test("without tagVersion only the first page is read, as before", async () => {
+    const urls = stubPages([Array.from({ length: 50 }, () => ({ name: "v1.0.0" })), [{ name: "v9.0.0" }]]);
+    expect(await resolverFor(pin({ kind: "tags" }), "v1.0.0")()).toBe("v1.0.0");
+    expect(urls).toHaveLength(1);
+    expect(urls[0]).toContain("per_page=50");
+  });
+});

package/src/codegen/pinned-upgrade.test.ts

@@ -12,8 +12,11 @@ import {
   revertVersionBump,
   checkPinnedUpgrade,
   loadUpstreamPin,
+  lexiconNameOf,
+  applyPinnedVersionBump,
   type LexiconId,
 } from "./pinned-upgrade";
+import { runPinnedUpgrade } from "../cli/commands/pinned-upgrade";
 
 // ── Version parsing / comparison ──────────────────────────────────────
 
@@ -397,3 +400,104 @@ describe("loadUpstreamPin — pin descriptors come from the lexicon plugins (#68
     expect(await loadUpstreamPin("definitely-not-a-lexicon")).toBeNull();
   });
 });
+
+// ── #3258: any lexicon that declares upstreamPin, loaded from its directory ──
+
+describe("loadUpstreamPin from a lexicon directory (#3258)", () => {
+  const repoLexicons = join(__dirname, "../../../../lexicons");
+
+  test("sql: -lts tag suffix, a replace that strips the tag, and a companion-digest note", async () => {
+    const dir = join(repoLexicons, "sql");
+    const pin = await loadUpstreamPin(lexiconNameOf(dir), dir);
+    expect(pin?.upstream).toEqual({ owner: "ClickHouse", repo: "ClickHouse", kind: "releases", tagSuffix: "-lts" });
+    expect(pin?.alsoMoves).toMatch(/CLICKHOUSE_IMAGE_DIGEST/);
+    expect(pin?.replace("v26.8.20.5-lts", 'export const CLICKHOUSE_VERSION = "26.8.15.10";')).toBe(
+      'export const CLICKHOUSE_VERSION = "26.8.20.5";',
+    );
+  });
+
+  test("k3s and cedar declare a pin and no companion note", async () => {
+    for (const name of ["k3s", "cedar"]) {
+      const dir = join(repoLexicons, name);
+      const pin = await loadUpstreamPin(lexiconNameOf(dir), dir);
+      expect(pin, name).not.toBeNull();
+      expect(pin?.alsoMoves, name).toBeUndefined();
+    }
+  });
+
+  test("lexiconNameOf reads the package name, then the directory name", () => {
+    expect(lexiconNameOf(join(repoLexicons, "sql"))).toBe("sql");
+    const root = mkdtempSync(join(tmpdir(), "chant-name-"));
+    try {
+      expect(lexiconNameOf(root)).toBe(root.split("/").pop());
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("a directory whose plugin has no upstreamPin gets a clear message", async () => {
+    const result = await runPinnedUpgrade({ lexiconDir: join(repoLexicons, "aws") });
+    expect(result.hasUpgrade).toBe(false);
+    expect(result.fetchError).toMatch(/declares no upstreamPin/);
+  });
+});
+
+describe("pinned-upgrade for a pin that moves with a digest (sql shape, network mocked)", () => {
+  function sqlShaped(root: string): { dir: string; pin: string } {
+    const dir = makeWorkingLexicon(root, "sql", "src/spec/pin.ts", [
+      'export const CLICKHOUSE_VERSION = "26.8.15.10";',
+      'export const CLICKHOUSE_IMAGE_DIGEST = "sha256:aaaa";',
+      "",
+    ].join("\n"));
+    return { dir, pin: join(dir, "src/spec/pin.ts") };
+  }
+
+  test("reports the newer -lts version with instructions and edits nothing", async () => {
+    const root = mkdtempSync(join(tmpdir(), "chant-up-"));
+    try {
+      const { dir, pin } = sqlShaped(root);
+      const before = readFileSync(pin, "utf-8");
+      const result = await checkPinnedUpgrade({
+        lexiconDir: dir,
+        lexicon: "sql",
+        resolverOverride: async () => "v26.8.20.5-lts",
+      });
+      expect(result.hasUpgrade).toBe(true);
+      expect(result.from).toBe("26.8.15.10");
+      expect(result.to).toBe("v26.8.20.5-lts");
+      expect(result.validation).toBeNull();
+      expect(result.manualPin?.file).toBe("src/spec/pin.ts");
+      expect(result.manualPin?.instructions).toMatch(/digest/);
+      expect(readFileSync(pin, "utf-8")).toBe(before);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("the -lts tag compares equal to the bare pinned version", async () => {
+    const root = mkdtempSync(join(tmpdir(), "chant-up-"));
+    try {
+      const { dir } = sqlShaped(root);
+      const result = await checkPinnedUpgrade({
+        lexiconDir: dir,
+        lexicon: "sql",
+        resolverOverride: async () => "v26.8.15.10-lts",
+      });
+      expect(result.hasUpgrade).toBe(false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("applyPinnedVersionBump refuses a pin it cannot rewrite generically", async () => {
+    const root = mkdtempSync(join(tmpdir(), "chant-up-"));
+    try {
+      const { dir, pin } = sqlShaped(root);
+      const before = readFileSync(pin, "utf-8");
+      await expect(applyPinnedVersionBump("sql", dir, "v26.8.20.5-lts")).rejects.toThrow(/generically/);
+      expect(readFileSync(pin, "utf-8")).toBe(before);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});