@utaba/deep-memory-storage-cosmosdb 0.17.0 → 0.19.0

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/CosmosDbProvider.ts
 import {
   GremlinCompiler,
-  ProviderError,
+  ProviderError as ProviderError2,
   InvalidInputError,
   isValidUuid,
   projectEntity,
@@ -290,6 +290,7 @@ function sleep2(ms) {
 }
 
 // src/mapping.ts
+import { ProviderError } from "@utaba/deep-memory";
 var STORED_ENTITY_FIELDS = [
   "id",
   "entityType",
@@ -630,6 +631,89 @@ function repositoryConfigToLadderBindings(config) {
   bindings[SENTINEL_BINDING] = ABSENT_STRING_SENTINEL;
   return bindings;
 }
+var RESERVED_ENTITY_PROPERTY_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "repositoryId",
+  ...ENTITY_REQUIRED_SLOTS,
+  ...ENTITY_OPTIONAL_SLOTS
+]);
+var RESERVED_RELATIONSHIP_PROPERTY_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "repositoryId",
+  "label",
+  ...RELATIONSHIP_REQUIRED_SLOTS,
+  ...RELATIONSHIP_OPTIONAL_SLOTS
+]);
+var USER_PROPERTY_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertSafeUserPropertyKey(key, reserved, scope) {
+  if (!USER_PROPERTY_KEY_PATTERN.test(key)) {
+    throw new ProviderError(
+      `${scope} property key "${key}" is not a valid Gremlin identifier \u2014 must match ${USER_PROPERTY_KEY_PATTERN.source}. User-property keys are interpolated into Gremlin .property(...) / values(...) / .drop() slots (the key slot cannot be parameterised), so an unsafe value would widen the injection surface.`
+    );
+  }
+  if (reserved.has(key)) {
+    throw new ProviderError(
+      `${scope} property key "${key}" collides with a schema-managed field. Reserved names: ${Array.from(reserved).join(", ")}.`
+    );
+  }
+  return key;
+}
+function assertSafeEntityUserPropertyKey(key) {
+  return assertSafeUserPropertyKey(key, RESERVED_ENTITY_PROPERTY_KEYS, "Entity");
+}
+function assertSafeRelationshipUserPropertyKey(key) {
+  return assertSafeUserPropertyKey(key, RESERVED_RELATIONSHIP_PROPERTY_KEYS, "Relationship");
+}
+function isNativeStorableValue(value) {
+  if (typeof value === "string") return true;
+  if (typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return true;
+    const first = value[0];
+    const t = typeof first;
+    if (t !== "string" && t !== "boolean" && (t !== "number" || !Number.isFinite(first))) {
+      return false;
+    }
+    for (const v of value) {
+      if (typeof v !== t) return false;
+      if (t === "number" && !Number.isFinite(v)) return false;
+    }
+    return true;
+  }
+  return false;
+}
+function entityUserPropertyParams(properties) {
+  const out = [];
+  for (const [key, value] of Object.entries(properties)) {
+    assertSafeEntityUserPropertyKey(key);
+    if (isNativeStorableValue(value)) {
+      out.push({ key, value });
+    }
+  }
+  return out;
+}
+function relationshipUserPropertyParams(properties) {
+  const out = [];
+  for (const [key, value] of Object.entries(properties)) {
+    assertSafeRelationshipUserPropertyKey(key);
+    if (isNativeStorableValue(value)) {
+      out.push({ key, value });
+    }
+  }
+  return out;
+}
+function existingEntityScalarUserKeys(blob) {
+  if (blob == null) return [];
+  const out = [];
+  for (const [key, value] of Object.entries(blob)) {
+    if (!USER_PROPERTY_KEY_PATTERN.test(key)) continue;
+    if (RESERVED_ENTITY_PROPERTY_KEYS.has(key)) continue;
+    if (!isNativeStorableValue(value)) continue;
+    out.push(key);
+  }
+  return out;
+}
 
 // src/queries/repository.ts
 import { DuplicateRepositoryError, RepositoryNotFoundError } from "@utaba/deep-memory";
