ir

type AggregateExpr struct {
	// OutputName is the variable name assigned to the aggregate result.
	OutputName string
	// Function is the aggregate function name (e.g. "count", "sum", "avg").
	Function string
	// Argument is the expression argument to the aggregate function. An empty
	// string corresponds to count(*).
	Argument string
	// ArgumentExpr is the parsed AST for the aggregate argument, when available.
	// Non-nil when the argument is a non-trivial expression (property access,
	// function call, …); when nil, callers fall back to schema lookup keyed on
	// Argument or supply the constant Null. count(*) keeps ArgumentExpr == nil.
	ArgumentExpr ast.Expression
	// SecondArgExpr captures the second argument of two-arg aggregates
	// (percentileCont, percentileDisc). The value is constant across the
	// aggregation (it parameterises the factory, not the per-row Step) and
	// is evaluated once at physical-build time, typically from a parameter
	// or a literal.
	SecondArgExpr ast.Expression
	// Distinct indicates whether the DISTINCT qualifier is applied inside the
	// aggregate (e.g. count(DISTINCT n)).
	Distinct bool
}

type AllNodesScan struct {
	// NodeVar is the variable name bound to each scanned node.
	NodeVar string
}

type AntiSemiApply struct {
	// Outer is the driving subplan.
	Outer LogicalPlan
	// Inner is the correlated non-existence-check subplan; its leftmost leaf
	// must be an [Argument] whose Tag equals [AntiSemiApply.ArgTag].
	Inner LogicalPlan
	// ArgTag is the tag shared with the inner-side Argument leaf so that the
	// physical builder can route the matching exec.Argument instance.
	ArgTag uint32
}

type Apply struct {
	// Outer is the driving (left) subplan.
	Outer LogicalPlan
	// Inner is the correlated (right) subplan.
	Inner LogicalPlan
}

type Argument struct {
	// Variables holds the variable names that are injected from the outer scope.
	Variables []string
	// Tag uniquely identifies this Argument node so the physical builder can
	// route the matching [exec.Argument] instance from an enclosing
	// [CorrelatedApply] or [OptionalApply]. Tags are assigned at construction
	// time and are stable for the lifetime of the node.
	Tag uint32
}

type Bound struct {
	// Value is the opaque string representation of the bound expression.
	Value string
	// Inclusive reports whether the bound is inclusive (≤/≥) or exclusive (</>).
	Inclusive bool
}

type ConstraintKind uint8

type CorrelatedApply struct {
	// Outer is the driving (left) subplan.
	Outer LogicalPlan
	// Inner is the correlated (right) subplan; its leftmost leaf must be an
	// [Argument] whose Tag equals [CorrelatedApply.ArgTag].
	Inner LogicalPlan
	// ArgTag is the tag shared with the inner-side Argument leaf so that the
	// physical builder can route the matching exec.Argument instance.
	ArgTag uint32
}

type CreateConstraint struct {
	// Name is the user-defined constraint name.
	Name string
	// Label is the node label to which the constraint applies.
	Label string
	// Property is the node property key constrained.
	Property string
	// Kind is the constraint type (unique or not-null).
	Kind ConstraintKind
	// IfNotExists suppresses an error when the constraint already exists.
	IfNotExists bool
}

type CreateIndex struct {
	// Name is the user-defined index name, or empty for an auto-named index.
	Name string
	// Label is the node label on which the index is built.
	Label string
	// Property is the node property key indexed.
	Property string
	// Type is the backing index kind (hash or btree).
	Type IndexType
	// IfNotExists suppresses ErrIndexExists when the index already exists.
	IfNotExists bool
}

type CreateNode struct {
	// NodeVar is the variable name bound to the newly created node.
	NodeVar string
	// Labels is the list of labels assigned to the new node.
	Labels []string
	// Properties is the opaque string representation of the property map
	// expression (e.g. "{name: 'Alice'}").
	Properties string
	// PropertiesExpr is the parsed AST for the property map, when available.
	// Non-nil when the property map contains non-literal expressions (variable
	// references, property accesses, arithmetic) that must be evaluated at
	// runtime against the current row. The physical builder uses PropertiesExpr
	// when non-nil to construct a per-row evaluation closure; nil means all
	// values were literals and Properties (the string form) is sufficient.
	PropertiesExpr ast.Expression
	// Child is the driving subplan.
	Child LogicalPlan
}

