@graphorin/provider 0.6.0 → 0.7.0

package/src/counters/anthropic-wire.ts

@@ -0,0 +1,199 @@
+/**
+ * Conversion from Graphorin messages to the Anthropic Messages API
+ * wire shape, used by `AnthropicAPICounter` (core-provider-04).
+ *
+ * The `count_tokens` endpoint accepts the same body as `/v1/messages`:
+ * only `user` / `assistant` roles in `messages`, system prompts in the
+ * top-level `system` field, assistant tool calls as `tool_use` blocks,
+ * tool results as `tool_result` blocks inside a **user** turn, and
+ * images as `source` blocks. Posting Graphorin-shaped messages 400s on
+ * any transcript containing a system / tool message or `toolCalls`,
+ * silently downgrading the "native" counter to tiktoken.
+ *
+ * @internal
+ */
+
+import type { Message, MessageContent } from '@graphorin/core';
+
+/** Anthropic-shaped count_tokens payload. */
+export interface AnthropicCountPayload {
+  readonly system?: string;
+  readonly messages: ReadonlyArray<{
+    readonly role: 'user' | 'assistant';
+    readonly content: ReadonlyArray<Readonly<Record<string, unknown>>>;
+  }>;
+}
+
+/**
+ * Convert Graphorin messages to the Anthropic wire shape. Returns
+ * `null` when nothing countable remains (the caller should use its
+ * local fallback instead of paying an HTTP round trip for a 400).
+ *
+ * Consecutive same-role turns are merged and the transcript is forced
+ * to start with a user turn - both hard requirements of the API.
+ * Parts with no wire representation for counting purposes (audio,
+ * non-PDF files, unsigned reasoning) are skipped; the count is then a
+ * slight undercount rather than a guaranteed 400.
+ *
+ * @internal
+ */
+export function toAnthropicCountPayload(
+  messages: ReadonlyArray<Message>,
+): AnthropicCountPayload | null {
+  const systemParts: string[] = [];
+  const turns: Array<{ role: 'user' | 'assistant'; content: Array<Record<string, unknown>> }> = [];
+
+  const pushBlocks = (role: 'user' | 'assistant', blocks: Array<Record<string, unknown>>): void => {
+    if (blocks.length === 0) return;
+    const last = turns[turns.length - 1];
+    if (last !== undefined && last.role === role) {
+      last.content.push(...blocks);
+      return;
+    }
+    turns.push({ role, content: blocks });
+  };
+
+  for (const msg of messages) {
+    switch (msg.role) {
+      case 'system':
+        if (msg.content.length > 0) systemParts.push(msg.content);
+        break;
+      case 'user':
+        pushBlocks('user', contentToBlocks(msg.content, 'user'));
+        break;
+      case 'assistant': {
+        const blocks = contentToBlocks(msg.content, 'assistant');
+        for (const call of msg.toolCalls ?? []) {
+          blocks.push({
+            type: 'tool_use',
+            id: call.toolCallId,
+            name: call.toolName,
+            input: toInputObject(call.args),
+          });
+        }
+        pushBlocks('assistant', blocks);
+        break;
+      }
+      case 'tool': {
+        // Tool results live in the next USER turn on the Anthropic wire.
+        const text = flattenToText(msg.content);
+        pushBlocks('user', [
+          {
+            type: 'tool_result',
+            tool_use_id: msg.toolCallId,
+            ...(text.length > 0 ? { content: [{ type: 'text', text }] } : {}),
+          },
+        ]);
+        break;
+      }
+    }
+  }
+
+  if (turns.length === 0 && systemParts.length === 0) return null;
+  // The API requires the first message to be a user turn.
+  if (turns.length === 0 || turns[0]?.role !== 'user') {
+    turns.unshift({ role: 'user', content: [{ type: 'text', text: '.' }] });
+  }
+  return {
+    ...(systemParts.length > 0 ? { system: systemParts.join('\n\n') } : {}),
+    messages: turns,
+  };
+}
+
+function contentToBlocks(
+  content: string | ReadonlyArray<MessageContent>,
+  role: 'user' | 'assistant',
+): Array<Record<string, unknown>> {
+  if (typeof content === 'string') {
+    return content.length > 0 ? [{ type: 'text', text: content }] : [];
+  }
+  const blocks: Array<Record<string, unknown>> = [];
+  for (const part of content) {
+    switch (part.type) {
+      case 'text':
+        if (part.text.length > 0) blocks.push({ type: 'text', text: part.text });
+        break;
+      case 'image': {
+        const source = toImageSource(part.image, part.mimeType);
+        if (source !== null && role === 'user') blocks.push({ type: 'image', source });
+        break;
+      }
+      case 'file': {
+        // PDFs count as document blocks; other file kinds have no
+        // countable wire form and are skipped.
+        if (part.mimeType === 'application/pdf' && part.file instanceof Uint8Array) {
+          blocks.push({
+            type: 'document',
+            source: {
+              type: 'base64',
+              media_type: 'application/pdf',
+              data: toBase64(part.file),
+            },
+          });
+        }
+        break;
+      }
+      case 'reasoning': {
+        // Only signed thinking blocks round-trip through the API;
+        // unsigned reasoning would 400, so it is skipped (the default
+        // retention policy strips it from outbound requests anyway).
+        if (
+          role === 'assistant' &&
+          part.meta?.provider === 'anthropic' &&
+          typeof part.meta.signature === 'string'
+        ) {
+          blocks.push({ type: 'thinking', thinking: part.text, signature: part.meta.signature });
+        }
+        break;
+      }
+      case 'audio':
+        // No audio block on the Messages API; skip.
+        break;
+    }
+  }
+  return blocks;
+}
+
+function toImageSource(
+  image: Uint8Array | URL,
+  mimeType: string | undefined,
+): Record<string, unknown> | null {
+  if (image instanceof URL) {
+    return { type: 'url', url: image.toString() };
+  }
+  if (image instanceof Uint8Array) {
+    return {
+      type: 'base64',
+      media_type: mimeType ?? 'image/png',
+      data: toBase64(image),
+    };
+  }
+  return null;
+}
+
+function toBase64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64');
+}
+
+function toInputObject(args: unknown): Record<string, unknown> {
+  if (typeof args === 'string') {
+    try {
+      const parsed: unknown = JSON.parse(args);
+      return typeof parsed === 'object' && parsed !== null
+        ? (parsed as Record<string, unknown>)
+        : {};
+    } catch {
+      return {};
+    }
+  }
+  return typeof args === 'object' && args !== null ? (args as Record<string, unknown>) : {};
+}
+
+function flattenToText(content: string | ReadonlyArray<MessageContent>): string {
+  if (typeof content === 'string') return content;
+  const buffer: string[] = [];
+  for (const part of content) {
+    if (part.type === 'text' || part.type === 'reasoning') buffer.push(part.text);
+  }
+  return buffer.join('');
+}

