@utaba/deep-memory 0.17.0 → 0.19.0

package/dist/{StorageProvider-DDTLUcuj.d.ts → StorageProvider-CgWRfvIZ.d.ts}

@@ -1,4 +1,4 @@
-import { au as StorageRepositoryConfig, aB as StoredRepository, ad as RepositoryFilter, T as PaginatedResult, aC as StoredRepositorySummary, ah as RepositoryUpdate, g as DeleteProgressCallback, af as RepositoryStats, O as MemoryVocabulary, U as PaginationOptions, aM as VocabularyChangeRecord, ay as StoredEntity, az as StoredEntityUpdate, an as StorageFindQuery, aA as StoredRelationship, a5 as RelationshipQueryOptions, am as StorageExploreOptions, ao as StorageNeighborhood, as as StoragePathOptions, at as StoragePathResult, aw as StorageTimelineOptions, ax as StorageTimelineResult, s as ExportChunk, J as ImportChunk, B as BulkImportOptions, d as BulkImportResult } from './portability-Dbm6vCdD.js';
+import { au as StorageRepositoryConfig, aB as StoredRepository, ad as RepositoryFilter, T as PaginatedResult, aC as StoredRepositorySummary, ah as RepositoryUpdate, g as DeleteProgressCallback, af as RepositoryStats, O as MemoryVocabulary, U as PaginationOptions, aM as VocabularyChangeRecord, ay as StoredEntity, az as StoredEntityUpdate, an as StorageFindQuery, aA as StoredRelationship, a5 as RelationshipQueryOptions, am as StorageExploreOptions, ao as StorageNeighborhood, as as StoragePathOptions, at as StoragePathResult, aw as StorageTimelineOptions, ax as StorageTimelineResult, s as ExportChunk, J as ImportChunk, B as BulkImportOptions, d as BulkImportResult } from './portability-BHyXmv5-.js';
 
 /** Result returned by ensureSchema describing what actions were taken. */
 interface EnsureSchemaResult {

package/dist/{StorageProvider-DGH7bVuK.d.cts → StorageProvider-RPhT7vtH.d.cts}

@@ -1,4 +1,4 @@
-import { au as StorageRepositoryConfig, aB as StoredRepository, ad as RepositoryFilter, T as PaginatedResult, aC as StoredRepositorySummary, ah as RepositoryUpdate, g as DeleteProgressCallback, af as RepositoryStats, O as MemoryVocabulary, U as PaginationOptions, aM as VocabularyChangeRecord, ay as StoredEntity, az as StoredEntityUpdate, an as StorageFindQuery, aA as StoredRelationship, a5 as RelationshipQueryOptions, am as StorageExploreOptions, ao as StorageNeighborhood, as as StoragePathOptions, at as StoragePathResult, aw as StorageTimelineOptions, ax as StorageTimelineResult, s as ExportChunk, J as ImportChunk, B as BulkImportOptions, d as BulkImportResult } from './portability-Dbm6vCdD.cjs';
+import { au as StorageRepositoryConfig, aB as StoredRepository, ad as RepositoryFilter, T as PaginatedResult, aC as StoredRepositorySummary, ah as RepositoryUpdate, g as DeleteProgressCallback, af as RepositoryStats, O as MemoryVocabulary, U as PaginationOptions, aM as VocabularyChangeRecord, ay as StoredEntity, az as StoredEntityUpdate, an as StorageFindQuery, aA as StoredRelationship, a5 as RelationshipQueryOptions, am as StorageExploreOptions, ao as StorageNeighborhood, as as StoragePathOptions, at as StoragePathResult, aw as StorageTimelineOptions, ax as StorageTimelineResult, s as ExportChunk, J as ImportChunk, B as BulkImportOptions, d as BulkImportResult } from './portability-BHyXmv5-.cjs';
 
 /** Result returned by ensureSchema describing what actions were taken. */
 interface EnsureSchemaResult {

package/dist/index.cjs

@@ -1438,13 +1438,36 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
     unionFullLength = unionElements.length;
     const pageSlice = unionElements.slice(offset, offset + limit);
     const pageEntries = [];
+    const pageEntityIds = /* @__PURE__ */ new Set();
     for (const element of pageSlice) {
       if (element.kind === "entity") {
-        pageEntries.push(element.entry);
+        if (!pageEntityIds.has(element.entry.entity.id)) {
+          pageEntityIds.add(element.entry.entity.id);
+          pageEntries.push(element.entry);
+        }
       } else {
         pagedAllRels.push(element.rel);
       }
     }
+    if (pagedAllRels.length > 0) {
+      const entityIndex = /* @__PURE__ */ new Map();
+      for (const el of unionElements) {
+        if (el.kind === "entity" && !entityIndex.has(el.entry.entity.id)) {
+          entityIndex.set(el.entry.entity.id, el.entry);
+        }
+      }
+      for (const rel of pagedAllRels) {
+        for (const endpointId of [rel.sourceEntityId, rel.targetEntityId]) {
+          if (!pageEntityIds.has(endpointId)) {
+            const entry = entityIndex.get(endpointId);
+            if (entry) {
+              pageEntityIds.add(endpointId);
+              pageEntries.push(entry);
+            }
+          }
+        }
+      }
+    }
     paged = pageEntries;
     total = pageEntries.length + pagedAllRels.length;
   } else {
@@ -1472,13 +1495,13 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
             direction: "both",
             limit: 1e4
           });
