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

package/resources/models/DESIGN.md

@@ -0,0 +1,39 @@
+# resources/models/ — model facade, backends, decisions
+
+Notes on invariants the models layer relies on that the code cannot state itself. User-facing behavior is documented in HarperFast/documentation.
+
+## Decision outputs are validated at the facade
+
+A `Decision` returned by `models.decide` names a value from the schema's allowed set, and its distribution has exactly one entry per allowed value, with finite probabilities in [0, 1] that sum to one (within 1e-3), sorted descending with ties in schema order unless the backend chose one of the tied values, which then leads. `normalizeDecision` (`decision.ts`) enforces this on every backend output, so no backend's arithmetic is trusted; a violation is a `DecisionContractError`, which `Models.decide` treats like any backend error (recorded against that backend, next candidate tried). A malformed schema or state rejects before routing and writes no analytics row, because nothing was called. Object schemas are marginal-only: `value` is assembled from each field's argmax and may be a combination no single sample produced. Enforced by `unitTests/resources/models/decision.test.js` and `decide.test.js`.
+
+## The generative adapter reports no usage of its own
+
+Every sample the adapter (`generativeDecision.ts`) takes is a `models.generate` call with its own `hdb_model_calls` row and token metrics. The adapter therefore returns no `usage` on its `ModelCallResult`; reporting the sum again would count each sample twice in `SUM(prompt_tokens)` and in `model-*-tokens`, the same double-billing the `toolMode: 'auto'` outer call avoids by writing no row. Samples run under one `AbortController`: the first failure aborts the rest, and the worker pool is awaited to settlement before the error is thrown, so no sample rejects unobserved and the facade never falls back to another candidate while calls are still in flight. Enforced by `unitTests/resources/models/generativeDecision.test.js`.
+
+## Required capabilities are checked on the candidate about to be invoked
+
+The router's candidate list is advisory: the default router filters by `requires`, but a custom router installed with `registerRouter` may return any backend. `assertCapabilities` (`Models.ts`) therefore re-checks every required capability against `capabilities()` immediately before each candidate is invoked, in every facade method, fallbacks included, and for a stream both before the iterable is returned and again on its first `next()`; a miss is a `ModelCapabilityError` recorded as `capability_unsupported`, and the next candidate is tried, except by a stream, which only ever uses its first candidate. Candidates are backend instances captured when the call was resolved, so the check sees a backend's own `capabilities()` at invocation time, not a registry entry a reload has since replaced; the built-in providers return one frozen object, so the check allocates nothing. The generative decision backend relies on it: by default it passes `requires: ['structuredOutput']` on every sample, so a generative candidate whose integration does not send the response schema as a decoding constraint (Anthropic and Bedrock today) is refused before a completion is billed, whatever router produced it, unless the entry sets `requireStructuredOutput: false`. Enforced by the custom-router cases in `unitTests/resources/models/Models.test.js`; the bootstrap cases in `generativeDecision.test.js` cover the default router's filtering of the same requirement.
+
+## Likelihood scoring is a leaf-level hook with voting as the fallback
+
+A generative backend may implement `scoreChoices` (#2838): one finite, unnormalized log-likelihood per choice, in order, for a whole call, or a `ChoiceScoringUnsupportedError` for a call it cannot score. A decline is weaker news than a failure, and the two are kept apart at every layer. The facade's internal `models.scoreChoices` validates the vector's shape before it records a success, so a malformed result is one failed attempt against that backend and the next candidate is tried; when every candidate fails it surfaces the first failure, and the primary's decline only when every candidate declined, so a decline never hides a broken fallback. A declined call is recorded as `scoring_unsupported` with the usage the error carries, because a completion that came back without log-probabilities was still billed: those tokens land on that attempt's failure row and in the token metric while the call-count metric stays a count of successes. They are billed once: no other error's `usage` is read, no other method's failure row carries usage (the `decide` row stays usage-free when a decline propagates under `score`), and the adapter aborts sibling calls with a fresh reason rather than the decline itself, so a call cut short is recorded as `aborted` and not as another copy of the decline. The adapter scores one leaf per call (each property of an object schema separately), normalizes by softmax, and never mixes paths: in `auto` mode a decline, or a `ModelCapabilityError`, discards any leaf already scored and votes the whole decision under the same budget, so a distribution is wholly scored or wholly voted; any other error fails the decision. `auto` asks the router synchronously before deciding, so a generative backend whose capabilities say no costs no attempt, no exception and no analytics row. The same probe reads each candidate's `maxScoredChoices`: when no scoring candidate can take the schema's largest leaf, `auto` votes without a scoring attempt, and the facade treats a call above a candidate's limit as a decline it records without invoking that backend, so sibling leaves are never scored and then discarded. A candidate that advertises scoring without implementing it still counts as able, so its contract failure is reported rather than hidden by a vote. `maxScoredChoices` is a limit, not a `Capability`: it cannot be required. The OpenAI backend labels the choices `A`..`T` on one line each (a value that cannot sit on one line as itself is JSON-quoted, so it cannot pose as a further option and values that differ only in whitespace stay distinct), asks for one token with `top_logprobs: 20`, combines spellings of a label by log-sum-exp, and places a label with no listed spelling only when the mass the list leaves over is smaller than the leading observed label's, so a wholly unlisted label can never be the chosen value; otherwise the call is declined rather than guessed. An unlisted label then stands at a floor no higher than the smallest listed alternative or the leftover, finite even when the list leaves nothing over. Every placed score is still an estimate: an observed label's own unlisted spellings can add up to the leftover to it, so two observed labels closer than that may be ordered wrongly, and a response with no label at all is declined rather than reported as uniform. A malformed alternative is a failure, not a decline. A model that refuses `logprobs`, by a 400 (by `param`, or by a message that names it and says it is unsupported) or by an answer with no log-probability field at all, has scoring switched off until reload and `capabilities()` says so for the configured model, so later decisions vote without an attempt; a completion with no content token or no alternatives, and an answer that is simply not a label, are declined for that call only, and any other HTTP failure stays an error so an outage does not silently turn into voting. Probabilities from scoring are still `calibrated: false`. Enforced by `unitTests/resources/models/generativeDecision.test.js`, `scoreChoices.test.js` and `unitTests/components/openai/index.test.js`.
+
+## `@decide` and `@embed` share one trigger rule
+
+Both directives derive an attribute on the originating node before the record is staged, in `_writeUpdate` and in the cache-from-source write. `writeHookApplies` and `sourceState` (`embedHook.ts`) are the only trigger logic: a replication receive, an `x-replicate-from: none` write or an audit replay never re-derives, a payload without the source leaves the derived attributes alone, a null source clears them, and a CRDT op is skipped. `@decide` writes the chosen value and, when named, its probability from one `models.decide` call, and a failure fails the write, so the two are never from different decisions and never half-written; a missing decider or an override without the promised probability fails the write too. `runWriteJobs` aborts the siblings of a failed hook and settles them before the failure is reported, so a rejected write neither waits on a hook that honors the signal nor keeps being mutated by one; the built-in hooks forward the signal to their model calls. `assertDerivedFieldOwnership` gives every derived field one writer, refuses a directive whose source is another directive's output, because the hooks run concurrently within a write, holds a decided field and its confidence to what the loader accepts, and refuses an `Object.prototype` key as any of those fields, because `sourceState` tests presence with `in`. The loader runs it, and `declareTable` runs it on the complete list (a peer's fields merged, an omitted primary key inherited) before that list replaces the live one or reaches the catalog, so a programmatic `table({ attributes })` declaration is held to the same rules and a refused declaration changes nothing. `Table.updatedAttributes` runs it too but only logs a violation, because it also runs when a descriptor an earlier build accepted is loaded from the catalog, and a table must keep loading. The hooks receive the request's signal, so a client that disconnects cancels the model calls as it did before the hooks were combined. A `decide` descriptor change persists without a reindex: a stored decision does not depend on the model, unlike an embedding, whose `version` carries the model. Enforced by `unitTests/resources/models/decideHook.test.js`, `decideDirective.test.js`, `decideWrite.test.js` and `integrationTests/server/decide-directive.test.ts`.
+
+## Built-ins serve one kind
+
+The provider factories (`ollama`, `openai`, `anthropic`, `bedrock`) treat every non-embedding kind as generative, so a `models.decision` entry naming one would register a backend with no `decide`. `builtinServesKind` (`bootstrap.ts`) refuses that entry at boot and reload, and `wrongKindEntrySchema` (`validation/configValidator.ts`) refuses it at validation, in both directions: `backend: generative` is the only built-in for `decision` and is refused under `embedding` and `generative`. Module backends are exempt because their factory receives `kind`.
+
+## A recorded decision is committed before its id is returned, and its facts are separate rows
+
+Recording is opt-in: `Models.decide` stores nothing beyond the per-call analytics row unless the call passes `persist: true`, so by default it costs what `embed` and `generate` cost and works on any node; only callers that will report outcomes pay for a durable record. The option types carry that promise: `RecordedDecideOpts` (`persist: true`) returns a `RecordedDecision` whose `id` is present, and any other options object returns a `Decision` whose `id` is optional. With `persist: true`, `Decision.id` names a row in `hdb_model_decisions` that `Models.decide` commits in a transaction of its own (`decisionStore.ts`: `transaction()` with a fresh context object, so the write never joins an ambient application transaction and survives that transaction's abort) before the decision is returned. The row is written once and never rewritten; each recorded fact (`truth` or `action`, per field for object schemas) is its own `hdb_model_outcomes` row keyed `<id>/<fact>[/<field>]`, so two facts recorded on two nodes cannot overwrite each other and a report never re-expires the prediction: facts copy the decision's `expiresAt`, and a report whose state equals the stored fact writes nothing. The id is a UUID because `getNextMonotonicTime()` is monotonic per process, not unique across nodes, and both tables replicate: they are declared with `replicate: true`, as the scheduler state table is, so a scoped `replication.databases` cannot exclude them, with `audit: true` as the feed, and neither is in `NON_REPLICATING_SYSTEM_TABLES`. With `persist: true`, a commit failure after the backend succeeded throws `DecisionPersistenceError` outside the candidate loop, so a storage fault never bills a second model call, and a read-only node rejects before routing. Both tables are provisioned with their primary key by `json/systemSchema.json` and the `5.3.0` directive, and `declareDecisionTablesAtBoot` (called from `componentLoader` after `bootstrapModels`) layers the attributes and the indexed `expiresAt` TTL on every writable node, so a peer that never decides still evicts. Enforced by `unitTests/resources/models/decisionStore.test.js` and `decideOutcome.test.js`.
+
+## No-match is a separate score, never a value
+
+A leaf opts in with `noMatch: true` (#2846, decided on #2843). The backend then returns a score in `[0, 1]` that the input matches none of the allowed values, beside the unchanged forced-choice `distribution`; the two are not a joint distribution, so the all-votes-no-match case still has a closest allowed value. No sentinel ever enters an enum, which is why boolean and integer leaves can opt in. An opted-in call requires the `noMatch` capability (and `calibratedNoMatch` when it requires `calibrated`), checked per candidate like every other requirement, and reports `calibrated: true` only when both scores are calibrated. A score on a leaf that did not opt in is dropped, so a schema without the flag sees exactly the pre-#2846 output. The generative adapter asks an opted-in leaf for `{ value, noMatch }` when voting and adds one distinct "none" choice when scoring, renormalizing the allowed values without it. Enforced by `unitTests/resources/models/noMatch.test.js`.
+
+## A `@decide` decision is recorded only when the record can reach it
+
+The built-in decider passes `persist: true` only when the directive names a `decision` attribute, so a directive nobody can report outcomes for writes no `hdb_model_decisions` row (#2852). With one, the decider records the decision and the hook stores `Decision.id` beside the value and confidence; a null source clears all three. The id is provenance an outcome report trusts, so `buildDecideBefore` rejects a write that carries it unless that same write derives or clears it, or arrives by replication or replay; `x-replicate-from: none` and a CRDT operation on the source do not qualify, since any request can send them. The association is bounded, not atomic: the decision commits in its own transaction before the record, so an aborted write, a later source write, or a delete leaves an unreferenced row that expires with the retention. On a read-only node no write can commit, so `Table` skips the model hooks and serves a source-cache fill without staging it (`noCacheStore`), for every table. Enforced by `decideHook.test.js`, `decideWrite.test.js`, `decideOutcome.test.js` and `integrationTests/server/decide-directive.test.ts`.

package/resources/models/Models.ts

@@ -9,12 +9,44 @@ import {
 import { getRouter, registerRouter as registerRouterImpl } from './routing.ts';
 import { getModelCallAnalyticsWriter, type ModelCallAnalyticsWriter, type ModelCallRecord } from './analyticsTable.ts';
 import { recordAction } from '../analytics/write.ts';
-import { ServerError } from '../../utility/errors/hdbError.ts';
+import { ClientError, ServerError } from '../../utility/errors/hdbError.ts';
 import { runAgentLoop, runAgentLoopStream } from './agentLoop.ts';
+import { assignFiniteTokenCount, ChoiceScoringUnsupportedError } from './backendHelpers.ts';
+import {
+	DecisionContractError,
+	DecisionInputError,
+	hashSchema,
+	hashText,
+	normalizeDecision,
+	wantsNoMatch,
+	scoringSchema,
+	snapshotSchema,
+	stateToText,
+	validateDecisionSchema,
+} from './decision.ts';
+import {
+	DECISION_RETENTION_MS,
+	DecisionPersistenceError,
+	type DecisionRow,
+	type DecisionStore,
+	getDecisionStore,
+	getModelsConfigHash,
+	newDecisionId,
+} from './decisionStore.ts';
 import type {
 	AccountingContext,
+	ModelCapabilities,
 	BackendOpts,
 	Capability,
+	ChoiceScores,
+	DecideInput,
+	DecideOpts,
+	RecordedDecideOpts,
+	RecordedDecision,
+	Decision,
+	DecisionOutput,
+	DecisionRecord,
+	DecisionSchema,
 	DefineBackendSpec,
 	EmbedOpts,
 	GenerateChunk,
@@ -22,13 +54,17 @@ import type {
 	GenerateOpts,
 	GenerateResult,
 	ModelBackend,
+	ModelKind,
 	ModelRouter,
 	ModelCallResult,
 	Models as ModelsContract,
+	ScoreChoicesOpts,
+	OutcomeReport,
 	TokenUsage,
 } from './types.ts';
 
 type CallMethod = ModelCallRecord['method'];
+type CallIdentity = { hash: string; scoring: DecisionSchema; configHash?: string };
 type MetricEmitter = (value: number, metric: string, path?: string) => void;
 
 /**
@@ -50,14 +86,17 @@ type MetricEmitter = (value: number, metric: string, path?: string) => void;
 export class Models implements ModelsContract {
 	#analyticsWriter: ModelCallAnalyticsWriter;
 	#emit: MetricEmitter;
+	#decisionStore: DecisionStore;
 
 	constructor(
 		analyticsWriter: ModelCallAnalyticsWriter = getModelCallAnalyticsWriter(),
 		// DI'd for unit tests; production wires up the module-scope `recordAction`.
-		metricEmitter: MetricEmitter = recordAction
+		metricEmitter: MetricEmitter = recordAction,
+		decisionStore: DecisionStore = getDecisionStore()
 	) {
 		this.#analyticsWriter = analyticsWriter;
 		this.#emit = metricEmitter;
+		this.#decisionStore = decisionStore;
 	}
 
 	/**
@@ -67,7 +106,7 @@ export class Models implements ModelsContract {
 	 * `models.defineBackend` to build the backend from a few methods. Namespaced
 	 * under `models` (`scope.models.registerBackend(...)`), not a generic global. See #1325.
 	 */
-	registerBackend(kind: 'embedding' | 'generative', id: string, backend: ModelBackend): void {
+	registerBackend(kind: ModelKind, id: string, backend: ModelBackend): void {
 		registerBackendImpl(kind, id, backend);
 	}
 
@@ -125,6 +164,7 @@ export class Models implements ModelsContract {
 			signal?.throwIfAborted();
 			const attemptStart = performance.now();
 			try {
+				assertCapabilities(backend, resolved.requires);
 				const backendOpts = toBackendOpts(opts, signal, accounting);
 				const result = await backend.embed!(input, backendOpts);
 				// Throw on `pending` BEFORE recording success — otherwise we'd write a
@@ -179,6 +219,7 @@ export class Models implements ModelsContract {
 			signal?.throwIfAborted();
 			const attemptStart = performance.now();
 			try {
+				assertCapabilities(backend, resolved.requires);
 				const backendOpts = toBackendOpts(opts, signal, accounting);
 				const result = await backend.generate!(input, backendOpts);
 				if (result.status !== 'completed') throw new ModelPendingNotSupportedError(backend.name);
@@ -223,8 +264,16 @@ export class Models implements ModelsContract {
 		}
 		// First candidate only — mid-stream fallback would mean replaying already-yielded chunks.
 		const backend = resolved.candidates[0];
+		// Checked here, before the iterable exists, so an incapable first candidate from a custom router
+		// is a 400 rather than an error frame inside a 200; #wrapStream checks again on the first next().
+		try {
+			assertCapabilities(backend, resolved.requires);
+		} catch (err) {
+			this.#recordFailure(backend, 'generateStream', opts.model, accounting, opts, startedAt, err);
+			throw err;
+		}
 		const backendOpts = toBackendOpts(opts, signal, accounting);
-		return this.#wrapStream(backend, input, backendOpts, opts, accounting, startedAt);
+		return this.#wrapStream(backend, input, backendOpts, opts, accounting, startedAt, resolved.requires);
 	}
 
 	async *#wrapStream(
@@ -233,11 +282,13 @@ export class Models implements ModelsContract {
 		backendOpts: BackendOpts<GenerateOpts>,
 		opts: GenerateOpts,
 		accounting: AccountingContext,
-		startedAt: number
+		startedAt: number,
+		requires: Capability[]
 	): AsyncIterable<GenerateChunk> {
 		let caught: unknown;
 		let completed = false;
 		try {
+			assertCapabilities(backend, requires);
 			for await (const chunk of backend.generateStream!(input, backendOpts)) {
 				yield chunk;
 			}
@@ -259,6 +310,245 @@ export class Models implements ModelsContract {
 		}
 	}
 
+	/**
+	 * Choose from the closed set `schema` defines, with the distribution over it. A malformed schema or
+	 * state rejects before routing, with no analytics row: nothing was called. With `persist: true` the
+	 * record is committed before the decision is returned: a read-only node rejects before routing, and a
+	 * commit failure rejects without another candidate, so a storage fault never bills a second model
+	 * call. Without it nothing is stored and no `id` is returned, so any node can decide.
+	 */
+	decide<T = unknown>(
+		state: DecideInput,
+		schema: DecisionSchema,
+		opts: RecordedDecideOpts
+	): Promise<RecordedDecision<T>>;
+	decide<T = unknown>(state: DecideInput, schema: DecisionSchema, opts?: DecideOpts): Promise<Decision<T>>;
+	async decide<T = unknown>(state: DecideInput, schema: DecisionSchema, opts: DecideOpts = {}): Promise<Decision<T>> {
+		validateDecisionSchema(schema);
+		stateToText(state);
+		if (opts.persist !== undefined && typeof opts.persist !== 'boolean')
+			throw new DecisionInputError('persist must be a boolean');
+		const persist = opts.persist === true;
+		if (persist) this.#decisionStore.assertWritable('Decisions');
+		// the call and its record share one snapshot of the schema and options; nothing the caller mutates afterwards reaches either
+		const call = snapshotSchema(schema);
+		if (opts.instructions !== undefined && typeof opts.instructions !== 'string')
+			throw new DecisionInputError('instructions must be a string');
+		const instructions = opts.instructions || undefined;
+		const callOpts = { ...opts, instructions, requires: opts.requires ? [...opts.requires] : undefined } as DecideOpts;
+		if (opts.persist !== undefined) delete callOpts.persist;
+		const identity: CallIdentity | undefined = persist
+			? { hash: hashSchema(call), scoring: scoringSchema(call), configHash: getModelsConfigHash() }
+			: undefined;
+		const { accounting, signal } = resolveCallContext(callOpts.signal);
+		const startedAt = performance.now();
+		const requires = buildRequires('decide', callOpts.requires, false);
+		if (wantsNoMatch(call)) {
+			if (!requires.includes('noMatch')) requires.push('noMatch');
+			if (requires.includes('calibrated') && !requires.includes('calibratedNoMatch'))
+				requires.push('calibratedNoMatch');
+		}
+		const resolved = resolveCandidates('decision', callOpts.model, requires);
+		if ('error' in resolved) {
+			this.#recordFailure(resolved.backend, 'decide', callOpts.model, accounting, undefined, startedAt, resolved.error);
+			throw resolved.error;
+		}
+		let firstError: unknown = undefined;
+		let hasError = false;
+		for (const backend of resolved.candidates) {
+			signal?.throwIfAborted();
+			const attemptStart = performance.now();
+			let result: ModelCallResult<DecisionOutput<unknown>>;
+			let decision: Omit<Decision<T>, 'id' | 'usage'>;
+			try {
+				assertCapabilities(backend, resolved.requires);
+				const backendOpts = toBackendOpts(callOpts, signal, accounting);
+				result = await backend.decide!(state, call, backendOpts);
+				if (result.status !== 'completed') throw new ModelPendingNotSupportedError(backend.name);
+				const caps = backend.capabilities();
+				decision = normalizeDecision<T>(
+					call,
+					result.output,
+					backend.name,
+					caps?.calibrated === true,
+					caps?.calibratedNoMatch === true
+				);
+				// A backend may report a single call as uncalibrated; the caller's requirement still holds.
+				if (!decision.calibrated && callOpts.requires?.includes('calibrated'))
+					throw new DecisionContractError(
+						backend.name,
+						"probabilities are not calibrated, but 'calibrated' was required"
+					);
+			} catch (err) {
+				this.#recordFailure(backend, 'decide', callOpts.model, accounting, undefined, attemptStart, err);
+				if (!hasError) {
+					firstError = err;
+					hasError = true;
+				}
+				if (signal?.aborted) throw err;
+				continue;
+			}
+			const callId = this.#record(backend, 'decide', callOpts.model, accounting, undefined, result, attemptStart);
+			if (!identity) return result.usage ? { ...decision, usage: result.usage } : decision;
+			const id = await this.#persistDecision(
+				callId,
+				backend,
+				callOpts.model,
+				instructions,
+				accounting,
+				result.output,
+				identity,
+				decision
+			);
+			return result.usage ? { id, ...decision, usage: result.usage } : { id, ...decision };
+		}
+		throw firstError;
+	}
+
+	/**
+	 * Score `choices` as answers to `input` with a generative backend that implements
+	 * `scoreChoices` (#2838): the decision adapter's likelihood path. Routes `generative` with
+	 * `scoreChoices` required, tries candidates like `embed`, and records one `scoreChoices` row
+	 * per attempt; a `ChoiceScoringUnsupportedError` is recorded as `scoring_unsupported` with the
+	 * usage it consumed. Internal, like `embedWithUsage`: not part of the stable models API.
+	 */
+	async scoreChoices(
+		input: GenerateInput,
+		choices: readonly string[],
+		opts: ScoreChoicesOpts = {}
+	): Promise<ChoiceScores & { usage?: TokenUsage }> {
+		const { accounting, signal } = resolveCallContext(opts.signal);
+		const startedAt = performance.now();
+		const resolved = resolveCandidates('generative', opts.model, buildRequires('scoreChoices', opts.requires, false));
+		if ('error' in resolved) {
+			this.#recordFailure(
+				resolved.backend,
+				'scoreChoices',
+				opts.model,
+				accounting,
+				undefined,
+				startedAt,
+				resolved.error
+			);
+			throw resolved.error;
+		}
+		let firstError: unknown = undefined;
+		let hasError = false;
+		let firstFailure: unknown = undefined;
+		let hasFailure = false;
+		for (const backend of resolved.candidates) {
+			signal?.throwIfAborted();
+			const attemptStart = performance.now();
+			try {
+				const caps = assertCapabilities(backend, resolved.requires);
+				// A router may hand back a backend whose capabilities claim more than it implements;
+				// that is this backend's contract failure, recorded against it, not a crash.
+				if (typeof backend.scoreChoices !== 'function')
+					throw new ServerError(`Backend '${backend.name}' advertises 'scoreChoices' but does not implement it`);
+				const limit = scoringLimit(caps);
+				if (limit !== undefined && choices.length > limit)
+					throw new ChoiceScoringUnsupportedError(
+						`Backend '${backend.name}' scores at most ${limit} choices per call; got ${choices.length}`
+					);
+				const result = await backend.scoreChoices(input, choices, toBackendOpts(opts, signal, accounting));
+				if (result.status !== 'completed') throw new ModelPendingNotSupportedError(backend.name);
+				const logLikelihoods = result.output?.logLikelihoods;
+				if (
+					!Array.isArray(logLikelihoods) ||
+					logLikelihoods.length !== choices.length ||
+					!logLikelihoods.every((x) => typeof x === 'number' && Number.isFinite(x))
+				)
+					throw new ServerError(
+						`Backend '${backend.name}' did not return one finite log-likelihood per choice (${choices.length})`
+					);
+				this.#record(backend, 'scoreChoices', opts.model, accounting, undefined, result, attemptStart);
+				return result.usage ? { logLikelihoods, usage: result.usage } : { logLikelihoods };
+			} catch (err) {
+				// Only this attempt's own decline bills its tokens: the error may travel on as an abort
+				// reason or through the decision adapter, and those rows must not count it again.
+				this.#recordFailure(
+					backend,
+					'scoreChoices',
+					opts.model,
+					accounting,
+					undefined,
+					attemptStart,
+					err,
+					usageFromError(err)
+				);
+				if (!hasError) {
+					firstError = err;
+					hasError = true;
+				}
+				if (!hasFailure && !isChoiceScoringUnsupported(err)) {
+					firstFailure = err;
+					hasFailure = true;
+				}
+				if (signal?.aborted) throw err;
+			}
+		}
+		throw hasFailure ? firstFailure : firstError;
+	}
+
+	async getDecision<T = unknown>(id: string): Promise<DecisionRecord<T> | undefined> {
+		checkDecisionId(id);
+		return (await this.#decisionStore.get(id, resolveCallContext().accounting.tenantId)) as
+			DecisionRecord<T> | undefined;
+	}
+
+	async recordOutcome<T = unknown>(id: string, outcome: OutcomeReport): Promise<DecisionRecord<T>> {
+		checkDecisionId(id);
+		return (await this.#decisionStore.recordOutcome(
+			id,
+			outcome,
+			resolveCallContext().accounting.tenantId
+		)) as DecisionRecord<T>;
+	}
+
+	async #persistDecision<T>(
+		callId: number,
+		backend: ModelBackend,
+		model: string | undefined,
+		instructions: string | undefined,
+		accounting: AccountingContext,
+		output: DecisionOutput<unknown>,
+		identity: CallIdentity,
+		decision: Omit<Decision<T>, 'id' | 'usage'>
+	): Promise<string> {
+		const id = newDecisionId();
+		const at = Date.now();
+		const row: DecisionRow = {
+			id,
+			callId,
+			at,
+			expiresAt: at + DECISION_RETENTION_MS,
+			tenant: accounting.tenantId,
+			app: accounting.app,
+			backend: backend.name,
+			model: model ?? 'default',
+			signature: typeof output.signature === 'string' ? output.signature : undefined,
+			configHash: identity.configHash,
+			instructionsHash: instructions ? hashText(instructions) : undefined,
+			schema: identity.scoring,
+			schemaHash: identity.hash,
+			value: decision.value,
+			probability: decision.probability,
+			distribution: decision.distribution,
+			fields: decision.fields,
+			calibrated: decision.calibrated,
+		};
+		if (decision.noMatch !== undefined) row.noMatch = decision.noMatch;
+		try {
+			await this.#decisionStore.persist(row);
+		} catch (err) {
+			// the fault stays on `cause`: its message can name a data path and this error can reach an HTTP body
+			const error = new DecisionPersistenceError('Decision could not be recorded');
+			(error as Error & { cause?: unknown }).cause = err;
+			throw error;
+		}
+		return id;
+	}
+
 	#record(
 		backend: ModelBackend,
 		method: CallMethod,
@@ -267,9 +557,11 @@ export class Models implements ModelsContract {
 		opts: GenerateOpts | undefined,
 		result: ModelCallResult<unknown> | undefined,
 		startedAt: number
-	): void {
+	): number {
 		const usage = result?.status === 'completed' ? result.usage : undefined;
-		this.#analyticsWriter.write(buildRecord(backend, method, model, accounting, opts, usage, startedAt, true));
+		const id = this.#analyticsWriter.write(
+			buildRecord(backend, method, model, accounting, opts, usage, startedAt, true)
+		);
 		// Also emit aggregate analytics into hdb_raw_analytics so model usage rolls up
 		// into the same per-period analytics that license enforcement and admin
 		// dashboards consume — mirrors the `db-read` pattern in Table.ts. The detailed
@@ -277,10 +569,14 @@ export class Models implements ModelsContract {
 		// Path is the backend name (analogous to tableName for db-read) so dashboards
 		// can break usage down by backend.
 		this.#emit(1, `model-${method}`, backend.name);
-		if (usage) {
-			const tokens = (usage.embeddingTokens ?? 0) + (usage.promptTokens ?? 0) + (usage.completionTokens ?? 0);
-			if (tokens > 0) this.#emit(tokens, `model-${method}-tokens`, backend.name);
-		}
+		this.#emitTokens(method, backend.name, usage);
+		return id;
+	}
+
+	#emitTokens(method: CallMethod, backendName: string, usage: TokenUsage | undefined): void {
+		if (!usage) return;
+		const tokens = (usage.embeddingTokens ?? 0) + (usage.promptTokens ?? 0) + (usage.completionTokens ?? 0);
+		if (tokens > 0) this.#emit(tokens, `model-${method}-tokens`, backendName);
 	}
 
 	#recordFailure(
@@ -290,16 +586,38 @@ export class Models implements ModelsContract {
 		accounting: AccountingContext,
 		opts: GenerateOpts | undefined,
 		startedAt: number,
-		errOrCode: unknown
+		errOrCode: unknown,
+		usage?: TokenUsage
 	): void {
 		const error_code = typeof errOrCode === 'string' ? errOrCode : classifyError(errOrCode);
 		this.#analyticsWriter.write({
-			...buildRecord(backend, method, model, accounting, opts, undefined, startedAt, false),
+			...buildRecord(backend, method, model, accounting, opts, usage, startedAt, false),
 			error_code,
 		});
+		if (backend) this.#emitTokens(method, backend.name, usage);
 	}
 }
 
+function isChoiceScoringUnsupported(err: unknown): boolean {
+	return (err as { name?: string } | null)?.name === 'ChoiceScoringUnsupportedError';
+}
+
+/**
+ * Tokens a declined scoring call consumed (`ChoiceScoringUnsupportedError.usage`), finite counts
+ * only: a completion that came back without log-probabilities was billed, so they land on that
+ * attempt's failure row and in the token metric while the call-count metric stays a count of
+ * successes. No other error's `usage` is read, and no other method's failure row carries usage.
+ */
+function usageFromError(err: unknown): TokenUsage | undefined {
+	if (!isChoiceScoringUnsupported(err)) return undefined;
+	const reported = (err as { usage?: unknown }).usage;
+	if (!reported || typeof reported !== 'object') return undefined;
+	const usage: TokenUsage = {};
+	for (const key of ['promptTokens', 'completionTokens', 'embeddingTokens'] as const)
+		assignFiniteTokenCount(usage, key, (reported as Record<string, unknown>)[key]);
+	return Object.keys(usage).length > 0 ? usage : undefined;
+}
+
 function buildRecord(
 	backend: ModelBackend | undefined,
 	method: CallMethod,
@@ -350,8 +668,26 @@ function inputHasTools(input: GenerateInput): boolean {
 	return typeof input === 'object' && !Array.isArray(input) && Array.isArray(input.tools) && input.tools.length > 0;
 }
 
-type ResolveKind = 'embedding' | 'generative';
-type Resolution = { candidates: ModelBackend[] } | { error: Error; backend: ModelBackend | undefined };
+type Resolution =
+	{ candidates: ModelBackend[]; requires: Capability[] } | { error: Error; backend: ModelBackend | undefined };
+
+/**
+ * The router's list is advisory: a custom router may return a backend that lacks a required
+ * capability, and the facade must not invoke it. Checked immediately before each candidate is
+ * invoked, fallbacks included.
+ */
+function assertCapabilities(backend: ModelBackend, requires: Capability[]): ModelCapabilities | undefined {
+	const caps = backend.capabilities();
+	for (const capability of requires) {
+		if (!caps?.[capability]) throw new ModelCapabilityError(backend.name, capability);
+	}
+	return caps;
+}
+
+export function scoringLimit(caps: ModelCapabilities | undefined): number | undefined {
+	const limit = caps?.maxScoredChoices;
+	return Number.isSafeInteger(limit) && (limit as number) > 0 ? (limit as number) : undefined;
+}
 
 /**
  * Resolve a call to its ordered candidate backends via the active router (#1326),
@@ -381,10 +717,10 @@ function toBackendOpts<TOpts extends { model?: string; signal?: AbortSignal }>(
 	return backendOpts;
 }
 
-function resolveCandidates(kind: ResolveKind, model: string | undefined, requires: Capability[]): Resolution {
+function resolveCandidates(kind: ModelKind, model: string | undefined, requires: Capability[]): Resolution {
 	const logicalName = model ?? 'default';
-	const candidates = getRouter().route({ kind, logicalName, requires });
-	if (candidates.length > 0) return { candidates };
+	const candidates = getRouter().route({ kind, logicalName, requires: [...requires] });
+	if (candidates.length > 0) return { candidates, requires };
 	const primary = getBackend(kind, logicalName);
 	if (!primary) return { error: new ModelBackendNotFoundError(kind, logicalName), backend: undefined };
 	// `caps?.[…]` guards a custom backend whose capabilities() returns nullish — a
@@ -398,6 +734,8 @@ function resolveCandidates(kind: ResolveKind, model: string | undefined, require
 /** Capabilities a call requires: its base method, the caller's `requires`, and `tools` when the input declares them. */
 function buildRequires(base: Capability, requires: Capability[] | undefined, includeTools: boolean): Capability[] {
 	const set = new Set<Capability>([base, ...(requires ?? [])]);
+	// A limit is not a capability; from untyped callers it would read as satisfied by any number.
+	set.delete('maxScoredChoices' as Capability);
 	if (includeTools) set.add('tools');
 	return [...set];
 }
@@ -407,6 +745,7 @@ function classifyError(err: unknown): string {
 		const e = err as { name?: string; code?: string };
 		if (e.name === 'AbortError' || e.code === 'ABORT_ERR') return 'aborted';
 		if (e.name === 'ModelCapabilityError') return 'capability_unsupported';
+		if (e.name === 'ChoiceScoringUnsupportedError') return 'scoring_unsupported';
 		if (e.name === 'ModelBackendNotFoundError') return 'backend_not_found';
 		if (e.name === 'ModelPendingNotSupportedError') return 'pending_unsupported';
 	}
@@ -444,3 +783,7 @@ _assignPackageExport('models', models);
 // The backend-registration API is reachable as `models.registerBackend(...)` /
 // `models.defineBackend(...)` — methods on the `models` singleton above, not generic
 // free globals (#1534). Custom routers install via `models.registerRouter(...)` (#1326).
+
+function checkDecisionId(id: unknown): asserts id is string {
+	if (typeof id !== 'string' || id.length === 0) throw new ClientError('A decision id must be a non-empty string', 400);
+}

package/resources/models/TestBackend.ts

@@ -1,5 +1,13 @@
+import { allowedValues, isObjectSchema } from './decision.ts';
 import type {
 	BackendOpts,
+	ChoiceScores,
+	DecideInput,
+	DecideOpts,
+	DecisionLeaf,
+	DecisionOutcome,
+	DecisionOutput,
+	DecisionSchema,
 	EmbedOpts,
 	GenerateChunk,
 	GenerateInput,
@@ -8,6 +16,7 @@ import type {
 	ModelBackend,
 	ModelCallResult,
 	ModelCapabilities,
+	ScoreChoicesOpts,
 } from './types.ts';
 
 /**
@@ -21,7 +30,16 @@ export class TestBackend implements ModelBackend {
 	readonly name = 'test';
 
 	capabilities(): ModelCapabilities {
-		return { embed: true, generate: true, stream: true, tools: false, adapters: false };
+		return {
+			embed: true,
+			generate: true,
+			stream: true,
+			tools: false,
+			adapters: false,
+			decide: true,
+			calibrated: false,
+			scoreChoices: true,
+		};
 	}
 
 	async embed(input: string | string[], _opts: BackendOpts<EmbedOpts>): Promise<ModelCallResult<Float32Array[]>> {
@@ -49,6 +67,35 @@ export class TestBackend implements ModelBackend {
 		}
 		yield { finishReason: 'stop' };
 	}
+
+	async decide(
+		state: DecideInput,
+		schema: DecisionSchema,
+		_opts: BackendOpts<DecideOpts>
+	): Promise<ModelCallResult<DecisionOutput<unknown>>> {
+		const text = typeof state === 'string' ? state : JSON.stringify(state);
+		const output: DecisionOutput<unknown> = isObjectSchema(schema)
+			? {
+					fields: Object.fromEntries(
+						Object.entries(schema.properties).map(([name, leaf]) => [
+							name,
+							{ distribution: deterministicDistribution(`${text}\n${name}`, leaf) },
+						])
+					),
+				}
+			: { distribution: deterministicDistribution(text, schema) };
+		return { status: 'completed', output, usage: { promptTokens: text.length, latencyMs: 0 } };
+	}
+
+	async scoreChoices(
+		input: GenerateInput,
+		choices: readonly string[],
+		_opts: BackendOpts<ScoreChoicesOpts>
+	): Promise<ModelCallResult<ChoiceScores>> {
+		const text = stringFromInput(input);
+		const logLikelihoods = choices.map((choice) => deterministicVector(`${text}\n${choice}`, 1)[0] * 4);
+		return { status: 'completed', output: { logLikelihoods }, usage: { promptTokens: text.length, latencyMs: 0 } };
+	}
 }
 
 function stringFromInput(input: GenerateInput): string {
@@ -57,6 +104,14 @@ function stringFromInput(input: GenerateInput): string {
 	return messages.map((m) => m.content).join(' ');
 }
 
+/** A complete distribution over the leaf's values, seeded by the text so the same input always decides the same way. */
+function deterministicDistribution(text: string, leaf: DecisionLeaf): DecisionOutcome[] {
+	const values = allowedValues(leaf);
+	const weights = Array.from(deterministicVector(text, values.length), (w) => (w + 1) / 2 + 0.01);
+	const total = weights.reduce((sum, w) => sum + w, 0);
+	return values.map((value, i) => ({ value, probability: weights[i] / total }));
+}
+
 /**
  * Hash text into a deterministic Float32Array of the given dimension.
  *