@sailfish-ai/sf-veritas 0.3.2 → 0.4.1

package/dist/types/baseTransmitter.d.ts

@@ -42,6 +42,7 @@ export declare class BaseTransmitter {
         sessionId: string;
         timestampMs: string;
         parentSpanId: string;
+        dataSensitivityLevel: string;
     };
     /**
      * Merges the default variables with any additional variables passed as arguments.

package/dist/types/constants.d.ts

@@ -3,6 +3,12 @@
  * for a request (e.g., during stack trace or debugging).
  */
 export declare const TRACE_HEADER = "x-sf3-rid";
+/**
+ * Canonical header / metadata key for Sailfish trace propagation across any
+ * transport (HTTP, Kafka headers, Celery headers dict, BullMQ opts, etc).
+ * Use this constant everywhere a trace ID is written or read.
+ */
+export declare const HEADER_TRACING = "X-Sf3-Rid";
 /**
  * Outbound parent-trace header (mirrors Python's PARENT_SESSION_ID_HEADER).
  * Carries the FULL inbound trace id (3 segments) so server-side code can

package/dist/types/contextManager.d.ts

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "async_hooks";
 type Store = Map<string, unknown>;
 export declare const context: AsyncLocalStorage<Store>;
+export declare const NONSESSION_APPLOGS = "nonsession-applogs";
 export declare const DEFAULT_DOMAINS_TO_EXCLUDE: readonly ["identitytoolkit.googleapis.com", "t.co", "*.twitter.com", "*.gravatar.com", "*.googleapis.com", "*.amazonaws.com", "*.smooch.io", "*.zendesk.com"];
 type Context = {
     traceId?: string;
@@ -37,6 +38,20 @@ export declare class ContextManager {
     runWithSession<T>(sessionId: string, fn: () => T): T;
     /** Optional: clean up session context to avoid leaks in long-lived processes */
     deleteSession(sessionId: string): void;
+    /**
+     * Run `fn` inside a new AsyncLocalStorage scope whose Context is a shallow
+     * merge of the current context and `overrides`. Used by queue-consumer
+     * wrappers so each message's handler has its own trace without leaking into
+     * sibling iterations.
+     *
+     * H1: Context holds `Set` fields (`handledExceptions`, `excludedDomains`,
+     * `supportedDomains`). A naïve shallow merge would propagate the SAME Set
+     * reference from parent to child — child mutations would write into the
+     * parent's Set, leaking state across consumer-message scopes and growing
+     * unbounded. Clone the Sets when entering a new scope so each child gets
+     * its own copy.
+     */
+    runScoped<T>(overrides: Partial<Context>, fn: () => T): T;
     getTraceId(): string | undefined;
     getPageVisitUUID(): string | undefined;
     setTraceId(traceId: string): void;

package/dist/types/index.d.ts

