// Package gql implements a GQL query engine over the in-memory graph of
// [github.com/pancsta/asyncmachine-go/pkg/graph]. It uses the parser front-end
// of the gochickpeas fork (gql/gqlparser) and a native executor that reads the
// live github.com/dominikbraun/graph instance directly, with no separate
// storage and no chickpeas snapshot.
//
// The exposed graph model mirrors the frogql backend, so queries are portable
// between the two:
//
//	(:Machine {id, parent, schema_hash, mtime_sum, queue_tick, mach_tick})
//	(:State {mach, name, tick, active})
//	(:Tag {mach, name, value})
//	(Machine)-[:HAS {auto, multi}]->(State)
//	(Machine)-[:HAS_TAG]->(Tag)
//	(Machine)-[:CHILD_OF]->(Machine)
//	(Machine)-[:CONNECTED_TO]->(Machine) // RPC conns (src-id tags)
//	(State)-[:REQUIRE|ADD|REMOVE|AFTER]->(State)
//
// This package is MIT-licensed (see LICENSE). The GQL parser front-end comes
// from the MIT-licensed gochickpeas fork (see LICENSE.gochickpeas).

package gql

import (
	
	
	
	
	
	

	

	amgraph 
	amtypes 
	am 
)

// Db implements [amtypes.DbGraph] over a live in-memory graph instance. It
// keeps no data of its own: every Exec projects the current graph (through
// dominikbraun/graph's locked accessors, which return copies) and runs the
// native executor over it, so queries always see the latest state without any
// mirroring or sync loop.
//
// Wire it to the same graph the NetGraph maintains:
//
//	netGraph.Db = gql.NewDb(netGraph.Graph)
//
// The GQL engine is read-only: writes go through the graph itself (AddMachine,
// ParseMsgDbg, ParseMsgRpc), which is why UpsertMachine/SyncMachine are no-ops
// here.
type Db struct {
	graph *amgraph.Graph
}

var _ amtypes.DbGraph = (*Db)(nil)

// NewDb returns a [amtypes.DbGraph] reading g. g must not be nil.
func ( *amgraph.Graph) amtypes.DbGraph {
	return &Db{graph: }
}

// Exec parses and executes one GQL read statement against a snapshot of the
// graph. It returns []any, each element a map[string]any of output columns, in
// the same shape as the frogql backend (JSON/msgpack encodable; numbers are
// int64/float64).
func ( *Db) ( string) (any, error) {
	,  := gqlparser.Parse()
	if  != nil {
		return nil, fmt.Errorf("%w: %w", ErrParse, )
	}
	if  := gqlparser.Desugar();  != nil {
		return nil, fmt.Errorf("%w: %w", ErrUnsupported, )
	}

	,  := .snapshot()
	if  != nil {
		return nil, 
	}

	 := &exec{store: }
	, ,  := .query()
	if  != nil {
		return nil, 
	}

	 := make([]any, len())
	for ,  := range  {
		 := make(map[string]any, len())
		for ,  := range  {
			[] = .out[].Any()
		}
		[] = 
	}
	return , nil
}

// snapshot projects the current graph into the queryable store. The store
// build reads through dominikbraun/graph's locked accessors, which return
// copies, so no full graph [amgraph.Graph.Clone] (and no Map mirror clone) is
// needed per query.
func ( *Db) () (*store, error) {
	if  == nil || .graph == nil {
		return nil, errors.New("gql: nil graph")
	}
	return newStore(.graph)
}

// NodeCount returns the number of vertices in the graph instance.
func ( *Db) () int {
	,  := .snapshot()
	if  != nil {
		return 0
	}
	return len(.nodes)
}

// EdgeCount returns the number of logical relationships in the graph
// instance (one physical edge may expand into several).
func ( *Db) () int {
	,  := .snapshot()
	if  != nil {
		return 0
	}
	return len(.rels)
}

// UpsertMachine is a no-op: the queried store is the live graph instance,
// which the NetGraph updates before pushing to Db.
func ( *Db) (*amtypes.Machine) error {
	return nil
}

// SyncMachine is a no-op: see UpsertMachine.
func ( *Db) (*amtypes.Machine) error {
	return nil
}

// Close is a no-op: the Db owns no resources.
func ( *Db) () error {
	return nil
}

// litVal converts a parsed literal to a runtime value. Named and auto-lifted
// parameters are unsupplied (Exec has no parameter binding), so they read as
// null.
func litVal( gqlparser.Literal) Value {
	switch .Kind {
	case gqlparser.LitInt:
		return Int(.I)
	case gqlparser.LitFloat:
		return Float(.F)
	case gqlparser.LitStr:
		return Str(.S)
	case gqlparser.LitBool:
		return Bool(.B)
	case gqlparser.LitNull, gqlparser.LitNamedParam, gqlparser.LitParam:
		return Null()
	}
	return Null()
}

// eqVal is two-valued equality used by inline property filters.
func eqVal(,  Value) bool {
	,  := compare(, )
	return  &&  == 0
}

// eval evaluates one expression against a row.
func ( *exec) ( row,  gqlparser.Expr) (Value, error) {
	switch n := .(type) {
	case nil:
		return Null(), nil

	case *gqlparser.Lit:
		return litVal(.Value), nil

	case *gqlparser.Var:
		,  := .vals[.Name]
		if ! {
			return Null(), fmt.Errorf("%w: unknown variable %q", ErrParse, .Name)
		}
		return , nil

	case *gqlparser.Prop:
		,  := .(, &gqlparser.Var{Name: .Var})
		if  != nil {
			return Null(), 
		}
		return propOf(, .Key), nil

	case *gqlparser.PropOf:
		,  := .(, .Base)
		if  != nil {
			return Null(), 
		}
		return propOf(, .Key), nil

	case *gqlparser.Unary:
		,  := .(, .Expr)
		if  != nil {
			return Null(), 
		}
		switch .Op {
		case gqlparser.Not:
			if .kind == kBool {
				return Bool(!.b), nil
			}
			return Null(), nil
		case gqlparser.Neg:
			if .kind == kInt {
				return Int(-.i), nil
			}
			if .kind == kFloat {
				return Float(-.f), nil
			}
			return Null(), nil
		}
		return Null(), fmt.Errorf("%w: unary op %d", ErrUnsupported, .Op)

	case *gqlparser.Binary:
		return .evalBinary(, )

	case *gqlparser.Func:
		return .evalFunc(, )

	case *gqlparser.ListExpr:
		 := make([]Value, len(.Elems))
		for ,  := range .Elems {
			,  := .(, )
			if  != nil {
				return Null(), 
			}
			[] = 
		}
		return List(), nil

	case *gqlparser.In:
		,  := .(, .Expr)
		if  != nil {
			return Null(), 
		}
		,  := .(, .List)
		if  != nil {
			return Null(), 
		}
		if .kind != kList {
			return Null(), nil
		}
		 := false
		for ,  := range .list {
			if .kind == kNull || .kind == kNull {
				 = true
				continue
			}
			if eqVal(, ) {
				return Bool(true), nil
			}
		}
		if  {
			return Null(), nil
		}
		return Bool(false), nil

	case *gqlparser.IsNull:
		,  := .(, .Expr)
		if  != nil {
			return Null(), 
		}
		 := .kind == kNull
		if .Negated {
			 = !
		}
		return Bool(), nil

	case *gqlparser.IsTruth:
		,  := .(, .Expr)
		if  != nil {
			return Null(), 
		}
		var  bool
		if .Want {
			 = .kind == kBool && .b
		} else {
			 = .kind == kBool && !.b
		}
		if .Negated {
			 = !
		}
		return Bool(), nil

	case *gqlparser.IsTyped:
		,  := .(, .Expr)
		if  != nil {
			return Null(), 
		}
		 := typeMatches(, .Kind)
		if .Negated {
			 = !
		}
		return Bool(), nil

	case *gqlparser.Case:
		return .evalCase(, )

	case *gqlparser.Index:
		return .evalIndex(, )

	case *gqlparser.Slice:
		return .evalSlice(, )

	case *gqlparser.ListPred:
		return .evalListPred(, )

	case *gqlparser.MapLit:
		 := make(map[string]Value, len(.Fields))
		for ,  := range .Fields {
			,  := .(, .Val)
			if  != nil {
				return Null(), 
			}
			[.Key] = 
		}
		return Map(), nil

	case *gqlparser.HasLabelExpr:
		,  := .(, &gqlparser.Var{Name: .Var})
		if  != nil {
			return Null(), 
		}
		if .kind != kNode {
			return Bool(false), nil
		}
		return Bool(labelMatches(.node, .Expr)), nil
	}

	return Null(), fmt.Errorf("%w: expression %T", ErrUnsupported, )
}

