@intentius/chant 0.102.0 → 0.104.1

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

@@ -3,14 +3,19 @@
 //
 // 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>
+// 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. answer.schema.json is a copy of 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",

package/src/workspace/conformance/__writer_fixture__/answers/answer.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "urn:intentius:chant:point-answer:1",
   "title": "Decision point answer front matter",
-  "description": "The front matter of one answer to a decision point (ws-058, #2739), as `chant workspace points ask` and `points answer` write it into the records directory of a record kind with an `answers` block. One record per point, declaration and inputs: its id is the point's name and the first 12 hex digits of the inputs hash, so the same question is answered once. A table's answer is `answered`; a model's answer at or above its threshold is `proposed` until a person confirms it; a question no decider before the quorum answered is `escalated`, open for people. A workspace copies this file next to its answer kind, as reference-workspace/answers/ does. Values stay within what YAML and JSON share. Fields other than these must start with x-.",
+  "description": "The front matter of one answer to a decision point (ws-058, #2739), as `chant workspace points ask` and `points answer` write it into the records directory of a record kind with an `answers` block. One record per point, declaration and inputs: its id is the point's name and the first 12 hex digits of the inputs hash, so the same question is answered once. A table's answer is `answered`; a model's answer at or above its threshold is `proposed` until a person confirms it; a question no decider before the quorum answered is `escalated`, open for people. An answer never changes in place: `points retract` escalates the question to people again and moves the answer into `retractions` (#3351, ws-084). An ad-hoc point's answer keeps the question and candidates its ask gave as `asked`, and they are part of the inputs hash (#3403). A workspace copies this file next to its answer kind, as reference-workspace/answers/ does. Values stay within what YAML and JSON share. Fields other than these must start with x-.",
   "type": "object",
   "additionalProperties": false,
   "patternProperties": { "^x-": {} },
@@ -14,6 +14,21 @@
     "point_version": { "$ref": "#/definitions/sha256", "description": "sha256 of the point's declaration when it was asked. Editing the question or any decider changes it." },
     "question_type": { "enum": ["noul", "choice", "score"] },
     "candidates": { "type": "array", "minItems": 2, "items": { "type": ["string", "boolean"] }, "description": "The answers the question allowed: true and false, a choice's options, or a score's levels." },
