@intentius/chant 0.13.0 → 0.15.0

package/src/components/verbs/wait-verify.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import {
+  createWaitClusterHealthyCapability,
+  createWaitEndpointCapability,
+  createHealthGateCapability,
+} from "./wait-verify";
+import { createMockCloudExecutor } from "./__tests__/mock-cloud-executor";
+
+describe("wait-cluster-healthy (#557 — Neo4j bolt/quorum probe)", () => {
+  it("size mode: resolves once the exact required member count is healthy", async () => {
+    const mock = createMockCloudExecutor({ clusters: { "host1:7687": { healthyCount: 1 } } });
+    const capability = createWaitClusterHealthyCapability(mock.executor);
+    const output = await capability.run(
+      { env: "dev", component: "neo4j-cluster" },
+      { cluster: "host1:7687", size: 1 },
+    );
+    expect(output.healthyCount).toBe(1);
+  });
+
+  it("quorum mode: resolves once a majority of the cluster list is healthy", async () => {
+    const mock = createMockCloudExecutor({
+      clusters: { "host1:7687,host2:7687,host3:7687": { healthyCount: 2 } },
+    });
+    const capability = createWaitClusterHealthyCapability(mock.executor);
+    const output = await capability.run(
+      { env: "dev", component: "neo4j-cluster" },
+      { cluster: "host1:7687,host2:7687,host3:7687", quorum: true },
+    );
+    expect(output.healthyCount).toBe(2);
+  });
+
+  it("quorum mode: does not resolve until a majority (not just >0) is healthy", async () => {
+    const mock = createMockCloudExecutor({
+      clusters: { "host1:7687,host2:7687,host3:7687": { healthyCount: 1 } },
+    });
+    const capability = createWaitClusterHealthyCapability(mock.executor);
+    await expect(
+      capability.run(
+        { env: "dev", component: "neo4j-cluster" },
+        { cluster: "host1:7687,host2:7687,host3:7687", quorum: true, intervalMs: 1, timeoutMs: 5 },
+      ),
+    ).rejects.toThrow(/timed out/);
+  });
+
+  it("falls back to ctx.vars.clusterEndpoints when `cluster` is omitted (matches the Neo4j pilot's bare steps)", async () => {
+    const mock = createMockCloudExecutor({ clusters: { "az0:7687": { healthyCount: 1 } } });
+    const capability = createWaitClusterHealthyCapability(mock.executor);
+    const output = await capability.run(
+      { env: "dev", component: "neo4j-cluster", vars: { clusterEndpoints: "az0:7687" } },
+      { size: 1 },
+    );
+    expect(output.healthyCount).toBe(1);
+  });
+
+  it("declares no rollback — a health probe is read-only", () => {
+    const capability = createWaitClusterHealthyCapability(createMockCloudExecutor().executor);
+    expect(capability.rollback).toBeUndefined();
+  });
+});
+
+const httpCtx = { env: "dev", component: "svc" };
+
+describe("wait-endpoint (#557)", () => {
+  it("returns the status once the endpoint matches an expected code", async () => {
+    let n = 0;
+    const cap = createWaitEndpointCapability(async () => (++n < 2 ? { status: 503, ok: false } : { status: 200, ok: true }));
+    const out = await cap.run(httpCtx, { url: "http://x/health", intervalMs: 0 });
+    expect(out.status).toBe(200);
+    expect(n).toBe(2); // retried once before success
+  });
+
+  it("keeps polling when fetch throws (endpoint not up yet)", async () => {
+    let n = 0;
+    const cap = createWaitEndpointCapability(async () => {
+      if (++n < 2) throw new Error("ECONNREFUSED");
+      return { status: 200, ok: true };
+    });
+    const out = await cap.run(httpCtx, { url: "http://x", intervalMs: 0 });
+    expect(out.status).toBe(200);
+  });
+
+  it("times out when the endpoint never matches", async () => {
+    const cap = createWaitEndpointCapability(async () => ({ status: 500, ok: false }));
+    await expect(cap.run(httpCtx, { url: "http://x", intervalMs: 0, timeoutMs: 0 })).rejects.toThrow("wait-endpoint");
+  });
+
+  it("declares no rollback — a wait is read-only", () => {
+    expect(createWaitEndpointCapability().rollback).toBeUndefined();
+  });
+});
+
+describe("health-gate (#557)", () => {
+  it("passes only after the required consecutive successes (a failure resets the streak)", async () => {
+    const results = [true, false, true, true];
+    let i = 0;
+    const cap = createHealthGateCapability(async () => ({ status: 200, ok: results[i++] ?? true }));
+    const out = await cap.run(httpCtx, { path: "http://x/healthz", consecutiveSuccesses: 2, intervalMs: 0 });
+    expect(out.healthy).toBe(true);
+    expect(i).toBe(4); // ok, fail(reset), ok, ok -> two in a row
+  });
+
+  it("treats a thrown fetch as unhealthy", async () => {
+    let i = 0;
+    const cap = createHealthGateCapability(async () => {
+      if (++i < 2) throw new Error("down");
+      return { status: 200, ok: true };
+    });
+    const out = await cap.run(httpCtx, { path: "http://x", intervalMs: 0 });
+    expect(out.healthy).toBe(true);
+  });
+});

