@rigour-labs/core 5.2.8 → 5.3.0

package/dist/storage/context-telemetry.d.ts

@@ -0,0 +1,83 @@
+export interface ContextEvent {
+    id?: string;
+    taskId?: string;
+    sessionId?: string;
+    agentId?: string;
+    toolName: string;
+    queryHash?: string;
+    cacheStatus: 'exact-hit' | 'semantic-hit' | 'partial-hit' | 'miss' | 'none';
+    candidateTokens: number;
+    returnedTokens: number;
+    deduplicatedTokens?: number;
+    candidateFiles?: number;
+    returnedFiles?: number;
+    createdAt?: number;
+}
+export interface ModelUsage {
+    id?: string;
+    taskId?: string;
+    sessionId?: string;
+    agentId?: string;
+    provider?: string;
+    model?: string;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens?: number;
+    observedCostUsd?: number;
+    source: string;
+    createdAt?: number;
+}
+export interface ContextCacheRecord {
+    cacheKey: string;
+    cacheType: 'static' | 'component' | 'semantic' | 'checkpoint';
+    repo: string;
+    branch: string;
+    commitSha?: string;
+    dependencyFingerprint: string;
+    payloadJson: string;
+    payloadTokens: number;
+    hitCount?: number;
+    createdAt?: number;
+    lastHitAt?: number;
+}
+export interface CheckpointMetric {
+    checkpointId: string;
+    taskId: string;
+    agentId: string;
+    rawStateTokens: number;
+    checkpointTokens: number;
+    replayTokensAvoided: number;
+    createdAt?: number;
+}
+/**
+ * Log a context retrieval event.
+ */
+export declare function recordContextEvent(event: ContextEvent, cwd?: string): Promise<string>;
+/**
+ * Log observed model usage (Cursor Admin API, CSV import, or manual).
+ */
+export declare function recordModelUsage(usage: ModelUsage, cwd?: string): Promise<string>;
+/**
+ * Insert or update cache entry.
+ */
+export declare function setContextCacheRecord(record: ContextCacheRecord, cwd?: string): Promise<void>;
+/**
+ * Fetch cached context record by cache key. Increments hit count.
+ */
+export declare function getContextCacheRecord(cacheKey: string, cwd?: string): Promise<ContextCacheRecord | null>;
+/**
+ * Record subagent checkpoint metrics.
+ */
+export declare function recordCheckpointMetric(metric: CheckpointMetric, cwd?: string): Promise<void>;
+/**
+ * Helper to fetch all recorded context events.
+ */
+export declare function getContextEvents(taskId?: string, cwd?: string): Promise<ContextEvent[]>;
+/**
+ * Helper to fetch model usage records.
+ */
+export declare function getModelUsages(taskId?: string, cwd?: string): Promise<ModelUsage[]>;
+/**
+ * Helper to fetch checkpoint metrics.
+ */
+export declare function getCheckpointMetrics(taskId?: string, cwd?: string): Promise<CheckpointMetric[]>;

package/dist/storage/context-telemetry.js

