query

type AliasDef struct {
	Name string `json:"name" yaml:"name"`
	CEL  string `json:"cel" yaml:"cel"`
}

type CardinalityProbe struct {
	Provider   string `json:"provider"`
	Connection string `json:"connection,omitempty"`
	Column     string `json:"column"`
	Field      string `json:"field,omitempty"`
	Distinct   int64  `json:"distinct"`
	Limit      int    `json:"limit"`
	Kind       string `json:"kind"` // the filter kind the count chose
	Cached     bool   `json:"cached"`
}

type ColumnDef struct {
	// Name is the public row key and default header label.
	Name string `json:"name" yaml:"name"`

	// Source is the provider row key copied into Name. The original key is
	// removed after all column expressions have been evaluated.
	Source string `json:"source,omitempty" yaml:"source,omitempty"`

	// Label overrides the column header. Defaults to a prettified Name.
	Label string `json:"label,omitempty" yaml:"label,omitempty"`

	// Type is the semantic type used for formatting. Defaults to string.
	Type ColumnType `json:"type,omitempty" yaml:"type,omitempty"`

	// Kind enables specialized table behavior. In particular, timestamp marks
	// the column used by the table's date-range control.
	Kind ColumnKind `json:"kind,omitempty" yaml:"kind,omitempty"`

	// Format overrides the clicky format string (e.g. "date", "bytes",
	// "duration", "currency"). When empty it is derived from Type.
	Format string `json:"format,omitempty" yaml:"format,omitempty"`

	// Unit is an optional display unit (e.g. "ms", "bytes", "percentunit").
	Unit string `json:"unit,omitempty" yaml:"unit,omitempty"`

	// Width is an optional max display width in characters.
	Width int `json:"width,omitempty" yaml:"width,omitempty"`

	// CEL is an optional expression computing the cell value from the row.
	// The row is exposed as `row` in the CEL environment.
	CEL string `json:"cel,omitempty" yaml:"cel,omitempty"`

	// JSONPath is an optional path computing the cell value. It is rooted at the
	// row, or at Source when that is set — and a Source holding JSON as a string
	// is parsed first, so an encoded and a native column read the same way. A
	// path matching nothing yields nil: on a scan, a row that lacks the field is
	// ordinary rather than exceptional. Alternative to CEL, not a companion.
	//
	// Source names the root here; it does not rename. Several columns read one
	// JSON column, and that column stays in the row rather than being consumed
	// by whichever of them ran first.
	JSONPath string `json:"jsonpath,omitempty" yaml:"jsonpath,omitempty"`

	// Filter overrides how this column is filtered at the backend. Direct
	// columns, simple row/span CEL lookups and literal-key-chain JSONPaths infer
	// the field automatically and Type infers the control; computed CEL, and a
	// JSONPath that selects rather than addresses, need an explicit field to be
	// filterable at all.
	Filter *ColumnFilterDef `json:"filter,omitempty" yaml:"filter,omitempty"`

	// Hidden excludes the column from rendered output while keeping it available
	// to later column and style CEL expressions.
	Hidden bool `json:"hidden,omitempty" yaml:"hidden,omitempty"`

	// Style is an optional CEL expression returning this cell's presentation
	// classes (e.g. `level == "ERROR" ? "text-red-500" : ""`). It reads the row
	// the same way CEL does and affects rendering only: the row itself is
	// unchanged, so an export carries the value without the styling.
	Style string `json:"style,omitempty" yaml:"style,omitempty"`
}

type ColumnFilterBinding struct {
	Column  string
	Key     string
	Field   string
	Label   string
	Kind    ColumnFilterKind
	Options []string
	Lookup  bool
	Multi   bool
	// Unit is the unit the column stores its values in (ColumnDef.Unit), which
	// a duration bound is resolved into. Empty means milliseconds, the unit an
	// unannotated duration column is read under. No other kind consults it.
	Unit string
	// Nested and Where carry the container the selection is compiled inside and
	// the constants that address one entry of it. See ColumnFilterDef.
	Nested string
	Where  map[string]string
	// Limit is the author's declared cap on the lookup, or zero when they
	// declared none. Zero is not "no values": it is what leaves the choice to
	// whoever asks, which is why an inferred binding never fills it in.
	Limit int

	// Default is the selection a request that names no value is executed under,
	// written in the same wire grammar a request would send. It exists for a
	// generated control whose absence is not a sensible query — a log profile
	// with no time bound reads every line a container ever wrote — and it is
	// resolved through the same parse a supplied value takes, so the two can
	// never mean different things. Empty means the filter is simply absent when
	// nobody selects anything.
	Default string
}

type ColumnFilterDef struct {
	// Field is the backend field the selection is applied to. For a document
	// store it is the indexed field; for SQL it is the result column the query
	// returns. Required only when the column's own definition implies none.
	Field string `json:"field,omitempty" yaml:"field,omitempty"`

	// Nested names the `nested` mapping Field lives inside. A document store
	// indexes each element of such a field as its own document, so a selection on
	// one has to be compiled inside a nested query; a flat clause on it matches no
	// document at all, and says nothing about why.
	//
	// It cannot be inferred from the column, because a tag list mapped `nested`
	// and a plain array of objects report identical fields — only the index
	// mapping tells them apart. Declare it for a profile; the connection browser
	// reads it from the mapping itself.
	Nested string `json:"nested,omitempty" yaml:"nested,omitempty"`

	// Where pins the constants the selection also requires, keyed by backend
	// field. It is what narrows to one entry of a key/value tag list: the key is
	// fixed here and the value is what the operator picks.
	//
	// It requires Nested. Outside a nested query the two clauses are ANDed across
	// the whole document, which matches a document carrying the key on one entry
	// and the value on another — the wrong rows, returned confidently.
	Where map[string]string `json:"where,omitempty" yaml:"where,omitempty"`

	// Kind overrides the control and the value grammar. Empty derives it from
	// Type: string, status and health select values; number, duration and bytes
	// take numeric bounds; datetime takes a time range; boolean is a yes/no
	// toggle; key_value, key_values and json offer nothing. Set it where the
	// rendered type and the backend storage disagree — a status code shown as a
	// badge but stored as a number filters by range.
	Kind ColumnFilterKind `json:"kind,omitempty" yaml:"kind,omitempty"`

	// Options enumerates the selectable values, replacing the backend lookup. It
	// is what a low-cardinality field the backend cannot aggregate needs: the
	// question the lookup asks has no answer there. Value selections only.
	Options []string `json:"options,omitempty" yaml:"options,omitempty"`

	// Lookup asks the backend for this field's distinct values. Defaults to true
	// for a value selection with no Options. Turning it off leaves the values
	// typed rather than picked, which is the only workable control over a
	// high-cardinality field like a trace id.
	Lookup *bool `json:"lookup,omitempty" yaml:"lookup,omitempty"`

	// Multi allows several values at once, defaulting to true. A single-valued
	// filter still excludes: "!eu" is one value with a sign, not two.
	Multi *bool `json:"multi,omitempty" yaml:"multi,omitempty"`

	// Limit caps how many distinct values one lookup offers, defaulting to
	// DefaultFilterLookupLimit. Everything past it is reached by typing rather
	// than scrolling, so raise it for a field whose whole range is worth seeing
	// at once and lower it for one where even fifty is noise. Value selections
	// only — the other kinds have no list to cap.
	Limit *int `json:"limit,omitempty" yaml:"limit,omitempty"`

	// Disabled offers no filter for this column while leaving the column itself
	// rendered, which Hidden does not.
	Disabled bool `json:"disabled,omitempty" yaml:"disabled,omitempty"`
}

type ColumnFilterKind string