package/src/components/verbs/wait-verify.ts

@@ -0,0 +1,171 @@
+/**
+ * wait / verify family — poll until a deploy reaches a terminal or healthy
+ * state. The *agnostic* members live here: `wait-cluster-healthy` (a Neo4j
+ * bolt/quorum probe over the core `CloudExecutor`), and the HTTP waits
+ * `wait-endpoint` / `health-gate` (over an injectable `fetch`). The
+ * cloud-specific members — `wait-for-stack` (CloudFormation),
+ * `wait-steady-state` (ECS), `wait-job` (EMR) — moved to the aws lexicon
+ * alongside their executor clients (see docs/components/cloud-boundary).
+ */
+
+import type { Capability } from "../capability";
+import { defaultCloudExecutor, sleep, type CloudExecutor } from "./cloud-executor";
+
+/** Minimal fetch surface the HTTP waits (`wait-endpoint`, `health-gate`) need — injectable for tests. */
+type Fetcher = (url: string) => Promise<{ status: number; ok: boolean }>;
+const defaultFetcher: Fetcher = (url) => fetch(url);
+
+// ── wait-cluster-healthy ─────────────────────────────────────────────────────
+
+export interface WaitClusterHealthyInput {
+  /**
+   * Cluster identifier — a comma-separated list of `host:port` bolt
+   * endpoints. Optional because a per-instance fan-out phase (e.g. the Neo4j
+   * pilot) calls this once per instance without repeating the cluster's
+   * member list on every step; when omitted, falls back to
+   * `ctx.vars.clusterEndpoints` (env config resolved by the caller) or,
+   * failing that, `ctx.component` as a single-endpoint identifier.
+   */
+  cluster?: string;
+  /** Minimum healthy member count required. */
+  size?: number;
+  /** Require quorum (majority of expected members healthy) rather than an exact size. Default: false. */
+  quorum?: boolean;
+  /** Poll interval in ms. Default: 5000. */
+  intervalMs?: number;
+  /** Overall timeout in ms. Default: 5 minutes. */
+  timeoutMs?: number;
+}
+
+export interface WaitClusterHealthyOutput {
+  /** Number of healthy members observed. */
+  healthyCount: number;
+}
+
+/**
+ * Poll a multi-node cluster (e.g. Neo4j) via a bolt-port TCP probe until it
+ * reports healthy: `size` members reachable (exact-count mode, used by a
+ * cluster's seed instance) or a majority of the expected member list
+ * (`quorum` mode, used once followers exist). No rollback: a health probe is
+ * read-only.
+ */
+export function createWaitClusterHealthyCapability(
+  executor: CloudExecutor = defaultCloudExecutor(),
+): Capability<WaitClusterHealthyInput, WaitClusterHealthyOutput> {
+  return {
+    kind: "wait-cluster-healthy",
+    async run(ctx, input) {
+      const cluster = input.cluster ?? (ctx.vars?.clusterEndpoints as string | undefined) ?? ctx.component;
+      const intervalMs = input.intervalMs ?? 5_000;
+      const deadline = Date.now() + (input.timeoutMs ?? 5 * 60_000);
+      while (true) {
+        const { healthyCount, total } = await executor.neo4j.probe({ cluster });
+        const required = input.quorum ? Math.floor(total / 2) + 1 : (input.size ?? total);
+        if (healthyCount >= required) return { healthyCount };
+        if (Date.now() > deadline) {
+          throw new Error(
+            `wait-cluster-healthy "${cluster}" timed out: ${healthyCount}/${total} healthy, needed ${required}`,
+          );
+        }
+        await sleep(intervalMs);
+      }
+    },
+  };
+}
+
+/** Default `wait-cluster-healthy` capability, backed by the real `CloudExecutor`. */
+export const waitClusterHealthyCapability: Capability<WaitClusterHealthyInput, WaitClusterHealthyOutput> =
+  createWaitClusterHealthyCapability();
+
+// ── wait-endpoint ────────────────────────────────────────────────────────────
+
+export interface WaitEndpointInput {
+  /** URL to poll. */
+  url: string;
+  /** Expected HTTP status codes. Default: [200]. */
+  expectStatus?: number[];
+  /** Poll interval in ms. Default: 5000. */
+  intervalMs?: number;
+  /** Overall timeout in ms. */
+  timeoutMs?: number;
+}
+
+export interface WaitEndpointOutput {
+  /** Observed status code on success. */
+  status: number;
+}
+
+/** Poll an HTTP(S) endpoint until it responds with an expected status. Cloud-agnostic. */
+export function createWaitEndpointCapability(fetcher: Fetcher = defaultFetcher): Capability<WaitEndpointInput, WaitEndpointOutput> {
+  return {
+    kind: "wait-endpoint",
+    async run(_ctx, input) {
+      const expect = input.expectStatus ?? [200];
+      const intervalMs = input.intervalMs ?? 5_000;
+      const timeoutMs = input.timeoutMs ?? 5 * 60_000;
+      const deadline = Date.now() + timeoutMs;
+      for (;;) {
+        try {
+          const res = await fetcher(input.url);
+          if (expect.includes(res.status)) return { status: res.status };
+        } catch {
+          // not reachable yet — keep polling until the deadline
+        }
+        if (Date.now() >= deadline) {
+          throw new Error(`wait-endpoint: ${input.url} did not return ${expect.join("/")} within ${timeoutMs}ms`);
+        }
+        await sleep(intervalMs);
+      }
+    },
+  };
+}
+
+/** Default `wait-endpoint` capability, backed by the global `fetch`. */
+export const waitEndpointCapability: Capability<WaitEndpointInput, WaitEndpointOutput> = createWaitEndpointCapability();
+
+// ── health-gate ──────────────────────────────────────────────────────────────
+
+export interface HealthGateInput {
+  /** Health check path or full URL. */
+  path: string;
+  /** Number of consecutive successes required. Default: 1. */
+  consecutiveSuccesses?: number;
+  /** Poll interval in ms. Default: 5000. */
+  intervalMs?: number;
+}
+
+export interface HealthGateOutput {
+  /** True once the health check passed the required consecutive count. */
+  healthy: boolean;
+}
+
+/** Block progression until a health check passes — the generic post-deploy verification gate. Cloud-agnostic. */
+export function createHealthGateCapability(fetcher: Fetcher = defaultFetcher): Capability<HealthGateInput, HealthGateOutput> {
+  return {
+    kind: "health-gate",
+    async run(_ctx, input) {
+      const need = input.consecutiveSuccesses ?? 1;
+      const intervalMs = input.intervalMs ?? 5_000;
+      // HealthGateInput has no timeout field; cap the wait so a never-healthy target fails rather than hangs.
+      const deadline = Date.now() + 5 * 60_000;
+      let streak = 0;
+      for (;;) {
+        let ok = false;
+        try {
+          ok = (await fetcher(input.path)).ok;
+        } catch {
+          ok = false;
+        }
+        streak = ok ? streak + 1 : 0;
+        if (streak >= need) return { healthy: true };
+        if (Date.now() >= deadline) {
+          throw new Error(`health-gate: ${input.path} did not reach ${need} consecutive healthy check(s) within 300000ms`);
+        }
+        await sleep(intervalMs);
+      }
+    },
+  };
+}
+
+/** Default `health-gate` capability, backed by the global `fetch`. */
+export const healthGateCapability: Capability<HealthGateInput, HealthGateOutput> = createHealthGateCapability();

