/**
 * The unit of trace data: an immutable {@link Segment} value.
 *
 * A {@link Segment} is a plain, frozen value object — never a class instance and
 * never mutated in place. The lifecycle (open → note → close) is expressed by
 * *producing new* segment values rather than by toggling fields on a live
 * object, which keeps the data model trivially serializable and free of the
 * `BaseSpan`/`DefaultSpan`/`NoopSpan` inheritance shape. The behavioural side —
 * the open/note/close operations a caller actually invokes — lives entirely in
 * {@link SegmentHandle} (see `./handle`).
 *
 * The vocabulary here is deliberately distinct from the OpenTelemetry "span"
 * lineage: an entity kind is a {@link SegmentKind} (`run`/`inference`/`action`/
 * `recall`/`custom`), and the exported, closed form is a {@link TraceRecord}.
 */
/**
 * The kind of work a segment records.
 *
 * - `run`       — a whole agent run / top-level invocation.
 * - `inference` — a single model/LLM call.
 * - `action`    — a tool or side-effecting action execution.
 * - `recall`    — a memory / retrieval operation.
 * - `custom`    — anything a caller wants to time that does not fit above.
 */
export type SegmentKind = "run" | "inference" | "action" | "recall" | "custom";
/** The lifecycle status of a segment. `open` until closed; then `ok` or `error`. */
export type SegmentStatus = "open" | "ok" | "error";
/** A captured failure attached to a segment. Intentionally minimal and serializable. */
export interface SegmentError {
    readonly message: string;
}
/**
 * An immutable trace segment.
 *
 * Every field is `readonly`; the value is frozen at construction (see
 * {@link openSegment}). Transitions are modelled as *new* frozen values derived
 * from a prior one ({@link withAttributes}, {@link closeSegment}) — there is no
 * in-place mutation anywhere in this module.
 */
export interface Segment {
    /** Stable identifier for this segment, unique within its trace. Hex. */
    readonly id: string;
    /** Identifier of the trace this segment belongs to. Shared by all kin. Hex. */
    readonly traceId: string;
    /** The enclosing segment's `id`, or `null` for a trace root. */
    readonly parentId: string | null;
    /** What kind of work this segment records. */
    readonly kind: SegmentKind;
    /** Human-readable label for the segment. */
    readonly name: string;
    /** Wall-clock start, in epoch milliseconds. */
    readonly startedAt: number;
    /** Wall-clock end, in epoch milliseconds; `null` while still open. */
    readonly endedAt: number | null;
    /** Lifecycle status. */
    readonly status: SegmentStatus;
    /** Arbitrary structured annotations; a frozen, read-only bag. */
    readonly attributes: Readonly<Record<string, unknown>>;
    /** Present only once a segment has failed. */
    readonly error?: SegmentError;
}
/**
 * The exported, serializable form of a *closed* segment.
 *
 * Structurally a {@link Segment} that is guaranteed terminal: `endedAt` is a
 * number (not `null`) and `status` is no longer `open`. This is what a
 * `close` signal carries and what sinks persist; it never appears for a segment
 * still in flight.
 */
export interface TraceRecord extends Segment {
    readonly endedAt: number;
    readonly status: "ok" | "error";
}
/**
 * Generate a fresh hex identifier of `byteLength` random bytes.
 *
 * Trace ids default to 16 bytes (128-bit) and segment ids to 8 bytes (64-bit),
 * mirroring the W3C Trace Context sizing without depending on any OTel SDK.
 */
export declare function freshId(byteLength: number): string;
/** A new 128-bit hex trace id. */
export declare function freshTraceId(): string;
/** A new 64-bit hex segment id. */
export declare function freshSegmentId(): string;
/** Inputs for opening a fresh segment. Missing ids/clock are generated/sampled. */
export interface OpenSegmentInput {
    readonly kind: SegmentKind;
    readonly name: string;
    /** Trace to join. Omit on a root to mint a fresh trace id. */
    readonly traceId?: string;
    /** Enclosing segment id, or `null`/omitted for a root. */
    readonly parentId?: string | null;
    /** Pre-assigned segment id; one is minted when omitted. */
    readonly id?: string;
    /** Initial annotations. */
    readonly attributes?: Readonly<Record<string, unknown>>;
    /** Start clock override (epoch ms); `Date.now()` when omitted. */
    readonly startedAt?: number;
}
/**
 * Construct a fresh, frozen, `open` {@link Segment}.
 *
 * Pure aside from id/clock defaulting: with all fields supplied it is
 * deterministic. The returned value and its `attributes` bag are both frozen.
 */
export declare function openSegment(input: OpenSegmentInput): Segment;
/**
 * Derive a new frozen segment with `patch` merged over its attributes.
 *
 * Last-writer-wins on key collision. The original segment is untouched.
 */
export declare function withAttributes(segment: Segment, patch: Readonly<Record<string, unknown>>): Segment;
/**
 * Derive the terminal {@link TraceRecord} for an open segment.
 *
 * Stamps `endedAt` (defaulting to now), sets the final `status`, and — when the
 * status is `error` — attaches `error` (a passed-in error wins over any already
 * recorded one). Closing an already-closed segment is idempotent in spirit:
 * the new end clock and status simply replace the prior terminal fields.
 */
export declare function closeSegment(segment: Segment, status: "ok" | "error", options?: {
    readonly endedAt?: number;
    readonly error?: SegmentError;
}): TraceRecord;
