@intentius/chant 0.79.0 → 0.80.0

package/src/lexicon-module.test.ts

@@ -0,0 +1,203 @@
+/**
+ * chant #2520 — a lexicon declared by module path in `chant.config.ts`
+ * (`{ name, module }`) loads with no `@intentius/chant-lexicon-<name>`
+ * package, for build, lint, run and the capability registry.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { loadChantConfig } from "./config";
+import { lexiconModulePath, lexiconNames, resetLexiconModules } from "./lexicon-module";
+import { loadPlugins, resolveProjectLexicons, loadPlugin } from "./cli/plugins";
+import { loadActivities } from "./op/activity-registry";
+import { loadActivityContracts } from "./op/activity-contract-registry";
+import { loadGatePolicyEvaluator } from "./op/gate-approval";
+import { buildCapabilityRegistry } from "./components/capability-plugin-loader";
+import { buildCommand } from "./cli/commands/build";
+import { lintCommand } from "./cli/commands/lint";
+
+const activityContractModule = resolve(import.meta.dirname, "op/activity-contract.ts");
+const zodModule = createRequire(import.meta.url).resolve("zod");
+
+/** The whole project-local lexicon, in one module, importing core by absolute path so it needs no package. */
+function lexiconSource(pluginName = "site"): string {
+  return `
+import { z } from ${JSON.stringify(zodModule)};
+import { activityContract } from ${JSON.stringify(activityContractModule)};
+
+export const sitePlugin = {
+  name: ${JSON.stringify(pluginName)},
+  serializer: {
+    name: "site",
+    rulePrefix: "SITE",
+    serialize: (entities) => JSON.stringify({ pages: [...entities.keys()].sort() }),
+  },
+  generate: async () => {},
+  validate: async () => {},
+  coverage: async () => {},
+  package: async () => {},
+  activities: () => ({ siteDeploy: async (args) => ({ deployed: args.target }) }),
+  activityContracts: () => [activityContract("siteDeploy", z.strictObject({ target: z.string() }))],
+};
+
+export const siteCapabilities = {
+  name: "site-capabilities",
+  version: "0.0.0",
+  capabilities: () => [{ kind: "site-publish", run: async () => ({}) }],
+};
+
+export async function evaluateGatePolicy() {
+  return { decision: "allow", determiningPolicies: [], errors: [] };
+}
+`;
+}
+
+function opSource(args: Record<string, unknown>): string {
+  return `
+export default {
+  [Symbol.for("chant.declarable")]: true,
+  entityType: "Chant::Op",
+  lexicon: "chant",
+  kind: "resource",
+  props: {
+    name: "publish",
+    overview: "test",
+    phases: [
+      { name: "Publish", steps: [{ kind: "activity", fn: "siteDeploy", args: ${JSON.stringify(args)} }] },
+    ],
+  },
+};
+`;
+}
+
+describe("lexicons declared by module path (#2520)", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    resetLexiconModules();
+    dir = await mkdtemp(join(tmpdir(), "chant-lexicon-module-"));
+    await mkdir(join(dir, "lexicon"));
+    await writeFile(join(dir, "lexicon", "index.ts"), lexiconSource());
+    await writeFile(
+      join(dir, "chant.config.ts"),
+      `export default { lexicons: [{ name: "site", module: "./lexicon/index.ts" }] };\n`,
+    );
+    await writeFile(
+      join(dir, "main.ts"),
+      `export const home = { lexicon: "site", entityType: "Site::Page", kind: "resource", props: {}, [Symbol.for("chant.declarable")]: true };\n`,
+    );
+  });
+
+  afterEach(async () => {
+    resetLexiconModules();
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("the loaded config holds the name, and the module path is recorded against the config's directory", async () => {
+    const { config } = await loadChantConfig(dir);
+    expect(config.lexicons).toEqual(["site"]);
+    expect(config.lexiconModules).toEqual({ site: join(dir, "lexicon", "index.ts") });
+    expect(lexiconModulePath("site")).toBe(join(dir, "lexicon", "index.ts"));
+  });
+
+  test("a config of plain names comes back as written, with nothing recorded", async () => {
+    const plain = join(dir, "plain");
+    await mkdir(plain);
+    await writeFile(join(plain, "chant.config.ts"), `export default { lexicons: ["aws"] };\n`);
+    const { config } = await loadChantConfig(plain);
+    expect(config).toEqual({ lexicons: ["aws"] });
+    expect(lexiconModulePath("aws")).toBeUndefined();
+  });
+
+  test("a later config naming the lexicon as a package drops the recorded path", async () => {
+    await loadChantConfig(dir);
+    expect(lexiconModulePath("site")).toBeDefined();
+    // A second project; a config file is a module, cached by path.
+    const other = join(dir, "other");
+    await mkdir(other);
+    await writeFile(join(other, "chant.config.ts"), `export default { lexicons: ["site"] };\n`);
+    await loadChantConfig(other);
+    expect(lexiconModulePath("site")).toBeUndefined();
+  });
+
+  test("an entry with an unknown key is rejected", async () => {
+    const pinned = join(dir, "pinned");
+    await mkdir(pinned);
+    await writeFile(
+      join(pinned, "chant.config.ts"),
+      `export default { lexicons: [{ name: "site", module: "./lexicon/index.ts", pin: "x" }] };\n`,
+    );
+    await expect(loadChantConfig(pinned)).rejects.toThrow(/Invalid chant config/);
+  });
+
+  test("lexiconNames reads both entry forms", () => {
+    expect(lexiconNames(["aws", { name: "site", module: "./x.ts" }])).toEqual(["aws", "site"]);
+  });
+
+  test("build: the plugin loads from the module and the project builds with it", async () => {
+    const names = await resolveProjectLexicons(dir);
+    expect(names).toEqual(["site"]);
+    const plugins = await loadPlugins(names);
+    expect(plugins.map((p) => p.name)).toEqual(["site"]);
+
+    await writeFile(join(dir, "publish.op.ts"), opSource({ target: "prod" }));
+    const result = await buildCommand({
+      path: dir,
+      format: "json",
+      serializers: plugins.map((p) => p.serializer),
+      plugins,
+    });
+    expect(result.errors).toEqual([]);
+    expect(result.success).toBe(true);
+    // The page and the Op.
+    expect(result.resourceCount).toBe(2);
+  });
+
+  test("a plugin whose name differs from the declared name is refused", async () => {
+    await writeFile(join(dir, "lexicon", "index.ts"), lexiconSource("other"));
+    await loadChantConfig(dir);
+    await expect(loadPlugin("site")).rejects.toThrow(/plugin it exports is named "other"/);
+  });
+
+  test("run: the plugin's activities are loaded by name, with no op/activities subpath", async () => {
+    await loadChantConfig(dir);
+    const activities = await loadActivities(["site"]);
+    expect(await activities.get("siteDeploy")?.({ target: "prod" })).toEqual({ deployed: "prod" });
+    // Core's base activities are still there.
+    expect(activities.get("shellCmd")).toBeDefined();
+  });
+
+  test("activity contracts are found by name, with no op/activity-contracts subpath", async () => {
+    await loadChantConfig(dir);
+    const contracts = await loadActivityContracts(["site"]);
+    expect(contracts.get("siteDeploy")).toBeDefined();
+  });
+
+  test("lint: the plugin's contract validates an Op step calling its activity", async () => {
+    await writeFile(join(dir, "publish.op.ts"), opSource({ target: 42 }));
+    const bad = await lintCommand({ path: dir, format: "stylish" });
+    expect(
+      bad.diagnostics.some((d) => d.ruleId === "OPS012" && d.message.includes("siteDeploy")),
+    ).toBe(true);
+
+    // A fresh path: ES modules are cached by URL, so the corrected Op needs its own file.
+    await rm(join(dir, "publish.op.ts"));
+    await writeFile(join(dir, "publish2.op.ts"), opSource({ target: "prod" }));
+    const good = await lintCommand({ path: dir, format: "stylish" });
+    expect(good.diagnostics.filter((d) => d.ruleId === "OPS012")).toEqual([]);
+  });
+
+  test("the capability registry registers the module's capability plugin", async () => {
+    await loadChantConfig(dir);
+    const registry = await buildCapabilityRegistry({ lexicons: ["site"] });
+    expect(registry.has("site-publish")).toBe(true);
+  });
+
+  test("the gate policy evaluator is read from the module", async () => {
+    await loadChantConfig(dir);
+    const evaluator = await loadGatePolicyEvaluator("site");
+    expect(typeof evaluator.evaluateGatePolicy).toBe("function");
+  });
+});

