@harperfast/harper 5.3.0-beta.3 → 5.3.0-beta.4

package/dist/resources/models/generativeDecision.js

@@ -0,0 +1,315 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenerativeDecisionError = exports.MAX_SAMPLES = exports.DEFAULT_SAMPLES = void 0;
+exports.registerGenerativeDecisionBackend = registerGenerativeDecisionBackend;
+exports.createGenerativeDecisionBackend = createGenerativeDecisionBackend;
+/**
+ * Built-in `decision` backend over a configured generative logical name (#2779). A call either
+ * scores every allowed value from the generative model's own likelihoods (#2838), when that name
+ * routes to a backend implementing `scoreChoices`, or asks the model for `samples`
+ * structured-output completions and reports the vote frequencies as the distribution. Configured
+ * as `models.decision.<name>: { backend: generative, scoring: auto | vote | score }`.
+ *
+ * Every sample and every scoring call flows through the `models` facade, so each one writes its
+ * own `hdb_model_calls` row and token metrics; the decide row itself reports no usage, or the
+ * tokens would be counted twice (the same reason the agent loop's outer call writes no row).
+ */
+const hdbError_ts_1 = require("../../utility/errors/hdbError.js");
+const backendHelpers_ts_1 = require("./backendHelpers.js");
+const backendRegistry_ts_1 = require("./backendRegistry.js");
+const decision_ts_1 = require("./decision.js");
+const Models_ts_1 = require("./Models.js");
+const routing_ts_1 = require("./routing.js");
+exports.DEFAULT_SAMPLES = 5;
+exports.MAX_SAMPLES = 25;
+const DEFAULT_CONCURRENCY = 5;
+const STRUCTURED_OUTPUT = Object.freeze(['structuredOutput']);
+const CAPABILITIES = Object.freeze({
+    embed: false,
+    generate: false,
+    stream: false,
+    tools: false,
+    adapters: false,
+    decide: true,
+    calibrated: false,
+    noMatch: true,
+    calibratedNoMatch: false,
+});
+const VOTE_SYSTEM_PROMPT = 'You make a decision about the input. Reply with a single JSON object that matches the required schema, choosing only from the allowed values.';
+const SCORE_SYSTEM_PROMPT = 'You make a decision about the input, choosing only from the allowed values.';
+const SCORE_NO_MATCH_SYSTEM_PROMPT = 'You make a decision about the input. Choose the allowed value that fits it, or the final option when none of the allowed values fits.';
+const NO_MATCH_CHOICE = '(none of the listed values)';
+class GenerativeDecisionError extends hdbError_ts_1.ServerError {
+    constructor(message) {
+        super(message);
+        this.name = 'GenerativeDecisionError';
+    }
+}
+exports.GenerativeDecisionError = GenerativeDecisionError;
+function registerGenerativeDecisionBackend(args) {
+    if (args.kind !== 'decision')
+        throw new GenerativeDecisionError(`backend 'generative' serves models.decision entries, not models.${args.kind}`);
+    (0, backendRegistry_ts_1.setDecision)(args.logicalName, createGenerativeDecisionBackend(args.config));
+}
+function createGenerativeDecisionBackend(config = {}, deps = {}) {
+    const generate = deps.generate ?? ((input, opts) => Models_ts_1.models.generate(input, opts));
+    const score = deps.score ?? ((input, choices, opts) => Models_ts_1.models.scoreChoices(input, choices, opts));
+    const canScore = deps.canScore ?? routesToScorer;
+    const logicalName = config.generative ?? 'default';
+    const samples = boundedCount(config.samples, exports.DEFAULT_SAMPLES);
+    const concurrency = boundedCount(config.concurrency, DEFAULT_CONCURRENCY);
+    const scoring = config.scoring ?? 'auto';
+    const { temperature, requestTimeoutMs } = config;
+    const vote = async (state, schema, instructions, signal) => {
+        const input = buildInput(state, schema, instructions, (0, decision_ts_1.wantsNoMatch)(schema) ? `${VOTE_SYSTEM_PROMPT} ${voteNoMatchLine(schema)}` : VOTE_SYSTEM_PROMPT, undefined);
+        const responseFormat = { schema: (0, decision_ts_1.toResponseSchema)(schema) };
+        const votes = await runPool(Array.from({ length: samples }, () => async (sampleSignal) => {
+            const result = await generate(input, {
+                model: logicalName,
+                responseFormat,
+                temperature,
+                signal: sampleSignal,
+                requires,
+            });
+            return parseSample(schema, result.content, logicalName);
+        }), concurrency, signal);
+        return tally(schema, votes);
+    };
+    const scoreLeaf = async (state, schema, field, leaf, instructions, signal) => {
+        const values = (0, decision_ts_1.allowedValues)(leaf);
+        const choices = values.map((value) => String(value));
+        if (leaf.noMatch !== true) {
+            const input = buildInput(state, schema, instructions, SCORE_SYSTEM_PROMPT, field);
+            const scored = await score(input, choices, { model: logicalName, signal });
+            return { distribution: softmax(values, scored?.logLikelihoods, logicalName) };
+        }
+        const input = buildInput(state, schema, instructions, SCORE_NO_MATCH_SYSTEM_PROMPT, field);
+        const scored = await score(input, [...choices, noMatchChoice(choices)], { model: logicalName, signal });
+        const all = softmax([...values, NO_MATCH], scored?.logLikelihoods, logicalName);
+        // Normalized over the allowed values' own scores, not by dividing out the none share, which can underflow to zero.
+        const distribution = softmax(values, scored.logLikelihoods.slice(0, values.length), logicalName);
+        return { distribution, noMatch: all[values.length].probability };
+    };
+    // One scoring call per leaf, through the same pool and budget as voting, so a 32-field schema
+    // does not open 32 provider connections at once and a caller abort settles every sibling.
+    const scoreAll = async (state, schema, instructions, signal) => {
+        if (!(0, decision_ts_1.isObjectSchema)(schema)) {
+            const [scored] = await runPool([(leafSignal) => scoreLeaf(state, schema, undefined, schema, instructions, leafSignal)], concurrency, signal);
+            return scored;
+        }
+        const entries = Object.entries(schema.properties);
+        const marginals = await runPool(entries.map(([name, leaf]) => (leafSignal) => scoreLeaf(state, schema, name, leaf, instructions, leafSignal)), concurrency, signal);
+        return { fields: Object.fromEntries(entries.map(([name], i) => [name, marginals[i]])) };
+    };
+    const signatureFor = (mode) => `generative=${logicalName};mode=${mode};samples=${samples};temperature=${temperature ?? 'default'}`;
+    const requires = config.requireStructuredOutput === false ? undefined : STRUCTURED_OUTPUT;
+    return {
+        name: 'generative',
+        capabilities: () => CAPABILITIES,
+        async decide(state, schema, opts) {
+            const signal = (0, backendHelpers_ts_1.composeSignal)(opts.signal, requestTimeoutMs);
+            const mode = scoring === 'auto' ? (canScore(logicalName, largestLeaf(schema)) ? 'score' : 'vote') : scoring;
+            if (mode === 'score') {
+                try {
+                    return {
+                        status: 'completed',
+                        output: { ...(await scoreAll(state, schema, opts.instructions, signal)), signature: signatureFor('score') },
+                    };
+                }
+                catch (err) {
+                    if (scoring !== 'auto' || !isScoringUnsupported(err))
+                        throw err;
+                }
+            }
+            return {
+                status: 'completed',
+                output: { ...(await vote(state, schema, opts.instructions, signal)), signature: signatureFor('vote') },
+            };
+        },
+    };
+}
+// A candidate that advertises scoring without implementing it counts as able, so the facade reports
+// that contract failure instead of the decision quietly voting.
+function routesToScorer(logicalName, largestLeafSize) {
+    for (const backend of (0, routing_ts_1.getRouter)().route({ kind: 'generative', logicalName, requires: ['scoreChoices'] })) {
+        const limit = (0, Models_ts_1.scoringLimit)(backend.capabilities());
+        if (limit === undefined || largestLeafSize <= limit || typeof backend.scoreChoices !== 'function')
+            return true;
+    }
+    return false;
+}
+// Infinity for anything that is not a well-formed leaf, so an unexpected shape never reads as within a limit.
+function leafSize(leaf) {
+    if (!leaf || typeof leaf !== 'object')
+        return Infinity;
+    if (Array.isArray(leaf.enum))
+        return leaf.enum.length;
+    if (leaf.type === 'boolean')
+        return 2;
+    const { type, minimum, maximum } = leaf;
+    if (type !== 'integer' || !Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximum))
+        return Infinity;
+    const size = maximum - minimum + 1;
+    return size > 0 ? size : Infinity;
+}
+// A leaf that opted into no-match is scored with one extra choice, the "none" continuation.
+function scoredChoices(leaf) {
+    return leafSize(leaf) + (leaf?.noMatch === true ? 1 : 0);
+}
+function largestLeaf(schema) {
+    if (!(0, decision_ts_1.isObjectSchema)(schema))
+        return scoredChoices(schema);
+    let largest = 0;
+    for (const name in schema.properties)
+        if (Object.hasOwn(schema.properties, name))
+            largest = Math.max(largest, scoredChoices(schema.properties[name]));
+    return largest;
+}
+/** The errors after which `auto` votes: the backend declined this call, or lost the capability since the probe. */
+function isScoringUnsupported(err) {
+    const name = err?.name;
+    return name === 'ChoiceScoringUnsupportedError' || name === 'ModelCapabilityError';
+}
+/**
+ * Run `tasks` with at most `concurrency` in flight under one AbortController. The first failure
+ * aborts the rest, and the pool settles before that failure is thrown, so no task rejects
+ * unobserved and the facade never falls back to another candidate while calls are in flight.
+ * Siblings are aborted with a fresh reason, not the failure itself: a call that was cut short is
+ * recorded as aborted, not as a second copy of the failure with the same billed usage.
+ */
+async function runPool(tasks, concurrency, signal) {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(signal?.reason);
+    if (signal?.aborted)
+        onAbort();
+    else
+        signal?.addEventListener('abort', onAbort, { once: true });
+    const results = new Array(tasks.length);
+    let failure;
+    let failed = false;
+    let next = 0;
+    const worker = async () => {
+        while (next < tasks.length && !controller.signal.aborted) {
+            const index = next++;
+            try {
+                results[index] = await tasks[index](controller.signal);
+            }
+            catch (err) {
+                if (!failed) {
+                    failed = true;
+                    failure = err;
+                }
+                controller.abort(new DOMException('another call in this decision failed', 'AbortError'));
+                return;
+            }
+        }
+    };
+    try {
+        await Promise.all(Array.from({ length: Math.min(concurrency, tasks.length) }, worker));
+    }
+    finally {
+        signal?.removeEventListener('abort', onAbort);
+    }
+    if (failed)
+        throw failure;
+    signal?.throwIfAborted();
+    return results;
+}
+function boundedCount(value, fallback) {
+    if (!Number.isInteger(value) || value < 1)
+        return fallback;
+    return Math.min(value, exports.MAX_SAMPLES);
+}
+function parseSample(schema, content, logicalName) {
+    try {
+        return (0, decision_ts_1.parseDecisionSample)(schema, content);
+    }
+    catch (err) {
+        throw new GenerativeDecisionError(`generative model '${logicalName}' produced a sample outside the decision schema: ${err.message}`);
+    }
+}
+/** Normalize the backend's log-likelihoods over the leaf's values; the shape is checked because no backend's arithmetic is trusted. */
+function softmax(values, logLikelihoods, logicalName) {
+    if (!Array.isArray(logLikelihoods) ||
+        logLikelihoods.length !== values.length ||
+        !logLikelihoods.every((x) => typeof x === 'number' && Number.isFinite(x)))
+        throw new GenerativeDecisionError(`generative model '${logicalName}' did not return one finite log-likelihood per allowed value (${values.length})`);
+    const scores = logLikelihoods;
+    const max = Math.max(...scores);
+    const weights = scores.map((x) => Math.exp(x - max));
+    const total = weights.reduce((sum, w) => sum + w, 0);
+    return values.map((value, i) => ({ value, probability: weights[i] / total }));
+}
+function buildInput(state, schema, instructions, system, field) {
+    const lines = [];
+    if (instructions)
+        lines.push(instructions, '');
+    if (schema.description)
+        lines.push(schema.description, '');
+    if (!(0, decision_ts_1.isObjectSchema)(schema)) {
+        lines.push(`Decide "value": ${describeLeaf(schema)}`);
+    }
+    else if (field !== undefined) {
+        lines.push(`Decide "${field}": ${describeLeaf(schema.properties[field])}`);
+    }
+    else {
+        lines.push('Decide each field:');
+        for (const [name, leaf] of Object.entries(schema.properties))
+            lines.push(`- ${name}: ${describeLeaf(leaf)}`);
+    }
+    lines.push('', 'Input:', (0, decision_ts_1.stateToText)(state));
+    return { system, messages: [{ role: 'user', content: lines.join('\n') }] };
+}
+function describeLeaf(leaf) {
+    const range = !('enum' in leaf) && leaf.type === 'integer'
+        ? `an integer from ${leaf.minimum} to ${leaf.maximum}`
+        : `one of ${(0, decision_ts_1.allowedValues)(leaf)
+            .map((value) => JSON.stringify(value))
+            .join(', ')}`;
+    return leaf.description ? `${leaf.description} (${range})` : range;
+}
+function tally(schema, votes) {
+    if ((0, decision_ts_1.isObjectSchema)(schema)) {
+        const fields = {};
+        for (const [name, leaf] of Object.entries(schema.properties))
+            fields[name] = tallyLeaf(leaf, votes.map((vote) => vote[name]));
+        return { fields };
+    }
+    return tallyLeaf(schema, votes);
+}
+function tallyLeaf(leaf, votes) {
+    if (leaf.noMatch !== true)
+        return { distribution: frequencies(leaf, votes) };
+    const values = new Array(votes.length);
+    let none = 0;
+    for (let i = 0; i < votes.length; i++) {
+        const pair = votes[i];
+        values[i] = pair.value;
+        if (pair.noMatch)
+            none++;
+    }
+    return { distribution: frequencies(leaf, values), noMatch: none / votes.length };
+}
+const NO_MATCH = Symbol('noMatch');
+function voteNoMatchLine(schema) {
+    const rule = 'give the closest allowed value as "value", and set "noMatch" to true only when none of the allowed values truly fits the input.';
+    if (!(0, decision_ts_1.isObjectSchema)(schema))
+        return `Answer as { "value", "noMatch" }: ${rule}`;
+    const names = Object.entries(schema.properties)
+        .filter(([, leaf]) => leaf.noMatch === true)
+        .map(([name]) => JSON.stringify(name));
+    return `Answer ${names.join(', ')} each as { "value", "noMatch" }: ${rule}`;
+}
+function noMatchChoice(choices) {
+    let text = NO_MATCH_CHOICE;
+    while (choices.includes(text))
+        text = `(${text})`;
+    return text;
+}
+function frequencies(leaf, votes) {
+    const counts = new Map();
+    for (const vote of votes)
+        counts.set(vote, (counts.get(vote) ?? 0) + 1);
+    return (0, decision_ts_1.allowedValues)(leaf).map((value) => ({ value, probability: (counts.get(value) ?? 0) / votes.length }));
+}
+//# sourceMappingURL=generativeDecision.js.map

