noteconnection 1.7.0 → 1.9.0

package/dist/src/frontend/storage_provider.js

@@ -42,12 +42,44 @@
 
     let capacitorFsPermissionGranted = false;
     let capacitorFsPermissionPromise = null;
-    const CAPACITOR_GRAPH_BUILD_MAX_FILES = 2000;
-    const CAPACITOR_GRAPH_BUILD_MAX_BYTES = 16 * 1024 * 1024;
     const CAPACITOR_GRAPH_BUILD_WORKER_TIMEOUT_MS = 20000;
     const CAPACITOR_BRIDGE_MAX_CHUNK_BYTES = 192 * 1024;
-    const CAPACITOR_BRIDGE_MAX_TEXT_PAYLOAD_BYTES = 64 * 1024 * 1024;
     const CAPACITOR_GRAPH_SERIALIZATION_MAX_BYTES = 48 * 1024 * 1024;
+    const CAPACITOR_BRIDGE_MAX_TEXT_PAYLOAD_BYTES = 64 * 1024 * 1024;
+    const FALLBACK_MOBILE_RUNTIME_BUDGET = Object.freeze({
+        maxDocuments: 5000,
+        maxDocumentBytes: 16 * 1024 * 1024,
+        maxTotalInputBytes: 64 * 1024 * 1024,
+        maxEdges: 250000,
+        maxDepth: 64,
+        maxProjectionBytes: CAPACITOR_GRAPH_SERIALIZATION_MAX_BYTES
+    });
+
+    function getMobileRuntimeBudget() {
+        const candidate = typeof window !== 'undefined' ? window.NoteConnectionMobileBudget : null;
+        const runtime = candidate && candidate.runtime;
+        if (!runtime || typeof runtime !== 'object') {
+            return FALLBACK_MOBILE_RUNTIME_BUDGET;
+        }
+
+        const keys = Object.keys(FALLBACK_MOBILE_RUNTIME_BUDGET);
+        const isValid = keys.every((key) => Number.isInteger(runtime[key]) && runtime[key] > 0);
+        return isValid ? runtime : FALLBACK_MOBILE_RUNTIME_BUDGET;
+    }
+
+    function measureUtf8Bytes(textPayload) {
+        const text = String(textPayload || '');
+        if (!text) {
+            return 0;
+        }
+        if (typeof TextEncoder === 'function') {
+            return new TextEncoder().encode(text).length;
+        }
+        if (typeof Buffer !== 'undefined' && typeof Buffer.byteLength === 'function') {
+            return Buffer.byteLength(text, 'utf8');
+        }
+        return text.length;
+    }
 
     function getCapacitorDirectoryHints(filesystem) {
         const directoryHints = [];
@@ -170,13 +202,40 @@
             .pop() || '';
     }
 
