@wooojin/forgen 0.2.1 → 0.3.0

package/dist/engine/meta-learning/session-quality-scorer.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Forgen Meta-Learning — Session Quality Scorer (Feature 1)
+ *
+ * Joins existing data sources to compute a per-session quality score.
+ * This score feeds other meta-learning features (matcher tuning, thresholds).
+ *
+ * Data sources:
+ *   - injection-cache-{sessionId}.json → injected solutions
+ *   - modified-files-{sessionId}.json  → drift state
+ *   - implicit-feedback.jsonl          → revert/drift events
+ *   - me/behavior/*.json              → correction evidence
+ *   - state/sessions/{sessionId}.json  → session metadata
+ */
+import type { SessionQualityScore } from './types.js';
+interface InjectionCacheData {
+    injected: string[];
+    totalInjectedChars: number;
+    updatedAt: string;
+    /** Tag snapshot per solution (backfill feature) */
+    tags?: Record<string, string[]>;
+}
+interface DriftState {
+    sessionId: string;
+    totalEdits: number;
+    totalReverts: number;
+    ewmaEditRate: number;
+    ewmaRevertRate: number;
+    lastWarningAt: number | null;
+    lastCriticalAt: number | null;
+    hardCapReached: boolean;
+}
+interface ImplicitFeedbackEntry {
+    type: string;
+    sessionId?: string;
+    at: string;
+    [key: string]: unknown;
+}
+export declare function loadInjectionCache(sessionId: string): InjectionCacheData | null;
+export declare function loadDriftState(sessionId: string): DriftState | null;
+export declare function loadImplicitFeedback(sessionId: string): ImplicitFeedbackEntry[];
+export declare function loadSessionCorrections(sessionId: string): number;
+/**
+ * Compute overall session quality score (0-100, higher = better).
+ *
+ * Formula:
+ *   100
+ *   - (correctionRate × 15)        // each correction/prompt penalizes 15pts
+ *   - (driftScore × 0.3)           // drift 0-100 maps to 0-30 penalty
+ *   - (revertCount × 5)            // each revert penalizes 5pts
+ *   + (solutionEffectiveness × 20) // good solution usage boosts 0-20pts
+ */
+export declare function computeOverallScore(correctionRate: number, driftScore: number, revertCount: number, solutionEffectiveness: number): number;
+/**
+ * Score a session's quality by joining all available data sources.
+ * Returns null if insufficient data (no session state found).
+ */
+export declare function scoreSession(sessionId: string): SessionQualityScore | null;
+export declare function saveSessionQuality(score: SessionQualityScore, baseDir?: string): void;
+export declare function loadSessionQuality(sessionId: string, baseDir?: string): SessionQualityScore | null;
+export declare function loadRecentQualityScores(limit?: number, baseDir?: string): SessionQualityScore[];
+export {};

package/dist/engine/meta-learning/session-quality-scorer.js

