@andespindola/brainlink 1.0.7 → 1.2.0

package/dist/application/search-graph-node-ids.js

@@ -1,6 +1,7 @@
 import { stat } from 'node:fs/promises';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
-import { indexStoragePath, openFileIndex } from '../infrastructure/file-index.js';
+import { indexStoragePath } from '../infrastructure/file-index.js';
+import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
 import { getGraphLayout } from './get-graph-layout.js';
 const graphSearchCacheTtlMs = 20_000;
 const graphSearchCacheMaxEntries = 120;
@@ -52,7 +53,7 @@ export const searchGraphNodeIds = async (vaultPath, query, limit, agentId, conte
     const contextNodeIds = context
         ? new Set((await getGraphLayout(absoluteVaultPath, { agentId, context })).layout.nodes.map((node) => node.id))
         : new Set();
-    const index = openFileIndex(absoluteVaultPath);
+    const index = openKnowledgeStore(absoluteVaultPath);
     try {
         const searchLimit = context ? Math.max(limit, 5000) : limit;
         const foundNodeIds = await index.searchGraphNodeIds(query, searchLimit, agentId);

package/dist/application/search-knowledge.js

@@ -1,7 +1,7 @@
-import { stat } from 'node:fs/promises';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
 import { ensurePrivatePacksFromLegacyIndex, searchInPacks } from '../infrastructure/search-packs.js';
-import { indexStoragePath, openFileIndex } from '../infrastructure/file-index.js';
+import { indexCommitSignature } from '../infrastructure/index-signature.js';
+import { openKnowledgeStore } from '../infrastructure/knowledge-store/index.js';
 import { createEmbeddingProvider } from '../domain/embeddings.js';
 import { loadBrainlinkConfig, sanitizeSearchMode } from '../infrastructure/config.js';
 const embedQuerySafely = async (provider, query) => {
@@ -17,26 +17,18 @@ const embedQuerySafely = async (provider, query) => {
 const hybridCacheTtlMs = 30_000;
 const hybridCacheMaxEntries = 200;
 const hybridSearchCache = new Map();
-const readIndexMtimeMs = async (vaultPath) => {
-    try {
-        return (await stat(indexStoragePath(vaultPath))).mtimeMs;
-    }
-    catch {
-        return 0;
-    }
-};
 const toCacheKey = (vaultPath, query, limit, agentId) => JSON.stringify({
     vaultPath,
     query: query.trim().toLowerCase(),
     limit,
     agentId: agentId?.trim().toLowerCase() ?? '*'
 });
-const cacheGet = (key, indexMtimeMs) => {
+const cacheGet = (key, indexSignature) => {
     const entry = hybridSearchCache.get(key);
     if (!entry) {
         return undefined;
     }
-    const fresh = Date.now() - entry.createdAt <= hybridCacheTtlMs && entry.indexMtimeMs === indexMtimeMs;
+    const fresh = Date.now() - entry.createdAt <= hybridCacheTtlMs && entry.indexSignature === indexSignature;
     if (!fresh) {
         hybridSearchCache.delete(key);
         return undefined;
@@ -58,8 +50,8 @@ export const searchKnowledge = async (vaultPath, query, limit, agentId, mode) =>
     const searchMode = sanitizeSearchMode(mode, config.defaultSearchMode);
     await ensurePrivatePacksFromLegacyIndex(absoluteVaultPath);
     const cacheKey = searchMode === 'hybrid' ? toCacheKey(absoluteVaultPath, query, limit, agentId) : undefined;
-    const indexMtimeMs = cacheKey ? await readIndexMtimeMs(absoluteVaultPath) : 0;
-    const cached = cacheKey ? cacheGet(cacheKey, indexMtimeMs) : undefined;
+    const indexSignature = cacheKey ? await indexCommitSignature(absoluteVaultPath) : '';
+    const cached = cacheKey ? cacheGet(cacheKey, indexSignature) : undefined;
     if (cached) {
         return cached;
     }
@@ -73,14 +65,14 @@ export const searchKnowledge = async (vaultPath, query, limit, agentId, mode) =>
     // to lexical (fts) so a transient provider outage still yields results.
     const effectiveMode = searchMode === 'semantic' && shouldEmbedQuery && queryEmbedding.length === 0 ? 'fts' : searchMode;
     try {
-        const index = openFileIndex(absoluteVaultPath);
+        const index = openKnowledgeStore(absoluteVaultPath);
         try {
             const results = await index.search(query, limit, agentId, effectiveMode, queryEmbedding);
             if (cacheKey) {
                 cacheSet({
                     key: cacheKey,
                     createdAt: Date.now(),
-                    indexMtimeMs,
+                    indexSignature,
                     results
                 });
             }
@@ -96,7 +88,7 @@ export const searchKnowledge = async (vaultPath, query, limit, agentId, mode) =>
             cacheSet({
                 key: cacheKey,
                 createdAt: Date.now(),
-                indexMtimeMs,
+                indexSignature,
                 results: fallbackResults
             });
         }

package/dist/application/server/routes.js

@@ -40,6 +40,10 @@ const readContextCacheTtlMs = async (url) => {
     const defaults = await readRuntimeDefaults(url);
     return defaults.defaultContextCacheTtlMs;
 };
+const readCagPackTtlMs = async (url) => {
+    const defaults = await readRuntimeDefaults(url);
+    return defaults.cagPackTtlMs;
+};
 const hasInvalidSearchMode = (url) => {
     const mode = url.searchParams.get('mode');
     return mode !== null && !['fts', 'semantic', 'hybrid'].includes(mode);
@@ -445,13 +449,14 @@ export const route = async (request, url, vaultPath) => {
         const mode = await readSearchMode(url);
         const strategy = await readContextStrategy(url);
         const contextCacheTtlMs = await readContextCacheTtlMs(url);
+        const cagPackTtlMs = await readCagPackTtlMs(url);
         if (hasInvalidSearchMode(url)) {
             return createResponse(createJsonResponse({ error: 'Invalid mode. Use fts, semantic or hybrid.' }), 400, contentTypes['.json']);
         }
         if (hasInvalidContextStrategy(url)) {
             return createResponse(createJsonResponse({ error: 'Invalid strategy. Use rag, cag or auto.' }), 400, contentTypes['.json']);
         }
-        return createResponse(createJsonResponse(await buildContextPackage(vaultPath, query, limit, tokens, readAgentQuery(url), mode, strategy, contextCacheTtlMs)), 200, contentTypes['.json']);
+        return createResponse(createJsonResponse(await buildContextPackage(vaultPath, query, limit, tokens, readAgentQuery(url), mode, strategy, contextCacheTtlMs, cagPackTtlMs)), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/links') {
         return createResponse(createJsonResponse({ links: await listLinks(vaultPath, readAgentQuery(url)) }), 200, contentTypes['.json']);

package/dist/application/vault-encryption.js

@@ -0,0 +1,64 @@
+// Encrypted vault versioning: the git repo tracks `<note>.md.enc` ciphertext
+// (opaque without the local key), while the plaintext `.md` stays the canonical
+// working copy and is git-ignored. Committing refreshes the ciphertext mirror;
+// pulling/cloning/restoring decrypts it back to Markdown before reindexing. Only
+// content that changed is rewritten, so encryption adds no git churn.
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { loadBrainlinkConfig } from '../infrastructure/config.js';
+import { ensureVault, listVaultFiles } from '../infrastructure/file-system-vault.js';
+import { decryptVaultContent, encryptVaultContent, readOrCreateVaultKey } from '../infrastructure/vault-crypto.js';
+const encryptedSuffix = '.md.enc';
+const isMarkdown = (path) => extname(path).toLowerCase() === '.md';
+const isEncryptedMarkdown = (path) => path.toLowerCase().endsWith(encryptedSuffix);
+export const vaultEncryptionEnabled = async () => (await loadBrainlinkConfig()).vaultEncryption === true;
+// Refresh the ciphertext mirror: (re)write `<note>.md.enc` for every Markdown
+// file whose ciphertext is missing or stale, and drop orphan `.md.enc` whose
+// source Markdown was deleted. Deterministic encryption means an unchanged note
+// produces identical bytes, so it is skipped (no write, no git churn).
+export const encryptVaultTree = async (vaultPath) => {
+    const root = await ensureVault(vaultPath);
+    const key = await readOrCreateVaultKey(root);
+    const files = await listVaultFiles(root);
+    const markdown = files.filter(isMarkdown);
+    const expected = new Set(markdown.map((path) => `${path}.enc`));
+    let written = 0;
+    for (const source of markdown) {
+        const payload = encryptVaultContent(key, await readFile(source));
+        const target = `${source}.enc`;
+        let current = null;
+        try {
+            current = await readFile(target);
+        }
+        catch {
+            current = null;
+        }
+        if (!current || !current.equals(payload)) {
+            await writeFile(target, payload, { mode: 0o600 });
+            written += 1;
+        }
+    }
+    let removed = 0;
+    for (const encrypted of files.filter(isEncryptedMarkdown)) {
+        if (!expected.has(encrypted)) {
+            await rm(encrypted, { force: true });
+            removed += 1;
+        }
+    }
+    return { written, removed };
+};
+// Rebuild plaintext Markdown from the ciphertext mirror after a checkout. Fails
+// loudly if the key cannot decrypt a payload (wrong/missing key) rather than
+// writing garbage.
+export const decryptVaultTree = async (vaultPath) => {
+    const root = await ensureVault(vaultPath);
+    const key = await readOrCreateVaultKey(root);
+    const encrypted = (await listVaultFiles(root)).filter(isEncryptedMarkdown);
+    let written = 0;
+    for (const source of encrypted) {
+        const plaintext = decryptVaultContent(key, await readFile(source));
+        await writeFile(source.slice(0, -'.enc'.length), plaintext, { mode: 0o600 });
+        written += 1;
+    }
+    return { written };
+};

package/dist/application/vault-git-core.js

@@ -0,0 +1,168 @@
+// Git primitives for vault versioning, with no dependency on the indexing layer
+// so they can be reused by the auto-version hook that runs *after* indexing
+// (avoiding a cycle with index-vault). Only the canonical Markdown is versioned;
+// the derived `.brainlink/` directory is git-ignored. Git is driven through the
+// system binary via execFile (never a shell), and a missing binary degrades to a
+// clear, actionable error.
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { ensureVault } from '../infrastructure/file-system-vault.js';
+import { encryptVaultTree, vaultEncryptionEnabled } from './vault-encryption.js';
+const execFileAsync = promisify(execFile);
+export class GitUnavailableError extends Error {
+    constructor() {
+        super('git executable not found. Install git to use vault versioning.');
+        this.name = 'GitUnavailableError';
+    }
+}
+export class GitCommandError extends Error {
+    constructor(args, stderr) {
+        super(`git ${args.join(' ')} failed: ${stderr.trim() || 'unknown error'}`);
+        this.name = 'GitCommandError';
+    }
+}
+const isMissingBinary = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+export const runGit = async (cwd, args) => {
+    try {
+        const { stdout } = await execFileAsync('git', [...args], { cwd, maxBuffer: 64 * 1024 * 1024 });
+        return stdout;
+    }
+    catch (error) {
+        if (isMissingBinary(error)) {
+            throw new GitUnavailableError();
+        }
+        const stderr = error.stderr ?? (error instanceof Error ? error.message : String(error));
+        throw new GitCommandError(args, stderr);
+    }
+};
+const isInsideGitRepo = async (cwd) => {
+    try {
+        const out = await runGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+        return out.trim() === 'true';
+    }
+    catch (error) {
+        if (error instanceof GitUnavailableError) {
+            throw error;
+        }
+        return false;
+    }
+};
+const baseGitignoreLines = ['.brainlink/', '*.tmp', '.DS_Store'];
+// In encrypted mode the plaintext Markdown is never committed — only the
+// `<note>.md.enc` ciphertext is — so the working `.md` files are git-ignored.
+const encryptedGitignoreLines = [...baseGitignoreLines, '*.md'];
+const ensureGitignore = async (vaultRoot, lines) => {
+    const path = join(vaultRoot, '.gitignore');
+    let current = '';
+    try {
+        current = await readFile(path, 'utf8');
+    }
+    catch {
+        current = '';
+    }
+    const existing = new Set(current.split('\n').map((line) => line.trim()));
+    const missing = lines.filter((line) => !existing.has(line));
+    if (missing.length === 0 && current.length > 0) {
+        return;
+    }
+    const next = `${[current.trimEnd(), ...missing].filter(Boolean).join('\n')}\n`;
+    await writeFile(path, next, 'utf8');
+};
+// Reject credentials embedded in a remote URL: they would be written to
+// .git/config in clear text. Users should rely on SSH or a git credential
+// helper instead.
+export const assertSafeRemote = (remote) => {
+    if (/\/\/[^/@]*:[^/@]*@/.test(remote) || /x-access-token|:[^/]*@github/.test(remote)) {
+        throw new Error('Refusing a remote URL with an inline credential. Use SSH or a git credential helper.');
+    }
+};
+export const markdownOnly = (paths) => paths.filter((path) => path.toLowerCase().endsWith('.md'));
+// True when the repo has an 'origin' remote, so auto-versioning knows whether a
+// push is possible.
+export const hasRemote = async (root, remote = 'origin') => {
+    const remotes = await runGit(root, ['remote']).catch(() => '');
+    return remotes.split('\n').map((line) => line.trim()).includes(remote);
+};
+export const initVaultGit = async (vaultPath, options = {}) => {
+    const root = await ensureVault(vaultPath);
+    await mkdir(root, { recursive: true });
+    const already = await isInsideGitRepo(root);
+    if (!already) {
+        await runGit(root, ['init']);
+    }
+    await ensureGitignore(root, (await vaultEncryptionEnabled()) ? encryptedGitignoreLines : baseGitignoreLines);
+    if (options.remote) {
+        assertSafeRemote(options.remote);
+        const verb = (await hasRemote(root)) ? 'set-url' : 'add';
+        await runGit(root, ['remote', verb, 'origin', options.remote]);
+    }
+    return { root, initialized: !already };
+};
+export const vaultGitStatus = async (vaultPath) => {
+    const root = await ensureVault(vaultPath);
+    const branch = (await runGit(root, ['rev-parse', '--abbrev-ref', 'HEAD']).catch(() => 'HEAD')).trim();
+    const porcelain = await runGit(root, ['status', '--porcelain']);
+    const changed = porcelain
+        .split('\n')
+        .map((line) => line.slice(3).trim())
+        .filter(Boolean);
+    return { branch, dirty: changed.length > 0, changedMarkdown: markdownOnly(changed) };
+};
+// Stage and commit the versioned content. Returns null when there is nothing to
+// commit. In encrypted mode the ciphertext mirror is refreshed first and only
+// `<note>.md.enc` is staged; otherwise the plaintext Markdown is staged.
+export const commitVault = async (vaultPath, message) => {
+    const root = await ensureVault(vaultPath);
+    const encrypted = await vaultEncryptionEnabled();
+    if (encrypted) {
+        await encryptVaultTree(root);
+        await ensureGitignore(root, encryptedGitignoreLines);
+    }
+    const patterns = encrypted
+        ? ['*.md.enc', ':(glob)**/*.md.enc', '.gitignore']
+        : ['*.md', ':(glob)**/*.md', '.gitignore'];
+    await runGit(root, ['add', '-A', '--', ...patterns]);
+    const staged = await runGit(root, ['diff', '--cached', '--name-only']);
+    if (staged.trim().length === 0) {
+        return null;
+    }
+    await runGit(root, ['commit', '-m', message]);
+    return (await runGit(root, ['rev-parse', 'HEAD'])).trim();
+};
+export const pushVault = async (vaultPath, branch) => {
+    const root = await ensureVault(vaultPath);
+    const target = branch ?? (await runGit(root, ['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
+    await runGit(root, ['push', '-u', 'origin', target]);
+};
+export const vaultHistory = async (vaultPath, limit = 20) => {
+    const root = await ensureVault(vaultPath);
+    const out = await runGit(root, [
+        'log',
+        `-n${Math.max(1, Math.floor(limit))}`,
+        '--format=%H%x00%an%x00%aI%x00%s',
+        '--',
+        '*.md'
+    ]).catch(() => '');
+    return out
+        .split('\n')
+        .map((line) => line.split('\u0000'))
+        .filter((parts) => parts.length === 4)
+        .map(([hash, author, date, subject]) => ({ hash: hash, author: author, date: date, subject: subject }));
+};
+// Best-effort commit + push of the canonical Markdown, used by the auto-version
+// hook after a successful index. A no-op unless the vault is a git repo with an
+// origin remote. Commits only when Markdown actually changed.
+export const autoVersionVault = async (vaultPath, message) => {
+    const root = await ensureVault(vaultPath);
+    if (!(await isInsideGitRepo(root)) || !(await hasRemote(root))) {
+        return { committed: null, pushed: false };
+    }
+    const committed = await commitVault(vaultPath, message);
+    if (!committed) {
+        return { committed: null, pushed: false };
+    }
+    await pushVault(vaultPath);
+    return { committed, pushed: true };
+};

package/dist/application/vault-git.js

@@ -0,0 +1,75 @@
+// Vault versioning operations that reindex after changing Markdown on disk
+// (pull, restore, clone) so the vault stays immediately usable ("no losing the
+// use of the data"). The git primitives live in vault-git-core (which has no
+// indexing dependency) and are re-exported here so callers keep a single import.
+import { indexVault } from './index-vault.js';
+import { ensureVault } from '../infrastructure/file-system-vault.js';
+import { decryptVaultTree, vaultEncryptionEnabled } from './vault-encryption.js';
+import { assertSafeRemote, GitCommandError, markdownOnly, runGit } from './vault-git-core.js';
+export * from './vault-git-core.js';
+const reindexAfterMarkdownChange = async (vaultPath, changedMarkdown, skipIndex) => !skipIndex && changedMarkdown.length > 0 ? indexVault(vaultPath) : undefined;
+// Pull from origin and reindex when Markdown changed, so the vault is usable
+// immediately. On a merge conflict the merge is aborted and a clear error is
+// raised rather than leaving conflict markers in the Markdown.
+export const pullVault = async (vaultPath, options = {}) => {
+    const root = await ensureVault(vaultPath);
+    const before = (await runGit(root, ['rev-parse', 'HEAD']).catch(() => '')).trim();
+    try {
+        await runGit(root, ['pull', '--no-rebase', '--no-edit', 'origin']);
+    }
+    catch (error) {
+        await runGit(root, ['merge', '--abort']).catch(() => undefined);
+        throw error instanceof GitCommandError
+            ? new GitCommandError(['pull'], 'merge conflict; aborted. Resolve manually, then commit.')
+            : error;
+    }
+    const after = (await runGit(root, ['rev-parse', 'HEAD']).catch(() => '')).trim();
+    const changed = Boolean(before && after && before !== after);
+    // Encrypted vaults track ciphertext; rebuild the plaintext Markdown from it
+    // before reindexing. Individual filenames are not reported (the diff is over
+    // opaque `.md.enc`).
+    if (await vaultEncryptionEnabled()) {
+        if (changed) {
+            await decryptVaultTree(root);
+        }
+        const index = changed ? await reindexAfterMarkdownChange(vaultPath, ['(encrypted)'], options.skipIndex === true) : undefined;
+        return { changedMarkdown: changed ? ['(encrypted)'] : [], index };
+    }
+    const diff = changed ? await runGit(root, ['diff', '--name-only', before, after, '--', '*.md']) : '';
+    const changedMarkdown = markdownOnly(diff.split('\n').map((line) => line.trim()).filter(Boolean));
+    const index = await reindexAfterMarkdownChange(vaultPath, changedMarkdown, options.skipIndex === true);
+    return { changedMarkdown, index };
+};
+export const restoreVault = async (vaultPath, ref, options = {}) => {
+    const root = await ensureVault(vaultPath);
+    const encrypted = await vaultEncryptionEnabled();
+    const diff = await runGit(root, ['diff', '--name-only', ref, '--', encrypted ? '*.md.enc' : '*.md']).catch(() => '');
+    await runGit(root, ['checkout', ref, '--', '.']);
+    // Restore is an explicit request to materialize this ref's Markdown, so in
+    // encrypted mode always rebuild the plaintext from the (now checked-out)
+    // ciphertext — the plaintext is derived and may be missing or stale even when
+    // the ciphertext already matched the ref.
+    if (encrypted) {
+        const rebuilt = await decryptVaultTree(root);
+        const index = await reindexAfterMarkdownChange(vaultPath, rebuilt.written > 0 ? ['(encrypted)'] : [], options.skipIndex === true);
+        return { changedMarkdown: rebuilt.written > 0 ? ['(encrypted)'] : [], index };
+    }
+    const changedMarkdown = markdownOnly(diff.split('\n').map((line) => line.trim()).filter(Boolean));
+    const index = await reindexAfterMarkdownChange(vaultPath, changedMarkdown, options.skipIndex === true);
+    return { changedMarkdown, index };
+};
+// Clone a remote vault and build its index from scratch so it is immediately
+// searchable. The clone target must not already exist.
+export const cloneVault = async (remote, targetPath, options = {}) => {
+    assertSafeRemote(remote);
+    await runGit(process.cwd(), ['clone', remote, targetPath]);
+    const root = await ensureVault(targetPath);
+    // Encrypted clone: decrypt the ciphertext mirror before indexing. Requires the
+    // vault key on this machine (BRAINLINK_VAULT_KEY or a copied key file);
+    // decryption throws a clear error if the key is missing or wrong.
+    if (await vaultEncryptionEnabled()) {
+        await decryptVaultTree(root);
+    }
+    const index = options.skipIndex === true ? undefined : await indexVault(root, { full: true });
+    return { root, index };
+};

package/dist/application/vault-snapshot.js

@@ -0,0 +1,87 @@
+// Portable vault snapshot (`.blvault`): a single gzip-compressed envelope of the
+// canonical Markdown (with per-file SHA-256), self-contained and movable to any
+// machine. The derived index is never included — import rebuilds it so the vault
+// is immediately usable. Conflicts on import are preserved as `*.conflict-<ts>.md`
+// rather than overwriting local edits.
+import { createHash } from 'node:crypto';
+import { gzipSync, gunzipSync } from 'node:zlib';
+import { extname, relative } from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+import { indexVault } from './index-vault.js';
+import { ensureVault, listVaultFiles, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
+const snapshotVersion = 1;
+const isMarkdown = (path) => extname(path).toLowerCase() === '.md';
+const toPosix = (path) => path.split('\\').join('/');
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+const conflictName = (path) => {
+    const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+$/, 'Z');
+    const extension = extname(path);
+    const base = extension ? path.slice(0, -extension.length) : path;
+    return `${base}.conflict-${stamp}${extension}`;
+};
+export const exportVaultSnapshot = async (vaultPath, outputFile) => {
+    const root = await ensureVault(vaultPath);
+    const markdownFiles = (await listVaultFiles(root)).filter(isMarkdown);
+    const entries = await Promise.all(markdownFiles.map(async (absolutePath) => {
+        const content = await readFile(absolutePath);
+        const path = toPosix(relative(root, absolutePath));
+        return {
+            manifest: { path, sha256: sha256(content), bytes: content.byteLength },
+            file: { path, contentB64: content.toString('base64') }
+        };
+    }));
+    const envelope = {
+        version: snapshotVersion,
+        createdAt: new Date().toISOString(),
+        manifest: entries.map((entry) => entry.manifest),
+        files: entries.map((entry) => entry.file)
+    };
+    const packed = gzipSync(Buffer.from(JSON.stringify(envelope), 'utf8'), { level: 9 });
+    await writeFile(outputFile, packed, { mode: 0o600 });
+    return { file: outputFile, fileCount: entries.length, bytes: packed.byteLength };
+};
+const parseEnvelope = (raw) => {
+    const envelope = JSON.parse(gunzipSync(raw).toString('utf8'));
+    if (!envelope || envelope.version !== snapshotVersion || !Array.isArray(envelope.files)) {
+        throw new Error('Unrecognized .blvault snapshot format.');
+    }
+    return envelope;
+};
+export const importVaultSnapshot = async (snapshotFile, vaultPath, options = {}) => {
+    const root = await ensureVault(vaultPath);
+    const envelope = parseEnvelope(await readFile(snapshotFile));
+    const manifestByPath = new Map(envelope.manifest.map((entry) => [entry.path, entry]));
+    let imported = 0;
+    let conflicted = 0;
+    for (const file of envelope.files) {
+        if (!isMarkdown(file.path)) {
+            continue;
+        }
+        const content = Buffer.from(file.contentB64, 'base64');
+        const expected = manifestByPath.get(file.path)?.sha256;
+        if (expected && sha256(content) !== expected) {
+            throw new Error(`Checksum mismatch for ${file.path}; snapshot is corrupt.`);
+        }
+        // Preserve local edits: write divergent incoming files under a conflict name
+        // instead of overwriting. writeMarkdownFile guards against path traversal.
+        let existing = null;
+        try {
+            existing = await readFile(`${root}/${file.path}`);
+        }
+        catch {
+            existing = null;
+        }
+        if (existing && !existing.equals(content)) {
+            await writeMarkdownFile(root, conflictName(file.path), content.toString('utf8'));
+            conflicted += 1;
+            continue;
+        }
+        if (existing && existing.equals(content)) {
+            continue;
+        }
+        await writeMarkdownFile(root, file.path, content.toString('utf8'));
+        imported += 1;
+    }
+    const index = !options.skipIndex && imported + conflicted > 0 ? await indexVault(root) : undefined;
+    return { imported, conflicted, index };
+};

package/dist/cli/commands/read-commands.js

@@ -1,5 +1,5 @@
 import { getBrokenLinksReport, getExtendedStats, getOrphansReport, getStats, validateVault } from '../../application/analyze-vault.js';
-import { buildContextPackage, readContextDataSignature } from '../../application/build-context.js';
+import { buildContextPackage, readContextDataSignature, readVolatileSignature } from '../../application/build-context.js';
 import { getGraph } from '../../application/get-graph.js';
 import { listAgents } from '../../application/list-agents.js';
 import { listBacklinks, listLinks } from '../../application/list-links.js';
@@ -82,24 +82,28 @@ export const registerReadCommands = (program) => {
         const resolved = await resolveOptions(options);
         const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
         const strategy = sanitizeContextStrategy(options.strategy, resolved.defaults.defaultContextStrategy);
-        const contextPackage = await buildContextPackage(resolved.vault, query, parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit), parsePositiveInteger(options.tokens ?? String(resolved.defaults.defaultContextTokens), resolved.defaults.defaultContextTokens), resolved.agent, mode, strategy, resolved.defaults.defaultContextCacheTtlMs);
+        const contextPackage = await buildContextPackage(resolved.vault, query, parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit), parsePositiveInteger(options.tokens ?? String(resolved.defaults.defaultContextTokens), resolved.defaults.defaultContextTokens), resolved.agent, mode, strategy, resolved.defaults.defaultContextCacheTtlMs, resolved.defaults.cagPackTtlMs);
         print(options.json, contextPackage, () => contextPackage.content);
     });
     program
         .command('context-packs')
         .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'accepted for consistency; context packs are already keyed by agent')
-        .option('--stale', 'operate only on packs stale for the current index and volatile-memory signature')
+        .option('--stale', 'operate only on packs whose cited documents (or volatile memory) have changed')
         .option('--clear', 'remove context packs instead of listing them')
         .option('--json', 'print machine-readable JSON')
         .description('list or clear persisted CAG context packs')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
         const dataSignature = await readContextDataSignature(resolved.vault);
+        const freshness = {
+            volatileSignature: await readVolatileSignature(resolved.vault),
+            ttlMs: resolved.defaults.cagPackTtlMs
+        };
         if (options.clear) {
             const result = await clearContextPacks(resolved.vault, {
                 staleOnly: options.stale === true,
-                dataSignature
+                freshness
             });
             print(options.json, { vault: resolved.vault, dataSignature, ...result }, () => [
                 `Removed context packs: ${result.removed.length}`,
@@ -107,7 +111,7 @@ export const registerReadCommands = (program) => {
             ].join('\n'));
             return;
         }
-        const packs = await listContextPacks(resolved.vault, dataSignature);
+        const packs = await listContextPacks(resolved.vault, freshness);
         const visiblePacks = options.stale ? packs.filter((pack) => pack.stale) : packs;
         print(options.json, { vault: resolved.vault, dataSignature, packs: visiblePacks }, () => visiblePacks.length === 0
             ? 'No context packs found.'