obsdb

type Aggregator interface {
	// Stats answers StatsQuery: one StatsGroup per key of q.By over the
	// runs started in [q.Since, q.Until) that q.RunQuery's filters keep,
	// with a per-bucket series. ErrInvalidStats for a query outside
	// CheckStats' bounds.
	Stats(ctx context.Context, q StatsQuery) (StatsPage, error)
	// ErrorCounts counts the distinct error texts (RunRow.Err, never
	// "") of the runs q matches — Searcher.Search's match exactly, its
	// sort, offset and limit not read — most frequent first (ties by
	// text), at most MaxErrorTexts of them; capped is true when the
	// match held more distinct texts than that. ErrorClasses folds the
	// answer into the error_class facet, ErrorClassTexts resolves one
	// class back to its texts (RunQuery.Errs).
	ErrorCounts(ctx context.Context, q SearchQuery) (counts []ErrorCount, capped bool, err error)
}

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

type Batch struct {
	Spans   []Span
	Records []Record
}

type BreakpointProvenanceStore interface {
	// PutBreakpointSet is PutBreakpoints keeping set.SetAt and set.SetBy
	// (a clear — empty Tools — keeps neither).
	PutBreakpointSet(ctx context.Context, runtimeID string, set BreakpointSet) error
	// BreakpointSet is Breakpoints with the stored provenance (zero
	// SetAt, empty SetBy when none was kept). Tools never nil when stored.
	BreakpointSet(ctx context.Context, runtimeID string) (BreakpointSet, bool, error)
}

type BreakpointSet struct {
	Tools []string
	// SetAt is when Studio delivered the set (zero: not known).
	SetAt time.Time
	// SetBy is the surface the set came through: the Studio page that
	// sent it ("runtimes"), else "api" for a PUT that named none ("":
	// not known).
	SetBy string
}

type CommandQuery struct {
	ID        string
	RuntimeID string
	RunID     string
	States    []string // any of these states; nil and empty both mean no filter
	Limit     int
}

type CommandStore interface {
	// PutCommand writes c, replacing any row under c.ID whole (an
	// upsert: the caller writes the row it holds). A zero Created or
	// Updated is stamped with the current time — on every write, so
	// the caller carries the Created it read back into each upsert; a
	// zero one would move the row to the front of the newest-first
	// order. ErrInvalidCommand for an empty ID or a State outside the
	// five.
	PutCommand(ctx context.Context, c StoredCommand) error
	// Commands answers the rows q selects, newest Created first (ties
	// by ID, descending). An empty query answers every row.
	Commands(ctx context.Context, q CommandQuery) ([]StoredCommand, error)
	// PutRoute writes r, replacing any route of r.RunID. ErrInvalidCommand
	// for an empty RunID or RuntimeID. A zero Seen is stamped with the
	// current time on every write.
	PutRoute(ctx context.Context, r RunRoute) error
	// Route answers the route of runID; false when none is stored.
	Route(ctx context.Context, runID string) (RunRoute, bool, error)
	// PutBreakpoints replaces runtimeID's breakpoint set whole; an empty
	// tools stores the empty set (a clear), which Breakpoints then
	// answers as stored. ErrInvalidCommand for an empty runtimeID.
	PutBreakpoints(ctx context.Context, runtimeID string, tools []string) error
	// Breakpoints answers runtimeID's stored set (never nil when
	// stored); false when none was ever stored — distinct from a stored
	// empty set, which a registering runtime's own set must not replace.
	Breakpoints(ctx context.Context, runtimeID string) ([]string, bool, error)
	// PutRuntime writes r, replacing any row under r.ID whole. Zero
	// Registered or LastSeen is stamped with the current time on every
	// write, so the caller carries Registered into each upsert.
	// ErrInvalidCommand for an empty ID.
	PutRuntime(ctx context.Context, r StoredRuntime) error
	// Runtimes answers every stored runtime, most recently seen first
	// (ties by ID).
	Runtimes(ctx context.Context) ([]StoredRuntime, error)
	// DeleteRuntime removes runtimeID's row and its breakpoint set —
	// Studio's "forget" of a runtime that is gone (U20.1). Its commands
	// and routes stay: they are history, and PruneCommands bounds them.
	// An id with nothing stored is no error. ErrInvalidCommand for an
	// empty runtimeID.
	DeleteRuntime(ctx context.Context, runtimeID string) error
	// PruneCommands bounds the store, the in-memory runtime server's
	// rule made durable, and answers how many commands it deleted:
	//
	//   - a terminal command (CommandTerminal) whose Updated is before
	//     before is deleted;
	//   - then, while more than keep commands remain (keep ≤ 0: no
	//     count bound), the
	//     oldest terminal ones by Created go — a queued or accepted
	//     command is never deleted, whatever its age or the count;
	//   - a route goes when it names a command (CommandID) no longer
	//     stored, or when its Seen is before before and no queued or
	//     accepted command names its run;
	//   - a runtime goes when its LastSeen is before before, no queued
	//     or accepted command is addressed to it and its breakpoint set
	//     is absent or empty (that set goes with it);
	//   - an empty breakpoint set no runtime row names goes when it was
	//     last written before before; a non-empty one stays, as a
	//     runtime holding one does.
	//
	// The terminal commands go in bounded passes (SweepBatch rows on
	// SQLite, each its own transaction, ctx checked between them); on
	// an error the passes before it stay deleted and are counted. On
	// ClickHouse the prune is not atomic with concurrent Put* calls —
	// a Put racing it keeps its own version, but each rule decides
	// from what it read — so the caller serialises PruneCommands with
	// its own writes. On ClickHouse the count names the commands a
	// rule selected; a command a racing Put rewrote is counted though
	// it stays.
	PruneCommands(ctx context.Context, before time.Time, keep int) (int, error)
}

type Compaction struct {
	Scope        string
	Hash         string // weft.compaction.hash
	Index        int64
	Step         int
	FromSeq      int64
	ToSeq        int64
	Messages     json.RawMessage
	Reason       string
	Replaced     int
	Entries      int
	TokensBefore int64
	TokensAfter  int64
}

