import { SmrtClassOptions } from '@happyvertical/smrt-core';
import { DataQueryFieldDescriptor, DataQueryRequest, DataQueryResult, DataQueryRow, DataQuerySchema } from '@happyvertical/smrt-types';
import { PrincipalRun } from './execute-as-principal.js';
import { PrincipalTool } from './invoke-agent.js';
export declare const DATA_DISCOVER_TOOL_SLUG = "data.discover";
export declare const DATA_INSPECT_TOOL_SLUG = "data.inspect";
export declare const DATA_QUERY_TOOL_SLUG = "data.query";
export declare const DATA_DISCOVER_FUNCTION_NAME = "data-discover";
export declare const DATA_INSPECT_FUNCTION_NAME = "data-inspect";
export declare const DATA_QUERY_FUNCTION_NAME = "data-query";
export declare const DEFAULT_DATA_SURFACE_DEADLINE_MS = 5000;
export declare const MAX_DATA_SURFACE_DEADLINE_MS = 30000;
/** Declarative, non-authoritative metadata that a server-owned catalog may expose. */
export type DataSurfaceMetadataValue = string | number | boolean | null | ReadonlyArray<string | number | boolean | null>;
export type DataSurfaceFieldMetadata = Readonly<Record<string, DataSurfaceMetadataValue>>;
/** Surface-level metadata is descriptive only; it never enters query normalization. */
export type DataSurfaceMetadata = Readonly<Record<string, DataSurfaceMetadataValue>>;
/** A data field plus server-owned visibility policy annotations. */
export interface DataSurfaceField extends DataQueryFieldDescriptor {
    sensitive?: boolean;
    readPermission?: string;
    metadata?: DataSurfaceFieldMetadata;
}
/** Server-owned schema; policy annotations never cross the core query boundary. */
export interface DataSurfaceSchema extends Omit<DataQuerySchema, 'fields'> {
    fields: DataSurfaceField[];
}
/** A server-owned data source. Never construct this from model/tool input. */
export interface DataSurfaceDefinition {
    /** Stable opaque id presented to the model. */
    id: string;
    /** Permission-catalog collection used for the read gate. */
    collection: string;
    /** Optional backing SMRT class, useful to registry-backed executors. */
    className?: string;
    label?: string;
    description?: string;
    /** Safe catalog metadata, returned only after the read gate succeeds. */
    metadata?: DataSurfaceMetadata;
    schema: DataSurfaceSchema;
    /** Optional surface-specific executor. */
    execute?: DataSurfaceExecutor;
}
export interface DataSurfacePrincipal {
    /** The authenticated execution principal, copied from the live run. */
    userId: string;
    /** The authenticated tenant scope, copied from the live run. */
    tenantId: string | null;
}
export interface DataSurfaceExecutionContext {
    run: PrincipalRun;
    principal: DataSurfacePrincipal;
    db?: SmrtClassOptions['db'];
    /** Signal for adapters that can cancel database work. */
    signal: AbortSignal;
}
export type DataSurfaceExecutorResult = DataQueryResult | DataQueryRow[] | {
    rows?: DataQueryRow[];
    total?: DataQueryResult['total'];
    facets?: DataQueryResult['facets'];
    freshness?: DataQueryResult['freshness'];
    warnings?: string[];
    truncated?: boolean;
    nextCursor?: string;
    hasMore?: boolean;
};
export type DataSurfaceExecutor = (surface: DataSurfaceDefinition, request: DataQueryRequest, context: DataSurfaceExecutionContext) => Promise<DataSurfaceExecutorResult>;
export interface DataSurfaceAuditEntry {
    action: 'discover' | 'inspect' | 'query';
    surfaceId?: string;
    requestId?: string;
    userId: string;
    tenantId: string | null;
    rowCount?: number;
    truncated?: boolean;
}
export type DataSurfaceAuditSink = (entry: DataSurfaceAuditEntry) => void | Promise<void>;
export interface DataSurfaceToolsOptions {
    /** Server-owned catalog. A function is evaluated per authenticated run. */
    surfaces: readonly DataSurfaceDefinition[] | ((run: PrincipalRun) => readonly DataSurfaceDefinition[] | Promise<readonly DataSurfaceDefinition[]>);
    /** Shared executor used when a definition does not provide one. */
    execute?: DataSurfaceExecutor;
    /** Audit sink for individual tool actions. */
    audit?: DataSurfaceAuditSink;
    /** Deadline for an adapter call. Defaults to five seconds. */
    deadlineMs?: number;
    /** Receives detailed server-side failures; never surfaced to the model. */
    onFailure?: DataSurfaceFailureSink;
}
export interface DataSurfaceFailureEntry {
    action: 'discover' | 'inspect' | 'query';
    surfaceId?: string;
    requestId?: string;
    userId: string;
    tenantId: string | null;
    error: unknown;
}
export type DataSurfaceFailureSink = (entry: DataSurfaceFailureEntry) => void | Promise<void>;
export declare class DataSurfaceDeniedError extends Error {
    readonly status = 403;
    constructor();
}
export declare class DataSurfaceDeadlineError extends Error {
    readonly status = 504;
    constructor();
}
/** Adapter output was not in the requested deterministic order. */
export declare class DataSurfaceResultOrderError extends Error {
    readonly status = 502;
    constructor();
}
/** Stable public failure for executor and result-boundary errors. */
export declare class DataSurfaceQueryError extends Error {
    readonly status = 502;
    readonly code = "DATA_SURFACE_QUERY_FAILED";
    constructor();
}
/** Stable public failure for requests that name hidden schema capabilities. */
export declare class DataSurfaceRequestError extends Error {
    readonly status = 400;
    readonly code = "DATA_SURFACE_REQUEST_INVALID";
    constructor();
}
/**
 * Create the fingerprint for the already-normalized request passed to a
 * surface executor. This supports internal projections beyond core's public
 * 50-field projection limit; callers must use the exact request received.
 */
export declare function createDataSurfaceQueryFingerprint(request: DataQueryRequest): string;
/** Build the discover/inspect/query tools for a persona conversation. */
export declare function createDataSurfaceTools(options: DataSurfaceToolsOptions): PrincipalTool[];
//# sourceMappingURL=data-surface.d.ts.map