@intentius/chant 0.91.0 → 0.93.0

package/src/lint/rules/op/ops014-converge-rule-refusals.ts

@@ -53,7 +53,7 @@
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "../../post-synth";
 import { classifyOpVerbClass, isWellFormedPredicate, predicateReferencesField } from "../../../op";
 import type { ConvergeRule, OpConfig } from "../../../op";
-import { CONVERGE_SYMPTOM_FIELDS, type ConvergeSymptom } from "../../../lifecycle/symptoms";
+import { CONVERGE_SYMPTOM_FIELDS, RESOURCE_SYMPTOM_FIELDS, type ConvergeSymptom } from "../../../lifecycle/symptoms";
 import { isOpEntity } from "./support";
 
 function looksLikeOpProps(props: Record<string, unknown>): boolean {
@@ -61,12 +61,15 @@ function looksLikeOpProps(props: Record<string, unknown>): boolean {
 }
 
 /** Read a ConvergeOp's rule table back off its `convergeTick` step's `args.rules`. `undefined` if this doesn't look like a ConvergeOp-shaped Op (defensive — never crashes the build over an unexpected shape). */
-function findConvergeRules(props: OpConfig): ConvergeRule<ConvergeSymptom>[] | undefined {
+function findConvergeRules(props: OpConfig): { rules: ConvergeRule<ConvergeSymptom>[]; fields: ReadonlySet<string> } | undefined {
   for (const phase of props.phases) {
     for (const step of phase.steps) {
       if (step.kind === "activity" && step.fn === "convergeTick") {
         const rules = step.args?.rules;
-        return Array.isArray(rules) ? (rules as ConvergeRule<ConvergeSymptom>[]) : undefined;
+        // #2778: a ConvergeOp with an observer step passes its result as
+        // `observed`, and its rules read a ResourceSymptom.
+        const fields = step.args?.observed !== undefined ? RESOURCE_SYMPTOM_FIELDS : CONVERGE_SYMPTOM_FIELDS;
+        return Array.isArray(rules) ? { rules: rules as ConvergeRule<ConvergeSymptom>[], fields } : undefined;
       }
     }
   }
@@ -100,8 +103,9 @@ export const ops014: PostSynthCheck = {
       if (props.labels?.Converge !== "true") continue;
 
       const dial = props.labels?.Dial ?? "observe";
-      const rules = findConvergeRules(props);
-      if (!rules) continue;
+      const found = findConvergeRules(props);
+      if (!found) continue;
+      const { rules, fields } = found;
 
       for (const rule of rules) {
         const label = typeof rule?.id === "string" ? rule.id : "(unnamed rule)";
@@ -119,7 +123,7 @@ export const ops014: PostSynthCheck = {
           push("every rule must carry its why — refused at build");
           continue;
         }
-        if (!isWellFormedPredicate(rule.when, CONVERGE_SYMPTOM_FIELDS)) {
+        if (!isWellFormedPredicate(rule.when, fields)) {
           push("predicate is outside the evaluable subset (build it from eq/neq/gt/gte/lt/lte/truthy/falsy/allOf/anyOf over a known symptom field)");
           continue;
         }

package/src/lint/rules/op/sys010-key-over-plain-http.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { Op, phase, decide } from "../../../op";
+import type { PostSynthContext } from "../../post-synth";
+import { plainRemoteHost, sys010, sys010Check } from "./sys010-key-over-plain-http";
+import { coreOpChecks } from "./index";
+
+const ctx = (op?: unknown): PostSynthContext => ({ outputs: new Map(), entities: new Map(op ? [["op", op as never]] : []), buildResult: {} as never }) as unknown as PostSynthContext;
+
+describe("SYS010", () => {
+  it("fires when a decide step sends a key over plain http to a remote host", () => {
+    const op = Op({ name: "ask", overview: "ask", phases: [phase("Ask", [decide("triage", { backends: { s: { url: "http://jev.example.com", key: { env: "K" } } } })])] });
+    const d = sys010.check(ctx(op));
+    expect(d).toHaveLength(1);
+    expect(d[0]).toMatchObject({ checkId: "SYS010", severity: "error" });
+    expect(d[0].message).toContain("jev.example.com");
+  });
+
+  it("is quiet for https, for loopback, and for a backend with no key", () => {
+    const op = Op({
+      name: "ask",
+      overview: "ask",
+      phases: [
+        phase("Ask", [
+          decide("a", { backends: { s: { url: "https://api.typesafe.ai", key: { env: "K" } } } }),
+          decide("b", { backends: { s: { url: "http://127.0.0.1:8080", key: { env: "K" } } } }),
+          decide("c", { backends: { s: { url: "http://jev.example.com" } } }),
+          decide("d"),
+        ]),
+      ],
+    });
+    expect(sys010.check(ctx(op))).toEqual([]);
+  });
+
+  it("fires on a backend configured in decide.backends, and is quiet for https", () => {
+    const check = sys010Check({ remote: { url: "http://jev.internal:8080", key: { env: "K" } }, ok: { url: "https://api.typesafe.ai", key: { env: "K" } } });
+    const d = check.check(ctx());
+    expect(d.map((x) => x.entity)).toEqual(["decide.backends.remote"]);
+  });
+
+  it("runs with core's Op checks, with the configured backends when given", () => {
+    expect(coreOpChecks().map((c) => c.id)).toContain("SYS010");
+    const configured = coreOpChecks({ decideBackends: { remote: { url: "http://10.0.0.2", key: { env: "K" } } } }).find((c) => c.id === "SYS010")!;
+    expect(configured.check(ctx())).toHaveLength(1);
+  });
+
+  it("reads hosts", () => {
+    expect(plainRemoteHost("http://localhost:1")).toBeUndefined();
+    expect(plainRemoteHost("http://[::1]:1")).toBeUndefined();
+    expect(plainRemoteHost("http://10.0.0.2")).toBe("10.0.0.2");
+    expect(plainRemoteHost("not a url")).toBeUndefined();
+  });
+});

package/src/lint/rules/op/sys010-key-over-plain-http.ts

@@ -0,0 +1,100 @@
+/**
+ * SYS010: a `decide` backend sends its key over plain HTTP (#2740, core's
+ * since #2828).
+ *
+ * A backend in `decide.backends` in chant.config, or in a `decide` step's own
+ * `backends`, may have a key and an `http://` URL. The bearer key then crosses
+ * the network in clear text. A loopback address (127.0.0.1, ::1, localhost)
+ * is exempt, since that is where a local server such as `von serve` or the
+ * stub runs, and where a broker that is itself the endpoint listens.
+ *
+ * The steps are read off the Op entities, which covers a step written with
+ * the `decide` builder and one written with `activity("decide", ...)`. The
+ * configured backends are not entities: `chant build` and `chant lint` read
+ * them from the project's config and hand them to {@link sys010Check}. The id
+ * keeps the SYS prefix it had in the systemone lexicon.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "../../post-synth";
+import type { OpConfig, PhaseDefinition, ActivityStep } from "../../../op/types";
+import type { DecideBackend } from "../../../op/decide-config";
+import { isOpEntity } from "./support";
+
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
+
+function* decideSteps(phases: PhaseDefinition[] | undefined): Generator<ActivityStep> {
+  for (const phase of phases ?? []) {
+    for (const step of phase.steps ?? []) {
+      if (step.kind === "activity" && step.fn === "decide") yield step;
+      else if (step.kind === "effect") {
+        for (const nested of step.steps ?? []) if (nested.kind === "activity" && nested.fn === "decide") yield nested;
+      }
+    }
+  }
+}
+
+/** The host of an http:// URL that is not loopback, or undefined. */
+export function plainRemoteHost(url: unknown): string | undefined {
+  if (typeof url !== "string") return undefined;
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  if (parsed.protocol !== "http:") return undefined;
+  return LOOPBACK.has(parsed.hostname) ? undefined : parsed.hostname;
+}
+
+const DESCRIPTION = "A decide backend sends its key over plain HTTP to a host that is not loopback";
+
+/**
+ * SYS010 over the Op entities and, when given, the backends configured in
+ * `decide.backends`. A configured backend's diagnostic names it as the entity
+ * `decide.backends.<name>`.
+ */
+export function sys010Check(configured?: Record<string, Pick<DecideBackend, "url" | "key">>): PostSynthCheck {
+  return {
+    id: "SYS010",
+    description: DESCRIPTION,
+
+    check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+      const diagnostics: PostSynthDiagnostic[] = [];
+      for (const [name, b] of Object.entries(configured ?? {})) {
+        const host = b?.key !== undefined ? plainRemoteHost(b.url) : undefined;
+        if (!host) continue;
+        diagnostics.push({
+          checkId: "SYS010",
+          severity: "error",
+          message: `decide.backends.${name} sends its key over http:// to ${host}; use https://, or a loopback broker`,
+          entity: `decide.backends.${name}`,
+        });
+      }
+      for (const [entityKey, entity] of ctx.entities) {
+        if (!isOpEntity(entity)) continue;
+        const rec = entity as unknown as Record<string, unknown>;
+        const props = ((entity as { props?: Record<string, unknown> }).props ?? {}) as unknown as OpConfig;
+        for (const step of [...decideSteps(props.phases), ...decideSteps(props.onFailure)]) {
+          const backends = (step.args as { backends?: unknown } | undefined)?.backends;
+          if (backends === null || typeof backends !== "object") continue;
+          for (const [name, b] of Object.entries(backends as Record<string, { url?: unknown; key?: unknown }>)) {
+            if (b?.key === undefined) continue;
+            const host = plainRemoteHost(b.url);
+            if (!host) continue;
+            diagnostics.push({
+              checkId: "SYS010",
+              severity: "error",
+              message: `Op "${props.name}", decide ${JSON.stringify((step.args as { point?: unknown }).point)}: backend ${name} sends its key over http:// to ${host}; use https://, or a loopback broker`,
+              entity: entityKey,
+              lexicon: typeof rec.lexicon === "string" ? rec.lexicon : undefined,
+            });
+          }
+        }
+      }
+      return diagnostics;
+    },
+  };
+}
+
+/** SYS010 over the Op entities alone, with no configured backends. */
+export const sys010: PostSynthCheck = sys010Check();

package/src/lint/rules/sys001-no-literal-key.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import ts from "typescript";
+import { noLiteralKeyRule } from "./sys001-no-literal-key";
+import { loadCoreRules } from "./index";
+
+const run = (code: string) =>
+  noLiteralKeyRule.check({ sourceFile: ts.createSourceFile("x.ts", code, ts.ScriptTarget.Latest, true), filePath: "x.ts", entities: [] } as never);
+
+describe("SYS001", () => {
+  it("is one of core's rules", () => {
+    expect(loadCoreRules().map((r) => r.id)).toContain("SYS001");
+  });
+
+  it("fires on a literal key in the config's decide block", () => {
+    const d = run(`export default { decide: { backends: { s: { url: "https://x", key: "sk-abc" } } } };`);
+    expect(d.map((x) => x.ruleId)).toEqual(["SYS001"]);
+  });
+
+  it("fires on a literal key in a decide step's backends", () => {
+    expect(run('decide("p", { backends: { s: { url: "https://x", key: `k` } } });')).toHaveLength(1);
+  });
+
+  it("is quiet for { env } and a brokered capability", () => {
+    expect(run(`export default { decide: { backends: { s: { url: "https://x", key: { env: "K" } }, b: { url: "http://127.0.0.1", key: { capability: "inference" } } } } };`)).toEqual([]);
+  });
+
+  it("is quiet for a key property outside decide, and for another tool's backends", () => {
+    expect(run(`const x = { key: "not a backend" };`)).toEqual([]);
+    expect(run(`const tf = { backends: { s3: { bucket: "b", key: "state/terraform.tfstate" } } };`)).toEqual([]);
+  });
+});

package/src/lint/rules/sys001-no-literal-key.ts

@@ -0,0 +1,67 @@
+import ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "../rule";
+
+/**
+ * SYS001: a `decide` backend's key is never a literal (#2740, core's since
+ * #2828).
+ *
+ * A key is `{ env: "VARIABLE" }` or a brokered capability
+ * (`{ capability: "inference", member: "box" }`, #2726). A string written
+ * where a key goes is a credential in git history, and a box that holds one
+ * fails `workspace check` with WSP121 as well.
+ *
+ * Fires on a `key` property whose value is a string or template literal,
+ * inside a backend of a `backends` object that belongs to `decide`: the
+ * `decide` block of a config object (`decide: { backends: ... }`) or the
+ * options of a `decide(...)` step. A `backends` object anywhere else, such as
+ * a Terraform backend's `key`, is not a decide backend and is left alone.
+ * The id keeps the SYS prefix it had in the systemone lexicon.
+ */
+
+function keyText(name: ts.PropertyName): string | undefined {
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+  return undefined;
+}
+
+const isLiteral = (node: ts.Expression): boolean => ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) || ts.isTemplateExpression(node);
+
+const isDecideCall = (node: ts.Node): node is ts.CallExpression =>
+  ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "decide";
+
+/** Where the walk is: outside decide, inside decide's options or config block, or inside its `backends`. */
+type Scope = "outside" | "decide" | "backends";
+
+export const noLiteralKeyRule: LintRule = {
+  id: "SYS001",
+  severity: "error",
+  category: "security",
+  description: "A decide backend key is { env } or a brokered capability, never a literal string",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+    const visit = (node: ts.Node, scope: Scope) => {
+      let within = scope;
+      if (isDecideCall(node)) within = "decide";
+      else if (ts.isPropertyAssignment(node)) {
+        const key = keyText(node.name);
+        if (key === "decide") within = "decide";
+        else if (key === "backends" && scope === "decide") within = "backends";
+        if (scope === "backends" && key === "key" && isLiteral(node.initializer)) {
+          const { line, character } = source.getLineAndCharacterOfPosition(node.initializer.getStart(source));
+          diagnostics.push({
+            ruleId: "SYS001",
+            severity: "error",
+            message: 'Literal backend key: use { env: "VARIABLE" } or a brokered capability ({ capability, member }) instead',
+            file: context.filePath,
+            line: line + 1,
+            column: character + 1,
+          });
+        }
+      }
+      ts.forEachChild(node, (child) => visit(child, within));
+    };
+    visit(source, "outside");
+    return diagnostics;
+  },
+};

package/src/op/__fixtures__/decide-stub-backend.ts

@@ -0,0 +1,143 @@
+/**
+ * A stub `POST /v1/systemone` server for tests of the `decide` activity
+ * (`@intentius/chant/op/__fixtures__/decide-stub-backend`): a real HTTP server on
+ * 127.0.0.1 that checks a request the way a Jev-compatible server would and
+ * answers with what the test scripts. No model runs.
+ *
+ * ```ts
+ * const stub = await startStubBackend({ key: "k", answers: { slice_tier: { type: "choice", choice: "large", probabilities: {...}, confidence: 0.9 } } });
+ * // decide.backends, or a decide step's backends: { systemone: { url: stub.url, key: { env: "STUB_KEY" } } }
+ * await stub.close();
+ * ```
+ *
+ * It answers 401 when a key is set and the request's bearer differs, 422 when
+ * the body is not a request in the wire format, and `status` when the test
+ * forces one (429 or 529, say). Every request it read is kept in `requests`.
+ *
+ * It lives under `__fixtures__` because it listens on a port, and no module
+ * chant runs does (#2657, `test/no-listener.test.ts`): only tests start it.
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { WireAnswer } from "../../workspace/points";
+import { SYSTEMONE_PATH, type BackendRequest } from "../decide-backend";
+
+export interface StubQuestion {
+  name: string;
+  type: string;
+  instructions: string;
+  criteria: Record<string, string> | string[];
+}
+
+export interface StubBackendOptions {
+  /** The bearer key the stub requires. Without it, any request is taken. */
+  key?: string;
+  /** The model id the response reports. Defaults to the id the request sent. */
+  model?: string;
+  /** The answer to a question, by question name, or computed from the question. Defaults to {@link defaultAnswer}. */
+  answers?: Record<string, WireAnswer> | ((question: StubQuestion, request: BackendRequest) => WireAnswer);
+  /** Answer every request with this status and no answers. */
+  status?: number;
+}
+
+export interface StubBackend {
+  /** The base URL, without `/v1/systemone`. */
+  url: string;
+  /** Each request body the stub read, in order. */
+  requests: BackendRequest[];
+  /** The Authorization header of each request, or null. */
+  authorizations: (string | null)[];
+  close(): Promise<void>;
+}
+
+/** A confident answer of the question's own type: true, the first option, or the last level. */
+export function defaultAnswer(question: StubQuestion): WireAnswer {
+  if (question.type === "noul") return { type: "noul", noul: 0.95 };
+  if (question.type === "choice") {
+    const options = Object.keys(question.criteria);
+    const rest = options.length > 1 ? 0.05 / (options.length - 1) : 0;
+    const probabilities = Object.fromEntries(options.map((o, i) => [o, i === 0 ? 0.95 : rest]));
+    return { type: "choice", choice: options[0], probabilities, confidence: 0.925 };
+  }
+  if (question.type === "score") {
+    const levels = question.criteria as string[];
+    const probabilities = Object.fromEntries(levels.map((l, i) => [l, i === levels.length - 1 ? 0.95 : 0.05 / Math.max(1, levels.length - 1)]));
+    return { type: "score", score: levels.length - 0.05, probabilities, confidence: 0.925 };
+  }
+  return { type: "unsupported" };
+}
+
+/** Why a body is not a request in the wire format, or null when it is one. */
+export function requestProblem(body: unknown): string | null {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) return "the body is not a JSON object";
+  const b = body as Record<string, unknown>;
+  if (typeof b.model !== "string" || b.model === "") return "model is required";
+  if (b.state === undefined) return "state is required";
+  if (b.questions === null || typeof b.questions !== "object" || Array.isArray(b.questions) || Object.keys(b.questions).length === 0) return "questions must name at least one question";
+  for (const [name, q] of Object.entries(b.questions as Record<string, unknown>)) {
+    const question = q as Record<string, unknown> | null;
+    if (question === null || typeof question !== "object") return `questions.${name} is not an object`;
+    if (typeof question.instructions !== "string") return `questions.${name}.instructions is required`;
+    if (question.type === "noul" || question.type === "choice") {
+      if (question.criteria === null || typeof question.criteria !== "object" || Array.isArray(question.criteria)) return `questions.${name}.criteria must be an object`;
+      if (question.type === "noul" && !("true" in question.criteria && "false" in question.criteria)) return `questions.${name}.criteria must describe true and false`;
+    } else if (question.type === "score") {
+      if (!Array.isArray(question.criteria) || question.criteria.length < 2 || question.criteria.length > 10) return `questions.${name}.criteria must be 2 to 10 levels`;
+    } else {
+      return `questions.${name}.type must be noul, choice or score`;
+    }
+  }
+  return null;
+}
+
+function send(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+async function readBody(req: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+/** Start the stub on a free port on 127.0.0.1. */
+export async function startStubBackend(opts: StubBackendOptions = {}): Promise<StubBackend> {
+  const requests: BackendRequest[] = [];
+  const authorizations: (string | null)[] = [];
+  const server = createServer((req, res) => {
+    void (async () => {
+      if (req.method !== "POST" || req.url !== SYSTEMONE_PATH) return send(res, 404, { error: { type: "not_found", message: `${req.method} ${req.url}` } });
+      const auth = req.headers.authorization ?? null;
+      authorizations.push(auth);
+      if (opts.key !== undefined && auth !== `Bearer ${opts.key}`) return send(res, 401, { error: { type: "authentication_error", message: "invalid key" } });
+      let body: unknown;
+      try {
+        body = JSON.parse(await readBody(req));
+      } catch {
+        return send(res, 422, { error: { type: "invalid_request", message: "the body is not JSON" } });
+      }
+      const problem = requestProblem(body);
+      if (problem) return send(res, 422, { error: { type: "invalid_request", message: problem } });
+      const request = body as BackendRequest;
+      requests.push(request);
+      if (opts.status !== undefined) return send(res, opts.status, { error: { type: "stub", message: `the stub answers ${opts.status}` } });
+      const answers: Record<string, WireAnswer> = {};
+      for (const [name, q] of Object.entries(request.questions)) {
+        const question: StubQuestion = { name, ...q };
+        const scripted = typeof opts.answers === "function" ? opts.answers(question, request) : opts.answers?.[name];
+        answers[name] = scripted ?? defaultAnswer(question);
+      }
+      send(res, 200, { model: opts.model ?? request.model, answers, usage: { input_tokens: JSON.stringify(request).length, output_tokens: 0 } });
+    })().catch((err: unknown) => send(res, 500, { error: { type: "stub", message: err instanceof Error ? err.message : String(err) } }));
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as AddressInfo;
+  return {
+    url: `http://127.0.0.1:${port}`,
+    requests,
+    authorizations,
+    close: () => new Promise<void>((resolve, reject) => server.close((err) => (err ? reject(err) : resolve()))),
+  };
+}

package/src/op/activities/activity-contracts.ts

@@ -25,6 +25,7 @@
 
 import { z } from "zod";
 import { activityContract } from "../activity-contract";
+import { backendSchema } from "../decide-config";
 
 export const lifecycleSnapshotContract = activityContract(
   "lifecycleSnapshot",
@@ -54,8 +55,14 @@ export const shellCmdContract = activityContract(
     env: z.record(z.string(), z.string()).optional(),
     cwd: z.string().optional(),
     okExit: z.array(z.number()).optional(),
+    gatedExit: z.number().optional(),
+    gate: z.strictObject({ op: z.string(), gate: z.string() }).optional(),
+    json: z.boolean().optional(),
   }),
-  z.object({ stdout: z.string(), stderr: z.string(), exitCode: z.number() }),
+  // `json` is stdout parsed, when the step sets `json` (#2787): whatever the
+  // command printed, so its shape is the author's and only the whole value is
+  // a reference target (`sh.out.json`).
+  z.object({ stdout: z.string(), stderr: z.string(), exitCode: z.number(), json: z.unknown().optional() }),
 );
 
 export const httpCheckContract = activityContract(
@@ -166,3 +173,185 @@ export const proposeWorkspaceUpgradeContract = activityContract(
     summary: z.string(),
   }),
 );
+
+/**
+ * The forward coverage check over an Op's own diff (#2773). `args` mirrors
+ * `ChangeCoverageArgs`. `returns` names what a step reads: whether the check
+ * passed, the range and work item checked, and each finding with the
+ * `triage` a work item seeded from it takes as its `source`.
+ */
+export const changeCoverageContract = activityContract(
+  "changeCoverage",
+  z.strictObject({
+    cwd: z.string().optional(),
+    range: z.string().optional(),
+    work: z.string().optional(),
+    severity: z.enum(["off", "warn", "fail"]).optional(),
+  }),
+  z.object({
+    ok: z.boolean(),
+    range: z.object({ spec: z.string(), base: z.string(), head: z.string() }),
+    work: z.string().nullable(),
+    severity: z.enum(["off", "warn", "fail"]),
+    findings: z.array(
+      z.object({
+        code: z.enum(["change-uncovered", "change-out-of-scope"]),
+        path: z.string(),
+        message: z.string(),
+        severity: z.enum(["warn", "fail"]),
+        records: z.array(z.string()),
+        triage: z.object({ finding: z.enum(["change-uncovered", "change-out-of-scope"]), region: z.string() }),
+      }),
+    ),
+    summary: z.object({
+      paths: z.number(),
+      covered: z.number(),
+      uncovered: z.number(),
+      outOfScope: z.number(),
+      ignored: z.number(),
+      records: z.number(),
+    }),
+  }),
+);
+
+/**
+ * Evidence for an acceptance criterion, under the run's work lease (#2772).
+ * `lease` is the run's lease, a reference the builder fills in, so it is not
+ * checked here. `returns` names what a step reads: the item, the record's
+ * path, the entry appended and the criteria counted with it.
+ */
+export const workEvidenceContract = activityContract(
+  "workEvidence",
+  z.strictObject({
+    lease: z.unknown(),
+    criterion: z.string(),
+    result: z.enum(["pass", "fail"]),
+    title: z.string(),
+    url: z.string().optional(),
+    path: z.string().optional(),
+    kind: z.string().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({
+    item: z.string(),
+    path: z.string(),
+    evidence: z.record(z.string(), z.unknown()),
+    acceptance: z.object({ met: z.number(), total: z.number(), criteria: z.array(z.object({ id: z.string(), verification: z.string(), met: z.boolean() })) }),
+  }),
+);
+
+/**
+ * The source-release activities (#2782, ./source-release.ts). A release Op
+ * reads `archive.out.digest` into its plan, `plan.out.digest` into its gate
+ * and its ship step, and `plan.out.file` into its record step.
+ */
+export const sourceArchiveContract = activityContract(
+  "sourceArchive",
+  z.strictObject({ path: z.string(), ref: z.string().optional(), out: z.string().optional(), cwd: z.string().optional() }),
+  z.object({ digest: z.string(), archive: z.string(), commit: z.string(), dir: z.string(), files: z.number(), bytes: z.number() }),
+);
+
+export const releasePlanContract = activityContract(
+  "releasePlan",
+  z.strictObject({
+    component: z.string(),
+    env: z.string(),
+    gitSha: z.string(),
+    content: z.record(z.string(), z.unknown()),
+    dir: z.string().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({ digest: z.string(), file: z.string(), gitSha: z.string() }),
+);
+
+export const releaseRecordContract = activityContract(
+  "releaseRecord",
+  z.strictObject({
+    plan: z.string(),
+    digest: z.string().optional(),
+    approval: z.strictObject({ op: z.string(), gate: z.string() }).optional(),
+    actor: z.string().optional(),
+    runId: z.string().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({ recorded: z.boolean(), digest: z.string(), env: z.string(), component: z.string(), approver: z.string().nullable() }),
+);
+
+/**
+ * `decide` (#2740, core's since #2828). OPS012 checks a step's args against
+ * it and OPS013 a later step's reference into its result, so a misspelled
+ * `point` or a key written as a literal string fails `chant build` rather
+ * than a run.
+ */
+const decideEscalation = z.object({ kind: z.enum(["table", "model"]), reason: z.string() }).loose();
+
+export const decideContract = activityContract(
+  "decide",
+  z.strictObject({
+    point: z.string().min(1),
+    inputs: z.record(z.string(), z.unknown()).optional(),
+    read: z.record(z.string(), z.string()).optional(),
+    subject: z.string().optional(),
+    kind: z.string().optional(),
+    cwd: z.string().optional(),
+    backends: z.record(z.string(), backendSchema).optional(),
+    dryRun: z.boolean().optional(),
+  }),
+  z.strictObject({
+    id: z.string(),
+    path: z.string(),
+    state: z.enum(["escalated", "proposed", "answered"]),
+    open: z.boolean(),
+    answer: z.union([z.string(), z.boolean(), z.null()]),
+    decider: z.string(),
+    model: z.string().nullable(),
+    backend: z.string().nullable(),
+    confidence: z.number().nullable(),
+    threshold: z.number().nullable(),
+    answeredBy: z.array(z.string()),
+    escalations: z.array(decideEscalation),
+    missing: z.array(z.string()),
+  }),
+  { entities: ["point"] },
+);
+
+/**
+ * The rollback activities for a source release (#2800, ./source-rollback.ts).
+ * A rollback Op reads `plan.out.digest` into its gate, `plan.out.to` and the
+ * archive fields into the step that restores the Machine, and
+ * `plan.out.file` into its record step.
+ */
+export const releaseRollbackPlanContract = activityContract(
+  "releaseRollbackPlan",
+  z.strictObject({
+    component: z.string(),
+    env: z.string(),
+    to: z.string().optional(),
+    path: z.string().optional(),
+    dir: z.string().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({
+    digest: z.string(),
+    file: z.string(),
+    to: z.string(),
+    from: z.string(),
+    gitSha: z.string(),
+    archive: z.string(),
+    archiveDigest: z.string(),
+    dir: z.string(),
+  }),
+);
+
+export const releaseRollbackRecordContract = activityContract(
+  "releaseRollbackRecord",
+  z.strictObject({
+    plan: z.string(),
+    digest: z.string().optional(),
+    approval: z.strictObject({ op: z.string(), gate: z.string() }).optional(),
+    actor: z.string().optional(),
+    runId: z.string().optional(),
+    cwd: z.string().optional(),
+  }),
+  z.object({ recorded: z.boolean(), digest: z.string(), env: z.string(), component: z.string(), approver: z.string().nullable() }),
+);