@intentius/chant 0.124.31 → 0.124.33

package/src/workspace/declaration.schema.json

@@ -177,6 +177,11 @@
       "properties": {
         "green": {
           "$ref": "#/$defs/ciGreen"
+        },
+        "reportUrl": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where the pull-request jobs copy their reports and events, and where chant ci run keeps the run index, <reportUrl>/runs/index.json (#4160): an s3://<bucket>/<prefix> or file://<directory> URL, as --report-url takes. chant build --pr-loop, chant ci run, chant ci serve and chant ci runs use it when --report-url is not given, and the flag wins. Readers find it in chant workspace ls --json as ci.reportUrl. Added in schema 1 by chant 0.124.32, so a declaration that uses it sets minReader to 0.124.32 or newer."
         }
       }
     },
@@ -231,6 +236,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": {
@@ -482,6 +495,14 @@
           "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,
@@ -581,7 +602,7 @@
     },
     "box": {
       "type": "object",
-      "description": "The member is a box, or holds a box's declarations (#2726). A box holds no credential: each capability it needs outside itself is reached through a broker, a runtime such as a lobby or a door, which holds the credential and enforces the scope. chant workspace check fails when a file in the member's directory carries a literal secret (WSP121) and when a capability names no broker (WSP122). chant workspace status --json lists the capabilities, so a broker can read the scopes. Its host, slot, ports, state and cookies state the box's isolation (#2727): chant derives each value from the box's identity, its host, the member's name and its slot, and prints them in chant workspace status --json, so a runtime reads them instead of choosing its own. chant workspace check fails when two boxes on a host resolve to the same value (WSP123) and when a box hard-codes a machine path (WSP124). A member that builds the fountain lexicon's Box declares the callback token fountain gives its persistent sandbox as the capability fountain-callback, brokered by fountain, with scope owner, or chant workspace check fails (WSP125, #2780). Its intent names the decision record that says what the box is for (#2850): chant workspace status --json reports the record's state and answer, and chant workspace check fails when no decision record has the id (WSP126) and warns when the record constrains no member or path of this workspace (WSP127, #2857). Its services list what the box runs under its supervisor (#2880), which the fly lexicon observes, restarts and applies through sprite-env, and which chant workspace status --json prints. Its factory declares what the box builds, how a build is checked, which member declares the builder agents and where a finished build is published (#3146, ws-077), its listing what the box shows of itself (#3146), and its replicate where the box's work in progress is pushed so a lost box loses none of it (#3172, ws-085). Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
+      "description": "The member is a box, or holds a box's declarations (#2726). A box holds no credential: each capability it needs outside itself is reached through a broker, a runtime such as a lobby or a door, which holds the credential and enforces the scope. chant workspace check fails when a file in the member's directory carries a literal secret (WSP121) and when a capability names no broker (WSP122). chant workspace status --json lists the capabilities, so a broker can read the scopes. Its host, slot, ports, state and cookies state the box's isolation (#2727): chant derives each value from the box's identity, its host, the member's name and its slot, and prints them in chant workspace status --json, so a runtime reads them instead of choosing its own. chant workspace check fails when two boxes on a host resolve to the same value (WSP123) and when a box hard-codes a machine path (WSP124). A member that builds the fountain lexicon's Box declares the callback token fountain gives its sandbox as the capability fountain-callback, brokered by fountain, with scope owner, or chant workspace check fails (WSP125, #2780). Its intent names the decision record that says what the box is for (#2850): chant workspace status --json reports the record's state and answer, and chant workspace check fails when no decision record has the id (WSP126) and warns when the record constrains no member or path of this workspace (WSP127, #2857). Its services list what the box runs under its supervisor (#2880), which the fly lexicon observes, restarts and applies through sprite-env, and which chant workspace status --json prints. Its factory declares what the box builds, how a build is checked, which member declares the builder agents and where a finished build is published (#3146, ws-077), its listing what the box shows of itself (#3146), and its replicate where the box's work in progress is pushed so a lost box loses none of it (#3172, ws-085). Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
       "properties": {
         "intent": {
           "type": "string",
@@ -1518,7 +1539,7 @@
         "signedSince": {
           "type": "string",
           "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$",
-          "description": "Added by #4031, read by chant 0.124.28 and newer. The full sha of the first commit on branch whose ci/green and ci/revoked tags must carry a DSSE statement in their annotation, signed by a key .chant/trust.json at base lists under runners for a principal holding the runner role. A tag on a strict first-parent ancestor of this commit counts unsigned, so existing tags keep working; a tag on any other commit, this one included, needs a statement. Position in history decides, never a date, which whoever makes a commit or a tag sets. A reader refuses a sha that names no commit in its clone with declaration-invalid. Absent, no tag needs a statement."
+          "description": "Added by #4031, read by chant 0.124.28 and newer. The full sha of the first commit on branch whose ci/green and ci/revoked tags must carry a DSSE statement in their annotation, signed by a key .chant/trust.json at base lists under runners for a principal holding the runner role. A tag on a strict first-parent ancestor of this commit counts unsigned, so existing tags keep working; a tag on any other commit, this one included, needs a statement. Position in history decides, never a date, which whoever makes a commit or a tag sets. A reader refuses a sha that names no commit in its clone with declaration-invalid. Absent, no tag needs a statement. Since chant 0.124.32 (#4156) it covers Op run records the same way, when ci.green.source is runs: an unsigned run counts on a strict first-parent ancestor of this commit and needs a statement on any other, ci serve refuses to start without a runner key trusted at the target's head, and ci run and chant run warn about a run they leave unsigned. Absent, an unsigned run counts and nothing asks for a key."
         },
         "source": {
           "enum": [
@@ -1557,6 +1578,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

@@ -436,6 +436,46 @@ describe("retention (#4036)", () => {
   });
 });
 
+describe("ci.reportUrl (#4160)", () => {
+  test("an s3:// or file:// URL is read without its trailing slash, beside green or alone, and is null when absent", () => {
+    expect(parse(base([])).ci).toBeNull();
+    expect(parse(base([], { ci: {} })).ci).toEqual({ green: null, reportUrl: null });
+    expect(parse(base([], { ci: { reportUrl: "s3://acme-reports/prod/" } })).ci).toEqual({ green: null, reportUrl: "s3://acme-reports/prod" });
+    const green = { branch: "main", phases: { build: ["build"] }, require: ["build"] };
+    const d = parse(base([], { ci: { green, reportUrl: "file:///srv/chant-reports" } }));
+    expect(d.ci?.reportUrl).toBe("file:///srv/chant-reports");
+    expect(d.ci?.green?.branch).toBe("main");
+  });
+
+  test("a URL no job can upload to is declaration-invalid, at ci.reportUrl, with the reason --report-url gives", () => {
+    for (const reportUrl of ["https://reports.example/acme", "ftp://example/x", "reports/"]) {
+      const err = failure(base([], { ci: { reportUrl } }));
+      expect(err.code).toBe("declaration-invalid");
+      expect(err.message).toBe(`ci.reportUrl ${reportUrl}: takes an s3://<bucket>/<prefix> or file://<directory> URL`);
+      expect(err.location?.line).toBeGreaterThan(1);
+    }
+    expect(failure(base([], { ci: { reportUrl: "" } })).code).toBe("declaration-invalid");
+    expect(failure(base([], { ci: { reportUrl: 7 } })).code).toBe("declaration-invalid");
+  });
+});
+
+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();

package/src/workspace/declaration.ts

@@ -17,11 +17,13 @@
  */
 
 import { RETENTION_KINDS, type RetentionOverride } from "../lifecycle/retention-policy";
+import { parseReportUrl } from "../pr-report-url";
 import schema from "./declaration.schema.json" with { type: "json" };
 import { expandGlob } from "./glob";
 import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
 import type { ReasonCode } from "./reason-codes";
+import type { SecurityGroup } from "./security";
 import { joinPath, type WorkspaceTree } from "./tree";
 import { loadAjv2020 } from "./ajv2020";
 import { readChantPackageVersion } from "../package-version";
@@ -183,6 +185,13 @@ export interface AgentDeclaration {
 /** What a check run that finished as skipped counts as in a CI phase (#3573). */
 export type CiSkipped = "pass" | "fail";
 
+/**
+ * Which commits a phase runs on (#4169): `every` first-parent commit of the
+ * branch, or only the `newest` one when a runner frees, the commits between
+ * left unbuilt and a red one bisected.
+ */
+export type CiBuild = "every" | "newest";
+
 /** One phase of `ci.green`: the check runs that make it up (#3573, ws-103). */
 export interface CiPhase {
   name: string;
@@ -190,6 +199,12 @@ export interface CiPhase {
   runs: string[];
   /** `fail` (the default): a skipped run never passes. `pass`: it passes, for a job a path filter runs only on some commits. */
   skipped: CiSkipped;
+  /**
+   * Which commits the phase runs on (#4169), when the declaration says.
+   * Absent means `every`, and `ci workflow` then leaves the phase's
+   * workflows as they are.
+   */
+  build?: CiBuild;
   pointer: string;
 }
 
@@ -232,6 +247,14 @@ export type CiSource = "checks" | "runs";
 /** The declaration's `ci` block (#3573). */
 export interface CiDeclaration {
   green: CiGreen | null;
+  /**
+   * `ci.reportUrl` (#4160): where the pull-request jobs copy their reports
+   * and `chant ci run` keeps the run index, `<reportUrl>/runs/index.json`.
+   * An `s3://` or `file://` URL, as `--report-url` takes, without a trailing
+   * slash. The commands that take `--report-url` default to it. Null when
+   * the declaration sets none.
+   */
+  reportUrl: string | null;
 }
 
 export interface MemberRole {
@@ -548,6 +571,8 @@ export interface Member {
   because: string | null;
   /** Whether `chant workspace export` takes the member (#2552, D10). False when the entry does not say. */
   travel: boolean;
+  /** The security groups this member adds to the declaration's top-level `security` (#4168 step 7), in file order; empty when it names none. */
+  security: SecurityGroup[];
   suppress: Suppression[];
   /** The entry's JSON Pointer in the file, for messages. */
   pointer: string;
@@ -615,6 +640,8 @@ export interface Declaration {
    * then uses 7.
    */
   metrics: { failureWindowDays?: number } | null;
+  /** The security groups the workspace opts into (#4168 section 8, ./security.ts), in file order; empty when the declaration has no `security` key. */
+  security: SecurityGroup[];
   /** The file, relative to the workspace root's tree (`chant.workspace.json` or `.jsonc`). */
   file: string;
 }
@@ -841,6 +868,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       upstream: (e.upstream as string | undefined) ?? null,
       because: (e.because as string | undefined) ?? null,
       travel: e.travel === true,
+      security: [...((e.security as SecurityGroup[] | undefined) ?? [])],
       suppress,
       pointer,
     };
@@ -993,6 +1021,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     ci,
     retention: retentionOf(obj.retention),
     metrics: metricsOf(obj.metrics),
+    security: [...((obj.security as SecurityGroup[] | undefined) ?? [])],
     file,
   };
   written.set(declaration, raw);
@@ -1087,13 +1116,21 @@ function retentionOf(raw: unknown): RetentionOverride | null {
 
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
-  const block = raw as { green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped }>; require: string[]; signedSince?: string; source?: CiSource } };
-  if (block.green === undefined) return { green: null };
+  const block = raw as { reportUrl?: string; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; signedSince?: string; source?: CiSource } };
+  let reportUrl: string | null = null;
+  if (block.reportUrl !== undefined) {
+    // #4160: refused here as pr-plan and ci run refuse the flag, so a reader never gets a URL no job can write to.
+    const target = parseReportUrl(block.reportUrl, "ci.reportUrl");
+    if ("error" in target) throw new WorkspaceReadError("declaration-invalid", target.error, at("/ci/reportUrl"));
+    reportUrl = target.url;
+  }
+  if (block.green === undefined) return { green: null, reportUrl };
   const g = block.green;
   const phases: CiPhase[] = Object.entries(g.phases).map(([name, p]) => ({
     name,
     runs: [...(Array.isArray(p) ? p : p.runs)],
     skipped: Array.isArray(p) ? "fail" : (p.skipped ?? "fail"),
+    ...(!Array.isArray(p) && p.build !== undefined ? { build: p.build } : {}),
     pointer: `/ci/green/phases/${pointerToken(name)}`,
   }));
   for (const [i, name] of g.require.entries()) {
@@ -1104,7 +1141,7 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
       at(`/ci/green/require/${i}`),
     );
   }
-  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" } };
+  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, reportUrl };
 }
 
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {

package/src/workspace/export.ts

@@ -44,6 +44,7 @@ import { parseJsonText } from "./jsonc";
 import { fileHash, LOCK_FILE, LockError, parseLock, renderLock, type Lineage, type LineageLock } from "./lineage-lock";
 import { loadRecordKind } from "./records";
 import { workingTree } from "./tree";
+import { isWorkDir } from "../lifecycle/work-dir";
 
 /** The role that marks the member an export is written into. */
 export const EXPORT_ROLE = "export";
@@ -142,7 +143,7 @@ export function gitTopOf(dir: string): string | undefined {
 /**
  * The files under `dir` (absolute) that git tracks or would track, relative
  * to `dir`, that exist in the working tree. Outside git, every file, leaving
- * out `.git` and `node_modules`.
+ * out `.git`, `node_modules` and `.chant/work`.
  */
 export function listFiles(dir: string): string[] {
   if (!existsSync(dir)) return [];
@@ -167,8 +168,10 @@ export function listFiles(dir: string): string[] {
     for (const d of readdirSync(join(dir, rel), { withFileTypes: true })) {
       if (d.name === ".git" || d.name === "node_modules") continue;
       const p = rel ? `${rel}/${d.name}` : d.name;
-      if (d.isDirectory()) walk(p);
-      else if (d.isFile()) out.push(p);
+      // `.chant/work` holds work worktrees, each a copy of the checkout (#2893).
+      if (d.isDirectory()) {
+        if (!isWorkDir(p)) walk(p);
+      } else if (d.isFile()) out.push(p);
     }
   };
   walk("");

package/src/workspace/ls.schema.json

@@ -21,7 +21,8 @@
             "properties": {
               "name": { "type": "string" },
               "runs": { "type": "array", "items": { "type": "string" }, "description": "Check-run name patterns, * standing for any run of characters." },
-              "skipped": { "enum": ["pass", "fail"], "description": "What a run that finished as skipped counts as." }
+              "skipped": { "enum": ["pass", "fail"], "description": "What a run that finished as skipped counts as." },
+              "build": { "enum": ["every", "newest"], "description": "Added in contract 1 by #4169, written by chant 0.124.33 and newer, and only when the declaration sets it: whether the phase runs on every first-parent commit or only the newest one when a runner frees. Absent means every." }
             }
           }
         },
@@ -103,7 +104,13 @@
             {
               "type": "object",
               "required": ["green"],
-              "properties": { "green": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/ciGreen" }] } }
+              "properties": {
+                "green": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/ciGreen" }] },
+                "reportUrl": {
+                  "type": "string",
+                  "description": "Added in contract 1 by chant 0.124.32 (#4160). The declaration's ci.reportUrl, an s3:// or file:// URL without a trailing slash, present only when it is set. The run index is at <reportUrl>/runs/index.json (ci-run-index), and each job's report under <reportUrl>/<pr>/<commit>[/<member>]/."
+                }
+              }
             }
           ]
         },

