@mupt-ai/dari-gateway 0.2.0 → 0.3.0

package/dist/telemetry/skills/shell_words.js

@@ -0,0 +1,189 @@
+import { posix, win32 } from "node:path";
+const MAX_COMMAND_TOKENS = 4_096;
+const SHELL_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/u;
+const POSIX_SHELL_WHITESPACE = /[\t\n\v\f\r ]/u;
+const POSIX_CONTROL_COMMANDS = new Set([
+    "!",
+    "[[",
+    "case",
+    "do",
+    "done",
+    "elif",
+    "else",
+    "esac",
+    "fi",
+    "for",
+    "function",
+    "if",
+    "select",
+    "then",
+    "time",
+    "until",
+    "while",
+    "{",
+    "}",
+]);
+const TRUSTED_POSIX_EXECUTABLE_DIRECTORIES = new Set([
+    "/bin",
+    "/opt/homebrew/bin",
+    "/usr/bin",
+    "/usr/local/bin",
+]);
+export function executableCommand(words) {
+    let index = 0;
+    while (index < words.length && SHELL_ASSIGNMENT.test(words[index]))
+        index += 1;
+    if (words[index] === "env") {
+        index += 1;
+        while (index < words.length
+            && (words[index].startsWith("-") || SHELL_ASSIGNMENT.test(words[index])))
+            index += 1;
+    }
+    if (words[index] === "command" || words[index] === "builtin") {
+        index += 1;
+        while (index < words.length && words[index].startsWith("-"))
+            index += 1;
+    }
+    const executable = words[index];
+    return executable === undefined
+        ? undefined
+        : { executable, args: words.slice(index + 1) };
+}
+// This lexer recognizes only the shell structure needed to identify direct
+// read commands. Unsupported substitutions and control flow fail closed.
+export function restrictedShellSegments(command, platform) {
+    const powershell = platform === "windows";
+    if ((!powershell && (command.includes("$(") || command.includes("`"))) || command.includes("\u0000")) {
+        return undefined;
+    }
+    const segments = [];
+    let words = [];
+    let word = "";
+    let wordStarted = false;
+    let quote = null;
+    let tokenCount = 0;
+    const flushWord = () => {
+        if (!wordStarted)
+            return;
+        words.push(word);
+        tokenCount += 1;
+        word = "";
+        wordStarted = false;
+    };
+    const flushSegment = (next) => {
+        flushWord();
+        if (words.length > 0)
+            segments.push({ words, next });
+        words = [];
+    };
+    for (let index = 0; index < command.length; index += 1) {
+        const character = command[index];
+        if (quote !== null) {
+            if (character === quote) {
+                quote = null;
+            }
+            else if (powershell && character === "`") {
+                index += 1;
+                if (index >= command.length)
+                    return undefined;
+                word += command[index];
+            }
+            else if (!powershell && character === "\\" && quote === '"') {
+                const escaped = command[index + 1];
+                if (escaped === undefined)
+                    return undefined;
+                if (["$", "`", '"', "\\", "\n"].includes(escaped)) {
+                    index += 1;
+                    if (escaped !== "\n")
+                        word += escaped;
+                }
+                else {
+                    word += character;
+                }
+            }
+            else {
+                word += character;
+            }
+            wordStarted = true;
+            continue;
+        }
+        if (character === "'" || character === '"') {
+            quote = character;
+            wordStarted = true;
+            continue;
+        }
+        if ((!powershell && character === "\\") || (powershell && character === "`")) {
+            index += 1;
+            if (index >= command.length)
+                return undefined;
+            if (command[index] !== "\n") {
+                word += command[index];
+                wordStarted = true;
+            }
+            continue;
+        }
+        if (POSIX_SHELL_WHITESPACE.test(character)) {
+            flushWord();
+            if (character === "\n")
+                flushSegment("\n");
+            continue;
+        }
+        if (character === "#" && !wordStarted) {
+            flushWord();
+            while (index + 1 < command.length && command[index + 1] !== "\n")
+                index += 1;
+            continue;
+        }
+        if (character === ";" || character === "|" || character === "&") {
+            const doubled = command[index + 1] === character;
+            const operator = (doubled ? character + character : character);
+            if ((character === "|" || character === "&") && doubled)
+                index += 1;
+            flushSegment(operator);
+            continue;
+        }
+        if (character === "("
+            || character === ")"
+            || character === "<"
+            || character === ">")
+            return undefined;
+        word += character;
+        wordStarted = true;
+    }
+    if (quote !== null)
+        return undefined;
+    flushWord();
+    if (words.length > 0)
+        segments.push({ words, next: null });
+    if (tokenCount > MAX_COMMAND_TOKENS
+        || segments.length > MAX_COMMAND_TOKENS
+        || (platform === "posix" && segments.some((segment) => {
+            const parsed = executableCommand(segment.words);
+            return parsed !== undefined
+                && POSIX_CONTROL_COMMANDS.has(parsed.executable);
+        })))
+        return undefined;
+    return segments;
+}
+export function trustedExecutableName(command, platform) {
+    if (!command.includes("/") && !command.includes("\\")) {
+        return command.toLowerCase();
+    }
+    if (platform === "windows") {
+        if (!win32.isAbsolute(command))
+            return undefined;
+        const normalized = win32.normalize(command);
+        const directory = win32.dirname(normalized).toLowerCase();
+        if (directory !== "c:\\windows\\system32"
+            && directory !== "c:\\program files\\powershell\\7")
+            return undefined;
+        return win32.basename(normalized).replace(/\.exe$/iu, "").toLowerCase();
+    }
+    if (!posix.isAbsolute(command))
+        return undefined;
+    const normalized = posix.normalize(command);
+    if (!TRUSTED_POSIX_EXECUTABLE_DIRECTORIES.has(posix.dirname(normalized))) {
+        return undefined;
+    }
+    return posix.basename(normalized).toLowerCase();
+}