+    function canonicalMobileNodeIdFromIdentity(identity) {
+        const sourceUri = identity && typeof identity.sourceUri === 'string'
+            ? identity.sourceUri
+            : '';
+        const prefix = 'note://workspace/v1/';
+        if (!sourceUri.startsWith(prefix)) {
+            return '';
+        }
+        try {
+            return decodeURIComponent(sourceUri.slice(prefix.length))
+                .replace(/\.(?:md|markdown)$/i, '')
+                .trim();
+        } catch (_error) {
+            return '';
+        }
+    }
+
+    async function createMobileResourceIdentity(relativePath, legacyId, content) {
+        const identityContract = typeof globalThis !== 'undefined'
+            ? globalThis.NoteConnectionMobileIdentity
+            : null;
+        if (!identityContract || typeof identityContract.createResourceIdentity !== 'function') {
+            throw new Error('Mobile identity contract is unavailable.');
+        }
+        return await identityContract.createResourceIdentity(relativePath, legacyId, content);
+    }
+
     function extractWikiLinks(content) {
         const links = new Set();
         const regex = /\[\[(.*?)(?:\|.*?)?\]\]/g;
         const text = String(content || '');
         let match;
         while ((match = regex.exec(text)) !== null) {
-            const linked = stripMarkdownExtension(match[1]);
+            const linked = String(match[1] || '').trim();
             if (linked) {
                 links.add(linked);
             }
@@ -184,6 +243,122 @@
         return Array.from(links);
     }
 
+    function extractMarkdownLinks(content) {
+        const links = new Set();
+        const regex = /\]\(([^)]+)\)/g;
+        const text = String(content || '');
+        let match;
+        while ((match = regex.exec(text)) !== null) {
+            const linked = String(match[1] || '').trim();
+            if (linked) {
+                links.add(linked);
+            }
+        }
+        return Array.from(links);
+    }
+
+    function normalizeCapacitorCanonicalId(value) {
+        const normalized = String(value || '')
+            .normalize('NFC')
+            .replace(/\\/g, '/')
+            .replace(/^knowledge_base\//i, '')
+            .replace(/^\/+/, '')
+            .trim();
+        const segments = [];
+        for (const segment of normalized.split('/')) {
+            if (!segment || segment === '.') {
+                continue;
+            }
+            if (segment === '..') {
+                if (segments.length === 0) {
+                    return '';
+                }
+                segments.pop();
+                continue;
+            }
+            segments.push(segment);
+        }
+        return segments.join('/').replace(/\.(?:md|markdown)$/i, '').toLowerCase();
+    }
+
+    function cleanCapacitorReference(rawReference) {
+        let reference = String(rawReference || '').trim();
+        const wikiMatch = reference.match(/^\[\[(.*?)(?:\|.*?)?\]\]$/);
+        if (wikiMatch) {
+            reference = String(wikiMatch[1] || '').trim();
+        }
+        reference = reference.replace(/^['"]|['"]$/g, '').trim();
+        reference = reference.split('#')[0].split('?')[0].trim();
+        if (!reference || /^[a-z][a-z0-9+.-]*:/i.test(reference) || reference.startsWith('/')) {
+            return '';
+        }
+        try {
+            reference = decodeURIComponent(reference);
+        } catch (_error) {
+            return '';
+        }
+        return reference;
+    }
+
+    function resolveCapacitorReferencePath(sourceCanonicalId, rawReference) {
+        const reference = cleanCapacitorReference(rawReference);
+        if (!reference) {
+            return '';
+        }
+        const direct = normalizeCapacitorCanonicalId(reference);
+        const sourceSegments = normalizeCapacitorCanonicalId(sourceCanonicalId).split('/').filter(Boolean);
+        sourceSegments.pop();
+        const relative = normalizeCapacitorCanonicalId([...sourceSegments, reference].join('/'));
+        return { direct, relative };
+    }
+
+    function buildCapacitorReferenceIndex(files) {
+        const byCanonicalId = new Map();
+        const byLegacyId = new Map();
+        const byUniqueStem = new Map();
+        files.forEach((file) => {
+            const canonicalId = normalizeCapacitorCanonicalId(
+                file.canonicalId || canonicalMobileNodeIdFromIdentity(file) || file.path || file.id
+            );
+            if (!file.id || !canonicalId) {
+                return;
+            }
+            const legacyKey = String(file.id).normalize('NFC').toLowerCase();
+            if (byLegacyId.has(legacyKey)) {
+                throw new Error(`Capacitor graph contains an ambiguous legacy basename: ${file.id}`);
+            }
+            if (byCanonicalId.has(canonicalId)) {
+                throw new Error(`Capacitor graph contains duplicate canonical node id: ${canonicalId}`);
+            }
+            byLegacyId.set(legacyKey, file);
+            byCanonicalId.set(canonicalId, file);
+            const stem = canonicalId.split('/').pop() || canonicalId;
+            const stemCandidates = byUniqueStem.get(stem) || [];
+            stemCandidates.push(file);
+            byUniqueStem.set(stem, stemCandidates);
+            file.__canonicalId = canonicalId;
+        });
+        return { byCanonicalId, byLegacyId, byUniqueStem };
+    }
+
+    function resolveCapacitorReference(sourceFile, rawReference, referenceIndex) {
+        const paths = resolveCapacitorReferencePath(sourceFile.__canonicalId, rawReference);
+        if (!paths) {
+            return null;
+        }
+        const direct = referenceIndex.byCanonicalId.get(paths.direct);
+        if (direct) {
+            return direct;
+        }
+        const relative = referenceIndex.byCanonicalId.get(paths.relative);
+        if (relative) {
+            return relative;
+        }
+        const stem = paths.direct.split('/').pop() || paths.direct;
+        const candidates = referenceIndex.byUniqueStem.get(stem) || [];
+        return candidates.length === 1 ? candidates[0] : null;
+    }
+
     function normalizeCapacitorPath(pathValue, options) {
         const allowCurrentDir = Boolean(options && options.allowCurrentDir);
         const normalized = String(pathValue || '').replace(/\\/g, '/').replace(/^\/+/, '');
@@ -235,6 +410,20 @@
         return null;
     }
 
+    function extractRelativePathFromWorkspaceUri(rawFilePath) {
+        const normalized = String(rawFilePath || '').replace(/\\/g, '/');
+        const prefix = 'note://workspace/v1/';
+        if (!normalized.toLowerCase().startsWith(prefix)) {
+            return null;
+        }
+        try {
+            const relative = decodeURIComponent(normalized.slice(prefix.length));
+            return relative.length > 0 ? relative : null;
+        } catch (_error) {
+            throw new Error('Invalid workspace source URI for Capacitor content read.');
+        }
+    }
+
     function resolveCapacitorContentCandidatePath(rawFilePath) {
         const raw = String(rawFilePath || '').trim();
         if (!raw) {
@@ -247,6 +436,15 @@
             return normalizeCapacitorPath(`Knowledge_Base/${relativeFromKb}`);
         }
 
+        const relativeFromWorkspaceUri = extractRelativePathFromWorkspaceUri(raw);
+        if (relativeFromWorkspaceUri) {
+            return normalizeCapacitorPath(`Knowledge_Base/${relativeFromWorkspaceUri}`);
+        }
+
+        if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(normalized)) {
+            throw new Error('Cannot map non-workspace URI on Capacitor without Knowledge_Base marker.');
+        }
+
         if (/^[A-Za-z]:\//.test(normalized) || normalized.startsWith('/')) {
             throw new Error('Cannot map absolute desktop path on Capacitor without Knowledge_Base marker.');
         }
@@ -404,20 +602,6 @@
         }
     }
 
-    function measureUtf8Bytes(textPayload) {
-        const text = String(textPayload || '');
-        if (!text) {
-            return 0;
-        }
-        if (typeof TextEncoder === 'function') {
-            return new TextEncoder().encode(text).length;
-        }
-        if (typeof Buffer !== 'undefined' && typeof Buffer.byteLength === 'function') {
-            return Buffer.byteLength(text, 'utf8');
-        }
-        return text.length;
-    }
-
     async function writeCapacitorChunkSequenceToDirectory(filesystem, normalizedPath, chunkSequenceFactory, options) {
         const directory = options && Object.prototype.hasOwnProperty.call(options, 'directory')
             ? options.directory
@@ -580,6 +764,10 @@
         const explicitDirectory = options && Object.prototype.hasOwnProperty.call(options, 'directory')
             ? options.directory
             : undefined;
+        const maxBytes = Math.max(
+            1024,
+            Math.floor(Number(options && options.maxBytes) || CAPACITOR_BRIDGE_MAX_TEXT_PAYLOAD_BYTES)
+        );
         const directoryHints = explicitDirectory === undefined
             ? getCapacitorDirectoryHints(filesystem)
             : [explicitDirectory];
@@ -591,9 +779,41 @@
                 if (directory) {
                     args.directory = directory;
                 }
+                // Stat is a preflight guard: reading an oversized note first would
+                // defeat the low-memory contract even if the decoded text is later rejected.
+                if (typeof filesystem.stat === 'function') {
+                    try {
+                        const statResult = await filesystem.stat(args);
+                        const reportedBytes = Number(statResult && statResult.size);
+                        if (Number.isFinite(reportedBytes) && reportedBytes > maxBytes) {
+                            const budgetError = new Error(
+                                `Capacitor file exceeds ${maxBytes} bytes: ${normalizedPath}`
+                            );
+                            budgetError.code = 'MOBILE_BUDGET_EXCEEDED';
+                            throw budgetError;
+                        }
+                    } catch (err) {
+                        if (err && err.code === 'MOBILE_BUDGET_EXCEEDED') {
+                            throw err;
+                        }
+                        // Some Capacitor versions do not expose stat for SAF handles;
+                        // the bounded decoded-text check below remains the fallback.
+                    }
+                }
                 const result = await filesystem.readFile(args);
-                return decodeCapacitorTextPayload(result);
+                const text = decodeCapacitorTextPayload(result);
+                if (measureUtf8Bytes(text) > maxBytes) {
+                    const budgetError = new Error(
+                        `Capacitor file exceeds ${maxBytes} bytes: ${normalizedPath}`
+                    );
+                    budgetError.code = 'MOBILE_BUDGET_EXCEEDED';
+                    throw budgetError;
+                }
+                return text;
             } catch (err) {
+                if (err && err.code === 'MOBILE_BUDGET_EXCEEDED') {
+                    throw err;
+                }
                 lastError = err;
             }
         }