@@ -1011,7 +1095,8 @@ import {
   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()})`;
+var ENTITY_CREATE_PREFIX = `g.V().has('repositoryId', rid).hasId(vid).fold().coalesce(unfold().constant('${DUPLICATE_SENTINEL}'),addV(vertexLabel).property('id', vid).property('repositoryId', rid)${buildEntityPropertyLadder()}`;
+var ENTITY_CREATE_QUERY = `${ENTITY_CREATE_PREFIX})`;
 async function createEntity(conn, repositoryId, entity) {
   const bindings = {
     rid: repositoryId,
@@ -1019,7 +1104,20 @@ async function createEntity(conn, repositoryId, entity) {
     vertexLabel: entity.entityType,
     ...entityToLadderBindings(entity)
   };
-  const result = await conn.submit(ENTITY_CREATE_QUERY, bindings);
+  const userProps = entityUserPropertyParams(entity.properties ?? {});
+  let query;
+  if (userProps.length === 0) {
+    query = ENTITY_CREATE_QUERY;
+  } else {
+    let suffix = "";
+    for (let i = 0; i < userProps.length; i++) {
+      const { key, value } = userProps[i];
+      suffix += `.property('${key}', p_user_${i})`;
+      bindings[`p_user_${i}`] = value;
+    }
+    query = `${ENTITY_CREATE_PREFIX}${suffix})`;
+  }
+  const result = await conn.submit(query, bindings);
   if (result.items[0] === DUPLICATE_SENTINEL) {
     throw new DuplicateEntityError(entity.id);
   }
@@ -1065,7 +1163,36 @@ async function getEntities(conn, repositoryId, entityIds, options) {
   }
   return map;
 }
+async function readExistingEntityPropertiesBlob(conn, repositoryId, entityId) {
+  const result = await conn.submit(
+    "g.V().has('repositoryId', rid).hasId(eid).has('entityType').values('properties').limit(1)",
+    { rid: repositoryId, eid: entityId }
+  );
+  if (result.items.length === 0) return { found: false };
+  const raw = result.items[0];
+  const json = typeof raw === "string" ? raw : String(raw ?? "");
+  if (!json) return { found: true, blob: {} };
+  try {
+    const parsed = JSON.parse(json);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return { found: true, blob: parsed };
+    }
+  } catch {
+  }
+  return { found: true, blob: {} };
+}
 async function updateEntity(conn, repositoryId, entityId, updates) {
+  const userProps = updates.properties !== void 0 ? entityUserPropertyParams(updates.properties) : null;
+  let droppedUserKeys = [];
+  if (updates.properties !== void 0) {
+    const existing = await readExistingEntityPropertiesBlob(conn, repositoryId, entityId);
+    if (!existing.found) {
+      throw new EntityNotFoundError(entityId);
+    }
+    const existingKeys = existingEntityScalarUserKeys(existing.blob);
+    const newKeySet = new Set(userProps.map((p) => p.key));
+    droppedUserKeys = existingKeys.filter((k) => !newKeySet.has(k));
+  }
   const bindings = { rid: repositoryId, eid: entityId };
   const propParts = [];
   let idx = 0;
@@ -1082,7 +1209,18 @@ async function updateEntity(conn, repositoryId, entityId, updates) {
   if (updates.slug !== void 0) addProp("slug", updates.slug);
   if (updates.summary === null) dropProp("summary");
   else if (updates.summary !== void 0) addProp("summary", updates.summary);
-  if (updates.properties !== void 0) addProp("properties", JSON.stringify(updates.properties));
+  if (updates.properties !== void 0 && userProps !== null) {
+    addProp("properties", JSON.stringify(updates.properties));
+    for (const dropKey of droppedUserKeys) {
+      dropProp(dropKey);
+    }
+    for (let i = 0; i < userProps.length; i++) {
+      const { key, value } = userProps[i];
+      const paramName = `p_user_${i}`;
+      bindings[paramName] = value;
+      propParts.push(`.property('${key}', ${paramName})`);
+    }
+  }
   if (updates.data === null) dropProp("data");
   else if (updates.data !== void 0) addProp("data", updates.data);
   if (updates.dataFormat === null) dropProp("dataFormat");
@@ -1137,16 +1275,33 @@ function buildWhereClause(query, repositoryId) {
       `(CONTAINS(${sqlPath("entityLabel")}, @term, true) OR CONTAINS(${sqlPath("slug")}, @term, true) OR CONTAINS(${sqlPath("summary")}, @term, 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)`);
+  let propertyFilterMode = "none";
+  if (query.properties != null && Object.keys(query.properties).length > 0) {
+    const entries = Object.entries(query.properties);
+    const allStorable = entries.every(([, value]) => isNativeStorableValue(value));
+    if (allStorable) {
+      for (const [key] of entries) {
+        assertSafeEntityUserPropertyKey(key);
+      }
+      let i = 0;
+      for (const [key, value] of entries) {
+        const name = `@val${i++}`;
+        params.push({ name, value });
+        predicates.push(`${sqlPath(key)} = ${name}`);
+      }
+      propertyFilterMode = "exact";
+    } else {
+      let i = 0;
+      for (const [key, value] of entries) {
+        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)`);
+      }
+      propertyFilterMode = "approximate";
     }
   }
