@utaba/deep-memory 0.1.0

package/dist/index.cjs

@@ -0,0 +1,4054 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  DeepMemory: () => DeepMemory,
+  DeepMemoryError: () => DeepMemoryError,
+  DuplicateEntityError: () => DuplicateEntityError,
+  DuplicateRelationshipError: () => DuplicateRelationshipError,
+  DuplicateRepositoryError: () => DuplicateRepositoryError,
+  EmbeddingProviderRequiredError: () => EmbeddingProviderRequiredError,
+  EntityNotFoundError: () => EntityNotFoundError,
+  ExportError: () => ExportError,
+  GovernanceDeniedError: () => GovernanceDeniedError,
+  ImportError: () => ImportError,
+  InMemorySearchProvider: () => InMemorySearchProvider,
+  InMemoryStorageProvider: () => InMemoryStorageProvider,
+  InvalidInputError: () => InvalidInputError,
+  MemoryRepository: () => MemoryRepository,
+  NoOpEmbeddingProvider: () => NoOpEmbeddingProvider,
+  OperationCancelledError: () => OperationCancelledError,
+  ProviderError: () => ProviderError,
+  RelationshipConstraintError: () => RelationshipConstraintError,
+  RelationshipNotFoundError: () => RelationshipNotFoundError,
+  RepositoryNotFoundError: () => RepositoryNotFoundError,
+  VocabularyValidationError: () => VocabularyValidationError,
+  generateId: () => generateId,
+  isValidUuid: () => isValidUuid,
+  matchesPropertyFilters: () => matchesPropertyFilters
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/core/errors.ts
+var DeepMemoryError = class extends Error {
+  code;
+  suggestion;
+  constructor(code, message, suggestion) {
+    super(message);
+    this.name = "DeepMemoryError";
+    this.code = code;
+    this.suggestion = suggestion;
+  }
+};
+var InvalidInputError = class extends DeepMemoryError {
+  field;
+  constructor(field, message, suggestion) {
+    super(
+      "INVALID_INPUT",
+      message,
+      suggestion ?? `Check the value of "${field}" and try again.`
+    );
+    this.name = "InvalidInputError";
+    this.field = field;
+  }
+};
+var EntityNotFoundError = class extends DeepMemoryError {
+  id;
+  slug;
+  constructor(idOrSlug, slug) {
+    super(
+      "ENTITY_NOT_FOUND",
+      `Entity "${idOrSlug}" not found`,
+      `Check the entity ID or slug is correct. Use findEntities() to search by label if unknown.`
+    );
+    this.name = "EntityNotFoundError";
+    this.id = idOrSlug;
+    this.slug = slug;
+  }
+};
+var DuplicateEntityError = class extends DeepMemoryError {
+  id;
+  constructor(id) {
+    super(
+      "ENTITY_ALREADY_EXISTS",
+      `Entity "${id}" already exists`,
+      `Use updateEntity() to modify an existing entity, or omit id to auto-generate a unique one.`
+    );
+    this.name = "DuplicateEntityError";
+    this.id = id;
+  }
+};
+var RelationshipNotFoundError = class extends DeepMemoryError {
+  relationshipId;
+  constructor(relationshipId) {
+    super(
+      "RELATIONSHIP_NOT_FOUND",
+      `Relationship "${relationshipId}" not found`,
+      `Check the relationship ID is correct. Use getRelationships() to list relationships for an entity.`
+    );
+    this.name = "RelationshipNotFoundError";
+    this.relationshipId = relationshipId;
+  }
+};
+var DuplicateRelationshipError = class extends DeepMemoryError {
+  relationshipId;
+  constructor(relationshipId) {
+    super(
+      "RELATIONSHIP_ALREADY_EXISTS",
+      `Relationship "${relationshipId}" already exists`,
+      `Omit relationshipId to auto-generate a unique one, or use a different explicit ID.`
+    );
+    this.name = "DuplicateRelationshipError";
+    this.relationshipId = relationshipId;
+  }
+};
+var RepositoryNotFoundError = class extends DeepMemoryError {
+  repositoryId;
+  constructor(repositoryId) {
+    super(
+      "REPOSITORY_NOT_FOUND",
+      `Repository "${repositoryId}" not found`,
+      `Use listRepositories() to see available repositories, or createRepository() to create a new one.`
+    );
+    this.name = "RepositoryNotFoundError";
+    this.repositoryId = repositoryId;
+  }
+};
+var DuplicateRepositoryError = class extends DeepMemoryError {
+  repositoryId;
+  constructor(repositoryId) {
+    super(
+      "REPOSITORY_ALREADY_EXISTS",
+      `Repository "${repositoryId}" already exists`,
+      `Use openRepository() to access an existing repository, or choose a different ID.`
+    );
+    this.name = "DuplicateRepositoryError";
+    this.repositoryId = repositoryId;
+  }
+};
+var VocabularyValidationError = class extends DeepMemoryError {
+  errors;
+  constructor(errors) {
+    const errorMsg = errors.map((e) => e.message).join("; ");
+    const suggestions = errors.filter((e) => e.suggestion).map((e) => e.suggestion);
+    super(
+      "VOCABULARY_VALIDATION_FAILED",
+      `Vocabulary validation failed: ${errorMsg}`,
+      suggestions.length > 0 ? suggestions.join(" ") : `Check the repository vocabulary with getVocabulary() to see valid types and properties.`
+    );
+    this.name = "VocabularyValidationError";
+    this.errors = errors;
+  }
+};
+var RelationshipConstraintError = class extends DeepMemoryError {
+  relationshipType;
+  sourceType;
+  targetType;
+  constructor(relationshipType, message, sourceType, targetType) {
+    super(
+      "RELATIONSHIP_CONSTRAINT_FAILED",
+      message,
+      `Check the vocabulary for allowed source/target types on "${relationshipType}".`
+    );
+    this.name = "RelationshipConstraintError";
+    this.relationshipType = relationshipType;
+    this.sourceType = sourceType;
+    this.targetType = targetType;
+  }
+};
+var GovernanceDeniedError = class extends DeepMemoryError {
+  governanceMode;
+  constructor(governanceMode, reason) {
+    super(
+      "GOVERNANCE_DENIED",
+      `Governance denied: ${reason}`,
+      governanceMode === "locked" ? `The vocabulary is locked. Change governance mode to "managed" or "open" to allow modifications.` : `The operation was denied by governance rules. Review the governance configuration.`
+    );
+    this.name = "GovernanceDeniedError";
+    this.governanceMode = governanceMode;
+  }
+};
+var OperationCancelledError = class extends DeepMemoryError {
+  operation;
+  reason;
+  constructor(operation, reason) {
+    super(
+      "OPERATION_CANCELLED",
+      `${operation} cancelled: ${reason}`,
+      `A pre-mutation hook cancelled this operation. Review registered hooks if this is unexpected.`
+    );
+    this.name = "OperationCancelledError";
+    this.operation = operation;
+    this.reason = reason;
+  }
+};
+var EmbeddingProviderRequiredError = class extends DeepMemoryError {
+  constructor() {
+    super(
+      "EMBEDDING_PROVIDER_REQUIRED",
+      "EmbeddingProvider required: no embedding provider is configured",
+      `Provide an EmbeddingProvider in the DeepMemory config to use semantic search (searchByConcept).`
+    );
+    this.name = "EmbeddingProviderRequiredError";
+  }
+};
+var ImportError = class extends DeepMemoryError {
+  constructor(message, suggestion) {
+    super(
+      "IMPORT_ERROR",
+      message,
+      suggestion ?? `Verify the archive format and check that the target repository is accessible.`
+    );
+    this.name = "ImportError";
+  }
+};
+var ExportError = class extends DeepMemoryError {
+  constructor(message, suggestion) {
+    super(
+      "EXPORT_ERROR",
+      message,
+      suggestion ?? `Verify the repository exists and the storage provider is accessible.`
+    );
+    this.name = "ExportError";
+  }
+};
+var ProviderError = class extends DeepMemoryError {
+  constructor(message, suggestion) {
+    super(
+      "PROVIDER_ERROR",
+      message,
+      suggestion ?? `Check provider configuration and connectivity.`
+    );
+    this.name = "ProviderError";
+  }
+};
+
+// src/entities/IdGenerator.ts
+function slugify(text) {
+  return text.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function generateSlug(entityType, label) {
+  const slug = slugify(label);
+  return `${entityType}:${slug || "unnamed"}`;
+}
+async function generateUniqueSlug(entityType, label, existsCheck) {
+  const baseSlug = generateSlug(entityType, label);
+  if (!await existsCheck(baseSlug)) {
+    return baseSlug;
+  }
+  for (let i = 2; i <= 100; i++) {
+    const candidateSlug = `${baseSlug}-${i}`;
+    if (!await existsCheck(candidateSlug)) {
+      return candidateSlug;
+    }
+  }
+  const randomSuffix = Math.random().toString(36).slice(2, 8);
+  return `${baseSlug}-${randomSuffix}`;
+}
+function generateEntityId() {
+  return generateId();
+}
+function generateRelationshipId() {
+  return generateId();
+}
+
+// src/entities/EntityManager.ts
+var EntityManager = class {
+  constructor(repositoryId, vocabularyEngine, provenanceTracker, eventBus, storage, embedding) {
+    this.repositoryId = repositoryId;
+    this.vocabularyEngine = vocabularyEngine;
+    this.provenanceTracker = provenanceTracker;
+    this.eventBus = eventBus;
+    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;
+      }
+    );
+    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;
+  }
+  /** Update an existing entity */
+  async update(entityId, updates) {
+    const existing = await this.storage.getEntity(this.repositoryId, entityId);
+    if (!existing) {
+      throw new EntityNotFoundError(entityId);
+    }
+    const validation = await this.vocabularyEngine.validateEntityUpdate(
+      updates,
+      existing.entityType
+    );
+    if (!validation.valid) {
+      await this.eventBus.emit("validation:failed", {
+        operation: "updateEntity",
+        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("entity:updating", {
+      id: entityId,
+      updates
+    });
+    if (hookResult.cancelled) {
+      throw new OperationCancelledError("Entity update", hookResult.reason ?? "cancelled by hook");
+    }
+    const provenance = this.provenanceTracker.stampUpdate(existing.provenance);
+    const mergedProperties = updates.properties ? { ...existing.properties, ...updates.properties } : existing.properties;
+    const needsReembed = updates.reembed === true || updates.label !== void 0 || updates.summary !== void 0;
+    const entityEmbedding = needsReembed ? await this.generateEmbedding(
+      updates.label ?? existing.label,
+      updates.summary !== void 0 ? updates.summary : existing.summary
+    ) : void 0;
+    const updated = await this.storage.updateEntity(this.repositoryId, entityId, {
+      label: updates.label,
+      summary: updates.summary,
+      properties: updates.properties ? mergedProperties : void 0,
+      data: updates.data,
+      dataFormat: updates.dataFormat,
+      provenance,
+      embedding: entityEmbedding
+    });
+    const entity = storedToEntity(updated);
+    await this.eventBus.emit("entity:updated", { entity });
+    return entity;
+  }
+  /** Get a single entity with configurable detail level */
+  async get(entityId, detailLevel = "full") {
+    const stored = await this.storage.getEntity(this.repositoryId, entityId);
+    if (!stored) return null;
+    switch (detailLevel) {
+      case "brief":
+        return storedToBrief(stored);
+      case "summary":
+        return storedToSummary(stored);
+      case "full":
+      default:
+        return storedToEntity(stored);
+    }
+  }
+  /** Get an entity by its slug */
+  async getBySlug(slug, detailLevel = "full") {
+    const stored = await this.storage.getEntityBySlug(this.repositoryId, slug);
+    if (!stored) return null;
+    switch (detailLevel) {
+      case "brief":
+        return storedToBrief(stored);
+      case "summary":
+        return storedToSummary(stored);
+      case "full":
+      default:
+        return storedToEntity(stored);
+    }
+  }
+  /** Get multiple entities in a single call (max 50, brief or summary only) */
+  async getMany(entityIds, detailLevel = "summary") {
+    const ids = entityIds.slice(0, 50);
+    const storedMap = await this.storage.getEntities(this.repositoryId, ids);
+    const result = /* @__PURE__ */ new Map();
+    for (const [id, stored] of storedMap) {
+      result.set(
+        id,
+        detailLevel === "brief" ? storedToBrief(stored) : storedToSummary(stored)
+      );
+    }
+    return result;
+  }
+  /** Find entities by search criteria */
+  async find(query) {
+    const storageQuery = {
+      searchTerm: query.searchTerm,
+      entityTypes: query.entityTypes,
+      properties: query.properties,
+      limit: Math.min(query.limit ?? 10, 50),
+      offset: query.offset ?? 0
+    };
+    const result = await this.storage.findEntities(this.repositoryId, storageQuery);
+    return {
+      items: result.items.map(storedToSummary),
+      total: result.total,
+      hasMore: result.hasMore,
+      limit: result.limit,
+      offset: result.offset
+    };
+  }
+  /** Delete an entity */
+  async delete(entityId) {
+    const existing = await this.storage.getEntity(this.repositoryId, entityId);
+    if (!existing) {
+      throw new EntityNotFoundError(entityId);
+    }
+    const hookResult = await this.eventBus.emitHook("entity:deleting", { id: entityId });
+    if (hookResult.cancelled) {
+      throw new OperationCancelledError("Entity deletion", hookResult.reason ?? "cancelled by hook");
+    }
+    await this.storage.deleteEntity(this.repositoryId, entityId);
+    await this.eventBus.emit("entity:deleted", { id: entityId });
+  }
+  /**
+   * Re-embed a specific set of entities using the current EmbeddingProvider.
+   * Retries embedBatch up to maxRetries times with exponential backoff on failure.
+   */
+  async reembedEntities(entityIds, options) {
+    if (!this.embedding) {
+      throw new EmbeddingProviderRequiredError();
+    }
+    const maxRetries = options?.maxRetries ?? 3;
+    const storedMap = await this.storage.getEntities(this.repositoryId, entityIds);
+    const entries = Array.from(storedMap.entries());
+    const texts = entries.map(([, e]) => [e.label, e.summary ?? ""].join(" "));
+    let embeddings;
+    let attempt = 0;
+    while (true) {
+      try {
+        embeddings = await this.embedding.embedBatch(texts);
+        break;
+      } catch (err) {
+        attempt++;
+        if (attempt > maxRetries) {
+          const errorMsg = err instanceof Error ? err.message : String(err);
+          return {
+            processed: 0,
+            failed: entries.length,
+            errors: entries.map(([id]) => ({ entityId: id, error: `embedBatch failed after ${maxRetries} retries: ${errorMsg}` })),
+            modelId: this.embedding.modelId(),
+            dimensions: this.embedding.dimensions()
+          };
+        }
+        const backoffMs = 1e3 * 2 ** (attempt - 1);
+        await new Promise((resolve) => {
+          setTimeout(resolve, backoffMs);
+        });
+      }
+    }
+    const errors = [];
+    let processed = 0;
+    for (let i = 0; i < entries.length; i++) {
+      const [id, entity] = entries[i];
+      try {
+        await this.storage.updateEntity(this.repositoryId, id, {
+          provenance: entity.provenance,
+          // preserve existing provenance — not a content edit
+          embedding: embeddings[i]
+        });
+        processed++;
+      } catch (err) {
+        errors.push({ entityId: id, error: err instanceof Error ? err.message : String(err) });
+      }
+    }
+    return {
+      processed,
+      failed: errors.length,
+      errors,
+      modelId: this.embedding.modelId(),
+      dimensions: this.embedding.dimensions()
+    };
+  }
+  /**
+   * Re-embed all entities in the repository, processing in batches.
+   * @param options.batchSize — entities per batch (default 50)
+   * @param options.maxRetries — retries per batch on embedding failure (default 3)
+   * @param options.errorThresholdToAbort — abort after this many cumulative failures (default: no limit)
+   * @param options.delayBetweenBatchesMs — milliseconds to wait between batches for rate limiting (default 0)
+   * @param options.onProgress — callback invoked after each batch
+   */
+  async reembedAll(options) {
+    if (!this.embedding) {
+      throw new EmbeddingProviderRequiredError();
+    }
+    const batchSize = options?.batchSize ?? 50;
+    const errorThreshold = options?.errorThresholdToAbort;
+    const firstPage = await this.storage.findEntities(this.repositoryId, { limit: 1, offset: 0 });
+    const total = firstPage.total;
+    let totalProcessed = 0;
+    let totalFailed = 0;
+    const allErrors = [];
+    let offset = 0;
+    while (offset < total) {
+      const page = await this.storage.findEntities(this.repositoryId, {
+        limit: batchSize,
+        offset
+      });
+      if (page.items.length === 0) break;
+      const ids = page.items.map((e) => e.id);
+      const result = await this.reembedEntities(ids, {
+        maxRetries: options?.maxRetries
+      });
+      totalProcessed += result.processed;
+      totalFailed += result.failed;
+      allErrors.push(...result.errors);
+      options?.onProgress?.(totalProcessed, total, totalFailed);
+      if (errorThreshold !== void 0 && totalFailed >= errorThreshold) {
+        allErrors.push({ entityId: "", error: `Aborted: error threshold of ${errorThreshold} reached (${totalFailed} failures)` });
+        break;
+      }
+      offset += page.items.length;
+      const delayMs = options?.delayBetweenBatchesMs ?? 0;
+      if (delayMs > 0 && offset < total) {
+        await new Promise((resolve) => {
+          setTimeout(resolve, delayMs);
+        });
+      }
+    }
+    return {
+      processed: totalProcessed,
+      failed: totalFailed,
+      errors: allErrors,
+      modelId: this.embedding.modelId(),
+      dimensions: this.embedding.dimensions()
+    };
+  }
+  /** Generate an embedding vector from label + summary if a provider is available */
+  async generateEmbedding(label, summary) {
+    if (!this.embedding) return void 0;
+    const text = [label, summary ?? ""].join(" ");
+    return this.embedding.embed(text);
+  }
+};
+function storedToEntity(stored) {
+  return {
+    id: stored.id,
+    slug: stored.slug,
+    entityType: stored.entityType,
+    label: stored.label,
+    summary: stored.summary,
+    properties: stored.properties,
+    data: stored.data,
+    dataFormat: stored.dataFormat,
+    provenance: stored.provenance
+  };
+}
+function storedToSummary(stored) {
+  return {
+    id: stored.id,
+    slug: stored.slug,
+    entityType: stored.entityType,
+    label: stored.label,
+    summary: stored.summary,
+    properties: stored.properties
+  };
+}
+function storedToBrief(stored) {
+  return {
+    id: stored.id,
+    slug: stored.slug,
+    entityType: stored.entityType,
+    label: stored.label,
+    summary: stored.summary
+  };
+}
+
+// src/vocabulary/similarity.ts
+function jaroSimilarity(a, b) {
+  if (a === b) return 1;
+  if (a.length === 0 || b.length === 0) return 0;
+  const matchWindow = Math.max(Math.floor(Math.max(a.length, b.length) / 2) - 1, 0);
+  const aMatches = new Array(a.length).fill(false);
+  const bMatches = new Array(b.length).fill(false);
+  let matches = 0;
+  let transpositions = 0;
+  for (let i = 0; i < a.length; i++) {
+    const start = Math.max(0, i - matchWindow);
+    const end = Math.min(i + matchWindow + 1, b.length);
+    for (let j = start; j < end; j++) {
+      if (bMatches[j] || a[i] !== b[j]) continue;
+      aMatches[i] = true;
+      bMatches[j] = true;
+      matches++;
+      break;
+    }
+  }
+  if (matches === 0) return 0;
+  let k = 0;
+  for (let i = 0; i < a.length; i++) {
+    if (!aMatches[i]) continue;
+    while (!bMatches[k]) k++;
+    if (a[i] !== b[k]) transpositions++;
+    k++;
+  }
+  return (matches / a.length + matches / b.length + (matches - transpositions / 2) / matches) / 3;
+}
+function jaroWinklerSimilarity(a, b, scalingFactor = 0.1) {
+  const jaro = jaroSimilarity(a, b);
+  if (jaro === 0) return 0;
+  const prefixLength = Math.min(4, Math.min(a.length, b.length));
+  let commonPrefix = 0;
+  for (let i = 0; i < prefixLength; i++) {
+    if (a[i] === b[i]) {
+      commonPrefix++;
+    } else {
+      break;
+    }
+  }
+  return jaro + commonPrefix * Math.min(scalingFactor, 0.25) * (1 - jaro);
+}
+function normaliseTypeName(name) {
+  return name.toLowerCase().trim().replace(/[-\s.]+/g, "_").replace(/[^a-z0-9_]/g, "");
+}
+function toScreamingSnakeCase(name) {
+  return name.trim().replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/[-\s.]+/g, "_").replace(/[^A-Za-z0-9_]/g, "").replace(/_+/g, "_").replace(/^_+|_+$/g, "").toUpperCase();
+}
+
+// src/relationships/RelationshipManager.ts
+var RelationshipManager = class {
+  constructor(repositoryId, vocabularyEngine, provenanceTracker, eventBus, storage) {
+    this.repositoryId = repositoryId;
+    this.vocabularyEngine = vocabularyEngine;
+    this.provenanceTracker = provenanceTracker;
+    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"
+      );
+    }
+    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;
+  }
+  /** Remove a relationship by ID */
+  async remove(relationshipId) {
+    const existing = await this.storage.getRelationship(this.repositoryId, relationshipId);
+    if (!existing) {
+      throw new RelationshipNotFoundError(relationshipId);
+    }
+    const hookResult = await this.eventBus.emitHook("relationship:removing", { id: relationshipId });
+    if (hookResult.cancelled) {
+      throw new OperationCancelledError(
+        "Relationship removal",
+        hookResult.reason ?? "cancelled by hook"
+      );
+    }
+    await this.storage.deleteRelationship(this.repositoryId, relationshipId);
+    await this.eventBus.emit("relationship:removed", { id: relationshipId });
+  }
+  /** Get relationships for an entity with filtering */
+  async getForEntity(entityId, options) {
+    const result = await this.storage.getEntityRelationships(
+      this.repositoryId,
+      entityId,
+      options
+    );
+    return {
+      items: result.items.map(storedToRelationship),
+      total: result.total,
+      hasMore: result.hasMore,
+      limit: result.limit,
+      offset: result.offset
+    };
+  }
+};
+function storedToRelationship(stored) {
+  return {
+    id: stored.id,
+    relationshipType: stored.relationshipType,
+    sourceEntityId: stored.sourceEntityId,
+    targetEntityId: stored.targetEntityId,
+    properties: stored.properties,
+    bidirectional: stored.bidirectional,
+    provenance: stored.provenance
+  };
+}
+
+// src/entities/entityProjection.ts
+function projectEntity(stored, level) {
+  switch (level) {
+    case "brief":
+      return {
+        id: stored.id,
+        slug: stored.slug,
+        entityType: stored.entityType,
+        label: stored.label,
+        summary: stored.summary
+      };
+    case "summary":
+      return {
+        id: stored.id,
+        slug: stored.slug,
+        entityType: stored.entityType,
+        label: stored.label,
+        summary: stored.summary,
+        properties: stored.properties
+      };
+    case "full":
+      return {
+        id: stored.id,
+        slug: stored.slug,
+        entityType: stored.entityType,
+        label: stored.label,
+        summary: stored.summary,
+        properties: stored.properties,
+        data: stored.data,
+        dataFormat: stored.dataFormat,
+        provenance: stored.provenance
+      };
+  }
+}
+
+// src/relationships/GraphTraversal.ts
+var GraphTraversal = class {
+  constructor(repositoryId, storage) {
+    this.repositoryId = repositoryId;
+    this.storage = storage;
+  }
+  /** BFS neighbourhood exploration from a centre entity */
+  async exploreNeighbourhood(entityId, options) {
+    const storageOptions = {
+      depth: options?.depth ?? 1,
+      relationshipTypes: options?.relationshipTypes,
+      entityTypes: options?.entityTypes,
+      direction: options?.direction ?? "both",
+      limitPerType: options?.limitPerType ?? 10,
+      offsetPerType: options?.offsetPerType ?? 0,
+      relationshipPropertyFilters: options?.relationshipPropertyFilters
+    };
+    const storageResult = await this.storage.exploreNeighbourhood(
+      this.repositoryId,
+      entityId,
+      storageOptions
+    );
+    const centreEntity = await this.storage.getEntity(this.repositoryId, entityId);
+    if (!centreEntity) {
+      throw new EntityNotFoundError(entityId);
+    }
+    const detailLevel = options?.detailLevel ?? "summary";
+    let totalEntities = 0;
+    let returnedEntities = 0;
+    const truncatedTypes = [];
+    const layers = storageResult.layers.map((storageLayer) => {
+      const layer = {};
+      for (const [relType, group] of Object.entries(storageLayer)) {
+        totalEntities += group.total;
+        returnedEntities += group.entities.length;
+        if (group.entities.length < group.total && !truncatedTypes.includes(relType)) {
+          truncatedTypes.push(relType);
+        }
+        layer[relType] = {
+          total: group.total,
+          returned: group.entities.length,
+          entities: group.entities.map((e) => projectEntity(e, detailLevel))
+        };
+      }
+      return layer;
+    });
+    return {
+      centre: {
+        id: centreEntity.id,
+        slug: centreEntity.slug,
+        entityType: centreEntity.entityType,
+        label: centreEntity.label
+      },
+      layers,
+      statistics: {
+        totalEntities,
+        returnedEntities,
+        truncatedTypes
+      }
+    };
+  }
+  /** BFS shortest path finding between two entities */
+  async findPaths(sourceId, targetId, options) {
+    const storageOptions = {
+      maxDepth: options?.maxDepth ?? 3,
+      relationshipTypes: options?.relationshipTypes,
+      entityTypes: options?.entityTypes,
+      limit: options?.limit ?? 5,
+      offset: options?.offset ?? 0,
+      relationshipPropertyFilters: options?.relationshipPropertyFilters
+    };
+    const storageResult = await this.storage.findPaths(
+      this.repositoryId,
+      sourceId,
+      targetId,
+      storageOptions
+    );
+    const entityIdSet = /* @__PURE__ */ new Set();
+    const relIdSet = /* @__PURE__ */ new Set();
+    for (const path of storageResult.paths) {
+      for (const eid of path.entityIds) entityIdSet.add(eid);
+      for (const rid of path.relationshipIds) relIdSet.add(rid);
+    }
+    const entityMap = await this.storage.getEntities(
+      this.repositoryId,
+      Array.from(entityIdSet)
+    );
+    const relMap = /* @__PURE__ */ new Map();
+    for (const rid of relIdSet) {
+      const rel = await this.storage.getRelationship(this.repositoryId, rid);
+      if (rel) {
+        relMap.set(rid, {
+          id: rel.id,
+          type: rel.relationshipType,
+          sourceEntityId: rel.sourceEntityId,
+          properties: rel.properties
+        });
+      }
+    }
+    const entityTypeFilter = options?.entityTypes;
+    const filteredPaths = entityTypeFilter ? storageResult.paths.filter(
+      (sp) => sp.entityIds.every((eid) => {
+        const e = entityMap.get(eid);
+        return e ? entityTypeFilter.includes(e.entityType) : true;
+      })
+    ) : storageResult.paths;
+    const pathDetailLevel = options?.detailLevel ?? "brief";
+    return {
+      totalPaths: entityTypeFilter ? filteredPaths.length : storageResult.totalPaths,
+      returned: filteredPaths.length,
+      paths: filteredPaths.map((sp) => ({
+        length: sp.entityIds.length - 1,
+        entities: sp.entityIds.map((eid) => {
+          const e = entityMap.get(eid);
+          if (e) return projectEntity(e, pathDetailLevel);
+          return {
+            id: eid,
+            slug: eid,
+            entityType: "unknown",
+            label: eid,
+            summary: void 0
+          };
+        }),
+        relationships: sp.relationshipIds.map((rid, idx) => {
+          const r = relMap.get(rid);
+          const currentEntityId = sp.entityIds[idx];
+          return {
+            id: rid,
+            type: r?.type ?? "unknown",
+            direction: r?.sourceEntityId === currentEntityId ? "outbound" : "inbound",
+            properties: r?.properties ?? {}
+          };
+        })
+      }))
+    };
+  }
+};
+
+// src/search/SearchOrchestrator.ts
+var SearchOrchestrator = class {
+  repositoryId;
+  storage;
+  search;
+  embedding;
+  eventBus;
+  defaultSimilarityThreshold;
+  conceptSearchScanLimit;
+  constructor(config) {
+    this.repositoryId = config.repositoryId;
+    this.storage = config.storage;
+    this.search = config.search;
+    this.embedding = config.embedding;
+    this.eventBus = config.eventBus;
+    this.defaultSimilarityThreshold = config.defaultSimilarityThreshold ?? 0.5;
+    this.conceptSearchScanLimit = config.conceptSearchScanLimit ?? 1e3;
+  }
+  /**
+   * Find entities by label, type, and property filters.
+   * When a SearchProvider is available, its results are merged with
+   * storage-level results for better relevance ranking.
+   */
+  async findEntities(query) {
+    const limit = Math.min(query.limit ?? 10, 50);
+    const offset = query.offset ?? 0;
+    const detailLevel = query.detailLevel ?? "summary";
+    const storageQuery = {
+      searchTerm: query.searchTerm,
+      entityTypes: query.entityTypes,
+      properties: query.properties,
+      provenance: query.provenance,
+      limit,
+      offset
+    };
+    if (this.search && query.searchTerm) {
+      const [storageResult, searchResult] = await Promise.all([
+        this.storage.findEntities(this.repositoryId, storageQuery),
+        this.search.search(this.repositoryId, query.searchTerm, {
+          entityTypes: query.entityTypes,
+          limit: limit * 2,
+          // fetch more from search to merge
+          offset: 0
+        })
+      ]);
+      const merged = this.mergeResults(storageResult.items, searchResult.items, limit, offset, detailLevel);
+      await this.emitSearchEvent(query.searchTerm, merged.items.length);
+      return merged;
+    }
+    const result = await this.storage.findEntities(this.repositoryId, storageQuery);
+    if (query.searchTerm) {
+      await this.emitSearchEvent(query.searchTerm, result.items.length);
+    }
+    return {
+      items: result.items.map((e) => projectEntity(e, detailLevel)),
+      total: result.total,
+      hasMore: result.hasMore,
+      limit: result.limit,
+      offset: result.offset
+    };
+  }
+  /**
+   * Semantic concept search using the EmbeddingProvider.
+   * Embeds the query, then compares against entity embeddings.
+   * Falls back to label/summary text matching when no embeddings exist on entities.
+   */
+  async searchByConcept(query, options) {
+    if (!this.embedding) {
+      throw new EmbeddingProviderRequiredError();
+    }
+    const limit = Math.min(options?.limit ?? 10, 50);
+    const offset = options?.offset ?? 0;
+    const threshold = options?.similarityThreshold ?? this.defaultSimilarityThreshold;
+    const queryEmbedding = await this.embedding.embed(query);
+    const allEntities = await this.storage.findEntities(this.repositoryId, {
+      entityTypes: options?.entityTypes,
+      limit: this.conceptSearchScanLimit,
+      offset: 0
+    });
+    const scored = [];
+    for (const entity of allEntities.items) {
+      let score;
+      if (entity.embedding && entity.embedding.length > 0) {
+        score = this.cosineSimilarity(queryEmbedding, entity.embedding);
+      } else {
+        const entityText = [entity.label, entity.summary ?? ""].join(" ");
+        const entityEmbedding = await this.embedding.embed(entityText);
+        score = this.cosineSimilarity(queryEmbedding, entityEmbedding);
+      }
+      if (score >= threshold) {
+        scored.push({
+          id: entity.id,
+          slug: entity.slug,
+          entityType: entity.entityType,
+          label: entity.label,
+          summary: entity.summary,
+          score
+        });
+      }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    const total = scored.length;
+    const items = scored.slice(offset, offset + limit);
+    await this.emitSearchEvent(query, items.length);
+    return {
+      items,
+      total,
+      hasMore: offset + limit < total,
+      limit,
+      offset
+    };
+  }
+  /** Merge storage results with search provider results */
+  mergeResults(storageItems, searchHits, limit, offset, detailLevel = "summary") {
+    const scoreMap = /* @__PURE__ */ new Map();
+    for (const hit of searchHits) {
+      scoreMap.set(hit.id, hit.score);
+    }
+    const allEntityIds = /* @__PURE__ */ new Set();
+    const rankedItems = [];
+    for (const hit of searchHits) {
+      const storageEntity = storageItems.find((e) => e.id === hit.id);
+      if (storageEntity) {
+        rankedItems.push({ entity: storageEntity, score: hit.score });
+        allEntityIds.add(hit.id);
+      }
+    }
+    for (const entity of storageItems) {
+      if (!allEntityIds.has(entity.id)) {
+        rankedItems.push({ entity, score: 0 });
+        allEntityIds.add(entity.id);
+      }
+    }
+    rankedItems.sort((a, b) => b.score - a.score);
+    const total = rankedItems.length;
+    const page = rankedItems.slice(offset, offset + limit);
+    return {
+      items: page.map((r) => projectEntity(r.entity, detailLevel)),
+      total,
+      hasMore: offset + limit < total,
+      limit,
+      offset
+    };
+  }
+  /** Cosine similarity between two vectors */
+  cosineSimilarity(a, b) {
+    if (this.embedding?.similarity) {
+      return this.embedding.similarity(a, b);
+    }
+    if (a.length !== b.length || a.length === 0) return 0;
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      const ai = a[i];
+      const bi = b[i];
+      dotProduct += ai * bi;
+      normA += ai * ai;
+      normB += bi * bi;
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    return denominator === 0 ? 0 : dotProduct / denominator;
+  }
+  async emitSearchEvent(query, resultCount) {
+    if (this.eventBus) {
+      await this.eventBus.emit("search:executed", { query, resultCount });
+    }
+  }
+};
+
+// src/core/MemoryRepository.ts
+var MemoryRepository = class {
+  repositoryId;
+  storage;
+  search;
+  vocabularyEngine;
+  provenanceTracker;
+  eventBus;
+  entityManager;
+  relationshipManager;
+  graphTraversal;
+  searchOrchestrator;
+  constructor(config) {
+    this.repositoryId = config.repositoryId;
+    this.storage = config.storage;
+    this.search = config.search;
+    this.vocabularyEngine = config.vocabularyEngine;
+    this.provenanceTracker = config.provenanceTracker;
+    this.eventBus = config.eventBus;
+    this.entityManager = new EntityManager(
+      config.repositoryId,
+      config.vocabularyEngine,
+      config.provenanceTracker,
+      config.eventBus,
+      config.storage,
+      config.embedding
+    );
+    this.relationshipManager = new RelationshipManager(
+      config.repositoryId,
+      config.vocabularyEngine,
+      config.provenanceTracker,
+      config.eventBus,
+      config.storage
+    );
+    this.graphTraversal = new GraphTraversal(
+      config.repositoryId,
+      config.storage
+    );
+    this.searchOrchestrator = new SearchOrchestrator({
+      repositoryId: config.repositoryId,
+      storage: config.storage,
+      search: config.search,
+      embedding: config.embedding,
+      eventBus: config.eventBus,
+      defaultSimilarityThreshold: config.vocabularyEngine.getGovernanceConfig().defaultSimilarityThreshold
+    });
+  }
+  // ─── Vocabulary ────────────────────────────────────────────────────
+  async getVocabulary() {
+    return this.vocabularyEngine.getResolvedVocabulary();
+  }
+  async proposeVocabularyChange(proposal) {
+    const context = this.provenanceTracker.getContext();
+    return this.vocabularyEngine.proposeChange(proposal, context.actorId);
+  }
+  /** @deprecated Use proposeVocabularyChange instead */
+  async proposeVocabularyExtension(proposal) {
+    return this.proposeVocabularyChange(proposal);
+  }
+  // ─── Entities ──────────────────────────────────────────────────────
+  async createEntity(input) {
+    const entity = await this.entityManager.create(input);
+    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
+      });
+    }
+    return entity;
+  }
+  async updateEntity(entityId, updates) {
+    const entity = await this.entityManager.update(entityId, updates);
+    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
+      });
+    }
+    return entity;
+  }
+  async getEntity(entityId, detailLevel) {
+    return this.entityManager.get(entityId, detailLevel);
+  }
+  async getBySlug(slug, detailLevel) {
+    return this.entityManager.getBySlug(slug, detailLevel);
+  }
+  async getEntities(entityIds, detailLevel) {
+    return this.entityManager.getMany(entityIds, detailLevel);
+  }
+  async findEntities(query) {
+    return this.searchOrchestrator.findEntities(query);
+  }
+  async deleteEntity(entityId) {
+    await this.entityManager.delete(entityId);
+    if (this.search) {
+      await this.search.removeEntity(this.repositoryId, entityId);
+    }
+  }
+  // ─── Re-embedding ──────────────────────────────────────────────────
+  /** Re-embed specific entities using the current EmbeddingProvider */
+  async reembedEntities(entityIds) {
+    return this.entityManager.reembedEntities(entityIds);
+  }
+  /**
+   * Re-embed all entities in the repository using the current EmbeddingProvider.
+   * Processes in batches with optional rate limiting. Emits reembed:* events for progress tracking.
+   * Updates repository metadata with the new model ID and dimensions on completion.
+   */
+  async reembedAll(options) {
+    const stats = await this.getStats();
+    await this.eventBus.emit("reembed:started", {
+      repositoryId: this.repositoryId,
+      totalEntities: stats.entityCount
+    });
+    try {
+      const result = await this.entityManager.reembedAll({
+        batchSize: options?.batchSize,
+        maxRetries: options?.maxRetries,
+        errorThresholdToAbort: options?.errorThresholdToAbort,
+        delayBetweenBatchesMs: options?.delayBetweenBatchesMs,
+        onProgress: async (processed, total, failed) => {
+          await this.eventBus.emit("reembed:progress", {
+            repositoryId: this.repositoryId,
+            processed,
+            totalEntities: total,
+            failed
+          });
+        }
+      });
+      await this.storage.updateRepository(this.repositoryId, {
+        metadata: {
+          embeddingModelId: result.modelId,
+          embeddingDimensions: result.dimensions
+        }
+      });
+      await this.eventBus.emit("reembed:completed", {
+        repositoryId: this.repositoryId,
+        processed: result.processed,
+        failed: result.failed,
+        modelId: result.modelId
+      });
+      return result;
+    } catch (err) {
+      await this.eventBus.emit("reembed:failed", {
+        repositoryId: this.repositoryId,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
+    }
+  }
+  // ─── Relationships ─────────────────────────────────────────────────
+  async createRelationship(input) {
+    return this.relationshipManager.create(input);
+  }
+  async removeRelationship(relationshipId) {
+    return this.relationshipManager.remove(relationshipId);
+  }
+  async getRelationships(entityId, options) {
+    return this.relationshipManager.getForEntity(entityId, options);
+  }
+  async getRelationshipSummary(entityId) {
+    const result = await this.storage.getEntityRelationships(
+      this.repositoryId,
+      entityId,
+      { direction: "both", limit: 1e4 }
+    );
+    const outbound = {};
+    const inbound = {};
+    for (const rel of result.items) {
+      if (rel.sourceEntityId === entityId) {
+        outbound[rel.relationshipType] = (outbound[rel.relationshipType] ?? 0) + 1;
+      }
+      if (rel.targetEntityId === entityId) {
+        inbound[rel.relationshipType] = (inbound[rel.relationshipType] ?? 0) + 1;
+      }
+    }
+    return { outbound, inbound };
+  }
+  async getRelationshipsForEntities(entityIds) {
+    const seen = /* @__PURE__ */ new Set();
+    const results = [];
+    for (const entityId of entityIds) {
+      const rels = await this.relationshipManager.getForEntity(entityId, {
+        direction: "both",
+        limit: 1e4
+      });
+      for (const rel of rels.items) {
+        if (!seen.has(rel.id)) {
+          seen.add(rel.id);
+          results.push(rel);
+        }
+      }
+    }
+    return results;
+  }
+  // ─── Graph ─────────────────────────────────────────────────────────
+  /** Get the full graph — entities with enriched relationships, vocabulary, and stats. Paginated. */
+  async getGraph(options) {
+    const pageSize = options?.limit ?? 200;
+    const offset = options?.offset ?? 0;
+    const [stats, vocabulary] = await Promise.all([
+      this.getStats(),
+      this.getVocabulary()
+    ]);
+    const entities = await this.findEntities({ limit: pageSize, offset, detailLevel: options?.detailLevel ?? "summary" });
+    const rawRelationships = await this.getRelationshipsForEntities(
+      entities.items.map((e) => e.id)
+    );
+    const entityLookup = /* @__PURE__ */ new Map();
+    for (const e of entities.items) {
+      entityLookup.set(e.id, { slug: e.slug, label: e.label });
+    }
+    const MAX_RELATIONSHIPS = 1e3;
+    const totalRelationships = rawRelationships.length;
+    const cappedRelationships = rawRelationships.slice(0, MAX_RELATIONSHIPS);
+    const relationships = cappedRelationships.map((rel) => {
+      const source = entityLookup.get(rel.sourceEntityId);
+      const target = entityLookup.get(rel.targetEntityId);
+      return {
+        ...rel,
+        sourceSlug: source?.slug ?? rel.sourceEntityId,
+        sourceLabel: source?.label ?? rel.sourceEntityId,
+        targetSlug: target?.slug ?? rel.targetEntityId,
+        targetLabel: target?.label ?? rel.targetEntityId
+      };
+    });
+    const nextOffset = offset + entities.items.length;
+    const hasMore = nextOffset < stats.entityCount;
+    return {
+      vocabulary,
+      stats,
+      entities: entities.items,
+      relationships,
+      totalRelationships,
+      relationshipsTruncated: totalRelationships > MAX_RELATIONSHIPS,
+      hasMore,
+      ...hasMore ? { cursor: `offset:${nextOffset}` } : {}
+    };
+  }
+  // ─── Graph Traversal ───────────────────────────────────────────────
+  async exploreNeighbourhood(entityId, options) {
+    return this.graphTraversal.exploreNeighbourhood(entityId, options);
+  }
+  async findPaths(sourceId, targetId, options) {
+    return this.graphTraversal.findPaths(sourceId, targetId, options);
+  }
+  // ─── Search ────────────────────────────────────────────────────────
+  async searchByConcept(query, options) {
+    return this.searchOrchestrator.searchByConcept(query, options);
+  }
+  // ─── Timeline ──────────────────────────────────────────────────────
+  async getTimeline(entityId, options) {
+    const storageOptions = {
+      timeRange: options?.timeRange,
+      eventTypes: options?.eventTypes,
+      provenance: options?.provenance,
+      limit: options?.limit ?? 20,
+      offset: options?.offset ?? 0
+    };
+    const storageResult = await this.storage.getTimeline(
+      this.repositoryId,
+      entityId,
+      storageOptions
+    );
+    const entity = await this.storage.getEntity(this.repositoryId, entityId);
+    const centreRef = {
+      id: entityId,
+      slug: entity?.slug ?? entityId,
+      label: entity?.label ?? entityId
+    };
+    const relIds = storageResult.events.filter((e) => e.relationshipId).map((e) => e.relationshipId);
+    const relMap = /* @__PURE__ */ new Map();
+    const entityIdsToResolve = /* @__PURE__ */ new Set();
+    for (const rid of relIds) {
+      const rel = await this.storage.getRelationship(this.repositoryId, rid);
+      if (rel) {
+        relMap.set(rid, {
+          id: rel.id,
+          type: rel.relationshipType,
+          sourceId: rel.sourceEntityId,
+          targetId: rel.targetEntityId
+        });
+        entityIdsToResolve.add(rel.sourceEntityId);
+        entityIdsToResolve.add(rel.targetEntityId);
+      }
+    }
+    const entityMap = await this.storage.getEntities(
+      this.repositoryId,
+      Array.from(entityIdsToResolve)
+    );
+    const toRef = (eid) => {
+      const e = entityMap.get(eid);
+      return { id: eid, slug: e?.slug ?? eid, label: e?.label ?? eid };
+    };
+    const events = storageResult.events.map((e) => {
+      if (e.relationshipId && relMap.has(e.relationshipId)) {
+        const rel = relMap.get(e.relationshipId);
+        const sourceRef = toRef(rel.sourceId);
+        const targetRef = toRef(rel.targetId);
+        const otherRef = rel.sourceId === entityId ? targetRef : sourceRef;
+        const direction = rel.sourceId === entityId ? "to" : "from";
+        const relDetail = {
+          id: rel.id,
+          relationshipType: rel.type,
+          sourceEntity: sourceRef,
+          targetEntity: targetRef
+        };
+        return {
+          timestamp: e.timestamp,
+          eventType: e.eventType,
+          description: `${rel.type} relationship created ${direction} ${otherRef.label}`,
+          relatedEntities: [centreRef, otherRef],
+          relationship: relDetail
+        };
+      }
+      const action = e.eventType === "entity:created" ? "created" : "updated";
+      return {
+        timestamp: e.timestamp,
+        eventType: e.eventType,
+        description: `${centreRef.label} ${action}`,
+        relatedEntities: [centreRef]
+      };
+    });
+    return {
+      id: entityId,
+      slug: centreRef.slug,
+      totalEvents: storageResult.total,
+      returned: events.length,
+      events
+    };
+  }
+  // ─── Stats ─────────────────────────────────────────────────────────
+  async getStats() {
+    return this.storage.getRepositoryStats(this.repositoryId);
+  }
+  // ─── Events ────────────────────────────────────────────────────────
+  on(event, handler) {
+    return this.eventBus.on(event, handler);
+  }
+  onHook(event, handler) {
+    return this.eventBus.onHook(event, handler);
+  }
+};
+
+// src/vocabulary/SemanticDeduplicator.ts
+var DEFAULT_THRESHOLD = 0.85;
+var SemanticDeduplicator = class {
+  threshold;
+  embeddingProvider;
+  constructor(config = {}) {
+    this.threshold = config.similarityThreshold ?? DEFAULT_THRESHOLD;
+    this.embeddingProvider = config.embeddingProvider;
+  }
+  /**
+   * 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.
+   */
+  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);
+    if (exactMatch) {
+      return {
+        isDuplicate: true,
+        matches: [{ type: exactMatch.type, description: exactMatch.description, similarity: 1 }]
+      };
+    }
+    if (this.embeddingProvider) {
+      return this.checkWithEmbeddings(proposedType, proposedDescription, existingTypes);
+    }
+    return this.checkWithStringSimilarity(proposedType, existingTypes);
+  }
+  async checkWithEmbeddings(proposedType, proposedDescription, existingTypes) {
+    const proposedText = `${proposedType}: ${proposedDescription}`;
+    const existingTexts = existingTypes.map((t) => `${t.type}: ${t.description}`);
+    const allTexts = [proposedText, ...existingTexts];
+    const embeddings = await this.embeddingProvider.embedBatch(allTexts);
+    const proposedEmbedding = embeddings[0];
+    const matches = [];
+    for (let i = 0; i < existingTypes.length; i++) {
+      const similarity = this.cosineSimilarity(proposedEmbedding, embeddings[i + 1]);
+      if (similarity >= this.threshold) {
+        matches.push({
+          type: existingTypes[i].type,
+          description: existingTypes[i].description,
+          similarity
+        });
+      }
+    }
+    matches.sort((a, b) => b.similarity - a.similarity);
+    return {
+      isDuplicate: matches.length > 0,
+      matches
+    };
+  }
+  checkWithStringSimilarity(proposedType, existingTypes) {
+    const normProposed = normaliseTypeName(proposedType);
+    const matches = [];
+    for (const existing of existingTypes) {
+      const normExisting = normaliseTypeName(existing.type);
+      const similarity = jaroWinklerSimilarity(normProposed, normExisting);
+      if (similarity >= this.threshold) {
+        matches.push({
+          type: existing.type,
+          description: existing.description,
+          similarity
+        });
+      }
+    }
+    matches.sort((a, b) => b.similarity - a.similarity);
+    return {
+      isDuplicate: matches.length > 0,
+      matches
+    };
+  }
+  cosineSimilarity(a, b) {
+    if (this.embeddingProvider?.similarity) {
+      return this.embeddingProvider.similarity(a, b);
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dotProduct += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    return denominator === 0 ? 0 : dotProduct / denominator;
+  }
+};
+
+// src/vocabulary/VocabularySchema.ts
+function createEmptyVocabulary(modifiedBy) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    version: "0.0.0",
+    lastModified: now,
+    modifiedBy,
+    entityTypes: [],
+    relationshipTypes: []
+  };
+}
+function createEntityTypeDefinition(input, createdBy) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    type: input.type,
+    description: input.description,
+    version: "1.0.0",
+    properties: input.properties ?? [],
+    createdAt: now,
+    createdBy,
+    modifiedAt: now,
+    modifiedBy: createdBy
+  };
+}
+function createRelationshipTypeDefinition(input, createdBy) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    type: toScreamingSnakeCase(input.type),
+    description: input.description,
+    version: "1.0.0",
+    allowedSourceTypes: input.allowedSourceTypes,
+    allowedTargetTypes: input.allowedTargetTypes,
+    bidirectional: input.bidirectional ?? false,
+    properties: input.properties,
+    createdAt: now,
+    createdBy,
+    modifiedAt: now,
+    modifiedBy: createdBy
+  };
+}
+function buildVocabulary(input, createdBy) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    version: "1.0.0",
+    lastModified: now,
+    modifiedBy: createdBy,
+    entityTypes: (input.entityTypes ?? []).map((et) => createEntityTypeDefinition(et, createdBy)),
+    relationshipTypes: (input.relationshipTypes ?? []).map(
+      (rt) => createRelationshipTypeDefinition(rt, createdBy)
+    )
+  };
+}
+function incrementVersion(version, level = "patch") {
+  const parts = version.split(".").map(Number);
+  const major = parts[0] ?? 0;
+  const minor = parts[1] ?? 0;
+  const patch = parts[2] ?? 0;
+  switch (level) {
+    case "major":
+      return `${major + 1}.0.0`;
+    case "minor":
+      return `${major}.${minor + 1}.0`;
+    case "patch":
+      return `${major}.${minor}.${patch + 1}`;
+  }
+}
+function mergeProperties(existing, addProperties, removeProperties, updateProperties) {
+  let result = [...existing];
+  if (removeProperties && removeProperties.length > 0) {
+    const removeSet = new Set(removeProperties);
+    result = result.filter((p) => !removeSet.has(p.name));
+  }
+  if (updateProperties && updateProperties.length > 0) {
+    const updateMap = new Map(updateProperties.map((p) => [p.name, p]));
+    result = result.map((p) => updateMap.get(p.name) ?? p);
+  }
+  if (addProperties && addProperties.length > 0) {
+    const existingNames = new Set(result.map((p) => p.name));
+    for (const prop of addProperties) {
+      if (!existingNames.has(prop.name)) {
+        result.push(prop);
+      }
+    }
+  }
+  return result;
+}
+function mergeEntityTypeEdit(existing, edit, modifiedBy) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    ...existing,
+    description: edit.description ?? existing.description,
+    version: incrementVersion(existing.version, "minor"),
+    properties: mergeProperties(
+      existing.properties,
+      edit.addProperties,
+      edit.removeProperties,
+      edit.updateProperties
+    ),
+    modifiedAt: now,
+    modifiedBy
+  };
+}
+function mergeRelationshipTypeEdit(existing, edit, modifiedBy) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    ...existing,
+    description: edit.description ?? existing.description,
+    allowedSourceTypes: edit.allowedSourceTypes ?? existing.allowedSourceTypes,
+    allowedTargetTypes: edit.allowedTargetTypes ?? existing.allowedTargetTypes,
+    bidirectional: edit.bidirectional ?? existing.bidirectional,
+    version: incrementVersion(existing.version, "minor"),
+    properties: mergeProperties(
+      existing.properties ?? [],
+      edit.addProperties,
+      edit.removeProperties,
+      edit.updateProperties
+    ),
+    modifiedAt: now,
+    modifiedBy
+  };
+}
+
+// src/vocabulary/VocabularyGovernor.ts
+function canPropose(governanceConfig, _proposal) {
+  switch (governanceConfig.mode) {
+    case "locked":
+      return {
+        allowed: false,
+        reason: "Vocabulary is locked. Only organisation admins can modify the vocabulary via the admin API."
+      };
+    case "managed":
+    case "open":
+      return { allowed: true };
+  }
+}
+function processProposal(vocabulary, proposal, governanceConfig, options) {
+  const decision = canPropose(governanceConfig, proposal);
+  if (!decision.allowed) {
+    return {
+      result: {
+        status: "rejected",
+        type: getProposedTypeName(proposal),
+        reason: decision.reason
+      }
+    };
+  }
+  const isAddProposal = proposal.proposalType === "entity_type" || proposal.proposalType === "relationship_type";
+  if (isAddProposal && options.duplicates && options.duplicates.length > 0) {
+    return {
+      result: {
+        status: "rejected",
+        type: getProposedTypeName(proposal),
+        reason: `Similar type(s) already exist in the vocabulary`,
+        duplicates: options.duplicates
+      }
+    };
+  }
+  if (governanceConfig.mode === "managed" && governanceConfig.requireApproval) {
+    return {
+      result: {
+        status: "pending_approval",
+        type: getProposedTypeName(proposal),
+        proposalId: generateProposalId()
+      }
+    };
+  }
+  switch (proposal.proposalType) {
+    case "entity_type":
+    case "relationship_type":
+      return applyAddProposal(vocabulary, proposal, options.proposedBy);
+    case "edit_entity_type":
+    case "edit_relationship_type":
+      return applyEditProposal(vocabulary, proposal, options.proposedBy);
+    case "delete_entity_type":
+    case "delete_relationship_type":
+      return applyDeleteProposal(vocabulary, proposal, options.proposedBy);
+  }
+}
+function applyAddProposal(vocabulary, proposal, proposedBy) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const newVersion = incrementVersion(vocabulary.version, "minor");
+  const typeName = getProposedTypeName(proposal);
+  let updatedVocabulary;
+  let changeType;
+  if (proposal.proposalType === "entity_type" && proposal.entityType) {
+    const newType = createEntityTypeDefinition(proposal.entityType, proposedBy);
+    updatedVocabulary = {
+      ...vocabulary,
+      version: newVersion,
+      lastModified: now,
+      modifiedBy: proposedBy,
+      entityTypes: [...vocabulary.entityTypes, newType]
+    };
+    changeType = "entity_type_added";
+  } else if (proposal.proposalType === "relationship_type" && proposal.relationshipType) {
+    const newType = createRelationshipTypeDefinition(
+      {
+        type: proposal.relationshipType.type,
+        description: proposal.relationshipType.description,
+        allowedSourceTypes: proposal.relationshipType.allowedSourceTypes,
+        allowedTargetTypes: proposal.relationshipType.allowedTargetTypes,
+        bidirectional: proposal.relationshipType.bidirectional,
+        properties: proposal.relationshipType.properties
+      },
+      proposedBy
+    );
+    updatedVocabulary = {
+      ...vocabulary,
+      version: newVersion,
+      lastModified: now,
+      modifiedBy: proposedBy,
+      relationshipTypes: [...vocabulary.relationshipTypes, newType]
+    };
+    changeType = "relationship_type_added";
+  } else {
+    return {
+      result: {
+        status: "rejected",
+        type: typeName,
+        reason: "Invalid proposal: missing type definition for the specified proposal type"
+      },
+      updatedVocabulary: vocabulary,
+      changeRecord: {
+        changeId: generateChangeId(),
+        changeType: "entity_type_added",
+        typeName,
+        newVersion: vocabulary.version,
+        proposedBy,
+        proposedAt: now,
+        reason: proposal.justification
+      }
+    };
+  }
+  const changeRecord = {
+    changeId: generateChangeId(),
+    changeType,
+    typeName,
+    previousVersion: vocabulary.version,
+    newVersion,
+    proposedBy,
+    proposedAt: now,
+    approvedAt: now,
+    reason: proposal.justification
+  };
+  return {
+    result: { status: "approved", type: typeName, vocabularyVersion: newVersion },
+    updatedVocabulary,
+    changeRecord
+  };
+}
+function applyEditProposal(vocabulary, proposal, proposedBy) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const typeName = getProposedTypeName(proposal);
+  const newVersion = incrementVersion(vocabulary.version, "minor");
+  let updatedVocabulary;
+  let changeType;
+  if (proposal.proposalType === "edit_entity_type" && proposal.editEntityType) {
+    const existing = vocabulary.entityTypes.find((et) => et.type === proposal.editEntityType.type);
+    if (!existing) {
+      return {
+        result: {
+          status: "rejected",
+          type: typeName,
+          reason: `Entity type "${typeName}" not found in vocabulary`
+        }
+      };
+    }
+    const merged = mergeEntityTypeEdit(existing, proposal.editEntityType, proposedBy);
+    updatedVocabulary = {
+      ...vocabulary,
+      version: newVersion,
+      lastModified: now,
+      modifiedBy: proposedBy,
+      entityTypes: vocabulary.entityTypes.map((et) => et.type === typeName ? merged : et)
+    };
+    changeType = "entity_type_modified";
+  } else if (proposal.proposalType === "edit_relationship_type" && proposal.editRelationshipType) {
+    const existing = vocabulary.relationshipTypes.find(
+      (rt) => rt.type === proposal.editRelationshipType.type
+    );
+    if (!existing) {
+      return {
+        result: {
+          status: "rejected",
+          type: typeName,
+          reason: `Relationship type "${typeName}" not found in vocabulary`
+        }
+      };
+    }
+    const merged = mergeRelationshipTypeEdit(existing, proposal.editRelationshipType, proposedBy);
+    updatedVocabulary = {
+      ...vocabulary,
+      version: newVersion,
+      lastModified: now,
+      modifiedBy: proposedBy,
+      relationshipTypes: vocabulary.relationshipTypes.map(
+        (rt) => rt.type === typeName ? merged : rt
+      )
+    };
+    changeType = "relationship_type_modified";
+  } else {
+    return {
+      result: {
+        status: "rejected",
+        type: typeName,
+        reason: "Invalid proposal: missing edit definition for the specified proposal type"
+      }
+    };
+  }
+  const changeRecord = {
+    changeId: generateChangeId(),
+    changeType,
+    typeName,
+    previousVersion: vocabulary.version,
+    newVersion,
+    proposedBy,
+    proposedAt: now,
+    approvedAt: now,
+    reason: proposal.justification
+  };
+  return {
+    result: { status: "approved", type: typeName, vocabularyVersion: newVersion },
+    updatedVocabulary,
+    changeRecord
+  };
+}
+function applyDeleteProposal(vocabulary, proposal, proposedBy) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const typeName = getProposedTypeName(proposal);
+  const newVersion = incrementVersion(vocabulary.version, "major");
+  let updatedVocabulary;
+  let changeType;
+  if (proposal.proposalType === "delete_entity_type" && proposal.deleteEntityType) {
+    const exists = vocabulary.entityTypes.some((et) => et.type === proposal.deleteEntityType.type);
+    if (!exists) {
+      return {
+        result: {
+          status: "rejected",
+          type: typeName,
+          reason: `Entity type "${typeName}" not found in vocabulary`
+        }
+      };
+    }
+    updatedVocabulary = {
+      ...vocabulary,
+      version: newVersion,
+      lastModified: now,
+      modifiedBy: proposedBy,
+      entityTypes: vocabulary.entityTypes.filter((et) => et.type !== typeName)
+    };
+    changeType = "entity_type_removed";
+  } else if (proposal.proposalType === "delete_relationship_type" && proposal.deleteRelationshipType) {
+    const exists = vocabulary.relationshipTypes.some(
+      (rt) => rt.type === proposal.deleteRelationshipType.type
+    );
+    if (!exists) {
+      return {
+        result: {
+          status: "rejected",
+          type: typeName,
+          reason: `Relationship type "${typeName}" not found in vocabulary`
+        }
+      };
+    }
+    updatedVocabulary = {
+      ...vocabulary,
+      version: newVersion,
+      lastModified: now,
+      modifiedBy: proposedBy,
+      relationshipTypes: vocabulary.relationshipTypes.filter((rt) => rt.type !== typeName)
+    };
+    changeType = "relationship_type_removed";
+  } else {
+    return {
+      result: {
+        status: "rejected",
+        type: typeName,
+        reason: "Invalid proposal: missing delete definition for the specified proposal type"
+      }
+    };
+  }
+  const changeRecord = {
+    changeId: generateChangeId(),
+    changeType,
+    typeName,
+    previousVersion: vocabulary.version,
+    newVersion,
+    proposedBy,
+    proposedAt: now,
+    approvedAt: now,
+    reason: proposal.justification
+  };
+  return {
+    result: { status: "approved", type: typeName, vocabularyVersion: newVersion },
+    updatedVocabulary,
+    changeRecord
+  };
+}
+function getProposedTypeName(proposal) {
+  switch (proposal.proposalType) {
+    case "entity_type":
+      return proposal.entityType?.type ?? "unknown";
+    case "relationship_type":
+      return proposal.relationshipType?.type ?? "unknown";
+    case "edit_entity_type":
+      return proposal.editEntityType?.type ?? "unknown";
+    case "edit_relationship_type":
+      return proposal.editRelationshipType?.type ?? "unknown";
+    case "delete_entity_type":
+      return proposal.deleteEntityType?.type ?? "unknown";
+    case "delete_relationship_type":
+      return proposal.deleteRelationshipType?.type ?? "unknown";
+  }
+}
+function generateProposalId() {
+  return `proposal_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function generateChangeId() {
+  return `change_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+// src/vocabulary/VocabularyValidator.ts
+function ok() {
+  return { valid: true, errors: [] };
+}
+function fail(...errors) {
+  return { valid: false, errors };
+}
+function merge(...results) {
+  const errors = results.flatMap((r) => r.errors);
+  return { valid: errors.length === 0, errors };
+}
+function findClosestType(typeName, types) {
+  if (types.length === 0) return void 0;
+  const lower = typeName.toLowerCase();
+  const match = types.find(
+    (t) => t.type.toLowerCase().includes(lower) || lower.includes(t.type.toLowerCase())
+  );
+  return match?.type;
+}
+function validatePropertyValue(name, value, schema) {
+  if (value === void 0 || value === null) {
+    if (schema.required) {
+      return fail({
+        field: `properties.${name}`,
+        message: `Required property "${name}" is missing`
+      });
+    }
+    return ok();
+  }
+  switch (schema.type) {
+    case "string":
+      if (typeof value !== "string") {
+        return fail({
+          field: `properties.${name}`,
+          message: `Property "${name}" must be a string, got ${typeof value}`
+        });
+      }
+      break;
+    case "number":
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        return fail({
+          field: `properties.${name}`,
+          message: `Property "${name}" must be a number, got ${typeof value}`
+        });
+      }
+      break;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        return fail({
+          field: `properties.${name}`,
+          message: `Property "${name}" must be a boolean, got ${typeof value}`
+        });
+      }
+      break;
+    case "date":
+      if (typeof value !== "string" || Number.isNaN(Date.parse(value))) {
+        return fail({
+          field: `properties.${name}`,
+          message: `Property "${name}" must be a valid ISO date string`
+        });
+      }
+      break;
+    case "enum":
+      if (typeof value !== "string") {
+        return fail({
+          field: `properties.${name}`,
+          message: `Property "${name}" must be a string (enum value), got ${typeof value}`
+        });
+      }
+      if (schema.enumValues && !schema.enumValues.includes(value)) {
+        return fail({
+          field: `properties.${name}`,
+          message: `Property "${name}" must be one of: ${schema.enumValues.join(", ")}`,
+          suggestion: `Valid values: ${schema.enumValues.join(", ")}`
+        });
+      }
+      break;
+  }
+  return ok();
+}
+function validateProperties(properties, schemas, context) {
+  const results = [];
+  const providedProperties = properties ?? {};
+  for (const schema of schemas) {
+    const value = providedProperties[schema.name];
+    results.push(validatePropertyValue(schema.name, value, schema));
+  }
+  const knownNames = new Set(schemas.map((s) => s.name));
+  for (const key of Object.keys(providedProperties)) {
+    if (!knownNames.has(key)) {
+      results.push(
+        fail({
+          field: `properties.${key}`,
+          message: `Unknown property "${key}" on ${context}`,
+          suggestion: `Known properties: ${schemas.map((s) => s.name).join(", ") || "none"}`
+        })
+      );
+    }
+  }
+  return merge(...results);
+}
+function validateEntity(input, vocabulary) {
+  const entityTypeDef = vocabulary.entityTypes.find((et) => et.type === input.entityType);
+  if (!entityTypeDef) {
+    const closest = findClosestType(input.entityType, vocabulary.entityTypes);
+    return fail({
+      field: "entityType",
+      message: `Entity type "${input.entityType}" does not exist in the vocabulary`,
+      suggestion: closest ? `Did you mean "${closest}"?` : `Available types: ${vocabulary.entityTypes.map((et) => et.type).join(", ") || "none"}`
+    });
+  }
+  if (!input.label || input.label.trim().length === 0) {
+    return fail({
+      field: "label",
+      message: "Entity label is required and cannot be empty"
+    });
+  }
+  return validateProperties(input.properties, entityTypeDef.properties, input.entityType);
+}
+function validateEntityUpdate(input, entityTypeDef) {
+  if (input.label !== void 0 && input.label.trim().length === 0) {
+    return fail({
+      field: "label",
+      message: "Entity label cannot be empty"
+    });
+  }
+  if (input.properties) {
+    const results = [];
+    for (const [key, value] of Object.entries(input.properties)) {
+      const schema = entityTypeDef.properties.find((p) => p.name === key);
+      if (!schema) {
+        results.push(
+          fail({
+            field: `properties.${key}`,
+            message: `Unknown property "${key}" on ${entityTypeDef.type}`,
+            suggestion: `Known properties: ${entityTypeDef.properties.map((p) => p.name).join(", ") || "none"}`
+          })
+        );
+      } else {
+        results.push(validatePropertyValue(key, value, schema));
+      }
+    }
+    return merge(...results);
+  }
+  return ok();
+}
+function validateRelationship(input, vocabulary, sourceEntityType, targetEntityType) {
+  const normalisedType = toScreamingSnakeCase(input.relationshipType);
+  const relTypeDef = vocabulary.relationshipTypes.find(
+    (rt) => rt.type === normalisedType
+  );
+  if (!relTypeDef) {
+    const closest = findClosestType(input.relationshipType, vocabulary.relationshipTypes);
+    return fail({
+      field: "relationshipType",
+      message: `Relationship type "${input.relationshipType}" does not exist in the vocabulary`,
+      suggestion: closest ? `Did you mean "${closest}"?` : `Available types: ${vocabulary.relationshipTypes.map((rt) => rt.type).join(", ") || "none"}`
+    });
+  }
+  const results = [];
+  if (relTypeDef.allowedSourceTypes.length > 0 && !relTypeDef.allowedSourceTypes.includes(sourceEntityType)) {
+    results.push(
+      fail({
+        field: "sourceEntityId",
+        message: `Entity type "${sourceEntityType}" is not allowed as source for relationship type "${input.relationshipType}"`,
+        suggestion: `Allowed source types: ${relTypeDef.allowedSourceTypes.join(", ")}`
+      })
+    );
+  }
+  if (relTypeDef.allowedTargetTypes.length > 0 && !relTypeDef.allowedTargetTypes.includes(targetEntityType)) {
+    results.push(
+      fail({
+        field: "targetEntityId",
+        message: `Entity type "${targetEntityType}" is not allowed as target for relationship type "${input.relationshipType}"`,
+        suggestion: `Allowed target types: ${relTypeDef.allowedTargetTypes.join(", ")}`
+      })
+    );
+  }
+  if (relTypeDef.properties) {
+    results.push(
+      validateProperties(input.properties, relTypeDef.properties, input.relationshipType)
+    );
+  }
+  return merge(...results);
+}
+function getEntityTypeDef(entityType, vocabulary) {
+  return vocabulary.entityTypes.find((et) => et.type === entityType) ?? null;
+}
+
+// src/core/VocabularyEngine.ts
+var VocabularyEngine = class {
+  repositoryId;
+  storage;
+  governanceConfig;
+  deduplicator;
+  /** Cached vocabulary — invalidated on mutation */
+  cachedVocabulary = null;
+  constructor(config) {
+    this.repositoryId = config.repositoryId;
+    this.storage = config.storageProvider;
+    this.governanceConfig = config.governanceConfig;
+    this.deduplicator = new SemanticDeduplicator({
+      similarityThreshold: config.deduplicationThreshold,
+      embeddingProvider: config.embeddingProvider
+    });
+  }
+  /** Get the governance configuration for this repository */
+  getGovernanceConfig() {
+    return this.governanceConfig;
+  }
+  /** Get the current vocabulary from storage (cached) */
+  async getVocabulary() {
+    if (!this.cachedVocabulary) {
+      this.cachedVocabulary = await this.storage.getVocabulary(this.repositoryId);
+    }
+    return this.cachedVocabulary;
+  }
+  /** Get the resolved vocabulary with governance info */
+  async getResolvedVocabulary() {
+    const vocabulary = await this.getVocabulary();
+    return {
+      vocabulary,
+      governanceMode: this.governanceConfig.mode,
+      governanceConfig: this.governanceConfig
+    };
+  }
+  /** Invalidate the cached vocabulary (call after external mutations) */
+  invalidateCache() {
+    this.cachedVocabulary = null;
+  }
+  /** Validate an entity creation input against the vocabulary */
+  async validateEntity(input) {
+    const vocabulary = await this.getVocabulary();
+    return validateEntity(input, vocabulary);
+  }
+  /** Validate an entity update input against the vocabulary */
+  async validateEntityUpdate(input, entityType) {
+    const vocabulary = await this.getVocabulary();
+    const typeDef = getEntityTypeDef(entityType, vocabulary);
+    if (!typeDef) {
+      return {
+        valid: false,
+        errors: [
+          {
+            field: "entityType",
+            message: `Entity type "${entityType}" does not exist in the vocabulary`
+          }
+        ]
+      };
+    }
+    return validateEntityUpdate(input, typeDef);
+  }
+  /** Validate a relationship creation input against the vocabulary */
+  async validateRelationship(input, sourceEntityType, targetEntityType) {
+    const vocabulary = await this.getVocabulary();
+    return validateRelationship(input, vocabulary, sourceEntityType, targetEntityType);
+  }
+  /** Get an entity type definition from the vocabulary */
+  async getEntityTypeDef(entityType) {
+    const vocabulary = await this.getVocabulary();
+    return getEntityTypeDef(entityType, vocabulary);
+  }
+  /**
+   * Propose a vocabulary change (add, edit, or delete).
+   * Runs deduplication for add proposals, then governance rules.
+   * For delete proposals, cascades data deletion if approved.
+   */
+  async proposeChange(proposal, proposedBy) {
+    const vocabulary = await this.getVocabulary();
+    const isAddProposal = proposal.proposalType === "entity_type" || proposal.proposalType === "relationship_type";
+    let duplicates;
+    if (isAddProposal) {
+      const existingTypes = this.getExistingTypesForProposal(proposal, vocabulary);
+      const proposedTypeName = this.getProposedTypeName(proposal);
+      const proposedDescription = this.getProposedDescription(proposal);
+      const skipDedup = this.governanceConfig.mode === "open" && this.governanceConfig.deduplicationEnabled === false;
+      if (!skipDedup) {
+        const dedupResult = await this.deduplicator.checkDuplicate(
+          proposedTypeName,
+          proposedDescription,
+          existingTypes
+        );
+        if (dedupResult.isDuplicate) {
+          duplicates = dedupResult.matches;
+        }
+      }
+    }
+    const { result, updatedVocabulary } = processProposal(
+      vocabulary,
+      proposal,
+      this.governanceConfig,
+      { duplicates, proposedBy }
+    );
+    if (result.status === "approved" && updatedVocabulary) {
+      const isDeleteProposal = proposal.proposalType === "delete_entity_type" || proposal.proposalType === "delete_relationship_type";
+      if (isDeleteProposal) {
+        await this.cascadeDeleteData(proposal);
+      }
+      await this.storage.saveVocabulary(this.repositoryId, updatedVocabulary);
+      this.cachedVocabulary = updatedVocabulary;
+    }
+    return result;
+  }
+  /** @deprecated Use proposeChange instead */
+  async proposeExtension(proposal, proposedBy) {
+    return this.proposeChange(proposal, proposedBy);
+  }
+  /** Cascade-delete all data for a deleted vocabulary type */
+  async cascadeDeleteData(proposal) {
+    if (proposal.proposalType === "delete_entity_type" && proposal.deleteEntityType) {
+      return this.storage.deleteEntitiesByType(
+        this.repositoryId,
+        proposal.deleteEntityType.type
+      );
+    }
+    if (proposal.proposalType === "delete_relationship_type" && proposal.deleteRelationshipType) {
+      const result = await this.storage.deleteRelationshipsByType(
+        this.repositoryId,
+        proposal.deleteRelationshipType.type
+      );
+      return { deletedEntities: 0, deletedRelationships: result.deletedRelationships };
+    }
+    return { deletedEntities: 0, deletedRelationships: 0 };
+  }
+  getExistingTypesForProposal(proposal, vocabulary) {
+    if (proposal.proposalType === "entity_type") {
+      return vocabulary.entityTypes.map((et) => ({
+        type: et.type,
+        description: et.description
+      }));
+    }
+    return vocabulary.relationshipTypes.map((rt) => ({
+      type: rt.type,
+      description: rt.description
+    }));
+  }
+  getProposedTypeName(proposal) {
+    if (proposal.proposalType === "entity_type") {
+      return proposal.entityType?.type ?? "";
+    }
+    return proposal.relationshipType?.type ?? "";
+  }
+  getProposedDescription(proposal) {
+    if (proposal.proposalType === "entity_type") {
+      return proposal.entityType?.description ?? "";
+    }
+    return proposal.relationshipType?.description ?? "";
+  }
+};
+
+// src/core/ProvenanceTracker.ts
+var ProvenanceTracker = class {
+  context;
+  constructor(context) {
+    this.context = { ...context };
+  }
+  /** Update the active provenance context (e.g., different conversation) */
+  updateContext(newContext) {
+    this.context = { ...this.context, ...newContext };
+  }
+  /** Get the current provenance context */
+  getContext() {
+    return { ...this.context };
+  }
+  /** Stamp a newly created entity or relationship with full provenance */
+  stampCreate() {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      createdBy: this.context.actorId,
+      createdByType: this.context.actorType,
+      createdAt: now,
+      createdInConversation: this.context.conversationId,
+      createdFromMessage: this.context.messageId,
+      modifiedBy: this.context.actorId,
+      modifiedByType: this.context.actorType,
+      modifiedAt: now,
+      modifiedInConversation: this.context.conversationId,
+      modifiedFromMessage: this.context.messageId
+    };
+  }
+  /** Stamp an updated entity or relationship — preserves creation fields, updates modified fields */
+  stampUpdate(existing) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      ...existing,
+      modifiedBy: this.context.actorId,
+      modifiedByType: this.context.actorType,
+      modifiedAt: now,
+      modifiedInConversation: this.context.conversationId,
+      modifiedFromMessage: this.context.messageId
+    };
+  }
+};
+
+// src/core/EventBus.ts
+var EventBus = class {
+  handlers = /* @__PURE__ */ new Map();
+  hookHandlers = /* @__PURE__ */ new Map();
+  provenance;
+  repositoryId;
+  constructor(provenance, repositoryId) {
+    this.provenance = provenance;
+    this.repositoryId = repositoryId;
+  }
+  /** Update provenance context (e.g., when conversation changes) */
+  updateProvenance(provenance) {
+    this.provenance = provenance;
+  }
+  /** Subscribe to an event. Returns an unsubscribe function. */
+  on(event, handler) {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.handlers.get(event).add(handler);
+    return () => {
+      this.handlers.get(event)?.delete(handler);
+    };
+  }
+  /** Register a pre-mutation hook that can cancel operations */
+  onHook(event, handler) {
+    if (!this.hookHandlers.has(event)) {
+      this.hookHandlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.hookHandlers.get(event).add(handler);
+    return () => {
+      this.hookHandlers.get(event)?.delete(handler);
+    };
+  }
+  /** Emit an event to all registered handlers */
+  async emit(event, payload) {
+    const handlers = this.handlers.get(event);
+    if (!handlers || handlers.size === 0) return;
+    const eventObj = {
+      type: event,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      repositoryId: this.repositoryId,
+      provenance: { ...this.provenance },
+      payload
+    };
+    for (const handler of handlers) {
+      await handler(eventObj);
+    }
+  }
+  /**
+   * Emit a pre-mutation hook event.
+   * Returns `{ cancelled: false }` if all hooks pass,
+   * or `{ cancelled: true, reason }` if any hook cancels.
+   */
+  async emitHook(event, payload) {
+    const hooks = this.hookHandlers.get(event);
+    if (!hooks || hooks.size === 0) return { cancelled: false };
+    const eventObj = {
+      type: event,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      repositoryId: this.repositoryId,
+      provenance: { ...this.provenance },
+      payload
+    };
+    for (const hook of hooks) {
+      const result = await hook(eventObj);
+      if (result.cancel) {
+        return { cancelled: true, reason: result.reason };
+      }
+    }
+    return { cancelled: false };
+  }
+  /** Remove all listeners and hooks */
+  removeAllListeners() {
+    this.handlers.clear();
+    this.hookHandlers.clear();
+  }
+};
+
+// src/portability/RepositoryExporter.ts
+var LIBRARY_VERSION = "0.1.0";
+var RepositoryExporter = class {
+  storage;
+  provenance;
+  constructor(config) {
+    this.storage = config.storage;
+    this.provenance = config.provenance;
+  }
+  /**
+   * Stream a repository export as an async generator.
+   * Yields: manifest → vocabulary → entity chunks → relationship chunks.
+   * The caller can pipe this to a file, zip stream, or HTTP response.
+   */
+  async *exportStream(repositoryId) {
+    const repo = await this.storage.getRepository(repositoryId);
+    if (!repo) {
+      throw new RepositoryNotFoundError(repositoryId);
+    }
+    const vocabulary = await this.storage.getVocabulary(repositoryId);
+    const stats = await this.storage.getRepositoryStats(repositoryId);
+    const manifest = {
+      formatVersion: "1.0.0",
+      libraryVersion: LIBRARY_VERSION,
+      exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      exportedBy: this.provenance,
+      repository: {
+        repositoryId,
+        type: repo.type,
+        label: repo.label,
+        description: repo.description,
+        vocabularyVersion: vocabulary.version,
+        governanceMode: repo.governanceConfig.mode
+      },
+      statistics: {
+        entityCount: stats.entityCount,
+        relationshipCount: stats.relationshipCount,
+        entityTypeBreakdown: stats.entityTypeBreakdown,
+        relationshipTypeBreakdown: stats.relationshipTypeBreakdown
+      }
+    };
+    if (repo.metadata?.embeddingModelId) {
+      manifest.embedding = {
+        modelId: repo.metadata.embeddingModelId,
+        dimensions: repo.metadata.embeddingDimensions ?? 0,
+        note: "Embeddings are model-specific. Re-embed after import if using a different model."
+      };
+    }
+    yield { type: "manifest", data: manifest };
+    yield { type: "vocabulary", data: vocabulary };
+    for await (const chunk of this.storage.exportAll(repositoryId)) {
+      if (chunk.type === "entities") {
+        yield {
+          type: "entities",
+          data: chunk.data,
+          sequence: chunk.sequence,
+          isLast: chunk.isLast
+        };
+      } else {
+        yield {
+          type: "relationships",
+          data: chunk.data,
+          sequence: chunk.sequence,
+          isLast: chunk.isLast
+        };
+      }
+    }
+  }
+  /**
+   * Export a repository to a complete in-memory archive.
+   * Convenience wrapper around exportStream() — use for small repositories.
+   * For large repositories, use exportStream() directly.
+   */
+  async export(repositoryId) {
+    let manifest;
+    let vocabulary;
+    const entities = [];
+    const relationships = [];
+    for await (const item of this.exportStream(repositoryId)) {
+      switch (item.type) {
+        case "manifest":
+          manifest = item.data;
+          break;
+        case "vocabulary":
+          vocabulary = item.data;
+          break;
+        case "entities":
+          entities.push(...item.data);
+          break;
+        case "relationships":
+          relationships.push(...item.data);
+          break;
+      }
+    }
+    return {
+      manifest,
+      vocabulary,
+      entities,
+      relationships
+    };
+  }
+};
+
+// src/vocabulary/VocabularyDiff.ts
+function diffVocabularies(from, to) {
+  const changes = [];
+  diffTypes(
+    from.entityTypes,
+    to.entityTypes,
+    "entity_type",
+    diffEntityType,
+    changes
+  );
+  diffTypes(
+    from.relationshipTypes,
+    to.relationshipTypes,
+    "relationship_type",
+    diffRelationshipType,
+    changes
+  );
+  return {
+    fromVersion: from.version,
+    toVersion: to.version,
+    changes,
+    hasChanges: changes.length > 0
+  };
+}
+function diffTypes(fromTypes, toTypes, category, detailDiff, changes) {
+  const fromMap = new Map(fromTypes.map((t) => [t.type, t]));
+  const toMap = new Map(toTypes.map((t) => [t.type, t]));
+  for (const [typeName] of toMap) {
+    if (!fromMap.has(typeName)) {
+      changes.push({ changeType: "added", category, typeName });
+    }
+  }
+  for (const [typeName] of fromMap) {
+    if (!toMap.has(typeName)) {
+      changes.push({ changeType: "removed", category, typeName });
+    }
+  }
+  for (const [typeName, fromType] of fromMap) {
+    const toType = toMap.get(typeName);
+    if (!toType) continue;
+    const details = detailDiff(fromType, toType);
+    if (details) {
+      changes.push({ changeType: "modified", category, typeName, details });
+    }
+  }
+}
+function diffEntityType(from, to) {
+  const diffs = [];
+  if (from.description !== to.description) {
+    diffs.push("description changed");
+  }
+  const propDiff = diffPropertySchemas(from.properties, to.properties);
+  if (propDiff) {
+    diffs.push(propDiff);
+  }
+  return diffs.length > 0 ? diffs.join("; ") : null;
+}
+function diffRelationshipType(from, to) {
+  const diffs = [];
+  if (from.description !== to.description) {
+    diffs.push("description changed");
+  }
+  if (from.bidirectional !== to.bidirectional) {
+    diffs.push(`bidirectional: ${from.bidirectional} \u2192 ${to.bidirectional}`);
+  }
+  const srcDiff = diffArrays(from.allowedSourceTypes, to.allowedSourceTypes);
+  if (srcDiff) diffs.push(`allowedSourceTypes: ${srcDiff}`);
+  const tgtDiff = diffArrays(from.allowedTargetTypes, to.allowedTargetTypes);
+  if (tgtDiff) diffs.push(`allowedTargetTypes: ${tgtDiff}`);
+  const propDiff = diffPropertySchemas(from.properties ?? [], to.properties ?? []);
+  if (propDiff) diffs.push(propDiff);
+  return diffs.length > 0 ? diffs.join("; ") : null;
+}
+function diffPropertySchemas(from, to) {
+  const fromMap = new Map(from.map((p) => [p.name, p]));
+  const toMap = new Map(to.map((p) => [p.name, p]));
+  const parts = [];
+  for (const [name] of toMap) {
+    if (!fromMap.has(name)) parts.push(`property "${name}" added`);
+  }
+  for (const [name] of fromMap) {
+    if (!toMap.has(name)) parts.push(`property "${name}" removed`);
+  }
+  for (const [name, fromProp] of fromMap) {
+    const toProp = toMap.get(name);
+    if (!toProp) continue;
+    if (fromProp.type !== toProp.type) {
+      parts.push(`property "${name}" type: ${fromProp.type} \u2192 ${toProp.type}`);
+    }
+    if (fromProp.required !== toProp.required) {
+      parts.push(`property "${name}" required: ${fromProp.required} \u2192 ${toProp.required}`);
+    }
+  }
+  return parts.length > 0 ? parts.join(", ") : null;
+}
+function diffArrays(from, to) {
+  const fromSet = new Set(from);
+  const toSet = new Set(to);
+  const added = to.filter((t) => !fromSet.has(t));
+  const removed = from.filter((f) => !toSet.has(f));
+  const parts = [];
+  if (added.length > 0) parts.push(`+[${added.join(", ")}]`);
+  if (removed.length > 0) parts.push(`-[${removed.join(", ")}]`);
+  return parts.length > 0 ? parts.join(" ") : null;
+}
+
+// src/portability/MigrationEngine.ts
+var MigrationEngine = class {
+  /**
+   * Analyse and migrate vocabulary differences between source and target.
+   *
+   * @param sourceVocabulary - vocabulary from the export archive
+   * @param targetVocabulary - vocabulary in the target repository
+   * @param conflictMode - how to handle differences
+   * @param migratedBy - actor performing the migration
+   */
+  migrate(sourceVocabulary, targetVocabulary, conflictMode, migratedBy) {
+    const diff = diffVocabularies(targetVocabulary, sourceVocabulary);
+    if (!diff.hasChanges) {
+      return { success: true, mergedVocabulary: targetVocabulary, warnings: [] };
+    }
+    const warnings = [];
+    switch (conflictMode) {
+      case "reject":
+        return {
+          success: false,
+          warnings: [],
+          reason: `Vocabulary mismatch: ${diff.changes.length} difference(s) found. Changes: ${diff.changes.map(describeChange).join("; ")}`
+        };
+      case "prompt":
+        return {
+          success: false,
+          warnings: diff.changes.map((c) => ({
+            code: "vocabulary_mismatch",
+            message: describeChange(c)
+          })),
+          reason: "Vocabulary differences require manual resolution"
+        };
+      case "extend": {
+        const merged = this.extendVocabulary(
+          sourceVocabulary,
+          targetVocabulary,
+          diff.changes,
+          migratedBy,
+          warnings
+        );
+        return { success: true, mergedVocabulary: merged, warnings };
+      }
+    }
+  }
+  /** Extend the target vocabulary with types from the source */
+  extendVocabulary(source, target, changes, migratedBy, warnings) {
+    const merged = {
+      ...target,
+      entityTypes: [...target.entityTypes],
+      relationshipTypes: [...target.relationshipTypes]
+    };
+    for (const change of changes) {
+      if (change.changeType === "added") {
+        if (change.category === "entity_type") {
+          const sourceType = source.entityTypes.find((t) => t.type === change.typeName);
+          if (sourceType) {
+            merged.entityTypes.push(
+              createEntityTypeDefinition(
+                { type: sourceType.type, description: sourceType.description, properties: sourceType.properties },
+                migratedBy
+              )
+            );
+            warnings.push({
+              code: "entity_type_added",
+              message: `Entity type "${change.typeName}" added from source vocabulary`
+            });
+          }
+        } else {
+          const sourceType = source.relationshipTypes.find((t) => t.type === change.typeName);
+          if (sourceType) {
+            merged.relationshipTypes.push(
+              createRelationshipTypeDefinition(
+                {
+                  type: sourceType.type,
+                  description: sourceType.description,
+                  allowedSourceTypes: sourceType.allowedSourceTypes,
+                  allowedTargetTypes: sourceType.allowedTargetTypes,
+                  bidirectional: sourceType.bidirectional,
+                  properties: sourceType.properties
+                },
+                migratedBy
+              )
+            );
+            warnings.push({
+              code: "relationship_type_added",
+              message: `Relationship type "${change.typeName}" added from source vocabulary`
+            });
+          }
+        }
+      } else if (change.changeType === "modified") {
+        warnings.push({
+          code: "vocabulary_conflict",
+          message: `Type "${change.typeName}" differs between source and target: ${change.details ?? "unknown"}. Target version kept.`
+        });
+      } else if (change.changeType === "removed") {
+        warnings.push({
+          code: "vocabulary_extra",
+          message: `Type "${change.typeName}" exists in target but not in source \u2014 kept as-is`
+        });
+      }
+    }
+    const bumped = incrementVersion(merged.version, "minor");
+    merged.version = compareVersions(source.version, bumped) > 0 ? source.version : bumped;
+    merged.lastModified = (/* @__PURE__ */ new Date()).toISOString();
+    merged.modifiedBy = migratedBy;
+    return merged;
+  }
+};
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+function describeChange(change) {
+  const label = change.category === "entity_type" ? "entity type" : "relationship type";
+  switch (change.changeType) {
+    case "added":
+      return `${label} "${change.typeName}" exists in source but not target`;
+    case "removed":
+      return `${label} "${change.typeName}" exists in target but not source`;
+    case "modified":
+      return `${label} "${change.typeName}" differs: ${change.details ?? "unknown"}`;
+  }
+}
+
+// src/portability/RepositoryImporter.ts
+var RepositoryImporter = class {
+  storage;
+  actorId;
+  migrationEngine = new MigrationEngine();
+  constructor(config) {
+    this.storage = config.storage;
+    this.actorId = config.actorId;
+  }
+  /**
+   * Import an export archive according to the provided options.
+   * Convenience wrapper around importStream() — use for small repositories.
+   * For large repositories, use importStream() directly.
+   */
+  async import(archive, options) {
+    const validationWarnings = this.validateArchive(archive);
+    if (validationWarnings.length > 0) {
+      const hasCritical = validationWarnings.some((w) => w.code === "invalid_archive");
+      if (hasCritical) {
+        return {
+          success: false,
+          repositoryId: options.target.repositoryId,
+          statistics: { entitiesImported: 0, entitiesSkipped: 0, relationshipsImported: 0, relationshipsSkipped: 0, vocabularyExtensions: 0 },
+          warnings: validationWarnings
+        };
+      }
+    }
+    const header = {
+      manifest: archive.manifest,
+      vocabulary: archive.vocabulary
+    };
+    async function* toChunks() {
+      yield { entities: archive.entities };
+      yield { relationships: archive.relationships };
+    }
+    return this.importStream(header, toChunks(), options);
+  }
+  /**
+   * Streaming import — processes data from an async iterable of chunks.
+   * For large repositories, this avoids loading everything into memory at once.
+   *
+   * The caller provides the header (manifest + vocabulary) up front,
+   * then streams ImportChunks containing batches of entities and/or relationships.
+   */
+  async importStream(header, chunks, options) {
+    const warnings = [];
+    if (!header.manifest) {
+      warnings.push({ code: "invalid_archive", message: "Header is missing manifest" });
+    }
+    if (!header.vocabulary) {
+      warnings.push({ code: "invalid_archive", message: "Header is missing vocabulary" });
+    }
+    if (options.target.mode === "create") {
+      return this.importStreamCreate(header, chunks, options, warnings);
+    } else {
+      return this.importStreamMerge(header, chunks, options, warnings);
+    }
+  }
+  /** Streaming create mode — set up repo then pipe chunks through importBulk */
+  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
+    });
+    await this.storage.saveVocabulary(target.repositoryId, header.vocabulary);
+    let entitiesImported = 0;
+    let relationshipsImported = 0;
+    for await (const chunk of chunks) {
+      const bulkResult = await this.storage.importBulk(target.repositoryId, [chunk]);
+      entitiesImported += bulkResult.entitiesImported;
+      relationshipsImported += bulkResult.relationshipsImported;
+      for (const e of bulkResult.errors) {
+        warnings.push({
+          code: "import_error",
+          message: `Failed to import ${e.item}: ${e.error}`,
+          id: e.item
+        });
+      }
+    }
+    return {
+      success: true,
+      repositoryId: target.repositoryId,
+      statistics: {
+        entitiesImported,
+        entitiesSkipped: 0,
+        relationshipsImported,
+        relationshipsSkipped: 0,
+        vocabularyExtensions: 0
+      },
+      warnings
+    };
+  }
+  /** Streaming merge mode — process chunks with per-entity conflict resolution */
+  async importStreamMerge(header, chunks, options, warnings) {
+    const target = options.target;
+    const repositoryId = target.repositoryId;
+    const existingRepo = await this.storage.getRepository(repositoryId);
+    if (!existingRepo) {
+      return {
+        success: false,
+        repositoryId,
+        statistics: { entitiesImported: 0, entitiesSkipped: 0, relationshipsImported: 0, relationshipsSkipped: 0, vocabularyExtensions: 0 },
+        warnings: [{ code: "repository_not_found", message: `Repository "${repositoryId}" not found` }]
+      };
+    }
+    const targetVocabulary = await this.storage.getVocabulary(repositoryId);
+    const conflictMode = options.vocabularyConflict ?? "reject";
+    const migrationResult = this.migrationEngine.migrate(
+      header.vocabulary,
+      targetVocabulary,
+      conflictMode,
+      this.actorId
+    );
+    warnings.push(...migrationResult.warnings);
+    if (!migrationResult.success) {
+      return {
+        success: false,
+        repositoryId,
+        statistics: { entitiesImported: 0, entitiesSkipped: 0, relationshipsImported: 0, relationshipsSkipped: 0, vocabularyExtensions: 0 },
+        warnings: [...warnings, { code: "vocabulary_migration_failed", message: migrationResult.reason ?? "Vocabulary migration failed" }]
+      };
+    }
+    if (migrationResult.mergedVocabulary && migrationResult.mergedVocabulary !== targetVocabulary) {
+      await this.storage.saveVocabulary(repositoryId, migrationResult.mergedVocabulary);
+    }
+    const entityConflict = options.entityConflict ?? "skip";
+    let entitiesImported = 0;
+    let entitiesSkipped = 0;
+    let relationshipsImported = 0;
+    let relationshipsSkipped = 0;
+    for await (const chunk of chunks) {
+      if (chunk.entities) {
+        for (const entity of chunk.entities) {
+          let existing = await this.storage.getEntity(repositoryId, entity.id);
+          if (!existing && entity.slug) {
+            existing = await this.storage.getEntityBySlug(repositoryId, entity.slug);
+          }
+          if (existing) {
+            const existingId = existing.id;
+            switch (entityConflict) {
+              case "skip":
+                entitiesSkipped++;
+                warnings.push({
+                  code: "entity_skipped",
+                  message: `Entity "${entity.slug}" already exists \u2014 skipped`,
+                  id: existingId
+                });
+                continue;
+              case "overwrite":
+                await this.storage.updateEntity(repositoryId, existingId, {
+                  label: entity.label,
+                  slug: entity.slug,
+                  summary: entity.summary,
+                  properties: entity.properties,
+                  data: entity.data,
+                  dataFormat: entity.dataFormat,
+                  provenance: entity.provenance,
+                  embedding: entity.embedding
+                });
+                entitiesImported++;
+                warnings.push({
+                  code: "entity_overwritten",
+                  message: `Entity "${entity.slug}" overwritten`,
+                  id: existingId
+                });
+                continue;
+              case "rename": {
+                const renamedEntity = { ...entity, id: generateId(), slug: `${entity.slug}-imported` };
+                await this.storage.createEntity(repositoryId, renamedEntity);
+                entitiesImported++;
+                warnings.push({
+                  code: "entity_renamed",
+                  message: `Entity "${entity.slug}" slug renamed to "${renamedEntity.slug}"`,
+                  id: entity.id
+                });
+                continue;
+              }
+            }
+          } else {
+            await this.storage.createEntity(repositoryId, entity);
+            entitiesImported++;
+          }
+        }
+      }
+      if (chunk.relationships) {
+        for (const rel of chunk.relationships) {
+          const existing = await this.storage.getRelationship(repositoryId, rel.id);
+          if (existing) {
+            relationshipsSkipped++;
+            warnings.push({
+              code: "relationship_skipped",
+              message: `Relationship "${rel.id}" already exists \u2014 skipped`,
+              relationshipId: rel.id
+            });
+          } else {
+            const sourceExists = await this.storage.getEntity(repositoryId, rel.sourceEntityId);
+            const targetExists = await this.storage.getEntity(repositoryId, rel.targetEntityId);
+            if (!sourceExists || !targetExists) {
+              relationshipsSkipped++;
+              warnings.push({
+                code: "relationship_orphaned",
+                message: `Relationship "${rel.id}" skipped \u2014 source or target entity missing`,
+                relationshipId: rel.id
+              });
+            } else {
+              await this.storage.createRelationship(repositoryId, rel);
+              relationshipsImported++;
+            }
+          }
+        }
+      }
+    }
+    const vocabExtensions = migrationResult.warnings.filter(
+      (w) => w.code === "entity_type_added" || w.code === "relationship_type_added"
+    ).length;
+    return {
+      success: true,
+      repositoryId,
+      statistics: {
+        entitiesImported,
+        entitiesSkipped,
+        relationshipsImported,
+        relationshipsSkipped,
+        vocabularyExtensions: vocabExtensions
+      },
+      warnings
+    };
+  }
+  /** Basic archive validation */
+  validateArchive(archive) {
+    const warnings = [];
+    if (!archive.manifest) {
+      warnings.push({ code: "invalid_archive", message: "Archive is missing manifest" });
+    }
+    if (!archive.vocabulary) {
+      warnings.push({ code: "invalid_archive", message: "Archive is missing vocabulary" });
+    }
+    if (!archive.entities) {
+      warnings.push({ code: "invalid_archive", message: "Archive is missing entities array" });
+    }
+    if (!archive.relationships) {
+      warnings.push({ code: "invalid_archive", message: "Archive is missing relationships array" });
+    }
+    return warnings;
+  }
+};
+
+// src/core/DeepMemory.ts
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function generateId() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === "x" ? r : r & 3 | 8).toString(16);
+  });
+}
+function isValidUuid(value) {
+  return UUID_RE.test(value);
+}
+var DeepMemory = class {
+  storage;
+  search;
+  embedding;
+  /** Reserved for future distributed locking support */
+  lock;
+  provenance;
+  globalEventBus;
+  initialised = false;
+  constructor(config) {
+    this.storage = config.storage;
+    this.search = config.search;
+    this.embedding = config.embedding;
+    this.lock = config.lock;
+    this.provenance = new ProvenanceTracker(config.provenance);
+    this.globalEventBus = new EventBus(config.provenance);
+  }
+  /** Initialise the storage provider (call once before use) */
+  async ensureInitialised() {
+    if (!this.initialised) {
+      if (this.storage.initialise) {
+        await this.storage.initialise();
+      }
+      this.initialised = true;
+    }
+  }
+  /** Create or migrate the storage schema. Call once at deployment / startup, not per-request. */
+  async ensureSchema() {
+    await this.ensureInitialised();
+    if (this.storage.ensureSchema) {
+      await this.storage.ensureSchema();
+    }
+  }
+  validateRepositoryId(repositoryId) {
+    if (!isValidUuid(repositoryId)) {
+      throw new InvalidInputError(
+        "repositoryId",
+        `Repository ID "${repositoryId}" is not a valid UUID`,
+        `Provide a valid UUID (e.g. "550e8400-e29b-41d4-a716-446655440000") or omit repositoryId to auto-generate one.`
+      );
+    }
+  }
+  /** Create a new memory repository */
+  async createRepository(config) {
+    await this.ensureInitialised();
+    const repositoryId = config.repositoryId ?? generateId();
+    this.validateRepositoryId(repositoryId);
+    const context = this.provenance.getContext();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const governanceConfig = config.governance ?? { mode: "open" };
+    const metadata = { ...config.metadata };
+    if (this.embedding) {
+      if (!metadata.embeddingModelId) {
+        metadata.embeddingModelId = this.embedding.modelId();
+      }
+      if (metadata.embeddingDimensions === void 0) {
+        try {
+          metadata.embeddingDimensions = this.embedding.dimensions();
+        } catch {
+        }
+      }
+    }
+    await this.storage.createRepository({
+      repositoryId,
+      type: config.type,
+      label: config.label,
+      description: config.description,
+      legal: config.legal,
+      owner: config.owner,
+      governanceConfig,
+      metadata: Object.keys(metadata).length > 0 ? metadata : void 0,
+      createdAt: now,
+      createdBy: context.actorId
+    });
+    const vocabulary = config.vocabulary ? buildVocabulary(config.vocabulary, context.actorId) : createEmptyVocabulary(context.actorId);
+    await this.storage.saveVocabulary(repositoryId, vocabulary);
+    const eventBus = new EventBus(context, repositoryId);
+    const vocabularyEngine = new VocabularyEngine({
+      repositoryId,
+      storageProvider: this.storage,
+      governanceConfig,
+      embeddingProvider: this.embedding
+    });
+    const repo = new MemoryRepository({
+      repositoryId,
+      storage: this.storage,
+      search: this.search,
+      embedding: this.embedding,
+      vocabularyEngine,
+      provenanceTracker: this.provenance,
+      eventBus
+    });
+    await this.globalEventBus.emit("repository:created", {
+      repositoryId,
+      label: config.label
+    });
+    return repo;
+  }
+  /** Open an existing repository */
+  async openRepository(repositoryId) {
+    await this.ensureInitialised();
+    this.validateRepositoryId(repositoryId);
+    const storedRepo = await this.storage.getRepository(repositoryId);
+    if (!storedRepo) {
+      throw new RepositoryNotFoundError(repositoryId);
+    }
+    const context = this.provenance.getContext();
+    const eventBus = new EventBus(context, repositoryId);
+    const vocabularyEngine = new VocabularyEngine({
+      repositoryId,
+      storageProvider: this.storage,
+      governanceConfig: storedRepo.governanceConfig,
+      embeddingProvider: this.embedding
+    });
+    const repo = new MemoryRepository({
+      repositoryId,
+      storage: this.storage,
+      search: this.search,
+      embedding: this.embedding,
+      vocabularyEngine,
+      provenanceTracker: this.provenance,
+      eventBus
+    });
+    await this.globalEventBus.emit("repository:opened", { repositoryId });
+    return repo;
+  }
+  /** List all repositories */
+  async listRepositories(filter) {
+    await this.ensureInitialised();
+    const result = await this.storage.listRepositories(filter);
+    return {
+      items: result.items.map((stored) => ({
+        repositoryId: stored.repositoryId,
+        type: stored.type,
+        label: stored.label,
+        description: stored.description,
+        governanceMode: stored.governanceConfig.mode
+      })),
+      total: result.total,
+      hasMore: result.hasMore,
+      limit: result.limit,
+      offset: result.offset
+    };
+  }
+  /** Update repository metadata and settings */
+  async updateRepository(repositoryId, updates) {
+    await this.ensureInitialised();
+    this.validateRepositoryId(repositoryId);
+    const updated = await this.storage.updateRepository(repositoryId, updates);
+    await this.globalEventBus.emit("repository:updated", { repositoryId });
+    return updated;
+  }
+  /** Delete a repository */
+  async deleteRepository(repositoryId) {
+    await this.ensureInitialised();
+    this.validateRepositoryId(repositoryId);
+    await this.storage.deleteRepository(repositoryId);
+    await this.globalEventBus.emit("repository:deleted", { repositoryId });
+  }
+  /** Export a repository to a portable archive */
+  async exportRepository(repositoryId) {
+    await this.ensureInitialised();
+    const exporter = new RepositoryExporter({
+      storage: this.storage,
+      provenance: this.provenance.getContext()
+    });
+    const archive = await exporter.export(repositoryId);
+    await this.globalEventBus.emit("export:completed", {
+      repositoryId,
+      entityCount: archive.entities.length,
+      relationshipCount: archive.relationships.length
+    });
+    return archive;
+  }
+  /** Import a repository from a portable archive */
+  async importRepository(archive, options) {
+    await this.ensureInitialised();
+    const importer = new RepositoryImporter({
+      storage: this.storage,
+      actorId: this.provenance.getContext().actorId
+    });
+    const result = await importer.import(archive, options);
+    if (result.success) {
+      await this.globalEventBus.emit("import:completed", {
+        repositoryId: result.repositoryId,
+        entitiesImported: result.statistics.entitiesImported,
+        relationshipsImported: result.statistics.relationshipsImported
+      });
+    } else {
+      await this.globalEventBus.emit("import:failed", {
+        repositoryId: result.repositoryId,
+        error: result.warnings.map((w) => w.message).join("; ")
+      });
+    }
+    return result;
+  }
+  /**
+   * Stream a repository export as an async generator.
+   * Yields: manifest → vocabulary → entity chunks → relationship chunks.
+   * Use for large repositories to avoid loading everything into memory.
+   */
+  async *exportRepositoryStream(repositoryId) {
+    await this.ensureInitialised();
+    const exporter = new RepositoryExporter({
+      storage: this.storage,
+      provenance: this.provenance.getContext()
+    });
+    await this.globalEventBus.emit("export:started", { repositoryId });
+    let entityCount = 0;
+    let relationshipCount = 0;
+    for await (const item of exporter.exportStream(repositoryId)) {
+      yield item;
+      if (item.type === "entities") {
+        entityCount += item.data.length;
+      } else if (item.type === "relationships") {
+        relationshipCount += item.data.length;
+      }
+    }
+    await this.globalEventBus.emit("export:completed", {
+      repositoryId,
+      entityCount,
+      relationshipCount
+    });
+  }
+  /**
+   * Import a repository from a stream of chunks.
+   * Use for large repositories to avoid loading everything into memory.
+   */
+  async importRepositoryStream(header, chunks, options) {
+    await this.ensureInitialised();
+    const importer = new RepositoryImporter({
+      storage: this.storage,
+      actorId: this.provenance.getContext().actorId
+    });
+    await this.globalEventBus.emit("import:started", { repositoryId: options.target.repositoryId });
+    const result = await importer.importStream(header, chunks, options);
+    if (result.success) {
+      await this.globalEventBus.emit("import:completed", {
+        repositoryId: result.repositoryId,
+        entitiesImported: result.statistics.entitiesImported,
+        relationshipsImported: result.statistics.relationshipsImported
+      });
+    } else {
+      await this.globalEventBus.emit("import:failed", {
+        repositoryId: result.repositoryId,
+        error: result.warnings.map((w) => w.message).join("; ")
+      });
+    }
+    return result;
+  }
+  /** Subscribe to global events */
+  on(event, handler) {
+    return this.globalEventBus.on(event, handler);
+  }
+  /** Update the provenance context (e.g., new conversation) */
+  updateProvenance(context) {
+    this.provenance.updateContext(context);
+    this.globalEventBus.updateProvenance(this.provenance.getContext());
+  }
+  /** Dispose of all resources */
+  async dispose() {
+    this.globalEventBus.removeAllListeners();
+    if (this.storage.dispose) {
+      await this.storage.dispose();
+    }
+    this.initialised = false;
+  }
+};
+
+// 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();
+  getStore(repositoryId) {
+    const store = this.stores.get(repositoryId);
+    if (!store) {
+      throw new RepositoryNotFoundError(repositoryId);
+    }
+    return store;
+  }
+  // ─── Lifecycle ─────────────────────────────────────────────────────
+  async initialise() {
+  }
+  async dispose() {
+    this.stores.clear();
+  }
+  // ─── Repository ────────────────────────────────────────────────────
+  async createRepository(config) {
+    if (this.stores.has(config.repositoryId)) {
+      throw new DuplicateRepositoryError(config.repositoryId);
+    }
+    const repository = {
+      repositoryId: config.repositoryId,
+      type: config.type,
+      label: config.label,
+      description: config.description,
+      legal: config.legal,
+      owner: config.owner,
+      governanceConfig: config.governanceConfig,
+      metadata: config.metadata,
+      createdAt: config.createdAt,
+      createdBy: config.createdBy
+    };
+    this.stores.set(config.repositoryId, {
+      repository,
+      vocabulary: createEmptyVocabulary(config.createdBy),
+      vocabularyChangeLog: [],
+      entities: /* @__PURE__ */ new Map(),
+      slugIndex: /* @__PURE__ */ new Map(),
+      relationships: /* @__PURE__ */ new Map()
+    });
+    return repository;
+  }
+  async getRepository(repositoryId) {
+    return this.stores.get(repositoryId)?.repository ?? null;
+  }
+  async listRepositories(filter) {
+    let items = Array.from(this.stores.values()).map((store) => ({
+      repositoryId: store.repository.repositoryId,
+      type: store.repository.type,
+      label: store.repository.label,
+      description: store.repository.description,
+      governanceConfig: store.repository.governanceConfig
+    }));
+    if (filter?.type) {
+      items = items.filter((r) => r.type === filter.type);
+    }
+    const total = items.length;
+    const offset = filter?.offset ?? 0;
+    const limit = filter?.limit ?? 20;
+    const paged = items.slice(offset, offset + limit);
+    return {
+      items: paged,
+      total,
+      hasMore: offset + paged.length < total,
+      limit,
+      offset
+    };
+  }
+  async updateRepository(repositoryId, updates) {
+    const store = this.stores.get(repositoryId);
+    if (!store) {
+      throw new RepositoryNotFoundError(repositoryId);
+    }
+    const repo = store.repository;
+    if (updates.label !== void 0) repo.label = updates.label;
+    if (updates.description !== void 0) repo.description = updates.description;
+    if (updates.type !== void 0) repo.type = updates.type;
+    if (updates.legal !== void 0) repo.legal = updates.legal;
+    if (updates.owner !== void 0) repo.owner = updates.owner;
+    if (updates.governanceConfig !== void 0) repo.governanceConfig = updates.governanceConfig;
+    if (updates.metadata !== void 0) repo.metadata = { ...repo.metadata, ...updates.metadata };
+    return repo;
+  }
+  async deleteRepository(repositoryId) {
+    if (!this.stores.has(repositoryId)) {
+      throw new RepositoryNotFoundError(repositoryId);
+    }
+    this.stores.delete(repositoryId);
+  }
+  async getRepositoryStats(repositoryId) {
+    const store = this.getStore(repositoryId);
+    const entityTypeBreakdown = {};
+    for (const entity of store.entities.values()) {
+      entityTypeBreakdown[entity.entityType] = (entityTypeBreakdown[entity.entityType] ?? 0) + 1;
+    }
+    const relationshipTypeBreakdown = {};
+    for (const rel of store.relationships.values()) {
+      relationshipTypeBreakdown[rel.relationshipType] = (relationshipTypeBreakdown[rel.relationshipType] ?? 0) + 1;
+    }
+    return {
+      entityCount: store.entities.size,
+      relationshipCount: store.relationships.size,
+      vocabularyVersion: store.vocabulary.version,
+      entityTypeBreakdown,
+      relationshipTypeBreakdown
+    };
+  }
+  // ─── Vocabulary ────────────────────────────────────────────────────
+  async getVocabulary(repositoryId) {
+    const store = this.getStore(repositoryId);
+    return store.vocabulary;
+  }
+  async saveVocabulary(repositoryId, vocabulary) {
+    const store = this.getStore(repositoryId);
+    store.vocabulary = vocabulary;
+  }
+  async getVocabularyChangeLog(repositoryId, options) {
+    const store = this.getStore(repositoryId);
+    const limit = options?.limit ?? 10;
+    const offset = options?.offset ?? 0;
+    const items = store.vocabularyChangeLog.slice(offset, offset + limit);
+    return {
+      items,
+      total: store.vocabularyChangeLog.length,
+      hasMore: offset + limit < store.vocabularyChangeLog.length,
+      limit,
+      offset
+    };
+  }
+  // ─── Entities ──────────────────────────────────────────────────────
+  async createEntity(repositoryId, entity) {
+    const store = this.getStore(repositoryId);
+    if (store.entities.has(entity.id)) {
+      throw new DuplicateEntityError(entity.id);
+    }
+    store.entities.set(entity.id, entity);
+    store.slugIndex.set(entity.slug, entity.id);
+    return entity;
+  }
+  async getEntity(repositoryId, entityId) {
+    const store = this.getStore(repositoryId);
+    return store.entities.get(entityId) ?? null;
+  }
+  async getEntityBySlug(repositoryId, slug) {
+    const store = this.getStore(repositoryId);
+    const id = store.slugIndex.get(slug);
+    if (!id) return null;
+    return store.entities.get(id) ?? null;
+  }
+  async getEntities(repositoryId, entityIds) {
+    const store = this.getStore(repositoryId);
+    const result = /* @__PURE__ */ new Map();
+    for (const id of entityIds) {
+      const entity = store.entities.get(id);
+      if (entity) {
+        result.set(id, entity);
+      }
+    }
+    return result;
+  }
+  async updateEntity(repositoryId, entityId, updates) {
+    const store = this.getStore(repositoryId);
+    const existing = store.entities.get(entityId);
+    if (!existing) {
+      throw new EntityNotFoundError(entityId);
+    }
+    const updated = {
+      ...existing,
+      label: updates.label ?? existing.label,
+      summary: updates.summary !== void 0 ? updates.summary : existing.summary,
+      properties: updates.properties ?? existing.properties,
+      data: updates.data !== void 0 ? updates.data : existing.data,
+      dataFormat: updates.dataFormat !== void 0 ? updates.dataFormat : existing.dataFormat,
+      provenance: updates.provenance,
+      embedding: updates.embedding ?? existing.embedding
+    };
+    if (updates.slug && updates.slug !== existing.slug) {
+      store.slugIndex.delete(existing.slug);
+      updated.slug = updates.slug;
+      store.slugIndex.set(updates.slug, entityId);
+    }
+    store.entities.set(entityId, updated);
+    return updated;
+  }
+  async deleteEntity(repositoryId, entityId) {
+    const store = this.getStore(repositoryId);
+    const existing = store.entities.get(entityId);
+    if (!existing) {
+      throw new EntityNotFoundError(entityId);
+    }
+    store.slugIndex.delete(existing.slug);
+    store.entities.delete(entityId);
+    for (const [relId, rel] of store.relationships) {
+      if (rel.sourceEntityId === entityId || rel.targetEntityId === entityId) {
+        store.relationships.delete(relId);
+      }
+    }
+  }
+  async deleteEntitiesByType(repositoryId, entityType) {
+    const store = this.getStore(repositoryId);
+    const entityIds = /* @__PURE__ */ new Set();
+    for (const [id, entity] of store.entities) {
+      if (entity.entityType === entityType) {
+        entityIds.add(id);
+        store.slugIndex.delete(entity.slug);
+      }
+    }
+    let deletedRelationships = 0;
+    for (const [relId, rel] of store.relationships) {
+      if (entityIds.has(rel.sourceEntityId) || entityIds.has(rel.targetEntityId)) {
+        store.relationships.delete(relId);
+        deletedRelationships++;
+      }
+    }
+    for (const id of entityIds) {
+      store.entities.delete(id);
+    }
+    return { deletedEntities: entityIds.size, deletedRelationships };
+  }
+  async findEntities(repositoryId, query) {
+    const store = this.getStore(repositoryId);
+    let matches = Array.from(store.entities.values());
+    if (query.entityTypes && query.entityTypes.length > 0) {
+      matches = matches.filter((e) => query.entityTypes.includes(e.entityType));
+    }
+    if (query.searchTerm) {
+      const term = query.searchTerm.toLowerCase();
+      matches = matches.filter(
+        (e) => e.label.toLowerCase().includes(term) || e.summary && e.summary.toLowerCase().includes(term)
+      );
+    }
+    if (query.properties) {
+      const entries = Object.entries(query.properties);
+      matches = matches.filter(
+        (e) => entries.every(([key, value]) => e.properties[key] === value)
+      );
+    }
+    if (query.provenance) {
+      matches = matches.filter((e) => matchesProvenance(e.provenance, query.provenance));
+    }
+    const total = matches.length;
+    const items = matches.slice(query.offset, query.offset + query.limit);
+    return {
+      items,
+      total,
+      hasMore: query.offset + query.limit < total,
+      limit: query.limit,
+      offset: query.offset
+    };
+  }
+  // ─── Relationships ─────────────────────────────────────────────────
+  async createRelationship(repositoryId, relationship) {
+    const store = this.getStore(repositoryId);
+    if (store.relationships.has(relationship.id)) {
+      throw new DuplicateRelationshipError(relationship.id);
+    }
+    store.relationships.set(relationship.id, relationship);
+    return relationship;
+  }
+  async getRelationship(repositoryId, relationshipId) {
+    const store = this.getStore(repositoryId);
+    return store.relationships.get(relationshipId) ?? null;
+  }
+  async getEntityRelationships(repositoryId, entityId, options) {
+    const store = this.getStore(repositoryId);
+    const direction = options?.direction ?? "both";
+    let matches = Array.from(store.relationships.values());
+    matches = matches.filter((rel) => {
+      const isSource = rel.sourceEntityId === entityId;
+      const isTarget = rel.targetEntityId === entityId;
+      const isBidirectionalTarget = rel.bidirectional && isTarget;
+      switch (direction) {
+        case "outbound":
+          return isSource || isBidirectionalTarget;
+        case "inbound":
+          return isTarget || rel.bidirectional && isSource;
+        case "both":
+        default:
+          return isSource || isTarget;
+      }
+    });
+    if (options?.relationshipTypes && options.relationshipTypes.length > 0) {
+      matches = matches.filter((r) => options.relationshipTypes.includes(r.relationshipType));
+    }
+    if (options?.propertyFilters && options.propertyFilters.length > 0) {
+      matches = matches.filter((r) => matchesPropertyFilters(r.properties, options.propertyFilters));
+    }
+    const total = matches.length;
+    const limit = options?.limit ?? 10;
+    const offset = options?.offset ?? 0;
+    const items = matches.slice(offset, offset + limit);
+    return {
+      items,
+      total,
+      hasMore: offset + limit < total,
+      limit,
+      offset
+    };
+  }
+  async deleteRelationship(repositoryId, relationshipId) {
+    const store = this.getStore(repositoryId);
+    if (!store.relationships.has(relationshipId)) {
+      throw new RelationshipNotFoundError(relationshipId);
+    }
+    store.relationships.delete(relationshipId);
+  }
+  async deleteRelationshipsByType(repositoryId, relationshipType) {
+    const store = this.getStore(repositoryId);
+    let deletedRelationships = 0;
+    for (const [relId, rel] of store.relationships) {
+      if (rel.relationshipType === relationshipType) {
+        store.relationships.delete(relId);
+        deletedRelationships++;
+      }
+    }
+    return { deletedRelationships };
+  }
+  // ─── Graph Traversal ───────────────────────────────────────────────
+  async exploreNeighbourhood(repositoryId, entityId, options) {
+    const store = this.getStore(repositoryId);
+    if (!store.entities.has(entityId)) {
+      throw new EntityNotFoundError(entityId);
+    }
+    const layers = [];
+    const visited = /* @__PURE__ */ new Set([entityId]);
+    let currentFrontier = /* @__PURE__ */ new Set([entityId]);
+    for (let depth = 0; depth < options.depth; depth++) {
+      const layer = {};
+      const nextFrontier = /* @__PURE__ */ new Set();
+      for (const frontierEntityId of currentFrontier) {
+        for (const rel of store.relationships.values()) {
+          const isSource = rel.sourceEntityId === frontierEntityId;
+          const isTarget = rel.targetEntityId === frontierEntityId;
+          let matchesDirection = false;
+          let connectedEntityId;
+          if (isSource && (options.direction === "outbound" || options.direction === "both")) {
+            matchesDirection = true;
+            connectedEntityId = rel.targetEntityId;
+          } else if (isTarget && (options.direction === "inbound" || options.direction === "both")) {
+            matchesDirection = true;
+            connectedEntityId = rel.sourceEntityId;
+          } else if (rel.bidirectional) {
+            if (isSource && options.direction === "inbound") {
+              matchesDirection = true;
+              connectedEntityId = rel.targetEntityId;
+            } else if (isTarget && options.direction === "outbound") {
+              matchesDirection = true;
+              connectedEntityId = rel.sourceEntityId;
+            }
+          }
+          if (!matchesDirection || !connectedEntityId) continue;
+          if (visited.has(connectedEntityId)) continue;
+          if (options.relationshipTypes && !options.relationshipTypes.includes(rel.relationshipType)) {
+            continue;
+          }
+          if (options.relationshipPropertyFilters && options.relationshipPropertyFilters.length > 0) {
+            if (!matchesPropertyFilters(rel.properties, options.relationshipPropertyFilters)) {
+              continue;
+            }
+          }
+          const connectedEntity = store.entities.get(connectedEntityId);
+          if (!connectedEntity) continue;
+          if (options.entityTypes && !options.entityTypes.includes(connectedEntity.entityType)) {
+            continue;
+          }
+          const relType = rel.relationshipType;
+          if (!layer[relType]) {
+            layer[relType] = { total: 0, entities: [], relationships: [] };
+          }
+          layer[relType].total++;
+          const group = layer[relType];
+          if (group.entities.length < options.limitPerType) {
+            group.entities.push(connectedEntity);
+            group.relationships.push(rel);
+          }
+          nextFrontier.add(connectedEntityId);
+          visited.add(connectedEntityId);
+        }
+      }
+      layers.push(layer);
+      currentFrontier = nextFrontier;
+      if (nextFrontier.size === 0) break;
+    }
+    return {
+      centreId: entityId,
+      layers
+    };
+  }
+  async findPaths(repositoryId, sourceId, targetId, options) {
+    const store = this.getStore(repositoryId);
+    if (!store.entities.has(sourceId)) {
+      throw new EntityNotFoundError(sourceId);
+    }
+    if (!store.entities.has(targetId)) {
+      throw new EntityNotFoundError(targetId);
+    }
+    if (sourceId === targetId) {
+      return { paths: [{ entityIds: [sourceId], relationshipIds: [] }], totalPaths: 1 };
+    }
+    const paths = [];
+    const queue = [
+      { entityId: sourceId, path: [sourceId], relPath: [] }
+    ];
+    const visitedAtDepth = /* @__PURE__ */ new Map();
+    visitedAtDepth.set(sourceId, 0);
+    while (queue.length > 0 && paths.length < options.limit + options.offset) {
+      const current = queue.shift();
+      if (current.path.length > options.maxDepth + 1) continue;
+      for (const rel of store.relationships.values()) {
+        if (options.relationshipTypes && !options.relationshipTypes.includes(rel.relationshipType)) {
+          continue;
+        }
+        if (options.relationshipPropertyFilters && options.relationshipPropertyFilters.length > 0) {
+          if (!matchesPropertyFilters(rel.properties, options.relationshipPropertyFilters)) {
+            continue;
+          }
+        }
+        let nextEntityId;
+        if (rel.sourceEntityId === current.entityId) {
+          nextEntityId = rel.targetEntityId;
+        } else if (rel.targetEntityId === current.entityId) {
+          nextEntityId = rel.sourceEntityId;
+        }
+        if (!nextEntityId) continue;
+        if (current.path.includes(nextEntityId) && nextEntityId !== targetId) continue;
+        if (options.entityTypes && nextEntityId !== targetId) {
+          const nextEntity = store.entities.get(nextEntityId);
+          if (nextEntity && !options.entityTypes.includes(nextEntity.entityType)) continue;
+        }
+        const newPath = [...current.path, nextEntityId];
+        const newRelPath = [...current.relPath, rel.id];
+        if (nextEntityId === targetId) {
+          paths.push({ entityIds: newPath, relationshipIds: newRelPath });
+        } else if (newPath.length <= options.maxDepth) {
+          const prevDepth = visitedAtDepth.get(nextEntityId);
+          if (prevDepth === void 0 || prevDepth >= newPath.length - 1) {
+            visitedAtDepth.set(nextEntityId, newPath.length - 1);
+            queue.push({ entityId: nextEntityId, path: newPath, relPath: newRelPath });
+          }
+        }
+      }
+    }
+    const paginatedPaths = paths.slice(options.offset, options.offset + options.limit);
+    return {
+      paths: paginatedPaths,
+      totalPaths: paths.length
+    };
+  }
+  // ─── Timeline ──────────────────────────────────────────────────────
+  async getTimeline(repositoryId, entityId, options) {
+    const store = this.getStore(repositoryId);
+    const entity = store.entities.get(entityId);
+    if (!entity) {
+      throw new EntityNotFoundError(entityId);
+    }
+    const events = [];
+    events.push({
+      timestamp: entity.provenance.createdAt,
+      eventType: "entity:created",
+      entityId
+    });
+    if (entity.provenance.modifiedAt !== entity.provenance.createdAt) {
+      events.push({
+        timestamp: entity.provenance.modifiedAt,
+        eventType: "entity:updated",
+        entityId
+      });
+    }
+    for (const rel of store.relationships.values()) {
+      if (rel.sourceEntityId === entityId || rel.targetEntityId === entityId) {
+        events.push({
+          timestamp: rel.provenance.createdAt,
+          eventType: "relationship:created",
+          entityId,
+          relationshipId: rel.id
+        });
+      }
+    }
+    let filtered = events;
+    if (options.timeRange) {
+      const from = new Date(options.timeRange.from).getTime();
+      const to = new Date(options.timeRange.to).getTime();
+      filtered = filtered.filter((e) => {
+        const t = new Date(e.timestamp).getTime();
+        return t >= from && t <= to;
+      });
+    }
+    if (options.eventTypes && options.eventTypes.length > 0) {
+      filtered = filtered.filter((e) => options.eventTypes.includes(e.eventType));
+    }
+    if (options.provenance) {
+      const prov = options.provenance;
+      filtered = filtered.filter((e) => {
+        if (e.eventType.startsWith("entity:")) {
+          const ent = store.entities.get(e.entityId);
+          return ent ? matchesProvenance(ent.provenance, prov) : false;
+        }
+        if (e.relationshipId) {
+          const rel = store.relationships.get(e.relationshipId);
+          return rel ? matchesProvenance(rel.provenance, prov) : false;
+        }
+        return true;
+      });
+    }
+    filtered.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    const total = filtered.length;
+    const items = filtered.slice(options.offset, options.offset + options.limit);
+    return {
+      events: items,
+      total
+    };
+  }
+  // ─── Bulk Operations ───────────────────────────────────────────────
+  async *exportAll(repositoryId) {
+    const store = this.getStore(repositoryId);
+    const entities = Array.from(store.entities.values());
+    const batchSize = 100;
+    for (let i = 0; i < entities.length; i += batchSize) {
+      const batch = entities.slice(i, i + batchSize);
+      yield {
+        type: "entities",
+        data: batch,
+        sequence: Math.floor(i / batchSize),
+        isLast: i + batchSize >= entities.length
+      };
+    }
+    if (entities.length === 0) {
+      yield { type: "entities", data: [], sequence: 0, isLast: true };
+    }
+    const relationships = Array.from(store.relationships.values());
+    for (let i = 0; i < relationships.length; i += batchSize) {
+      const batch = relationships.slice(i, i + batchSize);
+      yield {
+        type: "relationships",
+        data: batch,
+        sequence: Math.floor(i / batchSize),
+        isLast: i + batchSize >= relationships.length
+      };
+    }
+    if (relationships.length === 0) {
+      yield { type: "relationships", data: [], sequence: 0, isLast: true };
+    }
+  }
+  async importBulk(repositoryId, data) {
+    const store = this.getStore(repositoryId);
+    let entitiesImported = 0;
+    let relationshipsImported = 0;
+    const errors = [];
+    for (const chunk of data) {
+      if (chunk.entities) {
+        for (const entity of chunk.entities) {
+          try {
+            store.entities.set(entity.id, entity);
+            store.slugIndex.set(entity.slug, entity.id);
+            entitiesImported++;
+          } catch (err) {
+            errors.push({
+              item: entity.id,
+              error: err instanceof Error ? err.message : String(err)
+            });
+          }
+        }
+      }
+      if (chunk.relationships) {
+        for (const rel of chunk.relationships) {
+          try {
+            store.relationships.set(rel.id, rel);
+            relationshipsImported++;
+          } catch (err) {
+            errors.push({
+              item: rel.id,
+              error: err instanceof Error ? err.message : String(err)
+            });
+          }
+        }
+      }
+    }
+    return { entitiesImported, relationshipsImported, errors };
+  }
+};
+function matchesProvenance(prov, filter) {
+  if (filter.conversationIds && filter.conversationIds.length > 0) {
+    const matchesCreated = prov.createdInConversation && filter.conversationIds.includes(prov.createdInConversation);
+    const matchesModified = prov.modifiedInConversation && filter.conversationIds.includes(prov.modifiedInConversation);
+    if (!matchesCreated && !matchesModified) return false;
+  }
+  if (filter.actors && filter.actors.length > 0) {
+    const matchesCreator = filter.actors.includes(prov.createdBy);
+    const matchesModifier = filter.actors.includes(prov.modifiedBy);
+    if (!matchesCreator && !matchesModifier) return false;
+  }
+  if (filter.dateRange) {
+    const from = new Date(filter.dateRange.from).getTime();
+    const to = new Date(filter.dateRange.to).getTime();
+    const created = new Date(prov.createdAt).getTime();
+    const modified = new Date(prov.modifiedAt).getTime();
+    if (!(created >= from && created <= to) && !(modified >= from && modified <= to)) return false;
+  }
+  return true;
+}
+
+// src/providers-builtin/InMemorySearchProvider.ts
+var InMemorySearchProvider = class {
+  indices = /* @__PURE__ */ new Map();
+  getIndex(repositoryId) {
+    if (!this.indices.has(repositoryId)) {
+      this.indices.set(repositoryId, /* @__PURE__ */ new Map());
+    }
+    return this.indices.get(repositoryId);
+  }
+  async indexEntity(repositoryId, entity) {
+    const index = this.getIndex(repositoryId);
+    const parts = [entity.label, entity.summary ?? ""];
+    if (entity.properties) {
+      for (const value of Object.values(entity.properties)) {
+        if (typeof value === "string") {
+          parts.push(value);
+        }
+      }
+    }
+    if (entity.data) {
+      parts.push(entity.data);
+    }
+    index.set(entity.entityId, {
+      entityId: entity.entityId,
+      entityType: entity.entityType,
+      text: parts.join(" ").toLowerCase()
+    });
+  }
+  async removeEntity(repositoryId, entityId) {
+    this.getIndex(repositoryId).delete(entityId);
+  }
+  async search(repositoryId, query, options) {
+    const index = this.getIndex(repositoryId);
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (terms.length === 0) {
+      return { items: [], total: 0, hasMore: false, limit: options?.limit ?? 10, offset: options?.offset ?? 0 };
+    }
+    let hits = [];
+    for (const entry of index.values()) {
+      if (options?.entityTypes && options.entityTypes.length > 0) {
+        if (!options.entityTypes.includes(entry.entityType)) continue;
+      }
+      let matchCount = 0;
+      for (const term of terms) {
+        if (entry.text.includes(term)) {
+          matchCount++;
+        }
+      }
+      if (matchCount > 0) {
+        hits.push({ entry, score: matchCount / terms.length });
+      }
+    }
+    hits.sort((a, b) => b.score - a.score);
+    const total = hits.length;
+    const limit = options?.limit ?? 10;
+    const offset = options?.offset ?? 0;
+    const page = hits.slice(offset, offset + limit);
+    return {
+      items: page.map((h) => ({
+        id: h.entry.entityId,
+        score: h.score
+      })),
+      total,
+      hasMore: offset + limit < total,
+      limit,
+      offset
+    };
+  }
+  async reindexRepository(repositoryId, entities) {
+    this.indices.set(repositoryId, /* @__PURE__ */ new Map());
+    for await (const entity of entities) {
+      await this.indexEntity(repositoryId, entity);
+    }
+  }
+};
+
+// src/providers-builtin/NoOpEmbeddingProvider.ts
+var NoOpEmbeddingProvider = class {
+  async embed(_text) {
+    throw new EmbeddingProviderRequiredError();
+  }
+  async embedBatch(_texts) {
+    throw new EmbeddingProviderRequiredError();
+  }
+  dimensions() {
+    return 0;
+  }
+  modelId() {
+    return "none";
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DeepMemory,
+  DeepMemoryError,
+  DuplicateEntityError,
+  DuplicateRelationshipError,
+  DuplicateRepositoryError,
+  EmbeddingProviderRequiredError,
+  EntityNotFoundError,
+  ExportError,
+  GovernanceDeniedError,
+  ImportError,
+  InMemorySearchProvider,
+  InMemoryStorageProvider,
+  InvalidInputError,
+  MemoryRepository,
+  NoOpEmbeddingProvider,
+  OperationCancelledError,
+  ProviderError,
+  RelationshipConstraintError,
+  RelationshipNotFoundError,
+  RepositoryNotFoundError,
+  VocabularyValidationError,
+  generateId,
+  isValidUuid,
+  matchesPropertyFilters
+});
+//# sourceMappingURL=index.cjs.map