type ColumnFilterValue struct {
	Column string
	Key    string
	Field  string

	// Nested and Where carry the container this selection is compiled inside and
	// the constants that address one entry of it. See ColumnFilterDef.
	Nested string
	Where  map[string]string

	// Kind is the grammar the value was parsed under and the one a provider
	// compiles it back out of. Empty means a value selection.
	Kind ColumnFilterKind

	// Include and Exclude carry a value or substring selection.
	Include []string
	Exclude []string

	// Range carries a numeric or time selection.
	Range *FilterRange

	// Bool carries a yes/no selection. Nil is the "any" arm.
	Bool *bool
}

type ColumnInspectionProvider interface {
	InspectColumnFilters(context.Context, ProviderRequest, []ColumnDef) (ColumnInspectionResult, error)
}

type ColumnInspectionResult struct {
	Filters map[string]*ColumnFilterDef
	Cache   []inspection.CacheMetadata

	// Counts is the distinct count per inspected *field* that the filter kinds
	// above were chosen from. It is reported rather than kept internal because
	// the count is the whole reason for the choice: without it, "why is this a
	// text box and not a dropdown" can only be answered by re-running the probe
	// by hand.
	Counts map[string]int64
}

type ColumnKind string

type ColumnType string

type Cursor string

type CursorEncoding struct {
	Scope  CursorScope
	Keys   []any
	PIT    string
	Scroll string
	State  map[string][]byte
}

type CursorPosition struct {
	// Keys are the ordered sort values of the last row of the previous page.
	// A provider resumes strictly after them.
	Keys []any

	// PIT identifies the backend snapshot this walk is reading, when it has
	// one. Empty means the walk sees the index as it changes.
	PIT string

	// Scroll identifies the OpenSearch scroll context this walk is reading.
	// It is mutually exclusive with PIT.
	Scroll string

	// State is what each processor carried forward from the previous page,
	// keyed by its label. A processor that folds rows across the whole result —
	// a dedupe, say — is only correct page by page if it can remember what it
	// has already emitted, and the cursor is where that memory lives, because
	// the cursor is the only thing a resumed request brings with it.
	State map[string][]byte
}

type CursorScope struct {
	Profile    string
	Provider   string
	Connection string
	Query      string
	Options    map[string]any
	Order      Order
	Params     map[string]any
	Roles      map[string]ParamRole
	Filters    []ColumnFilterValue

	// Now is the clock Params were resolved against. One walk resolves its date
	// math once — the first page picks the instant, every later page reads it
	// back off the cursor — so a rolling window names one result set for as long
	// as the walk lasts.
	Now time.Time
}

type DiagnosticDetail int

type DiagnosticError struct {
	Err         error
	Diagnostics *ProviderDiagnostics
}

type DiagnosticOptions struct {
	Provider string
	Query    string
	Options  map[string]any
	Detail   DiagnosticDetail
	Walk     bool
}

type Event struct {
	SessionID string    `json:"sessionId"`
	Sequence  int64     `json:"sequence"`
	Time      time.Time `json:"time"`
	Row       Row       `json:"row,omitempty"`
	Rows      []Row     `json:"rows,omitempty"`
	Error     string    `json:"error,omitempty"`
}

type ExecutionDetail struct {
	Summary     ExecutionSummary       `json:"summary"`
	Operations  []*ProviderDiagnostics `json:"operations,omitempty"`
	HAR         *har.File              `json:"har,omitempty"`
	Logs        []LogLine              `json:"logs,omitempty"`
	Probes      []CardinalityProbe     `json:"probes,omitempty"`
	Inspections []InspectionRecord     `json:"inspections,omitempty"`

	// HARSensitive reports that credential capture was switched on, so the
	// entries above hold live secrets. Stated rather than refused: it is a
	// deliberate operator setting for replay, and a console that hands the file
	// to a colleague has to know which kind of file it is.
	HARSensitive bool `json:"harSensitive,omitempty"`
}

type ExecutionSource struct {
	Surface string `json:"surface"` // profile | browser | sample | reconcile
	Profile string `json:"profile,omitempty"`
	Method  string `json:"method,omitempty"`
	Path    string `json:"path,omitempty"`
	// Query is the client's query string with credential-shaped values blanked,
	// kept so a console can offer "re-run with bodies" without the caller having
	// to reconstruct the request by hand.
	Query string `json:"query,omitempty"`
}

type ExecutionSummary struct {
	ID       string `json:"id"`
	Sequence int64  `json:"sequence"` // assigned by the store; the SSE event id

	Source     ExecutionSource `json:"source"`
	StartedAt  time.Time       `json:"startedAt"`
	DurationMS float64         `json:"durationMs"`
	Rows       int             `json:"rows"`
	Status     int             `json:"status,omitempty"`
	Error      string          `json:"error,omitempty"`

	// Level names the capture level this run was armed at. A console showing a
	// record it did not arm needs it to explain why the bodies are missing,
	// rather than implying the request made none.
	Level      string             `json:"level"`
	Operations []OperationSummary `json:"operations,omitempty"`
	Counts     RecordCounts       `json:"counts"`
}

type ExpressionOptions struct {
	// Scope selects the binding environment.
	Scope ExpressionScope

	// Rows are the rows the caller already holds. In ScopeRow and ScopeBoundary
	// each row produces a result; in ScopeBatch they are one group producing one.
	Rows []Row

	// Keep chooses the kept row of a ScopeBatch group: "first" (default) or
	// "last".
	Keep string
}

type ExpressionResult struct {
	// Index is the row this result came from, or 0 for a batch.
	Index int `json:"index"`

	Value any    `json:"value,omitempty"`
	Type  string `json:"type,omitempty"`
	Error string `json:"error,omitempty"`
}

type ExpressionScope string

type FilterBound struct {
	Value     any
	Inclusive bool
}

type FilterDef struct {
	// Name identifies the filter in the UI and in error messages. Required for a
	// quick filter, which a UI has to be able to select by name.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Description surfaces in the UI tooltip and listing.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Fields holds CEL predicates keyed by a label, AND-ed together. Each is
	// evaluated with the row bound as `row`.
	Fields map[string]string `json:"fields,omitempty" yaml:"fields,omitempty"`

	// Exclude inverts the match: matching rows are dropped rather than kept.
	Exclude bool `json:"exclude,omitempty" yaml:"exclude,omitempty"`

	// Hidden marks the filter always-on rather than togglable.
	Hidden bool `json:"hidden,omitempty" yaml:"hidden,omitempty"`
}

type FilterLookupProvider interface {
	LookupFilterValues(ctx context.Context, req ProviderRequest, binding ColumnFilterBinding, search string, limit int) ([]FilterOption, *Total, error)
}

type FilterOption struct {
	Value string
	Count int64
}

type FilterRange struct {
	Min *FilterBound
	Max *FilterBound
}

type FilterValueLookupRequest struct {
	Profile    Profile
	Input      map[string]any
	Key        string
	Search     string
	Limit      int
	Inspection InspectionOptions
}

type FinishOptions struct {
	Status int
	Err    error
}

type InspectionCacheSummary struct {
	Policy string `json:"policy"`
	State  string `json:"state"`
	Age    string `json:"age"`
	Cached bool   `json:"cached"`
}

type InspectionCardinality struct {
	Value    int64  `json:"value"`
	Relation string `json:"relation"`
	Cached   bool   `json:"cached"`
}

type InspectionField struct {
	ID           string                     `json:"id"`
	Name         string                     `json:"name"`
	Source       string                     `json:"source,omitempty"`
	DatabaseType string                     `json:"databaseType"`
	SemanticType string                     `json:"semanticType"`
	Cardinality  *InspectionCardinality     `json:"cardinality,omitempty"`
	Filter       InspectionFilterResolution `json:"filter"`
}