package/src/lexicon-module.ts

@@ -0,0 +1,117 @@
+/**
+ * Lexicons declared by module path (chant #2520).
+ *
+ * A `lexicons` entry has always been a bare name, and chant resolves a name to
+ * the package `@intentius/chant-lexicon-<name>`. A project that writes its own
+ * lexicon in the same repo can instead point at the module:
+ *
+ * ```ts
+ * export default {
+ *   lexicons: ["fly", { name: "site", module: "./lexicon/index.ts" }],
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * The path is resolved against the directory holding `chant.config.ts`. That
+ * module is the whole lexicon: its `LexiconPlugin` export is the plugin, the
+ * plugin's `activities()` and `activityContracts()` members stand in for the
+ * `op/activities` and `op/activity-contracts` subpaths, a `CapabilityPlugin`
+ * export feeds the capability registry, and an `evaluateGatePolicy` export
+ * stands in for the `gate-policy` subpath.
+ *
+ * Loaders take lexicon names, so the config loader records each path-declared
+ * name here and every loader asks {@link lexiconModulePath} before falling back
+ * to the package name. A name declared as a plain string is never recorded, so
+ * a project that names lexicons by package takes exactly the path it always did.
+ */
+
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+/** One `lexicons` entry: a package-backed name, or a name plus the module that implements it. */
+export type LexiconDeclaration = string | { name: string; module: string };
+
+/** The lexicon name an entry declares, whichever form it takes. */
+export function lexiconDeclarationName(entry: LexiconDeclaration): string {
+  return typeof entry === "string" ? entry : entry.name;
+}
+
+/** Every entry's name, in declaration order. `undefined` in, `undefined` out. */
+export function lexiconNames(entries: readonly LexiconDeclaration[]): string[];
+export function lexiconNames(entries: readonly LexiconDeclaration[] | undefined): string[] | undefined;
+export function lexiconNames(entries: readonly LexiconDeclaration[] | undefined): string[] | undefined {
+  return entries?.map(lexiconDeclarationName);
+}
+
+/** Name to absolute module path, for the lexicons declared by path in the configs loaded so far. */
+const modulePaths = new Map<string, string>();
+
+/**
+ * Record the path-declared entries of one loaded config. `baseDir` is the
+ * directory the config file sits in. A plain-string entry for a name removes
+ * any path recorded for it earlier in this process, so loading a second
+ * project (the example harness does) cannot leave the first one's module in
+ * place of a package.
+ *
+ * Returns the recorded name-to-path map for this config, empty when every
+ * entry is a plain name.
+ */
+export function registerLexiconDeclarations(
+  entries: readonly LexiconDeclaration[] | undefined,
+  baseDir: string,
+): Record<string, string> {
+  const recorded: Record<string, string> = {};
+  for (const entry of entries ?? []) {
+    if (typeof entry === "string") {
+      modulePaths.delete(entry);
+      continue;
+    }
+    const path = isAbsolute(entry.module) ? entry.module : resolve(baseDir, entry.module);
+    modulePaths.set(entry.name, path);
+    recorded[entry.name] = path;
+  }
+  return recorded;
+}
+
+/** The absolute module path `name` was declared with, or `undefined` for a package-backed lexicon. */
+export function lexiconModulePath(name: string): string | undefined {
+  return modulePaths.get(name);
+}
+
+/** Forget every recorded path. For tests. */
+export function resetLexiconModules(): void {
+  modulePaths.clear();
+}
+
+/**
+ * Import the module a path-declared lexicon names. Returns `undefined` when
+ * `name` is package-backed, so a caller falls through to its package import.
+ * An import failure is thrown with the declared path in the message.
+ */
+export async function importLexiconModule(name: string): Promise<Record<string, unknown> | undefined> {
+  const path = modulePaths.get(name);
+  if (path === undefined) return undefined;
+  try {
+    return (await import(path)) as Record<string, unknown>;
+  } catch (err) {
+    throw new Error(
+      `lexicon "${name}" is declared with module ${path}, which could not be loaded: ` +
+        (err instanceof Error ? err.message : String(err)),
+    );
+  }
+}
+
+/**
+ * chant#2578 — how a message should name a lexicon. A package-backed name is
+ * its npm package; a lexicon declared by path is that path, relative to
+ * `fromDir` when it sits under it.
+ */
+export function lexiconSourceLabel(name: string, fromDir: string = process.cwd()): string {
+  const path = modulePaths.get(name);
+  if (path === undefined) return `@intentius/chant-lexicon-${name}`;
+  const rel = relative(fromDir, path);
+  return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? path : `./${rel.split(sep).join("/")}`;
+}
+
+/** The npm packages that provide `names`, leaving out every lexicon declared by path: those have nothing to install. */
+export function lexiconPackagesToInstall(names: readonly string[]): string[] {
+  return names.filter((name) => !modulePaths.has(name)).map((name) => `@intentius/chant-lexicon-${name}`);
+}