type CreateRelationship struct {
	// StartVar is the already-bound source node variable.
	StartVar string
	// EndVar is the already-bound destination node variable.
	EndVar string
	// RelVar is the variable name bound to the newly created relationship.
	RelVar string
	// RelType is the relationship type.
	RelType string
	// Properties is the opaque string representation of the property map
	// expression.
	Properties string
	// PropertiesExpr is the parsed AST for the property map, when available.
	// Non-nil when the property map contains non-literal expressions that must
	// be evaluated at runtime against the current row. See CreateNode.PropertiesExpr.
	PropertiesExpr ast.Expression
	// Child is the driving subplan.
	Child LogicalPlan
}

type DeleteNode struct {
	// NodeVar is the already-bound node variable to delete.
	NodeVar string
	// TargetExpr is the parsed AST for the delete target when the target
	// is not a bare variable (e.g. `DELETE friends[$i]`, `DELETE map.key`,
	// `DELETE coll[0]`). When non-nil the exec builder uses it to evaluate
	// the target per row; the resulting NodeValue / IntegerValue identifies
	// the node to delete.
	TargetExpr ast.Expression
	// Child is the driving subplan.
	Child LogicalPlan
}

type DeleteRelationship struct {
	// RelVar is the already-bound relationship variable to delete.
	RelVar string
	// Child is the driving subplan.
	Child LogicalPlan
}

type DetachDelete struct {
	// NodeVar is the already-bound node variable to delete.
	NodeVar string
	// TargetExpr is the parsed AST for the delete target when the target
	// is not a bare variable (e.g. `DETACH DELETE friends[$i]`,
	// `DETACH DELETE map.key`). Same role as DeleteNode.TargetExpr.
	TargetExpr ast.Expression
	// Child is the driving subplan.
	Child LogicalPlan
}

type Direction uint8

type Distinct struct {
	// Child is the subplan whose duplicate rows are removed.
	Child LogicalPlan
}

type DropConstraint struct {
	// Name is the constraint name to drop.
	Name string
	// Label is the node label associated with the constraint.
	// May be empty for DROP CONSTRAINT by name only.
	Label string
	// Property is the constrained property key.
	// May be empty for DROP CONSTRAINT by name only.
	Property string
	// Kind is the constraint type (unique or not-null).
	Kind ConstraintKind
	// IfExists suppresses an error when the constraint is absent.
	IfExists bool
}

type DropIndex struct {
	// Name is the index name to drop.
	Name string
	// IfExists suppresses ErrIndexNotFound when the index is absent.
	IfExists bool
}

type Eager struct {
	// Child is the subplan to materialise.
	Child LogicalPlan
}

type EagerAggregation struct {
	// GroupBy is the ordered list of grouping key variable names.
	GroupBy []string
	// GroupByExprs holds the parsed AST expression for each grouping key, in
	// the same order as GroupBy. Entries may be nil for legacy callers that
	// only supplied string keys; non-nil entries enable property-access and
	// complex expression evaluation at execution time.
	GroupByExprs []ast.Expression
	// Aggregates is the list of aggregate expressions computed per group.
	Aggregates []AggregateExpr
	// Child is the subplan whose rows are aggregated.
	Child LogicalPlan
}

type Expand struct {
	// FromVar is the already-bound source node variable.
	FromVar string
	// RelVar is the variable name bound to the traversed relationship.
	RelVar string
	// RelTypes is the list of allowed relationship types. An empty slice means
	// any type is accepted.
	RelTypes []string
	// Direction is the traversal direction relative to FromVar.
	Direction Direction
	// ToVar is the variable name bound to the destination node.
	ToVar string
	// SiblingRelVars carries the names of relationship variables already bound
	// by earlier hops in the SAME MATCH pattern. The physical builder
	// translates each name to its schema column and passes the column set as
	// the Expand operator's relationship-isomorphism (cyphermorphism) guard,
	// so every anonymous or named relationship in one pattern maps to a
	// distinct edge per openCypher 9 §3.2.2.
	SiblingRelVars []string
	// PathVar, when non-empty, is the named-path variable this Expand
	// step participates in. Set by applyPathVar for mixed paths
	// (Expand + VLE) so the physical builder can record this hop's
	// (src, edge, dst) triplet as a leading segment in the same
	// pathVarMeta entry the downstream VLE updates — closing the
	// "missing leading hop" path-reconstruction gap (Match6 [14]).
	PathVar string
	// Child is the subplan that produces FromVar.
	Child LogicalPlan
}

