@nola-lang/providers 0.1.11 → 0.1.12

package/dist/combinators.d.ts

@@ -18,13 +18,14 @@ export declare function exponential(opts: {
 /** Definitive errors must not be retried: explicit flag, or HTTP 4xx except 408/429. */
 export declare function isDefinitiveProviderError(error: unknown): boolean;
 /**
- * Wire-level retry: re-attempts the single `provider.complete` call with
- * backoff, fail-fasting on definitive errors. Honors the provider's
- * `retryAfterMs` (Retry-After) when it exceeds the scheduled delay, capped at
+ * Wire-level retry: re-attempts the single provider call with backoff,
+ * fail-fasting on definitive errors. Honors the provider's `retryAfterMs`
+ * (Retry-After) when it exceeds the scheduled delay, capped at
  * `policy.maxDelayMs` — so a policy whose maxDelayMs is 0 (e.g. `constant()`
  * with no delay) ignores the header entirely. Distinct from the intent method
  * `.withRetry(n)`, which flat-retries the entire ask (composition, provider
  * call, parse, validation) with no backoff and no definitive-error check.
+ * Mirrors the inner's dialect and decision brand.
  */
 export declare function withRetry(provider: LanguageModel, policy: RetryPolicy): LanguageModel;
 export declare function fallback(providers: LanguageModel[]): LanguageModel;

package/dist/combinators.js

@@ -1,5 +1,6 @@
 import { Codes } from "@nola-lang/ast";
-import { isPlatformModel, NolaConfigError, NolaProviderError } from "@nola-lang/core";
+import { DECISION_MODEL, isDecisionModel, isInferModel, isPlatformModel, NolaConfigError, NolaProviderError } from "@nola-lang/core";
+import { callModel, isDecisionRequest } from "./dialect.js";
 export function constant(opts) {
     const delayMs = opts.delayMs ?? 0;
     return { maxRetries: opts.maxRetries, delayMs, multiplier: 1, maxDelayMs: delayMs };
@@ -45,79 +46,85 @@ function describeError(error) {
     return error instanceof Error ? error.message : String(error);
 }
 /**
- * Wire-level retry: re-attempts the single `provider.complete` call with
- * backoff, fail-fasting on definitive errors. Honors the provider's
- * `retryAfterMs` (Retry-After) when it exceeds the scheduled delay, capped at
+ * Build the outer model of a combinator (decision types spec 2026-09-18
+ * §6.1–6.2): infer-dialect iff any inner is (chat inners get the rendering
+ * through callModel), branded a decision model iff any inner is. `run`
+ * receives the request in the outer dialect.
+ */
+function outer(name, inners, run) {
+    const brand = inners.some((m) => isDecisionModel(m)) ? { [DECISION_MODEL]: true } : {};
+    const model = inners.some((m) => isInferModel(m))
+        ? { name, ...brand, infer: (req) => run(req) }
+        : { name, ...brand, complete: (req) => run(req) };
+    return model;
+}
+/**
+ * Wire-level retry: re-attempts the single provider call with backoff,
+ * fail-fasting on definitive errors. Honors the provider's `retryAfterMs`
+ * (Retry-After) when it exceeds the scheduled delay, capped at
  * `policy.maxDelayMs` — so a policy whose maxDelayMs is 0 (e.g. `constant()`
  * with no delay) ignores the header entirely. Distinct from the intent method
  * `.withRetry(n)`, which flat-retries the entire ask (composition, provider
  * call, parse, validation) with no backoff and no definitive-error check.
+ * Mirrors the inner's dialect and decision brand.
  */
 export function withRetry(provider, policy) {
     rejectPlatformModel([provider], "withRetry");
-    return {
-        name: `retry(${provider.name})`,
-        async complete(req) {
-            let delay = policy.delayMs;
-            let lastError;
-            for (let attempt = 0; attempt <= policy.maxRetries; attempt++) {
-                try {
-                    return await provider.complete(req);
-                }
-                catch (error) {
-                    lastError = error;
-                    if (isDefinitiveProviderError(error) || attempt === policy.maxRetries)
-                        throw error;
-                    const retryAfterMs = error instanceof NolaProviderError ? (error.retryAfterMs ?? 0) : 0;
-                    await sleep(Math.min(Math.max(delay, retryAfterMs), policy.maxDelayMs));
-                    delay = Math.min(delay * policy.multiplier, policy.maxDelayMs);
-                }
+    const inner = provider;
+    return outer(`retry(${provider.name})`, [inner], async (req) => {
+        let delay = policy.delayMs;
+        let lastError;
+        for (let attempt = 0; attempt <= policy.maxRetries; attempt++) {
+            try {
+                return await callModel(inner, req);
             }
-            throw lastError; // unreachable; satisfies control-flow analysis
-        },
-    };
+            catch (error) {
+                lastError = error;
+                if (isDefinitiveProviderError(error) || attempt === policy.maxRetries)
+                    throw error;
+                const retryAfterMs = error instanceof NolaProviderError ? (error.retryAfterMs ?? 0) : 0;
+                await sleep(Math.min(Math.max(delay, retryAfterMs), policy.maxDelayMs));
+                delay = Math.min(delay * policy.multiplier, policy.maxDelayMs);
+            }
+        }
+        throw lastError; // unreachable; satisfies control-flow analysis
+    });
+}
+/** Try each inner in order; on a decision request, unbranded inners are skipped (they would fabricate). */
+async function tryInOrder(name, ordered, req) {
+    const decision = isDecisionRequest(req);
+    const failures = [];
+    for (const p of ordered) {
+        if (decision && !isDecisionModel(p)) {
+            failures.push(`${p.name}: not a decision model`);
+            continue;
+        }
+        try {
+            return await callModel(p, req);
+        }
+        catch (error) {
+            failures.push(`${p.name}: ${describeError(error)}`);
+        }
+    }
+    throw new NolaProviderError(`${name}: all providers failed —\n  ${failures.join("\n  ")}`);
 }
 export function fallback(providers) {
     requireModels(providers, "fallback");
     rejectPlatformModel(providers, "fallback");
+    const inners = providers;
     const name = `fallback(${providers.map((p) => p.name).join(", ")})`;
-    return {
-        name,
-        async complete(req) {
-            const failures = [];
-            for (const p of providers) {
-                try {
-                    return await p.complete(req);
-                }
-                catch (error) {
-                    failures.push(`${p.name}: ${describeError(error)}`);
-                }
-            }
-            throw new NolaProviderError(`${name}: all providers failed —\n  ${failures.join("\n  ")}`);
-        },
-    };
+    return outer(name, inners, (req) => tryInOrder(name, inners, req));
 }
 export function roundRobin(providers) {
     requireModels(providers, "roundRobin");
     rejectPlatformModel(providers, "roundRobin");
+    const inners = providers;
     const name = `roundRobin(${providers.map((p) => p.name).join(", ")})`;
     let nextStart = 0;
-    return {
-        name,
-        async complete(req) {
-            const start = nextStart++ % providers.length;
-            const failures = [];
-            for (let i = 0; i < providers.length; i++) {
-                const p = providers[(start + i) % providers.length];
-                try {
-                    return await p.complete(req);
-                }
-                catch (error) {
-                    failures.push(`${p.name}: ${describeError(error)}`);
-                }
-            }
-            throw new NolaProviderError(`${name}: all providers failed —\n  ${failures.join("\n  ")}`);
-        },
-    };
+    return outer(name, inners, (req) => {
+        const start = nextStart++ % inners.length;
+        const ordered = inners.map((_, i) => inners[(start + i) % inners.length]);
+        return tryInOrder(name, ordered, req);
+    });
 }
 //# sourceMappingURL=combinators.js.map

package/dist/decisions.d.ts

@@ -0,0 +1,60 @@
+import type { InferenceModel } from "@nola-lang/core";
+/**
+ * The decisions wire dialect (spec 2026-09-18 §6.2–6.3): typesafe.ai's
+ * System One and OpenRouter's Decisions API take one JSON `state` and a map
+ * of named typed questions — choice / score / noul — and answer every one
+ * with a probability distribution. This module turns an InferenceModel into
+ * that request and its answers back into the values the ask's carrier
+ * validates. Pure: no fetch, no vendor URL, so every wire over the dialect
+ * shares it.
+ */
+/** `instructions` may be a string or a JSON object on the wire (UNVERIFIED against the live API: the object form). */
+export type Instructions = string | {
+    context: string;
+    question: string;
+};
+export type DecisionWireQuestion = {
+    type: "choice";
+    instructions: Instructions;
+    criteria: Record<string, string | null>;
+} | {
+    type: "score";
+    instructions: Instructions;
+    criteria: string[];
+} | {
+    type: "noul";
+    instructions: Instructions;
+    criteria?: {
+        true: string;
+        false: string;
+    };
+};
+export type DecodeResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Turns the wire answer for one question into the JSON value the ask expects. */
+export type Decoder = (answer: unknown) => DecodeResult;
+export interface DecisionPlan {
+    /** JSON: the contextual values by name (innermost wins), or the ask's instruction text when there are none */
+    state: unknown;
+    questions: Record<string, DecisionWireQuestion>;
+    decode: Record<string, Decoder>;
+    /** true ⇔ the reply is the bare "value" answer, not an object of answers */
+    scalar: boolean;
+}
+export type PlanResult = {
+    ok: true;
+    plan: DecisionPlan;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The request for an ask, or why the dialect cannot serve it. */
+export declare function planFor(model: InferenceModel, options: {
+    threshold: number;
+}): PlanResult;
+//# sourceMappingURL=decisions.d.ts.map

package/dist/decisions.js

@@ -0,0 +1,231 @@
+import { joinBlocks } from "@nola-lang/core";
+const SERVES = "typesafe() serves Choice, Scale and Prob, literal unions and booleans";
+const SCALAR_QUESTION = "Determine the value the request asks for.";
+function fail(reason) {
+    return { ok: false, reason };
+}
+// ---- state and context ----
+/** Scopes outer→inner (the model lists them innermost first through `parent`). */
+function scopesOuterFirst(scope) {
+    const out = [];
+    for (let s = scope; s; s = s.parent)
+        out.unshift(s);
+    return out;
+}
+/** The contextual values by name, outer→inner so an inner binding shadows an outer one; undefined when there are none. */
+function contextualState(model) {
+    const state = {};
+    let any = false;
+    for (const scope of scopesOuterFirst(model.scope)) {
+        for (const arg of scope.args) {
+            if (arg.contextual && "value" in arg) {
+                state[arg.name] = arg.value;
+                any = true;
+            }
+        }
+    }
+    return any ? state : undefined;
+}
+const askText = (model) => model.input.text ?? model.input.instruction;
+/** What the model says about the ask, outer→inner: system, each scope's text, then (optionally) the ask text. */
+function contextText(model, includeAskText) {
+    const parts = [
+        model.system ?? "",
+        ...scopesOuterFirst(model.scope).map((s) => s.text ?? s.instruction),
+        includeAskText ? askText(model) : "",
+    ];
+    return parts.filter((p) => p.trim() !== "").reduce((acc, p) => joinBlocks(acc, p), "");
+}
+/** Follow a `$ref` chain through the root `$defs`; the FIRST description seen along the chain wins. */
+function resolve(node, defs, path) {
+    let current = node;
+    let description = node.description;
+    const seen = new Set();
+    while ("$ref" in current) {
+        const ref = current.$ref;
+        if (seen.has(ref))
+            return fail(`${path} is a cyclic reference ${JSON.stringify(ref)}; ${SERVES}`);
+        seen.add(ref);
+        const name = /^#\/\$defs\/(.+)$/.exec(ref)?.[1];
+        const next = name ? defs?.[name] : undefined;
+        if (!next)
+            return fail(`${path} is an unresolved reference ${JSON.stringify(ref)}; ${SERVES}`);
+        current = next;
+        description ??= current.description;
+    }
+    return description === undefined ? { ok: true, node: current } : { ok: true, node: current, description };
+}
+/** What an unsupported node is, in the words of the failure reason. */
+function kindOf(node) {
+    if ("const" in node)
+        return "a single literal";
+    if ("anyOf" in node)
+        return "a union that is not all string literals or all number literals";
+    if ("type" in node) {
+        switch (node.type) {
+            case "string":
+                return node.format === "date-time" ? "a date-time string" : "a free-form string";
+            case "number":
+            case "integer":
+                return "a number";
+            case "array":
+                return "an array";
+            case "object":
+                return "properties" in node ? "a nested object" : "a record";
+            case "null":
+                return "null";
+        }
+    }
+    return "an unsupported shape";
+}
+const missing = (key) => fail(`answer "${key}" is missing from the reply`);
+function finiteOrUndefined(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+/** A plain literal union: labels are the literals; the decoder returns the JSON value the label stands for. */
+function plainChoice(key, instructions, labels) {
+    const criteria = {};
+    for (const label of labels.keys())
+        criteria[label] = null;
+    const decode = (answer) => {
+        if (answer === undefined || answer === null)
+            return missing(key);
+        const choice = answer.choice;
+        if (typeof choice !== "string" || !labels.has(choice)) {
+            return fail(`answer "${key}" chose ${JSON.stringify(choice)}, which is not one of the options sent`);
+        }
+        return { ok: true, value: labels.get(choice) };
+    };
+    return { ok: true, question: { type: "choice", instructions, criteria }, decode };
+}
+function plainNoul(key, instructions, threshold) {
+    const decode = (answer) => {
+        if (answer === undefined || answer === null)
+            return missing(key);
+        const noul = finiteOrUndefined(answer.noul);
+        if (noul === undefined)
+            return fail(`answer "${key}" has no numeric noul`);
+        return { ok: true, value: noul > threshold };
+    };
+    return { ok: true, question: { type: "noul", instructions }, decode };
+}
+/** A decision node: the question is the node's own; the decoder builds the answer shape the carrier validates. */
+function decisionQuestion(key, instructions, q) {
+    switch (q.kind) {
+        case "choice": {
+            const labels = Object.keys(q.criteria);
+            const decode = (answer) => {
+                if (answer === undefined || answer === null)
+                    return missing(key);
+                const a = answer;
+                if (typeof a.choice !== "string" || !labels.includes(a.choice)) {
+                    return fail(`answer "${key}" chose ${JSON.stringify(a.choice)}, which is not one of the options sent`);
+                }
+                if (a.probabilities === null || typeof a.probabilities !== "object") {
+                    return fail(`answer "${key}" has no probabilities object`);
+                }
+                const confidence = finiteOrUndefined(a.confidence);
+                // the wire's label is its text; a label written as a number comes back as that number
+                const choice = q.numeric?.includes(a.choice) ? Number(a.choice) : a.choice;
+                return {
+                    ok: true,
+                    value: { choice, probabilities: a.probabilities, ...(confidence !== undefined ? { confidence } : {}) },
+                };
+            };
+            return { ok: true, question: { type: "choice", instructions, criteria: { ...q.criteria } }, decode };
+        }
+        case "scale": {
+            const levels = [...q.levels];
+            const decode = (answer) => {
+                if (answer === undefined || answer === null)
+                    return missing(key);
+                const a = answer;
+                const score = finiteOrUndefined(a.score);
+                if (score === undefined)
+                    return fail(`answer "${key}" has no numeric score`);
+                const byIndex = (a.probabilities ?? {});
+                const probabilities = levels.map((_, i) => finiteOrUndefined(byIndex[String(i)]) ?? 0);
+                const confidence = finiteOrUndefined(a.confidence);
+                return { ok: true, value: { score, probabilities, levels, ...(confidence !== undefined ? { confidence } : {}) } };
+            };
+            return { ok: true, question: { type: "score", instructions, criteria: levels }, decode };
+        }
+        case "prob": {
+            const decode = (answer) => {
+                if (answer === undefined || answer === null)
+                    return missing(key);
+                const noul = finiteOrUndefined(answer.noul);
+                if (noul === undefined)
+                    return fail(`answer "${key}" has no numeric noul`);
+                return { ok: true, value: noul };
+            };
+            return {
+                ok: true,
+                question: q.criteria ? { type: "noul", instructions, criteria: q.criteria } : { type: "noul", instructions },
+                decode,
+            };
+        }
+    }
+}
+/** Map one schema node to a question. `path` names the node in failure reasons; `key` is the answer key. */
+function questionFor(raw, defs, path, key, context, threshold) {
+    const resolved = resolve(raw, defs, path);
+    if (!resolved.ok)
+        return resolved;
+    const { node, description } = resolved;
+    const question = description ?? (key === "value" ? SCALAR_QUESTION : `Determine "${key}".`);
+    const instructions = context === "" ? question : { context, question };
+    const decision = node["x-nola-decision"];
+    if (decision)
+        return decisionQuestion(key, instructions, decision);
+    if ("type" in node && node.type === "boolean")
+        return plainNoul(key, instructions, threshold);
+    if ("type" in node && node.type === "string" && node.enum) {
+        return plainChoice(key, instructions, new Map(node.enum.map((label) => [label, label])));
+    }
+    if ("anyOf" in node && node.anyOf.length >= 2) {
+        const consts = node.anyOf.map((branch) => ("const" in branch ? branch.const : undefined));
+        if (consts.every((c) => typeof c === "string")) {
+            return plainChoice(key, instructions, new Map(consts.map((c) => [c, c])));
+        }
+        if (consts.every((c) => typeof c === "number")) {
+            return plainChoice(key, instructions, new Map(consts.map((c) => [String(c), c])));
+        }
+    }
+    return fail(`${path} is ${kindOf(node)}; ${SERVES}`);
+}
+/** The request for an ask, or why the dialect cannot serve it. */
+export function planFor(model, options) {
+    const schema = model.output.syntax === "json" ? model.output.schema : undefined;
+    if (!schema)
+        return fail(`the ask has no output schema (free text); ${SERVES}`);
+    const values = contextualState(model);
+    const state = values ?? askText(model);
+    const context = contextText(model, values !== undefined);
+    const defs = "$defs" in schema ? schema.$defs : undefined;
+    const root = resolve(schema, defs, "the output type");
+    if (!root.ok)
+        return root;
+    const node = root.node;
+    const decisionRoot = node["x-nola-decision"];
+    if (!decisionRoot && "type" in node && node.type === "object" && "properties" in node) {
+        const questions = {};
+        const decode = {};
+        for (const [name, prop] of Object.entries(node.properties)) {
+            const mapped = questionFor(prop, defs, `output property ${JSON.stringify(name)}`, name, context, options.threshold);
+            if (!mapped.ok)
+                return mapped;
+            questions[name] = mapped.question;
+            decode[name] = mapped.decode;
+        }
+        return { ok: true, plan: { state, questions, decode, scalar: false } };
+    }
+    const mapped = questionFor(schema, defs, "the output type", "value", context, options.threshold);
+    if (!mapped.ok)
+        return mapped;
+    return {
+        ok: true,
+        plan: { state, questions: { value: mapped.question }, decode: { value: mapped.decode }, scalar: true },
+    };
+}
+//# sourceMappingURL=decisions.js.map

package/dist/dialect.d.ts

@@ -0,0 +1,12 @@
+import type { ChatModel, InferModel, InferRequest, ProviderRequest, ProviderResponse } from "@nola-lang/core";
+/**
+ * The dialect bridge (decision types spec 2026-09-18 §6.2): a combinator is
+ * infer-dialect iff any inner is, and renders for its chat inners. `callModel`
+ * is the one place that decides which method an inner gets.
+ */
+export declare function callModel(model: ChatModel | InferModel, req: InferRequest | ProviderRequest): Promise<ProviderResponse>;
+/** An infer request rendered for a chat inner: the rendering replaces the model; everything else rides along. */
+export declare function toClassic(req: InferRequest): ProviderRequest;
+/** True when the request's output schema carries a decision question (either request shape). */
+export declare function isDecisionRequest(req: InferRequest | ProviderRequest): boolean;
+//# sourceMappingURL=dialect.d.ts.map

package/dist/dialect.js

@@ -0,0 +1,25 @@
+import { findDecisionQuestions, isInferModel, NolaProviderError, renderClassic } from "@nola-lang/core";
+/**
+ * The dialect bridge (decision types spec 2026-09-18 §6.2): a combinator is
+ * infer-dialect iff any inner is, and renders for its chat inners. `callModel`
+ * is the one place that decides which method an inner gets.
+ */
+export async function callModel(model, req) {
+    if (isInferModel(model)) {
+        if ("model" in req)
+            return model.infer(req);
+        throw new NolaProviderError(`infer-dialect model "${model.name}" received a classic request — a combinator over it must expose infer()`, { definitive: true });
+    }
+    return model.complete("model" in req ? toClassic(req) : req);
+}
+/** An infer request rendered for a chat inner: the rendering replaces the model; everything else rides along. */
+export function toClassic(req) {
+    const { model, project: _project, ...rest } = req;
+    return { payload: renderClassic(model), ...rest };
+}
+/** True when the request's output schema carries a decision question (either request shape). */
+export function isDecisionRequest(req) {
+    const output = "model" in req ? req.model.output : req.payload.output;
+    return output.syntax === "json" && findDecisionQuestions(output.schema).length > 0;
+}
+//# sourceMappingURL=dialect.js.map

package/dist/index.d.ts

@@ -5,8 +5,9 @@ import { openai } from "./openai.js";
 import { typesafe } from "./typesafe.js";
 export { type AnthropicOptions, anthropic } from "./anthropic.js";
 export { constant, exponential, fallback, isDefinitiveProviderError, type RetryPolicy, roundRobin, withRetry, } from "./combinators.js";
+export { callModel, isDecisionRequest, toClassic } from "./dialect.js";
 export { type GoogleOptions, google } from "./google.js";
-export { type MockRequest, mockProvider } from "./mock.js";
+export { type MockOptions, type MockRequest, mockProvider } from "./mock.js";
 export { type OpenAiOptions, openai } from "./openai.js";
 export { record, replay } from "./record-replay.js";
 export { type TypesafeOptions, typesafe } from "./typesafe.js";
@@ -22,4 +23,5 @@ export declare const providers: {
     readonly typesafe: typeof typesafe;
     readonly mock: typeof mockProvider;
 };
+export { type DecisionPlan, type DecisionWireQuestion, type DecodeResult, type Decoder, type Instructions, type PlanResult, planFor, } from "./decisions.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -5,6 +5,7 @@ import { openai } from "./openai.js";
 import { typesafe } from "./typesafe.js";
 export { anthropic } from "./anthropic.js";
 export { constant, exponential, fallback, isDefinitiveProviderError, roundRobin, withRetry, } from "./combinators.js";
+export { callModel, isDecisionRequest, toClassic } from "./dialect.js";
 export { google } from "./google.js";
 export { mockProvider } from "./mock.js";
 export { openai } from "./openai.js";
@@ -22,4 +23,5 @@ export const providers = {
     typesafe,
     mock: mockProvider,
 };
+export { planFor, } from "./decisions.js";
 //# sourceMappingURL=index.js.map

package/dist/mock.d.ts

@@ -1,5 +1,14 @@
 import type { LanguageModel, ProviderRequest } from "@nola-lang/core";
 /** What a mock callback sees: the classic request — `payload` IS the rendering (reshape 2026-09-01). */
 export type MockRequest = ProviderRequest;
-export declare function mockProvider(source: unknown[] | ((req: MockRequest) => unknown)): LanguageModel;
+export interface MockOptions {
+    /**
+     * Brand the mock a decision model (decision types spec 2026-09-18 §6.1): a
+     * test routing a Choice / Scale / Prob ask through a mock says so
+     * explicitly — without it the runtime refuses, as it would for any
+     * unbranded model.
+     */
+    decisions?: boolean;
+}
+export declare function mockProvider(source: unknown[] | ((req: MockRequest) => unknown), options?: MockOptions): LanguageModel;
 //# sourceMappingURL=mock.d.ts.map

package/dist/mock.js

@@ -1,6 +1,8 @@
-export function mockProvider(source) {
+import { DECISION_MODEL } from "@nola-lang/core";
+export function mockProvider(source, options = {}) {
     const queue = Array.isArray(source) ? [...source] : null;
     return {
+        ...(options.decisions ? { [DECISION_MODEL]: true } : {}),
         name: "mock",
         async complete(req) {
             let value;

package/dist/record-replay.js

@@ -1,10 +1,15 @@
 import { appendFileSync, readFileSync } from "node:fs";
 import { Codes } from "@nola-lang/ast";
-import { fingerprintRequest, isPlatformModel, NolaConfigError, NolaProviderError, PLATFORM_MODEL, redactDeep, redactSecrets, } from "@nola-lang/core";
+import { DECISION_MODEL, fingerprintRequest, isDecisionModel, isInferModel, isPlatformModel, NolaConfigError, NolaProviderError, PLATFORM_MODEL, redactDeep, redactSecrets, } from "@nola-lang/core";
 export function record(inner, ledgerPath) {
-    if (isPlatformModel(inner)) {
+    // the brands ride along: the platform's (its own rules) and the decision capability
+    const brands = {
+        ...(isPlatformModel(inner) ? { [PLATFORM_MODEL]: true } : {}),
+        ...(isDecisionModel(inner) ? { [DECISION_MODEL]: true } : {}),
+    };
+    if (isInferModel(inner)) {
         return {
-            [PLATFORM_MODEL]: true,
+            ...brands,
             name: `record(${inner.name})`,
             async infer(req) {
                 const res = await inner.infer(req);
@@ -22,10 +27,12 @@ export function record(inner, ledgerPath) {
             },
         };
     }
+    const chat = inner;
     return {
+        ...brands,
         name: `record(${inner.name})`,
         async complete(req) {
-            const res = await inner.complete(req);
+            const res = await chat.complete(req);
             const entry = {
                 fingerprint: fingerprintRequest(req),
                 request: { payload: redactDeep(req.payload), ...(req.params ? { params: req.params } : {}) },
@@ -83,6 +90,8 @@ export function replay(ledgerPath) {
             entries.set(e.fingerprint, [hit]);
     });
     return {
+        // a ledger serves whatever it holds — a replayed decision ask needs no live capability
+        ...{ [DECISION_MODEL]: true },
         name: "replay",
         async complete(req) {
             const fingerprint = fingerprintRequest(req);

package/dist/typesafe.d.ts

@@ -8,14 +8,28 @@ export interface TypesafeOptions {
     /** Default: "https://api.typesafe.ai" */
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
+    /**
+     * A plain `boolean` is `true` when the probability of yes is STRICTLY above
+     * this (default 0.5, so a coin flip is `false`). `params.providerOptions.threshold`
+     * on an ask overrides it (the `.withParams` channel — no new syntax).
+     */
+    threshold?: number;
 }
 /**
  * typesafe.ai's System One API (model Jev): not a chat model. One request
- * answers named choice / noul questions about a `state`, so this factory
- * serves exactly the asks whose output type is literal unions and
- * booleans (see `questionsFor`) and fails definitively — before the
- * network — on anything else, which is what lets `fallback([typesafe(),
- * openai("…")])` escalate. A bare string is shorthand for `{ model }`.
+ * answers named choice / score / noul questions about a JSON `state`, so this
+ * factory is an INFER-dialect decision model (spec 2026-09-18 §6.2): it
+ * receives the InferenceModel, sends the contextual values as the state and
+ * each property's JSDoc as its question (through the shared `planFor`), serves
+ * `Choice` / `Scale` / `Prob` natively beside literal unions and booleans, and
+ * fails definitively — before the network — on anything else, which is what
+ * lets `fallback([typesafe(), openai("…")])` escalate. A bare string is
+ * shorthand for `{ model }`.
+ *
+ * UNVERIFIED against the live API (no key at implementation time): option
+ * labels with spaces/punctuation as `criteria` keys, and the structured
+ * `instructions` object. If the API rejects either, the change is confined to
+ * `decisions.ts` (`opt_<n>` keys with a decoder map; a joined string).
  */
 export declare function typesafe(optionsOrModel?: TypesafeOptions | string): LanguageModel;
 //# sourceMappingURL=typesafe.d.ts.map

package/dist/typesafe.js

@@ -1,14 +1,23 @@
-import { joinBlocks, NolaProviderError, parseRetryAfter } from "@nola-lang/core";
-import { questionsFor } from "./typesafe-questions.js";
+import { DECISION_MODEL, NolaProviderError, parseRetryAfter } from "@nola-lang/core";
+import { planFor } from "./decisions.js";
 const DEFAULT_MODEL = "jev-latest";
 const DEFAULT_BASE_URL = "https://api.typesafe.ai";
+const DEFAULT_THRESHOLD = 0.5;
 /**
  * typesafe.ai's System One API (model Jev): not a chat model. One request
- * answers named choice / noul questions about a `state`, so this factory
- * serves exactly the asks whose output type is literal unions and
- * booleans (see `questionsFor`) and fails definitively — before the
- * network — on anything else, which is what lets `fallback([typesafe(),
- * openai("…")])` escalate. A bare string is shorthand for `{ model }`.
+ * answers named choice / score / noul questions about a JSON `state`, so this
+ * factory is an INFER-dialect decision model (spec 2026-09-18 §6.2): it
+ * receives the InferenceModel, sends the contextual values as the state and
+ * each property's JSDoc as its question (through the shared `planFor`), serves
+ * `Choice` / `Scale` / `Prob` natively beside literal unions and booleans, and
+ * fails definitively — before the network — on anything else, which is what
+ * lets `fallback([typesafe(), openai("…")])` escalate. A bare string is
+ * shorthand for `{ model }`.
+ *
+ * UNVERIFIED against the live API (no key at implementation time): option
+ * labels with spaces/punctuation as `criteria` keys, and the structured
+ * `instructions` object. If the API rejects either, the change is confined to
+ * `decisions.ts` (`opt_<n>` keys with a decoder map; a joined string).
  */
 export function typesafe(optionsOrModel) {
     const options = typeof optionsOrModel === "string" ? { model: optionsOrModel } : (optionsOrModel ?? {});
@@ -16,29 +25,28 @@ export function typesafe(optionsOrModel) {
     const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     const model = options.model ?? DEFAULT_MODEL;
     return {
+        ...{ [DECISION_MODEL]: true },
         name: "typesafe",
-        async complete(req) {
+        async infer(req) {
             const requestedAt = Date.now();
             const envName = options.apiKeyEnv ?? "TYPESAFE_API_KEY";
             const apiKey = options.apiKey ?? process.env[envName];
             if (!apiKey) {
                 throw new NolaProviderError(`TypeSafe API key not found: environment variable ${envName} is not set (checked process.env, including the project .env applied by the Nola loader) and no \`apiKey\` was passed to typesafe(). Fix: set ${envName}, or pass typesafe({ apiKeyEnv: "MY_VAR" }) or typesafe({ apiKey }) in nola.config.ts.`, { definitive: true });
             }
-            const { system, messages, output } = req.payload;
-            const mapped = questionsFor(output.syntax === "json" ? output.schema : undefined);
+            const askThreshold = req.params?.providerOptions?.threshold;
+            const threshold = typeof askThreshold === "number" ? askThreshold : (options.threshold ?? DEFAULT_THRESHOLD);
+            // Jev has no conversation: a correction turn (req.model.correction) has
+            // nothing to say to it, so the ask is re-answered from the same state.
+            const mapped = planFor(req.model, { threshold });
             if (!mapped.ok) {
                 throw new NolaProviderError(`TypeSafe cannot serve this ask: ${mapped.reason}`, { definitive: true });
             }
             const { plan } = mapped;
-            // Jev has no conversation: the state is the rendering's system text and
-            // its first user turn. A correction turn cannot occur in practice (the
-            // synthesized reply is schema-valid by construction), so any further
-            // messages are ignored and the ask is re-answered from the first turn.
-            const state = joinBlocks(system, messages[0]?.content ?? "");
             const res = await doFetch(`${baseUrl}/v1/systemone`, {
                 method: "POST",
                 headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
-                body: JSON.stringify({ model, state, questions: plan.questions }),
+                body: JSON.stringify({ model, state: plan.state, questions: plan.questions }),
                 signal: req.signal ?? null,
             });
             if (!res.ok) {
@@ -59,8 +67,9 @@ export function typesafe(optionsOrModel) {
             const value = {};
             for (const [key, decode] of Object.entries(plan.decode)) {
                 const decoded = decode(answers[key]);
-                if (!decoded.ok)
+                if (!decoded.ok) {
                     throw new NolaProviderError(`TypeSafe reply is malformed: ${decoded.reason}`, { definitive: true });
+                }
                 value[key] = decoded.value;
             }
             const durationMs = Date.now() - requestedAt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nola-lang/providers",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Nola bring-your-own LLM providers: openai, anthropic, google, typesafe, mock, resilience combinators, record/replay",
   "keywords": [
     "nola",
@@ -37,8 +37,8 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@nola-lang/ast": "0.1.11",
-    "@nola-lang/core": "0.1.11"
+    "@nola-lang/ast": "0.1.12",
+    "@nola-lang/core": "0.1.12"
   },
   "engines": {
     "node": ">=22"

package/dist/typesafe-questions.d.ts

@@ -1,36 +0,0 @@
-import type { JsonSchema } from "@nola-lang/core";
-/** One question as `POST /v1/systemone` takes it. Only the two primitives Nola output types can express. */
-export type TypesafeQuestion = {
-    type: "choice";
-    instructions: string;
-    criteria: Record<string, string>;
-} | {
-    type: "noul";
-    instructions: string;
-};
-export type DecodeResult = {
-    ok: true;
-    value: unknown;
-} | {
-    ok: false;
-    reason: string;
-};
-/** Turns the wire answer for one question into the JSON value the ask expects. */
-export type Decoder = (answer: unknown) => DecodeResult;
-export interface QuestionPlan {
-    /** keyed by property name, or "value" for a scalar root */
-    questions: Record<string, TypesafeQuestion>;
-    decode: Record<string, Decoder>;
-    /** true ⇔ the reply is the bare "value" answer, not an object of answers */
-    scalar: boolean;
-}
-export type MappingResult = {
-    ok: true;
-    plan: QuestionPlan;
-} | {
-    ok: false;
-    reason: string;
-};
-/** The questions and decoders for an ask's output schema, or why Jev cannot serve it. */
-export declare function questionsFor(schema: JsonSchema | undefined): MappingResult;
-//# sourceMappingURL=typesafe-questions.d.ts.map

package/dist/typesafe-questions.js

@@ -1,124 +0,0 @@
-const SERVES = "typesafe() serves only literal unions and booleans";
-const SCALAR_INSTRUCTIONS = "Determine the value the request asks for.";
-function fail(reason) {
-    return { ok: false, reason };
-}
-/** `labels` maps each wire label to the JSON value it stands for (the literal itself, or its number). */
-function choiceQuestion(key, instructions, labels) {
-    const criteria = {};
-    for (const label of labels.keys())
-        criteria[label] = label;
-    const decode = (answer) => {
-        if (answer === undefined || answer === null)
-            return fail(`answer "${key}" is missing from the reply`);
-        const choice = answer.choice;
-        if (typeof choice !== "string" || !labels.has(choice)) {
-            return fail(`answer "${key}" chose ${JSON.stringify(choice)}, which is not one of the options sent`);
-        }
-        return { ok: true, value: labels.get(choice) };
-    };
-    return { ok: true, question: { type: "choice", instructions, criteria }, decode };
-}
-function noulQuestion(key, instructions) {
-    const decode = (answer) => {
-        if (answer === undefined || answer === null)
-            return fail(`answer "${key}" is missing from the reply`);
-        const noul = answer.noul;
-        if (typeof noul !== "number" || Number.isNaN(noul))
-            return fail(`answer "${key}" has no numeric noul`);
-        return { ok: true, value: noul >= 0.5 };
-    };
-    return { ok: true, question: { type: "noul", instructions }, decode };
-}
-/** Follow a `$ref` chain through the root `$defs`; the FIRST description seen along the chain wins. */
-function resolve(node, defs, path) {
-    let current = node;
-    let description = node.description;
-    const seen = new Set();
-    while ("$ref" in current) {
-        const ref = current.$ref;
-        if (seen.has(ref))
-            return fail(`${path} is a cyclic reference ${JSON.stringify(ref)}; ${SERVES}`);
-        seen.add(ref);
-        const name = /^#\/\$defs\/(.+)$/.exec(ref)?.[1];
-        const next = name ? defs?.[name] : undefined;
-        if (!next)
-            return fail(`${path} is an unresolved reference ${JSON.stringify(ref)}; ${SERVES}`);
-        current = next;
-        description ??= current.description;
-    }
-    return description === undefined ? { ok: true, node: current } : { ok: true, node: current, description };
-}
-/** What an unsupported node is, in the words of the failure reason. */
-function kindOf(node) {
-    if ("const" in node)
-        return "a single literal";
-    if ("anyOf" in node)
-        return "a union that is not all string literals or all number literals";
-    if ("type" in node) {
-        switch (node.type) {
-            case "string":
-                return node.format === "date-time" ? "a date-time string" : "a free-form string";
-            case "number":
-            case "integer":
-                return "a number";
-            case "array":
-                return "an array";
-            case "object":
-                return "properties" in node ? "a nested object" : "a record";
-            case "null":
-                return "null";
-        }
-    }
-    return "an unsupported shape";
-}
-/** Map one schema node to a question. `path` names the node in failure reasons; `key` is the answer key. */
-function questionFor(raw, defs, path, key) {
-    const resolved = resolve(raw, defs, path);
-    if (!resolved.ok)
-        return resolved;
-    const { node, description } = resolved;
-    const instructions = description ?? (key === "value" ? SCALAR_INSTRUCTIONS : `Determine "${key}".`);
-    if ("type" in node && node.type === "boolean")
-        return noulQuestion(key, instructions);
-    if ("type" in node && node.type === "string" && node.enum) {
-        return choiceQuestion(key, instructions, new Map(node.enum.map((label) => [label, label])));
-    }
-    if ("anyOf" in node && node.anyOf.length >= 2) {
-        const consts = node.anyOf.map((branch) => ("const" in branch ? branch.const : undefined));
-        if (consts.every((c) => typeof c === "string")) {
-            return choiceQuestion(key, instructions, new Map(consts.map((c) => [c, c])));
-        }
-        if (consts.every((c) => typeof c === "number")) {
-            return choiceQuestion(key, instructions, new Map(consts.map((c) => [String(c), c])));
-        }
-    }
-    return fail(`${path} is ${kindOf(node)}; ${SERVES}`);
-}
-/** The questions and decoders for an ask's output schema, or why Jev cannot serve it. */
-export function questionsFor(schema) {
-    if (!schema)
-        return fail(`the ask has no output schema (free text); ${SERVES}`);
-    const defs = "$defs" in schema ? schema.$defs : undefined;
-    const root = resolve(schema, defs, "the output type");
-    if (!root.ok)
-        return root;
-    const node = root.node;
-    if ("type" in node && node.type === "object" && "properties" in node) {
-        const questions = {};
-        const decode = {};
-        for (const [name, prop] of Object.entries(node.properties)) {
-            const mapped = questionFor(prop, defs, `output property ${JSON.stringify(name)}`, name);
-            if (!mapped.ok)
-                return mapped;
-            questions[name] = mapped.question;
-            decode[name] = mapped.decode;
-        }
-        return { ok: true, plan: { questions, decode, scalar: false } };
-    }
-    const mapped = questionFor(schema, defs, "the output type", "value");
-    if (!mapped.ok)
-        return mapped;
-    return { ok: true, plan: { questions: { value: mapped.question }, decode: { value: mapped.decode }, scalar: true } };
-}
-//# sourceMappingURL=typesafe-questions.js.map