// evalBinary evaluates an infix operator.
func ( *exec) ( row,  *gqlparser.Binary) (Value, error) {
	,  := .eval(, .LHS)
	if  != nil {
		return Null(), 
	}
	,  := .eval(, .RHS)
	if  != nil {
		return Null(), 
	}

	switch .Op {
	case gqlparser.OpAnd:
		return andVal(, ), nil
	case gqlparser.OpOr:
		return orVal(, ), nil
	case gqlparser.OpXor:
		return xorVal(, ), nil
	}

	if .IsNum() || .IsNum() {
		switch .Op {
		case gqlparser.OpAdd, gqlparser.OpSub, gqlparser.OpMul, gqlparser.OpDiv:
			return arith(.Op, , ), nil
		}
	}

	switch .Op {
	case gqlparser.OpEq, gqlparser.OpNeq, gqlparser.OpLt, gqlparser.OpLte,
		gqlparser.OpGt, gqlparser.OpGte:
		,  := compare(, )
		if ! {
			return Null(), nil
		}
		switch .Op {
		case gqlparser.OpEq:
			return Bool( == 0), nil
		case gqlparser.OpNeq:
			return Bool( != 0), nil
		case gqlparser.OpLt:
			return Bool( < 0), nil
		case gqlparser.OpLte:
			return Bool( <= 0), nil
		case gqlparser.OpGt:
			return Bool( > 0), nil
		case gqlparser.OpGte:
			return Bool( >= 0), nil
		}
	case gqlparser.OpAdd:
		return arith(.Op, , ), nil
	case gqlparser.OpSub, gqlparser.OpMul, gqlparser.OpDiv:
		return Null(), nil
	case gqlparser.OpConcat:
		return concatVal(, ), nil
	case gqlparser.OpStartsWith, gqlparser.OpEndsWith, gqlparser.OpContains:
		if .kind != kString || .kind != kString {
			return Null(), nil
		}
		switch .Op {
		case gqlparser.OpStartsWith:
			return Bool(strings.HasPrefix(.s, .s)), nil
		case gqlparser.OpEndsWith:
			return Bool(strings.HasSuffix(.s, .s)), nil
		}
		return Bool(strings.Contains(.s, .s)), nil
	}

	return Null(), fmt.Errorf("%w: binary op %d", ErrUnsupported, .Op)
}

// evalFunc evaluates a scalar function call.
func ( *exec) ( row,  *gqlparser.Func) (Value, error) {
	if isAggregate() {
		return Null(), fmt.Errorf(
			"%w: aggregate %q outside a projection", ErrUnsupported, .Name)
	}

	 := make([]Value, len(.Args))
	for  := range .Args {
		,  := .eval(, .Args[])
		if  != nil {
			return Null(), 
		}
		[] = 
	}

	switch strings.ToLower(.Name) {
	case "labels":
		if len() != 1 || [0].kind != kNode {
			return Null(), nil
		}
		return List([]Value{Str([0].node.label)}), nil
	case "type":
		if len() != 1 || [0].kind != kRel {
			return Null(), nil
		}
		return Str([0].rel.typ), nil
	case "id":
		if len() != 1 {
			return Null(), nil
		}
		switch [0].kind {
		case kNode:
			return Str([0].node.id), nil
		case kRel:
			return Str("r" + strconv.Itoa([0].rel.idx)), nil
		}
		return Null(), nil
	case "keys":
		if len() != 1 {
			return Null(), nil
		}
		var  []string
		switch [0].kind {
		case kNode:
			for  := range [0].node.props {
				 = append(, )
			}
		case kRel:
			for  := range [0].rel.props {
				 = append(, )
			}
		case kMap:
			for  := range [0].mp {
				 = append(, )
			}
		default:
			return Null(), nil
		}
		sort.Strings()
		 := make([]Value, len())
		for ,  := range  {
			[] = Str()
		}
		return List(), nil
	case "size", "length":
		if len() != 1 {
			return Null(), nil
		}
		switch [0].kind {
		case kList:
			return Int(int64(len([0].list))), nil
		case kString:
			return Int(int64(len([0].s))), nil
		}
		return Null(), nil
	case "coalesce":
		for ,  := range  {
			if .kind != kNull {
				return , nil
			}
		}
		return Null(), nil
	case "tostring":
		if len() != 1 {
			return Null(), nil
		}
		switch [0].kind {
		case kNull:
			return Null(), nil
		case kString:
			return [0], nil
		case kBool:
			return Str(strconv.FormatBool([0].b)), nil
		case kInt:
			return Str(strconv.FormatInt([0].i, 10)), nil
		case kFloat:
			return Str(strconv.FormatFloat([0].f, 'g', -1, 64)), nil
		}
		return Null(), nil
	case "tointeger":
		if len() != 1 {
			return Null(), nil
		}
		switch [0].kind {
		case kInt:
			return [0], nil
		case kFloat:
			return Int(int64([0].f)), nil
		case kString:
			,  := strconv.ParseInt([0].s, 10, 64)
			if  != nil {
				return Null(), nil
			}
			return Int(), nil
		}
		return Null(), nil
	case "tofloat":
		if len() != 1 {
			return Null(), nil
		}
		if ,  := [0].Float64();  {
			return Float(), nil
		}
		if [0].kind == kString {
			,  := strconv.ParseFloat([0].s, 64)
			if  != nil {
				return Null(), nil
			}
			return Float(), nil
		}
		return Null(), nil
	}

	return Null(), fmt.Errorf("%w: function %q", ErrUnsupported, .Name)
}

