@intentius/chant 0.89.0 → 0.91.0

package/src/workspace/point-answer.schema.json

@@ -0,0 +1,95 @@
+{
+  "$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-.",
+  "type": "object",
+  "additionalProperties": false,
+  "patternProperties": { "^x-": {} },
+  "required": ["id", "title", "point", "point_version", "question_type", "candidates", "inputs", "inputs_hash", "state", "decider", "asked_on"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*-[0-9a-f]{12}$", "description": "The point's name, a hyphen, and the first 12 hex digits of inputs_hash." },
+    "title": { "type": "string", "minLength": 1 },
+    "point": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "description": "The point in the points file this answers." },
+    "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." },
+    "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." },
+    "state": { "enum": ["escalated", "proposed", "answered"] },
+    "answer": { "type": ["string", "boolean"] },
+    "decider": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": { "enum": ["table", "model", "quorum"] },
+        "row": { "type": "integer", "minimum": 0, "description": "table: the row that matched." },
+        "backend": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1, "description": "model: the model id that answered, as the backend reported it." },
+        "count": { "type": "integer", "minimum": 1 },
+        "roles": { "type": "array", "items": { "type": "string" } },
+        "by": { "type": "array", "items": { "type": "string" }, "description": "quorum: who answered." }
+      },
+      "additionalProperties": false
+    },
+    "probabilities": { "$ref": "#/definitions/probabilities" },
+    "confidence": { "$ref": "#/definitions/unit" },
+    "threshold": { "$ref": "#/definitions/unit" },
+    "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." },
+    "asked_on": { "$ref": "#/definitions/date" },
+    "answered_on": { "$ref": "#/definitions/date" },
+    "source": {
+      "type": "object",
+      "description": "Where the answer came from (#2708): via, client and model, the model id that answered when a model decider did."
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "state": { "const": "proposed" } }, "required": ["state"] },
+      "then": { "required": ["answer"], "properties": { "decider": { "properties": { "kind": { "const": "model" } } } } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "answered" } }, "required": ["state"] },
+      "then": { "required": ["answer", "answered_on"] }
+    },
+    {
+      "if": { "properties": { "state": { "const": "escalated" } }, "required": ["state"] },
+      "then": { "not": { "required": ["answer"] }, "properties": { "decider": { "properties": { "kind": { "const": "quorum" } } } } }
+    },
+    {
+      "if": { "properties": { "decider": { "properties": { "kind": { "const": "model" } }, "required": ["kind"] } }, "required": ["decider"] },
+      "then": { "required": ["probabilities", "confidence", "threshold"], "properties": { "decider": { "required": ["backend", "model"] } } }
+    },
+    {
+      "if": { "properties": { "state": { "const": "answered" }, "decider": { "properties": { "kind": { "const": "quorum" } }, "required": ["kind"] } }, "required": ["state", "decider"] },
+      "then": { "required": ["answered_by"], "properties": { "decider": { "required": ["by"] } } }
+    }
+  ],
+  "definitions": {
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "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" } },
+    "escalation": {
+      "type": "object",
+      "required": ["kind", "reason"],
+      "properties": {
+        "kind": { "enum": ["table", "model"] },
+        "reason": { "type": "string", "minLength": 1 },
+        "backend": { "type": "string" },
+        "model": { "type": "string" },
+        "answer": { "type": ["string", "boolean", "null"] },
+        "probabilities": { "$ref": "#/definitions/probabilities" },
+        "confidence": { "$ref": "#/definitions/unit" },
+        "threshold": { "$ref": "#/definitions/unit" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/src/workspace/points-cli.ts

@@ -0,0 +1,273 @@
+/**
+ * `chant workspace points [--open] [--kind <kind file>] [--at <rev>] [--json]`
+ * (ws-058, #2739): the workspace's decision points and the questions asked of
+ * them, a read-contract output (`points.schema.json`).
+ *
+ * The points come from each record kind the declaration names with an
+ * `answers` block, or from `--kind`, and the questions are that kind's
+ * records. A question is open while it is escalated to people or proposed by a
+ * model and not yet confirmed, and it lists any model's answer with its
+ * confidence, so a reader such as hud can prompt a person and an MCP client
+ * 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`.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+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 { 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";
+import { loadRecordKind, RecordReadError, type ReadErrorCode } from "./records";
+import { readRecordsFor } from "./records-cli";
+import { locateWorkspace } from "./which-chant";
+
+export const POINTS_CONTRACT_VERSION = 1;
+export const POINTS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/points/v1/points.schema.json";
+
+/** Why `points` read nothing. Closed. */
+export const POINTS_ERROR_CODES = [
+  "declaration-missing",
+  "declaration-ambiguous",
+  "declaration-unparseable",
+  "declaration-invalid",
+  "placement-invalid",
+  "reader-too-old",
+  "root-chant-required",
+  "not-a-git-repository",
+  "revision-unknown",
+] as const satisfies readonly ReasonCode[];
+
+/** Why one answer kind's points or questions could not be read. The document is still printed. Closed. */
+export const POINTS_SOURCE_REASON_CODES = [
+  "kind-unreadable",
+  "kind-invalid",
+  "schema-unreadable",
+  "schema-id-mismatch",
+  "schema-invalid",
+  "location-missing",
+  /** The points file the kind names can't be read, or is not valid. */
+  "points-invalid",
+] as const satisfies readonly ReasonCode[];
+type SourceReasonCode = (typeof POINTS_SOURCE_REASON_CODES)[number];
+
+/** One point as `points` lists it. */
+export interface PointView {
+  name: string;
+  title: string;
+  /** The answer kind file, from the workspace root, whose records answer it. */
+  kind: string;
+  /** The points file, from the repository root. */
+  file: string;
+  /** sha256 of the declaration: a question asked under another version answers an older question. */
+  version: string;
+  questionType: string;
+  instructions: string;
+  candidates: (string | boolean)[];
+  /** Each input: its name, the read-contract output it names, and its description. */
+  inputs: { name: string; output: string; description: string }[];
+  deciders: Decider[];
+  quorum: { count: number; roles?: string[] };
+}
+
+/** One answer kind the read covered. */
+export interface SourceView {
+  /** The kind file, as declared from the workspace root, or as given with --kind. */
+  kind: string;
+  /** The points file from the repository root, or null when the kind couldn't be loaded. */
+  points: string | null;
+  reason: { code: SourceReasonCode; message: string } | null;
+}
+
+export type PointsDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      at: string | null;
+      workspace: { name: string; root: string };
+      /** Whether only open questions are listed (--open). */
+      open: boolean;
+      sources: SourceView[];
+      points: PointView[];
+      questions: QuestionView[];
+      summary: { points: number; questions: number; open: number; escalated: number; proposed: number; answered: number };
+    }
+  | { $schema: string; contract: number; chant: string; error: { code: WorkspaceErrorCode; message: string; location: ErrorLocation | null } };
+
+export interface PointsQuery {
+  cwd: string;
+  at?: string;
+  open?: boolean;
+  /** One answer kind file, in place of the declared ones. */
+  kind?: string;
+}
+
+/** Read the points and questions. Never throws a read error: a declaration that can't be read is the failure document. */
+export async function workspacePoints(query: PointsQuery): Promise<PointsDocument> {
+  const head = { $schema: POINTS_OUTPUT_SCHEMA_ID, contract: POINTS_CONTRACT_VERSION, chant: readerVersion() };
+  let located;
+  let declaration;
+  try {
+    located = locateWorkspace(query.cwd, query.at);
+    declaration = readDeclaration(located.tree);
+  } catch (err) {
+    if (!(err instanceof WorkspaceReadError)) throw err;
+    return { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } };
+  }
+  const kinds =
+    query.kind !== undefined
+      ? [{ shown: query.kind, file: resolve(query.cwd, query.kind), given: true }]
+      : declaredRecordKinds(declaration).map((d) => ({ shown: d.path, file: declaredKindFile(d, located.rootOnDisk), given: false }));
+
+  const sources: SourceView[] = [];
+  const points: PointView[] = [];
+  const questions: QuestionView[] = [];
+  for (const k of kinds) {
+    try {
+      const loaded = await loadRecordKind(k.file);
+      if (!loaded.kind.answers) {
+        if (k.given) sources.push({ kind: k.shown, points: null, reason: { code: "kind-invalid", message: `the ${loaded.kind.name} kind has no answers block, so it holds no answers to decision points` } });
+        continue;
+      }
+      const read = await readRecordsFor({ kind: k.file, cwd: query.cwd, at: query.at });
+      const source = read.at !== null && read.top ? gitRevisionSource(read.top, read.at) : workingTreeSource(read.root);
+      const file = pointsFileOf(read.loaded, read.root);
+      const parsed = readPointsThrough(source, file);
+      const declared = "points" in parsed ? parsed.points : {};
+      sources.push({ kind: k.shown, points: file, reason: "error" in parsed ? { code: "points-invalid", message: parsed.error } : null });
+      for (const [name, p] of Object.entries(declared)) {
+        points.push({
+          name,
+          title: p.title,
+          kind: k.shown,
+          file,
+          version: pointVersion(p),
+          questionType: p.question.type,
+          instructions: p.question.instructions,
+          candidates: candidates(p.question),
+          inputs: Object.entries(p.inputs).map(([n, description]) => ({ name: n, output: inputOutput(n), description })),
+          deciders: p.deciders,
+          quorum: quorumOf(p),
+        });
+      }
+      for (const e of read.result.records) {
+        const view = questionView(e, typeof e.data?.point === "string" ? declared[e.data.point] : undefined);
+        if (view && (!query.open || view.open)) questions.push(view);
+      }
+    } catch (err) {
+      if (!(err instanceof RecordReadError)) throw err;
+      sources.push({ kind: k.shown, points: null, reason: { code: err.code as Exclude<ReadErrorCode, "not-a-git-repository" | "revision-unknown">, message: err.message } });
+    }
+  }
+  const count = (s: string) => questions.filter((q) => q.state === s).length;
+  return {
+    ...head,
+    at: located.at,
+    workspace: { name: declaration.name, root: located.root },
+    open: !!query.open,
+    sources,
+    points,
+    questions,
+    summary: { points: points.length, questions: questions.length, open: questions.filter((q) => q.open).length, escalated: count("escalated"), proposed: count("proposed"), answered: count("answered") },
+  };
+}
+
+/** The document as lines for a person. */
+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(", ")})`);
+  if (doc.points.length === 0) lines.push("no decision points are declared");
+  lines.push("");
+  for (const q of doc.questions) {
+    const model = q.model && q.state !== "answered" ? `  model ${JSON.stringify(q.model.answer)} at ${q.model.confidence ?? "?"}${q.model.observed ? "" : `, below ${q.model.threshold ?? "?"}`}` : "";
+    lines.push(`${q.id}  ${q.state}  ${q.title}${model}`);
+  }
+  const n = doc.summary.questions;
+  lines.push(doc.open ? `${n} open ${n === 1 ? "question" : "questions"}` : `${n} ${n === 1 ? "question" : "questions"}, ${doc.summary.open} open`);
+  return lines.join("\n");
+}
+
+/** A POST /v1/systemone response the caller already has, as the model call: its answer to the point asked. */
+export function responseAsk(response: unknown): ModelAsk {
+  return async (request) => {
+    const r = response as { model?: unknown; answers?: Record<string, unknown> } | null;
+    if (r === null || typeof r !== "object") throw new Error("the response is not a JSON object");
+    if (typeof r.model !== "string" || r.model === "") throw new Error("the response names no model");
+    const answer = r.answers?.[request.point];
+    if (answer === null || typeof answer !== "object") throw new Error(`the response has no answer for ${request.point}`);
+    return { model: r.model, answer: answer as WireAnswer };
+  };
+}
+
+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]",
+].join("\n");
+
+function usage(verb: "ask" | "answer", 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 {
+  let text: string;
+  try {
+    text = 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)}` } };
+  }
+  try {
+    return { value: JSON.parse(text) };
+  } catch (err) {
+    return { $schema: POINTS_WRITE_SCHEMA_ID, contract: POINTS_WRITE_CONTRACT_VERSION, verb, error: { code: "write-input-invalid", message: `${flag} ${value} is not JSON: ${err instanceof Error ? err.message : String(err)}` } };
+  }
+}
+
+/** `chant workspace points`, and its `ask` and `answer` verbs. */
+export async function runWorkspacePoints(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const cwd = process.cwd();
+  const print = (doc: object): number => {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc ? 1 : 0;
+  };
+  const verb = args.extraPositional;
+  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"));
+    const inputs = readJson("ask", "--inputs", args.inputs, cwd);
+    if (!("value" in inputs)) return print(inputs);
+    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 }));
+  }
+  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 }));
+  }
+  if (verb !== undefined) {
+    console.error(formatError({ message: `chant workspace points takes no argument but ask or answer (got ${verb})`, hint: USAGE }));
+    return 1;
+  }
+  const doc = await workspacePoints({ cwd, at: args.at, open: args.open, kind: args.kind });
+  if (args.json) console.log(JSON.stringify(doc, null, 2));
+  else if ("error" in doc) console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+  else console.log(formatPoints(doc));
+  return "error" in doc ? 1 : 0;
+}