@intentius/chant 0.89.0 → 0.91.0

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

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/decision-points/v1/decision-points.schema.json",
+  "title": "Decision points",
+  "description": "A workspace's decision points (ws-058, #2738): the recurring questions it asks of its own graph, declared as data in a JSON file that an answer record kind names in `answers.points`. Each point is a typed question (`noul`, `choice` with 2 to 255 options, or `score` with 2 to 10 ordered levels, the question types of the POST /v1/systemone wire format, #2491), the inputs it reads, each named as a read-contract output, and an ordered chain of deciders: `table` rows, `model` deciders with a backend, a pinned model id and a threshold, and a `quorum` of people, always last. Taken from chud's decision-points.schema.json; `boolean` is read as `noul`. What JSON Schema cannot say is checked in code (`points.ts`): an input's output is one the read contract has, a table row tests declared inputs and answers a candidate, a field belongs to its decider's kind, a model id is pinned rather than an alias, and the chain ends in its one quorum. Unknown fields are refused, except fields whose names start with x-.",
+  "type": "object",
+  "required": ["points"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "points": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": { "$ref": "#/$defs/point" }
+    }
+  },
+  "patternProperties": { "^x-": true },
+  "additionalProperties": false,
+  "$defs": {
+    "text": { "type": "string", "minLength": 1 },
+    "point": {
+      "type": "object",
+      "required": ["title", "question", "inputs", "deciders"],
+      "properties": {
+        "title": { "$ref": "#/$defs/text" },
+        "question": { "$ref": "#/$defs/question" },
+        "inputs": {
+          "type": "object",
+          "description": "The state the deciders see, input name to description. A name is a read-contract output (record, decision, work-item, finding, region, commit, member, gate, release, environment, component), optionally followed by dotted field names, such as work-item.fits_small: a field of that output, or a value the caller derives from it. The caller supplies the values; a table row can only test these names.",
+          "minProperties": 1,
+          "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_-]*(\\.[A-Za-z_][A-Za-z0-9_]*)*$" },
+          "additionalProperties": { "type": "string" }
+        },
+        "deciders": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/decider" }
+        }
+      },
+      "patternProperties": { "^x-": true },
+      "additionalProperties": false
+    },
+    "question": {
+      "type": "object",
+      "required": ["type", "instructions", "criteria"],
+      "properties": {
+        "type": { "enum": ["noul", "boolean", "choice", "score"], "description": "boolean is chud's name for noul, read as noul." },
+        "instructions": { "$ref": "#/$defs/text" },
+        "criteria": {
+          "description": "The candidates. noul: {true, false} descriptions. choice: option to description, 2 to 255 options. score: 2 to 10 ordered levels.",
+          "type": ["object", "array"]
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "enum": ["noul", "boolean"] } } },
+          "then": {
+            "properties": {
+              "criteria": {
+                "type": "object",
+                "required": ["true", "false"],
+                "properties": { "true": { "type": "string" }, "false": { "type": "string" } },
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "choice" } } },
+          "then": { "properties": { "criteria": { "type": "object", "minProperties": 2, "maxProperties": 255, "additionalProperties": { "type": "string" } } } }
+        },
+        {
+          "if": { "properties": { "type": { "const": "score" } } },
+          "then": { "properties": { "criteria": { "type": "array", "minItems": 2, "maxItems": 10, "uniqueItems": true, "items": { "$ref": "#/$defs/text" } } } }
+        }
+      ]
+    },
+    "scalar": { "type": ["string", "number", "boolean", "null"] },
+    "condition": {
+      "description": "A value the input must equal, or one comparison.",
+      "oneOf": [
+        { "$ref": "#/$defs/scalar" },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 1,
+          "properties": {
+            "eq": { "$ref": "#/$defs/scalar" },
+            "ne": { "$ref": "#/$defs/scalar" },
+            "lt": { "type": "number" },
+            "lte": { "type": "number" },
+            "gt": { "type": "number" },
+            "gte": { "type": "number" },
+            "in": { "type": "array", "items": { "$ref": "#/$defs/scalar" } }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "row": {
+      "type": "object",
+      "required": ["when", "answer"],
+      "properties": {
+        "when": {
+          "type": "object",
+          "description": "Every named input must meet its condition. An empty object matches every state.",
+          "additionalProperties": { "$ref": "#/$defs/condition" }
+        },
+        "answer": { "type": ["string", "boolean"] },
+        "note": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "decider": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": { "enum": ["table", "model", "quorum"] },
+        "rows": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/row" } },
+        "backend": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "model: which backend answers, such as systemone (any server with the POST /v1/systemone wire format). chant never calls it: the decide Op activity or a runtime's decider does." },
+        "model": { "type": "string", "minLength": 1, "description": "model: the pinned model id the backend is asked for, such as jev-1.13.0. An alias such as jev-latest is refused." },
+        "threshold": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "description": "model: the least confidence that makes the answer a proposal. Below it the answer is not observed and the next decider is asked." },
+        "unreachable": { "enum": ["escalate", "fail"], "description": "model: what happens when the backend can't be reached or gives no usable answer: escalate to the next decider (the default), or fail the ask and write nothing." },
+        "count": { "type": "integer", "minimum": 1, "description": "quorum: how many distinct people must answer." },
+        "roles": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/text" }, "description": "quorum: the trust policy roles whose holders count." },
+        "note": { "type": "string" }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        { "if": { "properties": { "kind": { "const": "table" } } }, "then": { "required": ["rows"] } },
+        { "if": { "properties": { "kind": { "const": "model" } } }, "then": { "required": ["backend", "model", "threshold"] } },
+        { "if": { "properties": { "kind": { "const": "quorum" } } }, "then": { "required": ["count"] } }
+      ]
+    }
+  }
+}

