@graphorin/provider 0.6.0 → 0.7.0

package/src/middleware/with-retry.ts

@@ -0,0 +1,274 @@
+/**
+ * `withRetry` - retry idempotent failures (5xx, network, timeouts)
+ * with exponential backoff + jitter. Lives outside `withRateLimit`
+ * per the canonical order so retried requests respect the rate-limit
+ * bucket of the next attempt.
+ *
+ * @packageDocumentation
+ */
+
+import type { Provider, ProviderEvent, ProviderRequest, ProviderResponse } from '@graphorin/core';
+
+import { isAbortError } from '../internal/abort.js';
+import { defineProviderMiddleware } from './compose.js';
+
+/**
+ * Options for {@link withRetry}.
+ *
+ * @stable
+ */
+export interface WithRetryOptions {
+  readonly maxRetries?: number;
+  readonly backoff?: 'exponential' | 'linear' | 'constant';
+  readonly initialDelayMs?: number;
+  readonly maxDelayMs?: number;
+  readonly jitter?: boolean;
+  readonly retryableErrors?: (err: unknown) => boolean;
+  /** Optional sleep override (test fixtures use a synchronous resolver). */
+  readonly sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+/**
+ * @stable
+ */
+export const withRetry = defineProviderMiddleware<WithRetryOptions>({
+  kind: 'withRetry',
+  factory: (opts: WithRetryOptions) => {
+    const maxRetries = opts.maxRetries ?? 3;
+    const backoff = opts.backoff ?? 'exponential';
+    const initialDelay = opts.initialDelayMs ?? 250;
+    const maxDelay = opts.maxDelayMs ?? 30_000;
+    const jitter = opts.jitter ?? true;
+    const isRetryable = opts.retryableErrors ?? defaultRetryable;
+    const sleep = opts.sleepImpl ?? defaultSleep;
+    return (next: Provider): Provider => ({
+      name: next.name,
+      modelId: next.modelId,
+      capabilities: next.capabilities,
+      ...(next.acceptsSensitivity !== undefined
+        ? { acceptsSensitivity: next.acceptsSensitivity }
+        : {}),
+      stream(req) {
+        return retryingStream(
+          next,
+          req,
+          maxRetries,
+          backoff,
+          initialDelay,
+          maxDelay,
+          jitter,
+          isRetryable,
+          sleep,
+        );
+      },
+      async generate(req) {
+        let attempt = 0;
+        for (;;) {
+          try {
+            return await next.generate(req);
+          } catch (err) {
+            if (req.signal?.aborted) throw err;
+            if (attempt >= maxRetries) throw err;
+            if (!isRetryable(err)) throw err;
+            const hint = readRetryAfter(err);
+            const delay =
+              hint !== null
+                ? Math.min(hint, maxDelay)
+                : computeDelay(backoff, initialDelay, attempt, maxDelay, jitter);
+            await sleep(delay, req.signal);
+            attempt++;
+          }
+        }
+      },
+      ...(next.countTokens ? { countTokens: next.countTokens.bind(next) } : {}),
+    });
+  },
+});
+
+async function* retryingStream(
+  next: Provider,
+  req: ProviderRequest,
+  maxRetries: number,
+  backoff: 'exponential' | 'linear' | 'constant',
+  initialDelay: number,
+  maxDelay: number,
+  jitter: boolean,
+  isRetryable: (err: unknown) => boolean,
+  sleep: (ms: number, signal?: AbortSignal) => Promise<void>,
+): AsyncIterable<ProviderEvent> {
+  let attempt = 0;
+  // Stream-level (not per-attempt): once *any* event has reached the
+  // consumer, a retryable failure mid-stream must NOT restart the stream -
+  // that would replay stream-start + already-delivered text/tool-call events
+  // into the same iteration (duplicate output, potential double tool execution).
+  // `withFallback` upholds the same invariant. Pre-yield failures still retry.
+  let yieldedAny = false;
+  for (;;) {
+    try {
+      for await (const event of next.stream(req)) {
+        yieldedAny = true;
+        yield event;
+      }
+      if (yieldedAny) return;
+      // Empty stream - surface a finish so callers do not hang.
+      yield {
+        type: 'finish',
+        finishReason: 'stop',
+        usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      };
+      return;
+    } catch (err) {
+      if (req.signal?.aborted) throw err;
+      // PS-1: never restart a stream that already emitted events.
+      if (yieldedAny) throw err;
+      if (attempt >= maxRetries) throw err;
+      if (!isRetryable(err)) throw err;
+      const hint = readRetryAfter(err);
+      const delay =
+        hint !== null
+          ? Math.min(hint, maxDelay)
+          : computeDelay(backoff, initialDelay, attempt, maxDelay, jitter);
+      await sleep(delay, req.signal);
+      attempt++;
+    }
+  }
+}
+
+/**
+ * Read a `Retry-After` hint from a thrown error. Recognises:
+ *
+ * - `RateLimitExceededError`-shaped errors carrying a `retryAfterMs`
+ *   field (already milliseconds).
+ * - HTTP-shaped errors carrying a `headers['retry-after']` value
+ *   (numeric seconds; we convert to milliseconds).
+ * - HTTP-shaped errors carrying a `retryAfterSeconds` numeric field.
+ *
+ * Returns the resolved delay in milliseconds or `null` when no hint
+ * is available.
+ *
+ * @internal
+ */
+function readRetryAfter(err: unknown): number | null {
+  if (err === null || typeof err !== 'object') return null;
+  const e = err as {
+    retryAfterMs?: number;
+    retryAfterSeconds?: number;
+    headers?: Record<string, string | undefined>;
+  };
+  if (
+    typeof e.retryAfterMs === 'number' &&
+    Number.isFinite(e.retryAfterMs) &&
+    e.retryAfterMs >= 0
+  ) {
+    return e.retryAfterMs;
+  }
+  if (
+    typeof e.retryAfterSeconds === 'number' &&
+    Number.isFinite(e.retryAfterSeconds) &&
+    e.retryAfterSeconds >= 0
+  ) {
+    return Math.round(e.retryAfterSeconds * 1000);
+  }
+  const headerValue =
+    e.headers?.['retry-after'] ?? e.headers?.['Retry-After'] ?? e.headers?.['RETRY-AFTER'];
+  if (typeof headerValue === 'string' && headerValue.length > 0) {
+    const seconds = Number(headerValue);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1000);
+    const httpDateMs = Date.parse(headerValue);
+    if (Number.isFinite(httpDateMs)) {
+      const delta = httpDateMs - Date.now();
+      return delta > 0 ? delta : 0;
+    }
+  }
+  return null;
+}
+
+function defaultRetryable(err: unknown): boolean {
+  if (err === null || typeof err !== 'object') return false;
+  // An aborted request is never retryable, even when it surfaces as a
+  // `status: 0` network error (PS-2). The retry loop also short-circuits on
+  // `req.signal?.aborted`, but the predicate must exclude abort independently
+  // so an internally-aborted call is not retried.
+  if (isAbortError(err)) return false;
+  const e = err as { kind?: string; errorKind?: string; status?: number; name?: string };
+  // `ProviderHttpError.kind` is always 'provider-http'; the canonical
+  // mapped kind rides on `errorKind` - consult both.
+  const kinds = [e.kind, e.errorKind];
+  if (
+    kinds.includes('transient') ||
+    kinds.includes('rate-limit') ||
+    kinds.includes('rate-limit-exceeded') ||
+    kinds.includes('capacity')
+  ) {
+    return true;
+  }
+  if (
+    kinds.includes('unauthorized') ||
+    kinds.includes('invalid-request') ||
+    kinds.includes('context-length') ||
+    kinds.includes('content-filter')
+  ) {
+    return false;
+  }
+  if (typeof e.status === 'number' && e.status === 429) return true;
+  if (typeof e.status === 'number' && e.status >= 500 && e.status < 600) return true;
+  // PS-2: a `ProviderHttpError{ status: 0 }` is a fetch-level network failure
+  // (ECONNREFUSED, DNS, connection reset) - exactly the transient class
+  // `withRetry` documents. Retry it (abort already excluded above).
+  if (typeof e.status === 'number' && e.status === 0) return true;
+  return false;
+}
+
+function computeDelay(
+  backoff: 'exponential' | 'linear' | 'constant',
+  initial: number,
+  attempt: number,
+  maxDelay: number,
+  jitter: boolean,
+): number {
+  let delay: number;
+  switch (backoff) {
+    case 'exponential':
+      delay = initial * 2 ** attempt;
+      break;
+    case 'linear':
+      delay = initial * (attempt + 1);
+      break;
+    default:
+      delay = initial;
+      break;
+  }
+  delay = Math.min(delay, maxDelay);
+  if (jitter) {
+    const factor = 0.5 + Math.random() * 0.5; // 0.5..1.0
+    delay = Math.floor(delay * factor);
+  }
+  return delay;
+}
+
+function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error('aborted'));
+      return;
+    }
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      cleanup();
+      reject(signal?.reason ?? new Error('aborted'));
+    };
+    function cleanup(): void {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+    }
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+// Cast for return-type compatibility with the discriminated union in
+// `Provider.generate(...)` (TypeScript has no concept of "exhaustive
+// retry loop" so the empty exit path is unreachable).
+export type _RetryProviderResponseGuard = ProviderResponse;

