@intentius/chant 0.57.0 → 0.58.0

package/src/op/activities/shell.ts

@@ -0,0 +1,26 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+export interface ShellCmdArgs {
+  cmd: string;
+  /** Additional environment variables. */
+  env?: Record<string, string>;
+  /** Working directory. Default: process.cwd(). */
+  cwd?: string;
+}
+
+/**
+ * Run an arbitrary shell command.
+ * Uses fastIdempotent profile — 5m timeout, 3 retries.
+ */
+export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promise<string> {
+  const { stdout, stderr } = await execAsync(args.cmd, {
+    cwd: args.cwd,
+    env: { ...process.env, ...args.env },
+    signal,
+  });
+  if (stderr) console.error(stderr);
+  return stdout.trim();
+}

package/src/op/activities/teardown.ts

@@ -0,0 +1,22 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+export interface ChantTeardownArgs {
+  /** Path to the chant project to tear down. */
+  path: string;
+}
+
+/**
+ * Run `chant teardown` in the given project path.
+ * Uses longInfra profile — 20m timeout.
+ */
+export async function chantTeardown(args: ChantTeardownArgs, signal?: AbortSignal): Promise<void> {
+  const { stdout, stderr } = await execAsync("npm run teardown", {
+    cwd: args.path,
+    signal,
+  });
+  if (stdout) console.log(stdout);
+  if (stderr) console.error(stderr);
+}

package/src/op/activities/util.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-export shim — `sleep` is the shared activity-runtime helper one directory
+ * up (`../activity-runtime`). Kept here so existing `./util` imports resolve
+ * unchanged.
+ */
+export { sleep } from "../activity-runtime";

package/src/op/activities/wait.ts

@@ -0,0 +1,69 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { sleep } from "./util";
+
+const execAsync = promisify(exec);
+
+export interface WaitForStackArgs {
+  /** Stack name — used to locate the kubectl deployment/statefulset to poll. */
+  name: string;
+  /** Kubernetes namespace. */
+  namespace?: string;
+  /** kubectl context. */
+  context?: string;
+  /** Poll interval in ms. Default: 10000. */
+  intervalMs?: number;
+}
+
+/**
+ * Poll until a Kubernetes Deployment or StatefulSet named `name` is fully rolled out.
+ * Uses the `k8sWait` profile — 15m timeout.
+ *
+ * Progress goes to stdout, one line per poll, which is the executor's step-record
+ * channel: the local executor streams an activity's output alongside the step it
+ * belongs to, so a long rollout is visible without a liveness protocol. Nothing
+ * mid-run is durable here by design (chant #2114) — the op re-runs and converges.
+ *
+ * Deliberately NOT migrated onto the generic `waitForReady` (#957): `kubectl
+ * rollout status` encodes rollout-specific semantics — progress-deadline
+ * timeouts, partial/paused rollouts, generation tracking — that a status-field
+ * predicate spec does not replicate, and it targets built-in workloads rather
+ * than arbitrary operator CRDs. `waitForReady` is the right tool for CRD
+ * readiness; `waitForStack` stays the right tool for workload rollouts.
+ */
+export async function waitForStack(args: WaitForStackArgs, signal?: AbortSignal): Promise<void> {
+  const ns = args.namespace ? `-n ${args.namespace}` : "";
+  const ctx = args.context ? `--context ${args.context}` : "";
+  const interval = args.intervalMs ?? 10_000;
+  let attempt = 0;
+
+  while (true) {
+    if (signal?.aborted) throw new Error("waitForStack aborted");
+    attempt++;
+    console.log(`[waitForStack] ${args.name}: poll ${attempt}`);
+
+    try {
+      await execAsync(
+        `kubectl rollout status deployment/${args.name} ${ns} ${ctx} --timeout=30s`,
+        { signal },
+      );
+      return;
+    } catch {
+      if (signal?.aborted) throw new Error("waitForStack aborted");
+      // Not ready yet — wait and retry
+    }
+
+    try {
+      await execAsync(
+        `kubectl rollout status statefulset/${args.name} ${ns} ${ctx} --timeout=30s`,
+        { signal },
+      );
+      return;
+    } catch {
+      if (signal?.aborted) throw new Error("waitForStack aborted");
+      // Not ready yet
+    }
+
+    await sleep(interval, signal);
+  }
+}

