/**
 * Phase2 Telemetry — Structured span emission
 *
 * Every major step emits a span with start/end, inputs, outputs, and file paths.
 * Spans are collected on Phase2Context and written to telemetry.jsonl at the end.
 */
import type { TelemetrySpan } from './types.js';
export type { TelemetrySpan } from './types.js';
/**
 * Create a new telemetry span. The span starts immediately with status 'ok'.
 * Call {@link endSpan} when the operation completes to record duration and
 * final status.
 *
 * @param stage     - Pipeline stage name (e.g. 'scaffold', 'codegen')
 * @param operation - Specific operation within the stage
 * @param attributes - Optional key-value metadata to attach
 * @param parentSpanId - Optional parent span for nested tracing
 * @returns A new TelemetrySpan with startTime set to now
 */
export declare function createSpan(stage: string, operation: string, attributes?: Record<string, string | number | boolean>, parentSpanId?: string): TelemetrySpan;
/**
 * Finalize a span by recording its end time, duration, and final status.
 * Returns a new span object (does not mutate the original).
 *
 * @param span            - The span to finalize
 * @param status          - Final status: 'ok' or 'error'
 * @param extraAttributes - Optional additional attributes to merge
 * @returns A new span with end-time data
 */
export declare function endSpan(span: TelemetrySpan, status: 'ok' | 'error', extraAttributes?: Record<string, string | number | boolean>): TelemetrySpan;
/**
 * Emit a single span to stderr for real-time observability.
 * Format: `  [SPAN] stage/operation Xms STATUS`
 *
 * @param span - The span to emit
 */
export declare function emitSpan(span: TelemetrySpan): void;
/**
 * Write an array of spans to a NDJSON file (one JSON object per line).
 * The file is written to `<outputDir>/telemetry.jsonl` with 0o600 permissions.
 *
 * @param spans     - Completed spans to persist
 * @param outputDir - Directory to write the telemetry file into
 */
export declare function writeSpans(spans: readonly TelemetrySpan[], outputDir: string): void;
//# sourceMappingURL=telemetry.d.ts.map