ir

type AggregateExpr struct {
	// 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
	// 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
	// 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 {
	// 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
	// NodeVar is the variable name bound to the newly created node.
	NodeVar string
	// Properties is the opaque string representation of the property map
	// expression (e.g. "{name: 'Alice'}").
	Properties string
	// Labels is the list of labels assigned to the new node.
	Labels []string
}

type CreateRelationship struct {
	// 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
	// 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
}

type DegreeShape struct {
	// AnchorVar is the variable naming the node whose degree is wanted. The
	// caller must confirm it is bound in the row before using the shape.
	AnchorVar string
	// FarVar is the far endpoint's variable, or "" when the pattern does not
	// name one. When it is non-empty the caller must confirm it is NOT bound in
	// the row: a bound far endpoint makes the pattern an expand-into between two
	// fixed nodes, not a degree.
	FarVar string
	// RelType is the single relationship type, or "" when the pattern is
	// untyped. Cypher has no empty relationship type, so "" is unambiguous.
	RelType string
}

type DeleteNode struct {
	// 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
	// NodeVar is the already-bound node variable to delete.
	NodeVar string
}

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

type DetachDelete struct {
	// 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
	// NodeVar is the already-bound node variable to delete.
	NodeVar string
}

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 {
	// Child is the subplan whose rows are aggregated.
	Child LogicalPlan
	// 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
}

type Expand struct {
	// Child is the subplan that produces FromVar.
	Child LogicalPlan
	// FromVar is the already-bound source node variable.
	FromVar string
	// RelVar is the variable name bound to the traversed relationship.
	RelVar string
	// ToVar is the variable name bound to the destination node.
	ToVar 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
	// RelTypes is the list of allowed relationship types. An empty slice means
	// any type is accepted.
	RelTypes []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
	// Direction is the traversal direction relative to FromVar.
	Direction Direction
	// IntoVar names an ALREADY-BOUND destination variable this hop must land on —
	// the openCypher "expand into" case, which arises whenever a pattern closes a
	// cycle (`MATCH (a)-[:K]->(b)-[:K]->(a)`) or re-uses a bound endpoint.
	//
	// When set, ToVar carries the synthetic `__anon_N_to_<IntoVar>` name the
	// translator generates and an equality Selection sits above this node. IntoVar
	// records the same fact as a FIELD so the physical builder can act on it without
	// parsing that naming convention (#2206); the convention itself stays, because
	// lastSyntheticToFor threads the synthetic as the next hop's FromVar.
	//
	// Empty for every hop whose destination is fresh, which is the common case.
	IntoVar string
}

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

type IndexType uint8

type KVAction struct {
	Key   string
	Value string // opaque literal string (parsed at physical-build time)
	// RetainKeys lists the RHS property keys of a Replace map sentinel — the
	// keys that must NOT be cleared. Nil for an entity-copy Replace sentinel
	// (the retained set is the source entity's live keys, resolved at write
	// time) and for non-Replace actions.
	RetainKeys []string
	// Replace marks the leading sentinel of a whole-entity `=` replace group.
	// When true the exec layer clears the relationship's existing properties
	// that are absent from the RHS before applying the subsequent write
	// actions. Always false for the additive `+=` form and for
	// single-property `SET <relVar>.<key> = <value>` items.
	Replace bool
}

type Limit struct {
	// 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
	// Count is the maximum number of rows to pass through. Ignored when
	// CountExpr is non-nil.
	Count int64
}

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 {
	// 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
	// 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
	// OnCreateExprs / OnMatchExprs carry the parsed value-expression ASTs of
	// the ON CREATE / ON MATCH property-set items whose right-hand side is a
	// non-literal expression (e.g. `ON MATCH SET n.num = n.num + 1`). The
	// physical builder installs a per-row evaluator for each so the RHS is
	// evaluated against the matched/created row instead of being dropped as a
	// literal-parse failure. Literal RHS items are omitted (they use the
	// opaque-string fast path in [OnCreate]/[OnMatch]).
	OnCreateExprs []MergeSetExpr
	OnMatchExprs  []MergeSetExpr
	// OnCreateSetAll / OnMatchSetAll carry whole-entity ON CREATE / ON MATCH
	// SET items (`SET n = <expr>` / `SET n += <expr>`) whose target is a node
	// variable rather than a property. The per-property opaque-string path
	// drops such keyless items; the physical builder installs a per-row
	// expression evaluator for each so the whole map/entity value is written
	// (#2031).
	OnCreateSetAll []MergeSetAll
	OnMatchSetAll  []MergeSetAll
}

