reflector

Overview ¶

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 main

import (
	"context"
	"encoding/json"
	"fmt"

	"git.flytoex.net/yuanwei/flyto-agent/pkg/evolve"
	"git.flytoex.net/yuanwei/flyto-agent/pkg/reflector"
	"git.flytoex.net/yuanwei/flyto-agent/pkg/validator"
)

func main() {
	scorer, _ := evolve.NewFuncEvaluator(func(_ context.Context, c evolve.Candidate) (float64, map[string]float64, error) {
		payload, _ := c.Payload.(map[string]any)
		if payload["risky"] == true {
			return 0.2, map[string]float64{"risk": 0.8}, nil
		}
		return 0.9, map[string]float64{"risk": 0.1}, nil
	})

	extract := func(d validator.DiffInput) (evolve.Candidate, error) {
		var payload map[string]any
		if err := json.Unmarshal(d.Raw, &payload); err != nil {
			return evolve.Candidate{}, err
		}
		return evolve.Candidate{ID: d.SourceTool, Payload: payload}, nil
	}

	v := reflector.EvaluatorAsValidator(scorer, extract, 0.5,
		reflector.WithName("ga-gate"),
		reflector.WithPolicyVersion("2026-04"),
	)

	vd, _ := v.Validate(context.Background(), validator.DiffInput{
		SourceTool: "SQLCAS",
		Raw:        []byte(`{"risky": true}`),
	})

	fmt.Println(v.Name(), vd.Approved, vd.Severity)
}

Output:
ga-gate false block