// evalCase evaluates a CASE expression.
func ( *exec) ( row,  *gqlparser.Case) (Value, error) {
	if .Operand != nil {
		,  := .eval(, .Operand)
		if  != nil {
			return Null(), 
		}
		for ,  := range .Whens {
			,  := .eval(, .Cond)
			if  != nil {
				return Null(), 
			}
			if eqVal(, ) {
				return .eval(, .Result)
			}
		}
	} else {
		for ,  := range .Whens {
			,  := .eval(, .Cond)
			if  != nil {
				return Null(), 
			}
			if truth() {
				return .eval(, .Result)
			}
		}
	}
	if .Else != nil {
		return .eval(, .Else)
	}
	return Null(), nil
}

// evalIndex evaluates base[index] over lists and strings.
func ( *exec) ( row,  *gqlparser.Index) (Value, error) {
	,  := .eval(, .Base)
	if  != nil {
		return Null(), 
	}
	,  := .eval(, .Idx)
	if  != nil {
		return Null(), 
	}
	,  := .Float64()
	if ! {
		return Null(), nil
	}
	 := int()

	switch .kind {
	case kList:
		return listAt(.list, ), nil
	case kString:
		 := []rune(.s)
		if  := listAtRunes(, );  != nil {
			return Str(string(*)), nil
		}
	}
	return Null(), nil
}

// evalSlice evaluates base[from..to].
func ( *exec) ( row,  *gqlparser.Slice) (Value, error) {
	,  := .eval(, .Base)
	if  != nil {
		return Null(), 
	}
	if .kind != kList {
		return Null(), nil
	}
	,  := 0, len(.list)
	if .From != nil {
		,  := .eval(, .From)
		if  != nil {
			return Null(), 
		}
		if ,  := .Float64();  {
			 = clampIndex(int(), len(.list))
		}
	}
	if .To != nil {
		,  := .eval(, .To)
		if  != nil {
			return Null(), 
		}
		if ,  := .Float64();  {
			 = clampIndex(int(), len(.list))
		}
	}
	if  >  {
		return List(nil), nil
	}
	 := make([]Value, -)
	copy(, .list[:])
	return List(), nil
}

// evalListPred evaluates all/any/none/single predicates.
func ( *exec) ( row,  *gqlparser.ListPred) (Value, error) {
	,  := .eval(, .List)
	if  != nil {
		return Null(), 
	}
	if .kind != kList {
		return Null(), nil
	}

	 := 0
	for ,  := range .list {
		 := .clone()
		.vals[.Var] = 
		,  := .eval(, .Pred)
		if  != nil {
			return Null(), 
		}
		if truth() {
			++
		}
	}

	switch .Quant {
	case gqlparser.QuantAll:
		return Bool( == len(.list)), nil
	case gqlparser.QuantAny:
		return Bool( > 0), nil
	case gqlparser.QuantNone:
		return Bool( == 0), nil
	case gqlparser.QuantSingle:
		return Bool( == 1), nil
	}
	return Null(), nil
}

// propOf reads key from a node, relationship, or map value.
func propOf( Value,  string) Value {
	switch .kind {
	case kNode:
		if ,  := .node.props[];  {
			return 
		}
	case kRel:
		if ,  := .rel.props[];  {
			return 
		}
	case kMap:
		if ,  := .mp[];  {
			return 
		}
	}
	return Null()
}

// andVal is three-valued AND.
func andVal(,  Value) Value {
	if (.kind == kBool && !.b) || (.kind == kBool && !.b) {
		return Bool(false)
	}
	if .kind == kNull || .kind == kNull {
		return Null()
	}
	return Bool(truth() && truth())
}

// orVal is three-valued OR.
func orVal(,  Value) Value {
	if (.kind == kBool && .b) || (.kind == kBool && .b) {
		return Bool(true)
	}
	if .kind == kNull || .kind == kNull {
		return Null()
	}
	return Bool(false)
}

// xorVal is three-valued XOR.
func xorVal(,  Value) Value {
	if .kind == kNull || .kind == kNull {
		return Null()
	}
	return Bool(truth() != truth())
}

// arith evaluates + - * / with GQL null semantics; + also concatenates
// strings and lists.
func arith( gqlparser.BinOp, ,  Value) Value {
	if  == gqlparser.OpAdd {
		switch {
		case .kind == kString && .kind == kString:
			return Str(.s + .s)
		case .kind == kList && .kind == kList:
			 := make([]Value, 0, len(.list)+len(.list))
			 = append(, .list...)
			 = append(, .list...)
			return List()
		}
	}

	,  := .Float64()
	,  := .Float64()
	if ! || ! {
		return Null()
	}
	 := .kind == kInt && .kind == kInt

	switch  {
	case gqlparser.OpAdd:
		if  {
			return Int(.i + .i)
		}
		return Float( + )
	case gqlparser.OpSub:
		if  {
			return Int(.i - .i)
		}
		return Float( - )
	case gqlparser.OpMul:
		if  {
			return Int(.i * .i)
		}
		return Float( * )
	case gqlparser.OpDiv:
		if  == 0 {
			return Null()
		}
		if  {
			return Int(.i / .i)
		}
		return Float( / )
	}
	return Null()
}

// concatVal is the || operator: strings or lists only.
func concatVal(,  Value) Value {
	switch {
	case .kind == kString && .kind == kString:
		return Str(.s + .s)
	case .kind == kList && .kind == kList:
		 := make([]Value, 0, len(.list)+len(.list))
		 = append(, .list...)
		 = append(, .list...)
		return List()
	}
	return Null()
}

// typeMatches implements IS TYPED.
func typeMatches( Value,  string) bool {
	switch strings.ToLower() {
	case "integer":
		return .kind == kInt
	case "float":
		return .kind == kFloat
	case "string":
		return .kind == kString
	case "boolean":
		return .kind == kBool
	case "list":
		return .kind == kList
	case "map":
		return .kind == kMap
	case "node":
		return .kind == kNode
	case "relationship":
		return .kind == kRel
	}
	return false
}

// labelMatches tests a label expression against a node.
func labelMatches( *node,  *gqlparser.LabelExpr) bool {
	if  == nil {
		return true
	}
	switch .Kind {
	case gqlparser.LabelName:
		return .label == .Name
	case gqlparser.LabelAnd:
		return (, .L) && (, .R)
	case gqlparser.LabelOr:
		return (, .L) || (, .R)
	case gqlparser.LabelNot:
		return !(, .L)
	case gqlparser.LabelWild:
		return .label != ""
	}
	return false
}

// listAt returns the element at i, with negative indices from the end.
func listAt( []Value,  int) Value {
	if  < 0 {
		 += len()
	}
	if  < 0 ||  >= len() {
		return Null()
	}
	return []
}

