@andespindola/brainlink 0.1.0-beta.40 → 0.1.0-beta.42

package/dist/application/frontend/client-worker-js.js

@@ -0,0 +1,66 @@
+export const createClientWorkerJs = () => `const normalize = value => String(value || '')
+  .normalize('NFKD')
+  .replace(/\\p{Diacritic}/gu, '')
+  .toLowerCase()
+
+let nodeIndex = []
+
+const toNodeIndex = nodes =>
+  (Array.isArray(nodes) ? nodes : [])
+    .map(node => {
+      const id = typeof node.id === 'string' ? node.id : ''
+      if (!id) {
+        return null
+      }
+      const title = normalize(node.title)
+      const path = normalize(node.path)
+      const tags = Array.isArray(node.tags) ? node.tags.map(tag => normalize(tag)) : []
+      return {
+        id,
+        text: [title, path, ...tags].join(' ')
+      }
+    })
+    .filter(Boolean)
+
+const scoreText = (text, query) => {
+  if (!query) return 0
+  if (!text.includes(query)) return 0
+  if (text.startsWith(query)) return 4
+  return 1
+}
+
+const filterIds = (query, limit) => {
+  const normalizedQuery = normalize(query).trim()
+  if (!normalizedQuery) {
+    return []
+  }
+  const rows = []
+  for (let index = 0; index < nodeIndex.length; index += 1) {
+    const row = nodeIndex[index]
+    const score = scoreText(row.text, normalizedQuery)
+    if (score > 0) {
+      rows.push({ id: row.id, score })
+    }
+  }
+  rows.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))
+  return rows.slice(0, Math.max(1, Number.isFinite(limit) ? limit : rows.length)).map(row => row.id)
+}
+
+self.onmessage = event => {
+  const payload = event.data
+  if (!payload || typeof payload !== 'object') {
+    return
+  }
+  if (payload.type === 'load-nodes') {
+    nodeIndex = toNodeIndex(payload.nodes)
+    return
+  }
+  if (payload.type === 'filter') {
+    const token = payload.token
+    const ids = filterIds(payload.query, payload.limit)
+    self.postMessage({ type: 'filter-result', token, ids })
+  }
+}
+
+self.postMessage({ type: 'ready' })
+`;

package/dist/application/index-vault.js

@@ -1,8 +1,11 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
 import { createIndexedDocument, parseMarkdownDocument } from '../domain/markdown.js';
 import { sharedAgentId } from '../domain/agents.js';
 import { createEmbeddingProvider } from '../domain/embeddings.js';
 import { loadBrainlinkConfig } from '../infrastructure/config.js';
-import { ensureVault, readMarkdownFiles } from '../infrastructure/file-system-vault.js';
+import { ensureVault, readMarkdownFileSummaries } from '../infrastructure/file-system-vault.js';
+import { readIndexState, writeIndexState } from '../infrastructure/index-state.js';
 import { buildSearchPacks } from '../infrastructure/search-packs.js';
 import { openFileIndex } from '../infrastructure/file-index.js';
 const toTitleKey = (title) => title.toLowerCase();
@@ -34,6 +37,9 @@ const createScopedTitleResolver = (document, titleMaps) => ({
     get: (title) => titleMaps.byAgent.get(document.agentId)?.get(title)?.id ?? titleMaps.shared.get(title)?.id
 });
 const embedIndexedDocuments = async (documents, providerName) => {
+    if (documents.length === 0) {
+        return documents;
+    }
     const provider = createEmbeddingProvider(providerName);
     const chunks = documents.flatMap((document) => document.chunks);
     const embeddings = await provider.embed(chunks.map((chunk) => chunk.content));
@@ -47,34 +53,144 @@ const embedIndexedDocuments = async (documents, providerName) => {
         }))
     }));
 };
