query

type AliasFile struct {
	Aliases AliasMap `yaml:"aliases"`
}

type AliasMap map[string][]string

type AlignmentReport struct {
	Status         AlignmentStatus `json:"status"`
	RecordedCommit string          `json:"recorded_commit,omitempty"`
	CurrentCommit  string          `json:"current_commit,omitempty"`
	RecordedDigest string          `json:"recorded_digest,omitempty"`
	CurrentDigest  string          `json:"current_digest,omitempty"`
	SchemaVersion  string          `json:"schema_version,omitempty"`
	CKGPath        string          `json:"ckg_path,omitempty"`
	Reason         string          `json:"reason,omitempty"`
	Warnings       []string        `json:"warnings,omitempty"`
}

type AlignmentStatus string

type BoostOptions struct {
	// SignatureMatch boosts hits whose symbol name or signature contains
	// query keywords. Default multiplier: 1.5
	SignatureMatch      bool
	SignatureMultiplier float64

	// DocMatch boosts hits whose leading comment block contains query
	// keywords. Default multiplier: 1.3
	DocMatch      bool
	DocMultiplier float64

	// RecentModified boosts hits whose commit_hash equals the indexed
	// HEAD (treated as "recently modified"). Default multiplier: 1.1
	// For real git log-based recency, the caller can pre-compute and
	// pass via a custom Score override.
	RecentModified   bool
	RecentMultiplier float64

	// PackageProximity boosts hits whose file path contains the given
	// package keyword. Default multiplier: 1.2
	PackageProximity  bool
	PackageKeyword    string
	PackageMultiplier float64

	// IndexedHead is used by RecentModified to compare chunk.CommitHash.
	// Set by the engine before calling Run.
	IndexedHead string
}

type BoostService struct{}

type BranchMatch struct {
	When     string         `json:"when"`
	Then     string         `json:"then"`
	At       string         `json:"at"`
	StepID   string         `json:"step_id"`
	FlowID   string         `json:"flow_id"`
	Symbol   string         `json:"symbol,omitempty"`
	Citation types.Citation `json:"citation"`
	Score    float64        `json:"score"`
}

type CommitSummary struct {
	Hash    string `json:"hash"`
	Author  string `json:"author"`
	Date    string `json:"date"`
	Subject string `json:"subject"`
}

type ConventionHit struct {
	ChunkID string         `json:"chunk_id"`
	File    string         `json:"file"`
	Package string         `json:"package"`
	Summary string         `json:"summary"`
	Stats   map[string]any `json:"stats"`
}

type DensityService struct{}

type DensityTier string

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

type EmbedderInfo struct {
	Name      string `json:"name"`
	Dimension int    `json:"dimension"`
	// Status: "ready" | "stub" | "unavailable"
	//   ready       — embedder loaded, semantic signal expected
	//   stub        — placeholder embedder (mock, hash-based); recall not meaningful
	//   unavailable — embedder is nil or failed to attach
	Status string `json:"status"`
	// Provider is the execution backend tag (bgeonnx-specific):
	// "coreml" | "coreml-fallback-to-cpu" | "cpu" | "". Empty for
	// embedders that don't run a backend (mock).
	Provider string `json:"provider,omitempty"`
	// ModelDir is the on-disk model directory the embedder loaded from.
	// Empty for embedders that don't have one (mock).
	ModelDir string `json:"model_dir,omitempty"`
}

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

type EnrichService struct{}

type ExpandResult struct {
	Origin         string         `json:"origin"`
	Direction      string         `json:"direction"`
	OriginBranches []types.Branch `json:"origin_branches,omitempty"`
	Neighbors      []FlowNeighbor `json:"neighbors"`
}

type Explanation struct {
	ChunkID  string                      `json:"chunk_id"`
	Citation types.Citation              `json:"citation"`
	Vector   ExplanationVectorScore      `json:"vector_score"`
	Keyword  ExplanationKeywordScore     `json:"keyword_score"`
	Category string                      `json:"category,omitempty"`
	Guidance *types.ModificationGuidance `json:"guidance,omitempty"`
	Symbol   string                      `json:"symbol,omitempty"`
}

type ExplanationKeywordScore struct {
	Score          float64  `json:"score"`
	MatchedTokens  []string `json:"matched_tokens"`
	QueryTokens    []string `json:"query_tokens"`
	ChunkTokenSize int      `json:"chunk_token_size"`
}

type ExplanationVectorScore struct {
	Normalized     float64 `json:"normalized"`
	CosineDistance float64 `json:"cosine_distance"`
}

type FlowNeighbor struct {
	StepID   string         `json:"step_id"`
	Symbol   string         `json:"symbol,omitempty"`
	Citation types.Citation `json:"citation"`
	Relation string         `json:"relation"` // "calls" (downstream) | "called_by" (upstream)
}

type FlowSelector struct {
	FlowID      string
	EntryPoint  string
	InvariantID string // resolves to the first flow in the invariant's enforced_at
}

