@atlanai/sdk 0.1.0

package/dist/tracing/context-manager.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AsyncLocalStorage-backed OTel ContextManager.
+ *
+ * Implemented in-repo (over the isomorph ALS) instead of depending on
+ * `@opentelemetry/context-async-hooks`: that package ships CJS whose
+ * `require("async_hooks")` becomes a throwing shim when a consumer bundles the
+ * SDK into an ESM worker — and the implementation is ~30 lines against a
+ * stable `ContextManager` interface anyway.
+ */
+import { type Context, type ContextManager } from "@opentelemetry/api";
+export declare class AlsContextManager implements ContextManager {
+    private readonly storage;
+    /** Whether the runtime actually provides AsyncLocalStorage. */
+    get available(): boolean;
+    active(): Context;
+    with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(context: Context, fn: F, thisArg?: ThisParameterType<F>, ...args: A): ReturnType<F>;
+    bind<T>(context: Context, target: T): T;
+    enable(): this;
+    disable(): this;
+}

package/dist/tracing/context-manager.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * AsyncLocalStorage-backed OTel ContextManager.
+ *
+ * Implemented in-repo (over the isomorph ALS) instead of depending on
+ * `@opentelemetry/context-async-hooks`: that package ships CJS whose
+ * `require("async_hooks")` becomes a throwing shim when a consumer bundles the
+ * SDK into an ESM worker — and the implementation is ~30 lines against a
+ * stable `ContextManager` interface anyway.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlsContextManager = void 0;
+const api_1 = require("@opentelemetry/api");
+const isomorph_js_1 = require("./isomorph.js");
+class AlsContextManager {
+    storage = isomorph_js_1.iso.newAsyncLocalStorage();
+    /** Whether the runtime actually provides AsyncLocalStorage. */
+    get available() {
+        return this.storage !== null;
+    }
+    active() {
+        return this.storage?.getStore() ?? api_1.ROOT_CONTEXT;
+    }
+    with(context, fn, thisArg, ...args) {
+        if (this.storage === null)
+            return fn.call(thisArg, ...args);
+        return this.storage.run(context, () => fn.call(thisArg, ...args));
+    }
+    bind(context, target) {
+        if (typeof target !== "function")
+            return target;
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const manager = this;
+        return function bound(...args) {
+            return manager.with(context, () => target.apply(this, args));
+        };
+    }
+    enable() {
+        return this;
+    }
+    disable() {
+        this.storage?.disable();
+        return this;
+    }
+}
+exports.AlsContextManager = AlsContextManager;

package/dist/tracing/exporter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Exporter construction (SPEC §2, §3.3).
+ *
+ * Atlan mode: stock OTLP/HTTP protobuf exporter, gzip, pointed at
+ * `{base_url}/otel/v1/traces` with auth + workspace headers.
+ *
+ * Generic-collector mode: a bare OTLPTraceExporter, which itself honors the
+ * standard OTEL_EXPORTER_OTLP_(TRACES_)ENDPOINT / _HEADERS env chain — the SDK
+ * adds no Atlan headers there.
+ */
+import type { SpanExporter } from "@opentelemetry/sdk-trace-base";
+import type { ResolvedConfig } from "./config.js";
+/**
+ * Lazy OTLP exporter: the heavyweight node-only OTLP/protobuf chain is
+ * dynamic-imported on first use, so bundling the SDK for an edge runtime (or
+ * injecting a custom spanExporter) never evaluates it at startup — the
+ * top-level evaluation of its CJS dependencies is exactly what breaks ESM
+ * worker bundles.
+ */
+export declare function buildExporter(config: ResolvedConfig): SpanExporter;

