@intentius/chant 0.90.0 → 0.91.0

package/src/workspace/checks/boxes.ts

@@ -0,0 +1,307 @@
+/**
+ * The box checks, WSP121 and WSP122 (#2726).
+ *
+ * A member whose entry has a `box` block is a box, or holds a box's
+ * declarations. A box holds no credential: each capability it needs outside
+ * itself (inference, Fountain, a third-party API) is reached through a
+ * broker, a runtime such as a lobby or a door, which holds the credential
+ * and enforces the scope the block declares. chant only states and checks
+ * this; it never runs a broker (ws-052).
+ *
+ * | Id | Code | Fails when |
+ * |---|---|---|
+ * | WSP121 | `box-credential-declared` | a file in the box member's directory carries a literal secret (fixed) |
+ * | WSP122 | `box-capability-unbrokered` | a capability in the block names no broker |
+ *
+ * WSP121 reads the member's files from the tree checked, so it works under
+ * `--at`, and runs no member code. A literal secret is either a value with a
+ * well-known credential shape (an AWS key id, a GitHub or Slack token, an
+ * `sk-` key, private key material), wherever it sits, or a literal string
+ * where a credential goes: under a key named like one (`API_KEY`, `token`,
+ * `credential`, `password`, ...), or the `value` of a `{ key, value }` vault
+ * secret. A reference is never one: `${VAR}` and `$VAR`, a secret-manager
+ * reference (`op://`, `bws://`, `infisical://`), a `{{...}}` template
+ * placeholder, and any expression, such as `process.env.X`, that is not a
+ * string literal. WSP121 is fixed: a credential in a box's files is in git.
+ *
+ * WSP123 and WSP124, box isolation (#2727), are in `./box-isolation.ts` and
+ * listed here after these two.
+ */
+
+import * as ts from "typescript";
+import type { WorkspaceCheck, WorkspaceCheckContext, WorkspaceDiagnostic } from "../checks";
+import type { Member } from "../declaration";
+import type { ReasonCode } from "../reason-codes";
+import { joinPath, skippedDir, type WorkspaceTree } from "../tree";
+import { BOX_ISOLATION_CHECKS } from "./box-isolation";
+
+/** The read contract's codes for the box findings, carried as `code` on each. */
+export const BOX_FINDING_CODES = ["box-credential-declared", "box-capability-unbrokered", "box-isolation-collision", "box-isolation-literal"] as const satisfies readonly ReasonCode[];
+
+export const WSP_BOX_CREDENTIAL = "WSP121";
+export const WSP_BOX_UNBROKERED = "WSP122";
+
+/** Values whose shape alone says they are a credential. The list FTN001 uses, plus Anthropic keys. */
+export const CREDENTIAL_SHAPES: readonly { pattern: RegExp; label: string }[] = [
+  { pattern: /\bAKIA[0-9A-Z]{16}\b/, label: "an AWS access key id" },
+  { pattern: /\b(?:ghp|gho|ghs|ghu)_[A-Za-z0-9]{20,}/, label: "a GitHub token" },
+  { pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}/, label: "a GitHub fine-grained token" },
+  { pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}/, label: "an Anthropic API key" },
+  { pattern: /\bsk-[A-Za-z0-9_-]{20,}/, label: "a secret API key (sk-)" },
+  { pattern: /\bftn_[A-Za-z0-9]{16,}/, label: "a Fountain API key" },
+  { pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}/, label: "a Slack token" },
+  { pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/, label: "private key material" },
+];
+
+/** Secret-manager references a value may be instead of the secret. */
+export const SECRET_REFERENCE_SCHEMES = ["op://", "bws://", "infisical://"] as const;
+
+/**
+ * A key whose value is a credential: `API_KEY`, `GITHUB_TOKEN`, `apiKey`,
+ * `token`, `credential`, `password`, `AWS_SECRET_ACCESS_KEY`. A key that
+ * names where a secret is (`secretKey`, `TOKEN_FILE`, `tokenHash`) is not.
+ */
+const CREDENTIAL_KEY = /(?:^|[_-])(?:API_?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|PRIVATE_?KEY|ACCESS_?KEY)$|^(?:apiKey|token|secret|password|credentials?|privateKey|accessKey|authToken)$|[a-z](?:ApiKey|Token|Secret|Password|Credentials?|PrivateKey|AccessKey)$/i;
+
+/** Whether `key` names a credential. Exported for tests. */
+export function isCredentialKey(key: string): boolean {
+  return CREDENTIAL_KEY.test(key);
+}
+
+/** Whether `value` refers to a secret rather than being one. Exported for tests. */
+export function isSecretReference(value: string): boolean {
+  const v = value.trim();
+  if (v === "") return true;
+  if (v.includes("${")) return true;
+  // $VAR, $1, $(command): the shell fills it in.
+  if (v.startsWith("$")) return true;
+  if (/^\{\{[^}]*\}\}$/.test(v)) return true;
+  return SECRET_REFERENCE_SCHEMES.some((s) => v.startsWith(s));
+}
+
+/**
+ * Whether a value under a credential key says where a secret is rather than
+ * being one: a path (`~/box/llm-token`, `/run/secrets/token`), a URL, or an
+ * environment variable's name (`GIT_TOKEN`).
+ */
+function namesWhereSecretIs(value: string): boolean {
+  const v = value.trim();
+  return /^(?:\/|~|\.\.?\/)/.test(v) || /^[a-z][a-z0-9+.-]*:\/\//i.test(v) || /^[A-Z][A-Z0-9_]*$/.test(v);
+}
+
+/** The credential shape `value` has, or undefined. */
+export function credentialShape(value: string): string | undefined {
+  return CREDENTIAL_SHAPES.find((s) => s.pattern.test(value))?.label;
+}
+
+/** One literal secret found in a file. */
+export interface LiteralSecret {
+  /** 1-based. */
+  line: number;
+  column: number;
+  /** What was found, for the message: never the value itself. */
+  what: string;
+}
+
+const CODE_EXTENSIONS: Record<string, ts.ScriptKind> = {
+  ".ts": ts.ScriptKind.TS,
+  ".mts": ts.ScriptKind.TS,
+  ".cts": ts.ScriptKind.TS,
+  ".tsx": ts.ScriptKind.TSX,
+  ".js": ts.ScriptKind.JS,
+  ".mjs": ts.ScriptKind.JS,
+  ".cjs": ts.ScriptKind.JS,
+  ".jsx": ts.ScriptKind.JSX,
+  ".json": ts.ScriptKind.JSON,
+  ".jsonc": ts.ScriptKind.JSON,
+};
+
+const PROSE_EXTENSIONS = new Set([".md", ".mdx", ".txt", ".html", ".rst"]);
+
+/** Files larger than this are not read: a box's declarations are small, and a large file is data or a build. */
+const MAX_FILE_BYTES = 1024 * 1024;
+
+function propertyName(name: ts.PropertyName | undefined): string | undefined {
+  if (!name) return undefined;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name)) return name.text;
+  return undefined;
+}
+
+const isStringLiteral = (n: ts.Node): n is ts.StringLiteral | ts.NoSubstitutionTemplateLiteral => ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n);
+
+/**
+ * The literal secrets in a TypeScript, JavaScript or JSON file, read as
+ * syntax and never run.
+ */
+export function literalSecretsInCode(text: string, file: string, kind: ts.ScriptKind): LiteralSecret[] {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, kind);
+  const out: LiteralSecret[] = [];
+  const at = (node: ts.Node, what: string) => {
+    const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+    out.push({ line: line + 1, column: character + 1, what });
+  };
+  const reported = new Set<ts.Node>();
+  const visit = (node: ts.Node) => {
+    if (isStringLiteral(node) && !reported.has(node)) {
+      const shape = credentialShape(node.text);
+      if (shape && !isSecretReference(node.text)) {
+        reported.add(node);
+        at(node, shape);
+      }
+    }
+    if (ts.isPropertyAssignment(node) && isStringLiteral(node.initializer) && !reported.has(node.initializer)) {
+      const key = propertyName(node.name);
+      const value = node.initializer.text;
+      // A value with a credential's shape is reported by that shape, below.
+      if (key !== undefined && !isSecretReference(value) && !namesWhereSecretIs(value) && credentialShape(value) === undefined) {
+        if (isCredentialKey(key)) {
+          reported.add(node.initializer);
+          at(node.initializer, `a literal value for ${key}`);
+        } else if (key === "value" && ts.isObjectLiteralExpression(node.parent) && isVaultSecret(node.parent)) {
+          reported.add(node.initializer);
+          at(node.initializer, `a literal vault secret value for ${vaultSecretKey(node.parent) ?? "a key"}`);
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return out;
+}
+
+/** `{ key, value }` with nothing else but a description: the shape of a vault secret. */
+function isVaultSecret(obj: ts.ObjectLiteralExpression): boolean {
+  const names = obj.properties.map((p) => (ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p) ? propertyName(p.name) : undefined));
+  return names.includes("key") && names.includes("value") && names.every((n) => n === "key" || n === "value" || n === "description");
+}
+
+function vaultSecretKey(obj: ts.ObjectLiteralExpression): string | undefined {
+  for (const p of obj.properties) {
+    if (ts.isPropertyAssignment(p) && propertyName(p.name) === "key" && isStringLiteral(p.initializer)) return p.initializer.text;
+  }
+  return undefined;
+}
+
+/** `KEY=value`, `export KEY=value` or `KEY: value`, the value optionally quoted. */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.-]*)\s*[=:]\s*(["']?)([^"'\s#]+)\2\s*(?:#.*)?$/;
+
+/**
+ * The literal secrets in any other text file, such as a shell script, an
+ * env file or YAML: a credential shape anywhere, or a line assigning a
+ * literal to a credential-named key.
+ */
+export function literalSecretsInText(text: string, assignments = true): LiteralSecret[] {
+  const out: LiteralSecret[] = [];
+  text.split(/\r?\n/).forEach((lineText, i) => {
+    for (const { pattern, label } of CREDENTIAL_SHAPES) {
+      const m = pattern.exec(lineText);
+      if (m && !isSecretReference(m[0])) {
+        out.push({ line: i + 1, column: m.index + 1, what: label });
+        return;
+      }
+    }
+    const a = assignments ? ASSIGNMENT.exec(lineText) : null;
+    if (a && isCredentialKey(a[1]) && !isSecretReference(a[3]) && !namesWhereSecretIs(a[3])) {
+      out.push({ line: i + 1, column: lineText.indexOf(a[3]) + 1, what: `a literal value for ${a[1]}` });
+    }
+  });
+  return out;
+}
+
+function extension(path: string): string {
+  const base = path.slice(path.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(dot).toLowerCase() : "";
+}
+
+/** The literal secrets in one file, or none when the file is binary or too large. */
+export function literalSecretsInFile(text: string, path: string): LiteralSecret[] {
+  if (text.length > MAX_FILE_BYTES || text.includes("\0")) return [];
+  const kind = CODE_EXTENSIONS[extension(path)];
+  if (kind !== undefined) return literalSecretsInCode(text, path, kind);
+  // Prose says "Token: ..." without meaning one, so only a credential's shape counts there.
+  return literalSecretsInText(text, !PROSE_EXTENSIONS.has(extension(path)));
+}
+
+/** Every file under `dir` in `tree`, skipping node_modules and dot-directories, sorted. */
+function filesUnder(tree: WorkspaceTree, dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string) => {
+    for (const e of tree.list(d) ?? []) {
+      const p = joinPath(d, e.name);
+      if (e.type === "dir") {
+        if (!skippedDir(e.name)) walk(p);
+      } else out.push(p);
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+const boxMembers = (ctx: WorkspaceCheckContext): Member[] => ctx.declaration.members.filter((m) => m.box !== null);
+
+export const BOX_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_BOX_CREDENTIAL,
+    name: "box-credential-declared",
+    description:
+      "A box holds no credential: no file in a box member's directory carries a literal secret, in its declarations, an env or a vault's defaults. Variable references and secret-manager references (op://, bws://, infisical://) are not secrets.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of boxMembers(ctx)) {
+        const dir = m.dir === "." ? "" : m.dir;
+        if (ctx.tree.stat(dir) !== "dir") continue;
+        for (const path of filesUnder(ctx.tree, dir)) {
+          let text: string;
+          try {
+            text = ctx.tree.read(path);
+          } catch {
+            continue;
+          }
+          for (const s of literalSecretsInFile(text, path)) {
+            out.push({
+              checkId: this.id,
+              severity: this.severity,
+              code: "box-credential-declared",
+              message: `box-credential-declared: ${path} holds ${s.what}, and member ${m.name} is a box, which holds no credential; replace it with a \${VAR} or secret-manager reference, or declare the capability as brokered in the member's box block`,
+              entity: m.name,
+              pointer: m.box!.pointer,
+              treeFile: path,
+              line: s.line,
+              column: s.column,
+            });
+          }
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: WSP_BOX_UNBROKERED,
+    name: "box-capability-unbrokered",
+    description: "Every capability a box declares names the broker that holds its credential and enforces its scope.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of boxMembers(ctx)) {
+        for (const c of m.box!.capabilities) {
+          if (c.broker !== null) continue;
+          out.push({
+            checkId: this.id,
+            severity: this.severity,
+            code: "box-capability-unbrokered",
+            message: `box-capability-unbrokered: member ${m.name}'s box needs ${c.name} and names no broker for it, so the box would hold its credential; set broker to the runtime that holds it, such as the lobby`,
+            entity: m.name,
+            pointer: c.pointer,
+          });
+        }
+      }
+      return out;
+    },
+  },
+  // Box isolation (#2727), WSP123 and WSP124.
+  ...BOX_ISOLATION_CHECKS,
+];

package/src/workspace/checks/records.ts

@@ -14,6 +14,7 @@
  * | WSP113 | a pinned file that a superseding record pins at the old hash: the artifact did not follow the decision |
  * | WSP114 | the records of `--kind` can't be read (fixed) |
  * | WSP115 | a record kind the declaration names is missing or does not load as one (fixed, #2680) |
+ * | WSP116 | an answer kind's decision points file is missing or not valid (fixed, ws-058, #2738) |
  */
 
 import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
@@ -99,4 +100,28 @@ export const RECORD_CHECKS: readonly WorkspaceCheck[] = [
         }));
     },
   },