type IndexType uint8

type KVAction struct {
	Key   string
	Value string // opaque literal string (parsed at physical-build time)
}

type Limit struct {
	// Count is the maximum number of rows to pass through. Ignored when
	// CountExpr is non-nil.
	Count int64
	// CountExpr is the parsed AST for the LIMIT expression when it is
	// not a literal integer (typically a parameter reference like
	// $limit). Nil when Count is the authoritative value.
	CountExpr ast.Expression
	// Child is the subplan whose output is truncated.
	Child LogicalPlan
}

type LogicalPlan interface {
	// Children returns the direct children of this operator. Leaf operators
	// return nil. Unary operators return a single-element slice. Binary
	// operators return a two-element slice [left, right].
	Children() []LogicalPlan

	// Vars returns the variable names introduced or required by this operator.
	// The order is unspecified but deterministic for a given operator instance.
	Vars() []string
}

type Merge struct {
	// Pattern is the opaque string representation of the MERGE pattern.
	Pattern string
	// OnCreate is the list of update expression strings applied when the pattern
	// is created (the ON CREATE SET sub-clause).
	OnCreate []string
	// OnMatch is the list of update expression strings applied when the pattern
	// is matched (the ON MATCH SET sub-clause).
	OnMatch []string
	// BoundVars lists the variable names that are bound by the MERGE pattern and
	// made available downstream.
	BoundVars []string
	// NodePropsAST carries the property-map AST of the first node pattern in
	// the MERGE pattern, when present. The physical builder consults it to
	// decide whether the property map contains row-driven expressions (e.g.
	// `MERGE (p:Person {login: prop.login})` after an UNWIND) and, if so,
	// installs a per-row PropsEvalFn on the [exec.Merge] operator.
	// nil when no inline property map is present or when MERGE is shaped as
	// a relationship MERGE (handled by [MergeRelationship]).
	NodePropsAST ast.Expression
	// Child is the driving subplan.
	Child LogicalPlan
}

type MergeRelationship struct {
	// SrcVar is the variable name of the source endpoint.
	SrcVar string
	// DstVar is the variable name of the destination endpoint.
	DstVar string
	// RelVar is the relationship variable name (may be empty for an
	// anonymous relationship).
	RelVar string
	// RelType is the relationship type label.
	RelType string
	// RelProps is the opaque map-literal string representation of the
	// inline relationship property predicate (e.g. `{name: 'r2'}`). Empty
	// when the MERGE pattern declares no inline properties on the
	// relationship. When non-empty the exec operator filters the
	// search by these properties and writes them on creation.
	RelProps string
	// Undirected reports whether the MERGE relationship pattern declares
	// an undirected hop (`MERGE (a)-[r:T]-(b)`). When true the exec
	// operator searches for an existing edge in either direction before
	// creating one (closes Merge5 [13]).
	Undirected bool
	// OnCreate is the list of (key, value) pairs to set on the
	// relationship when a new edge is created.
	OnCreate []KVAction
	// OnMatch is the list of (key, value) pairs to set on the
	// relationship when an existing edge is matched.
	OnMatch []KVAction
	// Child is the driving subplan that binds SrcVar and DstVar.
	Child LogicalPlan
}

type NamedPath struct {
	// PathName is the user-visible path variable name (e.g. "p").
	PathName string
	// Chain is the alternating node/rel description of the pattern, in
	// document order. The first entry has IsLeading=true.
	Chain []PathChainElement
	// Child is the subplan that produces the chain's variables.
	Child LogicalPlan
}

type NodeByIndexRangeScan struct {
	// NodeVar is the variable name bound to each matching node.
	NodeVar string
	// Label is the indexed node label.
	Label string
	// Property is the indexed property key.
	Property string
	// Min is the lower bound (inclusive/exclusive) or nil for an open lower end.
	Min *Bound
	// Max is the upper bound (inclusive/exclusive) or nil for an open upper end.
	Max *Bound
}