+    "asked": {
+      "type": "object",
+      "description": "An ad-hoc point's question as its ask gave it (`points ask --candidates`, #3403): its text, and its criteria in the point's question type's shape, from which candidates come. People's answer is one of them.",
+      "required": ["question", "criteria"],
+      "properties": {
+        "question": { "type": "string", "minLength": 1 },
+        "criteria": {
+          "oneOf": [
+            { "type": "object", "minProperties": 2, "maxProperties": 255, "additionalProperties": { "type": "string" } },
+            { "type": "array", "minItems": 2, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
     "inputs": { "type": "object", "description": "The state the deciders saw, input name to value." },
     "inputs_hash": { "$ref": "#/definitions/sha256", "description": "sha256 of the point, its version and its inputs. The same hash is answered once." },
     "constrains": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "What the question is about, such as a work item's id." },
@@ -36,12 +51,20 @@
     "probabilities": { "$ref": "#/definitions/probabilities" },
     "confidence": { "$ref": "#/definitions/unit" },
     "threshold": { "$ref": "#/definitions/unit" },
+    "reason": { "type": "string", "minLength": 1, "description": "model: the model's own explanation of its answer, when the backend gave one (#3345). Kept when a person confirms the proposal; moved into the escalations as model_reason when people answer otherwise." },
     "escalations": {
       "type": "array",
       "description": "The deciders asked before the one that answered, or before the quorum, and why each did not answer.",
       "items": { "$ref": "#/definitions/escalation" }
     },
     "answered_by": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "The people who answered or confirmed it." },
+    "note": { "type": "string", "minLength": 1, "description": "What the people who answered wrote with their answer (`points answer --note`, #3351). Moved into the retraction when the answer is retracted." },
+    "relayed_by": { "type": "string", "minLength": 1, "description": "Who carried the answer to chant for the people in answered_by (`points answer --relayed-by`, #3402), such as a follower relaying a person's answer through hud. It does not count toward the quorum. Moved into the retraction as answer_relayed_by when the answer is retracted." },
+    "retractions": {
+      "type": "array",
+      "description": "Answers people took back, oldest first (`points retract`, #3351): each answer as it was, and who retracted it, when and why. A retracted question is escalated to people again.",
+      "items": { "$ref": "#/definitions/retraction" }
+    },
     "asked_on": { "$ref": "#/definitions/date" },
     "answered_on": { "$ref": "#/definitions/date" },
     "source": {
@@ -76,6 +99,22 @@
     "unit": { "type": "number", "minimum": 0, "maximum": 1 },
     "date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
     "probabilities": { "type": "object", "additionalProperties": { "$ref": "#/definitions/unit" } },
+    "retraction": {
+      "type": "object",
+      "required": ["answer", "decider", "by", "on"],
+      "properties": {
+        "answer": { "type": ["string", "boolean"], "description": "The answer retracted." },
+        "decider": { "type": "object", "required": ["kind"], "properties": { "kind": { "enum": ["table", "model", "quorum"] } }, "description": "Who gave it: the record's decider as it was." },
+        "answered_by": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "answered_on": { "$ref": "#/definitions/date" },
+        "answer_note": { "type": "string", "minLength": 1, "description": "The note the answer carried." },
+        "answer_relayed_by": { "type": "string", "minLength": 1, "description": "Who relayed the answer (#3402)." },
+        "by": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Who retracted it." },
+        "on": { "$ref": "#/definitions/date" },
+        "note": { "type": "string", "minLength": 1, "description": "Why it was retracted (`points retract --note`)." }
+      },
+      "additionalProperties": false
+    },
     "escalation": {
       "type": "object",
       "required": ["kind", "reason"],
@@ -87,7 +126,8 @@
         "answer": { "type": ["string", "boolean", "null"] },
         "probabilities": { "$ref": "#/definitions/probabilities" },
         "confidence": { "$ref": "#/definitions/unit" },
-        "threshold": { "$ref": "#/definitions/unit" }
+        "threshold": { "$ref": "#/definitions/unit" },
+        "model_reason": { "type": "string", "minLength": 1, "description": "model: the model's own explanation of the answer it gave, when the backend gave one (#3345). reason is why the decider did not answer." }
       },
       "additionalProperties": false
     }

package/src/workspace/conformance/__writer_fixture__/contracts/contract.kind.mjs

@@ -0,0 +1,37 @@
+// The contract record kind (#3148, ws-082), data only: no imports, no code.
+//
+// chant workspace records --kind design/contracts/contract.kind.mjs --current --json
+//
+// A contract is an acceptance criterion made formal: what a person can do,
+// the criteria a check proves, and the check itself, a file pinned by hash.
+// It is drafted, approved once its reviewers agree, and retired when nothing
+// should be built against it any more. Studio's factory builds work items
+// against approved contracts; a work kind links an item to its contract with
+// work.contract (#3147). Each check run's result is an evidence record
+// (../evidence/evidence.kind.mjs) that names the contract and its criteria.
+export const recordKind = {
+  name: "contract",
+  location: { dir: ".", match: "^C-[0-9]{3,}-.+\\.md$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:intentius:chant:contract:1", path: "contract.schema.json" },
+  idField: "id",
+  stateField: "state",
+  states: ["draft", "approved", "retired"],
+  // An approved contract changes only in its state, its check pins and its
+  // reviews: anything else is a new contract that supersedes it. A retired
+  // contract is final and sealed.
+  closedStates: ["retired"],
+  approval: { draft: 0, approved: 1, retired: 1 },
+  seal: { field: "closed_digest" },
+  // A bare id or a list of ids, as studio's contracts write it. A link takes
+  // effect from an approved or retired contract.
+  supersedes: { field: "supersedes" },
+  // The contract's checks, each a workspace file pinned by the hash of its
+  // bytes (#2549): records reports a check edited after it was pinned.
+  pins: { field: "checks" },
+  // Verdicts on the contract, given in a review session (whose subjects
+  // include this kind) or with records review, and who approved it.
+  reviews: { field: "reviews", decider: "approved_by" },
+  // records new --by names a draft's proposer here (#2756).
+  proposedBy: { field: "proposed_by" },
+};