package/src/counters/anthropic.ts

@@ -0,0 +1,114 @@
+/**
+ * `AnthropicAPICounter` - uses Anthropic's native count-tokens
+ * endpoint when an API key is configured, otherwise falls back to
+ * `JsTiktokenCounter`. The native call is opt-in: the user supplies
+ * an explicit `apiKey`. The framework never makes the call without
+ * one.
+ *
+ * @packageDocumentation
+ */
+
+import type { Message, TokenCounter } from '@graphorin/core';
+
+import { stripTrailingSlashes } from '../internal/url-utils.js';
+import { toAnthropicCountPayload } from './anthropic-wire.js';
+import { JsTiktokenCounter } from './js-tiktoken.js';
+
+/**
+ * Options for {@link AnthropicAPICounter}.
+ *
+ * @stable
+ */
+export interface AnthropicAPICounterOptions {
+  readonly modelId: string;
+  readonly apiKey?: string;
+  readonly baseUrl?: string;
+  readonly fetchImpl?: typeof fetch;
+  /** Identifier carried on the produced counter. */
+  readonly id?: string;
+  /**
+   * Log sink for the WARN emitted (once per counter) when the native
+   * call degrades to the tiktoken fallback. Defaults to `console.warn`.
+   */
+  readonly logger?: (message: string, meta?: object) => void;
+}
+
+/**
+ * Counter that talks to `POST /v1/messages/count_tokens` when an API
+ * key is configured. Without an API key, the counter delegates to
+ * `JsTiktokenCounter('cl100k_base')` - the closest publicly-available
+ * proxy for Anthropic's tokenizer.
+ *
+ * @stable
+ */
+export class AnthropicAPICounter implements TokenCounter {
+  readonly id: string;
+  readonly version: string;
+  readonly #modelId: string;
+  readonly #apiKey?: string;
+  readonly #baseUrl: string;
+  readonly #fetchImpl: typeof fetch;
+  readonly #fallback: JsTiktokenCounter;
+  readonly #logger: (message: string, meta?: object) => void;
+  #fallbackWarned = false;
+
+  constructor(options: AnthropicAPICounterOptions) {
+    this.#modelId = options.modelId;
+    if (options.apiKey !== undefined) this.#apiKey = options.apiKey;
+    this.#baseUrl = stripTrailingSlashes(options.baseUrl ?? 'https://api.anthropic.com');
+    this.#fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.#fallback = new JsTiktokenCounter({ encoding: 'cl100k_base', modelId: options.modelId });
+    this.#logger = options.logger ?? ((message, meta) => console.warn(message, meta ?? ''));
+    this.id = options.id ?? `anthropic-native@${options.modelId}`;
+    this.version = `anthropic-native-${options.modelId}-v1`;
+  }
+
+  async count(messages: ReadonlyArray<Message>): Promise<number> {
+    if (this.#apiKey === undefined) return this.#fallback.count(messages);
+    // core-provider-04: the endpoint accepts only Anthropic wire-shaped
+    // bodies. Posting Graphorin messages 400s on any transcript with a
+    // system / tool message or `toolCalls`, so convert first.
+    const payload = toAnthropicCountPayload(messages);
+    if (payload === null) return this.#fallback.count(messages);
+    try {
+      const resp = await this.#fetchImpl(`${this.#baseUrl}/v1/messages/count_tokens`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'x-api-key': this.#apiKey,
+          'anthropic-version': '2023-06-01',
+        },
+        body: JSON.stringify({ model: this.#modelId, ...payload }),
+      });
+      if (!resp.ok) {
+        this.#warnFallback(`HTTP ${resp.status}`);
+        return this.#fallback.count(messages);
+      }
+      const json = (await resp.json()) as { input_tokens?: number };
+      if (typeof json.input_tokens === 'number') return json.input_tokens;
+      this.#warnFallback('response missing input_tokens');
+      return this.#fallback.count(messages);
+    } catch (cause) {
+      this.#warnFallback((cause as Error).message);
+      return this.#fallback.count(messages);
+    }
+  }
+
+  async countText(text: string): Promise<number> {
+    return this.#fallback.countText(text);
+  }
+
+  /**
+   * WARN once per counter when the native path degrades - a silent
+   * fallback to cl100k tiktoken undercounts Claude tokens by ~15-20%,
+   * so the degradation must be visible.
+   */
+  #warnFallback(reason: string): void {
+    if (this.#fallbackWarned) return;
+    this.#fallbackWarned = true;
+    this.#logger(
+      `[graphorin/provider] AnthropicAPICounter(${this.#modelId}): native count_tokens failed (${reason}); ` +
+        'falling back to cl100k tiktoken (undercounts Claude by ~15-20%). Further fallbacks are silent.',
+    );
+  }
+}

