/**
 * BlackboardValidator + QualityGateAgent
 *
 * Two-layer content validation for the SharedBlackboard:
 *
 * Layer 1 -- BlackboardValidator (rule-based, deterministic, fast)
 *   Validates structure, completeness, and basic quality of tasks,
 *   results, and code before they enter the blackboard.
 *
 * Layer 2 -- QualityGateAgent (AI-assisted, optional)
 *   A special review agent that can inspect pending entries,
 *   run deeper analysis, detect hallucinations, and approve/reject.
 *
 * Together they prevent bad code, incomplete results, and hallucinated
 * data from poisoning the shared state that other agents depend on.
 *
 * @module BlackboardValidator
 */
export interface ValidationResult {
    /** Did the entry pass validation? */
    passed: boolean;
    /** Quality score 0-1 (1 = perfect) */
    score: number;
    /** Specific issues found */
    issues: ValidationIssue[];
    /** Which rules were checked */
    rulesApplied: string[];
    /** Timestamp of validation */
    timestamp: string;
    /** If failed, can it be retried after fixes? */
    recoverable: boolean;
}
export interface ValidationIssue {
    /** Rule that flagged the issue */
    rule: string;
    /** Severity: error blocks entry, warning is logged, info is advisory */
    severity: 'error' | 'warning' | 'info';
    /** Human-readable description */
    message: string;
    /** Which field had the problem */
    field?: string;
    /** Suggested fix */
    suggestion?: string;
}
/** Configuration for validation rules -- all configurable per domain */
export interface ValidationConfig {
    /** Minimum instruction length for tasks (chars) */
    minInstructionLength: number;
    /** Maximum instruction length for tasks (chars) */
    maxInstructionLength: number;
    /** Require tasks to have constraints defined */
    requireConstraints: boolean;
    /** Require tasks to have expectedOutput defined */
    requireExpectedOutput: boolean;
    /** Minimum result data fields for a result to be considered complete */
    minResultFields: number;
    /** Maximum allowed error rate in a batch of results */
    maxErrorRate: number;
    /** Code quality: minimum lines for a code entry to be non-trivial */
    minCodeLines: number;
    /** Code quality: maximum allowed ratio of comments to code */
    maxCommentRatio: number;
    /** Detect common hallucination patterns */
    detectHallucinations: boolean;
    /** Reject entries with placeholder/dummy data patterns */
    rejectPlaceholders: boolean;
    /** Custom validation rules -- user-extensible */
    customRules: CustomValidationRule[];
}
export interface CustomValidationRule {
    /** Unique rule name */
    name: string;
    /** Human-readable description of the rule */
    description?: string;
    /** Which entry types this rule applies to ('task', 'result', 'code', 'any') */
    appliesTo: string[];
    /** The validation function -- return null if valid, or an issue */
    validate: (key: string, value: unknown, metadata?: Record<string, unknown>) => ValidationIssue | null;
}
/** Quality gate decision */
export type GateDecision = 'approve' | 'reject' | 'quarantine' | 'needs_review';
export interface QualityGateResult {
    decision: GateDecision;
    validation: ValidationResult;
    /** If quarantined, it's stored here instead of the main blackboard */
    quarantineKey?: string;
    /** Review notes from the quality gate */
    reviewNotes: string[];
    /** Reviewer agent ID (if AI review was used) */
    reviewedBy?: string;
}
/** Callback type for AI review delegation */
export type AIReviewCallback = (key: string, value: unknown, entryType: string, context: {
    sourceAgent: string;
    validation: ValidationResult;
}) => Promise<{
    approved: boolean;
    confidence: number;
    feedback: string;
    suggestedFixes?: string[];
}>;
/**
 * Subset of JSON Schema Draft-07 supported by the built-in validator.
 *
 * Supports: type, required, properties, items, enum, const,
 * minLength/maxLength, minimum/maximum, pattern, minItems/maxItems,
 * additionalProperties, oneOf/anyOf/allOf.
 */
export interface JsonSchema {
    type?: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null' | string[];
    properties?: Record<string, JsonSchema>;
    required?: string[];
    items?: JsonSchema;
    enum?: unknown[];
    const?: unknown;
    minLength?: number;
    maxLength?: number;
    minimum?: number;
    maximum?: number;
    pattern?: string;
    minItems?: number;
    maxItems?: number;
    additionalProperties?: boolean | JsonSchema;
    oneOf?: JsonSchema[];
    anyOf?: JsonSchema[];
    allOf?: JsonSchema[];
    description?: string;
}
/**
 * Validate a value against a {@link JsonSchema}.
 * Returns an array of human-readable error strings (empty = valid).
 */
