@intentius/chant 0.90.0 → 0.93.0

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() }),
+);

package/src/op/activities/apply.ts

@@ -35,6 +35,7 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import { normalizeApply, type ApplyResult } from "../../apply";
+import { importLexiconPackage } from "../../lexicon-module";
 
 const execAsync = promisify(exec);
 
@@ -241,7 +242,7 @@ async function loadK8sApplier(): Promise<K8sApplier> {
   const spec = "@intentius/chant-lexicon-k8s/op/activities";
   let mod: { applyManifest?: K8sApplier };
   try {
-    mod = (await import(spec)) as { applyManifest?: K8sApplier };
+    mod = (await importLexiconPackage(spec)) as { applyManifest?: K8sApplier };
   } catch (err) {
     throw new Error(
       `apply target "kubectl" needs @intentius/chant-lexicon-k8s, which could not be loaded ` +
@@ -269,7 +270,7 @@ async function loadAzureApplier(): Promise<AzureApplier> {
   };
   let mod: AzureModule;
   try {
-    mod = (await import(spec)) as AzureModule;
+    mod = (await importLexiconPackage(spec)) as AzureModule;
   } catch (err) {
     throw new Error(
       `apply target "arm" needs @intentius/chant-lexicon-azure, which could not be loaded ` +
@@ -304,7 +305,7 @@ async function loadGcpApplier(): Promise<GcpApplier> {
   };
   let mod: GcpModule;
   try {
-    mod = (await import(spec)) as GcpModule;
+    mod = (await importLexiconPackage(spec)) as GcpModule;
   } catch (err) {
     throw new Error(
       `apply target "gcp" needs @intentius/chant-lexicon-gcp, which could not be loaded ` +
@@ -339,7 +340,7 @@ async function loadFlyApplier(): Promise<FlyApplier> {
   };
   let mod: FlyModule;
   try {
-    mod = (await import(spec)) as FlyModule;
+    mod = (await importLexiconPackage(spec)) as FlyModule;
   } catch (err) {
     throw new Error(
       `apply target "fly" needs @intentius/chant-lexicon-fly, which could not be loaded ` +
@@ -370,7 +371,7 @@ async function loadAwsApplier(): Promise<AwsApplier> {
   const spec = "@intentius/chant-lexicon-aws/op/activities";
   let mod: { awsApply?: AwsApplier };
   try {
-    mod = (await import(spec)) as { awsApply?: AwsApplier };
+    mod = (await importLexiconPackage(spec)) as { awsApply?: AwsApplier };
   } catch (err) {
     throw new Error(
       `apply target "cloudformation" needs @intentius/chant-lexicon-aws, which could not be loaded ` +
@@ -395,7 +396,7 @@ async function loadAwsRollback(): Promise<AwsRollback> {
   const spec = "@intentius/chant-lexicon-aws/op/activities";
   let mod: { rollbackStack?: AwsRollback };
   try {
-    mod = (await import(spec)) as { rollbackStack?: AwsRollback };
+    mod = (await importLexiconPackage(spec)) as { rollbackStack?: AwsRollback };
   } catch (err) {
     throw new Error(
       `rollback for target "cloudformation" needs @intentius/chant-lexicon-aws, which could not be ` +

package/src/op/activities/change-coverage.ts

@@ -0,0 +1,60 @@
+/**
+ * changeCoverage — the forward coverage check (#2773) as an Op activity, for
+ * an Op that changes the checkout (#2748) to run on its own diff.
+ *
+ * Such an Op's leased steps work in a worktree of their own on
+ * `chant/work/[<member>/]<item>`. Given that worktree as `cwd`
+ * (`workLeaseOutput("worktree")`) and no `range`, the activity checks the
+ * commits the branch holds beyond the main worktree's HEAD, with the branch's
+ * item as the work item in hand, exactly as `chant workspace check --changes
+ * <base>..HEAD --work <item>` would. A `range` or `work` given replaces what
+ * the branch says.
+ *
+ * The step fails when the check's severity is `fail` and it has a finding,
+ * or when the check can't run; otherwise it returns the document's findings
+ * and summary for later steps. The workspace code loads on first call, so
+ * importing core's activities loads nothing under `workspace/` (#2525 rule 5).
+ */
+
+import type { ChangeFinding, ChangesDocument } from "../../workspace/changes";
+
+export interface ChangeCoverageArgs {
+  /** The checkout to check: the Op's worktree. Default: the working directory. */
+  cwd?: string;
+  /** `<base>..<head>`, `<base>...<head>` or `<base>`. Default: the work branch's own commits. */
+  range?: string;
+  /** The work item in hand. Default: the work branch's item. */
+  work?: string;
+  /** In place of the declaration's `changes.severity`. */
+  severity?: "off" | "warn" | "fail";
+}
+
+export interface ChangeCoverageResult {
+  ok: boolean;
+  range: { spec: string; base: string; head: string };
+  work: string | null;
+  severity: "off" | "warn" | "fail";
+  findings: Pick<ChangeFinding, "code" | "path" | "message" | "severity" | "records" | "triage">[];
+  summary: Exclude<ChangesDocument, { error: unknown }>["summary"];
+}
+
+export async function changeCoverage(args: ChangeCoverageArgs = {}): Promise<ChangeCoverageResult> {
+  const { checkChanges, workBranchChanges } = await import("../../workspace/changes");
+  const cwd = args.cwd ?? process.cwd();
+  const branch = args.range === undefined ? workBranchChanges(cwd) : undefined;
+  const range = args.range ?? branch?.range;
+  if (range === undefined) throw new Error(`changeCoverage: ${cwd} is not on a chant/work/ branch, so give the range to check`);
+  const work = args.work ?? branch?.work;
+  const { doc } = await checkChanges({ cwd, range, ...(work !== undefined ? { work } : {}), ...(args.severity ? { severity: args.severity } : {}) });
+  if ("error" in doc) throw new Error(`changeCoverage: ${doc.error.code}: ${doc.error.message}`);
+  const result: ChangeCoverageResult = {
+    ok: doc.ok,
+    range: doc.range,
+    work: doc.work?.record ?? null,
+    severity: doc.severity,
+    findings: doc.findings.map(({ code, path, message, severity, records, triage }) => ({ code, path, message, severity, records, triage })),
+    summary: doc.summary,
+  };
+  if (!doc.ok) throw new Error(`changeCoverage: ${doc.findings.length} change ${doc.findings.length === 1 ? "finding" : "findings"} at severity fail: ${doc.findings.map((f) => `${f.code} ${f.path}`).join(", ")}`);
+  return result;
+}