@@ -704,13 +924,21 @@
     }
 
     async function collectCapacitorMarkdownFiles(targetPath) {
-        const queue = [normalizeCapacitorPath(targetPath, { allowCurrentDir: true })];
+        const budget = getMobileRuntimeBudget();
+        const queue = [{
+            path: normalizeCapacitorPath(targetPath, { allowCurrentDir: true }),
+            depth: 0
+        }];
         const visited = new Set();
         const files = [];
         let totalBytes = 0;
 
         while (queue.length > 0) {
-            const current = queue.shift();
+            const currentEntry = queue.shift();
+            const current = currentEntry && currentEntry.path;
+            const currentDepth = currentEntry && Number.isInteger(currentEntry.depth)
+                ? currentEntry.depth
+                : 0;
             if (!current || visited.has(current)) {
                 continue;
             }
@@ -723,23 +951,47 @@
                 }
 
                 const looksLikeMarkdown = /\.md$/i.test(entry.name);
+                const entryDepth = currentDepth + 1;
+                if (entryDepth > budget.maxDepth) {
+                    throw new Error(
+                        `Capacitor local build directory depth exceeds ${budget.maxDepth}. ` +
+                        'Please flatten the knowledge base or build on desktop.'
+                    );
+                }
                 if (entry.isDirectory === true) {
-                    queue.push(entry.path);
+                    queue.push({ path: entry.path, depth: entryDepth });
                     continue;
                 }
                 if (entry.isDirectory === null && !looksLikeMarkdown) {
-                    queue.push(entry.path);
+                    queue.push({ path: entry.path, depth: entryDepth });
                     continue;
                 }
                 if (!looksLikeMarkdown) {
                     continue;
                 }
 
-                const rawText = await capacitorReadText(entry.path, { directory: entry.directory });
-                totalBytes += rawText.length;
-                if (totalBytes > CAPACITOR_GRAPH_BUILD_MAX_BYTES) {
+                if (files.length >= budget.maxDocuments) {
                     throw new Error(
-                        `Capacitor local build payload exceeds ${CAPACITOR_GRAPH_BUILD_MAX_BYTES} bytes. ` +
+                        `Capacitor local build file count exceeds ${budget.maxDocuments}. ` +
+                        'Please build on desktop for large datasets.'
+                    );
+                }
+
+                const rawText = await capacitorReadText(entry.path, {
+                    directory: entry.directory,
+                    maxBytes: budget.maxDocumentBytes
+                });
+                const documentBytes = measureUtf8Bytes(rawText);
+                if (documentBytes > budget.maxDocumentBytes) {
+                    throw new Error(
+                        `Capacitor local build document exceeds ${budget.maxDocumentBytes} bytes. ` +
+                        'Please split the note or build on desktop.'
+                    );
+                }
+                totalBytes += documentBytes;
+                if (totalBytes > budget.maxTotalInputBytes) {
+                    throw new Error(
+                        `Capacitor local build payload exceeds ${budget.maxTotalInputBytes} bytes. ` +
                         'Please build on desktop for large datasets.'
                     );
                 }
@@ -753,22 +1005,21 @@
                 const relativePath = entry.path;
                 const segments = relativePath.split('/').filter(Boolean);
                 const clusterId = segments.length > 1 ? segments[segments.length - 2] : 'root';
+                const identity = await createMobileResourceIdentity(relativePath, filename, rawText);
 
                 files.push({
                     id: filename,
+                    canonicalId: identity.canonicalId || canonicalMobileNodeIdFromIdentity(identity),
                     label: filename,
                     path: relativePath,
+                    sourceUri: identity.sourceUri,
+                    revision: identity.revision,
+                    identityAliases: identity.identityAliases,
                     content: rawText,
                     metadata,
                     clusterId
                 });
 
-                if (files.length > CAPACITOR_GRAPH_BUILD_MAX_FILES) {
-                    throw new Error(
-                        `Capacitor local build file count exceeds ${CAPACITOR_GRAPH_BUILD_MAX_FILES}. ` +
-                        'Please build on desktop for large datasets.'
-                    );
-                }
             }
         }
 
