/**
 * SHIP Protocol - TypeScript Type Definitions
 * Success Heuristics for Intelligent Programming
 *
 * Version: 1.0.0
 * Specification: https://ship.vibeatlas.dev/spec/v1.0
 *
 * Copyright (c) 2025 VibeAtlas
 * Licensed under MIT License
 */
/**
 * SHIP Protocol version identifiers
 */
type ShipVersion = '1.0';
/**
 * Message types in the SHIP Protocol
 */
type ShipMessageType = 'ShipRequest' | 'ShipResponse' | 'ShipFeedback' | 'ShipError';
/**
 * Supported programming languages
 */
type Language = 'typescript' | 'javascript' | 'python' | 'java' | 'go' | 'rust' | 'csharp' | 'cpp' | 'ruby' | 'php' | 'swift' | 'kotlin' | 'other';
/**
 * AI model identifiers for optimization
 */
type AIModel = 'gpt-4' | 'gpt-4-turbo' | 'gpt-4o' | 'claude-opus' | 'claude-sonnet' | 'claude-haiku' | 'gemini-pro' | 'gemini-ultra' | 'codestral' | 'deepseek-coder' | 'other';
/**
 * Confidence levels for reliability predictions
 */
type ConfidenceLevel = 'very_high' | 'high' | 'medium' | 'low' | 'uncertain';
/**
 * Risk tolerance settings
 */
type RiskTolerance = 'conservative' | 'moderate' | 'aggressive';
/**
 * Retry strategies for failed tasks
 */
type RetryStrategy = 'none' | 'incremental' | 'full_reset' | 'decompose';
/**
 * Risk factor identified in context
 */
interface IRiskFactor {
    /** Description of the risk */
    factor: string;
    /** Severity score (0-1) */
    severity: number;
    /** Suggested mitigation */
    mitigation?: string;
    /** Category of risk */
    category?: 'complexity' | 'dependency' | 'ambiguity' | 'scope' | 'technical';
}
/**
 * Success pattern matched from historical data
 */
interface ISuccessPattern {
    /** Pattern identifier */
    pattern_id: string;
    /** Pattern description */
    description: string;
    /** Match confidence (0-1) */
    match_confidence: number;
    /** Historical success rate for this pattern */
    success_rate: number;
}
/**
 * Confidence assessment for a task
 */
interface IConfidenceAssessment {
    /** Predicted probability of task completion (0-1) */
    task_completion_probability: number;
    /** Confidence level category */
    confidence_level: ConfidenceLevel;
    /** Confidence score (0-100) for SHIP Score calculation */
    confidence_score: number;
    /** Identified risk factors */
    risk_factors: IRiskFactor[];
    /** Matched success patterns */
    success_patterns: ISuccessPattern[];
    /** Historical success rate for similar tasks */
    historical_success_rate: number;
    /** Recommended retry strategy if task fails */
    recommended_retry_strategy: RetryStrategy;
    /** Number of similar tasks in training data */
    similar_tasks_count: number;
}
/**
 * Confidence request parameters
 */
interface IConfidenceRequest {
    /** Enable confidence scoring */
    enable_confidence_scoring: boolean;
    /** Historical context for pattern matching */
    historical_context?: {
        /** IDs of similar past tasks */
        similar_task_ids?: string[];
        /** User's successful patterns */
        user_success_patterns?: string[];
        /** Recent failure patterns to avoid */
        failure_patterns?: string[];
    };
    /** Risk tolerance level */
    risk_tolerance?: RiskTolerance;
    /** Minimum acceptable confidence (0-1) */
    minimum_confidence?: number;
}
/**
 * File focus specification
 */
interface IFileFocus {
    /** File path */
    file: string;
    /** Line range (e.g., "45-80") */
    lines?: string;
    /** Reason for focus priority */
    reason?: string;
    /** Attention weight (0-1) */
    attention_weight?: number;
    /** Semantic role in the task */
    semantic_role?: 'primary' | 'dependency' | 'reference' | 'context';
}
/**
 * Temporal context for focus management
 */
interface ITemporalContext {
    /** Git commit range (e.g., "HEAD~3..HEAD") */
    git_range?: string;
    /** Weight given to recent changes (0-1) */
    recency_weight?: number;
    /** Time window in milliseconds */
    time_window_ms?: number;
    /** Include only modified files */
    modified_only?: boolean;
}
/**
 * Semantic coverage analysis
 */
interface ISemanticCoverage {
    /** Semantic anchors that were found in context */
    anchors_found: string[];
    /** Semantic anchors that were requested but missing */
    anchors_missing: string[];
    /** Coverage percentage (0-100) */
    coverage_percentage: number;
}
/**
 * Focus directives for context selection
 */