package/src/op/activities/workflow-audit.test.ts

@@ -0,0 +1,90 @@
+import { describe, test, expect } from "vitest";
+import {
+  workflowSupplyChainAudit,
+  collectAuditRefs,
+  type ActionRefResolution,
+  type ActionRefResolver,
+} from "./workflow-audit";
+
+const SHA = "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b";
+
+const WORKFLOW = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@${SHA} # v4.1.0
+      - uses: evil/typo-action@v1
+      - uses: archived/old-action@v2
+`;
+
+/** Recorded upstream responses — no live network. */
+function recordedResolver(records: Record<string, ActionRefResolution>): ActionRefResolver {
+  return async (slug, ref) =>
+    records[`${slug}@${ref}`] ?? { exists: true, tags: [], archived: false, advisories: [] };
+}
+
+describe("collectAuditRefs (#292)", () => {
+  test("collects external refs with version comments, skipping local/docker", () => {
+    const yaml = `jobs:
+  a:
+    steps:
+      - uses: actions/checkout@${SHA} # v4.1.0
+      - uses: ./.github/actions/local
+      - uses: docker://alpine:3.19
+      - uses: org/reusable/.github/workflows/x.yml@v1
+`;
+    const refs = collectAuditRefs(yaml);
+    const slugs = refs.map((r) => r.slug);
+    expect(slugs).toContain("actions/checkout");
+    expect(slugs).toContain("org/reusable");
+    expect(slugs).not.toContain("./.github");
+    expect(refs.find((r) => r.slug === "actions/checkout")?.comment).toBe("v4.1.0");
+  });
+});
+
+describe("workflowSupplyChainAudit (#292)", () => {
+  test("flags stale pin, impostor, archived, and pin/comment mismatch", async () => {
+    const resolver = recordedResolver({
+      // SHA no longer on any tag → stale; actual tag differs from comment → mismatch
+      [`actions/checkout@${SHA}`]: { exists: true, tags: ["v4.2.0"], archived: false, advisories: [] },
+      "evil/typo-action@v1": { exists: false, tags: [], archived: false, advisories: [] },
+      "archived/old-action@v2": { exists: true, tags: ["v2"], archived: true, advisories: ["GHSA-xxxx"] },
+    });
+    const result = await workflowSupplyChainAudit({ yaml: WORKFLOW, resolver, mode: "issue" });
+    const kinds = result.findings.map((f) => `${f.slug}:${f.kind}`);
+
+    expect(kinds).toContain("evil/typo-action:impostor");
+    expect(kinds).toContain("archived/old-action:archived");
+    expect(kinds).toContain("archived/old-action:advisory");
+    expect(kinds).toContain("actions/checkout:pin-comment-mismatch");
+    expect(result.mode).toBe("issue");
+    expect(result.summary).toContain("Workflow supply-chain audit");
+  });
+
+  test("flags a stale SHA pin with no upstream tag", async () => {
+    const resolver = recordedResolver({
+      [`actions/checkout@${SHA}`]: { exists: true, tags: [], archived: false, advisories: [] },
+      "evil/typo-action@v1": { exists: true, tags: ["v1"], archived: false, advisories: [] },
+      "archived/old-action@v2": { exists: true, tags: ["v2"], archived: false, advisories: [] },
+    });
+    const result = await workflowSupplyChainAudit({ yaml: WORKFLOW, resolver });
+    expect(result.findings.some((f) => f.slug === "actions/checkout" && f.kind === "stale-pin")).toBe(true);
+  });
+
+  test("clean workflow yields no findings", async () => {
+    const yaml = `jobs:
+  build:
+    steps:
+      - uses: actions/checkout@${SHA}
+`;
+    const resolver = recordedResolver({
+      [`actions/checkout@${SHA}`]: { exists: true, tags: ["v4"], archived: false, advisories: [] },
+    });
+    const result = await workflowSupplyChainAudit({ yaml, resolver });
+    expect(result.findings).toHaveLength(0);
+    expect(result.summary).toContain("No live drift");
+  });
+});

package/src/op/activities/workflow-audit.ts

@@ -0,0 +1,203 @@
+/**
+ * workflowSupplyChainAudit — the live counterpart to the github post-synth
+ * supply-chain checks (#286-#291).
+ *
+ * Some workflow-reference checks can only be answered against a moving external
+ * truth: whether a pinned SHA still corresponds to a real tag/release upstream,
+ * whether a referenced commit exists in the repo it claims, whether a ref is
+ * confusable as both a tag and a branch, whether a pin matches its version
+ * comment, or whether a new advisory now covers an action already in use. These
+ * change over time independent of the source, so they cannot live in the
+ * deterministic build — this activity owns *only* the checks that require live
+ * resolution.
+ *
+ * It is dependency-free and primitives-only: it reads the emitted workflow YAML
+ * (passed as a string) and resolves references through an injectable
+ * `ActionRefResolver`, so `chant run` can schedule it and tests can run
+ * it against recorded responses with no live network.
+ */
+
+/** What the audit produces on findings, mirroring ReconcileOp's modes. */
+export type WorkflowAuditMode = "report" | "issue" | "pull-request";
+
+/** Live resolution of a single action reference against its upstream. */
+export interface ActionRefResolution {
+  /** Does the ref/SHA exist in the claimed repo? */
+  exists: boolean;
+  /** Tag/release names that point at this commit (empty for a SHA ⇒ stale pin). */
+  tags: string[];
+  /** Is the upstream repository archived? */
+  archived: boolean;
+  /** Disclosed advisory identifiers affecting this action. */
+  advisories: string[];
+  /** Is the ref resolvable as BOTH a tag and a branch upstream? */
+  ambiguousRef?: boolean;
+}
+
+/** Pluggable upstream resolver — overridden in tests with recorded responses. */
+export type ActionRefResolver = (slug: string, ref: string) => Promise<ActionRefResolution>;
+
+export type WorkflowAuditFindingKind =
+  | "stale-pin"
+  | "impostor"
+  | "ambiguous-ref"
+  | "pin-comment-mismatch"
+  | "advisory"
+  | "archived";
+
+export interface WorkflowAuditFinding {
+  /** owner/repo slug. */
+  slug: string;
+  /** The pinned ref/SHA. */
+  ref: string;
+  kind: WorkflowAuditFindingKind;
+  detail: string;
+}
+
+export interface WorkflowAuditArgs {
+  /** One emitted workflow YAML document. */
+  yaml?: string;
+  /** Several emitted workflow YAML documents. */
+  yamls?: string[];
+  /**
+   * Directory of emitted workflow files (`*.yml`/`*.yaml`) to read at run time
+   * when no `yaml`/`yamls` is given — the form used inside a scheduled Op.
+   * Default `.github/workflows`.
+   */
+  workflowsDir?: string;
+  /** What to produce. Default: report. */
+  mode?: WorkflowAuditMode;
+  /** Injectable upstream resolver. Defaults to the live GitHub REST resolver. */
+  resolver?: ActionRefResolver;
+}
+
+/** Read `*.yml`/`*.yaml` files from a directory (best-effort). */
+async function readWorkflowDir(dir: string): Promise<string[]> {
+  try {
+    const { readdir, readFile } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    const files = (await readdir(dir)).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
+    return Promise.all(files.map((f) => readFile(join(dir, f), "utf-8")));
+  } catch {
+    return [];
+  }
+}
+
+export interface WorkflowAuditResult {
+  mode: WorkflowAuditMode;
+  findings: WorkflowAuditFinding[];
+  /** Markdown summary used as the PR/issue body or printed in report mode. */
+  summary: string;
+}
+
+interface CollectedRef {
+  slug: string;
+  ref: string;
+  /** Adjacent `# vX.Y.Z` comment, when present. */
+  comment?: string;
+}
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+/**
+ * Collect external action references (`uses: owner/repo@ref`, with an optional
+ * trailing version comment) from a workflow YAML. Local (`./`) and `docker://`
+ * references are excluded.
+ */
+export function collectAuditRefs(yaml: string): CollectedRef[] {
+  const out: CollectedRef[] = [];
+  const re = /uses:\s*['"]?([\w.-]+\/[\w.-]+(?:\/[\w./-]+)?)@([\w.-]+)['"]?\s*(?:#\s*(\S+))?/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(yaml)) !== null) {
+    out.push({ slug: m[1].split("/").slice(0, 2).join("/"), ref: m[2], comment: m[3] });
+  }
+  return out;
+}
+
+/**
+ * Default resolver: query the GitHub REST API for whether the ref exists, what
+ * tags point at it, archive status, and advisories. Best-effort and resilient —
+ * a network/HTTP error yields an "unknown" resolution (exists=true, no findings)
+ * rather than a false positive.
+ */
+export const defaultActionRefResolver: ActionRefResolver = async (slug, ref) => {
+  const base = `https://api.github.com/repos/${slug}`;
+  const headers: Record<string, string> = { Accept: "application/vnd.github+json" };
+  if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  const unknown: ActionRefResolution = { exists: true, tags: [], archived: false, advisories: [] };
+  try {
+    const repoResp = await fetch(base, { headers });
+    if (repoResp.status === 404) return { exists: false, tags: [], archived: false, advisories: [] };
+    if (!repoResp.ok) return unknown;
+    const repo = (await repoResp.json()) as { archived?: boolean };
+
+    const refResp = await fetch(`${base}/commits/${ref}`, { headers });
+    if (refResp.status === 404) return { exists: false, tags: [], archived: !!repo.archived, advisories: [] };
+
+    let tags: string[] = [];
+    if (SHA_RE.test(ref)) {
+      const tagsResp = await fetch(`${base}/tags?per_page=100`, { headers });
+      if (tagsResp.ok) {
+        const tagList = (await tagsResp.json()) as Array<{ name: string; commit?: { sha?: string } }>;
+        tags = tagList.filter((t) => t.commit?.sha === ref).map((t) => t.name);
+      }
+    }
+    return { exists: refResp.ok, tags, archived: !!repo.archived, advisories: [] };
+  } catch {
+    return unknown;
+  }
+};
+
+function renderSummary(findings: WorkflowAuditFinding[]): string {
+  if (findings.length === 0) return "## Workflow supply-chain audit\n\nNo live drift detected against upstream references.\n";
+  let out = `## Workflow supply-chain audit\n\n${findings.length} finding(s) against live upstream truth:\n\n`;
+  out += "| Action | Ref | Finding | Detail |\n|---|---|---|---|\n";
+  for (const f of findings) out += `| ${f.slug} | ${f.ref} | ${f.kind} | ${f.detail} |\n`;
+  return out;
+}
+
+/**
+ * Resolve each pinned external reference in the emitted workflows against live
+ * upstreams and report drift.
+ */
+export async function workflowSupplyChainAudit(args: WorkflowAuditArgs): Promise<WorkflowAuditResult> {
+  const resolver = args.resolver ?? defaultActionRefResolver;
+  const mode = args.mode ?? "report";
+  let yamls = args.yamls ?? (args.yaml ? [args.yaml] : []);
+  if (yamls.length === 0) {
+    yamls = await readWorkflowDir(args.workflowsDir ?? ".github/workflows");
+  }
+
+  const findings: WorkflowAuditFinding[] = [];
+  const seen = new Set<string>();
+  for (const yaml of yamls) {
+    for (const { slug, ref, comment } of collectAuditRefs(yaml)) {
+      const key = `${slug}@${ref}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const res = await resolver(slug, ref);
+      if (!res.exists) {
+        findings.push({ slug, ref, kind: "impostor", detail: `ref does not exist in ${slug} — possible impostor or deleted ref` });
+        continue;
+      }
+      if (SHA_RE.test(ref) && res.tags.length === 0) {
+        findings.push({ slug, ref, kind: "stale-pin", detail: "pinned SHA is no longer on any tag/release upstream" });
+      }
+      if (res.ambiguousRef) {
+        findings.push({ slug, ref, kind: "ambiguous-ref", detail: "ref resolves as both a tag and a branch upstream (symbolic-ref confusion)" });
+      }
+      if (comment && res.tags.length > 0 && !res.tags.includes(comment)) {
+        findings.push({ slug, ref, kind: "pin-comment-mismatch", detail: `pin comment "${comment}" does not match the SHA's actual tag(s): ${res.tags.join(", ")}` });
+      }
+      if (res.archived) {
+        findings.push({ slug, ref, kind: "archived", detail: `${slug} has been archived upstream since pinning` });
+      }
+      for (const adv of res.advisories) {
+        findings.push({ slug, ref, kind: "advisory", detail: `disclosed advisory ${adv} covers ${slug}` });
+      }
+    }
+  }
+
+  return { mode, findings, summary: renderSummary(findings) };
+}

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

