build

type MemProvider interface {
	Read() (MemStat, error)
}

type MemStat struct {
	TotalMB     uint64
	AvailableMB uint64
}

type Options struct {
	SrcRoot   string
	OutDir    string
	Embedder  types.Embedder // required
	CKVIgnore []string       // extra ignore patterns from --ckvignore CLI flag
	BatchSize int            // embedding batch size; 0 → 32
	// Version is the ckv build version recorded in the manifest. The CLI sets
	// it from the ldflags-injected cmd/ckv.Version; empty falls back to "dev".
	Version   string
	Now       func() time.Time
	Footprint *footprint.Logger // optional; nil → no logging
	// ProgressOut receives human-readable per-file progress lines.
	// nil disables progress entirely (the library-mode default so
	// embedded callers don't get surprise stderr writes). The CLI
	// sets this to os.Stderr; tests can inject a bytes.Buffer.
	ProgressOut io.Writer

	// DisableContextualPrefix turns off the rule-based contextual prefix.
	// The default (zero value, prefix on) prepends a one-line
	// "language: X. file: Y. symbol: Z." sentence to each chunk's embed
	// text — improving recall@1 on natural-language queries at ~5%
	// throughput cost. Disable for A/B measurement against the raw-text
	// baseline. Chunk IDs and the stored Text are unaffected either way.
	DisableContextualPrefix bool

	// LLMPrefixModel enables Phase D.2 contextual retrieval: an Ollama chat
	// model (e.g. "llama3") writes a one-sentence description of each chunk,
	// prepended to the chunk's raw embed text. Empty (the default) keeps the
	// cheap rule-based prefix. Generated prefixes are disk-cached under
	// <OutDir>/.ckv-llmprefix-cache and a generation failure degrades to the
	// rule-based prefix, so the build never fails on the LLM. Expensive: one
	// generation per new chunk, so opt-in only. Chunk IDs/stored Text are
	// unaffected — the prefix lives only in the embedded text.
	LLMPrefixModel string

	// PR corpus. When non-nil, the build fetches merged PRs
	// via `gh` CLI and indexes their descriptions + commit messages
	// as additional chunks alongside the source code.
	PRFetch *PRFetchOptions

	// PolicyPath is the path to a policy yaml (e.g. policy/stablenet.yaml).
	// When set and the file exists, every emitted chunk is annotated with
	// Category + ModificationGuidance based on its path. Empty disables
	// classification — chunks ship with Category="" and Guidance=nil.
	PolicyPath string

	// DocsRoots are extra directories walked for markdown AFTER SrcRoot.
	// Files found here are tagged Category="domain" and cited by their
	// path relative to the docs root. Used to embed an out-of-tree curated
	// corpus (the cks domain-knowledge entries + authoritative docs) in
	// the same index. These roots are not git repos, so chunks carry no
	// commit hash.
	DocsRoots []string

	// FlowCorpus is the path to a curated flow corpus JSONL (corpus.jsonl).
	// When set, the builder parses it (internal/flowcorpus) into flow_step /
	// flow_spine / curated-invariant chunks and embeds them in the same index.
	// Step chunks cite their real file:line; flow/invariant chunks are fileless
	// and cite the corpus path, whose directory is added to the manifest's docs
	// roots so query-time citation enforcement resolves them. Empty disables it.
	FlowCorpus string

	// CKGPath is the path to a CKG data directory (containing graph.db).
	// When set, the builder loads an in-memory (file_path, start_line)
	// index from ckg and resolves each emitted source chunk's CanonicalID
	// via ckgalign.LookupEntry — the stable, import-path-qualified key cks
	// composer uses to disambiguate same-named symbols across packages.
	// Empty disables alignment (CanonicalID stays ""). Docs-corpus chunks
	// are NOT aligned (ckg has no node for curated markdown). Open failures
	// abort the build with a clear error rather than silently skipping alignment.
	CKGPath string

	// FilesFromPath is the path to a JSON file with include/exclude glob
	// patterns. When set, only files whose repo-relative path passes the
	// filterlist.FilterList.Allow check are sent to the embedder — for
	// ALL languages (Go, Solidity, TypeScript, JavaScript, Markdown).
	// Empty string (the default) disables the allowlist: all discovered
	// files are eligible as before. See internal/filterlist for the JSON
	// schema: {"include": [...globs...], "exclude": [...globs...]}.
	FilesFromPath string
}

