@intentius/chant 0.91.0 → 0.94.0

package/src/lifecycle/symptoms.ts

@@ -124,3 +124,98 @@ export const CONVERGE_SYMPTOM_FIELDS: ReadonlySet<string> = new Set([
   "unobservedReasons",
   "totalCount",
 ]);
+
+// ── Resources an observer step reports (#2778) ──────────────────────────────
+
+/**
+ * One resource's verdict, as an observer step reports it: `in-sync` when it
+ * is what its declaration says, `drifted` when it isn't, and `unknown` when
+ * the observer could not tell.
+ */
+export type ResourceStatus = "in-sync" | "drifted" | "unknown";
+
+/** One resource an observer step looked at. */
+export interface ObservedResource {
+  name: string;
+  status: ResourceStatus;
+  /** Why the observer gave that verdict, in one line. */
+  detail?: string;
+}
+
+/**
+ * What a `ConvergeOp`'s observer step returns (#2778), for resources no
+ * lexicon declares or observes: the processes a supervisor runs in a box,
+ * for example. `ConvergeOp({ observe })` evaluates its rules once per
+ * resource, against a {@link ResourceSymptom}.
+ */
+export interface ResourceObservation {
+  resources: ObservedResource[];
+}
+
+/**
+ * The record a `ConvergeOp` with an observer step evaluates each rule
+ * against, once per observed resource (#2778). A rule reads `status` (and
+ * may read `resource` to single one out); a `run()` it fires is dispatched
+ * for that resource, which the dispatched Op reads from
+ * `CHANT_CONVERGE_RESOURCE`.
+ */
+export interface ResourceSymptom {
+  env: string;
+  /** The resource's name, as the observer reported it. */
+  resource: string;
+  status: ResourceStatus;
+  /** The observer's one-line reason, or "". */
+  detail: string;
+}
+
+/**
+ * The environment variable a dispatched Op reads the resource from, when a
+ * ConvergeOp with an observer step fired its rule for one resource (#2778).
+ */
+export const CONVERGE_RESOURCE_ENV = "CHANT_CONVERGE_RESOURCE";
+
+/** Every field a {@link ResourceSymptom} produces: OPS014's whitelist for a ConvergeOp with an observer step. */
+export const RESOURCE_SYMPTOM_FIELDS: ReadonlySet<string> = new Set(["env", "resource", "status", "detail"]);
+
+const RESOURCE_STATUSES: ReadonlySet<string> = new Set(["in-sync", "drifted", "unknown"]);
+
+/**
+ * Read an observer step's result as a {@link ResourceObservation}. The
+ * result is the observation itself, or a `shell()` step's result whose
+ * stdout is the observation as JSON. Throws, naming what is wrong, on
+ * anything else: a tick must not converge from a reading it can't parse.
+ */
+export function parseResourceObservation(value: unknown): ResourceObservation {
+  let candidate: unknown = value;
+  if (candidate && typeof candidate === "object" && !("resources" in candidate) && typeof (candidate as { stdout?: unknown }).stdout === "string") {
+    const stdout = (candidate as { stdout: string }).stdout;
+    try {
+      candidate = JSON.parse(stdout);
+    } catch {
+      throw new Error(`the observer step's stdout is not JSON: ${stdout.slice(0, 120)}`);
+    }
+  }
+  const resources = (candidate as { resources?: unknown } | null)?.resources;
+  if (!Array.isArray(resources)) {
+    throw new Error("the observer step returned no `resources` array: it must return { resources: [{ name, status }] }, or print it as JSON");
+  }
+  const seen = new Set<string>();
+  const out: ObservedResource[] = [];
+  for (const [i, r] of resources.entries()) {
+    const entry = r as { name?: unknown; status?: unknown; detail?: unknown } | null;
+    if (!entry || typeof entry.name !== "string" || entry.name === "") {
+      throw new Error(`the observer step's resources[${i}] has no name`);
+    }
+    if (typeof entry.status !== "string" || !RESOURCE_STATUSES.has(entry.status)) {
+      throw new Error(`the observer step's resource "${entry.name}" has status ${JSON.stringify(entry.status)}: it must be in-sync, drifted or unknown`);
+    }
+    if (seen.has(entry.name)) throw new Error(`the observer step reported resource "${entry.name}" twice`);
+    seen.add(entry.name);
+    out.push({
+      name: entry.name,
+      status: entry.status as ResourceStatus,
+      ...(typeof entry.detail === "string" && entry.detail !== "" ? { detail: entry.detail } : {}),
+    });
+  }
+  return { resources: out };
+}

package/src/lint/rules/index.ts

@@ -1,5 +1,6 @@
 /**
- * Core lint rules for chant projects (COR + EVL).
+ * Core lint rules for chant projects (COR + EVL, and SYS001 for the `decide`
+ * activity's backends, #2828).
  */
 
 import type { LintRule } from "../rule";