type DB interface {
	// Write stores one batch, idempotent on (run, record kind, pos)
	// and (trace, span): a retried transport's duplicate is a no-op.
	// Deltas are counted, never stored; heartbeats are never stored —
	// they only move the run's last-seen (DeriveStatus's clock).
	Write(ctx context.Context, b Batch) error

	Runs(ctx context.Context, q RunQuery) (RunPage, error)
	Run(ctx context.Context, id string) (RunDetail, error) // ErrNotFound
	// Events pages a run's durable events in position order. after is
	// exclusive — pass -1 to read from the start (0 would skip position
	// 0, the run_start) and EventPage.NextAfter to continue. limit: 0 =
	// 100, max 1000.
	Events(ctx context.Context, runID string, after int64, limit int) (EventPage, error)
	// Transcript returns the messages bodies in index order, one per
	// growth messages record (a compaction view, ADR 0028 §8, is not
	// transcript: see Compactions), read through DedupTranscript — so
	// they concatenate to the transcript the run held.
	Transcript(ctx context.Context, runID string) ([]json.RawMessage, error)
	// TranscriptBatches is Transcript with what each messages record
	// stored beside its body: its index, the step it joined
	// (weft.step.index, -1 when the record carried none) and whether
	// it is the run's input (weft.messages.input). The bodies are
	// Transcript's, through DedupTranscript, one per record.
	TranscriptBatches(ctx context.Context, runID string) ([]TranscriptBatch, error)
	// Compactions returns the compactions a run's records name (ADR
	// 0028 §8): every run-scope view in index order, then the session
	// markers thread filed under the run, in emission order — what a reader needs to draw the compaction and
	// rebuild a request's messages. Transcript and TranscriptBatches
	// never include a view: the plain transcript is growth records
	// only. A messages record with an unknown weft.messages.reason is
	// an error. ErrNotFound for an unknown run; empty, not an error,
	// for a run that never compacted.
	Compactions(ctx context.Context, runID string) ([]Compaction, error)

	// The request record (ADR 0028). Requests pages a run's request
	// records in index order, one per model-call attempt
	// (RequestQuery). Prompt and Tools return the run's prompt or tools
	// record of one hash: ErrNotFound when the run holds none, as a
	// *HoleError when the reason is known (not_recorded, stripped,
	// gap — ExplainMissing). Catalogs returns every tools record of the
	// run, one per hash, in index order; a content-off run has none.
	// All four answer ErrNotFound for an unknown run.
	Requests(ctx context.Context, runID string, q RequestQuery) ([]RequestRecord, error)
	Prompt(ctx context.Context, runID, hash string) (PromptRecord, error)
	Tools(ctx context.Context, runID, hash string) (ToolsRecord, error)
	Catalogs(ctx context.Context, runID string) ([]ToolsRecord, error)
	RunSpans(ctx context.Context, runID string) ([]Span, error)
	// OtherLogs pages a run's app log records — the non-weft records
	// the writers store beside weft's (other_logs on SQLite, otel_logs
	// on ClickHouse), attributed to the run through the spans they were
	// emitted under — in time order (LogQuery, ReadOtherLogs), with
	// what the read could not show (LogPage: partial while running,
	// lines under a never-stored span, the candidate cap).
	// ErrNotFound for an unknown run; empty Logs, not nil, for a run
	// with no app logs; a *HoleError (Kind "logs", HoleNotRecorded) for
	// a finished run with no span to attribute them through.
	OtherLogs(ctx context.Context, runID string, q LogQuery) (LogPage, error)
	// CountLogs counts a run's app log records at or above minSeverity
	// (an OTLP severity number; 13 is WARN) with OtherLogs'
	// attribution, in one scan the backend narrows by severity
	// (CountOtherLogs): the run document's log_warn / log_error without
	// paging every line's body. Capped past MaxLogCandidates such lines
	// (the counts are floors). OtherLogs' errors.
	CountLogs(ctx context.Context, runID string, minSeverity int) (LogCounts, error)
	Trace(ctx context.Context, traceID string) ([]Span, error) // empty, not an error, for an unknown trace
	// Traces lists traces — weft and non-weft alike, one row per trace
	// id the spans table holds — newest first (TraceQuery, TracePage):
	// the row is computed from the trace's spans alone, so a trace
	// whose root never arrived is listed with Root nil.
	Traces(ctx context.Context, q TraceQuery) (TracePage, error)

	Sessions(ctx context.Context, q SessionQuery) (SessionPage, error)
	Session(ctx context.Context, id string) (SessionDetail, error)
	ResolvePublicID(ctx context.Context, publicID string) (sessionID string, err error)

	// The playground's saved experiments (WEFT-PLAYGROUND §10.4,
	// PQ4): the definition rows keyed by the weft.experiment.id the
	// runs carry — one small table beside runs.
	SaveExperiment(ctx context.Context, e Experiment) error // upsert by ID
	Experiments(ctx context.Context) ([]Experiment, error)  // newest update first
	Experiment(ctx context.Context, id string) (Experiment, error)

	// Deletion and retention (plan A7, §13.13). Every one touches the
	// observability tables alone — never another module's tables
	// sharing the file (thread's sessions in one SQLite file stay
	// byte-identical) and never the experiments table (its definitions
	// name runs, they do not hold them).
	//
	// DeleteRun removes a run and its subagent children — every run
	// whose ParentRunID chain reaches id — with everything stored under
	// them: records (deltas kept by KeepDeltas included), the search
	// index rows, the spans named by DeletedSpans and the app log
	// records emitted under those spans; the CommandStore rows
	// (commands, run_routes, breakpoints, runtimes) are never touched.
	// The derived run of a stock agent under the run's tool goes too
	// (docs/record-contract.md §9): it is no child of the run — the
	// derivation stops at weft spans — but its root is among the spans
	// deleted, and its row would otherwise outlive every span it was
	// derived from (StockRunsOf).
	// ErrNotFound for an unknown id.
	// A run still being written is deleted as it stands: a later write
	// for it starts a new run row from what that write carries.
	DeleteRun(ctx context.Context, id string) error
	// DeleteSession is DeleteRun for every run carrying the session id
	// (weft.session.id), children included. The app's own conversation
	// store is not obsdb's and is never touched. ErrNotFound when no
	// run carries the id.
	DeleteSession(ctx context.Context, id string) error
	// Sweep deletes, as DeleteRun does, the runs whose LastSeen is
	// before the cutoff and whose status is not running (succeeded,
	// failed or interrupted — a run silent past InterruptedAfter is
	// interrupted, so it counts as not running and is swept), with
	// their children that are not running either; a running child keeps
	// its own subtree and is swept on its own once it ends. Until then
	// that child of a swept parent is listed only under RunQuery's
	// ParentRunID "*" (the API's all=1 / parent=*), never among the
	// top-level runs. It works in passes of at most SweepBatch roots
	// (each with its subtree), so a large backlog never holds the
	// writer for the whole sweep; ctx is checked between passes. It
	// returns how many runs it deleted, children and the derived runs
	// DeleteRun takes beside them counted, over every pass — on an
	// error, the passes before it stay deleted.
	Sweep(ctx context.Context, before time.Time) (int, error)
	// Vacuum gives the space deletions freed back: SQLite runs VACUUM
	// (the whole file is rewritten, other modules' tables with their
	// contents unchanged); ClickHouse runs OPTIMIZE TABLE … FINAL on
	// the tables deletions mutate, which merges every part — an
	// operator's command, heavy on a large database.
	Vacuum(ctx context.Context) error

	Close() error
}

type ErrorClassCount struct {
	Class string
	Count int64
}

type ErrorCount struct {
	Err   string
	Count int64
}

type EventPage struct {
	Events    []PosEvent
	NextAfter *int64
	// Done: every stored event was returned and the run is terminal —
	// its run_finish is stored, its invoke_agent span ended with Error,
	// or its invoke_agent span is stored (RunRow.RootEnded) and nothing
	// was heard from the run for over InterruptedAfter (the settling
	// window, DeriveSettling: records that trail a stored root are given
	// that long to land, so a run whose run_finish was lost still ends
	// a poll that waits for Done). An interrupted run (no root, stale)
	// is not Done here: a reader that follows it decides from the row's
	// derived Status.
	Done bool
	Gaps []int64
}

