Files
pipelines/internal/protocol/search.go
T
alan c700b28e6a Add cross-system read-only search
One query now finds anything in the system over the wire and from the CLI.

- protocol: add Search/SearchResults message types and a SearchRequest
  (query, optional kind filter, optional limit) / SearchResponse (typed,
  ranked matches plus truncation and scan-bound counters) pair, with typed
  payloads for pipeline, version, run, step/visit, field text and artifact.
- store: add Store.Search, a read-only query over pipelines,
  pipeline_versions, pipeline_runs, run_steps (+step_control) and
  step_artifacts. Ranks exact name (3) > name substring (2) > body text (1),
  breaks ties by recency then a stable kind/target order, and reports the
  matched field. Bounds work with a 50-default/200-max result cap, a 2000-row
  per-kind scan limit and a 2000-step / 1 MiB field-text scan budget.
- terms: a bare status word or lone date expression (today, yesterday, this
  week, YYYY-MM-DD) selects runs; anything else stays free text.
- server: dispatch protocol.Search to stores[0].Search; read-only and
  unconfirmed.
- cli: add `pipelines search QUERY [--type KIND] [--limit N] [--json]`, help
  text and a BROWSE line.
- store: add OpenReadOnly so the live-database check never runs DDL.
- docs: document the grammar, kinds, ranking and bounds in docs/cli.md,
  scope the TUI omnisearch to pipelines in docs/ui-ux-review.md, and add a
  search bullet to the packaged operations reference.
- tests: protocol round trip, store/ranking/term-parsing/limit/scan-bound
  unit tests, a server end-to-end test, and an env-guarded live check.

No new dependencies; go.mod/go.sum unchanged.
2026-10-16 15:43:25 +01:00

159 lines
6.1 KiB
Go

