vectra 0.12.2 → 0.14.0

package/src/codecs/LocalIndex.protobuf.spec.ts

@@ -0,0 +1,115 @@
+import assert from 'node:assert';
+import { LocalIndex } from '../LocalIndex';
+import { VirtualFileStorage } from '../storage';
+import { ProtobufCodec } from './ProtobufCodec';
+
+describe('LocalIndex with ProtobufCodec', () => {
+    const codec = new ProtobufCodec();
+
+    it('creates index with .pb extension', async () => {
+        const storage = new VirtualFileStorage();
+        const index = new LocalIndex('mem://idx', undefined, storage, codec);
+        assert.equal(index.indexName, 'index.pb');
+        await index.createIndex();
+        assert.equal(await index.isIndexCreated(), true);
+    });
+
+    it('full CRUD operations produce correct results', async () => {
+        const storage = new VirtualFileStorage();
+        const index = new LocalIndex('mem://idx', undefined, storage, codec);
+        await index.createIndex();
+
+        // Insert
+        await index.insertItem({ id: 'a', vector: [1, 0, 0], metadata: { cat: 'x' } });
+        await index.insertItem({ id: 'b', vector: [0, 1, 0], metadata: { cat: 'y' } });
+
+        // List
+        const items = await index.listItems();
+        assert.equal(items.length, 2);
+        assert.equal(items[0].id, 'a');
+
+        // Get
+        const item = await index.getItem('a');
+        assert.ok(item);
+        assert.equal(item.metadata.cat, 'x');
+
+        // Query
+        const results = await index.queryItems([1, 0, 0], '', 1);
+        assert.equal(results.length, 1);
+        assert.equal(results[0].item.id, 'a');
+
+        // Upsert
+        await index.upsertItem({ id: 'a', vector: [0, 0, 1], metadata: { cat: 'z' } });
+        const updated = await index.getItem('a');
+        assert.equal(updated?.metadata.cat, 'z');
+
+        // Delete
+        await index.deleteItem('b');
+        const remaining = await index.listItems();
+        assert.equal(remaining.length, 1);
+        assert.equal(remaining[0].id, 'a');
+
+        // Stats
+        const stats = await index.getIndexStats();
+        assert.equal(stats.items, 1);
+    });
+
+    it('batch insert works', async () => {
+        const storage = new VirtualFileStorage();
+        const index = new LocalIndex('mem://idx', undefined, storage, codec);
+        await index.createIndex();
+
+        await index.batchInsertItems([
+            { id: '1', vector: [1, 0, 0] },
+            { id: '2', vector: [0, 1, 0] },
+            { id: '3', vector: [0, 0, 1] },
+        ]);
+
+        const items = await index.listItems();
+        assert.equal(items.length, 3);
+    });
+
+    it('metadata filtering works with protobuf storage', async () => {
+        const storage = new VirtualFileStorage();
+        const index = new LocalIndex('mem://idx', undefined, storage, codec);
+        await index.createIndex();
+
+        await index.batchInsertItems([
+            { id: '1', vector: [1, 0], metadata: { category: 'food' } },
+            { id: '2', vector: [0, 1], metadata: { category: 'drink' } },
+        ]);
+
+        const food = await index.listItemsByMetadata({ category: { $eq: 'food' } });
+        assert.equal(food.length, 1);
+        assert.equal(food[0].id, '1');
+    });
+
+    it('external metadata files use .pb extension', async () => {
+        const storage = new VirtualFileStorage();
+        const index = new LocalIndex('mem://idx', undefined, storage, codec);
+        await index.createIndex({ version: 1, metadata_config: { indexed: ['keep'] } });
+
+        await index.insertItem({ id: 'm1', vector: [1], metadata: { keep: 'x', extra: 'y' } });
+
+        const items = await index.listItems();
+        const stored = items.find(i => i.id === 'm1')!;
+        assert.ok(stored.metadataFile);
+        assert.ok(stored.metadataFile.endsWith('.pb'), `Expected .pb extension, got: ${stored.metadataFile}`);
+    });
+
+    it('persists and reloads across instances', async () => {
+        const storage = new VirtualFileStorage();
+
+        // First instance: create and populate
+        const idx1 = new LocalIndex('mem://idx', undefined, storage, codec);
+        await idx1.createIndex();
+        await idx1.insertItem({ id: 'persist', vector: [1, 2, 3], metadata: { key: 'val' } });
+
+        // Second instance: should read persisted data
+        const idx2 = new LocalIndex('mem://idx', undefined, storage, codec);
+        const item = await idx2.getItem('persist');
+        assert.ok(item);
+        assert.equal(item.id, 'persist');
+        assert.equal(item.metadata.key, 'val');
+    });
+});