package/src/counters/bedrock.ts

@@ -0,0 +1,46 @@
+/**
+ * `BedrockAPICounter` - placeholder counter that delegates to
+ * `JsTiktokenCounter('cl100k_base')` for now (Bedrock's native
+ * `count_tokens` API requires AWS Signature v4; full integration
+ * lands in Phase 16). The proxy is sufficient for v0.1 within the
+ * documented ±5% accuracy envelope.
+ *
+ * @packageDocumentation
+ */
+
+import type { Message, TokenCounter } from '@graphorin/core';
+
+import { JsTiktokenCounter } from './js-tiktoken.js';
+
+/**
+ * Options for {@link BedrockAPICounter}.
+ *
+ * @stable
+ */
+export interface BedrockAPICounterOptions {
+  readonly modelId: string;
+  readonly id?: string;
+}
+
+/**
+ * @stable
+ */
+export class BedrockAPICounter implements TokenCounter {
+  readonly id: string;
+  readonly version: string;
+  readonly #fallback: JsTiktokenCounter;
+
+  constructor(options: BedrockAPICounterOptions) {
+    this.#fallback = new JsTiktokenCounter({ encoding: 'cl100k_base', modelId: options.modelId });
+    this.id = options.id ?? `bedrock-proxy@${options.modelId}`;
+    this.version = `bedrock-cl100k-proxy-${options.modelId}-v1`;
+  }
+
+  count(messages: ReadonlyArray<Message>): Promise<number> {
+    return this.#fallback.count(messages);
+  }
+
+  countText(text: string): Promise<number> {
+    return this.#fallback.countText(text);
+  }
+}