type NodeByIndexSeek struct {
	// NodeVar is the variable name bound to each matching node.
	NodeVar string
	// Label is the indexed node label.
	Label string
	// Property is the indexed property key.
	Property string
	// Value is the opaque string representation of the exact-match value.
	Value string
}

type NodeByLabelScan struct {
	// NodeVar is the variable name bound to each scanned node.
	NodeVar string
	// Label is the node label to filter on.
	Label string
}

type OptionalApply struct {
	// Outer is the driving (left) subplan.
	Outer LogicalPlan
	// Inner is the optional correlated subplan.
	Inner LogicalPlan
	// ArgTag is the tag shared with the inner-side Argument leaf.
	ArgTag uint32
}

type OptionalExpand struct {
	// FromVar is the already-bound source node variable.
	FromVar string
	// RelVar is the variable name bound to the traversed relationship (or null).
	RelVar string
	// RelTypes is the list of allowed relationship types. An empty slice means
	// any type is accepted.
	RelTypes []string
	// Direction is the traversal direction relative to FromVar.
	Direction Direction
	// ToVar is the variable name bound to the destination node (or null).
	ToVar string
	// Child is the subplan that produces FromVar.
	Child LogicalPlan
}

type PathChainElement struct {
	// NodeVar is the variable name of the (destination) node for this step,
	// or "" when the node is anonymous.
	NodeVar string
	// RelVar is the variable name of the relationship leading into NodeVar,
	// or "" when the relationship is anonymous. Empty when IsLeading is true.
	RelVar string
	// RelTypes carries the relationship type filter declared in the pattern
	// (e.g. KNOWS in `-[:KNOWS]->`). Empty when IsLeading is true or when no
	// type was specified. Used as a fallback edge type when the live graph
	// lookup cannot resolve one.
	RelTypes []string
	// Direction is the traversal direction relative to the previous node
	// (PreviousNode → NodeVar). Meaningful only when IsLeading is false.
	Direction Direction
	// IsLeading is true for the first element of the chain (the source node
	// of the path).
	IsLeading bool
}

type ProcedureCall struct {
	// Namespace is the optional namespace path of the procedure
	// (e.g. ["apoc", "algo"] for apoc.algo.dijkstra).
	Namespace []string
	// Name is the bare procedure name.
	Name string
	// Arguments is the list of opaque string representations of the call
	// argument expressions.
	Arguments []string
	// YieldVars is the ordered list of variable names produced by the YIELD
	// clause. An empty slice means YIELD * (all output columns).
	YieldVars []string
	// YieldSourceNames is the parallel list of declared procedure-output
	// names that each YieldVars entry binds (the LHS in `YIELD col AS alias`,
	// or the same name as YieldVars when no AS rename is present). Used by
	// the physical builder to map yield aliases to the procedure's declared
	// output column index, so `CALL proc(…) YIELD b, a` (procedure declares
	// outputs in order a, b) reads each column from the correct slot.
	// Empty slice means defaulted to YieldVars (no AS rename).
	YieldSourceNames []string
	// Child is the driving subplan. May be nil when CALL appears at the start
	// of a query.
	Child LogicalPlan
}

type ProduceResults struct {
	// Columns is the ordered list of output column names.
	Columns []string
	// Child is the subplan that produces the result rows.
	Child LogicalPlan
}

type ProjectEndpoints struct {
	// RelVar is the already-bound relationship variable.
	RelVar string
	// StartVar is the variable name bound to the start node (may be empty if
	// not needed).
	StartVar string
	// EndVar is the variable name bound to the end node (may be empty if not
	// needed).
	EndVar string
	// Child is the subplan that produces RelVar.
	Child LogicalPlan
}

type Projection struct {
	// Items is the ordered list of output columns.
	Items []ProjectionItem
	// Child is the subplan whose rows are projected.
	Child LogicalPlan
}

type ProjectionItem struct {
	// Name is the output variable name (the AS alias, or the expression's
	// canonical string representation when no alias is given).
	Name string
	// Expression is an opaque string representation of the expression.
	Expression string
	// Expr is the parsed AST for the expression, when available. Nil for
	// legacy or string-only callers. When non-nil, the executor evaluates it
	// via expr.Eval rather than falling back to a schema-key lookup.
	Expr ast.Expression
}