package/src/codecs/ProtobufCodec.spec.ts

@@ -0,0 +1,166 @@
+import assert from 'node:assert';
+import { ProtobufCodec } from './ProtobufCodec';
+import { JsonCodec } from './JsonCodec';
+import { IndexData } from '../types';
+import { DocumentCatalog } from './IndexCodec';
+
+describe('ProtobufCodec', () => {
+    const codec = new ProtobufCodec();
+
+    it('has .pb extension', () => {
+        assert.equal(codec.extension, '.pb');
+    });
+
+    describe('serializeIndex / deserializeIndex', () => {
+        it('round-trips IndexData', () => {
+            const data: IndexData = {
+                version: 1,
+                metadata_config: { indexed: ['category'] },
+                items: [
+                    { id: 'a', metadata: { category: 'food', score: 42 }, vector: [1.5, 2.5, 3.5], norm: 4.5 },
+                    { id: 'b', metadata: {}, vector: [0, 0, 0], norm: 0, metadataFile: 'ext.pb' },
+                ],
+            };
+            const buf = codec.serializeIndex(data);
+            assert.ok(Buffer.isBuffer(buf));
+            const result = codec.deserializeIndex(buf);
+            assert.equal(result.version, data.version);
+            assert.deepStrictEqual(result.metadata_config, data.metadata_config);
+            assert.equal(result.items.length, 2);
+            assert.equal(result.items[0].id, 'a');
+            assert.deepStrictEqual(result.items[0].metadata, { category: 'food', score: 42 });
+            // Float32 precision: vectors should be close but not exact
+            assert.ok(Math.abs(result.items[0].vector[0] - 1.5) < 0.001);
+            assert.ok(Math.abs(result.items[0].vector[1] - 2.5) < 0.001);
+            assert.ok(Math.abs(result.items[0].vector[2] - 3.5) < 0.001);
+            assert.equal(result.items[0].norm, 4.5); // norm is double, exact
+            assert.equal(result.items[1].metadataFile, 'ext.pb');
+        });
+
+        it('handles empty items', () => {
+            const data: IndexData = { version: 2, metadata_config: {}, items: [] };
+            const result = codec.deserializeIndex(codec.serializeIndex(data));
+            assert.equal(result.version, 2);
+            assert.deepStrictEqual(result.items, []);
+        });
+
+        it('handles boolean metadata values', () => {
+            const data: IndexData = {
+                version: 1,
+                metadata_config: {},
+                items: [
+                    { id: 'x', metadata: { active: true, deleted: false }, vector: [1], norm: 1 },
+                ],
+            };
+            // Note: false/0/"" are proto3 default values — test the tricky case
+            const result = codec.deserializeIndex(codec.serializeIndex(data));
+            assert.equal(result.items[0].metadata.active, true);
+        });
+
+        it('handles string metadata', () => {
+            const data: IndexData = {
+                version: 1,
+                metadata_config: {},
+                items: [
+                    { id: 'x', metadata: { name: 'hello', tag: 'world' }, vector: [1], norm: 1 },
+                ],
+            };
+            const result = codec.deserializeIndex(codec.serializeIndex(data));
+            assert.equal(result.items[0].metadata.name, 'hello');
+            assert.equal(result.items[0].metadata.tag, 'world');
+        });
+    });
+
+    describe('serializeCatalog / deserializeCatalog', () => {
+        it('round-trips DocumentCatalog', () => {
+            const catalog: DocumentCatalog = {
+                version: 1,
+                count: 2,
+                uriToId: { 'http://a': 'id-a', 'http://b': 'id-b' },
+                idToUri: { 'id-a': 'http://a', 'id-b': 'http://b' },
+            };
+            const buf = codec.serializeCatalog(catalog);
+            assert.ok(Buffer.isBuffer(buf));
+            const result = codec.deserializeCatalog(buf);
+            assert.deepStrictEqual(result, catalog);
+        });
+
+        it('handles empty catalog', () => {
+            const catalog: DocumentCatalog = { version: 1, count: 0, uriToId: {}, idToUri: {} };
+            const result = codec.deserializeCatalog(codec.serializeCatalog(catalog));
+            assert.deepStrictEqual(result, catalog);
+        });
+    });
+
+    describe('serializeMetadata / deserializeMetadata', () => {
+        it('round-trips metadata (uses JSON for external files)', () => {
+            const metadata = { name: 'test', score: 42, active: true };
+            const buf = codec.serializeMetadata(metadata);
+            const result = codec.deserializeMetadata(buf);
+            assert.deepStrictEqual(result, metadata);
+        });
+    });
+
+    describe('cross-codec compatibility', () => {
+        const json = new JsonCodec();
+        const pb = new ProtobufCodec();
+
+        it('data serialized with JSON can be re-serialized with Protobuf and back (logical equivalence)', () => {
+            const data: IndexData = {
+                version: 1,
+                metadata_config: { indexed: ['cat'] },
+                items: [
+                    { id: 'item1', metadata: { cat: 'a', num: 7 }, vector: [0.1, 0.2, 0.3], norm: 0.374 },
+                ],
+            };
+            // JSON -> Protobuf
+            const jsonBuf = json.serializeIndex(data);
+            const fromJson = json.deserializeIndex(jsonBuf);
+            const pbBuf = pb.serializeIndex(fromJson);
+            const fromPb = pb.deserializeIndex(pbBuf);
+
+            assert.equal(fromPb.version, data.version);
+            assert.deepStrictEqual(fromPb.metadata_config, data.metadata_config);
+            assert.equal(fromPb.items[0].id, data.items[0].id);
+            assert.deepStrictEqual(fromPb.items[0].metadata, data.items[0].metadata);
+
+            // Protobuf -> JSON
+            const jsonBuf2 = json.serializeIndex(fromPb);
+            const final = json.deserializeIndex(jsonBuf2);
+            assert.equal(final.items[0].id, 'item1');
+            assert.deepStrictEqual(final.items[0].metadata, { cat: 'a', num: 7 });
+        });
+
+        it('catalog round-trips across codecs', () => {
+            const catalog: DocumentCatalog = {
+                version: 1,
+                count: 1,
+                uriToId: { 'file://doc.txt': 'uuid-1' },
+                idToUri: { 'uuid-1': 'file://doc.txt' },
+            };
+            const pbBuf = pb.serializeCatalog(catalog);
+            const fromPb = pb.deserializeCatalog(pbBuf);
+            const jsonBuf = json.serializeCatalog(fromPb);
+            const final = json.deserializeCatalog(jsonBuf);
+            assert.deepStrictEqual(final, catalog);
+        });
+    });
+
+    describe('protobuf produces smaller output than JSON for vector data', () => {
+        it('binary is smaller than JSON for a 1536-dim vector', () => {
+            const vector = Array.from({ length: 1536 }, (_, i) => Math.random() * 2 - 1);
+            const norm = Math.sqrt(vector.reduce((s, v) => s + v * v, 0));
+            const data: IndexData = {
+                version: 1,
+                metadata_config: {},
+                items: [{ id: 'vec', metadata: {}, vector, norm }],
+            };
+            const jsonSize = new JsonCodec().serializeIndex(data).length;
+            const pbSize = codec.serializeIndex(data).length;
+            // Protobuf should be significantly smaller
+            assert.ok(pbSize < jsonSize, `Expected pb (${pbSize}) < json (${jsonSize})`);
+            // Spec says ~40-50% savings
+            assert.ok(pbSize < jsonSize * 0.7, `Expected at least 30% savings, got ${((1 - pbSize / jsonSize) * 100).toFixed(1)}%`);
+        });
+    });
+});