package/src/workspace/ls.ts

@@ -142,7 +142,8 @@ export interface LsDiagram {
 export interface LsCiGreen {
   branch: string;
   window: string;
-  phases: { name: string; runs: string[]; skipped: "pass" | "fail" }[];
+  /** `build` is present only when the declaration sets it (#4169). */
+  phases: { name: string; runs: string[]; skipped: "pass" | "fail"; build?: "every" | "newest" }[];
   require: string[];
   /** The first commit whose ci tags need a signed statement (#4031). Present only when the declaration sets it. */
   signedSince?: string;
@@ -186,8 +187,12 @@ export type LsDocument =
       groups: LsGroup[];
       /** Every declared diagram, the workspace's own first, then each member's, in file order (#2764). */
       diagrams: LsDiagram[];
-      /** What the workspace's CI decides about its commits (#3573), or null with no `ci` block. */
-      ci: { green: LsCiGreen | null } | null;
+      /**
+       * What the workspace's CI decides about its commits (#3573), or null
+       * with no `ci` block. `reportUrl` (#4160) is the declared report URL,
+       * where the run index is kept, present only when it is set.
+       */
+      ci: { green: LsCiGreen | null; reportUrl?: string } | null;
       summary: { members: number; unreadable: number; groups: number; matches: number };
     }
   | {
@@ -324,12 +329,13 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
               ? {
                   branch: declaration.ci.green.branch,
                   window: declaration.ci.green.window,
-                  phases: declaration.ci.green.phases.map((p) => ({ name: p.name, runs: p.runs, skipped: p.skipped })),
+                  phases: declaration.ci.green.phases.map((p) => ({ name: p.name, runs: p.runs, skipped: p.skipped, ...(p.build ? { build: p.build } : {}) })),
                   require: declaration.ci.green.require,
                   ...(declaration.ci.green.signedSince !== null ? { signedSince: declaration.ci.green.signedSince } : {}),
                   ...(declaration.ci.green.source === "runs" ? { source: "runs" as const } : {}),
                 }
               : null,
+            ...(declaration.ci.reportUrl !== null ? { reportUrl: declaration.ci.reportUrl } : {}),
           }
         : null,
       summary: {

package/src/workspace/member-pipeline.ts

@@ -212,7 +212,7 @@ export interface ComponentPlanInput {
   params?: string[];
   paramsFile?: string;
   /** `--pr-loop`, with its `--gate` and `--branch` (#3465). */
-  prLoop?: { gate?: string; branch?: string };
+  prLoop?: { gate?: string; branch?: string; applyOnMerge?: boolean };
   /** `--wave-gate` with its `--canary` and `--base` (#3049). */
   waveGate?: { gate: string; canary?: string[]; base?: string };
   /** `--image` (#4002). */
@@ -258,6 +258,7 @@ export function planMemberComponentPipeline(input: ComponentPlanInput): MemberCo
     parts.push("--pr-loop");
     if (input.prLoop.gate) parts.push("--gate", input.prLoop.gate);
     if (input.prLoop.branch) parts.push("--branch", input.prLoop.branch);
+    if (input.prLoop.applyOnMerge) parts.push("--apply-on-merge");
   }
   if (input.image) parts.push("--image", input.image);
   for (const line of input.beforeScript ?? []) parts.push("--before-script", line);

package/src/workspace/merge-record.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/merge-record/v1/merge-record.schema.json",
+  "title": "chant merge record",
+  "description": "What landed on the target branch, keyed by commit: _merges/<commit>.json on chant/lifecycle (#4168, chant 0.124.33 and newer). The record job writes it on merge. It applies nothing; a release that carries the commit deploys it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "contract", "commit", "base", "env", "source", "op", "gate", "digest", "plan", "approvedBy", "components", "recordedAt"],
+  "properties": {
+    "$schema": { "const": "https://intentius.io/chant/schemas/workspace/merge-record/v1/merge-record.schema.json" },
+    "contract": { "const": 1 },
+    "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The merged commit." },
+    "base": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The commit the change is measured from." },
+    "env": { "type": "string", "minLength": 1 },
+    "member": { "type": "string", "minLength": 1, "description": "The workspace member whose pipeline wrote it." },
+    "source": {
+      "description": "Where the change came from: the pull request that merged it, else the work items its Chant-Record: work:<id> trailers name, else a direct push.",
+      "oneOf": [
+        { "type": "object", "additionalProperties": false, "required": ["kind", "pr"], "properties": { "kind": { "const": "pull-request" }, "pr": { "type": "integer", "minimum": 1 } } },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "records"],
+          "properties": {
+            "kind": { "const": "work-item" },
+            "records": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "object", "additionalProperties": false, "required": ["kind", "id"], "properties": { "kind": { "const": "work" }, "id": { "type": "string", "minLength": 1 } } }
+            }
+          }
+        },
+        { "type": "object", "additionalProperties": false, "required": ["kind"], "properties": { "kind": { "const": "direct-push" } } }
+      ]
+    },
+    "op": { "type": ["string", "null"], "description": "The pull request's gate op, pr-<n> or pr-<n>-<member>; null without a pull request." },
+    "gate": { "type": "string", "minLength": 1 },
+    "digest": { "type": ["string", "null"], "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "The change-set digest planned on the merged commit; null when nothing was planned. The change set is stored under _change-sets/." },
+    "plan": {
+      "enum": ["approved", "changed", "unapproved", "nothing", "plan-failed"],
+      "description": "approved: an approval stands for digest. changed: one stands for approvedDigest, so the plan moved after review; the record job's chant/record status fails. unapproved: none stands. nothing: no component deploys what the change touches. plan-failed: a member failed to plan."
+    },
+    "approvedDigest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$" },
+    "approvedBy": { "type": "array", "items": { "type": "string" } },
+    "authorApproved": { "type": "array", "items": { "type": "string" }, "description": "Approvers who wrote the change (#4000), read with a forge." },
+    "components": { "type": "array", "items": { "type": "string" } },
+    "recordedAt": { "type": "string", "minLength": 1, "description": "ISO 8601." }
+  }
+}