// listAtRunes is listAt over a rune slice, returning a pointer to the rune.
func listAtRunes( []rune,  int) *rune {
	if  < 0 {
		 += len()
	}
	if  < 0 ||  >= len() {
		return nil
	}
	return &[]
}

// clampIndex normalizes a possibly negative list index into [0, n].
func clampIndex(,  int) int {
	if  < 0 {
		 += 
	}
	if  < 0 {
		return 0
	}
	if  >  {
		return 
	}
	return 
}

var (
	// ErrGraph marks failures while snapshotting the graph instance.
	ErrGraph = errors.New("gql graph error")
	// ErrParse marks GQL syntax errors.
	ErrParse = errors.New("gql parse error")
	// ErrUnsupported marks valid GQL constructs the native executor does not
	// implement yet.
	ErrUnsupported = errors.New("gql unsupported")
)

// exec runs a parsed query against one store snapshot.
type exec struct {
	store *store
}

// row is one binding environment flowing through the clauses.
type row struct {
	vals map[string]Value
	// used is the set of relationship indices taken in the current MATCH
	// clause (relationship uniqueness).
	used map[int]struct{}
}

// outRow pairs a projected row with its source row, so ORDER BY expressions
// can still reach pre-projection variables.
type outRow struct {
	src row
	out map[string]Value
}

func newRow() row { return row{vals: make(map[string]Value, 4)} }

// clone deep-copies the row's maps (bindings and the used-rel set).
func ( row) () row {
	 := row{vals: make(map[string]Value, len(.vals))}
	for ,  := range .vals {
		.vals[] = 
	}
	if .used != nil {
		.used = make(map[int]struct{}, len(.used))
		for  := range .used {
			.used[] = struct{}{}
		}
	}
	return 
}

func ( row) ( string,  Value) row {
	 := .clone()
	.vals[] = 
	return 
}

func ( row) ( int) row {
	 := .clone()
	if .used == nil {
		.used = make(map[int]struct{}, 2)
	}
	.used[] = struct{}{}
	return 
}

// query executes a whole query and returns projected rows plus column names
// in output order.
func ( *exec) ( *gqlparser.Query) ([]outRow, []string, error) {
	if  == nil || len(.Parts) == 0 {
		return nil, nil, fmt.Errorf("%w: empty query", ErrParse)
	}

	if .Mode == gqlparser.Explain || .Mode == gqlparser.Profile {
		return []outRow{{out: map[string]Value{"plan": Str(explainQuery())}}},
			[]string{"plan"}, nil
	}

	var  []outRow
	var  []string

	for  := range .Parts {
		 := len(.Parts) == 1
		, ,  := .runPart(&.Parts[], )
		if  != nil {
			return nil, nil, 
		}

		if  == 0 {
			,  = , 
			continue
		}
		if !sameStrings(, ) {
			return nil, nil, fmt.Errorf(
				"%w: UNION parts project different columns: %v vs %v",
				ErrUnsupported, , )
		}

		switch .Union[-1] {
		case gqlparser.UnionAll:
			 = append(, ...)
		case gqlparser.UnionDistinct:
			 = dedupeOut(append(, ...))
		default:
			return nil, nil, fmt.Errorf("%w: UNION kind %d",
				ErrUnsupported, .Union[-1])
		}
	}

	if len(.Parts) > 1 {
		var  error
		,  = .orderPage(, &.Parts[len(.Parts)-1].Ret)
		if  != nil {
			return nil, nil, 
		}
	}

	return , , nil
}

// runPart executes one UNION branch: clauses, then the final projection.
func ( *exec) (
	 *gqlparser.QueryPart,  bool,
) ([]outRow, []string, error) {
	 := []row{newRow()}

	for ,  := range .Clauses {
		var  error
		switch n := .(type) {
		case *gqlparser.Match:
			,  = .match(, )
		case *gqlparser.With:
			,  = .with(, )
		default:
			 = fmt.Errorf("%w: clause %T", ErrUnsupported, )
		}
		if  != nil {
			return nil, nil, 
		}
	}

	return .project(, &.Ret, )
}

// match applies one MATCH / OPTIONAL MATCH clause.
func ( *exec) ( []row,  *gqlparser.Match) ([]row, error) {
	var  []row

	for ,  := range  {
		// relationship uniqueness is scoped to one MATCH clause
		.used = nil

		 := []row{}
		for  := range .Patterns {
			var  error
			,  = .expandPattern(, &.Patterns[], )
			if  != nil {
				return nil, 
			}
		}

		if .Where != nil {
			var  error
			,  = .filter(, .Where)
			if  != nil {
				return nil, 
			}
		}

		if len() == 0 && .Optional {
			// left-join semantics: keep the row, null the clause's variables
			 := .clone()
			for ,  := range patternVars(.Patterns) {
				if ,  := .vals[]; ! {
					.vals[] = Null()
				}
			}
			 = append(, )
			continue
		}

		 = append(, ...)
	}

	return , nil
}

// with applies a projection boundary (WITH / RETURN ... NEXT / FILTER).
func ( *exec) ( []row,  *gqlparser.With) ([]row, error) {
	, ,  := .project(, &.Proj, true)
	if  != nil {
		return nil, 
	}

	 := make([]row, 0, len())
	for ,  := range  {
		 := newRow()
		for ,  := range  {
			.vals[] = .out[]
		}
		 = append(, )
	}

	if .Where != nil {
		,  = .filter(, .Where)
		if  != nil {
			return nil, 
		}
	}

	return , nil
}

// expandPattern matches one linear path pattern, joining onto rows.
func ( *exec) (
	 []row,  *gqlparser.Pattern,  int,
) ([]row, error) {
	 := .Start.Var
	if  == "" {
		 = fmt.Sprintf("__n%d_0", )
	}

	,  := .matchNode(, &.Start, )
	if  != nil {
		return nil, 
	}

	 := 
	for  := range .Hops {
		 := &.Hops[]
		 := .Node.Var
		if  == "" {
			 = fmt.Sprintf("__n%d_%d", , +1)
		}

		,  = .matchHop(, , &.Rel, .Rel.Var,
			&.Node, )
		if  != nil {
			return nil, 
		}
		 = 
	}

	return , nil
}

// matchNode joins the node pattern np, binding varName.
func ( *exec) (
	 []row,  *gqlparser.NodePat,  string,
) ([]row, error) {
	var  []row

	for ,  := range  {
		if ,  := .vals[];  {
			if .kind != kNode {
				return nil, fmt.Errorf("variable %q is not a node", )
			}
			if nodeMatches(.node, ) {
				 = append(, )
			}
			continue
		}

		for ,  := range .nodeCandidates() {
			 := .store.nodes[]
			if !nodeMatches(, ) {
				continue
			}
			 = append(, .bind(, nodeVal()))
		}
	}

	return , nil
}

