@devflow-tools/database 0.16.0 → 0.16.3

package/src/database.ts

@@ -71,6 +71,33 @@ export interface GovernanceAuditRecord {
   signature: string;
 }
 
+const CONTEXT_REQUIRED_SKILLS = new Set([
+  'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
+]);
+
+function toolNameMatches(event: any, expected: string): boolean {
+  if (event.blocked || event.error) return false;
+  const name = String(event.mcpToolName ?? event.toolName ?? '')
+    .replace(/^mcp__[^_]+__/, '');
+  return name === expected;
+}
+
+function obligationsForSkill(skillName: string, configured: unknown): string[] {
+  const configuredTools = Array.isArray(configured)
+    ? configured.filter((tool): tool is string => typeof tool === 'string' && tool.length > 0)
+    : [];
+  const family = skillName.split(':').pop() ?? skillName;
+  if (CONTEXT_REQUIRED_SKILLS.has(family)) {
+    return [`${family}:context`, `${family}:domain`];
+  }
+  if (family === 'context') return ['get_project_context'];
+  if (family === 'graph') return ['get_dependency_graph'];
+  if (family === 'knowledge') return ['get_knowledge'];
+  if (family === 'memory') return ['get_memory'];
+  if (family === 'workflow') return ['run_workflow'];
+  return configuredTools.slice(0, 1);
+}
+
 export interface HookReceiptRecord {
   projectRoot: string;
   lastMcpCall?: number;
@@ -78,6 +105,15 @@ export interface HookReceiptRecord {
   updatedAt: number;
 }
 
+export interface ContextReceiptRecord {
+  projectRoot: string;
+  sessionId: string;
+  executionId: string;
+  contextHash: string;
+  issuedAt: number;
+  expiresAt: number;
+}
+
 export interface MemoryDistillCheckpointRecord {
   id: string;
   projectRoot: string;
@@ -225,7 +261,8 @@ export class DevFlowDatabase {
         error TEXT,
         blocked INTEGER DEFAULT 0 CHECK (blocked IN (0, 1)),
         block_reason TEXT,
-        failure_category TEXT
+        failure_category TEXT,
+        tool_use_id TEXT
       );
 
       CREATE INDEX IF NOT EXISTS idx_executions_skill ON skill_executions(skill_name);
@@ -248,7 +285,8 @@ export class DevFlowDatabase {
         mcp_tool_calls INTEGER DEFAULT 0,
         direct_tool_calls INTEGER DEFAULT 0,
         subagent_count INTEGER DEFAULT 0,
-        status TEXT NOT NULL DEFAULT 'running' CHECK (status IN ('running', 'completed', 'failed'))
+        status TEXT NOT NULL DEFAULT 'running' CHECK (status IN ('running', 'completed', 'failed')),
+        metadata TEXT
       );
 
       CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_root);
@@ -315,6 +353,19 @@ export class DevFlowDatabase {
         updated_at INTEGER NOT NULL
       );
 
+      CREATE TABLE IF NOT EXISTS devflow_context_receipts (
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        execution_id TEXT NOT NULL,
+        context_hash TEXT NOT NULL,
+        issued_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL,
+        PRIMARY KEY (project_root, session_id, execution_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_context_receipts_expiry
+        ON devflow_context_receipts(expires_at);
+
       CREATE TABLE IF NOT EXISTS devflow_memory_distill_checkpoints (
         id TEXT PRIMARY KEY,
         project_root TEXT NOT NULL,
@@ -340,6 +391,13 @@ export class DevFlowDatabase {
     // Migration: workflow run persistence
     try { this.db.exec('ALTER TABLE tool_call_events ADD COLUMN workflow_run_id TEXT'); } catch {}
     try { this.db.exec('ALTER TABLE tool_call_events ADD COLUMN failure_category TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE tool_call_events ADD COLUMN tool_use_id TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE sessions ADD COLUMN metadata TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE skill_executions ADD COLUMN metadata TEXT'); } catch {}
+    try {
+      this.db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_events_session_tool_use
+        ON tool_call_events(session_id, tool_use_id) WHERE tool_use_id IS NOT NULL`);
+    } catch {}
     try { this.db.exec('ALTER TABLE devflow_rules ADD COLUMN gate INTEGER NOT NULL DEFAULT 1'); } catch {}
     try { this.db.exec('ALTER TABLE devflow_rules ADD COLUMN updated_at INTEGER'); } catch {}
     this.db.exec('UPDATE devflow_rules SET updated_at = created_at WHERE updated_at IS NULL');
@@ -631,6 +689,27 @@ export class DevFlowDatabase {
     `).run(params.id, params.projectRoot, params.label ?? null, params.startedAt);
   }
 
+  ensureSession(params: {
+    id: string;
+    projectRoot: string;
+    label?: string;
+    startedAt?: number;
+  }): void {
+    if (!params.id.trim()) throw new Error('Canonical session ID is required');
+    const startedAt = params.startedAt ?? Date.now();
+    this.db.prepare(`
+      INSERT INTO sessions (id, project_root, label, started_at, status)
+      VALUES (?, ?, ?, ?, 'running')
+      ON CONFLICT(id) DO UPDATE SET
+        project_root = CASE
+          WHEN sessions.project_root = '' OR sessions.project_root = 'unknown' THEN excluded.project_root
+          ELSE sessions.project_root
+        END,
+        label = COALESCE(sessions.label, excluded.label),
+        started_at = MIN(sessions.started_at, excluded.started_at)
+    `).run(params.id, params.projectRoot || 'unknown', params.label ?? null, startedAt);
+  }
+
   getSession(id: string): any | null {
     const row = this.db.prepare('SELECT * FROM sessions WHERE id = ?').get(id) as any;
     if (!row) return null;
@@ -646,6 +725,7 @@ export class DevFlowDatabase {
       directToolCalls: row.direct_tool_calls,
       subagentCount: row.subagent_count,
       status: row.status,
+      metadata: row.metadata ? JSON.parse(row.metadata) : null,
     };
   }
 
@@ -672,6 +752,7 @@ export class DevFlowDatabase {
       directToolCalls: row.direct_tool_calls,
       subagentCount: row.subagent_count,
       status: row.status,
+      metadata: row.metadata ? JSON.parse(row.metadata) : null,
     }));
   }
 
@@ -739,6 +820,7 @@ export class DevFlowDatabase {
       blocked: row.blocked === 1,
       blockReason: row.block_reason,
       failureCategory: row.failure_category,
+      toolUseId: row.tool_use_id,
       tokensUsed: row.tokens_used ?? 0,
     }));
   }
