@utaba/deep-memory 0.2.0 → 0.4.0

package/dist/index.js

@@ -277,6 +277,12 @@ var EntityManager = class {
     this.storage = storage;
     this.embedding = embedding;
   }
+  repositoryId;
+  vocabularyEngine;
+  provenanceTracker;
+  eventBus;
+  storage;
+  embedding;
   /** Create one or more entities with vocabulary validation, ID generation, provenance, and events */
   async create(inputs) {
     const results = [];
@@ -640,7 +646,7 @@ function jaroWinklerSimilarity(a, b, scalingFactor = 0.1) {
   }
   return jaro + commonPrefix * Math.min(scalingFactor, 0.25) * (1 - jaro);
 }
-function normaliseTypeName(name) {
+function normalizeTypeName(name) {
   return name.toLowerCase().trim().replace(/[-\s.]+/g, "_").replace(/[^a-z0-9_]/g, "");
 }
 function toScreamingSnakeCase(name) {
@@ -656,6 +662,11 @@ var RelationshipManager = class {
     this.eventBus = eventBus;
     this.storage = storage;
   }
+  repositoryId;
+  vocabularyEngine;
+  provenanceTracker;
+  eventBus;
+  storage;
   /** Create one or more relationships with vocabulary validation, provenance, and events */
   async create(inputs) {
     const results = [];
@@ -795,6 +806,7 @@ 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 {
@@ -808,37 +820,45 @@ function validateTraversalSpec(spec, vocabulary, capabilities) {
       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`);
-        }
+  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 spec.steps) {
+    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}`);
@@ -847,15 +867,15 @@ function validateTraversalSpec(spec, vocabulary, capabilities) {
   if (spec.offset !== void 0 && spec.offset < 0) {
     errors.push("offset must be >= 0");
   }
-  if (vocabulary && spec.steps) {
+  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 < spec.steps.length; i++) {
-      const step = spec.steps[i];
+    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)) {
@@ -909,7 +929,8 @@ var GremlinCompiler = class {
         parts.push(compilePropertyFilter(f, nextParam));
       }
     }
-    for (const step of spec.steps) {
+    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;
@@ -1091,8 +1112,9 @@ var CypherCompiler = class {
       }
     }
     let lastNode = startNode;
-    for (let i = 0; i < spec.steps.length; i++) {
-      const step = spec.steps[i];
+    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("|") : "";
@@ -1134,7 +1156,7 @@ 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}`);
+      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}`);
@@ -1215,6 +1237,7 @@ function matchesSingleFilter(properties, filter) {
 
 // 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();
@@ -1224,6 +1247,9 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
       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);
@@ -1236,7 +1262,7 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
   } else if (spec.start.entityType) {
     const result = await storage.findEntities(repositoryId, {
       entityTypes: [spec.start.entityType],
-      limit: spec.limit ?? 50,
+      limit: fetchLimit,
       offset: 0
     });
     storageCalls++;
@@ -1247,7 +1273,7 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
     }));
   } else if (spec.start.filter && spec.start.filter.length > 0) {
     const result = await storage.findEntities(repositoryId, {
-      limit: spec.limit ?? 50,
+      limit: fetchLimit,
       offset: 0
     });
     storageCalls++;
@@ -1262,8 +1288,9 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
       (entry) => matchesPropertyFilters(entry.entity.properties, spec.start.filter)
     );
   }
+  const steps = spec.steps ?? [];
   const allCollected = spec.returnMode === "all" ? [...frontier] : [];