type RemoveLabels struct {
	// NodeVar is the already-bound node variable.
	NodeVar string
	// Labels is the list of labels to remove.
	Labels []string
	// Child is the driving subplan.
	Child LogicalPlan
}

type RemoveProperty struct {
	// EntityVar is the already-bound node or relationship variable.
	EntityVar string
	// PropertyKey is the property key to remove.
	PropertyKey string
	// Child is the driving subplan.
	Child LogicalPlan
}

type RollUpApply struct {
	// Outer is the driving subplan.
	Outer LogicalPlan
	// Inner is the correlated subplan whose results are collected.
	Inner LogicalPlan
	// CollectVar is the variable name bound to the collected list.
	CollectVar string
	// ArgTag identifies the [Argument] leaf that anchors the Inner
	// subplan. The physical builder pre-allocates the matching
	// exec.Argument under this tag so RollUpApply's loop can seed it
	// with each outer row before re-initialising Inner.
	ArgTag uint32
}

type Selection struct {
	// Predicate is the opaque string representation of the filter expression.
	Predicate string
	// PredicateExpr is the parsed AST for the predicate, when available. Nil
	// for legacy or string-only callers. When non-nil, the executor evaluates
	// it via expr.Eval rather than the pass-through stub.
	PredicateExpr ast.Expression
	// Child is the subplan whose rows are filtered.
	Child LogicalPlan
}

type SemiApply struct {
	// Outer is the driving subplan.
	Outer LogicalPlan
	// Inner is the correlated existence-check subplan; its leftmost leaf must
	// be an [Argument] whose Tag equals [SemiApply.ArgTag].
	Inner LogicalPlan
	// ArgTag is the tag shared with the inner-side Argument leaf so that the
	// physical builder can route the matching exec.Argument instance.
	ArgTag uint32
}

type SetAllProperties struct {
	// EntityVar is the already-bound node or relationship variable.
	EntityVar string
	// IsReplace selects `=` (true, replace) vs `+=` (false, merge) semantics.
	IsReplace bool
	// SourceVar names a bound node/relationship whose properties are copied.
	// Empty when the source is a literal map or a parameter reference.
	SourceVar string
	// MapLiteral holds the opaque literal-map string (e.g. `{a: 1, b: "x"}`)
	// produced by the AST printer. Empty when the source is a SourceVar or a
	// parameter reference.
	MapLiteral string
	// ParamName holds the `$name` reference text (without the dollar sign)
	// when the source is a parameter. Empty otherwise.
	ParamName string
	// Child is the driving subplan.
	Child LogicalPlan
}

type SetLabels struct {
	// NodeVar is the already-bound node variable.
	NodeVar string
	// Labels is the list of labels to add.
	Labels []string
	// Child is the driving subplan.
	Child LogicalPlan
}

type SetProperty struct {
	// EntityVar is the already-bound node or relationship variable.
	EntityVar string
	// PropertyKey is the property key to set.
	PropertyKey string
	// Value is the opaque string representation of the new value expression.
	Value string
	// ValueExpr is the parsed AST for the value expression when available.
	// The physical builder uses it to construct a per-row evaluator so that
	// non-literal RHS expressions (variable references, arithmetic, property
	// access, function calls) actually run against each input row instead of
	// silently failing the literal-parser fast path.
	ValueExpr ast.Expression
	// Child is the driving subplan.
	Child LogicalPlan
}

type Skip struct {
	// Count is the number of leading rows to skip. Ignored when
	// CountExpr is non-nil.
	Count int64
	// CountExpr is the parsed AST for the SKIP expression when it is
	// not a literal integer. Nil when Count is the authoritative value.
	CountExpr ast.Expression
	// Child is the subplan whose leading rows are discarded.
	Child LogicalPlan
}

type Sort struct {
	// SortItems is the ordered list of sort keys.
	SortItems []SortItem
	// Child is the subplan whose rows are sorted.
	Child LogicalPlan
}

