@wooojin/forgen 0.4.8 → 0.4.9

package/dist/core/observability-backfill.js

@@ -0,0 +1,178 @@
+/**
+ * Forgen — Observability Backfill (Phase 2)
+ *
+ * 기존 JSONL 상태 파일에서 solution_events 를 소급 생성한다.
+ * Phase A (결정론적): match-eval-log, implicit-feedback, compound-usage, outcomes
+ * Phase B (휴리스틱): transcript 스캔 — CLI --phase B|all 로만 활성
+ *
+ * 안전성:
+ *   - 기본: events 가 이미 있으면 reject (--force 필요)
+ *   - signal_source 에 '-backfill' prefix 로 실시간 emit 과 구분
+ *   - BEGIN/COMMIT 단위 트랜잭션
+ *   - fail-open: 파일 누락은 조용히 skip
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+import { STATE_DIR, MATCH_EVAL_LOG_PATH, FORGEN_HOME } from './paths.js';
+import { createLogger } from './logger.js';
+import { emitSolutionEvent } from './observability-store.js';
+const require = createRequire(import.meta.url);
+const log = createLogger('observability-backfill');
+const DB_PATH = path.join(FORGEN_HOME, 'sessions.db');
+const COMPOUND_USAGE_LOG = path.join(STATE_DIR, 'compound-usage.jsonl');
+const IMPLICIT_FEEDBACK_LOG = path.join(STATE_DIR, 'implicit-feedback.jsonl');
+const OUTCOMES_DIR = path.join(STATE_DIR, 'outcomes');
+function readJsonlLines(filePath) {
+    if (!fs.existsSync(filePath))
+        return [];
+    try {
+        return fs.readFileSync(filePath, 'utf-8')
+            .split('\n')
+            .filter(Boolean)
+            .map(l => { try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        } })
+            .filter((x) => x !== null);
+    }
+    catch {
+        return [];
+    }
+}
+function hasExistingEvents() {
+    try {
+        if (!fs.existsSync(DB_PATH))
+            return false;
+        const { DatabaseSync } = require('node:sqlite');
+        const db = new DatabaseSync(DB_PATH);
+        try {
+            const row = db.prepare(`SELECT COUNT(*) AS cnt FROM solution_events`).get();
+            return (row?.cnt ?? 0) > 0;
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/** Phase A: 결정론적 소급 */
+async function runPhaseA(opts) {
+    const counts = { matched: 0, surfaced: 0, acted_on: 0 };
+    // 1. match-eval-log.jsonl → matched events
+    const matchLines = readJsonlLines(MATCH_EVAL_LOG_PATH);
+    for (const line of matchLines) {
+        const sessionId = line.sessionId ?? line.session_id ?? undefined;
+        const topN = line.rankedTopN ?? line.candidates?.slice(0, 5).map(c => c.name) ?? [];
+        const candidateMap = new Map((line.candidates ?? []).map(c => [c.name, c.relevance]));
+        for (const name of topN) {
+            if (!name)
+                continue;
+            const score = candidateMap.get(name) ?? null;
+            if (!opts.dryRun) {
+                emitSolutionEvent({
+                    sessionId: sessionId ?? null,
+                    solutionId: name,
+                    eventType: 'matched',
+                    signalSource: 'matcher-backfill',
+                    signalScore: score,
+                });
+            }
+            counts.matched++;
+            if (counts.matched % 1000 === 0)
+                process.stderr.write(`[backfill] matched: ${counts.matched}\n`);
+        }
+    }
+    // 2. implicit-feedback.jsonl type='recommendation_surfaced' → surfaced
+    const feedbackLines = readJsonlLines(IMPLICIT_FEEDBACK_LOG);
+    for (const line of feedbackLines) {
+        if (line.type !== 'recommendation_surfaced')
+            continue;
+        const sid = line.solutionId ?? line.solution_id;
+        if (!sid)
+            continue;
+        const sessionId = line.sessionId ?? line.session_id ?? undefined;
+        if (!opts.dryRun) {
+            emitSolutionEvent({
+                sessionId: sessionId ?? null,
+                solutionId: sid,
+                eventType: 'surfaced',
+                signalSource: 'hook-backfill',
+            });
+        }
+        counts.surfaced++;
+    }
+    // 3. compound-usage.jsonl → acted_on (signalSource='mcp-read-backfill')
+    const usageLines = readJsonlLines(COMPOUND_USAGE_LOG);
+    for (const line of usageLines) {
+        if (!line.name)
+            continue;
+        if (!opts.dryRun) {
+            emitSolutionEvent({
+                sessionId: null,
+                solutionId: line.name,
+                eventType: 'acted_on',
+                signalSource: 'mcp-read-backfill',
+                signalScore: 0.30,
+            });
+        }
+        counts.acted_on++;
+        if (counts.acted_on % 1000 === 0)
+            process.stderr.write(`[backfill] acted_on: ${counts.acted_on}\n`);
+    }
+    // 4. outcomes/<sid>.jsonl outcome='accept' → acted_on (signalSource='outcome-accept-backfill')
+    if (fs.existsSync(OUTCOMES_DIR)) {
+        const outFiles = fs.readdirSync(OUTCOMES_DIR).filter(f => f.endsWith('.jsonl'));
+        for (const file of outFiles) {
+            const lines = readJsonlLines(path.join(OUTCOMES_DIR, file));
+            for (const line of lines) {
+                if (line.outcome !== 'accept')
+                    continue;
+                const sid = line.solution_id ?? line.solutionId;
+                if (!sid)
+                    continue;
+                const sessionId = line.session_id ?? line.sessionId ?? undefined;
+                if (!opts.dryRun) {
+                    emitSolutionEvent({
+                        sessionId: sessionId ?? null,
+                        solutionId: sid,
+                        eventType: 'acted_on',
+                        signalSource: 'outcome-accept-backfill',
+                        signalScore: 0.15,
+                    });
+                }
+                counts.acted_on++;
+            }
+        }
+    }
+    return counts;
+}
+export async function runBackfill(opts = {}) {
+    const start = Date.now();
+    const phase = opts.phase ?? 'A';
+    if (!opts.force && !opts.dryRun) {
+        if (hasExistingEvents()) {
+            throw new Error('solution_events 테이블에 기존 이벤트가 있습니다. ' +
+                '--force 플래그를 사용하면 강행합니다.');
+        }
+    }
+    const phaseA = { matched: 0, surfaced: 0, acted_on: 0 };
+    const phaseB = { acted_on: 0 };
+    if (phase === 'A' || phase === 'all') {
+        const aResult = await runPhaseA(opts);
+        phaseA.matched = aResult.matched;
+        phaseA.surfaced = aResult.surfaced;
+        phaseA.acted_on = aResult.acted_on;
+    }
+    // Phase B: transcript 스캔 — 1차 release 는 opt-in 만
+    if (phase === 'B' || phase === 'all') {
+        log.debug('Phase B (transcript scan) 은 현재 미구현 — 향후 릴리스에서 활성화');
+    }
+    const total = phaseA.matched + phaseA.surfaced + phaseA.acted_on + phaseB.acted_on;
+    const durationMs = Date.now() - start;
+    return { phaseA, phaseB, total, durationMs };
+}

