@jsonstudio/llms 0.6.954 → 0.6.1172

package/dist/conversion/shared/tool-argument-repairer.js

@@ -0,0 +1,56 @@
+/**
+ * Tool Argument Repairer
+ *
+ * Tool calls require `function.arguments` to be a JSON string. Models often emit JSON-ish
+ * payloads (single quotes, fenced blocks, comments, trailing commas, etc.).
+ *
+ * This module provides a deterministic, best-effort repair surface that returns a JSON string
+ * or `{}` and never throws.
+ */
+import { repairArgumentsToString } from './jsonish.js';
+export class ToolArgumentRepairer {
+    repairToString(args) {
+        return repairArgumentsToString(args);
+    }
+    validateAndRepair(toolName, args) {
+        const repaired = this.repairToString(args);
+        try {
+            JSON.parse(repaired);
+            return {
+                repaired,
+                success: true
+            };
+        }
+        catch (error) {
+            return {
+                repaired,
+                success: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    /**
+     * 批量修复工具参数
+     *
+     * @param toolCalls - 工具调用列表
+     * @returns 修复后的工具调用列表
+     */
+    repairToolCalls(toolCalls) {
+        return toolCalls.map((call) => ({
+            name: call.name,
+            arguments: this.repairToString(call.arguments)
+        }));
+    }
+}
+/**
+ * 快捷函数：修复工具参数
+ */
+export function repairToolArguments(args) {
+    return new ToolArgumentRepairer().repairToString(args);
+}
+/**
+ * 快捷函数：验证并修复工具参数
+ */
+export function validateToolArguments(toolName, args) {
+    return new ToolArgumentRepairer().validateAndRepair(toolName, args);
+}

package/dist/conversion/shared/tool-call-id-manager.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Tool Call ID Manager
+ *
+ * 提供统一的工具调用 ID 生成、规范化和风格管理功能。
+ * 支持 'fc' (function call) 和 'preserve' 两种风格。
+ */
+import type { JsonObject } from '../hub/types/json.js';
+export type ToolCallIdStyle = 'fc' | 'preserve';
+export interface ToolCallIdManagerOptions {
+    /**
+     * ID 风格
+     * - 'fc': 使用 fc_ 前缀的短 ID（如 fc_abc123）
+     * - 'preserve': 保留原始 ID
+     */
+    style?: ToolCallIdStyle;
+    /**
+     * ID 前缀（仅用于 'fc' 风格）
+     * 默认 'fc_'
+     */
+    prefix?: string;
+    /**
+     * ID 长度（仅用于 'fc' 风格）
+     * 默认 8
+     */
+    idLength?: number;
+}
+/**
+ * 工具调用 ID 管理器
+ */
+export declare class ToolCallIdManager {
+    private options;
+    private counter;
+    constructor(options?: ToolCallIdManagerOptions);
+    /**
+     * 生成新的工具调用 ID
+     */
+    generateId(): string;
+    /**
+     * 规范化工具调用 ID
+     *
+     * @param id - 原始 ID
+     * @returns 规范化后的 ID
+     */
+    normalizeId(id: string | undefined | null): string;
+    /**
+     * 规范化工具调用 ID（带别名注册）
+     *
+     * @param id - 原始 ID
+     * @param aliasMap - 别名映射（用于 preserve 风格）
+     * @returns 规范化后的 ID
+     */
+    normalizeIdWithAlias(id: string | undefined | null, aliasMap?: Map<string, string>): string;
+    /**
+     * 批量规范化工具调用 ID
+     *
+     * @param ids - ID 列表
+     * @returns 规范化后的 ID 列表
+     */
+    normalizeIds(ids: (string | undefined | null)[]): string[];
+    /**
+     * 检查 ID 是否为有效的 fc_ 风格
+     */
+    isValidFcStyle(id: string): boolean;
+    /**
+     * 从 ID 中提取基础部分（移除前缀）
+     */
+    extractBaseId(id: string): string;
+    /**
+     * 重置计数器
+     */
+    resetCounter(): void;
+    /**
+     * 获取当前配置
+     */
+    getOptions(): ToolCallIdManagerOptions;
+    /**
+     * 更新配置
+     */
+    updateOptions(options: Partial<ToolCallIdManagerOptions>): void;
+    /**
+     * 生成 UUID（用于 preserve 风格）
+     */
+    private generateUUID;
+}
+/**
+ * 规范化工具调用 ID 值
+ *
+ * @param value - ID 值（可能是字符串或其他类型）
+ * @param forceGenerate - 如果为 true，总是生成新 ID
+ * @returns 规范化后的 ID 字符串
+ */
+export declare function normalizeIdValue(value: unknown, forceGenerate?: boolean): string;
+/**
+ * 从对象中提取工具调用 ID
+ *
+ * @param obj - 包含 ID 的对象
+ * @returns 提取的 ID
+ */
+export declare function extractToolCallId(obj: unknown): string | undefined;
+/**
+ * 创建工具调用 ID 转换器（用于 Responses 格式）
+ *
+ * @param style - ID 风格
+ * @returns 转换器函数
+ */
+export declare function createToolCallIdTransformer(style: ToolCallIdStyle): ((id: string) => string) | null;
+/**
+ * 在消息列表中强制应用工具调用 ID 风格
+ *
+ * @param messages - 消息列表
+ * @param transformer - ID 转换器
+ */
+export declare function enforceToolCallIdStyle(messages: JsonObject[], transformer: (id: string) => string): void;

package/dist/conversion/shared/tool-call-id-manager.js

@@ -0,0 +1,231 @@
+/**
+ * Tool Call ID Manager
+ *
+ * 提供统一的工具调用 ID 生成、规范化和风格管理功能。
+ * 支持 'fc' (function call) 和 'preserve' 两种风格。
+ */
+const DEFAULT_OPTIONS = {
+    style: 'fc',
+    prefix: 'fc_',
+    idLength: 8
+};
+/**
+ * 工具调用 ID 管理器
+ */
+export class ToolCallIdManager {
+    options;
+    counter = 0;
+    constructor(options) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * 生成新的工具调用 ID
+     */
+    generateId() {
+        if (this.options.style === 'fc') {
+            return `${this.options.prefix}${this.counter++}`;
+        }
+        // preserve 风格：使用 UUID
+        return this.generateUUID();
+    }
+    /**
+     * 规范化工具调用 ID
+     *
+     * @param id - 原始 ID
+     * @returns 规范化后的 ID
+     */
+    normalizeId(id) {
+        if (!id) {
+            return this.generateId();
+        }
+        const trimmed = id.trim();
+        if (!trimmed) {
+            return this.generateId();
+        }
+        if (this.options.style === 'fc') {
+            // fc 风格：提取或生成 fc_ 风格 ID
+            const fcMatch = trimmed.match(/fc_([a-z0-9]+)/i);
+            if (fcMatch) {
+                return `fc_${fcMatch[1]}`;
+            }
+            // 如果不是 fc_ 风格，生成新的 fc_ ID
+            return this.generateId();
+        }
+        // preserve 风格：保留原始 ID
+        return trimmed;
+    }
+    /**
+     * 规范化工具调用 ID（带别名注册）
+     *
+     * @param id - 原始 ID
+     * @param aliasMap - 别名映射（用于 preserve 风格）
+     * @returns 规范化后的 ID
+     */
+    normalizeIdWithAlias(id, aliasMap) {
+        if (!id) {
+            return this.generateId();
+        }
+        const trimmed = id.trim();
+        if (!trimmed) {
+            return this.generateId();
+        }
+        if (this.options.style === 'fc') {
+            return this.normalizeId(id);
+        }
+        // preserve 风格：检查是否已有别名
+        if (aliasMap && aliasMap.has(trimmed)) {
+            return aliasMap.get(trimmed);
+        }
+        // 没有别名，保留原始 ID
+        return trimmed;
+    }
+    /**
+     * 批量规范化工具调用 ID
+     *
+     * @param ids - ID 列表
+     * @returns 规范化后的 ID 列表
+     */
+    normalizeIds(ids) {
+        return ids.map(id => this.normalizeId(id));
+    }
+    /**
+     * 检查 ID 是否为有效的 fc_ 风格
+     */
+    isValidFcStyle(id) {
+        return /^fc_[a-z0-9]+$/i.test(id);
+    }
+    /**
+     * 从 ID 中提取基础部分（移除前缀）
+     */
+    extractBaseId(id) {
+        if (this.options.style === 'fc') {
+            const match = id.match(/^fc_(.+)$/i);
+            return match ? match[1] : id;
+        }
+        return id;
+    }
+    /**
+     * 重置计数器
+     */
+    resetCounter() {
+        this.counter = 0;
+    }
+    /**
+     * 获取当前配置
+     */
+    getOptions() {
+        return { ...this.options };
+    }
+    /**
+     * 更新配置
+     */
+    updateOptions(options) {
+        this.options = { ...this.options, ...options };
+    }
+    /**
+     * 生成 UUID（用于 preserve 风格）
+     */
+    generateUUID() {
+        // 简单的 UUID 生成（生产环境建议使用 crypto.randomUUID()）
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+            const r = Math.random() * 16 | 0;
+            const v = c === 'x' ? r : (r & 0x3 | 0x8);
+            return v.toString(16);
+        });
+    }
+}
+/**
+ * 规范化工具调用 ID 值
+ *
+ * @param value - ID 值（可能是字符串或其他类型）
+ * @param forceGenerate - 如果为 true，总是生成新 ID
+ * @returns 规范化后的 ID 字符串
+ */
+export function normalizeIdValue(value, forceGenerate = false) {
+    if (forceGenerate) {
+        const manager = new ToolCallIdManager();
+        return manager.generateId();
+    }
+    if (typeof value === 'string' && value.trim()) {
+        return value.trim();
+    }
+    // 生成默认 ID
+    const manager = new ToolCallIdManager();
+    return manager.generateId();
+}
+/**
+ * 从对象中提取工具调用 ID
+ *
+ * @param obj - 包含 ID 的对象
+ * @returns 提取的 ID
+ */
+export function extractToolCallId(obj) {
+    if (!obj || typeof obj !== 'object') {
+        return undefined;
+    }
+    const record = obj;
+    // 按优先级查找：tool_call_id > call_id > id > tool_use_id
+    const id = record.tool_call_id ??
+        record.call_id ??
+        record.id ??
+        record.tool_use_id;
+    return typeof id === 'string' ? id : undefined;
+}
+/**
+ * 创建工具调用 ID 转换器（用于 Responses 格式）
+ *
+ * @param style - ID 风格
+ * @returns 转换器函数
+ */
+export function createToolCallIdTransformer(style) {
+    const manager = new ToolCallIdManager({ style });
+    const aliasMap = new Map();
+    if (style === 'fc') {
+        return (id) => manager.normalizeId(id);
+    }
+    if (style === 'preserve') {
+        return (id) => {
+            const normalized = manager.normalizeIdWithAlias(id, aliasMap);
+            // 如果 ID 是新的，注册别名
+            if (!aliasMap.has(id)) {
+                aliasMap.set(id, normalized);
+            }
+            return normalized;
+        };
+    }
+    return null;
+}
+/**
+ * 在消息列表中强制应用工具调用 ID 风格
+ *
+ * @param messages - 消息列表
+ * @param transformer - ID 转换器
+ */
+export function enforceToolCallIdStyle(messages, transformer) {
+    if (!messages || !Array.isArray(messages)) {
+        return;
+    }
+    for (const message of messages) {
+        if (!message || typeof message !== 'object')
+            continue;
+        const role = message.role;
+        // 处理 assistant 消息的 tool_calls
+        if (role === 'assistant' && Array.isArray(message.tool_calls)) {
+            for (const call of message.tool_calls) {
+                if (!call || typeof call !== 'object')
+                    continue;
+                const id = extractToolCallId(call);
+                if (id) {
+                    call.id = transformer(id);
+                }
+            }
+        }
+        // 处理 tool 消息的 tool_call_id
+        if (role === 'tool') {
+            const id = extractToolCallId(message);
+            if (id) {
+                message.tool_call_id = transformer(id);
+            }
+        }
+    }
+}

package/dist/conversion/shared/tool-canonicalizer.js

@@ -1,17 +1,8 @@
 // Minimal canonicalizer to ensure tool_calls invariants without altering semantics
+import { repairToolArguments } from './tool-argument-repairer.js';
 function isObject(v) {
     return !!v && typeof v === 'object' && !Array.isArray(v);
 }
-function repairArgumentsToString(args) {
-    if (typeof args === 'string')
-        return args;
-    try {
-        return JSON.stringify(args ?? {});
-    }
-    catch {
-        return String(args);
-    }
-}
 export function canonicalizeChatResponseTools(payload) {
     try {
         const out = isObject(payload) ? JSON.parse(JSON.stringify(payload)) : payload;
@@ -36,7 +27,7 @@ export function canonicalizeChatResponseTools(payload) {
                 try {
                     const fn = tc && tc.function ? tc.function : undefined;
                     if (fn)
-                        fn.arguments = repairArgumentsToString(fn.arguments);
+                        fn.arguments = repairToolArguments(fn.arguments);
                 }
                 catch { /* ignore */ }
             }

package/dist/router/virtual-router/bootstrap.js

@@ -30,6 +30,7 @@ export function bootstrapVirtualRouterConfig(input) {
     const webSearch = normalizeWebSearch(section.webSearch, routingSource);
     validateWebSearchRouting(webSearch, routingSource);
     const execCommandGuard = normalizeExecCommandGuard(section.execCommandGuard);
+    const clock = normalizeClock(section.clock);
     const { runtimeEntries, aliasIndex, modelIndex } = buildProviderRuntimeEntries(providersSource);
     const { routing, targetKeys } = expandRoutingTable(routingSource, aliasIndex);
     if (!routing.default || routing.default.length === 0) {
@@ -67,7 +68,8 @@ export function bootstrapVirtualRouterConfig(input) {
         health,
         contextRouting,
         ...(webSearch ? { webSearch } : {}),
-        ...(execCommandGuard ? { execCommandGuard } : {})
+        ...(execCommandGuard ? { execCommandGuard } : {}),
+        ...(clock ? { clock } : {})
     };
     return {
         config,
@@ -90,7 +92,31 @@ function extractVirtualRouterSection(input) {
     const contextRouting = normalizeContextRouting(section.contextRouting ?? root.contextRouting);
     const webSearch = section.webSearch ?? root.webSearch;
     const execCommandGuard = section.execCommandGuard ?? root.execCommandGuard;
-    return { providers, routing, classifier, loadBalancing, health, contextRouting, webSearch, execCommandGuard };
+    const clock = section.clock ?? root.clock;
+    return { providers, routing, classifier, loadBalancing, health, contextRouting, webSearch, execCommandGuard, clock };
+}
+function normalizeClock(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return undefined;
+    }
+    const record = raw;
+    const enabled = record.enabled === true ||
+        (typeof record.enabled === 'string' && record.enabled.trim().toLowerCase() === 'true') ||
+        (typeof record.enabled === 'number' && record.enabled === 1);
+    if (!enabled) {
+        return undefined;
+    }
+    const out = { enabled: true };
+    if (typeof record.retentionMs === 'number' && Number.isFinite(record.retentionMs) && record.retentionMs >= 0) {
+        out.retentionMs = Math.floor(record.retentionMs);
+    }
+    if (typeof record.dueWindowMs === 'number' && Number.isFinite(record.dueWindowMs) && record.dueWindowMs >= 0) {
+        out.dueWindowMs = Math.floor(record.dueWindowMs);
+    }
+    if (typeof record.tickMs === 'number' && Number.isFinite(record.tickMs) && record.tickMs >= 0) {
+        out.tickMs = Math.floor(record.tickMs);
+    }
+    return out;
 }
 function buildProviderRuntimeEntries(providers) {
     const runtimeEntries = {};
@@ -1130,9 +1156,48 @@ function normalizeLoadBalancing(input) {
             weightsEntries[key] = value;
         }
     }
-    return Object.keys(weightsEntries).length
-        ? { strategy, weights: weightsEntries }
-        : { strategy };
+    const healthWeightedRaw = asRecord(record.healthWeighted);
+    const healthWeighted = Object.keys(healthWeightedRaw).length > 0
+        ? {
+            ...(typeof healthWeightedRaw.enabled === 'boolean' ? { enabled: healthWeightedRaw.enabled } : {}),
+            ...(typeof healthWeightedRaw.recoverToBestOnRetry === 'boolean'
+                ? { recoverToBestOnRetry: healthWeightedRaw.recoverToBestOnRetry }
+                : {}),
+            ...(typeof healthWeightedRaw.baseWeight === 'number' && Number.isFinite(healthWeightedRaw.baseWeight)
+                ? { baseWeight: healthWeightedRaw.baseWeight }
+                : {}),
+            ...(typeof healthWeightedRaw.minMultiplier === 'number' && Number.isFinite(healthWeightedRaw.minMultiplier)
+                ? { minMultiplier: healthWeightedRaw.minMultiplier }
+                : {}),
+            ...(typeof healthWeightedRaw.beta === 'number' && Number.isFinite(healthWeightedRaw.beta)
+                ? { beta: healthWeightedRaw.beta }
+                : {}),
+            ...(typeof healthWeightedRaw.halfLifeMs === 'number' && Number.isFinite(healthWeightedRaw.halfLifeMs)
+                ? { halfLifeMs: healthWeightedRaw.halfLifeMs }
+                : {})
+        }
+        : undefined;
+    const contextWeightedRaw = asRecord(record.contextWeighted);
+    const contextWeighted = Object.keys(contextWeightedRaw).length > 0
+        ? {
+            ...(typeof contextWeightedRaw.enabled === 'boolean' ? { enabled: contextWeightedRaw.enabled } : {}),
+            ...(typeof contextWeightedRaw.clientCapTokens === 'number' && Number.isFinite(contextWeightedRaw.clientCapTokens)
+                ? { clientCapTokens: contextWeightedRaw.clientCapTokens }
+                : {}),
+            ...(typeof contextWeightedRaw.gamma === 'number' && Number.isFinite(contextWeightedRaw.gamma)
+                ? { gamma: contextWeightedRaw.gamma }
+                : {}),
+            ...(typeof contextWeightedRaw.maxMultiplier === 'number' && Number.isFinite(contextWeightedRaw.maxMultiplier)
+                ? { maxMultiplier: contextWeightedRaw.maxMultiplier }
+                : {})
+        }
+        : undefined;
+    return {
+        strategy,
+        ...(Object.keys(weightsEntries).length ? { weights: weightsEntries } : {}),
+        ...(healthWeighted ? { healthWeighted } : {}),
+        ...(contextWeighted ? { contextWeighted } : {})
+    };
 }
 function coerceRatio(value) {
     if (typeof value === 'number' && Number.isFinite(value)) {

package/dist/router/virtual-router/context-advisor.d.ts

@@ -16,4 +16,8 @@ export declare class ContextAdvisor {
     private hardLimit;
     configure(config?: VirtualRouterContextRoutingConfig | null): void;
     classify(pool: string[], estimatedTokens: number, resolveProfile: (key: string) => ProviderProfile): ContextAdvisorResult;
+    getConfig(): {
+        warnRatio: number;
+        hardLimit: boolean;
+    };
 }

package/dist/router/virtual-router/context-advisor.js

@@ -55,6 +55,9 @@ export class ContextAdvisor {
             allOverflow: safe.length === 0 && risky.length === 0 && overflow.length > 0
         };
     }
+    getConfig() {
+        return { warnRatio: this.warnRatio, hardLimit: this.hardLimit };
+    }
 }
 function clampWarnRatio(value) {
     if (!Number.isFinite(value)) {

package/dist/router/virtual-router/context-weighted.d.ts

@@ -0,0 +1,31 @@
+import type { ContextWeightedLoadBalancingConfig } from './types.js';
+export type ResolvedContextWeightedConfig = Required<{
+    enabled: boolean;
+    clientCapTokens: number;
+    gamma: number;
+    maxMultiplier: number;
+}>;
+/**
+ * Context-weighted constant table (defaults).
+ *
+ * Intended behavior:
+ * - Prefer smaller effective safe context windows early, so that larger windows remain available later.
+ * - Compensation is proportional by default (`gamma=1`), but capped by `maxMultiplier`.
+ *
+ * Notes:
+ * - `clientCapTokens` is the maximum effective context the client can consume, even if the model supports more.
+ * - The effective safe window is computed using ContextAdvisor's `warnRatio` and model "slack" above the client cap.
+ *   - If a model has slack >= the reserved margin, it effectively gets the full client cap as safe window.
+ */
+export declare const DEFAULT_CONTEXT_WEIGHTED_CONFIG: ResolvedContextWeightedConfig;
+export declare function resolveContextWeightedConfig(raw?: ContextWeightedLoadBalancingConfig | null): ResolvedContextWeightedConfig;
+export declare function computeEffectiveSafeWindowTokens(options: {
+    modelMaxTokens: number;
+    warnRatio: number;
+    clientCapTokens: number;
+}): number;
+export declare function computeContextMultiplier(options: {
+    effectiveSafeRefTokens: number;
+    effectiveSafeTokens: number;
+    cfg: ResolvedContextWeightedConfig;
+}): number;

package/dist/router/virtual-router/context-weighted.js

@@ -0,0 +1,54 @@
+/**
+ * Context-weighted constant table (defaults).
+ *
+ * Intended behavior:
+ * - Prefer smaller effective safe context windows early, so that larger windows remain available later.
+ * - Compensation is proportional by default (`gamma=1`), but capped by `maxMultiplier`.
+ *
+ * Notes:
+ * - `clientCapTokens` is the maximum effective context the client can consume, even if the model supports more.
+ * - The effective safe window is computed using ContextAdvisor's `warnRatio` and model "slack" above the client cap.
+ *   - If a model has slack >= the reserved margin, it effectively gets the full client cap as safe window.
+ */
+export const DEFAULT_CONTEXT_WEIGHTED_CONFIG = {
+    enabled: false,
+    clientCapTokens: 200_000,
+    gamma: 1,
+    maxMultiplier: 2
+};
+export function resolveContextWeightedConfig(raw) {
+    const enabled = raw?.enabled ?? DEFAULT_CONTEXT_WEIGHTED_CONFIG.enabled;
+    const clientCapTokens = typeof raw?.clientCapTokens === 'number' && Number.isFinite(raw.clientCapTokens) && raw.clientCapTokens > 0
+        ? Math.floor(raw.clientCapTokens)
+        : DEFAULT_CONTEXT_WEIGHTED_CONFIG.clientCapTokens;
+    const gamma = typeof raw?.gamma === 'number' && Number.isFinite(raw.gamma) && raw.gamma > 0
+        ? raw.gamma
+        : DEFAULT_CONTEXT_WEIGHTED_CONFIG.gamma;
+    const maxMultiplier = typeof raw?.maxMultiplier === 'number' && Number.isFinite(raw.maxMultiplier) && raw.maxMultiplier >= 1
+        ? raw.maxMultiplier
+        : DEFAULT_CONTEXT_WEIGHTED_CONFIG.maxMultiplier;
+    return { enabled, clientCapTokens, gamma, maxMultiplier };
+}
+export function computeEffectiveSafeWindowTokens(options) {
+    const modelMaxTokens = typeof options.modelMaxTokens === 'number' && Number.isFinite(options.modelMaxTokens) && options.modelMaxTokens > 0
+        ? Math.floor(options.modelMaxTokens)
+        : 1;
+    const clientCapTokens = typeof options.clientCapTokens === 'number' && Number.isFinite(options.clientCapTokens) && options.clientCapTokens > 0
+        ? Math.floor(options.clientCapTokens)
+        : DEFAULT_CONTEXT_WEIGHTED_CONFIG.clientCapTokens;
+    const warnRatio = typeof options.warnRatio === 'number' && Number.isFinite(options.warnRatio) && options.warnRatio > 0 && options.warnRatio < 1
+        ? options.warnRatio
+        : 0.9;
+    const effectiveMax = Math.min(modelMaxTokens, clientCapTokens);
+    const reserve = Math.ceil(effectiveMax * (1 - warnRatio));
+    const slack = Math.max(0, modelMaxTokens - clientCapTokens);
+    const reserveEff = Math.max(0, reserve - slack);
+    return Math.max(1, effectiveMax - reserveEff);
+}
+export function computeContextMultiplier(options) {
+    const ref = Math.max(1, Math.floor(options.effectiveSafeRefTokens));
+    const cur = Math.max(1, Math.floor(options.effectiveSafeTokens));
+    const ratio = ref / cur;
+    const raw = Math.pow(Math.max(1, ratio), options.cfg.gamma);
+    return Math.min(options.cfg.maxMultiplier, raw);
+}