@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/checks.ts

@@ -45,7 +45,8 @@ import type { PostSynthDiagnostic } from "../lint/post-synth";
 import { readDeclaration, resolveGroups, WorkspaceReadError, type Declaration, type Entry, type ErrorLocation, type ResolvedGroup } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
-import { loadKindRegistry, probeKind, resolveKind, type KindLoadProblem, type KindRegistry } from "./kinds";
+import { loadKindRegistry, probeKind, resolveKind, resolveMemberFields, type KindLoadProblem, type KindRegistry } from "./kinds";
+import { coreClassRegistry, loadClassRegistry, unknownScopeClasses, type ClassRegistry } from "./principal-classes";
 import { gitTop, workingTree, type WorkspaceTree } from "./tree";
 import { LINK_CHECKS, linkTable } from "./checks/links";
 import type { LinkRow, LinkTableRow } from "./links";
@@ -89,6 +90,10 @@ export interface WorkspaceCheckContext {
   kinds: KindRegistry;
   /** Why some pinned kinds could not be read. */
   kindProblems: KindLoadProblem[];
+  /** The principal classes: the core four and those the pins supply (#3080). Without it, the core four. */
+  classes?: ClassRegistry;
+  /** Why some pinned principal classes could not be read (#3080). */
+  classProblems?: KindLoadProblem[];
   /** The facts gathered before the checks ran. */
   facts?: WorkspaceFacts;
 }
