@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/plan-summary.schema.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/plan-summary/v1/plan-summary.schema.json",
+  "title": "plan summary",
+  "description": "The grouped plan summary (#3188): a change-set document's members, or one member's instances, grouped by their normalized changes, with every destroy, replacement, failure and hole by name. Written by `chant change-set summary --format json` and by groupChangeSet in @intentius/chant/plan-summary. Reviewers read it; no gate binds it. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version.",
+  "type": "object",
+  "required": ["$schema", "contract", "changeSet", "unit", "units", "groups", "failed", "destroys", "holes", "imports", "forgets", "sideEffects"],
+  "properties": {
+    "$schema": { "const": "https://intentius.io/chant/schemas/workspace/plan-summary/v1/plan-summary.schema.json" },
+    "contract": { "const": 1 },
+    "changeSet": {
+      "type": "string",
+      "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$",
+      "description": "The digest of the change-set document summarized."
+    },
+    "unit": {
+      "enum": ["member", "instance"],
+      "description": "member: each unit is a member of the document. instance: each unit is one resource instance of the document's one member."
+    },
+    "units": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Members, failed ones included, or the changing instances."
+    },
+    "groups": {
+      "type": "array",
+      "description": "Largest first. For instances, sorted by resource first.",
+      "items": { "$ref": "#/$defs/group" }
+    },
+    "failed": {
+      "type": "array",
+      "description": "Members that failed to plan. None is in a group.",
+      "items": {
+        "type": "object",
+        "required": ["member", "reason"],
+        "properties": {
+          "member": { "type": "string" },
+          "scope": { "type": "string" },
+          "reason": { "type": "string" }
+        }
+      }
+    },
+    "destroys": {
+      "type": "array",
+      "description": "Every delete and replace in the document, failed members' included, sorted by member and address.",
+      "items": { "$ref": "#/$defs/destroy" }
+    },
+    "imports": {
+      "type": "array",
+      "description": "Every entry that imports an object into state, sorted by member and address. An import is not a destroy.",
+      "items": { "$ref": "#/$defs/import" }
+    },
+    "forgets": {
+      "type": "array",
+      "description": "Every forget: the plan stops tracking the object and leaves it running. Never in destroys, and a destroy is never here.",
+      "items": { "$ref": "#/$defs/forget" }
+    },
+    "sideEffects": {
+      "type": "array",
+      "description": "Every provider-defined action an apply runs (Terraform actions blocks), sorted by member and address.",
+      "items": { "$ref": "#/$defs/sideEffect" }
+    },
+    "holes": {
+      "type": "array",
+      "description": "Every address a member's planner could not read.",
+      "items": {
+        "type": "object",
+        "required": ["member", "address", "reason"],
+        "properties": {
+          "member": { "type": "string" },
+          "address": { "type": "string" },
+          "type": { "type": "string" },
+          "reason": { "type": "string" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "action": { "enum": ["create", "update", "replace", "delete", "read", "no-op", "forget"] },
+    "import": {
+      "type": "object",
+      "required": ["member", "address", "type", "action"],
+      "properties": {
+        "member": { "type": "string" },
+        "address": { "type": "string" },
+        "type": { "type": "string" },
+        "action": { "$ref": "#/$defs/action", "description": "What else the plan does to the object; no-op when the import changes nothing." }
+      }
+    },
+    "forget": {
+      "type": "object",
+      "required": ["member", "address", "type"],
+      "properties": {
+        "member": { "type": "string" },
+        "address": { "type": "string" },
+        "type": { "type": "string" },
+        "deposed": { "type": "string" }
+      }
+    },
+    "sideEffect": {
+      "type": "object",
+      "required": ["member", "address", "type"],
+      "properties": {
+        "member": { "type": "string" },
+        "address": { "type": "string", "description": "The invocation's address, or its action type when the planner gives none." },
+        "type": { "type": "string" },
+        "trigger": { "type": "string", "description": "The resource whose lifecycle triggers it." },
+        "event": { "type": "string" }
+      }
+    },
+    "destroy": {
+      "type": "object",
+      "required": ["member", "address", "type", "action"],
+      "properties": {
+        "member": { "type": "string" },
+        "address": { "type": "string", "description": "The real address, never normalized." },
+        "type": { "type": "string" },
+        "action": { "enum": ["delete", "replace"] },
+        "deposed": { "type": "string" }
+      }
+    },
+    "change": {
+      "type": "object",
+      "required": ["line", "action", "count"],
+      "properties": {
+        "line": { "type": "string", "description": "The action's symbol, the normalized address and, for an update or replace, the attributes it writes. Values are never printed." },
+        "action": { "$ref": "#/$defs/action" },
+        "count": { "type": "integer", "minimum": 1, "description": "How many times one unit makes this change." },
+        "differsFrom": { "type": "string", "description": "The baseline group whose change at the same address and action this one differs from." },
+        "differsIn": { "type": "array", "items": { "type": "string" }, "description": "The attributes it differs in." }
+      }
+    },
+    "group": {
+      "type": "object",
+      "required": ["id", "units", "outlier", "noChanges", "changes", "destroys"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{12}$",
+          "description": "Twelve hex characters of computePlanDigest(\"plan-summary-group\", { resource, changes }) over the group's sorted normalized changes. The same change gets the same id in every run, so a report can link one group across commits. A change to the normalization rules can change it."
+        },
+        "resource": { "type": "string", "description": "For instance groups, the expansion: the address with its instance keys removed." },
+        "units": { "type": "array", "items": { "type": "string" }, "description": "Member names or instance addresses, sorted." },
+        "outlier": { "type": "boolean", "description": "A group of one beside other groups of the same expansion." },
+        "noChanges": { "type": "boolean" },
+        "changes": { "type": "array", "items": { "$ref": "#/$defs/change" } },
+        "extends": { "type": "string", "description": "The group whose whole change this one contains." },
+        "plus": { "type": "array", "items": { "$ref": "#/$defs/change" }, "description": "What it adds to that group's change." },
+        "destroys": { "type": "array", "items": { "$ref": "#/$defs/destroy" }, "description": "Every delete and replace a unit of this group makes. Each is also in the top-level destroys." },
+        "sideEffects": { "type": "array", "items": { "$ref": "#/$defs/sideEffect" }, "description": "Every triggered action a unit of this group runs." },
+        "provisional": { "const": true, "description": "Its units are provisional plans, planned before what they read applied. Part of the id, so they never share a group with real plans. Absent on a group of real plans." }
+      }
+    }
+  }
+}

package/src/workspace/point-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/points-cli.ts

@@ -11,7 +11,8 @@
  * can see it. With `--open`, only open questions are listed. It never writes
  * and never calls a model.
  *
- * `points ask` and `points answer` are the writes, in `decide.ts`.
+ * `points ask`, `points answer` and `points retract` are the writes, in
+ * `decide.ts`.
  */
 
 import { readFileSync } from "node:fs";
@@ -20,7 +21,7 @@ import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
 import { declaredRecordKinds, readDeclaration, readerVersion, WorkspaceReadError, type ErrorLocation, type WorkspaceErrorCode } from "./declaration";
 import { declaredKindFile } from "./declared-kinds";
-import { answerPoint, askPoint, questionView, POINTS_WRITE_CONTRACT_VERSION, POINTS_WRITE_SCHEMA_ID, type PointsWriteDocument, type QuestionView } from "./decide";
+import { answerPoint, askPoint, questionView, retractAnswer, POINTS_WRITE_CONTRACT_VERSION, POINTS_WRITE_SCHEMA_ID, type PointsWriteDocument, type PointsWriteVerb, type QuestionView } from "./decide";
 import { candidates, inputOutput, pointsFileOf, pointVersion, quorumOf, readPointsThrough, type Decider, type ModelAsk, type WireAnswer } from "./points";
 import type { ReasonCode } from "./reason-codes";
 import { gitRevisionSource, workingTreeSource } from "./record-source";
@@ -71,8 +72,14 @@ export interface PointView {
   questionType: string;
   instructions: string;
   candidates: (string | boolean)[];
-  /** What each candidate means, as the points file declares it: an object of strings for noul and choice, an array for score. */
+  /**
+   * What each candidate means, as the points file declares it: an object of
+   * strings for noul and choice, an array for score. Empty for an ad-hoc point,
+   * whose candidates come with each ask (#3403).
+   */
   criteria: Record<string, string> | string[];
+  /** The question's text and candidates come with each ask (#3403): each question lists them as `asked`. */
+  adhoc: boolean;
   /** Each input: its name, the read-contract output it names, and its description. */
   inputs: { name: string; output: string; description: string }[];
   deciders: Decider[];
@@ -164,8 +171,9 @@ export async function workspacePoints(query: PointsQuery): Promise<PointsDocumen
           version: pointVersion(p),
           questionType: p.question.type,
           instructions: p.question.instructions,
-          candidates: candidates(p.question),
-          criteria: p.question.criteria,
+          candidates: p.adhoc ? [] : candidates(p.question),
+          criteria: p.question.criteria ?? (p.question.type === "score" ? [] : {}),
+          adhoc: !!p.adhoc,
           inputs: Object.entries(p.inputs).map(([n, description]) => ({ name: n, output: inputOutput(n), description })),
           deciders: p.deciders,
           quorum: quorumOf(p),
@@ -215,7 +223,7 @@ export async function readQuestionStates(cwd: string): Promise<Map<string, Quest
 export function formatPoints(doc: Extract<PointsDocument, { points: unknown }>): string {
   const lines: string[] = [];
   for (const s of doc.sources) if (s.reason) lines.push(`${s.kind}: ${s.reason.code}: ${s.reason.message}`);
-  for (const p of doc.points) lines.push(`${p.name}  ${p.questionType}  ${p.title}  (${p.deciders.map((d) => d.kind).join(", ")})`);
+  for (const p of doc.points) lines.push(`${p.name}  ${p.questionType}${p.adhoc ? ", ad hoc" : ""}  ${p.title}  (${p.deciders.map((d) => d.kind).join(", ")})`);
   if (doc.points.length === 0) lines.push("no decision points are declared");
   lines.push("");
   for (const q of doc.questions) {
@@ -241,18 +249,23 @@ export function responseAsk(response: unknown): ModelAsk {
 
 const USAGE = [
   "chant workspace points [--open] [--kind <kind file>] [--at <rev>] [--json]",
-  "chant workspace points ask <point> --inputs <file|-> [--response <file>] [--subject <id>] [--kind <kind file>] [--dry-run]",
-  "chant workspace points answer <id> --answer <value> --by <name> [--by <name>...] [--kind <kind file>] [--dry-run]",
+  "chant workspace points ask <point> --inputs <file|-|json> [--candidates <file|-|json>] [--response <file>] [--subject <id>] [--kind <kind file>] [--dry-run]",
+  "chant workspace points answer <id> --answer <value> --by <name> [--by <name>...] [--note <text>] [--relayed-by <principal>] [--kind <kind file>] [--dry-run]",
+  "chant workspace points retract <id> --by <name> [--by <name>...] [--note <text>] [--kind <kind file>] [--dry-run]",
 ].join("\n");
 
-function usage(verb: "ask" | "answer", message: string): PointsWriteDocument {
+function usage(verb: PointsWriteVerb, message: string): PointsWriteDocument {
   return { $schema: POINTS_WRITE_SCHEMA_ID, contract: POINTS_WRITE_CONTRACT_VERSION, verb, error: { code: "write-usage-invalid", message } };
 }
 
-function readJson(verb: "ask" | "answer", flag: string, value: string, cwd: string): { value: unknown } | PointsWriteDocument {
+/** Whether a flag's value is the JSON itself rather than a file: it starts with { or [ (#3403). */
+const inlineJson = (value: string): boolean => /^\s*[[{]/.test(value);
+
+/** A flag's JSON: from standard input (-), the value itself when it starts with { or [, or a file. */
+function readJson(verb: PointsWriteVerb, flag: string, value: string, cwd: string): { value: unknown } | PointsWriteDocument {
   let text: string;
   try {
-    text = readFileSync(value === "-" ? 0 : resolve(cwd, value), "utf-8");
+    text = inlineJson(value) ? value : readFileSync(value === "-" ? 0 : resolve(cwd, value), "utf-8");
   } catch (err) {
     return { $schema: POINTS_WRITE_SCHEMA_ID, contract: POINTS_WRITE_CONTRACT_VERSION, verb, error: { code: "write-input-invalid", message: `${flag} ${value} could not be read: ${err instanceof Error ? err.message : String(err)}` } };
   }
@@ -263,7 +276,7 @@ function readJson(verb: "ask" | "answer", flag: string, value: string, cwd: stri
   }
 }
 
-/** `chant workspace points`, and its `ask` and `answer` verbs. */
+/** `chant workspace points`, and its `ask`, `answer` and `retract` verbs. */
 export async function runWorkspacePoints(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const cwd = process.cwd();
@@ -275,26 +288,39 @@ export async function runWorkspacePoints(ctx: CommandContext): Promise<number> {
   if (verb === "ask") {
     const point = args.extraPositional2;
     if (!point) return print(usage("ask", "ask needs the point's name"));
-    if (args.inputs === undefined) return print(usage("ask", "--inputs <file|-> is required"));
+    if (args.inputs === undefined) return print(usage("ask", "--inputs <file|-|json> is required"));
+    if (args.inputs === "-" && args.candidates === "-") return print(usage("ask", "--inputs and --candidates can't both read standard input: give one as a file or as JSON"));
     const inputs = readJson("ask", "--inputs", args.inputs, cwd);
     if (!("value" in inputs)) return print(inputs);
+    let given: unknown;
+    if (args.candidates !== undefined) {
+      const read = readJson("ask", "--candidates", args.candidates, cwd);
+      if (!("value" in read)) return print(read);
+      given = read.value;
+    }
     let ask: ModelAsk | undefined;
     if (args.response !== undefined) {
       const response = readJson("ask", "--response", args.response, cwd);
       if (!("value" in response)) return print(response);
       ask = responseAsk(response.value);
     }
-    return print(await askPoint({ cwd, point, inputs: inputs.value, subject: args.subject, kind: args.kind, ask, dryRun: args.dryRun }));
+    return print(await askPoint({ cwd, point, inputs: inputs.value, candidates: given, subject: args.subject, kind: args.kind, ask, dryRun: args.dryRun }));
   }
   if (verb === "answer") {
     const id = args.extraPositional2;
     if (!id) return print(usage("answer", "answer needs the question's id"));
     if (args.answer === undefined) return print(usage("answer", "--answer <value> is required"));
     if (!args.bys || args.bys.length === 0) return print(usage("answer", "--by <name> is required, once for each person who answered"));
-    return print(await answerPoint({ cwd, id, answer: args.answer, by: args.bys, kind: args.kind, dryRun: args.dryRun }));
+    return print(await answerPoint({ cwd, id, answer: args.answer, by: args.bys, note: args.note, relayedBy: args.relayedBy, kind: args.kind, dryRun: args.dryRun }));
+  }
+  if (verb === "retract") {
+    const id = args.extraPositional2;
+    if (!id) return print(usage("retract", "retract needs the question's id"));
+    if (!args.bys || args.bys.length === 0) return print(usage("retract", "--by <name> is required, once for each person who takes the answer back"));
+    return print(await retractAnswer({ cwd, id, by: args.bys, note: args.note, kind: args.kind, dryRun: args.dryRun }));
   }
   if (verb !== undefined) {
-    console.error(formatError({ message: `chant workspace points takes no argument but ask or answer (got ${verb})`, hint: USAGE }));
+    console.error(formatError({ message: `chant workspace points takes no argument but ask, answer or retract (got ${verb})`, hint: USAGE }));
     return 1;
   }
   const doc = await workspacePoints({ cwd, at: args.at, open: args.open, kind: args.kind });

package/src/workspace/points-write.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/points-write/v1/points-write.schema.json",
-  "title": "chant workspace points ask and answer output",
-  "description": "What `chant workspace points ask` and `points answer` print (ws-058, #2739): the answer record asked for or written, as `points --json` lists a question. ask returns the record that is there when the same point, declaration and inputs were answered or proposed before (reused), and otherwise writes one: answered from a table, proposed from a model at or above its threshold, escalated to people below it. answer records people's answer to an open question once the point's quorum is met. Nothing is committed to the working branch, and nothing is written on a refusal or with --dry-run. In a steward's turn a new record goes on the lifecycle ledger instead of the working tree (#2786), as a commit on chant/lifecycle, and a record already held there is rewritten there. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Written at contract version 1 of the write documents.",
+  "title": "chant workspace points ask, answer and retract output",
+  "description": "What `chant workspace points ask`, `points answer` and `points retract` print (ws-058, #2739, #3351): the answer record asked for or written, as `points --json` lists a question. ask returns the record that is there when the same point, declaration and inputs were answered or proposed before (reused), and otherwise writes one: answered from a table, proposed from a model at or above its threshold, escalated to people below it. answer records people's answer to an open question once the point's quorum is met, with their note. retract takes an answer back once the quorum is met: the question is escalated to people again and the answer moves into its retractions (ws-084). Nothing is committed to the working branch, and nothing is written on a refusal or with --dry-run. In a steward's turn a new record goes on the lifecycle ledger instead of the working tree (#2786), as a commit on chant/lifecycle, and a record already held there is rewritten there. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Written at contract version 1 of the write documents.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -37,7 +37,8 @@
         "verb": {
           "enum": [
             "ask",
-            "answer"
+            "answer",
+            "retract"
           ]
         },
         "kind": {
@@ -235,6 +236,13 @@
             }
           ]
         },
+        "reason": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The model's own explanation of the recorded answer, a proposal or a confirmed proposal, when the backend gave one (#3345). null otherwise, and from a chant before it."
+        },
         "model": {
           "description": "Any model answer: the proposal (observed), or the last answer below a model decider's threshold (not observed). null when no model answered.",
           "oneOf": [
@@ -303,6 +311,13 @@
                 },
                 "observed": {
                   "type": "boolean"
+                },
+                "reason": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The model's explanation of this answer, when the backend gave one (#3345)."
                 }
               }
             }
@@ -362,6 +377,10 @@
                 "type": "number",
                 "minimum": 0,
                 "maximum": 1
+              },
+              "model_reason": {
+                "type": "string",
+                "description": "A model decider's own explanation of the answer it gave, when the backend gave one (#3345). reason is why the decider did not answer."
               }
             }
           }
@@ -391,6 +410,139 @@
             "null"
           ]
         },
+        "note": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "What the people who answered wrote with their answer (points answer --note, #3351). null when they wrote nothing, and from a chant before it."
+        },
+        "relayedBy": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Who relayed the answer to chant for the people who gave it (points answer --relayed-by, #3402), such as a follower relaying a person's answer through hud. null when nobody did, and from a chant before it."
+        },
+        "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. Empty when none was, and absent from a chant before it.",
+          "items": {
+            "type": "object",
+            "required": [
+              "answer",
+              "decider",
+              "answeredBy",
+              "answeredOn",
+              "answerNote",
+              "answerRelayedBy",
+              "by",
+              "on",
+              "note"
+            ],
+            "properties": {
+              "answer": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "decider": {
+                "type": "object",
+                "description": "Who gave the answer: the record's decider as it was."
+              },
+              "answeredBy": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "answeredOn": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "answerNote": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The note the answer carried."
+              },
+              "answerRelayedBy": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Who relayed the answer (#3402)."
+              },
+              "by": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Who retracted it."
+              },
+              "on": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "note": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Why it was retracted (points retract --note)."
+              }
+            }
+          }
+        },
+        "asked": {
+          "description": "An ad-hoc point's question as its ask gave it (points ask --candidates, #3403): the question's text, and its criteria, what each candidate means, in the point's question type's shape. People's answer is one of the candidates. null for a declared point's question, and absent from a chant before it.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "question",
+                "criteria"
+              ],
+              "properties": {
+                "question": {
+                  "type": "string"
+                },
+                "criteria": {
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "string"
+                      }
+                    },
+                    {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          ]
+        },
         "valid": {
           "type": "boolean"
         },
@@ -445,7 +597,8 @@
         "verb": {
           "enum": [
             "ask",
-            "answer"
+            "answer",
+            "retract"
           ]
         },
         "error": {
@@ -473,6 +626,12 @@
                 "answer-not-candidate",
                 "quorum-not-met",
                 "answer-in-steward-turn",
+                "principal-unidentified",
+                "answer-not-answered",
+                "answer-field-unsupported",
+                "point-candidates-invalid",
+                "write-lock-timeout",
+                "write-lock-not-held",
                 "record-not-found",
                 "record-closed",
                 "record-id-taken",