@intentius/chant 0.110.0 → 0.111.0

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),
+  };
+}

package/src/workspace/box-intent.test.ts

@@ -4,7 +4,7 @@
  * `graph --intent` shows it for the box's files.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
 import { cleanScratch, commitAll, contract, REPO, repo } from "./__fixtures__/contract-repo";
@@ -134,13 +134,13 @@ describe("the box block's intent", () => {
 describe("a box planted as a question", () => {
   test("a proposed intent reports its question and no answer, and passes the checks", async () => {
     const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:app"]) });
-    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "proposed", question: QUESTION, choice: null, answer: null, decided_by: null, decided_on: null });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "proposed", question: QUESTION, choice: null, answer: null, decided_by: null, decided_on: null, approved: false });
     expect(await intentFindings(root)).toEqual([]);
   });
 
   test("a decided intent reports the answer and who gave it, and graph --intent shows it for the box's files", async () => {
     const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "decided", ["member:app"]) });
-    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "decided", question: QUESTION, choice: CHOICE, answer: ANSWER, decided_by: "alex", decided_on: "2026-09-26" });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "decided", question: QUESTION, choice: CHOICE, answer: ANSWER, decided_by: "alex", decided_on: "2026-09-26", approved: true });
     expect(await intentFindings(root)).toEqual([]);
     commitAll(root, "plant the box");
     const { doc } = await intentGraph({ cwd: root, region: "app" });
@@ -148,6 +148,16 @@ describe("a box planted as a question", () => {
     expect(doc.nodes.filter((n) => n.kind === "decision").map((n) => (n.kind === "decision" ? [n.record, n.state, n.decided_by] : []))).toEqual([["box-001", "decided", "alex"]]);
   });
 