package/src/codecs/ProtobufCodec.ts

@@ -0,0 +1,193 @@
+import * as path from 'path';
+import { IndexData, IndexItem, MetadataTypes } from '../types';
+import { DocumentCatalog, IndexCodec } from './IndexCodec';
+
+let protobuf: typeof import('protobufjs') | undefined;
+
+function loadProtobuf(): typeof import('protobufjs') {
+    if (!protobuf) {
+        try {
+            protobuf = require('protobufjs');
+        } catch {
+            throw new Error(
+                "ProtobufCodec requires the 'protobufjs' package. Install it with: npm install protobufjs"
+            );
+        }
+    }
+    return protobuf!;
+}
+
+// Cached proto root — loaded once per process
+let cachedRoot: any;
+
+function getRoot(): any {
+    if (!cachedRoot) {
+        const pb = loadProtobuf();
+        cachedRoot = pb.loadSync(path.join(__dirname, 'schemas', 'index.proto'));
+    }
+    return cachedRoot;
+}
+
+/** Convert MetadataTypes value to protobuf MetadataValue shape */
+function toProtoMetadataValue(value: MetadataTypes): Record<string, any> {
+    if (typeof value === 'string') return { stringValue: value };
+    if (typeof value === 'number') return { numberValue: value };
+    if (typeof value === 'boolean') return { boolValue: value };
+    return { stringValue: String(value) };
+}
+
+/** Convert protobuf MetadataValue back to MetadataTypes */
+function fromProtoMetadataValue(mv: any): MetadataTypes {
+    if (mv.stringValue !== undefined && mv.stringValue !== '') return mv.stringValue;
+    if (mv.numberValue !== undefined && mv.numberValue !== 0) return mv.numberValue;
+    if (mv.boolValue !== undefined && mv.boolValue !== false) return mv.boolValue;
+    // Disambiguate zero-value fields by checking which oneof field is set
+    if (mv.value === 'boolValue') return false;
+    if (mv.value === 'numberValue') return 0;
+    if (mv.value === 'stringValue') return '';
+    // Fallback — proto3 defaults make this tricky; prefer string empty
+    return '';
+}
+
+/** Convert JS IndexItem to proto-friendly shape */
+function toProtoItem(item: IndexItem): Record<string, any> {
+    const metadata: Record<string, any> = {};
+    if (item.metadata) {
+        for (const [k, v] of Object.entries(item.metadata)) {
+            metadata[k] = toProtoMetadataValue(v as MetadataTypes);
+        }
+    }
+    const out: Record<string, any> = {
+        id: item.id,
+        metadata,
+        vector: item.vector,
+        norm: item.norm,
+    };
+    if (item.metadataFile) {
+        out.metadataFile = item.metadataFile;
+    }
+    return out;
+}
+
+/** Convert proto IndexItem back to JS IndexItem */
+function fromProtoItem(pi: any): IndexItem {
+    const metadata: Record<string, MetadataTypes> = {};
+    if (pi.metadata) {
+        for (const [k, v] of Object.entries(pi.metadata as Record<string, any>)) {
+            metadata[k] = fromProtoMetadataValue(v);
+        }
+    }
+    // proto packed float → JS number[]; ensure plain array
+    const vector: number[] = pi.vector ? Array.from(pi.vector as number[]) : [];
+    const item: IndexItem = {
+        id: pi.id,
+        metadata,
+        vector,
+        norm: pi.norm,
+    };
+    if (pi.metadataFile) {
+        item.metadataFile = pi.metadataFile;
+    }
+    return item;
+}
+
+/**
+ * Protocol Buffers codec — opt-in binary format.
+ * @remarks
+ * Vectors are stored as packed float32 arrays (~50% smaller than JSON).
+ * Norms are stored as float64 to avoid compounding rounding error.
+ * Requires the `protobufjs` package to be installed.
+ */
+export class ProtobufCodec implements IndexCodec {
+    readonly extension = '.pb';
+
+    constructor() {
+        // Eagerly validate that protobufjs is available
+        loadProtobuf();
+    }
+
+    serializeIndex(data: IndexData): Buffer {
+        const root = getRoot();
+        const IndexDataMsg = root.lookupType('IndexData');
+        const payload = {
+            version: data.version,
+            metadataConfig: {
+                indexed: data.metadata_config?.indexed ?? [],
+            },
+            items: data.items.map(toProtoItem),
+        };
+        const err = IndexDataMsg.verify(payload);
+        if (err) throw new Error(`Protobuf verify error: ${err}`);
+        const message = IndexDataMsg.create(payload);
+        return Buffer.from(IndexDataMsg.encode(message).finish());
+    }
+
+    deserializeIndex(buffer: Buffer): IndexData {
+        const root = getRoot();
+        const IndexDataMsg = root.lookupType('IndexData');
+        const decoded = IndexDataMsg.decode(new Uint8Array(buffer));
+        const obj = IndexDataMsg.toObject(decoded, {
+            longs: Number,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+        });
+        return {
+            version: obj.version,
+            metadata_config: {
+                indexed: obj.metadataConfig?.indexed ?? [],
+            },
+            items: (obj.items || []).map(fromProtoItem),
+        };
+    }
+
+    serializeCatalog(catalog: DocumentCatalog): Buffer {
+        const root = getRoot();
+        const CatalogMsg = root.lookupType('DocumentCatalog');
+        const payload = {
+            version: catalog.version,
+            count: catalog.count,
+            uriToId: catalog.uriToId,
+            idToUri: catalog.idToUri,
+        };
+        const err = CatalogMsg.verify(payload);
+        if (err) throw new Error(`Protobuf verify error: ${err}`);
+        const message = CatalogMsg.create(payload);
+        return Buffer.from(CatalogMsg.encode(message).finish());
+    }
+
+    deserializeCatalog(buffer: Buffer): DocumentCatalog {
+        const root = getRoot();
+        const CatalogMsg = root.lookupType('DocumentCatalog');
+        const decoded = CatalogMsg.decode(new Uint8Array(buffer));
+        const obj = CatalogMsg.toObject(decoded, {
+            longs: Number,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+        });
+        return {
+            version: obj.version,
+            count: obj.count,
+            uriToId: obj.uriToId || {},
+            idToUri: obj.idToUri || {},
+        };
+    }
+
+    serializeMetadata(metadata: Record<string, MetadataTypes>): Buffer {
+        // Metadata is a flat key-value map. We encode it as a JSON buffer
+        // wrapped in a simple length-prefixed envelope to stay self-describing
+        // while keeping the main index binary.
+        //
+        // We reuse the IndexItem metadata map encoding for consistency:
+        // encode as { entries: map<string, MetadataValue> }.
+        // However, since there's no standalone proto message for this,
+        // we just use JSON for external metadata files — the size savings
+        // from protobuf on small metadata objects are negligible.
+        return Buffer.from(JSON.stringify(metadata), 'utf-8');
+    }
+
+    deserializeMetadata(buffer: Buffer): Record<string, MetadataTypes> {
+        return JSON.parse(buffer.toString('utf-8'));
+    }
+}