// matchHop expands one relationship step from srcVar.
func ( *exec) (
	 []row,  string,  *gqlparser.RelPat,  string,
	 *gqlparser.NodePat,  string,
) ([]row, error) {
	if .Length != nil {
		return nil, fmt.Errorf("%w: variable-length relationships", ErrUnsupported)
	}

	var  []row

	for ,  := range  {
		,  := .vals[]
		if ! || .kind != kNode {
			return nil, fmt.Errorf("variable %q is not a node", )
		}
		 := .store.byID[.node.id]

		for ,  := range .store.neighbors(, .Dir) {
			if !.relMatches(, ) {
				continue
			}
			if ,  := .used[.idx];  {
				continue
			}

			// rel variable already bound: constraint, not a binding
			if  != "" {
				if ,  := .vals[];  {
					if .kind != kRel || .rel.idx != .idx {
						continue
					}
				}
			}

			 := .other()
			 := .store.nodes[]
			if !nodeMatches(, ) {
				continue
			}
			if ,  := .vals[];  {
				if .kind != kNode || .node.id != .id {
					continue
				}
			}

			 := .markUsed(.idx)
			if  != "" {
				if ,  := .vals[]; ! {
					 = .bind(, relVal())
				}
			}
			if ,  := .vals[]; ! {
				 = .bind(, nodeVal())
			}
			 = append(, )
		}
	}

	return , nil
}

// nodeCandidates returns the label-scan candidates for a node pattern.
func ( *exec) ( *gqlparser.NodePat) []int {
	if len(.Labels) == 0 {
		 := make([]int, len(.store.nodes))
		for  := range .store.nodes {
			[] = 
		}
		return 
	}
	return .store.byLabel[.Labels[0]]
}

// nodeMatches applies label and inline-property filters.
func nodeMatches( *node,  *gqlparser.NodePat) bool {
	for ,  := range .Labels {
		if .label !=  {
			return false
		}
	}
	for ,  := range .Props {
		if !propMatches(.props, .Key, .Val) {
			return false
		}
	}
	return true
}

// relMatches applies type and inline-property filters.
func ( *exec) ( *rel,  *gqlparser.RelPat) bool {
	if len(.Types) > 0 {
		 := false
		for ,  := range .Types {
			if .typ ==  {
				 = true
				break
			}
		}
		if ! {
			return false
		}
	}
	for ,  := range .Props {
		if !propMatches(.props, .Key, .Val) {
			return false
		}
	}
	return true
}

// propMatches is inline-property equality: an absent property equals only a
// null literal.
func propMatches(
	 map[string]Value,  string,  gqlparser.Literal,
) bool {
	,  := []
	 := litVal()
	if ! {
		return .kind == kNull
	}
	return eqVal(, )
}

// filter keeps the rows whose WHERE expression is true.
func ( *exec) ( []row,  gqlparser.Expr) ([]row, error) {
	 := make([]row, 0, len())
	for ,  := range  {
		,  := .eval(, )
		if  != nil {
			return nil, 
		}
		if truth() {
			 = append(, )
		}
	}
	return , nil
}

// project applies a projection (final or WITH) with ORDER BY / SKIP / LIMIT.
func ( *exec) (
	 []row,  *gqlparser.Projection,  bool,
) ([]outRow, []string, error) {
	, ,  := .projectionItems(, )
	if  != nil {
		return nil, nil, 
	}

	 := false
	for ,  := range  {
		if isAggregate() {
			 = true
			continue
		}
		if containsAggregate() {
			return nil, nil, fmt.Errorf(
				"%w: aggregate nested in an expression", ErrUnsupported)
		}
	}

	if  {
		return .projectAggregate(, , , , )
	}

	 := make([]outRow, 0, len())
	for ,  := range  {
		 := make(map[string]Value, len())
		for ,  := range  {
			,  := .eval(, )
			if  != nil {
				return nil, nil, 
			}
			[[]] = 
		}
		 = append(, outRow{src: , out: })
	}

	if .Distinct {
		 = dedupeOut()
	}
	if  {
		,  = .orderPage(, )
		if  != nil {
			return nil, nil, 
		}
	}

	return , , nil
}

// projectionItems expands `*` and computes output column names.
func ( *exec) (
	 []row,  *gqlparser.Projection,
) ([]string, []gqlparser.Expr, error) {
	var  []string
	var  []gqlparser.Expr

	if .Star {
		 := .scopeOf()
		for ,  := range  {
			 = append(, )
			 = append(, &gqlparser.Var{Name: })
		}
	}

	for ,  := range .Items {
		 := .Alias
		if  == "" {
			if ,  := .Expr.(*gqlparser.Var);  {
				 = .Name
			}
		}
		if  == "" {
			 = fmt.Sprintf("expr_%d", +1)
		}
		if ,  := indexOf(, );  {
			return nil, nil, fmt.Errorf(
				"%w: duplicate output column %q", ErrUnsupported, )
		}
		 = append(, )
		 = append(, .Expr)
	}

	if len() == 0 {
		return nil, nil, fmt.Errorf("%w: empty projection", ErrUnsupported)
	}
	return , , nil
}

// projectAggregate runs an implicit GROUP BY over the non-aggregate items.
func ( *exec) (
	 []row,  []string,  []gqlparser.Expr,
	 *gqlparser.Projection,  bool,
) ([]outRow, []string, error) {
	type  struct {
		  row
		 []row
	}

	 := make(map[string]*)
	var  []string

	for ,  := range  {
		var  strings.Builder
		for ,  := range  {
			if isAggregate() {
				.WriteString("#")
				.WriteString(fmt.Sprint())
				.WriteByte(':')
				continue
			}
			,  := .eval(, )
			if  != nil {
				return nil, nil, 
			}
			.WriteString(.key())
			.WriteByte(0)
		}
		 := .String()
		,  := []
		if ! {
			 = &{: }
			[] = 
			 = append(, )
		}
		. = append(., )
	}

	 := make([]outRow, 0, len())
	for ,  := range  {
		 := []
		 := make(map[string]Value, len())
		for ,  := range  {
			if isAggregate() {
				,  := .evalAggregate(., .(*gqlparser.Func))
				if  != nil {
					return nil, nil, 
				}
				[[]] = 
				continue
			}
			,  := .eval(., )
			if  != nil {
				return nil, nil, 
			}
			[[]] = 
		}
		 = append(, outRow{src: ., out: })
	}

	if .Distinct {
		 = dedupeOut()
	}
	if  {
		var  error
		,  = .orderPage(, )
		if  != nil {
			return nil, nil, 
		}
	}

	return , , nil
}