type InspectionFilterResolution struct {
	Label  string `json:"label"`
	Kind   string `json:"kind"`
	Origin string `json:"origin"`
	Field  string `json:"field,omitempty"`
	Lookup bool   `json:"lookup,omitempty"`
	Multi  bool   `json:"multi,omitempty"`
	Reason string `json:"reason"`
}

type InspectionLimit struct {
	Label  string `json:"label"`
	Value  int    `json:"value"`
	Origin string `json:"origin"`
}

type InspectionOptions struct {
	Refresh bool
}

type InspectionPaging struct {
	Selected    string            `json:"selected"`
	Supported   []string          `json:"supported"`
	Execution   string            `json:"execution"`
	Order       string            `json:"order"`
	Consistency string            `json:"consistency"`
	Note        string            `json:"note"`
	Limits      []InspectionLimit `json:"limits"`
}

type InspectionRecord struct {
	// Policy is the cache class (inspect.CacheClass) and Key the entry within
	// it. The key is a digest of the request, so it correlates two lookups
	// without disclosing what was in them.
	Policy string `json:"policy"`
	Key    string `json:"key"`

	// ElapsedMS is what this caller waited: ~0 for a hit, the whole fill for a
	// miss. That difference is the reason this record exists.
	ElapsedMS float64 `json:"elapsedMs"`

	Cached bool   `json:"cached"`
	State  string `json:"state,omitempty"` // fresh | stale
	// Refreshing says a background fill is running behind the value served.
	Refreshing bool  `json:"refreshing,omitempty"`
	AgeMS      int64 `json:"ageMs"`

	// RefreshError is a failed refresh behind a value that was still served;
	// Error is a failure the caller actually got. Distinct because the first is
	// a warning about staleness and the second is why the page has no filters.
	RefreshError string `json:"refreshError,omitempty"`
	Error        string `json:"error,omitempty"`
}

type InspectionResult struct {
	Name       string                 `json:"name"`
	Provider   string                 `json:"provider"`
	Connection string                 `json:"connection"`
	ScopeLabel string                 `json:"scopeLabel"`
	Scope      string                 `json:"scope"`
	Query      string                 `json:"query"`
	Status     string                 `json:"status"`
	StatusNote string                 `json:"statusNote"`
	DurationMS float64                `json:"durationMs,omitempty"`
	Cache      InspectionCacheSummary `json:"cache"`
	Fields     []InspectionField      `json:"fields"`
	Paging     InspectionPaging       `json:"paging"`
}

type InspectionStatus struct {
	Status  string                     `json:"status"`
	Message string                     `json:"message,omitempty"`
	Cache   []inspection.CacheMetadata `json:"cache,omitempty"`
	Counts  map[string]int64           `json:"counts,omitempty"`
}

type JSONPathFilterTarget struct {
	// Field is the backend field the selection applies to.
	Field string

	// Container names the field the path descends through to reach Field, when it
	// reaches it by picking one entry rather than by naming it. It is set only
	// alongside Where.
	//
	// Whether the backend can actually correlate Where with Field inside it is
	// not something the path can know — it depends on how the container is
	// mapped, which is why a profile declares it as filter.nested and the
	// connection browser reads it from the index mapping.
	Container string

	// Where is the constants the selection also requires, keyed by backend field.
	// It is what addresses one entry of a key/value tag list: the path fixes the
	// key and the operator picks the value.
	Where map[string]string
}

type KeyFunc func(Row) (string, error)

type KeyRange struct {
	From string `json:"from,omitempty" yaml:"from,omitempty"`
	To   string `json:"to,omitempty" yaml:"to,omitempty"`
}

type KeySpec struct {
	// Columns names the row keys whose values, joined in order, form the key.
	Columns []string `json:"columns,omitempty" yaml:"columns,omitempty"`

	// CEL is an expression evaluated against the row. The row is exposed as
	// both `row` and `span`, and every row key that is a valid CEL identifier
	// is bound as a top-level variable.
	CEL string `json:"cel,omitempty" yaml:"cel,omitempty"`
}

type LogLine struct {
	Sequence int64          `json:"sequence"`
	Time     time.Time      `json:"time"`
	Level    string         `json:"level"`
	Source   string         `json:"source"` // request | process
	Logger   string         `json:"logger,omitempty"`
	Event    string         `json:"event,omitempty"` // an observability.Event, when it came from one
	Message  string         `json:"message"`
	Values   map[string]any `json:"values,omitempty"`

	// RecordID and Operation say which execution, and which operation within it,
	// this line belongs to. Operation is 0 when the line is not attributable to
	// one — a line the request logged before any provider ran.
	RecordID  string `json:"recordId,omitempty"`
	Operation int    `json:"operation,omitempty"`
}

type NamedProcessor struct {
	// Name is the library key referenced by ProcessorSpec.Use (e.g.
	// "java.stacktrace").
	Name string `json:"name" yaml:"name"`

	// Title is the human label shown in the profile editor.
	Title string `json:"title,omitempty" yaml:"title,omitempty"`

	// Description explains what the preset does to a result set.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Spec is the processor type and its default configuration.
	Spec ProcessorSpec `json:"spec" yaml:"spec"`
}

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

type OperationResult struct {
	Diagnostics *ProviderDiagnostics
	Entries     []har.Entry
	Dropped     int
	Sensitive   bool
	Duration    time.Duration
	Rows        int
	Err         error
}

type OperationSummary struct {
	Index      int     `json:"index"` // 1-based, in the order they started
	Provider   string  `json:"provider"`
	Connection string  `json:"connection,omitempty"`
	Query      string  `json:"query,omitempty"`
	Method     string  `json:"method,omitempty"`
	URL        string  `json:"url,omitempty"`
	Status     int     `json:"status,omitempty"`
	DurationMS float64 `json:"durationMs"`
	Rows       int     `json:"rows"`
	Pages      int     `json:"pages,omitempty"`
	Error      string  `json:"error,omitempty"`
}

type Order []OrderBy

type OrderBy struct {
	// Column is the row key to order by.
	Column string `json:"column" yaml:"column"`

	// Desc orders this column descending.
	Desc bool `json:"desc,omitempty" yaml:"desc,omitempty"`

	// Unique asserts this column breaks all remaining ties, which is what makes
	// the order total. Paging requires the order to end in one.
	//
	// We validate that the author asserted a tiebreaker, not that the assertion
	// is true: whether a column is unique is a fact about their schema, not
	// about anything reachable from here. An untrue assertion produces the same
	// unstable paging an undeclared order does — but it does so having been
	// claimed, which is the difference between a bug and a silent default.
	Unique bool `json:"unique,omitempty" yaml:"unique,omitempty"`
}

type OrderingProvider interface {
	// NaturalOrder returns the order this provider would page by, given the
	// options the profile configured it with.
	NaturalOrder(config ProviderConfig) (Order, error)
}

