@intentius/chant 0.100.0 → 0.102.0

package/src/workspace/declaration.ts

@@ -107,6 +107,72 @@ export interface ChangesPolicy {
   ignore: string[];
 }
 
+/** The core principal classes (#2524 D5). A pinned package may supply domain classes too (#3080, `principal-classes.ts`). */
+export const PRINCIPAL_CLASSES = ["human", "agent", "runner", "service"] as const;
+export type CorePrincipalClass = (typeof PRINCIPAL_CLASSES)[number];
+/** A class name: a core class, or a domain class a pinned package supplies (#3080). */
+export type PrincipalClass = string;
+
+/** How a record is written, as the records commands name it (#2548). */
+export const WRITE_VERBS = ["new", "amend", "review", "close"] as const;
+export type WriteVerb = (typeof WRITE_VERBS)[number];
+
+/** One principal class's entry in the declaration's `writeScope` (#2548, ws-067). */
+export interface ClassScope {
+  /** The members whose files the class may write, or null for every path. Always null for the agent class: a session writes its own member. */
+  members: string[] | null;
+  /** Kind name to the verbs the class may write it with, or null for every kind in reach with every verb. */
+  records: Record<string, WriteVerb[]> | null;
+  /** Paths the class may not write even inside a member it may (#3146, ws-077), in file order. Empty when the entry lists none. */
+  protected: ProtectedPath[];
+  pointer: string;
+}
+
+/**
+ * A protected path in a write scope (#3146, ws-077): a glob from the
+ * workspace root. It protects the files it matches and everything under a
+ * directory it matches. `except` names top-level keys of a JSON file a write
+ * may still change; empty when the entry allows none.
+ */
+export interface ProtectedPath {
+  path: string;
+  except: string[];
+}
+
+/**
+ * The declaration's `writeScope` block: an entry per restricted class, in
+ * file order. A class with no entry is not restricted. A key may name a
+ * domain class a pinned package supplies (#3080); whether one does is known
+ * only once the pins are read, so an unknown key is judged where the scope
+ * is applied, not here.
+ */
+export type WriteScope = Record<PrincipalClass, ClassScope>;
+
+/** A gate the declaration's `identity.gates` names (#3163, ws-080): it passes only on a signed approval. */
+export interface SignedGate {
+  gate: string;
+  /** The class the signer must be in, or null for any signer the signers file at base lists. */
+  class: PrincipalClass | null;
+  pointer: string;
+}
+
+/** The declaration's `identity` block (#3163, ws-080), read at base. */
+export interface IdentityPolicy {
+  /** `identified`: a person-attributed write must name a forge identity, a signer at base, or an agent, runner or service principal. */
+  attribution: "any" | "identified";
+  /** By gate name. */
+  gates: Record<string, SignedGate>;
+}
+
+/** An agent session the declaration names (#2524 D20, #2548): bound to one member. */
+export interface AgentDeclaration {
+  name: string;
+  member: string;
+  /** Principals that write only as this session. */
+  principals: string[];
+  pointer: string;
+}
+
 export interface MemberRole {
   name: string;
   /** Relative to the member's directory, or null for the whole member. */
@@ -135,6 +201,8 @@ export interface LinkDeclaration {
   output: string;
   /** The link kind as written, or null for the default (`output`). */
   kind: string | null;
+  /** A telemetry link's OTLP protocol as written (#2558), or null. */
+  protocol: string | null;
   /** The link's JSON Pointer in the file, for messages. */
   pointer: string;
 }
@@ -223,10 +291,63 @@ export interface BoxDeclaration {
    * `spriteApplyServices` read them with `box: true`.
    */
   services: BoxService[];
+  /** What the box builds and how (#3146, ws-077), or null when the block declares no factory. */
+  factory: BoxFactory | null;
+  /** What the box shows of itself on a home site (#3146), or null when the block declares no listing. */
+  listing: BoxListing | null;
+  /** The block's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
+/** What a check command is (#3146). */
+export const FACTORY_CHECK_KINDS = ["test", "build", "lint", "plan", "conformance"] as const;
+export type FactoryCheckKind = (typeof FACTORY_CHECK_KINDS)[number];
+
+/**
+ * A box's factory (#3146, ws-077): what it builds, how a build is checked,
+ * which member declares the builder agents and where a finished build is
+ * published. Defaults are filled in, so a reader never guesses one.
+ */
+export interface BoxFactory {
+  /** The members the factory builds, in file order; at least one. */
+  builds: string[];
+  /** The verdict command, run from the workspace root, or null when none is declared. */
+  check: { run: string; kind: FactoryCheckKind } | null;
+  /** Where a work item's builder writes its check, from the workspace root, or null for the orchestrator's choice. */
+  checks: string | null;
+  /** The member that declares the builder agents, or null when none is named. */
+  builders: string | null;
+  /** Where a finished build is published, or null when the factory doesn't publish past the box. */
+  publish: FactoryPublish | null;
   /** The block's JSON Pointer in the file, for messages. */
   pointer: string;
 }
 
+/** Where a finished build goes (#3146): its branch is pushed and a pull request opened against `repo`'s `base`. */
+export interface FactoryPublish {
+  forge: "github";
+  /** owner/name. */
+  repo: string;
+  /** The branch the pull request targets, or null for the repository's default branch. */
+  base: string | null;
+  /** What the published branch's name starts with, before the work item's id. */
+  branchPrefix: string;
+  /** The repository the branch is pushed to when it isn't `repo` (a fork), as owner/name, or null. */
+  head: string | null;
+}
+
+/** The branch prefix a publish target uses when it names none: the work lease's own branch. */
+export const DEFAULT_PUBLISH_BRANCH_PREFIX = "chant/work/";
+
+/** What a box shows of itself (#3146, #3154). */
+export interface BoxListing {
+  published: boolean;
+  title: string;
+  line: string;
+  /** The cover image, from the workspace root, or null. */
+  cover: string | null;
+}
+
 /** A service a box runs under its supervisor (#2880). */
 export interface BoxService {
   /** Unique in the box. */
@@ -292,6 +413,8 @@ export interface Member {
   box: BoxDeclaration | null;
   upstream: string | null;
   because: string | null;
+  /** Whether `chant workspace export` takes the member (#2552, D10). False when the entry does not say. */
+  travel: boolean;
   suppress: Suppression[];
   /** The entry's JSON Pointer in the file, for messages. */
   pointer: string;
@@ -338,6 +461,12 @@ export interface Declaration {
   hosts: Host[];
   /** The forward coverage check's policy (#2773), or null when the declaration has no `changes` block. */
   changes: ChangesPolicy | null;
+  /** Who may write what (#2548), or null when the declaration has no `writeScope` block. */
+  writeScope: WriteScope | null;
+  /** The agent sessions, in file order (#2548). */
+  agents: AgentDeclaration[];
+  /** Who a person-attributed write may name, and which gates need a signed approval (#3163), or null when the declaration has no `identity` block. */
+  identity: IdentityPolicy | null;
   /** The file, relative to the workspace root's tree (`chant.workspace.json` or `.jsonc`). */
   file: string;
 }
@@ -543,10 +672,11 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       handWritten: g.handWritten ? { because: (g.handWritten as { because: string }).because } : null,
       pointer: `${pointer}/generated/${j}`,
     }));
-    const links = ((e.links as { member: string; output: string; kind?: string }[] | undefined) ?? []).map((l, j) => ({
+    const links = ((e.links as { member: string; output: string; kind?: string; protocol?: string }[] | undefined) ?? []).map((l, j) => ({
       member: l.member,
       output: l.output,
       kind: l.kind ?? null,
+      protocol: l.protocol ?? null,
       pointer: `${pointer}/links/${j}`,
     }));
     const records = recordKindsOf(e.records, e.dir as string, e.name as string, `${pointer}/records`);
@@ -566,6 +696,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       box,
       upstream: (e.upstream as string | undefined) ?? null,
       because: (e.because as string | undefined) ?? null,
+      travel: e.travel === true,
       suppress,
       pointer,
     };
@@ -660,6 +791,9 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     const problem = m.box ? boxServicesProblem(m.name, m.box.services) : null;
     if (problem) throw new WorkspaceReadError("declaration-invalid", problem.message, at(problem.pointer));
   }
+  // One factory, building and naming declared members (#3146).
+  const factory = factoryProblem(members);
+  if (factory) throw new WorkspaceReadError("declaration-invalid", factory.message, at(factory.pointer));
 
   // A diagram name is given once across the declaration (#2764): a reader keys diagrams by name.
   const ownDiagrams = diagramsOf(obj.diagrams, null, "/diagrams");
@@ -673,6 +807,8 @@ export function parseDeclaration(text: string, file: string, reader: string = re
   }
 
   const hosts = hostsOf(obj, members, at);
+  const writeScope = writeScopeOf(obj.writeScope, members, at);
+  const agents = agentsOf(obj.agents, members, at);
 
   const pins = ((obj.pins as Record<string, string>[] | undefined) ?? []).map((p) => ({
     package: p.package ?? null,
@@ -695,10 +831,86 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     diagrams: ownDiagrams,
     hosts,
     changes: changesOf(obj.changes as Record<string, unknown> | undefined),
+    writeScope,
+    agents,
+    identity: identityOf(obj.identity),
     file,
   };
 }
 
+/**
+ * The `writeScope` block, already validated, with the rule the schema can't
+ * say (#2548): a member it names is a declared member. Its keys are kept in
+ * file order: the core classes and any domain class (#3080).
+ */
+function writeScopeOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): WriteScope | null {
+  if (raw === undefined) return null;
+  const block = raw as Record<PrincipalClass, { members?: "*" | string[]; records?: Record<string, WriteVerb[]>; protected?: (string | { path: string; except?: string[] })[] }>;
+  const out: WriteScope = {};
+  for (const [cls, entry] of Object.entries(block)) {
+    const pointer = `/writeScope/${cls}`;
+    const list = entry.members === undefined || entry.members === "*" ? null : [...entry.members];
+    for (const [i, name] of (list ?? []).entries()) {
+      if (!members.some((m) => m.name === name)) {
+        throw new WorkspaceReadError(
+          "declaration-invalid",
+          `writeScope.${cls} names the member ${JSON.stringify(name)}, which the declaration does not declare; declared members: ${members.map((m) => m.name).join(", ") || "none"}`,
+          at(`${pointer}/members/${i}`),
+        );
+      }
+    }
+    const records = entry.records === undefined ? null : Object.fromEntries(Object.entries(entry.records).map(([k, v]) => [k, [...v]]));
+    const guarded = (entry.protected ?? []).map((p) => (typeof p === "string" ? { path: p, except: [] } : { path: p.path, except: [...(p.except ?? [])] }));
+    out[cls] = { members: list, records, protected: guarded, pointer };
+  }
+  return out;
+}
+
+/**
+ * The `agents` list, already validated, with the rules the schema can't say
+ * (#2548): names are unique, each names a declared member, and a principal
+ * is listed by one session at most.
+ */
+/** The `identity` block, already validated by the schema (#3163). */
+function identityOf(raw: unknown): IdentityPolicy | null {
+  if (raw === undefined) return null;
+  const block = raw as { attribution?: "any" | "identified"; gates?: Record<string, { class?: string }> };
+  const gates: Record<string, SignedGate> = {};
+  for (const [gate, entry] of Object.entries(block.gates ?? {})) {
+    gates[gate] = { gate, class: entry.class ?? null, pointer: `/identity/gates/${gate.replace(/~/g, "~0").replace(/\//g, "~1")}` };
+  }
+  return { attribution: block.attribution ?? "any", gates };
+}
+
+function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {
+  const agents = ((raw as { name: string; member: string; principals?: string[] }[] | undefined) ?? []).map((a, i) => ({
+    name: a.name,
+    member: a.member,
+    principals: [...(a.principals ?? [])],
+    pointer: `/agents/${i}`,
+  }));
+  const byName = new Map<string, AgentDeclaration>();
+  const byPrincipal = new Map<string, AgentDeclaration>();
+  for (const a of agents) {
+    const first = byName.get(a.name);
+    if (first) throw new WorkspaceReadError("declaration-invalid", `the agent name ${JSON.stringify(a.name)} is already used by the agent at ${first.pointer}`, at(`${a.pointer}/name`));
+    byName.set(a.name, a);
+    if (!members.some((m) => m.name === a.member)) {
+      throw new WorkspaceReadError(
+        "declaration-invalid",
+        `agent ${a.name} is bound to ${JSON.stringify(a.member)}, which is not a declared member; an agent session is bound to one member, not an example group`,
+        at(`${a.pointer}/member`),
+      );
+    }
+    for (const [i, p] of a.principals.entries()) {
+      const other = byPrincipal.get(p);
+      if (other) throw new WorkspaceReadError("declaration-invalid", `the principal ${JSON.stringify(p)} is already listed by agent ${other.name}`, at(`${a.pointer}/principals/${i}`));
+      byPrincipal.set(p, a);
+    }
+  }
+  return agents;
+}
+
 /** The `changes` block, already validated, with its defaults (#2773). */
 function changesOf(block: Record<string, unknown> | undefined): ChangesPolicy | null {
   if (block === undefined) return null;
@@ -751,7 +963,17 @@ function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
     cookies?: string[];
     intent?: string;
     services?: { name: string; cmd: string; needs?: string[]; httpPort?: number; duration?: string; health?: string; optional?: boolean }[];
+    factory?: {
+      builds: string[];
+      check?: string | { run: string; kind?: FactoryCheckKind };
+      checks?: string;
+      builders?: string;
+      publish?: { forge?: "github"; repo: string; base?: string; branchPrefix?: string; head?: string };
+    };
+    listing?: { published?: boolean; title?: string; line?: string; cover?: string };
   };
+  const f = b.factory;
+  const l = b.listing;
   return {
     capabilities: (b.capabilities ?? []).map((c, i) => ({ name: c.name, broker: c.broker ?? null, scope: [...(c.scope ?? [])], pointer: `${pointer}/capabilities/${i}` })),
     // The schema requires host and slot together, and host for ports, state and cookies.
@@ -770,10 +992,57 @@ function boxOf(raw: unknown, pointer: string): BoxDeclaration | null {
       optional: s.optional ?? false,
       pointer: `${pointer}/services/${i}`,
     })),
+    factory:
+      f === undefined
+        ? null
+        : {
+            builds: [...f.builds],
+            check: f.check === undefined ? null : typeof f.check === "string" ? { run: f.check, kind: "test" } : { run: f.check.run, kind: f.check.kind ?? "test" },
+            checks: f.checks ?? null,
+            builders: f.builders ?? null,
+            publish:
+              f.publish === undefined
+                ? null
+                : {
+                    forge: f.publish.forge ?? "github",
+                    repo: f.publish.repo,
+                    base: f.publish.base ?? null,
+                    branchPrefix: f.publish.branchPrefix ?? DEFAULT_PUBLISH_BRANCH_PREFIX,
+                    head: f.publish.head ?? null,
+                  },
+            pointer: `${pointer}/factory`,
+          },
+    listing: l === undefined ? null : { published: l.published ?? true, title: l.title ?? "", line: l.line ?? "", cover: l.cover ?? null },
     pointer,
   };
 }
 
