@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/decision-points.schema.json

@@ -1,144 +1,144 @@
 {
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://intentius.io/chant/schemas/workspace/decision-points/v1/decision-points.schema.json",
-    "title": "Decision points",
-    "description": "A workspace's decision points (ws-058, #2738): the recurring questions it asks of its own graph, declared as data in a JSON file that an answer record kind names in `answers.points`. Each point is a typed question (`noul`, `choice` with 2 to 255 options, or `score` with 2 to 10 ordered levels, the question types of the POST /v1/systemone wire format, #2491), the inputs it reads, each named as a read-contract output, and an ordered chain of deciders: `table` rows, `model` deciders with a backend, a pinned model id and a threshold, and a `quorum` of people, always last. What JSON Schema cannot say is checked in code (`points.ts`): an input's output is one the read contract has, a table row tests declared inputs and answers a candidate, a field belongs to its decider's kind, a model id is pinned rather than an alias, and the chain ends in its one quorum. A point declared `adhoc` (#3403) leaves out its question's criteria: the question's text and candidates come with each ask (`points ask --candidates`), and its chain is one quorum. Unknown fields are refused, except fields whose names start with x-.",
-    "type": "object",
-    "required": ["points"],
-    "properties": {
-        "$schema": { "type": "string" },
-        "points": {
-            "type": "object",
-            "minProperties": 1,
-            "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
-            "additionalProperties": { "$ref": "#/$defs/point" }
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/decision-points/v1/decision-points.schema.json",
+  "title": "Decision points",
+  "description": "A workspace's decision points (ws-058, #2738): the recurring questions it asks of its own graph, declared as data in a JSON file that an answer record kind names in `answers.points`. Each point is a typed question (`noul`, `choice` with 2 to 255 options, or `score` with 2 to 10 ordered levels, the question types of the POST /v1/systemone wire format, #2491), the inputs it reads, each named as a read-contract output, and an ordered chain of deciders: `table` rows, `model` deciders with a backend, a pinned model id and a threshold, and a `quorum` of people, always last. What JSON Schema cannot say is checked in code (`points.ts`): an input's output is one the read contract has, a table row tests declared inputs and answers a candidate, a field belongs to its decider's kind, a model id is pinned rather than an alias, and the chain ends in its one quorum. A point declared `adhoc` (#3403) leaves out its question's criteria: the question's text and candidates come with each ask (`points ask --candidates`), and its chain is one quorum. Unknown fields are refused, except fields whose names start with x-.",
+  "type": "object",
+  "required": ["points"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "points": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": { "$ref": "#/$defs/point" }
+    }
+  },
+  "patternProperties": { "^x-": true },
+  "additionalProperties": false,
+  "$defs": {
+    "text": { "type": "string", "minLength": 1 },
+    "point": {
+      "type": "object",
+      "required": ["title", "question", "inputs", "deciders"],
+      "properties": {
+        "title": { "$ref": "#/$defs/text" },
+        "adhoc": {
+          "type": "boolean",
+          "description": "An ad-hoc point (#3403): the question declares its type and what the asks are for, and no criteria. Each ask gives the question's text and its candidates, and the answer record keeps them, so people's answer is checked against them. Its chain is one quorum."
+        },
+        "question": { "$ref": "#/$defs/question" },
+        "inputs": {
+          "type": "object",
+          "description": "The state the deciders see, input name to description. A name is a read-contract output (record, decision, work-item, finding, region, commit, node, member, gate, release, environment, component, ask), optionally followed by dotted field names, such as work-item.fits_small: a field of that output, or a value the caller derives from it. The caller supplies the values; a table row can only test these names.",
+          "minProperties": 1,
+          "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_-]*(\\.[A-Za-z_][A-Za-z0-9_]*)*$" },
+          "additionalProperties": { "type": "string" }
+        },
+        "deciders": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/decider" }
         }
+      },
+      "patternProperties": { "^x-": true },
+      "additionalProperties": false,
+      "if": { "properties": { "adhoc": { "const": true } }, "required": ["adhoc"] },
+      "then": { "properties": { "question": { "not": { "required": ["criteria"] } } } },
+      "else": { "properties": { "question": { "required": ["criteria"] } } }
     },
-    "patternProperties": { "^x-": true },
-    "additionalProperties": false,
-    "$defs": {
-        "text": { "type": "string", "minLength": 1 },
-        "point": {
-            "type": "object",
-            "required": ["title", "question", "inputs", "deciders"],
-            "properties": {
-                "title": { "$ref": "#/$defs/text" },
-                "adhoc": {
-                    "type": "boolean",
-                    "description": "An ad-hoc point (#3403): the question declares its type and what the asks are for, and no criteria. Each ask gives the question's text and its candidates, and the answer record keeps them, so people's answer is checked against them. Its chain is one quorum."
-                },
-                "question": { "$ref": "#/$defs/question" },
-                "inputs": {
-                    "type": "object",
-                    "description": "The state the deciders see, input name to description. A name is a read-contract output (record, decision, work-item, finding, region, commit, node, member, gate, release, environment, component, ask), optionally followed by dotted field names, such as work-item.fits_small: a field of that output, or a value the caller derives from it. The caller supplies the values; a table row can only test these names.",
-                    "minProperties": 1,
-                    "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_-]*(\\.[A-Za-z_][A-Za-z0-9_]*)*$" },
-                    "additionalProperties": { "type": "string" }
-                },
-                "deciders": {
-                    "type": "array",
-                    "minItems": 1,
-                    "items": { "$ref": "#/$defs/decider" }
-                }
-            },
-            "patternProperties": { "^x-": true },
-            "additionalProperties": false,
-            "if": { "properties": { "adhoc": { "const": true } }, "required": ["adhoc"] },
-            "then": { "properties": { "question": { "not": { "required": ["criteria"] } } } },
-            "else": { "properties": { "question": { "required": ["criteria"] } } }
-        },
-        "question": {
-            "type": "object",
-            "required": ["type", "instructions"],
+    "question": {
+      "type": "object",
+      "required": ["type", "instructions"],
+      "properties": {
+        "type": { "enum": ["noul", "choice", "score"] },
+        "instructions": { "$ref": "#/$defs/text" },
+        "criteria": {
+          "description": "The candidates. noul: {true, false} descriptions. choice: option to description, 2 to 255 options. score: 2 to 10 ordered levels.",
+          "type": ["object", "array"]
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "noul" } } },
+          "then": {
             "properties": {
-                "type": { "enum": ["noul", "choice", "score"] },
-                "instructions": { "$ref": "#/$defs/text" },
-                "criteria": {
-                    "description": "The candidates. noul: {true, false} descriptions. choice: option to description, 2 to 255 options. score: 2 to 10 ordered levels.",
-                    "type": ["object", "array"]
-                }
-            },
-            "additionalProperties": false,
-            "allOf": [
-                {
-                    "if": { "properties": { "type": { "const": "noul" } } },
-                    "then": {
-                        "properties": {
-                            "criteria": {
-                                "type": "object",
-                                "required": ["true", "false"],
-                                "properties": { "true": { "type": "string" }, "false": { "type": "string" } },
-                                "additionalProperties": false
-                            }
-                        }
-                    }
-                },
-                {
-                    "if": { "properties": { "type": { "const": "choice" } } },
-                    "then": { "properties": { "criteria": { "type": "object", "minProperties": 2, "maxProperties": 255, "additionalProperties": { "type": "string" } } } }
-                },
-                {
-                    "if": { "properties": { "type": { "const": "score" } } },
-                    "then": { "properties": { "criteria": { "type": "array", "minItems": 2, "maxItems": 10, "uniqueItems": true, "items": { "$ref": "#/$defs/text" } } } }
-                }
-            ]
-        },
-        "scalar": { "type": ["string", "number", "boolean", "null"] },
-        "condition": {
-            "description": "A value the input must equal, or one comparison.",
-            "oneOf": [
-                { "$ref": "#/$defs/scalar" },
-                {
-                    "type": "object",
-                    "minProperties": 1,
-                    "maxProperties": 1,
-                    "properties": {
-                        "eq": { "$ref": "#/$defs/scalar" },
-                        "ne": { "$ref": "#/$defs/scalar" },
-                        "lt": { "type": "number" },
-                        "lte": { "type": "number" },
-                        "gt": { "type": "number" },
-                        "gte": { "type": "number" },
-                        "in": { "type": "array", "items": { "$ref": "#/$defs/scalar" } }
-                    },
-                    "additionalProperties": false
-                }
-            ]
+              "criteria": {
+                "type": "object",
+                "required": ["true", "false"],
+                "properties": { "true": { "type": "string" }, "false": { "type": "string" } },
+                "additionalProperties": false
+              }
+            }
+          }
         },