package/src/counters/dispatcher.ts

@@ -0,0 +1,127 @@
+/**
+ * `createDefaultCounter` - model-id classifier that returns the
+ * recommended {@link TokenCounter} for a given `(provider, model)`
+ * pair. The same classifier is reused by the model-tier dispatcher
+ * (`@graphorin/provider/model-tier`) so provider-family detection
+ * lives in exactly one place.
+ *
+ * @packageDocumentation
+ */
+
+import type { TokenCounter } from '@graphorin/core';
+
+import { AnthropicAPICounter } from './anthropic.js';
+import { BedrockAPICounter } from './bedrock.js';
+import { GoogleAPICounter } from './google.js';
+import { HeuristicCounter } from './heuristic.js';
+import { JsTiktokenCounter } from './js-tiktoken.js';
+
+/**
+ * Options for {@link createDefaultCounter}.
+ *
+ * @stable
+ */
+export interface CreateDefaultCounterOptions {
+  /** Concrete model id (e.g. `'gpt-4o'`, `'claude-opus-4-7'`). */
+  readonly model: string;
+  /** Optional provider hint to short-circuit the regex matching. */
+  readonly provider?: string;
+  /** Optional Anthropic API key threaded through to {@link AnthropicAPICounter}. */
+  readonly anthropicApiKey?: string;
+}
+
+/**
+ * Detect the provider family for a model id. Exposed for downstream
+ * consumers (the model-tier classifier; future per-tool counters) so
+ * provider-family detection is centralised here.
+ *
+ * @stable
+ */
+export function detectProviderFamily(args: {
+  readonly model: string;
+  readonly provider?: string;
+}): 'anthropic' | 'openai' | 'google' | 'bedrock' | 'ollama' | 'openai-compatible' | 'unknown' {
+  const provider = args.provider?.toLowerCase();
+  // Strip the Bedrock cross-region inference-profile prefix
+  // (`us.anthropic.claude-…`) so region-qualified ids classify like
+  // their bare form (core-provider-11).
+  const modelLower = args.model.toLowerCase().replace(/^(?:us|eu|apac|jp|au|us-gov)\./, '');
+  // The AI SDK reports dotted provider ids ('anthropic.messages',
+  // 'amazon-bedrock.messages'), so match by prefix / substring.
+  const providerIsAnthropic = provider?.startsWith('anthropic');
+  const providerIsBedrock = provider?.includes('bedrock');
+  if (
+    providerIsAnthropic ||
+    modelLower.startsWith('claude') ||
+    modelLower.startsWith('anthropic.claude')
+  ) {
+    if (providerIsBedrock || modelLower.startsWith('anthropic.claude')) return 'bedrock';
+    return 'anthropic';
+  }
+  if (provider === 'google' || modelLower.startsWith('gemini')) return 'google';
+  if (providerIsBedrock) return 'bedrock';
+  if (provider === 'openai' || provider === 'azure-openai' || /^(gpt-|o1|o3|o4)/.test(modelLower)) {
+    return 'openai';
+  }
+  if (provider === 'ollama' || modelLower.startsWith('ollama-')) return 'ollama';
+  if (provider === 'openai-compatible' || provider === 'lmstudio' || provider === 'vllm') {
+    return 'openai-compatible';
+  }
+  return 'unknown';
+}
+
+/**
+ * Build the recommended {@link TokenCounter} for the given
+ * `(provider, model)` pair. The dispatch table:
+ *
+ * - Anthropic Claude → `AnthropicAPICounter` (native if `apiKey` set,
+ *   otherwise `cl100k_base` proxy).
+ * - OpenAI / OpenAI-compatible → `JsTiktokenCounter('cl100k_base')`.
+ * - Google Gemini → `GoogleAPICounter` (cl100k_base proxy in v0.1).
+ * - Bedrock Claude → `BedrockAPICounter` (cl100k_base proxy in v0.1).
+ * - Ollama / unknown → `HeuristicCounter` with one WARN per process.
+ *
+ * @stable
+ */
+export function createDefaultCounter(options: CreateDefaultCounterOptions): TokenCounter {
+  const family = detectProviderFamily({
+    model: options.model,
+    ...(options.provider !== undefined ? { provider: options.provider } : {}),
+  });
+  switch (family) {
+    case 'anthropic':
+      return new AnthropicAPICounter({
+        modelId: options.model,
+        ...(options.anthropicApiKey !== undefined ? { apiKey: options.anthropicApiKey } : {}),
+      });
+    case 'bedrock':
+      return new BedrockAPICounter({ modelId: options.model });
+    case 'google':
+      return new GoogleAPICounter({ modelId: options.model });
+    case 'openai':
+    case 'openai-compatible':
+      return new JsTiktokenCounter({
+        encoding: defaultOpenAiEncoding(options.model),
+        modelId: options.model,
+      });
+    default:
+      return new HeuristicCounter({ modelId: options.model });
+  }
+}
+
+/**
+ * PS-20: pick the fallback tiktoken encoding by model family. `js-tiktoken`'s
+ * `encodingForModel` handles ids it recognises; this is the explicit fallback
+ * for ids it does not (the 2025/2026 families). gpt-4o / gpt-4.1 / gpt-5+ and
+ * the o-series reasoning models use `o200k_base`; legacy gpt-4 / gpt-3.5 stay
+ * on `cl100k_base`.
+ */
+export function defaultOpenAiEncoding(model: string | undefined): 'o200k_base' | 'cl100k_base' {
+  if (model === undefined) return 'cl100k_base';
+  const id = model.toLowerCase();
+  const sep = Math.max(id.lastIndexOf('/'), id.lastIndexOf(':'));
+  const bare = sep === -1 ? id : id.slice(sep + 1);
+  return /^(?:gpt-4o|gpt-4\.1|gpt-[5-9]|gpt-\d{2}|o[1-9])/.test(bare)
+    ? 'o200k_base'
+    : 'cl100k_base';
+}