+/**
+ * The rules the schema can't say about the factories (#3146, ws-077): at most
+ * one box block declares one, and the members its builds and builders name
+ * are declared members.
+ */
+function factoryProblem(members: readonly Member[]): { message: string; pointer: string } | null {
+  const declaring = members.filter((m) => m.box?.factory);
+  if (declaring.length > 1) {
+    return {
+      message: `members ${declaring[0].name} and ${declaring[1].name} both declare a factory in their box block; a workspace has one factory, so an orchestrator reads one`,
+      pointer: declaring[1].box!.factory!.pointer,
+    };
+  }
+  const factory = declaring[0]?.box?.factory;
+  if (!factory) return null;
+  const known = () => members.map((m) => m.name).join(", ");
+  const j = factory.builds.findIndex((name) => !members.some((m) => m.name === name));
+  if (j >= 0) {
+    return { message: `the factory builds ${JSON.stringify(factory.builds[j])}, which is not a declared member; declared members: ${known()}`, pointer: `${factory.pointer}/builds/${j}` };
+  }
+  if (factory.builders !== null && !members.some((m) => m.name === factory.builders)) {
+    return { message: `the factory's builders names ${JSON.stringify(factory.builders)}, which is not a declared member; declared members: ${known()}`, pointer: `${factory.pointer}/builders` };
+  }
+  return null;
+}
+
 /**
  * The rules the schema can't say about a box's services (#2880), as a
  * message and the pointer to show, or null when they hold: each name is

package/src/workspace/declared-kinds.test.ts

@@ -5,6 +5,7 @@
  * `--kind` is not given, while `--kind` still overrides.
  */
 
