/**
 * Ranking-input audit trail (T12693, owner decision D11161).
 *
 * Agents may write a task's ranking inputs — priority, severity, kind and
 * depends — directly, but every such change records WHO (actor), in WHICH
 * session, WHY (optional reason) and the values before and after, as one
 * `ranking_changed` row in the task audit log, written in the same
 * transaction as the change. `cleo history ranking <id>` lists them and
 * `cleo history revert <entryId>` undoes one.
 *
 * @task T12693
 */
import type { Task } from '@cleocode/contracts';
/** The audit action a ranking change is recorded under. */
export declare const RANKING_CHANGED_ACTION = "ranking_changed";
/** Fields the ranking sort reads (D11161). */
export declare const RANKING_FIELDS: readonly ["priority", "severity", "kind", "depends"];
/** One ranking input. */
export type RankingField = (typeof RANKING_FIELDS)[number];
/** A task's ranking inputs at one moment. */
export interface RankingSnapshot {
    priority: Task['priority'] | null;
    severity: NonNullable<Task['severity']> | null;
    kind: NonNullable<Task['kind']> | null;
    depends: string[];
}
/** Who made a change: agent (or `human`) and session. */
export interface RankingActor {
    actor: string;
    sessionId: string | null;
}
/** One recorded ranking change, as `cleo history ranking` shows it. */
export interface RankingChange {
    /** Audit row id — what `cleo history revert` takes. */
    id: string;
    taskId: string;
    timestamp: string;
    actor: string;
    sessionId: string | null;
    reason: string | null;
    /** What made the change (`update`, `delete-cascade`, `revert`). */
    source: string | null;
    fields: RankingField[];
    before: Partial<RankingSnapshot>;
    after: Partial<RankingSnapshot>;
}
/**
 * A task's ranking inputs.
 *
 * @param task - The task.
 * @returns The snapshot (depends sorted, so order changes are not changes).
 * @task T12693
 */
export declare function rankingSnapshot(task: Pick<Task, 'priority' | 'severity' | 'kind' | 'depends'>): RankingSnapshot;
/**
 * The ranking fields that differ between two snapshots.
 *
 * @param before - Snapshot before the change.
 * @param after - Snapshot after it.
 * @returns Changed fields, in {@link RANKING_FIELDS} order.
 * @task T12693
 */
export declare function rankingDiff(before: RankingSnapshot, after: RankingSnapshot): RankingField[];
/**
 * The actor and session a change is attributed to: the agent id
 * (`CLEO_AGENT_ID`, else `human`) and the caller's session (env first, then
 * the bound session).
 *
 * @param cwd - Project root.
 * @returns The actor and session.
 * @task T12693
 */
export declare function resolveRankingActor(cwd?: string): Promise<RankingActor>;
/**
 * The audit-log entry for one ranking change, or null when nothing ranking
 * related changed. Only the changed fields are stored before and after.
 *
 * @param input - Task, snapshots, attribution and why.
 * @returns The `appendLog` entry, or null.
 * @task T12693
 */
export declare function rankingAuditEntry(input: {
    taskId: string;
    before: RankingSnapshot;
    after: RankingSnapshot;
    actor: RankingActor;
    reason?: string | undefined;
    source: string;
}): Record<string, unknown> | null;
/**
 * Who changed a task's ranking inputs, when, and why — newest first.
 *
 * @param taskId - Task.
 * @param cwd - Project root.
 * @param limit - Maximum rows (default 50).
 * @returns The recorded changes.
 * @task T12693
 */
export declare function listRankingHistory(taskId: string, cwd?: string, limit?: number): Promise<RankingChange[]>;
/**
 * Undo one recorded ranking change: set each field it changed back to its
 * value before, as a new audited change (source `revert`). Refused when a
 * field has changed again since, so a later decision is never silently lost —
 * unless `force`.
 *
 * @param entryId - The `ranking_changed` audit row id.
 * @param opts - Why (recorded), and `force` to revert over later changes.
 * @param cwd - Project root.
 * @returns The task id, the reverted fields and the new audit row id.
 * @throws {CleoError} When the entry is not a ranking change, or a field
 *   changed since and `force` is not set.
 * @task T12693
 */
export declare function revertRankingChange(entryId: string, opts?: {
    reason?: string;
    force?: boolean;
}, cwd?: string): Promise<{
    taskId: string;
    fields: RankingField[];
    revertedTo: Partial<RankingSnapshot>;
}>;
//# sourceMappingURL=ranking-audit.d.ts.map