@intentius/chant 0.90.0 → 0.93.0

package/src/op/command-gate.test.ts

@@ -0,0 +1,192 @@
+/**
+ * #2779 — a step whose command stops at a gate of its own stops its run
+ * there. The stand-in below behaves like `chant workspace upgrade --json` in
+ * the part an Op sees: it reads its gate (`workspace-upgrade` / `<scope>`) on
+ * the gate ledger, prints `{ outcome: "gated", pending }` and exits 3 while
+ * nobody has approved the pending fact, and applies and commits once someone
+ * has.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, contract, git, repo } from "../workspace/__fixtures__/contract-repo";
+import statusSchema from "../workspace/status.schema.json";
+import { readMemberStewards } from "../workspace/status-stewards";
+import { appendGateResolution, appendPendingGate } from "../lifecycle/gate-ledger";
+import { readRunLedger } from "../lifecycle/run-ledger";
+import { readLeaseHistory } from "../lifecycle/work-lease";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import { shellCmd } from "./activities/shell";
+import { runOpLocally } from "./local-executor";
+import { formatRoundLine, runOperatorRound } from "./operator";
+import { declareSteward } from "./steward";
+import { isGateWait } from "./gate-wait";
+import { workLeaseOutput } from "./work-lease-run";
+import { WORKSPACE_UPGRADE_GATE_OP } from "./gate-name";
+import type { OpConfig } from "./types";
+
+const PROFILES: Record<string, ActivityProfile> = { atMostOnce: { timeout: "60s" } };
+const ACTIVITIES = new Map<string, ActivityFn>([["shellCmd", ((args, signal) => shellCmd(args as never, signal)) as ActivityFn]]);
+
+/** `chant workspace upgrade <scope> --json`, as far as its gate goes. */
+const STAND_IN = `
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+const scope = process.argv[2];
+let text = "";
+try { text = execFileSync("git", ["show", "chant/lifecycle:_gates/workspace-upgrade.jsonl"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); } catch {}
+const lines = text.split("\\n").filter(Boolean).map((l) => JSON.parse(l)).filter((l) => l.gate === scope);
+const pending = lines.filter((l) => l.kind === "pending").at(-1);
+if (!pending) { console.error("no pending fact: the test records it"); process.exit(1); }
+const approved = lines.some((l) => l.kind !== "pending" && Date.parse(l.timestamp) >= Date.parse(pending.timestamp));
+if (!approved) {
+  console.log(JSON.stringify({ outcome: "gated", scope, pending }, null, 2));
+  process.exit(3);
+}
+writeFileSync("upgraded-" + scope + ".txt", "upgraded\\n");
+execFileSync("git", ["add", "-A"]);
+execFileSync("git", ["commit", "-q", "-m", "upgrade " + scope]);
+console.log(JSON.stringify({ outcome: "applied", scope }, null, 2));
+`;
+
+let root: string;
+
+beforeAll(() => {
+  root = repo({ "chant.config.json": "{}\n", "tools/upgrade.mjs": STAND_IN }, false);
+  git(root, "config", "user.name", "Gate Test");
+  git(root, "config", "user.email", "gate@example.com");
+  commitAll(root, "c0");
+});
+afterAll(cleanScratch);
+
+function upgradeOp(name: string, scope: string, extra: Partial<OpConfig> = {}): OpConfig {
+  return {
+    name,
+    overview: "chant workspace upgrade in a work-lease worktree",
+    changesCheckout: true,
+    workLease: { item: scope === "." ? "workspace-upgrade" : `upgrade-${scope}` },
+    phases: [
+      {
+        name: "Upgrade",
+        steps: [
+          {
+            kind: "activity",
+            fn: "shellCmd",
+            id: "upgrade",
+            args: { cmd: `node ${JSON.stringify(join(root, "tools", "upgrade.mjs"))} ${scope}`, cwd: workLeaseOutput("worktree"), gatedExit: 3 },
+          },
+        ],
+      },
+      { name: "After", steps: [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }] },
+    ],
+    ...extra,
+  };
+}
+
+/** What `chant workspace upgrade` records when it stages a patch nobody has approved. */
+async function stage(scope: string): Promise<string> {
+  const timestamp = new Date().toISOString();
+  await appendPendingGate(
+    { op: WORKSPACE_UPGRADE_GATE_OP, gate: scope, timestamp, expiresAt: new Date(Date.now() + 3_600_000).toISOString(), description: `upgrade ${scope}` },
+    { cwd: root },
+  );
+  return timestamp;
+}
+
+async function approve(scope: string): Promise<void> {
+  await new Promise((r) => setTimeout(r, 5));
+  await appendGateResolution({ op: WORKSPACE_UPGRADE_GATE_OP, gate: scope, resolvedBy: "alice", timestamp: new Date().toISOString() }, { cwd: root });
+}
+
+describe("shell's gatedExit (#2779)", () => {
+  test("the gate comes from the command's JSON, else from the step's gate on the ledger, else the step fails", async () => {
+    const pending = { version: 1, kind: "pending", op: "workspace-upgrade", gate: "web", timestamp: "2027-01-01T00:00:00.000Z", expiresAt: "2027-01-03T00:00:00.000Z" };
+    const printed = JSON.stringify({ outcome: "gated", pending }, null, 2).replace(/'/g, "");
+    const fromJson = await shellCmd({ cmd: `printf '%s' '${printed}'; exit 3`, gatedExit: 3 }).catch((e: unknown) => e);
+    expect(isGateWait(fromJson)).toBe(true);
+    expect((fromJson as { pending: unknown }).pending).toMatchObject({ op: "workspace-upgrade", gate: "web" });
+
+    const since = await stage("named");
+    const named = await shellCmd({ cmd: "exit 3", cwd: root, gatedExit: 3, gate: { op: "workspace-upgrade", gate: "named" } }).catch((e: unknown) => e);
+    expect(isGateWait(named)).toBe(true);
+    expect((named as { pending: { timestamp: string } }).pending.timestamp).toBe(since);
+
+    await expect(shellCmd({ cmd: "exit 3", gatedExit: 3 })).rejects.toThrow(/named no gate/);
+    await expect(shellCmd({ cmd: "exit 3", cwd: root, gatedExit: 3, gate: { op: "workspace-upgrade", gate: "never" } })).rejects.toThrow(/no pending fact/);
+    // Another code still fails, and okExit still passes.
+    await expect(shellCmd({ cmd: "exit 4", gatedExit: 3 })).rejects.toThrow(/command exited 4/);
+    await expect(shellCmd({ cmd: "exit 1", gatedExit: 3, okExit: [0, 1] })).resolves.toMatchObject({ exitCode: 1 });
+  });
+});
+
+describe("an Op whose step runs chant workspace upgrade in a work-lease worktree (#2779)", () => {
+  test("records its first run gated with the gate, releases the lease gated, and applies once approved", async () => {
+    const since = await stage(".");
+    const config = upgradeOp("upgrade", ".");
+    const first = await runOpLocally(config, ACTIVITIES, PROFILES, undefined, { cwd: root, ledger: { cwd: root } });
+
+    expect(first.status).toBe("gated");
+    expect(first.gate).toMatchObject({ op: "workspace-upgrade", gate: ".", timestamp: since });
+    expect(first.records.map((r) => [r.fn, r.status])).toEqual([["workLease:claim", "ok"], ["shellCmd", "skipped"], ["shellCmd", "skipped"]]);
+    expect(first.records[1].gate).toEqual({ op: "workspace-upgrade", gate: "." });
+    expect(first.workLease).toMatchObject({ item: "workspace-upgrade", released: true, outcome: "gated" });
+
+    const newest = (await readRunLedger("local", "upgrade", { cwd: root })).records.at(-1)!;
+    expect(newest).toMatchObject({ status: "gated", gate: { name: ".", since, op: "workspace-upgrade" } });
+    expect(newest.phases[0].steps[1]).toMatchObject({ fn: "shellCmd", status: "skipped", gate: { op: "workspace-upgrade", gate: "." } });
+    expect((await readLeaseHistory("workspace-upgrade", { cwd: root })).records.at(-1)).toMatchObject({ event: "release", outcome: "gated" });
+
+    // workspace status shows the gate the Op's run waits on, with the command that approves it.
+    const steward = declareSteward({ name: "box-steward", ops: [config] });
+    mkdirSync(join(root, "ops"), { recursive: true });
+    writeFileSync(join(root, "ops", "steward.op.ts"), `export const steward = ${JSON.stringify(steward)};\n`);
+    const status = await readMemberStewards(root, "local", new Date().toISOString());
+    expect(status.reasons).toEqual([]);
+    const entry = status.stewards.find((s) => s.name === "box-steward")!;
+    contract({ $schema: statusSchema.$schema, $id: "urn:test:status-steward-gate", $defs: statusSchema.$defs, $ref: "#/$defs/steward" }).expectValid(entry);
+    expect(entry.ops[0].lastRun).toMatchObject({
+      status: "gated",
+      gate: { name: ".", since, op: "workspace-upgrade", approve: "chant approve workspace-upgrade ." },
+    });
+
+    // `chant approve workspace-upgrade .`, and the next run applies the patch in the worktree.
+    await approve(".");
+    const second = await runOpLocally(config, ACTIVITIES, PROFILES, undefined, { cwd: root, ledger: { cwd: root } });
+    expect(second.status).toBe("ok");
+    expect(second.records.map((r) => [r.fn, r.status])).toEqual([["workLease:claim", "ok"], ["shellCmd", "ok"], ["shellCmd", "ok"]]);
+    expect(second.workLease).toMatchObject({ released: true, outcome: "done" });
+    expect(git(root, "show", `${second.workLease!.branch}:upgraded-..txt`)).toBe("upgraded");
+    expect(existsSync(join(root, "upgraded-..txt"))).toBe(false);
+    const status2 = await readMemberStewards(root, "local", new Date().toISOString());
+    expect(status2.stewards[0].ops[0].lastRun).toMatchObject({ status: "ok", gate: null });
+  });
+
+  test("a local steward leaves its gated run while the gate stands, and runs it again once a person approves", async () => {
+    await stage("web");
+    const config = upgradeOp("upgrade-web", "web", { schedule: { cron: "0 0 1 1 *" } });
+    const steward = declareSteward({ name: "web-steward", ops: [config] });
+    const scheduleState = new Map<string, Date>();
+    const round = (minute: number) =>
+      runOperatorRound({ cwd: root, steward, activities: ACTIVITIES, profiles: PROFILES, holder: "box", now: () => new Date(2027, 0, 1, 0, minute, 10), scheduleState });
+
+    const first = await round(0);
+    expect(first[0]).toMatchObject({ kind: "ticked", op: "upgrade-web" });
+    expect((first[0] as { result: { status: string } }).result.status).toBe("gated");
+    expect(formatRoundLine(first[0])).toContain('status=gated gate="web"');
+    expect((await readRunLedger("local", "upgrade-web", { cwd: root })).records.at(-1)).toMatchObject({ status: "gated", steward: "web-steward" });
+
+    const second = await round(5);
+    expect(second).toEqual([{ kind: "waiting-on-gate", op: "upgrade-web", env: "local", gateOp: "workspace-upgrade", gate: "web" }]);
+    expect(formatRoundLine(second[0])).toBe("operator: upgrade-web@local gated=1(gate:workspace-upgrade/web)");
+
+    await approve("web");
+    const third = await round(10);
+    expect(third[0]).toMatchObject({ kind: "ticked", op: "upgrade-web", approved: { op: "workspace-upgrade", gate: "web" } });
+    expect((third[0] as { result: { status: string } }).result.status).toBe("ok");
+    expect(formatRoundLine(third[0])).toContain('approved="workspace-upgrade/web"');
+
+    // Done: the next round waits for the cron again.
+    expect(await round(15)).toEqual([{ kind: "skipped-not-due", op: "upgrade-web", env: "local", cron: "0 0 1 1 *" }]);
+  });
+});

package/src/op/composites/converge-op.test.ts

@@ -3,7 +3,8 @@ import { runOpLocally } from "../local-executor";
 import type { ActivityFn, ActivityProfile } from "../activity-registry";
 import type { OpConfig } from "../types";
 import { eq, gt, run, report, when } from "../converge-rule";
-import type { ConvergeSymptom } from "../../lifecycle/symptoms";
+import type { ConvergeSymptom, ResourceSymptom } from "../../lifecycle/symptoms";
+import { activity } from "../builders";
 import { ConvergeOp } from "./converge-op";
 
 function props(op: unknown): OpConfig {
@@ -166,3 +167,28 @@ describe("ConvergeOp — end-to-end local run (#1484)", () => {
     expect(result.status).toBe("ok");
   });
 });
