@runhalo/engine 0.5.0 → 0.6.0

package/dist/graduation/graduation-validator.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Sprint 13a Week 2: Graduation Validator
+ *
+ * Stage 3 of the Graduation Pipeline.
+ * Evaluates aggregated FP patterns against graduation criteria.
+ * Patterns that meet all thresholds become candidates for codification
+ * as permanent engine heuristics.
+ *
+ * Graduation criteria (configurable):
+ * - Minimum N dismissals across scans
+ * - Average confidence above threshold
+ * - Zero (or near-zero) false confirmations
+ * - Minimum precision when validated against ground truth
+ * - Appeared in minimum N unique scans
+ */
+import { PatternStats, AggregationResult } from './pattern-aggregator';
+export interface GraduationCriteria {
+    /** Minimum total dismissals required */
+    minDismissals: number;
+    /** Minimum average confidence (1-10) */
+    minAvgConfidence: number;
+    /** Maximum allowed false confirmations (ground truth contradictions) */
+    maxFalseConfirmations: number;
+    /** Minimum precision when validated against ground truth (0-1) */
+    minPrecision: number;
+    /** Minimum unique scans the pattern appeared in */
+    minUniqueScans: number;
+}
+export interface GraduationCandidate {
+    /** The FP pattern being evaluated */
+    pattern: PatternStats;
+    /** Whether this pattern meets all criteria */
+    eligible: boolean;
+    /** Which criteria passed/failed */
+    criteriaResults: {
+        criterion: string;
+        passed: boolean;
+        actual: number;
+        required: number;
+    }[];
+    /** Recommended heuristic type for codification */
+    recommendedHeuristic: 'file_skip' | 'rule_suppress' | 'severity_downgrade' | 'context_check';
+    /** Generated heuristic description */
+    heuristicDescription: string;
+    /** Priority score (higher = graduate first) */
+    priorityScore: number;
+}
+export interface GraduationReport {
+    /** When validation was run */
+    validatedAt: string;
+    /** Criteria used */
+    criteria: GraduationCriteria;
+    /** All candidates evaluated */
+    candidates: GraduationCandidate[];
+    /** Eligible candidates only */
+    eligible: GraduationCandidate[];
+    /** Nearly eligible (missing 1 criterion) */
+    nearMiss: GraduationCandidate[];
+    /** Summary stats */
+    summary: {
+        totalPatterns: number;
+        eligibleCount: number;
+        nearMissCount: number;
+        rejectedCount: number;
+    };
+}
+export declare const DEFAULT_GRADUATION_CRITERIA: GraduationCriteria;
+export declare const MVP_GRADUATION_CRITERIA: GraduationCriteria;
+/**
+ * Evaluate FP patterns against graduation criteria.
+ */
+export declare function validateGraduation(aggregation: AggregationResult, criteria?: GraduationCriteria, groundTruthPrecision?: Map<string, number>): GraduationReport;
+export declare function formatGraduationReport(report: GraduationReport): string;