package/dist/tracing/exporter.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Exporter construction (SPEC §2, §3.3).
+ *
+ * Atlan mode: stock OTLP/HTTP protobuf exporter, gzip, pointed at
+ * `{base_url}/otel/v1/traces` with auth + workspace headers.
+ *
+ * Generic-collector mode: a bare OTLPTraceExporter, which itself honors the
+ * standard OTEL_EXPORTER_OTLP_(TRACES_)ENDPOINT / _HEADERS env chain — the SDK
+ * adds no Atlan headers there.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildExporter = buildExporter;
+const logger_js_1 = require("./logger.js");
+const version_js_1 = require("./version.js");
+async function loadOtlpExporter(config) {
+    const [{ OTLPTraceExporter }, { CompressionAlgorithm }] = await Promise.all([
+        import("@opentelemetry/exporter-trace-otlp-proto"),
+        import("@opentelemetry/otlp-exporter-base"),
+    ]);
+    if (config.mode === "atlan") {
+        return new OTLPTraceExporter({
+            url: `${config.baseUrl}/otel/v1/traces`,
+            headers: {
+                Authorization: `Bearer ${config.apiKey ?? ""}`,
+                "X-Atlan-Workspace-Id": config.workspaceId ?? "",
+                "x-atlan-sdk-name": version_js_1.SDK_LANGUAGE,
+                "x-atlan-sdk-version": version_js_1.SDK_VERSION,
+            },
+            timeoutMillis: Math.round(config.timeoutS * 1000),
+            compression: CompressionAlgorithm.GZIP,
+        });
+    }
+    // Generic-collector mode: delegate endpoint/headers/protocol to OTLP env vars.
+    return new OTLPTraceExporter({ timeoutMillis: Math.round(config.timeoutS * 1000) });
+}
+/**
+ * Lazy OTLP exporter: the heavyweight node-only OTLP/protobuf chain is
+ * dynamic-imported on first use, so bundling the SDK for an edge runtime (or
+ * injecting a custom spanExporter) never evaluates it at startup — the
+ * top-level evaluation of its CJS dependencies is exactly what breaks ESM
+ * worker bundles.
+ */
+function buildExporter(config) {
+    let loading = null;
+    const load = () => {
+        loading ??= loadOtlpExporter(config).catch(() => {
+            logger_js_1.logger.warn("OTLP exporter unavailable on this runtime; spans will be dropped");
+            return null;
+        });
+        return loading;
+    };
+    return {
+        export(spans, resultCallback) {
+            void load().then((exporter) => {
+                if (exporter === null) {
+                    resultCallback({ code: 0 });
+                    return;
+                }
+                exporter.export(spans, resultCallback);
+            });
+        },
+        async shutdown() {
+            const exporter = loading === null ? null : await loading;
+            await exporter?.shutdown();
+        },
+        async forceFlush() {
+            const exporter = loading === null ? null : await loading;
+            await exporter?.forceFlush?.();
+        },
+    };
+}

package/dist/tracing/ids.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Trace/span ID derivation (SPEC §7.1-7.2).
+ *
+ * Seeded IDs are byte-compatible with Langfuse v4's `create_trace_id` /
+ * `_create_observation_id` (sha256 prefix), deliberately, so trace IDs match
+ * across both backends during a dual-run migration. Conformance:
+ * testdata/conformance/trace-id-v1.json.
+ *
+ * The sync variants are the primary API (atlanClaw exports its deterministic
+ * ids synchronously); they need the isomorph sha256 (node:crypto — present on
+ * Node and workerd-with-nodejs_compat). The async variants cover
+ * WebCrypto-only runtimes.
+ */
+/** Return a 32-lowercase-hex trace ID; deterministic when seeded. */
+export declare function createTraceId(seed?: string): string;
+/** Return a 16-lowercase-hex span ID; deterministic when seeded. */
+export declare function createSpanId(seed?: string): string;
+export declare function createTraceIdAsync(seed?: string): Promise<string>;
+export declare function createSpanIdAsync(seed?: string): Promise<string>;

