principles-disciple 1.8.0 → 1.8.2

package/src/core/control-ui-db.ts

@@ -0,0 +1,435 @@
+import Database from 'better-sqlite3';
+import fs from 'fs';
+import path from 'path';
+import { withLock } from '../utils/file-lock.js';
+import { resolvePdPath } from './paths.js';
+
+/**
+ * Control UI database stores ANALYTICS READ MODELS.
+ *
+ * PURPOSE: Aggregated data for dashboard visualization and historical insights.
+ * USAGE: Control UI queries and dashboard displays.
+ * NOT FOR: Control decisions, Phase 3 eligibility, or real-time operations.
+ *
+ * Runtime truth comes from: queue state, workspace trust scorecard, active sessions
+ */
+
+export interface ThinkingModelEventInput {
+  sessionId: string;
+  runId: string;
+  assistantTurnId: number;
+  modelId: string;
+  matchedPattern: string;
+  scenarioJson: unknown;
+  toolContextJson: unknown;
+  painContextJson: unknown;
+  principleContextJson: unknown;
+  triggerExcerpt: string;
+  createdAt: string;
+}
+
+export interface ControlUiDatabaseOptions {
+  workspaceDir: string;
+  busyTimeoutMs?: number;
+}
+
+export interface RecentThinkingContext {
+  toolCalls: Array<{
+    id: number;
+    toolName: string;
+    outcome: 'success' | 'failure' | 'blocked';
+    errorType: string | null;
+    errorMessage: string | null;
+    createdAt: string;
+  }>;
+  painEvents: Array<{
+    id: number;
+    source: string;
+    score: number;
+    reason: string | null;
+    createdAt: string;
+  }>;
+  gateBlocks: Array<{
+    id: number;
+    toolName: string;
+    reason: string;
+    filePath: string | null;
+    createdAt: string;
+  }>;
+  userCorrections: Array<{
+    id: number;
+    correctionCue: string | null;
+    rawExcerpt: string | null;
+    createdAt: string;
+  }>;
+  principleEvents: Array<{
+    id: number;
+    principleId: string | null;
+    eventType: string;
+    createdAt: string;
+  }>;
+}
+
+const DEFAULT_BUSY_TIMEOUT_MS = 5000;
+
+function safeJson(value: unknown): string {
+  return JSON.stringify(value ?? []);
+}
+
+export class ControlUiDatabase {
+  private readonly workspaceDir: string;
+  private readonly dbPath: string;
+  private readonly blobDir: string;
+  private readonly db: Database.Database;
+
+  constructor(opts: ControlUiDatabaseOptions) {
+    this.workspaceDir = path.resolve(opts.workspaceDir);
+    this.dbPath = resolvePdPath(this.workspaceDir, 'TRAJECTORY_DB');
+    this.blobDir = resolvePdPath(this.workspaceDir, 'TRAJECTORY_BLOBS_DIR');
+
+    fs.mkdirSync(path.dirname(this.dbPath), { recursive: true });
+    fs.mkdirSync(this.blobDir, { recursive: true });
+
+    this.db = new Database(this.dbPath);
+    this.db.pragma('journal_mode = WAL');
+    this.db.pragma('foreign_keys = ON');
+    this.db.pragma('synchronous = NORMAL');
+    this.db.pragma(`busy_timeout = ${Math.max(0, opts.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS)}`);
+    this.initSchema();
+  }
+
+  dispose(): void {
+    this.db.close();
+  }
+
+  recordThinkingModelEvent(input: ThinkingModelEventInput): number {
+    return this.withWrite(() => {
+      const result = this.db.prepare(`
+        INSERT INTO thinking_model_events (
+          session_id, run_id, assistant_turn_id, model_id, matched_pattern, scenario_json,
+          tool_context_json, pain_context_json, principle_context_json, trigger_excerpt, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        input.sessionId,
+        input.runId,
+        input.assistantTurnId,
+        input.modelId,
+        input.matchedPattern,
+        safeJson(input.scenarioJson),
+        safeJson(input.toolContextJson),
+        safeJson(input.painContextJson),
+        safeJson(input.principleContextJson),
+        input.triggerExcerpt,
+        input.createdAt,
+      );
+      return Number(result.lastInsertRowid);
+    });
+  }
+
+  /**
+   * Get recent thinking context for a session.
+   *
+   * Returns: Analytics data (read model) aggregated from trajectory database.
+   * Not: Runtime truth or real-time queue state.
+   */
+  getRecentThinkingContext(sessionId: string, beforeCreatedAt: string, limit = 5): RecentThinkingContext {
+    return {
+      toolCalls: this.all<{
+        id: number;
+        tool_name: string;
+        outcome: 'success' | 'failure' | 'blocked';
+        error_type: string | null;
+        error_message: string | null;
+        created_at: string;
+      }>(
+        `
+          SELECT id, tool_name, outcome, error_type, error_message, created_at
+          FROM tool_calls
+          WHERE session_id = ? AND created_at <= ?
+          ORDER BY created_at DESC
+          LIMIT ?
+        `,
+        sessionId,
+        beforeCreatedAt,
+        limit,
+      ).map((row) => ({
+        id: Number(row.id),
+        toolName: String(row.tool_name),
+        outcome: row.outcome,
+        errorType: row.error_type,
+        errorMessage: row.error_message,
+        createdAt: String(row.created_at),
+      })),
+      painEvents: this.all<{
+        id: number;
+        source: string;
+        score: number;
+        reason: string | null;
+        created_at: string;
+      }>(
+        `
+          SELECT id, source, score, reason, created_at
+          FROM pain_events
+          WHERE session_id = ? AND created_at <= ?
+          ORDER BY created_at DESC
+          LIMIT ?
+        `,
+        sessionId,
+        beforeCreatedAt,
+        limit,
+      ).map((row) => ({
+        id: Number(row.id),
+        source: String(row.source),
+        score: Number(row.score),
+        reason: row.reason,
+        createdAt: String(row.created_at),
+      })),
+      gateBlocks: this.all<{
+        id: number;
+        tool_name: string;
+        reason: string;
+        file_path: string | null;
+        created_at: string;
+      }>(
+        `
+          SELECT id, tool_name, reason, file_path, created_at
+          FROM gate_blocks
+          WHERE session_id = ? AND created_at <= ?
+          ORDER BY created_at DESC
+          LIMIT ?
+        `,
+        sessionId,
+        beforeCreatedAt,
+        limit,
+      ).map((row) => ({
+        id: Number(row.id),
+        toolName: String(row.tool_name),
+        reason: String(row.reason),
+        filePath: row.file_path,
+        createdAt: String(row.created_at),
+      })),
+      userCorrections: this.all<{
+        id: number;
+        correction_cue: string | null;
+        raw_excerpt: string | null;
+        created_at: string;
+      }>(
+        `
+          SELECT id, correction_cue, raw_excerpt, created_at
+          FROM user_turns
+          WHERE session_id = ? AND correction_detected = 1 AND created_at <= ?
+          ORDER BY created_at DESC
+          LIMIT ?
+        `,
+        sessionId,
+        beforeCreatedAt,
+        limit,
+      ).map((row) => ({
+        id: Number(row.id),
+        correctionCue: row.correction_cue,
+        rawExcerpt: row.raw_excerpt,
+        createdAt: String(row.created_at),
+      })),
+      principleEvents: this.all<{
+        id: number;
+        principle_id: string | null;
+        event_type: string;
+        created_at: string;
+      }>(
+        `
+          SELECT id, principle_id, event_type, created_at
+          FROM principle_events
+          WHERE created_at <= ?
+          ORDER BY created_at DESC
+          LIMIT ?
+        `,
+        beforeCreatedAt,
+        limit,
+      ).map((row) => ({
+        id: Number(row.id),
+        principleId: row.principle_id,
+        eventType: String(row.event_type),
+        createdAt: String(row.created_at),
+      })),
+    };
+  }
+
+  /**
+   * Execute SQL query and return all rows.
+   *
+   * Returns: Analytics data (read model) aggregated from trajectory database.
+   * Not: Runtime truth or real-time queue state.
+   */
+  all<T>(sql: string, ...params: unknown[]): T[] {
+    return this.db.prepare(sql).all(...params) as T[];
+  }
+
+  /**
+   * Execute SQL query and return first row.
+   *
+   * Returns: Analytics data (read model) aggregated from trajectory database.
+   * Not: Runtime truth or real-time queue state.
+   */
+  get<T>(sql: string, ...params: unknown[]): T | undefined {
+    return this.db.prepare(sql).get(...params) as T | undefined;
+  }
+
+  restoreRawText(inlineText?: string | null, blobRef?: string | null): string {
+    if (inlineText) return inlineText;
+    if (!blobRef) return '';
+    const fullPath = path.join(this.blobDir, blobRef);
+    return fs.existsSync(fullPath) ? fs.readFileSync(fullPath, 'utf8') : '';
+  }
+
+  private initSchema(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS thinking_model_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL,
+        run_id TEXT NOT NULL,
+        assistant_turn_id INTEGER NOT NULL,
+        model_id TEXT NOT NULL,
+        matched_pattern TEXT NOT NULL,
+        scenario_json TEXT NOT NULL,
+        tool_context_json TEXT NOT NULL,
+        pain_context_json TEXT NOT NULL,
+        principle_context_json TEXT NOT NULL,
+        trigger_excerpt TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_thinking_model_events_model_created
+        ON thinking_model_events(model_id, created_at);
+      CREATE INDEX IF NOT EXISTS idx_thinking_model_events_session_created
+        ON thinking_model_events(session_id, created_at);
+      CREATE INDEX IF NOT EXISTS idx_thinking_model_events_assistant_turn
+        ON thinking_model_events(assistant_turn_id);
+      CREATE INDEX IF NOT EXISTS idx_thinking_model_events_run_id
+        ON thinking_model_events(run_id);
+
+      DROP VIEW IF EXISTS v_thinking_model_usage;
+      CREATE VIEW v_thinking_model_usage AS
+      WITH totals AS (
+        SELECT COUNT(*) AS assistant_turns FROM assistant_turns
+      ),
+      usage_rows AS (
+        SELECT
+          model_id,
+          COUNT(*) AS hits,
+          COUNT(DISTINCT session_id) AS distinct_sessions,
+          COUNT(DISTINCT assistant_turn_id) AS distinct_turns
+        FROM thinking_model_events
+        GROUP BY model_id
+      )
+      SELECT
+        usage_rows.model_id AS model_id,
+        usage_rows.hits AS hits,
+        usage_rows.distinct_sessions AS distinct_sessions,
+        usage_rows.distinct_turns AS distinct_turns,
+        CASE
+          WHEN totals.assistant_turns = 0 THEN 0
+          ELSE ROUND(CAST(usage_rows.distinct_turns AS REAL) / CAST(totals.assistant_turns AS REAL), 4)
+        END AS coverage_rate
+      FROM usage_rows, totals
+      ORDER BY usage_rows.hits DESC, usage_rows.model_id ASC;
+
+      DROP VIEW IF EXISTS v_thinking_model_effectiveness;
+      CREATE VIEW v_thinking_model_effectiveness AS
+      WITH event_windows AS (
+        SELECT
+          e.id,
+          e.session_id,
+          e.model_id,
+          e.created_at,
+          (
+            SELECT MIN(a.created_at)
+            FROM assistant_turns a
+            WHERE a.session_id = e.session_id AND a.created_at > e.created_at
+          ) AS next_assistant_at,
+          datetime(e.created_at, '+10 minutes') AS max_window_end
+        FROM thinking_model_events e
+      ),
+      bounded_windows AS (
+        SELECT
+          id,
+          session_id,
+          model_id,
+          created_at,
+          CASE
+            WHEN next_assistant_at IS NULL THEN max_window_end
+            WHEN next_assistant_at < max_window_end THEN next_assistant_at
+            ELSE max_window_end
+          END AS window_end
+        FROM event_windows
+      )
+      SELECT
+        b.model_id AS model_id,
+        COUNT(*) AS events,
+        SUM(CASE WHEN EXISTS (
+          SELECT 1 FROM tool_calls t
+          WHERE t.session_id = b.session_id
+            AND t.created_at > b.created_at
+            AND t.created_at <= b.window_end
+            AND t.outcome = 'success'
+        ) THEN 1 ELSE 0 END) AS success_windows,
+        SUM(CASE WHEN EXISTS (
+          SELECT 1 FROM tool_calls t
+          WHERE t.session_id = b.session_id
+            AND t.created_at > b.created_at
+            AND t.created_at <= b.window_end
+            AND t.outcome = 'failure'
+        ) THEN 1 ELSE 0 END) AS failure_windows,
+        SUM(CASE WHEN EXISTS (
+          SELECT 1 FROM pain_events p
+          WHERE p.session_id = b.session_id
+            AND p.created_at > b.created_at
+            AND p.created_at <= b.window_end
+        ) THEN 1 ELSE 0 END) AS pain_windows,
+        SUM(CASE WHEN EXISTS (
+          SELECT 1 FROM user_turns u
+          WHERE u.session_id = b.session_id
+            AND u.created_at > b.created_at
+            AND u.created_at <= b.window_end
+            AND u.correction_detected = 1
+        ) THEN 1 ELSE 0 END) AS correction_windows,
+        SUM(CASE WHEN EXISTS (
+          SELECT 1 FROM correction_samples c
+          WHERE c.session_id = b.session_id
+            AND c.created_at > b.created_at
+            AND c.created_at <= b.window_end
+        ) THEN 1 ELSE 0 END) AS correction_sample_windows
+      FROM bounded_windows b
+      GROUP BY b.model_id
+      ORDER BY events DESC, model_id ASC;
+
+      DROP VIEW IF EXISTS v_thinking_model_scenarios;
+      CREATE VIEW v_thinking_model_scenarios AS
+      SELECT
+        e.model_id AS model_id,
+        CAST(j.value AS TEXT) AS scenario,
+        COUNT(*) AS hits
+      FROM thinking_model_events e
+      JOIN json_each(
+        CASE
+          WHEN json_valid(e.scenario_json) THEN e.scenario_json
+          ELSE '[]'
+        END
+      ) AS j
+      GROUP BY e.model_id, CAST(j.value AS TEXT)
+      ORDER BY hits DESC, scenario ASC;
+
+      DROP VIEW IF EXISTS v_thinking_model_daily_trend;
+      CREATE VIEW v_thinking_model_daily_trend AS
+      SELECT
+        substr(created_at, 1, 10) AS day,
+        model_id,
+        COUNT(*) AS hits
+      FROM thinking_model_events
+      GROUP BY substr(created_at, 1, 10), model_id
+      ORDER BY day ASC, model_id ASC;
+    `);
+  }
+
+  private withWrite<T>(fn: () => T): T {
+    return withLock(this.dbPath, fn, { lockSuffix: '.trajectory.lock', lockStaleMs: 30000 });
+  }
+}

package/{dist/core/detection-funnel.js → src/core/detection-funnel.ts}

@@ -1,16 +1,23 @@
 import { createHash } from 'crypto';
-import { shouldIgnorePainProtocolText } from './dictionary.js';
+import { shouldIgnorePainProtocolText, type PainDictionary } from './dictionary.js';
+
+export interface DetectionResult {
+    detected: boolean;
+    severity?: number;
+    ruleId?: string;
+    source: 'l1_exact' | 'l2_cache' | 'l3_async_queued' | 'l3_semantic_hit';
+}
+
 /**
  * A simple LRU Cache implementation using Map.
  */
-class SimpleLRU {
-    maxSize;
-    cache;
-    constructor(maxSize = 100) {
-        this.maxSize = maxSize;
+class SimpleLRU<K, V> {
+    private cache: Map<K, V>;
+    constructor(private maxSize: number = 100) {
         this.cache = new Map();
     }
-    get(key) {
+
+    get(key: K): V | undefined {
         const item = this.cache.get(key);
         if (item !== undefined) {
             // Refresh: delete and re-insert
@@ -19,11 +26,11 @@ class SimpleLRU {
         }
         return item;
     }
-    set(key, value) {
+
+    set(key: K, value: V): void {
         if (this.cache.has(key)) {
             this.cache.delete(key);
-        }
-        else if (this.cache.size >= this.maxSize) {
+        } else if (this.cache.size >= this.maxSize) {
             // Remove the oldest (first) item
             const firstKey = this.cache.keys().next().value;
             if (firstKey !== undefined) {
@@ -33,23 +40,24 @@ class SimpleLRU {
         this.cache.set(key, value);
     }
 }
+
 /**
  * Orchestrates the three-layer detection funnel for pain signals.
  */
 export class DetectionFunnel {
-    dictionary;
-    cache = new SimpleLRU(100);
-    asyncQueue = [];
-    constructor(dictionary) {
-        this.dictionary = dictionary;
-    }
+    private cache = new SimpleLRU<string, { detected: boolean; severity?: number }>(100);
+    private asyncQueue: string[] = [];
+
+    constructor(private dictionary: PainDictionary) {}
+
     /**
      * Detects pain in the given text using L1 (Exact), L2 (Cache), and L3 (Async).
      */
-    detect(text) {
+    detect(text: string): DetectionResult {
         if (shouldIgnorePainProtocolText(text)) {
             return { detected: false, source: 'l1_exact' };
         }
+
         // --- Layer 1: Exact Match (Sync) ---
         const exactMatch = this.dictionary.match(text);
         if (exactMatch) {
@@ -60,6 +68,7 @@ export class DetectionFunnel {
                 source: 'l1_exact'
             };
         }
+
         // --- Layer 2: LRU Cache (Sync) ---
         const hash = this.computeHash(text);
         const cached = this.cache.get(hash);
@@ -70,33 +79,39 @@ export class DetectionFunnel {
                 source: 'l2_cache'
             };
         }
+
         // --- Layer 3: Async Semantic Queue ---
         this.enqueueAsync(text);
+        
         return {
             detected: false,
             source: 'l3_async_queued'
         };
     }
-    computeHash(text) {
+
+    private computeHash(text: string): string {
         return createHash('sha256').update(text).digest('hex');
     }
-    enqueueAsync(text) {
+
+    private enqueueAsync(text: string): void {
         if (this.asyncQueue.length < 1000) {
             this.asyncQueue.push(text);
         }
         // Worker will pick this up and perform semantic search via createMemorySearchTool
     }
+
     /**
      * Internal method for the worker to update the cache after a semantic hit.
      */
-    updateCache(text, result) {
+    updateCache(text: string, result: { detected: boolean; severity?: number }): void {
         const hash = this.computeHash(text);
         this.cache.set(hash, result);
     }
+
     /**
      * Retrieves and clears the current asynchronous queue.
      */
-    flushQueue() {
+    flushQueue(): string[] {
         const queue = [...this.asyncQueue];
         this.asyncQueue = [];
         return queue;

package/{dist/core/detection-service.js → src/core/detection-service.ts}

@@ -1,7 +1,9 @@
 import { DetectionFunnel } from './detection-funnel.js';
 import { DictionaryService } from './dictionary-service.js';
-let instance = null;
-let lastStateDir = null;
+
+let instance: DetectionFunnel | null = null;
+let lastStateDir: string | null = null;
+
 /**
  * Singleton service to manage the Semantic Detection Funnel.
  */
@@ -10,7 +12,7 @@ export const DetectionService = {
      * Gets or initializes the Detection Funnel instance.
      * @param stateDir The directory used to initialize the dictionary.
      */
-    get(stateDir) {
+    get(stateDir: string): DetectionFunnel {
         if (!instance || lastStateDir !== stateDir) {
             const dictionary = DictionaryService.get(stateDir);
             instance = new DetectionFunnel(dictionary);
@@ -18,10 +20,11 @@ export const DetectionService = {
         }
         return instance;
     },
+
     /**
      * Resets the singleton instance (primarily for testing).
      */
-    reset() {
+    reset(): void {
         instance = null;
         lastStateDir = null;
     }

package/{dist/core/dictionary-service.js → src/core/dictionary-service.ts}

@@ -1,6 +1,8 @@
 import { PainDictionary } from './dictionary.js';
-let dictionary = null;
-let lastStateDir = null;
+
+let dictionary: PainDictionary | null = null;
+let lastStateDir: string | null = null;
+
 /**
  * Singleton service to manage the Pain Dictionary.
  */
@@ -9,7 +11,7 @@ export const DictionaryService = {
      * Gets or initializes the Pain Dictionary instance.
      * @param stateDir The directory where the dictionary JSON is stored.
      */
-    get(stateDir) {
+    get(stateDir: string): PainDictionary {
         if (!dictionary || lastStateDir !== stateDir) {
             dictionary = new PainDictionary(stateDir);
             dictionary.load();
@@ -17,10 +19,11 @@ export const DictionaryService = {
         }
         return dictionary;
     },
+
     /**
      * Resets the singleton instance (primarily for testing).
      */
-    reset() {
+    reset(): void {
         dictionary = null;
     }
 };