@utaba/deep-memory 0.15.0 → 0.17.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");
@@ -894,10 +907,15 @@ var EntityManager = class {
         attempt++;
         if (attempt > maxRetries) {
           const errorMsg = err instanceof Error ? err.message : String(err);
+          const failureMessage = `embedBatch failed after ${maxRetries} retries: ${errorMsg}`;
+          const failed = entries.map(([id]) => ({ entityId: id, error: failureMessage }));
+          for (const { entityId, error } of failed) {
+            await options?.onItemFailed?.(entityId, error);
+          }
           return {
             processed: 0,
             failed: entries.length,
-            errors: entries.map(([id]) => ({ entityId: id, error: `embedBatch failed after ${maxRetries} retries: ${errorMsg}` })),
+            errors: failed,
             modelId: this.embedding.modelId(),
             dimensions: this.embedding.dimensions()
           };
@@ -920,7 +938,9 @@ var EntityManager = class {
         });
         processed++;
       } catch (err) {
-        errors.push({ entityId: id, error: err instanceof Error ? err.message : String(err) });
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        errors.push({ entityId: id, error: errorMessage });
+        await options?.onItemFailed?.(id, errorMessage);
       }
     }
     return {
@@ -952,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");
       }
@@ -963,7 +983,8 @@ var EntityManager = class {
       if (page.items.length === 0) break;
       const ids = page.items.map((e) => e.id);
       const result = await this.reembedEntities(ids, {
-        maxRetries: options?.maxRetries
+        maxRetries: options?.maxRetries,
+        onItemFailed: options?.onItemFailed
       });
       totalProcessed += result.processed;
       totalFailed += result.failed;
@@ -978,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);
         });
@@ -1407,22 +1429,29 @@ 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 = [];
+    for (const element of pageSlice) {
+      if (element.kind === "entity") {
+        pageEntries.push(element.entry);
+      } else {
+        pagedAllRels.push(element.rel);
+      }
+    }
+    paged = pageEntries;
+    total = pageEntries.length + pagedAllRels.length;
   } else {
-    resultEntries = frontier;
+    const resultEntries = dedup && spec.returnMode !== "path" ? dedupEntriesById(frontier) : frontier;
+    total = resultEntries.length;
+    paged = resultEntries.slice(offset, offset + limit);
   }
-  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 total = resultEntries.length;
-  const paged = resultEntries.slice(offset, offset + limit);
   const suppressEntities = spec.projection !== void 0 && spec.projection.includeEntities !== true;
   let entities;
   if (suppressEntities) {
@@ -1463,7 +1492,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;
@@ -1505,17 +1535,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: "outbound",
+      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 ? "outbound" : "inbound",
             properties: rel.properties
           });
         }
@@ -1524,39 +1565,61 @@ 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 ? "outbound" : "inbound",
+          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
     }
   };
 }