type FlowStepView struct {
	StepID     string         `json:"step_id"`
	Symbol     string         `json:"symbol,omitempty"`
	Citation   types.Citation `json:"citation"`
	Kind       string         `json:"kind,omitempty"`
	Calls      []string       `json:"calls,omitempty"`
	Reads      string         `json:"reads,omitempty"`
	Writes     string         `json:"writes,omitempty"`
	Emits      string         `json:"emits,omitempty"`
	Branches   []types.Branch `json:"branches,omitempty"`
	Invariants []string       `json:"invariants,omitempty"`
}

type FlowView struct {
	FlowID     string         `json:"flow_id"`
	EntryPoint string         `json:"entry_point,omitempty"`
	Trigger    string         `json:"trigger,omitempty"`
	RootSymbol string         `json:"root_symbol,omitempty"`
	Links      []string       `json:"links,omitempty"`
	CalledBy   []string       `json:"called_by,omitempty"`
	Steps      []FlowStepView `json:"steps"`
}

type HallucinationResult struct {
	Verified bool   `json:"verified"`
	Reason   string `json:"reason,omitempty"` // empty when Verified=true
	// File-level diagnostics for false cases. Populated only when
	// Verified=false so the JSON payload stays compact for the common
	// case.
	ExpectedFile string `json:"expected_file,omitempty"`
}

type Hit struct {
	ChunkID  string         `json:"chunk_id"`
	Citation types.Citation `json:"citation"`
	Snippet  string         `json:"snippet"`
	// Density names which 3-tier ladder rung this Snippet was rendered
	// at (DensityFull / DensitySignature5 / DensitySignatureOnly).
	// Useful for downstream UIs that want to badge compressed hits or
	// for eval pipelines counting how often the budget forced a
	// downgrade. Omitted when empty (e.g. callers building Hit by hand).
	Density DensityTier `json:"density,omitempty"`
	// StaleCitation propagates from types.Hit: the chunk's recorded
	// commit_hash disagrees with the current source-tree HEAD. The
	// citation file/lines still resolve — the content there may have
	// shifted since the index was built. Consumers can render a badge
	// or schedule a reindex. Omitted when false.
	StaleCitation bool             `json:"stale_citation,omitempty"`
	Score         types.HitScore   `json:"score"`
	Language      string           `json:"language"`
	IsTest        bool             `json:"is_test,omitempty"`
	Symbol        string           `json:"symbol,omitempty"`
	SymbolKind    types.SymbolKind `json:"symbol_kind,omitempty"`
	// ChunkKind classifies the chunk's origin strategy (symbol,
	// file_header, doc, invariant, convention, flow_*). Lets consumers
	// (cks knowledge quota) route knowledge chunks without re-querying.
	ChunkKind   types.ChunkKind `json:"chunk_kind,omitempty"`
	CanonicalID string          `json:"canonical_id,omitempty"` // ckg's import-path-qualified symbol id (ADR-0001); the stable key cks uses to FindByCanonicalID against ckg
	// Category and Guidance are populated by the policy loader at build
	// time. Category labels the chunk's domain ("consensus", "state",
	// ...); Guidance lists what the agent should also review, test, and
	// watch out for when modifying this code. Both omitted when the
	// chunk did not match any policy rule (or no policy was loaded).
	Category string                      `json:"category,omitempty"`
	Guidance *types.ModificationGuidance `json:"guidance,omitempty"`

	// GitHistory holds recent commits touching this hit's file.
	// Populated when Options.EnableMetadataEnrichment is set.
	GitHistory []CommitSummary `json:"git_history,omitempty"`
}

type InvariantEnforcement struct {
	InvID      string               `json:"inv_id"`
	Statement  string               `json:"statement,omitempty"`
	EnforcedAt []types.EnforcePoint `json:"enforced_at"`
}

type InvariantHit struct {
	ChunkID     string                      `json:"chunk_id"`
	File        string                      `json:"file"`
	StartLine   int                         `json:"start_line"`
	EndLine     int                         `json:"end_line"`
	Marker      string                      `json:"marker"`             // e.g. "CRITICAL", "panic"
	Tier        types.InvariantTier         `json:"tier"`               // 1, 2, or 3
	Text        string                      `json:"text"`               // the invariant statement
	Category    string                      `json:"category,omitempty"` // inherited from source chunk's policy
	Guidance    *types.ModificationGuidance `json:"guidance,omitempty"` // ditto
	SourceChunk string                      `json:"source_chunk_id,omitempty"`
}

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

type OpenOption func(*Engine)

