@armoriq/sdk-dev 0.8.5 → 0.8.7

package/dist/observability/otel-runtime.d.ts

@@ -1,8 +1,10 @@
 /** SDK-owned OpenTelemetry runtime. It never registers a global provider. */
-import type { Tracer } from '@opentelemetry/api';
+import { type Span, type SpanOptions, type Tracer } from '@opentelemetry/api';
 import { type ObservabilityOptions, type ResolvedOtelConfig } from './otel-config';
-import { type PolicyLease } from './policy-lease';
+import { type PolicyLease, type PolicyLeaseStore } from './policy-lease';
 import { type ContentCaptureAuthority } from './content-capture';
+import { type SpanSink } from './otel-span-spool';
+import { type SpooledExportResult } from './otel-spool-export';
 export type TelemetryAttributeValue = string | number | boolean | string[];
 export type TelemetryAttributes = Readonly<Record<string, unknown>>;
 export interface AttributeContext {
@@ -18,7 +20,19 @@ export interface TelemetryRuntimeOptions {
     options?: ObservabilityOptions;
     /** Test/host hook; production defaults to the policy-lease HTTP endpoint. */
     leaseFetcher?: (signal?: AbortSignal) => Promise<PolicyLease>;
+    leaseStore?: PolicyLeaseStore;
+    /** Takes the place of the OTLP request for the `armoriq` exporter. */
+    spanSink?: SpanSink;
 }
+export interface SpanIds {
+    traceId: string;
+    spanId: string;
+}
+/**
+ * Only a tracer from the runtime's own provider honors the ids; a
+ * caller-owned provider assigns its own.
+ */
+export declare function startRootSpanWithIds(runtime: ArmorIQTelemetryRuntime, tracer: Tracer, name: string, options: SpanOptions, ids: SpanIds): Span;
 /**
  * Manages one private exporter, or borrows a caller-owned provider. A runtime
  * is request/session scoped and `close()` is idempotent and fail-open.
@@ -29,21 +43,38 @@ export declare class ArmorIQTelemetryRuntime {
     private readonly apiKey;
     private readonly sdkVersion;
     private readonly leaseFetcher?;
+    private readonly leaseStore?;
+    private readonly spanSink?;
+    private readonly leaseBinding;
+    private readonly spoolKey;
+    private readonly storeAbort;
     private lease;
     private refreshing;
     private firstExternalAuthorityAwaited;
     private externalAuthorityUnavailable;
     private nextRefreshAt;
     private provider;
+    private exporter;
     private policyLeaseAbort;
-    private readonly ownedAgents;
+    private transport;
+    private readonly spoolCalls;
+    private readonly spoolSlots;
     private closed;
     constructor(options: TelemetryRuntimeOptions);
+    currentOrFreshSnapshot(): Promise<PolicyLease>;
     policySnapshot(options?: {
         awaitFresh?: boolean;
     }): Promise<PolicyLease>;
+    /**
+     * Resolves at once while a current lease is held. Otherwise it adopts a
+     * current lease from the store, or waits for a lease request: the real
+     * lease, or the fallback after a failure or the request's 5 s abort.
+     */
+    refreshPolicy(): Promise<void>;
+    private adoptStoredLease;
     /** Start at most one control-plane request; request callers never await it. */
     private refreshInBackground;
+    private startRefresh;
     private applyCeiling;
     /**
      * The ceiling-applied lease this runtime already knows about, computed
@@ -78,9 +109,14 @@ export declare class ArmorIQTelemetryRuntime {
      * time for a disallowed capture mode.
      */
     reapplyContentCeiling(snapshot: PolicyLease, attributes: TelemetryAttributes): Record<string, TelemetryAttributeValue>;
+    private storeLease;
     private fetchPolicyLease;
     tracer(snapshot: PolicyLease): Tracer | null;
     private privateProvider;
+    private resource;
+    private pipelineExporter;
+    private firstPartyTracesUrl;
+    private ownedTransport;
     /**
      * Construct the OTLP delegate from explicit values. The convenience
      * exporter reads process.env while merging defaults, which could leak a
@@ -98,6 +134,20 @@ export declare class ArmorIQTelemetryRuntime {
     /** Stable, externally safe root span names prevent identifier leakage. */
     externalTraceName(value: string): string;
     forceFlush(): Promise<void>;
-    close(): Promise<void>;
+    /** Process-exit drain: a bounded flush that then fails what is still in flight; the runtime stays open. */
+    drainForExit(): Promise<void>;
+    private drainExports;
+    /** The `binding` of every batch this runtime's `spanSink` receives. */
+    get spoolBinding(): string;
+    /**
+     * Ships batches this runtime's `spanSink` wrote, one OTLP request each,
+     * under its current authoritative lease. Resolves to one result per entry of
+     * `batches`, in order.
+     */
+    exportSpooled(batches: readonly unknown[]): Promise<SpooledExportResult[]>;
+    private openSpoolCall;
+    private shipSpooled;
+    private shippedAttributes;
+    close(deadlineMs?: number): Promise<void>;
 }
 //# sourceMappingURL=otel-runtime.d.ts.map

