gcyphrq 0.12.6

package/dist/lib.js

@@ -0,0 +1,1455 @@
+// src/engine/cypher-parser.ts
+import { createRequire } from "module";
+var _require = createRequire(import.meta.url);
+var antlr4 = _require("antlr4").default;
+var { CypherLexer, CypherParser } = _require("@neo4j-cypher/antlr4");
+var Ctx = {
+  Atom: "AtomContext",
+  AddOrSubtractExpression: "AddOrSubtractExpressionContext",
+  BooleanLiteral: "BooleanLiteralContext",
+  AnonymousPatternPart: "AnonymousPatternPartContext",
+  Clause: "ClauseContext",
+  ComparisonExpression: "ComparisonExpressionContext",
+  CreateClause: "CreateClauseContext",
+  CypherQuery: "CypherQueryContext",
+  DeleteClause: "DeleteClauseContext",
+  Expression: "ExpressionContext",
+  FloatLiteral: "FloatLiteralContext",
+  FunctionInvocation: "FunctionInvocationContext",
+  FunctionInvocationBody: "FunctionInvocationBodyContext",
+  FunctionName: "FunctionNameContext",
+  IntegerLiteral: "IntegerLiteralContext",
+  Keyword: "KeywordContext",
+  LabelName: "LabelNameContext",
+  LeftArrowHead: "LeftArrowHeadContext",
+  Literal: "LiteralContext",
+  LiteralEntry: "LiteralEntryContext",
+  MapLiteral: "MapLiteralContext",
+  MatchClause: "MatchClauseContext",
+  NodeLabel: "NodeLabelContext",
+  NodeLabels: "NodeLabelsContext",
+  NodePattern: "NodePatternContext",
+  NumberLiteral: "NumberLiteralContext",
+  PartialComparisonExpression: "PartialComparisonExpressionContext",
+  Pattern: "PatternContext",
+  PatternElement: "PatternElementContext",
+  PatternElementChain: "PatternElementChainContext",
+  PatternPart: "PatternPartContext",
+  Properties: "PropertiesContext",
+  PropertyExpression: "PropertyExpressionContext",
+  PropertyKey: "PropertyKeyNameContext",
+  PropertyLookup: "PropertyLookupContext",
+  RangeLiteral: "RangeLiteralContext",
+  RelTypeName: "RelTypeNameContext",
+  RelationshipDetail: "RelationshipDetailContext",
+  RelationshipPattern: "RelationshipPatternContext",
+  RelationshipPatternEnd: "RelationshipPatternEndContext",
+  RelationshipPatternStart: "RelationshipPatternStartContext",
+  RelationshipType: "RelationshipTypeContext",
+  RelationshipTypes: "RelationshipTypesContext",
+  RegularQuery: "RegularQueryContext",
+  Query: "QueryContext",
+  RightArrowHead: "RightArrowHeadContext",
+  Limit: "LimitContext",
+  Order: "OrderContext",
+  Skip: "SkipContext",
+  ReturnBody: "ReturnBodyContext",
+  ReturnClause: "ReturnClauseContext",
+  ReturnItem: "ReturnItemContext",
+  ReturnItems: "ReturnItemsContext",
+  SortItem: "SortItemContext",
+  SetClause: "SetClauseContext",
+  SetItem: "SetItemContext",
+  SingleQuery: "SingleQueryContext",
+  Statement: "StatementContext",
+  StringLiteral: "StringLiteralContext",
+  SymbolicName: "SymbolicNameContext",
+  TerminalNode: "TerminalNodeImpl",
+  Variable: "VariableContext",
+  Where: "WhereContext",
+  WithClause: "WithClauseContext"
+};
+function validateContextNames() {
+  const richQuery = 'MATCH (a:User {name: "Alice"})-[r:FRIEND*1..2]->(b:User) WITH a.name AS name, count(b) AS cnt WHERE cnt > 0 RETURN name, cnt';
+  const chars = antlr4.CharStreams.fromString(richQuery);
+  const lexer = new CypherLexer(chars);
+  const tokens = new antlr4.CommonTokenStream(lexer);
+  const parser = new CypherParser(tokens);
+  const tree = parser.cypher();
+  const allNames = /* @__PURE__ */ new Set();
+  const collect = (ctx) => {
+    allNames.add(ctx.constructor.name);
+    if (ctx.children) {
+      for (const child of ctx.children) collect(child);
+    }
+  };
+  collect(tree);
+  const required = [
+    Ctx.CypherQuery,
+    Ctx.Statement,
+    Ctx.Query,
+    Ctx.RegularQuery,
+    Ctx.SingleQuery,
+    Ctx.Clause,
+    Ctx.MatchClause,
+    Ctx.ReturnClause,
+    Ctx.ReturnBody,
+    Ctx.ReturnItems,
+    Ctx.ReturnItem,
+    Ctx.Expression,
+    Ctx.Atom,
+    Ctx.Variable,
+    Ctx.SymbolicName,
+    Ctx.Pattern,
+    Ctx.PatternPart,
+    Ctx.AnonymousPatternPart,
+    Ctx.PatternElement,
+    Ctx.NodePattern,
+    Ctx.TerminalNode
+  ];
+  const missing = required.filter((name) => !allNames.has(name));
+  if (missing.length > 0) {
+    throw new Error(
+      `ANTLR4 context name mismatch. Core contexts missing: ${missing.join(", ")}. Available: ${[...allNames].join(", ")}`
+    );
+  }
+}
+var contextNamesValidated = false;
+function ensureContextNamesValid() {
+  if (contextNamesValidated) return;
+  if (process.env.NODE_ENV === "test") return;
+  validateContextNames();
+  contextNamesValidated = true;
+}
+if (process.env.NODE_ENV === "development") {
+  validateContextNames();
+}
+var ErrorCollector = class {
+  errors = [];
+  syntaxError(_recognizer, _offendingSymbol, line, column, message, _e) {
+    this.errors.push(`line ${line}:${column} ${message}`);
+  }
+  // no-op — we only care about syntax errors
+  reportAmbiguity() {
+  }
+  reportAttemptingFullContext() {
+  }
+  reportContextSensitivity() {
+  }
+};
+function findPropertyLookup(exprCtx) {
+  if (!exprCtx) return null;
+  const walk = (ctx) => {
+    if (!ctx.children) return null;
+    for (const child of ctx.children) {
+      if (child.constructor.name === Ctx.PropertyLookup) return child;
+      const found = walk(child);
+      if (found) return found;
+    }
+    return null;
+  };
+  return walk(exprCtx);
+}
+function findChild(ctx, name) {
+  if (!ctx?.children) return null;
+  return ctx.children.find((c) => c.constructor.name === name) ?? null;
+}
+function findAllChildren(ctx, name) {
+  if (!ctx?.children) return [];
+  return ctx.children.filter((c) => c.constructor.name === name);
+}
+function hasTerminal(ctx, text) {
+  if (!ctx?.children) return false;
+  return ctx.children.some((c) => c.symbol?.text === text);
+}
+function getTerminalText(ctx) {
+  if (!ctx) return void 0;
+  const term = findChild(ctx, Ctx.TerminalNode);
+  return term?.symbol?.text;
+}
+function getSymbolicName(ctx) {
+  if (!ctx) return void 0;
+  const sym = findChild(ctx, Ctx.SymbolicName);
+  if (!sym) return getTerminalText(ctx);
+  const term = findChild(sym, Ctx.TerminalNode);
+  if (term) return term.symbol?.text;
+  const keyword = findChild(sym, Ctx.Keyword);
+  if (keyword) {
+    const keywordTerm = findChild(keyword, Ctx.TerminalNode);
+    return keywordTerm?.symbol?.text;
+  }
+  return sym.getText();
+}
+function getAtom(exprCtx) {
+  if (!exprCtx) return null;
+  const walk = (ctx) => {
+    if (ctx.constructor.name === Ctx.Atom) return ctx;
+    if (!ctx.children) return null;
+    for (const child of ctx.children) {
+      const found = walk(child);
+      if (found) return found;
+    }
+    return null;
+  };
+  return walk(exprCtx);
+}
+function evaluateExpression(exprCtx) {
+  if (!exprCtx) return void 0;
+  const atom = getAtom(exprCtx);
+  if (!atom) return void 0;
+  const funcCtx = findChild(atom, Ctx.FunctionInvocation);
+  if (funcCtx) {
+    const bodyCtx = findChild(funcCtx, Ctx.FunctionInvocationBody);
+    const funcNameCtx = findChild(bodyCtx, Ctx.FunctionName);
+    const funcName = getTerminalText(funcNameCtx);
+    const argExpr = findChild(funcCtx, Ctx.Expression);
+    const argAtom = getAtom(argExpr ?? void 0);
+    const argVar = argAtom ? findChild(argAtom, Ctx.Variable) : null;
+    const argName = getSymbolicName(argVar);
+    let argProperty;
+    if (argAtom) {
+      const propLookup = findChild(argAtom, Ctx.PropertyLookup);
+      if (!propLookup) {
+        const parentPropLookup = findPropertyLookup(argExpr);
+        if (parentPropLookup) {
+          const pkCtx = findChild(parentPropLookup, Ctx.PropertyKey);
+          argProperty = getSymbolicName(pkCtx);
+        }
+      } else {
+        const pkCtx = findChild(propLookup, Ctx.PropertyKey);
+        argProperty = getSymbolicName(pkCtx);
+      }
+    }
+    if (funcName && argName) {
+      return {
+        type: "Aggregation",
+        aggregationType: funcName.toUpperCase(),
+        variable: argName,
+        property: argProperty
+      };
+    }
+  }
+  const varCtx = findChild(atom, Ctx.Variable);
+  if (varCtx) {
+    const name = getSymbolicName(varCtx);
+    if (name) {
+      const propLookup = findPropertyLookup(exprCtx);
+      if (propLookup) {
+        const propName = getSymbolicName(findChild(propLookup, Ctx.PropertyKey));
+        if (propName) {
+          return { type: "PropertyAccess", variable: name, property: propName };
+        }
+      }
+      return { type: "PropertyAccess", variable: name, property: void 0 };
+    }
+  }
+  const literalCtx = findChild(atom, Ctx.Literal);
+  const literal = extractLiteral(literalCtx);
+  if (literal) return literal;
+  return void 0;
+}
+function unescapeStringLiteral(raw) {
+  if (raw.startsWith('"') && raw.endsWith('"')) {
+    raw = raw.slice(1, -1);
+  }
+  return raw.replace(/\\(.)/g, (match, char, offset) => {
+    switch (char) {
+      case '"':
+        return '"';
+      case "\\":
+        return "\\";
+      case "n":
+        return "\n";
+      case "t":
+        return "	";
+      case "r":
+        return "\r";
+      case "b":
+        return "\b";
+      case "f":
+        return "\f";
+      case "/":
+        return "/";
+      case "u": {
+        const hex = raw.slice(offset + 2, offset + 6);
+        return hex.length === 4 ? String.fromCharCode(parseInt(hex, 16)) : `\\u${hex}`;
+      }
+      default:
+        return `\\${char}`;
+    }
+  });
+}
+function extractLiteral(literalCtx) {
+  if (!literalCtx) return void 0;
+  const stringLit = findChild(literalCtx, Ctx.StringLiteral);
+  if (stringLit) {
+    const raw = getTerminalText(stringLit);
+    if (raw) return { type: "Literal", value: unescapeStringLiteral(raw) };
+  }
+  const numLit = findChild(literalCtx, Ctx.NumberLiteral);
+  if (numLit) {
+    const intLit = findChild(numLit, Ctx.IntegerLiteral);
+    if (intLit) {
+      const text = getTerminalText(intLit);
+      if (text) return { type: "Literal", value: parseInt(text, 10) };
+    }
+    const floatLit = findChild(numLit, Ctx.FloatLiteral);
+    if (floatLit) {
+      const text = getTerminalText(floatLit);
+      if (text) return { type: "Literal", value: parseFloat(text) };
+    }
+  }
+  const boolLit = findChild(literalCtx, Ctx.BooleanLiteral);
+  if (boolLit) {
+    const text = getTerminalText(boolLit);
+    if (text === "true") return { type: "Literal", value: true };
+    if (text === "false") return { type: "Literal", value: false };
+  }
+  if (hasTerminal(literalCtx, "null") || hasTerminal(literalCtx, "NULL")) {
+    return { type: "Literal", value: null };
+  }
+  return void 0;
+}
+function extractNodePattern(nodePatternCtx) {
+  if (!nodePatternCtx) return { variable: "", label: void 0, properties: void 0 };
+  const variable = getSymbolicName(findChild(nodePatternCtx, Ctx.Variable)) ?? "";
+  const labelsCtx = findChild(nodePatternCtx, Ctx.NodeLabels);
+  const labelCtx = findChild(labelsCtx, Ctx.NodeLabel);
+  const labelNameCtx = findChild(labelCtx, Ctx.LabelName);
+  const label = getSymbolicName(labelNameCtx);
+  const propsCtx = findChild(nodePatternCtx, Ctx.Properties);
+  const mapLitCtx = findChild(propsCtx, Ctx.MapLiteral);
+  const properties = extractProperties(mapLitCtx);
+  return { variable, label, properties };
+}
+function extractProperties(mapLiteralCtx) {
+  if (!mapLiteralCtx) return void 0;
+  const entries = findAllChildren(mapLiteralCtx, Ctx.LiteralEntry);
+  if (entries.length === 0) return void 0;
+  const props = {};
+  for (const entry of entries) {
+    const keyCtx = findChild(entry, Ctx.PropertyKey);
+    const key = getSymbolicName(keyCtx);
+    const exprCtx = findChild(entry, Ctx.Expression);
+    const value = evaluateExpression(exprCtx);
+    if (key && value && value.type === "Literal") {
+      props[key] = value.value;
+    }
+  }
+  return Object.keys(props).length > 0 ? props : void 0;
+}
+function extractRelationPattern(relPatternCtx) {
+  if (!relPatternCtx) return { variable: void 0, type: void 0, minDepth: void 0, maxDepth: void 0, direction: "UNDIRECTED" };
+  const direction = extractDirection(relPatternCtx);
+  const detailCtx = findChild(relPatternCtx, Ctx.RelationshipDetail);
+  const variable = detailCtx ? getSymbolicName(findChild(detailCtx, Ctx.Variable)) : void 0;
+  const typesCtx = findChild(detailCtx, Ctx.RelationshipTypes);
+  const typeCtx = findChild(typesCtx, Ctx.RelationshipType);
+  const typeNameCtx = findChild(typeCtx, Ctx.RelTypeName);
+  const type = getSymbolicName(typeNameCtx);
+  const rangeCtx = findChild(detailCtx, Ctx.RangeLiteral);
+  if (rangeCtx) {
+    const intLits = findAllChildren(rangeCtx, Ctx.IntegerLiteral);
+    const values = intLits.map((ic) => {
+      const text = getTerminalText(ic);
+      return text ? parseInt(text, 10) : 0;
+    });
+    if (values.length >= 1) {
+      return {
+        variable,
+        type,
+        minDepth: values[0],
+        maxDepth: values.length >= 2 ? values[1] : values[0],
+        direction
+      };
+    }
+  }
+  return { variable, type, minDepth: void 0, maxDepth: void 0, direction };
+}
+function extractDirection(relPatternCtx) {
+  if (!relPatternCtx) return "UNDIRECTED";
+  const startCtx = findChild(relPatternCtx, Ctx.RelationshipPatternStart);
+  const endCtx = findChild(relPatternCtx, Ctx.RelationshipPatternEnd);
+  const hasStartArrow = !!findChild(startCtx, Ctx.LeftArrowHead);
+  const hasEndArrow = !!findChild(endCtx, Ctx.RightArrowHead);
+  if (hasStartArrow && hasEndArrow) return "UNDIRECTED";
+  if (hasStartArrow) return "IN";
+  if (hasEndArrow) return "OUT";
+  return "UNDIRECTED";
+}
+function extractMatchClause(clauseCtx) {
+  const matchCtx = findChild(clauseCtx, Ctx.MatchClause);
+  const optional = hasTerminal(clauseCtx, "OPTIONAL") || matchCtx && hasTerminal(matchCtx, "OPTIONAL");
+  const patternCtx = findChild(matchCtx, Ctx.Pattern);
+  if (!patternCtx) throw new Error("Failed to parse MATCH: missing Pattern node.");
+  const patternPart = findChild(patternCtx, Ctx.PatternPart);
+  if (!patternPart) throw new Error("Failed to parse MATCH: missing PatternPart node.");
+  const anonPart = findChild(patternPart, Ctx.AnonymousPatternPart);
+  if (!anonPart) throw new Error("Failed to parse MATCH: missing AnonymousPatternPart node.");
+  const element = findChild(anonPart, Ctx.PatternElement);
+  if (!element) throw new Error("Failed to parse MATCH: missing PatternElement node.");
+  const nodePatterns = findAllChildren(element, Ctx.NodePattern);
+  const chains = findAllChildren(element, Ctx.PatternElementChain);
+  const sourcePattern = nodePatterns[0] ? extractNodePattern(nodePatterns[0]) : { variable: "", label: void 0, properties: void 0 };
+  let relationPattern = { variable: void 0, type: void 0, minDepth: void 0, maxDepth: void 0, direction: "UNDIRECTED" };
+  let targetPattern = { variable: "", label: void 0, properties: void 0 };
+  const hasChains = chains.length > 0;
+  if (chains.length > 1) {
+    throw new Error("Multi-hop patterns (more than one relationship chain) are not supported. Use multiple MATCH stages or a WITH clause.");
+  }
+  if (hasChains) {
+    const chain = chains[0];
+    const relPatternCtx = findChild(chain, Ctx.RelationshipPattern);
+    relationPattern = extractRelationPattern(relPatternCtx);
+    const targetNodeCtx = findChild(chain, Ctx.NodePattern);
+    if (targetNodeCtx) {
+      targetPattern = extractNodePattern(targetNodeCtx);
+    }
+  } else if (nodePatterns.length > 1) {
+    targetPattern = extractNodePattern(nodePatterns[1]);
+  }
+  return { optional: !!optional, hasChains, sourcePattern, relationPattern, targetPattern };
+}
+function computeDefaultAlias(expr) {
+  if (expr.type === "PropertyAccess") {
+    return expr.property ?? expr.variable;
+  }
+  if (expr.type === "Aggregation") {
+    return `${expr.aggregationType}(${expr.variable})`;
+  }
+  return String(expr.value);
+}
+function extractReturnBody(returnBody) {
+  if (!returnBody) return [];
+  const returnItems = findChild(returnBody, Ctx.ReturnItems);
+  if (!returnItems) return [];
+  const items = findAllChildren(returnItems, Ctx.ReturnItem);
+  const parsedItems = [];
+  for (const item of items) {
+    const exprCtx = findChild(item, Ctx.Expression);
+    const expr = evaluateExpression(exprCtx);
+    if (!expr) continue;
+    const hasAs = hasTerminal(item, "AS");
+    let asAlias;
+    if (hasAs) {
+      const aliasVar = findChild(item, Ctx.Variable);
+      asAlias = getSymbolicName(aliasVar);
+    }
+    parsedItems.push({ expr, hasAs, asAlias });
+  }
+  const aliasCounts = /* @__PURE__ */ new Map();
+  for (const { expr, hasAs, asAlias } of parsedItems) {
+    if (hasAs) continue;
+    const alias = computeDefaultAlias(expr);
+    aliasCounts.set(alias, (aliasCounts.get(alias) ?? 0) + 1);
+  }
+  const projections = [];
+  const usedAliases = /* @__PURE__ */ new Set();
+  for (const { expr, hasAs, asAlias } of parsedItems) {
+    if (hasAs) {
+      if (asAlias) {
+        projections.push({ expression: expr, alias: asAlias });
+        usedAliases.add(asAlias);
+      }
+      continue;
+    }
+    let alias = computeDefaultAlias(expr);
+    if ((aliasCounts.get(alias) ?? 0) > 1 && expr.type === "PropertyAccess" && expr.property) {
+      alias = `${expr.variable}.${expr.property}`;
+    }
+    if (usedAliases.has(alias)) {
+      let idx = 1;
+      alias = `${alias}_${idx}`;
+      while (usedAliases.has(alias)) {
+        idx++;
+        alias = `${alias.slice(0, -String(idx).length - 1)}_${idx}`;
+      }
+    }
+    usedAliases.add(alias);
+    projections.push({ expression: expr, alias });
+  }
+  return projections;
+}
+function extractOrderBy(returnBody) {
+  const orderCtx = findChild(returnBody, Ctx.Order);
+  if (!orderCtx) return void 0;
+  const sortItems = findAllChildren(orderCtx, Ctx.SortItem);
+  if (sortItems.length === 0) return void 0;
+  const items = [];
+  for (const sortItem of sortItems) {
+    const exprCtx = findChild(sortItem, Ctx.Expression);
+    const expr = evaluateExpression(exprCtx);
+    if (!expr) continue;
+    const hasDesc = hasTerminal(sortItem, "DESC");
+    const direction = hasDesc ? "DESC" : "ASC";
+    items.push({ expression: expr, direction });
+  }
+  return items.length > 0 ? items : void 0;
+}
+function extractLimit(returnBody) {
+  const limitCtx = findChild(returnBody, Ctx.Limit);
+  if (!limitCtx) return void 0;
+  const exprCtx = findChild(limitCtx, Ctx.Expression);
+  const expr = evaluateExpression(exprCtx);
+  if (expr && expr.type === "Literal" && typeof expr.value === "number") {
+    return expr.value;
+  }
+  return void 0;
+}
+function extractSkip(returnBody) {
+  const skipCtx = findChild(returnBody, Ctx.Skip);
+  if (!skipCtx) return void 0;
+  const exprCtx = findChild(skipCtx, Ctx.Expression);
+  const expr = evaluateExpression(exprCtx);
+  if (expr && expr.type === "Literal" && typeof expr.value === "number") {
+    return expr.value;
+  }
+  return void 0;
+}
+function extractReturnClause(clauseCtx) {
+  const returnCtx = findChild(clauseCtx, Ctx.ReturnClause);
+  if (!returnCtx) return void 0;
+  const returnBody = findChild(returnCtx, Ctx.ReturnBody);
+  const projections = extractReturnBody(returnBody);
+  const orderBy = extractOrderBy(returnBody);
+  const skip = extractSkip(returnBody);
+  const limit = extractLimit(returnBody);
+  return { projections, orderBy, skip, limit };
+}
+function extractWithClause(clauseCtx) {
+  const withCtx = findChild(clauseCtx, Ctx.WithClause);
+  if (!withCtx) return void 0;
+  const returnBody = findChild(withCtx, Ctx.ReturnBody);
+  const projections = extractReturnBody(returnBody);
+  const orderBy = extractOrderBy(returnBody);
+  const skip = extractSkip(returnBody);
+  const limit = extractLimit(returnBody);
+  const whereCtx = findChild(withCtx, Ctx.Where);
+  const whereExpr = findChild(whereCtx, Ctx.Expression);
+  const where = whereExpr ? extractComparison(whereExpr) : void 0;
+  return { projections, where, orderBy, skip, limit };
+}
+function extractComparison(exprCtx) {
+  if (!exprCtx) return void 0;
+  let foundPartial;
+  let foundComp;
+  const walk = (ctx) => {
+    if (ctx.constructor.name === Ctx.PartialComparisonExpression) {
+      foundPartial = ctx;
+    } else if (ctx.constructor.name === Ctx.ComparisonExpression) {
+      foundComp = ctx;
+    }
+    if (ctx.children) {
+      for (const child of ctx.children) {
+        walk(child);
+      }
+    }
+  };
+  walk(exprCtx);
+  if (!foundPartial || !foundComp) return void 0;
+  const operatorTerm = findChild(foundPartial, Ctx.TerminalNode);
+  const operator = operatorTerm?.symbol?.text;
+  if (!operator) return void 0;
+  const leftExprCtx = findChild(foundComp, Ctx.AddOrSubtractExpression);
+  const left = extractValueExpression(leftExprCtx);
+  const rightExprCtx = findChild(foundPartial, Ctx.AddOrSubtractExpression);
+  const right = extractValueExpression(rightExprCtx);
+  if (left && right) {
+    return { type: "BinaryExpression", operator, left, right };
+  }
+  return void 0;
+}
+function extractValueExpression(ctx) {
+  if (!ctx) return void 0;
+  const atom = getAtom(ctx);
+  if (!atom) return void 0;
+  const varCtx = findChild(atom, Ctx.Variable);
+  if (varCtx) {
+    const name = getSymbolicName(varCtx);
+    if (name) {
+      const propLookup = findPropertyLookup(ctx);
+      if (propLookup) {
+        const propName = getSymbolicName(findChild(propLookup, Ctx.PropertyKey));
+        if (propName) {
+          return { type: "PropertyAccess", variable: name, property: propName };
+        }
+      }
+      return { type: "PropertyAccess", variable: name, property: void 0 };
+    }
+  }
+  const literalCtx = findChild(atom, Ctx.Literal);
+  return extractLiteral(literalCtx);
+}
+function extractWriteClause(clauseCtx) {
+  const setCtx = findChild(clauseCtx, Ctx.SetClause);
+  if (setCtx) {
+    const setItem = findChild(setCtx, Ctx.SetItem);
+    if (!setItem) throw new Error("Failed to parse SET: missing SetItem node in AST.");
+    const propExpr = findChild(setItem, Ctx.PropertyExpression);
+    if (!propExpr) throw new Error("Failed to parse SET: missing PropertyExpression node in AST.");
+    const atom = findChild(propExpr, Ctx.Atom);
+    if (!atom) throw new Error("Failed to parse SET: missing Atom node in AST.");
+    const varCtx = findChild(atom, Ctx.Variable);
+    const variable = getSymbolicName(varCtx);
+    if (!variable) throw new Error("Failed to parse SET: missing variable name.");
+    const propLookup = findChild(propExpr, Ctx.PropertyLookup);
+    if (!propLookup) throw new Error("Failed to parse SET: missing PropertyLookup node in AST.");
+    const propKeyCtx = findChild(propLookup, Ctx.PropertyKey);
+    const property = getSymbolicName(propKeyCtx);
+    if (!property) throw new Error("Failed to parse SET: missing property name.");
+    const exprCtx = findChild(setItem, Ctx.Expression);
+    const valueExpr = evaluateExpression(exprCtx);
+    if (!valueExpr) {
+      throw new Error(`Failed to parse SET: could not extract value for "${variable}.${property}".`);
+    }
+    if (valueExpr.type !== "Literal") {
+      throw new Error(`Failed to parse SET: only literal values are supported on the right-hand side, got ${valueExpr.type}.`);
+    }
+    return { type: "SET", variable, property, value: valueExpr.value };
+  }
+  const createCtx = findChild(clauseCtx, Ctx.CreateClause);
+  if (createCtx) {
+    const patternCtx = findChild(createCtx, Ctx.Pattern);
+    if (!patternCtx) throw new Error("Failed to parse CREATE: missing Pattern node in AST.");
+    const patternPart = findChild(patternCtx, Ctx.PatternPart);
+    if (!patternPart) throw new Error("Failed to parse CREATE: missing PatternPart node in AST.");
+    const anonPart = findChild(patternPart, Ctx.AnonymousPatternPart);
+    if (!anonPart) throw new Error("Failed to parse CREATE: missing AnonymousPatternPart node in AST.");
+    const element = findChild(anonPart, Ctx.PatternElement);
+    if (!element) throw new Error("Failed to parse CREATE: missing PatternElement node in AST.");
+    const nodePatternCtx = findChild(element, Ctx.NodePattern);
+    if (!nodePatternCtx) throw new Error("Failed to parse CREATE: missing NodePattern node in AST.");
+    const variable = getSymbolicName(findChild(nodePatternCtx, Ctx.Variable)) ?? "";
+    const labelsCtx = findChild(nodePatternCtx, Ctx.NodeLabels);
+    const labelCtx = findChild(labelsCtx, Ctx.NodeLabel);
+    const labelNameCtx = findChild(labelCtx, Ctx.LabelName);
+    const label = getSymbolicName(labelNameCtx);
+    const propsCtx = findChild(nodePatternCtx, Ctx.Properties);
+    const mapLitCtx = findChild(propsCtx, Ctx.MapLiteral);
+    const properties = extractProperties(mapLitCtx);
+    return { type: "CREATE", variable, label, properties };
+  }
+  const deleteCtx = findChild(clauseCtx, Ctx.DeleteClause);
+  if (deleteCtx) {
+    const exprCtx = findChild(deleteCtx, Ctx.Expression);
+    if (!exprCtx) throw new Error("Failed to parse DELETE: missing Expression node in AST.");
+    const atom = getAtom(exprCtx);
+    if (!atom) throw new Error("Failed to parse DELETE: missing Atom node in AST.");
+    const varCtx = findChild(atom, Ctx.Variable);
+    const variable = getSymbolicName(varCtx);
+    if (!variable) throw new Error("Failed to parse DELETE: missing variable name.");
+    return { type: "DELETE", variable };
+  }
+  return void 0;
+}
+function parseCypher(query) {
+  ensureContextNamesValid();
+  const chars = antlr4.CharStreams.fromString(query);
+  const lexer = new CypherLexer(chars);
+  const tokens = new antlr4.CommonTokenStream(lexer);
+  const parser = new CypherParser(tokens);
+  const collector = new ErrorCollector();
+  parser.removeErrorListeners();
+  parser.addErrorListener(collector);
+  const tree = parser.cypher();
+  if (collector.errors.length > 0) {
+    throw new Error(`Failed to parse Cypher query: ${collector.errors.join("; ")}`);
+  }
+  const stages = [];
+  let returnClause;
+  const cypherPart = tree.children?.[0];
+  const cypherQuery = findChild(cypherPart, Ctx.CypherQuery);
+  const statement = findChild(cypherQuery, Ctx.Statement);
+  const queryCtx = findChild(statement, Ctx.Query);
+  const regularQuery = findChild(queryCtx, Ctx.RegularQuery);
+  const singleQuery = findChild(regularQuery, Ctx.SingleQuery);
+  if (!singleQuery) {
+    return { type: "Query", stages, return: returnClause };
+  }
+  const clauses = findAllChildren(singleQuery, Ctx.Clause);
+  for (const clause of clauses) {
+    if (findChild(clause, Ctx.MatchClause)) {
+      stages.push({ type: "MATCH", clause: extractMatchClause(clause) });
+    } else if (findChild(clause, Ctx.ReturnClause)) {
+      returnClause = extractReturnClause(clause);
+    } else if (findChild(clause, Ctx.WithClause)) {
+      const withClause = extractWithClause(clause);
+      if (withClause) stages.push({ type: "WITH", clause: withClause });
+    } else if (findChild(clause, Ctx.SetClause)) {
+      const writeClause = extractWriteClause(clause);
+      if (writeClause) stages.push({ type: "WRITE", clause: writeClause });
+    } else if (findChild(clause, Ctx.CreateClause)) {
+      const writeClause = extractWriteClause(clause);
+      if (writeClause) stages.push({ type: "WRITE", clause: writeClause });
+    } else if (findChild(clause, Ctx.DeleteClause)) {
+      const writeClause = extractWriteClause(clause);
+      if (writeClause) stages.push({ type: "WRITE", clause: writeClause });
+    }
+  }
+  return { type: "Query", stages, return: returnClause };
+}
+
+// src/engine/cypher-engine.ts
+import { randomUUID } from "crypto";
+var CHAIN_BASE = /* @__PURE__ */ Symbol("contextBase");
+var CHAIN_OVERRIDES = /* @__PURE__ */ Symbol("contextOverrides");
+function isContextChain(ctx) {
+  return CHAIN_BASE in ctx && CHAIN_OVERRIDES in ctx;
+}
+function resolveChainValue(chain, key) {
+  let current = chain;
+  while (current !== null) {
+    if (isContextChain(current)) {
+      const val = current[CHAIN_OVERRIDES][key];
+      if (val !== void 0) return val;
+      current = current[CHAIN_BASE];
+    } else {
+      return current[key];
+    }
+  }
+  return void 0;
+}
+function materialiseChain(chain) {
+  const result = {};
+  const stack = [];
+  let current = chain;
+  while (current !== null) {
+    if (isContextChain(current)) {
+      stack.push(current[CHAIN_OVERRIDES]);
+      current = current[CHAIN_BASE];
+    } else {
+      stack.push(current);
+      break;
+    }
+  }
+  for (let i = 0; i < stack.length; i++) {
+    Object.assign(result, stack[i]);
+  }
+  return result;
+}
+var AdvancedCypherGraphologyEngine = class {
+  graph;
+  indexes;
+  constructor(graph, indexes) {
+    this.graph = graph;
+    this.indexes = indexes;
+  }
+  /**
+   * MAIN ENTRY POINT
+   * Sequentially executes query stages and formats the return projection.
+   */
+  execute(ast) {
+    let contexts = [{}];
+    for (const stage of ast.stages) {
+      if (stage.type === "MATCH") {
+        contexts = this.executeMatch(stage.clause, contexts);
+      } else if (stage.type === "WITH") {
+        contexts = this.executeWith(stage.clause, contexts);
+      } else if (stage.type === "WRITE") {
+        this.executeWrite(stage.clause, contexts);
+      }
+    }
+    if (ast.return) {
+      return this.executeReturn(ast.return, contexts);
+    }
+    return [];
+  }
+  // ── Index-based node lookup (optimisation #2, #3) ─────────────────────────
+  /**
+   * Resolve node IDs matching a pattern using indexes when available.
+   * Falls back to full-graph scan when indexes are absent.
+   */
+  getMatchingNodeIds(pattern) {
+    const indexes = this.indexes;
+    if (!indexes) {
+      return this.graph.filterNodes(
+        (_node, attr) => this.matchNodeCriteria(attr, pattern)
+      );
+    }
+    const { labelIndex, propertyIndex } = indexes;
+    const label = pattern.label;
+    const props = pattern.properties;
+    const propKeys = props ? Object.keys(props) : [];
+    const hasLabel = label !== void 0;
+    const hasProps = propKeys.length > 0;
+    if (hasLabel && hasProps && props) {
+      const labelSet = labelIndex.get(label);
+      if (!labelSet || labelSet.size === 0) return [];
+      const firstKey = propKeys[0];
+      if (!firstKey) return [];
+      const firstVal = String(props[firstKey]);
+      const propSet = propertyIndex.get(firstKey)?.get(firstVal);
+      if (!propSet || propSet.size === 0) return [];
+      const candidates = propSet.size < labelSet.size ? [...propSet].filter((id) => labelSet.has(id)) : [...labelSet].filter((id) => propSet.has(id));
+      if (propKeys.length <= 1) return candidates;
+      return candidates.filter((id) => {
+        const attrs = this.graph.getNodeAttributes(id);
+        return propKeys.slice(1).every((k) => attrs[k] === props[k]);
+      });
+    }
+    if (hasLabel) {
+      const labelSet = labelIndex.get(label);
+      return labelSet ? [...labelSet] : [];
+    }
+    if (hasProps && props) {
+      const firstKey = propKeys[0];
+      if (!firstKey) return [];
+      const firstVal = String(props[firstKey]);
+      const propSet = propertyIndex.get(firstKey)?.get(firstVal);
+      if (!propSet) return [];
+      if (propKeys.length === 1) return [...propSet];
+      return [...propSet].filter((id) => {
+        const attrs = this.graph.getNodeAttributes(id);
+        return propKeys.slice(1).every((k) => attrs[k] === props[k]);
+      });
+    }
+    return this.graph.filterNodes(() => true);
+  }
+  // ── 1. MATCH & OPTIONAL MATCH STAGE ────────────────────────────────────────
+  // Optimisations applied:
+  //   #1  DFS uses shared onStack set + shared edge array (no per-edge copies)
+  //   #2  Label index for start/target node resolution
+  //   #3  Property index for filtered patterns
+  //   #4  Context chains avoid full context copies during traversal
+  executeMatch(clause, incomingContexts) {
+    const { sourcePattern, relationPattern, targetPattern, optional, hasChains } = clause;
+    const outgoingContexts = [];
+    const eligibleTargetIds = new Set(this.getMatchingNodeIds(targetPattern));
+    for (const context of incomingContexts) {
+      let startNodeIds = [];
+      const boundNode = resolveChainValue(context, sourcePattern.variable);
+      if (boundNode && typeof boundNode === "object" && !Array.isArray(boundNode) && "id" in boundNode) {
+        const boundId = boundNode.id;
+        if (this.graph.hasNode(boundId)) {
+          const freshAttrs = this.graph.getNodeAttributes(boundId);
+          if (this.matchNodeCriteria(freshAttrs, sourcePattern)) {
+            startNodeIds = [boundId];
+          }
+        }
+      } else {
+        startNodeIds = this.getMatchingNodeIds(sourcePattern);
+      }
+      let matchFoundForThisContext = false;
+      startNodeIds.forEach((startId) => {
+        const sourceAttr = this.graph.getNodeAttributes(startId);
+        const sourceNode = { id: startId, ...sourceAttr };
+        if (!hasChains) {
+          matchFoundForThisContext = true;
+          outgoingContexts.push({
+            [CHAIN_BASE]: context,
+            [CHAIN_OVERRIDES]: { [sourcePattern.variable]: sourceNode }
+          });
+          return;
+        }
+        const minDepth = relationPattern.minDepth ?? 1;
+        const maxDepth = relationPattern.maxDepth ?? 1;
+        const getNeighbors = this.buildNeighborGetter(relationPattern);
+        const onStack = /* @__PURE__ */ new Set();
+        const edgeHistory = [];
+        const explore = (currentId) => {
+          if (onStack.has(currentId)) return;
+          onStack.add(currentId);
+          if (edgeHistory.length >= minDepth && eligibleTargetIds.has(currentId)) {
+            matchFoundForThisContext = true;
+            const targetAttr = this.graph.getNodeAttributes(currentId);
+            const chain = {
+              [CHAIN_BASE]: context,
+              [CHAIN_OVERRIDES]: {
+                [sourcePattern.variable]: sourceNode,
+                [targetPattern.variable]: { id: currentId, ...targetAttr }
+              }
+            };
+            if (relationPattern.variable) {
+              chain[CHAIN_OVERRIDES][relationPattern.variable] = edgeHistory.map(
+                (edgeId) => ({ id: edgeId, ...this.graph.getEdgeAttributes(edgeId) })
+              );
+            }
+            outgoingContexts.push(chain);
+          }
+          if (edgeHistory.length >= maxDepth) {
+            onStack.delete(currentId);
+            return;
+          }
+          getNeighbors(currentId, (neighborId, edgeId) => {
+            if (neighborId === currentId) {
+              if (edgeHistory.length + 1 >= minDepth && eligibleTargetIds.has(currentId)) {
+                matchFoundForThisContext = true;
+                const targetAttr = this.graph.getNodeAttributes(currentId);
+                const chain = {
+                  [CHAIN_BASE]: context,
+                  [CHAIN_OVERRIDES]: {
+                    [sourcePattern.variable]: sourceNode,
+                    [targetPattern.variable]: { id: currentId, ...targetAttr }
+                  }
+                };
+                if (relationPattern.variable) {
+                  chain[CHAIN_OVERRIDES][relationPattern.variable] = [...edgeHistory, edgeId].map(
+                    (eid) => ({ id: eid, ...this.graph.getEdgeAttributes(eid) })
+                  );
+                }
+                outgoingContexts.push(chain);
+              }
+              return;
+            }
+            edgeHistory.push(edgeId);
+            explore(neighborId);
+            edgeHistory.pop();
+          });
+          onStack.delete(currentId);
+        };
+        explore(startId);
+      });
+      if (optional && !matchFoundForThisContext) {
+        const nullChain = {
+          [CHAIN_BASE]: context,
+          [CHAIN_OVERRIDES]: { [targetPattern.variable]: null }
+        };
+        if (relationPattern.variable) nullChain[CHAIN_OVERRIDES][relationPattern.variable] = [];
+        outgoingContexts.push(nullChain);
+      }
+    }
+    return outgoingContexts;
+  }
+  /**
+   * Build a neighbor iterator using the edge-type adjacency index when available.
+   * Falls back to graph iteration for untyped edges or missing indexes.
+   */
+  buildNeighborGetter(relation) {
+    const indexes = this.indexes;
+    const edgeType = relation.type;
+    const hasIndex = indexes !== void 0 && edgeType !== void 0;
+    if (hasIndex && edgeType && relation.direction === "OUT") {
+      const adj = indexes.edgeTypeIndex.out.get(edgeType);
+      return (nodeId, cb) => {
+        const neighbors = adj?.get(nodeId);
+        if (!neighbors) return;
+        for (const n of neighbors) {
+          cb(n.target, n.edgeId);
+        }
+      };
+    }
+    if (hasIndex && edgeType && relation.direction === "IN") {
+      const adj = indexes.edgeTypeIndex.in.get(edgeType);
+      return (nodeId, cb) => {
+        const neighbors = adj?.get(nodeId);
+        if (!neighbors) return;
+        for (const n of neighbors) {
+          cb(n.source, n.edgeId);
+        }
+      };
+    }
+    if (hasIndex && edgeType && relation.direction === "UNDIRECTED") {
+      const adjOut = indexes.edgeTypeIndex.out.get(edgeType);
+      const adjIn = indexes.edgeTypeIndex.in.get(edgeType);
+      return (nodeId, cb) => {
+        const outNeighbors = adjOut?.get(nodeId);
+        if (outNeighbors) {
+          for (const n of outNeighbors) {
+            cb(n.target, n.edgeId);
+          }
+        }
+        const inNeighbors = adjIn?.get(nodeId);
+        if (inNeighbors) {
+          for (const n of inNeighbors) {
+            cb(n.source, n.edgeId);
+          }
+        }
+      };
+    }
+    return (nodeId, cb) => {
+      const iterator = (id, edgeCb) => {
+        if (relation.direction === "OUT") this.graph.forEachOutboundEdge(id, edgeCb);
+        else if (relation.direction === "IN") this.graph.forEachInboundEdge(id, edgeCb);
+        else this.graph.forEachEdge(id, edgeCb);
+      };
+      iterator(nodeId, (edgeId, edgeAttr, source, target) => {
+        if (relation.type && edgeAttr.type !== relation.type) return;
+        const neighborId = nodeId === source ? target : source;
+        cb(neighborId, edgeId);
+      });
+    };
+  }
+  // ── 2. WITH & IMPLICIT GROUPING AGGREGATIONS STAGE ─────────────────────────
+  // Optimisations applied:
+  //   #4  Context chains throughout, materialised only for grouping
+  //   #5  Single-pass aggregation (all agg types computed in one row scan)
+  executeWith(clause, contexts) {
+    const keysSimple = clause.projections.filter((p) => p.expression.type !== "Aggregation");
+    const keysAggr = clause.projections.filter((p) => p.expression.type === "Aggregation");
+    const groups = /* @__PURE__ */ new Map();
+    const materialised = contexts.map((c) => materialiseChain(c));
+    for (const context of materialised) {
+      const groupKeyObj = {};
+      keysSimple.forEach((p) => {
+        groupKeyObj[p.alias] = this.evaluateExpression(p.expression, context);
+      });
+      const sortedKeys = Object.keys(groupKeyObj).sort();
+      const groupKeyStr = sortedKeys.map((k) => JSON.stringify([k, groupKeyObj[k]])).join(",");
+      if (!groups.has(groupKeyStr)) {
+        groups.set(groupKeyStr, { simpleValues: groupKeyObj, rows: [] });
+      }
+      groups.get(groupKeyStr).rows.push(context);
+    }
+    let newContexts = [];
+    groups.forEach(({ simpleValues, rows }) => {
+      newContexts.push(this.computeAggregations(simpleValues, rows, keysAggr));
+    });
+    if (clause.where) {
+      newContexts = newContexts.filter((ctx) => this.evaluateWhere(clause.where, ctx));
+    }
+    if (clause.orderBy && clause.orderBy.length > 0) {
+      newContexts = this.applyOrderByToContexts(newContexts, clause.orderBy);
+    }
+    if (clause.skip !== void 0 && clause.skip !== null) {
+      newContexts = newContexts.slice(clause.skip);
+    }
+    if (clause.limit !== void 0 && clause.limit !== null) {
+      newContexts = newContexts.slice(0, clause.limit);
+    }
+    return newContexts;
+  }
+  // ── Shared aggregation logic (optimisation #5) ─────────────────────────────
+  // Single-pass: compute COUNT, SUM, AVG, MIN, MAX for all aggregation
+  // variables in one row scan. Used by both executeWith and executeReturn.
+  computeAggregations(baseContext, rows, aggrProjections) {
+    const newContext = { ...baseContext };
+    const aggVars = /* @__PURE__ */ new Map();
+    aggrProjections.forEach((p) => {
+      if (p.expression.type === "Aggregation") {
+        const key = `${p.expression.variable}:${p.expression.property ?? ""}`;
+        aggVars.set(key, p.expression);
+      }
+    });
+    const numericCache = /* @__PURE__ */ new Map();
+    const nonNullCache = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      for (const expr of aggVars.values()) {
+        const key = `${expr.variable}:${expr.property ?? ""}`;
+        const baseVal = row[expr.variable];
+        const val = expr.property ? baseVal?.[expr.property] : baseVal;
+        if (val !== null && val !== void 0) {
+          nonNullCache.set(key, (nonNullCache.get(key) ?? 0) + 1);
+        }
+        if (typeof val === "number") {
+          if (!numericCache.has(key)) numericCache.set(key, []);
+          const arr = numericCache.get(key);
+          if (arr) arr.push(val);
+        }
+      }
+    }
+    aggrProjections.forEach((p) => {
+      const expr = p.expression;
+      if (expr.type !== "Aggregation") return;
+      const key = `${expr.variable}:${expr.property ?? ""}`;
+      const numericValues = numericCache.get(key) ?? [];
+      const nonNullCount = nonNullCache.get(key) ?? 0;
+      if (expr.aggregationType === "COUNT") {
+        newContext[p.alias] = nonNullCount;
+      } else if (expr.aggregationType === "SUM") {
+        newContext[p.alias] = numericValues.reduce((a, b) => a + b, 0);
+      } else if (expr.aggregationType === "AVG") {
+        newContext[p.alias] = numericValues.length > 0 ? numericValues.reduce((a, b) => a + b, 0) / numericValues.length : null;
+      } else if (expr.aggregationType === "MIN") {
+        newContext[p.alias] = numericValues.length > 0 ? Math.min(...numericValues) : null;
+      } else if (expr.aggregationType === "MAX") {
+        newContext[p.alias] = numericValues.length > 0 ? Math.max(...numericValues) : null;
+      }
+    });
+    return newContext;
+  }
+  // ── 3. WRITE MUTATIONS STAGE (CREATE, SET, DELETE) ─────────────────────────
+  // NOTE: indexes are invalidated after mutations so subsequent MATCH/WITH
+  // stages fall back to full-graph scan and see the updated graph state.
+  executeWrite(clause, contexts) {
+    for (let i = 0; i < contexts.length; i++) {
+      const ctx = contexts[i];
+      if (ctx && isContextChain(ctx)) {
+        contexts[i] = materialiseChain(ctx);
+      }
+    }
+    const materialised = contexts;
+    if (clause.type === "CREATE") {
+      const newId = randomUUID();
+      this.graph.addNode(newId, { label: clause.label, ...clause.properties });
+      const newNode = { id: newId, label: clause.label, ...clause.properties };
+      for (const context of materialised) {
+        context[clause.variable] = newNode;
+      }
+    } else if (clause.type === "SET") {
+      const nodeIds = /* @__PURE__ */ new Set();
+      for (const context of materialised) {
+        const targetNode = context[clause.variable];
+        if (targetNode && targetNode.id) nodeIds.add(targetNode.id);
+      }
+      for (const nodeId of nodeIds) {
+        this.graph.setNodeAttribute(nodeId, clause.property, clause.value);
+      }
+      for (const context of materialised) {
+        const targetNode = context[clause.variable];
+        if (targetNode && targetNode.id && nodeIds.has(targetNode.id)) {
+          const fresh = { id: targetNode.id, ...this.graph.getNodeAttributes(targetNode.id) };
+          context[clause.variable] = fresh;
+        }
+      }
+    } else if (clause.type === "DELETE") {
+      const nodeIds = /* @__PURE__ */ new Set();
+      for (const context of materialised) {
+        const targetNode = context[clause.variable];
+        if (targetNode && targetNode.id && this.graph.hasNode(targetNode.id)) {
+          nodeIds.add(targetNode.id);
+        }
+      }
+      for (const nodeId of nodeIds) {
+        this.graph.dropNode(nodeId);
+      }
+      for (const context of materialised) {
+        const targetNode = context[clause.variable];
+        if (targetNode && targetNode.id && nodeIds.has(targetNode.id)) {
+          context[clause.variable] = null;
+        }
+      }
+    }
+    this.indexes = void 0;
+  }
+  // ── 4. RETURN PROJECTION STAGE ─────────────────────────────────────────────
+  // Optimisations applied:
+  //   #5  Single-pass aggregation
+  //   #11 Pre-computed sort keys (Schwartzian transform)
+  executeReturn(clause, contexts) {
+    const keysSimple = clause.projections.filter((p) => p.expression.type !== "Aggregation");
+    const keysAggr = clause.projections.filter((p) => p.expression.type === "Aggregation");
+    let results;
+    if (keysAggr.length > 0) {
+      const materialised = contexts.map((c) => materialiseChain(c));
+      const result = {};
+      keysSimple.forEach((p) => {
+        const values = materialised.map((ctx) => this.evaluateExpression(p.expression, ctx));
+        const uniqueValues = new Set(values.map((v) => JSON.stringify(v)));
+        if (uniqueValues.size > 1) {
+          throw new Error(
+            `Mixed aggregation and non-aggregation in RETURN without WITH: "${p.alias}" has different values across rows. Use a WITH clause to group first.`
+          );
+        }
+        result[p.alias] = values[0];
+      });
+      const aggResult = this.computeAggregations(result, materialised, keysAggr);
+      results = [aggResult];
+    } else {
+      const materialised = contexts.map((c) => materialiseChain(c));
+      let workingContexts = materialised;
+      if (clause.orderBy && clause.orderBy.length > 0) {
+        workingContexts = this.applyOrderByToContexts(workingContexts, clause.orderBy);
+      }
+      if (clause.skip !== void 0 && clause.skip !== null) {
+        workingContexts = workingContexts.slice(clause.skip);
+      }
+      if (clause.limit !== void 0 && clause.limit !== null) {
+        workingContexts = workingContexts.slice(0, clause.limit);
+      }
+      results = workingContexts.map((context) => {
+        const res = {};
+        clause.projections.forEach((p) => {
+          res[p.alias] = this.evaluateExpression(p.expression, context);
+        });
+        return res;
+      });
+    }
+    return results;
+  }
+  // ── Expression evaluation ──────────────────────────────────────────────────
+  evaluateExpression(expr, context) {
+    if (expr.type === "PropertyAccess") {
+      const obj = context[expr.variable];
+      if (obj === void 0) return void 0;
+      if (obj === null) return null;
+      if (expr.property) return obj[expr.property];
+      return obj;
+    }
+    if (expr.type === "Literal") return expr.value;
+    if (expr.type === "Aggregation") return void 0;
+    return void 0;
+  }
+  evaluateWhere(whereNode, context) {
+    const leftValue = this.evaluateExpression(whereNode.left, context);
+    const rightValue = this.evaluateExpression(whereNode.right, context);
+    switch (whereNode.operator) {
+      case ">":
+        if (typeof leftValue !== "number" || typeof rightValue !== "number") {
+          throw new Error(`WHERE comparison "${whereNode.operator}" requires numeric values, got ${JSON.stringify(leftValue)} and ${JSON.stringify(rightValue)}`);
+        }
+        return leftValue > rightValue;
+      case "<":
+        if (typeof leftValue !== "number" || typeof rightValue !== "number") {
+          throw new Error(`WHERE comparison "${whereNode.operator}" requires numeric values, got ${JSON.stringify(leftValue)} and ${JSON.stringify(rightValue)}`);
+        }
+        return leftValue < rightValue;
+      case "=":
+        return leftValue === rightValue;
+      case "CONTAINS":
+        return String(leftValue).includes(String(rightValue));
+      default:
+        return false;
+    }
+  }
+  // ── ORDER BY with pre-computed sort keys (optimisation #11) ────────────────
+  // Schwartzian transform: compute sort keys once per context, then sort by keys.
+  // Avoids re-evaluating expressions on every comparison (n log n → n + n log n key compares).
+  applyOrderByToContexts(contexts, orderBy) {
+    const keyed = contexts.map((ctx) => ({
+      ctx,
+      keys: orderBy.map((item) => this.evaluateExpression(item.expression, ctx))
+    }));
+    keyed.sort((a, b) => {
+      for (let i = 0; i < orderBy.length; i++) {
+        const cmp = this.compareValues(a.keys[i], b.keys[i]);
+        const item = orderBy[i];
+        if (cmp !== 0 && item) return item.direction === "DESC" ? -cmp : cmp;
+      }
+      return 0;
+    });
+    return keyed.map((k) => k.ctx);
+  }
+  /**
+   * Compare two values for sorting. Handles nulls, numbers, strings, booleans.
+   * null < boolean < number < string < object
+   * Mixed-type coercion differs from Neo4j (which throws). Here we stringify
+   * for pragmatic compatibility in exploratory queries.
+   */
+  compareValues(a, b) {
+    if (a === null || a === void 0) {
+      if (b === null || b === void 0) return 0;
+      return -1;
+    }
+    if (b === null || b === void 0) return 1;
+    if (typeof a === "number" && typeof b === "number") return a - b;
+    if (typeof a === "string" && typeof b === "string") return a < b ? -1 : a > b ? 1 : 0;
+    if (typeof a === "boolean" && typeof b === "boolean") return a === b ? 0 : a ? -1 : 1;
+    const aStr = String(a);
+    const bStr = String(b);
+    return aStr < bStr ? -1 : aStr > bStr ? 1 : 0;
+  }
+  matchNodeCriteria(nodeAttr, pattern) {
+    if (pattern.label !== void 0 && nodeAttr.label !== pattern.label) return false;
+    const props = pattern.properties;
+    if (props) {
+      return Object.keys(props).every((k) => nodeAttr[k] === props[k]);
+    }
+    return true;
+  }
+};
+
+// src/indexes.ts
+function buildIndexes(nodeIterator, graph) {
+  const labelIndex = /* @__PURE__ */ new Map();
+  const propertyIndex = /* @__PURE__ */ new Map();
+  const edgeOut = /* @__PURE__ */ new Map();
+  const edgeIn = /* @__PURE__ */ new Map();
+  for (const [id, attrs] of nodeIterator) {
+    const label = attrs.label;
+    if (label && typeof label === "string") {
+      let labelSet = labelIndex.get(label);
+      if (!labelSet) {
+        labelSet = /* @__PURE__ */ new Set();
+        labelIndex.set(label, labelSet);
+      }
+      labelSet.add(id);
+    }
+    for (const [key, value] of Object.entries(attrs)) {
+      if (key === "id" || key === "label") continue;
+      if (value === null || value === void 0 || typeof value === "object") continue;
+      let valMap = propertyIndex.get(key);
+      if (!valMap) {
+        valMap = /* @__PURE__ */ new Map();
+        propertyIndex.set(key, valMap);
+      }
+      const valKey = String(value);
+      let nodeSet = valMap.get(valKey);
+      if (!nodeSet) {
+        nodeSet = /* @__PURE__ */ new Set();
+        valMap.set(valKey, nodeSet);
+      }
+      nodeSet.add(id);
+    }
+  }
+  graph.forEachEdge((edgeId, attrs, source, target) => {
+    const edgeType = attrs.type && typeof attrs.type === "string" ? attrs.type : "__UNTYPED__";
+    let outMap = edgeOut.get(edgeType);
+    if (!outMap) {
+      outMap = /* @__PURE__ */ new Map();
+      edgeOut.set(edgeType, outMap);
+    }
+    let outList = outMap.get(source);
+    if (!outList) {
+      outList = [];
+      outMap.set(source, outList);
+    }
+    outList.push({ target, edgeId });
+    let inMap = edgeIn.get(edgeType);
+    if (!inMap) {
+      inMap = /* @__PURE__ */ new Map();
+      edgeIn.set(edgeType, inMap);
+    }
+    let inList = inMap.get(target);
+    if (!inList) {
+      inList = [];
+      inMap.set(target, inList);
+    }
+    inList.push({ source, edgeId });
+  });
+  return {
+    labelIndex,
+    propertyIndex,
+    edgeTypeIndex: { out: edgeOut, in: edgeIn }
+  };
+}
+function buildGraphIndexesFromGraph(graph) {
+  const allNodes = graph.filterNodes(() => true);
+  const nodeEntries = allNodes.map((id) => [id, graph.getNodeAttributes(id)]);
+  return buildIndexes(nodeEntries, graph);
+}
+function buildGraphIndexesFromData(data, graph) {
+  const nodeEntries = data.nodes.map((node) => [node.id, node]);
+  return buildIndexes(nodeEntries, graph);
+}
+
+// src/graph.ts
+import GraphModule from "graphology";
+var Graph = GraphModule;
+function assertGraphApi(graph) {
+  const requiredMethods = [
+    "addNode",
+    "addEdge",
+    "getNodeAttributes",
+    "getEdgeAttributes",
+    "filterNodes",
+    "forEachOutboundEdge",
+    "forEachInboundEdge",
+    "forEachEdge",
+    "setNodeAttribute",
+    "hasNode",
+    "dropNode"
+  ];
+  for (const method of requiredMethods) {
+    if (typeof graph[method] !== "function") {
+      throw new Error(`Graphology API mismatch: missing method "${method}".`);
+    }
+  }
+}
+if (process.env.NODE_ENV === "development") {
+  assertGraphApi(new Graph());
+}
+
+// src/lib.ts
+var GraphError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GraphError";
+  }
+};
+function validateGraphData(data) {
+  if (!data || typeof data !== "object") {
+    throw new GraphError('Invalid graph data: expected a JSON object with "nodes" and "edges" arrays.');
+  }
+  const obj = data;
+  if (!Array.isArray(obj.nodes)) {
+    throw new GraphError('Invalid graph data: "nodes" must be an array.');
+  }
+  if (!Array.isArray(obj.edges)) {
+    throw new GraphError('Invalid graph data: "edges" must be an array.');
+  }
+  const seenNodeIds = /* @__PURE__ */ new Set();
+  for (let i = 0; i < obj.nodes.length; i++) {
+    const node = obj.nodes[i];
+    if (!node || typeof node !== "object") {
+      throw new GraphError(`Invalid graph data: node at index ${i} must be an object.`);
+    }
+    const n = node;
+    if (typeof n.id !== "string" || !n.id) {
+      throw new GraphError(`Invalid graph data: node at index ${i} must have a non-empty string "id".`);
+    }
+    if (seenNodeIds.has(n.id)) {
+      throw new GraphError(`Invalid graph data: duplicate node id "${n.id}" at index ${i}.`);
+    }
+    seenNodeIds.add(n.id);
+  }
+  const nodeIds = seenNodeIds;
+  const seenEdges = /* @__PURE__ */ new Set();
+  for (let i = 0; i < obj.edges.length; i++) {
+    const edge = obj.edges[i];
+    if (!edge || typeof edge !== "object") {
+      throw new GraphError(`Invalid graph data: edge at index ${i} must be an object.`);
+    }
+    const e = edge;
+    if (typeof e.source !== "string" || !e.source) {
+      throw new GraphError(`Invalid graph data: edge at index ${i} must have a non-empty string "source".`);
+    }
+    if (typeof e.target !== "string" || !e.target) {
+      throw new GraphError(`Invalid graph data: edge at index ${i} must have a non-empty string "target".`);
+    }
+    if (!nodeIds.has(e.source)) {
+      throw new GraphError(`Invalid graph data: edge at index ${i} references unknown source node "${e.source}".`);
+    }
+    if (!nodeIds.has(e.target)) {
+      throw new GraphError(`Invalid graph data: edge at index ${i} references unknown target node "${e.target}".`);
+    }
+    const edgeKey = `${e.source}->${e.target}`;
+    if (seenEdges.has(edgeKey)) {
+      throw new GraphError(`Invalid graph data: duplicate edge "${edgeKey}" at index ${i}. Graphology does not support multi-graphs.`);
+    }
+    seenEdges.add(edgeKey);
+  }
+  return {
+    nodes: obj.nodes,
+    edges: obj.edges
+  };
+}
+function createGraph(data) {
+  const validated = validateGraphData(data);
+  return buildGraph(validated);
+}
+function buildGraph(validated) {
+  const graph = new Graph();
+  for (const node of validated.nodes) {
+    const { id, ...attrs } = node;
+    graph.addNode(id, attrs);
+  }
+  for (const edge of validated.edges) {
+    const { source, target, ...attrs } = edge;
+    graph.addEdge(source, target, attrs);
+  }
+  return graph;
+}
+function buildGraphIndexes(dataOrGraph, graph) {
+  if (graph === void 0) {
+    if (isGraphInstance(dataOrGraph)) {
+      return buildGraphIndexesFromGraph(dataOrGraph);
+    }
+    const validated2 = validateGraphData(dataOrGraph);
+    const builtGraph = buildGraph(validated2);
+    return buildGraphIndexesFromGraph(builtGraph);
+  }
+  const validated = validateGraphData(dataOrGraph);
+  return buildGraphIndexesFromData(validated, graph);
+}
+function parseCypher2(query) {
+  return parseCypher(query);
+}
+function executeQuery(graphOrData, query) {
+  const graph = isGraphInstance(graphOrData) ? graphOrData : buildGraph(validateGraphData(graphOrData));
+  const indexes = buildGraphIndexesFromGraph(graph);
+  const engine = new AdvancedCypherGraphologyEngine(graph, indexes);
+  const ast = parseCypher(query);
+  return engine.execute(ast);
+}
+function isGraphInstance(value) {
+  return typeof value.hasNode === "function" && typeof value.filterNodes === "function" && typeof value.forEachEdge === "function";
+}
+export {
+  Graph,
+  AdvancedCypherGraphologyEngine as GraphEngine,
+  GraphError,
+  buildGraphIndexes,
+  createGraph,
+  executeQuery,
+  parseCypher2 as parseCypher
+};