feat: load explicit configuration references and remove implicit env overlays

reports/explicitConfigurationAcceptance.md

@@ -0,0 +1,53 @@
+# v0.22 显式配置引用验收（2026-09-26）
+
+配置文件明确决定值的来源。框架只处理通用加载、类型绑定和安全诊断，不包含接入项目的字段、环境前缀或业务规则。
+
+## 回归结果
+
+- `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./...`：48 个有测试的包通过，包含实际生成项目、错误目录、生命周期失败清理、上传下载、后台收尾和 copyx 回归。
+- 生成模板最后调整后，CLI、apigen、scaffold 的实际消费者 race 复测通过。
+- `go vet ./...`、`go build ./...` 通过。
+- `GOTOOLCHAIN=go1.22.12 go test ./config ./database ./examples/configuration` 通过。
+- managedService 的生成检查、race 与根目录构建通过；userService 的 race 通过。外部 MySQL 测试未配置时按原规则跳过。
+- 三种格式示例分别运行默认值与显式 0/含特殊字符凭据；结果一致。类型错误非零退出，指出字段和环境名，未输出输入值。
+
+| 场景 | 验证 |
+| --- | --- |
+| 固定值与 Default() | 不读取同名环境变量；文件缺失保留默认，显式 0/false/空字符串覆盖 |
+| `${NAME}` / `${NAME:-fallback}` | 未设置与空值区分规则明确；必填失败不退回 Default，0/false/空格属于有效值 |
+| 特殊字符与转义 | 冒号、`:-`、引号、换行、XML 字符、`${OTHER}` 原样保留；`$$` 转义，无二次展开 |
+| YAML/JSON/XML/自定义 Decoder | 解码标量后解析引用，不替换文件源文本；同一绑定/验证流程 |
+| 类型、null 与集合 | 按目标类型绑定，保留 int64 精度；不把环境文本隐式解析为对象、集合或 null |
+| 失败诊断 | 文件、字段、环境名、可获取行列；类型/溢出/Validate 错误不输出值；相近未知字段给出建议 |
+| 并发和默认值隔离 | 每次加载独立缓存，每个引用变量最多读取一次；24 个并发加载 race 通过 |
+| 资源限制 | 文件和单值上限、总展开预算、深度/节点/引用上限、非法 UTF-8、恶意格式拒绝 |
+| 生成维护边界 | 重复生成、dry-run/check 结果一致；业务配置和实现保留；main/loadGen 漂移拒绝 |
+| `-check-config` | 使用同一 Load，成功退出 0；失败非零；不初始化依赖、不创建日志文件、不监听 |
+| 单文件选择 | `-config` 选择一份，邻接 local/test 文件不自动叠加；空路径仅 Default |
+| 删除旧模式 | env/envDefault 检出即提示迁移；不保留前缀、别名或隐式二次覆盖 |
+
+`FuzzConfigurationReferences` 使用 4 worker、30 秒：284783 次执行，通过，总运行 31.445 秒（包含收尾）。另有确定性超限与格式安全测试；执行次数不代表形式化证明。
+
+## 性能
+
+Go 1.27.1、darwin/arm64、Apple M2 Max；同一实现、无 race、每场景三轮，benchtime=500ms。原始结果：[explicitConfigurationBenchmark.txt](explicitConfigurationBenchmark.txt)。
+
+| 场景 | 中位数 | 典型分配 |
+| --- | ---: | ---: |
+| 小配置固定值：读文件＋解析＋绑定＋校验 | 24.932 µs | 10.24 KB / 123 allocs |
+| 相同小配置带显式环境引用 | 25.420 µs | 11.12 KB / 133 allocs |
+| 约 28 KB、1000 条目 JSON 解码＋绑定 | 2.390 ms | 2.40 MB / 31582 allocs |
+
+小配置引用增加约 0.49 µs / 0.88 KB / 10 次分配；测量有波动，不承诺固定比例。配置只在启动/显式重新加载时执行，不进入业务请求路径。这是本机暖文件缓存测试，不是线上并发、冷磁盘或请求 QPS 测量。
+
+## 迁移与范围
+
+- 本版有意移除旧自动环境覆盖、标签、前缀/别名及数据库环境加载 API；完整清单见 [CONFIG.md](../CONFIG.md#v022-迁移旧模式已移除)。
+- 配置文件里的其他 `${...}` 模板改写 `$${...}`；`.api` 响应模板不变。固定文件值不再被进程环境偷偷覆盖。
+- XML 占位符使用普通叶元素或 type=string；显式 number/bool 表示文件常量。原有解析器的配置子集和安全限制保留。
+- Decoder、Validate、自定义反序列化是可信 Go 扩展，项目负责其副作用与公开原因脱敏。
+- 本轮没有修改接入项目业务代码，没有使用线上服务器压测，也没有连接业务数据库。框架回归不能代替项目升级后的实际部署配置和业务验收。
+
+## 远程验收
+
+发布后使用空 module 缓存安装固定版本，验证无本地 replace 的生成、编译、退出、配置及消费者回归。具体版本、校验和、检查清单与源码哈希写入远程验收记录。

reports/explicitConfigurationBenchmark.txt

@@ -0,0 +1,15 @@
+goos: darwin
+goarch: arm64
+pkg: git.yuntuo.hk/k2safe/go-omni/config
+cpu: Apple M2 Max
+BenchmarkConfigurationLarge-12       	     246	   2408597 ns/op	  11.63 MB/s	 2403405 B/op	   31582 allocs/op
+BenchmarkConfigurationLarge-12       	     249	   2368666 ns/op	  11.83 MB/s	 2403394 B/op	   31582 allocs/op
+BenchmarkConfigurationLarge-12       	     249	   2389703 ns/op	  11.72 MB/s	 2403361 B/op	   31582 allocs/op
+BenchmarkExplicitConfiguration/false-12         	   23610	     24932 ns/op	   10234 B/op	     123 allocs/op
+BenchmarkExplicitConfiguration/false-12         	   23541	     25349 ns/op	   10237 B/op	     123 allocs/op
+BenchmarkExplicitConfiguration/false-12         	   24046	     24805 ns/op	   10237 B/op	     123 allocs/op
+BenchmarkExplicitConfiguration/true-12          	   23520	     25420 ns/op	   11119 B/op	     133 allocs/op
+BenchmarkExplicitConfiguration/true-12          	   23612	     24984 ns/op	   11118 B/op	     133 allocs/op
+BenchmarkExplicitConfiguration/true-12          	   23516	     25432 ns/op	   11116 B/op	     133 allocs/op
+PASS
+ok  	git.yuntuo.hk/k2safe/go-omni/config	8.469s