package/src/config.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
-import { loadChantConfig, DEFAULT_CHANT_CONFIG } from "./config";
+import { loadChantConfig, DEFAULT_CHANT_CONFIG, resolveAutoReleaseDisabled, resolveSbomFormat } from "./config";
 import { writeFileSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
 
@@ -56,6 +56,20 @@ describe("loadChantConfig", () => {
     expect(result.configPath).toBe(jsonPath);
   });
 
+  // #559, epic #551: `capabilities` mirrors `lexicons` — additional
+  // capability plugin package names loaded on top of the built-in starter
+  // set (see ./components/capability-plugin-loader.ts's `buildCapabilityRegistry`).
+  test("loads chant.config.json with capabilities", async () => {
+    const jsonPath = join(TEST_DIR, "chant.config.json");
+    writeFileSync(
+      jsonPath,
+      JSON.stringify({ lexicons: ["aws"], capabilities: ["acme"] }),
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config.capabilities).toEqual(["acme"]);
+  });
+
   test("prefers .ts over .json when both exist", async () => {
     // .ts takes priority — verify by checking configPath ends with .ts
     writeFileSync(
@@ -88,4 +102,63 @@ describe("loadChantConfig", () => {
     expect(result.config.lexicons).toEqual(["testdom"]);
     expect(result.config.lint).toBeUndefined();
   });
+
+  // #597: release.autoRecord opts out of auto-emitting a release-ledger
+  // record from `chant run --components` post-run.
+  test("loads chant.config.json with release.autoRecord: false", async () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ release: { autoRecord: false } }),
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config.release?.autoRecord).toBe(false);
+  });
+
+  // #606: sbom.format sets the project-wide default SBOM format for every
+  // `generate-sbom` step that doesn't specify its own.
+  test("loads chant.config.json with sbom.format: cyclonedx", async () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ sbom: { format: "cyclonedx" } }),
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config.sbom?.format).toBe("cyclonedx");
+  });
+});
+
+describe("resolveAutoReleaseDisabled", () => {
+  test("default (no flag, no config) → not disabled", () => {
+    expect(resolveAutoReleaseDisabled({})).toBe(false);
+  });
+
+  test("the CLI flag disables regardless of config", () => {
+    expect(resolveAutoReleaseDisabled({}, true)).toBe(true);
+    expect(resolveAutoReleaseDisabled({ release: { autoRecord: true } }, true)).toBe(true);
+  });
+
+  test("release.autoRecord: false disables without the CLI flag", () => {
+    expect(resolveAutoReleaseDisabled({ release: { autoRecord: false } })).toBe(true);
+  });
+
+  test("release.autoRecord: true (or unset) does not disable", () => {
+    expect(resolveAutoReleaseDisabled({ release: { autoRecord: true } })).toBe(false);
+    expect(resolveAutoReleaseDisabled({ release: {} })).toBe(false);
+  });
+});
+
+describe("resolveSbomFormat (#606)", () => {
+  test("defaults to spdx (DEFAULT_SBOM_FORMAT) with no config and no step override", () => {
+    expect(resolveSbomFormat({})).toBe("spdx");
+  });
+
+  test("project config sbom.format overrides the built-in default", () => {
+    expect(resolveSbomFormat({ sbom: { format: "cyclonedx" } })).toBe("cyclonedx");
+  });
+
+  test("a step-level format always wins over project config", () => {
+    expect(resolveSbomFormat({ sbom: { format: "cyclonedx" } }, "spdx")).toBe("spdx");
+    expect(resolveSbomFormat({}, "cyclonedx")).toBe("cyclonedx");
+  });
 });