// evalAggregate computes one aggregate function over a group.
func ( *exec) ( []row,  *gqlparser.Func) (Value, error) {
	 := strings.ToLower(.Name)

	switch  {
	case "count":
		if .Star {
			return Int(int64(len())), nil
		}
		if len(.Args) != 1 {
			return Null(), fmt.Errorf("%w: count() arity", ErrUnsupported)
		}
		var  int64
		 := make(map[string]struct{})
		for ,  := range  {
			,  := .eval(, .Args[0])
			if  != nil {
				return Null(), 
			}
			if .kind == kNull {
				continue
			}
			if .Distinct {
				 := .key()
				if ,  := [];  {
					continue
				}
				[] = struct{}{}
			}
			++
		}
		return Int(), nil

	case "sum", "avg", "min", "max":
		if len(.Args) != 1 {
			return Null(), fmt.Errorf("%w: %s() arity", ErrUnsupported, )
		}
		var  []Value
		for ,  := range  {
			,  := .eval(, .Args[0])
			if  != nil {
				return Null(), 
			}
			if .kind == kNull {
				continue
			}
			if !.IsNum() {
				continue
			}
			 = append(, )
		}
		switch  {
		case "sum":
			if len() == 0 {
				return Int(0), nil
			}
			 := true
			var  float64
			var  int64
			for ,  := range  {
				if .kind == kInt {
					 += .i
				} else {
					 = false
				}
				,  := .Float64()
				 += 
			}
			if  {
				return Int(), nil
			}
			return Float(), nil
		case "avg":
			if len() == 0 {
				return Null(), nil
			}
			var  float64
			for ,  := range  {
				,  := .Float64()
				 += 
			}
			return Float( / float64(len())), nil
		case "min":
			if len() == 0 {
				return Null(), nil
			}
			 := [0]
			for ,  := range [1:] {
				if ,  := compare(, );  &&  < 0 {
					 = 
				}
			}
			return , nil
		case "max":
			if len() == 0 {
				return Null(), nil
			}
			 := [0]
			for ,  := range [1:] {
				if ,  := compare(, );  &&  > 0 {
					 = 
				}
			}
			return , nil
		}

	case "collect":
		if len(.Args) != 1 {
			return Null(), fmt.Errorf("%w: collect() arity", ErrUnsupported)
		}
		 := make([]Value, 0, len())
		 := make(map[string]struct{})
		for ,  := range  {
			,  := .eval(, .Args[0])
			if  != nil {
				return Null(), 
			}
			if .kind == kNull {
				continue
			}
			if .Distinct {
				 := .key()
				if ,  := [];  {
					continue
				}
				[] = struct{}{}
			}
			 = append(, )
		}
		return List(), nil
	}

	return Null(), fmt.Errorf("%w: aggregate %q", ErrUnsupported, .Name)
}

// orderPage applies ORDER BY, then SKIP/OFFSET and LIMIT.
func ( *exec) (
	 []outRow,  *gqlparser.Projection,
) ([]outRow, error) {
	if len(.OrderBy) > 0 {
		type  struct {
			  outRow
			 []Value
		}

		 := make([], len())
		for  := range  {
			[]. = []
			[]. = make([]Value, len(.OrderBy))
			for ,  := range .OrderBy {
				,  := .sortKey([], .Expr)
				if  != nil {
					return nil, 
				}
				[].[] = 
			}
		}

		sort.SliceStable(, func(,  int) bool {
			for ,  := range .OrderBy {
				 := orderCompare([].[], [].[])
				if  == 0 {
					continue
				}
				if .Desc {
					return  > 0
				}
				return  < 0
			}
			return false
		})

		for  := range  {
			[] = [].
		}
	}

	if .Skip != nil {
		 := int(*.Skip)
		if  >= len() {
			 = nil
		} else {
			 = [:]
		}
	}
	if .Limit != nil {
		 := int(*.Limit)
		if  < len() {
			 = [:]
		}
	}

	return , nil
}

// sortKey resolves one ORDER BY key: an output column alias first, then the
// source row scope.
func ( *exec) ( outRow,  gqlparser.Expr) (Value, error) {
	if ,  := .(*gqlparser.Var);  {
		if ,  := .out[.Name];  {
			return , nil
		}
	}
	if .src.vals == nil {
		return Null(), fmt.Errorf(
			"%w: ORDER BY after UNION may only reference output columns",
			ErrUnsupported)
	}
	return .eval(.src, )
}

// scopeOf returns the visible variable names (sorted, hidden ones excluded).
func ( *exec) ( []row) []string {
	if len() == 0 {
		return nil
	}
	 := make([]string, 0, len([0].vals))
	for  := range [0].vals {
		if strings.HasPrefix(, "__") {
			continue
		}
		 = append(, )
	}
	sort.Strings()
	return 
}

// dedupeOut removes duplicate projected rows, keeping the first occurrence.
func dedupeOut( []outRow) []outRow {
	 := make(map[string]struct{}, len())
	 := [:0]
	for ,  := range  {
		 := make([]string, 0, len(.out))
		for  := range .out {
			 = append(, )
		}
		sort.Strings()
		var  strings.Builder
		for ,  := range  {
			.WriteString()
			.WriteByte(0)
			.WriteString(.out[].key())
			.WriteByte(0)
		}
		 := .String()
		if ,  := [];  {
			continue
		}
		[] = struct{}{}
		 = append(, )
	}
	return 
}

// patternVars lists the non-hidden variables a pattern introduces, in order.
func patternVars( []gqlparser.Pattern) []string {
	 := make(map[string]struct{})
	var  []string
	 := func( string) {
		if  == "" || strings.HasPrefix(, "__") {
			return
		}
		if ,  := [];  {
			return
		}
		[] = struct{}{}
		 = append(, )
	}

	for  := range  {
		 := &[]
		(.Start.Var)
		for ,  := range .Hops {
			(.Rel.Var)
			(.Node.Var)
		}
	}
	return 
}

// isAggregate reports whether e is an aggregate function call.
func isAggregate( gqlparser.Expr) bool {
	,  := .(*gqlparser.Func)
	if ! {
		return false
	}
	switch strings.ToLower(.Name) {
	case "count", "sum", "avg", "min", "max", "collect":
		return true
	}
	return false
}

// containsAggregate reports whether e contains an aggregate call anywhere.
func containsAggregate( gqlparser.Expr) bool {
	 := false
	walkExpr(, func( gqlparser.Expr) bool {
		if isAggregate() {
			 = true
			return false
		}
		return true
	})
	return 
}

// walkExpr visits an expression tree (a local, non-mutating copy of the
// upstream walker that does not descend into pattern subqueries).
func walkExpr( gqlparser.Expr,  func(gqlparser.Expr) bool) {
	if  == nil || !() {
		return
	}
	switch n := .(type) {
	case *gqlparser.Unary:
		(.Expr, )
	case *gqlparser.Binary:
		(.LHS, )
		(.RHS, )
	case *gqlparser.Func:
		for ,  := range .Args {
			(, )
		}
	case *gqlparser.ListExpr:
		for ,  := range .Elems {
			(, )
		}
	case *gqlparser.In:
		(.Expr, )
		(.List, )
	case *gqlparser.IsNull:
		(.Expr, )
	case *gqlparser.IsTruth:
		(.Expr, )
	case *gqlparser.IsTyped:
		(.Expr, )
	case *gqlparser.ListPred:
		(.List, )
		(.Pred, )
	case *gqlparser.Case:
		(.Operand, )
		for ,  := range .Whens {
			(.Cond, )
			(.Result, )
		}
		(.Else, )
	case *gqlparser.Index:
		(.Base, )
		(.Idx, )
	case *gqlparser.Slice:
		(.Base, )
		(.From, )
		(.To, )
	case *gqlparser.PropOf:
		(.Base, )
	case *gqlparser.MapLit:
		for ,  := range .Fields {
			(.Val, )
		}
	}
}

