@semiont/graph 0.2.30 → 0.2.31

package/README.md

@@ -1,7 +1,10 @@
 # @semiont/graph
 
-[![npm version](https://img.shields.io/npm/v/@semiont/graph)](https://www.npmjs.com/package/@semiont/graph)
 [![Tests](https://github.com/The-AI-Alliance/semiont/actions/workflows/package-tests.yml/badge.svg)](https://github.com/The-AI-Alliance/semiont/actions/workflows/package-tests.yml?query=branch%3Amain+is%3Asuccess+job%3A%22Test+graph%22)
+[![codecov](https://codecov.io/gh/The-AI-Alliance/semiont/graph/badge.svg?flag=graph)](https://codecov.io/gh/The-AI-Alliance/semiont?flag=graph)
+[![npm version](https://img.shields.io/npm/v/@semiont/graph.svg)](https://www.npmjs.com/package/@semiont/graph)
+[![npm downloads](https://img.shields.io/npm/dm/@semiont/graph.svg)](https://www.npmjs.com/package/@semiont/graph)
+[![License](https://img.shields.io/npm/l/@semiont/graph.svg)](https://github.com/The-AI-Alliance/semiont/blob/main/LICENSE)
 
 Graph database abstraction with Neo4j, Neptune, JanusGraph, and in-memory implementations.
 
@@ -84,6 +87,7 @@ const annotations = await graph.getAnnotationsForDocument('doc-123');
 
 - [API Reference](./docs/API.md) - Complete API documentation
 - [Architecture](./docs/ARCHITECTURE.md) - System design and principles
+- [Eventual Consistency](./docs/EVENTUAL-CONSISTENCY.md) - Order-independent projections and race condition handling
 - [Provider Guide](./docs/PROVIDERS.md) - Provider-specific details
 
 ## Examples

package/dist/index.js

@@ -880,19 +880,19 @@ var Neo4jGraphDatabase = class {
         throw new Error("Resource must have at least one representation");
       }
       const result = await session.run(
-        `CREATE (d:Resource {
-          id: $id,
-          name: $name,
-          entityTypes: $entityTypes,
-          format: $format,
-          archived: $archived,
-          created: datetime($created),
-          creator: $creator,
-          creationMethod: $creationMethod,
-          contentChecksum: $contentChecksum,
-          sourceAnnotationId: $sourceAnnotationId,
-          sourceResourceId: $sourceResourceId
-        }) RETURN d`,
+        `MERGE (d:Resource {id: $id})
+         SET d.name = $name,
+             d.entityTypes = $entityTypes,
+             d.format = $format,
+             d.archived = $archived,
+             d.created = datetime($created),
+             d.creator = $creator,
+             d.creationMethod = $creationMethod,
+             d.contentChecksum = $contentChecksum,
+             d.sourceAnnotationId = $sourceAnnotationId,
+             d.sourceResourceId = $sourceResourceId,
+             d.stub = false
+         RETURN d`,
         {
           id,
           name: resource.name,
@@ -907,6 +907,7 @@ var Neo4jGraphDatabase = class {
           sourceResourceId: resource.sourceResourceId ?? null
         }
       );
+      console.log(`[Neo4j] Resource created/enriched: ${id}`);
       return this.parseResourceNode(result.records[0].get("d"));
     } finally {
       await session.close();
@@ -1189,18 +1190,24 @@ var Neo4jGraphDatabase = class {
           console.log(`[Neo4j] \u2705 Creating REFERENCES edge: ${id} -> ${specificResource.source}`);
           const refResult = await session.run(
             `MATCH (a:Annotation {id: $annotationId})
-             MATCH (target:Resource {id: $targetResourceId})
+             MERGE (target:Resource {id: $targetResourceId})
+             ON CREATE SET target.stub = true
              MERGE (a)-[:REFERENCES]->(target)
-             RETURN a, target`,
+             RETURN a, target, target.stub AS wasStub`,
             {
               annotationId: id,
               targetResourceId: specificResource.source
             }
           );
-          console.log(`[Neo4j] \u2705 REFERENCES edge created! Matched ${refResult.records.length} nodes`);
           if (refResult.records.length > 0) {
-            console.log(`[Neo4j]   Annotation: ${refResult.records[0].get("a").properties.id}`);
-            console.log(`[Neo4j]   Target Resource: ${refResult.records[0].get("target").properties.id}`);
+            const wasStub = refResult.records[0].get("wasStub");
+            if (wasStub) {
+              console.log(`[Neo4j] \u2705 REFERENCES edge created with stub node for ${specificResource.source} (will be enriched by resource.created event)`);
+            } else {
+              console.log(`[Neo4j] \u2705 REFERENCES edge created to existing resource ${specificResource.source}`);
+            }
+          } else {
+            console.log(`[Neo4j] \u26A0\uFE0F  REFERENCES edge creation returned no records`);
           }
         } else {
           console.log(`[Neo4j] No SpecificResource in body - this is a stub reference (not yet resolved)`);
@@ -2258,7 +2265,7 @@ var JanusGraphDatabase = class {
 // src/implementations/memorygraph.ts
 import { getResourceEntityTypes } from "@semiont/api-client";
 import { getEntityTypes as getEntityTypes4 } from "@semiont/ontology";
-import { resourceId as makeResourceId } from "@semiont/core";
+import { resourceId as makeResourceId, uriToResourceId } from "@semiont/core";
 import { resourceUri as resourceUri2 } from "@semiont/api-client";
 import { v4 as uuidv44 } from "uuid";
 import { getBodySource as getBodySource4, getTargetSource as getTargetSource3 } from "@semiont/api-client";
@@ -2290,19 +2297,28 @@ var MemoryGraphDatabase = class {
     return resource;
   }
   async getResource(id) {
-    return this.resources.get(id) || null;
+    try {
+      const resourceId = uriToResourceId(id);
+      return this.resources.get(resourceId) || null;
+    } catch {
+      return null;
+    }
   }
   async updateResource(id, input) {
     if (Object.keys(input).length !== 1 || input.archived === void 0) {
       throw new Error("Resources are immutable. Only archiving is allowed.");
     }
-    const doc = this.resources.get(id);
+    const resourceId = uriToResourceId(id);
+    const doc = resourceId ? this.resources.get(resourceId) : null;
     if (!doc) throw new Error("Resource not found");
     doc.archived = input.archived;
     return doc;
   }
   async deleteResource(id) {
-    this.resources.delete(id);
+    const resourceId = uriToResourceId(id);
+    if (resourceId) {
+      this.resources.delete(resourceId);
+    }
     for (const [selId, sel] of this.annotations) {
       if (getTargetSource3(sel.target) === id || getBodySource4(sel.body) === id) {
         this.annotations.delete(selId);
@@ -2376,7 +2392,8 @@ var MemoryGraphDatabase = class {
       const resourceIdStr = String(filter.resourceId);
       results = results.filter((a) => {
         const targetSource = getTargetSource3(a.target);
-        return targetSource === resourceIdStr || targetSource === resourceUri2(resourceIdStr);
+        const targetResourceId = targetSource ? uriToResourceId(targetSource) : null;
+        return targetResourceId === resourceIdStr;
       });
     }
     if (filter.type) {
@@ -2389,7 +2406,8 @@ var MemoryGraphDatabase = class {
     const resourceIdStr = String(resourceId);
     const highlights = Array.from(this.annotations.values()).filter((sel) => {
       const targetSource = getTargetSource3(sel.target);
-      return (targetSource === resourceIdStr || targetSource === resourceUri2(resourceIdStr)) && sel.motivation === "highlighting";
+      const targetResourceId = targetSource ? uriToResourceId(targetSource) : null;
+      return targetResourceId === resourceIdStr && sel.motivation === "highlighting";
     });
     console.log(`Memory: getHighlights for ${resourceId} found ${highlights.length} highlights`);
     return highlights;
@@ -2397,11 +2415,13 @@ var MemoryGraphDatabase = class {
   async resolveReference(annotationId, source) {
     const annotation = this.annotations.get(annotationId);
     if (!annotation) throw new Error("Annotation not found");
+    const sourceResource = this.resources.get(String(source));
+    if (!sourceResource) throw new Error("Source resource not found");
     const updated = {
       ...annotation,
       body: {
         type: "SpecificResource",
-        source,
+        source: sourceResource["@id"],
         purpose: "linking"
       }
     };
@@ -2412,7 +2432,8 @@ var MemoryGraphDatabase = class {
     const resourceIdStr = String(resourceId);
     const references = Array.from(this.annotations.values()).filter((sel) => {
       const targetSource = getTargetSource3(sel.target);
-      return (targetSource === resourceIdStr || targetSource === resourceUri2(resourceIdStr)) && sel.motivation === "linking";
+      const targetResourceId = targetSource ? uriToResourceId(targetSource) : null;
+      return targetResourceId === resourceIdStr && sel.motivation === "linking";
     });
     console.log(`Memory: getReferences for ${resourceId} found ${references.length} references`);
     references.forEach((ref) => {
@@ -2428,14 +2449,16 @@ var MemoryGraphDatabase = class {
   async getEntityReferences(resourceId, entityTypes) {
     const resourceIdStr = String(resourceId);
     let refs = Array.from(this.annotations.values()).filter((sel) => {
-      const selEntityTypes = getEntityTypes4(sel);
       const targetSource = getTargetSource3(sel.target);
-      return (targetSource === resourceIdStr || targetSource === resourceUri2(resourceIdStr)) && selEntityTypes.length > 0;
+      const targetResourceId = targetSource ? uriToResourceId(targetSource) : null;
+      const bodyEntityTypes = sel.body?.entityTypes;
+      const hasEntityTypes = Array.isArray(bodyEntityTypes) && bodyEntityTypes.length > 0;
+      return targetResourceId === resourceIdStr && hasEntityTypes;
     });
     if (entityTypes && entityTypes.length > 0) {
       refs = refs.filter((sel) => {
-        const selEntityTypes = getEntityTypes4(sel);
-        return selEntityTypes.some((type) => entityTypes.includes(type));
+        const bodyEntityTypes = sel.body?.entityTypes || [];
+        return bodyEntityTypes.some((type) => entityTypes.includes(type));
       });
     }
     return refs;
@@ -2444,7 +2467,8 @@ var MemoryGraphDatabase = class {
     const resourceIdStr = String(resourceId);
     return Array.from(this.annotations.values()).filter((sel) => {
       const targetSource = getTargetSource3(sel.target);
-      return targetSource === resourceIdStr || targetSource === resourceUri2(resourceIdStr);
+      const targetResourceId = targetSource ? uriToResourceId(targetSource) : null;
+      return targetResourceId === resourceIdStr;
     });
   }
   async getResourceReferencedBy(resourceUri3, _motivation) {
@@ -2458,34 +2482,41 @@ var MemoryGraphDatabase = class {
       if (bodySource) {
         const targetDoc = await this.getResource(resourceUri2(bodySource));
         if (targetDoc) {
-          const reverseRefs = await this.getReferences(makeResourceId(bodySource));
-          const resourceIdStr = String(resourceId);
-          const bidirectional = reverseRefs.some((r) => {
-            const reverseBodySource = getBodySource4(r.body);
-            return reverseBodySource === resourceIdStr || reverseBodySource === resourceUri2(resourceIdStr);
-          });
-          connections.push({
-            targetResource: targetDoc,
-            annotations: [ref],
-            bidirectional
-          });
+          const bodySourceId = uriToResourceId(bodySource);
+          if (bodySourceId) {
+            const reverseRefs = await this.getReferences(makeResourceId(bodySourceId));
+            const resourceIdStr = String(resourceId);
+            const bidirectional = reverseRefs.some((r) => {
+              const reverseBodySource = getBodySource4(r.body);
+              const reverseBodyResourceId = reverseBodySource ? uriToResourceId(reverseBodySource) : null;
+              return reverseBodyResourceId === resourceIdStr;
+            });
+            connections.push({
+              targetResource: targetDoc,
+              annotations: [ref],
+              bidirectional
+            });
+          }
         }
       }
     }
     return connections;
   }
   async findPath(fromResourceId, toResourceId, maxDepth = 5) {
+    const fromUuid = uriToResourceId(fromResourceId);
+    const toUuid = uriToResourceId(toResourceId);
+    if (!fromUuid || !toUuid) return [];
     const visited = /* @__PURE__ */ new Set();
     const queue = [];
     const fromDoc = await this.getResource(resourceUri2(fromResourceId));
     if (!fromDoc) return [];
-    queue.push({ docId: fromResourceId, path: [fromDoc], sels: [] });
-    visited.add(fromResourceId);
+    queue.push({ docId: fromUuid, path: [fromDoc], sels: [] });
+    visited.add(fromUuid);
     const paths = [];
     while (queue.length > 0 && paths.length < 10) {
       const { docId, path, sels } = queue.shift();
       if (path.length > maxDepth) continue;
-      if (docId === toResourceId) {
+      if (docId === toUuid) {
         paths.push({ resources: path, annotations: sels });
         continue;
       }
@@ -2532,7 +2563,10 @@ var MemoryGraphDatabase = class {
     const annotations = Array.from(this.annotations.values());
     const highlightCount = annotations.filter((a) => a.motivation === "highlighting").length;
     const referenceCount = annotations.filter((a) => a.motivation === "linking").length;
-    const entityReferenceCount = annotations.filter((a) => a.motivation === "linking" && getEntityTypes4(a).length > 0).length;
+    const entityReferenceCount = annotations.filter((a) => {
+      const bodyEntityTypes = a.body?.entityTypes;
+      return a.motivation === "linking" && Array.isArray(bodyEntityTypes) && bodyEntityTypes.length > 0;
+    }).length;
     return {
       resourceCount: this.resources.size,
       annotationCount: this.annotations.size,