@nanobpm/urban 0.7.0 → 0.9.0

package/src/runtime/core/modules/llm.test.ts

@@ -0,0 +1,237 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { LlmBinding } from "../manifest.ts";
+import {
+  buildMessages,
+  callLlm,
+  type ChatMessage,
+  type EnvLookup,
+  resolveProvider,
+  runLlmJob,
+} from "./llm.ts";
+
+const noEnv: EnvLookup = () => undefined;
+const envOf =
+  (m: Record<string, string>): EnvLookup =>
+  (k) =>
+    m[k];
+
+/** A minimal fetch double returning a fixed chat-completion. */
+function fakeFetch(
+  content: string,
+  opts: { ok?: boolean; status?: number; capture?: (url: string, init: RequestInit) => void } = {},
+): typeof fetch {
+  return (async (url: string, init: RequestInit) => {
+    opts.capture?.(String(url), init);
+    return {
+      ok: opts.ok ?? true,
+      status: opts.status ?? 200,
+      json: async () => ({ choices: [{ message: { content } }] }),
+      text: async () => content,
+    };
+  }) as unknown as typeof fetch;
+}
+
+// --- resolveProvider -------------------------------------------------------
+
+test("resolveProvider defaults to the local Ollama endpoint and env-templates the model", () => {
+  const binding: LlmBinding = { provider: "env", model: "${NANO_APP_LLM_MODEL}" };
+  const p = resolveProvider(binding, envOf({ NANO_APP_LLM_MODEL: "llama3" }));
+  assert.equal(p.baseUrl, "http://localhost:11434/v1");
+  assert.equal(p.model, "llama3");
+  assert.equal(p.apiKey, undefined);
+});
+
+test("resolveProvider honours NANO_APP_LLM_BASE_URL (trailing slash trimmed) + api key", () => {
+  const p = resolveProvider(
+    { provider: "env", model: "gpt-4o-mini" },
+    envOf({ NANO_APP_LLM_BASE_URL: "https://api.example.com/v1/", NANO_APP_LLM_API_KEY: "sk-x" }),
+  );
+  assert.equal(p.baseUrl, "https://api.example.com/v1");
+  assert.equal(p.model, "gpt-4o-mini");
+  assert.equal(p.apiKey, "sk-x");
+});
+
+test("resolveProvider falls back to NANO_APP_LLM_MODEL when the binding model is empty", () => {
+  const p = resolveProvider({ provider: "env", model: "" }, envOf({ NANO_APP_LLM_MODEL: "phi3" }));
+  assert.equal(p.model, "phi3");
+});
+
+test("resolveProvider throws when no model resolves", () => {
+  assert.throws(() => resolveProvider({ provider: "env", model: "" }, noEnv), /no model resolved/);
+});
+
+test("resolveProvider throws on an unsupported provider", () => {
+  assert.throws(
+    () => resolveProvider({ provider: "openai", model: "gpt" }, noEnv),
+    /unsupported provider "openai"/,
+  );
+});
+
+// --- buildMessages ---------------------------------------------------------
+
+test("buildMessages wraps a prompt string as a single user message", () => {
+  assert.deepEqual(buildMessages({ prompt: "hi" }), [{ role: "user", content: "hi" }]);
+});
+
+test("buildMessages prepends an optional system message", () => {
+  assert.deepEqual(buildMessages({ prompt: "hi", system: "be terse" }), [
+    { role: "system", content: "be terse" },
+    { role: "user", content: "hi" },
+  ]);
+});
+
+test("buildMessages uses a messages array verbatim", () => {
+  const messages: ChatMessage[] = [
+    { role: "user", content: "a" },
+    { role: "assistant", content: "b" },
+  ];
+  assert.deepEqual(buildMessages({ messages }), messages);
+});
+
+test("buildMessages rejects a malformed messages entry", () => {
+  assert.throws(() => buildMessages({ messages: [{ role: "user" }] }), /messages\[0\]/);
+  assert.throws(() => buildMessages({ messages: [{ role: "bogus", content: "x" }] }), /messages\[0\]/);
+});
+
+test("buildMessages requires a prompt or messages", () => {
+  assert.throws(() => buildMessages({}), /needs a 'prompt' string or a 'messages' array/);
+});
+
+test("buildMessages rejects an empty messages array", () => {
+  assert.throws(() => buildMessages({ messages: [] }), /must not be an empty array/);
+});
+
+// --- callLlm ---------------------------------------------------------------
+
+test("callLlm posts to /chat/completions and returns the message content", async () => {
+  let seen: { url: string; init: RequestInit } | undefined;
+  const f = fakeFetch("hello world", { capture: (url, init) => (seen = { url, init }) });
+  const out = await callLlm({ baseUrl: "http://h/v1", model: "m", apiKey: "k" }, [
+    { role: "user", content: "hi" },
+  ], { fetch: f });
+  assert.equal(out, "hello world");
+  assert.equal(seen?.url, "http://h/v1/chat/completions");
+  assert.equal(seen?.init.method, "POST");
+  const headers = seen?.init.headers as Record<string, string>;
+  assert.equal(headers.authorization, "Bearer k");
+  const body = JSON.parse(String(seen?.init.body));
+  assert.equal(body.model, "m");
+  assert.equal(body.response_format, undefined);
+});
+
+test("callLlm requests a JSON object response when json:true", async () => {
+  let body: Record<string, unknown> = {};
+  const f = fakeFetch("{}", { capture: (_u, init) => (body = JSON.parse(String(init.body))) });
+  await callLlm({ baseUrl: "http://h/v1", model: "m" }, [{ role: "user", content: "hi" }], {
+    json: true,
+    fetch: f,
+  });
+  assert.deepEqual(body.response_format, { type: "json_object" });
+});
+
+test("callLlm throws on a non-ok provider response", async () => {
+  const f = fakeFetch("boom", { ok: false, status: 500 });
+  await assert.rejects(
+    callLlm({ baseUrl: "http://h/v1", model: "m" }, [{ role: "user", content: "hi" }], { fetch: f }),
+    /llm provider returned 500/,
+  );
+});
+
+test("callLlm throws when the provider returns no content", async () => {
+  const f = (async () => ({ ok: true, status: 200, json: async () => ({ choices: [] }) })) as unknown as typeof fetch;
+  await assert.rejects(
+    callLlm({ baseUrl: "http://h/v1", model: "m" }, [{ role: "user", content: "hi" }], { fetch: f }),
+    /no message content/,
+  );
+});
+
+// --- runLlmJob -------------------------------------------------------------
+
+const model = envOf({ NANO_APP_LLM_MODEL: "m" });
+
+test("runLlmJob returns raw text when the binding has no output schema", async () => {
+  const out = await runLlmJob({ prompt: "hi" }, { provider: "env", model: "" }, {
+    env: model,
+    fetch: fakeFetch("plain answer"),
+  });
+  assert.deepEqual(out, { text: "plain answer" });
+});
+
+test("runLlmJob parses JSON output when the binding sets output", async () => {
+  const out = await runLlmJob(
+    { prompt: "classify" },
+    { provider: "env", model: "", output: {} },
+    { env: model, fetch: fakeFetch('{"decision":"risk","score":0.9}') },
+  );
+  assert.deepEqual(out, { decision: "risk", score: 0.9 });
+});
+
+test("runLlmJob throws when JSON output is expected but not returned", async () => {
+  await assert.rejects(
+    runLlmJob({ prompt: "x" }, { provider: "env", model: "", output: {} }, {
+      env: model,
+      fetch: fakeFetch("not json"),
+    }),
+    /expected JSON output/,
+  );
+});
+
+test("runLlmJob rejects a non-object JSON output (scalar/array/null)", async () => {
+  for (const bad of ["42", "[1,2]", "null", '"just a string"']) {
+    await assert.rejects(
+      runLlmJob({ prompt: "x" }, { provider: "env", model: "", output: {} }, {
+        env: model,
+        fetch: fakeFetch(bad),
+      }),
+      /expected a JSON object output/,
+      `should reject ${bad}`,
+    );
+  }
+});
+
+test("runLlmJob feeds parsed JSON through the decision rails and returns its output", async () => {
+  const calls: Array<{ id: string; vars: Record<string, unknown> }> = [];
+  const out = await runLlmJob(
+    { prompt: "x" },
+    { provider: "env", model: "", output: { decision: "risk" } },
+    {
+      env: model,
+      fetch: fakeFetch('{"amount":100}'),
+      evaluateDecision: async (id, vars) => {
+        calls.push({ id, vars });
+        return { approved: true };
+      },
+    },
+  );
+  assert.deepEqual(out, { approved: true });
+  assert.deepEqual(calls, [{ id: "risk", vars: { amount: 100 } }]);
+});
+
+test("runLlmJob wraps a scalar decision output as { result }", async () => {
+  const out = await runLlmJob(
+    { prompt: "x" },
+    { provider: "env", model: "", output: { decision: "risk" } },
+    { env: model, fetch: fakeFetch("{}"), evaluateDecision: async () => "APPROVE" },
+  );
+  assert.deepEqual(out, { result: "APPROVE" });
+});
+
+test("runLlmJob wraps an array decision output as { result } (not a var map)", async () => {
+  const out = await runLlmJob(
+    { prompt: "x" },
+    { provider: "env", model: "", output: { decision: "risk" } },
+    { env: model, fetch: fakeFetch("{}"), evaluateDecision: async () => [1, 2] },
+  );
+  assert.deepEqual(out, { result: [1, 2] });
+});
+
+test("runLlmJob throws when decision rails are declared but no evaluator is available", async () => {
+  await assert.rejects(
+    runLlmJob({ prompt: "x" }, { provider: "env", model: "", output: { decision: "risk" } }, {
+      env: model,
+      fetch: fakeFetch("{}"),
+    }),
+    /no decision evaluator is available/,
+  );
+});