func sameStrings(,  []string) bool {
	if len() != len() {
		return false
	}
	for  := range  {
		if [] != [] {
			return false
		}
	}
	return true
}

// explainQuery renders a short structural plan for EXPLAIN/PROFILE.
func explainQuery( *gqlparser.Query) string {
	var  strings.Builder
	.WriteString("native netgraph executor (in-memory, no planner)\n")
	for ,  := range .Parts {
		fmt.Fprintf(&, "part %d:\n", +1)
		for ,  := range .Clauses {
			switch n := .(type) {
			case *gqlparser.Match:
				 := ""
				if .Optional {
					 = "OPTIONAL "
				}
				fmt.Fprintf(&, "  %sMATCH %d pattern(s)", , len(.Patterns))
				if .Where != nil {
					.WriteString(" WHERE <expr>")
				}
				.WriteString("\n")
			case *gqlparser.With:
				fmt.Fprintf(&, "  WITH %d item(s)\n", len(.Proj.Items))
			}
		}
		fmt.Fprintf(&, "  RETURN %d item(s)\n", len(.Ret.Items))
	}
	return .String()
}

// label constants of the graph model.
const (
	labelMachine = "Machine"
	labelState   = "State"
	labelTag     = "Tag"
)

// node is one queryable vertex.
type node struct {
	// id is the dominikbraun/graph vertex hash.
	id    string
	label string
	props map[string]Value
}

// rel is one logical relationship. A single dominikbraun/graph edge may
// expand into several (state relations are lists on one edge).
type rel struct {
	idx    int
	from   int // source node index
	to     int // target node index
	fromID string
	toID   string
	typ    string
	props  map[string]Value
}

// store is a read-only snapshot view of the in-memory graph instance.
type store struct {
	nodes []*node
	byID  map[string]int
	rels  []*rel
	out   [][]*rel // node index -> outgoing rels
	in    [][]*rel // node index -> incoming rels

	byLabel map[string][]int
}

// newStore snapshots g into a queryable store. The caller passes an already
// cloned graph, so no locking is needed.
func newStore( *amgraph.Graph) (*store, error) {
	if  == nil || .G == nil {
		return nil, fmt.Errorf("%w: nil graph", ErrGraph)
	}

	,  := .G.AdjacencyMap()
	if  != nil {
		return nil, fmt.Errorf("%w: %w", ErrGraph, )
	}

	 := &store{
		byID:    make(map[string]int, len()),
		byLabel: make(map[string][]int),
	}

	// vertices; the adjacency map covers isolated ones too
	for  := range  {
		,  := .G.Vertex()
		if  != nil {
			continue
		}
		.addVertex(, , .Machines)
	}

	// edges, expanded into logical relationships
	for ,  := range  {
		,  := .byID[]
		if ! {
			continue
		}
		for ,  := range  {
			,  := .byID[]
			if ! {
				continue
			}
			,  := .Properties.Data.(*amgraph.EdgeData)
			.addEdgeData(, , )
		}
	}

	// adjacency indices
	.out = make([][]*rel, len(.nodes))
	.in = make([][]*rel, len(.nodes))
	for ,  := range .rels {
		.out[.from] = append(.out[.from], )
		.in[.to] = append(.in[.to], )
	}

	return , nil
}

// addVertex appends one vertex in the graph model.
func ( *store) (
	 string,  *amgraph.Vertex,  map[string]*amgraph.Machine,
) {
	if  == nil {
		return
	}

	 := &node{id: , props: make(map[string]Value, 6)}
	switch {
	case .StateName != "":
		.label = labelState
		.props["mach"] = Str(.MachId)
		.props["name"] = Str(.StateName)
	case .TagName != "":
		.label = labelTag
		.props["mach"] = Str(.MachId)
		.props["name"] = Str(.TagName)
		.props["value"] = Str(amtypes.TagValue(.TagName))
	default:
		.label = labelMachine
		.props["id"] = Str(.MachId)
	}

	if  := [.MachId];  != nil && .Serialized != nil {
		switch .label {
		case labelMachine:
			.props["id"] = Str(.ID)
			.props["parent"] = Str(.Parent)
			.props["schema_hash"] = Str(.SchemaHash)
			.props["mtime_sum"] = Int(int64(.MTimeSum))
			.props["queue_tick"] = Int(int64(.QueueTick))
			.props["mach_tick"] = Int(int64(.MachineTick))
		case labelState:
			.props["mach"] = Str(.ID)
			.props["tick"] = Int(0)
			.props["active"] = Bool(false)
			if ,  := indexOf(.StateNames, .StateName);  &&
				 < len(.Time) {
				.props["tick"] = Int(int64(.Time[]))
				.props["active"] = Bool(am.IsActiveTick(.Time[]))
			}
		case labelTag:
			.props["mach"] = Str(.ID)
		}
	}

	 := len(.nodes)
	.nodes = append(.nodes, )
	.byID[.id] = 
	.byLabel[.label] = append(.byLabel[.label], )
}

// addEdgeData appends the logical relationships carried by one edge between
// two node indices.
func ( *store) (,  int,  *amgraph.EdgeData) {
	if  == nil {
		return
	}
	,  := .nodes[], .nodes[]

	 := func( string,  map[string]Value) {
		.rels = append(.rels, &rel{
			idx:    len(.rels),
			from:   ,
			to:     ,
			fromID: .id,
			toID:   .id,
			typ:    ,
			props:  ,
		})
	}

	if .MachHas != nil {
		 := make(map[string]Value, 3)
		["auto"] = Bool(.MachHas.Auto)
		["multi"] = Bool(.MachHas.Multi)
		("HAS", )
	}
	if .MachHasTag {
		("HAS_TAG", nil)
	}
	if .MachChildOf {
		("CHILD_OF", nil)
	}
	if .MachConnectedTo {
		("CONNECTED_TO", nil)
	}
	for ,  := range .StateRelation {
		(amtypes.RelLabel(.RelType), nil)
	}
}

// neighbors returns the relationships incident to node in the traversal
// direction dir, deduplicated (DIR_BOTH sees a self-loop once).
func ( *store) ( int,  gqlparser.Dir) []*rel {
	switch  {
	case gqlparser.DirOut:
		return .out[]
	case gqlparser.DirIn:
		return .in[]
	default:
		 := make(map[*rel]struct{}, len(.out[])+len(.in[]))
		 := make([]*rel, 0, len(.out[])+len(.in[]))
		for ,  := range .out[] {
			[] = struct{}{}
			 = append(, )
		}
		for ,  := range .in[] {
			if ,  := [];  {
				continue
			}
			 = append(, )
		}
		return 
	}
}

// other returns the far endpoint of r seen from node index idx.
func ( *rel) ( int) int {
	if .from ==  {
		return .to
	}
	return .from
}