type Page struct {
	Rows []Row

	// Styles are the evaluated cell styles for Rows, positionally parallel to
	// it. Nil when no column declares a Style.
	Styles []map[string]string

	// Next resumes after this Page's last row. Empty when the source is
	// exhausted, and never set by a provider that cannot cursor.
	//
	// A provider does not set this: it sets NextKeys and the engine mints the
	// token, so the format and its validation stay in one place rather than in
	// every backend.
	Next Cursor

	// NextKeys are the ordered sort values of this Page's last row, in the
	// order's column order. A cursoring provider sets them; ExecutePages turns
	// them into Next.
	NextKeys []any

	// PIT is the backend snapshot this page was read from, when the provider
	// opened one. It travels inside Next so the next request lands on the same
	// snapshot rather than on the index as it has since become.
	PIT string

	// Scroll is the OpenSearch scroll context that resumes this page. It is
	// mutually exclusive with PIT and travels inside Next for the same reason:
	// the next request must continue the backend cursor that produced this page.
	Scroll string

	// State is what each processor asked to carry into the next page, keyed by
	// label. Like PIT it travels inside Next rather than being returned to the
	// caller, so a resumed walk hands each processor back its own memory.
	// Providers never set it; ProcessPages does.
	State map[string][]byte

	// HasMore reports that the source had rows beyond this Page.
	//
	// It is the provider's answer rather than an inference from len(Rows),
	// because a short page and the end of the data are different facts that
	// look identical from the outside — and reading one as the other is how a
	// partial answer starts being presented as a complete one.
	HasMore bool

	// Total is the size of the whole result set when the source knows it.
	Total *Total

	// Truncated reports that the provider applied a cap of its own — a
	// configured limit, a backend default, a result-window ceiling — so a short
	// Page is never mistaken for the end of the data.
	//
	// This is distinct from HasMore: HasMore says the caller may ask for more,
	// Truncated says the source already decided not to give it. A caller that
	// asked for everything needs to know the difference.
	Truncated bool
}

type PageInfo struct {
	Mode          string `json:"mode"`
	Limit         int    `json:"limit"`
	Offset        int    `json:"offset,omitempty"`
	Cursor        Cursor `json:"cursor,omitempty"`
	NextCursor    Cursor `json:"nextCursor,omitempty"`
	HasMore       bool   `json:"hasMore"`
	Total         *int64 `json:"total,omitempty"`
	TotalRelation string `json:"totalRelation"`
	Consistency   string `json:"consistency"`
}

type PageProcessor interface {
	Processor
	ProcessPage(ctx context.Context, spec ProcessorSpec, page Page, state []byte) (Page, []byte, error)
}

type PageRequest struct {
	// Limit is the most rows one Page may carry. Required and positive.
	Limit int

	// Offset skips rows from the start of the order. Offset paging only.
	Offset int

	// Cursor resumes immediately after the position it encodes. Cursor paging
	// only.
	Cursor Cursor

	// Sort names the column this request orders by, overriding the order the
	// profile declared. It is a public column name, not a backend field: the
	// profile resolves it through the same target inference its filters use, so
	// a caller never has to know what the backend calls anything.
	//
	// The requested column leads the order rather than replacing it — the
	// profile's declared tiebreaker still has to end it, or paging past the
	// first page would have no stable meaning. See Profile.RequestedOrder.
	Sort string

	// Desc orders Sort descending. It is inert without one.
	Desc bool

	// Strategy chooses how to page when the request does not already say.
	//
	// It is needed because the first page of a cursor walk carries no cursor,
	// and so is indistinguishable from an offset page at position zero. Zero
	// means offset, which is the strategy a caller gets by not thinking about
	// it — and the one that can jump to an arbitrary page.
	Strategy PagingMode

	// Ceiling bounds the whole walk rather than one page: an export reads
	// forward to it and stops. Zero leaves the walk unbounded. A provider that
	// can push it down to the backend should, so the read stops where the export
	// does instead of continuing past it into rows nobody will receive.
	Ceiling int

	// SkipTotal releases the provider from reporting the size of the whole
	// result, and a provider that takes it up must report no total rather than a
	// zero one — Total.Relation tells those apart, and a caller reading "exactly
	// 0" while rows stream past is worse served than one reading "unknown".
	//
	// It exists because stating an exact total can cost the whole result: see
	// buildPagedSQL, where it is the difference between a walk that streams and
	// one that materializes. A page cannot waive it — a table has to say what it
	// is a page of — so this is an export's trade to make.
	SkipTotal bool

	// Diagnostics is non-nil only for an explicit debug execution. It is not a
	// paging input and is excluded from cursor scope.
	Diagnostics *ProviderDiagnostics `json:"-"`

	Inspection InspectionOptions `json:"-"`
}

type PagingMode uint8

type PagingProvider interface {
	Provider

	Pages(ctx context.Context, req ProviderRequest, page PageRequest) iter.Seq2[Page, error]

	// PagingModes reports which strategies this provider can serve, so a
	// request for one it cannot is refused before it runs rather than quietly
	// answered with another.
	PagingModes() PagingMode
}

type ParamDef struct {
	// Name is the parameter key, referenced as `{{.params.<Name>}}` (or
	// `$(.params.<Name>)`) in the query, in any provider option, or in the
	// connection.
	Name string `json:"name" yaml:"name"`

	// Label is the human-facing name for the FilterBar. Defaults to Name.
	Label string `json:"label,omitempty" yaml:"label,omitempty"`

	// Type drives validation/coercion. Defaults to string. Identifier is for a
	// SQL database, schema, table, or column name and is dialect-quoted rather
	// than bound as a value.
	Type ParamType `json:"type,omitempty" yaml:"type,omitempty"`

	// Role maps the parameter to a first-class table control. Empty defaults to
	// filter. A profile can rename the pager parameters by assigning limit and
	// offset roles; time-from/time-to form one server-backed date-range picker.
	Role ParamRole `json:"role,omitempty" yaml:"role,omitempty"`

	// Default is used when no value is supplied.
	Default any `json:"default,omitempty" yaml:"default,omitempty"`

	// Options enumerates the allowed values (an enum). When set, a supplied value
	// must be one of these. A list parameter validates every selected value
	// against them, and leaving them empty asks the provider for its distinct
	// values instead.
	Options []string `json:"options,omitempty" yaml:"options,omitempty"`

	// Field is the backend field an include/exclude selection binds to. Declaring
	// it makes a list parameter tri-state: a value prefixed with "!" excludes,
	// and both halves resolve into the same native filter clauses a column filter
	// produces. `params.<Name>` still carries only the includes, so a query
	// template and an esdsl multi-operand condition see a plain list either way.
	// Only a provider that applies native filters may declare it — Validate
	// rejects the rest, so an exclusion can never be silently dropped.
	Field string `json:"field,omitempty" yaml:"field,omitempty"`

	// Required fails execution when no value (and no Default) is supplied.
	Required bool `json:"required,omitempty" yaml:"required,omitempty"`

	// Description is shown as the FilterBar tooltip.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Template optionally rewrites the resolved value; "{value}" is replaced with
	// the supplied value (e.g. "{value}-api").
	Template string `json:"template,omitempty" yaml:"template,omitempty"`
}

type ParamRole string

type ParamType string

type ParameterizedQuery struct {
	Query       string
	Args        []any
	Identifiers []string
	UsedParams  []string
}

type Processor interface {
	// Type is the registry key (e.g. "sqlite.merge", "sqlite.recon").
	Type() string

	// Process transforms in according to spec and returns the new Result.
	Process(ctx context.Context, spec ProcessorSpec, in *Result) (*Result, error)
}

type ProcessorPreview struct {
	Input  []Row                   `json:"input"`
	Stages []ProcessorPreviewStage `json:"stages"`
}

type ProcessorPreviewStage struct {
	Index   int    `json:"index"`
	Label   string `json:"label"`
	Type    string `json:"type"`
	RowsIn  int    `json:"rowsIn"`
	RowsOut int    `json:"rowsOut"`
	Rows    []Row  `json:"rows"`
}

