// Package reflector is the umbrella namespace for the "Reflector"
// product abstraction: a family of three sibling interfaces --
// validator.Validator, evolve.Evaluator, evolve.Reflector -- that each
// reflect on an artifact and emit, respectively, a commit verdict, a
// fitness score, or a replay-time side effect. This package defines no
// new top-level interface. It hosts type-safe adapters so a concrete
// implementation of one sibling can satisfy another sibling's
// signature, giving consumers "replaceability" (any of rule / LLM / ML
// backing can be plugged in wherever any sibling interface is
// expected) without forcing every author to write three copies.
//
// Why three interfaces stay separate:
//
//   - validator.Validator is a synchronous commit gate. Input is a
//     staged DiffInput, output is a Verdict with Severity. Negative
//     verdict blocks the commit.
//   - evolve.Evaluator is a cheap scorer used in candidate-ranking /
//     GA loops. Input is a Candidate (opaque Payload), output is a
//     scalar fitness plus optional breakdown.
//   - evolve.Reflector is fire-and-forget replay consumer. Input is a
//     ReplayEvent pushed by LogReplayer, output is error only (err is
//     logged, never halts the replayer).
//
// A merged super-interface would force Reflector to fabricate a
// synthetic Verdict or force Validator to carry replay semantics.
// Neither fits. Go idiom is small interfaces composed via wrappers
// (io.Reader / io.Closer / io.ReadCloser), not one God interface.
//
// What this package delivers:
//
//	ValidatorAsEvaluator   wraps validator.Validator as evolve.Evaluator
//	EvaluatorAsValidator   wraps evolve.Evaluator    as validator.Validator
//	ValidatorAsReflector   wraps validator.Validator as evolve.Reflector (side-channel)
//	EvaluatorAsReflector   wraps evolve.Evaluator    as evolve.Reflector (side-channel)
//
// The reverse direction (Reflector -> Validator / Evaluator) is
// intentionally absent: Reflector.OnEvent has no return payload from
// which a synchronous Verdict or fitness can be reconstructed.
//
// Replaceability guarantee. Each adapter returns the target interface
// type directly. A call site written against validator.Validator can
// be wired with a native impl or with EvaluatorAsValidator(...); the
// swap is a single construction-site line, and the rest of the call
// site stays free of reflector imports.
//
// Concurrency. Wrapped implementations must be goroutine-safe. A
// single underlying Validator / Evaluator may be fan-out wrapped by
// several adapters (e.g. ValidatorAsEvaluator + ValidatorAsReflector)
// and therefore reached from multiple goroutines concurrently. If the
// underlying impl is not goroutine-safe, wrap a synchronizing
// decorator before passing it to the adapter.
//
// 反射器产品抽象的伞形命名空间. 三个同族接口 validator.Validator /
// evolve.Evaluator / evolve.Reflector 各自对一个待审对象做反思, 分别
// 产出 commit verdict / fitness / 回放副作用. 本包不引入新的顶层接口,
// 只提供类型安全的 adapter, 让一个具体实现同时满足另一个同族接口签名.
// "可替换性" 由此兑现 (规则 / LLM / ML 后端可互换接入任一同族接口的
// 调用点), 实现方不必重写三份.
//
// 为什么三个接口保持独立:
//
//   - validator.Validator 是同步 commit 闸. 输入 staged DiffInput, 输出
//     带 Severity 的 Verdict. 否决即阻断 commit.
//   - evolve.Evaluator 是候选排序 / GA 循环里的便宜打分器. 输入 Candidate
//     (Payload 不透明), 输出标量 fitness 与可选 breakdown.
//   - evolve.Reflector 是 fire-and-forget 的回放消费者. 输入 ReplayEvent,
//     输出仅 error (只记录, 不打断 replayer).
//
// 合一的超级接口要么逼 Reflector 伪造 Verdict, 要么逼 Validator 承担
// 回放语义, 都别扭. Go 惯例是小接口通过 wrapper 组合 (io.Reader /
// io.Closer / io.ReadCloser), 不是一个 God interface.
//
// 本包提供的 adapter:
//
//	ValidatorAsEvaluator   把 validator.Validator 包为 evolve.Evaluator
//	EvaluatorAsValidator   把 evolve.Evaluator    包为 validator.Validator
//	ValidatorAsReflector   把 validator.Validator 包为 evolve.Reflector (旁路)
//	EvaluatorAsReflector   把 evolve.Evaluator    包为 evolve.Reflector (旁路)
//
// 反向 (Reflector -> Validator / Evaluator) 刻意不做: OnEvent 无返回载荷,
// 无法反推同步 Verdict 或 fitness.
//
// 可替换性保证. 每个 adapter 直接返回目标接口类型. 针对 validator.Validator
// 写的调用点既可注入原生实现, 也可注入 EvaluatorAsValidator(...); 切换是
// 构造点一行改动, 其他调用代码不污染 reflector import.
//
// 并发语义. 被包装的实现必须 goroutine-safe. 同一底层 Validator / Evaluator
// 可能被多个 adapter 扇出包装 (例如 ValidatorAsEvaluator + ValidatorAsReflector),
// 因此会被多 goroutine 并发调用. 若底层实现非 goroutine-safe, 在传入 adapter
// 前套一层同步装饰器.
package reflector