type Experiment struct {
	ID, Name, Agent  string
	Created, Updated time.Time
	Variants         []ExperimentVariant
	Inputs           []ExperimentInput
	// PassPredicate is the experiment's pass predicate (UX plan D8), as
	// the playground sent it: obsdb stores and returns it verbatim and
	// reads nothing into it (Studio bounds its length). "" when none,
	// and on an experiment saved before obsdb kept it.
	PassPredicate string
	// ExperimentCommand is the rest of the §5.1 command the matrix
	// sent, so a saved experiment reopens as the form that ran it.
	// Zero on an experiment saved before obsdb kept it.
	ExperimentCommand
}

type ExperimentCommand struct {
	Engine          string          `json:"engine,omitempty"`           // live | scripted
	SideEffects     string          `json:"side_effects,omitempty"`     // substitute | park | allow
	Thread          string          `json:"thread,omitempty"`           // ephemeral | fork
	FromStep        *int            `json:"from_step,omitempty"`        // the step every cell continues from
	SourceRunID     string          `json:"source_run_id,omitempty"`    // the run the cells replay from
	TranscriptEdits json.RawMessage `json:"transcript_edits,omitempty"` // the list as sent
}

type ExperimentInput struct {
	Key         string `json:"key"`
	SourceRunID string `json:"source_run_id,omitempty"`
	Text        string `json:"text,omitempty"`
	FromStep    *int   `json:"from_step,omitempty"`
}

type ExperimentVariant struct {
	Key         string          `json:"key"`
	Overrides   json.RawMessage `json:"overrides,omitempty"`
	Engine      string          `json:"engine,omitempty"`
	SideEffects string          `json:"side_effects,omitempty"`
	Thread      string          `json:"thread,omitempty"`
}

type Frame struct {
	Kind   string  // "record" | "run" | "attempt"
	Record *Record // Kind == record; Weft derived
	Weft   Weft
	Run    *RunRow // Kind == run
	Span   *Span   // Kind == attempt; Weft derived
	Seq    uint64  // hub-wide, monotonic: the SSE id and the resume cursor
}

type Hole string

type HoleCause string

type HoleError struct {
	Kind string // "prompt", "tools" or "logs"
	Hash string
	Hole Hole
}

type Hub interface {
	Publish(ctx context.Context, f Frame)
	Subscribe(ctx context.Context, sel Selector, after uint64) (<-chan Frame, error)
}

type HubOption interface {
	// contains filtered or unexported methods
}

type LogCandidates func(ctx context.Context, traceIDs []string, from, to time.Time, limit int) ([]OtherLog, error)

type LogCounts struct {
	Total, Warn, Error int64
	Capped             bool
}

type LogPage struct {
	Logs      []OtherLog
	Partial   bool
	Gap       int
	Truncated bool
	NoBridge  bool
}

type LogQuery struct {
	From        int64
	Limit       int
	MinSeverity int
}

type ManifestStore interface {
	// PutManifest stores m unless its hash is stored already (then it
	// is a no-op answering nil). A zero FirstSeen is stamped with the
	// current time. ErrInvalidManifest when CheckStoredManifest
	// refuses m.
	PutManifest(ctx context.Context, m StoredManifest) error
	// Manifest answers the manifest stored under hash; false when none
	// is.
	Manifest(ctx context.Context, hash string) (StoredManifest, bool, error)
}

type MessageText struct {
	Role, Text string
	ToolCall   bool
}

type ModelUsage struct {
	Provider, Model string
	Usage           core.Usage
}

type OtherLog struct {
	Index     int64
	Time      time.Time
	Severity  int
	EventName string
	Body      string
	Attrs     map[string]any
	TraceID   string
	SpanID    string
	Service   string
}

type Percentiles struct {
	P50, P95 float64
	N        int64
}

type PosEvent struct {
	Pos            int64
	Time           time.Time
	Event          json.RawMessage // the body, verbatim
	Content        string
	TruncatedBytes int64
}

type Problems struct {
	// AttemptsRetried counts the model attempts that failed and were
	// followed by another attempt of the same model call: attempt spans
	// with status Error whose weft.attempt.index is below the highest
	// index among their chat span's attempts (mw.Retry's retries,
	// mw.Fallback's fallen-back-from tries, an adapter's reported SDK
	// retries). The last attempt of a call is never counted — failed, it
	// failed the call, and nothing retried it.
	AttemptsRetried int64
	// Fallbacks counts the model calls a fallback layer answered:
	// attempt spans that succeeded carrying weft.attempt.layer
	// "fallback" (mw.Fallback's report for a backup). Never a comparison
	// of model names.
	Fallbacks int64
	// ToolErrors counts the tool calls that ended in an error result:
	// execute_tool spans with status Error, except DENIED (Denied),
	// RETRY (core.ModelRetry: the intended repair loop) and a context
	// error (the run's cancellation reaching the call — the run's
	// error_type, not the tool's failure). NO_SUCH_TOOL counts.
	ToolErrors int64
	// Denied counts the refused tool calls: execute_tool spans whose
	// error.type is DENIED (a policy middleware, mw.Allow), plus the
	// calls a resume denied — Deny, or no decision — which have no span
	// and are counted by the invoke_agent span's weft.run.denied.
	Denied int64
	// Truncated counts the tool results the result cap cut:
	// execute_tool spans carrying weft.tool.truncated_bytes > 0.
	Truncated int64
	// Repaired counts the tool calls whose arguments a model
	// middleware repaired before the loop saw them (mw.RepairJSON):
	// execute_tool spans carrying weft.tool.args_repaired true (U23.1).
	Repaired int64
	// TapPanics counts the observer panics the run contained — taps,
	// OnMessages observers, a record the pipeline failed to build, and
	// every call into the run's TracerProvider or LoggerProvider that
	// panicked (P9-core-panic) — from its invoke_agent span's
	// weft.tap.panics (U32.1, UX-E-51). The run is unchanged; an
	// observer the app relies on saw less.
	TapPanics int64
	// MetadataDropped counts the metadata pairs the core's limits
	// dropped (64 keys, 128-byte keys, 1 KiB values), from the
	// invoke_agent span's weft.metadata.dropped (U32.1, UX-E-42): the
	// run document's truncated hole, cause metadata_cap — not a
	// problem badge.
	MetadataDropped int64
	// LogWarn and LogError count the app's own log records under the
	// run's spans at WARN (13–16) and at ERROR or above (17–24). They
	// are read time, not ingest time — an app log carries the trace and
	// span ids, not the run id, so it can only be attributed once the
	// run's spans are known (DB.CountLogs) — and filled on the run
	// document alone (Studio's run route), never on a list row.
	LogWarn, LogError int64
}

type PromptRecord struct {
	Index          int64
	Time           time.Time
	Hash           string
	Text           string
	Segments       []PromptSegment
	Content        Hole
	TruncatedBytes int64
}

type PromptSegment struct {
	Source string `json:"source"`
	Text   string `json:"text"`
}