@@ -775,6 +857,7 @@ export class DevFlowDatabase {
         blocked: row.blocked === 1,
         blockReason: row.block_reason,
         failureCategory: row.failure_category,
+        toolUseId: row.tool_use_id,
         tokensUsed: row.tokens_used ?? 0,
       });
     }
@@ -827,6 +910,7 @@ export class DevFlowDatabase {
       mcpComplianceRate: row.mcp_compliance_rate,
       missedMcpTools: row.missed_mcp_tools ? JSON.parse(row.missed_mcp_tools) : null,
       createdAt: row.created_at,
+      metadata: row.metadata ? JSON.parse(row.metadata) : null,
     };
   }
 
@@ -840,6 +924,7 @@ export class DevFlowDatabase {
     mcpToolCalls?: number;
     directToolCalls?: number;
     subagentCount?: number;
+    metadata?: Record<string, unknown>;
   }): void {
     const sets: string[] = [];
     const values: any[] = [];
@@ -853,6 +938,7 @@ export class DevFlowDatabase {
     if (updates.mcpToolCalls !== undefined) { sets.push('mcp_tool_calls = ?'); values.push(updates.mcpToolCalls); }
     if (updates.directToolCalls !== undefined) { sets.push('direct_tool_calls = ?'); values.push(updates.directToolCalls); }
     if (updates.subagentCount !== undefined) { sets.push('subagent_count = ?'); values.push(updates.subagentCount); }
+    if (updates.metadata !== undefined) { sets.push('metadata = ?'); values.push(JSON.stringify(updates.metadata)); }
 
     if (sets.length > 0) {
       values.push(executionId);
@@ -886,6 +972,7 @@ export class DevFlowDatabase {
       subagentCount: row.subagent_count,
       totalDuration: row.total_duration,
       mcpComplianceRate: row.mcp_compliance_rate,
+      metadata: row.metadata ? JSON.parse(row.metadata) : null,
     }));
   }
 
