/**
 * IntrospectionResolver - GraphQL-style introspection for MCP-AQL
 *
 * Provides discovery capabilities for LLMs to understand available operations,
 * their parameters, return types, and examples.
 *
 * INTROSPECTION QUERIES:
 * - operations: List all available operations
 * - operation(name): Get details for a specific operation
 * - types: List available types (ElementType, etc.)
 * - type(name): Get details for a specific type
 * - categories: Category format rules + discovery guidance (Issue #631)
 *
 * DESIGN RATIONALE:
 * - Token-efficient: Returns minimal but useful information
 * - Self-documenting: Operations describe themselves
 * - Read-only: Safe to call at any time (no side effects)
 *
 * SCHEMA INTEGRATION (Issue #254):
 * - Schema-driven operations get their metadata from OperationSchema
 * - Legacy operations use the fallback OPERATION_PARAMETERS/OPERATION_EXAMPLES
 * - This ensures single source of truth for schema-driven operations
 */
import { type CRUDEndpoint } from './OperationRouter.js';
import { type EndpointPermissions } from './PermissionGuard.js';
/**
 * Basic information about an operation (used in list responses)
 */
export interface OperationInfo {
    /** Operation name (e.g., 'create_element') */
    name: string;
    /** CRUD endpoint this operation belongs to */
    endpoint: string;
    /** Brief description of what the operation does */
    description: string;
}
/**
 * Parameter information for operation details
 */
export interface ParameterInfo {
    /** Parameter name */
    name: string;
    /** Parameter type (e.g., 'string', 'ElementType', 'object') */
    type: string;
    /** Whether the parameter is required */
    required: boolean;
    /** Brief description of the parameter */
    description: string;
    /** Default value if any */
    default?: unknown;
}
/**
 * Return type information
 */
export interface TypeInfo {
    /** Type name */
    name: string;
    /** Type kind (enum, object, scalar, union) */
    kind: 'enum' | 'object' | 'scalar' | 'union';
    /** Brief description */
    description?: string;
}
/**
 * Detailed information about a specific operation
 */
export interface OperationDetails {
    /** Operation name */
    name: string;
    /** CRUD endpoint */
    endpoint: string;
    /** MCP tool name (e.g., 'mcp_aql_read') */
    mcpTool: string;
    /** Full description */
    description: string;
    /** Permission flags */
    permissions: EndpointPermissions;
    /** Parameter definitions */
    parameters: ParameterInfo[];
    /** Return type information */
    returns: TypeInfo;
    /** Usage examples */
    examples: string[];
    /** Alternative operation names that resolve to this operation */
    aliases?: string[];
}
/**
 * Detailed type information with enum values or object fields
 */
export interface TypeDetails {
    /** Type name */
    name: string;
    /** Type kind */
    kind: 'enum' | 'object' | 'scalar' | 'union';
    /** Full description */
    description: string;
    /** Enum values (for enum types) */
    values?: string[];
    /** Object fields (for object types) */
    fields?: ParameterInfo[];
    /** Union member types (for union types) */
    members?: string[];
}
/**
 * Format specification for an element type (Issue #715)
 */
export interface FormatSpec {
    /** Element type this spec describes */
    elementType: string;
    /** File format used for storage */
    fileFormat: string;
    /** Required fields in frontmatter */
    requiredFields: string[];
    /** Optional fields in frontmatter */
    optionalFields: string[];
    /** Guidance on using instructions vs content fields */
    dualFieldGuidance: string;
    /** Syntax notes specific to this element type */
    syntaxNotes: string[];
    /** Minimal working example */
    minimalExample: string;
    /** Full-featured example */
    fullExample: string;
    /** Naming conventions for this element type */
    namingConventions: string[];
}
/**
 * Result of an introspection query
 */
export interface IntrospectionResult {
    /** List of operations (for 'operations' query) */
    operations?: OperationInfo[];
    /** Single operation details (for 'operation(name)' query) */
    operation?: OperationDetails | null;
    /** List of types (for 'types' query) */
    types?: TypeInfo[];
    /** Single type details (for 'type(name)' query) */
    type?: TypeDetails | null;
    /** Format specification (for 'format' query) */
    formatSpec?: FormatSpec | FormatSpec[] | null;
    /** Category discovery info (for 'categories' query, Issue #631) */
    categories?: Record<string, unknown>;
}
/**
 * Resolver for introspection queries.
 * Provides self-documentation capabilities for MCP-AQL operations.
 */
