@intentius/chant 0.93.0 → 0.95.0

package/src/workspace/checks/boxes.ts

@@ -37,11 +37,23 @@
  * imports `Box` from `@intentius/chant-lexicon-fountain` and calls it, read as
  * syntax and never run. Upstream, managoat/fountain#2497 asks for a way to run
  * a persistent agent with no callback token.
+ *
+ * WSP126 (`box-intent-unknown`) and WSP127 (`box-intent-unconstrained`), #2850,
+ * read the decision record a box block names as its intent (`box-intent.ts`).
+ * WSP126 fails when no record of a declared kind named decision has the id.
+ * WSP127 warns when the record's constrains names no member or path of this
+ * workspace at all: no `member:` entry for a declared member and no `path:`
+ * entry at, above or inside one's directory. It need not reach the box's own
+ * member: the decision an intent names can constrain the member whose app the
+ * box runs, on a workspace where the box block sits on a different member,
+ * the box's steward (studio's template, #2857). Both read the working
+ * tree's records, so neither runs under `--at`.
  */
 
 import * as ts from "typescript";
 import type { WorkspaceCheck, WorkspaceCheckContext, WorkspaceDiagnostic } from "../checks";
 import type { Member } from "../declaration";
+import { constrainsWorkspace } from "../box-intent";
 import type { ReasonCode } from "../reason-codes";
 import { joinPath, skippedDir, type WorkspaceTree } from "../tree";
 import { BOX_ISOLATION_CHECKS } from "./box-isolation";
@@ -53,11 +65,15 @@ export const BOX_FINDING_CODES = [
   "box-isolation-collision",
   "box-isolation-literal",
   "box-fountain-callback-undeclared",
+  "box-intent-unknown",
+  "box-intent-unconstrained",
 ] as const satisfies readonly ReasonCode[];
 
 export const WSP_BOX_CREDENTIAL = "WSP121";
 export const WSP_BOX_UNBROKERED = "WSP122";
 export const WSP_BOX_FOUNTAIN_CALLBACK = "WSP125";
+export const WSP_BOX_INTENT_UNKNOWN = "WSP126";
+export const WSP_BOX_INTENT_UNCONSTRAINED = "WSP127";
 
 /** The fountain lexicon's package, whose `Box` composite runs a persistent sandbox. */
 const FOUNTAIN_LEXICON = "@intentius/chant-lexicon-fountain";
@@ -439,4 +455,54 @@ export const BOX_CHECKS: readonly WorkspaceCheck[] = [
       return out;
     },
   },
+  {
+    id: WSP_BOX_INTENT_UNKNOWN,
+    name: "box-intent-unknown",
+    description: "The intent a box block names is the id of a decision record: a record of a declared kind named decision.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const i of ctx.facts?.boxIntents ?? []) {
+        if (i.record) continue;
+        out.push({
+          checkId: this.id,
+          severity: this.severity,
+          code: "box-intent-unknown",
+          message: `box-intent-unknown: member ${i.member}'s box names the intent ${i.id}, and ${i.why}; propose the decision with chant workspace records new, or fix the id`,
+          entity: i.member,
+          pointer: i.pointer,
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: WSP_BOX_INTENT_UNCONSTRAINED,
+    name: "box-intent-unconstrained",
+    description:
+      "The decision record a box names as its intent constrains a member or path of this workspace: member:<a declared member's name>, or a path: entry at, above or inside a declared member's directory. It need not be the box's own member: a box one member runs can be what a decision about another member constrains.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      const members = ctx.declaration.members;
+      for (const i of ctx.facts?.boxIntents ?? []) {
+        if (!i.record) continue;
+        if (i.record.constrains.some((c) => constrainsWorkspace(c, members))) continue;
+        out.push({
+          checkId: this.id,
+          severity: this.severity,
+          code: "box-intent-unconstrained",
+          message:
+            `box-intent-unconstrained: member ${i.member}'s box names the intent ${i.id} (${i.record.path}), whose constrains ` +
+            (i.record.constrains.length === 0 ? "is empty" : `names ${i.record.constrains.join(", ")}`) +
+            `, and none of it is a member or path of this workspace; add member:<name> for the member the intent is about, or a path: entry at, above or inside a member's directory`,
+          entity: i.member,
+          pointer: i.pointer,
+        });
+      }
+      return out;
+    },
+  },
 ];

