@intentius/chant 0.94.0 → 0.95.1

package/src/op/steward.ts

@@ -55,9 +55,36 @@
  * (`workLease`, #2748): its leased steps get a worktree of their own on
  * `chant/work/<item>`. `declareSteward` refuses such an Op without the lease,
  * and a scheduled Op whose lease leaves the item to the run.
+ *
+ * ## Beside the turns
+ *
+ * An Op listed under `beside` (#2861) is the steward's too, but its runs are
+ * not turns. A build that takes half an hour would otherwise hold every other
+ * Op of the steward, converge included, for its whole length. The local
+ * operator starts a run of it as a `chant run <op>` process of its own, with
+ * `CHANT_STEWARD` set so the run is still the steward's, and goes on with its
+ * rounds. One run at a time: the run holds the Op's own lease
+ * (`refs/chant/lease/<op>`), renewed while it runs, and never the turn lease.
+ * The operator starts one on the Op's cron, when its `ready` step says there
+ * is work, or to resume a run of the steward's that waited on a question now
+ * answered (or a gate now approved).
+ *
+ * ```ts
+ * export const steward = declareSteward({
+ *   name: "box-steward",
+ *   ops: [converge, release],
+ *   beside: [{ op: dispatch, ready: shell("node ops/ready.mjs", { json: true }) }],
+ * });
+ * ```
+ *
+ * `ops` on the normalised declaration is every Op the steward runs, beside
+ * ones last, so a reader that only asks "whose Op is this" (discovery's
+ * two-writers check, `chant run`, `workspace status`) needs nothing new.
+ * `beside` names the ones that run beside the turns.
  */
 
-import type { OpConfig } from "./types";
+import type { ActivityStep, OpConfig } from "./types";
+import { collectStepOutputRefs } from "./step-output-ref";
 import { isValidCronExpression, cronSyntaxMessage } from "./cron";
 import { workLeaseNeedsRunItem, workLeaseProblems } from "./work-lease-decl";
 
@@ -83,11 +110,35 @@ export const STEWARD_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
  */
 export type StewardOpInput = OpConfig | { props: unknown };
 
+/**
+ * An Op that runs beside the steward's turns (#2861): the Op alone, or the
+ * Op with the step that says when there is work for it.
+ */
+export type StewardBesideInput = StewardOpInput | { op: StewardOpInput; ready?: ActivityStep };
+
+/** An Op that runs beside the steward's turns, normalised. */
+export interface StewardBeside {
+  /** The Op's name; its config is in the declaration's `ops`. */
+  readonly op: string;
+  /**
+   * The step the operator runs each round, while no run of the Op is in
+   * flight, to ask whether there is work: see {@link readinessKeys}. Null
+   * for an Op started only on its cron, to resume a run, or by hand.
+   */
+  readonly ready: ActivityStep | null;
+}
+
 export interface StewardDeclarationConfig {
   /** The steward's name. On Fountain, the Agent's and the Teammate's. */
   name: string;
   /** The Ops it runs. A scheduled one runs on its cron; any other runs when asked. */
   ops: StewardOpInput[];
+  /**
+   * Ops it runs beside its turns (#2861), each in a process of its own under
+   * the Op's own lease, so a long run holds none of `ops` up. See the module
+   * doc.
+   */
+  beside?: StewardBesideInput[];
   /** Where it runs. Default `local`. */
   form?: StewardFormSpec;
   /**
@@ -105,7 +156,13 @@ export interface StewardDeclarationConfig {
 export interface StewardDeclaration {
   readonly kind: typeof STEWARD_KIND;
   readonly name: string;
+  /** Every Op it runs: its turns' Ops, then those that run beside them. */
   readonly ops: readonly OpConfig[];
+  /**
+   * The Ops of `ops` that run beside its turns (#2861). Read it through
+   * {@link stewardBesideOf}: a declaration made by an older core has none.
+   */
+  readonly beside?: readonly StewardBeside[];
   readonly form: { readonly default: StewardForm; readonly environments: Readonly<Record<string, StewardForm>> };
   /** Brokered box capabilities its Ops use (#2726). Empty when it names none. */
   readonly capabilities: readonly string[];
@@ -140,11 +197,22 @@ export function normaliseStewardForm(steward: string, spec: StewardFormSpec | un
   return { default: checkForm(steward, spec.default, "form.default"), environments };
 }
 
+/** A `beside` entry's Op and ready step, whichever of the two forms it was given in. */
+function besideEntry(entry: StewardBesideInput): { op: OpConfig; ready: ActivityStep | null } {
+  const e = entry as { op?: unknown; ready?: ActivityStep; phases?: unknown; props?: unknown };
+  if (e && typeof e === "object" && e.op !== undefined && e.phases === undefined && e.props === undefined) {
+    return { op: stewardOpConfig(e.op as StewardOpInput), ready: e.ready ?? null };
+  }
+  return { op: stewardOpConfig(entry as StewardOpInput), ready: null };
+}
+
 /**
  * Declare a steward. Refuses what would make it more than one writer or a
  * promise it can't keep: an Op listed twice, a schedule whose overlap isn't
  * `skip` (a fire while a turn runs is dropped in both forms), a cron that
- * doesn't parse, and a name a lease ref can't hold.
+ * doesn't parse, and a name a lease ref can't hold. For an Op beside the
+ * turns (#2861), also a `ready` that is not one activity step, or that reads
+ * another step's output (it runs on its own, outside any run).
  */
 export function declareSteward(config: StewardDeclarationConfig): StewardDeclaration {
   const name = config.name;
@@ -153,7 +221,8 @@ export function declareSteward(config: StewardDeclarationConfig): StewardDeclara
       `Steward ${JSON.stringify(name)}: a steward's name is letters, digits, ".", "_" and "-", starting with a letter or digit`,
     );
   }
-  const ops = config.ops.map(stewardOpConfig);
+  const besides = (config.beside ?? []).map(besideEntry);
+  const ops = [...config.ops.map(stewardOpConfig), ...besides.map((b) => b.op)];
   const seen = new Set<string>();
   for (const op of ops) {
     if (!op || typeof op.name !== "string" || !Array.isArray(op.phases)) {
@@ -172,6 +241,22 @@ export function declareSteward(config: StewardDeclarationConfig): StewardDeclara
           `Name the item, candidates, or the step whose output picks it.`,
       );
     }
+    const beside = besides.find((b) => b.op === op);
+    if (beside?.ready) {
+      const ready = beside.ready;
+      if (!ready || ready.kind !== "activity" || typeof ready.fn !== "string") {
+        throw new Error(`Steward "${name}": op "${op.name}": ready is one activity step, such as shell("...", { json: true })`);
+      }
+      if (collectStepOutputRefs(ready.args ?? {}).length > 0) {
+        throw new Error(`Steward "${name}": op "${op.name}": its ready step reads another step's output, and it runs outside any run`);
+      }
+      if (workLeaseNeedsRunItem(op)) {
+        throw new Error(
+          `Steward "${name}": op "${op.name}" is started when its ready step says so, but its workLease names no item, and such a run can't be given one. ` +
+            `Name the item, candidates, or the step whose output picks it.`,
+        );
+      }
+    }
     const schedule = op.schedule;
     if (!schedule) continue;
     if (!isValidCronExpression(schedule.cron)) {
@@ -199,6 +284,7 @@ export function declareSteward(config: StewardDeclarationConfig): StewardDeclara
     kind: STEWARD_KIND,
     name,
     ops: Object.freeze([...ops]),
+    beside: Object.freeze(besides.map((b) => Object.freeze({ op: b.op.name, ready: b.ready }))),
     form: normaliseStewardForm(name, config.form),
     capabilities: Object.freeze(capabilities),
     vault,
@@ -219,6 +305,52 @@ export function isStewardDeclaration(value: unknown): value is StewardDeclaratio
   );
 }
 
+/** The Ops a steward runs beside its turns (#2861); none for a declaration without the field. */
+export function stewardBesideOf(steward: StewardDeclaration): readonly StewardBeside[] {
+  return Array.isArray(steward.beside) ? steward.beside : [];
+}
+
+/** The entry for `op` when the steward runs it beside its turns (#2861), or undefined. */
+export function stewardBesideFor(steward: StewardDeclaration, op: string): StewardBeside | undefined {
+  return stewardBesideOf(steward).find((b) => b.op === op);
+}
+
+/** The Ops a steward runs as its turns, one at a time: `ops` without the beside ones. */
+export function stewardTurnOps(steward: StewardDeclaration): OpConfig[] {
+  const beside = new Set(stewardBesideOf(steward).map((b) => b.op));
+  return steward.ops.filter((op) => !beside.has(op.name));
+}
+
+/**
+ * What a `ready` step's result says (#2861): the work keys it names, or null
+ * when its result is not one of the shapes below. The value read is the
+ * result's `json` when it has one (a `shell` step with `json: true`), or the
+ * result itself.
+ *
+ * - an array: one key per entry (a string as is, anything else as its JSON);
+ *   empty means no work;
+ * - a non-empty string: one key; `""` means no work;
+ * - `true` means work, with no key; `false` and `null` mean none.
+ *
+ * The operator starts a run when a key is one it has not started a run for
+ * yet, so a run that ends with the same work still ready is not started
+ * again for it. `true` has no key, so it starts a run whenever none is in
+ * flight.
+ */
+export function readinessKeys(result: unknown): { ready: boolean; keys: string[] } | null {
+  const value = result && typeof result === "object" && !Array.isArray(result) && "json" in result
+    ? (result as { json: unknown }).json
+    : result;
+  if (value === true) return { ready: true, keys: [] };
+  if (value === false || value === null || value === undefined) return { ready: false, keys: [] };
+  if (typeof value === "string") return value === "" ? { ready: false, keys: [] } : { ready: true, keys: [value] };
+  if (Array.isArray(value)) {
+    const keys = value.map((v) => (typeof v === "string" ? v : JSON.stringify(v)));
+    return { ready: keys.length > 0, keys };
+  }
+  return null;
+}
+
 /** The form a steward takes in `env` (`local` when none is named). */
 export function stewardFormFor(steward: StewardDeclaration, env: string = DEFAULT_STEWARD_ENV): StewardForm {
   return steward.form.environments[env] ?? steward.form.default;

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

@@ -0,0 +1,129 @@
+/**
+ * #2880: a box block declares its services. The declaration reads them, a
+ * `needs` naming no service of the block or forming a cycle, a name given
+ * twice and a second httpPort each fail the read (declaration-invalid), so
+ * `chant workspace check` fails with WSP001, and `readBoxServices` gives the
+ * list of the member a process runs in.
+ */
+
+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 { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "./checks";
+import { parseDeclaration, WorkspaceReadError } from "./declaration";
+import { readBoxServices } from "./box-services";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-box-services-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const declaration = (services: unknown[]) =>
+  JSON.stringify(
+    {
+      name: "acme",
+      schema: 1,
+      members: [
+        { name: "app", dir: "app", kind: "other", because: "the app" },
+        { name: "box", dir: "box", kind: "other", because: "the box's steward and its Ops", box: { services } },
+      ],
+    },
+    null,
+    2,
+  );
+
+const parse = (services: unknown[]) => parseDeclaration(declaration(services), "chant.workspace.json");
+
+/** The error a declaration's read fails with, as its code and message. */
+function readFailure(services: unknown[]): { code: string; message: string; line: number | undefined } {
+  try {
+    parse(services);
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return { code: err.code, message: err.message, line: err.location?.line };
+    throw err;
+  }
+  throw new Error("the declaration read");
+}
+
+const TWO = [
+  { name: "app", cmd: "${HOME}/box/run-app.sh", duration: "3s", health: "http://127.0.0.1:5173/health" },
+  { name: "hud", cmd: "${HOME}/box/run-daemon.sh", needs: ["app"], httpPort: 8080 },
+];
+
+describe("the services of a box block (#2880)", () => {
+  test("two services, one needing the other, read with every field", () => {
+    expect(parse(TWO).members[1].box?.services).toEqual([
+      { name: "app", cmd: "${HOME}/box/run-app.sh", needs: [], httpPort: null, duration: "3s", health: "http://127.0.0.1:5173/health", optional: false, pointer: "/members/1/box/services/0" },
+      { name: "hud", cmd: "${HOME}/box/run-daemon.sh", needs: ["app"], httpPort: 8080, duration: null, health: null, optional: false, pointer: "/members/1/box/services/1" },
+    ]);
+    expect(parseDeclaration(JSON.stringify({ name: "a", schema: 1, members: [{ name: "b", dir: "b", kind: "other", because: "x", box: {} }] }), "chant.workspace.json").members[0].box?.services).toEqual([]);
+  });
+
+  test("a needs naming no service of the block is declaration-invalid, at the entry", () => {
+    const f = readFailure([TWO[0], { ...TWO[1], needs: ["api"] }]);
+    expect(f.code).toBe("declaration-invalid");
+    expect(f.message).toBe(`member box's box service hud needs "api", which the block does not declare; declared services: app, hud`);
+  });
+
+  test("needs that form a cycle are declaration-invalid, and so is a service that needs itself", () => {
+    const cycle = readFailure([
+      { name: "a", cmd: "a", needs: ["c"] },
+      { name: "b", cmd: "b", needs: ["a"] },
+      { name: "c", cmd: "c", needs: ["b"] },
+    ]);
+    expect(cycle).toMatchObject({ code: "declaration-invalid", message: "member box's box services need each other in a cycle: a -> c -> b -> a" });
+    expect(readFailure([{ name: "a", cmd: "a", needs: ["a"] }]).message).toMatch(/cycle: a -> a$/);
+  });
+
+  test("a name given twice, and a second httpPort, are declaration-invalid", () => {
+    expect(readFailure([TWO[0], { ...TWO[0], cmd: "other" }])).toMatchObject({ code: "declaration-invalid", message: expect.stringMatching(/declares the service app twice; the first is at \/members\/1\/box\/services\/0/) });
+    expect(readFailure([{ ...TWO[0], httpPort: 5173 }, TWO[1]]).message).toMatch(/gives both app \(port 5173\) and hud \(port 8080\) an httpPort/);
+  });
+
+  test("the schema refuses a service with no cmd, an unknown field, a malformed duration or a health that is no URL", () => {
+    expect(readFailure([{ name: "app" }]).code).toBe("declaration-invalid");
+    expect(readFailure([{ ...TWO[0], restart: "always" }]).message).toMatch(/unknown field "restart"/);
+    expect(readFailure([{ ...TWO[0], duration: "3 seconds" }]).code).toBe("declaration-invalid");
+    expect(readFailure([{ ...TWO[0], health: "/health" }]).code).toBe("declaration-invalid");
+  });
+
+  test("chant workspace check passes the valid block and fails the invalid one with WSP001 declaration-invalid", async () => {
+    const good = repo({ "chant.workspace.json": declaration(TWO), "app/.keep": "", "box/.keep": "" });
+    expect((await runDeclarationChecks(good)).diagnostics.filter((d) => d.ruleId === "WSP001")).toEqual([]);
+    const bad = repo({ "chant.workspace.json": declaration([TWO[0], { ...TWO[1], needs: ["api"] }]), "app/.keep": "", "box/.keep": "" });
+    const found = (await runDeclarationChecks(bad)).diagnostics;
+    expect(found.map((d) => [d.ruleId, d.severity, d.code])).toEqual([["WSP001", "error", "declaration-invalid"]]);
+    expect(found[0].message).toMatch(/needs "api", which the block does not declare/);
+  });
+});
+
+describe("readBoxServices (#2880)", () => {
+  test("reads the services of the member whose directory holds the working directory", () => {
+    const root = repo({ "chant.workspace.json": declaration(TWO), "app/.keep": "", "box/ops/.keep": "" });
+    const read = readBoxServices(join(root, "box", "ops"));
+    expect(read.member).toBe("box");
+    expect(read.root).toBe(root);
+    expect(read.services.map((s) => [s.name, s.needs])).toEqual([["app", []], ["hud", ["app"]]]);
+  });
+
+  test("a member with no box block, a directory no member holds, and no workspace are errors", () => {
+    const root = repo({ "chant.workspace.json": declaration(TWO), "app/.keep": "", "box/.keep": "", "elsewhere/.keep": "" });
+    expect(() => readBoxServices(join(root, "app"))).toThrow(/member app \(app\) has no box block/);
+    expect(() => readBoxServices(join(root, "elsewhere"))).toThrow(/no member of the workspace/);
+    const none = repo({ "x/.keep": "" });
+    expect(() => readBoxServices(join(none, "x"))).toThrow(/no chant.workspace.json/);
+  });
+});

package/src/workspace/box-services.ts

@@ -0,0 +1,51 @@
+/**
+ * The services a box declares, read for the process that runs in the box
+ * (#2880).
+ *
+ * A box member's block in the declaration lists the services the box runs
+ * under its supervisor (`BoxService` in `declaration.ts`). The fly lexicon's
+ * `spriteServicesObserve`, `spriteServiceRestart` and `spriteApplyServices`
+ * take `box: true` to read that list instead of one passed to them: the list
+ * of the member whose directory holds the working directory. They import
+ * this module when they run, so it stays small: it finds the workspace root,
+ * reads the declaration from the working tree and picks the member.
+ */
+
+import { realpathSync } from "node:fs";
+import { relative } from "node:path";
+import { findWorkspaceRoot } from "../project-root";
+import { ownerOf, readDeclaration, WorkspaceReadError, type BoxService } from "./declaration";
+import { workingTree } from "./tree";
+
+export type { BoxService } from "./declaration";
+
+/** The box block's services, and whose they are. */
+export interface DeclaredBoxServices {
+  /** The workspace root, absolute. */
+  root: string;
+  /** The member whose directory holds the working directory. */
+  member: string;
+  /** In file order. */
+  services: BoxService[];
+}
+
+/**
+ * The services of the box block of the member whose directory holds `cwd`.
+ * Throws a {@link WorkspaceReadError} when there is no workspace or its
+ * declaration can't be read, and an Error when no member holds `cwd` or the
+ * member has no box block. A block with no `services` gives an empty list.
+ */
+export function readBoxServices(cwd: string = process.cwd()): DeclaredBoxServices {
+  const found = findWorkspaceRoot(cwd);
+  if (!found) {
+    throw new WorkspaceReadError("declaration-missing", `no chant.workspace.json or .jsonc between ${cwd} and the git root, so there is no box block to read services from`);
+  }
+  const root = realpathSync(found.dir);
+  const declaration = readDeclaration(workingTree(root));
+  const path = relative(root, realpathSync(cwd)).split("\\").join("/") || ".";
+  const owner = ownerOf(declaration, [], path);
+  if (!owner || !("member" in owner)) throw new Error(`no member of the workspace at ${root} holds ${cwd}, so there is no box block to read services from`);
+  const m = owner.member;
+  if (!m.box) throw new Error(`member ${m.name} (${m.dir}) has no box block in ${declaration.file}, so it declares no services`);
+  return { root, member: m.name, services: m.box.services };
+}

package/src/workspace/checks/boxes.test.ts

@@ -157,6 +157,7 @@ describe("the box block in the declaration", () => {
       pointer: "/members/0/box",
       isolation: null,
       intent: null,
+      services: [],
       capabilities: [
         { name: "fountain", broker: "lobby", scope: ["agent", "vault"], pointer: "/members/0/box/capabilities/0" },
         { name: "inference", broker: null, scope: [], pointer: "/members/0/box/capabilities/1" },

package/src/workspace/compose-graph.test.ts

@@ -17,6 +17,7 @@ const member = (name: string, dir: string): ComposedMember => ({
   reason: null,
   chant: "0.80.0",
   irVersion: 1,
+  live: false,
 });
 
 const web: GraphIR = {

package/src/workspace/compose-graph.ts

@@ -76,6 +76,17 @@ export interface ComposedMember {
   chant: string | null;
   /** The IR version the member printed; `null` when it printed none and was upgraded as version 1. */
   irVersion: number | null;
+  /** Whether the member was read with `--live` (#2875): its graph is the account as it stands, not its source. */
+  live: boolean;
+  /** For a live read, when the member's read finished, as an ISO time. */
+  readAt?: string;
+  /**
+   * Whether the per-member cache answered this read (#2876). Set on composed
+   * members by `chant workspace graph`.
+   */
+  cached?: boolean;
+  /** The member's stamp (#2876): what the cache keys the read on, or null when none could be taken. */
+  stamp?: string | null;
   /** Whole-read facts the member's IR carried (`meta`, `pipeline`), kept apart from the composed sections. */
   meta?: Record<string, unknown>;
   pipeline?: unknown;

package/src/workspace/composites.test.ts

@@ -113,7 +113,7 @@ describe("composites output schema", () => {
   test("lists exactly the reason and error codes the code can return", () => {
     expect(schema.$defs.reason.properties.code.enum).toEqual([...COMPOSITES_REASON_CODES]);
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...COMPOSITES_ERROR_CODES]);
-    expect(COMPOSITES_ERROR_CODES).toEqual(GRAPH_ERROR_CODES);
+    expect(COMPOSITES_ERROR_CODES).toEqual(GRAPH_ERROR_CODES.filter((c) => c !== "live-at-revision"));
     expect(schema.$defs.member.properties.reason.oneOf[1].properties!.code.enum).toEqual([...MEMBER_RUN_REASON_CODES]);
     expect(schema.$defs.member.properties.runtimeReasons.items.properties.code.enum).toEqual([...COMPOSITES_RUNTIME_REASON_CODES]);
     expect(schema.$defs.member.properties.environmentReasons.items.properties.code.enum).toEqual([...COMPOSITES_ENVIRONMENT_REASON_CODES]);

package/src/workspace/composites.ts

@@ -44,10 +44,10 @@ import type { CommandContext } from "../cli/registry";
 import { joinLabel, type JoinLabel } from "../join-key";
 import type { ComposedMember, MemberReason, WorkspaceGraph } from "./compose-graph";
 import { readMemberIr } from "./compose-graph";
-import { GRAPH_ERROR_CODES, workspaceGraph, type GraphQuery } from "./graph-cli";
+import { workspaceGraph, type GraphQuery } from "./graph-cli";
 import type { LinkRow } from "./links";
 import { emitDocument, type UnitResult } from "./member-commands";
-import { readerVersion, type ErrorLocation, type WorkspaceErrorCode } from "./declaration";
+import { readerVersion, WORKSPACE_ERROR_CODES, type ErrorLocation, type WorkspaceErrorCode } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import { componentEnvironments, ENVIRONMENT_REASON_CODES, memberEnvironments, readLedgerEnvironments, type ComponentEnvironment, type EnvironmentReason, type LedgerEnvironmentReader, type MemberEnvironments } from "./environments";
 import { componentRuntimes, readRuntimesIn, RUNTIME_REASON_CODES, type ComponentRuntime, type MemberRuntimes, type PluginLoader, type RuntimeReason } from "./runtimes";
@@ -58,8 +58,12 @@ export const COMPOSITES_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/w
 /** The read-contract version the document follows. */
 export const COMPOSITES_CONTRACT_VERSION = 1;
 
-/** Why the composites couldn't be read at all: the graph's codes. */
-export const COMPOSITES_ERROR_CODES = GRAPH_ERROR_CODES;
+/**
+ * Why the composites couldn't be read at all: the declaration's codes, as for
+ * the graph. The composites never read live, so the graph's own
+ * `live-at-revision` (#2875) can't reach them.
+ */
+export const COMPOSITES_ERROR_CODES = WORKSPACE_ERROR_CODES;
 
 /** Why the list is empty, or why no instance has a component. Closed: part of the read contract. */
 export const COMPOSITES_REASON_CODES = [
@@ -262,12 +266,15 @@ export async function workspaceComposites(
   const { loadPlugin, readLedgerEnvironments: readLedger = readLedgerEnvironments, ...graphQuery } = query;
   const { doc: graph, failed, components: runs } = await workspaceGraph({
     ...graphQuery,
+    // The composites read source only; a live flag never reaches the members.
+    ...(graphQuery.args ? { args: { ...graphQuery.args, live: false, overlay: false, traffic: undefined } } : {}),
     components: true,
     inTree: async (root, members) => {
       runtimes = await readRuntimesIn(root, members, loadPlugin);
     },
   });
-  if ("error" in graph) return { doc: { ...head, error: graph.error }, failed: true };
+  // With no live read, the graph fails only with a declaration code.
+  if ("error" in graph) return { doc: { ...head, error: { ...graph.error, code: graph.error.code as WorkspaceErrorCode } }, failed: true };
 
   const byMember = new Map((runs ?? []).map((r) => [r.unit.member, r]));
   const members: CompositesMember[] = [];

package/src/workspace/conformance/__fixture__/decisions/decision.kind.mjs

@@ -33,8 +33,10 @@ export const recordKind = {
   // (#2773): chant workspace check --changes reports change-out-of-scope.
   outOfScope: { field: "out_of_scope" },
   // Verdicts, and the field naming the decider, for each record's digest and
-  // quorum (#2671, #2672).
-  reviews: { field: "reviews", decider: "decided_by" },
+  // quorum (#2671, #2672). A decision becomes ratified only once its quorum
+  // is met: records new and amend refuse it below, and the digest leaves the
+  // state out, so ratifying keeps the verdicts counting (#2873).
+  reviews: { field: "reviews", decider: "decided_by", ratified: "ratified" },
   // records new --by and the MCP records-new tool's by name a proposal's
   // proposer here, apart from decided_by, which stays null until the
   // decision is decided (#2756).

package/src/workspace/declaration.schema.json

@@ -402,13 +402,20 @@
     },
     "box": {
       "type": "object",
-      "description": "The member is a box, or holds a box's declarations (#2726). A box holds no credential: each capability it needs outside itself is reached through a broker, a runtime such as a lobby or a door, which holds the credential and enforces the scope. chant workspace check fails when a file in the member's directory carries a literal secret (WSP121) and when a capability names no broker (WSP122). chant workspace status --json lists the capabilities, so a broker can read the scopes. Its host, slot, ports, state and cookies state the box's isolation (#2727): chant derives each value from the box's identity, its host, the member's name and its slot, and prints them in chant workspace status --json, so a runtime reads them instead of choosing its own. chant workspace check fails when two boxes on a host resolve to the same value (WSP123) and when a box hard-codes a machine path (WSP124). A member that builds the fountain lexicon's Box declares the callback token fountain gives its persistent sandbox as the capability fountain-callback, brokered by fountain, with scope owner, or chant workspace check fails (WSP125, #2780). Its intent names the decision record that says what the box is for (#2850): chant workspace status --json reports the record's state and answer, and chant workspace check fails when no decision record has the id (WSP126) and warns when the record constrains no member or path of this workspace (WSP127, #2857). Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
+      "description": "The member is a box, or holds a box's declarations (#2726). A box holds no credential: each capability it needs outside itself is reached through a broker, a runtime such as a lobby or a door, which holds the credential and enforces the scope. chant workspace check fails when a file in the member's directory carries a literal secret (WSP121) and when a capability names no broker (WSP122). chant workspace status --json lists the capabilities, so a broker can read the scopes. Its host, slot, ports, state and cookies state the box's isolation (#2727): chant derives each value from the box's identity, its host, the member's name and its slot, and prints them in chant workspace status --json, so a runtime reads them instead of choosing its own. chant workspace check fails when two boxes on a host resolve to the same value (WSP123) and when a box hard-codes a machine path (WSP124). A member that builds the fountain lexicon's Box declares the callback token fountain gives its persistent sandbox as the capability fountain-callback, brokered by fountain, with scope owner, or chant workspace check fails (WSP125, #2780). Its intent names the decision record that says what the box is for (#2850): chant workspace status --json reports the record's state and answer, and chant workspace check fails when no decision record has the id (WSP126) and warns when the record constrains no member or path of this workspace (WSP127, #2857). Its services list what the box runs under its supervisor (#2880), which the fly lexicon observes, restarts and applies through sprite-env, and which chant workspace status --json prints. Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
       "properties": {
         "intent": {
           "type": "string",
           "minLength": 1,
           "description": "The id of the decision record that says what the box is for (#2850), a record of a declared kind named decision. A new box starts as a question: the record is proposed with a null choice until the person who answers it decides it. The record constrains a member or path of this workspace, with member:<a member's name> or a path: entry at, above or inside a member's directory. It need not be this member: the intent can constrain the app the box runs when that app is another member (#2857). When it constrains this member, chant workspace graph --intent shows it for the box's files. Added by chant 0.94.0, so a declaration that uses it sets minReader to 0.94.0 or newer."
         },
+        "services": {
+          "type": "array",
+          "description": "The services the box runs under its supervisor, sprite-env on a sprite (#2880). Each name is given once, every needs entry names a service of this list, the needs form no cycle, and at most one service sets httpPort; a declaration that breaks one of these can't be read (declaration-invalid). The fly lexicon's spriteServicesObserve and spriteServiceRestart read the list with box: true, and spriteApplyServices with box: true creates and replaces the services through sprite-env. None when omitted. Added by chant 0.95.0, so a declaration that uses it sets minReader to 0.95.0 or newer.",
+          "items": {
+            "$ref": "#/$defs/boxService"
+          }
+        },
         "capabilities": {
           "type": "array",
           "description": "Each capability the box reaches outside itself, named once. None when omitted.",
@@ -481,6 +488,55 @@
       },
       "additionalProperties": false
     },
+    "boxService": {
+      "type": "object",
+      "description": "A service a box runs under its supervisor (#2880).",
+      "required": [
+        "name",
+        "cmd"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/$defs/kindName",
+          "description": "The service's name in the supervisor. Unique within the box."
+        },
+        "cmd": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The command the supervisor runs (sprite-env services create --cmd). ${HOME} and other ${VAR} references are expanded from the environment of the process that applies the list, so the declaration holds no machine path."
+        },
+        "needs": {
+          "type": "array",
+          "uniqueItems": true,
+          "description": "Names of services of the same box that start before this one (sprite-env services create --needs).",
+          "items": {
+            "$ref": "#/$defs/kindName"
+          }
+        },
+        "httpPort": {
+          "$ref": "#/$defs/port",
+          "description": "The port the supervisor routes the sprite's URL to (sprite-env services create --http-port). At most one service of a box sets it."
+        },
+        "duration": {
+          "type": "string",
+          "pattern": "^[0-9]+(\\.[0-9]+)?(ms|s|m)$",
+          "description": "How long the service must stay up after it is created or started, such as 3s (sprite-env services create --duration)."
+        },
+        "health": {
+          "type": "string",
+          "pattern": "^https?://",
+          "description": "A URL that answers 200 while the service works. spriteServicesObserve probes it, and spriteServiceRestart waits for it after a restart. Without it, the supervisor's state decides."
+        },
+        "optional": {
+          "type": "boolean",
+          "description": "True for a service something else creates by name, such as a site a release Op makes: spriteApplyServices creates it only when its only names it, and spriteServicesObserve skips it while the supervisor has no such service."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
     "capability": {
       "type": "object",
       "description": "A capability a box needs and does not hold the credential for, such as inference, fountain or a third-party API (#2726).",