om-memory-system 5.5.0 → 5.6.1

package/dist/services/spaces/transfer.js

@@ -0,0 +1,276 @@
+/**
+ * The space transfer engine (design D3). Pure over a `SourceReader` and a
+ * `TargetWriter`: no CONFIG import, no files, no host adapters. Steps:
+ * select, skip exact duplicates, preview, write per shard, check, remove.
+ */
+import { tryExtractScopeFromContainerTag } from "../memory-scope.js";
+import { formatTagsForEmbedding } from "../turso/vector-utils.js";
+import { tagTextKey } from "./transfer-types.js";
+export * from "./transfer-types.js";
+/** Preview examples are for the screen only and never logged (spec). */
+const EXAMPLE_LIMIT = 5;
+const EXAMPLE_TEXT_LIMIT = 160;
+const PERSONAL_GROUP_NAME = "Personal";
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Both bounds are inclusive; the project filter matches the container tag exactly. */
+function matchesFilter(row, filter) {
+    if (row.createdAt < filter.since || row.createdAt > filter.until)
+        return false;
+    if (filter.projectTag !== undefined && row.containerTag !== filter.projectTag)
+        return false;
+    return true;
+}
+/**
+ * Apply the filter to whatever the reader returned. Rows whose container tag
+ * cannot be parsed carry no scope, so they can be neither written to a scoped
+ * shard nor removed: the engine leaves them alone in both spaces.
+ */
+function selectRows(rows, filter) {
+    return rows.filter((row) => matchesFilter(row, filter) && tryExtractScopeFromContainerTag(row.containerTag) !== null);
+}
+/** Exact duplicates: the same id, or the same container tag and text under another id. */
+function skipDuplicates(rows, targetIds, targetTagTexts) {
+    const kept = [];
+    let duplicates = 0;
+    for (const row of rows) {
+        if (targetIds.has(row.id) || targetTagTexts.has(tagTextKey(row.containerTag, row.text))) {
+            duplicates += 1;
+        }
+        else {
+            kept.push(row);
+        }
+    }
+    return { kept, duplicates };
+}
+/** Vectors move only when the source provably used the target's model and dimensions. */
+function canReuseVectors(source, target) {
+    return (source !== undefined &&
+        source.model !== undefined &&
+        source.model === target.model &&
+        source.dimensions === target.dimensions);
+}
+function groupByScope(rows) {
+    const groups = new Map();
+    for (const row of rows) {
+        const scopeRef = tryExtractScopeFromContainerTag(row.containerTag);
+        const key = `${scopeRef.scope}:${scopeRef.hash}`;
+        const group = groups.get(key) ?? { scope: scopeRef.scope, scopeHash: scopeRef.hash, rows: [] };
+        group.rows.push(row);
+        groups.set(key, group);
+    }
+    return [...groups.values()];
+}
+function splitTags(tags) {
+    if (!tags)
+        return [];
+    return tags
+        .split(",")
+        .map((tag) => tag.trim())
+        .filter(Boolean);
+}
+function requireEmbed(embed) {
+    if (!embed) {
+        throw new Error("the stored vectors cannot be reused and no embed callback was provided");
+    }
+    return embed;
+}
+/** Give one row a usable vector: reuse the stored one when allowed, embed otherwise. */
+async function prepareWriteRow(row, reuseStoredVectors, embed) {
+    let vector = reuseStoredVectors ? row.vector : undefined;
+    let tagsVector = reuseStoredVectors ? row.tagsVector : undefined;
+    let embedded = false;
+    if (vector === undefined) {
+        vector = await requireEmbed(embed)(row.text);
+        embedded = true;
+    }
+    const tags = splitTags(row.tags);
+    if (tagsVector === undefined && tags.length > 0) {
+        tagsVector = await requireEmbed(embed)(formatTagsForEmbedding(tags));
+        embedded = true;
+    }
+    return {
+        row: {
+            id: row.id,
+            text: row.text,
+            containerTag: row.containerTag,
+            tags: row.tags,
+            type: row.type,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+            metadata: row.metadata,
+            isPinned: row.isPinned,
+            vector,
+            tagsVector,
+        },
+        embedded,
+    };
+}
+/**
+ * Write one scope group in batches that fit the shard's free room, one
+ * transaction per batch, and set the shard's vector count after each batch.
+ * Progress lands in `result` and `copiedRows` per batch, so a later failure
+ * still reports how far the transfer got; earlier batches stay because a
+ * re-run skips them as duplicates.
+ */
+async function writeScopeGroup(target, group, maxVectorsPerShard, reuseStoredVectors, embed, result, copiedRows) {
+    let pending = group.rows;
+    while (pending.length > 0) {
+        const shard = await target.getWriteShard(group.scope, group.scopeHash);
+        const room = maxVectorsPerShard - shard.vectorCount;
+        if (room <= 0) {
+            throw new Error(`the target offered shard ${shard.key} with no room left`);
+        }
+        const batch = pending.slice(0, room);
+        const prepared = [];
+        for (const row of batch) {
+            const writeRow = await prepareWriteRow(row, reuseStoredVectors, embed);
+            prepared.push(writeRow.row);
+            result.embeddedAgain = result.embeddedAgain || writeRow.embedded;
+        }
+        await target.insertBatch(shard, prepared);
+        await target.setShardCount(shard.key, shard.vectorCount + prepared.length);
+        copiedRows.push(...batch);
+        result.copied += batch.length;
+        pending = pending.slice(batch.length);
+    }
+}
+/**
+ * Preview a transfer: count, project groups, at most five examples (text cut
+ * to 160 characters) and the duplicate count. Reads only; never writes.
+ */
+export async function previewTransfer(args) {
+    const rows = selectRows(await args.source.readRows(args.filter), args.filter);
+    const [targetIds, targetTagTexts] = await Promise.all([
+        args.target.loadExistingIds(),
+        args.target.loadExistingTagTexts(),
+    ]);
+    const { kept, duplicates } = skipDuplicates(rows, targetIds, targetTagTexts);
+    const groups = new Map();
+    for (const row of kept) {
+        const scope = tryExtractScopeFromContainerTag(row.containerTag).scope;
+        const name = scope === "user" ? PERSONAL_GROUP_NAME : (row.projectName ?? row.containerTag);
+        const group = groups.get(row.containerTag) ?? { name, tag: row.containerTag, count: 0 };
+        group.count += 1;
+        groups.set(row.containerTag, group);
+    }
+    return {
+        matched: rows.length,
+        toCopy: kept.length,
+        duplicates,
+        groups: [...groups.values()],
+        examples: kept.slice(0, EXAMPLE_LIMIT).map((row) => ({
+            id: row.id,
+            text: row.text.slice(0, EXAMPLE_TEXT_LIMIT),
+        })),
+    };
+}
+/**
+ * Run a transfer: select and skip duplicates at apply time, write to the
+ * target, and for a move check every copied id before removing it from the
+ * source. Failures are reported in the result, never thrown: the counts say
+ * how far the transfer got.
+ */
+export async function applyTransfer(args) {
+    const { source, target, filter, mode } = args;
+    const result = {
+        ok: false,
+        mode,
+        copied: 0,
+        skipped: 0,
+        removed: 0,
+        changedFromPreview: 0,
+        embeddedAgain: false,
+        missingIds: [],
+    };
+    // Steps 1 and 2: select at apply time, then drop exact duplicates.
+    let kept;
+    try {
+        const rows = selectRows(await source.readRows(filter), filter);
+        result.changedFromPreview =
+            args.previewMatched === undefined ? 0 : rows.length - args.previewMatched;
+        const [targetIds, targetTagTexts] = await Promise.all([
+            target.loadExistingIds(),
+            target.loadExistingTagTexts(),
+        ]);
+        const selection = skipDuplicates(rows, targetIds, targetTagTexts);
+        kept = selection.kept;
+        result.skipped = selection.duplicates;
+    }
+    catch (error) {
+        result.error = {
+            step: "select",
+            message: `reading the source or the target failed: ${describeError(error)}`,
+        };
+        return result;
+    }
+    // Step 4: write per scope group, in batches that fit the shard's free room.
+    const copiedRows = [];
+    try {
+        const [sourceEmbedding, targetEmbedding] = await Promise.all([
+            source.getEmbeddingInfo(),
+            target.getEmbeddingSettings(),
+        ]);
+        const reuseStoredVectors = canReuseVectors(sourceEmbedding, targetEmbedding);
+        for (const group of groupByScope(kept)) {
+            await writeScopeGroup(target, group, args.maxVectorsPerShard, reuseStoredVectors, args.embed, result, copiedRows);
+        }
+    }
+    catch (error) {
+        result.error = {
+            step: "write",
+            message: `writing to the target failed after ${result.copied} memories: ${describeError(error)}`,
+        };
+        return result;
+    }
+    if (mode === "copy") {
+        result.ok = true;
+        return result;
+    }
+    // Step 5: check that every copied id is in the target.
+    const copiedIds = copiedRows.map((row) => row.id);
+    try {
+        const found = await target.findExistingIds(copiedIds);
+        result.missingIds = copiedIds.filter((id) => !found.has(id));
+    }
+    catch (error) {
+        result.error = {
+            step: "check",
+            message: `reading the copied memories back failed: ${describeError(error)}`,
+        };
+        return result;
+    }
+    if (result.missingIds.length > 0) {
+        result.error = {
+            step: "check",
+            message: `${result.missingIds.length} copied memory id(s) missing from the target: ${result.missingIds.join(", ")}`,
+        };
+        return result;
+    }
+    // Step 6: remove only the checked ids, one transaction per source shard.
+    try {
+        const byShard = new Map();
+        for (const row of copiedRows) {
+            const shardRows = byShard.get(row.shardKey) ?? [];
+            shardRows.push(row);
+            byShard.set(row.shardKey, shardRows);
+        }
+        const before = await source.getShardCounts([...byShard.keys()]);
+        for (const [shardKey, shardRows] of byShard) {
+            await source.deleteFromShard(shardKey, shardRows.map((row) => row.id));
+            const beforeCount = before.get(shardKey) ?? shardRows.length;
+            await source.setShardCount(shardKey, Math.max(0, beforeCount - shardRows.length));
+            result.removed += shardRows.length;
+        }
+    }
+    catch (error) {
+        result.error = {
+            step: "remove",
+            message: `removing from the source failed after ${result.removed} memories: ${describeError(error)}`,
+        };
+        return result;
+    }
+    result.ok = true;
+    return result;
+}