@@ -182,23 +187,41 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   {
     id: "WSP002",
     name: "kinds-unreadable",
-    description: "Every pinned package's kinds can be read: it is installed at the pinned version, and its ./workspace-kinds file is valid kind data.",
+    description: "Every pinned package's kinds and principal classes can be read: it is installed at the pinned version, its ./workspace-kinds file is valid kind data, and its ./workspace-principals file is valid class data.",
     severity: "error",
     configurable: false,
     check(ctx) {
-      return ctx.kindProblems.map((p) => ({ checkId: this.id, severity: this.severity, message: p.message, pointer: `/pins/${p.pin}` }));
+      // A pin that can't be read is a problem for both loaders; report it once.
+      const seen = new Set<string>();
+      return [...ctx.kindProblems, ...(ctx.classProblems ?? [])]
+        .filter((p) => {
+          const key = `${p.pin}\0${p.message}`;
+          if (seen.has(key)) return false;
+          seen.add(key);
+          return true;
+        })
+        .map((p) => ({ checkId: this.id, severity: this.severity, message: p.message, pointer: `/pins/${p.pin}` }));
     },
   },
   {
     id: "WSP003",
     name: "kind-unknown",
-    description: "Every member's kind is built in or supplied by a pinned package. Unknown kinds fail closed.",
+    description: "Every member's kind is built in or supplied by a pinned package, and so is every principal class writeScope names (#3080). Unknown kinds and classes fail closed.",
     severity: "error",
     configurable: false,
     check(ctx) {
-      return ctx.declaration.members
+      const members = ctx.declaration.members
         .filter((m) => ctx.kinds.get(m.kind) === undefined)
         .map((m) => entryFinding(this, m, "kind", `member ${m.name} has kind ${m.kind}, which no built-in kind or pinned package supplies; known kinds: ${ctx.kinds.names().join(", ")}`));
+      const classes = ctx.classes ?? coreClassRegistry();
+      const scope = unknownScopeClasses(ctx.declaration.writeScope, classes).map((c) => ({
+        checkId: this.id,
+        severity: this.severity,
+        message: `writeScope names the principal class ${c}, which no core class or pinned package supplies, so a writer judged human is refused with write-scope-class-unknown; known classes: ${classes.names().join(", ")}`,
+        entity: c,
+        pointer: `/writeScope/${pointerToken(c)}`,
+      }));
+      return [...members, ...scope];
     },
   },
   {
@@ -216,13 +239,20 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   {
     id: "WSP005",
     name: "kind-probe-failed",
-    description: "Every member's directory is what its kind reads, such as a chant config for a chant member.",
+    description: "Every member's directory is what its kind reads, such as a chant config for a chant member, and its fields are ones its kind declares, of the declared types (#3151).",
     severity: "error",
     configurable: true,
     check(ctx) {
-      return readableMembers(ctx)
+      const probes = readableMembers(ctx)
         .filter((m) => !probeKind(ctx.kinds.get(m.kind)!, ctx.tree, memberDir(m.dir)))
         .map((m) => entryFinding(this, m, "kind", `member ${m.name} (${m.dir}) is not ${ctx.kinds.get(m.kind)!.description}`));
+      // A member's fields (#3151): checked whether or not its directory exists, since they are the entry's own.
+      const fields = ctx.declaration.members.flatMap((m) =>
+        resolveMemberFields(ctx.kinds.get(m.kind), m.fields).problems.map((p) =>
+          entryFinding(this, m, p.path === "" ? "fields" : `fields/${p.path.split("/").map(pointerToken).join("/")}`, `member ${m.name}: ${p.message}`),
+        ),
+      );
+      return [...probes, ...fields];
     },
   },
   {
@@ -484,6 +514,7 @@ export async function runDeclarationChecks(
     return { file: display(location.file), diagnostics: [diagnostic], suppressed: [], links: [], ok: false };
   }
   const { registry, problems } = loadKindRegistry(declaration.pins, root);
+  const classes = loadClassRegistry(declaration.pins, root, { tree });
   const gathered = options.gather === false || options.tree ? {} : await gatherWorkspaceFacts(root, declaration, options);
   // 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).
@@ -497,7 +528,7 @@ export async function runDeclarationChecks(
     ...(boxIntents ? { boxIntents } : {}),
     ...(options.live && !options.tree ? { live: await gatherLiveLinkFacts(root, declaration, registry, options.live.env, options.live.onStderr) } : {}),
   };
-  const ctx: WorkspaceCheckContext = { declaration, tree, groups, kinds: registry, kindProblems: problems, facts };
+  const ctx: WorkspaceCheckContext = { declaration, tree, groups, kinds: registry, kindProblems: problems, classes: classes.registry, classProblems: classes.problems, facts };
   const findings = runWorkspaceChecks(ctx);
   const { active, suppressed } = applyCheckSettings(declaration, findings);
 

package/src/workspace/component-environments.test.ts

@@ -0,0 +1,105 @@
+/**
+ * #3153, ws-095: a component declares where each release goes, by
+ * environment (the runtime that hosts it, its URL, a custom domain and the
+ * git remote its lifecycle records go to), replacing studio's
+ * `studio.sites` key in delivery's chant.config.ts. The contract validates
+ * it, `chant graph --components` carries it, and `graph --composites` lists
+ * each environment with its site.
+ */
+
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { computeComponentGraph } from "../components/cli-support";
+import componentSchema from "../components/component.schema.json";
+import { componentEnvironments, memberEnvironments, type EnvironmentReason } from "./environments";
+import type { MemberRuntimes } from "./runtimes";
+
+const runtimes = (environments: MemberRuntimes["environments"], lexicons: string[] = []): MemberRuntimes => ({ lexicons, default: "local", reasons: [], environments });
+
+const SITES = [
+  { name: "prod", runtime: "local" },
+  { name: "fly", runtime: "fly", lifecycle: "origin", url: "https://shop.fly.dev", domain: "shop.example.com" },
+];
+
+describe("a component's environments in the contract (#3153)", () => {
+  const validate = new Ajv2020({ strict: false }).compile(componentSchema);
+  const base = { name: "app", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy" }] }] };
+
+  test("are optional, each a name with an optional runtime, url, domain and lifecycle", () => {
+    expect(validate(base)).toBe(true);
+    expect(validate({ ...base, environments: SITES })).toBe(true);
+  });
+
+  test("refuse an empty list, an entry with no name, a url that isn't http and a field nobody reads", () => {
+    expect(validate({ ...base, environments: [] })).toBe(false);
+    expect(validate({ ...base, environments: [{ runtime: "fly" }] })).toBe(false);
+    expect(validate({ ...base, environments: [{ name: "fly", url: "shop.fly.dev" }] })).toBe(false);
+    expect(validate({ ...base, environments: [{ name: "fly", region: "ams" }] })).toBe(false);
+  });
+});
+
+describe("chant graph --components carries them (#3153)", () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = join(tmpdir(), `chant-3153-${Date.now()}-${Math.random()}`);
+    await mkdir(dir, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("for a component that declares them, and not for one that doesn't", async () => {
+    await writeFile(
+      join(dir, "app.component.ts"),
+      `export const app = { name: "app", dependsOn: [], environments: ${JSON.stringify(SITES)}, deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy" }] }] };\n` +
+        `export const db = { name: "db", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy" }] }] };\n`,
+    );
+    const graph = await computeComponentGraph(dir);
+    expect(graph.success, graph.error).toBe(true);
+    expect(graph.environments).toEqual({ app: SITES });
+  });
+});
+
+describe("graph --composites lists each environment with the component's site (#3153)", () => {
+  test("an environment the config names takes the site, and the command runs on the site's runtime when the member hosts it", () => {
+    const member = memberEnvironments(runtimes(["prod", "fly"], ["fly"]), { envs: [], reason: null });
+    const envs = componentEnvironments("app", member, "local", SITES, ["fly"]);
+    expect(envs).toEqual([
+      { name: "local", default: true, source: "builtin", site: null, command: "chant run --components app" },
+      { name: "prod", default: false, source: "config", site: { runtime: "local", url: null, domain: null, lifecycle: null }, command: "chant run --components app --env prod" },
+      {
+        name: "fly",
+        default: false,
+        source: "config",
+        site: { runtime: "fly", url: "https://shop.fly.dev", domain: "shop.example.com", lifecycle: "origin" },
+        command: "chant run --components app --on fly --env fly",
+      },
+    ]);
+  });
+
+  test("a site whose runtime the member doesn't host runs on the default runtime", () => {
+    const member = memberEnvironments(runtimes(["fly"]), { envs: [], reason: null });
+    const fly = componentEnvironments("app", member, "local", SITES, []).find((e) => e.name === "fly")!;
+    expect(fly.command).toBe("chant run --components app --env fly");
+    expect(fly.site?.runtime).toBe("fly");
+  });
+
+  test("an environment only the component names is added when the config declares none, and left out with a reason when the config doesn't cover it", () => {
+    const open = memberEnvironments(runtimes([]), { envs: [], reason: null });
+    expect(componentEnvironments("app", open, "local", SITES).map((e) => `${e.name}:${e.source}`)).toEqual(["local:builtin", "prod:component", "fly:component"]);
+
+    const reasons: EnvironmentReason[] = [];
+    const closed = memberEnvironments(runtimes(["prod"]), { envs: [], reason: null });
+    expect(componentEnvironments("app", closed, "local", SITES, [], reasons).map((e) => e.name)).toEqual(["local", "prod"]);
+    expect(reasons).toEqual([{ code: "environments-component-undeclared", message: expect.stringMatching(/component app declares environment fly/) }]);
+  });
+
+  test("a pattern in the config covers a declared name", () => {
+    const member = memberEnvironments(runtimes(["pr-*"]), { envs: [], reason: null });
+    const envs = componentEnvironments("app", member, "local", [{ name: "pr-7", url: "https://pr-7.example.com" }]);
+    expect(envs.find((e) => e.name === "pr-7")).toMatchObject({ source: "component", site: { url: "https://pr-7.example.com" } });
+  });
+});

package/src/workspace/compose-graph.ts

@@ -29,6 +29,7 @@
  * `chant graph` itself is untouched: this is the only place members compose.
  */
 
+import type { FactoryView, ListingView } from "./box-factory";
 import type { Declaration } from "./declaration";
 import type { KindRegistry } from "./kinds";
 import { graphLinks, type LinkTableRow } from "./links";
@@ -93,6 +94,12 @@ export interface ComposedMember {
    * the outer `nodes` with `outer/inner/id` ids.
    */
   nested?: NestedWorkspace;
+  /**
+   * The factory and listing the member's box block declares (#3146, ws-077),
+   * read from the declaration at the revision read. Set by
+   * `chant workspace graph` on every member; null when the box declares neither.
+   */
+  box?: { factory: FactoryView | null; listing: ListingView | null } | 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.schema.json

@@ -227,7 +227,8 @@
                   "runtimes-config-unreadable",
                   "environments-none-declared",
                   "environments-ledger-undeclared",
-                  "environments-ledger-unreadable"
+                  "environments-ledger-unreadable",
+                  "environments-component-undeclared"
                 ]
               },
               "message": {
@@ -428,7 +429,7 @@
           }
         },
         "environments": {
-          "description": "The environments the component may deploy to with chant run --components --env in its member: local first, the default, then each name the member's chant.config.ts declares in environments (patterns left out), in config order, then each environment with a release ledger for the member on chant/lifecycle that the config covers, sorted. The component contract declares no environments.",
+          "description": "The environments the component may deploy to with chant run --components --env in its member: local first, the default, then each name the member's chant.config.ts declares in environments (patterns left out), in config order, then each environment with a release ledger for the member on chant/lifecycle that the config covers, sorted, then each environment only the component's own environments declare (#3153) that the config covers, in contract order. An environment the component declares carries its site.",
           "type": "array",
           "minItems": 1,
           "items": {
@@ -569,6 +570,7 @@
         "name",
         "default",
         "source",
+        "site",
         "command"
       ],
       "properties": {
@@ -584,9 +586,26 @@
           "enum": [
             "config",
             "ledger",
-            "builtin"
+            "builtin",
+            "component"
           ],
-          "description": "Where the name came from, the first of these that names it: config for the member's chant.config.ts environments, ledger for a release ledger on chant/lifecycle, builtin for local when neither names it."
+          "description": "Where the name came from, the first of these that names it: config for the member's chant.config.ts environments, ledger for a release ledger on chant/lifecycle, builtin for local when neither names it, and component for an environment only the component's own environments declare (#3153, added by chant 0.103.0)."
+        },
+        "site": {
+          "description": "Where a release of the component goes in this environment, as the component's environments declare it (#3153): the runtime that hosts it, the URL it answers on, a custom domain and the git remote its lifecycle records are pushed to, each null when not declared. Null when the component declares nothing for this environment. Added by chant 0.103.0.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["runtime", "url", "domain", "lifecycle"],
+              "properties": {
+                "runtime": { "type": ["string", "null"] },
+                "url": { "type": ["string", "null"] },
+                "domain": { "type": ["string", "null"] },
+                "lifecycle": { "type": ["string", "null"] }
+              }
+            }
+          ]
         },
         "command": {
           "type": "string",

package/src/workspace/composites.test.ts

@@ -61,7 +61,7 @@ const componentIr = (components: { name: string; composites?: string[]; archetyp
 const local = (name: string) => ({ name: "local", lexicon: null, default: true, command: `chant run --components ${name}` });
 
 /** The default environment, named by nothing but chant itself. */
-const localEnv = (name: string) => ({ name: "local", default: true, source: "builtin", command: `chant run --components ${name}` });
+const localEnv = (name: string) => ({ name: "local", default: true, source: "builtin", site: null, command: `chant run --components ${name}` });
 
 /**
  * app declares three instances and exports ImageUri; delivery links to it and
@@ -381,11 +381,11 @@ describe("the environments each component may deploy to (#2695)", () => {
     const g = result((await workspaceComposites({ cwd: declared() })).doc);
     expectValid(g);
     expect(g.components.find((c) => c.id === "jobs/queue-runner")!.environments).toEqual([
-      { name: "local", default: true, source: "builtin", command: "chant run --components queue-runner" },
-      { name: "staging", default: false, source: "config", command: "chant run --components queue-runner --env staging" },
-      { name: "prod", default: false, source: "config", command: "chant run --components queue-runner --env prod" },
+      { name: "local", default: true, source: "builtin", site: null, command: "chant run --components queue-runner" },
+      { name: "staging", default: false, source: "config", site: null, command: "chant run --components queue-runner --env staging" },
+      { name: "prod", default: false, source: "config", site: null, command: "chant run --components queue-runner --env prod" },
       // The pattern pr-* is no environment by itself, and it covers the ledger's pr-42.
-      { name: "pr-42", default: false, source: "ledger", command: "chant run --components queue-runner --env pr-42" },
+      { name: "pr-42", default: false, source: "ledger", site: null, command: "chant run --components queue-runner --env pr-42" },
     ]);
     const jobs = g.members.find((m) => m.name === "jobs")!;
     expect(jobs.environmentReasons).toEqual([{ code: "environments-ledger-undeclared", message: expect.stringContaining("retired") }]);
@@ -397,7 +397,7 @@ describe("the environments each component may deploy to (#2695)", () => {
     // delivery has no _members/delivery, so the flat staging ledger is its; its config declares nothing, so anything goes.
     expect(g.components.find((c) => c.id === "delivery/edge")!.environments).toEqual([
       localEnv("edge"),
-      { name: "staging", default: false, source: "ledger", command: "chant run --components edge --env staging" },
+      { name: "staging", default: false, source: "ledger", site: null, command: "chant run --components edge --env staging" },
     ]);
     expect(g.members.find((m) => m.name === "delivery")!.environmentReasons.map((r) => r.code)).toEqual(["environments-none-declared"]);
     expect(g.members.find((m) => m.name === "docs")!.environmentReasons).toEqual([]);
@@ -409,8 +409,8 @@ describe("the environments each component may deploy to (#2695)", () => {
     const g = result((await workspaceComposites({ cwd: root })).doc);
     expectValid(g);
     expect(g.components.find((c) => c.id === "jobs/queue-runner")!.environments).toEqual([
-      { name: "local", default: true, source: "config", command: "chant run --components queue-runner" },
-      { name: "prod", default: false, source: "config", command: "chant run --components queue-runner --env prod" },
+      { name: "local", default: true, source: "config", site: null, command: "chant run --components queue-runner" },
+      { name: "prod", default: false, source: "config", site: null, command: "chant run --components queue-runner --env prod" },
     ]);
     expect(g.members.find((m) => m.name === "jobs")!.environmentReasons).toEqual([]);
   });

package/src/workspace/composites.ts

@@ -49,6 +49,7 @@ import type { LinkRow } from "./links";
 import { emitDocument, type UnitResult } from "./member-commands";
 import { readerVersion, WORKSPACE_ERROR_CODES, type ErrorLocation, type WorkspaceErrorCode } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
+import type { ComponentEnvironmentDeclaration } from "../components/component";
 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";
 
@@ -109,7 +110,7 @@ export interface ComponentEntry {
   file: string | null;
   /** The runtimes it can deploy on: `local` first, then each hosting lexicon its member configures. */
   runtimes: ComponentRuntime[];
-  /** The environments it may deploy to: `local` first, then the config's, then the ledger's. */
+  /** The environments it may deploy to: `local` first, then the config's, then the ledger's, then the ones only the component declares, each with the site the component declares for it. */
   environments: ComponentEnvironment[];
 }
 
@@ -183,12 +184,22 @@ function readComponents(member: string, dir: string, run: UnitResult, runtimes:
       composites: composites && composites.length > 0 ? composites : null,
       file: file ? (dir === "." ? file : `${dir}/${file}`) : null,
       runtimes: componentRuntimes(n.id, runtimes),
-      environments: componentEnvironments(n.id, environments, runtimes?.default),
+      // The component's own environments (#3153): their sites, and any the member doesn't list; a reason lands on the member.
+      environments: componentEnvironments(n.id, environments, runtimes?.default, declaredEnvironments(attrs.environments), runtimes?.lexicons ?? [], environments?.reasons ?? []),
     });
   }
   return { components };
 }
 
