import { type ComposeQueryResult, type SemanticLayer, type SemanticExecutionReceiptV1, type SemanticTargetBindingV1 } from '@duckcodeailabs/dql-core';
import { type DbtCloudSemanticTestResult } from './dbt-cloud-semantic.js';
import { type SemanticRuntimePreference, type SemanticRuntimeSettingsInput } from './semantic-runtime-settings.js';
export type SemanticRuntimeAdapterId = 'native' | 'metricflow-cli' | 'dbt-cloud';
export type SemanticMetricExecutionStatus = 'ready' | 'requires_setup' | 'unsupported';
export interface SemanticRuntimeProjectConfig {
    semanticLayer?: {
        provider?: string;
        projectPath?: string;
    };
    dbt?: {
        projectDir?: string;
        profilesDir?: string;
    };
}
export interface SemanticRuntimeAdapterStatus {
    id: SemanticRuntimeAdapterId;
    label: string;
    bundled: boolean;
    configured: boolean;
    tested: boolean;
    ready: boolean;
    source: 'bundled' | 'local' | 'env' | 'none';
    detail: string;
}
export interface SemanticRuntimeStatus {
    preference: SemanticRuntimePreference;
    active: SemanticRuntimeAdapterId;
    adapters: SemanticRuntimeAdapterStatus[];
    setup: string | null;
}
export interface SemanticMetricExecutionCapability {
    status: SemanticMetricExecutionStatus;
    engine: SemanticRuntimeAdapterId | null;
    reason: string | null;
    reasonCode?: 'SEMANTIC_SOURCE_DRIFT';
    semanticCatalogFingerprint?: string;
}
export interface SemanticRuntimeQueryRequest {
    metrics: string[];
    dimensions: string[];
    filters?: Array<{
        dimension?: string;
        operator?: string;
        values?: string[];
        expression?: string;
    }>;
    timeDimension?: {
        name: string;
        granularity: string;
    };
    orderBy?: Array<{
        name: string;
        direction: 'asc' | 'desc';
    }>;
    limit?: number;
    savedQuery?: string;
    engine?: 'native' | 'metricflow' | SemanticRuntimeAdapterId;
}
export type SemanticRuntimeBindingRole = 'dimension' | 'time_dimension' | 'filter' | 'order_by';
export interface SemanticRuntimeBinding {
    role: SemanticRuntimeBindingRole;
    /** Stable DQL/model-scoped identity shown to the analyst. */
    authoringReference: string;
    /** Exact dunder-qualified member sent to MetricFlow or dbt Cloud. */
    runtimeReference: string;
    /** Metric-relative entity path selected ahead of the member's own qualified name. */
    entityPath: string[];
    status: 'resolved' | 'ambiguous';
}
export interface SemanticRuntimePathCandidate {
    /** Stable evidence identity used by Ask clarification and retry. */
    id: string;
    label: string;
    description: string;
    authoringReference: string;
    runtimeReference: string;
    entityPath: string[];
    /** DQL-safe reference that preserves the model identity and the selected path. */
    selectionReference: string;
}
export interface SemanticRuntimeTraceStep {
    id: 'resolve_members' | 'bind_entity_paths' | 'compile_semantic_query' | 'validate_execution_target' | 'preflight_physical_sql' | 'execute_query';
    label: string;
    status: 'completed' | 'failed' | 'not_started';
    detail: string;
}
export interface SemanticRuntimeTrace {
    version: 1;
    adapter: SemanticRuntimeAdapterId;
    status: 'compiled' | 'ambiguous' | 'failed';
    authoringRequest: SemanticRuntimeQueryRequest;
    runtimeRequest?: SemanticRuntimeQueryRequest;
    bindings: SemanticRuntimeBinding[];
    warnings: string[];
    steps: SemanticRuntimeTraceStep[];
    /** Redacted compiler-to-warehouse target proof shown in Trust & Steps. */
    targetBinding?: SemanticTargetBindingV1;
    /** Terminal receipt added by the shared execution gateway. */
    executionReceipt?: SemanticExecutionReceiptV1;
    failure?: {
        code: 'SEMANTIC_PATH_AMBIGUOUS' | 'SEMANTIC_COMPILATION_FAILED' | 'SEMANTIC_SOURCE_DRIFT';
        phase: 'capability' | 'path_binding' | 'compilation';
        message: string;
        environmentId?: string;
        semanticCatalogFingerprint?: string;
        metricInventoryState?: 'missing' | 'partial' | 'complete';
        unavailableMetrics?: string[];
        safeActions?: string[];
        candidates?: SemanticRuntimePathCandidate[];
    };
}
export interface SemanticRuntimeCompileContext {
    projectRoot: string;
    projectConfig: SemanticRuntimeProjectConfig;
    detectedProvider?: string | null;
    semanticLayer: SemanticLayer;
    driver?: string;
    tableMapping?: Record<string, string>;
}
export interface SemanticRuntimeCompileResult extends ComposeQueryResult {
    engine: SemanticRuntimeAdapterId;
    /**
     * The governed request as the USER expressed it (preferably model-scoped
     * dimension identities), after deterministic normalization. Echoed to callers
     * and back into `.dql` sources — it must never be replaced by adapter-specific
     * MetricFlow spellings such as `entity__dim`.
     */
    effectiveRequest: SemanticRuntimeQueryRequest;
    /**
     * The request actually SENT to a full runtime (MetricFlow / dbt Cloud), with
     * dimensions/filters/order-by/time qualified to entity-qualified names. Absent
     * for native compilation (which speaks bare names). Diagnostic only.
     */
    runtimeRequest?: SemanticRuntimeQueryRequest;
    /** Auditable authoring → runtime bindings and compiler phases. */
    semanticTrace: SemanticRuntimeTrace;
    /** Non-fatal advisories (e.g. a time grain clamped up to the column's base). */
    warnings?: string[];
}
export declare class SemanticRuntimeRequiredError extends Error {
    readonly code = "SEMANTIC_RUNTIME_REQUIRED";
    constructor(message: string);
}
export declare class SemanticSourceDriftError extends Error {
    readonly code = "SEMANTIC_SOURCE_DRIFT";
    readonly details: {
        adapter: 'dbt-cloud';
        phase: 'capability';
        environmentId?: string;
        semanticCatalogFingerprint?: string;
        metricInventoryState: 'missing' | 'partial' | 'complete';
        requestedMetrics: string[];
        unavailableMetrics: string[];
        safeActions: string[];
        semanticTrace?: SemanticRuntimeTrace;
    };
    readonly semanticTrace?: SemanticRuntimeTrace;
    constructor(input: {
        environmentId?: string;
        semanticCatalogFingerprint?: string;
        metricInventoryState: 'missing' | 'partial' | 'complete';
        requestedMetrics: string[];
        unavailableMetrics: string[];
        authoringRequest?: SemanticRuntimeQueryRequest;
    });
}
export declare class SemanticRuntimeCompilationError extends Error {
    readonly code = "SEMANTIC_COMPILATION_FAILED";
    readonly adapter: Exclude<SemanticRuntimeAdapterId, 'native'>;
    constructor(adapter: Exclude<SemanticRuntimeAdapterId, 'native'>, error: unknown);
}
export declare class SemanticRuntimePathAmbiguityError extends Error {
    readonly code = "SEMANTIC_PATH_AMBIGUOUS";
    readonly adapter: Exclude<SemanticRuntimeAdapterId, 'native'>;
    readonly details: {
        authoringReference: string;
        runtimeReference: string;
        candidates: SemanticRuntimePathCandidate[];
    };
    readonly semanticTrace: SemanticRuntimeTrace;
    constructor(input: {
        adapter: Exclude<SemanticRuntimeAdapterId, 'native'>;
        authoringRequest: SemanticRuntimeQueryRequest;
        runtimeRequest: SemanticRuntimeQueryRequest;
        bindings: SemanticRuntimeBinding[];
        warnings: string[];
        authoringReference: string;
        runtimeReference: string;
        candidates: SemanticRuntimePathCandidate[];
    });
}
export declare function assertDbtCloudMetricInventory(projectRoot: string, metrics: string[], authoringRequest?: SemanticRuntimeQueryRequest): void;
/**
 * API-004 / AGT-001: MetricFlow requires `metric_time` whenever an input metric uses a time offset.
 * dbt stores that requirement in the metric definition, so normalize it once at
 * the shared runtime boundary instead of asking every UI and agent route to infer
 * the same compiler constraint independently.
 */
