@intentius/chant 0.89.0 → 0.91.0

package/dist/workspace/decide.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Answers to decision points as records (ws-058, #2739).
+ *
+ * {@link askPoint} asks a point's deciders for one set of inputs and records
+ * the answer in the answer kind's records directory, and {@link answerPoint}
+ * records people's answer to an open question. Both write one Markdown record
+ * or none, never commit, and go through the checks every records write goes
+ * through (`records-write.ts`): the record is read back with the kind's schema
+ * before it is written, and no other record may become invalid.
+ *
+ * - A table's answer is `answered`.
+ * - A model's answer at or above its threshold is `proposed`, whatever its
+ *   confidence, with the probabilities, confidence and threshold, until a
+ *   person confirms it. Below the threshold the question is `escalated`.
+ * - A question no decider before the quorum answered is `escalated`: open for
+ *   people, with every decider's reason and any model's answer.
+ *
+ * The same point, declaration and inputs are answered once: the record's id is
+ * the point's name and the first 12 hex digits of the inputs hash. Asking again
+ * returns the record that is there when it is proposed or answered. An
+ * escalated one is asked again, since a backend may answer now, and rewritten
+ * only when the chain no longer escalates.
+ *
+ * chant never calls a model (ws-052): the model call is the caller's
+ * {@link ModelAsk}, such as the decide Op activity (#2740), or a backend's
+ * response the caller already has (`points ask --response`).
+ */
+import { type RecordEntry, type RecordWarning } from "./records.js";
+import { type KindView } from "./records-write.js";
+import { type Escalation, type ModelAsk, type Point } from "./points.js";
+import { type TrustPolicy } from "./trust/policy.js";
+import type { SourceVia } from "./source-block.js";
+/** The version of the write documents `points ask` and `points answer` print. */
+export declare const POINTS_WRITE_CONTRACT_VERSION = 1;
+export declare const POINTS_WRITE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/points-write/v1/points-write.schema.json";
+/** Why `points ask` or `points answer` wrote nothing. Closed: a reader may switch on it. */
+export declare const POINTS_WRITE_ERROR_CODES: readonly ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch", "schema-invalid", "location-missing", "write-usage-invalid", "write-input-invalid", "points-undeclared", "points-invalid", "point-unknown", "point-inputs-invalid", "point-decider-failed", "answer-not-candidate", "quorum-not-met", "record-not-found", "record-closed", "record-id-taken", "record-unparseable", "record-schema-invalid", "record-id-duplicate", "record-supersedes-unknown", "record-supersedes-conflict", "session-seal-mismatch", "session-verdict-unknown-record"];
+export type PointsWriteErrorCode = (typeof POINTS_WRITE_ERROR_CODES)[number];
+export declare class PointsWriteError extends Error {
+    readonly code: PointsWriteErrorCode;
+    constructor(code: PointsWriteErrorCode, message: string);
+}
+/** An answer as the read contract shows it: in `points --json` and in the documents `points ask` and `points answer` print. */
+export interface QuestionView {
+    id: string;
+    /** The record file, from the repository root, with / separators. */
+    path: string;
+    point: string;
+    title: string;
+    /** What the question is about, the record's first `constrains` entry, or null. */
+    subject: string | null;
+    state: "escalated" | "proposed" | "answered";
+    /** Not answered yet: escalated to people, or proposed by a model and waiting for a person to confirm it. */
+    open: boolean;
+    questionType: string;
+    candidates: (string | boolean)[];
+    inputs: Record<string, unknown>;
+    inputsHash: string;
+    pointVersion: string;
+    /** The point's declaration is still the one the question was asked under, or null when the points file no longer declares the point. */
+    current: boolean | null;
+    answer: string | boolean | null;
+    decider: Record<string, unknown>;
+    probabilities: Record<string, number> | null;
+    confidence: number | null;
+    threshold: number | null;
+    /**
+     * Any model answer: the proposal for a proposed question, or for an
+     * escalated one the last model answer below its threshold. null when no
+     * model answered.
+     */
+    model: {
+        answer: string | boolean | null;
+        confidence: number | null;
+        threshold: number | null;
+        model: string | null;
+        backend: string | null;
+        observed: boolean;
+    } | null;
+    escalations: Escalation[];
+    answeredBy: string[];
+    askedOn: string | null;
+    answeredOn: string | null;
+    valid: boolean;
+    warnings: RecordWarning[];
+}
+/** One answer record as a {@link QuestionView}, or null when its front matter can't be read. `point` is its point as declared now, when there is one. */
+export declare function questionView(entry: RecordEntry, point: Point | undefined): QuestionView | null;
+/** What `points ask` and `points answer` print. */
+export type PointsWriteDocument = {
+    $schema: string;
+    contract: number;
+    verb: "ask" | "answer";
+    kind: KindView;
+    id: string;
+    path: string;
+    /** True when the record was already there and nothing new was written. */
+    reused: boolean;
+    /** True when a file was written. False when reused, and with --dry-run. */
+    written: boolean;
+    dryRun: boolean;
+    question: QuestionView;
+    /** With --dry-run, the text the command would write. */
+    text?: string;
+} | {
+    $schema: string;
+    contract: number;
+    verb: "ask" | "answer";
+    error: {
+        code: PointsWriteErrorCode;
+        message: string;
+    };
+};
+/**
+ * The answer kinds a write can go through: the one `kind` names (a file, or a
+ * declared kind's name), or every declared kind with an answers block.
+ */
+export declare function answerKindFiles(cwd: string, kind?: string): Promise<string[]>;
+export interface AskPointOptions {
+    /** Where the kind resolves and the workspace is found. */
+    cwd: string;
+    /** The point's name. */
+    point: string;
+    /** The inputs, keyed by the point's declared input names. */
+    inputs: unknown;
+    /** What the question is about, such as a work item's id: written to `constrains`. */
+    subject?: string;
+    /** The answer kind file, or a declared kind's name. Without it, the declared answer kind whose points file declares the point. */
+    kind?: string;
+    /** The model call. Without it, a model decider is not asked. */
+    ask?: ModelAsk;
+    /** How the answer reached the workspace, for its source block (#2708). Defaults to cli. */
+    via?: SourceVia;
+    /** The client that asked, for its source block. */
+    client?: {
+        name: string;
+        version?: string;
+    };
+    /** The date written as asked_on, and answered_on for a table's answer, YYYY-MM-DD. Defaults to today, in UTC. */
+    on?: string;
+    dryRun?: boolean;
+}
+/**
+ * Ask a point for these inputs, and record the answer: `points ask`. Returns
+ * the record that is there when the same point, declaration and inputs were
+ * answered or proposed before.
+ */
+export declare function askPoint(opts: AskPointOptions): Promise<PointsWriteDocument>;
+export interface AnswerPointOptions {
+    cwd: string;
+    /** The answer record's id. */
+    id: string;
+    /** The people's answer: one of the question's candidates. For a noul, true, false, yes or no. */
+    answer: string | boolean;
+    /** Who answered, as the caller names them. chant does not check who they are; the trust policy says who counts. */
+    by: string[];
+    kind?: string;
+    on?: string;
+    dryRun?: boolean;
+}
+/**
+ * Count `by` toward a point's quorum: distinct people, after normalising,
+ * leaving out anyone holding the agent role in the trust policy at base, and,
+ * when the quorum names roles, anyone holding none of them.
+ */
+export declare function tallyQuorum(by: string[], quorum: {
+    count: number;
+    roles?: string[];
+}, policy: TrustPolicy): {
+    counted: string[];
+    left: {
+        name: string;
+        why: string;
+    }[];
+    met: boolean;
+};
+/**
+ * People answer an open question: `points answer`. A proposed question the
+ * people answer as the model did is confirmed, and keeps the model as its
+ * decider; any other answer is the quorum's, and a model's proposal moves into
+ * the escalations. The question becomes `answered`.
+ */
+export declare function answerPoint(opts: AnswerPointOptions): Promise<PointsWriteDocument>;
+//# sourceMappingURL=decide.d.ts.map

package/dist/workspace/decide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../../src/workspace/decide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,EAA4E,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3I,OAAO,EAWL,KAAK,QAAQ,EAEd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAYL,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,KAAK,EACX,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,iFAAiF;AACjF,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAC/C,eAAO,MAAM,sBAAsB,0FAA0F,CAAC;AAE9H,4FAA4F;AAC5F,eAAO,MAAM,wBAAwB,mjBAsBK,CAAC;AAC3C,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,qBAAa,gBAAiB,SAAQ,KAAK;IAEvC,QAAQ,CAAC,IAAI,EAAE,oBAAoB;gBAA1B,IAAI,EAAE,oBAAoB,EACnC,OAAO,EAAE,MAAM;CAKlB;AAED,+HAA+H;AAC/H,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CAAC;IAC7C,4GAA4G;IAC5G,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,wIAAwI;IACxI,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC7C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACxK,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,yJAAyJ;AACzJ,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,YAAY,GAAG,IAAI,CA4C9F;AAED,mDAAmD;AACnD,MAAM,MAAM,mBAAmB,GAC3B;IACE,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAC;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,YAAY,CAAC;IACvB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GACD;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,oBAAoB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAc1H;;;GAGG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYnF;AAmBD,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;IAChB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kIAAkI;IAClI,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,2FAA2F;IAC3F,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,mDAAmD;IACnD,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,iHAAiH;IACjH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAqED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAgElF;AAQD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,iGAAiG;IACjG,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,mHAAmH;IACnH,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAYD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,MAAM,EAAE,WAAW,GAAG;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAqBtL;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA2FxF"}

package/dist/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/dist/workspace/declaration.d.ts

@@ -96,6 +96,53 @@ export interface RecordKindDeclaration {
     /** The entry's JSON Pointer in the file, for messages. */
     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 declare const DEFAULT_STATE_ROOT = "${XDG_STATE_HOME}/chant/boxes";
 export interface Member {
     type: "member";
     name: string;
@@ -111,6 +158,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[];
@@ -149,6 +198,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;
 }

package/dist/workspace/declaration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"declaration.d.ts","sourceRoot":"","sources":["../../src/workspace/declaration.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"declaration.d.ts","sourceRoot":"","sources":["../../src/workspace/declaration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,OAAO,EAAE,aAAa,EAAqB,MAAM,SAAS,CAAC;AAC3D,OAAO,EAA+B,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEzE,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEtD,eAAO,MAAM,qBAAqB,QAAa,CAAC;AAChD,eAAO,MAAM,iBAAiB,4DAA6D,CAAC;AAC5F,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,gFAAgF;AAChF,eAAO,MAAM,cAAc,qCAAsC,CAAC;AAClE,eAAO,MAAM,YAAY,QAA8B,CAAC;AAIxD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,uNAmBQ,CAAC;AAC3C,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,IAAI,EAAE,kBAAkB;IAEjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa;gBAFxB,IAAI,EAAE,kBAAkB,EACjC,OAAO,EAAE,MAAM,EACN,QAAQ,CAAC,EAAE,aAAa,YAAA;IAMnC,yDAAyD;IACzD,QAAQ,IAAI,MAAM;CAInB;AAID,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,+DAA+D;AAC/D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC;AAEjE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gEAAgE;IAChE,WAAW,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACxC,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,kIAAkI;IAClI,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,oEAAoE;IACpE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,8GAA8G;IAC9G,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,aAAa,EAAE,CAAC;IAC9B,oIAAoI;IACpI,SAAS,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAC1C,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,0HAA0H;AAC1H,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,mEAAmE;AACnE,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,kCAAkC,CAAC;AAElE,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,iHAAiH;IACjH,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,mFAAmF;IACnF,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACzB,yEAAyE;IACzE,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,oEAAoE;IACpE,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,qEAAqE;IACrE,GAAG,EAAE,cAAc,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,aAAa,CAAC;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;AAEnC,MAAM,WAAW,GAAG;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yCAAyC;IACzC,OAAO,EAAE,KAAK,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACtC,+GAA+G;IAC/G,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2HAA2H;IAC3H,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,qDAAqD;IACrD,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;CACd;AAID,wEAAwE;AACxE,eAAO,MAAM,aAAa,qBAAqB,CAAC;AAIhD;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAID,qHAAqH;AACrH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAY5D;AAkED,MAAM,WAAW,WAAW;IAC1B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,+GAA+G;AAC/G,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAMxG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAwB,EAAE,OAAO,GAAE,WAAgB,GAAG,WAAW,CAgNrI;AAmFD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,qBAAqB,EAAE,CAErF;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAG3D;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,SAAK,EAAE,OAAO,GAAE,WAAgB,GAAG,WAAW,CAarG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKzF;AAID,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,qEAAqE;IACrE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uEAAuE;IACvE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,GAAG,aAAa,EAAE,CA8B5F;AAID;;;;;;GAMG;AACH,wBAAgB,OAAO,CACrB,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,aAAa,EAAE,EACvB,IAAI,EAAE,MAAM,GACX;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAWlE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAWlH"}

package/dist/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/dist/workspace/declared-kinds.d.ts

@@ -28,6 +28,18 @@ export interface DeclaredKind {
         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`. */
 export declare function declaredKindFile(declared: RecordKindDeclaration, rootOnDisk: string): string;