@atlanai/sdk 0.1.0

package/dist/tracing/masking.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaskingSpanExporter = exports.MASK_FAILURE_PLACEHOLDER = void 0;
+exports.applyMask = applyMask;
+exports.spanKey = spanKey;
+const core_1 = require("@opentelemetry/core");
+const logger_js_1 = require("./logger.js");
+exports.MASK_FAILURE_PLACEHOLDER = "[atlan: value withheld - mask hook failed]";
+function applyMask(mask, value) {
+    if (mask === undefined)
+        return value;
+    try {
+        return mask({ data: value });
+    }
+    catch {
+        logger_js_1.logger.warn("mask function threw; value fully masked");
+        return exports.MASK_FAILURE_PLACEHOLDER;
+    }
+}
+function spanKey(span) {
+    const context = span.spanContext();
+    return `${context.traceId}:${context.spanId}`;
+}
+function spanData(span) {
+    const context = span.spanContext();
+    return {
+        traceId: context.traceId,
+        spanId: context.spanId,
+        name: span.name,
+        parentSpanId: span.parentSpanContext?.spanId,
+        instrumentationScope: span.instrumentationScope?.name ?? "",
+        instrumentationScopeVersion: span.instrumentationScope?.version,
+        attributes: { ...span.attributes },
+        resourceAttributes: { ...span.resource.attributes },
+    };
+}
+function validAttributeValue(value) {
+    if (typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value))) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.every((item) => typeof item === "string" || typeof item === "boolean" || typeof item === "number");
+    }
+    return false;
+}
+/** Shallow clone carrying replaced attributes; the original span (an ended
+ * SDK Span) is never mutated. */
+function cloneWithAttributes(span, attributes) {
+    return {
+        name: span.name,
+        kind: span.kind,
+        spanContext: () => span.spanContext(),
+        ...(span.parentSpanContext !== undefined ? { parentSpanContext: span.parentSpanContext } : {}),
+        startTime: span.startTime,
+        endTime: span.endTime,
+        status: span.status,
+        attributes,
+        links: span.links,
+        events: span.events,
+        duration: span.duration,
+        ended: span.ended,
+        resource: span.resource,
+        instrumentationScope: span.instrumentationScope,
+        droppedAttributesCount: span.droppedAttributesCount,
+        droppedEventsCount: span.droppedEventsCount,
+        droppedLinksCount: span.droppedLinksCount,
+    };
+}
+/** Wraps the real exporter; applies the export-stage masking hook per batch. */
+class MaskingSpanExporter {
+    wrapped;
+    hook;
+    constructor(wrapped, hook) {
+        this.wrapped = wrapped;
+        this.hook = hook;
+    }
+    export(spans, resultCallback) {
+        let result;
+        try {
+            const batch = new Map();
+            for (const span of spans)
+                batch.set(spanKey(span), spanData(span));
+            result = this.hook(batch);
+        }
+        catch {
+            // Fail closed: a broken hook must never leak an unmasked batch.
+            logger_js_1.logger.warn(`maskOtelSpans threw; dropping batch of ${spans.length} spans`);
+            resultCallback({ code: core_1.ExportResultCode.SUCCESS });
+            return;
+        }
+        if (result === null || result === undefined) {
+            this.wrapped.export(spans, resultCallback);
+            return;
+        }
+        if (!(result instanceof Map)) {
+            logger_js_1.logger.warn(`maskOtelSpans returned ${typeof result} (expected Map or null); ` +
+                `dropping batch of ${spans.length} spans`);
+            resultCallback({ code: core_1.ExportResultCode.SUCCESS });
+            return;
+        }
+        const patches = result;
+        const kept = [];
+        for (const span of spans) {
+            const patch = patches.get(spanKey(span));
+            if (patch === undefined) {
+                kept.push(span);
+                continue;
+            }
+            const patched = this.applyPatch(span, patch);
+            if (patched !== null)
+                kept.push(patched);
+        }
+        if (kept.length === 0) {
+            resultCallback({ code: core_1.ExportResultCode.SUCCESS });
+            return;
+        }
+        this.wrapped.export(kept, resultCallback);
+    }
+    /** Returns the patched span, or null to drop it (invalid patch). */
+    applyPatch(span, patch) {
+        if (patch === null || typeof patch !== "object") {
+            logger_js_1.logger.warn(`invalid patch for span ${span.name}; dropping span`);
+            return null;
+        }
+        const attributes = { ...span.attributes };
+        for (const key of patch.deleteAttributes ?? []) {
+            if (typeof key !== "string") {
+                logger_js_1.logger.warn(`non-string delete key for ${span.name}; dropping span`);
+                return null;
+            }
+            delete attributes[key];
+        }
+        for (const [key, value] of Object.entries(patch.setAttributes ?? {})) {
+            if (!validAttributeValue(value)) {
+                logger_js_1.logger.warn(`invalid setAttributes entry ${key} for span ${span.name}; dropping span`);
+                return null;
+            }
+            attributes[key] = value;
+        }
+        return cloneWithAttributes(span, attributes);
+    }
+    shutdown() {
+        return this.wrapped.shutdown();
+    }
+    forceFlush() {
+        return this.wrapped.forceFlush?.() ?? Promise.resolve();
+    }
+}
+exports.MaskingSpanExporter = MaskingSpanExporter;