package/src/workspace/declaration.schema.json

@@ -56,6 +56,13 @@
         "$ref": "#/$defs/recordKind"
       }
     },
+    "hosts": {
+      "type": "array",
+      "description": "The hosts boxes run on (#2727). A host is one machine reached under one hostname: boxes on it share its ports, its state root and, in a browser, its cookie jar, so chant workspace check compares the boxes on one host and never boxes on different hosts. A member's box block names its host. Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
+      "items": {
+        "$ref": "#/$defs/host"
+      }
+    },
     "checks": {
       "type": "object",
       "description": "Severity for the declaration checks that allow it, keyed by WSP id (#2535, ws-028): error, warning, info or off. chant workspace check refuses an id it does not know, and one whose severity is fixed.",
@@ -269,6 +276,9 @@
             "$ref": "#/$defs/recordKind"
           }
         },
+        "box": {
+          "$ref": "#/$defs/box"
+        },
         "upstream": {
           "type": "string",
           "minLength": 1,
@@ -354,6 +364,114 @@
       "description": "A file or directory path with / separators: no leading /, no . or .. segments and no trailing /.",
       "pattern": "^(?!\\.\\.?(/|$))[^/\\\\]+(/(?!\\.\\.?(/|$))[^/\\\\]+)*$"
     },
