@intentius/chant 0.124.32 → 0.124.34

package/src/workspace/ci-serve.ts

@@ -3,11 +3,15 @@
  * host. It polls the forge for the open pull requests into the target branch
  * and for the branch's head, and runs the pull-request jobs with
  * {@link ciRun} (./ci-run.ts): `plan` for each new pull request head, and
- * `apply` for each new commit on the target branch, measured from the head
- * the previous poll saw (the push's `before`).
+ * `record` for each new commit on the target branch (#4168), measured from
+ * the head the previous poll saw (the push's `before`). The record applies
+ * nothing; with `applyOnMerge` (`--apply-on-merge`) the commit gets `apply`
+ * in its place, as before #4168. After each job settles it runs `ci tick`
+ * from the runs the jobs recorded, when the declaration has `ci.green`.
+ * What the list below says of the apply holds for it under `applyOnMerge`.
  *
  * - Dedupe. A state file in the state directory keeps every job it started,
- *   keyed by job and commit (`plan:<pr>:<sha>`, `apply:<sha>`), with how it
+ *   keyed by job and commit (`plan:<pr>:<sha>`, `record:<sha>`, `apply:<sha>`), with how it
  *   ended, and the target head the last apply was measured to. A job already
  *   in it is not started again, unless it failed and `rerunFailed` asks for
  *   it: the forge's "re-run failed jobs".
@@ -37,6 +41,14 @@
  * - `[skip ci]` (#4122). A target head or pull request head whose commit
  *   message says `[skip ci]` or `[ci skip]` is recorded as seen and not run,
  *   as Actions does.
+ * - Build requests (#4169). With `buildCommand`, each `ci/build/<sha>`
+ *   tag the tick or `ci run --at` pushed is served once: the command runs
+ *   in a fresh detached worktree of the commit, with `CHANT_BUILD_COMMIT`,
+ *   `CHANT_BUILD_PHASES` (comma-separated) and `CHANT_BUILD_REASON` set,
+ *   and is expected to run the phases' Ops (`chant run <op>`), whose
+ *   records the tick reads. A build counts against `maxJobs`, and the state
+ *   file keeps it under `build:<sha>`. Without `buildCommand` the tags are
+ *   left alone.
  * - The forge's ledger (#4121). Before each job, when no other job of this
  *   serve runs, the clone's `chant/lifecycle` follows the forge's: it is
  *   deleted when the forge has none, and reset to the forge's when neither
@@ -54,9 +66,11 @@
  * turn a checked payload into the same triggers and schedule them.
  */
 
-import { execFileSync, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { CI_BUILD_TAG_PREFIX, readBuildRequests, type BuildRequest } from "./ci-builds";
 import { prApplyGroup, prApplyRecordKey } from "../components/pr-pipeline";
 import { forgeFromEnv, type OpenPullRequest } from "../pr-forge";
 import type { CommandContext } from "../cli/registry";
@@ -65,7 +79,7 @@ import { acquireLease, currentHolderId, releaseLease, DEFAULT_LEASE_TTL_MS, type
 import { parseDuration } from "../op/duration";
 import { reportUrlOf } from "./ci-report-url";
 import { CI_JOB_OPS, ciJobPlace, ciLoopOptions, ciSecretsOf, ciRun, ciStatusFromEnv, CiRunError, type CiJobName, type CiRunRequest, type CiRunResult } from "./ci-run";
-import { RUNNER_KEY_ENV, signedRunsRequired } from "./ci-green";
+import { CiGreenError, ciTick, RUNNER_KEY_ENV, signedRunsRequired } from "./ci-green";
 import { gitTop } from "./tree";
 import { ciServeRunnerKey, formatRunnerKeySetup, setupRunnerKey } from "./ci-runner-key";
 
@@ -80,10 +94,14 @@ export interface CiServeForge {
   pullRequestFor?(sha: string): Promise<number | null>;
 }
 
-/** A job the forge's state calls for: the plan of a pull request's head, or the apply of a target-branch commit. */
+/**
+ * A job the forge's state calls for: the plan of a pull request's head, or
+ * for a target-branch commit its record (#4168) or, with `applyOnMerge`,
+ * its apply.
+ */
 export type CiServeTrigger =
   | { job: "plan"; commit: string; base: string; pr: number; rerun?: boolean }
-  | { job: "apply"; commit: string; base: string; rerun?: boolean };
+  | { job: "apply" | "record"; commit: string; base: string; rerun?: boolean };
 
 /** One job in the state file. */
 export interface CiServeJobState {
@@ -116,6 +134,8 @@ export interface CiServeState {
   jobs: Record<string, CiServeJobState>;
   /** Plans seen and not run, by state key, with why (#4122). */
   skipped?: Record<string, "skip-ci">;
+  /** The build requests served (#4169), by `build:<sha>`, with how each ended. */
+  builds?: Record<string, { tag: string; status: "running" | "ok" | "fail"; startedAt: string; settledAt?: string }>;
 }
 
 /** What a pass did, in order, for the log. */
@@ -128,6 +148,9 @@ export type CiServeEvent =
   | { type: "settled"; job: CiJobName; commit: string; pr?: number; status: "ok" | "fail"; failure?: string; report?: string }
   | { type: "not-run"; job: CiJobName; commit: string; pr?: number; reason: "not-fast-forward" | "skip-ci"; branch?: string; from?: string }
   | { type: "ledger"; action: "deleted" | "reset"; local: string; forge?: string }
+  | { type: "build"; commit: string; phases: string[]; status: "started" | "ok" | "fail" | "held"; exitCode?: number }
+  /** `ci tick` after the pass (#4168): the tags it made from the runs. */
+  | { type: "tick"; made: string[] }
   | { type: "error"; message: string };
 
 /** The `ciRun` request fields `ci serve` passes through to every job: the generator's options and the runner's. */
@@ -149,6 +172,18 @@ export interface CiServeOptions {
   authors?: readonly string[];
   /** Run again the failed apply at the target's head, and the failed plans of open heads. */
   rerunFailed?: boolean;
+  /**
+   * Apply each new target-branch commit (#4168), as `ci serve` did before
+   * #4168. Default false: each new commit gets the record job, which applies
+   * nothing.
+   */
+  applyOnMerge?: boolean;
+  /**
+   * Run after each pass that settled a job (#4168): `ci tick` from the runs
+   * the jobs recorded. Returns the tags it made, or undefined when the
+   * declaration has no `ci.green`. The command passes one; a test may not.
+   */
+  tick?: () => Promise<string[] | undefined>;
   /** Passed to each job. `job.hostEnv` gets `GITHUB_REPOSITORY` set to `repo`. */
   job?: CiServeJobOptions;
   /** This process's lease identity. Default `currentHolderId()`. */
@@ -158,18 +193,26 @@ export interface CiServeOptions {
   now?: () => Date;
   /** Runs a job. Default {@link ciRun}. */
   run?: (req: CiRunRequest) => Promise<CiRunResult>;
+  /**
+   * The shell line that builds a requested commit (#4169), run in a fresh
+   * worktree of it. Without it `ci/build/<sha>` tags are not served.
+   */
+  buildCommand?: string;
+  /** Runs a build. Default: `sh -c <buildCommand>` in a detached worktree of the commit. */
+  build?: (input: { top: string; request: BuildRequest; command: string }) => Promise<number>;
 }
 
 /** The jobs this process runs now, by state key, shared by every pass of one loop. */
 export interface CiServeRuntime {
-  inflight: Map<string, Promise<CiServeJobState>>;
+  /** Jobs and build requests (#4169) alike, by state key: they share `maxJobs`. */
+  inflight: Map<string, Promise<unknown>>;
 }
 
 export const newCiServeRuntime = (): CiServeRuntime => ({ inflight: new Map() });
 
 /** The state key of a job. */
 export function ciServeKey(t: { job: CiJobName; commit: string; pr?: number }): string {
-  return t.job === "plan" ? `plan:${t.pr}:${t.commit}` : `apply:${t.commit}`;
+  return t.job === "plan" ? `plan:${t.pr}:${t.commit}` : `${t.job}:${t.commit}`;
 }
 
 const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
@@ -324,6 +367,8 @@ export async function ciServeObserve(opts: CiServeOptions, rt: CiServeRuntime =
   const triggers: CiServeTrigger[] = [];
   const events: CiServeEvent[] = [];
   const [head, prs] = await Promise.all([opts.client.branchHead(place.branch), opts.client.openPullRequests(place.branch)]);
+  // #4168: a new target commit is recorded, and applied only with applyOnMerge.
+  const onMerge: "apply" | "record" = opts.applyOnMerge ? "apply" : "record";
 
   if (head === undefined) {
     events.push({ type: "no-branch", branch: place.branch });
@@ -336,7 +381,7 @@ export async function ciServeObserve(opts: CiServeOptions, rt: CiServeRuntime =
   } else if (head !== state.target) {
     const from = state.target;
     const move = targetMove(place.top, place.branch, from, head);
-    const entry = state.jobs[ciServeKey({ job: "apply", commit: head })];
+    const entry = state.jobs[ciServeKey({ job: onMerge, commit: head })];
     if (move === "unknown") {
       events.push({ type: "error", message: `${place.branch} is at ${head.slice(0, 12)} on the forge, and that commit could not be fetched; the next poll tries again` });
     } else if (move === "other" || (!entry && skipsCi(place.top, head))) {
@@ -344,13 +389,13 @@ export async function ciServeObserve(opts: CiServeOptions, rt: CiServeRuntime =
       update((s) => {
         s.target = head;
       });
-      events.push({ type: "not-run", job: "apply", commit: head, reason: move === "other" ? "not-fast-forward" : "skip-ci", ...(move === "other" ? { branch: place.branch, from } : {}) });
-    } else if (!entry) triggers.push({ job: "apply", commit: head, base: from });
-    else if (opts.rerunFailed && failedEntry(entry, ciServeKey(entry), rt)) triggers.push({ job: "apply", commit: head, base: entry.base, rerun: true });
+      events.push({ type: "not-run", job: onMerge, commit: head, reason: move === "other" ? "not-fast-forward" : "skip-ci", ...(move === "other" ? { branch: place.branch, from } : {}) });
+    } else if (!entry) triggers.push({ job: onMerge, commit: head, base: from });
+    else if (opts.rerunFailed && failedEntry(entry, ciServeKey(entry), rt)) triggers.push({ job: onMerge, commit: head, base: entry.base, rerun: true });
   } else {
-    const key = ciServeKey({ job: "apply", commit: head });
+    const key = ciServeKey({ job: onMerge, commit: head });
     const entry = state.jobs[key];
-    if (opts.rerunFailed && failedEntry(entry, key, rt)) triggers.push({ job: "apply", commit: head, base: entry.base, rerun: true });
+    if (opts.rerunFailed && failedEntry(entry, key, rt)) triggers.push({ job: onMerge, commit: head, base: entry.base, rerun: true });
   }
 
   const authors = opts.authors?.length ? new Set(opts.authors.map((a) => a.toLowerCase())) : undefined;
@@ -453,7 +498,7 @@ export async function ciServeSchedule(opts: CiServeOptions, triggers: readonly C
     const entry: CiServeJobState = { job: t.job, commit: t.commit, base: t.base, ...pr, status: "running", runId, attempts: attempt, startedAt: now().toISOString() };
     update((s) => {
       s.jobs[key] = entry;
-      if (t.job === "apply" && !t.rerun) s.target = t.commit;
+      if (t.job !== "plan" && !t.rerun) s.target = t.commit;
     });
     emit({ type: "started", job: t.job, commit: t.commit, ...pr, base: t.base, runId, attempt, ...(resume && existsSync(resume) ? { resume } : {}) });
 
@@ -468,7 +513,7 @@ export async function ciServeSchedule(opts: CiServeOptions, triggers: readonly C
         emit({ type: "error", message: `${key} settled, and the state file could not be written: ${message(err)}` });
       }
       emit({ type: "settled", job: t.job, commit: t.commit, ...pr, status: settled.status === "ok" ? "ok" : "fail", ...(settled.failure ? { failure: settled.failure } : {}), ...(settled.report ? { report: settled.report } : {}) });
-      return settled;
+      return serveTick(opts).then(() => settled);
     });
     rt.inflight.set(key, job);
     started.push(job);
@@ -496,7 +541,7 @@ async function runJob(
     tryGit(place.top, ["fetch", "--quiet", "--no-tags", "origin", t.job === "plan" ? `refs/pull/${t.pr}/head` : place.branch]);
     const hostEnv = { ...(opts.job?.hostEnv ?? process.env), GITHUB_REPOSITORY: opts.repo };
     // An apply is for a merge: pass the pull request whose merge commit it is, so the commit status link and the run index use `<pr>/<commit>`. None found, or a forge that errs, is today's behaviour.
-    if (t.job === "apply" && opts.client.pullRequestFor) merged = (await opts.client.pullRequestFor(t.commit).catch(() => null)) ?? undefined;
+    if (t.job !== "plan" && opts.client.pullRequestFor) merged = (await opts.client.pullRequestFor(t.commit).catch(() => null)) ?? undefined;
     const run = opts.run ?? ciRun;
     const r = await run({
       ...opts.job,
@@ -522,13 +567,101 @@ async function runJob(
   }
 }
 
-/** One pass: observe, schedule, and with `wait` wait for the jobs it started. */
+/** One pass: observe, schedule, serve build requests, and with `wait` wait for the jobs it started. */
 export async function ciServePass(opts: CiServeOptions, rt: CiServeRuntime = newCiServeRuntime(), wait = true): Promise<{ events: CiServeEvent[]; jobs: CiServeJobState[] }> {
   const observed = await ciServeObserve(opts, rt);
   for (const e of observed.events) opts.log?.(e);
   const scheduled = await ciServeSchedule(opts, observed.triggers, rt);
+  const builds = opts.buildCommand ? ciServeBuilds(opts, rt) : { started: [], events: [] };
   const jobs = wait ? await Promise.all(scheduled.started) : [];
-  return { events: [...observed.events, ...scheduled.events], jobs };
+  if (wait) await Promise.all(builds.started);
+  return { events: [...observed.events, ...scheduled.events, ...builds.events], jobs };
+}
+
+/**
+ * Serve the build requests (#4169): fetch the `ci/build/*` tags, and start
+ * `buildCommand` for each one not in the state file yet, oldest first, while
+ * fewer than `maxJobs` jobs run. A build that fails is recorded and not run
+ * again; the tick decides what its phases say.
+ */
+export function ciServeBuilds(opts: CiServeOptions, rt: CiServeRuntime): { started: Promise<void>[]; events: CiServeEvent[] } {
+  const place = servePlace(opts);
+  const fresh = { forge: opts.forge, repo: opts.repo, env: opts.env, branch: place.branch, ...(place.member ? { member: place.member } : {}) };
+  const update = (fn: (s: CiServeState) => void): void => {
+    const st = readCiServeState(place.stateFile, fresh);
+    fn(st);
+    writeState(place.stateFile, st);
+  };
+  const events: CiServeEvent[] = [];
+  const started: Promise<void>[] = [];
+  tryGit(place.top, ["fetch", "--quiet", "--prune", "origin", `+refs/tags/${CI_BUILD_TAG_PREFIX}*:refs/tags/${CI_BUILD_TAG_PREFIX}*`]);
+  const served = readCiServeState(place.stateFile, fresh).builds ?? {};
+  const max = opts.maxJobs ?? 1;
+  const now = opts.now ?? (() => new Date());
+  const requests = [...readBuildRequests(place.top).values()].sort((a, b) => a.at.localeCompare(b.at));
+  for (const request of requests) {
+    const key = `build:${request.commit}`;
+    if (served[key]?.tag === request.tag || rt.inflight.has(key)) continue;
+    const log = (e: CiServeEvent) => {
+      events.push(e);
+      opts.log?.(e);
+    };
+    if (rt.inflight.size >= max) {
+      log({ type: "build", commit: request.commit, phases: request.phases, status: "held" });
+      continue;
+    }
+    update((st) => {
+      st.builds = { ...st.builds, [key]: { tag: request.tag, status: "running", startedAt: now().toISOString() } };
+    });
+    log({ type: "build", commit: request.commit, phases: request.phases, status: "started" });
+    const build = opts.build ?? runBuild;
+    const job = build({ top: place.top, request, command: opts.buildCommand! })
+      .catch(() => 1)
+      .then((code) => {
+        update((st) => {
+          st.builds = { ...st.builds, [key]: { tag: request.tag, status: code === 0 ? "ok" : "fail", startedAt: st.builds?.[key]?.startedAt ?? now().toISOString(), settledAt: now().toISOString() } };
+        });
+        opts.log?.({ type: "build", commit: request.commit, phases: request.phases, status: code === 0 ? "ok" : "fail", exitCode: code });
+      });
+    const tracked = job.finally(() => rt.inflight.delete(key));
+    rt.inflight.set(key, tracked);
+    started.push(tracked);
+  }
+  return { started, events };
+}
+
+/** `sh -c <command>` in a fresh detached worktree of the request's commit, removed after. Resolves to the exit code. */
+async function runBuild(input: { top: string; request: BuildRequest; command: string }): Promise<number> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-ci-build-"));
+  try {
+    execFileSync("git", ["worktree", "add", "--quiet", "--detach", dir, input.request.commit], { cwd: input.top, stdio: ["ignore", "pipe", "pipe"] });
+    return await new Promise<number>((done) => {
+      const child = spawn("sh", ["-c", input.command], {
+        cwd: dir,
+        stdio: ["ignore", "inherit", "inherit"],
+        env: { ...process.env, CHANT_BUILD_COMMIT: input.request.commit, CHANT_BUILD_PHASES: input.request.phases.join(","), CHANT_BUILD_REASON: input.request.reason },
+      });
+      child.on("error", () => done(127));
+      child.on("close", (code) => done(code ?? 1));
+    });
+  } finally {
+    tryGit(input.top, ["worktree", "remove", "--force", dir]);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** `ci tick` after a job settled (#4168), logged; a tick that fails is an error event and never fails the job. */
+async function serveTick(opts: CiServeOptions): Promise<CiServeEvent | undefined> {
+  if (!opts.tick) return undefined;
+  let event: CiServeEvent | undefined;
+  try {
+    const made = await opts.tick();
+    event = made === undefined ? undefined : { type: "tick", made };
+  } catch (err) {
+    event = { type: "error", message: `ci tick after a job settled: ${message(err)}` };
+  }
+  if (event) opts.log?.(event);
+  return event;
 }
 
 /**
@@ -579,6 +712,13 @@ export function formatCiServeEvent(e: CiServeEvent): string {
       return e.action === "deleted"
         ? `the forge has no ${LEDGER}, so this clone's, at ${e.local.slice(0, 12)}, was deleted`
         : `the forge's ${LEDGER} at ${e.forge!.slice(0, 12)} does not contain this clone's at ${e.local.slice(0, 12)}, so this clone's was reset to the forge's and not pushed`;
+    case "build": {
+      const what = `the build of ${e.phases.join(", ")} at ${e.commit.slice(0, 12)}`;
+      if (e.status === "held") return `${what} waits: --max-jobs jobs run`;
+      return e.status === "started" ? `${what} started` : e.status === "ok" ? `${what} passed` : `${what} failed${e.exitCode !== undefined ? ` with exit code ${e.exitCode}` : ""}`;
+    }
+    case "tick":
+      return e.made.length > 0 ? `ci tick made ${e.made.join(", ")}` : "ci tick: no tag due";
     case "error":
       return `error: ${e.message}`;
   }
@@ -615,7 +755,7 @@ export function runnerKeySetupCommand(ctx: CommandContext): number {
 const USAGE =
   "chant ci serve --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>] | " +
   "chant ci serve --forge forgejo|github --repo <owner/repo> --env <env> [--interval <s>] [--max-jobs <n>] [--state <dir>] " +
-  "[--author <login>]... [--once] [--rerun-failed] [--gate <name>] [--wave-gate <name>] [--branch <name>] [--events-json] [--report-url <url>] [--no-status] [--status-url <url template>] " +
+  "[--author <login>]... [--once] [--rerun-failed] [--build-command <line>] [--gate <name>] [--wave-gate <name>] [--branch <name>] [--events-json] [--report-url <url>] [--no-status] [--status-url <url template>] " +
   "[--image <image>] [--before-script <line>]... [--pr-build] [--pr-build-command <line>] [--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [--unsigned]";
 
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -638,6 +778,8 @@ export async function runCiServe(ctx: CommandContext): Promise<number> {
     if (!args.ciRepo) throw new CiRunError("--repo names the repository whose pull requests ci serve polls: --repo <owner/repo>");
     if (!args.env) throw new CiRunError("--env names the environment the pipeline is for: --env <env>");
     for (const name of args.passEnv ?? []) if (!ENV_NAME.test(name)) throw new CiRunError(`--pass-env takes a variable's name, not ${JSON.stringify(name)}`);
+    // #4168: a gate per wave gates the apply on merge, which a merge runs only when opted in.
+    if (args.waveGate && !args.applyOnMerge) throw new CiRunError("--wave-gate gates the apply on merge, so it needs --apply-on-merge (#4168); without it a merge gets the record job, which applies nothing");
     const intervalMs = ciServeInterval(args.interval);
     const cwd = process.cwd();
     const top = gitTop(cwd);
@@ -670,6 +812,8 @@ export async function runCiServe(ctx: CommandContext): Promise<number> {
     const { status, warning } = ciStatusFromEnv({ forge, hostEnv, noStatus: args.noStatus, statusUrl: args.statusUrl });
     if (warning) console.error(formatWarning({ message: warning }));
     if (!client.openPullRequests || !client.branchHead) throw new CiRunError(`the ${forge} client cannot list pull requests`);
+    // #4168: a host that applied each merge before the upgrade hears that it no longer does.
+    if (!args.applyOnMerge) console.error("ci serve: each new commit on the target branch gets the record job, which applies nothing (#4168); --apply-on-merge applies it");
     const opts: CiServeOptions = {
       cwd,
       forge,
@@ -680,6 +824,17 @@ export async function runCiServe(ctx: CommandContext): Promise<number> {
       ...(args.maxJobs ? { maxJobs: args.maxJobs } : {}),
       ...(args.ciAuthors?.length ? { authors: args.ciAuthors } : {}),
       ...(args.rerunFailed ? { rerunFailed: true } : {}),
+      ...(args.ciBuildCommand ? { buildCommand: args.ciBuildCommand } : {}),
+      ...(args.applyOnMerge ? { applyOnMerge: true } : {}),
+      // #4168: the tick from the runs the jobs recorded, signed with the runs' key. No ci.green, no tick.
+      tick: async () => {
+        try {
+          return (await ciTick({ cwd, source: "runs", ...(runnerKey !== undefined ? { runnerKey } : {}) })).made;
+        } catch (err) {
+          if (err instanceof CiGreenError && err.code === "ci-green-undeclared") return undefined;
+          throw err;
+        }
+      },
       job: {
         loop: ciLoopOptions(reportUrl ? { ...args, reportUrl } : args),
         ...(args.runIndexLimit ? { runIndexLimit: args.runIndexLimit } : {}),

package/src/workspace/ci-workflow.ts

@@ -0,0 +1,71 @@
+/**
+ * The prescribed delivery workflows (#4168 section 7): `ci.workflow` in the
+ * declaration, at the top level or on a member, which wins.
+ *
+ * `trunk-curated`: a merge records the plan and deploys nothing (#4168 4.1),
+ * the quick checks run before the branch moves (4.4), and a release is cut
+ * from a green commit and promoted through the member's environments, gated
+ * in the last (4.2). `trunk-curated+apply-on-merge` is the same with the apply
+ * on merge turned back on (section 5).
+ *
+ * A workflow requires no security group: those are opt-in on their own
+ * (./security.ts). `chant workspace check` reports what a member under a
+ * workflow still lacks (./checks/ci-workflow.ts, WSP151), and `chant ci
+ * init` writes what it can. {@link CI_WORKFLOW_REQUIREMENTS} is the table the
+ * reference page prints.
+ */
+import type { CiWorkflow, Declaration, Member } from "./declaration";
+
+/** The marker a component stub `chant ci init` writes carries until someone fills it in. WSP151 reports a member whose only components carry it. */
+export const STUB_MARKER = "TODO(chant ci init)";
+
+export const CI_WORKFLOWS = ["trunk-curated", "trunk-curated+apply-on-merge"] as const satisfies readonly CiWorkflow[];
+
+/** Whether `workflow` turns the apply on merge back on. */
+export function appliesOnMerge(workflow: CiWorkflow): boolean {
+  return workflow === "trunk-curated+apply-on-merge";
+}
+
+/** The workflow `member` follows: its own `ci.workflow`, else the top level's, else null. */
+export function workflowOf(declaration: Pick<Declaration, "ci">, member: Pick<Member, "ciWorkflow"> | null): CiWorkflow | null {
+  return member?.ciWorkflow ?? declaration.ci?.workflow ?? null;
+}
+
+/** One requirement of the workflows, with the `workspace check` code that reports it missing. */
+export interface CiWorkflowRequirement {
+  /** The reason code WSP151 reports. */
+  code: string;
+  /** What the workflow needs. */
+  requirement: string;
+  /** What adds it. */
+  fix: string;
+  /** Whether it applies per member (true) or once for the workspace. */
+  perMember: boolean;
+}
+
+/**
+ * Every requirement, in the order `workspace check` reports them. The
+ * reference page's table is printed from this list (`ciWorkflowTable`), and a
+ * test compares the two.
+ */
+export const CI_WORKFLOW_REQUIREMENTS = [
+  { code: "ci-workflow-green-undeclared", requirement: "`ci.green` is declared, so commits get a verdict and a release is cut only from a green one", fix: "`chant ci init`, or a hand-written `ci.green` block", perMember: false },
+  { code: "ci-workflow-no-pre-merge", requirement: "`ci.green.preMerge` names at least one phase, the quick checks that run before the branch moves", fix: "`preMerge` in `ci.green`", perMember: false },
+  { code: "ci-workflow-apply-in-green", requirement: "no phase in `ci.green.require` matches an apply job, which would wait on its own verdict", fix: "drop the apply job's pattern from the required phases", perMember: false },
+  { code: "ci-workflow-no-components", requirement: "the member declares a component (`*.component.ts`)", fix: "`chant ci init` writes a stub", perMember: true },
+  { code: "ci-workflow-no-environments", requirement: "the member's `chant.config.ts` declares `environments`, the promotion order", fix: "`environments` in `chant.config.ts`", perMember: true },
+  { code: "ci-workflow-ungated-env", requirement: "each component has a gate, so a promote to the last environment waits on an approval", fix: "a `gate()` step in the component", perMember: true },
+  { code: "ci-workflow-pipeline-missing", requirement: "a pipeline file runs the plan job, the merge job (`ci run record`, or `ci run apply` under apply on merge) and `chant ci tick`", fix: "`chant build --components --generate <forge> --pr-loop` and `chant ci workflow`", perMember: false },
+  { code: "ci-workflow-pipeline-differs", requirement: "the merge job matches the workflow: it records under `trunk-curated` and applies under `trunk-curated+apply-on-merge`", fix: "regenerate the pull-request pipeline, with `--apply-on-merge` only under apply on merge", perMember: false },
+  { code: "ci-workflow-publish-missing", requirement: "a pipeline file runs `chant release publish`", fix: "`chant release workflow`", perMember: false },
+] as const satisfies readonly CiWorkflowRequirement[];
+
+export type CiWorkflowCode = (typeof CI_WORKFLOW_REQUIREMENTS)[number]["code"];
+
+export const CI_WORKFLOW_FINDING_CODES = CI_WORKFLOW_REQUIREMENTS.map((r) => r.code) as readonly CiWorkflowCode[];
+
+/** The requirements table the reference page carries, row for row. */
+export function ciWorkflowTable(): string {
+  const rows = CI_WORKFLOW_REQUIREMENTS.map((r) => `| \`${r.code}\` | ${r.requirement} | ${r.perMember ? "each member" : "the workspace"} | ${r.fix} |`);
+  return ["| Code | Requirement | Checked for | Added by |", "|---|---|---|---|", ...rows].join("\n");
+}

package/src/workspace/declaration.schema.json

@@ -178,6 +178,9 @@
         "green": {
           "$ref": "#/$defs/ciGreen"
         },
+        "workflow": {
+          "$ref": "#/$defs/ciWorkflow"
+        },
         "reportUrl": {
           "type": "string",
           "minLength": 1,
@@ -236,6 +239,14 @@
           "description": "A deploy counts as failed when, within this many days after it, the commit it deployed is revoked or the environment is rolled back from it. The default is 7."
         }
       }
+    },
+    "security": {
+      "type": "array",
+      "uniqueItems": true,
+      "description": "The security groups the workspace opts into (#4168), for every member; a member's own security adds to them. With none, a security feature the workspace has not turned on never refuses, warns or hides anything. verified-releases: release publish and promote --release take only a verified release. supply-chain: a publish without OIDC provenance warns, and a target with no SBOM source is refused. who-ran-it: ci tick needs a runner key. review-rules: pr-apply requires a forge review. isolated-runners: an apply job requires a runner-start statement. workspace check reports what a declared group lacks (WSP161 to WSP165). Added in schema 1 by chant 0.124.33, so a declaration that uses it sets minReader to 0.124.33 or newer.",
+      "items": {
+        "enum": ["verified-releases", "supply-chain", "who-ran-it", "review-rules", "isolated-runners"]
+      }
     }
   },
   "patternProperties": {
@@ -483,10 +494,31 @@
           "minLength": 1,
           "description": "Where an embedded member's files come from. Versions live in the lock."
         },
+        "ci": {
+          "type": "object",
+          "additionalProperties": false,
+          "patternProperties": {
+            "^x-": true
+          },
+          "description": "This member's own CI settings (#4168 step 6). Added in schema 1 by chant 0.124.34, so a declaration that uses it sets minReader to 0.124.34 or newer.",
+          "properties": {
+            "workflow": {
+              "$ref": "#/$defs/ciWorkflow"
+            }
+          }
+        },
         "travel": {
           "type": "boolean",
           "description": "Whether the member goes with an export (#2524 D10, #2552). chant workspace export writes only members that set travel to true into the export member, and refuses to name one that does not. Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer."
         },
+        "security": {
+          "type": "array",
+          "uniqueItems": true,
+          "description": "The security groups this member opts into, added to the declaration's top-level security (#4168). A release, publish or pull-request job of this member runs under both lists. Added in schema 1 by chant 0.124.33, so a declaration that uses it sets minReader to 0.124.33 or newer.",
+          "items": {
+            "enum": ["verified-releases", "supply-chain", "who-ran-it", "review-rules", "isolated-runners"]
+          }
+        },
         "because": {
           "type": "string",
           "minLength": 1,
@@ -1520,6 +1552,14 @@
             "$ref": "#/$defs/ciPhaseName"
           }
         },
+        "preMerge": {
+          "type": "array",
+          "uniqueItems": true,
+          "description": "The phases that must pass before the branch moves (#4168 4.4), by name: the quick checks a pull request's checks, a merge queue, chant ci serve landing a branch, or chant ci run --local give before a change lands. Each must be a declared phase. The trunk-curated workflow needs at least one. Added in schema 1 by chant 0.124.34, so a declaration that uses it sets minReader to 0.124.34 or newer.",
+          "items": {
+            "$ref": "#/$defs/ciPhaseName"
+          }
+        },
         "signedSince": {
           "type": "string",
           "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$",
@@ -1538,6 +1578,10 @@
       },
       "additionalProperties": false
     },
+    "ciWorkflow": {
+      "enum": ["trunk-curated", "trunk-curated+apply-on-merge"],
+      "description": "A prescribed delivery workflow (#4168). trunk-curated: a merge records the plan and deploys nothing; releases are cut from green commits and promoted through each member's environments, gated in the last. trunk-curated+apply-on-merge: the same, with the apply on merge turned back on. chant workspace check reports what a member under one still lacks (WSP151), and chant ci init writes it. At the top level for every member, or on a member, which wins. Added in schema 1 by chant 0.124.34, so a declaration that uses it sets minReader to 0.124.34 or newer."
+    },
     "ciPhaseName": {
       "type": "string",
       "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$"
@@ -1562,6 +1606,13 @@
                 "fail"
               ],
               "description": "What a check run that finished as skipped counts as. fail (the default): it never passes. pass: it passes, for a job a path filter runs only on some commits."
+            },
+            "build": {
+              "enum": [
+                "every",
+                "newest"
+              ],
+              "description": "Added by #4169, read by chant 0.124.33 and newer. Which first-parent commits of the branch the phase runs on. every (the default): each one. newest: only the newest commit when a runner frees. Under either, a run that was cancelled leaves the commit unbuilt rather than red. Under newest, a commit a newer run superseded is unbuilt too, and a red commit starts a bisect over the unbuilt commits back to the last one the phase passed on. chant ci workflow writes the triggers and concurrency of the workflows holding a phase that sets build, and leaves them alone for a phase that does not."
             }
           },
           "patternProperties": {

package/src/workspace/declaration.test.ts

@@ -459,6 +459,23 @@ describe("ci.reportUrl (#4160)", () => {
   });
 });
 
+describe("security (#4168)", () => {
+  test("the groups are read in file order, empty when absent, and securityGroupsOf reads them", async () => {
+    const { securityGroupsOf } = await import("./security");
+    expect(parse(base([])).security).toEqual([]);
+    const decl = parse(base([], { security: ["supply-chain", "verified-releases"] }));
+    expect(decl.security).toEqual(["supply-chain", "verified-releases"]);
+    expect([...securityGroupsOf(decl)]).toEqual(["supply-chain", "verified-releases"]);
+    expect(securityGroupsOf(null).size).toBe(0);
+  });
+
+  test("an unknown group, a repeated group and a non-array are refused", () => {
+    for (const security of [["signed"], ["supply-chain", "supply-chain"], "supply-chain"]) {
+      expect(failure(base([], { security })).code).toBe("declaration-invalid");
+    }
+  });
+});
+
 describe("metrics (#4039)", () => {
   test("failureWindowDays is read as written, without x- keys, and the block is null when absent", () => {
     expect(parse(base([])).metrics).toBeNull();