/**
 * Observability event pipeline — event schema, bus, and correlation IDs.
 *
 * Defines a unified event model for run/host/resource lifecycle telemetry.
 * All reporters and formatters consume the same event stream, ensuring
 * consistent output regardless of sink.
 */
import type { ErrorMode, HostContext, ResourceResult, ResourceStatus, RunMode } from "../core/types.ts";
import type { RedactionPolicy } from "../core/serialize.ts";
/** Unique identifier for a run, host, or resource execution. */
export type CorrelationId = string;
/** Correlation context threaded through all events in a run. */
export type CorrelationContext = {
    /** Unique ID for the entire run. */
    runId: CorrelationId;
    /** Unique ID for the current host (absent for run-level events). */
    hostId?: CorrelationId | undefined;
    /** Unique ID for the current resource execution (absent for run/host-level events). */
    resourceId?: CorrelationId | undefined;
    /** 1-based attempt number (present only for retry-related events). */
    attempt?: number | undefined;
};
/** Discriminant for all lifecycle event types. */
export type EventType = "run_started" | "run_finished" | "host_started" | "host_finished" | "resource_started" | "resource_finished" | "resource_retry" | "resource_output";
/** Base shape shared by all events. */
export type BaseEvent = {
    /** Event type discriminant. */
    type: EventType;
    /** ISO-8601 timestamp of event emission. */
    timestamp: string;
    /** Correlation IDs for tracing. */
    correlation: CorrelationContext;
};
/** Emitted when a run begins. */
export type RunStartedEvent = BaseEvent & {
    type: "run_started";
    mode: RunMode;
    errorMode: ErrorMode;
    hostCount: number;
};
/** Emitted when a run completes. */
export type RunFinishedEvent = BaseEvent & {
    type: "run_finished";
    durationMs: number;
    hasFailures: boolean;
    hostCount: number;
};
/** Emitted when a host begins execution. */
export type HostStartedEvent = BaseEvent & {
    type: "host_started";
    host: HostContext;
};
/** Emitted when a host completes execution. */
export type HostFinishedEvent = BaseEvent & {
    type: "host_finished";
    host: HostContext;
    ok: number;
    changed: number;
    failed: number;
    durationMs: number;
    cancelled?: boolean | undefined;
};
/** Emitted when a resource begins execution. */
export type ResourceStartedEvent = BaseEvent & {
    type: "resource_started";
    resourceType: string;
    resourceName: string;
};
/** Emitted when a resource completes execution. */
export type ResourceFinishedEvent = BaseEvent & {
    type: "resource_finished";
    resourceType: string;
    resourceName: string;
    status: ResourceStatus;
    durationMs: number;
    error?: {
        message: string;
        name: string;
    } | undefined;
    cacheHit?: boolean | undefined;
};
/** Emitted when a resource phase is retried. */
export type ResourceRetryEvent = BaseEvent & {
    type: "resource_retry";
    resourceType: string;
    resourceName: string;
    phase: "check" | "apply" | "post-check";
    error: {
        message: string;
        name: string;
    };
    durationMs: number;
};
/** Emitted when a resource produces stdout/stderr output during execution. */
export type ResourceOutputEvent = BaseEvent & {
    type: "resource_output";
    resourceType: string;
    resourceName: string;
    stream: "stdout" | "stderr";
    chunk: string;
};
/** Discriminated union of all lifecycle events. */
export type LifecycleEvent = RunStartedEvent | RunFinishedEvent | HostStartedEvent | HostFinishedEvent | ResourceStartedEvent | ResourceFinishedEvent | ResourceRetryEvent | ResourceOutputEvent;
/** Callback for receiving lifecycle events. */
export type EventListener = (event: LifecycleEvent) => void;
/**
 * Central event bus for run lifecycle telemetry.
 *
 * Generates correlation IDs and dispatches events to registered listeners.
 * Thread-safe for concurrent host execution — each emit is synchronous.
 */
export declare class EventBus {
    #private;
    constructor(runId?: CorrelationId);
    /** The run-level correlation ID. */
    get runId(): CorrelationId;
    /** Register a listener. Returns an unsubscribe function. */
    on(listener: EventListener): () => void;
    /** Generate a unique correlation ID for a host or resource. */
    nextId(): CorrelationId;
    /** Emit an event to all listeners. */
    emit(event: LifecycleEvent): void;
    /** Build and emit a run_started event. */
    runStarted(mode: RunMode, errorMode: ErrorMode, hostCount: number): void;
    /** Build and emit a run_finished event. */
    runFinished(durationMs: number, hasFailures: boolean, hostCount: number): void;
    /** Build and emit a host_started event. */
    hostStarted(hostId: CorrelationId, host: HostContext): void;
    /** Build and emit a host_finished event. */
    hostFinished(hostId: CorrelationId, host: HostContext, counts: {
        ok: number;
        changed: number;
        failed: number;
        durationMs: number;
        cancelled?: boolean;
    }): void;
    /** Build and emit a resource_started event. */
    resourceStarted(hostId: CorrelationId, resourceId: CorrelationId, resourceType: string, resourceName: string): void;
    /** Build and emit a resource_finished event. */
    resourceFinished(hostId: CorrelationId, resourceId: CorrelationId, result: ResourceResult): void;
    /** Build and emit a resource_retry event. */
    resourceRetry(hostId: CorrelationId, resourceId: CorrelationId, attempt: number, resourceType: string, resourceName: string, phase: "check" | "apply" | "post-check", error: Error, durationMs: number): void;
    /** Build and emit a resource_output event. */
    resourceOutput(hostId: CorrelationId, resourceId: CorrelationId, resourceType: string, resourceName: string, stream: "stdout" | "stderr", chunk: string): void;
}
/**
 * A Reporter that emits resource lifecycle events to an EventBus.
 *
 * Wraps an optional delegate Reporter so existing pretty/quiet output
 * continues to work alongside the event pipeline. Requires hostId and
 * a reference to the event bus for correlation.
 */
export declare class EventReporter {
    #private;
    constructor(bus: EventBus, hostId: CorrelationId, delegate?: {
        resourceStart(type: string, name: string): void;
        resourceEnd(result: ResourceResult): void;
        resourceOutput?(type: string, name: string, stream: "stdout" | "stderr", chunk: string): void;
    });
    /** The event bus backing this reporter. */
    get bus(): EventBus;
    /** The host correlation ID for this reporter. */
    get hostId(): CorrelationId;
    resourceStart(type: string, name: string): void;
    resourceEnd(result: ResourceResult): void;
    /** Emit a retry event for the currently active resource. */
    resourceRetry(attempt: number, resourceType: string, resourceName: string, phase: "check" | "apply" | "post-check", error: Error, durationMs: number): void;
    /** Emit a resource_output event for the currently active resource. */
    resourceOutput(resourceType: string, resourceName: string, stream: "stdout" | "stderr", chunk: string): void;
}
/**
 * Streams lifecycle events as newline-delimited JSON (NDJSON).
 *
 * Each event is serialized as a single JSON line followed by `\n`.
 * Suitable for piping to log aggregators, monitoring tools, or `jq`.
 * When a redaction policy is provided, sensitive fields are replaced
 * before serialization.
 */
export declare class NdjsonStream {
    #private;
    constructor(writer: {
        writeSync(p: Uint8Array): number;
    }, redactionPolicy?: RedactionPolicy);
    /** EventListener-compatible handler. */
    listener: EventListener;
}
/** Generate a short unique ID (12 hex chars). */
export declare function generateId(): string;
//# sourceMappingURL=events.d.ts.map