package/src/runtime/core/modules/llm.ts

@@ -0,0 +1,209 @@
+// LLM-as-worker runtime (ADR 0022 §E role 1) — the batteries-included implementation of
+// the manifest's `llm` seam. For every `workers[]` entry that carries an `llm` binding
+// (instead of a `handler` file), `workers.ts` registers a job worker on that task type
+// whose handler is an LLM call — no external connector runtime required.
+//
+// A worker's contract:
+//   { "taskType": "classify", "llm": "classifier" }              // workers[]
+//   "llm": { "classifier": { "provider": "env",                  // llm registry
+//                            "model": "${NANO_APP_LLM_MODEL}",
+//                            "output": { "decision": "risk" } } }
+//
+// The job's input variables drive the prompt (`prompt` string and/or `messages` array,
+// optional `system`); the model's reply becomes the job's output variables. When the
+// binding declares `output.decision`, the model's JSON is fed through that DMN decision
+// (the rails) and the decision's output is returned instead — the LLM proposes, the
+// decision disposes.
+//
+// Provider is configuration, not code: `provider: "env"` resolves an OpenAI-compatible
+// endpoint from the environment, so a fully-local model (Ollama, LM Studio, llama.cpp,
+// vLLM, …) or a hosted API both work unchanged. This module is host-agnostic: env and
+// fetch are injected (env always via the host seam), never read from a concrete runtime.
+
+import type { LlmBinding } from "../manifest.ts";
+import { expandEnvString } from "../manifest.ts";
+
+/** Job variables/headers default to untyped JSON. */
+export type LlmVars = Record<string, unknown>;
+
+/** Reads an environment variable (routed through the host seam). */
+export type EnvLookup = (name: string) => string | undefined;
+
+/** One chat message on the wire. */
+export interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+/** A resolved provider endpoint (OpenAI-compatible chat completions). */
+export interface ProviderConfig {
+  baseUrl: string;
+  apiKey?: string;
+  model: string;
+}
+
+/**
+ * Evaluate a DMN decision (the output "rails"), returning its already-parsed output.
+ * Injected by the caller so this module stays free of any engine/SDK coupling.
+ */
+export type DecisionEvaluator = (
+  decisionId: string,
+  variables: Record<string, unknown>,
+) => Promise<unknown>;
+
+/** Everything running one LLM job needs, injected for host-agnosticism + testability. */
+export interface LlmRuntime {
+  env: EnvLookup;
+  /** Fetch implementation. Defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+  /** Decision-rails evaluator; required only when a binding sets `output.decision`. */
+  evaluateDecision?: DecisionEvaluator;
+}
+
+/**
+ * Resolve an OpenAI-compatible endpoint for a binding. `provider: "env"` (the only
+ * built-in today) reads:
+ *   - NANO_APP_LLM_BASE_URL  (default http://localhost:11434/v1 — Ollama's
+ *                             OpenAI-compatible endpoint; override for any host)
+ *   - NANO_APP_LLM_API_KEY   (optional; sent as `Authorization: Bearer` if set)
+ *   - NANO_APP_LLM_MODEL     (fallback when the binding's `model` resolves empty)
+ * The binding's `model` is env-templated (`${VAR}` / `${VAR:-default}`).
+ */
+export function resolveProvider(binding: LlmBinding, env: EnvLookup): ProviderConfig {
+  if (binding.provider !== "env") {
+    throw new Error(
+      `llm worker: unsupported provider "${binding.provider}" (only "env" is built in — ` +
+        `it resolves an OpenAI-compatible endpoint from NANO_APP_LLM_* env)`,
+    );
+  }
+  const baseUrl = (env("NANO_APP_LLM_BASE_URL") ?? "http://localhost:11434/v1").replace(/\/+$/, "");
+  const apiKey = env("NANO_APP_LLM_API_KEY") || undefined;
+  const model = expandEnvString(binding.model ?? "", env) || env("NANO_APP_LLM_MODEL") || "";
+  if (!model) {
+    throw new Error(
+      `llm worker: no model resolved for binding (model="${binding.model}"); ` +
+        `set NANO_APP_LLM_MODEL or a literal model`,
+    );
+  }
+  return { baseUrl, apiKey, model };
+}
+
+/**
+ * Build the chat messages for a job's variables. Input contract:
+ *   - `messages`: a ready `{role,content}[]` (used verbatim), or
+ *   - `prompt`:   a user-message string.
+ * An optional `system` string is prepended.
+ */
+export function buildMessages(vars: LlmVars): ChatMessage[] {
+  const system = typeof vars.system === "string" ? vars.system : undefined;
+
+  let msgs: ChatMessage[];
+  if (Array.isArray(vars.messages)) {
+    if (vars.messages.length === 0) {
+      throw new Error("llm worker: 'messages' must not be an empty array");
+    }
+    msgs = (vars.messages as unknown[]).map((m, i) => {
+      const o = m as { role?: unknown; content?: unknown };
+      if (
+        typeof o.content !== "string" ||
+        (o.role !== "user" && o.role !== "assistant" && o.role !== "system")
+      ) {
+        throw new Error(
+          `llm worker: messages[${i}] must be { role: user|assistant|system, content: string }`,
+        );
+      }
+      return { role: o.role, content: o.content };
+    });
+  } else if (typeof vars.prompt === "string") {
+    msgs = [{ role: "user", content: vars.prompt }];
+  } else {
+    throw new Error(
+      "llm worker: job needs a 'prompt' string or a 'messages' array in its variables",
+    );
+  }
+
+  return system ? [{ role: "system", content: system }, ...msgs] : msgs;
+}
+
+/**
+ * Call the model's chat-completions endpoint. When `json` is set, requests a JSON object
+ * response (`response_format`) so structured output can be parsed. Returns the assistant
+ * message text.
+ */
+export async function callLlm(
+  provider: ProviderConfig,
+  messages: ChatMessage[],
+  opts: { json?: boolean; fetch?: typeof fetch } = {},
+): Promise<string> {
+  const doFetch = opts.fetch ?? fetch;
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (provider.apiKey) headers.authorization = `Bearer ${provider.apiKey}`;
+  const body: Record<string, unknown> = { model: provider.model, messages };
+  if (opts.json) body.response_format = { type: "json_object" };
+
+  const res = await doFetch(`${provider.baseUrl}/chat/completions`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`llm provider returned ${res.status}: ${detail.slice(0, 500)}`);
+  }
+  const data = (await res.json()) as { choices?: Array<{ message?: { content?: string } }> };
+  const content = data.choices?.[0]?.message?.content;
+  if (typeof content !== "string") {
+    throw new Error("llm provider returned no message content");
+  }
+  return content;
+}
+
+/**
+ * Run one job through the LLM (and optional decision rails). Returns the output variables
+ * the job is completed with.
+ *
+ * - No `output` binding → returns `{ text }` (the raw completion).
+ * - `output` set → requests JSON, parses it; the parsed object is the output.
+ * - `output.decision` set → the parsed JSON is fed to that DMN decision and the decision's
+ *   output is returned (object as-is, scalar wrapped as `{ result }`).
+ */
+export async function runLlmJob(
+  vars: LlmVars,
+  binding: LlmBinding,
+  rt: LlmRuntime,
+): Promise<Record<string, unknown>> {
+  const wantJson = !!binding.output;
+  const provider = resolveProvider(binding, rt.env);
+  const messages = buildMessages(vars);
+  const text = await callLlm(provider, messages, { json: wantJson, fetch: rt.fetch });
+
+  if (!wantJson) return { text };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`llm worker: expected JSON output but got: ${text.slice(0, 300)}`);
+  }
+  // response_format asks for a JSON object, but a provider can still return a scalar, array,
+  // or null — none of which is a valid variable map (nor valid decision-rails input).
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`llm worker: expected a JSON object output but got: ${text.slice(0, 300)}`);
+  }
+  const obj = parsed as Record<string, unknown>;
+
+  const decisionId = binding.output?.decision;
+  if (decisionId) {
+    if (!rt.evaluateDecision) {
+      throw new Error(
+        `llm worker: binding declares output.decision "${decisionId}" but no decision ` +
+          `evaluator is available (the engine SDK surface is required for decision rails)`,
+      );
+    }
+    const out = await rt.evaluateDecision(decisionId, obj);
+    return out !== null && typeof out === "object" && !Array.isArray(out)
+      ? (out as Record<string, unknown>)
+      : { result: out };
+  }
+  return obj;
+}

