oql

type AdaptedSQL struct {
	SQL     string
	Args    []interface{}
	Aliases []string // Column aliases in SELECT order

	// DecimalColumns tracks which result aliases need denormalisation.
	// Only populated when the backend stores decimals as scaled integers
	// (i.e. SupportsNativeDecimalAggregation() returns false).
	DecimalColumns map[string]int
}

type AggregateFunc func(values []interface{}) interface{}

type AggregateSQL struct {
	SQL     string
	Args    []interface{}
	Aliases []string // Column aliases in SELECT order

	// DecimalColumns tracks which result aliases are decimal aggregates
	// that need denormalisation. Key: alias, Value: scale.
	DecimalColumns map[string]int
}

type Aggregator struct {
	// contains filtered or unexported fields
}

type Engine struct {
	// contains filtered or unexported fields
}

type EntityChecker interface {
	ListEntities(ctx context.Context) ([]string, error)
}

type Executor struct {
	// contains filtered or unexported fields
}

type GeneratedSQL struct {
	SQL  string
	Args []interface{}
}

type HardwareProfile struct {
	Name string // "edge", "vps", "dedicated", "calibrated", or "custom"

	// BlobPushThreshold is the minimum row count at which blob entity
	// queries are pushed to SQL (json_extract). Below this count, the
	// Go path processes rows directly without a CountEntities round-trip.
	BlobPushThreshold int

	// ComplexityThresholds gate PushFull for adapted entities based on
	// estimated query complexity. When estimated complexity exceeds zero,
	// the planner checks row count against these thresholds before
	// committing to PushFull.
	//
	// A query's complexity is estimated from its AST:
	//   - Each multi-key GROUP BY adds 1 temp B-tree
	//   - Each ORDER BY misaligned with GROUP BY adds 1 temp B-tree
	//   - Non-COUNT aggregates on columns not in GROUP BY set nonCovering
	//
	// Simple queries (0 temp B-trees, covering) always use PushFull.
	NonCoveringThreshold int // min rows for push-down with non-covering aggregate scan
	TempBTree1Threshold  int // min rows for push-down with 1 temp B-tree
	TempBTree2Threshold  int // min rows for push-down with 2+ temp B-trees
}

type Job struct {
	ID        string
	Query     string
	Status    JobStatus
	Result    *Result
	Error     string
	CreatedAt time.Time
	UpdatedAt time.Time
	// contains filtered or unexported fields
}

type JobManager struct {
	// contains filtered or unexported fields
}

type JobStatus string

type JoinSQL struct {
	SQL     string
	Args    []interface{}
	Aliases []string // Result column aliases in SELECT order
	// DecimalColumns is alias -> scale for every adapted-side decimal
	// column selected. XM-7b (xoluman's own report, 2026-08-12): this
	// field, and the tracking that populates it, didn't exist at all
	// before this fix -- generateJoinSelectColumns already called
	// store.AdaptedColumnInfo (which returns scale/isDecimal) but
	// discarded both, so a decimal field through a JOIN returned its
	// raw, scaled-integer stored form untransformed (e.g. "333000.65"
	// stored/returned elsewhere as that exact decimal string came back
	// as the bare integer 33300065 through a JOIN specifically -- an
	// exact x100 scale factor, not a computation error, consistent
	// with the missing denormalisation step this field and
	// denormaliseAggregateDecimals (already used by the adapted and
	// aggregate paths, reused here unmodified) now close.
	DecimalColumns map[string]int
}

type Planner struct {
	// contains filtered or unexported fields
}

type PredicateCompileResult struct {
	// Preds is the set of AND-combined predicates that can be evaluated
	// during JSON tokenisation. May be nil if nothing was extractable.
	Preds *jsonic.PredicateSet

	// Residual is the remaining WHERE expression that cannot be pushed
	// into the tokeniser. Must still be evaluated in Go after extraction.
	// Nil if the entire WHERE was compiled to predicates.
	Residual ast.Expression
}

type PushDecision int

type QueryComplexity struct {
	TempBTrees  int  // estimated number of temp B-tree materialisations
	NonCovering bool // aggregate scan requires data page access beyond the index
}

type QueryLimits struct {
	MaxRows     int // Max rows returned
	MaxScanRows int // Max rows scanned before abort
}

type QueryPlan struct {
	Push        []PushDecision            // Which operations to push
	EstimatedN  int                       // Estimated input cardinality
	BackendCaps storage.QueryCapabilities // What the backend can do
	Reason      string                    // Human-readable explanation for debug log

	// Join is non-nil when Push contains PushJoin.
	Join         *joinSpec
	LeftAdapted  bool // true when the left-side entity uses an adapted table
	RightAdapted bool // true when the right-side entity uses an adapted table
}

