noteconnection 1.8.0 → 1.9.1

package/dist/src/backend/GraphBuilder.identity.test.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const GraphBuilder_1 = require("./GraphBuilder");
+const config_1 = require("./config");
+describe('GraphBuilder identity compatibility', () => {
+    const originalConfig = {
+        ...config_1.config,
+        exclusionList: [...config_1.config.exclusionList],
+    };
+    beforeEach(() => {
+        config_1.config.enableTags = false;
+        config_1.config.enableStatisticalInference = false;
+        config_1.config.enableVectorSimilarity = false;
+        config_1.config.enableHybridInference = false;
+        config_1.config.enableGPU = false;
+        config_1.config.enableGPULayout = false;
+        config_1.config.clusteringStrategy = 'folder';
+        config_1.config.exclusionList = [];
+    });
+    afterEach(() => {
+        Object.assign(config_1.config, originalConfig);
+    });
+    test('preserves identity metadata, reads URI frontmatter, and accepts URI layouts', async () => {
+        const files = [
+            {
+                filepath: 'workspace/algebra/a.md',
+                filename: 'A',
+                content: '# A',
+                relativePath: 'algebra/a.md',
+                sourceUri: 'note://workspace/v1/algebra/a.md',
+                canonicalId: 'algebra/a',
+                revision: 'sha256:a',
+                identityAliases: ['A', 'algebra/a.md'],
+            },
+            {
+                filepath: 'workspace/algebra/b.md',
+                filename: 'B',
+                content: '---\nprerequisites:\n  - note://workspace/v1/algebra/a.md\n---\n# B',
+                relativePath: 'algebra/b.md',
+                sourceUri: 'note://workspace/v1/algebra/b.md',
+                revision: 'sha256:b',
+                identityAliases: ['B', 'algebra/b.md'],
+            },
+        ];
+        const graph = await GraphBuilder_1.GraphBuilder.build(files, new Map([
+            ['note://workspace/v1/algebra/a.md', { x: 12, y: 34 }],
+        ]));
+        expect(graph.getNode('A')).toEqual(expect.objectContaining({
+            sourceUri: 'note://workspace/v1/algebra/a.md',
+            canonicalId: 'algebra/a',
+            revision: 'sha256:a',
+            identityAliases: expect.arrayContaining(['algebra/a.md']),
+            x: 12,
+            y: 34,
+        }));
+        expect(graph.getIncomingEdges('B')).toEqual(expect.arrayContaining([
+            expect.objectContaining({ source: 'A', target: 'B', type: 'explicit-prerequisite' }),
+        ]));
+    });
+    test('uses indexed keyword candidates without changing exact-match semantics', async () => {
+        const files = [
+            {
+                filepath: 'workspace/alpha.md',
+                filename: 'Alpha',
+                content: 'Alpha is a prerequisite concept.',
+            },
+            {
+                filepath: 'workspace/context.md',
+                filename: 'Context',
+                content: 'This context mentions Alpha as an explicit phrase.',
+            },
+            {
+                filepath: 'workspace/beta.md',
+                filename: 'Beta',
+                content: 'This context mentions alphabet but not the standalone concept.',
+            },
+        ];
+        const graph = await GraphBuilder_1.GraphBuilder.build(files);
+        expect(graph.getOutgoingEdges('Alpha')).toEqual(expect.arrayContaining([
+            expect.objectContaining({ target: 'Context', type: 'keyword-match' }),
+        ]));
+        expect(graph.getOutgoingEdges('Alpha')).not.toEqual(expect.arrayContaining([
+            expect.objectContaining({ target: 'Beta', type: 'keyword-match' }),
+        ]));
+    });
+});

package/dist/src/backend/GraphBuilder.js

@@ -52,11 +52,34 @@ const HybridEngine_1 = require("./algorithms/HybridEngine");
 const PerformanceLogger_1 = require("./utils/PerformanceLogger");
 const LayoutEngine_1 = require("./algorithms/LayoutEngine");
 const WorkerRuntime_1 = require("./utils/WorkerRuntime");