+const relinkIndexedDocument = (indexedDocument, titleMaps) => {
+    const resolver = createScopedTitleResolver(indexedDocument.document, titleMaps);
+    return {
+        ...indexedDocument,
+        links: indexedDocument.links
+            .map((link) => ({
+            ...link,
+            toDocumentId: resolver.get(link.toTitle.toLowerCase()) ?? null
+        }))
+            .filter((link) => link.toDocumentId !== indexedDocument.document.id)
+    };
+};
+const toIndexResult = (documents) => ({
+    documentCount: documents.length,
+    chunkCount: documents.reduce((total, document) => total + document.chunks.length, 0),
+    linkCount: documents.reduce((total, document) => total + document.links.length, 0)
+});
+const toSnapshot = (summaries) => summaries.map((summary) => ({
+    path: summary.relativePath,
+    mtimeMs: summary.updatedAt.getTime(),
+    size: summary.size
+}));
+const createSnapshotMap = (snapshot) => new Map(snapshot.map((entry) => [entry.path, entry]));
+const packManifestPath = (vaultPath) => join(vaultPath, '.brainlink', 'search-packs', 'manifest.json');
+const hasPackManifest = async (vaultPath) => {
+    try {
+        await stat(packManifestPath(vaultPath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const readChangedDocuments = async (absoluteVaultPath, changedSummaries) => {
+    const parsed = await Promise.all(changedSummaries.map(async (summary) => parseMarkdownDocument({
+        absolutePath: summary.absolutePath,
+        vaultPath: absoluteVaultPath,
+        content: await readFile(summary.absolutePath, 'utf8'),
+        createdAt: summary.createdAt,
+        updatedAt: summary.updatedAt
+    })));
+    return new Map(parsed.map((document) => [document.path, document]));
+};
 export const indexVault = async (vaultPath) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
     const config = await loadBrainlinkConfig();
-    const files = await readMarkdownFiles(absoluteVaultPath);
-    const documents = files.map((file) => parseMarkdownDocument({
-        absolutePath: file.absolutePath,
-        vaultPath: absoluteVaultPath,
-        content: file.content,
-        createdAt: file.createdAt,
-        updatedAt: file.updatedAt
-    }));
-    const titleMaps = createTitleMaps(documents);
-    const indexedDocuments = await embedIndexedDocuments(documents.map((document) => createIndexedDocument(document, createScopedTitleResolver(document, titleMaps), config.chunkSize)), config.embeddingProvider);
+    const [summaries, previousState] = await Promise.all([
+        readMarkdownFileSummaries(absoluteVaultPath),
+        readIndexState(absoluteVaultPath)
+    ]);
     const index = openFileIndex(absoluteVaultPath);
     try {
+        const existingIndexedDocuments = await index.getIndexedDocuments();
+        const existingByPath = new Map(existingIndexedDocuments.map((document) => [document.document.path, document]));
+        const currentSnapshot = toSnapshot(summaries);
+        const currentSnapshotMap = createSnapshotMap(currentSnapshot);
+        const previousSnapshotMap = createSnapshotMap(previousState?.files ?? []);
+        const settingsChanged = previousState == null ||
+            previousState.chunkSize !== config.chunkSize ||
+            previousState.embeddingProvider !== config.embeddingProvider;
+        const changedPaths = new Set();
+        for (let index = 0; index < summaries.length; index += 1) {
+            const summary = summaries[index];
+            const previous = previousSnapshotMap.get(summary.relativePath);
+            const changed = settingsChanged ||
+                previous == null ||
+                previous.mtimeMs !== summary.updatedAt.getTime() ||
+                previous.size !== summary.size ||
+                !existingByPath.has(summary.relativePath);
+            if (changed) {
+                changedPaths.add(summary.relativePath);
+            }
+        }
+        const hasDeletes = previousState
+            ? previousState.files.some((entry) => !currentSnapshotMap.has(entry.path))
+            : false;
+        if (changedPaths.size === 0 &&
+            !hasDeletes &&
+            existingIndexedDocuments.length === summaries.length &&
+            previousState != null) {
+            return toIndexResult(existingIndexedDocuments);
+        }
+        const changedSummaries = summaries.filter((summary) => changedPaths.has(summary.relativePath));
+        const changedDocumentsByPath = await readChangedDocuments(absoluteVaultPath, changedSummaries);
+        const documents = summaries.flatMap((summary) => {
+            const changed = changedDocumentsByPath.get(summary.relativePath);
+            if (changed) {
+                return [changed];
+            }
+            const existing = existingByPath.get(summary.relativePath);
+            return existing ? [existing.document] : [];
+        });
+        const titleMaps = createTitleMaps(documents);
+        const changedIndexedDocuments = changedDocumentsByPath.size > 0
+            ? await embedIndexedDocuments(Array.from(changedDocumentsByPath.values()).map((document) => createIndexedDocument(document, createScopedTitleResolver(document, titleMaps), config.chunkSize)), config.embeddingProvider)
+            : [];
+        const changedIndexedByPath = new Map(changedIndexedDocuments.map((document) => [document.document.path, document]));
+        const needsRelink = settingsChanged || hasDeletes || changedPaths.size > 0;
+        const indexedDocuments = documents.map((document) => {
+            const changed = changedIndexedByPath.get(document.path);
+            if (changed) {
+                return changed;
+            }
+            const existing = existingByPath.get(document.path);
+            if (!existing) {
+                return createIndexedDocument(document, createScopedTitleResolver(document, titleMaps), config.chunkSize);
+            }
+            return needsRelink ? relinkIndexedDocument(existing, titleMaps) : existing;
+        });
         await index.reset();
         await index.saveDocuments(indexedDocuments);
-        try {
-            await buildSearchPacks(absoluteVaultPath, indexedDocuments);
+        const existingPackManifest = await hasPackManifest(absoluteVaultPath);
+        const changedCount = changedPaths.size;
+        const documentCount = Math.max(indexedDocuments.length, 1);
+        const changeRatio = changedCount / documentCount;
+        const previousPendingPackChanges = previousState?.pendingPackChanges ?? 0;
+        const pendingPackChanges = previousPendingPackChanges + changedCount;
+        const shouldRebuildPacks = !existingPackManifest ||
+            settingsChanged ||
+            hasDeletes ||
+            changedCount >= 400 ||
+            changeRatio >= 0.04 ||
+            pendingPackChanges >= 1200;
+        if (shouldRebuildPacks) {
+            try {
+                await buildSearchPacks(absoluteVaultPath, indexedDocuments);
+            }
+            catch {
+                // Pack generation is best-effort. The JSON index remains the primary path.
+            }
         }
-        catch {
-            // Pack generation is best-effort. The JSON index remains the primary path.
-        }
-        return {
-            documentCount: indexedDocuments.length,
-            chunkCount: indexedDocuments.reduce((total, document) => total + document.chunks.length, 0),
-            linkCount: indexedDocuments.reduce((total, document) => total + document.links.length, 0)
-        };
+        await writeIndexState(absoluteVaultPath, {
+            chunkSize: config.chunkSize,
+            embeddingProvider: config.embeddingProvider,
+            files: currentSnapshot,
+            pendingPackChanges: shouldRebuildPacks ? 0 : pendingPackChanges
+        });
+        return toIndexResult(indexedDocuments);
     }
     finally {
         index.close();

package/dist/application/server/routes.js

@@ -11,6 +11,7 @@ import { loadBrainlinkConfig, sanitizeSearchMode } from '../../infrastructure/co
 import { createClientCss } from '../frontend/client-css.js';
 import { createClientHtml } from '../frontend/client-html.js';
 import { createClientJs } from '../frontend/client-js.js';
+import { createClientWorkerJs } from '../frontend/client-worker-js.js';
 import { contentTypes, createJsonResponse, isReadMethod, parsePositiveInteger } from './http.js';
 const readSearchMode = async (url) => {
     const config = await loadBrainlinkConfig();
@@ -51,10 +52,41 @@ const sameEntityTag = (candidate, signature) => {
     return decodeEntityTag(candidate) === signature;
 };
 const readAgentQuery = (url) => url.searchParams.get('agent') ?? undefined;
+const compactGraphLayoutThreshold = 12_000;
+const compactGraphLayoutEdgeLimit = 60_000;
+const compactGraphLayoutEdgeLimitFor = (nodeCount) => {
+    if (nodeCount > 100_000)
+        return 15_000;
+    if (nodeCount > 50_000)
+        return 22_000;
+    if (nodeCount > 25_000)
+        return 30_000;
+    return compactGraphLayoutEdgeLimit;
+};
 const stripLayoutContent = (layout) => ({
     ...layout,
     nodes: layout.nodes.map(({ content, ...node }) => node)
 });
+const compactLayoutPayload = (layout) => {
+    const edgeLimit = compactGraphLayoutEdgeLimitFor(layout.nodes.length);
+    const compactNodes = layout.nodes.map((node) => [node.id, node.title, node.x, node.y, node.group, node.segment]);
+    const compactEdges = [...layout.edges]
+        .sort((left, right) => (right.weight ?? 1) - (left.weight ?? 1))
+        .slice(0, edgeLimit)
+        .map((edge) => [edge.source, edge.target, edge.weight, edge.priority]);
+    return {
+        compact: true,
+        layout: {
+            nodes: compactNodes,
+            edges: compactEdges
+        },
+        totals: {
+            nodes: layout.nodes.length,
+            edges: layout.edges.length
+        }
+    };
+};
+const encodeLayoutPayload = (layout) => layout.nodes.length > compactGraphLayoutThreshold ? compactLayoutPayload(layout) : { compact: false, layout: stripLayoutContent(layout) };
 export const route = async (request, url, vaultPath) => {
     if (isReadMethod(request) && (url.pathname === '/' || url.pathname === '/index.html')) {
         return createResponse(createClientHtml(), 200, contentTypes['.html']);
@@ -65,6 +97,9 @@ export const route = async (request, url, vaultPath) => {
     if (isReadMethod(request) && url.pathname === '/app.js') {
         return createResponse(createClientJs(), 200, contentTypes['.js']);
     }
+    if (isReadMethod(request) && url.pathname === '/app-worker.js') {
+        return createResponse(createClientWorkerJs(), 200, contentTypes['.js']);
+    }
     if (isReadMethod(request) && url.pathname === '/api/graph') {
         return createResponse(createJsonResponse(await getGraph(vaultPath, readAgentQuery(url))), 200, contentTypes['.json']);
     }
@@ -73,7 +108,7 @@ export const route = async (request, url, vaultPath) => {
         const requestEtags = request.headers['if-none-match'];
         const notModified = sameEntityTag(requestEtags, signature);
         const etag = encodeEntityTag(signature);
-        const body = createJsonResponse({ signature, layout: stripLayoutContent(layout) });
+        const body = createJsonResponse({ signature, ...encodeLayoutPayload(layout) });
         const jsonResponse = createResponse(body, 200, contentTypes['.json']);
         const notModifiedResponse = createResponse('', 304, contentTypes['.json']);
         if (notModified) {

package/dist/application/start-server.js

@@ -1,9 +1,78 @@
 import { createServer } from 'node:http';
+import { brotliCompressSync, constants, gzipSync } from 'node:zlib';
 import { indexVault } from './index-vault.js';
 import { startVaultWatcher } from './watch-vault.js';
 import { assertLoopbackHost } from './server/host-security.js';
 import { contentTypes, createJsonResponse, isHttpError } from './server/http.js';
 import { route } from './server/routes.js';
+const compressionThresholdBytes = 1024;
+const normalizeEncodingToken = (value) => value.trim().toLowerCase();
+const supportsEncoding = (acceptEncoding, target) => {
+    if (!acceptEncoding) {
+        return false;
+    }
+    return acceptEncoding
+        .split(',')
+        .map((entry) => entry.split(';')[0] ?? '')
+        .map(normalizeEncodingToken)
+        .includes(target);
+};
+const isCompressibleContentType = (contentType) => {
+    const normalized = contentType?.toLowerCase() ?? '';
+    return (normalized.includes('application/json') ||
+        normalized.includes('text/javascript') ||
+        normalized.includes('text/css') ||
+        normalized.includes('text/html') ||
+        normalized.startsWith('text/'));
+};
+const maybeCompressResponse = (requestHeaders, statusCode, headers, body) => {
+    if (statusCode === 204 || statusCode === 304) {
+        return { headers, body: '' };
+    }
+    if (!isCompressibleContentType(headers['content-type'])) {
+        return { headers, body };
+    }
+    const bodyBuffer = Buffer.from(body, 'utf8');
+    if (bodyBuffer.byteLength < compressionThresholdBytes) {
+        return { headers, body };
+    }
+    if (headers['content-encoding']) {
+        return { headers, body };
+    }
+    const acceptEncodingHeader = Array.isArray(requestHeaders['accept-encoding'])
+        ? requestHeaders['accept-encoding'].join(',')
+        : requestHeaders['accept-encoding'];
+    const vary = headers.vary ? `${headers.vary}, Accept-Encoding` : 'Accept-Encoding';
+    const withVary = {
+        ...headers,
+        vary
+    };
+    if (supportsEncoding(acceptEncodingHeader, 'br')) {
+        return {
+            headers: {
+                ...withVary,
+                'content-encoding': 'br'
+            },
+            body: brotliCompressSync(bodyBuffer, {
+                params: {
+                    [constants.BROTLI_PARAM_QUALITY]: 5
+                }
+            })
+        };
+    }
+    if (supportsEncoding(acceptEncodingHeader, 'gzip')) {
+        return {
+            headers: {
+                ...withVary,
+                'content-encoding': 'gzip'
+            },
+            body: gzipSync(bodyBuffer, {
+                level: 6
+            })
+        };
+    }
+    return { headers: withVary, body };
+};
 export const startServer = async (input) => {
     assertLoopbackHost(input.host);
     if (input.shouldIndex) {
@@ -19,14 +88,16 @@ export const startServer = async (input) => {
         const url = new URL(request.url ?? '/', `http://${request.headers.host ?? input.host}`);
         route(request, url, input.vaultPath)
             .then((result) => {
-            response.writeHead(result.statusCode, result.headers);
-            response.end(result.body);
+            const encoded = maybeCompressResponse(request.headers, result.statusCode, result.headers, result.body);
+            response.writeHead(result.statusCode, encoded.headers);
+            response.end(encoded.body);
         })
             .catch((error) => {
             const message = error instanceof Error ? error.message : String(error);
             const statusCode = isHttpError(error) ? error.statusCode : 500;
-            response.writeHead(statusCode, { 'content-type': contentTypes['.json'] });
-            response.end(createJsonResponse({ error: message }));
+            const fallback = maybeCompressResponse(request.headers, statusCode, { 'content-type': contentTypes['.json'] }, createJsonResponse({ error: message }));
+            response.writeHead(statusCode, fallback.headers);
+            response.end(fallback.body);
         });
     });
     await new Promise((resolve, reject) => {

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

@@ -37,9 +37,13 @@ const parseScore = (value, fallback) => {
     }
     return parsed;
 };
-const spawnDetached = (command, args) => {
+const spawnDetached = (command, args, envOverrides) => {
     try {
-        const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: 'ignore',
+            env: envOverrides ? { ...process.env, ...envOverrides } : process.env
+        });
         child.unref();
         return true;
     }
@@ -219,6 +223,7 @@ const commandExists = (command) => {
 };
 const envFlagEnabled = (name) => process.env[name] === '1' || process.env[name] === 'true';
 const spawnAnyDetached = (candidates) => candidates.some(([command, args]) => spawnDetached(command, args));
+const spawnAnyDetachedWithEnv = (candidates) => candidates.some(([command, args, env]) => spawnDetached(command, args, env));
 const windowsStartCandidates = (program, args = []) => [
     ['cmd', ['/c', 'start', '', program, ...args]]
 ];
@@ -318,6 +323,16 @@ const openGraphInAppWindow = (url) => {
         ]);
     }
     const appArgument = `--app=${url}`;
+    const linuxChromiumStableFlags = [
+        '--ozone-platform=x11',
+        '--disable-gpu',
+        '--disable-features=Vulkan,VaapiVideoDecoder',
+        '--disable-background-networking'
+    ];
+    const linuxChromiumEnv = {
+        GDK_BACKEND: 'x11',
+        OZONE_PLATFORM: 'x11'
+    };
     const linuxAppWindowCandidates = [
         'microsoft-edge',
         'microsoft-edge-stable',
@@ -327,7 +342,11 @@ const openGraphInAppWindow = (url) => {
         'chromium-browser',
         'brave-browser'
     ].filter((candidate) => commandExists(candidate));
-    return spawnAnyDetached(linuxAppWindowCandidates.map((command) => [command, [appArgument, '--new-window']]));
+    return spawnAnyDetachedWithEnv(linuxAppWindowCandidates.map((command) => [
+        command,
+        [...linuxChromiumStableFlags, appArgument, '--new-window'],
+        linuxChromiumEnv
+    ]));
 };
 const openGraphInDetectedBrowser = (url) => {
     if (platform() === 'win32') {
@@ -339,18 +358,28 @@ const openGraphInDetectedBrowser = (url) => {
             ...windowsStartCandidates('brave', [url])
         ]);
     }
+    const linuxChromiumStableFlags = [
+        '--ozone-platform=x11',
+        '--disable-gpu',
+        '--disable-features=Vulkan,VaapiVideoDecoder',
+        '--disable-background-networking'
+    ];
+    const linuxChromiumEnv = {
+        GDK_BACKEND: 'x11',
+        OZONE_PLATFORM: 'x11'
+    };
     const linuxBrowserCandidates = [
-        ['microsoft-edge', [url]],
-        ['microsoft-edge-stable', [url]],
-        ['google-chrome', [url]],
-        ['google-chrome-stable', [url]],
-        ['chromium', [url]],
-        ['chromium-browser', [url]],
-        ['brave-browser', [url]],
-        ['firefox', ['-new-window', url]]
+        ['microsoft-edge', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['microsoft-edge-stable', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['google-chrome', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['google-chrome-stable', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['chromium', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['chromium-browser', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['brave-browser', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['firefox', ['-new-window', url], undefined]
     ];
     const available = linuxBrowserCandidates.filter(([command]) => commandExists(command));
-    return spawnAnyDetached(available);
+    return spawnAnyDetachedWithEnv(available);
 };
 const openUrlInUi = (url, parentPid) => {
     const openDisabled = process.env.BRAINLINK_NO_BROWSER === '1' ||

package/dist/infrastructure/file-index.js

@@ -155,6 +155,36 @@ export const openFileIndex = (vaultPath) => {
                 links
             });
         },
+        getIndexedDocuments: async (agentId) => {
+            const index = await load();
+            const documents = agentId ? index.documents.filter((document) => document.agentId === agentId) : index.documents;
+            const selectedDocumentIds = new Set(documents.map((document) => document.id));
+            const chunksByDocumentId = index.chunks.reduce((state, chunk) => {
+                if (!selectedDocumentIds.has(chunk.documentId)) {
+                    return state;
+                }
+                const current = state.get(chunk.documentId) ?? [];
+                current.push(chunk);
+                state.set(chunk.documentId, current);
+                return state;
+            }, new Map());
+            const linksByDocumentId = index.links.reduce((state, link) => {
+                if (!selectedDocumentIds.has(link.fromDocumentId)) {
+                    return state;
+                }
+                const current = state.get(link.fromDocumentId) ?? [];
+                current.push(link);
+                state.set(link.fromDocumentId, current);
+                return state;
+            }, new Map());
+            return documents
+                .map((document) => ({
+                document,
+                chunks: [...(chunksByDocumentId.get(document.id) ?? [])].sort((left, right) => left.ordinal - right.ordinal),
+                links: linksByDocumentId.get(document.id) ?? []
+            }))
+                .sort((left, right) => left.document.path.localeCompare(right.document.path));
+        },
         search: async (query, limit, agentId, mode = 'hybrid', queryEmbedding = []) => {
             const index = await load();
             const documentsById = new Map(index.documents.map((document) => [document.id, document]));

package/dist/infrastructure/file-system-vault.js

@@ -76,6 +76,21 @@ export const readMarkdownFiles = async (vaultPath) => {
         };
     }));
 };
+export const readMarkdownFileSummaries = async (vaultPath) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const paths = await walkMarkdownFiles(absoluteVaultPath);
+    const summaries = await Promise.all(paths.map(async (absolutePath) => {
+        const fileStats = await stat(absolutePath);
+        return {
+            absolutePath,
+            relativePath: relative(absoluteVaultPath, absolutePath),
+            createdAt: fileStats.birthtime,
+            updatedAt: fileStats.mtime,
+            size: fileStats.size
+        };
+    }));
+    return summaries.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+};
 export const listVaultFiles = async (vaultPath) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
     return walkVaultFiles(absoluteVaultPath);

package/dist/infrastructure/index-state.js

@@ -0,0 +1,50 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const indexStateFileName = 'index-state.json';
+const toIndexStatePath = (vaultPath) => join(vaultPath, '.brainlink', indexStateFileName);
+export const readIndexState = async (vaultPath) => {
+    try {
+        const parsed = JSON.parse(await readFile(toIndexStatePath(vaultPath), 'utf8'));
+        if (parsed.version !== 1 || !Array.isArray(parsed.files)) {
+            return null;
+        }
+        const files = parsed.files.flatMap((entry) => {
+            if (!entry || typeof entry !== 'object') {
+                return [];
+            }
+            const row = entry;
+            if (typeof row.path !== 'string' || typeof row.mtimeMs !== 'number' || typeof row.size !== 'number') {
+                return [];
+            }
+            return [
+                {
+                    path: row.path,
+                    mtimeMs: row.mtimeMs,
+                    size: row.size
+                }
+            ];
+        });
+        return {
+            version: 1,
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+            chunkSize: typeof parsed.chunkSize === 'number' ? parsed.chunkSize : 1200,
+            embeddingProvider: typeof parsed.embeddingProvider === 'string' ? parsed.embeddingProvider : 'none',
+            files,
+            pendingPackChanges: typeof parsed.pendingPackChanges === 'number' && parsed.pendingPackChanges >= 0 ? parsed.pendingPackChanges : 0
+        };
+    }
+    catch {
+        return null;
+    }
+};
+export const writeIndexState = async (vaultPath, state) => {
+    const payload = {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        chunkSize: state.chunkSize,
+        embeddingProvider: state.embeddingProvider,
+        files: [...state.files].sort((left, right) => left.path.localeCompare(right.path)),
+        pendingPackChanges: Math.max(0, Math.floor(state.pendingPackChanges))
+    };
+    await writeFile(toIndexStatePath(vaultPath), `${JSON.stringify(payload)}\n`, 'utf8');
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.40",
+  "version": "0.1.0-beta.42",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",