@open-mercato/ai-assistant 0.10.1-develop.7688.1.8bbd70dcdf → 0.10.1-develop.7690.1.9d41ec4115

package/src/modules/ai_assistant/lib/decision-model-registry.ts

@@ -0,0 +1,108 @@
+import type { DecisionModelAdapter } from '@open-mercato/shared/lib/ai/decision-model'
+import type { EnvLookup } from '@open-mercato/shared/lib/ai/llm-provider'
+import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
+import { createFixtureDecisionAdapter } from './decision-adapters/fixture'
+import { createOpenRouterDecisionAdapter } from './decision-adapters/openrouter'
+
+const PROVIDER_ENV = 'OM_DECISION_PROVIDER'
+const MODEL_ENV = 'OM_DECISION_MODEL'
+const FIXTURE_ENABLED_ENV = 'OM_DECISION_FIXTURE_ENABLED'
+const FIXTURE_ADAPTER_ID = 'fixture'
+
+/** @experimental Why no decision model adapter could be resolved. */
+export type DecisionModelUnavailableReason =
+  | 'not_configured'
+  | 'unknown_provider'
+  | 'credentials_missing'
+  | 'model_missing'
+  | 'fixture_disabled'
+
+/** @experimental Outcome of resolving the active decision model adapter from env. */
+export type DecisionModelResolution =
+  | { ok: true; adapter: DecisionModelAdapter; modelId: string }
+  | { ok: false; reason: DecisionModelUnavailableReason }
+
+/** @experimental Pure, instance-scoped registry of decision model adapters. */
+export interface DecisionModelRegistry {
+  /** Registers an adapter. Idempotent by id: re-registering an id replaces the previous entry in place. */
+  register(adapter: DecisionModelAdapter): void
+  get(id: string): DecisionModelAdapter | undefined
+  /** Registered adapters in registration order. */
+  list(): DecisionModelAdapter[]
+  /**
+   * Resolves the adapter and model from `OM_DECISION_PROVIDER`,
+   * `OM_DECISION_<MODULE>_MODEL` and `OM_DECISION_MODEL`.
+   */
+  resolve(input?: { moduleId?: string; env?: EnvLookup }): DecisionModelResolution
+}
+
+/** Env key of the per-module model override, e.g. `workflows` → `OM_DECISION_WORKFLOWS_MODEL`. */
+export function decisionModuleModelEnvKey(moduleId: string): string {
+  return `OM_DECISION_${moduleId.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_MODEL`
+}
+
+/** True when the fixture adapter is opted in and the process is not running in production. */
+export function isDecisionFixtureEnabled(env: EnvLookup): boolean {
+  return parseBooleanToken(env[FIXTURE_ENABLED_ENV]) === true && env.NODE_ENV !== 'production'
+}
+
+function readTrimmed(env: EnvLookup, key: string): string | undefined {
+  const value = env[key]
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  return trimmed ? trimmed : undefined
+}
+
+function normalizeId(id: string): string {
+  return id.trim().toLowerCase()
+}
+
+/**
+ * Creates a decision model registry with its built-in adapters registered:
+ * `openrouter` always, `fixture` only when `isDecisionFixtureEnabled` holds
+ * for the creation env.
+ *
+ * @experimental
+ */
+export function createDecisionModelRegistry(input?: { env?: EnvLookup }): DecisionModelRegistry {
+  const creationEnv = input?.env
+  const adapters = new Map<string, DecisionModelAdapter>()
+
+  const registry: DecisionModelRegistry = {
+    register(adapter) {
+      adapters.set(normalizeId(adapter.id), adapter)
+    },
+    get(id) {
+      return adapters.get(normalizeId(id))
+    },
+    list() {
+      return Array.from(adapters.values())
+    },
+    resolve(options) {
+      const lookup = options?.env ?? creationEnv ?? process.env
+      const providerId = readTrimmed(lookup, PROVIDER_ENV)
+      if (!providerId) return { ok: false, reason: 'not_configured' }
+      const normalizedProvider = normalizeId(providerId)
+      const adapter = adapters.get(normalizedProvider)
+      if (!adapter) {
+        return {
+          ok: false,
+          reason: normalizedProvider === FIXTURE_ADAPTER_ID ? 'fixture_disabled' : 'unknown_provider',
+        }
+      }
+      if (!adapter.isConfigured(lookup)) return { ok: false, reason: 'credentials_missing' }
+      const moduleModel = options?.moduleId
+        ? readTrimmed(lookup, decisionModuleModelEnvKey(options.moduleId))
+        : undefined
+      const modelId = moduleModel ?? readTrimmed(lookup, MODEL_ENV)
+      if (!modelId) return { ok: false, reason: 'model_missing' }
+      return { ok: true, adapter, modelId }
+    },
+  }
+
+  registry.register(createOpenRouterDecisionAdapter())
+  if (isDecisionFixtureEnabled(creationEnv ?? process.env)) {
+    registry.register(createFixtureDecisionAdapter())
+  }
+  return registry
+}

