// Package validator provides a pluggable contract for verdicting AI-
// written staging changes. An implementation takes a tool-specific diff
// snapshot, applies its own policy (rule-based / LLM-as-judge /
// external ML service / ensemble), and returns a Verdict that the
// caller uses to commit or rollback, and feeds to a circuit breaker.
//
// Deliberately carries no schema assumption: diffs flow in as opaque
// bytes keyed by SourceTool, letting implementations self-dispatch.
// The package supplies reference implementations (RuleValidator,
// LLMValidator) and a CompositeValidator for overlay composition
// (CLAUDE.md principle 10, "overlay not replace"). Provider selection
// (which ML or LLM backend) is a platform-layer concern.
//
// Relationship to evolve.Reflector: Reflector is event-driven learning
// from historical feedback (post-decision KPI); Validator is a
// synchronous gate on an individual staged diff (pre-commit). The two
// interfaces are deliberately not merged -- their timing, inputs, and
// return shapes diverge. See evolve package docs for the learning
// surface.
//
// Package validator 提供可插拔契约, 用于审批 AI 写入 staging 的变更.
// 实现接收工具特定的 diff 快照, 应用自定义策略 (规则 / LLM-as-judge /
// 外部 ML 服务 / 组合), 返回 Verdict 供调用方决定 commit 或 rollback,
// 并喂给熔断器.
//
// 刻意不假设 schema: diff 以 opaque bytes + SourceTool 流入, 实现自行
// 分发. 本包提供参考实现 (RuleValidator, LLMValidator) 与 CompositeValidator
// 叠加组合 (CLAUDE.md 原则 10 "叠加而非替换"). 具体后端选型 (用哪个 ML
// 或 LLM) 属 platform 层职责.
//
// 与 evolve.Reflector 的区分: Reflector 是从历史反馈事后学习 (决策后 KPI),
// Validator 是单个 staged diff 的同步 gate (commit 前). 两接口的时机 /
// 输入 / 返回形态都不同, 刻意不合并. 学习面见 evolve 包文档.
package validator