@intentius/chant 0.90.0 → 0.93.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,20 @@
         "$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"
+      }
+    },
+    "diagrams": {
+      "type": "array",
+      "description": "The workspace's own diagram artifacts (#2764): the diagrams that belong to no one member, such as a diagrams directory at the root. A member names its own in its diagrams. chant workspace ls lists every declared diagram, and chant workspace check reports one whose render is stale for its source when the entry records a sourceHash. 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/diagram"
+      }
+    },
     "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.",
@@ -65,6 +79,28 @@
       "additionalProperties": {
         "$ref": "#/$defs/severity"
       }
+    },
+    "changes": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The forward coverage check, chant workspace check --changes <base>..<head> (#2773): each path a diff changes is mapped to the current records whose constrains cover it. severity says what a finding does: off reports none, warn (the default) reports them and passes, fail reports them and fails. ignore lists globs over files whose changes need no record, such as lockfiles and generated output. Added in schema 1 by chant 0.92.0, so a declaration that uses it sets minReader to 0.92.0 or newer.",
+      "properties": {
+        "severity": {
+          "enum": [
+            "off",
+            "warn",
+            "fail"
+          ],
+          "description": "What a change-uncovered or change-out-of-scope finding does. warn when absent."
+        },
+        "ignore": {
+          "type": "array",
+          "description": "Globs over file paths from the workspace root: * and ? within one segment, ** across segments. A changed path one matches is listed as ignored and never reported.",
+          "items": {
+            "$ref": "#/$defs/fileGlob"
+          }
+        }
+      }
     }
   },
   "patternProperties": {
@@ -269,6 +305,16 @@
             "$ref": "#/$defs/recordKind"
           }
         },
+        "diagrams": {
+          "type": "array",
+          "description": "The diagram artifacts this member holds (#2764). chant workspace ls lists every declared diagram, and chant workspace check reports one whose render is stale for its source when the entry records a sourceHash. 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/diagram"
+          }
+        },
+        "box": {
+          "$ref": "#/$defs/box"
+        },
         "upstream": {
           "type": "string",
           "minLength": 1,
@@ -354,6 +400,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). A member that builds the fountain lexicon's Box declares the callback token fountain gives its persistent sandbox as the capability fountain-callback, brokered by fountain, with scope owner, or chant workspace check fails (WSP125, #2780). 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.",
@@ -375,6 +529,78 @@
       },
       "additionalProperties": false
     },
