@utaba/deep-memory-storage-cosmosdb 0.16.0 → 0.18.0

package/dist/index.js

@@ -1,11 +1,22 @@
 // src/CosmosDbProvider.ts
-import crypto from "crypto";
-import { GremlinCompiler, ProviderError, InvalidInputError, isValidUuid, projectEntity, createSafeSink } from "@utaba/deep-memory";
+import {
+  GremlinCompiler,
+  ProviderError,
+  InvalidInputError,
+  isValidUuid,
+  projectEntity,
+  createSafeSink,
+  matchesPropertyFilters as matchesPropertyFilters3
+} from "@utaba/deep-memory";
 
 // src/CosmosDbConnection.ts
 import gremlin from "gremlin";
+
+// src/usage.ts
 import { AsyncLocalStorage } from "async_hooks";
 var usageScope = new AsyncLocalStorage();
+
+// src/CosmosDbConnection.ts
 var CosmosDbConnection = class {
   client = null;
   config;
@@ -101,14 +112,220 @@ function getRetryAfterMs(err, attempt) {
 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;
+  const total = attrs["x-ms-total-request-charge"];
+  if (typeof total === "number") return total;
+  const single = attrs["x-ms-request-charge"];
+  if (typeof single === "number") return single;
+  return void 0;
 }
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// src/cosmos-rest-auth.ts
+import crypto from "crypto";
+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) {
+    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}`);
+}
+
+// src/CosmosDocumentClient.ts
+var CosmosDocumentClient = class {
+  config;
+  fetchImpl;
+  /**
+   * `fetchImpl` is for tests only — production code should pass nothing and
+   * inherit `globalThis.fetch`. Keeping it on the constructor (rather than
+   * stubbing globals) means each test instance is hermetic.
+   */
+  constructor(config, fetchImpl) {
+    this.config = {
+      ...config,
+      maxRetries: config.maxRetries ?? 3,
+      defaultTimeoutMs: config.defaultTimeoutMs ?? 3e4
+    };
+    this.fetchImpl = fetchImpl ?? fetch;
+  }
+  /**
+   * Execute a parameterised Cosmos SQL query against the container's `docs`
+   * resource. Retries on 429/503 with the response's `x-ms-retry-after-ms`
+   * when present, otherwise exponential backoff. RU is accumulated into the
+   * active {@link usageScope}.
+   */
+  async query(sql, parameters, options) {
+    const resourceLink = `dbs/${this.config.database}/colls/${this.config.container}`;
+    const url = `${this.restBase()}/${resourceLink}/docs`;
+    if (!this.config.rejectUnauthorized) {
+      process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = "0";
+    }
+    const body = JSON.stringify({ query: sql, parameters });
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      const date = (/* @__PURE__ */ new Date()).toUTCString();
+      const token = cosmosAuthToken("post", "docs", resourceLink, date, this.config.key);
+      const headers = {
+        "Authorization": token,
+        "x-ms-version": "2018-12-31",
+        "x-ms-date": date,
+        "Content-Type": "application/query+json",
+        "x-ms-documentdb-isquery": "true"
+      };
+      if (options.partitionKey != null) {
+        headers["x-ms-documentdb-partitionkey"] = JSON.stringify([options.partitionKey]);
+      } else {
+        headers["x-ms-documentdb-query-enablecrosspartition"] = "true";
+      }
+      if (options.populateMetrics) {
+        headers["x-ms-documentdb-populatequerymetrics"] = "true";
+      }
+      if (options.continuationToken) {
+        headers["x-ms-continuation"] = options.continuationToken;
+      }
+      const response = await this.fetchImpl(url, { method: "POST", headers, body });
+      if (response.status === 429 || response.status === 503) {
+        if (attempt < this.config.maxRetries) {
+          const waitMs = parseRetryAfterMs(response, attempt);
+          const acc2 = usageScope.getStore();
+          if (acc2) acc2.retries++;
+          await sleep2(waitMs);
+          continue;
+        }
+        const text = await response.text();
+        throw new Error(`CosmosDB Document query ${response.status}: ${text}`);
+      }
+      if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`CosmosDB Document query ${response.status}: ${text}`);
+      }
+      const json = await response.json();
+      const requestCharge = Number(response.headers.get("x-ms-request-charge") ?? "0") || 0;
+      const queryMetrics = response.headers.get("x-ms-documentdb-query-metrics");
+      const continuationToken = response.headers.get("x-ms-continuation");
+      const acc = usageScope.getStore();
+      if (acc) {
+        acc.calls++;
+        acc.ru += requestCharge;
+      }
+      return {
+        documents: json.Documents ?? [],
+        requestCharge,
+        queryMetrics,
+        continuationToken
+      };
+    }
+    throw new Error("CosmosDocumentClient.query: retry loop exhausted without resolution");
+  }
+  /**
+   * Read container metadata (id, partition key, indexing policy). Used by
+   * `ensureSchema()` to warn when externally-provisioned containers have
+   * excluded paths the findEntities SQL needs.
+   */
+  async getContainerProperties() {
+    const resourceLink = `dbs/${this.config.database}/colls/${this.config.container}`;
+    const url = `${this.restBase()}/${resourceLink}`;
+    if (!this.config.rejectUnauthorized) {
+      process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = "0";
+    }
+    const date = (/* @__PURE__ */ new Date()).toUTCString();
+    const token = cosmosAuthToken("get", "colls", resourceLink, date, this.config.key);
+    const response = await this.fetchImpl(url, {
+      method: "GET",
+      headers: {
+        "Authorization": token,
+        "x-ms-version": "2018-12-31",
+        "x-ms-date": date
+      }
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`CosmosDB Document getContainerProperties ${response.status}: ${text}`);
+    }
+    return await response.json();
+  }
+  restBase() {
+    return this.config.restEndpoint.replace(/\/+$/, "");
+  }
+};
+function parseRetryAfterMs(response, attempt) {
+  const header = response.headers.get("x-ms-retry-after-ms");
+  if (header) {
+    const n = Number(header);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return Math.min(500 * Math.pow(2, attempt), 1e4);
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // src/mapping.ts
+var STORED_ENTITY_FIELDS = [
+  "id",
+  "entityType",
+  "entityLabel",
+  "slug",
+  "summary",
+  "properties",
+  "data",
+  "dataFormat",
+  "createdBy",
+  "createdByType",
+  "createdAt",
+  "createdInConversation",
+  "createdFromMessage",
+  "modifiedBy",
+  "modifiedByType",
+  "modifiedAt",
+  "modifiedInConversation",
+  "modifiedFromMessage"
+];
+function buildRepositoryProjectChain() {
+  return [
+    `project('id','repositoryId','repoLabel','description','type','legal','owner','governanceConfig','metadata','createdAt','createdBy')`,
+    `.by(id)`,
+    `.by('repositoryId')`,
+    `.by('repoLabel')`,
+    `.by(coalesce(values('description'), constant('')))`,
+    `.by(coalesce(values('type'), constant('')))`,
+    `.by(coalesce(values('legal'), constant('')))`,
+    `.by(coalesce(values('owner'), constant('')))`,
+    `.by('governanceConfig')`,
+    `.by(coalesce(values('metadata'), constant('')))`,
+    `.by('createdAt')`,
+    `.by('createdBy')`
+  ].join("");
+}
 function unwrap(val) {
   if (Array.isArray(val) && val.length > 0) return val[0];
   return val;
@@ -160,6 +377,54 @@ function entityFromGremlin(props) {
     embedding: embeddingStr ? safeParseJson(embeddingStr, void 0) : void 0
   };
 }
+function pluckDocValue(doc, key) {
+  const arr = doc[key];
+  if (Array.isArray(arr) && arr.length > 0) {
+    const entry = arr[0];
+    if (entry && typeof entry === "object") {
+      return entry["_value"];
+    }
+  }
+  return void 0;
+}
+function pluckDocStr(doc, key) {
+  const v = pluckDocValue(doc, key);
+  return typeof v === "string" ? v : String(v ?? "");
+}
+function pluckDocOptStr(doc, key) {
+  const v = pluckDocValue(doc, key);
+  return v != null && v !== "" ? String(v) : void 0;
+}
+function provenanceFromDocument(doc) {
+  return {
+    createdBy: pluckDocStr(doc, "createdBy"),
+    createdByType: pluckDocStr(doc, "createdByType") || "agent",
+    createdAt: pluckDocStr(doc, "createdAt"),
+    createdInConversation: pluckDocOptStr(doc, "createdInConversation"),
+    createdFromMessage: pluckDocOptStr(doc, "createdFromMessage"),
+    modifiedBy: pluckDocStr(doc, "modifiedBy"),
+    modifiedByType: pluckDocStr(doc, "modifiedByType") || "agent",
+    modifiedAt: pluckDocStr(doc, "modifiedAt"),
+    modifiedInConversation: pluckDocOptStr(doc, "modifiedInConversation"),
+    modifiedFromMessage: pluckDocOptStr(doc, "modifiedFromMessage")
+  };
+}
+function entityFromDocument(doc) {
+  const id = typeof doc["id"] === "string" ? doc["id"] : String(doc["id"] ?? "");
+  const embeddingStr = pluckDocOptStr(doc, "embedding");
+  return {
+    id,
+    slug: pluckDocStr(doc, "slug"),
+    entityType: pluckDocStr(doc, "entityType"),
+    label: pluckDocStr(doc, "entityLabel"),
+    summary: pluckDocOptStr(doc, "summary"),
+    properties: safeParseJson(pluckDocValue(doc, "properties"), {}),
+    data: pluckDocOptStr(doc, "data"),
+    dataFormat: pluckDocOptStr(doc, "dataFormat"),
+    provenance: provenanceFromDocument(doc),
+    embedding: embeddingStr ? safeParseJson(embeddingStr, void 0) : void 0
+  };
+}
 function relationshipFromGremlin(props) {
   const bidir = unwrap(props["bidirectional"]);
   return {
@@ -186,24 +451,6 @@ function repositoryFromGremlin(props) {
     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"]),
@@ -218,9 +465,97 @@ function changeRecordFromGremlin(props) {
     reason: unwrapStr(props["reason"])
   };
 }
-function entityToGremlinProps(repositoryId, entity) {
-  const props = {
-    repositoryId,
+var ABSENT_STRING_SENTINEL = "";
+var SENTINEL_BINDING = "absentSentinel";
+var ENTITY_REQUIRED_SLOTS = [
+  "entityType",
+  "entityLabel",
+  "slug",
+  "properties",
+  "createdBy",
+  "createdByType",
+  "createdAt",
+  "modifiedBy",
+  "modifiedByType",
+  "modifiedAt"
+];
+var ENTITY_OPTIONAL_SLOTS = [
+  "summary",
+  "data",
+  "dataFormat",
+  "embedding",
+  "createdInConversation",
+  "createdFromMessage",
+  "modifiedInConversation",
+  "modifiedFromMessage"
+];
+var RELATIONSHIP_REQUIRED_SLOTS = [
+  "relationshipType",
+  "sourceEntityId",
+  "targetEntityId",
+  "bidirectional",
+  "properties",
+  "createdBy",
+  "createdByType",
+  "createdAt",
+  "modifiedBy",
+  "modifiedByType",
+  "modifiedAt"
+];
+var RELATIONSHIP_OPTIONAL_SLOTS = [
+  "createdInConversation",
+  "createdFromMessage",
+  "modifiedInConversation",
+  "modifiedFromMessage"
+];
+var REPOSITORY_REQUIRED_SLOTS = [
+  "repoLabel",
+  "governanceConfig",
+  "createdAt",
+  "createdBy"
+];
+var REPOSITORY_OPTIONAL_SLOTS = [
+  "description",
+  "type",
+  "legal",
+  "owner",
+  "metadata"
+];
+function buildLadder(required, optional, paramPrefix) {
+  const parts = [];
+  let i = 0;
+  for (const slot of required) {
+    parts.push(`.property('${slot}', ${paramPrefix}${i++})`);
+  }
+  for (const slot of optional) {
+    parts.push(
+      `.choose(__.constant(${paramPrefix}${i}).is(neq(${SENTINEL_BINDING})), __.property('${slot}', ${paramPrefix}${i}), __.identity())`
+    );
+    i++;
+  }
+  return parts.join("");
+}
+function buildLadderBindings(required, optional, paramPrefix, values) {
+  const bindings = {};
+  let i = 0;
+  for (const slot of required) {
+    const v = values[slot];
+    if (v == null) {
+      throw new Error(`Fixed-shape ladder: required slot '${slot}' is null/undefined`);
+    }
+    bindings[`${paramPrefix}${i++}`] = v;
+  }
+  for (const slot of optional) {
+    const v = values[slot];
+    bindings[`${paramPrefix}${i++}`] = v ?? ABSENT_STRING_SENTINEL;
+  }
+  return bindings;
+}
+function buildEntityPropertyLadder() {
+  return buildLadder(ENTITY_REQUIRED_SLOTS, ENTITY_OPTIONAL_SLOTS, "p");
+}
+function entityToLadderBindings(entity) {
+  const bindings = buildLadderBindings(ENTITY_REQUIRED_SLOTS, ENTITY_OPTIONAL_SLOTS, "p", {
     entityType: entity.entityType,
     entityLabel: entity.label,
     slug: entity.slug,
@@ -230,46 +565,120 @@ function entityToGremlinProps(repositoryId, entity) {
     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;
+    modifiedAt: entity.provenance.modifiedAt,
+    summary: entity.summary,
+    data: entity.data,
+    dataFormat: entity.dataFormat,
+    embedding: entity.embedding != null ? JSON.stringify(entity.embedding) : void 0,
+    createdInConversation: entity.provenance.createdInConversation,
+    createdFromMessage: entity.provenance.createdFromMessage,
+    modifiedInConversation: entity.provenance.modifiedInConversation,
+    modifiedFromMessage: entity.provenance.modifiedFromMessage
+  });
+  bindings[SENTINEL_BINDING] = ABSENT_STRING_SENTINEL;
+  return bindings;
+}
+function buildRelationshipPropertyLadder() {
+  return buildLadder(RELATIONSHIP_REQUIRED_SLOTS, RELATIONSHIP_OPTIONAL_SLOTS, "p");
+}
+function relationshipToLadderBindings(rel) {
+  const bindings = buildLadderBindings(
+    RELATIONSHIP_REQUIRED_SLOTS,
+    RELATIONSHIP_OPTIONAL_SLOTS,
+    "p",
+    {
+      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,
+      createdInConversation: rel.provenance.createdInConversation,
+      createdFromMessage: rel.provenance.createdFromMessage,
+      modifiedInConversation: rel.provenance.modifiedInConversation,
+      modifiedFromMessage: rel.provenance.modifiedFromMessage
+    }
+  );
+  bindings[SENTINEL_BINDING] = ABSENT_STRING_SENTINEL;
+  return bindings;
+}
+function buildRepositoryPropertyLadder() {
+  return buildLadder(REPOSITORY_REQUIRED_SLOTS, REPOSITORY_OPTIONAL_SLOTS, "p");
+}
+function repositoryConfigToLadderBindings(config) {
+  const bindings = buildLadderBindings(
+    REPOSITORY_REQUIRED_SLOTS,
+    REPOSITORY_OPTIONAL_SLOTS,
+    "p",
+    {
+      repoLabel: config.label,
+      governanceConfig: JSON.stringify(config.governanceConfig),
+      createdAt: config.createdAt,
+      createdBy: config.createdBy,
+      description: config.description,
+      type: config.type,
+      legal: config.legal,
+      owner: config.owner,
+      metadata: config.metadata != null ? JSON.stringify(config.metadata) : void 0
+    }
+  );
+  bindings[SENTINEL_BINDING] = ABSENT_STRING_SENTINEL;
+  return bindings;
 }
 
 // src/queries/repository.ts
 import { DuplicateRepositoryError, RepositoryNotFoundError } from "@utaba/deep-memory";
 var REPO_LABEL = "_repository";
+var REPOSITORY_INDEX_VERTEX_ID = "_repository_index";
+var REPOSITORY_INDEX_PARTITION = "_index";
+var REPOSITORY_INDEX_LABEL = "_repository_index";
 function repoVertexId(repositoryId) {
   return `repo:${repositoryId}`;
 }
+async function ensureRepositoryIndex(conn) {
+  const existing = await conn.submit(
+    "g.V().has('repositoryId', pk).hasId(sid).count()",
+    { pk: REPOSITORY_INDEX_PARTITION, sid: REPOSITORY_INDEX_VERTEX_ID }
+  );
+  if (Number(existing.items[0] ?? 0) > 0) {
+    return null;
+  }
+  const scan = await conn.submit(
+    "g.V().hasLabel('_repository').values('repositoryId')",
+    {}
+  );
+  const ids = scan.items.map((item) => typeof item === "string" ? item : String(item ?? "")).filter((id) => id.length > 0);
+  await conn.submit(
+    "g.addV('" + REPOSITORY_INDEX_LABEL + "').property('id', sid).property('repositoryId', pk).property('repositoryIds', initial)",
+    {
+      pk: REPOSITORY_INDEX_PARTITION,
+      sid: REPOSITORY_INDEX_VERTEX_ID,
+      initial: JSON.stringify(ids)
+    }
+  );
+  return ids.length;
+}
+async function readRepositoryIndex(conn) {
+  const result = await conn.submit(
+    "g.V().has('repositoryId', pk).hasId(sid).values('repositoryIds')",
+    { pk: REPOSITORY_INDEX_PARTITION, sid: REPOSITORY_INDEX_VERTEX_ID }
+  );
+  if (result.items.length === 0) return [];
+  const raw = result.items[0];
+  const json = typeof raw === "string" ? raw : String(raw ?? "");
+  if (!json) return [];
+  try {
+    const parsed = JSON.parse(json);
+    return Array.isArray(parsed) ? parsed.filter((id) => typeof id === "string") : [];
+  } catch {
+    return [];
+  }
+}
 function propertyChain(bindings, props, startIndex) {
   const parts = [];
   let idx = startIndex;
@@ -281,33 +690,27 @@ function propertyChain(bindings, props, startIndex) {
   }
   return { chain: parts.join(""), nextIndex: idx };
 }
+var REPOSITORY_CREATE_QUERY = `g.addV('${REPO_LABEL}').property('id', vid).property('repositoryId', rid)${buildRepositoryPropertyLadder()}.sideEffect(__.V().has('repositoryId', pk).hasId(sid).property('repositoryIds', updatedIndex))`;
 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 }
+    "g.V().has('repositoryId', rid).hasId(vid).has('label', lbl).count()",
+    { vid: vertexId, rid: config.repositoryId, lbl: REPO_LABEL }
   );
   if (existing.items.length > 0 && Number(existing.items[0]) > 0) {
     throw new DuplicateRepositoryError(config.repositoryId);
   }
+  const currentIds = await readRepositoryIndex(conn);
+  const updatedIds = currentIds.includes(config.repositoryId) ? currentIds : [...currentIds, 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
+    rid: config.repositoryId,
+    pk: REPOSITORY_INDEX_PARTITION,
+    sid: REPOSITORY_INDEX_VERTEX_ID,
+    updatedIndex: JSON.stringify(updatedIds),
+    ...repositoryConfigToLadderBindings(config)
   };
-  const { chain } = propertyChain(bindings, props, 0);
-  const query = `g.addV('${REPO_LABEL}').property('id', vid).property('repositoryId', rid)${chain}`;
-  await conn.submit(query, bindings);
+  await conn.submit(REPOSITORY_CREATE_QUERY, bindings);
   return {
     repositoryId: config.repositoryId,
     type: config.type,
@@ -322,9 +725,10 @@ async function createRepository(conn, config) {
   };
 }
 async function getRepository(conn, repositoryId) {
+  const projection = buildRepositoryProjectChain();
   const result = await conn.submit(
-    "g.V().has('id', vid).hasLabel('_repository').valueMap(true)",
-    { vid: repoVertexId(repositoryId) }
+    `g.V().has('repositoryId', rid).hasId(vid).hasLabel('_repository').${projection}`,
+    { vid: repoVertexId(repositoryId), rid: repositoryId }
   );
   if (result.items.length === 0) return null;
   return repositoryFromGremlin(result.items[0]);
@@ -332,27 +736,32 @@ async function getRepository(conn, repositoryId) {
 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 repositoryIds = await readRepositoryIndex(conn);
+  if (repositoryIds.length === 0) {
+    return { items: [], total: 0, hasMore: false, limit, offset };
   }
-  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 hydrated = await Promise.all(
+    repositoryIds.map((rid) => getRepository(conn, rid))
   );
-  const items = dataResult.items.map(repositorySummaryFromGremlin);
+  let summaries = hydrated.filter((r) => r != null).map((r) => {
+    const summary = {
+      repositoryId: r.repositoryId,
+      label: r.label,
+      governanceConfig: r.governanceConfig
+    };
+    if (r.type !== void 0) summary.type = r.type;
+    if (r.description !== void 0) summary.description = r.description;
+    return summary;
+  });
+  if (filter?.type) {
+    summaries = summaries.filter((s) => s.type === filter.type);
+  }
+  const total = summaries.length;
+  const items = summaries.slice(offset, offset + limit);
   return {
     items,
     total,
-    hasMore: offset + limit < total,
+    hasMore: offset + items.length < total,
     limit,
     offset
   };
@@ -361,7 +770,7 @@ 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 bindings = { vid: vertexId, rid: repositoryId };
   const props = {};
   if (updates.label !== void 0) props["repoLabel"] = updates.label;
   if (updates.description !== void 0) props["description"] = updates.description;
@@ -375,7 +784,7 @@ async function updateRepository(conn, repositoryId, updates) {
   }
   if (Object.keys(props).length === 0) return existing;
   const { chain } = propertyChain(bindings, props, 0);
-  const query = `g.V().has('id', vid).hasLabel('_repository')${chain}`;
+  const query = `g.V().has('repositoryId', rid).hasId(vid).hasLabel('_repository')${chain}`;
   await conn.submit(query, bindings);
   return await getRepository(conn, repositoryId);
 }
@@ -421,6 +830,18 @@ async function deleteRepository(conn, repositoryId, onProgress) {
     await onProgress?.({ entitiesDeleted, relationshipsDeleted, totalEntities, totalRelationships });
     if (remainingCount === 0) break;
   }
+  const currentIds = await readRepositoryIndex(conn);
+  const updatedIds = currentIds.filter((id) => id !== repositoryId);
+  if (updatedIds.length !== currentIds.length) {
+    await conn.submit(
+      "g.V().has('repositoryId', pk).hasId(sid).property('repositoryIds', updatedIndex)",
+      {
+        pk: REPOSITORY_INDEX_PARTITION,
+        sid: REPOSITORY_INDEX_VERTEX_ID,
+        updatedIndex: JSON.stringify(updatedIds)
+      }
+    );
+  }
 }
 async function deleteAllContents(conn, repositoryId, onProgress) {
   const entityCountResult = await conn.submit(
@@ -517,33 +938,39 @@ async function getRepositoryStats(conn, repositoryId) {
 function vocabVertexId(repositoryId) {
   return `vocab:${repositoryId}`;
 }
+var EMPTY_VOCABULARY = () => ({
+  version: "0.0.0",
+  lastModified: (/* @__PURE__ */ new Date()).toISOString(),
+  modifiedBy: "system",
+  entityTypes: [],
+  relationshipTypes: []
+});
 async function getVocabulary(conn, repositoryId) {
   const result = await conn.submit(
-    "g.V().has('id', vid).hasLabel('_vocabulary').valueMap(true)",
-    { vid: vocabVertexId(repositoryId) }
+    "g.V().has('repositoryId', rid).hasId(vid).hasLabel('_vocabulary').values('vocabulary').limit(1)",
+    { vid: vocabVertexId(repositoryId), rid: repositoryId }
   );
-  if (result.items.length === 0) {
-    return {
-      version: "0.0.0",
-      lastModified: (/* @__PURE__ */ new Date()).toISOString(),
-      modifiedBy: "system",
-      entityTypes: [],
-      relationshipTypes: []
-    };
+  if (result.items.length === 0) return EMPTY_VOCABULARY();
+  const raw = result.items[0];
+  const json = typeof raw === "string" ? raw : String(raw ?? "");
+  if (!json) return EMPTY_VOCABULARY();
+  try {
+    return JSON.parse(json);
+  } catch {
+    return EMPTY_VOCABULARY();
   }
-  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 }
+    "g.V().has('repositoryId', rid).hasId(vid).hasLabel('_vocabulary').count()",
+    { vid, rid: repositoryId }
   );
   if (Number(existing.items[0] ?? 0) > 0) {
     await conn.submit(
-      "g.V().has('id', vid).hasLabel('_vocabulary').property('vocabulary', vocabJson)",
-      { vid, vocabJson }
+      "g.V().has('repositoryId', rid).hasId(vid).hasLabel('_vocabulary').property('vocabulary', vocabJson)",
+      { vid, rid: repositoryId, vocabJson }
     );
   } else {
     await conn.submit(
@@ -555,66 +982,68 @@ async function saveVocabulary(conn, repositoryId, vocabulary) {
 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 [countResult, dataResult] = await Promise.all([
+    conn.submit(
+      "g.V().has('repositoryId', rid).hasLabel('_vocabularyChangeLog').count()",
+      { rid: repositoryId }
+    ),
+    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 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,
+    hasMore: offset + items.length < total,
     limit,
     offset
   };
 }
 
 // src/queries/entity.ts
-import { DuplicateEntityError } from "@utaba/deep-memory";
+import {
+  DuplicateEntityError,
+  EntityNotFoundError,
+  buildVertexProjectChain,
+  matchesPropertyFilters
+} from "@utaba/deep-memory";
+var DUPLICATE_SENTINEL = "__duplicate";
+var ENTITY_CREATE_QUERY = `g.V().has('repositoryId', rid).hasId(vid).fold().coalesce(unfold().constant('${DUPLICATE_SENTINEL}'),addV(vertexLabel).property('id', vid).property('repositoryId', rid)${buildEntityPropertyLadder()})`;
 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) {
+  const bindings = {
+    rid: repositoryId,
+    vid: entity.id,
+    vertexLabel: entity.entityType,
+    ...entityToLadderBindings(entity)
+  };
+  const result = await conn.submit(ENTITY_CREATE_QUERY, bindings);
+  if (result.items[0] === DUPLICATE_SENTINEL) {
     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) {
+async function getEntity(conn, repositoryId, entityId, options) {
+  const projection = buildVertexProjectChain({ withEmbedding: options?.loadEmbeddings });
   const result = await conn.submit(
-    "g.V().has('repositoryId', rid).has('id', eid).has('entityType').valueMap(true)",
+    `g.V().has('repositoryId', rid).hasId(eid).has('entityType').${projection}`,
     { rid: repositoryId, eid: entityId }
   );
   if (result.items.length === 0) return null;
   return entityFromGremlin(result.items[0]);
 }
-async function getEntityBySlug(conn, repositoryId, slug) {
+async function getEntityBySlug(conn, repositoryId, slug, options) {
+  const projection = buildVertexProjectChain({ withEmbedding: options?.loadEmbeddings });
   const result = await conn.submit(
-    "g.V().has('repositoryId', rid).has('slug', slugVal).has('entityType').valueMap(true)",
+    `g.V().has('repositoryId', rid).has('slug', slugVal).has('entityType').${projection}`,
     { rid: repositoryId, slugVal: slug }
   );
   if (result.items.length === 0) return null;
   return entityFromGremlin(result.items[0]);
 }
-async function getEntities(conn, repositoryId, entityIds) {
+async function getEntities(conn, repositoryId, entityIds, options) {
   if (entityIds.length === 0) return /* @__PURE__ */ new Map();
   const bindings = { rid: repositoryId };
   const idParams = [];
@@ -624,8 +1053,9 @@ async function getEntities(conn, repositoryId, entityIds) {
     idParams.push(paramName);
   });
   const withinClause = `within(${idParams.join(", ")})`;
+  const projection = buildVertexProjectChain({ withEmbedding: options?.loadEmbeddings });
   const result = await conn.submit(
-    `g.V().has('repositoryId', rid).has('id', ${withinClause}).has('entityType').valueMap(true)`,
+    `g.V().has('repositoryId', rid).hasId(${withinClause}).has('entityType').${projection}`,
     bindings
   );
   const map = /* @__PURE__ */ new Map();
@@ -663,132 +1093,124 @@ async function updateEntity(conn, repositoryId, entityId, updates) {
   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);
+  const projection = buildVertexProjectChain();
+  const query = `g.V().has('repositoryId', rid).hasId(eid).has('entityType')${propParts.join("")}.${projection}`;
+  const result = await conn.submit(query, bindings);
+  if (result.items.length === 0) {
+    throw new EntityNotFoundError(entityId);
+  }
+  return entityFromGremlin(result.items[0]);
 }
 async function deleteEntity(conn, repositoryId, entityId) {
   await conn.submit(
-    "g.V().has('repositoryId', rid).has('id', eid).has('entityType').drop()",
+    "g.V().has('repositoryId', rid).hasId(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()",
+  const result = await conn.submit(
+    "g.V().has('repositoryId', rid).has('entityType', etype).aggregate('found').by('id').drop().cap('found')",
     { 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 };
+  const bucket = result.items[0];
+  const deletedEntities = Array.isArray(bucket) ? bucket.length : 0;
+  return { deletedEntities, deletedRelationships: void 0 };
 }
-async function findEntities(conn, repositoryId, query) {
-  const bindings = { rid: repositoryId };
-  let filterClause = ".has('repositoryId', rid).has('entityType')";
+function sqlPath(key) {
+  return `c.${key}[0]._value`;
+}
+function buildWhereClause(query, repositoryId) {
+  const params = [{ name: "@rid", value: repositoryId }];
+  const predicates = ["c.repositoryId = @rid", "IS_DEFINED(c.entityType)"];
   if (query.entityTypes && query.entityTypes.length > 0) {
-    const typeParams = [];
+    const typeParamNames = [];
     query.entityTypes.forEach((t, i) => {
-      const paramName = `etype${i}`;
-      bindings[paramName] = t;
-      typeParams.push(paramName);
+      const name = `@etype${i}`;
+      params.push({ name, value: t });
+      typeParamNames.push(name);
     });
-    filterClause += `.has('entityType', within(${typeParams.join(", ")}))`;
-  }
-  const hasPropertyFilter = query.properties != null && Object.keys(query.properties).length > 0;
-  const needsClientFilter = Boolean(query.searchTerm) || hasPropertyFilter;
-  if (needsClientFilter) {
-    const dataResult2 = await conn.submit(
-      `g.V()${filterClause}.valueMap(true)`,
-      bindings
+    predicates.push(`${sqlPath("entityType")} IN (${typeParamNames.join(", ")})`);
+  }
+  if (query.searchTerm) {
+    params.push({ name: "@term", value: query.searchTerm });
+    predicates.push(
+      `(CONTAINS(${sqlPath("entityLabel")}, @term, true) OR CONTAINS(${sqlPath("slug")}, @term, true) OR CONTAINS(${sqlPath("summary")}, @term, true))`
     );
-    let items2 = dataResult2.items.map(entityFromGremlin);
-    if (query.searchTerm) {
-      const term = query.searchTerm.toLowerCase();
-      items2 = items2.filter(
-        (e) => e.label.toLowerCase().includes(term) || e.slug.toLowerCase().includes(term) || e.summary != null && e.summary.toLowerCase().includes(term)
-      );
-    }
-    if (hasPropertyFilter) {
-      items2 = items2.filter((entity) => {
-        for (const [key, value] of Object.entries(query.properties)) {
-          if (entity.properties[key] !== value) return false;
-        }
-        return true;
-      });
+  }
+  if (query.properties != null) {
+    let i = 0;
+    for (const [key, value] of Object.entries(query.properties)) {
+      const fragment = JSON.stringify({ [key]: value }).slice(1, -1);
+      const name = `@kv${i++}`;
+      params.push({ name, value: fragment });
+      predicates.push(`CONTAINS(${sqlPath("properties")}, ${name}, false)`);
     }
-    const total2 = items2.length;
-    const paged = items2.slice(query.offset, query.offset + query.limit);
-    return {
-      items: paged,
-      total: total2,
-      hasMore: query.offset + query.limit < total2,
-      limit: query.limit,
-      offset: query.offset
-    };
   }
-  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
-  );
-  const items = dataResult.items.map(entityFromGremlin);
+  return { sqlWhere: `WHERE ${predicates.join(" AND ")}`, params };
+}
+function buildSelectClause(loadEmbeddings) {
+  const fields = ["c.id", ...STORED_ENTITY_FIELDS.filter((f) => f !== "id").map((f) => `c.${f}`)];
+  if (loadEmbeddings) fields.push("c.embedding");
+  return `SELECT ${fields.join(", ")}`;
+}
+async function findEntities(docClient, repositoryId, query, options) {
+  const { sqlWhere, params } = buildWhereClause(query, repositoryId);
+  const dataParams = [
+    ...params,
+    { name: "@off", value: query.offset },
+    { name: "@lim", value: query.limit }
+  ];
+  const selectClause = buildSelectClause(options?.loadEmbeddings === true);
+  const dataSql = `${selectClause} FROM c ${sqlWhere} ORDER BY c.id OFFSET @off LIMIT @lim`;
+  const countSql = `SELECT VALUE COUNT(1) FROM c ${sqlWhere}`;
+  const skipCount = query.properties != null && Object.keys(query.properties).length > 0;
+  const [dataResult, countResult] = await Promise.all([
+    docClient.query(dataSql, dataParams, {
+      partitionKey: repositoryId
+    }),
+    skipCount ? Promise.resolve(null) : docClient.query(countSql, params, { partitionKey: repositoryId })
+  ]);
+  let items = dataResult.documents.map(entityFromDocument);
+  if (query.properties != null && Object.keys(query.properties).length > 0) {
+    const filters = Object.entries(query.properties).map(
+      ([key, value]) => ({ key, operator: "eq", value })
+    );
+    items = items.filter((entity) => matchesPropertyFilters(entity.properties, filters));
+  }
+  const total = countResult && countResult.documents.length > 0 ? Number(countResult.documents[0]) : void 0;
+  const hasMore = total != null ? query.offset + items.length < total : items.length === query.limit;
   return {
     items,
     total,
-    hasMore: query.offset + query.limit < total,
+    hasMore,
     limit: query.limit,
     offset: query.offset
   };
 }
 
 // src/queries/relationship.ts
-import { DuplicateRelationshipError, matchesPropertyFilters } from "@utaba/deep-memory";
+import { DuplicateRelationshipError, matchesPropertyFilters as matchesPropertyFilters2, buildEdgeProjectChain } from "@utaba/deep-memory";
+var DUPLICATE_SENTINEL2 = "__duplicate";
+var RELATIONSHIP_CREATE_QUERY = `g.E().has('repositoryId', rid).hasId(relId).fold().coalesce(unfold().constant('${DUPLICATE_SENTINEL2}'),g.V().has('repositoryId', rid).hasId(srcId).has('entityType').addE(edgeLabel).to(g.V().has('repositoryId', rid).hasId(tgtId).has('entityType')).property('id', relId).property('repositoryId', rid)${buildRelationshipPropertyLadder()})`;
 async function createRelationship(conn, repositoryId, relationship) {
-  const existing = await conn.submit(
-    "g.E().has('repositoryId', rid).has('id', relId).count()",
-    { rid: repositoryId, relId: relationship.id }
-  );
-  if (Number(existing.items[0] ?? 0) > 0) {
-    throw new DuplicateRelationshipError(relationship.id);
-  }
-  const props = relationshipToGremlinProps(repositoryId, relationship);
   const bindings = {
+    rid: repositoryId,
     relId: relationship.id,
     srcId: relationship.sourceEntityId,
     tgtId: relationship.targetEntityId,
-    rid: repositoryId,
-    edgeLabel: relationship.relationshipType
+    edgeLabel: relationship.relationshipType,
+    ...relationshipToLadderBindings(relationship)
   };
-  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 result = await conn.submit(RELATIONSHIP_CREATE_QUERY, bindings);
+  if (result.items[0] === DUPLICATE_SENTINEL2) {
+    throw new DuplicateRelationshipError(relationship.id);
   }
-  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 projection = buildEdgeProjectChain();
   const result = await conn.submit(
-    "g.E().has('id', relId).has('repositoryId', rid).valueMap(true)",
+    `g.E().hasId(relId).has('repositoryId', rid).${projection}`,
     { relId: relationshipId, rid: repositoryId }
   );
   if (result.items.length === 0) return null;
@@ -798,21 +1220,22 @@ async function getEntityRelationships(conn, repositoryId, entityId, options) {
   const limit = options?.limit ?? 50;
   const offset = options?.offset ?? 0;
   const direction = options?.direction ?? "both";
-  const bindings = {
+  const hasPropertyFilters = options?.propertyFilters != null && options.propertyFilters.length > 0;
+  const baseBindings = {
     rid: repositoryId,
     eid: entityId
   };
   let edgeTraversal;
   switch (direction) {
-    case "outbound":
-      edgeTraversal = "g.V().has('repositoryId', rid).has('id', eid).has('entityType').outE()";
+    case "out":
+      edgeTraversal = "g.V().has('repositoryId', rid).hasId(eid).has('entityType').outE()";
       break;
-    case "inbound":
-      edgeTraversal = "g.V().has('repositoryId', rid).has('id', eid).has('entityType').inE()";
+    case "in":
+      edgeTraversal = "g.V().has('repositoryId', rid).hasId(eid).has('entityType').inE()";
       break;
     case "both":
     default:
-      edgeTraversal = "g.V().has('repositoryId', rid).has('id', eid).has('entityType').bothE()";
+      edgeTraversal = "g.V().has('repositoryId', rid).hasId(eid).has('entityType').bothE()";
       break;
   }
   let typeFilter = "";
@@ -820,218 +1243,63 @@ async function getEntityRelationships(conn, repositoryId, entityId, options) {
     const typeParams = [];
     options.relationshipTypes.forEach((t, i) => {
       const paramName = `rtype${i}`;
-      bindings[paramName] = t;
+      baseBindings[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))`;
+  if (direction === "out") {
+    unionQuery = `g.V().has('repositoryId', rid).hasId(eid).has('entityType').union(outE()${typeFilter}, inE()${typeFilter}.has('bidirectional', true))`;
+  } else if (direction === "in") {
+    unionQuery = `g.V().has('repositoryId', rid).hasId(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));
-  }
+  const projection = buildEdgeProjectChain();
+  const dataBindings = { ...baseBindings, rangeStart: offset, rangeEnd: offset + limit };
+  const [countResult, dataResult] = await Promise.all([
+    hasPropertyFilters ? Promise.resolve(null) : conn.submit(`${baseQuery}.dedup().count()`, baseBindings),
+    conn.submit(
+      `${baseQuery}.dedup().range(rangeStart, rangeEnd).${projection}`,
+      dataBindings
+    )
+  ]);
+  const rawItems = dataResult.items;
+  let items = rawItems.map(relationshipFromGremlin);
+  if (hasPropertyFilters) {
+    items = items.filter((rel) => matchesPropertyFilters2(rel.properties, options.propertyFilters));
+  }
+  const total = countResult ? Number(countResult.items[0] ?? 0) : void 0;
+  const hasMore = total != null ? offset + rawItems.length < total : rawItems.length === limit;
   return {
     items,
     total,
-    hasMore: offset + limit < total,
+    hasMore,
     limit,
     offset
   };
 }
 async function deleteRelationship(conn, repositoryId, relationshipId) {
   await conn.submit(
-    "g.E().has('id', relId).has('repositoryId', rid).drop()",
+    "g.E().hasId(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()",
+  const result = await conn.submit(
+    "g.E().has('repositoryId', rid).hasLabel(rtype).aggregate('found').by('id').drop().cap('found')",
     { 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 }
-    );
-  }
+  const bucket = result.items[0];
+  const deletedRelationships = Array.isArray(bucket) ? bucket.length : 0;
   return { deletedRelationships };
 }
 
-// src/queries/traversal.ts
-import { matchesPropertyFilters as matchesPropertyFilters2 } from "@utaba/deep-memory";
-async function exploreNeighborhood(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();
-    const layerCache = /* @__PURE__ */ new Map();
-    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)) continue;
-        let entity = layerCache.get(connectedId);
-        if (entity === void 0) {
-          const loaded = await getEntityLight(conn, repositoryId, connectedId);
-          if (loaded && (!options.entityTypes || options.entityTypes.length === 0 || options.entityTypes.includes(loaded.entityType))) {
-            entity = loaded;
-          } else {
-            entity = null;
-          }
-          layerCache.set(connectedId, entity);
-          if (entity) nextFrontier.add(connectedId);
-        }
-        if (!entity) continue;
-        layer[relType].entities.push(entity);
-        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);
-    }
-    for (const id of nextFrontier) {
-      visited.add(id);
-    }
-    frontier = nextFrontier;
-    if (frontier.size === 0) break;
-  }
-  return { centerId: 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')",
+    "g.V().has('repositoryId', rid).hasId(eid).has('entityType').valueMap('createdAt', 'modifiedAt')",
     { rid: repositoryId, eid: entityId }
   );
   if (entityResult.items.length > 0) {
@@ -1054,7 +1322,7 @@ async function getTimeline(conn, repositoryId, entityId, options) {
     }
   }
   const relResult = await conn.submit(
-    "g.V().has('repositoryId', rid).has('id', eid).has('entityType').bothE().valueMap('id', 'createdAt')",
+    "g.V().has('repositoryId', rid).hasId(eid).has('entityType').bothE().valueMap('id', 'createdAt')",
     { rid: repositoryId, eid: entityId }
   );
   for (const item of relResult.items) {
@@ -1283,7 +1551,7 @@ async function runTaskWithUsage(fn) {
     }
   }
 }
-function sleep2(ms) {
+function sleep3(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 async function runAdaptive(items, controller, fn) {
@@ -1308,7 +1576,7 @@ async function runAdaptive(items, controller, fn) {
         const slotsAvailable = inFlight < controller.getConcurrency();
         if (cooldownRemaining <= 0 && slotsAvailable) break;
         if (cooldownRemaining > 0) {
-          await Promise.race([sleep2(cooldownRemaining), gate.promise]);
+          await Promise.race([sleep3(cooldownRemaining), gate.promise]);
         } else {
           await gate.promise;
         }
@@ -1482,88 +1750,79 @@ async function importBulk(conn, repositoryId, data, options) {
   }
   return { entitiesImported, relationshipsImported, errors };
 }
+var ENTITY_LADDER_CHAIN = buildEntityPropertyLadder();
+var RELATIONSHIP_LADDER_CHAIN = buildRelationshipPropertyLadder();
+var INSERT_ENTITY_QUERY = `g.addV(vertexLabel).property('id', vid).property('repositoryId', rid)${ENTITY_LADDER_CHAIN}`;
+var INSERT_RELATIONSHIP_QUERY = `g.V().has('repositoryId', rid).hasId(srcId).has('entityType').addE(edgeLabel).to(g.V().has('repositoryId', rid).hasId(tgtId).has('entityType')).property('id', relId).property('repositoryId', rid)${RELATIONSHIP_LADDER_CHAIN}`;
+var UPSERT_ENTITY_QUERY = `g.V().has('repositoryId', rid).hasId(vid).has('entityType').fold().coalesce(unfold()${ENTITY_LADDER_CHAIN}, addV(vertexLabel).property('id', vid).property('repositoryId', rid)${ENTITY_LADDER_CHAIN})`;
+var UPSERT_RELATIONSHIP_QUERY = `g.E().has('repositoryId', rid).hasId(relId).fold().coalesce(unfold()${RELATIONSHIP_LADDER_CHAIN}, g.V().has('repositoryId', rid).hasId(srcId).has('entityType').addE(edgeLabel).to(g.V().has('repositoryId', rid).hasId(tgtId).has('entityType')).property('id', relId).property('repositoryId', rid)${RELATIONSHIP_LADDER_CHAIN})`;
 async function insertEntity(conn, repositoryId, entity) {
-  const props = entityToGremlinProps(repositoryId, entity);
   const bindings = {
+    rid: repositoryId,
     vid: entity.id,
-    vertexLabel: entity.entityType
+    vertexLabel: entity.entityType,
+    ...entityToLadderBindings(entity)
   };
-  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);
+  await conn.submit(INSERT_ENTITY_QUERY, bindings);
 }
 async function insertRelationship(conn, repositoryId, rel) {
-  const props = relationshipToGremlinProps(repositoryId, rel);
   const bindings = {
+    rid: repositoryId,
     relId: rel.id,
     srcId: rel.sourceEntityId,
     tgtId: rel.targetEntityId,
-    rid: repositoryId,
-    edgeLabel: rel.relationshipType
+    edgeLabel: rel.relationshipType,
+    ...relationshipToLadderBindings(rel)
   };
-  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);
+  await conn.submit(INSERT_RELATIONSHIP_QUERY, bindings);
 }
 async function upsertEntity(conn, repositoryId, entity) {
-  const props = entityToGremlinProps(repositoryId, entity);
   const bindings = {
-    vid: entity.id,
     rid: repositoryId,
-    vertexLabel: entity.entityType
+    vid: entity.id,
+    vertexLabel: entity.entityType,
+    ...entityToLadderBindings(entity)
   };
-  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);
+  await conn.submit(UPSERT_ENTITY_QUERY, bindings);
 }
 async function upsertRelationship(conn, repositoryId, rel) {
-  const props = relationshipToGremlinProps(repositoryId, rel);
   const bindings = {
+    rid: repositoryId,
     relId: rel.id,
     srcId: rel.sourceEntityId,
     tgtId: rel.targetEntityId,
-    rid: repositoryId,
-    edgeLabel: rel.relationshipType
+    edgeLabel: rel.relationshipType,
+    ...relationshipToLadderBindings(rel)
   };
-  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('repositoryId', rid).has('id', relId).fold().coalesce(unfold()${propParts.join("")}, ${createEdge})`;
-  await conn.submit(query, bindings);
+  await conn.submit(UPSERT_RELATIONSHIP_QUERY, bindings);
 }
 
 // src/CosmosDbProvider.ts
 var PROVIDER_NAME = "cosmosdb";
 var SCHEMA_VERSION = 1;
 var META_VERTEX_ID = "_meta:schema";
