@intentius/chant 0.94.0 → 0.95.0

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).",

package/src/workspace/declaration.ts

@@ -216,10 +216,37 @@ export interface BoxDeclaration {
    * proposed with no choice until the person who answers it decides it.
    */
   intent: string | null;
+  /**
+   * The services the box runs under its supervisor (sprite-env on a sprite),
+   * in file order, or empty when the block declares none (#2880). The fly
+   * lexicon's `spriteServicesObserve`, `spriteServiceRestart` and
+   * `spriteApplyServices` read them with `box: true`.
+   */
+  services: BoxService[];
   /** The block's JSON Pointer in the file, for messages. */
   pointer: string;
 }
 
+/** A service a box runs under its supervisor (#2880). */
+export interface BoxService {
+  /** Unique in the box. */
+  name: string;
+  /** The command the supervisor runs, as written: `${VAR}` references are left for the applying process to expand. */
+  cmd: string;
+  /** Names of services in the same block that start first. Empty when none. */
+  needs: string[];
+  /** The port the supervisor routes the sprite's URL to, or null. At most one service of a box sets it. */
+  httpPort: number | null;
+  /** How long the service must stay up after a create or start, such as `3s` (`sprite-env services create --duration`), or null for the supervisor's default. */
+  duration: string | null;
+  /** A URL that answers 200 while the service works, or null when the supervisor's state decides. */
+  health: string | null;
+  /** True: an apply creates it only when named, and an observer skips it while the supervisor has no such service. */
+  optional: boolean;
+  /** The entry's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
 /** What a box declares about its isolation (#2727): its identity on a host, and the names of what it needs kept apart. */
 export interface BoxIsolationDeclaration {
   host: string;
@@ -629,6 +656,9 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       if (first) throw new WorkspaceReadError("declaration-invalid", `member ${m.name}'s box lists the capability ${c.name} twice; the first is at ${first.pointer}`, at(`${c.pointer}/name`));
       seen.set(c.name, c);
     }
+    // Its services name each other only within the block, without a cycle (#2880).
+    const problem = m.box ? boxServicesProblem(m.name, m.box.services) : null;
+    if (problem) throw new WorkspaceReadError("declaration-invalid", problem.message, at(problem.pointer));
   }
 
   // A diagram name is given once across the declaration (#2764): a reader keys diagrams by name.
@@ -720,6 +750,7 @@ function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
     state?: Record<string, string>;
     cookies?: string[];
     intent?: string;
+    services?: { name: string; cmd: string; needs?: string[]; httpPort?: number; duration?: string; health?: string; optional?: boolean }[];
   };
   return {
     capabilities: (b.capabilities ?? []).map((c, i) => ({ name: c.name, broker: c.broker ?? null, scope: [...(c.scope ?? [])], pointer: `${pointer}/capabilities/${i}` })),
@@ -729,10 +760,83 @@ function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
         ? null
         : { host: b.host, slot: b.slot!, ports: { ...(b.ports ?? {}) }, state: { ...(b.state ?? {}) }, cookies: [...(b.cookies ?? [])] },
     intent: b.intent ?? null,
+    services: (b.services ?? []).map((s, i) => ({
+      name: s.name,
+      cmd: s.cmd,
+      needs: [...(s.needs ?? [])],
+      httpPort: s.httpPort ?? null,
+      duration: s.duration ?? null,
+      health: s.health ?? null,
+      optional: s.optional ?? false,
+      pointer: `${pointer}/services/${i}`,
+    })),
     pointer,
   };
 }
 
+/**
+ * The rules the schema can't say about a box's services (#2880), as a
+ * message and the pointer to show, or null when they hold: each name is
+ * given once, every `needs` names a service of the same block, the `needs`
+ * form no cycle, and at most one service sets `httpPort`. The fly lexicon
+ * checks a list it is handed inline with the same rules.
+ */
+export function boxServicesProblem(member: string, services: readonly BoxService[]): { message: string; pointer: string } | null {
+  const byName = new Map<string, BoxService>();
+  for (const s of services) {
+    const first = byName.get(s.name);
+    if (first) return { message: `member ${member}'s box declares the service ${s.name} twice; the first is at ${first.pointer}`, pointer: `${s.pointer}/name` };
+    byName.set(s.name, s);
+  }
+  let routed: BoxService | undefined;
+  for (const s of services) {
+    if (s.httpPort === null) continue;
+    if (routed) {
+      return {
+        message: `member ${member}'s box gives both ${routed.name} (port ${routed.httpPort}) and ${s.name} (port ${s.httpPort}) an httpPort, and the supervisor routes the sprite's URL to one service`,
+        pointer: `${s.pointer}/httpPort`,
+      };
+    }
+    routed = s;
+  }
+  for (const s of services) {
+    const j = s.needs.findIndex((n) => !byName.has(n));
+    if (j >= 0) {
+      const known = services.map((x) => x.name).join(", ");
+      return { message: `member ${member}'s box service ${s.name} needs ${JSON.stringify(s.needs[j])}, which the block does not declare; declared services: ${known}`, pointer: `${s.pointer}/needs/${j}` };
+    }
+  }
+  const cycle = serviceCycle(services);
+  if (cycle) {
+    const s = byName.get(cycle[0])!;
+    return { message: `member ${member}'s box services need each other in a cycle: ${cycle.join(" -> ")}`, pointer: `${s.pointer}/needs` };
+  }
+  return null;
+}
+
+/** The first cycle the services' `needs` form, as names ending where it starts, or null. */
+function serviceCycle(services: readonly { name: string; needs: readonly string[] }[]): string[] | null {
+  const byName = new Map(services.map((s) => [s.name, s]));
+  const state = new Map<string, "visiting" | "done">();
+  const visit = (name: string, trail: string[]): string[] | null => {
+    const st = state.get(name);
+    if (st === "done") return null;
+    if (st === "visiting") return [...trail.slice(trail.indexOf(name)), name];
+    state.set(name, "visiting");
+    for (const dep of byName.get(name)?.needs ?? []) {
+      const found = visit(dep, [...trail, name]);
+      if (found) return found;
+    }
+    state.set(name, "done");
+    return null;
+  };
+  for (const s of services) {
+    const found = visit(s.name, []);
+    if (found) return found;
+  }
+  return null;
+}
+
 /**
  * The hosts, already validated, with the rules the schema can't say (#2727):
  * host names are unique, a box's host is declared, its slot's block fits the