/**
 * Slice topology observability — schema + emit (Slice A of v2.11.1).
 *
 * Public surface:
 *   - `emitObservabilityEvent(event, options)` — fire-and-forget write
 *     to `.peaks/_runtime/<event.sessionId>/metrics/slices.jsonl`.
 *   - `readObservabilityEvents(projectRoot, sessionId)` — schema-aware
 *     reader that skips malformed lines and unknown schema versions
 *     (per PRD Q3 forward-compat).
 *
 * Schema-versioned (schemaVersion: 1). The zod schema is the source of
 * truth for the wire format. `ts` and `sessionId` are required; the
 * caller is responsible for passing them (so each hook site has a
 * canonical session binding even when run in a sub-agent).
 *
 * Per PRD Q4, `emit` MUST NEVER throw or fail-loud. All error paths
 * collapse to `written: false` with a `reason` string so the caller can
 * log if it wants — but the calling hook site itself swallows the
 * result (fire-and-forget by convention).
 */
import { type EmitOptions, type EmitResult, type ObservabilityEvent, type ObservabilitySubagentRole } from './observability-schema.js';
export { OBSERVABILITY_CATEGORIES, OBSERVABILITY_CONSTANTS, OBSERVABILITY_SCHEMA_VERSION, OBSERVABILITY_SUBAGENT_ROLES, ObservabilityEventSchema } from './observability-schema.js';
export type { EmitFailureReason, EmitOptions, EmitResult, ObservabilityCategory, ObservabilityEvent, ObservabilitySubagentRole } from './observability-schema.js';
/**
 * Append a single observability event to the session's JSONL metrics
 * file. Synchronous (small append, sub-ms in practice) and
 * fire-and-forget by construction — the caller never awaits, and the
 * function never throws.
 *
 * On success, also triggers the cross-session prune
 * (`pruneMetricsFiles`). The prune is best-effort and cheap when the
 * session count is below `MAX_METRICS_FILES`.
 */
export declare function emitObservabilityEvent(event: ObservabilityEvent, options: EmitOptions): EmitResult;
/**
 * Read all events from a session's metrics file, skipping malformed
 * lines and any record whose `schemaVersion` does not match the
 * current `OBSERVABILITY_SCHEMA_VERSION` (forward-compat per Q3).
 *
 * Returns [] when the session has no metrics file yet, and [] when the
 * session id names no session directory — both are "no events are
 * readable here", and this reader does not throw (repair R6: it used to,
 * via `readMetricLines` → `metricsFilePath`).
 */
export declare function readObservabilityEvents(projectRoot: string, sessionId: string): ObservabilityEvent[];
/**
 * True when the candidate record validates against the current
 * schema (re-exported as a convenience for callers that already have
 * parsed JSON and want to skip forward-compat records).
 */
export declare function isCurrentSchemaVersion(record: unknown): record is ObservabilityEvent;
/**
 * observability. Each `peaks worktree spawn / renew / release /
 * gc` CLI emits a `lease` event; the auto-release hook in
 * dispatch finalization emits `autoRelease` (success) or
 * `autoRelease-failed` (detached spawn failed). The
 * `peaks lease metrics --json` reader aggregates these for the
 * dashboard.
 *
 * Fire-and-forget by contract (mirrors emitCycleEvent /
 * emitTokenUsageEvent): never throws, written=false on schema
 * mismatch or IO failure. Callers do not inspect the result.
 */
export type LeaseEventKind = 'spawn' | 'renew' | 'release' | 'gc' | 'autoRelease' | 'autoRelease-failed' | 'autoRelease-skipped';
export declare function emitLeaseEvent(opts: {
    sessionId: string;
    projectRoot: string;
    kind: LeaseEventKind;
    leaseId: string;
    rid?: string;
    role?: string;
    /** Reason the autoRelease was skipped (e.g. "no-lease", "non-terminal-status"). */
    reason?: string;
}): EmitResult;
/**
 * Fire-and-forget; never throws. Tagging `kind` for downstream dashboards.
 */
export declare function emitCycleEvent(opts: {
    sessionId: string;
    projectRoot: string;
    cycle: number;
    status: 'started' | 'completed' | 'failed';
}): EmitResult;
/**
 * sum the dashboard cares about; `inputTokens`/`outputTokens` are kept
 * for downstream drill-down.
 */
export declare function emitTokenUsageEvent(opts: {
    sessionId: string;
    projectRoot: string;
    inputTokens: number;
    outputTokens: number;
    /**
     * Where the two counts came from. Required, not defaulted: a `0` the provider
     * reported and a `0` nobody measured are the same number, and the whole point
     * of the tag is to stop them being read as one — a caller that cannot say
     * which it holds has not measured.
     */
    source: 'provider' | 'estimated';
}): EmitResult;
/**
 */
export declare function emitMonotonicTriggerEvent(opts: {
    sessionId: string;
    projectRoot: string;
    report: 'pass' | 'warn' | 'block';
    action: string;
}): EmitResult;
/**
 * existing `dispatch` category (rd/qa/reviewer/audit). Provides a
 * canonical emit helper so dashboards don't have to hand-author the
 * `ObservabilityEvent` envelope.
 */
export declare function emitDispatchEvent(opts: {
    sessionId: string;
    projectRoot: string;
    role: ObservabilitySubagentRole;
    status?: 'queued' | 'running' | 'done' | 'failed';
}): EmitResult;