interface IFocusDirectives {
    /** Ordered priority of files/locations to focus on */
    focus_priority?: IFileFocus[];
    /** Semantic concepts the AI should anchor on */
    semantic_anchors?: string[];
    /** Temporal weighting of context */
    temporal_context?: ITemporalContext;
    /** Signals to deprioritize or ignore */
    ignore_signals?: string[];
    /** Maximum files to include */
    max_files?: number;
    /** Depth of dependency traversal */
    dependency_depth?: number;
}
/**
 * Focus assessment in response
 */
interface IFocusAssessment {
    /** Overall focus quality score (0-100) */
    focus_score: number;
    /** Primary context locations with weights */
    primary_context: IFileFocus[];
    /** Semantic coverage analysis */
    semantic_coverage: ISemanticCoverage;
    /** Distribution of focus across categories */
    focus_distribution: Record<string, number>;
    /** Number of distracting elements filtered out */
    distractions_filtered: number;
    /** Focus efficiency (relevant / total context) */
    focus_efficiency: number;
}
/**
 * File information with metadata
 */
interface IFileInfo {
    /** File path relative to project root */
    path: string;
    /** File content */
    content: string;
    /** Programming language */
    language: Language;
    /** Size in bytes */
    size_bytes: number;
    /** Relevance score (0-1) - only in responses */
    relevance_score?: number;
    /** Token count - only in responses */
    tokens?: number;
    /** Last modified timestamp */
    last_modified?: string;
    /** Git status (modified, added, deleted) */
    git_status?: 'modified' | 'added' | 'deleted' | 'unchanged';
}
/**
 * Context to be optimized
 */
interface IContext {
    /** Files included in the context */
    files: IFileInfo[];
    /** User prompt or query */
    prompt: string;
    /** Project root path */
    project_root?: string;
    /** Additional metadata */
    metadata?: Record<string, unknown>;
}
/**
 * Context optimization constraints
 */
interface IContextConstraints {
    /** Maximum tokens allowed */
    max_tokens?: number;
    /** Target AI model */
    target_model?: AIModel;
    /** Minimum relevance score to include (0-1) */
    min_relevance_score?: number;
    /** Exclude test files */
    exclude_tests?: boolean;
    /** Exclude configuration files */
    exclude_config?: boolean;
    /** Preserve specific file patterns */
    preserve_patterns?: string[];
}
/**
 * Optimized context result
 */
interface IOptimizedContext {
    /** Optimized files with relevance scores */
    files: IFileInfo[];
    /** Total tokens in optimized context */
    total_tokens: number;
    /** Number of files excluded */
    excluded_files_count: number;
    /** Context coverage score (0-100) */
    context_coverage: number;
}
/**
 * Context assessment in response
 */
interface IContextAssessment {
    /** Context quality score (0-100) */
    context_score: number;
    /** Original token count */
    original_tokens: number;
    /** Optimized token count */
    optimized_tokens: number;
    /** Token reduction percentage */
    reduction_percentage: number;
    /** Relevance distribution */
    relevance_distribution: {
        high: number;
        medium: number;
        low: number;
    };
}
/**
 * Efficiency metrics
 */
interface IEfficiencyMetrics {
    /** Efficiency score (0-100) */
    efficiency_score: number;
    /** Tokens saved */
    tokens_saved: number;
    /** Percentage saved (0-100) */
    percentage_saved: number;
    /** Estimated cost saved (USD) */
    cost_saved_usd: number;
    /** Estimated CO2 saved (grams) */
    co2_saved_grams: number;
    /** Processing time in milliseconds */
    processing_time_ms: number;
    /** Requests per second capacity */
    throughput_rps?: number;
}
/**
 * SHIP Score breakdown
 */
interface IShipScore {
    /** Overall SHIP Score (0-100) */
    score: number;
    /** Score grade */
    grade: 'A+' | 'A' | 'B' | 'C' | 'D' | 'F';
    /** Confidence component (0-100) × 0.40 */
    confidence_component: number;
    /** Focus component (0-100) × 0.30 */
    focus_component: number;
    /** Context component (0-100) × 0.20 */
    context_component: number;
    /** Efficiency component (0-100) × 0.10 */
    efficiency_component: number;
    /** Individual layer scores */
    layer_scores: {
        confidence: number;
        focus: number;
        context: number;
        efficiency: number;
    };
    /** Percentile rank (if available) */
    percentile?: number;
}
/**
 * SHIP Score grade thresholds
 */
declare const SHIP_GRADE_THRESHOLDS: {
    readonly 'A+': 95;
    readonly A: 85;
    readonly B: 70;
    readonly C: 50;
    readonly D: 30;
    readonly F: 0;
};
/**
 * Calculate SHIP Score grade from numeric score
 */
