@semiont/graph 0.5.30 → 0.5.31

package/dist/index.d.ts

@@ -84,6 +84,40 @@ declare function createGraphDatabase(config: GraphDatabaseConfig): GraphDatabase
 declare function getGraphDatabase(graphConfig: GraphServiceConfig): Promise<GraphDatabase>;
 declare function closeGraphDatabase(): Promise<void>;
 
+/**
+ * The annotation codec — the one module that decides how a W3C annotation
+ * becomes stored properties and back.
+ *
+ * Every store keeps its own dialect (Cypher parameters, Gremlin
+ * `.property()` chains, a Map) and its own way of flattening what the driver
+ * hands back into a property bag. What none of them owns any more is the
+ * SHAPE: the W3C envelope, which fields are required, how a selector is
+ * serialized, how the body array is reconstructed from entity tags and a
+ * linking source. Those lived in three near-verbatim copies that disagreed
+ * in four places, and each disagreement was a bug — a resource-level
+ * annotation came back carrying `selector: {}`, which is not a legal
+ * selector, and a motivation-less row was silently relabelled `'linking'`.
+ *
+ * The codec manufactures nothing. Absence is stored as absence and read back
+ * as absence, in both directions.
+ */
+
+/**
+ * What the graph is SUPPOSED to hold for this annotation — the codec's own
+ * statement of it, obtained by round-tripping through both halves.
+ *
+ * The graph is a purpose-built projection, not a copy of the views: it stores
+ * what graph queries need and nothing else. `wasAttributedTo`, for instance,
+ * rides on almost every annotation in the log and the encoder deliberately
+ * writes none of it. So "is the graph correct?" cannot be answered by comparing
+ * it to a view — only by comparing it to what this module says it should be.
+ *
+ * Callers get a value scoped to exactly the fields the encoder writes, in the
+ * decoded shape, free of any store's physical dialect. Widen or narrow the
+ * encoder and this follows automatically; there is no second list to maintain.
+ */
+declare function intendedGraphAnnotation(annotation: Annotation): Annotation;
+
 declare class Neo4jGraphDatabase implements GraphDatabase {
     private driver;
     private neo4j;
@@ -375,5 +409,5 @@ declare class MemoryGraphDatabase implements GraphDatabase {
     clearDatabase(): Promise<void>;
 }
 
-export { JanusGraphDatabase, MemoryGraphDatabase, Neo4jGraphDatabase, NeptuneGraphDatabase, closeGraphDatabase, compareByRecencyThenId, createGraphDatabase, getGraphDatabase };
+export { JanusGraphDatabase, MemoryGraphDatabase, Neo4jGraphDatabase, NeptuneGraphDatabase, closeGraphDatabase, compareByRecencyThenId, createGraphDatabase, getGraphDatabase, intendedGraphAnnotation };
 export type { GraphDatabase };

package/dist/index.js

@@ -56,18 +56,19 @@ function queryResources(all, filter) {
 }
 
 // src/implementations/neptune.ts
-import { getEntityTypes } from "@semiont/ontology";
+import { getEntityTypes as getEntityTypes2 } from "@semiont/ontology";
 
 // src/annotation-codec.ts
 import { annotationId as makeAnnotationId } from "@semiont/core";
 import { getBodySource, getExactText, getTargetSelector, getTargetSource } from "@semiont/core";
+import { getEntityTypes } from "@semiont/ontology";
 function storedAnnotationType(motivation) {
   return motivation === "highlighting" ? "TextualBody" : "SpecificResource";
 }
 function motivationForCategory(category) {
   return category === "highlight" ? "highlighting" : "linking";
 }
-function buildAnnotation(input, created) {
+function buildAnnotation(input) {
   const annotation = {
     "@context": "http://www.w3.org/ns/anno.jsonld",
     type: "Annotation",
@@ -75,7 +76,7 @@ function buildAnnotation(input, created) {
     motivation: input.motivation,
     target: input.target,
     creator: input.creator,
-    created
+    created: input.created
   };
   if (input.body && (!Array.isArray(input.body) || input.body.length > 0)) {
     annotation.body = input.body;
@@ -87,7 +88,6 @@ function encodeAnnotation(annotation) {
   const bodySource = getBodySource(annotation.body);
   const resourceId = getTargetSource(annotation.target);
   if (!resourceId) throw new Error(`Annotation ${annotation.id} has no target source`);
-  if (!annotation.created) throw new Error(`Annotation ${annotation.id} has no created timestamp`);
   const props = {
     id: annotation.id,
     resourceId,
@@ -154,6 +154,9 @@ function decodeSelector(raw) {
   if (!parsed || Object.keys(parsed).length === 0) return void 0;
   return parsed;
 }
+function intendedGraphAnnotation(annotation) {
+  return decodeAnnotation(encodeAnnotation(annotation), getEntityTypes(annotation));
+}
 
 // src/implementations/neptune.ts
 import { v4 as uuidv4 } from "uuid";
@@ -167,7 +170,7 @@ var cardinality;
 var __;
 async function loadDependencies() {
   if (!NeptuneClient) {
-    const neptuneModule = await import("./dist-es-F44WH2AS.js");
+    const neptuneModule = await import("./dist-es-7XA2K3QN.js");
     NeptuneClient = neptuneModule.NeptuneClient;
     DescribeDBClustersCommand = neptuneModule.DescribeDBClustersCommand;
   }
@@ -435,11 +438,11 @@ var NeptuneGraphDatabase = class {
     }
   }
   async createAnnotation(input) {
-    const annotation = buildAnnotation(input, (/* @__PURE__ */ new Date()).toISOString());
+    const annotation = buildAnnotation(input);
     const props = encodeAnnotation(annotation);
     const targetSource = props.resourceId;
     const bodySource = props.source;
-    const entityTypes = getEntityTypes(input);
+    const entityTypes = getEntityTypes2(input);
     try {
       let vertex = this.g.addV("Annotation");
       for (const [key, value] of Object.entries(props)) {
@@ -490,7 +493,7 @@ var NeptuneGraphDatabase = class {
       }
       if (updates.body !== void 0) {
         const bodySource = getBodySource2(updates.body);
-        const entityTypes2 = getEntityTypes({ body: updates.body });
+        const entityTypes2 = getEntityTypes2({ body: updates.body });
         if (bodySource) {
           traversal = traversal.property("source", bodySource);
         }
@@ -863,7 +866,7 @@ var NeptuneGraphDatabase = class {
 // src/implementations/neo4j.ts
 import { v4 as uuidv42 } from "uuid";
 import { getPrimaryRepresentation as getPrimaryRepresentation2, getStorageUri as getStorageUri3 } from "@semiont/core";
-import { getEntityTypes as getEntityTypes2 } from "@semiont/ontology";
+import { getEntityTypes as getEntityTypes3 } from "@semiont/ontology";
 function motivationToLabel(motivation) {
   return motivation.charAt(0).toUpperCase() + motivation.slice(1);
 }
@@ -989,7 +992,7 @@ var Neo4jGraphDatabase = class {
              d.entityTypes = $entityTypes,
              d.format = $format,
              d.archived = $archived,
-             d.created = datetime($created),
+             d.created = $created,
              d.creator = $creator,
              d.contentChecksum = $contentChecksum,
              d.sourceAnnotationId = $sourceAnnotationId,
@@ -1129,16 +1132,16 @@ var Neo4jGraphDatabase = class {
   async createAnnotation(input) {
     const session = this.getSession();
     try {
-      const annotation = buildAnnotation(input, (/* @__PURE__ */ new Date()).toISOString());
+      const annotation = buildAnnotation(input);
       const props = encodeAnnotation(annotation);
       const targetSource = props.resourceId;
       const bodySource = props.source;
-      const entityTypes = getEntityTypes2(input);
+      const entityTypes = getEntityTypes3(input);
       const motivationLabel = motivationToLabel(annotation.motivation);
       const cypher = bodySource ? `MATCH (from:Resource {id: $targetSource})
            MATCH (to:Resource {id: $bodySource})
            CREATE (a:Annotation:${motivationLabel})
-           SET a = $props, a.created = datetime($created)
+           SET a = $props
            CREATE (a)-[:BELONGS_TO]->(from)
            CREATE (a)-[:REFERENCES]->(to)
            FOREACH (entityType IN $entityTypes |
@@ -1147,7 +1150,7 @@ var Neo4jGraphDatabase = class {
            )
            RETURN a` : `MATCH (d:Resource {id: $targetSource})
            CREATE (a:Annotation:${motivationLabel})
-           SET a = $props, a.created = datetime($created)
+           SET a = $props
            CREATE (a)-[:BELONGS_TO]->(d)
            FOREACH (entityType IN $entityTypes |
              MERGE (et:EntityType {name: entityType})
@@ -1156,7 +1159,6 @@ var Neo4jGraphDatabase = class {
            RETURN a`;
       const result = await session.run(cypher, {
         props,
-        created: annotation.created,
         targetSource,
         bodySource: bodySource ?? null,
         entityTypes
@@ -1646,7 +1648,7 @@ var Neo4jGraphDatabase = class {
              d.entityTypes = r.entityTypes,
              d.format = r.format,
              d.archived = r.archived,
-             d.created = datetime(r.created),
+             d.created = r.created,
              d.creator = r.creator,
              d.contentChecksum = r.contentChecksum,
              d.sourceAnnotationId = r.sourceAnnotationId,
@@ -1789,7 +1791,7 @@ function normalizeProperties2(props) {
 // src/implementations/janusgraph.ts
 import { resourceId as makeResourceId } from "@semiont/core";
 import { getBodySource as getBodySource3, getPrimaryRepresentation as getPrimaryRepresentation3, getResourceId as getResourceId2, getStorageUri as getStorageUri4 } from "@semiont/core";
-import { getEntityTypes as getEntityTypes3 } from "@semiont/ontology";
+import { getEntityTypes as getEntityTypes4 } from "@semiont/ontology";
 import { v4 as uuidv43 } from "uuid";
 function getPropertyValue(props, key) {
   if (!props[key]) return void 0;
@@ -1951,11 +1953,11 @@ var JanusGraphDatabase = class {
     return queryResources(docs.map((v) => this.vertexToResource(v)), filter);
   }
   async createAnnotation(input) {
-    const annotation = buildAnnotation(input, (/* @__PURE__ */ new Date()).toISOString());
+    const annotation = buildAnnotation(input);
     const props = encodeAnnotation(annotation);
     const targetSource = props.resourceId;
     const bodySource = props.source;
-    const entityTypes = getEntityTypes3(input);
+    const entityTypes = getEntityTypes4(input);
     let vertex = this.g.addV("Annotation");
     for (const [key, value] of Object.entries(props)) {
       vertex = vertex.property(key, value);
@@ -2000,7 +2002,7 @@ var JanusGraphDatabase = class {
     }
     if (updates.body !== void 0) {
       const bodySource = getBodySource3(updates.body);
-      const entityTypes = getEntityTypes3({ body: updates.body });
+      const entityTypes = getEntityTypes4({ body: updates.body });
       if (bodySource) {
         await traversalQuery.property("source", bodySource).next();
       }
@@ -2092,11 +2094,11 @@ var JanusGraphDatabase = class {
     });
     if (entityTypes && entityTypes.length > 0) {
       return annotations.filter((ann) => {
-        const annEntityTypes = getEntityTypes3(ann);
+        const annEntityTypes = getEntityTypes4(ann);
         return annEntityTypes.some((type) => entityTypes.includes(type));
       });
     }
-    return annotations.filter((ann) => getEntityTypes3(ann).length > 0);
+    return annotations.filter((ann) => getEntityTypes4(ann).length > 0);
   }
   async getResourceAnnotations(resourceId) {
     const { annotations } = await this.listAnnotations({ resourceId });
@@ -2164,7 +2166,7 @@ var JanusGraphDatabase = class {
     const annotations = await this.fetchAnnotationsWithEntityTypes(anns);
     const highlights = annotations.filter((a) => a.motivation === "highlighting");
     const references = annotations.filter((a) => a.motivation === "linking");
-    const entityReferences = references.filter((a) => getEntityTypes3(a).length > 0);
+    const entityReferences = references.filter((a) => getEntityTypes4(a).length > 0);
     return {
       resourceCount: resources.length,
       annotationCount: annotations.length,
@@ -2269,7 +2271,7 @@ var JanusGraphDatabase = class {
 import { resourceId as makeResourceId2 } from "@semiont/core";
 import { v4 as uuidv44 } from "uuid";
 import { getBodySource as getBodySource4, getTargetSource as getTargetSource3, getResourceId as getResourceId3, getPrimaryRepresentation as getPrimaryRepresentation4, getResourceEntityTypes as getResourceEntityTypes2 } from "@semiont/core";
-import { getEntityTypes as getEntityTypes4 } from "@semiont/ontology";
+import { getEntityTypes as getEntityTypes5 } from "@semiont/ontology";
 var MemoryGraphDatabase = class {
   connected = false;
   logger;
@@ -2323,8 +2325,8 @@ var MemoryGraphDatabase = class {
   async createAnnotation(input) {
     const id = input.id;
     const annotation = decodeAnnotation(
-      encodeAnnotation(buildAnnotation(input, (/* @__PURE__ */ new Date()).toISOString())),
-      getEntityTypes4(input)
+      encodeAnnotation(buildAnnotation(input)),
+      getEntityTypes5(input)
     );
     this.annotations.set(id, annotation);
     this.logger?.debug("Created annotation", {
@@ -2391,9 +2393,9 @@ var MemoryGraphDatabase = class {
   }
   async getEntityReferences(resourceId, entityTypes) {
     const resourceIdStr = String(resourceId);
-    let refs = Array.from(this.annotations.values()).filter((sel) => getTargetSource3(sel.target) === resourceIdStr && getEntityTypes4(sel).length > 0);
+    let refs = Array.from(this.annotations.values()).filter((sel) => getTargetSource3(sel.target) === resourceIdStr && getEntityTypes5(sel).length > 0);
     if (entityTypes && entityTypes.length > 0) {
-      refs = refs.filter((sel) => getEntityTypes4(sel).some((type) => entityTypes.includes(type)));
+      refs = refs.filter((sel) => getEntityTypes5(sel).some((type) => entityTypes.includes(type)));
     }
     return refs;
   }
@@ -2484,7 +2486,7 @@ var MemoryGraphDatabase = class {
     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
+      (a) => a.motivation === "linking" && getEntityTypes5(a).length > 0
     ).length;
     return {
       resourceCount: this.resources.size,
@@ -2663,6 +2665,7 @@ export {
   closeGraphDatabase,
   compareByRecencyThenId,
   createGraphDatabase,
-  getGraphDatabase
+  getGraphDatabase,
+  intendedGraphAnnotation
 };
 //# sourceMappingURL=index.js.map