package/src/middleware/with-tracing.ts

@@ -0,0 +1,117 @@
+/**
+ * `withTracing` - outermost middleware. Wraps every `provider.stream`
+ * / `provider.generate` call in a Graphorin OTel-shaped span so the
+ * span captures retry decisions, rate-limit waits, and the underlying
+ * provider call as one logical unit.
+ *
+ * The middleware accepts any object that exposes the
+ * {@link Tracer} contract from `@graphorin/core/contracts`. Tests pass
+ * a `NOOP_TRACER`-shaped stub; production wires the real Graphorin
+ * tracer from `@graphorin/observability`.
+ *
+ * @packageDocumentation
+ */
+
+import type { Provider, Tracer } from '@graphorin/core';
+
+import { defineProviderMiddleware } from './compose.js';
+
+/**
+ * Options for {@link withTracing}.
+ *
+ * @stable
+ */
+export interface WithTracingOptions {
+  /** Tracer instance. Defaults to a no-op tracer if unset. */
+  readonly tracer?: Tracer;
+}
+
+/**
+ * @stable
+ */
+export const withTracing = defineProviderMiddleware<WithTracingOptions>({
+  kind: 'withTracing',
+  factory: (opts: WithTracingOptions) => {
+    return (next: Provider): Provider => ({
+      name: next.name,
+      modelId: next.modelId,
+      capabilities: next.capabilities,
+      ...(next.acceptsSensitivity !== undefined
+        ? { acceptsSensitivity: next.acceptsSensitivity }
+        : {}),
+      stream(req) {
+        if (opts.tracer === undefined) return next.stream(req);
+        return tracedStream(opts.tracer, next, req);
+      },
+      async generate(req) {
+        if (opts.tracer === undefined) return next.generate(req);
+        return opts.tracer.span(
+          {
+            type: 'provider.generate' as const,
+            attrs: {
+              'graphorin.provider.id': next.name,
+              'graphorin.provider.model': next.modelId,
+              // C7: OTel GenAI semantic conventions.
+              'gen_ai.operation.name': 'chat',
+              'gen_ai.provider.name': next.name,
+              'gen_ai.request.model': next.modelId,
+            },
+            // C7: parent under the agent step span when the loop supplies one.
+            ...(req.parentSpan !== undefined ? { parent: req.parentSpan } : {}),
+          },
+          async (span) => {
+            const response = await next.generate(req);
+            span.setAttributes({
+              'gen_ai.usage.input_tokens': response.usage.promptTokens,
+              'gen_ai.usage.output_tokens': response.usage.completionTokens,
+            });
+            return response;
+          },
+        );
+      },
+      ...(next.countTokens ? { countTokens: next.countTokens.bind(next) } : {}),
+    });
+  },
+});
+
+async function* tracedStream(
+  tracer: Tracer,
+  next: Provider,
+  req: import('@graphorin/core').ProviderRequest,
+): AsyncIterable<import('@graphorin/core').ProviderEvent> {
+  const span = tracer.startSpan({
+    type: 'provider.stream' as const,
+    attrs: {
+      'graphorin.provider.id': next.name,
+      'graphorin.provider.model': next.modelId,
+      // C7: OTel GenAI semantic conventions.
+      'gen_ai.operation.name': 'chat',
+      'gen_ai.provider.name': next.name,
+      'gen_ai.request.model': next.modelId,
+    },
+    // C7: parent under the agent step span when the loop supplies one.
+    ...(req.parentSpan !== undefined ? { parent: req.parentSpan } : {}),
+  });
+  try {
+    for await (const event of next.stream(req)) {
+      if (event.type === 'finish') {
+        span.setAttributes({
+          'gen_ai.usage.input_tokens': event.usage.promptTokens,
+          'gen_ai.usage.output_tokens': event.usage.completionTokens,
+        });
+      }
+      yield event;
+    }
+    span.setStatus('ok');
+  } catch (err) {
+    span.recordException(err);
+    span.setStatus('error', (err as Error).message);
+    throw err;
+  } finally {
+    // PS-7: a consumer `break`/early-return injects a generator `return` at the
+    // `yield`, skipping both the success and catch paths. Ending the span in
+    // `finally` guarantees it is closed exactly once on every exit - normal
+    // completion, error, or early abort (which leaves the status unset).
+    span.end();
+  }
+}

