@utaba/deep-memory-storage-cosmosdb 0.3.0

package/dist/index.js

@@ -0,0 +1,1630 @@
+// src/CosmosDbProvider.ts
+import crypto from "crypto";
+import { GremlinCompiler, ProviderError } from "@utaba/deep-memory";
+
+// src/CosmosDbConnection.ts
+import gremlin from "gremlin";
+var CosmosDbConnection = class {
+  client = null;
+  config;
+  constructor(config) {
+    this.config = {
+      ...config,
+      maxRetries: config.maxRetries ?? 3,
+      defaultTimeoutMs: config.defaultTimeoutMs ?? 3e4,
+      rejectUnauthorized: config.rejectUnauthorized ?? true
+    };
+  }
+  /** Open the WebSocket connection to CosmosDB Gremlin endpoint. */
+  async connect() {
+    if (this.client) return;
+    const authenticator = new gremlin.driver.auth.PlainTextSaslAuthenticator(
+      `/dbs/${this.config.database}/colls/${this.config.container}`,
+      this.config.key
+    );
+    this.client = new gremlin.driver.Client(this.config.endpoint, {
+      authenticator,
+      traversalsource: "g",
+      rejectUnauthorized: this.config.rejectUnauthorized,
+      mimeType: "application/vnd.gremlin-v2.0+json"
+    });
+    await this.client.open();
+  }
+  /** Close the WebSocket connection. */
+  async close() {
+    if (this.client) {
+      await this.client.close();
+      this.client = null;
+    }
+  }
+  /**
+   * Submit a parameterized Gremlin query with retry on transient errors.
+   * All user values should be passed as bindings (never interpolated into the query string).
+   */
+  async submit(query, bindings) {
+    if (!this.client) {
+      throw new Error("CosmosDbConnection: not connected. Call connect() first.");
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      try {
+        const resultSet = await this.client.submit(query, bindings);
+        const items = resultSet.toArray();
+        const requestCharge = extractRequestCharge(resultSet);
+        return { items, requestCharge };
+      } catch (err) {
+        lastError = err;
+        if (isTransientError(err) && attempt < this.config.maxRetries) {
+          const retryAfterMs = getRetryAfterMs(err, attempt);
+          await sleep(retryAfterMs);
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw lastError;
+  }
+  /** Get the underlying Gremlin client (for advanced usage). */
+  getClient() {
+    if (!this.client) {
+      throw new Error("CosmosDbConnection: not connected. Call connect() first.");
+    }
+    return this.client;
+  }
+};
+function isTransientError(err) {
+  if (err instanceof Error) {
+    const msg = err.message;
+    if (msg.includes("429") || msg.includes("RequestRateTooLarge")) return true;
+    if (msg.includes("503") || msg.includes("ServiceUnavailable")) return true;
+  }
+  const statusCode = err?.["statusCode"];
+  if (statusCode === 429 || statusCode === 503) return true;
+  return false;
+}
+function getRetryAfterMs(err, attempt) {
+  const retryAfter = err?.["retryAfterMs"];
+  if (typeof retryAfter === "number" && retryAfter > 0) {
+    return retryAfter;
+  }
+  return Math.min(500 * Math.pow(2, attempt), 1e4);
+}
+function extractRequestCharge(resultSet) {
+  const attrs = resultSet.attributes;
+  if (!attrs) return void 0;
+  const charge = attrs["x-ms-request-charge"] ?? attrs["x-ms-total-request-charge"];
+  return typeof charge === "number" ? charge : void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/mapping.ts
+function unwrap(val) {
+  if (Array.isArray(val) && val.length > 0) return val[0];
+  return val;
+}
+function unwrapStr(val) {
+  const v = unwrap(val);
+  return typeof v === "string" ? v : String(v ?? "");
+}
+function unwrapOptStr(val) {
+  const v = unwrap(val);
+  return v != null && v !== "" ? String(v) : void 0;
+}
+function safeParseJson(val, fallback) {
+  if (val == null) return fallback;
+  const str = typeof val === "string" ? val : String(unwrap(val));
+  if (!str || str === "") return fallback;
+  try {
+    return JSON.parse(str);
+  } catch {
+    return fallback;
+  }
+}
+function provenanceFromGremlin(props) {
+  return {
+    createdBy: unwrapStr(props["createdBy"]),
+    createdByType: unwrapStr(props["createdByType"]) || "agent",
+    createdAt: unwrapStr(props["createdAt"]),
+    createdInConversation: unwrapOptStr(props["createdInConversation"]),
+    createdFromMessage: unwrapOptStr(props["createdFromMessage"]),
+    modifiedBy: unwrapStr(props["modifiedBy"]),
+    modifiedByType: unwrapStr(props["modifiedByType"]) || "agent",
+    modifiedAt: unwrapStr(props["modifiedAt"]),
+    modifiedInConversation: unwrapOptStr(props["modifiedInConversation"]),
+    modifiedFromMessage: unwrapOptStr(props["modifiedFromMessage"])
+  };
+}
+function entityFromGremlin(props) {
+  const embeddingStr = unwrapOptStr(props["embedding"]);
+  return {
+    id: unwrapStr(props["id"]),
+    slug: unwrapStr(props["slug"]),
+    entityType: unwrapStr(props["entityType"]),
+    label: unwrapStr(props["entityLabel"]),
+    summary: unwrapOptStr(props["summary"]),
+    properties: safeParseJson(unwrap(props["properties"]), {}),
+    data: unwrapOptStr(props["data"]),
+    dataFormat: unwrapOptStr(props["dataFormat"]),
+    provenance: provenanceFromGremlin(props),
+    embedding: embeddingStr ? safeParseJson(embeddingStr, void 0) : void 0
+  };
+}
+function relationshipFromGremlin(props) {
+  const bidir = unwrap(props["bidirectional"]);
+  return {
+    id: unwrapStr(props["id"]),
+    relationshipType: unwrapStr(props["relationshipType"]),
+    sourceEntityId: unwrapStr(props["sourceEntityId"]),
+    targetEntityId: unwrapStr(props["targetEntityId"]),
+    properties: safeParseJson(unwrap(props["properties"]), {}),
+    bidirectional: bidir === true || bidir === "true",
+    provenance: provenanceFromGremlin(props)
+  };
+}
+function repositoryFromGremlin(props) {
+  return {
+    repositoryId: unwrapStr(props["repositoryId"]),
+    type: unwrapOptStr(props["type"]),
+    label: unwrapStr(props["repoLabel"]),
+    description: unwrapOptStr(props["description"]),
+    legal: unwrapOptStr(props["legal"]),
+    owner: unwrapOptStr(props["owner"]),
+    governanceConfig: safeParseJson(unwrap(props["governanceConfig"]), { mode: "open" }),
+    metadata: safeParseJson(unwrap(props["metadata"]), void 0),
+    createdAt: unwrapStr(props["createdAt"]),
+    createdBy: unwrapStr(props["createdBy"])
+  };
+}
+function repositorySummaryFromGremlin(props) {
+  return {
+    repositoryId: unwrapStr(props["repositoryId"]),
+    type: unwrapOptStr(props["type"]),
+    label: unwrapStr(props["repoLabel"]),
+    description: unwrapOptStr(props["description"]),
+    governanceConfig: safeParseJson(unwrap(props["governanceConfig"]), { mode: "open" })
+  };
+}
+function vocabularyFromGremlin(props) {
+  return safeParseJson(unwrap(props["vocabulary"]), {
+    version: "0.0.0",
+    lastModified: (/* @__PURE__ */ new Date()).toISOString(),
+    modifiedBy: "system",
+    entityTypes: [],
+    relationshipTypes: []
+  });
+}
+function changeRecordFromGremlin(props) {
+  return {
+    changeId: unwrapStr(props["changeId"]),
+    changeType: unwrapStr(props["changeType"]),
+    typeName: unwrapStr(props["typeName"]),
+    previousVersion: unwrapOptStr(props["previousVersion"]),
+    newVersion: unwrapStr(props["newVersion"]),
+    proposedBy: unwrapStr(props["proposedBy"]),
+    proposedAt: unwrapStr(props["proposedAt"]),
+    approvedBy: unwrapOptStr(props["approvedBy"]),
+    approvedAt: unwrapOptStr(props["approvedAt"]),
+    reason: unwrapStr(props["reason"])
+  };
+}
+function entityToGremlinProps(repositoryId, entity) {
+  const props = {
+    repositoryId,
+    entityType: entity.entityType,
+    entityLabel: entity.label,
+    slug: entity.slug,
+    properties: JSON.stringify(entity.properties ?? {}),
+    createdBy: entity.provenance.createdBy,
+    createdByType: entity.provenance.createdByType,
+    createdAt: entity.provenance.createdAt,
+    modifiedBy: entity.provenance.modifiedBy,
+    modifiedByType: entity.provenance.modifiedByType,
+    modifiedAt: entity.provenance.modifiedAt
+  };
+  if (entity.summary != null) props["summary"] = entity.summary;
+  if (entity.data != null) props["data"] = entity.data;
+  if (entity.dataFormat != null) props["dataFormat"] = entity.dataFormat;
+  if (entity.provenance.createdInConversation != null) props["createdInConversation"] = entity.provenance.createdInConversation;
+  if (entity.provenance.createdFromMessage != null) props["createdFromMessage"] = entity.provenance.createdFromMessage;
+  if (entity.provenance.modifiedInConversation != null) props["modifiedInConversation"] = entity.provenance.modifiedInConversation;
+  if (entity.provenance.modifiedFromMessage != null) props["modifiedFromMessage"] = entity.provenance.modifiedFromMessage;
+  if (entity.embedding != null) props["embedding"] = JSON.stringify(entity.embedding);
+  return props;
+}
+function relationshipToGremlinProps(repositoryId, rel) {
+  const props = {
+    repositoryId,
+    relationshipType: rel.relationshipType,
+    sourceEntityId: rel.sourceEntityId,
+    targetEntityId: rel.targetEntityId,
+    bidirectional: rel.bidirectional,
+    properties: JSON.stringify(rel.properties ?? {}),
+    createdBy: rel.provenance.createdBy,
+    createdByType: rel.provenance.createdByType,
+    createdAt: rel.provenance.createdAt,
+    modifiedBy: rel.provenance.modifiedBy,
+    modifiedByType: rel.provenance.modifiedByType,
+    modifiedAt: rel.provenance.modifiedAt
+  };
+  if (rel.provenance.createdInConversation != null) props["createdInConversation"] = rel.provenance.createdInConversation;
+  if (rel.provenance.createdFromMessage != null) props["createdFromMessage"] = rel.provenance.createdFromMessage;
+  if (rel.provenance.modifiedInConversation != null) props["modifiedInConversation"] = rel.provenance.modifiedInConversation;
+  if (rel.provenance.modifiedFromMessage != null) props["modifiedFromMessage"] = rel.provenance.modifiedFromMessage;
+  return props;
+}
+
+// src/queries/repository.ts
+import { DuplicateRepositoryError, RepositoryNotFoundError } from "@utaba/deep-memory";
+var REPO_LABEL = "_repository";
+function repoVertexId(repositoryId) {
+  return `repo:${repositoryId}`;
+}
+function propertyChain(bindings, props, startIndex) {
+  const parts = [];
+  let idx = startIndex;
+  for (const [key, value] of Object.entries(props)) {
+    if (value == null) continue;
+    const paramName = `p${idx++}`;
+    bindings[paramName] = value;
+    parts.push(`.property('${key}', ${paramName})`);
+  }
+  return { chain: parts.join(""), nextIndex: idx };
+}
+async function createRepository(conn, config) {
+  const vertexId = repoVertexId(config.repositoryId);
+  const existing = await conn.submit(
+    "g.V().has('id', vid).has('label', lbl).count()",
+    { vid: vertexId, lbl: REPO_LABEL }
+  );
+  if (existing.items.length > 0 && Number(existing.items[0]) > 0) {
+    throw new DuplicateRepositoryError(config.repositoryId);
+  }
+  const bindings = {
+    vid: vertexId,
+    rid: config.repositoryId
+  };
+  const props = {
+    repoLabel: config.label,
+    description: config.description,
+    type: config.type,
+    legal: config.legal,
+    owner: config.owner,
+    governanceConfig: JSON.stringify(config.governanceConfig),
+    metadata: config.metadata ? JSON.stringify(config.metadata) : void 0,
+    createdAt: config.createdAt,
+    createdBy: config.createdBy
+  };
+  const { chain } = propertyChain(bindings, props, 0);
+  const query = `g.addV('${REPO_LABEL}').property('id', vid).property('repositoryId', rid)${chain}`;
+  await conn.submit(query, bindings);
+  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 function getRepository(conn, repositoryId) {
+  const result = await conn.submit(
+    "g.V().has('id', vid).hasLabel('_repository').valueMap(true)",
+    { vid: repoVertexId(repositoryId) }
+  );
+  if (result.items.length === 0) return null;
+  return repositoryFromGremlin(result.items[0]);
+}
+async function listRepositories(conn, filter) {
+  const limit = filter?.limit ?? 20;
+  const offset = filter?.offset ?? 0;
+  let countQuery = "g.V().hasLabel('_repository')";
+  let dataQuery = "g.V().hasLabel('_repository')";
+  const bindings = {};
+  if (filter?.type) {
+    countQuery += ".has('type', filterType)";
+    dataQuery += ".has('type', filterType)";
+    bindings["filterType"] = filter.type;
+  }
+  const countResult = await conn.submit(`${countQuery}.count()`, bindings);
+  const total = Number(countResult.items[0] ?? 0);
+  bindings["rangeStart"] = offset;
+  bindings["rangeEnd"] = offset + limit;
+  const dataResult = await conn.submit(
+    `${dataQuery}.range(rangeStart, rangeEnd).valueMap(true)`,
+    bindings
+  );
+  const items = dataResult.items.map(repositorySummaryFromGremlin);
+  return {
+    items,
+    total,
+    hasMore: offset + limit < total,
+    limit,
+    offset
+  };
+}
+async function updateRepository(conn, repositoryId, updates) {
+  const vertexId = repoVertexId(repositoryId);
+  const existing = await getRepository(conn, repositoryId);
+  if (!existing) throw new RepositoryNotFoundError(repositoryId);
+  const bindings = { vid: vertexId };
+  const props = {};
+  if (updates.label !== void 0) props["repoLabel"] = updates.label;
+  if (updates.description !== void 0) props["description"] = updates.description;
+  if (updates.type !== void 0) props["type"] = updates.type;
+  if (updates.legal !== void 0) props["legal"] = updates.legal;
+  if (updates.owner !== void 0) props["owner"] = updates.owner;
+  if (updates.governanceConfig !== void 0) props["governanceConfig"] = JSON.stringify(updates.governanceConfig);
+  if (updates.metadata !== void 0) {
+    const merged = { ...existing.metadata, ...updates.metadata };
+    props["metadata"] = JSON.stringify(merged);
+  }
+  if (Object.keys(props).length === 0) return existing;
+  const { chain } = propertyChain(bindings, props, 0);
+  const query = `g.V().has('id', vid).hasLabel('_repository')${chain}`;
+  await conn.submit(query, bindings);
+  return await getRepository(conn, repositoryId);
+}
+var DELETE_BATCH_SIZE = 500;
+async function deleteRepository(conn, repositoryId, onProgress) {
+  const entityCountResult = await conn.submit(
+    "g.V().has('repositoryId', rid).has('entityType').count()",
+    { rid: repositoryId }
+  );
+  const totalEntities = Number(entityCountResult.items[0] ?? 0);
+  const relCountResult = await conn.submit(
+    "g.E().has('repositoryId', rid).count()",
+    { rid: repositoryId }
+  );
+  const totalRelationships = Number(relCountResult.items[0] ?? 0);
+  let relationshipsDeleted = 0;
+  let entitiesDeleted = 0;
+  while (true) {
+    await conn.submit(
+      "g.E().has('repositoryId', rid).limit(batchSize).drop()",
+      { rid: repositoryId, batchSize: DELETE_BATCH_SIZE }
+    );
+    const remaining = await conn.submit(
+      "g.E().has('repositoryId', rid).limit(1).count()",
+      { rid: repositoryId }
+    );
+    const remainingCount = Number(remaining.items[0] ?? 0);
+    relationshipsDeleted = totalRelationships - remainingCount;
+    await onProgress?.({ entitiesDeleted, relationshipsDeleted, totalEntities, totalRelationships });
+    if (remainingCount === 0) break;
+  }
+  while (true) {
+    await conn.submit(
+      "g.V().has('repositoryId', rid).limit(batchSize).drop()",
+      { rid: repositoryId, batchSize: DELETE_BATCH_SIZE }
+    );
+    const remaining = await conn.submit(
+      "g.V().has('repositoryId', rid).limit(1).count()",
+      { rid: repositoryId }
+    );
+    const remainingCount = Number(remaining.items[0] ?? 0);
+    entitiesDeleted = totalEntities - remainingCount;
+    await onProgress?.({ entitiesDeleted, relationshipsDeleted, totalEntities, totalRelationships });
+    if (remainingCount === 0) break;
+  }
+}
+async function deleteAllContents(conn, repositoryId, onProgress) {
+  const entityCountResult = await conn.submit(
+    "g.V().has('repositoryId', rid).has('entityType').count()",
+    { rid: repositoryId }
+  );
+  const totalEntities = Number(entityCountResult.items[0] ?? 0);
+  const relCountResult = await conn.submit(
+    "g.E().has('repositoryId', rid).count()",
+    { rid: repositoryId }
+  );
+  const totalRelationships = Number(relCountResult.items[0] ?? 0);
+  let relationshipsDeleted = 0;
+  let entitiesDeleted = 0;
+  while (true) {
+    await conn.submit(
+      "g.E().has('repositoryId', rid).limit(batchSize).drop()",
+      { rid: repositoryId, batchSize: DELETE_BATCH_SIZE }
+    );
+    const remaining = await conn.submit(
+      "g.E().has('repositoryId', rid).limit(1).count()",
+      { rid: repositoryId }
+    );
+    const remainingCount = Number(remaining.items[0] ?? 0);
+    relationshipsDeleted = totalRelationships - remainingCount;
+    await onProgress?.({ entitiesDeleted, relationshipsDeleted, totalEntities, totalRelationships });
+    if (remainingCount === 0) break;
+  }
+  while (true) {
+    await conn.submit(
+      "g.V().has('repositoryId', rid).has('entityType').limit(batchSize).drop()",
+      { rid: repositoryId, batchSize: DELETE_BATCH_SIZE }
+    );
+    const remaining = await conn.submit(
+      "g.V().has('repositoryId', rid).has('entityType').limit(1).count()",
+      { rid: repositoryId }
+    );
+    const remainingCount = Number(remaining.items[0] ?? 0);
+    entitiesDeleted = totalEntities - remainingCount;
+    await onProgress?.({ entitiesDeleted, relationshipsDeleted, totalEntities, totalRelationships });
+    if (remainingCount === 0) break;
+  }
+  return { deletedEntities: totalEntities, deletedRelationships: totalRelationships };
+}
+async function getRepositoryStats(conn, repositoryId) {
+  const vocabResult = await conn.submit(
+    "g.V().has('repositoryId', rid).hasLabel('_vocabulary').values('vocabulary')",
+    { rid: repositoryId }
+  );
+  let vocabVersion = "0.0.0";
+  if (vocabResult.items.length > 0) {
+    try {
+      const vocab = JSON.parse(vocabResult.items[0]);
+      vocabVersion = vocab.version ?? "0.0.0";
+    } catch {
+    }
+  }
+  const entityResult = await conn.submit(
+    "g.V().has('repositoryId', rid).has('entityType').group().by('entityType').by(count())",
+    { rid: repositoryId }
+  );
+  const entityTypeBreakdown = {};
+  let entityCount = 0;
+  if (entityResult.items.length > 0) {
+    const grouped = entityResult.items[0];
+    for (const [type, count] of Object.entries(grouped)) {
+      entityTypeBreakdown[type] = Number(count);
+      entityCount += Number(count);
+    }
+  }
+  const relResult = await conn.submit(
+    "g.E().has('repositoryId', rid).group().by('relationshipType').by(count())",
+    { rid: repositoryId }
+  );
+  const relationshipTypeBreakdown = {};
+  let relationshipCount = 0;
+  if (relResult.items.length > 0) {
+    const grouped = relResult.items[0];
+    for (const [type, count] of Object.entries(grouped)) {
+      relationshipTypeBreakdown[type] = Number(count);
+      relationshipCount += Number(count);
+    }
+  }
+  return {
+    entityCount,
+    relationshipCount,
+    vocabularyVersion: vocabVersion,
+    entityTypeBreakdown,
+    relationshipTypeBreakdown
+  };
+}
+
+// src/queries/vocabulary.ts
+function vocabVertexId(repositoryId) {
+  return `vocab:${repositoryId}`;
+}
+async function getVocabulary(conn, repositoryId) {
+  const result = await conn.submit(
+    "g.V().has('id', vid).hasLabel('_vocabulary').valueMap(true)",
+    { vid: vocabVertexId(repositoryId) }
+  );
+  if (result.items.length === 0) {
+    return {
+      version: "0.0.0",
+      lastModified: (/* @__PURE__ */ new Date()).toISOString(),
+      modifiedBy: "system",
+      entityTypes: [],
+      relationshipTypes: []
+    };
+  }
+  return vocabularyFromGremlin(result.items[0]);
+}
+async function saveVocabulary(conn, repositoryId, vocabulary) {
+  const vid = vocabVertexId(repositoryId);
+  const vocabJson = JSON.stringify(vocabulary);
+  const existing = await conn.submit(
+    "g.V().has('id', vid).hasLabel('_vocabulary').count()",
+    { vid }
+  );
+  if (Number(existing.items[0] ?? 0) > 0) {
+    await conn.submit(
+      "g.V().has('id', vid).hasLabel('_vocabulary').property('vocabulary', vocabJson)",
+      { vid, vocabJson }
+    );
+  } else {
+    await conn.submit(
+      "g.addV('_vocabulary').property('id', vid).property('repositoryId', rid).property('vocabulary', vocabJson)",
+      { vid, rid: repositoryId, vocabJson }
+    );
+  }
+}
+async function getVocabularyChangeLog(conn, repositoryId, options) {
+  const limit = options?.limit ?? 10;
+  const offset = options?.offset ?? 0;
+  const countResult = await conn.submit(
+    "g.V().has('repositoryId', rid).hasLabel('_vocabularyChangeLog').count()",
+    { rid: repositoryId }
+  );
+  const total = Number(countResult.items[0] ?? 0);
+  const dataResult = await conn.submit(
+    "g.V().has('repositoryId', rid).hasLabel('_vocabularyChangeLog').order().by('proposedAt', decr).range(rangeStart, rangeEnd).valueMap(true)",
+    { rid: repositoryId, rangeStart: offset, rangeEnd: offset + limit }
+  );
+  const items = dataResult.items.map(changeRecordFromGremlin);
+  return {
+    items,
+    total,
+    hasMore: offset + limit < total,
+    limit,
+    offset
+  };
+}
+
+// src/queries/entity.ts
+import { DuplicateEntityError } from "@utaba/deep-memory";
+async function createEntity(conn, repositoryId, entity) {
+  const existing = await conn.submit(
+    "g.V().has('repositoryId', rid).has('id', eid).count()",
+    { rid: repositoryId, eid: entity.id }
+  );
+  if (Number(existing.items[0] ?? 0) > 0) {
+    throw new DuplicateEntityError(entity.id);
+  }
+  const props = entityToGremlinProps(repositoryId, entity);
+  const bindings = { vid: entity.id };
+  const propParts = [];
+  let idx = 0;
+  for (const [key, value] of Object.entries(props)) {
+    const paramName = `p${idx++}`;
+    bindings[paramName] = value;
+    propParts.push(`.property('${key}', ${paramName})`);
+  }
+  bindings["vertexLabel"] = entity.entityType;
+  const query = `g.addV(vertexLabel).property('id', vid)${propParts.join("")}`;
+  await conn.submit(query, bindings);
+  return entity;
+}
+async function getEntity(conn, repositoryId, entityId) {
+  const result = await conn.submit(
+    "g.V().has('repositoryId', rid).has('id', eid).has('entityType').valueMap(true)",
+    { rid: repositoryId, eid: entityId }
+  );
+  if (result.items.length === 0) return null;
+  return entityFromGremlin(result.items[0]);
+}
+async function getEntityBySlug(conn, repositoryId, slug) {
+  const result = await conn.submit(
+    "g.V().has('repositoryId', rid).has('slug', slugVal).has('entityType').valueMap(true)",
+    { rid: repositoryId, slugVal: slug }
+  );
+  if (result.items.length === 0) return null;
+  return entityFromGremlin(result.items[0]);
+}
+async function getEntities(conn, repositoryId, entityIds) {
+  if (entityIds.length === 0) return /* @__PURE__ */ new Map();
+  const bindings = { rid: repositoryId };
+  const idParams = [];
+  entityIds.forEach((id, i) => {
+    const paramName = `eid${i}`;
+    bindings[paramName] = id;
+    idParams.push(paramName);
+  });
+  const withinClause = `within(${idParams.join(", ")})`;
+  const result = await conn.submit(
+    `g.V().has('repositoryId', rid).has('id', ${withinClause}).has('entityType').valueMap(true)`,
+    bindings
+  );
+  const map = /* @__PURE__ */ new Map();
+  for (const item of result.items) {
+    const entity = entityFromGremlin(item);
+    map.set(entity.id, entity);
+  }
+  return map;
+}
+async function updateEntity(conn, repositoryId, entityId, updates) {
+  const bindings = { rid: repositoryId, eid: entityId };
+  const propParts = [];
+  let idx = 0;
+  const addProp = (key, value) => {
+    const paramName = `p${idx++}`;
+    bindings[paramName] = value;
+    propParts.push(`.property('${key}', ${paramName})`);
+  };
+  if (updates.label !== void 0) addProp("entityLabel", updates.label);
+  if (updates.slug !== void 0) addProp("slug", updates.slug);
+  if (updates.summary !== void 0) addProp("summary", updates.summary);
+  if (updates.properties !== void 0) addProp("properties", JSON.stringify(updates.properties));
+  if (updates.data !== void 0) addProp("data", updates.data);
+  if (updates.dataFormat !== void 0) addProp("dataFormat", updates.dataFormat);
+  if (updates.embedding !== void 0) addProp("embedding", JSON.stringify(updates.embedding));
+  addProp("modifiedBy", updates.provenance.modifiedBy);
+  addProp("modifiedByType", updates.provenance.modifiedByType);
+  addProp("modifiedAt", updates.provenance.modifiedAt);
+  if (updates.provenance.modifiedInConversation != null) addProp("modifiedInConversation", updates.provenance.modifiedInConversation);
+  if (updates.provenance.modifiedFromMessage != null) addProp("modifiedFromMessage", updates.provenance.modifiedFromMessage);
+  const query = `g.V().has('repositoryId', rid).has('id', eid).has('entityType')${propParts.join("")}`;
+  await conn.submit(query, bindings);
+  return await getEntity(conn, repositoryId, entityId);
+}
+async function deleteEntity(conn, repositoryId, entityId) {
+  await conn.submit(
+    "g.V().has('repositoryId', rid).has('id', eid).has('entityType').drop()",
+    { rid: repositoryId, eid: entityId }
+  );
+}
+async function deleteEntitiesByType(conn, repositoryId, entityType) {
+  const entityCountResult = await conn.submit(
+    "g.V().has('repositoryId', rid).has('entityType', etype).count()",
+    { rid: repositoryId, etype: entityType }
+  );
+  const deletedEntities = Number(entityCountResult.items[0] ?? 0);
+  const relCountResult = await conn.submit(
+    "g.V().has('repositoryId', rid).has('entityType', etype).bothE().dedup().count()",
+    { rid: repositoryId, etype: entityType }
+  );
+  const deletedRelationships = Number(relCountResult.items[0] ?? 0);
+  if (deletedEntities > 0) {
+    await conn.submit(
+      "g.V().has('repositoryId', rid).has('entityType', etype).drop()",
+      { rid: repositoryId, etype: entityType }
+    );
+  }
+  return { deletedEntities, deletedRelationships };
+}
+async function findEntities(conn, repositoryId, query) {
+  const bindings = { rid: repositoryId };
+  let filterClause = ".has('repositoryId', rid).has('entityType')";
+  if (query.entityTypes && query.entityTypes.length > 0) {
+    const typeParams = [];
+    query.entityTypes.forEach((t, i) => {
+      const paramName = `etype${i}`;
+      bindings[paramName] = t;
+      typeParams.push(paramName);
+    });
+    filterClause += `.has('entityType', within(${typeParams.join(", ")}))`;
+  }
+  if (query.searchTerm) {
+    bindings["searchTerm"] = query.searchTerm.toLowerCase();
+    filterClause += ".has('slug', containing(searchTerm))";
+  }
+  const countResult = await conn.submit(
+    `g.V()${filterClause}.count()`,
+    bindings
+  );
+  const total = Number(countResult.items[0] ?? 0);
+  bindings["rangeStart"] = query.offset;
+  bindings["rangeEnd"] = query.offset + query.limit;
+  const dataResult = await conn.submit(
+    `g.V()${filterClause}.range(rangeStart, rangeEnd).valueMap(true)`,
+    bindings
+  );
+  let items = dataResult.items.map(entityFromGremlin);
+  if (query.properties && Object.keys(query.properties).length > 0) {
+    items = items.filter((entity) => {
+      for (const [key, value] of Object.entries(query.properties)) {
+        if (entity.properties[key] !== value) return false;
+      }
+      return true;
+    });
+  }
+  return {
+    items,
+    total,
+    hasMore: query.offset + query.limit < total,
+    limit: query.limit,
+    offset: query.offset
+  };
+}
+
+// src/queries/relationship.ts
+import { DuplicateRelationshipError, matchesPropertyFilters } from "@utaba/deep-memory";
+async function createRelationship(conn, repositoryId, relationship) {
+  const existing = await conn.submit(
+    "g.E().has('id', relId).count()",
+    { relId: relationship.id }
+  );
+  if (Number(existing.items[0] ?? 0) > 0) {
+    throw new DuplicateRelationshipError(relationship.id);
+  }
+  const props = relationshipToGremlinProps(repositoryId, relationship);
+  const bindings = {
+    relId: relationship.id,
+    srcId: relationship.sourceEntityId,
+    tgtId: relationship.targetEntityId,
+    rid: repositoryId,
+    edgeLabel: relationship.relationshipType
+  };
+  const propParts = [];
+  let idx = 0;
+  for (const [key, value] of Object.entries(props)) {
+    const paramName = `p${idx++}`;
+    bindings[paramName] = value;
+    propParts.push(`.property('${key}', ${paramName})`);
+  }
+  const query = `g.V().has('repositoryId', rid).has('id', srcId).has('entityType').addE(edgeLabel).to(g.V().has('repositoryId', rid).has('id', tgtId).has('entityType')).property('id', relId)${propParts.join("")}`;
+  await conn.submit(query, bindings);
+  return relationship;
+}
+async function getRelationship(conn, repositoryId, relationshipId) {
+  const result = await conn.submit(
+    "g.E().has('id', relId).has('repositoryId', rid).valueMap(true)",
+    { relId: relationshipId, rid: repositoryId }
+  );
+  if (result.items.length === 0) return null;
+  return relationshipFromGremlin(result.items[0]);
+}
+async function getEntityRelationships(conn, repositoryId, entityId, options) {
+  const limit = options?.limit ?? 50;
+  const offset = options?.offset ?? 0;
+  const direction = options?.direction ?? "both";
+  const bindings = {
+    rid: repositoryId,
+    eid: entityId
+  };
+  let edgeTraversal;
+  switch (direction) {
+    case "outbound":
+      edgeTraversal = "g.V().has('repositoryId', rid).has('id', eid).has('entityType').outE()";
+      break;
+    case "inbound":
+      edgeTraversal = "g.V().has('repositoryId', rid).has('id', eid).has('entityType').inE()";
+      break;
+    case "both":
+    default:
+      edgeTraversal = "g.V().has('repositoryId', rid).has('id', eid).has('entityType').bothE()";
+      break;
+  }
+  let typeFilter = "";
+  if (options?.relationshipTypes && options.relationshipTypes.length > 0) {
+    const typeParams = [];
+    options.relationshipTypes.forEach((t, i) => {
+      const paramName = `rtype${i}`;
+      bindings[paramName] = t;
+      typeParams.push(paramName);
+    });
+    typeFilter = `.hasLabel(${typeParams.join(", ")})`;
+  }
+  let unionQuery = null;
+  if (direction === "outbound") {
+    unionQuery = `g.V().has('repositoryId', rid).has('id', eid).has('entityType').union(outE()${typeFilter}, inE()${typeFilter}.has('bidirectional', true))`;
+  } else if (direction === "inbound") {
+    unionQuery = `g.V().has('repositoryId', rid).has('id', eid).has('entityType').union(inE()${typeFilter}, outE()${typeFilter}.has('bidirectional', true))`;
+  }
+  const baseQuery = unionQuery ?? `${edgeTraversal}${typeFilter}`;
+  const countResult = await conn.submit(`${baseQuery}.dedup().count()`, bindings);
+  const total = Number(countResult.items[0] ?? 0);
+  bindings["rangeStart"] = offset;
+  bindings["rangeEnd"] = offset + limit;
+  const dataResult = await conn.submit(
+    `${baseQuery}.dedup().range(rangeStart, rangeEnd).valueMap(true)`,
+    bindings
+  );
+  let items = dataResult.items.map(relationshipFromGremlin);
+  if (options?.propertyFilters && options.propertyFilters.length > 0) {
+    items = items.filter((rel) => matchesPropertyFilters(rel.properties, options.propertyFilters));
+  }
+  return {
+    items,
+    total,
+    hasMore: offset + limit < total,
+    limit,
+    offset
+  };
+}
+async function deleteRelationship(conn, repositoryId, relationshipId) {
+  await conn.submit(
+    "g.E().has('id', relId).has('repositoryId', rid).drop()",
+    { relId: relationshipId, rid: repositoryId }
+  );
+}
+async function deleteRelationshipsByType(conn, repositoryId, relationshipType) {
+  const countResult = await conn.submit(
+    "g.E().has('repositoryId', rid).hasLabel(rtype).count()",
+    { rid: repositoryId, rtype: relationshipType }
+  );
+  const deletedRelationships = Number(countResult.items[0] ?? 0);
+  if (deletedRelationships > 0) {
+    await conn.submit(
+      "g.E().has('repositoryId', rid).hasLabel(rtype).drop()",
+      { rid: repositoryId, rtype: relationshipType }
+    );
+  }
+  return { deletedRelationships };
+}
+
+// src/queries/traversal.ts
+import { matchesPropertyFilters as matchesPropertyFilters2 } from "@utaba/deep-memory";
+async function exploreNeighbourhood(conn, repositoryId, entityId, options) {
+  const layers = [];
+  let frontier = /* @__PURE__ */ new Set([entityId]);
+  const visited = /* @__PURE__ */ new Set([entityId]);
+  for (let depth = 0; depth < options.depth; depth++) {
+    const layer = {};
+    const nextFrontier = /* @__PURE__ */ new Set();
+    for (const currentId of frontier) {
+      const rels = await getRelationshipsForEntity(conn, repositoryId, currentId, options);
+      for (const rel of rels) {
+        const relType = rel.relationshipType;
+        if (!layer[relType]) {
+          layer[relType] = { total: 0, entities: [], relationships: [] };
+        }
+        let connectedId;
+        if (rel.sourceEntityId === currentId) {
+          connectedId = rel.targetEntityId;
+        } else {
+          connectedId = rel.sourceEntityId;
+        }
+        if (!visited.has(connectedId)) {
+          if (options.entityTypes && options.entityTypes.length > 0) {
+            const entity = await getEntityLight(conn, repositoryId, connectedId);
+            if (!entity || !options.entityTypes.includes(entity.entityType)) continue;
+            layer[relType].entities.push(entity);
+          } else {
+            const entity = await getEntityLight(conn, repositoryId, connectedId);
+            if (entity) {
+              layer[relType].entities.push(entity);
+            }
+          }
+          visited.add(connectedId);
+          nextFrontier.add(connectedId);
+        }
+        layer[relType].relationships.push(rel);
+        layer[relType].total = layer[relType].entities.length;
+      }
+    }
+    for (const relType of Object.keys(layer)) {
+      const group = layer[relType];
+      const start = options.offsetPerType;
+      const end = start + options.limitPerType;
+      group.entities = group.entities.slice(start, end);
+      group.relationships = group.relationships.slice(start, end);
+    }
+    if (Object.keys(layer).length > 0) {
+      layers.push(layer);
+    }
+    frontier = nextFrontier;
+    if (frontier.size === 0) break;
+  }
+  return { centreId: entityId, layers };
+}
+async function getRelationshipsForEntity(conn, repositoryId, entityId, options) {
+  const bindings = { rid: repositoryId, eid: entityId };
+  let edgeTraversal;
+  switch (options.direction) {
+    case "outbound":
+      edgeTraversal = "g.V().has('repositoryId', rid).has('id', eid).has('entityType').union(outE(), inE().has('bidirectional', true))";
+      break;
+    case "inbound":
+      edgeTraversal = "g.V().has('repositoryId', rid).has('id', eid).has('entityType').union(inE(), outE().has('bidirectional', true))";
+      break;
+    case "both":
+    default:
+      edgeTraversal = "g.V().has('repositoryId', rid).has('id', eid).has('entityType').bothE()";
+      break;
+  }
+  let typeFilter = "";
+  if (options.relationshipTypes && options.relationshipTypes.length > 0) {
+    const typeParams = [];
+    options.relationshipTypes.forEach((t, i) => {
+      const paramName = `rtype${i}`;
+      bindings[paramName] = t;
+      typeParams.push(paramName);
+    });
+    typeFilter = `.hasLabel(${typeParams.join(", ")})`;
+  }
+  const result = await conn.submit(
+    `${edgeTraversal}${typeFilter}.dedup().valueMap(true)`,
+    bindings
+  );
+  let rels = result.items.map(relationshipFromGremlin);
+  if (options.relationshipPropertyFilters && options.relationshipPropertyFilters.length > 0) {
+    rels = rels.filter((rel) => matchesPropertyFilters2(rel.properties, options.relationshipPropertyFilters));
+  }
+  return rels;
+}
+async function getEntityLight(conn, repositoryId, entityId) {
+  const result = await conn.submit(
+    "g.V().has('repositoryId', rid).has('id', eid).has('entityType').valueMap(true)",
+    { rid: repositoryId, eid: entityId }
+  );
+  if (result.items.length === 0) return null;
+  return entityFromGremlin(result.items[0]);
+}
+async function findPaths(conn, repositoryId, sourceId, targetId, options) {
+  const paths = [];
+  const maxDepth = options.maxDepth;
+  const limit = options.limit;
+  let queue = [{ entityId: sourceId, path: [sourceId], relationshipIds: [] }];
+  for (let depth = 0; depth < maxDepth && paths.length < limit; depth++) {
+    const nextQueue = [];
+    for (const state of queue) {
+      if (paths.length >= limit) break;
+      const bindings = { rid: repositoryId, eid: state.entityId };
+      let edgeQuery = "g.V().has('repositoryId', rid).has('id', eid).has('entityType').bothE()";
+      if (options.relationshipTypes && options.relationshipTypes.length > 0) {
+        const typeParams = [];
+        options.relationshipTypes.forEach((t, i) => {
+          const paramName = `rtype${i}`;
+          bindings[paramName] = t;
+          typeParams.push(paramName);
+        });
+        edgeQuery += `.hasLabel(${typeParams.join(", ")})`;
+      }
+      const relResult = await conn.submit(`${edgeQuery}.valueMap(true)`, bindings);
+      const rels = relResult.items.map(relationshipFromGremlin);
+      let filteredRels = rels;
+      if (options.relationshipPropertyFilters && options.relationshipPropertyFilters.length > 0) {
+        filteredRels = rels.filter((r) => matchesPropertyFilters2(r.properties, options.relationshipPropertyFilters));
+      }
+      for (const rel of filteredRels) {
+        const nextId = rel.sourceEntityId === state.entityId ? rel.targetEntityId : rel.sourceEntityId;
+        if (state.path.includes(nextId)) continue;
+        if (options.entityTypes && options.entityTypes.length > 0 && nextId !== targetId) {
+          const entity = await getEntityLight(conn, repositoryId, nextId);
+          if (!entity || !options.entityTypes.includes(entity.entityType)) continue;
+        }
+        const newPath = [...state.path, nextId];
+        const newRelIds = [...state.relationshipIds, rel.id];
+        if (nextId === targetId) {
+          paths.push({ entityIds: newPath, relationshipIds: newRelIds });
+          if (paths.length >= limit) break;
+        } else {
+          nextQueue.push({ entityId: nextId, path: newPath, relationshipIds: newRelIds });
+        }
+      }
+    }
+    queue = nextQueue;
+    if (queue.length === 0) break;
+  }
+  return {
+    paths,
+    totalPaths: paths.length
+  };
+}
+
+// src/queries/timeline.ts
+async function getTimeline(conn, repositoryId, entityId, options) {
+  const events = [];
+  const entityResult = await conn.submit(
+    "g.V().has('repositoryId', rid).has('id', eid).has('entityType').valueMap('createdAt', 'modifiedAt')",
+    { rid: repositoryId, eid: entityId }
+  );
+  if (entityResult.items.length > 0) {
+    const props = entityResult.items[0];
+    const createdAt = unwrapValue(props["createdAt"]);
+    const modifiedAt = unwrapValue(props["modifiedAt"]);
+    if (createdAt && isInTimeRange(createdAt, options.timeRange)) {
+      events.push({
+        timestamp: createdAt,
+        eventType: "entity_created",
+        entityId
+      });
+    }
+    if (modifiedAt && modifiedAt !== createdAt && isInTimeRange(modifiedAt, options.timeRange)) {
+      events.push({
+        timestamp: modifiedAt,
+        eventType: "entity_modified",
+        entityId
+      });
+    }
+  }
+  const relResult = await conn.submit(
+    "g.V().has('repositoryId', rid).has('id', eid).has('entityType').bothE().valueMap('id', 'createdAt')",
+    { rid: repositoryId, eid: entityId }
+  );
+  for (const item of relResult.items) {
+    const props = item;
+    const relId = unwrapValue(props["id"]);
+    const relCreatedAt = unwrapValue(props["createdAt"]);
+    if (relCreatedAt && isInTimeRange(relCreatedAt, options.timeRange)) {
+      events.push({
+        timestamp: relCreatedAt,
+        eventType: "relationship_created",
+        entityId,
+        relationshipId: relId
+      });
+    }
+  }
+  events.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+  let filtered = events;
+  if (options.eventTypes && options.eventTypes.length > 0) {
+    filtered = events.filter((e) => options.eventTypes.includes(e.eventType));
+  }
+  const total = filtered.length;
+  const paged = filtered.slice(options.offset, options.offset + options.limit);
+  return { events: paged, total };
+}
+function unwrapValue(val) {
+  if (Array.isArray(val) && val.length > 0) return String(val[0]);
+  return String(val ?? "");
+}
+function isInTimeRange(timestamp, timeRange) {
+  if (!timeRange) return true;
+  return timestamp >= timeRange.from && timestamp <= timeRange.to;
+}
+
+// src/queries/bulk.ts
+var EXPORT_BATCH_SIZE = 100;
+var IMPORT_CONCURRENCY = 8;
+async function runWithConcurrency(items, concurrency, fn) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  const workers = [];
+  for (let w = 0; w < Math.min(concurrency, items.length); w++) {
+    workers.push(
+      (async () => {
+        while (nextIndex < items.length) {
+          const idx = nextIndex++;
+          results[idx] = await fn(items[idx]);
+        }
+      })()
+    );
+  }
+  await Promise.all(workers);
+  return results;
+}
+async function* exportAll(conn, repositoryId) {
+  let sequence = 0;
+  let cursor = "";
+  while (true) {
+    const result = cursor === "" ? await conn.submit(
+      "g.V().has('repositoryId', rid).has('entityType').order().by('id').limit(batchSize).valueMap(true)",
+      { rid: repositoryId, batchSize: EXPORT_BATCH_SIZE }
+    ) : await conn.submit(
+      "g.V().has('repositoryId', rid).has('entityType').has('id', gt(cursor)).order().by('id').limit(batchSize).valueMap(true)",
+      { rid: repositoryId, cursor, batchSize: EXPORT_BATCH_SIZE }
+    );
+    const entities = result.items.map(entityFromGremlin);
+    const isLast = entities.length < EXPORT_BATCH_SIZE;
+    if (entities.length > 0) {
+      cursor = entities[entities.length - 1].id;
+      yield {
+        type: "entities",
+        data: entities,
+        sequence: sequence++,
+        isLast
+      };
+    }
+    if (isLast) break;
+  }
+  cursor = "";
+  while (true) {
+    const result = cursor === "" ? await conn.submit(
+      "g.E().has('repositoryId', rid).order().by('id').limit(batchSize).valueMap(true)",
+      { rid: repositoryId, batchSize: EXPORT_BATCH_SIZE }
+    ) : await conn.submit(
+      "g.E().has('repositoryId', rid).has('id', gt(cursor)).order().by('id').limit(batchSize).valueMap(true)",
+      { rid: repositoryId, cursor, batchSize: EXPORT_BATCH_SIZE }
+    );
+    const relationships = result.items.map(relationshipFromGremlin);
+    const isLast = relationships.length < EXPORT_BATCH_SIZE;
+    if (relationships.length > 0) {
+      cursor = relationships[relationships.length - 1].id;
+      yield {
+        type: "relationships",
+        data: relationships,
+        sequence: sequence++,
+        isLast
+      };
+    }
+    if (isLast) break;
+  }
+  if (sequence === 0) {
+    yield {
+      type: "entities",
+      data: [],
+      sequence: 0,
+      isLast: true
+    };
+  }
+}
+async function importBulk(conn, repositoryId, data, options) {
+  let entitiesImported = 0;
+  let relationshipsImported = 0;
+  const errors = [];
+  const skipCheck = options?.skipExistenceCheck ?? false;
+  for (const chunk of data) {
+    if (chunk.entities && chunk.entities.length > 0) {
+      const results = await runWithConcurrency(
+        chunk.entities,
+        IMPORT_CONCURRENCY,
+        async (entity) => {
+          try {
+            if (skipCheck) {
+              await insertEntity(conn, repositoryId, entity);
+            } else {
+              await upsertEntity(conn, repositoryId, entity);
+            }
+            return { ok: true, id: entity.id };
+          } catch (err) {
+            return {
+              ok: false,
+              id: entity.id,
+              error: err instanceof Error ? err.message : String(err)
+            };
+          }
+        }
+      );
+      for (const r of results) {
+        if (r.ok) {
+          entitiesImported++;
+        } else {
+          errors.push({ item: `entity:${r.id}`, error: r.error });
+        }
+      }
+    }
+    if (chunk.relationships && chunk.relationships.length > 0) {
+      const results = await runWithConcurrency(
+        chunk.relationships,
+        IMPORT_CONCURRENCY,
+        async (rel) => {
+          try {
+            if (skipCheck) {
+              await insertRelationship(conn, repositoryId, rel);
+            } else {
+              await upsertRelationship(conn, repositoryId, rel);
+            }
+            return { ok: true, id: rel.id };
+          } catch (err) {
+            return {
+              ok: false,
+              id: rel.id,
+              error: err instanceof Error ? err.message : String(err)
+            };
+          }
+        }
+      );
+      for (const r of results) {
+        if (r.ok) {
+          relationshipsImported++;
+        } else {
+          errors.push({ item: `relationship:${r.id}`, error: r.error });
+        }
+      }
+    }
+  }
+  return { entitiesImported, relationshipsImported, errors };
+}
+async function insertEntity(conn, repositoryId, entity) {
+  const props = entityToGremlinProps(repositoryId, entity);
+  const bindings = {
+    vid: entity.id,
+    vertexLabel: entity.entityType
+  };
+  const propParts = [];
+  let idx = 0;
+  for (const [key, value] of Object.entries(props)) {
+    const paramName = `p${idx++}`;
+    bindings[paramName] = value;
+    propParts.push(`.property('${key}', ${paramName})`);
+  }
+  const query = `g.addV(vertexLabel).property('id', vid)${propParts.join("")}`;
+  await conn.submit(query, bindings);
+}
+async function insertRelationship(conn, repositoryId, rel) {
+  const props = relationshipToGremlinProps(repositoryId, rel);
+  const bindings = {
+    relId: rel.id,
+    srcId: rel.sourceEntityId,
+    tgtId: rel.targetEntityId,
+    rid: repositoryId,
+    edgeLabel: rel.relationshipType
+  };
+  const propParts = [];
+  let idx = 0;
+  for (const [key, value] of Object.entries(props)) {
+    const paramName = `p${idx++}`;
+    bindings[paramName] = value;
+    propParts.push(`.property('${key}', ${paramName})`);
+  }
+  const query = `g.V().has('repositoryId', rid).has('id', srcId).has('entityType').addE(edgeLabel).to(g.V().has('repositoryId', rid).has('id', tgtId).has('entityType')).property('id', relId)${propParts.join("")}`;
+  await conn.submit(query, bindings);
+}
+async function upsertEntity(conn, repositoryId, entity) {
+  const props = entityToGremlinProps(repositoryId, entity);
+  const bindings = {
+    vid: entity.id,
+    rid: repositoryId,
+    vertexLabel: entity.entityType
+  };
+  const propParts = [];
+  let idx = 0;
+  for (const [key, value] of Object.entries(props)) {
+    const paramName = `p${idx++}`;
+    bindings[paramName] = value;
+    propParts.push(`.property('${key}', ${paramName})`);
+  }
+  const query = `g.V().has('repositoryId', rid).has('id', vid).has('entityType').fold().coalesce(unfold()${propParts.join("")}, addV(vertexLabel).property('id', vid)${propParts.join("")})`;
+  await conn.submit(query, bindings);
+}
+async function upsertRelationship(conn, repositoryId, rel) {
+  const props = relationshipToGremlinProps(repositoryId, rel);
+  const bindings = {
+    relId: rel.id,
+    srcId: rel.sourceEntityId,
+    tgtId: rel.targetEntityId,
+    rid: repositoryId,
+    edgeLabel: rel.relationshipType
+  };
+  const propParts = [];
+  let idx = 0;
+  for (const [key, value] of Object.entries(props)) {
+    const paramName = `p${idx++}`;
+    bindings[paramName] = value;
+    propParts.push(`.property('${key}', ${paramName})`);
+  }
+  const createEdge = `g.V().has('repositoryId', rid).has('id', srcId).has('entityType').addE(edgeLabel).to(g.V().has('repositoryId', rid).has('id', tgtId).has('entityType')).property('id', relId)${propParts.join("")}`;
+  const query = `g.E().has('id', relId).fold().coalesce(unfold()${propParts.join("")}, ${createEdge})`;
+  await conn.submit(query, bindings);
+}
+
+// src/CosmosDbProvider.ts
+var SCHEMA_VERSION = 1;
+var META_VERTEX_ID = "_meta:schema";
+var CosmosDbProvider = class {
+  conn;
+  config;
+  compiler = new GremlinCompiler();
+  constructor(config) {
+    this.config = config;
+    this.conn = new CosmosDbConnection({
+      endpoint: config.endpoint,
+      key: config.key,
+      database: config.database,
+      container: config.container,
+      maxRetries: config.maxRetries,
+      defaultTimeoutMs: config.defaultTimeoutMs,
+      rejectUnauthorized: config.rejectUnauthorized
+    });
+  }
+  // ─── Lifecycle ─────────────────────────────────────────────────────
+  async initialise() {
+    await this.conn.connect();
+  }
+  async dispose() {
+    await this.conn.close();
+  }
+  async ensureSchema() {
+    const restBase = this.getRestEndpoint();
+    const partitionKey = this.config.partitionKey ?? "/repositoryId";
+    let databaseCreated = false;
+    let schemaCreated = false;
+    try {
+      const dbCreated = await cosmosRestPut(
+        restBase,
+        this.config.key,
+        "dbs",
+        "",
+        "dbs",
+        { id: this.config.database },
+        this.config.rejectUnauthorized ?? true
+      );
+      databaseCreated = dbCreated;
+      const containerCreated = await cosmosRestPut(
+        restBase,
+        this.config.key,
+        `dbs/${this.config.database}/colls`,
+        `dbs/${this.config.database}`,
+        "colls",
+        {
+          id: this.config.container,
+          partitionKey: { paths: [partitionKey], kind: "Hash" }
+        },
+        this.config.rejectUnauthorized ?? true
+      );
+      schemaCreated = containerCreated;
+      await this.conn.close();
+      await this.conn.connect();
+      const existing = await this.conn.submit(
+        "g.V().has('id', metaId).hasLabel('_meta').valueMap(true)",
+        { metaId: META_VERTEX_ID }
+      );
+      if (existing.items.length > 0) {
+        const props = existing.items[0];
+        const version = Number(unwrapGremlinValue(props["schemaVersion"]) ?? 0);
+        if (version >= SCHEMA_VERSION && !databaseCreated && !schemaCreated) {
+          return {
+            databaseCreated: false,
+            schemaCreated: false,
+            alreadyUpToDate: true,
+            schemaVersion: SCHEMA_VERSION
+          };
+        }
+        await this.conn.submit(
+          "g.V().has('id', metaId).hasLabel('_meta').property('schemaVersion', ver)",
+          { metaId: META_VERTEX_ID, ver: SCHEMA_VERSION }
+        );
+      } else {
+        await this.conn.submit(
+          "g.addV('_meta').property('id', metaId).property('repositoryId', pk).property('schemaVersion', ver)",
+          { metaId: META_VERTEX_ID, pk: "_system", ver: SCHEMA_VERSION }
+        );
+        schemaCreated = true;
+      }
+      return {
+        databaseCreated,
+        schemaCreated,
+        alreadyUpToDate: !databaseCreated && !schemaCreated,
+        schemaVersion: SCHEMA_VERSION
+      };
+    } catch (err) {
+      throw new ProviderError(
+        `Failed to ensure CosmosDB schema: ${err instanceof Error ? err.message : String(err)}`,
+        "Verify the CosmosDB REST endpoint is accessible and the Gremlin endpoint is reachable."
+      );
+    }
+  }
+  /** Derive the REST endpoint from config — either explicit or from the Gremlin endpoint host. */
+  getRestEndpoint() {
+    if (this.config.restEndpoint) return this.config.restEndpoint.replace(/\/+$/, "");
+    const url = new URL(this.config.endpoint);
+    return `https://${url.hostname}:8081`;
+  }
+  // ─── Repository ────────────────────────────────────────────────────
+  async createRepository(config) {
+    return createRepository(this.conn, config);
+  }
+  async getRepository(repositoryId) {
+    return getRepository(this.conn, repositoryId);
+  }
+  async listRepositories(filter) {
+    return listRepositories(this.conn, filter);
+  }
+  async updateRepository(repositoryId, updates) {
+    return updateRepository(this.conn, repositoryId, updates);
+  }
+  async deleteRepository(repositoryId, onProgress) {
+    return deleteRepository(this.conn, repositoryId, onProgress);
+  }
+  async deleteAllContents(repositoryId, onProgress) {
+    return deleteAllContents(this.conn, repositoryId, onProgress);
+  }
+  async getRepositoryStats(repositoryId) {
+    return getRepositoryStats(this.conn, repositoryId);
+  }
+  // ─── Vocabulary ────────────────────────────────────────────────────
+  async getVocabulary(repositoryId) {
+    return getVocabulary(this.conn, repositoryId);
+  }
+  async saveVocabulary(repositoryId, vocabulary) {
+    return saveVocabulary(this.conn, repositoryId, vocabulary);
+  }
+  async getVocabularyChangeLog(repositoryId, options) {
+    return getVocabularyChangeLog(this.conn, repositoryId, options);
+  }
+  // ─── Entities ──────────────────────────────────────────────────────
+  async createEntity(repositoryId, entity) {
+    return createEntity(this.conn, repositoryId, entity);
+  }
+  async getEntity(repositoryId, entityId) {
+    return getEntity(this.conn, repositoryId, entityId);
+  }
+  async getEntityBySlug(repositoryId, slug) {
+    return getEntityBySlug(this.conn, repositoryId, slug);
+  }
+  async getEntities(repositoryId, entityIds) {
+    return getEntities(this.conn, repositoryId, entityIds);
+  }
+  async updateEntity(repositoryId, entityId, updates) {
+    return updateEntity(this.conn, repositoryId, entityId, updates);
+  }
+  async deleteEntity(repositoryId, entityId) {
+    return deleteEntity(this.conn, repositoryId, entityId);
+  }
+  async deleteEntitiesByType(repositoryId, entityType) {
+    return deleteEntitiesByType(this.conn, repositoryId, entityType);
+  }
+  async findEntities(repositoryId, query) {
+    return findEntities(this.conn, repositoryId, query);
+  }
+  // ─── Relationships ─────────────────────────────────────────────────
+  async createRelationship(repositoryId, relationship) {
+    return createRelationship(this.conn, repositoryId, relationship);
+  }
+  async getRelationship(repositoryId, relationshipId) {
+    return getRelationship(this.conn, repositoryId, relationshipId);
+  }
+  async getEntityRelationships(repositoryId, entityId, options) {
+    return getEntityRelationships(this.conn, repositoryId, entityId, options);
+  }
+  async deleteRelationship(repositoryId, relationshipId) {
+    return deleteRelationship(this.conn, repositoryId, relationshipId);
+  }
+  async deleteRelationshipsByType(repositoryId, relationshipType) {
+    return deleteRelationshipsByType(this.conn, repositoryId, relationshipType);
+  }
+  // ─── Graph Traversal (StorageProvider) ─────────────────────────────
+  async exploreNeighbourhood(repositoryId, entityId, options) {
+    return exploreNeighbourhood(this.conn, repositoryId, entityId, options);
+  }
+  async findPaths(repositoryId, sourceId, targetId, options) {
+    return findPaths(this.conn, repositoryId, sourceId, targetId, options);
+  }
+  // ─── Timeline ──────────────────────────────────────────────────────
+  async getTimeline(repositoryId, entityId, options) {
+    return getTimeline(this.conn, repositoryId, entityId, options);
+  }
+  // ─── Bulk Operations ───────────────────────────────────────────────
+  exportAll(repositoryId) {
+    return exportAll(this.conn, repositoryId);
+  }
+  async importBulk(repositoryId, data, options) {
+    return importBulk(this.conn, repositoryId, data, options);
+  }
+  // ─── GraphTraversalProvider ────────────────────────────────────────
+  getCapabilities() {
+    return {
+      supportsNativeQuery: true,
+      nativeQueryLanguage: "gremlin",
+      maxTraversalDepth: 10,
+      supportsRelationshipPropertyFilters: true,
+      supportsEntityPropertyFilters: true,
+      supportsAggregation: false,
+      supportsRepeat: true,
+      supportsDedup: true,
+      supportsRelationshipSummary: false
+    };
+  }
+  async traverse(repositoryId, spec, compiledQuery) {
+    const startTime = Date.now();
+    const vocabulary = await this.getVocabulary(repositoryId);
+    const compiled = compiledQuery ? { query: compiledQuery, params: {}, estimatedFanOut: 100 } : this.compiler.compile(spec, vocabulary);
+    const scopedQuery = compiled.query.replace(
+      "g.V()",
+      `g.V().has('repositoryId', '${repositoryId}')`
+    );
+    try {
+      const result = await this.conn.submit(scopedQuery, compiled.params);
+      const executionTimeMs = Date.now() - startTime;
+      const entities = [];
+      const relationships = [];
+      const paths = [];
+      if (spec.returnMode === "path") {
+        for (const item of result.items) {
+          const pathData = item;
+          if (pathData.objects) {
+            const pathEntities = [];
+            for (const obj of pathData.objects) {
+              const props = obj;
+              if (props["entityType"]) {
+                pathEntities.push(entityFromGremlin(props));
+              }
+            }
+            if (pathEntities.length > 0) {
+              paths.push({
+                length: pathEntities.length - 1,
+                entities: pathEntities,
+                relationships: []
+              });
+            }
+          }
+        }
+      } else {
+        for (const item of result.items) {
+          const entity = entityFromGremlin(item);
+          entities.push(entity);
+        }
+      }
+      const limit = spec.limit ?? 50;
+      const queryMetadata = {
+        executionTimeMs,
+        resourceCost: result.requestCharge != null ? { units: "RU", value: result.requestCharge } : void 0,
+        compiledQuery: scopedQuery,
+        compiledQueryLanguage: "gremlin",
+        appliedLimits: {
+          maxResults: limit,
+          maxDepth: spec.steps?.length
+        },
+        truncated: entities.length >= limit,
+        truncationReason: entities.length >= limit ? "result_limit" : void 0
+      };
+      return {
+        entities: spec.returnMode === "path" ? [] : entities,
+        relationships: spec.returnMode === "path" || spec.returnMode === "all" ? relationships : void 0,
+        paths: spec.returnMode === "path" ? paths : void 0,
+        total: entities.length + paths.length,
+        returned: entities.length + paths.length,
+        hasMore: entities.length >= limit || paths.length >= limit,
+        queryMetadata
+      };
+    } catch (err) {
+      throw new ProviderError(
+        `Gremlin traversal failed: ${err instanceof Error ? err.message : String(err)}`,
+        "Check the traversal spec and ensure the CosmosDB connection is healthy."
+      );
+    }
+  }
+  async executeNativeQuery(_repositoryId, query, params) {
+    const startTime = Date.now();
+    try {
+      const result = await this.conn.submit(query, params);
+      const executionTimeMs = Date.now() - startTime;
+      const entities = [];
+      for (const item of result.items) {
+        try {
+          const entity = entityFromGremlin(item);
+          if (entity.id) {
+            entities.push(entity);
+          }
+        } catch {
+        }
+      }
+      const queryMetadata = {
+        executionTimeMs,
+        resourceCost: result.requestCharge != null ? { units: "RU", value: result.requestCharge } : void 0,
+        compiledQuery: query,
+        compiledQueryLanguage: "gremlin",
+        appliedLimits: { maxResults: entities.length },
+        truncated: false
+      };
+      return {
+        entities,
+        total: entities.length,
+        returned: entities.length,
+        hasMore: false,
+        queryMetadata
+      };
+    } catch (err) {
+      throw new ProviderError(
+        `Native Gremlin query failed: ${err instanceof Error ? err.message : String(err)}`,
+        "Verify the Gremlin query syntax is valid for CosmosDB."
+      );
+    }
+  }
+};
+function unwrapGremlinValue(val) {
+  if (Array.isArray(val) && val.length > 0) return val[0];
+  return val;
+}
+function cosmosAuthToken(verb, resourceType, resourceLink, date, key) {
+  const payload = `${verb.toLowerCase()}
+${resourceType.toLowerCase()}
+${resourceLink}
+${date.toLowerCase()}
+
+`;
+  const keyBuffer = Buffer.from(key, "base64");
+  const hmac = crypto.createHmac("sha256", keyBuffer);
+  hmac.update(payload);
+  const signature = hmac.digest("base64");
+  return encodeURIComponent(`type=master&ver=1.0&sig=${signature}`);
+}
+async function cosmosRestPut(restBase, key, urlPath, resourceLink, resourceType, body, rejectUnauthorized) {
+  const date = (/* @__PURE__ */ new Date()).toUTCString();
+  const token = cosmosAuthToken("post", resourceType, resourceLink, date, key);
+  const url = `${restBase}/${urlPath}`;
+  const options = {
+    method: "POST",
+    headers: {
+      "Authorization": token,
+      "x-ms-version": "2018-12-31",
+      "x-ms-date": date,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(body)
+  };
+  if (!rejectUnauthorized) {
+    try {
+      options.dispatcher = new (await import("undici")).Agent({
+        connect: { rejectUnauthorized: false }
+      });
+    } catch {
+      process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = "0";
+    }
+  }
+  const response = await fetch(url, options);
+  if (response.status === 201) return true;
+  if (response.status === 409) return false;
+  const text = await response.text();
+  throw new Error(`CosmosDB REST ${response.status}: ${text}`);
+}
+export {
+  CosmosDbConnection,
+  CosmosDbProvider
+};
+//# sourceMappingURL=index.js.map