package/src/lexicon.ts

@@ -486,6 +486,21 @@ export interface ComponentPipelineOptions {
    * this too when the file should land under some other name than its stage.
    */
   opsFileName?: string;
+  /**
+   * An environment to promote to after the deploy (#2575). The component
+   * generators add one job that needs every component job and runs
+   * `chant components promote --from <env> --to <promoteTo>`. Each component
+   * job also uploads the files its build steps wrote (see
+   * `promoteArchivePaths` in `components/promote.ts`), and the promote job
+   * downloads them, since a promote publishes from the archive on disk.
+   * Unset, the pipeline has no promote job and is unchanged.
+   */
+  promoteTo?: string;
+  /**
+   * The promote job's command as argv, when `promoteTo` is set. Default
+   * `["chant", "components", "promote", "--from", <env>, "--to", <promoteTo>]`.
+   */
+  promoteCommand?: string[];
 }
 
 /** The synthesized CI pipeline for a component graph (generate mode). */
@@ -939,6 +954,17 @@ export interface LexiconPlugin {
    */
   activityContracts?(): ActivityContract[];
 
+  /**
+   * Op activity implementations, keyed by the name a step's `fn` calls them
+   * by (chant #2520). Read only for a lexicon declared by module path
+   * (`{ name, module }` in `chant.config.ts`), which has no
+   * `@intentius/chant-lexicon-<name>/op/activities` subpath for
+   * `loadActivities` to import. A package-backed lexicon keeps using the
+   * subpath and leaves this out.
+   */
+  activities?(): Record<string, (args: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>>
+    | Promise<Record<string, (args: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>>>;
+
   /**
    * Audit catalog metadata (title/tier/fix/authority/category) for this
    * lexicon's `postSynthChecks`, keyed by check id — the per-provider half of

package/src/lifecycle/build-ledger-store.ts

@@ -55,6 +55,7 @@
  */
 
 import { sortedJsonReplacer } from "../utils";
+import { warnOnLegacyDigests } from "./legacy-digest";
 import { writeBlobToPath, readBlobFromPath, listFilesInDir } from "./git";
 import type { BuildArchiveManifest } from "../components/verbs/build-archive";
 
@@ -104,11 +105,20 @@ export async function readBuildManifest(
 ): Promise<BuildArchiveManifest | null> {
   const content = await readBlobFromPath(BUILDS_DIR, manifestFilename(manifestDigest), opts);
   if (!content) return null;
+  let manifest: BuildArchiveManifest;
   try {
-    return JSON.parse(content) as BuildArchiveManifest;
+    manifest = JSON.parse(content) as BuildArchiveManifest;
   } catch {
     return null;
   }
+  // chant #2514 — a release ahead of real SHA-256 digests, say once that
+  // the persisted manifests hold values in the old form.
+  warnOnLegacyDigests(
+    [manifest.manifestDigest, ...(Array.isArray(manifest.contents) ? manifest.contents.map((e) => e?.digest) : [])],
+    "build manifests",
+    opts?.cwd,
+  );
+  return manifest;
 }
 
 /** List the `manifestDigest` of every build manifest persisted on the orphan branch. */

package/src/lifecycle/legacy-digest.test.ts

@@ -0,0 +1,114 @@
+/**
+ * chant #2514 — the warning a release ahead of real SHA-256 digests: a
+ * project whose release ledger or build manifests hold values from the old
+ * 32-bit `contentDigest` is told once that they will change.
+ */
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isLegacyContentDigest, resetLegacyDigestWarnings, warnOnLegacyDigests } from "./legacy-digest";
+import { appendReleaseRecord, readReleaseLedger, type ReleaseRecordInput } from "./release-ledger";
+import { persistBuildManifest, readAllBuildManifests } from "./build-ledger-store";
+import { addArchiveEntry, contentDigest, createBuildArchiveManifest } from "../components/verbs/build-archive";
+
+function git(args: string[], cwd: string): void {
+  spawnSync("git", args, { cwd, encoding: "utf-8" });
+}
+
+function initRepo(dir: string): void {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+function release(digest: string, runId: string): ReleaseRecordInput {
+  return {
+    component: "web",
+    env: "prod",
+    digest,
+    gitSha: "deadbeef",
+    runId,
+    timestamp: "2026-01-01T00:00:00.000Z",
+    actor: "ci-bot",
+  };
+}
+
+const realSha256 = `sha256:${createHash("sha256").update("x").digest("hex")}`;
+
+describe("legacy content digests (#2514)", () => {
+  let warn: { mock: { calls: unknown[][] }; mockRestore(): void };
+
+  beforeEach(() => {
+    resetLegacyDigestWarnings();
+    warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warn.mockRestore();
+    resetLegacyDigestWarnings();
+  });
+
+  const legacyWarnings = () => warn.mock.calls.filter((c: unknown[]) => String(c[0]).includes("issues/2514"));
+
+  test("today's contentDigest output is recognised as the old form", () => {
+    expect(isLegacyContentDigest(contentDigest("hello"))).toBe(true);
+    expect(isLegacyContentDigest(contentDigest(""))).toBe(true);
+  });
+
+  test("a real SHA-256 value, a short value and a non-string are not", () => {
+    expect(isLegacyContentDigest(realSha256)).toBe(false);
+    expect(isLegacyContentDigest("sha256:abc123")).toBe(false);
+    expect(isLegacyContentDigest(undefined)).toBe(false);
+  });
+
+  test("warns once per project, and not at all without an old value", () => {
+    expect(warnOnLegacyDigests([realSha256], "release ledger", "/p/a")).toBe(false);
+    expect(warnOnLegacyDigests([contentDigest("x")], "release ledger", "/p/a")).toBe(true);
+    expect(warnOnLegacyDigests([contentDigest("y")], "build manifests", "/p/a")).toBe(false);
+    expect(warnOnLegacyDigests([contentDigest("y")], "build manifests", "/p/b")).toBe(true);
+    expect(legacyWarnings()).toHaveLength(2);
+    expect(String(legacyWarnings()[0][0])).toContain("next chant release computes real SHA-256");
+  });
+
+  test("reading a release ledger that holds an old value warns once", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      await appendReleaseRecord(release(contentDigest("rendered"), "run-1"), { cwd: dir });
+      await appendReleaseRecord(release(contentDigest("rendered-2"), "run-2"), { cwd: dir });
+
+      await readReleaseLedger("prod", { cwd: dir });
+      await readReleaseLedger("prod", { cwd: dir });
+      expect(legacyWarnings()).toHaveLength(1);
+      expect(String(legacyWarnings()[0][0])).toContain("release ledger holds");
+    });
+  });
+
+  test("a release ledger of real SHA-256 values stays quiet", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      await appendReleaseRecord(release(realSha256, "run-1"), { cwd: dir });
+      await readReleaseLedger("prod", { cwd: dir });
+      expect(legacyWarnings()).toHaveLength(0);
+    });
+  });
+
+  test("reading persisted build manifests that hold old values warns once", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      let manifest = createBuildArchiveManifest("web", { now: () => new Date(0) });
+      manifest = addArchiveEntry(manifest, { kind: "template", path: "web.json", digest: contentDigest("{}") });
+      await persistBuildManifest(manifest, { cwd: dir });
+
+      await readAllBuildManifests({ cwd: dir });
+      await readAllBuildManifests({ cwd: dir });
+      expect(legacyWarnings()).toHaveLength(1);
+      expect(String(legacyWarnings()[0][0])).toContain("build manifests hold");
+    });
+  });
+});