-        "row": {
-            "type": "object",
-            "required": ["when", "answer"],
-            "properties": {
-                "when": {
-                    "type": "object",
-                    "description": "Every named input must meet its condition. An empty object matches every state.",
-                    "additionalProperties": { "$ref": "#/$defs/condition" }
-                },
-                "answer": { "type": ["string", "boolean"] },
-                "note": { "type": "string" }
-            },
-            "additionalProperties": false
+        {
+          "if": { "properties": { "type": { "const": "choice" } } },
+          "then": { "properties": { "criteria": { "type": "object", "minProperties": 2, "maxProperties": 255, "additionalProperties": { "type": "string" } } } }
         },
-        "decider": {
-            "type": "object",
-            "required": ["kind"],
-            "properties": {
-                "kind": { "enum": ["table", "model", "quorum"] },
-                "rows": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/row" } },
-                "backend": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "model: which backend answers, such as systemone (any server with the POST /v1/systemone wire format). chant never calls it: the decide Op activity or a runtime's decider does." },
-                "model": { "type": "string", "minLength": 1, "description": "model: the pinned model id the backend is asked for, such as jev-1.13.0. An alias such as jev-latest is refused." },
-                "threshold": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "description": "model: the least confidence that makes the answer a proposal. Below it the answer is not observed and the next decider is asked." },
-                "unreachable": { "enum": ["escalate", "fail"], "description": "model: what happens when the backend can't be reached or gives no usable answer: escalate to the next decider (the default), or fail the ask and write nothing." },
-                "count": { "type": "integer", "minimum": 1, "description": "quorum: how many distinct people must answer." },
-                "roles": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/text" }, "description": "quorum: the trust policy roles whose holders count." },
-                "note": { "type": "string" }
-            },
-            "additionalProperties": false,
-            "allOf": [
-                { "if": { "properties": { "kind": { "const": "table" } } }, "then": { "required": ["rows"] } },
-                { "if": { "properties": { "kind": { "const": "model" } } }, "then": { "required": ["backend", "model", "threshold"] } },
-                { "if": { "properties": { "kind": { "const": "quorum" } } }, "then": { "required": ["count"] } }
-            ]
+        {
+          "if": { "properties": { "type": { "const": "score" } } },
+          "then": { "properties": { "criteria": { "type": "array", "minItems": 2, "maxItems": 10, "uniqueItems": true, "items": { "$ref": "#/$defs/text" } } } }
+        }
+      ]
+    },
+    "scalar": { "type": ["string", "number", "boolean", "null"] },
+    "condition": {
+      "description": "A value the input must equal, or one comparison.",
+      "oneOf": [
+        { "$ref": "#/$defs/scalar" },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 1,
+          "properties": {
+            "eq": { "$ref": "#/$defs/scalar" },
+            "ne": { "$ref": "#/$defs/scalar" },
+            "lt": { "type": "number" },
+            "lte": { "type": "number" },
+            "gt": { "type": "number" },
+            "gte": { "type": "number" },
+            "in": { "type": "array", "items": { "$ref": "#/$defs/scalar" } }
+          },
+          "additionalProperties": false
         }
+      ]
+    },
+    "row": {
+      "type": "object",
+      "required": ["when", "answer"],
+      "properties": {
+        "when": {
+          "type": "object",
+          "description": "Every named input must meet its condition. An empty object matches every state.",
+          "additionalProperties": { "$ref": "#/$defs/condition" }
+        },
+        "answer": { "type": ["string", "boolean"] },
+        "note": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "decider": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": { "enum": ["table", "model", "quorum"] },
+        "rows": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/row" } },
+        "backend": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "model: which backend answers, such as systemone (any server with the POST /v1/systemone wire format). chant never calls it: the decide Op activity or a runtime's decider does." },
+        "model": { "type": "string", "minLength": 1, "description": "model: the pinned model id the backend is asked for, such as jev-1.13.0. An alias such as jev-latest is refused." },
+        "threshold": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "description": "model: the least confidence that makes the answer a proposal. Below it the answer is not observed and the next decider is asked." },
+        "unreachable": { "enum": ["escalate", "fail"], "description": "model: what happens when the backend can't be reached or gives no usable answer: escalate to the next decider (the default), or fail the ask and write nothing." },
+        "count": { "type": "integer", "minimum": 1, "description": "quorum: how many distinct people must answer." },
+        "roles": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/text" }, "description": "quorum: the trust policy roles whose holders count." },
+        "note": { "type": "string" }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        { "if": { "properties": { "kind": { "const": "table" } } }, "then": { "required": ["rows"] } },
+        { "if": { "properties": { "kind": { "const": "model" } } }, "then": { "required": ["backend", "model", "threshold"] } },
+        { "if": { "properties": { "kind": { "const": "quorum" } } }, "then": { "required": ["count"] } }
+      ]
     }