-  for (const step of spec.steps) {
+  for (const step of steps) {
     checkCallLimit();
     if (step.repeat) {
       const result = await executeRepeatStep(
@@ -1316,10 +1343,89 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
   }
   const total = resultEntries.length;
   const paged = resultEntries.slice(offset, offset + limit);
-  const entities = paged.map((entry) => projectEntity(entry.entity, detailLevel));
+  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 (spec.returnMode === "path" || spec.returnMode === "all") {
+  if (!suppressEntities && (spec.returnMode === "path" || spec.returnMode === "all")) {
     const relMap = /* @__PURE__ */ new Map();
     for (const entry of paged) {
       for (const rel of entry.relationshipPath) {
@@ -1337,10 +1443,14 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
     }
     relationships = Array.from(relMap.values());
   }
-  if (spec.returnMode === "path") {
+  if (!suppressEntities && spec.returnMode === "path") {
     paths = paged.map((entry) => ({
       length: entry.entityPath.length - 1,
-      entities: [projectEntity(entry.entity, detailLevel)],
+      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,
@@ -1356,6 +1466,7 @@ async function executeFallbackTraversal(repositoryId, storage, spec) {
     entities,
     relationships,
     paths,
+    aggregations,
     total,
     returned: paged.length,
     hasMore: offset + limit < total,
@@ -1490,8 +1601,12 @@ var GraphTraversal = class {
     this.graphTraversalProvider = graphTraversalProvider;
     this.vocabularyEngine = vocabularyEngine;
   }
-  /** BFS neighbourhood exploration from a centre entity */
-  async exploreNeighbourhood(entityId, options) {
+  repositoryId;
+  storage;
+  graphTraversalProvider;
+  vocabularyEngine;
+  /** BFS neighborhood exploration from a center entity */
+  async exploreNeighborhood(entityId, options) {
     const storageOptions = {
       depth: options?.depth ?? 1,
       relationshipTypes: options?.relationshipTypes,
@@ -1501,13 +1616,13 @@ var GraphTraversal = class {
       offsetPerType: options?.offsetPerType ?? 0,
       relationshipPropertyFilters: options?.relationshipPropertyFilters
     };
-    const storageResult = await this.storage.exploreNeighbourhood(
+    const storageResult = await this.storage.exploreNeighborhood(
       this.repositoryId,
       entityId,
       storageOptions
     );
-    const centreEntity = await this.storage.getEntity(this.repositoryId, entityId);
-    if (!centreEntity) {
+    const centerEntity = await this.storage.getEntity(this.repositoryId, entityId);
+    if (!centerEntity) {
       throw new EntityNotFoundError(entityId);
     }
     const detailLevel = options?.detailLevel ?? "summary";
@@ -1531,11 +1646,11 @@ var GraphTraversal = class {
       return layer;
     });
     return {
-      centre: {
-        id: centreEntity.id,
-        slug: centreEntity.slug,
-        entityType: centreEntity.entityType,
-        label: centreEntity.label
+      center: {
+        id: centerEntity.id,
+        slug: centerEntity.slug,
+        entityType: centerEntity.entityType,
+        label: centerEntity.label
       },
       layers,
       statistics: {
@@ -2089,8 +2204,8 @@ var MemoryRepository = class {
     };
   }
   // ─── Graph Traversal ───────────────────────────────────────────────
-  async exploreNeighbourhood(entityId, options) {
-    return this.graphTraversal.exploreNeighbourhood(entityId, options);
+  async exploreNeighborhood(entityId, options) {
+    return this.graphTraversal.exploreNeighborhood(entityId, options);
   }
   async findPaths(sourceId, targetId, options) {
     return this.graphTraversal.findPaths(sourceId, targetId, options);
@@ -2120,7 +2235,7 @@ var MemoryRepository = class {
       storageOptions
     );
     const entity = await this.storage.getEntity(this.repositoryId, entityId);
-    const centreRef = {
+    const centerRef = {
       id: entityId,
       slug: entity?.slug ?? entityId,
       label: entity?.label ?? entityId
@@ -2166,7 +2281,7 @@ var MemoryRepository = class {
           timestamp: e.timestamp,
           eventType: e.eventType,
           description: `${rel.type} relationship created ${direction} ${otherRef.label}`,
-          relatedEntities: [centreRef, otherRef],
+          relatedEntities: [centerRef, otherRef],
           relationship: relDetail
         };
       }
@@ -2174,13 +2289,13 @@ var MemoryRepository = class {
       return {
         timestamp: e.timestamp,
         eventType: e.eventType,
-        description: `${centreRef.label} ${action}`,
-        relatedEntities: [centreRef]
+        description: `${centerRef.label} ${action}`,
+        relatedEntities: [centerRef]
       };
     });
     return {
       id: entityId,
-      slug: centreRef.slug,
+      slug: centerRef.slug,
       totalEvents: storageResult.total,
       returned: events.length,
       events
@@ -2190,6 +2305,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);
@@ -2211,14 +2378,14 @@ var SemanticDeduplicator = class {
   /**
    * Check whether a proposed type name is a duplicate of an existing type.
    * Uses embedding similarity if an EmbeddingProvider is available, otherwise falls back
-   * to Jaro-Winkler string similarity on normalised type names.
+   * to Jaro-Winkler string similarity on normalized type names.
    */
   async checkDuplicate(proposedType, proposedDescription, existingTypes) {
     if (existingTypes.length === 0) {
       return { isDuplicate: false, matches: [] };
     }
-    const normProposed = normaliseTypeName(proposedType);
-    const exactMatch = existingTypes.find((t) => normaliseTypeName(t.type) === normProposed);
+    const normProposed = normalizeTypeName(proposedType);
+    const exactMatch = existingTypes.find((t) => normalizeTypeName(t.type) === normProposed);
     if (exactMatch) {
       return {
         isDuplicate: true,
@@ -2254,10 +2421,10 @@ var SemanticDeduplicator = class {
     };
   }
   checkWithStringSimilarity(proposedType, existingTypes) {
-    const normProposed = normaliseTypeName(proposedType);
+    const normProposed = normalizeTypeName(proposedType);
     const matches = [];
     for (const existing of existingTypes) {
-      const normExisting = normaliseTypeName(existing.type);
+      const normExisting = normalizeTypeName(existing.type);
       const similarity = jaroWinklerSimilarity(normProposed, normExisting);
       if (similarity >= this.threshold) {
         matches.push({
@@ -2418,7 +2585,7 @@ function canPropose(governanceConfig, _proposal) {
     case "locked":
       return {
         allowed: false,
-        reason: "Vocabulary is locked. Only organisation admins can modify the vocabulary via the admin API."
+        reason: "Vocabulary is locked. Only organization admins can modify the vocabulary via the admin API."
       };
     case "managed":
     case "open":
@@ -2858,9 +3025,9 @@ function validateEntityUpdate(input, entityTypeDef) {
   return ok();
 }
 function validateRelationship(input, vocabulary, sourceEntityType, targetEntityType) {
-  const normalisedType = toScreamingSnakeCase(input.relationshipType);
+  const normalizedType = toScreamingSnakeCase(input.relationshipType);
   const relTypeDef = vocabulary.relationshipTypes.find(
-    (rt) => rt.type === normalisedType
+    (rt) => rt.type === normalizedType
   );
   if (!relTypeDef) {
     const closest = findClosestType(input.relationshipType, vocabulary.relationshipTypes);
@@ -3185,7 +3352,7 @@ var EventBus = class {
 };
 
 // src/portability/RepositoryExporter.ts
-var LIBRARY_VERSION = true ? "0.2.0" : "0.1.0";
+var LIBRARY_VERSION = true ? "0.4.0" : "0.1.0";
 var RepositoryExporter = class {
   storage;
   provenance;
@@ -3401,7 +3568,7 @@ function diffArrays(from, to) {
 // src/portability/MigrationEngine.ts
 var MigrationEngine = class {
   /**
-   * Analyse and migrate vocabulary differences between source and target.
+   * Analyze and migrate vocabulary differences between source and target.
    *
    * @param sourceVocabulary - vocabulary from the export archive
    * @param targetVocabulary - vocabulary in the target repository
@@ -3528,13 +3695,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.
@@ -3585,26 +3761,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",
@@ -3612,6 +3796,15 @@ var RepositoryImporter = class {
           id: e.item
         });
       }
+      await this.onProgress?.({
+        repositoryId: target.repositoryId,
+        entitiesImported,
+        relationshipsImported,
+        totalEntities,
+        totalRelationships,
+        chunksCompleted,
+        totalChunks
+      });
     }
     return {
       success: true,
@@ -3659,11 +3852,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) {
@@ -3745,6 +3942,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"
@@ -3801,7 +4008,7 @@ var DeepMemory = class {
   graphTraversalProvider;
   provenance;
   globalEventBus;
-  initialised = false;
+  initialized = false;
   constructor(config) {
     this.storage = config.storage;
     this.search = config.search;
@@ -3811,16 +4018,16 @@ var DeepMemory = class {
     this.provenance = new ProvenanceTracker(config.provenance);
     this.globalEventBus = new EventBus(config.provenance);
   }
-  /** Initialise the storage provider and optional providers (call once before use) */
-  async ensureInitialised() {
-    if (!this.initialised) {
-      if (this.storage.initialise) {
-        await this.storage.initialise();
+  /** Initialize the storage provider and optional providers (call once before use) */
+  async ensureInitialized() {
+    if (!this.initialized) {
+      if (this.storage.initialize) {
+        await this.storage.initialize();
       }
-      if (this.graphTraversalProvider?.initialise) {
-        await this.graphTraversalProvider.initialise();
+      if (this.graphTraversalProvider?.initialize) {
+        await this.graphTraversalProvider.initialize();
       }
-      this.initialised = true;
+      this.initialized = true;
     }
   }
   /** Create or migrate the storage schema. Call once at deployment / startup, not per-request. */
@@ -3832,15 +4039,15 @@ var DeepMemory = class {
       schemaVersion: 0
     };
     try {
-      await this.ensureInitialised();
+      await this.ensureInitialized();
     } catch {
     }
     let result = noOpResult;
     if (this.storage.ensureSchema) {
       result = await this.storage.ensureSchema();
     }
-    if (!this.initialised) {
-      await this.ensureInitialised();
+    if (!this.initialized) {
+      await this.ensureInitialized();
     }
     return result;
   }
@@ -3855,7 +4062,7 @@ var DeepMemory = class {
   }
   /** Create a new memory repository */
   async createRepository(config) {
-    await this.ensureInitialised();
+    await this.ensureInitialized();
     const repositoryId = config.repositoryId ?? generateId();
     this.validateRepositoryId(repositoryId);
     const context = this.provenance.getContext();
@@ -3912,7 +4119,7 @@ var DeepMemory = class {
   }
   /** Open an existing repository */
   async openRepository(repositoryId) {
-    await this.ensureInitialised();
+    await this.ensureInitialized();
     this.validateRepositoryId(repositoryId);
     const storedRepo = await this.storage.getRepository(repositoryId);
     if (!storedRepo) {
@@ -3941,7 +4148,7 @@ var DeepMemory = class {
   }
   /** List all repositories */
   async listRepositories(filter) {
-    await this.ensureInitialised();
+    await this.ensureInitialized();
     const result = await this.storage.listRepositories(filter);
     return {
       items: result.items.map((stored) => ({
@@ -3959,7 +4166,7 @@ var DeepMemory = class {
   }
   /** Update repository metadata and settings */
   async updateRepository(repositoryId, updates) {
-    await this.ensureInitialised();
+    await this.ensureInitialized();
     this.validateRepositoryId(repositoryId);
     const updated = await this.storage.updateRepository(repositoryId, updates);
     await this.globalEventBus.emit("repository:updated", { repositoryId });
@@ -3967,14 +4174,55 @@ var DeepMemory = class {
   }
   /** Delete a repository */
   async deleteRepository(repositoryId) {
-    await this.ensureInitialised();
+    await this.ensureInitialized();
     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.ensureInitialized();
+    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, options) {
-    await this.ensureInitialised();
+    await this.ensureInitialized();
+    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(),
@@ -3990,10 +4238,12 @@ var DeepMemory = class {
   }
   /** Import a repository from a portable archive */
   async importRepository(archive, options) {
-    await this.ensureInitialised();
+    await this.ensureInitialized();
+    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) {
@@ -4016,21 +4266,50 @@ var DeepMemory = class {
    * Use for large repositories to avoid loading everything into memory.
    */
   async *exportRepositoryStream(repositoryId, options) {
-    await this.ensureInitialised();
+    await this.ensureInitialized();
     const exporter = new RepositoryExporter({
       storage: this.storage,
       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", {
@@ -4044,10 +4323,11 @@ var DeepMemory = class {
    * Use for large repositories to avoid loading everything into memory.
    */
   async importRepositoryStream(header, chunks, options) {
-    await this.ensureInitialised();
+    await this.ensureInitialized();
     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);
@@ -4083,7 +4363,7 @@ var DeepMemory = class {
     if (this.storage.dispose) {
       await this.storage.dispose();
     }
-    this.initialised = false;
+    this.initialized = false;
   }
 };
 
@@ -4098,7 +4378,7 @@ var InMemoryStorageProvider = class {
     return store;
   }
   // ─── Lifecycle ─────────────────────────────────────────────────────
-  async initialise() {
+  async initialize() {
   }
   async dispose() {
     this.stores.clear();
@@ -4171,12 +4451,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 = {};
@@ -4406,7 +4695,7 @@ var InMemoryStorageProvider = class {
     return { deletedRelationships };
   }
   // ─── Graph Traversal ───────────────────────────────────────────────
-  async exploreNeighbourhood(repositoryId, entityId, options) {
+  async exploreNeighborhood(repositoryId, entityId, options) {
     const store = this.getStore(repositoryId);
     if (!store.entities.has(entityId)) {
       throw new EntityNotFoundError(entityId);
@@ -4472,7 +4761,7 @@ var InMemoryStorageProvider = class {
       if (nextFrontier.size === 0) break;
     }
     return {
-      centreId: entityId,
+      centerId: entityId,
       layers
     };
   }
@@ -4631,7 +4920,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;