export declare function normalizeSemanticRuntimeQueryRequest(request: SemanticRuntimeQueryRequest, semanticLayer: SemanticLayer): SemanticRuntimeQueryRequest;
export declare function getSemanticRuntimeStatus(projectRoot: string, options?: {
    probeConfiguredCloud?: boolean;
}): Promise<SemanticRuntimeStatus>;
export declare function testSemanticRuntimeDraft(projectRoot: string, input: SemanticRuntimeSettingsInput): Promise<DbtCloudSemanticTestResult>;
/**
 * Rewrite a semantic request's dimension references (dimensions, filter
 * dimensions, order-by names, time dimension) from bare names to the
 * MetricFlow entity-qualified names the runtime expects, using the
 * compatibility service as the source of truth. Names it can't resolve pass
 * through unchanged (the 1.8.13 group-by suggestion-retry is the safety net).
 * `metric_time` is never rewritten. Also clamps a requested time grain up to
 * the column's base grain, collecting a warning. Pure — returns a new request.
 */
/**
 * Explain, actionably, why no full semantic runtime is active for a derived/
 * ratio/cumulative metric — probing the REAL runtime state so the message names
 * the actual gap instead of a generic "configure a runtime". Covers both traps:
 *   • dbt Cloud is configured but its connection test is failing (bad host/env/
 *     token or network) — so it never becomes active, and the query silently
 *     falls back to native, which can't compose a derived metric;
 *   • MetricFlow is installed but this server process can't find it, because the
 *     server was launched from a shell without the dbt virtualenv on PATH.
 */