package/dist/tracing/ids.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Trace/span ID derivation (SPEC §7.1-7.2).
+ *
+ * Seeded IDs are byte-compatible with Langfuse v4's `create_trace_id` /
+ * `_create_observation_id` (sha256 prefix), deliberately, so trace IDs match
+ * across both backends during a dual-run migration. Conformance:
+ * testdata/conformance/trace-id-v1.json.
+ *
+ * The sync variants are the primary API (atlanClaw exports its deterministic
+ * ids synchronously); they need the isomorph sha256 (node:crypto — present on
+ * Node and workerd-with-nodejs_compat). The async variants cover
+ * WebCrypto-only runtimes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTraceId = createTraceId;
+exports.createSpanId = createSpanId;
+exports.createTraceIdAsync = createTraceIdAsync;
+exports.createSpanIdAsync = createSpanIdAsync;
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const isomorph_js_1 = require("./isomorph.js");
+const generator = new sdk_trace_base_1.RandomIdGenerator();
+function hex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function seededBytes(seed, length) {
+    const digest = isomorph_js_1.iso.sha256(seed);
+    if (digest === null) {
+        throw new Error("atlanai: sync seeded ids need node:crypto (Node or workerd nodejs_compat); " +
+            "use createTraceIdAsync/createSpanIdAsync on WebCrypto-only runtimes");
+    }
+    return hex(digest.subarray(0, length));
+}
+async function seededBytesAsync(seed, length) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(seed));
+    return hex(new Uint8Array(digest).subarray(0, length));
+}
+/** Return a 32-lowercase-hex trace ID; deterministic when seeded. */
+function createTraceId(seed) {
+    if (!seed)
+        return generator.generateTraceId();
+    return seededBytes(seed, 16);
+}
+/** Return a 16-lowercase-hex span ID; deterministic when seeded. */
+function createSpanId(seed) {
+    if (!seed)
+        return generator.generateSpanId();
+    return seededBytes(seed, 8);
+}
+async function createTraceIdAsync(seed) {
+    if (!seed)
+        return generator.generateTraceId();
+    return seededBytesAsync(seed, 16);
+}
+async function createSpanIdAsync(seed) {
+    if (!seed)
+        return generator.generateSpanId();
+    return seededBytesAsync(seed, 8);
+}