type RawRecord struct {
	Index           int64     `json:"index"`
	Step            int       `json:"step"`
	Attempt         int64     `json:"attempt"`
	Time            time.Time `json:"time"`
	Request         RawSide   `json:"request"`
	Response        *RawSide  `json:"response"`
	RedactedHeaders []string  `json:"redacted_headers"`
	RedactedQuery   []string  `json:"redacted_query,omitempty"`
	Content         Hole      `json:"content"`
	TruncatedBytes  int64     `json:"truncated_bytes"`
}

type RawSide struct {
	Method         string              `json:"method,omitempty"`
	URL            string              `json:"url,omitempty"`
	Status         int                 `json:"status,omitempty"`
	Headers        map[string][]string `json:"headers"`
	MediaType      string              `json:"media_type,omitempty"`
	Body           string              `json:"body"`
	Encoding       string              `json:"encoding,omitempty"`
	Bytes          int64               `json:"bytes"`
	TruncatedBytes int64               `json:"truncated_bytes,omitempty"`
	// Complete is the response side's: false when the body was not read
	// to its end (closed unread by a transport retry, a timeout, a
	// reader that stopped) — the body is what was read, never the whole;
	// nil on the request side and on records that do not say.
	Complete *bool `json:"complete,omitempty"`
}

type Record struct {
	Time, Observed  time.Time
	TraceID, SpanID string
	Severity        int
	EventName       string
	Body            string
	Service         string
	Attrs           map[string]any
	Resource        map[string]any
}

type RequestBody struct {
	Step            int                `json:"step"`
	Attempt         int64              `json:"attempt"`
	SystemHash      string             `json:"system_hash"`
	MessagesRef     RequestMessagesRef `json:"messages_ref"`
	Tools           RequestTools       `json:"tools"`
	ToolChoice      *RequestToolChoice `json:"tool_choice,omitempty"`
	Thinking        *RequestThinking   `json:"thinking,omitempty"`
	SequentialTools bool               `json:"sequential_tools"`
	// Parallelism is the step's Parallelism dial (UX-S2-07, record
	// contract §4): how many of its tool calls may run at once. 0 on a
	// record written before it.
	Parallelism int           `json:"parallelism,omitempty"`
	Params      RequestParams `json:"params"`
	Model       RequestModel  `json:"model"`
	Stream      bool          `json:"stream"`
	// Prepared names the parts the run's PrepareStep chain changed
	// (O9, record contract §4): system, messages, tools, tool_choice,
	// params, thinking, sequential_tools. Absent when none did.
	Prepared []string `json:"prepared,omitempty"`
	// Wire is how the adapter's escape hatches shape the request
	// (UX-S2-09, record contract §4): names only. Nil when the model
	// declares none.
	Wire *RequestWire `json:"wire,omitempty"`
}

type RequestMessagesRef struct {
	Index *int64 `json:"index,omitempty"`
	Count int    `json:"count"`
}

type RequestModel struct {
	Provider string `json:"provider,omitempty"`
	Name     string `json:"name,omitempty"`
}

type RequestParams struct {
	Temperature *float64 `json:"temperature,omitempty"`
	TopP        *float64 `json:"top_p,omitempty"`
	MaxTokens   *int     `json:"max_tokens,omitempty"`
	Stop        []string `json:"stop,omitempty"`
	Seed        *int64   `json:"seed,omitempty"`
}

type RequestQuery struct {
	Step  *int
	From  int64
	Limit int
}

type RequestRecord struct {
	Index          int64
	Step           int
	Attempt        int64
	Time           time.Time
	SystemHash     string
	CatalogHash    string
	Content        Hole
	TruncatedBytes int64 // informational only; a request record is never capped by weft
	Body           RequestBody
	Raw            json.RawMessage
	Wire           *RawRecord
}

type RequestThinking struct {
	Level  string `json:"level"`
	Budget int64  `json:"budget,omitempty"`
	// Wire is how the adapter sends the level (O16): the provider field
	// it writes, or "none"; absent when the model declares none.
	Wire string `json:"wire,omitempty"`
}

type RequestToolChoice struct {
	Mode string `json:"mode"`
	Name string `json:"name,omitempty"`
}

type RequestTools struct {
	CatalogHash string   `json:"catalog_hash"`
	Names       []string `json:"names"`
}

type RequestWire struct {
	ServerAddress string   `json:"server_address,omitempty"`
	ExtraBodyKeys []string `json:"extra_body_keys,omitempty"`
	ExtraHeaders  []string `json:"extra_headers,omitempty"`
	Dropped       int      `json:"dropped,omitempty"`
}

type RunDetail struct {
	RunRow
	Children []RunRow
}

type RunPage struct {
	Runs         []RunRow
	Total        int
	NextBefore   *time.Time
	NextBeforeID string
}

type RunQuery struct {
	Agent, SessionID, PublicID, ParentRunID string            // ParentRunID: "" top-level only (no parent, no caller link), "*" all
	Status                                  Status            // "" any; a StatusWords word (parked, cancelled read time)
	Playground                              *bool             // nil any
	ExperimentID                            string            // the runs of one experiment
	Meta                                    map[string]string // subset match on metadata
	Before                                  time.Time         // cursor on Started; zero = newest
	// LastSeenAfter keeps the runs last seen at or after it (zero = no
	// bound). A running run is always among them once the bound is
	// older than InterruptedAfter: running means seen that recently.
	LastSeenAfter time.Time
	// BeforeID, with Before, makes the cursor the pair (Started, ID):
	// the runs after that one in the list order — exact inside a group
	// sharing one Started. Pass RunPage.NextBeforeID.
	BeforeID string
	Limit    int // 0 = 50, max 500
	// StoppedBy keeps the runs whose RunRow.StoppedBy is exactly this
	// ("" any); a value ending in ':' is a prefix ("has_tool_call:"
	// matches every has_tool_call:<tools> value).
	StoppedBy string
	// ErrorType keeps the runs whose RunRow.ErrorType is exactly this
	// ("" any): max_steps, cancelled, model_error, …
	ErrorType string
	// Errs keeps the runs whose RunRow.Err is exactly one of these
	// texts: nil any, an empty non-nil slice none. The error_class
	// filter resolves a class to its texts (ErrorClassTexts) and reads
	// them through it.
	Errs []string
	// IDPrefix keeps the runs whose ID starts with it, byte for byte
	// ("" any; no wildcard, no case folding): a pasted short id.
	IDPrefix string
	// CallerRunID keeps the runs started from one of that run's tool
	// calls without being its Subagent children (RunRow.CallerRunID;
	// "" any): a delegating turn's thread/pool child turns, its nested
	// Generates. Pair it with ParentRunID "*" — a caller-linked run is
	// top-level by ParentRunID.
	CallerRunID string
	// SessionIDs keeps the runs of any of these sessions (nil any; with
	// SessionID both apply): one read for a set of sessions — Studio
	// prices a level of delegated sessions with one.
	SessionIDs []string
	// TurnBelow and TurnAbove keep the runs whose RunRow.Turn is below
	// / above them (0 = no bound): with SessionID, a turn's neighbours —
	// TurnBelow N, Limit 1 the newest-started turn before N, and the
	// page's Total how many there are; TurnAbove N with Oldest the
	// first after it (U15.1-fix: a turn page's stepper reads O(1) rows,
	// never the whole session).
	TurnBelow, TurnAbove int
	// Oldest turns the list around: oldest first, in start order (run
	// id breaking ties, ascending), and the (Before, BeforeID) cursor
	// then reads the runs after that one — RunPage.NextBefore pages
	// forward. A run page's caller_linked rows are its first page. Runs
	// alone: Search keeps its own sort.
	Oldest bool
}