package/dist/observability/otel-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"otel-runtime.d.ts","sourceRoot":"","sources":["../../src/observability/otel-runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"otel-runtime.d.ts","sourceRoot":"","sources":["../../src/observability/otel-runtime.ts"],"names":[],"mappings":"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"}

package/dist/observability/otel-runtime.js

@@ -2,6 +2,8 @@
 /** SDK-owned OpenTelemetry runtime. It never registers a global provider. */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArmorIQTelemetryRuntime = void 0;
+exports.startRootSpanWithIds = startRootSpanWithIds;
+const api_1 = require("@opentelemetry/api");
 const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
 const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
 const resources_1 = require("@opentelemetry/resources");
@@ -13,6 +15,9 @@ const policy_lease_1 = require("./policy-lease");
 const content_capture_1 = require("./content-capture");
 const otel_shutdown_1 = require("./otel-shutdown");
 const otel_export_ceiling_1 = require("./otel-export-ceiling");
+const otlp_http_transport_1 = require("./otlp-http-transport");
+const otel_span_spool_1 = require("./otel-span-spool");
+const otel_spool_export_1 = require("./otel-spool-export");
 const SENSITIVE_KEY = /(?:api[_-]?key|auth(?:orization)?|bearer|cookie|credential|password|passphrase|secret|private[_-]?key|ssn|card(?:_number)?)/i;
 const SECRET_TOKEN_KEY = /(?:^|[_.-])token(?:$|[_.-])/i;
 const USAGE_TOKEN_KEY = /^gen_ai\.usage\.(?:input|output|cache_read|cache_write)_tokens$/;
@@ -37,7 +42,7 @@ const MAX_FINISH_REASONS = 16;
 const MAX_FINISH_REASON_CANDIDATES = 64;
 const SENSITIVE_VALUE = /(?:\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b|\b(?:ak|sk|pk|rk|ghp|github_pat)_[A-Za-z0-9_-]{12,}\b|-----BEGIN [A-Z0-9 ]+-----)/i;
 const EMAIL = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i;
-const CONTENT_KEY = /^(?:armoriq\.(?:content\.|observability\.error\.summary$)|gen_ai\.(?:prompt|completion|input\.messages|output\.messages|tool\.(?:args|arguments|result|call\.(?:arguments|result))))$/;
+const CONTENT_KEY = /^(?:armoriq\.(?:content\..*|observability\.error\.summary)|gen_ai\.(?:prompt|completion|input\.messages|output\.messages|tool\.(?:args|arguments|result|call\.(?:arguments|result))))$/;
 const EXTERNAL_METADATA_ATTRIBUTES = new Set([
     'gen_ai.request.model',
     'gen_ai.response.model',
@@ -118,7 +123,46 @@ const EXTERNAL_CONTENT_ATTRIBUTES = new Set([
     'gen_ai.tool.call.arguments', 'gen_ai.tool.call.result',
 ]);
 const CLOSE_DEADLINE_MS = 1_500;
+const EXPORT_CONCURRENCY_LIMIT = 30;
+const MAX_TIMER_MS = 2_147_483_647;
 const FIRST_EXTERNAL_AUTHORITY_WAIT_MS = 1_400;
+const SPOOL_EXPORT_CONCURRENCY = 8;
+const TRACER_NAME = 'armoriq-sdk';
+class PresetIdGenerator {
+    random = new sdk_trace_base_1.RandomIdGenerator();
+    preset = null;
+    generateTraceId() {
+        return this.preset?.traceId ?? this.random.generateTraceId();
+    }
+    generateSpanId() {
+        return this.preset?.spanId ?? this.random.generateSpanId();
+    }
+    withIds(ids, start) {
+        this.preset = ids;
+        try {
+            return start();
+        }
+        finally {
+            this.preset = null;
+        }
+    }
+}
+const presetIdGenerators = new WeakMap();
+function presetIdGenerator(runtime) {
+    const existing = presetIdGenerators.get(runtime);
+    if (existing)
+        return existing;
+    const created = new PresetIdGenerator();
+    presetIdGenerators.set(runtime, created);
+    return created;
+}
+/**
+ * Only a tracer from the runtime's own provider honors the ids; a
+ * caller-owned provider assigns its own.
+ */
+function startRootSpanWithIds(runtime, tracer, name, options, ids) {
+    return presetIdGenerator(runtime).withIds(ids, () => tracer.startSpan(name, options, api_1.ROOT_CONTEXT));
+}
 function bounded(promise, timeoutMillis = CLOSE_DEADLINE_MS) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => resolve(undefined), timeoutMillis);
@@ -131,6 +175,9 @@ function bounded(promise, timeoutMillis = CLOSE_DEADLINE_MS) {
         });
     });
 }
