@intentius/chant 0.124.31 → 0.124.32

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

@@ -103,7 +103,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

@@ -186,8 +186,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 };
     }
   | {
@@ -330,6 +334,7 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
                   ...(declaration.ci.green.source === "runs" ? { source: "runs" as const } : {}),
                 }
               : null,
+            ...(declaration.ci.reportUrl !== null ? { reportUrl: declaration.ci.reportUrl } : {}),
           }
         : null,
       summary: {

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

@@ -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", "plan-failed", "nothing", "applied", "failed", "wave-applied", "refused", "waiting"],
+      "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. 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.ts

@@ -232,8 +232,8 @@ export const REASONS = {
   // A box that holds a credential (check, #2726). Each is also a WSP finding.
   "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",
   "box-capability-unbrokered": "A capability in a member's box block names no broker, so the box would hold its credential.",
-  // The credential fountain itself hands a persistent box (check, #2780). Also a WSP finding.
-  "box-fountain-callback-undeclared": "A box member builds a fountain Box, whose persistent sandbox fountain gives a callback token scoped to its owner, and the member's box block does not declare the fountain-callback capability brokered by fountain with scope owner.",
+  // The credential fountain itself hands a box (check, #2780). Also a WSP finding.
+  "box-fountain-callback-undeclared": "A box member builds a fountain Box, whose sandbox fountain gives a callback token scoped to its owner, and the member's box block does not declare the fountain-callback capability brokered by fountain with scope owner.",
   // A box's intent, the decision record its box block names (check, #2850). Each is also a WSP finding.
   "box-intent-unknown": "A box block names an intent, and no record of a declared kind named decision has that id.",
   "box-intent-unconstrained": "The decision record a box names as its intent constrains no member or path of this workspace: no member: entry for a declared member and no path: entry at, above or inside one's directory.",

package/src/workspace/run-event.schema.json

@@ -54,7 +54,9 @@
           "description": "github: a GitHub Actions run, also the spelling Forgejo Actions uses. gitlab: a CI pipeline. op: a steward's run, named by its Op run id. local: a run on the machine that started it, outside CI. chant: a pull-request job the chant runner ran (chant ci run, #4094), named by its Op run id; added within contract version 1 and written by chant 0.124.30 and newer, so a reader that switches on forge keeps a case for a value it does not know."
         },
         "repo": { "type": "string", "description": "The repository or project slug on the forge, when the environment named one." },
-        "url": { "type": "string", "description": "A link to the run, when the environment gave enough to build one." }
+        "url": { "type": "string", "description": "A link to the run, when the environment gave enough to build one." },
+        "jobId": { "type": "string", "description": "The forge's id for the job within the run: GITHUB_JOB on GitHub and Forgejo, CI_JOB_ID on GitLab. Added within contract 1 by #4156 and written by chant 0.124.32 and newer, only by chant ci run in a forge job." },
+        "attempt": { "type": "integer", "minimum": 1, "description": "The run's attempt, GITHUB_RUN_ATTEMPT on GitHub and Forgejo. Added within contract 1 by #4156 and written by chant 0.124.32 and newer, only by chant ci run in a forge job." }
       }
     },
     "settleStatus": {

package/src/workspace/status.schema.json

@@ -451,7 +451,9 @@
                         "properties": {
                           "forge": { "enum": ["github", "gitlab", "op", "local", "chant"], "description": "chant: a pull-request job the chant runner ran (chant ci run, #4094), added within contract 1 and written by chant 0.124.30 and newer." },
                           "repo": { "type": "string" },
-                          "url": { "type": "string" }
+                          "url": { "type": "string" },
+                          "jobId": { "type": "string", "description": "The forge's job id within the run. Added within contract 1 by #4156 and written by chant 0.124.32 and newer, only by chant ci run in a forge job." },
+                          "attempt": { "type": "integer", "minimum": 1, "description": "The run's attempt on GitHub and Forgejo. Added within contract 1 by #4156 and written by chant 0.124.32 and newer, only by chant ci run in a forge job." }
                         }
                       },
                       "failure": {

package/src/workspace/write-scope.test.ts

@@ -28,7 +28,7 @@ import { parseDeclaration, WorkspaceReadError } from "./declaration";
 import { parseFrontMatter } from "./records";
 import { amendRecord, newRecord, renderRecord, reviewRecord } from "./records-write";
 import { emptyPolicy } from "./trust/policy";
-import { judgePath, judgeRecord, onlyKeysChanged, principalClass, resolveWriter, WriteScopeError } from "./write-scope";
+import { FACTORY_CHECK_LOG, judgePath, judgeRecord, onlyKeysChanged, principalClass, resolveWriter, WriteScopeError } from "./write-scope";
 import { createWorkspaceTools } from "../cli/mcp/workspace-tools";
 
 const DECISIONS = join(REPO, "docs", "design", "decisions");
@@ -226,6 +226,34 @@ describe("judging a write", () => {
     expect(judgeRecord(d, factory, screen, "amend")).toMatchObject({ ok: false, code: "write-scope-kind" });
   });
 
+  test("the factory Op's own check log is in no member and is not judged by member scope (#3512)", () => {
+    const d = parseDeclaration(declaration(SCOPE, [...AGENTS, { name: "factory", members: ["app", "design"] }]), "chant.workspace.json");
+    const factory = resolveWriter(d, policy, { agent: "factory" });
+    expect(judgePath(d, factory, ".chant/factory/W-007/check.log")).toEqual({ ok: true });
+    const app = resolveWriter(d, policy, { agent: "app-agent" });
+    expect(judgePath(d, app, ".chant/factory/W-007/check.log")).toEqual({ ok: true });
+    // Only that file: the rest of .chant/ stays outside an agent's members.
+    expect(judgePath(d, factory, ".chant/factory/W-007/notes.md")).toMatchObject({ ok: false, code: "write-scope-member" });
+    expect(judgePath(d, factory, ".chant/factory/check.log")).toMatchObject({ ok: false, code: "write-scope-member" });
+    expect(judgePath(d, factory, ".chant/factory/W-007/sub/check.log")).toMatchObject({ ok: false, code: "write-scope-member" });
+  });
+
+  test("a protected entry still covers the factory check log (#3512)", () => {
+    const d = parseDeclaration(
+      declaration({ agent: { protected: [".chant/**"] } }, [{ name: "factory", members: ["app", "design"] }]),
+      "chant.workspace.json",
+    );
+    const factory = resolveWriter(d, policy, { agent: "factory" });
+    expect(judgePath(d, factory, ".chant/factory/W-007/check.log")).toMatchObject({ ok: false, code: "write-scope-protected" });
+  });
+
+  test("the pattern matches the path factoryCheck writes", async () => {
+    const { readFileSync } = await import("node:fs");
+    const src = readFileSync(new URL("../op/activities/factory.ts", import.meta.url), "utf-8");
+    expect(src).toContain("const log = `.chant/factory/${lease.item}/check.log`;");
+    expect(FACTORY_CHECK_LOG.test(".chant/factory/W-007/check.log")).toBe(true);
+  });
+
   test("the declared name of a kind is a key for its records rule too", () => {
     const d = parseDeclaration(declaration({ agent: { records: { screen: ["new"] } } }), "chant.workspace.json");
     const design = resolveWriter(d, policy, { agent: "design-agent" });

package/src/workspace/write-scope.ts

@@ -308,6 +308,16 @@ export interface PathChange {
   after(): string | null;
 }
 
+/**
+ * The factory Op's check log, `.chant/factory/<item>/check.log` (#3512). The
+ * Check step writes it in the worktree (`../op/activities/factory.ts`,
+ * `factoryCheck`), attaches it as each criterion's evidence, and Record
+ * commits it with the build under the builder's Chant-Agent. It is chant's own
+ * output and in no member, so an agent's member scope would flag every build
+ * commit. The member check passes over it; a protected entry still covers it.
+ */
+export const FACTORY_CHECK_LOG = /^\.chant\/factory\/[^/]+\/check\.log$/;
+
 /**
  * Whether `writer` may write the file at `path`, from the workspace root:
  * the path is in a member the writer may write, and no protected entry of
@@ -319,7 +329,8 @@ export function judgePath(declaration: Declaration | null, writer: Writer, path:
   const scope = scopeOf(declaration, writer);
   if (scope === null) return OK;
   const member = memberHolding(path, declaration?.members ?? []);
-  if (!memberAllowed(writer, scope, member)) {
+  const chantOutput = member === null && FACTORY_CHECK_LOG.test(path);
+  if (!chantOutput && !memberAllowed(writer, scope, member)) {
     const where = member === null ? "is in no member" : `is in member ${member}`;
     return {
       ok: false,