+    "diagram": {
+      "type": "object",
+      "description": "A diagram artifact the workspace declares (#2764): a rendered image with a source, pinned to the renderer that made it. chant never runs the renderer.",
+      "required": [
+        "name",
+        "title",
+        "render",
+        "renderer"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/$defs/name",
+          "description": "Unique across the declaration."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Shown above the diagram."
+        },
+        "source": {
+          "oneOf": [
+            { "$ref": "#/$defs/path" },
+            { "type": "null" }
+          ],
+          "description": "The source file, from the workspace root, with / separators. Null for an SVG with no source. Default null."
+        },
+        "render": {
+          "$ref": "#/$defs/path",
+          "description": "The rendered image, from the workspace root, with / separators."
+        },
+        "renderer": {
+          "$ref": "#/$defs/diagramRenderer"
+        },
+        "sourceHash": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "sha256 hex of the source's bytes when render was last produced from it. chant workspace check compares this against the source in the tree read and reports drift (WSP133) on a mismatch; without it, or without a source, the render is never checked for drift. Default null."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
+    "diagramRenderer": {
+      "type": "object",
+      "description": "The renderer a diagram's render was made with. chant records the pin; it never installs or runs the renderer (ws-052).",
+      "required": [
+        "tool",
+        "version"
+      ],
+      "properties": {
+        "tool": {
+          "enum": ["d2", "mermaid", "graphviz"]
+        },
+        "version": {
+          "$ref": "#/$defs/version",
+          "description": "The exact release the render was made with, such as 0.9.0."
+        },
+        "args": {
+          "type": "array",
+          "description": "Passed before the input and output paths, in order, such as [\"--layout=elk\", \"--theme=0\", \"--pad=40\", \"--omit-version\"]. Empty when absent.",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
     "generatedFile": {
       "type": "object",
       "description": "One generated file of a member (#2524 D14, #2541).",
@@ -469,6 +695,65 @@
           "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
+    },
+    "fileGlob": {
+      "type": "string",
+      "description": "A glob over file paths, relative to the workspace root: * and ? within one segment, ** across segments, [...] classes and {a,b} alternatives. No leading /, no . or .. segments.",
+      "pattern": "^(?!\\.\\.?(/|$))[^/\\\\]+(/(?!\\.\\.?(/|$))[^/\\\\]+)*$"
     }
   }
 }

package/src/workspace/declaration.test.ts

@@ -6,6 +6,7 @@ import { afterAll, describe, expect, test } from "vitest";
 import {
   compareVersions,
   DECLARATION_SCHEMA_ID,
+  declaredDiagrams,
   ownerOf,
   parseDeclaration,
   readDeclaration,
@@ -345,3 +346,60 @@ describe("generated files (#2541)", () => {
     expect(failure(base([{ name: "g", kind: "examples", glob: "examples/*", generated: [] }])).message).toContain('unknown field "generated"');
   });
 });
+
+describe("diagram artifacts (#2764)", () => {
+  const renderer = { tool: "d2", version: "0.9.0", args: ["--layout=elk", "--theme=0", "--pad=40", "--omit-version"] };
+  const diagram = (extra: Record<string, unknown> = {}) => ({
+    name: "architecture",
+    title: "Studio architecture",
+    source: "docs/diagrams/architecture.d2",
+    render: "docs/diagrams/architecture.svg",
+    renderer,
+    ...extra,
+  });
+  const member = (diagrams: unknown[], extra: Record<string, unknown> = {}) => ({ name: "docs", dir: "docs", kind: "other", because: "the docs site", diagrams, ...extra });
+
+  test("a member's diagram is read with the workspace-relative source and render, and a null source is the default", () => {
+    const d = parse(base([member([diagram()])]));
+    expect(d.members[0].diagrams).toEqual([
+      { name: "architecture", title: "Studio architecture", source: "docs/diagrams/architecture.d2", render: "docs/diagrams/architecture.svg", renderer, sourceHash: null, member: "docs", pointer: "/members/0/diagrams/0" },
+    ]);
+    const noSource = parse(base([member([diagram({ source: undefined })])]));
+    expect(noSource.members[0].diagrams[0].source).toBeNull();
+  });
+
+  test("the workspace's own diagrams are in the top-level diagrams, with member null", () => {
+    const d = parse(base([{ name: "x", dir: "x", kind: "chant" }], { diagrams: [diagram({ name: "boundary" })] }));
+    expect(d.diagrams).toEqual([{ ...diagram({ name: "boundary" }), sourceHash: null, member: null, pointer: "/diagrams/0" }]);
+    expect(declaredDiagrams(d)).toEqual(d.diagrams);
+  });
+
+  test("declaredDiagrams lists the workspace's own first, then each member's, in file order", () => {
+    const d = parse(base([member([diagram()]), { name: "app", dir: "app", kind: "chant" }], { diagrams: [diagram({ name: "boundary", render: "docs/diagrams/boundary.svg" })] }));
+    expect(declaredDiagrams(d).map((x) => x.name)).toEqual(["boundary", "architecture"]);
+  });
+
+  test("a diagram name is unique across the declaration, workspace and members together", () => {
+    const clash = failure(base([member([diagram()])], { diagrams: [diagram()] }));
+    expect(clash.code).toBe("declaration-invalid");
+    expect(clash.message).toContain('the diagram name "architecture" is already used by the diagram at /diagrams/0');
+  });
+
+  test("renderer.tool is a closed list, and title, render and renderer are required", () => {
+    expect(failure(base([member([diagram({ renderer: { tool: "mscgen", version: "1.0.0" } })])])).code).toBe("declaration-invalid");
+    expect(failure(base([member([{ name: "a", source: null, render: "a.svg", renderer }])])).message).toContain('missing required field "title"');
+    expect(failure(base([member([{ name: "a", title: "A", source: null, renderer }])])).message).toContain('missing required field "render"');
+    expect(failure(base([member([{ name: "a", title: "A", source: null, render: "a.svg" }])])).message).toContain('missing required field "renderer"');
+  });
+
+  test("a sourceHash is a 64-character lowercase hex string, or absent", () => {
+    const hash = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+    expect(parse(base([member([diagram({ sourceHash: hash })])])).members[0].diagrams[0].sourceHash).toBe(hash);
+    expect(failure(base([member([diagram({ sourceHash: "not-a-hash" })])])).code).toBe("declaration-invalid");
+  });
+
+  test("source and render stay inside the workspace, like every other path", () => {
+    expect(failure(base([member([diagram({ source: "/etc/passwd" })])])).code).toBe("declaration-invalid");
+    expect(failure(base([member([diagram({ render: "../out.svg" })])])).code).toBe("declaration-invalid");
+  });
+});