+  }
 }

package/dist/workspace/declaration-write-cli.js

@@ -0,0 +1,74 @@
+/**
+ * `chant workspace member add <name> --from <file|->`, `chant workspace
+ * member remove <name>` and `chant workspace host set <name> --from
+ * <file|->` (#3596): the command lines of `declaration-write.ts`.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { readerVersion } from "./declaration.js";
+import { DECLARATION_WRITE_CONTRACT_VERSION, DECLARATION_WRITE_SCHEMA_ID, declarationWrite, } from "./declaration-write.js";
+import { AGENT_ENV } from "./write-scope.js";
+const USAGE = {
+    "member add": "chant workspace member add <name> --from <file|-> [--by <principal>] [--dry-run] [--json]",
+    "member remove": "chant workspace member remove <name> [--by <principal>] [--dry-run] [--json]",
+    "host set": "chant workspace host set <name> --from <file|-> [--by <principal>] [--dry-run] [--json]",
+};
+const print = (doc) => {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc ? 1 : 0;
+};
+/** `chant workspace member add|remove <name>`. */
+export function runWorkspaceMember(ctx) {
+    const [, verb, ...rest] = ctx.args.positionals ?? [];
+    const action = verb === "add" ? "member add" : verb === "remove" ? "member remove" : null;
+    if (action === null)
+        return usage("member add", rest[0], `chant workspace member takes add <name> or remove <name>${verb === undefined ? "" : `, not ${verb}`}`);
+    return run(ctx, action, rest);
+}
+/** `chant workspace host set <name>`. */
+export function runWorkspaceHost(ctx) {
+    const [, verb, ...rest] = ctx.args.positionals ?? [];
+    if (verb !== "set")
+        return usage("host set", rest[0], `chant workspace host takes set <name>${verb === undefined ? "" : `, not ${verb}`}`);
+    return run(ctx, "host set", rest);
+}
+function usage(action, name, message) {
+    return print({
+        $schema: DECLARATION_WRITE_SCHEMA_ID,
+        contract: DECLARATION_WRITE_CONTRACT_VERSION,
+        chant: readerVersion(),
+        action,
+        name: name ?? null,
+        error: { code: "write-usage-invalid", message: `${message}; ${USAGE[action]}` },
+    });
+}
+function run(ctx, action, rest) {
+    const { args } = ctx;
+    const cwd = process.cwd();
+    const [name, ...extra] = rest;
+    if (name === undefined)
+        return usage(action, undefined, `${action} needs a name`);
+    if (extra.length > 0)
+        return usage(action, name, `${action} takes one name, and was also given ${extra.join(" ")}`);
+    for (const [flag, v] of [["--set", args.set], ["--kind", args.kind], ["--at", args.at], ["--cover", args.cover]]) {
+        if (v !== undefined)
+            return usage(action, name, `${action} takes no ${flag}`);
+    }
+    let entry;
+    if (args.migrateFrom !== undefined) {
+        try {
+            entry = readFileSync(args.migrateFrom === "-" ? 0 : resolve(cwd, args.migrateFrom), "utf-8");
+        }
+        catch (err) {
+            return print({
+                $schema: DECLARATION_WRITE_SCHEMA_ID,
+                contract: DECLARATION_WRITE_CONTRACT_VERSION,
+                chant: readerVersion(),
+                action,
+                name,
+                error: { code: "write-input-invalid", message: `--from ${args.migrateFrom} could not be read: ${err instanceof Error ? err.message : String(err)}` },
+            });
+        }
+    }
+    return print(declarationWrite({ cwd, action, name, entry, by: args.by, agent: process.env[AGENT_ENV] || undefined, dryRun: args.dryRun === true }));
+}