package/dist/tracing/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @atlanai/sdk — Atlan tracing SDK for TypeScript/JavaScript agents.
+ *
+ * OTel-native second implementation of the agent-sdk.v1 behavior spec
+ * (normative source: the atlanai-sdk-python repo's SPEC.md). Phase 1 ships the
+ * core runtime — init/getClient, the export pipeline (allowlist + enrichment),
+ * propagation, and lifecycle; the span API lands in Phase 2.
+ */
+export { init, getClient, AtlanAI, _resetForTests, type InitOptions, type StartAsCurrentSpanOptions, type StartSpanOptions, type TraceContext, } from "./client.js";
+export { AtlanSpan, noopSpan, resolveSpanType, ROOT_SPAN_CONTEXT_KEY, type ScoreOptions, type UpdateFields, } from "./spans.js";
+export { observe, type ObserveOptions } from "./observe.js";
+export { createSpanId, createSpanIdAsync, createTraceId, createTraceIdAsync } from "./ids.js";
+export { isMessageShaped, serializePayload, toJsonable, truncateUtf8, MAX_DEPTH, TRUNCATION_SUFFIX, } from "./serialize.js";
+export { AtlanConfigError, DEFAULT_BASE_URL, resolveConfig, type ConfigOptions, type Mode, type ResolvedConfig, } from "./config.js";
+export { propagateAttributes, type PropagateAttributesOptions } from "./propagation.js";
+export { VisitorIdentifyError, type IdentifyVisitorOptions, type Visitor, type VisitorType, } from "./visitor.js";
+export { ATLAN_SDK_SCOPE, defaultShouldExport, isAtlanSdkSpan, isGenAiSpan, isKnownInstrumentorSpan, KNOWN_INSTRUMENTATION_SCOPE_PREFIXES, type ShouldExportSpan, } from "./span-filter.js";
+export { AtlanSpanProcessor, type AtlanSpanProcessorOptions } from "./processor.js";
+export { applyMask, MASK_FAILURE_PLACEHOLDER, MaskingSpanExporter, type MaskFunction, type MaskOtelSpansFunction, type OtelSpanData, type OtelSpanKey, type OtelSpanPatch, } from "./masking.js";
+export { SDK_LANGUAGE, SDK_VERSION } from "./version.js";
+export * as semconv from "./semconv.js";

package/dist/tracing/index.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * @atlanai/sdk — Atlan tracing SDK for TypeScript/JavaScript agents.
+ *
+ * OTel-native second implementation of the agent-sdk.v1 behavior spec
+ * (normative source: the atlanai-sdk-python repo's SPEC.md). Phase 1 ships the
+ * core runtime — init/getClient, the export pipeline (allowlist + enrichment),
+ * propagation, and lifecycle; the span API lands in Phase 2.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.semconv = exports.SDK_VERSION = exports.SDK_LANGUAGE = exports.MaskingSpanExporter = exports.MASK_FAILURE_PLACEHOLDER = exports.applyMask = exports.AtlanSpanProcessor = exports.KNOWN_INSTRUMENTATION_SCOPE_PREFIXES = exports.isKnownInstrumentorSpan = exports.isGenAiSpan = exports.isAtlanSdkSpan = exports.defaultShouldExport = exports.ATLAN_SDK_SCOPE = exports.VisitorIdentifyError = exports.propagateAttributes = exports.resolveConfig = exports.DEFAULT_BASE_URL = exports.AtlanConfigError = exports.TRUNCATION_SUFFIX = exports.MAX_DEPTH = exports.truncateUtf8 = exports.toJsonable = exports.serializePayload = exports.isMessageShaped = exports.createTraceIdAsync = exports.createTraceId = exports.createSpanIdAsync = exports.createSpanId = exports.observe = exports.ROOT_SPAN_CONTEXT_KEY = exports.resolveSpanType = exports.noopSpan = exports.AtlanSpan = exports._resetForTests = exports.AtlanAI = exports.getClient = exports.init = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "init", { enumerable: true, get: function () { return client_js_1.init; } });
+Object.defineProperty(exports, "getClient", { enumerable: true, get: function () { return client_js_1.getClient; } });
+Object.defineProperty(exports, "AtlanAI", { enumerable: true, get: function () { return client_js_1.AtlanAI; } });
+Object.defineProperty(exports, "_resetForTests", { enumerable: true, get: function () { return client_js_1._resetForTests; } });
+var spans_js_1 = require("./spans.js");
+Object.defineProperty(exports, "AtlanSpan", { enumerable: true, get: function () { return spans_js_1.AtlanSpan; } });
+Object.defineProperty(exports, "noopSpan", { enumerable: true, get: function () { return spans_js_1.noopSpan; } });
+Object.defineProperty(exports, "resolveSpanType", { enumerable: true, get: function () { return spans_js_1.resolveSpanType; } });
+Object.defineProperty(exports, "ROOT_SPAN_CONTEXT_KEY", { enumerable: true, get: function () { return spans_js_1.ROOT_SPAN_CONTEXT_KEY; } });
+var observe_js_1 = require("./observe.js");
+Object.defineProperty(exports, "observe", { enumerable: true, get: function () { return observe_js_1.observe; } });
+var ids_js_1 = require("./ids.js");
+Object.defineProperty(exports, "createSpanId", { enumerable: true, get: function () { return ids_js_1.createSpanId; } });
+Object.defineProperty(exports, "createSpanIdAsync", { enumerable: true, get: function () { return ids_js_1.createSpanIdAsync; } });
+Object.defineProperty(exports, "createTraceId", { enumerable: true, get: function () { return ids_js_1.createTraceId; } });
+Object.defineProperty(exports, "createTraceIdAsync", { enumerable: true, get: function () { return ids_js_1.createTraceIdAsync; } });
+var serialize_js_1 = require("./serialize.js");
+Object.defineProperty(exports, "isMessageShaped", { enumerable: true, get: function () { return serialize_js_1.isMessageShaped; } });
+Object.defineProperty(exports, "serializePayload", { enumerable: true, get: function () { return serialize_js_1.serializePayload; } });
+Object.defineProperty(exports, "toJsonable", { enumerable: true, get: function () { return serialize_js_1.toJsonable; } });
+Object.defineProperty(exports, "truncateUtf8", { enumerable: true, get: function () { return serialize_js_1.truncateUtf8; } });
+Object.defineProperty(exports, "MAX_DEPTH", { enumerable: true, get: function () { return serialize_js_1.MAX_DEPTH; } });
+Object.defineProperty(exports, "TRUNCATION_SUFFIX", { enumerable: true, get: function () { return serialize_js_1.TRUNCATION_SUFFIX; } });
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "AtlanConfigError", { enumerable: true, get: function () { return config_js_1.AtlanConfigError; } });
+Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return config_js_1.DEFAULT_BASE_URL; } });
+Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_js_1.resolveConfig; } });
+var propagation_js_1 = require("./propagation.js");
+Object.defineProperty(exports, "propagateAttributes", { enumerable: true, get: function () { return propagation_js_1.propagateAttributes; } });
+var visitor_js_1 = require("./visitor.js");
+Object.defineProperty(exports, "VisitorIdentifyError", { enumerable: true, get: function () { return visitor_js_1.VisitorIdentifyError; } });
+var span_filter_js_1 = require("./span-filter.js");
+Object.defineProperty(exports, "ATLAN_SDK_SCOPE", { enumerable: true, get: function () { return span_filter_js_1.ATLAN_SDK_SCOPE; } });
+Object.defineProperty(exports, "defaultShouldExport", { enumerable: true, get: function () { return span_filter_js_1.defaultShouldExport; } });
+Object.defineProperty(exports, "isAtlanSdkSpan", { enumerable: true, get: function () { return span_filter_js_1.isAtlanSdkSpan; } });
+Object.defineProperty(exports, "isGenAiSpan", { enumerable: true, get: function () { return span_filter_js_1.isGenAiSpan; } });
+Object.defineProperty(exports, "isKnownInstrumentorSpan", { enumerable: true, get: function () { return span_filter_js_1.isKnownInstrumentorSpan; } });
+Object.defineProperty(exports, "KNOWN_INSTRUMENTATION_SCOPE_PREFIXES", { enumerable: true, get: function () { return span_filter_js_1.KNOWN_INSTRUMENTATION_SCOPE_PREFIXES; } });
+var processor_js_1 = require("./processor.js");
+Object.defineProperty(exports, "AtlanSpanProcessor", { enumerable: true, get: function () { return processor_js_1.AtlanSpanProcessor; } });
+var masking_js_1 = require("./masking.js");
+Object.defineProperty(exports, "applyMask", { enumerable: true, get: function () { return masking_js_1.applyMask; } });
+Object.defineProperty(exports, "MASK_FAILURE_PLACEHOLDER", { enumerable: true, get: function () { return masking_js_1.MASK_FAILURE_PLACEHOLDER; } });
+Object.defineProperty(exports, "MaskingSpanExporter", { enumerable: true, get: function () { return masking_js_1.MaskingSpanExporter; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "SDK_LANGUAGE", { enumerable: true, get: function () { return version_js_1.SDK_LANGUAGE; } });
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return version_js_1.SDK_VERSION; } });
+exports.semconv = __importStar(require("./semconv.js"));

