noteconnection 1.7.0 → 1.9.0

package/dist/src/frontend/knowledge_projection_contract.js

@@ -0,0 +1,230 @@
+(function attachKnowledgeProjectionContract(root, factory) {
+    const api = factory();
+    if (typeof module === 'object' && module.exports) {
+        module.exports = api;
+    }
+    if (root) {
+        root.NoteConnectionKnowledgeProjection = api;
+    }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function createKnowledgeProjectionContract() {
+    'use strict';
+
+    const SCHEMA_VERSION = 1;
+    const MAX_NODES = 50000;
+    const MAX_EDGES = 250000;
+    const MAX_NEIGHBORS = 64;
+    const MAX_EVIDENCE_REFS = 8;
+
+    function isRecord(value) {
+        return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+    }
+
+    function cleanString(value) {
+        return typeof value === 'string' ? value.trim() : '';
+    }
+
+    function cleanStringList(value, fieldName, limit) {
+        if (value === undefined || value === null) {
+            return [];
+        }
+        if (!Array.isArray(value)) {
+            throw new Error(`${fieldName} must be an array when provided.`);
+        }
+        const values = Array.from(new Set(value.map(cleanString).filter(Boolean)));
+        if (values.length > limit) {
+            throw new Error(`${fieldName} exceeds the bounded limit of ${limit}.`);
+        }
+        return values;
+    }
+
+    function classifyEdgeKind(rawType, rawKind) {
+        const kind = cleanString(rawKind).toLowerCase();
+        if (kind === 'explicit' || kind === 'inferred' || kind === 'runtime') {
+            return kind;
+        }
+        const type = cleanString(rawType).toLowerCase();
+        if (type.includes('inferred') || type.includes('keyword') || type.includes('vector') || type.includes('statistical')) {
+            return 'inferred';
+        }
+        if (type === 'runtime' || type.includes('runtime')) {
+            return 'runtime';
+        }
+        return 'explicit';
+    }
+
+    function assertSupportedVersion(value) {
+        const version = value === undefined || value === null ? SCHEMA_VERSION : Number(value);
+        if (!Number.isInteger(version) || version < 1 || version > SCHEMA_VERSION) {
+            throw new Error(`Unsupported knowledge projection schema version: ${String(value)}.`);
+        }
+        return version;
+    }
+
+    function normalizeNode(rawNode, maxEvidenceRefs) {
+        if (!isRecord(rawNode)) {
+            throw new Error('Knowledge projection nodes must be objects.');
+        }
+        const id = cleanString(rawNode.id);
+        if (!id) {
+            throw new Error('Knowledge projection node id must be non-empty.');
+        }
+        return {
+            id,
+            canonicalId: cleanString(rawNode.canonicalId),
+            label: cleanString(rawNode.label) || id,
+            sourceUri: cleanString(rawNode.sourceUri),
+            revision: cleanString(rawNode.revision),
+            identityAliases: cleanStringList(rawNode.identityAliases, `node ${id}.identityAliases`, 16),
+            evidenceRefs: cleanStringList(rawNode.evidenceRefs, `node ${id}.evidenceRefs`, maxEvidenceRefs),
+            tags: cleanStringList(rawNode.tags || (rawNode.metadata && rawNode.metadata.tags), `node ${id}.tags`, 32),
+        };
+    }
+
+    function normalizeEdge(rawEdge, nodeById, maxEvidenceRefs) {
+        if (!isRecord(rawEdge)) {
+            throw new Error('Knowledge projection edges must be objects.');
+        }
+        const source = cleanString(rawEdge.source || rawEdge.from);
+        const target = cleanString(rawEdge.target || rawEdge.to);
+        if (!source || !target || source === target || !nodeById.has(source) || !nodeById.has(target)) {
+            throw new Error(`Knowledge projection edge references an invalid node: ${source || '?'} -> ${target || '?'}.`);
+        }
+        const type = cleanString(rawEdge.type) || 'association';
+        const confidence = Number(rawEdge.confidence ?? rawEdge.weight);
+        const sourceNode = nodeById.get(source);
+        const targetNode = nodeById.get(target);
+        return {
+            source,
+            target,
+            sourceUri: cleanString(rawEdge.sourceUri) || sourceNode.sourceUri,
+            targetUri: cleanString(rawEdge.targetUri) || targetNode.sourceUri,
+            type,
+            kind: classifyEdgeKind(type, rawEdge.kind),
+            provenance: cleanString(rawEdge.provenance) || type,
+            confidence: Number.isFinite(confidence) ? Math.max(0, Math.min(1, confidence)) : 1,
+            evidenceRefs: cleanStringList(rawEdge.evidenceRefs, `edge ${source}->${target}.evidenceRefs`, maxEvidenceRefs),
+        };
+    }
+
+    function buildAdjacency(nodes, edges, maxNeighbors) {
+        const adjacency = new Map(nodes.map((node) => [node.id, { outgoing: [], incoming: [] }]));
+        edges.forEach((edge) => {
+            const source = adjacency.get(edge.source);
+            const target = adjacency.get(edge.target);
+            if (source.outgoing.length < maxNeighbors && !source.outgoing.includes(edge.target)) {
+                source.outgoing.push(edge.target);
+            }
+            if (target.incoming.length < maxNeighbors && !target.incoming.includes(edge.source)) {
+                target.incoming.push(edge.source);
+            }
+        });
+        return Array.from(adjacency, ([nodeId, value]) => ({ nodeId, ...value }));
+    }
+
+    function normalizeProjection(rawProjection, options) {
+        if (!isRecord(rawProjection)) {
+            throw new Error('Knowledge projection must be an object.');
+        }
+        const maxNodes = Math.min(MAX_NODES, Math.max(1, Number(options && options.maxNodes) || MAX_NODES));
+        const maxEdges = Math.min(MAX_EDGES, Math.max(1, Number(options && options.maxEdges) || MAX_EDGES));
+        const maxNeighbors = Math.min(MAX_NEIGHBORS, Math.max(1, Number(options && options.maxNeighbors) || MAX_NEIGHBORS));
+        const maxEvidenceRefs = MAX_EVIDENCE_REFS;
+        const declaredSchemaVersion = rawProjection.schemaVersion !== undefined
+            ? rawProjection.schemaVersion
+            : rawProjection.projectionVersion;
+        const schemaVersion = assertSupportedVersion(declaredSchemaVersion);
+        const rawNodes = Array.isArray(rawProjection.nodes) ? rawProjection.nodes : [];
+        const rawEdges = Array.isArray(rawProjection.edges) ? rawProjection.edges : [];
+        if (rawNodes.length > maxNodes || rawEdges.length > maxEdges) {
+            throw new Error(`Knowledge projection exceeds bounded size: ${rawNodes.length} nodes / ${rawEdges.length} edges.`);
+        }
+
+        const nodes = rawNodes.map((node) => normalizeNode(node, maxEvidenceRefs));
+        const nodeIds = new Set();
+        const normalizedIds = new Set();
+        const canonicalIds = new Set();
+        nodes.forEach((node) => {
+            const normalizedId = node.id.normalize ? node.id.normalize('NFC').toLowerCase() : node.id.toLowerCase();
+            if (nodeIds.has(node.id) || normalizedIds.has(normalizedId)) {
+                throw new Error(`Knowledge projection contains a duplicate node id: ${node.id}.`);
+            }
+            nodeIds.add(node.id);
+            normalizedIds.add(normalizedId);
+            if (node.canonicalId) {
+                const normalizedCanonicalId = node.canonicalId.normalize
+                    ? node.canonicalId.normalize('NFC').toLowerCase()
+                    : node.canonicalId.toLowerCase();
+                if (canonicalIds.has(normalizedCanonicalId)
+                    || (normalizedCanonicalId !== normalizedId && normalizedIds.has(normalizedCanonicalId))) {
+                    throw new Error(`Knowledge projection contains a duplicate canonical node id: ${node.canonicalId}.`);
+                }
+                canonicalIds.add(normalizedCanonicalId);
+            }
+        });
+
+        const edgeKeys = new Set();
+        const nodeById = new Map(nodes.map((node) => [node.id, node]));
+        const edges = rawEdges.map((edge) => normalizeEdge(edge, nodeById, maxEvidenceRefs))
+            .filter((edge) => {
+                // Preserve distinct provenance for the same directed endpoints.
+                // Collapsing by kind loses whether a link was explicit-next, wiki, or markdown.
+                const key = `${edge.source}->${edge.target}:${edge.kind}:${edge.type}:${edge.provenance}`;
+                if (edgeKeys.has(key)) {
+                    return false;
+                }
+                edgeKeys.add(key);
+                return true;
+            });
+
+        return {
+            schemaVersion,
+            projectionVersion: schemaVersion,
+            workspaceId: cleanString(rawProjection.workspaceId) || 'workspace',
+            revision: cleanString(rawProjection.revision),
+            nodes,
+            edges,
+            adjacency: buildAdjacency(nodes, edges, maxNeighbors),
+            extensions: isRecord(rawProjection.extensions) ? rawProjection.extensions : {},
+        };
+    }
+
+    function createKnowledgeProjection(graph, options) {
+        if (!isRecord(graph)) {
+            throw new Error('Knowledge graph payload must be an object.');
+        }
+        const projectionOptions = isRecord(options) ? options : {};
+        return normalizeProjection({
+            ...graph,
+            schemaVersion: graph.schemaVersion !== undefined
+                ? graph.schemaVersion
+                : (graph.projectionVersion !== undefined ? graph.projectionVersion : SCHEMA_VERSION),
+            workspaceId: projectionOptions.workspaceId !== undefined
+                ? projectionOptions.workspaceId
+                : graph.workspaceId,
+            revision: projectionOptions.revision !== undefined
+                ? projectionOptions.revision
+                : graph.revision,
+        }, projectionOptions);
+    }
+
+    function replayKnowledgeProjection(serialized, options) {
+        let payload = serialized;
+        if (typeof serialized === 'string') {
+            try {
+                payload = JSON.parse(serialized);
+            } catch (error) {
+                throw new Error(`Knowledge projection JSON is invalid: ${String(error && error.message || error)}.`);
+            }
+        }
+        return normalizeProjection(payload, options);
+    }
+
+    return Object.freeze({
+        schemaVersion: SCHEMA_VERSION,
+        limits: Object.freeze({ maxNodes: MAX_NODES, maxEdges: MAX_EDGES, maxNeighbors: MAX_NEIGHBORS, maxEvidenceRefs: MAX_EVIDENCE_REFS }),
+        classifyEdgeKind,
+        normalizeProjection,
+        createKnowledgeProjection,
+        replayKnowledgeProjection,
+    });
+}));