@@ -0,0 +1,166 @@
+/**
+ * Forgen Meta-Learning — Session Quality Scorer (Feature 1)
+ *
+ * Joins existing data sources to compute a per-session quality score.
+ * This score feeds other meta-learning features (matcher tuning, thresholds).
+ *
+ * Data sources:
+ *   - injection-cache-{sessionId}.json → injected solutions
+ *   - modified-files-{sessionId}.json  → drift state
+ *   - implicit-feedback.jsonl          → revert/drift events
+ *   - me/behavior/*.json              → correction evidence
+ *   - state/sessions/{sessionId}.json  → session metadata
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ME_BEHAVIOR, STATE_DIR } from '../../core/paths.js';
+import { safeReadJSON } from '../../hooks/shared/atomic-write.js';
+function sanitizeId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+export function loadInjectionCache(sessionId) {
+    const cachePath = path.join(STATE_DIR, `injection-cache-${sanitizeId(sessionId)}.json`);
+    return safeReadJSON(cachePath, null);
+}
+function loadSolutionCache(sessionId) {
+    const cachePath = path.join(STATE_DIR, `solution-cache-${sanitizeId(sessionId)}.json`);
+    return safeReadJSON(cachePath, null);
+}
+export function loadDriftState(sessionId) {
+    const statePath = path.join(STATE_DIR, `modified-files-${sanitizeId(sessionId)}.json`);
+    const data = safeReadJSON(statePath, null);
+    return data?.drift ?? null;
+}
+export function loadImplicitFeedback(sessionId) {
+    const logPath = path.join(STATE_DIR, 'implicit-feedback.jsonl');
+    try {
+        if (!fs.existsSync(logPath))
+            return [];
+        const lines = fs.readFileSync(logPath, 'utf-8').split('\n').filter(Boolean);
+        const entries = [];
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                if (entry.sessionId === sessionId)
+                    entries.push(entry);
+            }
+            catch {
+                /* skip malformed lines */
+            }
+        }
+        return entries;
+    }
+    catch {
+        return [];
+    }
+}
+export function loadSessionCorrections(sessionId) {
+    try {
+        if (!fs.existsSync(ME_BEHAVIOR))
+            return 0;
+        let count = 0;
+        for (const file of fs.readdirSync(ME_BEHAVIOR)) {
+            if (!file.endsWith('.json'))
+                continue;
+            const data = safeReadJSON(path.join(ME_BEHAVIOR, file), null);
+            if (data?.session_id === sessionId && data?.type === 'explicit_correction') {
+                count++;
+            }
+        }
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
+function loadToolCallCount(sessionId) {
+    const statePath = path.join(STATE_DIR, `modified-files-${sanitizeId(sessionId)}.json`);
+    const data = safeReadJSON(statePath, null);
+    return data?.toolCallCount ?? 0;
+}
+// ── Score computation ──
+/**
+ * Compute overall session quality score (0-100, higher = better).
+ *
+ * Formula:
+ *   100
+ *   - (correctionRate × 15)        // each correction/prompt penalizes 15pts
+ *   - (driftScore × 0.3)           // drift 0-100 maps to 0-30 penalty
+ *   - (revertCount × 5)            // each revert penalizes 5pts
+ *   + (solutionEffectiveness × 20) // good solution usage boosts 0-20pts
+ */
+export function computeOverallScore(correctionRate, driftScore, revertCount, solutionEffectiveness) {
+    const raw = 100 - correctionRate * 15 - driftScore * 0.3 - revertCount * 5 + solutionEffectiveness * 20;
+    return Math.max(0, Math.min(100, Math.round(raw * 100) / 100));
+}
+// ── Main entry ──
+/**
+ * Score a session's quality by joining all available data sources.
+ * Returns null if insufficient data (no session state found).
+ */
+export function scoreSession(sessionId) {
+    // Load injected solutions — try both caches
+    const injectionCache = loadInjectionCache(sessionId);
+    const solutionCache = loadSolutionCache(sessionId);
+    const injectedSolutions = injectionCache?.injected ?? solutionCache?.injected ?? [];
+    // Load drift state
+    const drift = loadDriftState(sessionId);
+    const driftScore = drift ? Math.min(100, drift.ewmaEditRate * 65 + drift.ewmaRevertRate * 35) : 0;
+    const revertCount = drift?.totalReverts ?? 0;
+    // Count corrections
+    const corrections = loadSessionCorrections(sessionId);
+    const toolCallCount = loadToolCallCount(sessionId);
+    // Use toolCallCount as proxy for prompt count (each prompt leads to tool calls)
+    const promptEstimate = Math.max(1, Math.ceil(toolCallCount / 3));
+    const correctionRate = corrections / promptEstimate;
+    // Solution effectiveness: we can only measure at session level
+    // by checking how many injected solutions have reflected > 0.
+    // For per-session granularity, count revert events as negative signal.
+    const implicitFeedback = loadImplicitFeedback(sessionId);
+    const revertEvents = implicitFeedback.filter((e) => e.type === 'revert_detected').length;
+    // Effectiveness: 1 - (negative signals / total injections), clamped to [0, 1]
+    const solutionEffectiveness = injectedSolutions.length > 0
+        ? Math.max(0, Math.min(1, 1 - revertEvents / injectedSolutions.length))
+        : 0;
+    const overallScore = computeOverallScore(correctionRate, driftScore, revertCount, solutionEffectiveness);
+    return {
+        sessionId,
+        correctionRate: Math.round(correctionRate * 1000) / 1000,
+        driftScore: Math.round(driftScore * 100) / 100,
+        revertCount,
+        solutionEffectiveness: Math.round(solutionEffectiveness * 1000) / 1000,
+        overallScore,
+        injectedSolutions,
+        computedAt: new Date().toISOString(),
+    };
+}
+// ── Persistence ──
+export function saveSessionQuality(score, baseDir) {
+    const dir = baseDir ?? path.join(STATE_DIR, 'session-quality');
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${sanitizeId(score.sessionId)}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(score, null, 2));
+}
+export function loadSessionQuality(sessionId, baseDir) {
+    const dir = baseDir ?? path.join(STATE_DIR, 'session-quality');
+    const filePath = path.join(dir, `${sanitizeId(sessionId)}.json`);
+    return safeReadJSON(filePath, null);
+}
+export function loadRecentQualityScores(limit = 10, baseDir) {
+    const dir = baseDir ?? path.join(STATE_DIR, 'session-quality');
+    try {
+        if (!fs.existsSync(dir))
+            return [];
+        const files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+        const scores = [];
+        for (const file of files) {
+            const score = safeReadJSON(path.join(dir, file), null);
+            if (score)
+                scores.push(score);
+        }
+        return scores.sort((a, b) => b.computedAt.localeCompare(a.computedAt)).slice(0, limit);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/engine/meta-learning/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Forgen Meta-Learning — Shared Types
+ *
+ * HyperAgents-inspired self-tuning layer above the compound system.
+ * All types consumed by the meta-learning runner and its sub-modules.
+ */
+export interface SessionQualityScore {
+    sessionId: string;
+    /** corrections per prompt in this session */
+    correctionRate: number;
+    /** final EWMA drift score (0-100) */
+    driftScore: number;
+    /** total reverts detected */
+    revertCount: number;
+    /** reflected / injected ratio (0-1, NaN → 0 if no injections) */
+    solutionEffectiveness: number;
+    /** composite score 0-100 (higher = better) */
+    overallScore: number;
+    /** which solutions were injected this session */
+    injectedSolutions: string[];
+    computedAt: string;
+}
+export interface MatcherWeights {
+    tfidf: number;
+    bm25: number;
+    bigram: number;
+    updatedAt: string;
+    /** how many solutions informed this tuning */
+    sampleSize: number;
+    /** monotonic version for rollback detection */
+    version: number;
+    /** original defaults for fallback */
+    defaults: {
+        tfidf: number;
+        bm25: number;
+        bigram: number;
+    };
+}
+export interface PromotionThresholds {
+    reflected: number;
+    sessions: number;
+    reExtracted: number;
+}
+export interface AdaptiveLifecycleThresholds {
+    experiment: PromotionThresholds;
+    candidate: PromotionThresholds;
+    verified: PromotionThresholds & {
+        negative: number;
+    };
+    /** solutions per week */
+    learningVelocity: number;
+    updatedAt: string;
+    sampleSize: number;
+    defaults: {
+        experiment: PromotionThresholds;
+        candidate: PromotionThresholds;
+        verified: PromotionThresholds & {
+            negative: number;
+        };
+    };
+}
+export interface ExtractionBias {
+    typeWeights: Record<string, number>;
+    updatedAt: string;
+    sampleSize: number;
+}
+export interface ProjectUsageEntry {
+    projects: string[];
+    updatedAt: string;
+}
+export interface ProjectUsageMap {
+    solutions: Record<string, ProjectUsageEntry>;
+}
+export interface MetaLearningFeatures {
+    sessionQualityScorer: boolean;
+    matcherWeightTuning: boolean;
+    scopeAutoPromotion: boolean;
+    adaptiveThresholds: boolean;
+    extractionTuning: boolean;
+}
+export interface ColdStartConfig {
+    minSessionsForQuality: number;
+    minSolutionsForMatcher: number;
+    minSolutionsForThresholds: number;
+    minSolutionsForExtraction: number;
+    minProjectsForScope: number;
+}
+export interface GuardrailConfig {
+    weightFloor: number;
+    weightCeiling: number;
+    maxWeightDelta: number;
+    thresholdFloor: number;
+    thresholdCeiling: number;
+    maxThresholdDelta: number;
+    degradationThreshold: number;
+}
+export interface MetaLearningConfig {
+    enabled: boolean;
+    features: MetaLearningFeatures;
+    coldStart: ColdStartConfig;
+    guardrails: GuardrailConfig;
+}
+export interface MetaLearningResult {
+    skipped?: boolean;
+    reason?: string;
+    qualityScore?: SessionQualityScore | null;
+    matcherWeights?: MatcherWeights | null;
+    scopePromotions?: string[];
+    thresholds?: AdaptiveLifecycleThresholds | null;
+    extractionBias?: ExtractionBias | null;
+}
+export declare const DEFAULT_CONFIG: MetaLearningConfig;
+export declare const DEFAULT_MATCHER_WEIGHTS: MatcherWeights['defaults'];
+export declare const DEFAULT_PROMOTION_THRESHOLDS: AdaptiveLifecycleThresholds['defaults'];

package/dist/engine/meta-learning/types.js

@@ -0,0 +1,43 @@
+/**
+ * Forgen Meta-Learning — Shared Types
+ *
+ * HyperAgents-inspired self-tuning layer above the compound system.
+ * All types consumed by the meta-learning runner and its sub-modules.
+ */
+// ── Defaults ──
+export const DEFAULT_CONFIG = {
+    enabled: false,
+    features: {
+        sessionQualityScorer: true,
+        matcherWeightTuning: true,
+        scopeAutoPromotion: true,
+        adaptiveThresholds: true,
+        extractionTuning: true,
+    },
+    coldStart: {
+        minSessionsForQuality: 1,
+        minSolutionsForMatcher: 10,
+        minSolutionsForThresholds: 15,
+        minSolutionsForExtraction: 20,
+        minProjectsForScope: 3,
+    },
+    guardrails: {
+        weightFloor: 0.1,
+        weightCeiling: 0.7,
+        maxWeightDelta: 0.05,
+        thresholdFloor: 2,
+        thresholdCeiling: 15,
+        maxThresholdDelta: 1,
+        degradationThreshold: 0.3,
+    },
+};
+export const DEFAULT_MATCHER_WEIGHTS = {
+    tfidf: 0.5,
+    bm25: 0.3,
+    bigram: 0.2,
+};
+export const DEFAULT_PROMOTION_THRESHOLDS = {
+    experiment: { reflected: 3, sessions: 3, reExtracted: 2 },
+    candidate: { reflected: 4, sessions: 3, reExtracted: 2 },
+    verified: { reflected: 8, sessions: 5, reExtracted: 2, negative: 1 },
+};

package/dist/engine/solution-format.d.ts

@@ -13,7 +13,7 @@ export interface SolutionFrontmatter {
     status: SolutionStatus;
     confidence: number;
     type: SolutionType;
-    scope: 'me' | 'team' | 'project';
+    scope: 'me' | 'team' | 'project' | 'universal';
     tags: string[];
     identifiers: string[];
     evidence: SolutionEvidence;
@@ -33,7 +33,7 @@ export interface SolutionIndexEntry {
     status: SolutionStatus;
     confidence: number;
     type: SolutionType;
-    scope: 'me' | 'team' | 'project';
+    scope: 'me' | 'team' | 'project' | 'universal';
     tags: string[];
     /**
      * Pre-expanded tag set, computed at index build time via the term normalizer.