type MergePattern struct {
	Child LogicalPlan
	// Nodes holds one entry per chain position; len(Nodes) == len(Hops)+1.
	Nodes []MergePatternEndpoint
	// Hops holds one entry per relationship; Hops[i] connects Nodes[i] to
	// Nodes[i+1].
	Hops []MergePatternHop
	// OnCreate / OnMatch are opaque SET-item strings (the same representation
	// [Merge] uses), parsed by the physical builder via the shared
	// parseMergeActions helper into actions addressable by any pattern
	// variable — any Nodes[i].Var or Hops[i].RelVar, not just one entity.
	OnCreate []string
	OnMatch  []string
	// OnCreateExprs / OnMatchExprs carry the value-expression ASTs of the
	// ON CREATE / ON MATCH property-set items whose right-hand side is a
	// non-literal expression. See [MergeSetExpr]; literal RHS items are
	// omitted (handled via the opaque-string fast path in [OnCreate]/[OnMatch]).
	OnCreateExprs []MergeSetExpr
	OnMatchExprs  []MergeSetExpr
	// OnCreateSetAll / OnMatchSetAll carry whole-entity ON CREATE / ON MATCH
	// SET items on a chain node variable, which the per-property opaque-string
	// path drops. See [MergeSetAll] (#2031).
	OnCreateSetAll []MergeSetAll
	OnMatchSetAll  []MergeSetAll
}

type MergePatternEndpoint struct {
	// PropsAST carries the property-map AST when it contains non-literal
	// expressions (variable references, property accesses, parameters).
	// nil when the map is absent or fully literal, in which case PropsRaw
	// alone drives both the search predicate and the create-time write.
	PropsAST ast.Expression
	Var      string
	PropsRaw string // opaque inline `{k: v, ...}` source string, "" when absent
	Labels   []string
	Bound    bool
}

type MergePatternHop struct {
	// RelPropsAST carries the property-map AST when it contains non-literal
	// expressions; nil when the map is absent or fully literal.
	RelPropsAST ast.Expression
	RelVar      string // "" for an anonymous relationship
	RelType     string
	RelPropsRaw string // opaque inline `{k: v, ...}` source string, "" when absent
	Undirected  bool
	// Reversed is true for an incoming `<-` pattern: chain positions stay in
	// pattern-declaration order, but the edge is stored/searched from the
	// NEXT position back to this one rather than this one to the next.
	Reversed bool
}

type MergeRelationship struct {
	// RelPropsAST carries the inline relationship property-map AST when it
	// contains a non-literal value (a variable reference, property access,
	// or arithmetic expression — e.g. `{kind: r.pk}`). The physical builder
	// installs a per-row property evaluator from it so the map drives both
	// the match-search predicate and the created edge's properties. nil when
	// the map is absent or every value is a literal (or a $param, resolved at
	// build time via the opaque RelProps string). Without it a row-driven
	// inline property silently degrades to null on the created edge, since
	// the literal-only parser drops the non-literal entry (fail-silent
	// Consistency defect).
	RelPropsAST ast.Expression
	// Child is the driving subplan that binds SrcVar and DstVar.
	Child LogicalPlan
	// 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
	// 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
	// OnCreateExprs / OnMatchExprs carry the value-expression ASTs of the
	// ON CREATE / ON MATCH property-set items whose right-hand side is a
	// non-literal expression (e.g. `ON MATCH SET r.n = r.n + 1`). See
	// [MergeSetExpr]; literal RHS items are omitted (handled via the
	// [KVAction] opaque-string fast path).
	OnCreateExprs []MergeSetExpr
	OnMatchExprs  []MergeSetExpr
	// 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
}

type MergeSetAll struct {
	Value     ast.Expression
	TargetVar string
	IsReplace bool
}

type MergeSetExpr struct {
	Value     ast.Expression
	TargetVar string
	Key       string
}

type NamedPath struct {
	// Child is the subplan that produces the chain's variables.
	Child LogicalPlan
	// 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
}

type NodeByIndexRangeScan struct {
	// 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
	// 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
}

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 {
	// Child is the subplan that produces FromVar.
	Child LogicalPlan
	// FromVar is the already-bound source node variable.
	FromVar string
	// RelVar is the variable name bound to the traversed relationship (or null).
	RelVar string
	// ToVar is the variable name bound to the destination node (or null).
	ToVar 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
}

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 {
	// Child is the driving subplan. May be nil when CALL appears at the start
	// of a query.
	Child LogicalPlan
	// Name is the bare procedure name.
	Name string
	// Namespace is the optional namespace path of the procedure
	// (e.g. ["apoc", "algo"] for apoc.algo.dijkstra).
	Namespace []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
}

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

type ProjectEndpoints struct {
	// Child is the subplan that produces RelVar.
	Child LogicalPlan
	// 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
}

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