type PRFetchOptions struct {
	Repo  string    // "owner/repo"; inferred from git remote if empty
	Since time.Time // only PRs merged after this date
	Limit int       // max PRs to fetch; 0 → 100
}

type PRTagger interface {
	UpdateRecentPRs(ctx context.Context, filePRs map[string][]types.PRRef) (int, error)
}

type ReindexOptions struct {
	SrcRoot   string
	OutDir    string
	Embedder  types.Embedder // must match the embedder identity in the manifest
	CKVIgnore []string       // extra ignore patterns from --ckvignore CLI flag

	// Since is the commit the diff is computed against. Empty means
	// "use manifest.IndexedHead" (the common case). Pass a specific
	// SHA to override (e.g., "main~5") for catch-up reindex.
	Since string

	// Files, when non-empty, bypasses the git diff and forces reindex
	// of exactly these src-relative paths. Useful when the caller
	// already knows the change set (CI hook, fsnotify watcher) or when
	// reindexing files that aren't yet committed.
	Files []string

	BatchSize int               // 0 → defaultBatch (32)
	Now       func() time.Time  // 0 → time.Now
	Footprint *footprint.Logger // optional; nil → no logging

	// ProgressOut receives human-readable per-file progress lines.
	// nil disables progress entirely (library-mode default).
	ProgressOut io.Writer

	// DisableContextualPrefix mirrors Options.DisableContextualPrefix
	// for the reindex path so partial rebuilds match what the original
	// build produced. Keep both at the same value across build+reindex
	// — mixing prefixed and raw embeddings in one store would degrade
	// retrieval.
	DisableContextualPrefix bool

	// LLMPrefixModel mirrors Options.LLMPrefixModel for the reindex path.
	// Keep it equal to the value used at build time — mixing LLM-prefixed
	// and rule-prefixed embeddings in one store would degrade retrieval.
	LLMPrefixModel string

	// PolicyPath mirrors Options.PolicyPath. Reindexed chunks pass
	// through the policy loader so category/guidance stay current with
	// the yaml even when only some files change.
	PolicyPath string

	// PRFetch, when non-nil, enables incremental PR-corpus ingest: reindex
	// fetches merged PRs after the manifest's recorded cutoff
	// (sources.prs.last_pr_number / last_merged_at) and indexes only the new
	// ones. Nil leaves the PR corpus untouched (the common code-only reindex).
	PRFetch *PRFetchOptions
}

type ReindexResult struct {
	// FilesProcessed is the count of files actually re-embedded
	// (added + modified). Deletions don't count here.
	FilesProcessed int
	// FilesAdded / FilesModified / FilesDeleted partition the changed
	// set by git diff status so callers can report a useful summary.
	FilesAdded    int
	FilesModified int
	FilesDeleted  int
	// FilesSkipped is files in the diff that didn't match any parser
	// (e.g., changed README.txt is in the diff but ckv doesn't index
	// .txt today). Surfaced so users know the diff size != reindex size.
	FilesSkipped int
	// FilesResumed is the count of files skipped because a prior interrupted
	// reindex toward the same head already re-embedded them (resume checkpoint).
	FilesResumed int
	// Chunks aggregates chunk.Stats across every file processed.
	Chunks chunk.Stats
	// PrevHead and NewHead bracket the reindex range.
	PrevHead string
	NewHead  string
	BuiltAt  string
	DBPath   string
	// Validation is the post-reindex integrity report (§5.1): authoritative
	// counts, orphan detection, and canonical coverage.
	Validation sqlitevec.Validation
	// PRsIndexed is the number of PR-corpus chunks added by an incremental PR
	// ingest this run (0 when PRFetch is nil or no new PRs were found).
	PRsIndexed int
	// FlowReindexed is the number of flow-corpus chunks re-indexed this run
	// because the corpus content hash changed (0 when unchanged or absent).
	FlowReindexed int
	// DocsReindexed is the number of curated docs-corpus chunks re-indexed this
	// run because the docs tree content hash changed (0 when unchanged/absent).
	DocsReindexed int
}

type Result struct {
	FilesIndexed int
	Chunks       chunk.Stats
	IndexedHead  string
	BuiltAt      string
	DBPath       string
}