package/dist/tracing/isomorph.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime capability layer (plan §8 Phase 1).
+ *
+ * v1 targets Node >=20 and Cloudflare Workers **with `nodejs_compat`** — both
+ * resolve `node:async_hooks` and `node:crypto`, so the capabilities below use
+ * static imports and degrade per-capability at runtime (no `process.env` on
+ * workerd → env reads return undefined; no exit hook → flush via waitUntil).
+ * A pure-web build (separate per-runtime entrypoints, Braintrust-style) is a
+ * later increment if ever needed; nothing else in the SDK touches Node APIs
+ * directly — always through `iso`.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+export declare const iso: {
+    /** Environment variable read; undefined where the runtime has no env (workerd). */
+    env(name: string): string | undefined;
+    /** Sync sha256; null when the runtime lacks node:crypto (pure web). */
+    sha256(data: string): Uint8Array | null;
+    newAsyncLocalStorage<T>(): AsyncLocalStorage<T> | null;
+    /** Best-effort process-exit hook (SPEC §10.3); no-op where unsupported. */
+    onExit(callback: () => void): void;
+    isNode(): boolean;
+};

package/dist/tracing/isomorph.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Runtime capability layer (plan §8 Phase 1).
+ *
+ * v1 targets Node >=20 and Cloudflare Workers **with `nodejs_compat`** — both
+ * resolve `node:async_hooks` and `node:crypto`, so the capabilities below use
+ * static imports and degrade per-capability at runtime (no `process.env` on
+ * workerd → env reads return undefined; no exit hook → flush via waitUntil).
+ * A pure-web build (separate per-runtime entrypoints, Braintrust-style) is a
+ * later increment if ever needed; nothing else in the SDK touches Node APIs
+ * directly — always through `iso`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.iso = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = require("node:crypto");
+function nodeProcess() {
+    return globalThis.process;
+}
+exports.iso = {
+    /** Environment variable read; undefined where the runtime has no env (workerd). */
+    env(name) {
+        const value = nodeProcess()?.env?.[name];
+        return value ? value : undefined;
+    },
+    /** Sync sha256; null when the runtime lacks node:crypto (pure web). */
+    sha256(data) {
+        try {
+            return new Uint8Array((0, node_crypto_1.createHash)("sha256").update(data, "utf8").digest());
+        }
+        catch {
+            return null;
+        }
+    },
+    newAsyncLocalStorage() {
+        try {
+            return new node_async_hooks_1.AsyncLocalStorage();
+        }
+        catch {
+            return null;
+        }
+    },
+    /** Best-effort process-exit hook (SPEC §10.3); no-op where unsupported. */
+    onExit(callback) {
+        try {
+            nodeProcess()?.once?.("beforeExit", callback);
+        }
+        catch {
+            // workerd: no process lifecycle — flush() / waitUntil is the contract.
+        }
+    },
+    isNode() {
+        return nodeProcess()?.release?.name === "node";
+    },
+};