+  test("approved follows the decision kind's approval ranks, not the state's name (#3609)", async () => {
+    const records = { "decisions/box-001-what-app-is-for.md": decision("box-001", "decided", ["member:app"]) };
+    const root = workspace({ intent: "box-001" }, records);
+    const kind = join(root, "decisions", "decision.kind.mjs");
+    const text = readFileSync(kind, "utf-8");
+    expect(text).toContain("decided: 1,");
+    writeFileSync(kind, text.replace("decided: 1,", "decided: 0,"));
+    expect((await boxOf(root))?.intent).toMatchObject({ state: "decided", approved: false });
+  });
+
   test("a decided intent whose choice names an option not in options[] reports a null answer", async () => {
     const data = { ...BASE, id: "box-001", title: "Intent box-001", state: "decided", question: QUESTION, choice: { option: "z", reason: "no such option" }, rejected: [], evidence: [], decided_by: "alex", decided_on: "2026-09-26", constrains: ["member:app"] };
     const record = `---\n${JSON.stringify(data, null, 2)}\n---\n\n# box-001\n`;
@@ -157,7 +167,7 @@ describe("a box planted as a question", () => {
 
   test("an intent no decision record has fails WSP126, and status reports only its id", async () => {
     const root = workspace({ intent: "box-009" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:app"]) });
-    expect((await boxOf(root))?.intent).toEqual({ id: "box-009", state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-009", state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null, approved: false });
     expect(await intentFindings(root)).toEqual([["WSP126", "error", "box-intent-unknown", "app"]]);
     const [d] = (await runDeclarationChecks(root)).diagnostics.filter((x) => x.ruleId === "WSP126");
     expect(d.message).toContain("no record of decisions/decision.kind.mjs has that id");

package/src/workspace/box-intent.ts

@@ -37,6 +37,12 @@ export interface BoxIntent {
   answer: string | null;
   decided_by: string | null;
   decided_on: string | null;
+  /**
+   * Whether the record's state counts as approved (#3609): the decision
+   * kind's `approval` rank for it is above 0, the rule the factory's pick
+   * holds dispatch with. False with no record, and for a kind with no ranks.
+   */
+  approved: boolean;
 }
 
 /** The decision record a box's intent names, as the checks read it. */
@@ -71,7 +77,7 @@ function answerOf(choice: unknown, options: unknown): string | null {
 
 /** The intent of `id` with no record: every field but the id null. */
 export function unresolvedIntent(id: string): BoxIntent {
-  return { id, state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null };
+  return { id, state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null, approved: false };
 }
 
 /**
@@ -96,6 +102,7 @@ export async function resolveBoxIntents(declaration: Declaration, root: string,
     try {
       const read = await readRecordsFor({ kind: k.file, cwd: root, workGaps: false });
       const field = read.loaded.kind.constrains?.field ?? "constrains";
+      const approval = read.loaded.kind.approval ?? {};
       for (const r of read.result.records) {
         if (r.id === null || found.has(r.id)) continue;
         const data = r.data ?? {};
@@ -112,6 +119,7 @@ export async function resolveBoxIntents(declaration: Declaration, root: string,
             answer: answerOf(data.choice, data.options),
             decided_by: str(data.decided_by),
             decided_on: str(data.decided_on),
+            approved: r.state !== null && (approval[r.state] ?? 0) > 0,
           },
         });
       }

package/src/workspace/declaration-extensions.test.ts

@@ -0,0 +1,79 @@
+/**
+ * #3595: the x- keys a declaration holds come back from `status --json` and
+ * `ls --json` on the object that holds them, so a reader never parses the
+ * declaration to get back what it wrote through chant.
+ */
+
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, repo } from "./__fixtures__/contract-repo";
+import { extensionsAt, parseDeclaration } from "./declaration";
+import { listWorkspace } from "./ls";
+import lsSchema from "./ls.schema.json";
+import { workspaceStatus } from "./status";
+import statusSchema from "./status.schema.json";
+
+afterAll(cleanScratch);
+
+const APP = { owner: "alex", createdAt: "2026-10-01T00:00:00.000Z", repo: "acme/fern", branch: "main" };
+
+const DECLARATION = {
+  name: "fern",
+  schema: 1,
+  "x-lobby": { slot: 3 },
+  members: [
+    { name: "app", dir: "app", kind: "other", because: "the app", "x-member": 1 },
+    {
+      name: "steward",
+      dir: "steward",
+      kind: "other",
+      because: "the box",
+      box: {
+        "x-factory": { intent: "box-001" },
+        capabilities: [{ name: "inference", scope: ["chat"], "x-cap": true }],
+        services: [{ name: "app", cmd: "node app.mjs", "x-svc": "a" }],
+        factory: { builds: ["app"], check: { run: "npm test", "x-check": 2 }, publish: { repo: "acme/fern", "x-pub": "p" }, "x-fac": "f" },
+        listing: { title: "Fern", line: "A review queue", "x-studio-app": APP },
+        ship: { op: "ship", "x-ship": "s" },
+      },
+    },
+  ],
+};
+
+describe("x- keys in the read contract (#3595)", () => {
+  const root = repo({ "chant.workspace.json": `${JSON.stringify(DECLARATION, null, 2)}\n`, "app/a.txt": "", "steward/s.txt": "" }, true);
+
+  test("extensionsAt reads the x- keys at a pointer, and nothing where there is no object", () => {
+    const decl = parseDeclaration(JSON.stringify(DECLARATION), "chant.workspace.json");
+    expect(extensionsAt(decl, "")).toEqual({ "x-lobby": { slot: 3 } });
+    expect(extensionsAt(decl, "/members/0")).toEqual({ "x-member": 1 });
+    expect(extensionsAt(decl, "/members/1/box/listing")).toEqual({ "x-studio-app": APP });
+    expect(extensionsAt(decl, "/members/0/box")).toEqual({});
+    expect(extensionsAt(decl, "/members/0/name")).toEqual({});
+    expect(extensionsAt({ ...decl }, "")).toEqual({});
+  });
+
+  test("status --json keeps them on the member, the box and the box's parts", async () => {
+    const out = await workspaceStatus({ cwd: root, env: "box" });
+    contract(statusSchema).expectValid(out);
+    if ("error" in out) throw new Error(out.error.message);
+    const [app, steward] = out.members;
+    expect(app).toMatchObject({ name: "app", "x-member": 1 });
+    const box = steward.box!;
+    expect(box).toMatchObject({ "x-factory": { intent: "box-001" } });
+    expect(box.capabilities[0]).toMatchObject({ name: "inference", "x-cap": true });
+    expect(box.services[0]).toMatchObject({ name: "app", "x-svc": "a" });
+    expect(box.factory).toMatchObject({ "x-fac": "f", check: { run: "npm test", "x-check": 2 }, publish: { repo: "acme/fern", "x-pub": "p" } });
+    expect(box.listing).toMatchObject({ title: "Fern", "x-studio-app": APP });
+    expect(box.ship).toMatchObject({ op: "ship", "x-ship": "s" });
+    expect(Object.keys(steward).filter((k) => k.startsWith("x-"))).toEqual([]);
+  });
+
+  test("ls --json keeps them on each member and on the workspace", () => {
+    const out = listWorkspace({ cwd: root });
+    contract(lsSchema).expectValid(out);
+    if ("error" in out) throw new Error(out.error.message);
+    expect(out.workspace).toMatchObject({ name: "fern", "x-lobby": { slot: 3 } });
+    expect(out.members[0]).toMatchObject({ name: "app", "x-member": 1 });
+    expect(Object.keys(out.members[1]).filter((k) => k.startsWith("x-"))).toEqual([]);
+  });
+});

package/src/workspace/declaration-write-cli.ts

@@ -0,0 +1,82 @@
+/**
+ * `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 type { CommandContext } from "../cli/registry";
+import { readerVersion } from "./declaration";
+import {
+  DECLARATION_WRITE_CONTRACT_VERSION,
+  DECLARATION_WRITE_SCHEMA_ID,
+  declarationWrite,
+  type DeclarationWriteAction,
+  type DeclarationWriteDocument,
+} from "./declaration-write";
+import { AGENT_ENV } from "./write-scope";
+
+const USAGE: Record<DeclarationWriteAction, string> = {
+  "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: DeclarationWriteDocument): number => {
+  console.log(JSON.stringify(doc, null, 2));
+  return "error" in doc ? 1 : 0;
+};
+
+/** `chant workspace member add|remove <name>`. */
+export function runWorkspaceMember(ctx: CommandContext): number {
+  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: CommandContext): number {
+  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: DeclarationWriteAction, name: string | undefined, message: string): number {
+  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: CommandContext, action: DeclarationWriteAction, rest: string[]): number {
+  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]] as const) {
+    if (v !== undefined) return usage(action, name, `${action} takes no ${flag}`);
+  }
+  let entry: string | undefined;
+  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/src/workspace/declaration-write.test.ts

@@ -0,0 +1,155 @@
+/**
+ * #3596: a declaration's members and hosts written through chant, the way a
+ * local lobby plants, retires and starts boxes, without editing the file.
+ */
+
+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 { readDeclaration } from "./declaration";
+import { declarationWrite, type DeclarationWriteDocument, type DeclarationWriteRequest } from "./declaration-write";
+import schema from "./member-write.schema.json";
+import { appendElement, removeElement, setElement } from "./json-edit";
+import { parseJsonText } from "./jsonc";
+import { workingTree } from "./tree";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(schema);
+
+const HOST = { name: "local", ports: { from: 18100, to: 18199, perBox: 10 }, stateRoot: "${STUDIO_LOBBY_HOME}/boxes" };
+const box = (name: string, slot: number) => ({
+  name,
+  dir: `boxes/${name}`,
+  kind: "other",
+  because: "a box the lobby planted",
+  box: { host: "local", slot, ports: { door: 0, site: 1 }, state: { record: "box.json" }, cookies: ["hud_session"] },
+});
+
+const JSONC = `{
+  // the lobby
+  "name": "studio-lobby",
+  "schema": 1,
+  "minReader": "0.93.0",
+  "members": [
+    // planted boxes
+  ],
+}
+`;
+
+function lobby(text = JSONC, file = "chant.workspace.jsonc"): string {
+  return repo({ [file]: text });
+}
+
+function run(root: string, req: Omit<DeclarationWriteRequest, "cwd" | "entry"> & { entry?: unknown }): DeclarationWriteDocument {
+  const doc = declarationWrite({ ...req, cwd: root, entry: req.entry === undefined ? undefined : JSON.stringify(req.entry) });
+  expectValid(doc);
+  return doc;
+}
+
+const code = (doc: DeclarationWriteDocument) => ("error" in doc ? doc.error.code : null);
+const declOf = (root: string) => readDeclaration(workingTree(root));
+
+describe("host set and member add|remove on a lobby's declaration (#3596)", () => {
+  test("the first start writes the host, plants two boxes and retires one, keeping the file's comments", () => {
+    const root = lobby();
+    const host = run(root, { action: "host set", name: "local", entry: HOST });
+    expect(host).toMatchObject({ action: "host set", name: "local", changed: true, previous: null, entry: HOST, paths: ["chant.workspace.jsonc"] });
+
+    const fern = run(root, { action: "member add", name: "fern", entry: box("fern", 0) });
+    expect(fern).toMatchObject({ changed: true, previous: null, entry: box("fern", 0) });
+    expect(run(root, { action: "member add", name: "moss", entry: { ...box("moss", 1), name: undefined } })).toMatchObject({ changed: true });
+    expect(declOf(root).members.map((m) => [m.name, m.box?.isolation?.slot])).toEqual([
+      ["fern", 0],
+      ["moss", 1],
+    ]);
+
+    const text = readFileSync(join(root, "chant.workspace.jsonc"), "utf-8");
+    expect(text).toContain("// the lobby");
+    expect(text).toContain("// planted boxes");
+    expect(declarationWrite({ cwd: root, action: "host set", name: "local", entry: JSON.stringify(HOST) })).toMatchObject({ changed: false, previous: HOST, paths: [] });
+
+    const retire = run(root, { action: "member remove", name: "fern" });
+    expect(retire).toMatchObject({ changed: true, previous: box("fern", 0), entry: null });
+    expect(declOf(root).members.map((m) => m.name)).toEqual(["moss"]);
+    expect(readFileSync(join(root, "chant.workspace.jsonc"), "utf-8")).toContain("// planted boxes");
+  });
+
+  test("host set replaces a host in place, and a dry run writes nothing", () => {
+    const root = lobby(`${JSON.stringify({ name: "l", schema: 1, members: [], hosts: [HOST] }, null, 2)}\n`, "chant.workspace.json");
+    const before = readFileSync(join(root, "chant.workspace.json"), "utf-8");
+    const wider = { ...HOST, ports: { from: 18100, to: 18299, perBox: 10 } };
+    const dry = run(root, { action: "host set", name: "local", entry: wider, dryRun: true });
+    expect(dry).toMatchObject({ changed: true, dryRun: true, previous: HOST, entry: wider });
+    expect(readFileSync(join(root, "chant.workspace.json"), "utf-8")).toBe(before);
+    run(root, { action: "host set", name: "local", entry: wider });
+    expect(declOf(root).hosts.map((h) => h.ports.to)).toEqual([18299]);
+  });
+
+  test("refuses a name taken, a member not there, an entry that doesn't read, and two boxes in one slot", () => {
+    const root = lobby();
+    run(root, { action: "host set", name: "local", entry: HOST });
+    run(root, { action: "member add", name: "fern", entry: box("fern", 0) });
+    const before = readFileSync(join(root, "chant.workspace.jsonc"), "utf-8");
+
+    expect(run(root, { action: "member add", name: "fern", entry: box("fern", 0) })).toMatchObject({ changed: false });
+    expect(code(run(root, { action: "member add", name: "fern", entry: box("fern", 2) }))).toBe("member-exists");
+    expect(code(run(root, { action: "member remove", name: "ghost" }))).toBe("member-unknown");
+    const invalid = run(root, { action: "member add", name: "moss", entry: { ...box("moss", 1), because: undefined } });
+    expect(code(invalid)).toBe("write-input-invalid");
+    expect("error" in invalid && invalid.error.message).toMatch(/needs "because"/);
+    const shared = run(root, { action: "member add", name: "moss", entry: box("moss", 0) });
+    expect(code(shared)).toBe("box-isolation-collision");
+    expect("error" in shared && shared.error.message).toMatch(/fern\.door and moss\.door/);
+    expect(code(run(root, { action: "member add", name: "moss", entry: { ...box("moss", 1), name: "fern" } }))).toBe("write-input-invalid");
+    expect(code(run(root, { action: "host set", name: "local", entry: { ...HOST, stateRoot: "/var/boxes" } }))).toBe("box-isolation-literal");
+    expect(code(run(root, { action: "member remove", name: "fern", entry: {} }))).toBe("write-usage-invalid");
+    expect(code(run(root, { action: "host set", name: "local" }))).toBe("write-usage-invalid");
+    expect(readFileSync(join(root, "chant.workspace.jsonc"), "utf-8")).toBe(before);
+  });
+
+  test("a writer the write scope at base keeps off the declaration is refused, unless except allows members and hosts", () => {
+    const decl = (except?: string[]) => ({
+      name: "l",
+      schema: 1,
+      members: [{ name: "root", dir: ".", kind: "other", because: "the lobby" }],
+      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, { action: "host set", name: "local", entry: HOST }))).toBe("write-scope-protected");
+    writeFileSync(join(root, "chant.workspace.json"), `${JSON.stringify(decl(["members", "hosts"]), null, 2)}\n`);
+    git(root, "commit", "-q", "-am", "allow the lobby's writes");
+    expect(run(root, { action: "host set", name: "local", entry: HOST })).toMatchObject({ changed: true });
+    expect(run(root, { action: "member add", name: "fern", entry: box("fern", 0) })).toMatchObject({ changed: true });
+  });
+});
+
+describe("array edits in place (#3596)", () => {
+  const read = (text: string) => {
+    const r = parseJsonText(text, { jsonc: true });
+    if (!r.ok) throw new Error(r.message);
+    return r.value;
+  };
+
+  test("append to an empty, a multi-line and a one-line array", () => {
+    expect(read(appendElement('{ "a": [] }', false, "/a", { x: 1 }))).toEqual({ a: [{ x: 1 }] });
+    const multi = '{\n  "a": [\n    1, // one\n    2\n  ]\n}\n';
+    const out = appendElement(multi, true, "/a", 3);
+    expect(out).toBe('{\n  "a": [\n    1, // one\n    2,\n    3\n  ]\n}\n');
+    expect(appendElement('{ "a": [1, 2] }', false, "/a", 3)).toBe('{ "a": [1, 2, 3] }');
+    expect(read(appendElement('{\n  "a": [\n    1,\n  ],\n}', true, "/a", 2))).toEqual({ a: [1, 2] });
+  });
+
+  test("remove the first, a middle, the last and the only element, and replace one", () => {
+    const text = '{\n  "a": [\n    1,\n    2,\n    3\n  ]\n}\n';
+    expect(removeElement(text, false, "/a", 0)).toBe('{\n  "a": [\n    2,\n    3\n  ]\n}\n');
+    expect(removeElement(text, false, "/a", 1)).toBe('{\n  "a": [\n    1,\n    3\n  ]\n}\n');
+    expect(removeElement(text, false, "/a", 2)).toBe('{\n  "a": [\n    1,\n    2\n  ]\n}\n');
+    expect(removeElement('{ "a": [1] }', false, "/a", 0)).toBe('{ "a": [] }');
+    expect(removeElement('{\n  "a": [\n    // kept\n    1\n  ]\n}', true, "/a", 0)).toBe('{\n  "a": [\n    // kept\n  ]\n}');
+    expect(read(setElement(text, false, "/a", 1, { b: true }))).toEqual({ a: [1, { b: true }, 3] });
+    expect(() => removeElement(text, false, "/a", 3)).toThrow(/no element 3/);
+  });
+});