package/dist/telemetry/tools/input.d.ts

@@ -0,0 +1,2 @@
+import type { InteractionToolCall } from "../../interaction/types.js";
+export declare function interactionToolInput(item: InteractionToolCall): Record<string, unknown> | undefined;

package/dist/telemetry/tools/input.js

@@ -0,0 +1,14 @@
+import { isRecord } from "@mupt-ai/dari-router/policy-engine";
+export function interactionToolInput(item) {
+    if (isRecord(item.input))
+        return item.input;
+    if (typeof item.input !== "string")
+        return undefined;
+    try {
+        const parsed = JSON.parse(item.input);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/telemetry/tools/observations.d.ts

@@ -0,0 +1,29 @@
+import type { InteractionOutput, InteractionRequest } from "../../interaction/types.js";
+import type { HarnessConversationIdentity } from "../../runtime/harness_identity/index.js";
+export type ToolSkillEventReport = {
+    event_type: "tool_call" | "skill_use" | "skill_load";
+    tool_call_id: string | null;
+    exchange_context_hash: string | null;
+    capability_id: string;
+    observed_name: string;
+    skill_version: null;
+    evidence_source: "model_tool_call" | "skill_content_injection" | "skill_command_expansion" | "skill_tool_activation" | "skill_file_read";
+    ordinal: number;
+};
+export type ToolResultObservationReport = {
+    tool_call_id: string;
+    exchange_context_hash: string | null;
+    ordinal: number;
+};
+export declare function toolSkillEvents(args: {
+    routerId: string;
+    request: InteractionRequest;
+    output: InteractionOutput | undefined;
+    harnessConversationIdentity?: HarnessConversationIdentity;
+    zdr: boolean;
+}): ToolSkillEventReport[];
+export declare function toolResultObservations(args: {
+    routerId: string;
+    request: InteractionRequest;
+    zdr: boolean;
+}): ToolResultObservationReport[];

package/dist/telemetry/tools/observations.js

@@ -0,0 +1,247 @@
+import { isRecord, stableStringify } from "@mupt-ai/dari-router/policy-engine";
+import { interactionPrefixChain } from "../../context/interaction_fingerprint.js";
+import { isProtocolToolCallId } from "../../interaction/tool_identity.js";
+import { anthropicMessagesToInteraction } from "../../protocol/input/anthropic_messages.js";
+import { internalChatCompletionsToInteraction } from "../../protocol/input/chat_completions.js";
+import { anthropicContent } from "../../protocol/output/anthropic_messages_output.js";
+import { assistantMessagePayload } from "../../protocol/output/chat_completions.js";
+import { inputSkillObservations, outputSkillObservations, } from "../skills/observations.js";
+const MAX_TOOL_SKILL_EVENTS = 1000;
+export function toolSkillEvents(args) {
+    if (args.zdr)
+        return [];
+    const outputEvents = (args.output?.items ?? [])
+        .flatMap((item, ordinal) => item.type === "tool_call"
+        && isProtocolToolCallId(item.callId)
+        ? [{ item, ordinal }]
+        : [])
+        .slice(0, MAX_TOOL_SKILL_EVENTS);
+    const explicitSkills = inputSkillObservations({
+        ...args,
+        limit: MAX_TOOL_SKILL_EVENTS - outputEvents.length,
+    });
+    const outputCallIds = new Set(outputEvents.map(({ item }) => item.callId));
+    const automaticSkills = args.output === undefined
+        ? []
+        : outputSkillObservations({
+            request: args.request,
+            output: args.output,
+            harnessConversationIdentity: args.harnessConversationIdentity,
+            limit: MAX_TOOL_SKILL_EVENTS,
+        }).filter((skill) => skill.toolCallId !== null
+            && outputCallIds.has(skill.toolCallId)).slice(0, MAX_TOOL_SKILL_EVENTS - outputEvents.length - explicitSkills.length);
+    if (explicitSkills.length === 0
+        && automaticSkills.length === 0
+        && outputEvents.length === 0)
+        return [];
+    const exchangeContextHash = outputEvents.length === 0 || args.output === undefined
+        ? null
+        : outputExchangeContextHash(args.routerId, args.request, args.output);
+    const reportedExplicitSkills = explicitSkills.map((skill, ordinal) => ({
+        event_type: skill.eventType,
+        tool_call_id: skill.toolCallId,
+        exchange_context_hash: null,
+        capability_id: skill.capabilityId,
+        observed_name: skill.observedName,
+        skill_version: null,
+        evidence_source: skill.evidenceSource,
+        ordinal,
+    }));
+    const reportedAutomaticSkills = automaticSkills.map((skill, ordinal) => ({
+        event_type: skill.eventType,
+        tool_call_id: skill.toolCallId,
+        exchange_context_hash: exchangeContextHash,
+        capability_id: skill.capabilityId,
+        observed_name: skill.observedName,
+        skill_version: null,
+        evidence_source: skill.evidenceSource,
+        ordinal: explicitSkills.length + ordinal,
+    }));
+    const skillCount = explicitSkills.length + automaticSkills.length;
+    const reportedOutputEvents = outputEvents.map(({ item, ordinal }) => {
+        const observedName = item.namespace
+            ? `${item.namespace}.${item.name}`
+            : item.name;
+        return {
+            event_type: "tool_call",
+            tool_call_id: item.callId,
+            exchange_context_hash: exchangeContextHash,
+            capability_id: observedName,
+            observed_name: observedName,
+            skill_version: null,
+            evidence_source: "model_tool_call",
+            ordinal: skillCount + ordinal,
+        };
+    });
+    return [
+        ...reportedExplicitSkills,
+        ...reportedAutomaticSkills,
+        ...reportedOutputEvents,
+    ];
+}
+export function toolResultObservations(args) {
+    if (args.zdr)
+        return [];
+    const submitted = newlySubmittedToolResults(args.request);
+    if (submitted.results.length === 0)
+        return [];
+    const requestBeforeResults = {
+        ...args.request,
+        items: args.request.items.slice(0, submitted.contextEnd),
+    };
+    const exchangeContextHash = interactionPrefixChain(args.routerId, normalizeExchangeRequest(requestBeforeResults), null).at(-1) ??
+        null;
+    return submitted.results.slice(0, 1000).map(({ item, ordinal }) => ({
+        tool_call_id: item.callId,
+        exchange_context_hash: exchangeContextHash,
+        ordinal,
+    }));
+}
+function newlySubmittedToolResults(request) {
+    if (request.sourceProtocol === "anthropic_messages") {
+        return currentAnthropicUserTurnResults(request.items);
+    }
+    const results = [];
+    for (let ordinal = request.items.length - 1; ordinal >= 0; ordinal -= 1) {
+        const item = request.items[ordinal];
+        if (item.type !== "tool_result")
+            break;
+        if (isProtocolToolCallId(item.callId))
+            results.push({ item, ordinal });
+    }
+    const ordered = results.reverse();
+    return {
+        results: ordered,
+        contextEnd: ordered[0]?.ordinal ?? request.items.length,
+    };
+}
+function currentAnthropicUserTurnResults(items) {
+    const results = [];
+    let contextEnd = 0;
+    for (let ordinal = items.length - 1; ordinal >= 0; ordinal -= 1) {
+        const item = items[ordinal];
+        if (isAssistantOutputItem(item)) {
+            contextEnd = ordinal + 1;
+            break;
+        }
+        if (item.type === "tool_result" && isProtocolToolCallId(item.callId)) {
+            results.push({ item, ordinal });
+        }
+    }
+    return { results: results.reverse(), contextEnd };
+}
+function isAssistantOutputItem(item) {
+    return item.type === "reasoning"
+        || item.type === "tool_call"
+        || item.type === "hosted_tool_call"
+        || (item.type === "message" && item.role === "assistant");
+}
+function outputExchangeContextHash(routerId, request, output) {
+    const outputItems = clientVisibleOutputItems(request.sourceProtocol, output);
+    const completedRequest = normalizeExchangeRequest({
+        ...request,
+        items: [...request.items, ...outputItems],
+    });
+    return interactionPrefixChain(routerId, completedRequest, null).at(-1) ?? null;
+}
+function clientVisibleOutputItems(sourceProtocol, output) {
+    if (sourceProtocol === "openai_chat") {
+        return internalChatCompletionsToInteraction({
+            model: "dari/routing",
+            messages: [assistantMessagePayload(output)],
+        }).items;
+    }
+    if (sourceProtocol === "anthropic_messages") {
+        return anthropicMessagesToInteraction({
+            model: "dari/routing",
+            max_tokens: 1,
+            messages: [{ role: "assistant", content: anthropicContent(output) }],
+        }).items;
+    }
+    return output.items;
+}
+function normalizeExchangeRequest(request) {
+    // Claude Code may omit thinking blocks when it submits tool results even
+    // though those blocks were present in the preceding Anthropic response.
+    const items = request.sourceProtocol === "anthropic_messages"
+        ? request.items.filter((item) => item.type !== "reasoning")
+        : request.items;
+    return {
+        ...request,
+        instructions: undefined,
+        tools: [],
+        items: items.map(normalizeExchangeItem),
+    };
+}
+// Correlation follows semantic tool history, not wire-only item IDs, message
+// phases, content container shapes, or JSON object insertion order.
+function normalizeExchangeItem(item) {
+    if (item.type === "reasoning") {
+        const { id: _id, ...rest } = item;
+        return rest;
+    }
+    if (item.type === "message") {
+        const { id: _id, phase: _phase, ...rest } = item;
+        return {
+            ...rest,
+            ...normalizeContent(item.content, item.contentShape, item.role === "assistant"),
+        };
+    }
+    if (item.type === "tool_call") {
+        const { id: _id, ...rest } = item;
+        return {
+            ...rest,
+            input: normalizeFunctionInput(item.kind, item.input),
+        };
+    }
+    if (item.type === "tool_result") {
+        const { id: _id, ...rest } = item;
+        if (!Array.isArray(item.output))
+            return rest;
+        const normalized = normalizeContent(item.output, item.outputShape);
+        return { ...rest, output: normalized.content, outputShape: normalized.contentShape };
+    }
+    if (item.type === "hosted_tool_call") {
+        const { id: _id, source: _source, payload: { id: _payloadId, status: _payloadStatus, ...payload }, ...rest } = item;
+        return {
+            ...rest,
+            id: "",
+            payload: item.status ? { ...payload, status: item.status } : payload,
+        };
+    }
+    return item;
+}
+function normalizeContent(content, contentShape, collapseEmpty = false) {
+    if (collapseEmpty
+        && content.every((part) => part.type === "text" && part.text.length === 0 && !part.annotations?.length)) {
+        return { content: [], contentShape: "null" };
+    }
+    if (contentShape === "null" || contentShape === "absent") {
+        return { content, contentShape };
+    }
+    if (content.every((part) => part.type === "text" && !part.annotations?.length)) {
+        return {
+            content: [{
+                    type: "text",
+                    text: content
+                        .map((part) => (part.type === "text" ? part.text : ""))
+                        .join(""),
+                }],
+            contentShape: "string",
+        };
+    }
+    return { content, contentShape: "parts" };
+}
+function normalizeFunctionInput(kind, input) {
+    if (kind === "custom" || input === undefined)
+        return input;
+    if (isRecord(input))
+        return stableStringify(input);
+    try {
+        const parsed = JSON.parse(input);
+        return isRecord(parsed) ? stableStringify(parsed) : input;
+    }
+    catch {
+        return input;
+    }
+}

package/dist/telemetry/usage.d.ts

@@ -0,0 +1,57 @@
+import type { Provider } from "@mupt-ai/dari-router/policy-engine";
+import { HttpError } from "../http/errors.js";
+import { type RequestTags } from "../platform/platform.js";
+import type { ProviderKeySource, ResolvedRouter } from "../types.js";
+export type RoutingUsageContext = {
+    organizationId: string;
+    routerId: string;
+    provider: Provider;
+    model: string;
+    tags: RequestTags;
+    startedAt: Date;
+};
+/**
+ * Reject requests that need model selection when the organization is not on
+ * the Autorouting plan. Without it, Gateway serves only routers with a single
+ * model and thinking level, which never invoke the selector.
+ */
+export declare function assertAutoroutingAllowed(credentials: ResolvedRouter, selects: boolean): void;
+/**
+ * Whether the router offers more than one model/thinking-level pair. A model
+ * without listed levels serves every level it supports, so it counts as
+ * selecting, matching candidate preparation and the CLI.
+ */
+export declare function routerSelectsModels(credentials: ResolvedRouter): boolean;
+/**
+ * Reject billable requests before the routing decision once the org's
+ * credits are exhausted, unless a personal subscription serves one of the
+ * router's models: those owe no credits, so they keep serving and routing
+ * narrows to them. Managed and own-key requests stay gated (own-key requests
+ * owe the router fee), and refusing before selection keeps an exhausted org
+ * from burning selector-model spend.
+ */
+export declare function assertCreditAvailableBeforeRouting(billable: boolean, credentials: ResolvedRouter): void;
+/**
+ * Decide whether this routed call bills org credits: returns the usage
+ * context for billable managed-key selections and undefined otherwise.
+ * Throws 402 when the selection needs a managed key while the org's
+ * credits are exhausted.
+ */
+export declare function usageContextFor(args: {
+    billable: boolean;
+    credentials: ResolvedRouter;
+    routerId: string;
+    selectedModel: string;
+    keySource: ProviderKeySource;
+    tags: RequestTags;
+}): RoutingUsageContext | undefined;
+/**
+ * Bill one managed-key routed call to the org's credits through the
+ * platform. Stream billing calls this from the protocol stream's onFinal hook; the
+ * non-stream path awaits it before responding. Never throws: the provider
+ * spend already happened, so a recording failure must not fail an
+ * otherwise-successful completion — it is logged and reported operationally
+ * instead.
+ */
+export declare function reportRoutingUsage(context: RoutingUsageContext, message: Record<string, unknown>): Promise<void>;
+export declare function creditExhaustedError(): HttpError;

package/dist/telemetry/usage.js

@@ -0,0 +1,136 @@
+import { randomUUID } from "node:crypto";
+import { HttpError } from "../http/errors.js";
+import { executionProviderForModel, keySourceForModel } from "../models/execution_provider.js";
+import { captureOperationalError } from "../observability/errors.js";
+import { gatewayPlatform } from "../platform/platform.js";
+/**
+ * Reject requests that need model selection when the organization is not on
+ * the Autorouting plan. Without it, Gateway serves only routers with a single
+ * model and thinking level, which never invoke the selector.
+ */
+export function assertAutoroutingAllowed(credentials, selects) {
+    if (selects && credentials.autorouting_enabled === false) {
+        throw new HttpError(402, "Autorouting requires the Autorouting plan. Subscribe at https://app.dari.dev/usage, or keep one model and thinking level on this router.", "autorouting_plan_required");
+    }
+}
+/**
+ * Whether the router offers more than one model/thinking-level pair. A model
+ * without listed levels serves every level it supports, so it counts as
+ * selecting, matching candidate preparation and the CLI.
+ */
+export function routerSelectsModels(credentials) {
+    let pairs = 0;
+    for (const model of credentials.enabled_models) {
+        const levels = credentials.model_thinking_levels?.[model]?.length ?? 0;
+        if (levels === 0)
+            return true;
+        pairs += levels;
+    }
+    return pairs > 1;
+}
+/**
+ * Reject billable requests before the routing decision once the org's
+ * credits are exhausted, unless a personal subscription serves one of the
+ * router's models: those owe no credits, so they keep serving and routing
+ * narrows to them. Managed and own-key requests stay gated (own-key requests
+ * owe the router fee), and refusing before selection keeps an exhausted org
+ * from burning selector-model spend.
+ */
+export function assertCreditAvailableBeforeRouting(billable, credentials) {
+    if (billable &&
+        credentials.credit_exhausted &&
+        !credentials.enabled_models.some((model) => keySourceForModel(credentials, model) === "subscription")) {
+        throw creditExhaustedError();
+    }
+}
+/**
+ * Decide whether this routed call bills org credits: returns the usage
+ * context for billable managed-key selections and undefined otherwise.
+ * Throws 402 when the selection needs a managed key while the org's
+ * credits are exhausted.
+ */
+export function usageContextFor(args) {
+    if (!args.billable || args.keySource !== "managed")
+        return undefined;
+    if (args.credentials.credit_exhausted)
+        throw creditExhaustedError();
+    return {
+        organizationId: args.credentials.organization_id,
+        routerId: args.routerId,
+        provider: executionProviderForModel(args.credentials, args.selectedModel),
+        model: args.selectedModel,
+        tags: args.tags,
+        startedAt: new Date(),
+    };
+}
+/**
+ * Bill one managed-key routed call to the org's credits through the
+ * platform. Stream billing calls this from the protocol stream's onFinal hook; the
+ * non-stream path awaits it before responding. Never throws: the provider
+ * spend already happened, so a recording failure must not fail an
+ * otherwise-successful completion — it is logged and reported operationally
+ * instead.
+ */
+export async function reportRoutingUsage(context, message) {
+    const payload = usagePayload(context, message);
+    if (payload.total_cost_usd === "0") {
+        console.error("Routing usage billed at zero cost; model pricing may be missing.", usageLogFields(payload));
+    }
+    try {
+        await gatewayPlatform().recordUsage(payload);
+    }
+    catch (error) {
+        reportUsageFailure(error, payload);
+    }
+}
+function reportUsageFailure(error, payload) {
+    console.error("Routing usage not recorded.", usageLogFields(payload));
+    captureOperationalError(error, {
+        code: "billing_usage_report_failed",
+        routerId: typeof payload.router_id === "string" ? payload.router_id : undefined,
+    });
+}
+export function creditExhaustedError() {
+    return new HttpError(402, "Organization credits are exhausted.", "credit_exhausted");
+}
+function usagePayload(context, message) {
+    const usage = isRecord(message.usage) ? message.usage : {};
+    const cost = isRecord(usage.cost) ? usage.cost : {};
+    const responseId = typeof message.responseId === "string" && message.responseId ? message.responseId : undefined;
+    return {
+        organization_id: context.organizationId,
+        router_id: context.routerId,
+        provider: context.provider,
+        model: context.model,
+        provider_request_id: responseId ?? `routing-${randomUUID()}`,
+        input_tokens: tokens(usage.input),
+        cached_input_tokens: tokens(usage.cacheRead),
+        output_tokens: tokens(usage.output),
+        usage_estimated: usage.estimated === true,
+        input_cost_usd: usd(cost.input),
+        cached_input_cost_usd: usd(cost.cacheRead),
+        output_cost_usd: usd(cost.output),
+        total_cost_usd: usd(cost.total) ?? "0",
+        started_at: context.startedAt.toISOString(),
+        ended_at: new Date().toISOString(),
+        tags: context.tags,
+    };
+}
+function usageLogFields(payload) {
+    return {
+        organization_id: payload.organization_id,
+        router_id: payload.router_id,
+        provider_request_id: payload.provider_request_id,
+        model: payload.model,
+        total_cost_usd: payload.total_cost_usd,
+    };
+}
+function tokens(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.trunc(value) : 0;
+}
+function usd(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? String(value) : null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}