type ProcessorSpec struct {
	// Type is the registered processor key (e.g. "sqlite.merge", "sqlite.recon").
	// Optional when Use names a library entry, which supplies it.
	Type string `json:"type,omitempty" yaml:"type,omitempty"`

	// Use names a library processor (see RegisterNamedProcessor) whose type and
	// configuration this spec starts from — the processor equivalent of
	// Profile.Imports. Config set here is merged over the preset's, so a profile
	// can adopt a shared transform and still override a single key.
	Use string `json:"use,omitempty" yaml:"use,omitempty"`

	// Config is the processor-specific configuration.
	Config map[string]any `json:"config,omitempty" yaml:"config,omitempty"`
}

type Profile struct {
	// Name identifies the Profile (e.g. "SQL Server trace").
	Name string `json:"profile" yaml:"profile"`

	// Virtual profiles are generated runtime views over temporary data. They use
	// the normal profile execution surfaces but cannot be persisted.
	Virtual   bool       `json:"virtual,omitempty" yaml:"-"`
	ReadOnly  bool       `json:"read_only,omitempty" yaml:"-"`
	ExpiresAt *time.Time `json:"expires_at,omitempty" yaml:"-"`

	// Imports names profiles to merge from left to right before this profile is
	// executed. The authored profile remains unchanged in the profile store.
	Imports []string `json:"imports,omitempty" yaml:"imports,omitempty"`

	// Namespace scopes Kubernetes secret/configmap lookups and workload URLs used
	// by inline provider connections. When empty, the caller's namespace is used.
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

	// Icon overrides the glyph the UI shows for this Profile. It is an opaque
	// icon name resolved by the frontend's icon provider (e.g. "kubernetes",
	// "activemq"). When empty the provider type's own mark is used, so this only
	// needs setting where the backend type is not what the Profile is *about*.
	Icon string `json:"icon,omitempty" yaml:"icon,omitempty"`

	// Provider selects and configures the backend the Profile reads from.
	Provider ProviderConfig `json:"provider" yaml:"provider"`

	// Query is the provider-native query (SQL, PromQL, HTTP path, etc.). It may
	// reference declared params as `{{.params.<name>}}` (or `$(...)`), which are
	// rendered before the provider runs.
	Query string `json:"query,omitempty" yaml:"query,omitempty"`

	// Params declares the server-side filter parameters the Profile accepts. Their
	// resolved values are templated into Query (and context sub-queries) and drive
	// the per-profile FilterBar schema.
	Params []ParamDef `json:"params,omitempty" yaml:"params,omitempty"`

	// Columns declares the output columns in display order. When empty, the
	// provider's raw row keys are used.
	Columns []ColumnDef `json:"columns,omitempty" yaml:"columns,omitempty"`

	// Aliases are ordered CEL projections applied after processors. Later aliases
	// can reference values produced by earlier aliases.
	Aliases []AliasDef `json:"aliases,omitempty" yaml:"aliases,omitempty"`

	// Ignore removes processed row fields after aliases have been evaluated.
	Ignore []string `json:"ignore,omitempty" yaml:"ignore,omitempty"`

	// Filters are named row predicates evaluated after aliases, dropping rows
	// before they reach the columns. Hidden filters always apply; the rest are
	// togglable and inert until named in FilterEnabledParam.
	Filters []FilterDef `json:"filters,omitempty" yaml:"filters,omitempty"`

	// Processors consume raw provider rows in order before aliases, ignores, row
	// filters, columns, and styles.
	Processors []ProcessorSpec `json:"processors,omitempty" yaml:"processors,omitempty"`

	// Context defines secondary queries whose single result becomes a named side
	// object on the Result (e.g. Policy, Plan, Integrations).
	Context map[string]SubQuery `json:"context,omitempty" yaml:"context,omitempty"`

	// Output lists the render targets (e.g. table, html, xlsx, json).
	Output []string `json:"output,omitempty" yaml:"output,omitempty"`

	// Render selects how the frontend presents the result. "table" (the default,
	// when empty) uses the generic data table; "logs" maps the columns onto the
	// canonical LogsTable view (timestamp/level/pod/logger/thread/message, plus an
	// optional duration column) for trace/log profiles. Filtering stays server-side
	// via Params regardless of render mode.
	Render string `json:"render,omitempty" yaml:"render,omitempty"`

	// Trace declares the Profile as a long-running streaming session with
	// explicit setup/teardown; the provider must implement StreamProvider.
	// Mutually exclusive with Top.
	Trace *TraceSpec `json:"trace,omitempty" yaml:"trace,omitempty"`

	// Top declares the Profile as interval-sampled: the engine re-executes the
	// query per tick and each snapshot replaces the last. Mutually exclusive
	// with Trace.
	Top *TopSpec `json:"top,omitempty" yaml:"top,omitempty"`

	// Replay describes how a single result row is turned back into an outbound
	// HTTP request, so a failed or dropped record can be re-sent to its
	// destination without hand-assembling the call.
	Replay *ReplaySpec `json:"replay,omitempty" yaml:"replay,omitempty"`

	// Reconcile is the profile this one is normally joined against, and how:
	// the shared identity, the event-time column, and the per-side row bound.
	// It supplies the defaults of the `reconcile` action, so the join a profile
	// is habitually checked against is stored with it rather than retyped.
	Reconcile *ReconcileConfig `json:"reconcile,omitempty" yaml:"reconcile,omitempty"`

	// Limits are the row caps this Profile sets for itself: the page it returns
	// by default, the largest page a caller may ask for, and where an all-row
	// export stops. Each unset cap takes its default. None of them is the
	// query's own limit, which is a provider option.
	Limits *RowLimits `json:"limits,omitempty" yaml:"limits,omitempty"`

	// Order is the total order this Profile's rows are returned in, ending in a
	// column declared unique. It is what makes a page identifiable twice
	// running, so paging past the first page requires it: without one, two
	// executions of the same query may interleave rows differently and a second
	// page can repeat or skip rows from the first.
	Order Order `json:"order,omitempty" yaml:"order,omitempty"`
}

type ProfileKind string

type Provider interface {
	// Type is the registry key (e.g. "sql", "http", "prometheus").
	Type() string

	// Execute runs req against the backend and returns the raw rows.
	Execute(ctx context.Context, req ProviderRequest) ([]Row, error)
}

type ProviderConfig struct {
	// Type is the registered provider key (e.g. "sql", "http", "prometheus").
	Type string `json:"type" yaml:"type"`

	// Connection references a connection (connection://name) or an inline DSN/URL.
	// It is templated with the resolved params before the provider runs.
	Connection string `json:"connection,omitempty" yaml:"connection,omitempty"`

	// Options carries provider-specific knobs. Every string in it — however
	// deeply nested — is templated with the resolved params before the provider
	// runs, so `{{.params.x}}` and `$(.params.x)` work in any provider's options.
	Options map[string]any `json:"options,omitempty" yaml:"options,omitempty"`
}

type ProviderDiagnosticRequest struct {
	// Query is the statement the provider actually issued — the first page's,
	// for a walk. Rendered is the profile's query once the engine templated it.
	// A provider that records nothing of its own leaves them equal.
	Query    string `json:"query,omitempty"`
	Rendered string `json:"rendered,omitempty"`
	// Connection is the reference or DSN the request was rendered against,
	// stripped of credentials.
	Connection string         `json:"connection,omitempty"`
	Arguments  []any          `json:"arguments,omitempty"`
	Options    map[string]any `json:"options,omitempty"`
	Details    map[string]any `json:"details,omitempty"`

	// Method, URL and Headers are the HTTP exchange the request rode on, for a
	// provider that speaks HTTP. The endpoint is stated nowhere the author can
	// read it — a connection names a host and the provider builds the path — so
	// it is the first thing anyone reproducing the call by hand has to guess.
	Method  string            `json:"method,omitempty"`
	URL     string            `json:"url,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
}

type ProviderDiagnosticResponse struct {
	DurationMS   float64        `json:"durationMs,omitempty"`
	ReturnedRows int            `json:"returnedRows,omitempty"`
	Pages        int            `json:"pages,omitempty"`
	Details      map[string]any `json:"details,omitempty"`
	Preview      string         `json:"preview,omitempty"`
	ContentType  string         `json:"contentType,omitempty"`
	Truncated    bool           `json:"truncated,omitempty"`

	// Status and Headers are what the HTTP exchange answered, for a provider
	// that speaks HTTP.
	Status  int               `json:"status,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
}

