/**
 * Versioned cross-surface contracts for analytical composition and repair.
 *
 * These types deliberately contain no agent or UI concepts. Ask, Notebook,
 * CLI, MCP, Chat, and execution adapters exchange the same serialized shapes.
 *
 * Acceptance: CONTRACT-002, AGT-017, API-007, SEC-004.
 */
export declare const ANALYTICAL_QUESTION_FRAME_VERSION: 2;
export declare const ANALYTICAL_FAILURE_VERSION: 1;
export declare const ANALYTICAL_FAILURE_V2_VERSION: 2;
export declare const ANALYTICAL_REPAIR_CAPABILITY_VERSION: 1;
export declare const PROVIDER_EGRESS_RECEIPT_VERSION: 1;
export type AnalyticalDimensionRole = 'group_by' | 'filter' | 'display' | 'rank_entity' | 'time_axis';
export type AnalyticalQuestionType = 'definition' | 'scalar' | 'ranking' | 'trend' | 'comparison' | 'diagnosis' | 'research';
export type AnalyticalPeriodKind = 'absolute' | 'current' | 'previous_period' | 'previous_year';
export interface AnalyticalDimensionBindingV2 {
    dimensionId: string;
    role: AnalyticalDimensionRole;
    requestedLabel?: string;
}
export interface AnalyticalMemberBindingV2 {
    dimensionId: string;
    canonicalValues: unknown[];
    source: 'question' | 'clarification' | 'prior_result' | 'parameter';
    confidence: 'exact' | 'high' | 'medium';
    sourceTurnId?: string;
}
export interface AnalyticalPeriodV2 {
    id: string;
    kind: AnalyticalPeriodKind;
    start?: string;
    end?: string;
    alignToPeriodId?: string;
}
export interface AnalyticalTimeContextV2 {
    timeDimensionId?: string;
    timeRole?: string;
    calendarId?: string;
    timezone?: string;
    grain?: string;
    completenessPolicy?: 'partial_current' | 'latest_complete' | 'closed_period';
    periods: AnalyticalPeriodV2[];
}
export interface AnalyticalComparisonV2 {
    basePeriodId: string;
    comparisonPeriodIds: string[];
    alignment?: 'elapsed_period' | 'calendar_period' | 'fiscal_period';
    outputs: Array<'value' | 'absolute_delta' | 'percent_delta'>;
    zeroDenominatorPolicy: 'null' | 'not_applicable';
}
export interface AnalyticalRankingV2 {
    entityDimensionId: string;
    byMetricId: string;
    byPeriodId?: string;
    direction: 'asc' | 'desc';
    limit: number;
    tiePolicy: 'stable_secondary_key' | 'include_ties';
}
export interface AnalyticalRequestedOutputV2 {
    id: string;
    kind: 'dimension' | 'metric_value' | 'delta' | 'percent_delta' | 'rank';
    metricId?: string;
    periodId?: string;
}
export interface AnalyticalAmbiguityV2 {
    field: string;
    candidateIds: string[];
    reasonCode: string;
}
export interface AnalyticalQuestionFrameV2 {
    version: 2;
    interpretedQuestion: string;
    questionType: AnalyticalQuestionType;
    metricConceptIds: string[];
    entityGrainIds: string[];
    dimensions: AnalyticalDimensionBindingV2[];
    memberBindings: AnalyticalMemberBindingV2[];
    timeContext?: AnalyticalTimeContextV2;
    comparison?: AnalyticalComparisonV2;
    ranking?: AnalyticalRankingV2;
    requestedOutputs: AnalyticalRequestedOutputV2[];
    ambiguity: AnalyticalAmbiguityV2[];
}
export type AnalyticalOperation = 'filter' | 'group' | 'trend' | 'compare' | 'rank' | 'window' | 'having';
/**
 * One immutable relationship authority selected with an analytical metric.
 * DQL relationship IDs and adapter-native semantic paths remain distinct:
 * only the former can authorize generated physical SQL joins.
 */