export declare function validateJsonSchema(value: unknown, schema: JsonSchema, path?: string): string[];
export declare class BlackboardValidator {
    private config;
    /** Schema registry: key-prefix → JSON Schema. Checked in validate(). */
    private schemas;
    constructor(config?: Partial<ValidationConfig>);
    /**
     * Register a JSON Schema for a blackboard key prefix.
     * Any value written to a key matching the prefix will be validated against the schema.
     *
     * @param keyPrefix Key prefix (e.g. `'result:'`, `'task:code-review'`)
     * @param schema    A {@link JsonSchema} definition
     */
    registerSchema(keyPrefix: string, schema: JsonSchema): void;
    /**
     * Remove a previously registered schema.
     */
    unregisterSchema(keyPrefix: string): boolean;
    /**
     * List all registered schema prefixes.
     */
    getRegisteredSchemas(): string[];
    /**
     * Validate any entry by auto-detecting its type from the key prefix.
     * Also runs registered JSON Schema validation if a matching prefix exists.
     */
    validate(key: string, value: unknown, metadata?: Record<string, unknown>): ValidationResult;
    /**
     * Validate a task payload before dispatching.
     */
    validateTask(key: string, value: unknown): ValidationResult;
    /**
     * Validate a result/output before caching.
     */
    validateResult(key: string, value: unknown, metadata?: Record<string, unknown>): ValidationResult;
    /**
     * Validate code content before it enters the blackboard.
     */
    validateCode(key: string, value: unknown): ValidationResult;
    /**
     * Validate a generic entry (not task, result, or code).
     */
    validateGeneric(key: string, value: unknown): ValidationResult;
    /**
     * Register a custom validation rule at runtime.
     */
    addRule(rule: CustomValidationRule): void;
    /**
     * Update configuration at runtime.
     */
    updateConfig(patch: Partial<ValidationConfig>): void;
    private detectEntryType;
    private extractCode;
    private checkCodeSyntax;
    private detectHallucinations;
    private applyCustomRules;
    /**
     * Run registered JSON Schema validations for the given key.
     * Matches the longest matching prefix.
     */
    private validateAgainstSchemas;
    private calculateScore;
    private makeResult;
}
export declare class QualityGateAgent {
    private validator;
    private quarantine;
    private reviewCallback?;
    private metrics;
    /** Best (highest quality score) partial result seen across all `gate()` calls so far. */
    private _bestPartialResult;
    /** Quality score threshold: entries below this go to AI review or quarantine */
    private qualityThreshold;
    /** Score below which entries are auto-rejected (no AI review) */
    private autoRejectThreshold;
    /** Whether to invoke AI review for borderline entries */
    private aiReviewEnabled;
    constructor(options?: {
        validationConfig?: Partial<ValidationConfig>;
        qualityThreshold?: number;
        autoRejectThreshold?: number;
        aiReviewCallback?: AIReviewCallback;
    });
    /**
     * Gate an entry -- validate, optionally send for AI review, and decide.
     *
     * Call this before writing to the blackboard. Returns a decision:
     * - 'approve': safe to write
     * - 'reject': do not write, return error to submitting agent
     * - 'quarantine': stored separately for human/senior-agent review
     * - 'needs_review': requires AI review (only if callback is set)
     */
    gate(key: string, value: unknown, sourceAgent: string, metadata?: Record<string, unknown>): Promise<QualityGateResult>;
    /** @internal — core gate logic, called by `gate()` which wraps it for partial-result tracking. */
    private _gateCore;
    /**
     * Get all quarantined entries for manual review.
     */
    getQuarantined(): Array<{
        quarantineId: string;
        key: string;
        value: unknown;
        issues: ValidationIssue[];
        submittedBy: string;
        timestamp: string;
    }>;
    /**
     * Approve a quarantined entry -- returns the value for writing to the blackboard.
     */
    approveQuarantined(quarantineId: string): {
        key: string;
        value: unknown;
    } | null;
    /**
     * Reject and discard a quarantined entry.
     */
    rejectQuarantined(quarantineId: string): boolean;
    /**
     * Get quality gate metrics.
     */
    getMetrics(): Readonly<typeof this.metrics>;
    /**
     * Get the underlying validator for direct access (e.g., adding custom rules).
     */
    getValidator(): BlackboardValidator;
    /**
     * Set or change the AI review callback at runtime.
     */
    setAIReviewCallback(callback: AIReviewCallback): void;
    /**
     * Return the best (highest quality-score) partial result seen across all
     * `gate()` calls since construction or the last `resetBestPartialResult()`.
     *
     * Useful for graceful degradation: when a pipeline exhausts its budget or
     * time before finding a fully-approved result, callers can fall back to the
     * best candidate seen so far rather than returning nothing.
     *
     * @returns The best partial result, or `null` if `gate()` has never been called.
     */
    getBestPartialResult(): {
        key: string;
        value: unknown;
        result: QualityGateResult;
    } | null;
    /**
     * Reset the best partial result tracker (e.g. before starting a new gating session).
     */
    resetBestPartialResult(): void;
    /** @internal — decision rank for tie-breaking in `_updateBestPartial`. */
    private static readonly _DECISION_RANK;
    /** @internal */
    private _updateBestPartial;
    private addToQuarantine;
    private detectEntryType;
}
//# sourceMappingURL=blackboard-validator.d.ts.map