package protocol
// Search brokered by the Pipelines server: one query can find a pipeline, a
// pipeline version, a run, a recorded step/visit, the text of a step field
// (input/output/evidence/transcript) or a recorded artifact. A client sends
// Message{Type: Search, ID: <opaque>, Search: <SearchRequest>} and the server
// echoes the ID with a SearchResults response, matching every other exchange.
const (
Search = "search"
SearchResults = "search_results"
)
// Search.Kind narrowing values. They are the only narrowing mechanism and are
// enforced server-side; an empty Kind searches every kind.
const (
SearchKindPipeline = "pipeline"
SearchKindVersion = "version"
SearchKindRun = "run"
SearchKindStep = "step"
SearchKindField = "field"
SearchKindArtifact = "artifact"
)
// SearchKinds is the accepted Kind vocabulary in display order; the CLI help
// and notes are kept in step with it.
var SearchKinds = []string{
SearchKindPipeline,
SearchKindVersion,
SearchKindRun,
SearchKindStep,
SearchKindField,
SearchKindArtifact,
}
// SearchStatuses is the accepted set of bare status words a query may name to
// select runs. It mirrors the run status vocabulary; a bare word selects runs
// rather than matching as free text.
var SearchStatuses = []string{"queued", "running", "succeeded", "failed", "canceled", "interrupted"}
// Search budget and cap constants. They are fixed, enforced server-side and
// reported on SearchResponse so a client can see the bound that applied.
const (
// SearchDefaultLimit is the result cap when a request omits Limit (or sends 0).
SearchDefaultLimit = 50
// SearchMaxLimit is the largest accepted result cap; larger requests clamp.
SearchMaxLimit = 200
// SearchMaxScanSteps bounds how many recorded steps one query inspects while
// scanning input/output/transcript field text.
SearchMaxScanSteps = 2000
// SearchMaxScanBytes bounds the total field bytes (input_json + output_json +
// evidence_json + transcript) one query decodes and searches before it stops
// and reports Truncated.
SearchMaxScanBytes = 1 << 20
)
// SearchRequest is the search request body. Query is the free text, a bare
// status word or a date expression; Kind optionally narrows to one SearchKind;
// Limit caps the returned results (0 = server default).
type SearchRequest struct {
Query string `json:"query"`
Kind string `json:"kind,omitempty"`
Limit int `json:"limit,omitempty"`
}
// SearchResponse is the ranked, bounded set of matches. Results are ordered by
// score, then recency, then a stable kind/target tie-break. Truncated reports
// that either the result cap or the field-scan budget dropped matches;
// ScannedSteps/ScannedBytes and ScanBoundBytes make the body-scan bound
// observable.
type SearchResponse struct {
Query string `json:"query"`
Kind string `json:"kind,omitempty"`
Results []SearchResult `json:"results"`
Truncated bool `json:"truncated,omitempty"`
ScannedSteps int `json:"scanned_steps"`
ScannedBytes int `json:"scanned_bytes"`
Cap int `json:"cap"`
ScanBoundBytes int `json:"scan_bound_bytes"`
}
// SearchResult is one typed, navigable match. Kind selects which payload is
// set; Target is a stable token an existing CLI command can resolve
// (pipeline:<id>, pipeline:<id>:v<version>, run:<id>, run:<id>:<sequence>,
// run:<id>:<sequence>:<field>, or an artifact URL). Score and MatchedField
// expose the ranking tier and why the hit matched so a client can re-rank;
// Recency is the hit's sortable UTC timestamp.
type SearchResult struct {
Kind string `json:"kind"`
Target string `json:"target"`
Score int `json:"score"`
MatchedField string `json:"matched_field"`
Recency string `json:"recency,omitempty"`
Pipeline *SearchPipeline `json:"pipeline,omitempty"`
Version *SearchVersion `json:"version,omitempty"`
Run *SearchRun `json:"run,omitempty"`
Step *SearchStep `json:"step,omitempty"`
Field *SearchField `json:"field,omitempty"`
Artifact *SearchArtifact `json:"artifact,omitempty"`
}
// SearchPipeline is a pipeline name/identity hit: its latest version and stage count.
type SearchPipeline struct {
ID int64 `json:"id"`
Name string `json:"name"`
Version int `json:"version"`
Stages int `json:"stages"`
}
// SearchVersion is a pipeline version/source hit.
type SearchVersion struct {
PipelineID int64 `json:"pipeline_id"`
Version int `json:"version"`
ContentHash string `json:"content_hash"`
CreatedAt string `json:"created_at"`
}
// SearchRun is a run identity/metadata hit. FinishedAt and DurationSeconds are
// omitted for a run without a recorded finish.
type SearchRun struct {
ID int64 `json:"id"`
PipelineName string `json:"pipeline_name"`
Status string `json:"status"`
Workspace string `json:"workspace,omitempty"`
CreatedAt string `json:"created_at"`
FinishedAt string `json:"finished_at,omitempty"`
DurationSeconds float64 `json:"duration_seconds,omitempty"`
}
// SearchStep is a recorded step/visit hit.
type SearchStep struct {
RunID int64 `json:"run_id"`
Sequence int `json:"sequence"`
Stage string `json:"stage"`
Visit int `json:"visit,omitempty"`
Outcome string `json:"outcome,omitempty"`
Target string `json:"target,omitempty"`
Diagnostic string `json:"diagnostic,omitempty"`
}
// SearchField is a stage input/output/evidence/transcript text hit with a
// snippet around the first match.
type SearchField struct {
RunID int64 `json:"run_id"`
Sequence int `json:"sequence"`
Field string `json:"field"`
Snippet string `json:"snippet"`
}
// SearchArtifact is a recorded artifact hit; contents are never read, only the
// recorded metadata.
type SearchArtifact struct {
RunID int64 `json:"run_id"`
Sequence int `json:"sequence"`
Name string `json:"name"`
ContentType string `json:"content_type"`
SizeBytes int64 `json:"size_bytes"`
URL string `json:"url"`
}