export interface ResolvedRelationshipProofV1 {
    version: 1;
    kind: 'dql_relationship_path' | 'semantic_native_grouping';
    metricId: string;
    dimensionId: string;
    sourceEntityId: string;
    targetEntityId: string;
    route: MetricCapabilityContract['executionCapabilities'][number]['route'];
    adapterId?: string;
    executionId: string;
    snapshotId: string;
    capabilityFingerprint: string;
    relationshipPathIds: string[];
    nativeGroupingReference?: string;
    nativeGroupingPath?: string[];
    authorityFingerprint: string;
}
export interface MetricCapabilityContract {
    metricId: string;
    semanticModelId?: string;
    measureIds: string[];
    primaryEntityId: string;
    /** Result grain used when the question requests no grouping dimension. */
    defaultResultGrainId: string;
    resultGrainIds: string[];
    aggregation: string;
    additivity: {
        entities: 'additive' | 'semi_additive' | 'non_additive';
        time: 'additive' | 'semi_additive' | 'non_additive';
        nonAdditiveDimensionIds?: string[];
    };
    dimensions: Array<{
        dimensionId: string;
        /** Entity grain produced/filtered by this dimension. */
        entityId: string;
        supportedRoles: AnalyticalDimensionRole[];
        /** Authored semantic-layer display label; never inferred from the ID. */
        label?: string;
        /** Authored registry aliases retained for deterministic binding only. */
        aliases?: string[];
        /** Exact adapter-native group-by reference proved compatible for this metric. */
        nativeGroupingReference?: string;
        /** Exact adapter-native entity path; empty means the metric's own model. */
        nativeGroupingPath?: string[];
        relationshipPathIds?: string[];
    }>;
    timeDimensions: Array<{
        dimensionId: string;
        role: string;
        supportedGrains: string[];
        defaultFor?: Array<'scalar' | 'trend' | 'comparison'>;
    }>;
    freshness?: {
        observedThroughFieldId?: string;
        defaultCompletenessPolicy?: 'partial_current' | 'latest_complete' | 'closed_period';
    };
    operations: AnalyticalOperation[];
    supportedOutputKinds: AnalyticalRequestedOutputV2['kind'][];
    /** Certified assets may further restrict the exact output aliases. */
    declaredOutputIds?: string[];
    executionCapabilities: Array<{
        route: 'certified' | 'semantic' | 'governed_sql' | 'exploratory';
        adapterId?: string;
    }>;
    sourceFingerprint: string;
}
export interface AnalyticalPolicyContract {
    policyId: string;
    sourceHash: string;
    metricIds?: string[];
    timeRole?: string;
    calendarId?: string;
    timezone?: string;
    completenessPolicy?: 'partial_current' | 'latest_complete' | 'closed_period';
    comparisonAlignment?: 'elapsed_period' | 'calendar_period' | 'fiscal_period';
    defaultRankingPeriod?: 'current' | 'comparison';
    narrativeGuidance?: string[];
}
export type AnalyticalFailureCode = 'COLUMN_NOT_FOUND' | 'RELATION_NOT_FOUND' | 'PERMISSION_DENIED' | 'AMBIGUOUS_COLUMN' | 'DIALECT_ERROR' | 'SNAPSHOT_DRIFT' | 'TIMEOUT' | 'RESULT_CONTRACT_MISMATCH' | 'COMPILATION_FAILED' | 'POLICY_DENIED';
export type AnalyticalFailurePhase = 'planning' | 'compilation' | 'validation' | 'execution' | 'result_validation';
export type AnalyticalFailureRecoverability = 'retry_same' | 'refresh_snapshot' | 'edit_dql' | 'edit_sql' | 'change_authorized_connection' | 'request_access' | 'modeling_change' | 'none';
export interface AnalyticalFailureV1 {
    version: 1;
    runId: string;
    failureId: string;
    code: AnalyticalFailureCode;
    phase: AnalyticalFailurePhase;
    message: string;
    recoverability: AnalyticalFailureRecoverability;
    failedBindings: Array<{
        qualifiedId?: string;
        role?: string;
        reasonCode: string;
    }>;
    snapshotId: string;
    planFingerprint?: string;
    dqlFingerprint?: string;
    sqlFingerprint?: string;
    safeActions: string[];
    /**
     * The redacted PRODUCER text behind `message`, for the inspector only.
     *
     * `message` is a fixed safe string chosen by failure code — that redaction is
     * the governance contract and stays. But discarding the driver/compiler text
     * entirely meant a real error like `Binder Error: column "amt" not found` was
     * unrecoverable even for the person debugging it, and every unclassified
     * failure read as the same generic sentence. Credentials, connection strings
     * and quoted literals are already stripped by `redactAnalyticalDiagnostic`.
     */
    diagnostic?: string;
}
export type AnalyticalFailureCodeV2 = AnalyticalFailureCode | 'SEMANTIC_ADAPTER_NOT_READY' | 'SEMANTIC_TARGET_BINDING_MISSING' | 'EXECUTION_TARGET_MISMATCH' | 'SEMANTIC_SOURCE_DRIFT' | 'SEMANTIC_MEMBER_BINDING_FAILED' | 'SEMANTIC_PATH_AMBIGUOUS' | 'IDENTIFIER_SCOPE_INVALID' | 'EXECUTION_CANCELLED' | 'SEMANTIC_COMPILATION_TIMEOUT';
export interface AnalyticalFailureV2 extends Omit<AnalyticalFailureV1, 'version' | 'code'> {
    version: 2;
    code: AnalyticalFailureCodeV2;
    expectedTargetFingerprint?: string;
    actualTargetFingerprint?: string;
    adapterId?: string;
    queryId?: string;
    sqlState?: string;
    vendorCode?: string;
}
export type AnalyticalTrustState = 'certified' | 'governed' | 'review_required';
export type AnalyticalRepairChange = 'parameter_only' | 'display_only' | 'dql_source' | 'sql_text' | 'snapshot_refresh' | 'connection_change' | 'reviewed_draft_promotion';
export interface AnalyticalRepairTrustTransition {
    previous: AnalyticalTrustState;
    next: AnalyticalTrustState;
    requiresNewReceipt: boolean;
    requiresReview: boolean;
    preservesCertifiedAssetIdentity: boolean;
}
export type AnalyticalAutomaticRepairAction = 'repair_embedded_sql' | 'none';
export type AnalyticalRepairCorrectionCode = 'SQL_EXECUTION_REPAIR' | 'MANUAL_REVIEW_REQUIRED';
export type AnalyticalManualRepairAction = 'edit_dql' | 'open_sql_notebook' | 'refresh_snapshot' | 'retry_same_plan' | 'change_authorized_connection' | 'request_access';
export type AnalyticalRepairIneligibilityReason = 'failure_not_eligible' | 'missing_failure_authority' | 'missing_dql_wrapper' | 'invalid_dql_wrapper' | 'missing_compiled_sql' | 'missing_plan_fingerprint' | 'missing_execution_target' | 'attempt_exhausted';
/**
 * Server-owned authority for one automatic Ask execution repair.
 *
 * A retained warehouse diagnostic is deliberately absent: it may explain a
 * failure, but it never grants repair authority. Legacy runs without this
 * capability remain readable and are manual-only.
 */