@@ -7,3 +7,5 @@ export { transformFunctionSpans, transformFunctionSpansSync, setSkipTypeScriptPl
 export { shouldEnableRuntimeHooks, isRuntimeModeEnabled, isProductionEnvironment } from "./runtime/runtimeConfig";
 export { isAlreadyInstrumented } from "./runtime/instrumentationDetector";
 export { initializeWorkerPoolPatching, isInitialized as isWorkerPoolInitialized } from "./patches/workerPool/index";
+export { uninstallAsyncQueuePatches, isAsyncQueuePatchesInstalled, } from "./patches/asyncQueues/index";
+export { _setAsyncQueueHopSpy } from "./patches/asyncQueues/asyncQueueTracer";

package/dist/types/patches/asyncQueues/_stubs/bee-queue.d.ts

@@ -0,0 +1,10 @@
+/**
+ * TODO(queue-tracing): bee-queue async-queue tracing patch.
+ *
+ * Placeholder. bee-queue is a lightweight Redis-backed queue similar to
+ * BullMQ but with a different API. Store the trace in `job.data._sf` or on
+ * a custom options field — see bullmq.ts for the pattern.
+ *
+ * See veritas/jsts-backend/CONTRIBUTING_QUEUES.md.
+ */
+export declare function patchBeeQueue(): "not-installed";

package/dist/types/patches/asyncQueues/_stubs/rabbitmq.d.ts

@@ -0,0 +1,11 @@
+/**
+ * TODO(queue-tracing): RabbitMQ (amqplib) async-queue tracing patch.
+ *
+ * This is a placeholder. RabbitMQ messages have a `properties.headers` dict
+ * (amqplib) — the trace ID can go there. See the existing kafkajs.ts patch
+ * for the injection pattern.
+ *
+ * See veritas/jsts-backend/CONTRIBUTING_QUEUES.md for the step-by-step
+ * contributor guide on implementing this.
+ */
+export declare function patchRabbitMQ(): "not-installed";

package/dist/types/patches/asyncQueues/_stubs/sqs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * TODO(queue-tracing): AWS SQS (@aws-sdk/client-sqs) async-queue tracing patch.
+ *
+ * Placeholder. SQS `SendMessageCommand` input has a `MessageAttributes` dict
+ * — inject the trace ID there; the consumer reads it via `ReceiveMessage`.
+ *
+ * See veritas/jsts-backend/CONTRIBUTING_QUEUES.md.
+ */
+export declare function patchSQS(): "not-installed";

package/dist/types/patches/asyncQueues/asyncQueueTracer.d.ts

@@ -0,0 +1,127 @@
+import { NetworkHopTransmitter } from "../../networkHopTransmitter";
+import { NetworkRequestData, NetworkRequestTransmitter } from "../../networkRequestTransmitter";
+export declare const QUEUE_TRACE_HEADER = "X-Sf3-Rid";
+/**
+ * Case-insensitive lookup of the Sailfish trace header (X-Sf3-Rid) in a
+ * headers object or array-of-{key,value} entries. Proxies (HAProxy, envoy,
+ * nginx) and some Kafka clients may normalize header case.
+ */
+export declare function findSailfishTraceHeaderValue(headers: unknown): unknown;
+export interface QueueProducerContext {
+    /** Short library identifier, e.g. 'bullmq', 'kafkajs'. */
+    library: string;
+    /** Synthetic URI describing the destination, e.g. 'kafka://broker/topic'. */
+    queueUri: string;
+    /** The user-supplied message payload (used for body capture). */
+    messagePayload?: unknown;
+    /**
+     * HTTP-method-style label on the emitted hop. Defaults to ``ENQUEUE``.
+     * Useful overrides: ``ENQUEUE_TX`` for Kafka transactional producers so
+     * the UI can visually distinguish "pending until commit" from normal
+     * enqueue.
+     */
+    method?: string;
+}
+export interface QueueConsumerContext {
+    library: string;
+    queueUri: string;
+    messagePayload?: unknown;
+    /** Override the emitted hop method. Defaults to ``CONSUME``. Used by
+     *  BullMQ stalled-recovery path to tag ``CONSUME_STALLED``. */
+    method?: string;
+    /** Trace ID extracted from the incoming message header (if present). */
+    incomingTraceId?: string;
+}
+export interface ProducerHandle {
+    /** Trace ID with the third UUID freshly rotated. Inject this into the message. */
+    readonly traceId: string;
+    /** Call when the enqueue call settles (success or error). */
+    hopEnd: (err?: Error | null) => void;
+}
+declare function getNetworkRequestTransmitter(): NetworkRequestTransmitter;
+declare function getNetworkHopTransmitter(): NetworkHopTransmitter;
+export declare function isValidTraceShape(trace: unknown): trace is string;
+/**
+ * Rotate only the last segment (requestId) of a Sailfish trace triplet while
+ * preserving session + pageVisit. Exported so per-library consumer patches can
+ * rotate on retry/redelivery without emitting a producer hop.
+ */
+export declare function rotateTraceRequestId(trace: string): string;
+/**
+ * Begin a producer span. Rotates the third UUID of the current trace, returns
+ * the new trace + a `hopEnd` callback.
+ *
+ * W1: snapshot the body string AT call time (rather than at `hopEnd` time) and
+ * extract every other ctx field we'll need into local variables before
+ * returning. The `hopEnd` closure must NOT close over `ctx`, otherwise
+ * `ctx.messagePayload` (potentially MB-sized) stays pinned in heap for the
+ * entire in-flight window of the user's `producer.send()`. Under producer
+ * backpressure (slow brokers, high concurrency) this multiplies memory
+ * residency by the number of in-flight enqueues.
+ */
+export declare function beginProducer(ctx: QueueProducerContext): ProducerHandle;
+/**
+ * Wrap a consumer's handler so:
+ *   1. The handler runs inside a scoped AsyncLocalStorage context seeded with
+ *      the incoming trace ID (so child work sees it).
+ *   2. An inbound NetworkRequest span is emitted whose duration spans the
+ *      entire handler execution (success or error).
+ */
+export declare function wrapConsumerHandler<T>(ctx: QueueConsumerContext, handler: () => Promise<T> | T): Promise<T>;
+export { getNetworkHopTransmitter, getNetworkRequestTransmitter };
+/**
+ * W8: install a patched function onto a target prototype, returning whether
+ * the assignment succeeded. Customers who freeze library prototypes (security
+ * hardening, `Object.freeze(Queue.prototype)`) or other SDKs that install
+ * non-configurable properties on the same key would otherwise cause our
+ * assignment to throw TypeError in strict mode, aborting the entire installer
+ * mid-loop. We swallow the failure (logged under sfDebug) and let the rest
+ * of the patches in the same module continue.
+ */
+/**
+ * Optional debug/QA hook: every hop the SDK is about to transmit is also
+ * passed to a spy callback (if registered) BEFORE the transmitter runs.
+ * Used by the QA test app to stream hop events to a browser UI in real time.
+ * Zero cost when no spy is registered.
+ *
+ * @internal — exposed publicly for QA tooling only. Not part of the
+ *             stable customer-facing API.
+ */
+type HopSpy = (data: NetworkRequestData) => void;
+export declare function _setAsyncQueueHopSpy(spy: HopSpy | null): void;
+/**
+ * E3: use globally-keyed Symbols instead of string property names for our
+ * "this function/object has already been instrumented" markers. Other
+ * observability SDKs that happen to also use the string `__sfPatched`
+ * would otherwise see our marker on a function they wrapped and skip
+ * their own instrumentation, silently breaking their tracing. Symbols
+ * registered with the same key collide only across vendors that
+ * deliberately pick the same registry key.
+ */
+export declare const SF_PATCHED: unique symbol;
+export declare const SF_INSTANCE_WRAPPED: unique symbol;
+export declare function safeInstallPrototypeMethod(proto: any, key: string, patched: Function): boolean;
+/**
+ * W3: revert every prototype patch we've installed. Best-effort —
+ * individual restorations that throw (frozen prototype, non-configurable
+ * descriptor) are skipped. Returns the number of methods restored.
+ *
+ * After uninstall, `installAsyncQueuePatches()` may be called again to
+ * re-install. Customers should treat this as an emergency revert: if the
+ * SDK is responsible for an incident, uninstall in-process and redeploy
+ * later with `SF_DISABLE_QUEUE_PATCHES=true`.
+ */
+export declare function uninstallAllPrototypePatches(): number;
+/**
+ * A1: run an instrumentation rewrite (compute a new args object, allocate
+ * tracking handles, etc.) and never let an exception in our code escape into
+ * the customer's call path. Returns the rewrite result on success, or
+ * `null` on failure (caller falls back to the user's original args, no
+ * hop emitted).
+ *
+ * Customer payloads can carry exotic shapes — Proxies with throwing traps,
+ * objects with throw-on-access getters, non-stringifiable Symbol keys —
+ * that make `{...x}` / `Buffer.from(x)` / `JSON.stringify(x)` throw. Our
+ * telemetry must absorb those failures, not propagate them.
+ */
+export declare function tryInstrumentationRewrite<T>(rewrite: () => T, context: string): T | null;

package/dist/types/patches/asyncQueues/asyncQueues.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/patches/asyncQueues/bullmq.d.ts

@@ -0,0 +1,27 @@
+/** Shape we mutate. We don't depend on BullMQ's types to avoid a hard dep. */
+interface MutableJobOpts {
+    sf?: {
+        rid?: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * F9: queue-URI builder. For jobs we prefer (in order):
+ *   1. ``job.queueQualifiedName`` — BullMQ's prefix-aware canonical name
+ *      (e.g. ``bull:my-queue``). Present on Worker side.
+ *   2. ``job.queueName`` — plain queue name.
+ *   3. ``worker.name`` or ``queue.name`` — fallback for edge cases.
+ *
+ * Callers pass whichever of these they have. We strip BullMQ's ``bull:``
+ * prefix if present since our URI already has a scheme.
+ */
+export declare function buildQueueUri(queueName: string | undefined, jobName: string | undefined): string;
+/**
+ * Pick the best-available queue-name field from a Job or Worker-like
+ * object. Prefers qualified (prefix-aware) names.
+ */
+export declare function pickQueueNameFromJob(job: any): string | undefined;
+export declare function injectTraceIntoOpts(opts: MutableJobOpts | undefined, traceId: string): MutableJobOpts;
+type PatchInstallResult = "installed" | "not-installed" | "failed";
+export declare function patchBullmq(injectedBullmq?: unknown): PatchInstallResult;
+export {};

package/dist/types/patches/asyncQueues/bullmqPro.d.ts

@@ -0,0 +1,3 @@
+type PatchInstallResult = "installed" | "not-installed" | "failed";
+export declare function patchBullmqPro(injectedModule?: unknown): PatchInstallResult;
+export {};

package/dist/types/patches/asyncQueues/confluentKafkaJs.d.ts

@@ -0,0 +1,3 @@
+type PatchInstallResult = "installed" | "not-installed" | "failed";
+export declare function patchConfluentKafkaJs(injectedModule?: unknown): PatchInstallResult;
+export {};

package/dist/types/patches/asyncQueues/index.d.ts

@@ -0,0 +1,15 @@
+type PatchResult = "installed" | "not-installed" | "failed";
+type PatchInstaller = () => PatchResult;
+export declare function installAsyncQueuePatches(): void;
+export declare function isAsyncQueuePatchesInstalled(): boolean;
+/**
+ * W3: revert every async-queue prototype patch we've installed. Customers
+ * use this as an emergency revert when the SDK is implicated in an
+ * incident — restores library prototypes in-place and resets the
+ * `installed` guard so a later `installAsyncQueuePatches()` would
+ * install fresh. Returns the number of methods restored.
+ */
+export declare function uninstallAsyncQueuePatches(): number;
+/** Internal — used by subsequent subtasks to register their patch. */
+export declare function _registerAsyncQueuePatch(name: string, install: PatchInstaller, envDisableKey?: string): void;
+export * from "./asyncQueueTracer";

package/dist/types/patches/asyncQueues/kafkajs.d.ts

@@ -0,0 +1,7 @@
+type PatchInstallResult = "installed" | "not-installed" | "failed";
+/**
+ * @param injectedKafkajs  test hook — passes a kafkajs-shaped module so the
+ *                          vitest specs can avoid CJS require interop issues.
+ */
+export declare function patchKafkajs(injectedKafkajs?: unknown): PatchInstallResult;
+export {};

package/dist/types/setupConfig.d.ts

@@ -156,7 +156,10 @@ declare class AppConfig {
     captureResponseBody: boolean;
     requestBodyLimitBytes: number;
     responseBodyLimitBytes: number;
+    bullmqBulkAggregateMode: boolean;
     retryOnClientError: "all" | "idempotent" | "none";
+    dataSensitivityLevel: string;
+    exceptionCaptureLocals: boolean;
     private _serviceIdentificationReceived;
     constructor(options: SetupOptions);
     private getPackageVersion;

package/dist/worker-pool-capture.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./workerPoolSpanCapture-BUFN_RMW.cjs");exports.captureWorkerPoolOperation=e.captureWorkerPoolOperation;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./workerPoolSpanCapture-CVp5eCI6.cjs");exports.captureWorkerPoolOperation=e.captureWorkerPoolOperation;

package/dist/worker-pool-capture.mjs

@@ -1,4 +1,4 @@
-import { c as e } from "./workerPoolSpanCapture-BomWTMM2.js";
+import { c as e } from "./workerPoolSpanCapture-B5AjE5B9.js";
 export {
   e as captureWorkerPoolOperation
 };