type ProjectionItem struct {
	// 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
	// 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
	// Hidden marks a synthetic passthrough item added only so a downstream
	// Sort can resolve an ORDER BY reference to a pre-projection variable. It
	// is emitted into the row stream but MUST be excluded from the final
	// ProduceResults output columns (#1805).
	Hidden bool
}

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

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

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 {
	// 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
	// Predicate is the opaque string representation of the filter expression.
	Predicate string
}

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 {
	// MapAST carries the source map-literal AST when it contains a non-literal
	// value (a variable reference, property access, or arithmetic — e.g.
	// `SET n += {x: row.y}`). The physical builder installs a per-row map
	// evaluator from it so the row-driven values are written (and null-valued
	// keys removed). nil when the map is absent or every value is a literal
	// (or a $param, resolved at build time via the opaque MapLiteral string).
	// Without it a row-driven map value silently degrades to null on the target.
	MapAST ast.Expression
	// ExprAST carries a whole map-valued RHS expression for the
	// `SET n = <expr>` / `SET n += <expr>` forms whose right-hand side is
	// neither a `{…}` literal, a bound entity variable, nor a `$param` — e.g.
	// `SET n = properties(m)`, a map projection, or coalesce. The physical
	// builder installs a per-row expression evaluator from it; the exec operator
	// dispatches on the evaluated value's runtime kind (map / node / relationship
	// / null / other). nil for the SourceVar, MapLiteral, and ParamName forms.
	// Without it such an openCypher-valid expression fails at build time (the
	// literal-map parser rejects the stringified expression).
	ExprAST ast.Expression
	// Child is the driving subplan.
	Child LogicalPlan
	// EntityVar is the already-bound node or relationship variable.
	EntityVar string
	// 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
	// IsReplace selects `=` (true, replace) vs `+=` (false, merge) semantics.
	IsReplace bool
}

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

type SetProperty struct {
	// 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
	// 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
}

type ShortestPath struct {
	// Child is the subplan that produces FromVar and ToVar.
	Child LogicalPlan
	// FromVar / ToVar are the endpoint node variables, both produced by Child.
	FromVar string
	ToVar   string
	// PathVar is the named path variable bound to the resulting path. Always
	// non-empty (the parser only rewrites the named binding form).
	PathVar string
	// RelVar is the inner relationship variable name, or empty when the inner
	// relationship is anonymous. Bound as LIST<RELATIONSHIP> for the path.
	RelVar string
	// RelTypes is the inner relationship's accepted type set (OR semantics). An
	// empty slice means any type.
	RelTypes []string
	// MinDepth / MaxDepth bound the path length. MinDepth is 0 or 1 (enforced by
	// sema). MaxDepth uses math.MaxInt for "unbounded".
	MinDepth int
	MaxDepth int
	// All selects allShortestPaths (every minimum-length path) over
	// shortestPath (a single arbitrary minimum-length path).
	All bool
	// Optional reports whether the binding sits under OPTIONAL MATCH. When a
	// pair has no path: a non-optional binding eliminates the row; an optional
	// one keeps the row with the path variable bound to null.
	Optional bool
	// Direction is the inner relationship's traversal direction relative to
	// FromVar.
	Direction Direction
}

type ShowConstraints struct {
	Projection *ShowProjection
}

type ShowIndexes struct {
	Projection *ShowProjection
}

type ShowProjection struct {
	Project []ShowYield
	Where   ast.Expression
	Return  *ast.Projection
	// ReturnColumns are the output column names for an explicit RETURN item list
	// (Return non-nil and not RETURN *), precomputed by the parser using the same
	// column-naming convention as an ordinary RETURN. Empty otherwise.
	ReturnColumns []string
}

type ShowYield struct {
	Source string
	Output string
}

type Skip struct {
	// 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
	// Count is the number of leading rows to skip. Ignored when
	// CountExpr is non-nil.
	Count int64
}

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

type SortItem struct {
	// 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
	// Expression is an opaque string representation of the sort key expression.
	Expression string
	// 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 {
	// Child is the subplan whose rows are sorted and truncated.
	Child LogicalPlan
	// SortItems is the ordered list of sort keys.
	SortItems []SortItem
	// Limit is the maximum number of rows to produce.
	Limit int64
}

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 {
	// 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
	// Child is the subplan that provides the context rows. May be nil when
	// UNWIND appears at the start of a query.
	Child LogicalPlan
	// ListExpression is the opaque string representation of the list expression.
	ListExpression string
	// ElementVar is the variable name bound to each list element.
	ElementVar string
}

type VarLengthExpand struct {
	// Child is the subplan that produces FromVar.
	Child LogicalPlan
	// FromVar is the already-bound source node variable.
	FromVar string
	// RelVar is the variable name bound to the collected path relationships.
	RelVar string
	// ToVar is the variable name bound to the destination node.
	ToVar string
	// 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
	// RelTypes is the list of allowed relationship types. An empty slice means
	// any type is accepted.
	RelTypes []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
	// MinDepth is the minimum number of hops (inclusive, ≥1).
	MinDepth int
	// MaxDepth is the maximum number of hops (inclusive). Zero means unbounded.
	MaxDepth int
	// Direction is the traversal direction relative to FromVar.
	Direction Direction
}