@intentius/chant 0.91.0 → 0.93.0

package/src/op/activities/apply.ts

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

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

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

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

@@ -1,9 +1,11 @@
 import { describe, test, expect } from "vitest";
 import { eq, gt, run, report, when } from "../converge-rule";
-import type { ConvergeSymptom } from "../../lifecycle/symptoms";
+import { parseResourceObservation, type ConvergeSymptom, type ObservedResource, type ResourceSymptom } from "../../lifecycle/symptoms";
 import type { ConvergeTickRecord, ConvergeRuleOutcome } from "../../lifecycle/converge-ledger";
 import {
   planConvergeTick,
+  planResourceTick,
+  consecutiveResourceFires,
   verbClassAllowedToDispatch,
   enforceVerbClassAtDispatch,
   sanitizeOneLine,
@@ -354,3 +356,55 @@ describe("classifyDispatchFailure", () => {
     expect(classifyDispatchFailure("")).toBeUndefined();
   });
 });
+
+describe("planResourceTick — rules evaluated once per observed resource (#2778)", () => {
+  const restart = when<ResourceSymptom>(eq("status", "drifted"), run("restart-service"), { id: "restart-drifted", why: "Restart a drifted service." });
+  const unknownR = when<ResourceSymptom>(eq("status", "unknown"), report("not observed"), { id: "report-unknown", why: "unknown never remediates." });
+  const resources: ObservedResource[] = [
+    { name: "app", status: "drifted", detail: "stopped" },
+    { name: "hud", status: "in-sync" },
+    { name: "door", status: "drifted" },
+    { name: "site", status: "unknown", detail: "no health" },
+  ];
+
+  test("a fired run() is planned for each drifted resource, and names it", () => {
+    const plan = planResourceTick("box", resources, [restart, unknownR], [], "box-converge", "apply", 3);
+    expect(plan.firedRuleIds).toEqual(["restart-drifted", "report-unknown"]);
+    expect(plan.outcomes).toEqual([
+      { ruleId: "restart-drifted", resource: "app", action: "ran", op: "restart-service" },
+      { ruleId: "restart-drifted", resource: "door", action: "ran", op: "restart-service" },
+      { ruleId: "report-unknown", resource: "site", action: "reported", reason: "not observed" },
+    ]);
+  });
+
+  test("unknown never remediates, the dial and the budget hold per tick", () => {
+    const anyStatus = when<ResourceSymptom>(eq("env", "box"), run("restart-service"), { id: "restart-all", why: "x" });
+    const plan = planResourceTick("box", [{ name: "site", status: "unknown" }], [anyStatus], [], "box-converge", "apply", 3);
+    expect(plan.outcomes[0]).toMatchObject({ action: "reported", resource: "site", reason: expect.stringMatching(/unknown never remediates/) });
+    expect(planResourceTick("box", resources, [restart], [], "box-converge", "observe", 3).outcomes.map((o) => o.action)).toEqual(["reported", "reported"]);
+    expect(planResourceTick("box", resources, [restart], [], "box-converge", "apply", 1).outcomes.map((o) => o.action)).toEqual(["ran", "skipped-budget"]);
+  });
+
+  test("flap damping counts one rule's fires for one resource, on this op's ticks", () => {
+    const fired = (resource: string, op = "box-converge") =>
+      tick({ op, firedRuleIds: ["restart-drifted"], outcomes: [{ ruleId: "restart-drifted", action: "ran", op: "restart-service", resource }] });
+    const prior = [fired("app"), fired("app"), fired("hud", "other-converge"), fired("app")];
+    expect(consecutiveResourceFires(prior, "box-converge", "restart-drifted", "app")).toBe(3);
+    expect(consecutiveResourceFires(prior, "box-converge", "restart-drifted", "door")).toBe(0);
+    const plan = planResourceTick("box", resources, [restart], prior, "box-converge", "apply", 3);
+    expect(plan.outcomes.map((o) => [o.resource, o.action])).toEqual([["app", "skipped-flap"], ["door", "ran"]]);
+  });
+});
+
+describe("parseResourceObservation (#2778)", () => {
+  test("reads an observation, or a shell result that prints one, and refuses anything else", () => {
+    const observation = { resources: [{ name: "app", status: "drifted", detail: "stopped" }] };
+    expect(parseResourceObservation(observation)).toEqual(observation);
+    expect(parseResourceObservation({ stdout: JSON.stringify(observation), stderr: "", exitCode: 0 })).toEqual(observation);
+    expect(() => parseResourceObservation({ stdout: "nope", stderr: "", exitCode: 0 })).toThrow(/not JSON/);
+    expect(() => parseResourceObservation({})).toThrow(/no `resources` array/);
+    expect(() => parseResourceObservation({ resources: [{ name: "app", status: "down" }] })).toThrow(/in-sync, drifted or unknown/);
+    expect(() => parseResourceObservation({ resources: [{ status: "drifted" }] })).toThrow(/has no name/);
+    expect(() => parseResourceObservation({ resources: [{ name: "a", status: "drifted" }, { name: "a", status: "in-sync" }] })).toThrow(/twice/);
+  });
+});

