@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/change-set.schema.json

@@ -0,0 +1,460 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json",
+  "title": "change-set document",
+  "description": "One change set across planners (#3181): what a combined run's chant, terraform, tofu, choudoufu and warden members will change, a summary, and the digest a gate binds. Written by the composeChangeSet Op activity and by composeChangeSet in @intentius/chant/change-set. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version.",
+  "type": "object",
+  "required": [
+    "$schema",
+    "contract",
+    "digest",
+    "members",
+    "entries",
+    "summary"
+  ],
+  "properties": {
+    "$schema": {
+      "const": "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json"
+    },
+    "contract": {
+      "const": 1
+    },
+    "chant": {
+      "type": "string",
+      "description": "The chant that composed the document."
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$",
+      "description": "computePlanDigest(\"change-set\", \u2026) over the members' { member, planDigest } pairs sorted by member, provisional members left out. What a gate over the whole run binds."
+    },
+    "members": {
+      "type": "array",
+      "description": "Sorted by member. Each name appears once.",
+      "items": {
+        "$ref": "#/$defs/member"
+      }
+    },
+    "entries": {
+      "type": "array",
+      "description": "Sorted by member, address, deposed key and action.",
+      "items": {
+        "$ref": "#/$defs/entry"
+      }
+    },
+    "sideEffects": {
+      "type": "array",
+      "description": "Provider-defined actions an apply runs (Terraform actions blocks), sorted by member and address. Absent when none.",
+      "items": {
+        "type": "object",
+        "required": ["member", "address", "type"],
+        "properties": {
+          "member": { "type": "string" },
+          "address": { "type": "string" },
+          "type": { "type": "string" },
+          "trigger": { "type": "string" },
+          "event": { "type": "string" }
+        }
+      }
+    },
+    "summary": {
+      "$ref": "#/$defs/summary"
+    }
+  },
+  "$defs": {
+    "member": {
+      "type": "object",
+      "required": [
+        "member",
+        "lexicon",
+        "planner",
+        "status",
+        "planDigest",
+        "holes"
+      ],
+      "properties": {
+        "member": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The workspace member, or the root a set plan names."
+        },
+        "lexicon": {
+          "type": "string"
+        },
+        "planner": {
+          "enum": [
+            "terraform",
+            "tofu",
+            "choudoufu",
+            "chant",
+            "warden"
+          ]
+        },
+        "scope": {
+          "type": "string",
+          "description": "The estate, environment or org the member plans into."
+        },
+        "status": {
+          "enum": [
+            "planned",
+            "failed"
+          ]
+        },
+        "error": {
+          "type": "string"
+        },
+        "planDigest": {
+          "oneOf": [
+            {
+              "type": "string",
+              "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "What a gate on this member alone binds. null when it failed to plan."
+        },
+        "nativeDigest": {
+          "type": "string",
+          "description": "The planner's own digest of the same plan, such as choudoufu's per-root digest."
+        },
+        "provisional": {
+          "const": true,
+          "description": "Planned before what it reads applied, so it may hold stand-in values (a Terragrunt dependent planned on mock_outputs). Left out of the document's digest, refused by a wave's set digest, and never grouped with real plans."
+        },
+        "holes": {
+          "type": "array",
+          "description": "What the planner could not read, so the plan says nothing about it.",
+          "items": {
+            "type": "object",
+            "required": [
+              "address",
+              "reason"
+            ],
+            "properties": {
+              "address": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "required": [
+        "member",
+        "lexicon",
+        "planner",
+        "address",
+        "type",
+        "action",
+        "attributes"
+      ],
+      "properties": {
+        "member": {
+          "type": "string"
+        },
+        "lexicon": {
+          "type": "string"
+        },
+        "planner": {
+          "enum": [
+            "terraform",
+            "tofu",
+            "choudoufu",
+            "chant",
+            "warden"
+          ]
+        },
+        "address": {
+          "type": "string",
+          "description": "The planner's address, unique within the member with deposed."
+        },
+        "type": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string",
+          "description": "The resource name without module path or index."
+        },
+        "index": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "integer"
+            }
+          ],
+          "description": "A count or for_each index."
+        },
+        "module": {
+          "type": "string"
+        },
+        "deposed": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string",
+          "description": "The provider's id, when the planner reports one."
+        },
+        "importing": {
+          "const": true,
+          "description": "The entry also imports the object into state; action is what else the plan does to it."
+        },
+        "action": {
+          "enum": [
+            "create",
+            "update",
+            "replace",
+            "delete",
+            "read",
+            "no-op",
+            "forget"
+          ]
+        },
+        "disruption": {
+          "enum": [
+            "in-place",
+            "rolling",
+            "replace",
+            "destroy",
+            "unknown"
+          ],
+          "description": "Set on update, replace and delete."
+        },
+        "region": {
+          "type": "string"
+        },
+        "scope": {
+          "type": "string"
+        },
+        "attributes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/attribute"
+          }
+        }
+      }
+    },
+    "attribute": {
+      "type": "object",
+      "required": [
+        "path"
+      ],
+      "properties": {
+        "path": {
+          "type": "string"
+        },
+        "before": {},
+        "after": {},
+        "unknown": {
+          "const": true,
+          "description": "The value is known only after apply."
+        },
+        "sensitive": {
+          "const": true,
+          "description": "Marked sensitive: neither value is carried."
+        },
+        "forcesReplacement": {
+          "const": true
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "members",
+        "entries",
+        "actions",
+        "types",
+        "byMember",
+        "deletes",
+        "replacements",
+        "failed",
+        "holes"
+      ],
+      "properties": {
+        "members": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "entries": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "actions": {
+          "type": "object",
+          "required": [
+            "create",
+            "update",
+            "replace",
+            "delete",
+            "read",
+            "no-op",
+            "forget"
+          ],
+          "properties": {
+            "create": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "update": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "replace": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "delete": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "read": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "no-op": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "forget": {
+              "type": "integer",
+              "minimum": 0
+            }
+          },
+          "additionalProperties": false
+        },
+        "types": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "propertyNames": {
+              "enum": [
+                "create",
+                "update",
+                "replace",
+                "delete",
+                "read",
+                "no-op",
+                "forget"
+              ]
+            },
+            "additionalProperties": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        "byMember": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "propertyNames": {
+              "enum": [
+                "create",
+                "update",
+                "replace",
+                "delete",
+                "read",
+                "no-op",
+                "forget"
+              ]
+            },
+            "additionalProperties": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        "deletes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "member",
+              "address",
+              "type"
+            ],
+            "properties": {
+              "member": {
+                "type": "string"
+              },
+              "address": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              },
+              "deposed": {
+                "type": "string"
+              },
+              "disruption": {
+                "enum": [
+                  "in-place",
+                  "rolling",
+                  "replace",
+                  "destroy",
+                  "unknown"
+                ]
+              }
+            }
+          }
+        },
+        "replacements": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "member",
+              "address",
+              "type"
+            ],
+            "properties": {
+              "member": {
+                "type": "string"
+              },
+              "address": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              },
+              "deposed": {
+                "type": "string"
+              },
+              "disruption": {
+                "enum": [
+                  "in-place",
+                  "rolling",
+                  "replace",
+                  "destroy",
+                  "unknown"
+                ]
+              }
+            }
+          }
+        },
+        "failed": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "holes": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}

