@intentius/chant 0.102.0 → 0.104.1

package/src/workspace/lineage-upgrade.test.ts

@@ -194,6 +194,69 @@ describe("chant workspace upgrade", () => {
     expect(git(proj, ["status", "--porcelain"])).toBe("");
   });
 
+  describe("a CI workflow a chant member builds is rebuilt with this chant (#3244)", () => {
+    const WS = JSON.stringify({ name: "proj", schema: 1, members: [{ name: "delivery", dir: "delivery", kind: "chant" }] }, null, 2) + "\n";
+    const PKG = JSON.stringify({ name: "delivery", scripts: { "ci:build": "chant build ci --lexicon github -o ../.github/workflows/ci.yml", "ci:check": "npm run ci:build && git diff --exit-code ../.github/workflows/ci.yml", "agents": "chant build agents --lexicon fountain -o ../.studio/agents.yaml" } }, null, 2) + "\n";
+    const OLD = "steps:\n  - uses: actions/checkout@v4\n";
+    const NEW = "steps:\n  - uses: actions/checkout@v7\n";
+    /** A chant whose github lexicon now emits @v7: `build` writes NEW where -o points. */
+    const builds = (calls: Array<{ command: string; cwd: string; args?: readonly string[] }>, output = NEW): ChantRunner => async (command, cwd, args) => {
+      calls.push({ command, cwd, args });
+      const o = args?.indexOf("-o") ?? -1;
+      if (o >= 0) put(cwd, args![o + 1], output);
+      return { exitCode: 0, output: "" };
+    };
+
+    beforeEach(() => {
+      release("v2.0.0", { "chant.workspace.json": WS, "delivery/chant.config.ts": "export default {};\n", "delivery/package.json": PKG, ".github/workflows/ci.yml": OLD });
+    });
+
+    test("an upgrade to the same version puts the rebuilt workflow in the patch, and only the CI workflow", async () => {
+      // A box planted at v2.0.0 with the chant of then.
+      const port = ledger();
+      const staged0 = await upgradeCommand({ root: proj, to: "v2.0.0", runChant: passing, ledger: port, now: "2026-10-03T00:00:00.000Z" });
+      port.approve(staged0.staged!.digest, "2026-10-03T00:01:00.000Z");
+      expect((await upgradeCommand({ root: proj, to: "v2.0.0", runChant: passing, ledger: port, now: "2026-10-03T00:02:00.000Z" })).outcome).toBe("applied");
+      commitProject("at v2");
+      expect(read(proj, ".github/workflows/ci.yml")).toBe(OLD);
+
+      // chant is upgraded; the template is not. The workflow ci.ts builds now differs.
+      const calls: Array<{ command: string; cwd: string; args?: readonly string[] }> = [];
+      const staged = await stageUpgrade({ root: proj, to: "v2.0.0", runChant: builds(calls) });
+      try {
+        expect(staged.workflows).toEqual([{ member: "delivery", script: "ci:build", path: ".github/workflows/ci.yml", command: "chant build ci --lexicon github -o ../.github/workflows/ci.yml", status: "rebuilt" }]);
+        expect(calls[0]).toEqual({ command: "build", cwd: join(staged.worktreeProject, "delivery"), args: ["ci", "--lexicon", "github", "-o", "../.github/workflows/ci.yml"] });
+        // The agents script writes no CI workflow, so it is not run.
+        expect(calls.some((c) => c.args?.includes("agents"))).toBe(false);
+        expect(staged.changed).toBe(true);
+        expect(staged.changedPaths).toEqual([".github/workflows/ci.yml"]);
+        expect(staged.governance?.paths).toEqual([".github/workflows/ci.yml"]);
+        expect(read(proj, ".github/workflows/ci.yml")).toBe(OLD);
+      } finally {
+        staged.dispose();
+      }
+
+      // Once it is committed as built, the next upgrade finds nothing to do.
+      put(proj, ".github/workflows/ci.yml", NEW);
+      commitProject("ci:build");
+      const again = await stageUpgrade({ root: proj, to: "v2.0.0", runChant: builds([]) });
+      try {
+        expect(again.workflows.map((w) => w.status)).toEqual(["unchanged"]);
+        expect(again.changed).toBe(false);
+      } finally {
+        again.dispose();
+      }
+    });
+
+    test("a workflow that does not build fails the build check and stays as it was", async () => {
+      const failing: ChantRunner = async (_command, _cwd, args) => (args?.length ? { exitCode: 1, output: "cannot find @intentius/chant-lexicon-github\n" } : { exitCode: 0, output: "" });
+      const result = await upgradeCommand({ root: proj, to: "v2.0.0", runChant: failing });
+      expect(result.outcome).toBe("checks-failed");
+      expect(result.staged!.workflows.map((w) => w.status)).toEqual(["failed"]);
+      expect(result.staged!.checks).toEqual(expect.arrayContaining([expect.objectContaining({ name: "build", status: "failed", member: "delivery", detail: expect.stringMatching(/\.github\/workflows\/ci\.yml could not be rebuilt[\s\S]*cannot find/) })]));
+    });
+  });
+
   test("gates on the patch digest, then applies exactly the approved patch", async () => {
     release("v2.0.0", { "README.md": "starter v2\n" });
     const port = ledger();

package/src/workspace/lineage-upgrade.ts

@@ -21,6 +21,9 @@
  * 4. Merge per file (ws-005): an edited file takes the new version only when
  *    every hunk merges cleanly. Otherwise it stays as it was, with one manual
  *    step. The worktree never holds conflict markers.
+ *    Then rebuild each CI workflow a chant member's package.json builds with
+ *    `chant build ... -o <workflow>` (#3244), with the chant doing the
+ *    upgrade, so the committed workflow follows that chant's composites.
  * 5. Check the worktree: `chant build` and `chant lint` when the project is a
  *    chant project, and the lineage checks of `chant workspace check`.
  * 6. Bind the gate to the digest of the resulting patch: the pending fact and
@@ -34,7 +37,7 @@
  */
 
 import { execFileSync, spawn } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { computePlanDigest } from "../lifecycle/plan-digest";
@@ -64,6 +67,7 @@ import { pathsInsideNested } from "./nesting";
 import { carryParameters, readManifest, substituteParameters } from "./template-manifest";
 import { repinSubstituted, type RepinnedRecord } from "./template-pins";
 import { workingTree } from "./tree";
+import { splitCommandLine } from "./checks/generated";
 
 /** The kind the patch digest is taken under, so it never collides with another kind of plan. */
 export const UPGRADE_PLAN_KIND = "workspace-upgrade";
@@ -86,22 +90,26 @@ export interface UpgradeCheck {
   member?: string;
 }
 
-/** Runs `chant build` or `chant lint` in a directory. */
-export type ChantRunner = (command: "build" | "lint", cwd: string) => Promise<{ exitCode: number; output: string }>;
+/**
+ * Runs `chant build` or `chant lint` in a directory, with `args` after the
+ * command when given (a workflow rebuild's `ci --lexicon github -o <file>`,
+ * #3244).
+ */
+export type ChantRunner = (command: "build" | "lint", cwd: string, args?: readonly string[]) => Promise<{ exitCode: number; output: string }>;
 
 /**
  * The default runner: this same chant, in a child process. The child sees the
  * worktree's sources and resolves packages the way the project does, since the
  * worktree sits inside the project.
  */
-export const spawnChant: ChantRunner = (command, cwd) =>
+export const spawnChant: ChantRunner = (command, cwd, args = []) =>
   new Promise((resolvePromise, reject) => {
     const entry = process.argv[1];
     if (!entry) {
       reject(new UpgradeError("cannot find the chant entry point to run build and lint in the worktree"));
       return;
     }
-    const child = spawn(process.execPath, [...process.execArgv, entry, command], { cwd, stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    const child = spawn(process.execPath, [...process.execArgv, entry, command, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"], env: process.env });
     const out: Buffer[] = [];
     child.stdout.on("data", (c: Buffer) => out.push(c));
     child.stderr.on("data", (c: Buffer) => out.push(c));
@@ -139,6 +147,121 @@ export interface UpgradeOptions {
   runChant?: ChantRunner;
 }
 
+/**
+ * A CI workflow a chant member's package.json builds, and what rebuilding it
+ * did (#3244). `rebuilt`: the workflow chant builds now differs from the one
+ * committed, and the patch carries the new one. `unchanged`: it is the same.
+ * `failed`: the build failed, the file is left as the merge left it, and the
+ * upgrade's `build` check fails with the output.
+ */
+export interface RebuiltWorkflow {
+  /** The chant member whose package.json script builds it. */
+  member: string;
+  /** The script's name, such as `ci:build`. */
+  script: string;
+  /** The workflow, relative to the repository root. */
+  path: string;
+  /** The command line, as the script has it. */
+  command: string;
+  status: "rebuilt" | "unchanged" | "failed";
+  /** The tail of the build's output, when it failed. */
+  detail?: string;
+}
+
+/** A CI workflow path a forge reads, relative to the repository root. The governance list's pipeline entries. */
+const CI_WORKFLOW = [/(^|\/)\.github\/workflows\/[^/]+\.ya?ml$/, /(^|\/)\.forgejo\/workflows\/[^/]+\.ya?ml$/, /(^|\/)\.gitea\/workflows\/[^/]+\.ya?ml$/, /(^|\/)\.gitlab-ci\.ya?ml$/];
+
+/**
+ * The CI workflows the chant members under `worktreeProject` build: each
+ * package.json script that is one `chant build ... -o <file>` command (no
+ * shell, no `&&`), whose output is a committed CI workflow inside the scope.
+ * The studio kit's template has `"ci:build": "chant build ci --lexicon github
+ * -o ../.github/workflows/ci.yml"` in delivery/, and its CI fails when the
+ * committed workflow differs from what ci/ci.ts builds.
+ */
+function workflowBuilds(worktree: string, worktreeProject: string, scopeRepoPath: string): Array<{ member: string; script: string; command: string; args: string[]; abs: string; path: string }> {
+  const out: Array<{ member: string; script: string; command: string; args: string[]; abs: string; path: string }> = [];
+  for (const member of chantMemberDirs(worktreeProject)) {
+    const dir = member === "." ? worktreeProject : join(worktreeProject, member);
+    let scripts: Record<string, unknown>;
+    try {
+      scripts = (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { scripts?: Record<string, unknown> }).scripts ?? {};
+    } catch {
+      continue;
+    }
+    for (const [script, line] of Object.entries(scripts)) {
+      if (typeof line !== "string") continue;
+      const words = splitCommandLine(line);
+      if (!words || words[0] !== "chant" || words[1] !== "build") continue;
+      const flag = words.findIndex((w) => w === "-o" || w === "--output");
+      const target = flag >= 0 ? words[flag + 1] : words.find((w) => w.startsWith("--output="))?.slice("--output=".length);
+      if (!target) continue;
+      const abs = resolve(dir, target);
+      const path = relative(worktree, abs).split(sep).join("/");
+      if (path.startsWith("../") || !CI_WORKFLOW.some((re) => re.test(path))) continue;
+      if (scopeRepoPath !== "." && !path.startsWith(`${scopeRepoPath}/`)) continue;
+      if (!existsSync(abs)) continue;
+      out.push({ member, script, command: line, args: words.slice(2), abs, path });
+    }
+  }
+  return out;
+}
+
+/**
+ * Rebuild the CI workflows {@link workflowBuilds} finds (#3244), each in its
+ * member's directory of the staging worktree with that member's node_modules
+ * linked in from the project. A workflow is built from the member's sources
+ * through the lexicon's composites, so upgrading chant can change it with no
+ * change to the sources (#2621 moved Checkout and SetupNode from v4 to v7),
+ * and a committed copy then fails the project's own ci:check. Rebuilding it
+ * here puts the new workflow in the patch the gate approves. The links are
+ * removed before the patch is taken. A build that fails leaves the file as
+ * the merge left it.
+ */
+async function rebuildWorkflows(root: string, worktree: string, worktreeProject: string, scopeRepoPath: string, run: ChantRunner): Promise<RebuiltWorkflow[]> {
+  const builds = workflowBuilds(worktree, worktreeProject, scopeRepoPath);
+  if (builds.length === 0) return [];
+  const linked: string[] = [];
+  const results: RebuiltWorkflow[] = [];
+  try {
+    for (const member of new Set(builds.map((b) => b.member))) {
+      if (member === ".") continue;
+      const from = join(root, member, "node_modules");
+      const to = join(worktreeProject, member, "node_modules");
+      if (existsSync(from) && !existsSync(to) && existsSync(dirname(to))) {
+        symlinkSync(from, to, "dir");
+        linked.push(to);
+      }
+    }
+    for (const b of builds) {
+      const before = readFileSync(b.abs);
+      const r = await run("build", b.member === "." ? worktreeProject : join(worktreeProject, b.member), b.args);
+      const base = { member: b.member, script: b.script, path: b.path, command: b.command };
+      if (r.exitCode !== 0) {
+        writeFileSync(b.abs, before);
+        results.push({ ...base, status: "failed", detail: tail(r.output) });
+        continue;
+      }
+      const after = existsSync(b.abs) ? readFileSync(b.abs) : null;
+      if (after === null) {
+        writeFileSync(b.abs, before);
+        results.push({ ...base, status: "failed", detail: `\`${b.command}\` exited 0 and wrote no ${b.path}` });
+        continue;
+      }
+      results.push({ ...base, status: after.equals(before) ? "unchanged" : "rebuilt" });
+    }
+  } finally {
+    for (const l of linked) {
+      try {
+        if (lstatSync(l).isSymbolicLink()) unlinkSync(l);
+      } catch {
+        // Already gone.
+      }
+    }
+  }
+  return results;
+}
+
 export interface GovernanceChange {
   /** Changed governance paths, relative to the repository root. */
   paths: string[];
@@ -166,6 +289,8 @@ export interface StagedUpgrade {
   migrations: string[];
   /** The migrations chant ships (./chant-migrations.ts) that found something to move, applied or not. */
   chantMigrations: ChantMigrationReport[];
+  /** The CI workflows a chant member builds, rebuilt with this chant before the patch was taken (#3244). */
+  workflows: RebuiltWorkflow[];
   written: string[];
   merged: string[];
   removed: string[];
@@ -694,6 +819,10 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
     writeLock(worktreeProject, next);
     const lockText = renderLock(next);
 
+    // The CI workflows a chant member builds, rebuilt with this chant (#3244),
+    // before the patch is taken so the gate approves them with the rest.
+    const workflows = lineage.kind === "template" ? await rebuildWorkflows(root, worktree, worktreeProject, scopeRepoPath, options.runChant ?? spawnChant) : [];
+
     // The patch, taken before anything else runs in the worktree.
     gitOut(worktree, ["add", "-A"]);
     if (!lockTracked) gitOut(worktree, ["rm", "--cached", "-q", "--ignore-unmatch", "--", lockRepoPath]);
@@ -730,6 +859,14 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
 
     // 5. Checks.
     const checks: UpgradeCheck[] = [];
+    for (const w of workflows.filter((w) => w.status === "failed")) {
+      checks.push({
+        name: "build",
+        status: "failed",
+        member: w.member,
+        detail: `${w.path} could not be rebuilt with \`${w.command}\` (the ${w.script} script), so it may differ from what this chant builds:\n${w.detail ?? ""}`,
+      });
+    }
     for (const m of chantMigrations.filter((m) => !m.applied)) {
       checks.push({
         name: "migration",
@@ -783,6 +920,7 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
       ...(upstream.commit ? { commit: { ...(lineage.address?.commit ? { from: lineage.address.commit } : {}), to: upstream.commit } } : {}),
       migrations: [...plan.chain.map((m) => m.migration.id), ...chantMigrations.filter((m) => m.applied).map((m) => m.id)],
       chantMigrations,
+      workflows,
       written: result.written,
       merged: result.merged,
       removed: result.removed,
@@ -885,6 +1023,9 @@ export function describeStaged(staged: StagedUpgrade): string[] {
     for (const n of m.notMoved) lines.push(`    not moved: ${n.what} -> ${n.where}`);
     for (const c of m.conflicts) lines.push(`    conflict: ${at(c.path)}: ${c.reason}`);
   }
+  for (const w of staged.workflows) {
+    if (w.status !== "unchanged") lines.push(`  workflow ${w.status === "rebuilt" ? "rebuilt" : "not rebuilt"}: ${w.path} (${w.script}: ${w.command})`);
+  }
   for (const p of staged.written) lines.push(`  updated: ${at(p)}`);
   for (const p of staged.merged) lines.push(`  merged: ${at(p)}`);
   for (const p of staged.removed) lines.push(`  removed: ${at(p)}`);

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
     }