type QueryStats struct {
	RowsScanned   int           `json:"rows_scanned"`
	RowsReturned  int           `json:"rows_returned"`
	RowsAffected  int           `json:"rows_affected,omitempty"`
	ExecutionTime time.Duration `json:"execution_time_ms"`
}

type Result struct {
	Type  ResultType               `json:"type"`
	Rows  []map[string]interface{} `json:"data,omitempty"`
	Stats QueryStats               `json:"stats"`
}

type ResultType int

type SQLDialect interface {
	// JSONFieldAs extracts a field from the JSON data column and casts it
	// to the requested OQL type. This is the canonical extraction method;
	// all comparison and ordering sites should use it rather than the
	// deprecated JSONField / JSONFieldNumeric shortcuts.
	//
	// oqlType must be one of: "text", "numeric", "boolean", "auto".
	JSONFieldAs(fieldPath, oqlType string) string

	// JSONFieldAliasedAs is JSONFieldAs for JOIN queries where the data
	// column is qualified by a table alias.
	JSONFieldAliasedAs(alias, fieldPath, oqlType string) string

	// JSONField extracts a field from the JSON data column without an
	// explicit type cast. Equivalent to JSONFieldAs(fieldPath, "auto").
	//
	// Deprecated: use JSONFieldAs with an explicit oqlType. JSONField is
	// retained for backward compatibility with existing dialect implementations
	// and will be removed when a PostgreSQL dialect is added.
	JSONField(fieldPath string) string

	// JSONFieldNumeric extracts a field and casts it to a numeric type.
	// Equivalent to JSONFieldAs(fieldPath, "numeric").
	//
	// Deprecated: use JSONFieldAs(fieldPath, "numeric").
	JSONFieldNumeric(fieldPath string) string

	// JSONFieldAliased extracts a field from a JOIN-aliased data column
	// without a type cast. Equivalent to JSONFieldAliasedAs(alias, fieldPath, "auto").
	//
	// Deprecated: use JSONFieldAliasedAs with an explicit oqlType.
	JSONFieldAliased(alias, fieldPath string) string

	// Placeholder emits a parameter placeholder for the n-th argument (1-based).
	// For SQLite: ?
	// For Postgres: $1, $2, ...
	Placeholder(n int) string

	// LimitClause emits the LIMIT/TOP equivalent.
	// T-SQL uses TOP N (before columns); SQLite and Postgres use LIMIT N (at end).
	LimitClause(placeholder string) string

	// BaseQuery emits the initial SELECT ... FROM ... WHERE entity_type = <param>.
	// Returns the SQL fragment and the initial argument (entity name).
	BaseQuery(entity string) (sql string, arg interface{})

	// Name returns the dialect identifier (for debug logging).
	Name() string

	// DefaultThreshold returns the minimum entity count at which push-down
	// becomes worthwhile for this backend. Below this count, the fixed
	// overhead of generating and executing backend SQL exceeds the cost
	// of Go-side processing. This varies by backend: an in-process SQLite
	// has near-zero call overhead, while a networked Postgres has
	// connection and round-trip costs that raise the crossover point.
	DefaultThreshold() int

	// ScalarFunction translates an OQL scalar function name to the
	// backend's equivalent SQL expression. Returns the SQL fragment
	// and true, or ("", false) if the function is not supported.
	// Example: ("LEN", "col") -> ("LENGTH(col)", true) on SQLite,
	//          ("LEN", "col") -> ("CHAR_LENGTH(col)", true) on PostgreSQL.
	ScalarFunction(name string, argSQL string) (string, bool)

	// CastExpression emits a CAST for the target backend.
	// Example: CastExpression("price", "REAL") -> "CAST(price AS REAL)"
	// on SQLite, "CAST(price AS DOUBLE PRECISION)" on PostgreSQL.
	CastExpression(expr, targetType string) string
}

type SQLGenerator struct {
	// contains filtered or unexported fields
}

type SQLiteDialect struct {
	// NodesTable is the tenant-scoped blob node store table name (e.g. t0000_nodes).
	// Set by the OQL executor from store.NodesTable() when the store implements
	// storage.TableNamer. Defaults to "t0000_nodes" if unset.
	NodesTable string
}

type ScalarFunc func(args []interface{}) interface{}

type SchemaValidator interface {
	Validate(entity string, data map[string]interface{}) (bool, []string)
}

type Validator struct {
	// contains filtered or unexported fields
}