@intentius/chant 0.110.0 → 0.112.0

package/src/workspace/box-factory-write.schema.json

@@ -0,0 +1,342 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/box-factory-write/v1/box-factory-write.schema.json",
+  "title": "chant workspace box factory set output",
+  "description": "What `chant workspace box factory set <member> --from <file|->` prints (#3600): the box's factory before and after, as `status --json` prints it, and the file the write changed, or the reason it wrote nothing. The write changes only the factory's own top-level properties, members[i].box.factory in the declaration, in place, keeping the file's formatting and comments. It never commits. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.110.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The factory was written, or would be with --dry-run, or already held what was given (changed false). Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "member",
+        "declaration",
+        "paths",
+        "changed",
+        "dryRun",
+        "previous",
+        "factory"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/box-factory-write/v1/box-factory-write.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string",
+          "description": "The chant that wrote it."
+        },
+        "member": {
+          "type": "string",
+          "description": "The member whose box block holds the factory."
+        },
+        "declaration": {
+          "type": "object",
+          "required": [
+            "path",
+            "sha256"
+          ],
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "The declaration file, relative to the repository root (the working directory outside git), with / separators."
+            },
+            "sha256": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "The sha256 of the declaration's bytes after the write, or as they would be with --dry-run."
+            }
+          }
+        },
+        "paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The declaration, relative to the repository root, when the write changed it or would with --dry-run; empty when the factory already held what was given."
+        },
+        "changed": {
+          "type": "boolean",
+          "description": "Whether the declaration changed: paths is not empty."
+        },
+        "dryRun": {
+          "type": "boolean",
+          "description": "True when --dry-run was given: nothing was written, and the document says what would have been."
+        },
+        "previous": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/factory"
+            }
+          ],
+          "description": "The factory before the write, as status --json prints it, or null when the box declared none."
+        },
+        "factory": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/factory"
+            }
+          ],
+          "description": "The factory after the write, as status --json prints it, or null when the box still declares none."
+        }
+      }
+    },
+    "factory": {
+      "type": "object",
+      "required": [
+        "builds",
+        "check",
+        "checks",
+        "builders",
+        "tiers",
+        "builderFor",
+        "publish"
+      ],
+      "properties": {
+        "builds": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "The members the factory builds, in declaration order. A work item a person asks for constrains member:<the first>."
+        },
+        "check": {
+          "description": "The verdict command, run from the workspace root, and what it is; null when none is declared.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "run",
+                "kind"
+              ],
+              "properties": {
+                "run": {
+                  "type": "string"
+                },
+                "kind": {
+                  "enum": [
+                    "test",
+                    "build",
+                    "lint",
+                    "plan",
+                    "conformance"
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        "checks": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Where a work item's builder writes its check, from the workspace root, or null for the orchestrator's choice."
+        },
+        "builders": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The member that declares the builder agents, or null."
+        },
+        "tiers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "tier",
+              "agent",
+              "kinds",
+              "session"
+            ],
+            "properties": {
+              "tier": {
+                "type": "string"
+              },
+              "agent": {
+                "type": "string"
+              },
+              "kinds": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ]
+              },
+              "session": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            }
+          },
+          "description": "Which builder agent builds at which tier, as declared (#3152, ws-094), each { tier, agent, kinds, session } with kinds and session null when not declared; empty when none is. Added in contract 1 by chant 0.103.0."
+        },
+        "builderFor": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "required": [
+                "agent",
+                "session"
+              ],
+              "properties": {
+                "agent": {
+                  "type": "string"
+                },
+                "session": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              }
+            }
+          },
+          "description": "The builder for each member the factory builds, by tier (#3152): member name, then tier, then { agent, session }. For a member the entry naming its kind is used, else the tier's entry with no kinds; a tier with neither is left out. Added in contract 1 by chant 0.103.0."
+        },
+        "publish": {
+          "description": "Where a finished build is published, or null when the factory doesn't publish past the box.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "forge",
+                "repo",
+                "base",
+                "branchPrefix",
+                "head"
+              ],
+              "properties": {
+                "forge": {
+                  "const": "github"
+                },
+                "repo": {
+                  "type": "string",
+                  "description": "owner/name: where the pull request is opened."
+                },
+                "base": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The branch the pull request targets, or null for the repository's default branch."
+                },
+                "branchPrefix": {
+                  "type": "string",
+                  "description": "What the published branch's name starts with, before the work item's id. chant/work/ unless declared."
+                },
+                "head": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "owner/name of the fork the branch is pushed to, or null to push to repo."
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was written. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "member",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/box-factory-write/v1/box-factory-write.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "revision-unknown",
+                "write-usage-invalid",
+                "write-input-invalid",
+                "factory-member-unknown",
+                "factory-box-missing",
+                "write-scope-member",
+                "write-scope-protected",
+                "write-scope-class-unknown",
+                "agent-unknown",
+                "principal-unidentified",
+                "write-lock-timeout",
+                "write-lock-not-held"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/workspace/box-factory-write.test.ts

