/**
 * OpenTelemetry SDK init — the application half of the OTel library/application
 * split, wired ONLY at the CLI composition root.
 *
 * ## Opt-in gate (the load-bearing contract)
 *
 * The OTel SDK (traces + metrics) is gated on `OTEL_EXPORTER_OTLP_ENDPOINT`.
 * Local CPU profiling is a separate, explicit artifact path.
 *
 *   - **Set** ⇒ register NodeTracerProvider + (Phase 2) MeterProvider.
 *     `core`'s `getTracer`/`withSpan`/`getMeter` resolve to real implementations.
 *   - `OPENSIP_PROFILING=1` independently enables local CPU artifacts without a
 *     collector; an OTLP endpoint alone does not enable profiling.
 *   - **Unset** ⇒ traces and metrics are hard no-ops. Standalone CLI pays nothing.
 *
 * ## Layering
 *
 * The heavy SDK packages (`@opentelemetry/sdk-trace-node`, the OTLP exporter,
 * `context-async-hooks`, `core`'s propagator, `resources`) are imported HERE
 * and nowhere else. `core` and the tool packages depend on `@opentelemetry/api`
 * only — dependency-cruiser enforces that an `@opentelemetry/sdk-*` import never
 * leaks into the kernel or a tool.
 *
 * ## Parent-trace nesting
 *
 * An embedding consumer spawns the binary with a `TRACEPARENT` env var. We
 * extract it via the W3C propagator and expose it as a parent context
 * ({@link parentTelemetryContext} / {@link runWithTelemetryContext}) so the
 * command dispatch — and therefore graph's stage spans — nests under the
 * consumer's trace. When `TRACEPARENT` is unset the spans form their own trace,
 * which is still valid.
 *
 * ## Fail-safe shutdown
 *
 * Telemetry must never crash OR hang the primary CLI run: a dead/slow collector
 * has to degrade to "spans dropped," not a multi-second stall on exit (amplified
 * on the sharded path, where every shard-worker subprocess also flushes). Two
 * bounds enforce this: each export attempt is capped at {@link SHUTDOWN_TIMEOUT_MS}
 * (`OTLPTraceExporter({ timeoutMillis })`), and {@link shutdownTelemetry} races the
 * final flush against the same deadline and swallows any failure.
 */
import { type Context } from '@opentelemetry/api';
/**
 * Warn when the OTLP endpoint targets a non-loopback host over plaintext http.
 * Traces can carry identity (`tenant_id`/`run_id` via OTEL_RESOURCE_ATTRIBUTES),
 * so a remote plaintext collector leaks it on the wire — the same risk the cloud
 * signal/report egress refuses outright. Loopback dev collectors
 * (localhost/127.0.0.1/::1) are exempt; https is the fix for remote ones. We warn
 * rather than refuse — telemetry is strictly opt-in. Exported for tests.
 */
export declare function warnIfInsecureOtlpEndpoint(endpoint: string): void;
/**
 * Initialize OpenTelemetry tracing, gated on `OTEL_EXPORTER_OTLP_ENDPOINT`.
 *
 * No-op when the endpoint env var is falsy, or when already started (idempotent
 * and safe to call from multiple entry points). Sets the GLOBAL tracer provider
 * so `core`'s `getTracer` resolves to real tracers process-wide.
 *
 * @param cliEntryUrl `import.meta.url` of the CLI entry, used to read the CLI
 *   package version for the `service.version` resource attribute.
 */
export declare function initTelemetry(cliEntryUrl: string): void;
/**
 * The parent context extracted from `TRACEPARENT`, or undefined. Exposed for
 * tests; production code should prefer {@link runWithTelemetryContext}.
 */
export declare function parentTelemetryContext(): Context | undefined;
/**
 * Run `fn` with the extracted parent context active (when present), so spans
 * created inside nest under the consumer's trace. A plain pass-through when no
 * parent context was extracted (or telemetry is disabled), so standalone runs
 * pay nothing.
 */
export declare function runWithTelemetryContext<T>(fn: () => T): T;
/**
 * Flush and shut down the tracer + meter providers (and stop profiling if active)
 * so batched data export before the short-lived process exits.
 * OTel-provider shutdown is a no-op when telemetry was never started; local
 * profiling is still flushed independently. Swallows shutdown errors — a dead
 * collector or profiler must not crash the CLI on the way out.
 */
export declare function shutdownTelemetry(): Promise<void>;
/**
 * Resolve when `work` settles, or reject with {@link TimeoutError} after `ms` —
 * whichever comes first. The deadline timer is `unref`'d so it never keeps the
 * (short-lived CLI) event loop alive when the work wins, and cleared on the
 * happy path. Exported for tests.
 */
export declare function raceWithTimeout(work: Promise<void>, ms: number): Promise<void>;
/**
 * Test-only reset of module state. Production never calls this — the CLI is a
 * one-shot process. Tests use it to exercise the gate across env permutations
 * without a fresh module each time.
 */
export declare function resetTelemetryForTests(): void;
//# sourceMappingURL=sdk-init.d.ts.map