@@ -778,6 +1029,8 @@
     function buildCapacitorGraphData(files) {
         const nodeMap = new Map();
         const edgeMap = new Map();
+        const sourceFiles = Array.isArray(files) ? files.filter((file) => file && file.id) : [];
+        const referenceIndex = buildCapacitorReferenceIndex(sourceFiles);
 
         const addEdge = (source, target, type) => {
             if (!source || !target || source === target) {
@@ -786,25 +1039,39 @@
             if (!nodeMap.has(source) || !nodeMap.has(target)) {
                 return;
             }
-            const key = `${source}->${target}`;
+            const edgeType = type || 'association';
+            const key = `${source}->${target}:${edgeType}`;
             if (edgeMap.has(key)) {
                 return;
             }
+            const sourceNode = nodeMap.get(source);
+            const targetNode = nodeMap.get(target);
             edgeMap.set(key, {
                 source,
                 target,
-                type: type || 'association',
+                type: edgeType,
+                kind: 'explicit',
+                provenance: edgeType,
+                sourceUri: sourceNode && sourceNode.sourceUri ? sourceNode.sourceUri : '',
+                targetUri: targetNode && targetNode.sourceUri ? targetNode.sourceUri : '',
                 weight: 1
             });
         };
 
-        files.forEach((file) => {
-            if (!file || !file.id || nodeMap.has(file.id)) {
+        sourceFiles.forEach((file) => {
+            if (!file || !file.id) {
                 return;
             }
+            if (nodeMap.has(file.id)) {
+                throw new Error(`Capacitor graph contains duplicate legacy node id: ${file.id}`);
+            }
             nodeMap.set(file.id, {
                 id: file.id,
+                canonicalId: file.canonicalId || file.__canonicalId || '',
                 label: file.label || file.id,
+                sourceUri: file.sourceUri || '',
+                revision: file.revision || '',
+                identityAliases: Array.isArray(file.identityAliases) ? file.identityAliases : [],
                 inDegree: 0,
                 outDegree: 0,
                 metadata: {
@@ -819,7 +1086,7 @@
             });
         });
 
-        files.forEach((file) => {
+        sourceFiles.forEach((file) => {
             const sourceId = file.id;
             if (!nodeMap.has(sourceId)) {
                 return;
@@ -829,24 +1096,37 @@
                 ? file.metadata.prerequisites
                 : [];
             prerequisites.forEach((rawPrereq) => {
-                const prereqId = stripMarkdownExtension(rawPrereq);
-                addEdge(prereqId, sourceId, 'explicit-prerequisite');
+                const prerequisiteFile = resolveCapacitorReference(file, rawPrereq, referenceIndex);
+                addEdge(prerequisiteFile && prerequisiteFile.id, sourceId, 'explicit-prerequisite');
             });
 
             const nextItems = Array.isArray(file.metadata && file.metadata.next)
                 ? file.metadata.next
                 : [];
             nextItems.forEach((rawNext) => {
-                const nextId = stripMarkdownExtension(rawNext);
-                addEdge(sourceId, nextId, 'explicit-next');
+                const nextFile = resolveCapacitorReference(file, rawNext, referenceIndex);
+                addEdge(sourceId, nextFile && nextFile.id, 'explicit-next');
+            });
+
+            extractWikiLinks(file.content).forEach((rawLink) => {
+                const linkedFile = resolveCapacitorReference(file, rawLink, referenceIndex);
+                addEdge(sourceId, linkedFile && linkedFile.id, 'wiki-link');
             });
 
-            extractWikiLinks(file.content).forEach((linkedId) => {
-                addEdge(linkedId, sourceId, 'wiki-link');
+            extractMarkdownLinks(file.content).forEach((rawLink) => {
+                const linkedFile = resolveCapacitorReference(file, rawLink, referenceIndex);
+                addEdge(sourceId, linkedFile && linkedFile.id, 'markdown-link');
             });
         });
 
         const edges = Array.from(edgeMap.values());
+        const budget = getMobileRuntimeBudget();
+        if (edges.length > budget.maxEdges) {
+            throw new Error(
+                `Capacitor graph edge count exceeds ${budget.maxEdges}. ` +
+                'Please reduce links or build on desktop for large datasets.'
+            );
+        }
         edges.forEach((edge) => {
             const sourceNode = nodeMap.get(edge.source);
             const targetNode = nodeMap.get(edge.target);
@@ -889,13 +1169,78 @@
             '  try {',
             '    var files = Array.isArray(event.data && event.data.files) ? event.data.files : [];',
             '    function stripMarkdownExtension(value) {',
-            "      return String(value || '')",
-            '        .trim()',
-            "        .replace(/\\.md$/i, '')",
+            '      var normalized = String(value || "").trim()',
+            "        .replace(/\\.(?:md|markdown)$/i, '')",
             "        .replace(/\\\\/g, '/')",
-            "        .split('/')",
-            '        .filter(Boolean)',
-            '        .pop() || "";',
+            '        .replace(/^knowledge_base\\//i, "")',
+            '        .replace(/^\\/+/, "");',
+            '      var parts = [];',
+            '      normalized.split("/").forEach(function(part) {',
+            '        if (!part || part === ".") return;',
+            '        if (part === "..") { if (parts.length > 0) parts.pop(); return; }',
+            '        parts.push(part);',
+            '      });',
+            '      return parts.join("/").normalize("NFC").toLowerCase();',
+            '    }',
+            '',
+            '    function cleanReference(rawReference) {',
+            '      var reference = String(rawReference || "").trim();',
+            '      var wikiMatch = reference.match(/^\\[\\[(.*?)(?:\\|.*?)?\\]\\]$/);',
+            '      if (wikiMatch) reference = String(wikiMatch[1] || "").trim();',
+            '      reference = reference.replace(/^[\'\"]|[\'\"]$/g, "").split("#")[0].split("?")[0].trim();',
+            '      if (!reference || /^[a-z][a-z0-9+.-]*:/i.test(reference) || reference.charAt(0) === "/") return "";',
+            '      try { return decodeURIComponent(reference); } catch (_error) { return ""; }',
+            '    }',
+            '',
+            '    function canonicalIdFromSourceUri(file) {',
+            '      var sourceUri = String(file && file.sourceUri || "");',
+            '      var prefix = "note://workspace/v1/";',
+            '      if (!sourceUri.startsWith(prefix)) return "";',
+            '      try { return stripMarkdownExtension(decodeURIComponent(sourceUri.slice(prefix.length))); }',
+            '      catch (_error) { return ""; }',
+            '    }',
+            '',
+            '    function resolveReferencePath(sourceCanonicalId, rawReference) {',
+            '      var reference = cleanReference(rawReference);',
+            '      if (!reference) return null;',
+            '      var direct = stripMarkdownExtension(reference);',
+            '      var sourceSegments = stripMarkdownExtension(sourceCanonicalId).split("/").filter(Boolean);',
+            '      sourceSegments.pop();',
+            '      var relative = stripMarkdownExtension(sourceSegments.concat([reference]).join("/"));',
+            '      return { direct: direct, relative: relative };',
+            '    }',
+            '',
+            '    function buildReferenceIndex(files) {',
+            '      var byCanonicalId = new Map();',
+            '      var byLegacyId = new Map();',
+            '      var byUniqueStem = new Map();',
+            '      files.forEach(function(file) {',
+            '        var canonicalId = stripMarkdownExtension(file.canonicalId || canonicalIdFromSourceUri(file) || file.path || file.id);',
+            '        var legacyKey = String(file.id || "").normalize("NFC").toLowerCase();',
+            '        if (!file.id || !canonicalId) return;',
+            '        if (byLegacyId.has(legacyKey)) throw new Error("Capacitor graph contains an ambiguous legacy basename: " + file.id);',
+            '        if (byCanonicalId.has(canonicalId)) throw new Error("Capacitor graph contains duplicate canonical node id: " + canonicalId);',
+            '        file.__canonicalId = canonicalId;',
+            '        byLegacyId.set(legacyKey, file);',
+            '        byCanonicalId.set(canonicalId, file);',
+            '        var stem = canonicalId.split("/").pop() || canonicalId;',
+            '        var candidates = byUniqueStem.get(stem) || [];',
+            '        candidates.push(file);',
+            '        byUniqueStem.set(stem, candidates);',
+            '      });',
+            '      return { byCanonicalId: byCanonicalId, byUniqueStem: byUniqueStem };',
+            '    }',
+            '',
+            '    function resolveReference(sourceFile, rawReference, index) {',
+            '      var paths = resolveReferencePath(sourceFile.__canonicalId, rawReference);',
+            '      if (!paths) return null;',
+            '      var direct = index.byCanonicalId.get(paths.direct);',
+            '      if (direct) return direct;',
+            '      var relative = index.byCanonicalId.get(paths.relative);',
+            '      if (relative) return relative;',
+            '      var stem = paths.direct.split("/").pop() || paths.direct;',
+            '      var candidates = index.byUniqueStem.get(stem) || [];',
+            '      return candidates.length === 1 ? candidates[0] : null;',
             '    }',
             '',
             '    function extractWikiLinks(content) {',
@@ -904,7 +1249,21 @@
             "      var text = String(content || '');",
             '      var match;',
             '      while ((match = regex.exec(text)) !== null) {',
-            '        var linked = stripMarkdownExtension(match[1]);',
+            '        var linked = String(match[1] || "").trim();',
+            '        if (linked) {',
+            '          links.add(linked);',
+            '        }',
+            '      }',
+            '      return Array.from(links);',
+            '    }',
+            '',
+            '    function extractMarkdownLinks(content) {',
+            '      var links = new Set();',
+            '      var regex = /\\]\\(([^)]+)\\)/g;',
+            "      var text = String(content || '');",
+            '      var match;',
+            '      while ((match = regex.exec(text)) !== null) {',
+            "        var linked = String(match[1] || '').trim();",
             '        if (linked) {',
             '          links.add(linked);',
             '        }',
@@ -914,6 +1273,7 @@
             '',
             '    var nodeMap = new Map();',
             '    var edgeMap = new Map();',
+            '    var referenceIndex = buildReferenceIndex(files);',
             '',
             '    function addEdge(source, target, type) {',
             '      if (!source || !target || source === target) {',
@@ -922,21 +1282,40 @@
             '      if (!nodeMap.has(source) || !nodeMap.has(target)) {',
             '        return;',
             '      }',
-            '      var key = source + "->" + target;',
+            '      var edgeType = type || "association";',
+            '      var key = source + "->" + target + ":" + edgeType;',
             '      if (edgeMap.has(key)) {',
             '        return;',
             '      }',
-            '      edgeMap.set(key, { source: source, target: target, type: type || "association", weight: 1 });',
+            '      var sourceNode = nodeMap.get(source);',
+            '      var targetNode = nodeMap.get(target);',
+            '      edgeMap.set(key, {',
+            '        source: source,',
+            '        target: target,',
+            '        type: edgeType,',
+            '        kind: "explicit",',
+            '        provenance: edgeType,',
+            '        sourceUri: sourceNode && sourceNode.sourceUri ? sourceNode.sourceUri : "",',
+            '        targetUri: targetNode && targetNode.sourceUri ? targetNode.sourceUri : "",',
+            '        weight: 1',
+            '      });',
             '    }',
             '',
             '    files.forEach(function(file) {',
-            '      if (!file || !file.id || nodeMap.has(file.id)) {',
+            '      if (!file || !file.id) {',
             '        return;',
             '      }',
+            '      if (nodeMap.has(file.id)) {',
+            '        throw new Error("Capacitor graph contains duplicate legacy node id: " + file.id);',
+            '      }',
             '      var metadata = file.metadata || {};',
             '      nodeMap.set(file.id, {',
             '        id: file.id,',
+            '        canonicalId: file.canonicalId || file.__canonicalId || "",',
             '        label: file.label || file.id,',
+            '        sourceUri: file.sourceUri || "",',
+            '        revision: file.revision || "",',
+            '        identityAliases: Array.isArray(file.identityAliases) ? file.identityAliases : [],',
             '        inDegree: 0,',
             '        outDegree: 0,',
             '        metadata: {',
@@ -959,18 +1338,24 @@
             '      var metadata = file.metadata || {};',
             '      var prerequisites = Array.isArray(metadata.prerequisites) ? metadata.prerequisites : [];',
             '      prerequisites.forEach(function(rawPrereq) {',
-            '        var prereqId = stripMarkdownExtension(rawPrereq);',
-            '        addEdge(prereqId, sourceId, "explicit-prerequisite");',
+            '        var prerequisiteFile = resolveReference(file, rawPrereq, referenceIndex);',
+            '        addEdge(prerequisiteFile && prerequisiteFile.id, sourceId, "explicit-prerequisite");',
             '      });',
             '',
             '      var nextItems = Array.isArray(metadata.next) ? metadata.next : [];',
             '      nextItems.forEach(function(rawNext) {',
-            '        var nextId = stripMarkdownExtension(rawNext);',
-            '        addEdge(sourceId, nextId, "explicit-next");',
+            '        var nextFile = resolveReference(file, rawNext, referenceIndex);',
+            '        addEdge(sourceId, nextFile && nextFile.id, "explicit-next");',
+            '      });',
+            '',
+            '      extractWikiLinks(file.content).forEach(function(rawLink) {',
+            '        var linkedFile = resolveReference(file, rawLink, referenceIndex);',
+            '        addEdge(sourceId, linkedFile && linkedFile.id, "wiki-link");',
             '      });',
             '',
-            '      extractWikiLinks(file.content).forEach(function(linkedId) {',
-            '        addEdge(linkedId, sourceId, "wiki-link");',
+            '      extractMarkdownLinks(file.content).forEach(function(rawLink) {',
+            '        var linkedFile = resolveReference(file, rawLink, referenceIndex);',
+            '        addEdge(sourceId, linkedFile && linkedFile.id, "markdown-link");',
             '      });',
             '    });',
             '',
@@ -1143,9 +1528,22 @@
     }
 
     async function buildCapacitorGraphDataWithWorkerFallback(files) {
+        const budget = getMobileRuntimeBudget();
+        const validateGraphBudget = (graphData) => {
+            if (!graphData || !Array.isArray(graphData.nodes) || !Array.isArray(graphData.edges)) {
+                throw new Error('Capacitor graph payload is invalid.');
+            }
+            if (graphData.nodes.length > budget.maxDocuments) {
+                throw new Error(`Capacitor graph node count exceeds ${budget.maxDocuments}.`);
+            }
+            if (graphData.edges.length > budget.maxEdges) {
+                throw new Error(`Capacitor graph edge count exceeds ${budget.maxEdges}.`);
+            }
+            return graphData;
+        };
         if (!supportsCapacitorGraphBuildWorker()) {
             return {
-                graphData: buildCapacitorGraphData(files),
+                graphData: validateGraphBudget(buildCapacitorGraphData(files)),
                 buildMode: 'single-thread'
             };
         }
@@ -1156,7 +1554,7 @@
                 throw new Error('Capacitor worker returned invalid graph payload.');
             }
             return {
-                graphData: workerGraph,
+                graphData: validateGraphBudget(workerGraph),
                 buildMode: 'worker'
             };
         } catch (workerErr) {
@@ -1166,7 +1564,7 @@
                 workerErr
             );
             return {
-                graphData: buildCapacitorGraphData(files),
+                graphData: validateGraphBudget(buildCapacitorGraphData(files)),
                 buildMode: 'single-thread-fallback',
                 warning
             };
@@ -1208,16 +1606,27 @@
 
         const files = await collectCapacitorMarkdownFiles(targetPath);
         const buildResult = await buildCapacitorGraphDataWithWorkerFallback(files);
-        const graphData = buildResult.graphData;
+        const projectionApi = window.NoteConnectionKnowledgeProjection;
+        if (!projectionApi || typeof projectionApi.createKnowledgeProjection !== 'function') {
+            throw new Error('Knowledge projection contract is unavailable in the mobile runtime.');
+        }
+        const graphData = projectionApi.createKnowledgeProjection(buildResult.graphData, {
+            workspaceId: 'mobile-workspace',
+        });
+        const projectionMaxBytes = getMobileRuntimeBudget().maxProjectionBytes;
+        const graphSerializationMaxBytes = Math.min(
+            CAPACITOR_GRAPH_SERIALIZATION_MAX_BYTES,
+            projectionMaxBytes
+        );
         const graphJsChunkFactory = createCapacitorGraphJavascriptChunkFactory(graphData);
         const graphJsonChunkFactory = createCapacitorGraphJsonChunkFactory(graphData);
 
         await capacitorWriteChunkSequence('data.js', graphJsChunkFactory, {
-            maxPayloadBytes: CAPACITOR_GRAPH_SERIALIZATION_MAX_BYTES,
+            maxPayloadBytes: graphSerializationMaxBytes,
             payloadLabel: 'data.js graph payload'
         });
         await capacitorWriteChunkSequence('graph_data.json', graphJsonChunkFactory, {
-            maxPayloadBytes: CAPACITOR_GRAPH_SERIALIZATION_MAX_BYTES,
+            maxPayloadBytes: graphSerializationMaxBytes,
             payloadLabel: 'graph_data.json graph payload'
         });
 
@@ -1225,11 +1634,11 @@
             const targetName = sanitizeTargetName(rawTarget);
             if (targetName) {
                 await capacitorWriteChunkSequence(`data_${targetName}.js`, graphJsChunkFactory, {
-                    maxPayloadBytes: CAPACITOR_GRAPH_SERIALIZATION_MAX_BYTES,
+                    maxPayloadBytes: graphSerializationMaxBytes,
                     payloadLabel: `data_${targetName}.js graph payload`
                 });
                 await capacitorWriteChunkSequence(`graph_data_${targetName}.json`, graphJsonChunkFactory, {
-                    maxPayloadBytes: CAPACITOR_GRAPH_SERIALIZATION_MAX_BYTES,
+                    maxPayloadBytes: graphSerializationMaxBytes,
                     payloadLabel: `graph_data_${targetName}.json graph payload`
                 });
             }
@@ -1295,6 +1704,23 @@
         return new Error(`Storage provider operation is unsupported in this runtime: ${operation}`);
     }
 
+    function normalizeStorageProviderKind(value) {
+        const normalized = String(value || '').trim().toLowerCase();
+        if (normalized === 'sqlite' || normalized === 'embedded' || normalized === 'embedded-sqlite' || normalized === 'embedded_sqlite') {
+            return 'sqlite';
+        }
+        if (normalized === 'file' || normalized === 'local-file' || normalized === 'snapshot') {
+            return 'file';
+        }
+        if (normalized === 'projection' || normalized === 'mobile_projection' || normalized === 'mobile-slim') {
+            return 'projection';
+        }
+        if (normalized === 'remote' || normalized === 'http' || normalized === 'external_http' || normalized === 'remote-http' || normalized === 'service') {
+            return 'remote';
+        }
+        return null;
+    }
+
     function formatCapacitorMtime(statObject) {
         if (!statObject || typeof statObject !== 'object') {
             return '';
@@ -1320,6 +1746,65 @@
     class RuntimeStorageProvider {
         constructor(runtimeCaps) {
             this.runtimeCaps = runtimeCaps || {};
+            this.mobileExactIndexPromise = null;
+        }
+
+        getStorageResolution() {
+            const runtimePlatform = String(this.runtimeCaps.platform || '').trim().toLowerCase();
+            const mobileRuntime = isCapacitorNativeRuntime()
+                || runtimePlatform.includes('android')
+                || runtimePlatform.includes('ios')
+                || runtimePlatform === 'mobile';
+            const requestedProvider = normalizeStorageProviderKind(
+                this.runtimeCaps.storage_requested_provider
+            ) || (mobileRuntime ? 'projection' : 'sqlite');
+            const reportedProvider = normalizeStorageProviderKind(this.runtimeCaps.storage_resolved_provider);
+            const resolvedProvider = mobileRuntime
+                ? 'projection'
+                : reportedProvider || undefined;
+            const fallbackReason = String(
+                this.runtimeCaps.storage_fallback_reason
+                || (mobileRuntime && requestedProvider === 'sqlite' ? 'native_sqlite_runtime_unavailable' : '')
+            ).trim();
+            return Object.freeze({
+                requestedProvider,
+                resolvedProvider,
+                fallbackReason: fallbackReason || undefined,
+                supportsSqlite: !mobileRuntime && resolvedProvider === 'sqlite',
+                supportsProjection: this.runtimeCaps.supports_projection_store !== false
+                    && resolvedProvider === 'projection',
+            });
+        }
+
+        async refreshStorageResolution() {
+            const current = this.getStorageResolution();
+            if (isCapacitorNativeRuntime() || !this._supportsSidecar()) {
+                return current;
+            }
+            try {
+                const payload = await sidecarFetchJson('api/knowledge/store-diagnostics');
+                const store = payload && payload.store && typeof payload.store === 'object'
+                    ? payload.store
+                    : null;
+                const resolvedProvider = normalizeStorageProviderKind(
+                    store && (store.resolvedProvider || store.storageEngine || store.provider)
+                );
+                if (resolvedProvider) {
+                    this.runtimeCaps = {
+                        ...this.runtimeCaps,
+                        storage_requested_provider: normalizeStorageProviderKind(
+                            store.requestedProvider
+                        ) || current.requestedProvider,
+                        storage_resolved_provider: resolvedProvider,
+                        storage_fallback_reason: String(store.fallbackReason || '').trim(),
+                        supports_sqlite: resolvedProvider === 'sqlite',
+                    };
+                }
+            } catch (_error) {
+                // Capability probing is advisory; the normal storage operation
+                // still owns the authoritative failure/fallback behavior.
+            }
+            return this.getStorageResolution();
         }
 
         _supportsSidecar() {
@@ -1558,6 +2043,95 @@
             throw unsupportedOperationError('buildGraph');
         }
 
+        async _loadMobileExactIndex() {
+            if (this.mobileExactIndexPromise) {
+                return await this.mobileExactIndexPromise;
+            }
+
+            this.mobileExactIndexPromise = (async () => {
+                const analyzer = window.NoteConnectionMobileExactAnalyzer;
+                if (!analyzer || typeof analyzer.createMobileExactIndex !== 'function') {
+                    throw unsupportedOperationError('mobileExactAnalysis');
+                }
+                const storeApi = window.NoteConnectionKnowledgeProjectionStore;
+                if (!storeApi || typeof storeApi.createProjectionStore !== 'function') {
+                    throw unsupportedOperationError('projectionStore');
+                }
+                const projectionStore = typeof storeApi.createFileProjectionStore === 'function'
+                    ? storeApi.createFileProjectionStore({
+                        fileName: 'graph_data.json',
+                        maxBytes: getMobileRuntimeBudget().maxProjectionBytes,
+                        readFile: async (filename) => await this.readGeneratedAsset(filename),
+                    })
+                    : storeApi.createProjectionStore({
+                        maxBytes: getMobileRuntimeBudget().maxProjectionBytes,
+                        read: async () => await this.readGeneratedAsset('graph_data.json'),
+                    });
+                const graph = await projectionStore.load();
+                return analyzer.createMobileExactIndex(graph);
+            })();
+
+            try {
+                return await this.mobileExactIndexPromise;
+            } catch (error) {
+                this.mobileExactIndexPromise = null;
+                throw error;
+            }
+        }
+
+        async queryKnowledgeBaseExact(request) {
+            const payload = request && typeof request === 'object' ? request : {};
+            const query = typeof payload.query === 'string' ? payload.query.trim() : '';
+            if (!query) {
+                throw new Error('Local exact query requires a non-empty query.');
+            }
+            const index = await this._loadMobileExactIndex();
+            const matches = index.searchExact(query, payload.maxMatches);
+            return {
+                query,
+                matches: matches.map((node) => ({
+                    ...node,
+                    neighbors: index.neighbors(
+                        node.id,
+                        payload.maxNeighborsPerMatch,
+                        payload.edgeKinds
+                    ),
+                    learningRoute: typeof index.learningRoute === 'function'
+                        ? index.learningRoute(node.id, 6)
+                        : []
+                })),
+                statistics: index.statistics({ includeProvenance: true }),
+                execution: 'local-exact',
+                remoteInferenceUsed: false
+            };
+        }
+
+        async findKnowledgePath(request) {
+            const payload = request && typeof request === 'object' ? request : {};
+            const sourceNodeId = typeof payload.sourceNodeId === 'string'
+                ? payload.sourceNodeId.trim()
+                : '';
+            const targetNodeId = typeof payload.targetNodeId === 'string'
+                ? payload.targetNodeId.trim()
+                : '';
+            if (!sourceNodeId || !targetNodeId) {
+                throw new Error('Local knowledge path requires sourceNodeId and targetNodeId.');
+            }
+            const index = await this._loadMobileExactIndex();
+            return {
+                sourceNodeId,
+                targetNodeId,
+                path: index.shortestPath(
+                    sourceNodeId,
+                    targetNodeId,
+                    payload.maxDepth,
+                    payload.maxVisitedNodes
+                ),
+                execution: 'local-exact',
+                remoteInferenceUsed: false
+            };
+        }
+
         async readContent(filePath) {
             if (!this._supportsContentApi()) {
                 throw unsupportedOperationError('readContent');
@@ -1565,7 +2139,9 @@
 
             if (isCapacitorNativeRuntime()) {
                 const capacitorPath = resolveCapacitorContentCandidatePath(filePath);
-                return await capacitorReadText(capacitorPath);
+                return await capacitorReadText(capacitorPath, {
+                    maxBytes: getMobileRuntimeBudget().maxDocumentBytes
+                });
             }
 
             if (this._supportsSidecar()) {
@@ -1630,7 +2206,9 @@
                 try {
                     // Prefer local runtime-generated assets first so on-device builds
                     // are picked up without requiring an app rebundle.
-                    return await capacitorReadText(normalized);
+                    return await capacitorReadText(normalized, {
+                        maxBytes: getMobileRuntimeBudget().maxProjectionBytes
+                    });
                 } catch (_fsErr) {
                     // Fall through to bundled asset fetch.
                 }
@@ -1658,6 +2236,18 @@
     }
 
     window.NoteConnectionStorage = {
-        createProvider
+        createProvider,
+        measureUtf8Bytes
     };
+
+    if (typeof module === 'object' && module.exports) {
+        module.exports = {
+            createProvider,
+            buildCapacitorGraphData,
+            getCapacitorGraphBuildWorkerSource,
+            createMobileResourceIdentity,
+            getMobileRuntimeBudget,
+            measureUtf8Bytes,
+        };
+    }
 }());