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

package/dist/index.cjs

@@ -36,7 +36,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/CosmosDbProvider.ts
-var import_deep_memory5 = require("@utaba/deep-memory");
+var import_deep_memory6 = require("@utaba/deep-memory");
 
 // src/CosmosDbConnection.ts
 var import_gremlin = __toESM(require("gremlin"), 1);
@@ -319,6 +319,7 @@ function sleep2(ms) {
 }
 
 // src/mapping.ts
+var import_deep_memory = require("@utaba/deep-memory");
 var STORED_ENTITY_FIELDS = [
   "id",
   "entityType",
@@ -659,9 +660,92 @@ 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 import_deep_memory.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 import_deep_memory.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
-var import_deep_memory = require("@utaba/deep-memory");
+var import_deep_memory2 = require("@utaba/deep-memory");
 var REPO_LABEL = "_repository";
 var REPOSITORY_INDEX_VERTEX_ID = "_repository_index";
 var REPOSITORY_INDEX_PARTITION = "_index";
@@ -727,7 +811,7 @@ async function createRepository(conn, config) {
     { vid: vertexId, rid: config.repositoryId, lbl: REPO_LABEL }
   );
   if (existing.items.length > 0 && Number(existing.items[0]) > 0) {
-    throw new import_deep_memory.DuplicateRepositoryError(config.repositoryId);
+    throw new import_deep_memory2.DuplicateRepositoryError(config.repositoryId);
   }
   const currentIds = await readRepositoryIndex(conn);
   const updatedIds = currentIds.includes(config.repositoryId) ? currentIds : [...currentIds, config.repositoryId];
@@ -798,7 +882,7 @@ async function listRepositories(conn, filter) {
 async function updateRepository(conn, repositoryId, updates) {
   const vertexId = repoVertexId(repositoryId);
   const existing = await getRepository(conn, repositoryId);
-  if (!existing) throw new import_deep_memory.RepositoryNotFoundError(repositoryId);
+  if (!existing) throw new import_deep_memory2.RepositoryNotFoundError(repositoryId);
   const bindings = { vid: vertexId, rid: repositoryId };
   const props = {};
   if (updates.label !== void 0) props["repoLabel"] = updates.label;
@@ -1033,9 +1117,10 @@ async function getVocabularyChangeLog(conn, repositoryId, options) {
 }
 
 // src/queries/entity.ts
-var import_deep_memory2 = require("@utaba/deep-memory");
+var import_deep_memory3 = require("@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,
@@ -1043,14 +1128,27 @@ 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 import_deep_memory2.DuplicateEntityError(entity.id);
+    throw new import_deep_memory3.DuplicateEntityError(entity.id);
   }
   return entity;
 }
 async function getEntity(conn, repositoryId, entityId, options) {
-  const projection = (0, import_deep_memory2.buildVertexProjectChain)({ withEmbedding: options?.loadEmbeddings });
+  const projection = (0, import_deep_memory3.buildVertexProjectChain)({ withEmbedding: options?.loadEmbeddings });
   const result = await conn.submit(
     `g.V().has('repositoryId', rid).hasId(eid).has('entityType').${projection}`,
     { rid: repositoryId, eid: entityId }
@@ -1059,7 +1157,7 @@ async function getEntity(conn, repositoryId, entityId, options) {
   return entityFromGremlin(result.items[0]);
 }
 async function getEntityBySlug(conn, repositoryId, slug, options) {
-  const projection = (0, import_deep_memory2.buildVertexProjectChain)({ withEmbedding: options?.loadEmbeddings });
+  const projection = (0, import_deep_memory3.buildVertexProjectChain)({ withEmbedding: options?.loadEmbeddings });
   const result = await conn.submit(
     `g.V().has('repositoryId', rid).has('slug', slugVal).has('entityType').${projection}`,
     { rid: repositoryId, slugVal: slug }
@@ -1077,7 +1175,7 @@ async function getEntities(conn, repositoryId, entityIds, options) {
     idParams.push(paramName);
   });
   const withinClause = `within(${idParams.join(", ")})`;
-  const projection = (0, import_deep_memory2.buildVertexProjectChain)({ withEmbedding: options?.loadEmbeddings });
+  const projection = (0, import_deep_memory3.buildVertexProjectChain)({ withEmbedding: options?.loadEmbeddings });
   const result = await conn.submit(
     `g.V().has('repositoryId', rid).hasId(${withinClause}).has('entityType').${projection}`,
     bindings
@@ -1089,7 +1187,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 import_deep_memory3.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;
@@ -1106,7 +1233,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");
@@ -1117,11 +1255,11 @@ 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 projection = (0, import_deep_memory2.buildVertexProjectChain)();
+  const projection = (0, import_deep_memory3.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 import_deep_memory2.EntityNotFoundError(entityId);
+    throw new import_deep_memory3.EntityNotFoundError(entityId);
   }
   return entityFromGremlin(result.items[0]);
 }
@@ -1161,16 +1299,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}`)];
@@ -1178,7 +1333,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 },
@@ -1187,7 +1342,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
@@ -1199,7 +1354,7 @@ async function findEntities(docClient, repositoryId, query, options) {
     const filters = Object.entries(query.properties).map(
       ([key, value]) => ({ key, operator: "eq", value })
     );
-    items = items.filter((entity) => (0, import_deep_memory2.matchesPropertyFilters)(entity.properties, filters));
+    items = items.filter((entity) => (0, import_deep_memory3.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;
@@ -1213,9 +1368,10 @@ async function findEntities(docClient, repositoryId, query, options) {
 }
 
 // src/queries/relationship.ts
-var import_deep_memory3 = require("@utaba/deep-memory");
+var import_deep_memory4 = require("@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,
@@ -1225,14 +1381,27 @@ 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 import_deep_memory3.DuplicateRelationshipError(relationship.id);
+    throw new import_deep_memory4.DuplicateRelationshipError(relationship.id);
   }
   return relationship;
 }
 async function getRelationship(conn, repositoryId, relationshipId) {
-  const projection = (0, import_deep_memory3.buildEdgeProjectChain)();
+  const projection = (0, import_deep_memory4.buildEdgeProjectChain)();
   const result = await conn.submit(
     `g.E().hasId(relId).has('repositoryId', rid).${projection}`,
     { relId: relationshipId, rid: repositoryId }
@@ -1279,7 +1448,7 @@ async function getEntityRelationships(conn, repositoryId, entityId, options) {
     unionQuery = `g.V().has('repositoryId', rid).hasId(eid).has('entityType').union(inE()${typeFilter}, outE()${typeFilter}.has('bidirectional', true))`;
   }
   const baseQuery = unionQuery ?? `${edgeTraversal}${typeFilter}`;
-  const projection = (0, import_deep_memory3.buildEdgeProjectChain)();
+  const projection = (0, import_deep_memory4.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),
@@ -1291,7 +1460,7 @@ async function getEntityRelationships(conn, repositoryId, entityId, options) {
   const rawItems = dataResult.items;
   let items = rawItems.map(relationshipFromGremlin);
   if (hasPropertyFilters) {
-    items = items.filter((rel) => (0, import_deep_memory3.matchesPropertyFilters)(rel.properties, options.propertyFilters));
+    items = items.filter((rel) => (0, import_deep_memory4.matchesPropertyFilters)(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;
@@ -1381,7 +1550,7 @@ function isInTimeRange(timestamp, timeRange) {
 }
 
 // src/queries/adaptive-import.ts
-var import_deep_memory4 = require("@utaba/deep-memory");
+var import_deep_memory5 = require("@utaba/deep-memory");
 var DEFAULT_MIN = 1;
 var DEFAULT_START = 5;
 var DEFAULT_MAX = 32;
@@ -1632,7 +1801,7 @@ async function runAdaptive(items, controller, fn) {
   }
   await Promise.all(workers);
   if (aborted) {
-    throw new import_deep_memory4.ImportThrottleAbortError(
+    throw new import_deep_memory5.ImportThrottleAbortError(
       controller.getConcurrency(),
       controller.getConsecutiveThrottlesAtMin(),
       controller.getCompleted(),
@@ -1778,8 +1947,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,
@@ -1787,7 +1960,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 = {
@@ -1798,7 +1984,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 = {
@@ -1807,7 +2006,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 = {
@@ -1818,7 +2030,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
@@ -1838,7 +2063,7 @@ var CosmosDbProvider = class {
   conn;
   docClient;
   config;
-  compiler = new import_deep_memory5.GremlinCompiler();
+  compiler = new import_deep_memory6.GremlinCompiler();
   reportUsage;
   /**
    * Per-process vocabulary cache, keyed by repositoryId. Read lazily by
@@ -1849,7 +2074,7 @@ var CosmosDbProvider = class {
   vocabularyCache = /* @__PURE__ */ new Map();
   constructor(config) {
     this.config = config;
-    this.reportUsage = (0, import_deep_memory5.createSafeSink)(config.reportUsage);
+    this.reportUsage = (0, import_deep_memory6.createSafeSink)(config.reportUsage);
     this.conn = new CosmosDbConnection({
       endpoint: config.endpoint,
       key: config.key,
@@ -1912,8 +2137,8 @@ var CosmosDbProvider = class {
    * ever reaching query construction.
    */
   assertValidRepositoryId(repositoryId) {
-    if (!(0, import_deep_memory5.isValidUuid)(repositoryId)) {
-      throw new import_deep_memory5.InvalidInputError(
+    if (!(0, import_deep_memory6.isValidUuid)(repositoryId)) {
+      throw new import_deep_memory6.InvalidInputError(
         "repositoryId",
         `repositoryId must be a valid v4 UUID; got '${repositoryId}'`
       );
@@ -1989,7 +2214,7 @@ var CosmosDbProvider = class {
         schemaVersion: SCHEMA_VERSION
       };
     } catch (err) {
-      throw new import_deep_memory5.ProviderError(
+      throw new import_deep_memory6.ProviderError(
         `Failed to ensure CosmosDB schema: ${err instanceof Error ? err.message : String(err)}`,
         "Verify the CosmosDB REST endpoint is accessible and the Gremlin endpoint is reachable."
       );
@@ -2406,7 +2631,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) {
@@ -2432,17 +2657,21 @@ Verify the ARM/Bicep template that provisioned the container.`
           if (!matchesDirection || !connectedId) continue;
           if (visited.has(connectedId)) continue;
           if (options.relationshipPropertyFilters && options.relationshipPropertyFilters.length > 0) {
-            if (!(0, import_deep_memory5.matchesPropertyFilters)(rel.properties, options.relationshipPropertyFilters)) continue;
+            if (!(0, import_deep_memory6.matchesPropertyFilters)(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;
+          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: [] };
           }
@@ -2660,7 +2889,7 @@ Verify the ARM/Bicep template that provisioned the container.`
     const raw = await this.executeTraversal(repositoryId, spec);
     const detailLevel = spec.detailLevel ?? "summary";
     const projectStoredEntity = (stored) => {
-      const projected = (0, import_deep_memory5.projectEntity)(stored, detailLevel);
+      const projected = (0, import_deep_memory6.projectEntity)(stored, detailLevel);
       if (!spec.includeProvenance) {
         delete projected["provenance"];
       }
@@ -2677,8 +2906,11 @@ Verify the ARM/Bicep template that provisioned the container.`
     let entities = [];
     let relationships;
     let paths;
+    const aggregations = raw.aggregations;
+    const projectionEmitted = aggregations !== void 0;
     const rangeRowCount = spec.returnMode === "all" ? raw.allEntities.length + raw.allRelationships.length : 0;
-    if (spec.returnMode === "terminal") {
+    if (projectionEmitted) {
+    } else if (spec.returnMode === "terminal") {
       entities = raw.terminalEntities.map(projectStoredEntity);
       relationships = void 0;
     } else if (spec.returnMode === "all") {
@@ -2706,7 +2938,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 import_deep_memory5.ProviderError(
+            throw new import_deep_memory6.ProviderError(
               "Unpacking Gremlin path: entity referenced by path is missing from the result",
               "This indicates a Gremlin response shape mismatch \u2014 inspect compiledQuery."
             );
@@ -2716,7 +2948,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 import_deep_memory5.ProviderError(
+            throw new import_deep_memory6.ProviderError(
               "Unpacking Gremlin path: relationship referenced by path is missing from the result",
               "This indicates a Gremlin response shape mismatch \u2014 inspect compiledQuery."
             );
@@ -2730,7 +2962,9 @@ Verify the ARM/Bicep template that provisioned the container.`
     }
     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);
@@ -2755,6 +2989,7 @@ Verify the ARM/Bicep template that provisioned the container.`
       entities,
       relationships,
       paths,
+      ...aggregations !== void 0 ? { aggregations } : {},
       total,
       returned: total,
       hasMore: truncated,
@@ -2791,7 +3026,7 @@ Verify the ARM/Bicep template that provisioned the container.`
     try {
       result = await this.conn.submit(scopedQuery, scopedParams);
     } catch (err) {
-      throw new import_deep_memory5.ProviderError(
+      throw new import_deep_memory6.ProviderError(
         `Gremlin traversal failed: ${err instanceof Error ? err.message : String(err)}`,
         "Check the traversal spec and ensure the CosmosDB connection is healthy."
       );
@@ -2809,7 +3044,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);
@@ -2897,6 +3139,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) {