package/src/op/activities/converge.ts

@@ -40,7 +40,14 @@ import {
 } from "../converge-rule";
 import { classifyOpVerbClass, type OpVerbClass } from "../op-verb-class";
 import { discoverOps } from "../discover";
-import { deriveSymptoms, type ConvergeSymptom } from "../../lifecycle/symptoms";
+import {
+  deriveSymptoms,
+  parseResourceObservation,
+  CONVERGE_RESOURCE_ENV,
+  type ConvergeSymptom,
+  type ObservedResource,
+  type ResourceSymptom,
+} from "../../lifecycle/symptoms";
 import {
   appendConvergeRecord,
   readConvergeLedger,
@@ -88,6 +95,14 @@ export interface ConvergeTickArgs {
    * (this activity re-derives its own symptom independently).
    */
   preflightDrift?: boolean;
+  /**
+   * The observer step's result, for a ConvergeOp declared with `observe`
+   * (#2778): a {@link ResourceObservation}, or a `shell()` result whose
+   * stdout is one. Present, the tick observes nothing itself: it evaluates
+   * `rules` once per reported resource, against a `ResourceSymptom`, and
+   * dispatches a fired `run()` for that resource.
+   */
+  observed?: unknown;
 }
 
 export interface ConvergeTickResult {
@@ -209,9 +224,10 @@ export function classifyDispatchFailure(raw: string): { gateName: string } | und
 async function dispatchOp(
   opName: string,
   signal?: AbortSignal,
+  env?: Record<string, string>,
 ): Promise<{ ok: true } | { ok: false; error: string; gateName?: string }> {
   try {
-    await execAsync(`chant run ${shellQuote(opName)} --json`, { signal });
+    await execAsync(`chant run ${shellQuote(opName)} --json`, { signal, ...(env ? { env: { ...process.env, ...env } } : {}) });
     return { ok: true };
   } catch (err) {
     const e = err as { code?: number; stdout?: string; stderr?: string; message?: string };
@@ -383,25 +399,106 @@ function renderLog(env: string, s: ConvergeSymptom, counts: ReturnType<typeof su
   );
 }
 
-export async function convergeTick(args: ConvergeTickArgs, signal?: AbortSignal): Promise<ConvergeTickResult> {
-  await fetchLifecycle().catch(() => undefined);
+// ── Resources an observer step reports (#2778) ──────────────────────────────
 
-  const [cs, statusRows, ledger] = await Promise.all([
-    observeChangeSet(args.env, signal),
-    observeStatusRows(args.env, signal),
-    readConvergeLedger(args.env),
-  ]);
+/**
+ * How many consecutive most-recent ticks of `op` fired `ruleId` for
+ * `resource`. A rule of a ConvergeOp with an observer step fires once per
+ * resource, so its flap damping is counted per resource: a rule that
+ * restarts `app` on one tick and `hud` on the next is not flapping.
+ */
+export function consecutiveResourceFires(records: ConvergeTickRecord[], op: string, ruleId: string, resource: string): number {
+  let count = 0;
+  for (let i = records.length - 1; i >= 0; i--) {
+    if (records[i].op !== op) continue;
+    if (!records[i].outcomes.some((o) => o.ruleId === ruleId && o.resource === resource)) break;
+    count++;
+  }
+  return count;
+}
 
-  const symptom = deriveSymptoms(args.env, cs, statusRows);
-  const plan = planConvergeTick(symptom, args.rules, ledger.records, args.dial, args.budget);
+/**
+ * The pure planning core of a resource tick (#2778): every rule against every
+ * observed resource, in authored order within each resource. The rules of
+ * {@link planConvergeTick} hold per resource: `unknown` never remediates, a
+ * `report()` never dispatches, the dial decides whether a `run()` may, and
+ * `budget` bounds the dispatches across the whole tick.
+ */
+export function planResourceTick(
+  env: string,
+  resources: ObservedResource[],
+  rules: ConvergeRule<ResourceSymptom>[],
+  priorRecords: ConvergeTickRecord[],
+  op: string,
+  dial: ConvergeTickArgs["dial"],
+  budget: number,
+): ConvergeTickPlan {
+  const fired = new Set<string>();
+  const outcomes: ConvergeRuleOutcome[] = [];
+  let dispatched = 0;
 
-  // Execute: only "ran" outcomes cause a subprocess dispatch. Before that
-  // dispatch, the runtime backstop (Finding A, #1954 pre-merge review)
-  // re-classifies the target and downgrades to "reported" if this dial/verb
-  // class pairing was never supposed to reach dispatch — OPS014 (build time)
-  // is the primary defense; this is what catches a rule table that reached
-  // `convergeTick` without going through it.
-  for (const outcome of plan.outcomes) {
+  for (const resource of resources) {
+    const symptom: ResourceSymptom = { env, resource: resource.name, status: resource.status, detail: resource.detail ?? "" };
+    for (const rule of rules) {
+      if (!evaluatePredicate(rule.when, symptom)) continue;
+      fired.add(rule.id);
+      const base = { ruleId: rule.id, resource: resource.name };
+
+      const threshold = rule.flapThreshold ?? DEFAULT_FLAP_THRESHOLD;
+      const consecutive = consecutiveResourceFires(priorRecords, op, rule.id, resource.name);
+      if (consecutive >= threshold) {
+        outcomes.push({
+          ...base,
+          action: "skipped-flap",
+          reason: `fired for ${resource.name} ${consecutive + 1} consecutive ticks without clearing (threshold ${threshold}) — escalated to report`,
+        });
+        continue;
+      }
+
+      const action: RuleAction = rule.then;
+      if (resource.status === "unknown" && action.kind === "run") {
+        outcomes.push({
+          ...base,
+          action: "reported",
+          reason: `${resource.name} is unknown (${resource.detail || "unobserved"}) — unknown never remediates`,
+        });
+        continue;
+      }
+      if (action.kind === "report") {
+        outcomes.push({ ...base, action: "reported", reason: action.reason });
+        continue;
+      }
+      if (!dialAllowsDispatch(dial)) {
+        outcomes.push({ ...base, action: "reported", reason: `dial "${dial}" does not permit dispatch — report only`, op: action.op });
+        continue;
+      }
+      if (dispatched >= budget) {
+        outcomes.push({ ...base, action: "skipped-budget", op: action.op });
+        continue;
+      }
+      dispatched++;
+      outcomes.push({ ...base, action: "ran", op: action.op });
+    }
+  }
+  return { firedRuleIds: [...fired], outcomes };
+}
+
+function renderResourceLog(env: string, resources: ObservedResource[], counts: ReturnType<typeof summarizeOutcomes>): string {
+  const n = (status: ObservedResource["status"]) => resources.filter((r) => r.status === status).length;
+  return (
+    `converge(${env}): resources=${resources.length} in-sync=${n("in-sync")} drifted=${n("drifted")} unknown=${n("unknown")} ` +
+    `remediated=${counts.remediated} reported=${counts.reported} skipped-budget=${counts.skippedBudget} ` +
+    `skipped-flap=${counts.skippedFlap} gated=${counts.gated}`
+  );
+}
+
+/** Run the planned dispatches of a tick, in place: the verb-class backstop, then `chant run`, then what came of it. */
+async function dispatchPlanned(
+  outcomes: ConvergeRuleOutcome[],
+  args: ConvergeTickArgs,
+  signal?: AbortSignal,
+): Promise<void> {
+  for (const outcome of outcomes) {
     if (outcome.action !== "ran" || !outcome.op) continue;
 
     const verbClass = await classifyDispatchTarget(outcome.op);
@@ -410,7 +507,9 @@ export async function convergeTick(args: ConvergeTickArgs, signal?: AbortSignal)
     outcome.reason = backstopped.reason;
     if (outcome.action !== "ran") continue;
 
-    const result = await dispatchOp(outcome.op, signal);
+    // A rule fired for one resource (#2778) hands the dispatched Op its name.
+    const env = outcome.resource !== undefined ? { [CONVERGE_RESOURCE_ENV]: outcome.resource } : undefined;
+    const result = await dispatchOp(outcome.op, signal, env);
     if (!result.ok && result.gateName) {
       // Gate-as-fact (#1485, closed by #2119): a terminal, durable,
       // non-blocking fact — not an ordinary dispatch failure the operator
@@ -432,6 +531,95 @@ export async function convergeTick(args: ConvergeTickArgs, signal?: AbortSignal)
       outcome.reason = `dispatch of "${outcome.op}" failed: ${result.error}`;
     }
   }
+}
+
+/** Push the tick's ledger record, and say whether it reached the remote (chant#2337). */
+async function pushTick(): Promise<{ pushed: boolean; pushWarning?: string }> {
+  try {
+    const pushed = await pushLifecycle();
+    return pushed ? { pushed } : { pushed, pushWarning: "no remote is configured for chant/lifecycle — the tick record was recorded locally only" };
+  } catch (err) {
+    return { pushed: false, pushWarning: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** A tick of a ConvergeOp with an observer step (#2778): the observation is already in `args.observed`. */
+async function resourceTick(args: ConvergeTickArgs, signal?: AbortSignal): Promise<ConvergeTickResult> {
+  const { resources } = parseResourceObservation(args.observed);
+  const ledger = await readConvergeLedger(args.env);
+  const plan = planResourceTick(
+    args.env,
+    resources,
+    args.rules as unknown as ConvergeRule<ResourceSymptom>[],
+    ledger.records,
+    args.opName,
+    args.dial,
+    args.budget,
+  );
+  await dispatchPlanned(plan.outcomes, args, signal);
+
+  const counts = summarizeOutcomes(plan.outcomes);
+  const log = renderResourceLog(args.env, resources, counts);
+  const drifted = resources.filter((r) => r.status === "drifted").length;
+  const { record } = await appendConvergeRecord({
+    op: args.opName,
+    env: args.env,
+    timestamp: new Date().toISOString(),
+    firedRuleIds: plan.firedRuleIds,
+    outcomes: plan.outcomes,
+    resources: resources.map((r) => ({
+      name: r.name,
+      status: r.status,
+      ...(r.detail ? { detail: sanitizeLedgerText(r.detail) } : {}),
+    })),
+    summary: {
+      drifted,
+      remediated: counts.remediated,
+      reported: counts.reported,
+      skippedBudget: counts.skippedBudget,
+      skippedFlap: counts.skippedFlap,
+      gated: counts.gated,
+      unobserved: resources.filter((r) => r.status === "unknown").length,
+      adopted: 0,
+    },
+    log,
+  });
+  const push = await pushTick();
+  return {
+    id: record.id,
+    drifted: drifted > 0,
+    remediated: record.summary.remediated,
+    reported: record.summary.reported,
+    skippedBudget: record.summary.skippedBudget,
+    skippedFlap: record.summary.skippedFlap,
+    gated: record.summary.gated ?? 0,
+    unobserved: record.summary.unobserved,
+    adopted: 0,
+    log: record.log,
+    ...push,
+  };
+}
+
+export async function convergeTick(args: ConvergeTickArgs, signal?: AbortSignal): Promise<ConvergeTickResult> {
+  await fetchLifecycle().catch(() => undefined);
+  if (args.observed !== undefined) return resourceTick(args, signal);
+
+  const [cs, statusRows, ledger] = await Promise.all([
+    observeChangeSet(args.env, signal),
+    observeStatusRows(args.env, signal),
+    readConvergeLedger(args.env),
+  ]);
+
+  const symptom = deriveSymptoms(args.env, cs, statusRows);
+  const plan = planConvergeTick(symptom, args.rules, ledger.records, args.dial, args.budget);
+
+  // Execute: only "ran" outcomes cause a subprocess dispatch. Before that
+  // dispatch, the runtime backstop (Finding A, #1954 pre-merge review)
+  // re-classifies the target and downgrades to "reported" if this dial/verb
+  // class pairing was never supposed to reach dispatch — OPS014 (build time)
+  // is the primary defense; this is what catches a rule table that reached
+  // `convergeTick` without going through it.
+  await dispatchPlanned(plan.outcomes, args, signal);
 
   const counts = summarizeOutcomes(plan.outcomes);
   const log = renderLog(args.env, symptom, counts);
@@ -461,16 +649,7 @@ export async function convergeTick(args: ConvergeTickArgs, signal?: AbortSignal)
   // chant#2337 — reported rather than swallowed, the way #2336 does it for the
   // gate. A push that did not land leaves a correct local record nobody else
   // can read, and the caller is the only one positioned to say so.
-  let pushed = false;
-  let pushWarning: string | undefined;
-  try {
-    pushed = await pushLifecycle();
-    if (!pushed) {
-      pushWarning = "no remote is configured for chant/lifecycle — the tick record was recorded locally only";
-    }
-  } catch (err) {
-    pushWarning = err instanceof Error ? err.message : String(err);
-  }
+  const { pushed, pushWarning } = await pushTick();
 
   return {
     id: record.id,

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

@@ -0,0 +1,78 @@
+/**
+ * The decide activity against a real Jev-compatible server (#2740). Gated:
+ * it runs only when TYPESAFE_API_KEY is set, and is skipped otherwise, so the
+ * suite never needs an account or the network.
+ *
+ *   TYPESAFE_API_KEY=... npx vitest run packages/core/src/op/activities/decide.live.test.ts
+ *
+ * TYPESAFE_BASE_URL points it at another compatible server (the default is
+ * https://api.typesafe.ai), and TYPESAFE_MODEL at another pinned model id (the
+ * default is jev-1.13.0). A model id is always a versioned one, never an alias.
+ */
+
+import { afterAll, describe, expect, test } from "vitest";
+import { isPointWait } from "../steward-points";
+import { workspacePoints } from "../../workspace/points-cli";
+import { postQuestion } from "../decide-backend";
+import { cleanScratch, workspace } from "../../workspace/__fixtures__/decide-workspace";
+import { runDecide } from "./decide";
+
+const key = process.env.TYPESAFE_API_KEY;
+const url = process.env.TYPESAFE_BASE_URL ?? "https://api.typesafe.ai";
+const model = process.env.TYPESAFE_MODEL ?? "jev-1.13.0";
+const backend = { url, key: { env: "TYPESAFE_API_KEY" }, timeoutMs: 60_000 };
+
+afterAll(cleanScratch);
+
+describe.skipIf(!key)("decide against a real Jev-compatible server (TYPESAFE_API_KEY is set)", () => {
+  test("the server answers each question type in the wire format", async () => {
+    const cwd = process.cwd();
+    const noul = await postQuestion(backend, "systemone", {
+      point: "live-noul",
+      backend: "systemone",
+      model,
+      question: { type: "noul", instructions: "Is the sky in the state blue?", criteria: { true: "It is blue.", false: "It is not blue." } },
+      state: { sky: "a clear blue sky at noon" },
+    }, { cwd });
+    expect(noul.model).toBe(model);
+    expect(noul.answer.type).toBe("noul");
+    expect((noul.answer as { noul: number }).noul).toBeGreaterThanOrEqual(0);
+
+    const choice = await postQuestion(backend, "systemone", {
+      point: "live-choice",
+      backend: "systemone",
+      model,
+      question: { type: "choice", instructions: "Which team takes the ticket in the state?", criteria: { billing: "Payments and invoices.", platform: "Servers and deploys." } },
+      state: { ticket: "The production deploy failed with a disk full error." },
+    }, { cwd });
+    expect(choice.answer).toMatchObject({ type: "choice" });
+    expect(["billing", "platform"]).toContain((choice.answer as { choice: string }).choice);
+
+    const score = await postQuestion(backend, "systemone", {
+      point: "live-score",
+      backend: "systemone",
+      model,
+      question: { type: "score", instructions: "How urgent is the ticket in the state?", criteria: ["not urgent", "somewhat urgent", "very urgent"] },
+      state: { ticket: "Every customer is locked out of their account." },
+    }, { cwd });
+    expect(score.answer).toMatchObject({ type: "score" });
+  }, 120_000);
+
+  test("the activity asks a point and records the model's answer or its escalation", async () => {
+    const root = workspace();
+    const outcome = await runDecide({ cwd: root, point: "triage", inputs: { "record.size": 5, "record.risky": true }, backends: { systemone: backend } }, {}).then(
+      (r) => r.id,
+      (e: unknown) => {
+        if (isPointWait(e)) return e.question.id;
+        throw e;
+      },
+    );
+    const doc = await workspacePoints({ cwd: root });
+    if ("error" in doc) throw new Error(doc.error.message);
+    const q = doc.questions.find((x) => x.id === outcome)!;
+    // The server answered: a proposal at the pin, or an escalation below the threshold with the model's lean. Never unreachable.
+    expect(["proposed", "escalated"]).toContain(q.state);
+    if (q.state === "proposed") expect(q.decider).toMatchObject({ kind: "model", model });
+    else expect(q.escalations.find((e) => e.kind === "model")?.reason).not.toContain("could not answer");
+  }, 120_000);
+});