package/dist/tracing/observe.d.ts

@@ -0,0 +1,27 @@
+/**
+ * observe() — trace a function as an agent-sdk.v1 observation (plan §7).
+ *
+ * A higher-order function usable on sync functions, async functions,
+ * generators, and async generators. Generator spans stay open across yields
+ * with the span context re-entered around every next() call, so nested spans
+ * created between yields parent correctly. Early consumer close (break /
+ * return()) is normal control flow: the span ends without an output and
+ * without an error.
+ *
+ * TS deviation from the Python decorator (documented in the plan): JS has no
+ * kwargs, so the per-call `atlan_trace_id` magic arguments become the
+ * wrap-time `traceContext` option (pass a function to compute it per call);
+ * dynamic per-call trace ids use client.startAsCurrentSpan directly.
+ */
+import { type TraceContext } from "./client.js";
+export interface ObserveOptions {
+    name?: string;
+    asType?: string;
+    captureInput?: boolean;
+    captureOutput?: boolean;
+    /** Static or per-call ({@link TraceContext} computed from the call args). */
+    traceContext?: TraceContext | ((...args: unknown[]) => TraceContext | undefined);
+}
+type AnyFunction = (...args: any[]) => any;
+export declare function observe<F extends AnyFunction>(fn: F, options?: ObserveOptions): F;
+export {};