package/src/modules/ai_assistant/lib/decision-model-schemas.ts

@@ -0,0 +1,224 @@
+/**
+ * Zod schemas and response normalization for the decision model port.
+ *
+ * The port types live in `@open-mercato/shared/lib/ai/decision-model` (types
+ * only); these schemas are their runtime counterpart and stay internal to
+ * `ai-assistant`. A type-level test keeps the two from drifting.
+ *
+ * @see .ai/specs/2026-10-06-ai-decision-model-port.md
+ */
+
+import { z } from 'zod'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type {
+  DecisionAnswer,
+  DecisionErrorCode,
+  DecisionQuestion,
+  DecisionRequest,
+} from '@open-mercato/shared/lib/ai/decision-model'
+
+const decisionKeySchema = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/).refine((key) => key !== '__proto__', {
+  message: 'Reserved key',
+})
+
+export const decisionChoiceQuestionSchema = z.object({
+  type: z.literal('choice'),
+  instructions: z.string().min(1).max(4000),
+  options: z.array(z.object({ key: decisionKeySchema, criteria: z.string().min(1).max(500) }))
+    .min(2).max(64)
+    .refine((options) => new Set(options.map((option) => option.key)).size === options.length, {
+      message: 'Option keys must be unique',
+    }),
+})
+
+export const decisionScoreQuestionSchema = z.object({
+  type: z.literal('score'),
+  instructions: z.string().min(1).max(4000),
+  levels: z.array(z.string().min(1).max(500)).min(2).max(16),
+})
+
+export const decisionBinaryQuestionSchema = z.object({
+  type: z.literal('binary'),
+  instructions: z.string().min(1).max(4000),
+  criteria: z.object({ true: z.string().min(1).max(500), false: z.string().min(1).max(500) }),
+})
+
+export const decisionQuestionSchema = z.discriminatedUnion('type', [
+  decisionChoiceQuestionSchema,
+  decisionScoreQuestionSchema,
+  decisionBinaryQuestionSchema,
+])
+
+export const decisionRequestSchema = z.object({
+  state: z.unknown(),
+  questions: z.unknown()
+    .refine((raw) => !(typeof raw === 'object' && raw !== null && Object.prototype.hasOwnProperty.call(raw, '__proto__')), {
+      message: 'Reserved question name',
+    })
+    .pipe(z.record(decisionKeySchema, decisionQuestionSchema))
+    .refine((questions) => Object.keys(questions).length >= 1 && Object.keys(questions).length <= 8, {
+      message: 'Between 1 and 8 questions are required',
+    }),
+  sessionId: z.string().max(256).optional(),
+})
+
+/**
+ * Error thrown by adapters and internal helpers. The service catches it and
+ * turns it into the closed `{ ok: false, error }` result; it never reaches
+ * consumers.
+ */
+export class DecisionModelError extends Error {
+  readonly code: DecisionErrorCode
+  readonly httpStatus?: number
+
+  constructor(code: DecisionErrorCode, message: string, httpStatus?: number) {
+    super(`[internal] ${message}`)
+    this.name = 'DecisionModelError'
+    this.code = code
+    this.httpStatus = httpStatus
+  }
+}
+
+export const PROBABILITY_SUM_TOLERANCE = 0.02
+
+const EXACT_SUM_EPSILON = 1e-9
+
+const logger = createLogger('ai_assistant').child({ component: 'decision-model' })
+
+function logNormalized(questionName: string, sum: number): void {
+  try {
+    logger.debug('Normalized decision probabilities', { questionName, sum })
+  } catch {
+    return
+  }
+}
+
+const probabilitySchema = z.number().finite().min(0).max(1)
+
+const rawChoiceAnswerSchema = z.object({
+  type: z.literal('choice'),
+  value: z.string(),
+  probabilities: z.array(z.object({ key: z.string(), probability: probabilitySchema })),
+  confidence: probabilitySchema.nullable(),
+})
+
+const rawScoreAnswerSchema = z.object({
+  type: z.literal('score'),
+  probabilities: z.array(z.object({ level: z.number().int(), probability: probabilitySchema })),
+  confidence: probabilitySchema.nullable(),
+})
+
+const rawBinaryAnswerSchema = z.object({
+  type: z.literal('binary'),
+  probability: probabilitySchema,
+})
+
+/**
+ * What an adapter hands back per question before the port validates it. For
+ * `score`, the port derives `value` and `level` itself, so adapters only
+ * supply the distribution.
+ */
+export const rawDecisionAnswerSchema = z.discriminatedUnion('type', [
+  rawChoiceAnswerSchema,
+  rawScoreAnswerSchema,
+  rawBinaryAnswerSchema,
+])
+
+export type RawDecisionAnswer = z.infer<typeof rawDecisionAnswerSchema>
+
+function invalidResponse(questionName: string, reason: string): DecisionModelError {
+  return new DecisionModelError('invalid_response', `Decision answer "${questionName}" ${reason}`)
+}
+
+function normalizeDistribution(questionName: string, probabilities: number[]): number[] {
+  const sum = probabilities.reduce((total, probability) => total + probability, 0)
+  if (Math.abs(sum - 1) > PROBABILITY_SUM_TOLERANCE) {
+    throw invalidResponse(questionName, 'has probabilities that do not sum to 1')
+  }
+  if (Math.abs(sum - 1) > EXACT_SUM_EPSILON) logNormalized(questionName, sum)
+  return probabilities.map((probability) => probability / sum)
+}
+
+function argmax(values: number[]): number {
+  return values.reduce((bestIndex, value, index) => (value > values[bestIndex] ? index : bestIndex), 0)
+}
+
+function normalizeChoice(
+  questionName: string,
+  question: Extract<DecisionQuestion, { type: 'choice' }>,
+  answer: z.infer<typeof rawChoiceAnswerSchema>,
+): DecisionAnswer {
+  const byKey = new Map(answer.probabilities.map((entry) => [entry.key, entry.probability]))
+  const requestKeys = question.options.map((option) => option.key)
+  if (byKey.size !== answer.probabilities.length || byKey.size !== requestKeys.length || requestKeys.some((key) => !byKey.has(key))) {
+    throw invalidResponse(questionName, 'does not cover exactly the requested options')
+  }
+  if (!byKey.has(answer.value)) {
+    throw invalidResponse(questionName, 'selected an option that was not requested')
+  }
+  const normalized = normalizeDistribution(questionName, requestKeys.map((key) => byKey.get(key) ?? 0))
+  return {
+    type: 'choice',
+    value: answer.value,
+    probabilities: requestKeys.map((key, index) => ({ key, probability: normalized[index] })),
+    confidence: answer.confidence,
+  }
+}
+
+function normalizeScore(
+  questionName: string,
+  question: Extract<DecisionQuestion, { type: 'score' }>,
+  answer: z.infer<typeof rawScoreAnswerSchema>,
+): DecisionAnswer {
+  const byLevel = new Map(answer.probabilities.map((entry) => [entry.level, entry.probability]))
+  const levelCount = question.levels.length
+  const levelIndexes = question.levels.map((_, index) => index)
+  if (byLevel.size !== answer.probabilities.length || byLevel.size !== levelCount || levelIndexes.some((level) => !byLevel.has(level))) {
+    throw invalidResponse(questionName, 'does not cover exactly the requested levels')
+  }
+  const normalized = normalizeDistribution(questionName, levelIndexes.map((level) => byLevel.get(level) ?? 0))
+  const value = normalized.reduce((total, probability, level) => total + probability * level, 0)
+  return {
+    type: 'score',
+    value,
+    level: argmax(normalized),
+    probabilities: levelIndexes.map((level) => ({ level, probability: normalized[level] })),
+    confidence: answer.confidence,
+  }
+}
+
+/**
+ * Validates adapter output against the request and returns port answers:
+ * every question answered with a matching type, probabilities in [0, 1],
+ * key/level sets equal to the request's, the chosen value among them, and
+ * `choice`/`score` distributions summing to 1 ± 0.02 (then normalized to
+ * exactly 1). `probabilities` come back in request order. Any violation
+ * throws `DecisionModelError('invalid_response')`.
+ */
+export function normalizeDecisionAnswers(
+  request: DecisionRequest,
+  rawAnswers: Record<string, unknown>,
+): Record<string, DecisionAnswer> {
+  const answers: Record<string, DecisionAnswer> = {}
+  for (const [questionName, question] of Object.entries(request.questions)) {
+    if (!Object.prototype.hasOwnProperty.call(rawAnswers, questionName)) {
+      throw invalidResponse(questionName, 'is missing')
+    }
+    const parsed = rawDecisionAnswerSchema.safeParse(rawAnswers[questionName])
+    if (!parsed.success) {
+      throw invalidResponse(questionName, 'has an invalid shape')
+    }
+    const answer = parsed.data
+    if (answer.type !== question.type) {
+      throw invalidResponse(questionName, 'has a type that does not match the question')
+    }
+    if (answer.type === 'choice' && question.type === 'choice') {
+      answers[questionName] = normalizeChoice(questionName, question, answer)
+    } else if (answer.type === 'score' && question.type === 'score') {
+      answers[questionName] = normalizeScore(questionName, question, answer)
+    } else if (answer.type === 'binary') {
+      answers[questionName] = { type: 'binary', probability: answer.probability }
+    }
+  }
+  return answers
+}