package/dist/core/observability-store.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Forgen — Observability Store (Phase 1)
+ *
+ * solution_events 테이블에 matched/surfaced/acted_on 이벤트를 기록.
+ * Fail-open: 모든 함수는 내부 오류를 삼키고 절대 throw 하지 않는다.
+ */
+export type EventType = 'matched' | 'surfaced' | 'acted_on';
+export interface EmitOptions {
+    ts?: number;
+    sessionId?: string | null;
+    solutionId: string;
+    eventType: EventType;
+    signalSource: string;
+    signalScore?: number | null;
+    meta?: Record<string, unknown>;
+}
+export interface SurfacedEvent {
+    id: number;
+    ts: number;
+    sessionId: string | null;
+    solutionId: string;
+    signalSource: string;
+    signalScore: number | null;
+    meta: Record<string, unknown> | null;
+}
+export interface HitRateRow {
+    solutionId: string;
+    matched_30d: number;
+    surfaced_30d: number;
+    acted_30d: number;
+    matched_90d: number;
+    surfaced_90d: number;
+    acted_90d: number;
+    matched_180d: number;
+    surfaced_180d: number;
+    acted_180d: number;
+    last_event_ts: number;
+}
+interface SqliteDb {
+    exec(sql: string): void;
+    prepare(sql: string): {
+        run(...args: unknown[]): {
+            lastInsertRowid: number;
+        };
+        get(...args: unknown[]): unknown;
+        all(...args: unknown[]): unknown[];
+    };
+    close(): void;
+}
+/** solution_events 스키마 및 schema_version 초기화. idempotent. */
+export declare function ensureObservabilitySchema(db: SqliteDb): void;
+/** solution_events 에 이벤트를 기록한다. fail-open (throw 없음). */
+export declare function emitSolutionEvent(opts: EmitOptions): void;
+/** 특정 세션에서 지정 시간 window 내 surfaced 이벤트 조회. */
+export declare function querySurfacedWithin(sessionId: string, minutesWindow: number): SurfacedEvent[];
+/** 30/90/180일 hit-rate 집계. solutionId 지정 시 단일 솔루션만. */
+export declare function queryHitRate(solutionId?: string): HitRateRow[];
+export {};

