@wooojin/forgen 0.1.0

package/dist/engine/compound-loop.js

@@ -0,0 +1,511 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ME_SOLUTIONS, ME_RULES } from '../core/paths.js';
+import { resolveScope } from '../core/scope-resolver.js';
+import { serializeSolutionV3, extractTags, DEFAULT_EVIDENCE, slugify } from './solution-format.js';
+/** 키워드 기반으로 인사이트를 개인/팀으로 자동 분류 */
+export function classifyInsight(title, content) {
+    const teamKeywords = [
+        'API', 'DB', 'database', 'migration', 'schema', 'deploy', 'CI', 'CD',
+        'security', 'auth', 'permission', 'error handling', 'logging', 'monitoring',
+        'convention', 'standard', 'guideline', 'rule', 'pattern', 'architecture',
+        'naming', 'structure', 'review', 'test strategy', 'documentation',
+        '에러 처리', '네이밍', '규칙', '규약', '표준', '패턴', '보안', '인증',
+        '배포', '마이그레이션', '아키텍처', '로깅', '모니터링', '구조',
+    ];
+    const personalKeywords = [
+        'shortcut', 'preference', 'my style', 'editor', 'workflow tip',
+        'vim', 'vscode', 'alias', 'snippet', 'dotfile',
+        '단축키', '내 스타일', '편의', '습관',
+    ];
+    const text = `${title} ${content}`.toLowerCase();
+    const teamScore = teamKeywords.filter(kw => text.includes(kw.toLowerCase())).length;
+    const personalScore = personalKeywords.filter(kw => text.includes(kw.toLowerCase())).length;
+    if (teamScore > personalScore) {
+        return { classification: 'team', reason: `team pattern (${teamScore} keyword matches)` };
+    }
+    if (personalScore > teamScore) {
+        return { classification: 'personal', reason: `personal style (${personalScore} keyword matches)` };
+    }
+    return { classification: 'personal', reason: 'default (personal)' };
+}
+/**
+ * Compound Loop — 이미 추출된 인사이트를 저장
+ */
+export async function runCompoundLoop(cwd, insights) {
+    const saved = [];
+    const skipped = [];
+    const scope = resolveScope(cwd);
+    for (const insight of insights) {
+        try {
+            const destPath = getDestPath(insight, scope.team?.name);
+            if (!destPath) {
+                skipped.push(`${insight.title}: cannot determine save path`);
+                continue;
+            }
+            // 중복 체크
+            if (fs.existsSync(destPath)) {
+                skipped.push(`${insight.title}: already exists`);
+                continue;
+            }
+            // 디렉토리 생성
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+            // 파일 저장
+            const fileContent = formatInsight(insight);
+            fs.writeFileSync(destPath, fileContent);
+            saved.push(`${insight.scope}/${insight.type}: ${insight.title}`);
+        }
+        catch (err) {
+            skipped.push(`${insight.title}: ${err.message}`);
+        }
+    }
+    return { saved, skipped };
+}
+function getDestPath(insight, _teamPackName) {
+    const fileName = `${slugify(insight.title)}.md`;
+    if (insight.scope === 'me') {
+        const dir = insight.type === 'rule' || insight.type === 'convention'
+            ? ME_RULES
+            : ME_SOLUTIONS;
+        return path.join(dir, fileName);
+    }
+    // v1: 팀 scope 제거 — 모든 인사이트를 개인으로 저장
+    const dir = insight.type === 'rule' || insight.type === 'convention'
+        ? ME_RULES
+        : ME_SOLUTIONS;
+    return path.join(dir, fileName);
+}
+/** Map v1 CompoundInsight type to v3 SolutionType */
+function mapInsightType(type) {
+    switch (type) {
+        case 'solution': return 'pattern';
+        case 'pattern': return 'pattern';
+        case 'rule': return 'decision';
+        case 'convention': return 'decision';
+        default: return 'pattern';
+    }
+}
+/** Infer identifiers from title and content for Code Reflection matching */
+function inferIdentifiers(title, content) {
+    const text = `${title} ${content}`;
+    // Extract PascalCase words (likely class/component names)
+    const pascalCase = text.match(/\b[A-Z][a-zA-Z0-9]{3,}\b/g) ?? [];
+    // Extract camelCase words starting with lowercase (likely function names)
+    const camelCase = text.match(/\b[a-z][a-zA-Z0-9]{3,}(?=[A-Z])\w*/g) ?? [];
+    // Extract quoted strings that look like identifiers
+    const quoted = text.match(/['"`]([a-zA-Z][a-zA-Z0-9-]{3,})['"`]/g)?.map(s => s.slice(1, -1)) ?? [];
+    const all = [...new Set([...pascalCase, ...camelCase, ...quoted])]
+        .filter(id => id.length >= 4 && id.length <= 50);
+    return all.slice(0, 10); // max 10 identifiers
+}
+function formatInsight(insight) {
+    const today = new Date().toISOString().split('T')[0];
+    const solution = {
+        frontmatter: {
+            name: slugify(insight.title),
+            version: 1,
+            status: 'candidate',
+            confidence: 0.5,
+            type: mapInsightType(insight.type),
+            scope: insight.scope,
+            tags: extractTags(`${insight.title} ${insight.content}`),
+            identifiers: inferIdentifiers(insight.title, insight.content),
+            evidence: { ...DEFAULT_EVIDENCE },
+            created: today,
+            updated: today,
+            supersedes: null,
+            extractedBy: insight.source === 'manual' ? 'manual' : 'auto',
+        },
+        context: '',
+        content: insight.content,
+    };
+    return serializeSolutionV3(solution);
+}
+// slugify is imported from solution-format.ts (single source of truth)
+/** 팀 제안으로 저장 (.compound/proposals/) */
+export function saveTeamProposals(insights, cwd) {
+    const proposalsDir = path.join(cwd, '.compound', 'proposals');
+    fs.mkdirSync(proposalsDir, { recursive: true });
+    const date = new Date().toISOString().split('T')[0];
+    const filename = `${date}-${Date.now()}.json`;
+    fs.writeFileSync(path.join(proposalsDir, filename), JSON.stringify(insights, null, 2));
+}
+/** .compound/proposals/ 에서 제안 파일 로드 */
+export function loadProposals(proposalsDir) {
+    if (!fs.existsSync(proposalsDir))
+        return [];
+    const files = fs.readdirSync(proposalsDir).filter(f => f.endsWith('.json'));
+    const all = [];
+    for (const file of files) {
+        try {
+            const content = fs.readFileSync(path.join(proposalsDir, file), 'utf-8');
+            const parsed = JSON.parse(content);
+            if (Array.isArray(parsed)) {
+                all.push(...parsed);
+            }
+        }
+        catch {
+            // skip malformed files
+        }
+    }
+    return all;
+}
+/** 제안 파일 정리 */
+export function cleanProposals(proposalsDir) {
+    if (!fs.existsSync(proposalsDir))
+        return;
+    const files = fs.readdirSync(proposalsDir).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+        fs.unlinkSync(path.join(proposalsDir, file));
+    }
+}
+/** CLI 핸들러: forgen compound */
+export async function handleCompound(args) {
+    const cwd = process.cwd();
+    const scope = resolveScope(cwd);
+    // --help 처리
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(`
+  Usage: forgen compound [options]
+
+  Default:
+    forgen compound             Preview auto analysis from recent session/code changes
+    forgen compound --save      Persist previewed insights
+
+  Manual add:
+    forgen compound --solution "title" "content"
+    forgen compound --rule "title" "content"
+    forgen compound --convention "title" "content"
+    forgen compound --to team        Save to team scope
+
+  Inspect & manage:
+    forgen compound list             List saved entries (solutions and rules)
+    forgen compound inspect <name>   Show saved entry details
+    forgen compound remove <name>    Remove a saved entry
+    forgen compound clean-stale      Retire solutions from removed extractors (C4 cleanup)
+    forgen compound rollback --since 2026-03-20
+                                     Rollback unused auto-extracted solutions since date
+
+  Lifecycle:
+    forgen compound --lifecycle      Run promotion/demotion/circuit-breaker check
+    forgen compound --verify <name>  Manually promote solution to verified
+
+  Auto-extraction:
+    forgen compound --pause-auto     Pause auto-extraction
+    forgen compound --resume-auto    Resume auto-extraction
+
+  Interactive:
+    forgen compound interactive
+`);
+        return;
+    }
+    // --pause-auto / --resume-auto
+    if (args.includes('--pause-auto') || args.includes('pause-auto')) {
+        const { pauseExtraction } = await import('./compound-extractor.js');
+        pauseExtraction();
+        console.log('  자동 추출이 중단되었습니다. resume-auto로 재개할 수 있습니다.\n');
+        return;
+    }
+    if (args.includes('--resume-auto') || args.includes('resume-auto')) {
+        const { resumeExtraction } = await import('./compound-extractor.js');
+        resumeExtraction();
+        console.log('  자동 추출이 재개되었습니다.\n');
+        return;
+    }
+    // --- lifecycle command ---
+    if (args.includes('--lifecycle') || args.includes('lifecycle')) {
+        const { runLifecycleCheck } = await import('./compound-lifecycle.js');
+        const result = runLifecycleCheck();
+        console.log('\n  Compound Lifecycle Check\n');
+        if (result.promoted.length) {
+            console.log('  Promoted:');
+            for (const p of result.promoted)
+                console.log(`    ↑ ${p}`);
+        }
+        if (result.demoted.length) {
+            console.log('  Demoted:');
+            for (const d of result.demoted)
+                console.log(`    ↓ ${d}`);
+        }
+        if (result.retired.length) {
+            console.log('  Retired:');
+            for (const r of result.retired)
+                console.log(`    ✗ ${r}`);
+        }
+        if (result.contradictions.length) {
+            console.log('  Contradictions:');
+            for (const c of result.contradictions)
+                console.log(`    ⚠ ${c}`);
+        }
+        if (!result.promoted.length && !result.demoted.length && !result.retired.length && !result.contradictions.length) {
+            console.log('  No lifecycle changes needed.\n');
+        }
+        console.log();
+        return;
+    }
+    // --- verify command ---
+    if (args.includes('--verify')) {
+        const nameIdx = args.indexOf('--verify') + 1;
+        const name = args[nameIdx];
+        if (!name || name.startsWith('--')) {
+            console.log('  Usage: forgen compound --verify <solution-name>\n');
+            return;
+        }
+        const { verifySolution } = await import('./compound-lifecycle.js');
+        if (verifySolution(name)) {
+            console.log(`  ✓ "${name}" verified 상태로 승격됨\n`);
+        }
+        else {
+            console.log(`  ✗ "${name}" 솔루션을 찾을 수 없거나 업데이트 실패\n`);
+        }
+        return;
+    }
+    // --- list command ---
+    if (args.includes('list') || args.includes('--list')) {
+        const { listSolutions } = await import('./compound-cli.js');
+        listSolutions();
+        return;
+    }
+    // --- inspect command ---
+    if (args.includes('inspect') || args.includes('--inspect')) {
+        const nameIdx = Math.max(args.indexOf('inspect'), args.indexOf('--inspect')) + 1;
+        const name = args[nameIdx];
+        if (!name || name.startsWith('--')) {
+            console.log('  Usage: forgen compound inspect <solution-name>\n');
+            return;
+        }
+        const { inspectSolution } = await import('./compound-cli.js');
+        inspectSolution(name);
+        return;
+    }
+    // --- clean-stale command (M-3 migration) ---
+    if (args.includes('clean-stale') || args.includes('--clean-stale')) {
+        const { cleanStaleSolutions } = await import('./compound-cli.js');
+        cleanStaleSolutions();
+        return;
+    }
+    // --- remove command ---
+    if (args.includes('remove') || args.includes('--remove')) {
+        const nameIdx = Math.max(args.indexOf('remove'), args.indexOf('--remove')) + 1;
+        const name = args[nameIdx];
+        if (!name || name.startsWith('--')) {
+            console.log('  Usage: forgen compound remove <solution-name>\n');
+            return;
+        }
+        const { removeSolution } = await import('./compound-cli.js');
+        removeSolution(name);
+        return;
+    }
+    // --- retag command ---
+    if (args.includes('retag') || args.includes('--retag')) {
+        const { retagSolutions } = await import('./compound-cli.js');
+        retagSolutions();
+        return;
+    }
+    // --- rollback command ---
+    if (args.includes('rollback') || args.includes('--rollback')) {
+        const sinceIdx = args.indexOf('--since');
+        const since = sinceIdx !== -1 ? args[sinceIdx + 1] : undefined;
+        if (!since) {
+            console.log('  Usage: forgen compound rollback --since 2026-03-20\n');
+            return;
+        }
+        const { rollbackSolutions } = await import('./compound-cli.js');
+        rollbackSolutions(since);
+        return;
+    }
+    // --- explicit interactive command ---
+    if (args.includes('interactive') || args.includes('--interactive')) {
+        await interactiveCompound(cwd, scope);
+        return;
+    }
+    // --- preview-first default mode ---
+    if (args.length === 0) {
+        const { previewExtraction } = await import('./compound-extractor.js');
+        const result = await previewExtraction(cwd);
+        console.log('\n  Compound Preview\n');
+        console.log(`  Scope: ${scope.summary}`);
+        console.log();
+        if (result.preview.length === 0) {
+            console.log(`  No auto-analysis preview available${result.reason ? `: ${result.reason}` : '.'}`);
+            console.log('  Run `forgen compound --save` after meaningful code changes, or `forgen compound interactive` for manual capture.\n');
+            return;
+        }
+        console.log('  Preview only — nothing was saved.\n');
+        for (const [index, insight] of result.preview.entries()) {
+            console.log(`  ${index + 1}. [${insight.type}] ${insight.name}`);
+            console.log(`     ${insight.content.split('\n')[0]}`);
+        }
+        if (result.skipped.length > 0) {
+            console.log('\n  Skipped:');
+            for (const entry of result.skipped.slice(0, 5)) {
+                console.log(`    - ${entry}`);
+            }
+        }
+        console.log('\n  Run `forgen compound --save` to persist this preview.\n');
+        return;
+    }
+    // --- auto save mode ---
+    if (args.includes('--save')) {
+        const { runExtraction } = await import('./compound-extractor.js');
+        const sessionId = `compound-cli-${Date.now()}`;
+        const result = await runExtraction(cwd, sessionId);
+        console.log('\n  Compound Save\n');
+        console.log(`  Scope: ${scope.summary}`);
+        console.log();
+        if (result.extracted.length === 0 && result.skipped.length === 0) {
+            console.log(`  No insights saved${result.reason ? `: ${result.reason}` : '.'}\n`);
+            return;
+        }
+        for (const saved of result.extracted) {
+            console.log(`  ✓ Saved: ${saved}`);
+        }
+        for (const skipped of result.skipped) {
+            console.log(`  ─ Skipped: ${skipped}`);
+        }
+        if (result.reason) {
+            console.log(`  Reason: ${result.reason}`);
+        }
+        console.log();
+        return;
+    }
+    // 인자가 없거나 알 수 없는 플래그만 있으면 수동 추가/interactive가 아닌 것으로 간주
+    const knownFlags = [
+        '--solution', '--rule', '--convention', '--pattern', '--to', '--pause-auto', '--resume-auto',
+        '--lifecycle', '--verify', '--save', '--interactive',
+        'list', 'inspect', 'remove', 'rollback', 'retag', 'lifecycle',
+        '--list', '--inspect', '--remove', '--rollback', '--retag', '--since', 'interactive',
+    ];
+    const hasTypeFlag = knownFlags.some(f => args.includes(f));
+    if (!hasTypeFlag) {
+        console.log('  Unknown compound arguments. Run `forgen compound --help` for usage.\n');
+        return;
+    }
+    console.log('\n  Compound Loop — Accumulating insights\n');
+    console.log(`  Scope: ${scope.summary}`);
+    console.log();
+    // 수동 인사이트 추가
+    const type = args.includes('--solution') ? 'solution'
+        : args.includes('--rule') ? 'rule'
+            : args.includes('--convention') ? 'convention'
+                : 'pattern';
+    const scopeTarget = args.includes('--to')
+        ? (args[args.indexOf('--to') + 1] === 'team' ? 'team' : 'me')
+        : 'me';
+    // --solution/--rule 다음 인자들이 제목과 내용 (-- 접두사 인자 필터)
+    const typeFlag = `--${type}`;
+    const flagIdx = args.indexOf(typeFlag);
+    const positionalArgs = args.slice(flagIdx + 1).filter(a => !a.startsWith('--'));
+    const title = positionalArgs[0];
+    const content = positionalArgs.slice(1).join(' ');
+    if (!title) {
+        console.log('  A title is required.');
+        console.log('  Usage: forgen compound --solution "title" "content"');
+        return;
+    }
+    const { classification, reason } = classifyInsight(title, content || title);
+    const insight = {
+        id: `c-${Date.now()}`,
+        type,
+        title,
+        content: content || title,
+        scope: scopeTarget,
+        classification,
+        reason,
+        source: 'manual',
+    };
+    const result = await runCompoundLoop(cwd, [insight]);
+    for (const s of result.saved) {
+        console.log(`  ✓ Saved: ${s}`);
+    }
+    for (const s of result.skipped) {
+        console.log(`  ─ Skipped: ${s}`);
+    }
+    console.log();
+}
+async function interactiveCompound(cwd, scope) {
+    console.log("\n  Forgen Compound — Today's insights\n");
+    console.log(`  Scope: ${scope.summary}`);
+    console.log();
+    // Non-interactive mode: 대화 없이 안내만 출력
+    if (!process.stdin.isTTY) {
+        console.log('  Non-interactive environment. Add insights via manual mode.\n');
+        console.log('  Usage:');
+        console.log('    forgen compound --solution "title" "content"');
+        console.log('    forgen compound --rule "title" "content"');
+        console.log('    forgen compound --convention "title" "content"');
+        console.log('    forgen compound --to team          Save to team scope\n');
+        console.log('  Interactive mode: run `forgen compound interactive` in a TTY environment\n');
+        return;
+    }
+    const readline = await import('node:readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const prompt = (q) => new Promise(resolve => rl.question(q, resolve));
+    const insights = [];
+    console.log('  Enter insights. Press enter on empty line to finish.\n');
+    let idx = 1;
+    while (true) {
+        const title = await prompt(`  [${idx}] Title (empty=quit): `);
+        if (!title.trim())
+            break;
+        const content = await prompt('      Content: ');
+        const typeChoiceStr = await prompt('      Type (1=solution 2=rule 3=convention 4=pattern) [1]: ');
+        const typeMap = { '1': 'solution', '2': 'rule', '3': 'convention', '4': 'pattern' };
+        const insightType = typeMap[typeChoiceStr.trim()] ?? 'solution';
+        const { classification, reason } = classifyInsight(title, content);
+        const insight = {
+            id: `c-${Date.now()}-${idx}`,
+            type: insightType,
+            title: title.trim(),
+            content: content.trim(),
+            classification,
+            reason,
+            scope: classification === 'team' ? 'team' : 'me',
+            source: 'manual',
+        };
+        insights.push(insight);
+        const icon = classification === 'team' ? '👥' : '👤';
+        console.log(`      → ${icon} ${classification} (${reason})\n`);
+        idx++;
+    }
+    if (insights.length === 0) {
+        console.log('  No insights.\n');
+        rl.close();
+        return;
+    }
+    // Show summary and let user adjust
+    console.log('\n  ── Classification results ──\n');
+    for (let i = 0; i < insights.length; i++) {
+        const ins = insights[i];
+        const icon = ins.classification === 'team' ? '👥 Team' : '👤 Personal';
+        console.log(`  ${i + 1}. [${icon}] ${ins.title}`);
+    }
+    console.log('\n  Enter number to toggle classification (e.g. 2=team→personal), enter to confirm');
+    const changes = await prompt('  > ');
+    if (changes.trim()) {
+        for (const num of changes.split(/[,\s]+/)) {
+            const changeIdx = parseInt(num, 10) - 1;
+            if (changeIdx >= 0 && changeIdx < insights.length) {
+                insights[changeIdx].classification = insights[changeIdx].classification === 'team' ? 'personal' : 'team';
+                insights[changeIdx].scope = insights[changeIdx].classification === 'team' ? 'team' : 'me';
+            }
+        }
+    }
+    // Save — runCompoundLoop을 통해 타입별 올바른 경로에 저장
+    const personal = insights.filter(i => i.classification === 'personal');
+    const team = insights.filter(i => i.classification === 'team');
+    if (personal.length > 0) {
+        const result = await runCompoundLoop(cwd, personal);
+        for (const s of result.saved)
+            console.log(`\n  ✓ Saved: ${s}`);
+        for (const s of result.skipped)
+            console.log(`  ─ Skipped: ${s}`);
+    }
+    // Save team to .compound/proposals/ (for later propose)
+    if (team.length > 0) {
+        saveTeamProposals(team, cwd);
+        console.log(`  ✓ ${team.length} team rule candidate(s) saved (.compound/proposals/)`);
+        console.log('  → Run forgen propose to share with the team.\n');
+    }
+    rl.close();
+}

package/dist/engine/match-eval-log.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Match eval log — JSONL ranking-decision writer (T3 of the Round 3 plan).
+ *
+ * Why this module exists:
+ *   The bootstrap evaluator (`evaluateSolutionMatcher`) measures matcher
+ *   quality against a labeled fixture, but production traffic is open-ended.
+ *   T2 hoisted query normalization out of the per-solution loop, which is
+ *   fast, but it also hid the "what did we actually rank, and why?" signal
+ *   from offline review. This module appends a single JSONL line per matcher
+ *   call capturing the normalized query, the top candidates with their
+ *   matched terms, and which ones the caller ultimately surfaced.
+ *
+ *   The target consumer is offline analysis: a reviewer can tail or grep
+ *   the file to spot systematic recall misses or spurious matches without
+ *   instrumenting production.
+ *
+ * Privacy posture (T3 security review fix):
+ *   The raw user prompt is NEVER written to disk. Instead, we store a
+ *   short SHA-256 prefix (`rawQueryHash`) plus character length
+ *   (`rawQueryLen`). This keeps dedup and "was the prompt substantial"
+ *   signals available for offline analysis while eliminating the PII /
+ *   API-key / credential leakage risk of persisting raw prompts in
+ *   `~/.forgen/state/match-eval-log.jsonl`. The `normalizedQuery` array
+ *   already carries the matching-signal payload and is safe to persist
+ *   because it only contains short tag tokens (never the full prompt).
+ *
+ * Operational principles:
+ *   1. **Off the critical path.** Never throw; never block. A failed write
+ *      is silently swallowed — the hook must continue to return its
+ *      solutions even if the log is misconfigured, read-only, or full.
+ *   2. **Bounded record size.** Candidates are capped at 5 (the matcher's
+ *      own top-5 cap). `normalizedQuery` is capped at 64 terms. Each
+ *      candidate's `matchedTerms` is capped at 16. Worst-case record ≈
+ *      2KB, which stays under Linux PIPE_BUF=4096 for safe concurrent
+ *      appends on local filesystems.
+ *   3. **Symlink defense.** `fs.openSync` with `O_NOFOLLOW` refuses to
+ *      follow a symlink at the log path. Without this guard, an attacker
+ *      with write access to `~/.forgen/state/` could redirect appends to
+ *      `~/.ssh/authorized_keys`, `~/.bashrc`, or other sensitive files.
+ *   4. **File-lock for concurrency.** Uses `withFileLockSync` to serialize
+ *      concurrent writers. macOS PIPE_BUF=512 is smaller than the worst-
+ *      case record size so POSIX atomic append alone isn't enough.
+ *   5. **Opt-out via env, fail-closed on invalid config.**
+ *      `FORGEN_MATCH_EVAL_LOG=off|disabled|0|false|no` disables entirely.
+ *      `FORGEN_MATCH_EVAL_LOG_SAMPLE=<float 0..1>` samples. An invalid
+ *      sample value (NaN, out of range, whitespace) falls back to 0
+ *      (skip) rather than 1 (log everything) — fail-closed for privacy.
+ *   6. **File size cap.** `readMatchEvalLog` refuses to parse files
+ *      larger than 50 MB to prevent OOM in the offline analyzer. Callers
+ *      are responsible for rotating the log externally.
+ */
+/** Environment variable controlling log enable/disable. */
+export declare const MATCH_EVAL_LOG_ENV = "FORGEN_MATCH_EVAL_LOG";
+/** Environment variable controlling sample rate (0.0 – 1.0). */
+export declare const MATCH_EVAL_LOG_SAMPLE_ENV = "FORGEN_MATCH_EVAL_LOG_SAMPLE";
+/**
+ * Single ranking decision captured at matcher call time.
+ *
+ * Rationale for each field:
+ *   - `source`: distinguishes the hook path (`solution-injector`) from the
+ *     MCP path (`solution-reader.searchSolutions`). They have different
+ *     query shapes and the log should support filtering by origin.
+ *   - `rawQueryHash`: first 16 hex chars of SHA-256 over the user prompt.
+ *     Enables dedup ("this query shape recurred") without persisting the
+ *     prompt text. NOT cryptographically reversible — only useful for
+ *     grouping identical queries in offline analysis.
+ *   - `rawQueryLen`: character count of the original prompt. A rough
+ *     "was this a substantial query?" signal that helps triage.
+ *   - `normalizedQuery`: the output of `defaultNormalizer.normalizeTerms`
+ *     over `extractTags(rawQuery)`. This is what actually drove matching,
+ *     so it's the most important piece for debugging ranking surprises.
+ *     Only short tag tokens — safe to persist.
+ *   - `candidates`: top-N ranked solutions with relevance and matched
+ *     terms. Bounded by `MAX_CANDIDATES_LOGGED`.
+ *   - `rankedTopN`: the names of the top-N solutions the CALLER RECEIVED
+ *     from the matcher at the time of logging. This is the pre-filter top
+ *     (hook path) or post-`limit` top (MCP path). Caller-side budget /
+ *     experiment / disjoint filtering happens AFTER logging and is not
+ *     captured here — by design, this field records what the matcher
+ *     returned, not what the hook ultimately injected.
+ *   - `ts`: ISO 8601 timestamp. Always set by the logger, never by the
+ *     caller — prevents clock injection from polluting the log.
+ */
+export interface MatchEvalLogRecord {
+    source: 'hook' | 'mcp';
+    rawQueryHash: string;
+    rawQueryLen: number;
+    normalizedQuery: string[];
+    candidates: Array<{
+        name: string;
+        relevance: number;
+        matchedTerms: string[];
+    }>;
+    rankedTopN: string[];
+    ts: string;
+}
+/**
+ * Caller payload. `ts` and `rawQueryHash`/`rawQueryLen` are derived by
+ * the logger from the caller-supplied `rawQuery`. `rawQuery` itself is
+ * consumed in-process only and never written to disk.
+ */
+export interface MatchEvalLogInput {
+    source: 'hook' | 'mcp';
+    /** Raw user prompt. Hashed + length-captured, never persisted. */
+    rawQuery: string;
+    normalizedQuery: string[];
+    candidates: Array<{
+        name: string;
+        relevance: number;
+        matchedTerms: string[];
+    }>;
+    /**
+     * Top-N by relevance that the matcher returned to the caller at log
+     * time. See `MatchEvalLogRecord.rankedTopN` for semantics — this is
+     * NOT the post-filter "actually injected" set.
+     */
+    rankedTopN: string[];
+}
+/**
+ * Append a single ranking decision to the match-eval-log JSONL file.
+ *
+ * Fail-open: any error is caught and debug-logged. Callers can invoke
+ * this without guarding — the logger will never bubble an exception into
+ * the hook critical path.
+ */
+export declare function logMatchDecision(input: MatchEvalLogInput): void;
+/**
+ * Read all records from the match-eval-log file. Intended for tests and
+ * offline analysis tools; NOT for hot-path use.
+ *
+ * Malformed lines (non-JSON, missing required fields, wrong shape) are
+ * silently skipped — preserves the debug value of the rest of the file
+ * if one entry gets corrupted by a partial write or tool error.
+ *
+ * DoS guard: refuses to read files larger than `MAX_LOG_FILE_SIZE_BYTES`
+ * to prevent OOM when a long-running log grows unbounded. Returns [] in
+ * that case and debug-logs the skip.
+ */
+export declare function readMatchEvalLog(): MatchEvalLogRecord[];