package/src/runtime/core/modules/surfaces.ts

@@ -5,6 +5,7 @@
 
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { html, json, normalizeRoutePath, type Route } from "../router.ts";
+import { mountActions } from "./actions.ts";
 import { mountPages } from "./pages.ts";
 
 /** Escape HTML-significant characters before embedding a value in markup. */
@@ -99,6 +100,15 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
     });
   }
 
+  // App-authored action overrides mount BEFORE the generic pages routes so an exact
+  // override (e.g. /app/actions/cancel) shadows the generic action; the router is
+  // first-match-wins.
+  const actions = mountActions(ctx, app);
+  if (actions.routes.length > 0) {
+    routes.push(...actions.routes);
+    enabled.push(`actions(${actions.routes.length})`);
+  }
+
   // The pages surface (the schema-driven page runtime) mounts its own routes.
   const pages = mountPages(ctx, app);
   if (pages.routes.length > 0) {

package/src/runtime/core/modules/workers.test.ts

@@ -0,0 +1,158 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
+import type { AppManifest } from "../manifest.ts";
+import { mountWorkers, sdkDecisionEvaluator } from "./workers.ts";
+
+/** A tiny engine that records registrations and can deliver a job to a handler. */
+class MiniEngine {
+  workers = new Map<string, JobHandler>();
+  async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
+    this.workers.set(jobType, handler);
+    return { jobType, unsubscribe: async () => void this.workers.delete(jobType) };
+  }
+  deliver(jobType: string, job: EngineJob) {
+    const h = this.workers.get(jobType);
+    if (!h) throw new Error(`no worker for ${jobType}`);
+    return h(job);
+  }
+}
+
+function makeCtx(
+  manifest: Partial<AppManifest>,
+  engine: MiniEngine,
+): { ctx: RuntimeContext; logs: Array<{ level: string; msg: string }> } {
+  const logs: Array<{ level: string; msg: string }> = [];
+  const ctx = {
+    root: "/app",
+    manifest: { schemaVersion: 1, id: "t", name: "T", ...manifest } as AppManifest,
+    engine: engine as unknown as RuntimeContext["engine"],
+    host: {
+      log: (level: string, msg: string) => logs.push({ level, msg }),
+      importModule: () => Promise.reject(new Error("no modules in this test")),
+    },
+  } as unknown as RuntimeContext;
+  return { ctx, logs };
+}
+
+function makeApp(over: Partial<AppApi> = {}): AppApi {
+  return {
+    env: (n) => ({ NANO_APP_LLM_MODEL: "m" } as Record<string, string>)[n],
+    log: () => {},
+    ...over,
+  } as AppApi;
+}
+
+function fakeFetch(content: string): typeof fetch {
+  return (async () => ({
+    ok: true,
+    status: 200,
+    json: async () => ({ choices: [{ message: { content } }] }),
+    text: async () => content,
+  })) as unknown as typeof fetch;
+}
+
+const orig = globalThis.fetch;
+function withFetch(content: string, fn: () => Promise<void>): Promise<void> {
+  globalThis.fetch = fakeFetch(content);
+  return fn().finally(() => {
+    globalThis.fetch = orig;
+  });
+}
+
+test("mountWorkers registers an llm-bound worker and runs the job through the model", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx(
+    {
+      workers: [{ taskType: "classify", llm: "classifier" }],
+      llm: { classifier: { provider: "env", model: "" } },
+    },
+    engine,
+  );
+  const handle = await mountWorkers(ctx, makeApp());
+  assert.deepEqual(handle.jobTypes, ["classify"]);
+  assert.ok(logs.some((l) => l.msg === "llm worker registered"));
+
+  await withFetch("hi there", async () => {
+    const out = await engine.deliver("classify", {
+      jobKey: "j1",
+      jobType: "classify",
+      variables: { prompt: "who are you" },
+    });
+    assert.deepEqual(out, { text: "hi there" });
+  });
+  await handle.stop();
+});
+
+test("mountWorkers throws when an llm worker references an unknown binding", async () => {
+  const engine = new MiniEngine();
+  const { ctx } = makeCtx(
+    { workers: [{ taskType: "classify", llm: "missing" }], llm: {} },
+    engine,
+  );
+  await assert.rejects(mountWorkers(ctx, makeApp()), /unknown llm binding "missing"/);
+});
+
+test("mountWorkers skips (with a warning) a worker with neither handler nor llm", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx({ workers: [{ taskType: "orphan" }] }, engine);
+  const handle = await mountWorkers(ctx, makeApp());
+  assert.deepEqual(handle.jobTypes, []);
+  assert.ok(logs.some((l) => l.level === "warn" && /neither a handler nor an llm/.test(l.msg)));
+});
+
+test("an llm worker with decision rails uses app.sdk to evaluate the decision", async () => {
+  const engine = new MiniEngine();
+  const evaluated: Array<{ id: string; vars: Record<string, unknown> }> = [];
+  const sdk = {
+    evaluateDecision: async (input: { decisionDefinitionId: string; variables: Record<string, unknown> }) => {
+      evaluated.push({ id: input.decisionDefinitionId, vars: input.variables });
+      return { output: JSON.stringify({ approved: true }) };
+    },
+  };
+  const { ctx } = makeCtx(
+    {
+      workers: [{ taskType: "risk", llm: "risker" }],
+      llm: { risker: { provider: "env", model: "", output: { decision: "risk-table" } } },
+    },
+    engine,
+  );
+  await mountWorkers(ctx, makeApp({ sdk: sdk as unknown as AppApi["sdk"] }));
+
+  await withFetch('{"amount":100}', async () => {
+    const out = await engine.deliver("risk", {
+      jobKey: "j1",
+      jobType: "risk",
+      variables: { prompt: "score it" },
+    });
+    assert.deepEqual(out, { approved: true });
+  });
+  assert.deepEqual(evaluated, [{ id: "risk-table", vars: { amount: 100 } }]);
+});
+
+test("sdkDecisionEvaluator parses the decision's JSON-string output", async () => {
+  const evaluate = sdkDecisionEvaluator({
+    evaluateDecision: async () => ({ output: JSON.stringify({ ok: 1 }) }),
+  });
+  assert.deepEqual(await evaluate("d", {}), { ok: 1 });
+});
+
+test("sdkDecisionEvaluator passes through a non-string output", async () => {
+  const evaluate = sdkDecisionEvaluator({
+    evaluateDecision: async () => ({ output: { ok: 2 } }),
+  });
+  assert.deepEqual(await evaluate("d", {}), { ok: 2 });
+});
+
+test("sdkDecisionEvaluator throws with decision context on unparseable output", async () => {
+  const evaluate = sdkDecisionEvaluator({
+    evaluateDecision: async () => ({ output: "not json" }),
+  });
+  await assert.rejects(evaluate("risk", {}), /decision "risk" returned unparseable JSON/);
+});
+
+test("sdkDecisionEvaluator throws a clear error when the SDK lacks evaluateDecision", async () => {
+  const evaluate = sdkDecisionEvaluator({});
+  await assert.rejects(evaluate("risk", {}), /does not support evaluateDecision.*"risk"/);
+});