-          const summary = { outbound: {}, inbound: {} };
+          const summary = { out: {}, in: {} };
           for (const rel of result.items) {
             if (rel.sourceEntityId === entry.entity.id) {
-              summary.outbound[rel.relationshipType] = (summary.outbound[rel.relationshipType] ?? 0) + 1;
+              summary.out[rel.relationshipType] = (summary.out[rel.relationshipType] ?? 0) + 1;
             }
             if (rel.targetEntityId === entry.entity.id) {
-              summary.inbound[rel.relationshipType] = (summary.inbound[rel.relationshipType] ?? 0) + 1;
+              summary.in[rel.relationshipType] = (summary.in[rel.relationshipType] ?? 0) + 1;
             }
           }
           return summary;
@@ -1541,7 +1564,7 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
       type: rel.relationshipType,
       sourceEntityId: rel.sourceEntityId,
       targetEntityId: rel.targetEntityId,
-      direction: "outbound",
+      direction: "out",
       properties: rel.properties
     }));
   } else if (!suppressEntities && spec.returnMode === "path") {
@@ -1556,7 +1579,7 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
             type: rel.relationshipType,
             sourceEntityId: rel.sourceEntityId,
             targetEntityId: rel.targetEntityId,
-            direction: fromId === rel.sourceEntityId ? "outbound" : "inbound",
+            direction: fromId === rel.sourceEntityId ? "out" : "in",
             properties: rel.properties
           });
         }
@@ -1595,7 +1618,7 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
           type: rel.relationshipType,
           sourceEntityId: rel.sourceEntityId,
           targetEntityId: rel.targetEntityId,
-          direction: fromId === rel.sourceEntityId ? "outbound" : "inbound",
+          direction: fromId === rel.sourceEntityId ? "out" : "in",
           properties: rel.properties
         };
       })