package/src/codecs/index.ts

@@ -0,0 +1,4 @@
+export * from './IndexCodec';
+export * from './JsonCodec';
+export * from './ProtobufCodec';
+export * from './migrateIndex';

package/src/codecs/migrateIndex.spec.ts

@@ -0,0 +1,176 @@
+import assert from 'node:assert';
+import { VirtualFileStorage } from '../storage';
+import { JsonCodec } from './JsonCodec';
+import { ProtobufCodec } from './ProtobufCodec';
+import { detectCodec, migrateIndex } from './migrateIndex';
+import { IndexData } from '../types';
+import { DocumentCatalog } from './IndexCodec';
+
+describe('detectCodec', () => {
+    it('detects JSON format', async () => {
+        const storage = new VirtualFileStorage();
+        await storage.createFolder('/idx');
+        await storage.upsertFile('/idx/index.json', '{}');
+        const codec = await detectCodec('/idx', storage);
+        assert.equal(codec.extension, '.json');
+    });
+
+    it('detects Protobuf format', async () => {
+        const storage = new VirtualFileStorage();
+        await storage.createFolder('/idx');
+        await storage.upsertFile('/idx/index.pb', Buffer.from([0]));
+        const codec = await detectCodec('/idx', storage);
+        assert.equal(codec.extension, '.pb');
+    });
+
+    it('throws when both formats exist', async () => {
+        const storage = new VirtualFileStorage();
+        await storage.createFolder('/idx');
+        await storage.upsertFile('/idx/index.json', '{}');
+        await storage.upsertFile('/idx/index.pb', Buffer.from([0]));
+        await assert.rejects(
+            () => detectCodec('/idx', storage),
+            /Both index\.json and index\.pb found/
+        );
+    });
+
+    it('throws when no index file exists', async () => {
+        const storage = new VirtualFileStorage();
+        await storage.createFolder('/idx');
+        await assert.rejects(
+            () => detectCodec('/idx', storage),
+            /No index file found/
+        );
+    });
+});
+
+describe('migrateIndex', () => {
+    const json = new JsonCodec();
+    const pb = new ProtobufCodec();
+
+    function makeIndexData(): IndexData {
+        return {
+            version: 1,
+            metadata_config: { indexed: ['cat'] },
+            items: [
+                { id: 'item1', metadata: { cat: 'food' }, vector: [0.1, 0.2, 0.3], norm: 0.374 },
+                { id: 'item2', metadata: { cat: 'drink' }, vector: [0.4, 0.5, 0.6], norm: 0.877, metadataFile: 'abc.json' },
+            ],
+        };
+    }
+
+    function makeCatalog(): DocumentCatalog {
+        return {
+            version: 1,
+            count: 1,
+            uriToId: { 'doc.txt': 'doc-id-1' },
+            idToUri: { 'doc-id-1': 'doc.txt' },
+        };
+    }
+
+    it('migrates JSON -> Protobuf', async () => {
+        const storage = new VirtualFileStorage();
+        await storage.createFolder('/idx');
+        const data = makeIndexData();
+        await storage.upsertFile('/idx/index.json', json.serializeIndex(data));
+        await storage.upsertFile('/idx/abc.json', json.serializeMetadata({ cat: 'drink', extra: 'data' }));
+
+        await migrateIndex('/idx', { to: 'protobuf', storage });
+
+        // Old files should be gone
+        assert.equal(await storage.pathExists('/idx/index.json'), false);
+        assert.equal(await storage.pathExists('/idx/abc.json'), false);
+
+        // New files should exist
+        assert.equal(await storage.pathExists('/idx/index.pb'), true);
+        assert.equal(await storage.pathExists('/idx/abc.pb'), true);
+
+        // Data should be intact
+        const result = pb.deserializeIndex(await storage.readFile('/idx/index.pb'));
+        assert.equal(result.items.length, 2);
+        assert.equal(result.items[0].id, 'item1');
+        assert.equal(result.items[1].metadataFile, 'abc.pb');
+
+        // External metadata should be readable
+        const meta = pb.deserializeMetadata(await storage.readFile('/idx/abc.pb'));
+        assert.equal(meta.cat, 'drink');
+        assert.equal(meta.extra, 'data');
+    });
+
+    it('migrates Protobuf -> JSON', async () => {
+        const storage = new VirtualFileStorage();
+        await storage.createFolder('/idx');
+        const data = makeIndexData();
+        // Adjust metadataFile extension
+        data.items[1].metadataFile = 'abc.pb';
+        await storage.upsertFile('/idx/index.pb', pb.serializeIndex(data));
+        await storage.upsertFile('/idx/abc.pb', pb.serializeMetadata({ cat: 'drink', extra: 'data' }));
+
+        await migrateIndex('/idx', { to: 'json', storage });
+
+        assert.equal(await storage.pathExists('/idx/index.pb'), false);
+        assert.equal(await storage.pathExists('/idx/index.json'), true);
+
+        const result = json.deserializeIndex(await storage.readFile('/idx/index.json'));
+        assert.equal(result.items.length, 2);
+        assert.equal(result.items[1].metadataFile, 'abc.json');
+    });
+
+    it('migrates catalog along with index', async () => {
+        const storage = new VirtualFileStorage();
+        await storage.createFolder('/idx');
+        const data: IndexData = { version: 1, metadata_config: {}, items: [] };
+        const catalog = makeCatalog();
+        await storage.upsertFile('/idx/index.json', json.serializeIndex(data));
+        await storage.upsertFile('/idx/catalog.json', json.serializeCatalog(catalog));
+
+        await migrateIndex('/idx', { to: 'protobuf', storage });
+
+        assert.equal(await storage.pathExists('/idx/catalog.json'), false);
+        assert.equal(await storage.pathExists('/idx/catalog.pb'), true);
+
+        const result = pb.deserializeCatalog(await storage.readFile('/idx/catalog.pb'));
+        assert.deepStrictEqual(result, catalog);
+    });
+
+    it('migrates document metadata files referenced by catalog', async () => {
+        const storage = new VirtualFileStorage();
+        await storage.createFolder('/idx');
+        const data: IndexData = { version: 1, metadata_config: {}, items: [] };
+        const catalog = makeCatalog();
+        await storage.upsertFile('/idx/index.json', json.serializeIndex(data));
+        await storage.upsertFile('/idx/catalog.json', json.serializeCatalog(catalog));
+        await storage.upsertFile('/idx/doc-id-1.json', json.serializeMetadata({ author: 'test' }));
+
+        await migrateIndex('/idx', { to: 'protobuf', storage });
+
+        assert.equal(await storage.pathExists('/idx/doc-id-1.json'), false);
+        assert.equal(await storage.pathExists('/idx/doc-id-1.pb'), true);
+        const meta = pb.deserializeMetadata(await storage.readFile('/idx/doc-id-1.pb'));
+        assert.equal(meta.author, 'test');
+    });
+
+    it('no-op when already in target format', async () => {
+        const storage = new VirtualFileStorage();
+        await storage.createFolder('/idx');
+        const data: IndexData = { version: 1, metadata_config: {}, items: [] };
+        await storage.upsertFile('/idx/index.json', json.serializeIndex(data));
+
+        await migrateIndex('/idx', { to: 'json', storage });
+
+        // Should still be there, unchanged
+        assert.equal(await storage.pathExists('/idx/index.json'), true);
+    });
+
+    it('interruption detection: dual format raises error on detectCodec', async () => {
+        const storage = new VirtualFileStorage();
+        await storage.createFolder('/idx');
+        await storage.upsertFile('/idx/index.json', '{}');
+        await storage.upsertFile('/idx/index.pb', Buffer.from([0]));
+
+        await assert.rejects(
+            () => detectCodec('/idx', storage),
+            /Both index\.json and index\.pb found/
+        );
+    });
+});