declare function getShipGrade(score: number): IShipScore['grade'];
/**
 * Calculate SHIP Score from layer scores
 */
declare function calculateShipScore(confidence: number, focus: number, context: number, efficiency: number): IShipScore;
/**
 * Base message structure
 */
interface IBaseMessage {
    /** SHIP Protocol version */
    ship_version: ShipVersion;
    /** Message type */
    message_type: ShipMessageType;
    /** Unique message identifier (UUID v4) */
    message_id: string;
    /** ISO 8601 timestamp */
    timestamp: string;
}
/**
 * SHIP Request message
 */
interface IShipRequest extends IBaseMessage {
    message_type: 'ShipRequest';
    /** Context to analyze/optimize */
    context: IContext;
    /** Confidence configuration */
    confidence_request?: IConfidenceRequest;
    /** Focus directives */
    focus_directives?: IFocusDirectives;
    /** Context constraints */
    context_constraints?: IContextConstraints;
    /** Client metadata */
    client_info?: {
        /** Client name */
        name: string;
        /** Client version */
        version: string;
        /** Platform */
        platform?: string;
    };
}
/**
 * SHIP Response message
 */
interface IShipResponse extends IBaseMessage {
    message_type: 'ShipResponse';
    /** Request ID this response is for */
    request_id: string;
    /** SHIP Score */
    ship_score: IShipScore;
    /** Confidence assessment */
    confidence: IConfidenceAssessment;
    /** Focus assessment */
    focus: IFocusAssessment;
    /** Context assessment */
    context: IContextAssessment;
    /** Efficiency metrics */
    efficiency: IEfficiencyMetrics;
    /** Optimized context */
    optimized_context: IOptimizedContext;
    /** Recommendations for improvement */
    recommendations?: IRecommendation[];
}
/**
 * Recommendation for improving SHIP Score
 */
interface IRecommendation {
    /** Recommendation type */
    type: 'confidence' | 'focus' | 'context' | 'efficiency';
    /** Priority (1-5, 1 is highest) */
    priority: number;
    /** Recommendation message */
    message: string;
    /** Expected score improvement */
    expected_improvement: number;
    /** Action to take */
    action?: string;
}
/**
 * Task outcome for feedback
 */
interface ITaskOutcome {
    /** Whether the task was completed successfully */
    task_completed: boolean;
    /** Whether it succeeded on first attempt */
    first_attempt_success: boolean;
    /** Total attempts made */
    total_attempts: number;
    /** Time to completion in milliseconds */
    time_to_completion_ms?: number;
    /** User satisfaction score (1-5) */
    user_satisfaction?: 1 | 2 | 3 | 4 | 5;
    /** Free-form feedback */
    feedback_text?: string;
}
/**
 * Focus quality feedback
 */
interface IFocusFeedback {
    /** Whether focus guidance was helpful */
    focus_helpful: boolean;
    /** Context that was needed but missing */
    missed_context?: string[];
    /** Context that was provided but unnecessary */
    unnecessary_context?: string[];
    /** Percentage of provided context actually used (0-1) */
    utilization_rate: number;
}
/**
 * Error pattern observation
 */
interface IErrorPattern {
    /** Type of error encountered */
    error_type: string;
    /** Error message or code */
    error_code?: string;
    /** How many times this error occurred */
    frequency: number;
    /** Whether it was auto-resolved */
    auto_resolved: boolean;
    /** Resolution method if resolved */
    resolution_method?: string;
}
/**
 * Learning signals for pattern improvement
 */
interface ILearningSignals {
    /** Patterns to reinforce */
    pattern_reinforcement?: string[];
    /** Patterns that need correction */
    pattern_correction?: string[];
    /** New patterns discovered */
    new_patterns?: string[];
}
/**
 * SHIP Feedback message
 */
interface IShipFeedback extends IBaseMessage {
    message_type: 'ShipFeedback';
    /** Request ID this feedback is for */
    request_id: string;
    /** Task outcome */
    outcome: ITaskOutcome;
    /** Actual SHIP Score achieved (post-hoc) */
    actual_ship_score?: number;
    /** Focus feedback */
    focus_feedback?: IFocusFeedback;
    /** Error patterns observed */
    error_patterns?: IErrorPattern[];
    /** Learning signals */
    learning_signals?: ILearningSignals;
}
/**
 * Error codes
 */
type ShipErrorCode = 'INVALID_REQUEST' | 'INVALID_VERSION' | 'TIMEOUT' | 'QUOTA_EXCEEDED' | 'RATE_LIMITED' | 'CONTEXT_TOO_LARGE' | 'INTERNAL_ERROR' | 'SERVICE_UNAVAILABLE';
/**
 * Error information
 */