package/dist/services/turso/connection-manager.d.ts

@@ -3,12 +3,14 @@ import { TursoDb } from "./turso-db.js";
 import { resettable } from "../spaces/store-handles.js";
 export { resettable };
 export declare class TursoConnectionManager {
-    private readonly clientFactory;
     private readonly connections;
     private readonly pending;
     private readonly closingConnections;
     private closingPromise;
-    constructor(clientFactory?: typeof createClient);
+    private readonly clientFactory;
+    /** Roots whose subfolders this manager may open. Default: the two CONFIG roots. */
+    private readonly allowedRoots;
+    constructor(clientFactory?: typeof createClient, allowedRoots?: () => string[]);
     getConnection(dbPath: string): Promise<TursoDb>;
     closeConnection(dbPath: string): Promise<void>;
     closeAll(): Promise<void>;

package/dist/services/turso/connection-manager.js

@@ -17,21 +17,27 @@ function insideRoot(root, dbPath) {
         relativePath.startsWith(`..${sep}`) ||
         isAbsolute(relativePath));
 }
-function assertPathInsideStorage(dbPath) {
+/** The default allowed roots: the active storage path plus the global skills path. */
+function defaultAllowedRoots() {
     // skills.db stays in the global storage path when a project moves storagePath.
-    const roots = [CONFIG.storagePath, CONFIG.skillStoragePath].filter((root) => root !== undefined);
+    return [CONFIG.storagePath, CONFIG.skillStoragePath].filter((root) => root !== undefined);
+}
+function assertPathInsideStorage(dbPath, roots) {
     if (!roots.some((root) => insideRoot(root, dbPath))) {
         throw new Error(`Refusing to open database outside storagePath: ${dbPath}`);
     }
 }
 export class TursoConnectionManager {
-    clientFactory;
     connections = new Map();
     pending = new Map();
     closingConnections = new Map();
     closingPromise = null;
-    constructor(clientFactory = createClient) {
+    clientFactory;
+    /** Roots whose subfolders this manager may open. Default: the two CONFIG roots. */
+    allowedRoots;
+    constructor(clientFactory = createClient, allowedRoots = defaultAllowedRoots) {
         this.clientFactory = clientFactory;
+        this.allowedRoots = allowedRoots;
     }
     async getConnection(dbPath) {
         if (this.closingPromise) {
@@ -41,7 +47,7 @@ export class TursoConnectionManager {
         if (closingConnection) {
             await closingConnection;
         }
-        assertPathInsideStorage(dbPath);
+        assertPathInsideStorage(dbPath, this.allowedRoots());
         const existing = this.connections.get(dbPath);
         if (existing) {
             return existing;

package/dist/services/turso/cross-process-write-lock.d.ts

@@ -1 +1 @@
-export declare function withCrossProcessWriteLock<T>(scope: "user" | "project", hash: string, fn: () => Promise<T>): Promise<T>;
+export declare function withCrossProcessWriteLock<T>(scope: "user" | "project", hash: string, fn: () => Promise<T>, root?: string): Promise<T>;

package/dist/services/turso/cross-process-write-lock.js

@@ -49,8 +49,8 @@ function readLiveLock(path) {
     }
     return null;
 }
-function lockFilePath(scope, hash) {
-    return join(CONFIG.storagePath, WRITE_LOCK_DIR, `${scope}_${hash}.lock`);
+function lockFilePath(root, scope, hash) {
+    return join(root, WRITE_LOCK_DIR, `${scope}_${hash}.lock`);
 }
 async function publishLock(candidate, path) {
     // Match the bounded Windows hard-link retries used by the web start lock (TDR-034).
@@ -72,12 +72,12 @@ async function publishLock(candidate, path) {
         }
     }
 }
-export async function withCrossProcessWriteLock(scope, hash, fn) {
-    const dir = join(CONFIG.storagePath, WRITE_LOCK_DIR);
+export async function withCrossProcessWriteLock(scope, hash, fn, root = CONFIG.storagePath) {
+    const dir = join(root, WRITE_LOCK_DIR);
     if (!existsSync(dir)) {
         mkdirSync(dir, { recursive: true });
     }
-    const path = lockFilePath(scope, hash);
+    const path = lockFilePath(root, scope, hash);
     const state = { pid: process.pid, timestamp: new Date().toISOString() };
     const deadline = Date.now() + LOCK_TIMEOUT_MS;
     const candidate = `${path}.${process.pid}.${randomUUID()}.tmp`;

package/dist/services/turso/operation-lock.d.ts

@@ -1,2 +1,2 @@
-export declare function assertNoTursoMigrationInProgress(): void;
-export declare function acquireTursoOperationLock(operation: string): () => void;
+export declare function assertNoTursoMigrationInProgress(root?: string): void;
+export declare function acquireTursoOperationLock(operation: string, root?: string): () => void;

package/dist/services/turso/operation-lock.js

@@ -33,9 +33,9 @@ function readLiveLock(path) {
     }
     return null;
 }
-export function assertNoTursoMigrationInProgress() {
+export function assertNoTursoMigrationInProgress(root = CONFIG.storagePath) {
     for (const file of [OPERATION_LOCK, LEGACY_MIGRATION_LOCK]) {
-        const path = join(CONFIG.storagePath, file);
+        const path = join(root, file);
         const state = readLiveLock(path);
         if (state) {
             throw new Error(`Database migration is in progress${state.operation ? ` (${state.operation})` : ""} ` +
@@ -43,9 +43,9 @@ export function assertNoTursoMigrationInProgress() {
         }
     }
 }
-export function acquireTursoOperationLock(operation) {
-    assertNoTursoMigrationInProgress();
-    const path = join(CONFIG.storagePath, OPERATION_LOCK);
+export function acquireTursoOperationLock(operation, root = CONFIG.storagePath) {
+    assertNoTursoMigrationInProgress(root);
+    const path = join(root, OPERATION_LOCK);
     const state = {
         pid: process.pid,
         timestamp: new Date().toISOString(),

package/dist/services/turso/shard-manager.d.ts

@@ -1,3 +1,4 @@
+import type { TursoConnectionManager } from "./connection-manager.js";
 import type { ShardInfo } from "./types.js";
 import type { TursoDb } from "./turso-db.js";
 export declare class TursoShardManager {
@@ -5,6 +6,13 @@ export declare class TursoShardManager {
     private metadataPath;
     private initPromise;
     private readonly writeLocks;
+    private readonly getRoot;
+    private readonly connections;
+    /** Space-bound stores pass their own root and connections (D1); defaults keep CONFIG. */
+    constructor(options?: {
+        root?: () => string;
+        connections?: TursoConnectionManager;
+    });
     reset(): void;
     withScopeWriteLock<T>(scope: "user" | "project", scopeHash: string, fn: () => Promise<T>): Promise<T>;
     private ensureInitialized;

package/dist/services/turso/shard-manager.js

@@ -24,6 +24,13 @@ export class TursoShardManager {
     metadataPath = "";
     initPromise = null;
     writeLocks = new Map();
+    getRoot;
+    connections;
+    /** Space-bound stores pass their own root and connections (D1); defaults keep CONFIG. */
+    constructor(options = {}) {
+        this.getRoot = options.root ?? (() => CONFIG.storagePath);
+        this.connections = options.connections ?? tursoConnectionManager;
+    }
     reset() {
         this.metadataDb = null;
         this.initPromise = null;
@@ -46,7 +53,7 @@ export class TursoShardManager {
             // between processes (OpenCode + Pi, or any two writers) so that shard
             // allocation, vector-count sync, and the insert itself run as one
             // critical section per scope.
-            return await withCrossProcessWriteLock(scope, scopeHash, fn);
+            return await withCrossProcessWriteLock(scope, scopeHash, fn, this.getRoot());
         }
         finally {
             release();
@@ -67,8 +74,8 @@ export class TursoShardManager {
         }
         this.initPromise = (async () => {
             try {
-                this.metadataPath = join(CONFIG.storagePath, METADATA_DB_NAME);
-                this.metadataDb = await tursoConnectionManager.getConnection(this.metadataPath);
+                this.metadataPath = join(this.getRoot(), METADATA_DB_NAME);
+                this.metadataDb = await this.connections.getConnection(this.metadataPath);
                 await this.initMetadataDb(this.metadataDb);
             }
             catch (error) {
@@ -107,7 +114,7 @@ export class TursoShardManager {
     }
     getShardPath(scope, scopeHash, shardIndex) {
         assertSafeScopeHash(scopeHash);
-        const scopeDir = resolve(CONFIG.storagePath, `${scope}s`);
+        const scopeDir = resolve(this.getRoot(), `${scope}s`);
         const fullPath = resolve(join(scopeDir, `${scope}_${scopeHash}_shard_${shardIndex}.db`));
         const relativePath = relative(scopeDir, fullPath);
         if (relativePath.startsWith("..") || relativePath.includes("..")) {
@@ -117,7 +124,7 @@ export class TursoShardManager {
     }
     resolveStoredPath(storedPath, scope) {
         const fileName = basename(storedPath);
-        return join(CONFIG.storagePath, `${scope}s`, fileName);
+        return join(this.getRoot(), `${scope}s`, fileName);
     }
     async getActiveShard(scope, scopeHash) {
         const metadataDb = await this.ensureInitialized();
@@ -154,7 +161,7 @@ export class TursoShardManager {
         // (disk full, permissions), the registry stays free of an orphan row that points
         // at an uninitialized file — such a row would later fail isShardValid on every
         // getWriteShard and brick all writes to this scope. initShardDb is idempotent.
-        const shardDb = await tursoConnectionManager.getConnection(fullPath);
+        const shardDb = await this.connections.getConnection(fullPath);
         await this.initShardDb(shardDb);
         let result;
         try {
@@ -169,9 +176,8 @@ export class TursoShardManager {
           SELECT * FROM shards
           WHERE scope = ? AND scope_hash = ? AND shard_index = ?
         `, [scope, scopeHash, shardIndex]);
-                if (existing) {
+                if (existing)
                     return this.rowToShardInfo(existing);
-                }
             }
             throw error;
         }
@@ -325,7 +331,7 @@ export class TursoShardManager {
         return true;
     }
     async syncShardVectorCount(shard) {
-        const db = await tursoConnectionManager.getConnection(shard.dbPath);
+        const db = await this.connections.getConnection(shard.dbPath);
         const row = await db.get(`SELECT COUNT(*) as count FROM memories`);
         const count = Number(row?.count ?? 0);
         if (count === shard.vectorCount) {
@@ -341,13 +347,10 @@ export class TursoShardManager {
             return false;
         }
         try {
-            const db = await tursoConnectionManager.getConnection(shard.dbPath);
+            const db = await this.connections.getConnection(shard.dbPath);
             const result = await db.get(`SELECT name FROM sqlite_master WHERE type='table' AND name='memories'`);
             if (!result) {
-                log("Shard DB missing 'memories' table", {
-                    dbPath: shard.dbPath,
-                    shardId: shard.id,
-                });
+                log("Shard DB missing 'memories' table", { dbPath: shard.dbPath, shardId: shard.id });
                 return false;
             }
             if (!(await this.hasMatchingEmbeddingDimensions(db, shard))) {
@@ -364,12 +367,11 @@ export class TursoShardManager {
         }
     }
     async getWriteShard(scope, scopeHash) {
-        assertNoTursoMigrationInProgress();
+        assertNoTursoMigrationInProgress(this.getRoot());
         for (let attempt = 0; attempt < 3; attempt++) {
             let shard = await this.getActiveShard(scope, scopeHash);
-            if (!shard) {
+            if (!shard)
                 return this.createShard(scope, scopeHash, 0);
-            }
             if (!(await this.isShardValid(shard))) {
                 throw new Error(`Shard ${shard.scope}/${shard.scopeHash}#${shard.shardIndex} is incompatible or corrupt. ` +
                     `The original database was left untouched at ${shard.dbPath}; run the migration or restore it before writing.`);
@@ -427,11 +429,10 @@ export class TursoShardManager {
         if (!row)
             return;
         const fullPath = this.resolveStoredPath(String(row.db_path), String(row.scope));
-        await tursoConnectionManager.closeConnection(fullPath);
+        await this.connections.closeConnection(fullPath);
         try {
-            if (existsSync(fullPath)) {
+            if (existsSync(fullPath))
                 await withSqliteFileLockRetry(() => unlinkSync(fullPath));
-            }
         }
         catch (error) {
             log("Error deleting shard file", {
@@ -447,9 +448,9 @@ export class TursoShardManager {
         if (!row)
             return null;
         const fullPath = this.resolveStoredPath(String(row.db_path), String(row.scope));
-        await tursoConnectionManager.closeConnection(fullPath);
+        await this.connections.closeConnection(fullPath);
         const archivePath = archivePathOverride ?? `${fullPath}.${reason}-${process.pid}-${Date.now()}.bak`;
-        const scopeDir = resolve(CONFIG.storagePath, `${String(row.scope)}s`);
+        const scopeDir = resolve(this.getRoot(), `${String(row.scope)}s`);
         const archiveRelativePath = relative(scopeDir, resolve(archivePath));
         if (archiveRelativePath.startsWith("..") || archiveRelativePath.includes("..")) {
             throw new Error(`Archive path escapes storage directory: ${archivePath}`);

package/dist/services/turso/vector-search.d.ts

@@ -5,9 +5,13 @@ import type { Transaction } from "@libsql/client";
 export declare class TursoVectorSearch {
     insertVectorInTransaction(tx: Transaction, record: MemoryRecord): Promise<void>;
     insertVector(db: TursoDb, record: MemoryRecord): Promise<void>;
-    searchInShard(shard: ShardInfo, queryVector: Float32Array, containerTag: string, limit: number, queryText?: string, keywordBoost?: number, keywordMode?: KeywordMode): Promise<SearchResult[]>;
+    searchInShard(shard: ShardInfo, queryVector: Float32Array, containerTag: string, limit: number, queryText?: string, keywordBoost?: number, keywordMode?: KeywordMode, 
+    /** Opens the shard database; linked-space searches pass a read-only opener. */
+    openDb?: (dbPath: string) => Promise<TursoDb>): Promise<SearchResult[]>;
     private searchKind;
-    searchAcrossShards(shards: ShardInfo[], queryVector: Float32Array, containerTag: string, limit: number, similarityThreshold: number, queryText?: string, keywordBoost?: number, keywordMode?: KeywordMode): Promise<{
+    searchAcrossShards(shards: ShardInfo[], queryVector: Float32Array, containerTag: string, limit: number, similarityThreshold: number, queryText?: string, keywordBoost?: number, keywordMode?: KeywordMode, 
+    /** Opens each shard database; linked-space searches pass a read-only opener. */
+    openDb?: (dbPath: string) => Promise<TursoDb>): Promise<{
         results: SearchResult[];
         warnings: string[];
     }>;

package/dist/services/turso/vector-search.js

@@ -92,8 +92,10 @@ export class TursoVectorSearch {
       ) VALUES (?, ?, vector32(?), NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `, [record.id, record.content, contentVector, ...commonArgs]);
     }
-    async searchInShard(shard, queryVector, containerTag, limit, queryText, keywordBoost = 0, keywordMode = "boost") {
-        const db = await tursoConnectionManager.getConnection(shard.dbPath);
+    async searchInShard(shard, queryVector, containerTag, limit, queryText, keywordBoost = 0, keywordMode = "boost", 
+    /** Opens the shard database; linked-space searches pass a read-only opener. */
+    openDb = (dbPath) => tursoConnectionManager.getConnection(dbPath)) {
+        const db = await openDb(shard.dbPath);
         const queryJson = vectorToJson(queryVector);
         // Over-fetch aggressively when filtering by container_tag after ANN,
         // because post-filtering can discard many DiskANN neighbors.
@@ -203,11 +205,13 @@ export class TursoVectorSearch {
             return exactScanKind(db, queryJson, k, containerTag, columnName);
         }
     }
-    async searchAcrossShards(shards, queryVector, containerTag, limit, similarityThreshold, queryText, keywordBoost = 0, keywordMode = "boost") {
+    async searchAcrossShards(shards, queryVector, containerTag, limit, similarityThreshold, queryText, keywordBoost = 0, keywordMode = "boost", 
+    /** Opens each shard database; linked-space searches pass a read-only opener. */
+    openDb) {
         const shardErrors = [];
         const shardPromises = shards.map(async (shard) => {
             try {
-                return await this.searchInShard(shard, queryVector, containerTag, limit, queryText, keywordBoost, keywordMode);
+                return await this.searchInShard(shard, queryVector, containerTag, limit, queryText, keywordBoost, keywordMode, openDb);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);

package/dist/services/user-profile/user-profile-manager.d.ts

@@ -1,14 +1,18 @@
+import type { TursoConnectionManager } from "../turso/connection-manager.js";
 import type { UserProfile, UserProfileChangelog, UserProfileData } from "./types.js";
 import { EmbeddingService } from "../embedding.js";
 export declare const USER_PROFILES_DB_NAME = "user-profiles.db";
 export declare class UserProfileManager {
+    private readonly root?;
+    private readonly connections;
     private db;
     private dbPath;
     private initPromise;
     private coldBuffers;
     private coldBufferPath;
     private dedupCheckedCache;
-    constructor();
+    /** A rooted manager (profile import, design D1) reads and writes only `root`. */
+    constructor(root?: string | undefined, connections?: TursoConnectionManager);
     reset(): void;
     private initialize;
     private ready;