type ProviderDiagnostics struct {
	Provider string                     `json:"provider"`
	Request  ProviderDiagnosticRequest  `json:"request"`
	Response ProviderDiagnosticResponse `json:"response,omitempty"`
	Error    string                     `json:"error,omitempty"`
	// contains filtered or unexported fields
}

type ProviderRequest struct {
	// Provider is the resolved registry key. It is carried so optional
	// diagnostics can identify the native backend without re-deriving it.
	Provider string

	// Connection references a connection (connection://name) or an inline DSN/URL.
	Connection string

	// Query is the provider-native query string.
	Query string

	// QueryArgs are values bound to placeholders derived from Query parameter
	// references. They never form part of Query itself.
	QueryArgs []any

	// QueryIdentifiers are validated names represented by opaque markers in
	// Query. The SQL provider quotes them for the resolved connection dialect.
	QueryIdentifiers []string

	// Options carries provider-specific knobs from ProviderConfig.Options.
	Options map[string]any

	// Params contains the validated profile parameters. Providers use this for
	// native query builders that cannot be expressed as a query template.
	Params map[string]any

	// ParamRoles maps each declared param name to its ParamRole, so a structural
	// query builder can fold role-carrying params (time-from, limit, …) into the
	// backend's native constructs instead of treating them as plain filters.
	ParamRoles map[string]ParamRole

	// TemplatedParams names the params consumed while templating Query, Options
	// or Connection. A provider with its own structural param binding counts
	// them as referenced, so a param interpolated into the options is not
	// reported as unused.
	TemplatedParams []string

	// Filters contains native include/exclude clauses bound to profile columns.
	Filters []ColumnFilterValue

	// Order is the Profile's declared result order. A provider that pages by
	// cursor needs it to sort by, and to cut the next position out of the last
	// row it returned.
	Order Order

	// Position is the decoded cursor this request resumes after, empty at the
	// start of a walk. The engine validates and decodes it, so a provider works
	// in key values and never in the token format.
	Position CursorPosition

	// Diagnostics is populated only for an explicitly requested debug run.
	// Providers record their final native request and response details here so
	// failures can return the same evidence as successful executions.
	Diagnostics *ProviderDiagnostics

	Inspection InspectionOptions
}

type QueryModel struct {
	// Table name
	Table string

	// Custom functions to map fields to clauses
	// Example: map["custom_field"] = func(ctx, tx, val) { ... custom query logic ... }
	Custom map[string]func(ctx context.Context, tx *gorm.DB, val string) (*gorm.DB, error)

	// List of jsonb columns that store a map.
	// These columns can be addressed using dot notation to access the JSON fields directly
	// Example: tags.cluster or tags.namespace.
	JSONMapColumns []string

	// List of columns that can be addressed on the search query.
	// Any other fields will be treated as a property lookup.
	Columns []string

	// Alias maps fields from the search query to the table columns
	// Example: map["created"] = "created_at"
	Aliases map[string]string

	// True when the table has a "tags" column
	HasTags bool

	// True when the table has a "labels" column
	HasLabels bool

	// True when the table has properties column
	HasProperties bool

	// FieldMapper maps the value of these fields
	// Example: map["created_at"] = DateMapper
	FieldMapper map[string]func(ctx context.Context, id string) (any, error)
}

type QueryParameterizationRequest struct {
	Query       string
	Params      map[string]any
	Definitions []ParamDef
}

type QueryParameterizer interface {
	ParameterizeQuery(request QueryParameterizationRequest) (ParameterizedQuery, error)
}

type ReconcileConfig struct {
	// Dest names the profile the source is reconciled against.
	Dest string `json:"dest" yaml:"dest"`

	// SourceFilters and DestFilters are independent because both profiles can
	// expose the same filter name with different values, or entirely different
	// filter surfaces.
	SourceFilters map[string]string `json:"sourceFilters,omitempty" yaml:"sourceFilters,omitempty"`
	DestFilters   map[string]string `json:"destFilters,omitempty" yaml:"destFilters,omitempty"`

	// Key and TimeColumn are promoted, so a stored reconcile reads as one flat
	// block rather than nesting the join spec inside itself.
	ReconcileSpec `yaml:",inline"`
}

type ReconcileMode string

type ReconcileProvenance struct {
	Mode           ReconcileMode           `json:"mode,omitempty"`
	BufferedReason string                  `json:"buffered_reason,omitempty"`
	Source         *ReconcileSideExecution `json:"source,omitempty"`
	Dest           *ReconcileSideExecution `json:"dest,omitempty"`
	RanAt          time.Time               `json:"ran_at"`
}

type ReconcileResult struct {
	// Config is what the run was asked to do — destination, key, per-side
	// filters, and the span of keys it covered (nil range means all of them).
	// Both sides are cut at the same keys, so a one-sided key inside the range
	// is a finding rather than an artefact of where the read stopped.
	Config        ReconcileConfig `json:"config"`
	SourceProfile Profile         `json:"-"`
	DestProfile   Profile         `json:"-"`
	Source        string          `json:"source"`
	Dest          string          `json:"dest"`
	Rows          []ReconcileRow  `json:"rows"`
	Stats         ReconcileStats  `json:"stats"`

	// Mode says how the two sides were joined, and BufferedReason says why a run
	// could not be merged — which is always something the author can change.
	Mode           ReconcileMode `json:"mode,omitempty"`
	BufferedReason string        `json:"buffered_reason,omitempty"`

	// Provenance is what each side actually ran. It is a record, not an input:
	// nothing in the join reads it, and it is the only trace of a query that
	// existed only at execution time.
	Provenance *ReconcileProvenance `json:"provenance,omitempty"`

	// The Truncated flags report a side whose backend cut the read short. A
	// one-sided key from an incomplete read is not a finding, which is why they
	// travel with the result.
	SourceTruncated bool `json:"source_truncated,omitempty"`
	DestTruncated   bool `json:"dest_truncated,omitempty"`
}

type ReconcileRow struct {
	Key    string          `json:"key"`
	Status ReconcileStatus `json:"status"`

	Source Row `json:"source,omitempty"`
	Dest   Row `json:"dest,omitempty"`

	SourceTime *time.Time     `json:"source_time,omitempty"`
	DestTime   *time.Time     `json:"dest_time,omitempty"`
	TimeDiff   *time.Duration `json:"time_diff,omitempty"`

	// Dup counters expose the cartesian expansion: index i of N rows sharing
	// this key on that side. Both are 1/1 when the key is unique.
	SourceDupIndex int `json:"source_dup_index,omitempty"`
	SourceDupCount int `json:"source_dup_count,omitempty"`
	DestDupIndex   int `json:"dest_dup_index,omitempty"`
	DestDupCount   int `json:"dest_dup_count,omitempty"`
}

type ReconcileRun struct {
	Source        Profile
	Dest          Profile
	Config        ReconcileConfig
	SourceFilters map[string]any
	DestFilters   map[string]any
}