type SortItem struct {
	// Expression is an opaque string representation of the sort key expression.
	Expression string
	// Expr is the original AST expression for the sort key. It is carried
	// alongside Expression so the physical builder can compile an expression
	// evaluator for keys that are not directly present in the output schema
	// (e.g. ORDER BY n.age after RETURN n — n.age is not a projected column
	// but it can be derived by evaluating the expression against the row).
	// May be nil for sort items constructed without access to the AST.
	Expr ast.Expression
	// Descending indicates DESC ordering; false means ASC.
	Descending bool
}

type SubqueryCount struct {
	// Inner is the subplan whose row-count is reported by the count.
	Inner LogicalPlan
	// CorrelationVars is the snapshot of outer-scope variable names visible
	// inside the subquery.
	CorrelationVars []string
	// ArgTag is the tag shared with the inner-side Argument leaf.
	ArgTag uint32
}

type SubqueryExists struct {
	// Inner is the subplan whose row-count drives the existence check. Its
	// leftmost leaf must be an [Argument] whose Tag equals
	// [SubqueryExists.ArgTag].
	Inner LogicalPlan
	// CorrelationVars is the snapshot of outer-scope variable names that the
	// inner plan may reference at evaluation time. The expression evaluator
	// projects the outer row onto these names before seeding the Argument.
	CorrelationVars []string
	// ArgTag is the tag shared with the inner-side Argument leaf so the
	// physical builder routes the matching exec.Argument instance per outer
	// row.
	ArgTag uint32
}

type Top struct {
	// SortItems is the ordered list of sort keys.
	SortItems []SortItem
	// Limit is the maximum number of rows to produce.
	Limit int64
	// Child is the subplan whose rows are sorted and truncated.
	Child LogicalPlan
}

type TranslateError struct {
	// UnsupportedClause is the name of the clause or construct that triggered
	// the error (e.g. "FOREACH", "multi-graph UNION").
	UnsupportedClause string
	// Pos is the source position of the unsupported clause.
	Pos ast.Position
}

type Union struct {
	// Left is the first input subplan.
	Left LogicalPlan
	// Right is the second input subplan.
	Right LogicalPlan
}

type UnionAll struct {
	// Left is the first input subplan.
	Left LogicalPlan
	// Right is the second input subplan.
	Right LogicalPlan
}

type Unwind struct {
	// ListExpression is the opaque string representation of the list expression.
	ListExpression string
	// ListExpr is the parsed AST for the list expression, when available. Nil
	// means the expression could not be parsed; callers must fall back to a
	// static empty list. The executor uses ListExpr when non-nil.
	ListExpr ast.Expression
	// ElementVar is the variable name bound to each list element.
	ElementVar string
	// Child is the subplan that provides the context rows. May be nil when
	// UNWIND appears at the start of a query.
	Child LogicalPlan
}

type VarLengthExpand struct {
	// FromVar is the already-bound source node variable.
	FromVar string
	// RelVar is the variable name bound to the collected path relationships.
	RelVar string
	// RelTypes is the list of allowed relationship types. An empty slice means
	// any type is accepted.
	RelTypes []string
	// Direction is the traversal direction relative to FromVar.
	Direction Direction
	// ToVar is the variable name bound to the destination node.
	ToVar string
	// MinDepth is the minimum number of hops (inclusive, ≥1).
	MinDepth int
	// MaxDepth is the maximum number of hops (inclusive). Zero means unbounded.
	MaxDepth int
	// PathVar, when non-empty, is the named path variable (`p` in
	// `MATCH p=(a)-[*1..3]->(b)`). The physical builder allocates a schema slot
	// for it and emits a PathValue in that column.
	PathVar string
	// ExcludedRelVars lists relationship-variable names already in scope
	// at the time this VLE step is reached whose bound edge must not be
	// traversed. Implements the openCypher no-repeated-relationships rule
	// across distinct rel patterns in the same MATCH (e.g. `MATCH ()-[r]
	// -() MATCH (n)-[*0..1]-()-[r]-()-[*0..1]-(m)` — the two VLE steps
	// must exclude r's edge). The physical builder resolves each name
	// against the current schema; unresolved names are silently dropped
	// (the variable is not yet bound).
	ExcludedRelVars []string
	// Child is the subplan that produces FromVar.
	Child LogicalPlan
}