/**
 * The `tracing()` plugin - establishes a span per request, propagates W3C trace context, and exposes
 * `c.trace` for forwarding the trace to downstream services. OpenTelemetry-compatible by wire format
 * (traceparent) and attribute names (HTTP semantic conventions); the span itself is exported through
 * your {@link ObservationAdapter} (bridge to the OTel SDK, or log via `consoleSpanExporter`).
 */
import { type CausalityContext, type CausalityRecorder } from "@nifrajs/core/causality";
import { type ContextPlugin } from "@nifrajs/core/server";
import { type ActiveObservation, type ObservationContext } from "./lifecycle.js";
import { type ObservationAdapter } from "./span.js";
/** The trace context exposed on the handler `c.trace` (typed, threaded via `derive`). */
export type TraceContext = ObservationContext;
/** What `tracing()` adds to every handler context downstream of `.use(tracing())`. */
export interface TracingContext {
    readonly trace: TraceContext;
    readonly observation: ActiveObservation;
    readonly causality: CausalityContext;
}
export interface TracingOptions {
    /** Where spans are sent. Default: {@link consoleSpanExporter}. */
    readonly exporter?: ObservationAdapter;
    /** Additional observation adapters (DevTools, a private redacting backend, metrics, …). */
    readonly adapters?: readonly ObservationAdapter[];
    /** Sets the `service.name` attribute on every span. */
    readonly serviceName?: string;
    /**
     * Set the outbound `traceparent` on the RESPONSE too (handy for browser/client correlation).
     * Default false - most setups only propagate downstream, not back to the caller.
     */
    readonly responseHeader?: boolean;
    /**
     * Optional durable graph recorder. When configured, the request root is appended before the
     * handler runs and recorder failure fails closed. Without one, `c.causality` is still propagated.
     */
    readonly causality?: {
        readonly recorder?: CausalityRecorder;
        /** Injectable epoch clock for deterministic tests. */
        readonly now?: () => number;
        /**
         * Explicit trust gate for service-to-service causality headers. Internet clients are untrusted
         * by default; a false result or thrown/rejected check starts a fresh execution graph.
         */
        readonly acceptInbound?: (request: Request, context: CausalityContext) => boolean | Promise<boolean>;
    };
}
/** Spread into an outgoing `fetch`/`ctx.api` call's headers to continue the trace downstream:
 * `fetch(url, { headers: traceHeaders(c.trace) })`. */
export declare function traceHeaders(trace: TraceContext, causality?: CausalityContext): {
    readonly traceparent: string;
} & Readonly<Record<string, string>>;
/**
 * Distributed-tracing plugin. Each request continues the inbound trace (or starts one), opens a
 * server span, and ends it on response with the status + HTTP attributes. Idempotent.
 *
 * ```ts
 * app.use(tracing({ exporter: myOtelExporter, serviceName: "orders-api" }))
 * // in a handler: fetch(url, { headers: traceHeaders(c.trace) })  // continue the trace downstream
 * ```
 */
export declare function tracing(options?: TracingOptions): ContextPlugin<TracingContext>;
//# sourceMappingURL=tracing.d.ts.map