@intentius/chant 0.90.0 → 0.93.0

package/src/workspace/answers-ledger.ts

@@ -0,0 +1,118 @@
+/**
+ * Answer records held on the lifecycle ledger (#2786).
+ *
+ * A steward's writes never touch the checkout's index or working tree
+ * (`../op/steward.ts`): the working tree is the coding agent's. A decision
+ * point asked in a steward's turn still has to leave its question somewhere a
+ * person finds it after the turn ends, and an Op's leased worktree is removed
+ * with the run. So a question asked in a steward's turn is written to
+ * `chant/lifecycle`, beside the lease histories and run records, under
+ * `_answers/<kind name>/<id>.md` in the ledger of the member that owns the
+ * answer kind. The file is the same Markdown record the kind's directory
+ * would hold, and it is written with git plumbing, like every ledger write.
+ *
+ * Readers see the ledger's answers as if they sat in the kind's directory:
+ * {@link withLedgerAnswers} lays them over the working tree, so `points`,
+ * `points --open`, a later `points ask` of the same question and `points
+ * answer` all find them. A record on the ledger wins over a file of the same
+ * name in the tree, because the ledger copy is the one a steward rewrote.
+ * People's answer to a question held on the ledger is written back there, so
+ * answering through hud in a box does not touch the checkout either.
+ *
+ * `points --at <rev>` reads a revision of the working branch, which the
+ * ledger is not part of, so it lists the tree's records only.
+ */
+
+import { basename, dirname } from "node:path";
+import { fetchLifecycleStatus, ledgerDir, listFilesInDir, pushLifecycle, readBlobBySha, readPathSha, writeBlobToPath } from "../lifecycle/git";
+import type { RecordSource } from "./record-source";
+import { overlay } from "./records-write";
+
+/** The directory on `chant/lifecycle`, under the member's prefix, that holds answer records. */
+export const ANSWERS_LEDGER_DIR = "_answers";
+
+const BRANCH = "chant/lifecycle";
+
+/** One answer record on the ledger. */
+export interface LedgerAnswer {
+  /** Where the record reads as being: the kind's directory, from the repository root. */
+  path: string;
+  /** Where it is: `chant/lifecycle:<path on the branch>`, which `git show` reads. */
+  ledger: string;
+  text: string;
+  /** Its blob sha, for a compare-and-set rewrite. */
+  sha: string;
+}
+
+/** The answer records one kind holds on the ledger. */
+export interface LedgerAnswers {
+  /** Where the ledger is resolved from: the kind file's directory, so the member owning the kind owns its answers. */
+  cwd: string;
+  /** The directory on the branch, relative to the member's prefix. */
+  dir: string;
+  /** The kind's records directory, from the repository root. */
+  dirRel: string;
+  /** By the path each record reads as. */
+  byPath: Map<string, LedgerAnswer>;
+}
+
+/** The ledger directory of the kind named `kindName`. */
+export function answersLedgerDir(kindName: string): string {
+  return `${ANSWERS_LEDGER_DIR}/${kindName.replace(/[^A-Za-z0-9._-]/g, "_")}`;
+}
+
+function treePath(dirRel: string, name: string): string {
+  return dirRel === "." ? name : `${dirRel}/${name}`;
+}
+
+/**
+ * Read the answer records the kind at `kindFile` holds on the ledger. Empty
+ * when there are none, when there is no ledger branch, and outside a git
+ * repository.
+ */
+export async function readLedgerAnswers(kind: { file: string; name: string; dirRel: string }): Promise<LedgerAnswers> {
+  const cwd = dirname(kind.file);
+  const dir = answersLedgerDir(kind.name);
+  const out: LedgerAnswers = { cwd, dir, dirRel: kind.dirRel, byPath: new Map() };
+  try {
+    const names = (await listFilesInDir(dir, { cwd })).filter((n) => n.endsWith(".md"));
+    if (names.length === 0) return out;
+    const full = await ledgerDir(dir, { cwd });
+    for (const name of names) {
+      const sha = await readPathSha(dir, name, { cwd });
+      const text = sha ? await readBlobBySha(sha, { cwd }) : null;
+      if (sha === null || text === null) continue;
+      const path = treePath(kind.dirRel, name);
+      out.byPath.set(path, { path, ledger: `${BRANCH}:${full}/${name}`, text, sha });
+    }
+  } catch {
+    // No repository, or a member ledger that can't be placed: the tree's records are all there is.
+  }
+  return out;
+}
+
+/** `base` with each ledger answer at the path it reads as, over any file of the same name. */
+export function withLedgerAnswers(base: RecordSource, answers: LedgerAnswers): RecordSource {
+  let source = base;
+  for (const a of answers.byPath.values()) source = overlay(source, a.path, a.text);
+  return source;
+}
+
+/** Fetch `chant/lifecycle` before a ledger write when it fast-forwards, so a question another clone asked is found. Best effort. */
+export async function refreshLedger(kindFile: string): Promise<void> {
+  await fetchLifecycleStatus({ cwd: dirname(kindFile) }).catch(() => undefined);
+}
+
+/**
+ * Write the record read as `path` to the ledger, expecting the blob it had
+ * when it was read (`prior`, null for a new record), then push the branch.
+ * A changed blob throws `RefCASConflictError` from `../lifecycle/git`. The
+ * push is best effort: a question that did not reach the remote is still
+ * open here. Returns where the record went.
+ */
+export async function writeLedgerAnswer(answers: LedgerAnswers, path: string, text: string, message: string, prior: string | null): Promise<{ ledger: string; pushed: boolean }> {
+  const name = basename(path);
+  await writeBlobToPath(answers.dir, name, text, message, { cwd: answers.cwd, expectPriorPathSha: prior });
+  const pushed = await pushLifecycle({ cwd: answers.cwd }).catch(() => false);
+  return { ledger: `${BRANCH}:${await ledgerDir(answers.dir, { cwd: answers.cwd })}/${name}`, pushed };
+}

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