@@ -29,6 +30,7 @@ export { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-
 export { cor021EnvLiteralNameRule } from "./cor021-env-literal-name";
 export { cor022ReceiptLeafRule, collectReceiptVariables, receiptFactoryCall } from "./cor022-receipt-leaf";
 export { cor024ReceiptSecretPointerRule } from "./cor024-receipt-secret-pointer";
+export { noLiteralKeyRule } from "./sys001-no-literal-key";
 export { isInsideCompositeFactory } from "./composite-scope";
 
 import { flatDeclarationsRule } from "./flat-declarations";
@@ -56,9 +58,10 @@ import { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-
 import { cor021EnvLiteralNameRule } from "./cor021-env-literal-name";
 import { cor022ReceiptLeafRule } from "./cor022-receipt-leaf";
 import { cor024ReceiptSecretPointerRule } from "./cor024-receipt-secret-pointer";
+import { noLiteralKeyRule } from "./sys001-no-literal-key";
 
 /**
- * Load all 24 core lint rules (COR + EVL).
+ * Load all core lint rules (COR + EVL + SYS001).
  */
 export function loadCoreRules(): LintRule[] {
   return [
@@ -87,5 +90,6 @@ export function loadCoreRules(): LintRule[] {
     cor021EnvLiteralNameRule,
     cor022ReceiptLeafRule,
     cor024ReceiptSecretPointerRule,
+    noLiteralKeyRule,
   ];
 }

package/src/lint/rules/op/index.ts

@@ -5,7 +5,8 @@
  * `coreReceiptChecks`) so they run over the FULL build result regardless of
  * which lexicons are configured — an Op is recognized by entity type
  * (`../../../op/resource.ts`'s `OpResource`), not by which lexicon declared
- * it.
+ * it. SYS010 (#2828) joined them when the `decide` activity moved into core:
+ * it reads the decide steps, and the `decide.backends` the caller passes.
  */
 
 import type { PostSynthCheck } from "../../post-synth";
@@ -13,13 +14,25 @@ import { ops012 } from "./ops012-activity-contract";
 import { ops013 } from "./ops013-step-output-ref";
 import { ops014 } from "./ops014-converge-rule-refusals";
 import { ops015 } from "./ops015-gate-approval";
+import { sys010Check } from "./sys010-key-over-plain-http";
+import type { DecideBackend } from "../../../op/decide-config";
 
 export { ops012 } from "./ops012-activity-contract";
 export { ops013 } from "./ops013-step-output-ref";
 export { ops014 } from "./ops014-converge-rule-refusals";
 export { ops015 } from "./ops015-gate-approval";
+export { sys010, sys010Check } from "./sys010-key-over-plain-http";
 
-/** Core's own post-synth checks over the Op model — OPS012, OPS013, OPS014, OPS015. */
-export function coreOpChecks(): PostSynthCheck[] {
-  return [ops012, ops013, ops014, ops015];
+export interface CoreOpCheckOptions {
+  /** `decide.backends` from the project's chant.config, for SYS010 (#2828). */
+  decideBackends?: Record<string, Pick<DecideBackend, "url" | "key">>;
+}
+
+/**
+ * Core's own post-synth checks over the Op model: OPS012, OPS013, OPS014,
+ * OPS015, and SYS010 over the `decide` steps and the configured decide
+ * backends.
+ */
+export function coreOpChecks(opts: CoreOpCheckOptions = {}): PostSynthCheck[] {
+  return [ops012, ops013, ops014, ops015, sys010Check(opts.decideBackends)];
 }

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

@@ -8,7 +8,7 @@ import type { PostSynthContext } from "../../post-synth";
 import { DECLARABLE_MARKER } from "../../../declarable";
 import { when, eq, gt, allOf, run, report } from "../../../op";
 import type { ConvergeRule } from "../../../op";
-import type { ConvergeSymptom } from "../../../lifecycle/symptoms";
+import type { ConvergeSymptom, ResourceSymptom } from "../../../lifecycle/symptoms";
 import { ops014 } from "./ops014-converge-rule-refusals";
 
 function makeEntity(entityType: string, props: Record<string, unknown>) {
@@ -261,3 +261,25 @@ describe("OPS014: converge-rule-refusals", () => {
     expect(ops014.check(ctx)).toHaveLength(0);
   });
 });
+
+describe("OPS014 over a ConvergeOp with an observer step (#2778)", () => {
+  test("its rules are checked against ResourceSymptom's fields", () => {
+    const observed = (rules: unknown[]) =>
+      makeEntity("Chant::Op", {
+        name: "box-converge",
+        overview: "test",
+        labels: { Converge: "true", Env: "box", Dial: "apply", Observe: "step" },
+        phases: [
+          { name: "Observe", steps: [{ kind: "activity", fn: "spriteServicesObserve", args: {}, id: "observe" }] },
+          { name: "Converge", steps: [{ kind: "activity", fn: "convergeTick", args: { rules, observed: { kind: "step-output-ref", step: "observe" } } }] },
+        ],
+      });
+    const restartOp = opEntity("restart-service", [{ kind: "activity", fn: "spriteServiceRestart", args: {} }]);
+    const good = when<ResourceSymptom>(eq("status", "drifted"), run("restart-service"), { id: "restart", why: "x" });
+    const wrongField = { ...good, id: "adopt", when: { kind: "field-comparison", field: "adoptCount", op: "gt", value: 0 } };
+    const ok = ops014.check(makeCtxFromEntities(new Map<string, unknown>([["c", observed([good])], ["r", restartOp]])));
+    expect(ok).toEqual([]);
+    const bad = ops014.check(makeCtxFromEntities(new Map<string, unknown>([["c", observed([wrongField])], ["r", restartOp]])));
+    expect(bad.map((d) => d.message)).toEqual([expect.stringMatching(/rule "adopt": predicate is outside the evaluable subset/)]);
+  });
+});

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