package/src/config.ts

@@ -3,12 +3,16 @@ import { join } from "path";
 import { z } from "zod";
 import type { LintConfig } from "./lint/config";
 import type { OwnershipMarker } from "./ownership";
+import { DEFAULT_SBOM_FORMAT, type SbomFormat } from "./components/verbs/sbom-generator";
+import type { Severity } from "./components/verbs/vuln-scan";
+import type { VulnPolicy } from "./components/verbs/vuln-gate";
 
 /**
  * Zod schema for ChantConfig validation.
  */
 export const ChantConfigSchema = z.object({
   lexicons: z.array(z.string().min(1)).optional(),
+  capabilities: z.array(z.string().min(1)).optional(),
   environments: z.array(z.string().min(1)).optional(),
   sourceDir: z.string().min(1).optional(),
   lint: z.record(z.string(), z.unknown()).optional(),
@@ -17,6 +21,33 @@ export const ChantConfigSchema = z.object({
     env: z.string().min(1).optional(),
     enabled: z.boolean().optional(),
   }).optional(),
+  release: z.object({
+    autoRecord: z.boolean().optional(),
+  }).optional(),
+  sbom: z.object({
+    format: z.enum(["spdx", "cyclonedx"]).optional(),
+    enabled: z.boolean().optional(),
+  }).optional(),
+  signing: z.object({
+    keyless: z.boolean().optional(),
+    oidcIssuer: z.string().min(1).optional(),
+    identity: z.string().min(1).optional(),
+    identityIsRegexp: z.boolean().optional(),
+    key: z.string().min(1).optional(),
+  }).optional(),
+  vulnPolicy: z.object({
+    failSeverity: z.enum(["critical", "high", "medium", "low", "negligible", "unknown"]).optional(),
+    fixableOnly: z.boolean().optional(),
+    warnSeverity: z.enum(["critical", "high", "medium", "low", "negligible", "unknown"]).optional(),
+    failOnLicense: z.boolean().optional(),
+    failOnUnknownSeverity: z.boolean().optional(),
+    license: z.object({
+      allow: z.array(z.string()).optional(),
+      deny: z.array(z.string()).optional(),
+    }).optional(),
+    scanner: z.enum(["grype", "trivy"]).optional(),
+    vexSources: z.array(z.string()).optional(),
+  }).optional(),
 }).passthrough();
 
 /**
@@ -28,6 +59,17 @@ export interface ChantConfig {
   /** Lexicon package names to load (e.g. ["aws"]) */
   lexicons?: string[];
 
