@intentius/chant 0.101.0 → 0.102.0

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/composites/apply-op.ts

@@ -10,8 +10,11 @@
  * the ownership tag on `arm` (chant #1448 — previously `--mode Complete`, which
  * removed resources chant never applied), the ownership label on `gcp`
  * (chant #1449), the metadata marker (machines) and managed app
- * (volumes/ips/certs/secrets) on `fly` (chant #1449), and the stack itself on
- * `cloudformation`, which a resource CFN did not create is not in. All of
+ * (volumes/ips/certs/secrets) on `fly` (chant #1449), the ownership labels on
+ * `grafana` (chant #3011), the comment marker on `clickhouse` (chant #3208)
+ * and `postgres` (chant #3280),
+ * and the stack itself on `cloudformation`, which a
+ * resource CFN did not create is not in. All of
  * them are owned-only. See {@link DeleteMode}.
  *
  * A gate is a fact, not a wait (#2119): the local executor reads the gate
@@ -52,14 +55,18 @@ import { defaultOutput, hasNativeRollback, type ApplyTarget, type DeleteMode } f
 export interface ApplyOpConfig {
   /** Op name (kebab-case). */
   name: string;
-  /** Environment — CFN stack name / ARM resource group / kube context env;
-   * a log label on `gcp` and `fly`. */
+  /** Environment — CFN stack name / ARM resource group / kube context env /
+   * the `grafana.profiles.<env>` entry on `grafana` / the `sql.profiles.<env>`
+   * entry on `clickhouse` and `postgres`; a log label on `gcp` and
+   * `fly`. */
   env: string;
   /** Native apply mechanism. Default: "kubectl". */
   target?: ApplyTarget;
   /** Built manifest/template path. Default per target: `dist` (dir) for kubectl,
    * `template.json` (file) for CloudFormation/ARM, `dist/gcp.yaml` for gcp,
-   * `dist/fly.json` for fly. Must match your build output. */
+   * `dist/fly.json` for fly, `dist/grafana.json` (the build index) for
+   * grafana, `dist/schema.json` for clickhouse and postgres. Must match your
+   * build output. */
   output?: string;
   /** Project directory to build. Default: ".". */
   path?: string;

package/src/op/composites/composites.test.ts

@@ -157,6 +157,33 @@ describe("ApplyOp: shape", () => {
     expect(applyStep.fn).toBe("nativeApply");
     expect(applyStep.args).toEqual({ target: "kubectl", env: "prod", output: "dist", deleteMode: "never" });
   });
+
+  test("target clickhouse applies the sql build output, dist/schema.json by default (#3208)", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", target: "clickhouse", delete: "owned-only" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const applyStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(applyStep.fn).toBe("nativeApply");
+    expect(applyStep.args).toEqual({ target: "clickhouse", env: "prod", output: "dist/schema.json", deleteMode: "owned-only" });
+    expect(getProps(op).onFailure).toBeUndefined();
+  });
+
+  test("target postgres applies the sql build output, dist/schema.json by default (#3280)", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", target: "postgres", delete: "owned-only" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const applyStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(applyStep.fn).toBe("nativeApply");
+    expect(applyStep.args).toEqual({ target: "postgres", env: "prod", output: "dist/schema.json", deleteMode: "owned-only" });
+    expect(getProps(op).onFailure).toBeUndefined();
+  });
+
+  test("target grafana applies the build index, dist/grafana.json by default (#3011)", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", target: "grafana", delete: "owned-only" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const applyStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(applyStep.fn).toBe("nativeApply");
+    expect(applyStep.args).toEqual({ target: "grafana", env: "prod", output: "dist/grafana.json", deleteMode: "owned-only" });
+    expect(getProps(op).onFailure).toBeUndefined();
+  });
 });
 
 describe("ApplyOp: gating + deletes", () => {
@@ -274,7 +301,7 @@ describe("ApplyOp: compensation (#125, total-or-refused in #1449)", () => {
   });
 
   test("compensate: true is refused at build time for every rollback-less target (#1449)", () => {
-    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly"] as const) {
+    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly", "grafana", "clickhouse", "postgres"] as const) {
       expect(() => ApplyOp({ name: "p", env: "prod", target, compensate: true })).toThrow(
         new RegExp(`ApplyOp "p": compensate is enabled, but target "${target}" has no automatic rollback`),
       );
@@ -296,7 +323,7 @@ describe("ApplyOp: compensation (#125, total-or-refused in #1449)", () => {
   });
 
   test("an object without a command is refused the same way as true", () => {
-    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly"] as const) {
+    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly", "grafana", "clickhouse", "postgres"] as const) {
       expect(() => ApplyOp({ name: "p", env: "prod", target, compensate: {} })).toThrow(
         /has no automatic rollback/,
       );
@@ -304,7 +331,7 @@ describe("ApplyOp: compensation (#125, total-or-refused in #1449)", () => {
   });
 
   test("a command lifts the refusal on every target", () => {
-    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly", "cloudformation"] as const) {
+    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly", "grafana", "clickhouse", "postgres", "cloudformation"] as const) {
       const { op } = ApplyOp({
         name: "p",
         env: "prod",

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

@@ -49,17 +49,22 @@ describe("LexiconUpgradeOp composite (#527)", () => {
     expect(phases[0].steps[0].outcomeAttribute).toEqual({ name: "HasUpgrade", from: "hasUpgrade" });
   });
 
-  test("in-scope set is exactly the 9 lexicons (helm/forgejo excluded)", () => {
+  test("known set is exactly the 11 lexicons (helm/forgejo excluded)", () => {
     // cedar joined with #1650: it pins `CEDAR_WASM_VERSION`, a dependency
     // rather than a downloaded spec, but the pinned-constant machinery the Op
     // drives is identical. helm/forgejo still have no upstream at all.
     expect([...IN_SCOPE_LEXICONS].sort()).toEqual(
-      ["aws", "azure", "cedar", "docker", "fly", "gcp", "github", "gitlab", "k8s"].sort(),
+      ["aws", "azure", "cedar", "docker", "fly", "gcp", "github", "gitlab", "k3s", "k8s", "sql"].sort(),
     );
     expect(IN_SCOPE_LEXICONS).not.toContain("helm");
     expect(IN_SCOPE_LEXICONS).not.toContain("forgejo");
   });
 
+  test("accepts a pinned lexicon by name, discovered at run time", () => {
+    expect(() => LexiconUpgradeOp({ lexicon: "sql" })).not.toThrow();
+    expect(() => LexiconUpgradeOp({ lexicon: "k3s" })).not.toThrow();
+  });
+
   test("rejects out-of-scope lexicons at construction", () => {
     for (const l of ["helm", "forgejo"]) {
       expect(() => LexiconUpgradeOp({ lexicon: l as never })).toThrow(/not in scope/);

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

@@ -13,9 +13,13 @@
  * lands on the Op itself (#2120).
  *
  * Lexicon classification (which check the activity dispatches to):
- *   PINNED  {k8s, gcp, docker, gitlab} → checkPinnedUpgrade
- *   ROLLING {aws, azure, github}       → checkRollingUpgrade
- * helm / forgejo are excluded — no upstream spec.
+ *   ROLLING {aws, azure, github, fly}  → checkRollingUpgrade
+ *   PINNED  any other lexicon whose plugin declares `upstreamPin`
+ *           (k8s, k3s, gcp, docker, gitlab, cedar, sql, ...) → checkPinnedUpgrade
+ * The pinned set is discovered from the plugin at run time, the way `chant dev
+ * pinned-upgrade` does. A pin that moves with other constants (`alsoMoves`, as
+ * sql's version plus digest) is report-only. helm / forgejo are excluded: no
+ * upstream spec.
  *
  * Finding-modes mirror ReconcileOp: `report` (default, no external services)
  * | `issue` | `pull-request`. For the epic goal, `pull-request` opens/updates a
@@ -43,9 +47,15 @@ import { Op, phase } from "../builders";
 import type { OpResource } from "../resource";
 import type { LexiconUpgradeMode, SupportedLexicon } from "../activities/lexicon-upgrade";
 
-/** The in-scope lexicons. helm / forgejo are excluded (no upstream spec). */
+/**
+ * The lexicons known to be in scope. This is not a gate: a lexicon that declares
+ * `upstreamPin` is dispatched without being listed. helm / forgejo are excluded
+ * (no upstream spec).
+ */
 export const IN_SCOPE_LEXICONS: readonly SupportedLexicon[] = [
   "k8s",
+  "k3s",
+  "sql",
   "gcp",
   "docker",
   "gitlab",
@@ -74,6 +84,12 @@ export interface LexiconUpgradeOpConfig {
    * `<cwd>/lexicons/<lexicon>` at run time.
    */
   lexiconDir?: string;
+  /**
+   * Label of one pin to check, for a lexicon whose plugin declares several
+   * (`upstreamPins`; sql has `clickhouse` and `postgres-14` to `postgres-18`).
+   * Omit to check every pin.
+   */
+  pin?: string;
   /**
    * What to produce on findings. Default: "report".
    * @default "report"
@@ -86,15 +102,19 @@ export interface LexiconUpgradeOpResources {
   op: InstanceType<typeof OpResource>;
 }
 
+const EXCLUDED_LEXICONS: ReadonlySet<string> = new Set(["helm", "forgejo"]);
+
 /**
- * Build a LexiconUpgradeOp for one lexicon. Rejects out-of-scope lexicons at
- * construction time so a typo never silently produces a no-op Op.
+ * Build a LexiconUpgradeOp for one lexicon. Rejects the lexicons with no
+ * upstream spec at construction time. Whether any other name declares a pin is
+ * only known by loading its plugin, so the activity checks that at run time and
+ * fails with a clear message for a name that has none.
  */
 export function LexiconUpgradeOp(config: LexiconUpgradeOpConfig): LexiconUpgradeOpResources {
-  if (!IN_SCOPE_LEXICONS.includes(config.lexicon)) {
+  if (EXCLUDED_LEXICONS.has(config.lexicon)) {
     throw new Error(
       `LexiconUpgradeOp: "${config.lexicon}" is not in scope. ` +
-        `In-scope lexicons: ${IN_SCOPE_LEXICONS.join(", ")} ` +
+        `Known lexicons: ${IN_SCOPE_LEXICONS.join(", ")}, and any lexicon declaring upstreamPin ` +
         `(helm, forgejo have no upstream spec).`,
     );
   }
@@ -119,6 +139,7 @@ export function LexiconUpgradeOp(config: LexiconUpgradeOpConfig): LexiconUpgrade
           args: {
             lexicon: config.lexicon,
             ...(config.lexiconDir ? { lexiconDir: config.lexiconDir } : {}),
+            ...(config.pin ? { pin: config.pin } : {}),
             mode: onFinding,
           },
           // Surface whether a PR-worthy upgrade was found as the run's

package/src/op/emulator-lifecycle.test.ts

@@ -39,3 +39,26 @@ describe("emulatorLifecycle command builders", () => {
     expect(emu.endpoint(4599)).toBe("http://localhost:4599");
   });
 });
+
+describe("an emulator reached by its own client, not over HTTP", () => {
+  const pg = emulatorLifecycle({
+    name: "chant-postgres",
+    image: "postgres:18",
+    containerPort: 5432,
+    readyCommand: ["pg_isready", "-h", "127.0.0.1"],
+    endpoint: (port) => `postgres://postgres@localhost:${port}/postgres`,
+  });
+
+  test("readiness is a command run in the container", () => {
+    expect(pg.readyExecCommand("chant-postgres")).toBe("docker exec chant-postgres pg_isready -h 127.0.0.1");
+    expect(emulatorLifecycle({ name: "x", image: "x:1", containerPort: 1, healthPath: "/h" }).readyExecCommand("x")).toBeUndefined();
+  });
+
+  test("the endpoint is the declared one, not an http URL", () => {
+    expect(pg.endpoint(55432)).toBe("postgres://postgres@localhost:55432/postgres");
+  });
+
+  test("a spec with neither a health path nor a ready command is refused", () => {
+    expect(() => emulatorLifecycle({ name: "x", image: "x:1", containerPort: 1 })).toThrow(/neither a healthPath nor a readyCommand/);
+  });
+});