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

package/resources/models/analyticsTable.ts

@@ -20,7 +20,7 @@ export interface ModelCallRecord {
 	app?: string;
 	model?: string;
 	backend: string;
-	method: 'embed' | 'generate' | 'generateStream';
+	method: 'embed' | 'generate' | 'generateStream' | 'decide' | 'scoreChoices';
 	adapter?: string;
 	conversation_id?: string;
 	prompt_tokens?: number;
@@ -134,15 +134,17 @@ export class ModelCallAnalyticsWriter {
 		this.#cleanupTimer.unref?.();
 	}
 
-	write(record: ModelCallRecord): void {
-		if (this.#stopped) return;
+	write(record: ModelCallRecord): number {
+		const id = getNextMonotonicTime();
+		if (this.#stopped) return id;
 		// id last so a record that accidentally carries an `id` field can't override
 		// the monotonic primary key.
-		this.#buffer.push({ ...record, id: getNextMonotonicTime() });
+		this.#buffer.push({ ...record, id });
 		if (this.#buffer.length >= this.#maxBufferSize) {
 			// Out-of-cadence flush; swallow errors so a failing flush doesn't escape into the caller.
 			this.flush().catch((err) => log.warn?.(`Model-call analytics flush failed: ${err?.message ?? err}`));
 		}
+		return id;
 	}
 
 	async flush(): Promise<void> {

package/resources/models/backendHelpers.ts

@@ -10,12 +10,29 @@
  * in via a constructor type so the thrown errors carry the backend's name
  * for `instanceof` matching in tests.
  */
+import { ServerError } from '../../utility/errors/hdbError.ts';
 import { isUnresolvedEnvVarPlaceholder } from '../../utility/expandEnvVar.ts';
 import type { TokenUsage } from './types.ts';
 
 /** Constructor signature for backend-specific error classes. */
 export type BackendErrorCtor = new (message: string) => Error;
 
+/**
+ * Thrown by a backend's `scoreChoices` for a call it cannot score (#2838), as distinct from a call
+ * that failed: the decision adapter votes instead in `auto` mode, and the facade records the
+ * attempt as `scoring_unsupported`. `usage` carries the tokens the attempt did consume (a
+ * completion that came back without log-probabilities is still billed), so the failure row
+ * accounts for them.
+ */
+export class ChoiceScoringUnsupportedError extends ServerError {
+	declare usage?: TokenUsage;
+	constructor(message: string, usage?: TokenUsage) {
+		super(message);
+		this.name = 'ChoiceScoringUnsupportedError';
+		if (usage) this.usage = usage;
+	}
+}
+
 /**
  * Combine a caller-supplied AbortSignal with a per-call timeout via
  * `AbortSignal.any`. Returns the caller signal directly when no timeout is

package/resources/models/backendRegistry.ts

@@ -1,6 +1,13 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { ServerError } from '../../utility/errors/hdbError.ts';
-import type { DefineBackendSpec, GenerateResult, ModelBackend, ModelCapabilities, ToolCall } from './types.ts';
+import type {
+	DefineBackendSpec,
+	GenerateResult,
+	ModelBackend,
+	ModelCapabilities,
+	ModelKind,
+	ToolCall,
+} from './types.ts';
 
 /**
  * Process-wide model backend registry.
@@ -20,10 +27,11 @@ import type { DefineBackendSpec, GenerateResult, ModelBackend, ModelCapabilities
  * step) lands in Phase 2 alongside the first real backend.
  */
 
-type ModelKind = 'embedding' | 'generative';
-
-const embedding: Map<string, ModelBackend> = new Map();
-const generative: Map<string, ModelBackend> = new Map();
+const registries: Record<ModelKind, Map<string, ModelBackend>> = {
+	embedding: new Map(),
+	generative: new Map(),
+	decision: new Map(),
+};
 
 /** A registration a factory made during construction, deferred to the caller. */
 export interface CapturedInstall {
@@ -54,7 +62,7 @@ function install(kind: ModelKind, logicalName: string, backend: ModelBackend): v
 		else slot.extras.push({ kind, logicalName, backend });
 		return;
 	}
-	(kind === 'embedding' ? embedding : generative).set(logicalName, backend);
+	registries[kind].set(logicalName, backend);
 }
 
 /** Map `logicalName` to a backend for embedding calls. Re-set replaces. */
@@ -67,6 +75,11 @@ export function setGenerative(logicalName: string, backend: ModelBackend): void
 	install('generative', logicalName, backend);
 }
 
+/** Map `logicalName` to a backend for decide calls. Re-set replaces. */
+export function setDecision(logicalName: string, backend: ModelBackend): void {
+	install('decision', logicalName, backend);
+}
+
 /**
  * Build a backend through its normal registration path but return it instead of installing it, so a
  * config reload can install it conditionally. A scratch logical name would be briefly visible
@@ -99,7 +112,7 @@ export function replaceIfCurrent(
 	expected: ModelBackend | undefined,
 	next: ModelBackend
 ): boolean {
-	const map = kind === 'embedding' ? embedding : generative;
+	const map = registries[kind];
 	if (map.get(logicalName) !== expected) return false;
 	map.set(logicalName, next);
 	return true;
@@ -110,7 +123,7 @@ export function replaceIfCurrent(
  * removed. Withdrawing a credential must not delete a slot another writer has since taken over.
  */
 export function removeIfCurrent(kind: ModelKind, logicalName: string, expected: ModelBackend | undefined): boolean {
-	const map = kind === 'embedding' ? embedding : generative;
+	const map = registries[kind];
 	if (map.get(logicalName) !== expected) return false;
 	map.delete(logicalName);
 	return true;
@@ -118,7 +131,7 @@ export function removeIfCurrent(kind: ModelKind, logicalName: string, expected:
 
 /** Non-throwing lookup of the backend mapped to `logicalName` for `kind`, or `undefined`. Used by the router to assemble + filter candidate lists without exceptions. */
 export function getBackend(kind: ModelKind, logicalName: string): ModelBackend | undefined {
-	return (kind === 'embedding' ? embedding : generative).get(logicalName);
+	return registries[kind].get(logicalName);
 }
 
 /**
@@ -127,8 +140,7 @@ export function getBackend(kind: ModelKind, logicalName: string): ModelBackend |
  * caller passes as `opts.model`, not the backend's own `.name`.
  */
 export function listBackends(kind: ModelKind): Array<{ logicalName: string; backend: ModelBackend }> {
-	const map = kind === 'embedding' ? embedding : generative;
-	return [...map.entries()].map(([logicalName, backend]) => ({ logicalName, backend }));
+	return [...registries[kind].entries()].map(([logicalName, backend]) => ({ logicalName, backend }));
 }
 
 /**
@@ -136,7 +148,7 @@ export function listBackends(kind: ModelKind): Array<{ logicalName: string; back
  * Throws `ModelBackendNotFoundError` if no backend is mapped.
  */
 export function resolveEmbedding(logicalName: string = 'default'): ModelBackend {
-	const backend = embedding.get(logicalName);
+	const backend = registries.embedding.get(logicalName);
 	if (!backend) throw new ModelBackendNotFoundError('embedding', logicalName);
 	return backend;
 }
@@ -146,11 +158,21 @@ export function resolveEmbedding(logicalName: string = 'default'): ModelBackend
  * Throws `ModelBackendNotFoundError` if no backend is mapped.
  */
 export function resolveGenerative(logicalName: string = 'default'): ModelBackend {
-	const backend = generative.get(logicalName);
+	const backend = registries.generative.get(logicalName);
 	if (!backend) throw new ModelBackendNotFoundError('generative', logicalName);
 	return backend;
 }
 
+/**
+ * Resolve the decision backend mapped to `logicalName` (default: `'default'`).
+ * Throws `ModelBackendNotFoundError` if no backend is mapped.
+ */
+export function resolveDecision(logicalName: string = 'default'): ModelBackend {
+	const backend = registries.decision.get(logicalName);
+	if (!backend) throw new ModelBackendNotFoundError('decision', logicalName);
+	return backend;
+}
+
 /**
  * Public registration API (#1325).
  *
@@ -170,8 +192,10 @@ export function resolveGenerative(logicalName: string = 'default'): ModelBackend
  * derives them for you, so prefer it.
  */
 export function registerBackend(kind: ModelKind, id: string, backend: ModelBackend): void {
-	if (kind !== 'embedding' && kind !== 'generative')
-		throw new ModelBackendRegistrationError(`kind must be 'embedding' or 'generative', got '${String(kind)}'`);
+	if (kind !== 'embedding' && kind !== 'generative' && kind !== 'decision')
+		throw new ModelBackendRegistrationError(
+			`kind must be 'embedding', 'generative' or 'decision', got '${String(kind)}'`
+		);
 	if (typeof id !== 'string' || id.length === 0)
 		throw new ModelBackendRegistrationError('backend id must be a non-empty string');
 	if (
@@ -185,6 +209,10 @@ export function registerBackend(kind: ModelKind, id: string, backend: ModelBacke
 		if (typeof backend.embed !== 'function')
 			throw new ModelBackendRegistrationError(`embedding backend '${id}' must implement embed()`);
 		setEmbedding(id, backend);
+	} else if (kind === 'decision') {
+		if (typeof backend.decide !== 'function')
+			throw new ModelBackendRegistrationError(`decision backend '${id}' must implement decide()`);
+		setDecision(id, backend);
 	} else {
 		if (typeof backend.generate !== 'function' && typeof backend.generateStream !== 'function')
 			throw new ModelBackendRegistrationError(
@@ -196,7 +224,8 @@ export function registerBackend(kind: ModelKind, id: string, backend: ModelBacke
 
 /**
  * Build a `ModelBackend` from just the methods it implements. `capabilities()`
- * is derived from which of `embed` / `generate` / `generateStream` are present;
+ * is derived from which of `embed` / `generate` / `generateStream` / `decide` /
+ * `scoreChoices` are present;
  * `tools` and `adapters` aren't inferable from method presence, so pass them
  * explicitly (both default `false`). Lowers the bar from authoring a class to
  * supplying a function — pair with `registerBackend`. See #1325.
@@ -204,16 +233,34 @@ export function registerBackend(kind: ModelKind, id: string, backend: ModelBacke
 export function defineBackend(spec: DefineBackendSpec): ModelBackend {
 	if (!spec || typeof spec.name !== 'string' || spec.name.length === 0)
 		throw new ModelBackendRegistrationError('defineBackend requires a non-empty name');
-	const { name, embed, generate, generateStream, tools = false, adapters = false } = spec;
+	const {
+		name,
+		embed,
+		generate,
+		generateStream,
+		decide,
+		scoreChoices,
+		tools = false,
+		adapters = false,
+		calibrated = false,
+		structuredOutput = false,
+		noMatch = false,
+		calibratedNoMatch = false,
+		maxScoredChoices,
+	} = spec;
 	// Gate on function-ness, not truthiness: a non-function value (`generate: 'oops'`)
 	// must be rejected at definition time, not assigned and crash at call time.
 	const hasEmbed = typeof embed === 'function';
 	const hasGenerate = typeof generate === 'function';
 	const hasStream = typeof generateStream === 'function';
-	if (!hasEmbed && !hasGenerate && !hasStream)
+	const hasDecide = typeof decide === 'function';
+	const hasScore = typeof scoreChoices === 'function';
+	if (!hasEmbed && !hasGenerate && !hasStream && !hasDecide && !hasScore)
 		throw new ModelBackendRegistrationError(
-			`backend '${name}' must implement at least one of embed / generate / generateStream (as functions)`
+			`backend '${name}' must implement at least one of embed / generate / generateStream / decide / scoreChoices (as functions)`
 		);
+	if (maxScoredChoices !== undefined && !(Number.isSafeInteger(maxScoredChoices) && maxScoredChoices > 0))
+		throw new ModelBackendRegistrationError(`backend '${name}': maxScoredChoices must be a positive integer`);
 	const capabilities: ModelCapabilities = Object.freeze({
 		embed: hasEmbed,
 		// A stream-only backend gains generate() via the synthesis below.
@@ -221,11 +268,20 @@ export function defineBackend(spec: DefineBackendSpec): ModelBackend {
 		stream: hasStream,
 		tools,
 		adapters,
+		decide: hasDecide,
+		calibrated: hasDecide && calibrated,
+		scoreChoices: hasScore,
+		structuredOutput: (hasGenerate || hasStream) && structuredOutput,
+		noMatch: hasDecide && noMatch,
+		calibratedNoMatch: hasDecide && noMatch && calibratedNoMatch,
+		...(hasScore && maxScoredChoices !== undefined ? { maxScoredChoices } : {}),
 	});
 	const backend: ModelBackend = { name, capabilities: () => capabilities };
 	if (hasEmbed) backend.embed = embed;
 	if (hasGenerate) backend.generate = generate;
 	if (hasStream) backend.generateStream = generateStream;
+	if (hasDecide) backend.decide = decide;
+	if (hasScore) backend.scoreChoices = scoreChoices;
 	// Stream-only generative backend: synthesize generate() by draining the stream,
 	// so a plain models.generate() works without the backend implementing both.
 	if (hasStream && !hasGenerate) backend.generate = synthesizeGenerateFromStream(generateStream!);
@@ -261,8 +317,7 @@ function synthesizeGenerateFromStream(
 
 /** Remove all registrations. Test-only hygiene. */
 export function clearRegistry(): void {
-	embedding.clear();
-	generative.clear();
+	for (const map of Object.values(registries)) map.clear();
 }
 
 export class ModelBackendNotFoundError extends ServerError {

package/resources/models/bootstrap.ts

@@ -34,6 +34,7 @@ import { registerOllamaBackend, type OllamaBackendConfig } from '../../component
 import { registerOpenAIBackend, type OpenAIBackendConfig } from '../../components/openai/index.ts';
 import { registerAnthropicBackend, type AnthropicBackendConfig } from '../../components/anthropic/index.ts';
 import { registerBedrockBackend, type BedrockBackendConfig } from '../../components/bedrock/index.ts';
+import { setModelsConfigHash } from './decisionStore.ts';
 import { isAbsolute, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
@@ -48,7 +49,8 @@ import {
 } from './backendRegistry.ts';
 import { getSharedRootConfigWatcher, RootConfigWatcher } from '../../config/RootConfigWatcher.ts';
 import { validateModelsBlock } from '../../validation/configValidator.ts';
-import type { ModelBackend } from './types.ts';
+import { registerGenerativeDecisionBackend, type GenerativeDecisionConfig } from './generativeDecision.ts';
+import type { ModelBackend, ModelKind } from './types.ts';
 
 /**
  * Field names treated as credentials. When present in config as a literal
@@ -58,8 +60,6 @@ import type { ModelBackend } from './types.ts';
  */
 const CREDENTIAL_FIELDS = new Set(['apiKey']);
 
-type ModelKind = 'embedding' | 'generative';
-
 interface ModelEntry {
 	backend?: string;
 	host?: string;
@@ -71,6 +71,13 @@ interface ModelEntry {
 	organization?: string;
 	// bedrock
 	region?: string;
+	// generative decision adapter
+	generative?: string;
+	samples?: number;
+	concurrency?: number;
+	temperature?: number;
+	scoring?: 'auto' | 'vote' | 'score';
+	requireStructuredOutput?: boolean;
 	/** Ordered fallback group: other logical names tried, in order, after this one (#1326). */
 	fallback?: string[];
 }
@@ -78,6 +85,7 @@ interface ModelEntry {
 interface ModelsConfig {
 	embedding?: Record<string, ModelEntry>;
 	generative?: Record<string, ModelEntry>;
+	decision?: Record<string, ModelEntry>;
 }
 
 interface RootConfig {
@@ -85,14 +93,33 @@ interface RootConfig {
 }
 
 type BackendRegisterFn = (args: { logicalName: string; kind: ModelKind; config: object }) => void | Promise<void>;
+type ProviderKind = Exclude<ModelKind, 'decision'>;
 
+// The provider casts hold because `builtinServesKind` refuses a `decision` entry before any factory runs.
 const FACTORIES: Record<string, BackendRegisterFn> = {
-	ollama: (args) => registerOllamaBackend({ ...args, config: args.config as OllamaBackendConfig }),
-	openai: (args) => registerOpenAIBackend({ ...args, config: args.config as OpenAIBackendConfig }),
-	anthropic: (args) => registerAnthropicBackend({ ...args, config: args.config as AnthropicBackendConfig }),
-	bedrock: (args) => registerBedrockBackend({ ...args, config: args.config as BedrockBackendConfig }),
+	ollama: (args) =>
+		registerOllamaBackend({ ...args, kind: args.kind as ProviderKind, config: args.config as OllamaBackendConfig }),
+	openai: (args) =>
+		registerOpenAIBackend({ ...args, kind: args.kind as ProviderKind, config: args.config as OpenAIBackendConfig }),
+	anthropic: (args) =>
+		registerAnthropicBackend({
+			...args,
+			kind: args.kind as ProviderKind,
+			config: args.config as AnthropicBackendConfig,
+		}),
+	bedrock: (args) =>
+		registerBedrockBackend({ ...args, kind: args.kind as ProviderKind, config: args.config as BedrockBackendConfig }),
+	generative: (args) => registerGenerativeDecisionBackend({ ...args, config: args.config as GenerativeDecisionConfig }),
 };
 
+// The provider factories treat every non-embedding kind as generative, so a `decision` entry naming
+// one would silently register a backend with no `decide`; the adapter is the only built-in for that kind.
+const DECISION_BUILTINS = new Set(['generative']);
+
+function builtinServesKind(backend: string, kind: ModelKind): boolean {
+	return (kind === 'decision') === DECISION_BUILTINS.has(backend);
+}
+
 // What the config projection currently has installed, per kind+logicalName slot. `backend` is the
 // exact instance this module put in the registry: reload swaps compare against it, so a
 // programmatic `registerBackend` that overrode a config entry keeps its documented precedence, and
@@ -106,6 +133,7 @@ interface InstalledSlot {
 	entryJson: string;
 	/** The entry's fallback group as applied, so a retained backend keeps its routing. */
 	fallback?: string[];
+	configJson?: string;
 	/** Whether the entry's backend is a built-in. Module-backed entries are restart-managed: reload
 	 * refuses to add, change, OR remove them, so a rename cannot half-apply as a bare removal. */
 	builtin?: boolean;
@@ -223,6 +251,7 @@ interface DesiredEntry {
 	logicalName: string;
 	entry: ModelEntry;
 	entryJson: string;
+	configJson?: string;
 }
 
 function collectKind(
@@ -291,6 +320,7 @@ function publishEntry(
 	const builtin = Boolean(FACTORIES[entry.backend as string]);
 	if (replaceIfCurrent(kind, logicalName, expected, backend)) {
 		installedSlots.set(key, {
+			configJson: desiredEntry.configJson,
 			kind,
 			logicalName,
 			backend,
@@ -303,6 +333,7 @@ function publishEntry(
 		// Record the ask with no installed instance, so unchanged reloads skip instead of
 		// re-losing this swap every apply; installed helpers stay recorded and removable.
 		installedSlots.set(key, {
+			configJson: desiredEntry.configJson,
 			kind,
 			logicalName,
 			entryJson,
@@ -339,6 +370,7 @@ async function applyModels(block: ModelsConfig | null | undefined, isBoot: boole
 	const presentKeys = new Set<string>();
 	collectKind('embedding', block?.embedding, desired, presentKeys);
 	collectKind('generative', block?.generative, desired, presentKeys);
+	collectKind('decision', block?.decision, desired, presentKeys);
 
 	const staged = new Map<string, { desiredEntry: DesiredEntry; backend: ModelBackend; extras: CapturedInstall[] }>();
 	const failedKeys = new Set<string>();
@@ -358,6 +390,13 @@ async function applyModels(block: ModelsConfig | null | undefined, isBoot: boole
 		// the incoming backend AND a currently-installed module-backed slot: a module→built-in rewrite
 		// is still a change of a restart-managed entry, so it must not live-replace the module (which
 		// would drop its helpers with none of the disposal a restart performs).
+		if (FACTORIES[entry.backend as string] && !builtinServesKind(entry.backend as string, kind)) {
+			harperLogger.error(
+				`models.${kind}.${logicalName}: backend '${entry.backend}' cannot serve ${kind} entries; skipping`
+			);
+			failedKeys.add(key);
+			continue;
+		}
 		if (!isBoot && (!FACTORIES[entry.backend as string] || slot?.builtin === false)) {
 			harperLogger.warn(
 				`models.${kind}.${logicalName}: module-backed entries require a restart to add or change; ` +
@@ -378,6 +417,7 @@ async function applyModels(block: ModelsConfig | null | undefined, isBoot: boole
 			// (env var unset) pass through unchanged — backend's required-field
 			// validation catches them with a meaningful error.
 			const config = expandEnvVarsDeep(entry);
+			desiredEntry.configJson = JSON.stringify(config);
 			const { backend, extras } = await constructBackend(kind, logicalName, async () => {
 				const builtin = FACTORIES[entry.backend as string];
 				if (builtin) {
@@ -462,6 +502,16 @@ async function applyModels(block: ModelsConfig | null | undefined, isBoot: boole
 			setFallbackGroup(slot.kind, slot.logicalName, slot.fallback);
 		}
 	}
+	setModelsConfigHash(installedConfiguration());
+}
+
+function installedConfiguration(): Record<string, unknown> | undefined {
+	const configuration: Record<string, unknown> = {};
+	for (const [key, slot] of installedSlots) {
+		if (slot.backend)
+			configuration[key] = JSON.parse(slot.configJson ?? JSON.stringify(expandEnvVarsDeep(JSON.parse(slot.entryJson))));
+	}
+	return Object.keys(configuration).length > 0 ? configuration : undefined;
 }
 
 // ── Hot reload wiring ─────────────────────────────────────────────────────────

package/resources/models/decideHook.ts

@@ -0,0 +1,135 @@
+import { ClientError } from '../../utility/errors/hdbError.ts';
+import { isAllowedValue } from './decision.ts';
+import {
+	runWriteJobs,
+	sanitizedHookError,
+	sourceState,
+	writeHookApplies,
+	type WriteHook,
+	type WriteHookContext,
+} from './embedHook.ts';
+import type { DecideInput, DecideOpts, Decision, DecisionLeaf } from './types.ts';
+
+export type DecideConfig = {
+	source: string;
+	model: string;
+	confidence?: string;
+	/** A nullable `String` attribute that receives the durable `Decision.id`; the decision is recorded only when this is named (#2852). */
+	decision?: string;
+	instructions?: string;
+	/** Resolved from the attribute type and the directive arguments, and validated, when the schema loads. */
+	schema: DecisionLeaf;
+};
+
+export type DecideAttribute = {
+	name: string;
+	decide: DecideConfig;
+};
+
+/**
+ * `null` clears the attribute, its confidence and its decision id; `probability` is required when the
+ * directive names a confidence attribute. `id` must come from a `models.decide` call; an override for a
+ * directive with a `decision` attribute gets it from a `models.decide` call made with `persist: true`.
+ */
+export type DeciderResult = { value: unknown; probability?: number; id?: string };
+export type Decider = (record: any, hook?: WriteHookContext) => Promise<DeciderResult | null | undefined>;
+
+type DecideFn = (state: DecideInput, schema: DecisionLeaf, opts: DecideOpts) => Promise<Decision>;
+
+// Lazy-imported so this module can be unit-tested without loading the transaction
+// stack `Models.ts` pulls in. Overridable via `__setDecideFnForTest`.
+let _decideFn: DecideFn | undefined;
+function resolveDecideFn(): DecideFn {
+	if (_decideFn) return _decideFn;
+	const { Models } = require('#src/resources/models/Models'); // eslint-disable-line @typescript-eslint/no-var-requires
+	const models = new Models();
+	_decideFn = (state, schema, opts) => models.decide(state, schema, opts);
+	return _decideFn;
+}
+
+/** Test seam: override the decide function. Pass `undefined` to reset to `Models.decide`. */
+export function __setDecideFnForTest(fn: DecideFn | undefined): void {
+	_decideFn = fn;
+}
+
+export function createDefaultDecider(config: DecideConfig): Decider {
+	const { source, model, instructions, schema } = config;
+	const persist = Boolean(config.decision);
+	return async (record: any, hook?: WriteHookContext): Promise<DeciderResult | null> => {
+		const sourceValue = record?.[source];
+		if (sourceValue == null) return null;
+		// An object source is program state the primitive serializes itself; anything else is text.
+		const state: DecideInput = typeof sourceValue === 'object' ? sourceValue : String(sourceValue);
+		const decision = await resolveDecideFn()(state, schema, { model, instructions, signal: hook?.signal, persist });
+		return { value: decision.value, probability: decision.probability, id: decision.id };
+	};
+}
+
+export function buildDecideBefore(
+	record: any,
+	context: any,
+	options: any,
+	decideAttributes: DecideAttribute[] | undefined,
+	deciders: Record<string, Decider>
+): WriteHook | undefined {
+	if (!decideAttributes || decideAttributes.length === 0) return undefined;
+	const applies = writeHookApplies(record, context, options);
+	if (record && typeof record === 'object' && options?.isNotification !== true && context?.alreadyLogged !== true)
+		for (const attr of decideAttributes) {
+			const { decision, source } = attr.decide;
+			if (!decision || !(decision in record)) continue;
+			const state = applies ? sourceState(record, source) : 'absent';
+			// An outcome report trusts this id, so only a write that derives or clears it may carry it.
+			if (state !== 'value' && state !== 'null')
+				throw new ClientError(
+					`"${decision}" is written by @decide on "${attr.name}"; a write may carry it only with a value for "${source}"`,
+					400
+				);
+		}
+	if (!applies) return undefined;
+	let present = false;
+	for (const attr of decideAttributes) if (sourceState(record, attr.decide?.source) !== 'absent') present = true;
+	if (!present) return undefined;
+	return (signal) =>
+		runWriteJobs(
+			decideAttributes.map((attr) => async (jobSignal) => {
+				const { source, confidence, decision, schema } = attr.decide;
+				const state = sourceState(record, source);
+				if (state === 'absent' || state === 'op') return;
+				const clear = () => {
+					record[attr.name] = null;
+					if (confidence) record[confidence] = null;
+					if (decision) record[decision] = null;
+				};
+				if (state === 'null') return clear();
+				const decider = deciders[attr.name];
+				// Committing the source without its pair would be indistinguishable from a decision later.
+				if (!decider) throw new Error(`No decider is registered for the @decide attribute "${attr.name}"`);
+				let result: DeciderResult | null | undefined;
+				try {
+					result = await decider(record, { signal: jobSignal });
+				} catch (err) {
+					// An aborted job failed because a sibling did; only that failure is worth a log line.
+					throw sanitizedHookError('Decider', 'decision', attr.name, err, !jobSignal.aborted);
+				}
+				if (result == null) return clear();
+				// The facade validates `models.decide` output; an author override is checked here so the
+				// stored pair keeps the closed-set guarantee a query relies on.
+				if (!isAllowedValue(schema, result.value))
+					throw new Error(`Decider for attribute "${attr.name}" returned a value outside its @decide set`);
+				if (confidence) {
+					const probability = result.probability;
+					if (!(typeof probability === 'number' && probability >= 0 && probability <= 1))
+						throw new Error(
+							`Decider for attribute "${attr.name}" must return a probability in [0, 1] for its confidence attribute "${confidence}"`
+						);
+					record[attr.name] = result.value;
+					record[confidence] = probability;
+				} else {
+					record[attr.name] = result.value;
+				}
+				if (decision) record[decision] = typeof result.id === 'string' && result.id !== '' ? result.id : null;
+			}),
+			signal
+		);
+}