import { DiffOptions, DiffResult, DiffNode } from '@ai-matrx/diff/structural';

/** Internal/runtime fields that should never appear in diffs */
declare const AGENT_EXCLUDE_PATHS: Set<string>;
/** Identity keys for array matching — prevents false diffs when items shift position */
declare const AGENT_IDENTITY_KEYS: Record<string, string>;
declare const AGENT_DIFF_OPTIONS: DiffOptions;

/**
 * Any agent record the diff can compare: the web's Redux `AgentDefinition`, a version snapshot
 * mapped by `snapshotToComparable`, or a fixture. Only top-level keys matter to the comparison.
 */
type ComparableAgent = object;
interface AgentDefinitionComparison {
    diffResult: DiffResult;
    changedFields: DiffNode[];
    behaviorFields: DiffNode[];
    profileFields: DiffNode[];
    localStateFields: DiffNode[];
    behaviorMatches: boolean;
    comparedConfigurationMatches: boolean;
}
/**
 * Compare two live agents through the same exclusions and identity rules as
 * the canonical AgentDiffViewer, while separating behavior from expected
 * personal-copy profile differences.
 */
declare function compareAgentDefinitions(systemAgent: ComparableAgent, personalAgent: ComparableAgent): AgentDefinitionComparison;

declare function promoteFailureMessage(err: unknown): string;
/**
 * What a restore does to the history, said ONCE. `agx_promote_version` copies the version's settings
 * onto the agent and the snapshot trigger SAVES THEM AS A NEW VERSION noted "Restored from v<N>"; the
 * agent's current version moves to it (aidream migration 20261021233500). Its answer carries that
 * number as `new_version`, and `unchanged: true` when the agent already matched (nothing saved).
 * The confirm dialog and the result notice both build their sentence from this one constant, so
 * neither can promise a row the other denies; `__tests__/promote-failure-message.test.ts` guards it.
 */
declare const PROMOTE_HISTORY_OUTCOME = "a new version";
/** The sentence the confirm shows BEFORE a restore (web dialog and desktop confirm). */
declare function promoteConfirmMessage(version: number, currentVersion?: number | null): string;
/** What the restore door answered, as the result sentence needs it (from `promoteAgentVersion`). */
interface PromoteOutcome {
    /** The version row the restore saved (`new_version`); null/undefined when the answer has none. */
    newVersion?: number | null;
    /** True when the agent already matched the restored version, so nothing was saved. */
    unchanged?: boolean;
}
/** The sentence a successful restore shows AFTER it ran. */
declare function promoteSuccessMessage(version: number, outcome?: PromoteOutcome): string;

/** One row of `agx_get_version_history`: a saved version of an agent (newest first). */
interface AgentVersionHistoryEntry {
    version_id: string;
    version_number: number;
    name: string;
    changed_at: string;
    change_note: string | null;
    contract_change: string | null;
    contract_break_declared: string | null;
    input_contract_hash: string | null;
    output_contract_hash: string | null;
}
/** A version id resolved to its agent and number (`agent.definition_version`). */
interface AgentVersionLookup {
    versionId: string;
    agentId: string;
    versionNumber: number;
    agentName: string | null;
}
/** What `agx_promote_version` answers. */
interface PromoteVersionResult {
    success: boolean;
    error?: string;
    promoted_version?: number;
    agent_id?: string;
    /** The version row the restore saved ("Restored from v<N>"); the agent's current version now. */
    new_version?: number;
    /** True when the agent already matched the restored version: no row was saved. */
    unchanged?: boolean;
}
/** A contract break a person declares on a version (null clears the declaration). */
type ContractBreakKind = "input" | "output" | "both";
/** A history entry with what changed since the version before it, once both snapshots were read. */
interface EnrichedVersion extends AgentVersionHistoryEntry {
    diffSummary?: DiffResult;
    snapshotLoaded: boolean;
}
/** The load state the version timeline renders (the host owns where snapshots are kept). */
interface VersionHistoryLoad {
    enrichedVersions: EnrichedVersion[];
    loading: boolean;
    progress: {
        fetched: number;
        total: number;
    };
    /** Versions whose snapshot read failed — never invisible. */
    failedVersions: number[];
    failureReason: string | null;
    fetchEnrichedHistory: () => void | Promise<void>;
    /** Read the named versions' snapshots (the timeline's Load on a gap). */
    fetchGap: (versionNumbers: number[]) => void | Promise<void>;
}

