research

type Candidate struct {
	// EntityID is the matching graph entity. Required.
	EntityID string `json:"entity_id"`

	// Label is a human-readable name for the entity. Optional; empty
	// when the candidate source doesn't carry a label (some graph
	// queries return only IDs).
	Label string `json:"label,omitempty"`

	// Type is the entity's domain type when known (e.g. "drone",
	// "sensor"). Optional.
	Type string `json:"type,omitempty"`

	// Relevance is the within-tier ranking score (higher = better).
	// Per ADR-045 Phase 1, cross-tier comparison isn't meaningful —
	// PR 4 keeps per-tier ordering + recency tie-break; Phase 2 may
	// add a learned ranker.
	Relevance float64 `json:"relevance,omitempty"`

	// SnippetText is a short inline preview useful for prompt
	// injection. Omit when the candidate has no readable preview.
	SnippetText string `json:"snippet_text,omitempty"`

	// Tier is the retrieval tier that surfaced this hit. Same
	// taxonomy as Evidence.Tier in result.go so the evidence schema
	// stays consistent across PR 2 (this file) and PR 4.
	Tier string `json:"tier"`

	// Source is the retrieval source within the tier — e.g.
	// "classifier_chain", "search_graph". Required so PR 4 can
	// classify candidates by retrieval pathway.
	Source string `json:"source"`
}

type ClassifierOutput struct {
	// Topic is the topic the classifier ran on. Echoed so the
	// downstream consumer (route_search) doesn't have to read the
	// intent payload separately.
	Topic string `json:"topic"`

	// Tier is which classifier tier produced the hint set:
	// "0" (keyword), "1" (embedding/BM25), or "3" (LLM). The
	// numbering follows ClassifierChain conventions (T0/T1/T2/T3 — T2
	// neural is Phase 2, not currently emitted). Empty/"0" is the
	// default fall-through when no tier matched.
	//
	// IMPORTANT: this is the *classifier* tier and shares no enum
	// with [Candidate.Tier] / [Evidence.Tier], which are *retrieval*
	// tiers ("0"/"1"/"2"). A LLM-tier classifier may surface
	// Tier="3" here while its surfaced candidates carry Tier="0" or
	// "1". Don't copy this string into a Candidate without
	// re-mapping — Candidate.Validate rejects "3".
	Tier string `json:"tier,omitempty"`

	// Intent is the LLM-or-embedding-detected intent classification.
	// Empty when the keyword tier matched (KeywordClassifier doesn't
	// set Intent — its semantics live in the Options map).
	Intent string `json:"intent,omitempty"`

	// Confidence is the classifier's confidence in the hint set.
	// 1.0 for keyword matches, <=1.0 from embedding similarity.
	Confidence float64 `json:"confidence,omitempty"`

	// Hints is the operator-facing flattened classifier output: time
	// range, geo bounds, path intent, aggregation type, etc. Wire
	// shape matches ClassificationResult.Options so consumers can
	// reconstruct a SearchOptions when they need to re-execute.
	Hints map[string]any `json:"hints,omitempty"`

	// Candidates is the initial candidate set: entities the
	// classifier surfaced, with scores + snippets where available.
	// Empty when the topic produced no hits — PR 3's route_search
	// will choose "retighten" or "decompose" in that case.
	Candidates []Candidate `json:"candidates,omitempty"`

	// Degraded is set when the candidate retrieval fell back to a
	// less-rich path (e.g. server-side semantic fallback). Carried
	// through so PR 3's router can treat the candidates as
	// advisory.
	Degraded bool `json:"degraded,omitempty"`

	// DegradedReason is a short operator-readable label describing
	// the fallback path when Degraded is true. Empty otherwise.
	DegradedReason string `json:"degraded_reason,omitempty"`
}

type DecompTrace struct {
	// RouterAction is the value emitted by route_search at the chain's
	// first LLM judgment. One of the four ActionXxx constants.
	RouterAction string `json:"router_action,omitempty"`

	// SubQueries records the decomposed sub-queries the router
	// generated when RouterAction == ActionDecompose. Free-form per
	// Phase 1; typed sub-query schemas land with PR 3's router action
	// arg schemas.
	SubQueries []map[string]any `json:"sub_queries,omitempty"`

	// SeedEntities records the walk_seeds entity set when
	// RouterAction == ActionWalkSeeds.
	SeedEntities []string `json:"seed_entities,omitempty"`

	// RetightenRounds records how many times R2's retighten branch
	// fired before terminating (success, cap, or downstream branch).
	RetightenRounds int `json:"retighten_rounds,omitempty"`
}

type DecomposeArgs struct {
	// Axes lists the dimensions of decomposition (e.g.
	// "entity_type", "time", "spatial", "relationship"). Free-form
	// strings; backend matches against its known decomposition
	// templates.
	Axes []string `json:"axes"`

	// Focus is the central concept to decompose around. Anchors the
	// backend's template selection — e.g. "sensor maintenance
	// events" or "drone telemetry anomalies".
	Focus string `json:"focus"`

	// Scope is the breadth of decomposition. One of the
	// DecomposeScope* constants. Empty resolves to "medium" at the
	// backend.
	Scope string `json:"scope,omitempty"`
}