-  return { sqlWhere: `WHERE ${predicates.join(" AND ")}`, params };
+  return { sqlWhere: `WHERE ${predicates.join(" AND ")}`, params, propertyFilterMode };
 }
 function buildSelectClause(loadEmbeddings) {
   const fields = ["c.id", ...STORED_ENTITY_FIELDS.filter((f) => f !== "id").map((f) => `c.${f}`)];
@@ -1154,7 +1309,7 @@ function buildSelectClause(loadEmbeddings) {
   return `SELECT ${fields.join(", ")}`;
 }
 async function findEntities(docClient, repositoryId, query, options) {
-  const { sqlWhere, params } = buildWhereClause(query, repositoryId);
+  const { sqlWhere, params, propertyFilterMode } = buildWhereClause(query, repositoryId);
   const dataParams = [
     ...params,
     { name: "@off", value: query.offset },
@@ -1163,7 +1318,7 @@ async function findEntities(docClient, repositoryId, query, options) {
   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 skipCount = propertyFilterMode === "approximate";
   const [dataResult, countResult] = await Promise.all([
     docClient.query(dataSql, dataParams, {
       partitionKey: repositoryId
@@ -1191,7 +1346,8 @@ async function findEntities(docClient, repositoryId, query, options) {
 // src/queries/relationship.ts
 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()})`;
+var RELATIONSHIP_CREATE_PREFIX = `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()}`;
+var RELATIONSHIP_CREATE_QUERY = `${RELATIONSHIP_CREATE_PREFIX})`;
 async function createRelationship(conn, repositoryId, relationship) {
   const bindings = {
     rid: repositoryId,
@@ -1201,7 +1357,20 @@ async function createRelationship(conn, repositoryId, relationship) {
     edgeLabel: relationship.relationshipType,
     ...relationshipToLadderBindings(relationship)
   };
-  const result = await conn.submit(RELATIONSHIP_CREATE_QUERY, bindings);
+  const userProps = relationshipUserPropertyParams(relationship.properties ?? {});
+  let query;
+  if (userProps.length === 0) {
+    query = RELATIONSHIP_CREATE_QUERY;
+  } else {
+    let suffix = "";
+    for (let i = 0; i < userProps.length; i++) {
+      const { key, value } = userProps[i];
+      suffix += `.property('${key}', p_user_${i})`;
+      bindings[`p_user_${i}`] = value;
+    }
+    query = `${RELATIONSHIP_CREATE_PREFIX}${suffix})`;
+  }
+  const result = await conn.submit(query, bindings);
   if (result.items[0] === DUPLICATE_SENTINEL2) {
     throw new DuplicateRelationshipError(relationship.id);
   }
@@ -1227,10 +1396,10 @@ async function getEntityRelationships(conn, repositoryId, entityId, options) {
   };
   let edgeTraversal;
   switch (direction) {
-    case "outbound":
+    case "out":
       edgeTraversal = "g.V().has('repositoryId', rid).hasId(eid).has('entityType').outE()";
       break;
-    case "inbound":
+    case "in":
       edgeTraversal = "g.V().has('repositoryId', rid).hasId(eid).has('entityType').inE()";
       break;
     case "both":
@@ -1249,9 +1418,9 @@ async function getEntityRelationships(conn, repositoryId, entityId, options) {
     typeFilter = `.hasLabel(${typeParams.join(", ")})`;
   }
   let unionQuery = null;
-  if (direction === "outbound") {
+  if (direction === "out") {
     unionQuery = `g.V().has('repositoryId', rid).hasId(eid).has('entityType').union(outE()${typeFilter}, inE()${typeFilter}.has('bidirectional', true))`;
-  } else if (direction === "inbound") {
+  } 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}`;
@@ -1754,8 +1923,12 @@ 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})`;
+var UPSERT_ENTITY_OPEN = `g.V().has('repositoryId', rid).hasId(vid).has('entityType').fold().coalesce(unfold()${ENTITY_LADDER_CHAIN}`;
+var UPSERT_ENTITY_CREATE_BRANCH = `, addV(vertexLabel).property('id', vid).property('repositoryId', rid)${ENTITY_LADDER_CHAIN}`;
+var UPSERT_ENTITY_QUERY = `${UPSERT_ENTITY_OPEN}${UPSERT_ENTITY_CREATE_BRANCH})`;
+var UPSERT_RELATIONSHIP_OPEN = `g.E().has('repositoryId', rid).hasId(relId).fold().coalesce(unfold()${RELATIONSHIP_LADDER_CHAIN}`;
+var UPSERT_RELATIONSHIP_CREATE_BRANCH = `, 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_RELATIONSHIP_QUERY = `${UPSERT_RELATIONSHIP_OPEN}${UPSERT_RELATIONSHIP_CREATE_BRANCH})`;
 async function insertEntity(conn, repositoryId, entity) {
   const bindings = {
     rid: repositoryId,
@@ -1763,7 +1936,20 @@ async function insertEntity(conn, repositoryId, entity) {
     vertexLabel: entity.entityType,
     ...entityToLadderBindings(entity)
   };
-  await conn.submit(INSERT_ENTITY_QUERY, bindings);
+  const userProps = entityUserPropertyParams(entity.properties ?? {});
+  let query;
+  if (userProps.length === 0) {
+    query = INSERT_ENTITY_QUERY;
+  } else {
+    let suffix = "";
+    for (let i = 0; i < userProps.length; i++) {
+      const { key, value } = userProps[i];
+      suffix += `.property('${key}', p_user_${i})`;
+      bindings[`p_user_${i}`] = value;
+    }
+    query = `${INSERT_ENTITY_QUERY}${suffix}`;
+  }
+  await conn.submit(query, bindings);
 }
 async function insertRelationship(conn, repositoryId, rel) {
   const bindings = {
@@ -1774,7 +1960,20 @@ async function insertRelationship(conn, repositoryId, rel) {
     edgeLabel: rel.relationshipType,
     ...relationshipToLadderBindings(rel)
   };
-  await conn.submit(INSERT_RELATIONSHIP_QUERY, bindings);
+  const userProps = relationshipUserPropertyParams(rel.properties ?? {});
+  let query;
+  if (userProps.length === 0) {
+    query = INSERT_RELATIONSHIP_QUERY;
+  } else {
+    let suffix = "";
+    for (let i = 0; i < userProps.length; i++) {
+      const { key, value } = userProps[i];
+      suffix += `.property('${key}', p_user_${i})`;
+      bindings[`p_user_${i}`] = value;
+    }
+    query = `${INSERT_RELATIONSHIP_QUERY}${suffix}`;
+  }
+  await conn.submit(query, bindings);
 }
 async function upsertEntity(conn, repositoryId, entity) {
   const bindings = {
@@ -1783,7 +1982,20 @@ async function upsertEntity(conn, repositoryId, entity) {
     vertexLabel: entity.entityType,
     ...entityToLadderBindings(entity)
   };
-  await conn.submit(UPSERT_ENTITY_QUERY, bindings);
+  const userProps = entityUserPropertyParams(entity.properties ?? {});
+  let query;
+  if (userProps.length === 0) {
+    query = UPSERT_ENTITY_QUERY;
+  } else {
+    let suffix = "";
+    for (let i = 0; i < userProps.length; i++) {
+      const { key, value } = userProps[i];
+      suffix += `.property('${key}', p_user_${i})`;
+      bindings[`p_user_${i}`] = value;
+    }
+    query = `${UPSERT_ENTITY_OPEN}${suffix}${UPSERT_ENTITY_CREATE_BRANCH}${suffix})`;
+  }
+  await conn.submit(query, bindings);
 }
 async function upsertRelationship(conn, repositoryId, rel) {
   const bindings = {
@@ -1794,7 +2006,20 @@ async function upsertRelationship(conn, repositoryId, rel) {
     edgeLabel: rel.relationshipType,
     ...relationshipToLadderBindings(rel)
   };
-  await conn.submit(UPSERT_RELATIONSHIP_QUERY, bindings);
+  const userProps = relationshipUserPropertyParams(rel.properties ?? {});
+  let query;
+  if (userProps.length === 0) {
+    query = UPSERT_RELATIONSHIP_QUERY;
+  } else {
+    let suffix = "";
+    for (let i = 0; i < userProps.length; i++) {
+      const { key, value } = userProps[i];
+      suffix += `.property('${key}', p_user_${i})`;
+      bindings[`p_user_${i}`] = value;
+    }
+    query = `${UPSERT_RELATIONSHIP_OPEN}${suffix}${UPSERT_RELATIONSHIP_CREATE_BRANCH}${suffix})`;
+  }
+  await conn.submit(query, bindings);
 }
 
 // src/CosmosDbProvider.ts
@@ -1965,7 +2190,7 @@ var CosmosDbProvider = class {
         schemaVersion: SCHEMA_VERSION
       };
     } catch (err) {
-      throw new ProviderError(
+      throw new ProviderError2(
         `Failed to ensure CosmosDB schema: ${err instanceof Error ? err.message : String(err)}`,
         "Verify the CosmosDB REST endpoint is accessible and the Gremlin endpoint is reachable."
       );
@@ -2340,11 +2565,11 @@ Verify the ARM/Bicep template that provisioned the container.`
    *
    * 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: 'outbound'` includes inbound edges
+   * 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 "outbound" given
+   * observable contract (which edges count toward `'out'` given
    * bidirectionality) is preserved.
    *
    * Round-trips per call: `options.depth` (one per layer). The previous BFS
@@ -2382,7 +2607,7 @@ Verify the ARM/Bicep template that provisioned the container.`
       }
       const layer = {};
       const nextFrontier = /* @__PURE__ */ new Set();
-      const layerEdgeSeen = /* @__PURE__ */ new Set();
+      const layerBucketSeen = /* @__PURE__ */ new Map();
       for (const fv of frontier) {
         const incident = edgesByVertex.get(fv) ?? [];
         for (const rel of incident) {
@@ -2390,17 +2615,17 @@ Verify the ARM/Bicep template that provisioned the container.`
           const isTarget = rel.targetEntityId === fv;
           let matchesDirection = false;
           let connectedId;
-          if (isSource && (options.direction === "outbound" || options.direction === "both")) {
+          if (isSource && (options.direction === "out" || options.direction === "both")) {
             matchesDirection = true;
             connectedId = rel.targetEntityId;
-          } else if (isTarget && (options.direction === "inbound" || options.direction === "both")) {
+          } else if (isTarget && (options.direction === "in" || options.direction === "both")) {
             matchesDirection = true;
             connectedId = rel.sourceEntityId;
           } else if (rel.bidirectional) {
-            if (isSource && options.direction === "inbound") {
+            if (isSource && options.direction === "in") {
               matchesDirection = true;
               connectedId = rel.targetEntityId;
-            } else if (isTarget && options.direction === "outbound") {
+            } else if (isTarget && options.direction === "out") {
               matchesDirection = true;
               connectedId = rel.sourceEntityId;
             }
@@ -2415,10 +2640,14 @@ Verify the ARM/Bicep template that provisioned the container.`
           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;
+          let bucketSeen = layerBucketSeen.get(relType);
+          if (!bucketSeen) {
+            bucketSeen = /* @__PURE__ */ new Set();
+            layerBucketSeen.set(relType, bucketSeen);
+          }
+          if (bucketSeen.has(connectedId)) continue;
+          bucketSeen.add(connectedId);
           if (!layer[relType]) {
             layer[relType] = { total: 0, entities: [], relationships: [] };
           }
@@ -2642,7 +2871,7 @@ Verify the ARM/Bicep template that provisioned the container.`
       }
       return projected;
     };
-    const projectStoredRelationship = (rel, direction = "outbound") => ({
+    const projectStoredRelationship = (rel, direction = "out") => ({
       id: rel.id,
       type: rel.relationshipType,
       sourceEntityId: rel.sourceEntityId,
@@ -2653,10 +2882,30 @@ Verify the ARM/Bicep template that provisioned the container.`
     let entities = [];
     let relationships;
     let paths;
-    if (spec.returnMode === "terminal") {
+    const aggregations = raw.aggregations;
+    const projectionEmitted = aggregations !== void 0;
+    const rangeRowCount = spec.returnMode === "all" ? raw.allEntities.length + raw.allRelationships.length : 0;
+    if (projectionEmitted) {
+    } else 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 {
@@ -2665,7 +2914,7 @@ Verify the ARM/Bicep template that provisioned the container.`
         entities: row.entityIds.map((id) => {
           const stored = raw.entityMap.get(id);
           if (!stored) {
-            throw new ProviderError(
+            throw new ProviderError2(
               "Unpacking Gremlin path: entity referenced by path is missing from the result",
               "This indicates a Gremlin response shape mismatch \u2014 inspect compiledQuery."
             );
@@ -2675,7 +2924,7 @@ Verify the ARM/Bicep template that provisioned the container.`
         relationships: row.relationshipIds.map((id, i) => {
           const stored = raw.relationshipMap.get(id);
           if (!stored) {
-            throw new ProviderError(
+            throw new ProviderError2(
               "Unpacking Gremlin path: relationship referenced by path is missing from the result",
               "This indicates a Gremlin response shape mismatch \u2014 inspect compiledQuery."
             );
@@ -2684,18 +2933,22 @@ Verify the ARM/Bicep template that provisioned the container.`
         })
       }));
       relationships = Array.from(raw.relationshipMap.values()).map(
-        (rel) => projectStoredRelationship(rel, raw.pathRelFirstDirection.get(rel.id) ?? "outbound")
+        (rel) => projectStoredRelationship(rel, raw.pathRelFirstDirection.get(rel.id) ?? "out")
       );
     }
     const limit = spec.limit ?? 50;
     let total;
-    if (spec.returnMode === "path") {
+    if (projectionEmitted) {
+      total = aggregations.length;
+    } else 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,
@@ -2705,16 +2958,17 @@ Verify the ARM/Bicep template that provisioned the container.`
         maxResults: limit,
         maxDepth: spec.steps?.length
       },
-      truncated: total >= limit,
-      truncationReason: total >= limit ? "result_limit" : void 0
+      truncated,
+      truncationReason: truncated ? "result_limit" : void 0
     };
     return {
       entities,
       relationships,
       paths,
+      ...aggregations !== void 0 ? { aggregations } : {},
       total,
       returned: total,
-      hasMore: total >= limit,
+      hasMore: truncated,
       queryMetadata
     };
   }
@@ -2748,7 +3002,7 @@ Verify the ARM/Bicep template that provisioned the container.`
     try {
       result = await this.conn.submit(scopedQuery, scopedParams);
     } catch (err) {
-      throw new ProviderError(
+      throw new ProviderError2(
         `Gremlin traversal failed: ${err instanceof Error ? err.message : String(err)}`,
         "Check the traversal spec and ensure the CosmosDB connection is healthy."
       );
@@ -2766,7 +3020,14 @@ Verify the ARM/Bicep template that provisioned the container.`
       requestCharge: result.requestCharge,
       compiledQuery: scopedQuery
     };
-    if (spec.returnMode === "terminal") {
+    const emitsProjection = spec.projection !== void 0 && spec.returnMode !== "all" && spec.returnMode !== "path";
+    if (emitsProjection) {
+      raw.aggregations = parseProjectionRows(
+        result.items,
+        spec.projection.properties,
+        spec.projection.mode ?? "values"
+      );
+    } else if (spec.returnMode === "terminal") {
       for (const item of result.items) {
         const stored = entityFromGremlin(item);
         raw.terminalEntities.push(stored);
@@ -2805,7 +3066,7 @@ Verify the ARM/Bicep template that provisioned the container.`
             const stored = relationshipFromGremlin(props);
             raw.relationshipMap.set(stored.id, stored);
             pathRelIds.push(stored.id);
-            const direction = lastVertexId === stored.sourceEntityId ? "outbound" : "inbound";
+            const direction = lastVertexId === stored.sourceEntityId ? "out" : "in";
             pathRelDirections.push(direction);
             if (!raw.pathRelFirstDirection.has(stored.id)) {
               raw.pathRelFirstDirection.set(stored.id, direction);
@@ -2854,6 +3115,81 @@ function unwrapGremlinValue(val) {
   if (Array.isArray(val) && val.length > 0) return val[0];
   return val;
 }
+function parseProjectionRows(items, properties, mode) {
+  const singleProperty = properties.length === 1;
+  const aggregations = [];
+  if (mode === "count") {
+    for (const item of items) {
+      const entry = readEntry(item);
+      if (entry === void 0) continue;
+      const values = singleProperty ? { [properties[0]]: normaliseProjectionScalar(entry.key) } : readProjectedMap(entry.key, properties);
+      aggregations.push({ values, count: coerceCount(entry.value) });
+    }
+    return aggregations;
+  }
+  for (const item of items) {
+    const values = singleProperty ? { [properties[0]]: normaliseProjectionScalar(item) } : readProjectedMap(item, properties);
+    aggregations.push({ values });
+  }
+  return aggregations;
+}
+function readEntry(item) {
+  if (item instanceof Map) {
+    if (item.has("key") && item.has("value")) {
+      return { key: item.get("key"), value: item.get("value") };
+    }
+    const first = item.entries().next();
+    if (!first.done) {
+      const [key, value] = first.value;
+      return { key, value };
+    }
+    return void 0;
+  }
+  if (typeof item !== "object" || item === null) return void 0;
+  const obj = item;
+  if ("key" in obj && "value" in obj) {
+    return { key: obj["key"], value: obj["value"] };
+  }
+  const keys = Object.keys(obj);
+  if (keys.length === 1) {
+    const k = keys[0];
+    return { key: k, value: obj[k] };
+  }
+  return void 0;
+}
+function readProjectedMap(row, properties) {
+  const out = {};
+  if (row instanceof Map) {
+    for (const prop of properties) {
+      out[prop] = normaliseProjectionScalar(row.get(prop));
+    }
+    return out;
+  }
+  if (typeof row === "object" && row !== null) {
+    const obj = row;
+    for (const prop of properties) {
+      out[prop] = normaliseProjectionScalar(obj[prop]);
+    }
+    return out;
+  }
+  for (const prop of properties) {
+    out[prop] = void 0;
+  }
+  return out;
+}
+function normaliseProjectionScalar(value) {
+  if (typeof value === "bigint") return Number(value);
+  return value;
+}
+function coerceCount(value) {
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string") {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : 0;
+  }
+  return 0;
+}
 function buildExploreSteps(depth, options) {
   const base = { direction: "both" };
   if (options.relationshipTypes && options.relationshipTypes.length > 0) {