type RunRoute struct {
	RunID, RuntimeID, CommandID, PublicID string
	Fork                                  bool
	Seen                                  time.Time
}

type RunRow struct {
	ID, ParentRunID, ParentCallID, TraceID                     string
	Agent, Provider, Model, ManifestHash, WeftVersion, Service string
	SessionID, PublicID                                        string
	Turn                                                       int
	Playground                                                 bool
	ExperimentID, ForkedFrom                                   string
	// ResumedFrom is the run this one resumes — its weft.resumed_from
	// (core.ResumeOf; thread and weft/runtime pass it, an app passes
	// the parked RunResult.ID) — and ResumedBy, on a parked run, the
	// run that resumed it: the latest run by start time whose
	// ResumedFrom names this run (a tie: the larger id), derived at read time on both backends, so a resumer
	// stored before or after the parked run links it alike (record
	// contract §6, UX-E-17). "" when none.
	ResumedFrom, ResumedBy string
	// CallerRunID / CallerCallID are the tool call this run was started
	// from when it is no core Subagent child (weft.caller.run.id /
	// weft.caller.call.id, O11; record contract §2): a thread/pool child
	// session's turn, another agent's Generate inside a handler. A link,
	// never parenthood: ParentRunID names a Subagent's parent alone, the
	// run whose usage includes this one's (rule 13). "" when none, and
	// on every run recorded before weft 0.18 (which named such a run's
	// caller in ParentRunID instead).
	CallerRunID, CallerCallID string
	Meta                      map[string]string
	Started                   time.Time
	Finished                  *time.Time
	LastSeen                  time.Time
	Status                    Status
	Err                       string
	Steps, Pending            int
	StopReason                string
	Usage                     core.Usage
	EventCount, MessageCount  int64
	DeltaCount                int64 // deltas are counted, never stored (Q4)
	// ADR 0028 §10: run_start's weft.instructions.hash ("" on a run
	// written before the request record — RequestsHole reads the
	// table), request index 0's weft.catalog.hash ("" when it offered
	// no tools) and the request records' high-water mark (max
	// weft.request.index + 1). The API names them instructions_hash,
	// catalog_hash and request_count.
	InstructionsHash, CatalogHash string
	RequestCount                  int64
	// PromptPreview is the run's prompt — the turn's own, PromptText's
	// rule with TurnPrompt's resume clause (Searcher's prompt field) — cut to
	// PromptPreviewRunes runes; "" when the records carried no content
	// (a content-off run stores no messages) or no user text.
	PromptPreview string
	// Derived marks a run the reader built from stock GenAI spans
	// (DeriveStockRuns; docs/record-contract.md §9): an invoke_agent
	// span with gen_ai.conversation.id and no weft.run.id, its id
	// otel-<trace id>-<root span id>. Such a run has no events, no
	// transcript and no request records (its counts and hashes are
	// zero, its status succeeded or failed only); RequestsHole reads
	// HoleDerived for it, and the API badges it "derived from spans ·
	// no events" (HoleNoteFor(HoleDerived, CauseStockSpans)).
	Derived bool
	// Removed marks a run frame's row that no longer exists: a derived
	// run the latest derivation folded into another (a top-level agent
	// without a conversation id whose enclosing agent arrived in a later
	// export, docs/record-contract.md §9). Only a live frame carries it
	// (StockFoldedRuns, the writers' dropped rows) — so an open list drops
	// the row; no store returns such a row.
	Removed bool
	// RootEnded marks a run whose invoke_agent span was stored: the span
	// is exported only once it ended, so the run is over whatever records
	// are missing (docs/record-contract.md §6). Its error status is
	// failed; any other status reads succeeded with or without a
	// run_finish (DeriveStatus's ended). LostRecordsHole reads it too.
	RootEnded bool
	// FinishRecorded marks a run whose run_finish record is stored (the
	// column both backends already keep: runs.finished_ok,
	// weft_runs.FinishedOK; a derived run's reads its succeeded status).
	// A RootEnded run without it lost its record tail on the way
	// (TailLostHole) or never had records (LostRecordsHole).
	FinishRecorded bool
	// Settling marks a RootEnded weft run (not Derived, not Failed) whose run_finish
	// is not stored and that was heard from within InterruptedAfter
	// (DeriveSettling): a destination may store the root span before the
	// records that trail it (a log exporter's retry or backlog), so for
	// that window the reader neither calls the records lost
	// (LostRecordsHole, TailLostHole) nor the event stream done
	// (EventPage.Done). Derived at read time with Status, never stored;
	// Status itself already reads succeeded or failed from the root.
	Settling bool
	// StoppedBy names what ended the run, in the manifest's stop_when
	// vocabulary (has_tool_call:<tools>, step_count_is:N,
	// output_submitted, final_answer, parked, max_steps, usage_limit,
	// loop_detected, model_retries_exceeded, canceled, a custom
	// condition's name): the invoke_agent span's weft.run.stopped_by, or
	// run_finish's stopped_by — one core value on both carriers, so a
	// failed run (no run_finish) still names it from its span. "" when
	// neither carried one: a failure no control decided (a model error),
	// a run still going, or one recorded before the field existed.
	StoppedBy string
	// CancelCause is a canceled run's weft.cancel.cause
	// (thread.interrupted, thread.closed, studio.cancel, deadline, or a
	// caller's own core.CancelCause kind); "" on a plain cancel and on
	// every other run.
	CancelCause string
	// EventsEmitted and MessagesEmitted are what the core emitted (U5):
	// the invoke_agent span's weft.run.events and weft.run.messages — the
	// durable event records and growth messages records the run handed
	// to its LoggerProvider. 0 when the root carried neither (not stored
	// yet, or a weft before them) and when the run emitted none (no
	// logger). Fewer stored than emitted is a loss (EventsLost,
	// TailLostHole, LostRecordsHole); emitted 0 with nothing stored is
	// no_logger. Fewer messages stored than emitted, some stored, is a
	// lost transcript batch (MessagesLostHole); none stored is not
	// called lost: a content-off destination legitimately stores no
	// messages record (contract §5), and the row cannot tell it from one
	// that lost them all (contract §7).
	EventsEmitted, MessagesEmitted int64
	// ErrorType is a failed run's kind (U4): the invoke_agent span's
	// error.type — max_steps, usage_limit, loop_detected,
	// model_retries_exceeded, model_contract, model_error, … (the
	// core's closed table, record contract §3) — with the context
	// errors read as "cancelled" (RunErrorType); "" for a run that did
	// not fail, a failure whose root carried none, or a run still
	// going. The larger when several roots differ (both backends).
	ErrorType string
	// Problems are the run's problem counters (U4; Problems): failed
	// attempts, fallbacks, tool errors, denials, truncated results —
	// derived at ingest from its spans; the log counters are filled on
	// the run document only.
	Problems Problems
}

