queryengine

type ControlI interface {
	// Kill asks the engine to stop the run named by runID.
	//
	// It is a request, not a guarantee, and a nil error is NOT evidence
	// that anything was stopped: a run that had already finished, or that
	// never existed, is indistinguishable from one that was killed. As
	// everywhere else in this contract, terminal truth comes from the
	// result path.
	Kill(ctx context.Context, runID string) (err error)
}

type DeliveryI interface {
	// Deliver submits req and returns its result stream. It returns once
	// the engine has accepted the run and said what it is delivering; the
	// frames themselves arrive as the consumer pulls them.
	//
	// err is non-nil only when the request was REJECTED before execution:
	// it is malformed, or it asks for something this engine does not do.
	// Those are the caller's to fix, and st is nil.
	//
	// Everything else is an outcome of the run and arrives as a terminal
	// frame — including a statement the engine refused, a worker that died,
	// and a transport that never connected. That split is what lets a
	// consumer stop branching on which engine ran the query: outcomes are
	// read in one place, and the one thing a caller must not do is ignore
	// the terminal.
	Deliver(ctx context.Context, req Request) (st StreamI, res Result, err error)
}

type ObservationI interface {
	// Watch registers a run for observation. Where the observations go —
	// a bus subject family, typically — is the implementation's business
	// and its consumers'; this contract covers only the registration.
	Watch(runID string) (err error)
	// Unwatch deregisters a run. The caller decides when: at the terminal.
	Unwatch(runID string)
}

type Request struct {
	// RunID is the client-minted identity of the run (R7), from
	// [runid.Mint]. It is what live progress, query_log facts, pins and a
	// cancellation all name, so an engine that can register it should be
	// given one. Optional, because an engine may have nowhere to put it —
	// a one-shot worker's system tables die with the process — but it must
	// satisfy [runid.Valid] when set.
	RunID string
	// SQL is the finalized outgoing statement: what the engine will
	// actually receive, after every client-side rewrite. Adapters do not
	// rewrite it, with the single exception of the prelude an engine needs
	// to bind Inputs.
	SQL string
	// Format is the ClickHouse FORMAT the delivered bytes are in
	// ("ArrowStream", "JSONEachRow", …). Empty takes the engine's default,
	// and then [Result.ContentType] is the only thing that says what came
	// back.
	Format string
	// Params binds `{name:Type}` placeholders by BARE name — "limit", not
	// "param_limit". Adapters apply their engine's prefixing. Typed
	// substitution stays the engine's job, as on the HTTP interface.
	Params map[string]string
	// Settings are per-run engine settings, passed through verbatim. They
	// are the escape hatch for everything this struct deliberately does not
	// model (`log_comment`, `replace_running_query`, a session setting),
	// and an adapter REJECTS a key it owns itself rather than letting a run
	// carry two identities or two formats.
	Settings map[string]string
	// Inputs binds in-memory datasets as temporary tables, keyed by table
	// name; each value is Arrow IPC in the `Arrow` file format (with
	// footer). An engine that cannot accept them refuses the request rather
	// than dropping them, because the alternative is a query failing
	// against the engine with "unknown table" and the reason being
	// invisible.
	Inputs map[string][]byte
	// Cap is the row limit the request declares on ITSELF, and is what
	// makes a truncated result recognisable as truncated (R9). Zero
	// declares none. A cap the engine applies by its own default, or that
	// a quota imposes, is not visible from here and is not claimed.
	Cap RowCap
	// Sensitivity is what the run TOUCHES, and is the R6 sensitivity axis
	// of the E9 dispatch label. A run naming sealed data is
	// [SensitivityConfined] and may only be executed where its plaintext is
	// allowed to go; everything else is ordinary. An engine that may not
	// serve confined runs refuses one rather than executing it.
	//
	// The label is derived by whoever knows what the statement names — a
	// registry lookup, not a guess over SQL text — and rides here so the
	// engine can refuse independently of whatever placed the run.
	Sensitivity SensitivityE
	// Cacheable is the caller asserting that the statement is
	// deterministic, so an engine holding a result cache may answer from it
	// instead of executing. The assertion is the caller's to get right —
	// now(), rand(), a network function and a mutable dictionary each make
	// it false — and it is advisory in the same way [OnProgress] is: an
	// engine without a cache ignores it, and [Result.CacheHit] reports what
	// actually happened rather than what was asked for.
	Cacheable bool
	// OnProgress, when set, receives inflight observations for engines that
	// can deliver them on the request's own channel. Advisory in the
	// strongest sense: it may never fire, it is not a substitute for the
	// terminal frame, and its absence says nothing about the run (R8).
	// Called from whatever goroutine the engine reads on — keep it cheap
	// and safe to call concurrently with the caller's own draining.
	//
	// It is a callback and not a progress frame for a reason worth knowing:
	// on the ClickHouse HTTP interface the ticks arrive inside the
	// still-open response-header block, which is to say BEFORE the stream
	// they would have to be frames of exists. Making them frames would mean
	// replaying them after the headers completed, by which time the only
	// thing they had — liveness — is gone. Frames are how a party that is
	// NOT the connection holder sees progress; that is [ObservationI].
	OnProgress func(p runstream.Progress)
}

type Result struct {
	// ContentType is the media type of the delivered bytes as the engine
	// reported it. Empty when the engine did not say — derive it from
	// [Request.Format] then, and know that is an assumption.
	ContentType string
	// Summary is the run's counters as known when delivery began. On a
	// synchronous engine that is the response header, which may predate the
	// last byte; treat it as a report, not as an audit.
	Summary Summary
	// CacheHit is true when the engine answered from a result cache and no
	// execution happened. Advisory: an engine without a cache always
	// reports false, which is not evidence of a miss.
	CacheHit bool
}

type RowCap struct {
	// MaxResultRows is `max_result_rows`; zero means unset.
	MaxResultRows uint64
	// Breaks is true when `result_overflow_mode` is `break`. ClickHouse
	// defaults to `throw`, which raises instead of truncating and is
	// already loud, so only `break` can produce a silently short result.
	Breaks bool
}

type SensitivityE uint8

type StreamI interface {
	// Next advances to the next frame. ok is false once the stream is
	// exhausted, which says nothing on its own about how the run ended —
	// consult the terminal frame, or its absence.
	Next() (f runstream.Frame[[]byte], ok bool)
	// Err reports a transport failure that ended the stream early. It is
	// informational: a live adapter that observed a failure also yields a
	// failed terminal frame, and the frame is what the contract makes
	// authoritative.
	Err() (err error)
	// Close releases the stream's resources. It must be called even by a
	// consumer that drained to the end, and is safe to call more than once.
	Close() (err error)
}

type Summary struct {
	ReadRows        uint64
	ReadBytes       uint64
	WrittenRows     uint64
	WrittenBytes    uint64
	TotalRowsToRead uint64
	ResultRows      uint64
	ResultBytes     uint64
	ElapsedNs       uint64
	MemoryUsage     uint64
}