export interface AnalyticalRepairCapabilityV1 {
    version: 1;
    automatic: {
        eligible: boolean;
        action: AnalyticalAutomaticRepairAction;
        correctionCode: AnalyticalRepairCorrectionCode;
        attemptsRemaining: number;
    };
    failureFingerprint: string;
    sourceFingerprint: string;
    planFingerprint: string;
    dqlFingerprint: string;
    sqlFingerprint: string;
    targetFingerprint: string;
    routeLocked: true;
    targetLocked: true;
    sourceImmutable: true;
    manualActions: AnalyticalManualRepairAction[];
    ineligibilityReason?: AnalyticalRepairIneligibilityReason;
}
export type ProviderEgressPurpose = 'answer_generation'
/** Ordinary Ask narration: the provider writes the business-facing answer. */
 | 'answer_narration' | 'research_narration' | 'research_tool' | 'repair_sql';
export type ProviderEgressCategory = 'instructions' | 'question' | 'schema_metadata' | 'governed_context' | 'result_rows';
/** Server-owned orchestration phase for one physical provider dispatch. */
export type ProviderDispatchPhaseV1 = 'meaning_resolution' | 'planning' | 'generation' | 'narration' | 'repair';
/** Content-free evidence for one provider-bound payload class. */
export interface ProviderEgressReceiptV1 {
    version: 1;
    purpose: ProviderEgressPurpose;
    /** Additive for legacy compatibility; absent means the phase was not recorded. */
    dispatchPhase?: ProviderDispatchPhaseV1;
    provider: string;
    /** Exact physical transport identity; absent only on legacy receipts. */
    model?: string;
    operation?: 'generate' | 'generate_with_tools' | 'generate_stream';
    attemptIndex?: number;
    options?: {
        maxTokens?: number;
        temperature?: number;
        reasoningEffort?: 'low' | 'medium' | 'high';
    };
    permittedCategories: ProviderEgressCategory[];
    resultRowCount: number;
    /** Rows disclosed so far in this receipt's per-run budget group. */
    cumulativeResultRowCount?: number;
    columnCount: number;
    redactionPolicyId: string;
    optIn: boolean;
    payloadFingerprint: string;
}
/** Strictly normalize server-owned automatic repair authority. */
export declare function normalizeAnalyticalRepairCapabilityV1(value: unknown): AnalyticalRepairCapabilityV1 | undefined;
/** Strictly normalize a content-free provider egress receipt. */
export declare function normalizeProviderEgressReceiptV1(value: unknown): ProviderEgressReceiptV1 | undefined;
/** Strictly normalize an untrusted cross-surface analytical frame. */
export declare function normalizeAnalyticalQuestionFrameV2(value: unknown): AnalyticalQuestionFrameV2 | undefined;
/** Strictly normalize capability metadata before it becomes routing evidence. */
export declare function normalizeMetricCapabilityContract(value: unknown): MetricCapabilityContract | undefined;
/** Strictly normalize a failure returned by any DQL analytical surface. */
export declare function normalizeAnalyticalFailureV1(value: unknown): AnalyticalFailureV1 | undefined;
/** Strictly normalize the target-bound failure returned by any DQL surface. */
export declare function normalizeAnalyticalFailureV2(value: unknown): AnalyticalFailureV2 | undefined;
/** Apply the RFC 0005 trust matrix before a derived repair is exposed. */
export declare function analyticalRepairTrustTransition(input: {
    previous: AnalyticalTrustState;
    change: AnalyticalRepairChange;
    governedValidationPassed?: boolean;
}): AnalyticalRepairTrustTransition;
//# sourceMappingURL=analytical.d.ts.map