@intentius/chant 0.101.0 → 0.104.0

package/src/op/activities/index.ts

@@ -25,6 +25,8 @@ export type { ReleaseRollbackPlanArgs, ReleaseRollbackPlanResult, ReleaseRollbac
 export type { HttpCheckArgs, HttpFetch } from "./http-check";
 
 export { lifecycleSnapshot, lifecycleDiff } from "./lifecycle";
+export { composeChangeSet, lifecyclePlanChangeSet, readChangeSetPart } from "./change-set";
+export type { ComposeChangeSetArgs, ComposeChangeSetResult, LifecyclePlanChangeSetArgs, ReadChangeSetPartArgs, ChangeSetPartResult } from "./change-set";
 export type { LifecycleSnapshotArgs, LifecycleDiffArgs, LifecycleDiffResult } from "./lifecycle";
 
 export { chantTeardown } from "./teardown";
@@ -70,6 +72,9 @@ export type {
   AzureApplier,
   GcpApplier,
   FlyApplier,
+  GrafanaApplier,
+  ClickHouseApplier,
+  PostgresApplier,
   AwsApplier,
   AwsRollback,
 } from "./apply";
@@ -178,3 +183,7 @@ export type { ChangeCoverageArgs, ChangeCoverageResult } from "./change-coverage
 // loads the workspace code on first call.
 export { decide } from "./decide";
 export type { DecideArgs, DecideResult } from "./decide";
+
+// The factory reference Op's rules and hooks (#3406, ws-087): `factoryOp` in ../factory.ts declares them.
+export { factoryPick, factoryReady, factoryAsk, factoryBuild, factoryCheck, factoryRecord } from "./factory";
+export type { FactoryAskResult, FactoryBuildResult, FactoryCheckResult, FactoryRecordResult, FactoryPickResult, FactoryLease } from "./factory";

package/src/op/activities/lexicon-upgrade.test.ts

@@ -18,23 +18,37 @@ import type { UpgradeCheckResult } from "../../codegen/pinned-upgrade";
 import type { RollingUpgradeResult } from "../../codegen/rolling-upgrade";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { writeFileSync, readFileSync } from "node:fs";
+import { writeFileSync, readFileSync, mkdirSync } from "node:fs";
 
 // ── Classification ────────────────────────────────────────────────────
 
 describe("pinned vs rolling classification", () => {
-  test("pinned lexicons", () => {
-    for (const l of ["k8s", "gcp", "docker", "gitlab"] as const) {
-      expect(isPinned(l)).toBe(true);
+  const pin = {
+    file: "src/pin.ts",
+    pattern: /V = "(.+)"/,
+    replace: (v: string) => `V = "${v}"`,
+    upstream: { owner: "o", repo: "r", kind: "releases" as const },
+  };
+
+  test("pinned lexicons are any whose plugin declares upstreamPin", async () => {
+    const loadPin = vi.fn(async () => pin);
+    for (const l of ["k8s", "gcp", "docker", "gitlab", "sql", "k3s", "cedar"]) {
+      expect(await isPinned(l, "/x", loadPin)).toBe(true);
       expect(isRolling(l)).toBe(false);
     }
   });
 
-  test("rolling lexicons", () => {
+  test("a lexicon without a pin is not pinned", async () => {
+    expect(await isPinned("helm", "/x", async () => null)).toBe(false);
+  });
+
+  test("rolling lexicons", async () => {
+    const loadPin = vi.fn(async () => null);
     for (const l of ["aws", "azure", "github"] as const) {
       expect(isRolling(l)).toBe(true);
-      expect(isPinned(l)).toBe(false);
+      expect(await isPinned(l, "/x", loadPin)).toBe(false);
     }
+    expect(loadPin).not.toHaveBeenCalled();
   });
 });
 
@@ -389,6 +403,86 @@ describe("lexiconUpgrade breakage handling", () => {
 
 // ── out-of-scope rejection ────────────────────────────────────────────
 
+describe("discovered pinned lexicons (#3266)", () => {
+  const pin = {
+    file: "src/pin.ts",
+    pattern: /V = "(.+)"/,
+    replace: (v: string) => `V = "${v}"`,
+    upstream: { owner: "o", repo: "r", kind: "releases" as const },
+  };
+
+  test("a lexicon with a declared pin reaches the pinned check and opens a PR", async () => {
+    const checkPinned: CheckPinnedFn = vi.fn(async () => pinnedResult());
+    const applyBump = vi.fn(async () => ({ filePath: "/x/src/pin.ts" }));
+    const { gh } = recordingGh();
+    const dir = join(tmpdir(), `chant-3266-${process.pid}`);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ version: "0.1.0" }));
+    const r = await lexiconUpgrade({
+      lexicon: "k3s",
+      lexiconDir: dir,
+      mode: "pull-request",
+      _loadPin: async () => pin,
+      _checkPinned: checkPinned,
+      _applyBump: applyBump,
+      _bumpPackageVersion: vi.fn(),
+      _gh: gh,
+    });
+    expect(checkPinned).toHaveBeenCalledOnce();
+    expect(applyBump).toHaveBeenCalledWith("k3s", dir, "v1.33.0");
+    expect(r.hasUpgrade).toBe(true);
+  });
+
+  test("a lexicon with no pin and not rolling is rejected", async () => {
+    await expect(
+      lexiconUpgrade({ lexicon: "helm", mode: "report", _loadPin: async () => null }),
+    ).rejects.toThrow(/not supported/);
+  });
+
+  test("a discovered pin reaches the real check when none is injected", async () => {
+    const loadPin = vi.fn(async () => pin);
+    // The real checkPinnedUpgrade loads the pin itself; an empty dir has no
+    // plugin, so it reports the fetch error rather than throwing "not supported".
+    const r = await lexiconUpgrade({
+      lexicon: "sql",
+      lexiconDir: join(tmpdir(), "chant-3266-none"),
+      mode: "report",
+      _loadPin: loadPin,
+    });
+    expect(loadPin).toHaveBeenCalledOnce();
+    expect(r.validationOk).toBe(false);
+  });
+
+  test("an alsoMoves pin is report-only: newer version and manual step, no bump, no git", async () => {
+    const manual = pinnedResult({
+      validation: null,
+      from: "25.8.1.1-lts",
+      to: "26.3.1.1-lts",
+      manualPin: { file: "src/spec/pin.ts", instructions: "move CLICKHOUSE_IMAGE_DIGEST too" },
+    });
+    const applyBump = vi.fn();
+    const { gh, calls } = recordingGh();
+    for (const mode of ["report", "issue", "pull-request"] as const) {
+      const r = await lexiconUpgrade({
+        lexicon: "sql",
+        mode,
+        _checkPinned: vi.fn(async () => manual),
+        _applyBump: applyBump,
+        _gh: gh,
+      });
+      expect(r.hasUpgrade).toBe(true);
+      expect(r.mode).toBe("report");
+      expect(r.prUrl).toBeUndefined();
+      expect(r.issueUrl).toBeUndefined();
+      expect(r.summary).toContain("26.3.1.1-lts");
+      expect(r.summary).toContain("move CLICKHOUSE_IMAGE_DIGEST too");
+      expect(r.summary).toContain("src/spec/pin.ts");
+    }
+    expect(applyBump).not.toHaveBeenCalled();
+    expect(calls).toHaveLength(0);
+  });
+});
+
 describe("out-of-scope lexicons", () => {
   test("helm/forgejo throw", async () => {
     for (const l of ["helm", "forgejo"]) {
@@ -585,3 +679,63 @@ describe("lexiconUpgrade pull-request mode: package.json version bump", () => {
     }
   });
 });
+
+describe("a lexicon with several pins (#3288)", () => {
+  const manual = (pin: string, from: string, to: string): UpgradeCheckResult =>
+    pinnedResult({ pin, validation: null, from, to, manualPin: { file: "src/spec/postgres-pin.ts", instructions: `move the ${pin} digest too` } });
+  const current = (pin: string, v: string): UpgradeCheckResult => pinnedResult({ pin, validation: null, hasUpgrade: false, from: v, to: v });
+
+  test("every pin is reported; manual pins stay report-only in every mode", async () => {
+    const results = [current("clickhouse", "26.8.15.10"), manual("postgres-17", "17.11", "17.12"), manual("postgres-14", "14.24", "14.25")];
+    const applyBump = vi.fn();
+    const { gh, calls } = recordingGh();
+    for (const mode of ["report", "issue", "pull-request"] as const) {
+      const r = await lexiconUpgrade({ lexicon: "sql", mode, _checkPinned: vi.fn(async () => results), _applyBump: applyBump, _gh: gh });
+      expect(r.hasUpgrade).toBe(true);
+      expect(r.mode).toBe("report");
+      expect(r.summary).toContain("## Lexicon upgrade: sql (clickhouse)");
+      expect(r.summary).toContain("## Lexicon upgrade: sql (postgres-17)");
+      expect(r.summary).toContain("move the postgres-17 digest too");
+      expect(r.summary).toContain("move the postgres-14 digest too");
+    }
+    expect(applyBump).not.toHaveBeenCalled();
+    expect(calls).toHaveLength(0);
+  });
+
+  test("no pin has an upgrade: nothing to do", async () => {
+    const r = await lexiconUpgrade({
+      lexicon: "sql",
+      _checkPinned: vi.fn(async () => [current("clickhouse", "1.0"), current("postgres-18", "18.6")]),
+    });
+    expect(r.hasUpgrade).toBe(false);
+    expect(r.validationOk).toBe(true);
+  });
+
+  test("the pin label is forwarded to the check", async () => {
+    const check = vi.fn(async () => [current("postgres-16", "16.15")]);
+    await lexiconUpgrade({ lexicon: "sql", pin: "postgres-16", _checkPinned: check });
+    expect(check).toHaveBeenCalledWith(expect.objectContaining({ lexicon: "sql", pin: "postgres-16" }));
+  });
+
+  test("a rewritable pin leads: the PR branch, title and bump name the pin", async () => {
+    const results = [manual("clickhouse", "1.0", "2.0"), pinnedResult({ pin: "postgres-17", from: "17.11", to: "17.12" })];
+    const applyBump = vi.fn(async () => ({ filePath: "/x/pin.ts" }));
+    const { gh, calls } = recordingGh();
+    const dir = join(tmpdir(), `chant-3288-${process.pid}`);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ version: "0.1.0" }));
+    await lexiconUpgrade({
+      lexicon: "sql",
+      mode: "pull-request",
+      lexiconDir: dir,
+      _checkPinned: vi.fn(async () => results),
+      _applyBump: applyBump,
+      _bumpPackageVersion: vi.fn(() => "/x/package.json"),
+      _gh: gh,
+    });
+    expect(applyBump).toHaveBeenCalledWith("sql", dir, "17.12", "postgres-17");
+    expect(calls.some((c) => c.includes("lexicon-upgrade/sql-postgres-17"))).toBe(true);
+    expect(upgradeBranchName("sql", "postgres-17")).toBe("lexicon-upgrade/sql-postgres-17");
+    expect(upgradePrTitle("sql", "17.11", "17.12", "postgres-17")).toBe("feat(sql): upgrade postgres-17 17.11 to 17.12");
+  });
+});

package/src/op/activities/lexicon-upgrade.ts

@@ -1,6 +1,8 @@
 /**
  * lexiconUpgrade — the upgrade-detection and PR-automation activity for
- * in-scope lexicons (k8s, gcp, docker, gitlab, aws, azure, github).
+ * in-scope lexicons: every lexicon whose plugin declares `upstreamPin` (k8s,
+ * k3s, gcp, docker, gitlab, cedar, sql, ...) plus the rolling ones (aws, azure,
+ * github, fly).
  *
  * Classifies the lexicon as pinned or rolling, calls the right check function,
  * then surfaces the result in the requested mode: report (default), issue, or
@@ -25,7 +27,7 @@ import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import type { UpgradeCheckResult, LexiconId } from "../../codegen/pinned-upgrade";
+import type { UpgradeCheckResult, LexiconId, UpstreamPin } from "../../codegen/pinned-upgrade";
 import type { RollingUpgradeResult, RollingLexicon } from "../../codegen/rolling-upgrade";
 import { bumpForSeverity, bumpPackageJsonVersion } from "../../codegen/version-bump";
 import { postOrUpdateGithubIssue } from "./reconcile";
@@ -48,8 +50,9 @@ export type SemverLabel = "minor" | "breaking";
 export interface LexiconUpgradeArgs {
   /**
    * Which lexicon to check. Determines pinned vs rolling dispatch:
-   *   PINNED: k8s, gcp, docker, gitlab, cedar
    *   ROLLING: aws, azure, github, fly
+   *   PINNED: any other lexicon whose plugin declares `upstreamPin`
+   *           (discovered at run time, as `chant dev pinned-upgrade` does)
    */
   lexicon: SupportedLexicon;
   /**
@@ -57,11 +60,17 @@ export interface LexiconUpgradeArgs {
    * Defaults to `<cwd>/lexicons/<lexicon>`.
    */
   lexiconDir?: string;
+  /**
+   * Label of one pin to check, for a lexicon whose plugin declares several
+   * (`upstreamPins`). Omitted, every pin is checked and reported.
+   */
+  pin?: string;
   /** What to produce. Default: "report". */
   mode?: LexiconUpgradeMode;
   /**
-   * Override the pinned check function — inject a mock in tests.
-   * The real implementation calls checkPinnedUpgrade from core.
+   * Override the pinned check function — inject a mock in tests. It may
+   * return one result or one per pin.
+   * The real implementation calls checkPinnedUpgrades from core.
    */
   _checkPinned?: CheckPinnedFn;
   /**
@@ -77,6 +86,13 @@ export interface LexiconUpgradeArgs {
    * Override the applyPinnedVersionBump function — inject a mock in tests.
    */
   _applyBump?: ApplyBumpFn;
+  /**
+   * Override pin discovery — inject a mock in tests. The real one is
+   * `loadUpstreamPin` from core, the loader `chant dev pinned-upgrade` uses.
+   * Not consulted when `_checkPinned` is injected: that stands in for the
+   * whole pinned check.
+   */
+  _loadPin?: (lexicon: string, lexiconDir: string) => Promise<UpstreamPin | null>;
   /**
    * Override the package.json version writer — inject a mock in tests.
    * Defaults to bumpPackageJsonVersion.
@@ -109,9 +125,11 @@ export interface LexiconUpgradeResult {
 export type CheckPinnedFn = (opts: {
   lexiconDir: string;
   lexicon: LexiconId;
+  /** One pin's label; omitted, every pin of the plugin. */
+  pin?: string;
   force?: boolean;
   verbose?: boolean;
-}) => Promise<UpgradeCheckResult>;
+}) => Promise<UpgradeCheckResult | UpgradeCheckResult[]>;
 
 /** Matches checkRollingUpgrade from core. */
 export type CheckRollingFn = (opts: {
@@ -141,6 +159,7 @@ export type ApplyBumpFn = (
   lexicon: LexiconId,
   lexiconDir: string,
   newVersion: string,
+  pin?: string,
 ) => { filePath: string } | Promise<{ filePath: string }>;
 
 /**
@@ -177,21 +196,32 @@ export function computeBumpedVersion(
 
 // ── Classification ────────────────────────────────────────────────────
 
-// cedar pins `CEDAR_WASM_VERSION`, a dependency version rather than a spec
-// URL, but the pinned-constant machinery is the same (#1650).
-const PINNED_LEXICONS: ReadonlySet<string> = new Set<LexiconId>(["k8s", "gcp", "docker", "gitlab", "cedar"]);
+// Rolling lexicons follow their upstream spec with no version constant, so
+// they are a fixed list. Every other lexicon is pinned when its plugin declares
+// `upstreamPin` (cedar's CEDAR_WASM_VERSION, sql's ClickHouse version, k3s...):
+// discovered at run time, not listed here.
 const ROLLING_LEXICONS: ReadonlySet<string> = new Set<RollingLexicon>(["aws", "azure", "github", "fly"]);
 
-/** Return true when the lexicon uses a pinned version constant. */
-export function isPinned(lexicon: SupportedLexicon): lexicon is LexiconId {
-  return PINNED_LEXICONS.has(lexicon);
-}
-
 /** Return true when the lexicon follows a rolling spec (no pinned constant). */
 export function isRolling(lexicon: SupportedLexicon): lexicon is RollingLexicon {
   return ROLLING_LEXICONS.has(lexicon);
 }
 
+/**
+ * Return true when the lexicon's plugin declares an `upstreamPin` (loaded from
+ * `lexiconDir`, else from its installed package), the same discovery
+ * `chant dev pinned-upgrade` does.
+ */
+export async function isPinned(
+  lexicon: SupportedLexicon,
+  lexiconDir?: string,
+  loadPin?: (lexicon: string, lexiconDir: string) => Promise<UpstreamPin | null>,
+): Promise<boolean> {
+  if (isRolling(lexicon)) return false;
+  const load = loadPin ?? (async (l, d) => (await import("../../codegen/pinned-upgrade")).loadUpstreamPin(l, d));
+  return (await load(lexicon, lexiconDir ?? `${process.cwd()}/lexicons/${lexicon}`)) !== null;
+}
+
 // ── Semver labeling ───────────────────────────────────────────────────
 
 /**
@@ -210,8 +240,8 @@ export function severityToLabel(severity: string): SemverLabel | null {
 // ── Branch / PR naming ────────────────────────────────────────────────
 
 /** Long-lived branch name for a lexicon upgrade PR. */
-export function upgradeBranchName(lexicon: SupportedLexicon): string {
-  return `lexicon-upgrade/${lexicon}`;
+export function upgradeBranchName(lexicon: SupportedLexicon, pin?: string): string {
+  return pin ? `lexicon-upgrade/${lexicon}-${pin}` : `lexicon-upgrade/${lexicon}`;
 }
 
 /** PR title for an upgrade. */
@@ -219,8 +249,9 @@ export function upgradePrTitle(
   lexicon: SupportedLexicon,
   from?: string,
   to?: string | null,
+  pin?: string,
 ): string {
-  if (from && to) return `feat(${lexicon}): upgrade spec ${from} to ${to}`;
+  if (from && to) return `feat(${lexicon}): upgrade ${pin ? `${pin} ` : "spec "}${from} to ${to}`;
   return `feat(${lexicon}): upgrade to latest spec`;
 }
 
@@ -229,14 +260,18 @@ export function upgradePrTitle(
 /** Build the PR/issue/report body from the upgrade result data. */
 export function buildUpgradeSummary(opts: {
   lexicon: SupportedLexicon;
+  /** The pin's label, for a lexicon with several pins. */
+  pin?: string;
   from?: string;
   to?: string | null;
   deltaText: string;
   semverLabel: SemverLabel | null;
   validationOk: boolean;
   failures?: Array<{ step: string; output: string }>;
+  /** Set for a pin that moves with other constants: nothing was bumped or regenerated. */
+  manualPin?: { file: string; instructions: string };
 }): string {
-  const { lexicon, from, to, deltaText, semverLabel, validationOk, failures = [] } = opts;
+  const { lexicon, from, to, deltaText, semverLabel, validationOk, failures = [], manualPin } = opts;
 
   // Example validation status (#604): the upgrade check lints the lexicon's
   // examples (regenLexicon step 6), and an example failure makes validation
@@ -246,7 +281,7 @@ export function buildUpgradeSummary(opts: {
   // for rolling lexicons.)
   const exampleFailures = failures.filter((f) => f.step === "lint" || f.step === "examples");
 
-  const lines: string[] = [`## Lexicon upgrade: ${lexicon}`];
+  const lines: string[] = [`## Lexicon upgrade: ${lexicon}${opts.pin ? ` (${opts.pin})` : ""}`];
   if (from) lines.push(``, `**From:** \`${from}\`  **To:** \`${to ?? "latest"}\``);
   if (semverLabel) lines.push(`**Semver label:** \`${semverLabel}\``);
   lines.push(
@@ -257,6 +292,17 @@ export function buildUpgradeSummary(opts: {
 
   lines.push(``);
 
+  if (manualPin) {
+    lines.push(`### Manual pin bump`);
+    lines.push(``);
+    lines.push(
+      `This pin cannot be rewritten automatically, so nothing was edited or regenerated. ` +
+        `Edit \`${manualPin.file}\`: ${manualPin.instructions}`,
+    );
+    lines.push(``);
+    return lines.join("\n");
+  }
+
   if (!validationOk) {
     lines.push(`### Validation failures`);
     lines.push(``);
@@ -403,7 +449,7 @@ let _realApplyBump: ApplyBumpFn | null = null;
 async function getRealCheckPinned(): Promise<CheckPinnedFn> {
   if (!_realCheckPinned) {
     const mod = await import("../../codegen/pinned-upgrade");
-    _realCheckPinned = (opts) => mod.checkPinnedUpgrade(opts);
+    _realCheckPinned = (opts) => mod.checkPinnedUpgrades(opts);
   }
   return _realCheckPinned;
 }
@@ -419,8 +465,8 @@ async function getRealCheckRolling(): Promise<CheckRollingFn> {
 async function getRealApplyBump(): Promise<ApplyBumpFn> {
   if (!_realApplyBump) {
     const mod = await import("../../codegen/pinned-upgrade");
-    _realApplyBump = (lexicon, lexiconDir, newVersion) =>
-      mod.applyPinnedVersionBump(lexicon, lexiconDir, newVersion);
+    _realApplyBump = (lexicon, lexiconDir, newVersion, pin) =>
+      mod.applyPinnedVersionBump(lexicon, lexiconDir, newVersion, pin);
   }
   return _realApplyBump;
 }
@@ -430,9 +476,12 @@ async function getRealApplyBump(): Promise<ApplyBumpFn> {
 /**
  * Run the lexicon upgrade check for one lexicon and surface the result.
  *
- * Pinned lexicons (k8s, gcp, docker, gitlab):
+ * Pinned lexicons (any whose plugin declares `upstreamPin`):
  *   Calls checkPinnedUpgrade. A PR is opened only when hasUpgrade=true AND
  *   validation passed. Validation failures produce a report or issue.
+ *   A pin that moves with other constants (`alsoMoves`, sql's version plus
+ *   digest) is report-only: the summary names the newer version and the
+ *   manual step, and no branch, bump or PR is made.
  *
  * Rolling lexicons (aws, azure, github):
  *   Calls checkRollingUpgrade. A PR is opened only when the surface changed
@@ -472,20 +521,65 @@ export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconU
   let to: string | null | undefined;
   let freshSnapshotJson: string | null = null;
 
-  if (isPinned(lexicon)) {
+  // An injected check stands in for the whole pinned check, so discovery runs
+  // only on the real path.
+  const pinned = !isRolling(lexicon) && (args._checkPinned ? true : await isPinned(lexicon, lexiconDir, args._loadPin));
+  let manualPin: { file: string; instructions: string } | undefined;
+
+  let pinLabel: string | undefined;
+  let summaryOverride: string | undefined;
+
+  if (pinned) {
     const checkPinned = args._checkPinned ?? (await getRealCheckPinned());
-    const result = await checkPinned({ lexiconDir, lexicon });
+    const raw = await checkPinned({ lexiconDir, lexicon, ...(args.pin ? { pin: args.pin } : {}) });
+    const results = Array.isArray(raw) ? raw : [raw];
+    const multi = results.length > 1;
+
+    // The pin the rest of the flow (validation, bump, PR) acts on: the first
+    // one that has a rewritable upgrade, else the first with any finding.
+    // A pin with `alsoMoves` (manualPin) is report-only, so it never leads.
+    const rewritable = (r: UpgradeCheckResult) => r.hasUpgrade && !r.manualPin && !r.fetchError;
+    const result = results.find(rewritable) ?? results.find((r) => r.hasUpgrade || r.fetchError) ?? results[0]!;
+    if (multi) {
+      pinLabel = rewritable(result) ? result.pin : undefined;
+      const sections = results.map((r) =>
+        buildUpgradeSummary({
+          lexicon,
+          pin: r.pin,
+          from: r.from,
+          to: r.to,
+          deltaText: r.validation?.deltaText ?? "",
+          semverLabel: severityToLabel(r.validation?.severity ?? "none"),
+          validationOk: r.fetchError ? false : (r.validation?.ok ?? true),
+          failures: r.fetchError
+            ? [{ step: "upstream-fetch", output: r.fetchError }]
+            : (r.validation?.failures ?? []).map((f) => ({ step: f.step, output: f.output })),
+          manualPin: r.manualPin,
+        }),
+      );
+      const others = results.filter((r) => r !== result && rewritable(r));
+      if (others.length > 0) {
+        const names = others.map((r) => r.pin).join(", ");
+        sections.push(
+          "More than one pin has an upgrade this run can bump. This run acts on " + result.pin +
+            "; run it again with pin set to each of the others (" + names + ").",
+        );
+      }
+      summaryOverride = sections.join("\n\n");
+    }
 
     if (result.fetchError) {
-      const summary = buildUpgradeSummary({
-        lexicon,
-        from: result.from,
-        to: result.to,
-        deltaText: "",
-        semverLabel: null,
-        validationOk: false,
-        failures: [{ step: "upstream-fetch", output: result.fetchError }],
-      });
+      const summary =
+        summaryOverride ??
+        buildUpgradeSummary({
+          lexicon,
+          from: result.from,
+          to: result.to,
+          deltaText: "",
+          semverLabel: null,
+          validationOk: false,
+          failures: [{ step: "upstream-fetch", output: result.fetchError }],
+        });
       return {
         lexicon,
         mode,
@@ -497,9 +591,10 @@ export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconU
       };
     }
 
-    hasUpgrade = result.hasUpgrade;
+    hasUpgrade = results.some((r) => r.hasUpgrade && !r.fetchError);
     from = result.from;
     to = result.to;
+    manualPin = multi ? (rewritable(result) ? undefined : result.manualPin) : result.manualPin;
     severity = result.validation?.severity ?? "none";
     deltaText = result.validation?.deltaText ?? "";
     validationOk = result.validation?.ok ?? true;
@@ -524,20 +619,23 @@ export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconU
   } else {
     throw new Error(
       `Lexicon "${lexicon as string}" is not supported by LexiconUpgradeOp. ` +
-        `Supported: k8s, gcp, docker, gitlab, aws, azure, github`,
+        `Supported: the rolling lexicons (${[...ROLLING_LEXICONS].join(", ")}) and any lexicon whose plugin declares upstreamPin.`,
     );
   }
 
   const semverLabel = severityToLabel(severity);
-  const summary = buildUpgradeSummary({
-    lexicon,
-    from,
-    to,
-    deltaText,
-    semverLabel,
-    validationOk,
-    failures,
-  });
+  const summary =
+    summaryOverride ??
+    buildUpgradeSummary({
+      lexicon,
+      from,
+      to,
+      deltaText,
+      semverLabel,
+      validationOk,
+      failures,
+      manualPin,
+    });
 
   // ── 2. No upgrade ─────────────────────────────────────────────────
 
@@ -584,15 +682,20 @@ export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconU
 
   // ── 4. Upgrade ready: surface according to mode ───────────────────
 
-  const title = upgradePrTitle(lexicon, from, to);
+  const title = upgradePrTitle(lexicon, from, to, pinLabel);
 
   // #546: rolling lexicons have no version pin, so a "pull-request" would only
   // refresh the baseline snapshot — low signal, no build-output change. Surface
   // rolling drift as an issue instead; re-baselining stays a deliberate
   // maintainer action (`chant dev surface-diff <lexicon> --update-snapshot --bump`).
   // Pinned lexicons keep opening version-bump PRs.
-  const effectiveMode: LexiconUpgradeMode =
-    mode === "pull-request" && isRolling(lexicon) ? "issue" : mode;
+  // A pin that moves with other constants cannot be bumped here, so it is
+  // report-only whatever the mode.
+  const effectiveMode: LexiconUpgradeMode = manualPin
+    ? "report"
+    : mode === "pull-request" && isRolling(lexicon)
+      ? "issue"
+      : mode;
 
   if (effectiveMode === "report") {
     return {
@@ -622,7 +725,7 @@ export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconU
 
   // ── 5. pull-request mode: idempotent branch + PR management ──────
 
-  const branch = upgradeBranchName(lexicon);
+  const branch = upgradeBranchName(lexicon, pinLabel);
 
   // Idempotency check: if the open PR already has this summary, nothing changed.
   // Compare trimmed — gh/git round-trips can alter trailing whitespace.
@@ -662,9 +765,9 @@ export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconU
     await gh(`git checkout ${shellQuote(branch)}`);
 
     // For pinned lexicons: apply the spec version bump permanently on this branch.
-    if (isPinned(lexicon) && to) {
+    if (pinned && to) {
       const applyBump = args._applyBump ?? (await getRealApplyBump());
-      const { filePath } = await applyBump(lexicon, lexiconDir, to);
+      const { filePath } = await (pinLabel ? applyBump(lexicon, lexiconDir, to, pinLabel) : applyBump(lexicon, lexiconDir, to));
       await gh(`git add ${shellQuote(filePath)}`).catch(() => {/* best-effort */});
 
       // Bump the lexicon's package.json version so merging this PR causes

package/src/op/activity-contract.test.ts

@@ -7,7 +7,8 @@
 
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
-import { activity, phase, effect } from "./builders";
+import { activity, decide, phase, effect } from "./builders";
+import { decideContract } from "./activities/activity-contracts";
 import type { OpConfig } from "./types";
 import {
   activityContract,
@@ -118,6 +119,25 @@ describe("validateActivitySteps() — passing Ops", () => {
   });
 });
 
+describe("validateActivitySteps() — a whole-value reference in a record-typed arg (#3299)", () => {
+  const contracts = new Map([["decide", decideContract]]);
+
+  it("accepts decide's `inputs: step.out.json` without throwing", () => {
+    const fetch = activity("fetchInputs", {}, { id: "fetch" });
+    const ask = decide("dispatch-tier", { inputs: fetch.out.json as unknown as Record<string, unknown> });
+    const config = opWith({ phases: [phase("Fetch", [fetch]), phase("Decide", [ask])] });
+    expect(validateActivitySteps(config, contracts)).toEqual([]);
+  });
+
+  it("reports a symbol key in a record-typed arg as a finding instead of throwing", () => {
+    const step = activity("decide", { point: "dispatch-tier", inputs: { [Symbol("odd")]: 1 } });
+    const config = opWith({ phases: [phase("Decide", [step])] });
+    const issues = validateActivitySteps(config, contracts);
+    expect(issues.length).toBeGreaterThan(0);
+    expect(issues[0].message).toContain("args.inputs.Symbol(odd)");
+  });
+});
+
 describe("validateActivitySteps() — the four failure classes from #1288", () => {
   it("flags an unknown profile — e.g. kubectlApply(..., { profile: \"longInfa\" })", () => {
     const step = activity("kubectlApply", { manifest: "dist/k8s.yaml" }, "longInfa" as never);