@@ -0,0 +1,261 @@
+/**
+ * Box isolation (#2727): hosts in the declaration and a host, slot, ports,
+ * state and cookies in a member's box block, the values derived from a box's
+ * identity, `chant workspace check`'s WSP123 and WSP124, and the resolved
+ * values in `chant workspace status --json`.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import { afterAll, describe, expect, test } from "vitest";
+import { boxCollisions, boxLiterals, resolveBoxes, stateRootLiteral, statePathLiteral } from "./box-isolation";
+import { runDeclarationChecks, WORKSPACE_CHECKS } from "./checks";
+import { DEFAULT_STATE_ROOT, parseDeclaration, WorkspaceReadError, type Declaration } from "./declaration";
+import { formatStatus, workspaceStatus } from "./status";
+import statusSchema from "./status.schema.json";
+
+const FILE = "chant.workspace.json";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+const local = { name: "local", ports: { from: 7100, to: 7999, perBox: 20 } };
+
+/** A box member, with the ports, hud state and cookies chaff's spec/box.ts and kernel/door.mjs hard-code today. */
+const chaffBox = (name: string, slot: number, extra: Record<string, unknown> = {}) => ({
+  name,
+  dir: `boxes/${name}`,
+  kind: "other",
+  because: "a planted box",
+  box: {
+    host: "local",
+    slot,
+    ports: { app: 0, door: 1, proxy: 2, inject: 3, ticker: 4, behold: 5, surface: 6, historian: 7 },
+    state: { HUD_IDENTITY_PATH: "hud/identity.json", HUD_DB_PATH: "hud/events.db", CHAFF_HUD_IDENTITY: "hud/identity.json" },
+    cookies: ["hud_session", "chaff_door"],
+    ...extra,
+  },
+});
+type BoxMember = ReturnType<typeof chaffBox>;
+
+const declaration = (members: BoxMember[], hosts: unknown[] = [local]) => ({ name: "lobby", schema: 1, members, hosts });
+
+/** A committed git repository holding the declaration, and a file in each member's directory. */
+function repo(value: ReturnType<typeof declaration>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-box-isolation-")));
+  scratch.push(root);
+  const files: Record<string, string> = { [FILE]: JSON.stringify(value, null, 2) };
+  for (const m of value.members) files[`${m.dir}/README.md`] = `# ${m.name}\n`;
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  const git = (args: string[]) =>
+    execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], { cwd: root, stdio: "ignore" });
+  git(["init", "-q", "-b", "main"]);
+  git(["add", "-A"]);
+  git(["commit", "-q", "-m", "init"]);
+  return root;
+}
+
+/** The box findings, less WSP009, which every member of kind other gets. */
+async function findings(root: string) {
+  const report = await runDeclarationChecks(root);
+  return { ...report, diagnostics: report.diagnostics.filter((d) => d.ruleId !== "WSP009") };
+}
+
+function parse(value: unknown, reader = "0.91.0"): Declaration {
+  return parseDeclaration(JSON.stringify(value, null, 2), FILE, reader);
+}
+
+function refusal(value: unknown): WorkspaceReadError {
+  try {
+    parse(value);
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return err;
+    throw err;
+  }
+  throw new Error("expected the declaration to be refused");
+}
+
+describe("hosts, and a box's isolation in its block (#2727)", () => {
+  test("are read, with the host's state root null when it is the default and no isolation without a host", () => {
+    const d = parse({ ...declaration([chaffBox("fern", 0)]), members: [chaffBox("fern", 0), { name: "plain", dir: "plain", kind: "other", because: "x", box: { capabilities: [] } }] });
+    expect(d.hosts).toEqual([{ name: "local", ports: { from: 7100, to: 7999, perBox: 20 }, stateRoot: null, pointer: "/hosts/0" }]);
+    expect(d.members[0].box?.isolation).toMatchObject({ host: "local", slot: 0, cookies: ["hud_session", "chaff_door"] });
+    expect(d.members[1].box?.isolation).toBeNull();
+    expect(parse({ name: "plain", schema: 1, members: [] }).hosts).toEqual([]);
+  });
+
+  test("a block with only a host, or only isolation, still reads: capabilities are optional", () => {
+    const d = parse(declaration([{ ...chaffBox("fern", 0), box: { host: "local", slot: 0 } } as BoxMember]));
+    expect(d.members[0].box).toMatchObject({ capabilities: [], isolation: { host: "local", slot: 0, ports: {}, state: {}, cookies: [] } });
+  });
+
+  test("the rules the schema can't say are read errors, each at its place", () => {
+    const cases: [unknown, string, RegExp][] = [
+      [declaration([chaffBox("fern", 0)], [local, local]), "name", /host name "local" is already used/],
+      [declaration([chaffBox("fern", 0, { host: "cloud" })]), "host", /names the host "cloud", which hosts does not declare; declared hosts: local/],
+      [declaration([chaffBox("fern", 45)]), "slot", /slot 45 on host local, which needs ports 8000 to 8019, past the end of the host's range \(7999\); the range holds 45 slots/],
+      [declaration([chaffBox("fern", 0, { ports: { app: 20 } })]), "app", /gives port app offset 20, and host local gives each box 20 ports \(offsets 0 to 19\)/],
+      [declaration([], [{ name: "local", ports: { from: 8000, to: 7000, perBox: 1 } }]), "ports", /starts at 8000, after its end 7000/],
+    ];
+    for (const [value, key, message] of cases) {
+      const err = refusal(value);
+      expect(err.code).toBe("declaration-invalid");
+      expect(err.message).toMatch(message);
+      expect(JSON.stringify(value, null, 2).split("\n")[err.location!.line - 1]).toContain(`"${key}"`);
+    }
+  });
+
+  test("the schema refuses an unknown field, a bad cookie name, a host without a slot and ports without a host", () => {
+    for (const bad of [
+      declaration([chaffBox("fern", 0, { stateDir: "/tmp/x" })]),
+      declaration([chaffBox("fern", 0, { cookies: ["hud session"] })]),
+      declaration([{ ...chaffBox("fern", 0), box: { host: "local" } } as BoxMember]),
+      declaration([{ ...chaffBox("fern", 0), box: { ports: { app: 0 } } } as BoxMember]),
+      declaration([], [{ name: "local", ports: { from: 0, to: 10, perBox: 1 } }]),
+    ]) {
+      expect(refusal(bad).code).toBe("declaration-invalid");
+    }
+  });
+});
+
+describe("the values derived from a box's identity", () => {
+  test("ports from the slot's block, state under <stateRoot>/<name>, cookies suffixed with the name", () => {
+    const [fern, moss] = resolveBoxes(parse(declaration([chaffBox("fern", 0), chaffBox("moss", 1)]))).map((b) => b.isolation);
+    expect(fern).toEqual({
+      host: "local",
+      slot: 0,
+      portRange: { from: 7100, to: 7119 },
+      ports: { app: 7100, door: 7101, proxy: 7102, inject: 7103, ticker: 7104, behold: 7105, surface: 7106, historian: 7107 },
+      stateDir: `${DEFAULT_STATE_ROOT}/fern`,
+      state: {
+        HUD_IDENTITY_PATH: "${XDG_STATE_HOME}/chant/boxes/fern/hud/identity.json",
+        HUD_DB_PATH: "${XDG_STATE_HOME}/chant/boxes/fern/hud/events.db",
+        CHAFF_HUD_IDENTITY: "${XDG_STATE_HOME}/chant/boxes/fern/hud/identity.json",
+      },
+      cookies: { hud_session: "hud_session_fern", chaff_door: "chaff_door_fern" },
+    });
+    expect(moss.portRange).toEqual({ from: 7120, to: 7139 });
+    expect(moss.ports.door).toBe(7121);
+    expect(moss.state.HUD_IDENTITY_PATH).toBe("${XDG_STATE_HOME}/chant/boxes/moss/hud/identity.json");
+    expect(moss.cookies.hud_session).toBe("hud_session_moss");
+  });
+
+  test("are the same for the same identity, whatever other boxes are declared or in what order", () => {
+    const alone = resolveBoxes(parse(declaration([chaffBox("moss", 3)])))[0].isolation;
+    const among = resolveBoxes(parse(declaration([chaffBox("zinnia", 7), chaffBox("moss", 3), chaffBox("fern", 0)])))[1].isolation;
+    expect(among).toEqual(alone);
+  });
+
+  test("a host's own state root is used, trailing slash or not", () => {
+    const [b] = resolveBoxes(parse(declaration([chaffBox("fern", 0)], [{ ...local, stateRoot: "${BOX_STATE}/" }])));
+    expect(b.isolation.stateDir).toBe("${BOX_STATE}/fern");
+    expect(b.isolation.state.HUD_DB_PATH).toBe("${BOX_STATE}/fern/hud/events.db");
+  });
+});
+
+describe("literal machine paths", () => {
+  test("a state root starts with an environment reference other than $HOME", () => {
+    expect(stateRootLiteral("${XDG_STATE_HOME}/chant/boxes")).toBeUndefined();
+    expect(stateRootLiteral("$XDG_STATE_HOME")).toBeUndefined();
+    expect(stateRootLiteral("${HOME}/alecraso/hud-live")).toMatch(/\$HOME/);
+    expect(stateRootLiteral("$HOME/.local/state")).toMatch(/\$HOME/);
+    expect(stateRootLiteral("/Users/alex/state")).toMatch(/environment reference/);
+    expect(stateRootLiteral("~/state")).toMatch(/environment reference/);
+    expect(stateRootLiteral("${XDG_STATE_HOME}/../x")).toMatch(/\.\./);
+  });
+
+  test("a state entry is relative to the box's state directory and stays in it", () => {
+    expect(statePathLiteral("hud/identity.json")).toBeUndefined();
+    expect(statePathLiteral("/Users/alex/.local/state/hud/identity.json")).toMatch(/absolute/);
+    expect(statePathLiteral("${HOME}/.local/state/hud/box-chaff/identity.json")).toMatch(/environment reference/);
+    expect(statePathLiteral("~/hud")).toMatch(/home/);
+    expect(statePathLiteral("../moss/hud/identity.json")).toMatch(/\.\./);
+    expect(statePathLiteral("C:\\state")).toMatch(/Windows/);
+  });
+});
+
+describe("chant workspace check: WSP123 and WSP124", () => {
+  test("are fixed errors in the catalog, with the names the issue gives them", () => {
+    const byId = Object.fromEntries(WORKSPACE_CHECKS.map((c) => [c.id, c]));
+    expect([byId.WSP123.name, byId.WSP123.severity, byId.WSP123.configurable]).toEqual(["box-isolation-collision", "error", false]);
+    expect([byId.WSP124.name, byId.WSP124.severity, byId.WSP124.configurable]).toEqual(["box-isolation-literal", "error", false]);
+  });
+
+  test("two boxes with distinct names and slots pass, and status --json shows their distinct values", async () => {
+    const root = repo(declaration([chaffBox("fern", 0), chaffBox("moss", 1)]));
+    const report = await findings(root);
+    expect(report.diagnostics).toEqual([]);
+    expect(report.ok).toBe(true);
+
+    const doc = await workspaceStatus({ cwd: root, env: "local" });
+    if ("error" in doc) throw new Error(doc.error.message);
+    const validate = new Ajv2020({ strict: true, allErrors: true }).compile(statusSchema);
+    expect(validate(doc), JSON.stringify(validate.errors)).toBe(true);
+    const [fern, moss] = doc.members.map((m) => m.box!.isolation!);
+    for (const what of ["ports", "state", "cookies"] as const) {
+      const a = new Set<unknown>(Object.values(fern[what]));
+      expect(Object.values(moss[what]).some((v) => a.has(v)), what).toBe(false);
+    }
+    expect(doc.members[0].box).toMatchObject({ capabilities: [], isolation: { ports: { door: 7101 } } });
+    expect(formatStatus(doc)).toContain("fern  local  0     7100-7119  ${XDG_STATE_HOME}/chant/boxes/fern");
+  });
+
+  test("two boxes on one host with the same port range and state root collide", async () => {
+    const report = await findings(repo(declaration([chaffBox("fern", 2), chaffBox("moss", 2)])));
+    expect(report.ok).toBe(false);
+    const found = report.diagnostics.filter((d) => d.ruleId === "WSP123");
+    // One finding per shared port; state and cookies stay apart, since the names differ.
+    expect(found).toHaveLength(8);
+    expect(found[0]).toMatchObject({ severity: "error", entity: "moss", code: "box-isolation-collision" });
+    expect(found[0].message).toBe(
+      "box-isolation-collision: fern.app and moss.app on host local resolve to the same port 7140; give each box on a host its own slot",
+    );
+  });
+
+  test("the same slot on two hosts is no collision: hosts share nothing", () => {
+    const hosts = [local, { ...local, name: "tailnet" }];
+    expect(boxCollisions(parse(declaration([chaffBox("fern", 0), chaffBox("moss", 0, { host: "tailnet" })], hosts)))).toEqual([]);
+  });
+
+  test("two ports in one box at one offset collide; two state entries naming one file do not", () => {
+    const d = parse(declaration([chaffBox("fern", 0, { ports: { app: 0, door: 0 } })]));
+    expect(boxCollisions(d).map((c) => [c.what, c.value, c.holders.map((h) => `${h.box}.${h.name}`)])).toEqual([["port", "7100", ["fern.app", "fern.door"]]]);
+  });
+
+  test("a state entry spelled into another box's directory collides with it, and is a literal", () => {
+    const d = parse(declaration([chaffBox("fern", 0), chaffBox("moss", 1, { state: { HUD_IDENTITY_PATH: "./../fern/hud/identity.json" } })]));
+    expect(boxLiterals(d).map((l) => l.pointer)).toEqual(["/members/1/box/state/HUD_IDENTITY_PATH"]);
+    const state = boxCollisions(d).filter((c) => c.what === "state");
+    expect(state.map((c) => [c.value, c.holders.map((h) => `${h.box}.${h.name}`)])).toEqual([
+      ["${XDG_STATE_HOME}/chant/boxes/fern/hud/identity.json", ["fern.HUD_IDENTITY_PATH", "moss.HUD_IDENTITY_PATH"]],
+    ]);
+  });
+
+  test("a hard-coded machine path in a host or a box is WSP124", async () => {
+    const hosts = [{ ...local, stateRoot: "${HOME}/alecraso/hud-live" }];
+    const report = await findings(repo(declaration([chaffBox("chaff", 0, { state: { HUD_IDENTITY_PATH: "${HOME}/.local/state/hud/box-chaff/identity.json" } })], hosts)));
+    expect(report.diagnostics.map((d) => [d.ruleId, d.entity ?? null, d.code])).toEqual([
+      ["WSP124", "chaff", "box-isolation-literal"],
+      ["WSP124", null, "box-isolation-literal"],
+    ]);
+    expect(report.diagnostics[1].message).toMatch(/^box-isolation-literal: host local's stateRoot "\$\{HOME\}\/alecraso\/hud-live" starts at \$HOME/);
+    expect(report.diagnostics[0].message).toMatch(
+      /^box-isolation-literal: member chaff's box gives state HUD_IDENTITY_PATH the path "\$\{HOME\}\/.local\/state\/hud\/box-chaff\/identity.json", which starts with an environment reference/,
+    );
+  });
+
+  test("a fixed box check can't be turned off", async () => {
+    const root = repo({ ...declaration([chaffBox("fern", 0), chaffBox("moss", 0)]), checks: { WSP123: "off" } } as ReturnType<typeof declaration>);
+    const ids = (await findings(root)).diagnostics.map((d) => d.ruleId);
+    expect(ids).toContain("WSP011");
+    expect(ids).toContain("WSP123");
+  });
+});

package/src/workspace/box-isolation.ts

@@ -0,0 +1,205 @@
+/**
+ * Box isolation (#2727): the ports, state paths and cookie names each box
+ * uses, derived from its identity and its host, never chosen by a runtime.
+ *
+ * A box is a member with a `box` block (#2726), and its name is the
+ * member's. A box's identity is its host, its name and its slot, from the
+ * block's `host` and `slot`. Everything else
+ * follows from those and the host's declaration, and nothing else goes in:
+ *
+ * - port `p` is `host.ports.from + slot * host.ports.perBox + offset(p)`;
+ * - the state directory is `<host.stateRoot>/<box name>`, and state entry
+ *   `k` is that directory joined with the entry's relative path;
+ * - cookie `c` is `<c>_<box name>`.
+ *
+ * So the same declaration gives the same values on every machine and every
+ * run, and adding or removing a box changes no other box's values. The state
+ * paths keep their environment reference (`${XDG_STATE_HOME}` by default):
+ * the runtime that sets them expands it on its machine, and chant never
+ * reads the machine.
+ *
+ * Distinct names on one host give distinct state paths and cookie names by
+ * construction (a member name has no `_`, so `<c>_<box>` splits one way).
+ * Ports are the only value two boxes can share: two boxes on one host with
+ * the same slot, or two ports in one box at the same offset. `chant
+ * workspace check` compares every value anyway (WSP123), so an entry whose
+ * path escapes its directory is caught too.
+ */
+
+import { DEFAULT_STATE_ROOT, type BoxIsolationDeclaration, type Declaration, type Host, type Member } from "./declaration";
+import { pointerToken } from "./jsonc";
+
+/** A box's isolation, resolved: what `chant workspace status --json` prints in the member's box block. */
+export interface ResolvedIsolation {
+  host: string;
+  slot: number;
+  /** The box's block of its host's range, inclusive. */
+  portRange: { from: number; to: number };
+  /** Each declared port's number, in file order. */
+  ports: Record<string, number>;
+  /** `<stateRoot>/<box name>`, with the environment reference unexpanded. */
+  stateDir: string;
+  /** Each declared state entry's path, under `stateDir`. */
+  state: Record<string, string>;
+  /** Each declared cookie's name for this box. */
+  cookies: Record<string, string>;
+}
+
+/** The host's state root as written, or the default. */
+export function stateRootOf(host: Host): string {
+  return host.stateRoot ?? DEFAULT_STATE_ROOT;
+}
+
+const trimSlash = (s: string) => s.replace(/\/+$/, "");
+
+/** Resolve the isolation of the box named `name` on its host. */
+export function resolveIsolation(name: string, box: BoxIsolationDeclaration, host: Host): ResolvedIsolation {
+  const first = host.ports.from + box.slot * host.ports.perBox;
+  const stateDir = `${trimSlash(stateRootOf(host))}/${name}`;
+  return {
+    host: box.host,
+    slot: box.slot,
+    portRange: { from: first, to: first + host.ports.perBox - 1 },
+    ports: Object.fromEntries(Object.entries(box.ports).map(([name, offset]) => [name, first + offset])),
+    stateDir,
+    state: Object.fromEntries(Object.entries(box.state).map(([name, path]) => [name, `${stateDir}/${path.replace(/^\.\/+/, "")}`])),
+    cookies: Object.fromEntries(box.cookies.map((c) => [c, `${c}_${name}`])),
+  };
+}
+
+/** A member whose box block declares its isolation, with it resolved. */
+export interface IsolatedBox {
+  member: Member;
+  isolation: ResolvedIsolation;
+}
+
+/** Every box that declares its isolation, resolved, in member order. The declaration read already checked each box's host exists. */
+export function resolveBoxes(declaration: Declaration): IsolatedBox[] {
+  const hosts = new Map(declaration.hosts.map((h) => [h.name, h]));
+  const out: IsolatedBox[] = [];
+  for (const m of declaration.members) {
+    const iso = m.box?.isolation;
+    if (iso) out.push({ member: m, isolation: resolveIsolation(m.name, iso, hosts.get(iso.host)!) });
+  }
+  return out;
+}
+
+// ── Literal machine paths (WSP124) ───────────────────────────────────────────
+
+const ENV_REF = /^\$(\{[A-Za-z_][A-Za-z0-9_]*\}|[A-Za-z_][A-Za-z0-9_]*)/;
+const HOME_REF = /^\$(\{HOME\}|HOME)(?![A-Za-z0-9_])/;
+
+/**
+ * Why a host's `stateRoot` is a literal machine path, or undefined when it is
+ * not. A state root starts with an environment reference the runtime expands,
+ * and that reference is not `$HOME`: a path under a home directory names one
+ * person's machine layout (`${HOME}/<user>/...`), where `${XDG_STATE_HOME}`
+ * names the place the machine keeps state.
+ */
+export function stateRootLiteral(root: string): string | undefined {
+  if (HOME_REF.test(root)) return "starts at $HOME, which names one person's machine layout; use ${XDG_STATE_HOME} or another variable the runtime sets";
+  if (!ENV_REF.test(root)) return "does not start with an environment reference such as ${XDG_STATE_HOME}, so it names one machine's layout";
+  if (root.split("/").includes("..")) return "has a .. segment";
+  return undefined;
+}
+
+/**
+ * Why a state entry's path is not one relative to the box's state directory,
+ * or undefined when it is: absolute, home-relative, starting with an
+ * environment reference, a Windows drive path, or with a `..` segment.
+ */
+export function statePathLiteral(path: string): string | undefined {
+  if (path.startsWith("/")) return "is absolute";
+  if (path.startsWith("~")) return "starts at a home directory";
+  if (path.startsWith("$")) return "starts with an environment reference";
+  if (/^[A-Za-z]:[\\/]/.test(path) || path.includes("\\")) return "is a Windows path";
+  if (path.split("/").includes("..")) return "has a .. segment, which leaves the box's state directory";
+  return undefined;
+}
+
+export interface BoxLiteral {
+  /** The box, or null for a host's state root. */
+  box: string | null;
+  message: string;
+  pointer: string;
+}
+
+/** Every literal machine path in the hosts and boxes. */
+export function boxLiterals(declaration: Declaration): BoxLiteral[] {
+  const out: BoxLiteral[] = [];
+  for (const h of declaration.hosts) {
+    if (h.stateRoot === null) continue;
+    const why = stateRootLiteral(h.stateRoot);
+    if (why) out.push({ box: null, message: `host ${h.name}'s stateRoot ${JSON.stringify(h.stateRoot)} ${why}`, pointer: `${h.pointer}/stateRoot` });
+  }
+  for (const m of declaration.members) {
+    for (const [name, path] of Object.entries(m.box?.isolation?.state ?? {})) {
+      const why = statePathLiteral(path);
+      if (why) {
+        out.push({
+          box: m.name,
+          message: `member ${m.name}'s box gives state ${name} the path ${JSON.stringify(path)}, which ${why}; state paths are relative to the box's state directory, which chant derives from the host's stateRoot and the member's name`,
+          pointer: `${m.box!.pointer}/state/${pointerToken(name)}`,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+// ── Collisions (WSP123) ──────────────────────────────────────────────────────
+
+export interface BoxCollision {
+  host: string;
+  what: "port" | "state" | "cookie";
+  /** The shared value. */
+  value: string;
+  /** Each holder as `<box>.<name>`, in declaration order. */
+  holders: { box: string; name: string; pointer: string }[];
+}
+
+/** Collapse `.`, `..` and repeated slashes, so two spellings of one path compare equal. */
+function normalizePath(path: string): string {
+  const out: string[] = [];
+  for (const seg of path.split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === ".." && out.length > 0 && out[out.length - 1] !== "..") out.pop();
+    else out.push(seg);
+  }
+  return (path.startsWith("/") ? "/" : "") + out.join("/");
+}
+
+/**
+ * Every value two holders on one host resolve to. Ports collide within a box
+ * too, since two listeners can't share a port; state entries in one box may
+ * name one file on purpose (a runtime and the door both reading hud's
+ * identity), and cookies are unique in a box by the schema.
+ */
+export function boxCollisions(declaration: Declaration): BoxCollision[] {
+  const resolved = resolveBoxes(declaration);
+  const seen = new Map<string, BoxCollision>();
+  const add = (host: string, what: BoxCollision["what"], value: string, box: string, name: string, pointer: string) => {
+    const key = `${host}\u0000${what}\u0000${value}`;
+    let c = seen.get(key);
+    if (!c) {
+      c = { host, what, value, holders: [] };
+      seen.set(key, c);
+    }
+    c.holders.push({ box, name, pointer });
+  };
+  for (const { member, isolation: r } of resolved) {
+    const at = member.box!.pointer;
+    const box = member.name;
+    for (const [name, port] of Object.entries(r.ports)) add(r.host, "port", String(port), box, name, `${at}/ports/${pointerToken(name)}`);
+    const files = new Set<string>();
+    for (const [name, path] of Object.entries(r.state)) {
+      const file = normalizePath(path);
+      if (files.has(file)) continue;
+      files.add(file);
+      add(r.host, "state", file, box, name, `${at}/state/${pointerToken(name)}`);
+    }
+    Object.entries(r.cookies).forEach(([name, cookie], i) => add(r.host, "cookie", cookie, box, name, `${at}/cookies/${i}`));
+  }
+  // A state file is counted once per box above, so two holders are two boxes.
+  return [...seen.values()].filter((c) => c.holders.length > 1);
+}

package/src/workspace/changes-cli.ts

@@ -0,0 +1,56 @@
+/**
+ * `chant workspace check --changes <base>..<head> [--work <id>] [--severity
+ * off|warn|fail] [--kind <kind file>...] [--json]` (#2773): the forward
+ * coverage check (`changes.ts`), printed as JSON with `--json` or as one line
+ * per changed path, then the findings.
+ */
+
+import { resolve } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { CHANGE_SEVERITIES, checkChanges, type ChangesDocument } from "./changes";
+import type { ChangeSeverity } from "./declaration";
+
+const USAGE = "chant workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]";
+
+type Result = Exclude<ChangesDocument, { error: unknown }>;
+
+/** One line per changed path, then the findings and a summary. */
+export function formatChanges(doc: Result): string {
+  const out: string[] = [];
+  const work = doc.work ? `, work item ${doc.work.record} in hand` : "";
+  out.push(`changes   ${doc.range.base.slice(0, 8)}..${doc.range.head.slice(0, 8)} (${doc.range.spec}), severity ${doc.severity}${work}`);
+  for (const p of doc.paths) {
+    const why =
+      p.status === "covered"
+        ? `by ${p.coveredBy.map((c) => `${c.record} (${c.entry})`).join(", ")}`
+        : p.status === "out-of-scope"
+          ? `by ${p.outOfScopeBy.map((c) => `${c.record} (${c.entry})`).join(", ")}`
+          : p.status === "ignored"
+            ? `by ${p.ignoredBy}`
+            : "";
+    out.push(`${p.status.padEnd(12)} ${p.change.padEnd(8)} ${p.path}${p.from ? ` (from ${p.from})` : ""}${why ? `; ${why}` : ""}`);
+  }
+  for (const f of doc.findings) out.push(`${f.severity === "fail" ? "error  " : "warning"}   ${f.code}: ${f.message}`);
+  const s = doc.summary;
+  out.push(`${s.paths} changed paths: ${s.covered} covered, ${s.uncovered} uncovered, ${s.outOfScope} out of scope, ${s.ignored} ignored, ${s.records} records; ${doc.findings.length} findings`);
+  return out.join("\n");
+}
+
+export async function runWorkspaceChanges(ctx: CommandContext, cwd: string): Promise<number> {
+  const { args } = ctx;
+  const severity = args.severity as ChangeSeverity | undefined;
+  if (severity !== undefined && !(CHANGE_SEVERITIES as readonly string[]).includes(severity)) {
+    console.error(formatError({ message: `--severity ${severity} is not off, warn or fail`, hint: USAGE }));
+    return 1;
+  }
+  const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined);
+  const { doc, failed } = await checkChanges({ cwd, range: args.changes!, kinds: kinds?.map((k) => resolve(k)), work: args.work, severity });
+  if (args.json || args.format === "json") console.log(JSON.stringify(doc, null, 2));
+  if ("error" in doc) {
+    console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    return 1;
+  }
+  if (!args.json && args.format !== "json") console.log(formatChanges(doc));
+  return failed ? 1 : 0;
+}