/**
 * The versions a "Load Full History" reads: the 10 newest, the oldest, and about every 10th in
 * between — enough to say what changed across a long history without reading every snapshot.
 */
declare function computeVersionFetchTargets(versions: readonly Pick<AgentVersionHistoryEntry, "version_number">[]): number[];
/**
 * Each version (newest first) with `snapshotLoaded` and, when it and the version before it were
 * both read, the diff between them. `snapshotOf` answers the host's stored snapshot or undefined.
 */
declare function enrichVersions<V extends AgentVersionHistoryEntry>(versions: readonly V[], snapshotOf: (versionNumber: number) => ComparableAgent | undefined): (V & EnrichedVersion)[];
/**
 * A raw `agx_get_version_snapshot` row in the agent-definition key names the diff adapters read
 * (`model_id` → `modelId`, `variable_definitions` → `variableDefinitions`, …). Top-level keys only;
 * values pass through untouched, so both sides of a comparison made this way read alike. A host
 * with its own parsed agent records (the web's Redux store) compares those instead.
 */
declare function snapshotToComparable(row: Record<string, unknown>): Record<string, unknown>;

/** The database's refusal, as supabase-js reports it. */
interface VersionsDbError {
    message: string;
    code?: string | null;
    details?: string | null;
    hint?: string | null;
}
type Answer = PromiseLike<{
    data: unknown;
    error: VersionsDbError | null;
}>;
/** The calls these reads make: a supabase-js client fits it as is. */
interface VersionsClient {
    rpc(fn: string, args: Record<string, unknown>): Answer;
    schema(name: "agent"): {
        rpc(fn: string, args: Record<string, unknown>): Answer;
        from(table: "definition_version" | "definition"): {
            select(columns: string): {
                eq(column: string, value: string): {
                    maybeSingle(): Answer;
                };
            };
        };
    };
}
/** A refused or failed read, carrying the database's own sentence. */
declare class AgentVersionsError extends Error {
    readonly code: string | null;
    readonly detail: string | null;
    readonly hint: string | null;
    constructor(error: VersionsDbError);
}
/** One page of an agent's saved versions, newest first. */
declare function listAgentVersions(client: VersionsClient, query: {
    agentId: string;
    limit?: number;
    offset?: number;
}): Promise<AgentVersionHistoryEntry[]>;
/** The raw snapshot row of one version (null: the database has no such version for this agent). */
declare function readAgentVersionSnapshot(client: VersionsClient, query: {
    agentId: string;
    version: number;
}): Promise<Record<string, unknown> | null>;
/** An immutable version id → its agent and number. RLS on agent.definition_version is the boundary. */
declare function resolveAgentVersionId(client: VersionsClient, versionId: string): Promise<AgentVersionLookup | null>;
/**
 * Restore: make a past version the agent's current definition (`agx_promote_version`). A refusal
 * throws with the database's sentence — show it with `promoteFailureMessage`.
 */
declare function promoteAgentVersion(client: VersionsClient, query: {
    agentId: string;
    version: number;
}): Promise<PromoteVersionResult>;
/**
 * The version the agent is at NOW (`agent.definition.version`), read from the agent itself. Null
 * when the person cannot read the agent.
 */
declare function readAgentCurrentVersion(client: VersionsClient, agentId: string): Promise<number | null>;
/** Declare (or clear, with null) a contract break the hashes cannot see. */
declare function declareContractBreak(client: VersionsClient, query: {
    agentId: string;
    version: number;
    kind: ContractBreakKind | null;
}): Promise<void>;

export { AGENT_DIFF_OPTIONS, AGENT_EXCLUDE_PATHS, AGENT_IDENTITY_KEYS, AgentVersionsError, PROMOTE_HISTORY_OUTCOME, compareAgentDefinitions, computeVersionFetchTargets, declareContractBreak, enrichVersions, listAgentVersions, promoteAgentVersion, promoteConfirmMessage, promoteFailureMessage, promoteSuccessMessage, readAgentCurrentVersion, readAgentVersionSnapshot, resolveAgentVersionId, snapshotToComparable };
export type { AgentDefinitionComparison, AgentVersionHistoryEntry, AgentVersionLookup, ComparableAgent, ContractBreakKind, EnrichedVersion, PromoteOutcome, PromoteVersionResult, VersionHistoryLoad, VersionsClient, VersionsDbError };