type Options struct {
	K            int          // top-K (0 → DefaultK)
	Filter       types.Filter // pre-filter (lang / path / kind / commit)
	BudgetTokens int          // snippet density budget (0 → DefaultBudgetTokens)
	Threshold    float64      // min normalized score (0 → DefaultThreshold; <0 disables)
	SrcRoot      string       // absolute path used by citation enforcement;

	// ExamplesK splits test-file hits out of the main Hits slice into a
	// separate Examples slice in the response. Up to ExamplesK test
	// chunks pass through — distinct from K, which counts only the
	// non-test (primary implementation) hits. Defaults to 0 → no
	// separation, every hit goes through Hits as before.
	//
	// Why: an LLM coding agent gets cleaner signal when primary code
	// (the actual implementation it should mimic) is separate from
	// usage examples (tests that show how the code is called). With
	// them mixed, top-5 can be diluted by 2-3 test results that compete
	// for context window space.
	ExamplesK int

	// TraceID is a caller-supplied correlation ID propagated to the
	// footprint span and echoed in Response.Metadata.TraceID. Useful
	// when a single user action fans out into multiple Search calls
	// (CKS multiplex, retries) and the operator wants to grep all
	// related log entries together. Empty → engine generates one from
	// the intent hash + a monotonic suffix.
	TraceID string

	// DryRun, when true, validates the request (intent, embedder,
	// manifest identity) but skips embedding, store search, citation
	// enforcement, and density adjustment. The response carries
	// metadata only — Hits and Examples are empty. Useful for caller-
	// side budget / plan validation without paying the query cost
	// or polluting the footprint log with hot-path entries.
	DryRun bool

	// MaxDensity caps the snippet rendering tier (B3 ladder).
	// "" / DensityFull → no cap, downgrade only under budget pressure
	// (the documented default). DensitySignature5 → start every hit at
	// signature+N and downgrade to signature_only under pressure.
	// DensitySignatureOnly → emit signatures only, never bodies; useful
	// when the caller already has the chunk body cached and just wants
	// pointers (e.g. CLI list-mode).
	MaxDensity DensityTier

	// SignatureContextLines tunes the SignatureWithContext tier (number
	// of non-blank lines kept after the signature). 0 →
	// DefaultSignatureContextLines (5). Larger values keep more body
	// in the middle tier at the cost of fewer hits fitting the budget.
	SignatureContextLines int

	// Aliases is the vocabulary-bridge glossary applied to the intent
	// at the very start of Search. When non-nil, ExpandQuery
	// widens the intent with code-keyword aliases before embedding —
	// useful for Korean / domain-vague queries against an English code
	// corpus. Nil leaves the intent untouched (off by default).
	//
	// The expanded intent is what gets embedded and what appears in
	// the query.embed sub-span fingerprint; the *original* intent is
	// still echoed in the query.search top-level span for log triage.
	Aliases AliasMap

	// EnableBM25Rerank turns on the optional BM25 rerank pass between
	// store.search and threshold.drop. When true, the engine builds a
	// candidate-set BM25 over the vector hits (corpus = chunk.SymbolName
	// + first text line), scores each candidate against the *original*
	// intent (alias expansion is embed-side only), and reorders by RRF
	// fusion of vector + BM25 ranks. Default false — vector-only
	// behavior preserved as the baseline.
	//
	// The flag intentionally lives at the query-call level rather than
	// the Engine: comparison runs (`--bm25-rerank` vs no-flag) share
	// the same Engine + index, only the rerank step toggles.
	EnableBM25Rerank bool

	// EnableScoreBoost applies signature/doc/recent/package multipliers
	// to the rerank pass. Default false.
	EnableScoreBoost bool
	Boost            BoostOptions

	// EnableMetadataEnrichment attaches git log history to each hit.
	// Default false (calls git log per file, has IO cost).
	EnableMetadataEnrichment bool
	MaxHistoryCommits        int // 0 → 5
}

type RerankService struct{}

type Response struct {
	Hits []Hit `json:"hits"`
	// Examples holds test-file hits separated out from Hits when
	// Options.ExamplesK > 0. Nil/empty otherwise. The ranking inside
	// Examples follows the same score order as Hits — top of Examples
	// is the most-similar test result.
	Examples []Hit            `json:"examples,omitempty"`
	Warnings []string         `json:"warnings,omitempty"`
	Metadata ResponseMetadata `json:"metadata"`
}

type ResponseMetadata struct {
	TokensUsed     int    `json:"tokens_used"`
	IndexedHeadCKV string `json:"indexed_head_ckv"`
	Fresh          bool   `json:"fresh"`
	// TraceID echoes Options.TraceID (or the engine-generated fallback)
	// so callers can correlate this response with their footprint log
	// entries. Always set; non-empty.
	TraceID string `json:"trace_id,omitempty"`
	// DryRun mirrors Options.DryRun so callers reading only the
	// response can tell whether Hits actually came from the index.
	DryRun bool `json:"dry_run,omitempty"`
}

type SearchContext struct {
	// Input (set by caller before pipeline starts)
	Intent      string
	EmbedIntent string // after alias expansion; same as Intent when no aliases
	Options     Options
	TraceID     string

	// After EmbedService
	QueryVec []float32

	// After StoreSearch
	RawHits []types.Hit

	// After Rerank + Threshold + Citation
	FilteredHits []types.Hit

	// After TestSplit
	PrimaryHits []types.Hit
	ExampleHits []types.Hit

	// After DensityAdjust
	FinalHits     []Hit
	FinalExamples []Hit
	TokensUsed    int

	// Accumulated warnings
	Warnings []string

	// Metadata
	DroppedCitations int
	StaleCitations   int
}

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

type ThresholdService struct{}