@@ -0,0 +1,108 @@
+/**
+ * #3600: a box's factory written through chant, so a box planted from a
+ * shared template gets its factory.publish target at planting.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, repo } from "./__fixtures__/contract-repo";
+import { boxFactorySet, type BoxFactoryWriteDocument, type BoxFactoryWriteRequest } from "./box-factory-write";
+import schema from "./box-factory-write.schema.json";
+import { workspaceStatus } from "./status";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(schema);
+
+/** The template's declaration: a box whose factory builds the app and names no publish target. */
+const TEMPLATE = `{
+  // planted from the studio template
+  "name": "fern",
+  "schema": 1,
+  "members": [
+    { "name": "app", "dir": "app", "kind": "other", "because": "the app" },
+    {
+      "name": "box",
+      "dir": "box",
+      "kind": "other",
+      "because": "the box",
+      "box": {
+        "factory": { "builds": ["app"], "check": "npm test" }, // no publish: the template can't know the repo
+        "publisher": "node box/publish.mjs",
+      },
+    },
+  ],
+}
+`;
+
+function run(root: string, req: Omit<BoxFactoryWriteRequest, "cwd" | "fields"> & { fields?: unknown }): BoxFactoryWriteDocument {
+  const doc = boxFactorySet({ ...req, cwd: root, fields: req.fields === undefined ? undefined : JSON.stringify(req.fields) });
+  expectValid(doc);
+  return doc;
+}
+
+const code = (doc: BoxFactoryWriteDocument) => ("error" in doc ? doc.error.code : null);
+
+describe("box factory set (#3600)", () => {
+  test("a planter sets factory.publish, status reads it back, and the file keeps its comments", async () => {
+    const root = repo({ "chant.workspace.jsonc": TEMPLATE, "app/a.txt": "", "box/b.txt": "" });
+    const doc = run(root, { member: "box", fields: { publish: { repo: "alex/fern", base: "main" } } });
+    expect(doc).toMatchObject({
+      member: "box",
+      changed: true,
+      paths: ["chant.workspace.jsonc"],
+      previous: { builds: ["app"], publish: null },
+      factory: { builds: ["app"], check: { run: "npm test", kind: "test" }, publish: { forge: "github", repo: "alex/fern", base: "main", branchPrefix: "chant/work/", head: null } },
+    });
+    const text = readFileSync(join(root, "chant.workspace.jsonc"), "utf-8");
+    expect(text).toContain("// no publish: the template can't know the repo");
+    expect(text).toContain("// planted from the studio template");
+    const status = await workspaceStatus({ cwd: root, env: "box" });
+    if ("error" in status) throw new Error(status.error.message);
+    expect(status.members.find((m) => m.name === "box")?.box?.factory?.publish?.repo).toBe("alex/fern");
+
+    // The same again changes nothing; null takes a field out.
+    expect(run(root, { member: "box", fields: { publish: { repo: "alex/fern", base: "main" } } })).toMatchObject({ changed: false, paths: [] });
+    expect(run(root, { member: "box", fields: { publish: null } })).toMatchObject({ changed: true, factory: { publish: null } });
+  });
+
+  test("a dry run writes nothing, and a box with no factory gets one", () => {
+    const root = repo({
+      "chant.workspace.json": `${JSON.stringify({ name: "w", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "b", box: {} }] }, null, 2)}\n`,
+      "app/a.txt": "",
+    });
+    const before = readFileSync(join(root, "chant.workspace.json"), "utf-8");
+    expect(run(root, { member: "app", fields: { builds: ["app"], publish: { repo: "o/r" } }, dryRun: true })).toMatchObject({ changed: true, dryRun: true, previous: null });
+    expect(readFileSync(join(root, "chant.workspace.json"), "utf-8")).toBe(before);
+    expect(run(root, { member: "app", fields: { builds: ["app"], publish: { repo: "o/r" } } })).toMatchObject({ factory: { builds: ["app"], publish: { repo: "o/r" } } });
+  });
+
+  test("refuses an unknown member, a member with no box, a field a factory doesn't take, and a repo that isn't owner/name", () => {
+    const root = repo({ "chant.workspace.jsonc": TEMPLATE, "app/a.txt": "", "box/b.txt": "" });
+    const before = readFileSync(join(root, "chant.workspace.jsonc"), "utf-8");
+    expect(code(run(root, { member: "ghost", fields: { publish: { repo: "o/r" } } }))).toBe("factory-member-unknown");
+    expect(code(run(root, { member: "app", fields: { publish: { repo: "o/r" } } }))).toBe("factory-box-missing");
+    expect(code(run(root, { member: "box", fields: { listing: {} } }))).toBe("write-input-invalid");
+    const bad = run(root, { member: "box", fields: { publish: { repo: "{{chant:repo}}" } } });
+    expect(code(bad)).toBe("write-input-invalid");
+    expect(code(run(root, { member: "box" }))).toBe("write-usage-invalid");
+    expect(readFileSync(join(root, "chant.workspace.jsonc"), "utf-8")).toBe(before);
+  });
+
+  test("a protected declaration takes the write when its except names the publish target", () => {
+    const decl = (except?: string[]) => ({
+      name: "w",
+      schema: 1,
+      members: [{ name: "app", dir: ".", kind: "other", because: "b", box: { factory: { builds: ["app"] } } }],
+      writeScope: { human: { protected: [except ? { path: "chant.workspace.json", except } : "chant.workspace.json"] } },
+    });
+    const root = repo({ "chant.workspace.json": `${JSON.stringify(decl(), null, 2)}\n` }, true);
+    git(root, "branch", "-M", "main");
+    expect(code(run(root, { member: "app", fields: { publish: { repo: "o/r" } } }))).toBe("write-scope-protected");
+    writeFileSync(join(root, "chant.workspace.json"), `${JSON.stringify(decl(["/members/*/box/factory/publish"]), null, 2)}\n`);
+    git(root, "commit", "-q", "-am", "planting may set the publish target");
+    expect(run(root, { member: "app", fields: { publish: { repo: "o/r" } } })).toMatchObject({ changed: true });
+    expect(code(run(root, { member: "app", fields: { "x-note": 1 } }))).toBe("write-scope-protected");
+  });
+});