@@ -1672,6 +1735,58 @@ function getTargetId(rel, currentEntityId) {
   }
   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) {
+      const newRel = entry.relationshipPath[depth - 1];
+      if (newRel && !seenRels.has(newRel.id)) {
+        seenRels.add(newRel.id);
+        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;
+}
 
 // src/relationships/GraphTraversal.ts
 var GraphTraversal = class {
@@ -1932,11 +2047,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;
@@ -2392,6 +2511,9 @@ var MemoryRepository = class {
       signal: options?.signal,
       onProgress: async (processed, total, failed) => {
         await options?.onProgress?.({ processed, totalEntities: total, failed });
+      },
+      onItemFailed: async (entityId, error) => {
+        await options?.onItemFailed?.({ entityId, error });
       }
     });
     await this.storage.updateRepository(this.repositoryId, {
@@ -3316,7 +3438,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(
@@ -3514,7 +3643,7 @@ var EventBus = class {
 };
 
 // src/portability/RepositoryExporter.ts
-var LIBRARY_VERSION = true ? "0.15.0" : "0.1.0";
+var LIBRARY_VERSION = true ? "0.17.0" : "0.1.0";
 var RepositoryExporter = class {
   storage;
   provenance;
@@ -3868,12 +3997,14 @@ var RepositoryImporter = class {
   storage;
   actorId;
   onProgress;
+  onItemFailed;
   signal;
   migrationEngine = new MigrationEngine();
   constructor(config) {
     this.storage = config.storage;
     this.actorId = config.actorId;
     this.onProgress = config.onProgress;
+    this.onItemFailed = config.onItemFailed;
     this.signal = config.signal;
   }
   throwIfAborted() {
@@ -3970,6 +4101,8 @@ var RepositoryImporter = class {
           message: `Failed to import ${e.item}: ${e.error}`,
           id: e.item
         });
+        const itemType = chunk.entities?.some((x) => x.id === e.item) ? "entity" : chunk.relationships?.some((x) => x.id === e.item) ? "relationship" : "entity";
+        await this.onItemFailed?.({ itemId: e.item, itemType, error: e.error });
       }
       await this.onProgress?.({
         repositoryId: target.repositoryId,
@@ -4106,11 +4239,13 @@ var RepositoryImporter = class {
             const targetExists = await this.storage.getEntity(repositoryId, rel.targetEntityId);
             if (!sourceExists || !targetExists) {
               relationshipsSkipped++;
+              const errorMsg = `source or target entity missing`;
               warnings.push({
                 code: "relationship_orphaned",
-                message: `Relationship "${rel.id}" skipped \u2014 source or target entity missing`,
+                message: `Relationship "${rel.id}" skipped \u2014 ${errorMsg}`,
                 relationshipId: rel.id
               });
+              await this.onItemFailed?.({ itemId: rel.id, itemType: "relationship", error: errorMsg });
             } else {
               try {
                 await this.storage.createRelationship(repositoryId, rel);
@@ -4457,6 +4592,12 @@ var DeepMemory = class {
       storage: this.storage,
       actorId: this.provenance.getContext().actorId,
       onProgress: (progress) => this.globalEventBus.emit("import:progress", progress),
+      onItemFailed: (failure) => this.globalEventBus.emit("import:item-failed", {
+        repositoryId: options.target.repositoryId,
+        itemId: failure.itemId,
+        itemType: failure.itemType,
+        error: failure.error
+      }),
       signal: options.signal
     });
     try {
@@ -4550,6 +4691,12 @@ var DeepMemory = class {
       storage: this.storage,
       actorId: this.provenance.getContext().actorId,
       onProgress: (progress) => this.globalEventBus.emit("import:progress", progress),
+      onItemFailed: (failure) => this.globalEventBus.emit("import:item-failed", {
+        repositoryId: options.target.repositoryId,
+        itemId: failure.itemId,
+        itemType: failure.itemType,
+        error: failure.error
+      }),
       signal: options.signal
     });
     await this.globalEventBus.emit("import:started", { repositoryId: options.target.repositoryId });
@@ -4599,11 +4746,21 @@ 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", {
+          repositoryId,
+          entityId: failure.entityId,
+          error: failure.error
         })
       });
       await this.globalEventBus.emit("reembed:completed", {
@@ -4656,6 +4813,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) {
@@ -4671,7 +4891,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})`);
@@ -4683,44 +4903,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}.${EDGE_PROJECT_EXPR}`);
+        branches.push(`__${prefix}${edge}${vertex}${entityFilters}.${VERTEX_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(""),
@@ -4741,7 +4996,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(", ") : "";
@@ -4761,22 +5016,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()");
   }
@@ -4785,10 +5055,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()");
   }
@@ -5107,17 +5380,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) {
@@ -5188,7 +5464,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) {
@@ -5711,6 +5987,8 @@ var NoOpEmbeddingProvider = class {
   EmbeddingProviderRequiredError,
   EntityNotFoundError,
   ExportError,
+  GREMLIN_EDGE_PROJECTION_FIELDS,
+  GREMLIN_VERTEX_PROJECTION_FIELDS,
   GovernanceDeniedError,
   GraphTraversalProviderRequiredError,
   GremlinCompiler,
@@ -5732,7 +6010,10 @@ var NoOpEmbeddingProvider = class {
   TraversalTimeoutError,
   TraversalValidationError,
   TraversalVocabularyError,
+  UnsupportedQueryError,
   VocabularyValidationError,
+  buildEdgeProjectChain,
+  buildVertexProjectChain,
   createSafeSink,
   generateId,
   isValidUuid,