+var GUARDED_INDEX_PATHS = [
+  "/entityLabel",
+  "/slug",
+  "/summary",
+  "/entityType",
+  "/properties",
+  "/repositoryId"
+];
+var VOCABULARY_CACHE_TTL_MS = 6e4;
 var CosmosDbProvider = class {
   conn;
+  docClient;
   config;
   compiler = new GremlinCompiler();
   reportUsage;
+  /**
+   * Per-process vocabulary cache, keyed by repositoryId. Read lazily by
+   * `traverseImpl` via `getVocabularyCached`; invalidated on `saveVocabulary`.
+   * Each provider instance owns its own cache so isolated test providers do
+   * not share state.
+   */
+  vocabularyCache = /* @__PURE__ */ new Map();
   constructor(config) {
     this.config = config;
     this.reportUsage = createSafeSink(config.reportUsage);
@@ -1576,6 +1835,15 @@ var CosmosDbProvider = class {
       defaultTimeoutMs: config.defaultTimeoutMs,
       rejectUnauthorized: config.rejectUnauthorized
     });
+    this.docClient = new CosmosDocumentClient({
+      restEndpoint: this.getRestEndpoint(),
+      key: config.key,
+      database: config.database,
+      container: config.container,
+      rejectUnauthorized: config.rejectUnauthorized ?? true,
+      maxRetries: config.maxRetries,
+      defaultTimeoutMs: config.defaultTimeoutMs
+    });
   }
   /**
    * Run the given operation inside an async-local usage scope. While the
@@ -1669,24 +1937,18 @@ var CosmosDbProvider = class {
       await this.conn.close();
       await this.conn.connect();
       const existing = await this.conn.submit(
-        "g.V().has('id', metaId).hasLabel('_meta').valueMap(true)",
+        "g.V().hasId(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
-          };
+        if (version < SCHEMA_VERSION || databaseCreated || schemaCreated) {
+          await this.conn.submit(
+            "g.V().hasId(metaId).hasLabel('_meta').property('schemaVersion', ver)",
+            { metaId: META_VERTEX_ID, ver: 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)",
@@ -1694,6 +1956,8 @@ var CosmosDbProvider = class {
         );
         schemaCreated = true;
       }
+      await ensureRepositoryIndex(this.conn);
+      await this.runIndexingPolicyDiagnostic();
       return {
         databaseCreated,
         schemaCreated,
@@ -1707,6 +1971,51 @@ var CosmosDbProvider = class {
       );
     }
   }
+  /**
+   * Step E — verify the container's indexing policy covers every path that
+   * the SQL `findEntities` rewrite hits. The probe (2026-05-26) confirmed
+   * code-managed containers get the Cosmos default policy (everything
+   * indexed). This guard is for operator-facing protection: externally
+   * provisioned containers (ARM/Bicep) can have `excludedPaths` set, which
+   * would force `findEntities` to scan rather than index-lookup.
+   *
+   * Single GET against the colls resource, minimal RU. Never fails
+   * `ensureSchema` — a diagnostic must not break provisioning.
+   */
+  async runIndexingPolicyDiagnostic() {
+    let policy;
+    try {
+      const props = await this.docClient.getContainerProperties();
+      policy = props.indexingPolicy;
+    } catch (err) {
+      console.warn(
+        `[CosmosDbProvider] could not verify indexing policy on container ${this.config.container}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return;
+    }
+    const offending = [];
+    for (const entry of policy.excludedPaths) {
+      const prefix = entry.path.replace(/\/[?*]$/, "");
+      if (prefix === "" || prefix === "/") {
+        for (const guard of GUARDED_INDEX_PATHS) {
+          offending.push(`${guard} (covered by ${entry.path})`);
+        }
+        break;
+      }
+      for (const guard of GUARDED_INDEX_PATHS) {
+        if (prefix === guard || guard.startsWith(prefix + "/")) {
+          offending.push(`${guard} (excluded by ${entry.path})`);
+        }
+      }
+    }
+    if (offending.length > 0) {
+      console.warn(
+        `[CosmosDbProvider] Container ${this.config.container} has indexing-policy excludedPaths that cover paths used by findEntities. The query will fall back to scan and may exceed RU budgets:
+  ${offending.join("\n  ")}
+Verify the ARM/Bicep template that provisioned the container.`
+      );
+    }
+  }
   /** Derive the REST endpoint from config — either explicit or from the Gremlin endpoint host. */
   getRestEndpoint() {
     if (this.config.restEndpoint) return this.config.restEndpoint.replace(/\/+$/, "");
@@ -1778,13 +2087,38 @@ var CosmosDbProvider = class {
       () => getVocabulary(this.conn, repositoryId)
     );
   }
+  /**
+   * Cached vocabulary read used by traversal compilation. The vocabulary is
+   * compile-time context for the GremlinCompiler — it changes on the order of
+   * once per session, but the traversal hot path pays one round-trip per call
+   * to fetch it. The cache flips that to one round-trip per TTL window.
+   *
+   * Reads inside an active usage scope are still recorded if a fetch happens
+   * (cache miss); cache hits emit no round-trip and therefore no usage entry.
+   */
+  async getVocabularyCached(repositoryId) {
+    const now = Date.now();
+    const cached = this.vocabularyCache.get(repositoryId);
+    if (cached && cached.expiresAt > now) {
+      return cached.vocab;
+    }
+    const vocab = await getVocabulary(this.conn, repositoryId);
+    this.vocabularyCache.set(repositoryId, {
+      vocab,
+      expiresAt: now + VOCABULARY_CACHE_TTL_MS
+    });
+    return vocab;
+  }
+  /** Drop the cache entry for a repository — call after any vocabulary write. */
+  invalidateVocabularyCache(repositoryId) {
+    this.vocabularyCache.delete(repositoryId);
+  }
   async saveVocabulary(repositoryId, vocabulary) {
     this.assertValidRepositoryId(repositoryId);
-    return this.track(
-      "saveVocabulary",
-      repositoryId,
-      () => saveVocabulary(this.conn, repositoryId, vocabulary)
-    );
+    return this.track("saveVocabulary", repositoryId, async () => {
+      await saveVocabulary(this.conn, repositoryId, vocabulary);
+      this.invalidateVocabularyCache(repositoryId);
+    });
   }
   async getVocabularyChangeLog(repositoryId, options) {
     this.assertValidRepositoryId(repositoryId);
@@ -1803,28 +2137,28 @@ var CosmosDbProvider = class {
       () => createEntity(this.conn, repositoryId, entity)
     );
   }
-  async getEntity(repositoryId, entityId) {
+  async getEntity(repositoryId, entityId, options) {
     this.assertValidRepositoryId(repositoryId);
     return this.track(
       "getEntity",
       repositoryId,
-      () => getEntity(this.conn, repositoryId, entityId)
+      () => getEntity(this.conn, repositoryId, entityId, options)
     );
   }
-  async getEntityBySlug(repositoryId, slug) {
+  async getEntityBySlug(repositoryId, slug, options) {
     this.assertValidRepositoryId(repositoryId);
     return this.track(
       "getEntityBySlug",
       repositoryId,
-      () => getEntityBySlug(this.conn, repositoryId, slug)
+      () => getEntityBySlug(this.conn, repositoryId, slug, options)
     );
   }
-  async getEntities(repositoryId, entityIds) {
+  async getEntities(repositoryId, entityIds, options) {
     this.assertValidRepositoryId(repositoryId);
     return this.track(
       "getEntities",
       repositoryId,
-      () => getEntities(this.conn, repositoryId, entityIds)
+      () => getEntities(this.conn, repositoryId, entityIds, options)
     );
   }
   async updateEntity(repositoryId, entityId, updates) {
@@ -1848,6 +2182,19 @@ var CosmosDbProvider = class {
     this.assertValidRepositoryId(repositoryId);
     return this.track("deleteEntities", repositoryId, () => this.deleteEntitiesImpl(repositoryId, ids));
   }
+  /**
+   * Single round-trip bulk-delete via the aggregate-side-effect pattern:
+   * collapses the per-chunk existence-check + drop into one Gremlin call.
+   *
+   *   g.V()...hasId(within(...)).has('entityType')
+   *     .aggregate('found').by('id')   // collects the ids that match
+   *     .drop()                         // drops the vertices (and cascaded edges)
+   *     .cap('found')                   // emits the bucket as the single result
+   *
+   * The bucket is always emitted as a single list item — empty when nothing
+   * matched (probe-verified 2026-05-25, local-tests/phase7-shape-probe.mjs).
+   * `notFound` is derived client-side as the set difference.
+   */
   async deleteEntitiesImpl(repositoryId, ids) {
     const deleted = [];
     const CHUNK = 100;
@@ -1860,26 +2207,14 @@ var CosmosDbProvider = class {
         bindings[p] = chunk[j];
         idParams.push(p);
       }
-      const withinExpr = `P.within(${idParams.join(", ")})`;
-      const existResult = await this.conn.submit(
-        `g.V().has('repositoryId', rid).has('id', ${withinExpr}).has('entityType').values('id')`,
+      const withinExpr = `within(${idParams.join(", ")})`;
+      const result = await this.conn.submit(
+        `g.V().has('repositoryId', rid).hasId(${withinExpr}).has('entityType').aggregate('found').by('id').drop().cap('found')`,
         bindings
       );
-      const found = existResult.items;
-      if (found.length > 0) {
-        const dropBindings = { rid: repositoryId };
-        const dropIdParams = [];
-        for (let j = 0; j < found.length; j++) {
-          const p = `did${j}`;
-          dropBindings[p] = found[j];
-          dropIdParams.push(p);
-        }
-        const dropWithinExpr = `P.within(${dropIdParams.join(", ")})`;
-        await this.conn.submit(
-          `g.V().has('repositoryId', rid).has('id', ${dropWithinExpr}).has('entityType').drop()`,
-          dropBindings
-        );
-        deleted.push(...found);
+      const bucket = result.items[0];
+      if (Array.isArray(bucket)) {
+        deleted.push(...bucket);
       }
     }
     const deletedSet = new Set(deleted);
@@ -1893,12 +2228,12 @@ var CosmosDbProvider = class {
       () => deleteEntitiesByType(this.conn, repositoryId, entityType)
     );
   }
-  async findEntities(repositoryId, query) {
+  async findEntities(repositoryId, query, options) {
     this.assertValidRepositoryId(repositoryId);
     return this.track(
       "findEntities",
       repositoryId,
-      () => findEntities(this.conn, repositoryId, query)
+      () => findEntities(this.docClient, repositoryId, query, options)
     );
   }
   // ─── Relationships ─────────────────────────────────────────────────
@@ -1939,6 +2274,20 @@ var CosmosDbProvider = class {
     this.assertValidRepositoryId(repositoryId);
     return this.track("deleteRelationships", repositoryId, () => this.deleteRelationshipsImpl(repositoryId, ids));
   }
+  /**
+   * Single round-trip bulk relationship delete via the aggregate-side-effect
+   * pattern: collapses the per-chunk existence-check + drop into one Gremlin
+   * call. Gremlin drop on edges is routed by the engine and the bucket gives
+   * back the exact ids that were actually dropped, so `notFound` can be
+   * derived client-side.
+   *
+   * Source-id partition routing is not exposed on this method (the public
+   * surface accepts only edge ids), so the lookup may fan out across
+   * partitions — see [docs/cosmosdb-gremlin-compatibility.md §`g.E().has`
+   * doesn't always push partition down]. Callers that already hold a
+   * StoredRelationship and want partition-scoped routing should add a
+   * dedicated method when the need is concrete.
+   */
   async deleteRelationshipsImpl(repositoryId, ids) {
     const deleted = [];
     const CHUNK = 100;
@@ -1951,23 +2300,14 @@ var CosmosDbProvider = class {
         bindings[p] = chunk[j];
         idParams.push(p);
       }
-      const withinExpr = `P.within(${idParams.join(", ")})`;
-      const existResult = await this.conn.submit(
-        `g.E().has('repositoryId', rid).has('id', ${withinExpr}).values('id')`,
+      const withinExpr = `within(${idParams.join(", ")})`;
+      const result = await this.conn.submit(
+        `g.E().has('repositoryId', rid).hasId(${withinExpr}).aggregate('found').by('id').drop().cap('found')`,
         bindings
       );
-      const found = existResult.items;
-      if (found.length > 0) {
-        await cosmosRestBatchDelete(
-          this.getRestEndpoint(),
-          this.config.key,
-          this.config.database,
-          this.config.container,
-          repositoryId,
-          found,
-          this.config.rejectUnauthorized ?? true
-        );
-        deleted.push(...found);
+      const bucket = result.items[0];
+      if (Array.isArray(bucket)) {
+        deleted.push(...bucket);
       }
     }
     const deletedSet = new Set(deleted);
@@ -1987,17 +2327,213 @@ var CosmosDbProvider = class {
     return this.track(
       "exploreNeighborhood",
       repositoryId,
-      () => exploreNeighborhood(this.conn, repositoryId, entityId, options)
+      () => this.exploreNeighborhoodImpl(repositoryId, entityId, options)
     );
   }
+  /**
+   * Compiler-model implementation of exploreNeighborhood.
+   *
+   * Strategy: for each depth `d` from 1 to `options.depth`, build a
+   * cumulative `TraversalSpec` with `d` steps and `returnMode: 'all'`, run
+   * it through {@link executeTraversal}, then walk one BFS layer client-side
+   * from the previous frontier using the returned edges.
+   *
+   * The server-side step direction is fixed to `'both'` (catches every edge
+   * in either direction). The directional + bidirectional filter is applied
+   * client-side per hop — i.e. `direction: 'out'` includes inbound edges
+   * where `bidirectional` is true. The CosmosDB Gremlin compiler does not
+   * natively express the `union(outE, inE.has(bidirectional))` shape that
+   * would push this filter server-side, so it stays client-side; the
+   * observable contract (which edges count toward `'out'` given
+   * bidirectionality) is preserved.
+   *
+   * Round-trips per call: `options.depth` (one per layer). The previous BFS
+   * was `1 + fanout + fanout² + …` round-trips for the same depth.
+   */
+  async exploreNeighborhoodImpl(repositoryId, entityId, options) {
+    const layers = [];
+    const visited = /* @__PURE__ */ new Set([entityId]);
+    let frontier = /* @__PURE__ */ new Set([entityId]);
+    for (let d = 1; d <= options.depth; d++) {
+      if (frontier.size === 0) break;
+      const spec = {
+        start: { entityId },
+        steps: buildExploreSteps(d, options),
+        returnMode: "all",
+        // Each round-trip fetches the cumulative subgraph at depth `d` and
+        // we reconstruct layers client-side. The result can include every
+        // edge and vertex reachable in ≤d hops in either direction; size
+        // the limit generously.
+        limit: 1e4,
+        // Use 'full' + includeProvenance so executeTraversal returns full
+        // StoredEntity rows (StorageNeighborhood embeds StoredEntity).
+        detailLevel: "full",
+        includeProvenance: true
+      };
+      const raw = await this.executeTraversal(repositoryId, spec);
+      const edgesByVertex = /* @__PURE__ */ new Map();
+      for (const rel of raw.allRelationships) {
+        const a = edgesByVertex.get(rel.sourceEntityId);
+        if (a) a.push(rel);
+        else edgesByVertex.set(rel.sourceEntityId, [rel]);
+        const b = edgesByVertex.get(rel.targetEntityId);
+        if (b) b.push(rel);
+        else edgesByVertex.set(rel.targetEntityId, [rel]);
+      }
+      const layer = {};
+      const nextFrontier = /* @__PURE__ */ new Set();
+      const layerEdgeSeen = /* @__PURE__ */ new Set();
+      for (const fv of frontier) {
+        const incident = edgesByVertex.get(fv) ?? [];
+        for (const rel of incident) {
+          const isSource = rel.sourceEntityId === fv;
+          const isTarget = rel.targetEntityId === fv;
+          let matchesDirection = false;
+          let connectedId;
+          if (isSource && (options.direction === "out" || options.direction === "both")) {
+            matchesDirection = true;
+            connectedId = rel.targetEntityId;
+          } else if (isTarget && (options.direction === "in" || options.direction === "both")) {
+            matchesDirection = true;
+            connectedId = rel.sourceEntityId;
+          } else if (rel.bidirectional) {
+            if (isSource && options.direction === "in") {
+              matchesDirection = true;
+              connectedId = rel.targetEntityId;
+            } else if (isTarget && options.direction === "out") {
+              matchesDirection = true;
+              connectedId = rel.sourceEntityId;
+            }
+          }
+          if (!matchesDirection || !connectedId) continue;
+          if (visited.has(connectedId)) continue;
+          if (options.relationshipPropertyFilters && options.relationshipPropertyFilters.length > 0) {
+            if (!matchesPropertyFilters3(rel.properties, options.relationshipPropertyFilters)) continue;
+          }
+          const connectedEntity = raw.entityMap.get(connectedId);
+          if (!connectedEntity) continue;
+          if (options.entityTypes && options.entityTypes.length > 0 && !options.entityTypes.includes(connectedEntity.entityType)) {
+            continue;
+          }
+          const edgeKey = `${rel.id}|${fv}->${connectedId}`;
+          if (layerEdgeSeen.has(edgeKey)) continue;
+          layerEdgeSeen.add(edgeKey);
+          const relType = rel.relationshipType;
+          if (!layer[relType]) {
+            layer[relType] = { total: 0, entities: [], relationships: [] };
+          }
+          layer[relType].entities.push(connectedEntity);
+          layer[relType].relationships.push(rel);
+          layer[relType].total = layer[relType].entities.length;
+          nextFrontier.add(connectedId);
+        }
+      }
+      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);
+      }
+      for (const id of nextFrontier) {
+        visited.add(id);
+      }
+      frontier = nextFrontier;
+    }
+    return { centerId: entityId, layers };
+  }
   async findPaths(repositoryId, sourceId, targetId, options) {
     this.assertValidRepositoryId(repositoryId);
     return this.track(
       "findPaths",
       repositoryId,
-      () => findPaths(this.conn, repositoryId, sourceId, targetId, options)
+      () => this.findPathsImpl(repositoryId, sourceId, targetId, options)
     );
   }
+  /**
+   * Compiler-model implementation of findPaths.
+   *
+   * Strategy: build a `TraversalSpec` with a single `'both'` direction step
+   * in `repeat()` mode with `emitIntermediates: true` and `returnMode:
+   * 'path'`, run it once. The compiler always emits `.simplePath()` in path
+   * mode for cycle prevention, producing
+   * `.emit().repeat(bothE().otherV()).times(maxDepth).simplePath()
+   * .range(...).path().by(<v>).by(<e>)`, which yields paths of every length
+   * from 0 (the start vertex alone) to `maxDepth`. Live-probed against the
+   * Cosmos emulator 2026-05-25 — see local-tests/phase4-repeat-emit-probe.mjs.
+   *
+   * The pre-Phase-4 Cosmos BFS in (now-deleted) `packages/storage-cosmosdb/
+   * src/queries/traversal.ts` traversed edges with unconditional `bothE()`
+   * regardless of the `bidirectional` flag (path discovery is reachability,
+   * not semantic direction). Mirror that here by using step direction
+   * `'both'` and not applying any direction filter. The plan's §6
+   * observable-outputs rule requires preserving this.
+   *
+   * One round-trip total. The previous BFS was up to `1 + fanout + fanout² + …`.
+   */
+  async findPathsImpl(repositoryId, sourceId, targetId, options) {
+    if (sourceId === targetId) {
+      return { paths: [{ entityIds: [sourceId], relationshipIds: [] }], totalPaths: 1 };
+    }
+    const step = {
+      direction: "both",
+      repeat: { maxDepth: options.maxDepth, emitIntermediates: true }
+    };
+    if (options.relationshipTypes && options.relationshipTypes.length > 0) {
+      step.relationshipTypes = options.relationshipTypes;
+    }
+    if (options.relationshipPropertyFilters && options.relationshipPropertyFilters.length > 0) {
+      step.relationshipFilter = options.relationshipPropertyFilters;
+    }
+    const spec = {
+      start: { entityId: sourceId },
+      steps: [step],
+      returnMode: "path",
+      // Cycle prevention comes from the compiler unconditionally emitting
+      // .simplePath() in path mode — replaces the explicit
+      // `state.path.includes(nextId)` guard from the old BFS.
+      // Pull the full pool of paths so we can post-filter to those ending at
+      // targetId, then paginate. The emulator returns paths of every length
+      // 0..maxDepth in one round-trip with the repeat+emit shape; cap
+      // generously to ensure all candidates are inspected.
+      limit: Math.max(options.limit + options.offset, options.limit) * 10,
+      detailLevel: "full",
+      includeProvenance: true
+    };
+    const raw = await this.executeTraversal(repositoryId, spec);
+    const matchingPaths = [];
+    for (const row of raw.pathRows) {
+      const last = row.entityIds[row.entityIds.length - 1];
+      if (last !== targetId) continue;
+      if (options.entityTypes && options.entityTypes.length > 0) {
+        let rejected = false;
+        for (let i = 1; i < row.entityIds.length - 1; i++) {
+          const intermediate = raw.entityMap.get(row.entityIds[i]);
+          if (!intermediate) {
+            rejected = true;
+            break;
+          }
+          if (!options.entityTypes.includes(intermediate.entityType)) {
+            rejected = true;
+            break;
+          }
+        }
+        if (rejected) continue;
+      }
+      matchingPaths.push({
+        entityIds: [...row.entityIds],
+        relationshipIds: [...row.relationshipIds]
+      });
+    }
+    const paginated = matchingPaths.slice(options.offset, options.offset + options.limit);
+    return {
+      paths: paginated,
+      totalPaths: matchingPaths.length
+    };
+  }
   // ─── Timeline ──────────────────────────────────────────────────────
   async getTimeline(repositoryId, entityId, options) {
     this.assertValidRepositoryId(repositoryId);
@@ -2085,79 +2621,224 @@ var CosmosDbProvider = class {
   }
   async traverse(repositoryId, spec) {
     this.assertValidRepositoryId(repositoryId);
-    return this.track("traverse", repositoryId, () => this.traverseImpl(repositoryId, spec));
+    return this.track("traverse", repositoryId, () => this.traverseInternal(repositoryId, spec));
+  }
+  /**
+   * Compile + execute a TraversalSpec against this repository's partition.
+   *
+   * Internal entrypoint shared by `traverse` (the public surface) and the
+   * compiler-model rewrites of `exploreNeighborhood` / `findPaths`. Does NOT
+   * wrap in `track()` — the outer public method owns its own usage scope, and
+   * inner submits accumulate into that scope (the nested-scope guard in
+   * `track()` keeps nested public calls from emitting duplicate records).
+   */
+  async traverseInternal(repositoryId, spec) {
+    const raw = await this.executeTraversal(repositoryId, spec);
+    const detailLevel = spec.detailLevel ?? "summary";
+    const projectStoredEntity = (stored) => {
+      const projected = projectEntity(stored, detailLevel);
+      if (!spec.includeProvenance) {
+        delete projected["provenance"];
+      }
+      return projected;
+    };
+    const projectStoredRelationship = (rel, direction = "out") => ({
+      id: rel.id,
+      type: rel.relationshipType,
+      sourceEntityId: rel.sourceEntityId,
+      targetEntityId: rel.targetEntityId,
+      direction,
+      properties: rel.properties
+    });
+    let entities = [];
+    let relationships;
+    let paths;
+    const rangeRowCount = spec.returnMode === "all" ? raw.allEntities.length + raw.allRelationships.length : 0;
+    if (spec.returnMode === "terminal") {
+      entities = raw.terminalEntities.map(projectStoredEntity);
+      relationships = void 0;
+    } else if (spec.returnMode === "all") {
+      const missingIds = /* @__PURE__ */ new Set();
+      for (const rel of raw.allRelationships) {
+        if (!raw.entityMap.has(rel.sourceEntityId)) {
+          missingIds.add(rel.sourceEntityId);
+        }
+        if (!raw.entityMap.has(rel.targetEntityId)) {
+          missingIds.add(rel.targetEntityId);
+        }
+      }
+      if (missingIds.size > 0) {
+        const fetched = await this.getEntities(repositoryId, [...missingIds]);
+        for (const stored of fetched.values()) {
+          raw.allEntities.push(stored);
+          raw.entityMap.set(stored.id, stored);
+        }
+      }
+      entities = raw.allEntities.map(projectStoredEntity);
+      relationships = raw.allRelationships.map((r) => projectStoredRelationship(r));
+    } else {
+      paths = raw.pathRows.map((row) => ({
+        length: Math.max(row.entityIds.length - 1, 0),
+        entities: row.entityIds.map((id) => {
+          const stored = raw.entityMap.get(id);
+          if (!stored) {
+            throw new ProviderError(
+              "Unpacking Gremlin path: entity referenced by path is missing from the result",
+              "This indicates a Gremlin response shape mismatch \u2014 inspect compiledQuery."
+            );
+          }
+          return projectStoredEntity(stored);
+        }),
+        relationships: row.relationshipIds.map((id, i) => {
+          const stored = raw.relationshipMap.get(id);
+          if (!stored) {
+            throw new ProviderError(
+              "Unpacking Gremlin path: relationship referenced by path is missing from the result",
+              "This indicates a Gremlin response shape mismatch \u2014 inspect compiledQuery."
+            );
+          }
+          return projectStoredRelationship(stored, row.relationshipDirections[i]);
+        })
+      }));
+      relationships = Array.from(raw.relationshipMap.values()).map(
+        (rel) => projectStoredRelationship(rel, raw.pathRelFirstDirection.get(rel.id) ?? "out")
+      );
+    }
+    const limit = spec.limit ?? 50;
+    let total;
+    if (spec.returnMode === "path") {
+      total = paths?.length ?? 0;
+    } else if (spec.returnMode === "all") {
+      total = entities.length + (relationships?.length ?? 0);
+    } else {
+      total = entities.length;
+    }
+    const paginationSignal = spec.returnMode === "all" ? rangeRowCount : total;
+    const truncated = paginationSignal >= limit;
+    const queryMetadata = {
+      executionTimeMs: raw.executionTimeMs,
+      resourceCost: raw.requestCharge != null ? { units: "RU", value: raw.requestCharge } : void 0,
+      compiledQuery: raw.compiledQuery,
+      compiledQueryLanguage: "gremlin",
+      appliedLimits: {
+        maxResults: limit,
+        maxDepth: spec.steps?.length
+      },
+      truncated,
+      truncationReason: truncated ? "result_limit" : void 0
+    };
+    return {
+      entities,
+      relationships,
+      paths,
+      total,
+      returned: total,
+      hasMore: truncated,
+      queryMetadata
+    };
   }
-  async traverseImpl(repositoryId, spec) {
+  /**
+   * Lower-level traversal helper: compiles a spec, submits to Gremlin, and
+   * parses the rows into raw {@link StoredEntity} / {@link StoredRelationship}
+   * objects (no detail-level projection, no provenance stripping). Used by
+   * `traverseInternal` and by the storage-layer rewrites of
+   * `exploreNeighborhood` / `findPaths` that need the full stored shape to
+   * rebuild `StorageNeighborhood` / `StoragePathResult`.
+   *
+   * Returns a discriminated bag — only the fields relevant to `spec.returnMode`
+   * are populated:
+   * - `'terminal'`: `terminalEntities` (in row order, no dedup beyond what the
+   *    server emitted).
+   * - `'all'`: `allEntities` and `allRelationships`, already server-deduped.
+   * - `'path'`: `pathRows` plus the `entityMap` / `relationshipMap` lookup
+   *    tables and `pathRelFirstDirection` for the first-seen direction per
+   *    deduped edge id.
+   */
+  async executeTraversal(repositoryId, spec) {
     const startTime = Date.now();
-    const vocabulary = await this.getVocabulary(repositoryId);
+    const vocabulary = await this.getVocabularyCached(repositoryId);
     const compiled = this.compiler.compile(spec, vocabulary);
     const scopedQuery = compiled.query.replace(
       "g.V()",
       "g.V().has('repositoryId', pRid)"
     );
     const scopedParams = { ...compiled.params, pRid: repositoryId };
+    let result;
     try {
-      const result = await this.conn.submit(scopedQuery, scopedParams);
-      const executionTimeMs = Date.now() - startTime;
-      const detailLevel = spec.detailLevel ?? "summary";
-      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"]) {
-                const stored = entityFromGremlin(props);
-                pathEntities.push(projectEntity(stored, detailLevel));
-              }
-            }
-            if (pathEntities.length > 0) {
-              paths.push({
-                length: pathEntities.length - 1,
-                entities: pathEntities,
-                relationships: []
-              });
-            }
-          }
-        }
-      } else {
-        for (const item of result.items) {
-          const stored = entityFromGremlin(item);
-          entities.push(projectEntity(stored, detailLevel));
-        }
-      }
-      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
-      };
+      result = await this.conn.submit(scopedQuery, scopedParams);
     } 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."
       );
     }
+    const executionTimeMs = Date.now() - startTime;
+    const raw = {
+      terminalEntities: [],
+      allEntities: [],
+      allRelationships: [],
+      pathRows: [],
+      entityMap: /* @__PURE__ */ new Map(),
+      relationshipMap: /* @__PURE__ */ new Map(),
+      pathRelFirstDirection: /* @__PURE__ */ new Map(),
+      executionTimeMs,
+      requestCharge: result.requestCharge,
+      compiledQuery: scopedQuery
+    };
+    if (spec.returnMode === "terminal") {
+      for (const item of result.items) {
+        const stored = entityFromGremlin(item);
+        raw.terminalEntities.push(stored);
+      }
+    } else if (spec.returnMode === "all") {
+      for (const item of result.items) {
+        const props = item;
+        const kind = props["__kind"];
+        if (kind === "v") {
+          const stored = entityFromGremlin(props);
+          raw.allEntities.push(stored);
+          raw.entityMap.set(stored.id, stored);
+        } else if (kind === "e") {
+          const stored = relationshipFromGremlin(props);
+          raw.allRelationships.push(stored);
+          raw.relationshipMap.set(stored.id, stored);
+        }
+      }
+    } else {
+      for (const item of result.items) {
+        const pathData = item;
+        if (!pathData.objects) continue;
+        const pathEntityIds = [];
+        const pathRelIds = [];
+        const pathRelDirections = [];
+        let lastVertexId = null;
+        for (const obj of pathData.objects) {
+          const props = obj;
+          const kind = props["__kind"];
+          if (kind === "v") {
+            const stored = entityFromGremlin(props);
+            raw.entityMap.set(stored.id, stored);
+            pathEntityIds.push(stored.id);
+            lastVertexId = stored.id;
+          } else if (kind === "e") {
+            const stored = relationshipFromGremlin(props);
+            raw.relationshipMap.set(stored.id, stored);
+            pathRelIds.push(stored.id);
+            const direction = lastVertexId === stored.sourceEntityId ? "out" : "in";
+            pathRelDirections.push(direction);
+            if (!raw.pathRelFirstDirection.has(stored.id)) {
+              raw.pathRelFirstDirection.set(stored.id, direction);
+            }
+          }
+        }
+        raw.pathRows.push({
+          entityIds: pathEntityIds,
+          relationshipIds: pathRelIds,
+          relationshipDirections: pathRelDirections
+        });
+      }
+    }
+    return raw;
   }
   /**
    * Execute a raw Gremlin query with caller-supplied bindings.
@@ -2192,67 +2873,16 @@ 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) {
-    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}`);
-}
-async function cosmosRestBatchDelete(restBase, key, database, container, partitionKeyValue, ids, rejectUnauthorized) {
-  const resourceLink = `dbs/${database}/colls/${container}`;
-  const date = (/* @__PURE__ */ new Date()).toUTCString();
-  const token = cosmosAuthToken("post", "docs", resourceLink, date, key);
-  if (!rejectUnauthorized) {
-    process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = "0";
+function buildExploreSteps(depth, options) {
+  const base = { direction: "both" };
+  if (options.relationshipTypes && options.relationshipTypes.length > 0) {
+    base.relationshipTypes = options.relationshipTypes;
   }
-  const ops = ids.map((id) => ({ operationType: "Delete", id }));
-  const response = await fetch(`${restBase}/${resourceLink}/docs`, {
-    method: "POST",
-    headers: {
-      "Authorization": token,
-      "x-ms-version": "2020-07-15",
-      "x-ms-date": date,
-      "Content-Type": "application/json",
-      "x-ms-documentdb-partitionkey": JSON.stringify([partitionKeyValue]),
-      "x-ms-cosmos-is-batch-request": "true",
-      "x-ms-cosmos-batch-atomic": "true"
-    },
-    body: JSON.stringify(ops)
-  });
-  if (response.status !== 200 && response.status !== 207) {
-    const text = await response.text();
-    throw new ProviderError(`CosmosDB batch delete failed (${response.status}): ${text}`);
+  const steps = [];
+  for (let i = 0; i < depth; i++) {
+    steps.push({ ...base });
   }
+  return steps;
 }
 export {
   CosmosDbConnection,