+  /**
+   * Capability plugin package names to load in addition to the built-in
+   * starter set (e.g. ["acme"] loads `@intentius/chant-capability-acme`),
+   * mirroring `lexicons` — see {@link CapabilityPlugin} in
+   * `./components/capability-plugin.ts` and `buildCapabilityRegistry` in
+   * `./components/capability-plugin-loader.ts` (#559, epic #551). The
+   * built-in starter verb set (`./components/starter-plugin.ts`) is always
+   * loaded regardless of this field.
+   */
+  capabilities?: string[];
+
   /** Environment names (e.g. ["staging", "prod"]) */
   environments?: string[];
 
@@ -57,6 +99,88 @@ export interface ChantConfig {
     /** Set false to disable stamping even when `stack` is present. */
     enabled?: boolean;
   };
+
+  /**
+   * Release-ledger recording behavior (#597, epic #551). Auto-emitting a
+   * release record on a successful `chant run --components <name> --env
+   * <env>` deploy is ON by default — this is opt-**out**, not opt-in, per
+   * #597's "populate the ledger by construction." See {@link
+   * resolveAutoReleaseDisabled}.
+   */
+  release?: {
+    /** Set false to disable auto-emitting a release record after a successful component deploy project-wide. The `--no-release-record` CLI flag overrides this per-invocation. */
+    autoRecord?: boolean;
+  };
+
+  /**
+   * Project-wide SBOM generation defaults (#606, epic #551 follow-up to
+   * #564/#568). Consumed by the `generate-sbom` capability
+   * (./components/verbs/sbom.ts) via {@link resolveSbomFormat} — a
+   * component's own `build.sbom.format` (see `BuildSpec` in
+   * ./components/component.ts) always wins over this project default when
+   * set, mirroring how `ownership`/`release` are project-wide defaults a
+   * more specific caller can override.
+   */
+  sbom?: {
+    /** Default SBOM format for every `generate-sbom` step that doesn't specify its own. Defaults to `DEFAULT_SBOM_FORMAT` ("spdx", see ./components/verbs/sbom-generator.ts) when unset — BuildKit natively emits SPDX attestations for images. */
+    format?: SbomFormat;
+    /** Set false to opt this project out of SBOM generation entirely — components composing a `generate-sbom` step still run it explicitly, but this is the project-wide switch a component author can point to when deciding whether to include the step at all. Purely advisory: `generate-sbom` has no implicit/automatic invocation to suppress (a component's composition always decides), so this flag has no effect unless a component's own authoring code reads it. */
+    enabled?: boolean;
+  };
+
+  /**
+   * Project-wide signing/verification defaults (#622, epic #551 follow-up to
+   * #614's reproducibility/provenance material). Consumed by
+   * `./components/verbs/sign.ts`'s `sign`/`attest-provenance` capabilities and
+   * `./components/verbs/verify.ts`'s `verify` gate via {@link
+   * resolveSigningDefaults}. **Keyless is the default** — `keyless: false`
+   * plus `key` is the opt-in override for a team with an existing KMS/file
+   * key policy (see `./components/verbs/sign.ts`'s module doc for why keyless
+   * is never something a beginner has to turn on). `oidcIssuer`/`identity`
+   * are the one identity-setup step #622 asks projects to document: the
+   * expected signer for `verify`'s identity policy (e.g. GitHub Actions'
+   * OIDC issuer + a workflow ref).
+   */
+  signing?: {
+    /** Set false only alongside `key` to opt into key-based signing instead of the keyless default. Omit (or leave `true`) for the default keyless flow. */
+    keyless?: boolean;
+    /** Expected OIDC issuer for keyless signing/verification (e.g. `"https://token.actions.githubusercontent.com"` for GitHub Actions). Required for `verify`'s identity policy; optional for `sign`/`attest-provenance`, which can rely on cosign's own ambient OIDC detection in CI. */
+    oidcIssuer?: string;
+    /** Expected signer identity (e.g. a workflow ref URI) `verify` checks the certificate against. Required for `verify`'s identity policy. */
+    identity?: string;
+    /** Treat `identity` as a regexp rather than a literal match — see `IdentityPolicy.identityIsRegexp` in `./components/verbs/verify.ts`. */
+    identityIsRegexp?: boolean;
+    /** Opt-in key-based override (a path, or `kms://`/`awskms://`/... reference) for `sign`/`attest-provenance`/`verify` alike. Presence alone does not disable keyless — pair with `keyless: false` for clarity, though a capability call that explicitly sets its own `key`/`policy.key` always wins over this project default either way. */
+    key?: string;
+  };
+
+  /**
+   * Project-wide vulnerability/license policy-gate defaults (#626, epic #551
+   * supply-chain follow-up to the SBOM stack). Consumed by
+   * `./components/verbs/vuln-gate.ts`'s `vuln-gate` capability via {@link
+   * resolveVulnPolicy}. **Beginner-safe defaults** (see `DEFAULT_VULN_POLICY`
+   * in `./components/verbs/vuln-gate.ts`): block only `critical` + `fixable` +
+   * not-VEX-suppressed findings, warn on `high`, license report-only. Every
+   * field here overrides one of those defaults.
+   */
+  vulnPolicy?: {
+    /** Minimum severity that FAILS the gate. Default `"critical"`. */
+    failSeverity?: Severity;
+    /** Only fixable findings at/above `failSeverity` block. Default `true`. */
+    fixableOnly?: boolean;
+    /** Minimum severity reported as a warning. Default `"high"`. */
+    warnSeverity?: Severity;
+    /** Block on a license violation (else report-only). Default `false`. */
+    failOnLicense?: boolean;
+    /** Block on an `unknown`-severity finding (always warned regardless). Default `false`. */
+    failOnUnknownSeverity?: boolean;
+    /** License allow/deny lists evaluated against the SBOM's declared licenses. */
+    license?: { allow?: string[]; deny?: string[] };
+    /** Which real scanner a `ProcessRunner`-backed `vuln-gate`/`scan-vulnerabilities` shells out to. Default `"grype"`. Read where the capability/scanner is constructed. */
+    scanner?: "grype" | "trivy";
+    /** Default VEX document paths (OpenVEX/CycloneDX) applied to every gate. Read where the gate step is composed. */
+    vexSources?: string[];
+  };
 }
 
 /**
@@ -112,6 +236,101 @@ export function resolveOwnershipMarker(config: ChantConfig): OwnershipMarker | u
   return { stack: o.stack, env: o.env };
 }
 
+/**
+ * Whether auto-emitting a release-ledger record after a successful `chant
+ * run --components` deploy should be skipped (#597). Opt-out, not opt-in:
+ * recording happens unless the CLI's `--no-release-record` flag was passed
+ * (`cliFlag`) or the project config sets `release.autoRecord: false` — the
+ * flag always wins for that one invocation, regardless of config.
+ */
+export function resolveAutoReleaseDisabled(config: ChantConfig, cliFlag?: boolean): boolean {
+  if (cliFlag) return true;
+  return config.release?.autoRecord === false;
+}
+
+/**
+ * Resolve which SBOM format a `generate-sbom` step should request (#606),
+ * given the project's `chant.config.ts` `sbom.format` and an optional
+ * component/step-level override. Precedence, most to least specific:
+ * `stepFormat` (the component's own `build.sbom.format` or an explicit
+ * `generate-sbom` step input) > `config.sbom.format` (project default) >
+ * `DEFAULT_SBOM_FORMAT` ("spdx", ./components/verbs/sbom-generator.ts).
+ * Never hardcodes one format as *the* format — this is purely precedence
+ * resolution over the two first-class formats SPDX/CycloneDX.
+ */
+export function resolveSbomFormat(config: ChantConfig, stepFormat?: SbomFormat): SbomFormat {
+  return stepFormat ?? config.sbom?.format ?? DEFAULT_SBOM_FORMAT;
+}
+
+/**
+ * Resolved signing defaults a `sign`/`attest-provenance`/`verify` capability
+ * call can spread its own `keyless`/`key`/`policy` input over (#622). Shaped
+ * to match `./components/verbs/sign.ts`'s `KeyBasedSigningConfig` (the `key`
+ * field) and `./components/verbs/verify.ts`'s `IdentityPolicy` (`expectedIssuer`/
+ * `expectedIdentity`/`identityIsRegexp`) so a caller can do
+ * `{ ...resolveSigningDefaults(config).identityPolicyDefaults, ...override }`
+ * without a config module import inside `./components/verbs/*` (no verb
+ * module imports `../../config.ts` directly — same convention `resolveSbomFormat`'s
+ * callers already follow: the orchestrator/caller resolves config, capabilities
+ * stay config-free).
+ */
+export interface ResolvedSigningDefaults {
+  /** False only when the project opted into the key-based override (`signing.keyless === false`). True (keyless) otherwise — the #622 default. */
+  keyless: boolean;
+  /** `./components/verbs/sign.ts`'s `KeyBasedSigningConfig`, present only when key-based signing is configured (`signing.key` set). */
+  key?: { key: string };
+  /** Partial `./components/verbs/verify.ts` `IdentityPolicy` fields resolved from project config — a caller still supplies any per-call override and must ensure `expectedIssuer`/`expectedIdentity` end up set before calling `verify` (config alone does not guarantee both are present). */
+  identityPolicyDefaults: {
+    expectedIssuer?: string;
+    expectedIdentity?: string;
+    identityIsRegexp?: boolean;
+    key?: string;
+  };
+}
+
+/**
+ * Resolve project-wide signing defaults from `chant.config.ts`'s `signing`
+ * section (#622). Keyless unless `signing.keyless === false` — the same
+ * "default is the safe choice, override is explicit" precedence
+ * `resolveOwnershipMarker`/`resolveAutoReleaseDisabled` already use for their
+ * respective opt-outs.
+ */
+export function resolveSigningDefaults(config: ChantConfig): ResolvedSigningDefaults {
+  const s = config.signing;
+  const keyless = s?.keyless !== false;
+  return {
+    keyless,
+    ...(!keyless && s?.key ? { key: { key: s.key } } : {}),
+    identityPolicyDefaults: {
+      expectedIssuer: s?.oidcIssuer,
+      expectedIdentity: s?.identity,
+      identityIsRegexp: s?.identityIsRegexp,
+      key: s?.keyless === false ? s?.key : undefined,
+    },
+  };
+}
+
+/**
+ * Resolve the `vuln-gate` policy overrides from `chant.config.ts`'s
+ * `vulnPolicy` section (#626). Returns only the fields the project set; the
+ * gate merges these over its own `DEFAULT_VULN_POLICY`
+ * (`./components/verbs/vuln-gate.ts`), so an empty/absent section yields the
+ * beginner-safe defaults. `scanner`/`vexSources` are not policy fields — they
+ * configure how the capability is constructed and are read separately.
+ */
+export function resolveVulnPolicy(config: ChantConfig): Partial<VulnPolicy> {
+  const v = config.vulnPolicy;
+  if (!v) return {};
+  const out: Partial<VulnPolicy> = {};
+  if (v.failSeverity) out.failSeverity = v.failSeverity;
+  if (v.fixableOnly !== undefined) out.fixableOnly = v.fixableOnly;
+  if (v.warnSeverity) out.warnSeverity = v.warnSeverity;
+  if (v.failOnLicense !== undefined) out.failOnLicense = v.failOnLicense;
+  if (v.failOnUnknownSeverity !== undefined) out.failOnUnknownSeverity = v.failOnUnknownSeverity;
+  if (v.license) out.license = v.license;
+  return out;
+}
+
 /**
  * Validate and normalize a raw config object into ChantConfig shape.
  */