package/src/workspace/box-factory-write.ts

@@ -0,0 +1,226 @@
+/**
+ * `chant workspace box factory set <member>` (#3600): change a box's
+ * factory, `members[i].box.factory` in the declaration (#3146, ws-077),
+ * through chant.
+ *
+ * A box planted from a shared template can't carry where it publishes:
+ * `factory.publish.repo` must be a real owner/name, so the template leaves
+ * it out and whoever plants the box, which knows the box's repo, sets it
+ * here. The write is the factory's sibling of `box listing set` (#3308): it
+ * changes only the factory's own top-level properties, in place, so the file
+ * keeps its formatting, key order and comments; it validates the declaration
+ * it would write, judges the declaration by the write scope at base (so a
+ * protected declaration takes it when its `except` names
+ * `/members/*\/box/factory/publish`), refuses a bare `--by` name under
+ * `identity.attribution: "identified"`, holds the working tree's write lock,
+ * prints one JSON document (`box-factory-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 { factoryView, type FactoryView } from "./box-factory";
+import { parseDeclaration, readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type Declaration } from "./declaration";
+import { IDENTITY_CODES, IdentityError, refuseUnidentified } from "./identity";
+import { removeProperty, setProperty, valueAt } from "./json-edit";
+import { parseJsonText } from "./jsonc";
+import type { ReasonCode } from "./reason-codes";
+import { locateWorkspace } from "./which-chant";
+import { judgePath, resolveWriter, scopeSource, unknownClassVerdict, WriteScopeError } from "./write-scope";
+import { withWriteLockSync, WriteLockError, WRITE_LOCK_CODES } from "./write-lock";
+
+/** The version of the document this write prints. */
+export const BOX_FACTORY_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for what `box factory set` prints, shipped beside this file. */
+export const BOX_FACTORY_WRITE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/box-factory-write/v1/box-factory-write.schema.json";
+
+/** Why a factory write wrote nothing. Closed. */
+export const BOX_FACTORY_ERROR_CODES = [
+  ...WORKSPACE_ERROR_CODES,
+  "write-usage-invalid",
+  "write-input-invalid",
+  "factory-member-unknown",
+  "factory-box-missing",
+  "write-scope-member",
+  "write-scope-protected",
+  "write-scope-class-unknown",
+  "agent-unknown",
+  ...IDENTITY_CODES,
+  ...WRITE_LOCK_CODES,
+] as const satisfies readonly ReasonCode[];
+export type BoxFactoryErrorCode = (typeof BOX_FACTORY_ERROR_CODES)[number];
+
+/** The factory properties a write may set. Any `x-` key is passed through as well. */
+export const FACTORY_FIELDS = ["builds", "check", "checks", "builders", "tiers", "publish"] as const;
+
+type Head = { $schema: string; contract: number; chant: string };
+
+/** What `box factory set` prints. */
+export type BoxFactoryWriteDocument =
+  | (Head & {
+      member: string;
+      /** The declaration file, from the repository root, and the sha256 of its bytes after the write (or as it would be, with dryRun). */
+      declaration: { path: string; sha256: string };
+      /** The declaration, from the repository root, when the write changed it; else empty. */
+      paths: string[];
+      changed: boolean;
+      dryRun: boolean;
+      /** The factory before the write, as status --json prints it, or null when the box declared none. */
+      previous: FactoryView | null;
+      /** The factory after the write, as status --json prints it, or null when the write took every field out. */
+      factory: FactoryView | null;
+    })
+  | (Head & { member: string | null; error: { code: BoxFactoryErrorCode; message: string } });
+
+export interface BoxFactoryWriteRequest {
+  cwd: string;
+  member: string;
+  /** The factory fields as JSON text (`--from`). */
+  fields?: string;
+  /** Who is writing (`--by`). */
+  by?: string;
+  /** The agent session (`CHANT_AGENT`). */
+  agent?: string;
+  dryRun?: boolean;
+}
+
+class FactoryWriteError extends Error {
+  constructor(
+    readonly code: BoxFactoryErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+const toPosix = (p: string) => (sep === "/" ? p : p.split(sep).join("/"));
+const sha256 = (b: string) => createHash("sha256").update(b).digest("hex");
+const isObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** The factory fields given with --from: a JSON object of the factory's fields and x- keys; null for a key takes it out. */
+function readFields(text: string | undefined): Record<string, unknown> {
+  if (text === undefined || text.trim() === "") throw new FactoryWriteError("write-usage-invalid", "box factory set needs the factory fields: --from <file|->, such as {\"publish\": {\"repo\": \"owner/name\"}}");
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (err) {
+    throw new FactoryWriteError("write-input-invalid", `the factory fields are not JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!isObject(value)) throw new FactoryWriteError("write-input-invalid", "the factory fields are a JSON object, such as {\"publish\": {\"repo\": \"owner/name\"}}");
+  for (const k of Object.keys(value)) {
+    if (k.startsWith("x-") || (FACTORY_FIELDS as readonly string[]).includes(k)) continue;
+    throw new FactoryWriteError("write-input-invalid", `${k} is not a factory field; a factory takes ${FACTORY_FIELDS.join(", ")} and x- keys`);
+  }
+  return value;
+}
+
+/** Write `text` to `file` through a sibling temporary file, so a reader never sees half of it. */
+function writeAtomically(file: string, text: string): void {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.chant-${process.pid}.tmp`;
+  writeFileSync(tmp, text);
+  renameSync(tmp, file);
+}
+
+/** Run the write and build the document it prints. Never throws for a refusal. */
+export function boxFactorySet(req: BoxFactoryWriteRequest): BoxFactoryWriteDocument {
+  const head: Head = { $schema: BOX_FACTORY_WRITE_SCHEMA_ID, contract: BOX_FACTORY_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    return withWriteLockSync(req.cwd, { verb: "box factory set", by: req.by ?? null, agent: req.agent || null }, req.dryRun, () => write(req, head));
+  } catch (err) {
+    const fail = (code: BoxFactoryErrorCode, message: string): BoxFactoryWriteDocument => ({ ...head, member: req.member || null, error: { code, message } });
+    if (err instanceof FactoryWriteError) return fail(err.code, err.message);
+    if (err instanceof WriteScopeError) return fail(err.code as BoxFactoryErrorCode, 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 as BoxFactoryErrorCode, err.describe());
+    throw err;
+  }
+}
+
+function write(req: BoxFactoryWriteRequest, head: Head): BoxFactoryWriteDocument {
+  if (!req.member) throw new FactoryWriteError("write-usage-invalid", "box factory set needs the member whose box builds: box factory set <member>");
+  const fields = readFields(req.fields);
+
+  const located = locateWorkspace(req.cwd);
+  const declaration = readDeclaration(located.tree);
+  const member = declaration.members.find((m) => m.name === req.member);
+  if (!member) {
+    throw new FactoryWriteError("factory-member-unknown", `no member is named ${req.member}; the declaration's members are ${declaration.members.map((m) => m.name).join(", ") || "none"}`);
+  }
+  if (!member.box) throw new FactoryWriteError("factory-box-missing", `member ${member.name} declares no box block, so it has no factory; a factory is what a box builds (#3146)`);
+
+  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");
+
+  // The declaration, with only the factory's own properties changed.
+  const boxPointer = member.box.pointer;
+  const factoryPointer = `${boxPointer}/factory`;
+  const parsed = parseJsonText(before, { jsonc });
+  if (!parsed.ok) throw new WorkspaceReadError("declaration-unparseable", parsed.message);
+  const raw = valueAt(parsed.value, factoryPointer);
+  let after = before;
+  const expected = structuredClone(parsed.value) as Record<string, unknown>;
+  const expectedBox = valueAt(expected, boxPointer) as Record<string, unknown>;
+  if (raw === undefined) {
+    const value = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== null));
+    if (Object.keys(value).length > 0) {
+      after = setProperty(after, jsonc, boxPointer, "factory", value);
+      expectedBox.factory = value;
+    }
+  } else {
+    const expectedFactory = expectedBox.factory as Record<string, unknown>;
+    for (const [k, v] of Object.entries(fields)) {
+      if (v === null) {
+        after = removeProperty(after, jsonc, factoryPointer, k);
+        delete expectedFactory[k];
+      } else if (!isDeepStrictEqual(expectedFactory[k], v)) {
+        after = setProperty(after, jsonc, factoryPointer, k, v);
+        expectedFactory[k] = v;
+      }
+    }
+  }
+  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(`box factory set: editing ${declaration.file} in place did not give the declaration intended; nothing was written`);
+  }
+  let next: Declaration;
+  try {
+    next = parseDeclaration(after, declaration.file);
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) throw new FactoryWriteError("write-input-invalid", `the factory would make the declaration invalid: ${err.describe()}`);
+    throw err;
+  }
+  const nextMember = next.members.find((m) => m.name === member.name)!;
+
+  // 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 FactoryWriteError(verdict.code as BoxFactoryErrorCode, verdict.message);
+  }
+
+  const changed = after !== before;
+  if (changed && !req.dryRun) writeAtomically(declFile, after);
+  return {
+    ...head,
+    member: member.name,
+    declaration: { path: declPath, sha256: sha256(after) },
+    paths: changed ? [declPath] : [],
+    changed,
+    dryRun: req.dryRun === true,
+    previous: factoryView(member.box.factory, declaration.members),
+    factory: factoryView(nextMember.box!.factory, next.members),
+  };
+}