type RunTree struct {
	// Spans is the tree's spans in start order, then span id: at most
	// TreeSpanCap, the first ones.
	Spans []TreeSpan
	// Truncated says the tree holds more than TreeSpanCap spans: Spans
	// is its first TreeSpanCap.
	Truncated bool
	// TraceTruncated says a derived run's trace held more than
	// TreeTraceCap spans: the tree was cut from the trace's first
	// TreeTraceCap, so a span of it after them was not read. Never set
	// for a weft run (its spans are read by run id).
	TraceTruncated bool
	// Missing is the descendant runs the tree knows from their rows
	// that have no span in Spans and are not running — a child that
	// ran without a tracer, or whose spans a destination dropped —
	// ordered by Started, then id: at most TreeMissingCap, the first
	// ones. A running child (StatusRunning: spans export when they
	// end) is not missing yet. Empty when Truncated: a cut tree cannot
	// tell a missing run from one past the cap.
	Missing []TreeRun
	// MissingCount is how many runs are missing: Missing's length
	// before TreeMissingCap.
	MissingCount int
	// Hidden says TreeQuery's scope (PublicID, Meta) left runs out.
	Hidden bool
	// HiddenCount is how many runs it left out: each descendant run the
	// tree knows (from its rows' parents or its spans) that the scope
	// cut, its subtree's runs included. Never their ids. 0 unless Hidden.
	HiddenCount int
}

type SearchQuery struct {
	RunQuery
	Text, Tool, Model, Error string
	Since, Until             time.Time
	MinTokens                int64
	Sort                     SearchSort
	Offset                   int
}

type SearchSort string

type Searcher interface {
	// Search answers the runs SearchQuery matches, sorted as it asks,
	// with Total counting the whole match. NextBefore and NextBeforeID
	// stay nil and "": a search pages by SearchQuery.Offset.
	Search(ctx context.Context, q SearchQuery) (RunPage, error)
}

type Selector struct {
	RunID, SessionID, PublicID, Agent string
	// All matches every run's frames (subagent children included; a
	// record that names no run is no run's, and is not matched). It is
	// a scope of its own: set with any other field, the selector is
	// over-set and matches nothing.
	All bool
}

type SessionDetail struct {
	SessionRow
	Runs []RunRow
}

type SessionEvent struct {
	SessionID string
	RunID     string
	Kind      string
	Name      string
	PublicID  string
	Content   string
	Time      time.Time
	Body      json.RawMessage
}

type SessionEventPage struct {
	Events []SessionEvent
	Total  int
}

type SessionEventQuery struct {
	SessionID string
	PublicID  string
	RunIDs    []string
	Kinds     []string
	Offset    int
	Limit     int
}

type SessionEventReader interface {
	// SessionEvents pages a session's events in order (SessionEventQuery):
	// by record time, then run id, kind and body — one total order on
	// every backend, stable across reads, two records of one time, run
	// and kind included. Total counts every event the query selects (the
	// session's, or its public id's under PublicID). An unknown session
	// is an empty page, not an error: the caller decides whether the
	// session exists (DB.Session).
	SessionEvents(ctx context.Context, q SessionEventQuery) (SessionEventPage, error)
}

type SessionPage struct {
	Sessions     []SessionRow
	Total        int
	NextBefore   *time.Time
	NextBeforeID string
}

type SessionQuery struct {
	Agent, PublicID string
	Q               string
	Parents         []string
	IDs             []string
	// IDPrefix keeps the sessions whose id starts with it, byte for
	// byte (RunQuery.IDPrefix's rule: no wildcard, no case folding) —
	// the ⌘K palette's lookup of a pasted short session id (U30.2). ""
	// any.
	IDPrefix  string
	Meta      map[string]string
	Awaiting  bool
	Failed    bool
	Compacted bool
	Status    Status    // "" any; running, succeeded, failed or interrupted
	Lineage   string    // "", LineageChild or LineageFork
	Since     time.Time // zero = any
	Before    time.Time // cursor on LastSeen; zero = newest
	BeforeID  string    // with Before: the (LastSeen, ID) pair, as RunQuery.BeforeID
	Limit     int       // 0 = 50, max 500
}

type SessionRow struct {
	ID, PublicID, Agent string
	Turns               int
	FirstSeen, LastSeen time.Time
	Status              Status // the newest turn's
	Usage               core.Usage
	// SummarizerUsage is what weft/thread's summarizer model calls — a
	// compaction's summary, a SummarizeLeft branch summary — cost the
	// session: the summed usage of the chat spans marked weft.chat.role
	// summarizer under its runs (audit O15, record contract §6). A
	// separate, labelled figure, never part of Usage (the turns' own)
	// nor of any run's usage: a reader adds it for the session's whole
	// cost. Zero when the session summarized nothing (or before weft
	// recorded the spans).
	SummarizerUsage core.Usage
	// SummarizerModels is SummarizerUsage split by the model that
	// summarized — each summarizer span's gen_ai.provider.name and
	// gen_ai.request.model (Provider and Model "" when the span named
	// none) — sorted by provider, then model: what a reader prices each
	// part at (U15.1-fix, UX-B-13). Its parts sum to SummarizerUsage;
	// nil when the session summarized nothing.
	SummarizerModels []ModelUsage
	// Title is the newest turn's (by turn, then start) non-empty
	// SessionTitleKey — thread's Title as that turn started, a label
	// that survives content-off — "" when no turn carried one.
	Title string
	// FirstPrompt is the first turn's (lowest turn, then earliest
	// start) RunRow.PromptPreview: "" when that turn's records carried
	// no content (content-off) or no user text — never a later turn's.
	FirstPrompt string
	// ContentOff marks a session whose first turn (FirstPrompt's) was
	// recorded without content: events stored and not one messages
	// record (RunRow.EventCount > 0, MessageCount 0), and not Derived,
	// nor running or settling — its messages records may still arrive
	// (SessionContentOff). The list says "(content not captured)" for it
	// instead of the id.
	ContentOff bool
	// ParentSession, ParentCall and ParentRun are a delegated session's
	// lineage (thread/pool, ADR 0022): the session that delegated it
	// (its turns' weft.session.parent), the delegating tool call
	// (weft.session.parent_call) and the parent's run that call
	// belonged to (its first turn's CallerRunID, else — recorded before
	// weft 0.18 — its ParentRunID). "" for a session nothing delegated,
	// and ParentRun "" for a child submitted outside a run (p.Submit).
	ParentSession, ParentCall, ParentRun string
	// The turns' state over time (U16; UX-B-15, UX-B-16), read by
	// SessionTurnFacts over the same turns as every aggregate: Pending
	// is the newest turn's pending calls when it is an open park
	// (succeeded, pending calls, no resumer: the session awaits a
	// decision), else 0; FailedTurns counts the failed turns that are
	// neither ended nor cancelled; EndedTurns, apart, the turns thread's
	// busy policy ended (Interrupt or Rollback: a cancel cause of
	// BusyCancelCause, never a failure); CancelledTurns the other failed
	// turns whose error type is ErrorTypeCancelled (a caller's cancel, a
	// deadline, thread.closed, studio.cancel: no failure of the agent);
	// Resumes the turns that resume a parked one (a stored ResumedFrom),
	// so Turns - Resumes is the session's exchanges; Outcomes the newest
	// MaxOutcomes turns' outcomes, oldest first (Turns - len(Outcomes)
	// older ones are not in it); ForkedFrom the weft.session.forked_from
	// (<origin>#<entry>) its turns carry (the greatest, should they
	// differ), "" for a session no Fork made. A backend counts in SQL and
	// reads only the newest MaxOutcomes turns for the strip and Pending.
	Pending, FailedTurns, EndedTurns, CancelledTurns, Resumes int
	Outcomes                                                  []TurnOutcome
	ForkedFrom                                                string
}