interface IShipErrorInfo {
    /** Error code */
    code: ShipErrorCode;
    /** Human-readable error message */
    message: string;
    /** Additional error details */
    details?: Record<string, unknown>;
    /** Retry information */
    retry?: {
        /** Whether retry is recommended */
        should_retry: boolean;
        /** Suggested delay before retry (ms) */
        retry_after_ms?: number;
    };
}
/**
 * SHIP Error message
 */
interface IShipError extends IBaseMessage {
    message_type: 'ShipError';
    /** Request ID that caused the error */
    request_id: string;
    /** Error information */
    error: IShipErrorInfo;
}
/**
 * Union type for all SHIP messages
 */
type ShipMessage = IShipRequest | IShipResponse | IShipFeedback | IShipError;
/**
 * SHIP Badge types
 */
type ShipBadgeType = 'ship-score' | 'confidence' | 'focus' | 'reliability-rate' | 'certified';
/**
 * Badge style variants
 */
type BadgeStyle = 'flat' | 'flat-square' | 'plastic' | 'for-the-badge';
/**
 * Badge configuration
 */
interface IBadgeConfig {
    /** Badge type */
    type: ShipBadgeType;
    /** Current score/value */
    value: number;
    /** Badge style */
    style?: BadgeStyle;
    /** Custom label */
    label?: string;
    /** Custom color */
    color?: string;
}
/**
 * Generate badge URL
 */
declare function generateBadgeUrl(config: IBadgeConfig): string;
/**
 * Generate badge markdown
 */
declare function generateBadgeMarkdown(config: IBadgeConfig): string;
/**
 * Certification levels
 */
type CertificationLevel = 'bronze' | 'silver' | 'gold' | 'platinum';
/**
 * Certification status
 */
interface ICertification {
    /** Certification level achieved */
    level: CertificationLevel;
    /** SHIP Score at certification */
    ship_score: number;
    /** Certification date */
    certified_at: string;
    /** Expiration date (optional) */
    expires_at?: string;
    /** Certificate ID */
    certificate_id: string;
    /** Project/repository name */
    project_name: string;
    /** Verification URL */
    verification_url: string;
}
/**
 * Get certification level from SHIP Score
 */
declare function getCertificationLevel(score: number): CertificationLevel | null;
/**
 * SHIP Protocol conformance levels
 */
type ConformanceLevel = 'basic' | 'standard' | 'full';
/**
 * Conformance requirements
 */
interface IConformanceRequirements {
    level: ConformanceLevel;
    requirements: {
        /** Required message types */
        message_types: ShipMessageType[];
        /** Required SHIP Score components */
        score_components: ('confidence' | 'focus' | 'context' | 'efficiency')[];
        /** Required features */
        features: string[];
    };
}
/**
 * Conformance level requirements
 */
declare const CONFORMANCE_REQUIREMENTS: Record<ConformanceLevel, IConformanceRequirements>;
declare const _default: {
    calculateShipScore: typeof calculateShipScore;
    getShipGrade: typeof getShipGrade;
    getCertificationLevel: typeof getCertificationLevel;
    generateBadgeUrl: typeof generateBadgeUrl;
    generateBadgeMarkdown: typeof generateBadgeMarkdown;
    SHIP_GRADE_THRESHOLDS: {
        readonly 'A+': 95;
        readonly A: 85;
        readonly B: 70;
        readonly C: 50;
        readonly D: 30;
        readonly F: 0;
    };
    CONFORMANCE_REQUIREMENTS: Record<ConformanceLevel, IConformanceRequirements>;
};

export { type AIModel, type BadgeStyle, CONFORMANCE_REQUIREMENTS, type CertificationLevel, type ConfidenceLevel, type ConformanceLevel, type IBadgeConfig, type IBaseMessage, type ICertification, type IConfidenceAssessment, type IConfidenceRequest, type IConformanceRequirements, type IContext, type IContextAssessment, type IContextConstraints, type IEfficiencyMetrics, type IErrorPattern, type IFileFocus, type IFileInfo, type IFocusAssessment, type IFocusDirectives, type IFocusFeedback, type ILearningSignals, type IOptimizedContext, type IRecommendation, type IRiskFactor, type ISemanticCoverage, type IShipError, type IShipErrorInfo, type IShipFeedback, type IShipRequest, type IShipResponse, type IShipScore, type ISuccessPattern, type ITaskOutcome, type ITemporalContext, type Language, type RetryStrategy, type RiskTolerance, SHIP_GRADE_THRESHOLDS, type ShipBadgeType, type ShipErrorCode, type ShipMessage, type ShipMessageType, type ShipVersion, calculateShipScore, _default as default, generateBadgeMarkdown, generateBadgeUrl, getCertificationLevel, getShipGrade };