type Evidence struct {
	// EntityID is the graph entity this evidence refers to. Required.
	EntityID string `json:"entity_id"`

	// Tier is the retrieval tier that surfaced this hit: "0" (rules /
	// predicate queries), "1" (BM25), or "2" (neural — deferred to
	// Phase 2). Operators may use it to filter evidence by retrieval
	// method.
	Tier string `json:"tier"`

	// Source is the retrieval source within the tier — e.g.
	// "classifier", "predicate_walk", "bm25_index". Required.
	Source string `json:"source"`

	// Score is the within-tier ranking score (higher = better).
	// Cross-tier comparison is not meaningful in Phase 1 (per-tier
	// ordering + recency tie-break); Phase 2 may add a learned ranker.
	Score float64 `json:"score,omitempty"`

	// SnippetText is a short inline preview (prompt-injection
	// friendly). Omit when the evidence has no readable preview.
	SnippetText string `json:"snippet_text,omitempty"`

	// ObjectStoreRef is the ObjectStore key for the full body when
	// the evidence has bulk content. Empty when the evidence is fully
	// expressed in the EntityID + triples on the graph.
	ObjectStoreRef string `json:"objectstore_ref,omitempty"`
}

type Intent struct {
	// Topic is the natural-language research question or subject.
	// Required.
	Topic string `json:"topic"`

	// Hints is an optional, free-form map of classifier hints. Phase 1
	// keeps the shape flexible; Phase 2 may add typed subtypes once
	// operator trajectories show what hints get passed.
	Hints map[string]string `json:"hints,omitempty"`

	// BudgetTokens caps total LLM token spend across the chain. Zero
	// falls back to DefaultBudgetTokens at consumption time so callers
	// can omit it.
	BudgetTokens int `json:"budget_tokens,omitempty"`

	// MaxIterations caps the refine loop in R4. Zero falls back to
	// DefaultMaxIterations.
	MaxIterations int `json:"max_iterations,omitempty"`
}

type RetightenArgs struct {
	// Topic is the refined topic string. Required.
	Topic string `json:"topic"`

	// Hints is the refined hint set. Optional; empty map and absent
	// field both treated as no hints.
	Hints map[string]string `json:"hints,omitempty"`
}

type RouteDecision struct {
	// Action is the routing decision. Must be one of ActionXxx
	// constants. UnmarshalJSON and Validate both enforce the enum.
	Action string `json:"action"`

	// Args carries the action-specific argument map. Per-action shapes
	// (intent-not-structure per ADR-045 Amendment 2026-05-23 — model
	// emits intent, backend constructs typed structures):
	//   - synthesize_directly: empty (uses classifier output as-is)
	//   - retighten:           RetightenArgs   {topic, hints}
	//   - walk_seeds:          WalkSeedsArgs   {seeds: [{ref, ref_type}]}
	//                          ref_type ∈ {"name","partial_id","candidate_index"};
	//                          backend resolves to full 6-part entity IDs
	//   - decompose:           DecomposeArgs   {axes, focus, scope}
	//                          backend constructs typed sub-queries
	// The map is intentionally loose at the wire level so the payload
	// stays uniform; strict per-action shape checks live in the
	// Parse*Args helpers below, called by the consuming component
	// after a successful Validate() of the action enum.
	Args map[string]any `json:"args,omitempty"`

	// Rationale is the LLM's natural-language justification for the
	// chosen action. Captured for operator trajectory review;
	// rule-opaque per discipline memory.
	Rationale string `json:"rationale,omitempty"`
}

type SearchResult struct {
	// Evidence is the set of hits that informed Synthesis. Every
	// evidence item synthesize_answer references must appear here;
	// quote-back validation enforces this in PR 5.
	Evidence []Evidence `json:"evidence,omitempty"`

	// Synthesis is the natural-language answer produced by
	// synthesize_answer. Refs quoted in the prose must resolve to
	// Evidence items above.
	Synthesis string `json:"synthesis"`

	// DecompTrace is the per-call audit of the chain's routing
	// choices and decompositions. Optional — present when the chain
	// took a non-trivial path (anything beyond synthesize_directly).
	DecompTrace *DecompTrace `json:"decomp_trace,omitempty"`

	// TokensUsed is the total LLM-token spend across the chain's
	// LLM calls (route_search + assess_sufficiency + synthesize_answer
	// + any retighten/refine repetitions).
	TokensUsed int `json:"tokens_used,omitempty"`

	// Iterations is the total refine-loop iterations the chain
	// executed before terminating. Distinct from RetightenRounds in
	// DecompTrace — Iterations counts R4's refine loop (capped by
	// ResearchIntent.MaxIterations); RetightenRounds counts R2's
	// retighten branch (capped at 2).
	Iterations int `json:"iterations,omitempty"`
}

type SeedRef struct {
	// Ref is the reference itself — a display name, a partial
	// federated ID, or a stringified index into the upstream
	// classifier candidate list. Interpretation depends on RefType.
	Ref string `json:"ref"`

	// RefType disambiguates how the backend resolves Ref. Closed
	// enum.
	RefType string `json:"ref_type"`
}

type WalkSeedsArgs struct {
	Seeds []SeedRef `json:"seeds"`
}