@@ -1624,7 +1647,7 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
   };
 }
 async function executeSingleStep(repositoryId, storage, frontier, step, onStorageCall) {
-  const direction = mapDirection(step.direction);
+  const direction = step.direction;
   const pendingEdges = [];
   for (const entry of frontier) {
     const rels = await storage.getEntityRelationships(repositoryId, entry.entity.id, {
@@ -1719,16 +1742,6 @@ async function resolveEntity(repositoryId, storage, idOrSlug) {
   if (byId) return byId;
   return storage.getEntityBySlug(repositoryId, idOrSlug);
 }
-function mapDirection(direction) {
-  switch (direction) {
-    case "out":
-      return "outbound";
-    case "in":
-      return "inbound";
-    case "both":
-      return "both";
-  }
-}
 function getTargetId(rel, currentEntityId) {
   if (rel.sourceEntityId === currentEntityId) {
     return rel.targetEntityId;
@@ -1771,6 +1784,12 @@ function buildAllModeUnion(entries) {
   }
   for (let depth = 1; depth <= maxDepth; depth++) {
     const bucket = byDepth.get(depth) ?? [];
+    for (const entry of bucket) {
+      if (!seenEntities.has(entry.entity.id)) {
+        seenEntities.add(entry.entity.id);
+        result.push({ kind: "entity", entry });
+      }
+    }
     for (const entry of bucket) {
       const newRel = entry.relationshipPath[depth - 1];
       if (newRel && !seenRels.has(newRel.id)) {
@@ -1778,12 +1797,6 @@ function buildAllModeUnion(entries) {
         result.push({ kind: "relationship", rel: newRel });
       }
     }
-    for (const entry of bucket) {
-      if (!seenEntities.has(entry.entity.id)) {
-        seenEntities.add(entry.entity.id);
-        result.push({ kind: "entity", entry });
-      }
-    }
   }
   return result;
 }
@@ -1923,7 +1936,7 @@ var GraphTraversal = class {
           return {
             id: rid,
             type: r?.type ?? "unknown",
-            direction: r?.sourceEntityId === currentEntityId ? "outbound" : "inbound",
+            direction: r?.sourceEntityId === currentEntityId ? "out" : "in",
             properties: r?.properties ?? {}
           };
         })
@@ -2550,7 +2563,7 @@ var MemoryRepository = class {
         inbound[rel.relationshipType] = (inbound[rel.relationshipType] ?? 0) + 1;
       }
     }
-    return { outbound, inbound };
+    return { out: outbound, in: inbound };
   }
   async getRelationshipsForEntities(entityIds) {
     const seen = /* @__PURE__ */ new Set();
@@ -2758,9 +2771,10 @@ var MemoryRepository = class {
 ### Step 1 \u2014 Discover before you traverse
 
 Before following relationships from an entity, check that it actually has relationships.
-Graph queries include \`relationshipSummary\` on every returned entity by default
-(outbound and inbound counts by type). Inspect this before traversing \u2014 entities with
-zero outbound counts for the relationship type you need have no connections to follow.
+Graph queries include \`relationshipSummary\` on every returned entity by default \u2014
+\`out\` (entity is source) and \`in\` (entity is target) counts by relationship type.
+Inspect this before traversing: entities with zero counts for the relationship type
+you need have no connections to follow.
 To skip summaries and reduce response size, set \`includeRelationshipSummary: false\`.
 
 ### Step 2 \u2014 Use projection for aggregation
@@ -3643,7 +3657,7 @@ var EventBus = class {
 };
 
 // src/portability/RepositoryExporter.ts
-var LIBRARY_VERSION = true ? "0.17.0" : "0.1.0";
+var LIBRARY_VERSION = true ? "0.19.0" : "0.1.0";
 var RepositoryExporter = class {
   storage;
   provenance;
@@ -3675,6 +3689,9 @@ var RepositoryExporter = class {
         type: repo.type,
         label: repo.label,
         description: repo.description,
+        legal: repo.legal,
+        owner: repo.owner,
+        metadata: repo.metadata,
         vocabularyVersion: vocabulary.version,
         governanceMode: repo.governanceConfig.mode
       },
@@ -4072,7 +4089,10 @@ var RepositoryImporter = class {
         type: target.config.type,
         label: target.config.label,
         description: target.config.description,
+        legal: target.config.legal,
+        owner: target.config.owner,
         governanceConfig: target.config.governance ?? { mode: "open" },
+        metadata: target.config.metadata,
         createdAt: now,
         createdBy: this.actorId
       });
@@ -4587,6 +4607,7 @@ var DeepMemory = class {
   /** Import a repository from a portable archive */
   async importRepository(archive, options) {
     await this.ensureInitialized();
+    this.validateRepositoryId(options.target.repositoryId);
     await this.globalEventBus.emit("import:started", { repositoryId: options.target.repositoryId });
     const importer = new RepositoryImporter({
       storage: this.storage,
@@ -4687,6 +4708,7 @@ var DeepMemory = class {
    */
   async importRepositoryStream(header, chunks, options) {
     await this.ensureInitialized();
+    this.validateRepositoryId(options.target.repositoryId);
     const importer = new RepositoryImporter({
       storage: this.storage,
       actorId: this.provenance.getContext().actorId,
@@ -4921,8 +4943,8 @@ var GremlinCompiler = class {
       const branches = [`__.identity().${VERTEX_PROJECT_EXPR}`];
       let prefix = "";
       for (const { edge, vertex, entityFilters } of compiledSteps) {
-        branches.push(`__${prefix}${edge}.${EDGE_PROJECT_EXPR}`);
         branches.push(`__${prefix}${edge}${vertex}${entityFilters}.${VERTEX_PROJECT_EXPR}`);
+        branches.push(`__${prefix}${edge}.${EDGE_PROJECT_EXPR}`);
         prefix = `${prefix}${edge}${vertex}`;
         estimatedFanOut *= DEFAULT_ESTIMATED_FANOUT_PER_HOP;
       }
@@ -4958,12 +4980,16 @@ var GremlinCompiler = class {
           }
         }
       }
-      if (returnMode === "terminal" && spec.dedup !== false) {
+      const emitProjection = spec.projection !== void 0 && returnMode === "terminal";
+      if (returnMode === "terminal" && !emitProjection && spec.dedup !== false) {
         parts.push(".dedup()");
       }
       if (returnMode === "path") {
         parts.push(".simplePath()");
       }
+      if (emitProjection) {
+        parts.push(emitProjectionTerminal(spec.projection));
+      }
       const limit = spec.limit ?? 50;
       const offset = spec.offset ?? 0;
       const pOffset = nextParam(offset);
@@ -4971,7 +4997,8 @@ var GremlinCompiler = class {
       parts.push(`.range(${pOffset}, ${pEnd})`);
       params["_limit"] = limit;
       params["_offset"] = offset;
-      if (returnMode === "terminal") {
+      if (emitProjection) {
+      } else if (returnMode === "terminal") {
         parts.push(`.${VERTEX_PROJECT_EXPR}`);
       } else {
         parts.push(`.path().by(${VERTEX_PROJECT_EXPR}).by(${EDGE_PROJECT_EXPR})`);
@@ -5067,6 +5094,31 @@ function compileRepeatStep(step, nextParam, useEdgeEmission) {
   }
   return parts.join("");
 }
+var SAFE_PROJECTION_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertSafeProjectionKey(key) {
+  if (!SAFE_PROJECTION_KEY_RE.test(key)) {
+    throw new Error(
+      `Unsafe projection property name: "${key}". Property names must match ${SAFE_PROJECTION_KEY_RE.source}.`
+    );
+  }
+}
+function emitProjectionTerminal(projection) {
+  const properties = projection.properties;
+  const mode = projection.mode ?? "values";
+  const distinct = projection.distinct ?? false;
+  for (const prop of properties) {
+    assertSafeProjectionKey(prop);
+  }
+  const singleProperty = properties.length === 1;
+  const keyExpr = singleProperty ? `values('${properties[0]}')` : `project(${properties.map((p) => `'${p}'`).join(",")})${properties.map((p) => `.by(values('${p}'))`).join("")}`;
+  if (mode === "count") {
+    return `.group().by(${keyExpr}).by(count()).unfold()`;
+  }
+  if (distinct) {
+    return `.${keyExpr}.dedup()`;
+  }
+  return `.${keyExpr}`;
+}
 function compilePropertyFilter(filter, nextParam) {
   const key = nextParam(filter.key);
   switch (filter.operator) {
@@ -5176,17 +5228,35 @@ var CypherCompiler = class {
       }
       lastNode = targetNode;
     }
-    const matchClause = `MATCH ${matchParts[0]}${matchParts.slice(1).join("")}`;
+    const bindPath = spec.returnMode === "path";
+    const pathBinding = bindPath ? "p = " : "";
+    const matchClause = `MATCH ${pathBinding}${matchParts[0]}${matchParts.slice(1).join("")}`;
     const whereClause = whereClauses.length > 0 ? `
 WHERE ${whereClauses.join(" AND ")}` : "";
     let returnClause;
-    if (spec.returnMode === "path") {
-      const allNodes = Array.from({ length: nodeIndex }, (_, i) => `n${i}`);
-      const allRels = steps.map((_, i) => `r${i}`);
-      returnClause = `RETURN ${[...allNodes, ...allRels].join(", ")}`;
+    const emitProjection = spec.projection !== void 0 && spec.returnMode !== "path" && spec.returnMode !== "all";
+    if (emitProjection) {
+      const projection = spec.projection;
+      const mode = projection.mode ?? "values";
+      const distinct = projection.distinct ?? false;
+      const projectionColumns = projection.properties.map((prop) => {
+        assertSafeProjectionKey2(prop);
+        return `${lastNode}.${prop} AS ${prop}`;
+      });
+      if (mode === "count") {
+        returnClause = `RETURN ${projectionColumns.join(", ")}, count(*) AS count`;
+      } else if (distinct) {
+        returnClause = `RETURN DISTINCT ${projectionColumns.join(", ")}`;
+      } else {
+        returnClause = `RETURN ${projectionColumns.join(", ")}`;
+      }
+    } else if (spec.returnMode === "path") {
+      returnClause = "RETURN nodes(p) AS pathNodes, relationships(p) AS pathRels, length(p) AS pathLength";
     } else if (spec.returnMode === "all") {
       const allNodes = Array.from({ length: nodeIndex }, (_, i) => `n${i}`);
-      returnClause = spec.dedup !== false ? `RETURN DISTINCT ${allNodes.join(", ")}` : `RETURN ${allNodes.join(", ")}`;
+      const allRels = steps.map((_, i) => `r${i}`);
+      const projection = [...allNodes, ...allRels].join(", ");
+      returnClause = spec.dedup !== false ? `RETURN DISTINCT ${projection}` : `RETURN ${projection}`;
     } else {
       returnClause = spec.dedup !== false ? `RETURN DISTINCT ${lastNode}` : `RETURN ${lastNode}`;
     }
@@ -5207,6 +5277,14 @@ ${returnClause}${skipClause}${limitClause}`;
     };
   }
 };
+var SAFE_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertSafeProjectionKey2(key) {
+  if (!SAFE_KEY_RE.test(key)) {
+    throw new Error(
+      `Unsafe projection property name: "${key}". Property names must match ${SAFE_KEY_RE.source}.`
+    );
+  }
+}
 function compilePropertyFilterCypher(nodeAlias, filter, nextParam) {
   const prop = `${nodeAlias}.${filter.key}`;
   switch (filter.operator) {
@@ -5517,9 +5595,9 @@ var InMemoryStorageProvider = class {
       const isTarget = rel.targetEntityId === entityId;
       const isBidirectionalTarget = rel.bidirectional && isTarget;
       switch (direction) {
-        case "outbound":
+        case "out":
           return isSource || isBidirectionalTarget;
-        case "inbound":
+        case "in":
           return isTarget || rel.bidirectional && isSource;
         case "both":
         default:
@@ -5611,23 +5689,24 @@ var InMemoryStorageProvider = class {
     for (let depth = 0; depth < options.depth; depth++) {
       const layer = {};
       const nextFrontier = /* @__PURE__ */ new Set();
+      const layerBucketSeen = /* @__PURE__ */ new Map();
       for (const frontierEntityId of currentFrontier) {
         for (const rel of store.relationships.values()) {
           const isSource = rel.sourceEntityId === frontierEntityId;
           const isTarget = rel.targetEntityId === frontierEntityId;
           let matchesDirection = false;
           let connectedEntityId;
-          if (isSource && (options.direction === "outbound" || options.direction === "both")) {
+          if (isSource && (options.direction === "out" || options.direction === "both")) {
             matchesDirection = true;
             connectedEntityId = rel.targetEntityId;
-          } else if (isTarget && (options.direction === "inbound" || options.direction === "both")) {
+          } else if (isTarget && (options.direction === "in" || options.direction === "both")) {
             matchesDirection = true;
             connectedEntityId = rel.sourceEntityId;
           } else if (rel.bidirectional) {
-            if (isSource && options.direction === "inbound") {
+            if (isSource && options.direction === "in") {
               matchesDirection = true;
               connectedEntityId = rel.targetEntityId;
-            } else if (isTarget && options.direction === "outbound") {
+            } else if (isTarget && options.direction === "out") {
               matchesDirection = true;
               connectedEntityId = rel.sourceEntityId;
             }
@@ -5648,6 +5727,13 @@ var InMemoryStorageProvider = class {
             continue;
           }
           const relType = rel.relationshipType;
+          let bucketSeen = layerBucketSeen.get(relType);
+          if (!bucketSeen) {
+            bucketSeen = /* @__PURE__ */ new Set();
+            layerBucketSeen.set(relType, bucketSeen);
+          }
+          if (bucketSeen.has(connectedEntityId)) continue;
+          bucketSeen.add(connectedEntityId);
           if (!layer[relType]) {
             layer[relType] = { total: 0, entities: [], relationships: [] };
           }