package/src/counters/global.ts

@@ -0,0 +1,39 @@
+/**
+ * Process-global token counter slot. Components (e.g. the
+ * ContextEngine in Phase 10) read the global counter when no
+ * per-provider counter is wired explicitly.
+ *
+ * @packageDocumentation
+ */
+
+import type { TokenCounter } from '@graphorin/core';
+
+let globalCounter: TokenCounter | null = null;
+
+/**
+ * Set the process-global counter. Called once at startup by user
+ * code; passing `null` clears the slot.
+ *
+ * @stable
+ */
+export function setGlobalTokenCounter(counter: TokenCounter | null): void {
+  globalCounter = counter;
+}
+
+/**
+ * Read the process-global counter, or `null` if unset.
+ *
+ * @stable
+ */
+export function getGlobalTokenCounter(): TokenCounter | null {
+  return globalCounter;
+}
+
+/**
+ * Test-only hook that resets the global slot to `null` between cases.
+ *
+ * @internal
+ */
+export function __resetGlobalTokenCounter(): void {
+  globalCounter = null;
+}

package/src/counters/google.ts

@@ -0,0 +1,46 @@
+/**
+ * `GoogleAPICounter` - placeholder counter that delegates to
+ * `JsTiktokenCounter('cl100k_base')` for now. The full Google `:countTokens`
+ * implementation lands in Phase 16 alongside the optional pricing
+ * refresher; for v0.1 the proxy is sufficient (verified within ±5% on
+ * the standard fixture corpus per the existing DEC-131 acceptance).
+ *
+ * @packageDocumentation
+ */
+
+import type { Message, TokenCounter } from '@graphorin/core';
+
+import { JsTiktokenCounter } from './js-tiktoken.js';
+
+/**
+ * Options for {@link GoogleAPICounter}.
+ *
+ * @stable
+ */
+export interface GoogleAPICounterOptions {
+  readonly modelId: string;
+  readonly id?: string;
+}
+
+/**
+ * @stable
+ */
+export class GoogleAPICounter implements TokenCounter {
+  readonly id: string;
+  readonly version: string;
+  readonly #fallback: JsTiktokenCounter;
+
+  constructor(options: GoogleAPICounterOptions) {
+    this.#fallback = new JsTiktokenCounter({ encoding: 'cl100k_base', modelId: options.modelId });
+    this.id = options.id ?? `google-proxy@${options.modelId}`;
+    this.version = `google-cl100k-proxy-${options.modelId}-v1`;
+  }
+
+  count(messages: ReadonlyArray<Message>): Promise<number> {
+    return this.#fallback.count(messages);
+  }
+
+  countText(text: string): Promise<number> {
+    return this.#fallback.countText(text);
+  }
+}