+    "box": {
+      "type": "object",
+      "description": "The member is a box, or holds a box's declarations (#2726). A box holds no credential: each capability it needs outside itself is reached through a broker, a runtime such as a lobby or a door, which holds the credential and enforces the scope. chant workspace check fails when a file in the member's directory carries a literal secret (WSP121) and when a capability names no broker (WSP122). chant workspace status --json lists the capabilities, so a broker can read the scopes. Its host, slot, ports, state and cookies state the box's isolation (#2727): chant derives each value from the box's identity, its host, the member's name and its slot, and prints them in chant workspace status --json, so a runtime reads them instead of choosing its own. chant workspace check fails when two boxes on a host resolve to the same value (WSP123) and when a box hard-codes a machine path (WSP124). Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
+      "properties": {
+        "capabilities": {
+          "type": "array",
+          "description": "Each capability the box reaches outside itself, named once. None when omitted.",
+          "items": {
+            "$ref": "#/$defs/capability"
+          }
+        },
+        "host": {
+          "$ref": "#/$defs/name",
+          "description": "The host the box runs on, one of the top-level hosts (#2727). The box's name is the member's name."
+        },
+        "slot": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The box's number on its host (#2727). Its ports come from the slot's block of the host's range."
+        },
+        "ports": {
+          "type": "object",
+          "description": "The ports the box listens on, each a name and its offset in the box's block (#2727). The port is the block's first port plus the offset.",
+          "propertyNames": {
+            "$ref": "#/$defs/kindName"
+          },
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 65534
+          }
+        },
+        "state": {
+          "type": "object",
+          "description": "State the box keeps outside its checkout, such as hud's identity and database, each a name and a path relative to the box's state directory (#2727). The name is usually the environment variable the runtime sets, such as HUD_IDENTITY_PATH. A path that is absolute, starts with ~ or an environment reference, or has a .. segment is a WSP124 finding.",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$"
+          },
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "cookies": {
+          "type": "array",
+          "description": "Session cookie names the box's runtimes set, such as hud_session (#2727). A browser scopes a cookie to a host, not a port, so each resolves to <cookie>_<member name>.",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,63}$"
+          }
+        }
+      },
+      "dependentRequired": {
+        "host": [
+          "slot"
+        ],
+        "slot": [
+          "host"
+        ],
+        "ports": [
+          "host"
+        ],
+        "state": [
+          "host"
+        ],
+        "cookies": [
+          "host"
+        ]
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
+    "capability": {
+      "type": "object",
+      "description": "A capability a box needs and does not hold the credential for, such as inference, fountain or a third-party API (#2726).",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/$defs/kindName",
+          "description": "The capability, such as inference or fountain. Unique within the box."
+        },
+        "broker": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What brokers the capability: the runtime that holds the credential and swaps the box's own token for it, such as lobby or door. It may name a member of this workspace, or a runtime outside it. Without it the capability is unbrokered, and chant workspace check fails with WSP122."
+        },
+        "scope": {
+          "type": "array",
+          "uniqueItems": true,
+          "description": "What of the box's own the broker lets it reach, which the broker enforces. For Fountain: agent (start conversations with its own agent), vault (attach its own vault), conversations and sandboxes (its own). The words are the broker's; chant records them.",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[^\\u0000-\\u001f]+$"
+          }
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
     "recordKind": {
       "type": "object",
       "description": "A record kind the workspace declares (#2680): a kind file that exports recordKind. chant workspace check fails (WSP115) when the file is missing or does not load as a record kind.",
@@ -469,6 +587,60 @@
           "additionalProperties": false
         }
       ]
+    },
+    "host": {
+      "type": "object",
+      "description": "A host boxes run on (#2727).",
+      "required": [
+        "name",
+        "ports"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/$defs/name",
+          "description": "The host's name, unique among hosts. A box block names it in host."
+        },
+        "ports": {
+          "type": "object",
+          "description": "The TCP ports boxes on this host take theirs from. Slot n owns the block from + n * perBox to from + (n + 1) * perBox - 1, which must end at or before to.",
+          "required": [
+            "from",
+            "to",
+            "perBox"
+          ],
+          "properties": {
+            "from": {
+              "$ref": "#/$defs/port",
+              "description": "The first port of the range."
+            },
+            "to": {
+              "$ref": "#/$defs/port",
+              "description": "The last port of the range, inclusive."
+            },
+            "perBox": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 65535,
+              "description": "How many ports each box's block holds. A box's port offsets are below it."
+            }
+          },
+          "additionalProperties": false
+        },
+        "stateRoot": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where boxes on this host keep state, as an environment reference such as ${XDG_STATE_HOME}/chant/boxes, which the runtime expands on the machine. A box's state directory is <stateRoot>/<member name>. A literal machine path, such as /Users/... or anything under $HOME, is a WSP124 finding. Default ${XDG_STATE_HOME}/chant/boxes."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
+    "port": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 65535
     }
   }
 }