type SkippedTool struct {
	Name   string `json:"name"`
	Reason string `json:"reason"`
	Source string `json:"source,omitempty"`
}

type SourceDetail struct {
	Server     string `json:"server,omitempty"`
	Transport  string `json:"transport,omitempty"`
	Prefix     string `json:"prefix,omitempty"`
	RemoteName string `json:"remote_name,omitempty"`
}

type Span struct {
	TraceID, SpanID, ParentSpanID string // lowercase hex
	Name                          string
	Kind                          int // OTLP SpanKind
	Start, End                    time.Time
	StatusCode                    int // 0 unset, 1 ok, 2 error
	StatusMessage                 string
	Service                       string         // resource service.name
	Attrs                         map[string]any // string, bool, int64, float64, []any
	Resource                      map[string]any
	Events                        []SpanEvent // exceptions etc.
}

type SpanEvent struct {
	Time  time.Time
	Name  string
	Attrs map[string]any
}

type SpanKey struct {
	TraceID, SpanID string
}

type SpanLink struct {
	TraceID, SpanID, ParentSpanID, RunID string
}

type StatsBucket struct {
	Runs, Failed, Calls, FailedCalls int64
	InputTokens, OutputTokens        int64
}

type StatsBy string

type StatsCell struct {
	Key                                       string
	Bucket                                    int
	Runs, Failed, Calls, FailedCalls, Retried int64
	Denials                                   int64
	InputTokens, OutputTokens                 int64
	CachedInputTokens, CacheWriteTokens       int64
	ReasoningTokens                           int64
	// DelegatedRuns is summed into the group, never into a bucket.
	DelegatedRuns int64
}

type StatsGroup struct {
	Key                         string
	Runs, Failed                int64
	Calls, FailedCalls, Retried int64
	Denials                     int64
	Usage                       core.Usage
	Models                      []ModelUsage
	Delegated                   core.Usage
	DelegatedModels             []ModelUsage
	DelegatedRuns               int64
	Duration, TTFT              Percentiles
	Series                      []StatsBucket
}

type StatsModelPart struct {
	Key       string
	Delegated bool
	ModelUsage
}

type StatsPage struct {
	By           StatsBy
	Since, Until time.Time
	Buckets      int
	Bucket       time.Duration // each bucket's width
	Groups       []StatsGroup
	GroupsCut    int
}

type StatsPercentiles struct {
	Key            string
	Duration, TTFT Percentiles
}

type StatsQuery struct {
	RunQuery
	By           StatsBy
	Since, Until time.Time // both required, Since before Until
	Buckets      int       // 0 = StatsBuckets, max MaxStatsBuckets
}

type Status string

type StepMessages struct {
	Step     int
	Messages []core.Message
	View     *Compaction
	Derived  bool
}

type StepMessagesError struct {
	Step int
	Hole Hole
	Msg  string
}

type StockRun struct {
	Row   RunRow
	Spans []Span
}

type StoredCommand struct {
	ID        string
	RuntimeID string // the runtime the command was enqueued to
	// Kind is the frame kind the caller names — "" or run, cancel,
	// approve, breakpoints, steer; stored verbatim, never interpreted.
	Kind  string
	State string // one of the five Command* states
	// RunID is the run an ack named ("" until one did).
	RunID string
	// PublicID is the public id the command is scoped to; Fork marks a
	// thread=fork command (its runs are sessions the runtime owns).
	PublicID string
	Fork     bool
	// Agent, SourceRunID and ExperimentID are the command's own, copied
	// out of Body for the reader that lists without decoding it.
	Agent, SourceRunID, ExperimentID string
	// Status is a finished command's run outcome (succeeded | failed);
	// Error why, when there is a why (a rejection's reason, a failed
	// run's error, what made it lost).
	Status, Error string
	// Created and Updated bound the row's life; AcceptedAt is when the
	// accepted ack arrived and LastBeat the last heartbeat (a repeated
	// accepted ack) — zero when none did. A restarted Studio decides a
	// silent accepted command lost from these two, never re-issuing it.
	Created, Updated, AcceptedAt, LastBeat time.Time
	Body                                   json.RawMessage
	Ack                                    json.RawMessage
}

type StoredManifest struct {
	// Hash is sha256 of Body, lowercase hex.
	Hash string
	// Body is the one-agent core.Manifest document, verbatim.
	Body json.RawMessage
	// Source is where Studio first saw it: ManifestSourceFile or
	// ManifestSourceRuntime ("" when the writer did not say).
	Source string
	// FirstSeen is when it was first stored.
	FirstSeen time.Time
}

type StoredRecord struct {
	Index          int64
	Step           int
	Time           time.Time
	Body           []byte
	Content        string
	TruncatedBytes int64
	SystemHash     string
	CatalogHash    string
}

type StoredRuntime struct {
	ID, Service, Host, Cwd string
	Pid                    int
	Agents                 []string
	Registered, LastSeen   time.Time
	Body                   json.RawMessage
}

type ToolEntry struct {
	Name           string          `json:"name"`
	Description    string          `json:"description"`
	Schema         json.RawMessage `json:"schema"`
	TimeoutMS      int64           `json:"timeout_ms"`
	Approval       bool            `json:"approval"`
	Replay         string          `json:"replay"`
	MaxResultBytes int             `json:"max_result_bytes"`
	Sequential     bool            `json:"sequential"`
	Source         string          `json:"source"`
	// Output marks the tool Output registered (submit_output): the
	// run's typed answer (record contract §4, UX-S1-06).
	Output bool `json:"output,omitempty"`
	// SourceDetail is the tool's origin in parts (O8): nil when the
	// producer set none.
	SourceDetail *SourceDetail `json:"source_detail,omitempty"`
}

type ToolsRecord struct {
	Index          int64
	Time           time.Time
	Hash           string
	Tools          []ToolEntry
	Content        Hole
	TruncatedBytes int64
	// Skipped are the tools an importer left out of the offered
	// sources (record contract §4, O8: weft/mcp's ImportError), at most
	// 64; SkippedMore counts the rest. Nil when none was skipped.
	Skipped     []SkippedTool
	SkippedMore int
}

type TracePage struct {
	Traces       []TraceRow
	Total        int
	NextBefore   *time.Time
	NextBeforeID string
}

