/**
 * The default model (`agent-engine` setting): which engine and model a chat
 * uses when neither the app nor the chat picks one.
 *
 * It belongs to the organization, and only owners and admins change it. A
 * signed-in user with no organization keeps their own. Every reader and writer
 * goes through this module so the scope rules live in one place.
 */
import type { AuditAttribution } from "../audit/attribution.js";
export declare const DEFAULT_AGENT_ENGINE_SETTING_KEY = "agent-engine";
/** Audit target type for default-model changes and refused attempts. */
export declare const DEFAULT_AGENT_ENGINE_AUDIT_TARGET_TYPE = "agent-default-model";
export type DefaultAgentEngineScope = "org" | "user";
/**
 * Where the effective default came from. `legacy` is the deployment-wide row
 * every organization shared before defaults were scoped; `none` means nothing
 * is stored and resolution falls through to credential detection.
 */
export type DefaultAgentEngineSource = DefaultAgentEngineScope | "legacy" | "none";
export interface DefaultAgentEngineContext {
    userEmail?: string | null;
    orgId?: string | null;
    orgScope?: "personal";
    defaultAgentEngineScope?: "deployment";
}
export interface DefaultAgentEngineRead {
    /** The stored `{ engine, model }` row, or null when no default applies. */
    value: Record<string, unknown> | null;
    source: DefaultAgentEngineSource;
}
export type DefaultAgentEngineAuthority = {
    allowed: true;
    scope: "org";
    orgId: string;
    userEmail: string;
} | {
    allowed: true;
    scope: "user";
    userEmail: string;
} | {
    allowed: false;
    reason: "unauthenticated" | "not-admin" | "scope-unavailable";
    message: string;
};
export interface DefaultAgentEngineChangeMeta {
    /** Action or route name recorded on the audit event. */
    actionName: string;
    attribution: AuditAttribution;
}
export interface DefaultAgentEngineSelection {
    engine: string;
    model: string;
}
/**
 * Read the default that applies to `ctx` (the current request when omitted):
 * the organization's row, else an explicitly personal user's own row, else
 * the legacy deployment-wide row. An unresolved scope throws before fallback.
 *
 * A scoped row with no engine is an explicit "cleared" marker. It answers for
 * that scope instead of falling through to the legacy row, so clearing the
 * default actually clears it for an organization that inherited a legacy one.
 */
export declare function readDefaultAgentEngineSettingDetailed(ctx?: DefaultAgentEngineContext): Promise<DefaultAgentEngineRead>;
/** {@link readDefaultAgentEngineSettingDetailed}, value only. */
export declare function readDefaultAgentEngineSetting(ctx?: DefaultAgentEngineContext): Promise<Record<string, unknown> | null>;
/**
 * Who may change the default for `ctx`: owners and admins change their
 * organization's; a signed-in user with no organization changes their own.
 */
export declare function resolveDefaultAgentEngineAuthority(ctx?: DefaultAgentEngineContext): Promise<DefaultAgentEngineAuthority>;
/**
 * Save the default for the authority's scope. Validate the engine first; this
 * stores only that scope and records the change.
 */
export declare function writeDefaultAgentEngineSelection(authority: Extract<DefaultAgentEngineAuthority, {
    allowed: true;
}>, selection: DefaultAgentEngineSelection, meta: DefaultAgentEngineChangeMeta): Promise<void>;
/**
 * Clear the default for the authority's scope. Writes a cleared marker rather
 * than deleting the row; see {@link readDefaultAgentEngineSettingDetailed}.
 */
export declare function clearDefaultAgentEngineSelection(authority: Extract<DefaultAgentEngineAuthority, {
    allowed: true;
}>, meta: DefaultAgentEngineChangeMeta): Promise<void>;
/** Record a refused change so owners and admins can see who tried. */
export declare function recordDefaultAgentEngineRefusal(ctx: DefaultAgentEngineContext, authority: Extract<DefaultAgentEngineAuthority, {
    allowed: false;
}>, operation: "set" | "clear", meta: DefaultAgentEngineChangeMeta, selection?: {
    engine: string;
    model?: string;
}): Promise<void>;