@@ -0,0 +1,98 @@
+import { describe, test, expect } from "vitest";
+import { z } from "zod";
+import { loadActivityContracts, mergeActivityContracts } from "./activity-contract-registry";
+import { activityContract, type ActivityContract } from "./activity-contract";
+
+describe("loadActivityContracts", () => {
+  test("core's own contracts load with no lexicons configured", async () => {
+    const contracts = await loadActivityContracts();
+    expect(contracts.get("shellCmd")).toBeDefined();
+    expect(contracts.get("httpCheck")?.returns).toBeDefined();
+    expect(contracts.get("lifecycleDiff")?.name).toBe("lifecycleDiff");
+  });
+
+  test("a lexicon's contracts are resolved by the same subpath convention loadActivities uses", async () => {
+    const contracts = await loadActivityContracts(["terraform"]);
+    // terraform ships `@intentius/chant-lexicon-terraform/op/activity-contracts`.
+    expect(contracts.get("terraformPlan")).toBeDefined();
+    expect(contracts.get("terraformApply")).toBeDefined();
+    // Core's own are still there — the lexicon adds, it does not replace.
+    expect(contracts.get("shellCmd")).toBeDefined();
+  });
+
+  test("terraformPlan's declared return schema carries the fields an Apply step references", async () => {
+    const contracts = await loadActivityContracts(["terraform"]);
+    const returns = contracts.get("terraformPlan")?.returns as z.ZodObject<z.ZodRawShape>;
+    expect(Object.keys(returns.shape)).toEqual(
+      expect.arrayContaining(["planFile", "text", "changed", "adds", "changes", "destroys"]),
+    );
+  });
+
+  test("an absent lexicon contributes nothing and does not throw", async () => {
+    const contracts = await loadActivityContracts(["no-such-lexicon-anywhere"]);
+    expect(contracts.get("shellCmd")).toBeDefined();
+    expect(contracts.size).toBeGreaterThan(0);
+  });
+
+  test("a plugin member contributes contracts alongside the conventional subpath", async () => {
+    const contracts = await loadActivityContracts([
+      {
+        name: "no-such-lexicon-anywhere",
+        activityContracts: () => [activityContract("bespokeApply", z.strictObject({ target: z.string() }))],
+      },
+    ]);
+    expect(contracts.get("bespokeApply")).toBeDefined();
+  });
+
+  test("a plugin member that throws contributes nothing rather than failing the load", async () => {
+    const contracts = await loadActivityContracts([
+      {
+        name: "no-such-lexicon-anywhere",
+        activityContracts: () => {
+          throw new Error("boom");
+        },
+      },
+    ]);
+    expect(contracts.get("shellCmd")).toBeDefined();
+  });
+
+  test("the last lexicon in wins a name collision, as loadActivities does for implementations", async () => {
+    const mine = activityContract("shellCmd", z.strictObject({ cmd: z.string(), extra: z.string() }));
+    const contracts = await loadActivityContracts([
+      { name: "no-such-lexicon-anywhere", activityContracts: () => [mine] },
+    ]);
+    expect(contracts.get("shellCmd")).toBe(mine);
+  });
+});
+
+describe("mergeActivityContracts", () => {
+  const base = new Map<string, ActivityContract>([
+    ["shellCmd", activityContract("shellCmd", z.strictObject({ cmd: z.string() }))],
+  ]);
+
+  test("an undefined loaded map returns the base unchanged", () => {
+    expect(mergeActivityContracts(base, undefined)).toBe(base);
+  });
+
+  test("an empty loaded map returns the base unchanged", () => {
+    expect(mergeActivityContracts(base, new Map())).toBe(base);
+  });
+
+  test("loaded contracts are added without mutating the base", () => {
+    const loaded = new Map<string, ActivityContract>([
+      ["terraformPlan", activityContract("terraformPlan", z.strictObject({ root: z.string() }))],
+    ]);
+    const merged = mergeActivityContracts(base, loaded);
+    expect(merged.get("terraformPlan")).toBeDefined();
+    expect(merged.get("shellCmd")).toBeDefined();
+    expect(base.has("terraformPlan")).toBe(false);
+  });
+
+  test("the loaded map wins a name collision — it is the one resolved against this build's lexicons", () => {
+    const loaded = new Map<string, ActivityContract>([
+      ["shellCmd", activityContract("shellCmd", z.strictObject({ cmd: z.string(), cwd: z.string() }))],
+    ]);
+    const merged = mergeActivityContracts(base, loaded);
+    expect(merged.get("shellCmd")).toBe(loaded.get("shellCmd"));
+  });
+});

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