package/src/lifecycle/legacy-digest.ts

@@ -0,0 +1,62 @@
+/**
+ * The warning a release ahead of real SHA-256 digests (chant #2514).
+ *
+ * `contentDigest` (../components/verbs/build-archive.ts) labels its output
+ * `sha256:` but computes a 32-bit string hash and repeats its 8 hex digits
+ * eight times. The next release makes it real SHA-256, so every value it
+ * produces changes once. Values already recorded in a project's release
+ * ledger or persisted build manifests keep the old form. This release only
+ * says so: readers of those records warn once per project, per process, when
+ * they meet an old value. Nothing is rewritten or flagged yet.
+ *
+ * An old value is recognisable by its shape alone. A real SHA-256 hex digest
+ * whose 64 characters are one 8-character block repeated eight times has
+ * probability 2^-224, so the check has no false positives worth considering.
+ */
+
+import { resolve } from "node:path";
+
+const LEGACY_DIGEST = /^sha256:([0-9a-f]{8})\1{7}$/;
+
+/** Whether `value` is a `sha256:` string made by the old 32-bit `contentDigest`. */
+export function isLegacyContentDigest(value: unknown): boolean {
+  return typeof value === "string" && LEGACY_DIGEST.test(value);
+}
+
+/** Project roots already warned about in this process. */
+const warnedProjects = new Set<string>();
+
+/** Forget which projects were warned about. For tests. */
+export function resetLegacyDigestWarnings(): void {
+  warnedProjects.clear();
+}
+
+/**
+ * Warn once for the project at `cwd` (default: the working directory) when
+ * any of `values` is an old-form digest. `where` names the record that held
+ * it, for the message. Returns whether a warning was printed.
+ */
+export function warnOnLegacyDigests(
+  values: Iterable<unknown>,
+  where: "release ledger" | "build manifests",
+  cwd?: string,
+): boolean {
+  const project = resolve(cwd ?? process.cwd());
+  if (warnedProjects.has(project)) return false;
+  let found = false;
+  for (const value of values) {
+    if (isLegacyContentDigest(value)) {
+      found = true;
+      break;
+    }
+  }
+  if (!found) return false;
+  warnedProjects.add(project);
+  console.warn(
+    `[chant] warning: this project's ${where} ${where === "release ledger" ? "holds" : "hold"} sha256: values made by chant's old 32-bit content hash, ` +
+      "not real SHA-256. The next chant release computes real SHA-256, so digests recorded from then on " +
+      "will not match these for the same content. Existing entries stay readable and will be marked " +
+      "legacy-digest. See https://github.com/INTENTIUS/chant/issues/2514",
+  );
+  return true;
+}

