@strav/brain 1.0.0-alpha.9 → 1.0.1

package/src/brain_manager.ts

@@ -1,7 +1,7 @@
 /**
  * `BrainManager` — the per-app facade apps inject and call.
  *
- * Holds the configured `Provider` registry + the default-provider key
+ * Holds the configured `BrainDriver` registry + the default-provider key
  * + the tier-to-model map. Apps call `chat / stream / countTokens`
  * with framework-native types; the manager resolves which provider
  * runs the call (default unless `options.provider` overrides),
@@ -21,38 +21,61 @@
 
 import type { Agent } from './agent.ts'
 import type { AgentResult } from './agent_result.ts'
+import type { AgentStreamEvent } from './agent_stream_event.ts'
+import type { MCPServer } from './mcp_server.ts'
+import type { AgentGenerateResult } from './agent_generate_result.ts'
+import type { OutputSchema } from './output_schema.ts'
 import { AgentRunner } from './agent_runner.ts'
 import { BrainError } from './brain_error.ts'
 import type { ModelTier } from './types.ts'
 import type {
+  AudioSource,
   ChatOptions,
   ChatResult,
+  EmbedOptions,
+  EmbedResult,
+  GenerateResult,
   Message,
   StreamEvent,
+  TranscribeOptions,
+  TranscribeResult,
 } from './types.ts'
-import type { Provider, RunWithToolsOptions } from './provider.ts'
+import type {
+  BrainDriver,
+  RunWithToolsOptions,
+  RunWithToolsOptionsWithSuspend,
+} from './brain_driver.ts'
+import { appendResumeResults, type SuspendedRun, type SuspendedState, type ToolResultInput } from './suspended_run.ts'
 import type { Tool } from './tool.ts'
 import { DEFAULT_TIERS } from './brain_config.ts'
 
 /** Container-aware Agent constructor resolver — `BrainProvider` installs one wired to `app.resolve(...)`. */
