@utaba/deep-memory-storage-neo4j 0.19.0

package/dist/index.js

@@ -0,0 +1,3299 @@
+// src/Neo4jStorageProvider.ts
+import {
+  ProviderError as ProviderError7,
+  RepositoryNotFoundError,
+  createSafeSink,
+  matchesPropertyFilters as matchesPropertyFilters2,
+  projectEntity
+} from "@utaba/deep-memory";
+
+// src/Neo4jTraversalExecutor.ts
+import { CypherCompiler, ProviderError as ProviderError2 } from "@utaba/deep-memory";
+
+// src/mapping.ts
+import { ProviderError } from "@utaba/deep-memory";
+var MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+var MIN_SAFE_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
+function bigintToSafeNumber(value) {
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") {
+    if (value > MAX_SAFE_BIGINT || value < MIN_SAFE_BIGINT) {
+      throw new ProviderError(
+        `Neo4j integer value ${value.toString()} exceeds Number.MAX_SAFE_INTEGER \u2014 refusing to truncate.`
+      );
+    }
+    return Number(value);
+  }
+  throw new ProviderError(
+    `bigintToSafeNumber expected bigint | number, received ${typeof value}.`
+  );
+}
+function entityFromRecord(record, alias = "n") {
+  return entityFromProperties(extractPropertyBag(record, alias));
+}
+function relationshipFromRecord(record, alias = "r") {
+  return relationshipFromProperties(extractPropertyBag(record, alias));
+}
+function entityFromProperties(props) {
+  const summary = optionalString(props, "summary");
+  const data = optionalString(props, "data");
+  const dataFormat = optionalString(props, "dataFormat");
+  const embedding = parseEmbedding(props);
+  const entity = {
+    id: requireString(props, "id"),
+    slug: requireString(props, "slug"),
+    entityType: requireString(props, "entityType"),
+    label: requireString(props, "label"),
+    properties: parsePropertiesBlob(props),
+    provenance: provenanceFromProperties(props)
+  };
+  if (summary !== void 0) entity.summary = summary;
+  if (data !== void 0) entity.data = data;
+  if (dataFormat !== void 0) entity.dataFormat = dataFormat;
+  if (embedding !== void 0) entity.embedding = embedding;
+  return entity;
+}
+function relationshipFromProperties(props) {
+  return {
+    id: requireString(props, "id"),
+    relationshipType: requireString(props, "relationshipType"),
+    sourceEntityId: requireString(props, "sourceEntityId"),
+    targetEntityId: requireString(props, "targetEntityId"),
+    properties: parsePropertiesBlob(props),
+    bidirectional: requireBoolean(props, "bidirectional"),
+    provenance: provenanceFromProperties(props)
+  };
+}
+function repositoryFromRecord(record, alias = "r") {
+  return repositoryFromProperties(extractPropertyBag(record, alias));
+}
+function repositorySummaryFromRecord(record, alias = "r") {
+  return repositorySummaryFromProperties(extractPropertyBag(record, alias));
+}
+function repositoryFromProperties(props) {
+  const type = optionalString(props, "type");
+  const description = optionalString(props, "description");
+  const legal = optionalString(props, "legal");
+  const owner = optionalString(props, "owner");
+  const metadata = parseOptionalJsonObject(props, "metadata");
+  const repo = {
+    repositoryId: requireString(props, "repositoryId"),
+    label: requireString(props, "label"),
+    governanceConfig: parseRequiredJsonObject(props, "governanceConfig"),
+    createdAt: requireString(props, "createdAt"),
+    createdBy: requireString(props, "createdBy")
+  };
+  if (type !== void 0) repo.type = type;
+  if (description !== void 0) repo.description = description;
+  if (legal !== void 0) repo.legal = legal;
+  if (owner !== void 0) repo.owner = owner;
+  if (metadata !== void 0) repo.metadata = metadata;
+  return repo;
+}
+function repositorySummaryFromProperties(props) {
+  const type = optionalString(props, "type");
+  const description = optionalString(props, "description");
+  const summary = {
+    repositoryId: requireString(props, "repositoryId"),
+    label: requireString(props, "label"),
+    governanceConfig: parseRequiredJsonObject(props, "governanceConfig")
+  };
+  if (type !== void 0) summary.type = type;
+  if (description !== void 0) summary.description = description;
+  return summary;
+}
+function changeRecordFromRecord(record, alias = "e") {
+  return changeRecordFromProperties(extractPropertyBag(record, alias));
+}
+function changeRecordFromProperties(props) {
+  const previousVersion = optionalString(props, "previousVersion");
+  const approvedBy = optionalString(props, "approvedBy");
+  const approvedAt = optionalString(props, "approvedAt");
+  const record = {
+    changeId: requireString(props, "changeId"),
+    changeType: requireChangeType(props, "changeType"),
+    typeName: requireString(props, "typeName"),
+    newVersion: requireString(props, "newVersion"),
+    proposedBy: requireString(props, "proposedBy"),
+    proposedAt: requireString(props, "proposedAt"),
+    reason: requireString(props, "reason")
+  };
+  if (previousVersion !== void 0) record.previousVersion = previousVersion;
+  if (approvedBy !== void 0) record.approvedBy = approvedBy;
+  if (approvedAt !== void 0) record.approvedAt = approvedAt;
+  return record;
+}
+var STORED_ENTITY_FIELDS = [
+  "id",
+  "entityType",
+  "label",
+  "slug",
+  "summary",
+  "properties",
+  "data",
+  "dataFormat",
+  "createdBy",
+  "createdByType",
+  "createdAt",
+  "createdInConversation",
+  "createdFromMessage",
+  "modifiedBy",
+  "modifiedByType",
+  "modifiedAt",
+  "modifiedInConversation",
+  "modifiedFromMessage"
+];
+function buildEntityProjection(options) {
+  const alias = options?.alias ?? "n";
+  const parts = STORED_ENTITY_FIELDS.map((field) => `${alias}.${field} AS ${field}`);
+  if (options?.loadEmbeddings === true) {
+    parts.push(`${alias}.embedding AS embedding`);
+  }
+  return parts.join(", ");
+}
+var RESERVED_ENTITY_PROPERTY_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "repositoryId",
+  "entityType",
+  "label",
+  "slug",
+  "summary",
+  "properties",
+  "data",
+  "dataFormat",
+  "embedding",
+  "createdBy",
+  "createdByType",
+  "createdAt",
+  "createdInConversation",
+  "createdFromMessage",
+  "modifiedBy",
+  "modifiedByType",
+  "modifiedAt",
+  "modifiedInConversation",
+  "modifiedFromMessage"
+]);
+var USER_PROPERTY_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertSafeUserPropertyKey(key) {
+  if (!USER_PROPERTY_KEY_PATTERN.test(key)) {
+    throw new ProviderError(
+      `Entity property key "${key}" is not a valid Cypher identifier \u2014 must match ${USER_PROPERTY_KEY_PATTERN.source}. User-property keys are interpolated into Cypher REMOVE / predicate slots (the key slot cannot be parameterised), so an unsafe value would widen the injection surface.`
+    );
+  }
+  if (RESERVED_ENTITY_PROPERTY_KEYS.has(key)) {
+    throw new ProviderError(
+      `Entity property key "${key}" collides with a schema-managed field. Reserved names: ${Array.from(RESERVED_ENTITY_PROPERTY_KEYS).join(", ")}.`
+    );
+  }
+  return key;
+}
+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 entityToParams(entity) {
+  const p = entity.provenance;
+  return {
+    id: entity.id,
+    entityType: entity.entityType,
+    label: entity.label,
+    slug: entity.slug,
+    summary: entity.summary ?? null,
+    properties: JSON.stringify(entity.properties),
+    data: entity.data ?? null,
+    dataFormat: entity.dataFormat ?? null,
+    embedding: entity.embedding ?? null,
+    createdBy: p.createdBy,
+    createdByType: p.createdByType,
+    createdAt: p.createdAt,
+    createdInConversation: p.createdInConversation ?? null,
+    createdFromMessage: p.createdFromMessage ?? null,
+    modifiedBy: p.modifiedBy,
+    modifiedByType: p.modifiedByType,
+    modifiedAt: p.modifiedAt,
+    modifiedInConversation: p.modifiedInConversation ?? null,
+    modifiedFromMessage: p.modifiedFromMessage ?? null
+  };
+}
+function entityUserPropertyParams(properties) {
+  const out = {};
+  for (const [key, value] of Object.entries(properties)) {
+    assertSafeUserPropertyKey(key);
+    if (isNativeStorableValue(value)) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+var STORED_RELATIONSHIP_FIELDS = [
+  "id",
+  "relationshipType",
+  "sourceEntityId",
+  "targetEntityId",
+  "properties",
+  "bidirectional",
+  "createdBy",
+  "createdByType",
+  "createdAt",
+  "createdInConversation",
+  "createdFromMessage",
+  "modifiedBy",
+  "modifiedByType",
+  "modifiedAt",
+  "modifiedInConversation",
+  "modifiedFromMessage"
+];
+function buildRelationshipProjection(options) {
+  const alias = options?.alias ?? "r";
+  return STORED_RELATIONSHIP_FIELDS.map((field) => `${alias}.${field} AS ${field}`).join(", ");
+}
+function relationshipToParams(rel) {
+  const p = rel.provenance;
+  return {
+    id: rel.id,
+    relationshipType: rel.relationshipType,
+    sourceEntityId: rel.sourceEntityId,
+    targetEntityId: rel.targetEntityId,
+    properties: JSON.stringify(rel.properties ?? {}),
+    bidirectional: rel.bidirectional,
+    createdBy: p.createdBy,
+    createdByType: p.createdByType,
+    createdAt: p.createdAt,
+    createdInConversation: p.createdInConversation ?? null,
+    createdFromMessage: p.createdFromMessage ?? null,
+    modifiedBy: p.modifiedBy,
+    modifiedByType: p.modifiedByType,
+    modifiedAt: p.modifiedAt,
+    modifiedInConversation: p.modifiedInConversation ?? null,
+    modifiedFromMessage: p.modifiedFromMessage ?? null
+  };
+}
+var RELATIONSHIP_TYPE_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertSafeRelationshipType(value) {
+  if (!RELATIONSHIP_TYPE_PATTERN.test(value)) {
+    throw new ProviderError(
+      `Relationship type "${value}" is not a valid Cypher identifier \u2014 must match ${RELATIONSHIP_TYPE_PATTERN.source}. Cypher 25 does not allow parameterising the relationship-type slot, so the value is interpolated directly into the query string and an unsafe value would otherwise widen the injection surface.`
+    );
+  }
+  return value;
+}
+function repositoryCreateParams(config) {
+  return {
+    type: config.type ?? null,
+    label: config.label,
+    description: config.description ?? null,
+    legal: config.legal ?? null,
+    owner: config.owner ?? null,
+    governanceConfig: JSON.stringify(config.governanceConfig),
+    metadata: config.metadata !== void 0 ? JSON.stringify(config.metadata) : null,
+    createdAt: config.createdAt,
+    createdBy: config.createdBy
+  };
+}
+function extractPropertyBag(record, alias) {
+  if (record.keys.includes(alias)) {
+    const value = record.get(alias);
+    if (isNodeLike(value)) return value.properties;
+    if (isRelationshipLike(value)) return value.properties;
+  }
+  const bag = {};
+  for (const key of record.keys) {
+    if (typeof key !== "string") continue;
+    bag[key] = record.get(key);
+  }
+  return bag;
+}
+function isNodeLike(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.properties === "object" && v.properties !== null && !Array.isArray(v.properties) && Array.isArray(v.labels);
+}
+function isRelationshipLike(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.properties === "object" && v.properties !== null && !Array.isArray(v.properties) && typeof v.type === "string";
+}
+function provenanceFromProperties(props) {
+  const provenance = {
+    createdBy: requireString(props, "createdBy"),
+    createdByType: requireActorType(props, "createdByType"),
+    createdAt: requireString(props, "createdAt"),
+    modifiedBy: requireString(props, "modifiedBy"),
+    modifiedByType: requireActorType(props, "modifiedByType"),
+    modifiedAt: requireString(props, "modifiedAt")
+  };
+  const createdInConversation = optionalString(props, "createdInConversation");
+  const createdFromMessage = optionalString(props, "createdFromMessage");
+  const modifiedInConversation = optionalString(props, "modifiedInConversation");
+  const modifiedFromMessage = optionalString(props, "modifiedFromMessage");
+  if (createdInConversation !== void 0) provenance.createdInConversation = createdInConversation;
+  if (createdFromMessage !== void 0) provenance.createdFromMessage = createdFromMessage;
+  if (modifiedInConversation !== void 0) provenance.modifiedInConversation = modifiedInConversation;
+  if (modifiedFromMessage !== void 0) provenance.modifiedFromMessage = modifiedFromMessage;
+  return provenance;
+}
+function requireString(props, key) {
+  const value = props[key];
+  if (typeof value !== "string") {
+    throw new ProviderError(
+      `Neo4j record is missing required string field "${key}" (got ${describeType(value)}).`
+    );
+  }
+  return value;
+}
+function requireActorType(props, key) {
+  const value = requireString(props, key);
+  if (value !== "user" && value !== "agent") {
+    throw new ProviderError(
+      `Neo4j record field "${key}" must be "user" or "agent" (got ${JSON.stringify(value)}).`
+    );
+  }
+  return value;
+}
+var CHANGE_TYPES = [
+  "entity_type_added",
+  "relationship_type_added",
+  "entity_type_modified",
+  "relationship_type_modified",
+  "entity_type_removed",
+  "relationship_type_removed"
+];
+function requireChangeType(props, key) {
+  const value = requireString(props, key);
+  if (!CHANGE_TYPES.includes(value)) {
+    throw new ProviderError(
+      `Neo4j record field "${key}" must be one of the VocabularyChangeRecord change types (got ${JSON.stringify(value)}).`
+    );
+  }
+  return value;
+}
+function requireBoolean(props, key) {
+  const value = props[key];
+  if (typeof value !== "boolean") {
+    throw new ProviderError(
+      `Neo4j record is missing required boolean field "${key}" (got ${describeType(value)}).`
+    );
+  }
+  return value;
+}
+function optionalString(props, key) {
+  const value = props[key];
+  if (value === void 0 || value === null || value === "") return void 0;
+  if (typeof value !== "string") {
+    throw new ProviderError(
+      `Neo4j record field "${key}" must be a string or empty (got ${describeType(value)}).`
+    );
+  }
+  return value;
+}
+function parsePropertiesBlob(props) {
+  const raw = props["properties"];
+  if (raw === void 0 || raw === null || raw === "") return {};
+  if (typeof raw !== "string") {
+    throw new ProviderError(
+      `Neo4j record field "properties" must be a JSON string (got ${describeType(raw)}).`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new ProviderError(`Neo4j record field "properties" is not valid JSON: ${detail}.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new ProviderError(
+      `Neo4j record field "properties" must decode to a JSON object (got ${describeType(parsed)}).`
+    );
+  }
+  return parsed;
+}
+function parseRequiredJsonObject(props, key) {
+  const raw = props[key];
+  if (typeof raw !== "string" || raw === "") {
+    throw new ProviderError(
+      `Neo4j record field "${key}" must be a non-empty JSON string (got ${describeType(raw)}).`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new ProviderError(`Neo4j record field "${key}" is not valid JSON: ${detail}.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new ProviderError(
+      `Neo4j record field "${key}" must decode to a JSON object (got ${describeType(parsed)}).`
+    );
+  }
+  return parsed;
+}
+function parseOptionalJsonObject(props, key) {
+  const raw = props[key];
+  if (raw === void 0 || raw === null || raw === "") return void 0;
+  if (typeof raw !== "string") {
+    throw new ProviderError(
+      `Neo4j record field "${key}" must be a JSON string (got ${describeType(raw)}).`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new ProviderError(`Neo4j record field "${key}" is not valid JSON: ${detail}.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new ProviderError(
+      `Neo4j record field "${key}" must decode to a JSON object (got ${describeType(parsed)}).`
+    );
+  }
+  return parsed;
+}
+function parseEmbedding(props) {
+  const raw = props["embedding"];
+  if (raw === void 0 || raw === null) return void 0;
+  if (!Array.isArray(raw)) {
+    throw new ProviderError(
+      `Neo4j record field "embedding" must be an array of numbers (got ${describeType(raw)}).`
+    );
+  }
+  for (const v of raw) {
+    if (typeof v !== "number") {
+      throw new ProviderError(
+        `Neo4j record field "embedding" must contain only numbers (got ${describeType(v)}).`
+      );
+    }
+  }
+  return raw;
+}
+function describeType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+// src/Neo4jTraversalExecutor.ts
+var Neo4jTraversalExecutor = class {
+  constructor(connection, config) {
+    this.connection = connection;
+    this.config = config;
+  }
+  connection;
+  config;
+  compiler = new CypherCompiler();
+  /**
+   * Compile, scope, submit, and parse a traversal spec. The provider's vocab
+   * cache is the source of `vocabulary` — `traverse` / `exploreNeighborhood`
+   * / `findPaths` look it up once and pass it down.
+   */
+  async execute(repositoryId, spec, vocabulary) {
+    const startTime = Date.now();
+    const compiled = this.compiler.compile(spec, vocabulary);
+    const scopedQuery = this.scopeQuery(compiled.query);
+    const finalQuery = this.config.profileTraversals ? `PROFILE ${scopedQuery}` : scopedQuery;
+    const params = coerceSkipLimitToBigInt(finalQuery, compiled.params);
+    let result;
+    try {
+      result = await this.connection.executeQuery(
+        finalQuery,
+        params,
+        { repositoryId, routing: "READ" }
+      );
+    } catch (err) {
+      throw new ProviderError2(
+        `Neo4j traversal failed: ${err instanceof Error ? err.message : String(err)}`,
+        "Inspect the compiled Cypher in queryMetadata.compiledQuery and confirm the spec passed validation."
+      );
+    }
+    const executionTimeMs = Date.now() - startTime;
+    const summary = result.summary;
+    const serverMs = bigintLike(summary.resultConsumedAfter);
+    const raw = {
+      terminalEntities: [],
+      allEntities: [],
+      allRelationships: [],
+      pathRows: [],
+      entityMap: /* @__PURE__ */ new Map(),
+      relationshipMap: /* @__PURE__ */ new Map(),
+      pathRelFirstDirection: /* @__PURE__ */ new Map(),
+      executionTimeMs,
+      serverMs,
+      compiledQuery: finalQuery
+    };
+    if (this.config.profileTraversals && summary.profile !== void 0) {
+      raw.profile = summariseProfile(summary.profile);
+    }
+    const emitsProjection = spec.projection !== void 0 && spec.returnMode !== "path" && spec.returnMode !== "all";
+    if (emitsProjection) {
+      this.parseProjectionRows(result.records, raw, spec.projection.properties, spec.projection.mode ?? "values");
+    } else if (spec.returnMode === "terminal") {
+      this.parseTerminalRows(result.records, raw);
+    } else if (spec.returnMode === "all") {
+      this.parseAllRows(result.records, raw);
+    } else {
+      this.parsePathRows(result.records, raw);
+    }
+    return raw;
+  }
+  /**
+   * Parse the server-aggregated projection rows. Each row has one column per
+   * projected property and, when mode is 'count', an additional `count` column.
+   * Values arrive as native scalars / strings / BigInts; counts arrive as
+   * BigInt (per the driver's `useBigInt: true` configuration) and coerce to
+   * Number for the JSON wire shape.
+   */
+  parseProjectionRows(records, raw, propertyNames, mode) {
+    const aggregations = [];
+    for (const record of records) {
+      const values = {};
+      for (const prop of propertyNames) {
+        values[prop] = normaliseScalar(record.get(prop));
+      }
+      if (mode === "count") {
+        const rawCount = record.get("count");
+        const count = typeof rawCount === "bigint" ? Number(rawCount) : typeof rawCount === "number" ? rawCount : 0;
+        aggregations.push({ values, count });
+      } else {
+        aggregations.push({ values });
+      }
+    }
+    raw.aggregations = aggregations;
+  }
+  /**
+   * Inject the repositoryId scope onto the start node so the chokepoint's
+   * `$rid` assertion is satisfied structurally and the planner uses the
+   * `(repositoryId, id)` unique constraint's backing index for the seek.
+   *
+   * The compiler always emits `(n0)` as the first match part (it never adds a
+   * label or property map there) — we rewrite that single occurrence. The
+   * provider's defence-in-depth (D3b layer 3) prevents cross-repository edges
+   * from existing in the first place, so scoping just the start node is
+   * sufficient — once the planner anchors on a node in this repo, every
+   * reachable node is also in this repo.
+   */
+  scopeQuery(query) {
+    const scope = "(n0:_Entity {repositoryId: $rid})";
+    const replaced = query.replace("(n0)", scope);
+    if (replaced === query) {
+      throw new ProviderError2(
+        "Neo4jTraversalExecutor: compiled query did not contain the expected `(n0)` start-node form; cannot inject repositoryId scope.",
+        "This indicates a CypherCompiler emission change that the provider has not been updated for."
+      );
+    }
+    return replaced;
+  }
+  parseTerminalRows(records, raw) {
+    for (const record of records) {
+      for (const key of record.keys) {
+        if (typeof key !== "string") continue;
+        const value = record.get(key);
+        if (isNode(value)) {
+          const stored = entityFromNode(value);
+          raw.terminalEntities.push(stored);
+          if (!raw.entityMap.has(stored.id)) raw.entityMap.set(stored.id, stored);
+        }
+      }
+    }
+  }
+  parseAllRows(records, raw) {
+    for (const record of records) {
+      for (const key of record.keys) {
+        if (typeof key !== "string") continue;
+        const value = record.get(key);
+        if (isNode(value)) {
+          const stored = entityFromNode(value);
+          if (!raw.entityMap.has(stored.id)) {
+            raw.entityMap.set(stored.id, stored);
+            raw.allEntities.push(stored);
+          }
+        } else if (isRelationship(value)) {
+          const stored = relationshipFromRelationship(value);
+          if (!raw.relationshipMap.has(stored.id)) {
+            raw.relationshipMap.set(stored.id, stored);
+            raw.allRelationships.push(stored);
+          }
+        }
+      }
+    }
+  }
+  parsePathRows(records, raw) {
+    for (const record of records) {
+      const pathNodes = record.get("pathNodes");
+      const pathRels = record.get("pathRels");
+      if (!Array.isArray(pathNodes) || !Array.isArray(pathRels)) continue;
+      const pathEntityIds = [];
+      const pathRelIds = [];
+      const pathRelDirections = [];
+      let previousElementId;
+      for (const node of pathNodes) {
+        if (!isNode(node)) continue;
+        const stored = entityFromNode(node);
+        if (!raw.entityMap.has(stored.id)) raw.entityMap.set(stored.id, stored);
+        pathEntityIds.push(stored.id);
+      }
+      for (let i = 0; i < pathRels.length; i++) {
+        const rel = pathRels[i];
+        if (!isRelationship(rel)) continue;
+        const stored = relationshipFromRelationship(rel);
+        if (!raw.relationshipMap.has(stored.id)) raw.relationshipMap.set(stored.id, stored);
+        pathRelIds.push(stored.id);
+        const segmentStartNode = pathNodes[i];
+        const segmentStartElementId = isNode(segmentStartNode) ? segmentStartNode.elementId : previousElementId;
+        const direction = segmentStartElementId !== void 0 && rel.startNodeElementId === segmentStartElementId ? "out" : "in";
+        pathRelDirections.push(direction);
+        if (!raw.pathRelFirstDirection.has(stored.id)) {
+          raw.pathRelFirstDirection.set(stored.id, direction);
+        }
+        const segmentEndNode = pathNodes[i + 1];
+        if (isNode(segmentEndNode)) previousElementId = segmentEndNode.elementId;
+      }
+      raw.pathRows.push({
+        entityIds: pathEntityIds,
+        relationshipIds: pathRelIds,
+        relationshipDirections: pathRelDirections
+      });
+    }
+  }
+};
+function isNode(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.elementId === "string" && Array.isArray(v.labels) && typeof v.properties === "object" && v.properties !== null;
+}
+function isRelationship(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.elementId === "string" && typeof v.type === "string" && typeof v.startNodeElementId === "string" && typeof v.endNodeElementId === "string" && typeof v.properties === "object" && v.properties !== null;
+}
+function entityFromNode(node) {
+  return entityFromProperties(node.properties);
+}
+function relationshipFromRelationship(rel) {
+  return relationshipFromProperties(rel.properties);
+}
+function bigintLike(value) {
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "number") return value;
+  return 0;
+}
+function normaliseScalar(value) {
+  if (typeof value === "bigint") return Number(value);
+  return value;
+}
+var SKIP_LIMIT_PARAM_PATTERN = /\b(?:SKIP|LIMIT)\s+\$(\w+)/gi;
+function coerceSkipLimitToBigInt(cypher, params) {
+  const targetKeys = /* @__PURE__ */ new Set();
+  for (const match of cypher.matchAll(SKIP_LIMIT_PARAM_PATTERN)) {
+    if (match[1] !== void 0) targetKeys.add(match[1]);
+  }
+  if (targetKeys.size === 0) return params;
+  const out = { ...params };
+  for (const key of targetKeys) {
+    const value = out[key];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      out[key] = BigInt(Math.trunc(value));
+    }
+  }
+  return out;
+}
+function summariseProfile(plan) {
+  let total = 0;
+  const visit = (node) => {
+    if (node === void 0) return;
+    const hits = node.dbHits;
+    if (typeof hits === "bigint") total += Number(hits);
+    else if (typeof hits === "number") total += hits;
+    for (const child of node.children ?? []) visit(child);
+  };
+  visit(plan);
+  return { totalDbHits: total, rootOperator: plan.operatorType ?? "unknown" };
+}
+
+// src/Neo4jConnection.ts
+import neo4j from "neo4j-driver";
+import { ProviderError as ProviderError3 } from "@utaba/deep-memory";
+
+// src/usageScope.ts
+import { AsyncLocalStorage } from "async_hooks";
+var COUNTER_KEYS = [
+  "nodesCreated",
+  "nodesDeleted",
+  "relationshipsCreated",
+  "relationshipsDeleted",
+  "propertiesSet",
+  "labelsAdded",
+  "labelsRemoved",
+  "indexesAdded",
+  "indexesRemoved",
+  "constraintsAdded",
+  "constraintsRemoved"
+];
+var store = new AsyncLocalStorage();
+function createUsageScope() {
+  return {
+    calls: 0,
+    recordCount: 0,
+    serverMs: 0,
+    availableAfterMs: 0,
+    counters: {}
+  };
+}
+function runInUsageScope(scope, fn) {
+  return store.run(scope, fn);
+}
+function recordRoundTrip(summary, recordCount) {
+  const scope = store.getStore();
+  if (scope === void 0) return;
+  scope.calls += 1;
+  scope.recordCount += recordCount;
+  if (summary.resultConsumedAfter !== void 0) {
+    scope.serverMs += bigintToSafeNumber(summary.resultConsumedAfter);
+  }
+  if (summary.resultAvailableAfter !== void 0) {
+    scope.availableAfterMs += bigintToSafeNumber(summary.resultAvailableAfter);
+  }
+  const stats = summary.counters !== void 0 ? summary.counters.updates() : void 0;
+  if (stats !== void 0) {
+    for (const key of COUNTER_KEYS) {
+      const value = stats[key];
+      if (typeof value === "number" && value !== 0) {
+        scope.counters[key] = (scope.counters[key] ?? 0) + value;
+      }
+    }
+  }
+}
+function buildUsageDetails(scope) {
+  const details = {
+    calls: scope.calls,
+    recordCount: scope.recordCount,
+    availableAfterMs: scope.availableAfterMs
+  };
+  for (const [key, value] of Object.entries(scope.counters)) {
+    if (value !== 0) details[key] = value;
+  }
+  return details;
+}
+
+// src/Neo4jConnection.ts
+var DEFAULT_DATABASE = "neo4j";
+var DEFAULT_USER_AGENT = "@utaba/deep-memory-storage-neo4j";
+var RID_TOKEN_PATTERN = /\$rid\b/;
+var NOTIFICATION_QUERY_TRUNCATION = 200;
+var Neo4jConnection = class {
+  driver;
+  database;
+  constructor(config) {
+    this.database = config.database ?? DEFAULT_DATABASE;
+    this.driver = neo4j.driver(
+      config.uri,
+      neo4j.auth.basic(config.username, config.password),
+      {
+        // BigInt for INTEGER avoids silent precision loss on counts that may
+        // exceed Number.MAX_SAFE_INTEGER — see D6b. The mapping layer
+        // narrows BigInt → Number at the public-API boundary.
+        useBigInt: true,
+        userAgent: config.userAgent ?? DEFAULT_USER_AGENT,
+        ...config.maxTransactionRetryTime !== void 0 ? { maxTransactionRetryTime: config.maxTransactionRetryTime } : {}
+      }
+    );
+  }
+  /** Verify the driver can reach the server. Throws on failure. */
+  async verifyConnectivity() {
+    await this.driver.verifyConnectivity({ database: this.database });
+  }
+  /** Returns server version / edition metadata for diagnostics. */
+  async getServerInfo() {
+    return this.driver.getServerInfo({ database: this.database });
+  }
+  /** Close the driver and release all connections. */
+  async close() {
+    await this.driver.close();
+  }
+  /**
+   * Run a single-statement query scoped to a repository.
+   *
+   * Required `repositoryId` binds `$rid` for the caller. The Cypher string
+   * MUST reference `$rid` somewhere in a predicate or property map; absence
+   * throws `ProviderError` as a programming error (D3b layer 2).
+   */
+  async executeQuery(cypher, params, options) {
+    this.assertRepositoryId(options.repositoryId);
+    this.assertScoped(cypher);
+    const result = await this.driver.executeQuery(
+      cypher,
+      { ...params, rid: options.repositoryId },
+      {
+        database: this.database,
+        ...options.routing !== void 0 ? { routing: options.routing } : {}
+      }
+    );
+    recordRoundTrip(result.summary, result.records.length);
+    this.surfaceNotifications(cypher, result.summary);
+    return result;
+  }
+  /**
+   * Run a managed write transaction scoped to a repository. Use only when
+   * more than one Cypher statement must commit atomically — single-statement
+   * writes go through `executeQuery` so the driver handles transient-error
+   * retry uniformly (D2b).
+   *
+   * Every `tx.run` call inside `txFn` is wrapped to inject `$rid` and assert
+   * scope, so the same isolation enforcement applies as on the default path.
+   * The transaction function MUST be idempotent (the driver retries on
+   * transient errors) and MUST NOT return the raw `Result` — process records
+   * inside the function and return mapped data.
+   */
+  async executeWrite(repositoryId, txFn) {
+    return this.runManaged("write", repositoryId, txFn);
+  }
+  /**
+   * Run a managed read transaction scoped to a repository. Same isolation
+   * contract as `executeWrite`.
+   */
+  async executeRead(repositoryId, txFn) {
+    return this.runManaged("read", repositoryId, txFn);
+  }
+  /**
+   * Cross-repository escape hatch. Reserved for the small allowlist of
+   * legitimate cross-repository operations: `ensureSchema` (DDL),
+   * `listRepositories`, `_Meta` schema-version reads, server-info probes.
+   * Does NOT inject `$rid`. Every call site MUST add a one-line comment
+   * justifying why cross-repository access is correct (D3b).
+   */
+  async executeSystemQuery(cypher, params, options) {
+    if (options.crossRepository !== true) {
+      throw new ProviderError3(
+        "executeSystemQuery requires crossRepository: true \u2014 use executeQuery for repository-scoped Cypher."
+      );
+    }
+    const result = await this.driver.executeQuery(cypher, params, {
+      database: this.database,
+      ...options.routing !== void 0 ? { routing: options.routing } : {}
+    });
+    recordRoundTrip(result.summary, result.records.length);
+    this.surfaceNotifications(cypher, result.summary);
+    return result;
+  }
+  /**
+   * Run a single DDL statement on a session (auto-commit). Used for schema
+   * setup — `CREATE CONSTRAINT` / `CREATE INDEX` statements cannot run inside
+   * a managed transaction in Cypher 25 and must be issued one per call.
+   * Cross-repository by definition.
+   */
+  async executeSystemDdl(cypher) {
+    const session = this.driver.session({ database: this.database });
+    try {
+      const result = await session.run(cypher);
+      recordRoundTrip(result.summary, result.records.length);
+      this.surfaceNotifications(cypher, result.summary);
+      return result.summary;
+    } finally {
+      await session.close();
+    }
+  }
+  /**
+   * Run a repository-scoped Cypher statement that uses `CALL ( ) { ... } IN
+   * TRANSACTIONS OF $batchSize ROWS` semantics.
+   *
+   * `IN TRANSACTIONS` is only valid in implicit (auto-commit) transactions —
+   * the managed `executeWrite` / `executeRead` helpers open an explicit
+   * transaction internally and the server rejects the statement with
+   * `Neo.DatabaseError.Transaction.TransactionStartFailed`. Probe P13
+   * (local-tests/baseline/neo4j-call-in-transactions-results.md) captured the
+   * exact failure mode and the empty-match / partial-batch behaviour the
+   * chunked-wipe path relies on.
+   *
+   * Same `$rid` injection + scope assertion as `executeQuery`, so the chunked
+   * delete still flows through the D3b layer 2 lifeline. Returns only the
+   * summary because the chunked-wipe subquery yields no rows; counters live on
+   * `summary.counters.updates()`.
+   */
+  async executeImplicitInTransactions(cypher, params, options) {
+    this.assertRepositoryId(options.repositoryId);
+    this.assertScoped(cypher);
+    const session = this.driver.session({ database: this.database });
+    try {
+      const result = await session.run(cypher, { ...params, rid: options.repositoryId });
+      recordRoundTrip(result.summary, result.records.length);
+      this.surfaceNotifications(cypher, result.summary);
+      return result.summary;
+    } finally {
+      await session.close();
+    }
+  }
+  async runManaged(mode, repositoryId, txFn) {
+    this.assertRepositoryId(repositoryId);
+    const session = this.driver.session({ database: this.database });
+    try {
+      const wrapped = (managed) => txFn(new ScopedTransaction(managed, repositoryId, this.surfaceNotifications.bind(this)));
+      return mode === "write" ? await session.executeWrite(wrapped) : await session.executeRead(wrapped);
+    } finally {
+      await session.close();
+    }
+  }
+  assertRepositoryId(repositoryId) {
+    if (typeof repositoryId !== "string" || repositoryId.length === 0) {
+      throw new ProviderError3(
+        "Neo4jConnection: repositoryId is required for scoped queries (D3b isolation guarantee)."
+      );
+    }
+  }
+  assertScoped(cypher) {
+    if (!RID_TOKEN_PATTERN.test(cypher)) {
+      throw new ProviderError3(
+        "Neo4jConnection: Cypher omits required $rid binding. Repository-scoped queries MUST reference $rid in a predicate or property map. Use executeSystemQuery for cross-repository calls (D3b allowlist)."
+      );
+    }
+  }
+  surfaceNotifications(cypher, summary) {
+    const items = collectNonInformationNotifications(summary);
+    if (items.length === 0) return;
+    const truncated = cypher.length > NOTIFICATION_QUERY_TRUNCATION ? `${cypher.slice(0, NOTIFICATION_QUERY_TRUNCATION)}\u2026` : cypher;
+    console.warn("[neo4j] notifications", { cypher: truncated, notifications: items });
+  }
+};
+var ScopedTransaction = class {
+  constructor(tx, repositoryId, notify) {
+    this.tx = tx;
+    this.repositoryId = repositoryId;
+    this.notify = notify;
+  }
+  tx;
+  repositoryId;
+  notify;
+  /**
+   * Run a single statement inside the managed transaction. Injects `$rid`
+   * and asserts the Cypher string references it.
+   */
+  async run(cypher, params) {
+    if (!RID_TOKEN_PATTERN.test(cypher)) {
+      throw new ProviderError3(
+        "ScopedTransaction.run: Cypher omits required $rid binding. Multi-statement writes still flow through the isolation chokepoint."
+      );
+    }
+    const queryResult = await this.tx.run(cypher, { ...params, rid: this.repositoryId });
+    const records = queryResult.records;
+    const summary = queryResult.summary;
+    recordRoundTrip(summary, records.length);
+    this.notify(cypher, summary);
+    return { records, summary };
+  }
+};
+function collectNonInformationNotifications(summary) {
+  const summaryLike = summary;
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of summaryLike.notifications ?? []) {
+    const entry = {
+      severity: item.severity ?? "",
+      category: item.category ?? "",
+      code: item.code ?? "",
+      title: item.title ?? "",
+      description: item.description ?? ""
+    };
+    const key = entry.code || entry.title;
+    if (key && seen.has(key)) continue;
+    if (key) seen.add(key);
+    out.push(entry);
+  }
+  for (const item of summaryLike.gqlStatusObjects ?? []) {
+    const severity = item.severity ?? "";
+    if (severity !== "WARNING" && severity !== "ERROR") continue;
+    const entry = {
+      severity,
+      category: item.classification ?? "",
+      code: item.gqlStatus ?? "",
+      title: item.title ?? "",
+      description: item.description ?? item.statusDescription ?? ""
+    };
+    const key = entry.code || entry.title || entry.description;
+    if (key && seen.has(key)) continue;
+    if (key) seen.add(key);
+    out.push(entry);
+  }
+  return out;
+}
+
+// src/errors.ts
+import {
+  DuplicateEntityError,
+  DuplicateRelationshipError,
+  DuplicateRepositoryError,
+  ProviderError as ProviderError4
+} from "@utaba/deep-memory";
+var CONSTRAINT_VIOLATION_CODE = "Neo.ClientError.Schema.ConstraintValidationFailed";
+var SYNTAX_ERROR_CODE = "Neo.ClientError.Statement.SyntaxError";
+function mapDriverError(error, context = {}) {
+  if (error instanceof DuplicateEntityError || error instanceof DuplicateRelationshipError || error instanceof DuplicateRepositoryError || error instanceof ProviderError4) {
+    throw error;
+  }
+  const driverError = error ?? {};
+  const code = typeof driverError.code === "string" ? driverError.code : "";
+  const message = typeof driverError.message === "string" ? driverError.message : "";
+  if (code === CONSTRAINT_VIOLATION_CODE) {
+    const kind = inferConstraintKind(context, message);
+    if (kind === "repository" && context.repositoryId !== void 0) {
+      throw new DuplicateRepositoryError(context.repositoryId);
+    }
+    if (kind === "entity" && context.entityId !== void 0) {
+      throw new DuplicateEntityError(context.entityId);
+    }
+    if (kind === "relationship" && context.relationshipId !== void 0) {
+      throw new DuplicateRelationshipError(context.relationshipId);
+    }
+    throw new ProviderError4(
+      `Neo4j constraint violation${formatOperation(context)}: ${message || code}`,
+      "Inspect the failing Cypher and the schema constraints \u2014 the affected unique key already exists."
+    );
+  }
+  if (code === SYNTAX_ERROR_CODE) {
+    throw new ProviderError4(
+      `Neo4j syntax error${formatOperation(context)}: ${message || code}`,
+      "This is a programming error inside @utaba/deep-memory-storage-neo4j \u2014 please file an issue."
+    );
+  }
+  const prefix = `Neo4j driver error${formatOperation(context)}`;
+  const codeSuffix = code ? ` [${code}]` : "";
+  const messageSuffix = message ? `: ${message}` : "";
+  throw new ProviderError4(`${prefix}${codeSuffix}${messageSuffix}`);
+}
+function inferConstraintKind(context, message) {
+  if (context.kind !== void 0) return context.kind;
+  if (message.startsWith("Relationship")) return "relationship";
+  if (message.includes("`_Repository`")) return "repository";
+  return "entity";
+}
+function formatOperation(context) {
+  return context.operation ? ` in ${context.operation}` : "";
+}
+
+// src/queries/bulk.ts
+import { ProviderError as ProviderError5 } from "@utaba/deep-memory";
+var EXPORT_BATCH_SIZE = 100;
+var DEFAULT_IMPORT_CHUNK_SIZE = 500;
+var DEFAULT_IMPORT_CONCURRENCY = 8;
+var EXPORT_ENTITY_PROJECTION = buildEntityProjection({ loadEmbeddings: true });
+var EXPORT_RELATIONSHIP_PROJECTION = buildRelationshipProjection();
+var EXPORT_ENTITIES_FIRST_PAGE = `
+MATCH (n:_Entity {repositoryId: $rid})
+RETURN ${EXPORT_ENTITY_PROJECTION}
+ORDER BY n.id
+LIMIT $batchSize
+`;
+var EXPORT_ENTITIES_NEXT_PAGE = `
+MATCH (n:_Entity {repositoryId: $rid})
+WHERE n.id > $cursor
+RETURN ${EXPORT_ENTITY_PROJECTION}
+ORDER BY n.id
+LIMIT $batchSize
+`;
+var EXPORT_RELATIONSHIPS_FIRST_PAGE = `
+MATCH (:_Entity {repositoryId: $rid})-[r {repositoryId: $rid}]->(:_Entity {repositoryId: $rid})
+RETURN ${EXPORT_RELATIONSHIP_PROJECTION}
+ORDER BY r.id
+LIMIT $batchSize
+`;
+var EXPORT_RELATIONSHIPS_NEXT_PAGE = `
+MATCH (:_Entity {repositoryId: $rid})-[r {repositoryId: $rid}]->(:_Entity {repositoryId: $rid})
+WHERE r.id > $cursor
+RETURN ${EXPORT_RELATIONSHIP_PROJECTION}
+ORDER BY r.id
+LIMIT $batchSize
+`;
+async function* exportAll(conn, repositoryId) {
+  let sequence = 0;
+  let cursor;
+  while (true) {
+    const query = cursor === void 0 ? EXPORT_ENTITIES_FIRST_PAGE : EXPORT_ENTITIES_NEXT_PAGE;
+    const params = cursor === void 0 ? { batchSize: BigInt(EXPORT_BATCH_SIZE) } : { cursor, batchSize: BigInt(EXPORT_BATCH_SIZE) };
+    const result = await conn.executeQuery(query, params, { repositoryId, routing: "READ" });
+    const entities = result.records.map((record) => entityFromRecord(record));
+    const isLast = entities.length < EXPORT_BATCH_SIZE;
+    if (entities.length > 0) {
+      cursor = entities[entities.length - 1].id;
+      yield {
+        type: "entities",
+        data: entities,
+        sequence: sequence++,
+        isLast
+      };
+    }
+    if (isLast) break;
+  }
+  let relCursor;
+  while (true) {
+    const query = relCursor === void 0 ? EXPORT_RELATIONSHIPS_FIRST_PAGE : EXPORT_RELATIONSHIPS_NEXT_PAGE;
+    const params = relCursor === void 0 ? { batchSize: BigInt(EXPORT_BATCH_SIZE) } : { cursor: relCursor, batchSize: BigInt(EXPORT_BATCH_SIZE) };
+    const result = await conn.executeQuery(query, params, { repositoryId, routing: "READ" });
+    const relationships = result.records.map((record) => relationshipFromRecord(record));
+    const isLast = relationships.length < EXPORT_BATCH_SIZE;
+    if (relationships.length > 0) {
+      relCursor = relationships[relationships.length - 1].id;
+      yield {
+        type: "relationships",
+        data: relationships,
+        sequence: sequence++,
+        isLast
+      };
+    }
+    if (isLast) break;
+  }
+  if (sequence === 0) {
+    yield {
+      type: "entities",
+      data: [],
+      sequence: 0,
+      isLast: true
+    };
+  }
+}
+var INSERT_ENTITIES_QUERY = `
+UNWIND $rows AS row
+CREATE (n:_Entity)
+SET
+  n.id = row.id,
+  n.repositoryId = $rid,
+  n.entityType = row.entityType,
+  n.label = row.label,
+  n.slug = row.slug,
+  n.summary = row.summary,
+  n.properties = row.properties,
+  n.data = row.data,
+  n.dataFormat = row.dataFormat,
+  n.embedding = row.embedding,
+  n.createdBy = row.createdBy,
+  n.createdByType = row.createdByType,
+  n.createdAt = row.createdAt,
+  n.createdInConversation = row.createdInConversation,
+  n.createdFromMessage = row.createdFromMessage,
+  n.modifiedBy = row.modifiedBy,
+  n.modifiedByType = row.modifiedByType,
+  n.modifiedAt = row.modifiedAt,
+  n.modifiedInConversation = row.modifiedInConversation,
+  n.modifiedFromMessage = row.modifiedFromMessage
+SET n += row.userProperties
+`;
+var UPSERT_ENTITIES_QUERY = `
+UNWIND $rows AS row
+MERGE (n:_Entity {repositoryId: $rid, id: row.id})
+ON CREATE SET
+  n.entityType = row.entityType,
+  n.label = row.label,
+  n.slug = row.slug,
+  n.summary = row.summary,
+  n.properties = row.properties,
+  n.data = row.data,
+  n.dataFormat = row.dataFormat,
+  n.embedding = row.embedding,
+  n.createdBy = row.createdBy,
+  n.createdByType = row.createdByType,
+  n.createdAt = row.createdAt,
+  n.createdInConversation = row.createdInConversation,
+  n.createdFromMessage = row.createdFromMessage,
+  n.modifiedBy = row.modifiedBy,
+  n.modifiedByType = row.modifiedByType,
+  n.modifiedAt = row.modifiedAt,
+  n.modifiedInConversation = row.modifiedInConversation,
+  n.modifiedFromMessage = row.modifiedFromMessage
+ON MATCH SET
+  n.entityType = row.entityType,
+  n.label = row.label,
+  n.slug = row.slug,
+  n.summary = row.summary,
+  n.properties = row.properties,
+  n.data = row.data,
+  n.dataFormat = row.dataFormat,
+  n.embedding = row.embedding,
+  n.createdBy = row.createdBy,
+  n.createdByType = row.createdByType,
+  n.createdAt = row.createdAt,
+  n.createdInConversation = row.createdInConversation,
+  n.createdFromMessage = row.createdFromMessage,
+  n.modifiedBy = row.modifiedBy,
+  n.modifiedByType = row.modifiedByType,
+  n.modifiedAt = row.modifiedAt,
+  n.modifiedInConversation = row.modifiedInConversation,
+  n.modifiedFromMessage = row.modifiedFromMessage
+SET n += row.userProperties
+`;
+function buildInsertRelationshipsQuery(relationshipType) {
+  const safe = assertSafeRelationshipType(relationshipType);
+  return `
+UNWIND $rows AS row
+MATCH (s:_Entity {repositoryId: $rid, id: row.sourceEntityId})
+MATCH (t:_Entity {repositoryId: $rid, id: row.targetEntityId})
+CREATE (s)-[r:${safe} {
+  repositoryId: $rid,
+  id: row.id,
+  relationshipType: row.relationshipType,
+  sourceEntityId: row.sourceEntityId,
+  targetEntityId: row.targetEntityId,
+  properties: row.properties,
+  bidirectional: row.bidirectional,
+  createdBy: row.createdBy,
+  createdByType: row.createdByType,
+  createdAt: row.createdAt,
+  createdInConversation: row.createdInConversation,
+  createdFromMessage: row.createdFromMessage,
+  modifiedBy: row.modifiedBy,
+  modifiedByType: row.modifiedByType,
+  modifiedAt: row.modifiedAt,
+  modifiedInConversation: row.modifiedInConversation,
+  modifiedFromMessage: row.modifiedFromMessage
+}]->(t)
+RETURN row.id AS id
+`;
+}
+function buildUpsertRelationshipsQuery(relationshipType) {
+  const safe = assertSafeRelationshipType(relationshipType);
+  return `
+UNWIND $rows AS row
+MATCH (s:_Entity {repositoryId: $rid, id: row.sourceEntityId})
+MATCH (t:_Entity {repositoryId: $rid, id: row.targetEntityId})
+MERGE (s)-[r:${safe} {repositoryId: $rid, id: row.id}]->(t)
+ON CREATE SET
+  r.relationshipType = row.relationshipType,
+  r.sourceEntityId = row.sourceEntityId,
+  r.targetEntityId = row.targetEntityId,
+  r.properties = row.properties,
+  r.bidirectional = row.bidirectional,
+  r.createdBy = row.createdBy,
+  r.createdByType = row.createdByType,
+  r.createdAt = row.createdAt,
+  r.createdInConversation = row.createdInConversation,
+  r.createdFromMessage = row.createdFromMessage,
+  r.modifiedBy = row.modifiedBy,
+  r.modifiedByType = row.modifiedByType,
+  r.modifiedAt = row.modifiedAt,
+  r.modifiedInConversation = row.modifiedInConversation,
+  r.modifiedFromMessage = row.modifiedFromMessage
+ON MATCH SET
+  r.properties = row.properties,
+  r.bidirectional = row.bidirectional,
+  r.modifiedBy = row.modifiedBy,
+  r.modifiedByType = row.modifiedByType,
+  r.modifiedAt = row.modifiedAt,
+  r.modifiedInConversation = row.modifiedInConversation,
+  r.modifiedFromMessage = row.modifiedFromMessage
+RETURN row.id AS id
+`;
+}
+async function importBulk(conn, repositoryId, data, options) {
+  const skipCheck = options?.skipExistenceCheck === true;
+  const ext = options ?? {};
+  const chunkSize = ext.chunkSize ?? DEFAULT_IMPORT_CHUNK_SIZE;
+  const concurrency = ext.concurrency ?? DEFAULT_IMPORT_CONCURRENCY;
+  const allEntities = [];
+  const allRelationships = [];
+  for (const chunk of data) {
+    if (chunk.entities) allEntities.push(...chunk.entities);
+    if (chunk.relationships) allRelationships.push(...chunk.relationships);
+  }
+  const errors = [];
+  const entityChunks = sliceIntoChunks(allEntities, chunkSize);
+  const entityResults = await runBounded(
+    entityChunks,
+    concurrency,
+    (chunk) => importEntityChunk(conn, repositoryId, chunk, skipCheck)
+  );
+  let entitiesImported = 0;
+  for (const res of entityResults) {
+    entitiesImported += res.imported;
+    errors.push(...res.errors);
+  }
+  const relationshipChunks = groupRelationshipsByTypeIntoChunks(allRelationships, chunkSize);
+  const relationshipResults = await runBounded(
+    relationshipChunks,
+    concurrency,
+    (group) => importRelationshipChunk(conn, repositoryId, group, skipCheck)
+  );
+  let relationshipsImported = 0;
+  for (const res of relationshipResults) {
+    relationshipsImported += res.imported;
+    errors.push(...res.errors);
+  }
+  return { entitiesImported, relationshipsImported, errors };
+}
+async function importEntityChunk(conn, repositoryId, entities, skipCheck) {
+  if (entities.length === 0) return { imported: 0, errors: [] };
+  const rows = entities.map((entity) => ({
+    ...entityToParams(entity),
+    userProperties: entityUserPropertyParams(entity.properties)
+  }));
+  const query = skipCheck ? INSERT_ENTITIES_QUERY : UPSERT_ENTITIES_QUERY;
+  try {
+    await conn.executeQuery(query, { rows }, { repositoryId });
+    return { imported: entities.length, errors: [] };
+  } catch (err) {
+    return fallbackPerEntity(conn, repositoryId, entities, skipCheck, err);
+  }
+}
+async function fallbackPerEntity(conn, repositoryId, entities, skipCheck, chunkError) {
+  const errors = [];
+  let imported = 0;
+  const query = skipCheck ? INSERT_ENTITIES_QUERY : UPSERT_ENTITIES_QUERY;
+  for (const entity of entities) {
+    try {
+      const rows = [
+        {
+          ...entityToParams(entity),
+          userProperties: entityUserPropertyParams(entity.properties)
+        }
+      ];
+      await conn.executeQuery(query, { rows }, { repositoryId });
+      imported++;
+    } catch (rowErr) {
+      errors.push({
+        item: `entity:${entity.id}`,
+        error: rowErr instanceof Error ? rowErr.message : String(rowErr)
+      });
+    }
+  }
+  if (errors.length === 0 && imported < entities.length) {
+    errors.push({
+      item: `entity-chunk`,
+      error: chunkError instanceof Error ? chunkError.message : String(chunkError)
+    });
+  }
+  return { imported, errors };
+}
+async function importRelationshipChunk(conn, repositoryId, group, skipCheck) {
+  if (group.rows.length === 0) return { imported: 0, errors: [] };
+  const rows = group.rows.map((rel) => relationshipToParams(rel));
+  const query = skipCheck ? buildInsertRelationshipsQuery(group.relationshipType) : buildUpsertRelationshipsQuery(group.relationshipType);
+  try {
+    const result = await conn.executeQuery(query, { rows }, { repositoryId });
+    const importedIds = /* @__PURE__ */ new Set();
+    for (const record of result.records) {
+      const id = record.get("id");
+      if (typeof id === "string") importedIds.add(id);
+    }
+    const errors = [];
+    for (const rel of group.rows) {
+      if (!importedIds.has(rel.id)) {
+        errors.push({
+          item: `relationship:${rel.id}`,
+          error: `endpoint not found in repository (source=${rel.sourceEntityId}, target=${rel.targetEntityId})`
+        });
+      }
+    }
+    return { imported: importedIds.size, errors };
+  } catch (err) {
+    return fallbackPerRelationship(conn, repositoryId, group, skipCheck, err);
+  }
+}
+async function fallbackPerRelationship(conn, repositoryId, group, skipCheck, chunkError) {
+  const errors = [];
+  let imported = 0;
+  const query = skipCheck ? buildInsertRelationshipsQuery(group.relationshipType) : buildUpsertRelationshipsQuery(group.relationshipType);
+  for (const rel of group.rows) {
+    try {
+      const rows = [relationshipToParams(rel)];
+      const result = await conn.executeQuery(query, { rows }, { repositoryId });
+      if (result.records.length === 1) {
+        imported++;
+      } else {
+        errors.push({
+          item: `relationship:${rel.id}`,
+          error: `endpoint not found in repository (source=${rel.sourceEntityId}, target=${rel.targetEntityId})`
+        });
+      }
+    } catch (rowErr) {
+      errors.push({
+        item: `relationship:${rel.id}`,
+        error: rowErr instanceof Error ? rowErr.message : String(rowErr)
+      });
+    }
+  }
+  if (errors.length === 0 && imported < group.rows.length) {
+    errors.push({
+      item: `relationship-chunk:${group.relationshipType}`,
+      error: chunkError instanceof Error ? chunkError.message : String(chunkError)
+    });
+  }
+  return { imported, errors };
+}
+function sliceIntoChunks(items, chunkSize) {
+  if (items.length === 0) return [];
+  const out = [];
+  for (let i = 0; i < items.length; i += chunkSize) {
+    out.push(items.slice(i, i + chunkSize));
+  }
+  return out;
+}
+function groupRelationshipsByTypeIntoChunks(relationships, chunkSize) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const rel of relationships) {
+    const list = grouped.get(rel.relationshipType);
+    if (list) list.push(rel);
+    else grouped.set(rel.relationshipType, [rel]);
+  }
+  const out = [];
+  for (const [relationshipType, rows] of grouped) {
+    for (let i = 0; i < rows.length; i += chunkSize) {
+      out.push({ relationshipType, rows: rows.slice(i, i + chunkSize) });
+    }
+  }
+  return out;
+}
+async function runBounded(items, concurrency, fn) {
+  if (items.length === 0) return [];
+  if (concurrency < 1) {
+    throw new ProviderError5(`runBounded: concurrency must be >= 1 (got ${concurrency}).`);
+  }
+  const cap = Math.min(concurrency, items.length);
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  const workers = [];
+  for (let w = 0; w < cap; w++) {
+    workers.push(
+      (async () => {
+        while (true) {
+          const i = nextIndex++;
+          if (i >= items.length) return;
+          results[i] = await fn(items[i]);
+        }
+      })()
+    );
+  }
+  await Promise.all(workers);
+  return results;
+}
+
+// src/queries/entity.ts
+import { EntityNotFoundError, ProviderError as ProviderError6 } from "@utaba/deep-memory";
+var ENTITY_CREATE_QUERY = `
+CREATE (n:_Entity {
+  repositoryId: $rid,
+  id: $id,
+  entityType: $entityType,
+  label: $label,
+  slug: $slug,
+  summary: $summary,
+  properties: $properties,
+  data: $data,
+  dataFormat: $dataFormat,
+  embedding: $embedding,
+  createdBy: $createdBy,
+  createdByType: $createdByType,
+  createdAt: $createdAt,
+  createdInConversation: $createdInConversation,
+  createdFromMessage: $createdFromMessage,
+  modifiedBy: $modifiedBy,
+  modifiedByType: $modifiedByType,
+  modifiedAt: $modifiedAt,
+  modifiedInConversation: $modifiedInConversation,
+  modifiedFromMessage: $modifiedFromMessage
+})
+SET n += $userProperties
+RETURN n.id AS id
+`;
+var ENTITY_PROJECTION_LIGHT = buildEntityProjection();
+var ENTITY_PROJECTION_FULL = buildEntityProjection({ loadEmbeddings: true });
+var ENTITY_GET_QUERY_LIGHT = `MATCH (n:_Entity {repositoryId: $rid, id: $id}) RETURN ${ENTITY_PROJECTION_LIGHT}`;
+var ENTITY_GET_QUERY_FULL = `MATCH (n:_Entity {repositoryId: $rid, id: $id}) RETURN ${ENTITY_PROJECTION_FULL}`;
+var ENTITY_GET_BY_SLUG_QUERY_LIGHT = `MATCH (n:_Entity {repositoryId: $rid, slug: $slug}) RETURN ${ENTITY_PROJECTION_LIGHT}`;
+var ENTITY_GET_BY_SLUG_QUERY_FULL = `MATCH (n:_Entity {repositoryId: $rid, slug: $slug}) RETURN ${ENTITY_PROJECTION_FULL}`;
+var ENTITY_GET_MANY_QUERY_LIGHT = `MATCH (n:_Entity {repositoryId: $rid}) WHERE n.id IN $ids RETURN ${ENTITY_PROJECTION_LIGHT}`;
+var ENTITY_GET_MANY_QUERY_FULL = `MATCH (n:_Entity {repositoryId: $rid}) WHERE n.id IN $ids RETURN ${ENTITY_PROJECTION_FULL}`;
+async function createEntity(conn, repositoryId, entity) {
+  const userProperties = entityUserPropertyParams(entity.properties);
+  try {
+    await conn.executeQuery(
+      ENTITY_CREATE_QUERY,
+      { ...entityToParams(entity), userProperties },
+      { repositoryId }
+    );
+  } catch (err) {
+    mapDriverError(err, {
+      kind: "entity",
+      entityId: entity.id,
+      operation: "createEntity"
+    });
+  }
+  return entity;
+}
+async function getEntity(conn, repositoryId, entityId, options) {
+  const query = options?.loadEmbeddings === true ? ENTITY_GET_QUERY_FULL : ENTITY_GET_QUERY_LIGHT;
+  const result = await conn.executeQuery(
+    query,
+    { id: entityId },
+    { repositoryId, routing: "READ" }
+  );
+  const record = result.records[0];
+  if (record === void 0) return null;
+  return entityFromRecord(record);
+}
+async function getEntityBySlug(conn, repositoryId, slug, options) {
+  const query = options?.loadEmbeddings === true ? ENTITY_GET_BY_SLUG_QUERY_FULL : ENTITY_GET_BY_SLUG_QUERY_LIGHT;
+  const result = await conn.executeQuery(
+    query,
+    { slug },
+    { repositoryId, routing: "READ" }
+  );
+  const record = result.records[0];
+  if (record === void 0) return null;
+  return entityFromRecord(record);
+}
+async function getEntities(conn, repositoryId, entityIds, options) {
+  const map = /* @__PURE__ */ new Map();
+  if (entityIds.length === 0) return map;
+  const query = options?.loadEmbeddings === true ? ENTITY_GET_MANY_QUERY_FULL : ENTITY_GET_MANY_QUERY_LIGHT;
+  const result = await conn.executeQuery(
+    query,
+    { ids: entityIds },
+    { repositoryId, routing: "READ" }
+  );
+  for (const record of result.records) {
+    const entity = entityFromRecord(record);
+    map.set(entity.id, entity);
+  }
+  return map;
+}
+async function updateEntity(conn, repositoryId, entityId, updates) {
+  let userProperties = null;
+  if (updates.properties !== void 0) {
+    userProperties = entityUserPropertyParams(updates.properties);
+  }
+  let keysToRemove = [];
+  if (userProperties !== null) {
+    const readResult = await conn.executeQuery(
+      "MATCH (n:_Entity {repositoryId: $rid, id: $id}) RETURN properties(n) AS props",
+      { id: entityId },
+      { repositoryId, routing: "READ" }
+    );
+    const readRecord = readResult.records[0];
+    if (readRecord === void 0) throw new EntityNotFoundError(entityId);
+    const props = readRecord.get("props");
+    const existingProps = typeof props === "object" && props !== null && !Array.isArray(props) ? props : {};
+    const existingUserKeys = Object.keys(existingProps).filter(
+      (k) => !RESERVED_ENTITY_PROPERTY_KEYS.has(k)
+    );
+    keysToRemove = existingUserKeys.filter((k) => !(k in userProperties));
+  }
+  const setParts = [];
+  const params = { id: entityId };
+  const setField = (key, paramName, value) => {
+    setParts.push(`n.${key} = $${paramName}`);
+    params[paramName] = value;
+  };
+  if (updates.entityType !== void 0) setField("entityType", "entityType", updates.entityType);
+  if (updates.label !== void 0) setField("label", "label", updates.label);
+  if (updates.slug !== void 0) setField("slug", "slug", updates.slug);
+  if (updates.summary !== void 0) setField("summary", "summary", updates.summary);
+  if (updates.properties !== void 0) {
+    setField("properties", "properties", JSON.stringify(updates.properties));
+  }
+  if (updates.data !== void 0) setField("data", "data", updates.data);
+  if (updates.dataFormat !== void 0) setField("dataFormat", "dataFormat", updates.dataFormat);
+  if (updates.embedding !== void 0) setField("embedding", "embedding", updates.embedding);
+  const p = updates.provenance;
+  setField("modifiedBy", "modifiedBy", p.modifiedBy);
+  setField("modifiedByType", "modifiedByType", p.modifiedByType);
+  setField("modifiedAt", "modifiedAt", p.modifiedAt);
+  if (p.modifiedInConversation !== void 0) {
+    setField("modifiedInConversation", "modifiedInConversation", p.modifiedInConversation);
+  }
+  if (p.modifiedFromMessage !== void 0) {
+    setField("modifiedFromMessage", "modifiedFromMessage", p.modifiedFromMessage);
+  }
+  let userPropsClause = "";
+  if (userProperties !== null) {
+    params["userProperties"] = userProperties;
+    userPropsClause = " SET n += $userProperties";
+  }
+  let removeClause = "";
+  if (keysToRemove.length > 0) {
+    const safeKeys = keysToRemove.map((k) => `n.${assertSafeUserPropertyKey(k)}`);
+    removeClause = ` REMOVE ${safeKeys.join(", ")}`;
+  }
+  const cypher = `MATCH (n:_Entity {repositoryId: $rid, id: $id}) SET ${setParts.join(", ")}${userPropsClause}${removeClause} RETURN ${ENTITY_PROJECTION_LIGHT}`;
+  const result = await conn.executeQuery(cypher, params, { repositoryId });
+  const record = result.records[0];
+  if (record === void 0) throw new EntityNotFoundError(entityId);
+  return entityFromRecord(record);
+}
+async function deleteEntity(conn, repositoryId, entityId) {
+  const result = await conn.executeQuery(
+    "MATCH (n:_Entity {repositoryId: $rid, id: $id}) DETACH DELETE n RETURN count(n) AS deleted",
+    { id: entityId },
+    { repositoryId }
+  );
+  const deleted = bigintToSafeNumber(result.records[0]?.get("deleted") ?? 0);
+  if (deleted !== 1) throw new EntityNotFoundError(entityId);
+}
+async function deleteEntities(conn, repositoryId, ids) {
+  if (ids.length === 0) return { deleted: [], notFound: [] };
+  const result = await conn.executeQuery(
+    "MATCH (n:_Entity {repositoryId: $rid}) WHERE n.id IN $ids WITH n, n.id AS id DETACH DELETE n RETURN id AS deleted",
+    { ids },
+    { repositoryId }
+  );
+  const deleted = [];
+  for (const record of result.records) {
+    const id = record.get("deleted");
+    if (typeof id === "string") deleted.push(id);
+  }
+  const deletedSet = new Set(deleted);
+  const notFound = ids.filter((id) => !deletedSet.has(id));
+  return { deleted, notFound };
+}
+var FIND_PROJECTION_LIGHT = buildEntityProjection({ alias: "n" });
+var FIND_PROJECTION_FULL = buildEntityProjection({ alias: "n", loadEmbeddings: true });
+var FIND_PROJECTION_LIGHT_FT = buildEntityProjection({ alias: "node" });
+var FIND_PROJECTION_FULL_FT = buildEntityProjection({ alias: "node", loadEmbeddings: true });
+function buildFindEntitiesWhere(query, options) {
+  const { alias, includeRepositoryPredicate } = options;
+  const params = {};
+  const predicates = [];
+  if (includeRepositoryPredicate) {
+    predicates.push(`${alias}.repositoryId = $rid`);
+  }
+  if (query.entityTypes && query.entityTypes.length > 0) {
+    predicates.push(`${alias}.entityType IN $entityTypes`);
+    params["entityTypes"] = query.entityTypes;
+  }
+  if (query.properties) {
+    let i = 0;
+    for (const [key, value] of Object.entries(query.properties)) {
+      assertSafeUserPropertyKey(key);
+      if (!isNativeStorableValue(value)) {
+        throw new ProviderError6(
+          `findEntities property filter "${key}" has a value that Neo4j cannot store as a native scalar \u2014 filters must be strings, finite numbers, booleans, or homogeneous arrays of those. Nested objects and null values live only inside the JSON properties blob and are not predicate-queryable.`
+        );
+      }
+      const paramName = `prop${i}`;
+      predicates.push(`${alias}.${key} = $${paramName}`);
+      params[paramName] = value;
+      i++;
+    }
+  }
+  if (query.provenance) {
+    if (query.provenance.conversationIds && query.provenance.conversationIds.length > 0) {
+      predicates.push(
+        `(${alias}.createdInConversation IN $convIds OR ${alias}.modifiedInConversation IN $convIds)`
+      );
+      params["convIds"] = query.provenance.conversationIds;
+    }
+    if (query.provenance.actors && query.provenance.actors.length > 0) {
+      predicates.push(
+        `(${alias}.createdBy IN $actors OR ${alias}.modifiedBy IN $actors)`
+      );
+      params["actors"] = query.provenance.actors;
+    }
+    if (query.provenance.dateRange) {
+      predicates.push(
+        `((${alias}.createdAt >= $dateFrom AND ${alias}.createdAt <= $dateTo) OR (${alias}.modifiedAt >= $dateFrom AND ${alias}.modifiedAt <= $dateTo))`
+      );
+      params["dateFrom"] = query.provenance.dateRange.from;
+      params["dateTo"] = query.provenance.dateRange.to;
+    }
+  }
+  const cypherWhere = predicates.length > 0 ? `WHERE ${predicates.join(" AND ")}` : "";
+  return { cypherWhere, params };
+}
+async function findEntities(conn, repositoryId, query, options) {
+  const loadEmbeddings = options?.loadEmbeddings === true;
+  const skipLimitParams = {
+    skip: BigInt(query.offset),
+    limit: BigInt(query.limit)
+  };
+  let records;
+  let countResult;
+  if (query.searchTerm !== void 0 && query.searchTerm !== "") {
+    const projection = loadEmbeddings ? FIND_PROJECTION_FULL_FT : FIND_PROJECTION_LIGHT_FT;
+    const where = buildFindEntitiesWhere(query, {
+      alias: "node",
+      includeRepositoryPredicate: false
+    });
+    const repoPredicate = "node.repositoryId = $rid";
+    const combinedWhere = where.cypherWhere.length > 0 ? `WHERE ${repoPredicate} AND ${where.cypherWhere.slice("WHERE ".length)}` : `WHERE ${repoPredicate}`;
+    const dataCypher = `CALL db.index.fulltext.queryNodes('dm_entity_text', $term) YIELD node, score ${combinedWhere} RETURN ${projection} ORDER BY score DESC SKIP $skip LIMIT $limit`;
+    const countCypher = `CALL db.index.fulltext.queryNodes('dm_entity_text', $term) YIELD node ${combinedWhere} RETURN count(node) AS total`;
+    const termParam = { term: query.searchTerm };
+    const [dataResult, count] = await Promise.all([
+      conn.executeQuery(
+        dataCypher,
+        { ...where.params, ...termParam, ...skipLimitParams },
+        { repositoryId, routing: "READ" }
+      ),
+      conn.executeQuery(
+        countCypher,
+        { ...where.params, ...termParam },
+        { repositoryId, routing: "READ" }
+      )
+    ]);
+    records = dataResult.records;
+    countResult = count;
+  } else {
+    const projection = loadEmbeddings ? FIND_PROJECTION_FULL : FIND_PROJECTION_LIGHT;
+    const where = buildFindEntitiesWhere(query, {
+      alias: "n",
+      includeRepositoryPredicate: true
+    });
+    const dataCypher = `MATCH (n:_Entity) ${where.cypherWhere} RETURN ${projection} ORDER BY n.id SKIP $skip LIMIT $limit`;
+    const countCypher = `MATCH (n:_Entity) ${where.cypherWhere} RETURN count(n) AS total`;
+    const [dataResult, count] = await Promise.all([
+      conn.executeQuery(
+        dataCypher,
+        { ...where.params, ...skipLimitParams },
+        { repositoryId, routing: "READ" }
+      ),
+      conn.executeQuery(countCypher, where.params, { repositoryId, routing: "READ" })
+    ]);
+    records = dataResult.records;
+    countResult = count;
+  }
+  const items = records.map((record) => entityFromRecord(record));
+  const totalRaw = countResult.records[0]?.get("total");
+  const total = totalRaw === void 0 ? 0 : bigintToSafeNumber(totalRaw);
+  const hasMore = query.offset + items.length < total;
+  return {
+    items,
+    total,
+    hasMore,
+    limit: query.limit,
+    offset: query.offset
+  };
+}
+async function deleteEntitiesByType(conn, repositoryId, entityType) {
+  const result = await conn.executeQuery(
+    `MATCH (n:_Entity {repositoryId: $rid, entityType: $entityType})
+     OPTIONAL MATCH (n)-[r]-()
+     WITH collect(DISTINCT n) AS nodes,
+          count(DISTINCT n) AS entities,
+          count(DISTINCT r) AS rels
+     CALL (nodes) {
+       UNWIND nodes AS node
+       DETACH DELETE node
+     }
+     RETURN entities, rels`,
+    { entityType },
+    { repositoryId }
+  );
+  const record = result.records[0];
+  if (record === void 0) {
+    return { deletedEntities: 0, deletedRelationships: 0 };
+  }
+  const deletedEntities = bigintToSafeNumber(record.get("entities") ?? 0);
+  const deletedRelationships = bigintToSafeNumber(record.get("rels") ?? 0);
+  return { deletedEntities, deletedRelationships };
+}
+
+// src/queries/relationship.ts
+import {
+  EntityNotFoundError as EntityNotFoundError2,
+  matchesPropertyFilters
+} from "@utaba/deep-memory";
+var RELATIONSHIP_PROJECTION = buildRelationshipProjection();
+async function createRelationship(conn, repositoryId, relationship) {
+  const relType = assertSafeRelationshipType(relationship.relationshipType);
+  const cypher = `
+OPTIONAL MATCH (s:_Entity {repositoryId: $rid, id: $sourceEntityId})
+OPTIONAL MATCH (t:_Entity {repositoryId: $rid, id: $targetEntityId})
+WITH s, t
+FOREACH (_ IN CASE WHEN s IS NOT NULL AND t IS NOT NULL THEN [1] ELSE [] END |
+  CREATE (s)-[r:${relType} {
+    repositoryId: $rid,
+    id: $id,
+    relationshipType: $relationshipType,
+    sourceEntityId: $sourceEntityId,
+    targetEntityId: $targetEntityId,
+    properties: $properties,
+    bidirectional: $bidirectional,
+    createdBy: $createdBy,
+    createdByType: $createdByType,
+    createdAt: $createdAt,
+    createdInConversation: $createdInConversation,
+    createdFromMessage: $createdFromMessage,
+    modifiedBy: $modifiedBy,
+    modifiedByType: $modifiedByType,
+    modifiedAt: $modifiedAt,
+    modifiedInConversation: $modifiedInConversation,
+    modifiedFromMessage: $modifiedFromMessage
+  }]->(t)
+)
+RETURN s IS NULL AS sMissing, t IS NULL AS tMissing
+`;
+  const result = await conn.executeQuery(
+    cypher,
+    relationshipToParams(relationship),
+    { repositoryId }
+  );
+  const record = result.records[0];
+  if (record === void 0) {
+    throw new EntityNotFoundError2(relationship.sourceEntityId);
+  }
+  const sMissing = record.get("sMissing") === true;
+  const tMissing = record.get("tMissing") === true;
+  if (sMissing) throw new EntityNotFoundError2(relationship.sourceEntityId);
+  if (tMissing) throw new EntityNotFoundError2(relationship.targetEntityId);
+  return relationship;
+}
+async function getRelationship(conn, repositoryId, relationshipId) {
+  const result = await conn.executeQuery(
+    `MATCH ()-[r {repositoryId: $rid, id: $relId}]->() RETURN ${RELATIONSHIP_PROJECTION}`,
+    { relId: relationshipId },
+    { repositoryId, routing: "READ" }
+  );
+  const record = result.records[0];
+  if (record === void 0) return null;
+  return relationshipFromRecord(record);
+}
+async function getEntityRelationships(conn, repositoryId, entityId, options) {
+  const limit = options?.limit ?? 50;
+  const offset = options?.offset ?? 0;
+  const direction = options?.direction ?? "both";
+  const propertyFilters = options?.propertyFilters;
+  const hasPropertyFilters = propertyFilters != null && propertyFilters.length > 0;
+  const params = {
+    eid: entityId,
+    offset: BigInt(offset),
+    limit: BigInt(limit)
+  };
+  const typeFilter = options?.relationshipTypes != null && options.relationshipTypes.length > 0 ? buildTypeFilter(options.relationshipTypes, params) : "";
+  const { dataCypher, countCypher } = buildEntityRelationshipQueries(direction, typeFilter);
+  const [dataResult, countResult] = await Promise.all([
+    conn.executeQuery(dataCypher, params, { repositoryId, routing: "READ" }),
+    hasPropertyFilters ? Promise.resolve(null) : conn.executeQuery(countCypher, params, { repositoryId, routing: "READ" })
+  ]);
+  let items = dataResult.records.map((record) => relationshipFromRecord(record));
+  if (hasPropertyFilters) {
+    items = items.filter((rel) => matchesPropertyFilters(rel.properties, propertyFilters));
+  }
+  let total;
+  if (countResult !== null) {
+    const totalRecord = countResult.records[0];
+    total = totalRecord !== void 0 ? bigintToSafeNumber(totalRecord.get("total") ?? 0) : 0;
+  }
+  const hasMore = total !== void 0 ? offset + dataResult.records.length < total : dataResult.records.length === limit;
+  return { items, total, hasMore, limit, offset };
+}
+async function deleteRelationship(conn, repositoryId, relationshipId) {
+  await conn.executeQuery(
+    "MATCH ()-[r {repositoryId: $rid, id: $relId}]->() DELETE r",
+    { relId: relationshipId },
+    { repositoryId }
+  );
+}
+async function deleteRelationships(conn, repositoryId, ids) {
+  if (ids.length === 0) return { deleted: [], notFound: [] };
+  const result = await conn.executeQuery(
+    "MATCH ()-[r {repositoryId: $rid}]->() WHERE r.id IN $ids WITH r, r.id AS id DELETE r RETURN id AS deleted",
+    { ids },
+    { repositoryId }
+  );
+  const deleted = [];
+  for (const record of result.records) {
+    const id = record.get("deleted");
+    if (typeof id === "string") deleted.push(id);
+  }
+  const deletedSet = new Set(deleted);
+  const notFound = ids.filter((id) => !deletedSet.has(id));
+  return { deleted, notFound };
+}
+async function deleteRelationshipsByType(conn, repositoryId, relationshipType) {
+  const relType = assertSafeRelationshipType(relationshipType);
+  const result = await conn.executeQuery(
+    `MATCH ()-[r:${relType} {repositoryId: $rid}]->() WITH r, r.id AS id DELETE r RETURN id`,
+    {},
+    { repositoryId }
+  );
+  return { deletedRelationships: result.records.length };
+}
+function buildTypeFilter(relationshipTypes, params) {
+  params["relTypes"] = relationshipTypes;
+  return " WHERE type(r) IN $relTypes";
+}
+function buildEntityRelationshipQueries(direction, typeFilter) {
+  if (direction === "both") {
+    const dataCypher2 = `MATCH (e:_Entity {repositoryId: $rid, id: $eid})-[r {repositoryId: $rid}]-()${typeFilter} RETURN ${RELATIONSHIP_PROJECTION} ORDER BY id SKIP $offset LIMIT $limit`;
+    const countCypher2 = `MATCH (e:_Entity {repositoryId: $rid, id: $eid})-[r {repositoryId: $rid}]-()${typeFilter} RETURN count(r) AS total`;
+    return { dataCypher: dataCypher2, countCypher: countCypher2 };
+  }
+  const naturalPattern = direction === "out" ? "(e:_Entity {repositoryId: $rid, id: $eid})-[r {repositoryId: $rid}]->()" : "()-[r {repositoryId: $rid}]->(e:_Entity {repositoryId: $rid, id: $eid})";
+  const bidirPattern = direction === "out" ? "()-[r {repositoryId: $rid, bidirectional: true}]->(e:_Entity {repositoryId: $rid, id: $eid})" : "(e:_Entity {repositoryId: $rid, id: $eid})-[r {repositoryId: $rid, bidirectional: true}]->()";
+  const dataCypher = `CALL () {
+  MATCH ${naturalPattern}${typeFilter} RETURN ${RELATIONSHIP_PROJECTION}
+  UNION ALL
+  MATCH ${bidirPattern}${typeFilter} RETURN ${RELATIONSHIP_PROJECTION}
+}
+RETURN ${reprojectFromCallScope()} ORDER BY id SKIP $offset LIMIT $limit`;
+  const countCypher = `CALL () {
+  MATCH ${naturalPattern}${typeFilter} RETURN r.id AS rid
+  UNION ALL
+  MATCH ${bidirPattern}${typeFilter} RETURN r.id AS rid
+}
+RETURN count(rid) AS total`;
+  return { dataCypher, countCypher };
+}
+function reprojectFromCallScope() {
+  return RELATIONSHIP_PROJECTION.split(",").map((part) => {
+    const segments = part.trim().split(" AS ");
+    const fieldName = (segments[1] ?? segments[0] ?? "").trim();
+    return `${fieldName} AS ${fieldName}`;
+  }).join(", ");
+}
+
+// src/queries/repository.ts
+var ENTITY_STATS_QUERY = `
+MATCH (n:_Entity {repositoryId: $rid})
+RETURN n.entityType AS type, count(n) AS count
+`;
+var RELATIONSHIP_STATS_QUERY = `
+MATCH (:_Entity {repositoryId: $rid})-[r {repositoryId: $rid}]->(:_Entity {repositoryId: $rid})
+RETURN type(r) AS type, count(r) AS count
+`;
+async function getRepositoryStats(conn, repositoryId, vocabulary) {
+  const [entityResult, relationshipResult] = await Promise.all([
+    conn.executeQuery(ENTITY_STATS_QUERY, {}, { repositoryId, routing: "READ" }),
+    conn.executeQuery(RELATIONSHIP_STATS_QUERY, {}, { repositoryId, routing: "READ" })
+  ]);
+  const entityTypeBreakdown = {};
+  let entityCount = 0;
+  for (const record of entityResult.records) {
+    const type = record.get("type");
+    if (typeof type !== "string") continue;
+    const count = bigintToSafeNumber(record.get("count") ?? 0);
+    entityTypeBreakdown[type] = count;
+    entityCount += count;
+  }
+  const relationshipTypeBreakdown = {};
+  let relationshipCount = 0;
+  for (const record of relationshipResult.records) {
+    const type = record.get("type");
+    if (typeof type !== "string") continue;
+    const count = bigintToSafeNumber(record.get("count") ?? 0);
+    relationshipTypeBreakdown[type] = count;
+    relationshipCount += count;
+  }
+  return {
+    entityCount,
+    relationshipCount,
+    vocabularyVersion: vocabulary.version,
+    entityTypeBreakdown,
+    relationshipTypeBreakdown
+  };
+}
+
+// src/queries/timeline.ts
+var ENTITY_CREATED = "entity:created";
+var ENTITY_UPDATED = "entity:updated";
+var RELATIONSHIP_CREATED = "relationship:created";
+var TIMELINE_QUERY = `
+MATCH (n:_Entity {repositoryId: $rid, id: $id})
+OPTIONAL MATCH (n)-[r {repositoryId: $rid}]-()
+WITH n, collect(DISTINCT r) AS rels
+RETURN
+  n.createdAt AS createdAt,
+  n.modifiedAt AS modifiedAt,
+  [x IN rels WHERE x IS NOT NULL | {id: x.id, createdAt: x.createdAt}] AS rels
+`;
+async function getTimeline(conn, repositoryId, entityId, options) {
+  const result = await conn.executeQuery(
+    TIMELINE_QUERY,
+    { id: entityId },
+    { repositoryId, routing: "READ" }
+  );
+  const record = result.records[0];
+  if (record === void 0) {
+    return { events: [], total: 0 };
+  }
+  const createdAt = record.get("createdAt");
+  const modifiedAt = record.get("modifiedAt");
+  const relsRaw = record.get("rels");
+  const events = [];
+  if (typeof createdAt === "string" && createdAt.length > 0) {
+    events.push({ timestamp: createdAt, eventType: ENTITY_CREATED, entityId });
+  }
+  if (typeof modifiedAt === "string" && modifiedAt.length > 0 && modifiedAt !== createdAt) {
+    events.push({ timestamp: modifiedAt, eventType: ENTITY_UPDATED, entityId });
+  }
+  if (Array.isArray(relsRaw)) {
+    for (const item of relsRaw) {
+      if (item === null || typeof item !== "object") continue;
+      const rel = item;
+      const relId = rel.id;
+      const relCreatedAt = rel.createdAt;
+      if (typeof relId !== "string" || typeof relCreatedAt !== "string") continue;
+      events.push({
+        timestamp: relCreatedAt,
+        eventType: RELATIONSHIP_CREATED,
+        entityId,
+        relationshipId: relId
+      });
+    }
+  }
+  let filtered = events;
+  if (options.timeRange) {
+    const from = options.timeRange.from;
+    const to = options.timeRange.to;
+    filtered = filtered.filter((e) => e.timestamp >= from && e.timestamp <= to);
+  }
+  if (options.eventTypes && options.eventTypes.length > 0) {
+    const allow = new Set(options.eventTypes);
+    filtered = filtered.filter((e) => allow.has(e.eventType));
+  }
+  filtered.sort((a, b) => a.timestamp < b.timestamp ? 1 : a.timestamp > b.timestamp ? -1 : 0);
+  const total = filtered.length;
+  const paged = filtered.slice(options.offset, options.offset + options.limit);
+  return { events: paged, total };
+}
+
+// src/queries/vocabulary.ts
+function emptyVocabulary() {
+  return {
+    version: "0.0.0",
+    lastModified: (/* @__PURE__ */ new Date()).toISOString(),
+    modifiedBy: "system",
+    entityTypes: [],
+    relationshipTypes: []
+  };
+}
+async function getVocabulary(conn, repositoryId) {
+  const result = await conn.executeQuery(
+    "MATCH (v:_Vocabulary {repositoryId: $rid}) RETURN v.vocabulary AS json",
+    {},
+    { repositoryId, routing: "READ" }
+  );
+  const record = result.records[0];
+  if (record === void 0) return emptyVocabulary();
+  const raw = record.get("json");
+  if (typeof raw !== "string" || raw === "") return emptyVocabulary();
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return emptyVocabulary();
+  }
+}
+async function saveVocabulary(conn, repositoryId, vocabulary) {
+  await conn.executeQuery(
+    "MERGE (v:_Vocabulary {repositoryId: $rid}) SET v.vocabulary = $json",
+    { json: JSON.stringify(vocabulary) },
+    { repositoryId }
+  );
+}
+async function getVocabularyChangeLog(conn, repositoryId, options) {
+  const limit = options?.limit ?? 10;
+  const offset = options?.offset ?? 0;
+  const [dataResult, countResult] = await Promise.all([
+    conn.executeQuery(
+      `MATCH (e:_VocabularyChangeLog {repositoryId: $rid})
+       RETURN e
+       ORDER BY e.proposedAt DESC
+       SKIP $offset LIMIT $limit`,
+      { offset: BigInt(offset), limit: BigInt(limit) },
+      { repositoryId, routing: "READ" }
+    ),
+    conn.executeQuery(
+      "MATCH (e:_VocabularyChangeLog {repositoryId: $rid}) RETURN count(e) AS total",
+      {},
+      { repositoryId, routing: "READ" }
+    )
+  ]);
+  const items = dataResult.records.map((record) => changeRecordFromRecord(record, "e"));
+  const totalRaw = countResult.records[0]?.get("total");
+  const total = totalRaw === void 0 ? 0 : bigintToSafeNumber(totalRaw);
+  return {
+    items,
+    total,
+    hasMore: offset + items.length < total,
+    limit,
+    offset
+  };
+}
+
+// src/schema.ts
+var SCHEMA_VERSION = 1;
+function getSchemaCypher() {
+  return [
+    // Composite node-property uniqueness on (repositoryId, id) — the load-bearing
+    // primary discriminator for every entity-scoped query.
+    `CREATE CONSTRAINT dm_entity_unique IF NOT EXISTS
+FOR (n:_Entity) REQUIRE (n.repositoryId, n.id) IS UNIQUE`,
+    // Composite uniqueness on (repositoryId, slug) — backs getEntityBySlug
+    // and guarantees stable URL-style addressing within a repository.
+    `CREATE CONSTRAINT dm_entity_slug_unique IF NOT EXISTS
+FOR (n:_Entity) REQUIRE (n.repositoryId, n.slug) IS UNIQUE`,
+    // Repository uniqueness — backs getRepository and listRepositories.
+    `CREATE CONSTRAINT dm_repository_unique IF NOT EXISTS
+FOR (n:_Repository) REQUIRE n.repositoryId IS UNIQUE`,
+    // Range index (default for `CREATE INDEX` without a type keyword) covering
+    // (repositoryId, entityType) — backs findEntities type-filter and
+    // deleteEntitiesByType.
+    `CREATE INDEX dm_entity_type_lookup IF NOT EXISTS
+FOR (n:_Entity) ON (n.repositoryId, n.entityType)`,
+    // Range index on (repositoryId, modifiedAt) — backs timeline and recency
+    // ordering. Date is stored as ISO-8601 string (D6), lexicographic order
+    // matches chronological order.
+    `CREATE INDEX dm_entity_modified IF NOT EXISTS
+FOR (n:_Entity) ON (n.repositoryId, n.modifiedAt)`,
+    // Fulltext index on entity label + summary — backs the findEntities
+    // searchTerm branch via CALL db.index.fulltext.queryNodes(...). Unfiltered
+    // by design; query callers must post-filter by repositoryId (see D3b).
+    `CREATE FULLTEXT INDEX dm_entity_text IF NOT EXISTS
+FOR (n:_Entity) ON EACH [n.label, n.summary]`
+  ];
+}
+
+// src/Neo4jStorageProvider.ts
+var PROVIDER_NAME = "neo4j";
+var DELETE_BATCH_SIZE = 500;
+var VOCABULARY_CACHE_TTL_MS = 6e4;
+var TRACKED_METHODS = {
+  ensureSchema: () => void 0,
+  createRepository: (args) => {
+    const cfg = args[0];
+    return cfg?.repositoryId;
+  },
+  getRepository: (args) => args[0],
+  listRepositories: () => void 0,
+  updateRepository: (args) => args[0],
+  deleteRepository: (args) => args[0],
+  deleteAllContents: (args) => args[0],
+  getVocabulary: (args) => args[0],
+  saveVocabulary: (args) => args[0],
+  getVocabularyChangeLog: (args) => args[0],
+  createEntity: (args) => args[0],
+  getEntity: (args) => args[0],
+  getEntityBySlug: (args) => args[0],
+  getEntities: (args) => args[0],
+  updateEntity: (args) => args[0],
+  deleteEntity: (args) => args[0],
+  deleteEntities: (args) => args[0],
+  deleteEntitiesByType: (args) => args[0],
+  findEntities: (args) => args[0],
+  createRelationship: (args) => args[0],
+  getRelationship: (args) => args[0],
+  getEntityRelationships: (args) => args[0],
+  deleteRelationship: (args) => args[0],
+  deleteRelationships: (args) => args[0],
+  deleteRelationshipsByType: (args) => args[0],
+  traverse: (args) => args[0],
+  exploreNeighborhood: (args) => args[0],
+  findPaths: (args) => args[0],
+  getTimeline: (args) => args[0],
+  getRepositoryStats: (args) => args[0],
+  importBulk: (args) => args[0],
+  // `executeNativeQuery` is cross-repository by design. The first positional
+  // argument is `repositoryId` for interface symmetry but is intentionally
+  // not stamped on the sink record — the call is not scoped to one repository.
+  executeNativeQuery: () => void 0
+  // `exportAll` is intentionally omitted from this map. The Proxy emits one
+  // sink record at promise resolution; an `AsyncIterable` returns
+  // synchronously and is consumed across an arbitrary number of awaits, so
+  // a single emit at method-return would fire BEFORE any chunk had streamed
+  // and the sink would carry zero round-trips. `exportAll` opens its own
+  // usage scope via `trackIterable` and emits when the iterator drains.
+};
+var META_KEY = "schema";
+var Neo4jStorageProvider = class {
+  connection;
+  traversalExecutor;
+  initialized = false;
+  /**
+   * In-process vocabulary cache. Reads hit this map first; writes inside this
+   * process invalidate the entry so cache hits stay coherent with the local
+   * write. Cross-process staleness is bounded by `VOCABULARY_CACHE_TTL_MS`.
+   */
+  vocabularyCache = /* @__PURE__ */ new Map();
+  /**
+   * Captured at construction so `exportAll`'s `trackIterable` can emit
+   * outside the Proxy's promise-resolution path. The Proxy itself relies on
+   * the same `safeSink` captured by closure; this field exists for the
+   * streaming-iterator case only.
+   */
+  reportUsage;
+  constructor(config) {
+    this.connection = new Neo4jConnection(config);
+    this.traversalExecutor = new Neo4jTraversalExecutor(this.connection, {
+      profileTraversals: config.profileTraversals === true
+    });
+    const safeSink = createSafeSink(config.reportUsage);
+    this.reportUsage = safeSink;
+    if (safeSink) {
+      return new Proxy(this, {
+        get(target, prop, receiver) {
+          const value = Reflect.get(target, prop, receiver);
+          if (typeof prop !== "string" || typeof value !== "function") return value;
+          const extractRepoId = TRACKED_METHODS[prop];
+          if (!extractRepoId) return value;
+          const method = value;
+          return (...args) => {
+            const scope = createUsageScope();
+            const repositoryId = extractRepoId(args);
+            const emit = () => {
+              safeSink({
+                provider: PROVIDER_NAME,
+                operation: prop,
+                unit: "server_ms",
+                value: scope.serverMs,
+                ...repositoryId !== void 0 ? { repositoryId } : {},
+                timestamp: /* @__PURE__ */ new Date(),
+                details: buildUsageDetails(scope)
+              });
+            };
+            return runInUsageScope(scope, () => {
+              let result;
+              try {
+                result = method.apply(target, args);
+              } catch (err) {
+                emit();
+                throw err;
+              }
+              if (result && typeof result.then === "function") {
+                return result.then(
+                  (v) => {
+                    emit();
+                    return v;
+                  },
+                  (err) => {
+                    emit();
+                    throw err;
+                  }
+                );
+              }
+              emit();
+              return result;
+            });
+          };
+        }
+      });
+    }
+  }
+  // ─── Lifecycle ─────────────────────────────────────────────────────
+  async initialize() {
+    if (this.initialized) return;
+    await this.connection.verifyConnectivity();
+    this.initialized = true;
+  }
+  async dispose() {
+    await this.connection.close();
+    this.initialized = false;
+  }
+  // ─── Schema ────────────────────────────────────────────────────────
+  /**
+   * Idempotent constraint / index DDL plus a single `_Meta` schema-version
+   * handshake. Safe to call repeatedly — `CREATE ... IF NOT EXISTS` makes
+   * each statement a no-op on subsequent runs.
+   *
+   * Neo4j Community has no per-tenant database concept — `databaseCreated`
+   * is always `false`. Operators are responsible for the target database
+   * existing before the provider connects.
+   */
+  async ensureSchema() {
+    const currentVersion = await this.readSchemaVersion();
+    if (currentVersion !== null && currentVersion > SCHEMA_VERSION) {
+      throw new ProviderError7(
+        `Database schema version ${currentVersion} is newer than provider version ${SCHEMA_VERSION}. Update the @utaba/deep-memory-storage-neo4j package.`
+      );
+    }
+    if (currentVersion === SCHEMA_VERSION) {
+      return {
+        databaseCreated: false,
+        schemaCreated: false,
+        alreadyUpToDate: true,
+        schemaVersion: SCHEMA_VERSION
+      };
+    }
+    for (const statement of getSchemaCypher()) {
+      await this.connection.executeSystemDdl(statement);
+    }
+    await this.writeSchemaVersion(SCHEMA_VERSION);
+    return {
+      databaseCreated: false,
+      schemaCreated: true,
+      alreadyUpToDate: false,
+      schemaVersion: SCHEMA_VERSION
+    };
+  }
+  async readSchemaVersion() {
+    const result = await this.connection.executeSystemQuery(
+      "MATCH (m:_Meta {key: $key}) RETURN m.schemaVersion AS schemaVersion",
+      { key: META_KEY },
+      { crossRepository: true, routing: "READ" }
+    );
+    const record = result.records[0];
+    if (record === void 0) return null;
+    const raw = record.get("schemaVersion");
+    if (typeof raw === "bigint") {
+      if (raw > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new ProviderError7(
+          `_Meta.schemaVersion (${raw.toString()}) exceeds Number.MAX_SAFE_INTEGER.`
+        );
+      }
+      return Number(raw);
+    }
+    if (typeof raw === "number") return raw;
+    if (raw === null) return null;
+    throw new ProviderError7(
+      `_Meta.schemaVersion has unexpected type ${typeof raw}; expected bigint or number.`
+    );
+  }
+  async writeSchemaVersion(version) {
+    await this.connection.executeSystemQuery(
+      "MERGE (m:_Meta {key: $key}) SET m.schemaVersion = $version",
+      { key: META_KEY, version },
+      { crossRepository: true }
+    );
+  }
+  // ─── Repository ────────────────────────────────────────────────────
+  /**
+   * Create a new repository. Fixed-shape `CREATE` template — every optional
+   * field is bound on every call so the server plan-caches one entry across
+   * all repository creates. Optional fields bound as `null` are not persisted
+   * (Cypher drops null property values on write — symmetric with read).
+   *
+   * The `(:_Repository) REQUIRE n.repositoryId IS UNIQUE` constraint surfaces
+   * duplicates as `Neo.ClientError.Schema.ConstraintValidationFailed`, which
+   * `mapDriverError({ kind: 'repository', ... })` routes to
+   * `DuplicateRepositoryError`.
+   */
+  async createRepository(config) {
+    try {
+      await this.connection.executeQuery(
+        `CREATE (r:_Repository {
+          repositoryId: $rid,
+          type: $type,
+          label: $label,
+          description: $description,
+          legal: $legal,
+          owner: $owner,
+          governanceConfig: $governanceConfig,
+          metadata: $metadata,
+          createdAt: $createdAt,
+          createdBy: $createdBy
+        })`,
+        repositoryCreateParams(config),
+        { repositoryId: config.repositoryId }
+      );
+    } catch (err) {
+      mapDriverError(err, {
+        kind: "repository",
+        repositoryId: config.repositoryId,
+        operation: "createRepository"
+      });
+    }
+    const result = {
+      repositoryId: config.repositoryId,
+      label: config.label,
+      governanceConfig: config.governanceConfig,
+      createdAt: config.createdAt,
+      createdBy: config.createdBy
+    };
+    if (config.type !== void 0) result.type = config.type;
+    if (config.description !== void 0) result.description = config.description;
+    if (config.legal !== void 0) result.legal = config.legal;
+    if (config.owner !== void 0) result.owner = config.owner;
+    if (config.metadata !== void 0) result.metadata = config.metadata;
+    return result;
+  }
+  async getRepository(repositoryId) {
+    const result = await this.connection.executeQuery(
+      "MATCH (r:_Repository {repositoryId: $rid}) RETURN r",
+      {},
+      { repositoryId, routing: "READ" }
+    );
+    const record = result.records[0];
+    if (record === void 0) return null;
+    return repositoryFromRecord(record);
+  }
+  async listRepositories(filter) {
+    const limit = filter?.limit ?? 20;
+    const offset = filter?.offset ?? 0;
+    const typeFilter = filter?.type;
+    const wherePredicates = [];
+    const params = { offset: BigInt(offset), limit: BigInt(limit) };
+    if (typeFilter !== void 0) {
+      wherePredicates.push("r.type = $filterType");
+      params["filterType"] = typeFilter;
+    }
+    const whereClause = wherePredicates.length > 0 ? `WHERE ${wherePredicates.join(" AND ")}` : "";
+    const [dataResult, countResult] = await Promise.all([
+      this.connection.executeSystemQuery(
+        `MATCH (r:_Repository) ${whereClause} RETURN r ORDER BY r.repositoryId SKIP $offset LIMIT $limit`,
+        params,
+        { crossRepository: true, routing: "READ" }
+      ),
+      this.connection.executeSystemQuery(
+        `MATCH (r:_Repository) ${whereClause} RETURN count(r) AS total`,
+        typeFilter !== void 0 ? { filterType: typeFilter } : {},
+        { crossRepository: true, routing: "READ" }
+      )
+    ]);
+    const items = dataResult.records.map((record) => repositorySummaryFromRecord(record));
+    const totalRaw = countResult.records[0]?.get("total");
+    const total = totalRaw === void 0 ? 0 : bigintToSafeNumber(totalRaw);
+    return {
+      items,
+      total,
+      hasMore: offset + items.length < total,
+      limit,
+      offset
+    };
+  }
+  /**
+   * Variable-shape Cypher (per D23 trade-off — repository writes are rare so
+   * the plan-cache cost is negligible). Projection-on-write returns the
+   * updated row in one round-trip; empty-rowset → `RepositoryNotFoundError`.
+   */
+  async updateRepository(repositoryId, updates) {
+    const setClauses = [];
+    const params = {};
+    if (updates.label !== void 0) {
+      setClauses.push("r.label = $label");
+      params["label"] = updates.label;
+    }
+    if (updates.description !== void 0) {
+      setClauses.push("r.description = $description");
+      params["description"] = updates.description;
+    }
+    if (updates.type !== void 0) {
+      setClauses.push("r.type = $type");
+      params["type"] = updates.type;
+    }
+    if (updates.legal !== void 0) {
+      setClauses.push("r.legal = $legal");
+      params["legal"] = updates.legal;
+    }
+    if (updates.owner !== void 0) {
+      setClauses.push("r.owner = $owner");
+      params["owner"] = updates.owner;
+    }
+    if (updates.governanceConfig !== void 0) {
+      setClauses.push("r.governanceConfig = $governanceConfig");
+      params["governanceConfig"] = JSON.stringify(updates.governanceConfig);
+    }
+    if (updates.metadata !== void 0) {
+      const existing = await this.getRepository(repositoryId);
+      if (existing === null) throw new RepositoryNotFoundError(repositoryId);
+      const merged = { ...existing.metadata, ...updates.metadata };
+      setClauses.push("r.metadata = $metadata");
+      params["metadata"] = JSON.stringify(merged);
+    }
+    if (setClauses.length === 0) {
+      const existing = await this.getRepository(repositoryId);
+      if (existing === null) throw new RepositoryNotFoundError(repositoryId);
+      return existing;
+    }
+    const cypher = `MATCH (r:_Repository {repositoryId: $rid}) SET ${setClauses.join(", ")} RETURN r`;
+    const result = await this.connection.executeQuery(cypher, params, { repositoryId });
+    const record = result.records[0];
+    if (record === void 0) throw new RepositoryNotFoundError(repositoryId);
+    return repositoryFromRecord(record);
+  }
+  /**
+   * Drop every node and relationship scoped to `repositoryId`, including the
+   * `_Repository` node itself. Two-stage chunked wipe driven by app-side loops
+   * so the progress callback fires at a useful cadence:
+   *
+   *   1. Drain relationships in batches via `CALL ( ) { ... } IN TRANSACTIONS`.
+   *   2. Drain nodes (entities + system) in batches via the same form with
+   *      `DETACH DELETE` (catches any straggler edges).
+   *
+   * `IN TRANSACTIONS` can only run on auto-commit sessions — `executeWrite`
+   * fails with `Neo.DatabaseError.Transaction.TransactionStartFailed` per
+   * probe P13. The chokepoint's `executeImplicitInTransactions` is the only
+   * legitimate entry point for this pattern.
+   */
+  async deleteRepository(repositoryId, onProgress) {
+    const { totalEntities, totalRelationships } = await this.countRepositoryContents(repositoryId);
+    let relationshipsDeleted = 0;
+    let entitiesDeleted = 0;
+    while (true) {
+      const summary = await this.connection.executeImplicitInTransactions(
+        `CALL () {
+           MATCH ()-[r {repositoryId: $rid}]-()
+           WITH r LIMIT $batchSize
+           DELETE r
+         } IN TRANSACTIONS OF $batchSize ROWS`,
+        // BigInt so the Cypher LIMIT clause sees a Cypher INTEGER, not FLOAT.
+        { batchSize: BigInt(DELETE_BATCH_SIZE) },
+        { repositoryId }
+      );
+      const stats = summary.counters.updates();
+      const deletedThisBatch = stats["relationshipsDeleted"] ?? 0;
+      if (deletedThisBatch === 0) break;
+      relationshipsDeleted = Math.min(relationshipsDeleted + deletedThisBatch, totalRelationships);
+      await onProgress?.({ entitiesDeleted, relationshipsDeleted, totalEntities, totalRelationships });
+    }
+    while (true) {
+      const summary = await this.connection.executeImplicitInTransactions(
+        `CALL () {
+           MATCH (n {repositoryId: $rid})
+           WITH n LIMIT $batchSize
+           DETACH DELETE n
+         } IN TRANSACTIONS OF $batchSize ROWS`,
+        // BigInt so the Cypher LIMIT clause sees a Cypher INTEGER, not FLOAT.
+        { batchSize: BigInt(DELETE_BATCH_SIZE) },
+        { repositoryId }
+      );
+      const stats = summary.counters.updates();
+      const deletedThisBatch = stats["nodesDeleted"] ?? 0;
+      if (deletedThisBatch === 0) break;
+      entitiesDeleted = Math.min(entitiesDeleted + deletedThisBatch, totalEntities);
+      await onProgress?.({ entitiesDeleted, relationshipsDeleted, totalEntities, totalRelationships });
+    }
+  }
+  /**
+   * Drop every entity and relationship scoped to `repositoryId` but preserve
+   * the `_Repository` and `_Vocabulary` / `_VocabularyChangeLog` system nodes.
+   * Same chunked-wipe contract as `deleteRepository`, restricted to the
+   * `:_Entity` umbrella label for nodes.
+   */
+  async deleteAllContents(repositoryId, onProgress) {
+    const { totalEntities, totalRelationships } = await this.countRepositoryContents(repositoryId);
+    let relationshipsDeleted = 0;
+    let entitiesDeleted = 0;
+    while (true) {
+      const summary = await this.connection.executeImplicitInTransactions(
+        `CALL () {
+           MATCH (:_Entity {repositoryId: $rid})-[r {repositoryId: $rid}]-(:_Entity {repositoryId: $rid})
+           WITH r LIMIT $batchSize
+           DELETE r
+         } IN TRANSACTIONS OF $batchSize ROWS`,
+        // BigInt so the Cypher LIMIT clause sees a Cypher INTEGER, not FLOAT.
+        { batchSize: BigInt(DELETE_BATCH_SIZE) },
+        { repositoryId }
+      );
+      const stats = summary.counters.updates();
+      const deletedThisBatch = stats["relationshipsDeleted"] ?? 0;
+      if (deletedThisBatch === 0) break;
+      relationshipsDeleted = Math.min(relationshipsDeleted + deletedThisBatch, totalRelationships);
+      await onProgress?.({ entitiesDeleted, relationshipsDeleted, totalEntities, totalRelationships });
+    }
+    while (true) {
+      const summary = await this.connection.executeImplicitInTransactions(
+        `CALL () {
+           MATCH (n:_Entity {repositoryId: $rid})
+           WITH n LIMIT $batchSize
+           DETACH DELETE n
+         } IN TRANSACTIONS OF $batchSize ROWS`,
+        // BigInt so the Cypher LIMIT clause sees a Cypher INTEGER, not FLOAT.
+        { batchSize: BigInt(DELETE_BATCH_SIZE) },
+        { repositoryId }
+      );
+      const stats = summary.counters.updates();
+      const deletedThisBatch = stats["nodesDeleted"] ?? 0;
+      if (deletedThisBatch === 0) break;
+      entitiesDeleted = Math.min(entitiesDeleted + deletedThisBatch, totalEntities);
+      await onProgress?.({ entitiesDeleted, relationshipsDeleted, totalEntities, totalRelationships });
+    }
+    return { deletedEntities: totalEntities, deletedRelationships: totalRelationships };
+  }
+  /**
+   * One-shot pre-count used by `deleteRepository` / `deleteAllContents`. The
+   * entity count uses the umbrella `:_Entity` label so system nodes
+   * (`_Repository` / `_Vocabulary`) are excluded — that matches the
+   * user-facing semantics of the progress callback.
+   *
+   * The relationship count uses the **directed** pattern `()-[r]->()`: every
+   * edge is written in its stored direction (D5), so the directed pattern
+   * binds each edge to exactly one row. An undirected `-` pattern would
+   * double-count every edge whose endpoints are distinct vertices, because
+   * Cypher enumerates the pattern from both directions.
+   */
+  async countRepositoryContents(repositoryId) {
+    const [entitiesResult, relationshipsResult] = await Promise.all([
+      this.connection.executeQuery(
+        "MATCH (n:_Entity {repositoryId: $rid}) RETURN count(n) AS total",
+        {},
+        { repositoryId, routing: "READ" }
+      ),
+      this.connection.executeQuery(
+        "MATCH ()-[r {repositoryId: $rid}]->() RETURN count(r) AS total",
+        {},
+        { repositoryId, routing: "READ" }
+      )
+    ]);
+    const totalEntities = bigintToSafeNumber(entitiesResult.records[0]?.get("total") ?? 0);
+    const totalRelationships = bigintToSafeNumber(relationshipsResult.records[0]?.get("total") ?? 0);
+    return { totalEntities, totalRelationships };
+  }
+  // ─── Vocabulary ────────────────────────────────────────────────────
+  /**
+   * Read the vocabulary for a repository. Cache-aware: cache hits return
+   * synchronously with zero Bolt round-trips. The TRACKED_METHODS proxy still
+   * fires for every call — the sink record on a cache hit carries
+   * `details.calls === 0` and `value === 0`, which is the contract the sink
+   * expects to express "this operation ran but did no server work".
+   */
+  async getVocabulary(repositoryId) {
+    return this.getVocabularyCached(repositoryId);
+  }
+  /**
+   * Cached vocabulary read used by `getVocabulary` and (in later phases) by
+   * traversal compilation. The vocabulary is compile-time context for the
+   * Cypher compiler — it changes on the order of once per session, but the
+   * traversal hot path would otherwise pay one round-trip per call. The cache
+   * flips that to one round-trip per TTL window.
+   *
+   * Reads inside an active usage scope still record a round-trip when a fetch
+   * actually happens (cache miss); cache hits emit no round-trip and therefore
+   * contribute nothing to the scope.
+   */
+  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.connection, repositoryId);
+    this.vocabularyCache.set(repositoryId, {
+      vocab,
+      expiresAt: now + VOCABULARY_CACHE_TTL_MS
+    });
+    return vocab;
+  }
+  /** Drop the cache entry for a repository — call after every vocabulary write. */
+  invalidateVocabularyCache(repositoryId) {
+    this.vocabularyCache.delete(repositoryId);
+  }
+  /**
+   * Upsert the vocabulary for a repository. Invalidates the in-process cache
+   * on success so subsequent reads observe the new state immediately within
+   * this process (cross-process staleness is bounded by the 60 s TTL).
+   */
+  async saveVocabulary(repositoryId, vocabulary) {
+    await saveVocabulary(this.connection, repositoryId, vocabulary);
+    this.invalidateVocabularyCache(repositoryId);
+  }
+  /**
+   * Page the vocabulary change-log newest first. Writes land in
+   * `proposeVocabularyExtension` (out of scope here) — this method only reads
+   * the `_VocabularyChangeLog` nodes back, ordered by `proposedAt` to match
+   * the audit semantic on `VocabularyChangeRecord`.
+   */
+  async getVocabularyChangeLog(repositoryId, options) {
+    return getVocabularyChangeLog(this.connection, repositoryId, options);
+  }
+  // ─── Entities ──────────────────────────────────────────────────────
+  /**
+   * Create a new entity via fixed-shape `CREATE` + catch on the uniqueness
+   * constraint. A `MERGE`-with-discriminator alternative is marginally faster
+   * on the happy path but mutates the existing node on collisions, writing
+   * a discriminator property onto durable graph state the caller never
+   * requested — correctness wins over the marginal perf delta.
+   */
+  async createEntity(repositoryId, entity) {
+    return createEntity(this.connection, repositoryId, entity);
+  }
+  /** Read a single entity by id; `null` when not found. */
+  async getEntity(repositoryId, entityId, options) {
+    return getEntity(this.connection, repositoryId, entityId, options);
+  }
+  /** Read a single entity by slug; `null` when not found. */
+  async getEntityBySlug(repositoryId, slug, options) {
+    return getEntityBySlug(this.connection, repositoryId, slug, options);
+  }
+  /**
+   * Batch read by ids. Absent ids do not appear in the returned `Map`; empty
+   * input returns an empty map without a round-trip.
+   */
+  async getEntities(repositoryId, entityIds, options) {
+    return getEntities(this.connection, repositoryId, entityIds, options);
+  }
+  /**
+   * Variable-shape projection-on-write update (D23) — single round-trip
+   * MATCH+SET+RETURN. Empty record array → `EntityNotFoundError`.
+   */
+  async updateEntity(repositoryId, entityId, updates) {
+    return updateEntity(this.connection, repositoryId, entityId, updates);
+  }
+  /**
+   * Delete a single entity (and its incident relationships via `DETACH
+   * DELETE`). Throws `EntityNotFoundError` when the match returns zero rows.
+   */
+  async deleteEntity(repositoryId, entityId) {
+    return deleteEntity(this.connection, repositoryId, entityId);
+  }
+  /**
+   * Bulk delete by ids — single round-trip. Returns the ids actually
+   * deleted; missing ids land in `notFound`.
+   */
+  async deleteEntities(repositoryId, ids) {
+    return deleteEntities(this.connection, repositoryId, ids);
+  }
+  /**
+   * Delete every entity of a type plus their incident relationships, with
+   * exact counts (entity + relationship) returned in one round-trip — a
+   * strict improvement over Cosmos's `deletedRelationships: undefined` path
+   * (Gremlin would fan out across every partition the type touches).
+   */
+  async deleteEntitiesByType(repositoryId, entityType) {
+    return deleteEntitiesByType(this.connection, repositoryId, entityType);
+  }
+  /**
+   * Page entities matching a `StorageFindQuery`. Parallel data + count Cypher
+   * pair; `total` is always exact because every filter (entity-type, property
+   * equality, search term, provenance) is server-side via either a typed
+   * predicate or the `dm_entity_text` fulltext index. Search-term queries
+   * order by Lucene score descending; non-search queries order by `n.id` to
+   * pin pagination determinism across slices.
+   */
+  async findEntities(repositoryId, query, options) {
+    return findEntities(this.connection, repositoryId, query, options);
+  }
+  // ─── Relationships ─────────────────────────────────────────────────
+  /**
+   * Create a relationship. Both endpoint entities are matched under the
+   * repository scope before the edge is created, so cross-repository edges
+   * are structurally impossible to write (D3b layer 3). A missing endpoint
+   * surfaces as `EntityNotFoundError` carrying the absent id.
+   */
+  async createRelationship(repositoryId, relationship) {
+    return createRelationship(this.connection, repositoryId, relationship);
+  }
+  /** Read a single relationship by id; `null` when not found. */
+  async getRelationship(repositoryId, relationshipId) {
+    return getRelationship(this.connection, repositoryId, relationshipId);
+  }
+  /**
+   * Page an entity's incident relationships. `direction: 'out' | 'in'`
+   * additionally surfaces edges flagged `bidirectional: true` from the
+   * opposite endpoint, mirroring the Cosmos read-time duplication of bidir
+   * edges. `propertyFilters` is applied client-side and reports
+   * `total: undefined` in that branch — same trade-off as the Cosmos
+   * provider, because relationship `properties` is a JSON blob with no
+   * per-key index.
+   */
+  async getEntityRelationships(repositoryId, entityId, options) {
+    return getEntityRelationships(
+      this.connection,
+      repositoryId,
+      entityId,
+      options
+    );
+  }
+  /** Drop a single relationship by id. No-op when the id does not match. */
+  async deleteRelationship(repositoryId, relationshipId) {
+    return deleteRelationship(this.connection, repositoryId, relationshipId);
+  }
+  /**
+   * Bulk drop by ids — single round-trip. Returns the ids actually deleted;
+   * missing ids land in `notFound`.
+   */
+  async deleteRelationships(repositoryId, ids) {
+    return deleteRelationships(this.connection, repositoryId, ids);
+  }
+  /**
+   * Drop every relationship of a type in the repository. Returns an exact
+   * delete count in a single round-trip.
+   */
+  async deleteRelationshipsByType(repositoryId, relationshipType) {
+    return deleteRelationshipsByType(
+      this.connection,
+      repositoryId,
+      relationshipType
+    );
+  }
+  // ─── Graph Traversal ───────────────────────────────────────────────
+  /**
+   * Capabilities surface used by the dispatcher to decide whether a given
+   * `TraversalSpec` shape is supported natively. Strict improvement over the
+   * Cosmos provider in two cells: `supportsAggregation` is `true` (Cypher's
+   * native aggregation makes `count` / per-key projection a one-statement
+   * shape) and the runtime supports every other traversal lever.
+   */
+  getCapabilities() {
+    return {
+      supportsNativeQuery: true,
+      nativeQueryLanguage: "cypher",
+      maxTraversalDepth: 10,
+      supportsRelationshipPropertyFilters: true,
+      supportsEntityPropertyFilters: true,
+      supportsAggregation: true,
+      supportsRepeat: true,
+      supportsDedup: true,
+      supportsRelationshipSummary: false
+    };
+  }
+  /**
+   * Execute a `TraversalSpec` against this repository's subgraph. The
+   * provider owns Cypher compilation; the spec stays language-agnostic.
+   * `track('traverse')` opens the per-operation usage scope so every
+   * `executeQuery` round-trip the executor performs aggregates into a single
+   * `OperationUsage` record.
+   */
+  async traverse(repositoryId, spec) {
+    return this.traverseInternal(repositoryId, spec);
+  }
+  /**
+   * Internal compile → submit → project pipeline. Shared by the public
+   * `traverse` method and by the compiler-model rewrites of
+   * `exploreNeighborhood` / `findPaths`, which both consume the raw stored
+   * shape to rebuild their storage-level outputs.
+   */
+  async traverseInternal(repositoryId, spec) {
+    const raw = await this.executeRawTraversal(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 aggregations = raw.aggregations;
+    const projectionEmitted = aggregations !== void 0;
+    if (projectionEmitted) {
+    } else if (spec.returnMode === "terminal") {
+      entities = raw.terminalEntities.map(projectStoredEntity);
+      relationships = void 0;
+    } else if (spec.returnMode === "all") {
+      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 ProviderError7(
+              "Unpacking Cypher path: entity referenced by path is missing from the result.",
+              "Inspect compiledQuery \u2014 this indicates a path emission shape mismatch."
+            );
+          }
+          return projectStoredEntity(stored);
+        }),
+        relationships: row.relationshipIds.map((id, i) => {
+          const stored = raw.relationshipMap.get(id);
+          if (!stored) {
+            throw new ProviderError7(
+              "Unpacking Cypher path: relationship referenced by path is missing from the result.",
+              "Inspect compiledQuery \u2014 this indicates a path emission shape mismatch."
+            );
+          }
+          return projectStoredRelationship(stored, row.relationshipDirections[i] ?? "out");
+        })
+      }));
+      relationships = Array.from(raw.relationshipMap.values()).map(
+        (rel) => projectStoredRelationship(rel, raw.pathRelFirstDirection.get(rel.id) ?? "out")
+      );
+    }
+    const limit = spec.limit ?? 50;
+    let total;
+    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 truncated = total >= limit;
+    const queryMetadata = {
+      executionTimeMs: raw.executionTimeMs,
+      resourceCost: { units: "server_ms", value: raw.serverMs },
+      compiledQuery: raw.compiledQuery,
+      compiledQueryLanguage: "cypher",
+      appliedLimits: {
+        maxResults: limit,
+        ...spec.steps !== void 0 ? { maxDepth: spec.steps.length } : {}
+      },
+      truncated,
+      ...truncated ? { truncationReason: "result_limit" } : {}
+    };
+    return {
+      entities,
+      ...relationships !== void 0 ? { relationships } : {},
+      ...paths !== void 0 ? { paths } : {},
+      ...aggregations !== void 0 ? { aggregations } : {},
+      total,
+      returned: total,
+      hasMore: truncated,
+      queryMetadata
+    };
+  }
+  /**
+   * Lower-level compile + submit + parse helper. Fetches the cached
+   * vocabulary once (D16) and hands it to the executor; the executor handles
+   * the repositoryId-scope rewrite, optional PROFILE prefix, and Path-object
+   * parsing.
+   */
+  async executeRawTraversal(repositoryId, spec) {
+    const vocabulary = await this.getVocabularyCached(repositoryId);
+    return this.traversalExecutor.execute(repositoryId, spec, vocabulary);
+  }
+  /**
+   * BFS-like neighbourhood exploration. For each depth `d` from 1 to
+   * `options.depth`, compile a cumulative `'all'`-mode spec with `d` discrete
+   * `'both'`-direction steps, run it through the executor, and walk one BFS
+   * layer client-side from the previous frontier using the returned edges.
+   *
+   * Round-trips per call: `options.depth`. Server-side step direction is
+   * fixed to `'both'` (catches every edge in either direction); the
+   * directional + bidirectional filter and entity-type filter run client-side
+   * during layer reconstruction — both to preserve the observable contract
+   * shared with the Cosmos provider and because the compiler's prefix walk at
+   * each depth is intentionally unfiltered so deeper layers stay reachable
+   * through any intermediate.
+   */
+  async exploreNeighborhood(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",
+        // The cumulative-d query fetches every node and edge reachable in ≤d
+        // hops in either direction. Size the limit generously so a single
+        // round-trip can hold the layer's full graph regardless of fan-out.
+        limit: 1e4,
+        detailLevel: "full",
+        includeProvenance: true
+      };
+      const raw = await this.executeRawTraversal(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 layerBucketSeen = /* @__PURE__ */ new Map();
+      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 (!matchesPropertyFilters2(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 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: [] };
+          }
+          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 };
+  }
+  /**
+   * Path finding between two entities. Single round-trip via a variable-length
+   * `MATCH p = (s)-[*1..N]-(t)` pattern; the compiler's path-binding emission
+   * lets the executor recover ordered nodes and relationships via `nodes(p)`
+   * / `relationships(p)`. The default `DIFFERENT RELATIONSHIPS` match mode in
+   * Cypher 25 prevents edge reuse within a single path — no explicit dedup
+   * filter is needed.
+   *
+   * The traversal walks the graph topologically regardless of relationship
+   * directionality (a path is defined by reachability, not semantic
+   * direction); entity-type and relationship-property filters apply during
+   * compilation, target filtering happens post-fetch.
+   */
+  async findPaths(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",
+      // Pull a generous candidate pool so the post-fetch filter (paths ending
+      // at targetId) has enough rows to paginate from. The variable-length
+      // pattern returns every walk of length ≤ maxDepth in one round-trip.
+      limit: Math.max(options.limit + options.offset, options.limit) * 10,
+      detailLevel: "full",
+      includeProvenance: true
+    };
+    const raw = await this.executeRawTraversal(repositoryId, spec);
+    const matchingPaths = [];
+    for (const row of raw.pathRows) {
+      const last = row.entityIds[row.entityIds.length - 1];
+      if (last !== targetId) continue;
+      if (new Set(row.entityIds).size !== row.entityIds.length) 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 ──────────────────────────────────────────────────────
+  /**
+   * Reconstruct the timeline event stream for an entity. One server
+   * round-trip: the centre entity's provenance scalars plus every incident
+   * edge's id + createdAt arrive in a single tuple via `OPTIONAL MATCH +
+   * collect()`. The provider walks the row client-side to emit
+   * `entity:created` / `entity:updated` / `relationship:created` events.
+   *
+   * Cosmos pays two round-trips for the same information because Gremlin
+   * cannot bind an aggregated edge list to a vertex projection in one shot —
+   * a platform divergence, not an inherent trade-off.
+   */
+  async getTimeline(repositoryId, entityId, options) {
+    return getTimeline(this.connection, repositoryId, entityId, options);
+  }
+  // ─── Bulk Operations ───────────────────────────────────────────────
+  /**
+   * Stream every entity and every relationship in the repository as
+   * cursor-paginated chunks. Entities come first, then relationships; each
+   * chunk carries a monotonic `sequence` and an `isLast` flag.
+   *
+   * The Proxy-based tracking flow does not apply here. Tracked methods emit
+   * one sink record at promise resolution; an `AsyncIterable` returns
+   * synchronously, before any chunk has streamed. Instead, `trackIterable`
+   * wraps the underlying generator in its own `UsageScope` that opens at
+   * iterator creation, records each round-trip as the consumer pulls the
+   * next chunk, and emits one sink record when the iterator drains — so the
+   * resulting record aggregates server time across every chunk fetch.
+   */
+  exportAll(repositoryId) {
+    return this.trackIterable(
+      "exportAll",
+      repositoryId,
+      exportAll(this.connection, repositoryId)
+    );
+  }
+  /**
+   * Run a bulk import: every entity then every relationship from the input
+   * chunks lands in the repository. `skipExistenceCheck: true` uses CREATE
+   * for the absolute peak throughput; `false` (default) uses MERGE for
+   * idempotent re-imports.
+   *
+   * Returns a single aggregate `BulkImportResult` spanning every chunk.
+   * Per-row failures land in `result.errors`; surviving rows still count
+   * toward `entitiesImported` / `relationshipsImported`.
+   */
+  async importBulk(repositoryId, data, options) {
+    return importBulk(this.connection, repositoryId, data, options);
+  }
+  /**
+   * Wrap an `AsyncIterable` so every chunk it produces is generated inside a
+   * single shared `UsageScope`. The scope aggregates `summary.resultConsumedAfter`
+   * across every round-trip the iterator performs; one sink record fires when
+   * the iterator drains (or is closed / thrown into).
+   *
+   * Implementation mirrors the Cosmos `trackIterable` precedent: each
+   * `iter.next()` call re-enters the scope via `runInUsageScope`. The
+   * `AsyncLocalStorage` chain links async work performed inside the
+   * generator body to the scope for the duration of that step. Between
+   * `next()` calls the scope is dormant — the consumer's awaits do not
+   * accumulate into it, which is exactly the desired semantics.
+   *
+   * When the sink is absent the wrap degenerates to a pass-through; the
+   * Proxy's `createSafeSink` short-circuit covers the no-sink case at
+   * construction time, so this method is only reached when `reportUsage` is
+   * present.
+   */
+  trackIterable(operation, repositoryId, source) {
+    const sink = this.reportUsage;
+    if (sink === void 0) return source;
+    return {
+      [Symbol.asyncIterator]: () => {
+        const iter = source[Symbol.asyncIterator]();
+        const scope = createUsageScope();
+        let emitted = false;
+        const emit = () => {
+          if (emitted) return;
+          emitted = true;
+          sink({
+            provider: PROVIDER_NAME,
+            operation,
+            unit: "server_ms",
+            value: scope.serverMs,
+            repositoryId,
+            timestamp: /* @__PURE__ */ new Date(),
+            details: buildUsageDetails(scope)
+          });
+        };
+        return {
+          async next() {
+            const step = await runInUsageScope(scope, () => iter.next());
+            if (step.done) emit();
+            return step;
+          },
+          async return(value) {
+            emit();
+            if (iter.return) return iter.return(value);
+            return { done: true, value };
+          },
+          async throw(err) {
+            emit();
+            if (iter.throw) return iter.throw(err);
+            throw err;
+          }
+        };
+      }
+    };
+  }
+  // ─── Stats ─────────────────────────────────────────────────────────
+  /**
+   * Aggregate repository statistics — entity / relationship totals, per-type
+   * breakdowns, vocabulary version. Two parallel native-aggregation round-
+   * trips (`count(n)` per `entityType`, `count(r)` per `type(r)`); the
+   * vocabulary version comes from the cached `_Vocabulary` node so a warm
+   * cache costs exactly two round-trips total.
+   *
+   * Strict improvement over Cosmos's Gremlin `.group().by().by(count())`
+   * shape — Cypher's native aggregation collapses each metric to a one-
+   * statement plan that hits the `(repositoryId, entityType)` and
+   * relationship-property indexes directly.
+   */
+  async getRepositoryStats(repositoryId) {
+    const vocabulary = await this.getVocabularyCached(repositoryId);
+    return getRepositoryStats(this.connection, repositoryId, vocabulary);
+  }
+  // ─── Native Query ──────────────────────────────────────────────────
+  /**
+   * Execute a raw Cypher statement with caller-supplied bindings.
+   *
+   * ⚠️  ELEVATED PRIVILEGE — SYSTEM-LEVEL OPERATION ⚠️
+   *
+   * This method is an unscoped pass-through: it does not filter by
+   * repository, does not inject the `$rid` binding, and performs no
+   * validation on the Cypher string. A single call can read or mutate any
+   * node or relationship in the database regardless of which repository it
+   * belongs to.
+   *
+   * DO NOT expose this method to AI agents, end users, or any untrusted
+   * caller. It is intended for:
+   *   - administrative tooling (migrations, diagnostics, repairs)
+   *   - internal library operations that need cross-repository reach
+   *
+   * `repositoryId` is accepted for interface symmetry but is intentionally
+   * ignored here — the caller is trusted to scope the query themselves.
+   * Because the call is cross-repository by design, the emitted usage
+   * record carries no `repositoryId` (see `TRACKED_METHODS`).
+   *
+   * For agent-facing graph queries use {@link traverse}, which enforces the
+   * repositoryId scope predicate.
+   */
+  async executeNativeQuery(_repositoryId, query, params) {
+    const result = await this.connection.executeSystemQuery(query, params ?? {}, {
+      crossRepository: true
+    });
+    return result.records.map((record) => record.toObject());
+  }
+};
+function buildExploreSteps(depth, options) {
+  const base = { direction: "both" };
+  if (options.relationshipTypes && options.relationshipTypes.length > 0) {
+    base.relationshipTypes = options.relationshipTypes;
+  }
+  const steps = [];
+  for (let i = 0; i < depth; i++) {
+    steps.push({ ...base });
+  }
+  return steps;
+}
+export {
+  Neo4jStorageProvider,
+  SCHEMA_VERSION,
+  getSchemaCypher
+};
+//# sourceMappingURL=index.js.map