package/src/workspace/declaration.ts

@@ -145,6 +145,54 @@ export interface RecordKindDeclaration {
   pointer: string;
 }
 
+/**
+ * A capability a box reaches through a broker (#2726): inference, Fountain,
+ * a third-party API. The broker is runtime (a lobby, a door, a studio) and
+ * holds the credential; the declaration names it and the scope it enforces.
+ */
+export interface BoxCapability {
+  name: string;
+  /** What brokers it, such as `lobby`, or null when the entry names no broker (WSP122). */
+  broker: string | null;
+  /** What of the box's own the broker lets it reach, such as `agent`, `vault`, `conversations`, `sandboxes`. */
+  scope: string[];
+  /** The entry's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
+/** A member that is a box, or a box's declarations (#2726). */
+export interface BoxDeclaration {
+  capabilities: BoxCapability[];
+  /** The host and slot of the box's isolation, or null when the block declares none (#2727). The values are derived in `boxes.ts`. */
+  isolation: BoxIsolationDeclaration | null;
+  /** The block's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
+/** What a box declares about its isolation (#2727): its identity on a host, and the names of what it needs kept apart. */
+export interface BoxIsolationDeclaration {
+  host: string;
+  slot: number;
+  /** Port name to offset in the box's block, in file order. */
+  ports: Record<string, number>;
+  /** State name to a path relative to the box's state directory, in file order. */
+  state: Record<string, string>;
+  cookies: string[];
+}
+
+/** A host boxes run on (#2727): one machine under one hostname. */
+export interface Host {
+  name: string;
+  ports: { from: number; to: number; perBox: number };
+  /** As written, or null for the default ({@link DEFAULT_STATE_ROOT}). */
+  stateRoot: string | null;
+  /** The entry's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
+/** Where boxes keep state when their host names no stateRoot (#2727). */
+export const DEFAULT_STATE_ROOT = "${XDG_STATE_HOME}/chant/boxes";
+
 export interface Member {
   type: "member";
   name: string;
@@ -160,6 +208,8 @@ export interface Member {
   links: LinkDeclaration[];
   /** The record kinds this member declares, in file order (#2680). */
   records: RecordKindDeclaration[];
+  /** The member's box block, or null when it declares none (#2726). */
+  box: BoxDeclaration | null;
   upstream: string | null;
   because: string | null;
   suppress: Suppression[];
@@ -202,6 +252,8 @@ export interface Declaration {
   quorum: number | null;
   /** The workspace's own record kinds, from the top-level `records`, in file order (#2680). A member's are on the member. */
   records: RecordKindDeclaration[];
+  /** The hosts boxes run on, in file order (#2727). */
+  hosts: Host[];
   /** The file, relative to the workspace root's tree (`chant.workspace.json` or `.jsonc`). */
   file: string;
 }
@@ -414,6 +466,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       pointer: `${pointer}/links/${j}`,
     }));
     const records = recordKindsOf(e.records, e.dir as string, e.name as string, `${pointer}/records`);
+    const box = boxOf(e.box, `${pointer}/box`);
     return {
       type: "member",
       name: e.name as string,
@@ -424,6 +477,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       outputs: e.outputs === undefined ? null : [...(e.outputs as string[])],
       links,
       records,
+      box,
       upstream: (e.upstream as string | undefined) ?? null,
       because: (e.because as string | undefined) ?? null,
       suppress,
@@ -508,6 +562,18 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     byName.set(r.name, r);
   }
 
+  // A box names each capability once (#2726): a broker reads its scope by name.
+  for (const m of members) {
+    const seen = new Map<string, BoxCapability>();
+    for (const c of m.box?.capabilities ?? []) {
+      const first = seen.get(c.name);
+      if (first) throw new WorkspaceReadError("declaration-invalid", `member ${m.name}'s box lists the capability ${c.name} twice; the first is at ${first.pointer}`, at(`${c.pointer}/name`));
+      seen.set(c.name, c);
+    }
+  }
+
+  const hosts = hostsOf(obj, members, at);
+
   const pins = ((obj.pins as Record<string, string>[] | undefined) ?? []).map((p) => ({
     package: p.package ?? null,
     version: p.version ?? null,
@@ -526,6 +592,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     checks: { ...((obj.checks as Record<string, CheckSeverity> | undefined) ?? {}) },
     quorum: typeof obj.quorum === "number" ? obj.quorum : null,
     records: ownRecords,
+    hosts,
     file,
   };
 }
@@ -541,6 +608,76 @@ function recordKindsOf(raw: unknown, dir: string, member: string | null, pointer
   }));
 }
 