type ReconcileSideExecution struct {
	Side     string `json:"side"`
	Profile  string `json:"profile"`
	Provider string `json:"provider"`

	// Query is the profile's query as authored, templates and all; the rendered
	// and native forms live on Diagnostics.Request.
	Query string `json:"query,omitempty"`

	// Filters are the resolved per-side filter values, sanitized the same way a
	// provider's options are.
	Filters map[string]any `json:"filters,omitempty"`

	Diagnostics *ProviderDiagnostics `json:"diagnostics,omitempty"`

	// Rows is what the join consumed from this side — after column transforms
	// and processors, and after a key range stopped the walk early.
	// Diagnostics.Response.ReturnedRows is what the provider handed over, so the
	// two differ whenever the profile drops or the range truncates.
	Rows  int `json:"rows"`
	Pages int `json:"pages,omitempty"`

	// DurationMS is wall clock spent reading this side. On a merged run the two
	// sides interleave and this includes the join's own time between pulls, so
	// BackendMS — the summed provider response time — is the number that
	// compares across modes.
	DurationMS float64 `json:"durationMs"`
	BackendMS  float64 `json:"backendMs,omitempty"`

	Truncated bool `json:"truncated,omitempty"`
}

type ReconcileSpec struct {
	// Range narrows the join to a span of keys. An empty range covers all of
	// them.
	//
	// It replaced a per-side row cap, which could not be made correct: two sides
	// cut at N rows each are two different sets of keys unless they happen to be
	// ordered identically, so the bound itself produced the one-sided keys the
	// run then reported as findings. A range cuts both sides at the same keys by
	// construction, so a key missing from one side inside it is missing.
	Range *KeyRange `json:"range,omitempty" yaml:"range,omitempty"`

	// Key derives the join identity from a row on either side. Cross-profile
	// joins normally need KeySpec.CEL, since the two sides rarely name the same
	// field the same way.
	Key KeySpec `json:"key" yaml:"key"`

	// TimeColumn names the row key holding each side's event time, used for the
	// source/dest timestamps and their difference. When empty it is discovered
	// from the profile column declared with Kind: timestamp; when no such column
	// exists, the time fields are simply omitted.
	TimeColumn string `json:"timeColumn,omitempty" yaml:"timeColumn,omitempty"`
}

type ReconcileStats struct {
	Matched    int `json:"matched"`
	OnlySource int `json:"only_source"`
	OnlyDest   int `json:"only_dest"`
	DupKeys    int `json:"dup_keys"`
}

type ReconcileStatus string

type RecordCounts struct {
	Operations  int `json:"operations"`
	HAREntries  int `json:"harEntries"`
	HARDropped  int `json:"harDropped"`
	LogLines    int `json:"logLines"`
	LogDropped  int `json:"logDropped"`
	Probes      int `json:"probes"`
	Inspections int `json:"inspections"`
}

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

type RecorderOptions struct {
	ID     string
	Level  logger.LogLevel
	Source ExecutionSource

	// RefreshInspection makes every metadata lookup this request performs rebuild
	// rather than read what is cached — the console's "re-run inspection".
	//
	// Scoped to the request on purpose: it costs this caller the rebuild and
	// leaves everyone else's reads alone, unlike flushing the cache.
	RefreshInspection bool

	// MaxLogLines and MaxHAREntries bound what one record retains; zero takes
	// the defaults above.
	MaxLogLines   int
	MaxHAREntries int
}

type RegistryOptions struct {
	// MaxSessions caps concurrently active (starting/running) sessions.
	MaxSessions int // default 5

	// MaxDuration caps any session's run duration.
	MaxDuration time.Duration // default 15m

	// MaxEvents caps any session's ring buffer.
	MaxEvents int // default 10000

	// RetainDone is how many terminal sessions stay in memory before the
	// oldest are pruned.
	RetainDone int // default 50

	// OnEvent/OnTransition are installed on every session started through
	// ExecuteStream — the persistence hooks.
	OnEvent      func(Event)
	OnTransition func(SessionInfo)
}

type ReplayBuildOptions struct {
	// Profile supplies the ReplaySpec and the column metadata used to describe
	// the selected row.
	Profile Profile

	// Rows is the executed result the row is selected from.
	Rows []Row

	// Select filters Rows by exact column value. It must narrow to exactly one
	// row; an ambiguous selection is an error, never a silent first-match.
	Select map[string]string

	// DefaultTarget is used when neither the profile nor TargetOverride names
	// one — typically an application-level default connection.
	DefaultTarget connection.HTTPConnection

	// TargetOverride is a connection reference (name or connection://...) or a
	// direct http(s) URL.
	TargetOverride string

	MethodOverride string
	URLOverride    string
	BodyOverride   string

	// Headers are merged over the profile's rendered headers.
	Headers map[string]string

	// MaxBodyPreview caps the previewed body. Defaults to 64KiB.
	MaxBodyPreview int
}

type ReplayExecuteResult struct {
	Preview         ReplayPreview     `json:"preview"`
	StatusCode      int               `json:"statusCode,omitempty"`
	Status          string            `json:"status,omitempty"`
	DurationMS      int64             `json:"durationMs"`
	ResponseHeaders map[string]string `json:"responseHeaders,omitempty"`
	ResponsePreview string            `json:"responsePreview,omitempty"`
	ResponseBytes   int               `json:"responseBytes,omitempty"`
}

type ReplayPreview struct {
	Profile       string            `json:"profile"`
	Row           ReplayRowSummary  `json:"row"`
	Target        string            `json:"target"`
	Method        string            `json:"method"`
	URL           string            `json:"url"`
	Headers       map[string]string `json:"headers"`
	BodyPreview   string            `json:"bodyPreview,omitempty"`
	BodyBytes     int               `json:"bodyBytes,omitempty"`
	BodyTruncated bool              `json:"bodyTruncated,omitempty"`

	// Hash covers the method, URL, headers and body. A caller previews, shows
	// the user what will be sent, then sends the hash back with the execute
	// request; a changed hash means the underlying data moved and the user
	// approved something other than what would now be sent.
	Hash string `json:"hash"`
	// contains filtered or unexported fields
}

type ReplayRowSummary struct {
	Index  int            `json:"index"`
	Values map[string]any `json:"values,omitempty"`
}