+const ResourceIdentity_1 = require("./ResourceIdentity");
 /**
  * Service to build the graph from raw files.
  * 从原始文件构建图的服务。
  */
 class GraphBuilder {
+    static findLayoutPosition(file, layout) {
+        if (!layout)
+            return undefined;
+        const references = [
+            file.sourceUri,
+            file.relativePath,
+            ...(file.identityAliases ?? []),
+            file.filename,
+        ].filter((reference) => Boolean(reference));
+        for (const reference of references) {
+            const exactPosition = layout.get(reference);
+            if (exactPosition)
+                return exactPosition;
+        }
+        const normalizedReferences = new Set(references.map(ResourceIdentity_1.normalizeResourceReference));
+        for (const [reference, position] of layout.entries()) {
+            if (normalizedReferences.has((0, ResourceIdentity_1.normalizeResourceReference)(reference))) {
+                return position;
+            }
+        }
+        return undefined;
+    }
     /**
      * Builds a graph from raw files using keyword matching.
      * 使用关键词匹配从原始文件构建图。
@@ -65,13 +88,13 @@ class GraphBuilder {
      */
     static async build(files, layout) {
         PerformanceLogger_1.PerformanceLogger.logSystemInfo();
+        (0, ResourceIdentity_1.assertUniqueLegacyResourceIds)(files);
         const graph = new Graph_1.Graph();
         // 1. Add all nodes first
         PerformanceLogger_1.PerformanceLogger.start('Node Initialization');
         // 1. 首先添加所有节点
         const fileMap = new Map();
         files.forEach(file => {
-            // Parse Metadata (Tags, Prerequisites, Next)
             const metadata = frontmatterParser_1.FrontmatterParser.parse(file.content);
             const node = {
                 id: file.filename,
@@ -79,21 +102,28 @@ class GraphBuilder {
                 inDegree: 0,
                 outDegree: 0,
                 content: file.content,
+                sourceUri: file.sourceUri,
+                canonicalId: file.canonicalId,
+                revision: file.revision,
+                identityAliases: file.identityAliases,
                 metadata: {
                     filepath: file.filepath,
+                    relativePath: file.relativePath,
+                    sourceUri: file.sourceUri,
+                    revision: file.revision,
                     tags: metadata.tags,
                     prerequisites: metadata.prerequisites,
                     next: metadata.next
                 }
             };
-            if (layout && layout.has(file.filename)) {
-                const pos = layout.get(file.filename);
+            const savedPosition = this.findLayoutPosition(file, layout);
+            if (savedPosition) {
+                const pos = savedPosition;
                 node.x = pos.x;
                 node.y = pos.y;
             }
             graph.addNode(node);
             fileMap.set(file.filename, file);
-            // 1b. Add Tag Nodes
             if (config_1.config.enableTags) {
                 metadata.tags.forEach(tag => {
                     const tagId = `#${tag}`;
@@ -105,7 +135,6 @@ class GraphBuilder {
                             clusterId: 'tags' // Group tags together
                         });
                     }
-                    // Edge: Note -> Tag
                     graph.addEdge(node.id, tagId, 'tagged');
                 });
             }
@@ -209,7 +238,6 @@ class GraphBuilder {
                     const similar = sharedVectorSpace.getSimilar(file.filename, 3); // Top 3 similar
                     similar.forEach(sim => {
                         if (sim.score > 0.3) { // Threshold
-                            // Add UNDIRECTED association
                             graph.addEdge(file.filename, sim.id, 'vector-association', sim.score);
                             similarityEdges++;
                         }
@@ -369,6 +397,7 @@ class GraphBuilder {
         const chunkSize = Math.ceil(files.length / workerCount);
         const targetIds = files.map(f => f.filename);
         const workerPromises = [];
+        const matchingWorkers = [];
         const workerRuntime = (0, WorkerRuntime_1.resolveWorkerRuntimePath)(__dirname, 'workers/keywordMatchWorker.ts');
         const actualWorkerPath = workerRuntime.workerPath;
         const isTsNode = workerRuntime.isTsNode;
@@ -409,6 +438,7 @@ class GraphBuilder {
                         workerData: workerPayload,
                         execArgv
                     });
+                    matchingWorkers.push(worker);
                     worker.on('message', (results) => {
                         results.forEach(res => {
                             graph.addEdge(res.target, res.source, 'keyword-match');
@@ -441,24 +471,42 @@ class GraphBuilder {
         }
         catch (err) {
             console.error('[GraphBuilder] Parallel matching failed, falling back to sequential.', err);
-            // Fallback
+            // No worker may append edges while downstream graph analysis sees the fallback.
+            await Promise.allSettled(matchingWorkers.map(worker => worker.terminate()));
+            await Promise.allSettled(workerPromises);
             this.runSequentialMatching(files, graph);
         }
     }
     static runSequentialMatching(files, graph) {
-        files.forEach(sourceFile => {
-            const sourceId = sourceFile.filename;
-            const content = sourceFile.content;
-            files.forEach(targetFile => {
-                const targetId = targetFile.filename;
-                if (sourceId === targetId)
-                    return; // Skip self | 跳过自身
-                // Exclusion Check
-                if (config_1.config.exclusionList.includes(targetId)) {
+        // Exact-phrase matching uses JavaScript's ASCII word boundaries. Index
+        // those same word runs so mixed CJK/ASCII text cannot hide a valid match.
+        // Substring matching requires a full candidate set; token equality is not
+        // a conservative prefilter for fuzzy matches inside a longer word.
+        const candidatesByAnchor = new Map();
+        files.forEach((sourceFile) => {
+            const tokens = sourceFile.content.toLowerCase().match(/[A-Za-z0-9_]+/g) || [];
+            const seenTokens = new Set(tokens);
+            seenTokens.forEach((token) => {
+                const candidates = candidatesByAnchor.get(token) || [];
+                candidates.push(sourceFile);
+                candidatesByAnchor.set(token, candidates);
+            });
+        });
+        files.forEach((targetFile) => {
+            const targetId = targetFile.filename;
+            if (config_1.config.exclusionList.includes(targetId)) {
+                return;
+            }
+            const anchor = targetId.toLowerCase().match(/[A-Za-z0-9_]+/)?.[0] || '';
+            const candidateSources = config_1.config.matchingStrategy === 'exact-phrase' && anchor
+                ? (candidatesByAnchor.get(anchor) || [])
+                : files;
+            candidateSources.forEach((sourceFile) => {
+                const sourceId = sourceFile.filename;
+                if (sourceId === targetId) {
                     return;
                 }
-                if ((0, stringUtils_1.checkMatch)(content, targetId, config_1.config.matchingStrategy)) {
-                    // Found a reference!
+                if ((0, stringUtils_1.checkMatch)(sourceFile.content, targetId, config_1.config.matchingStrategy)) {
                     // Target (Concept) -> Source (Context)
                     graph.addEdge(targetId, sourceId, 'keyword-match');
                 }

package/dist/src/backend/GraphBuilder.matching.test.js

@@ -0,0 +1,127 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const GraphBuilder_1 = require("./GraphBuilder");
+const config_1 = require("./config");
+const stringUtils_1 = require("./utils/stringUtils");
+const worker_threads_1 = __importDefault(require("worker_threads"));
+const events_1 = require("events");
+describe('graph keyword matching equivalence', () => {
+    const original = { ...config_1.config, exclusionList: [...config_1.config.exclusionList] };
+    let root;
+    beforeEach(() => {
+        root = fs.mkdtempSync(path.join(os.tmpdir(), 'graph-matching-'));
+        Object.assign(config_1.config, {
+            enableTags: false, enableStatisticalInference: false, enableVectorSimilarity: false,
+            enableHybridInference: false, enableGPU: false, enableGPULayout: false,
+            clusteringStrategy: 'folder', exclusionList: ['ignored'], maxWorkers: 1,
+        });
+        jest.spyOn(console, 'log').mockImplementation(() => undefined);
+    });
+    afterEach(() => {
+        Object.assign(config_1.config, original);
+        jest.restoreAllMocks();
+        fs.rmSync(root, { recursive: true, force: true });
+    });
+    function corpus() {
+        const records = [
+            ['cat', ''], ['知识', ''], ['Alpha', ''], ['++', ''], ['café', ''],
+            ['ignored', ''], ['self', 'self'],
+            ['english-context', 'concatenate'], ['chinese-context', '知识图谱'],
+            ['mixed-context', 'Alpha知识'], ['punctuation-context', 'a++b'],
+            ['unicode-context', 'précaféiné'], ['excluded-context', 'ignored'],
+        ];
+        return records.map(([filename, content]) => {
+            const filepath = path.join(root, filename + '.md');
+            fs.writeFileSync(filepath, content);
+            return { filename, filepath, content };
+        });
+    }
+    function expectedEdges(files) {
+        return files.flatMap(source => files
+            .filter(target => source.filename !== target.filename
+            && !config_1.config.exclusionList.includes(target.filename)
+            && (0, stringUtils_1.checkMatch)(source.content, target.filename, config_1.config.matchingStrategy))
+            .map(target => target.filename + '->' + source.filename)).sort();
+    }
+    test.each(['exact-phrase', 'fuzzy'])('sequential matching preserves %s semantics', async (strategy) => {
+        config_1.config.matchingStrategy = strategy;
+        const files = corpus();
+        const graph = await GraphBuilder_1.GraphBuilder.build(files);
+        expect(graph.getEdges().filter(edge => edge.type === 'keyword-match')
+            .map(edge => edge.source + '->' + edge.target).sort()).toEqual(expectedEdges(files));
+    });
+    test.each([['exact-phrase', true], ['exact-phrase', false], ['fuzzy', true], ['fuzzy', false]])('worker matching preserves %s semantics with memorySavingMode=%s', async (strategy, memorySavingMode) => {
+        config_1.config.matchingStrategy = strategy;
+        config_1.config.memorySavingMode = memorySavingMode;
+        const files = corpus();
+        for (let index = 0; files.length <= 200; index++) {
+            const filename = 'unused-' + index;
+            const filepath = path.join(root, filename + '.md');
+            fs.writeFileSync(filepath, '');
+            files.push({ filename, filepath, content: '' });
+        }
+        const graph = await GraphBuilder_1.GraphBuilder.build(files);
+        expect(graph.getEdges().filter(edge => edge.type === 'keyword-match')
+            .map(edge => edge.source + '->' + edge.target).sort()).toEqual(expectedEdges(files));
+    }, 30000);
+    test('quiesces all workers before publishing sequential fallback after a worker failure', async () => {
+        config_1.config.matchingStrategy = 'fuzzy';
+        config_1.config.maxWorkers = 2;
+        const files = corpus();
+        for (let index = 0; files.length <= 200; index++)
+            files.push({ filename: 'padding-' + index, filepath: path.join(root, 'padding-' + index + '.md'), content: '' });
+        const children = [];
+        jest.spyOn(console, 'error').mockImplementation(() => undefined);
+        jest.spyOn(worker_threads_1.default, 'Worker').mockImplementation(() => {
+            const child = Object.assign(new events_1.EventEmitter(), { terminate: jest.fn(async () => { child.emit('exit', 0); return 0; }) });
+            children.push(child);
+            if (children.length === 1)
+                setImmediate(() => child.emit('error', new Error('injected worker failure')));
+            return child;
+        });
+        const graph = await GraphBuilder_1.GraphBuilder.build(files);
+        expect(graph.getEdges().filter(edge => edge.type === 'keyword-match').map(edge => edge.source + '->' + edge.target).sort()).toEqual(expectedEdges(files));
+        expect(children).toHaveLength(2);
+        for (const child of children)
+            expect(child.terminate).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/src/backend/GraphMetrics.js

@@ -235,8 +235,6 @@ class GraphMetrics {
         }
         try {
             const results = await Promise.all(workerPromises);
-            // Merge results
-            // 合并结果
             const totalCB = new Map();
             nodes.forEach(n => totalCB.set(n.id, 0));
             results.forEach(partial => {
@@ -261,7 +259,6 @@ class GraphMetrics {
     static calculateBetweenness(graph) {
         const nodes = graph.toJSON().nodes;
         const cb = new Map();
-        // Initialize
         nodes.forEach(n => cb.set(n.id, 0));
         // For each node s, calculate dependencies
         nodes.forEach(sNode => {

package/dist/src/backend/ResourceIdentity.js

@@ -0,0 +1,155 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeResourceReference = void 0;
+exports.normalizePortableResourcePath = normalizePortableResourcePath;
+exports.createResourceIdentity = createResourceIdentity;
+exports.normalizeResourceRelativePath = normalizeResourceRelativePath;
+exports.assertUniqueLegacyResourceIds = assertUniqueLegacyResourceIds;
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const ResourceReference_1 = require("../core/ResourceReference");
+var ResourceReference_2 = require("../core/ResourceReference");
+Object.defineProperty(exports, "normalizeResourceReference", { enumerable: true, get: function () { return ResourceReference_2.normalizeResourceReference; } });
+const SOURCE_URI_PREFIX = 'note://workspace/v1/';
+function normalizeUnicodeText(value, fieldName) {
+    if (typeof value !== 'string') {
+        throw new Error(`${fieldName} must be a string`);
+    }
+    if (value.includes('\0')) {
+        throw new Error(`${fieldName} must not contain NUL characters`);
+    }
+    return value.normalize('NFC');
+}
+/**
+ * Produces the case-folded path key used by portable aliases and source URIs.
+ * The lower-case policy is deliberate: a workspace must not change identity when
+ * moved between Windows and a case-sensitive POSIX host.
+ */
+function normalizePortableResourcePath(relativePath) {
+    const normalized = normalizeUnicodeText(relativePath, 'Relative resource path')
+        .replace(/\\/g, '/');
+    if (!normalized
+        || normalized.startsWith('/')
+        || /^[A-Za-z]:\//.test(normalized)) {
+        throw new Error(`Relative resource path must stay inside the workspace: ${relativePath}`);
+    }
+    const segments = normalized.split('/');
+    if (segments.some(segment => !segment || segment === '..')) {
+        throw new Error(`Relative resource path contains an unsafe segment: ${relativePath}`);
+    }
+    return segments
+        .filter(segment => segment !== '.')
+        .map(segment => segment.toLowerCase())
+        .join('/');
+}
+function createSourceUri(canonicalRelativePath) {
+    const encodedSegments = canonicalRelativePath
+        .split('/')
+        .map(segment => encodeURIComponent(segment));
+    return `${SOURCE_URI_PREFIX}${encodedSegments.join('/')}`;
+}
+function createCanonicalId(canonicalRelativePath) {
+    return canonicalRelativePath.replace(/\.(?:md|markdown)$/i, '');
+}
+function createContentRevision(content) {
+    const normalizedContent = normalizeUnicodeText(content, 'Resource content');
+    return `sha256:${(0, crypto_1.createHash)('sha256').update(normalizedContent, 'utf8').digest('hex')}`;
+}
+/**
+ * Builds additive identity metadata for a loaded Markdown resource.
+ * `relativePath` keeps its display spelling in aliases while the source URI is
+ * canonicalized for cross-platform persistence.
+ */
+function createResourceIdentity(relativePath, legacyId, content) {
+    const displayRelativePath = normalizeUnicodeText(relativePath, 'Relative resource path')
+        .replace(/\\/g, '/');
+    const canonicalRelativePath = normalizePortableResourcePath(displayRelativePath);
+    const normalizedLegacyId = normalizeUnicodeText(legacyId, 'Legacy resource ID');
+    if (!normalizedLegacyId.trim()) {
+        throw new Error('Legacy resource ID must not be empty');
+    }
+    const identityAliases = Array.from(new Set([
+        normalizedLegacyId,
+        normalizedLegacyId.toLowerCase().endsWith('.md') ? normalizedLegacyId : `${normalizedLegacyId}.md`,
+        displayRelativePath,
+        canonicalRelativePath,
+    ]));
+    return {
+        sourceUri: createSourceUri(canonicalRelativePath),
+        canonicalId: createCanonicalId(canonicalRelativePath),
+        revision: createContentRevision(content),
+        identityAliases,
+    };
+}
+/**
+ * Returns the stable, workspace-relative spelling used by persistence and diagnostics.
+ * The legacy basename remains a compatibility alias; this value is the migration input
+ * for a future stable source URI.
+ */
+function normalizeResourceRelativePath(rootPath, filePath) {
+    normalizeUnicodeText(rootPath, 'Workspace root');
+    normalizeUnicodeText(filePath, 'Resource path');
+    const resolvedRoot = path.resolve(rootPath);
+    const resolvedFile = path.resolve(filePath);
+    const relativePath = path.relative(resolvedRoot, resolvedFile);
+    const parentPrefix = `..${path.sep}`;
+    if (!relativePath
+        || relativePath === '..'
+        || relativePath.startsWith(parentPrefix)
+        || path.isAbsolute(relativePath)) {
+        throw new Error(`Resource path is outside workspace root: ${filePath}`);
+    }
+    return relativePath.split(path.sep).join('/').normalize('NFC');
+}
+/**
+ * Prevents the current basename-based graph identity from silently dropping files.
+ * This guard is intentionally fail-fast until stable source IDs and aliases are migrated.
+ */
+function assertUniqueLegacyResourceIds(files) {
+    const pathsById = new Map();
+    files.forEach((file) => {
+        const identityKey = (0, ResourceReference_1.normalizeResourceReference)(file.filename);
+        const paths = pathsById.get(identityKey) ?? [];
+        paths.push(file.filepath);
+        pathsById.set(identityKey, paths);
+    });
+    const collisions = Array.from(pathsById.entries())
+        .filter(([, paths]) => paths.length > 1)
+        .map(([id, paths]) => `${id}: ${paths.join(', ')}`);
+    if (collisions.length > 0) {
+        throw new Error(`Ambiguous legacy resource identity detected; duplicate basenames must be resolved before graph construction: ${collisions.join('; ')}`);
+    }
+}

package/dist/src/backend/ResourceIdentity.test.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("path"));
+const ResourceIdentity_1 = require("./ResourceIdentity");
+describe('Resource identity boundary', () => {
+    test('normalizes workspace-relative paths to POSIX separators', () => {
+        const root = path.resolve('workspace', 'Knowledge_Base');
+        const filePath = path.join(root, 'algebra', 'index.md');
+        expect((0, ResourceIdentity_1.normalizeResourceRelativePath)(root, filePath)).toBe('algebra/index.md');
+    });
+    test('rejects a path outside the workspace root', () => {
+        const root = path.resolve('workspace', 'Knowledge_Base');
+        expect(() => (0, ResourceIdentity_1.normalizeResourceRelativePath)(root, path.resolve(root, '..', 'other.md')))
+            .toThrow(/outside workspace root/i);
+    });
+    test('fails before graph construction when legacy basenames collide', () => {
+        expect(() => (0, ResourceIdentity_1.assertUniqueLegacyResourceIds)([
+            { filename: 'index', filepath: 'algebra/index.md' },
+            { filename: 'index', filepath: 'physics/index.md' },
+        ])).toThrow(/index.*algebra\/index\.md.*physics\/index\.md/i);
+    });
+    test('accepts unique legacy IDs', () => {
+        expect(() => (0, ResourceIdentity_1.assertUniqueLegacyResourceIds)([
+            { filename: 'algebra-index', filepath: 'algebra/index.md' },
+            { filename: 'physics-index', filepath: 'physics/index.md' },
+        ])).not.toThrow();
+    });
+    test('builds a versioned portable source URI and stable content revision', () => {
+        const identity = (0, ResourceIdentity_1.createResourceIdentity)('Algebra Notes\\Index #1.MD', 'Index #1', '# Algebra');
+        expect(identity.sourceUri).toBe('note://workspace/v1/algebra%20notes/index%20%231.md');
+        expect(identity.canonicalId).toBe('algebra notes/index #1');
+        expect(identity.revision).toMatch(/^sha256:[0-9a-f]{64}$/);
+        expect(identity.identityAliases).toEqual(expect.arrayContaining([
+            'Index #1',
+            'Algebra Notes/Index #1.MD',
+            'algebra notes/index #1.md',
+        ]));
+    });
+    test('keeps the revision stable for equal content and changes it for different content', () => {
+        const first = (0, ResourceIdentity_1.createResourceIdentity)('notes/a.md', 'a', 'same');
+        const same = (0, ResourceIdentity_1.createResourceIdentity)('notes/a.md', 'a', 'same');
+        const changed = (0, ResourceIdentity_1.createResourceIdentity)('notes/a.md', 'a', 'changed');
+        expect(same.revision).toBe(first.revision);
+        expect(changed.revision).not.toBe(first.revision);
+    });
+    test('rejects unsafe relative source paths', () => {
+        expect(() => (0, ResourceIdentity_1.createResourceIdentity)('../outside.md', 'outside', 'content'))
+            .toThrow(/relative resource path/i);
+        expect(() => (0, ResourceIdentity_1.createResourceIdentity)('notes/\0.md', 'nul', 'content'))
+            .toThrow(/NUL/i);
+    });
+    test('rejects case-folded legacy collisions for cross-platform determinism', () => {
+        expect(() => (0, ResourceIdentity_1.assertUniqueLegacyResourceIds)([
+            { filename: 'Index', filepath: 'Algebra/Index.md' },
+            { filename: 'index', filepath: 'Physics/index.md' },
+        ])).toThrow(/case-insensitive|ambiguous/i);
+    });
+    test('keeps same-content documents distinct by source URI while sharing the revision', () => {
+        const first = (0, ResourceIdentity_1.createResourceIdentity)('notes/first.md', 'First', 'same body');
+        const second = (0, ResourceIdentity_1.createResourceIdentity)('notes/second.md', 'Second', 'same body');
+        expect(first.revision).toBe(second.revision);
+        expect(first.sourceUri).not.toBe(second.sourceUri);
+        expect(first.identityAliases).toEqual(expect.arrayContaining(['First', 'notes/first.md']));
+        expect(second.identityAliases).toEqual(expect.arrayContaining(['Second', 'notes/second.md']));
+    });
+    test('treats move and rename as an additive alias transition before any canonical cutover', () => {
+        const before = (0, ResourceIdentity_1.createResourceIdentity)('algebra/intro.md', 'Intro', 'body');
+        const after = (0, ResourceIdentity_1.createResourceIdentity)('foundations/start.md', 'Intro', 'body');
+        expect(after.revision).toBe(before.revision);
+        expect(after.sourceUri).not.toBe(before.sourceUri);
+        expect(before.identityAliases).toContain('algebra/intro.md');
+        expect(after.identityAliases).toContain('foundations/start.md');
+    });
+    test('rejects Unicode-normalized collisions before graph mutation', () => {
+        expect(() => (0, ResourceIdentity_1.assertUniqueLegacyResourceIds)([
+            { filename: 'Cafe\u0301', filepath: 'one/Cafe\u0301.md' },
+            { filename: 'Caf\u00e9', filepath: 'two/Caf\u00e9.md' },
+        ])).toThrow(/ambiguous|duplicate/i);
+    });
+});