@utaba/deep-memory-storage-sqlserver 0.1.0

package/dist/index.js

@@ -0,0 +1,1652 @@
+// src/SqlServerStorageProvider.ts
+import sql from "mssql";
+import {
+  RepositoryNotFoundError,
+  DuplicateRepositoryError,
+  EntityNotFoundError,
+  DuplicateEntityError,
+  RelationshipNotFoundError,
+  DuplicateRelationshipError,
+  ProviderError,
+  matchesPropertyFilters
+} from "@utaba/deep-memory";
+
+// src/schema.ts
+var SCHEMA_VERSION = 1;
+function getSchemaSQL(schema = "dbo") {
+  const s = schema;
+  return `
+-- ============================================================
+-- @utaba/deep-memory SQL Server schema v${SCHEMA_VERSION}
+-- ============================================================
+
+-- Schema version tracking
+IF NOT EXISTS (SELECT 1 FROM sys.tables WHERE name = 'dm_meta' AND schema_id = SCHEMA_ID('${s}'))
+BEGIN
+  CREATE TABLE [${s}].[dm_meta] (
+    [key]   NVARCHAR(100)  NOT NULL,
+    [value] NVARCHAR(MAX)  NOT NULL,
+    CONSTRAINT [pk_dm_meta] PRIMARY KEY ([key])
+  );
+  INSERT INTO [${s}].[dm_meta] ([key], [value])
+  VALUES ('schema_version', '${SCHEMA_VERSION}');
+END;
+
+-- Repositories
+IF NOT EXISTS (SELECT 1 FROM sys.tables WHERE name = 'dm_repositories' AND schema_id = SCHEMA_ID('${s}'))
+CREATE TABLE [${s}].[dm_repositories] (
+  [repository_id]     UNIQUEIDENTIFIER NOT NULL DEFAULT NEWID(),
+  [type]              NVARCHAR(128)   NULL,
+  [label]             NVARCHAR(500)   NOT NULL,
+  [description]       NVARCHAR(MAX)   NULL,
+  [legal]             NVARCHAR(MAX)   NULL,
+  [owner]             NVARCHAR(500)   NULL,
+  [governance_config] NVARCHAR(MAX)   NOT NULL,  -- JSON
+  [metadata]          NVARCHAR(MAX)   NULL,      -- JSON
+  [created_at]        NVARCHAR(50)    NOT NULL,  -- ISO 8601
+  [created_by]        NVARCHAR(255)   NOT NULL,
+  CONSTRAINT [pk_dm_repositories] PRIMARY KEY ([repository_id])
+);
+
+-- Vocabularies (one JSON document per repository)
+IF NOT EXISTS (SELECT 1 FROM sys.tables WHERE name = 'dm_vocabularies' AND schema_id = SCHEMA_ID('${s}'))
+CREATE TABLE [${s}].[dm_vocabularies] (
+  [repository_id]  UNIQUEIDENTIFIER  NOT NULL,
+  [vocabulary]     NVARCHAR(MAX)  NOT NULL,  -- JSON (MemoryVocabulary)
+  CONSTRAINT [pk_dm_vocabularies] PRIMARY KEY ([repository_id]),
+  CONSTRAINT [fk_dm_vocabularies_repositories]
+    FOREIGN KEY ([repository_id]) REFERENCES [${s}].[dm_repositories]([repository_id])
+    ON DELETE CASCADE
+);
+
+-- Vocabulary change log
+IF NOT EXISTS (SELECT 1 FROM sys.tables WHERE name = 'dm_vocabulary_change_log' AND schema_id = SCHEMA_ID('${s}'))
+CREATE TABLE [${s}].[dm_vocabulary_change_log] (
+  [change_id]         NVARCHAR(128)  NOT NULL,
+  [repository_id]     UNIQUEIDENTIFIER  NOT NULL,
+  [change_type]       NVARCHAR(50)   NOT NULL,
+  [type_name]         NVARCHAR(255)  NOT NULL,
+  [previous_version]  NVARCHAR(50)   NULL,
+  [new_version]       NVARCHAR(50)   NOT NULL,
+  [proposed_by]       NVARCHAR(255)  NOT NULL,
+  [proposed_at]       NVARCHAR(50)   NOT NULL,  -- ISO 8601
+  [approved_by]       NVARCHAR(255)  NULL,
+  [approved_at]       NVARCHAR(50)   NULL,      -- ISO 8601
+  [reason]            NVARCHAR(MAX)  NOT NULL,
+  CONSTRAINT [pk_dm_vocabulary_change_log] PRIMARY KEY ([repository_id], [change_id]),
+  CONSTRAINT [fk_dm_vocabulary_change_log_repositories]
+    FOREIGN KEY ([repository_id]) REFERENCES [${s}].[dm_repositories]([repository_id])
+    ON DELETE CASCADE
+);
+
+CREATE NONCLUSTERED INDEX [ix_dm_vocabulary_change_log_proposed_at]
+  ON [${s}].[dm_vocabulary_change_log] ([repository_id], [proposed_at] DESC);
+
+-- Entities
+IF NOT EXISTS (SELECT 1 FROM sys.tables WHERE name = 'dm_entities' AND schema_id = SCHEMA_ID('${s}'))
+CREATE TABLE [${s}].[dm_entities] (
+  [ft_key]                   INT             NOT NULL IDENTITY(1,1),  -- surrogate for FT index
+  [entity_id]                NVARCHAR(300)   NOT NULL,
+  [slug]                     NVARCHAR(300)   NOT NULL,
+  [repository_id]            UNIQUEIDENTIFIER NOT NULL,
+  [entity_type]              NVARCHAR(255)   NOT NULL,
+  [label]                    NVARCHAR(500)   NOT NULL,
+  [summary]                  NVARCHAR(MAX)   NULL,
+  [properties]               NVARCHAR(MAX)   NOT NULL,  -- JSON
+  [data]                     NVARCHAR(MAX)   NULL,
+  [data_format]              NVARCHAR(100)   NULL,
+  [embedding]                NVARCHAR(MAX)   NULL,       -- JSON array of numbers
+  -- Provenance
+  [created_by]               NVARCHAR(255)   NOT NULL,
+  [created_by_type]          NVARCHAR(10)    NOT NULL,   -- 'user' | 'agent'
+  [created_at]               NVARCHAR(50)    NOT NULL,   -- ISO 8601
+  [created_in_conversation]  NVARCHAR(255)   NULL,
+  [created_from_message]     NVARCHAR(255)   NULL,
+  [modified_by]              NVARCHAR(255)   NOT NULL,
+  [modified_by_type]         NVARCHAR(10)    NOT NULL,
+  [modified_at]              NVARCHAR(50)    NOT NULL,   -- ISO 8601
+  [modified_in_conversation] NVARCHAR(255)   NULL,
+  [modified_from_message]    NVARCHAR(255)   NULL,
+  CONSTRAINT [pk_dm_entities] PRIMARY KEY ([repository_id], [entity_id]),
+  CONSTRAINT [uq_dm_entities_ft_key] UNIQUE ([ft_key]),
+  CONSTRAINT [fk_dm_entities_repositories]
+    FOREIGN KEY ([repository_id]) REFERENCES [${s}].[dm_repositories]([repository_id])
+    ON DELETE CASCADE
+);
+
+CREATE NONCLUSTERED INDEX [ix_dm_entities_type]
+  ON [${s}].[dm_entities] ([repository_id], [entity_type]);
+CREATE NONCLUSTERED INDEX [ix_dm_entities_label]
+  ON [${s}].[dm_entities] ([repository_id], [label]);
+
+CREATE UNIQUE NONCLUSTERED INDEX [ix_dm_entities_slug]
+  ON [${s}].[dm_entities] ([repository_id], [slug]);
+
+-- Provenance indexes for conversation/actor/temporal queries
+CREATE NONCLUSTERED INDEX [ix_dm_entities_created_conversation]
+  ON [${s}].[dm_entities] ([repository_id], [created_in_conversation])
+  INCLUDE ([entity_id], [entity_type], [label], [summary]);
+
+CREATE NONCLUSTERED INDEX [ix_dm_entities_modified_conversation]
+  ON [${s}].[dm_entities] ([repository_id], [modified_in_conversation])
+  INCLUDE ([entity_id], [entity_type], [label], [summary]);
+
+CREATE NONCLUSTERED INDEX [ix_dm_entities_created_by]
+  ON [${s}].[dm_entities] ([repository_id], [created_by])
+  INCLUDE ([entity_id], [entity_type], [label], [summary]);
+
+CREATE NONCLUSTERED INDEX [ix_dm_entities_modified_at]
+  ON [${s}].[dm_entities] ([repository_id], [modified_at] DESC)
+  INCLUDE ([entity_id], [entity_type], [label], [summary]);
+
+-- Full-text catalog and index on entities
+IF NOT EXISTS (SELECT 1 FROM sys.fulltext_catalogs WHERE name = 'dm_fulltext_catalog')
+  CREATE FULLTEXT CATALOG [dm_fulltext_catalog] AS DEFAULT;
+
+IF NOT EXISTS (
+  SELECT 1 FROM sys.fulltext_indexes fi
+  JOIN sys.tables t ON fi.object_id = t.object_id
+  WHERE t.name = 'dm_entities' AND t.schema_id = SCHEMA_ID('${s}')
+)
+CREATE FULLTEXT INDEX ON [${s}].[dm_entities] (
+  [label]      LANGUAGE 1033,
+  [summary]    LANGUAGE 1033,
+  [data]       LANGUAGE 1033,
+  [properties] LANGUAGE 1033
+)
+KEY INDEX [uq_dm_entities_ft_key]
+ON [dm_fulltext_catalog]
+WITH CHANGE_TRACKING AUTO;
+
+-- Relationships
+IF NOT EXISTS (SELECT 1 FROM sys.tables WHERE name = 'dm_relationships' AND schema_id = SCHEMA_ID('${s}'))
+CREATE TABLE [${s}].[dm_relationships] (
+  [relationship_id]          NVARCHAR(300)   NOT NULL,
+  [repository_id]            UNIQUEIDENTIFIER NOT NULL,
+  [relationship_type]        NVARCHAR(255)   NOT NULL,
+  [source_entity_id]         NVARCHAR(300)   NOT NULL,
+  [target_entity_id]         NVARCHAR(300)   NOT NULL,
+  [properties]               NVARCHAR(MAX)   NOT NULL,  -- JSON
+  [bidirectional]            BIT             NOT NULL DEFAULT 0,
+  -- Provenance
+  [created_by]               NVARCHAR(255)   NOT NULL,
+  [created_by_type]          NVARCHAR(10)    NOT NULL,
+  [created_at]               NVARCHAR(50)    NOT NULL,
+  [created_in_conversation]  NVARCHAR(255)   NULL,
+  [created_from_message]     NVARCHAR(255)   NULL,
+  [modified_by]              NVARCHAR(255)   NOT NULL,
+  [modified_by_type]         NVARCHAR(10)    NOT NULL,
+  [modified_at]              NVARCHAR(50)    NOT NULL,
+  [modified_in_conversation] NVARCHAR(255)   NULL,
+  [modified_from_message]    NVARCHAR(255)   NULL,
+  CONSTRAINT [pk_dm_relationships] PRIMARY KEY ([repository_id], [relationship_id]),
+  CONSTRAINT [fk_dm_relationships_repositories]
+    FOREIGN KEY ([repository_id]) REFERENCES [${s}].[dm_repositories]([repository_id])
+    ON DELETE CASCADE,
+  CONSTRAINT [fk_dm_relationships_source]
+    FOREIGN KEY ([repository_id], [source_entity_id]) REFERENCES [${s}].[dm_entities]([repository_id], [entity_id]),
+  CONSTRAINT [fk_dm_relationships_target]
+    FOREIGN KEY ([repository_id], [target_entity_id]) REFERENCES [${s}].[dm_entities]([repository_id], [entity_id])
+);
+
+CREATE NONCLUSTERED INDEX [ix_dm_relationships_source]
+  ON [${s}].[dm_relationships] ([repository_id], [source_entity_id], [relationship_type])
+  INCLUDE ([target_entity_id], [bidirectional]);
+CREATE NONCLUSTERED INDEX [ix_dm_relationships_target]
+  ON [${s}].[dm_relationships] ([repository_id], [target_entity_id], [relationship_type])
+  INCLUDE ([source_entity_id], [bidirectional]);
+CREATE NONCLUSTERED INDEX [ix_dm_relationships_type]
+  ON [${s}].[dm_relationships] ([repository_id], [relationship_type]);
+
+-- Relationship provenance indexes
+CREATE NONCLUSTERED INDEX [ix_dm_relationships_created_conversation]
+  ON [${s}].[dm_relationships] ([repository_id], [created_in_conversation]);
+
+CREATE NONCLUSTERED INDEX [ix_dm_relationships_modified_at]
+  ON [${s}].[dm_relationships] ([repository_id], [modified_at] DESC);
+
+-- Table-valued parameter type for batch ID lookups (eliminates plan cache bloat)
+IF NOT EXISTS (SELECT 1 FROM sys.types WHERE name = 'dm_id_list' AND is_table_type = 1)
+  CREATE TYPE [${s}].[dm_id_list] AS TABLE ([id] NVARCHAR(300) NOT NULL);
+`.trim();
+}
+function getSearchProcSQL(schema = "dbo") {
+  const s = schema;
+  return `
+CREATE OR ALTER PROCEDURE [${s}].[dm_search_entities]
+  @RepositoryId   UNIQUEIDENTIFIER,
+  @Query          NVARCHAR(4000),
+  @EntityTypes    NVARCHAR(MAX) = NULL,   -- JSON array of strings, e.g. '["person","project"]'
+  @Limit          INT = 20,
+  @Offset         INT = 0,
+  @UseContains    BIT = 0                 -- 0 = FREETEXTTABLE (natural language), 1 = CONTAINSTABLE (exact/prefix)
+AS
+BEGIN
+  SET NOCOUNT ON;
+
+  -- Parse entity type filter from JSON array into a temp table
+  CREATE TABLE #entity_types ([type_name] NVARCHAR(255));
+  IF @EntityTypes IS NOT NULL AND @EntityTypes <> '[]'
+  BEGIN
+    INSERT INTO #entity_types ([type_name])
+    SELECT TRIM(value) FROM OPENJSON(@EntityTypes);
+  END;
+
+  DECLARE @HasTypeFilter BIT = CASE WHEN EXISTS (SELECT 1 FROM #entity_types) THEN 1 ELSE 0 END;
+
+  -- CTE: ranked full-text matches
+  ;WITH ft_results AS (
+    SELECT
+      e.[entity_id],
+      e.[slug],
+      e.[entity_type],
+      e.[label],
+      e.[summary],
+      e.[data],
+      e.[properties],
+      ft.[RANK] AS ft_rank
+    FROM (
+      SELECT [KEY], [RANK]
+      FROM FREETEXTTABLE([${s}].[dm_entities], ([label], [summary], [data], [properties]), @Query)
+      WHERE @UseContains = 0
+      UNION ALL
+      SELECT [KEY], [RANK]
+      FROM CONTAINSTABLE([${s}].[dm_entities], ([label], [summary], [data], [properties]), @Query)
+      WHERE @UseContains = 1
+    ) AS ft
+    INNER JOIN [${s}].[dm_entities] e ON e.[ft_key] = ft.[KEY]
+    WHERE e.[repository_id] = @RepositoryId
+      AND (@HasTypeFilter = 0 OR e.[entity_type] IN (SELECT [type_name] FROM #entity_types))
+  ),
+  -- Count total matching rows before pagination
+  ft_counted AS (
+    SELECT *, COUNT(*) OVER () AS total_count FROM ft_results
+  )
+  SELECT
+    [entity_id],
+    [slug],
+    [entity_type],
+    [label],
+    [summary],
+    [data],
+    [properties],
+    [ft_rank],
+    [total_count],
+    -- Highlight snippets: return the first 200 chars of each matched field
+    -- (the application layer will do finer-grained highlighting using the query terms)
+    CASE WHEN FREETEXT([label], @Query)      THEN LEFT([label], 200)   ELSE NULL END AS [hl_label],
+    CASE WHEN FREETEXT([summary], @Query)     THEN LEFT(CAST([summary] AS NVARCHAR(200)), 200) ELSE NULL END AS [hl_summary],
+    CASE WHEN FREETEXT([data], @Query)        THEN LEFT(CAST([data] AS NVARCHAR(200)), 200)    ELSE NULL END AS [hl_data],
+    CASE WHEN FREETEXT([properties], @Query)  THEN LEFT(CAST([properties] AS NVARCHAR(200)), 200) ELSE NULL END AS [hl_properties]
+  FROM ft_counted
+  ORDER BY [ft_rank] DESC
+  OFFSET @Offset ROWS FETCH NEXT @Limit ROWS ONLY;
+
+  DROP TABLE #entity_types;
+END;
+  `.trim();
+}
+
+// src/SqlServerStorageProvider.ts
+var ENTITY_COLS_LIGHT = [
+  "entity_id",
+  "slug",
+  "repository_id",
+  "entity_type",
+  "label",
+  "summary",
+  "properties",
+  "data",
+  "data_format",
+  "created_by",
+  "created_by_type",
+  "created_at",
+  "created_in_conversation",
+  "created_from_message",
+  "modified_by",
+  "modified_by_type",
+  "modified_at",
+  "modified_in_conversation",
+  "modified_from_message"
+].map((c) => `[${c}]`).join(", ");
+var ENTITY_COLS_FULL = `${ENTITY_COLS_LIGHT}, [embedding]`;
+function provenanceFromRow(row) {
+  const r = row;
+  return {
+    createdBy: r["created_by"],
+    createdByType: r["created_by_type"],
+    createdAt: r["created_at"],
+    createdInConversation: r["created_in_conversation"] || void 0,
+    createdFromMessage: r["created_from_message"] || void 0,
+    modifiedBy: r["modified_by"],
+    modifiedByType: r["modified_by_type"],
+    modifiedAt: r["modified_at"],
+    modifiedInConversation: r["modified_in_conversation"] || void 0,
+    modifiedFromMessage: r["modified_from_message"] || void 0
+  };
+}
+function addProvenanceConditions(req, prov, conditions, prefix) {
+  if (prov.conversationIds && prov.conversationIds.length > 0) {
+    const placeholders = prov.conversationIds.map((id, i) => {
+      req.input(`${prefix}ConvId${i}`, sql.NVarChar, id);
+      return `@${prefix}ConvId${i}`;
+    });
+    const inClause = placeholders.join(",");
+    conditions.push(`([created_in_conversation] IN (${inClause}) OR [modified_in_conversation] IN (${inClause}))`);
+  }
+  if (prov.actors && prov.actors.length > 0) {
+    const placeholders = prov.actors.map((a, i) => {
+      req.input(`${prefix}Actor${i}`, sql.NVarChar, a);
+      return `@${prefix}Actor${i}`;
+    });
+    const inClause = placeholders.join(",");
+    conditions.push(`([created_by] IN (${inClause}) OR [modified_by] IN (${inClause}))`);
+  }
+  if (prov.dateRange) {
+    req.input(`${prefix}DateFrom`, sql.NVarChar, prov.dateRange.from);
+    req.input(`${prefix}DateTo`, sql.NVarChar, prov.dateRange.to);
+    conditions.push(`([created_at] >= @${prefix}DateFrom AND [created_at] <= @${prefix}DateTo) OR ([modified_at] >= @${prefix}DateFrom AND [modified_at] <= @${prefix}DateTo)`);
+  }
+}
+function entityFromRow(row) {
+  const r = row;
+  return {
+    id: r["entity_id"],
+    slug: r["slug"],
+    entityType: r["entity_type"],
+    label: r["label"],
+    summary: r["summary"] || void 0,
+    properties: JSON.parse(r["properties"] || "{}"),
+    data: r["data"] || void 0,
+    dataFormat: r["data_format"] || void 0,
+    provenance: provenanceFromRow(row),
+    embedding: "embedding" in r && r["embedding"] ? JSON.parse(r["embedding"]) : void 0
+  };
+}
+function relationshipFromRow(row) {
+  const r = row;
+  return {
+    id: r["relationship_id"],
+    relationshipType: r["relationship_type"],
+    sourceEntityId: r["source_entity_id"],
+    targetEntityId: r["target_entity_id"],
+    properties: JSON.parse(r["properties"] || "{}"),
+    bidirectional: r["bidirectional"] === true || r["bidirectional"] === 1,
+    provenance: provenanceFromRow(row)
+  };
+}
+function changeRecordFromRow(row) {
+  const r = row;
+  return {
+    changeId: r["change_id"],
+    changeType: r["change_type"],
+    typeName: r["type_name"],
+    previousVersion: r["previous_version"] || void 0,
+    newVersion: r["new_version"],
+    proposedBy: r["proposed_by"],
+    proposedAt: r["proposed_at"],
+    approvedBy: r["approved_by"] || void 0,
+    approvedAt: r["approved_at"] || void 0,
+    reason: r["reason"]
+  };
+}
+var SqlServerStorageProvider = class {
+  pool = null;
+  ownsPool;
+  config;
+  schema;
+  constructor(config) {
+    this.config = config;
+    this.schema = config.schema ?? "dbo";
+    this.ownsPool = !(config.connection instanceof sql.ConnectionPool);
+  }
+  t(table) {
+    return `[${this.schema}].[${table}]`;
+  }
+  getPool() {
+    if (!this.pool) {
+      throw new ProviderError(
+        "SqlServerStorageProvider not initialised. Call initialise() first."
+      );
+    }
+    return this.pool;
+  }
+  // ─── Lifecycle ────────────────────────────────────────────────────
+  async initialise() {
+    if (this.config.connection instanceof sql.ConnectionPool) {
+      this.pool = this.config.connection;
+      this.ownsPool = false;
+      if (!this.pool.connected) {
+        await this.pool.connect();
+      }
+    } else {
+      this.pool = new sql.ConnectionPool(this.config.connection);
+      this.ownsPool = true;
+      await this.pool.connect();
+    }
+  }
+  async dispose() {
+    if (this.ownsPool && this.pool) {
+      await this.pool.close();
+    }
+    this.pool = null;
+  }
+  async ensureSchema() {
+    const pool = this.getPool();
+    const metaCheck = await pool.request().query(
+      `SELECT COUNT(*) AS cnt FROM sys.tables WHERE name = 'dm_meta' AND schema_id = SCHEMA_ID('${this.schema}')`
+    );
+    const metaExists = (metaCheck.recordset[0]?.cnt ?? 0) > 0;
+    if (metaExists) {
+      const versionResult = await pool.request().query(
+        `SELECT [value] FROM ${this.t("dm_meta")} WHERE [key] = 'schema_version'`
+      );
+      const currentVersion = parseInt(versionResult.recordset[0]?.value ?? "0", 10);
+      if (currentVersion > SCHEMA_VERSION) {
+        throw new ProviderError(
+          `Database schema version ${currentVersion} is newer than provider version ${SCHEMA_VERSION}. Update the provider package.`
+        );
+      }
+      if (currentVersion === SCHEMA_VERSION) {
+        return;
+      }
+    }
+    const ddl = getSchemaSQL(this.schema);
+    const statements = ddl.split(/\n\n+/).map((s) => s.split("\n").filter((line) => !line.trimStart().startsWith("--")).join("\n").trim()).filter((s) => s.length > 0);
+    for (const stmt of statements) {
+      try {
+        await pool.request().query(stmt);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (!msg.includes("already exists")) {
+          throw new ProviderError(`Schema creation failed: ${msg}`);
+        }
+      }
+    }
+  }
+  // ─── Repository ──────────────────────────────────────────────────
+  async createRepository(config) {
+    const pool = this.getPool();
+    const existing = await pool.request().input("id", sql.UniqueIdentifier, config.repositoryId).query(
+      `SELECT [repository_id] FROM ${this.t("dm_repositories")} WHERE [repository_id] = @id`
+    );
+    if (existing.recordset.length > 0) {
+      throw new DuplicateRepositoryError(config.repositoryId);
+    }
+    await pool.request().input("id", sql.UniqueIdentifier, config.repositoryId).input("type", sql.NVarChar, config.type ?? null).input("label", sql.NVarChar, config.label).input("description", sql.NVarChar, config.description ?? null).input("legal", sql.NVarChar, config.legal ?? null).input("owner", sql.NVarChar, config.owner ?? null).input("governanceConfig", sql.NVarChar, JSON.stringify(config.governanceConfig)).input("metadata", sql.NVarChar, config.metadata ? JSON.stringify(config.metadata) : null).input("createdAt", sql.NVarChar, config.createdAt).input("createdBy", sql.NVarChar, config.createdBy).query(`
+        INSERT INTO ${this.t("dm_repositories")}
+          ([repository_id], [type], [label], [description], [legal], [owner], [governance_config], [metadata], [created_at], [created_by])
+        VALUES (@id, @type, @label, @description, @legal, @owner, @governanceConfig, @metadata, @createdAt, @createdBy)
+      `);
+    const emptyVocabulary = {
+      version: "0.0.0",
+      lastModified: config.createdAt,
+      modifiedBy: config.createdBy,
+      entityTypes: [],
+      relationshipTypes: []
+    };
+    await pool.request().input("id", sql.UniqueIdentifier, config.repositoryId).input("vocabulary", sql.NVarChar, JSON.stringify(emptyVocabulary)).query(`
+        INSERT INTO ${this.t("dm_vocabularies")} ([repository_id], [vocabulary])
+        VALUES (@id, @vocabulary)
+      `);
+    return {
+      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
+    };
+  }
+  async getRepository(repositoryId) {
+    const pool = this.getPool();
+    const result = await pool.request().input("id", sql.UniqueIdentifier, repositoryId).query(
+      `SELECT * FROM ${this.t("dm_repositories")} WHERE [repository_id] = @id`
+    );
+    const row = result.recordset[0];
+    if (!row) return null;
+    const metadataRaw = row["metadata"];
+    return {
+      repositoryId: row["repository_id"],
+      type: row["type"] || void 0,
+      label: row["label"],
+      description: row["description"] || void 0,
+      legal: row["legal"] || void 0,
+      owner: row["owner"] || void 0,
+      governanceConfig: JSON.parse(row["governance_config"]),
+      metadata: metadataRaw ? JSON.parse(metadataRaw) : void 0,
+      createdAt: row["created_at"],
+      createdBy: row["created_by"]
+    };
+  }
+  async listRepositories(filter) {
+    const pool = this.getPool();
+    const offset = filter?.offset ?? 0;
+    const limit = filter?.limit ?? 20;
+    const countReq = pool.request();
+    const dataReq = pool.request();
+    let where = "";
+    if (filter?.type) {
+      countReq.input("type", sql.NVarChar, filter.type);
+      dataReq.input("type", sql.NVarChar, filter.type);
+      where = "WHERE [type] = @type";
+    }
+    const countResult = await countReq.query(
+      `SELECT COUNT(*) AS [cnt] FROM ${this.t("dm_repositories")} ${where}`
+    );
+    const total = countResult.recordset[0]?.["cnt"] ?? 0;
+    dataReq.input("offset", sql.Int, offset);
+    dataReq.input("limit", sql.Int, limit);
+    const result = await dataReq.query(
+      `SELECT [repository_id], [type], [label], [description], [governance_config]
+       FROM ${this.t("dm_repositories")} ${where}
+       ORDER BY [label]
+       OFFSET @offset ROWS FETCH NEXT @limit ROWS ONLY`
+    );
+    const items = result.recordset.map((row) => ({
+      repositoryId: row["repository_id"],
+      type: row["type"] || void 0,
+      label: row["label"],
+      description: row["description"] || void 0,
+      governanceConfig: JSON.parse(row["governance_config"])
+    }));
+    return {
+      items,
+      total,
+      hasMore: offset + items.length < total,
+      limit,
+      offset
+    };
+  }
+  async updateRepository(repositoryId, updates) {
+    const pool = this.getPool();
+    const setClauses = [];
+    const request = pool.request().input("id", sql.UniqueIdentifier, repositoryId);
+    if (updates.label !== void 0) {
+      setClauses.push("[label] = @label");
+      request.input("label", sql.NVarChar, updates.label);
+    }
+    if (updates.description !== void 0) {
+      setClauses.push("[description] = @description");
+      request.input("description", sql.NVarChar, updates.description);
+    }
+    if (updates.type !== void 0) {
+      setClauses.push("[type] = @type");
+      request.input("type", sql.NVarChar, updates.type);
+    }
+    if (updates.legal !== void 0) {
+      setClauses.push("[legal] = @legal");
+      request.input("legal", sql.NVarChar, updates.legal);
+    }
+    if (updates.owner !== void 0) {
+      setClauses.push("[owner] = @owner");
+      request.input("owner", sql.NVarChar, updates.owner);
+    }
+    if (updates.governanceConfig !== void 0) {
+      setClauses.push("[governance_config] = @governanceConfig");
+      request.input("governanceConfig", sql.NVarChar, JSON.stringify(updates.governanceConfig));
+    }
+    if (updates.metadata !== void 0) {
+      const existing = await this.getRepository(repositoryId);
+      if (!existing) throw new RepositoryNotFoundError(repositoryId);
+      const merged = { ...existing.metadata, ...updates.metadata };
+      setClauses.push("[metadata] = @metadata");
+      request.input("metadata", sql.NVarChar, JSON.stringify(merged));
+    }
+    if (setClauses.length === 0) {
+      const existing = await this.getRepository(repositoryId);
+      if (!existing) throw new RepositoryNotFoundError(repositoryId);
+      return existing;
+    }
+    const result = await request.query(
+      `UPDATE ${this.t("dm_repositories")} SET ${setClauses.join(", ")} WHERE [repository_id] = @id`
+    );
+    if (result.rowsAffected[0] === 0) {
+      throw new RepositoryNotFoundError(repositoryId);
+    }
+    const updated = await this.getRepository(repositoryId);
+    if (!updated) throw new RepositoryNotFoundError(repositoryId);
+    return updated;
+  }
+  async deleteRepository(repositoryId) {
+    const pool = this.getPool();
+    const result = await pool.request().input("id", sql.UniqueIdentifier, repositoryId).query(`DELETE FROM ${this.t("dm_repositories")} WHERE [repository_id] = @id`);
+    if (result.rowsAffected[0] === 0) {
+      throw new RepositoryNotFoundError(repositoryId);
+    }
+  }
+  async getRepositoryStats(repositoryId) {
+    await this.assertRepository(repositoryId);
+    const pool = this.getPool();
+    const [entityStats, relStats, vocab] = await Promise.all([
+      pool.request().input("id", sql.UniqueIdentifier, repositoryId).query(
+        `SELECT [entity_type], COUNT(*) AS cnt
+           FROM ${this.t("dm_entities")} WHERE [repository_id] = @id
+           GROUP BY [entity_type]`
+      ),
+      pool.request().input("id", sql.UniqueIdentifier, repositoryId).query(
+        `SELECT [relationship_type], COUNT(*) AS cnt
+           FROM ${this.t("dm_relationships")} WHERE [repository_id] = @id
+           GROUP BY [relationship_type]`
+      ),
+      this.getVocabulary(repositoryId)
+    ]);
+    const entityTypeBreakdown = {};
+    let entityCount = 0;
+    for (const row of entityStats.recordset) {
+      entityTypeBreakdown[row.entity_type] = row.cnt;
+      entityCount += row.cnt;
+    }
+    const relationshipTypeBreakdown = {};
+    let relationshipCount = 0;
+    for (const row of relStats.recordset) {
+      relationshipTypeBreakdown[row.relationship_type] = row.cnt;
+      relationshipCount += row.cnt;
+    }
+    return {
+      entityCount,
+      relationshipCount,
+      vocabularyVersion: vocab.version,
+      entityTypeBreakdown,
+      relationshipTypeBreakdown
+    };
+  }
+  // ─── Vocabulary ──────────────────────────────────────────────────
+  async getVocabulary(repositoryId) {
+    await this.assertRepository(repositoryId);
+    const pool = this.getPool();
+    const result = await pool.request().input("id", sql.UniqueIdentifier, repositoryId).query(
+      `SELECT [vocabulary] FROM ${this.t("dm_vocabularies")} WHERE [repository_id] = @id`
+    );
+    const row = result.recordset[0];
+    if (!row) {
+      return {
+        version: "0.0.0",
+        lastModified: (/* @__PURE__ */ new Date()).toISOString(),
+        modifiedBy: "system",
+        entityTypes: [],
+        relationshipTypes: []
+      };
+    }
+    return JSON.parse(row.vocabulary);
+  }
+  async saveVocabulary(repositoryId, vocabulary) {
+    await this.assertRepository(repositoryId);
+    const pool = this.getPool();
+    await pool.request().input("id", sql.UniqueIdentifier, repositoryId).input("vocabulary", sql.NVarChar, JSON.stringify(vocabulary)).query(`
+        UPDATE ${this.t("dm_vocabularies")}
+        SET [vocabulary] = @vocabulary
+        WHERE [repository_id] = @id
+      `);
+  }
+  async getVocabularyChangeLog(repositoryId, options) {
+    await this.assertRepository(repositoryId);
+    const pool = this.getPool();
+    const limit = options?.limit ?? 10;
+    const offset = options?.offset ?? 0;
+    const countResult = await pool.request().input("id", sql.UniqueIdentifier, repositoryId).query(
+      `SELECT COUNT(*) AS cnt FROM ${this.t("dm_vocabulary_change_log")} WHERE [repository_id] = @id`
+    );
+    const total = countResult.recordset[0]?.cnt ?? 0;
+    const result = await pool.request().input("id", sql.UniqueIdentifier, repositoryId).input("limit", sql.Int, limit).input("offset", sql.Int, offset).query(
+      `SELECT * FROM ${this.t("dm_vocabulary_change_log")}
+         WHERE [repository_id] = @id
+         ORDER BY [proposed_at] DESC
+         OFFSET @offset ROWS FETCH NEXT @limit ROWS ONLY`
+    );
+    return {
+      items: result.recordset.map(changeRecordFromRow),
+      total,
+      hasMore: offset + limit < total,
+      limit,
+      offset
+    };
+  }
+  // ─── Entities ────────────────────────────────────────────────────
+  async createEntity(repositoryId, entity) {
+    await this.assertRepository(repositoryId);
+    const pool = this.getPool();
+    const existing = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityId", sql.NVarChar, entity.id).query(
+      `SELECT [entity_id] FROM ${this.t("dm_entities")}
+         WHERE [repository_id] = @repoId AND [entity_id] = @entityId`
+    );
+    if (existing.recordset.length > 0) {
+      throw new DuplicateEntityError(entity.id);
+    }
+    const req = pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityId", sql.NVarChar, entity.id).input("slug", sql.NVarChar, entity.slug).input("entityType", sql.NVarChar, entity.entityType).input("label", sql.NVarChar, entity.label).input("summary", sql.NVarChar, entity.summary ?? null).input("properties", sql.NVarChar, JSON.stringify(entity.properties)).input("data", sql.NVarChar, entity.data ?? null).input("dataFormat", sql.NVarChar, entity.dataFormat ?? null).input("embedding", sql.NVarChar, entity.embedding ? JSON.stringify(entity.embedding) : null);
+    this.addProvenanceInputs(req, entity.provenance);
+    await req.query(`
+      INSERT INTO ${this.t("dm_entities")} (
+        [repository_id], [entity_id], [slug], [entity_type], [label], [summary],
+        [properties], [data], [data_format], [embedding],
+        [created_by], [created_by_type], [created_at],
+        [created_in_conversation], [created_from_message],
+        [modified_by], [modified_by_type], [modified_at],
+        [modified_in_conversation], [modified_from_message]
+      ) VALUES (
+        @repoId, @entityId, @slug, @entityType, @label, @summary,
+        @properties, @data, @dataFormat, @embedding,
+        @createdBy, @createdByType, @createdAt,
+        @createdInConversation, @createdFromMessage,
+        @modifiedBy, @modifiedByType, @modifiedAt,
+        @modifiedInConversation, @modifiedFromMessage
+      )
+    `);
+    return entity;
+  }
+  async getEntity(repositoryId, entityId) {
+    const pool = this.getPool();
+    const result = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityId", sql.NVarChar, entityId).query(
+      `SELECT ${ENTITY_COLS_LIGHT} FROM ${this.t("dm_entities")}
+         WHERE [repository_id] = @repoId AND [entity_id] = @entityId`
+    );
+    const row = result.recordset[0];
+    if (!row) return null;
+    return entityFromRow(row);
+  }
+  async getEntityBySlug(repositoryId, slug) {
+    const pool = this.getPool();
+    const result = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("slug", sql.NVarChar, slug).query(
+      `SELECT ${ENTITY_COLS_LIGHT} FROM ${this.t("dm_entities")}
+         WHERE [repository_id] = @repoId AND [slug] = @slug`
+    );
+    const row = result.recordset[0];
+    if (!row) return null;
+    return entityFromRow(row);
+  }
+  async getEntities(repositoryId, entityIds) {
+    const pool = this.getPool();
+    const result = /* @__PURE__ */ new Map();
+    if (entityIds.length === 0) return result;
+    const tvp = this.createIdListTvp(entityIds);
+    const rows = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityIds", tvp).query(
+      `SELECT ${ENTITY_COLS_LIGHT} FROM ${this.t("dm_entities")}
+         WHERE [repository_id] = @repoId
+         AND [entity_id] IN (SELECT [id] FROM @entityIds)`
+    );
+    for (const row of rows.recordset) {
+      const entity = entityFromRow(row);
+      result.set(entity.id, entity);
+    }
+    return result;
+  }
+  async updateEntity(repositoryId, entityId, updates) {
+    const pool = this.getPool();
+    const existing = await this.getEntity(repositoryId, entityId);
+    if (!existing) {
+      throw new EntityNotFoundError(entityId);
+    }
+    const updated = {
+      ...existing,
+      label: updates.label ?? existing.label,
+      slug: updates.slug ?? existing.slug,
+      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
+    };
+    const req = pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityId", sql.NVarChar, entityId).input("slug", sql.NVarChar, updated.slug).input("label", sql.NVarChar, updated.label).input("summary", sql.NVarChar, updated.summary ?? null).input("properties", sql.NVarChar, JSON.stringify(updated.properties)).input("data", sql.NVarChar, updated.data ?? null).input("dataFormat", sql.NVarChar, updated.dataFormat ?? null).input("embedding", sql.NVarChar, updated.embedding ? JSON.stringify(updated.embedding) : null).input("modifiedBy", sql.NVarChar, updates.provenance.modifiedBy).input("modifiedByType", sql.NVarChar, updates.provenance.modifiedByType).input("modifiedAt", sql.NVarChar, updates.provenance.modifiedAt).input("modifiedInConversation", sql.NVarChar, updates.provenance.modifiedInConversation ?? null).input("modifiedFromMessage", sql.NVarChar, updates.provenance.modifiedFromMessage ?? null);
+    await req.query(`
+      UPDATE ${this.t("dm_entities")} SET
+        [slug] = @slug,
+        [label] = @label,
+        [summary] = @summary,
+        [properties] = @properties,
+        [data] = @data,
+        [data_format] = @dataFormat,
+        [embedding] = @embedding,
+        [modified_by] = @modifiedBy,
+        [modified_by_type] = @modifiedByType,
+        [modified_at] = @modifiedAt,
+        [modified_in_conversation] = @modifiedInConversation,
+        [modified_from_message] = @modifiedFromMessage
+      WHERE [repository_id] = @repoId AND [entity_id] = @entityId
+    `);
+    return updated;
+  }
+  async deleteEntity(repositoryId, entityId) {
+    const pool = this.getPool();
+    const delReq = pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityId", sql.NVarChar, entityId);
+    await delReq.query(`
+      DELETE FROM ${this.t("dm_relationships")}
+        WHERE [repository_id] = @repoId AND [source_entity_id] = @entityId;
+      DELETE FROM ${this.t("dm_relationships")}
+        WHERE [repository_id] = @repoId AND [target_entity_id] = @entityId;
+    `);
+    const result = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityId", sql.NVarChar, entityId).query(
+      `DELETE FROM ${this.t("dm_entities")}
+         WHERE [repository_id] = @repoId AND [entity_id] = @entityId`
+    );
+    if (result.rowsAffected[0] === 0) {
+      throw new EntityNotFoundError(entityId);
+    }
+  }
+  async deleteEntitiesByType(repositoryId, entityType) {
+    await this.assertRepository(repositoryId);
+    const pool = this.getPool();
+    const srcResult = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityType", sql.NVarChar, entityType).query(`
+        DELETE r FROM ${this.t("dm_relationships")} r
+        INNER JOIN ${this.t("dm_entities")} e
+          ON r.[repository_id] = e.[repository_id]
+          AND r.[source_entity_id] = e.[entity_id]
+        WHERE e.[repository_id] = @repoId AND e.[entity_type] = @entityType
+      `);
+    const tgtResult = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityType", sql.NVarChar, entityType).query(`
+        DELETE r FROM ${this.t("dm_relationships")} r
+        INNER JOIN ${this.t("dm_entities")} e
+          ON r.[repository_id] = e.[repository_id]
+          AND r.[target_entity_id] = e.[entity_id]
+        WHERE e.[repository_id] = @repoId AND e.[entity_type] = @entityType
+      `);
+    const deletedRelationships = (srcResult.rowsAffected[0] ?? 0) + (tgtResult.rowsAffected[0] ?? 0);
+    const entResult = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityType", sql.NVarChar, entityType).query(
+      `DELETE FROM ${this.t("dm_entities")}
+         WHERE [repository_id] = @repoId AND [entity_type] = @entityType`
+    );
+    const deletedEntities = entResult.rowsAffected[0] ?? 0;
+    return { deletedEntities, deletedRelationships };
+  }
+  async findEntities(repositoryId, query) {
+    const pool = this.getPool();
+    const req = pool.request().input("repoId", sql.UniqueIdentifier, repositoryId);
+    const conditions = ["[repository_id] = @repoId"];
+    if (query.entityTypes && query.entityTypes.length > 0) {
+      const typePlaceholders = query.entityTypes.map((t, i) => {
+        req.input(`et${i}`, sql.NVarChar, t);
+        return `@et${i}`;
+      });
+      conditions.push(`[entity_type] IN (${typePlaceholders.join(",")})`);
+    }
+    if (query.searchTerm) {
+      req.input("searchTerm", sql.NVarChar, `%${query.searchTerm}%`);
+      conditions.push(`([label] LIKE @searchTerm OR [summary] LIKE @searchTerm)`);
+    }
+    if (query.properties) {
+      const entries = Object.entries(query.properties);
+      for (let i = 0; i < entries.length; i++) {
+        const [key, value] = entries[i];
+        req.input(`propKey${i}`, sql.NVarChar, `$.${key}`);
+        req.input(`propVal${i}`, sql.NVarChar, String(value));
+        conditions.push(`JSON_VALUE([properties], @propKey${i}) = @propVal${i}`);
+      }
+    }
+    if (query.provenance) {
+      addProvenanceConditions(req, query.provenance, conditions, "data");
+    }
+    const where = conditions.join(" AND ");
+    const countReq = pool.request().input("repoId", sql.UniqueIdentifier, repositoryId);
+    const countConditions = ["[repository_id] = @repoId"];
+    if (query.entityTypes && query.entityTypes.length > 0) {
+      const typePlaceholders = query.entityTypes.map((t, i) => {
+        countReq.input(`et${i}`, sql.NVarChar, t);
+        return `@et${i}`;
+      });
+      countConditions.push(`[entity_type] IN (${typePlaceholders.join(",")})`);
+    }
+    if (query.searchTerm) {
+      countReq.input("searchTerm", sql.NVarChar, `%${query.searchTerm}%`);
+      countConditions.push(`([label] LIKE @searchTerm OR [summary] LIKE @searchTerm)`);
+    }
+    if (query.properties) {
+      const entries = Object.entries(query.properties);
+      for (let i = 0; i < entries.length; i++) {
+        const [key, value] = entries[i];
+        countReq.input(`propKey${i}`, sql.NVarChar, `$.${key}`);
+        countReq.input(`propVal${i}`, sql.NVarChar, String(value));
+        countConditions.push(`JSON_VALUE([properties], @propKey${i}) = @propVal${i}`);
+      }
+    }
+    if (query.provenance) {
+      addProvenanceConditions(countReq, query.provenance, countConditions, "count");
+    }
+    const countWhere = countConditions.join(" AND ");
+    const totalResult = await countReq.query(
+      `SELECT COUNT(*) AS cnt FROM ${this.t("dm_entities")} WHERE ${countWhere}`
+    );
+    const total = totalResult.recordset[0]?.cnt ?? 0;
+    req.input("limit", sql.Int, query.limit);
+    req.input("offset", sql.Int, query.offset);
+    const result = await req.query(
+      `SELECT ${ENTITY_COLS_LIGHT} FROM ${this.t("dm_entities")}
+       WHERE ${where}
+       ORDER BY [entity_id]
+       OFFSET @offset ROWS FETCH NEXT @limit ROWS ONLY`
+    );
+    return {
+      items: result.recordset.map(entityFromRow),
+      total,
+      hasMore: query.offset + query.limit < total,
+      limit: query.limit,
+      offset: query.offset
+    };
+  }
+  // ─── Relationships ──────────────────────────────────────────────
+  async createRelationship(repositoryId, relationship) {
+    await this.assertRepository(repositoryId);
+    const pool = this.getPool();
+    const existing = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("relId", sql.NVarChar, relationship.id).query(
+      `SELECT [relationship_id] FROM ${this.t("dm_relationships")}
+         WHERE [repository_id] = @repoId AND [relationship_id] = @relId`
+    );
+    if (existing.recordset.length > 0) {
+      throw new DuplicateRelationshipError(relationship.id);
+    }
+    const req = pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("relId", sql.NVarChar, relationship.id).input("relType", sql.NVarChar, relationship.relationshipType).input("sourceId", sql.NVarChar, relationship.sourceEntityId).input("targetId", sql.NVarChar, relationship.targetEntityId).input("properties", sql.NVarChar, JSON.stringify(relationship.properties)).input("bidirectional", sql.Bit, relationship.bidirectional ? 1 : 0);
+    this.addProvenanceInputs(req, relationship.provenance);
+    await req.query(`
+      INSERT INTO ${this.t("dm_relationships")} (
+        [repository_id], [relationship_id], [relationship_type],
+        [source_entity_id], [target_entity_id], [properties], [bidirectional],
+        [created_by], [created_by_type], [created_at],
+        [created_in_conversation], [created_from_message],
+        [modified_by], [modified_by_type], [modified_at],
+        [modified_in_conversation], [modified_from_message]
+      ) VALUES (
+        @repoId, @relId, @relType,
+        @sourceId, @targetId, @properties, @bidirectional,
+        @createdBy, @createdByType, @createdAt,
+        @createdInConversation, @createdFromMessage,
+        @modifiedBy, @modifiedByType, @modifiedAt,
+        @modifiedInConversation, @modifiedFromMessage
+      )
+    `);
+    return relationship;
+  }
+  async getRelationship(repositoryId, relationshipId) {
+    const pool = this.getPool();
+    const result = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("relId", sql.NVarChar, relationshipId).query(
+      `SELECT * FROM ${this.t("dm_relationships")}
+         WHERE [repository_id] = @repoId AND [relationship_id] = @relId`
+    );
+    const row = result.recordset[0];
+    if (!row) return null;
+    return relationshipFromRow(row);
+  }
+  async getEntityRelationships(repositoryId, entityId, options) {
+    const pool = this.getPool();
+    const direction = options?.direction ?? "both";
+    const limit = options?.limit ?? 10;
+    const offset = options?.offset ?? 0;
+    const tbl = this.t("dm_relationships");
+    let rtFilter = "";
+    const rtInputs = [];
+    if (options?.relationshipTypes && options.relationshipTypes.length > 0) {
+      const placeholders = options.relationshipTypes.map((t, i) => {
+        rtInputs.push({ name: `rt${i}`, value: t });
+        return `@rt${i}`;
+      });
+      rtFilter = ` AND [relationship_type] IN (${placeholders.join(",")})`;
+    }
+    const unionBranches = this.buildRelationshipUnion(tbl, direction, rtFilter);
+    const addParams = (req) => {
+      req.input("repoId", sql.UniqueIdentifier, repositoryId);
+      req.input("entityId", sql.NVarChar, entityId);
+      for (const p of rtInputs) req.input(p.name, sql.NVarChar, p.value);
+      return req;
+    };
+    const countReq = addParams(pool.request());
+    const totalResult = await countReq.query(
+      `SELECT COUNT(*) AS cnt FROM (${unionBranches}) AS _u`
+    );
+    const total = totalResult.recordset[0]?.cnt ?? 0;
+    const fetchReq = addParams(pool.request());
+    fetchReq.input("limit", sql.Int, limit);
+    fetchReq.input("offset", sql.Int, offset);
+    const result = await fetchReq.query(
+      `SELECT * FROM (${unionBranches}) AS _u
+       ORDER BY [relationship_id]
+       OFFSET @offset ROWS FETCH NEXT @limit ROWS ONLY`
+    );
+    let items = result.recordset.map(relationshipFromRow);
+    if (options?.propertyFilters && options.propertyFilters.length > 0) {
+      items = items.filter((r) => matchesPropertyFilters(r.properties, options.propertyFilters));
+      const filteredTotal = total;
+      return {
+        items,
+        total: filteredTotal,
+        hasMore: offset + limit < filteredTotal,
+        limit,
+        offset
+      };
+    }
+    return {
+      items,
+      total,
+      hasMore: offset + limit < total,
+      limit,
+      offset
+    };
+  }
+  /**
+   * Build a UNION ALL query that seeks on source and target indexes separately,
+   * avoiding OR-based index scans. Each branch produces an index seek at scale.
+   */
+  buildRelationshipUnion(tbl, direction, rtFilter) {
+    const srcBase = `SELECT * FROM ${tbl} WHERE [repository_id] = @repoId AND [source_entity_id] = @entityId${rtFilter}`;
+    const tgtBase = `SELECT * FROM ${tbl} WHERE [repository_id] = @repoId AND [target_entity_id] = @entityId${rtFilter}`;
+    const tgtBidi = `SELECT * FROM ${tbl} WHERE [repository_id] = @repoId AND [target_entity_id] = @entityId AND [bidirectional] = 1${rtFilter}`;
+    const srcBidi = `SELECT * FROM ${tbl} WHERE [repository_id] = @repoId AND [source_entity_id] = @entityId AND [bidirectional] = 1${rtFilter}`;
+    switch (direction) {
+      case "outbound":
+        return `${srcBase} UNION ALL ${tgtBidi} AND [source_entity_id] <> @entityId`;
+      case "inbound":
+        return `${tgtBase} UNION ALL ${srcBidi} AND [target_entity_id] <> @entityId`;
+      case "both":
+      default:
+        return `${srcBase} UNION ALL ${tgtBase} AND [source_entity_id] <> @entityId`;
+    }
+  }
+  async deleteRelationship(repositoryId, relationshipId) {
+    const pool = this.getPool();
+    const result = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("relId", sql.NVarChar, relationshipId).query(
+      `DELETE FROM ${this.t("dm_relationships")}
+         WHERE [repository_id] = @repoId AND [relationship_id] = @relId`
+    );
+    if (result.rowsAffected[0] === 0) {
+      throw new RelationshipNotFoundError(relationshipId);
+    }
+  }
+  async deleteRelationshipsByType(repositoryId, relationshipType) {
+    await this.assertRepository(repositoryId);
+    const pool = this.getPool();
+    const result = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("relType", sql.NVarChar, relationshipType).query(
+      `DELETE FROM ${this.t("dm_relationships")}
+         WHERE [repository_id] = @repoId AND [relationship_type] = @relType`
+    );
+    return { deletedRelationships: result.rowsAffected[0] ?? 0 };
+  }
+  // ─── Graph Traversal ────────────────────────────────────────────
+  async exploreNeighbourhood(repositoryId, entityId, options) {
+    const centre = await this.getEntityLight(repositoryId, entityId);
+    if (!centre) {
+      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();
+      const frontierIds = [...currentFrontier];
+      const relsByEntity = await this.getRelationshipsForEntities(
+        repositoryId,
+        frontierIds,
+        options.direction,
+        options.relationshipTypes
+      );
+      const connectedIdsToFetch = /* @__PURE__ */ new Set();
+      const pendingRels = [];
+      for (const frontierEntityId of frontierIds) {
+        const rels = relsByEntity.get(frontierEntityId) ?? [];
+        for (const rel of rels) {
+          let connectedEntityId;
+          if (rel.sourceEntityId === frontierEntityId) {
+            connectedEntityId = rel.targetEntityId;
+          } else if (rel.targetEntityId === frontierEntityId) {
+            connectedEntityId = rel.sourceEntityId;
+          }
+          if (!connectedEntityId || visited.has(connectedEntityId)) continue;
+          if (options.relationshipPropertyFilters && options.relationshipPropertyFilters.length > 0) {
+            if (!matchesPropertyFilters(rel.properties, options.relationshipPropertyFilters)) {
+              continue;
+            }
+          }
+          connectedIdsToFetch.add(connectedEntityId);
+          pendingRels.push({ frontierEntityId, rel, connectedEntityId });
+        }
+      }
+      const connectedEntities = await this.getEntitiesLight(repositoryId, [...connectedIdsToFetch]);
+      for (const { rel, connectedEntityId } of pendingRels) {
+        if (visited.has(connectedEntityId)) continue;
+        const connectedEntity = connectedEntities.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: [] };
+        }
+        const group = layer[relType];
+        group.total++;
+        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 [source, target] = await Promise.all([
+      this.getEntityLight(repositoryId, sourceId),
+      this.getEntityLight(repositoryId, targetId)
+    ]);
+    if (!source) throw new EntityNotFoundError(sourceId);
+    if (!target) throw new EntityNotFoundError(targetId);
+    if (sourceId === targetId) {
+      return { paths: [{ entityIds: [sourceId], relationshipIds: [] }], totalPaths: 1 };
+    }
+    const paths = [];
+    let currentLevel = [
+      { entityId: sourceId, path: [sourceId], relPath: [] }
+    ];
+    const visitedAtDepth = /* @__PURE__ */ new Map();
+    visitedAtDepth.set(sourceId, 0);
+    for (let depth = 0; depth <= options.maxDepth && currentLevel.length > 0 && paths.length < options.limit + options.offset; depth++) {
+      const frontierIds = [...new Set(currentLevel.map((e) => e.entityId))];
+      const relsByEntity = await this.getRelationshipsForEntities(
+        repositoryId,
+        frontierIds,
+        "both",
+        options.relationshipTypes
+      );
+      const nextLevel = [];
+      for (const current of currentLevel) {
+        if (paths.length >= options.limit + options.offset) break;
+        const rels = relsByEntity.get(current.entityId) ?? [];
+        for (const rel of rels) {
+          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;
+          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);
+              nextLevel.push({ entityId: nextEntityId, path: newPath, relPath: newRelPath });
+            }
+          }
+        }
+      }
+      if (options.entityTypes && nextLevel.length > 0) {
+        const nextIds = [...new Set(nextLevel.map((e) => e.entityId))];
+        const entityMap = await this.getEntitiesLight(repositoryId, nextIds);
+        const allowedIds = /* @__PURE__ */ new Set();
+        for (const [id, e] of entityMap) {
+          if (options.entityTypes.includes(e.entityType)) {
+            allowedIds.add(id);
+          }
+        }
+        currentLevel = nextLevel.filter((e) => allowedIds.has(e.entityId));
+      } else {
+        currentLevel = nextLevel;
+      }
+    }
+    const paginatedPaths = paths.slice(options.offset, options.offset + options.limit);
+    return { paths: paginatedPaths, totalPaths: paths.length };
+  }
+  // ─── Timeline ───────────────────────────────────────────────────
+  async getTimeline(repositoryId, entityId, options) {
+    const entity = await this.getEntityLight(repositoryId, 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
+      });
+    }
+    const pool = this.getPool();
+    const relReq = pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityId", sql.NVarChar, entityId).input("from", sql.NVarChar, options.timeRange?.from ?? null).input("to", sql.NVarChar, options.timeRange?.to ?? null);
+    const relResult = await relReq.query(
+      `SELECT [relationship_id], [created_at] FROM ${this.t("dm_relationships")}
+         WHERE [repository_id] = @repoId AND [source_entity_id] = @entityId
+           AND (@from IS NULL OR [created_at] >= @from)
+           AND (@to IS NULL OR [created_at] <= @to)
+       UNION ALL
+       SELECT [relationship_id], [created_at] FROM ${this.t("dm_relationships")}
+         WHERE [repository_id] = @repoId AND [target_entity_id] = @entityId
+           AND [source_entity_id] <> @entityId
+           AND (@from IS NULL OR [created_at] >= @from)
+           AND (@to IS NULL OR [created_at] <= @to)`
+    );
+    for (const row of relResult.recordset) {
+      events.push({
+        timestamp: row["created_at"],
+        eventType: "relationship:created",
+        entityId,
+        relationshipId: row["relationship_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));
+    }
+    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) {
+    await this.assertRepository(repositoryId);
+    const pool = this.getPool();
+    const batchSize = 100;
+    const entityCount = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).query(
+      `SELECT COUNT(*) AS cnt FROM ${this.t("dm_entities")} WHERE [repository_id] = @repoId`
+    );
+    const totalEntities = entityCount.recordset[0]?.cnt ?? 0;
+    if (totalEntities === 0) {
+      yield { type: "entities", data: [], sequence: 0, isLast: true };
+    } else {
+      for (let offset = 0; offset < totalEntities; offset += batchSize) {
+        const batch = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("offset", sql.Int, offset).input("limit", sql.Int, batchSize).query(
+          `SELECT ${ENTITY_COLS_FULL} FROM ${this.t("dm_entities")}
+             WHERE [repository_id] = @repoId
+             ORDER BY [entity_id]
+             OFFSET @offset ROWS FETCH NEXT @limit ROWS ONLY`
+        );
+        yield {
+          type: "entities",
+          data: batch.recordset.map(entityFromRow),
+          sequence: Math.floor(offset / batchSize),
+          isLast: offset + batchSize >= totalEntities
+        };
+      }
+    }
+    const relCount = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).query(
+      `SELECT COUNT(*) AS cnt FROM ${this.t("dm_relationships")} WHERE [repository_id] = @repoId`
+    );
+    const totalRels = relCount.recordset[0]?.cnt ?? 0;
+    if (totalRels === 0) {
+      yield { type: "relationships", data: [], sequence: 0, isLast: true };
+    } else {
+      for (let offset = 0; offset < totalRels; offset += batchSize) {
+        const batch = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("offset", sql.Int, offset).input("limit", sql.Int, batchSize).query(
+          `SELECT * FROM ${this.t("dm_relationships")}
+             WHERE [repository_id] = @repoId
+             ORDER BY [relationship_id]
+             OFFSET @offset ROWS FETCH NEXT @limit ROWS ONLY`
+        );
+        yield {
+          type: "relationships",
+          data: batch.recordset.map(relationshipFromRow),
+          sequence: Math.floor(offset / batchSize),
+          isLast: offset + batchSize >= totalRels
+        };
+      }
+    }
+  }
+  async importBulk(repositoryId, data) {
+    await this.assertRepository(repositoryId);
+    const pool = this.getPool();
+    let entitiesImported = 0;
+    let relationshipsImported = 0;
+    const transaction = pool.transaction();
+    await transaction.begin();
+    try {
+      for (const chunk of data) {
+        if (chunk.entities) {
+          for (const entity of chunk.entities) {
+            const req = transaction.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityId", sql.NVarChar, entity.id).input("slug", sql.NVarChar, entity.slug).input("entityType", sql.NVarChar, entity.entityType).input("label", sql.NVarChar, entity.label).input("summary", sql.NVarChar, entity.summary ?? null).input("properties", sql.NVarChar, JSON.stringify(entity.properties)).input("data", sql.NVarChar, entity.data ?? null).input("dataFormat", sql.NVarChar, entity.dataFormat ?? null).input("embedding", sql.NVarChar, entity.embedding ? JSON.stringify(entity.embedding) : null);
+            this.addProvenanceInputs(req, entity.provenance);
+            await req.query(`
+              MERGE ${this.t("dm_entities")} AS target
+              USING (SELECT @repoId AS repository_id, @entityId AS entity_id) AS source
+              ON target.[repository_id] = source.repository_id AND target.[entity_id] = source.entity_id
+              WHEN MATCHED THEN UPDATE SET
+                [entity_type] = @entityType, [slug] = @slug, [label] = @label, [summary] = @summary,
+                [properties] = @properties, [data] = @data, [data_format] = @dataFormat,
+                [embedding] = @embedding,
+                [modified_by] = @modifiedBy, [modified_by_type] = @modifiedByType,
+                [modified_at] = @modifiedAt, [modified_in_conversation] = @modifiedInConversation,
+                [modified_from_message] = @modifiedFromMessage
+              WHEN NOT MATCHED THEN INSERT (
+                [repository_id], [entity_id], [slug], [entity_type], [label], [summary],
+                [properties], [data], [data_format], [embedding],
+                [created_by], [created_by_type], [created_at],
+                [created_in_conversation], [created_from_message],
+                [modified_by], [modified_by_type], [modified_at],
+                [modified_in_conversation], [modified_from_message]
+              ) VALUES (
+                @repoId, @entityId, @slug, @entityType, @label, @summary,
+                @properties, @data, @dataFormat, @embedding,
+                @createdBy, @createdByType, @createdAt,
+                @createdInConversation, @createdFromMessage,
+                @modifiedBy, @modifiedByType, @modifiedAt,
+                @modifiedInConversation, @modifiedFromMessage
+              );
+            `);
+            entitiesImported++;
+          }
+        }
+        if (chunk.relationships) {
+          for (const rel of chunk.relationships) {
+            const req = transaction.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("relId", sql.NVarChar, rel.id).input("relType", sql.NVarChar, rel.relationshipType).input("sourceId", sql.NVarChar, rel.sourceEntityId).input("targetId", sql.NVarChar, rel.targetEntityId).input("properties", sql.NVarChar, JSON.stringify(rel.properties)).input("bidirectional", sql.Bit, rel.bidirectional ? 1 : 0);
+            this.addProvenanceInputs(req, rel.provenance);
+            await req.query(`
+              MERGE ${this.t("dm_relationships")} AS target
+              USING (SELECT @repoId AS repository_id, @relId AS relationship_id) AS source
+              ON target.[repository_id] = source.repository_id AND target.[relationship_id] = source.relationship_id
+              WHEN MATCHED THEN UPDATE SET
+                [relationship_type] = @relType, [source_entity_id] = @sourceId,
+                [target_entity_id] = @targetId, [properties] = @properties,
+                [bidirectional] = @bidirectional,
+                [modified_by] = @modifiedBy, [modified_by_type] = @modifiedByType,
+                [modified_at] = @modifiedAt, [modified_in_conversation] = @modifiedInConversation,
+                [modified_from_message] = @modifiedFromMessage
+              WHEN NOT MATCHED THEN INSERT (
+                [repository_id], [relationship_id], [relationship_type],
+                [source_entity_id], [target_entity_id], [properties], [bidirectional],
+                [created_by], [created_by_type], [created_at],
+                [created_in_conversation], [created_from_message],
+                [modified_by], [modified_by_type], [modified_at],
+                [modified_in_conversation], [modified_from_message]
+              ) VALUES (
+                @repoId, @relId, @relType,
+                @sourceId, @targetId, @properties, @bidirectional,
+                @createdBy, @createdByType, @createdAt,
+                @createdInConversation, @createdFromMessage,
+                @modifiedBy, @modifiedByType, @modifiedAt,
+                @modifiedInConversation, @modifiedFromMessage
+              );
+            `);
+            relationshipsImported++;
+          }
+        }
+      }
+      await transaction.commit();
+    } catch (err) {
+      await transaction.rollback();
+      throw err;
+    }
+    return { entitiesImported, relationshipsImported, errors: [] };
+  }
+  // ─── Private helpers ────────────────────────────────────────────
+  /** Creates a TVP table from an array of string IDs (eliminates plan cache bloat from IN clauses). */
+  createIdListTvp(ids) {
+    const tvp = new sql.Table(`${this.schema}.dm_id_list`);
+    tvp.columns.add("id", sql.NVarChar(300));
+    for (const id of ids) tvp.rows.add(id);
+    return tvp;
+  }
+  /** Returns a StoredEntity without the embedding column (lighter I/O). */
+  async getEntityLight(repositoryId, entityId) {
+    const pool = this.getPool();
+    const result = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityId", sql.NVarChar, entityId).query(
+      `SELECT ${ENTITY_COLS_LIGHT} FROM ${this.t("dm_entities")}
+         WHERE [repository_id] = @repoId AND [entity_id] = @entityId`
+    );
+    const row = result.recordset[0];
+    if (!row) return null;
+    return entityFromRow(row);
+  }
+  /** Returns multiple entities without embedding columns, using TVP for batch lookup. */
+  async getEntitiesLight(repositoryId, entityIds) {
+    const pool = this.getPool();
+    const result = /* @__PURE__ */ new Map();
+    if (entityIds.length === 0) return result;
+    const tvp = this.createIdListTvp(entityIds);
+    const rows = await pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityIds", tvp).query(
+      `SELECT ${ENTITY_COLS_LIGHT} FROM ${this.t("dm_entities")}
+         WHERE [repository_id] = @repoId
+         AND [entity_id] IN (SELECT [id] FROM @entityIds)`
+    );
+    for (const row of rows.recordset) {
+      const entity = entityFromRow(row);
+      result.set(entity.id, entity);
+    }
+    return result;
+  }
+  /**
+   * Fetches relationships for multiple entity IDs in a single query using TVP.
+   * Returns results grouped by the frontier entity ID.
+   */
+  async getRelationshipsForEntities(repositoryId, entityIds, direction, relationshipTypes) {
+    const pool = this.getPool();
+    const result = /* @__PURE__ */ new Map();
+    if (entityIds.length === 0) return result;
+    const tbl = this.t("dm_relationships");
+    const tvp = this.createIdListTvp(entityIds);
+    let rtFilter = "";
+    const rtInputs = [];
+    if (relationshipTypes && relationshipTypes.length > 0) {
+      const placeholders = relationshipTypes.map((t, i) => {
+        rtInputs.push({ name: `rt${i}`, value: t });
+        return `@rt${i}`;
+      });
+      rtFilter = ` AND [relationship_type] IN (${placeholders.join(",")})`;
+    }
+    const srcBase = `SELECT * FROM ${tbl} WHERE [repository_id] = @repoId AND [source_entity_id] IN (SELECT [id] FROM @entityIds)${rtFilter}`;
+    const tgtBase = `SELECT * FROM ${tbl} WHERE [repository_id] = @repoId AND [target_entity_id] IN (SELECT [id] FROM @entityIds)${rtFilter}`;
+    const tgtBidi = `SELECT * FROM ${tbl} WHERE [repository_id] = @repoId AND [target_entity_id] IN (SELECT [id] FROM @entityIds) AND [bidirectional] = 1${rtFilter}`;
+    const srcBidi = `SELECT * FROM ${tbl} WHERE [repository_id] = @repoId AND [source_entity_id] IN (SELECT [id] FROM @entityIds) AND [bidirectional] = 1${rtFilter}`;
+    let unionQuery;
+    switch (direction) {
+      case "outbound":
+        unionQuery = `${srcBase} UNION ALL ${tgtBidi}`;
+        break;
+      case "inbound":
+        unionQuery = `${tgtBase} UNION ALL ${srcBidi}`;
+        break;
+      case "both":
+      default:
+        unionQuery = `${srcBase} UNION ALL ${tgtBase}`;
+        break;
+    }
+    const req = pool.request().input("repoId", sql.UniqueIdentifier, repositoryId).input("entityIds", tvp);
+    for (const p of rtInputs) req.input(p.name, sql.NVarChar, p.value);
+    const rows = await req.query(unionQuery);
+    const entityIdSet = new Set(entityIds);
+    for (const row of rows.recordset) {
+      const rel = relationshipFromRow(row);
+      const frontierIds = [];
+      if (entityIdSet.has(rel.sourceEntityId)) frontierIds.push(rel.sourceEntityId);
+      if (entityIdSet.has(rel.targetEntityId)) frontierIds.push(rel.targetEntityId);
+      for (const fid of frontierIds) {
+        let list = result.get(fid);
+        if (!list) {
+          list = [];
+          result.set(fid, list);
+        }
+        list.push(rel);
+      }
+    }
+    return result;
+  }
+  async assertRepository(repositoryId) {
+    const repo = await this.getRepository(repositoryId);
+    if (!repo) {
+      throw new RepositoryNotFoundError(repositoryId);
+    }
+  }
+  addProvenanceInputs(req, provenance) {
+    req.input("createdBy", sql.NVarChar, provenance.createdBy);
+    req.input("createdByType", sql.NVarChar, provenance.createdByType);
+    req.input("createdAt", sql.NVarChar, provenance.createdAt);
+    req.input("createdInConversation", sql.NVarChar, provenance.createdInConversation ?? null);
+    req.input("createdFromMessage", sql.NVarChar, provenance.createdFromMessage ?? null);
+    req.input("modifiedBy", sql.NVarChar, provenance.modifiedBy);
+    req.input("modifiedByType", sql.NVarChar, provenance.modifiedByType);
+    req.input("modifiedAt", sql.NVarChar, provenance.modifiedAt);
+    req.input("modifiedInConversation", sql.NVarChar, provenance.modifiedInConversation ?? null);
+    req.input("modifiedFromMessage", sql.NVarChar, provenance.modifiedFromMessage ?? null);
+  }
+};
+
+// src/SqlServerSearchProvider.ts
+import sql2 from "mssql";
+import { ProviderError as ProviderError2 } from "@utaba/deep-memory";
+function normaliseRank(rank) {
+  return Math.min(1, Math.max(0, rank / 1e3));
+}
+function buildHighlights(query, row) {
+  const highlights = {};
+  const terms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
+  const fields = [
+    { key: "label", hlCol: "hl_label" },
+    { key: "summary", hlCol: "hl_summary" },
+    { key: "data", hlCol: "hl_data" },
+    { key: "properties", hlCol: "hl_properties" }
+  ];
+  for (const { key, hlCol } of fields) {
+    const snippet = row[hlCol];
+    if (!snippet) continue;
+    const lowerSnippet = snippet.toLowerCase();
+    for (const term of terms) {
+      const idx = lowerSnippet.indexOf(term);
+      if (idx !== -1) {
+        const windowStart = Math.max(0, idx - 40);
+        const windowEnd = Math.min(snippet.length, idx + term.length + 40);
+        const prefix = windowStart > 0 ? "..." : "";
+        const suffix = windowEnd < snippet.length ? "..." : "";
+        const window = prefix + snippet.slice(windowStart, windowEnd) + suffix;
+        if (!highlights[key]) highlights[key] = [];
+        highlights[key].push(window);
+        break;
+      }
+    }
+  }
+  return Object.keys(highlights).length > 0 ? highlights : void 0;
+}
+var SqlServerSearchProvider = class {
+  pool;
+  schema;
+  procedureCreated = false;
+  constructor(config) {
+    this.pool = config.pool;
+    this.schema = config.schema ?? "dbo";
+  }
+  /**
+   * Ensure the stored procedure exists. Called lazily on first search.
+   * Idempotent — uses CREATE OR ALTER.
+   */
+  async ensureProcedure() {
+    if (this.procedureCreated) return;
+    try {
+      const ddl = getSearchProcSQL(this.schema);
+      await this.pool.request().query(ddl);
+      this.procedureCreated = true;
+    } catch (err) {
+      throw new ProviderError2(
+        `Failed to create search stored procedure: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  /**
+   * Index an entity for full-text search.
+   *
+   * No-op: the FT index on dm_entities uses CHANGE_TRACKING AUTO,
+   * so SQL Server automatically indexes rows on insert/update.
+   */
+  async indexEntity(_repositoryId, _entity) {
+  }
+  /**
+   * Remove an entity from the search index.
+   *
+   * No-op: the FT index auto-removes when the row is deleted from dm_entities.
+   */
+  async removeEntity(_repositoryId, _entityId) {
+  }
+  /**
+   * Full-text search across entity labels, summaries, properties, and data.
+   * Calls the dm_search_entities stored procedure using FREETEXTTABLE
+   * for natural-language queries.
+   */
+  async search(repositoryId, query, options) {
+    await this.ensureProcedure();
+    const limit = options?.limit ?? 20;
+    const offset = options?.offset ?? 0;
+    const entityTypes = options?.entityTypes;
+    try {
+      const request = this.pool.request();
+      request.input("RepositoryId", sql2.UniqueIdentifier, repositoryId);
+      request.input("Query", sql2.NVarChar(4e3), query);
+      request.input(
+        "EntityTypes",
+        sql2.NVarChar(sql2.MAX),
+        entityTypes && entityTypes.length > 0 ? JSON.stringify(entityTypes) : null
+      );
+      request.input("Limit", sql2.Int, limit);
+      request.input("Offset", sql2.Int, offset);
+      request.input("UseContains", sql2.Bit, 0);
+      const result = await request.execute(
+        `[${this.schema}].[dm_search_entities]`
+      );
+      const rows = result.recordset;
+      const total = rows.length > 0 ? rows[0]["total_count"] : 0;
+      const items = rows.map((row) => ({
+        id: row["entity_id"],
+        score: normaliseRank(row["ft_rank"]),
+        highlights: buildHighlights(query, row)
+      }));
+      return {
+        items,
+        total,
+        hasMore: offset + items.length < total,
+        limit,
+        offset
+      };
+    } catch (err) {
+      throw new ProviderError2(
+        `Full-text search failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  /**
+   * Re-index an entire repository.
+   *
+   * Since the FT index is auto-maintained, this triggers a manual
+   * population of the full-text catalog to pick up any pending changes.
+   */
+  async reindexRepository(_repositoryId, _entities) {
+    try {
+      await this.pool.request().query(
+        `ALTER FULLTEXT CATALOG [dm_fulltext_catalog] REORGANIZE`
+      );
+    } catch (err) {
+      throw new ProviderError2(
+        `Full-text reindex failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+};
+export {
+  SCHEMA_VERSION,
+  SqlServerSearchProvider,
+  SqlServerStorageProvider,
+  getSchemaSQL,
+  getSearchProcSQL
+};
+//# sourceMappingURL=index.js.map