package/src/model-tier/classify.ts

@@ -0,0 +1,125 @@
+/**
+ * Per-provider model-tier auto-classifier - returns
+ * `'fast' | 'balanced' | 'smart' | undefined` for any model id. The
+ * classifier is consumed by the agent runtime (Phase 12) to validate
+ * operator-supplied tier mappings and to surface tier-not-mapped
+ * recommendations.
+ *
+ * The dispatcher is a pure function; it reads from a small static
+ * rule table keyed on regex patterns matched against the lowercased
+ * model id. The table can be inspected via {@link CLASSIFIER_RULES}
+ * for debugging and downstream tooling (CLI, dashboard, lint rules).
+ *
+ * @packageDocumentation
+ */
+
+import type { ModelHint, ProviderLike } from '@graphorin/core';
+
+import { InvalidProviderError } from '../errors/errors.js';
+
+/**
+ * Single entry in the classifier rule table.
+ *
+ * @stable
+ */
+export interface ClassifierRule {
+  readonly tier: ModelHint;
+  readonly pattern: RegExp;
+  /** Human-readable family label (`'anthropic-claude-haiku'`, …). */
+  readonly family: string;
+}
+
+/**
+ * The static rule table. Order matters - higher-specificity entries
+ * come first (e.g. `claude-haiku` before `claude-`). Tests assert
+ * that the table covers the canonical 2026 model families.
+ *
+ * @stable
+ */
+export const CLASSIFIER_RULES: readonly ClassifierRule[] = Object.freeze([
+  // Anthropic - direct. PS-20: the version segment between `claude` and the
+  // family word can be multi-part (`claude-3-5-haiku`, `claude-3-7-sonnet`) or
+  // absent (`claude-haiku-4-5`), so allow zero-or-more `-<digits/dots>` groups.
+  { tier: 'fast', family: 'anthropic-haiku', pattern: /^claude(?:-[\d.]+)*-?haiku/ },
+  { tier: 'balanced', family: 'anthropic-sonnet', pattern: /^claude(?:-[\d.]+)*-?sonnet/ },
+  { tier: 'smart', family: 'anthropic-opus', pattern: /^claude(?:-[\d.]+)*-?opus/ },
+  { tier: 'smart', family: 'anthropic-fable', pattern: /^claude.*fable/ },
+  { tier: 'smart', family: 'anthropic-mythos', pattern: /^claude.*mythos/ },
+  // Anthropic - via Bedrock.
+  {
+    tier: 'fast',
+    family: 'bedrock-claude-haiku',
+    pattern: /^anthropic\.claude(?:-[\d.]+)*-?haiku/,
+  },
+  {
+    tier: 'balanced',
+    family: 'bedrock-claude-sonnet',
+    pattern: /^anthropic\.claude(?:-[\d.]+)*-?sonnet/,
+  },
+  {
+    tier: 'smart',
+    family: 'bedrock-claude-opus',
+    pattern: /^anthropic\.claude(?:-[\d.]+)*-?opus/,
+  },
+  // OpenAI.
+  { tier: 'fast', family: 'openai-mini', pattern: /^gpt-(\d|\d+\.\d+)-?mini/ },
+  { tier: 'fast', family: 'openai-nano', pattern: /^gpt-(\d|\d+\.\d+)-?nano/ },
+  { tier: 'balanced', family: 'openai-gpt', pattern: /^gpt-(?!.*(?:mini|nano))/ },
+  { tier: 'smart', family: 'openai-reasoning', pattern: /^o[1-9]\b/ },
+  { tier: 'smart', family: 'openai-reasoning-extended', pattern: /^o[1-9][a-z-]/ },
+  // Google Gemini.
+  { tier: 'fast', family: 'gemini-flash', pattern: /^gemini.*flash/ },
+  { tier: 'balanced', family: 'gemini-pro', pattern: /^gemini.*pro\b/ },
+  { tier: 'smart', family: 'gemini-ultra', pattern: /^gemini.*ultra/ },
+]);
+
+/**
+ * Classify a `Provider`'s `modelId` into one of `'fast' | 'balanced' |
+ * 'smart'`. Returns `undefined` when the model id matches none of the
+ * canonical 2026 mappings (Ollama / OpenAI-compatible / unknown).
+ *
+ * @stable
+ */
+export function classifyModelTier(provider: ProviderLike): ModelHint | undefined {
+  if (provider === null || typeof provider !== 'object') {
+    throw new InvalidProviderError('classifyModelTier: argument must be a Provider-shaped object.');
+  }
+  const modelId = provider.modelId;
+  if (typeof modelId !== 'string' || modelId.length === 0) {
+    throw new InvalidProviderError(
+      'classifyModelTier: provider.modelId must be a non-empty string.',
+    );
+  }
+  const normalised = stripFamilyPrefix(modelId.toLowerCase());
+  for (const rule of CLASSIFIER_RULES) {
+    if (rule.pattern.test(normalised)) return rule.tier;
+  }
+  return undefined;
+}
+
+/**
+ * Bedrock cross-region inference-profile prefix (`us.anthropic.claude-…`).
+ * Stripped so region-qualified ids hit the `^anthropic\.claude` rules
+ * (core-provider-11).
+ */
+const BEDROCK_REGION_PREFIX = /^(?:us|eu|apac|jp|au|us-gov)\./;
+
+function stripFamilyPrefix(model: string): string {
+  // Common prefixes used by adapters: `anthropic/...`, `openai/...`,
+  // `google/...`, `provider:model`, etc. Strip them so the rule
+  // patterns can stay anchored at `^`.
+  const slash = model.indexOf('/');
+  if (slash !== -1) return model.slice(slash + 1).replace(BEDROCK_REGION_PREFIX, '');
+  const deRegioned = model.replace(BEDROCK_REGION_PREFIX, '');
+  // Bedrock ids end in ':<version>' (`anthropic.claude-...-v1:0`) - the
+  // colon there is a version separator, not a provider/model split, and
+  // the rule patterns are prefix-anchored so the suffix is harmless.
+  if (deRegioned.startsWith('anthropic.')) return deRegioned;
+  const colon = deRegioned.indexOf(':');
+  if (colon !== -1 && !deRegioned.startsWith('http')) {
+    // Skip URL-like values (`http://localhost:8080`) - `:` there is a
+    // port separator, not a provider/model split.
+    return deRegioned.slice(colon + 1);
+  }
+  return deRegioned;
+}

