wire

type CompactFileGroup struct {
	FilePath  string              `json:"file_path"`
	Namespace string              `json:"namespace,omitempty"`
	Hits      []CompactResultItem `json:"hits"`
}

type CompactResponse struct {
	Files              []CompactFileGroup `json:"files"`
	WeakFiltered       int                `json:"weak_filtered"`
	Truncated          bool               `json:"truncated"`
	PoolTruncated      bool               `json:"pool_truncated"`
	Limits             Limits             `json:"limits"`
	AnnotationCoverage evidence.Coverage  `json:"annotation_coverage"`
	Next               []NextAction       `json:"next,omitempty"`
	Note               string             `json:"note,omitempty"`
}

type CompactResultItem struct {
	QualifiedName string           `json:"qualified_name"`
	Kind          graph.NodeKind   `json:"kind"`
	StartLine     int              `json:"start_line"`
	EndLine       int              `json:"end_line"`
	Intent        string           `json:"intent,omitempty"`
	Matched       []evidence.Match `json:"matched,omitempty"`
	Reason        string           `json:"reason,omitempty"`
	MatchedTerms  []string         `json:"matched_terms,omitempty"`
}

type FileGroup struct {
	FilePath  string       `json:"file_path"`
	Namespace string       `json:"namespace,omitempty"`
	HitCount  int          `json:"hit_count"`
	Hits      []ResultItem `json:"hits"`
}

type Limits struct {
	Files     int `json:"files"`
	Offset    int `json:"offset"`
	HitBudget int `json:"hit_budget"`
}

type NextAction struct {
	Reason string         `json:"reason"`
	Tool   string         `json:"tool,omitempty"`
	Args   map[string]any `json:"args,omitempty"`
	// Skill names a packaged workflow to run rather than a tool to call. It is
	// set only for the step no tool can perform.
	Skill string `json:"skill,omitempty"`
}

type Response struct {
	Files        []FileGroup `json:"files"`
	FileCount    int         `json:"file_count"`
	WeakFiltered int         `json:"weak_filtered"`
	// Truncated is true when this answer did not reach every file the query
	// answered with. It is never about hits: a shown file is shown whole.
	Truncated bool `json:"truncated"`
	// PoolTruncated is true when the candidate pool behind this answer came back
	// full, so the backend held at least as many candidates as the pool could
	// take and may have held more.
	//
	// It is a second signal rather than part of Truncated because the two say
	// different things and call for different moves. Truncated counts files this
	// page did not reach, and stays about files. PoolTruncated says the page
	// stopped at the edge of what was fetched. `truncated: false` with
	// `pool_truncated: true` is the case that used to read as "that is
	// everything" when it was not: ask for the next page anyway.
	PoolTruncated bool   `json:"pool_truncated"`
	Limits        Limits `json:"limits"`
	// AnnotationCoverage is how many of the searched declarations recorded a
	// reason — an @intent or a @domainRule — out of how many were indexed.
	//
	// It is on every answer, not only the empty ones, because it is what makes an
	// answer's size readable: two files out of a repository where four hundred
	// declarations recorded a reason is a thin answer, and two out of a repository
	// where six did is most of what there was to find. `with_reason: 0` says the
	// question was put to an index nobody has written anything into yet.
	AnnotationCoverage evidence.Coverage `json:"annotation_coverage"`
	Next               []NextAction      `json:"next,omitempty"`
	Note               string            `json:"note,omitempty"`
}

type ResultItem struct {
	ID            uint           `json:"id"`
	QualifiedName string         `json:"qualified_name"`
	Kind          graph.NodeKind `json:"kind"`
	Name          string         `json:"name"`
	FilePath      string         `json:"file_path"`
	StartLine     int            `json:"start_line"`
	EndLine       int            `json:"end_line"`
	// Intent is the node's own @intent tag, empty when nobody wrote one.
	Intent string `json:"intent,omitempty"`
	// Matched names the signals this query touched — name, path, intent — so a
	// caller can tell an exact identifier hit from a hit on a written purpose.
	Matched []evidence.Match `json:"matched"`
	// Reason is the recorded reason the intent index answered with — set only
	// when this hit came from the intent query, so its absence means the hit
	// earned its place on name, path, or token overlap alone.
	Reason string `json:"reason,omitempty"`
	// MatchedTerms are the query terms written in Reason — the proof behind an
	// intent match that token overlap alone cannot see.
	MatchedTerms []string `json:"matched_terms,omitempty"`
	Namespace    string   `json:"namespace,omitempty"`
}