@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/points.js

@@ -0,0 +1,521 @@
+/**
+ * Decision points (ws-058, #2738): the recurring questions a workspace asks of
+ * its own graph, declared as data, and the answers they leave (#2739).
+ *
+ * A points file is JSON, validated against `decision-points.schema.json`, and
+ * named by a record kind's `answers.points`: the kind whose records are the
+ * answers. Each point is a typed question (`noul`, `choice` or `score`, 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 of { when, answer }; the first row whose conditions all hold answers.
+ *   model   a backend asked the question with the inputs as its state, at a
+ *           pinned model id. An answer at or above the threshold is a
+ *           proposal a person confirms; below it, the next decider is asked.
+ *   quorum  people. Always last: the question escalates to them.
+ *
+ * A point declared `adhoc` (#3403) has no candidates of its own: its
+ * question's text and candidates come with each ask, as an agent's question
+ * to the room does, and the answer record keeps them as `asked`, so people's
+ * answer is checked against the candidates the question was asked with. Only
+ * people decide it: its chain is one quorum.
+ *
+ * chant never calls a model (ws-052). {@link runChain} takes the model call
+ * as a function, {@link ModelAsk}, which the decide Op activity (#2740), a
+ * runtime's decider or a test's stub supplies. Without one, a model decider is
+ * not asked and the chain moves on.
+ *
+ * Ported from chud's `packages/runtime/src/decide.mjs` at 43afcf1: the chain,
+ * the observation rule, the point version and the inputs hash. The records
+ * are chant records: `decide.ts` writes them, and {@link applyAnswers} warns
+ * about them on read.
+ */
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import { dirname, posix, relative, resolve, sep } from "node:path";
+import schema from "./decision-points.schema.json" with { type: "json" };
+export const DECISION_POINTS_SCHEMA_ID = schema.$id;
+// ── The read-contract outputs an input may name ─────────────────────────────
+/**
+ * The read-contract outputs a point's input may name (#2738), each with the
+ * output schema and `$defs` entry that describes it. Closed: an input naming
+ * anything else is refused. `record`, `decision` and `work-item` are records
+ * as `records --json` lists them, of any kind, a decision kind and a work kind.
+ */
+export const POINT_INPUT_OUTPUTS = {
+    record: { schema: "records", def: "record", description: "a record of any kind, as records --json lists it" },
+    decision: { schema: "records", def: "record", description: "a decision record, as records --json lists it" },
+    "work-item": { schema: "records", def: "record", description: "a work item record, as records --json lists it (#2683)" },
+    finding: { schema: "intent", def: "finding", description: "a finding of graph --intent, or of check --changes (#2794)" },
+    region: { schema: "intent", def: "region", description: "the region an intent graph covers" },
+    commit: { schema: "intent", def: "commit", description: "a commit in an intent graph's window" },
+    node: { schema: "intent", def: "node", description: "any node of an intent graph, by its id and kind: a commit, decision, unit, artifact or the region itself, as an intent walk asks of it (#3351)" },
+    ask: { schema: "points", def: "question", description: "an ad-hoc question as its asker knows it (#3403): the asker's own id for the ask, such as hud's request id for an agent's question, and who asked" },
+    member: { schema: "ls", def: "member", description: "a member, as ls lists it" },
+    gate: { schema: "status", def: "gate", description: "a gate, as status lists it" },
+    release: { schema: "status", def: "release", description: "a release, as status lists it; a release plan's fields until the lifecycle ledger lists plans (#2717)" },
+    environment: { schema: "status", def: "environment", description: "an environment, as status lists it" },
+    component: { schema: "composites", def: "component", description: "a component, as graph --composites lists it" },
+};
+export const POINT_INPUT_OUTPUT_NAMES = Object.keys(POINT_INPUT_OUTPUTS);
+/** The output an input name reads: the part before its first dot. */
+export function inputOutput(name) {
+    const dot = name.indexOf(".");
+    return dot < 0 ? name : name.slice(0, dot);
+}
+export class PointsError extends Error {
+    constructor(file, problems) {
+        super(`${file}: ${problems.map((p) => (p.field ? `${p.field} ${p.message}` : p.message)).join("; ")}`);
+        this.file = file;
+        this.problems = problems;
+        this.name = "PointsError";
+    }
+}
+/** A question's candidate answers: true and false, a choice's options, or a score's levels. */
+export function candidates(question) {
+    if (question.type === "noul")
+        return [true, false];
+    if (question.type === "choice")
+        return Object.keys(question.criteria ?? {});
+    return [...(question.criteria ?? [])];
+}
+const ONLY = { table: ["rows"], model: ["backend", "model", "threshold", "unreachable"], quorum: ["count", "roles"] };
+/** A model id that names an alias rather than a release, such as jev-latest or jev-preview (#2491). */
+const ALIAS = /(^|[-_./])(latest|preview|stable|current)$/i;
+/** What the schema cannot say about the points (chud's pointProblems, and the input and chain rules of #2738). */
+function pointProblems(points) {
+    const problems = [];
+    for (const [name, point] of Object.entries(points)) {
+        const at = (...path) => ["points", name, ...path].join(".");
+        const inputs = Object.keys(point.inputs);
+        for (const input of inputs) {
+            const output = inputOutput(input);
+            if (!POINT_INPUT_OUTPUT_NAMES.includes(output)) {
+                problems.push({
+                    field: at("inputs", input),
+                    message: `names ${JSON.stringify(output)}, which is not a read-contract output; an input is one of ${POINT_INPUT_OUTPUT_NAMES.join(", ")}, optionally with dotted field names`,
+                });
+            }
+        }
+        if (point.adhoc && (point.deciders.length !== 1 || point.deciders[0].kind !== "quorum")) {
+            problems.push({
+                field: at("deciders"),
+                message: "is an ad-hoc point's chain, and an ad-hoc point is decided by people alone: its chain is one quorum, since no table row or model can know candidates that come with the ask",
+            });
+        }
+        const allowed = candidates(point.question);
+        const last = point.deciders.length - 1;
+        point.deciders.forEach((d, i) => {
+            const raw = d;
+            for (const [kind, fields] of Object.entries(ONLY)) {
+                if (kind === d.kind)
+                    continue;
+                for (const field of fields) {
+                    if (raw[field] !== undefined && !ONLY[d.kind].includes(field))
+                        problems.push({ field: at("deciders", i, field), message: `is only for a ${kind} decider, and this one is a ${d.kind}` });
+                }
+            }
+            if (d.kind === "quorum" && i !== last)
+                problems.push({ field: at("deciders", i), message: "is a quorum, and a quorum is the last decider: nobody is asked after people" });
+            if (d.kind === "model" && ALIAS.test(d.model)) {
+                problems.push({ field: at("deciders", i, "model"), message: `${JSON.stringify(d.model)} is an alias, and an alias moves when a new release ships: pin a versioned model id` });
+            }
+            if (d.kind === "table") {
+                d.rows.forEach((row, r) => {
+                    if (!allowed.includes(row.answer)) {
+                        problems.push({ field: at("deciders", i, "rows", r, "answer"), message: `must be one of ${allowed.map((a) => JSON.stringify(a)).join(", ")}, not ${JSON.stringify(row.answer)}` });
+                    }
+                    for (const key of Object.keys(row.when)) {
+                        if (!inputs.includes(key))
+                            problems.push({ field: at("deciders", i, "rows", r, "when", key), message: `is not one of this point's inputs (${inputs.join(", ")})` });
+                    }
+                });
+            }
+        });
+        if (point.deciders[last]?.kind !== "quorum") {
+            problems.push({ field: at("deciders"), message: "must end in a quorum: when no table row or model answers, people do" });
+        }
+    }
+    return problems;
+}
+let compiled;
+function validator() {
+    if (compiled)
+        return compiled;
+    const require = createRequire(import.meta.url);
+    // ajv is CommonJS; its class is the default export, or that export's own default.
+    const mod = require("ajv/dist/2020");
+    const Ajv = (mod.default ?? mod);
+    compiled = new Ajv({ allErrors: true, strict: false }).compile(schema);
+    return compiled;
+}
+const SUMMARY = new Set(["if", "then", "else", "oneOf", "anyOf", "allOf"]);
+/** The schema's problems with `data`, as JSON paths. */
+export function schemaProblems(data) {
+    const validate = validator();
+    if (validate(data))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const e of validate.errors ?? []) {
+        if (SUMMARY.has(e.keyword))
+            continue;
+        const path = e.instancePath.split("/").slice(1).map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+        const field = path.length ? path.join(".") : null;
+        const message = e.keyword === "additionalProperties"
+            ? `has an unknown field ${JSON.stringify(e.params.additionalProperty)}; only fields named x-... may be added`
+            : e.keyword === "required"
+                ? `is missing ${JSON.stringify(e.params.missingProperty)}`
+                : e.keyword === "propertyNames"
+                    ? `has a name that is not allowed: ${JSON.stringify(e.params.propertyName)}`
+                    : e.keyword === "not"
+                        ? "has criteria, and an ad-hoc point's candidates come with each ask (#3403): leave criteria out"
+                        : (e.message ?? "is invalid");
+        const key = `${field}\0${message}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ field, message });
+    }
+    return out;
+}
+/**
+ * Parse and validate a points file's text. Returns its points. Throws a
+ * {@link PointsError} naming the file and each field.
+ */
+export function parsePoints(text, file) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch (err) {
+        throw new PointsError(file, [{ field: null, message: `is not JSON: ${err instanceof Error ? err.message : String(err)}` }]);
+    }
+    const problems = schemaProblems(data);
+    if (problems.length > 0)
+        throw new PointsError(file, problems);
+    const points = data.points;
+    const more = pointProblems(points);
+    if (more.length > 0)
+        throw new PointsError(file, more);
+    return points;
+}
+/** One point by name, or undefined. */
+export function pointOf(points, name) {
+    return Object.prototype.hasOwnProperty.call(points, name) ? points[name] : undefined;
+}
+/** JSON with keys sorted and undefined members left out, the text every hash here is taken over. */
+export function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const o = value;
+        return `{${Object.keys(o)
+            .sort()
+            .filter((k) => o[k] !== undefined)
+            .map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+const sha256 = (text) => createHash("sha256").update(text, "utf8").digest("hex");
+/** The version of a point: the sha256 of its declaration. Editing the question or any decider changes it. */
+export const pointVersion = (point) => sha256(canonical(point));
+/**
+ * What is answered once: the point, its version and the inputs, and for an
+ * ad-hoc point the question and candidates it was asked with (#3403).
+ */
+export const inputsHash = (name, version, inputs, asked) => sha256(canonical({ point: name, version, inputs, asked }));
+/** The question an answer asks: the point's own, or for an ad-hoc point the one the ask gave. */
+export function askedQuestion(point, asked) {
+    return asked ? { type: point.question.type, instructions: asked.question, criteria: asked.criteria } : point.question;
+}
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+/**
+ * An ad-hoc ask's question and candidates (`points ask --candidates`), checked
+ * against the point's question type as a declaration's criteria are: noul
+ * describes true and false, choice gives 2 to 255 options, each with what it
+ * means, and score 2 to 10 distinct ordered levels. Returns the problems, or
+ * the question.
+ */
+export function parseAsked(point, value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return { problems: ["the candidates must be a JSON object with question and criteria"] };
+    const v = value;
+    const problems = [];
+    const extra = Object.keys(v).filter((k) => k !== "question" && k !== "criteria");
+    if (extra.length > 0)
+        problems.push(`the candidates take question and criteria, not ${extra.join(", ")}`);
+    if (!nonEmpty(v.question))
+        problems.push("question must be the question's text");
+    const c = v.criteria;
+    const type = point.question.type;
+    if (type === "score") {
+        if (!Array.isArray(c) || c.length < 2 || c.length > 10 || !c.every(nonEmpty) || new Set(c).size !== c.length)
+            problems.push("criteria must be 2 to 10 distinct levels, in order, for a score question");
+    }
+    else if (c === null || typeof c !== "object" || Array.isArray(c)) {
+        problems.push(`criteria must be an object of ${type === "noul" ? "true and false" : "options"}, each with what it means`);
+    }
+    else {
+        const entries = Object.entries(c);
+        if (!entries.every(([k, d]) => k !== "" && typeof d === "string"))
+            problems.push("each criterion must be a non-empty name with what it means as a string");
+        if (type === "noul") {
+            const keys = entries.map(([k]) => k).sort();
+            if (keys.length !== 2 || keys[0] !== "false" || keys[1] !== "true")
+                problems.push("criteria must describe true and false, and nothing else, for a noul question");
+        }
+        else if (entries.length < 2 || entries.length > 255) {
+            problems.push("criteria must give 2 to 255 options for a choice question");
+        }
+    }
+    if (problems.length > 0)
+        return { problems };
+    const criteria = Array.isArray(c) ? [...c] : { ...c };
+    return { asked: { question: v.question.trim(), criteria } };
+}
+/** An answer record's `asked`, when it has one. */
+export function askedOf(data) {
+    const a = data.asked;
+    if (a === null || typeof a !== "object" || Array.isArray(a) || typeof a.question !== "string")
+        return undefined;
+    const c = a.criteria;
+    if (Array.isArray(c))
+        return { question: a.question, criteria: c.filter((x) => typeof x === "string") };
+    if (c !== null && typeof c === "object")
+        return { question: a.question, criteria: Object.fromEntries(Object.entries(c).filter(([, d]) => typeof d === "string")) };
+    return undefined;
+}
+/** The id of the answer to `name` for inputs hashing to `hash`: the name and the hash's first 12 hex digits. */
+export const answerId = (name, hash) => `${name}-${hash.slice(0, 12)}`;
+/** The quorum a point ends in. */
+export function quorumOf(point) {
+    const last = point.deciders[point.deciders.length - 1];
+    return last?.kind === "quorum" ? { count: last.count, ...(last.roles ? { roles: last.roles } : {}) } : { count: 1 };
+}
+// ── The chain ────────────────────────────────────────────────────────────────
+function holds(condition, value) {
+    if (condition === null || typeof condition !== "object")
+        return value === condition;
+    const [[op, x]] = Object.entries(condition);
+    const number = typeof value === "number";
+    switch (op) {
+        case "eq":
+            return value === x;
+        case "ne":
+            return value !== x;
+        case "lt":
+            return number && value < x;
+        case "lte":
+            return number && value <= x;
+        case "gt":
+            return number && value > x;
+        case "gte":
+            return number && value >= x;
+        case "in":
+            return x.includes(value);
+        default:
+            return false;
+    }
+}
+/** Whether every condition in a row's `when` holds for these inputs. An input the state lacks never matches. */
+export const matches = (when, inputs) => Object.entries(when).every(([key, condition]) => Object.prototype.hasOwnProperty.call(inputs, key) && holds(condition, inputs[key]));
+/** A wire answer's reason, trimmed, or undefined when it gives none (or not a string). */
+export function answerReason(answer) {
+    const raw = answer?.reason;
+    if (typeof raw !== "string")
+        return undefined;
+    const reason = raw.trim();
+    return reason === "" ? undefined : reason;
+}
+export function wireQuestion(question) {
+    return { type: question.type, instructions: question.instructions, criteria: question.criteria ?? {} };
+}
+const round = (x) => Math.round(x * 1e6) / 1e6;
+/**
+ * A model's wire answer against the question and the decider's threshold
+ * (chud's rule):
+ *
+ * - noul p: true when p is at least the threshold, false when 1 - p is,
+ *   otherwise not observed. Its confidence is max(p, 1 - p).
+ * - choice and score: the choice (a score's most probable level) when the
+ *   reported confidence is at least the threshold. A backend that reports no
+ *   confidence is read by its largest probability.
+ *
+ * An answer outside the candidates, or an unsupported question, is not observed.
+ */
+export function observe(question, answer, threshold) {
+    const allowed = candidates(question);
+    if (!answer || answer.type === "unsupported")
+        return { observed: false, reason: "the backend does not support this question type" };
+    if (question.type === "noul") {
+        const p = Number(answer.noul);
+        if (!(p >= 0 && p <= 1))
+            return { observed: false, reason: "the answer carries no probability" };
+        const probabilities = { true: round(p), false: round(1 - p) };
+        const confidence = round(Math.max(p, 1 - p));
+        if (p >= threshold)
+            return { observed: true, answer: true, probabilities, confidence };
+        if (1 - p >= threshold)
+            return { observed: true, answer: false, probabilities, confidence };
+        return { observed: false, answer: p >= 0.5, probabilities, confidence, reason: `confidence ${confidence} is below the threshold ${threshold}` };
+    }
+    const a = answer;
+    const probabilities = Object.fromEntries(Object.entries(a.probabilities ?? {})
+        .map(([k, v]) => [k, Number(v)])
+        .filter(([, v]) => Number.isFinite(v) && v >= 0 && v <= 1)
+        .map(([k, v]) => [k, round(v)]));
+    const choice = question.type === "choice" ? a.choice : Object.entries(probabilities).sort((x, y) => y[1] - x[1])[0]?.[0];
+    const reported = Number(a.confidence);
+    const confidence = round(a.confidence !== undefined && Number.isFinite(reported) ? reported : Math.max(0, ...Object.values(probabilities)));
+    if (typeof choice !== "string" || !allowed.includes(choice)) {
+        return { observed: false, answer: typeof choice === "string" ? choice : null, probabilities, confidence, reason: `the answer ${JSON.stringify(choice ?? null)} is not a candidate` };
+    }
+    if (confidence >= threshold)
+        return { observed: true, answer: choice, probabilities, confidence };
+    return { observed: false, answer: choice, probabilities, confidence, reason: `confidence ${confidence} is below the threshold ${threshold}` };
+}
+/** A model decider declared `unreachable: "fail"` could not answer, so the ask fails and nothing is written. */
+export class DeciderFailed extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DeciderFailed";
+    }
+}
+/**
+ * Ask a point's deciders in order. A table row answers; a model at or above
+ * its threshold proposes; otherwise the question escalates to the quorum.
+ * Each decider that did not answer is in `escalations`, with why. A model
+ * decider is asked through `ask`; without it, it is not asked.
+ */
+export async function runChain(name, point, inputs, ask) {
+    const escalations = [];
+    for (const d of point.deciders) {
+        if (d.kind === "table") {
+            const row = d.rows.findIndex((r) => matches(r.when, inputs));
+            if (row >= 0) {
+                return { status: "answered", answer: d.rows[row].answer, decider: { kind: "table", row }, ...(d.rows[row].note ? { note: d.rows[row].note } : {}), escalations };
+            }
+            escalations.push({ kind: "table", reason: "no row matches these inputs" });
+        }
+        else if (d.kind === "model") {
+            if (!ask) {
+                escalations.push({ kind: "model", backend: d.backend, model: d.model, threshold: d.threshold, reason: "not asked: no model backend was given to this ask" });
+                continue;
+            }
+            let reply;
+            try {
+                reply = await ask({ point: name, backend: d.backend, model: d.model, question: wireQuestion(point.question), state: inputs });
+            }
+            catch (err) {
+                const why = `${d.backend} could not answer: ${err instanceof Error ? err.message : String(err)}`;
+                if (d.unreachable === "fail")
+                    throw new DeciderFailed(`${name}: ${why}, and the point fails closed (unreachable: "fail")`);
+                escalations.push({ kind: "model", backend: d.backend, model: d.model, threshold: d.threshold, reason: `not observed: ${why}` });
+                continue;
+            }
+            if (reply.model !== d.model) {
+                escalations.push({ kind: "model", backend: d.backend, model: reply.model, threshold: d.threshold, reason: `not observed: ${reply.model} answered, and the point pins ${d.model}` });
+                continue;
+            }
+            const seen = observe(point.question, reply.answer, d.threshold);
+            const why = answerReason(reply.answer);
+            if (seen.observed) {
+                return {
+                    status: "proposed",
+                    answer: seen.answer,
+                    decider: { kind: "model", backend: d.backend, model: reply.model },
+                    probabilities: seen.probabilities,
+                    confidence: seen.confidence,
+                    threshold: d.threshold,
+                    ...(why !== undefined ? { reason: why } : {}),
+                    escalations,
+                };
+            }
+            escalations.push({
+                kind: "model",
+                backend: d.backend,
+                model: reply.model,
+                answer: seen.answer ?? null,
+                ...(seen.probabilities ? { probabilities: seen.probabilities } : {}),
+                ...(seen.confidence !== undefined ? { confidence: seen.confidence } : {}),
+                threshold: d.threshold,
+                reason: `not observed: ${seen.reason}`,
+                ...(why !== undefined ? { model_reason: why } : {}),
+            });
+        }
+        else {
+            return { status: "escalated", decider: { kind: "quorum", count: d.count, ...(d.roles ? { roles: d.roles } : {}) }, escalations };
+        }
+    }
+    // Unreachable for a valid point, which ends in a quorum.
+    return { status: "escalated", decider: { kind: "quorum", count: 1 }, escalations };
+}
+// ── Answers on read ──────────────────────────────────────────────────────────
+/** Why an answer record carries a warning. Closed, like the record warning codes. */
+export const ANSWER_WARNING_CODES = [
+    /** The points file the answer kind names can't be read, or is not valid (#2738). */
+    "answer-points-unreadable",
+    /** The answer's point is not in the points file. */
+    "answer-point-unknown",
+    /** The point's declaration changed since the answer: it answers an older version of the question. */
+    "answer-point-changed",
+];
+/** The points file an answer kind names, from `root` with / separators. */
+export function pointsFileOf(loaded, root) {
+    const abs = resolve(dirname(loaded.file), loaded.kind.answers.points);
+    return relative(root, abs).split(sep).join(posix.sep);
+}
+/** The points an answer kind names, read from `source` (the tree read), or the problems reading them. */
+export function readPointsThrough(source, file) {
+    // A revision's source reads only files in a directory it has listed.
+    const names = source.list(posix.dirname(file));
+    if (!names?.includes(posix.basename(file))) {
+        return { error: `the points file ${file} does not exist${source.label}`, problems: [{ field: null, message: `does not exist${source.label}` }] };
+    }
+    let text;
+    try {
+        text = source.read(file);
+    }
+    catch (err) {
+        return { error: `the points file ${file} can't be read: ${err instanceof Error ? err.message : String(err)}`, problems: [{ field: null, message: "can't be read" }] };
+    }
+    try {
+        return { points: parsePoints(text, file) };
+    }
+    catch (err) {
+        if (err instanceof PointsError)
+            return { error: `the points file is not valid: ${err.message}`, problems: err.problems };
+        throw err;
+    }
+}
+/**
+ * Give an answer kind's records their warnings, in place: the points file
+ * can't be read, the answer's point is gone, or the point changed since. They
+ * never make a record invalid.
+ */
+export function applyAnswers(loaded, entries, options) {
+    const file = pointsFileOf(loaded, options.root);
+    const read = readPointsThrough(options.source, file);
+    for (const e of entries) {
+        if (e.data === null)
+            continue;
+        if ("error" in read) {
+            e.warnings.push({ code: "answer-points-unreadable", message: read.error });
+            continue;
+        }
+        const name = e.data.point;
+        if (typeof name !== "string")
+            continue;
+        const point = pointOf(read.points, name);
+        if (!point) {
+            e.warnings.push({ code: "answer-point-unknown", message: `answers ${name}, which ${file} does not declare` });
+            continue;
+        }
+        if (typeof e.data.point_version === "string" && e.data.point_version !== pointVersion(point)) {
+            e.warnings.push({ code: "answer-point-changed", message: `answers ${name} as it was declared at ${e.data.point_version.slice(0, 12)}, and ${file} declares it at ${pointVersion(point).slice(0, 12)} now: ask again for the question as it stands` });
+        }
+    }
+}