package/dist/tracing/logger.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SDK-internal logging. Telemetry failures degrade to logs and never break the
+ * host application (SPEC §10.5); warnings are visible by default, debug output
+ * is opt-in via ATLAN_DEBUG (wired by the client at init).
+ */
+export declare function setDebug(enabled: boolean): void;
+export declare const logger: {
+    warn(message: string): void;
+    debug(message: string): void;
+};

package/dist/tracing/logger.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * SDK-internal logging. Telemetry failures degrade to logs and never break the
+ * host application (SPEC §10.5); warnings are visible by default, debug output
+ * is opt-in via ATLAN_DEBUG (wired by the client at init).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+exports.setDebug = setDebug;
+let debugEnabled = false;
+function setDebug(enabled) {
+    debugEnabled = enabled;
+}
+exports.logger = {
+    warn(message) {
+        try {
+            console.warn(`atlanai: ${message}`);
+        }
+        catch {
+            // a broken console must not break the app
+        }
+    },
+    debug(message) {
+        if (!debugEnabled)
+            return;
+        try {
+            console.debug(`atlanai: ${message}`);
+        }
+        catch {
+            // ignore
+        }
+    },
+};

package/dist/tracing/masking.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Masking hooks (SPEC §8.2, §8.5). Both are fail-closed: a broken hook drops
+ * data, it never leaks it and never breaks the host application.
+ *
+ * Two stages:
+ *
+ * - data-level `mask({data})` — applied to input/output/metadata/tool payloads
+ *   at attribute-creation time; a throwing hook replaces the value with
+ *   MASK_FAILURE_PLACEHOLDER.
+ * - export-stage `maskOtelSpans` — sees whole export batches (including spans
+ *   from third-party instrumentation) as immutable data keyed by
+ *   `"{traceId}:{spanId}"` and returns sparse patches. A throwing or invalid
+ *   hook drops the batch; a single invalid patch drops that span. Patched
+ *   spans are shallow clones — ended spans are never mutated in place.
+ */
+import type { Attributes, AttributeValue } from "@opentelemetry/api";
+import type { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
+import type { ExportResult } from "@opentelemetry/core";
+export declare const MASK_FAILURE_PLACEHOLDER = "[atlan: value withheld - mask hook failed]";
+/** Called as mask({ data: value }); the return value replaces the payload. */
+export type MaskFunction = (params: {
+    data: unknown;
+}) => unknown;
+export declare function applyMask(mask: MaskFunction | undefined, value: unknown): unknown;
+/** `"{traceId}:{spanId}"` — the batch-map key for one span. */
+export type OtelSpanKey = string;
+export interface OtelSpanData {
+    traceId: string;
+    spanId: string;
+    name: string;
+    parentSpanId: string | undefined;
+    instrumentationScope: string;
+    instrumentationScopeVersion: string | undefined;
+    attributes: Readonly<Attributes>;
+    resourceAttributes: Readonly<Attributes>;
+}
+/** Sparse patch: deletes are applied before sets. */
+export interface OtelSpanPatch {
+    setAttributes?: Record<string, AttributeValue>;
+    deleteAttributes?: readonly string[];
+}
+export type MaskOtelSpansFunction = (spans: ReadonlyMap<OtelSpanKey, OtelSpanData>) => ReadonlyMap<OtelSpanKey, OtelSpanPatch> | null | undefined;
+export declare function spanKey(span: ReadableSpan): OtelSpanKey;
+/** Wraps the real exporter; applies the export-stage masking hook per batch. */
+export declare class MaskingSpanExporter implements SpanExporter {
+    private readonly wrapped;
+    private readonly hook;
+    constructor(wrapped: SpanExporter, hook: MaskOtelSpansFunction);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    /** Returns the patched span, or null to drop it (invalid patch). */
+    private applyPatch;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}