+
+describe("ConvergeOp with an observer step (#2778)", () => {
+  const restart = when<ResourceSymptom>(eq("status", "drifted"), run("restart-service"), { id: "restart-drifted", why: "Restart a drifted service." });
+  const observer = activity("spriteServicesObserve", { services: [{ name: "app" }] });
+
+  test("the observer is the Observe phase, and its whole result is the tick's observation", () => {
+    const { op } = ConvergeOp({ name: "box-converge", env: "box", dial: "apply", observe: observer, rules: [restart], schedule: "* * * * *" });
+    const config = props(op);
+    expect(config.labels).toEqual({ Converge: "true", Env: "box", Dial: "apply", Observe: "step" });
+    expect(config.schedule).toEqual({ cron: "* * * * *", overlap: "skip" });
+    expect(phaseNamed(op, "Observe").steps).toEqual([{ ...observer, id: "observe" }]);
+    const tickStep = phaseNamed(op, "Converge").steps[0] as { fn: string; args: Record<string, unknown> };
+    expect(tickStep.fn).toBe("convergeTick");
+    expect(tickStep.args.observed).toMatchObject({ kind: "step-output-ref", step: "observe" });
+    expect(tickStep.args.preflightDrift).toBeUndefined();
+    expect(tickStep.args.rules).toEqual([restart]);
+  });
+
+  test("an observer's own id is kept, and a rule over a field ResourceSymptom doesn't produce is refused", () => {
+    const { op } = ConvergeOp({ name: "box-converge", env: "box", observe: activity("shellCmd", { cmd: "./probe" }, { id: "probe" }), rules: [restart] });
+    expect((phaseNamed(op, "Converge").steps[0] as unknown as { args: { observed: { step: string } } }).args.observed.step).toBe("probe");
+    const envRule = when<ConvergeSymptom>(gt("adoptCount", 0), report("x"), { id: "adopt", why: "x" });
+    expect(() => ConvergeOp({ name: "box-converge", env: "box", observe: observer, rules: [envRule as never] })).toThrow(/ResourceSymptom/);
+  });
+});

