escribano 0.1.0

package/dist/tests/process-v2.test.js

@@ -0,0 +1,90 @@
+/**
+ * Process Recording V2 Tests
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { processRecordingV2 } from '../actions/process-recording-v2.js';
+describe('processRecordingV2', () => {
+    it('should call extractFramesAtInterval instead of extractFramesAtTimestamps during visual processing', async () => {
+        // Mock Recording in DB
+        const mockDbRecording = {
+            id: 'rec-123',
+            status: 'raw',
+            processing_step: 'idle',
+            video_path: '/tmp/test.mp4',
+            audio_mic_path: null,
+            audio_system_path: null,
+            captured_at: new Date(),
+            duration: 60,
+        };
+        const mockRepos = {
+            recordings: {
+                findById: vi.fn().mockReturnValue(mockDbRecording),
+                updateStatus: vi.fn(),
+            },
+            observations: {
+                saveBatch: vi.fn(),
+                save: vi.fn(),
+                findByRecording: vi.fn().mockReturnValue([]),
+                findByRecordingAndType: vi.fn().mockReturnValue([]),
+                updateEmbedding: vi.fn(),
+                deleteByRecording: vi.fn(),
+            },
+            clusters: {
+                deleteByRecording: vi.fn(),
+                save: vi.fn(),
+                linkObservationsBatch: vi.fn(),
+                findByRecording: vi.fn().mockReturnValue([]),
+                findByRecordingAndType: vi.fn().mockReturnValue([]),
+                getObservations: vi.fn().mockReturnValue([]),
+                updateClassification: vi.fn(),
+                getMergedAudioClusters: vi.fn().mockReturnValue([]),
+                saveMerge: vi.fn(),
+            },
+            contexts: {
+                findByTypeAndName: vi.fn(),
+                save: vi.fn(),
+                linkObservation: vi.fn(),
+                getLinksByRecording: vi.fn().mockReturnValue([]),
+            },
+            topicBlocks: {
+                deleteByRecording: vi.fn(),
+                save: vi.fn(),
+            },
+        };
+        const mockVideoService = {
+            extractFramesAtInterval: vi.fn().mockResolvedValue([
+                { imagePath: '/tmp/f1.jpg', timestamp: 0 },
+                { imagePath: '/tmp/f2.jpg', timestamp: 2 },
+            ]),
+            extractFramesAtTimestamps: vi.fn(),
+            runVisualIndexing: vi.fn().mockResolvedValue({ frames: [] }),
+        };
+        const mockIntelligence = {
+            describeImages: vi.fn().mockResolvedValue({ descriptions: [] }),
+            embedText: vi.fn().mockResolvedValue([]),
+            extractTopics: vi.fn().mockResolvedValue([]),
+        };
+        const mockEmbedding = {
+            embedBatch: vi.fn().mockResolvedValue([]),
+        };
+        const mockPreprocessor = {
+            extractSpeechSegments: vi
+                .fn()
+                .mockResolvedValue({ segments: [], tempDir: '/tmp' }),
+            cleanup: vi.fn(),
+        };
+        const mockTranscription = {};
+        await processRecordingV2('rec-123', mockRepos, {
+            video: mockVideoService,
+            intelligence: mockIntelligence,
+            embedding: mockEmbedding,
+            preprocessor: mockPreprocessor,
+            transcription: mockTranscription,
+        });
+        // Verify correct function was called
+        expect(mockVideoService.extractFramesAtInterval).toHaveBeenCalled();
+        expect(mockVideoService.extractFramesAtTimestamps).not.toHaveBeenCalled();
+        // Verify interval-based extraction was used with correct threshold
+        expect(mockVideoService.extractFramesAtInterval).toHaveBeenCalledWith('/tmp/test.mp4', 0.3, expect.stringContaining('frames'));
+    });
+});

package/dist/tests/services/clustering.test.js

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi } from 'vitest';
+import { embeddingToBlob } from '../../db/helpers.js';
+import { clusterObservations } from '../../services/clustering.js';
+describe('clusterObservations', () => {
+    const mockEmbeddingService = {
+        embed: vi.fn(),
+        embedBatch: vi.fn(),
+        similarity: vi.fn((a, b) => {
+            // Simple mock: if first element is same, they are identical
+            return a[0] === b[0] ? 1 : 0;
+        }),
+        centroid: vi.fn((embeddings) => {
+            if (embeddings.length === 0)
+                return [];
+            const dim = embeddings[0].length;
+            const res = new Array(dim).fill(0);
+            for (const e of embeddings) {
+                for (let i = 0; i < dim; i++)
+                    res[i] += e[i];
+            }
+            return res.map((v) => v / embeddings.length);
+        }),
+    };
+    const createObs = (id, timestamp, typeVal) => ({
+        id,
+        recording_id: 'rec1',
+        type: 'visual',
+        timestamp,
+        end_timestamp: timestamp + 1,
+        image_path: null,
+        ocr_text: `text ${typeVal}`,
+        vlm_description: null,
+        vlm_raw_response: null,
+        activity_type: null,
+        apps: null,
+        topics: null,
+        text: null,
+        audio_source: null,
+        audio_type: null,
+        embedding: embeddingToBlob([typeVal, 0, 0]),
+        created_at: new Date().toISOString(),
+    });
+    it('should cluster identical observations within time window', () => {
+        const obs = [
+            createObs('1', 10, 1),
+            createObs('2', 20, 1),
+            createObs('3', 30, 1),
+        ];
+        const clusters = clusterObservations(obs, mockEmbeddingService, {
+            timeWindowSeconds: 60,
+            distanceThreshold: 0.1,
+            minClusterSize: 2,
+        });
+        expect(clusters).toHaveLength(1);
+        expect(clusters[0].observations).toHaveLength(3);
+    });
+    it('should not cluster observations outside time window', () => {
+        const obs = [
+            createObs('1', 10, 1),
+            createObs('2', 1000, 1), // Far away in time
+        ];
+        const clusters = clusterObservations(obs, mockEmbeddingService, {
+            timeWindowSeconds: 60,
+            distanceThreshold: 0.1,
+            minClusterSize: 1, // Set to 1 to see two clusters
+        });
+        expect(clusters).toHaveLength(2);
+    });
+    it('should not cluster semantically different observations', () => {
+        const obs = [
+            createObs('1', 10, 1),
+            createObs('2', 20, 2), // Different embedding
+        ];
+        const clusters = clusterObservations(obs, mockEmbeddingService, {
+            timeWindowSeconds: 60,
+            distanceThreshold: 0.1,
+            minClusterSize: 1,
+        });
+        expect(clusters).toHaveLength(2);
+    });
+    it('should absorb small clusters into nearest large cluster', () => {
+        // 3 similar obs (large cluster)
+        // 1 similar obs (small cluster, should be absorbed)
+        const obs = [
+            createObs('1', 10, 1),
+            createObs('2', 20, 1),
+            createObs('3', 30, 1),
+            createObs('4', 40, 1),
+        ];
+        const clusters = clusterObservations(obs, mockEmbeddingService, {
+            timeWindowSeconds: 60,
+            distanceThreshold: 0.1,
+            minClusterSize: 3,
+        });
+        expect(clusters).toHaveLength(1);
+        expect(clusters[0].observations).toHaveLength(4);
+    });
+    it('should handle empty input', () => {
+        const clusters = clusterObservations([], mockEmbeddingService);
+        expect(clusters).toEqual([]);
+    });
+    it('should throw if an observation in validObs is missing embedding', () => {
+        // We mock bufferToEmbedding to fail if we want to test the throw,
+        // but the current code in clustering.ts uses a local bufferToEmbedding.
+        // However, if we pass an obs that PASSES the filter but then has no embedding
+        // (impossible due to filter), it would throw.
+        // Let's test the filter instead
+        const obsNoEmbed = [{ id: '1', embedding: null }];
+        const clusters = clusterObservations(obsNoEmbed, mockEmbeddingService);
+        expect(clusters).toHaveLength(0);
+    });
+});

package/dist/tests/services/frame-sampling.test.js

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+import { adaptiveSample, adaptiveSampleWithScenes, calculateAdaptiveBaseInterval, getSamplingStats, } from '../../services/frame-sampling.js';
+describe('adaptiveSample', () => {
+    it('should return empty array for empty input', () => {
+        const result = adaptiveSample([]);
+        expect(result).toEqual([]);
+    });
+    it('should sample at base interval', () => {
+        // Create frames every 2 seconds for 60 seconds
+        const frames = [];
+        for (let t = 0; t <= 60; t += 2) {
+            frames.push({ imagePath: `frame_${t}.jpg`, timestamp: t });
+        }
+        const result = adaptiveSample(frames, { baseIntervalSeconds: 10 });
+        // Should get frames at 0, 10, 20, 30, 40, 50, 60 = 7 frames
+        expect(result.length).toBe(7);
+        expect(result.every((f) => f.reason === 'base')).toBe(true);
+        expect(result.map((f) => f.timestamp)).toEqual([0, 10, 20, 30, 40, 50, 60]);
+    });
+    it('should fill gaps larger than threshold', () => {
+        // Create frames with a gap
+        const frames = [
+            { imagePath: 'frame_0.jpg', timestamp: 0 },
+            { imagePath: 'frame_2.jpg', timestamp: 2 },
+            { imagePath: 'frame_4.jpg', timestamp: 4 },
+            // Gap from 4 to 30 seconds
+            { imagePath: 'frame_30.jpg', timestamp: 30 },
+            { imagePath: 'frame_32.jpg', timestamp: 32 },
+        ];
+        const result = adaptiveSample(frames, {
+            baseIntervalSeconds: 10,
+            gapThresholdSeconds: 15,
+            gapFillIntervalSeconds: 5,
+        });
+        // Base samples: 0, 30
+        // Gap detected: 30 - 0 = 30 > 15
+        // Gap fill should add samples between 0 and 30
+        expect(result.length).toBeGreaterThan(2);
+        expect(result.some((f) => f.reason === 'gap_fill')).toBe(true);
+    });
+    it('should not fill gaps smaller than threshold', () => {
+        const frames = [];
+        for (let t = 0; t <= 30; t += 2) {
+            frames.push({ imagePath: `frame_${t}.jpg`, timestamp: t });
+        }
+        const result = adaptiveSample(frames, {
+            baseIntervalSeconds: 10,
+            gapThresholdSeconds: 15,
+        });
+        // Gap between samples is 10s, which is < 15s threshold
+        expect(result.every((f) => f.reason === 'base')).toBe(true);
+    });
+    it('should handle unsorted input', () => {
+        const frames = [
+            { imagePath: 'frame_20.jpg', timestamp: 20 },
+            { imagePath: 'frame_0.jpg', timestamp: 0 },
+            { imagePath: 'frame_10.jpg', timestamp: 10 },
+        ];
+        const result = adaptiveSample(frames, { baseIntervalSeconds: 10 });
+        expect(result.map((f) => f.timestamp)).toEqual([0, 10, 20]);
+    });
+});
+describe('getSamplingStats', () => {
+    it('should calculate correct statistics', () => {
+        const original = Array.from({ length: 100 }, (_, i) => ({
+            imagePath: `frame_${i}.jpg`,
+            timestamp: i * 2,
+        }));
+        const sampled = adaptiveSample(original, { baseIntervalSeconds: 10 });
+        const stats = getSamplingStats(original, sampled);
+        expect(stats.originalCount).toBe(100);
+        expect(stats.sampledCount).toBeLessThan(100);
+        expect(stats.reductionPercent).toBeGreaterThan(0);
+    });
+});
+describe('calculateAdaptiveBaseInterval', () => {
+    it('should return config base for few scene changes (<= 20)', () => {
+        expect(calculateAdaptiveBaseInterval(0, 10)).toBe(10);
+        expect(calculateAdaptiveBaseInterval(5, 10)).toBe(10);
+        expect(calculateAdaptiveBaseInterval(20, 10)).toBe(10);
+    });
+    it('should return 20s for moderate scene changes (21-50)', () => {
+        expect(calculateAdaptiveBaseInterval(21, 10)).toBe(20);
+        expect(calculateAdaptiveBaseInterval(35, 10)).toBe(20);
+        expect(calculateAdaptiveBaseInterval(50, 10)).toBe(20);
+    });
+    it('should return 30s for high scene density (> 50)', () => {
+        expect(calculateAdaptiveBaseInterval(51, 10)).toBe(30);
+        expect(calculateAdaptiveBaseInterval(109, 10)).toBe(30);
+        expect(calculateAdaptiveBaseInterval(200, 10)).toBe(30);
+    });
+    it('should never go below configured base interval', () => {
+        // If user configured 40s, keep it even for low scene counts
+        expect(calculateAdaptiveBaseInterval(5, 40)).toBe(40);
+        expect(calculateAdaptiveBaseInterval(30, 40)).toBe(40);
+        expect(calculateAdaptiveBaseInterval(100, 40)).toBe(40);
+    });
+});
+describe('adaptiveSampleWithScenes', () => {
+    // Helper: create frames every 2s for N minutes
+    function makeFrames(durationMinutes) {
+        const frames = [];
+        const total = durationMinutes * 60;
+        for (let t = 0; t <= total; t += 2) {
+            frames.push({ imagePath: `frame_${t}.jpg`, timestamp: t });
+        }
+        return frames;
+    }
+    it('should return empty array for empty input', () => {
+        expect(adaptiveSampleWithScenes([], [])).toEqual([]);
+    });
+    it('should sample at base interval when no scene changes', () => {
+        const frames = makeFrames(1); // 1 minute
+        const result = adaptiveSampleWithScenes(frames, []);
+        // Should behave like regular sampling
+        expect(result.length).toBeGreaterThan(0);
+        expect(result.every((f) => f.reason === 'base')).toBe(true);
+    });
+    it('should include scene change frames', () => {
+        const frames = makeFrames(1);
+        const sceneChanges = [10, 20, 40];
+        const result = adaptiveSampleWithScenes(frames, sceneChanges);
+        const sceneFrames = result.filter((f) => f.reason === 'scene_change');
+        expect(sceneFrames.length).toBe(3);
+    });
+    it('should produce fewer total frames with high scene density', () => {
+        const frames = makeFrames(10); // 10 minutes, 300 frames
+        // Low density: 5 scene changes
+        const lowDensityResult = adaptiveSampleWithScenes(frames, [30, 100, 200, 400, 500], { baseIntervalSeconds: 10 });
+        // High density: 60 scene changes (every ~10s)
+        const highDensityScenes = Array.from({ length: 60 }, (_, i) => i * 10);
+        const highDensityResult = adaptiveSampleWithScenes(frames, highDensityScenes, { baseIntervalSeconds: 10 });
+        // High density should use 30s base interval, resulting in fewer
+        // base samples (but more scene samples). Total should still be
+        // manageable and not explode.
+        const highStats = getSamplingStats(frames, highDensityResult);
+        expect(highStats.sampledCount).toBeLessThan(frames.length);
+        expect(highStats.reductionPercent).toBeGreaterThan(50);
+    });
+    it('should match real-world scenario: 59 min, 109 scenes', () => {
+        const frames = makeFrames(59); // 1776 frames
+        // Simulate 109 scene changes spread across 59 minutes
+        const sceneChanges = Array.from({ length: 109 }, (_, i) => Math.round((i / 109) * 59 * 60));
+        const result = adaptiveSampleWithScenes(frames, sceneChanges);
+        const stats = getSamplingStats(frames, result);
+        // Target: under 250 frames total (was 1199 before adaptive interval + gap threshold fix)
+        expect(stats.sampledCount).toBeLessThan(250);
+        expect(stats.sceneChangeCount).toBe(109);
+        // Reduction should be significant
+        expect(stats.reductionPercent).toBeGreaterThan(85);
+    });
+});

package/dist/tests/utils/ocr.test.js

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { cleanOcrText, isOcrMeaningful } from '../../utils/ocr.js';
+describe('OCR Cleanup Utilities', () => {
+    describe('cleanOcrText', () => {
+        it('preserves valid content and short commands', () => {
+            const input = 'git status\nnpm install\nThis is a valid sentence.';
+            const output = cleanOcrText(input);
+            expect(output).toContain('git status');
+            expect(output).toContain('npm install');
+            expect(output).toContain('This is a valid sentence.');
+        });
+        it('filters out system clock artifacts', () => {
+            const input = '© 15/01 Thu 12:12\nActual Content';
+            const output = cleanOcrText(input);
+            expect(output).not.toContain('© 15/01');
+            expect(output).toContain('Actual Content');
+        });
+        it('filters out window title artifacts', () => {
+            const input = '> Google Chrome\nSome webpage content';
+            const output = cleanOcrText(input);
+            expect(output).not.toContain('> Google Chrome');
+            expect(output).toContain('Some webpage content');
+        });
+        it('filters out repeated character garbage', () => {
+            const input = 'eee\nGPassssss\nValid text';
+            const output = cleanOcrText(input);
+            expect(output).not.toContain('eee');
+            expect(output).not.toContain('GPassssss');
+            expect(output).toContain('Valid text');
+        });
+        it('filters out common UI bookmarks and status lines', () => {
+            const input = 'All Bookmarks\nZoho Mail\nProject code here';
+            const output = cleanOcrText(input);
+            expect(output).not.toContain('All Bookmarks');
+            expect(output).not.toContain('Zoho Mail');
+            expect(output).toContain('Project code here');
+        });
+        it('filters out UI separators and indicators', () => {
+            const input = '| BSI - Bundesamt f.\nDetected Language\nEnglish\nActual information';
+            const output = cleanOcrText(input);
+            expect(output).not.toContain('BSI - Bundesamt');
+            expect(output).not.toContain('Detected Language');
+            expect(output).not.toContain('English');
+            expect(output).toContain('Actual information');
+        });
+        it('removes duplicate consecutive lines', () => {
+            const input = 'Line 1\nLine 1\nLine 2\nLine 1';
+            const output = cleanOcrText(input);
+            const lines = output.split('\n');
+            expect(lines).toHaveLength(3);
+            expect(lines[0]).toBe('Line 1');
+            expect(lines[1]).toBe('Line 2');
+            expect(lines[2]).toBe('Line 1');
+        });
+        it('filters out short garbage fragments while keeping short commands', () => {
+            // 'cid' was found in DB, should be filtered if it doesn't look like a word
+            // 'git' should be kept.
+            const input = 'cid\ngit\nnpm\nsh Twelv';
+            const output = cleanOcrText(input);
+            expect(output).not.toContain('cid');
+            expect(output).not.toContain('sh Twelv');
+            expect(output).toContain('git');
+            expect(output).toContain('npm');
+        });
+    });
+    describe('isOcrMeaningful', () => {
+        it('returns false for empty or very short text', () => {
+            expect(isOcrMeaningful('')).toBe(false);
+            expect(isOcrMeaningful('Too short')).toBe(false);
+        });
+        it('returns true for substantial content', () => {
+            const content = 'Line one of content\nLine two of content\nLine three of content';
+            expect(isOcrMeaningful(content)).toBe(true);
+        });
+    });
+});

package/dist/tests/utils/parallel.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from 'vitest';
+import { chunkArray, parallelMap } from '../../utils/parallel.js';
+describe('parallelMap', () => {
+    it('should process items and return results in order', async () => {
+        const items = [1, 2, 3, 4, 5];
+        const fn = async (n) => n * 2;
+        const results = await parallelMap(items, fn, 2);
+        expect(results).toEqual([2, 4, 6, 8, 10]);
+    });
+    it('should respect concurrency limits', async () => {
+        const items = [100, 100, 100, 100];
+        let activeCount = 0;
+        let maxActive = 0;
+        const fn = async (ms) => {
+            activeCount++;
+            maxActive = Math.max(maxActive, activeCount);
+            await new Promise((resolve) => setTimeout(resolve, ms));
+            activeCount--;
+            return ms;
+        };
+        const concurrency = 2;
+        await parallelMap(items, fn, concurrency);
+        expect(maxActive).toBeLessThanOrEqual(concurrency);
+    });
+    it('should handle empty input array', async () => {
+        const results = await parallelMap([], async (x) => x, 2);
+        expect(results).toEqual([]);
+    });
+    it('should handle concurrency <= 0 by defaulting to 1', async () => {
+        const items = [1, 2, 3];
+        const fn = vi.fn(async (x) => x);
+        const results0 = await parallelMap(items, fn, 0);
+        expect(results0).toEqual([1, 2, 3]);
+        const resultsNeg = await parallelMap(items, fn, -5);
+        expect(resultsNeg).toEqual([1, 2, 3]);
+    });
+    it('should propagate errors and stop processing', async () => {
+        const items = [1, 2, 3, 4, 5];
+        const fn = async (n) => {
+            if (n === 3)
+                throw new Error('Failed');
+            return n;
+        };
+        await expect(parallelMap(items, fn, 2)).rejects.toThrow('Failed');
+    });
+});
+describe('chunkArray', () => {
+    it('should split array into chunks', () => {
+        const items = [1, 2, 3, 4, 5];
+        expect(chunkArray(items, 2)).toEqual([[1, 2], [3, 4], [5]]);
+        expect(chunkArray(items, 5)).toEqual([[1, 2, 3, 4, 5]]);
+        expect(chunkArray(items, 10)).toEqual([[1, 2, 3, 4, 5]]);
+    });
+    it('should handle empty array', () => {
+        expect(chunkArray([], 2)).toEqual([]);
+    });
+});

package/dist/tests/visual-observer.test.js

@@ -0,0 +1,175 @@
+/**
+ * Visual Observer Integration Tests
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { processSession } from '../actions/process-session.js';
+vi.mock('node:fs/promises', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        writeFile: vi.fn().mockResolvedValue(undefined),
+    };
+});
+// Mock data
+const mockRecording = {
+    id: 'test-recording-123',
+    source: {
+        type: 'cap',
+        originalPath: '/tmp/test.cap',
+    },
+    videoPath: '/tmp/test.mp4',
+    audioMicPath: '/tmp/mic.wav',
+    audioSystemPath: null,
+    duration: 60,
+    capturedAt: new Date(),
+};
+// Note: Transcript mock not used in current test setup
+// const _mockTranscript: Transcript = {
+//   fullText: 'Hello world',
+//   segments: [{ id: '1', start: 0, end: 5, text: 'Hello world' }],
+//   language: 'en',
+//   duration: 60,
+// };
+const mockVisualIndex = {
+    frames: [
+        {
+            index: 0,
+            timestamp: 0,
+            imagePath: '/tmp/frame_0.jpg',
+            ocrText: 'def foo(): pass',
+            clusterId: 0,
+            changeScore: 0,
+        },
+    ],
+    clusters: [
+        {
+            id: 0,
+            heuristicLabel: 'code-editor',
+            timeRange: [0, 60],
+            frameCount: 1,
+            representativeIdx: 0,
+            avgOcrCharacters: 15,
+            mediaIndicators: [],
+        },
+    ],
+    processingTime: { ocrMs: 100, clipMs: 100, totalMs: 200 },
+};
+// Mock for describeImages() - returns array of parsed VLM results (not VisualDescriptions)
+const mockVlmResults = [
+    {
+        index: 0,
+        timestamp: 0,
+        imagePath: '/tmp/frame_0.jpg',
+        activity: 'coding',
+        description: 'User is writing python code',
+        apps: ['VSCode'],
+        topics: ['python', 'programming'],
+    },
+];
+const mockStorageService = {
+    saveSession: vi.fn().mockResolvedValue(undefined),
+    loadSession: vi.fn().mockResolvedValue(null),
+    listSessions: vi.fn().mockResolvedValue([]),
+    saveArtifact: vi.fn().mockResolvedValue(undefined),
+    loadArtifacts: vi.fn().mockResolvedValue([]),
+};
+describe('Visual Observer Pipeline', () => {
+    it('should process session with visual intelligence', async () => {
+        // Mock services
+        const mockTranscriber = {
+            transcribe: vi.fn().mockResolvedValue({
+                fullText: '',
+                segments: [],
+                language: 'en',
+                duration: 0,
+            }),
+            transcribeSegment: vi.fn().mockResolvedValue(''),
+        };
+        const mockVideoService = {
+            extractFramesAtTimestamps: vi
+                .fn()
+                .mockResolvedValue(['/tmp/frame_0.jpg']),
+            extractFramesAtInterval: vi
+                .fn()
+                .mockResolvedValue([{ imagePath: '/tmp/frame_0.jpg', timestamp: 0 }]),
+            extractFramesAtTimestampsBatch: vi
+                .fn()
+                .mockResolvedValue([{ imagePath: '/tmp/frame_0.jpg', timestamp: 0 }]),
+            getMetadata: vi
+                .fn()
+                .mockResolvedValue({ duration: 60, width: 1920, height: 1080 }),
+            runVisualIndexing: vi.fn().mockResolvedValue(mockVisualIndex),
+            detectSceneChanges: vi.fn().mockResolvedValue([]),
+        };
+        const mockIntelligenceService = {
+            classify: vi.fn(),
+            classifySegment: vi.fn(),
+            extractMetadata: vi.fn(),
+            generate: vi.fn(),
+            describeImages: vi.fn().mockResolvedValue(mockVlmResults),
+            embedText: vi.fn(),
+            extractTopics: vi.fn(),
+            generateText: vi.fn().mockResolvedValue('Mock generated summary'),
+        };
+        const session = await processSession(mockRecording, mockTranscriber, mockVideoService, mockStorageService, mockIntelligenceService);
+        expect(session.id).toBe(mockRecording.id);
+        expect(session.visualLogs).toHaveLength(1);
+        expect(session.visualLogs[0].entries).toHaveLength(1);
+        const entry = session.visualLogs[0].entries[0];
+        expect(entry.description).toBe('User is writing python code');
+        expect(entry.heuristicLabel).toBe('code-editor');
+        expect(entry.ocrSummary).toContain('def foo()');
+    });
+    it('should skip VLM when discriminator rules say so', async () => {
+        // Case: Rich audio transcript overlaps with cluster
+        const richTranscript = {
+            fullText: 'I am writing a long explanation of this code for 60 seconds.',
+            segments: [
+                {
+                    id: '1',
+                    start: 0,
+                    end: 60,
+                    text: 'I am writing a long explanation of this code for 60 seconds.',
+                },
+            ],
+            language: 'en',
+            duration: 60,
+        };
+        // Cluster with high OCR density and audio overlap
+        const denseIndex = {
+            ...mockVisualIndex,
+            clusters: [
+                {
+                    ...mockVisualIndex.clusters[0],
+                    avgOcrCharacters: 2000, // High density
+                },
+            ],
+        };
+        const mockTranscriber = {
+            transcribe: vi.fn().mockResolvedValue(richTranscript),
+            transcribeSegment: vi.fn().mockResolvedValue(''),
+        };
+        const mockVideoService = {
+            // biome-ignore lint/suspicious/noExplicitAny: mock
+            ...vi.fn(), // Other methods mocked as needed
+            extractFramesAtTimestamps: vi.fn(),
+            extractFramesAtInterval: vi
+                .fn()
+                .mockResolvedValue([{ imagePath: '/tmp/f.jpg', timestamp: 0 }]),
+            runVisualIndexing: vi.fn().mockResolvedValue(denseIndex),
+        };
+        const mockIntelligenceService = {
+            classify: vi.fn(),
+            classifySegment: vi.fn(),
+            extractMetadata: vi.fn(),
+            generate: vi.fn(),
+            describeImages: vi.fn(), // Should NOT be called
+            embedText: vi.fn(),
+            extractTopics: vi.fn(),
+            generateText: vi.fn().mockResolvedValue('Mock generated summary'),
+        };
+        const session = await processSession(mockRecording, mockTranscriber, mockVideoService, mockStorageService, mockIntelligenceService);
+        expect(mockIntelligenceService.describeImages).not.toHaveBeenCalled();
+        expect(session.visualLogs[0].entries[0].description).toBeUndefined();
+    });
+});

package/dist/utils/id-normalization.js

@@ -0,0 +1,15 @@
+/**
+ * ID Normalization Utilities
+ */
+/**
+ * Normalizes a raw ID (e.g. from a folder name) by removing spaces and special characters.
+ */
+export function normalizeSessionId(rawId) {
+    return rawId
+        .replace(/\s+/g, '-') // Spaces → hyphens
+        .replace(/[()[\]{}]/g, '') // Remove brackets
+        .replace(/—/g, '-') // Em-dash → hyphen
+        .replace(/-+/g, '-') // Collapse multiple hyphens
+        .replace(/^-|-$/g, '') // Trim leading/trailing hyphens
+        .replace(/\.cap$/i, ''); // Remove .cap extension
+}