package/src/workspace/changes.schema.json

@@ -498,14 +498,9 @@
         "restricted": {
           "type": "array",
           "items": {
-            "enum": [
-              "human",
-              "agent",
-              "runner",
-              "service"
-            ]
+            "$ref": "#/$defs/principalClass"
           },
-          "description": "The principal classes with a writeScope entry, and agent when any agent session is declared."
+          "description": "The principal classes with a writeScope entry, and agent when any agent session is declared: the core classes first, then domain classes in pin order, then any class writeScope names that no pinned package supplies."
         },
         "agents": {
           "type": "array",
@@ -528,6 +523,11 @@
         }
       }
     },
+    "principalClass": {
+      "type": "string",
+      "pattern": "^(?!x-)[a-z][a-z0-9-]{0,39}$",
+      "description": "A principal class: human, agent, runner or service, or a domain class a pinned package supplies at its ./workspace-principals subpath (#3080). A reader that knows only the core classes treats any other name as a domain class."
+    },
     "scopeCommit": {
       "type": "object",
       "required": [
@@ -556,12 +556,7 @@
           "description": "Whether principal is an attested signer."
         },
         "class": {
-          "enum": [
-            "human",
-            "agent",
-            "runner",
-            "service"
-          ],
+          "$ref": "#/$defs/principalClass",
           "description": "agent for a commit naming a session with a Chant-Agent trailer or by a principal a session lists; otherwise the class the principal's role grants at base give."
         },
         "agent": {
@@ -599,6 +594,8 @@
           "enum": [
             "write-scope-member",
             "write-scope-kind",
+            "write-scope-class-unknown",
+            "write-scope-protected",
             "agent-unknown"
           ]
         },
@@ -611,18 +608,13 @@
             "string",
             "null"
           ],
