@intentius/chant 0.90.0 → 0.91.0

package/src/op/work-lease-run.ts

@@ -0,0 +1,395 @@
+/**
+ * An Op run under a work item's lease (#2748, the Steward's gap 4 in #2731).
+ *
+ * An Op that declares `workLease` (`./types.ts`) runs its steps under the work
+ * lease of one work item (`../lifecycle/work-lease.ts`, ws-055). The local
+ * executor (`./local-executor.ts`) drives the {@link RunWorkLease} here:
+ *
+ * - Claim. Before the first step when the item is a literal or named by the
+ *   run (`chant run <op> --work <id>`); right after the producing step when
+ *   the item is a reference to a step's output. A list of candidates is tried
+ *   in order and the first one nobody holds is taken. When nothing can be
+ *   claimed the run ends `ok` with its remaining steps skipped, and the claim's
+ *   record carries the refusal, which names who holds the item.
+ * - Heartbeat. While the steps run, the lease is renewed every third of its
+ *   time to live, keeping its fencing token. A renewal the lease refuses (it
+ *   ran out and someone else claimed it, or it was released) means the lease
+ *   is lost: the in-flight step's abort signal fires, no further step starts,
+ *   and the run fails with `lease-lost`. A renewal that fails for any other
+ *   reason (the remote didn't answer) is retried at the next beat; if that
+ *   goes on past the expiry, the next renewal is refused and the lease is lost
+ *   then. These are the semantics of chud's dispatcher
+ *   (packages/runtime/src/dispatch.mjs), which this replaces.
+ * - Fence. Before the run's record is written, one last renewal checks that
+ *   the lease is still this run's, with the same token. Refused, the run is
+ *   recorded as failed with `lease-lost`, never as done.
+ * - Release. When the run ends, the lease is given back with the run's
+ *   outcome (`done`, `not_done`, `gated`, or the Op's own `outcome`), which
+ *   lands on `_leases/<id>.jsonl`. A lost lease is not released: it isn't
+ *   this run's to give back.
+ *
+ * Steps read the lease through {@link workLeaseOutput}: its item, holder,
+ * token and expiry, and for an Op that changes the checkout, the worktree and
+ * branch it works in. An activity that writes somewhere a token can fence
+ * (another ledger, a remote) passes the token along.
+ *
+ * ## Changing the checkout
+ *
+ * An Op with `changesCheckout` (applying a build, `chant workspace upgrade`)
+ * must declare `workLease`, and its leased steps get a git worktree of their
+ * own: `chant/work/<item>` checked out under the repository's git directory,
+ * from the checkout's HEAD, or from the branch as an earlier run left it. The
+ * worktree is removed when the run ends and the branch keeps whatever the
+ * steps committed, for the runner to deliver. The checkout a coding agent is
+ * editing, its index and its uncommitted files, are never touched.
+ */
+
+import { existsSync, rmSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { getRuntime } from "../runtime-adapter";
+import {
+  claimWorkLease,
+  DEFAULT_WORK_LEASE_TTL_MS,
+  releaseWorkLease,
+  renewWorkLease,
+  workLeaseRef,
+  WORK_ITEM_ID_PATTERN,
+  type WorkLease,
+} from "../lifecycle/work-lease";
+import { resolveMemberLedger } from "../lifecycle/member-ledger";
+import { currentHolderId } from "../lifecycle/lease";
+import { parseDuration } from "./duration";
+import { isStepOutputRef, stepOutput, type StepOutputRef } from "./step-output-ref";
+import { WORK_LEASE_STEP_ID, type OpConfig } from "./types";
+
+export { WORK_LEASE_STEP_ID } from "./types";
+export { workLeaseProblems, workLeaseNeedsRunItem } from "./work-lease-decl";
+
+/** Why a run under a work lease failed when the lease was lost: chud's reason, kept. */
+export const LEASE_LOST = "lease-lost";
+
+/** The branch prefix an Op that changes the checkout works on. */
+export const WORK_BRANCH_PREFIX = "chant/work/";
+
+/** What a run's steps read about its work lease, via {@link workLeaseOutput}. */
+export interface WorkLeaseOutput {
+  item: string;
+  holder: string;
+  /** The fencing token: the same for the whole run unless the lease is lost. */
+  token: string;
+  acquiredAt: string;
+  expiresAt: string;
+  /** The lease ref. */
+  ref: string;
+  /** For an Op that changes the checkout: the worktree its steps work in. Otherwise null. */
+  worktree: string | null;
+  /** For an Op that changes the checkout: the worktree's branch. Otherwise null. */
+  branch: string | null;
+}
+
+/** How a run's work lease ended, on `OpRunResult.workLease`. */
+export interface WorkLeaseRunResult {
+  /** The item claimed, or null when the run claimed nothing. */
+  item: string | null;
+  holder: string;
+  token: string | null;
+  /** The branch an Op that changes the checkout worked on, or null. */
+  branch: string | null;
+  /** Whether the lease was given back. False when it was lost, or never claimed. */
+  released: boolean;
+  /** The outcome the release recorded, or null when there was no release. */
+  outcome: string | null;
+  /** Why the lease was lost, or null when it wasn't. */
+  lost: string | null;
+  /** Why nothing was claimed, or null when something was. */
+  refusal: string | null;
+}
+
+/**
+ * A reference to the run's work lease, for a step's args:
+ * `workLeaseOutput("token")`, `workLeaseOutput("worktree")`, or the whole
+ * {@link WorkLeaseOutput} with no path.
+ */
+export function workLeaseOutput(path?: keyof WorkLeaseOutput): StepOutputRef {
+  return stepOutput(WORK_LEASE_STEP_ID, path);
+}
+
+/**
+ * The holder a steward's turn claims work leases as:
+ * `<steward>/<op>@<process>`. `chant workspace status --json` reads it back
+ * to show the lease a steward's current turn holds beside its Ops.
+ */
+export function stewardWorkHolder(steward: string, op: string, process: string = currentHolderId()): string {
+  return `${steward}/${op}@${process}`;
+}
+
+function resolvePath(value: unknown, path?: string): unknown {
+  if (!path) return value;
+  return path.split(".").reduce<unknown>((acc, key) => (acc == null ? acc : (acc as Record<string, unknown>)[key]), value);
+}
+
+async function git(args: string[], cwd: string): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+  const out = await getRuntime().spawn(["git", ...args], { cwd });
+  return { ok: out.exitCode === 0, stdout: out.stdout.trim(), stderr: out.stderr.trim() };
+}
+
+/** What a claim attempt came to, for the executor to record. */
+export type WorkClaimOutcome =
+  | { kind: "claimed"; lease: WorkLeaseOutput; tried: string[] }
+  /** Nothing to claim, or every candidate is held. `refusal` says which. */
+  | { kind: "unclaimed"; refusal: string; tried: string[] };
+
+export interface RunWorkLeaseOptions {
+  /** The project directory: where the run's ledger is, and what `workLease.kind` is relative to. */
+  cwd: string;
+  holder?: string;
+  /** The item the run names (`--work`), which takes the place of the Op's own. */
+  item?: string;
+  /** Called with a renewal's error that didn't lose the lease, which the next beat retries. */
+  onRenewError?: (message: string) => void;
+}
+
+/** One run's hold on one work item's lease. Created by the executor for an Op with `workLease`. */
+export class RunWorkLease {
+  readonly holder: string;
+  readonly ttlMs: number;
+  /** Aborts when the lease is lost, so the step in flight stops. */
+  readonly lostSignal: AbortSignal;
+  /** Set once the claim was made or given up on. */
+  attempted = false;
+  lease: WorkLeaseOutput | undefined;
+  refusal: string | undefined;
+  lost: string | undefined;
+
+  private readonly spec: NonNullable<OpConfig["workLease"]>;
+  private readonly abort = new AbortController();
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private beat: Promise<void> | undefined;
+
+  constructor(
+    private readonly config: Pick<OpConfig, "name" | "workLease" | "changesCheckout">,
+    private readonly opts: RunWorkLeaseOptions,
+  ) {
+    if (!config.workLease) throw new Error(`Op "${config.name}" declares no workLease`);
+    this.spec = config.workLease;
+    this.holder = opts.holder ?? currentHolderId();
+    this.ttlMs = this.spec.ttl ? parseDuration(this.spec.ttl) : DEFAULT_WORK_LEASE_TTL_MS;
+    this.lostSignal = this.abort.signal;
+  }
+
+  /** The directory whose ledger holds the lease: the kind file's, or the project's. */
+  private get ledgerCwd(): string {
+    const kind = this.spec.kind;
+    if (!kind) return this.opts.cwd;
+    const file = isAbsolute(kind) ? kind : resolve(this.opts.cwd, kind);
+    return resolve(file, "..");
+  }
+
+  /** Whether the claim is due at a step boundary, given the results so far. */
+  due(resultsById: ReadonlyMap<string, unknown>): boolean {
+    if (this.attempted) return false;
+    if (this.opts.item !== undefined) return true;
+    const item = this.spec.item;
+    return !isStepOutputRef(item) || resultsById.has(item.step);
+  }
+
+  /** The candidate ids, in order. Empty when the reference resolved to nothing. */
+  private candidates(resultsById: ReadonlyMap<string, unknown>): string[] {
+    if (this.opts.item !== undefined) return [this.opts.item];
+    const item = this.spec.item;
+    const value = isStepOutputRef(item) ? resolvePath(resultsById.get(item.step), item.path) : item;
+    if (value === undefined || value === null || value === "") return [];
+    const list = Array.isArray(value) ? value : [value];
+    return list.filter((v) => v !== undefined && v !== null && v !== "").map((v) => {
+      if (typeof v !== "string" || !WORK_ITEM_ID_PATTERN.test(v) || v.includes("..")) {
+        throw new Error(`Op "${this.config.name}": workLease.item resolved to ${JSON.stringify(v)}, which can't key a work lease`);
+      }
+      return v;
+    });
+  }
+
+  /**
+   * Claim the first candidate nobody holds. On a claim, the heartbeat starts,
+   * and for an Op that changes the checkout its worktree is made. Throws when
+   * the claim could not be made for a reason other than someone holding it
+   * (git failed): the run fails, as for any failing step.
+   */
+  async claim(resultsById: ReadonlyMap<string, unknown>): Promise<WorkClaimOutcome> {
+    this.attempted = true;
+    const tried = this.candidates(resultsById);
+    if (tried.length === 0) {
+      this.refusal = "nothing to claim: the work item resolved to no id";
+      return { kind: "unclaimed", refusal: this.refusal, tried };
+    }
+    const refused: string[] = [];
+    for (const id of tried) {
+      const result = await claimWorkLease(id, this.holder, { cwd: this.ledgerCwd, ttlMs: this.ttlMs, note: `op ${this.config.name}` });
+      if (!result.ok) {
+        refused.push(`${result.reason}: ${result.message}`);
+        continue;
+      }
+      const { prefix, members } = await resolveMemberLedger(this.ledgerCwd);
+      const lease: WorkLeaseOutput = {
+        ...pick(result.lease),
+        ref: workLeaseRef(id, prefix),
+        worktree: null,
+        branch: null,
+      };
+      this.lease = lease;
+      if (this.config.changesCheckout) {
+        try {
+          const made = await this.makeWorktree(id, members);
+          lease.worktree = made.worktree;
+          lease.branch = made.branch;
+        } catch (err) {
+          await releaseWorkLease(id, this.holder, { cwd: this.ledgerCwd, token: lease.token, outcome: "not_done", note: "the worktree could not be made" }).catch(() => undefined);
+          this.lease = undefined;
+          throw err;
+        }
+      }
+      this.startHeartbeat();
+      return { kind: "claimed", lease, tried };
+    }
+    this.refusal = refused.join("; ");
+    return { kind: "unclaimed", refusal: this.refusal, tried };
+  }
+
+  /**
+   * A worktree for `id` on `chant/work/[<member>/]<id>`, under the git
+   * directory so the checkout's own `git status` never lists it. Starts from
+   * the branch when an earlier run left it, from HEAD otherwise.
+   */
+  private async makeWorktree(id: string, members: readonly string[]): Promise<{ worktree: string; branch: string }> {
+    const cwd = this.opts.cwd;
+    const common = await git(["rev-parse", "--git-common-dir"], cwd);
+    if (!common.ok) throw new Error(`Op "${this.config.name}" changes the checkout, but ${cwd} is not a git checkout: ${common.stderr}`);
+    const commonDir = isAbsolute(common.stdout) ? common.stdout : resolve(cwd, common.stdout);
+    const scope = members.join("/");
+    const branch = `${WORK_BRANCH_PREFIX}${scope ? `${scope}/` : ""}${id}`;
+    const worktree = join(commonDir, "chant-work", ...members, id);
+    if (existsSync(worktree)) {
+      await git(["worktree", "remove", "--force", worktree], cwd);
+      rmSync(worktree, { recursive: true, force: true });
+    }
+    await git(["worktree", "prune"], cwd);
+    const exists = (await git(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], cwd)).ok;
+    const add = exists
+      ? await git(["worktree", "add", "--quiet", worktree, branch], cwd)
+      : await git(["worktree", "add", "--quiet", "-b", branch, worktree, "HEAD"], cwd);
+    if (!add.ok) throw new Error(`Op "${this.config.name}": could not make the worktree for ${id} on ${branch}: ${add.stderr}`);
+    return { worktree, branch };
+  }
+
+  private lose(why: string): void {
+    if (this.lost !== undefined) return;
+    this.lost = why;
+    this.stopHeartbeat();
+    this.abort.abort(new Error(`${LEASE_LOST}: ${why}`));
+  }
+
+  /** One renewal. Refused, the lease is lost; failed otherwise, the next beat retries. */
+  private async renew(): Promise<void> {
+    const lease = this.lease;
+    if (!lease || this.lost !== undefined) return;
+    try {
+      const result = await renewWorkLease(lease.item, this.holder, { cwd: this.ledgerCwd, ttlMs: this.ttlMs, token: lease.token });
+      if (result.ok) {
+        lease.expiresAt = result.lease.expiresAt;
+        return;
+      }
+      // The remote refusing the push is the lease held elsewhere only when it
+      // says who holds it; unreachable, the next beat tries again.
+      if (result.reason === "lease-push-rejected" && !result.heldBy) {
+        this.opts.onRenewError?.(result.message);
+        return;
+      }
+      if (result.reason === "lease-race") {
+        this.opts.onRenewError?.(result.message);
+        return;
+      }
+      this.lose(result.message);
+    } catch (err) {
+      this.opts.onRenewError?.(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  private startHeartbeat(): void {
+    const every = Math.max(1_000, Math.floor(this.ttlMs / 3));
+    this.timer = setInterval(() => {
+      if (this.beat) return;
+      this.beat = this.renew().finally(() => {
+        this.beat = undefined;
+      });
+    }, every);
+    (this.timer as { unref?: () => void }).unref?.();
+  }
+
+  private stopHeartbeat(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
+
+  /**
+   * The last renewal before the run's record is written, after the heartbeat
+   * stops. Returns whether the lease is still this run's.
+   */
+  async fence(): Promise<boolean> {
+    if (!this.lease) return this.lost === undefined;
+    this.stopHeartbeat();
+    await this.beat;
+    if (this.lost !== undefined) return false;
+    const lease = this.lease;
+    try {
+      const result = await renewWorkLease(lease.item, this.holder, { cwd: this.ledgerCwd, ttlMs: this.ttlMs, token: lease.token });
+      if (result.ok) lease.expiresAt = result.lease.expiresAt;
+      else this.lose(result.message);
+    } catch (err) {
+      this.lose(`the lease could not be renewed before the run was recorded: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return this.lost === undefined;
+  }
+
+  /**
+   * End the run's hold: stop the heartbeat, remove the worktree (the branch
+   * keeps what was committed), and give the lease back with the outcome
+   * unless it was lost.
+   */
+  async finish(status: "ok" | "fail" | "gated", resultsById: ReadonlyMap<string, unknown>): Promise<WorkLeaseRunResult> {
+    this.stopHeartbeat();
+    await this.beat;
+    const lease = this.lease;
+    const base: WorkLeaseRunResult = {
+      item: lease?.item ?? null,
+      holder: this.holder,
+      token: lease?.token ?? null,
+      branch: lease?.branch ?? null,
+      released: false,
+      outcome: null,
+      lost: this.lost ?? null,
+      refusal: this.refusal ?? null,
+    };
+    if (!lease) return base;
+    if (lease.worktree) {
+      await git(["worktree", "remove", "--force", lease.worktree], this.opts.cwd).catch(() => undefined);
+      rmSync(lease.worktree, { recursive: true, force: true });
+      await git(["worktree", "prune"], this.opts.cwd).catch(() => undefined);
+    }
+    if (this.lost !== undefined) return base;
+    let outcome = status === "ok" ? "done" : status === "gated" ? "gated" : "not_done";
+    if (status === "ok" && this.spec.outcome && isStepOutputRef(this.spec.outcome)) {
+      const declared = resolvePath(resultsById.get(this.spec.outcome.step), this.spec.outcome.path);
+      if (typeof declared === "string" && declared.trim() !== "") outcome = declared.trim();
+    }
+    const released = await releaseWorkLease(lease.item, this.holder, {
+      cwd: this.ledgerCwd,
+      token: lease.token,
+      outcome,
+      note: `op ${this.config.name}`,
+    }).catch(() => undefined);
+    return { ...base, released: released?.ok === true, outcome: released?.ok ? outcome : null };
+  }
+}
+
+function pick(lease: WorkLease): Omit<WorkLeaseOutput, "ref" | "worktree" | "branch"> {
+  return { item: lease.item, holder: lease.holder, token: lease.token, acquiredAt: lease.acquiredAt, expiresAt: lease.expiresAt };
+}

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