+  {
+    id: "WSP116",
+    name: "decision-points-invalid",
+    description:
+      "Every answer kind the declaration names has a decision points file that matches decision-points.schema.json: each input names a read-contract output, each table row tests declared inputs and answers a candidate, each model id is pinned, and the chain ends in its one quorum (ws-058).",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const k of ctx.facts?.declaredKinds ?? []) {
+        if (!k.points) continue;
+        const where = k.declared.member === null ? "the workspace" : `member ${k.declared.member}`;
+        const finding = (message: string) => ({
+          checkId: this.id,
+          severity: this.severity,
+          message,
+          ...(k.declared.member !== null ? { entity: k.declared.member } : {}),
+          pointer: `${k.declared.pointer}/kind`,
+        });
+        for (const p of k.points.problems) out.push(finding(`${where} declares the answer kind ${k.declared.kind}, whose points file ${k.points.file} ${p.field ? `has ${p.field}, which ${p.message}` : p.message}`));
+      }
+      return out;
+    },
+  },
 ];

package/src/workspace/checks.test.ts

@@ -60,6 +60,13 @@ describe("the WSP catalog", () => {
       "records-unreadable",
       // A declared record kind that doesn't load breaks every reader's default (#2680).
       "record-kind-unloadable",
+      // An answer kind's points file that isn't valid can't be asked (ws-058).
+      "decision-points-invalid",
+      // A credential in a box's files is in git (#2726).
+      "box-credential-declared",
+      // Two boxes sharing a value, or a box that only holds on one machine, is never the fix (#2727).
+      "box-isolation-collision",
+      "box-isolation-literal",
     ]);
   });
 