package/src/workspace/checks.ts

@@ -33,6 +33,7 @@
  * | WSP121, WSP122 | boxes: no literal credential, every capability brokered (#2726) |
  * | WSP123, WSP124 | box isolation: no shared port, state path or cookie, no literal machine path (#2727) |
  * | WSP125 | boxes: a fountain Box declares the callback token fountain gives its sandbox (#2780) |
+ * | WSP126, WSP127 | box intent: the decision record a box names exists, and constrains a member or path of this workspace (#2850, #2857) |
  * | WSP131 to WSP133 | diagram artifacts: source and render exist, a recorded source hash still matches (#2764) |
  */
 
@@ -54,6 +55,7 @@ import { RECORD_CHECKS, type RecordFacts } from "./checks/records";
 import { BOX_CHECKS } from "./checks/boxes";
 import { DIAGRAM_CHECKS } from "./checks/diagrams";
 import { loadDeclaredKinds, type DeclaredKind } from "./declared-kinds";
+import { resolveBoxIntents, type ResolvedBoxIntent } from "./box-intent";
 
 /**
  * What the checks beyond the declaration read, gathered from the checkout
@@ -71,6 +73,8 @@ export interface WorkspaceFacts {
   records?: RecordFacts;
   /** The record kinds the declaration names, each loaded, or only looked for under `--at` (#2680). */
   declaredKinds?: readonly DeclaredKind[];
+  /** The decision record each box's intent names, read from the working tree (#2850). */
+  boxIntents?: readonly ResolvedBoxIntent[];
 }
 
 /** What every declaration check reads. */
@@ -469,7 +473,14 @@ export async function runDeclarationChecks(
   // The declared record kinds load from the working tree; under --at only whether each exists at the revision is checked (#2680).
   // A declared work kind's acceptance criteria are counted in the working tree too (#2772).
   const declaredKinds = options.gather === false ? undefined : await loadDeclaredKinds(declaration, tree, root, { load: !options.tree, acceptance: !options.tree });
-  const facts: WorkspaceFacts = { ...gathered, ...(options.records ? { records: options.records } : {}), ...(declaredKinds ? { declaredKinds } : {}) };
+  // A box's intent is read from the working tree's records, so not under --at (#2850).
+  const boxIntents = declaredKinds && !options.tree ? await resolveBoxIntents(declaration, root, declaredKinds) : undefined;
+  const facts: WorkspaceFacts = {
+    ...gathered,
+    ...(options.records ? { records: options.records } : {}),
+    ...(declaredKinds ? { declaredKinds } : {}),
+    ...(boxIntents ? { boxIntents } : {}),
+  };
   const ctx: WorkspaceCheckContext = { declaration, tree, groups, kinds: registry, kindProblems: problems, facts };
   const findings = runWorkspaceChecks(ctx);
   const { active, suppressed } = applyCheckSettings(declaration, findings);

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/decision-points.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/decision-points/v1/decision-points.schema.json",
   "title": "Decision points",
-  "description": "A workspace's decision points (ws-058, #2738): the recurring questions it asks of its own graph, declared as data in a JSON file that an answer record kind names in `answers.points`. Each point is a typed question (`noul`, `choice` with 2 to 255 options, or `score` with 2 to 10 ordered levels, the question types of the POST /v1/systemone wire format, #2491), the inputs it reads, each named as a read-contract output, and an ordered chain of deciders: `table` rows, `model` deciders with a backend, a pinned model id and a threshold, and a `quorum` of people, always last. Taken from chud's decision-points.schema.json; `boolean` is read as `noul`. What JSON Schema cannot say is checked in code (`points.ts`): an input's output is one the read contract has, a table row tests declared inputs and answers a candidate, a field belongs to its decider's kind, a model id is pinned rather than an alias, and the chain ends in its one quorum. Unknown fields are refused, except fields whose names start with x-.",
+  "description": "A workspace's decision points (ws-058, #2738): the recurring questions it asks of its own graph, declared as data in a JSON file that an answer record kind names in `answers.points`. Each point is a typed question (`noul`, `choice` with 2 to 255 options, or `score` with 2 to 10 ordered levels, the question types of the POST /v1/systemone wire format, #2491), the inputs it reads, each named as a read-contract output, and an ordered chain of deciders: `table` rows, `model` deciders with a backend, a pinned model id and a threshold, and a `quorum` of people, always last. What JSON Schema cannot say is checked in code (`points.ts`): an input's output is one the read contract has, a table row tests declared inputs and answers a candidate, a field belongs to its decider's kind, a model id is pinned rather than an alias, and the chain ends in its one quorum. Unknown fields are refused, except fields whose names start with x-.",
   "type": "object",
   "required": ["points"],
   "properties": {
@@ -44,7 +44,7 @@
       "type": "object",
       "required": ["type", "instructions", "criteria"],
       "properties": {
-        "type": { "enum": ["noul", "boolean", "choice", "score"], "description": "boolean is chud's name for noul, read as noul." },
+        "type": { "enum": ["noul", "choice", "score"] },
         "instructions": { "$ref": "#/$defs/text" },
         "criteria": {
           "description": "The candidates. noul: {true, false} descriptions. choice: option to description, 2 to 255 options. score: 2 to 10 ordered levels.",
@@ -54,7 +54,7 @@
       "additionalProperties": false,
       "allOf": [
         {
-          "if": { "properties": { "type": { "enum": ["noul", "boolean"] } } },
+          "if": { "properties": { "type": { "const": "noul" } } },
           "then": {
             "properties": {
               "criteria": {

package/src/workspace/declaration.schema.json

@@ -402,8 +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). 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.",
@@ -476,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

@@ -210,10 +210,43 @@ export interface BoxDeclaration {
   capabilities: BoxCapability[];
   /** The host and slot of the box's isolation, or null when the block declares none (#2727). The values are derived in `boxes.ts`. */
   isolation: BoxIsolationDeclaration | null;
+  /**
+   * The id of the decision record that says what the box is for, or null when
+   * the block names none (#2850). A box starts as a question: the record is
+   * 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;
@@ -623,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.
@@ -713,6 +749,8 @@ function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
     ports?: Record<string, number>;
     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}` })),
@@ -721,10 +759,84 @@ function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
       b.host === undefined
         ? 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

package/src/workspace/declared-kinds.test.ts

@@ -242,6 +242,32 @@ describe("records without --kind reads every declared kind (#2680)", () => {
     expect(await run(workspace(), "--current")).toBe(0);
     expect(out.filter((l) => l.includes("("))).toEqual(["decision (decisions/decision.kind.mjs)", "notes (design/notes/note.kind.mjs)"]);
   });
+
+  test("--at an unknown revision with --json prints the error document, not just text on stderr (#2860)", async () => {
+    const root = workspace();
+    expect(await run(root, "--at", "refs/heads/no-such-branch", "--json")).toBe(1);
+    expect(err).toEqual([]);
+    const printed = JSON.parse(out.join("\n"));
+    expectValid(printed);
+    expect(printed).toEqual({
+      $schema: recordsSchema.$id,
+      contract: 1,
+      error: { code: "revision-unknown", message: expect.stringContaining("refs/heads/no-such-branch") as unknown as string },
+    });
+
+    out.length = 0;
+    err.length = 0;
+    expect(await run(root, "--at", "refs/heads/no-such-branch")).toBe(1);
+    expect(out).toEqual([]);
+    expect(err.join("\n")).toContain("revision-unknown");
+  });
+
+  test("a declaration-level code the records schema doesn't carry, such as declaration-invalid, stays text-only even with --json (#2860)", async () => {
+    const root = repo({ "chant.workspace.json": decl(members(), { records: [{ kind: "a.kind.mjs", file: "b" }] }), "app/x": "", "design/x": "" });
+    expect(await run(root, "--json")).toBe(1);
+    expect(out).toEqual([]);
+    expect(err.join("\n")).toContain("declaration-invalid");
+  });
 });
 
 describe("records new, amend and review without --kind (#2680)", () => {