// Package evolve provides the v0.2+ self-evolution interface matrix for Flyto
// Agent: LLM-generated candidates, offline log replay, versioned parameter
// storage, and shadow-mode validation.
//
// # API Consumption Shapes
//
// All ten contracts here are form 3 (synchronous callback) under the three
// Flyto API shapes (see `docs/api-reference.md` "API 消费形态 / API
// Consumption Patterns"). The engine's evolve loop calls each interface
// synchronously in sequence: Generator produces a candidate -> Evaluator
// scores it -> Reflector critiques -> ApprovalFunc gates -> ParameterEvolver
// proposes -> ShadowRunner validates in shadow mode -> ParameterStore
// persists. LogSource / LogReplayer / FeedbackChannel are pull interfaces
// the evolve loop drains during offline replay and feedback ingestion.
// Consumers implement any or all of them to plug alternative storage,
// models, or evaluation policies; the interfaces are designed for coexistence
// (see "Multi-Implementation Coexistence" below).
//
// API 消费形态:
//
// 本包 10 个契约在 Flyto 三种 API 形态下全部属于形态三 (同步回调, 见
// `docs/api-reference.md` "API 消费形态 / API Consumption Patterns").
// 引擎的 evolve loop 顺序同步调用: Generator 产候选 -> Evaluator 打分 ->
// Reflector 反思 -> ApprovalFunc 把关 -> ParameterEvolver 提议 ->
// ShadowRunner 影子模式验证 -> ParameterStore 持久化. LogSource / LogReplayer
// / FeedbackChannel 是 pull 接口, evolve loop 在离线回放和反馈摄入时读取.
// 消费者可实现任意子集来替换存储 / 模型 / 评估策略; 接口设计为可并存
// (见下文 "Multi-Implementation Coexistence").
//
// # Interface Topology
//
// Ten contracts (9 interfaces + 1 func type, canonical definitions in
// interfaces.go):
//
//	Core loop        : Generator / Evaluator / Reflector / ApprovalFunc (func)
//	Parameter mgmt   : ParameterStore / ParameterEvolver
//	Log / feedback   : LogReplayer / LogSource / FeedbackChannel
//	Risk mitigation  : ShadowRunner
//
// # Reference Implementations
//
// Shipped in this package (file-backed / in-process defaults). Alternative
// implementations (e.g. SQL-backed ParameterStore) are expected to live in the
// platform layer or consumer code and coexist with these via interface swap.
//
//	Generator         -> generator_llm.go          (LLMGenerator)
//	Evaluator         -> evaluator_impls.go        (Func / Weighted / Rule)
//	Reflector         -> reflector_impls.go, self_reflector.go
//	ApprovalFunc      -> evolve.go                 (Config.ApprovalFunc)
//	ParameterStore    -> parameter_store_file.go
//	ParameterEvolver  -> parameter_evolver_default.go
//	LogReplayer       -> default_log_replayer.go
//	LogSource         -> log_source_file.go
//	FeedbackChannel   -> feedback_channel_file.go
//	ShadowRunner      -> shadow_runner_default.go
//
// # Provider Bridge
//
// llm_adapter_flyto.go ships FlytoLLMClient, a thin adapter that wraps any
// flyto.ModelProvider (anthropic / openai / minimax / gemini / ollama /
// lmstudio / openrouter) as an LLMClient consumable by LLMGenerator. Event
// aggregation prefers TextEvent as authoritative and falls back to
// TextDeltaEvent when the provider does not emit complete-block events,
// avoiding double-counting on providers that emit both. ErrorEvent is wrapped
// via fmt.Errorf("%w: ...", ErrLLMFailed) so callers can use errors.Is.
//
// Note: flyto.Request (the cross-provider contract) does not expose
// Temperature, so LLMCallOpts.Temperature is intentionally ignored by this
// adapter. Set temperature at the provider factory Config (e.g.
// anthropic.Config) when per-call temperature control is needed.
//
// # End-to-End Example
//
// See core/examples/evolve_closed_loop/main.go -- all nine interfaces chained
// in a single process, demonstrating the full generate -> evaluate -> reflect
// -> propose -> shadow loop against fixture feedback.
//
// # Domain Agnostic
//
// All interfaces exchange business data as any / string / float64. The engine
// makes no assumption about any industry schema. Concrete data-source wiring
// (orders / settlement / complaints / KPI streams) belongs to the consumer
// layer. Rationale: docs/evolve-strategy.md and the "data ingress boundary"
// note in memory project_architecture_decisions.md.
//
// # Multi-Implementation Coexistence
//
// Every interface is expected to have multiple implementations side by side.
// For example the file-backed ParameterStore in this package serves CLI / TUI
// workflows, while platform/ is free to ship a SQL-backed ParameterStore for
// multi-tenant deployments. Interface contracts guarantee swap without code
// changes at call sites.
//
// # Strategic Background
//
//	docs/evolve-strategy.md   -- full strategy, Round 1/2/3 design rounds,
//	                             merge / absorb decisions, v0.2-v3.0 roadmap
//	CHANGELOG.md              -- v0.2-dev delivery summary (Unreleased)
//
// # Academic References
//
// The design draws on and cites the following arXiv works:
//
//	2508.07407  Comprehensive Survey of Self-Evolving AI Agents
//	2507.21046  Survey of Self-Evolving Agents
//	2509.04642  Maestro: Joint Graph & Config Optimization
//	2512.09108  Artemis / Evolving Excellence (mixed-variable optimization)
//	2406.16218  Trace: Next AutoDiff (NeurIPS 2024)
package evolve