type TraceQuery struct {
	// Service keeps the traces holding at least one span whose resource
	// service name is exactly this ("" any).
	Service string
	// PublicID keeps the traces every span of which carries
	// weft.public_id = PublicID — the rule a panel token's
	// /api/traces/{id} read applies, so a scoped list offers no trace
	// its detail would refuse (a non-weft span or another public id's
	// run in the trace excludes it).
	PublicID string
	// Meta keeps the traces holding, for each pair, a span whose
	// attributes carry it — run metadata rides every weft span verbatim
	// (core.Metadata, core.WithMetadata: tag.<k>=<v> and flow= on
	// /api/traces, U22). Empty: no filter.
	Meta map[string]string
	// ScopeMeta keeps the traces every span of which carries each pair
	// — PublicID's rule for a tag-scoped panel token (I4), so a scoped
	// list offers no trace its /api/traces/{id} read would refuse (a
	// span without the pair, a non-weft span included, excludes it).
	// Empty: no filter.
	ScopeMeta map[string]string
	// NotRun keeps the GenAI traces that make no run
	// (docs/record-contract.md §9, UX-H-02): a span without
	// weft.run.id whose GenAI operation StockCandidate reads
	// (invoke_agent, chat, execute_tool, by attribute or name), no span
	// carrying weft.run.id, and no derived run row of the trace — what
	// Studio's /runs counts as "GenAI traces that are not runs".
	NotRun bool
	// IDPrefix keeps the traces whose id starts with it, byte for byte
	// (RunQuery.IDPrefix's rule: no wildcard, no case folding) — the ⌘K
	// palette's lookup of a pasted short trace id. "" any.
	IDPrefix string
	Since    time.Time // Start at or after; zero = no bound
	Until    time.Time // Start before; zero = no bound
	Before   time.Time // cursor on Start; zero = newest
	// BeforeID, with Before, makes the cursor the pair (Start, TraceID),
	// as RunQuery.BeforeID: pass TracePage.NextBeforeID. A late earlier
	// span can re-list a trace on a later page (TracePage).
	BeforeID string
	Limit    int // 0 = 50, max 500
}

type TraceRoot struct {
	SpanID, Name string
}

type TraceRow struct {
	TraceID    string
	Root       *TraceRoot
	Service    string
	Start, End time.Time
	SpanCount  int
	Error      bool
	RunIDs     []string
}

type TranscriptBatch struct {
	Index        int64
	Step         int
	Input        bool
	InputDerived bool // Input was inferred by the backend, not read from the record
	Messages     json.RawMessage
}

type TreeQuery struct {
	// RunID is the tree's root run.
	RunID string
	// PublicID, when not "", scopes the tree to one public id (a panel
	// token's, U9.1-fix): the root run's spans stay, and a descendant
	// run stays when its row and each of its spans carry PublicID and
	// its parent run stays; any other descendant is left out with its
	// whole subtree, unnamed but counted (RunTree.Hidden, HiddenCount). The
	// backend leaves the rows' outsiders out of its span read, and the
	// cap counts the visible spans alone.
	PublicID string
	// Meta, when not empty, scopes the tree to the runs carrying every
	// pair (a tag-scoped panel token's, I4) by PublicID's rule: a
	// descendant run stays when its row's metadata and each of its spans'
	// attributes carry every pair — run metadata rides every weft span
	// verbatim — and its parent run stays. With PublicID both apply.
	Meta map[string]string
}

type TreeReader interface {
	// RunTreeSpans returns the spans of the run and of every run that
	// descends from it (RunTree): the runs whose parent chain reaches
	// it — RunRow.ParentRunID, else a span's weft.parent.run.id for a
	// run with no row — and, whatever else is known of them, the runs
	// core's id rule names its descendants (TreeIDRule: a Subagent
	// child's id is <parent>/<step>/<call id>). The descendants are
	// found from the run rows first and their spans read by run id, in
	// any trace — the run's trace is consulted only for its runs that
	// have no row — so a leaf of a large app-level trace reads its own
	// subtree, never the whole trace; a derived run (§9 of
	// docs/record-contract.md), whose spans carry no run id, is cut
	// from its trace. At most TreeSpanCap spans, in start order then
	// span id; RunTree.Truncated says the tree holds more. Each span
	// names the run it belongs to and that run's parent: the key a
	// reader draws one run's spans under another's by is (RunID,
	// SpanID). ErrNotFound for an unknown run; empty, not an error, for
	// a run with no span stored. TreeQuery.PublicID and Meta scope the
	// answer (a panel token's): the cut, then the scope, then
	// the cap, so a run the scope leaves out never takes a visible
	// run's place under the cap (RunTree.Hidden).
	RunTreeSpans(ctx context.Context, q TreeQuery) (RunTree, error)
	// ChildRuns returns the direct children (RunRow.ParentRunID) of each
	// of the parent ids, in one read per call however many ids it names
	// (the backend may split a very long list into chunks): each
	// parent's children ordered by Started, then id; a parent with no
	// child (or no row) is absent from the map. RunDetail.Children's
	// rows, for a page of runs at once — the runs list prices a page's
	// subagent trees level by level instead of one read per row. At
	// most ChildRunsCap rows in all; past it ErrChildRunsCapped.
	ChildRuns(ctx context.Context, parentIDs []string) (map[string][]RunRow, error)
}

type TreeRun struct {
	ID, ParentRunID, PublicID string
	Meta                      map[string]string
	Started                   time.Time
	Status                    Status
}

type TreeSpan struct {
	Span
	RunID, ParentRunID string
}

type TurnOutcome string

type Weft struct {
	RunID, ParentRunID, ParentCallID string
	SessionID, PublicID              string
	Turn                             int
	Agent                            string
	Record                           string // event | delta | messages | heartbeat | "" (non-weft)
	EventType                        string
	Pos                              int64 // event pos, messages index, delta pos, or request/prompt/tools index
	Step                             int   // -1 when absent
	ToolSeq                          int64 // -1 when absent
	Playground                       bool
	ExperimentID, ForkedFrom         string
	// ResumedFrom is a resuming run's weft.resumed_from (core.ResumeOf,
	// UX-E-17): the parked run it resumes. On its invoke_agent span and
	// run_start record only.
	ResumedFrom string
	// CallerRunID / CallerCallID are a run's weft.caller.run.id /
	// weft.caller.call.id (O11, U14): the tool call another run was
	// started from when it is no core Subagent child — a thread/pool
	// child session's turn, a Generate inside a handler. A link, never
	// parenthood (ParentRunID is the Subagent child's alone). On the
	// invoke_agent span and run_start record only.
	CallerRunID, CallerCallID string
	// Reason is a messages record's weft.messages.reason: "" for
	// transcript growth, "compacted" for a compaction view (ADR 0028
	// §8), which is never counted or concatenated as transcript. A
	// non-string reason reads as its text (never "": the record is not
	// growth), as ClickHouse's stringified attribute column reads it.
	Reason string
	// Input is a messages record's weft.messages.input: the run's input
	// record (ADR 0028 §8) — what search reads the turn's prompt from.
	Input bool
}