package/src/op/composites/converge-op.ts

@@ -45,9 +45,11 @@
 
 import { Op, phase, activity } from "../builders";
 import type { OpResource } from "../resource";
+import type { ActivityStep } from "../types";
+import { stepOutput } from "../step-output-ref";
 import { isWellFormedPredicate, duplicateRuleIds, type ConvergeRule } from "../converge-rule";
-import type { ConvergeSymptom } from "../../lifecycle/symptoms";
-import { CONVERGE_SYMPTOM_FIELDS } from "../../lifecycle/symptoms";
+import type { ConvergeSymptom, ResourceSymptom } from "../../lifecycle/symptoms";
+import { CONVERGE_SYMPTOM_FIELDS, RESOURCE_SYMPTOM_FIELDS } from "../../lifecycle/symptoms";
 
 /**
  * Authority level for this ConvergeOp's environment — issue #1484's own
@@ -96,7 +98,7 @@ import { CONVERGE_SYMPTOM_FIELDS } from "../../lifecycle/symptoms";
  */
 export type ConvergeDial = "observe" | "reconcile" | "apply";
 
-export interface ConvergeOpConfig {
+interface ConvergeOpCommon {
   /** Op name (kebab-case). Names the Op's output directory and is what `chant run` takes. */
   name: string;
   /** Environment to converge (e.g. "staging"). */
@@ -105,8 +107,6 @@ export interface ConvergeOpConfig {
   dial?: ConvergeDial;
   /** Max number of `run` dispatches per tick — the issue's "the worst tick is bounded" (Accessible Ops factor VI). Rules matched beyond the budget are recorded, not run. @default 3 */
   budget?: number;
-  /** The rule table — build with `when()`/`eq()`/`run()`/`report()` from `@intentius/chant/op`. Non-empty; every rule id must be unique. */
-  rules: ConvergeRule<ConvergeSymptom>[];
   /**
    * Cron expression. When set, it lands on the Op as `schedule` — the cadence
    * `chant operator` ticks this Op on and the CI generators render; omit for
@@ -114,10 +114,40 @@ export interface ConvergeOpConfig {
    * "one-shot runnable locally for a single tick").
    */
   schedule?: string;
+}
+
+/** A ConvergeOp that observes a chant environment through its lexicons. */
+export interface EnvironmentConvergeOpConfig extends ConvergeOpCommon {
+  /** The rule table — build with `when()`/`eq()`/`run()`/`report()` from `@intentius/chant/op`. Non-empty; every rule id must be unique. */
+  rules: ConvergeRule<ConvergeSymptom>[];
   /** Run `chant lifecycle diff --live` in the Observe phase (queries live state). @default true */
   live?: boolean;
+  observe?: undefined;
 }
 
+/**
+ * A ConvergeOp whose Observe phase is a step of its own (#2778), for
+ * resources no lexicon declares or observes, such as the services a
+ * supervisor runs in a box (the fly lexicon's `spriteServicesObserve`).
+ */
+export interface StepConvergeOpConfig extends ConvergeOpCommon {
+  /**
+   * The observer: an activity step that returns a `ResourceObservation`,
+   * `{ resources: [{ name, status: "in-sync" | "drifted" | "unknown", detail? }] }`,
+   * or a `shell()` step that prints one as JSON. Its id defaults to `observe`.
+   */
+  observe: ActivityStep;
+  /**
+   * The rule table, evaluated once per observed resource against a
+   * `ResourceSymptom` (`env`, `resource`, `status`, `detail`). A fired
+   * `run()` is dispatched for that resource: the dispatched Op reads its
+   * name from `CHANT_CONVERGE_RESOURCE`.
+   */
+  rules: ConvergeRule<ResourceSymptom>[];
+}
+
+export type ConvergeOpConfig = EnvironmentConvergeOpConfig | StepConvergeOpConfig;
+
 export interface ConvergeOpResources {
   /** Op resource — the observe-then-converge Op. */
   op: InstanceType<typeof OpResource>;
@@ -126,7 +156,8 @@ export interface ConvergeOpResources {
 export function ConvergeOp(config: ConvergeOpConfig): ConvergeOpResources {
   const dial = config.dial ?? "observe";
   const budget = config.budget ?? 3;
-  const live = config.live ?? true;
+  const observer = config.observe !== undefined ? config.observe : undefined;
+  const fields = observer ? RESOURCE_SYMPTOM_FIELDS : CONVERGE_SYMPTOM_FIELDS;
 
   // ── Build-time refusals (#1484) ─────────────────────────────────────────
   // Thrown here, at Op-construction time — the same "refuse in the factory,
@@ -142,7 +173,7 @@ export function ConvergeOp(config: ConvergeOpConfig): ConvergeOpResources {
   if (config.rules.length === 0) {
     throw new Error(`ConvergeOp "${config.name}": at least one rule is required — an empty table has nothing to converge.`);
   }
-  const dupes = duplicateRuleIds(config.rules);
+  const dupes = duplicateRuleIds<unknown>(config.rules as ConvergeRule<unknown>[]);
   if (dupes.length > 0) {
     throw new Error(
       `ConvergeOp "${config.name}": duplicate rule id(s) [${dupes.join(", ")}] — flap-damping counters are keyed by id, so ids must be unique.`,
@@ -157,13 +188,40 @@ export function ConvergeOp(config: ConvergeOpConfig): ConvergeOpResources {
       // assembled by hand (bypassing when()) reaches here too.
       throw new Error(`ConvergeOp "${config.name}", rule "${rule.id}": every rule must carry its why — refused at build.`);
     }
-    if (!isWellFormedPredicate(rule.when, CONVERGE_SYMPTOM_FIELDS)) {
+    if (!isWellFormedPredicate(rule.when, fields)) {
       throw new Error(
         `ConvergeOp "${config.name}", rule "${rule.id}": predicate is outside the evaluable subset — build it from ` +
-          `eq/neq/gt/gte/lt/lte/truthy/falsy/allOf/anyOf over a field ConvergeSymptom actually produces.`,
+          `eq/neq/gt/gte/lt/lte/truthy/falsy/allOf/anyOf over a field ${observer ? "ResourceSymptom" : "ConvergeSymptom"} actually produces.`,
       );
     }
   }
+  if (observer && observer.kind !== "activity") {
+    throw new Error(`ConvergeOp "${config.name}": observe must be an activity step, such as shell() or spriteServicesObserve()`);
+  }
+
+  const labels = { Converge: "true", Env: config.env, Dial: dial, ...(observer ? { Observe: "step" } : {}) };
+  const schedule = config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" as const } } : {};
+
+  if (observer) {
+    // #2778: the observer step is the Observe phase, and its whole result is
+    // the tick's observation.
+    const observeStep: ActivityStep = { ...observer, id: observer.id ?? "observe" };
+    const tickStep = activity(
+      "convergeTick",
+      { opName: config.name, env: config.env, dial, budget, rules: config.rules, observed: stepOutput(observeStep.id!) },
+      "longInfra",
+    );
+    tickStep.outcomeAttribute = { name: "Remediated", from: "remediated" };
+    const op = Op({
+      name: config.name,
+      overview: `Converge ${config.env}'s observed resources toward their declaration (dial: ${dial})`,
+      labels,
+      ...schedule,
+      phases: [phase("Observe", [observeStep]), phase("Converge", [tickStep])],
+    });
+    return { op };
+  }
+  const live = (config as EnvironmentConvergeOpConfig).live ?? true;
 
   const snapshotStep = activity("lifecycleSnapshot", { env: config.env }, { id: "snapshot" });
   const diffStep = activity("lifecycleDiff", { env: config.env, live }, { id: "diff", profile: "fastIdempotent" });
@@ -194,11 +252,7 @@ export function ConvergeOp(config: ConvergeOpConfig): ConvergeOpResources {
   const op = Op({
     name: config.name,
     overview: `Converge the ${config.env} environment toward its declaration (dial: ${dial})`,
-    labels: {
-      Converge: "true",
-      Env: config.env,
-      Dial: dial,
-    },
+    labels,
     // Overlap (#1484 acceptance criterion: "skip-and-report when a prior
     // remediation is in flight ... never queue"). `"skip"` is the only value
     // `OpSchedule` has, and it means exactly that: a fire arriving while the
@@ -206,7 +260,7 @@ export function ConvergeOp(config: ConvergeOpConfig): ConvergeOpResources {
     // alongside. There is no per-tick "in flight" ledger record for the
     // skipped fire to produce — nothing ran, so nothing observed, classified,
     // or dispatched.
-    ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" as const } } : {}),
+    ...schedule,
     phases: [phase("Observe", [snapshotStep, diffStep]), phase("Converge", [tickStep])],
   });
 

package/src/op/decide-backend.test.ts

@@ -0,0 +1,44 @@
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { backendAsk, postQuestion, questionName } from "./decide-backend";
+import { requestProblem, startStubBackend, type StubBackend } from "./__fixtures__/decide-stub-backend";
+
+let stub: StubBackend;
+beforeAll(async () => {
+  stub = await startStubBackend({ model: "jev-1.13.0" });
+});
+afterAll(() => stub.close());
+
+const request = { point: "slice-tier", backend: "local", model: "jev-1.13.0", question: { type: "choice" as const, instructions: "Pick", criteria: { small: "s", large: "l" } }, state: { size: 3 } };
+
+describe("the wire-format client", () => {
+  test("a point's name is the question's name, as points ask --response reads it", () => {
+    expect(questionName("slice-tier")).toBe("slice-tier");
+  });
+
+  test("posts to /v1/systemone and reads the answer back by the question's name", async () => {
+    const r = await postQuestion({ url: `${stub.url}/` }, "local", request, { cwd: process.cwd() });
+    expect(r.model).toBe("jev-1.13.0");
+    expect(r.answer).toMatchObject({ type: "choice", choice: "small" });
+    expect(Object.keys(stub.requests[stub.requests.length - 1].questions)).toEqual(["slice-tier"]);
+  });
+
+  test("a name no backend has, and a timeout, throw", async () => {
+    await expect(backendAsk({ backends: {}, cwd: process.cwd() })(request)).rejects.toThrow("no backend named local is configured");
+    const hang = (_url: unknown, init?: { signal?: AbortSignal }) => new Promise<Response>((_, reject) => init?.signal?.addEventListener("abort", () => reject(new Error("aborted"))));
+    await expect(postQuestion({ url: "http://127.0.0.1:9", timeoutMs: 20 }, "local", request, { cwd: process.cwd(), transport: hang as never })).rejects.toThrow("no answer within 20 ms");
+  });
+
+  test("a response without the answer, or not JSON, throws", async () => {
+    const fake = (body: string) => (async () => new Response(body, { status: 200 })) as never;
+    await expect(postQuestion({ url: "http://x" }, "b", request, { cwd: process.cwd(), transport: fake('{"model":"jev-1.13.0","answers":{}}') })).rejects.toThrow("has no answer to slice-tier");
+    await expect(postQuestion({ url: "http://x" }, "b", request, { cwd: process.cwd(), transport: fake("<html>") })).rejects.toThrow("not JSON");
+  });
+});
+
+describe("the stub", () => {
+  test("refuses a request outside the wire format with 422", async () => {
+    expect(requestProblem({ model: "m", state: {}, questions: { q: { type: "score", instructions: "i", criteria: ["one"] } } })).toContain("2 to 10 levels");
+    const res = await fetch(`${stub.url}/v1/systemone`, { method: "POST", body: JSON.stringify({ model: "m" }) });
+    expect(res.status).toBe(422);
+  });
+});

package/src/op/decide-backend.ts

@@ -0,0 +1,212 @@
+/**
+ * The client for the `POST /v1/systemone` wire format (#2491): TypeSafe's Jev
+ * API, and every server that implements the same request and response.
+ *
+ * ```
+ * POST <url>/v1/systemone          Authorization: Bearer <key>
+ * { "model": "jev-1.13.0", "state": {...}, "questions": { "<name>": { "type": "noul" | "choice" | "score", "instructions": ..., "criteria": ... } } }
+ *
+ * { "model": "jev-1.13.0", "answers": { "<name>": { "type": "noul", "noul": 0.22 } | { "type": "choice", "choice": ..., "probabilities": {...}, "confidence": ... } | { "type": "score", ... } } }
+ * ```
+ *
+ * {@link backendAsk} turns a set of backends into core's `ModelAsk`, the
+ * model call `askPoint` takes (`../workspace/points.ts`). This file
+ * only speaks the wire format: whether an answer is observed, proposed or
+ * escalated, and what a point does when the backend is unreachable, are
+ * core's (`runChain`), so they are the same for this client, for a response
+ * handed to `points ask --response`, and for any runtime's decider.
+ *
+ * The model id is sent as the point pins it. An alias such as `jev-latest` is
+ * refused where the point is declared, and the response's `model` is compared
+ * with the pin by core, so an alias that moved is never recorded as the pin.
+ *
+ * Anything that stops an answer arriving throws: no key, a network error, a
+ * timeout, a non-2xx status (Jev's are 401, 422, 429 and 529), or a response
+ * without an answer to the question asked. Core reads a throw as the backend
+ * being unreachable and follows the point's `unreachable`.
+ *
+ * It reads the workspace declaration for a brokered key, so it loads code
+ * under `workspace/`: the `decide` activity imports it on first call, never
+ * at module load (#2525 rule 5).
+ */
+
+import type { ModelAsk, ModelRequest, WireAnswer } from "../workspace/points";
+import { readDeclaration } from "../workspace/declaration";
+import { locateWorkspace } from "../workspace/which-chant";
+import type { BackendKey, BrokeredKey, DecideBackend } from "./decide-config";
+
+/** The path every Jev-compatible server serves. */
+export const SYSTEMONE_PATH = "/v1/systemone";
+
+/** How long a call may take before the backend counts as unreachable, when the backend names no `timeoutMs`. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** The request body. */
+export interface BackendRequest {
+  model: string;
+  state: unknown;
+  questions: Record<string, { type: string; instructions: string; criteria: Record<string, string> | string[] }>;
+}
+
+/** The response body, as far as this client reads it. */
+export interface BackendResponse {
+  model: string;
+  answers: Record<string, WireAnswer>;
+  usage?: { input_tokens?: number; output_tokens?: number };
+}
+
+/**
+ * The name a point's question is sent under: the point's own name, so a
+ * response reads back the way `points ask --response` reads one, with the
+ * answer under `answers["<point>"]`.
+ */
+export const questionName = (point: string): string => point;
+
+/** A backend or key that is configured wrongly: the activity refuses before asking anything. */
+export class DecideConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DecideConfigError";
+  }
+}
+
+/** Where a brokered capability is declared: the member and its broker. */
+export interface BrokeredCapability {
+  member: string;
+  broker: string;
+  scope: string[];
+}
+
+/**
+ * The declaration's entry for a brokered key (#2726): the box member that
+ * declares the capability, and the broker it names. Read from the workspace
+ * declaration nearest above `cwd`, the same declaration `workspace status`
+ * reads it from. Throws a {@link DecideConfigError} when no member declares
+ * the capability, when more than one does and the key names none, or when the
+ * capability names no broker.
+ */
+export function brokeredCapability(key: BrokeredKey, cwd: string): BrokeredCapability {
+  let members;
+  try {
+    members = readDeclaration(locateWorkspace(cwd).tree).members;
+  } catch (err) {
+    throw new DecideConfigError(`the key names the brokered capability ${key.capability}, and the workspace declaration can't be read: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const declaring = members.filter((m) => (key.member === undefined || m.name === key.member) && m.box?.capabilities.some((c) => c.name === key.capability));
+  if (declaring.length === 0) {
+    const what = key.member !== undefined ? `member ${key.member}'s box does not declare the capability ${key.capability}` : `no member's box declares the capability ${key.capability}`;
+    throw new DecideConfigError(`${what} (box.capabilities in chant.workspace.json, #2726)`);
+  }
+  if (declaring.length > 1) {
+    throw new DecideConfigError(`the capability ${key.capability} is declared by ${declaring.map((m) => m.name).join(" and ")}: name the member in the key`);
+  }
+  const member = declaring[0];
+  const capability = member.box!.capabilities.find((c) => c.name === key.capability)!;
+  if (capability.broker === null) {
+    throw new DecideConfigError(`member ${member.name}'s capability ${key.capability} names no broker (WSP122), so nothing holds its key`);
+  }
+  return { member: member.name, broker: capability.broker, scope: capability.scope };
+}
+
+/** Check a key reference without reading any secret: a string is a literal and refused, and a brokered capability must be declared. */
+export function checkKey(key: unknown, where: string, cwd: string): void {
+  if (key === undefined) return;
+  if (typeof key === "string") {
+    throw new DecideConfigError(`${where} is a literal string; a key is { env: "<VARIABLE>" } or a brokered capability, never the key itself (SYS001)`);
+  }
+  if (key !== null && typeof key === "object" && "capability" in key) brokeredCapability(key as BrokeredKey, cwd);
+}
+
+/**
+ * The bearer key for one call, or undefined when none is sent: a backend with
+ * no key, or a brokered capability whose broker is the endpoint. Throws when a
+ * variable the key names is unset, which the chain reads as unreachable.
+ */
+export function resolveKey(key: BackendKey | undefined, cwd: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  if (key === undefined) return undefined;
+  if ("capability" in key) {
+    const brokered = brokeredCapability(key, cwd);
+    if (key.env === undefined) return undefined;
+    const value = env[key.env];
+    if (!value) throw new Error(`the broker ${brokered.broker} has not set ${key.env} for the capability ${key.capability}`);
+    return value;
+  }
+  const value = env[key.env];
+  if (!value) throw new Error(`the environment variable ${key.env} is not set`);
+  return value;
+}
+
+export interface BackendAskOptions {
+  /** Backend name, as a point's model decider names it, to the backend. */
+  backends: Record<string, DecideBackend>;
+  /** Where the workspace declaration is found, for a brokered key. */
+  cwd: string;
+  /** The HTTP call. Defaults to the global fetch; a test passes its own. */
+  transport?: typeof fetch;
+  /** Defaults to process.env. */
+  env?: NodeJS.ProcessEnv;
+  /** Cancels an in-flight call, such as the Op's timeout. */
+  signal?: AbortSignal;
+  /** Called with each response, for usage and logs. */
+  onResponse?: (backend: string, response: BackendResponse) => void;
+}
+
+function short(text: string): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > 300 ? `${flat.slice(0, 300)}...` : flat;
+}
+
+/** Post one question to one backend and return the model that answered and its answer. */
+export async function postQuestion(backend: DecideBackend, name: string, request: ModelRequest, opts: Omit<BackendAskOptions, "backends">): Promise<{ model: string; answer: WireAnswer; response: BackendResponse }> {
+  const key = resolveKey(backend.key, opts.cwd, opts.env);
+  const question = questionName(request.point);
+  const body: BackendRequest = {
+    model: request.model,
+    state: request.state,
+    questions: { [question]: { type: request.question.type, instructions: request.question.instructions, criteria: request.question.criteria } },
+  };
+  const url = `${backend.url.replace(/\/+$/, "")}${SYSTEMONE_PATH}`;
+  const timeout = AbortSignal.timeout(backend.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+  let res: Response;
+  try {
+    res = await (opts.transport ?? fetch)(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json", ...(key ? { authorization: `Bearer ${key}` } : {}) },
+      body: JSON.stringify(body),
+      signal,
+    });
+  } catch (err) {
+    const why = timeout.aborted ? `no answer within ${backend.timeoutMs ?? DEFAULT_TIMEOUT_MS} ms` : err instanceof Error ? err.message : String(err);
+    throw new Error(`${name} at ${url}: ${why}`);
+  }
+  const text = await res.text();
+  if (!res.ok) throw new Error(`${name} at ${url} answered ${res.status}${text ? `: ${short(text)}` : ""}`);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`${name} at ${url} answered with something that is not JSON: ${short(text)}`);
+  }
+  const r = parsed as Partial<BackendResponse> | null;
+  if (r === null || typeof r !== "object") throw new Error(`${name} answered with no JSON object`);
+  if (typeof r.model !== "string" || r.model === "") throw new Error(`${name}'s response names no model`);
+  const answer = r.answers?.[question];
+  if (answer === null || typeof answer !== "object") throw new Error(`${name}'s response has no answer to ${question}`);
+  return { model: r.model, answer, response: r as BackendResponse };
+}
+
+/**
+ * The model call for `askPoint`: each request goes to the backend its decider
+ * names. A name no backend has throws, and so does anything
+ * {@link postQuestion} throws, which the chain reads as unreachable.
+ */
+export function backendAsk(opts: BackendAskOptions): ModelAsk {
+  return async (request) => {
+    const backend = opts.backends[request.backend];
+    if (!backend) throw new Error(`no backend named ${request.backend} is configured (decide.backends)`);
+    const { model, answer, response } = await postQuestion(backend, request.backend, request, opts);
+    opts.onResponse?.(request.backend, response);
+    return { model, answer };
+  };
+}