// indexOf returns the index of v in list.
func indexOf[ comparable]( [],  ) (int, bool) {
	for  := range  {
		if [] ==  {
			return , true
		}
	}
	return 0, false
}

// vKind discriminates a runtime [Value].
type vKind uint8

const (
	kNull vKind = iota
	kBool
	kInt
	kFloat
	kString
	kList
	kMap
	kNode
	kRel
)

// Value is a GQL runtime value: a scalar, a list/map, or a graph element
// (node/relationship). It is the unit rows are made of.
type Value struct {
	kind vKind
	b    bool
	i    int64
	f    float64
	s    string
	list []Value
	mp   map[string]Value
	node *node
	rel  *rel
}

// Null is the null value.
func () Value { return Value{kind: kNull} }

// Bool is a boolean value.
func ( bool) Value { return Value{kind: kBool, b: } }

// Int is an integer value.
func ( int64) Value { return Value{kind: kInt, i: } }

// Float is a float value.
func ( float64) Value { return Value{kind: kFloat, f: } }

// Str is a string value.
func ( string) Value { return Value{kind: kString, s: } }

// List is a list value.
func ( []Value) Value { return Value{kind: kList, list: } }

// Map is a map value.
func ( map[string]Value) Value { return Value{kind: kMap, mp: } }

func nodeVal( *node) Value { return Value{kind: kNode, node: } }
func relVal( *rel) Value   { return Value{kind: kRel, rel: } }

// IsNull reports whether v is null (also true for the zero Value).
func ( Value) () bool { return .kind == kNull }

// IsNum reports whether v is an int or float.
func ( Value) () bool { return .kind == kInt || .kind == kFloat }

// Float64 returns v as a float64; ok is false for non-numerics.
func ( Value) () (float64, bool) {
	switch .kind {
	case kInt:
		return float64(.i), true
	case kFloat:
		return .f, true
	}
	return 0, false
}

// String renders v for error messages.
func ( Value) () string {
	switch .kind {
	case kNull:
		return "null"
	case kBool:
		return strconv.FormatBool(.b)
	case kInt:
		return strconv.FormatInt(.i, 10)
	case kFloat:
		return strconv.FormatFloat(.f, 'g', -1, 64)
	case kString:
		return strconv.Quote(.s)
	case kList:
		 := make([]string, len(.list))
		for ,  := range .list {
			[] = .()
		}
		return "[" + strings.Join(, ", ") + "]"
	case kMap:
		 := make([]string, 0, len(.mp))
		for  := range .mp {
			 = append(, )
		}
		sort.Strings()
		 := make([]string, 0, len())
		for ,  := range  {
			 = append(, +": "+.mp[].())
		}
		return "{" + strings.Join(, ", ") + "}"
	case kNode:
		return "node(" + .node.id + ")"
	case kRel:
		return "rel(" + .rel.typ + ")"
	}
	return "?"
}

// Any converts v to a plain Go value for JSON/msgpack encoding.
func ( Value) () any {
	switch .kind {
	case kNull:
		return nil
	case kBool:
		return .b
	case kInt:
		return .i
	case kFloat:
		return .f
	case kString:
		return .s
	case kList:
		if .list == nil {
			return []any{}
		}
		 := make([]any, len(.list))
		for ,  := range .list {
			[] = .()
		}
		return 
	case kMap:
		 := make(map[string]any, len(.mp))
		for ,  := range .mp {
			[] = .()
		}
		return 
	case kNode:
		 := make(map[string]any, len(.node.props)+1)
		for ,  := range .node.props {
			[] = .()
		}
		["label"] = .node.label
		return 
	case kRel:
		 := make(map[string]any, len(.rel.props)+3)
		for ,  := range .rel.props {
			[] = .()
		}
		["type"] = .rel.typ
		["start"] = .rel.fromID
		["end"] = .rel.toID
		return 
	}
	return nil
}

// key returns a canonical grouping/distinct key. Numbers share one key space
// across int and float (GQL numeric equality), so Int(1) and Float(1) group
// together.
func ( Value) () string {
	switch .kind {
	case kNull:
		return "z"
	case kBool:
		return "b:" + strconv.FormatBool(.b)
	case kInt:
		return "d:" + strconv.FormatUint(math.Float64bits(float64(.i)), 16)
	case kFloat:
		return "d:" + strconv.FormatUint(math.Float64bits(.f), 16)
	case kString:
		return "s:" + .s
	case kList:
		 := make([]string, len(.list))
		for ,  := range .list {
			[] = .()
		}
		return "l:[" + strings.Join(, ",") + "]"
	case kMap:
		 := make([]string, 0, len(.mp))
		for  := range .mp {
			 = append(, )
		}
		sort.Strings()
		var  strings.Builder
		.WriteString("m:{")
		for ,  := range  {
			.WriteString()
			.WriteByte(':')
			.WriteString(.mp[].())
			.WriteByte(',')
		}
		.WriteString("}")
		return .String()
	case kNode:
		return "n:" + .node.id
	case kRel:
		return "r:" + strconv.Itoa(.rel.idx)
	}
	return "?"
}

// compare is the three-valued comparison behind =, <>, <, <=, >, >=. ok is
// false when either side is null or the types are not comparable. Numbers
// compare across int/float by coercing through float64 (like the reference
// engine).
func compare(,  Value) (int, bool) {
	if .kind == kNull || .kind == kNull {
		return 0, false
	}
	if .IsNum() && .IsNum() {
		,  := .Float64()
		,  := .Float64()
		switch {
		case  < :
			return -1, true
		case  > :
			return 1, true
		}
		return 0, true
	}
	if .kind != .kind {
		return 0, false
	}
	switch .kind {
	case kString:
		return strings.Compare(.s, .s), true
	case kBool:
		switch {
		case .b == .b:
			return 0, true
		case !.b:
			return -1, true
		}
		return 1, true
	case kNode:
		return strings.Compare(.node.id, .node.id), true
	case kRel:
		switch {
		case .rel.idx < .rel.idx:
			return -1, true
		case .rel.idx > .rel.idx:
			return 1, true
		}
		return 0, true
	}
	return 0, false
}

// orderCompare is a total order for ORDER BY: null sorts last, then numbers,
// strings, booleans, lists, maps, graph elements; incomparable values of the
// same rank sort stable.
func orderCompare(,  Value) int {
	 := func( Value) int {
		switch .kind {
		case kNull:
			return 9
		case kInt, kFloat:
			return 0
		case kString:
			return 1
		case kBool:
			return 2
		case kList:
			return 3
		case kMap:
			return 4
		case kNode:
			return 5
		case kRel:
			return 6
		}
		return 7
	}
	,  := (), ()
	if  !=  {
		if  <  {
			return -1
		}
		return 1
	}
	if ,  := compare(, );  {
		return 
	}
	return strings.Compare(.key(), .key())
}

// truth reports whether v is the boolean true; null and non-booleans are
// false in a WHERE position.
func truth( Value) bool { return .kind == kBool && .b }