principles-disciple 1.72.0 → 1.73.0

package/src/core/correction-cue-learner.ts

@@ -21,44 +21,19 @@ import {
   CORRECTION_SEED_KEYWORDS,
   MAX_CORRECTION_KEYWORDS,
 } from './correction-types.js';
-import { checkKeywordOptCooldown, recordKeywordOptRun } from '../service/nocturnal-runtime.js';
 import { atomicWriteFileSync } from '../utils/io.js';
 
 const KEYWORD_STORE_FILE = 'correction_keywords.json';
 
-// CORR-08: Daily optimization throttle (uses checkCooldown in nocturnal-runtime.ts)
-// Note: throttle state is stored in nocturnal-runtime.json, not a separate file.
-
-// Weight bounds for correction keywords (D-39-03, D-39-15)
 const MIN_KEYWORD_WEIGHT = 0.1;
 const MAX_KEYWORD_WEIGHT = 0.9;
 
-// =========================================================================
-// Module-level cache (D-04, D-05)
-// =========================================================================
-
-/**
- * Invalidated on every successful save so the next load re-reads from disk.
- * Set to null intentionally — never assume disk and memory are in sync after a write.
- */
 let _correctionCueCache: CorrectionKeywordStore | null = null;
 
-/**
- * Resets the module-level cache (for testing only).
- * @internal
- */
 export function _resetCorrectionCueCache(): void {
   _correctionCueCache = null;
 }
 