package/src/index.ts

@@ -60,6 +60,38 @@ export * from "./codegen/typecheck";
 export * from "./codegen/coverage";
 export * from "./codegen/validate";
 export * from "./codegen/docs";
+export * from "./codegen/surface-snapshot";
+export {
+  regenLexicon,
+  writeSurfaceSnapshot,
+  SNAPSHOT_FILENAME,
+  type RegenOptions,
+  type RegenResult,
+  type RegenFailure,
+} from "./codegen/lexicon-regen";
+export {
+  checkRollingUpgrade,
+  classifyDelta,
+  diffRollingSurface,
+  computeAzureApiVersionDelta,
+  diffAzureApiVersions,
+  extractAzureProvider,
+  type RollingLexicon,
+  type RollingUpgradeResult,
+  type CheckRollingUpgradeOptions,
+  type AzureApiVersionChange,
+} from "./codegen/rolling-upgrade";
+export {
+  checkPinnedUpgrade,
+  applyPinnedVersionBump,
+  isNewer,
+  parseVersion,
+  isPreRelease,
+  type LexiconId,
+  type UpgradeCheckResult,
+  type CheckPinnedUpgradeOptions,
+  type UpstreamResolver,
+} from "./codegen/pinned-upgrade";
 export * from "./runtime";
 export * from "./runtime-adapter";
 export * from "./resource-attributes";