type ReplaySpec struct {
	// Kind selects the replay transport. Defaults to http.
	Kind string `json:"kind,omitempty" yaml:"kind,omitempty"`

	// Target is the connection the request is sent to. A relative URL requires
	// one; an absolute URL falls back to its own origin.
	Target connection.HTTPConnection `json:"target,omitempty" yaml:"target,omitempty"`

	// Method is a CEL expression yielding the HTTP method. Defaults to POST.
	Method string `json:"method,omitempty" yaml:"method,omitempty"`

	// URL is a CEL expression yielding an absolute URL or a path relative to
	// Target.
	URL string `json:"url,omitempty" yaml:"url,omitempty"`

	// Body is a CEL expression yielding the request body. Non-string values are
	// JSON-encoded.
	Body string `json:"body,omitempty" yaml:"body,omitempty"`

	// Headers maps header names to CEL expressions. A header whose expression
	// yields blank is omitted rather than sent empty.
	Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`
}

type Result struct {
	// Profile is the name of the Profile that produced this Result.
	Profile string `json:"profile,omitempty" yaml:"profile,omitempty"`

	// Rows are the primary tabular records.
	Rows []Row `json:"rows" yaml:"rows"`

	// Context holds named side objects keyed by SubQuery name.
	Context map[string]any `json:"context,omitempty" yaml:"context,omitempty"`

	// ColumnFilterKeys binds rendered columns to native server filter params.
	ColumnFilterKeys map[string]string `json:"-" yaml:"-"`

	// ColumnSortKeys binds rendered columns to the public name a request sorts
	// them by. A column absent from it cannot be ordered on, which is what makes
	// the table render its header inert rather than offering a sort the server
	// would refuse.
	ColumnSortKeys map[string]string `json:"-" yaml:"-"`

	// Styles holds each row's evaluated ColumnDef.Style classes, keyed by column
	// name and positionally parallel to Rows. It is render-only and deliberately
	// off the wire: styling a cell must not change the value an export carries.
	Styles []map[string]string `json:"-" yaml:"-"`

	// Truncated reports that this result is short of what the query had to
	// give — the Profile's export ceiling stopping the read, or the backend
	// applying a cap of its own. It travels with the Result so a partial answer
	// is never mistaken for a complete one.
	Truncated bool `json:"truncated,omitempty" yaml:"truncated,omitempty"`
}

type ResultColumn struct {
	Name         string              `json:"name"`
	Label        string              `json:"label,omitempty"`
	DatabaseType string              `json:"databaseType,omitempty"`
	Kind         ColumnKind          `json:"kind,omitempty"`
	FilterKey    string              `json:"filterKey,omitempty"`
	Filter       *ResultColumnFilter `json:"filter,omitempty"`
}

type ResultColumnFilter struct {
	Kind    string                     `json:"kind"`
	Options []ResultColumnFilterOption `json:"options,omitempty"`
	Lookup  bool                       `json:"lookup,omitempty"`
	Multi   bool                       `json:"multi,omitempty"`
	Unit    string                     `json:"unit,omitempty"`
}

type ResultColumnFilterOption struct {
	Value string `json:"value"`
}

type ResultColumnOptions struct {
	Profile       Profile
	DatabaseTypes map[string]string
}

type Row = map[string]any

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

type RowLimits struct {
	// PageSize is the page this profile returns when a caller asks for no size.
	PageSize int `json:"pageSize,omitempty" yaml:"pageSize,omitempty"`

	// MaxPageSize is the largest page a caller may ask this profile for.
	MaxPageSize int `json:"maxPageSize,omitempty" yaml:"maxPageSize,omitempty"`

	// MaxExportRows is where an all-row export of this profile stops.
	MaxExportRows int `json:"maxExportRows,omitempty" yaml:"maxExportRows,omitempty"`
}

type SampleFilterValuesOptions struct {
	Params        map[string]any
	Filters       map[string]string
	FilterColumns []ColumnDef
	FilterKey     string
	Search        string
	Limit         int
	Inspection    InspectionOptions
}

type SampleOptions struct {
	Params            map[string]any
	Filters           map[string]string
	FilterColumns     []ColumnDef
	InspectionColumns []ColumnDef
	Page              PageRequest
	PreviewProcessors bool
	Inspection        InspectionOptions
}

type SampleResolution struct {
	PagingModes    string    `json:"pagingModes"`
	NativePaging   bool      `json:"nativePaging"`
	Pageable       bool      `json:"pageable"`
	PageableReason string    `json:"pageableReason,omitempty"`
	Order          Order     `json:"order"`
	Limits         RowLimits `json:"limits"`
}

type SampleResult struct {
	Rows             []Row                `json:"rows"`
	Columns          []ColumnDef          `json:"columns"`
	ResultColumns    []ResultColumn       `json:"resultColumns"`
	RenderedQuery    string               `json:"renderedQuery"`
	Truncated        bool                 `json:"truncated,omitempty"`
	DurationMS       float64              `json:"durationMs"`
	Pagination       PageInfo             `json:"pagination"`
	Diagnostics      *ProviderDiagnostics `json:"diagnostics,omitempty"`
	ProcessorPreview *ProcessorPreview    `json:"processorPreview,omitempty"`
	Inspection       *InspectionStatus    `json:"inspection,omitempty"`
	Resolution       SampleResolution     `json:"resolution"`
}

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

type SessionInfo struct {
	ID         string         `json:"id"`
	Profile    string         `json:"profile"`
	Kind       ProfileKind    `json:"kind"`
	State      SessionState   `json:"state"`
	Params     map[string]any `json:"params,omitempty"`
	Error      string         `json:"error,omitempty"`
	EventCount int64          `json:"eventCount"`
	StartedAt  time.Time      `json:"startedAt"`
	StoppedAt  *time.Time     `json:"stoppedAt,omitempty"`
}

type SessionOptions struct {
	ID      string
	Profile Profile
	Params  map[string]any

	// MaxEvents caps the in-memory ring buffer (already clamped by the caller).
	MaxEvents int

	// OnEvent is called synchronously for every emitted event (before ring
	// eviction can drop it) — the persistence hook.
	OnEvent func(Event)

	// OnTransition is called synchronously after every state change.
	OnTransition func(SessionInfo)
}

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

type SessionState string

type SortBinding struct {
	// Column is the public column name, which is what the client sorts by.
	Column string

	// Field is the backend field the order is compiled against.
	Field string
}

type SortingProvider interface {
	// SupportsRequestSort reports whether an order named by the request is
	// applied rather than ignored.
	SupportsRequestSort() bool
}

type StreamProvider interface {
	Provider

	// Stream runs req, calling emit for each row until ctx is cancelled or the
	// source ends. It blocks; a nil return means the source ended normally.
	Stream(ctx context.Context, req ProviderRequest, emit func(Row)) error
}

type SubQuery struct {
	Provider ProviderConfig `json:"provider" yaml:"provider"`
	Query    string         `json:"query,omitempty" yaml:"query,omitempty"`
}

type TopSpec struct {
	// Interval is the sampling period (default 5s, floor 1s).
	Interval types.Duration `json:"interval,omitempty" yaml:"interval,omitempty"`

	// MaxDuration bounds the session; the server may clamp it lower.
	MaxDuration types.Duration `json:"maxDuration,omitempty" yaml:"maxDuration,omitempty"`

	// SortBy names the column each snapshot is sorted by (descending).
	SortBy string `json:"sortBy,omitempty" yaml:"sortBy,omitempty"`

	// Limit truncates each snapshot after sorting.
	Limit int `json:"limit,omitempty" yaml:"limit,omitempty"`
}

type Total struct {
	Value int64
	Exact bool
}

type TraceBufferSpec struct {
	MaxRows int            `json:"maxRows,omitempty" yaml:"maxRows,omitempty"`
	MaxWait types.Duration `json:"maxWait,omitempty" yaml:"maxWait,omitempty"`
}

type TraceSpec struct {
	// MaxDuration bounds the session; the server may clamp it lower.
	MaxDuration types.Duration `json:"maxDuration,omitempty" yaml:"maxDuration,omitempty"`

	// MaxEvents caps the in-memory event ring buffer.
	MaxEvents int `json:"maxEvents,omitempty" yaml:"maxEvents,omitempty"`

	// Buffer batches raw provider rows before running the full processor chain.
	// Without it every trace processor must implement PageProcessor.
	Buffer *TraceBufferSpec `json:"buffer,omitempty" yaml:"buffer,omitempty"`

	// Follow marks a session promoted from a plain query profile by ?follow=true
	// rather than one an author declared. It is set by Follow and is not part of
	// the document, which is why it does not serialize: a profile cannot ask to
	// be followed, a request can.
	//
	// It exists because the two kinds want opposite things from a closing time
	// bound. A followed profile is being read from now onward, so an end instant
	// is the moment it would stop rather than a bound on what it reads, and
	// openTailWindow drops it. A declared trace is an author's whole statement of
	// what the session is, and silently discarding half of a window they wrote
	// down would be a worse answer than honouring it.
	Follow bool `json:"-" yaml:"-"`
}