/**
 * Structured logging contract.
 * Type-only — runtime lives in @skaile/workspaces/core/logging.
 */
/**
 * Top-level emitter family for a {@link LogSource}.
 *
 * `capability` was added in protocol v2.0.0 as part of the unified capability
 * registry. See `_devlog/specs/2026-04-30-protocol-v2-capability-protocol.md`
 * for the full taxonomy and `_devlog/specs/2026-05-01-debug-logging-design.md`
 * for the source-taxonomy table.
 *
 * @since 1.0.0 (`capability` since 2.0.0)
 * @docLink packages/types/logging#log-kind
 */
export type LogKind = "mount" | "connector" | "mcp" | "runner" | "bridge" | "agent" | "gateway" | "capability" | "flow-connector";
/**
 * Severity level for a log entry.
 *
 * @docLink packages/types/logging#log-entry
 */
export type LogLevel = "debug" | "info" | "warn" | "error";
/**
 * Source taxonomy for a log entry. The triple
 * (`kind`, `subkind`, `instance`) lets the debug panel and the
 * `skaile session logs` CLI filter by emitter family, driver, and
 * concrete instance.
 *
 * @see {@link LogKind} for the allowed top-level kinds
 *
 * For the `capability` kind (added in protocol v2.0.0):
 * - `subkind` is the origin kind: one of
 *   `framework | client | agent | flow | skill | mcp | connector | mount | app`
 *   (matches `CapabilityOrigin.kind` in `capabilities.ts`). For `app`-origin
 *   capabilities the `appId` is encoded into `instance` as `<appId>.<name>`.
 * - `instance` is the capability name (e.g. `platform.react`, `ui.gif`).
 *
 * Capability handlers receive a per-handler {@link Logger} via
 * `HandlerContext.log` (wired by the runner's capability registry); using
 * that logger ensures invocations land under the
 * `capability:<origin>:<name>` slice and stay queryable from the debug panel
 * and the CLI.
 *
 * @since 1.0.0
 * @docLink packages/types/logging#log-source
 */
export interface LogSource {
    kind: LogKind;
    subkind: string;
    instance?: string;
}
/**
 * Serializable representation of a thrown error, stored in `LogEntry.error`.
 *
 * @docLink packages/types/logging#log-entry
 */
export interface NormalizedError {
    name: string;
    message: string;
    stack?: string;
}
/**
 * A single structured log record written to the `LogStore`.
 *
 * Assigned a monotonic ULID id. The `source` triple identifies the emitter;
 * `data` and `error` carry structured context.
 *
 * @docLink packages/types/logging#log-entry
 */
export interface LogEntry {
    id: string;
    timestamp: string;
    sessionId: string;
    source: LogSource;
    level: LogLevel;
    message: string;
    data?: Record<string, unknown>;
    error?: NormalizedError;
}
/**
 * Per-source logging interface. Obtain an instance from `core`'s `createLogger()`.
 *
 * Call `child()` to create a derived logger with merged source fields for sub-components.
 *
 * @docLink packages/types/logging#logger
 */
export interface Logger {
    debug(msg: string, data?: object): void;
    info(msg: string, data?: object): void;
    warn(msg: string, data?: object): void;
    error(msg: string, err?: unknown, data?: object): void;
    /** Returns a new Logger with merged source. */
    child(partial: Partial<LogSource>): Logger;
}
/**
 * Storage mode for the `LogStore`. `persistent` writes to SQLite; `ephemeral` holds
 * entries in memory only; `off` disables logging entirely.
 *
 * @docLink packages/types/logging#log-store-config
 */
export type LogStoreMode = "persistent" | "ephemeral" | "off";
/**
 * Retention policy for the `LogStore`. When both fields are set, both limits apply.
 *
 * @docLink packages/types/logging#log-store-config
 */
export interface LogStoreRetention {
    maxEntries?: number;
    maxAgeDays?: number;
}
/**
 * Configuration for initializing a `LogStore` instance.
 *
 * @docLink packages/types/logging#log-store-config
 */
export interface LogStoreConfig {
    mode: LogStoreMode;
    level: LogLevel;
    sessionId: string;
    /** Workspace root; required when mode === 'persistent'. */
    workspacePath?: string;
    retention?: LogStoreRetention;
}
/**
 * Filter input for querying the `LogStore`. All fields except `sessionId` are optional.
 *
 * @docLink packages/types/logging#log-query
 */
export interface LogQuery {
    sessionId: string;
    source?: Partial<LogSource>;
    levels?: LogLevel[];
    since?: string;
    until?: string;
    search?: string;
    limit?: number;
    cursor?: string;
}
/**
 * Result of a `LogStore.query()` call. Carries a page of entries and an optional cursor
 * for pagination.
 *
 * @docLink packages/types/logging#log-query
 */
export interface LogQueryResult {
    entries: LogEntry[];
    nextCursor?: string;
}
/**
 * Sink contract for writing log entries. Runtime implementations live in
 * `@skaile/workspaces/core/logging`. Defined here so consumers can type-check sink
 * instances without depending on `core`.
 *
 * @docLink packages/types/logging#log-sink
 */
export interface LogSink {
    write(entry: LogEntry): void;
    writeBatch(entries: LogEntry[]): void;
    query?(q: LogQuery): LogQueryResult;
    close(): void;
}
//# sourceMappingURL=logging.d.ts.map