+/** A component's declared environments from its IR attrs (#3153), keeping only well-formed entries. */
+function declaredEnvironments(raw: unknown): ComponentEnvironmentDeclaration[] {
+  if (!Array.isArray(raw)) return [];
+  const text = (v: unknown) => (typeof v === "string" && v.length > 0 ? v : undefined);
+  return raw
+    .filter((e): e is Record<string, unknown> => e !== null && typeof e === "object" && typeof (e as Record<string, unknown>).name === "string")
+    .map((e) => ({ name: e.name as string, runtime: text(e.runtime), url: text(e.url), domain: text(e.domain), lifecycle: text(e.lifecycle) }));
+}
+
 /** The composite instances in a composed graph, without their components. */
 export function compositeInstances(graph: Pick<WorkspaceGraph, "nodes">): CompositeInstanceRow[] {
   const byId = new Map<string, { member: string; kinds: Set<string>; lexicons: Set<string>; nodes: string[] }>();

package/src/workspace/conformance/__fixture__/decisions/decision.schema.json

@@ -233,12 +233,12 @@
       "pattern": "^sha256:[0-9a-f]{64}$"
     },
     "constrains": {
-      "description": "What this decision governs: issues (owner/repo#n), other decisions (their ids), workspace members (member:<name>) or files and directories in the workspace (path:<path>, the grammar of an evidence path, #2549). At least one entry: a decision that governs nothing is refused.",
+      "description": "What this decision governs: issues (owner/repo#n), other decisions (their ids), workspace members (member:<name>), contracts (contract:<id>, #3148) or files and directories in the workspace (path:<path>, the grammar of an evidence path, #2549). At least one entry: a decision that governs nothing is refused.",
       "type": "array",
       "minItems": 1,
       "items": {
         "type": "string",
-        "pattern": "^([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+#[0-9]+|[a-z][a-z0-9]{0,15}-[0-9]{3,}|member:[a-z0-9][a-z0-9-]{0,39}|path:(?!/)(?!(?:[^/]*/)*\\.{1,2}(?:/|$))(?!.*//)[^\\\\\\u0000-\\u001f]*[^/\\\\\\u0000-\\u001f])$"
+        "pattern": "^([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+#[0-9]+|[a-z][a-z0-9]{0,15}-[0-9]{3,}|member:[a-z0-9][a-z0-9-]{0,39}|contract:[A-Za-z0-9][A-Za-z0-9._-]{0,99}|path:(?!/)(?!(?:[^/]*/)*\\.{1,2}(?:/|$))(?!.*//)[^\\\\\\u0000-\\u001f]*[^/\\\\\\u0000-\\u001f])$"
       }
     },
     "out_of_scope": {

package/src/workspace/conformance/__fixtures__/reference-broker.ts

@@ -0,0 +1,207 @@
+/**
+ * The reference broker (#3164, ws-097): the smallest broker of the broker
+ * protocol (`../broker-protocol.ts`) that passes the conformance suite
+ * (`./broker.ts`), serving all four standard capabilities. It keeps every
+ * report in memory and buffers each request, which a real broker should not;
+ * it exists to show the suite can be passed and what passing takes, and for
+ * a test to run a box against without studio's lobby.
+ *
+ * It is a test fixture and the package does not export it: chant never runs
+ * a broker or listens on a port (ws-052, ws-086), so it lives under
+ * `__fixtures__`, which test/no-listener.test.ts leaves out like a test file.
+ * `startReferenceBroker(env)` has the shape of the suite's `start`.
+ */
+
+import { randomBytes } from "node:crypto";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import {
+  BROKER_ROUTES,
+  DECLARATION_LIMITS,
+  declaredRefusal,
+  EGRESS_CAPABILITY,
+  FEEDBACK_CAPABILITY,
+  FOUNTAIN_CAPABILITY,
+  INFERENCE_CAPABILITY,
+  parseDeclarationReport,
+  formatPayerHeader,
+  PAYER_HEADER,
+  type BrokerPayer,
+  type KeptDeclaration,
+} from "../../broker-protocol";
+import type { BrokerConformanceEnv, StartedBroker } from "../broker";
+
+const MAX_BODY = 1024 * 1024;
+/** Request headers that describe the hop or carry the caller's credential. */
+const DROP = new Set(["host", "connection", "keep-alive", "content-length", "transfer-encoding", "authorization", "x-api-key", "cookie", "proxy-authorization", "te", "upgrade", "forwarded", "x-forwarded-for", "x-forwarded-host", "x-forwarded-proto", "x-real-ip"]);
+/** Response headers fetch has already undone. */
+const HOP = new Set(["connection", "keep-alive", "content-length", "content-encoding", "transfer-encoding"]);
+
+function send(res: ServerResponse, status: number, value: unknown, extra: Record<string, string> = {}): void {
+  res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store", ...extra });
+  res.end(JSON.stringify(value));
+}
+
+const refuse = (res: ServerResponse, status: number, message: string) => send(res, status, { error: { type: status === 403 ? "permission_error" : "invalid_request", message } });
+
+async function readBody(req: IncomingMessage): Promise<string | null> {
+  let raw = "";
+  for await (const chunk of req) {
+    raw += chunk;
+    if (raw.length > MAX_BODY) return null;
+  }
+  return raw;
+}
+
+/** The headers to forward, without the box's credential, plus `extra`. */
+function forwarded(req: IncomingMessage, extra: Record<string, string>): Record<string, string> {
+  const headers: Record<string, string> = {};
+  for (const [k, v] of Object.entries(req.headers)) if (!DROP.has(k) && v !== undefined) headers[k] = [v].flat().join(", ");
+  return { ...headers, ...extra };
+}
+
+async function relay(res: ServerResponse, answer: Response, swap?: [string, string], extra: Record<string, string> = {}): Promise<void> {
+  const headers: Record<string, string> = {};
+  answer.headers.forEach((v, k) => {
+    if (!HOP.has(k)) headers[k] = swap ? v.split(swap[0]).join(swap[1]) : v;
+  });
+  Object.assign(headers, extra);
+  res.writeHead(answer.status, headers);
+  res.end(Buffer.from(await answer.arrayBuffer()));
+}
+
+/** Start the reference broker for `env`, with a fresh token per box. */
+export async function startReferenceBroker(env: BrokerConformanceEnv): Promise<StartedBroker> {
+  const tokens: Record<string, string> = Object.fromEntries(env.boxes.map((b) => [b, `box_${randomBytes(32).toString("hex")}`]));
+  const boxOf = new Map(Object.entries(tokens).map(([box, token]) => [token, box]));
+  const reports = new Map<string, KeptDeclaration>();
+  const anthropic = new URL(env.anthropic.url);
+  // It spends the operator's one credential for every box, so the payer is shared (#3474), said on the report's answer and on each inference and decide answer.
+  const payer: BrokerPayer = { kind: "shared", principal: null };
+  const paid = { [PAYER_HEADER]: formatPayerHeader(payer) };
+  const fountain = new URL(env.fountain.url);
+
+  const tokenOf = (req: IncomingMessage): string | undefined => {
+    const bearer = /^Bearer\s+(\S+)$/i.exec(String(req.headers.authorization ?? ""))?.[1];
+    return bearer ?? (typeof req.headers["x-api-key"] === "string" ? req.headers["x-api-key"] : undefined);
+  };
+
+  const server = createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url ?? "/", "http://broker");
+      const path = url.pathname;
+      const method = req.method ?? "GET";
+      const token = tokenOf(req);
+      const box = token ? boxOf.get(token) : undefined;
+      const raw = await readBody(req);
+      if (raw === null) return refuse(res, 413, "The request is larger than 1 MB.");
+
+      if (path === BROKER_ROUTES.declaration) {
+        if (method !== "POST") return refuse(res, 405, `POST ${BROKER_ROUTES.declaration}`);
+        if (!box) return refuse(res, 403, "This token is no box this broker knows.");
+        if (raw.length > DECLARATION_LIMITS.bytes) return refuse(res, 413, "The declaration is larger than 32 KB.");
+        let body: unknown;
+        try {
+          body = JSON.parse(raw);
+        } catch {
+          return refuse(res, 400, "The body is not JSON.");
+        }
+        const parsed = parseDeclarationReport(body, env.broker);
+        if ("error" in parsed) return refuse(res, 400, parsed.error);
+        const kept: KeptDeclaration = { capabilities: parsed.capabilities, at: new Date().toISOString() };
+        reports.set(box, kept);
+        return send(res, 200, { ...kept, payer });
+      }
+
+      let body: unknown;
+      try {
+        body = raw ? JSON.parse(raw) : undefined;
+      } catch {
+        body = undefined;
+      }
+      const request = { method, path, body };
+      for (const spec of [INFERENCE_CAPABILITY, EGRESS_CAPABILITY, FEEDBACK_CAPABILITY, FOUNTAIN_CAPABILITY]) {
+        if (!spec.routes.some((r) => path === r || path.startsWith(`${r}/`))) continue;
+        const words = spec.scopes(request);
+        if (words === null) return refuse(res, 404, `This broker does not serve ${method} ${path}.`);
+        if (words.length === 0 && spec !== FEEDBACK_CAPABILITY) return send(res, 200, {});
+        if (!box) return refuse(res, spec === INFERENCE_CAPABILITY && path === BROKER_ROUTES.decide ? 401 : 403, "This request carried no token of a box this broker knows.");
+        if (words.length === 0) return refuse(res, 400, "A batch carries entries (scope agent), counts (scope passive), or both.");
+        for (const word of words) {
+          const refused = declaredRefusal(reports.get(box), env.broker, spec.name, word);
+          if (refused) return refuse(res, 403, refused);
+        }
+
+        if (spec === INFERENCE_CAPABILITY && path === BROKER_ROUTES.decide) return decide(res, body);
+        if (spec === INFERENCE_CAPABILITY) {
+          const rest = path.slice(BROKER_ROUTES.inference.length);
+          const answer = await fetch(new URL(`${rest}${url.search}`, anthropic), { method, headers: forwarded(req, { "x-api-key": env.anthropic.credential }), body: raw || undefined });
+          return relay(res, answer, undefined, paid);
+        }
+        if (spec === EGRESS_CAPABILITY) {
+          const [name] = words;
+          const secret = env.secrets.find((s) => s.box === box && s.name === name);
+          if (!secret) return refuse(res, 403, `This broker holds no value for ${name}.`);
+          const rest = path.slice(BROKER_ROUTES.egress.length + 1 + name.length) || "/";
+          // The box's token stands in for the value wherever the API expects its key, so it is swapped in every header.
+          const headers: Record<string, string> = {};
+          for (const [k, v] of Object.entries(req.headers)) if (v !== undefined && !HOP.has(k) && k !== "host") headers[k] = [v].flat().join(", ").split(token!).join(secret.value);
+          const search = url.search.split(token!).join(secret.value);
+          const answer = await fetch(new URL(`${rest}${search}`, secret.host), { method, headers, body: raw || undefined });
+          return relay(res, answer, [secret.value, token!]);
+        }
+        if (spec === FEEDBACK_CAPABILITY) return send(res, 202, { taken: true });
+        if (spec === FOUNTAIN_CAPABILITY) {
+          const rest = path.slice(BROKER_ROUTES.fountain.length);
+          const answer = await fetch(new URL(`${rest}${url.search}`, fountain), { method, headers: forwarded(req, { authorization: `Bearer ${env.fountain.credential}` }), body: raw || undefined });
+          return relay(res, answer);
+        }
+      }
+      if (path === BROKER_ROUTES.feedback) return refuse(res, 400, "A batch carries entries (scope agent), counts (scope passive), or both.");
+      return refuse(res, 404, "not found");
+    } catch (err) {
+      if (!res.headersSent) refuse(res, 502, `The broker could not answer: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  });
+
+  /** One Messages call per question, asking for JSON in a schema made from it, as studio's lobby does. */
+  async function decide(res: ServerResponse, body: unknown): Promise<void> {
+    const b = body as { model?: unknown; state?: unknown; questions?: Record<string, { type?: string; instructions?: string; criteria?: Record<string, string> }> } | undefined;
+    if (!b || typeof b.model !== "string" || b.state === undefined || !b.questions || typeof b.questions !== "object" || Object.keys(b.questions).length === 0) {
+      return refuse(res, 422, "The body is { model, state, questions } with at least one question.");
+    }
+    const answers: Record<string, unknown> = {};
+    for (const [name, q] of Object.entries(b.questions)) {
+      if (q.type !== "choice" && q.type !== "noul") {
+        answers[name] = { type: "unsupported" };
+        continue;
+      }
+      const options = q.type === "noul" ? ["true", "false"] : Object.keys(q.criteria ?? {});
+      const schema = {
+        type: "object",
+        properties: { reason: { type: "string" }, choice: { type: "string", enum: options }, probabilities: { type: "object", properties: Object.fromEntries(options.map((o) => [o, { type: "number" }])) } },
+        required: ["reason", "choice", "probabilities"],
+      };
+      const asked = await fetch(new URL("/v1/messages", anthropic), {
+        method: "POST",
+        headers: { "content-type": "application/json", "anthropic-version": "2023-06-01", "x-api-key": env.anthropic.credential },
+        body: JSON.stringify({ model: b.model, max_tokens: 1024, messages: [{ role: "user", content: `${name}: ${q.instructions}\n${JSON.stringify(b.state)}` }], output_config: { format: { type: "json_schema", schema } } }),
+      });
+      if (!asked.ok) return refuse(res, 502, `The model answered ${asked.status}.`);
+      const message = (await asked.json()) as { content?: { type: string; text?: string }[] };
+      const out = JSON.parse(message.content?.find((c) => c.type === "text")?.text ?? "{}") as { reason?: string; choice?: string; probabilities?: Record<string, number> };
+      const total = options.reduce((t, o) => t + Number(out.probabilities?.[o] ?? 0), 0) || 1;
+      const p = Object.fromEntries(options.map((o) => [o, Number(out.probabilities?.[o] ?? 0) / total]));
+      const reason = typeof out.reason === "string" ? { reason: out.reason } : {};
+      answers[name] = q.type === "noul" ? { type: "noul", noul: p.true, ...reason } : { type: "choice", choice: out.choice, probabilities: p, confidence: p[out.choice ?? ""] ?? 0, ...reason };
+    }
+    send(res, 200, { model: b.model, answers }, paid);
+  }
+
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
+  return {
+    url: `http://127.0.0.1:${(server.address() as AddressInfo).port}`,
+    tokens,
+    close: () => new Promise<void>((resolve) => server.close(() => resolve())),
+  };
+}

