import { LEDGER_FILE } from "./local-files.js";
/** Bumped when the record shape changes in a non-additive way. */
export declare const OBSERVE_VERSION = 1;
/** The ledger filename under the `.vigiles/` directory — defined on the one local-files list. */
export { LEDGER_FILE };
/** Fields every record carries; `v`/`ts` are stamped by the writer, not the caller. */
export interface ObservationBase {
    /** schema version (`OBSERVE_VERSION`) */
    v: number;
    /** ISO-8601 timestamp */
    ts: string;
}
/** A gate/hook decision observed in a real session. */
export interface HookObservation extends ObservationBase {
    kind: "hook";
    event: string;
    decision: "allow" | "deny" | "ask";
    /** the compiled-hook rule/name, when known */
    rule?: string;
    /** enforce actually blocked; observe recorded a would-be block */
    mode?: "enforce" | "observe";
    /** the bash command inspected, when the gate keyed on one */
    cmd?: string;
    reason?: string;
}
/** A subagent tool-contract decision (the PreToolUse rail). */
export interface AgentObservation extends ObservationBase {
    kind: "agent";
    /** the dispatched subagent */
    name: string;
    tool: string;
    allowed: boolean;
    reason?: string;
}
/** Whether a skill fired for a turn (behavioral surface — best-effort per harness). */
export interface SkillObservation extends ObservationBase {
    kind: "skill";
    name: string;
    fired: boolean;
}
/** A measured eval outcome (recall, cost, a check rate, …). */
export interface EvalObservation extends ObservationBase {
    kind: "eval";
    name: string;
    metric: string;
    value: number;
}
/** A capability/blast-radius change observed at PR time. */
export interface CapabilityDiffObservation extends ObservationBase {
    kind: "capability-diff";
    pr?: number;
    added: string[];
    removed?: string[];
    /** true when the change loosened the agent's effect surface */
    widened: boolean;
}
/** The discriminated union every reader narrows on `kind`. */
export type ObservationRecord = HookObservation | AgentObservation | SkillObservation | EvalObservation | CapabilityDiffObservation;
/** What a caller supplies — the writer stamps `v` + `ts`. */
export type ObservationInput = Omit<HookObservation, "v" | "ts"> | Omit<AgentObservation, "v" | "ts"> | Omit<SkillObservation, "v" | "ts"> | Omit<EvalObservation, "v" | "ts"> | Omit<CapabilityDiffObservation, "v" | "ts">;
/** Serialize one record to a single JSONL line (trailing newline included). */
export declare function formatObservation(record: ObservationRecord): string;
/**
 * Append one observation to `<cwd>/.vigiles/runs.jsonl`. Best-effort: any failure is
 * swallowed so recording can never break a live session (the `ts`/`clock` here is a
 * runtime side effect, intentionally — this module records reality, it is not a spec).
 */
export declare function appendObservation(input: ObservationInput, cwd?: string): void;
/**
 * Read the ledger back. Tolerant by design: a malformed or partially-written line is
 * skipped rather than throwing, so a torn append never nukes the whole read.
 */
export declare function readObservations(cwd?: string): ObservationRecord[];
/** Filter the ledger to one record kind, narrowing the type for the caller. */
export declare function observationsOfKind<K extends ObservationRecord["kind"]>(records: readonly ObservationRecord[], kind: K): Extract<ObservationRecord, {
    kind: K;
}>[];
/** A denial rendered as a structured `{label, reason}` — the shared shape the
 *  terminal line and the JSON summary both derive from (one-detector-no-drift). */
export interface LedgerDenial {
    readonly label: string;
    readonly reason: string;
}
/** Per-kind record count. */
export interface LedgerCount {
    readonly kind: ObservationRecord["kind"];
    readonly count: number;
}
/** The structured ledger summary carried in the versioned AuditReport JSON. */
export interface LedgerSummary {
    readonly total: number;
    readonly counts: readonly LedgerCount[];
    readonly denials: number;
    /** The most recent denials (blocked gates / out-of-contract tool calls). */
    readonly recentDenials: readonly LedgerDenial[];
}
/**
 * The structured ledger summary for the AuditReport JSON — total, per-kind counts,
 * and the recent denials. `undefined` when nothing is recorded, so the report field
 * stays absent (additive/optional). Shares `isDenial`/`denialParts` with the
 * terminal `formatLedgerSummary` so the two can't drift.
 */
export declare function summarizeObservations(records: readonly ObservationRecord[]): LedgerSummary | undefined;
/**
 * A compact human summary of the ledger for `vigiles audit` — total, counts by kind,
 * and the recent high-signal denials. Empty string when there is nothing recorded, so
 * the caller can skip the section entirely.
 */
export declare function formatLedgerSummary(records: readonly ObservationRecord[], committedLocks?: number): string;
//# sourceMappingURL=observe.d.ts.map