+function validDeadline(value) {
+    return value > 0 ? Math.min(value, MAX_TIMER_MS) : CLOSE_DEADLINE_MS;
+}
 function cleanString(value, length = 256) {
     if (SENSITIVE_VALUE.test(value))
         return '[REDACTED:CREDENTIAL]';
@@ -180,9 +227,27 @@ function safeValue(key, value, external) {
 function validExternalId(value) {
     return /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,127}$/.test(value) && (0, otel_config_1.sanitizeExternalTelemetryValue)(value, 128) !== undefined;
 }
+function sessionIdentity(context, external) {
+    const identity = {};
+    if (external) {
+        const sessionId = (0, otel_config_1.sanitizeExternalTelemetryValue)(context.sessionId, 128);
+        if (sessionId)
+            identity['session.id'] = sessionId;
+        if (context.userId && validExternalId(context.userId))
+            identity['user.id'] = context.userId;
+        return identity;
+    }
+    const sessionId = safeValue('armoriq.session_id', context.sessionId, false);
+    if (sessionId !== undefined)
+        identity['armoriq.session_id'] = sessionId;
+    return identity;
+}
 function hasOwn(value, key) {
     return Object.prototype.hasOwnProperty.call(value, key);
 }
+function holdsCurrentAuthority(lease) {
+    return Boolean(lease?.authoritative && (0, policy_lease_1.isLeaseCurrent)(lease));
+}
 /**
  * Manages one private exporter, or borrows a caller-owned provider. A runtime
  * is request/session scoped and `close()` is idempotent and fail-open.
@@ -193,14 +258,22 @@ class ArmorIQTelemetryRuntime {
     apiKey;
     sdkVersion;
     leaseFetcher;
+    leaseStore;
+    spanSink;
+    leaseBinding;
+    spoolKey;
+    storeAbort = new AbortController();
     lease = null;
     refreshing = null;
     firstExternalAuthorityAwaited = false;
     externalAuthorityUnavailable = false;
     nextRefreshAt = 0;
     provider = null;
+    exporter = null;
     policyLeaseAbort = null;
-    ownedAgents = new Set();
+    transport = null;
+    spoolCalls = new Set();
+    spoolSlots = new otel_spool_export_1.ExportSlots(SPOOL_EXPORT_CONCURRENCY);
     closed = false;
     constructor(options) {
         this.config = (0, otel_config_1.resolveOtelConfig)(options.options);
@@ -208,17 +281,24 @@ class ArmorIQTelemetryRuntime {
         this.apiKey = options.apiKey;
         this.sdkVersion = options.sdkVersion;
         this.leaseFetcher = options.leaseFetcher;
+        this.leaseStore = options.leaseStore;
+        this.spanSink = options.spanSink;
+        this.leaseBinding = (0, policy_lease_1.policyLeaseBinding)(this.backendEndpoint, options.apiKey);
+        this.spoolKey = { apiKey: options.apiKey, binding: this.leaseBinding };
         if (this.config.enabled && this.config.exporter !== 'provider') {
             (0, otel_shutdown_1.registerOwnedTelemetryRuntime)(this);
         }
     }
+    async currentOrFreshSnapshot() {
+        return this.policySnapshot({ awaitFresh: !holdsCurrentAuthority(this.lease) });
+    }
     async policySnapshot(options = {}) {
         if (!this.config.enabled || this.closed)
             return Object.freeze({ ...(0, policy_lease_1.fallbackPolicyLease)(), captureMode: 'off' });
         if (this.externalAuthorityUnavailable && this.config.exporter === 'external') {
             return Object.freeze({ ...(0, policy_lease_1.fallbackPolicyLease)(), captureMode: 'off' });
         }
-        if (!options.awaitFresh && this.lease?.authoritative && (0, policy_lease_1.isLeaseCurrent)(this.lease))
+        if (!options.awaitFresh && holdsCurrentAuthority(this.lease))
             return this.applyCeiling(this.lease);
         const refresh = this.refreshInBackground(options.awaitFresh === true);
         const mustAwaitExternalAuthority = this.config.exporter === 'external' && !this.firstExternalAuthorityAwaited;
@@ -242,16 +322,40 @@ class ArmorIQTelemetryRuntime {
         }
         return this.applyCeiling(this.lease && (0, policy_lease_1.isLeaseCurrent)(this.lease) ? this.lease : (0, policy_lease_1.fallbackPolicyLease)());
     }
+    /**
+     * Resolves at once while a current lease is held. Otherwise it adopts a
+     * current lease from the store, or waits for a lease request: the real
+     * lease, or the fallback after a failure or the request's 5 s abort.
+     */
+    async refreshPolicy() {
+        if (!this.config.enabled || this.closed || holdsCurrentAuthority(this.lease))
+            return;
+        await this.adoptStoredLease();
+        if (this.closed || holdsCurrentAuthority(this.lease))
+            return;
+        await (this.refreshing ?? this.startRefresh());
+    }
+    async adoptStoredLease() {
+        if (!this.leaseStore)
+            return;
+        const stored = await (0, policy_lease_1.readStoredPolicyLease)(this.leaseStore, this.leaseBinding, this.storeAbort.signal);
+        if (stored && !holdsCurrentAuthority(this.lease))
+            this.lease = stored;
+    }
     /** Start at most one control-plane request; request callers never await it. */
     refreshInBackground(force = false) {
         if (this.refreshing)
             return this.refreshing;
         if (!force && Date.now() < this.nextRefreshAt)
             return null;
+        return this.startRefresh();
+    }
+    startRefresh() {
         this.nextRefreshAt = Date.now() + 1_000;
         this.refreshing = this.fetchPolicyLease()
             .then((lease) => {
             this.lease = lease;
+            this.storeLease(lease);
             return lease;
         })
             .finally(() => {
@@ -420,6 +524,11 @@ class ArmorIQTelemetryRuntime {
         next['armoriq.observability.policy.revision'] = snapshot.revision;
         return next;
     }
+    storeLease(lease) {
+        if (!lease.authoritative || !this.leaseStore)
+            return;
+        (0, policy_lease_1.writeStoredPolicyLease)(this.leaseStore, lease, this.leaseBinding, this.storeAbort.signal);
+    }
     async fetchPolicyLease() {
         const controller = new AbortController();
         this.policyLeaseAbort = controller;
@@ -450,9 +559,9 @@ class ArmorIQTelemetryRuntime {
             return null;
         try {
             if (this.config.exporter === 'provider') {
-                return this.config.tracerProvider?.getTracer('armoriq-sdk', this.sdkVersion) ?? null;
+                return this.config.tracerProvider?.getTracer(TRACER_NAME, this.sdkVersion) ?? null;
             }
-            return this.privateProvider()?.getTracer('armoriq-sdk', this.sdkVersion) ?? null;
+            return this.privateProvider()?.getTracer(TRACER_NAME, this.sdkVersion) ?? null;
         }
         catch {
             return null;
@@ -461,18 +570,14 @@ class ArmorIQTelemetryRuntime {
     privateProvider() {
         if (this.provider || this.closed || !this.config.enabled)
             return this.provider;
-        const isExternal = this.config.exporter === 'external';
-        const url = isExternal ? this.config.endpoint : `${this.backendEndpoint}/v1/traces`;
-        if (!url)
-            return null;
         try {
-            const exporter = this.createExporter(url, isExternal ? this.config.headers : { 'x-api-key': this.apiKey });
+            const exporter = this.pipelineExporter();
+            if (!exporter)
+                return null;
+            this.exporter = exporter;
             this.provider = new sdk_trace_node_1.NodeTracerProvider({
-                resource: (0, resources_1.resourceFromAttributes)({
-                    'service.name': this.config.serviceName,
-                    'service.version': this.sdkVersion,
-                    ...this.config.resourceAttributes,
-                }),
+                idGenerator: presetIdGenerator(this),
+                resource: this.resource(),
                 // A span queued under a permissive lease may still be sitting in
                 // BatchSpanProcessor's in-memory buffer when the lease becomes
                 // stricter (or is revoked). Wrap both the exporter -- the true
@@ -483,7 +588,7 @@ class ArmorIQTelemetryRuntime {
                 // not whatever was authoritative at creation time, governs what
                 // actually ships.
                 spanProcessors: [
-                    new otel_export_ceiling_1.CeilingReapplyingSpanProcessor(new sdk_trace_base_1.BatchSpanProcessor(new otel_export_ceiling_1.CeilingReapplyingSpanExporter(exporter, this), { exportTimeoutMillis: Math.min(this.config.timeoutMillis, CLOSE_DEADLINE_MS) }), this),
+                    new otel_export_ceiling_1.CeilingReapplyingSpanProcessor(new sdk_trace_base_1.BatchSpanProcessor(new otel_export_ceiling_1.CeilingReapplyingSpanExporter(exporter, this), { exportTimeoutMillis: this.config.timeoutMillis }), this),
                 ],
             });
             return this.provider;
@@ -492,28 +597,50 @@ class ArmorIQTelemetryRuntime {
             return null;
         }
     }
+    resource() {
+        return (0, resources_1.resourceFromAttributes)({
+            'service.name': this.config.serviceName,
+            'service.version': this.sdkVersion,
+            ...this.config.resourceAttributes,
+        });
+    }
+    pipelineExporter() {
+        const isExternal = this.config.exporter === 'external';
+        if (this.spanSink && !isExternal) {
+            const sink = new otel_span_spool_1.SpanSinkExporter(this.spanSink, this.spoolKey);
+            this.transport = sink;
+            return sink;
+        }
+        const url = isExternal ? this.config.endpoint : this.firstPartyTracesUrl();
+        if (!url)
+            return null;
+        const headers = isExternal ? this.config.headers : { 'x-api-key': this.apiKey };
+        const transport = this.ownedTransport(url, headers);
+        this.transport = transport;
+        return this.createExporter(url, transport, this.config.timeoutMillis);
+    }
+    firstPartyTracesUrl() {
+        return `${this.backendEndpoint}/v1/traces`;
+    }
+    ownedTransport(url, headers) {
+        // The wire serializer is protobuf. Content type is SDK-owned and must
+        // be set after arbitrary caller headers.
+        return new otlp_http_transport_1.OwnedOtlpHttpTransport(new URL(url), {
+            ...headers,
+            'content-type': 'application/x-protobuf',
+        });
+    }
     /**
      * Construct the OTLP delegate from explicit values. The convenience
      * exporter reads process.env while merging defaults, which could leak a
      * caller's external headers into an ArmorIQ-only exporter.
      */
-    createExporter(url, headers) {
-        const agentFactory = async (protocol) => {
-            const { Agent } = protocol === 'http:' ? await import('node:http') : await import('node:https');
-            const agent = new Agent({ keepAlive: false });
-            this.ownedAgents.add(agent);
-            return agent;
-        };
-        return new otlp_exporter_base_1.OTLPExporterBase((0, node_http_1.createOtlpHttpExportDelegate)({
-            url,
-            // The wire serializer is protobuf. Content type is SDK-owned and must
-            // be set after arbitrary caller headers.
-            headers: () => ({ ...headers, 'content-type': 'application/x-protobuf' }),
-            timeoutMillis: Math.min(this.config.timeoutMillis, CLOSE_DEADLINE_MS),
-            concurrencyLimit: 1,
+    createExporter(url, transport, timeoutMillis) {
+        return new otlp_exporter_base_1.OTLPExporterBase((0, otlp_exporter_base_1.createOtlpNetworkExportDelegate)({
+            timeoutMillis,
+            concurrencyLimit: EXPORT_CONCURRENCY_LIMIT,
             compression: 'none',
-            agentFactory,
-        }, otlp_transformer_1.ProtobufTraceSerializer));
+        }, otlp_transformer_1.ProtobufTraceSerializer, (0, node_http_1.createOtlpHttpExporterMetrics)('otlp_http_span_exporter', otlp_transformer_1.TraceExporterMetricsHelper, url, undefined), transport));
     }
     safeAttributes(snapshot, attributes, context) {
         return this.safeAttributesWithAuthority(snapshot, attributes, context, false);
@@ -566,14 +693,7 @@ class ArmorIQTelemetryRuntime {
         }
         result['armoriq.observability.capture.mode'] = snapshot.captureMode;
         result['armoriq.observability.policy.revision'] = snapshot.revision;
-        if (external) {
-            const sessionId = (0, otel_config_1.sanitizeExternalTelemetryValue)(context.sessionId, 128);
-            if (sessionId)
-                result['session.id'] = sessionId;
-            if (context.userId && validExternalId(context.userId))
-                result['user.id'] = context.userId;
-        }
-        return result;
+        return Object.assign(result, sessionIdentity(context, external));
     }
     externalAttributeAllowed(key, mode) {
         if (EXTERNAL_METADATA_ATTRIBUTES.has(key) || EXTERNAL_POLICY_METADATA_ATTRIBUTES.has(key))
@@ -640,39 +760,111 @@ class ArmorIQTelemetryRuntime {
         if (this.config.exporter === 'provider')
             return;
         try {
-            await bounded(this.provider?.forceFlush() ?? Promise.resolve());
+            await bounded(this.drainExports(this.provider?.forceFlush(), this.exporter));
         }
         catch {
             // Export failure is intentionally fail-open.
         }
     }
-    async close() {
+    /** Process-exit drain: a bounded flush that then fails what is still in flight; the runtime stays open. */
+    async drainForExit() {
+        await this.forceFlush();
+        this.transport?.abandon(false);
+    }
+    async drainExports(batches, exporter) {
+        await batches?.catch(() => undefined);
+        await exporter?.forceFlush?.();
+    }
+    /** The `binding` of every batch this runtime's `spanSink` receives. */
+    get spoolBinding() {
+        return this.leaseBinding;
+    }
+    /**
+     * Ships batches this runtime's `spanSink` wrote, one OTLP request each,
+     * under its current authoritative lease. Resolves to one result per entry of
+     * `batches`, in order.
+     */
+    async exportSpooled(batches) {
+        const parsed = await (0, otel_spool_export_1.parseSpooledSpanBatches)(batches, {
+            key: this.spoolKey,
+            resource: this.resource(),
+            scope: { name: TRACER_NAME, version: this.sdkVersion },
+        });
+        const available = this.config.enabled && !this.closed && this.config.exporter === 'armoriq';
+        const shippable = available && parsed.some((entry) => 'spans' in entry);
+        const call = shippable && this.openSpoolCall();
+        if (!call)
+            return (0, otel_spool_export_1.settleShippable)(parsed, otel_spool_export_1.SPOOL_UNAVAILABLE);
+        try {
+            await (0, otel_spool_export_1.untilAborted)(this.refreshPolicy(), call.signal);
+            const ship = (spans) => this.shipSpooled(spans, call);
+            return await (0, otel_spool_export_1.exportSpooledBatches)(parsed, ship, this.spoolSlots, call.signal);
+        }
+        finally {
+            call.end();
+            this.spoolCalls.delete(call);
+        }
+    }
+    openSpoolCall() {
+        const url = this.firstPartyTracesUrl();
+        let transport;
+        try {
+            transport = this.ownedTransport(url, { 'x-api-key': this.apiKey });
+        }
+        catch {
+            return null;
+        }
+        const exporter = this.createExporter(url, transport, this.config.timeoutMillis);
+        const call = new otel_spool_export_1.SpoolExportCall(transport, exporter);
+        this.spoolCalls.add(call);
+        return call;
+    }
+    shipSpooled(spans, call) {
+        if (!holdsCurrentAuthority(this.lease))
+            return Promise.resolve(otel_spool_export_1.SPOOL_POLICY_UNAVAILABLE);
+        const snapshot = this.applyCeiling(this.lease);
+        if (snapshot.captureMode === 'off')
+            return Promise.resolve(otel_spool_export_1.SPOOL_DISCARDED);
+        const project = (span) => ({
+            ...span,
+            attributes: this.shippedAttributes(snapshot, span.attributes),
+        });
+        return call.send(spans.map(project));
+    }
+    shippedAttributes(snapshot, attributes) {
+        const governed = this.reapplyContentCeiling(snapshot, attributes);
+        Object.assign(governed, (0, content_capture_1.trustedContentDiagnostics)(attributes, governed));
+        const shipped = {};
+        for (const key of Object.keys(attributes))
+            if (hasOwn(governed, key))
+                shipped[key] = governed[key];
+        return Object.assign(shipped, governed);
+    }
+    async close(deadlineMs = CLOSE_DEADLINE_MS) {
         if (this.closed)
             return;
         this.closed = true;
         (0, otel_shutdown_1.unregisterOwnedTelemetryRuntime)(this);
+        this.storeAbort.abort();
         this.policyLeaseAbort?.abort();
         this.policyLeaseAbort = null;
+        this.spoolCalls.forEach((call) => call.abort(otel_spool_export_1.SPOOL_UNAVAILABLE));
         if (this.config.exporter === 'provider')
             return;
         const provider = this.provider;
+        const exporter = this.exporter;
+        const transport = this.transport;
         this.provider = null;
+        this.exporter = null;
+        this.transport = null;
         try {
-            await bounded(provider?.shutdown() ?? Promise.resolve());
+            await bounded(this.drainExports(provider?.shutdown(), exporter), validDeadline(deadlineMs));
         }
         catch {
             // Export failure is intentionally fail-open.
         }
         finally {
-            for (const agent of this.ownedAgents) {
-                try {
-                    agent.destroy();
-                }
-                catch {
-                    // Agents are SDK-owned and are best-effort only.
-                }
-            }
-            this.ownedAgents.clear();
+            transport?.abandon(true);
         }
     }
 }