+import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterAll, afterEach, beforeEach, describe, expect, test, vi } from "vitest";
@@ -199,6 +200,38 @@ describe("records without --kind reads every declared kind (#2680)", () => {
     expect(printed.kinds.map((k: { records: { id: string }[] }) => k.records.map((r) => r.id))).toEqual([["ref-001"], ["ref-001"]]);
   });
 
+  test("--current adds the spec: the current records of spec: true kinds, with the files they pin (#2546, #2524 D20)", async () => {
+    const server = "export const port = 8080;\n";
+    const sha256 = createHash("sha256").update(server).digest("hex");
+    // ref-004 supersedes ref-001 and pins the app's server file; the note kind is not part of the spec.
+    const ref004 = REF_001.replace('id: "ref-001"', 'id: "ref-004"')
+      .replace("supersedes: []", 'supersedes:\n  - decision: "ref-001"')
+      .replace(/^evidence:\n/m, `evidence:\n  - title: "The server"\n    path: "app/server.mjs"\n    sha256: "${sha256}"\n`);
+    const root = workspace({
+      "decisions/ref-004-how-the-app-is-deployed-now.md": ref004,
+      "design/notes/note.kind.mjs": NOTE_KIND.replace("spec: true", "spec: false"),
+    });
+    expect(await run(root, "--current", "--json")).toBe(0);
+    const printed = JSON.parse(out.join("\n"));
+    expectValid(printed);
+    expect(printed.kinds.map((k: { kind: { spec: boolean } }) => k.kind.spec)).toEqual([true, false]);
+    expect(printed.spec.kinds).toEqual([{ member: null, path: "decisions/decision.kind.mjs", name: null }]);
+    expect(printed.spec.records).toEqual([
+      expect.objectContaining({
+        kind: "decision",
+        id: "ref-004",
+        path: "decisions/ref-004-how-the-app-is-deployed-now.md",
+        state: "decided",
+        valid: true,
+        assets: [{ path: "app/server.mjs", sha256, actual: sha256, state: "pinned" }],
+      }),
+    ]);
+    // Without --current there is no spec: superseded records are still listed under kinds.
+    out.length = 0;
+    expect(await run(root, "--json")).toBe(0);
+    expect(JSON.parse(out.join("\n")).spec).toBeUndefined();
+  });
+
   test("a kind that can't be read is listed with its error, the others are read, and the exit code is 1", async () => {
     const root = workspace({}, [{ kind: "gone.kind.mjs" }]);
     expect(await run(root, "--json")).toBe(1);

package/src/workspace/evidence.schema.json

@@ -0,0 +1,279 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/evidence/v1/evidence.schema.json",
+  "title": "chant workspace evidence output",
+  "description": "What `chant workspace evidence verify --json` prints (#2553), and what a refused `chant workspace evidence sign --json` prints: runner evidence, an in-toto statement over record hashes in a DSSE envelope, checked offline against the runner keys `.chant/trust.json` lists at the base revision. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "A runner key the policy at base lists signed the envelope. `status` says whether the records still hash as signed; it exits 1 when they don't.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "at",
+        "ok",
+        "status",
+        "runner",
+        "class",
+        "keyid",
+        "statement",
+        "subjects"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/evidence/v1/evidence.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "at": {
+          "type": "string",
+          "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$",
+          "description": "The commit the subjects were compared at."
+        },
+        "ok": {
+          "const": true
+        },
+        "status": {
+          "enum": [
+            "current",
+            "stale"
+          ],
+          "description": "current when every subject hashes the same at `at`; stale otherwise. Stale evidence is never reused."
+        },
+        "runner": {
+          "type": "string",
+          "description": "The runner principal whose key signed."
+        },
+        "class": {
+          "enum": [
+            "runner",
+            "service"
+          ],
+          "description": "A CI runner or a service, as `.chant/trust.json` lists it."
+        },
+        "keyid": {
+          "type": "string",
+          "description": "The ssh SHA256 fingerprint of the key that signed."
+        },
+        "statement": {
+          "$ref": "#/$defs/statement"
+        },
+        "subjects": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/subject"
+          }
+        }
+      }
+    },
+    "statement": {
+      "type": "object",
+      "description": "The in-toto Statement v1 the runner signed.",
+      "required": [
+        "_type",
+        "subject",
+        "predicateType",
+        "predicate"
+      ],
+      "properties": {
+        "_type": {
+          "const": "https://in-toto.io/Statement/v1"
+        },
+        "subject": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "digest"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "digest": {
+                "type": "object",
+                "required": [
+                  "sha256"
+                ],
+                "properties": {
+                  "sha256": {
+                    "type": "string",
+                    "pattern": "^[0-9a-f]{64}$"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "predicateType": {
+          "const": "https://intentius.io/chant/runner-evidence/v1"
+        },
+        "predicate": {
+          "type": "object",
+          "required": [
+            "runner",
+            "commit",
+            "tree",
+            "check"
+          ],
+          "properties": {
+            "runner": {
+              "type": "string"
+            },
+            "commit": {
+              "type": "string",
+              "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+            },
+            "tree": {
+              "type": "string",
+              "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+            },
+            "check": {
+              "type": "string",
+              "description": "The check's id, as given to --check-id."
+            },
+            "claim": {
+              "type": "object",
+              "required": [
+                "sha256"
+              ],
+              "properties": {
+                "sha256": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$"
+                }
+              }
+            },
+            "environment": {
+              "type": "object",
+              "required": [
+                "sha256"
+              ],
+              "properties": {
+                "sha256": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "required": [
+        "name",
+        "signed",
+        "now",
+        "matches"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The record's path from the repository root."
+        },
+        "signed": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "now": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$"
+            }
+          ],
+          "description": "The record's hash at `at`, or null when it is not there."
+        },
+        "matches": {
+          "type": "boolean"
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "The evidence was refused, or could not be checked. Exits 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "at",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/evidence/v1/evidence.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "at": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "string",
+              "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+            }
+          ]
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "not-a-git-repository",
+                "revision-unknown",
+                "trust-policy-unreadable",
+                "envelope-unreadable",
+                "envelope-invalid",
+                "envelope-untrusted",
+                "evidence-payload-type",
+                "evidence-statement-invalid",
+                "evidence-runner-mismatch",
+                "runner-key-invalid",
+                "runner-key-is-signer",
+                "runner-key-unlisted",
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}