package/src/workspace/conformance/__writer_fixture__/answers/answer.kind.mjs

@@ -0,0 +1,32 @@
+// The answers to the workspace's decision points (ws-058, #2739), data only:
+// no imports, no code.
+//
+// chant workspace points --open --json
+// chant workspace points ask slice-tier --inputs inputs.json --subject W-002
+// chant workspace points answer <id> --answer medium --by <name> --note <text>
+// chant workspace points retract <id> --by <name> --note <why>
+// chant workspace points ask agent-question --inputs '{"ask.id":"req-1"}' --candidates question.json
+//
+// The points are declared in ../decisions/points.json: typed questions, the
+// read-contract outputs they read, and a table, model and quorum chain. Each
+// answer is one record here, named for the point and its inputs' hash, so the
+// same question is answered once. A table's answer is answered, a model's is
+// proposed until a person confirms it, and a question nobody before the
+// quorum answered is escalated to people. An answer never changes in place:
+// retracting it escalates the question again and keeps the answer in the
+// record's retractions (#3351). An ad-hoc point's question and candidates
+// come with each ask and stay in the record as asked (#3403). answer.schema.json is a copy of the
+// one @intentius/chant ships as workspace/point-answer.schema.json.
+export const recordKind = {
+  name: "answer",
+  location: { dir: ".", match: "^[a-z][a-z0-9-]*-[0-9a-f]{12}\\.md$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:intentius:chant:point-answer:1", path: "answer.schema.json" },
+  idField: "id",
+  stateField: "state",
+  states: ["escalated", "proposed", "answered"],
+  closedStates: ["answered"],
+  constrains: { field: "constrains" },
+  source: { field: "source" },
+  answers: { points: "../decisions/points.json" },
+};