+/** The `box` block at `pointer`, already validated, or null when there is none (#2726, #2727). */
+function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
+  if (raw === undefined) return null;
+  const b = raw as {
+    capabilities?: { name: string; broker?: string; scope?: string[] }[];
+    host?: string;
+    slot?: number;
+    ports?: Record<string, number>;
+    state?: Record<string, string>;
+    cookies?: string[];
+  };
+  return {
+    capabilities: (b.capabilities ?? []).map((c, i) => ({ name: c.name, broker: c.broker ?? null, scope: [...(c.scope ?? [])], pointer: `${pointer}/capabilities/${i}` })),
+    // The schema requires host and slot together, and host for ports, state and cookies.
+    isolation:
+      b.host === undefined
+        ? null
+        : { host: b.host, slot: b.slot!, ports: { ...(b.ports ?? {}) }, state: { ...(b.state ?? {}) }, cookies: [...(b.cookies ?? [])] },
+    pointer,
+  };
+}
+
+/**
+ * The hosts, already validated, with the rules the schema can't say (#2727):
+ * host names are unique, a box's host is declared, its slot's block fits the
+ * host's range and its offsets fit the block. What two boxes resolve to is
+ * `chant workspace check`'s question (WSP123), not a read error.
+ */
+function hostsOf(obj: Record<string, unknown>, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): Host[] {
+  const hosts = ((obj.hosts as Record<string, unknown>[] | undefined) ?? []).map((h, i): Host => ({
+    name: h.name as string,
+    ports: { ...(h.ports as Host["ports"]) },
+    stateRoot: (h.stateRoot as string | undefined) ?? null,
+    pointer: `/hosts/${i}`,
+  }));
+  const invalid = (message: string, pointer: string) => new WorkspaceReadError("declaration-invalid", message, at(pointer));
+  const byName = new Map<string, Host>();
+  for (const h of hosts) {
+    const first = byName.get(h.name);
+    if (first) throw invalid(`the host name ${JSON.stringify(h.name)} is already used by the host at ${first.pointer}`, `${h.pointer}/name`);
+    byName.set(h.name, h);
+    if (h.ports.from > h.ports.to) throw invalid(`host ${h.name}'s port range starts at ${h.ports.from}, after its end ${h.ports.to}`, `${h.pointer}/ports`);
+  }
+  for (const m of members) {
+    const iso = m.box?.isolation;
+    if (!iso) continue;
+    const box = m.box!.pointer;
+    const host = byName.get(iso.host);
+    if (!host) {
+      const known = hosts.map((h) => h.name).join(", ") || "none are declared";
+      throw invalid(`member ${m.name}'s box names the host ${JSON.stringify(iso.host)}, which hosts does not declare; declared hosts: ${known}`, `${box}/host`);
+    }
+    const { from, to, perBox } = host.ports;
+    const last = from + (iso.slot + 1) * perBox - 1;
+    if (last > to) {
+      const slots = Math.floor((to - from + 1) / perBox);
+      throw invalid(
+        `member ${m.name}'s box has slot ${iso.slot} on host ${host.name}, which needs ports ${from + iso.slot * perBox} to ${last}, past the end of the host's range (${to}); the range holds ${slots} slot${slots === 1 ? "" : "s"}`,
+        `${box}/slot`,
+      );
+    }
+    for (const [port, offset] of Object.entries(iso.ports)) {
+      if (offset >= perBox) {
+        throw invalid(`member ${m.name}'s box gives port ${port} offset ${offset}, and host ${host.name} gives each box ${perBox} port${perBox === 1 ? "" : "s"} (offsets 0 to ${perBox - 1})`, `${box}/ports/${pointerToken(port)}`);
+      }
+    }
+  }
+  return hosts;
+}
+
 /**
  * Every record kind the declaration names (#2680), in the order readers use
  * them: the workspace's own first, then each member's, members in file order

package/src/workspace/declared-kinds.ts

@@ -13,7 +13,7 @@
  * kind file.
  */
 