package/src/counters/heuristic.ts

@@ -0,0 +1,107 @@
+/**
+ * Conservative `chars / N` token-count estimator. Used as the fallback
+ * for unknown providers; emits exactly one WARN per unique
+ * `(provider, model)` tuple per process so operators are nudged
+ * toward a precise counter.
+ *
+ * @packageDocumentation
+ */
+
+import type { Message, TokenCounter } from '@graphorin/core';
+
+import { serialiseMessageForCount, serializedToString } from './serialize.js';
+
+/**
+ * Options for {@link HeuristicCounter}.
+ *
+ * @stable
+ */
+export interface HeuristicCounterOptions {
+  /** Average characters per token. Defaults to `4` (latin-1 estimate). */
+  readonly charsPerToken?: number;
+  /** Identifier carried on the produced counter. */
+  readonly id?: string;
+  /** Optional model hint surfaced in the WARN message. */
+  readonly modelId?: string;
+  /** Optional sink. Defaults to `console.warn`. */
+  readonly logger?: (message: string, meta?: object) => void;
+}
+
+const WARNED = new Set<string>();
+
+/**
+ * Counter that estimates tokens via simple character division. The
+ * estimator is deterministic and side-effect-free apart from the
+ * one-time WARN.
+ *
+ * @stable
+ */
+export class HeuristicCounter implements TokenCounter {
+  readonly id: string;
+  readonly version: string;
+  readonly #charsPerToken: number;
+  readonly #modelId?: string;
+  readonly #logger: (message: string, meta?: object) => void;
+  #warnedOnce = false;
+
+  constructor(options: HeuristicCounterOptions = {}) {
+    const charsPerToken = options.charsPerToken ?? 4;
+    if (!(charsPerToken > 0)) {
+      throw new RangeError('HeuristicCounter: charsPerToken must be > 0.');
+    }
+    this.#charsPerToken = charsPerToken;
+    this.id = options.id ?? `heuristic@${charsPerToken}cpt`;
+    this.version = `heuristic-${charsPerToken}-cpt-v1`;
+    if (options.modelId !== undefined) this.#modelId = options.modelId;
+    this.#logger = options.logger ?? defaultLogger;
+  }
+
+  async count(messages: ReadonlyArray<Message>): Promise<number> {
+    this.#warnIfNeeded();
+    let total = 0;
+    for (const msg of messages) {
+      const serialised = serialiseMessageForCount(msg);
+      total += this.#estimate(serializedToString(serialised));
+    }
+    return total;
+  }
+
+  async countText(text: string): Promise<number> {
+    this.#warnIfNeeded();
+    return this.#estimate(text);
+  }
+
+  #estimate(text: string): number {
+    if (text.length === 0) return 0;
+    return Math.ceil(text.length / this.#charsPerToken);
+  }
+
+  #warnIfNeeded(): void {
+    if (this.#warnedOnce) return;
+    const key = `${this.id}::${this.#modelId ?? 'unknown'}`;
+    if (WARNED.has(key)) {
+      this.#warnedOnce = true;
+      return;
+    }
+    WARNED.add(key);
+    this.#warnedOnce = true;
+    this.#logger(
+      `[graphorin/provider] heuristic token counter active (${this.id}); accuracy is approximate (~chars/${this.#charsPerToken}).`,
+      this.#modelId !== undefined ? { modelId: this.#modelId } : {},
+    );
+  }
+}
+
+function defaultLogger(message: string, meta?: object): void {
+  if (meta !== undefined) console.warn(message, meta);
+  else console.warn(message);
+}
+
+/**
+ * Test-only hook that resets the per-process WARN cache.
+ *
+ * @internal
+ */
+export function __resetHeuristicWarnCache(): void {
+  WARNED.clear();
+}