export declare class IntrospectionResolver {
    /**
     * Execute an introspection query
     *
     * @param params - Introspection parameters
     * @param params.query - What to introspect: 'operations', 'types', 'format', or 'categories'
     * @param params.name - Optional: specific operation or type name
     * @returns IntrospectionResult with requested information
     */
    static resolve(params: Record<string, unknown>): IntrospectionResult;
    /**
     * List all available operations
     *
     * For schema-driven operations, uses description from OperationSchema.
     * For legacy operations, uses description from OPERATION_ROUTES.
     *
     * @see Issue #254 - Single source of truth from schema
     */
    private static listOperations;
    /**
     * Get detailed information about a specific operation
     *
     * For schema-driven operations, reads metadata from OperationSchema.
     * For legacy operations, uses fallback OPERATION_PARAMETERS/OPERATION_EXAMPLES.
     *
     * @see Issue #254 - Auto-generate introspection from schema
     */
    private static getOperationDetails;
    /**
     * Get operation details from OperationSchema (dispatch-driven or introspection-only)
     *
     * @see Issue #254 - Single source of truth from schema
     * @see Issue #594 - Introspection-only schemas for all operations
     */
    private static getSchemaOperationDetails;
    /**
     * Get the return type for a legacy (non-schema) operation.
     * Schema-driven and introspection-only operations get return types from their schema definitions.
     */
    private static getReturnType;
    /**
     * List all available types
     */
    private static listTypes;
    /**
     * Get detailed information about a specific type
     */
    private static getTypeDetails;
    /**
     * Get format specification for an element type.
     * If name is provided, returns a single spec (or null for unknown types).
     * If name is omitted, returns all specs as an overview.
     *
     * @see Issue #715 - Proactive LLM guidance for element creation
     */
    private static getFormatSpec;
    /**
     * Issue #631: Category discovery info — format rules, allowed aggregation fields,
     * and guidance for discovering existing categories via query_elements.
     * IntrospectionResolver is stateless (no portfolio access), so live category data
     * must be fetched via query_elements with aggregate: { group_by: "category" }.
     */
    private static getCategoryInfo;
    /**
     * Get operations grouped by endpoint
     * Utility method for documentation generation
     */
    static getOperationsByEndpoint(): Record<CRUDEndpoint, OperationInfo[]>;
    /**
     * Generate a compact summary for token-efficient responses
     */
    static getSummary(): string;
    /**
     * Get server capabilities grouped by user-intent category.
     * Reads category from each operation's schema definition at runtime.
     * Designed for extensibility — additional CapabilitySources (e.g. portfolio
     * elements from the capability index) can be registered via registerSource().
     *
     * @param params - Optional parameters
     * @param params.category - Filter to a specific category
     * @returns CapabilitiesResult with categorized operations
     * @see Issue #1760 - get_capabilities operation
     */
    static getCapabilities(params: Record<string, unknown>): Record<string, unknown>;
    /**
     * Build the full category map from all registered capability sources.
     * Returns sorted categories with descriptions and merged entries.
     */
    private static buildCategoryMap;
    /**
     * Filter the category map to a single matching category (case-insensitive).
     */
    private static filterByCategory;
    /**
     * Register an additional capability source.
     * Future element sources (reading from the capability index) can be
     * plugged in here without modifying the get_capabilities handler.
     * @see Issue #1760 - extensibility for portfolio element capabilities
     */
    static registerSource(source: CapabilitySource): void;
    /**
     * Truncate a description to a brief one-liner.
     * Takes the first sentence (up to first period followed by space or end).
     */
    private static toBrief;
}
/**
 * A single capability entry — represents one thing a user can do.
 */
export interface CapabilityEntry {
    /** Operation or capability name */
    name: string;
    /** One-line description */
    brief: string;
    /** Origin: 'server' for built-in operations, or 'skill:name', 'agent:name', etc. */
    source: string;
    /** CRUDE endpoint (for server operations) */
    endpoint?: string;
    /** Whether this capability is currently active or available to activate */
    status: 'active' | 'available';
}
/**
 * Interface for pluggable capability providers.
 * Implement this to contribute capabilities from new sources (e.g. portfolio elements).
 * @see Issue #1760 - extensibility for portfolio element capabilities
 */
export interface CapabilitySource {
    readonly sourceType: string;
    getCapabilities(): Record<string, CapabilityEntry[]>;
}
//# sourceMappingURL=IntrospectionResolver.d.ts.map