package config

// 本文件承载内容护栏里**由部署方声明**的那一部分（design/04 §5）。
//
// 敏感信息阻断档是代码内定的安全默认值（见组合根的 buildGuardrailPipeline），
// 不对外开放配置：它不该被一次误配置关掉。这里放的是两项**与部署环境相关**的
// 取值 —— 内容策略词表，以及请求侧字符上限的显式覆盖。
//
// 请求侧字符上限为什么必须能配：它的默认值由**推导出的上下文预算**派生
// （预算被抬高到 1M 窗口能吃的量级后，硬编码的 256 Ki 字符反而成了瓶颈，
// 会把「分享大文件」整条主线打成 guardrail_input 结束，见
// cmd/cyrene/wire_guardrail.go 的说明）。派生值已经能自适应窗口，本键只是
// 给需要收紧或放宽的部署留一个显式落点。

// GuardrailMaxInputCharsEnv 是请求侧字符上限的配置键名。
//
// 它必须与 GuardrailConfig.MaxInputChars 的 env 标签**逐字一致**：WARN 文案要能
// 直接点出「改哪个键」，因此键名只能有一处出处（一致性由 guardrail_test.go 钉住）。
const GuardrailMaxInputCharsEnv = "GUARDRAIL_MAX_INPUT_CHARS"

// GuardrailConfig 承载内容护栏里由部署方声明的取值（design/04 §5）。
type GuardrailConfig struct {
	// Keywords 是内容策略关键词表（GUARDRAIL_KEYWORDS，逗号分隔）。
	//
	// **为空时不挂关键词护栏**：项目绝不硬编一张词表 —— 凭空猜出来的词
	// 只会误伤正常对话，且没有任何部署方能对它的命中负责。只有显式声明过
	// 的词才会被拦（大小写不敏感的子串匹配）。
	Keywords []string `env:"GUARDRAIL_KEYWORDS"`

	// MaxInputChars 是**请求侧**字符上限的显式覆盖（GUARDRAIL_MAX_INPUT_CHARS）。
	// 三态：
	//
	//   - 未设置 / 0（默认）= 按推导出的上下文预算派生：
	//     输入上限 = max(256 Ki, 推导预算 token 数 × CharsPerToken)
	//     （换算必须与附件注入预算同一个常量 loop.CharsPerToken，理由见
	//     cmd/cyrene/wire_guardrail.go 的说明）；
	//   - > 0 = 显式覆盖（原样使用）；
	//   - < 0 = 非法：记一条 WARN 并回落派生值，绝不静默生效（AGENTS §10）。
	//
	// 派生态下「单回合全部附件的注入预算合计 ≤ 输入上限」这条关系不变量恒成立
	// （1M 窗口 ⇒ 5 份 × 349525 = 1747625 字符 ≤ 上限 2796200 字符）；显式覆盖把它
	// 压到合计之下时，组合根记一条 WARN 明说「多附件回合会被护栏拦下」，而不是等到
	// 用户上传多个大文件时才以一个没有上下文的 input_length_exceeded 表现出来。
	//
	// 它只动**输入**侧：输出上限（65536）防的是模型输出失控，与上下文预算无关，
	// 因此不随本键变化、也不开放配置。
	MaxInputChars int `env:"GUARDRAIL_MAX_INPUT_CHARS"`
}