package/src/model-tier/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Per-provider model-tier auto-classifier.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  CLASSIFIER_RULES,
+  type ClassifierRule,
+  classifyModelTier,
+} from './classify.js';

package/src/provider.ts

@@ -0,0 +1,121 @@
+/**
+ * `createProvider(...)` - wrap an adapter return value in the canonical
+ * Graphorin `Provider` shape and apply optional sensitivity / capability
+ * overrides.
+ *
+ * Adapters return a "raw" provider object; `createProvider(...)` gives
+ * downstream code a single place to centralise:
+ *
+ * - per-instance `acceptsSensitivity` declarations,
+ * - capability overrides (e.g. forcing `multimodal: false` for a tool
+ *   that does not need it),
+ * - default `reasoningRetention` resolution from the adapter's declared
+ *   `reasoningContract`,
+ * - and the agreed-upon `name` / `modelId` lock-in.
+ *
+ * @stable
+ */
+
+import type {
+  Provider,
+  ProviderCapabilities,
+  ProviderRequest,
+  ReasoningRetention,
+  Sensitivity,
+} from '@graphorin/core';
+
+import { resolveReasoningRetention } from './reasoning/retention.js';
+import { foldToolExamples } from './tool-examples.js';
+
+/**
+ * Options accepted by {@link createProvider}.
+ *
+ * @stable
+ */
+export interface CreateProviderOptions {
+  /**
+   * Sensitivity tiers this provider is allowed to receive. When
+   * unset, the value is forwarded from the wrapped adapter (which is
+   * itself populated from the trust class for `baseUrl`-driven
+   * adapters).
+   */
+  readonly acceptsSensitivity?: ReadonlyArray<Sensitivity>;
+  /**
+   * Per-request override of the reasoning-retention default. The
+   * adapter's `capabilities.reasoningContract` decides the auto-
+   * detected default; this option pins a different value for every
+   * request the wrapper sees.
+   */
+  readonly reasoningRetention?: ReasoningRetention;
+  /**
+   * Optional capability override. Useful for narrowing what a
+   * downstream tool advertises (e.g. setting `multimodal: false`
+   * when the consumer's prompt cache is text-only).
+   */
+  readonly capabilities?: Partial<ProviderCapabilities>;
+}
+
+/**
+ * Wrap an adapter in the canonical `Provider` shape. Adapters returned
+ * by the bundled factories already implement `Provider`; passing them
+ * through `createProvider(...)` is the recommended entry point because
+ * it keeps the construction site documented and gives downstream
+ * middleware a single attachment surface.
+ *
+ * @example
+ * ```ts
+ * const provider = createProvider(vercelAdapter(model), {
+ *   acceptsSensitivity: ['public', 'internal'],
+ * });
+ * ```
+ *
+ * @stable
+ */
+export function createProvider(adapter: Provider, options: CreateProviderOptions = {}): Provider {
+  const capabilities: ProviderCapabilities = {
+    ...adapter.capabilities,
+    ...options.capabilities,
+  };
+  const acceptsSensitivity = options.acceptsSensitivity ?? adapter.acceptsSensitivity ?? undefined;
+
+  const wrapped: Provider = {
+    name: adapter.name,
+    modelId: adapter.modelId,
+    capabilities,
+    ...(acceptsSensitivity ? { acceptsSensitivity } : {}),
+    stream(req) {
+      return adapter.stream(applyDefaults(req, options, capabilities));
+    },
+    generate(req) {
+      return adapter.generate(applyDefaults(req, options, capabilities));
+    },
+    ...(adapter.countTokens ? { countTokens: adapter.countTokens.bind(adapter) } : {}),
+  };
+  return wrapped;
+}
+
+function applyDefaults(
+  req: ProviderRequest,
+  options: CreateProviderOptions,
+  capabilities: ProviderCapabilities,
+): ProviderRequest {
+  let next = req;
+  // A1: fold worked tool examples into the model-facing description so the model
+  // actually sees them (the wire contract carries them; adapters never rendered
+  // them). Deterministic ⇒ the tool spec stays prompt-cache-stable.
+  if (next.tools !== undefined) {
+    const foldedTools = foldToolExamples(next.tools);
+    if (foldedTools !== next.tools) next = { ...next, tools: foldedTools };
+  }
+  const effectiveRetention = resolveReasoningRetention({
+    ...(next.reasoningRetention !== undefined ? { requested: next.reasoningRetention } : {}),
+    ...(options.reasoningRetention !== undefined ? { overridden: options.reasoningRetention } : {}),
+    ...(capabilities.reasoningContract !== undefined
+      ? { contract: capabilities.reasoningContract }
+      : {}),
+  });
+  if (effectiveRetention !== next.reasoningRetention) {
+    next = { ...next, reasoningRetention: effectiveRetention };
+  }
+  return next;
+}