package/src/workspace/checks.ts

@@ -28,6 +28,9 @@
  * | WSP101 to WSP106 | generated files |
  * | WSP111 to WSP114 | records read with `--kind` (#2549) |
  * | WSP115 | the record kinds the declaration names (#2680) |
+ * | WSP116 | the decision points file of each declared answer kind (ws-058) |
+ * | WSP121, WSP122 | boxes: no literal credential, every capability brokered (#2726) |
+ * | WSP123, WSP124 | box isolation: no shared port, state path or cookie, no literal machine path (#2727) |
  */
 
 import { realpathSync } from "node:fs";
@@ -45,6 +48,7 @@ import { gatherGeneratedFacts, GENERATED_CHECKS, type GeneratedFileFacts } from
 import { gatherLedgerFacts, LEDGER_CHECKS, type MemberLedgerFacts } from "./checks/ledgers";
 import { gatherPipelineFacts, PIPELINE_CHECKS, type MemberPipelineFacts } from "./checks/pipelines";
 import { RECORD_CHECKS, type RecordFacts } from "./checks/records";
+import { BOX_CHECKS } from "./checks/boxes";
 import { loadDeclaredKinds, type DeclaredKind } from "./declared-kinds";
 
 /**
@@ -87,6 +91,12 @@ export interface WorkspaceDiagnostic extends PostSynthDiagnostic {
   pointer: string;
   /** An absolute path, for a finding about a file other than the declaration, such as a record (#2549). It is reported at its first line. */
   file?: string;
+  /** A path in the tree checked, relative to the workspace root, for a finding about a file there (#2726). It is reported at `line` and `column`. */
+  treeFile?: string;
+  line?: number;
+  column?: number;
+  /** The read contract's code for the finding, when it has one (#2726). */
+  code?: ReasonCode;
 }
 
 export interface WorkspaceCheck {
@@ -104,7 +114,7 @@ export interface WorkspaceCheck {
 /** A diagnostic ready for lint's reporters, with the entry it is about. */
 export interface WorkspaceFinding extends LintDiagnostic {
   entity?: string;
-  /** The read contract's reason code, for a WSP001 finding: why the declaration can't be read (#2536). */
+  /** The read contract's reason code: for a WSP001 finding, why the declaration can't be read (#2536); for a box check, its finding code (#2726). */
   code?: ReasonCode;
 }
 
@@ -307,6 +317,8 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   ...GENERATED_CHECKS,
   // Records read with --kind (#2549).
   ...RECORD_CHECKS,
+  // Boxes and their brokered capabilities (#2726).
+  ...BOX_CHECKS,
 ];
 
 const BY_ID = new Map(WORKSPACE_CHECKS.map((c) => [c.id, c]));
@@ -459,11 +471,16 @@ export async function runDeclarationChecks(
   const locate = (pointer: string): TextLocation => (parsed.ok ? parsed.locate(pointer) : { line: 1, column: 1 });
   const file = display(declaration.file);
   const toFinding = (d: WorkspaceDiagnostic): WorkspaceFinding => ({
-    ...(d.file !== undefined ? { file: display(relative(root, d.file).split(sep).join("/")), line: 1, column: 1 } : { file, ...locate(d.pointer) }),
+    ...(d.treeFile !== undefined
+      ? { file: display(d.treeFile), line: d.line ?? 1, column: d.column ?? 1 }
+      : d.file !== undefined
+        ? { file: display(relative(root, d.file).split(sep).join("/")), line: 1, column: 1 }
+        : { file, ...locate(d.pointer) }),
     ruleId: d.checkId,
     severity: d.severity,
     message: d.message,
     ...(d.entity !== undefined ? { entity: d.entity } : {}),
+    ...(d.code !== undefined ? { code: d.code } : {}),
   });
   const order = (a: LintDiagnostic, b: LintDiagnostic) => a.line - b.line || a.column - b.column || (a.ruleId < b.ruleId ? -1 : a.ruleId > b.ruleId ? 1 : 0);
   const diagnostics = active.map(toFinding).sort(order);

package/src/workspace/decide.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Answers to decision points as records (ws-058, #2739), with a stub model
+ * decider, on a workspace in a throwaway git repository: `points ask` and
+ * `points answer` as `decide.ts` runs them, `points --json` as
+ * `points-cli.ts` prints it, and WSP116 in `check`.
+ */
+
+import { cpSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "./checks";
+import { cleanScratch, commitAll, contract, REPO, repo } from "./__fixtures__/contract-repo";
+import { answerPoint, askPoint, type PointsWriteDocument } from "./decide";
+import pointAnswerSchema from "./point-answer.schema.json";
+import { workspacePoints } from "./points-cli";
+import pointsSchema from "./points.schema.json";
+import pointsWriteSchema from "./points-write.schema.json";
+import type { ModelAsk, WireAnswer } from "./points";
+import { queryRecords } from "./records-cli";
+
+const REF = join(REPO, "reference-workspace");
+const POINTS = JSON.parse(readFileSync(join(REF, "decisions", "points.json"), "utf-8")) as { points: Record<string, unknown> };
+
+const points = {
+  points: {
+    ...POINTS.points,
+    "needs-decision": {
+      title: "Does this change need a decision",
+      question: { type: "noul", instructions: "Does the change make a choice nobody has recorded?", criteria: { true: "It needs a decision.", false: "It does not." } },
+      inputs: { commit: "the commit, as graph --intent lists it" },
+      deciders: [
+        { kind: "model", backend: "systemone", model: "jev-1.13.0", threshold: 0.8 },
+        { kind: "quorum", count: 2, roles: ["lead"] },
+      ],
+    },
+  },
+};
+
+const write = contract(pointsWriteSchema);
+const read = contract(pointsSchema);
+
+let root: string;
+const on = "2026-09-25";
+
+/** A stub model decider answering every point with `answer`, at the pinned model. */
+const stub =
+  (answer: WireAnswer): ModelAsk =>
+  async (req) => ({ model: req.model, answer });
+
+const big = { "work-item.criteria": 9, "work-item.fits_small": false, "work-item.fits_medium": false };
+const confident: WireAnswer = { type: "choice", choice: "large", probabilities: { small: 0.01, medium: 0.07, large: 0.92 }, confidence: 0.88 };
+const unsure: WireAnswer = { type: "choice", choice: "medium", probabilities: { small: 0.2, medium: 0.45, large: 0.35 }, confidence: 0.175 };
+
+function ok(doc: PointsWriteDocument): Extract<PointsWriteDocument, { question: unknown }> {
+  write.expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+function refused(doc: PointsWriteDocument): string {
+  write.expectValid(doc);
+  if (!("error" in doc)) throw new Error("expected a refusal");
+  return doc.error.code;
+}
+
+const answers = () => readdirSync(join(root, "answers")).filter((f) => f.endsWith(".md")).sort();
+const fm = (path: string) => readFileSync(join(root, path), "utf-8");
+
+beforeAll(() => {
+  root = repo(
+    {
+      "chant.workspace.json": JSON.stringify(
+        { name: "studio", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "a plain Node server" }], records: [{ kind: "answers/answer.kind.mjs" }] },
+        null,
+        2,
+      ),
+      "app/server.mjs": "export const port = 8080;\n",
+      "decisions/points.json": JSON.stringify(points, null, 2),
+      ".chant/trust.json": JSON.stringify({ schema: 1, roles: { agent: ["bot"], lead: ["alice", "bob", "bot"] } }),
+    },
+    false,
+  );
+  cpSync(join(REF, "answers", "answer.kind.mjs"), join(root, "answers", "answer.kind.mjs"), { recursive: true });
+  cpSync(join(REF, "answers", "answer.schema.json"), join(root, "answers", "answer.schema.json"));
+  commitAll(root, "c0");
+});
+
+afterAll(cleanScratch);
+
+describe("points ask (#2739)", () => {
+  test("a table's answer is answered at once", async () => {
+    const doc = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: { "work-item.fits_small": true }, subject: "W-001", on }));
+    expect(doc.question).toMatchObject({ state: "answered", open: false, answer: "small", decider: { kind: "table", row: 0 }, subject: "W-001", answeredOn: on, model: null });
+    expect(doc.written).toBe(true);
+  });
+
+  test("a model answer at or above its threshold is written as proposed, with its values and source", async () => {
+    const doc = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: big, subject: "W-002", ask: stub(confident), on }));
+    expect(doc.question).toMatchObject({
+      state: "proposed",
+      open: true,
+      answer: "large",
+      decider: { kind: "model", backend: "systemone", model: "bosun-v3.1-1.7b" },
+      probabilities: { small: 0.01, medium: 0.07, large: 0.92 },
+      confidence: 0.88,
+      threshold: 0.8,
+      model: { answer: "large", confidence: 0.88, threshold: 0.8, observed: true },
+      escalations: [{ kind: "table", reason: "no row matches these inputs" }],
+    });
+    expect(doc.id).toBe(`slice-tier-${doc.question.inputsHash.slice(0, 12)}`);
+    expect(fm(doc.path)).toContain('source:\n  via: "cli"\n  model: "bosun-v3.1-1.7b"');
+    const records = await queryRecords({ kind: "answers/answer.kind.mjs", cwd: root });
+    if ("error" in records) throw new Error(records.error.message);
+    expect(records.records.find((r) => r.id === doc.id)).toMatchObject({ valid: true, state: "proposed", warnings: [] });
+  });
+
+  test("asking again with the same inputs returns the existing record", async () => {
+    const before = answers();
+    const first = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: big, subject: "W-002", ask: stub(unsure), on }));
+    // Key order does not matter: the inputs hash over canonical JSON.
+    const again = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: Object.fromEntries(Object.entries(big).reverse()), ask: stub(unsure) }));
+    for (const d of [first, again]) expect(d).toMatchObject({ reused: true, written: false, question: { state: "proposed", answer: "large" } });
+    expect(answers()).toEqual(before);
+  });
+
+  test("below its threshold the question is escalated and listed as open for a quorum, with the model's answer", async () => {
+    const doc = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: { ...big, "work-item.criteria": 12 }, subject: "W-003", ask: stub(unsure), on }));
+    expect(doc.question).toMatchObject({ state: "escalated", open: true, answer: null, decider: { kind: "quorum", count: 1 } });
+    expect(fm(doc.path)).not.toMatch(/^answer:/m);
+    const listed = await workspacePoints({ cwd: root, open: true });
+    read.expectValid(listed);
+    if ("error" in listed) throw new Error(listed.error.message);
+    const q = listed.questions.find((x) => x.id === doc.id)!;
+    expect(q).toMatchObject({ state: "escalated", open: true, current: true, model: { answer: "medium", confidence: 0.175, threshold: 0.8, model: "bosun-v3.1-1.7b", observed: false } });
+    expect(q.escalations.map((e) => e.reason)).toEqual(["no row matches these inputs", "not observed: confidence 0.175 is below the threshold 0.8"]);
+    expect(listed.questions.every((x) => x.open)).toBe(true);
+    expect(listed.points.map((p) => p.name)).toEqual(["slice-tier", "ship-skip", "needs-decision"]);
+    expect(listed.points[0].inputs[0]).toEqual({ name: "work-item.criteria", output: "work-item", description: "acceptance criteria in the work item" });
+
+    // A later ask still escalating keeps the standing record; one a model answers rewrites it, as proposed.
+    const still = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: { ...big, "work-item.criteria": 12 } }));
+    expect(still).toMatchObject({ reused: true, question: { state: "escalated" } });
+    const now = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: { ...big, "work-item.criteria": 12 }, ask: stub(confident), on }));
+    expect(now).toMatchObject({ id: doc.id, path: doc.path, reused: false, question: { state: "proposed", subject: "W-003", answer: "large" } });
+  });
+
+  test("with --dry-run nothing is written, and the text is returned", async () => {
+    const before = answers();
+    const doc = ok(await askPoint({ cwd: root, point: "ship-skip", inputs: { "release.units": 3 }, dryRun: true, on }));
+    expect(doc).toMatchObject({ written: false, dryRun: true, question: { state: "answered", answer: false } });
+    expect((doc as { text?: string }).text).toContain("answer: false");
+    expect(answers()).toEqual(before);
+  });
+
+  test("refusals: an unknown point, undeclared inputs, a closed-failing backend", async () => {
+    expect(refused(await askPoint({ cwd: root, point: "nope", inputs: {} }))).toBe("point-unknown");
+    expect(refused(await askPoint({ cwd: root, point: "slice-tier", inputs: { "contract.size": 3 } }))).toBe("point-inputs-invalid");
+    expect(refused(await askPoint({ cwd: root, point: "slice-tier", inputs: [] }))).toBe("point-inputs-invalid");
+  });
+});
+
+describe("points answer (#2739)", () => {
+  test("a person confirms a model's proposal, which keeps the model as its decider", async () => {
+    const asked = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: big, ask: stub(confident) }));
+    const doc = ok(await answerPoint({ cwd: root, id: asked.id, answer: "large", by: ["alice"], on }));
+    expect(doc.question).toMatchObject({ state: "answered", open: false, answer: "large", decider: { kind: "model", model: "bosun-v3.1-1.7b" }, confidence: 0.88, answeredBy: ["alice"], answeredOn: on });
+    expect(refused(await answerPoint({ cwd: root, id: asked.id, answer: "small", by: ["alice"] }))).toBe("record-closed");
+    // Asking again returns the confirmed answer.
+    expect(ok(await askPoint({ cwd: root, point: "slice-tier", inputs: big, ask: stub(unsure) }))).toMatchObject({ reused: true, question: { state: "answered" } });
+  });
+
+  test("people answering otherwise is the quorum's answer, and the proposal moves into the escalations", async () => {
+    const asked = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: { ...big, "work-item.criteria": 4 }, ask: stub(confident), on }));
+    expect(refused(await answerPoint({ cwd: root, id: asked.id, answer: "tiny", by: ["alice"] }))).toBe("answer-not-candidate");
+    const doc = ok(await answerPoint({ cwd: root, id: asked.id, answer: "medium", by: ["bob"], on }));
+    expect(doc.question).toMatchObject({ state: "answered", answer: "medium", decider: { kind: "quorum", count: 1, by: ["bob"] }, probabilities: null, confidence: null });
+    expect(doc.question.escalations.at(-1)).toMatchObject({ kind: "model", answer: "large", confidence: 0.88, reason: "proposed large, and people answered medium" });
+  });
+
+  test("the quorum counts distinct people holding its roles, never an agent", async () => {
+    const asked = ok(await askPoint({ cwd: root, point: "needs-decision", inputs: { commit: { sha: "abc" } }, ask: stub({ type: "noul", noul: 0.55 }), on }));
+    expect(asked.question).toMatchObject({ state: "escalated", model: { answer: true, confidence: 0.55, observed: false } });
+    expect(refused(await answerPoint({ cwd: root, id: asked.id, answer: "yes", by: ["alice", "Alice ", "bot", "carol"] }))).toBe("quorum-not-met");
+    const doc = ok(await answerPoint({ cwd: root, id: asked.id, answer: "yes", by: ["alice", "bob"], on }));
+    expect(doc.question).toMatchObject({ state: "answered", answer: true, decider: { kind: "quorum", count: 2, roles: ["lead"], by: ["alice", "bob"] } });
+  });
+
+  test("an unknown id is refused", async () => {
+    expect(refused(await answerPoint({ cwd: root, id: "slice-tier-000000000000", answer: "small", by: ["alice"] }))).toBe("record-not-found");
+  });
+
+  test("every record written follows point-answer.schema.json, and the reference workspace carries a copy of it", () => {
+    expect(JSON.parse(readFileSync(join(REF, "answers", "answer.schema.json"), "utf-8"))).toEqual(pointAnswerSchema);
+    expect(answers().length).toBeGreaterThan(3);
+  });
+});
+
+describe("the points file in check and on read (#2738)", () => {
+  test("a changed point warns on its answers, and an invalid points file is WSP116 and a points-invalid source", async () => {
+    const file = join(root, "decisions", "points.json");
+    const changed = JSON.parse(readFileSync(file, "utf-8"));
+    changed.points["slice-tier"].title = "Which builder builds this work item";
+    writeFileSync(file, JSON.stringify(changed, null, 2));
+    const doc = await workspacePoints({ cwd: root });
+    read.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const slice = doc.questions.filter((q) => q.point === "slice-tier");
+    expect(slice.every((q) => q.current === false && q.warnings.some((w) => w.code === "answer-point-changed"))).toBe(true);
+    expect((await runDeclarationChecks(root)).diagnostics.filter((d) => d.ruleId === "WSP116")).toEqual([]);
+
+    changed.points["slice-tier"].deciders.pop();
+    writeFileSync(file, JSON.stringify(changed, null, 2));
+    const report = await runDeclarationChecks(root);
+    expect(report.diagnostics.filter((d) => d.ruleId === "WSP116").map((d) => d.message)).toEqual([
+      "the workspace declares the answer kind answers/answer.kind.mjs, whose points file decisions/points.json has points.slice-tier.deciders, which must end in a quorum: when no table row or model answers, people do",
+    ]);
+    expect(report.ok).toBe(false);
+    const broken = await workspacePoints({ cwd: root });
+    read.expectValid(broken);
+    if ("error" in broken) throw new Error(broken.error.message);
+    expect(broken.sources[0].reason?.code).toBe("points-invalid");
+    expect(refused(await askPoint({ cwd: root, point: "slice-tier", inputs: big }))).toBe("points-invalid");
+  });
+});