@utaba/deep-memory 0.1.0 → 0.2.0

package/dist/index.js

@@ -191,6 +191,52 @@ var ProviderError = class extends DeepMemoryError {
     this.name = "ProviderError";
   }
 };
+var GraphTraversalProviderRequiredError = class extends DeepMemoryError {
+  constructor() {
+    super(
+      "GRAPH_TRAVERSAL_PROVIDER_REQUIRED",
+      "GraphTraversalProvider required: no graph traversal provider is configured",
+      `Provide a GraphTraversalProvider in the DeepMemory config to use native graph queries. Structured traversals via traverse() work without a provider using fallback BFS.`
+    );
+    this.name = "GraphTraversalProviderRequiredError";
+  }
+};
+var TraversalValidationError = class extends DeepMemoryError {
+  errors;
+  constructor(errors) {
+    super(
+      "TRAVERSAL_VALIDATION_FAILED",
+      `Traversal validation failed: ${errors.join("; ")}`,
+      `Check the TraversalSpec structure. Each spec needs a start (entityId, entityType, or filter), at least one step, and a returnMode.`
+    );
+    this.name = "TraversalValidationError";
+    this.errors = errors;
+  }
+};
+var TraversalVocabularyError = class extends DeepMemoryError {
+  unknownTypes;
+  constructor(unknownTypes) {
+    super(
+      "TRAVERSAL_VOCABULARY_ERROR",
+      `Traversal references unknown types: ${unknownTypes.join(", ")}`,
+      `Use getVocabulary() to see valid entity and relationship types for this repository.`
+    );
+    this.name = "TraversalVocabularyError";
+    this.unknownTypes = unknownTypes;
+  }
+};
+var TraversalTimeoutError = class extends DeepMemoryError {
+  timeoutMs;
+  constructor(timeoutMs) {
+    super(
+      "TRAVERSAL_TIMEOUT",
+      `Traversal timed out after ${timeoutMs}ms`,
+      `Try reducing the traversal depth, adding more specific filters, or increasing the timeout on your GraphTraversalProvider.`
+    );
+    this.name = "TraversalTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
 
 // src/entities/IdGenerator.ts
 function slugify(text) {
@@ -231,50 +277,54 @@ var EntityManager = class {
     this.storage = storage;
     this.embedding = embedding;
   }
-  /** Create a new entity with vocabulary validation, ID generation, provenance, and events */
-  async create(input) {
-    const validation = await this.vocabularyEngine.validateEntity(input);
-    if (!validation.valid) {
-      const errorMsg = validation.errors.map((e) => e.message).join("; ");
-      const suggestions = validation.errors.filter((e) => e.suggestion).map((e) => e.suggestion);
-      await this.eventBus.emit("validation:failed", {
-        operation: "createEntity",
-        error: errorMsg,
-        suggestions
-      });
-      throw new VocabularyValidationError(validation.errors);
-    }
-    const hookResult = await this.eventBus.emitHook("entity:creating", { input });
-    if (hookResult.cancelled) {
-      throw new OperationCancelledError("Entity creation", hookResult.reason ?? "cancelled by hook");
-    }
-    const id = input.id ?? generateEntityId();
-    const slug = await generateUniqueSlug(
-      input.entityType,
-      input.label,
-      async (candidateSlug) => {
-        const existing = await this.storage.getEntityBySlug(this.repositoryId, candidateSlug);
-        return existing !== null;
+  /** Create one or more entities with vocabulary validation, ID generation, provenance, and events */
+  async create(inputs) {
+    const results = [];
+    for (const input of inputs) {
+      const validation = await this.vocabularyEngine.validateEntity(input);
+      if (!validation.valid) {
+        const errorMsg = validation.errors.map((e) => e.message).join("; ");
+        const suggestions = validation.errors.filter((e) => e.suggestion).map((e) => e.suggestion);
+        await this.eventBus.emit("validation:failed", {
+          operation: "createEntity",
+          error: errorMsg,
+          suggestions
+        });
+        throw new VocabularyValidationError(validation.errors);
       }
-    );
-    const provenance = this.provenanceTracker.stampCreate();
-    const entityEmbedding = await this.generateEmbedding(input.label, input.summary);
-    const storedEntity = {
-      id,
-      slug,
-      entityType: input.entityType,
-      label: input.label,
-      summary: input.summary,
-      properties: input.properties ?? {},
-      data: input.data,
-      dataFormat: input.dataFormat,
-      provenance,
-      embedding: entityEmbedding
-    };
-    const created = await this.storage.createEntity(this.repositoryId, storedEntity);
-    const entity = storedToEntity(created);
-    await this.eventBus.emit("entity:created", { entity });
-    return entity;
+      const hookResult = await this.eventBus.emitHook("entity:creating", { input });
+      if (hookResult.cancelled) {
+        throw new OperationCancelledError("Entity creation", hookResult.reason ?? "cancelled by hook");
+      }
+      const id = input.id ?? generateEntityId();
+      const slug = await generateUniqueSlug(
+        input.entityType,
+        input.label,
+        async (candidateSlug) => {
+          const existing = await this.storage.getEntityBySlug(this.repositoryId, candidateSlug);
+          return existing !== null;
+        }
+      );
+      const provenance = this.provenanceTracker.stampCreate();
+      const entityEmbedding = await this.generateEmbedding(input.label, input.summary);
+      const storedEntity = {
+        id,
+        slug,
+        entityType: input.entityType,
+        label: input.label,
+        summary: input.summary,
+        properties: input.properties ?? {},
+        data: input.data,
+        dataFormat: input.dataFormat,
+        provenance,
+        embedding: entityEmbedding
+      };
+      const created = await this.storage.createEntity(this.repositoryId, storedEntity);
+      const entity = storedToEntity(created);
+      await this.eventBus.emit("entity:created", { entity });
+      results.push(entity);
+    }
+    return results;
   }
   /** Update an existing entity */
   async update(entityId, updates) {
@@ -606,55 +656,59 @@ var RelationshipManager = class {
     this.eventBus = eventBus;
     this.storage = storage;
   }
-  /** Create a relationship with vocabulary validation, provenance, and events */
-  async create(input) {
-    const sourceEntity = await this.storage.getEntity(this.repositoryId, input.sourceEntityId);
-    if (!sourceEntity) {
-      throw new EntityNotFoundError(input.sourceEntityId);
-    }
-    const targetEntity = await this.storage.getEntity(this.repositoryId, input.targetEntityId);
-    if (!targetEntity) {
-      throw new EntityNotFoundError(input.targetEntityId);
-    }
-    const validation = await this.vocabularyEngine.validateRelationship(
-      input,
-      sourceEntity.entityType,
-      targetEntity.entityType
-    );
-    if (!validation.valid) {
-      await this.eventBus.emit("validation:failed", {
-        operation: "createRelationship",
-        error: validation.errors.map((e) => e.message).join("; "),
-        suggestions: validation.errors.filter((e) => e.suggestion).map((e) => e.suggestion)
-      });
-      throw new VocabularyValidationError(validation.errors);
-    }
-    const hookResult = await this.eventBus.emitHook("relationship:creating", { input });
-    if (hookResult.cancelled) {
-      throw new OperationCancelledError(
-        "Relationship creation",
-        hookResult.reason ?? "cancelled by hook"
+  /** Create one or more relationships with vocabulary validation, provenance, and events */
+  async create(inputs) {
+    const results = [];
+    for (const input of inputs) {
+      const sourceEntity = await this.storage.getEntity(this.repositoryId, input.sourceEntityId);
+      if (!sourceEntity) {
+        throw new EntityNotFoundError(input.sourceEntityId);
+      }
+      const targetEntity = await this.storage.getEntity(this.repositoryId, input.targetEntityId);
+      if (!targetEntity) {
+        throw new EntityNotFoundError(input.targetEntityId);
+      }
+      const validation = await this.vocabularyEngine.validateRelationship(
+        input,
+        sourceEntity.entityType,
+        targetEntity.entityType
       );
+      if (!validation.valid) {
+        await this.eventBus.emit("validation:failed", {
+          operation: "createRelationship",
+          error: validation.errors.map((e) => e.message).join("; "),
+          suggestions: validation.errors.filter((e) => e.suggestion).map((e) => e.suggestion)
+        });
+        throw new VocabularyValidationError(validation.errors);
+      }
+      const hookResult = await this.eventBus.emitHook("relationship:creating", { input });
+      if (hookResult.cancelled) {
+        throw new OperationCancelledError(
+          "Relationship creation",
+          hookResult.reason ?? "cancelled by hook"
+        );
+      }
+      const normalizedType = toScreamingSnakeCase(input.relationshipType);
+      const vocabulary = await this.vocabularyEngine.getVocabulary();
+      const relType = vocabulary.relationshipTypes.find((rt) => rt.type === normalizedType);
+      const bidirectional = relType?.bidirectional ?? false;
+      const id = input.id ?? generateRelationshipId();
+      const provenance = this.provenanceTracker.stampCreate();
+      const storedRelationship = {
+        id,
+        relationshipType: normalizedType,
+        sourceEntityId: input.sourceEntityId,
+        targetEntityId: input.targetEntityId,
+        properties: input.properties ?? {},
+        bidirectional,
+        provenance
+      };
+      const created = await this.storage.createRelationship(this.repositoryId, storedRelationship);
+      const relationship = storedToRelationship(created);
+      await this.eventBus.emit("relationship:created", { relationship });
+      results.push(relationship);
     }
-    const normalizedType = toScreamingSnakeCase(input.relationshipType);
-    const vocabulary = await this.vocabularyEngine.getVocabulary();
-    const relType = vocabulary.relationshipTypes.find((rt) => rt.type === normalizedType);
-    const bidirectional = relType?.bidirectional ?? false;
-    const id = input.id ?? generateRelationshipId();
-    const provenance = this.provenanceTracker.stampCreate();
-    const storedRelationship = {
-      id,
-      relationshipType: normalizedType,
-      sourceEntityId: input.sourceEntityId,
-      targetEntityId: input.targetEntityId,
-      properties: input.properties ?? {},
-      bidirectional,
-      provenance
-    };
-    const created = await this.storage.createRelationship(this.repositoryId, storedRelationship);
-    const relationship = storedToRelationship(created);
-    await this.eventBus.emit("relationship:created", { relationship });
-    return relationship;
+    return results;
   }
   /** Remove a relationship by ID */
   async remove(relationshipId) {
@@ -735,11 +789,706 @@ function projectEntity(stored, level) {
   }
 }
 
+// src/relationships/TraversalValidator.ts
+var DEFAULT_MAX_STEPS = 6;
+var DEFAULT_MAX_LIMIT = 200;
+var DEFAULT_FALLBACK_MAX_DEPTH = 10;
+function validateTraversalSpec(spec, vocabulary, capabilities) {
+  const errors = [];
+  if (!spec.start) {
+    errors.push("start is required");
+  } else {
+    const hasEntityId = spec.start.entityId !== void 0 && spec.start.entityId !== "";
+    const hasEntityType = spec.start.entityType !== void 0 && spec.start.entityType !== "";
+    const hasFilter = spec.start.filter !== void 0 && spec.start.filter.length > 0;
+    if (!hasEntityId && !hasEntityType && !hasFilter) {
+      errors.push("start must have at least one of entityId, entityType, or filter");
+    }
+    if (hasEntityType && !hasEntityId && (spec.limit === void 0 || spec.limit === 0)) {
+      errors.push("start.entityType without entityId requires limit on the spec to prevent full type scans");
+    }
+  }
+  if (!spec.steps || spec.steps.length === 0) {
+    errors.push("steps must contain at least one step");
+  }
+  const maxSteps = capabilities?.maxTraversalDepth ?? DEFAULT_MAX_STEPS;
+  if (spec.steps && spec.steps.length > maxSteps) {
+    errors.push(`steps length ${spec.steps.length} exceeds maximum ${maxSteps}`);
+  }
+  if (spec.steps) {
+    for (let i = 0; i < spec.steps.length; i++) {
+      const step = spec.steps[i];
+      if (!step.direction || !["out", "in", "both"].includes(step.direction)) {
+        errors.push(`steps[${i}].direction must be 'out', 'in', or 'both'`);
+      }
+      if (step.repeat) {
+        if (step.repeat.maxDepth === void 0 || step.repeat.maxDepth <= 0) {
+          errors.push(`steps[${i}].repeat.maxDepth must be a positive number`);
+        }
+      }
+    }
+    const maxProviderDepth = capabilities?.maxTraversalDepth ?? DEFAULT_FALLBACK_MAX_DEPTH;
+    let totalDepth = 0;
+    for (const step of spec.steps) {
+      totalDepth += step.repeat ? step.repeat.maxDepth : 1;
+    }
+    if (totalDepth > maxProviderDepth) {
+      errors.push(`total potential depth ${totalDepth} exceeds provider maximum ${maxProviderDepth}`);
+    }
+  }
+  if (spec.returnMode && !["terminal", "path", "all"].includes(spec.returnMode)) {
+    errors.push(`returnMode must be 'terminal', 'path', or 'all'`);
+  }
+  if (spec.limit !== void 0) {
+    if (spec.limit < 1 || spec.limit > DEFAULT_MAX_LIMIT) {
+      errors.push(`limit must be between 1 and ${DEFAULT_MAX_LIMIT}`);
+    }
+  }
+  if (spec.offset !== void 0 && spec.offset < 0) {
+    errors.push("offset must be >= 0");
+  }
+  if (vocabulary && spec.steps) {
+    const entityTypeSet = new Set(vocabulary.entityTypes.map((et) => et.type));
+    const relationshipTypeSet = new Set(vocabulary.relationshipTypes.map((rt) => rt.type));
+    const unknownTypes = [];
+    if (spec.start?.entityType && !entityTypeSet.has(spec.start.entityType)) {
+      unknownTypes.push(`entity type "${spec.start.entityType}"`);
+    }
+    for (let i = 0; i < spec.steps.length; i++) {
+      const step = spec.steps[i];
+      if (step.relationshipTypes) {
+        for (const rt of step.relationshipTypes) {
+          if (!relationshipTypeSet.has(rt)) {
+            unknownTypes.push(`relationship type "${rt}" in steps[${i}]`);
+          }
+        }
+      }
+      if (step.entityTypes) {
+        for (const et of step.entityTypes) {
+          if (!entityTypeSet.has(et)) {
+            unknownTypes.push(`entity type "${et}" in steps[${i}]`);
+          }
+        }
+      }
+    }
+    if (unknownTypes.length > 0) {
+      errors.push(`Unknown vocabulary types: ${unknownTypes.join(", ")}`);
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+// src/relationships/compilers/GremlinCompiler.ts
+var DEFAULT_ESTIMATED_FANOUT_PER_HOP = 10;
+var GremlinCompiler = class {
+  language = "gremlin";
+  compile(spec, _vocabulary) {
+    const parts = [];
+    const params = {};
+    let paramIndex = 0;
+    let estimatedFanOut = 1;
+    const nextParam = (value) => {
+      const name = `p${paramIndex++}`;
+      params[name] = value;
+      return name;
+    };
+    parts.push("g.V()");
+    if (spec.start.entityId) {
+      const p = nextParam(spec.start.entityId);
+      parts.push(`.has('id', ${p})`);
+    } else if (spec.start.entityType) {
+      const p = nextParam(spec.start.entityType);
+      parts.push(`.has('entityType', ${p})`);
+      estimatedFanOut *= DEFAULT_ESTIMATED_FANOUT_PER_HOP;
+    }
+    if (spec.start.filter) {
+      for (const f of spec.start.filter) {
+        parts.push(compilePropertyFilter(f, nextParam));
+      }
+    }
+    for (const step of spec.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;
+      }
+      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)");
+    }
+    return {
+      query: parts.join(""),
+      params,
+      estimatedFanOut: Math.min(estimatedFanOut, 1e4)
+    };
+  }
+};
+function compileSimpleStep(step, nextParam) {
+  const types = step.relationshipTypes;
+  const typeArgs = types ? types.map((t) => nextParam(t)).join(", ") : "";
+  switch (step.direction) {
+    case "out":
+      return types ? `.out(${typeArgs})` : ".out()";
+    case "in":
+      return types ? `.in(${typeArgs})` : ".in()";
+    case "both":
+      return types ? `.both(${typeArgs})` : ".both()";
+  }
+}
+function compileEdgeStep(step, nextParam) {
+  const parts = [];
+  const types = step.relationshipTypes;
+  const typeArgs = types ? types.map((t) => nextParam(t)).join(", ") : "";
+  switch (step.direction) {
+    case "out":
+      parts.push(types ? `.outE(${typeArgs})` : ".outE()");
+      break;
+    case "in":
+      parts.push(types ? `.inE(${typeArgs})` : ".inE()");
+      break;
+    case "both":
+      parts.push(types ? `.bothE(${typeArgs})` : ".bothE()");
+      break;
+  }
+  if (step.relationshipFilter) {
+    for (const f of step.relationshipFilter) {
+      parts.push(compilePropertyFilter(f, nextParam));
+    }
+  }
+  switch (step.direction) {
+    case "out":
+      parts.push(".inV()");
+      break;
+    case "in":
+      parts.push(".outV()");
+      break;
+    case "both":
+      parts.push(".otherV()");
+      break;
+  }
+  return parts.join("");
+}
+function compileRepeatStep(step, nextParam) {
+  const parts = [];
+  const innerStep = step.relationshipFilter?.length ? compileEdgeStep({ ...step, repeat: void 0 }, nextParam) : compileSimpleStep(step, nextParam);
+  if (step.repeat?.emitIntermediates !== false) {
+    parts.push(".emit()");
+  }
+  parts.push(`.repeat(${innerStep.startsWith(".") ? `__${innerStep}` : innerStep})`);
+  if (step.repeat?.until && step.repeat.until.length > 0) {
+    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})`);
+  }
+  if (step.repeat?.emitIntermediates === false) {
+    parts.push(".emit()");
+  }
+  return parts.join("");
+}
+function compilePropertyFilter(filter, nextParam) {
+  const key = nextParam(filter.key);
+  switch (filter.operator) {
+    case "eq": {
+      const val = nextParam(filter.value);
+      return `.has(${key}, ${val})`;
+    }
+    case "neq": {
+      const val = nextParam(filter.value);
+      return `.has(${key}, neq(${val}))`;
+    }
+    case "gt": {
+      const val = nextParam(filter.value);
+      return `.has(${key}, gt(${val}))`;
+    }
+    case "gte": {
+      const val = nextParam(filter.value);
+      return `.has(${key}, gte(${val}))`;
+    }
+    case "lt": {
+      const val = nextParam(filter.value);
+      return `.has(${key}, lt(${val}))`;
+    }
+    case "lte": {
+      const val = nextParam(filter.value);
+      return `.has(${key}, lte(${val}))`;
+    }
+    case "contains": {
+      const val = nextParam(filter.value);
+      return `.has(${key}, containing(${val}))`;
+    }
+    case "isNull":
+      return `.hasNot(${key})`;
+    case "isNotNull":
+      return `.has(${key})`;
+  }
+}
+
+// src/relationships/compilers/CypherCompiler.ts
+var DEFAULT_ESTIMATED_FANOUT_PER_HOP2 = 10;
+var CypherCompiler = class {
+  language = "cypher";
+  compile(spec, _vocabulary) {
+    const params = {};
+    let paramIndex = 0;
+    let estimatedFanOut = 1;
+    const whereClauses = [];
+    let nodeIndex = 0;
+    const nextParam = (value) => {
+      const name = `p${paramIndex++}`;
+      params[name] = value;
+      return `$${name}`;
+    };
+    const startNode = `n${nodeIndex++}`;
+    let matchParts = [];
+    if (spec.start.entityId) {
+      matchParts.push(`(${startNode})`);
+      whereClauses.push(`${startNode}.id = ${nextParam(spec.start.entityId)}`);
+    } else if (spec.start.entityType) {
+      matchParts.push(`(${startNode})`);
+      whereClauses.push(`${startNode}.entityType = ${nextParam(spec.start.entityType)}`);
+      estimatedFanOut *= DEFAULT_ESTIMATED_FANOUT_PER_HOP2;
+    } else {
+      matchParts.push(`(${startNode})`);
+    }
+    if (spec.start.filter) {
+      for (const f of spec.start.filter) {
+        whereClauses.push(compilePropertyFilterCypher(startNode, f, nextParam));
+      }
+    }
+    let lastNode = startNode;
+    for (let i = 0; i < spec.steps.length; i++) {
+      const step = spec.steps[i];
+      const targetNode = `n${nodeIndex++}`;
+      const relAlias = `r${i}`;
+      const relTypes = step.relationshipTypes?.length ? step.relationshipTypes.join("|") : "";
+      const relTypePattern = relTypes ? `:${relTypes}` : "";
+      const depthPattern = step.repeat ? `*1..${step.repeat.maxDepth}` : "";
+      let pattern;
+      switch (step.direction) {
+        case "out":
+          pattern = `-[${relAlias}${relTypePattern}${depthPattern}]->(${targetNode})`;
+          break;
+        case "in":
+          pattern = `<-[${relAlias}${relTypePattern}${depthPattern}]-(${targetNode})`;
+          break;
+        case "both":
+          pattern = `-[${relAlias}${relTypePattern}${depthPattern}]-(${targetNode})`;
+          break;
+      }
+      matchParts.push(pattern);
+      estimatedFanOut *= step.repeat ? step.repeat.maxDepth * DEFAULT_ESTIMATED_FANOUT_PER_HOP2 : DEFAULT_ESTIMATED_FANOUT_PER_HOP2;
+      if (step.entityTypes && step.entityTypes.length > 0) {
+        const typeParam = nextParam(step.entityTypes);
+        whereClauses.push(`${targetNode}.entityType IN ${typeParam}`);
+      }
+      if (step.entityFilter) {
+        for (const f of step.entityFilter) {
+          whereClauses.push(compilePropertyFilterCypher(targetNode, f, nextParam));
+        }
+      }
+      if (step.relationshipFilter) {
+        for (const f of step.relationshipFilter) {
+          whereClauses.push(compilePropertyFilterCypher(relAlias, f, nextParam));
+        }
+      }
+      lastNode = targetNode;
+    }
+    const matchClause = `MATCH ${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 = spec.steps.map((_, i) => `r${i}`);
+      returnClause = `RETURN ${[...allNodes, ...allRels].join(", ")}`;
+    } 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(", ")}`;
+    } else {
+      returnClause = spec.dedup !== false ? `RETURN DISTINCT ${lastNode}` : `RETURN ${lastNode}`;
+    }
+    const offset = spec.offset ?? 0;
+    const limit = spec.limit ?? 50;
+    const skipClause = offset > 0 ? `
+SKIP ${nextParam(offset)}` : "";
+    const limitClause = `
+LIMIT ${nextParam(limit)}`;
+    params["_limit"] = limit;
+    params["_offset"] = offset;
+    const query = `${matchClause}${whereClause}
+${returnClause}${skipClause}${limitClause}`;
+    return {
+      query,
+      params,
+      estimatedFanOut: Math.min(estimatedFanOut, 1e4)
+    };
+  }
+};
+function compilePropertyFilterCypher(nodeAlias, filter, nextParam) {
+  const prop = `${nodeAlias}.${filter.key}`;
+  switch (filter.operator) {
+    case "eq":
+      return `${prop} = ${nextParam(filter.value)}`;
+    case "neq":
+      return `${prop} <> ${nextParam(filter.value)}`;
+    case "gt":
+      return `${prop} > ${nextParam(filter.value)}`;
+    case "gte":
+      return `${prop} >= ${nextParam(filter.value)}`;
+    case "lt":
+      return `${prop} < ${nextParam(filter.value)}`;
+    case "lte":
+      return `${prop} <= ${nextParam(filter.value)}`;
+    case "contains":
+      return `${prop} CONTAINS ${nextParam(filter.value)}`;
+    case "isNull":
+      return `${prop} IS NULL`;
+    case "isNotNull":
+      return `${prop} IS NOT NULL`;
+  }
+}
+
+// src/relationships/PropertyFilterMatcher.ts
+function matchesPropertyFilters(properties, filters) {
+  return filters.every((filter) => matchesSingleFilter(properties, filter));
+}
+function matchesSingleFilter(properties, filter) {
+  const value = properties[filter.key];
+  switch (filter.operator) {
+    case "isNull":
+      return value === null || value === void 0;
+    case "isNotNull":
+      return value !== null && value !== void 0;
+    case "eq":
+      return value === filter.value;
+    case "neq":
+      return value !== filter.value;
+    case "gt":
+      return typeof value === "number" && typeof filter.value === "number" ? value > filter.value : typeof value === "string" && typeof filter.value === "string" ? value > filter.value : false;
+    case "lt":
+      return typeof value === "number" && typeof filter.value === "number" ? value < filter.value : typeof value === "string" && typeof filter.value === "string" ? value < filter.value : false;
+    case "gte":
+      return typeof value === "number" && typeof filter.value === "number" ? value >= filter.value : typeof value === "string" && typeof filter.value === "string" ? value >= filter.value : false;
+    case "lte":
+      return typeof value === "number" && typeof filter.value === "number" ? value <= filter.value : typeof value === "string" && typeof filter.value === "string" ? value <= filter.value : false;
+    case "contains":
+      return typeof value === "string" && typeof filter.value === "string" ? value.toLowerCase().includes(filter.value.toLowerCase()) : false;
+    default:
+      return false;
+  }
+}
+
+// src/relationships/FallbackTraversalExecutor.ts
+var MAX_STORAGE_CALLS = 500;
+var REL_FETCH_LIMIT = 1e3;
+async function executeFallbackTraversal(repositoryId, storage, spec) {
+  const startTime = Date.now();
+  let storageCalls = 0;
+  const checkCallLimit = () => {
+    if (storageCalls >= MAX_STORAGE_CALLS) {
+      throw new Error(`Fallback traversal exceeded ${MAX_STORAGE_CALLS} storage calls. Consider using a GraphTraversalProvider for large traversals.`);
+    }
+  };
+  let frontier = [];
+  if (spec.start.entityId) {
+    const entity = await resolveEntity(repositoryId, storage, spec.start.entityId);
+    storageCalls++;
+    if (entity) {
+      frontier.push({ entity, entityPath: [entity.id], relationshipPath: [] });
+    } else {
+      throw new EntityNotFoundError(spec.start.entityId);
+    }
+  } else if (spec.start.entityType) {
+    const result = await storage.findEntities(repositoryId, {
+      entityTypes: [spec.start.entityType],
+      limit: spec.limit ?? 50,
+      offset: 0
+    });
+    storageCalls++;
+    frontier = result.items.map((e) => ({
+      entity: e,
+      entityPath: [e.id],
+      relationshipPath: []
+    }));
+  } else if (spec.start.filter && spec.start.filter.length > 0) {
+    const result = await storage.findEntities(repositoryId, {
+      limit: spec.limit ?? 50,
+      offset: 0
+    });
+    storageCalls++;
+    frontier = result.items.filter((e) => matchesPropertyFilters(e.properties, spec.start.filter)).map((e) => ({
+      entity: e,
+      entityPath: [e.id],
+      relationshipPath: []
+    }));
+  }
+  if (spec.start.filter && spec.start.filter.length > 0 && (spec.start.entityId || spec.start.entityType)) {
+    frontier = frontier.filter(
+      (entry) => matchesPropertyFilters(entry.entity.properties, spec.start.filter)
+    );
+  }
+  const allCollected = spec.returnMode === "all" ? [...frontier] : [];
+  for (const step of spec.steps) {
+    checkCallLimit();
+    if (step.repeat) {
+      const result = await executeRepeatStep(
+        repositoryId,
+        storage,
+        frontier,
+        step,
+        () => {
+          storageCalls++;
+          checkCallLimit();
+        }
+      );
+      frontier = result.terminal;
+      if (spec.returnMode === "all") {
+        allCollected.push(...result.intermediates);
+      }
+    } else {
+      frontier = await executeSingleStep(
+        repositoryId,
+        storage,
+        frontier,
+        step,
+        () => {
+          storageCalls++;
+          checkCallLimit();
+        }
+      );
+      if (spec.returnMode === "all") {
+        allCollected.push(...frontier);
+      }
+    }
+  }
+  const detailLevel = spec.detailLevel ?? "summary";
+  const dedup = spec.dedup !== false;
+  const limit = spec.limit ?? 50;
+  const offset = spec.offset ?? 0;
+  let resultEntries;
+  if (spec.returnMode === "all") {
+    resultEntries = allCollected;
+  } 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 total = resultEntries.length;
+  const paged = resultEntries.slice(offset, offset + limit);
+  const entities = paged.map((entry) => projectEntity(entry.entity, detailLevel));
+  let relationships;
+  let paths;
+  if (spec.returnMode === "path" || spec.returnMode === "all") {
+    const relMap = /* @__PURE__ */ new Map();
+    for (const entry of paged) {
+      for (const rel of entry.relationshipPath) {
+        if (!relMap.has(rel.id)) {
+          relMap.set(rel.id, {
+            id: rel.id,
+            type: rel.relationshipType,
+            sourceEntityId: rel.sourceEntityId,
+            targetEntityId: rel.targetEntityId,
+            direction: "outbound",
+            properties: rel.properties
+          });
+        }
+      }
+    }
+    relationships = Array.from(relMap.values());
+  }
+  if (spec.returnMode === "path") {
+    paths = paged.map((entry) => ({
+      length: entry.entityPath.length - 1,
+      entities: [projectEntity(entry.entity, detailLevel)],
+      relationships: entry.relationshipPath.map((rel) => ({
+        id: rel.id,
+        type: rel.relationshipType,
+        sourceEntityId: rel.sourceEntityId,
+        targetEntityId: rel.targetEntityId,
+        direction: "outbound",
+        properties: rel.properties
+      }))
+    }));
+  }
+  const executionTimeMs = Date.now() - startTime;
+  return {
+    entities,
+    relationships,
+    paths,
+    total,
+    returned: paged.length,
+    hasMore: offset + limit < total,
+    queryMetadata: {
+      executionTimeMs,
+      appliedLimits: {
+        maxResults: limit
+      },
+      truncated: total > limit + offset,
+      truncationReason: total > limit + offset ? "result_limit" : void 0
+    }
+  };
+}
+async function executeSingleStep(repositoryId, storage, frontier, step, onStorageCall) {
+  const direction = mapDirection(step.direction);
+  const pendingEdges = [];
+  for (const entry of frontier) {
+    const rels = await storage.getEntityRelationships(repositoryId, entry.entity.id, {
+      direction,
+      relationshipTypes: step.relationshipTypes,
+      limit: REL_FETCH_LIMIT
+    });
+    onStorageCall();
+    for (const rel of rels.items) {
+      if (step.relationshipFilter && step.relationshipFilter.length > 0) {
+        if (!matchesPropertyFilters(rel.properties, step.relationshipFilter)) {
+          continue;
+        }
+      }
+      const targetId = getTargetId(rel, entry.entity.id);
+      pendingEdges.push({ entry, rel, targetId });
+    }
+  }
+  if (pendingEdges.length === 0) return [];
+  const uniqueTargetIds = [...new Set(pendingEdges.map((e) => e.targetId))];
+  const entityMap = await storage.getEntities(repositoryId, uniqueTargetIds);
+  onStorageCall();
+  const nextFrontier = [];
+  for (const { entry, rel, targetId } of pendingEdges) {
+    const targetEntity = entityMap.get(targetId);
+    if (!targetEntity) continue;
+    if (step.entityTypes && step.entityTypes.length > 0) {
+      if (!step.entityTypes.includes(targetEntity.entityType)) continue;
+    }
+    if (step.entityFilter && step.entityFilter.length > 0) {
+      if (!matchesPropertyFilters(targetEntity.properties, step.entityFilter)) continue;
+    }
+    nextFrontier.push({
+      entity: targetEntity,
+      entityPath: [...entry.entityPath, targetEntity.id],
+      relationshipPath: [...entry.relationshipPath, rel]
+    });
+  }
+  return nextFrontier;
+}
+async function executeRepeatStep(repositoryId, storage, frontier, step, onStorageCall) {
+  const maxDepth = step.repeat?.maxDepth ?? 1;
+  const emitIntermediates = step.repeat?.emitIntermediates !== false;
+  const untilFilters = step.repeat?.until;
+  let current = frontier;
+  const allIntermediates = [];
+  const visited = /* @__PURE__ */ new Set();
+  for (const entry of frontier) {
+    visited.add(entry.entity.id);
+  }
+  for (let depth = 0; depth < maxDepth; depth++) {
+    const next = await executeSingleStep(repositoryId, storage, current, step, onStorageCall);
+    const unvisited = next.filter((entry) => {
+      if (visited.has(entry.entity.id)) return false;
+      visited.add(entry.entity.id);
+      return true;
+    });
+    if (unvisited.length === 0) break;
+    if (untilFilters && untilFilters.length > 0) {
+      const matching = [];
+      const continuing = [];
+      for (const entry of unvisited) {
+        if (matchesPropertyFilters(entry.entity.properties, untilFilters)) {
+          matching.push(entry);
+        } else {
+          continuing.push(entry);
+        }
+      }
+      if (emitIntermediates) {
+        allIntermediates.push(...continuing);
+      }
+      allIntermediates.push(...matching);
+      if (matching.length > 0 && continuing.length === 0) {
+        current = matching;
+        break;
+      }
+      current = continuing;
+    } else {
+      if (emitIntermediates) {
+        allIntermediates.push(...unvisited);
+      }
+      current = unvisited;
+    }
+  }
+  return {
+    terminal: current,
+    intermediates: allIntermediates
+  };
+}
+async function resolveEntity(repositoryId, storage, idOrSlug) {
+  const byId = await storage.getEntity(repositoryId, 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;
+}
+
 // src/relationships/GraphTraversal.ts
 var GraphTraversal = class {
-  constructor(repositoryId, storage) {
+  constructor(repositoryId, storage, graphTraversalProvider, vocabularyEngine) {
     this.repositoryId = repositoryId;
     this.storage = storage;
+    this.graphTraversalProvider = graphTraversalProvider;
+    this.vocabularyEngine = vocabularyEngine;
   }
   /** BFS neighbourhood exploration from a centre entity */
   async exploreNeighbourhood(entityId, options) {
@@ -871,6 +1620,51 @@ var GraphTraversal = class {
       }))
     };
   }
+  /**
+   * Execute a structured traversal.
+   * Validates the spec, compiles to native query if a provider exists,
+   * falls back to application-level BFS otherwise.
+   */
+  async traverse(spec) {
+    const capabilities = this.graphTraversalProvider?.getCapabilities();
+    const vocabulary = this.vocabularyEngine ? await this.vocabularyEngine.getVocabulary() : void 0;
+    const validation = validateTraversalSpec(spec, vocabulary, capabilities);
+    if (!validation.valid) {
+      const vocabErrors = validation.errors.filter((e) => e.startsWith("Unknown vocabulary types:"));
+      const structErrors = validation.errors.filter((e) => !e.startsWith("Unknown vocabulary types:"));
+      if (vocabErrors.length > 0) {
+        const unknownTypes = vocabErrors.join("; ").replace(/Unknown vocabulary types: /g, "").split(", ").map((t) => t.trim());
+        throw new TraversalVocabularyError(unknownTypes);
+      }
+      throw new TraversalValidationError(structErrors.length > 0 ? structErrors : validation.errors);
+    }
+    if (this.graphTraversalProvider && vocabulary) {
+      const language = capabilities.nativeQueryLanguage;
+      let compiledQuery;
+      if (language === "gremlin") {
+        const compiler = new GremlinCompiler();
+        const compiled = compiler.compile(spec, vocabulary);
+        compiledQuery = compiled.query;
+      } else if (language === "cypher") {
+        const compiler = new CypherCompiler();
+        const compiled = compiler.compile(spec, vocabulary);
+        compiledQuery = compiled.query;
+      }
+      return this.graphTraversalProvider.traverse(this.repositoryId, spec, compiledQuery);
+    }
+    return executeFallbackTraversal(this.repositoryId, this.storage, spec);
+  }
+  /**
+   * Execute a native graph query.
+   * Pass-through to GraphTraversalProvider.executeNativeQuery().
+   * Throws GraphTraversalProviderRequiredError if no provider registered.
+   */
+  async executeNativeQuery(query, params) {
+    if (!this.graphTraversalProvider) {
+      throw new GraphTraversalProviderRequiredError();
+    }
+    return this.graphTraversalProvider.executeNativeQuery(this.repositoryId, query, params);
+  }
 };
 
 // src/search/SearchOrchestrator.ts
@@ -1079,7 +1873,9 @@ var MemoryRepository = class {
     );
     this.graphTraversal = new GraphTraversal(
       config.repositoryId,
-      config.storage
+      config.storage,
+      config.graphTraversal,
+      config.vocabularyEngine
     );
     this.searchOrchestrator = new SearchOrchestrator({
       repositoryId: config.repositoryId,
@@ -1103,19 +1899,21 @@ var MemoryRepository = class {
     return this.proposeVocabularyChange(proposal);
   }
   // ─── Entities ──────────────────────────────────────────────────────
-  async createEntity(input) {
-    const entity = await this.entityManager.create(input);
+  async createEntities(inputs) {
+    const entities = await this.entityManager.create(inputs);
     if (this.search) {
-      await this.search.indexEntity(this.repositoryId, {
-        entityId: entity.id,
-        entityType: entity.entityType,
-        label: entity.label,
-        summary: entity.summary,
-        properties: entity.properties,
-        data: entity.data
-      });
+      for (const entity of entities) {
+        await this.search.indexEntity(this.repositoryId, {
+          entityId: entity.id,
+          entityType: entity.entityType,
+          label: entity.label,
+          summary: entity.summary,
+          properties: entity.properties,
+          data: entity.data
+        });
+      }
     }
-    return entity;
+    return entities;
   }
   async updateEntity(entityId, updates) {
     const entity = await this.entityManager.update(entityId, updates);
@@ -1202,8 +2000,8 @@ var MemoryRepository = class {
     }
   }
   // ─── Relationships ─────────────────────────────────────────────────
-  async createRelationship(input) {
-    return this.relationshipManager.create(input);
+  async createRelationships(inputs) {
+    return this.relationshipManager.create(inputs);
   }
   async removeRelationship(relationshipId) {
     return this.relationshipManager.remove(relationshipId);
@@ -1297,6 +2095,12 @@ var MemoryRepository = class {
   async findPaths(sourceId, targetId, options) {
     return this.graphTraversal.findPaths(sourceId, targetId, options);
   }
+  async traverse(spec) {
+    return this.graphTraversal.traverse(spec);
+  }
+  async executeNativeQuery(query, params) {
+    return this.graphTraversal.executeNativeQuery(query, params);
+  }
   // ─── Search ────────────────────────────────────────────────────────
   async searchByConcept(query, options) {
     return this.searchOrchestrator.searchByConcept(query, options);
@@ -2381,13 +3185,15 @@ var EventBus = class {
 };
 
 // src/portability/RepositoryExporter.ts
-var LIBRARY_VERSION = "0.1.0";
+var LIBRARY_VERSION = true ? "0.2.0" : "0.1.0";
 var RepositoryExporter = class {
   storage;
   provenance;
+  legal;
   constructor(config) {
     this.storage = config.storage;
     this.provenance = config.provenance;
+    this.legal = config.legal;
   }
   /**
    * Stream a repository export as an async generator.
@@ -2421,6 +3227,9 @@ var RepositoryExporter = class {
         relationshipTypeBreakdown: stats.relationshipTypeBreakdown
       }
     };
+    if (this.legal) {
+      manifest.legal = this.legal;
+    }
     if (repo.metadata?.embeddingModelId) {
       manifest.embedding = {
         modelId: repo.metadata.embeddingModelId,
@@ -2989,6 +3798,7 @@ var DeepMemory = class {
   embedding;
   /** Reserved for future distributed locking support */
   lock;
+  graphTraversalProvider;
   provenance;
   globalEventBus;
   initialised = false;
@@ -2997,24 +3807,42 @@ var DeepMemory = class {
     this.search = config.search;
     this.embedding = config.embedding;
     this.lock = config.lock;
+    this.graphTraversalProvider = config.graphTraversal;
     this.provenance = new ProvenanceTracker(config.provenance);
     this.globalEventBus = new EventBus(config.provenance);
   }
-  /** Initialise the storage provider (call once before use) */
+  /** Initialise the storage provider and optional providers (call once before use) */
   async ensureInitialised() {
     if (!this.initialised) {
       if (this.storage.initialise) {
         await this.storage.initialise();
       }
+      if (this.graphTraversalProvider?.initialise) {
+        await this.graphTraversalProvider.initialise();
+      }
       this.initialised = true;
     }
   }
   /** Create or migrate the storage schema. Call once at deployment / startup, not per-request. */
   async ensureSchema() {
-    await this.ensureInitialised();
+    const noOpResult = {
+      databaseCreated: false,
+      schemaCreated: false,
+      alreadyUpToDate: true,
+      schemaVersion: 0
+    };
+    try {
+      await this.ensureInitialised();
+    } catch {
+    }
+    let result = noOpResult;
     if (this.storage.ensureSchema) {
-      await this.storage.ensureSchema();
+      result = await this.storage.ensureSchema();
+    }
+    if (!this.initialised) {
+      await this.ensureInitialised();
     }
+    return result;
   }
   validateRepositoryId(repositoryId) {
     if (!isValidUuid(repositoryId)) {
@@ -3071,6 +3899,7 @@ var DeepMemory = class {
       storage: this.storage,
       search: this.search,
       embedding: this.embedding,
+      graphTraversal: this.graphTraversalProvider,
       vocabularyEngine,
       provenanceTracker: this.provenance,
       eventBus
@@ -3102,6 +3931,7 @@ var DeepMemory = class {
       storage: this.storage,
       search: this.search,
       embedding: this.embedding,
+      graphTraversal: this.graphTraversalProvider,
       vocabularyEngine,
       provenanceTracker: this.provenance,
       eventBus
@@ -3143,11 +3973,12 @@ var DeepMemory = class {
     await this.globalEventBus.emit("repository:deleted", { repositoryId });
   }
   /** Export a repository to a portable archive */
-  async exportRepository(repositoryId) {
+  async exportRepository(repositoryId, options) {
     await this.ensureInitialised();
     const exporter = new RepositoryExporter({
       storage: this.storage,
-      provenance: this.provenance.getContext()
+      provenance: this.provenance.getContext(),
+      legal: options?.legal
     });
     const archive = await exporter.export(repositoryId);
     await this.globalEventBus.emit("export:completed", {
@@ -3184,11 +4015,12 @@ var DeepMemory = class {
    * Yields: manifest → vocabulary → entity chunks → relationship chunks.
    * Use for large repositories to avoid loading everything into memory.
    */
-  async *exportRepositoryStream(repositoryId) {
+  async *exportRepositoryStream(repositoryId, options) {
     await this.ensureInitialised();
     const exporter = new RepositoryExporter({
       storage: this.storage,
-      provenance: this.provenance.getContext()
+      provenance: this.provenance.getContext(),
+      legal: options?.legal
     });
     await this.globalEventBus.emit("export:started", { repositoryId });
     let entityCount = 0;
@@ -3245,6 +4077,9 @@ var DeepMemory = class {
   /** Dispose of all resources */
   async dispose() {
     this.globalEventBus.removeAllListeners();
+    if (this.graphTraversalProvider?.dispose) {
+      await this.graphTraversalProvider.dispose();
+    }
     if (this.storage.dispose) {
       await this.storage.dispose();
     }
@@ -3252,36 +4087,6 @@ var DeepMemory = class {
   }
 };
 
-// src/relationships/PropertyFilterMatcher.ts
-function matchesPropertyFilters(properties, filters) {
-  return filters.every((filter) => matchesSingleFilter(properties, filter));
-}
-function matchesSingleFilter(properties, filter) {
-  const value = properties[filter.key];
-  switch (filter.operator) {
-    case "isNull":
-      return value === null || value === void 0;
-    case "isNotNull":
-      return value !== null && value !== void 0;
-    case "eq":
-      return value === filter.value;
-    case "neq":
-      return value !== filter.value;
-    case "gt":
-      return typeof value === "number" && typeof filter.value === "number" ? value > filter.value : typeof value === "string" && typeof filter.value === "string" ? value > filter.value : false;
-    case "lt":
-      return typeof value === "number" && typeof filter.value === "number" ? value < filter.value : typeof value === "string" && typeof filter.value === "string" ? value < filter.value : false;
-    case "gte":
-      return typeof value === "number" && typeof filter.value === "number" ? value >= filter.value : typeof value === "string" && typeof filter.value === "string" ? value >= filter.value : false;
-    case "lte":
-      return typeof value === "number" && typeof filter.value === "number" ? value <= filter.value : typeof value === "string" && typeof filter.value === "string" ? value <= filter.value : false;
-    case "contains":
-      return typeof value === "string" && typeof filter.value === "string" ? value.toLowerCase().includes(filter.value.toLowerCase()) : false;
-    default:
-      return false;
-  }
-}
-
 // src/providers-builtin/InMemoryStorageProvider.ts
 var InMemoryStorageProvider = class {
   stores = /* @__PURE__ */ new Map();
@@ -3976,6 +4781,7 @@ var NoOpEmbeddingProvider = class {
   }
 };
 export {
+  CypherCompiler,
   DeepMemory,
   DeepMemoryError,
   DuplicateEntityError,
@@ -3985,6 +4791,8 @@ export {
   EntityNotFoundError,
   ExportError,
   GovernanceDeniedError,
+  GraphTraversalProviderRequiredError,
+  GremlinCompiler,
   ImportError,
   InMemorySearchProvider,
   InMemoryStorageProvider,
@@ -3996,6 +4804,9 @@ export {
   RelationshipConstraintError,
   RelationshipNotFoundError,
   RepositoryNotFoundError,
+  TraversalTimeoutError,
+  TraversalValidationError,
+  TraversalVocabularyError,
   VocabularyValidationError,
   generateId,
   isValidUuid,