package/dist/graduation/graduation-validator.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Sprint 13a Week 2: Graduation Validator
+ *
+ * Stage 3 of the Graduation Pipeline.
+ * Evaluates aggregated FP patterns against graduation criteria.
+ * Patterns that meet all thresholds become candidates for codification
+ * as permanent engine heuristics.
+ *
+ * Graduation criteria (configurable):
+ * - Minimum N dismissals across scans
+ * - Average confidence above threshold
+ * - Zero (or near-zero) false confirmations
+ * - Minimum precision when validated against ground truth
+ * - Appeared in minimum N unique scans
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MVP_GRADUATION_CRITERIA = exports.DEFAULT_GRADUATION_CRITERIA = void 0;
+exports.validateGraduation = validateGraduation;
+exports.formatGraduationReport = formatGraduationReport;
+// ─── Default Criteria ───────────────────────────────────────────────────────
+exports.DEFAULT_GRADUATION_CRITERIA = {
+    minDismissals: 15,
+    minAvgConfidence: 7.0,
+    maxFalseConfirmations: 0,
+    minPrecision: 0.95,
+    minUniqueScans: 2,
+};
+// Relaxed criteria for MVP (smaller dataset)
+exports.MVP_GRADUATION_CRITERIA = {
+    minDismissals: 5,
+    minAvgConfidence: 6.0,
+    maxFalseConfirmations: 1,
+    minPrecision: 0.90,
+    minUniqueScans: 1,
+};
+// ─── Validator ──────────────────────────────────────────────────────────────
+/**
+ * Evaluate FP patterns against graduation criteria.
+ */
+function validateGraduation(aggregation, criteria = exports.DEFAULT_GRADUATION_CRITERIA, groundTruthPrecision // patternId → precision from ground truth
+) {
+    const candidates = [];
+    for (const pattern of aggregation.patterns) {
+        const precision = groundTruthPrecision?.get(pattern.fpPatternId) ?? 1.0;
+        const criteriaResults = [
+            {
+                criterion: 'minDismissals',
+                passed: pattern.totalDismissals >= criteria.minDismissals,
+                actual: pattern.totalDismissals,
+                required: criteria.minDismissals,
+            },
+            {
+                criterion: 'minAvgConfidence',
+                passed: pattern.avgConfidence >= criteria.minAvgConfidence,
+                actual: pattern.avgConfidence,
+                required: criteria.minAvgConfidence,
+            },
+            {
+                criterion: 'maxFalseConfirmations',
+                passed: pattern.falseConfirmations <= criteria.maxFalseConfirmations,
+                actual: pattern.falseConfirmations,
+                required: criteria.maxFalseConfirmations,
+            },
+            {
+                criterion: 'minPrecision',
+                passed: precision >= criteria.minPrecision,
+                actual: Math.round(precision * 100) / 100,
+                required: criteria.minPrecision,
+            },
+            {
+                criterion: 'minUniqueScans',
+                passed: pattern.uniqueScans >= criteria.minUniqueScans,
+                actual: pattern.uniqueScans,
+                required: criteria.minUniqueScans,
+            },
+        ];
+        const eligible = criteriaResults.every(r => r.passed);
+        const failedCount = criteriaResults.filter(r => !r.passed).length;
+        // Determine recommended heuristic type
+        const recommendedHeuristic = inferHeuristicType(pattern);
+        const heuristicDescription = generateHeuristicDescription(pattern, recommendedHeuristic);
+        // Priority score: higher = more confident graduation candidate
+        const priorityScore = calculatePriorityScore(pattern, precision);
+        candidates.push({
+            pattern,
+            eligible,
+            criteriaResults,
+            recommendedHeuristic,
+            heuristicDescription,
+            priorityScore,
+        });
+    }
+    // Sort by priority score
+    candidates.sort((a, b) => b.priorityScore - a.priorityScore);
+    const eligible = candidates.filter(c => c.eligible);
+    const nearMiss = candidates.filter(c => {
+        const failed = c.criteriaResults.filter(r => !r.passed).length;
+        return !c.eligible && failed === 1;
+    });
+    return {
+        validatedAt: new Date().toISOString(),
+        criteria,
+        candidates,
+        eligible,
+        nearMiss,
+        summary: {
+            totalPatterns: candidates.length,
+            eligibleCount: eligible.length,
+            nearMissCount: nearMiss.length,
+            rejectedCount: candidates.length - eligible.length - nearMiss.length,
+        },
+    };
+}
+// ─── Heuristic Inference ────────────────────────────────────────────────────
+function inferHeuristicType(pattern) {
+    const patternId = pattern.fpPatternId.toLowerCase();
+    // File-level skip patterns
+    if (patternId.includes('vendor') ||
+        patternId.includes('test') ||
+        patternId.includes('doc-generator') ||
+        patternId.includes('migration') ||
+        patternId.includes('fixture') ||
+        patternId.includes('mock') ||
+        patternId.includes('build-output') ||
+        patternId.includes('type-def')) {
+        return 'file_skip';
+    }
+    // Rule suppression patterns (specific rule on specific file types)
+    if (patternId.includes('admin') ||
+        patternId.includes('consent') ||
+        patternId.includes('playback') ||
+        patternId.includes('deletion')) {
+        return 'rule_suppress';
+    }
+    // Severity downgrade patterns
+    if (patternId.includes('framework') ||
+        patternId.includes('sanitized') ||
+        patternId.includes('error-monitoring')) {
+        return 'severity_downgrade';
+    }
+    // Context check (needs surrounding code analysis)
+    return 'context_check';
+}
+function generateHeuristicDescription(pattern, type) {
+    const rules = pattern.affectedRules.join(', ');
+    switch (type) {
+        case 'file_skip':
+            return `Add path pattern to classifyFile() → shouldSkip=true. Affects: ${rules}. Pattern: ${pattern.fpPatternId}`;
+        case 'rule_suppress':
+            return `Add to rule-specific suppression list (similar to TEST_FP_RULES). Suppress ${rules} when pattern "${pattern.fpPatternId}" matches.`;
+        case 'severity_downgrade':
+            return `Add severity downgrade logic for ${rules} when "${pattern.fpPatternId}" context detected. Downgrade from 'warning' to 'info'.`;
+        case 'context_check':
+            return `Add code context check in scan loop: when "${pattern.fpPatternId}" signals detected in surrounding code, suppress ${rules}.`;
+    }
+}
+function calculatePriorityScore(pattern, precision) {
+    // Weighted score:
+    // - 40% based on total dismissals (capped at 50)
+    // - 30% based on average confidence
+    // - 20% based on precision
+    // - 10% based on unique scans
+    const dismissalScore = Math.min(pattern.totalDismissals / 50, 1) * 40;
+    const confidenceScore = (pattern.avgConfidence / 10) * 30;
+    const precisionScore = precision * 20;
+    const scanScore = Math.min(pattern.uniqueScans / 5, 1) * 10;
+    return Math.round((dismissalScore + confidenceScore + precisionScore + scanScore) * 10) / 10;
+}
+// ─── Report Formatting ──────────────────────────────────────────────────────
+function formatGraduationReport(report) {
+    const lines = [
+        '═══ Graduation Pipeline — Validation Report ═══',
+        '',
+        `Validated at: ${report.validatedAt}`,
+        `Criteria: minDismissals=${report.criteria.minDismissals}, minConf=${report.criteria.minAvgConfidence}, maxFalseConf=${report.criteria.maxFalseConfirmations}, minPrecision=${report.criteria.minPrecision}, minScans=${report.criteria.minUniqueScans}`,
+        '',
+        `Total patterns: ${report.summary.totalPatterns}`,
+        `Eligible for graduation: ${report.summary.eligibleCount}`,
+        `Near miss (1 criterion short): ${report.summary.nearMissCount}`,
+        `Rejected: ${report.summary.rejectedCount}`,
+    ];
+    if (report.eligible.length > 0) {
+        lines.push('');
+        lines.push('── ELIGIBLE FOR GRADUATION ──');
+        for (const c of report.eligible) {
+            lines.push(`  [${c.priorityScore}] ${c.pattern.fpPatternId}`);
+            lines.push(`    Dismissals: ${c.pattern.totalDismissals}, Avg Conf: ${c.pattern.avgConfidence}, Scans: ${c.pattern.uniqueScans}`);
+            lines.push(`    Rules: ${c.pattern.affectedRules.join(', ')}`);
+            lines.push(`    Action: ${c.heuristicDescription}`);
+        }
+    }
+    if (report.nearMiss.length > 0) {
+        lines.push('');
+        lines.push('── NEAR MISS (1 criterion short) ──');
+        for (const c of report.nearMiss) {
+            const failed = c.criteriaResults.find(r => !r.passed);
+            lines.push(`  ${c.pattern.fpPatternId}`);
+            lines.push(`    Missing: ${failed?.criterion} (actual: ${failed?.actual}, required: ${failed?.required})`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=graduation-validator.js.map

package/dist/graduation/graduation-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graduation-validator.js","sourceRoot":"","sources":["../../src/graduation/graduation-validator.ts"],"names":[],"mappings":"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"}

package/dist/graduation/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Graduation Pipeline — Sprint 13a Week 2
+ *
+ * Four-stage pipeline that transforms AI Review Board FP verdicts
+ * into permanent engine heuristics:
+ *
+ * Stage 1: COLLECT — Log each verdict to structured JSONL
+ * Stage 2: AGGREGATE — Compute per-pattern statistics across scans
+ * Stage 3: VALIDATE — Check graduation criteria (dismissals, confidence, precision)
+ * Stage 4: CODIFY — Generate engine heuristic code for approved patterns
+ *
+ * Usage:
+ *   import { GraduationPipeline } from './graduation';
+ *   const pipeline = new GraduationPipeline({ logDir: './verdict-logs' });
+ *   pipeline.logVerdict(verdict);           // Stage 1
+ *   const stats = pipeline.aggregate();     // Stage 2
+ *   const candidates = pipeline.validate(); // Stage 3
+ *   const code = pipeline.codify();         // Stage 4
+ */
+export { FPVerdictLogger, VerdictLogEntry } from './fp-verdict-logger';
+export { aggregatePatterns, aggregateFromDirectory, formatAggregationReport, PatternStats, AggregationResult, } from './pattern-aggregator';
+export { validateGraduation, formatGraduationReport, DEFAULT_GRADUATION_CRITERIA, MVP_GRADUATION_CRITERIA, GraduationCriteria, GraduationCandidate, GraduationReport, } from './graduation-validator';
+export { generateCode, generateAllCode, formatCodegenReport, CodegenResult, } from './graduation-codifier';
+import { FPVerdictLogger, VerdictLogEntry } from './fp-verdict-logger';
+import { AggregationResult } from './pattern-aggregator';
+import { GraduationCriteria, GraduationReport } from './graduation-validator';
+import { CodegenResult } from './graduation-codifier';
+export interface GraduationPipelineConfig {
+    /** Directory for verdict JSONL logs */
+    logDir: string;
+    /** Known FP pattern IDs from the static library */
+    knownPatternIds?: Set<string>;
+    /** Graduation criteria (defaults to MVP criteria) */
+    criteria?: GraduationCriteria;
+    /** Ground truth precision per pattern (from regression suite) */
+    groundTruthPrecision?: Map<string, number>;
+}
+export declare class GraduationPipeline {
+    private config;
+    private logger;
+    constructor(config: GraduationPipelineConfig);
+    /**
+     * Initialize logger for a new scan.
+     */
+    startScan(scanId: string, promptVersion?: string): FPVerdictLogger;
+    /**
+     * Log a single verdict (convenience method).
+     */
+    logVerdict(entry: Omit<VerdictLogEntry, 'timestamp' | 'scanId' | 'promptVersion'>): void;
+    /**
+     * Aggregate all verdict logs in the log directory.
+     */
+    aggregate(): AggregationResult;
+    /**
+     * Validate aggregated patterns against graduation criteria.
+     */
+    validate(aggregation?: AggregationResult): GraduationReport;
+    /**
+     * Generate code for all eligible graduation candidates.
+     */
+    codify(report?: GraduationReport): CodegenResult[];
+    /**
+     * Run the full pipeline (stages 2-4) on existing log data.
+     * Stage 1 (logging) happens during scans, not here.
+     */
+    runPipeline(): {
+        aggregation: AggregationResult;
+        graduation: GraduationReport;
+        codegen: CodegenResult[];
+    };
+}

package/dist/graduation/index.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Graduation Pipeline — Sprint 13a Week 2
+ *
+ * Four-stage pipeline that transforms AI Review Board FP verdicts
+ * into permanent engine heuristics:
+ *
+ * Stage 1: COLLECT — Log each verdict to structured JSONL
+ * Stage 2: AGGREGATE — Compute per-pattern statistics across scans
+ * Stage 3: VALIDATE — Check graduation criteria (dismissals, confidence, precision)
+ * Stage 4: CODIFY — Generate engine heuristic code for approved patterns
+ *
+ * Usage:
+ *   import { GraduationPipeline } from './graduation';
+ *   const pipeline = new GraduationPipeline({ logDir: './verdict-logs' });
+ *   pipeline.logVerdict(verdict);           // Stage 1
+ *   const stats = pipeline.aggregate();     // Stage 2
+ *   const candidates = pipeline.validate(); // Stage 3
+ *   const code = pipeline.codify();         // Stage 4
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraduationPipeline = exports.formatCodegenReport = exports.generateAllCode = exports.generateCode = exports.MVP_GRADUATION_CRITERIA = exports.DEFAULT_GRADUATION_CRITERIA = exports.formatGraduationReport = exports.validateGraduation = exports.formatAggregationReport = exports.aggregateFromDirectory = exports.aggregatePatterns = exports.FPVerdictLogger = void 0;
+var fp_verdict_logger_1 = require("./fp-verdict-logger");
+Object.defineProperty(exports, "FPVerdictLogger", { enumerable: true, get: function () { return fp_verdict_logger_1.FPVerdictLogger; } });
+var pattern_aggregator_1 = require("./pattern-aggregator");
+Object.defineProperty(exports, "aggregatePatterns", { enumerable: true, get: function () { return pattern_aggregator_1.aggregatePatterns; } });
+Object.defineProperty(exports, "aggregateFromDirectory", { enumerable: true, get: function () { return pattern_aggregator_1.aggregateFromDirectory; } });
+Object.defineProperty(exports, "formatAggregationReport", { enumerable: true, get: function () { return pattern_aggregator_1.formatAggregationReport; } });
+var graduation_validator_1 = require("./graduation-validator");
+Object.defineProperty(exports, "validateGraduation", { enumerable: true, get: function () { return graduation_validator_1.validateGraduation; } });
+Object.defineProperty(exports, "formatGraduationReport", { enumerable: true, get: function () { return graduation_validator_1.formatGraduationReport; } });
+Object.defineProperty(exports, "DEFAULT_GRADUATION_CRITERIA", { enumerable: true, get: function () { return graduation_validator_1.DEFAULT_GRADUATION_CRITERIA; } });
+Object.defineProperty(exports, "MVP_GRADUATION_CRITERIA", { enumerable: true, get: function () { return graduation_validator_1.MVP_GRADUATION_CRITERIA; } });
+var graduation_codifier_1 = require("./graduation-codifier");
+Object.defineProperty(exports, "generateCode", { enumerable: true, get: function () { return graduation_codifier_1.generateCode; } });
+Object.defineProperty(exports, "generateAllCode", { enumerable: true, get: function () { return graduation_codifier_1.generateAllCode; } });
+Object.defineProperty(exports, "formatCodegenReport", { enumerable: true, get: function () { return graduation_codifier_1.formatCodegenReport; } });
+const fp_verdict_logger_2 = require("./fp-verdict-logger");
+const pattern_aggregator_2 = require("./pattern-aggregator");
+const graduation_validator_2 = require("./graduation-validator");
+const graduation_codifier_2 = require("./graduation-codifier");
+class GraduationPipeline {
+    constructor(config) {
+        this.logger = null;
+        this.config = config;
+    }
+    // ─── Stage 1: Collect ──────────────────────────────────────────────
+    /**
+     * Initialize logger for a new scan.
+     */
+    startScan(scanId, promptVersion) {
+        this.logger = new fp_verdict_logger_2.FPVerdictLogger({
+            logDir: this.config.logDir,
+            scanId,
+            promptVersion,
+        });
+        return this.logger;
+    }
+    /**
+     * Log a single verdict (convenience method).
+     */
+    logVerdict(entry) {
+        if (!this.logger) {
+            throw new Error('Call startScan() before logging verdicts');
+        }
+        this.logger.log(entry);
+    }
+    // ─── Stage 2: Aggregate ────────────────────────────────────────────
+    /**
+     * Aggregate all verdict logs in the log directory.
+     */
+    aggregate() {
+        const entries = fp_verdict_logger_2.FPVerdictLogger.readAllLogs(this.config.logDir);
+        return (0, pattern_aggregator_2.aggregatePatterns)(entries, this.config.knownPatternIds);
+    }
+    // ─── Stage 3: Validate ─────────────────────────────────────────────
+    /**
+     * Validate aggregated patterns against graduation criteria.
+     */
+    validate(aggregation) {
+        const agg = aggregation || this.aggregate();
+        return (0, graduation_validator_2.validateGraduation)(agg, this.config.criteria || graduation_validator_2.MVP_GRADUATION_CRITERIA, this.config.groundTruthPrecision);
+    }
+    // ─── Stage 4: Codify ───────────────────────────────────────────────
+    /**
+     * Generate code for all eligible graduation candidates.
+     */
+    codify(report) {
+        const rep = report || this.validate();
+        return (0, graduation_codifier_2.generateAllCode)(rep.eligible);
+    }
+    // ─── Full Pipeline Run ─────────────────────────────────────────────
+    /**
+     * Run the full pipeline (stages 2-4) on existing log data.
+     * Stage 1 (logging) happens during scans, not here.
+     */
+    runPipeline() {
+        const aggregation = this.aggregate();
+        const graduation = this.validate(aggregation);
+        const codegen = this.codify(graduation);
+        return { aggregation, graduation, codegen };
+    }
+}
+exports.GraduationPipeline = GraduationPipeline;
+//# sourceMappingURL=index.js.map

package/dist/graduation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/graduation/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAEH,yDAAuE;AAA9D,oHAAA,eAAe,OAAA;AACxB,2DAM8B;AAL5B,uHAAA,iBAAiB,OAAA;AACjB,4HAAA,sBAAsB,OAAA;AACtB,6HAAA,uBAAuB,OAAA;AAIzB,+DAQgC;AAP9B,0HAAA,kBAAkB,OAAA;AAClB,8HAAA,sBAAsB,OAAA;AACtB,mIAAA,2BAA2B,OAAA;AAC3B,+HAAA,uBAAuB,OAAA;AAKzB,6DAK+B;AAJ7B,mHAAA,YAAY,OAAA;AACZ,sHAAA,eAAe,OAAA;AACf,0HAAA,mBAAmB,OAAA;AAKrB,2DAAuE;AACvE,6DAA4E;AAC5E,iEAKgC;AAChC,+DAAuE;AAevE,MAAa,kBAAkB;IAI7B,YAAY,MAAgC;QAFpC,WAAM,GAA2B,IAAI,CAAC;QAG5C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,sEAAsE;IAEtE;;OAEG;IACH,SAAS,CAAC,MAAc,EAAE,aAAsB;QAC9C,IAAI,CAAC,MAAM,GAAG,IAAI,mCAAe,CAAC;YAChC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC1B,MAAM;YACN,aAAa;SACd,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,KAAsE;QAC/E,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,sEAAsE;IAEtE;;OAEG;IACH,SAAS;QACP,MAAM,OAAO,GAAG,mCAAe,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAChE,OAAO,IAAA,sCAAiB,EAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IACjE,CAAC;IAED,sEAAsE;IAEtE;;OAEG;IACH,QAAQ,CAAC,WAA+B;QACtC,MAAM,GAAG,GAAG,WAAW,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QAC5C,OAAO,IAAA,yCAAkB,EACvB,GAAG,EACH,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,8CAAuB,EAC/C,IAAI,CAAC,MAAM,CAAC,oBAAoB,CACjC,CAAC;IACJ,CAAC;IAED,sEAAsE;IAEtE;;OAEG;IACH,MAAM,CAAC,MAAyB;QAC9B,MAAM,GAAG,GAAG,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,IAAA,qCAAe,EAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,sEAAsE;IAEtE;;;OAGG;IACH,WAAW;QAKT,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAExC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IAC9C,CAAC;CACF;AAnFD,gDAmFC"}

package/dist/graduation/pattern-aggregator.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Sprint 13a Week 2: Pattern Aggregator
+ *
+ * Stage 2 of the Graduation Pipeline.
+ * Reads verdict logs (JSONL) and aggregates FP patterns across scans.
+ * Produces statistics per fpPatternId: total dismissals, avg confidence,
+ * false confirmation rate, affected rules and file paths.
+ *
+ * This is the bridge between raw verdict data and graduation decisions.
+ */
+import { VerdictLogEntry } from './fp-verdict-logger';
+export interface PatternStats {
+    /** The FP pattern ID (from fp-patterns.ts library) */
+    fpPatternId: string;
+    /** Human-readable pattern name */
+    fpReason: string;
+    /** Total times this pattern was used to dismiss a violation */
+    totalDismissals: number;
+    /** Average confidence of dismissals (1-10) */
+    avgConfidence: number;
+    /** Min confidence seen */
+    minConfidence: number;
+    /** Max confidence seen */
+    maxConfidence: number;
+    /** Number of times this pattern's verdict was later contradicted (false dismissal) */
+    falseConfirmations: number;
+    /** Rules this pattern applies to */
+    affectedRules: string[];
+    /** Sample file paths (up to 5) */
+    samplePaths: string[];
+    /** Number of unique scans this pattern appeared in */
+    uniqueScans: number;
+    /** First seen timestamp */
+    firstSeen: string;
+    /** Last seen timestamp */
+    lastSeen: string;
+    /** Whether this pattern is in the static FP pattern library */
+    inLibrary: boolean;
+}
+export interface AggregationResult {
+    /** When the aggregation was run */
+    aggregatedAt: string;
+    /** Total verdict entries processed */
+    totalEntries: number;
+    /** Total dismissed entries */
+    totalDismissed: number;
+    /** Total confirmed/escalated entries */
+    totalConfirmed: number;
+    /** Number of unique scans */
+    uniqueScans: number;
+    /** Per-pattern statistics */
+    patterns: PatternStats[];
+    /** Patterns without fpPatternId (novel FP patterns from AI) */
+    unclassifiedDismissals: number;
+    /** Rules with highest FP rates */
+    highFPRules: Array<{
+        ruleId: string;
+        total: number;
+        dismissed: number;
+        fpRate: number;
+    }>;
+}
+/**
+ * Aggregate verdict log entries into per-pattern statistics.
+ *
+ * @param entries - All verdict log entries to aggregate
+ * @param knownPatternIds - Set of pattern IDs from the static FP library (for inLibrary flag)
+ */
+export declare function aggregatePatterns(entries: VerdictLogEntry[], knownPatternIds?: Set<string>): AggregationResult;
+/**
+ * Convenience: aggregate from a log directory.
+ */
+export declare function aggregateFromDirectory(logDir: string, knownPatternIds?: Set<string>): AggregationResult;
+/**
+ * Format aggregation result as a readable report.
+ */
+export declare function formatAggregationReport(result: AggregationResult): string;