package/dist/resources/models/generativeDecision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generativeDecision.js","sourceRoot":"","sources":["../../../resources/models/generativeDecision.ts"],"names":[],"mappings":"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"}

package/dist/resources/models/types.d.ts

@@ -10,8 +10,15 @@ export interface Models {
     embed(input: string | string[], opts?: EmbedOpts): Promise<Float32Array[]>;
     generate(input: GenerateInput, opts?: GenerateOpts): Promise<GenerateResult>;
     generateStream(input: GenerateInput, opts?: GenerateOpts): AsyncIterable<GenerateChunk>;
+    /** Choose from a closed, schema-defined set and return the distribution over it. See #2779. */
+    decide<T = unknown>(state: DecideInput, schema: DecisionSchema, opts: RecordedDecideOpts): Promise<RecordedDecision<T>>;
+    decide<T = unknown>(state: DecideInput, schema: DecisionSchema, opts?: DecideOpts): Promise<Decision<T>>;
+    /** The durable record of a decision made with `persist: true`, with its recorded outcome, or undefined. See #2840. */
+    getDecision<T = unknown>(id: string): Promise<DecisionRecord<T> | undefined>;
+    /** Record what actually happened for a decision: its truth, the action taken, or both. See #2840. */
+    recordOutcome<T = unknown>(id: string, outcome: OutcomeReport): Promise<DecisionRecord<T>>;
     /** Register a custom backend under a logical id, selectable via `opts.model`. See #1325. */
-    registerBackend(kind: 'embedding' | 'generative', id: string, backend: ModelBackend): void;
+    registerBackend(kind: ModelKind, id: string, backend: ModelBackend): void;
     /** Build a `ModelBackend` from a spec; pair with `registerBackend`. See #1325. */
     defineBackend(spec: DefineBackendSpec): ModelBackend;
     /** Replace the model selection policy with a custom router. See #1326. */
@@ -23,19 +30,50 @@ export interface ModelBackend {
     embed?(input: string | string[], opts: BackendOpts<EmbedOpts>): Promise<ModelCallResult<Float32Array[]>>;
     generate?(input: GenerateInput, opts: BackendOpts<GenerateOpts>): Promise<ModelCallResult<GenerateResult>>;
     generateStream?(input: GenerateInput, opts: BackendOpts<GenerateOpts>): AsyncIterable<GenerateChunk>;
+    decide?(state: DecideInput, schema: DecisionSchema, opts: BackendOpts<DecideOpts>): Promise<ModelCallResult<DecisionOutput<unknown>>>;
+    /**
+     * Score every entry of `choices` as the answer to `input` from the model's own likelihoods
+     * (#2838): one finite, unnormalized log-likelihood per choice, in order. A call the backend
+     * cannot score (too many choices for its alternatives list, a model that rejects
+     * log-probabilities, a response with no scored label) throws `ChoiceScoringUnsupportedError`
+     * so the caller can fall back; any other error is a failure.
+     */
+    scoreChoices?(input: GenerateInput, choices: readonly string[], opts: BackendOpts<ScoreChoicesOpts>): Promise<ModelCallResult<ChoiceScores>>;
 }
+/** Registry kinds a backend is mapped under; a `decision` backend implements `decide` (#2779). */
+export type ModelKind = 'embedding' | 'generative' | 'decision';
 export interface ModelCapabilities {
     embed: boolean;
     generate: boolean;
     stream: boolean;
     tools: boolean;
     adapters: boolean;
+    /** Implements `decide`. Optional so pre-#2779 backends stay source-compatible; absent reads as false. */
+    decide?: boolean;
+    /** `decide` probabilities are calibrated as returned. Absent reads as false. */
+    calibrated?: boolean;
+    /** Implements `scoreChoices`. Absent reads as false. */
+    scoreChoices?: boolean;
+    /** `decide` returns a no-match score for leaves that opt in with `noMatch: true` (#2846). Absent reads as false. */
+    noMatch?: boolean;
+    /** That no-match score is calibrated as returned. Absent reads as false. */
+    calibratedNoMatch?: boolean;
+    /**
+     * `generate` sends `responseFormat: { schema }` to the provider as a decoding constraint rather
+     * than a hint. Says what Harper sends, not what a remote endpoint honors. Absent reads as false.
+     */
+    structuredOutput?: boolean;
+    /**
+     * The most choices one `scoreChoices` call accepts. Absent means no stated limit. A limit, not a
+     * capability: it cannot be required, and a call above it is declined without a request.
+     */
+    maxScoredChoices?: number;
 }
-/** A capability a call can require of its backend (a key of `ModelCapabilities`). */
-export type Capability = keyof ModelCapabilities;
+/** A capability a call can require of its backend (a boolean key of `ModelCapabilities`). */
+export type Capability = Exclude<keyof ModelCapabilities, 'maxScoredChoices'>;
 /** What the router is asked to resolve for a single call. See #1326. */
 export interface RouteRequest {
-    kind: 'embedding' | 'generative';
+    kind: ModelKind;
     /** Logical name from `opts.model` (a role or a concrete backend id); defaults to `'default'`. */
     logicalName: string;
     /** Capabilities the chosen backend must satisfy — explicit `opts.requires` plus any auto-derived (e.g. tools present in the input). */
@@ -67,10 +105,22 @@ export interface DefineBackendSpec {
     embed?: ModelBackend['embed'];
     generate?: ModelBackend['generate'];
     generateStream?: ModelBackend['generateStream'];
+    decide?: ModelBackend['decide'];
+    scoreChoices?: ModelBackend['scoreChoices'];
     /** Backend supports tool calls in `generate` / `generateStream`. Default `false`. */
     tools?: boolean;
     /** Backend supports per-call LoRA / adapter selection. Default `false`. */
     adapters?: boolean;
+    /** `decide` probabilities are calibrated as returned. Default `false`. */
+    calibrated?: boolean;
+    /** `decide` returns a no-match score for opted-in leaves. Default `false`. */
+    noMatch?: boolean;
+    /** That no-match score is calibrated as returned. Default `false`. */
+    calibratedNoMatch?: boolean;
+    /** `generate` sends `responseFormat: { schema }` as a decoding constraint. Default `false`. */
+    structuredOutput?: boolean;
+    /** The most choices one `scoreChoices` call accepts, a positive integer. Default: no limit. */
+    maxScoredChoices?: number;
 }
 export type EmbedOpts = {
     model?: string;
@@ -80,6 +130,184 @@ export type EmbedOpts = {
     inputType?: 'document' | 'query';
     signal?: AbortSignal;
 };
+/** Text, or JSON-serializable program state, for `decide`. */
+export type DecideInput = string | object;
+/**
+ * One leaf of a decision schema: a closed set every backend family can score. `enum` holds
+ * 2..255 distinct values of one type; an integer range spans at most 255 values; booleans order
+ * as `[false, true]` for tie-breaking.
+ */
+export type DecisionLeaf = {
+    description?: string;
+    noMatch?: boolean;
+} & ({
+    enum: readonly string[] | readonly number[] | readonly boolean[];
+} | {
+    type: 'boolean';
+} | {
+    type: 'integer';
+    minimum: number;
+    maximum: number;
+});
+/** A decision schema: one leaf, or one level of named leaves. Deeper nesting is deliberately unsupported. */
+export type DecisionSchema = DecisionLeaf | {
+    type: 'object';
+    description?: string;
+    properties: Record<string, DecisionLeaf>;
+};
+export type DecideOpts = {
+    model?: string;
+    /** Capabilities the chosen backend must satisfy, e.g. `['calibrated']`; the router filters candidates (#1326). */
+    requires?: Capability[];
+    /** Task framing beyond the schema's own descriptions. */
+    instructions?: string;
+    signal?: AbortSignal;
+    /**
+     * `true` commits a durable record of the decision to `hdb_model_decisions` before returning, so its
+     * outcome can be recorded later; the result then carries its `id`. Default `false`: nothing is stored
+     * beyond the per-call analytics row, as with `embed` and `generate`.
+     */
+    persist?: boolean;
+};
+/** Options that record the decision, so the result is a `RecordedDecision` with an `id`. */
+export type RecordedDecideOpts = DecideOpts & {
+    persist: true;
+};
+export interface DecisionOutcome {
+    value: unknown;
+    probability: number;
+}
+/**
+ * What a `decision` backend returns for one call. For a leaf schema `distribution` is required
+ * and complete (one entry per allowed value, summing to one); for an object schema `fields`
+ * carries one such entry per property. The facade derives `value` and `probability`, so a
+ * backend may omit them; a `value` it does supply must be a most-probable outcome, and on a
+ * tie it leads the distribution.
+ */
+export interface DecisionOutput<T = unknown> {
+    value?: T;
+    probability?: number;
+    distribution?: DecisionOutcome[];
+    fields?: Record<string, DecisionOutput<unknown>>;
+    /** For a leaf that opted in: the score in [0, 1] that the input matches none of the allowed values. */
+    noMatch?: number;
+    calibrated?: boolean;
+    /**
+     * Opaque identity of the configuration that produced the scores (sampling, scoring method,
+     * prompt revision), stored with the decision so calibration is keyed per configuration (#2841).
+     */
+    signature?: string;
+}
+/**
+ * Result of `models.decide`. For a leaf schema `value` is the first entry of `distribution`,
+ * which is sorted descending with ties in schema order unless the backend chose one of the tied
+ * values; `probability` is its entry. For an object schema
+ * `value` is assembled from each field's marginal argmax — a combination no single sample may
+ * have produced — and the marginals live in `fields`.
+ */
+export interface Decision<T = unknown> {
+    /** Present only when the call passed `persist: true`: the cluster-unique id of the decision's record in `hdb_model_decisions`, committed before the decision is returned; pass it to `recordOutcome` (#2840). */
+    id?: string;
+    value: T;
+    probability?: number;
+    distribution?: DecisionOutcome[];
+    fields?: Record<string, FieldDecision>;
+    /** Leaf schemas that opted in: the score that the input matches none of the allowed values (#2846). */
+    noMatch?: number;
+    /** Whether the probabilities come from a calibrated source, as the backend reports it. */
+    calibrated: boolean;
+    usage?: TokenUsage;
+}
+/** A decision made with `persist: true`: its `id` is always present. */
+export type RecordedDecision<T = unknown> = Decision<T> & {
+    id: string;
+};
+/** One field's marginal in an object-schema `Decision`. */
+export interface FieldDecision {
+    value: unknown;
+    probability: number;
+    distribution: DecisionOutcome[];
+    /** Fields that opted in: the no-match score. */
+    noMatch?: number;
+}
+export type ScoreChoicesOpts = {
+    model?: string;
+    /** Capabilities the chosen backend must satisfy, beyond `scoreChoices` itself; the router filters candidates (#1326). */
+    requires?: Capability[];
+    signal?: AbortSignal;
+};
+/** Unnormalized; the caller normalizes. */
+export interface ChoiceScores {
+    logLikelihoods: number[];
+}
+/** What turned out to be true for a decision: an allowed value, none of them, or not known. Tagged, so no label is a sentinel. */
+export type OutcomeTruth = {
+    kind: 'value';
+    value: unknown;
+} | {
+    kind: 'noMatch';
+} | {
+    kind: 'unknown';
+};
+/** What the application did with a decision: acted on a value, routed it as no-match, abstained by policy, or not known. */
+export type OutcomeAction = {
+    kind: 'value';
+    value: unknown;
+} | {
+    kind: 'noMatch';
+} | {
+    kind: 'abstained';
+} | {
+    kind: 'unknown';
+};
+/** The facts reported for one leaf: either, or both. Each is stored on its own, so reports never overwrite each other. */
+export interface LeafOutcomeReport {
+    truth?: OutcomeTruth;
+    action?: OutcomeAction;
+}
+/** A `recordOutcome` report: leaf facts for a leaf schema, or per-field facts for an object schema. */
+export type OutcomeReport = LeafOutcomeReport | {
+    fields: Record<string, LeafOutcomeReport>;
+};
+export interface RecordedLeafOutcome extends LeafOutcomeReport {
+    truthAt?: number;
+    actionAt?: number;
+}
+export type RecordedOutcome = RecordedLeafOutcome | {
+    fields: Record<string, RecordedLeafOutcome>;
+};
+/**
+ * The durable record of one decision (#2840): what was asked, what was answered, who answered,
+ * and what was recorded afterwards. Written once by `decide`; only `outcome` grows.
+ */
+export interface DecisionRecord<T = unknown> {
+    id: string;
+    /** The `hdb_model_calls` row of the call that produced it; correlation only. */
+    callId: number;
+    at: number;
+    /** When the record and its facts expire; a fact never extends it. */
+    expiresAt: number;
+    tenant?: string;
+    app?: string;
+    backend: string;
+    model: string;
+    signature?: string;
+    /** Identity of the `models` config block in force when the decision was made. */
+    configHash?: string;
+    /** sha256 of the per-call `instructions`, when any were given. */
+    instructionsHash?: string;
+    /** The schema's allowed values, without descriptions. */
+    schema: DecisionSchema;
+    /** Identity of the full schema, descriptions included. */
+    schemaHash: string;
+    value: T;
+    probability?: number;
+    distribution?: DecisionOutcome[];
+    fields?: Record<string, FieldDecision>;
+    noMatch?: number;
+    calibrated: boolean;
+    outcome: RecordedOutcome;
+}
 export type GenerateOpts = {
     model?: string;
     /** Capabilities the chosen backend must satisfy (e.g. `['tools']`); the router selects/filters candidates accordingly. Tools present in the input are auto-required. (#1326) */