package/dist/tracing/observe.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * observe() — trace a function as an agent-sdk.v1 observation (plan §7).
+ *
+ * A higher-order function usable on sync functions, async functions,
+ * generators, and async generators. Generator spans stay open across yields
+ * with the span context re-entered around every next() call, so nested spans
+ * created between yields parent correctly. Early consumer close (break /
+ * return()) is normal control flow: the span ends without an output and
+ * without an error.
+ *
+ * TS deviation from the Python decorator (documented in the plan): JS has no
+ * kwargs, so the per-call `atlan_trace_id` magic arguments become the
+ * wrap-time `traceContext` option (pass a function to compute it per call);
+ * dynamic per-call trace ids use client.startAsCurrentSpan directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observe = observe;
+const api_1 = require("@opentelemetry/api");
+const client_js_1 = require("./client.js");
+function functionKind(fn) {
+    const tag = Object.prototype.toString.call(fn);
+    if (tag === "[object AsyncGeneratorFunction]")
+        return "async-gen";
+    if (tag === "[object GeneratorFunction]")
+        return "gen";
+    if (tag === "[object AsyncFunction]")
+        return "async";
+    return "sync";
+}
+function resolveTraceContext(option, args) {
+    if (typeof option === "function") {
+        try {
+            return option(...args);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return option;
+}
+function captureArgs(args) {
+    return { args };
+}
+function observe(fn, options = {}) {
+    const spanName = options.name ?? (fn.name || "observed");
+    const asType = options.asType ?? "task";
+    const captureInput = options.captureInput ?? true;
+    const captureOutput = options.captureOutput ?? true;
+    const kind = functionKind(fn);
+    if (kind === "gen") {
+        function* generatorWrapper(...args) {
+            const client = (0, client_js_1.getClient)();
+            if (!client.isEnabled) {
+                yield* fn.apply(this, args);
+                return;
+            }
+            const traceContext = resolveTraceContext(options.traceContext, args);
+            const span = client.startSpan(spanName, traceContext ? { asType, traceContext } : { asType });
+            if (captureInput)
+                span.update({ input: captureArgs(args) });
+            const spanContext = api_1.trace.setSpan(api_1.context.active(), span.otelSpan);
+            const items = [];
+            let completed = false;
+            try {
+                const generator = fn.apply(this, args);
+                for (;;) {
+                    const step = api_1.context.with(spanContext, () => generator.next());
+                    if (step.done)
+                        break;
+                    items.push(step.value);
+                    yield step.value;
+                }
+                completed = true;
+                if (captureOutput)
+                    span.update({ output: items });
+            }
+            catch (error) {
+                span.recordFailure(error);
+                throw error;
+            }
+            finally {
+                void completed;
+                span.end();
+            }
+        }
+        return wrapIdentity(generatorWrapper, fn);
+    }
+    if (kind === "async-gen") {
+        async function* asyncGeneratorWrapper(...args) {
+            const client = (0, client_js_1.getClient)();
+            if (!client.isEnabled) {
+                yield* fn.apply(this, args);
+                return;
+            }
+            const traceContext = resolveTraceContext(options.traceContext, args);
+            const span = client.startSpan(spanName, traceContext ? { asType, traceContext } : { asType });
+            if (captureInput)
+                span.update({ input: captureArgs(args) });
+            const spanContext = api_1.trace.setSpan(api_1.context.active(), span.otelSpan);
+            const items = [];
+            try {
+                const generator = fn.apply(this, args);
+                for (;;) {
+                    const step = await api_1.context.with(spanContext, () => generator.next());
+                    if (step.done)
+                        break;
+                    items.push(step.value);
+                    yield step.value;
+                }
+                if (captureOutput)
+                    span.update({ output: items });
+            }
+            catch (error) {
+                span.recordFailure(error);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        }
+        return wrapIdentity(asyncGeneratorWrapper, fn);
+    }
+    function wrapper(...args) {
+        const client = (0, client_js_1.getClient)();
+        if (!client.isEnabled)
+            return fn.apply(this, args);
+        const traceContext = resolveTraceContext(options.traceContext, args);
+        return client.startAsCurrentSpan(spanName, { asType, ...(traceContext ? { traceContext } : {}) }, (span) => {
+            if (captureInput)
+                span.update({ input: captureArgs(args) });
+            const result = fn.apply(this, args);
+            if (result instanceof Promise) {
+                return result.then((value) => {
+                    if (captureOutput)
+                        span.update({ output: value });
+                    return value;
+                });
+            }
+            if (captureOutput)
+                span.update({ output: result });
+            return result;
+        });
+    }
+    return wrapIdentity(wrapper, fn);
+}
+function wrapIdentity(wrapper, original) {
+    try {
+        Object.defineProperty(wrapper, "name", { value: original.name, configurable: true });
+        Object.defineProperty(wrapper, "length", { value: original.length, configurable: true });
+    }
+    catch {
+        // identity metadata is cosmetic
+    }
+    return wrapper;
+}

package/dist/tracing/processor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The SDK span processor (SPEC §4, §6.2).
+ *
+ * Composes a BatchSpanProcessor tuned for GenAI span weight (default batch 64,
+ * not OTel's 512) — or a SimpleSpanProcessor in debug/immediate mode — and
+ * (a) stamps propagated attributes onto every span at start, including spans
+ * created by third-party instrumentation sharing the provider, and (b) applies
+ * the export allowlist at end. Filtering affects export only; filtered spans
+ * still parent children normally (SPEC §4.4). Composition (not subclassing)
+ * keeps the batch/simple swap a one-line decision and never depends on OTel
+ * SDK internals.
+ */
+import type { Context } from "@opentelemetry/api";
+import { type ReadableSpan, type Span, type SpanExporter, type SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { type MaskFunction } from "./masking.js";
+import { type ShouldExportSpan } from "./span-filter.js";
+export interface AtlanSpanProcessorOptions {
+    flushAt?: number;
+    flushIntervalS?: number;
+    timeoutS?: number;
+    shouldExportSpan?: ShouldExportSpan | undefined;
+    traceContent?: boolean;
+    /** SPEC §8.2: the data-level mask also covers propagated metadata. */
+    mask?: MaskFunction | undefined;
+    /** "immediate" swaps the batcher for a SimpleSpanProcessor (serverless/debug). */
+    exportMode?: "batch" | "immediate";
+}
+export declare class AtlanSpanProcessor implements SpanProcessor {
+    private readonly inner;
+    private readonly shouldExport;
+    private readonly traceContent;
+    private readonly mask;
+    constructor(exporter: SpanExporter, options?: AtlanSpanProcessorOptions);
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/tracing/processor.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * The SDK span processor (SPEC §4, §6.2).
+ *
+ * Composes a BatchSpanProcessor tuned for GenAI span weight (default batch 64,
+ * not OTel's 512) — or a SimpleSpanProcessor in debug/immediate mode — and
+ * (a) stamps propagated attributes onto every span at start, including spans
+ * created by third-party instrumentation sharing the provider, and (b) applies
+ * the export allowlist at end. Filtering affects export only; filtered spans
+ * still parent children normally (SPEC §4.4). Composition (not subclassing)
+ * keeps the batch/simple swap a one-line decision and never depends on OTel
+ * SDK internals.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtlanSpanProcessor = void 0;
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const logger_js_1 = require("./logger.js");
+const masking_js_1 = require("./masking.js");
+const propagation_js_1 = require("./propagation.js");
+const semconv_js_1 = require("./semconv.js");
+const span_filter_js_1 = require("./span-filter.js");
+class AtlanSpanProcessor {
+    inner;
+    shouldExport;
+    traceContent;
+    mask;
+    constructor(exporter, options = {}) {
+        this.shouldExport = options.shouldExportSpan ?? span_filter_js_1.defaultShouldExport;
+        this.traceContent = options.traceContent ?? true;
+        this.mask = options.mask;
+        this.inner =
+            options.exportMode === "immediate"
+                ? new sdk_trace_base_1.SimpleSpanProcessor(exporter)
+                : new sdk_trace_base_1.BatchSpanProcessor(exporter, {
+                    maxExportBatchSize: options.flushAt ?? 64,
+                    scheduledDelayMillis: Math.round((options.flushIntervalS ?? 5) * 1000),
+                    exportTimeoutMillis: Math.round((options.timeoutS ?? 30) * 1000),
+                });
+    }
+    onStart(span, parentContext) {
+        try {
+            const attributes = (0, propagation_js_1.propagatedAttributesFromContext)(parentContext, this.traceContent);
+            if (this.mask !== undefined) {
+                // SPEC §8.2: the data-level mask also covers propagated metadata.
+                for (const key of Object.keys(attributes)) {
+                    if (!key.startsWith(semconv_js_1.ATLAN_METADATA_PREFIX))
+                        continue;
+                    const masked = (0, masking_js_1.applyMask)(this.mask, attributes[key]);
+                    attributes[key] =
+                        typeof masked === "string" || typeof masked === "number" || typeof masked === "boolean"
+                            ? masked
+                            : (JSON.stringify(masked) ?? "null");
+                }
+            }
+            if (Object.keys(attributes).length > 0)
+                span.setAttributes(attributes);
+        }
+        catch {
+            // never break user spans on enrichment bugs (SPEC §10.5)
+            logger_js_1.logger.debug("propagated-attribute stamping failed");
+        }
+        this.inner.onStart(span, parentContext);
+    }
+    onEnd(span) {
+        let keep;
+        try {
+            keep = Boolean(this.shouldExport(span));
+        }
+        catch {
+            // SPEC §4.3: a throwing predicate drops the span, never propagates.
+            logger_js_1.logger.warn("shouldExportSpan threw; dropping span");
+            return;
+        }
+        if (keep)
+            this.inner.onEnd(span);
+    }
+    forceFlush() {
+        return this.inner.forceFlush();
+    }
+    shutdown() {
+        return this.inner.shutdown();
+    }
+}
+exports.AtlanSpanProcessor = AtlanSpanProcessor;

package/dist/tracing/propagation.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Propagated attributes (SPEC §6).
+ *
+ * `propagateAttributes(attrs, fn)` writes values into OTel context under
+ * `atlan.propagated.*` keys and onto the currently active span, then runs `fn`
+ * inside that context; the SDK's span processor stamps them onto every span
+ * started inside the scope — including spans created by third-party
+ * instrumentation.
+ *
+ * Merge precedence (highest wins): explicit API argument on a span > nearest
+ * enclosing scope > outer scopes. Metadata objects merge per-key; tag lists
+ * union with de-duplication preserving first-seen order.
+ */
+import { type Context } from "@opentelemetry/api";
+export type PropagatedAttributeValue = string | number | boolean | string[];
+export interface PropagateAttributesOptions {
+    sessionId?: string;
+    userId?: string;
+    visitorId?: string;
+    tags?: readonly string[];
+    metadata?: Record<string, unknown>;
+    traceName?: string;
+}
+/**
+ * Flatten one level to `atlan.metadata.{key}` attributes (SPEC §6.3):
+ * string/number/boolean values stay native; everything else JSON-serialized.
+ * Serialization failures degrade to String(value) — never throw.
+ */
+export declare function flattenMetadata(metadata: Record<string, unknown>): Record<string, string | number | boolean>;
+/**
+ * Build the attribute set the processor stamps in onStart (SPEC §6.2).
+ * `includeContent=false` (the SPEC §8.1 content switch) omits the
+ * content-classified metadata family; session/user/tags/trace-name are not
+ * content and are always included.
+ */
+export declare function propagatedAttributesFromContext(context: Context, includeContent?: boolean): Record<string, PropagatedAttributeValue>;
+/** Attach association attributes to every span started while `fn` runs. */
+export declare function propagateAttributes<T>(options: PropagateAttributesOptions, fn: () => T): T;

package/dist/tracing/propagation.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * Propagated attributes (SPEC §6).
+ *
+ * `propagateAttributes(attrs, fn)` writes values into OTel context under
+ * `atlan.propagated.*` keys and onto the currently active span, then runs `fn`
+ * inside that context; the SDK's span processor stamps them onto every span
+ * started inside the scope — including spans created by third-party
+ * instrumentation.
+ *
+ * Merge precedence (highest wins): explicit API argument on a span > nearest
+ * enclosing scope > outer scopes. Metadata objects merge per-key; tag lists
+ * union with de-duplication preserving first-seen order.
+ */
+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.flattenMetadata = flattenMetadata;
+exports.propagatedAttributesFromContext = propagatedAttributesFromContext;
+exports.propagateAttributes = propagateAttributes;
+const api_1 = require("@opentelemetry/api");
+const logger_js_1 = require("./logger.js");
+const sc = __importStar(require("./semconv.js"));
+const MAX_PROPAGATED_VALUE_CHARS = 200;
+const SESSION_ID_KEY = (0, api_1.createContextKey)("atlan.propagated.session_id");
+const USER_ID_KEY = (0, api_1.createContextKey)("atlan.propagated.user_id");
+const VISITOR_ID_KEY = (0, api_1.createContextKey)("atlan.propagated.visitor_id");
+const TAGS_KEY = (0, api_1.createContextKey)("atlan.propagated.tags");
+const METADATA_KEY = (0, api_1.createContextKey)("atlan.propagated.metadata");
+const TRACE_NAME_KEY = (0, api_1.createContextKey)("atlan.propagated.trace_name");
+function validShortString(name, value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string") {
+        logger_js_1.logger.warn(`dropping non-string ${name}=${JSON.stringify(value) ?? typeof value}`);
+        return undefined;
+    }
+    if (value.length > MAX_PROPAGATED_VALUE_CHARS) {
+        logger_js_1.logger.warn(`dropping ${name} longer than ${MAX_PROPAGATED_VALUE_CHARS} chars`);
+        return undefined;
+    }
+    return value;
+}
+function validTags(tags) {
+    if (!tags)
+        return [];
+    const kept = [];
+    for (const tag of tags) {
+        const checked = validShortString("tag", tag);
+        if (checked !== undefined && !kept.includes(checked))
+            kept.push(checked);
+    }
+    return kept;
+}
+/**
+ * Flatten one level to `atlan.metadata.{key}` attributes (SPEC §6.3):
+ * string/number/boolean values stay native; everything else JSON-serialized.
+ * Serialization failures degrade to String(value) — never throw.
+ */
+function flattenMetadata(metadata) {
+    const flattened = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        const attr = `${sc.ATLAN_METADATA_PREFIX}${key}`;
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            flattened[attr] = value;
+        }
+        else {
+            try {
+                flattened[attr] = JSON.stringify(value) ?? String(value);
+            }
+            catch {
+                flattened[attr] = String(value);
+            }
+        }
+    }
+    return flattened;
+}
+/**
+ * Build the attribute set the processor stamps in onStart (SPEC §6.2).
+ * `includeContent=false` (the SPEC §8.1 content switch) omits the
+ * content-classified metadata family; session/user/tags/trace-name are not
+ * content and are always included.
+ */
+function propagatedAttributesFromContext(context, includeContent = true) {
+    const attributes = {};
+    const sessionId = context.getValue(SESSION_ID_KEY);
+    if (typeof sessionId === "string")
+        attributes[sc.SESSION_ID] = sessionId;
+    const userId = context.getValue(USER_ID_KEY);
+    if (typeof userId === "string")
+        attributes[sc.USER_ID] = userId;
+    const visitorId = context.getValue(VISITOR_ID_KEY);
+    if (typeof visitorId === "string")
+        attributes[sc.ATLAN_VISITOR_ID] = visitorId;
+    const tags = context.getValue(TAGS_KEY);
+    if (Array.isArray(tags) && tags.length > 0)
+        attributes[sc.ATLAN_TAGS] = [...tags];
+    if (includeContent) {
+        const metadata = context.getValue(METADATA_KEY);
+        if (metadata && typeof metadata === "object") {
+            Object.assign(attributes, flattenMetadata(metadata));
+        }
+    }
+    const traceName = context.getValue(TRACE_NAME_KEY);
+    if (typeof traceName === "string")
+        attributes[sc.ATLAN_TRACE_NAME] = traceName;
+    return attributes;
+}
+/** Attach association attributes to every span started while `fn` runs. */
+function propagateAttributes(options, fn) {
+    let context = api_1.context.active();
+    const sessionId = validShortString("sessionId", options.sessionId);
+    if (sessionId !== undefined)
+        context = context.setValue(SESSION_ID_KEY, sessionId);
+    const userId = validShortString("userId", options.userId);
+    if (userId !== undefined)
+        context = context.setValue(USER_ID_KEY, userId);
+    const visitorId = validShortString("visitorId", options.visitorId);
+    if (visitorId !== undefined)
+        context = context.setValue(VISITOR_ID_KEY, visitorId);
+    const newTags = validTags(options.tags);
+    if (newTags.length > 0) {
+        const existing = context.getValue(TAGS_KEY);
+        const merged = Array.isArray(existing)
+            ? existing.filter((tag) => typeof tag === "string")
+            : [];
+        for (const tag of newTags)
+            if (!merged.includes(tag))
+                merged.push(tag);
+        context = context.setValue(TAGS_KEY, merged);
+    }
+    if (options.metadata && Object.keys(options.metadata).length > 0) {
+        const existing = context.getValue(METADATA_KEY);
+        const base = existing && typeof existing === "object" ? { ...existing } : {};
+        Object.assign(base, options.metadata);
+        context = context.setValue(METADATA_KEY, base);
+    }
+    const traceName = validShortString("traceName", options.traceName);
+    if (traceName !== undefined)
+        context = context.setValue(TRACE_NAME_KEY, traceName);
+    // SPEC §6.1(b): also stamp the currently active span immediately.
+    const current = api_1.trace.getSpan(context);
+    if (current?.isRecording()) {
+        current.setAttributes(propagatedAttributesFromContext(context));
+    }
+    return api_1.context.with(context, fn);
+}