risicare 0.7.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +346 -68
- package/dist/frameworks/instructor.cjs +790 -5
- package/dist/frameworks/instructor.cjs.map +1 -1
- package/dist/frameworks/instructor.js +780 -5
- package/dist/frameworks/instructor.js.map +1 -1
- package/dist/frameworks/langchain.cjs +790 -5
- package/dist/frameworks/langchain.cjs.map +1 -1
- package/dist/frameworks/langchain.d.cts +3 -2
- package/dist/frameworks/langchain.d.ts +3 -2
- package/dist/frameworks/langchain.js +780 -5
- package/dist/frameworks/langchain.js.map +1 -1
- package/dist/frameworks/langgraph.cjs +790 -5
- package/dist/frameworks/langgraph.cjs.map +1 -1
- package/dist/frameworks/langgraph.js +780 -5
- package/dist/frameworks/langgraph.js.map +1 -1
- package/dist/frameworks/llamaindex.cjs +801 -5
- package/dist/frameworks/llamaindex.cjs.map +1 -1
- package/dist/frameworks/llamaindex.d.cts +3 -2
- package/dist/frameworks/llamaindex.d.ts +3 -2
- package/dist/frameworks/llamaindex.js +791 -5
- package/dist/frameworks/llamaindex.js.map +1 -1
- package/dist/index.cjs +1219 -212
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +250 -44
- package/dist/index.d.ts +250 -44
- package/dist/index.js +1219 -212
- package/dist/index.js.map +1 -1
- package/dist/providers/anthropic/index.cjs +1601 -36
- package/dist/providers/anthropic/index.cjs.map +1 -1
- package/dist/providers/anthropic/index.d.cts +3 -1
- package/dist/providers/anthropic/index.d.ts +3 -1
- package/dist/providers/anthropic/index.js +1591 -36
- package/dist/providers/anthropic/index.js.map +1 -1
- package/dist/providers/bedrock/index.cjs +850 -32
- package/dist/providers/bedrock/index.cjs.map +1 -1
- package/dist/providers/bedrock/index.js +840 -32
- package/dist/providers/bedrock/index.js.map +1 -1
- package/dist/providers/cerebras/index.cjs +1534 -30
- package/dist/providers/cerebras/index.cjs.map +1 -1
- package/dist/providers/cerebras/index.js +1524 -30
- package/dist/providers/cerebras/index.js.map +1 -1
- package/dist/providers/cohere/index.cjs +1557 -102
- package/dist/providers/cohere/index.cjs.map +1 -1
- package/dist/providers/cohere/index.js +1547 -102
- package/dist/providers/cohere/index.js.map +1 -1
- package/dist/providers/google/index.cjs +1562 -60
- package/dist/providers/google/index.cjs.map +1 -1
- package/dist/providers/google/index.js +1552 -60
- package/dist/providers/google/index.js.map +1 -1
- package/dist/providers/groq/index.cjs +1534 -30
- package/dist/providers/groq/index.cjs.map +1 -1
- package/dist/providers/groq/index.js +1524 -30
- package/dist/providers/groq/index.js.map +1 -1
- package/dist/providers/huggingface/index.cjs +1622 -25
- package/dist/providers/huggingface/index.cjs.map +1 -1
- package/dist/providers/huggingface/index.d.cts +0 -9
- package/dist/providers/huggingface/index.d.ts +0 -9
- package/dist/providers/huggingface/index.js +1612 -25
- package/dist/providers/huggingface/index.js.map +1 -1
- package/dist/providers/mistral/index.cjs +1535 -54
- package/dist/providers/mistral/index.cjs.map +1 -1
- package/dist/providers/mistral/index.js +1525 -54
- package/dist/providers/mistral/index.js.map +1 -1
- package/dist/providers/ollama/index.cjs +1559 -93
- package/dist/providers/ollama/index.cjs.map +1 -1
- package/dist/providers/ollama/index.js +1549 -93
- package/dist/providers/ollama/index.js.map +1 -1
- package/dist/providers/openai/index.cjs +1598 -61
- package/dist/providers/openai/index.cjs.map +1 -1
- package/dist/providers/openai/index.d.cts +6 -1
- package/dist/providers/openai/index.d.ts +6 -1
- package/dist/providers/openai/index.js +1588 -61
- package/dist/providers/openai/index.js.map +1 -1
- package/dist/providers/together/index.cjs +1534 -30
- package/dist/providers/together/index.cjs.map +1 -1
- package/dist/providers/together/index.js +1524 -30
- package/dist/providers/together/index.js.map +1 -1
- package/dist/providers/vercel-ai/index.cjs +1288 -17
- package/dist/providers/vercel-ai/index.cjs.map +1 -1
- package/dist/providers/vercel-ai/index.d.cts +0 -6
- package/dist/providers/vercel-ai/index.d.ts +0 -6
- package/dist/providers/vercel-ai/index.js +1278 -17
- package/dist/providers/vercel-ai/index.js.map +1 -1
- package/package.json +1 -1
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/client.ts","../../src/globals.ts","../../src/utils/log.ts","../../src/exporters/batch.ts","../../src/ids.ts","../../src/noop.ts","../../src/runtime/taxonomy.generated.ts","../../src/runtime/applier.ts","../../src/utils/assert-client.ts","../../src/frameworks/instructor.ts"],"sourcesContent":["/**\n * RisicareClient — singleton client managing SDK lifecycle.\n *\n * Handles initialization, shutdown, and the connection between\n * the Tracer and the export pipeline (batch processor + HTTP exporter).\n *\n * Usage:\n * import { init, shutdown } from 'risicare';\n * init({ apiKey: 'rsk-...' }); // API key determines project\n * // ... instrument code ...\n * await shutdown(); // flush remaining spans\n */\n\n// ⚠ F-SDKJSREPORTERROR-001 (W20, 2026-08-14) — STATIC, and it must stay static.\n// This was `require('node:crypto')` INSIDE `_errorFingerprint()`. esbuild\n// rewrites a bare `require` in an ESM output bundle to `__require(\"crypto\")`,\n// whose shim THROWS at call time; `reportError`'s catch-all then swallowed it\n// (`client.ts` ~:597, \"Never crash the host application\"). Net effect measured\n// on clean tarball installs of the PUBLISHED 0.4.2: reportError() delivered\n// ZERO spans under ESM and one under CJS — a silent no-op for every ESM\n// customer, which is the default for modern Node apps.\n//\n// A static import adds NO new environmental constraint: the package's main\n// entry already pulls `node:crypto` statically, because `src/index.ts` re-\n// exports `./webhooks.js`, which does `import { createHmac, timingSafeEqual }\n// from 'node:crypto'` at `webhooks.ts:53`. Same precedent, same module.\n//\n// ⚠ Do NOT \"optimise\" this back to a lazy require to keep the module edge-safe.\n// It would not achieve that (see above) and it silently re-breaks ESM. Verify\n// with `bash fix-workstream/perf/sdkjs/reporterror_module_system_probe.sh`,\n// whose CJS arm is the non-vacuity control and gates the exit code.\nimport { createHash } from 'node:crypto';\nimport { type RisicareConfig, resolveConfig } from './config.js';\nimport { Tracer, attachErrorCode } from './tracer.js';\nimport { SDK_VERSION } from './version.js';\nimport { BatchSpanProcessor, SHUTDOWN_BUDGET_MS } from './exporters/batch.js';\nimport { HttpExporter } from './exporters/http.js';\nimport { ConsoleExporter } from './exporters/console.js';\nimport { SpanKind, SpanStatus } from './types.js';\nimport type { SpanExporter } from './exporters/base.js';\nimport { setDebug, debug } from './utils/log.js';\nimport { maskText, SCORE_COMMENT_KEY } from './masking.js';\nimport {\n getClient as getGlobalClient,\n setClient as setGlobalClient,\n getTracer as getGlobalTracer,\n setTracer as setGlobalTracer,\n} from './globals.js';\n// PR-4+5 review NIT (2026-05-25): static ESM import. Pre-fix this was a\n// CJS `require('./runtime/runtime.js')` inside the constructor, which\n// dies in TS-source consumers (vitest, ts-node ESM) because the .js\n// resolution fails — tripping the FixRuntime catch and emitting a\n// spurious \"auto-fix is OFFLINE\" warning on EVERY test that calls init().\n// Static import resolves at module-load time and works identically under\n// ESM and CJS bundles produced by tsup. The CON-194 test still exercises\n// the failure path via vi.mock() (which intercepts ES imports correctly).\nimport { initFixRuntime, shutdownFixRuntime } from './runtime/runtime.js';\n\n/**\n * Signals whose default disposition is TERMINATE, with their numbers — needed\n * for the conventional `128 + signum` exit code (SIGTERM 143, SIGINT 130).\n * SDK-RELEASE-RULING.md §3.\n */\nconst TERMINATING_SIGNALS: ReadonlyArray<readonly [string, number]> = [\n ['SIGTERM', 15],\n ['SIGINT', 2],\n];\n\n/**\n * Headroom between the shutdown budget and the backstop that force-exits if\n * shutdown never resolves. It must be > 0 or the backstop races the drain; it\n * is small because it buys nothing but the difference between \"the drain\n * finished\" and \"the drain is wedged\". 500 ms covers the up-to-one-RTT overrun\n * the between-rounds deadline check permits (ruling §4.4).\n */\nconst BACKSTOP_MARGIN_MS = 500;\n\n/**\n * SDK-RELEASE-RULING.md §5 — the final tally survives the teardown.\n *\n * `shutdown()` clears the global client, so without this the natural pattern\n * `await shutdown(); console.log(getMetrics())` reported `droppedSpans: 0` from\n * a hardcoded literal, in the exact process that had just discarded spans.\n *\n * Written once per shutdown; cleared by `init()` so a second lifecycle never\n * serves the first's tally. Mirrors `_final_metrics` in `client.py`.\n */\nlet _finalMetrics: ReturnType<BatchSpanProcessor['getMetrics']> | undefined;\n\n// ─── Client Class ───────────────────────────────────────────────────────────\n\nclass RisicareClient {\n readonly config: ReturnType<typeof resolveConfig>;\n readonly processor: BatchSpanProcessor;\n readonly tracer: Tracer;\n /** RULING §5. The signal path does NOT clear the global client, so without\n * this flag `getMetrics()` would keep reporting `\"running\"` over a processor\n * that has already been torn down. */\n isShutdown = false;\n private _shutdownPromise: Promise<void> | undefined;\n private _shutdownHandlers: { signal: string; handler: () => void }[] = [];\n\n constructor(config?: Partial<RisicareConfig>) {\n this.config = resolveConfig(config);\n\n // API key format validation\n if (this.config.apiKey && !this.config.apiKey.startsWith('rsk-')) {\n debug('Warning: API key should start with \"rsk-\". Got: ' + this.config.apiKey.slice(0, 4) + '...');\n }\n\n // Build exporter chain\n //\n // ⚠ F-SDKJSCONSOLE-001 (fixed 2026-08-15, W23). The `else` arm below used to\n // read `exporter = new ConsoleExporter()` — \"No API key and not debug — use\n // console as fallback\". `exporters/console.ts` writes\n // `JSON.stringify(span.toPayload())` to `process.stderr`: the WHOLE payload,\n // every attribute, every event, every exception, with NO redaction of any\n // kind. Neither Tier-1 (credentials) nor Tier-2 (email/phone/SSN/card/IPv4)\n // exists in the SDK — both run server-side, one hop later — so there is\n // nothing to fall back on and the only safe action is not to write.\n //\n // A falsy API key is not an exotic state: it is a missing, mistyped or\n // not-injected `RISICARE_API_KEY` — CI, staging, a new dev's laptop, a\n // container whose secret failed to mount. Measured from the extracted,\n // PUBLISHED `risicare-0.4.2.tgz` in BOTH module systems (W20-P2, re-derived\n // W23): `RISICARE_TRACING=true` with no key printed a synthetic email, SSN,\n // Visa test PAN and RFC-5737 address to the customer's own stderr. No debug\n // flag was required and no warning was emitted.\n //\n // Python in the identical state WARNS AND DROPS (`client.py:941-947`) and\n // attaches its ConsoleExporter only under `if config.debug`\n // (`client.py:868-875`). This makes JS match Python rather than inventing a\n // third behaviour: the explicit debug opt-in below is UNCHANGED — a customer\n // who asks for console output still gets it — and the accidental state now\n // configures NO exporter at all, which is exactly what Python does.\n //\n // Consequence, deliberate and honest: with an empty exporter array the\n // processor's existing accounting takes over — spans are re-queued to the\n // MAX_RETRIES bound and then discarded as `transport_refused`, COUNTED and\n // WARNED (\"check the api_key and the endpoint\"), instead of being reported\n // as delivered. A DropExporter returning SUCCESS would have been the smaller\n // diff and would have inflated `exportedSpans` for spans that reached\n // nothing — the F-HONEST-001 defect, re-introduced in the SDK.\n let exporter: SpanExporter | undefined;\n if (this.config.debug && !this.config.apiKey) {\n exporter = new ConsoleExporter();\n } else if (this.config.apiKey) {\n exporter = new HttpExporter({\n endpoint: this.config.endpoint,\n apiKey: this.config.apiKey,\n projectId: this.config.projectId || undefined,\n environment: this.config.environment || undefined,\n compress: this.config.compress,\n });\n } else {\n // No API key and not debug — configure NO exporter, and say so. Spans are\n // created and then dropped, exactly as in Python.\n exporter = undefined;\n if (this.config.enabled) {\n // console.warn, not debug() — `debug` is off by default, which is how\n // F-SDKJSREPORTERROR-001 stayed invisible in a shipped release. Same\n // defensive wrapper as the FixRuntime warning below: some sandboxed and\n // edge runtimes have a closed stderr, and a logging call must never be\n // the thing that crashes a customer's process.\n try {\n console.warn(\n `[risicare] tracing is enabled but NO API key is configured — spans are ` +\n `created and then DROPPED, not sent to ${this.config.endpoint}. ` +\n `Pass apiKey to init() (or set the RISICARE_API_KEY env var). ` +\n `Span data is NOT written to the console: it would be unredacted. ` +\n `Pass debug:true if you want console output for local development.`\n );\n } catch {\n // Prefer silent over crash.\n }\n }\n }\n\n this.processor = new BatchSpanProcessor({\n exporters: exporter ? [exporter] : [],\n batchSize: this.config.batchSize,\n batchTimeoutMs: this.config.batchTimeoutMs,\n maxQueueSize: this.config.maxQueueSize,\n debug: this.config.debug,\n // The processor is the ONE choke point every exporter is behind. Masking\n // anywhere downstream (in the HTTP exporter, say) would leave a hole for\n // any other exporter; masking upstream would put customer code on the\n // span-end call path.\n mask: this.config.mask,\n // Same argument as `mask`: the processor is the ONE choke point every\n // exporter is behind, and the only place BOTH content paths — provider\n // capture and hand-set attributes — can be gated together. The Tracer\n // still carries `traceContent` for the provider patches to read; that is\n // now a convenience, not the enforcement point.\n traceContent: this.config.traceContent,\n });\n\n this.tracer = new Tracer({\n onSpanEnd: (span) => this.processor.onSpanEnd(span),\n sampleRate: this.config.sampleRate,\n enabled: this.config.enabled,\n traceContent: this.config.traceContent,\n // F-SDKJSSVCNAME-001 — these were resolved into `config` and then read by\n // nothing. The Tracer is where Python emits them, so JS emits them there\n // too rather than inventing a second site.\n serviceName: this.config.serviceName,\n serviceVersion: this.config.serviceVersion,\n });\n\n // Start the batch processor (enables span queuing and periodic flushing)\n this.processor.start();\n\n // Start FixRuntime for runtime fix application, ONLY ON OPT-IN (0.7.0;\n // see `RisicareConfig.fixRuntime`). Through 0.6.0 it started whenever an\n // apiKey was set, so the server could change the customer's agent by\n // default. When it starts, it loads active fixes from /v1/fixes/active,\n // caches with TTL and background-refreshes every 60s. Provider patches call\n // interceptCall() to apply fixes before LLM calls. When it is off, no\n // runtime exists, so interceptCall() finds nothing to apply.\n //\n // CON-194: previously the catch was an empty-body silent swallow,\n // which meant a customer whose FixRuntime failed to initialize\n // (network unreachable, bad API key, server 5xx, etc.) saw ZERO\n // signal and assumed auto-fix was running. Now the catch logs\n // console.warn with an actionable message — visible at default\n // console output, including the endpoint so customers can verify\n // reachability. Mirrors the Python SDK fix at client.py:520-528.\n if (this.config.apiKey && this.config.enabled && this.config.fixRuntime) {\n try {\n initFixRuntime({\n apiEndpoint: this.config.apiEndpoint,\n apiKey: this.config.apiKey,\n enabled: true,\n debug: this.config.debug,\n });\n } catch (e) {\n // FixRuntime failure is non-fatal — tracing still works.\n // Surface a one-time console.warn so the customer knows.\n const errName = e instanceof Error ? e.name : 'Error';\n const errMsg = e instanceof Error ? e.message : String(e);\n try {\n console.warn(\n `[risicare] FixRuntime initialization failed — auto-fix is OFFLINE for this process. ` +\n `endpoint=${this.config.endpoint} error=${errName}: ${errMsg}. ` +\n `Tracing + reporting still work; only fix application is disabled. ` +\n `Pass debug:true in init() options for the full traceback.`\n );\n } catch {\n // Defensive: if console.warn itself throws (closed stderr in\n // some sandboxed/edge environments), prefer silent over crash.\n }\n if (this.config.debug) {\n debug(`FixRuntime init traceback: ${e instanceof Error && e.stack ? e.stack : String(e)}`);\n }\n }\n }\n\n // Register shutdown hooks\n this._registerShutdownHooks();\n\n // Enable internal debug logging if configured\n setDebug(this.config.debug);\n debug(`Initialized: enabled=${this.config.enabled}, endpoint=${this.config.endpoint}`);\n if (!this.config.fixRuntime) {\n debug(\n 'FixRuntime is off: nothing polls /fixes/active and no fix is applied. ' +\n 'Opt in with fixRuntime: true or RISICARE_FIX_RUNTIME=true.',\n );\n }\n }\n\n get enabled(): boolean {\n return this.tracer.enabled;\n }\n\n set enabled(value: boolean) {\n this.tracer.enabled = value;\n }\n\n // Audit #6: Promise-based shutdown dedup (fixes TOCTOU race condition)\n async shutdown(): Promise<void> {\n if (this._shutdownPromise) return this._shutdownPromise;\n this._shutdownPromise = this._doShutdown();\n return this._shutdownPromise;\n }\n\n private async _doShutdown(): Promise<void> {\n debug('Shutting down...');\n\n // Audit #3: Remove process listeners to prevent leak\n for (const { signal, handler } of this._shutdownHandlers) {\n process.removeListener(signal, handler);\n }\n this._shutdownHandlers = [];\n\n await this.processor.shutdown();\n\n // RULING §5: snapshot HERE, in the one place every teardown path passes\n // through.\n //\n // ⚠ THIS SITE IS THE WHOLE POINT, and the obvious site is wrong. A first\n // implementation snapshotted in the module-level `shutdown()` — which the\n // SIGTERM/SIGINT handlers never call. They call THIS method, so on exactly\n // the path a container redeploy takes, `getMetrics()` would have reported\n // a live-looking reading over a torn-down processor. The Python SDK had the\n // identical trap on its own signal path; one rule, two languages, both\n // instrumented at the shared site rather than the canonical one.\n this.isShutdown = true;\n _finalMetrics = this.processor.getMetrics();\n }\n\n /**\n * Flush pending spans.\n *\n * @returns `true` only if everything queued at entry was DELIVERED.\n *\n * RULING §6: this used to discard the processor's boolean and return\n * `Promise<void>`, which resolves without throwing and reads to a caller\n * exactly like success. A discarded answer is not meaningfully better than a\n * false one — both leave the customer unable to tell *drained* from\n * *discarded*.\n */\n async flush(): Promise<boolean> {\n return this.processor.flush();\n }\n\n /**\n * SDK-RELEASE-RULING.md §3 — who decides whether the process dies.\n *\n * The contract, and it is the same one the Python SDK now satisfies:\n *\n * the SDK's signal handler never CHANGES whether the signal\n * terminates the process.\n *\n * Registering ANY listener for SIGTERM/SIGINT displaces Node's default\n * terminate. Before this, the SDK registered one unconditionally, and on the\n * success path `clearTimeout` removed the 5 s `process.exit(1)` backstop —\n * so a JS app with a live event loop drained, cleared its own only exit, and\n * **ran forever**. The orchestrator waited out the whole grace period and\n * SIGKILLed, which exits **137** and reads as OOM-killed in every dashboard.\n * Measured >25 s alive on both 0.5.0 and a clean-rebuilt 0.4.2, so this is\n * PRE-EXISTING (`F-SDKJSEXIT-001`), not a regression of the data-loss fix.\n *\n * The rule splits on one question — did the signal already have an owner?\n *\n * * **No prior listener.** Node's default was termination and OUR\n * registration displaced it. We owe the process that death.\n * * **A prior listener exists.** The application took ownership before the\n * SDK loaded. We drain and RETURN; termination was never ours to decide,\n * and forcing it would cut off the app's own graceful shutdown.\n *\n * ⚠ `beforeExit` is deliberately NOT in that logic. It is not a signal and\n * carries no termination the SDK could displace — the loop has already\n * drained and the process is leaving on its own.\n */\n private _registerShutdownHooks(): void {\n // `beforeExit` first: no ownership question, no backstop, no exit.\n const onBeforeExit = () => {\n this.shutdown().catch(() => {});\n };\n process.once('beforeExit', onBeforeExit);\n this._shutdownHandlers.push({ signal: 'beforeExit', handler: onBeforeExit });\n\n for (const [signal, signum] of TERMINATING_SIGNALS) {\n // Captured ONCE, at registration — asking later would count our own.\n const weDisplacedDefault = process.listenerCount(signal) === 0;\n\n const handler = () => {\n // Backstop: DERIVED from the shutdown budget, never a second literal.\n // The two used to be an independent `5000` each, so a drain allowed\n // 5,000 ms raced a `process.exit(1)` firing at 5,000 ms — killing the\n // drain at its deadline, with the wrong exit code, before the residue\n // WARNING (the previous ruling's primary remedy) could print.\n const backstop = setTimeout(\n () => process.exit(128 + signum),\n SHUTDOWN_BUDGET_MS + BACKSTOP_MARGIN_MS,\n );\n backstop.unref();\n\n this.shutdown()\n .catch(() => {})\n .finally(() => {\n clearTimeout(backstop);\n if (!weDisplacedDefault) return; // the app owns termination\n\n // Our listener is gone (`process.once` + `_doShutdown` removed\n // them), so re-raising reaches Node's default and terminates for\n // real — WIFSIGNALED, not merely an exit code that looks like one.\n try {\n process.kill(process.pid, signal as NodeJS.Signals);\n } catch {\n process.exit(128 + signum);\n }\n // Belt and braces: if the application added a listener DURING our\n // drain, the re-raise above went to it instead of terminating and\n // we would hang exactly as before. unref()'d, so it cannot itself\n // hold open a process that is already leaving.\n const failsafe = setTimeout(() => process.exit(128 + signum), 100);\n failsafe.unref();\n });\n };\n\n process.once(signal, handler);\n this._shutdownHandlers.push({ signal, handler });\n }\n }\n}\n\n// ─── Public API ─────────────────────────────────────────────────────────────\n\n/**\n * Initialize the Risicare SDK. Call once at application startup.\n *\n * @example\n * import { init } from 'risicare';\n * init({ apiKey: 'rsk-...', serviceName: 'my-agent', environment: 'production' });\n */\nexport function init(config?: Partial<RisicareConfig>): void {\n const existing = getGlobalClient() as RisicareClient | undefined;\n if (existing) {\n // F-359: warn loudly when re-init would silently discard a config change.\n // The first init wins; a second init with a different apiKey/endpoint/\n // environment is almost certainly a bug (e.g., a side-effect import that\n // calls init() in a library, then the app's own init() with real config\n // gets ignored).\n if (config) {\n const incoming = resolveConfig(config);\n const diffs: string[] = [];\n const checkedKeys: Array<keyof typeof incoming> = [\n 'apiKey',\n 'endpoint',\n 'environment',\n 'serviceName',\n 'serviceVersion',\n 'sampleRate',\n ];\n for (const k of checkedKeys) {\n if (incoming[k] !== existing.config[k]) {\n // Don't print apiKey contents — just say \"differs\".\n const newRender = k === 'apiKey' ? '<redacted>' : JSON.stringify(incoming[k]);\n const oldRender = k === 'apiKey' ? '<redacted>' : JSON.stringify(existing.config[k]);\n diffs.push(`${String(k)}: ${oldRender} → ${newRender}`);\n }\n }\n if (diffs.length > 0) {\n console.warn(\n '[risicare] init() called twice with different config; the FIRST call wins. ' +\n 'Call shutdown() before re-initializing. Differences ignored: ' +\n diffs.join(', '),\n );\n } else {\n debug('init() called twice with identical config; no-op');\n }\n } else {\n debug('init() called twice; no-op');\n }\n return;\n }\n\n // RULING §5: a NEW lifecycle starts with no retained tally — otherwise\n // `init(); shutdown(); init()` would serve the FIRST run's losses as if they\n // belonged to the second.\n _finalMetrics = undefined;\n\n const client = new RisicareClient(config);\n setGlobalClient(client);\n setGlobalTracer(client.tracer);\n}\n\n/**\n * Gracefully shut down the SDK. Flushes pending spans before resolving.\n */\nexport async function shutdown(): Promise<void> {\n // Stop FixRuntime first (stops background refresh)\n try {\n shutdownFixRuntime();\n } catch {\n // FixRuntime may not be initialized\n }\n\n const client = getGlobalClient() as RisicareClient | undefined;\n if (!client) return;\n // RULING §5: the final tally is snapshotted inside `_doShutdown()`, which\n // this reaches and which the signal handlers reach directly. Do NOT add a\n // second snapshot here.\n await client.shutdown();\n setGlobalClient(undefined);\n setGlobalTracer(undefined);\n}\n\n/**\n * Flush all pending spans without shutting down.\n *\n * @returns `true` only if everything queued at entry was DELIVERED — `false`\n * if the deadline expired with spans still queued, or if any span was\n * discarded during the window (F-SDKCB-001 §6). An uninitialised SDK returns\n * `true`: it was handed nothing, and it lost nothing.\n *\n * ⚠ Signature change in 0.5.0 — was `Promise<void>`. Existing callers that\n * ignore the result keep working unchanged.\n */\nexport async function flush(): Promise<boolean> {\n const client = getGlobalClient() as RisicareClient | undefined;\n if (!client) return true;\n return client.flush();\n}\n\n/**\n * Enable tracing at runtime.\n */\nexport function enable(): void {\n const client = getGlobalClient() as RisicareClient | undefined;\n if (client) client.enabled = true;\n}\n\n/**\n * Disable tracing at runtime. Spans will not be created or exported.\n */\nexport function disable(): void {\n const client = getGlobalClient() as RisicareClient | undefined;\n if (client) client.enabled = false;\n}\n\n/**\n * Check whether tracing is currently enabled.\n */\nexport function isEnabled(): boolean {\n const client = getGlobalClient() as RisicareClient | undefined;\n return client?.enabled ?? false;\n}\n\n/**\n * Get the global tracer instance. Returns undefined if not initialized.\n */\nexport function getTracer(): Tracer | undefined {\n return getGlobalTracer() as Tracer | undefined;\n}\n\n/**\n * Get the global tracer, or throw if not initialized.\n * @internal Used by decorators and providers that require an active tracer.\n */\nexport function requireTracer(): Tracer {\n const tracer = getGlobalTracer() as Tracer | undefined;\n if (!tracer) {\n throw new Error(\n 'Risicare SDK not initialized. Call init() before using tracing features.',\n );\n }\n return tracer;\n}\n\n/**\n * Check whether content tracing (prompt/completion capture) is enabled.\n */\nexport function getTraceContent(): boolean {\n const tracer = getGlobalTracer() as Tracer | undefined;\n // Fail-closed, matching the 0.5.1 config default.\n return tracer?.traceContent ?? false;\n}\n\n/**\n * Get SDK metrics: exported spans, dropped spans, failed exports, queue stats.\n *\n * `sdkState` — SDK-RELEASE-RULING.md §5 — says WHICH of three different facts\n * the numbers are, because before it all three rendered as the same zeros:\n *\n * - `\"uninitialised\"` nothing was ever queued; the zeros are the truth\n * - `\"running\"` live readings from a live processor\n * - `\"shutdown\"` the RETAINED FINAL TALLY. Not live, and says so.\n *\n * The `\"shutdown\"` case is why this field exists. `shutdown()` clears the global\n * client, so this used to answer `droppedSpans: 0` from a hardcoded literal in\n * the very process that had just discarded spans — a guess presented\n * byte-identical to an authoritative answer, which is the W1/W3 class this\n * codebase already ruled against (`cost_source`, `settled`). The remedy there\n * and here is the same: do not hide the value and do not null it, LABEL it.\n * Every field of a retained tally is still true — the queue really is empty,\n * the capacity really is the configured one, and the drop counts describe the\n * whole life of the process, `shutdown_residue` included.\n *\n * ⚠ What it still CANNOT do: report loss to anything OUTSIDE the dying process.\n * A counter in memory about to be freed has no reader, and a SIGKILL takes this\n * and the WARNING together. The WARNING remains the primary signal.\n */\nexport function getMetrics() {\n const client = getGlobalClient() as RisicareClient | undefined;\n if (client && !client.isShutdown) {\n return { ...client.processor.getMetrics(), sdkState: 'running' as const };\n }\n if (_finalMetrics) {\n // Copy: a caller mutating the object must not corrupt the one tally the\n // process has left.\n return {\n ..._finalMetrics,\n droppedSpansByReason: { ..._finalMetrics.droppedSpansByReason },\n sdkState: 'shutdown' as const,\n };\n }\n return {\n exportedSpans: 0,\n droppedSpans: 0,\n droppedSpansByReason: {\n queue_full: 0,\n transport_refused: 0,\n shutdown_residue: 0,\n },\n failedExports: 0,\n queueSize: 0,\n queueCapacity: 0,\n queueUtilization: 0,\n sdkState: 'uninitialised' as const,\n };\n}\n\n// ─── reportError ──────────────────────────────────────────────────────────\n\n// Error dedup: SHA256 fingerprint → timestamp. Prevents retry loops from\n// creating N duplicate diagnoses. Matches Python SDK's 5-minute TTL.\nconst _ERROR_DEDUP_TTL_MS = 5 * 60 * 1000; // 5 minutes\nconst _ERROR_DEDUP_MAX = 1000;\nconst _recentErrors = new Map<string, number>(); // fingerprint → Date.now()\n\nfunction _errorFingerprint(err: Error): string {\n const raw = `${err.constructor?.name ?? 'Error'}:${String(err.message ?? '').slice(0, 200)}`;\n return createHash('sha256').update(raw).digest('hex').slice(0, 16);\n}\n\nfunction _isDuplicateError(fingerprint: string): boolean {\n const now = Date.now();\n // Evict expired entries\n for (const [fp, ts] of _recentErrors) {\n if (now - ts > _ERROR_DEDUP_TTL_MS) _recentErrors.delete(fp);\n else break; // Map iterates in insertion order\n }\n if (_recentErrors.has(fingerprint)) return true;\n // Enforce max size\n if (_recentErrors.size >= _ERROR_DEDUP_MAX) {\n const oldest = _recentErrors.keys().next().value;\n if (oldest !== undefined) _recentErrors.delete(oldest);\n }\n _recentErrors.set(fingerprint, now);\n return false;\n}\n\n/**\n * Report a caught exception to the error diagnosis pipeline.\n *\n * Creates an error span that triggers diagnosis and fix generation.\n * Deduplicates identical errors within a 5-minute window (SHA256 fingerprint).\n * This function never throws and is non-blocking.\n *\n * @param error - The caught exception (Error object or string)\n * @param options - Optional attributes and context overrides\n */\nexport function reportError(\n error: unknown,\n options?: { name?: string; attributes?: Record<string, unknown> },\n): void {\n try {\n const tracer = getTracer();\n if (!tracer) return;\n\n const err = error instanceof Error ? error : new Error(String(error ?? 'unknown'));\n const spanName = options?.name ?? `error:${err.constructor.name}`;\n\n // Dedup: suppress identical errors within TTL (matches Python SDK)\n const fp = _errorFingerprint(err);\n if (_isDuplicateError(fp)) {\n debug(`reportError: duplicate suppressed (fp=${fp.slice(0, 8)})`);\n return;\n }\n\n tracer.startSpan({ name: spanName, kind: SpanKind.INTERNAL }, (span) => {\n span.setStatus(SpanStatus.ERROR, err.message);\n span.setAttribute('error', true);\n span.setAttribute('error.type', err.constructor.name);\n span.setAttribute('error.message', err.message.slice(0, 2000));\n if (err.stack) span.setAttribute('error.stack', err.stack.slice(0, 4000));\n span.setAttribute('risicare.reported_error', true);\n // F-R-REPORTERRCODE-001. `reportError` is the API our own docs name for\n // feeding the diagnosis pipeline, yet it attached error/type/message and\n // NO taxonomy code, while an uncaught throw through a traced frame did —\n // `tracer.ts::Tracer.startSpan` calls `attachErrorCode` on both of its\n // throw handlers. Measured on the published 0.5.2 against the lab: 4\n // uncaught spans carried TOOL.EXECUTION.CRASHED, the reportError span\n // carried none. Same shape as the Python asymmetry, same remedy — reuse\n // the ONE definition rather than re-classifying here.\n attachErrorCode(span, err);\n if (options?.attributes) {\n for (const [k, v] of Object.entries(options.attributes)) {\n span.setAttribute(k, v);\n }\n }\n });\n } catch {\n // Never crash the host application\n debug('reportError failed');\n }\n}\n\n// ─── score ─────────────────────────────────────────────────────────────────\n\n/**\n * Record a custom evaluation score on a trace.\n *\n * Sends the score to the server in a fire-and-forget fashion.\n * This function never throws and is non-blocking.\n *\n * If a `mask` is configured on `init()`, `options.comment` is passed to it under\n * the key `score.comment` before the request is built. `traceId`, `spanId` and\n * `name` are NOT masked — they are identifiers the platform joins and groups on.\n *\n * @param traceId - The trace to score\n * @param name - Score name (e.g., \"accuracy\", \"user_satisfaction\")\n * @param value - Score value between 0.0 and 1.0 inclusive\n * @param options - Optional span_id and comment\n */\nexport function score(\n traceId: string,\n name: string,\n value: number,\n options?: { spanId?: string; comment?: string },\n): void {\n try {\n if (typeof value !== 'number' || !Number.isFinite(value) || value < 0.0 || value > 1.0) {\n debug(`score: value must be in [0.0, 1.0], got ${value}. Score not sent.`);\n return;\n }\n if (!traceId || !name) {\n debug('score: traceId and name are required');\n return;\n }\n\n const client = getGlobalClient() as RisicareClient | undefined;\n if (!client?.enabled || !client.config.apiKey) return;\n\n // ⚠ FIELD CHANGED 0.6.0 -> 0.7.0: this read `config.endpoint`, the SPAN\n // endpoint, and then composed an API path. That worked only while one\n // Caddy-fronted host served both services. It now reads `apiEndpoint`,\n // which falls back to `endpoint` when only that one is set.\n // The `/api` prefix is gone with the proxy that stripped it.\n const endpoint = client.config.apiEndpoint.replace(/\\/+$/, '');\n const url = `${endpoint}/v1/scores`;\n\n // ⚠ THE ONE NON-SPAN EGRESS THE MASK COVERS (F-SDKMASKSCORE-001).\n // This POST does not go through BatchSpanProcessor, so `applyMask` never\n // sees it — `comment` is free customer text on our wire and was uncovered\n // until this call. The ruling (why the same hook rather than a second one,\n // why `name` is deliberately NOT masked, and the caller-thread cost) is in\n // `risicare/masking.py`, \"THE NON-SPAN SURFACE\".\n //\n // Runs BEFORE `JSON.stringify`, so the unmasked value is never serialized.\n // `maskText` is the same primitive `statusMessage` uses, so a throwing mask\n // yields the same marker and the score is still sent.\n let comment = options?.comment;\n if (comment !== undefined && client.config.mask) {\n comment = maskText(client.config.mask, SCORE_COMMENT_KEY, comment);\n }\n\n const body = JSON.stringify({\n trace_id: traceId,\n name,\n score: value,\n source: 'sdk',\n ...(options?.spanId && { span_id: options.spanId }),\n ...(comment && { comment }),\n });\n\n // Fire-and-forget — never blocks caller\n fetch(url, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'Authorization': `Bearer ${client.config.apiKey}`,\n // F-SDKVER-001 — see the Python twin. `score()` reaches the FastAPI\n // server under /v1/, which `main.py::audit_logging_middleware` audits\n // into `audit_logs.user_agent`; ingest reaches the Rust gateway, which\n // discards it. This is the one client-identity visible with no gateway\n // change.\n 'User-Agent': `risicare-js/${SDK_VERSION} node/${process.version}`,\n 'X-Risicare-SDK-Version': SDK_VERSION,\n },\n body,\n }).catch((err) => debug(`score: send failed: ${err}`));\n } catch {\n // Never crash the host application\n debug('score failed');\n }\n}\n","/**\n * Shared state via globalThis — ensures all entry point bundles share\n * the same singleton instances.\n *\n * Problem: tsup with `splitting: false` gives each entry point (index,\n * openai, anthropic, vercel-ai) its own copy of module-level variables.\n * This means `init()` from 'risicare' sets a tracer that 'risicare/openai'\n * can't see — breaking all provider instrumentation silently.\n *\n * Solution: Store all mutable singletons on globalThis with a namespaced\n * prefix. Every bundle reads/writes the same global slots.\n *\n * This pattern is used by React, OpenTelemetry, and other SDKs that must\n * share state across independently bundled entry points.\n *\n * @internal\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst G = globalThis as any;\nconst PREFIX = '__risicare_';\n\n// ─── Client & Tracer ────────────────────────────────────────────────────────\n\nexport function getClient(): unknown {\n return G[PREFIX + 'client'];\n}\n\nexport function setClient(client: unknown): void {\n G[PREFIX + 'client'] = client;\n}\n\nexport function getTracer(): unknown {\n return G[PREFIX + 'tracer'];\n}\n\nexport function setTracer(tracer: unknown): void {\n G[PREFIX + 'tracer'] = tracer;\n}\n\n// ─── Context Storage ────────────────────────────────────────────────────────\n\nexport function getContextStorage(): AsyncLocalStorage<unknown> {\n if (!G[PREFIX + 'ctx']) {\n G[PREFIX + 'ctx'] = new AsyncLocalStorage();\n }\n return G[PREFIX + 'ctx'];\n}\n\n// ─── Span Registry ──────────────────────────────────────────────────────────\n\nexport function getRegistry(): Map<string, unknown> {\n if (!G[PREFIX + 'registry']) {\n G[PREFIX + 'registry'] = new Map();\n }\n return G[PREFIX + 'registry'];\n}\n\nexport function getOpCount(): number {\n return G[PREFIX + 'opcount'] ?? 0;\n}\n\nexport function setOpCount(n: number): void {\n G[PREFIX + 'opcount'] = n;\n}\n\n// ─── Debug Flag ─────────────────────────────────────────────────────────────\n\nexport function getDebug(): boolean {\n return G[PREFIX + 'debug'] ?? false;\n}\n\nexport function setDebugFlag(enabled: boolean): void {\n G[PREFIX + 'debug'] = enabled;\n}\n\n// ─── Fix Runtime ────────────────────────────────────────────────────────\n\nexport function getGlobalFixRuntime(): unknown {\n return G[PREFIX + 'fix_runtime'];\n}\n\nexport function setGlobalFixRuntime(runtime: unknown): void {\n G[PREFIX + 'fix_runtime'] = runtime;\n}\n","/**\n * Internal logger for the Risicare SDK.\n *\n * Centralizes all diagnostic output so that:\n * - Debug messages are gated by a single flag (zero-cost when disabled)\n * - Warnings always fire (operational alerts like queue full)\n * - All output goes to stderr with a consistent [risicare] prefix\n * - A future custom logger callback can be added in one place\n */\n\nimport { getDebug, setDebugFlag } from '../globals.js';\n\n/**\n * Enable or disable debug logging. Called once during init().\n * @internal\n */\nexport function setDebug(enabled: boolean): void {\n setDebugFlag(enabled);\n}\n\n/**\n * Log a debug message. Only outputs when debug mode is enabled.\n * @internal\n */\nexport function debug(msg: string): void {\n if (getDebug()) {\n process.stderr.write(`[risicare] ${msg}\\n`);\n }\n}\n\n/**\n * Log a warning. Always outputs regardless of debug mode.\n * Use sparingly — only for operational issues the user should see.\n * @internal\n */\nexport function warn(msg: string): void {\n process.stderr.write(`[risicare] WARNING: ${msg}\\n`);\n}\n","/**\n * Batch span processor.\n *\n * Collects spans and exports them in batches based on:\n * - Batch size threshold (default: 500 spans — SDK-RELEASE-RULING.md §4.3 raised\n * this from 100; see `DEFAULT_BATCH_SIZE` below, which is the one true source)\n * - Time interval (default: 1000ms)\n * - Attribute product (`MAX_ATTRIBUTE_PAIRS_PER_BATCH`) and estimated serialized\n * size (`MAX_BATCH_BYTES`), both mirroring gateway constants\n *\n * Node.js is single-threaded — no locks needed.\n * Timer is unref()'d so it doesn't prevent process exit.\n */\n\nimport type { Span } from '../span.js';\nimport { ExportResult, type SpanExporter } from './base.js';\nimport { debug, warn } from '../utils/log.js';\nimport {\n applyMaskBatch,\n stripContentBatch,\n warnMaskErrors,\n warnMaskSlow,\n MASK_BUDGET_MS_PER_SPAN,\n MASK_WARN_WINDOW_MS,\n type MaskFn,\n} from '../masking.js';\n\nexport interface BatchProcessorOptions {\n exporters: SpanExporter[];\n batchSize?: number;\n batchTimeoutMs?: number;\n maxQueueSize?: number;\n debug?: boolean;\n /**\n * Customer masking callback, `mask(key, value) => value`. Applied to every\n * content-bearing field of every span in this processor, once, BEFORE any\n * exporter sees the batch. See `../masking.ts`.\n */\n mask?: MaskFn;\n /**\n * Whether customer prompt/completion content may leave the process.\n * **Defaults to `false`** — the same fail-closed default as `resolveConfig`.\n * When false, every content-keyed attribute is replaced on the export path\n * before any exporter runs. See `../masking.ts` `stripContent`.\n */\n traceContent?: boolean;\n}\n\n/**\n * F-SDKCB-001 §5 (option J) — reason labels for a discarded span.\n *\n * One integer conflating an under-provisioned queue, a dead gateway and a\n * redeploy is the ambiguity W1/W3 was written against: the three causes demand\n * three different operator responses. The server side already landed on this\n * shape as `dropped{stage,reason,project_id}` (F-HONEST-001). Mirrors the\n * Python `DROP_*` constants in `exporters/batch.py`.\n */\nexport type DropReason = 'queue_full' | 'transport_refused' | 'shutdown_residue';\n\n/** Outcome of one `_exportBatch()` round.\n *\n * `shutdown()`'s drain loop must tell \"the queue is empty\" from \"a batch was\n * taken and nobody accepted it\" — RULING §4's no-SUCCESS exit. Without that\n * distinction the loop would spin for the whole budget against a dead\n * transport, and (because the bounded re-queue keeps the queue non-empty)\n * would never terminate at all. */\nconst enum Round {\n Empty = 0,\n Delivered = 1,\n Failed = 2,\n /** an export was already in flight (`_flushing`); this call made no progress */\n Busy = 3,\n}\n\n/**\n * RULING §4 delegates this number with a derive-and-justify obligation.\n * `shutdown()` runs `exporter.shutdown()` AFTER the drain, so a drain that\n * spends the whole budget starves it.\n *\n * The built-in `HttpExporter.shutdown()` is a literal no-op — native fetch\n * needs no cleanup (`exporters/http.ts:159-161`) — so for the shipped exporter\n * the measured cost is ZERO. The reserve is therefore a policy allowance for a\n * CUSTOMER-supplied exporter, whose `shutdown(): Promise<void> | void`\n * (`exporters/base.ts:16`) we cannot measure. Held at 100 ms to match the\n * Python constant — the two SDKs must end with the same contract, and Python's\n * value is measured (see `_SHUTDOWN_RESERVE_MS` in `exporters/batch.py` and\n * `fix-workstream/perf/sdk_exporter_shutdown_cost_probe.py`). Against the\n * binding 2,000 ms SIGTERM budget this leaves 1,900 ms of drain.\n */\nconst SHUTDOWN_RESERVE_MS = 100;\n\n/**\n * SDK-RELEASE-RULING.md §4.3 — ONE shutdown budget, on every teardown path.\n *\n * 5,000 ms is bounded from ABOVE by something outside our control: the SDK's\n * shutdown runs inside the application's, which runs inside the container's\n * termination grace period. The tightest common default is `docker stop` at\n * 10 s (k8s `terminationGracePeriodSeconds` 30 s; systemd `TimeoutStopSec`\n * 90 s), and taking more than half of the tightest is hostile to the app's own\n * cleanup.\n *\n * ⚠ WHY A LONGER BUDGET IS NEARLY FREE: the drain exits on the FIRST round that\n * does not deliver (`Round.Delivered` check below). A dead transport costs one\n * round, not the budget. It is spent only while the transport is SUCCEEDING.\n *\n * ⚠ `client.ts` DERIVES its signal-handler backstop from this rather than\n * repeating a literal. Before the ruling both were an independent `5000`, so\n * the backstop's `process.exit(1)` raced the drain it exists to protect —\n * killing it at the deadline, with the wrong exit code, before the residue\n * warning could print. Do not re-introduce a second literal.\n *\n * Mirrors `SHUTDOWN_BUDGET_MS` in `client.py`.\n */\nexport const SHUTDOWN_BUDGET_MS = 5000;\n\n/**\n * The `transport_refused` warning is rate-limited to the exporter's existing\n * window (`exporters/http.ts`), so a flaky network cannot spam customer logs.\n * The `shutdown_residue` warning is NOT rate-limited (RULING §5): it fires at\n * most once per process lifetime by construction, so a window buys nothing and\n * would suppress the only signal in any process that had already warned about\n * the breaker — exactly the correlated case where the customer most needs it.\n */\nconst REFUSAL_WARN_WINDOW_MS = 300_000;\n\n/**\n * SDK-RELEASE-RULING.md §4.3 — the default batch size, raised 100 -> 500.\n *\n * DERIVED, not picked. `shutdown()`'s drain is strictly serial — one export per\n * round-trip — so the most it can save is\n * ceiling = floor((budget - reserve) / RTT) x batchSize\n * and the requirement is that it drain the SDK's OWN maximum queue\n * (`maxQueueSize` = 10,000, the most it can ever be holding) at the design\n * target RTT = 100 ms:\n * batchSize >= 10,000 x RTT / (5,000 - 100) -> 204 at 100 ms, 510 at 250 ms\n * 500 satisfies it to the 250 ms trans-Pacific tail and sits 1.55x under the\n * ceiling the gateway's attribute-product cap imposes (below).\n *\n * ⚠ NEITHER THIS NOR THE BUDGET IS SUFFICIENT ALONE — measured, ruling §2. At\n * 100 ms RTT: budget alone leaves 51 % lost, batch alone leaves 60 % lost at the\n * tail, both together lose nothing. Do not \"simplify\" one back.\n *\n * Mirrors `DEFAULT_BATCH_SIZE` in `exporters/batch.py` — the two SDKs must end\n * with the same contract.\n */\nexport const DEFAULT_BATCH_SIZE = 500;\n\n/**\n * The gateway refuses a request whose summed attribute count exceeds this\n * (`MAX_ATTRIBUTE_PAIRS_PER_REQUEST`, `handlers/ingest.rs`, F-ACKRSV-001) —\n * WHOLE request, never truncated, and the exporter treats that 4xx as a\n * failure, retries it futilely and finally discards the batch as\n * `transport_refused`. The cap is `sum(span.attributes.length)`, i.e. LINEAR in\n * batch size: at batch B a customer is refused above `24,000 / B` attributes\n * per span — 240 at B=100, but only 48 at B=500.\n *\n * Without this bound, raising the default would silently break every customer\n * between those two densities: accepted today, whole-request-refused tomorrow,\n * with no action on their part. So the batch is bounded on BOTH axes, and the\n * raise becomes strictly no-worse-than-today on the attribute axis.\n *\n * ⚠ COUPLING, DECLARED (ruling §4.5) — AND THE DIRECTIONS ARE NOT SYMMETRIC.\n * ⚠ CORRECTED 2026-07-27 (F-SDKBYTES-001 §4.1). This comment used to read\n * \"Stale in either direction is SAFE — too low means slightly smaller batches,\n * too high means the gateway refuses exactly as it does today.\" The second half\n * is FALSE, and the error mattered because it licenses a unilateral change on\n * the gateway side that this SDK cannot survive:\n *\n * • STALE LOW (SDK constant < gateway cap) — SAFE, unconditionally. The SDK\n * assembles smaller batches than it needed to; every one is accepted.\n * • STALE HIGH (SDK constant > gateway cap) — safe ONLY while the gateway's\n * cap does not DECREASE. If it is lowered, this SDK assembles batches the\n * gateway now refuses: requests that are accepted TODAY begin returning\n * 4xx, the exporter retries each one futilely and discards the whole batch\n * as `transport_refused`. That is a NEW refusal caused by the mismatch —\n * not \"exactly as it does today\".\n *\n * ⇒ RAISING the gateway cap is safe to do unilaterally. LOWERING it is not: the\n * SDK constant must move first and be adopted, and `F-SDKVER-001` records\n * that nothing pins or even observes an SDK version server-side, so \"adopted\"\n * is weeks-to-never rather than a deploy.\n *\n * The gateway remains the enforcer; this only stops OUR DEFAULT from moving a\n * customer across ITS boundary.\n */\nexport const MAX_ATTRIBUTE_PAIRS_PER_BATCH = 24_000;\n\n/**\n * The per-batch SERIALIZED-BYTE bound (F-SDKBYTES-001) — the third axis.\n *\n * `SDK-RELEASE-RULING.md` §4.5 bounded the batch on span COUNT and attribute\n * PRODUCT and explicitly left BYTES open: \"a customer putting a 1 MB string in\n * an attribute can exceed the body limit at *any* batch size, and B=500 makes\n * it 5x more reachable. I did not guard this.\"\n *\n * MEASURED (`perf/sdk_batch_byte_ceiling_probe.py`, raw\n * `perf/sdk-batch-byte-ceiling.json`; its JS cross-check arm compiles\n * `src/span.ts` itself rather than trusting `dist/`):\n *\n * batch=500 crosses max_body_size (10,485,760 B) at 20,971 B/span\n * batch=100 crosses it at 104,857 B/span\n *\n * and the ruling's \"16x headroom\" quoted only the measured FLOOR. Against the\n * measured MAXIMUM realistic span (13,487 B) a 500-span batch is 6,743,500 B —\n * 1.55x headroom, not 16x. The count raise spent most of the byte margin.\n *\n * WITHOUT IT, MEASURED (probe ARM 2): the gateway answers 413, and the exporter\n * does NOT treat 413 as permanent — `http.ts` maps every non-2xx that is not\n * 408/504 to FAILURE and retries it. On a permanently-413 batch: 12 HTTP\n * requests (4 re-queue rounds x 3 exporter attempts), then the ENTIRE batch\n * discarded as `transport_refused`. Counted and warned — but total loss.\n *\n * THE ESTIMATE, AND WHICH WAY IT ERRS. Serialized size is not knowable without\n * serializing, and serializing to measure would double the export cost. So the\n * batch is bounded on an ESTIMATE:\n *\n * string -> 2 + utf8ByteLength(s), the bytes `fetch` will send for\n * the raw characters\n * number/bool/null -> a fixed allowance; containers recurse to depth 4\n * anything else -> a fixed allowance (see `EST_OPAQUE_VALUE_BYTES`)\n *\n * ⚠ ASYMMETRY WITH PYTHON, DELIBERATE. Each SDK estimates against ITS OWN\n * encoder. `JSON.stringify` emits non-ASCII RAW (UTF-8 on the wire);\n * `json.dumps` escapes it to `\\uXXXX`. Measured: a 9,525-char CJK attribute is\n * 28,859 B from JS and ~2x that from Python. Mirroring Python's per-character\n * multiplier here would over-estimate every non-ASCII JS batch by ~4x.\n *\n * ⚠ THE ONE UNDER-ESTIMATE, NAMED: JSON escaping. A `\"` costs 2 bytes and a\n * control character 6; `utf8ByteLength` charges 1 for each. The 20 % margin\n * below is what absorbs it — a batch may be up to ~25 % escape characters BY\n * COUNT before the estimate stops covering the real body. Past that the gateway\n * refuses, exactly as it does today: no new failure mode, the bound is simply\n * not helping. Stated rather than engineered away because counting escapes is a\n * second O(bytes) scan.\n *\n * THE FRACTION: 8 MiB is 80 % of the gateway's 10 MiB default. Below it the\n * measured realistic corpus does not bind at batch 500 (1.24x under this\n * budget); above it, the 20 % is the escape margin.\n *\n * ⚠ COUPLING, DECLARED, with the SAME asymmetry as the attribute cap above:\n * stale LOW is unconditionally safe; stale HIGH is safe only while\n * `max_body_size` does not DECREASE.\n */\nexport const MAX_BATCH_BYTES = 8 * 1024 * 1024; // 8,388,608 B = 80 % of max_body_size\n\nconst SPAN_ENVELOPE_BYTES = 512; // typed camelCase fields; a minimal span is ~250 B\nconst CHILD_ENVELOPE_BYTES = 128; // per event / link, before its strings\nconst SCALAR_BYTES = 24; // widest JSON number repr\nconst LITERAL_BYTES = 5; // \"false\" / \"null\"\nconst EST_MAX_DEPTH = 4;\n/**\n * Charge for a value the ladder cannot walk (a class instance, a Map, anything\n * past `EST_MAX_DEPTH`). ⚠ Unlike Python — whose `_coerce_attribute_value`\n * truncates its `str()` fallback at 4,096 chars, making the same charge there a\n * genuine BOUND — JS has no truncation at all (`F-SDKATTRLEN-001`), so this is\n * an ALLOWANCE and a deeply-nested object can exceed it. The gateway refuses\n * that shape exactly as it does today.\n */\nconst EST_OPAQUE_VALUE_BYTES = 4_096;\n\n/**\n * UTF-8 byte length, without allocating the encoded copy.\n *\n * `Buffer.byteLength` is a single native scan and is what `fetch` will actually\n * put on the wire for the raw characters. The fallback multiplier 3 is a true\n * upper bound on UTF-8 bytes per UTF-16 code unit (a BMP code point is 1 unit\n * and at most 3 bytes; an astral one is 2 units and 4 bytes, i.e. 2 per unit),\n * so a Buffer-less runtime errs HIGH rather than low.\n */\nconst utf8ByteLength: (s: string) => number =\n typeof Buffer !== 'undefined' && typeof Buffer.byteLength === 'function'\n ? (s) => Buffer.byteLength(s, 'utf8')\n : (s) => s.length * 3;\n\nfunction estStringBytes(s: string): number {\n return 2 + utf8ByteLength(s);\n}\n\nfunction estValueBytes(v: unknown, depth = 0): number {\n if (typeof v === 'string') return estStringBytes(v);\n if (v === null || v === undefined || typeof v === 'boolean') return LITERAL_BYTES;\n if (typeof v === 'number' || typeof v === 'bigint') return SCALAR_BYTES;\n if (Array.isArray(v) && depth < EST_MAX_DEPTH) {\n let total = 2 + Math.max(0, v.length - 1);\n for (const item of v) total += estValueBytes(item, depth + 1);\n return total;\n }\n if (\n typeof v === 'object' &&\n depth < EST_MAX_DEPTH &&\n Object.getPrototypeOf(v as object) === Object.prototype\n ) {\n let total = 2;\n for (const [k, val] of Object.entries(v as Record<string, unknown>)) {\n total += estStringBytes(k) + 2 + estValueBytes(val, depth + 1);\n }\n return total;\n }\n return EST_OPAQUE_VALUE_BYTES;\n}\n\nfunction estMappingBytes(m: Record<string, unknown>): number {\n let total = 0;\n for (const [k, v] of Object.entries(m)) total += estStringBytes(k) + 2 + estValueBytes(v);\n return total;\n}\n\n/**\n * Estimated serialized bytes this span contributes to a request body, or the\n * fixed envelope if the object is not span-shaped.\n *\n * ⚠ Defensive in exactly the shape `spanAttrCount` is, and for the same reason:\n * TypeScript types `_queue` as `Span[]`, but nothing stops a JS caller or a test\n * double from queueing something else. Throwing from inside the export path\n * would break export for the whole batch. On any surprise this returns the\n * envelope, which can only make the bound LESS binding — never more, and never\n * a wedge.\n */\nfunction spanBytesEstimate(span: Span): number {\n try {\n const s = span as unknown as Record<string, unknown>;\n let total = SPAN_ENVELOPE_BYTES;\n for (const field of ['name', 'statusMessage'] as const) {\n if (typeof s[field] === 'string') total += estStringBytes(s[field] as string);\n }\n const attrs = s.attributes;\n if (attrs != null && typeof attrs === 'object' && !Array.isArray(attrs)) {\n total += estMappingBytes(attrs as Record<string, unknown>);\n }\n for (const key of ['events', 'links'] as const) {\n const coll = s[key];\n if (!Array.isArray(coll)) continue;\n for (const child of coll) {\n total += CHILD_ENVELOPE_BYTES;\n const ca = (child as Record<string, unknown> | null)?.attributes;\n if (ca != null && typeof ca === 'object' && !Array.isArray(ca)) {\n total += estMappingBytes(ca as Record<string, unknown>);\n }\n }\n }\n return total;\n } catch {\n return SPAN_ENVELOPE_BYTES;\n }\n}\n\n/**\n * Attribute count for the per-batch product bound, or 0 if unknowable.\n *\n * ⚠ Defensive for the same reason the Python `_span_attr_count` is: TypeScript\n * types `_queue` as `Span[]`, but nothing stops a JS caller (or a test double)\n * from queueing an object without `attributes`. Reading `.length` off\n * `undefined` would throw from inside the export path and break export for the\n * whole batch. An object with no countable attributes contributes 0, which can\n * only make the bound less binding, never more.\n */\nfunction spanAttrCount(span: Span): number {\n const attrs = (span as { attributes?: unknown }).attributes;\n if (attrs == null) return 0;\n if (attrs instanceof Map) return attrs.size;\n if (typeof attrs === 'object') return Object.keys(attrs as object).length;\n return 0;\n}\n\nexport class BatchSpanProcessor {\n private readonly _exporters: SpanExporter[];\n private readonly _batchSize: number;\n private readonly _batchTimeoutMs: number;\n private readonly _maxQueueSize: number;\n // ⚠ NO `_debug` FIELD. It existed, was assigned, and was read by NOTHING —\n // `tsc --noEmit` had been RED on this package at HEAD for it (TS6133), which\n // survived because `ci-local.sh` runs this package's vitest and never its\n // typecheck, and `prepublishOnly` runs `build && test` — also no typecheck.\n // Filed F-SDKJSTYPECHECK-001. Debug output here is gated globally by\n // `setDebug()` in `../utils/log.ts`, so a per-processor flag was always\n // redundant; Python's `self._debug` exists because `logging` has no such\n // global switch.\n\n private _queue: Span[] = [];\n private _timer: ReturnType<typeof setInterval> | null = null;\n private _started = false;\n private _flushing = false;\n private _beforeExitHandler: (() => void) | null = null;\n\n // Retry tracking for failed batches (Audit #5)\n private _retryCounts = new Map<string, number>();\n private static readonly MAX_RETRIES = 3;\n\n private _lastRefusalWarnAt = Number.NEGATIVE_INFINITY;\n\n // ── Masking (see `../masking.ts`) ──────────────────────────────────────────\n private readonly _mask: MaskFn | undefined;\n // ── Content capture gate (see `../masking.ts`) ─────────────────────────────\n // Fail-closed: an unspecified value means \"do not capture\". This is the ONE\n // place the gate runs for BOTH content paths — provider capture AND hand-set\n // attributes — so it must not be conditional on anything a caller might\n // forget to pass. Python twin: `BatchSpanProcessor._trace_content`.\n private readonly _traceContent: boolean;\n private _lastMaskWarnAt = Number.NEGATIVE_INFINITY;\n private _lastSlowMaskWarnAt = Number.NEGATIVE_INFINITY;\n\n // Metrics\n /** DEPRECATED flat total. Retained as the exact SUM of\n * `droppedSpansByReason` so existing readers keep working (RULING §5\n * back-compat — the same deprecate-and-alias shape this codebase used for\n * `complete`->`settled` and `spans_flushed_total`). Prefer the labelled\n * record: one integer cannot tell an under-provisioned queue from a dead\n * gateway from a redeploy. */\n droppedSpans = 0;\n droppedSpansByReason: Record<DropReason, number> = {\n queue_full: 0,\n transport_refused: 0,\n shutdown_residue: 0,\n };\n exportedSpans = 0;\n /** Export ATTEMPTS, not a span count. */\n failedExports = 0;\n /**\n * Fields whose mask callback threw and were replaced with\n * `MASK_ERROR_MARKER`. A FIELD count, not a span count — one span can\n * contribute several. Non-zero means those fields carry a marker instead of\n * data: a customer-code bug, not a transport one.\n */\n maskErrors = 0;\n\n constructor(options: BatchProcessorOptions) {\n this._exporters = [...options.exporters];\n\n // batchSize: clamp to [1, 10000] AND warn on out-of-range — silent\n // clamping is a debugging tar pit (CON-257 / P1-3). Mirrors Python.\n const requestedBatchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;\n const clampedBatchSize = Math.max(1, Math.min(requestedBatchSize, 10_000));\n if (clampedBatchSize !== requestedBatchSize) {\n warn(\n `batchSize=${requestedBatchSize} is outside the allowed range [1, 10000]; clamping to ${clampedBatchSize}`,\n );\n }\n this._batchSize = clampedBatchSize;\n\n this._batchTimeoutMs = options.batchTimeoutMs ?? 1000;\n this._maxQueueSize = options.maxQueueSize ?? 10000;\n this._mask = options.mask;\n this._traceContent = options.traceContent ?? false;\n }\n\n start(): void {\n if (this._started) return;\n this._started = true;\n\n // Periodic flush timer — unref so it doesn't keep process alive\n this._timer = setInterval(() => {\n void this._exportBatch();\n }, this._batchTimeoutMs);\n this._timer.unref();\n\n // Flush on process exit (Audit #3: use .once, not .on; await, not void)\n this._beforeExitHandler = () => {\n void this.shutdown();\n };\n process.once('beforeExit', this._beforeExitHandler);\n }\n\n /** Record `count` discarded spans under `reason`.\n *\n * `droppedSpans` is maintained as the exact sum of the labelled counters\n * (RULING §5 back-compat), so the locked pins — which read the flat\n * integer — stay meaningful. */\n private _recordDropped(reason: DropReason, count = 1): void {\n this.droppedSpans += count;\n this.droppedSpansByReason[reason] += count;\n }\n\n /**\n * Run the customer mask over a batch, in place. Never throws.\n *\n * Failure semantics are ruled in `../masking.ts`: a field whose mask throws\n * becomes `MASK_ERROR_MARKER` and the span is kept. The counter is per FIELD;\n * both warnings are rate-limited to one per window so a mask that throws on\n * every span cannot flood the customer's logs — the same shape as the\n * transport-refusal warning above.\n */\n private _applyMask(batch: Span[]): void {\n const mask = this._mask;\n if (mask === undefined) return;\n\n const { errors, elapsedMs } = applyMaskBatch(batch, mask);\n const now = Date.now();\n\n if (errors > 0) {\n this.maskErrors += errors;\n if (now - this._lastMaskWarnAt > MASK_WARN_WINDOW_MS) {\n this._lastMaskWarnAt = now;\n warnMaskErrors(errors, this.maskErrors);\n }\n }\n\n if (\n elapsedMs > MASK_BUDGET_MS_PER_SPAN * batch.length &&\n now - this._lastSlowMaskWarnAt > MASK_WARN_WINDOW_MS\n ) {\n this._lastSlowMaskWarnAt = now;\n warnMaskSlow(batch.length, elapsedMs);\n }\n }\n\n /**\n * Drain what we hold, or name what we could not (F-SDKDRAIN-001).\n *\n * Per RULING §4 (option E, hard-bounded) the drain loops until ONE of: the\n * queue is empty; the deadline expires; or a full round completes with no\n * exporter returning SUCCESS.\n *\n * ⚠ The `_flushing` handling is load-bearing, and `SDKDRAIN_JS_004` exists\n * to catch its absence. `_exportBatch()` returns immediately when an export\n * is already in flight (`:171`), so a loop that merely calls it again makes\n * NO progress and abandons the queue exactly as before — measured at 900 of\n * 1,000. We await a tick instead, the shape `flush()` already models.\n *\n * Anything still queued when the loop stops is COUNTED as `shutdown_residue`\n * and announced with a WARNING. The warning is the primary signal, not the\n * counter: a counter incremented inside `shutdown()` is written to memory\n * about to be freed and has no reader (RULING §2 / §8.2).\n */\n async shutdown(timeoutMs = SHUTDOWN_BUDGET_MS): Promise<void> {\n if (!this._started) return;\n this._started = false;\n\n if (this._timer) {\n clearInterval(this._timer);\n this._timer = null;\n }\n\n // Remove process listener to prevent leak (Audit #3)\n if (this._beforeExitHandler) {\n process.removeListener('beforeExit', this._beforeExitHandler);\n this._beforeExitHandler = null;\n }\n\n // Halve rather than underflow on a tiny budget: shutdown(200) still gets\n // 100 ms of drain instead of none.\n const reserveMs = Math.min(SHUTDOWN_RESERVE_MS, timeoutMs / 2);\n const drainDeadline = Date.now() + Math.max(0, timeoutMs - reserveMs);\n\n while (this._queue.length > 0 || this._flushing) {\n if (Date.now() >= drainDeadline) break;\n const outcome = await this._exportBatch();\n if (outcome === Round.Busy) {\n // An export is mid-await. Yield rather than spin on a no-op call.\n await new Promise((r) => setTimeout(r, 1));\n continue;\n }\n if (outcome !== Round.Delivered) {\n // Empty -> nothing left, we are done.\n // Failed -> no exporter accepted this round; a further round cannot\n // help and would spin to the deadline on precisely the path\n // where there is nothing to save.\n break;\n }\n }\n\n // Once shutdown() has returned, holding IS abandoning: the timer is\n // cleared, the exit listener is gone, nothing will ever export these.\n const residue = this._queue.length;\n if (residue > 0) {\n this._queue.length = 0;\n this._recordDropped('shutdown_residue', residue);\n // NOT rate-limited, by ruling. Names the count AND the reason.\n warn(\n `shutdown() gave up with ${residue} span(s) still queued ` +\n `(reason=shutdown_residue) — they were NOT delivered. The ${timeoutMs} ms ` +\n `shutdown budget expired or the transport stopped accepting. Raise the ` +\n `shutdown timeout, or your container's termination grace period, to lose less.`\n );\n }\n\n // Shutdown exporters\n for (const exporter of this._exporters) {\n try {\n await exporter.shutdown();\n } catch (e) {\n debug(`Error shutting down ${exporter.name}: ${e}`);\n }\n }\n\n // Clean up retry tracking — retry-map drain site 3 of 3\n this._retryCounts.clear();\n\n debug(\n `BatchSpanProcessor shutdown. Exported: ${this.exportedSpans}, ` +\n `Dropped: ${this.droppedSpans}, Failed: ${this.failedExports}`\n );\n }\n\n onSpanEnd(span: Span): void {\n if (!this._started) return;\n\n // Check queue capacity\n if (this._queue.length >= this._maxQueueSize) {\n this._recordDropped('queue_full');\n if (this.droppedSpans === 1 || this.droppedSpans % 1000 === 0) {\n warn(`Span queue full (${this._maxQueueSize}). ${this.droppedSpans} spans dropped so far.`);\n }\n return;\n }\n\n this._queue.push(span);\n\n // Trigger immediate flush if batch size reached\n if (this._queue.length >= this._batchSize) {\n void this._exportBatch();\n }\n }\n\n /**\n * Flush pending spans.\n *\n * @returns `true` only if everything queued at entry was DELIVERED.\n *\n * RULING §6. This used to answer a different question — \"is the queue\n * empty?\" — and those two diverge in exactly one case: when spans left the\n * queue WITHOUT reaching the transport. That case is the entire finding. A\n * customer who calls `flush()` before exit and gets `true` has done\n * everything right; silence lets them discover the problem, a false\n * affirmative forecloses it.\n *\n * Returns `false` when (a) the deadline expires with spans still queued,\n * (b) any span was discarded during the window — breaker refusal or retry\n * exhaustion — or (c) it is called after `shutdown()` and the shutdown\n * residue was non-zero.\n *\n * ⚠ (b) reads the flat total, so a concurrent `queue_full` drop of a span\n * that arrived DURING the window also answers `false`. That is the\n * conservative direction on purpose: a false negative costs a caller one\n * more flush, a false positive is the defect being fixed.\n */\n async flush(timeoutMs = SHUTDOWN_BUDGET_MS): Promise<boolean> {\n if (!this._started) {\n // (c) — the `!_started => true` early return was unconditional, so\n // `flush()` after `shutdown()` reported success over abandoned data.\n return this._queue.length === 0 && this.droppedSpansByReason.shutdown_residue === 0;\n }\n\n const start = Date.now();\n const discardedAtEntry = this.droppedSpans;\n\n // Wait for in-flight exports to complete AND queue to drain\n while (this._queue.length > 0 || this._flushing) {\n if (!this._flushing && this._queue.length > 0) {\n await this._exportBatch();\n } else {\n // Wait a tick for the in-flight export to finish\n await new Promise((r) => setTimeout(r, 1));\n }\n if (Date.now() - start > timeoutMs) return false;\n }\n\n return this.droppedSpans === discardedAtEntry;\n }\n\n getMetrics() {\n return {\n exportedSpans: this.exportedSpans,\n droppedSpans: this.droppedSpans,\n droppedSpansByReason: { ...this.droppedSpansByReason },\n failedExports: this.failedExports,\n maskErrors: this.maskErrors,\n queueSize: this._queue.length,\n queueCapacity: this._maxQueueSize,\n queueUtilization: this._queue.length / this._maxQueueSize,\n };\n }\n\n private async _exportBatch(): Promise<Round> {\n if (this._flushing) return Round.Busy;\n if (this._queue.length === 0) return Round.Empty;\n this._flushing = true;\n\n try {\n // Take up to batchSize spans — AND up to the attribute-product bound, AND\n // up to the serialized-byte bound; whichever binds first\n // (SDK-RELEASE-RULING.md §4.5 + F-SDKBYTES-001). `batchSize` is a CEILING,\n // not a fixed size, on all three axes.\n //\n // Take-at-least-one is unconditional on every axis: a single span that\n // alone exceeded a bound would otherwise be taken by no round ever,\n // wedging the queue permanently. One over-cap span is the gateway's\n // problem to refuse and the retry budget's to count; a wedged queue would\n // be ours forever.\n let take = 0;\n let pairs = 0;\n let nbytes = 0;\n const limit = Math.min(this._batchSize, this._queue.length);\n while (take < limit) {\n const head = this._queue[take];\n const spanPairs = spanAttrCount(head);\n const spanBytes = spanBytesEstimate(head);\n if (\n take > 0 &&\n (pairs + spanPairs > MAX_ATTRIBUTE_PAIRS_PER_BATCH ||\n nbytes + spanBytes > MAX_BATCH_BYTES)\n ) {\n break;\n }\n pairs += spanPairs;\n nbytes += spanBytes;\n take++;\n }\n const batch = this._queue.splice(0, take);\n if (batch.length === 0) return Round.Empty;\n\n // ⚠ MASK HERE — after the batch is off the queue, before any exporter.\n //\n // WHY NOT in `onSpanEnd()`: that runs on the call that ended the span,\n // i.e. inside the customer's own request path. This site is at least on\n // the export turn.\n //\n // ⚠ AND WHY THAT IS A WEAKER GUARANTEE THAN PYTHON'S: Node has one\n // thread. Python's mask runs on a background worker and costs only drain\n // rate; this one blocks the event loop for its duration. The budget\n // warning below is the whole of the protection, and it is a warning.\n //\n // ⚠ DECLARED RIPPLE, same as Python: the attribute-product and byte\n // bounds above are computed on PRE-mask values. Redaction shrinks, so the\n // estimate stays conservative for every realistic mask; a mask that GROWS\n // content can push the real body past the estimate, which the estimate\n // already declares for ASCII escaping and already answers the same way —\n // the gateway remains the enforcer.\n // ⚠ STRIP BEFORE MASK, and unconditionally when capture is off.\n //\n // Before mask because content the customer never wanted to leave the\n // process should not be handed to a customer callback either — and\n // because a mask never called over a stripped field costs nothing, which\n // matters more here than in Python: this runs on the ONE event loop.\n //\n // Unconditional (not `if this._mask !== undefined`) because THIS is the\n // gate: `_applyMask` runs only when a mask was supplied, and the whole\n // defect being closed is that content escaped when nobody had opted into\n // anything.\n if (!this._traceContent) {\n const stripped = stripContentBatch(batch);\n if (stripped > 0) {\n debug(\n `traceContent is off — omitted ${stripped} content field(s) from ${batch.length} span(s)`,\n );\n }\n }\n\n if (this._mask !== undefined) {\n this._applyMask(batch);\n }\n\n debug(`Exporting batch of ${batch.length} spans`);\n\n // Export to all exporters — count once, not per exporter\n let batchExported = false;\n for (const exporter of this._exporters) {\n try {\n const result = await exporter.export(batch);\n if (result === ExportResult.SUCCESS) {\n if (!batchExported) {\n this.exportedSpans += batch.length;\n batchExported = true;\n // Clear retry counts for successfully exported spans\n for (const span of batch) {\n this._retryCounts.delete(span.spanId);\n }\n }\n } else {\n this.failedExports++;\n }\n } catch (e) {\n this.failedExports++;\n debug(`Export to ${exporter.name} failed: ${e}`);\n }\n }\n\n // Audit #5: Re-queue failed batches with retry limit\n if (!batchExported) {\n let dropped = 0;\n const retryable = batch.filter(span => {\n const count = (this._retryCounts.get(span.spanId) ?? 0) + 1;\n if (count > BatchSpanProcessor.MAX_RETRIES) {\n // retry-map drain site 2 of 3\n this._retryCounts.delete(span.spanId);\n // The count is once per SPAN IDENTITY, at exhaustion — never once\n // per attempt. A span re-queued twice and then dropped is ONE lost\n // span; keying on spanId is what makes that true.\n this._recordDropped('transport_refused');\n dropped++;\n return false;\n }\n this._retryCounts.set(span.spanId, count);\n return true;\n });\n if (retryable.length > 0) {\n this._queue.unshift(...retryable);\n debug(`Re-queued ${retryable.length} spans for retry (${batch.length - retryable.length} dropped after max retries)`);\n }\n if (dropped > 0) {\n // RULING §2: the PRIMARY remedy is a default-visible WARNING at the\n // moment of discard, naming the count and the reason — not a counter.\n // The log line survives the process; the counter does not, and on the\n // shutdown path there is no reader for it at all. `debug()` above is\n // suppressed at default level, which is why this is `warn()`.\n const now = Date.now();\n if (now - this._lastRefusalWarnAt > REFUSAL_WARN_WINDOW_MS) {\n this._lastRefusalWarnAt = now;\n warn(\n `${dropped} span(s) DISCARDED (reason=transport_refused) after ` +\n `${BatchSpanProcessor.MAX_RETRIES} failed export attempts each — the endpoint is ` +\n `not accepting spans and the retry budget is spent. ` +\n `${this.droppedSpansByReason.transport_refused} span(s) discarded this way so far ` +\n `in this process. This data is gone; check the apiKey and the endpoint.`\n );\n }\n }\n }\n return batchExported ? Round.Delivered : Round.Failed;\n } finally {\n this._flushing = false;\n }\n }\n}\n","/**\n * ID generation for traces and spans.\n *\n * Trace IDs: 32 lowercase hex characters (16 random bytes)\n * Span IDs: 16 lowercase hex characters (8 random bytes)\n *\n * Uses crypto.randomBytes for cryptographically secure randomness.\n */\n\nimport { randomBytes } from 'node:crypto';\n\nconst HEX_REGEX_32 = /^[0-9a-f]{32}$/;\nconst HEX_REGEX_16 = /^[0-9a-f]{16}$/;\n\nexport function generateTraceId(): string {\n return randomBytes(16).toString('hex');\n}\n\nexport function generateSpanId(): string {\n return randomBytes(8).toString('hex');\n}\n\nexport function generateAgentId(prefix?: string): string {\n const suffix = randomBytes(8).toString('hex');\n return prefix ? `${prefix}-${suffix}` : suffix;\n}\n\nexport function validateTraceId(id: string): boolean {\n return HEX_REGEX_32.test(id);\n}\n\nexport function validateSpanId(id: string): boolean {\n return HEX_REGEX_16.test(id);\n}\n","/**\n * No-op implementations for the disabled path.\n *\n * When tracing is disabled, all operations return these no-op objects\n * to maintain zero overhead. No allocations, no side effects.\n */\n\nimport { SpanKind, SpanStatus, type SpanPayload } from './types.js';\n\n/**\n * A frozen no-op span that silently ignores all operations.\n * Used when SDK is disabled to avoid overhead.\n */\nexport const NOOP_SPAN = Object.freeze({\n traceId: '00000000000000000000000000000000',\n spanId: '0000000000000000',\n parentSpanId: undefined,\n name: 'noop',\n kind: SpanKind.INTERNAL,\n startTime: '',\n startHrtime: 0,\n endTime: undefined,\n status: SpanStatus.UNSET,\n statusMessage: undefined,\n attributes: Object.freeze({}) as Record<string, unknown>,\n events: Object.freeze([]) as readonly [],\n links: Object.freeze([]) as readonly [],\n sessionId: undefined,\n agentId: undefined,\n agentName: undefined,\n semanticPhase: undefined,\n llmProvider: undefined,\n llmModel: undefined,\n llmPromptTokens: undefined,\n llmCompletionTokens: undefined,\n llmTotalTokens: undefined,\n llmCostUsd: undefined,\n toolName: undefined,\n toolSuccess: undefined,\n isEnded: true,\n durationMs: 0,\n\n setAttribute() { return this; },\n setAttributes() { return this; },\n setStatus() { return this; },\n addEvent() { return this; },\n addLink() { return this; },\n recordException() { return this; },\n setLlmFields() { return this; },\n setToolFields() { return this; },\n end() {},\n toPayload(): SpanPayload {\n return {\n traceId: this.traceId,\n spanId: this.spanId,\n name: this.name,\n kind: this.kind,\n startTime: this.startTime,\n status: this.status,\n attributes: {},\n events: [],\n links: [],\n };\n },\n});\n\nexport type NoopSpan = typeof NOOP_SPAN;\n","// ⚠ GENERATED FILE — DO NOT EDIT BY HAND.\n//\n// Source of truth: packages/risicare-sdk/src/risicare/runtime/_error_taxonomy.py\n// Generator: packages/risicare-sdk/scripts/gen_js_taxonomy.py\n// Verify: scripts/contracts/lint-taxonomy-parity.sh\n//\n// F-SDKTAXFORK-001. This SDK cannot import `risicare_core.taxonomy` —\n// `risicare-core` is not published to npm. Rather than hand-maintain a second\n// copy of one rule (a divergence this campaign has measured four times), the\n// rule table and the canonical code set are generated from the Python source\n// and a rail fails when the two drift.\n//\n// 154 canonical codes across 10 modules.\n\nexport const CANONICAL_ERROR_CODES: ReadonlySet<string> = new Set([\n \"COMMUNICATION.CONTENT.AMBIGUOUS\",\n \"COMMUNICATION.CONTENT.CORRUPTED\",\n \"COMMUNICATION.CONTENT.INCOMPATIBLE\",\n \"COMMUNICATION.CONTENT.MALFORMED\",\n \"COMMUNICATION.CONTENT.TOO_LARGE\",\n \"COMMUNICATION.DELIVERY.DELAYED\",\n \"COMMUNICATION.DELIVERY.DUPLICATED\",\n \"COMMUNICATION.DELIVERY.EXPIRED\",\n \"COMMUNICATION.DELIVERY.OUT_OF_ORDER\",\n \"COMMUNICATION.DELIVERY.UNDELIVERABLE\",\n \"COMMUNICATION.ROUTING.BROADCAST_STORM\",\n \"COMMUNICATION.ROUTING.LOOP\",\n \"COMMUNICATION.ROUTING.NO_ROUTE\",\n \"COMMUNICATION.ROUTING.PARTITION\",\n \"COMMUNICATION.ROUTING.WRONG_ROUTE\",\n \"CONSENSUS.AGREEMENT.INCONSISTENT\",\n \"CONSENSUS.AGREEMENT.QUORUM_FAILED\",\n \"CONSENSUS.AGREEMENT.REJECTED\",\n \"CONSENSUS.AGREEMENT.STALE_VOTE\",\n \"CONSENSUS.AGREEMENT.TIMEOUT\",\n \"CONSENSUS.CONFLICT.BIAS\",\n \"CONSENSUS.CONFLICT.CASCADING\",\n \"CONSENSUS.CONFLICT.DEADLOCK\",\n \"CONSENSUS.CONFLICT.RESOLUTION_REJECTED\",\n \"CONSENSUS.CONFLICT.UNRESOLVED\",\n \"CONSENSUS.VOTING.ABSTENTION_FLOOD\",\n \"CONSENSUS.VOTING.COERCED_VOTE\",\n \"CONSENSUS.VOTING.DUPLICATE_VOTE\",\n \"CONSENSUS.VOTING.INVALID_VOTE\",\n \"CONSENSUS.VOTING.SPLIT_VOTE\",\n \"COORDINATION.HANDOFF.DELAYED\",\n \"COORDINATION.HANDOFF.DUPLICATED\",\n \"COORDINATION.HANDOFF.INCOMPLETE\",\n \"COORDINATION.HANDOFF.LOST\",\n \"COORDINATION.HANDOFF.WRONG_RECIPIENT\",\n \"COORDINATION.SYNCHRONIZATION.CLOCK_SKEW\",\n \"COORDINATION.SYNCHRONIZATION.OUT_OF_ORDER\",\n \"COORDINATION.SYNCHRONIZATION.RACE_CONDITION\",\n \"COORDINATION.SYNCHRONIZATION.SPLIT_BRAIN\",\n \"COORDINATION.SYNCHRONIZATION.VERSION_MISMATCH\",\n \"COORDINATION.WORKFLOW.CYCLE\",\n \"COORDINATION.WORKFLOW.DEADLOCK\",\n \"COORDINATION.WORKFLOW.LIVELOCK\",\n \"COORDINATION.WORKFLOW.ORPHANED\",\n \"COORDINATION.WORKFLOW.STARVATION\",\n \"MEMORY.CONTEXT_WINDOW.DROPPED\",\n \"MEMORY.CONTEXT_WINDOW.EXCEEDED\",\n \"MEMORY.CONTEXT_WINDOW.FRAGMENTED\",\n \"MEMORY.CONTEXT_WINDOW.PRIORITY_ERROR\",\n \"MEMORY.RETRIEVAL.INCOMPLETE\",\n \"MEMORY.RETRIEVAL.NOT_FOUND\",\n \"MEMORY.RETRIEVAL.OUTDATED\",\n \"MEMORY.RETRIEVAL.TOO_MANY\",\n \"MEMORY.RETRIEVAL.WRONG_MATCH\",\n \"MEMORY.STATE.CORRUPTED\",\n \"MEMORY.STATE.INCONSISTENT\",\n \"MEMORY.STATE.LOST\",\n \"MEMORY.STATE.OVERFLOW\",\n \"MEMORY.STATE.STALE\",\n \"ORCHESTRATION.DELEGATION.CAPABILITY_MISMATCH\",\n \"ORCHESTRATION.DELEGATION.CIRCULAR_DELEGATION\",\n \"ORCHESTRATION.DELEGATION.EXCESSIVE_DEPTH\",\n \"ORCHESTRATION.DELEGATION.NO_AVAILABLE_AGENT\",\n \"ORCHESTRATION.DELEGATION.OVERLOADED_AGENT\",\n \"ORCHESTRATION.LIFECYCLE.CLEANUP_FAILED\",\n \"ORCHESTRATION.LIFECYCLE.CRASHED\",\n \"ORCHESTRATION.LIFECYCLE.HUNG\",\n \"ORCHESTRATION.LIFECYCLE.SPAWN_FAILED\",\n \"ORCHESTRATION.LIFECYCLE.ZOMBIE\",\n \"ORCHESTRATION.SCALING.OVERLOADED\",\n \"ORCHESTRATION.SCALING.QUOTA_EXCEEDED\",\n \"ORCHESTRATION.SCALING.SCALE_DOWN_FAILED\",\n \"ORCHESTRATION.SCALING.SCALE_UP_FAILED\",\n \"ORCHESTRATION.SCALING.UNDERUTILIZED\",\n \"OUTPUT.FORMAT.ENCODING\",\n \"OUTPUT.FORMAT.INVALID_JSON\",\n \"OUTPUT.FORMAT.MALFORMED\",\n \"OUTPUT.FORMAT.SCHEMA_VIOLATION\",\n \"OUTPUT.FORMAT.TRUNCATED\",\n \"OUTPUT.QUALITY.INCOMPLETE\",\n \"OUTPUT.QUALITY.IRRELEVANT\",\n \"OUTPUT.QUALITY.REPETITIVE\",\n \"OUTPUT.QUALITY.UNCLEAR\",\n \"OUTPUT.QUALITY.VERBOSE\",\n \"OUTPUT.SAFETY.BIAS\",\n \"OUTPUT.SAFETY.COPYRIGHT\",\n \"OUTPUT.SAFETY.HARMFUL_CONTENT\",\n \"OUTPUT.SAFETY.PII_LEAK\",\n \"OUTPUT.SAFETY.POLICY_VIOLATION\",\n \"PERCEPTION.CONTEXT.CONFLICTING\",\n \"PERCEPTION.CONTEXT.IRRELEVANT\",\n \"PERCEPTION.CONTEXT.MISSING\",\n \"PERCEPTION.CONTEXT.OVERFLOW\",\n \"PERCEPTION.CONTEXT.STALE\",\n \"PERCEPTION.INPUT.ENCODING\",\n \"PERCEPTION.INPUT.INJECTION\",\n \"PERCEPTION.INPUT.MALFORMED\",\n \"PERCEPTION.INPUT.SCHEMA_MISMATCH\",\n \"PERCEPTION.INPUT.TRUNCATED\",\n \"PERCEPTION.PARSING.DATE_FORMAT\",\n \"PERCEPTION.PARSING.JSON_INVALID\",\n \"PERCEPTION.PARSING.NUMBER_FORMAT\",\n \"PERCEPTION.PARSING.REFERENCE_BROKEN\",\n \"PERCEPTION.PARSING.XML_INVALID\",\n \"REASONING.DECISION.BIASED\",\n \"REASONING.DECISION.INDECISIVE\",\n \"REASONING.DECISION.OSCILLATING\",\n \"REASONING.DECISION.OVERCONFIDENT\",\n \"REASONING.DECISION.PREMATURE\",\n \"REASONING.HALLUCINATION.CAPABILITY\",\n \"REASONING.HALLUCINATION.CITATION\",\n \"REASONING.HALLUCINATION.ENTITY\",\n \"REASONING.HALLUCINATION.FACTUAL\",\n \"REASONING.HALLUCINATION.TEMPORAL\",\n \"REASONING.LOGIC.CIRCULAR\",\n \"REASONING.LOGIC.CONTRADICTION\",\n \"REASONING.LOGIC.INCOMPLETE\",\n \"REASONING.LOGIC.INVALID_INFERENCE\",\n \"REASONING.LOGIC.MISSING_PREMISE\",\n \"REASONING.PLANNING.INCOMPLETE\",\n \"REASONING.PLANNING.INFEASIBLE\",\n \"REASONING.PLANNING.SCOPE_CREEP\",\n \"REASONING.PLANNING.SUBOPTIMAL\",\n \"REASONING.PLANNING.UNSAFE\",\n \"RESOURCES.ACCESS.DENIED\",\n \"RESOURCES.ACCESS.EXPIRED\",\n \"RESOURCES.ACCESS.LOCKED\",\n \"RESOURCES.ACCESS.NOT_FOUND\",\n \"RESOURCES.ACCESS.REVOKED\",\n \"RESOURCES.CONTENTION.DEADLOCK\",\n \"RESOURCES.CONTENTION.OVERFLOW\",\n \"RESOURCES.CONTENTION.PRIORITY_INVERSION\",\n \"RESOURCES.CONTENTION.STARVATION\",\n \"RESOURCES.CONTENTION.THRASHING\",\n \"RESOURCES.QUOTA.ALLOCATION_FAILED\",\n \"RESOURCES.QUOTA.EXCEEDED\",\n \"RESOURCES.QUOTA.LEAK\",\n \"RESOURCES.QUOTA.STALE\",\n \"RESOURCES.QUOTA.UNFAIR_DISTRIBUTION\",\n \"TOOL.EXECUTION.CRASHED\",\n \"TOOL.EXECUTION.DEPENDENCY_FAILED\",\n \"TOOL.EXECUTION.RATE_LIMITED\",\n \"TOOL.EXECUTION.RESOURCE_EXHAUSTED\",\n \"TOOL.EXECUTION.TIMEOUT\",\n \"TOOL.INVOCATION.INVALID_ARGS\",\n \"TOOL.INVOCATION.MISSING_REQUIRED\",\n \"TOOL.INVOCATION.NOT_FOUND\",\n \"TOOL.INVOCATION.PERMISSION_DENIED\",\n \"TOOL.INVOCATION.TYPE_MISMATCH\",\n \"TOOL.RESULT.EMPTY\",\n \"TOOL.RESULT.ERROR_IN_RESULT\",\n \"TOOL.RESULT.PARTIAL\",\n \"TOOL.RESULT.UNEXPECTED_FORMAT\",\n \"TOOL.RESULT.UNPARSEABLE\",\n]);\n\nexport interface TaxonomyRule {\n re: RegExp;\n code: string;\n}\n\n/** Order matters: first match wins, most specific first. */\nexport const SUPPLEMENTAL_RULES: readonly TaxonomyRule[] = [\n { re: new RegExp(\"timeout|timedout|aborted\", 'i'), code: \"TOOL.EXECUTION.TIMEOUT\" },\n { re: new RegExp(\"rate.?limit|\\\\b429\\\\b|too many requests\", 'i'), code: \"TOOL.EXECUTION.RATE_LIMITED\" },\n { re: new RegExp(\"connection|econnrefused|econnreset|enotfound|fetch failed|unreachable|broken pipe\", 'i'), code: \"TOOL.EXECUTION.DEPENDENCY_FAILED\" },\n { re: new RegExp(\"\\\\bauth|unauthorized|forbidden|permission|\\\\b401\\\\b|\\\\b403\\\\b\", 'i'), code: \"TOOL.INVOCATION.PERMISSION_DENIED\" },\n { re: new RegExp(\"json|syntaxerror|unexpected token|decodeerror\", 'i'), code: \"PERCEPTION.PARSING.JSON_INVALID\" },\n];\n\nexport const GENERIC_FALLBACK = \"TOOL.EXECUTION.CRASHED\";\n","/**\n * Fix Applier — Applies fixes to agent operations.\n *\n * Handles different fix types:\n * - PromptFix: Modify system/user prompts (prepend, append, replace, few_shot)\n * - ParameterFix: Adjust LLM parameters (temperature, model, etc.)\n * - RetryFix: Retry with exponential backoff + jitter\n * - FallbackFix: Switch to fallback model or default response\n * - GuardFix: Input/output validation (content filter, format check, length)\n *\n * Port of Python SDK's runtime/applier.py adapted for Node.js.\n */\n\nimport { createHash } from 'node:crypto';\nimport type { ActiveFix, FixRuntimeConfig } from './config.js';\nimport { shouldApply, resolveFixRuntimeConfig } from './config.js';\nimport type { FixCache } from './cache.js';\nimport { debug, warn } from '../utils/log.js';\n\n/**\n * Maximum length for fix content injected into prompts.\n * Prevents unbounded prompt injection from malicious/corrupted fix configs.\n */\nconst MAX_FIX_CONTENT_LENGTH = 10_000;\n\n// ─── Apply Result ───────────────────────────────────────────────────────────\n\nexport interface ApplyResult {\n applied: boolean;\n fixId?: string;\n deploymentId?: string;\n fixType?: string;\n modifications: Record<string, unknown>;\n error?: string;\n /**\n * Guard-only: human-readable reason a guard failed (passed=false). Used\n * by GuardRejectedError to surface an actionable message to the customer.\n * `error` carries the raw exception text; `reason` carries the audit\n * category ('guard_exception', 'content_filter', 'format_check', etc.).\n */\n reason?: string;\n}\n\nfunction emptyResult(fix: ActiveFix, fixType: string): ApplyResult {\n return {\n applied: false,\n fixId: fix.fixId,\n deploymentId: fix.deploymentId,\n fixType,\n modifications: {},\n };\n}\n\n// ─── Fix Applier ────────────────────────────────────────────────────────────\n\nexport class FixApplier {\n private readonly _config: Required<FixRuntimeConfig>;\n private readonly _cache: FixCache;\n private _applicationLog: ApplyResult[] = [];\n\n constructor(config: FixRuntimeConfig, cache: FixCache) {\n this._config = resolveFixRuntimeConfig(config);\n this._cache = cache;\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // Fix Lookup\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Get applicable fix for an error code.\n *\n * Considers A/B testing bucket if sessionId is provided. Uses\n * crypto.createHash('md5') for deterministic bucketing across restarts.\n */\n getFixForError(\n errorCode: string,\n sessionId?: string,\n ): ActiveFix | null {\n try {\n const fix = this._cache.get(errorCode);\n if (!fix) return null;\n\n // Check A/B test bucketing\n if (sessionId && this._config.abTestingEnabled) {\n const hashHex = createHash('md5')\n .update(sessionId)\n .digest('hex')\n .substring(0, 8);\n const sessionHash = parseInt(hashHex, 16);\n\n if (!shouldApply(fix, sessionHash)) {\n debug(`Fix ${fix.fixId} not applied (A/B control group)`);\n return null;\n }\n }\n\n return fix;\n } catch (e) {\n debug(`getFixForError error: ${e}`);\n return null;\n }\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // 1. Prompt Fix\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Apply a prompt fix to messages.\n *\n * Supports 4 modification types:\n * - prepend: Add content before first system message\n * - append: Add content after first system message\n * - replace: Regex replace across all messages\n * - few_shot: Insert user/assistant example pairs after system message\n */\n applyPromptFix(\n fix: ActiveFix,\n messages: Record<string, unknown>[],\n ): { messages: Record<string, unknown>[]; result: ApplyResult } {\n try {\n const cfg = fix.config;\n const modificationType = (cfg.modification_type ?? cfg.modificationType ?? 'append') as string;\n const target = (cfg.target ?? 'system') as string;\n let content = (cfg.content ?? '') as string;\n\n // Truncate oversized content to prevent prompt injection\n if (content.length > MAX_FIX_CONTENT_LENGTH) {\n warn(\n `Fix ${fix.fixId} content truncated from ${content.length} to ${MAX_FIX_CONTENT_LENGTH} chars`,\n );\n content = content.slice(0, MAX_FIX_CONTENT_LENGTH);\n }\n\n const result = emptyResult(fix, 'prompt');\n\n if (this._config.dryRun) {\n result.modifications = {\n type: modificationType,\n target,\n contentPreview: content.slice(0, 100),\n };\n return { messages, result };\n }\n\n let modified = messages.map((m) => ({ ...m }));\n\n if (modificationType === 'prepend') {\n modified = this._prependToTarget(modified, target, content);\n result.applied = true;\n result.modifications = { type: 'prepend', target };\n } else if (modificationType === 'append') {\n modified = this._appendToTarget(modified, target, content);\n result.applied = true;\n result.modifications = { type: 'append', target };\n } else if (modificationType === 'replace') {\n const pattern = (cfg.pattern ?? '') as string;\n if (pattern) {\n modified = this._replaceInMessages(modified, pattern, content);\n result.applied = true;\n result.modifications = { type: 'replace', pattern };\n }\n } else if (modificationType === 'few_shot') {\n const examples = (cfg.examples ?? []) as Array<Record<string, string>>;\n if (examples.length > 0) {\n modified = this._addFewShotExamples(modified, examples);\n result.applied = true;\n result.modifications = { type: 'few_shot', count: examples.length };\n }\n }\n\n return { messages: modified, result };\n } catch (e) {\n debug(`applyPromptFix error: ${e}`);\n return {\n messages,\n result: {\n applied: false,\n fixId: fix.fixId,\n fixType: 'prompt',\n modifications: {},\n error: String(e),\n },\n };\n }\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // 2. Parameter Fix\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Apply a parameter fix — merge config.parameters into params.\n */\n applyParameterFix(\n fix: ActiveFix,\n params: Record<string, unknown>,\n ): { params: Record<string, unknown>; result: ApplyResult } {\n try {\n const newParams = (fix.config.parameters ?? {}) as Record<string, unknown>;\n const result = emptyResult(fix, 'parameter');\n\n if (this._config.dryRun) {\n result.modifications = { parameters: newParams };\n return { params, result };\n }\n\n const modified = { ...params, ...newParams };\n result.applied = true;\n result.modifications = { parameters: newParams };\n\n return { params: modified, result };\n } catch (e) {\n debug(`applyParameterFix error: ${e}`);\n return {\n params,\n result: {\n applied: false,\n fixId: fix.fixId,\n fixType: 'parameter',\n modifications: {},\n error: String(e),\n },\n };\n }\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // 3. Retry Fix (async — uses setTimeout for sleeping)\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Apply a retry fix to an async operation.\n *\n * Retries with exponential backoff + jitter using\n * `await new Promise(r => setTimeout(r, delay))`.\n */\n async applyRetryFix<T>(\n fix: ActiveFix,\n operation: () => Promise<T>,\n ): Promise<{ value: T; result: ApplyResult }> {\n const cfg = fix.config;\n const maxRetries = (cfg.max_retries ?? cfg.maxRetries ?? 3) as number;\n const initialDelayMs = (cfg.initial_delay_ms ?? cfg.initialDelayMs ?? 1000) as number;\n const maxDelayMs = (cfg.max_delay_ms ?? cfg.maxDelayMs ?? 30_000) as number;\n const exponentialBase = (cfg.exponential_base ?? cfg.exponentialBase ?? 2.0) as number;\n const jitter = (cfg.jitter ?? true) as boolean;\n const retryOn = (cfg.retry_on ?? cfg.retryOn ?? []) as string[];\n\n const result = emptyResult(fix, 'retry');\n\n if (this._config.dryRun) {\n result.modifications = { maxRetries, initialDelayMs };\n const value = await operation();\n return { value, result };\n }\n\n let lastError: Error | null = null;\n let attempts = 0;\n\n for (let attempt = 0; attempt <= maxRetries; attempt++) {\n attempts++;\n try {\n const value = await operation();\n result.applied = true;\n result.modifications = { attempts };\n return { value, result };\n } catch (e) {\n lastError = e instanceof Error ? e : new Error(String(e));\n const errorType = lastError.constructor.name;\n\n // Check if we should retry this specific error type\n if (retryOn.length > 0 && !retryOn.includes(errorType)) {\n throw lastError;\n }\n\n if (attempt < maxRetries) {\n // Calculate delay with exponential backoff\n let delayMs = Math.min(\n initialDelayMs * Math.pow(exponentialBase, attempt),\n maxDelayMs,\n );\n\n // Add jitter: multiply by random factor [0.5, 1.5)\n if (jitter) {\n delayMs *= 0.5 + Math.random();\n }\n\n debug(\n `Retry ${attempt + 1}/${maxRetries} after ${Math.round(delayMs)}ms`,\n );\n await new Promise<void>((r) => setTimeout(r, delayMs));\n }\n }\n }\n\n // All retries exhausted\n result.applied = true;\n result.error = lastError?.message;\n result.modifications = { attempts, exhausted: true };\n throw lastError;\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // 4. Fallback Fix\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Apply a fallback fix.\n *\n * - 'model': Replace params.model with the fallback model\n * - 'default': Set params._fallbackResponse for the caller to use\n */\n applyFallbackFix(\n fix: ActiveFix,\n params: Record<string, unknown>,\n ): { params: Record<string, unknown>; result: ApplyResult } {\n try {\n const cfg = fix.config;\n const fallbackType = (cfg.fallback_type ?? cfg.fallbackType ?? 'model') as string;\n const fallbackConfig = (cfg.fallback_config ?? cfg.fallbackConfig ?? {}) as Record<string, unknown>;\n const result = emptyResult(fix, 'fallback');\n\n if (this._config.dryRun) {\n result.modifications = { fallbackType, fallbackConfig };\n return { params, result };\n }\n\n const modified = { ...params };\n\n if (fallbackType === 'model') {\n const fallbackModel = fallbackConfig.model as string | undefined;\n if (fallbackModel) {\n modified.model = fallbackModel;\n result.applied = true;\n result.modifications = { model: fallbackModel };\n }\n } else if (fallbackType === 'default') {\n const defaultResponse = fallbackConfig.response;\n if (defaultResponse !== undefined) {\n modified._fallbackResponse = defaultResponse;\n result.applied = true;\n result.modifications = { defaultResponse: true };\n }\n }\n\n return { params: modified, result };\n } catch (e) {\n debug(`applyFallbackFix error: ${e}`);\n return {\n params,\n result: {\n applied: false,\n fixId: fix.fixId,\n fixType: 'fallback',\n modifications: {},\n error: String(e),\n },\n };\n }\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // 5. Guard Fix\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Apply a guard fix (validation).\n *\n * Guard types:\n * - content_filter: Regex-based blocked patterns\n * - format_check: JSON.parse() validity\n * - input_validation / output_validation: min/max length\n */\n applyGuardFix(\n fix: ActiveFix,\n content: string,\n isInput = true,\n ): { content: string; passed: boolean; result: ApplyResult } {\n try {\n const cfg = fix.config;\n const guardType = (cfg.guard_type ?? cfg.guardType ?? 'output_validation') as string;\n const guardConfig = (cfg.guard_config ?? cfg.guardConfig ?? {}) as Record<string, unknown>;\n const result = emptyResult(fix, 'guard');\n\n // Check if guard applies to this direction\n if (isInput && guardType !== 'input_validation' && guardType !== 'content_filter') {\n return { content, passed: true, result };\n }\n if (!isInput && guardType !== 'output_validation' && guardType !== 'format_check') {\n return { content, passed: true, result };\n }\n\n if (this._config.dryRun) {\n result.modifications = { guardType };\n return { content, passed: true, result };\n }\n\n let passed = true;\n let reason: string | undefined;\n\n if (guardType === 'content_filter') {\n const blockedPatterns = (guardConfig.blocked_patterns ?? guardConfig.blockedPatterns ?? []) as string[];\n for (const pattern of blockedPatterns) {\n const regex = this._safeCompileRegex(pattern);\n if (regex && regex.test(content)) {\n passed = false;\n reason = `blocked pattern matched: ${pattern.slice(0, 80)}`;\n break;\n }\n }\n } else if (guardType === 'format_check') {\n const requiredFormat = guardConfig.format as string | undefined;\n if (requiredFormat === 'json') {\n try {\n JSON.parse(content);\n } catch {\n passed = false;\n reason = 'format_check: invalid JSON';\n }\n }\n } else if (guardType === 'input_validation' || guardType === 'output_validation') {\n const minLength = (guardConfig.min_length ?? guardConfig.minLength ?? 0) as number;\n const maxLength = (guardConfig.max_length ?? guardConfig.maxLength ?? Infinity) as number;\n if (content.length < minLength || content.length > maxLength) {\n passed = false;\n reason = `${guardType}: length ${content.length} outside [${minLength}, ${maxLength}]`;\n }\n }\n\n result.applied = true;\n result.modifications = { passed, guardType };\n if (reason !== undefined) result.reason = reason;\n\n return { content, passed, result };\n } catch (e) {\n // F-731: Fail-CLOSED on guard error. An unexpected exception in a\n // safety-validation path MUST NOT silently pass content through —\n // that would defeat the entire purpose of input/output validation.\n // PR-4+5 review B2 (2026-05-25): the interceptor LAYER now reads\n // `passed:false` and throws GuardRejectedError to short-circuit the\n // LLM call. Before B2 this `passed:false` was advisory only — the\n // provider patcher consumed `modifications` / `messages` but never\n // read `passed`, so a thrown-getter attack still hit the LLM with\n // the attacker payload. The applier's job is to TELL the truth;\n // the interceptor's job is to ACT on it.\n warn(`applyGuardFix error (failing CLOSED): ${e}`);\n return {\n content,\n passed: false,\n result: {\n applied: true,\n fixId: fix.fixId,\n fixType: 'guard',\n modifications: { passed: false, reason: 'guard_exception' },\n error: String(e),\n reason: 'guard_exception',\n },\n };\n }\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // Application Log\n // ═══════════════════════════════════════════════════════════════════════════\n\n /** Log a fix application result. */\n logApplication(result: ApplyResult): void {\n this._applicationLog.push(result);\n\n // Limit log size\n if (this._applicationLog.length > 1000) {\n this._applicationLog = this._applicationLog.slice(-500);\n }\n }\n\n /** Get the application log. */\n getApplicationLog(): ApplyResult[] {\n return [...this._applicationLog];\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // Private Helpers\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Safely compile a regex pattern from untrusted input.\n * Returns null if invalid or too long.\n */\n private _safeCompileRegex(\n pattern: string,\n maxLength = 500,\n ): RegExp | null {\n if (!pattern || pattern.length > maxLength) return null;\n try {\n return new RegExp(pattern, 'i');\n } catch {\n debug(`Invalid regex pattern (length=${pattern.length})`);\n return null;\n }\n }\n\n /** Prepend content to the first message matching the target role. */\n private _prependToTarget(\n messages: Record<string, unknown>[],\n target: string,\n content: string,\n ): Record<string, unknown>[] {\n return messages.map((msg) => {\n if (msg.role === target) {\n return {\n ...msg,\n content: content + '\\n\\n' + ((msg.content as string) ?? ''),\n };\n }\n return msg;\n });\n }\n\n /** Append content to the first message matching the target role. */\n private _appendToTarget(\n messages: Record<string, unknown>[],\n target: string,\n content: string,\n ): Record<string, unknown>[] {\n return messages.map((msg) => {\n if (msg.role === target) {\n return {\n ...msg,\n content: ((msg.content as string) ?? '') + '\\n\\n' + content,\n };\n }\n return msg;\n });\n }\n\n /** Regex replace across all messages. */\n private _replaceInMessages(\n messages: Record<string, unknown>[],\n pattern: string,\n replacement: string,\n ): Record<string, unknown>[] {\n const regex = this._safeCompileRegex(pattern);\n if (!regex) {\n debug('Skipping invalid regex pattern in prompt fix');\n return messages;\n }\n\n return messages.map((msg) => {\n const msgContent = msg.content;\n if (typeof msgContent === 'string') {\n return { ...msg, content: msgContent.replace(regex, replacement) };\n }\n return msg;\n });\n }\n\n /** Add few-shot examples after the first system message. */\n private _addFewShotExamples(\n messages: Record<string, unknown>[],\n examples: Array<Record<string, string>>,\n ): Record<string, unknown>[] {\n const result: Record<string, unknown>[] = [];\n let systemFound = false;\n\n for (const msg of messages) {\n result.push(msg);\n\n if (msg.role === 'system' && !systemFound) {\n systemFound = true;\n for (const example of examples) {\n if (example.user) {\n result.push({ role: 'user', content: example.user });\n }\n if (example.assistant) {\n result.push({ role: 'assistant', content: example.assistant });\n }\n }\n }\n }\n\n return result;\n }\n}\n","/**\n * Provider patcher input validation.\n *\n * F-722/F-620: every `patchX(client)` entry point creates `new Proxy(client, ...)`.\n * Proxy constructors throw an opaque `TypeError: Cannot create proxy with a non-object\n * as target or handler` when handed `null`, `undefined`, a primitive, or `false`.\n * That error happens deep in the SDK with no actionable message — and it crashes\n * the customer's app startup the moment they pass a maybe-null client.\n *\n * We fail-fast with a clear, named TypeError so the customer sees:\n * \"patchOpenAI requires a client object, got null\"\n * instead of:\n * \"Cannot create proxy with a non-object as target or handler\"\n *\n * Rationale for throwing (not returning the input):\n * - Returning the input would silently disable instrumentation; a customer who\n * expects spans would see \"no traces\" and have to root-cause it themselves.\n * - Throwing surfaces the bug at the call-site (their `patchOpenAI(maybeNull)`).\n * - It happens at init/setup time, not in the request hot path, so no latency cost.\n */\n// PR-4+5 review NIT (2026-05-25): asserts-style narrowing. Pre-fix the\n// signature returned `void` with an `unknown` client parameter, forcing\n// every patcher's `new Proxy(client, ...)` call to keep the `unknown` /\n// loose `T` type — TS could not prove the Proxy target was non-null.\n// `asserts client is NonNullable<T>` means TS narrows the caller's\n// variable after assertClient returns, so the surrounding code is\n// type-safe without redundant runtime checks.\nexport function assertClient<T>(\n patcherName: string,\n client: T,\n): asserts client is NonNullable<T> {\n if (client === null || client === undefined) {\n throw new TypeError(\n `${patcherName} requires a client object, got ${client === null ? 'null' : 'undefined'}`,\n );\n }\n const t = typeof client;\n if (t !== 'object' && t !== 'function') {\n throw new TypeError(\n `${patcherName} requires a client object, got ${t}`,\n );\n }\n}\n","/**\n * Instructor integration via Proxy wrapping.\n *\n * Instructor wraps an LLM client's create() method to extract structured\n * data from completions using a response model (Zod schema, etc.).\n *\n * F-884: The Instructor JS client (`@instructor-ai/instructor`) exposes the\n * structured-extraction method at `client.chat.completions.create(...)` —\n * mirroring the underlying OpenAI shape — NOT at a top-level `client.create`.\n * The previous patcher hooked the top-level `create`, which Instructor JS does\n * not have, so no spans ever fired. We now walk the nested path (chat →\n * completions → create) AND keep a top-level `create` intercept for forward-\n * compatibility with API shapes that may expose both.\n *\n * Usage:\n * import { patchInstructor } from 'risicare/instructor';\n * import Instructor from '@instructor-ai/instructor';\n * const client = patchInstructor(Instructor({ client: openai, mode: 'TOOLS' }));\n * const result = await client.chat.completions.create({\n * model: 'gpt-4o-mini',\n * messages: [...],\n * response_model: { schema: MySchema, name: 'MyExtraction' },\n * });\n *\n * Does NOT suppress provider instrumentation -- Instructor delegates to the\n * underlying LLM client, which should produce its own provider span.\n */\n\nimport { getTracer } from '../client.js';\nimport { SpanKind } from '../types.js';\nimport { debug } from '../utils/log.js';\nimport { assertClient } from '../utils/assert-client.js';\n\n/**\n * Build the wrapped `create` function. Shared between top-level (legacy) and\n * nested (`chat.completions.create`, the real Instructor JS shape) intercepts.\n */\nfunction makePatchedCreate(originalCreate: Function): Function {\n return function patchedCreate(this: unknown, ...args: unknown[]): unknown {\n const tracer = getTracer();\n if (!tracer?.enabled) {\n debug('Tracer not initialized — call init() before using patchInstructor()');\n return originalCreate.apply(this, args);\n }\n\n const params = (args[0] ?? {}) as Record<string, unknown>;\n // Instructor JS accepts response_model as { schema, name } or a Zod schema\n const responseModel = params.response_model ?? params.responseModel;\n\n let modelName = 'unknown';\n if (responseModel && typeof responseModel === 'function') {\n modelName = (responseModel as { name?: string }).name || 'unknown';\n } else if (responseModel && typeof responseModel === 'object') {\n const rm = responseModel as Record<string, unknown>;\n modelName =\n (rm.name as string) ??\n (rm.description as string) ??\n ((rm.schema as { name?: string } | undefined)?.name) ??\n 'schema';\n } else if (typeof responseModel === 'string') {\n modelName = responseModel;\n }\n\n return tracer.startSpan(\n {\n name: 'instructor.create',\n kind: SpanKind.LLM_CALL,\n attributes: {\n framework: 'instructor',\n 'framework.span_kind': 'extraction',\n 'instructor.response_model': modelName,\n ...(params.max_retries != null\n ? { 'instructor.max_retries': params.max_retries }\n : {}),\n ...(params.model != null\n ? { 'gen_ai.request.model': params.model }\n : {}),\n },\n },\n (_span) => {\n const result = originalCreate.apply(this, args);\n if (result && typeof (result as Promise<unknown>).then === 'function') {\n return (result as Promise<unknown>).then((r) => r);\n }\n return result;\n },\n );\n };\n}\n\n/**\n * Wrap an Instructor client with Risicare tracing.\n *\n * Intercepts BOTH:\n * - `client.chat.completions.create` (the real Instructor JS shape)\n * - `client.create` (legacy top-level shape, if present)\n *\n * @param client - An Instructor client\n * @returns A proxied client with tracing enabled\n */\nexport function patchInstructor<T extends object>(client: T): T {\n assertClient('patchInstructor', client);\n return new Proxy(client, {\n get(target, prop, receiver) {\n const value = Reflect.get(target, prop, receiver);\n\n // Legacy top-level create (rare, but harmless to keep for compat).\n if (prop === 'create' && typeof value === 'function') {\n return makePatchedCreate(value.bind(target));\n }\n\n // F-884: REAL Instructor JS shape — walk into `.chat.completions.create`.\n if (prop === 'chat' && value && typeof value === 'object') {\n return new Proxy(value as object, {\n get(chatTarget, chatProp, chatReceiver) {\n const chatValue = Reflect.get(chatTarget, chatProp, chatReceiver);\n if (chatProp === 'completions' && chatValue && typeof chatValue === 'object') {\n return new Proxy(chatValue as object, {\n get(compTarget, compProp, compReceiver) {\n const compValue = Reflect.get(compTarget, compProp, compReceiver);\n if (compProp === 'create' && typeof compValue === 'function') {\n return makePatchedCreate(compValue.bind(compTarget));\n }\n return compValue;\n },\n });\n }\n return chatValue;\n },\n });\n }\n\n return value;\n },\n });\n}\n"],"mappings":"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","names":["createHash","getTracer","getTracer"]}
|
|
1
|
+
{"version":3,"sources":["../../src/client.ts","../../src/globals.ts","../../src/utils/log.ts","../../src/utils/text.ts","../../src/utils/scrub.ts","../../src/exporters/batch.ts","../../src/ids.ts","../../src/noop.ts","../../src/runtime/config.ts","../../src/runtime/taxonomy.generated.ts","../../src/version.ts","../../src/exporters/http.ts","../../src/runtime/applier.ts","../../src/runtime/loader.ts","../../src/utils/assert-client.ts","../../src/frameworks/instructor.ts"],"sourcesContent":["/**\n * RisicareClient — singleton client managing SDK lifecycle.\n *\n * Handles initialization, shutdown, and the connection between\n * the Tracer and the export pipeline (batch processor + HTTP exporter).\n *\n * Usage:\n * import { init, shutdown } from 'risicare';\n * init({ apiKey: 'rsk-...' }); // API key determines project\n * // ... instrument code ...\n * await shutdown(); // flush remaining spans\n */\n\n// ⚠ F-SDKJSREPORTERROR-001 (W20, 2026-08-14) — STATIC, and it must stay static.\n// This was `require('node:crypto')` INSIDE `_errorFingerprint()`. esbuild\n// rewrites a bare `require` in an ESM output bundle to `__require(\"crypto\")`,\n// whose shim THROWS at call time; `reportError`'s catch-all then swallowed it\n// (`client.ts` ~:597, \"Never crash the host application\"). Net effect measured\n// on clean tarball installs of the PUBLISHED 0.4.2: reportError() delivered\n// ZERO spans under ESM and one under CJS — a silent no-op for every ESM\n// customer, which is the default for modern Node apps.\n//\n// A static import adds NO new environmental constraint: the package's main\n// entry already pulls `node:crypto` statically, because `src/index.ts` re-\n// exports `./webhooks.js`, which does `import { createHmac, timingSafeEqual }\n// from 'node:crypto'` at `webhooks.ts:53`. Same precedent, same module.\n//\n// ⚠ Do NOT \"optimise\" this back to a lazy require to keep the module edge-safe.\n// It would not achieve that (see above) and it silently re-breaks ESM. Verify\n// with `bash fix-workstream/perf/sdkjs/reporterror_module_system_probe.sh`,\n// whose CJS arm is the non-vacuity control and gates the exit code.\nimport { createHash } from 'node:crypto';\nimport { type RisicareConfig, resolveConfig, given, tracingTurnedOff } from './config.js';\nimport { Tracer, attachErrorCode } from './tracer.js';\nimport { SDK_VERSION } from './version.js';\nimport { BatchSpanProcessor, SHUTDOWN_BUDGET_MS, normalizeTimeoutMs } from './exporters/batch.js';\nimport { HttpExporter } from './exporters/http.js';\nimport { SpanKind, SpanStatus } from './types.js';\nimport type { SpanExporter } from './exporters/base.js';\nimport { setDebug, debug, warn } from './utils/log.js';\nimport { cutCodePoints } from './utils/text.js';\nimport { endOpenProviderSpans } from './utils/stream-proxy.js';\nimport { maskText, SCORE_COMMENT_KEY } from './masking.js';\nimport {\n getClient as getGlobalClient,\n setClient as setGlobalClient,\n getTracer as getGlobalTracer,\n setTracer as setGlobalTracer,\n} from './globals.js';\n// PR-4+5 review NIT (2026-05-25): static ESM import. Pre-fix this was a\n// CJS `require('./runtime/runtime.js')` inside the constructor, which\n// dies in TS-source consumers (vitest, ts-node ESM) because the .js\n// resolution fails — tripping the FixRuntime catch and emitting a\n// spurious \"auto-fix is OFFLINE\" warning on EVERY test that calls init().\n// Static import resolves at module-load time and works identically under\n// ESM and CJS bundles produced by tsup. The CON-194 test still exercises\n// the failure path via vi.mock() (which intercepts ES imports correctly).\nimport { initFixRuntime, shutdownFixRuntime } from './runtime/runtime.js';\nimport { safeUrl, scrubText } from './utils/scrub.js';\n\n/**\n * Signals whose default disposition is TERMINATE, with their numbers — needed\n * for the conventional `128 + signum` exit code (SIGTERM 143, SIGINT 130).\n * SDK-RELEASE-RULING.md §3.\n */\nconst TERMINATING_SIGNALS: ReadonlyArray<readonly [string, number]> = [\n ['SIGTERM', 15],\n ['SIGINT', 2],\n];\n\n/**\n * Headroom between the shutdown budget and the backstop that force-exits if\n * shutdown never resolves. It must be > 0 or the backstop races the drain; it\n * is small because it buys nothing but the difference between \"the drain\n * finished\" and \"the drain is wedged\". The drain itself is a hard wall-clock\n * bound: each round is raced against the budget, and an export that the drain\n * abandons is aborted. So 500 ms covers only timer delay and the exporters'\n * own `shutdown()` after the drain, not a round that overruns the budget.\n */\nconst BACKSTOP_MARGIN_MS = 500;\n\n/**\n * SDK-RELEASE-RULING.md §5 — the final tally survives the teardown.\n *\n * `shutdown()` clears the global client, so without this the natural pattern\n * `await shutdown(); console.log(getMetrics())` reported `droppedSpans: 0` from\n * a hardcoded literal, in the exact process that had just discarded spans.\n *\n * Written once per shutdown; cleared by `init()` so a second lifecycle never\n * serves the first's tally. Mirrors `_final_metrics` in `client.py`.\n */\nlet _finalMetrics: ReturnType<BatchSpanProcessor['getMetrics']> | undefined;\n\n/**\n * The processor of the last shutdown, kept with the tally. Root `flush()` after\n * `shutdown()` asks it: the processor holds the loss mark, so a loss that the\n * shutdown counted (`shutdown_residue` included) makes ONE `flush()` false, as\n * every other loss does. Cleared by `init()`.\n */\nlet _finalProcessor: BatchSpanProcessor | undefined;\n/** Whether the client of that last shutdown was active (see `RisicareClient._activated`). */\nlet _finalActive = false;\n\n/**\n * score() requests: the timeout, the ones not yet settled, and the number that\n * failed since `init()`. Root `flush()` waits for the pending ones inside its\n * deadline. Through 0.7.1 a score request had no timeout, followed redirects,\n * never read the status, and a failure was a debug line only.\n */\nconst SCORE_TIMEOUT_MS = 2000;\nconst _pendingScores = new Set<Promise<void>>();\nlet _failedScores = 0;\n// The failed-score count that the last finished flush() saw. A flush() answers\n// false when the count is above this mark, and then raises the mark: each\n// failed score makes one flush false, also when it failed with no flush running.\nlet _failedScoresFlushMark = 0;\n\n/**\n * The score slot rule (both SDKs; review of PR #44):\n * - at most SCORE_MAX_IN_FLIGHT score requests are in flight;\n * - a score that finds no free slot waits, with NO timer of its own: the 2000 ms\n * bound of a score starts when its request starts;\n * - at most SCORE_MAX_WAITING scores wait; one more fails at once and is counted;\n * - when a flush or shutdown bound ends, the scores that still wait are counted as\n * failed and never start a request.\n * With one connection for each score, 200 scores at once overflowed the accept\n * queue of a server (128 on macOS). With a timer that also covered the wait, 150 of\n * 200 scores to a sink that answers in 1 s were lost.\n */\nconst SCORE_MAX_IN_FLIGHT = 50;\nconst SCORE_MAX_WAITING = 1000;\nconst SCORE_CAP_REASON = `not sent: ${SCORE_MAX_WAITING} scores wait for a free slot`;\nconst SCORE_DEADLINE_REASON = 'not sent before the deadline';\nlet _scoresInFlight = 0;\ninterface ScoreWaiter {\n start: () => void;\n fail: (reason: string) => void;\n}\nconst _scoreWaiters: ScoreWaiter[] = [];\n\n/** Start waiting scores while a slot is free. */\nfunction _startWaitingScores(): void {\n while (_scoresInFlight < SCORE_MAX_IN_FLIGHT && _scoreWaiters.length > 0) {\n _scoreWaiters.shift()!.start();\n }\n}\n\n/** Count every waiting score as failed. None of them starts a request after this. */\nfunction _failWaitingScores(reason: string): void {\n for (const waiter of _scoreWaiters.splice(0)) waiter.fail(reason);\n}\n\n// One WARNING for a failed score, then at most one for each window. The\n// failures in the window are counted, and the next WARNING gives their number.\nlet _scoreWarnWindowMs = 10_000;\nconst SCORE_NAME_MAX = 200;\nlet _scoreWarnedAt: number | undefined;\nlet _scoreHeld = 0;\nlet _scoreHeldReason = '';\n\n/** @internal Tests only: change the WARNING window. */\nexport function _setScoreWarnWindowMsForTesting(ms: number): void {\n _scoreWarnWindowMs = ms;\n}\n\nfunction _resetScoreFailures(): void {\n _failedScores = 0;\n _failedScoresFlushMark = 0;\n _scoreWarnedAt = undefined;\n _scoreHeld = 0;\n _scoreHeldReason = '';\n}\n\nfunction _heldText(): string {\n return ` ${_scoreHeld} more scores failed after the last warning. The last reason: ${_scoreHeldReason}.`;\n}\n\n/**\n * Count one failed score request, and write a WARNING when the window lets it.\n * The first failure writes at once. A failure less than 10 s after the last\n * WARNING is counted and held; the next WARNING gives the number of held\n * failures and the last reason. The WARNING gives the score name (at most 200\n * characters) and the status or the error code only.\n */\nfunction _scoreFailed(name: string, reason: string): void {\n _failedScores += 1;\n const now = Date.now();\n if (_scoreWarnedAt !== undefined && now - _scoreWarnedAt < _scoreWarnWindowMs) {\n _scoreHeld += 1;\n _scoreHeldReason = reason;\n return;\n }\n let message = `score ${JSON.stringify(name.slice(0, SCORE_NAME_MAX))} failed: ${reason}.`;\n if (_scoreHeld > 0) message += _heldText();\n _scoreWarnedAt = now;\n _scoreHeld = 0;\n _scoreHeldReason = '';\n warn(message);\n}\n\n/** Write the held failures now, if there are any. Root `flush()` calls this. */\nfunction _warnHeldScores(): void {\n if (_scoreHeld === 0) return;\n const message = _heldText().trimStart();\n _scoreWarnedAt = Date.now();\n _scoreHeld = 0;\n _scoreHeldReason = '';\n warn(message);\n}\n\n/** Resolve `true` when no score request is pending, `false` at the timeout. */\nasync function _waitForPendingScores(timeoutMs: number): Promise<boolean> {\n if (_pendingScores.size === 0) return true;\n let timer: ReturnType<typeof setTimeout> | undefined;\n const expired = new Promise<boolean>((resolve) => {\n timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));\n });\n const settled = (async () => {\n while (_pendingScores.size > 0) await Promise.all([..._pendingScores]);\n return true;\n })();\n try {\n return await Promise.race([settled, expired]);\n } finally {\n clearTimeout(timer);\n }\n}\n\n// ─── Client Class ───────────────────────────────────────────────────────────\n\nclass RisicareClient {\n readonly config: ReturnType<typeof resolveConfig>;\n readonly processor: BatchSpanProcessor;\n readonly tracer: Tracer;\n /** RULING §5. The signal path does NOT clear the global client, so without\n * this flag `getMetrics()` would keep reporting `\"running\"` over a processor\n * that has already been torn down. */\n isShutdown = false;\n /**\n * Tracing was on at `init()` or since `enable()`. A client that never was\n * (no key, or tracing off) accepted nothing, and delivered nothing: its\n * `flush()` is false. `disable()` does not clear it: spans that were accepted\n * before keep their answer.\n */\n private _activated = false;\n private _shutdownPromise: Promise<void> | undefined;\n private _shutdownHandlers: { signal: string; handler: () => void }[] = [];\n\n constructor(config?: Partial<RisicareConfig>) {\n this.config = resolveConfig(config);\n\n // API key format validation. `rsk-` is the legacy format (kept working\n // forever); `rski_` (Ingest) and `rsks_` (Secret) are the new checksummed\n // format — design: closure-plan-2026-09-25/org-project-ux/\n // 12-A2-A5-key-model-design.md §3. This is a hint only, never enforced.\n //\n // S14: `warn`, not `debug`. `setDebug()` runs at the end of this\n // constructor, so a `debug()` call here never printed for a customer. The\n // message never contains any part of the key.\n const hasKnownPrefix =\n this.config.apiKey?.startsWith('rsk-') ||\n this.config.apiKey?.startsWith('rski_') ||\n this.config.apiKey?.startsWith('rsks_');\n if (this.config.apiKey && !hasKnownPrefix) {\n warn(\n 'the API key does not look like a Risicare key: it should start with \"rsk-\", \"rski_\" or \"rsks_\". ' +\n 'Tracing continues with this key.',\n );\n }\n // NO KEY: tracing is off (`resolveConfig` forces `enabled` false), the SDK\n // sends nothing to Risicare, and `flush()` returns false. Say so once, in\n // plain words. A caller who turned tracing off on purpose (`enabled: false`,\n // `RISICARE_TRACING=false`) gets no WARNING.\n if (!this.config.apiKey && !tracingTurnedOff(config)) {\n warn(\n 'Risicare found no API key. Nothing is sent to Risicare: tracing is off, no span is ' +\n 'created, and flush() returns false. Set the RISICARE_API_KEY environment variable, ' +\n 'or pass apiKey to init().',\n );\n }\n\n // Build exporter chain.\n //\n // Only a key gives an exporter. With no key none exists, and none can: the SDK\n // writes nothing to the console either. F-SDKJSCONSOLE-001 (2026-08-15): the\n // old fallback printed `JSON.stringify(span.toPayload())`, the whole payload\n // with no redaction, to the customer's stderr. Through 0.8.0 `debug: true`\n // still printed spans with no key, and the processor counted them as exported\n // (a console exporter that is the only one decides the batch). Now no key\n // means `enabled` false: no span is created, so nothing is printed, queued,\n // dropped or counted as exported. Python prints with `debug` and no key\n // (display only, never counted); JavaScript does not print.\n let exporter: SpanExporter | undefined;\n if (this.config.apiKey) {\n exporter = new HttpExporter({\n endpoint: this.config.endpoint,\n apiKey: this.config.apiKey,\n projectId: this.config.projectId || undefined,\n environment: this.config.environment || undefined,\n compress: this.config.compress,\n });\n }\n\n this.processor = new BatchSpanProcessor({\n exporters: exporter ? [exporter] : [],\n batchSize: this.config.batchSize,\n batchTimeoutMs: this.config.batchTimeoutMs,\n maxQueueSize: this.config.maxQueueSize,\n debug: this.config.debug,\n // The processor is the ONE choke point every exporter is behind. Masking\n // anywhere downstream (in the HTTP exporter, say) would leave a hole for\n // any other exporter; masking upstream would put customer code on the\n // span-end call path.\n mask: this.config.mask,\n // Same argument as `mask`: the processor is the ONE choke point every\n // exporter is behind, and the only place BOTH content paths — provider\n // capture and hand-set attributes — can be gated together. The Tracer\n // still carries `traceContent` for the provider patches to read; that is\n // now a convenience, not the enforcement point.\n traceContent: this.config.traceContent,\n });\n\n this.tracer = new Tracer({\n onSpanEnd: (span) => this.processor.onSpanEnd(span),\n sampleRate: this.config.sampleRate,\n enabled: this.config.enabled,\n traceContent: this.config.traceContent,\n // F-SDKJSSVCNAME-001 — these were resolved into `config` and then read by\n // nothing. The Tracer is where Python emits them, so JS emits them there\n // too rather than inventing a second site.\n serviceName: this.config.serviceName,\n serviceVersion: this.config.serviceVersion,\n });\n\n this._activated = this.tracer.enabled;\n\n // Start the batch processor (enables span queuing and periodic flushing)\n this.processor.start();\n\n // Start FixRuntime for runtime fix application, ONLY ON OPT-IN (0.7.0;\n // see `RisicareConfig.fixRuntime`). Through 0.6.0 it started whenever an\n // apiKey was set, so the server could change the customer's agent by\n // default. When it starts, it loads active fixes from /v1/fixes/active,\n // caches with TTL and background-refreshes every 60s. The OpenAI chat patch\n // calls interceptCall() before the LLM call. It runs the input guards; with\n // no errorCode it applies no prompt, parameter or fallback fix. When it is\n // off, no runtime exists, so interceptCall() finds nothing to apply.\n //\n // CON-194: previously the catch was an empty-body silent swallow,\n // which meant a customer whose FixRuntime failed to initialize\n // (network unreachable, bad API key, server 5xx, etc.) saw ZERO\n // signal and assumed auto-fix was running. Now the catch logs\n // console.warn with an actionable message — visible at default\n // console output, including the api endpoint (fix reads go there, not to\n // the span endpoint) so customers can verify reachability. Mirrors the\n // Python SDK fix at client.py:520-528.\n //\n // ⚠ A failed LOAD of the fixes (network, 401, 5xx) does not reach this\n // catch: `initFixRuntime()` catches every fault. `FixLoader.start()` logs\n // its own WARNING for a failed first load. No known path makes\n // `initFixRuntime()` throw; the tests reach this catch through a mock.\n if (this.config.apiKey && this.config.enabled && this.config.fixRuntime) {\n try {\n initFixRuntime({\n apiEndpoint: this.config.apiEndpoint,\n apiKey: this.config.apiKey,\n enabled: true,\n debug: this.config.debug,\n });\n } catch (e) {\n // FixRuntime failure is non-fatal — tracing still works.\n // Surface a one-time console.warn so the customer knows.\n const errName = e instanceof Error ? e.name : 'Error';\n const errMsg = scrubText(e instanceof Error ? e.message : String(e), [this.config.apiKey]);\n try {\n console.warn(\n `[risicare] FixRuntime initialization failed — auto-fix is OFFLINE for this process. ` +\n `apiEndpoint=${safeUrl(this.config.apiEndpoint)} error=${errName}: ${errMsg}. ` +\n `Tracing + reporting still work; only fix application is disabled. ` +\n `Pass debug:true in init() options for the full traceback.`\n );\n } catch {\n // Defensive: if console.warn itself throws (closed stderr in\n // some sandboxed/edge environments), prefer silent over crash.\n }\n if (this.config.debug) {\n debug(\n `FixRuntime init traceback: ${scrubText(e instanceof Error && e.stack ? e.stack : String(e), [this.config.apiKey], 2000)}`,\n );\n }\n }\n }\n\n // Register shutdown hooks\n this._registerShutdownHooks();\n\n // Enable internal debug logging if configured\n setDebug(this.config.debug);\n debug(`Initialized: enabled=${this.config.enabled}, endpoint=${safeUrl(this.config.endpoint)}`);\n if (!this.config.fixRuntime) {\n debug(\n 'FixRuntime is off: nothing polls /fixes/active and no fix is applied. ' +\n 'Opt in with fixRuntime: true or RISICARE_FIX_RUNTIME=true.',\n );\n }\n }\n\n get enabled(): boolean {\n return this.tracer.enabled;\n }\n\n set enabled(value: boolean) {\n // `enable()` with no key does not turn tracing on: nothing can be sent.\n if (value && !this.config.apiKey) {\n debug('enable() ignored: no API key is configured, so tracing stays off');\n return;\n }\n this.tracer.enabled = value;\n if (value) this._activated = true;\n }\n\n // Audit #6: Promise-based shutdown dedup (fixes TOCTOU race condition)\n async shutdown(timeoutMs?: number): Promise<void> {\n if (this._shutdownPromise) return this._shutdownPromise;\n this._shutdownPromise = this._doShutdown(timeoutMs);\n return this._shutdownPromise;\n }\n\n private async _doShutdown(timeoutMs?: number): Promise<void> {\n debug('Shutting down...');\n\n // Audit #3: Remove process listeners to prevent leak\n for (const { signal, handler } of this._shutdownHandlers) {\n process.removeListener(signal, handler);\n }\n this._shutdownHandlers = [];\n\n // A provider span that is still open (for example a stream that nobody\n // read) ends now, so the processor exports it and it is not lost.\n endOpenProviderSpans();\n\n await this.processor.shutdown(timeoutMs);\n // The shutdown bound ended (also on SIGTERM and SIGINT, which reach this method):\n // a score that still waits for a slot is counted as failed and is not sent.\n _failWaitingScores(SCORE_DEADLINE_REASON);\n\n // RULING §5: snapshot HERE, in the one place every teardown path passes\n // through.\n //\n // ⚠ THIS SITE IS THE WHOLE POINT, and the obvious site is wrong. A first\n // implementation snapshotted in the module-level `shutdown()` — which the\n // SIGTERM/SIGINT handlers never call. They call THIS method, so on exactly\n // the path a container redeploy takes, `getMetrics()` would have reported\n // a live-looking reading over a torn-down processor. The Python SDK had the\n // identical trap on its own signal path; one rule, two languages, both\n // instrumented at the shared site rather than the canonical one.\n this.isShutdown = true;\n _finalMetrics = this.processor.getMetrics();\n _finalProcessor = this.processor;\n _finalActive = this._activated;\n }\n\n /**\n * Flush pending spans.\n *\n * @returns `true` only if everything queued at entry was DELIVERED.\n *\n * RULING §6: this used to discard the processor's boolean and return\n * `Promise<void>`, which resolves without throwing and reads to a caller\n * exactly like success. A discarded answer is not meaningfully better than a\n * false one — both leave the customer unable to tell *drained* from\n * *discarded*.\n */\n async flush(timeoutMs?: number): Promise<boolean> {\n // Not active means not true: no key, or tracing was off from the start.\n if (!this._activated) return false;\n return this.processor.flush(timeoutMs);\n }\n\n /**\n * SDK-RELEASE-RULING.md §3 — who decides whether the process dies.\n *\n * The contract, and it is the same one the Python SDK now satisfies:\n *\n * the SDK's signal handler never CHANGES whether the signal\n * terminates the process.\n *\n * Registering ANY listener for SIGTERM/SIGINT displaces Node's default\n * terminate. Before this, the SDK registered one unconditionally, and on the\n * success path `clearTimeout` removed the 5 s `process.exit(1)` backstop —\n * so a JS app with a live event loop drained, cleared its own only exit, and\n * **ran forever**. The orchestrator waited out the whole grace period and\n * SIGKILLed, which exits **137** and reads as OOM-killed in every dashboard.\n * Measured >25 s alive on both 0.5.0 and a clean-rebuilt 0.4.2, so this is\n * PRE-EXISTING (`F-SDKJSEXIT-001`), not a regression of the data-loss fix.\n *\n * The rule splits on one question — did the signal already have an owner?\n *\n * * **No prior listener.** Node's default was termination and OUR\n * registration displaced it. We owe the process that death.\n * * **A prior listener exists.** The application took ownership before the\n * SDK loaded. We drain and RETURN; termination was never ours to decide,\n * and forcing it would cut off the app's own graceful shutdown.\n * * **A listener that the application adds after `init()`.** Node calls ours\n * first. The question is asked when OUR listener starts, at signal time:\n * is there another listener for this signal? If there is, it owns\n * termination as well: when the drain ends we do not raise the signal\n * again, and we do not arm the fail-safe exit. Its listener runs once and\n * decides the exit, in the same way as when it was registered before\n * `init()`. Through 0.8.0 the re-raise ran it a second time, and the\n * fail-safe ended the process with code 143, 100 ms later.\n * * **A listener that the application adds DURING the drain.** There was none\n * at signal time, so the 0.8.0 rule holds: after the drain we raise the\n * signal again, and that listener runs on it, and the process ends (fail-safe\n * after 100 ms if it does not). A count taken after the drain would have\n * counted that listener, and nothing would have run or ended the process.\n *\n * ⚠ `beforeExit` is deliberately NOT in that logic. It is not a signal and\n * carries no termination the SDK could displace — the loop has already\n * drained and the process is leaving on its own.\n */\n private _registerShutdownHooks(): void {\n // `beforeExit` first: no ownership question, no backstop, no exit.\n const onBeforeExit = () => {\n this.shutdown().catch(() => {});\n };\n process.once('beforeExit', onBeforeExit);\n this._shutdownHandlers.push({ signal: 'beforeExit', handler: onBeforeExit });\n\n for (const [signal, signum] of TERMINATING_SIGNALS) {\n // Captured ONCE, at registration — asking later would count our own.\n const weDisplacedDefault = process.listenerCount(signal) === 0;\n\n const handler = (): void => {\n // The other listeners for this signal, counted NOW, at signal time. A\n // listener that the application adds during the drain is not one of them.\n const othersAtSignal = process.listeners(signal as NodeJS.Signals).filter((l) => l !== handler).length;\n\n // Backstop: DERIVED from the shutdown budget, never a second literal.\n // The two used to be an independent `5000` each, so a drain allowed\n // 5,000 ms raced a `process.exit(1)` firing at 5,000 ms — killing the\n // drain at its deadline, with the wrong exit code, before the residue\n // WARNING (the previous ruling's primary remedy) could print.\n const backstop = setTimeout(\n () => process.exit(128 + signum),\n SHUTDOWN_BUDGET_MS + BACKSTOP_MARGIN_MS,\n );\n backstop.unref();\n\n this.shutdown()\n .catch(() => {})\n .finally(() => {\n clearTimeout(backstop);\n if (!weDisplacedDefault) return; // the app owns termination\n // The application had a listener when the signal came (it added it\n // after init()): it owns termination too, so that the order of\n // registration does not change how often its listener runs, or who\n // decides the exit. (It does change which spans that listener ends are\n // delivered: see `BatchSpanProcessor.onSpanEnd`.) The\n // signal is not raised again (its listener would run a second time)\n // and the fail-safe exit is not armed (it ended the listener with code\n // 143, 100 ms later). With no listener at signal time, the 0.8.0 rule\n // below holds.\n if (othersAtSignal > 0) return;\n\n // Our listener is gone (`process.once` + `_doShutdown` removed\n // them), so re-raising reaches Node's default and terminates for\n // real — WIFSIGNALED, not merely an exit code that looks like one.\n try {\n process.kill(process.pid, signal as NodeJS.Signals);\n } catch {\n process.exit(128 + signum);\n }\n // Belt and braces: if the application added a listener DURING our\n // drain, the re-raise above went to it instead of terminating and\n // we would hang exactly as before. unref()'d, so it cannot itself\n // hold open a process that is already leaving.\n const failsafe = setTimeout(() => process.exit(128 + signum), 100);\n failsafe.unref();\n });\n };\n\n process.once(signal, handler);\n this._shutdownHandlers.push({ signal, handler });\n }\n }\n}\n\n// ─── Public API ─────────────────────────────────────────────────────────────\n\n/**\n * Initialize the Risicare SDK. Call once at application startup.\n *\n * @example\n * import { init } from 'risicare';\n * init({ apiKey: 'rsk-...', serviceName: 'my-agent', environment: 'production' });\n */\nexport function init(config?: Partial<RisicareConfig>): void {\n const existing = getGlobalClient() as RisicareClient | undefined;\n if (existing) {\n // F-359: warn loudly when re-init would silently discard a config change.\n // The first init wins; a second init with a different apiKey/endpoint/\n // environment is almost certainly a bug (e.g., a side-effect import that\n // calls init() in a library, then the app's own init() with real config\n // gets ignored).\n if (config) {\n const incoming = resolveConfig(config);\n const diffs: string[] = [];\n const checkedKeys: Array<keyof typeof incoming> = [\n 'apiKey',\n 'endpoint',\n 'environment',\n 'serviceName',\n 'serviceVersion',\n 'sampleRate',\n ];\n for (const k of checkedKeys) {\n if (incoming[k] !== existing.config[k]) {\n // Don't print apiKey contents — just say \"differs\".\n const newRender = k === 'apiKey' ? '<redacted>' : JSON.stringify(incoming[k]);\n const oldRender = k === 'apiKey' ? '<redacted>' : JSON.stringify(existing.config[k]);\n diffs.push(`${String(k)}: ${oldRender} → ${newRender}`);\n }\n }\n if (diffs.length > 0) {\n console.warn(\n '[risicare] init() called twice with different config; the FIRST call wins. ' +\n 'Call shutdown() before re-initializing. Differences ignored: ' +\n diffs.join(', '),\n );\n } else {\n debug('init() called twice with identical config; no-op');\n }\n } else {\n debug('init() called twice; no-op');\n }\n return;\n }\n\n // RULING §5: a NEW lifecycle starts with no retained tally — otherwise\n // `init(); shutdown(); init()` would serve the FIRST run's losses as if they\n // belonged to the second.\n _finalMetrics = undefined;\n _finalProcessor = undefined;\n _finalActive = false;\n _resetScoreFailures();\n\n const client = new RisicareClient(config);\n setGlobalClient(client);\n setGlobalTracer(client.tracer);\n}\n\n/**\n * Gracefully shut down the SDK. Flushes pending spans before resolving.\n *\n * @param timeoutMs - The shutdown budget in milliseconds (default 5000). It is a\n * hard wall-clock bound. A value that is not a finite number (NaN, Infinity, a\n * string, null) gives 5000. A negative value gives 0. The largest value is\n * 2**31 - 1.\n *\n * At the deadline, `shutdown()` stops the export in flight. Spans still queued\n * and spans in the stopped export are counted as `shutdown_residue`, with one\n * WARNING: they were not confirmed as delivered. The server may have received\n * the spans of the stopped export. Each exporter's own `shutdown()` gets only\n * the time that is left of the budget.\n *\n * Limit: the stop does not end a TLS handshake that stalls. Such a handshake\n * can keep the process alive about 10 s after `shutdown()` returns.\n */\nexport async function shutdown(timeoutMs?: number): Promise<void> {\n // Stop FixRuntime first (stops background refresh)\n try {\n shutdownFixRuntime();\n } catch {\n // FixRuntime may not be initialized\n }\n\n const client = getGlobalClient() as RisicareClient | undefined;\n if (!client) return;\n // RULING §5: the final tally is snapshotted inside `_doShutdown()`, which\n // this reaches and which the signal handlers reach directly. Do NOT add a\n // second snapshot here.\n await client.shutdown(timeoutMs);\n setGlobalClient(undefined);\n setGlobalTracer(undefined);\n}\n\n/**\n * Flush all pending spans without shutting down.\n *\n * @param timeoutMs - The budget in milliseconds (default 5000). It is a hard\n * wall-clock bound on the wait: at the deadline `flush()` resolves `false`.\n * A value that is not a finite number (NaN, Infinity, a string, null) gives\n * 5000. A negative value gives 0. The largest value is 2**31 - 1.\n * @returns `true` only if everything queued at entry was DELIVERED and no span\n * was lost since the previous `flush()` returned. A loss is reported by the next\n * `flush()`, one time. It returns `false` in these cases:\n * - the deadline expired with spans still queued or in flight;\n * - a span was discarded since the previous flush returned (F-SDKCB-001 §6);\n * - the backend rejected a span since the previous flush returned, or its ack\n * did not account for a span;\n * - a `shutdown()` left spans undelivered (`shutdown_residue`) since the previous\n * flush returned. That loss is reported once, as every other loss.\n * A `flush()` that comes while a `shutdown()` runs (the SDK's own drain at\n * SIGTERM / SIGINT, or one that nobody awaited) waits for it inside its own\n * deadline, and then answers from the final tally with the same rule. So does a\n * `flush()` after `shutdown()`. Through 0.8.0 both answered from the empty queue.\n * Not active means not true: `flush()` returns `false` before `init()`, with tracing\n * off (`enabled: false`, `RISICARE_TRACING=false`), and with no API key. Through\n * 0.8.0 it returned `true` in those cases: nothing was queued.\n *\n * `flush()` never stops a request that is already sent. At the deadline it stops\n * waiting; the export in flight continues and ends by its own rules.\n *\n * Limit: that export can keep the process alive after `flush()` returns `false`,\n * until its own timeouts end (measured on a silent server: 22 s). To end a\n * process within a bound, call `await shutdown(timeoutMs)`. It stops the export\n * in flight.\n *\n * Scores: `flush()` also waits, inside the same deadline, for each `score()`\n * request that is not complete. It returns `false` when a score is not complete\n * at the deadline, or when a score failed since the previous `flush()` returned.\n * Each failed score makes one flush `false`, as each lost span does.\n *\n * ⚠ Signature change in 0.5.0 — was `Promise<void>`. Existing callers that\n * ignore the result keep working unchanged.\n */\nexport async function flush(timeoutMs?: number): Promise<boolean> {\n // The same rule as the processor: a value that is not a finite number gives\n // the default, so the score wait and the span wait share one deadline.\n const budgetMs = normalizeTimeoutMs(timeoutMs);\n const deadline = Date.now() + budgetMs;\n // Read at entry: two flushes that overlap both report a score that failed\n // before either of them ended.\n const scoreMark = _failedScoresFlushMark;\n const client = getGlobalClient() as RisicareClient | undefined;\n let spansOk: boolean;\n if (client) {\n spansOk = await client.flush(timeoutMs);\n } else if (_finalProcessor) {\n // `shutdown()` clears the global client. The processor of that shutdown\n // answers from its final tally, with its loss mark: a loss that the shutdown\n // counted (the residue too) makes one flush false. Through 0.8.0 only the\n // residue counted, so a rejection or a `transport_refused` drop gave true.\n // `init()` clears it. A client that was never active answers false.\n spansOk = _finalActive && (await _finalProcessor.flush(timeoutMs));\n } else {\n // Never initialised: not active means not true.\n spansOk = false;\n }\n // Pending score requests run in parallel with the span flush. Wait for the\n // remaining scores inside the same deadline.\n const scoresDone = await _waitForPendingScores(deadline - Date.now());\n // The bound ended: the scores that still wait for a slot fail now, with no request.\n if (!scoresDone) _failWaitingScores(SCORE_DEADLINE_REASON);\n _warnHeldScores();\n const failedNow = _failedScores;\n if (failedNow > _failedScoresFlushMark) _failedScoresFlushMark = failedNow;\n return spansOk && scoresDone && failedNow <= scoreMark;\n}\n\n/**\n * Enable tracing at runtime.\n */\nexport function enable(): void {\n const client = getGlobalClient() as RisicareClient | undefined;\n if (client) client.enabled = true;\n}\n\n/**\n * Disable tracing at runtime. Spans will not be created or exported.\n */\nexport function disable(): void {\n const client = getGlobalClient() as RisicareClient | undefined;\n if (client) client.enabled = false;\n}\n\n/**\n * Check whether tracing is currently enabled. False before `init()`, with no API\n * key (also with `RISICARE_TRACING=true`, `enabled: true` or `enable()`), with\n * tracing off, and after `shutdown()` or the SDK's own drain at SIGTERM / SIGINT.\n */\nexport function isEnabled(): boolean {\n const client = getGlobalClient() as RisicareClient | undefined;\n // False after the SDK's own drain at SIGTERM / SIGINT too: the signal path does\n // not clear the global client, but the processor is shut down.\n return client !== undefined && !client.isShutdown && client.enabled;\n}\n\n/**\n * Get the global tracer instance. Returns undefined if not initialized.\n */\nexport function getTracer(): Tracer | undefined {\n return getGlobalTracer() as Tracer | undefined;\n}\n\n/**\n * Get the global tracer, or throw if not initialized.\n * @internal Used by decorators and providers that require an active tracer.\n */\nexport function requireTracer(): Tracer {\n const tracer = getGlobalTracer() as Tracer | undefined;\n if (!tracer) {\n throw new Error(\n 'Risicare SDK not initialized. Call init() before using tracing features.',\n );\n }\n return tracer;\n}\n\n/**\n * Check whether content tracing (prompt/completion capture) is enabled.\n */\nexport function getTraceContent(): boolean {\n const tracer = getGlobalTracer() as Tracer | undefined;\n // Fail-closed, matching the 0.5.1 config default.\n return tracer?.traceContent ?? false;\n}\n\n/**\n * Get SDK metrics: exported spans (accepted by the backend), `rejectedSpans`,\n * dropped spans and their reasons (`unacknowledged` included), failed exports,\n * queue stats, and `failedScores` (`score()` requests that failed since\n * `init()`).\n *\n * `sdkState` — SDK-RELEASE-RULING.md §5 — says WHICH of three different facts\n * the numbers are, because before it all three rendered as the same zeros:\n *\n * - `\"uninitialised\"` nothing was ever queued; the zeros are the truth\n * - `\"running\"` live readings from a live processor\n * - `\"shutdown\"` the RETAINED FINAL TALLY. Not live, and says so.\n *\n * The `\"shutdown\"` case is why this field exists. `shutdown()` clears the global\n * client, so this used to answer `droppedSpans: 0` from a hardcoded literal in\n * the very process that had just discarded spans — a guess presented\n * byte-identical to an authoritative answer, which is the W1/W3 class this\n * codebase already ruled against (`cost_source`, `settled`). The remedy there\n * and here is the same: do not hide the value and do not null it, LABEL it.\n * Every field of a retained tally is still true — the queue really is empty,\n * the capacity really is the configured one, and the drop counts describe the\n * whole life of the process, `shutdown_residue` included.\n *\n * ⚠ What it still CANNOT do: report loss to anything OUTSIDE the dying process.\n * A counter in memory about to be freed has no reader, and a SIGKILL takes this\n * and the WARNING together. The WARNING remains the primary signal.\n */\nexport function getMetrics() {\n const client = getGlobalClient() as RisicareClient | undefined;\n if (client && !client.isShutdown) {\n return {\n ...client.processor.getMetrics(),\n failedScores: _failedScores,\n sdkState: 'running' as const,\n };\n }\n if (_finalMetrics) {\n // Copy: a caller mutating the object must not corrupt the one tally the\n // process has left. The tally is read from the processor of the last shutdown,\n // not from the copy that `_doShutdown` took: a span that ends after the drain\n // is counted (`shutdown_residue`) and the tally must show it.\n const tally = _finalProcessor?.getMetrics() ?? _finalMetrics;\n return {\n ...tally,\n failedScores: _failedScores,\n droppedSpansByReason: { ...tally.droppedSpansByReason },\n sdkState: 'shutdown' as const,\n };\n }\n return {\n exportedSpans: 0,\n rejectedSpans: 0,\n failedScores: _failedScores,\n droppedSpans: 0,\n droppedSpansByReason: {\n queue_full: 0,\n transport_refused: 0,\n shutdown_residue: 0,\n unacknowledged: 0,\n },\n failedExports: 0,\n queueSize: 0,\n queueCapacity: 0,\n queueUtilization: 0,\n sdkState: 'uninitialised' as const,\n };\n}\n\n// ─── reportError ──────────────────────────────────────────────────────────\n\n// Error dedup: SHA256 fingerprint → timestamp. Prevents retry loops from\n// creating N duplicate diagnoses. Matches Python SDK's 5-minute TTL.\nconst _ERROR_DEDUP_TTL_MS = 5 * 60 * 1000; // 5 minutes\nconst _ERROR_DEDUP_MAX = 1000;\nconst _recentErrors = new Map<string, number>(); // fingerprint → Date.now()\n\nfunction _errorFingerprint(err: Error): string {\n const raw = `${err.constructor?.name ?? 'Error'}:${String(err.message ?? '').slice(0, 200)}`;\n return createHash('sha256').update(raw).digest('hex').slice(0, 16);\n}\n\nfunction _isDuplicateError(fingerprint: string): boolean {\n const now = Date.now();\n // Evict expired entries\n for (const [fp, ts] of _recentErrors) {\n if (now - ts > _ERROR_DEDUP_TTL_MS) _recentErrors.delete(fp);\n else break; // Map iterates in insertion order\n }\n if (_recentErrors.has(fingerprint)) return true;\n // Enforce max size\n if (_recentErrors.size >= _ERROR_DEDUP_MAX) {\n const oldest = _recentErrors.keys().next().value;\n if (oldest !== undefined) _recentErrors.delete(oldest);\n }\n _recentErrors.set(fingerprint, now);\n return false;\n}\n\n/**\n * Report a caught exception to the error diagnosis pipeline.\n *\n * Creates an error span that triggers diagnosis and fix generation.\n * Deduplicates identical errors within a 5-minute window (SHA256 fingerprint).\n * This function never throws and is non-blocking.\n *\n * @param error - The caught exception (Error object or string)\n * @param options - Optional attributes and context overrides\n */\nexport function reportError(\n error: unknown,\n options?: { name?: string; attributes?: Record<string, unknown> },\n): void {\n try {\n const tracer = getTracer();\n if (!tracer) return;\n\n const err = error instanceof Error ? error : new Error(String(error ?? 'unknown'));\n const spanName = options?.name ?? `error:${err.constructor.name}`;\n\n // Dedup: suppress identical errors within TTL (matches Python SDK)\n const fp = _errorFingerprint(err);\n if (_isDuplicateError(fp)) {\n debug(`reportError: duplicate suppressed (fp=${fp.slice(0, 8)})`);\n return;\n }\n\n tracer.startSpan({ name: spanName, kind: SpanKind.INTERNAL }, (span) => {\n span.setStatus(SpanStatus.ERROR, err.message);\n span.setAttribute('error', true);\n span.setAttribute('error.type', err.constructor.name);\n // Limits count code points, so a cut never splits a surrogate pair.\n span.setAttribute('error.message', cutCodePoints(err.message, 2000));\n if (err.stack) span.setAttribute('error.stack', cutCodePoints(err.stack, 4000));\n span.setAttribute('risicare.reported_error', true);\n // F-R-REPORTERRCODE-001. `reportError` is the API our own docs name for\n // feeding the diagnosis pipeline, yet it attached error/type/message and\n // NO taxonomy code, while an uncaught throw through a traced frame did —\n // `tracer.ts::Tracer.startSpan` calls `attachErrorCode` on both of its\n // throw handlers. Measured on the published 0.5.2 against the lab: 4\n // uncaught spans carried TOOL.EXECUTION.CRASHED, the reportError span\n // carried none. Same shape as the Python asymmetry, same remedy — reuse\n // the ONE definition rather than re-classifying here.\n attachErrorCode(span, err);\n if (options?.attributes) {\n for (const [k, v] of Object.entries(options.attributes)) {\n span.setAttribute(k, v);\n }\n }\n });\n } catch {\n // Never crash the host application\n debug('reportError failed');\n }\n}\n\n// ─── score ─────────────────────────────────────────────────────────────────\n\n/**\n * A score that `score()` refuses at the call (a value that is not a number or is\n * outside [0, 1], an empty trace id or name). One WARNING, no request, and the\n * score counts as a failed score: `failedScores` rises by 1, so that the next\n * `flush()` is false, as for a score that the gateway refused. The WARNING of the\n * refusal is the one WARNING; `_scoreFailed` is not used, so it writes no second.\n * An SDK that is not active (never initialised, shut down by `shutdown()` or by the\n * SDK's own drain at SIGTERM / SIGINT, tracing off, no key) counts nothing: it was\n * handed no score to deliver. `isEnabled()` is false in the same cases.\n */\nfunction refuseScore(message: string): void {\n warn(message);\n const client = getGlobalClient() as RisicareClient | undefined;\n if (client && !client.isShutdown && client.enabled && client.config.apiKey) _failedScores += 1;\n}\n\n/**\n * Record a custom evaluation score on a trace.\n *\n * Sends the score in the background. The root `flush()` waits for it.\n * This function never throws and does not block. At most 50 score requests\n * are in flight at once. Up to 1,000 scores wait for a free slot, with no timer;\n * the 2000 ms bound of a score starts when its request starts. A score that\n * comes when 1,000 already wait fails at once and is counted. When a `flush()`\n * or `shutdown()` bound ends, the scores that still wait fail and are not sent.\n *\n * Delivery: the request stops after 2000 ms and never follows a redirect. A\n * status of 300 or more, an error or the timeout is a failure, and it adds 1\n * to `failedScores` in `getMetrics()`. The first failure writes a WARNING with\n * the score name and the status or the error code. Later failures in the next\n * 10 s are counted, and the next WARNING gives their number. Root `flush()`\n * waits for pending scores inside its deadline, and returns `false` when a\n * score failed since the previous `flush()` returned. An out-of-range value, a\n * value that is not a number, or an empty `traceId` or `name` writes one WARNING,\n * and the SDK does not send the score. It counts as a failed score, so the next\n * `flush()` is false (not when the SDK is not active: then nothing is counted).\n * `true` and `false` count as 1 and 0.\n *\n * If a `mask` is configured on `init()`, `options.comment` is passed to it under\n * the key `score.comment` before the request is built. `traceId`, `spanId` and\n * `name` are NOT masked — they are identifiers the platform joins and groups on.\n *\n * @param traceId - The trace to score\n * @param name - Score name (e.g., \"accuracy\", \"user_satisfaction\")\n * @param value - Score value between 0.0 and 1.0 inclusive\n * @param options - Optional span_id and comment\n */\nexport function score(\n traceId: string,\n name: string,\n value: number,\n options?: { spanId?: string; comment?: string },\n): void {\n try {\n // WARNING, as in the Python SDK. Through 0.7.1 these were debug lines, so\n // a rejected score was invisible without `debug: true`. The WARNING prints\n // the value only when it is a number: a string could forge a log line, and\n // an object's `toString()` could run. A boolean is a number here (true is\n // 1, false is 0), as in the Python SDK.\n const raw: unknown = value;\n if (typeof raw === 'boolean') value = raw ? 1 : 0;\n if (typeof value !== 'number') {\n refuseScore(`score: the value must be a number, not ${typeof raw}. The SDK does not send this score.`);\n return;\n }\n if (!Number.isFinite(value) || value < 0.0 || value > 1.0) {\n refuseScore(`score: the value must be in [0.0, 1.0], not ${value}. The SDK does not send this score.`);\n return;\n }\n if (typeof traceId !== 'string' || given(traceId) === undefined) {\n refuseScore('score: traceId must be a non-empty string. The SDK does not send this score.');\n return;\n }\n if (typeof name !== 'string' || given(name) === undefined) {\n refuseScore('score: name must be a non-empty string. The SDK does not send this score.');\n return;\n }\n\n const client = getGlobalClient() as RisicareClient | undefined;\n if (!client?.enabled || !client.config.apiKey) return;\n\n // ⚠ FIELD CHANGED 0.6.0 -> 0.7.0: this read `config.endpoint`, the SPAN\n // endpoint, and then composed an API path. That worked only while one\n // Caddy-fronted host served both services. It now reads `apiEndpoint`.\n // The order that sets it is in `config.ts`, `resolveEndpoints`. The\n // default ingest host never names an api host.\n // The `/api` prefix is gone with the proxy that stripped it.\n const endpoint = client.config.apiEndpoint.replace(/\\/+$/, '');\n const url = `${endpoint}/v1/scores`;\n\n // ⚠ THE ONE NON-SPAN EGRESS THE MASK COVERS (F-SDKMASKSCORE-001).\n // This POST does not go through BatchSpanProcessor, so `applyMask` never\n // sees it — `comment` is free customer text on our wire and was uncovered\n // until this call. The ruling (why the same hook rather than a second one,\n // why `name` is deliberately NOT masked, and the caller-thread cost) is in\n // `risicare/masking.py`, \"THE NON-SPAN SURFACE\".\n //\n // Runs BEFORE `JSON.stringify`, so the unmasked value is never serialized.\n // `maskText` is the same primitive `statusMessage` uses, so a throwing mask\n // yields the same marker and the score is still sent.\n let comment = options?.comment;\n if (comment !== undefined && client.config.mask) {\n comment = maskText(client.config.mask, SCORE_COMMENT_KEY, comment);\n }\n\n const body = JSON.stringify({\n trace_id: traceId,\n name,\n score: value,\n source: 'sdk',\n ...(options?.spanId && { span_id: options.spanId }),\n ...(comment && { comment }),\n });\n\n // The caller does not wait. The score is pending until its request settles,\n // or until it fails while it waits for a slot; root `flush()` waits for it.\n if (_scoresInFlight >= SCORE_MAX_IN_FLIGHT && _scoreWaiters.length >= SCORE_MAX_WAITING) {\n _scoreFailed(name, SCORE_CAP_REASON);\n return;\n }\n let settle!: () => void;\n const request = new Promise<void>((resolve) => (settle = resolve));\n const send = async (): Promise<void> => {\n // The 2000 ms bound starts here, when the request starts.\n const controller = new AbortController();\n const timer = setTimeout(() => controller.abort(), SCORE_TIMEOUT_MS);\n try {\n const response = await fetch(url, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'Authorization': `Bearer ${client.config.apiKey}`,\n // F-SDKVER-001 — see the Python twin. `score()` reaches the FastAPI\n // server under /v1/, which `main.py::audit_logging_middleware` audits\n // into `audit_logs.user_agent`; ingest reaches the Rust gateway, which\n // discards it. This is the one client-identity visible with no gateway\n // change.\n 'User-Agent': `risicare-js/${SDK_VERSION} node/${process.version}`,\n 'X-Risicare-SDK-Version': SDK_VERSION,\n },\n body,\n // Never follow: a redirect is a misroute, not a route. Through 0.7.1\n // fetch followed a 307 and re-POSTed the score to the login page.\n redirect: 'manual',\n signal: controller.signal,\n });\n if (response.type === 'opaqueredirect' || response.status >= 300) {\n _scoreFailed(name, `HTTP ${response.status || '3xx'}`);\n }\n try {\n await response.body?.cancel();\n } catch {\n // The body is not needed.\n }\n } catch (err) {\n // The cause code tells a refused port, a DNS failure and a reset apart\n // (fetch wraps each of them in the same TypeError).\n const cause = err instanceof Error ? (err as Error & { cause?: { code?: unknown } }).cause : undefined;\n const code = typeof cause?.code === 'string' ? cause.code : undefined;\n const reason = controller.signal.aborted\n ? `no answer within ${SCORE_TIMEOUT_MS} ms`\n : code ?? (err instanceof Error ? err.name : 'Error');\n _scoreFailed(name, reason);\n } finally {\n clearTimeout(timer);\n _scoresInFlight--;\n settle();\n _startWaitingScores();\n }\n };\n const start = (): void => {\n _scoresInFlight++;\n void send();\n };\n if (_scoresInFlight < SCORE_MAX_IN_FLIGHT) {\n start();\n } else {\n _scoreWaiters.push({\n start,\n fail: (reason) => {\n _scoreFailed(name, reason);\n settle();\n },\n });\n }\n _pendingScores.add(request);\n void request.finally(() => _pendingScores.delete(request));\n } catch {\n // Never crash the host application\n debug('score failed');\n }\n}\n","/**\n * Shared state via globalThis — ensures all entry point bundles share\n * the same singleton instances.\n *\n * Problem: tsup with `splitting: false` gives each entry point (index,\n * openai, anthropic, vercel-ai) its own copy of module-level variables.\n * This means `init()` from 'risicare' sets a tracer that 'risicare/openai'\n * can't see — breaking all provider instrumentation silently.\n *\n * Solution: Store all mutable singletons on globalThis with a namespaced\n * prefix. Every bundle reads/writes the same global slots.\n *\n * This pattern is used by React, OpenTelemetry, and other SDKs that must\n * share state across independently bundled entry points.\n *\n * @internal\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst G = globalThis as any;\nconst PREFIX = '__risicare_';\n\n// ─── Client & Tracer ────────────────────────────────────────────────────────\n\nexport function getClient(): unknown {\n return G[PREFIX + 'client'];\n}\n\nexport function setClient(client: unknown): void {\n G[PREFIX + 'client'] = client;\n}\n\nexport function getTracer(): unknown {\n return G[PREFIX + 'tracer'];\n}\n\nexport function setTracer(tracer: unknown): void {\n G[PREFIX + 'tracer'] = tracer;\n}\n\n// ─── Context Storage ────────────────────────────────────────────────────────\n\nexport function getContextStorage(): AsyncLocalStorage<unknown> {\n if (!G[PREFIX + 'ctx']) {\n G[PREFIX + 'ctx'] = new AsyncLocalStorage();\n }\n return G[PREFIX + 'ctx'];\n}\n\n// ─── Span Registry ──────────────────────────────────────────────────────────\n\nexport function getRegistry(): Map<string, unknown> {\n if (!G[PREFIX + 'registry']) {\n G[PREFIX + 'registry'] = new Map();\n }\n return G[PREFIX + 'registry'];\n}\n\nexport function getOpCount(): number {\n return G[PREFIX + 'opcount'] ?? 0;\n}\n\nexport function setOpCount(n: number): void {\n G[PREFIX + 'opcount'] = n;\n}\n\n// ─── Debug Flag ─────────────────────────────────────────────────────────────\n\nexport function getDebug(): boolean {\n return G[PREFIX + 'debug'] ?? false;\n}\n\nexport function setDebugFlag(enabled: boolean): void {\n G[PREFIX + 'debug'] = enabled;\n}\n\n// ─── Fix Runtime ────────────────────────────────────────────────────────\n\nexport function getGlobalFixRuntime(): unknown {\n return G[PREFIX + 'fix_runtime'];\n}\n\nexport function setGlobalFixRuntime(runtime: unknown): void {\n G[PREFIX + 'fix_runtime'] = runtime;\n}\n\n// ─── Open provider spans (utils/stream-proxy.ts) ────────────────────────────\n\n/** An observed provider span that is not ended yet. */\nexport interface OpenProviderSpan {\n end(reason: 'shutdown'): void;\n release(): void;\n}\n\nexport interface ProviderSpanState {\n /** The shape of this object. Change it when the shape or a method of OpenProviderSpan changes. */\n version: 1;\n /** Every observed provider span that is still open: `shutdown()` ends them. */\n open: Set<OpenProviderSpan>;\n /** Ends a span when nobody can reach its promise, stream or iterators. */\n registry: FinalizationRegistry<OpenProviderSpan> | undefined;\n}\n\nconst PROVIDER_SPANS = Symbol.for('risicare.providerSpans');\n\n/** True when `s` is a version-1 state that this copy of the SDK can use. */\nfunction usableProviderSpanState(s: unknown): s is ProviderSpanState {\n if (!s || typeof s !== 'object') return false;\n const { version, open, registry } = s as Record<string, unknown>;\n const o = open as Record<PropertyKey, unknown> | undefined;\n return (\n version === 1 &&\n !!o &&\n typeof o.add === 'function' &&\n typeof o.delete === 'function' &&\n typeof o[Symbol.iterator] === 'function' &&\n (registry === undefined || typeof (registry as { register?: unknown }).register === 'function')\n );\n}\n\n/**\n * ONE set and ONE registry for every bundle. Each provider entry point bundles\n * its own copy of stream-proxy.ts (`splitting: false`), and `shutdown()` in the\n * main bundle must see the spans that `risicare/openai` opened.\n *\n * Two installed copies of the SDK share this state too. A copy uses it only\n * when it is version 1 and its shape checks pass; else this function throws,\n * and the caller of this function (stream-proxy.ts) does not observe the call.\n * It never replaces a state that another copy made.\n */\nexport function getProviderSpanState(): ProviderSpanState {\n const found: unknown = G[PROVIDER_SPANS];\n if (found === undefined) {\n const s: ProviderSpanState = {\n version: 1,\n open: new Set(),\n registry:\n typeof FinalizationRegistry === 'function'\n ? new FinalizationRegistry<OpenProviderSpan>((o) => o.release())\n : undefined,\n };\n G[PROVIDER_SPANS] = s;\n return s;\n }\n if (!usableProviderSpanState(found)) {\n throw new TypeError('the shared provider span state is not version 1');\n }\n return found;\n}\n","/**\n * Internal logger for the Risicare SDK.\n *\n * Centralizes all diagnostic output so that:\n * - Debug messages are gated by a single flag (zero-cost when disabled)\n * - Warnings always fire (operational alerts like queue full)\n * - All output goes to stderr with a consistent [risicare] prefix\n * - A future custom logger callback can be added in one place\n */\n\nimport { getDebug, setDebugFlag } from '../globals.js';\n\n/**\n * Enable or disable debug logging. Called once during init().\n * @internal\n */\nexport function setDebug(enabled: boolean): void {\n setDebugFlag(enabled);\n}\n\n/**\n * Log a debug message. Only outputs when debug mode is enabled.\n * @internal\n */\nexport function debug(msg: string): void {\n if (getDebug()) {\n process.stderr.write(`[risicare] ${msg}\\n`);\n }\n}\n\n/**\n * Log a warning. Always outputs regardless of debug mode.\n * Use sparingly — only for operational issues the user should see.\n * @internal\n */\nexport function warn(msg: string): void {\n process.stderr.write(`[risicare] WARNING: ${msg}\\n`);\n}\n","/**\n * Text helpers for strings that go on the wire.\n *\n * @internal Not public API.\n */\n\n/**\n * The first `max` CODE POINTS of `text`, as Python's `text[:max]` gives.\n *\n * Not `text.slice(0, max)`: that counts UTF-16 code units and can keep the\n * first half of a surrogate pair. JSON.stringify writes a lone half as\n * `\\ud83d`, and a strict JSON parser refuses the whole request body, so the\n * whole batch is lost. The walk stops at `max` code points, so a very long\n * text costs no more than the part that is kept.\n */\nexport function cutCodePoints(text: string, max: number): string {\n // A text of at most `max` code units has at most `max` code points.\n if (text.length <= max) return text;\n let units = 0;\n for (let points = 0; points < max && units < text.length; points++) {\n units += (text.codePointAt(units) as number) > 0xffff ? 2 : 1;\n }\n return text.slice(0, units);\n}\n","/**\n * Text that is safe to put in a log line: THE one scrub function of the SDK.\n * Python twin: `risicare/_error_text.py` (`scrub_text`, `safe_url`).\n *\n * Every text that comes from the network (a header, a body, a redirect target) or\n * from an error, and that goes into a log line of the exporters, the fix loader or\n * `score()`, goes through `scrubText`. It:\n * 1. removes each key it is given, and `RISICARE_API_KEY`, in any case of letters\n * (a literal match: a key with regex metacharacters is not read as a pattern);\n * 2. also finds a key that is percent-encoded: when the URL-decoded copy of the\n * text holds a key, the DECODED text is printed, with the key removed;\n * 3. makes the text one line (each control character becomes a space);\n * 4. cuts the text at `limit` code points (default 200).\n *\n * @internal Not public API.\n */\nimport { cutCodePoints } from './text.js';\n\nexport const KEY_MARKER = '[REDACTED-KEY]';\n\nconst CONTROL = new RegExp('[\\\\u0000-\\\\u001f\\\\u007f-\\\\u009f\\\\u2028\\\\u2029]', 'g');\n\nfunction escapeRegExp(text: string): string {\n return text.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/** Decode %XX sequences. A sequence that is not valid UTF-8 is decoded byte by byte. */\nfunction percentDecode(text: string): string {\n try {\n return decodeURIComponent(text);\n } catch {\n return text.replace(/%([0-9A-Fa-f]{2})/g, (_m, hex: string) => String.fromCharCode(parseInt(hex, 16)));\n }\n}\n\nfunction keyPattern(keys: ReadonlyArray<string | undefined | null>): RegExp | null {\n const values = new Set<string>();\n for (const k of [...keys, process.env.RISICARE_API_KEY]) if (k) values.add(k);\n if (values.size === 0) return null;\n // The longest value first, so that a key that contains another key is removed whole.\n const ordered = [...values].sort((a, b) => b.length - a.length);\n return new RegExp(ordered.map(escapeRegExp).join('|'), 'gi');\n}\n\n/** `text` as one line, with every given key removed, at most `limit` code points. */\nexport function scrubText(text: unknown, keys: ReadonlyArray<string | undefined | null>, limit = 200): string {\n let out: string;\n try {\n out = text instanceof Error ? `${text.name}: ${text.message}` : String(text);\n } catch {\n out = typeof text;\n }\n const pattern = keyPattern(keys);\n if (pattern !== null) {\n if (out.includes('%')) {\n const decoded = percentDecode(out);\n pattern.lastIndex = 0;\n if (decoded !== out && pattern.test(decoded)) out = decoded;\n }\n pattern.lastIndex = 0;\n out = out.replace(pattern, KEY_MARKER);\n }\n return cutCodePoints(out.replace(CONTROL, ' '), limit);\n}\n\n/**\n * `url` without userinfo, query and fragment: scheme, host, port and path only. The SDK\n * prints an endpoint in WARNING and debug lines; a secret in its userinfo\n * (`http://user:secret@host`) or its query (`?k=secret`) must not reach the log.\n */\nexport function safeUrl(url: string): string {\n try {\n const u = new URL(url);\n const path = u.pathname === '/' && !/^[a-z][a-z0-9+.-]*:\\/\\/[^/?#]*\\//i.test(url) ? '' : u.pathname;\n return `${u.protocol}//${u.host}${path}`;\n } catch {\n return url.split('?')[0].split('#')[0].replace(/\\/\\/[^/@]*@/, '//');\n }\n}\n\n/** True when `url` holds userinfo (`user:password@host`). `fetch` refuses such a URL. */\nexport function hasCredentials(url: string): boolean {\n try {\n const u = new URL(url);\n return u.username !== '' || u.password !== '';\n } catch {\n return false;\n }\n}\n","/**\n * Batch span processor.\n *\n * Collects spans and exports them in batches based on:\n * - Batch size threshold (default: 500 spans — SDK-RELEASE-RULING.md §4.3 raised\n * this from 100; see `DEFAULT_BATCH_SIZE` below, which is the one true source)\n * - Time interval (default: 1000ms)\n * - Attribute product (`MAX_ATTRIBUTE_PAIRS_PER_BATCH`) and estimated serialized\n * size (`MAX_BATCH_BYTES`), both mirroring gateway constants\n *\n * Node.js is single-threaded — no locks needed.\n * Timer is unref()'d so it doesn't prevent process exit.\n */\n\nimport type { Span } from '../span.js';\nimport { ExportResult, type AckCounts, type SpanExporter } from './base.js';\nimport { debug, warn } from '../utils/log.js';\nimport { scrubText } from '../utils/scrub.js';\nimport {\n applyMaskBatch,\n stripContentBatch,\n warnMaskErrors,\n warnMaskSlow,\n MASK_BUDGET_MS_PER_SPAN,\n MASK_WARN_WINDOW_MS,\n type MaskFn,\n} from '../masking.js';\n\nexport interface BatchProcessorOptions {\n exporters: SpanExporter[];\n batchSize?: number;\n batchTimeoutMs?: number;\n maxQueueSize?: number;\n debug?: boolean;\n /**\n * Customer masking callback, `mask(key, value) => value`. Applied to every\n * content-bearing field of every span in this processor, once, BEFORE any\n * exporter sees the batch. See `../masking.ts`.\n */\n mask?: MaskFn;\n /**\n * Whether customer prompt/completion content may leave the process.\n * **Defaults to `false`** — the same fail-closed default as `resolveConfig`.\n * When false, every content-keyed attribute is replaced on the export path\n * before any exporter runs. See `../masking.ts` `stripContent`.\n */\n traceContent?: boolean;\n}\n\n/**\n * F-SDKCB-001 §5 (option J) — reason labels for a discarded span.\n *\n * One integer conflating an under-provisioned queue, a dead gateway and a\n * redeploy is the ambiguity W1/W3 was written against: the three causes demand\n * three different operator responses. The server side already landed on this\n * shape as `dropped{stage,reason,project_id}` (F-HONEST-001). Mirrors the\n * Python `DROP_*` constants in `exporters/batch.py`.\n *\n * `unacknowledged`: the backend's ack accounts for fewer spans than the batch\n * sent (after the counts are clamped to the batch size). Those spans are in no\n * other counter, so they are counted here: exported + rejected + dropped then\n * equals the spans that ended.\n */\nexport type DropReason = 'queue_full' | 'transport_refused' | 'shutdown_residue' | 'unacknowledged';\n\n/** Outcome of one `_exportBatch()` round.\n *\n * `shutdown()`'s drain loop must tell \"the queue is empty\" from \"a batch was\n * taken and nobody accepted it\" — RULING §4's no-SUCCESS exit. Without that\n * distinction the loop would spin for the whole budget against a dead\n * transport, and (because the bounded re-queue keeps the queue non-empty)\n * would never terminate at all. */\nconst enum Round {\n Empty = 0,\n Delivered = 1,\n Failed = 2,\n /** an export was already in flight (`_flushing`); this call made no progress */\n Busy = 3,\n}\n\n/** The value `raceDeadline` gives when the deadline comes first. */\nconst DEADLINE = Symbol('deadline');\n\n/**\n * Wait for `p`, but not longer than `ms`. The timer is cleared on both paths, so\n * it never keeps the process alive. `p` is not cancelled: it continues, and the\n * caller decides what its late answer means.\n */\nasync function raceDeadline<T>(p: Promise<T>, ms: number): Promise<T | typeof DEADLINE> {\n let timer: ReturnType<typeof setTimeout> | undefined;\n const deadline = new Promise<typeof DEADLINE>((resolve) => {\n timer = setTimeout(() => resolve(DEADLINE), Math.max(0, ms));\n });\n try {\n return await Promise.race([p, deadline]);\n } finally {\n clearTimeout(timer);\n }\n}\n\n/** Describe a thrown value for a debug line. Never throws (a Symbol, a hostile `toString`). */\nfunction describeThrown(e: unknown): string {\n // An error text can hold a key: scrubbed (`utils/scrub.ts`; the processor does not\n // know the exporter's key, so RISICARE_API_KEY and the forms of it are removed).\n return scrubText(e, []);\n}\n\n/**\n * Wait for an exporter's own `shutdown()`, but not longer than `ms`. A rejection\n * or a synchronous throw is logged at debug level. The timer is cleared.\n */\nasync function shutdownExporter(exporter: SpanExporter, ms: number): Promise<void> {\n try {\n const outcome = await raceDeadline(Promise.resolve().then(() => exporter.shutdown()), ms);\n if (outcome === DEADLINE) debug(`${exporter.name}.shutdown() did not finish within ${ms} ms`);\n } catch (e) {\n debug(`Error shutting down ${exporter.name}: ${describeThrown(e)}`);\n }\n}\n\n/** The batch that an export round has taken off the queue and not yet settled. */\ninterface InFlight {\n /** The batch: the key that the exporter's `abort(spans)` uses. */\n spans: Span[];\n size: number;\n /** Set by `shutdown()` when it stops waiting. A late answer then changes nothing. */\n abandoned: boolean;\n}\n\n/**\n * RULING §4 delegates this number with a derive-and-justify obligation.\n * `shutdown()` runs `exporter.shutdown()` AFTER the drain, so a drain that\n * spends the whole budget starves it.\n *\n * The built-in `HttpExporter.shutdown()` is a literal no-op — native fetch\n * needs no cleanup (`exporters/http.ts:159-161`) — so for the shipped exporter\n * the measured cost is ZERO. The reserve is therefore a policy allowance for a\n * CUSTOMER-supplied exporter, whose `shutdown(): Promise<void> | void`\n * (`exporters/base.ts:16`) we cannot measure. Held at 100 ms to match the\n * Python constant — the two SDKs must end with the same contract, and Python's\n * value is measured (see `_SHUTDOWN_RESERVE_MS` in `exporters/batch.py` and\n * `fix-workstream/perf/sdk_exporter_shutdown_cost_probe.py`). Against the\n * binding 2,000 ms SIGTERM budget this leaves 1,900 ms of drain.\n */\nconst SHUTDOWN_RESERVE_MS = 100;\n\n/**\n * SDK-RELEASE-RULING.md §4.3 — ONE shutdown budget, on every teardown path.\n *\n * 5,000 ms is bounded from ABOVE by something outside our control: the SDK's\n * shutdown runs inside the application's, which runs inside the container's\n * termination grace period. The tightest common default is `docker stop` at\n * 10 s (k8s `terminationGracePeriodSeconds` 30 s; systemd `TimeoutStopSec`\n * 90 s), and taking more than half of the tightest is hostile to the app's own\n * cleanup.\n *\n * ⚠ WHY A LONGER BUDGET IS NEARLY FREE: the drain exits on the FIRST round that\n * does not deliver (`Round.Delivered` check below). A dead transport costs one\n * round, not the budget. It is spent only while the transport is SUCCEEDING.\n *\n * ⚠ `client.ts` DERIVES its signal-handler backstop from this rather than\n * repeating a literal. Before the ruling both were an independent `5000`, so\n * the backstop's `process.exit(1)` raced the drain it exists to protect —\n * killing it at the deadline, with the wrong exit code, before the residue\n * warning could print. Do not re-introduce a second literal.\n *\n * Mirrors `SHUTDOWN_BUDGET_MS` in `client.py`.\n */\nexport const SHUTDOWN_BUDGET_MS = 5000;\n\n/** The largest delay that `setTimeout` accepts (2**31 - 1 ms). A larger one fires at once. */\nconst MAX_TIMEOUT_MS = 2 ** 31 - 1;\n\n/**\n * The budget that `flush(timeoutMs)` and `shutdown(timeoutMs)` use.\n *\n * A value that is not a finite number (`undefined`, `NaN`, `Infinity`, a string,\n * `null`) gives the default, `SHUTDOWN_BUDGET_MS`. A negative value gives 0. A\n * value above 2**31 - 1 gives 2**31 - 1. Through 0.7.1 such values reached\n * `setTimeout` and string concatenation as they were: `flush(Infinity)` and\n * `flush('3000')` returned `false` at once, and `shutdown(NaN)` dropped every\n * span, on a healthy server.\n */\nexport function normalizeTimeoutMs(value: unknown): number {\n if (typeof value !== 'number' || !Number.isFinite(value)) return SHUTDOWN_BUDGET_MS;\n if (value < 0) return 0;\n return Math.min(value, MAX_TIMEOUT_MS);\n}\n\n/**\n * The `transport_refused` warning is rate-limited to the exporter's existing\n * window (`exporters/http.ts`), so a flaky network cannot spam customer logs.\n * The `shutdown_residue` warning is NOT rate-limited (RULING §5): it fires at\n * most once per process lifetime by construction, so a window buys nothing and\n * would suppress the only signal in any process that had already warned about\n * the breaker — exactly the correlated case where the customer most needs it.\n */\nconst REFUSAL_WARN_WINDOW_MS = 300_000;\n\n/**\n * SDK-RELEASE-RULING.md §4.3 — the default batch size, raised 100 -> 500.\n *\n * DERIVED, not picked. `shutdown()`'s drain is strictly serial — one export per\n * round-trip — so the most it can save is\n * ceiling = floor((budget - reserve) / RTT) x batchSize\n * and the requirement is that it drain the SDK's OWN maximum queue\n * (`maxQueueSize` = 10,000, the most it can ever be holding) at the design\n * target RTT = 100 ms:\n * batchSize >= 10,000 x RTT / (5,000 - 100) -> 204 at 100 ms, 510 at 250 ms\n * 500 satisfies it to the 250 ms trans-Pacific tail and sits 1.55x under the\n * ceiling the gateway's attribute-product cap imposes (below).\n *\n * ⚠ NEITHER THIS NOR THE BUDGET IS SUFFICIENT ALONE — measured, ruling §2. At\n * 100 ms RTT: budget alone leaves 51 % lost, batch alone leaves 60 % lost at the\n * tail, both together lose nothing. Do not \"simplify\" one back.\n *\n * Mirrors `DEFAULT_BATCH_SIZE` in `exporters/batch.py` — the two SDKs must end\n * with the same contract.\n */\nexport const DEFAULT_BATCH_SIZE = 500;\n\n/**\n * The gateway refuses a request whose summed attribute count exceeds this\n * (`MAX_ATTRIBUTE_PAIRS_PER_REQUEST`, `handlers/ingest.rs`, F-ACKRSV-001) —\n * WHOLE request, never truncated, and the exporter treats that 4xx as a\n * failure, retries it futilely and finally discards the batch as\n * `transport_refused`. The cap is `sum(span.attributes.length)`, i.e. LINEAR in\n * batch size: at batch B a customer is refused above `24,000 / B` attributes\n * per span — 240 at B=100, but only 48 at B=500.\n *\n * Without this bound, raising the default would silently break every customer\n * between those two densities: accepted today, whole-request-refused tomorrow,\n * with no action on their part. So the batch is bounded on BOTH axes, and the\n * raise becomes strictly no-worse-than-today on the attribute axis.\n *\n * ⚠ COUPLING, DECLARED (ruling §4.5) — AND THE DIRECTIONS ARE NOT SYMMETRIC.\n * ⚠ CORRECTED 2026-07-27 (F-SDKBYTES-001 §4.1). This comment used to read\n * \"Stale in either direction is SAFE — too low means slightly smaller batches,\n * too high means the gateway refuses exactly as it does today.\" The second half\n * is FALSE, and the error mattered because it licenses a unilateral change on\n * the gateway side that this SDK cannot survive:\n *\n * • STALE LOW (SDK constant < gateway cap) — SAFE, unconditionally. The SDK\n * assembles smaller batches than it needed to; every one is accepted.\n * • STALE HIGH (SDK constant > gateway cap) — safe ONLY while the gateway's\n * cap does not DECREASE. If it is lowered, this SDK assembles batches the\n * gateway now refuses: requests that are accepted TODAY begin returning\n * 4xx, the exporter retries each one futilely and discards the whole batch\n * as `transport_refused`. That is a NEW refusal caused by the mismatch —\n * not \"exactly as it does today\".\n *\n * ⇒ RAISING the gateway cap is safe to do unilaterally. LOWERING it is not: the\n * SDK constant must move first and be adopted, and `F-SDKVER-001` records\n * that nothing pins or even observes an SDK version server-side, so \"adopted\"\n * is weeks-to-never rather than a deploy.\n *\n * The gateway remains the enforcer; this only stops OUR DEFAULT from moving a\n * customer across ITS boundary.\n */\nexport const MAX_ATTRIBUTE_PAIRS_PER_BATCH = 24_000;\n\n/**\n * The per-batch SERIALIZED-BYTE bound (F-SDKBYTES-001) — the third axis.\n *\n * `SDK-RELEASE-RULING.md` §4.5 bounded the batch on span COUNT and attribute\n * PRODUCT and explicitly left BYTES open: \"a customer putting a 1 MB string in\n * an attribute can exceed the body limit at *any* batch size, and B=500 makes\n * it 5x more reachable. I did not guard this.\"\n *\n * MEASURED (`perf/sdk_batch_byte_ceiling_probe.py`, raw\n * `perf/sdk-batch-byte-ceiling.json`; its JS cross-check arm compiles\n * `src/span.ts` itself rather than trusting `dist/`):\n *\n * batch=500 crosses max_body_size (10,485,760 B) at 20,971 B/span\n * batch=100 crosses it at 104,857 B/span\n *\n * and the ruling's \"16x headroom\" quoted only the measured FLOOR. Against the\n * measured MAXIMUM realistic span (13,487 B) a 500-span batch is 6,743,500 B —\n * 1.55x headroom, not 16x. The count raise spent most of the byte margin.\n *\n * WITHOUT IT, MEASURED (probe ARM 2): the gateway answers 413, and the exporter\n * does NOT treat 413 as permanent — `http.ts` maps every non-2xx that is not\n * 408/504 to FAILURE and retries it. On a permanently-413 batch: 12 HTTP\n * requests (4 re-queue rounds x 3 exporter attempts), then the ENTIRE batch\n * discarded as `transport_refused`. Counted and warned — but total loss.\n *\n * THE ESTIMATE, AND WHICH WAY IT ERRS. Serialized size is not knowable without\n * serializing, and serializing to measure would double the export cost. So the\n * batch is bounded on an ESTIMATE:\n *\n * string -> 2 + utf8ByteLength(s), the bytes `fetch` will send for\n * the raw characters\n * number/bool/null -> a fixed allowance; containers recurse to depth 4\n * anything else -> a fixed allowance (see `EST_OPAQUE_VALUE_BYTES`)\n *\n * ⚠ ASYMMETRY WITH PYTHON, DELIBERATE. Each SDK estimates against ITS OWN\n * encoder. `JSON.stringify` emits non-ASCII RAW (UTF-8 on the wire);\n * `json.dumps` escapes it to `\\uXXXX`. Measured: a 9,525-char CJK attribute is\n * 28,859 B from JS and ~2x that from Python. Mirroring Python's per-character\n * multiplier here would over-estimate every non-ASCII JS batch by ~4x.\n *\n * ⚠ THE ONE UNDER-ESTIMATE, NAMED: JSON escaping. A `\"` costs 2 bytes and a\n * control character 6; `utf8ByteLength` charges 1 for each. The 20 % margin\n * below is what absorbs it — a batch may be up to ~25 % escape characters BY\n * COUNT before the estimate stops covering the real body. Past that the gateway\n * refuses, exactly as it does today: no new failure mode, the bound is simply\n * not helping. Stated rather than engineered away because counting escapes is a\n * second O(bytes) scan.\n *\n * THE FRACTION: 8 MiB is 80 % of the gateway's 10 MiB default. Below it the\n * measured realistic corpus does not bind at batch 500 (1.24x under this\n * budget); above it, the 20 % is the escape margin.\n *\n * ⚠ COUPLING, DECLARED, with the SAME asymmetry as the attribute cap above:\n * stale LOW is unconditionally safe; stale HIGH is safe only while\n * `max_body_size` does not DECREASE.\n */\nexport const MAX_BATCH_BYTES = 8 * 1024 * 1024; // 8,388,608 B = 80 % of max_body_size\n\nconst SPAN_ENVELOPE_BYTES = 512; // typed camelCase fields; a minimal span is ~250 B\nconst CHILD_ENVELOPE_BYTES = 128; // per event / link, before its strings\nconst SCALAR_BYTES = 24; // widest JSON number repr\nconst LITERAL_BYTES = 5; // \"false\" / \"null\"\nconst EST_MAX_DEPTH = 4;\n/**\n * Charge for a value the ladder cannot walk (a class instance, a Map, anything\n * past `EST_MAX_DEPTH`). ⚠ Unlike Python — whose `_coerce_attribute_value`\n * truncates its `str()` fallback at 4,096 chars, making the same charge there a\n * genuine BOUND — JS has no truncation at all (`F-SDKATTRLEN-001`), so this is\n * an ALLOWANCE and a deeply-nested object can exceed it. The gateway refuses\n * that shape exactly as it does today.\n */\nconst EST_OPAQUE_VALUE_BYTES = 4_096;\n\n/**\n * UTF-8 byte length, without allocating the encoded copy.\n *\n * `Buffer.byteLength` is a single native scan and is what `fetch` will actually\n * put on the wire for the raw characters. The fallback multiplier 3 is a true\n * upper bound on UTF-8 bytes per UTF-16 code unit (a BMP code point is 1 unit\n * and at most 3 bytes; an astral one is 2 units and 4 bytes, i.e. 2 per unit),\n * so a Buffer-less runtime errs HIGH rather than low.\n */\nconst utf8ByteLength: (s: string) => number =\n typeof Buffer !== 'undefined' && typeof Buffer.byteLength === 'function'\n ? (s) => Buffer.byteLength(s, 'utf8')\n : (s) => s.length * 3;\n\nfunction estStringBytes(s: string): number {\n return 2 + utf8ByteLength(s);\n}\n\nfunction estValueBytes(v: unknown, depth = 0): number {\n if (typeof v === 'string') return estStringBytes(v);\n if (v === null || v === undefined || typeof v === 'boolean') return LITERAL_BYTES;\n if (typeof v === 'number' || typeof v === 'bigint') return SCALAR_BYTES;\n if (Array.isArray(v) && depth < EST_MAX_DEPTH) {\n let total = 2 + Math.max(0, v.length - 1);\n for (const item of v) total += estValueBytes(item, depth + 1);\n return total;\n }\n if (\n typeof v === 'object' &&\n depth < EST_MAX_DEPTH &&\n Object.getPrototypeOf(v as object) === Object.prototype\n ) {\n let total = 2;\n for (const [k, val] of Object.entries(v as Record<string, unknown>)) {\n total += estStringBytes(k) + 2 + estValueBytes(val, depth + 1);\n }\n return total;\n }\n return EST_OPAQUE_VALUE_BYTES;\n}\n\nfunction estMappingBytes(m: Record<string, unknown>): number {\n let total = 0;\n for (const [k, v] of Object.entries(m)) total += estStringBytes(k) + 2 + estValueBytes(v);\n return total;\n}\n\n/**\n * Estimated serialized bytes this span contributes to a request body, or the\n * fixed envelope if the object is not span-shaped.\n *\n * ⚠ Defensive in exactly the shape `spanAttrCount` is, and for the same reason:\n * TypeScript types `_queue` as `Span[]`, but nothing stops a JS caller or a test\n * double from queueing something else. Throwing from inside the export path\n * would break export for the whole batch. On any surprise this returns the\n * envelope, which can only make the bound LESS binding — never more, and never\n * a wedge.\n */\nfunction spanBytesEstimate(span: Span): number {\n try {\n const s = span as unknown as Record<string, unknown>;\n let total = SPAN_ENVELOPE_BYTES;\n for (const field of ['name', 'statusMessage'] as const) {\n if (typeof s[field] === 'string') total += estStringBytes(s[field] as string);\n }\n const attrs = s.attributes;\n if (attrs != null && typeof attrs === 'object' && !Array.isArray(attrs)) {\n total += estMappingBytes(attrs as Record<string, unknown>);\n }\n for (const key of ['events', 'links'] as const) {\n const coll = s[key];\n if (!Array.isArray(coll)) continue;\n for (const child of coll) {\n total += CHILD_ENVELOPE_BYTES;\n const ca = (child as Record<string, unknown> | null)?.attributes;\n if (ca != null && typeof ca === 'object' && !Array.isArray(ca)) {\n total += estMappingBytes(ca as Record<string, unknown>);\n }\n }\n }\n return total;\n } catch {\n return SPAN_ENVELOPE_BYTES;\n }\n}\n\n/**\n * Attribute count for the per-batch product bound, or 0 if unknowable.\n *\n * ⚠ Defensive for the same reason the Python `_span_attr_count` is: TypeScript\n * types `_queue` as `Span[]`, but nothing stops a JS caller (or a test double)\n * from queueing an object without `attributes`. Reading `.length` off\n * `undefined` would throw from inside the export path and break export for the\n * whole batch. An object with no countable attributes contributes 0, which can\n * only make the bound less binding, never more.\n */\nfunction spanAttrCount(span: Span): number {\n const attrs = (span as { attributes?: unknown }).attributes;\n if (attrs == null) return 0;\n if (attrs instanceof Map) return attrs.size;\n if (typeof attrs === 'object') return Object.keys(attrs as object).length;\n return 0;\n}\n\nexport class BatchSpanProcessor {\n private readonly _exporters: SpanExporter[];\n private readonly _batchSize: number;\n private readonly _batchTimeoutMs: number;\n private readonly _maxQueueSize: number;\n // ⚠ NO `_debug` FIELD. It existed, was assigned, and was read by NOTHING —\n // `tsc --noEmit` had been RED on this package at HEAD for it (TS6133), which\n // survived because `ci-local.sh` runs this package's vitest and never its\n // typecheck, and `prepublishOnly` runs `build && test` — also no typecheck.\n // Filed F-SDKJSTYPECHECK-001. Debug output here is gated globally by\n // `setDebug()` in `../utils/log.ts`, so a per-processor flag was always\n // redundant; Python's `self._debug` exists because `logging` has no such\n // global switch.\n\n private _queue: Span[] = [];\n private _timer: ReturnType<typeof setInterval> | null = null;\n private _started = false;\n private _flushing = false;\n private _inFlight: InFlight | null = null;\n /**\n * The `shutdown()` that runs, or ran. A second `shutdown()` returns it, and a\n * `flush()` that comes while it runs waits for it (inside its own deadline).\n */\n private _closing: Promise<void> | null = null;\n /**\n * True from the start of the drain of `shutdown()` until its loop ends and the\n * residue is counted (no `await` between those two points). A span that ends\n * in this time joins the drain. After it, the processor can take no span.\n */\n private _drainOpen = false;\n private _lateSpanWarned = false;\n private _beforeExitHandler: (() => void) | null = null;\n\n // Retry tracking for failed batches (Audit #5)\n private _retryCounts = new Map<string, number>();\n private static readonly MAX_RETRIES = 3;\n\n private _lastRefusalWarnAt = Number.NEGATIVE_INFINITY;\n private _lastUnackWarnAt = Number.NEGATIVE_INFINITY;\n /**\n * The loss total (dropped + rejected) that the last finished `flush()` saw.\n * A flush reports a loss that is new since then, one time.\n */\n private _lossMark = 0;\n\n // ── Masking (see `../masking.ts`) ──────────────────────────────────────────\n private readonly _mask: MaskFn | undefined;\n // ── Content capture gate (see `../masking.ts`) ─────────────────────────────\n // Fail-closed: an unspecified value means \"do not capture\". This is the ONE\n // place the gate runs for BOTH content paths — provider capture AND hand-set\n // attributes — so it must not be conditional on anything a caller might\n // forget to pass. Python twin: `BatchSpanProcessor._trace_content`.\n private readonly _traceContent: boolean;\n private _lastMaskWarnAt = Number.NEGATIVE_INFINITY;\n private _lastSlowMaskWarnAt = Number.NEGATIVE_INFINITY;\n\n // Metrics\n /** DEPRECATED flat total. Retained as the exact SUM of\n * `droppedSpansByReason` so existing readers keep working (RULING §5\n * back-compat — the same deprecate-and-alias shape this codebase used for\n * `complete`->`settled` and `spans_flushed_total`). Prefer the labelled\n * record: one integer cannot tell an under-provisioned queue from a dead\n * gateway from a redeploy. */\n droppedSpans = 0;\n droppedSpansByReason: Record<DropReason, number> = {\n queue_full: 0,\n transport_refused: 0,\n shutdown_residue: 0,\n unacknowledged: 0,\n };\n exportedSpans = 0;\n /**\n * Spans that the backend acknowledged as REJECTED (the ack's `rejected`). They\n * are not stored and are not retried. An exporter without an ack adds nothing.\n */\n rejectedSpans = 0;\n /** Export ATTEMPTS, not a span count. */\n failedExports = 0;\n /**\n * Fields whose mask callback threw and were replaced with\n * `MASK_ERROR_MARKER`. A FIELD count, not a span count — one span can\n * contribute several. Non-zero means those fields carry a marker instead of\n * data: a customer-code bug, not a transport one.\n */\n maskErrors = 0;\n\n constructor(options: BatchProcessorOptions) {\n this._exporters = [...options.exporters];\n\n // batchSize: clamp to [1, 10000] AND warn on out-of-range — silent\n // clamping is a debugging tar pit (CON-257 / P1-3). Mirrors Python.\n const requestedBatchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;\n const clampedBatchSize = Math.max(1, Math.min(requestedBatchSize, 10_000));\n if (clampedBatchSize !== requestedBatchSize) {\n warn(\n `batchSize=${requestedBatchSize} is outside the allowed range [1, 10000]; clamping to ${clampedBatchSize}`,\n );\n }\n this._batchSize = clampedBatchSize;\n\n this._batchTimeoutMs = options.batchTimeoutMs ?? 1000;\n this._maxQueueSize = options.maxQueueSize ?? 10000;\n this._mask = options.mask;\n this._traceContent = options.traceContent ?? false;\n }\n\n start(): void {\n if (this._started) return;\n this._started = true;\n\n // Periodic flush timer — unref so it doesn't keep process alive\n this._timer = setInterval(() => {\n void this._exportBatch();\n }, this._batchTimeoutMs);\n this._timer.unref();\n\n // Flush on process exit (Audit #3: use .once, not .on; await, not void)\n this._beforeExitHandler = () => {\n void this.shutdown();\n };\n process.once('beforeExit', this._beforeExitHandler);\n }\n\n /** Record `count` discarded spans under `reason`.\n *\n * `droppedSpans` is maintained as the exact sum of the labelled counters\n * (RULING §5 back-compat), so the locked pins — which read the flat\n * integer — stay meaningful. */\n private _recordDropped(reason: DropReason, count = 1): void {\n this.droppedSpans += count;\n this.droppedSpansByReason[reason] += count;\n }\n\n /**\n * Run the customer mask over a batch, in place. Never throws.\n *\n * Failure semantics are ruled in `../masking.ts`: a field whose mask throws\n * becomes `MASK_ERROR_MARKER` and the span is kept. The counter is per FIELD;\n * both warnings are rate-limited to one per window so a mask that throws on\n * every span cannot flood the customer's logs — the same shape as the\n * transport-refusal warning above.\n */\n private _applyMask(batch: Span[]): void {\n const mask = this._mask;\n if (mask === undefined) return;\n\n const { errors, elapsedMs } = applyMaskBatch(batch, mask);\n const now = Date.now();\n\n if (errors > 0) {\n this.maskErrors += errors;\n if (now - this._lastMaskWarnAt > MASK_WARN_WINDOW_MS) {\n this._lastMaskWarnAt = now;\n warnMaskErrors(errors, this.maskErrors);\n }\n }\n\n if (\n elapsedMs > MASK_BUDGET_MS_PER_SPAN * batch.length &&\n now - this._lastSlowMaskWarnAt > MASK_WARN_WINDOW_MS\n ) {\n this._lastSlowMaskWarnAt = now;\n warnMaskSlow(batch.length, elapsedMs);\n }\n }\n\n /**\n * Drain what we hold, or name what we could not (F-SDKDRAIN-001).\n *\n * Per RULING §4 (option E, hard-bounded) the drain loops until ONE of: the\n * queue is empty; the deadline expires; or a full round completes with no\n * exporter returning SUCCESS.\n *\n * ⚠ The `_flushing` handling is load-bearing, and `SDKDRAIN_JS_004` exists\n * to catch its absence. `_exportBatch()` returns immediately when an export\n * is already in flight (`:171`), so a loop that merely calls it again makes\n * NO progress and abandons the queue exactly as before — measured at 900 of\n * 1,000. We await a tick instead, the shape `flush()` already models.\n *\n * The deadline is a hard wall-clock bound. Each round is raced against the\n * budget that remains. At the deadline, `shutdown()` stops the round in flight\n * through the exporter's optional `abort()`. That stopped round changes no\n * counter, does not move the circuit breaker and re-queues nothing. Through\n * 0.7.1 the deadline was checked only between rounds, so one round against a\n * silent server (3 attempts x 5 s) held a 5,000 ms shutdown for 15 s.\n *\n * Anything still queued when the loop stops, AND a batch whose export was\n * stopped, is COUNTED as `shutdown_residue` and announced with ONE WARNING\n * that gives both numbers. The server may have received the spans of the\n * stopped export. The warning is the primary signal, not the counter: a\n * counter incremented inside `shutdown()` is written to memory about to be\n * freed and has no reader (RULING §2 / §8.2).\n *\n * Each exporter's own `shutdown()` gets the time that is left of the budget.\n * An exporter that does not finish in that time is not awaited.\n *\n * Limit: the abort does not stop a TLS handshake that stalls. Measured, such a\n * handshake kept the process alive about 10 s after `shutdown()` returned.\n *\n * A second call, while the first runs or after it ended, returns the promise\n * of the first one. It does not return before the first drain ends.\n *\n * @param timeoutMs - The budget (default 5000). See `normalizeTimeoutMs` for\n * the values that are not a finite number.\n */\n shutdown(timeoutMs: number = SHUTDOWN_BUDGET_MS): Promise<void> {\n if (!this._started) return this._closing ?? Promise.resolve();\n this._closing = this._shutdown(timeoutMs);\n return this._closing;\n }\n\n private async _shutdown(timeoutMs: number): Promise<void> {\n timeoutMs = normalizeTimeoutMs(timeoutMs);\n this._started = false;\n this._drainOpen = true;\n\n if (this._timer) {\n clearInterval(this._timer);\n this._timer = null;\n }\n\n // Remove process listener to prevent leak (Audit #3)\n if (this._beforeExitHandler) {\n process.removeListener('beforeExit', this._beforeExitHandler);\n this._beforeExitHandler = null;\n }\n\n // Halve rather than underflow on a tiny budget: shutdown(200) still gets\n // 100 ms of drain instead of none.\n const reserveMs = Math.min(SHUTDOWN_RESERVE_MS, timeoutMs / 2);\n const shutdownDeadline = Date.now() + timeoutMs;\n const drainDeadline = shutdownDeadline - reserveMs;\n\n while (this._queue.length > 0 || this._flushing) {\n const remaining = drainDeadline - Date.now();\n if (remaining <= 0) break;\n // A hard wall-clock bound: the round is raced against the budget. At the\n // deadline the round in flight is stopped below.\n const outcome = await raceDeadline(this._exportBatch(), remaining);\n if (outcome === DEADLINE) break;\n if (outcome === Round.Busy) {\n // An export is mid-await. Yield rather than spin on a no-op call.\n await new Promise((r) => setTimeout(r, 1));\n continue;\n }\n if (outcome !== Round.Delivered) {\n // Empty -> nothing left, we are done.\n // Failed -> no exporter accepted this round; a further round cannot\n // help and would spin to the deadline on precisely the path\n // where there is nothing to save.\n break;\n }\n }\n\n // The drain takes no more spans from here on. This line and the residue\n // below have no `await` between them: a span that ends before them is in\n // `queued`, and one that ends after them is counted by `onSpanEnd`.\n this._drainOpen = false;\n\n // Once shutdown() has returned, holding IS abandoning: the timer is\n // cleared, the exit listener is gone, nothing will ever export these.\n //\n // A batch whose export did not finish inside the budget is abandoned too. It\n // is counted HERE, and its late answer changes no counter and re-queues\n // nothing (see `_exportBatch`).\n const queued = this._queue.length;\n const flight = this._inFlight;\n const inFlight = flight !== null && !flight.abandoned ? flight.size : 0;\n if (flight !== null && !flight.abandoned) {\n flight.abandoned = true;\n // Stop the abandoned export, so that its request, retries and backoff do\n // not keep the process alive. Without this, it ran on for up to 3\n // attempts of 5 s after shutdown() returned. An exporter without\n // `abort()` is left alone.\n for (const exporter of this._exporters) {\n try {\n exporter.abort?.(flight.spans);\n } catch (e) {\n debug(`Error aborting ${exporter.name}: ${describeThrown(e)}`);\n }\n }\n }\n const residue = queued + inFlight;\n if (residue > 0) {\n this._queue.length = 0;\n this._recordDropped('shutdown_residue', residue);\n // NOT rate-limited, by ruling. Names the counts AND the reason.\n warn(\n `shutdown() gave up with ${residue} span(s) (reason=shutdown_residue): ` +\n `${queued} still queued and ${inFlight} in an export that shutdown() stopped. ` +\n (inFlight > 0\n ? `The server may have received the ${inFlight} span(s) of the stopped export. `\n : '') +\n `All ${residue} were not confirmed as delivered, and are counted as dropped. ` +\n `The ${timeoutMs} ms shutdown ` +\n `budget expired or the transport stopped accepting. Pass a larger timeout to ` +\n `shutdown(timeoutMs), or raise your container's termination grace period, to lose less.`\n );\n }\n\n // Shutdown exporters, inside the time that is left. An exporter whose own\n // shutdown() is slow or never settles must not hold the process: through\n // 0.7.1 a 4 s exporter shutdown held shutdown(1000) for 4 s.\n for (const exporter of this._exporters) {\n await shutdownExporter(exporter, Math.max(0, shutdownDeadline - Date.now()));\n }\n\n // Clean up retry tracking — retry-map drain site 3 of 3\n this._retryCounts.clear();\n\n debug(\n `BatchSpanProcessor shutdown. Exported: ${this.exportedSpans}, ` +\n `Dropped: ${this.droppedSpans}, Failed: ${this.failedExports}`\n );\n }\n\n onSpanEnd(span: Span): void {\n if (!this._started) {\n // A span that ends WHILE the drain of `shutdown()` runs joins that drain: its\n // loop exports it before it ends, inside the same bound. Through 0.8.0 it was\n // dropped with no count. A span that ends when the drain can take no more (its\n // loop ended, or the bound ended) is counted at once as `shutdown_residue`.\n // A processor that was never started took no span, and counts none.\n if (this._drainOpen) this._enqueue(span, false);\n else if (this._closing !== null) this._lateSpan();\n return;\n }\n this._enqueue(span, true);\n }\n\n private _enqueue(span: Span, exportAtBatchSize: boolean): void {\n // Check queue capacity\n if (this._queue.length >= this._maxQueueSize) {\n this._recordDropped('queue_full');\n if (this.droppedSpans === 1 || this.droppedSpans % 1000 === 0) {\n warn(`Span queue full (${this._maxQueueSize}). ${this.droppedSpans} spans dropped so far.`);\n }\n return;\n }\n\n this._queue.push(span);\n\n // Trigger immediate flush if batch size reached\n if (exportAtBatchSize && this._queue.length >= this._batchSize) {\n void this._exportBatch();\n }\n }\n\n /** A span that ended after the drain ended: counted, with one WARNING for the first. */\n private _lateSpan(): void {\n this._recordDropped('shutdown_residue');\n if (this._lateSpanWarned) return;\n this._lateSpanWarned = true;\n warn(\n 'a span ended after shutdown() had stopped taking spans (reason=shutdown_residue). ' +\n 'It was not delivered, and it is counted as dropped. Later spans of this kind are ' +\n 'counted without a WARNING.'\n );\n }\n\n /**\n * Flush pending spans.\n *\n * @returns `true` only if everything queued at entry was DELIVERED and no\n * span was lost since the previous flush returned.\n *\n * RULING §6. This used to answer a different question — \"is the queue\n * empty?\" — and those two diverge in exactly one case: when spans left the\n * queue WITHOUT reaching the transport. That case is the entire finding. A\n * customer who calls `flush()` before exit and gets `true` has done\n * everything right; silence lets them discover the problem, a false\n * affirmative forecloses it.\n *\n * A LOSS IS REPORTED BY THE NEXT `flush()`, ONE TIME (design section 0,\n * third revision). Returns `true` only when, at the moment it returns, the\n * queue is empty, no batch is in flight, and no span was discarded or\n * rejected since the previous `flush()` returned (or since start, for the\n * first call). Through 0.7.1 only a loss during the call counted: a script\n * whose spans the batch timer had discarded against a 401 sink got `true`\n * with nothing delivered. A failure that a retry repairs does not make it\n * `false`.\n *\n * Mechanics: the processor keeps a loss mark, the loss total (dropped +\n * rejected) that the last finished flush saw. A flush compares the total\n * with the mark it read at its start, then raises the mark to the total\n * (never lowers it). Two flushes that overlap both answer `false` for one\n * loss. The flush after that answers `true` when nothing new was lost.\n *\n * Returns `false` in these cases:\n * (a) the deadline expires with spans still queued or in flight, or while a\n * `shutdown()` that it waits for still runs;\n * (b) a span was discarded since the previous flush returned: queue full,\n * breaker refusal, retry exhaustion, spans that `shutdown()` left\n * (`shutdown_residue`), or an ack that did not account for it or a span\n * that could not be serialized (`unacknowledged`);\n * (c) the backend rejected a span since the previous flush returned.\n *\n * A `flush()` that comes while a `shutdown()` runs (the SDK's own drain at\n * SIGTERM or SIGINT, or a `shutdown()` that nobody awaited) waits for that\n * shutdown, inside its OWN deadline, and then answers from the final tally with\n * the same loss mark. After `shutdown()` it answers from the final tally in the\n * same way. Through 0.8.0 both answered from the empty queue: true in 0 ms,\n * with the batch in flight, and true after a rejection or a `transport_refused`\n * drop. A loss that `shutdown()` counts (also `shutdown_residue`) makes ONE\n * `flush()` false, as every other loss does.\n *\n * The deadline is a hard wall-clock bound on the WAIT. At the deadline\n * `flush()` returns `false`. Through 0.7.1 the deadline was checked only\n * between rounds.\n *\n * ⚠ `flush()` never stops a request that is already sent. The export round in\n * flight continues and ends by its own rules: its request timeout, its\n * retries, the circuit breaker. A short flush budget therefore costs no retry,\n * moves no breaker and sends nothing twice. Its result still counts.\n *\n * Limit: that round can keep the process alive after `flush()` returns\n * `false`, until its own timeouts end. Measured on a silent server: 22 s. To\n * end a process within a bound, call `await shutdown(timeoutMs)`: it stops\n * the round in flight.\n *\n * ⚠ (b) reads the flat total, so a concurrent `queue_full` drop of a span\n * that arrived during the call also answers `false`. That is the\n * conservative direction on purpose: a false negative costs a caller one\n * more flush, a false positive is the defect being fixed.\n */\n async flush(timeoutMs: number = SHUTDOWN_BUDGET_MS): Promise<boolean> {\n timeoutMs = normalizeTimeoutMs(timeoutMs);\n\n const deadline = Date.now() + timeoutMs;\n const mark = this._lossMark;\n // Report a loss once: compare with the mark, then raise the mark to the\n // total this flush saw (never lower it). Two flushes that overlap both\n // answer false for one loss.\n const finish = (settled: boolean): boolean => {\n const lost = this.droppedSpans + this.rejectedSpans;\n this._lossMark = Math.max(this._lossMark, lost);\n return settled && lost === mark;\n };\n\n if (!this._started) {\n // A `shutdown()` that runs (the SDK's own drain, or one that nobody\n // awaited): its batch is in flight and its residue is not counted yet.\n // Wait for it, inside THIS deadline. The unconditional answer from the\n // empty queue was true in 0 ms, with nothing delivered.\n if (this._closing !== null) {\n const closed = await raceDeadline(this._closing.catch(() => undefined), timeoutMs);\n if (closed === DEADLINE) return finish(false);\n }\n // Shut down: the queue is empty, and a batch that `shutdown()` abandoned\n // is counted already (`shutdown_residue`), so the loss mark covers it.\n const held = this._inFlight !== null && !this._inFlight.abandoned;\n return finish(this._queue.length === 0 && !held);\n }\n\n // Wait for in-flight exports to complete AND queue to drain\n while (this._queue.length > 0 || this._flushing) {\n const remaining = deadline - Date.now();\n if (remaining <= 0) return finish(false);\n if (!this._flushing && this._queue.length > 0) {\n // Race the WAIT only. The round continues after the deadline.\n const outcome = await raceDeadline(this._exportBatch(), remaining);\n if (outcome === DEADLINE) return finish(false);\n } else {\n // Wait a tick for the in-flight export to finish\n await new Promise((r) => setTimeout(r, 1));\n }\n }\n\n return finish(true);\n }\n\n getMetrics() {\n return {\n exportedSpans: this.exportedSpans,\n rejectedSpans: this.rejectedSpans,\n droppedSpans: this.droppedSpans,\n droppedSpansByReason: { ...this.droppedSpansByReason },\n failedExports: this.failedExports,\n maskErrors: this.maskErrors,\n queueSize: this._queue.length,\n queueCapacity: this._maxQueueSize,\n queueUtilization: this._queue.length / this._maxQueueSize,\n };\n }\n\n /**\n * Count a delivered batch of `n` spans from the exporter's ack.\n *\n * The ack is not trusted. With r = min(rejected, n), a = min(accepted, n - r)\n * and u = n - a - r: `exportedSpans` rises by a, `rejectedSpans` by r, and the\n * u spans that no ack accounts for are dropped as `unacknowledged`, with one\n * rate-limited WARNING. Without an ack (console, custom exporter), the whole\n * batch counts as exported, as before. Python twin: the same clamp.\n */\n private _countDelivered(n: number, ack: AckCounts | null): void {\n if (ack === null) {\n this.exportedSpans += n;\n return;\n }\n // Pessimistic: a sink that says \"rejected\" is believed before one that says\n // \"accepted\" (design section 0, ack clamp REVISED).\n const rejected = Math.min(ack.rejected, n);\n const accepted = Math.min(ack.accepted, n - rejected);\n const unacknowledged = n - accepted - rejected;\n this.exportedSpans += accepted;\n this.rejectedSpans += rejected;\n if (unacknowledged > 0) {\n this._recordDropped('unacknowledged', unacknowledged);\n const now = Date.now();\n if (now - this._lastUnackWarnAt > REFUSAL_WARN_WINDOW_MS) {\n this._lastUnackWarnAt = now;\n warn(\n `Risicare: the backend's ack accounts for ${accepted + rejected} of ${n} span(s) ` +\n `in this batch. The other ${unacknowledged} are counted as dropped ` +\n `(reason=unacknowledged): they may not be stored. ` +\n `${this.droppedSpansByReason.unacknowledged} span(s) counted this way so far ` +\n `in this process.`,\n );\n }\n }\n }\n\n /** The requests in one export round, when every exporter that delivers states it. */\n private _requestsPerRound(): number | undefined {\n const delivering = this._exporters.filter((e) => e.countsAsDelivery !== false);\n if (delivering.length !== 1) return undefined;\n const n = delivering[0].attemptsPerExport;\n return typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : undefined;\n }\n\n /**\n * One export round.\n *\n * Which results decide delivery: an exporter that only shows spans locally\n * (`countsAsDelivery === false`, the console exporter) decides only when no\n * other kind of exporter is present. Among the exporters that deliver, ANY\n * success counts the batch as delivered, once.\n */\n private async _exportBatch(): Promise<Round> {\n if (this._flushing) return Round.Busy;\n if (this._queue.length === 0) return Round.Empty;\n this._flushing = true;\n let flight: InFlight | null = null;\n\n try {\n // Take up to batchSize spans — AND up to the attribute-product bound, AND\n // up to the serialized-byte bound; whichever binds first\n // (SDK-RELEASE-RULING.md §4.5 + F-SDKBYTES-001). `batchSize` is a CEILING,\n // not a fixed size, on all three axes.\n //\n // Take-at-least-one is unconditional on every axis: a single span that\n // alone exceeded a bound would otherwise be taken by no round ever,\n // wedging the queue permanently. One over-cap span is the gateway's\n // problem to refuse and the retry budget's to count; a wedged queue would\n // be ours forever.\n let take = 0;\n let pairs = 0;\n let nbytes = 0;\n const limit = Math.min(this._batchSize, this._queue.length);\n while (take < limit) {\n const head = this._queue[take];\n const spanPairs = spanAttrCount(head);\n const spanBytes = spanBytesEstimate(head);\n if (\n take > 0 &&\n (pairs + spanPairs > MAX_ATTRIBUTE_PAIRS_PER_BATCH ||\n nbytes + spanBytes > MAX_BATCH_BYTES)\n ) {\n break;\n }\n pairs += spanPairs;\n nbytes += spanBytes;\n take++;\n }\n const batch = this._queue.splice(0, take);\n if (batch.length === 0) return Round.Empty;\n flight = { spans: batch, size: batch.length, abandoned: false };\n this._inFlight = flight;\n\n // ⚠ MASK HERE — after the batch is off the queue, before any exporter.\n //\n // WHY NOT in `onSpanEnd()`: that runs on the call that ended the span,\n // i.e. inside the customer's own request path. This site is at least on\n // the export turn.\n //\n // ⚠ AND WHY THAT IS A WEAKER GUARANTEE THAN PYTHON'S: Node has one\n // thread. Python's mask runs on a background worker and costs only drain\n // rate; this one blocks the event loop for its duration. The budget\n // warning below is the whole of the protection, and it is a warning.\n //\n // ⚠ DECLARED RIPPLE, same as Python: the attribute-product and byte\n // bounds above are computed on PRE-mask values. Redaction shrinks, so the\n // estimate stays conservative for every realistic mask; a mask that GROWS\n // content can push the real body past the estimate, which the estimate\n // already declares for ASCII escaping and already answers the same way —\n // the gateway remains the enforcer.\n // ⚠ STRIP BEFORE MASK, and unconditionally when capture is off.\n //\n // Before mask because content the customer never wanted to leave the\n // process should not be handed to a customer callback either — and\n // because a mask never called over a stripped field costs nothing, which\n // matters more here than in Python: this runs on the ONE event loop.\n //\n // Unconditional (not `if this._mask !== undefined`) because THIS is the\n // gate: `_applyMask` runs only when a mask was supplied, and the whole\n // defect being closed is that content escaped when nobody had opted into\n // anything.\n if (!this._traceContent) {\n const stripped = stripContentBatch(batch);\n if (stripped > 0) {\n debug(\n `traceContent is off — omitted ${stripped} content field(s) from ${batch.length} span(s)`,\n );\n }\n }\n\n if (this._mask !== undefined) {\n this._applyMask(batch);\n }\n\n debug(`Exporting batch of ${batch.length} spans`);\n\n // Export to all exporters — count once, not per exporter\n let batchExported = false;\n const anyDelivers = this._exporters.some((e) => e.countsAsDelivery !== false);\n // Spans that an exporter could not serialize: not sent, dropped at once.\n const unserializable = new Set<Span>();\n for (const exporter of this._exporters) {\n const decides = !anyDelivers || exporter.countsAsDelivery !== false;\n try {\n const result = await exporter.export(batch);\n // `shutdown()` stopped this batch and counted it as residue. Its late\n // answer changes no counter and re-queues nothing.\n if (flight.abandoned) return Round.Failed;\n if (!decides) continue;\n for (const span of exporter.takeUnserializable?.(batch) ?? []) unserializable.add(span);\n if (result === ExportResult.SUCCESS) {\n const ack = exporter.takeAck?.(batch) ?? null;\n if (!batchExported) {\n this._countDelivered(batch.length - unserializable.size, ack);\n batchExported = true;\n // Clear retry counts for successfully exported spans\n for (const span of batch) {\n this._retryCounts.delete(span.spanId);\n }\n }\n } else {\n this.failedExports++;\n }\n } catch (e) {\n if (flight.abandoned) return Round.Failed;\n if (!decides) continue;\n this.failedExports++;\n debug(`Export to ${exporter.name} failed: ${describeThrown(e)}`);\n }\n }\n if (unserializable.size > 0) this._recordDropped('unacknowledged', unserializable.size);\n\n // Audit #5: Re-queue failed batches with retry limit\n if (!batchExported) {\n let dropped = 0;\n const retryable = batch.filter(span => {\n if (unserializable.has(span)) return false;\n const count = (this._retryCounts.get(span.spanId) ?? 0) + 1;\n if (count > BatchSpanProcessor.MAX_RETRIES) {\n // retry-map drain site 2 of 3\n this._retryCounts.delete(span.spanId);\n // The count is once per SPAN IDENTITY, at exhaustion — never once\n // per attempt. A span re-queued twice and then dropped is ONE lost\n // span; keying on spanId is what makes that true.\n this._recordDropped('transport_refused');\n dropped++;\n return false;\n }\n this._retryCounts.set(span.spanId, count);\n return true;\n });\n if (retryable.length > 0) {\n this._queue.unshift(...retryable);\n debug(`Re-queued ${retryable.length} spans for retry (${batch.length - retryable.length} dropped after max retries)`);\n }\n if (dropped > 0) {\n // RULING §2: the PRIMARY remedy is a default-visible WARNING at the\n // moment of discard, naming the count and the reason — not a counter.\n // The log line survives the process; the counter does not, and on the\n // shutdown path there is no reader for it at all. `debug()` above is\n // suppressed at default level, which is why this is `warn()`.\n const now = Date.now();\n if (now - this._lastRefusalWarnAt > REFUSAL_WARN_WINDOW_MS) {\n this._lastRefusalWarnAt = now;\n const rounds = BatchSpanProcessor.MAX_RETRIES + 1;\n const perRound = this._requestsPerRound();\n warn(\n `${dropped} span(s) DISCARDED (reason=transport_refused) after ` +\n `${rounds} failed export rounds each` +\n (perRound !== undefined\n ? ` (up to ${rounds * perRound} HTTP requests: ${perRound} in each round)`\n : '') +\n ` — the endpoint is ` +\n `not accepting spans and the retry budget is spent. ` +\n `${this.droppedSpansByReason.transport_refused} span(s) discarded this way so far ` +\n `in this process. This data is gone; check the apiKey and the endpoint.`\n );\n }\n }\n }\n return batchExported ? Round.Delivered : Round.Failed;\n } finally {\n if (this._inFlight === flight) this._inFlight = null;\n this._flushing = false;\n }\n }\n}\n","/**\n * ID generation for traces and spans.\n *\n * Trace IDs: 32 lowercase hex characters (16 random bytes)\n * Span IDs: 16 lowercase hex characters (8 random bytes)\n *\n * Uses crypto.randomBytes for cryptographically secure randomness.\n */\n\nimport { randomBytes } from 'node:crypto';\n\nconst HEX_REGEX_32 = /^[0-9a-f]{32}$/;\nconst HEX_REGEX_16 = /^[0-9a-f]{16}$/;\n\nexport function generateTraceId(): string {\n return randomBytes(16).toString('hex');\n}\n\nexport function generateSpanId(): string {\n return randomBytes(8).toString('hex');\n}\n\nexport function generateAgentId(prefix?: string): string {\n const suffix = randomBytes(8).toString('hex');\n return prefix ? `${prefix}-${suffix}` : suffix;\n}\n\nexport function validateTraceId(id: string): boolean {\n return HEX_REGEX_32.test(id);\n}\n\nexport function validateSpanId(id: string): boolean {\n return HEX_REGEX_16.test(id);\n}\n","/**\n * No-op implementations for the disabled path.\n *\n * When tracing is disabled, all operations return these no-op objects\n * to maintain zero overhead. No allocations, no side effects.\n */\n\nimport { SpanKind, SpanStatus, type SpanPayload } from './types.js';\n\n/**\n * A frozen no-op span that silently ignores all operations.\n * Used when SDK is disabled to avoid overhead.\n */\nexport const NOOP_SPAN = Object.freeze({\n traceId: '00000000000000000000000000000000',\n spanId: '0000000000000000',\n parentSpanId: undefined,\n name: 'noop',\n kind: SpanKind.INTERNAL,\n startTime: '',\n startHrtime: 0,\n endTime: undefined,\n status: SpanStatus.UNSET,\n statusMessage: undefined,\n attributes: Object.freeze({}) as Record<string, unknown>,\n events: Object.freeze([]) as readonly [],\n links: Object.freeze([]) as readonly [],\n sessionId: undefined,\n agentId: undefined,\n agentName: undefined,\n semanticPhase: undefined,\n llmProvider: undefined,\n llmModel: undefined,\n llmPromptTokens: undefined,\n llmCompletionTokens: undefined,\n llmTotalTokens: undefined,\n llmCostUsd: undefined,\n toolName: undefined,\n toolSuccess: undefined,\n isEnded: true,\n durationMs: 0,\n\n setAttribute() { return this; },\n setAttributes() { return this; },\n setStatus() { return this; },\n addEvent() { return this; },\n addLink() { return this; },\n recordException() { return this; },\n setLlmFields() { return this; },\n setToolFields() { return this; },\n end() {},\n toPayload(): SpanPayload {\n return {\n traceId: this.traceId,\n spanId: this.spanId,\n name: this.name,\n kind: this.kind,\n startTime: this.startTime,\n status: this.status,\n attributes: {},\n events: [],\n links: [],\n };\n },\n});\n\nexport type NoopSpan = typeof NOOP_SPAN;\n","/**\n * Fix Runtime Configuration.\n *\n * Settings for the fix runtime including caching, refresh intervals,\n * A/B testing, and fix application behavior.\n *\n * Port of Python SDK's runtime/config.py adapted for Node.js patterns.\n */\n\n// ─── Runtime Configuration ──────────────────────────────────────────────────\n\nexport interface FixRuntimeConfig {\n /** Api URL, serving /v1/fixes/active (e.g., \"https://api.risicare.ai\") */\n apiEndpoint: string;\n\n /** API key for authentication (format: \"rsk-{random}\") */\n apiKey: string;\n\n /** Whether the fix runtime is enabled (default: true) */\n enabled?: boolean;\n\n /** Whether caching is enabled (default: true) */\n cacheEnabled?: boolean;\n\n /** Cache entry TTL in milliseconds (default: 300_000 = 5 min) */\n cacheTtlMs?: number;\n\n /** Maximum number of cache entries (default: 1000) */\n cacheMaxEntries?: number;\n\n /** Whether to auto-refresh fixes in background (default: true) */\n autoRefresh?: boolean;\n\n /** Background refresh interval in milliseconds (default: 60_000 = 1 min) */\n refreshIntervalMs?: number;\n\n /** Log but don't apply fixes (default: false) */\n dryRun?: boolean;\n\n /** Whether A/B testing bucketing is active (default: true) */\n abTestingEnabled?: boolean;\n\n /** Timeout for API requests in milliseconds (default: 1000) */\n timeoutMs?: number;\n\n /** Enable debug logging (default: false) */\n debug?: boolean;\n}\n\n/** Resolve config with defaults applied. */\nexport function resolveFixRuntimeConfig(\n config: FixRuntimeConfig,\n): Required<FixRuntimeConfig> {\n return {\n apiEndpoint: config.apiEndpoint,\n apiKey: config.apiKey,\n enabled: config.enabled ?? true,\n cacheEnabled: config.cacheEnabled ?? true,\n cacheTtlMs: config.cacheTtlMs ?? 300_000,\n cacheMaxEntries: config.cacheMaxEntries ?? 1000,\n autoRefresh: config.autoRefresh ?? true,\n refreshIntervalMs: config.refreshIntervalMs ?? 60_000,\n dryRun: config.dryRun ?? false,\n abTestingEnabled: config.abTestingEnabled ?? true,\n timeoutMs: config.timeoutMs ?? 1000,\n debug: config.debug ?? false,\n };\n}\n\n// ─── Fix Type ───────────────────────────────────────────────────────────────\n\nexport type FixType =\n | 'prompt'\n | 'parameter'\n | 'retry'\n | 'fallback'\n | 'guard'\n | 'routing'\n | 'tool';\n\n// ─── Active Fix ─────────────────────────────────────────────────────────────\n\nexport interface ActiveFix {\n fixId: string;\n deploymentId?: string;\n errorCode: string;\n fixType: FixType;\n config: Record<string, unknown>;\n trafficPercentage: number; // 0–100\n version: number;\n}\n\n/**\n * Check if a fix matches the given error code.\n *\n * Supports exact match and wildcard prefix matching:\n * - \"TOOL.EXECUTION.TIMEOUT\" matches \"TOOL.EXECUTION.TIMEOUT\"\n * - \"TOOL.EXECUTION.*\" matches \"TOOL.EXECUTION.TIMEOUT\", \"TOOL.EXECUTION.FAILURE\", etc.\n * - \"TOOL.*\" matches any TOOL error\n */\nexport function matchesError(fix: ActiveFix, errorCode: string): boolean {\n if (fix.errorCode === errorCode) {\n return true;\n }\n\n // Wildcard matching\n if (fix.errorCode.endsWith('*')) {\n const prefix = fix.errorCode.slice(0, -1);\n return errorCode.startsWith(prefix);\n }\n\n return false;\n}\n\n/**\n * Determine if fix should be applied based on A/B traffic percentage.\n *\n * Uses consistent hashing so the same session always gets the same\n * treatment (fix or no fix).\n */\nexport function shouldApply(fix: ActiveFix, sessionHash: number): boolean {\n if (fix.trafficPercentage >= 100) return true;\n if (fix.trafficPercentage <= 0) return false;\n\n const bucket = sessionHash % 100;\n return bucket < fix.trafficPercentage;\n}\n\n/**\n * Create an ActiveFix from an API response item.\n *\n * Handles both snake_case (server API) and camelCase field names.\n */\nexport function activeFixFromApiResponse(\n item: Record<string, unknown>,\n): ActiveFix {\n return {\n fixId: (item.id ?? item.fix_id ?? item.fixId ?? '') as string,\n deploymentId: (item.deployment_id ?? item.deploymentId ?? '') as string,\n errorCode: (item.error_code ?? item.errorCode ?? '') as string,\n fixType: (item.fix_type ?? item.fixType ?? 'prompt') as FixType,\n config: (item.config ?? {}) as Record<string, unknown>,\n trafficPercentage: (item.traffic_percentage ?? item.trafficPercentage ?? 100) as number,\n version: (item.version ?? 1) as number,\n };\n}\n","// ⚠ GENERATED FILE — DO NOT EDIT BY HAND.\n//\n// Source of truth: packages/risicare-sdk/src/risicare/runtime/_error_taxonomy.py\n// Generator: packages/risicare-sdk/scripts/gen_js_taxonomy.py\n// Core rules: packages/risicare-core/src/risicare_core/taxonomy.py (_KEYWORD_RULES)\n// Verify: just taxonomy (gen_js_taxonomy.py --check)\n//\n// F-SDKTAXFORK-001. This SDK cannot import `risicare_core.taxonomy` —\n// `risicare-core` is not published to npm. Rather than hand-maintain a second\n// copy of one rule (a divergence this campaign has measured four times), the\n// rule table and the canonical code set are generated from the Python source\n// and a rail fails when the two drift.\n//\n// Each pattern is a translation of the Python pattern for the `u` flag\n// (`.` -> `[^\\n]`, `\\b` -> a lookaround on [\\p{L}\\p{N}_]). The text is\n// lowercased before the match, as in Python, so no rule has a case flag.\n//\n// 154 canonical codes across 10 modules.\n\nexport const CANONICAL_ERROR_CODES: ReadonlySet<string> = new Set([\n \"COMMUNICATION.CONTENT.AMBIGUOUS\",\n \"COMMUNICATION.CONTENT.CORRUPTED\",\n \"COMMUNICATION.CONTENT.INCOMPATIBLE\",\n \"COMMUNICATION.CONTENT.MALFORMED\",\n \"COMMUNICATION.CONTENT.TOO_LARGE\",\n \"COMMUNICATION.DELIVERY.DELAYED\",\n \"COMMUNICATION.DELIVERY.DUPLICATED\",\n \"COMMUNICATION.DELIVERY.EXPIRED\",\n \"COMMUNICATION.DELIVERY.OUT_OF_ORDER\",\n \"COMMUNICATION.DELIVERY.UNDELIVERABLE\",\n \"COMMUNICATION.ROUTING.BROADCAST_STORM\",\n \"COMMUNICATION.ROUTING.LOOP\",\n \"COMMUNICATION.ROUTING.NO_ROUTE\",\n \"COMMUNICATION.ROUTING.PARTITION\",\n \"COMMUNICATION.ROUTING.WRONG_ROUTE\",\n \"CONSENSUS.AGREEMENT.INCONSISTENT\",\n \"CONSENSUS.AGREEMENT.QUORUM_FAILED\",\n \"CONSENSUS.AGREEMENT.REJECTED\",\n \"CONSENSUS.AGREEMENT.STALE_VOTE\",\n \"CONSENSUS.AGREEMENT.TIMEOUT\",\n \"CONSENSUS.CONFLICT.BIAS\",\n \"CONSENSUS.CONFLICT.CASCADING\",\n \"CONSENSUS.CONFLICT.DEADLOCK\",\n \"CONSENSUS.CONFLICT.RESOLUTION_REJECTED\",\n \"CONSENSUS.CONFLICT.UNRESOLVED\",\n \"CONSENSUS.VOTING.ABSTENTION_FLOOD\",\n \"CONSENSUS.VOTING.COERCED_VOTE\",\n \"CONSENSUS.VOTING.DUPLICATE_VOTE\",\n \"CONSENSUS.VOTING.INVALID_VOTE\",\n \"CONSENSUS.VOTING.SPLIT_VOTE\",\n \"COORDINATION.HANDOFF.DELAYED\",\n \"COORDINATION.HANDOFF.DUPLICATED\",\n \"COORDINATION.HANDOFF.INCOMPLETE\",\n \"COORDINATION.HANDOFF.LOST\",\n \"COORDINATION.HANDOFF.WRONG_RECIPIENT\",\n \"COORDINATION.SYNCHRONIZATION.CLOCK_SKEW\",\n \"COORDINATION.SYNCHRONIZATION.OUT_OF_ORDER\",\n \"COORDINATION.SYNCHRONIZATION.RACE_CONDITION\",\n \"COORDINATION.SYNCHRONIZATION.SPLIT_BRAIN\",\n \"COORDINATION.SYNCHRONIZATION.VERSION_MISMATCH\",\n \"COORDINATION.WORKFLOW.CYCLE\",\n \"COORDINATION.WORKFLOW.DEADLOCK\",\n \"COORDINATION.WORKFLOW.LIVELOCK\",\n \"COORDINATION.WORKFLOW.ORPHANED\",\n \"COORDINATION.WORKFLOW.STARVATION\",\n \"MEMORY.CONTEXT_WINDOW.DROPPED\",\n \"MEMORY.CONTEXT_WINDOW.EXCEEDED\",\n \"MEMORY.CONTEXT_WINDOW.FRAGMENTED\",\n \"MEMORY.CONTEXT_WINDOW.PRIORITY_ERROR\",\n \"MEMORY.RETRIEVAL.INCOMPLETE\",\n \"MEMORY.RETRIEVAL.NOT_FOUND\",\n \"MEMORY.RETRIEVAL.OUTDATED\",\n \"MEMORY.RETRIEVAL.TOO_MANY\",\n \"MEMORY.RETRIEVAL.WRONG_MATCH\",\n \"MEMORY.STATE.CORRUPTED\",\n \"MEMORY.STATE.INCONSISTENT\",\n \"MEMORY.STATE.LOST\",\n \"MEMORY.STATE.OVERFLOW\",\n \"MEMORY.STATE.STALE\",\n \"ORCHESTRATION.DELEGATION.CAPABILITY_MISMATCH\",\n \"ORCHESTRATION.DELEGATION.CIRCULAR_DELEGATION\",\n \"ORCHESTRATION.DELEGATION.EXCESSIVE_DEPTH\",\n \"ORCHESTRATION.DELEGATION.NO_AVAILABLE_AGENT\",\n \"ORCHESTRATION.DELEGATION.OVERLOADED_AGENT\",\n \"ORCHESTRATION.LIFECYCLE.CLEANUP_FAILED\",\n \"ORCHESTRATION.LIFECYCLE.CRASHED\",\n \"ORCHESTRATION.LIFECYCLE.HUNG\",\n \"ORCHESTRATION.LIFECYCLE.SPAWN_FAILED\",\n \"ORCHESTRATION.LIFECYCLE.ZOMBIE\",\n \"ORCHESTRATION.SCALING.OVERLOADED\",\n \"ORCHESTRATION.SCALING.QUOTA_EXCEEDED\",\n \"ORCHESTRATION.SCALING.SCALE_DOWN_FAILED\",\n \"ORCHESTRATION.SCALING.SCALE_UP_FAILED\",\n \"ORCHESTRATION.SCALING.UNDERUTILIZED\",\n \"OUTPUT.FORMAT.ENCODING\",\n \"OUTPUT.FORMAT.INVALID_JSON\",\n \"OUTPUT.FORMAT.MALFORMED\",\n \"OUTPUT.FORMAT.SCHEMA_VIOLATION\",\n \"OUTPUT.FORMAT.TRUNCATED\",\n \"OUTPUT.QUALITY.INCOMPLETE\",\n \"OUTPUT.QUALITY.IRRELEVANT\",\n \"OUTPUT.QUALITY.REPETITIVE\",\n \"OUTPUT.QUALITY.UNCLEAR\",\n \"OUTPUT.QUALITY.VERBOSE\",\n \"OUTPUT.SAFETY.BIAS\",\n \"OUTPUT.SAFETY.COPYRIGHT\",\n \"OUTPUT.SAFETY.HARMFUL_CONTENT\",\n \"OUTPUT.SAFETY.PII_LEAK\",\n \"OUTPUT.SAFETY.POLICY_VIOLATION\",\n \"PERCEPTION.CONTEXT.CONFLICTING\",\n \"PERCEPTION.CONTEXT.IRRELEVANT\",\n \"PERCEPTION.CONTEXT.MISSING\",\n \"PERCEPTION.CONTEXT.OVERFLOW\",\n \"PERCEPTION.CONTEXT.STALE\",\n \"PERCEPTION.INPUT.ENCODING\",\n \"PERCEPTION.INPUT.INJECTION\",\n \"PERCEPTION.INPUT.MALFORMED\",\n \"PERCEPTION.INPUT.SCHEMA_MISMATCH\",\n \"PERCEPTION.INPUT.TRUNCATED\",\n \"PERCEPTION.PARSING.DATE_FORMAT\",\n \"PERCEPTION.PARSING.JSON_INVALID\",\n \"PERCEPTION.PARSING.NUMBER_FORMAT\",\n \"PERCEPTION.PARSING.REFERENCE_BROKEN\",\n \"PERCEPTION.PARSING.XML_INVALID\",\n \"REASONING.DECISION.BIASED\",\n \"REASONING.DECISION.INDECISIVE\",\n \"REASONING.DECISION.OSCILLATING\",\n \"REASONING.DECISION.OVERCONFIDENT\",\n \"REASONING.DECISION.PREMATURE\",\n \"REASONING.HALLUCINATION.CAPABILITY\",\n \"REASONING.HALLUCINATION.CITATION\",\n \"REASONING.HALLUCINATION.ENTITY\",\n \"REASONING.HALLUCINATION.FACTUAL\",\n \"REASONING.HALLUCINATION.TEMPORAL\",\n \"REASONING.LOGIC.CIRCULAR\",\n \"REASONING.LOGIC.CONTRADICTION\",\n \"REASONING.LOGIC.INCOMPLETE\",\n \"REASONING.LOGIC.INVALID_INFERENCE\",\n \"REASONING.LOGIC.MISSING_PREMISE\",\n \"REASONING.PLANNING.INCOMPLETE\",\n \"REASONING.PLANNING.INFEASIBLE\",\n \"REASONING.PLANNING.SCOPE_CREEP\",\n \"REASONING.PLANNING.SUBOPTIMAL\",\n \"REASONING.PLANNING.UNSAFE\",\n \"RESOURCES.ACCESS.DENIED\",\n \"RESOURCES.ACCESS.EXPIRED\",\n \"RESOURCES.ACCESS.LOCKED\",\n \"RESOURCES.ACCESS.NOT_FOUND\",\n \"RESOURCES.ACCESS.REVOKED\",\n \"RESOURCES.CONTENTION.DEADLOCK\",\n \"RESOURCES.CONTENTION.OVERFLOW\",\n \"RESOURCES.CONTENTION.PRIORITY_INVERSION\",\n \"RESOURCES.CONTENTION.STARVATION\",\n \"RESOURCES.CONTENTION.THRASHING\",\n \"RESOURCES.QUOTA.ALLOCATION_FAILED\",\n \"RESOURCES.QUOTA.EXCEEDED\",\n \"RESOURCES.QUOTA.LEAK\",\n \"RESOURCES.QUOTA.STALE\",\n \"RESOURCES.QUOTA.UNFAIR_DISTRIBUTION\",\n \"TOOL.EXECUTION.CRASHED\",\n \"TOOL.EXECUTION.DEPENDENCY_FAILED\",\n \"TOOL.EXECUTION.RATE_LIMITED\",\n \"TOOL.EXECUTION.RESOURCE_EXHAUSTED\",\n \"TOOL.EXECUTION.TIMEOUT\",\n \"TOOL.INVOCATION.INVALID_ARGS\",\n \"TOOL.INVOCATION.MISSING_REQUIRED\",\n \"TOOL.INVOCATION.NOT_FOUND\",\n \"TOOL.INVOCATION.PERMISSION_DENIED\",\n \"TOOL.INVOCATION.TYPE_MISMATCH\",\n \"TOOL.RESULT.EMPTY\",\n \"TOOL.RESULT.ERROR_IN_RESULT\",\n \"TOOL.RESULT.PARTIAL\",\n \"TOOL.RESULT.UNEXPECTED_FORMAT\",\n \"TOOL.RESULT.UNPARSEABLE\",\n]);\n\nexport interface TaxonomyRule {\n re: RegExp;\n code: string;\n}\n\n/**\n * risicare-core's keyword rules (`classify_error`). Python applies them FIRST,\n * to the lowercased message only. Order matters: first match wins.\n */\nexport const CORE_RULES: readonly TaxonomyRule[] = [\n { re: new RegExp(\"json\", 'u'), code: \"PERCEPTION.PARSING.JSON_INVALID\" },\n { re: new RegExp(\"encoding\", 'u'), code: \"PERCEPTION.INPUT.ENCODING\" },\n { re: new RegExp(\"injection\", 'u'), code: \"PERCEPTION.INPUT.INJECTION\" },\n { re: new RegExp(\"malformed\", 'u'), code: \"PERCEPTION.INPUT.MALFORMED\" },\n { re: new RegExp(\"hallucin\", 'u'), code: \"REASONING.HALLUCINATION.FACTUAL\" },\n { re: new RegExp(\"contradict\", 'u'), code: \"REASONING.LOGIC.CONTRADICTION\" },\n { re: new RegExp(\"timeout\", 'u'), code: \"TOOL.EXECUTION.TIMEOUT\" },\n { re: new RegExp(\"rate[^\\\\n]?limit\", 'u'), code: \"TOOL.EXECUTION.RATE_LIMITED\" },\n { re: new RegExp(\"permission\", 'u'), code: \"TOOL.INVOCATION.PERMISSION_DENIED\" },\n { re: new RegExp(\"context[^\\\\n]+overflow\", 'u'), code: \"MEMORY.CONTEXT_WINDOW.EXCEEDED\" },\n { re: new RegExp(\"state[^\\\\n]+corrupt\", 'u'), code: \"MEMORY.STATE.CORRUPTED\" },\n { re: new RegExp(\"pii\", 'u'), code: \"OUTPUT.SAFETY.PII_LEAK\" },\n { re: new RegExp(\"deadlock\", 'u'), code: \"COORDINATION.WORKFLOW.DEADLOCK\" },\n { re: new RegExp(\"undeliverable\", 'u'), code: \"COMMUNICATION.DELIVERY.UNDELIVERABLE\" },\n { re: new RegExp(\"crash\", 'u'), code: \"ORCHESTRATION.LIFECYCLE.CRASHED\" },\n { re: new RegExp(\"quorum\", 'u'), code: \"CONSENSUS.AGREEMENT.QUORUM_FAILED\" },\n { re: new RegExp(\"quota[^\\\\n]+exceed\", 'u'), code: \"RESOURCES.QUOTA.EXCEEDED\" },\n];\n\n/** Order matters: first match wins, most specific first. */\nexport const SUPPLEMENTAL_RULES: readonly TaxonomyRule[] = [\n { re: new RegExp(\"timeout|timedout|aborted\", 'u'), code: \"TOOL.EXECUTION.TIMEOUT\" },\n { re: new RegExp(\"rate[^\\\\n]?limit|(?<![\\\\p{L}\\\\p{N}_])429(?![\\\\p{L}\\\\p{N}_])|too many requests\", 'u'), code: \"TOOL.EXECUTION.RATE_LIMITED\" },\n { re: new RegExp(\"connection|econnrefused|econnreset|enotfound|fetch failed|unreachable|broken pipe\", 'u'), code: \"TOOL.EXECUTION.DEPENDENCY_FAILED\" },\n { re: new RegExp(\"(?<![\\\\p{L}\\\\p{N}_])auth|unauthorized|forbidden|permission|(?<![\\\\p{L}\\\\p{N}_])401(?![\\\\p{L}\\\\p{N}_])|(?<![\\\\p{L}\\\\p{N}_])403(?![\\\\p{L}\\\\p{N}_])\", 'u'), code: \"TOOL.INVOCATION.PERMISSION_DENIED\" },\n { re: new RegExp(\"json|syntaxerror|unexpected token|decodeerror\", 'u'), code: \"PERCEPTION.PARSING.JSON_INVALID\" },\n];\n\nexport const GENERIC_FALLBACK = \"TOOL.EXECUTION.CRASHED\";\n","/**\n * Single source of truth for the SDK version on the wire.\n *\n * F-720/F-351: prior to this file, two separate `SDK_VERSION` constants\n * existed in `exporters/http.ts` (\"0.1.1\") and `runtime/loader.ts` (\"0.1.3\"),\n * while `package.json` declared \"0.4.0\". Three different versions on the\n * wire confused customer telemetry and dashboard SDK-version-cohort filters.\n *\n * This file MUST stay in lock-step with the `version` field in\n * `packages/risicare-sdk-js/package.json`. Bumping the version is a\n * two-file edit (`package.json` + this file). The `prepublishOnly` script\n * verifies the match before any npm publish.\n *\n * Kept as a plain TS constant (not a runtime read of package.json) because:\n * 1. tsup bundles to ESM AND CJS for both Node and Edge; runtime fs\n * reads of package.json break in bundled-Edge environments.\n * 2. A constant inlines at tree-shake time, so no extra bytes shipped.\n * 3. The version is read in the hot path (every export); a static value\n * avoids per-call import-meta-resolve overhead.\n */\nexport const SDK_VERSION = '0.9.0';\n","/**\n * HTTP exporter for sending spans to the Risicare gateway.\n *\n * Uses native fetch (Node.js 18+), with:\n * - Automatic retry with exponential backoff\n * - Circuit breaker with half-open probe state\n * - Never follows a redirect; a 3xx or a 2xx without a Risicare ack is a FAILURE\n * - Gzip compression for large payloads\n * - Bearer token authentication\n */\n\nimport type { Span } from '../span.js';\nimport { ExportResult, type AckCounts, type SpanExporter } from './base.js';\nimport { debug, warn } from '../utils/log.js';\nimport { SDK_VERSION } from '../version.js';\nimport { hasCredentials, safeUrl, scrubText } from '../utils/scrub.js';\n\nexport interface HttpExporterOptions {\n endpoint: string;\n apiKey?: string;\n projectId?: string;\n environment?: string;\n timeoutMs?: number;\n maxRetries?: number;\n compress?: boolean;\n}\n\n/**\n * F-SDK503-001 · A CAPACITY REFUSAL IS NOT A SICK SERVER.\n *\n * ⚠ MEASURED ON THE PUBLISHED ARTEFACT (`risicare@0.5.0` from npm, clean install). The bundle\n * contains ZERO occurrences of `accepted`, one of `\"429\"` (which is TOOL-error classification,\n * not HTTP), and its export path is `if (response.status < 300) return SUCCESS` — so 429, 503\n * and 500 are byte-identical to it and `Retry-After` is never read. The Python twin measured\n * identically: `fix-workstream/perf/a3/sdk_python_refusal_probe.py`.\n *\n * ⚠ THE BREAKER IS THE DANGEROUS HALF. Five consecutive failing exports open it for 60 s, and\n * under sustained overload five refusals arrive in well under a second — so the SDK discards\n * everything the application emits for the next minute. A `503 QUEUE_NEAR_CAPACITY` is a\n * HEALTHY gateway shedding load whose backlog drains on its own; treating it as a dead sink\n * turns a transient server-side shed into total client-side loss.\n *\n * ⚠ THIS DOES NOT MAKE ANYTHING RETRY FOREVER. `maxRetries` still bounds the attempts and the\n * batch is still dropped when they are spent. A genuine 500 still opens the breaker — that is\n * the control arm, and losing it would turn our outage into the customer's retry loop.\n */\nconst CAPACITY_REFUSAL_STATUSES: ReadonlySet<number> = new Set([429, 503]);\n\n/** Ceiling on an honoured `Retry-After`, in ms. Matches the Python twin's 10 s. */\nconst RETRY_AFTER_CEILING_MS = 10_000;\n\n/** Backoff for a refusal carrying no `Retry-After` (1 s, 2 s, 4 s) — an order of magnitude\n * above the generic 100/200/400 ms ladder, because a queue needs time to drain. */\nconst REFUSAL_BACKOFF_BASE_MS = 1_000;\n\n/** Sentinel for \"refused, but the server named no delay\". */\nconst REFUSAL_NO_HINT = -1;\n\n/**\n * ⚠ A MISROUTE IS A CONFIGURATION ERROR, NOT AN OUTAGE (0.7.0). Two answers mean that the\n * request did not reach the Risicare ingest gateway: a 3xx, and a 2xx whose body is not a\n * Risicare ack. Measured: the old default `https://app.risicare.ai` is the dashboard, and it\n * answers `POST /v1/spans` with `307 -> /login`. Through 0.6.0 `fetch` followed that\n * redirect, got the login page as an HTML 200, and `checkAck` returned SUCCESS. Now:\n * - `fetch` runs with `redirect: 'manual'`, so a 3xx comes back as the answer;\n * - the retry loop stops at the first misroute — no backoff, no second attempt;\n * - the failure COUNTS toward the circuit breaker, as a genuine failure does: 5 requests,\n * then the breaker opens, then one probe per cooldown (60 s);\n * - one warning names the endpoint and the answer, at most once per 5 minutes.\n * A capacity refusal (429/503) is different: it does not count toward the breaker.\n * Python twin: `exporters/http.py`, the block above `HttpExporter`.\n */\nconst MISROUTE_WARN_WINDOW_MS = 300_000;\n\n/**\n * An AUTH REFUSAL cannot change on a retry: the same key gets the same answer. So\n * `export()` sends it once (no retry inside that call). The batch processor still\n * re-queues the batch a bounded number of times, and the circuit breaker counts the\n * failure as before. The Python twin uses the same two statuses.\n */\nconst AUTH_REFUSAL_STATUSES: ReadonlySet<number> = new Set([401, 403]);\n\n/**\n * The WARNING for a failed export (\"spans are NOT reaching ...\") is written at the\n * first failure of an outage, and at most once in this window. Python twin:\n * `_failure_warn_window` (300 s).\n */\nconst FAILURE_WARN_WINDOW_MS = 300_000;\n\n/**\n * The state of one `export()` call: the answer of its last attempt and its cancel signal.\n * It is per call, not on the instance, so that concurrent calls (two processors that share\n * one exporter) cannot read each other's answers across an `await`.\n */\ninterface Call {\n cancel: AbortController;\n /** F-SDK503-001: a CAPACITY REFUSAL. `null` = none; `REFUSAL_NO_HINT` = no `Retry-After`. */\n refusalAfterMs: number | null;\n /** A MISROUTE: a short description of the answer. `null` = none. */\n misroute: string | null;\n /** The answer cannot change on a retry (an ack of 0 and 0). */\n noRetry: boolean;\n /** The HTTP status of the last answer. `null` = no answer. For the WARNING and the retry loop. */\n status: number | null;\n /** The error code or class when the last attempt got no answer. `null` = none. */\n error: string | null;\n}\n\nexport class HttpExporter implements SpanExporter {\n readonly name = 'http';\n\n private readonly _endpoint: string;\n private readonly _apiKey: string | undefined;\n private readonly _projectId: string | undefined;\n private readonly _environment: string | undefined;\n private readonly _timeoutMs: number;\n private readonly _maxRetries: number;\n private readonly _compress: boolean;\n\n // Circuit breaker (CON-201 / B-16). Threshold and cooldown sized for\n // a \"30-second prod restart\" scenario: with default 1s batch flush a\n // 5-failure threshold opens the circuit ~5s into an outage and the 60s\n // cooldown gives the gateway time to come back before the half-open\n // probe fires. Lower numbers (was 3@30s) tripped on transient blips.\n private _consecutiveFailures = 0;\n private _lastMisrouteWarnAt = -Infinity;\n private _lastFailureWarnAt = -Infinity;\n /**\n * The kind of failure that the last outage WARNING named ('auth', 'http', 'none',\n * 'unknown'). `null` after a success. A new kind in the same outage writes one more\n * WARNING, also inside the window.\n */\n private _failureKind: string | null = null;\n /** The endpoint as a log line may show it: no userinfo, no query (see `safeUrl`). */\n private readonly _safeEndpoint: string;\n /** The endpoint holds userinfo. `fetch` refuses such a URL. */\n private readonly _endpointHasCredentials: boolean;\n /** The calls in progress, by their batch, so that `abort(spans)` stops the right one. */\n private readonly _calls = new Map<Span[], Call>();\n /** The ack of each finished call, by its batch. Read once by `takeAck(spans)`. */\n private readonly _acks = new WeakMap<Span[], AckCounts>();\n /** The spans of each finished call that could not be serialized, by its batch. */\n private readonly _unserializable = new WeakMap<Span[], Span[]>();\n private _circuitOpenUntil = 0;\n private readonly _circuitBreakerThreshold = 5;\n private readonly _circuitBreakerCooldownMs = 60_000;\n\n constructor(options: HttpExporterOptions) {\n this._endpoint = options.endpoint.replace(/\\/+$/, '');\n this._apiKey = options.apiKey;\n this._projectId = options.projectId;\n this._environment = options.environment;\n this._timeoutMs = options.timeoutMs ?? 5000;\n this._maxRetries = options.maxRetries ?? 3;\n this._compress = options.compress ?? false;\n this._safeEndpoint = safeUrl(this._endpoint);\n this._endpointHasCredentials = hasCredentials(this._endpoint);\n }\n\n /**\n * Network or error text for a log line: the endpoint as `safeUrl` gives it, and no\n * form of the API key (`utils/scrub.ts`).\n */\n private _scrub(text: unknown, limit = 200): string {\n let out: string;\n try {\n out = text instanceof Error ? `${text.name}: ${text.message}` : String(text);\n } catch {\n out = typeof text;\n }\n if (this._safeEndpoint !== this._endpoint) out = out.split(this._endpoint).join(this._safeEndpoint);\n return scrubText(out, [this._apiKey], limit);\n }\n\n /** Hide the key from `util.inspect` and `console.log` of the exporter. */\n [Symbol.for('nodejs.util.inspect.custom')](): string {\n return `HttpExporter { endpoint: '${this._safeEndpoint}' }`;\n }\n\n /** The most requests that one `export()` call sends (`maxRetries`). */\n get attemptsPerExport(): number {\n return this._maxRetries;\n }\n\n /**\n * Returns the counts of the ack that the `export()` call for `spans` received, and clears\n * them. The answer is kept per batch, not on the instance: two processors that share this\n * exporter cannot read each other's ack across an `await`.\n */\n takeAck(spans: Span[]): AckCounts | null {\n const ack = this._acks.get(spans) ?? null;\n this._acks.delete(spans);\n return ack;\n }\n\n /** Returns the spans of `spans` that could not be serialized and were not sent, and clears them. */\n takeUnserializable(spans: Span[]): Span[] {\n const bad = this._unserializable.get(spans) ?? [];\n this._unserializable.delete(spans);\n return bad;\n }\n\n /**\n * Cancel the `export()` call for `spans` (all calls when `spans` is not given): its\n * request, its retries and its backoff sleep. The batch processor calls it when\n * `shutdown()` abandons the batch, so that the call does not keep the process alive. The\n * cancelled call returns FAILURE, changes no counter (the circuit breaker included) and\n * logs no WARNING.\n */\n abort(spans?: Span[]): void {\n if (spans !== undefined) this._calls.get(spans)?.cancel.abort();\n else for (const call of this._calls.values()) call.cancel.abort();\n }\n\n /**\n * Send one batch. The limits are the request timeout and `maxRetries`.\n *\n * ⚠ NO CALLER BUDGET. `flush(timeoutMs)` only stops WAITING at its deadline; it never\n * cuts a request that is already sent. A short flush budget that cut the request made a\n * healthy, slow server look like a failure: the span used a retry, the breaker moved, and\n * the server stored the same spans again. Only `abort()` stops the call, and only\n * `shutdown()` calls it.\n */\n async export(spans: Span[]): Promise<ExportResult> {\n if (spans.length === 0) return ExportResult.SUCCESS;\n const call: Call = {\n cancel: new AbortController(),\n refusalAfterMs: null,\n misroute: null,\n noRetry: false,\n status: null,\n error: null,\n };\n this._calls.set(spans, call);\n try {\n return await this._export(spans, call);\n } finally {\n this._calls.delete(spans);\n }\n }\n\n private async _export(spans: Span[], call: Call): Promise<ExportResult> {\n const cancelled = call.cancel.signal;\n // Serialize each span alone. A span that cannot be serialized (a BigInt, a circular\n // value) is not sent; the batch processor drops it as `unacknowledged`. Through 0.7.1\n // one such span made the whole batch fail every round, and the WARNING blamed the\n // endpoint.\n const parts: string[] = [];\n const bad: Span[] = [];\n let errorClass = '';\n for (const span of spans) {\n try {\n parts.push(JSON.stringify(span.toPayload()));\n } catch (e) {\n bad.push(span);\n errorClass ||= e instanceof Error ? e.name : typeof e;\n }\n }\n if (bad.length > 0) {\n this._unserializable.set(spans, bad);\n warn(\n `Risicare: ${bad.length} of ${spans.length} span(s) in this batch could not be ` +\n `serialized (${errorClass}), for example an attribute with a BigInt or a circular ` +\n `reference. They are not sent and are counted as dropped (reason=unacknowledged).`,\n );\n }\n if (parts.length === 0) return ExportResult.SUCCESS;\n const payload =\n `{\"spans\":[${parts.join(',')}]` +\n (this._projectId ? `,\"projectId\":${JSON.stringify(this._projectId)}` : '') +\n (this._environment ? `,\"environment\":${JSON.stringify(this._environment)}` : '') +\n '}';\n\n // Circuit breaker: skip if open\n const now = Date.now();\n let isHalfOpen = false;\n if (this._consecutiveFailures >= this._circuitBreakerThreshold) {\n if (now < this._circuitOpenUntil) {\n return ExportResult.FAILURE;\n }\n // Cooldown expired — probe with single request (Audit #7: half-open state)\n isHalfOpen = true;\n }\n\n // Half-open: single probe request. Normal: full retry loop.\n const maxAttempts = isHalfOpen ? 1 : this._maxRetries;\n let attempts = 0;\n\n // Retry loop with exponential backoff\n for (let attempt = 0; attempt < maxAttempts; attempt++) {\n // F-SDK503-001: cleared before EVERY attempt, so a refusal recorded on attempt 1 cannot\n // be read as a refusal on attempt 2 (`_sendRequest` swallows transport errors and\n // returns FAILURE without touching the field).\n call.refusalAfterMs = null;\n call.misroute = null;\n call.noRetry = false;\n call.status = null;\n call.error = null;\n attempts++;\n const result = await this._sendRequest(payload, parts.length, call, spans);\n // Cancelled by `abort()`: no counter, no breaker step, no WARNING.\n if (cancelled.aborted) {\n this._acks.delete(spans);\n return ExportResult.FAILURE;\n }\n\n if (result === ExportResult.SUCCESS) {\n this._consecutiveFailures = 0;\n this._failureKind = null;\n return result;\n }\n\n // A misroute, or an ack of 0 and 0, gets the same answer on every attempt. Do not\n // retry it.\n if (call.misroute !== null || call.noRetry) break;\n // A 401 or 403 cannot change on a retry either.\n if (call.status !== null && AUTH_REFUSAL_STATUSES.has(call.status)) break;\n\n // Backoff. A generic failure is usually a blip worth retrying at once (100/200/400 ms);\n // a CAPACITY REFUSAL waits on the SERVER's terms when the server names them, and an\n // order of magnitude longer when it does not.\n if (attempt < maxAttempts - 1) {\n const refusal = call.refusalAfterMs;\n const delay =\n refusal === null\n ? 100 * Math.pow(2, attempt)\n : refusal === REFUSAL_NO_HINT\n ? REFUSAL_BACKOFF_BASE_MS * Math.pow(2, attempt)\n : refusal;\n await sleep(delay, cancelled);\n if (cancelled.aborted) return ExportResult.FAILURE;\n }\n }\n\n // ⚠ F-SDK503-001 — A CAPACITY REFUSAL DOES NOT COUNT TOWARD THE BREAKER.\n //\n // ⚠ THE COUNTER IS LEFT UNTOUCHED, NOT RESET. A refusal is not evidence of health either:\n // resetting would let an alternating 500/503 sequence hold the breaker open-ended at four.\n // It neither advances nor clears.\n if (call.refusalAfterMs !== null) {\n warn(\n `Risicare: the ingest endpoint refused this batch for capacity (HTTP 429/503) after ` +\n `${attempts} attempt(s). This is a healthy server shedding load, not an outage. ` +\n `This export of the batch failed; the circuit breaker does not count it. Reduce ` +\n `batch size or export rate if it persists.`\n );\n return ExportResult.FAILURE;\n }\n\n const misroute = call.misroute;\n if (misroute !== null && Date.now() - this._lastMisrouteWarnAt > MISROUTE_WARN_WINDOW_MS) {\n this._lastMisrouteWarnAt = Date.now();\n warn(\n `Risicare: spans are NOT reaching ${this._safeEndpoint}. It answered POST /v1/spans with ` +\n `${misroute}. That is not the Risicare ingest gateway, so the endpoint is probably ` +\n `wrong (for example the dashboard URL instead of the ingest gateway URL). The SDK ` +\n `does not follow redirects, and this batch is counted as NOT delivered. Set ` +\n `endpoint or RISICARE_ENDPOINT to the ingest gateway URL.`,\n );\n }\n\n // All retries failed — update circuit breaker\n this._consecutiveFailures++;\n\n // The first failure of an outage writes one WARNING, at most once in the window\n // (as in Python). A misroute and an ack of 0 and 0 have their own WARNING. A new\n // kind of failure in the same outage (for example a 401, then no answer) writes one\n // more WARNING, also inside the window. The WARNING names the last HTTP status, or\n // the error code when there was no answer. It never names the key or the response\n // body, and names the API key as a cause only for a 401 or 403.\n if (misroute === null && !call.noRetry) {\n const status = call.status;\n const kind =\n status !== null && AUTH_REFUSAL_STATUSES.has(status)\n ? 'auth'\n : status !== null\n ? 'http'\n : call.error !== null\n ? 'none'\n : 'unknown';\n let write = false;\n if (this._consecutiveFailures === 1 || this._failureKind === null) {\n if (Date.now() - this._lastFailureWarnAt > FAILURE_WARN_WINDOW_MS) {\n this._lastFailureWarnAt = Date.now();\n write = true;\n }\n this._failureKind = kind;\n } else if (kind !== this._failureKind) {\n this._failureKind = kind;\n write = true;\n }\n if (write) this._warnOutage(kind, status, call.error);\n }\n if (this._consecutiveFailures >= this._circuitBreakerThreshold) {\n this._circuitOpenUntil = Date.now() + this._circuitBreakerCooldownMs;\n warn(\n `HTTP exporter circuit breaker opened after ${this._consecutiveFailures} failures. ` +\n `Cooldown: ${this._circuitBreakerCooldownMs / 1000}s`\n );\n }\n\n return ExportResult.FAILURE;\n }\n\n /** The outage WARNING for one kind of failure. */\n private _warnOutage(kind: string, status: number | null, error: string | null): void {\n const where = `Risicare: spans are NOT reaching ${this._safeEndpoint}`;\n const tail = 'Tracing continues, but the SDK drops the spans that it cannot send.';\n if (kind === 'auth') {\n warn(\n `${where}: it answered HTTP ${status}. The endpoint refused the API key. Check the ` +\n `apiKey (or RISICARE_API_KEY) and the project it belongs to. ${tail}`,\n );\n } else if (kind === 'http') {\n warn(\n `${where}: it answered HTTP ${status}. The server did not take the batch. Check the ` +\n `endpoint and the server. ${tail} Set debug: true to see each attempt.`,\n );\n } else if (kind === 'none' && this._endpointHasCredentials) {\n warn(\n `${where}: no answer (${error}). The endpoint URL holds credentials (a user name ` +\n `or a password before the host), and fetch does not send a request to such a URL. ` +\n `Remove the credentials from the endpoint URL. ${tail}`,\n );\n } else if (kind === 'none') {\n warn(\n `${where}: no answer (${error}). The endpoint cannot be reached, or it did not ` +\n `answer in time. Check the endpoint and the network. ${tail} Set debug: true to ` +\n `see each attempt.`,\n );\n } else {\n warn(\n `${where}: the export failed. Common causes: an invalid apiKey or an unreachable ` +\n `endpoint. ${tail} Set debug: true to see each attempt.`,\n );\n }\n }\n\n /** Record a MISROUTE for the retry loop and the breaker. Always returns FAILURE. */\n private _noteMisroute(call: Call, answer: string): ExportResult {\n // The answer holds network text (a redirect target, a Content-Type): scrubbed here,\n // once, for the debug line below and for the WARNING.\n call.misroute = this._scrub(answer, 300);\n debug(`Ingest misroute: ${call.misroute}`);\n return ExportResult.FAILURE;\n }\n\n /**\n * Record a CAPACITY REFUSAL for the retry loop. Returns true if it was one.\n *\n * `Retry-After` is honoured only in its delta-seconds form (RFC 9110 §10.2.3 also permits an\n * HTTP-date); anything else falls back to our own backoff rather than guessing at a date\n * parse.\n */\n private _noteRefusal(call: Call, status: number, retryAfterRaw: string | null): boolean {\n if (!CAPACITY_REFUSAL_STATUSES.has(status)) return false;\n let delay = REFUSAL_NO_HINT;\n if (retryAfterRaw) {\n const secs = Number(retryAfterRaw);\n if (Number.isFinite(secs) && secs >= 0) {\n delay = Math.min(secs * 1000, RETRY_AFTER_CEILING_MS);\n }\n }\n call.refusalAfterMs = delay;\n debug(`Ingest refused for capacity: HTTP ${status} (Retry-After=${this._scrub(retryAfterRaw)})`);\n return true;\n }\n\n private async _sendRequest(\n body: string,\n spansSent: number,\n call: Call,\n spans: Span[],\n ): Promise<ExportResult> {\n const cancelled = call.cancel.signal;\n const timeoutMs = this._timeoutMs;\n const url = `${this._endpoint}/v1/spans`;\n const headers: Record<string, string> = {\n 'Content-Type': 'application/json',\n 'User-Agent': `risicare-js/${SDK_VERSION} node/${process.version}`,\n // F-SDKVER-001 parity. Python's ingest exporter has always sent\n // `X-Risicare-SDK-Version`; JS sent only a User-Agent, so the two SDKs\n // disagreed about how a client identifies itself. A parser-free header is\n // strictly easier for the gateway to consume than picking a version out of\n // a UA string.\n 'X-Risicare-SDK-Version': SDK_VERSION,\n };\n if (this._apiKey) {\n headers['Authorization'] = `Bearer ${this._apiKey}`;\n }\n\n let payload: string | Uint8Array = body;\n\n if (this._compress && payload.length > 1024) {\n try {\n const { gzipSync } = await import('node:zlib');\n payload = gzipSync(Buffer.from(payload));\n headers['Content-Encoding'] = 'gzip';\n } catch (e) {\n // Audit #16: log compression failures instead of silently swallowing\n debug(`Gzip compression failed, sending uncompressed: ${this._scrub(e)}`);\n }\n }\n\n // ⚠ ONE TIMER FOR THE WHOLE REQUEST, BODY READ INCLUDED (A4). Through 0.7.1 the timer\n // was cleared as soon as `fetch` resolved, which is when the HEADERS arrive. A server\n // that sent 200 headers and then stalled the body held `checkAck` for 301 s (the\n // runtime's own body timeout). And the `catch` path never cleared the timer, so each\n // refused attempt kept the process alive for the full timeout. The timer now covers\n // the body read and is cleared in `finally` on every path.\n const controller = new AbortController();\n const timeoutId = setTimeout(() => controller.abort(), timeoutMs);\n // `abort()` on the exporter stops this request too.\n const onCancel = () => controller.abort();\n cancelled.addEventListener('abort', onCancel, { once: true });\n if (cancelled.aborted) controller.abort();\n try {\n const response = await fetch(url, {\n method: 'POST',\n headers,\n body: payload,\n signal: controller.signal,\n // Never follow: a redirect is a misroute (see MISROUTE_WARN_WINDOW_MS). Node returns\n // the 3xx itself; a browser-like runtime returns type 'opaqueredirect' with status 0.\n redirect: 'manual',\n });\n call.status = response.status;\n\n const redirected = response.type === 'opaqueredirect';\n if (redirected || (response.status >= 300 && response.status < 400)) {\n const location = response.headers?.get?.('Location');\n // The target comes from the server, and it can contain the API key.\n const target = location ? this._scrub(location, 1000) : 'no Location header';\n return this._noteMisroute(call, `HTTP ${response.status || '3xx'}, a redirect to ${target}`);\n }\n if (response.status >= 200 && response.status < 300) {\n const ack = await checkAck(response, spansSent, (t) => this._scrub(t, 1000));\n if (ack === null) {\n // The timer ended the body read: a timeout, not a misroute.\n if (controller.signal.aborted) {\n call.status = null;\n call.error = `timeout after ${timeoutMs} ms`;\n debug(`HTTP export timeout: the ack body did not arrive within ${timeoutMs} ms`);\n return ExportResult.TIMEOUT;\n }\n return this._noteMisroute(\n call,\n `HTTP ${response.status} and a body that is not a Risicare ack ` +\n `(content-type: ${response.headers?.get?.('Content-Type') || 'none'})`,\n );\n }\n if (ack.result === ExportResult.SUCCESS) this._acks.set(spans, ack.counts);\n if (ack.final) call.noRetry = true;\n return ack.result;\n } else if (response.status === 408 || response.status === 504) {\n debug(`HTTP export timeout: ${response.status}`);\n return ExportResult.TIMEOUT;\n }\n // F-SDK503-001 — still a FAILURE for the return type (the batch did not land), but the\n // loop and the breaker treat it differently.\n this._noteRefusal(call, response.status, response.headers.get('Retry-After'));\n debug(`HTTP export failed: ${response.status}`);\n return ExportResult.FAILURE;\n } catch (e) {\n // The cause code tells a refused port, a DNS failure and a reset apart (fetch\n // wraps each of them in the same TypeError). A class name only: never a message.\n const cause = e instanceof Error ? (e as Error & { cause?: { code?: unknown } }).cause : undefined;\n call.error = controller.signal.aborted\n ? `timeout after ${timeoutMs} ms`\n : typeof cause?.code === 'string'\n ? cause.code\n : e instanceof Error\n ? e.name\n : 'Error';\n debug(`HTTP export error: ${this._scrub(e)}`);\n return ExportResult.FAILURE;\n } finally {\n clearTimeout(timeoutId);\n cancelled.removeEventListener('abort', onCancel);\n }\n }\n\n shutdown(): void {\n // Native fetch doesn't need cleanup\n }\n}\n\n/** Sleep for `ms`, or less when `signal` aborts. The timer never outlives the sleep. */\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n return new Promise((resolve) => {\n if (signal?.aborted) return resolve();\n const done = () => {\n clearTimeout(timer);\n signal?.removeEventListener('abort', done);\n resolve();\n };\n const timer = setTimeout(done, ms);\n signal?.addEventListener('abort', done, { once: true });\n });\n}\n\n/** An integer that is not a `boolean` (JS `typeof true === 'boolean'`, but be explicit). */\nfunction asCount(v: unknown): number | undefined {\n return typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : undefined;\n}\n\n/**\n * Decide SUCCESS/FAILURE from a 2xx response, reading the ACK body. Returns `null` when the\n * body is not a well-formed Risicare ack. The caller records that as a misroute, or as a\n * timeout when the request timer stopped the body read.\n *\n * ⚠ F-SDKACKBLIND-001. A 2xx is NOT delivery. The gateway answers\n * `StatusCode::OK` unconditionally on the ingest route (`routes/spans.rs`) and\n * reports per-span outcomes in the BODY — `{ accepted, rejected, errors[] }`,\n * camelCase, `errors` omitted when empty. Every span in a batch can be rejected\n * (bad trace-id hex, attribute-cardinality cap, clamps) and the status is still\n * 200. Before 0.5.1 this returned SUCCESS on any status below 300 and never\n * opened the body, so total loss looked like a clean export — and the retry, the\n * circuit breaker and `failedExports` all stayed silent.\n *\n * ⚠ ONLY A WELL-FORMED ACK IS SUCCESS (0.7.0). The ack is a JSON object with\n * non-negative integer `accepted` and `rejected`; other fields are ignored.\n * Through 0.6.0 any other body returned SUCCESS, to fail safe against a proxy\n * that rewrites bodies. That hid TOTAL loss: the login page that the dashboard\n * host redirects to is an HTML 200. Any other 2xx body is now a misroute: a\n * FAILURE, with no retry. The cost, stated: behind a proxy that rewrites bodies,\n * stored spans are counted as lost, and the batch processor can send them again.\n * That failure is loud.\n *\n * ⚠ A REJECTION IS AN ANSWER, NOT A FAILURE (after 0.7.1). A well-formed ack with\n * `rejected` > 0 is SUCCESS for the transport, also when `accepted` is 0: span-level\n * rejects are permanent, so a retry sends the same spans to the same refusal. Through\n * 0.7.1 an ack with `accepted` 0 was a FAILURE: the batch went to the server up to 12\n * times, the circuit breaker moved, and the last WARNING blamed the API key. A PARTIAL\n * rejection was already not a failure: retrying the whole batch would duplicate the\n * accepted spans. The result carries the counts, so that the batch processor adds\n * `accepted` to `exportedSpans` and `rejected` to `rejectedSpans`, and `flush()` then\n * returns `false`. One WARNING gives the counts and the reasons.\n *\n * ⚠ AN ACK OF 0 AND 0 FOR A NON-EMPTY BATCH IS A FAILURE (after 0.7.1). The gateway's\n * ack accounts for every span it got (accepted + rejected = spans sent). An ack\n * that counts no span is not a delivery. Through 0.7.1 it was SUCCESS, and the\n * whole batch was counted as exported. It is not retried inside the same\n * `export()` call, because the answer cannot change. The batch processor treats it\n * as any other failure.\n *\n * Other ack counts are not trusted here either: the batch processor clamps them to\n * the batch size (see `BatchSpanProcessor`).\n *\n * A WARNING names the reasons only: the distinct `errors[].error` strings (or\n * `errorMessage` when there are none), at most 3. Each one is made one printable\n * line (control characters become spaces) and then cut at 200 characters, so a\n * server cannot write a false log line. A WARNING never names a span index or span\n * content.\n *\n * Python twin: `exporters/http.py::_check_ack`. Same rule, same thresholds.\n */\ninterface AckOutcome {\n result: ExportResult;\n counts: AckCounts;\n /** True when a retry inside the same `export()` call cannot change the answer. */\n final: boolean;\n}\n\nconst MAX_ACK_REASONS = 3;\nconst MAX_ACK_REASON_CHARS = 200;\n\n/** Make a reason from the server one printable line: control and line-break characters become spaces. */\nfunction oneLine(text: string): string {\n // eslint-disable-next-line no-control-regex\n return text.replace(/[\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]/g, ' ');\n}\n\n/** The distinct reasons of an ack, for a WARNING. Never a span index, never span content. */\nfunction ackReasons(body: Record<string, unknown>): string {\n const reasons: string[] = [];\n const errors = body.errors;\n if (Array.isArray(errors)) {\n for (const entry of errors) {\n const text = (entry as { error?: unknown } | null)?.error;\n if (typeof text !== 'string' || text.length === 0) continue;\n const cut = oneLine(text).slice(0, MAX_ACK_REASON_CHARS);\n if (!reasons.includes(cut)) reasons.push(cut);\n if (reasons.length === MAX_ACK_REASONS) break;\n }\n }\n if (reasons.length === 0) {\n const message =\n (typeof body.errorMessage === 'string' && body.errorMessage) ||\n (typeof body.error_message === 'string' && body.error_message) ||\n '';\n if (message) reasons.push(oneLine(message).slice(0, MAX_ACK_REASON_CHARS));\n }\n return reasons.length === 0 ? 'No reason was returned.' : `Reasons: ${reasons.join('; ')}`;\n}\n\nasync function checkAck(\n response: Response,\n spansSent: number,\n scrub: (text: string) => string,\n): Promise<AckOutcome | null> {\n let payload: unknown;\n try {\n payload = await response.json();\n } catch {\n return null; // not JSON (or the body read was aborted): not a Risicare ack\n }\n if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {\n return null;\n }\n\n const body = payload as Record<string, unknown>;\n const accepted = asCount(body.accepted);\n const rejected = asCount(body.rejected);\n if (accepted === undefined || rejected === undefined) return null;\n const counts: AckCounts = { accepted, rejected };\n\n if (accepted === 0 && rejected === 0 && spansSent > 0) {\n warn(\n `Risicare: the backend acknowledged 0 of ${spansSent} span(s): its ack counts no ` +\n `span as accepted or rejected. This batch is counted as NOT delivered.`,\n );\n return { result: ExportResult.FAILURE, counts, final: true };\n }\n if (rejected === 0) return { result: ExportResult.SUCCESS, counts, final: false };\n\n const total = accepted + rejected;\n if (accepted === 0) {\n warn(\n `Risicare: the backend accepted 0 of ${total} span(s) and rejected ${rejected} — ` +\n `this batch was NOT stored. Rejected spans are permanently lost and are NOT ` +\n `retried. ${scrub(ackReasons(body))}`,\n );\n return { result: ExportResult.SUCCESS, counts, final: false };\n }\n\n warn(\n `Risicare: the backend rejected ${rejected} of ${total} span(s); the remaining ` +\n `${accepted} were stored. Those ${rejected} are permanently lost and are NOT ` +\n `retried. ${scrub(ackReasons(body))}`,\n );\n return { result: ExportResult.SUCCESS, counts, final: false };\n}\n","/**\n * Fix Applier — Applies fixes to agent operations.\n *\n * Handles different fix types:\n * - PromptFix: Modify system/user prompts (prepend, append, replace, few_shot)\n * - ParameterFix: Adjust LLM parameters (temperature, model, etc.)\n * - RetryFix: Retry with exponential backoff + jitter\n * - FallbackFix: Switch to fallback model or default response\n * - GuardFix: Input/output validation (content filter, format check, length)\n *\n * Port of Python SDK's runtime/applier.py adapted for Node.js.\n */\n\nimport { createHash } from 'node:crypto';\nimport type { ActiveFix, FixRuntimeConfig } from './config.js';\nimport { shouldApply, resolveFixRuntimeConfig } from './config.js';\nimport type { FixCache } from './cache.js';\nimport { debug, warn } from '../utils/log.js';\n\n/**\n * Maximum length for fix content injected into prompts.\n * Prevents unbounded prompt injection from malicious/corrupted fix configs.\n */\nconst MAX_FIX_CONTENT_LENGTH = 10_000;\n\n// ─── Apply Result ───────────────────────────────────────────────────────────\n\nexport interface ApplyResult {\n applied: boolean;\n fixId?: string;\n deploymentId?: string;\n fixType?: string;\n modifications: Record<string, unknown>;\n error?: string;\n /**\n * Guard-only: human-readable reason a guard failed (passed=false). Used\n * by GuardRejectedError to surface an actionable message to the customer.\n * `error` carries the raw exception text; `reason` carries the audit\n * category ('guard_exception', 'content_filter', 'format_check', etc.).\n */\n reason?: string;\n}\n\nfunction emptyResult(fix: ActiveFix, fixType: string): ApplyResult {\n return {\n applied: false,\n fixId: fix.fixId,\n deploymentId: fix.deploymentId,\n fixType,\n modifications: {},\n };\n}\n\n/**\n * Escapes of a backslash and an ASCII letter that Python `re` and JavaScript\n * `RegExp` (without the `u` flag) read the same way. From the two grammars:\n * - Outside a class: `\\b \\B \\d \\D \\s \\S \\w \\W` (classes and word\n * boundaries) and `\\f \\n \\r \\t \\v` (control characters).\n * - Inside a class: the same, but not `\\B` (Python refuses it; JS reads B).\n * `[\\b]` is a backspace in both.\n * - `\\xHH` and `\\uHHHH` only with exactly 2 or 4 hex digits (Python refuses\n * a short one; JS reads it as the letter x or u).\n * - `\\A` and `\\Z` outside a class are translated (see below).\n * Every other letter fails closed. JS reads it as the letter itself; Python\n * refuses it (`\\e`, `\\q`, `\\z` before 3.14, `\\k`, `\\c`, `[\\A]`, `[\\Z]`) or\n * reads it differently (`\\a`, `\\N{...}`, `\\U........`, `\\z` from 3.14).\n */\nconst SAME_ESCAPES = 'bBdDsSwWfnrtv';\nconst SAME_ESCAPES_IN_CLASS = 'bdDsSwWfnrtv';\n\nconst LEADING_INLINE_FLAGS = /^\\(\\?([ims]+)\\)/;\nconst PY_NAMED_GROUP = /^\\(\\?P<([A-Za-z_][A-Za-z0-9_]*)>/;\nconst PY_NAMED_BACKREF = /^\\(\\?P=([A-Za-z_][A-Za-z0-9_]*)\\)/;\nconst JS_NAMED_GROUP = /^\\(\\?<([A-Za-z_][A-Za-z0-9_]*)>/;\n\n/**\n * Translate a Python `re` pattern to a JavaScript RegExp source and flags.\n *\n * - A leading inline-flag group `(?i)`, `(?s)`, `(?m)` or a combination such\n * as `(?is)` becomes RegExp flags. The `i` flag is always set.\n * - `\\A` becomes `(?<![\\s\\S])` and `\\Z` becomes `(?![\\s\\S])` (start and end\n * of the input, as in Python). Without the `u` flag, JavaScript reads `\\A`\n * and `\\Z` as the letters A and Z.\n * - `(?P<name>` becomes `(?<name>`, and `(?P=name)` becomes `\\k<name>`.\n *\n * It THROWS (the caller fails closed) on a backslash and a letter outside the\n * set above, and on a group name that occurs two times (Python refuses it).\n * Other escaped characters and the rest of a character class are copied\n * unchanged. Any other Python-only form stays as it is; if it does not\n * compile, the caller fails closed.\n * @internal\n */\nexport function translatePythonPattern(pattern: string): { source: string; flags: string } {\n let flags = 'i';\n let rest = pattern;\n const m = LEADING_INLINE_FLAGS.exec(rest);\n if (m) {\n for (const f of m[1]) if (!flags.includes(f)) flags += f;\n rest = rest.slice(m[0].length);\n }\n\n const names = new Set<string>();\n const addName = (name: string): void => {\n if (names.has(name)) throw new Error('a group name occurs two times');\n names.add(name);\n };\n\n let source = '';\n let inClass = false;\n for (let i = 0; i < rest.length; i++) {\n const c = rest[i];\n if (c === '\\\\' && i + 1 < rest.length) {\n const next = rest[i + 1];\n if (/[A-Za-z]/.test(next)) {\n if (!inClass && next === 'A') {\n source += '(?<![\\\\s\\\\S])';\n i++;\n continue;\n }\n if (!inClass && next === 'Z') {\n source += '(?![\\\\s\\\\S])';\n i++;\n continue;\n }\n if (next === 'x' || next === 'u') {\n const n = next === 'x' ? 2 : 4;\n const hex = rest.slice(i + 2, i + 2 + n);\n if (!new RegExp(`^[0-9A-Fa-f]{${n}}$`).test(hex)) throw new Error('short hex escape');\n source += c + next + hex;\n i += 1 + n;\n continue;\n }\n if (!(inClass ? SAME_ESCAPES_IN_CLASS : SAME_ESCAPES).includes(next)) {\n throw new Error('an escape that Python and JavaScript read differently');\n }\n }\n source += c + next;\n i++;\n continue;\n }\n if (inClass) {\n if (c === ']') inClass = false;\n source += c;\n continue;\n }\n if (c === '[') {\n inClass = true;\n source += c;\n continue;\n }\n const tail = rest.slice(i);\n let g: RegExpExecArray | null;\n if ((g = PY_NAMED_GROUP.exec(tail)) || (g = JS_NAMED_GROUP.exec(tail))) {\n addName(g[1]);\n source += `(?<${g[1]}>`;\n i += g[0].length - 1;\n continue;\n }\n if ((g = PY_NAMED_BACKREF.exec(tail))) {\n source += `\\\\k<${g[1]}>`;\n i += g[0].length - 1;\n continue;\n }\n source += c;\n }\n return { source, flags };\n}\n\n/** (fix id, pattern index) pairs whose \"not usable\" WARNING was written. */\nconst warnedGuardPatterns = new Set<string>();\n\n/** One WARNING per (fix id, pattern index) per process. Index -1: not a list. */\nfunction warnUnusablePattern(fixId: string | undefined, index: number): void {\n const key = `${fixId ?? 'unknown'}\\u0000${index}`;\n if (warnedGuardPatterns.has(key)) return;\n warnedGuardPatterns.add(key);\n warn(\n index < 0\n ? `Guard fix ${fixId ?? 'unknown'}: blocked_patterns is not a list. The guard rejects every call.`\n : `Guard fix ${fixId ?? 'unknown'}: blocked pattern ${index} is not usable (empty, not a ` +\n 'string, longer than 500 characters, or it does not compile). The guard rejects every call.',\n );\n}\n\n// ─── Fix Applier ────────────────────────────────────────────────────────────\n\nexport class FixApplier {\n private readonly _config: Required<FixRuntimeConfig>;\n private readonly _cache: FixCache;\n private _applicationLog: ApplyResult[] = [];\n\n constructor(config: FixRuntimeConfig, cache: FixCache) {\n this._config = resolveFixRuntimeConfig(config);\n this._cache = cache;\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // Fix Lookup\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Get applicable fix for an error code.\n *\n * Considers A/B testing bucket if sessionId is provided. Uses\n * crypto.createHash('md5') for deterministic bucketing across restarts.\n */\n getFixForError(\n errorCode: string,\n sessionId?: string,\n ): ActiveFix | null {\n try {\n const fix = this._cache.get(errorCode);\n if (!fix) return null;\n\n // Check A/B test bucketing\n if (sessionId && this._config.abTestingEnabled) {\n const hashHex = createHash('md5')\n .update(sessionId)\n .digest('hex')\n .substring(0, 8);\n const sessionHash = parseInt(hashHex, 16);\n\n if (!shouldApply(fix, sessionHash)) {\n debug(`Fix ${fix.fixId} not applied (A/B control group)`);\n return null;\n }\n }\n\n return fix;\n } catch (e) {\n debug(`getFixForError error: ${e}`);\n return null;\n }\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // 1. Prompt Fix\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Apply a prompt fix to messages.\n *\n * Supports 4 modification types:\n * - prepend: Add content before first system message\n * - append: Add content after first system message\n * - replace: Regex replace across all messages\n * - few_shot: Insert user/assistant example pairs after system message\n */\n applyPromptFix(\n fix: ActiveFix,\n messages: Record<string, unknown>[],\n ): { messages: Record<string, unknown>[]; result: ApplyResult } {\n try {\n const cfg = fix.config;\n const modificationType = (cfg.modification_type ?? cfg.modificationType ?? 'append') as string;\n const target = (cfg.target ?? 'system') as string;\n let content = (cfg.content ?? '') as string;\n\n // Truncate oversized content to prevent prompt injection\n if (content.length > MAX_FIX_CONTENT_LENGTH) {\n warn(\n `Fix ${fix.fixId} content truncated from ${content.length} to ${MAX_FIX_CONTENT_LENGTH} chars`,\n );\n content = content.slice(0, MAX_FIX_CONTENT_LENGTH);\n }\n\n const result = emptyResult(fix, 'prompt');\n\n if (this._config.dryRun) {\n result.modifications = {\n type: modificationType,\n target,\n contentPreview: content.slice(0, 100),\n };\n return { messages, result };\n }\n\n let modified = messages.map((m) => ({ ...m }));\n\n if (modificationType === 'prepend') {\n modified = this._prependToTarget(modified, target, content);\n result.applied = true;\n result.modifications = { type: 'prepend', target };\n } else if (modificationType === 'append') {\n modified = this._appendToTarget(modified, target, content);\n result.applied = true;\n result.modifications = { type: 'append', target };\n } else if (modificationType === 'replace') {\n const pattern = (cfg.pattern ?? '') as string;\n if (pattern) {\n modified = this._replaceInMessages(modified, pattern, content);\n result.applied = true;\n result.modifications = { type: 'replace', pattern };\n }\n } else if (modificationType === 'few_shot') {\n const examples = (cfg.examples ?? []) as Array<Record<string, string>>;\n if (examples.length > 0) {\n modified = this._addFewShotExamples(modified, examples);\n result.applied = true;\n result.modifications = { type: 'few_shot', count: examples.length };\n }\n }\n\n return { messages: modified, result };\n } catch (e) {\n debug(`applyPromptFix error: ${e}`);\n return {\n messages,\n result: {\n applied: false,\n fixId: fix.fixId,\n fixType: 'prompt',\n modifications: {},\n error: String(e),\n },\n };\n }\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // 2. Parameter Fix\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Apply a parameter fix — merge config.parameters into params.\n */\n applyParameterFix(\n fix: ActiveFix,\n params: Record<string, unknown>,\n ): { params: Record<string, unknown>; result: ApplyResult } {\n try {\n const newParams = (fix.config.parameters ?? {}) as Record<string, unknown>;\n const result = emptyResult(fix, 'parameter');\n\n if (this._config.dryRun) {\n result.modifications = { parameters: newParams };\n return { params, result };\n }\n\n const modified = { ...params, ...newParams };\n result.applied = true;\n result.modifications = { parameters: newParams };\n\n return { params: modified, result };\n } catch (e) {\n debug(`applyParameterFix error: ${e}`);\n return {\n params,\n result: {\n applied: false,\n fixId: fix.fixId,\n fixType: 'parameter',\n modifications: {},\n error: String(e),\n },\n };\n }\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // 3. Retry Fix (async — uses setTimeout for sleeping)\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Apply a retry fix to an async operation.\n *\n * Retries with exponential backoff + jitter using\n * `await new Promise(r => setTimeout(r, delay))`.\n */\n async applyRetryFix<T>(\n fix: ActiveFix,\n operation: () => Promise<T>,\n ): Promise<{ value: T; result: ApplyResult }> {\n const cfg = fix.config;\n const maxRetries = (cfg.max_retries ?? cfg.maxRetries ?? 3) as number;\n const initialDelayMs = (cfg.initial_delay_ms ?? cfg.initialDelayMs ?? 1000) as number;\n const maxDelayMs = (cfg.max_delay_ms ?? cfg.maxDelayMs ?? 30_000) as number;\n const exponentialBase = (cfg.exponential_base ?? cfg.exponentialBase ?? 2.0) as number;\n const jitter = (cfg.jitter ?? true) as boolean;\n const retryOn = (cfg.retry_on ?? cfg.retryOn ?? []) as string[];\n\n const result = emptyResult(fix, 'retry');\n\n if (this._config.dryRun) {\n result.modifications = { maxRetries, initialDelayMs };\n const value = await operation();\n return { value, result };\n }\n\n let lastError: Error | null = null;\n let attempts = 0;\n\n for (let attempt = 0; attempt <= maxRetries; attempt++) {\n attempts++;\n try {\n const value = await operation();\n result.applied = true;\n result.modifications = { attempts };\n return { value, result };\n } catch (e) {\n lastError = e instanceof Error ? e : new Error(String(e));\n const errorType = lastError.constructor.name;\n\n // Check if we should retry this specific error type\n if (retryOn.length > 0 && !retryOn.includes(errorType)) {\n throw lastError;\n }\n\n if (attempt < maxRetries) {\n // Calculate delay with exponential backoff\n let delayMs = Math.min(\n initialDelayMs * Math.pow(exponentialBase, attempt),\n maxDelayMs,\n );\n\n // Add jitter: multiply by random factor [0.5, 1.5)\n if (jitter) {\n delayMs *= 0.5 + Math.random();\n }\n\n debug(\n `Retry ${attempt + 1}/${maxRetries} after ${Math.round(delayMs)}ms`,\n );\n await new Promise<void>((r) => setTimeout(r, delayMs));\n }\n }\n }\n\n // All retries exhausted\n result.applied = true;\n result.error = lastError?.message;\n result.modifications = { attempts, exhausted: true };\n throw lastError;\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // 4. Fallback Fix\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Apply a fallback fix.\n *\n * - 'model': Replace params.model with the fallback model\n * - 'default': Set params._fallbackResponse for the caller to use\n */\n applyFallbackFix(\n fix: ActiveFix,\n params: Record<string, unknown>,\n ): { params: Record<string, unknown>; result: ApplyResult } {\n try {\n const cfg = fix.config;\n const fallbackType = (cfg.fallback_type ?? cfg.fallbackType ?? 'model') as string;\n const fallbackConfig = (cfg.fallback_config ?? cfg.fallbackConfig ?? {}) as Record<string, unknown>;\n const result = emptyResult(fix, 'fallback');\n\n if (this._config.dryRun) {\n result.modifications = { fallbackType, fallbackConfig };\n return { params, result };\n }\n\n const modified = { ...params };\n\n if (fallbackType === 'model') {\n const fallbackModel = fallbackConfig.model as string | undefined;\n if (fallbackModel) {\n modified.model = fallbackModel;\n result.applied = true;\n result.modifications = { model: fallbackModel };\n }\n } else if (fallbackType === 'default') {\n const defaultResponse = fallbackConfig.response;\n if (defaultResponse !== undefined) {\n modified._fallbackResponse = defaultResponse;\n result.applied = true;\n result.modifications = { defaultResponse: true };\n }\n }\n\n return { params: modified, result };\n } catch (e) {\n debug(`applyFallbackFix error: ${e}`);\n return {\n params,\n result: {\n applied: false,\n fixId: fix.fixId,\n fixType: 'fallback',\n modifications: {},\n error: String(e),\n },\n };\n }\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // 5. Guard Fix\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Apply a guard fix (validation).\n *\n * Guard types:\n * - content_filter: Regex-based blocked patterns\n * - format_check: JSON.parse() validity\n * - input_validation / output_validation: min/max length\n *\n * `content_filter` searches the content for each entry of `blocked_patterns`\n * (case-insensitive, after `translatePythonPattern`). It fails CLOSED: when\n * `blocked_patterns` is not a list, or an entry is empty, is not a string,\n * is longer than 500 characters or cannot be used, the guard does not pass.\n * One WARNING names the fix id and the pattern index, once for each pair in\n * the process. The reason names the pattern index, never the pattern or the\n * content.\n *\n * Limits:\n * - The interceptor runs only on the OpenAI chat patch (input guards) and on\n * `interceptCall` / `interceptResponse`. It does not run when a framework\n * integration suppresses provider instrumentation.\n * - Each SDK uses its own regular-expression engine. These constructs can\n * give a different result in JavaScript and Python: `$` before a final\n * newline, Unicode case folding, `\\d` and `\\w` on non-ASCII text,\n * `\\N{...}` and `\\U........` (JavaScript fails closed), and a `]` first\n * in a class.\n * - A pattern has no time bound. A pattern with nested repeats can take a\n * very long time on a long input.\n */\n applyGuardFix(\n fix: ActiveFix,\n content: string,\n isInput = true,\n ): { content: string; passed: boolean; result: ApplyResult } {\n try {\n const cfg = fix.config;\n const guardType = (cfg.guard_type ?? cfg.guardType ?? 'output_validation') as string;\n const guardConfig = (cfg.guard_config ?? cfg.guardConfig ?? {}) as Record<string, unknown>;\n const result = emptyResult(fix, 'guard');\n\n // Check if guard applies to this direction\n if (isInput && guardType !== 'input_validation' && guardType !== 'content_filter') {\n return { content, passed: true, result };\n }\n if (!isInput && guardType !== 'output_validation' && guardType !== 'format_check') {\n return { content, passed: true, result };\n }\n\n if (this._config.dryRun) {\n result.modifications = { guardType };\n return { content, passed: true, result };\n }\n\n let passed = true;\n let reason: string | undefined;\n\n if (guardType === 'content_filter') {\n // A key that is present with null is \"not a list\" (as in Python); only\n // a missing key means \"no patterns\".\n const blockedPatterns: unknown = 'blocked_patterns' in guardConfig\n ? guardConfig.blocked_patterns\n : 'blockedPatterns' in guardConfig ? guardConfig.blockedPatterns : [];\n // F-029: a pattern that is not usable makes the guard FAIL CLOSED.\n // Through 0.7.1 it was skipped with a debug line and the guard passed.\n // The reason names the index only: a literal pattern IS the blocked text.\n if (!Array.isArray(blockedPatterns)) {\n warnUnusablePattern(fix.fixId, -1);\n passed = false;\n reason = 'blocked_patterns is not a list';\n } else {\n for (let index = 0; index < blockedPatterns.length; index++) {\n const regex = this._safeCompileRegex(blockedPatterns[index] as string);\n if (!regex) {\n warnUnusablePattern(fix.fixId, index);\n passed = false;\n reason = `blocked pattern ${index} is not usable`;\n break;\n }\n if (regex.test(content)) {\n passed = false;\n reason = `blocked pattern matched (pattern ${index})`;\n break;\n }\n }\n }\n } else if (guardType === 'format_check') {\n const requiredFormat = guardConfig.format as string | undefined;\n if (requiredFormat === 'json') {\n try {\n JSON.parse(content);\n } catch {\n passed = false;\n reason = 'format_check: invalid JSON';\n }\n }\n } else if (guardType === 'input_validation' || guardType === 'output_validation') {\n const minLength = (guardConfig.min_length ?? guardConfig.minLength ?? 0) as number;\n const maxLength = (guardConfig.max_length ?? guardConfig.maxLength ?? Infinity) as number;\n if (content.length < minLength || content.length > maxLength) {\n passed = false;\n reason = `${guardType}: length ${content.length} outside [${minLength}, ${maxLength}]`;\n }\n }\n\n result.applied = true;\n result.modifications = { passed, guardType };\n if (reason !== undefined) result.reason = reason;\n\n return { content, passed, result };\n } catch (e) {\n // F-731: Fail-CLOSED on guard error. An unexpected exception in a\n // safety-validation path MUST NOT silently pass content through —\n // that would defeat the entire purpose of input/output validation.\n // PR-4+5 review B2 (2026-05-25): the interceptor LAYER now reads\n // `passed:false` and throws GuardRejectedError to short-circuit the\n // LLM call. Before B2 this `passed:false` was advisory only — the\n // provider patcher consumed `modifications` / `messages` but never\n // read `passed`, so a thrown-getter attack still hit the LLM with\n // the attacker payload. The applier's job is to TELL the truth;\n // the interceptor's job is to ACT on it.\n warn(`applyGuardFix error (failing CLOSED): ${e}`);\n return {\n content,\n passed: false,\n result: {\n applied: true,\n fixId: fix.fixId,\n fixType: 'guard',\n modifications: { passed: false, reason: 'guard_exception' },\n error: String(e),\n reason: 'guard_exception',\n },\n };\n }\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // Application Log\n // ═══════════════════════════════════════════════════════════════════════════\n\n /** Log a fix application result. */\n logApplication(result: ApplyResult): void {\n this._applicationLog.push(result);\n\n // Limit log size\n if (this._applicationLog.length > 1000) {\n this._applicationLog = this._applicationLog.slice(-500);\n }\n }\n\n /** Get the application log. */\n getApplicationLog(): ApplyResult[] {\n return [...this._applicationLog];\n }\n\n // ═══════════════════════════════════════════════════════════════════════════\n // Private Helpers\n // ═══════════════════════════════════════════════════════════════════════════\n\n /**\n * Safely compile a regex pattern from untrusted input.\n * Returns null if invalid or too long.\n *\n * F-029: the fix patterns are written for Python `re`. Before it compiles\n * the pattern, this function translates the Python forms that have an exact\n * JavaScript equivalent (see `translatePythonPattern`). The `i` flag is\n * always on, as in the Python applier.\n */\n private _safeCompileRegex(\n pattern: string,\n maxLength = 500,\n ): RegExp | null {\n if (typeof pattern !== 'string' || !pattern || pattern.length > maxLength) return null;\n try {\n const { source, flags } = translatePythonPattern(pattern);\n return new RegExp(source, flags);\n } catch {\n debug(`Invalid regex pattern (length=${pattern.length})`);\n return null;\n }\n }\n\n /** Prepend content to the first message matching the target role. */\n private _prependToTarget(\n messages: Record<string, unknown>[],\n target: string,\n content: string,\n ): Record<string, unknown>[] {\n return messages.map((msg) => {\n if (msg.role === target) {\n return {\n ...msg,\n content: content + '\\n\\n' + ((msg.content as string) ?? ''),\n };\n }\n return msg;\n });\n }\n\n /** Append content to the first message matching the target role. */\n private _appendToTarget(\n messages: Record<string, unknown>[],\n target: string,\n content: string,\n ): Record<string, unknown>[] {\n return messages.map((msg) => {\n if (msg.role === target) {\n return {\n ...msg,\n content: ((msg.content as string) ?? '') + '\\n\\n' + content,\n };\n }\n return msg;\n });\n }\n\n /** Regex replace across all messages. */\n private _replaceInMessages(\n messages: Record<string, unknown>[],\n pattern: string,\n replacement: string,\n ): Record<string, unknown>[] {\n const regex = this._safeCompileRegex(pattern);\n if (!regex) {\n debug('Skipping invalid regex pattern in prompt fix');\n return messages;\n }\n\n return messages.map((msg) => {\n const msgContent = msg.content;\n if (typeof msgContent === 'string') {\n return { ...msg, content: msgContent.replace(regex, replacement) };\n }\n return msg;\n });\n }\n\n /** Add few-shot examples after the first system message. */\n private _addFewShotExamples(\n messages: Record<string, unknown>[],\n examples: Array<Record<string, string>>,\n ): Record<string, unknown>[] {\n const result: Record<string, unknown>[] = [];\n let systemFound = false;\n\n for (const msg of messages) {\n result.push(msg);\n\n if (msg.role === 'system' && !systemFound) {\n systemFound = true;\n for (const example of examples) {\n if (example.user) {\n result.push({ role: 'user', content: example.user });\n }\n if (example.assistant) {\n result.push({ role: 'assistant', content: example.assistant });\n }\n }\n }\n }\n\n return result;\n }\n}\n","/**\n * Fix Loader — Fetches active fixes from the Risicare API.\n *\n * Handles:\n * - Initial loading of fixes on startup\n * - Periodic background refresh via setInterval (unref'd)\n * - Exponential backoff on failure\n * - Circuit breaker: after 3 consecutive failures, stop trying for 30s\n *\n * Uses native fetch (Node.js 18+) with AbortController for timeouts.\n *\n * Port of Python SDK's runtime/loader.py adapted for Node.js.\n */\n\nimport type { ActiveFix } from './config.js';\nimport { activeFixFromApiResponse } from './config.js';\nimport type { FixRuntimeConfig } from './config.js';\nimport { resolveFixRuntimeConfig } from './config.js';\nimport type { FixCache } from './cache.js';\nimport { debug, warn } from '../utils/log.js';\nimport { safeUrl, scrubText } from '../utils/scrub.js';\nimport { SDK_VERSION } from '../version.js';\n\nexport class FixLoader {\n private readonly _config: Required<FixRuntimeConfig>;\n private readonly _cache: FixCache;\n\n private _refreshTimer: ReturnType<typeof setInterval> | null = null;\n private _lastLoadTime: number | null = null;\n private _consecutiveFailures = 0;\n private _circuitOpenUntil = 0;\n private _onLoadCallbacks: Array<(fixes: ActiveFix[]) => void> = [];\n // The HTTP status of the last load that got a non-2xx answer; null otherwise.\n private _lastStatus: number | null = null;\n\n // Circuit breaker settings\n private static readonly CIRCUIT_BREAKER_THRESHOLD = 3;\n private static readonly CIRCUIT_BREAKER_COOLDOWN_MS = 30_000;\n\n constructor(config: FixRuntimeConfig, cache: FixCache) {\n this._config = resolveFixRuntimeConfig(config);\n this._cache = cache;\n }\n\n /** Error text for a log line: one line, the api endpoint as `safeUrl` gives it, no key. */\n private _scrub(error: unknown): string {\n let out: string;\n try {\n out = error instanceof Error ? `${error.name}: ${error.message}` : String(error);\n } catch {\n out = typeof error;\n }\n const endpoint = (this._config.apiEndpoint ?? '').replace(/\\/+$/, '');\n if (endpoint && safeUrl(endpoint) !== endpoint) out = out.split(endpoint).join(safeUrl(endpoint));\n return scrubText(out, [this._config.apiKey]);\n }\n\n /**\n * The WARNING for a failed first load: the request URL with no userinfo, no\n * query and no key, the HTTP status or the error class, and that tracing is\n * not affected. Never the error text: it can echo the URL with its query.\n */\n private _firstLoadWarning(error: unknown): string {\n let cause: string;\n if (this._lastStatus !== null) {\n cause = `HTTP ${this._lastStatus}`;\n } else {\n cause = error instanceof Error ? error.name : typeof error;\n const code = (error as { cause?: { code?: unknown } } | null)?.cause?.code;\n if (typeof code === 'string' && /^[A-Z][A-Z0-9_]*$/.test(code)) cause += ` (${code})`;\n }\n const endpoint = (this._config.apiEndpoint ?? '').replace(/\\/+$/, '');\n return scrubText(\n `The first load of the fixes from ${safeUrl(endpoint)}/v1/fixes/active failed (${cause}). ` +\n 'No fix is applied until a later load succeeds. Tracing is not affected.',\n [this._config.apiKey],\n 500,\n );\n }\n\n /** Hide the key from `util.inspect` and `console.log` of the loader. */\n [Symbol.for('nodejs.util.inspect.custom')](): string {\n return 'FixLoader {}';\n }\n\n /** Timestamp of last successful load. */\n get lastLoadTime(): number | null {\n return this._lastLoadTime;\n }\n\n /**\n * Start the loader: perform initial load and start background refresh.\n *\n * Never throws — failures are logged and the runtime degrades gracefully.\n */\n start(): void {\n try {\n if (!this._config.enabled) {\n debug('Fix runtime disabled, skipping loader start');\n return;\n }\n\n if (!this._config.apiKey) {\n warn('No API key configured, fixes will not be loaded');\n return;\n }\n\n // Initial load (fire-and-forget — don't block startup). A failure gives\n // ONE WARNING, as the Python loader does: `initFixRuntime()` catches\n // every fault, so this is the only signal that a customer sees for a\n // 5xx, a 401 or a refused connection.\n this.loadSync().catch((e) => {\n warn(this._firstLoadWarning(e));\n });\n\n // Start background refresh\n if (this._config.autoRefresh) {\n this._startRefreshInterval();\n }\n } catch (e) {\n debug(`FixLoader.start error: ${this._scrub(e)}`);\n }\n }\n\n /** Stop the loader: clear the refresh interval. */\n stop(): void {\n try {\n if (this._refreshTimer !== null) {\n clearInterval(this._refreshTimer);\n this._refreshTimer = null;\n }\n } catch (e) {\n debug(`FixLoader.stop error: ${this._scrub(e)}`);\n }\n }\n\n /**\n * Register a callback invoked after each successful load.\n */\n onLoad(callback: (fixes: ActiveFix[]) => void): void {\n this._onLoadCallbacks.push(callback);\n }\n\n /**\n * Load fixes from the API.\n *\n * Name kept as \"loadSync\" for parity with the Python SDK, but this\n * returns a Promise in JS (there's no synchronous fetch in Node.js).\n */\n async loadSync(): Promise<ActiveFix[]> {\n if (!this._config.apiKey) {\n return [];\n }\n\n // Circuit breaker: skip if circuit is open\n const now = Date.now();\n if (\n this._consecutiveFailures >= FixLoader.CIRCUIT_BREAKER_THRESHOLD &&\n now < this._circuitOpenUntil\n ) {\n debug('Fix loader circuit breaker open — skipping load');\n return this._cache.getAll();\n }\n\n this._lastStatus = null;\n try {\n // ⚠ PATH AND HOST CHANGED 0.6.0 -> 0.7.0. This was\n // `{apiEndpoint}/api/v1/fixes/active`, and the `/api` prefix existed\n // only because a Caddy reverse proxy stripped it before forwarding to\n // FastAPI. The split has two hosts and no Caddy: the api serves\n // /v1/fixes/active directly, and the gateway host serves only /v1/spans.\n const endpoint = this._config.apiEndpoint.replace(/\\/+$/, '');\n const url = `${endpoint}/v1/fixes/active`;\n\n // AbortController for timeout\n const controller = new AbortController();\n const timeoutId = setTimeout(\n () => controller.abort(),\n this._config.timeoutMs,\n );\n\n const response = await fetch(url, {\n method: 'GET',\n headers: {\n 'Authorization': `Bearer ${this._config.apiKey}`,\n 'Content-Type': 'application/json',\n 'X-Risicare-SDK-Version': SDK_VERSION,\n },\n signal: controller.signal,\n });\n\n clearTimeout(timeoutId);\n\n if (!response.ok) {\n this._lastStatus = response.status;\n throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n }\n\n const data = (await response.json()) as Record<string, unknown>;\n const fixes = this._parseResponse(data);\n this._onLoadSuccess(fixes);\n return fixes;\n } catch (e) {\n this._onLoadFailure(e as Error);\n throw e;\n }\n }\n\n /** Get currently cached fixes without hitting the API. */\n getCached(): ActiveFix[] {\n return this._cache.getAll();\n }\n\n // ─── Private ────────────────────────────────────────────────────────────\n\n private _parseResponse(data: Record<string, unknown>): ActiveFix[] {\n const fixes: ActiveFix[] = [];\n const items =\n (data.fixes as unknown[]) ??\n (data.data as unknown[]) ??\n [];\n\n if (!Array.isArray(items)) return fixes;\n\n for (const item of items) {\n try {\n if (item && typeof item === 'object') {\n fixes.push(activeFixFromApiResponse(item as Record<string, unknown>));\n }\n } catch (e) {\n debug(`Failed to parse fix item: ${this._scrub(e)}`);\n }\n }\n\n return fixes;\n }\n\n private _onLoadSuccess(fixes: ActiveFix[]): void {\n this._lastLoadTime = Date.now();\n this._consecutiveFailures = 0;\n\n // Update cache\n this._cache.setAll(fixes);\n\n // Notify callbacks\n for (const callback of this._onLoadCallbacks) {\n try {\n callback(fixes);\n } catch (e) {\n debug(`Load callback error: ${this._scrub(e)}`);\n }\n }\n\n debug(`Loaded ${fixes.length} active fixes`);\n }\n\n private _onLoadFailure(error: Error): void {\n this._consecutiveFailures++;\n\n if (this._consecutiveFailures >= FixLoader.CIRCUIT_BREAKER_THRESHOLD) {\n this._circuitOpenUntil = Date.now() + FixLoader.CIRCUIT_BREAKER_COOLDOWN_MS;\n warn(\n `Fix loader circuit breaker opened after ${this._consecutiveFailures} failures. ` +\n `Cooldown: ${FixLoader.CIRCUIT_BREAKER_COOLDOWN_MS / 1000}s`,\n );\n } else {\n debug(\n `Fix load failed (attempt ${this._consecutiveFailures}): ${this._scrub(error)}`,\n );\n }\n }\n\n private _startRefreshInterval(): void {\n // Use exponential backoff on the refresh interval after failures\n const tick = (): void => {\n this.loadSync().catch((e) => {\n debug(`Background fix refresh failed: ${this._scrub(e)}`);\n });\n };\n\n this._refreshTimer = setInterval(\n () => {\n // Skip if circuit breaker is open (loadSync handles this,\n // but we also avoid the async overhead)\n if (\n this._consecutiveFailures >= FixLoader.CIRCUIT_BREAKER_THRESHOLD &&\n Date.now() < this._circuitOpenUntil\n ) {\n return;\n }\n tick();\n },\n this._config.refreshIntervalMs,\n );\n\n // unref() so the interval doesn't prevent Node.js process exit\n this._refreshTimer.unref();\n\n debug('Started fix refresh interval');\n }\n}\n","/**\n * Provider patcher input validation.\n *\n * F-722/F-620: every `patchX(client)` entry point creates `new Proxy(client, ...)`.\n * Proxy constructors throw an opaque `TypeError: Cannot create proxy with a non-object\n * as target or handler` when handed `null`, `undefined`, a primitive, or `false`.\n * That error happens deep in the SDK with no actionable message — and it crashes\n * the customer's app startup the moment they pass a maybe-null client.\n *\n * We fail-fast with a clear, named TypeError so the customer sees:\n * \"patchOpenAI requires a client object, got null\"\n * instead of:\n * \"Cannot create proxy with a non-object as target or handler\"\n *\n * Rationale for throwing (not returning the input):\n * - Returning the input would silently disable instrumentation; a customer who\n * expects spans would see \"no traces\" and have to root-cause it themselves.\n * - Throwing surfaces the bug at the call-site (their `patchOpenAI(maybeNull)`).\n * - It happens at init/setup time, not in the request hot path, so no latency cost.\n */\n// PR-4+5 review NIT (2026-05-25): asserts-style narrowing. Pre-fix the\n// signature returned `void` with an `unknown` client parameter, forcing\n// every patcher's `new Proxy(client, ...)` call to keep the `unknown` /\n// loose `T` type — TS could not prove the Proxy target was non-null.\n// `asserts client is NonNullable<T>` means TS narrows the caller's\n// variable after assertClient returns, so the surrounding code is\n// type-safe without redundant runtime checks.\nexport function assertClient<T>(\n patcherName: string,\n client: T,\n): asserts client is NonNullable<T> {\n if (client === null || client === undefined) {\n throw new TypeError(\n `${patcherName} requires a client object, got ${client === null ? 'null' : 'undefined'}`,\n );\n }\n const t = typeof client;\n if (t !== 'object' && t !== 'function') {\n throw new TypeError(\n `${patcherName} requires a client object, got ${t}`,\n );\n }\n}\n","/**\n * Instructor integration via Proxy wrapping.\n *\n * Instructor wraps an LLM client's create() method to extract structured\n * data from completions using a response model (Zod schema, etc.).\n *\n * F-884: The Instructor JS client (`@instructor-ai/instructor`) exposes the\n * structured-extraction method at `client.chat.completions.create(...)` —\n * mirroring the underlying OpenAI shape — NOT at a top-level `client.create`.\n * The previous patcher hooked the top-level `create`, which Instructor JS does\n * not have, so no spans ever fired. We now walk the nested path (chat →\n * completions → create) AND keep a top-level `create` intercept for forward-\n * compatibility with API shapes that may expose both.\n *\n * Usage:\n * import { patchInstructor } from 'risicare/instructor';\n * import Instructor from '@instructor-ai/instructor';\n * const client = patchInstructor(Instructor({ client: openai, mode: 'TOOLS' }));\n * const result = await client.chat.completions.create({\n * model: 'gpt-4o-mini',\n * messages: [...],\n * response_model: { schema: MySchema, name: 'MyExtraction' },\n * });\n *\n * Does NOT suppress provider instrumentation -- Instructor delegates to the\n * underlying LLM client, which should produce its own provider span.\n */\n\nimport { getTracer } from '../client.js';\nimport { SpanKind } from '../types.js';\nimport { debug } from '../utils/log.js';\nimport { assertClient } from '../utils/assert-client.js';\n\n/**\n * Build the wrapped `create` function. Shared between top-level (legacy) and\n * nested (`chat.completions.create`, the real Instructor JS shape) intercepts.\n */\nfunction makePatchedCreate(originalCreate: Function): Function {\n return function patchedCreate(this: unknown, ...args: unknown[]): unknown {\n const tracer = getTracer();\n if (!tracer?.enabled) {\n debug('Tracer not initialized — call init() before using patchInstructor()');\n return originalCreate.apply(this, args);\n }\n\n const params = (args[0] ?? {}) as Record<string, unknown>;\n // Instructor JS accepts response_model as { schema, name } or a Zod schema\n const responseModel = params.response_model ?? params.responseModel;\n\n let modelName = 'unknown';\n if (responseModel && typeof responseModel === 'function') {\n modelName = (responseModel as { name?: string }).name || 'unknown';\n } else if (responseModel && typeof responseModel === 'object') {\n const rm = responseModel as Record<string, unknown>;\n modelName =\n (rm.name as string) ??\n (rm.description as string) ??\n ((rm.schema as { name?: string } | undefined)?.name) ??\n 'schema';\n } else if (typeof responseModel === 'string') {\n modelName = responseModel;\n }\n\n return tracer.startSpan(\n {\n name: 'instructor.create',\n kind: SpanKind.LLM_CALL,\n attributes: {\n framework: 'instructor',\n 'framework.span_kind': 'extraction',\n 'instructor.response_model': modelName,\n ...(params.max_retries != null\n ? { 'instructor.max_retries': params.max_retries }\n : {}),\n ...(params.model != null\n ? { 'gen_ai.request.model': params.model }\n : {}),\n },\n },\n (_span) => {\n const result = originalCreate.apply(this, args);\n if (result && typeof (result as Promise<unknown>).then === 'function') {\n return (result as Promise<unknown>).then((r) => r);\n }\n return result;\n },\n );\n };\n}\n\n/**\n * Wrap an Instructor client with Risicare tracing.\n *\n * Intercepts BOTH:\n * - `client.chat.completions.create` (the real Instructor JS shape)\n * - `client.create` (legacy top-level shape, if present)\n *\n * @param client - An Instructor client\n * @returns A proxied client with tracing enabled\n */\nexport function patchInstructor<T extends object>(client: T): T {\n assertClient('patchInstructor', client);\n return new Proxy(client, {\n get(target, prop, receiver) {\n const value = Reflect.get(target, prop, receiver);\n\n // Legacy top-level create (rare, but harmless to keep for compat).\n if (prop === 'create' && typeof value === 'function') {\n return makePatchedCreate(value.bind(target));\n }\n\n // F-884: REAL Instructor JS shape — walk into `.chat.completions.create`.\n if (prop === 'chat' && value && typeof value === 'object') {\n return new Proxy(value as object, {\n get(chatTarget, chatProp, chatReceiver) {\n const chatValue = Reflect.get(chatTarget, chatProp, chatReceiver);\n if (chatProp === 'completions' && chatValue && typeof chatValue === 'object') {\n return new Proxy(chatValue as object, {\n get(compTarget, compProp, compReceiver) {\n const compValue = Reflect.get(compTarget, compProp, compReceiver);\n if (compProp === 'create' && typeof compValue === 'function') {\n return makePatchedCreate(compValue.bind(compTarget));\n }\n return compValue;\n },\n });\n }\n return chatValue;\n },\n });\n }\n\n return value;\n },\n });\n}\n"],"mappings":"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","names":["createHash","getTracer","getTracer"]}
|