@intentius/chant 0.90.0 → 0.93.0

package/src/op/activities/decide.test.ts

@@ -0,0 +1,300 @@
+/**
+ * The decide activity against the stub backend (#2740): a noul, a choice and
+ * a score answered and recorded, the run waiting on an open question until a
+ * person answers, reuse, the threshold, an unreachable backend escalating or
+ * failing as the point declares, brokered and literal keys, a steward's turn,
+ * and inputs read through the read contract.
+ */
+
+import { existsSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
+import { enterStewardTurn, isPointWait, resetStewardTurn, type WaitingPoint } from "..";
+import { loadActivities } from "../activity-registry";
+import { answerPoint, type QuestionView } from "../../workspace/decide";
+import { workspacePoints } from "../../workspace/points-cli";
+import type { WireAnswer } from "../../workspace/points";
+import { startStubBackend, type StubBackend } from "../__fixtures__/decide-stub-backend";
+import { cleanScratch, MODEL, recordText, workspace } from "../../workspace/__fixtures__/decide-workspace";
+import { DecideError, runDecide, type DecideArgs } from "./decide";
+
+const KEY = "stub-key-not-a-secret";
+const env = { STUB_KEY: KEY, LOBBY_TOKEN: KEY };
+const on = "2026-09-25";
+
+let root: string;
+let stub: StubBackend;
+/** What the stub answers, by question name, when a test sets it. */
+let script: Record<string, WireAnswer> = {};
+
+const backends = (url = stub.url) => ({ systemone: { url, key: { env: "STUB_KEY" } } });
+const ask = (args: Omit<DecideArgs, "cwd" | "backends"> & { backends?: DecideArgs["backends"] }) => runDecide({ cwd: root, backends: backends(), ...args }, { env, on });
+const answers = () => readdirSync(join(root, "answers")).filter((f) => f.endsWith(".md")).sort();
+
+/** The question an open ask stopped the run on: the step threw core's PointWait. */
+async function waitsOn(p: Promise<unknown>): Promise<WaitingPoint> {
+  const err = await p.then(
+    (r) => {
+      throw new Error(`expected the run to wait, and the step returned ${JSON.stringify(r)}`);
+    },
+    (e: unknown) => e,
+  );
+  if (!isPointWait(err)) throw err;
+  return err.question;
+}
+
+/** The question as the read contract lists it. */
+async function question(id: string): Promise<QuestionView> {
+  const doc = await workspacePoints({ cwd: root });
+  if ("error" in doc) throw new Error(doc.error.message);
+  const q = doc.questions.find((x) => x.id === id);
+  if (!q) throw new Error(`no question ${id}`);
+  return q;
+}
+
+beforeAll(async () => {
+  root = workspace();
+  stub = await startStubBackend({ key: KEY, answers: (q) => script[q.name] ?? (undefined as unknown as WireAnswer) });
+});
+
+afterEach(() => resetStewardTurn());
+
+afterAll(async () => {
+  await stub.close();
+  cleanScratch();
+});
+
+describe("decide against the stub (#2740)", () => {
+  test("a noul: the model's answer at the threshold is recorded as proposed, and the run waits on it", async () => {
+    script = { triage: { type: "noul", noul: 0.91 } };
+    const w = await waitsOn(ask({ point: "triage", inputs: { "record.size": 5, "record.risky": true }, subject: "T-1" }));
+    expect(w).toMatchObject({ point: "triage", state: "proposed", subject: "T-1", steward: null });
+    const q = await question(w.id);
+    expect(q).toMatchObject({ state: "proposed", open: true, answer: true, decider: { kind: "model", backend: "systemone", model: MODEL }, confidence: 0.91, threshold: 0.8, valid: true });
+    expect(q.escalations).toEqual([{ kind: "table", reason: "no row matches these inputs" }]);
+    expect(recordText(root, w.path)).toContain(`model: "${MODEL}"`);
+    // The request went out in the wire format, with the pinned model and the bearer key.
+    expect(stub.requests[stub.requests.length - 1]).toEqual({
+      model: MODEL,
+      state: { "record.size": 5, "record.risky": true },
+      questions: { triage: { type: "noul", instructions: "Does the task need a person to look at it today?", criteria: { true: "A person looks at it today.", false: "It can wait." } } },
+    });
+    expect(stub.authorizations[stub.authorizations.length - 1]).toBe(`Bearer ${KEY}`);
+  });
+
+  test("once a person confirms the proposal, the next run reads the answer and calls nothing", async () => {
+    const w = await waitsOn(ask({ point: "triage", inputs: { "record.risky": true, "record.size": 5 }, subject: "T-1" }));
+    const before = stub.requests.length;
+    const files = answers();
+    const confirmed = await answerPoint({ cwd: root, id: w.id, answer: true, by: ["alice"], on });
+    if ("error" in confirmed) throw new Error(confirmed.error.message);
+    const r = await ask({ point: "triage", inputs: { "record.size": 5, "record.risky": true }, subject: "T-1" });
+    expect(r).toMatchObject({ id: w.id, state: "answered", open: false, answer: true, decider: "model", model: MODEL, backend: "systemone", confidence: 0.91, answeredBy: ["alice"] });
+    expect(stub.requests.length).toBe(before);
+    expect(answers()).toEqual(files);
+  });
+
+  test("a choice: the choice and its probabilities are recorded", async () => {
+    script = { route: { type: "choice", choice: "platform", probabilities: { platform: 0.86, app: 0.1, docs: 0.04 }, confidence: 0.84 } };
+    const w = await waitsOn(ask({ point: "route", inputs: { "record.title": "Rotate the deploy key", "record.size": 5 }, subject: "T-1" }));
+    expect(await question(w.id)).toMatchObject({ state: "proposed", answer: "platform", confidence: 0.84, probabilities: { platform: 0.86, app: 0.1, docs: 0.04 } });
+  });
+
+  test("a score: the most probable level is the answer", async () => {
+    script = { effort: { type: "score", score: 2.7, legend: { 1: "low", 2: "medium", 3: "high" }, probabilities: { low: 0.02, medium: 0.1, high: 0.88 }, confidence: 0.82 } };
+    const w = await waitsOn(ask({ point: "effort", inputs: { "record.size": 5, "member.kind": "other" }, subject: "T-1" }));
+    expect(await question(w.id)).toMatchObject({ state: "proposed", answer: "high", confidence: 0.82 });
+  });
+
+  test("an open question asked again is reused: no second call, no second record", async () => {
+    const before = stub.requests.length;
+    const files = answers();
+    const w = await waitsOn(ask({ point: "route", inputs: { "record.size": 5, "record.title": "Rotate the deploy key" }, subject: "T-1" }));
+    expect(w.state).toBe("proposed");
+    expect(stub.requests.length).toBe(before);
+    expect(answers()).toEqual(files);
+  });
+
+  test("a table row answers before the model is asked, and the step returns it", async () => {
+    const before = stub.requests.length;
+    const r = await ask({ point: "triage", inputs: { "record.size": 0, "record.risky": false } });
+    expect(r).toMatchObject({ state: "answered", open: false, answer: false, decider: "table", model: null });
+    expect(stub.requests.length).toBe(before);
+  });
+
+  test("below the threshold the question escalates to people, with the model's lean", async () => {
+    script = { triage: { type: "noul", noul: 0.6 } };
+    const w = await waitsOn(ask({ point: "triage", inputs: { "record.size": 3, "record.risky": false } }));
+    expect(w.state).toBe("escalated");
+    const q = await question(w.id);
+    expect(q.model).toMatchObject({ answer: true, confidence: 0.6, threshold: 0.8, observed: false });
+    expect(q.escalations[1].reason).toContain("below the threshold");
+  });
+
+  test("a dry run asks, writes nothing, and returns the question whatever its state", async () => {
+    script = { triage: { type: "noul", noul: 0.05 } };
+    const files = answers();
+    const r = await ask({ point: "triage", inputs: { "record.size": 8, "record.risky": false }, dryRun: true });
+    expect(r).toMatchObject({ state: "proposed", open: true, answer: false, decider: "model" });
+    expect(answers()).toEqual(files);
+  });
+});
+
+describe("an unreachable backend follows the point's unreachable", () => {
+  let gone: string;
+  beforeAll(async () => {
+    const s = await startStubBackend();
+    gone = s.url;
+    await s.close();
+  });
+
+  test("escalate (the default): the question is open for people, with why", async () => {
+    const w = await waitsOn(ask({ point: "triage", inputs: { "record.size": 2, "record.risky": true }, backends: backends(gone) }));
+    expect(w.state).toBe("escalated");
+    const e = (await question(w.id)).escalations[1];
+    expect(e).toMatchObject({ kind: "model", backend: "systemone", model: MODEL });
+    expect(e.reason).toMatch(/^not observed: systemone could not answer: systemone at http:\/\/127\.0\.0\.1:\d+\/v1\/systemone/);
+  });
+
+  test("fail: nothing is written and the step fails", async () => {
+    const files = answers();
+    const err = await ask({ point: "route", inputs: { "record.title": "Write the release notes", "record.size": 2 }, backends: backends(gone) }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DecideError);
+    expect((err as DecideError).code).toBe("point-decider-failed");
+    expect((err as Error).message).toContain('unreachable: "fail"');
+    expect(answers()).toEqual(files);
+  });
+
+  test("a 429 from the backend is unreachable too", async () => {
+    const busy = await startStubBackend({ status: 429 });
+    try {
+      const w = await waitsOn(runDecide({ cwd: root, point: "triage", inputs: { "record.size": 4, "record.risky": true }, backends: { systemone: { url: busy.url } } }, { on }));
+      expect((await question(w.id)).escalations[1].reason).toContain("answered 429");
+    } finally {
+      await busy.close();
+    }
+  });
+
+  test("an unset key variable is unreachable, and the point decides", async () => {
+    const w = await waitsOn(runDecide({ cwd: root, point: "triage", inputs: { "record.size": 6, "record.risky": true }, backends: backends() }, { env: {}, on }));
+    expect((await question(w.id)).escalations[1].reason).toContain("the environment variable STUB_KEY is not set");
+  });
+});
+
+describe("the key", () => {
+  test("a brokered capability declared on the box: the broker's variable carries the key", async () => {
+    script = { triage: { type: "noul", noul: 0.97 } };
+    const w = await waitsOn(ask({ point: "triage", inputs: { "record.size": 9, "record.risky": true }, backends: { systemone: { url: stub.url, key: { capability: "inference", member: "box", env: "LOBBY_TOKEN" } } } }));
+    expect(w.state).toBe("proposed");
+    expect(stub.authorizations[stub.authorizations.length - 1]).toBe(`Bearer ${KEY}`);
+  });
+
+  test("a brokered capability without env sends no key: the broker is the endpoint", async () => {
+    const open = await startStubBackend();
+    try {
+      const w = await waitsOn(ask({ point: "triage", inputs: { "record.size": 10, "record.risky": true }, backends: { systemone: { url: open.url, key: { capability: "inference" } } } }));
+      expect(w.state).toBe("proposed");
+      expect(open.authorizations).toEqual([null]);
+    } finally {
+      await open.close();
+    }
+  });
+
+  test.each([
+    ["a capability with no broker", { capability: "raw", member: "box", env: "LOBBY_TOKEN" }, "names no broker"],
+    ["a capability no box declares", { capability: "fountain" }, "no member's box declares the capability fountain"],
+    ["a literal string", "sk-not-a-real-key", "is a literal string"],
+  ])("%s is refused before anything is asked or written", async (_label, key, message) => {
+    const before = stub.requests.length;
+    const files = answers();
+    const err = await ask({ point: "triage", inputs: { "record.size": 11, "record.risky": true }, backends: { systemone: { url: stub.url, key } } as never }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(DecideError);
+    expect((err as DecideError).code).toBe("backend-invalid");
+    expect((err as Error).message).toContain(message);
+    expect(stub.requests.length).toBe(before);
+    expect(answers()).toEqual(files);
+  });
+
+  test("a backend the point names but nobody configured is refused", async () => {
+    const err = await ask({ point: "triage", inputs: { "record.size": 12, "record.risky": true }, backends: { other: { url: stub.url } } }).catch((e: unknown) => e);
+    expect((err as DecideError).code).toBe("backend-invalid");
+    expect((err as Error).message).toContain("names the backend systemone, and none is configured (decide.backends: other)");
+  });
+});
+
+describe("in a steward's turn (#2749)", () => {
+  const brokered = { systemone: { url: "", key: { capability: "inference", member: "box", env: "LOBBY_TOKEN" } } };
+
+  test("the call goes through a capability the steward declares, and the question names the steward", async () => {
+    enterStewardTurn({ steward: "keeper", capabilities: ["inference"], run: "run-1" });
+    script = { triage: { type: "noul", noul: 0.95 } };
+    const before = stub.requests.length;
+    const w = await waitsOn(ask({ point: "triage", inputs: { "record.size": 14, "record.risky": true }, backends: { systemone: { ...brokered.systemone, url: stub.url } } }));
+    expect(w).toMatchObject({ state: "proposed", steward: "keeper" });
+    expect(stub.requests.length).toBe(before + 1);
+    expect((await question(w.id)).askedBy).toEqual({ steward: "keeper", run: "run-1" });
+  });
+
+  test("a steward that does not declare the capability makes no call, and the question goes to people", async () => {
+    enterStewardTurn({ steward: "keeper", capabilities: [] });
+    const before = stub.requests.length;
+    const w = await waitsOn(ask({ point: "triage", inputs: { "record.size": 15, "record.risky": true }, backends: { systemone: { ...brokered.systemone, url: stub.url } } }));
+    expect(w.state).toBe("escalated");
+    expect(stub.requests.length).toBe(before);
+    expect((await question(w.id)).escalations[1].reason).toContain("does not name the brokered capability inference");
+  });
+
+  test("a backend keyed by an environment variable is not called: the steward would hold the key", async () => {
+    enterStewardTurn({ steward: "keeper", capabilities: ["inference"] });
+    const before = stub.requests.length;
+    const w = await waitsOn(ask({ point: "triage", inputs: { "record.size": 16, "record.risky": true } }));
+    expect(w.state).toBe("escalated");
+    expect(stub.requests.length).toBe(before);
+    expect((await question(w.id)).escalations[1].reason).toContain("key is the environment variable STUB_KEY");
+  });
+});
+
+describe("inputs read through the read contract", () => {
+  test("a record by id gives each record.* input its field, and a member by name its own", async () => {
+    script = { effort: { type: "score", probabilities: { low: 0.9, medium: 0.08, high: 0.02 }, confidence: 0.85 } };
+    const w = await waitsOn(ask({ point: "effort", read: { record: "T-2", member: "app" }, subject: "T-2" }));
+    expect(stub.requests[stub.requests.length - 1].state).toEqual({ "record.size": 1, "member.kind": "other" });
+    expect(await question(w.id)).toMatchObject({ answer: "low", inputs: { "record.size": 1, "member.kind": "other" } });
+  });
+
+  test("an input passed as a value wins over the one read", async () => {
+    script = { triage: { type: "noul", noul: 0.02 } };
+    await waitsOn(ask({ point: "triage", read: { record: "T-2" }, inputs: { "record.risky": true } }));
+    expect(stub.requests[stub.requests.length - 1].state).toEqual({ "record.size": 1, "record.risky": true });
+  });
+
+  test("a record that is not there, and an output not read by id, are refused", async () => {
+    await expect(ask({ point: "triage", read: { record: "T-99" } })).rejects.toMatchObject({ code: "point-inputs-invalid", message: expect.stringContaining("no declared record kind holds a record with id T-99") });
+    await expect(ask({ point: "triage", read: { finding: "f-1" } })).rejects.toMatchObject({ code: "point-inputs-invalid", message: expect.stringContaining("finding is not read by id here") });
+  });
+});
+
+describe("the activity as an Op step runs it", () => {
+  test("loadActivities() registers decide with no lexicon configured", async () => {
+    const activities = await loadActivities([]);
+    expect(typeof activities.get("decide")).toBe("function");
+  });
+
+  test("backends come from decide.backends in the project's chant.config", async () => {
+    writeFileSync(join(root, "chant.config.json"), JSON.stringify({ decide: { backends: { systemone: { url: stub.url, key: { env: "STUB_KEY" } } } } }));
+    try {
+      script = { triage: { type: "noul", noul: 0.93 } };
+      const before = stub.requests.length;
+      const w = await waitsOn(runDecide({ cwd: root, point: "triage", inputs: { "record.size": 13, "record.risky": true } }, { env, on }));
+      expect(w.state).toBe("proposed");
+      expect(stub.requests.length).toBe(before + 1);
+    } finally {
+      rmSync(join(root, "chant.config.json"));
+    }
+  });
+
+  test("an unknown point is refused", async () => {
+    await expect(ask({ point: "nope" })).rejects.toMatchObject({ code: "point-unknown" });
+    expect(existsSync(join(root, "answers"))).toBe(true);
+  });
+});

package/src/op/activities/decide.ts

@@ -0,0 +1,267 @@
+/**
+ * The `decide` Op activity (ws-058, #2740): ask a decision point for one set
+ * of inputs, calling the backend its model decider names, and record the
+ * answer. Core's own since #2828, next to the decision points it asks; the
+ * typed step builder is `decide` in `../builders.ts`.
+ *
+ * The point is asked through core's `askPointInRun` (#2749), which writes the
+ * answer with `askPoint` (`points ask`, #2739), the same path `chant workspace
+ * points ask --response` takes. So the chain, the threshold, a model's answer
+ * being `proposed` and never `answered`, the reuse of an answer the same point,
+ * declaration and inputs already have, the escalation to people, and what an
+ * open question does to the run all come from core:
+ *
+ * - an answered question (a table row, or a person) is the step's result, and
+ *   the Op goes on;
+ * - an escalated or proposed question is open, so the step throws core's
+ *   `PointWait` and the run ends `waiting`. A person answers with `points
+ *   answer` or through hud, and the next run reads the answer from the record.
+ *
+ * This activity adds three things: reading the inputs through the read
+ * contract (`../decide-read-inputs.ts`), the call to a `POST /v1/systemone`
+ * backend (`../decide-backend.ts`), and refusing a misconfigured backend before
+ * anything is asked or written. The backends are the step's own `backends`, or
+ * `decide.backends` in chant.config (`../decide-config.ts`).
+ *
+ * With the backend unreachable, the point's `unreachable` decides: `escalate`
+ * (the default) records the question open for people with the reason, and
+ * `fail` writes nothing and fails the step.
+ *
+ * In a steward's turn the model call goes through the broker (#2749): core
+ * makes it only through a capability the steward declares, and a backend whose
+ * key is an environment variable is not called, since that key would be a
+ * credential the steward holds.
+ *
+ * chant's reads never call a model (ws-052): this runs only as an Op step.
+ *
+ * The workspace code, the client and the read-contract reads load on first
+ * call, so importing core's activities loads nothing under `workspace/`
+ * (#2525 rule 5).
+ */
+
+import { loadChantConfig } from "../../config";
+import { askPointInRun, brokeredModelAsk, isPointWait, type BrokeredModelAsk } from "../steward-points";
+import { currentStewardTurn } from "../steward-turn";
+import type { QuestionView } from "../../workspace/decide";
+import type { PointView } from "../../workspace/points-cli";
+import type { Escalation } from "../../workspace/points";
+import { backendSchema, type DecideBackend } from "../decide-config";
+import type { BackendAskOptions, BackendResponse } from "../decide-backend";
+
+export interface DecideArgs {
+  /** The point's name, as its points file declares it. */
+  point: string;
+  /** Input values by the point's input names, such as `{ "work-item.fits_small": false }`. They win over values read with `read`. */
+  inputs?: Record<string, unknown>;
+  /** What to read through the read contract, by output: `{ "work-item": "W-002" }` reads work item W-002 for every `work-item.*` input. */
+  read?: Record<string, string>;
+  /** What the question is about, such as a work item's id. Written to the answer's `constrains`. */
+  subject?: string;
+  /** The answer kind file, or a declared kind's name. Without it, the declared answer kind whose points file declares the point. */
+  kind?: string;
+  /** Where the workspace is found. Defaults to the working directory. */
+  cwd?: string;
+  /** Backends by name, in place of `decide.backends` in chant.config. */
+  backends?: Record<string, DecideBackend>;
+  /** Ask, but write nothing, and return the question whatever its state: an open one does not stop the run. */
+  dryRun?: boolean;
+}
+
+export interface DecideResult {
+  /** The answer record's id: the point's name and the first 12 hex digits of the inputs hash. */
+  id: string;
+  /** The record file, from the repository root. */
+  path: string;
+  /** `answered`, unless this was a dry run, which returns a question in any state. */
+  state: "escalated" | "proposed" | "answered";
+  open: boolean;
+  /** The answer, or null while the question is escalated. */
+  answer: string | boolean | null;
+  /** The decider that gave the recorded state: table, model (a proposal, or one a person confirmed) or quorum. */
+  decider: string;
+  /** For a model's answer: the pinned model id, the backend, its confidence and the threshold it met. */
+  model: string | null;
+  backend: string | null;
+  confidence: number | null;
+  threshold: number | null;
+  /** The people who answered, when people did. */
+  answeredBy: string[];
+  /** Each decider that was asked and did not answer, and why. */
+  escalations: Escalation[];
+  /** Declared inputs the read value did not have. */
+  missing: string[];
+}
+
+/** Seams a test swaps. */
+export interface DecideDeps {
+  /** The HTTP call, in place of the global one. */
+  transport?: BackendAskOptions["transport"];
+  env?: NodeJS.ProcessEnv;
+  /** The date written as asked_on, YYYY-MM-DD. */
+  on?: string;
+  onResponse?: (backend: string, response: BackendResponse) => void;
+}
+
+/** The step failed: what core refused, or a configuration this activity refuses. */
+export class DecideError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "DecideError";
+  }
+}
+
+/** The backends the args give, or `decide.backends` from the chant.config in `cwd`. Each is checked; a literal key is refused. */
+async function backendsFor(args: DecideArgs, cwd: string): Promise<Record<string, DecideBackend>> {
+  const { checkKey, DecideConfigError } = await import("../decide-backend");
+  let raw: unknown = args.backends;
+  if (raw === undefined) {
+    const { config } = await loadChantConfig(cwd);
+    raw = config.decide?.backends ?? {};
+  }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new DecideConfigError("backends must be an object of backend name to { url, key? }");
+  const out: Record<string, DecideBackend> = {};
+  for (const [name, b] of Object.entries(raw as Record<string, unknown>)) {
+    checkKey((b as { key?: unknown } | null)?.key, `backend ${name}'s key`, cwd);
+    const parsed = backendSchema.safeParse(b);
+    if (!parsed.success) throw new DecideConfigError(`backend ${name} is not { url, key?, timeoutMs? }: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(backend)"} ${i.message}`).join("; ")}`);
+    out[name] = parsed.data;
+  }
+  return out;
+}
+
+/** The point as `points --json` lists it, or a refusal. */
+async function pointFor(args: DecideArgs, cwd: string): Promise<PointView> {
+  const { workspacePoints } = await import("../../workspace/points-cli");
+  const doc = await workspacePoints({ cwd, ...(args.kind !== undefined ? { kind: args.kind } : {}) });
+  if ("error" in doc) throw new DecideError(doc.error.code, doc.error.message);
+  const point = doc.points.find((p) => p.name === args.point);
+  if (!point) {
+    const bad = doc.sources.find((s) => s.reason);
+    throw new DecideError("point-unknown", `no points file declares ${JSON.stringify(args.point)}${bad ? ` (${bad.kind}: ${bad.reason!.message})` : doc.points.length ? ` (the points are ${doc.points.map((p) => p.name).join(", ")})` : ""}`);
+  }
+  return point;
+}
+
+function result(q: QuestionView, missing: string[]): DecideResult {
+  const decider = typeof q.decider.kind === "string" ? q.decider.kind : "quorum";
+  const byModel = decider === "model";
+  return {
+    id: q.id,
+    path: q.path,
+    state: q.state,
+    open: q.open,
+    answer: q.answer,
+    decider,
+    model: byModel ? (q.model?.model ?? null) : null,
+    backend: byModel ? (q.model?.backend ?? null) : null,
+    confidence: byModel ? q.confidence : null,
+    threshold: byModel ? q.threshold : null,
+    answeredBy: q.answeredBy,
+    escalations: q.escalations,
+    missing,
+  };
+}
+
+/** Run the activity with its seams. {@link decide} is this with the real ones. */
+export async function runDecide(args: DecideArgs, deps: DecideDeps = {}, signal?: AbortSignal): Promise<DecideResult> {
+  if (typeof args?.point !== "string" || args.point === "") throw new DecideError("write-usage-invalid", "decide needs the point's name");
+  const cwd = args.cwd ?? process.cwd();
+  const { backendAsk, brokeredCapability, checkKey, DecideConfigError } = await import("../decide-backend");
+  const configError = <T>(f: () => T): T => {
+    try {
+      return f();
+    } catch (err) {
+      if (err instanceof DecideConfigError) throw new DecideError("backend-invalid", err.message);
+      throw err;
+    }
+  };
+  let backends: Record<string, DecideBackend>;
+  try {
+    backends = await backendsFor(args, cwd);
+  } catch (err) {
+    if (err instanceof DecideConfigError) throw new DecideError("backend-invalid", err.message);
+    throw err;
+  }
+  const point = await pointFor(args, cwd);
+
+  // Every model decider's backend is configured, and a brokered key's
+  // capability is declared with a broker, before anything is asked. The first
+  // brokered one names the capability a steward's call goes through.
+  let via: { capability: string; broker: string } | undefined;
+  for (const d of point.deciders) {
+    if (d.kind !== "model") continue;
+    const backend = backends[d.backend];
+    if (!backend) {
+      throw new DecideError("backend-invalid", `${args.point}'s model decider names the backend ${d.backend}, and none is configured (decide.backends${Object.keys(backends).length ? `: ${Object.keys(backends).join(", ")}` : " is empty"})`);
+    }
+    configError(() => checkKey(backend.key, `backend ${d.backend}'s key`, cwd));
+    if (via === undefined && backend.key && "capability" in backend.key) {
+      const key = backend.key;
+      via = { capability: key.capability, broker: configError(() => brokeredCapability(key, cwd)).broker };
+    }
+  }
+
+  let read = { inputs: {} as Record<string, unknown>, missing: [] as string[] };
+  if (args.read && Object.keys(args.read).length > 0) {
+    try {
+      const { readInputs } = await import("../decide-read-inputs");
+      read = await readInputs(point.inputs.map((i) => i.name), args.read, cwd);
+    } catch (err) {
+      throw new DecideError("point-inputs-invalid", err instanceof Error ? err.message : String(err));
+    }
+  }
+  const inputs = { ...read.inputs, ...(args.inputs ?? {}) };
+  const missing = read.missing.filter((m) => !(m in inputs));
+
+  const call = backendAsk({ backends, cwd, ...(deps.transport ? { transport: deps.transport } : {}), ...(deps.env ? { env: deps.env } : {}), ...(signal ? { signal } : {}), ...(deps.onResponse ? { onResponse: deps.onResponse } : {}) });
+  const turn = currentStewardTurn();
+  const ask: BrokeredModelAsk = async (request) => {
+    const key = backends[request.backend]?.key;
+    if (turn && key && !("capability" in key)) {
+      throw new Error(`in the steward ${turn.steward}'s turn a model call goes through the broker, and backend ${request.backend}'s key is the environment variable ${key.env}, a credential the steward would hold`);
+    }
+    return call(request);
+  };
+  const common = {
+    cwd,
+    point: args.point,
+    inputs,
+    ...(args.subject !== undefined ? { subject: args.subject } : {}),
+    ...(args.kind !== undefined ? { kind: args.kind } : {}),
+    ...(deps.on ? { on: deps.on } : {}),
+  };
+
+  if (args.dryRun) {
+    const { askPoint } = await import("../../workspace/decide");
+    const doc = await askPoint({
+      ...common,
+      ask: await brokeredModelAsk(ask, { ...(via ? via : {}), turn: turn ?? null, cwd }),
+      ...(turn ? { steward: { name: turn.steward, ...(turn.run ? { run: turn.run } : {}) } } : { client: { name: "chant decide" } }),
+      dryRun: true,
+    });
+    if ("error" in doc) throw new DecideError(doc.error.code, `${doc.error.code}: ${doc.error.message}`);
+    return result(doc.question, missing);
+  }
+
+  try {
+    const { question } = await askPointInRun({ ...common, ask, ...(via ? { capability: via.capability, broker: via.broker } : {}), turn: turn ?? null });
+    return result(question, missing);
+  } catch (err) {
+    // An open question is not a failure: the run waits on it (#2749).
+    if (isPointWait(err)) throw err;
+    const coded = err instanceof Error ? /^decision point [^:]+: ([a-z0-9-]+): /.exec(err.message) : null;
+    if (coded) throw new DecideError(coded[1], err instanceof Error ? err.message : String(err));
+    throw err;
+  }
+}
+
+/**
+ * Ask a decision point and record the answer. The Op activity: an answered
+ * question is the step's result, and an open one stops the run `waiting`.
+ */
+export async function decide(args: DecideArgs, signal?: AbortSignal): Promise<DecideResult> {
+  return runDecide(args, {}, signal);
+}