@@ -914,6 +1001,7 @@ export class DevFlowDatabase {
     workflowRunId?: string;
     failureCategory?: string;
     tokensUsed?: number;
+    toolUseId?: string;
   }): boolean {
     return this.db.transaction(() => {
       const result = this.db.prepare(`
@@ -921,8 +1009,8 @@ export class DevFlowDatabase {
         (event_id, execution_id, session_id, timestamp, tool_name, tool_type, is_mcp_tool,
          mcp_tool_name, mcp_enforced, mcp_fallback, kind, input, output, tokens_used, duration,
          parent_tool_call_id, subagent_id, error, blocked, block_reason, workflow_run_id,
-         failure_category)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         failure_category, tool_use_id)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `).run(
         params.eventId,
         params.executionId || '',
@@ -946,6 +1034,7 @@ export class DevFlowDatabase {
         params.blockReason || null,
         params.workflowRunId || null,
         params.failureCategory || null,
+        params.toolUseId || null,
       );
 
       if (result.changes === 0) return false;
@@ -955,14 +1044,37 @@ export class DevFlowDatabase {
         SET total_tool_calls = total_tool_calls + 1,
             mcp_tool_calls = mcp_tool_calls + ?,
             direct_tool_calls = direct_tool_calls + ?,
-            subagent_count = subagent_count + ?
+            subagent_count = subagent_count + ?,
+            total_duration = MAX(total_duration, ? - started_at),
+            mcp_compliance_rate = ROUND(
+              100.0 * (mcp_tool_calls + ?) / NULLIF(total_tool_calls + 1, 0), 2
+            )
         WHERE execution_id = ?
       `).run(
         params.isMcpTool ? 1 : 0,
         params.isMcpTool ? 0 : 1,
         params.toolType === 'subagent' ? 1 : 0,
+        params.timestamp,
+        params.isMcpTool ? 1 : 0,
         params.executionId,
       );
+      if (params.sessionId) {
+        this.db.prepare(`
+          UPDATE sessions
+          SET total_tool_calls = total_tool_calls + 1,
+              mcp_tool_calls = mcp_tool_calls + ?,
+              direct_tool_calls = direct_tool_calls + ?,
+              subagent_count = subagent_count + ?,
+              duration_ms = MAX(duration_ms, ? - started_at)
+          WHERE id = ?
+        `).run(
+          params.isMcpTool ? 1 : 0,
+          params.isMcpTool ? 0 : 1,
+          params.toolType === 'subagent' ? 1 : 0,
+          params.timestamp,
+          params.sessionId,
+        );
+      }
       return true;
     });
   }
@@ -993,6 +1105,7 @@ export class DevFlowDatabase {
       blocked: row.blocked === 1,
       blockReason: row.block_reason,
       failureCategory: row.failure_category,
+      toolUseId: row.tool_use_id,
     }));
   }
 
@@ -1023,65 +1136,147 @@ export class DevFlowDatabase {
     return false;
   }
 
+  markToolCallBlocked(eventId: string, reason: string): boolean {
+    return this.db.prepare(`
+      UPDATE tool_call_events
+      SET blocked = 1, block_reason = ?, error = COALESCE(error, ?)
+      WHERE event_id = ?
+    `).run(reason, reason, eventId).changes > 0;
+  }
+
+  reconcileSkillExecution(
+    executionId: string,
+    status: 'completed' | 'failed',
+    finishedAt = Date.now(),
+    metadata?: Record<string, unknown>,
+  ): void {
+    const row = this.db.prepare(`
+      SELECT COUNT(*) AS total,
+        SUM(CASE WHEN is_mcp_tool = 1 THEN 1 ELSE 0 END) AS mcp,
+        SUM(CASE WHEN is_mcp_tool = 0 THEN 1 ELSE 0 END) AS direct,
+        SUM(CASE WHEN tool_type = 'subagent' THEN 1 ELSE 0 END) AS subagents,
+        MIN(timestamp) AS first_at,
+        MAX(timestamp) AS last_at
+      FROM tool_call_events WHERE execution_id = ?
+    `).get(executionId) as any;
+    const total = Number(row?.total ?? 0);
+    const mcp = Number(row?.mcp ?? 0);
+    const obligation = this.getExecutionObligationCompliance(executionId);
+    this.updateSkillExecution(executionId, {
+      status,
+      finishedAt,
+      totalToolCalls: total,
+      mcpToolCalls: mcp,
+      directToolCalls: Number(row?.direct ?? 0),
+      subagentCount: Number(row?.subagents ?? 0),
+      totalDuration: row?.first_at != null && row?.last_at != null ? row.last_at - row.first_at : 0,
+      mcpComplianceRate: obligation.rate,
+      metadata,
+    });
+  }
+
+  getExecutionObligationCompliance(executionId: string): {
+    rate: number;
+    applicable: number;
+    satisfied: number;
+    missedTools: string[];
+    mcpCallShare: number;
+  } {
+    const execution = this.getSkillExecution(executionId);
+    const events = this.listToolCallEvents(executionId);
+    if (!execution) {
+      return { rate: 0, applicable: 0, satisfied: 0, missedTools: [], mcpCallShare: 0 };
+    }
+    const obligations = obligationsForSkill(execution.skillName, execution.requiredMcpTools);
+    const satisfied = obligations.filter((obligation) => {
+      if (obligation.endsWith(':context')) {
+        return events.some((event) => toolNameMatches(event, 'get_project_context'));
+      }
+      if (obligation.endsWith(':domain')) {
+        const family = obligation.slice(0, -':domain'.length);
+        return events.some((event) => {
+          if (event.blocked || event.error || !event.isMcpTool) return false;
+          const name = String(event.mcpToolName ?? event.toolName ?? '')
+            .replace(/^mcp__[^_]+__/, '');
+          return name.startsWith(`${family}_`);
+        });
+      }
+      return events.some((event) => toolNameMatches(event, obligation));
+    });
+    const missedTools = obligations.filter((obligation) => !satisfied.includes(obligation));
+    const total = events.length;
+    const mcp = events.filter((event) => event.isMcpTool).length;
+    return {
+      rate: obligations.length > 0
+        ? Math.round((satisfied.length / obligations.length) * 10000) / 100
+        : 0,
+      applicable: obligations.length,
+      satisfied: satisfied.length,
+      missedTools,
+      mcpCallShare: total > 0 ? Math.round((mcp / total) * 10000) / 100 : 0,
+    };
+  }
+
   // ---- MCP Compliance ----
 
   getMcpCompliance(): {
     overall: number;
     bySkill: Record<string, number>;
     missedTools: string[];
+    applicableObligations: number;
+    satisfiedObligations: number;
+    mcpCallShare: number;
   } {
-    // Overall compliance (include all executions, not just completed)
-    const overallRow = this.db.prepare(`
-      SELECT
-        SUM(mcp_tool_calls) as mcp_calls,
-        SUM(total_tool_calls) as total_calls
-      FROM skill_executions
-    `).get() as any;
-
-    const overall = overallRow?.total_calls > 0
-      ? Math.round((overallRow.mcp_calls / overallRow.total_calls) * 10000) / 100
-      : 0;
-
-    // By skill
-    const bySkillRows = this.db.prepare(`
-      SELECT
-        skill_name,
-        SUM(mcp_tool_calls) as mcp_calls,
-        SUM(total_tool_calls) as total_calls
-      FROM skill_executions
-      GROUP BY skill_name
-    `).all() as any[];
-
+    const executions = this.db.prepare('SELECT execution_id, skill_name FROM skill_executions').all() as any[];
     const bySkill: Record<string, number> = {};
-    for (const row of bySkillRows) {
-      bySkill[row.skill_name] = row.total_calls > 0
-        ? Math.round((row.mcp_calls / row.total_calls) * 10000) / 100
+    const bySkillCounts = new Map<string, { applicable: number; satisfied: number }>();
+    let applicableObligations = 0;
+    let satisfiedObligations = 0;
+    let totalCalls = 0;
+    let mcpCalls = 0;
+    const missedTools = new Set<string>();
+    for (const execution of executions) {
+      const result = this.getExecutionObligationCompliance(execution.execution_id);
+      const skill = String(execution.skill_name ?? 'unknown');
+      const skillCounts = bySkillCounts.get(skill) ?? { applicable: 0, satisfied: 0 };
+      skillCounts.applicable += result.applicable;
+      skillCounts.satisfied += result.satisfied;
+      bySkillCounts.set(skill, skillCounts);
+      applicableObligations += result.applicable;
+      satisfiedObligations += result.satisfied;
+      result.missedTools.forEach((tool) => missedTools.add(tool));
+      const events = this.listToolCallEvents(execution.execution_id);
+      totalCalls += events.length;
+      mcpCalls += events.filter((event) => event.isMcpTool).length;
+    }
+    for (const [skill, counts] of bySkillCounts) {
+      bySkill[skill] = counts.applicable > 0
+        ? Math.round((counts.satisfied / counts.applicable) * 10000) / 100
         : 0;
     }
-
-    // Missed tools: tools that were required but fell back to direct
-    const missedRows = this.db.prepare(`
-      SELECT DISTINCT mcp_tool_name
-      FROM tool_call_events
-      WHERE mcp_fallback = 1 AND mcp_tool_name IS NOT NULL
-      ORDER BY timestamp DESC
-      LIMIT 10
-    `).all() as any[];
-
-    const missedTools = missedRows.map((row: any) => row.mcp_tool_name);
-
-    return { overall, bySkill, missedTools };
+    return {
+      overall: applicableObligations > 0
+        ? Math.round((satisfiedObligations / applicableObligations) * 10000) / 100
+        : 0,
+      bySkill,
+      missedTools: [...missedTools].slice(0, 10),
+      applicableObligations,
+      satisfiedObligations,
+      mcpCallShare: totalCalls > 0 ? Math.round((mcpCalls / totalCalls) * 10000) / 100 : 0,
+    };
   }
 
   cleanupStaleRecords(): void {
     const cutoff = Date.now() - 30 * 60 * 1000;
     try {
       this.db.prepare(
-        `UPDATE skill_executions SET status = 'failed', finished_at = ? WHERE status = 'running' AND started_at < ?`
-      ).run(Date.now(), cutoff);
+        `UPDATE skill_executions SET status = 'failed', finished_at = ?, metadata = ?
+         WHERE status = 'running' AND started_at < ?`
+      ).run(Date.now(), JSON.stringify({ closureReason: 'abandoned' }), cutoff);
       this.db.prepare(
-        `UPDATE sessions SET status = 'failed', finished_at = ? WHERE status = 'running' AND started_at < ?`
-      ).run(Date.now(), cutoff);
+        `UPDATE sessions SET status = 'failed', finished_at = ?, metadata = ?
+         WHERE status = 'running' AND started_at < ?`
+      ).run(Date.now(), JSON.stringify({ closureReason: 'abandoned' }), cutoff);
     } catch { /* best-effort */ }
   }
 
@@ -1581,6 +1776,60 @@ export class DevFlowDatabase {
       .run(projectRoot).changes > 0;
   }
 
+  upsertContextReceipt(receipt: ContextReceiptRecord): void {
+    this.db.prepare(`
+      INSERT INTO devflow_context_receipts
+        (project_root, session_id, execution_id, context_hash, issued_at, expires_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_root, session_id, execution_id) DO UPDATE SET
+        context_hash = excluded.context_hash,
+        issued_at = excluded.issued_at,
+        expires_at = excluded.expires_at
+    `).run(
+      receipt.projectRoot,
+      receipt.sessionId,
+      receipt.executionId,
+      receipt.contextHash,
+      receipt.issuedAt,
+      receipt.expiresAt,
+    );
+  }
+
+  getContextReceipt(
+    projectRoot: string,
+    sessionId: string,
+    executionId: string,
+  ): ContextReceiptRecord | null {
+    const row = this.db.prepare(`
+      SELECT project_root, session_id, execution_id, context_hash, issued_at, expires_at
+      FROM devflow_context_receipts
+      WHERE project_root = ? AND session_id = ? AND execution_id = ?
+    `).get(projectRoot, sessionId, executionId) as any;
+    return row ? {
+      projectRoot: row.project_root,
+      sessionId: row.session_id,
+      executionId: row.execution_id,
+      contextHash: row.context_hash,
+      issuedAt: row.issued_at,
+      expiresAt: row.expires_at,
+    } : null;
+  }
+
+  deleteContextReceipt(projectRoot: string, sessionId: string, executionId?: string): number {
+    return executionId
+      ? this.db.prepare(`DELETE FROM devflow_context_receipts
+          WHERE project_root = ? AND session_id = ? AND execution_id = ?`)
+          .run(projectRoot, sessionId, executionId).changes
+      : this.db.prepare(`DELETE FROM devflow_context_receipts
+          WHERE project_root = ? AND session_id = ?`)
+          .run(projectRoot, sessionId).changes;
+  }
+
+  purgeExpiredContextReceipts(now = Date.now()): number {
+    return this.db.prepare('DELETE FROM devflow_context_receipts WHERE expires_at <= ?')
+      .run(now).changes;
+  }
+
   recordMemoryDistillCheckpoint(checkpoint: MemoryDistillCheckpointRecord): void {
     this.db.prepare(`
       INSERT INTO devflow_memory_distill_checkpoints