package/dist/src/frontend/knowledge_projection_store.js

@@ -0,0 +1,214 @@
+(function attachKnowledgeProjectionStore(root, factory) {
+    const api = factory(root && root.NoteConnectionKnowledgeProjection);
+    if (typeof module === 'object' && module.exports) {
+        module.exports = api;
+    }
+    if (root) {
+        root.NoteConnectionKnowledgeProjectionStore = api;
+    }
+}(typeof globalThis !== 'undefined' ? globalThis : this, function createProjectionStoreApi(projectionContract) {
+    'use strict';
+
+    const STORE_VERSION = 1;
+    const FALLBACK_MAX_BYTES = 48 * 1024 * 1024;
+
+    function defaultMaxBytes() {
+        const root = typeof globalThis !== 'undefined' ? globalThis : null;
+        const runtime = root && root.NoteConnectionMobileBudget && root.NoteConnectionMobileBudget.runtime;
+        return runtime && Number.isInteger(runtime.maxProjectionBytes) && runtime.maxProjectionBytes > 0
+            ? runtime.maxProjectionBytes
+            : FALLBACK_MAX_BYTES;
+    }
+
+    function requireProjectionContract() {
+        if (!projectionContract || typeof projectionContract.replayKnowledgeProjection !== 'function') {
+            throw new Error('Knowledge projection contract is unavailable.');
+        }
+        return projectionContract;
+    }
+
+    function normalizeProjection(value, options) {
+        return requireProjectionContract().replayKnowledgeProjection(value, options);
+    }
+
+    function measureBytes(value) {
+        const text = String(value || '');
+        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 metadataFor(projection) {
+        return Object.freeze({
+            schemaVersion: projection.schemaVersion,
+            projectionVersion: projection.projectionVersion,
+            workspaceId: projection.workspaceId,
+            revision: projection.revision,
+            nodeCount: projection.nodes.length,
+            edgeCount: projection.edges.length,
+        });
+    }
+
+    function createMemoryProjectionStore(initialProjection, options) {
+        const normalizedOptions = options && typeof options === 'object' ? options : {};
+        let current = initialProjection === undefined || initialProjection === null
+            ? null
+            : normalizeProjection(initialProjection, normalizedOptions);
+
+        return Object.freeze({
+            kind: 'memory',
+            async load() {
+                return current;
+            },
+            async save(projection) {
+                current = normalizeProjection(projection, normalizedOptions);
+                return current;
+            },
+            async metadata() {
+                return current ? metadataFor(current) : null;
+            },
+        });
+    }
+
+    function createPersistentProjectionStore(options) {
+        const normalizedOptions = options && typeof options === 'object' ? options : {};
+        const read = normalizedOptions.read;
+        const write = normalizedOptions.write;
+        if (typeof read !== 'function') {
+            return createMemoryProjectionStore(normalizedOptions.initialProjection, normalizedOptions);
+        }
+
+        const maxBytes = Math.max(1024, Math.floor(Number(normalizedOptions.maxBytes) || defaultMaxBytes()));
+        let cached = normalizedOptions.initialProjection === undefined || normalizedOptions.initialProjection === null
+            ? null
+            : normalizeProjection(normalizedOptions.initialProjection, normalizedOptions);
+        let hasLoaded = false;
+        let loadPromise = null;
+
+        const load = async () => {
+            if (hasLoaded && cached) {
+                return cached;
+            }
+            if (loadPromise) {
+                return await loadPromise;
+            }
+            loadPromise = (async () => {
+                let payload;
+                try {
+                    payload = await read();
+                } catch (error) {
+                    if (cached) {
+                        return cached;
+                    }
+                    throw error;
+                }
+                const serialized = typeof payload === 'string' ? payload : JSON.stringify(payload);
+                if (typeof serialized !== 'string') {
+                    throw new Error('Knowledge projection payload is not serializable.');
+                }
+                if (measureBytes(serialized) > maxBytes) {
+                    throw new Error(`Knowledge projection payload exceeds ${maxBytes} bytes.`);
+                }
+                // Validation errors must not be hidden by a stale in-memory value.
+                cached = normalizeProjection(payload, normalizedOptions);
+                hasLoaded = true;
+                return cached;
+            })();
+            try {
+                return await loadPromise;
+            } finally {
+                loadPromise = null;
+            }
+        };
+
+        return Object.freeze({
+            kind: typeof write === 'function' ? 'persistent' : 'read-through',
+            load,
+            async save(projection) {
+                const next = normalizeProjection(projection, normalizedOptions);
+                const serialized = JSON.stringify(next);
+                if (measureBytes(serialized) > maxBytes) {
+                    throw new Error(`Knowledge projection payload exceeds ${maxBytes} bytes.`);
+                }
+                if (typeof write !== 'function') {
+                    throw new Error('Knowledge projection store is read-only in this runtime.');
+                }
+                await write(serialized, next);
+                cached = next;
+                hasLoaded = true;
+                return next;
+            },
+            async metadata() {
+                const projection = await load();
+                return projection ? metadataFor(projection) : null;
+            },
+        });
+    }
+
+    function createFileProjectionStore(options) {
+        const normalizedOptions = options && typeof options === 'object' ? options : {};
+        const fileName = typeof normalizedOptions.fileName === 'string'
+            ? normalizedOptions.fileName.trim()
+            : '';
+        const readFile = normalizedOptions.readFile;
+        const writeAtomic = normalizedOptions.writeAtomic;
+
+        if (!fileName) {
+            throw new Error('App-local projection file name is required.');
+        }
+        if (typeof readFile !== 'function') {
+            throw new Error('App-local projection readFile adapter is required.');
+        }
+        if (writeAtomic !== undefined && typeof writeAtomic !== 'function') {
+            throw new Error('App-local projection writeAtomic adapter must be callable.');
+        }
+        if (normalizedOptions.write !== undefined) {
+            throw new Error('App-local projection writes must use the writeAtomic adapter.');
+        }
+
+        const persistentOptions = {
+            ...Object.fromEntries(Object.entries(normalizedOptions).filter(([key]) => (
+                key !== 'fileName'
+                && key !== 'readFile'
+                && key !== 'writeAtomic'
+                && key !== 'read'
+                && key !== 'write'
+            ))),
+            read: async () => await readFile(fileName),
+        };
+        if (typeof writeAtomic === 'function') {
+            persistentOptions.write = async (serialized, projection) => {
+                await writeAtomic(fileName, serialized, projection);
+            };
+        }
+
+        const store = createPersistentProjectionStore(persistentOptions);
+        return Object.freeze({
+            ...store,
+            kind: typeof writeAtomic === 'function' ? 'file-persistent' : 'file-read-through',
+            fileName,
+        });
+    }
+
+    function createProjectionStore(options) {
+        const normalizedOptions = options && typeof options === 'object' ? options : {};
+        if (typeof normalizedOptions.read === 'function') {
+            return createPersistentProjectionStore(normalizedOptions);
+        }
+        return createMemoryProjectionStore(normalizedOptions.initialProjection, normalizedOptions);
+    }
+
+    return Object.freeze({
+        storeVersion: STORE_VERSION,
+        defaultMaxBytes: FALLBACK_MAX_BYTES,
+        createProjectionStore,
+        createMemoryProjectionStore,
+        createPersistentProjectionStore,
+        createFileProjectionStore,
+        metadataFor,
+    });
+}));

package/dist/src/frontend/layout_gpu.js

@@ -232,7 +232,17 @@ class GPULinkForce {
         const nLinks = this._links.length;
         console.log(`[GPULink] Initializing for ${n} nodes, ${nLinks} links.`);
         
-        if (n === 0) return;
+        if (this.kernel) {
+            this.kernel.destroy();
+            this.kernel = null;
+        }
+
+        if (n === 0 || nLinks === 0) {
+            this.adjHead = new Float32Array(n);
+            this.adjCount = new Float32Array(n);
+            this.flatIndices = new Float32Array(0);
+            return;
+        }
 
         // Build Adjacency List (Source <-> Target)
         // D3 Link Force is symmetric: force acts on both ends.
@@ -295,8 +305,6 @@ class GPULinkForce {
         // Limit max neighbors width for texture if needed? 
         // gpu.js handles 1D arrays well.
         
-        if (this.kernel) this.kernel.destroy();
-
         // ---------------------------------------------------------
         // KERNEL
         // ---------------------------------------------------------
@@ -368,7 +376,7 @@ class GPULinkForce {
     }
 
     force(alpha) {
-        if (!this.available || this.nodes.length === 0) return;
+        if (!this.available || this.nodes.length === 0 || this._links.length === 0 || this.flatIndices.length === 0) return;
         
         const n = this.nodes.length;
         const posX = new Float32Array(n);