package/src/op/activities/index.ts

@@ -17,6 +17,11 @@ export { shellCmd } from "./shell";
 export type { ShellCmdArgs, ShellCmdResult } from "./shell";
 
 export { httpCheck, statusOk } from "./http-check";
+
+export { sourceArchive, releasePlan, releaseRecord } from "./source-release";
+export type { SourceArchiveArgs, SourceArchiveResult, ReleasePlanArgs, ReleasePlanResult, ReleaseRecordArgs, ReleaseRecordResult } from "./source-release";
+export { releaseRollbackPlan, releaseRollbackRecord } from "./source-rollback";
+export type { ReleaseRollbackPlanArgs, ReleaseRollbackPlanResult, ReleaseRollbackRecordArgs, ReleaseRollbackRecordResult } from "./source-rollback";
 export type { HttpCheckArgs, HttpFetch } from "./http-check";
 
 export { lifecycleSnapshot, lifecycleDiff } from "./lifecycle";
@@ -78,6 +83,9 @@ export type { PolicyGateArgs } from "./policy";
 export { guardValidate, parseGuardFindings } from "./guard-validate";
 export type { GuardValidateArgs, GuardValidateResult, GuardFinding } from "./guard-validate";
 
+export { workEvidence } from "./work-evidence";
+export type { WorkEvidenceArgs, WorkEvidenceResult } from "./work-evidence";
+
 export { workflowSupplyChainAudit, collectAuditRefs, defaultActionRefResolver } from "./workflow-audit";
 export type {
   WorkflowAuditArgs,
@@ -157,3 +165,16 @@ export type {
   ProposeUpgradeMode,
   CommandRunner,
 } from "./propose-upgrade";
+
+// The forward coverage check over an Op's own diff (#2773). Loads the
+// workspace code on first call only, like proposeWorkspaceUpgrade.
+export { changeCoverage } from "./change-coverage";
+export type { ChangeCoverageArgs, ChangeCoverageResult } from "./change-coverage";
+
+// Ask a decision point and record the answer (ws-058, #2740). Core's since
+// #2828, next to the decision points: the systemone lexicon that held it is
+// gone. Only the activity is re-exported, since the registry collects every
+// exported function; `runDecide` and its seams stay on the module, which
+// loads the workspace code on first call.
+export { decide } from "./decide";
+export type { DecideArgs, DecideResult } from "./decide";