package/src/modules/ai_assistant/lib/decision-model-service.ts

@@ -0,0 +1,297 @@
+import type {
+  DecisionErrorCode,
+  DecisionRequest,
+  DecisionResult,
+} from '@open-mercato/shared/lib/ai/decision-model'
+import type { EnvLookup } from '@open-mercato/shared/lib/ai/llm-provider'
+import { countTokens } from '@open-mercato/shared/lib/ai/token-count'
+import { createLogger, type Logger } from '@open-mercato/shared/lib/logger'
+import { parseNumberWithDefault } from '@open-mercato/shared/lib/number'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import {
+  createDecisionModelRegistry,
+  type DecisionModelRegistry,
+  type DecisionModelUnavailableReason,
+} from './decision-model-registry'
+import { DecisionModelError, decisionRequestSchema, normalizeDecisionAnswers } from './decision-model-schemas'
+
+export const DEFAULT_DECISION_TIMEOUT_MS = 5000
+export const MAX_DECISION_TIMEOUT_MS = 30000
+export const DEFAULT_DECISION_MAX_INPUT_TOKENS = 24000
+
+const MAX_INPUT_TOKENS_ENV = 'OM_DECISION_MAX_INPUT_TOKENS'
+
+/** @experimental Availability of the decision model for an optional module. */
+export interface DecisionModelAvailability {
+  available: boolean
+  provider?: string
+  model?: string
+  reason?: DecisionModelUnavailableReason
+}
+
+/** @experimental Closed error shape returned by `decide`. */
+export interface DecisionModelDecideError {
+  code: DecisionErrorCode
+  message: string
+  httpStatus?: number
+}
+
+/** @experimental Discriminated result of `decide`; it never throws. */
+export type DecisionModelDecideResult =
+  | { ok: true; result: DecisionResult }
+  | { ok: false; error: DecisionModelDecideError }
+
+/** @experimental Input of `decide`. */
+export interface DecisionModelDecideInput {
+  request: DecisionRequest
+  moduleId?: string
+  timeoutMs?: number
+  signal?: AbortSignal
+}
+
+/** @experimental DI service `decisionModelService`. */
+export interface DecisionModelService {
+  getAvailability(input?: { moduleId?: string }): DecisionModelAvailability
+  decide(input: DecisionModelDecideInput): Promise<DecisionModelDecideResult>
+}
+
+/** Minimal logger shape the service writes through. */
+export type DecisionModelServiceLogger = Pick<Logger, 'info' | 'warn'>
+
+/** Error reporter the service calls on `provider_error` / `invalid_response`. */
+export type DecisionModelReportError = (
+  error: unknown,
+  context: { module: string; code: string },
+) => void
+
+/** Optional dependencies of `createDecisionModelService`, mainly for tests and overrides. */
+export interface DecisionModelServiceDeps {
+  registry?: DecisionModelRegistry
+  env?: EnvLookup
+  logger?: DecisionModelServiceLogger
+  reportError?: DecisionModelReportError
+  now?: () => number
+}
+
+const ERROR_MESSAGES: Record<DecisionErrorCode, string> = {
+  unavailable: 'Decision model is unavailable',
+  invalid_request: 'Decision request is invalid',
+  auth: 'Decision provider rejected the credentials',
+  insufficient_credits: 'Decision provider credits are exhausted',
+  rate_limited: 'Decision provider rate limit reached',
+  payload_too_large: 'Decision request is too large',
+  timeout: 'Decision request timed out',
+  aborted: 'Decision request was aborted',
+  provider_error: 'Decision provider failed',
+  invalid_response: 'Decision provider returned an invalid response',
+}
+
+const REPORTED_ERROR_CODES: Partial<Record<DecisionErrorCode, string>> = {
+  provider_error: 'ai_assistant.decision_provider_error',
+  invalid_response: 'ai_assistant.decision_invalid_response',
+}
+
+function messageFor(code: DecisionErrorCode): string {
+  return ERROR_MESSAGES[code] ?? 'Decision request failed'
+}
+
+/** Clamps a caller timeout to the port bounds: default 5 s, maximum 30 s. */
+export function resolveDecisionTimeoutMs(timeoutMs: number | undefined): number {
+  if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return DEFAULT_DECISION_TIMEOUT_MS
+  }
+  return Math.min(timeoutMs, MAX_DECISION_TIMEOUT_MS)
+}
+
+function resolveMaxInputTokens(env: EnvLookup): number {
+  const raw = env[MAX_INPUT_TOKENS_ENV]
+  return parseNumberWithDefault(typeof raw === 'string' ? raw : undefined, DEFAULT_DECISION_MAX_INPUT_TOKENS, {
+    min: 1,
+    integer: true,
+  })
+}
+
+function defaultReportError(error: unknown, context: { module: string; code: string }): void {
+  getTelemetryRuntime()?.reportError(error, context)
+}
+
+function abortPromise(signal: AbortSignal): { promise: Promise<never>; cleanup: () => void } {
+  let listener: (() => void) | undefined
+  const promise = new Promise<never>((_resolve, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason)
+      return
+    }
+    listener = () => reject(signal.reason)
+    signal.addEventListener('abort', listener, { once: true })
+  })
+  return {
+    promise,
+    cleanup: () => {
+      if (listener) signal.removeEventListener('abort', listener)
+    },
+  }
+}
+
+class DecisionFailure extends Error {
+  readonly failure: DecisionModelDecideError
+  readonly origin: unknown
+
+  constructor(failure: DecisionModelDecideError, origin?: unknown) {
+    super(`[internal] ${failure.message}`)
+    this.name = 'DecisionFailure'
+    this.failure = failure
+    this.origin = origin
+  }
+}
+
+function fail(code: DecisionErrorCode, message?: string, httpStatus?: number, origin?: unknown): DecisionFailure {
+  const failure: DecisionModelDecideError = { code, message: message ?? messageFor(code) }
+  if (httpStatus !== undefined) failure.httpStatus = httpStatus
+  return new DecisionFailure(failure, origin)
+}
+
+/**
+ * Creates the decision model service. `decide` never throws or rejects: every
+ * failure becomes `{ ok: false, error }`. The request state, instructions,
+ * criteria and session id are never logged.
+ *
+ * @experimental
+ */
+export function createDecisionModelService(deps: DecisionModelServiceDeps = {}): DecisionModelService {
+  let registry: DecisionModelRegistry | undefined = deps.registry
+  let logger: DecisionModelServiceLogger | undefined = deps.logger
+  const env: EnvLookup = deps.env ?? process.env
+  const reportError: DecisionModelReportError = deps.reportError ?? defaultReportError
+  const now = deps.now ?? (() => Date.now())
+
+  const getRegistry = (): DecisionModelRegistry => {
+    if (!registry) registry = createDecisionModelRegistry({ env })
+    return registry
+  }
+
+  const getLogger = (): DecisionModelServiceLogger => {
+    if (!logger) logger = createLogger('ai_assistant').child({ component: 'decision-model' })
+    return logger
+  }
+
+  const safeLog = (level: 'info' | 'warn', fields: Record<string, unknown>): void => {
+    try {
+      getLogger()[level]('decision model call', fields)
+    } catch {
+      return
+    }
+  }
+
+  const safeReport = (code: DecisionErrorCode, error: unknown): void => {
+    const reportCode = REPORTED_ERROR_CODES[code]
+    if (!reportCode) return
+    try {
+      reportError(error, { module: 'ai_assistant', code: reportCode })
+    } catch {
+      return
+    }
+  }
+
+  const getAvailability: DecisionModelService['getAvailability'] = (input) => {
+    try {
+      const resolution = getRegistry().resolve({ moduleId: input?.moduleId, env })
+      if (!resolution.ok) return { available: false, reason: resolution.reason }
+      return { available: true, provider: resolution.adapter.id, model: resolution.modelId }
+    } catch {
+      return { available: false, reason: 'not_configured' }
+    }
+  }
+
+  const decide: DecisionModelService['decide'] = async (input) => {
+    const startedAt = now()
+    let provider: string | undefined
+    let model: string | undefined
+    let questionCount = 0
+    try {
+      const parsed = decisionRequestSchema.safeParse(input?.request)
+      if (!parsed.success) throw fail('invalid_request')
+      const request: DecisionRequest = parsed.data
+      questionCount = Object.keys(request.questions).length
+
+      let serialized: string | undefined
+      try {
+        serialized = JSON.stringify({ state: request.state, questions: request.questions })
+      } catch {
+        throw fail('invalid_request', 'Decision request state cannot be serialized')
+      }
+      if (countTokens(serialized ?? '') > resolveMaxInputTokens(env)) throw fail('payload_too_large')
+
+      const resolution = getRegistry().resolve({ moduleId: input.moduleId, env })
+      if (!resolution.ok) {
+        throw fail('unavailable', `Decision model unavailable: ${resolution.reason}`)
+      }
+      provider = resolution.adapter.id
+      model = resolution.modelId
+
+      const callerSignal = input.signal
+      if (callerSignal?.aborted) throw fail('aborted')
+
+      const timeoutMs = resolveDecisionTimeoutMs(input.timeoutMs)
+      const timeoutController = new AbortController()
+      const timeoutReason = new DecisionModelError('timeout', `Decision request exceeded ${timeoutMs} ms`)
+      const timer = setTimeout(() => timeoutController.abort(timeoutReason), timeoutMs)
+      const combined = AbortSignal.any([timeoutController.signal, ...(callerSignal ? [callerSignal] : [])])
+      const abort = abortPromise(combined)
+
+      let result: DecisionResult
+      try {
+        result = await Promise.race([
+          resolution.adapter.decide(request, { modelId: resolution.modelId, env, signal: combined }),
+          abort.promise,
+        ])
+      } catch (error) {
+        if (combined.aborted) {
+          const abortCode: DecisionErrorCode = combined.reason === timeoutReason ? 'timeout' : 'aborted'
+          throw fail(abortCode, undefined, undefined, error)
+        }
+        if (error instanceof DecisionModelError) {
+          throw fail(error.code, undefined, error.httpStatus, error)
+        }
+        throw fail('provider_error', undefined, undefined, error)
+      } finally {
+        clearTimeout(timer)
+        abort.cleanup()
+      }
+
+      let answers: DecisionResult['answers']
+      try {
+        answers = normalizeDecisionAnswers(request, result.answers)
+      } catch (error) {
+        throw fail('invalid_response', undefined, undefined, error)
+      }
+
+      const durationMs = now() - startedAt
+      const finalResult: DecisionResult = { ...result, answers, durationMs }
+      safeLog('info', {
+        provider: finalResult.provider,
+        model: finalResult.model,
+        durationMs,
+        usage: finalResult.usage,
+        questionCount,
+        outcomeCodes: ['ok'],
+      })
+      return { ok: true, result: finalResult }
+    } catch (error) {
+      const failure = error instanceof DecisionFailure ? error.failure : fail('provider_error').failure
+      const cause = error instanceof DecisionFailure ? error.origin ?? error : error
+      safeLog('warn', {
+        provider: provider ?? null,
+        model: model ?? null,
+        durationMs: now() - startedAt,
+        usage: null,
+        questionCount,
+        outcomeCodes: [failure.code],
+      })
+      safeReport(failure.code, cause)
+      return { ok: false, error: failure }
+    }
+  }
+
+  return { getAvailability, decide }
+}