grepmind-core 0.1.0-alpha

package/dist/indexer/wal/sync-wal.test.js

@@ -0,0 +1,752 @@
+/**
+ * SyncWal Tests
+ *
+ * Tests for SyncWal business logic.
+ * Covers: task lifecycle, checkpoint, recovery, lock management, cancellation.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { SyncWal } from './sync-wal.js';
+import { FileWalStorage } from './file-storage.js';
+describe('SyncWal', () => {
+    let tempDir;
+    let storage;
+    let syncWal;
+    beforeEach(async () => {
+        tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'sync-wal-test-'));
+        storage = new FileWalStorage(tempDir);
+        // Use small checkpoint interval for testing
+        syncWal = new SyncWal(storage, { checkpointInterval: 5 });
+    });
+    afterEach(async () => {
+        // Cleanup
+        syncWal.stopHeartbeat();
+        await fs.rm(tempDir, { recursive: true, force: true });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // INITIALIZATION
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('Initialization', () => {
+        it('should initialize with no recovery plan when no previous task', async () => {
+            const plan = await syncWal.initialize();
+            expect(plan).toBeNull();
+        });
+        it('should restore LSN from manifest', async () => {
+            // Setup manifest with high LSN
+            await storage.writeManifest({
+                version: 1,
+                current: null,
+                lastCompleted: null,
+                walLsn: 100,
+                lastCheckpointLsn: 50,
+            });
+            await syncWal.initialize();
+            // Start a task and check LSN is restored
+            const taskId = await syncWal.startTask('notes', 10, 'hash');
+            // The new entry should have LSN >= 100
+            const entries = await storage.getAllEntries();
+            expect(entries[0].lsn).toBeGreaterThanOrEqual(100);
+            await syncWal.completeTask(taskId);
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // TASK LIFECYCLE
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('Task Lifecycle', () => {
+        it('should start a task and acquire lock', async () => {
+            const taskId = await syncWal.startTask('notes', 100, 'manifest-hash');
+            expect(taskId).toBeTruthy();
+            expect(syncWal.isRunning()).toBe(true);
+            expect(syncWal.getCurrentTaskId()).toBe(taskId);
+            // Lock should be acquired
+            const lock = await storage.getLock();
+            expect(lock).not.toBeNull();
+            expect(lock?.id).toBe(taskId);
+            expect(lock?.type).toBe('notes');
+            await syncWal.completeTask(taskId);
+        });
+        it('should write task:start entry to WAL', async () => {
+            const taskId = await syncWal.startTask('notes', 100, 'hash123');
+            const entries = await storage.getAllEntries();
+            expect(entries).toHaveLength(1);
+            expect(entries[0].op).toBe('task:start');
+            expect(entries[0].taskId).toBe(taskId);
+            expect(entries[0].data?.type).toBe('notes');
+            expect(entries[0].data?.totalFiles).toBe(100);
+            expect(entries[0].data?.manifestHash).toBe('hash123');
+            await syncWal.completeTask(taskId);
+        });
+        it('should create manifest with current task', async () => {
+            const taskId = await syncWal.startTask('notes', 100);
+            const manifest = await storage.getManifest();
+            expect(manifest?.current).not.toBeNull();
+            expect(manifest?.current?.id).toBe(taskId);
+            expect(manifest?.current?.type).toBe('notes');
+            expect(manifest?.current?.status).toBe('running');
+            expect(manifest?.current?.totalFiles).toBe(100);
+            await syncWal.completeTask(taskId);
+        });
+        it('should fail to start second task when one is running', async () => {
+            const taskId1 = await syncWal.startTask('notes', 100);
+            await expect(syncWal.startTask('code', 50)).rejects.toThrow(/another sync is already running/);
+            await syncWal.completeTask(taskId1);
+        });
+        it('should complete task and release lock', async () => {
+            const taskId = await syncWal.startTask('notes', 100);
+            await syncWal.completeTask(taskId);
+            expect(syncWal.isRunning()).toBe(false);
+            expect(await storage.getLock()).toBeNull();
+            // Manifest should have lastCompleted
+            const manifest = await storage.getManifest();
+            expect(manifest?.current).toBeNull();
+            expect(manifest?.lastCompleted).not.toBeNull();
+            expect(manifest?.lastCompleted?.id).toBe(taskId);
+            expect(manifest?.lastCompleted?.status).toBe('completed');
+        });
+        it('should fail task and release lock', async () => {
+            const taskId = await syncWal.startTask('notes', 100);
+            await syncWal.failTask(taskId, 'Something went wrong');
+            expect(syncWal.isRunning()).toBe(false);
+            expect(await storage.getLock()).toBeNull();
+            const manifest = await storage.getManifest();
+            expect(manifest?.lastCompleted?.status).toBe('failed');
+        });
+        it('should cancel task and release lock', async () => {
+            const taskId = await syncWal.startTask('notes', 100);
+            await syncWal.cancelTask(taskId);
+            expect(syncWal.isRunning()).toBe(false);
+            expect(await storage.getLock()).toBeNull();
+            const manifest = await storage.getManifest();
+            expect(manifest?.lastCompleted?.status).toBe('cancelled');
+        });
+        it('should throw when completing non-active task', async () => {
+            const taskId = await syncWal.startTask('notes', 100);
+            await syncWal.completeTask(taskId);
+            await expect(syncWal.completeTask(taskId)).rejects.toThrow(/Task not active/);
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // FILE PROCESSING
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('File Processing', () => {
+        it('should record file:done entry', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            await syncWal.fileProcessed(taskId, '/test.md', 3);
+            const entries = await storage.getAllEntries();
+            const fileEntry = entries.find((e) => e.op === 'file:done');
+            expect(fileEntry).toBeDefined();
+            expect(fileEntry?.data?.path).toBe('/test.md');
+            expect(fileEntry?.data?.chunks).toBe(3);
+            await syncWal.completeTask(taskId);
+        });
+        it('should track added vs updated files', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            await syncWal.fileProcessed(taskId, '/new.md', 1, 'added');
+            await syncWal.fileProcessed(taskId, '/existing.md', 1, 'updated');
+            const progress = syncWal.getProgress();
+            expect(progress?.added).toBe(1);
+            expect(progress?.updated).toBe(1);
+            await syncWal.completeTask(taskId);
+        });
+        it('should record file:fail entry', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            await syncWal.fileFailed(taskId, '/bad.md', 'Parse error', 3);
+            const entries = await storage.getAllEntries();
+            const failEntry = entries.find((e) => e.op === 'file:fail');
+            expect(failEntry).toBeDefined();
+            expect(failEntry?.data?.path).toBe('/bad.md');
+            expect(failEntry?.data?.error).toBe('Parse error');
+            expect(failEntry?.data?.retries).toBe(3);
+            const progress = syncWal.getProgress();
+            expect(progress?.failedCount).toBe(1);
+            await syncWal.completeTask(taskId);
+        });
+        it('should record deleted files', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            await syncWal.fileDeleted(taskId, '/removed.md');
+            const progress = syncWal.getProgress();
+            expect(progress?.deleted).toBe(1);
+            await syncWal.completeTask(taskId);
+        });
+        it('should throw when processing file for non-active task', async () => {
+            await expect(syncWal.fileProcessed('non-existent', '/test.md', 1)).rejects.toThrow(/Task not active/);
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CHECKPOINT
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('Checkpoint', () => {
+        it('should create checkpoint after configured interval', async () => {
+            // Using checkpointInterval: 5 from config
+            const taskId = await syncWal.startTask('notes', 20);
+            // Process 5 files to trigger checkpoint
+            for (let i = 0; i < 5; i++) {
+                await syncWal.fileProcessed(taskId, `/file-${i}.md`, 1);
+            }
+            const checkpoint = await storage.getCheckpoint();
+            expect(checkpoint).not.toBeNull();
+            expect(checkpoint?.task.processedCount).toBe(5);
+            await syncWal.completeTask(taskId);
+        });
+        it('should truncate WAL after checkpoint', async () => {
+            const taskId = await syncWal.startTask('notes', 20);
+            // Process files to trigger checkpoint
+            for (let i = 0; i < 6; i++) {
+                await syncWal.fileProcessed(taskId, `/file-${i}.md`, 1);
+            }
+            // WAL should be truncated - only entries from checkpoint onwards
+            const entries = await storage.getAllEntries();
+            // Should have: checkpoint entry + 1 file:done entry (6th file after checkpoint)
+            // WAL is truncated BEFORE checkpoint LSN, so checkpoint entry and later entries remain
+            expect(entries.length).toBeLessThan(10);
+            await syncWal.completeTask(taskId);
+        });
+        it('should accumulate stats across checkpoints', async () => {
+            const taskId = await syncWal.startTask('notes', 15);
+            // First batch (triggers checkpoint)
+            for (let i = 0; i < 5; i++) {
+                await syncWal.fileProcessed(taskId, `/batch1-${i}.md`, 1, 'added');
+            }
+            // Second batch (triggers another checkpoint)
+            for (let i = 0; i < 5; i++) {
+                await syncWal.fileProcessed(taskId, `/batch2-${i}.md`, 1, 'updated');
+            }
+            const progress = syncWal.getProgress();
+            expect(progress?.processedFiles).toBe(10);
+            expect(progress?.added).toBe(5);
+            expect(progress?.updated).toBe(5);
+            await syncWal.completeTask(taskId);
+        });
+        it('should update manifest on checkpoint', async () => {
+            const taskId = await syncWal.startTask('notes', 20);
+            for (let i = 0; i < 5; i++) {
+                await syncWal.fileProcessed(taskId, `/file-${i}.md`, 1);
+            }
+            const manifest = await storage.getManifest();
+            expect(manifest?.current?.processedFiles).toBe(5);
+            await syncWal.completeTask(taskId);
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // RECOVERY
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('Recovery', () => {
+        it('should return recovery plan for incomplete task', async () => {
+            // Simulate crashed task by writing checkpoint directly
+            const now = Date.now();
+            await storage.writeCheckpoint({
+                version: 1,
+                lsn: 100,
+                createdAt: now,
+                task: {
+                    id: 'crashed-task',
+                    type: 'notes',
+                    status: 'running',
+                    startedAt: now - 10000,
+                    totalFiles: 1000,
+                    processedCount: 500,
+                    manifestHash: 'hash123',
+                },
+                stats: {
+                    added: 200,
+                    updated: 300,
+                    deleted: 0,
+                    failed: [],
+                },
+            });
+            // Add some WAL entries after checkpoint
+            await storage.appendEntry({
+                lsn: 101,
+                ts: now,
+                op: 'file:done',
+                taskId: 'crashed-task',
+                data: { path: '/file501.md', chunks: 1 },
+            });
+            await storage.appendEntry({
+                lsn: 102,
+                ts: now,
+                op: 'file:done',
+                taskId: 'crashed-task',
+                data: { path: '/file502.md', chunks: 1 },
+            });
+            const plan = await syncWal.recover();
+            expect(plan).not.toBeNull();
+            expect(plan?.taskId).toBe('crashed-task');
+            expect(plan?.type).toBe('notes');
+            expect(plan?.totalFiles).toBe(1000);
+            expect(plan?.skipCount).toBe(502); // 500 from checkpoint + 2 from WAL
+            expect(plan?.manifestHash).toBe('hash123');
+            expect(plan?.stats.added).toBe(200);
+            expect(plan?.stats.updated).toBe(300);
+        });
+        it('should return null when no incomplete task', async () => {
+            // Complete task checkpoint
+            await storage.writeCheckpoint({
+                version: 1,
+                lsn: 100,
+                createdAt: Date.now(),
+                task: {
+                    id: 'completed-task',
+                    type: 'notes',
+                    status: 'completed',
+                    startedAt: Date.now(),
+                    totalFiles: 100,
+                    processedCount: 100,
+                },
+                stats: {
+                    added: 100,
+                    updated: 0,
+                    deleted: 0,
+                    failed: [],
+                },
+            });
+            const plan = await syncWal.recover();
+            expect(plan).toBeNull();
+        });
+        it('should resume task from recovery plan', async () => {
+            // Setup recovery scenario
+            const now = Date.now();
+            await storage.writeCheckpoint({
+                version: 1,
+                lsn: 50,
+                createdAt: now,
+                task: {
+                    id: 'resume-task',
+                    type: 'code',
+                    status: 'running',
+                    startedAt: now - 10000,
+                    totalFiles: 100,
+                    processedCount: 25,
+                    manifestHash: 'hash456',
+                },
+                stats: {
+                    added: 10,
+                    updated: 15,
+                    deleted: 0,
+                    failed: [{ path: '/bad.ts', error: 'Syntax error', retries: 3 }],
+                },
+            });
+            const plan = await syncWal.recover();
+            expect(plan).not.toBeNull();
+            await syncWal.resumeTask(plan);
+            expect(syncWal.isRunning()).toBe(true);
+            expect(syncWal.getCurrentTaskId()).toBe('resume-task');
+            const progress = syncWal.getProgress();
+            expect(progress?.type).toBe('code');
+            expect(progress?.processedFiles).toBe(25);
+            expect(progress?.added).toBe(10);
+            expect(progress?.updated).toBe(15);
+            expect(progress?.failedCount).toBe(1);
+            await syncWal.completeTask('resume-task');
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // LOCK MANAGEMENT
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('Lock Management', () => {
+        it('should detect no lock', async () => {
+            const status = await syncWal.isLocked();
+            expect(status.locked).toBe(false);
+            expect(status.stale).toBe(false);
+        });
+        it('should detect active lock', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            const status = await syncWal.isLocked();
+            expect(status.locked).toBe(true);
+            expect(status.stale).toBe(false);
+            expect(status.lock?.id).toBe(taskId);
+            await syncWal.completeTask(taskId);
+        });
+        it('should detect stale lock by heartbeat', async () => {
+            // Create lock with old heartbeat
+            await storage.acquireLock({
+                id: 'old-task',
+                type: 'notes',
+                pid: process.pid,
+                startedAt: Date.now() - 300000,
+                heartbeat: Date.now() - 300000, // 5 minutes ago
+            });
+            // Create SyncWal with short timeout for testing
+            const shortTimeoutWal = new SyncWal(storage, { staleLockTimeout: 1000 });
+            const status = await shortTimeoutWal.isLocked();
+            expect(status.locked).toBe(true);
+            expect(status.stale).toBe(true);
+        });
+        it('should detect stale lock by dead PID', async () => {
+            // Create lock with non-existent PID
+            await storage.acquireLock({
+                id: 'dead-task',
+                type: 'notes',
+                pid: 999999999, // Very high, unlikely to exist
+                startedAt: Date.now(),
+                heartbeat: Date.now(),
+            });
+            const status = await syncWal.isLocked();
+            expect(status.locked).toBe(true);
+            expect(status.stale).toBe(true);
+        });
+        it('should force clear stale lock', async () => {
+            // Create stale lock
+            await storage.acquireLock({
+                id: 'stale-task',
+                type: 'notes',
+                pid: 999999999,
+                startedAt: Date.now(),
+                heartbeat: Date.now() - 300000,
+            });
+            const shortTimeoutWal = new SyncWal(storage, { staleLockTimeout: 1000 });
+            const cleared = await shortTimeoutWal.forceClearStaleLock();
+            expect(cleared).toBe(true);
+            expect(await storage.getLock()).toBeNull();
+        });
+        it('should not force clear active lock', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            const cleared = await syncWal.forceClearStaleLock();
+            expect(cleared).toBe(false);
+            expect((await storage.getLock())?.id).toBe(taskId);
+            await syncWal.completeTask(taskId);
+        });
+        it('should acquire lock by clearing stale lock', async () => {
+            // Create stale lock
+            await storage.acquireLock({
+                id: 'stale-task',
+                type: 'notes',
+                pid: 999999999,
+                startedAt: Date.now(),
+                heartbeat: Date.now() - 300000,
+            });
+            const shortTimeoutWal = new SyncWal(storage, { staleLockTimeout: 1000 });
+            const taskId = await shortTimeoutWal.startTask('notes', 10);
+            expect(taskId).toBeTruthy();
+            expect((await storage.getLock())?.id).toBe(taskId);
+            await shortTimeoutWal.completeTask(taskId);
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CANCELLATION
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('Cancellation', () => {
+        it('should request cancellation', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            await syncWal.requestCancel(taskId);
+            expect(syncWal.isCancelled(taskId)).toBe(true);
+            await syncWal.cancelTask(taskId);
+        });
+        it('should not mark non-requested task as cancelled', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            expect(syncWal.isCancelled(taskId)).toBe(false);
+            expect(syncWal.isCancelled('other-task')).toBe(false);
+            await syncWal.completeTask(taskId);
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PROGRESS
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('Progress', () => {
+        it('should return null when no task running', () => {
+            const progress = syncWal.getProgress();
+            expect(progress).toBeNull();
+        });
+        it('should return progress for running task', async () => {
+            const taskId = await syncWal.startTask('notes', 100, 'hash');
+            await syncWal.fileProcessed(taskId, '/a.md', 1, 'added');
+            await syncWal.fileProcessed(taskId, '/b.md', 1, 'updated');
+            await syncWal.fileFailed(taskId, '/c.md', 'error', 0);
+            const progress = syncWal.getProgress();
+            expect(progress).not.toBeNull();
+            expect(progress?.taskId).toBe(taskId);
+            expect(progress?.type).toBe('notes');
+            expect(progress?.status).toBe('running');
+            expect(progress?.phase).toBe('indexing');
+            expect(progress?.totalFiles).toBe(100);
+            expect(progress?.processedFiles).toBe(3);
+            expect(progress?.added).toBe(1);
+            expect(progress?.updated).toBe(1);
+            expect(progress?.failedCount).toBe(1);
+            expect(progress?.elapsedMs).toBeGreaterThan(0);
+            await syncWal.completeTask(taskId);
+        });
+        it('should estimate remaining time', async () => {
+            const taskId = await syncWal.startTask('notes', 100);
+            // Process some files with a small delay
+            for (let i = 0; i < 10; i++) {
+                await syncWal.fileProcessed(taskId, `/file-${i}.md`, 1);
+                await new Promise((r) => setTimeout(r, 5)); // Small delay
+            }
+            const progress = syncWal.getProgress();
+            expect(progress?.estimatedRemainingMs).toBeDefined();
+            expect(progress?.estimatedRemainingMs).toBeGreaterThan(0);
+            await syncWal.completeTask(taskId);
+        });
+        it('should emit progress via callback', async () => {
+            const progressUpdates = [];
+            syncWal.onProgress((p) => progressUpdates.push(p));
+            const taskId = await syncWal.startTask('notes', 10);
+            // Should have initial progress
+            expect(progressUpdates.length).toBeGreaterThan(0);
+            await syncWal.completeTask(taskId);
+            // Should have final progress with phase 'done'
+            const lastProgress = progressUpdates[progressUpdates.length - 1];
+            expect(lastProgress.phase).toBe('done');
+        });
+        it('should update phase', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            syncWal.setPhase('deleting');
+            expect(syncWal.getProgress()?.phase).toBe('deleting');
+            syncWal.setPhase('analyzing');
+            expect(syncWal.getProgress()?.phase).toBe('analyzing');
+            await syncWal.completeTask(taskId);
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STATE QUERIES
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('State Queries', () => {
+        it('should get manifest', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            const manifest = await syncWal.getManifest();
+            expect(manifest).not.toBeNull();
+            expect(manifest?.current?.id).toBe(taskId);
+            await syncWal.completeTask(taskId);
+        });
+        it('should get current task', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            const task = await syncWal.getCurrentTask();
+            expect(task).not.toBeNull();
+            expect(task?.id).toBe(taskId);
+            await syncWal.completeTask(taskId);
+            expect(await syncWal.getCurrentTask()).toBeNull();
+        });
+        it('should get last completed task', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            await syncWal.completeTask(taskId);
+            const lastCompleted = await syncWal.getLastCompleted();
+            expect(lastCompleted).not.toBeNull();
+            expect(lastCompleted?.id).toBe(taskId);
+            expect(lastCompleted?.status).toBe('completed');
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // HEARTBEAT
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('Heartbeat', () => {
+        it('should update heartbeat periodically', async () => {
+            // Use very short heartbeat for testing
+            const fastHeartbeatWal = new SyncWal(storage, {
+                heartbeatInterval: 50,
+                checkpointInterval: 100,
+            });
+            const taskId = await fastHeartbeatWal.startTask('notes', 10);
+            const initialLock = await storage.getLock();
+            const initialHeartbeat = initialLock.heartbeat;
+            // Wait for heartbeat update
+            await new Promise((r) => setTimeout(r, 100));
+            const updatedLock = await storage.getLock();
+            expect(updatedLock.heartbeat).toBeGreaterThan(initialHeartbeat);
+            fastHeartbeatWal.stopHeartbeat();
+            await fastHeartbeatWal.completeTask(taskId);
+        });
+        it('should stop heartbeat on task complete', async () => {
+            const taskId = await syncWal.startTask('notes', 10);
+            await syncWal.completeTask(taskId);
+            // Heartbeat should be stopped (no errors when lock is released)
+            await new Promise((r) => setTimeout(r, 50));
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // GRACEFUL SHUTDOWN
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('Graceful Shutdown', () => {
+        it('should checkpoint and release lock on shutdown', async () => {
+            const taskId = await syncWal.startTask('notes', 20);
+            // Process some files
+            for (let i = 0; i < 3; i++) {
+                await syncWal.fileProcessed(taskId, `/file-${i}.md`, 1);
+            }
+            await syncWal.shutdown();
+            // Lock should be released
+            expect(await storage.getLock()).toBeNull();
+            // Checkpoint should have latest state
+            const checkpoint = await storage.getCheckpoint();
+            expect(checkpoint?.task.processedCount).toBe(3);
+        });
+        it('should handle shutdown with no active task', async () => {
+            await expect(syncWal.shutdown()).resolves.not.toThrow();
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CLEAR WAL STATE
+    // ═══════════════════════════════════════════════════════════════════════════
+    describe('Clear WAL State', () => {
+        it('should clear all WAL state and reset to initial', async () => {
+            // Start a task and process some files
+            const taskId = await syncWal.startTask('notes', 10);
+            await syncWal.fileProcessed(taskId, '/test1.md', 1);
+            await syncWal.fileProcessed(taskId, '/test2.md', 1);
+            // Verify state exists before clear
+            expect(await storage.getLock()).not.toBeNull();
+            expect(syncWal.isRunning()).toBe(true);
+            // Clear all state
+            await syncWal.clear();
+            // Verify everything is cleared
+            expect(await storage.getLock()).toBeNull();
+            expect(await storage.getCheckpoint()).toBeNull();
+            expect(await storage.getManifest()).toBeNull();
+            expect(syncWal.isRunning()).toBe(false);
+            expect(syncWal.getCurrentTaskId()).toBeNull();
+            // Should be able to start fresh
+            const newTaskId = await syncWal.startTask('notes', 5);
+            expect(newTaskId).toBeDefined();
+            await syncWal.completeTask(newTaskId);
+        });
+        it('should clear recovery state when stuck in recovery loop', async () => {
+            // Simulate stuck recovery state: start task, checkpoint, then simulate crash
+            const taskId = await syncWal.startTask('notes', 100);
+            for (let i = 0; i < 10; i++) {
+                await syncWal.fileProcessed(taskId, `/file-${i}.md`, 1);
+            }
+            await syncWal.checkpoint();
+            // Simulate crash by creating new SyncWal without completing task
+            const crashedWal = new SyncWal(storage);
+            const recoveryPlan = await crashedWal.recover();
+            expect(recoveryPlan).not.toBeNull();
+            expect(recoveryPlan?.taskId).toBe(taskId);
+            // Clear should remove recovery state
+            await crashedWal.clear();
+            // No more recovery needed
+            const noRecovery = await crashedWal.recover();
+            expect(noRecovery).toBeNull();
+        });
+        it('should handle clear with no active state', async () => {
+            // Clear on fresh instance should not throw
+            await expect(syncWal.clear()).resolves.not.toThrow();
+        });
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// ERROR HANDLING TESTS
+// ═══════════════════════════════════════════════════════════════════════════
+describe('Error Handling', () => {
+    let tempDir;
+    let storage;
+    beforeEach(async () => {
+        tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'sync-wal-err-'));
+        storage = new FileWalStorage(tempDir);
+    });
+    afterEach(async () => {
+        await fs.rm(tempDir, { recursive: true, force: true });
+    });
+    it('should release lock if startTask fails after acquiring lock', async () => {
+        // Create mock storage that fails on appendEntry
+        const failingStorage = {
+            acquireLock: vi.fn(async () => true),
+            releaseLock: vi.fn(async () => { }),
+            getLock: vi.fn(async () => null),
+            updateHeartbeat: vi.fn(async () => { }),
+            appendEntry: vi.fn(async () => {
+                throw new Error('WAL write failed');
+            }),
+            getEntriesFromLsn: vi.fn(async () => []),
+            truncateBeforeLsn: vi.fn(async () => { }),
+            writeCheckpoint: vi.fn(async () => { }),
+            getCheckpoint: vi.fn(async () => null),
+            writeManifest: vi.fn(async () => { }),
+            getManifest: vi.fn(async () => null),
+            clear: vi.fn(async () => { }),
+        };
+        const wal = new SyncWal(failingStorage);
+        // startTask should fail and release the lock
+        await expect(wal.startTask('notes', 10)).rejects.toThrow('WAL write failed');
+        // Lock should have been released
+        expect(failingStorage.releaseLock).toHaveBeenCalled();
+        // SyncWal state should be clean
+        expect(wal.isRunning()).toBe(false);
+        expect(wal.getCurrentTaskId()).toBeNull();
+        wal.stopHeartbeat();
+    });
+    it('should release lock if manifest write fails', async () => {
+        // Create mock storage that fails on writeManifest
+        const failingStorage = {
+            acquireLock: vi.fn(async () => true),
+            releaseLock: vi.fn(async () => { }),
+            getLock: vi.fn(async () => null),
+            updateHeartbeat: vi.fn(async () => { }),
+            appendEntry: vi.fn(async () => { }),
+            getEntriesFromLsn: vi.fn(async () => []),
+            truncateBeforeLsn: vi.fn(async () => { }),
+            writeCheckpoint: vi.fn(async () => { }),
+            getCheckpoint: vi.fn(async () => null),
+            writeManifest: vi.fn(async () => {
+                throw new Error('Manifest write failed');
+            }),
+            getManifest: vi.fn(async () => null),
+            clear: vi.fn(async () => { }),
+        };
+        const wal = new SyncWal(failingStorage);
+        await expect(wal.startTask('notes', 10)).rejects.toThrow('Manifest write failed');
+        expect(failingStorage.releaseLock).toHaveBeenCalled();
+        expect(wal.isRunning()).toBe(false);
+        wal.stopHeartbeat();
+    });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// MOCK STORAGE TESTS
+// ═══════════════════════════════════════════════════════════════════════════
+describe('SyncWal with Mock Storage', () => {
+    it('should work with any WalStorage implementation', async () => {
+        // Simple in-memory mock
+        const mockEntries = [];
+        let mockLock = null;
+        let mockCheckpoint = null;
+        let mockManifest = null;
+        const mockStorage = {
+            acquireLock: vi.fn(async (lock) => {
+                if (mockLock)
+                    return false;
+                mockLock = lock;
+                return true;
+            }),
+            releaseLock: vi.fn(async (id) => {
+                if (mockLock?.id === id)
+                    mockLock = null;
+            }),
+            getLock: vi.fn(async () => mockLock),
+            updateHeartbeat: vi.fn(async () => { }),
+            appendEntry: vi.fn(async (entry) => {
+                mockEntries.push(entry);
+            }),
+            getEntriesFromLsn: vi.fn(async (lsn) => mockEntries.filter((e) => e.lsn >= lsn)),
+            truncateBeforeLsn: vi.fn(async (lsn) => {
+                const kept = mockEntries.filter((e) => e.lsn >= lsn);
+                mockEntries.length = 0;
+                mockEntries.push(...kept);
+            }),
+            writeCheckpoint: vi.fn(async (data) => {
+                mockCheckpoint = data;
+            }),
+            getCheckpoint: vi.fn(async () => mockCheckpoint),
+            writeManifest: vi.fn(async (data) => {
+                mockManifest = data;
+            }),
+            getManifest: vi.fn(async () => mockManifest),
+            clear: vi.fn(async () => {
+                mockEntries.length = 0;
+                mockLock = null;
+                mockCheckpoint = null;
+                mockManifest = null;
+            }),
+        };
+        const wal = new SyncWal(mockStorage, { checkpointInterval: 100 });
+        const taskId = await wal.startTask('notes', 50);
+        expect(mockStorage.acquireLock).toHaveBeenCalled();
+        expect(mockStorage.appendEntry).toHaveBeenCalled();
+        expect(mockStorage.writeManifest).toHaveBeenCalled();
+        await wal.fileProcessed(taskId, '/test.md', 1);
+        await wal.completeTask(taskId);
+        expect(mockStorage.releaseLock).toHaveBeenCalled();
+        wal.stopHeartbeat();
+    });
+});
+//# sourceMappingURL=sync-wal.test.js.map