package/src/lifecycle/release-ledger.ts

@@ -29,6 +29,7 @@
  */
 
 import { sortedJsonReplacer } from "../utils";
+import { warnOnLegacyDigests } from "./legacy-digest";
 import { appendReleaseRecordLine, readReleaseLedgerLines, listLedgerEnvironments as gitListLedgerEnvironments } from "./git";
 
 /**
@@ -50,6 +51,20 @@ export interface RunOrigin {
   url?: string;
 }
 
+/**
+ * Points at one earlier release record (#2530, #2531). A record has no id of its own,
+ * so it is named by the environment whose ledger holds it plus the run id and
+ * timestamp it was written with, which is enough to find the line again.
+ */
+export interface ReleaseRef {
+  /** The environment whose ledger holds the referenced record. */
+  env: string;
+  /** The referenced record's `runId`. */
+  runId: string;
+  /** The referenced record's `timestamp`. */
+  timestamp: string;
+}
+
 /**
  * One immutable deploy record: `(component, env, artifact digest, git sha,
  * run id, timestamp, actor)`, referencing the build archive by digest — the
@@ -128,6 +143,18 @@ export interface ReleaseRecord {
    * bytes each cluster got. Absent when `digest` is already input-side.
    */
   inputDigest?: string;
+  /**
+   * Optional: set when this release was a promotion (`chant components
+   * promote`, #2530). Names the source environment's release whose digest
+   * was deployed here without a build. Absent on every other record.
+   */
+  promotedFrom?: ReleaseRef;
+  /**
+   * Optional: set when this release was a rollback (`chant components
+   * rollback`, #2531). Names the earlier release of the same environment
+   * whose digest was deployed again. Absent on every other record.
+   */
+  restores?: ReleaseRef;
 }
 
 /** Required, non-empty-string fields every `ReleaseRecord` must carry. */
@@ -258,6 +285,13 @@ export async function readReleaseLedger(
       malformed++;
     }
   }
+  // chant #2514 — a release ahead of real SHA-256 digests, say once that
+  // this ledger holds values in the old form.
+  warnOnLegacyDigests(
+    records.flatMap((r) => [r.digest, r.manifestDigest, r.inputDigest]),
+    "release ledger",
+    opts?.cwd,
+  );
   return { records, malformed };
 }
 

package/src/lint/rules/comp/comp003-mutating-no-rollback.ts

@@ -24,9 +24,8 @@
  * component.schema.json), a component may attach a `noRollback: "<reason>"`
  * string property directly on the step to declare the compensation gap is
  * intentional and understood, or supply its own explicit compensation via a
- * component-level `rollback` field (as the ALB/ECS pilot does with
- * `rollback-previous`) or a sibling `rollback-previous`/`snapshot-before` step
- * in the same phase.
+ * component-level `rollback` field or a sibling
+ * `rollback-previous`/`snapshot-before` step in the same phase.
  *
  * Triggers on: a bare `{ kind: "run-migration", ... }` step with no
  * `noRollback` reason, no component-level `rollback`, and no sibling