@@ -0,0 +1,114 @@
+/**
+ * Activity contract registry — the schema-shaped sibling of
+ * `./activity-registry.ts` (chant #2101).
+ *
+ * `activity-contract.ts` left contract ownership per-caller on purpose: an
+ * activity declares its contract alongside its implementation, and whoever
+ * builds a contract map decides which activities it covers. What was missing
+ * was the other half of that arrangement, a way for the checks that validate
+ * Op steps to SEE a contract a lexicon declared. OPS012 and OPS013
+ * (`../lint/rules/op/`) walk every Op entity in the build, including steps
+ * calling `terraformPlan`, `k3sInstall`, `flyApply` or `gcpApply`, over
+ * core's own static table alone. Since #2122 moved those checks into core
+ * they fire on every project that declares an Op, so an Op built out of one
+ * lexicon's steps failed `chant build` outright even though `loadActivities`
+ * resolves the very same names at run time. Both terraform examples that
+ * carry an Op kept it outside `src/` because of the older, lexicon-hosted
+ * form of the same gap, which meant no example ever proved its Op builds.
+ *
+ * The resolution mirrors activities exactly, by convention:
+ * `@intentius/chant-lexicon-<name>/op/activity-contracts` is imported for
+ * every configured lexicon and every {@link ActivityContract} it exports is
+ * collected, keyed by the contract's declared `name`. A lexicon that ships
+ * no such module is skipped, the same way `loadActivities` skips one that
+ * contributes no activities. A plugin may also hand its contracts over
+ * directly through {@link LexiconActivityContractContributor}, for a lexicon
+ * whose contracts are not reachable at a subpath (a bundled single-file
+ * plugin, a project-local one).
+ *
+ * The merged map reaches a post-synth check as
+ * `PostSynthContext.activityContracts` (`../lint/post-synth.ts`), filled in
+ * by whoever runs the checks: `chant build`, `chant lint` and
+ * `check-lexicon`'s example harness all do. A check merges it over its own
+ * base table rather than replacing it, so a context that carries none (a
+ * hand-built one in a test) behaves exactly as before this existed.
+ */
+
+import * as coreContracts from "./activities/activity-contracts";
+import { collectActivityContracts, type ActivityContract } from "./activity-contract";
+
+/**
+ * The shape {@link loadActivityContracts} reads off a plugin: an optional
+ * member returning this lexicon's contracts directly, for one that cannot be
+ * reached by the subpath convention. Structural on purpose, so core's op
+ * layer does not depend on `../lexicon.ts`.
+ */
+export interface LexiconActivityContractContributor {
+  /** The lexicon's name, as in `@intentius/chant-lexicon-<name>`. */
+  name: string;
+  /** This lexicon's activity contracts, if it declares them in code rather than at the conventional subpath. */
+  activityContracts?(): ActivityContract[];
+}
+
+/**
+ * Build the activity-contract map for build-time validation: core's own
+ * contracts (`./activities/activity-contracts`, a static import so a project
+ * that has installed nothing but chant still gets them) plus every contract
+ * the named lexicons contribute.
+ *
+ * `lexicons` may be plain names or plugin-shaped objects; a plugin's
+ * `activityContracts()` is read after its conventional module, so a plugin
+ * that declares both wins on a name collision with itself. Across lexicons,
+ * last one in wins, which is the same rule `loadActivities` applies to
+ * implementations.
+ *
+ * Never throws: an absent lexicon, a missing subpath, or a plugin member that
+ * throws all leave the map as it was.
+ */
+export async function loadActivityContracts(
+  lexicons: ReadonlyArray<string | LexiconActivityContractContributor> = [],
+): Promise<Map<string, ActivityContract>> {
+  const contracts = new Map<string, ActivityContract>();
+
+  collectActivityContracts(coreContracts as unknown as Record<string, unknown>, contracts);
+
+  for (const entry of lexicons) {
+    const name = typeof entry === "string" ? entry : entry.name;
+    try {
+      const spec = `@intentius/chant-lexicon-${name}/op/activity-contracts`;
+      collectActivityContracts((await import(spec)) as Record<string, unknown>, contracts);
+    } catch {
+      // Lexicon absent or declares no contracts at the conventional subpath.
+    }
+
+    if (typeof entry !== "string" && typeof entry.activityContracts === "function") {
+      try {
+        for (const contract of entry.activityContracts()) contracts.set(contract.name, contract);
+      } catch {
+        // A plugin member that throws contributes nothing, the same as one that is absent.
+      }
+    }
+  }
+
+  return contracts;
+}
+
+/**
+ * Merge a check's own base contracts with the ones the build loaded, into the
+ * map `validateActivitySteps`/`validateStepOutputRefs` take. The loaded set
+ * wins on a name collision: it is the one resolved against the lexicons this
+ * build actually configured, whereas the base table is whatever the check
+ * imported statically.
+ *
+ * `loaded` being `undefined` is the ordinary case for a hand-built
+ * `PostSynthContext` and yields the base table unchanged.
+ */
+export function mergeActivityContracts(
+  base: ReadonlyMap<string, ActivityContract>,
+  loaded: ReadonlyMap<string, ActivityContract> | undefined,
+): ReadonlyMap<string, ActivityContract> {
+  if (!loaded || loaded.size === 0) return base;
+  const merged = new Map(base);
+  for (const [name, contract] of loaded) merged.set(name, contract);
+  return merged;
+}

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

@@ -90,7 +90,7 @@ describe("validateActivitySteps() — passing Ops", () => {
 
   it("a step-output reference standing in for a typed arg does not trip a false-positive type mismatch (#1290)", () => {
     // args.env is z.string() — a StepOutputRef placeholder there is not a
-    // string, but it's not a real error either; TMP013 validates it against
+    // string, but it's not a real error either; OPS013 validates it against
     // the producer's return schema separately.
     const step = activity("lifecycleDiff", { env: stepOutput("diff", "name") as unknown as string });
     const config = opWith({ phases: [phase("Diff", [step])] });