-// =========================================================================
-// Default store factory
-// =========================================================================
-
-/**
- * Creates a fresh store populated with the 16 seed keywords (D-08, D-09).
- * addedAt is stamped with the current ISO timestamp.
- */
 function createDefaultStore(): CorrectionKeywordStore {
   const now = new Date().toISOString();
   const keywords: CorrectionKeyword[] = CORRECTION_SEED_KEYWORDS.map((k) => ({
@@ -69,14 +44,6 @@ function createDefaultStore(): CorrectionKeywordStore {
   return { keywords, version: 1, lastOptimizedAt: now };
 }
 
-// =========================================================================
-// Load / save
-// =========================================================================
-
-/**
- * Loads the keyword store from disk.
- * On first run (file absent) or parse failure, creates and persists the default store.
- */
 export function loadCorrectionKeywordStore(stateDir: string): CorrectionKeywordStore {
   if (_correctionCueCache) return _correctionCueCache;
 
@@ -88,23 +55,16 @@ export function loadCorrectionKeywordStore(stateDir: string): CorrectionKeywordS
       _correctionCueCache = JSON.parse(raw) as CorrectionKeywordStore;
       return _correctionCueCache;
     } catch {
-      // Parse failure — fall through to default
+      void 0;
     }
   }
 
-  // File absent or corrupt: seed the store and persist it (D-01)
   const defaultStore = createDefaultStore();
   saveCorrectionKeywordStore(stateDir, defaultStore);
   _correctionCueCache = defaultStore;
   return _correctionCueCache;
 }
 
-/**
- * Atomically saves the keyword store to disk (D-03, T-38-02).
- * Uses temp-file-then-rename to ensure the file is always valid JSON or
- * the previous valid state if a crash occurs mid-write.
- * MUST invalidate the cache after the rename (D-05).
- */
 export function saveCorrectionKeywordStore(
   stateDir: string,
   store: CorrectionKeywordStore
@@ -114,29 +74,17 @@ export function saveCorrectionKeywordStore(
   fs.mkdirSync(stateDir, { recursive: true });
   atomicWriteFileSync(filePath, JSON.stringify(store, null, 2));
 
-  // Invalidate cache so the next read re-loads from disk (D-05)
   _correctionCueCache = null;
 }
 
-// =========================================================================
-// Throttle helpers (CORR-08)
-// =========================================================================
-// Singleton state
-// =========================================================================
-
 let _instance: CorrectionCueLearner | null = null;
 let _lastStateDir: string | null = null;
 
-/** Resets singleton state (for testing only). @internal */
 export function _resetCorrectionCueLearnerInstance(): void {
   _instance = null;
   _lastStateDir = null;
 }
 
-// =========================================================================
-// CorrectionCueLearner class
-// =========================================================================
-
 export class CorrectionCueLearner {
   private readonly store: CorrectionKeywordStore;
   private readonly stateDir: string;
@@ -146,17 +94,6 @@ export class CorrectionCueLearner {
     this.store = loadCorrectionKeywordStore(stateDir);
   }
 
-  // ── Public API ──────────────────────────────────────────────────────────
-
-  /**
-   * Checks whether text contains a correction cue (D-11).
-   * Pure read-only — does NOT modify the store.
-   * Normalisation is equivalent to the original detectCorrectionCue():
-   *   trim → lowercase → strip punctuation
-   * Returns weighted score based on keyword accuracy (D-39-03, D-39-04).
-   *
-   * To record hits/TPs, call recordHit() and recordTruePositive() separately.
-   */
   match(text: string): CorrectionMatchResult {
     const normalized = text
       .trim()
@@ -168,9 +105,6 @@ export class CorrectionCueLearner {
 
     for (const keyword of this.store.keywords) {
       if (normalized.includes(keyword.term.toLowerCase())) {
-        // D-39-03, D-39-04: Weighted score formula
-        // No history (tp=0, fp=0) → accuracy = 1 (trust raw weight)
-        // Has history → accuracy = tp / (tp + fp) (proportional to true positive rate)
         const tp = keyword.truePositiveCount ?? 0;
         const fp = keyword.falsePositiveCount ?? 0;
         const accuracy = (tp + fp) > 0 ? tp / (tp + fp) : 1;
@@ -184,7 +118,6 @@ export class CorrectionCueLearner {
     const cappedScore = Math.min(1, totalScore);
     const isMatched = matchedTerms.length > 0;
 
-    // D-39-04: Confidence derived from multiple signals
     const termConfidence = Math.min(1, matchedTerms.length / 3);
     const scoreConfidence = Math.min(1, cappedScore / 0.8);
     const confidence = Math.max(termConfidence, scoreConfidence);
@@ -197,12 +130,6 @@ export class CorrectionCueLearner {
     };
   }
 
-  /**
-   * Records a keyword hit (for hitCount/FPR tracking).
-   * Increments hitCount and updates lastHitAt for all matched terms.
-   * Intentionally does NOT flush — hitCount is best-effort analytics,
-   * persisted by the next recordTruePositive() or flush() call.
-   */
   recordHits(terms: string[]): void {
     for (const term of terms) {
       const keywordIndex = this.store.keywords.findIndex(k => k.term.toLowerCase() === term.toLowerCase());
@@ -216,17 +143,12 @@ export class CorrectionCueLearner {
     }
   }
 
-  /**
-   * Records a confirmed true positive for the given keyword term.
-   * Increments truePositiveCount atomically.
-   */
   recordTruePositive(term: string): void {
     const keyword = this.store.keywords.find(k => k.term.toLowerCase() === term.toLowerCase());
     if (!keyword) return;
 
     keyword.truePositiveCount = (keyword.truePositiveCount ?? 0) + 1;
 
-    // Update in-store reference
     const keywordIndex = this.store.keywords.findIndex(k => k.term.toLowerCase() === term.toLowerCase());
     if (keywordIndex >= 0) {
       this.store.keywords[keywordIndex] = { ...keyword };
@@ -235,61 +157,23 @@ export class CorrectionCueLearner {
     this.flush();
   }
 
-  /**
-   * Records a confirmed false positive for the given keyword term.
-   * CORR-10: Decreases keyword weight by 20% (x0.8 multiplicative factor).
-   * D-39-17: Keywords at very low weight (<0.1) still match but contribute minimally.
-   */
   recordFalsePositive(term: string): void {
     const keyword = this.store.keywords.find(k => k.term.toLowerCase() === term.toLowerCase());
     if (!keyword) return;
 
     keyword.falsePositiveCount = (keyword.falsePositiveCount ?? 0) + 1;
 
-    // D-39-15: Multiplicative weight decay x0.8 on confirmed FP
     keyword.weight = Math.max(MIN_KEYWORD_WEIGHT, keyword.weight * 0.8);
     keyword.lastHitAt = new Date().toISOString();
 
-    // Update in-store reference
     const keywordIndex = this.store.keywords.findIndex(k => k.term.toLowerCase() === term.toLowerCase());
     if (keywordIndex >= 0) {
       this.store.keywords[keywordIndex] = { ...keyword };
     }
 
-    // D-39-16: Apply decay BEFORE flush to disk
     this.flush();
   }
 
-  /**
-   * Returns true if optimization is allowed (within daily throttle limit).
-   * CORR-08: Max 4 optimizations per day across all triggers.
-   */
-  canRunKeywordOptimization(): boolean {
-    // D-39-12, D-39-13: Per-workspace throttle, 4 calls/day
-    // Uses dedicated keywordOptRunTimestamps array to avoid pollution from regular nocturnal runs (#321)
-    const cooldown = checkKeywordOptCooldown(this.stateDir, {
-      maxRunsPerWindow: 4,
-      quotaWindowMs: 24 * 60 * 60 * 1000,
-    });
-    return !cooldown.quotaExhausted;
-  }
-
-  /**
-   * Records that an optimization was performed.
-   * Updates lastOptimizedAt for the store and records the run in the
-   * keyword-optimization quota (dedicated from regular nocturnal quota).
-   * @throws Error if quota recording fails — caller should propagate
-   */
-  async recordOptimizationPerformed(): Promise<void> {
-    this.store.lastOptimizedAt = new Date().toISOString();
-    this.flush();
-    await recordKeywordOptRun(this.stateDir);
-  }
-
-  /**
-   * Adds a new keyword to the store and immediately flushes (D-06, D-07).
-   * Throws if the 200-term limit would be exceeded.
-   */
   add(keyword: Omit<CorrectionKeyword, 'addedAt'>): void {
     if (this.store.keywords.length >= MAX_CORRECTION_KEYWORDS) {
       throw new Error('Correction keyword store limit reached (200 terms)');
@@ -304,11 +188,6 @@ export class CorrectionCueLearner {
     this.flush();
   }
 
-  /**
-   * Updates the weight of an existing keyword.
-   * Weight is clamped to 0.1-0.9 range.
-   * Throws if keyword not found.
-   */
   updateWeight(term: string, weight: number): void {
     const keyword = this.store.keywords.find(
       k => k.term.toLowerCase() === term.toLowerCase()
@@ -317,7 +196,7 @@ export class CorrectionCueLearner {
       throw new Error(`Keyword not found: ${term}`);
     }
 
-    keyword.weight = Math.max(MIN_KEYWORD_WEIGHT, Math.min(MAX_KEYWORD_WEIGHT, weight)); // Clamp to MIN-MAX_KEYWORD_WEIGHT
+    keyword.weight = Math.max(MIN_KEYWORD_WEIGHT, Math.min(MAX_KEYWORD_WEIGHT, weight));
     const idx = this.store.keywords.findIndex(
       k => k.term.toLowerCase() === term.toLowerCase()
     );
@@ -327,10 +206,6 @@ export class CorrectionCueLearner {
     this.flush();
   }
 
-  /**
-   * Removes a keyword from the store by term.
-   * Throws if keyword not found.
-   */
   remove(term: string): void {
     const idx = this.store.keywords.findIndex(
       k => k.term.toLowerCase() === term.toLowerCase()
@@ -342,27 +217,18 @@ export class CorrectionCueLearner {
     this.flush();
   }
 
-  /** Returns a reference to the in-memory store. */
   getStore(): CorrectionKeywordStore {
     return this.store;
   }
 
-  /** Returns the lastOptimizedAt timestamp. */
   getLastOptimizedAt(): string {
     return this.store.lastOptimizedAt;
   }
 
-  /** Persists the current in-memory store to disk atomically. */
   flush(): void {
     saveCorrectionKeywordStore(this.stateDir, this.store);
   }
 
-  // ── Singleton factory ───────────────────────────────────────────────────
-
-  /**
-   * Returns the shared CorrectionCueLearner instance for a given stateDir.
-   * Re-creates the instance if stateDir changes (e.g. workspace switch).
-   */
   static get(stateDir: string): CorrectionCueLearner {
     if (!_instance || _lastStateDir !== stateDir) {
       _instance = new CorrectionCueLearner(stateDir);

package/src/core/correction-types.ts

@@ -1,88 +1,16 @@
-/**
- * Correction Cue Keyword Types
- *
- * Types for the dynamic correction cue detection system.
- * Replaces the previous hardcoded cue list in detectCorrectionCue()
- * with a persistent, learnable keyword store.
- */
-
-// =========================================================================
-// Keyword Store
-// =========================================================================
-
-export interface CorrectionKeyword {
-  /** The keyword term to match against normalized user text */
-  term: string;
-  /** Contribution weight (0-1) */
-  weight: number;
-  /** How this keyword was introduced */
-  source: 'seed' | 'llm' | 'user';
-  /** ISO 8601 timestamp of when this keyword was added */
-  addedAt: string;
-  /** Total times this keyword has matched (default: 0) */
-  hitCount?: number;
-  /** Confirmed correct matches (default: 0) */
-  truePositiveCount?: number;
-  /** Confirmed incorrect matches (default: 0) */
-  falsePositiveCount?: number;
-  /** Last time this keyword matched (ISO timestamp) */
-  lastHitAt?: string;
-}
-
-export interface CorrectionKeywordStore {
-  /** All correction keywords */
-  keywords: CorrectionKeyword[];
-  /** Schema version */
-  version: number;
-  /** Last time keyword optimization was performed (ISO timestamp) */
-  lastOptimizedAt: string;
-}
-
-// =========================================================================
-// Match Result
-// =========================================================================
-
-export interface CorrectionMatchResult {
-  /** Whether any keyword matched */
-  matched: boolean;
-  /** Matched terms (empty array when no match; may be truncated to first N items) */
-  matchedTerms: string[];
-  /** Weighted score (0-1) based on keyword weight and accuracy */
-  score: number;
-  /** Confidence in the match result (0-1) */
-  confidence: number;
-}
-
-// =========================================================================
-// Seed Keywords (16 terms — sourced from detectCorrectionCue)
-// =========================================================================
-
-/** Maximum number of keywords the store may hold (D-06). */
-export const MAX_CORRECTION_KEYWORDS = 200;
-
-/**
- * Preset seed keywords for correction cue detection.
- * Mirrors the hardcoded list in detectCorrectionCue() exactly (D-08).
- * addedAt is intentionally empty here — it is filled in at runtime by
- * createDefaultStore() when the store is first persisted to disk.
- */
-export const CORRECTION_SEED_KEYWORDS: CorrectionKeyword[] = [
-  // Chinese (8)
-  { term: '不是这个', weight: 0.6, source: 'seed', addedAt: '' },
-  { term: '不对', weight: 0.5, source: 'seed', addedAt: '' },
-  { term: '错了', weight: 0.5, source: 'seed', addedAt: '' },
-  { term: '搞错了', weight: 0.7, source: 'seed', addedAt: '' },
-  { term: '理解错了', weight: 0.7, source: 'seed', addedAt: '' },
-  { term: '你理解错了', weight: 0.8, source: 'seed', addedAt: '' },
-  { term: '重新来', weight: 0.6, source: 'seed', addedAt: '' },
-  { term: '再试一次', weight: 0.4, source: 'seed', addedAt: '' },
-  // English (8)
-  { term: 'you are wrong', weight: 0.7, source: 'seed', addedAt: '' },
-  { term: 'wrong file', weight: 0.6, source: 'seed', addedAt: '' },
-  { term: 'not this', weight: 0.4, source: 'seed', addedAt: '' },
-  { term: 'redo', weight: 0.6, source: 'seed', addedAt: '' },
-  { term: 'try again', weight: 0.4, source: 'seed', addedAt: '' },
-  { term: 'again', weight: 0.3, source: 'seed', addedAt: '' },
-  { term: 'please redo', weight: 0.6, source: 'seed', addedAt: '' },
-  { term: 'please try again', weight: 0.5, source: 'seed', addedAt: '' },
-];
+import type {
+  CorrectionKeyword,
+  CorrectionKeywordStore,
+  CorrectionMatchResult,
+} from '@principles/core/runtime-v2';
+
+export type {
+  CorrectionKeyword,
+  CorrectionKeywordStore,
+  CorrectionMatchResult,
+};
+
+export {
+  MAX_CORRECTION_KEYWORDS,
+  CORRECTION_SEED_KEYWORDS,
+} from '@principles/core/runtime-v2';

package/src/core/dictionary.ts

@@ -1,7 +1,7 @@
  
 import * as fs from 'fs';
 import * as path from 'path';
-import { atomicWriteFileSync } from '../utils/io.js';
+import { JsonFileStore } from './file-store.js';
 
 export type RuleType = 'regex' | 'exact_match';
 
@@ -64,25 +64,31 @@ const DEFAULT_RULES: Record<string, PainRule> = {
 
 export class PainDictionary {
     private data: PainDictionaryData = { rules: {} };
-    private readonly filePath: string;
+    private readonly store: JsonFileStore<PainDictionaryData>;
     private readonly compiledRegex: Map<string, RegExp> = new Map();
 
     constructor(private readonly stateDir: string) {
-        this.filePath = path.join(stateDir, 'pain_dictionary.json');
+        const filePath = path.join(stateDir, 'pain_dictionary.json');
+        this.store = new JsonFileStore<PainDictionaryData>(filePath, () => ({ rules: { ...DEFAULT_RULES } }));
     }
 
     load(): void {
-        if (fs.existsSync(this.filePath)) {
-            try {
-                this.data = JSON.parse(fs.readFileSync(this.filePath, 'utf8'));
-            } catch {
-                console.error('[PD] Failed to parse pain_dictionary.json, using defaults.');
-                this.data = { rules: { ...DEFAULT_RULES } };
-            }
+        const filePath = path.join(this.stateDir, 'pain_dictionary.json');
+        const fileExisted = fs.existsSync(filePath);
+        const loaded = this.store.load();
+        // Check if we got real data (has at least one rule from file) or just defaults
+        const hasRules = loaded.rules && Object.keys(loaded.rules).length > 0;
+        if (hasRules) {
+            this.data = loaded;
         } else {
             this.data = { rules: { ...DEFAULT_RULES } };
-            console.log(`[PD:Dictionary] Dictionary not found at ${this.filePath}, creating with default rules`);
-            this.flush();
+            // Only overwrite if file didn't previously exist — preserve corrupt files
+            if (!fileExisted) {
+                console.log(`[PD:Dictionary] Dictionary not found, creating with default rules`);
+                this.flush();
+            } else {
+                console.warn(`[PD:Dictionary] Dictionary corrupt or empty, preserving file and using defaults`);
+            }
         }
         this.compile();
     }
@@ -152,14 +158,7 @@ export class PainDictionary {
     }
 
     flush(): void {
-        try {
-            if (!fs.existsSync(this.stateDir)) {
-                fs.mkdirSync(this.stateDir, { recursive: true });
-            }
-            atomicWriteFileSync(this.filePath, JSON.stringify(this.data, null, 2));
-        } catch (e) {
-            console.error('[PD] Failed to flush pain_dictionary.json:', e);
-        }
+        this.store.save(this.data);
     }
 
     getStats(): { totalRules: number; totalHits: number } {