@@ -0,0 +1,313 @@
+/**
+ * Context Telemetry & Avoided Token Database Access Layer
+ * Stores and queries context events, model usage, context caches, and checkpoint metrics.
+ */
+import { randomUUID } from 'crypto';
+import fs from 'fs-extra';
+import path from 'path';
+import { openDatabase, isSQLiteAvailable } from './db.js';
+// Fallback JSON persistence path if SQLite is unavailable
+function getFallbackDir(cwd) {
+    return path.join(cwd || process.cwd(), '.rigour');
+}
+/**
+ * Log a context retrieval event.
+ */
+export async function recordContextEvent(event, cwd) {
+    const id = event.id || `evt-${randomUUID()}`;
+    const timestamp = event.createdAt || Date.now();
+    const candidateTokens = event.candidateTokens || 0;
+    const returnedTokens = event.returnedTokens || 0;
+    const deduplicatedTokens = event.deduplicatedTokens || 0;
+    const candidateFiles = event.candidateFiles || 0;
+    const returnedFiles = event.returnedFiles || 0;
+    if (isSQLiteAvailable()) {
+        try {
+            const db = await openDatabase();
+            if (db) {
+                await db.run(`INSERT INTO context_events (
+                        id, task_id, session_id, agent_id, tool_name, query_hash, cache_status,
+                        candidate_tokens, returned_tokens, deduplicated_tokens, candidate_files, returned_files, created_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, id, event.taskId || null, event.sessionId || null, event.agentId || null, event.toolName, event.queryHash || null, event.cacheStatus, candidateTokens, returnedTokens, deduplicatedTokens, candidateFiles, returnedFiles, timestamp);
+                await db.close();
+                return id;
+            }
+        }
+        catch {
+            // fallback to JSON
+        }
+    }
+    const fallbackDir = getFallbackDir(cwd);
+    const fallbackPath = path.join(fallbackDir, 'context-events.jsonl');
+    await fs.ensureDir(fallbackDir);
+    const record = { ...event, id, createdAt: timestamp };
+    await fs.appendFile(fallbackPath, JSON.stringify(record) + '\n');
+    return id;
+}
+/**
+ * Log observed model usage (Cursor Admin API, CSV import, or manual).
+ */
+export async function recordModelUsage(usage, cwd) {
+    const id = usage.id || `usage-${randomUUID()}`;
+    const timestamp = usage.createdAt || Date.now();
+    if (isSQLiteAvailable()) {
+        try {
+            const db = await openDatabase();
+            if (db) {
+                await db.run(`INSERT INTO model_usage (
+                        id, task_id, session_id, agent_id, provider, model,
+                        input_tokens, output_tokens, cached_input_tokens, observed_cost_usd, source, created_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, id, usage.taskId || null, usage.sessionId || null, usage.agentId || null, usage.provider || 'cursor', usage.model || 'claude-3-5-sonnet', usage.inputTokens, usage.outputTokens, usage.cachedInputTokens || 0, usage.observedCostUsd || 0, usage.source, timestamp);
+                await db.close();
+                return id;
+            }
+        }
+        catch {
+            // fallback to JSON
+        }
+    }
+    const fallbackDir = getFallbackDir(cwd);
+    const fallbackPath = path.join(fallbackDir, 'model-usage.jsonl');
+    await fs.ensureDir(fallbackDir);
+    const record = { ...usage, id, createdAt: timestamp };
+    await fs.appendFile(fallbackPath, JSON.stringify(record) + '\n');
+    return id;
+}
+/**
+ * Insert or update cache entry.
+ */
+export async function setContextCacheRecord(record, cwd) {
+    const timestamp = record.createdAt || Date.now();
+    if (isSQLiteAvailable()) {
+        try {
+            const db = await openDatabase();
+            if (db) {
+                await db.run(`INSERT INTO context_cache (
+                        cache_key, cache_type, repo, branch, commit_sha, dependency_fingerprint,
+                        payload_json, payload_tokens, hit_count, created_at, last_hit_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    ON CONFLICT(cache_key) DO UPDATE SET
+                        dependency_fingerprint=excluded.dependency_fingerprint,
+                        payload_json=excluded.payload_json,
+                        payload_tokens=excluded.payload_tokens,
+                        created_at=excluded.created_at`, record.cacheKey, record.cacheType, record.repo, record.branch, record.commitSha || null, record.dependencyFingerprint, record.payloadJson, record.payloadTokens, record.hitCount || 0, timestamp, record.lastHitAt || null);
+                await db.close();
+                return;
+            }
+        }
+        catch {
+            // fallback
+        }
+    }
+    const fallbackDir = getFallbackDir(cwd);
+    const fallbackPath = path.join(fallbackDir, 'context-cache.json');
+    await fs.ensureDir(fallbackDir);
+    let cacheData = {};
+    if (await fs.pathExists(fallbackPath)) {
+        try {
+            cacheData = await fs.readJson(fallbackPath);
+        }
+        catch { }
+    }
+    cacheData[record.cacheKey] = { ...record, createdAt: timestamp };
+    await fs.writeJson(fallbackPath, cacheData, { spaces: 2 });
+}
+/**
+ * Fetch cached context record by cache key. Increments hit count.
+ */
+export async function getContextCacheRecord(cacheKey, cwd) {
+    if (isSQLiteAvailable()) {
+        try {
+            const db = await openDatabase();
+            if (db) {
+                const row = await db.get(`SELECT * FROM context_cache WHERE cache_key = ?`, cacheKey);
+                if (row) {
+                    const now = Date.now();
+                    await db.run(`UPDATE context_cache SET hit_count = hit_count + 1, last_hit_at = ? WHERE cache_key = ?`, now, cacheKey);
+                    await db.close();
+                    return {
+                        cacheKey: row.cache_key,
+                        cacheType: row.cache_type,
+                        repo: row.repo,
+                        branch: row.branch,
+                        commitSha: row.commit_sha,
+                        dependencyFingerprint: row.dependency_fingerprint,
+                        payloadJson: row.payload_json,
+                        payloadTokens: row.payload_tokens,
+                        hitCount: (row.hit_count || 0) + 1,
+                        createdAt: row.created_at,
+                        lastHitAt: now
+                    };
+                }
+                await db.close();
+                return null;
+            }
+        }
+        catch {
+            // fallback
+        }
+    }
+    const fallbackPath = path.join(getFallbackDir(cwd), 'context-cache.json');
+    if (await fs.pathExists(fallbackPath)) {
+        try {
+            const cacheData = await fs.readJson(fallbackPath);
+            const entry = cacheData[cacheKey];
+            if (entry) {
+                entry.hitCount = (entry.hitCount || 0) + 1;
+                entry.lastHitAt = Date.now();
+                await fs.writeJson(fallbackPath, cacheData, { spaces: 2 });
+                return entry;
+            }
+        }
+        catch { }
+    }
+    return null;
+}
+/**
+ * Record subagent checkpoint metrics.
+ */
+export async function recordCheckpointMetric(metric, cwd) {
+    const timestamp = metric.createdAt || Date.now();
+    if (isSQLiteAvailable()) {
+        try {
+            const db = await openDatabase();
+            if (db) {
+                await db.run(`INSERT INTO checkpoint_metrics (
+                        checkpoint_id, task_id, agent_id, raw_state_tokens, checkpoint_tokens, replay_tokens_avoided, created_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?)
+                    ON CONFLICT(checkpoint_id) DO UPDATE SET
+                        raw_state_tokens=excluded.raw_state_tokens,
+                        checkpoint_tokens=excluded.checkpoint_tokens,
+                        replay_tokens_avoided=excluded.replay_tokens_avoided`, metric.checkpointId, metric.taskId, metric.agentId, metric.rawStateTokens, metric.checkpointTokens, metric.replayTokensAvoided, timestamp);
+                await db.close();
+                return;
+            }
+        }
+        catch {
+            // fallback
+        }
+    }
+    const fallbackDir = getFallbackDir(cwd);
+    const fallbackPath = path.join(fallbackDir, 'checkpoint-metrics.jsonl');
+    await fs.ensureDir(fallbackDir);
+    await fs.appendFile(fallbackPath, JSON.stringify({ ...metric, createdAt: timestamp }) + '\n');
+}
+/**
+ * Helper to fetch all recorded context events.
+ */
+export async function getContextEvents(taskId, cwd) {
+    if (isSQLiteAvailable()) {
+        try {
+            const db = await openDatabase();
+            if (db) {
+                const query = taskId
+                    ? `SELECT * FROM context_events WHERE task_id = ? ORDER BY created_at DESC`
+                    : `SELECT * FROM context_events ORDER BY created_at DESC`;
+                const params = taskId ? [taskId] : [];
+                const rows = await db.all(query, ...params);
+                await db.close();
+                return rows.map((r) => ({
+                    id: r.id,
+                    taskId: r.task_id,
+                    sessionId: r.session_id,
+                    agentId: r.agent_id,
+                    toolName: r.tool_name,
+                    queryHash: r.query_hash,
+                    cacheStatus: r.cache_status,
+                    candidateTokens: r.candidate_tokens,
+                    returnedTokens: r.returned_tokens,
+                    deduplicatedTokens: r.deduplicated_tokens,
+                    candidateFiles: r.candidate_files,
+                    returnedFiles: r.returned_files,
+                    createdAt: r.created_at
+                }));
+            }
+        }
+        catch {
+            // fallback
+        }
+    }
+    const fallbackPath = path.join(getFallbackDir(cwd), 'context-events.jsonl');
+    if (!await fs.pathExists(fallbackPath))
+        return [];
+    const lines = (await fs.readFile(fallbackPath, 'utf8')).split('\n').filter(Boolean);
+    const events = lines.map(l => JSON.parse(l));
+    return taskId ? events.filter(e => e.taskId === taskId) : events;
+}
+/**
+ * Helper to fetch model usage records.
+ */
+export async function getModelUsages(taskId, cwd) {
+    if (isSQLiteAvailable()) {
+        try {
+            const db = await openDatabase();
+            if (db) {
+                const query = taskId
+                    ? `SELECT * FROM model_usage WHERE task_id = ? ORDER BY created_at DESC`
+                    : `SELECT * FROM model_usage ORDER BY created_at DESC`;
+                const params = taskId ? [taskId] : [];
+                const rows = await db.all(query, ...params);
+                await db.close();
+                return rows.map((r) => ({
+                    id: r.id,
+                    taskId: r.task_id,
+                    sessionId: r.session_id,
+                    agentId: r.agent_id,
+                    provider: r.provider,
+                    model: r.model,
+                    inputTokens: r.input_tokens,
+                    outputTokens: r.output_tokens,
+                    cachedInputTokens: r.cached_input_tokens,
+                    observedCostUsd: r.observed_cost_usd,
+                    source: r.source,
+                    createdAt: r.created_at
+                }));
+            }
+        }
+        catch {
+            // fallback
+        }
+    }
+    const fallbackPath = path.join(getFallbackDir(cwd), 'model-usage.jsonl');
+    if (!await fs.pathExists(fallbackPath))
+        return [];
+    const lines = (await fs.readFile(fallbackPath, 'utf8')).split('\n').filter(Boolean);
+    const usages = lines.map(l => JSON.parse(l));
+    return taskId ? usages.filter(u => u.taskId === taskId) : usages;
+}
+/**
+ * Helper to fetch checkpoint metrics.
+ */
+export async function getCheckpointMetrics(taskId, cwd) {
+    if (isSQLiteAvailable()) {
+        try {
+            const db = await openDatabase();
+            if (db) {
+                const query = taskId
+                    ? `SELECT * FROM checkpoint_metrics WHERE task_id = ? ORDER BY created_at DESC`
+                    : `SELECT * FROM checkpoint_metrics ORDER BY created_at DESC`;
+                const params = taskId ? [taskId] : [];
+                const rows = await db.all(query, ...params);
+                await db.close();
+                return rows.map((r) => ({
+                    checkpointId: r.checkpoint_id,
+                    taskId: r.task_id,
+                    agentId: r.agent_id,
+                    rawStateTokens: r.raw_state_tokens,
+                    checkpointTokens: r.checkpoint_tokens,
+                    replayTokensAvoided: r.replay_tokens_avoided,
+                    createdAt: r.created_at
+                }));
+            }
+        }
+        catch {
+            // fallback
+        }
+    }
+    const fallbackPath = path.join(getFallbackDir(cwd), 'checkpoint-metrics.jsonl');
+    if (!await fs.pathExists(fallbackPath))
+        return [];
+    const lines = (await fs.readFile(fallbackPath, 'utf8')).split('\n').filter(Boolean);
+    const metrics = lines.map(l => JSON.parse(l));
+    return taskId ? metrics.filter(m => m.taskId === taskId) : metrics;
+}

package/dist/storage/context-telemetry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/storage/context-telemetry.test.js

@@ -0,0 +1,80 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import path from 'path';
+import os from 'os';
+import fs from 'fs-extra';
+vi.mock('./db.js', () => ({
+    isSQLiteAvailable: () => false,
+    openDatabase: async () => null,
+    DB_PATH: '/tmp/rigour-test.db',
+    RIGOUR_DIR: '/tmp/.rigour',
+}));
+import { recordContextEvent, recordModelUsage, setContextCacheRecord, getContextCacheRecord, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics, } from './context-telemetry.js';
+describe('context-telemetry storage', () => {
+    const testCwd = path.join(os.tmpdir(), `rigour-ctx-telemetry-${Date.now()}`);
+    beforeEach(async () => {
+        await fs.ensureDir(path.join(testCwd, '.rigour'));
+    });
+    afterEach(async () => {
+        await fs.remove(testCwd);
+    });
+    it('records and retrieves context events via JSON fallback', async () => {
+        const id = await recordContextEvent({
+            taskId: 'task-1',
+            toolName: 'rigour_recall',
+            cacheStatus: 'semantic-hit',
+            candidateTokens: 4000,
+            returnedTokens: 800,
+            deduplicatedTokens: 1200,
+        }, testCwd);
+        expect(id).toMatch(/^evt-/);
+        const events = await getContextEvents('task-1', testCwd);
+        expect(events).toHaveLength(1);
+        expect(events[0].toolName).toBe('rigour_recall');
+        expect(events[0].candidateTokens).toBe(4000);
+        expect(events[0].returnedTokens).toBe(800);
+    });
+    it('records and retrieves model usage via JSON fallback', async () => {
+        await recordModelUsage({
+            taskId: 'cursor-imported',
+            provider: 'cursor',
+            model: 'claude-3-5-sonnet',
+            inputTokens: 12000,
+            outputTokens: 1500,
+            observedCostUsd: 1.25,
+            source: 'cursor-dashboard-csv',
+        }, testCwd);
+        const usages = await getModelUsages(undefined, testCwd);
+        expect(usages).toHaveLength(1);
+        expect(usages[0].inputTokens).toBe(12000);
+        expect(usages[0].source).toBe('cursor-dashboard-csv');
+    });
+    it('stores cache records and increments hit count', async () => {
+        await setContextCacheRecord({
+            cacheKey: 'static:repo:main:file.ts:abc123:v1',
+            cacheType: 'static',
+            repo: 'repo',
+            branch: 'main',
+            dependencyFingerprint: 'dep-1',
+            payloadJson: JSON.stringify({ exports: ['foo'] }),
+            payloadTokens: 42,
+        }, testCwd);
+        const first = await getContextCacheRecord('static:repo:main:file.ts:abc123:v1', testCwd);
+        const second = await getContextCacheRecord('static:repo:main:file.ts:abc123:v1', testCwd);
+        expect(first?.payloadTokens).toBe(42);
+        expect(second?.hitCount).toBe(2);
+    });
+    it('records and retrieves checkpoint metrics via JSON fallback', async () => {
+        await recordCheckpointMetric({
+            checkpointId: 'checkpoint:CTP-1:agent-a:implementation',
+            taskId: 'CTP-1',
+            agentId: 'agent-a',
+            rawStateTokens: 50000,
+            checkpointTokens: 400,
+            replayTokensAvoided: 49600,
+        }, testCwd);
+        const metrics = await getCheckpointMetrics('CTP-1', testCwd);
+        expect(metrics).toHaveLength(1);
+        expect(metrics[0].rawStateTokens).toBe(50000);
+        expect(metrics[0].replayTokensAvoided).toBe(49600);
+    });
+});

package/dist/storage/db.js

@@ -45,7 +45,7 @@ function loadSqlite3() {
 const RIGOUR_DIR = path.join(os.homedir(), '.rigour');
 const DB_PATH = path.join(RIGOUR_DIR, 'rigour.db');
 /** Current schema version — bump when adding migrations. */
-const SCHEMA_VERSION = 2;
+const SCHEMA_VERSION = 4;
 const SCHEMA_SQL = `
 -- Schema version tracking
 CREATE TABLE IF NOT EXISTS meta (
@@ -118,6 +118,65 @@ CREATE TABLE IF NOT EXISTS codebase (
     last_indexed INTEGER NOT NULL
 );
 
+-- Rigour Telemetry: Avoided and observed context events
+CREATE TABLE IF NOT EXISTS context_events (
+    id TEXT PRIMARY KEY,
+    task_id TEXT,
+    session_id TEXT,
+    agent_id TEXT,
+    tool_name TEXT NOT NULL,
+    query_hash TEXT,
+    cache_status TEXT NOT NULL,
+    candidate_tokens INTEGER NOT NULL DEFAULT 0,
+    returned_tokens INTEGER NOT NULL DEFAULT 0,
+    deduplicated_tokens INTEGER NOT NULL DEFAULT 0,
+    candidate_files INTEGER NOT NULL DEFAULT 0,
+    returned_files INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL
+);
+
+-- Cursor / Model Usage telemetry
+CREATE TABLE IF NOT EXISTS model_usage (
+    id TEXT PRIMARY KEY,
+    task_id TEXT,
+    session_id TEXT,
+    agent_id TEXT,
+    provider TEXT,
+    model TEXT,
+    input_tokens INTEGER,
+    output_tokens INTEGER,
+    cached_input_tokens INTEGER,
+    observed_cost_usd REAL,
+    source TEXT NOT NULL,
+    created_at INTEGER NOT NULL
+);
+
+-- 4-Layer Context Cache
+CREATE TABLE IF NOT EXISTS context_cache (
+    cache_key TEXT PRIMARY KEY,
+    cache_type TEXT NOT NULL,
+    repo TEXT NOT NULL,
+    branch TEXT NOT NULL,
+    commit_sha TEXT,
+    dependency_fingerprint TEXT NOT NULL,
+    payload_json TEXT NOT NULL,
+    payload_tokens INTEGER NOT NULL,
+    hit_count INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL,
+    last_hit_at INTEGER
+);
+
+-- Checkpoint compression metrics
+CREATE TABLE IF NOT EXISTS checkpoint_metrics (
+    checkpoint_id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL,
+    agent_id TEXT NOT NULL,
+    raw_state_tokens INTEGER,
+    checkpoint_tokens INTEGER NOT NULL,
+    replay_tokens_avoided INTEGER,
+    created_at INTEGER NOT NULL
+);
+
 -- Indexes for performance
 CREATE INDEX IF NOT EXISTS idx_scans_repo ON scans(repo);
 CREATE INDEX IF NOT EXISTS idx_scans_timestamp ON scans(timestamp);
@@ -125,6 +184,14 @@ CREATE INDEX IF NOT EXISTS idx_findings_scan ON findings(scan_id);
 CREATE INDEX IF NOT EXISTS idx_findings_category ON findings(category);
 CREATE INDEX IF NOT EXISTS idx_patterns_repo ON patterns(repo);
 CREATE INDEX IF NOT EXISTS idx_patterns_strength ON patterns(strength);
+CREATE INDEX IF NOT EXISTS idx_context_events_task ON context_events(task_id);
+CREATE INDEX IF NOT EXISTS idx_context_events_session ON context_events(session_id);
+CREATE INDEX IF NOT EXISTS idx_context_events_agent ON context_events(agent_id);
+CREATE INDEX IF NOT EXISTS idx_context_events_created ON context_events(created_at);
+CREATE INDEX IF NOT EXISTS idx_model_usage_task ON model_usage(task_id);
+CREATE INDEX IF NOT EXISTS idx_model_usage_created ON model_usage(created_at);
+CREATE INDEX IF NOT EXISTS idx_context_cache_type ON context_cache(cache_type);
+CREATE INDEX IF NOT EXISTS idx_checkpoint_metrics_task ON checkpoint_metrics(task_id);
 `;
 function wrapDatabase(raw) {
     const db = {
@@ -230,7 +297,78 @@ async function runMigrations(db) {
         `);
         await db.run("INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', '2')");
     }
-    // Future: if (current < 3) { ... ALTER TABLE ... }
+    if (current < 3) {
+        await db.exec(`
+            CREATE TABLE IF NOT EXISTS context_events (
+                id TEXT PRIMARY KEY,
+                task_id TEXT,
+                session_id TEXT,
+                agent_id TEXT,
+                tool_name TEXT NOT NULL,
+                query_hash TEXT,
+                cache_status TEXT NOT NULL,
+                candidate_tokens INTEGER NOT NULL DEFAULT 0,
+                returned_tokens INTEGER NOT NULL DEFAULT 0,
+                deduplicated_tokens INTEGER NOT NULL DEFAULT 0,
+                candidate_files INTEGER NOT NULL DEFAULT 0,
+                returned_files INTEGER NOT NULL DEFAULT 0,
+                created_at INTEGER NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS model_usage (
+                id TEXT PRIMARY KEY,
+                task_id TEXT,
+                session_id TEXT,
+                agent_id TEXT,
+                provider TEXT,
+                model TEXT,
+                input_tokens INTEGER,
+                output_tokens INTEGER,
+                cached_input_tokens INTEGER,
+                observed_cost_usd REAL,
+                source TEXT NOT NULL,
+                created_at INTEGER NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS context_cache (
+                cache_key TEXT PRIMARY KEY,
+                cache_type TEXT NOT NULL,
+                repo TEXT NOT NULL,
+                branch TEXT NOT NULL,
+                commit_sha TEXT,
+                dependency_fingerprint TEXT NOT NULL,
+                payload_json TEXT NOT NULL,
+                payload_tokens INTEGER NOT NULL,
+                hit_count INTEGER NOT NULL DEFAULT 0,
+                created_at INTEGER NOT NULL,
+                last_hit_at INTEGER
+            );
+            CREATE TABLE IF NOT EXISTS checkpoint_metrics (
+                checkpoint_id TEXT PRIMARY KEY,
+                task_id TEXT NOT NULL,
+                agent_id TEXT NOT NULL,
+                raw_state_tokens INTEGER,
+                checkpoint_tokens INTEGER NOT NULL,
+                replay_tokens_avoided INTEGER,
+                created_at INTEGER NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS idx_context_events_task ON context_events(task_id);
+            CREATE INDEX IF NOT EXISTS idx_context_events_session ON context_events(session_id);
+            CREATE INDEX IF NOT EXISTS idx_context_events_agent ON context_events(agent_id);
+            CREATE INDEX IF NOT EXISTS idx_context_events_created ON context_events(created_at);
+            CREATE INDEX IF NOT EXISTS idx_model_usage_task ON model_usage(task_id);
+            CREATE INDEX IF NOT EXISTS idx_model_usage_created ON model_usage(created_at);
+            CREATE INDEX IF NOT EXISTS idx_context_cache_type ON context_cache(cache_type);
+            CREATE INDEX IF NOT EXISTS idx_checkpoint_metrics_task ON checkpoint_metrics(task_id);
+        `);
+        await db.run("INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', '3')");
+    }
+    if (current < 4) {
+        await db.exec(`
+            CREATE INDEX IF NOT EXISTS idx_context_events_session ON context_events(session_id);
+            CREATE INDEX IF NOT EXISTS idx_context_events_created ON context_events(created_at);
+            CREATE INDEX IF NOT EXISTS idx_model_usage_created ON model_usage(created_at);
+        `);
+        await db.run("INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', '4')");
+    }
 }
 /**
  * Compact the database — prune old data, reclaim disk space.

package/dist/storage/index.d.ts

@@ -9,3 +9,5 @@ export { insertFindings, getFindingsForScan, getDeepFindings } from './findings.
 export { reinforcePattern, decayPatterns, getStrongPatterns, getPatterns, getHardRules } from './patterns.js';
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './local-memory.js';
 export type { ProjectStats } from './local-memory.js';
+export { recordContextEvent, recordModelUsage, setContextCacheRecord, getContextCacheRecord, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics } from './context-telemetry.js';
+export type { ContextEvent, ModelUsage, ContextCacheRecord, CheckpointMetric } from './context-telemetry.js';

package/dist/storage/index.js

@@ -7,3 +7,4 @@ export { insertScan, getRecentScans, getScoreTrendFromDB, getTopIssues } from '.
 export { insertFindings, getFindingsForScan, getDeepFindings } from './findings.js';
 export { reinforcePattern, decayPatterns, getStrongPatterns, getPatterns, getHardRules } from './patterns.js';
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './local-memory.js';
+export { recordContextEvent, recordModelUsage, setContextCacheRecord, getContextCacheRecord, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics } from './context-telemetry.js';