package/dist/core/observability-store.js

@@ -0,0 +1,195 @@
+/**
+ * Forgen — Observability Store (Phase 1)
+ *
+ * solution_events 테이블에 matched/surfaced/acted_on 이벤트를 기록.
+ * Fail-open: 모든 함수는 내부 오류를 삼키고 절대 throw 하지 않는다.
+ */
+import { createRequire } from 'node:module';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createLogger } from './logger.js';
+import { FORGEN_HOME } from './paths.js';
+const require = createRequire(import.meta.url);
+const log = createLogger('observability');
+const DB_PATH = path.join(FORGEN_HOME, 'sessions.db');
+const DEDUP_WINDOW_MS = 5 * 60 * 1000;
+/** DB 파일을 열고 SqliteDb 반환. 실패 시 null. */
+function openObsDb() {
+    try {
+        const { DatabaseSync } = require('node:sqlite');
+        const dbDir = path.dirname(DB_PATH);
+        if (!fs.existsSync(dbDir))
+            fs.mkdirSync(dbDir, { recursive: true });
+        const db = new DatabaseSync(DB_PATH);
+        db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL; PRAGMA busy_timeout=1000;`);
+        return db;
+    }
+    catch (e) {
+        log.debug('openObsDb 실패', e);
+        return null;
+    }
+}
+/** solution_events 스키마 및 schema_version 초기화. idempotent. */
+export function ensureObservabilitySchema(db) {
+    try {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS schema_version (
+        component TEXT PRIMARY KEY,
+        version INTEGER NOT NULL,
+        applied_at INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS solution_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts INTEGER NOT NULL,
+        session_id TEXT,
+        solution_id TEXT NOT NULL,
+        event_type TEXT NOT NULL CHECK(event_type IN ('matched','surfaced','acted_on')),
+        signal_source TEXT,
+        signal_score REAL,
+        meta TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_se_solution ON solution_events(solution_id, ts);
+      CREATE INDEX IF NOT EXISTS idx_se_session  ON solution_events(session_id, ts);
+      CREATE INDEX IF NOT EXISTS idx_se_type     ON solution_events(event_type, ts);
+    `);
+        const row = db.prepare(`SELECT version FROM schema_version WHERE component = 'observability'`).get();
+        if (!row) {
+            db.prepare(`INSERT INTO schema_version (component, version, applied_at) VALUES ('observability', 1, ?)`).run(Date.now());
+        }
+    }
+    catch (e) {
+        log.debug('ensureObservabilitySchema 실패', e);
+    }
+}
+/** solution_events 에 이벤트를 기록한다. fail-open (throw 없음). */
+export function emitSolutionEvent(opts) {
+    const ts = opts.ts ?? Date.now();
+    let db = null;
+    try {
+        db = openObsDb();
+        if (!db)
+            return;
+        ensureObservabilitySchema(db);
+        // dedup: 직전 5분 내 동일 (session, solution, source) 존재 시 skip
+        if (opts.sessionId) {
+            const dup = db.prepare(`
+        SELECT id FROM solution_events
+        WHERE session_id = ? AND solution_id = ? AND signal_source = ?
+          AND ts > ?
+        LIMIT 1
+      `).get(opts.sessionId, opts.solutionId, opts.signalSource, ts - DEDUP_WINDOW_MS);
+            if (dup)
+                return;
+        }
+        db.prepare(`
+      INSERT INTO solution_events (ts, session_id, solution_id, event_type, signal_source, signal_score, meta)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(ts, opts.sessionId ?? null, opts.solutionId, opts.eventType, opts.signalSource, opts.signalScore ?? null, opts.meta ? JSON.stringify(opts.meta) : null);
+    }
+    catch (e) {
+        log.debug('emitSolutionEvent 실패', e);
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+/** 특정 세션에서 지정 시간 window 내 surfaced 이벤트 조회. */
+export function querySurfacedWithin(sessionId, minutesWindow) {
+    let db = null;
+    try {
+        db = openObsDb();
+        if (!db)
+            return [];
+        ensureObservabilitySchema(db);
+        const since = Date.now() - minutesWindow * 60 * 1000;
+        const rows = db.prepare(`
+      SELECT id, ts, session_id, solution_id, signal_source, signal_score, meta
+      FROM solution_events
+      WHERE session_id = ? AND event_type = 'surfaced' AND ts >= ?
+      ORDER BY ts DESC
+    `).all(sessionId, since);
+        return rows.map(r => ({
+            id: r.id,
+            ts: r.ts,
+            sessionId: r.session_id,
+            solutionId: r.solution_id,
+            signalSource: r.signal_source,
+            signalScore: r.signal_score,
+            meta: r.meta ? JSON.parse(r.meta) : null,
+        }));
+    }
+    catch (e) {
+        log.debug('querySurfacedWithin 실패', e);
+        return [];
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+/** 30/90/180일 hit-rate 집계. solutionId 지정 시 단일 솔루션만. */
+export function queryHitRate(solutionId) {
+    let db = null;
+    try {
+        db = openObsDb();
+        if (!db)
+            return [];
+        ensureObservabilitySchema(db);
+        const now = Date.now();
+        const cutoff30 = now - 30 * 24 * 60 * 60 * 1000;
+        const cutoff90 = now - 90 * 24 * 60 * 60 * 1000;
+        const cutoff180 = now - 180 * 24 * 60 * 60 * 1000;
+        const where = solutionId ? `WHERE solution_id = ?` : '';
+        const baseParams = [
+            cutoff30, cutoff30, cutoff30,
+            cutoff90, cutoff90, cutoff90,
+            cutoff180, cutoff180, cutoff180,
+        ];
+        const params = solutionId ? [...baseParams, solutionId] : baseParams;
+        const rows = db.prepare(`
+      SELECT
+        solution_id,
+        SUM(CASE WHEN event_type='matched'  AND ts > ? THEN 1 ELSE 0 END) AS matched_30d,
+        SUM(CASE WHEN event_type='surfaced' AND ts > ? THEN 1 ELSE 0 END) AS surfaced_30d,
+        SUM(CASE WHEN event_type='acted_on' AND ts > ? THEN 1 ELSE 0 END) AS acted_30d,
+        SUM(CASE WHEN event_type='matched'  AND ts > ? THEN 1 ELSE 0 END) AS matched_90d,
+        SUM(CASE WHEN event_type='surfaced' AND ts > ? THEN 1 ELSE 0 END) AS surfaced_90d,
+        SUM(CASE WHEN event_type='acted_on' AND ts > ? THEN 1 ELSE 0 END) AS acted_90d,
+        SUM(CASE WHEN event_type='matched'  AND ts > ? THEN 1 ELSE 0 END) AS matched_180d,
+        SUM(CASE WHEN event_type='surfaced' AND ts > ? THEN 1 ELSE 0 END) AS surfaced_180d,
+        SUM(CASE WHEN event_type='acted_on' AND ts > ? THEN 1 ELSE 0 END) AS acted_180d,
+        MAX(ts) AS last_event_ts
+      FROM solution_events
+      ${where}
+      GROUP BY solution_id
+    `).all(...params);
+        return rows.map(r => ({
+            solutionId: r.solution_id,
+            matched_30d: r.matched_30d,
+            surfaced_30d: r.surfaced_30d,
+            acted_30d: r.acted_30d,
+            matched_90d: r.matched_90d,
+            surfaced_90d: r.surfaced_90d,
+            acted_90d: r.acted_90d,
+            matched_180d: r.matched_180d,
+            surfaced_180d: r.surfaced_180d,
+            acted_180d: r.acted_180d,
+            last_event_ts: r.last_event_ts,
+        }));
+    }
+    catch (e) {
+        log.debug('queryHitRate 실패', e);
+        return [];
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* ignore */ }
+    }
+}

package/dist/core/session-store.js

@@ -10,6 +10,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { createLogger } from './logger.js';
 import { FORGEN_HOME } from './paths.js';
+import { ensureObservabilitySchema } from './observability-store.js';
 const require = createRequire(import.meta.url);
 // Suppress ExperimentalWarning for node:sqlite (Node.js 22+)
 {
@@ -31,6 +32,7 @@ function openDb() {
         // Node.js 22+ experimental node:sqlite
         const { DatabaseSync } = require('node:sqlite');
         const db = new DatabaseSync(DB_PATH);
+        db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL; PRAGMA busy_timeout=1000;`);
         db.exec(`
       CREATE TABLE IF NOT EXISTS sessions (
         id TEXT PRIMARY KEY,
@@ -62,6 +64,8 @@ function openDb() {
             log.debug('FTS5 미지원 — LIKE 폴백 사용', e);
             fts5Available = false;
         }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ensureObservabilitySchema(db);
         return db;
     }
     catch (e) {

package/dist/core/spawn.d.ts

@@ -1,5 +1,22 @@
 import type { V1HarnessContext } from './harness.js';
 import type { RuntimeHost } from './types.js';
+/**
+ * Plan B-1: 세션 transcript 사후 스캔으로 rate-limit 감지.
+ *
+ * stdio='inherit' 라 Claude 출력을 직접 캡처할 수 없으므로,
+ * 세션 종료 후 transcript JSONL 의 마지막 N 라인을 읽어
+ * RATE_LIMIT_REGEX 매칭 여부를 확인한다.
+ *
+ * - transcript 없음 / 빈 파일 / parse 실패 → matched: false (fail-open)
+ * - 이미 pending-resume.json 존재 시 hook 이 먼저 잡은 것이므로 덮어쓰지 않음
+ *
+ * @param transcriptPath JSONL 파일 경로
+ * @param tailLines 검사할 마지막 라인 수 (기본 5)
+ */
+export declare function scanTranscriptForRateLimit(transcriptPath: string, tailLines?: number): Promise<{
+    matched: boolean;
+    resetAt: string | null;
+}>;
 /** Claude Code를 하네스 환경으로 실행. exit code를 반환. */
 export declare function spawnClaude(args: string[], context: V1HarnessContext, runtime?: RuntimeHost): Promise<number>;
 declare const MAX_RESUMES = 3;