@utaba/deep-memory 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  CypherCompiler: () => CypherCompiler,
   DeepMemory: () => DeepMemory,
   DeepMemoryError: () => DeepMemoryError,
   DuplicateEntityError: () => DuplicateEntityError,
@@ -29,6 +30,8 @@ __export(src_exports, {
   EntityNotFoundError: () => EntityNotFoundError,
   ExportError: () => ExportError,
   GovernanceDeniedError: () => GovernanceDeniedError,
+  GraphTraversalProviderRequiredError: () => GraphTraversalProviderRequiredError,
+  GremlinCompiler: () => GremlinCompiler,
   ImportError: () => ImportError,
   InMemorySearchProvider: () => InMemorySearchProvider,
   InMemoryStorageProvider: () => InMemoryStorageProvider,
@@ -40,6 +43,9 @@ __export(src_exports, {
   RelationshipConstraintError: () => RelationshipConstraintError,
   RelationshipNotFoundError: () => RelationshipNotFoundError,
   RepositoryNotFoundError: () => RepositoryNotFoundError,
+  TraversalTimeoutError: () => TraversalTimeoutError,
+  TraversalValidationError: () => TraversalValidationError,
+  TraversalVocabularyError: () => TraversalVocabularyError,
   VocabularyValidationError: () => VocabularyValidationError,
   generateId: () => generateId,
   isValidUuid: () => isValidUuid,
@@ -240,6 +246,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) {
@@ -280,50 +332,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) {
@@ -655,55 +711,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) {
@@ -784,11 +844,806 @@ 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 = [];
+  const steps = spec.steps ?? [];
+  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");
+    }
+  }
+  const maxSteps = capabilities?.maxTraversalDepth ?? DEFAULT_MAX_STEPS;
+  if (steps.length > maxSteps) {
+    errors.push(`steps length ${steps.length} exceeds maximum ${maxSteps}`);
+  }
+  for (let i = 0; i < steps.length; i++) {
+    const step = 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`);
+      }
+    }
+  }
+  if (steps.length > 0) {
+    const maxProviderDepth = capabilities?.maxTraversalDepth ?? DEFAULT_FALLBACK_MAX_DEPTH;
+    let totalDepth = 0;
+    for (const step of steps) {
+      totalDepth += step.repeat ? step.repeat.maxDepth : 1;
+    }
+    if (totalDepth > maxProviderDepth) {
+      errors.push(`total potential depth ${totalDepth} exceeds provider maximum ${maxProviderDepth}`);
+    }
+  }
+  if (spec.returnMode === "path" && steps.length === 0) {
+    errors.push("returnMode 'path' requires at least one step");
+  }
+  if (spec.returnMode && !["terminal", "path", "all"].includes(spec.returnMode)) {
+    errors.push(`returnMode must be 'terminal', 'path', or 'all'`);
+  }
+  if (spec.projection) {
+    if (!spec.projection.properties || spec.projection.properties.length === 0) {
+      errors.push("projection.properties must contain at least one property name");
+    }
+    if (spec.projection.mode && !["count", "values"].includes(spec.projection.mode)) {
+      errors.push("projection.mode must be 'count' or 'values'");
+    }
+  }
+  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) {
+    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 < steps.length; i++) {
+      const step = 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));
+      }
+    }
+    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;
+      }
+      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;
+    const steps = spec.steps ?? [];
+    for (let i = 0; i < steps.length; i++) {
+      const step = 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 = 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 MAX_ENTITY_SCAN = 1e4;
+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.`);
+    }
+  };
+  const isVertexQuery = !spec.steps || spec.steps.length === 0;
+  const needsFullScan = isVertexQuery || spec.projection !== void 0;
+  const fetchLimit = needsFullScan ? MAX_ENTITY_SCAN : spec.limit ?? 50;
+  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: fetchLimit,
+      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: fetchLimit,
+      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 steps = spec.steps ?? [];
+  const allCollected = spec.returnMode === "all" ? [...frontier] : [];
+  for (const step of 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 suppressEntities = spec.projection !== void 0 && spec.projection.includeEntities !== true;
+  let entities;
+  if (suppressEntities) {
+    entities = [];
+  } else {
+    entities = paged.map((entry) => {
+      const projected = projectEntity(entry.entity, detailLevel);
+      if (!spec.includeProvenance) {
+        delete projected["provenance"];
+      }
+      return projected;
+    });
+    if (spec.includeRelationshipSummary && entities.length > 0) {
+      const summaryResults = await Promise.all(
+        paged.map(async (entry) => {
+          storageCalls++;
+          const result = await storage.getEntityRelationships(repositoryId, entry.entity.id, {
+            direction: "both",
+            limit: 1e4
+          });
+          const summary = { outbound: {}, inbound: {} };
+          for (const rel of result.items) {
+            if (rel.sourceEntityId === entry.entity.id) {
+              summary.outbound[rel.relationshipType] = (summary.outbound[rel.relationshipType] ?? 0) + 1;
+            }
+            if (rel.targetEntityId === entry.entity.id) {
+              summary.inbound[rel.relationshipType] = (summary.inbound[rel.relationshipType] ?? 0) + 1;
+            }
+          }
+          return summary;
+        })
+      );
+      entities = entities.map((e, i) => ({ ...e, relationshipSummary: summaryResults[i] }));
+    }
+  }
+  let aggregations;
+  if (spec.projection) {
+    const propNames = spec.projection.properties;
+    const mode = spec.projection.mode ?? "values";
+    const distinct = spec.projection.distinct ?? false;
+    const sourceEntries = dedup ? (() => {
+      const seen = /* @__PURE__ */ new Set();
+      return (spec.returnMode === "all" ? allCollected : frontier).filter((e) => {
+        if (seen.has(e.entity.id)) return false;
+        seen.add(e.entity.id);
+        return true;
+      });
+    })() : spec.returnMode === "all" ? allCollected : frontier;
+    if (mode === "count" || distinct) {
+      const groups = /* @__PURE__ */ new Map();
+      for (const entry of sourceEntries) {
+        const vals = {};
+        for (const prop of propNames) {
+          vals[prop] = entry.entity.properties[prop] ?? null;
+        }
+        const key = JSON.stringify(vals);
+        const existing = groups.get(key);
+        if (existing) {
+          existing.count++;
+        } else {
+          groups.set(key, { values: vals, count: 1 });
+        }
+      }
+      aggregations = Array.from(groups.values()).map((g) => ({
+        values: g.values,
+        ...mode === "count" ? { count: g.count } : {}
+      }));
+      if (mode === "count") {
+        aggregations.sort((a, b) => (b.count ?? 0) - (a.count ?? 0));
+      }
+    } else {
+      aggregations = sourceEntries.map((entry) => {
+        const vals = {};
+        for (const prop of propNames) {
+          vals[prop] = entry.entity.properties[prop] ?? null;
+        }
+        return { values: vals };
+      });
+    }
+  }
+  let relationships;
+  let paths;
+  if (!suppressEntities && (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 (!suppressEntities && spec.returnMode === "path") {
+    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
+      }))
+    }));
+  }
+  const executionTimeMs = Date.now() - startTime;
+  return {
+    entities,
+    relationships,
+    paths,
+    aggregations,
+    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) {
@@ -920,6 +1775,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
@@ -1128,7 +2028,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,
@@ -1152,19 +2054,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);
@@ -1251,8 +2155,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);
@@ -1346,6 +2250,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);
@@ -1435,6 +2345,58 @@ var MemoryRepository = class {
   async getStats() {
     return this.storage.getRepositoryStats(this.repositoryId);
   }
+  // ─── Bulk Operations ──────────────────────────────────────────────
+  /** Delete all entities and relationships in this repository, preserving the repository and vocabulary */
+  async deleteAllContents() {
+    return this.storage.deleteAllContents(this.repositoryId);
+  }
+  /**
+   * Returns a static markdown guide describing the recommended query strategy
+   * for AI agents and other consumers of the repository.
+   */
+  getQueryGuide() {
+    return `## Query Strategy Guide
+
+### Step 1 \u2014 Discover before you traverse
+
+Before following relationships from an entity, check that it actually has relationships.
+\`memory_query_graph\` includes \`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.
+To skip summaries and reduce response size, set \`includeRelationshipSummary: false\`.
+
+### Step 2 \u2014 Use projection for aggregation
+
+To understand what data exists (e.g. all distinct values of a property, or counts by
+category), use \`memory_query_graph\` with \`projection\` instead of fetching full entities:
+\`{ start: { entityType: "..." }, projection: { properties: ["propName"], distinct: true }, limit: 200 }\`
+
+This returns only the aggregated values \u2014 no entity objects \u2014 keeping responses lightweight.
+
+### Step 3 \u2014 Traverse efficiently
+
+- **Omit relationshipTypes** in a traversal step to follow all relationship types at once,
+  rather than making separate calls per type.
+- **Use multi-step traversals** for multi-hop patterns. A two-step query
+  (e.g. Equipment \u2192 Component \u2192 MaintenanceProcedure) is one call, not two sequential calls.
+- **Use returnMode "all"** when you need intermediate entities along the path, not just
+  the terminal nodes.
+
+### Step 4 \u2014 Use semantic search for known-unknowns
+
+\`memory_search_by_concept\` is best for finding specific entities when you know roughly
+what you're looking for but not the exact label or type. It is not efficient for broad
+discovery \u2014 use projection or find_entities for that.
+
+### Common anti-patterns to avoid
+
+- **Don't traverse from entities with zero relationship counts.** The \`relationshipSummary\` on each entity tells you what is connected before you traverse.
+- **Don't split queries by relationship type.** One step with no type filter is better
+  than three separate single-type calls.
+- **Don't use sequential single-hop traversals** when a multi-step query achieves the
+  same result in one call.
+- **Don't fetch full entities when you only need property values.** Use projection.`;
+  }
   // ─── Events ────────────────────────────────────────────────────────
   on(event, handler) {
     return this.eventBus.on(event, handler);
@@ -2430,13 +3392,15 @@ var EventBus = class {
 };
 
 // src/portability/RepositoryExporter.ts
-var LIBRARY_VERSION = "0.1.0";
+var LIBRARY_VERSION = true ? "0.3.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.
@@ -2470,6 +3434,9 @@ var RepositoryExporter = class {
         relationshipTypeBreakdown: stats.relationshipTypeBreakdown
       }
     };
+    if (this.legal) {
+      manifest.legal = this.legal;
+    }
     if (repo.metadata?.embeddingModelId) {
       manifest.embedding = {
         modelId: repo.metadata.embeddingModelId,
@@ -2768,13 +3735,22 @@ function describeChange(change) {
 }
 
 // src/portability/RepositoryImporter.ts
+function estimateChunkCount(totalEntities, totalRelationships) {
+  const ESTIMATED_CHUNK_SIZE = 100;
+  return Math.max(
+    1,
+    Math.ceil(totalEntities / ESTIMATED_CHUNK_SIZE) + Math.ceil(totalRelationships / ESTIMATED_CHUNK_SIZE)
+  );
+}
 var RepositoryImporter = class {
   storage;
   actorId;
+  onProgress;
   migrationEngine = new MigrationEngine();
   constructor(config) {
     this.storage = config.storage;
     this.actorId = config.actorId;
+    this.onProgress = config.onProgress;
   }
   /**
    * Import an export archive according to the provided options.
@@ -2825,26 +3801,34 @@ var RepositoryImporter = class {
       return this.importStreamMerge(header, chunks, options, warnings);
     }
   }
-  /** Streaming create mode — set up repo then pipe chunks through importBulk */
+  /** Streaming create mode — fast bulk inserts with no existence checks */
   async importStreamCreate(header, chunks, options, warnings) {
     const target = options.target;
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    await this.storage.createRepository({
-      repositoryId: target.repositoryId,
-      type: target.config.type,
-      label: target.config.label,
-      description: target.config.description,
-      governanceConfig: target.config.governance ?? { mode: "open" },
-      createdAt: now,
-      createdBy: this.actorId
-    });
+    const existing = await this.storage.getRepository(target.repositoryId);
+    if (!existing) {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      await this.storage.createRepository({
+        repositoryId: target.repositoryId,
+        type: target.config.type,
+        label: target.config.label,
+        description: target.config.description,
+        governanceConfig: target.config.governance ?? { mode: "open" },
+        createdAt: now,
+        createdBy: this.actorId
+      });
+    }
     await this.storage.saveVocabulary(target.repositoryId, header.vocabulary);
+    const totalEntities = header.manifest?.statistics?.entityCount ?? 0;
+    const totalRelationships = header.manifest?.statistics?.relationshipCount ?? 0;
+    const totalChunks = estimateChunkCount(totalEntities, totalRelationships);
     let entitiesImported = 0;
     let relationshipsImported = 0;
+    let chunksCompleted = 0;
     for await (const chunk of chunks) {
-      const bulkResult = await this.storage.importBulk(target.repositoryId, [chunk]);
+      const bulkResult = await this.storage.importBulk(target.repositoryId, [chunk], { skipExistenceCheck: true });
       entitiesImported += bulkResult.entitiesImported;
       relationshipsImported += bulkResult.relationshipsImported;
+      chunksCompleted++;
       for (const e of bulkResult.errors) {
         warnings.push({
           code: "import_error",
@@ -2852,6 +3836,15 @@ var RepositoryImporter = class {
           id: e.item
         });
       }
+      await this.onProgress?.({
+        repositoryId: target.repositoryId,
+        entitiesImported,
+        relationshipsImported,
+        totalEntities,
+        totalRelationships,
+        chunksCompleted,
+        totalChunks
+      });
     }
     return {
       success: true,
@@ -2899,11 +3892,15 @@ var RepositoryImporter = class {
     if (migrationResult.mergedVocabulary && migrationResult.mergedVocabulary !== targetVocabulary) {
       await this.storage.saveVocabulary(repositoryId, migrationResult.mergedVocabulary);
     }
+    const totalEntities = header.manifest?.statistics?.entityCount ?? 0;
+    const totalRelationships = header.manifest?.statistics?.relationshipCount ?? 0;
+    const totalChunks = estimateChunkCount(totalEntities, totalRelationships);
     const entityConflict = options.entityConflict ?? "skip";
     let entitiesImported = 0;
     let entitiesSkipped = 0;
     let relationshipsImported = 0;
     let relationshipsSkipped = 0;
+    let chunksCompleted = 0;
     for await (const chunk of chunks) {
       if (chunk.entities) {
         for (const entity of chunk.entities) {
@@ -2985,6 +3982,16 @@ var RepositoryImporter = class {
           }
         }
       }
+      chunksCompleted++;
+      await this.onProgress?.({
+        repositoryId,
+        entitiesImported,
+        relationshipsImported,
+        totalEntities,
+        totalRelationships,
+        chunksCompleted,
+        totalChunks
+      });
     }
     const vocabExtensions = migrationResult.warnings.filter(
       (w) => w.code === "entity_type_added" || w.code === "relationship_type_added"
@@ -3038,6 +4045,7 @@ var DeepMemory = class {
   embedding;
   /** Reserved for future distributed locking support */
   lock;
+  graphTraversalProvider;
   provenance;
   globalEventBus;
   initialised = false;
@@ -3046,24 +4054,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)) {
@@ -3120,6 +4146,7 @@ var DeepMemory = class {
       storage: this.storage,
       search: this.search,
       embedding: this.embedding,
+      graphTraversal: this.graphTraversalProvider,
       vocabularyEngine,
       provenanceTracker: this.provenance,
       eventBus
@@ -3151,6 +4178,7 @@ var DeepMemory = class {
       storage: this.storage,
       search: this.search,
       embedding: this.embedding,
+      graphTraversal: this.graphTraversalProvider,
       vocabularyEngine,
       provenanceTracker: this.provenance,
       eventBus
@@ -3188,15 +4216,57 @@ var DeepMemory = class {
   async deleteRepository(repositoryId) {
     await this.ensureInitialised();
     this.validateRepositoryId(repositoryId);
-    await this.storage.deleteRepository(repositoryId);
+    const stats = await this.storage.getRepositoryStats(repositoryId);
+    await this.globalEventBus.emit("delete:started", {
+      repositoryId,
+      totalEntities: stats.entityCount,
+      totalRelationships: stats.relationshipCount
+    });
+    await this.storage.deleteRepository(
+      repositoryId,
+      (progress) => this.globalEventBus.emit("delete:progress", { repositoryId, ...progress })
+    );
+    await this.globalEventBus.emit("delete:completed", {
+      repositoryId,
+      entitiesDeleted: stats.entityCount,
+      relationshipsDeleted: stats.relationshipCount
+    });
     await this.globalEventBus.emit("repository:deleted", { repositoryId });
   }
+  /** Delete all entities and relationships in a repository, preserving the repository and vocabulary */
+  async deleteAllContents(repositoryId) {
+    await this.ensureInitialised();
+    this.validateRepositoryId(repositoryId);
+    const stats = await this.storage.getRepositoryStats(repositoryId);
+    await this.globalEventBus.emit("delete:started", {
+      repositoryId,
+      totalEntities: stats.entityCount,
+      totalRelationships: stats.relationshipCount
+    });
+    const result = await this.storage.deleteAllContents(
+      repositoryId,
+      (progress) => this.globalEventBus.emit("delete:progress", { repositoryId, ...progress })
+    );
+    await this.globalEventBus.emit("delete:completed", {
+      repositoryId,
+      entitiesDeleted: result.deletedEntities,
+      relationshipsDeleted: result.deletedRelationships
+    });
+    return result;
+  }
   /** Export a repository to a portable archive */
-  async exportRepository(repositoryId) {
+  async exportRepository(repositoryId, options) {
     await this.ensureInitialised();
+    const stats = await this.storage.getRepositoryStats(repositoryId);
+    await this.globalEventBus.emit("export:started", {
+      repositoryId,
+      totalEntities: stats.entityCount,
+      totalRelationships: stats.relationshipCount
+    });
     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", {
@@ -3209,9 +4279,11 @@ var DeepMemory = class {
   /** Import a repository from a portable archive */
   async importRepository(archive, options) {
     await this.ensureInitialised();
+    await this.globalEventBus.emit("import:started", { repositoryId: options.target.repositoryId });
     const importer = new RepositoryImporter({
       storage: this.storage,
-      actorId: this.provenance.getContext().actorId
+      actorId: this.provenance.getContext().actorId,
+      onProgress: (progress) => this.globalEventBus.emit("import:progress", progress)
     });
     const result = await importer.import(archive, options);
     if (result.success) {
@@ -3233,21 +4305,51 @@ 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 });
+    const stats = await this.storage.getRepositoryStats(repositoryId);
+    const totalEntities = stats.entityCount;
+    const totalRelationships = stats.relationshipCount;
+    const estimatedChunkSize = 100;
+    const totalChunks = Math.max(
+      1,
+      Math.ceil(totalEntities / estimatedChunkSize) + Math.ceil(totalRelationships / estimatedChunkSize)
+    );
+    await this.globalEventBus.emit("export:started", { repositoryId, totalEntities, totalRelationships });
     let entityCount = 0;
     let relationshipCount = 0;
+    let chunksCompleted = 0;
     for await (const item of exporter.exportStream(repositoryId)) {
       yield item;
       if (item.type === "entities") {
         entityCount += item.data.length;
+        chunksCompleted++;
+        await this.globalEventBus.emit("export:progress", {
+          repositoryId,
+          entitiesExported: entityCount,
+          relationshipsExported: relationshipCount,
+          totalEntities,
+          totalRelationships,
+          chunksCompleted,
+          totalChunks
+        });
       } else if (item.type === "relationships") {
         relationshipCount += item.data.length;
+        chunksCompleted++;
+        await this.globalEventBus.emit("export:progress", {
+          repositoryId,
+          entitiesExported: entityCount,
+          relationshipsExported: relationshipCount,
+          totalEntities,
+          totalRelationships,
+          chunksCompleted,
+          totalChunks
+        });
       }
     }
     await this.globalEventBus.emit("export:completed", {
@@ -3264,7 +4366,8 @@ var DeepMemory = class {
     await this.ensureInitialised();
     const importer = new RepositoryImporter({
       storage: this.storage,
-      actorId: this.provenance.getContext().actorId
+      actorId: this.provenance.getContext().actorId,
+      onProgress: (progress) => this.globalEventBus.emit("import:progress", progress)
     });
     await this.globalEventBus.emit("import:started", { repositoryId: options.target.repositoryId });
     const result = await importer.importStream(header, chunks, options);
@@ -3294,6 +4397,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();
     }
@@ -3301,36 +4407,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();
@@ -3415,12 +4491,21 @@ var InMemoryStorageProvider = class {
     if (updates.metadata !== void 0) repo.metadata = { ...repo.metadata, ...updates.metadata };
     return repo;
   }
-  async deleteRepository(repositoryId) {
+  async deleteRepository(repositoryId, _onProgress) {
     if (!this.stores.has(repositoryId)) {
       throw new RepositoryNotFoundError(repositoryId);
     }
     this.stores.delete(repositoryId);
   }
+  async deleteAllContents(repositoryId, _onProgress) {
+    const store = this.getStore(repositoryId);
+    const deletedEntities = store.entities.size;
+    const deletedRelationships = store.relationships.size;
+    store.entities.clear();
+    store.slugIndex.clear();
+    store.relationships.clear();
+    return { deletedEntities, deletedRelationships };
+  }
   async getRepositoryStats(repositoryId) {
     const store = this.getStore(repositoryId);
     const entityTypeBreakdown = {};
@@ -3875,7 +4960,7 @@ var InMemoryStorageProvider = class {
       yield { type: "relationships", data: [], sequence: 0, isLast: true };
     }
   }
-  async importBulk(repositoryId, data) {
+  async importBulk(repositoryId, data, _options) {
     const store = this.getStore(repositoryId);
     let entitiesImported = 0;
     let relationshipsImported = 0;
@@ -4026,6 +5111,7 @@ var NoOpEmbeddingProvider = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CypherCompiler,
   DeepMemory,
   DeepMemoryError,
   DuplicateEntityError,
@@ -4035,6 +5121,8 @@ var NoOpEmbeddingProvider = class {
   EntityNotFoundError,
   ExportError,
   GovernanceDeniedError,
+  GraphTraversalProviderRequiredError,
+  GremlinCompiler,
   ImportError,
   InMemorySearchProvider,
   InMemoryStorageProvider,
@@ -4046,6 +5134,9 @@ var NoOpEmbeddingProvider = class {
   RelationshipConstraintError,
   RelationshipNotFoundError,
   RepositoryNotFoundError,
+  TraversalTimeoutError,
+  TraversalValidationError,
+  TraversalVocabularyError,
   VocabularyValidationError,
   generateId,
   isValidUuid,