package/src/workspace/pin-integrity.test.ts

@@ -51,6 +51,11 @@ describe("integrityOf", () => {
     expect(integrityOf(join(dir({ "d/a": "1", "d/b": "2", "d/e": "" }), "d")).integrity).not.toBe(base);
   });
 
+  test("a work worktree under .chant/work is left out, and the rest of .chant is hashed (#2893)", () => {
+    const root = dir({ "d/a": "1", "d/.chant/work/W-1/a": "copy", "d/.chant/work/m/W-2/a": "copy", "d/.chant/notes": "n" });
+    expect(pinnedFiles(join(root, "d"))).toEqual([".chant/notes", "a"]);
+  });
+
   test("node_modules and .git are left out, and a symbolic link is refused", () => {
     const root = dir({ "d/a": "1", "d/node_modules/x/index.js": "x", "d/.git/HEAD": "ref" });
     expect(pinnedFiles(join(root, "d"))).toEqual(["a"]);

package/src/workspace/pin-integrity.ts

@@ -28,6 +28,7 @@
 import { createHash } from "node:crypto";
 import { lstatSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { isWorkDir } from "../lifecycle/work-dir";
 
 export type IntegrityAlgorithm = "sha256" | "sha384" | "sha512";
 
@@ -39,7 +40,7 @@ export function parseIntegrity(value: string): { algorithm: IntegrityAlgorithm;
   return m ? { algorithm: m[1] as IntegrityAlgorithm, digest: m[2] } : undefined;
 }
 
-/** Directories a plugin hash never looks inside. */
+/** Directories a plugin hash never looks inside, with `.chant/work`, where work worktrees are (#2893). */
 const SKIPPED_DIRS = new Set(["node_modules", ".git"]);
 
 /** Thrown when a path can't be hashed: it is missing, or holds a symbolic link. */
@@ -50,7 +51,7 @@ function walk(dir: string, prefix: string, out: string[]): void {
     const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
     if (entry.isSymbolicLink()) throw new PinHashError(`${rel} is a symbolic link, which a pinned plugin may not contain`);
     if (entry.isDirectory()) {
-      if (!SKIPPED_DIRS.has(entry.name)) walk(join(dir, entry.name), rel, out);
+      if (!SKIPPED_DIRS.has(entry.name) && !isWorkDir(rel)) walk(join(dir, entry.name), rel, out);
     } else if (entry.isFile()) {
       out.push(rel);
     }

package/src/workspace/pr-report.schema.json

@@ -8,7 +8,7 @@
   "properties": {
     "$schema": { "const": "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json" },
     "contract": { "const": 1 },
-    "stage": { "enum": ["plan", "apply"] },
+    "stage": { "enum": ["plan", "apply", "record"], "description": "plan: on the pull request. record (#4168, chant 0.124.33 and newer): on merge, the default; it plans the merged commit and writes the merge record, applying nothing. apply: on merge with --apply-on-merge." },
     "pr": {
       "type": ["integer", "null"],
       "minimum": 1,
@@ -33,12 +33,12 @@
       "description": "The change-set digest of what this stage planned: computePlanDigest(\"change-set\", ...) over every member's { member, planDigest }. What the gate binds."
     },
     "status": {
-      "enum": ["planned", "plan-failed", "nothing", "applied", "failed", "refused"],
-      "description": "planned: every member planned (plan stage). plan-failed: a member failed to plan, so nothing can apply. nothing: no component deploys what the change touches. applied: every member applied. failed: a member failed to apply and its dependents did not run. refused: nothing applied, see refusal."
+      "enum": ["planned", "recorded", "plan-failed", "nothing", "applied", "failed", "wave-applied", "refused", "waiting"],
+      "description": "planned: every member planned (plan stage). recorded (#4168, chant 0.124.33 and newer): every member planned on the merged commit and the merge record was written (record stage); approval says whether the plan is the approved one, and nothing applied. plan-failed: a member failed to plan, so nothing can apply. nothing: no component deploys what the change touches. applied: every member applied. failed: a member failed to apply and its dependents did not run. wave-applied (#4003, chant 0.124.32 and newer): with --wave-gate and --wave, the wave applied and a later wave is still to run. refused: nothing applied, see refusal. waiting (#3999): the approved plans applied except members held back after an upstream applied, which wait on an approval of the plan the last of rounds made."
     },
     "refusal": {
-      "enum": ["not-approved", "plan-changed", "not-a-reviewer", "no-pull-request"],
-      "description": "Why an apply refused. plan-changed: an approval stands for another digest, so the plan changed after review."
+      "enum": ["not-approved", "plan-changed", "not-a-reviewer", "author-approved", "no-pull-request", "wave-not-approved", "wave-plan-changed", "earlier-wave"],
+      "description": "Why an apply refused. plan-changed: an approval stands for another digest, so the plan changed after review. author-approved (#4000): under --require-review, an approval names the pull request's author or an author or committer of one of its commits. With --wave-gate (#4003, chant 0.124.32 and newer): wave-not-approved, a wave's new plan is not covered by the approved one and no approval of its gate stands for it; wave-plan-changed, an approval of its gate stands for another digest; earlier-wave, an earlier wave has work left or no record says it applied. The waves that applied before a wave refused stay applied; waves says which."
     },
     "message": { "type": "string", "description": "The refusal or failure as printed." },
     "resumed": {
@@ -54,6 +54,61 @@
       "description": "Added within contract version 1 by #4104, written by chant 0.124.30 and newer. Per dependency a member was planned against, the names of the outputs read from the deployed estate through its capability's outputs, sorted. A dependency outside the change is listed here too, and one whose stack is not deployed yet lists []. Outputs given with --seed-outputs, or carried from an earlier attempt's record, are not listed. Absent when no dependency was read, and on a resumed apply.",
       "additionalProperties": { "type": "array", "items": { "type": "string" } }
     },
+    "waveGate": {
+      "type": "string",
+      "description": "Added within contract version 1 by #4003, written by chant 0.124.32 and newer. pr-apply --wave-gate <name>: the apply runs a wave at a time, each planned after the one before it applied, and wave k waits on <name>-wave-<k> under op when its plan moved. Absent without it."
+    },
+    "waves": {
+      "type": "array",
+      "description": "With waveGate: each wave reached so far, in order, with the approval it applied or waits under.",
+      "items": {
+        "type": "object",
+        "required": ["wave", "components", "status", "approval", "gate", "digest"],
+        "properties": {
+          "wave": { "type": "integer", "minimum": 1, "description": "1-based, from selection.waves." },
+          "components": { "type": "array", "items": { "type": "string" }, "description": "The components planned in it on the run that reached it." },
+          "status": { "enum": ["applied", "failed", "plan-failed", "waiting"] },
+          "approval": { "enum": ["pull-request", "wave"], "description": "pull-request: the approved change set covers the wave's plan, and it applies under the pull request's approval (gate and digest are the report's). wave: its plan moved, and it needs an approval of its own gate for its new plan." },
+          "gate": { "type": "string", "description": "The gate it applied or waits under: the report's gate, or <waveGate>-wave-<k>." },
+          "digest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "The digest that gate binds: the report's digest, or the change-set digest of the wave's new plan." },
+          "approvedBy": { "type": "array", "items": { "type": "string" } },
+          "approved": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Waiting: an approval of the wave's gate stands for this other digest." },
+          "moved": { "type": "array", "items": { "type": "string" }, "description": "Why the approved change set does not cover the wave's plan, one line per member." }
+        }
+      }
+    },
+    "plannedOutputs": {
+      "type": "object",
+      "description": "Added within contract version 1 by #3999, written by chant 0.124.32 and newer. Per dependency in the change that a member was planned against, the names of the outputs its plan knows, sorted. An output a member reads that is not listed is known only after apply, and the member lists it under unknownInputs. Absent when no member read one.",
+      "additionalProperties": { "type": "array", "items": { "type": "string" } }
+    },
+    "rounds": {
+      "type": "array",
+      "description": "Added within contract version 1 by #3999. Apply stage: the rounds planned after an upstream applied, in order. A member whose plan read an upstream output that applied as another value, or was known only after apply, is held back and planned again against the outputs the apply left; each round has its own gate and digest. Absent when nothing was held.",
+      "items": {
+        "type": "object",
+        "required": ["round", "gate", "digest", "components", "approval", "status", "changeSet"],
+        "properties": {
+          "round": { "type": "integer", "minimum": 2 },
+          "gate": { "type": "string", "description": "The gate the round waits on: <gate>-round-<round>." },
+          "digest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "The change-set digest of what the round planned. What its gate binds." },
+          "components": { "type": "array", "items": { "type": "string" }, "description": "The components planned again, in apply order." },
+          "approval": {
+            "type": "object",
+            "required": ["status"],
+            "description": "Where the approval stands for digest, as the top-level approval.",
+            "properties": {
+              "status": { "enum": ["approved", "changed", "pending"] },
+              "approvedBy": { "type": "array", "items": { "type": "string" } },
+              "approved": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$" }
+            }
+          },
+          "status": { "enum": ["applied", "failed", "waiting", "plan-failed"] },
+          "message": { "type": "string", "description": "With waiting: why an approval that stands does not count under --require-review." },
+          "changeSet": { "type": "object", "description": "The change-set document the round planned. Its digest equals digest." }
+        }
+      }
+    },
     "approval": {
       "type": "object",
       "required": ["status"],
@@ -85,7 +140,7 @@
           "member": { "type": "string", "description": "The member's name in the change set: the root, for a terraform-family step." },
           "component": { "type": "string" },
           "planDigest": { "type": ["string", "null"], "description": "What a gate on this member alone binds. null when it failed to plan." },
-          "status": { "enum": ["planned", "plan-failed", "applied", "failed", "blocked"] },
+          "status": { "enum": ["planned", "plan-failed", "applied", "failed", "blocked", "waiting"], "description": "waiting (#3999): held back because its plan read an upstream output that applied as another value, or was known only after apply; it waits on an approval of its plan in rounds." },
           "counts": {
             "type": "object",
             "required": ["create", "update", "replace", "delete"],
@@ -100,8 +155,20 @@
           "inputsMoved": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "Apply stage: components this one depends on whose outputs changed when they applied. It applied the plan it was approved with; the next run plans it against the new values."
-          }
+            "description": "Apply stage: components this one depends on whose outputs changed when they applied. It applied the plan it was approved with; the next run plans it against the new values. Not written by chant 0.124.32 and newer, which holds such a member back instead (held, round)."
+          },
+          "unknownInputs": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "#3999: the upstream outputs its plan read that the change's plans could not say, as <component>.<output>, sorted. Known only after that upstream applies; the approval does not cover what this member does with them."
+          },
+          "buildInputs": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "#3999: the published artifact identities its plan read from a build in the same change, as <component>.publish.<field>, sorted. Known only after the build runs and never approved again: the build's provenance binds them, so the member applies without a later round."
+          },
+          "round": { "type": "integer", "minimum": 2, "description": "Apply stage (#3999): the round whose plan it applied or waits on, when not the first. planDigest and counts are that round's." },
+          "held": { "type": "string", "description": "Apply stage (#3999): why the first round's plan did not apply." }
         }
       }
     },

package/src/workspace/reason-codes.test.ts

@@ -28,6 +28,7 @@ import { STATUS_ERROR_CODES, STATUS_GATE_REASON_CODES, STATUS_REASON_CODES, STAT
 import { WORK_WARNING_CODES } from "./work";
 import { BOX_FINDING_CODES } from "./checks/boxes";
 import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
+import { SECURITY_FINDING_CODES } from "./checks/security";
 import { WORK_ERROR_CODES, WORK_HISTORY_ERROR_CODES, WORK_LEASE_REFUSALS } from "./work-cli";
 import { RUN_STATEMENT_ERROR_CODES, RUNS_ERROR_CODES, RUNS_REASON_CODES, RUNS_WRITE_ERROR_CODES } from "./runs-cli";
 import { RUN_STATEMENT_FAILURE_CODES } from "./trust/run-statement";
@@ -66,6 +67,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   CHECK_ERROR_CODES,
   BOX_FINDING_CODES,
   DIAGRAM_FINDING_CODES,
+  SECURITY_FINDING_CODES,
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
   STATUS_GATE_REASON_CODES,