package/dist/workspace/declaration-write.js

@@ -0,0 +1,238 @@
+/**
+ * `chant workspace member add|remove` and `chant workspace host set` (#3596):
+ * a declaration's members and hosts, written through chant.
+ *
+ * ws-074 lets a tool write the repo only through chant. A local lobby keeps
+ * one member per box it runs, each with a box block whose isolation chant
+ * resolves, and the host those boxes run on; before these writes it edited
+ * `chant.workspace.json` itself to plant, retire and start a box. Each write
+ * changes one entry of `members` or `hosts` in place, so the file keeps its
+ * formatting, key order and, in a `.jsonc` file, its comments, as `box
+ * listing set` does (#3308).
+ *
+ * A write is refused, and nothing written, when the declaration it would
+ * write does not read (`write-input-invalid`, with the read's own message),
+ * when it adds a collision between two boxes on one host or a literal
+ * machine path (`box-isolation-collision`, `box-isolation-literal`, the codes
+ * `chant workspace check` reports as WSP123 and WSP124), and when the write
+ * scope at base keeps the writer off the declaration (`judgePath`, with the
+ * change, so a protected entry's `except` can allow `members` or `hosts`).
+ * Each holds the working tree's write lock (#3173, ws-089), prints one JSON
+ * document (`member-write.schema.json`) and never commits.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { boxCollisions, boxLiterals } from "./box-isolation.js";
+import { parseDeclaration, readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError } from "./declaration.js";
+import { IDENTITY_CODES, IdentityError, refuseUnidentified } from "./identity.js";
+import { appendElement, removeElement, setElement, setProperty, valueAt } from "./json-edit.js";
+import { parseJsonText } from "./jsonc.js";
+import { locateWorkspace } from "./which-chant.js";
+import { judgePath, resolveWriter, scopeSource, unknownClassVerdict, WriteScopeError } from "./write-scope.js";
+import { withWriteLockSync, WriteLockError, WRITE_LOCK_CODES } from "./write-lock.js";
+/** The version of the document these writes print. */
+export const DECLARATION_WRITE_CONTRACT_VERSION = 1;
+/** `$id` of the JSON Schema for what the member and host writes print, shipped beside this file. */
+export const DECLARATION_WRITE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/member-write/v1/member-write.schema.json";
+/** The writes. */
+export const DECLARATION_WRITE_ACTIONS = ["member add", "member remove", "host set"];
+/** Why a member or host write wrote nothing. Closed. */
+export const DECLARATION_WRITE_ERROR_CODES = [
+    ...WORKSPACE_ERROR_CODES,
+    "write-usage-invalid",
+    "write-input-invalid",
+    "member-exists",
+    "member-unknown",
+    "box-isolation-collision",
+    "box-isolation-literal",
+    "write-scope-member",
+    "write-scope-protected",
+    "write-scope-class-unknown",
+    "agent-unknown",
+    ...IDENTITY_CODES,
+    ...WRITE_LOCK_CODES,
+];
+class DeclarationWriteError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const toPosix = (p) => (sep === "/" ? p : p.split(sep).join("/"));
+const sha256 = (b) => createHash("sha256").update(b).digest("hex");
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** The entry given with --from: a JSON object whose name, if it has one, is the one the command names. The name goes first. */
+function readEntry(text, req) {
+    const what = req.action === "host set" ? "host" : "member";
+    if (text === undefined || text.trim() === "")
+        throw new DeclarationWriteError("write-usage-invalid", `${req.action} needs the ${what}'s entry: --from <file|->`);
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (err) {
+        throw new DeclarationWriteError("write-input-invalid", `the ${what} entry is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!isObject(value))
+        throw new DeclarationWriteError("write-input-invalid", `the ${what} entry is a JSON object, as the declaration's ${what}s hold it`);
+    if ("name" in value && value.name !== req.name) {
+        throw new DeclarationWriteError("write-input-invalid", `the ${what} entry is named ${JSON.stringify(value.name)}, and the command names ${req.name}; leave name out or make them the same`);
+    }
+    const { name: _name, ...rest } = value;
+    return { name: req.name, ...rest };
+}
+/** Write `text` to `file` through a sibling temporary file, so a reader never sees half of it. */
+function writeAtomically(file, text) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.chant-${process.pid}.tmp`;
+    writeFileSync(tmp, text);
+    renameSync(tmp, file);
+}
+const collisionKeys = (d) => new Map(boxCollisions(d).map((c) => [`${c.host} ${c.what} ${c.value} ${c.holders.map((h) => `${h.box}.${h.name}`).join(",")}`, c]));
+/** Run the write and build the document it prints. Never throws for a refusal. */
+export function declarationWrite(req) {
+    const head = { $schema: DECLARATION_WRITE_SCHEMA_ID, contract: DECLARATION_WRITE_CONTRACT_VERSION, chant: readerVersion(), action: req.action, name: req.name || null };
+    try {
+        return withWriteLockSync(req.cwd, { verb: req.action, by: req.by ?? null, agent: req.agent || null }, req.dryRun, () => write(req, head));
+    }
+    catch (err) {
+        const fail = (code, message) => ({ ...head, error: { code, message } });
+        if (err instanceof DeclarationWriteError)
+            return fail(err.code, err.message);
+        if (err instanceof WriteScopeError)
+            return fail(err.code, err.message);
+        if (err instanceof IdentityError)
+            return fail(err.code, err.message);
+        if (err instanceof WriteLockError)
+            return fail(err.code, err.message);
+        if (err instanceof WorkspaceReadError)
+            return fail(err.code, err.describe());
+        throw err;
+    }
+}
+function write(req, head) {
+    if (!req.name)
+        throw new DeclarationWriteError("write-usage-invalid", `${req.action} needs the name of the ${req.action === "host set" ? "host" : "member"}`);
+    if (req.action === "member remove" && req.entry !== undefined)
+        throw new DeclarationWriteError("write-usage-invalid", "member remove takes no --from: it removes the member's whole entry");
+    const given = req.action === "member remove" ? null : readEntry(req.entry, req);
+    const located = locateWorkspace(req.cwd);
+    const declaration = readDeclaration(located.tree);
+    const repoBase = located.top ?? located.rootOnDisk;
+    const declPath = toPosix(relative(repoBase, join(located.rootOnDisk, declaration.file)));
+    const declFile = join(located.rootOnDisk, declaration.file);
+    const before = readFileSync(declFile, "utf-8");
+    const jsonc = declaration.file.endsWith(".jsonc");
+    const parsed = parseJsonText(before, { jsonc });
+    if (!parsed.ok)
+        throw new WorkspaceReadError("declaration-unparseable", parsed.message);
+    const expected = structuredClone(parsed.value);
+    // The edit, made twice: in place in the text, and on the parsed value it must read back as.
+    let after = before;
+    let previous = null;
+    if (req.action === "host set") {
+        const hosts = valueAt(parsed.value, "/hosts");
+        const index = Array.isArray(hosts) ? hosts.findIndex((h) => isObject(h) && h.name === req.name) : -1;
+        if (index >= 0) {
+            previous = hosts[index];
+            if (!isDeepStrictEqual(previous, given)) {
+                after = setElement(after, jsonc, "/hosts", index, given);
+                expected.hosts[index] = given;
+            }
+        }
+        else if (Array.isArray(hosts)) {
+            after = appendElement(after, jsonc, "/hosts", given);
+            expected.hosts.push(given);
+        }
+        else {
+            after = setProperty(after, jsonc, "", "hosts", [given]);
+            expected.hosts = [given];
+        }
+    }
+    else {
+        const entries = valueAt(parsed.value, "/members");
+        const list = Array.isArray(entries) ? entries : [];
+        const index = list.findIndex((e) => isObject(e) && e.name === req.name);
+        if (req.action === "member add") {
+            if (index >= 0) {
+                previous = list[index];
+                if (!isDeepStrictEqual(previous, given)) {
+                    throw new DeclarationWriteError("member-exists", `the declaration already has an entry named ${req.name} (/members/${index}); member add writes a new member, so remove that one first or give its entry as it is`);
+                }
+            }
+            else if (Array.isArray(entries)) {
+                after = appendElement(after, jsonc, "/members", given);
+                expected.members.push(given);
+            }
+            else {
+                after = setProperty(after, jsonc, "", "members", [given]);
+                expected.members = [given];
+            }
+        }
+        else {
+            const member = declaration.members.find((m) => m.name === req.name);
+            if (!member || index < 0) {
+                const isGroup = declaration.groups.some((g) => g.name === req.name);
+                throw new DeclarationWriteError("member-unknown", isGroup
+                    ? `${req.name} is an example group, not a member; member remove removes members`
+                    : `no member is named ${req.name}; the declaration's members are ${declaration.members.map((m) => m.name).join(", ") || "none"}`);
+            }
+            previous = list[index];
+            after = removeElement(after, jsonc, "/members", index);
+            expected.members.splice(index, 1);
+        }
+    }
+    const reread = parseJsonText(after, { jsonc });
+    if (!reread.ok || !isDeepStrictEqual(reread.value, expected)) {
+        // An edit that does not read back as the value meant is never written.
+        throw new Error(`${req.action}: editing ${declaration.file} in place did not give the declaration intended; nothing was written`);
+    }
+    // The declaration it would write reads, and adds no collision or literal path.
+    let next;
+    try {
+        next = parseDeclaration(after, declaration.file);
+    }
+    catch (err) {
+        if (err instanceof WorkspaceReadError)
+            throw new DeclarationWriteError("write-input-invalid", `the ${req.action} would make the declaration invalid: ${err.describe()}`);
+        throw err;
+    }
+    const had = collisionKeys(declaration);
+    const added = [...collisionKeys(next)].filter(([k]) => !had.has(k)).map(([, c]) => c);
+    if (added.length > 0) {
+        const c = added[0];
+        throw new DeclarationWriteError("box-isolation-collision", `the ${req.action} would give ${c.holders.map((h) => `${h.box}.${h.name}`).join(" and ")} the same ${c.what} ${c.value} on host ${c.host}; give the box a slot no other box holds`);
+    }
+    const literalsBefore = new Set(boxLiterals(declaration).map((l) => l.message));
+    const literal = boxLiterals(next).find((l) => !literalsBefore.has(l.message));
+    if (literal)
+        throw new DeclarationWriteError("box-isolation-literal", `the ${req.action} would add a literal machine path: ${literal.message}`);
+    // The write scope at base, and who --by names.
+    const source = scopeSource(req.cwd);
+    if (req.by !== undefined)
+        refuseUnidentified(source, [req.by], "--by", { agent: req.agent });
+    if (after !== before && (source.declaration !== null || (req.agent !== undefined && req.agent !== ""))) {
+        const writer = resolveWriter(source.declaration, source.policy, { agent: req.agent || null, principal: req.by ?? null }, source.classes);
+        const unknown = unknownClassVerdict(source.declaration, writer, source.classes);
+        if (!unknown.ok)
+            throw new WriteScopeError(unknown.code, unknown.message);
+        const verdict = judgePath(source.declaration, writer, declaration.file, { before: () => before, after: () => after });
+        if (!verdict.ok)
+            throw new DeclarationWriteError(verdict.code, verdict.message);
+    }
+    const changed = after !== before;
+    if (changed && !req.dryRun)
+        writeAtomically(declFile, after);
+    return {
+        ...head,
+        name: req.name,
+        declaration: { path: declPath, sha256: sha256(after) },
+        paths: changed ? [declPath] : [],
+        changed,
+        dryRun: req.dryRun === true,
+        previous,
+        entry: given,
+    };
+}