-          "description": "From the workspace root; null for agent-unknown, a finding on the whole commit."
+          "description": "From the workspace root; null for agent-unknown and write-scope-class-unknown, findings on the whole commit."
         },
         "principal": {
           "type": "string"
         },
         "class": {
-          "enum": [
-            "human",
-            "agent",
-            "runner",
-            "service"
-          ]
+          "$ref": "#/$defs/principalClass"
         },
         "agent": {
           "type": [

package/src/workspace/changes.ts

@@ -44,6 +44,7 @@ import { declaredRecordKinds, readDeclaration, readerVersion, WORKSPACE_ERROR_CO
 import { declaredKindFile } from "./declared-kinds";
 import { isGeneratedPath } from "./generated-files";
 import { parseRegion } from "./intent";
+import { loadClassRegistry } from "./principal-classes";
 import { constraintCovers, isWorkspacePath, memberHolding } from "./record-assets";
 import { loadRecordKind, RecordReadError, type LoadedRecordKind, type RecordEntry } from "./records";
 import { readRecordsFor } from "./records-cli";
@@ -529,7 +530,9 @@ async function writeScopeAtBase(query: ChangesQuery, top: string, range: { base:
       format: kind.format,
     });
   }
-  return checkWriteScope({ top, base: range.base, head: range.head, prefix, declaration, kinds });
+  // The principal classes the pins supply, a path pin read at the base too (#3080).
+  const classes = loadClassRegistry(declaration.pins, located.rootOnDisk, { tree: located.tree }).registry;
+  return checkWriteScope({ top, base: range.base, head: range.head, prefix, declaration, kinds, classes });
 }
 
 function finding(code: ChangesFindingCode, p: ChangedPath, severity: "warn" | "fail", message: string, records: string[]): ChangeFinding {

package/src/workspace/chant-migrations.e2e.test.ts

@@ -105,14 +105,15 @@ function ledger(): GateLedgerPort & { approve(digest: string): void } {
 const passing: ChantRunner = async () => ({ exitCode: 0, output: "" });
 
 /** Stage, approve and apply the upgrade, and commit it. */
-async function upgrade(): Promise<void> {
+async function upgrade(runChant: ChantRunner = passing): Promise<NonNullable<Awaited<ReturnType<typeof upgradeCommand>>["staged"]>> {
   const l = ledger();
-  const first = await upgradeCommand({ root: proj, to: target(), runChant: passing, ledger: l, now: "2026-09-25T00:00:00Z" });
+  const first = await upgradeCommand({ root: proj, to: target(), runChant, ledger: l, now: "2026-09-25T00:00:00Z" });
   expect(first.outcome).toBe("gated");
   l.approve(first.staged!.digest);
-  const second = await upgradeCommand({ root: proj, to: target(), runChant: passing, ledger: l, now: "2026-09-25T00:00:00Z" });
+  const second = await upgradeCommand({ root: proj, to: target(), runChant, ledger: l, now: "2026-09-25T00:00:00Z" });
   expect(second.outcome).toBe("applied");
   commit("chud-lexicon-exit");
+  return second.staged!;
 }
 
 async function makeProject(from: "dir" | "git"): Promise<void> {
@@ -763,10 +764,21 @@ describe("the migrated delivery project, with this checkout's chant", () => {
   });
 
   test("builds, lints, rebuilds its CI, stops at the ship gate, ships each approved plan to Fly and records it once, and rolls back to the previous release", { timeout: 1_800_000 }, async () => {
-    await upgrade();
     const delivery = join(proj, "delivery");
-    symlinkSync(join(repoRoot, "node_modules"), join(delivery, "node_modules"));
     writeFileSync(join(proj, ".git/info/exclude"), "node_modules\n");
+    symlinkSync(join(repoRoot, "node_modules"), join(delivery, "node_modules"));
+    // The template's ci.yml was built by the chant of 84c8b21 (actions/checkout@v4). The upgrade rebuilds it with
+    // this chant (#3244), so its ci:check passes without anyone running ci:build: build and lint stay stubbed,
+    // and the workflow rebuild runs this checkout's chant.
+    expect(read(proj, ".github/workflows/ci.yml")).toContain("actions/checkout@v4");
+    const rebuilding: ChantRunner = async (command, cwd, args) => {
+      if (!args?.length) return passing(command, cwd);
+      const r = await chant(cwd, {}, command, ...args);
+      return { exitCode: r.status ?? 1, output: r.out };
+    };
+    const staged = await upgrade(rebuilding);
+    expect(staged.workflows).toEqual([expect.objectContaining({ member: "delivery", script: "ci:build", path: ".github/workflows/ci.yml", status: "rebuilt" })]);
+    expect(read(proj, ".github/workflows/ci.yml")).not.toContain("actions/checkout@v4");
     const fly = await flaps(join(root, "fly"));
     const env = { FLY_FLAPS_BASE_URL: fly.endpoint, FLY_API_TOKEN: "test", CHUD_FLY_APP_SECRET: "s3cret", GITHUB_ACTOR: "releaser" };
     /** The Machine's app over HTTP, on the host port its service is published on. */

package/src/workspace/checks/boxes.test.ts

@@ -158,6 +158,11 @@ describe("the box block in the declaration", () => {
       isolation: null,
       intent: null,
       services: [],
+      factory: null,
+      listing: null,
+      publisher: null,
+      ship: null,
+      replicate: null,
       capabilities: [
         { name: "fountain", broker: "lobby", scope: ["agent", "vault"], pointer: "/members/0/box/capabilities/0" },
         { name: "inference", broker: null, scope: [], pointer: "/members/0/box/capabilities/1" },