/** A dbt Cloud connection error that reads like a rejected/expired token rather
 *  than a bad host or a network failure. Exported for testability. */
export declare function looksLikeAuthFailure(detail: string): boolean;
export declare function explainMissingSemanticRuntime(projectRoot: string, dbtProjectPath?: string): Promise<string>;
export declare function qualifyForMetricFlow(request: SemanticRuntimeQueryRequest, semanticLayer: SemanticLayer): {
    request: SemanticRuntimeQueryRequest;
    warnings: string[];
    bindings: SemanticRuntimeBinding[];
};
export declare function parseSemanticDimensionSelection(value: string): {
    reference: string;
    entityPath?: string[];
};
export declare function formatSemanticDimensionSelection(reference: string, entityPath: string[]): string;
export declare function applySemanticPathSelection(request: SemanticRuntimeQueryRequest, authoringReference: string, entityPath: string[]): SemanticRuntimeQueryRequest;
export declare function encodeSemanticPathEvidenceId(authoringReference: string, entityPath: string[]): string;
export declare function decodeSemanticPathEvidenceId(value: string | undefined): {
    authoringReference: string;
    entityPath: string[];
} | undefined;
export declare function semanticPathAmbiguityFromError(input: {
    adapter: Exclude<SemanticRuntimeAdapterId, 'native'>;
    error: unknown;
    authoringRequest: SemanticRuntimeQueryRequest;
    runtimeRequest: SemanticRuntimeQueryRequest;
    bindings: SemanticRuntimeBinding[];
    warnings: string[];
}): SemanticRuntimePathAmbiguityError | undefined;
export declare function compileSemanticRuntimeQuery(request: SemanticRuntimeQueryRequest, context: SemanticRuntimeCompileContext): Promise<SemanticRuntimeCompileResult | null>;
/**
 * AGT-013/AGT-014/SEC-004: planning selects one adapter. Compilation may not
 * silently downgrade to another semantic engine or native SQL after selection.
 */
export declare function selectSemanticRuntimeAdapters(requested: SemanticRuntimeQueryRequest['engine'], active: SemanticRuntimeAdapterId): SemanticRuntimeAdapterId[];
/** A compatible dimension enriched with its MetricFlow-qualified name and, for
 *  time dimensions, real queryable grains. */
export type RuntimeCompatibleDimension = ReturnType<SemanticLayer['listDimensions']>[number] & {
    qualifiedName?: string;
    granularities?: string[];
};
export interface RuntimeCompatibilityResult {
    /** The engine that produced this compatibility answer. */
    engine: SemanticRuntimeAdapterId;
    dimensions: RuntimeCompatibleDimension[];
    incompatible: Array<{
        name: string;
        qualifiedName?: string;
        reason: string;
    }>;
    /** Retained for wire compatibility; selected-adapter failures no longer downgrade. */
    degraded?: string;
}
/**
 * The authoritative per-metric dimension-compatibility answer from the exact
 * adapter selected for execution. A selected adapter failure is preserved; it
 * never becomes a native compatibility answer.
 */
export declare function describeRuntimeCompatibility(projectRoot: string, semanticLayer: SemanticLayer, metrics: string[], projectConfig?: SemanticRuntimeProjectConfig): Promise<RuntimeCompatibilityResult>;
export declare function listRuntimeCompatibleDimensions(projectRoot: string, semanticLayer: SemanticLayer, metrics: string[], projectConfig?: SemanticRuntimeProjectConfig): Promise<Array<ReturnType<SemanticLayer['listDimensions']>[number]>>;
export declare function semanticMetricExecutionCapability(metricName: string, semanticLayer: SemanticLayer, provider: string, runtime: SemanticRuntimeStatus, projectRoot?: string): SemanticMetricExecutionCapability;
export declare function isSemanticRuntimeError(error: unknown): boolean;
export declare function semanticRuntimeErrorCode(error: unknown): 'SEMANTIC_RUNTIME_REQUIRED' | 'SEMANTIC_COMPILATION_FAILED' | 'SEMANTIC_PATH_AMBIGUOUS' | 'SEMANTIC_SOURCE_DRIFT' | undefined;
export declare function semanticRuntimeErrorDetails(error: unknown): unknown;
//# sourceMappingURL=semantic-runtime.d.ts.map