@utaba/deep-memory 0.16.0 → 0.18.0

package/dist/index.cjs

@@ -29,6 +29,8 @@ __export(src_exports, {
   EmbeddingProviderRequiredError: () => EmbeddingProviderRequiredError,
   EntityNotFoundError: () => EntityNotFoundError,
   ExportError: () => ExportError,
+  GREMLIN_EDGE_PROJECTION_FIELDS: () => GREMLIN_EDGE_PROJECTION_FIELDS,
+  GREMLIN_VERTEX_PROJECTION_FIELDS: () => GREMLIN_VERTEX_PROJECTION_FIELDS,
   GovernanceDeniedError: () => GovernanceDeniedError,
   GraphTraversalProviderRequiredError: () => GraphTraversalProviderRequiredError,
   GremlinCompiler: () => GremlinCompiler,
@@ -50,7 +52,10 @@ __export(src_exports, {
   TraversalTimeoutError: () => TraversalTimeoutError,
   TraversalValidationError: () => TraversalValidationError,
   TraversalVocabularyError: () => TraversalVocabularyError,
+  UnsupportedQueryError: () => UnsupportedQueryError,
   VocabularyValidationError: () => VocabularyValidationError,
+  buildEdgeProjectChain: () => buildEdgeProjectChain,
+  buildVertexProjectChain: () => buildVertexProjectChain,
   createSafeSink: () => createSafeSink,
   generateId: () => generateId,
   isValidUuid: () => isValidUuid,
@@ -341,6 +346,14 @@ var TraversalTimeoutError = class extends DeepMemoryError {
     this.timeoutMs = timeoutMs;
   }
 };
+var UnsupportedQueryError = class extends DeepMemoryError {
+  provider;
+  constructor(provider, message, suggestion) {
+    super("UNSUPPORTED_QUERY", message, suggestion);
+    this.name = "UnsupportedQueryError";
+    this.provider = provider;
+  }
+};
 
 // src/core/DeepMemory.ts
 var import_node_crypto = require("crypto");
@@ -959,7 +972,7 @@ var EntityManager = class {
     let totalFailed = 0;
     const allErrors = [];
     let offset = 0;
-    while (offset < total) {
+    while (total === void 0 || offset < total) {
       if (signal?.aborted) {
         throw new OperationAbortedError("reembedAll");
       }
@@ -986,7 +999,8 @@ var EntityManager = class {
         throw new OperationAbortedError("reembedAll");
       }
       const delayMs = options?.delayBetweenBatchesMs ?? 0;
-      if (delayMs > 0 && offset < total) {
+      const moreLikely = total === void 0 ? page.items.length === batchSize : offset < total;
+      if (delayMs > 0 && moreLikely) {
         await new Promise((resolve) => {
           setTimeout(resolve, delayMs);
         });
@@ -1415,22 +1429,52 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
   const dedup = spec.dedup !== false;
   const limit = spec.limit ?? 50;
   const offset = spec.offset ?? 0;
-  let resultEntries;
+  let paged;
+  let pagedAllRels = [];
+  let total;
+  let unionFullLength = 0;
   if (spec.returnMode === "all") {
-    resultEntries = allCollected;
+    const unionElements = buildAllModeUnion(allCollected);
+    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") {
+        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 {
-    resultEntries = frontier;
-  }
-  if (dedup) {
-    const seen = /* @__PURE__ */ new Set();
-    resultEntries = resultEntries.filter((entry) => {
-      if (seen.has(entry.entity.id)) return false;
-      seen.add(entry.entity.id);
-      return true;
-    });
+    const resultEntries = dedup && spec.returnMode !== "path" ? dedupEntriesById(frontier) : frontier;
+    total = resultEntries.length;
+    paged = resultEntries.slice(offset, offset + limit);
   }
-  const total = resultEntries.length;
-  const paged = resultEntries.slice(offset, offset + limit);
   const suppressEntities = spec.projection !== void 0 && spec.projection.includeEntities !== true;
   let entities;
   if (suppressEntities) {
@@ -1451,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;
@@ -1471,7 +1515,8 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
     const propNames = spec.projection.properties;
     const mode = spec.projection.mode ?? "values";
     const distinct = spec.projection.distinct ?? false;
-    const sourceEntries = dedup ? (() => {
+    const aggregateDedup = spec.returnMode === "all" || dedup && spec.returnMode !== "path";
+    const sourceEntries = aggregateDedup ? (() => {
       const seen = /* @__PURE__ */ new Set();
       return (spec.returnMode === "all" ? allCollected : frontier).filter((e) => {
         if (seen.has(e.entity.id)) return false;
@@ -1513,17 +1558,28 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
   }
   let relationships;
   let paths;
-  if (!suppressEntities && (spec.returnMode === "path" || spec.returnMode === "all")) {
+  if (!suppressEntities && spec.returnMode === "all") {
+    relationships = pagedAllRels.map((rel) => ({
+      id: rel.id,
+      type: rel.relationshipType,
+      sourceEntityId: rel.sourceEntityId,
+      targetEntityId: rel.targetEntityId,
+      direction: "out",
+      properties: rel.properties
+    }));
+  } else if (!suppressEntities && spec.returnMode === "path") {
     const relMap = /* @__PURE__ */ new Map();
     for (const entry of paged) {
-      for (const rel of entry.relationshipPath) {
+      for (let i = 0; i < entry.relationshipPath.length; i++) {
+        const rel = entry.relationshipPath[i];
         if (!relMap.has(rel.id)) {
+          const fromId = entry.entityPath[i];
           relMap.set(rel.id, {
             id: rel.id,
             type: rel.relationshipType,
             sourceEntityId: rel.sourceEntityId,
             targetEntityId: rel.targetEntityId,
-            direction: "outbound",
+            direction: fromId === rel.sourceEntityId ? "out" : "in",
             properties: rel.properties
           });
         }
@@ -1532,44 +1588,66 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
     relationships = Array.from(relMap.values());
   }
   if (!suppressEntities && spec.returnMode === "path") {
+    const pathEntityIds = /* @__PURE__ */ new Set();
+    for (const entry of paged) {
+      for (const id of entry.entityPath) {
+        pathEntityIds.add(id);
+      }
+    }
+    const pathEntityMap = pathEntityIds.size > 0 ? await storage.getEntities(repositoryId, [...pathEntityIds]) : /* @__PURE__ */ new Map();
+    if (pathEntityIds.size > 0) {
+      storageCalls++;
+    }
     paths = paged.map((entry) => ({
       length: entry.entityPath.length - 1,
-      entities: [(() => {
-        const e = projectEntity(entry.entity, detailLevel);
-        if (!spec.includeProvenance) delete e["provenance"];
-        return e;
-      })()],
-      relationships: entry.relationshipPath.map((rel) => ({
-        id: rel.id,
-        type: rel.relationshipType,
-        sourceEntityId: rel.sourceEntityId,
-        targetEntityId: rel.targetEntityId,
-        direction: "outbound",
-        properties: rel.properties
-      }))
+      entities: entry.entityPath.map((id) => {
+        const stored = pathEntityMap.get(id);
+        if (!stored) {
+          throw new EntityNotFoundError(id);
+        }
+        const projected = projectEntity(stored, detailLevel);
+        if (!spec.includeProvenance) {
+          delete projected["provenance"];
+        }
+        return projected;
+      }),
+      relationships: entry.relationshipPath.map((rel, i) => {
+        const fromId = entry.entityPath[i];
+        return {
+          id: rel.id,
+          type: rel.relationshipType,
+          sourceEntityId: rel.sourceEntityId,
+          targetEntityId: rel.targetEntityId,
+          direction: fromId === rel.sourceEntityId ? "out" : "in",
+          properties: rel.properties
+        };
+      })
     }));
   }
   const executionTimeMs = Date.now() - startTime;
+  const returned = spec.returnMode === "all" ? total : paged.length;
+  const hasMore = spec.returnMode === "all" ? offset + limit < unionFullLength : offset + limit < total;
+  const truncated = spec.returnMode === "all" ? unionFullLength > limit + offset : total > limit + offset;
   return {
     entities,
     relationships,
     paths,
     aggregations,
     total,
-    returned: paged.length,
-    hasMore: offset + limit < total,
+    returned,
+    hasMore,
     queryMetadata: {
       executionTimeMs,
       appliedLimits: {
         maxResults: limit
       },
-      truncated: total > limit + offset,
-      truncationReason: total > limit + offset ? "result_limit" : void 0
+      truncated,
+      truncationReason: truncated ? "result_limit" : void 0
     }
   };
 }
 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, {
@@ -1664,22 +1742,64 @@ 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;
   }
   return rel.sourceEntityId;
 }
+function dedupEntriesById(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const entry of entries) {
+    if (!seen.has(entry.entity.id)) {
+      seen.add(entry.entity.id);
+      result.push(entry);
+    }
+  }
+  return result;
+}
+function buildAllModeUnion(entries) {
+  if (entries.length === 0) return [];
+  let maxDepth = 0;
+  const byDepth = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const depth = entry.relationshipPath.length;
+    if (depth > maxDepth) maxDepth = depth;
+    let bucket = byDepth.get(depth);
+    if (!bucket) {
+      bucket = [];
+      byDepth.set(depth, bucket);
+    }
+    bucket.push(entry);
+  }
+  const seenEntities = /* @__PURE__ */ new Set();
+  const seenRels = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const entry of byDepth.get(0) ?? []) {
+    if (!seenEntities.has(entry.entity.id)) {
+      seenEntities.add(entry.entity.id);
+      result.push({ kind: "entity", entry });
+    }
+  }
+  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)) {
+        seenRels.add(newRel.id);
+        result.push({ kind: "relationship", rel: newRel });
+      }
+    }
+  }
+  return result;
+}
 
 // src/relationships/GraphTraversal.ts
 var GraphTraversal = class {
@@ -1816,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 ?? {}
           };
         })
@@ -1940,11 +2060,15 @@ var SearchOrchestrator = class {
     const offset = options?.offset ?? 0;
     const threshold = options?.similarityThreshold ?? this.defaultSimilarityThreshold;
     const queryEmbedding = await this.embedding.embed(query);
-    const allEntities = await this.storage.findEntities(this.repositoryId, {
-      entityTypes: options?.entityTypes,
-      limit: this.conceptSearchScanLimit,
-      offset: 0
-    });
+    const allEntities = await this.storage.findEntities(
+      this.repositoryId,
+      {
+        entityTypes: options?.entityTypes,
+        limit: this.conceptSearchScanLimit,
+        offset: 0
+      },
+      { loadEmbeddings: true }
+    );
     const scored = [];
     for (const entity of allEntities.items) {
       let score;
@@ -2439,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();
@@ -2647,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
@@ -3327,7 +3452,14 @@ var VocabularyEngine = class {
   async proposeExtension(proposal, proposedBy) {
     return this.proposeChange(proposal, proposedBy);
   }
-  /** Cascade-delete all data for a deleted vocabulary type */
+  /**
+   * Cascade-delete all data for a deleted vocabulary type.
+   *
+   * `deletedRelationships` may be `undefined` when the underlying provider
+   * does not count cascaded edges (see StorageProvider.deleteEntitiesByType).
+   * The return value is currently discarded by the only caller; the type is
+   * preserved for symmetry with the storage contract.
+   */
   async cascadeDeleteData(proposal) {
     if (proposal.proposalType === "delete_entity_type" && proposal.deleteEntityType) {
       return this.storage.deleteEntitiesByType(
@@ -3525,7 +3657,7 @@ var EventBus = class {
 };
 
 // src/portability/RepositoryExporter.ts
-var LIBRARY_VERSION = true ? "0.16.0" : "0.1.0";
+var LIBRARY_VERSION = true ? "0.18.0" : "0.1.0";
 var RepositoryExporter = class {
   storage;
   provenance;
@@ -4628,10 +4760,15 @@ var DeepMemory = class {
     try {
       const result = await repo.reembedAll({
         ...options,
+        // The repo signature widens `totalEntities` to `number | undefined`
+        // because PaginatedResult.total may be undefined under some provider/
+        // query combinations. The `reembed:progress` event contract is
+        // `totalEntities: number`, so fall back to the cached stats count
+        // when the inner layer doesn't supply one.
         onProgress: (progress) => this.globalEventBus.emit("reembed:progress", {
           repositoryId,
           processed: progress.processed,
-          totalEntities: progress.totalEntities,
+          totalEntities: progress.totalEntities ?? stats.entityCount,
           failed: progress.failed
         }),
         onItemFailed: (failure) => this.globalEventBus.emit("reembed:item-failed", {
@@ -4690,6 +4827,69 @@ function createSafeSink(sink) {
 
 // src/relationships/compilers/GremlinCompiler.ts
 var DEFAULT_ESTIMATED_FANOUT_PER_HOP = 10;
+var VERTEX_PROJECTION = [
+  ["__kind", `.by(constant('v'))`],
+  ["id", `.by(id)`],
+  ["entityType", `.by('entityType')`],
+  ["entityLabel", `.by('entityLabel')`],
+  ["slug", `.by('slug')`],
+  ["summary", `.by(coalesce(values('summary'), constant('')))`],
+  ["properties", `.by(coalesce(values('properties'), constant('{}')))`],
+  ["data", `.by(coalesce(values('data'), constant('')))`],
+  ["dataFormat", `.by(coalesce(values('dataFormat'), constant('')))`],
+  ["createdBy", `.by('createdBy')`],
+  ["createdByType", `.by('createdByType')`],
+  ["createdAt", `.by('createdAt')`],
+  ["createdInConversation", `.by(coalesce(values('createdInConversation'), constant('')))`],
+  ["createdFromMessage", `.by(coalesce(values('createdFromMessage'), constant('')))`],
+  ["modifiedBy", `.by('modifiedBy')`],
+  ["modifiedByType", `.by('modifiedByType')`],
+  ["modifiedAt", `.by('modifiedAt')`],
+  ["modifiedInConversation", `.by(coalesce(values('modifiedInConversation'), constant('')))`],
+  ["modifiedFromMessage", `.by(coalesce(values('modifiedFromMessage'), constant('')))`]
+];
+var EDGE_PROJECTION = [
+  ["__kind", `.by(constant('e'))`],
+  ["id", `.by(id)`],
+  ["relationshipType", `.by('relationshipType')`],
+  ["sourceEntityId", `.by('sourceEntityId')`],
+  ["targetEntityId", `.by('targetEntityId')`],
+  ["properties", `.by(coalesce(values('properties'), constant('{}')))`],
+  ["bidirectional", `.by(coalesce(values('bidirectional'), constant(false)))`],
+  ["createdBy", `.by('createdBy')`],
+  ["createdByType", `.by('createdByType')`],
+  ["createdAt", `.by('createdAt')`],
+  ["createdInConversation", `.by(coalesce(values('createdInConversation'), constant('')))`],
+  ["createdFromMessage", `.by(coalesce(values('createdFromMessage'), constant('')))`],
+  ["modifiedBy", `.by('modifiedBy')`],
+  ["modifiedByType", `.by('modifiedByType')`],
+  ["modifiedAt", `.by('modifiedAt')`],
+  ["modifiedInConversation", `.by(coalesce(values('modifiedInConversation'), constant('')))`],
+  ["modifiedFromMessage", `.by(coalesce(values('modifiedFromMessage'), constant('')))`]
+];
+var EMBEDDING_PROJECTION_ENTRY = [
+  "embedding",
+  `.by(coalesce(values('embedding'), constant('')))`
+];
+function buildProjectExpression(entries) {
+  const keys = entries.map(([k]) => `'${k}'`).join(",");
+  const bys = entries.map(([, by]) => by).join("");
+  return `project(${keys})${bys}`;
+}
+var VERTEX_PROJECT_EXPR = buildProjectExpression(VERTEX_PROJECTION);
+var VERTEX_PROJECT_EXPR_WITH_EMBEDDING = buildProjectExpression([
+  ...VERTEX_PROJECTION,
+  EMBEDDING_PROJECTION_ENTRY
+]);
+var EDGE_PROJECT_EXPR = buildProjectExpression(EDGE_PROJECTION);
+var GREMLIN_VERTEX_PROJECTION_FIELDS = VERTEX_PROJECTION.map(([k]) => k).filter((k) => k !== "__kind");
+var GREMLIN_EDGE_PROJECTION_FIELDS = EDGE_PROJECTION.map(([k]) => k).filter((k) => k !== "__kind");
+function buildVertexProjectChain(opts) {
+  return opts?.withEmbedding ? VERTEX_PROJECT_EXPR_WITH_EMBEDDING : VERTEX_PROJECT_EXPR;
+}
+function buildEdgeProjectChain() {
+  return EDGE_PROJECT_EXPR;
+}
 var GremlinCompiler = class {
   language = "gremlin";
   compile(spec, _vocabulary) {
@@ -4705,7 +4905,7 @@ var GremlinCompiler = class {
     parts.push("g.V()");
     if (spec.start.entityId) {
       const p = nextParam(spec.start.entityId);
-      parts.push(`.has('id', ${p})`);
+      parts.push(`.hasId(${p})`);
     } else if (spec.start.entityType) {
       const p = nextParam(spec.start.entityType);
       parts.push(`.has('entityType', ${p})`);
@@ -4717,44 +4917,79 @@ var GremlinCompiler = class {
       }
     }
     const steps = spec.steps ?? [];
-    for (const step of steps) {
-      if (step.repeat) {
-        parts.push(compileRepeatStep(step, nextParam));
-        estimatedFanOut *= step.repeat.maxDepth * DEFAULT_ESTIMATED_FANOUT_PER_HOP;
-      } else if (step.relationshipFilter && step.relationshipFilter.length > 0) {
-        parts.push(compileEdgeStep(step, nextParam));
-        estimatedFanOut *= DEFAULT_ESTIMATED_FANOUT_PER_HOP;
-      } else {
-        parts.push(compileSimpleStep(step, nextParam));
-        estimatedFanOut *= DEFAULT_ESTIMATED_FANOUT_PER_HOP;
+    const returnMode = spec.returnMode ?? "terminal";
+    if (returnMode === "all") {
+      if (steps.some((s) => s.repeat)) {
+        throw new Error(
+          "GremlinCompiler: 'all' returnMode does not support repeat steps. Use 'terminal' or 'path' mode, or unroll the repeat into explicit steps."
+        );
       }
-      if (step.entityTypes && step.entityTypes.length > 0) {
-        const typeParams = step.entityTypes.map((t) => nextParam(t));
-        parts.push(`.has('entityType', within(${typeParams.join(", ")}))`);
+      const compiledSteps = steps.map((step) => ({
+        edge: compileEdgeOnly(step, nextParam),
+        vertex: compileVertexHop(step),
+        // Per plan §3: entity-type/property filters apply only on branches
+        // ending at that depth's vertex. They are NOT included in the prefix
+        // that deeper branches traverse through.
+        entityFilters: compileEntityFilters(step, nextParam)
+      }));
+      const branches = [`__.identity().${VERTEX_PROJECT_EXPR}`];
+      let prefix = "";
+      for (const { edge, vertex, entityFilters } of compiledSteps) {
+        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;
       }
-      if (step.entityFilter) {
-        for (const f of step.entityFilter) {
-          parts.push(compilePropertyFilter(f, nextParam));
+      parts.push(`.union(${branches.join(", ")})`);
+      parts.push(`.dedup().by(select('id'))`);
+      const limit = spec.limit ?? 50;
+      const offset = spec.offset ?? 0;
+      const pOffset = nextParam(offset);
+      const pEnd = nextParam(offset + limit);
+      parts.push(`.range(${pOffset}, ${pEnd})`);
+      params["_limit"] = limit;
+      params["_offset"] = offset;
+    } else {
+      const useEdgeEmission = returnMode === "path";
+      for (const step of steps) {
+        if (step.repeat) {
+          parts.push(compileRepeatStep(step, nextParam, useEdgeEmission));
+          estimatedFanOut *= step.repeat.maxDepth * DEFAULT_ESTIMATED_FANOUT_PER_HOP;
+        } else if (useEdgeEmission || step.relationshipFilter && step.relationshipFilter.length > 0) {
+          parts.push(compileEdgeStep(step, nextParam));
+          estimatedFanOut *= DEFAULT_ESTIMATED_FANOUT_PER_HOP;
+        } else {
+          parts.push(compileSimpleStep(step, nextParam));
+          estimatedFanOut *= DEFAULT_ESTIMATED_FANOUT_PER_HOP;
+        }
+        if (step.entityTypes && step.entityTypes.length > 0) {
+          const typeParams = step.entityTypes.map((t) => nextParam(t));
+          parts.push(`.has('entityType', within(${typeParams.join(", ")}))`);
+        }
+        if (step.entityFilter) {
+          for (const f of step.entityFilter) {
+            parts.push(compilePropertyFilter(f, nextParam));
+          }
         }
       }
-    }
-    if (spec.returnMode === "all") {
-    }
-    if (spec.dedup !== false) {
-      parts.push(".dedup()");
-    }
-    const limit = spec.limit ?? 50;
-    const offset = spec.offset ?? 0;
-    const pOffset = nextParam(offset);
-    const pEnd = nextParam(offset + limit);
-    parts.push(`.range(${pOffset}, ${pEnd})`);
-    params["_limit"] = limit;
-    params["_offset"] = offset;
-    if (spec.returnMode === "path") {
-      parts.push(".path()");
-    }
-    if (spec.returnMode !== "path") {
-      parts.push(".valueMap(true)");
+      if (returnMode === "terminal" && spec.dedup !== false) {
+        parts.push(".dedup()");
+      }
+      if (returnMode === "path") {
+        parts.push(".simplePath()");
+      }
+      const limit = spec.limit ?? 50;
+      const offset = spec.offset ?? 0;
+      const pOffset = nextParam(offset);
+      const pEnd = nextParam(offset + limit);
+      parts.push(`.range(${pOffset}, ${pEnd})`);
+      params["_limit"] = limit;
+      params["_offset"] = offset;
+      if (returnMode === "terminal") {
+        parts.push(`.${VERTEX_PROJECT_EXPR}`);
+      } else {
+        parts.push(`.path().by(${VERTEX_PROJECT_EXPR}).by(${EDGE_PROJECT_EXPR})`);
+      }
     }
     return {
       query: parts.join(""),
@@ -4775,7 +5010,7 @@ function compileSimpleStep(step, nextParam) {
       return types ? `.both(${typeArgs})` : ".both()";
   }
 }
-function compileEdgeStep(step, nextParam) {
+function compileEdgeOnly(step, nextParam) {
   const parts = [];
   const types = step.relationshipTypes;
   const typeArgs = types ? types.map((t) => nextParam(t)).join(", ") : "";
@@ -4795,22 +5030,37 @@ function compileEdgeStep(step, nextParam) {
       parts.push(compilePropertyFilter(f, nextParam));
     }
   }
+  return parts.join("");
+}
+function compileVertexHop(step) {
   switch (step.direction) {
     case "out":
-      parts.push(".inV()");
-      break;
+      return ".inV()";
     case "in":
-      parts.push(".outV()");
-      break;
+      return ".outV()";
     case "both":
-      parts.push(".otherV()");
-      break;
+      return ".otherV()";
+  }
+}
+function compileEntityFilters(step, nextParam) {
+  const parts = [];
+  if (step.entityTypes && step.entityTypes.length > 0) {
+    const typeParams = step.entityTypes.map((t) => nextParam(t));
+    parts.push(`.has('entityType', within(${typeParams.join(", ")}))`);
+  }
+  if (step.entityFilter) {
+    for (const f of step.entityFilter) {
+      parts.push(compilePropertyFilter(f, nextParam));
+    }
   }
   return parts.join("");
 }
-function compileRepeatStep(step, nextParam) {
+function compileEdgeStep(step, nextParam) {
+  return compileEdgeOnly(step, nextParam) + compileVertexHop(step);
+}
+function compileRepeatStep(step, nextParam, useEdgeEmission) {
   const parts = [];
-  const innerStep = step.relationshipFilter?.length ? compileEdgeStep({ ...step, repeat: void 0 }, nextParam) : compileSimpleStep(step, nextParam);
+  const innerStep = useEdgeEmission || step.relationshipFilter?.length ? compileEdgeStep({ ...step, repeat: void 0 }, nextParam) : compileSimpleStep(step, nextParam);
   if (step.repeat?.emitIntermediates !== false) {
     parts.push(".emit()");
   }
@@ -4819,10 +5069,13 @@ function compileRepeatStep(step, nextParam) {
     const untilParts = step.repeat.until.map((f) => compilePropertyFilter(f, nextParam));
     parts.push(`.until(${untilParts.join("")})`);
   }
-  if (step.repeat?.maxDepth) {
-    const p = nextParam(step.repeat.maxDepth);
-    parts.push(`.times(${p})`);
+  const n = step.repeat.maxDepth;
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(
+      `GremlinCompiler: repeat.maxDepth must be a positive integer; got ${n}`
+    );
   }
+  parts.push(`.times(${n})`);
   if (step.repeat?.emitIntermediates === false) {
     parts.push(".emit()");
   }
@@ -5141,17 +5394,20 @@ var InMemoryStorageProvider = class {
     store.slugIndex.set(entity.slug, entity.id);
     return entity;
   }
-  async getEntity(repositoryId, entityId) {
+  // The in-memory provider always carries the full entity (embedding and all).
+  // The `loadEmbeddings` option is accepted for interface symmetry but ignored —
+  // there is no light/full split to switch between when entities live in a Map.
+  async getEntity(repositoryId, entityId, _options) {
     const store = this.getStore(repositoryId);
     return store.entities.get(entityId) ?? null;
   }
-  async getEntityBySlug(repositoryId, slug) {
+  async getEntityBySlug(repositoryId, slug, _options) {
     const store = this.getStore(repositoryId);
     const id = store.slugIndex.get(slug);
     if (!id) return null;
     return store.entities.get(id) ?? null;
   }
-  async getEntities(repositoryId, entityIds) {
+  async getEntities(repositoryId, entityIds, _options) {
     const store = this.getStore(repositoryId);
     const result = /* @__PURE__ */ new Map();
     for (const id of entityIds) {
@@ -5222,7 +5478,7 @@ var InMemoryStorageProvider = class {
     }
     return { deletedEntities: entityIds.size, deletedRelationships };
   }
-  async findEntities(repositoryId, query) {
+  async findEntities(repositoryId, query, _options) {
     const store = this.getStore(repositoryId);
     let matches = Array.from(store.entities.values());
     if (query.entityTypes && query.entityTypes.length > 0) {
@@ -5275,9 +5531,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:
@@ -5375,17 +5631,17 @@ var InMemoryStorageProvider = class {
           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;
             }
@@ -5745,6 +6001,8 @@ var NoOpEmbeddingProvider = class {
   EmbeddingProviderRequiredError,
   EntityNotFoundError,
   ExportError,
+  GREMLIN_EDGE_PROJECTION_FIELDS,
+  GREMLIN_VERTEX_PROJECTION_FIELDS,
   GovernanceDeniedError,
   GraphTraversalProviderRequiredError,
   GremlinCompiler,
@@ -5766,7 +6024,10 @@ var NoOpEmbeddingProvider = class {
   TraversalTimeoutError,
   TraversalValidationError,
   TraversalVocabularyError,
+  UnsupportedQueryError,
   VocabularyValidationError,
+  buildEdgeProjectChain,
+  buildVertexProjectChain,
   createSafeSink,
   generateId,
   isValidUuid,