// structural_validator.go - StructuralValidator 子接口与 sealed marker.
//
// ADR-0008 v2 范式: 反射器只做基础逻辑校验 (schema / 单位 / 段位结构 /
// parse 解析), 业务校验赶到决策层 (main agent verdict cross-check /
// staging ML 验证 / await_human_input).
//
// 关键洞察 (CRITIC 框架, MAOS commit e9e09e463c, 2026-05-02): LLM-backed
// 业务校验等于让 LLM 自评 LLM, 实证不可靠 (r31 v1+v2+v3 三次跨 model
// 跑同款失败). 工具验证信号必须来自外部确定性系统不能依赖 LLM 自报.

package validator

// StructuralValidator is a Validator that performs ONLY deterministic,
// schema-level / structural checks (parse fit, schema match, unit
// constraint, range, regex, segment shape). LLM-backed business
// validation is FORBIDDEN in this slot.
//
// Why this restriction: the CRITIC framework (MAOS commit e9e09e463c)
// + ADR-0008 v2 r31 v1+v2+v3 empirical evidence prove that letting an
// LLM critique LLM output is unreliable -- "tool validation signal
// must come from an external deterministic system, not LLM
// self-reporting". Business validation belongs to the decision layer:
//   - main agent verdict cross-check (ADR-0008 v2 § main_agent.md)
//   - staging ML 验证 (pkg/staging + pkg/validator, L434)
//   - await_human_input (ADR-0008 v2 § verdict tri-state)
//
// This interface is a Go idiomatic sealed interface (embeds Validator +
// a package-private marker method). External packages MUST embed
// StructuralMarker to satisfy it -- the embedding carries the contract
// acknowledgement "this validator performs no LLM call and no business
// judgement".
//
// StructuralValidator 是只做确定性 / 结构层校验 (parse 解析 / schema
// 匹配 / 单位约束 / 范围 / regex / 段位形态) 的 Validator. 此槽位
// 禁止挂 LLM-backed 业务校验.
//
// 限制原因: CRITIC 框架 (MAOS commit e9e09e463c) + ADR-0008 v2 r31
// v1+v2+v3 三次实证已证 LLM 自评 LLM 不可靠 -- "工具验证信号必须来自
// 外部确定性系统不能依赖 LLM 自报". 业务校验归决策层:
//   - main agent verdict cross-check (ADR-0008 v2 § main_agent.md)
//   - staging ML 验证 (pkg/staging + pkg/validator, L434)
//   - await_human_input (ADR-0008 v2 § verdict tri-state)
//
// 此接口是 Go idiomatic sealed interface (嵌入 Validator + 包内私有
// marker method). 包外类型必须嵌入 StructuralMarker 才能满足 -- 嵌入
// 隐含契约声明 "本 validator 不做 LLM 调用不做业务判断".
type StructuralValidator interface {
	Validator

	// structuralMarker is a sealed marker. Only types in this package
	// or types embedding StructuralMarker satisfy it. Prevents external
	// LLM-backed Validator types from accidentally being wired into
	// engine slots (cfg.ResponseReflector) that demand StructuralValidator.
	//
	// structuralMarker 是 sealed marker. 仅本包类型或嵌入
	// StructuralMarker 的类型实现. 阻止外部 LLM-backed Validator
	// 误挂到要求 StructuralValidator 的引擎槽位 (cfg.ResponseReflector).
	structuralMarker()
}

// StructuralMarker is the embeddable helper that lets external packages
// declare a Validator structural. Embed it in your Validator struct:
//
//	type MyReflector struct {
//	    validator.StructuralMarker
//	    // ... your fields ...
//	}
//
// By embedding, the Validator type acknowledges the contract: NO LLM
// calls, NO business judgement, ONLY deterministic schema / parse /
// unit checks. Code review should treat any LLM client field, prompt
// template, or domain heuristic inside a StructuralMarker-embedding
// type as a contract violation per ADR-0008 v2 § engine-level
// reflector contract.
//
// StructuralMarker 是给外部包嵌入用的 helper. 在 Validator struct 中
// 嵌入声明此 Validator 是 structural:
//
//	type MyReflector struct {
//	    validator.StructuralMarker
//	    // ... 你的字段 ...
//	}
//
// 嵌入即声明契约: 不做 LLM 调用, 不做业务判断, 只做确定性
// schema / parse / 单位校验. Code review 应把嵌入 StructuralMarker
// 的类型里出现 LLM client 字段 / prompt 模板 / 业务领域启发式
// 视为违反 ADR-0008 v2 § 引擎层反射器契约.
type StructuralMarker struct{}

// structuralMarker satisfies the StructuralValidator sealed interface.
// Method is intentionally a no-op -- it exists solely as a contract
// acknowledgement.
//
// structuralMarker 满足 StructuralValidator sealed interface. 方法
// 故意空 -- 仅作契约声明.
func (StructuralMarker) structuralMarker() {}