-export type AgentResolver = <A extends Agent>(cls: new (...args: never[]) => A) => A
+export type AgentResolver = <A extends Agent<unknown>>(cls: new (...args: never[]) => A) => A
 
 export interface BrainManagerOptions {
   /** Name of the default provider — must exist in `providers`. */
   default: string
   /** Provider registry keyed by name. */
-  providers: Record<string, Provider>
+  providers: Record<string, BrainDriver>
   /** Tier-to-model overrides; merged on top of the framework defaults. */
   tiers?: Partial<Record<ModelTier, string>>
   /** Default for `ChatOptions.cache` when the call site doesn't pass one. */
   defaultCache?: boolean
+  /**
+   * Default MCP servers used on every `runTools` call when the per-call
+   * options don't specify them. Per-call `mcpServers` replaces the
+   * default outright (no merge) — apps that want additive behavior
+   * concat at the call site.
+   */
+  defaultMcpServers?: readonly MCPServer[]
 }
 
 export class BrainManager {
   readonly defaultProvider: string
-  private readonly providers: Map<string, Provider>
+  private readonly providers: Map<string, BrainDriver>
   private readonly tiers: Record<ModelTier, string>
   private readonly defaultCache: boolean
+  private readonly defaultMcpServers: readonly MCPServer[]
 
   constructor(options: BrainManagerOptions) {
     if (!options.providers[options.default]) {
@@ -65,10 +88,11 @@ export class BrainManager {
     this.providers = new Map(Object.entries(options.providers))
     this.tiers = { ...DEFAULT_TIERS, ...(options.tiers ?? {}) }
     this.defaultCache = options.defaultCache ?? false
+    this.defaultMcpServers = options.defaultMcpServers ?? []
   }
 
   /** Resolve a provider by name. Default when no name passed. Throws when unknown. */
-  provider(name?: string): Provider {
+  provider(name?: string): BrainDriver {
     const key = name ?? this.defaultProvider
     const provider = this.providers.get(key)
     if (!provider) {
@@ -79,6 +103,29 @@ export class BrainManager {
     return provider
   }
 
+  /**
+   * Register an additional provider after construction. Apps that
+   * wire a custom adapter (a fine-tuned model server, a fork of
+   * Anthropic with extra knobs, an internal LLM) use this to add it
+   * to the registry without going through `config.brain.providers`.
+   *
+   * Overwrites any existing provider under the same name.
+   *
+   * ```ts
+   * brain.extend('internal', new InternalLlmProvider({ baseUrl }))
+   * const reply = await brain.chat(messages, { provider: 'internal' })
+   * ```
+   *
+   * Mirrors `RagManager.extend(name, factory)` / `PaymentManager.extend(name, factory)`
+   * — the OCP escape hatch every multi-driver Strav manager exposes.
+   */
+  extend(name: string, provider: BrainDriver): void {
+    if (!name) {
+      throw new BrainError('BrainManager.extend: provider name must be a non-empty string.')
+    }
+    this.providers.set(name, provider)
+  }
+
   /**
    * One-shot chat: send the messages, await the full reply.
    *
@@ -131,13 +178,23 @@ export class BrainManager {
    *
    * Throws `BrainError` when the configured provider doesn't
    * implement `runWithTools` (V1: OpenAI / Gemini / DeepSeek providers
-   * don't yet — only `AnthropicProvider`).
+   * don't yet — only `AnthropicBrainDriver`).
    */
+  runTools(
+    input: string | readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptionsWithSuspend,
+  ): Promise<AgentResult | SuspendedRun>
+  runTools(
+    input: string | readonly Message[],
+    tools: readonly Tool[],
+    options?: RunWithToolsOptions,
+  ): Promise<AgentResult>
   async runTools(
     input: string | readonly Message[],
     tools: readonly Tool[],
     options: RunWithToolsOptions = {},
-  ): Promise<AgentResult> {
+  ): Promise<AgentResult | SuspendedRun> {
     const provider = this.provider(options.provider)
     if (!provider.runWithTools) {
       throw new BrainError(
@@ -147,24 +204,252 @@ export class BrainManager {
     }
     const messages = normalizeInput(input)
     const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    // MCP defaults — per-call override (when present) replaces the
+    // configured list outright; apps that want concat behavior
+    // construct the merged array themselves and pass it in.
+    if (resolved.mcpServers === undefined && this.defaultMcpServers.length > 0) {
+      resolved.mcpServers = this.defaultMcpServers
+    }
     return provider.runWithTools(messages, tools, resolved)
   }
 
+  /**
+   * Resume a previously-suspended tool-use loop. Takes the
+   * `SuspendedRun.state` snapshot plus the results the integrator
+   * gathered for each `pendingToolCalls` entry; appends a `tool_result`
+   * block per entry; re-enters `runTools` so the model can continue
+   * (potentially suspending again on the next tool).
+   *
+   * Mid-batch invariant: every pending call MUST get a result —
+   * otherwise the provider rejects the next request because the
+   * assistant turn's `tool_use` blocks are no longer balanced.
+   * `resumeTools` throws `BrainError` when results are missing.
+   *
+   * The `previousResponseId` carried on the snapshot (when the
+   * provider supports stateful conversations) is threaded back via
+   * `options.previousResponseId` automatically — per-call
+   * `options.previousResponseId` wins if supplied explicitly.
+   */
+  async resumeTools(
+    state: SuspendedState,
+    results: readonly ToolResultInput[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): Promise<AgentResult | SuspendedRun> {
+    const resumed = appendResumeResults(state, results)
+    const merged: RunWithToolsOptions = { ...options }
+    if (merged.previousResponseId === undefined && state.responseId !== undefined) {
+      merged.previousResponseId = state.responseId
+    }
+    const out = await this.runTools(
+      resumed,
+      tools,
+      merged as RunWithToolsOptionsWithSuspend,
+    )
+    return mergeResumeCounters(out, state)
+  }
+
+  /**
+   * Streaming variant of `generateWithTools`. Yields
+   * `AgentStreamEvent<T>`s as the loop progresses; the terminal
+   * `stop` event carries the parsed value + raw JSON text. Throws
+   * `BrainError` when the provider lacks
+   * `streamWithToolsAndSchema` (V1: all three providers
+   * implement it).
+   */
+  streamGenerateWithTools<T>(
+    input: string | readonly Message[],
+    schema: OutputSchema<T>,
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): AsyncIterable<AgentStreamEvent<T>> {
+    rejectShouldSuspend(options, 'streamGenerateWithTools')
+    const provider = this.provider(options.provider)
+    if (!provider.streamWithToolsAndSchema) {
+      throw new BrainError(
+        `BrainManager.streamGenerateWithTools: provider "${provider.name}" does not implement streamWithToolsAndSchema.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    if (resolved.mcpServers === undefined && this.defaultMcpServers.length > 0) {
+      resolved.mcpServers = this.defaultMcpServers
+    }
+    return provider.streamWithToolsAndSchema<T>(messages, tools, schema, resolved)
+  }
+
+  /**
+   * Tool-loop + structured output combined. Runs the agentic loop
+   * with the supplied `tools` while pinning the output to `schema`
+   * on every turn; returns the parsed value when the model finally
+   * answers without calling a tool. MCP defaults + tier resolution
+   * + provider routing match `runTools` / `generate`.
+   *
+   * Throws `BrainError` when the chosen provider doesn't implement
+   * `runWithToolsAndSchema`. V1: all three providers do.
+   */
+  async generateWithTools<T>(
+    input: string | readonly Message[],
+    schema: OutputSchema<T>,
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): Promise<AgentGenerateResult<T>> {
+    rejectShouldSuspend(options, 'generateWithTools')
+    const provider = this.provider(options.provider)
+    if (!provider.runWithToolsAndSchema) {
+      throw new BrainError(
+        `BrainManager.generateWithTools: provider "${provider.name}" does not implement runWithToolsAndSchema.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    if (resolved.mcpServers === undefined && this.defaultMcpServers.length > 0) {
+      resolved.mcpServers = this.defaultMcpServers
+    }
+    return provider.runWithToolsAndSchema<T>(messages, tools, schema, resolved)
+  }
+
+  /**
+   * Streaming variant of `runTools`. Yields `AgentStreamEvent`s
+   * as the agentic loop progresses — text deltas during model
+   * turns, `tool_use` / `tool_result` boundaries around tool
+   * execution, `iteration_start` / `iteration_end` per round, a
+   * terminal `stop` with the full trace + usage.
+   *
+   * Throws `BrainError` when the configured provider doesn't
+   * implement `streamWithTools`.
+   */
+  streamTools(
+    input: string | readonly Message[],
+    tools: readonly Tool[],
+    options: RunWithToolsOptions = {},
+  ): AsyncIterable<AgentStreamEvent> {
+    rejectShouldSuspend(options, 'streamTools')
+    const provider = this.provider(options.provider)
+    if (!provider.streamWithTools) {
+      throw new BrainError(
+        `BrainManager.streamTools: provider "${provider.name}" does not implement streamWithTools.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options) as RunWithToolsOptions
+    if (resolved.mcpServers === undefined && this.defaultMcpServers.length > 0) {
+      resolved.mcpServers = this.defaultMcpServers
+    }
+    return provider.streamWithTools(messages, tools, resolved)
+  }
+
+  /**
+   * Structured output. Sends `input` to the configured (or
+   * `options.provider`-overridden) provider with the JSON-Schema
+   * constraint described by `schema`; returns the parsed object.
+   *
+   * Throws `BrainError` when the chosen provider doesn't implement
+   * `generate`. All three V1 providers (Anthropic, OpenAI, Gemini)
+   * do.
+   */
+  async generate<T>(
+    input: string | readonly Message[],
+    schema: OutputSchema<T>,
+    options: ChatOptions = {},
+  ): Promise<GenerateResult<T>> {
+    const provider = this.provider(options.provider)
+    if (!provider.generate) {
+      throw new BrainError(
+        `BrainManager.generate: provider "${provider.name}" does not implement generate.`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const messages = normalizeInput(input)
+    const resolved = this.applyDefaults(options)
+    return provider.generate<T>(messages, schema, resolved)
+  }
+
+  /**
+   * Turn one or more text inputs into embedding vectors. Accepts
+   * either a single string (returns one vector) or an array
+   * (batch — returns one vector per input in the same order).
+   *
+   * Throws `BrainError` when the configured (or
+   * `options.provider`-overridden) provider doesn't implement
+   * `embed`. V1: OpenAI, Gemini, Ollama support it; Anthropic +
+   * DeepSeek throw with a clear "route to a different provider"
+   * message.
+   */
+  async embed(
+    input: string | readonly string[],
+    options: EmbedOptions = {},
+  ): Promise<EmbedResult> {
+    const provider = this.provider(options.provider)
+    if (!provider.embed) {
+      throw new BrainError(
+        `BrainManager.embed: provider "${provider.name}" does not implement embed. Route to a provider with an embeddings API (V1: OpenAI / Gemini / Ollama).`,
+        { context: { provider: provider.name } },
+      )
+    }
+    const texts = typeof input === 'string' ? [input] : input
+    return provider.embed(texts, options)
+  }
+
+  /**
+   * Transcribe one audio clip to text. Complements `AudioBlock`
+   * (which sends audio + a text prompt together to a multimodal
+   * chat model) by exposing the dedicated transcription endpoint
+   * where the provider has one. Apps that already have an
+   * `AudioBlock` can pass its `source` directly.
+   *
+   * Throws `BrainError` when the configured (or
+   * `options.provider`-overridden) provider doesn't implement
+   * `transcribe`. V1: OpenAI / Ollama (Whisper / gpt-4o-transcribe
+   * / local) and Gemini (chat-wrap fallback); Anthropic +
+   * DeepSeek throw.
+   */
+  async transcribe(
+    audio: AudioSource,
+    options: TranscribeOptions = {},
+  ): Promise<TranscribeResult> {
+    const provider = this.provider(options.provider)
+    if (!provider.transcribe) {
+      throw new BrainError(
+        `BrainManager.transcribe: provider "${provider.name}" does not implement transcribe. Route to a provider with audio support (V1: OpenAI / Ollama / Gemini).`,
+        { context: { provider: provider.name } },
+      )
+    }
+    return provider.transcribe(audio, options)
+  }
+
   /**
    * Resolve an `Agent` subclass from the container and return an
    * `AgentRunner` ready to receive `input(...)` and `run()`. Apps
    * `@inject()`-decorate their Agent subclass so constructor
    * injection of dependencies (Repositories, services, etc.) flows
    * through normally.
+   *
+   * When the agent subclass extends `Agent<T>` for some `T` and
+   * declares `outputSchema`, the returned runner is typed as
+   * `AgentRunner<T>` and the schema is pre-applied — `.run()`
+   * returns `AgentGenerateResult<T>` without a per-call
+   * `.output(schema)`. Apps can still chain `.output(otherSchema)`
+   * to override.
    */
-  agent<A extends Agent>(AgentClass: new (...args: never[]) => A, instance?: A): AgentRunner {
+  agent<T = never>(
+    AgentClass: new (...args: never[]) => Agent<T>,
+    instance?: Agent<T>,
+  ): AgentRunner<T> {
     const agent = instance ?? this.resolveAgent(AgentClass)
-    return new AgentRunner(this, agent)
+    const runner = new AgentRunner<T>(this, agent)
+    if (agent.outputSchema !== undefined) {
+      return runner.output(agent.outputSchema)
+    }
+    return runner
   }
 
   // ─── Internal ────────────────────────────────────────────────────────────
 
-  private resolveAgent<A extends Agent>(AgentClass: new (...args: never[]) => A): A {
+  private resolveAgent<A extends Agent<unknown>>(AgentClass: new (...args: never[]) => A): A {
     if (this.agentResolver) return this.agentResolver(AgentClass)
     // Fallback: assume the Agent class is constructible without args.
     // Apps that need DI on the agent register a resolver via
@@ -203,3 +488,66 @@ function normalizeInput(input: string | readonly Message[]): readonly Message[]
   }
   return input
 }
+
+/**
+ * V1 scope guard. `shouldSuspend` is wired only into the non-
+ * streaming `runWithTools` loop; the streaming and schema variants
+ * don't yet model pause / resume, so silently ignoring would be
+ * worse than throwing. Apps that need both should run tools first
+ * (suspending as needed), then call `generate` for the structured
+ * summary in a separate step.
+ */
+/**
+ * Carry forward the pre-suspension iteration count + token usage so
+ * `result.iterations` / `result.usage` reflect the full run, not
+ * just the post-resume portion. When the resumed call suspends
+ * again, the new state's iterations + usage also get the carry-
+ * forward so apps see a running total across an arbitrary number
+ * of suspension cycles.
+ */
+function mergeResumeCounters(
+  out: AgentResult | SuspendedRun,
+  state: SuspendedState,
+): AgentResult | SuspendedRun {
+  // +1 accounts for the suspended round itself — at suspension time
+  // the loop hadn't yet incremented `iterations` (we paused mid-
+  // batch, before tool execution). Supplying results to resume
+  // effectively completes that round.
+  const carryIter = state.iterations + 1
+  if ('status' in out) {
+    return {
+      ...out,
+      state: {
+        ...out.state,
+        iterations: out.state.iterations + carryIter,
+        usage: addUsage(out.state.usage, state.usage),
+      },
+    }
+  }
+  return {
+    ...out,
+    iterations: out.iterations + carryIter,
+    usage: addUsage(out.usage, state.usage),
+  }
+}
+
+function addUsage(
+  a: SuspendedState['usage'],
+  b: SuspendedState['usage'],
+): SuspendedState['usage'] {
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+    cacheCreationTokens: a.cacheCreationTokens + b.cacheCreationTokens,
+  }
+}
+
+function rejectShouldSuspend(options: RunWithToolsOptions, entry: string): void {
+  if (options.shouldSuspend !== undefined) {
+    throw new BrainError(
+      `BrainManager.${entry}: \`shouldSuspend\` is only supported on \`runTools\` (the non-streaming + no-schema entrypoint) in V1. Run tools first with suspension, then call \`generate\` for the structured summary as a separate step.`,
+      { context: { entry } },
+    )
+  }
+}

package/src/brain_provider.ts

@@ -25,10 +25,18 @@
  */
 
 import { type Application, ConfigError, ConfigRepository, ServiceProvider } from '@strav/kernel'
-import { BrainManager } from './brain_manager.ts'
 import type { BrainConfigShape, ProviderConfig } from './brain_config.ts'
-import { AnthropicProvider } from './providers/anthropic_provider.ts'
-import type { Provider } from './provider.ts'
+import type { BrainDriver } from './brain_driver.ts'
+import { BrainManager } from './brain_manager.ts'
+import { AnthropicBrainDriver } from './drivers/anthropic/anthropic_brain_driver.ts'
+import { DeepSeekBrainDriver } from './drivers/deepseek/deepseek_brain_driver.ts'
+import { GeminiBrainDriver } from './drivers/gemini/gemini_brain_driver.ts'
+import { MiniMaxBrainDriver } from './drivers/minimax/minimax_brain_driver.ts'
+import { OllamaBrainDriver } from './drivers/ollama/ollama_brain_driver.ts'
+import { OpenAIBrainDriver } from './drivers/openai/openai_brain_driver.ts'
+import { OpenAIResponsesBrainDriver } from './drivers/openai_responses/openai_responses_brain_driver.ts'
+import { OpenRouterBrainDriver } from './drivers/openrouter/openrouter_brain_driver.ts'
+import { QwenBrainDriver } from './drivers/qwen/qwen_brain_driver.ts'
 
 export class BrainProvider extends ServiceProvider {
   override readonly name = 'brain'
@@ -53,9 +61,9 @@ export class BrainProvider extends ServiceProvider {
         )
       }
 
-      const providers: Record<string, Provider> = {}
+      const providers: Record<string, BrainDriver> = {}
       for (const [name, entry] of Object.entries(config.providers)) {
-        providers[name] = buildProvider(name, entry)
+        providers[name] = buildBrainDriver(name, entry)
       }
 
       const options: ConstructorParameters<typeof BrainManager>[0] = {
@@ -64,6 +72,7 @@ export class BrainProvider extends ServiceProvider {
       }
       if (config.tiers !== undefined) options.tiers = config.tiers
       if (config.cache?.auto !== undefined) options.defaultCache = config.cache.auto
+      if (config.mcpServers !== undefined) options.defaultMcpServers = config.mcpServers
       const manager = new BrainManager(options)
       // Plug in the container so `brain.agent(MyAgent)` resolves
       // its constructor deps through `@inject()` like every other
@@ -83,7 +92,7 @@ export class BrainProvider extends ServiceProvider {
   }
 }
 
-function buildProvider(name: string, config: ProviderConfig): Provider {
+function buildBrainDriver(name: string, config: ProviderConfig): BrainDriver {
   switch (config.driver) {
     case 'anthropic':
       if (!config.apiKey) {
@@ -91,10 +100,71 @@ function buildProvider(name: string, config: ProviderConfig): Provider {
           `BrainProvider: anthropic provider "${name}" is missing apiKey. Source from env('ANTHROPIC_API_KEY').`,
         )
       }
-      return new AnthropicProvider(name, config)
-    default:
+      return new AnthropicBrainDriver(name, config)
+    case 'openai':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: openai provider "${name}" is missing apiKey. Source from env('OPENAI_API_KEY').`,
+        )
+      }
+      return new OpenAIBrainDriver(name, config)
+    case 'openai-responses':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: openai-responses provider "${name}" is missing apiKey. Source from env('OPENAI_API_KEY').`,
+        )
+      }
+      return new OpenAIResponsesBrainDriver(name, config)
+    case 'google':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: google provider "${name}" is missing apiKey. Source from env('GOOGLE_API_KEY').`,
+        )
+      }
+      return new GeminiBrainDriver(name, config)
+    case 'deepseek':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: deepseek provider "${name}" is missing apiKey. Source from env('DEEPSEEK_API_KEY').`,
+        )
+      }
+      return new DeepSeekBrainDriver(name, config)
+    case 'ollama':
+      if (!config.defaultModel) {
+        throw new ConfigError(
+          `BrainProvider: ollama provider "${name}" is missing defaultModel. Ollama models are user-installed — pick one you've pulled (e.g. 'llama3.2').`,
+        )
+      }
+      return new OllamaBrainDriver(name, config)
+    case 'qwen':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: qwen provider "${name}" is missing apiKey. Source from env('DASHSCOPE_API_KEY') or env('QWEN_API_KEY').`,
+        )
+      }
+      return new QwenBrainDriver(name, config)
+    case 'minimax':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: minimax provider "${name}" is missing apiKey. Source from env('MINIMAX_API_KEY').`,
+        )
+      }
+      return new MiniMaxBrainDriver(name, config)
+    case 'openrouter':
+      if (!config.apiKey) {
+        throw new ConfigError(
+          `BrainProvider: openrouter provider "${name}" is missing apiKey. Source from env('OPENROUTER_API_KEY').`,
+        )
+      }
+      return new OpenRouterBrainDriver(name, config)
+    default: {
+      const exhaustiveCheck: never = config
       throw new ConfigError(
-        `BrainProvider: unknown driver for provider "${name}". Known drivers: anthropic.`,
+        `BrainProvider: unknown driver for provider "${name}". Known drivers: anthropic, openai, openai-responses, google, deepseek, ollama, qwen, minimax, openrouter.`,
       )
+      // (unreachable — kept for the exhaustive check to fire when a new driver lands)
+      // biome-ignore lint/correctness/noUnreachable: kept for the exhaustive-check above
+      return exhaustiveCheck
+    }
   }
 }