-import { join } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { declaredRecordKinds, type Declaration, type RecordKindDeclaration } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import type { WorkspaceTree } from "./tree";
@@ -30,6 +30,12 @@ export interface DeclaredKind {
   kind: string | null;
   /** Why it can't be loaded, or null. */
   reason: { code: DeclaredKindReasonCode; message: string } | null;
+  /**
+   * For an answer kind (ws-058, #2738): its points file from the workspace
+   * root, and what is wrong with it, empty when nothing is. Absent for any
+   * other kind, and when the kind wasn't loaded.
+   */
+  points?: { file: string; problems: { field: string | null; message: string }[] };
 }
 
 /** The kind file of `declared` on disk, under the workspace root `rootOnDisk`. */
@@ -65,7 +71,9 @@ export async function loadDeclaredKinds(
     }
     try {
       const loaded = await records.loadRecordKind(file);
-      out.push({ declared: d, file, kind: loaded.kind.name, reason: null });
+      const entry: DeclaredKind = { declared: d, file, kind: loaded.kind.name, reason: null };
+      if (loaded.kind.answers) entry.points = await checkPoints(resolve(dirname(file), loaded.kind.answers.points), rootOnDisk, tree);
+      out.push(entry);
     } catch (err) {
       if (!(err instanceof records.RecordReadError)) throw err;
       // loadRecordKind names the file as it was given, here an absolute path: name it from the workspace root instead.
@@ -74,3 +82,18 @@ export async function loadDeclaredKinds(
   }
   return out;
 }
+
+/** An answer kind's points file (ws-058), read from `tree` and validated as `points ask` reads it. */
+async function checkPoints(abs: string, rootOnDisk: string, tree: WorkspaceTree): Promise<NonNullable<DeclaredKind["points"]>> {
+  const file = relative(rootOnDisk, abs).split(sep).join("/");
+  if (file.startsWith("../")) return { file, problems: [{ field: null, message: "is outside the workspace" }] };
+  if (tree.stat(file) !== "file") return { file, problems: [{ field: null, message: `does not exist${tree.label}` }] };
+  const { parsePoints, PointsError } = await import("./points");
+  try {
+    parsePoints(tree.read(file), file);
+    return { file, problems: [] };
+  } catch (err) {
+    if (err instanceof PointsError) return { file, problems: err.problems };
+    throw err;
+  }
+}

package/src/workspace/intent.schema.json

@@ -940,7 +940,10 @@
                   "work-implements-undecided",
                   "work-done-unpinned",
                   "work-closed-without-date",
-                  "work-done-gap-open"
+                  "work-done-gap-open",
+                  "answer-points-unreadable",
+                  "answer-point-unknown",
+                  "answer-point-changed"
                 ]
               },
               "message": {