@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/core/lib/config-catalog.mjs

@@ -0,0 +1,1172 @@
+/**
+ * 配置目录（catalog）+ **通用读取器** —— 配置面的唯一真源（2026-10-09，配置地基批次）
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 一、它解决什么
+ * ══════════════════════════════════════════════════════════════════════════
+ * 此前"这台机器有哪些可配项"没有一份清单：有的项只活在 env 文件里（`fulfillment.env`）、
+ * 有的只活在 `config.json` 的一个键里、有的只活在某个 `*.json` 的深层字段里、有的干脆是
+ * 代码里的 `process.env.X || '默认值'`。后果有三笔：
+ *   ① **设置页无法生成** —— 页面只能靠人一份份手写名单，加一项就要改 UI 代码（本批要终结它）；
+ *   ② **"缺配置"报错五花八门** —— 同一个缺失，有的静默用默认值、有的抛一句 `KeyError`，
+ *      用户不知道"该去哪配"；
+ *   ③ **秘密没有统一口径** —— 哪个字段是密钥、能不能进日志/页面，全靠各文件自觉。
+ *
+ * 本文件给两样东西（**声明**与**读取**分离，各自只有一处实现）：
+ *   · **目录**：`configs/<域>.json`（引擎级）＋ `verticals/<id>/config.json`（业务线级），
+ *     逐项声明 key/label/category/type/source/secret/default/required/validation/归属/editable/help；
+ *   · **读取器**：本文件导出的 {@link createReader}（`get`/`require`/`sourceOf`/`isConfigured`/
+ *     `all`/`describe`/`invalidate`）——**全仓库唯一一份解析链**。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 二、解析顺序（**固定五级**，声明只描述"主来源"，不改变链）
+ * ══════════════════════════════════════════════════════════════════════════
+ *     ① 进程环境变量    由 key 归一化的名字（`ml.daily.hour` → `ML_DAILY_HOUR`）
+ *     ② 域 env 文件     `<数据目录>/verticals/<vid>/env/<域>.env` → `<数据目录>/<域>.env`
+ *                       （规范路径优先、旧平铺兜底 —— 与 `scripts/flow_config.py` 同口径；
+ *                        `~/.dsh/argent/*.env` 的**文件路径一个字节都不动**，见契约 §7）
+ *     ③ `config.json`   `<数据目录>/config.json#<字段>`（控制台/设置页写的那一份）
+ *     ④ 业务线/机器本地文件  `<数据目录>/<文件>#<字段>`（如 `ml-api-stores.json` / `instance.json`）
+ *     ⑤ 声明里的 default
+ *
+ * **`source`（声明）与 `sourceOf()`（事实）是两件事**，别混读：
+ *   · `item.source` = 这一项的**主来源**（给人看"它该在哪"，`server` 为**预留**：本批不读、不写）；
+ *   · `sourceOf(key).layer` = 这一次**实际**是从哪一级取到的 —— 设置页要显示的就是它
+ *     （"已配置（来自 env 文件 fulfillment.env）"）。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 三、秘密纪律（**唯一红线，由门禁 ② 守着**）
+ * ══════════════════════════════════════════════════════════════════════════
+ *   · `secret: true` 的项：{@link createReader} 的 `describe()` **永不**回值（连长度都不回），
+ *     只回 `{ configured, resolvedFrom }`；`require()` 的报错**永不**带值；
+ *   · 目录文件里 secret 项**不得**写 `default` 的非空值、**不得**写 `example`；
+ *   · `get()` 仍会返回值 —— 它是给**进程内**用的，谁调用谁负责不落日志（门禁 ② 用"诱饵值"
+ *     断言 `describe()` / 报错 / 目录文件里都找不到它）。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 四、为什么在 L1（`core/lib/`）
+ * ══════════════════════════════════════════════════════════════════════════
+ *   · 契约 §1：**确定性逻辑只能落在 L1**（"这一项现在是配置好了还是没配"是判断，不是 UI）；
+ *   · 零宿主依赖：只 import `node:` 内建与同层的 `./argent-datadir.mjs`（数据目录唯一判据，
+ *     **不自己拼三级链**）⇒ `kernel-purity` 对 `core/**` 的扫描面天然干净；
+ *   · 页面（L2）与 CLI/MCP（L1）**消费同一份** `describe()`，不允许壳里再写一套"这值配没配"。
+ *
+ * 跑法（回归）：`node scripts/tests/config-gates.test.mjs`
+ * 门禁 CLI：`node scripts/check-config-catalog.mjs --strict`
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { resolveDataDir } from './argent-datadir.mjs'
+
+// ══════════════════════════════════════════════════════════════════════════
+// 一、契约枚举（**唯一一份**；门禁、读取器、页面都从这里取，不各写一套）
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 载荷 schema 名（页面按它做版本判断）。 */
+export const CATALOG_SCHEMA = 'argent-config-catalog/1'
+
+/** 引擎级目录所在目录（仓库根或安装根的相对路径）。 */
+export const CATALOG_DIR = 'configs'
+/** 业务线级目录文件名（落在 `verticals/<id>/` 下）。 */
+export const VERTICAL_CATALOG_FILE = 'config.json'
+/** 允许的目录文件形状：`<域>.json`（域名字母数字/下划线/连字符，不带路径分隔符）。 */
+export const CATALOG_FILE_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*\.json$/
+
+/** 项的 `source`（**主来源**；`server` = 预留，本批不读不写）。 */
+export const SOURCES = ['env', 'envfile', 'json', 'machine', 'server', 'default']
+/** 实际取值层（`sourceOf()` 的 `layer`）；`missing` 只在"没取到"时出现。 */
+export const LAYERS = ['env', 'envfile', 'json', 'machine', 'server', 'default', 'missing']
+/** 解析顺序（固定；`default` 恒最后）。 */
+export const RESOLUTION_ORDER = ['env', 'envfile', 'json', 'machine', 'server', 'default']
+/** 项的 `type`。`secret` 是**历史形态**：等价于 `type: string` + `secret: true`（门禁 ① 强制一致）。 */
+export const ITEM_TYPES = ['string', 'int', 'bool', 'enum', 'secret', 'path', 'list']
+/** `binding.kind`（"今天实际怎么读"）。 */
+export const BINDING_KINDS = ['env', 'envfile', 'json', 'machine', 'server']
+/** 列表派生方式（只给只读事实项用）。 */
+export const TRANSFORMS = ['length']
+/** 内核判据派生（不自己拼路径，走 `argent-datadir.mjs`）。 */
+export const SPECIALS = ['dataDir', 'dshHome', 'dataDirSource']
+/**
+ * key 必须点分命名（`ml.daily.hour`）。
+ * **只允许小写/数字/下划线** ⇒ {@link envNameOf} 是**无损**映射（大写 + `.`→`_`），
+ * 于是"进程环境变量"这一级不需要任何人工登记表；门禁 ① 另查"两个 key 不得归一成同一个
+ * 环境变量名"（否则进程 env 覆盖会串项）。
+ */
+export const KEY_RE = /^[a-z][a-z0-9_]*(?:\.[a-z0-9_]+)+$/
+/** 域 env 文件名形状（`daily-report.env`）；写死形状 = 防目录里塞任意路径。 */
+export const ENV_FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.env$/
+/** 目录文件里**不得**出现的键（secret 项尤其）：值是"真实样例"的字段一律不许进仓库。 */
+export const FORBIDDEN_ITEM_KEYS = ['example', 'sample', 'value', 'secretValue']
+
+const ITEM_REQUIRED_FIELDS = ['key', 'label', 'category', 'type', 'source', 'help']
+
+// ══════════════════════════════════════════════════════════════════════════
+// 二、纯函数小件（门禁与读取器共用）
+// ══════════════════════════════════════════════════════════════════════════
+
+/**
+ * key → 进程环境变量名：点分 → 下划线、大写、非字母数字下划线一律换成 `_`。
+ * `ml.daily.hour` → `ML_DAILY_HOUR`；`account.ziniao.apiKey` → `ACCOUNT_ZINIAO_APIKEY`。
+ */
+export function envNameOf(key) {
+  return String(key || '').trim().toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+}
+
+/** `a.b.c` 取值（对象；缺失 → undefined；数组下标不支持 —— 目录只声明定点字段）。 */
+export function pickPath(doc, path) {
+  if (!path) return doc
+  let cur = doc
+  for (const seg of String(path).split('.')) {
+    if (cur === null || cur === undefined) return undefined
+    if (typeof cur !== 'object') return undefined
+    cur = cur[seg]
+  }
+  return cur
+}
+
+/** `KEY=VALUE` 行解析（注释/空行/`export ` 前缀/成对引号；与 shell 同口径的保守子集）。 */
+export function parseEnvText(text) {
+  const out = {}
+  for (const raw of String(text || '').split('\n')) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    const m = /^(?:export[ \t]+)?([A-Za-z_][A-Za-z0-9_]*)[ \t]*=(.*)$/.exec(line)
+    if (!m) continue
+    let v = m[2].trim()
+    if ((v.startsWith('"') && v.endsWith('"') && v.length > 1) || (v.startsWith("'") && v.endsWith("'") && v.length > 1)) {
+      v = v.slice(1, -1)
+    }
+    out[m[1]] = v
+  }
+  return out
+}
+
+/** 值的字面类型名（报错/校验用；`null`/`undefined` 单独归 `empty`）。 */
+export function literalTypeOf(v) {
+  if (v === null || v === undefined || v === '') return 'empty'
+  if (Array.isArray(v)) return 'list'
+  if (typeof v === 'boolean') return 'bool'
+  if (typeof v === 'number') return 'int'
+  return 'string'
+}
+
+/** 按声明把字符串投成目标类型；投不动 → `{ ok:false, why }`（**不抛**，调用方决定）。 */
+export function coerce(value, type) {
+  if (value === undefined || value === null) return { ok: false, why: 'empty' }
+  const t = String(type)
+  // 标量型一律拒绝对象/数组：binding 写错时**响亮失败**，绝不吐出 "[object Object]"
+  if (t !== 'list' && typeof value === 'object') {
+    return { ok: false, why: `期望标量，实际拿到 ${Array.isArray(value) ? 'list' : 'object'}（binding 的 field 写错了？）` }
+  }
+  if (t === 'int') {
+    const s = String(value).trim()
+    if (!/^-?\d+$/.test(s)) return { ok: false, why: `不是整数：${JSON.stringify(s)}` }
+    return { ok: true, value: Number(s) }
+  }
+  if (t === 'bool') {
+    const s = String(value).trim().toLowerCase()
+    if (['1', 'true', 'yes', 'on'].includes(s)) return { ok: true, value: true }
+    if (['0', 'false', 'no', 'off', ''].includes(s)) return { ok: true, value: false }
+    return { ok: false, why: `不是布尔字面量：${JSON.stringify(String(value))}` }
+  }
+  if (t === 'list') {
+    if (Array.isArray(value)) return { ok: true, value }
+    const s = String(value).trim()
+    if (!s) return { ok: true, value: [] }
+    return { ok: true, value: s.split(',').map((x) => x.trim()).filter(Boolean) }
+  }
+  if (t === 'path') {
+    const s = String(value).trim()
+    if (!s) return { ok: false, why: 'empty' }
+    return { ok: true, value: s }
+  }
+  if (t === 'enum') {
+    const s = String(value).trim()
+    return s ? { ok: true, value: s } : { ok: false, why: 'empty' }
+  }
+  // string / secret
+  return { ok: true, value: typeof value === 'string' ? value : String(value) }
+}
+
+/**
+ * **写入落点**（本页能不能改、改了写去哪）—— L1 的判定，页面**只消费不复制**。
+ *
+ * 为什么必须有它（2026-10-09，设置页批次）："这一项可不可以从页面改"是**判断**（契约 §1：判断只能落 L1），
+ * 而且答案取决于 `editable` + `binding.kind` + 落点是否已有既有写入口三件事的合取。若让页面各自
+ * 推一遍，就会出现"页面显示能点保存、后端其实不受理"（或反之）——**两处判据必然漂移**。
+ *
+ * 返回值：`{ kind, label, file, field, env, vertical }` 或 `null`
+ *   · `kind: 'config'`  = 写 `<数据目录>/config.json#<field>`（既有落点：host 的 POST /api/argent-state/config）
+ *   · `kind: 'envfile'` = 写域 env 文件（既有落点：scripts/argent-env-write.mjs，受 ARGENT_ENV_WRITER 开关管）
+ *   · `null`            = 本页不可写（原因见 {@link writeBlockedReason}）
+ * ⛔ **不新增第三套存储**：只有上面两条既有落点，别的 binding 一律 `null`。
+ */
+export function writeTargetOf(item) {
+  if (!item || typeof item !== 'object') return null
+  if (item.editable !== true) return null
+  if (String(item.source) === 'server') return null          // 预留来源：本批不读不写
+  const b = item.binding || {}
+  if (b.special) return null                                 // 内核判据派生（数据目录/home/来源）
+  if (b.presence) return null                                // 存在性标记（暂停开关这类，由系统维护）
+  if (b.kind === 'json') {
+    const file = String(b.file || 'config.json')
+    if (file !== 'config.json' || !b.field) return null      // 只认既有那个 config.json 写入口
+    return { kind: 'config', label: `config.json#${b.field}`, file, field: String(b.field) }
+  }
+  if (b.kind === 'envfile') {
+    const file = String(b.file || '')
+    if (!file) return null
+    const vertical = b.vertical || item.vertical || null
+    return {
+      kind: 'envfile',
+      label: vertical ? `verticals/${vertical}/env/${file}` : file,
+      file, field: null,
+      env: String(b.env || envNameOf(item.key)),
+      vertical,
+    }
+  }
+  return null
+}
+
+/** 本页**不可写**的原因（`editable:true` 却拿不到落点时，页面要能说清"为什么改不了"）。 */
+export function writeBlockedReason(item) {
+  if (!item) return '未声明'
+  if (item.editable !== true) return '声明为只读（editable:false）'
+  if (String(item.source) === 'server') return '来源 server 为本批预留（当前无读取/写入实现）'
+  const b = item.binding || {}
+  if (b.special) return '内核判据派生（数据目录 / 宿主 home 等机器事实）'
+  if (b.presence) return '存在性标记（由系统/流程维护，不在页面改）'
+  if (b.kind === 'env') return '进程环境变量：由宿主启动环境提供，页面不写'
+  if (b.kind === 'machine') return '机器本地文件：由安装/体检生成，页面不写'
+  if (b.kind === 'json') return '声明指向的不是 config.json（脚本维护的部署事实，页面不写）'
+  return '声明里没有可写落点（binding 不指向既有写入口）'
+}
+
+/**
+ * **旧优先级提示**（`todayChain` 与规范链**首级不同** ⇒ 系统仍按旧优先级读）。
+ *
+ * 契约 §7.2 的 `todayChain` 如实登记"今天代码里的优先级"；读取器恒按规范链解析
+ * （`env → envfile → json → machine → server → default`）。两者首级不同时：页面写的是**该旧链的第一落点**
+ * （写对了），但**同名环境变量/env 文件一旦有值，实际生效的仍是旧链那一级** ⇒ 必须当面讲清，
+ * ⛔ 不能"看起来改了其实没改"。
+ */
+export function chainNoteOf(item) {
+  const t = item && Array.isArray(item.todayChain) ? item.todayChain : null
+  if (!t || !t.length) return null
+  if (String(t[0]) === RESOLUTION_ORDER[0]) return null
+  return `当前系统仍按**旧优先级**读取：${t.join(' → ')}（规范链是 ${RESOLUTION_ORDER.join(' → ')}）`
+    + ' —— 本页写入的是旧链的第一落点，写对了；但若同名环境变量 / env 文件同时有值，'
+    + '实际生效的仍是旧链里更靠前的那一级。'
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 二·五、**生效来源**（谁赢了）+ 密钥脱敏（2026-10-09，配置地基第三批次）
+// ══════════════════════════════════════════════════════════════════════════
+//
+// 要消灭的误会：**「我在设置页改了，但更靠前的那一级还在生效」**。
+// 既有提示（{@link chainNoteOf}）是**静态**的（只说"两套链不同序"），缺**逐项动态**的
+// "这一项此刻到底谁赢了、谁被压住了" —— 本节的纯函数补的就是它。
+//
+// 三条纪律（本批的行为契约）：
+//   ① **零行为变化**：本节的函数**不读文件、不写任何东西、不改变解析顺序**。它们只把
+//      "调用方已经取到的各级现值" 按**规范链**（{@link RESOLUTION_ORDER}）排一次序。
+//      读取器真正取值的那条路径（`resolveOne`）一个字节都没动。
+//   ② **可纯夹具回归**：`resolveEffective(item, levels)` 的输入全是普通对象 ⇒ 不碰磁盘也能测；
+//      真机取值的活儿由 {@link createReader} 的 `levelsOf()` 干（它复用同一份文件缓存）。
+//   ③ **密钥只在门外**：`secret: true` 的项，输出里的**任何**值位（含 `shadowed[].value`、
+//      `invalid[].why`）一律是 {@link redactSecret} 的产物，**永不含明文**（门禁 ② 另用诱饵值钉住）。
+
+/** 密钥占位形态：**只给"已设置 + 长度"**，不给任何前缀（前缀也能被撞库/比对）。 */
+export function redactSecret(value) {
+  const s = value === undefined || value === null ? '' : String(value)
+  return `❰已设置(长度${s.length})❱`
+}
+
+/** 值位脱敏：`secret: true` 的项走占位，其余原样（含 `false` / `0` / `''` 这类合法值）。 */
+export function maskIfSecret(value, secret) {
+  return secret ? redactSecret(value) : value
+}
+
+/**
+ * 这一项**读取器真会去看**哪几级（按规范链次序）。
+ *
+ * 判据与 `resolveOne` **逐条对齐**（两边必须同序同名，否则"生效来源"会与真实取值分家）：
+ *   · `env`      —— **恒**参与（任何 binding 都先试进程环境变量，名字 = `binding.env || envNameOf(key)`）；
+ *   · `envfile`  —— 仅当 `binding.kind === 'envfile'` 或 `source === 'envfile'`；
+ *   · `json` / `machine` —— 仅当 `binding.special`（内核判据派生 ⇒ `machine`）
+ *     或 `binding.kind` 是 `json` / `machine`（两者互斥）；
+ *   · `default`  —— 恒参与（恒最后一级）；
+ *   · `server`   —— **本批无读取实现**（预留来源）⇒ 不进这张表，但 CLI 会如实标"预留"。
+ */
+export function levelsApplicableTo(item) {
+  const b = (item && item.binding) || {}
+  const out = ['env']
+  if (b.kind === 'envfile' || (item && item.source === 'envfile')) out.push('envfile')
+  if (b.special) out.push('machine')
+  else if (b.kind === 'json') out.push('json')
+  else if (b.kind === 'machine') out.push('machine')
+  out.push('default')
+  return out
+}
+
+/**
+ * **纯函数**：给定一项声明 + "各级现值视图"，算出生效级与被压住的级。
+ *
+ * @param {object} item 目录里的一项声明（只读 `key` / `type` / `secret` / `binding` /
+ *        `source` / `default` / `todayChain`）
+ * @param {Record<string, any>} [levels] 各级现值（**调用方已取到**；本函数不读文件）：
+ *        `{ env, envfile, json, machine, server, default }`。缺席/`null` = 该级无值。
+ *        `levels.default` 省略时取 `item.default` —— 那是**声明里的最后一级**，不是隐式默认值。
+ * @param {{ chain?: string[] }} [opts] `chain` 覆盖规范链（默认 {@link RESOLUTION_ORDER}；夹具用）
+ * @returns {{ key: string, from: string|null, value: any, chain: string[], applicable: string[],
+ *             present: string[], shadowed: Array<{level: string, value: any, why: string}>,
+ *             conflict: boolean, invalid: Array<{level: string, why: string}>, secret: boolean,
+ *             todayChain: string[]|null, todayFirst: string|null, todayFirstPresent: boolean,
+ *             divergent: boolean, note: string }}
+ *
+ * 判据（**"谁赢"的顺序依据 = 规范链 `RESOLUTION_ORDER`，不是 `source`、也不是 `todayChain`**）：
+ *   ① `from` = 规范链里**第一个有值**的级（值还要能被声明的 `type` 投出来 —— 与 `resolveOne` 同口径；
+ *      投不动的级进 `invalid`，**不算有值**，正是"我设了但它其实没生效"的那种情形）；
+ *   ② `present` = **真实来源级**里有值且投得动的级名（按规范链次序，**不含 `default`**）；
+ *   ③ `shadowed` = `present` 里除 `from` 之外的级（**有值但被压住**），逐条给出被压住的原因；
+ *   ④ `conflict` = `shadowed.length > 0`（**≥2 个真实级同时有值**）；
+ *   ⑤ 空值判据：非 `default` 级缺席 = `undefined | null`（`false` / `0` / `''` 都**算有值**，
+ *      与 `resolveOne` 一致）；`default` 级另把 `''` 视为缺席；
+ *   ⑥ **`default` 是兜底级**：只有"其余级全都没值"时它才成为 `from`（那时 `present` 为空）——
+ *      声明里写了个默认值**不是冲突**（否则"有 default 的项"会全被标红）；
+ *   ⑦ `divergent` = **旧链第一落点此刻真有值**、且规范链从别的真实级取到值 ⇒ 两套口径答案不同；
+ *   ⑧ **不做任何写入、不做隐式默认**：本函数没有副作用，也不必知道数据目录在哪。
+ */
+export function resolveEffective(item, levels = {}, opts = {}) {
+  const it = item && typeof item === 'object' ? item : {}
+  const secret = it.secret === true
+  const chain = Array.isArray(opts.chain) && opts.chain.length ? [...opts.chain] : [...RESOLUTION_ORDER]
+  const view = levels && typeof levels === 'object' ? levels : {}
+  const wantType = it.type === 'secret' ? 'string' : String(it.type || 'string')
+  const applicable = levelsApplicableTo(it)
+
+  const present = []
+  const values = {}
+  const invalid = []
+  for (const level of chain) {
+    if (!applicable.includes(level)) continue
+    const raw = level === 'default'
+      ? (view.default !== undefined ? view.default : it.default)   // 声明里的 default = 最后一级
+      : view[level]
+    if (raw === undefined || raw === null) continue
+    if (level === 'default' && raw === '') continue                // 与 resolveOne 同口径：空 default 不算
+    const c = coerce(raw, wantType)
+    if (!c.ok) {
+      // ⛔ 密钥项的失败原因也可能带值（`coerce` 的 int 报错会回显字面量）⇒ 一律换成通用措辞
+      invalid.push({ level, why: secret ? '取值失败（密钥项不显示细节）' : c.why })
+      continue
+    }
+    values[level] = c.value
+    // `default` 是**兜底级**，不进 `present`/`shadowed`：声明里写了个默认值**不是冲突**
+    // （否则"有 default 的项"全都会被标成冲突，`--all` 当场失去意义）。
+    if (level !== 'default') present.push(level)
+  }
+
+  const from = present.length ? present[0] : (values.default !== undefined ? 'default' : null)
+  const shadowed = present.slice(1).map((level) => ({
+    level,
+    value: maskIfSecret(values[level], secret),
+    why: `规范链里 ${from} 比它靠前且已有值 ⇒ 它当前不生效`,
+  }))
+
+  // 今日链（`todayChain` 是**登记**的"今天代码里的优先级"，本批**不按它解析**）：
+  // 只做"两套口径是否分歧 + 旧链第一落点此刻有没有值"的如实呈现 —— ⛔ 不改读取顺序。
+  const todayChain = Array.isArray(it.todayChain) && it.todayChain.length ? it.todayChain.map(String) : null
+  const todayFirst = todayChain ? todayChain[0] : null
+  const todayFirstPresent = Boolean(todayFirst)
+    && (present.includes(todayFirst) || (todayFirst === 'default' && values.default !== undefined))
+  // "两套口径不一致" = **旧链第一落点此刻真有值**，且规范链从**别的真实级**取到值
+  // ⇒ 两个答案不一样（这才是"我在页面上改了、它却读别处"的那种情形）。
+  // 旧链第一落点没值时不算分歧（旧代码会自己往下走，最终落到同一处）。
+  const divergent = Boolean(from && from !== 'default' && todayFirst && todayFirst !== from && todayFirstPresent)
+
+  return {
+    key: String(it.key || ''),
+    from,
+    value: from ? maskIfSecret(values[from], secret) : null,
+    chain,
+    applicable,
+    present,
+    shadowed,
+    conflict: shadowed.length > 0,
+    invalid,
+    secret,
+    todayChain,
+    todayFirst,
+    todayFirstPresent,
+    divergent,
+    note: effectiveNote({ from, shadowed, present, invalid, todayFirst, todayFirstPresent, divergent }),
+  }
+}
+
+/** 生效来源的**人话**（L1 出文案，页面只渲染 —— 两处各写一份必然漂移）。 */
+export function effectiveNote({ from, shadowed, present, invalid, todayFirst, todayFirstPresent, divergent }) {
+  const parts = []
+  if (from === 'default') {
+    parts.push(`生效级：default（${present.length ? present.join(' / ') : '真实来源'}都没有值 ⇒ 用的是声明里的默认值）`)
+  } else if (from) {
+    parts.push(`生效级：${from}（按规范链 ${RESOLUTION_ORDER.join(' → ')} 取第一个有值的级）`)
+    parts.push(shadowed.length
+      ? `被压住：${shadowed.map((s) => `${s.level}（改了不生效：${from} 比它靠前且已有值）`).join('；')}`
+      : '无覆盖（其余级当前都没有值）')
+  } else {
+    parts.push('五级链全无值（也没有可用的声明 default）')
+  }
+  if (invalid && invalid.length) parts.push(`有值但取不动：${invalid.map((x) => `${x.level}（${x.why}）`).join('；')}`)
+  if (todayFirst) {
+    parts.push(`今天代码按登记的 todayChain 先读 ${todayFirst}（当前${todayFirstPresent ? '有值' : '无值'}）`)
+    if (divergent) parts.push(`⚠️ 与规范链生效级 ${from} 不是同一级 ⇒ 两套口径不一致（迁移未完，见「旧优先级」提示）`)
+  }
+  return parts.join('；')
+}
+
+/** 声明里的 validation 校验（pattern / enum / min / max / minLength）。→ `[]` 通过。 */
+export function validateValue(value, item) {
+  const v = item && item.validation
+  if (!v || typeof v !== 'object') return []
+  const problems = []
+  const isList = Array.isArray(value)
+  const text = isList ? value.join(',') : String(value ?? '')
+  if (v.pattern) {
+    let re = null
+    try { re = new RegExp(String(v.pattern)) } catch (e) { return [`validation.pattern 不是合法正则：${e.message}`] }
+    if (text && !re.test(text)) problems.push(`不匹配 pattern ${v.pattern}`)
+  }
+  if (Array.isArray(v.enum) && v.enum.length) {
+    const allowed = v.enum.map(String)
+    if (isList) {
+      for (const x of value) if (!allowed.includes(String(x))) problems.push(`值 ${JSON.stringify(String(x))} 不在 enum 内`)
+    } else if (text && !allowed.includes(text)) problems.push(`值不在 enum 内（允许：${allowed.join(' / ')}）`)
+  }
+  if (typeof v.min === 'number' || typeof v.max === 'number') {
+    const n = Number(value)
+    if (Number.isFinite(n)) {
+      if (typeof v.min === 'number' && n < v.min) problems.push(`小于下界 ${v.min}`)
+      if (typeof v.max === 'number' && n > v.max) problems.push(`大于上界 ${v.max}`)
+    }
+  }
+  if (typeof v.minLength === 'number' && !isList && text && text.length < v.minLength) {
+    problems.push(`长度小于 ${v.minLength}`)
+  }
+  return problems
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 三、目录加载（`configs/<域>.json` + `verticals/<id>/config.json`）
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 仓库/安装根：本文件在 `<根>/core/lib/` ⇒ 上跳两级。可用 `ARGENT_CATALOG_ROOT` 覆盖（夹具用）。 */
+export function catalogRoot(opts = {}) {
+  const env = opts.env || process.env
+  const explicit = (env && env.ARGENT_CATALOG_ROOT) || opts.root
+  if (explicit) return resolvePath(String(explicit))
+  return resolvePath(join(dirname(fileURLToPath(import.meta.url)), '..', '..'))
+}
+
+const readJson = (p) => {
+  try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return null }
+}
+
+/** 目录文件清单（引擎级 + 业务线级，按路径排序；只读，缺失即空列表）。 */
+export function listCatalogFiles(opts = {}) {
+  const root = catalogRoot(opts)
+  const out = []
+  const cdir = join(root, CATALOG_DIR)
+  if (existsSync(cdir)) {
+    let names = []
+    try { names = readdirSync(cdir) } catch { names = [] }
+    for (const n of names.sort()) {
+      if (!CATALOG_FILE_RE.test(n)) continue
+      out.push(join(cdir, n))
+    }
+  }
+  const vdir = join(root, 'verticals')
+  if (existsSync(vdir)) {
+    let vids = []
+    try { vids = readdirSync(vdir) } catch { vids = [] }
+    for (const vid of vids.sort()) {
+      if (vid.startsWith('.') || vid.startsWith('_')) continue
+      const p = join(vdir, vid, VERTICAL_CATALOG_FILE)
+      if (existsSync(p)) out.push(p)
+    }
+  }
+  return out
+}
+
+/**
+ * 读全部目录文件并展平成 `{ schema, root, files, items, entries, domains }`。
+ * `items` 保序（文件顺序 → 文件内顺序），**不**去重（重复 key 由 {@link validateCatalog} 判红）。
+ */
+export function loadCatalog(opts = {}) {
+  const root = catalogRoot(opts)
+  const env = opts.env || process.env
+  const files = opts.files || listCatalogFiles({ ...opts, root, env })
+  const items = []
+  const entries = []
+  const problems = []
+  const usedFiles = []
+  for (const abs of files) {
+    const doc = readJson(abs)
+    const rel = abs.startsWith(root) ? abs.slice(root.length + 1) : abs
+    if (!doc || typeof doc !== 'object') {
+      problems.push(`${rel}：不是合法 JSON 对象`)
+      continue
+    }
+    usedFiles.push(rel)
+    const domain = String(doc.domain || rel.split('/').pop().replace(/\.json$/, ''))
+    const vertical = doc.vertical ? String(doc.vertical) : (/^verticals\/([^/]+)\//.exec(rel) || [])[1] || null
+    // 域级 `order`（页面分区次序的**唯一真源**，契约 §7.2）：只在目录文件里写一次，随每一项/入口带下去
+    // ⇒ `describe()` 的分类树按它排序，页面**不写任何次序名单**（新增域 = 加文件，不改页面）。
+    const order = Number.isFinite(Number(doc.order)) ? Number(doc.order) : null
+    const fileEntries = Array.isArray(doc.entries) ? doc.entries : []
+    for (const e of fileEntries) {
+      entries.push({ ...e, domain, vertical: e.vertical || vertical, _file: rel, _order: order })
+    }
+    const list = Array.isArray(doc.items) ? doc.items : []
+    if (!Array.isArray(doc.items)) problems.push(`${rel}：缺 items 数组（目录文件必须显式声明，即使是空）`)
+    list.forEach((raw, i) => {
+      items.push({ ...raw, domain, vertical: raw.vertical || vertical, _file: rel, _index: i, _order: order })
+    })
+  }
+  return { schema: CATALOG_SCHEMA, root, files: usedFiles, items, entries, problems }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 四、目录自检（**门禁 ① 的一半**：声明本身合法）
+// ══════════════════════════════════════════════════════════════════════════
+
+/**
+ * 声明形状校验（唯一实现；门禁与测试都调它，不另写"测试版判据"）。
+ * @returns {string[]} 问题清单（空 = 合法）；每条形如 `<文件>:<key> 说明`。
+ */
+export function validateCatalog(cat) {
+  const problems = [...(cat.problems || [])]
+  const seen = new Map()
+  const entryIds = new Set()
+  for (const it of cat.items) {
+    const at = `${it._file}${it.key ? `:${it.key}` : `[${it._index}]`}`
+    for (const f of ITEM_REQUIRED_FIELDS) {
+      if (it[f] === undefined || it[f] === null || String(it[f]).trim() === '') problems.push(`${at} 缺必需字段 \`${f}\``)
+    }
+    if (it.key && !KEY_RE.test(String(it.key))) {
+      problems.push(`${at} key 必须是点分命名（如 \`ml.daily.hour\`）`)
+    }
+    if (it.key) {
+      if (seen.has(it.key)) problems.push(`${at} key 与 ${seen.get(it.key)} 重复（key 必须全局唯一）`)
+      else seen.set(it.key, at)
+    }
+    if (it.type && !ITEM_TYPES.includes(String(it.type))) {
+      problems.push(`${at} type=\`${it.type}\` 不在 ${ITEM_TYPES.join(' / ')} 内`)
+    }
+    if (it.source && !SOURCES.includes(String(it.source))) {
+      problems.push(`${at} source=\`${it.source}\` 不在 ${SOURCES.join(' / ')} 内（\`server\` 是预留来源）`)
+    }
+    if (it.type === 'secret' && it.secret !== true) {
+      problems.push(`${at} type=secret 必须同时写 \`secret: true\`（两处口径必须一致，否则页面会漏掩）`)
+    }
+    if (it.type === 'enum' && !(Array.isArray(it.validation && it.validation.enum) && it.validation.enum.length)) {
+      problems.push(`${at} type=enum 必须在 validation.enum 里列出允许值`)
+    }
+    for (const k of FORBIDDEN_ITEM_KEYS) {
+      if (it[k] !== undefined) problems.push(`${at} 不允许出现 \`${k}\` 字段（真实样例值不得进仓库；secret 项尤其）`)
+    }
+    if (it.secret === true) {
+      if (it.default !== undefined && it.default !== null && String(it.default) !== '') {
+        problems.push(`${at} secret 项不得写非空 default（默认值会进仓库、进日志）`)
+      }
+    }
+    if (it.validation && typeof it.validation !== 'object') problems.push(`${at} validation 必须是对象`)
+    if (it.todayChain !== undefined) {
+      if (!Array.isArray(it.todayChain) || !it.todayChain.length) problems.push(`${at} todayChain 必须是非空数组（层级名）`)
+      else for (const l of it.todayChain) {
+        if (!LAYERS.includes(String(l))) problems.push(`${at} todayChain 里的 \`${l}\` 不是合法层级（${LAYERS.join(' / ')}）`)
+      }
+    }
+    if (it.validation && it.validation.pattern) {
+      try { new RegExp(String(it.validation.pattern)) } catch (e) { problems.push(`${at} validation.pattern 不是合法正则：${e.message}`) }
+    }
+    if (it.editable !== undefined && typeof it.editable !== 'boolean') problems.push(`${at} editable 必须是布尔`)
+    if (it.required !== undefined && typeof it.required !== 'boolean') problems.push(`${at} required 必须是布尔`)
+    if (it.secret !== undefined && typeof it.secret !== 'boolean') problems.push(`${at} secret 必须是布尔`)
+    // 归属：至少要有 capability 或 vertical（否则"谁的东西"没人知道）
+    if (!it.capability && !it.vertical && !it.domain) problems.push(`${at} 缺归属（capability / vertical / domain 至少要有一个）`)
+    // binding：`source: server` 是预留 ⇒ 允许无 binding；其余必须有可执行的读法
+    const b = it.binding
+    if (String(it.source) === 'server') {
+      if (b) problems.push(`${at} source=server（预留来源）不得声明 binding —— 本批不读服务端`)
+    } else if (!b || typeof b !== 'object') {
+      problems.push(`${at} 缺 binding（非 server 来源必须有可执行的读法）`)
+    } else {
+      if (!BINDING_KINDS.includes(String(b.kind))) problems.push(`${at} binding.kind=\`${b.kind}\` 不在 ${BINDING_KINDS.join(' / ')} 内`)
+      if (b.kind === 'envfile' && !ENV_FILE_RE.test(String(b.file || ''))) {
+        problems.push(`${at} binding.file 必须是 \`<域>.env\` 形状（得到 ${JSON.stringify(b.file)}）`)
+      }
+      if (b.kind !== 'env' && b.kind !== 'server') {
+        const f = String(b.file || '')
+        if (f && (isAbsolute(f) || f.includes('..'))) problems.push(`${at} binding.file 必须是数据目录下的相对路径（不得绝对路径/上跳）`)
+      }
+      if (b.transform && !TRANSFORMS.includes(String(b.transform))) problems.push(`${at} binding.transform=\`${b.transform}\` 不在 ${TRANSFORMS.join(' / ')} 内`)
+      if (b.special && !SPECIALS.includes(String(b.special))) problems.push(`${at} binding.special=\`${b.special}\` 不在 ${SPECIALS.join(' / ')} 内`)
+    }
+  }
+  for (const e of cat.entries) {
+    const at = `${e._file}:${e.id || '(缺 id)'}`
+    if (!e.id || !String(e.id).trim()) problems.push(`${at} 入口缺 id`)
+    else if (entryIds.has(e.id)) problems.push(`${at} 入口 id 重复`)
+    else entryIds.add(e.id)
+    if (!e.label) problems.push(`${at} 入口缺 label`)
+    if (!e.category) problems.push(`${at} 入口缺 category`)
+    if (e.implemented !== undefined && typeof e.implemented !== 'boolean') problems.push(`${at} implemented 必须是布尔`)
+  }
+  return problems
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 五、读取器
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 缺配置错误：消息必须**可执行**（点名 key + 该去哪配 + 现有哪些来源）。 */
+export class ConfigMissingError extends Error {
+  constructor(message, { key, item, tried } = {}) {
+    super(message)
+    this.name = 'ConfigMissingError'
+    this.code = 'CONFIG_MISSING'
+    this.key = key
+    this.label = (item && item.label) || ''
+    this.tried = tried || []
+  }
+}
+
+/** 带 mtime/size 签名的文件缓存（配置一改就失效 ⇒ 页面立刻看到新值）。 */
+function fileCache() {
+  const map = new Map()
+  const sig = (p) => {
+    try { const st = statSync(p); return `${st.mtimeMs}:${st.size}` } catch { return 'absent' }
+  }
+  return {
+    text(p) {
+      const s = sig(p)
+      const hit = map.get(p)
+      if (hit && hit.sig === s) return hit.value
+      let value = null
+      if (s !== 'absent') { try { value = readFileSync(p, 'utf8') } catch { value = null } }
+      map.set(p, { sig: s, value })
+      return value
+    },
+    json(p) {
+      const t = this.text(p)
+      if (t === null) return null
+      try { return JSON.parse(t) } catch { return null }
+    },
+    env(p) {
+      const t = this.text(p)
+      return t === null ? null : parseEnvText(t)
+    },
+    clear() { map.clear() },
+    /** 缓存里有几个文件是"当前存在"的（诊断用）。 */
+    size() { return map.size },
+  }
+}
+
+/**
+ * 造一个读取器。**默认单例**见文件末尾的同名导出。
+ * @param {{ root?: string, env?: Record<string,string|undefined>, home?: string,
+ *           dataDir?: string, files?: string[] }} [opts]
+ */
+export function createReader(opts = {}) {
+  const env = opts.env || process.env
+  const cache = fileCache()
+  let catCache = null
+
+  const catalog = () => {
+    if (catCache && !opts.files) {
+      // 目录文件本身的改动也要立刻可见：签名（路径+mtime+size）不变才复用
+      const sig = listCatalogFiles({ ...opts, env }).map((p) => {
+        try { const st = statSync(p); return `${p}:${st.mtimeMs}:${st.size}` } catch { return `${p}:absent` }
+      }).join('|')
+      if (sig === catCache.sig) return catCache.cat
+    }
+    const cat = loadCatalog({ ...opts, env })
+    const sig = opts.files
+      ? 'fixed'
+      : cat.files.map((rel) => {
+        const p = join(cat.root, rel)
+        try { const st = statSync(p); return `${p}:${st.mtimeMs}:${st.size}` } catch { return `${p}:absent` }
+      }).join('|')
+    catCache = { cat, sig }
+    return cat
+  }
+
+  const byKey = () => {
+    const m = new Map()
+    for (const it of catalog().items) if (!m.has(it.key)) m.set(it.key, it)
+    return m
+  }
+
+  const dataDir = () => (opts.dataDir ? resolvePath(String(opts.dataDir)) : resolveDataDir({ env, home: opts.home }).dir)
+
+  /**
+   * 解析一项的**当前取值**。
+   * @returns {{ key, found: boolean, layer: string, detail: string, value?: any,
+   *             skipped?: string[], coerced?: boolean, problems?: string[] }}
+   */
+  function resolveOne(item) {
+    const tried = []
+    if (!item) return { key: '', found: false, layer: 'missing', detail: '未声明', tried }
+    const b = item.binding || {}
+    const name = String(b.env || envNameOf(item.key))
+    const wantType = item.type === 'secret' ? 'string' : String(item.type || 'string')
+
+    /** 逐层尝试：命中即投类型；投不动记一条 tried 继续往下（不静默吞成默认值）。 */
+    const attempt = (layer, detail, raw) => {
+      if (raw === undefined || raw === null) { tried.push(`${layer}:${detail}=未设置`); return null }
+      const c = coerce(raw, wantType)
+      if (!c.ok) { tried.push(`${layer}:${detail}=${c.why}`); return null }
+      return { key: item.key, found: true, layer, detail, value: c.value, tried, problems: validateValue(c.value, item) }
+    }
+
+    // ① 进程环境变量
+    const fromEnv = attempt('env', name, env ? env[name] : undefined)
+    if (fromEnv) return fromEnv
+
+    // ② 域 env 文件（规范路径优先、旧平铺兜底 —— 与 flow_config._resolve_env_path 同口径）
+    if (b.kind === 'envfile' || item.source === 'envfile') {
+      const file = String(b.file || '')
+      // 规范路径的**命名空间**以 `binding.vertical` 为准（引擎级目录里的项也可能指向某条业务线的
+      // env 目录）；`item.vertical` 是"这项归谁"的归属，两者可以不同（如 `host.path.stores_json`）。
+      const vid = b.vertical || item.vertical
+      const candidates = []
+      if (vid) candidates.push(join(dataDir(), 'verticals', vid, 'env', file))
+      candidates.push(join(dataDir(), file))
+      for (const p of candidates) {
+        const doc = cache.env(p)
+        if (doc === null) { tried.push(`envfile:${p}=文件不存在`); continue }
+        const hit = attempt('envfile', p, doc[name])
+        if (hit) return hit
+      }
+    }
+
+    // ④ json 与机器本地文件（同一套读法，只差 layer 标签）
+    //    ⚠️ 顺序：`binding.special`（内核判据派生）**先于**通用文件读 —— 否则"没写 file 的
+    //    special 项"会被通用分支当成"读 config.json 整个文档"，静默吐一个对象（实测踩过）。
+    if (b.special) {
+      const r = resolveDataDir({ env, home: opts.home })
+      const v = b.special === 'dataDir' ? r.dir : b.special === 'dshHome' ? r.dshHome : r.source
+      const hit = attempt('machine', `内核判据(${b.special})`, v)
+      if (hit) return hit
+    } else if (b.kind === 'json' || b.kind === 'machine') {
+      const file = String(b.file || 'config.json')
+      const p = join(dataDir(), file)
+      const doc = cache.json(p)
+      const layer = b.kind
+      if (doc === null) {
+        tried.push(`${layer}:${p}=文件不存在或不是 JSON`)
+      } else if (b.presence) {
+        return { key: item.key, found: true, layer, detail: p, value: true, tried, problems: [] }
+      } else {
+        let raw = b.field ? pickPath(doc, b.field) : doc
+        if (b.transform === 'length' && raw !== undefined && raw !== null) {
+          raw = Array.isArray(raw) ? raw.length : Object.keys(raw || {}).length
+        }
+        const hit = attempt(layer, `${p}${b.field ? `#${b.field}` : ''}`, raw)
+        if (hit) return hit
+      }
+    }
+
+    // ⑤ 声明里的 default
+    if (item.default !== undefined && item.default !== null && item.default !== '') {
+      const c = coerce(item.default, wantType)
+      if (c.ok) {
+        return { key: item.key, found: true, layer: 'default', detail: '声明 default', value: c.value, tried, problems: validateValue(c.value, item), fromDefault: true }
+      }
+      tried.push(`default:${c.why}`)
+    }
+
+    return { key: item.key, found: false, layer: 'missing', detail: '五级链全部未命中', tried, problems: [] }
+  }
+
+  /** 给报错用的"该去哪配"（声明的所有来源 → 可照做的落点）。 */
+  function whereToConfigure(item) {
+    const b = item.binding || {}
+    const out = []
+    const name = String(b.env || envNameOf(item.key))
+    if (b.kind === 'env' || item.source === 'env') out.push(`进程环境变量 ${name}`)
+    if (b.kind === 'envfile' || item.source === 'envfile') {
+      const file = String(b.file || `${item.domain || 'config'}.env`)
+      const vid = b.vertical || item.vertical
+      out.push(vid ? `${dataDir()}/verticals/${vid}/env/${file}（或旧平铺 ${dataDir()}/${file}）` : `${dataDir()}/${file}`)
+    }
+    if (b.kind === 'json') out.push(`${dataDir()}/${b.file || 'config.json'}${b.field ? ` 的 \`${b.field}\` 字段` : ''}（设置页「${item.category}」或 /api/argent-state/config）`)
+    if (b.kind === 'machine') out.push(`${dataDir()}/${b.file || 'config.json'}${b.field ? ` 的 \`${b.field}\` 字段` : ''}（机器本地文件，由安装/体检生成）`)
+    if (item.source === 'server') out.push('服务端（来源 server 为本批**预留**，当前无读取实现）')
+    if (item.default !== undefined && item.default !== null && item.default !== '') out.push(`声明 default=${JSON.stringify(item.default)}`)
+    return out.length ? out : ['（目录里没写任何可配落点 —— 请先补 binding）']
+  }
+
+  /**
+   * **逐级现值视图**（给 {@link resolveEffective} 用）：把"这一项在**每一级**上现在有没有值"
+   * 都取出来 —— 而 `resolveOne()` 只回**第一个命中**的级。两者的读法与缓存**完全共用**
+   * （同一个 `cache`、同一个 `dataDir()`），所以"生效来源"不会与真实取值分家。
+   *
+   * ⛔ **只取不改**：不写任何文件、不改变 `resolveOne` 的顺序；本函数只是把同样的几处
+   * 读一遍并把**每一级**的结果都留下（含落点路径）。`server` 级本批无读取实现 ⇒ 恒缺席。
+   *
+   * @returns {{ values: Record<string, any>, detail: Record<string, string> }}
+   */
+  function levelsOf(item) {
+    const b = (item && item.binding) || {}
+    const values = {}
+    const detail = {}
+    const applicable = levelsApplicableTo(item)
+    const secret = item && item.secret === true
+
+    // ① 进程环境变量（恒参与；名字与 resolveOne 同一处判据）
+    const name = String(b.env || envNameOf(item.key))
+    detail.env = `进程环境变量 ${name}`
+    if (env && env[name] !== undefined) values.env = env[name]
+
+    // ② 域 env 文件（规范路径优先、旧平铺兜底 —— 与 resolveOne 同一候选顺序）
+    if (applicable.includes('envfile')) {
+      const file = String(b.file || '')
+      const vid = b.vertical || item.vertical
+      const cands = []
+      if (vid) cands.push(join(dataDir(), 'verticals', vid, 'env', file))
+      cands.push(join(dataDir(), file))
+      const seen = []
+      for (const p of cands) {
+        const doc = cache.env(p)
+        if (doc === null) { seen.push(`${p}（文件不存在）`); continue }
+        if (doc[name] === undefined) { seen.push(`${p}（文件在，但没有 ${name}）`); continue }
+        seen.push(`${p}（**有** ${name}）`)
+        if (values.envfile === undefined) {
+          values.envfile = doc[name]
+          detail.envfile = p
+        }
+      }
+      if (detail.envfile === undefined) detail.envfile = `候选文件都没有 ${name}：${seen.join('；')}`
+      else if (seen.length > 1) detail.envfile = `${detail.envfile}（候选：${seen.join('；')}）`
+    }
+
+    // ④ json / 机器本地文件（与 resolveOne 同分支：`special` 优先，其次 binding.kind）
+    if (b.special) {
+      const r = resolveDataDir({ env, home: opts.home })
+      const v = b.special === 'dataDir' ? r.dir : b.special === 'dshHome' ? r.dshHome : r.source
+      values.machine = v
+      detail.machine = `内核判据（binding.special=${b.special}）`
+    } else if (b.kind === 'json' || b.kind === 'machine') {
+      const layer = b.kind
+      const file = String(b.file || 'config.json')
+      const p = join(dataDir(), file)
+      detail[layer] = `${p}${b.field ? `#${b.field}` : ''}`
+      const doc = cache.json(p)
+      if (doc === null) {
+        detail[layer] = `${detail[layer]}（文件不存在或不是 JSON）`
+      } else if (b.presence) {
+        values[layer] = true                       // 存在性标记（暂停开关这类）：文件在 = 有值
+        detail[layer] = `${detail[layer]}（存在性标记：文件在即有值）`
+      } else {
+        let raw = b.field ? pickPath(doc, b.field) : doc
+        if (b.transform === 'length' && raw !== undefined && raw !== null) {
+          raw = Array.isArray(raw) ? raw.length : Object.keys(raw || {}).length
+        }
+        if (raw !== undefined && raw !== null) values[layer] = raw
+        else detail[layer] = `${detail[layer]}（字段不存在）`
+      }
+    }
+
+    // ⑤ 声明里的 default（最后一级；空值不算 —— 与 resolveOne 同口径）
+    const hasDefault = item && item.default !== undefined && item.default !== null && item.default !== ''
+    values.default = hasDefault ? item.default : undefined
+    detail.default = hasDefault
+      ? `声明 default=${secret ? redactSecret(item.default) : JSON.stringify(item.default)}`
+      : '没有声明 default'
+
+    return { values, detail }
+  }
+
+  /**
+   * **这一项此刻的"生效来源"**（页面/CLI 要显示的就是它）：纯函数 {@link resolveEffective}
+   * 的取值封装 —— 值从 {@link levelsOf} 来，落点路径一并带上。
+   *
+   * ⛔ 输出里**永不含明文密钥**（`secret: true` 的项，值位全是 `❰已设置(长度N)❱`）。
+   */
+  function effectiveOf(key) {
+    const item = byKey().get(String(key))
+    if (!item) {
+      return {
+        key: String(key), from: null, value: null, chain: [...RESOLUTION_ORDER], applicable: [],
+        present: [], shadowed: [], conflict: false, invalid: [], secret: false,
+        todayChain: null, todayFirst: null, todayFirstPresent: false, divergent: false,
+        detail: '', levelDetail: {}, declared: false, note: `未声明的配置 key：${key}（目录里没有它）`,
+      }
+    }
+    const { values, detail } = levelsOf(item)
+    const eff = resolveEffective(item, values)
+    return {
+      ...eff,
+      detail: eff.from ? String(detail[eff.from] || '') : '',
+      levelDetail: detail,
+      declared: true,
+      declaredSource: item.source,
+      source: String(item.source) === 'server' ? '服务端（来源 server 为本批预留，当前无读取实现）' : undefined,
+    }
+  }
+
+  function missingMessage(item, res) {
+    const name = String((item.binding && item.binding.env) || envNameOf(item.key))
+    const lines = [
+      `缺配置：${item.key}（${item.label}）—— 该能力/业务线需要它才能继续。`,
+      ...(item.help ? [`这一项是什么：${item.help}`] : []),
+      `去哪里配：`,
+      ...whereToConfigure(item).map((x) => `  · ${x}`),
+      `已尝试的来源：`,
+      ...(res.tried || []).map((x) => `  · ${x}`),
+      `同名环境变量：${name}；查全部可配项：node scripts/check-config-catalog.mjs --list`,
+    ]
+    if (item.secret === true) lines.push('（这是密钥项：报错与日志都不会显示它的值）')
+    return lines.join('\n')
+  }
+
+  const reader = {
+    /** 当前目录（含 problems；门禁消费）。 */
+    catalog,
+    /** 数据目录（绝对路径；唯一判据）。 */
+    dataDir,
+    /** 目录自检（形状校验；门禁 ① 的一半）。 */
+    validate: () => validateCatalog(catalog()),
+
+    /** 取值（缺失或投类型失败 → 返回 fallback，不抛）。**secret 项也回值**（进程内用）。 */
+    get(key, fallback = undefined) {
+      const item = byKey().get(String(key))
+      if (!item) return fallback
+      const r = resolveOne(item)
+      return r.found ? r.value : fallback
+    },
+
+    /** 取值，缺失即**可执行报错**（点名 key + 该去哪配 + 已试来源）。 */
+    require(key) {
+      const item = byKey().get(String(key))
+      if (!item) {
+        const err = new ConfigMissingError(`未声明的配置 key：${key}（配置目录里没有它 ⇒ 先声明再读）`, { key: String(key), tried: [] })
+        err.code = 'CONFIG_UNDECLARED'
+        throw err
+      }
+      const r = resolveOne(item)
+      if (!r.found) throw new ConfigMissingError(missingMessage(item, r), { key: item.key, item, tried: r.tried })
+      return r.value
+    },
+
+    /** 这一项**此刻**的取值来自哪一级（页面要显示的就是它）。 */
+    sourceOf(key) {
+      const item = byKey().get(String(key))
+      if (!item) return { key: String(key), layer: 'missing', detail: '未声明', configured: false, declaredSource: null }
+      const r = resolveOne(item)
+      return {
+        key: item.key,
+        layer: r.layer,
+        detail: r.detail,
+        configured: r.found && r.layer !== 'default',
+        fromDefault: Boolean(r.fromDefault),
+        declaredSource: item.source,
+        tried: r.tried,
+      }
+    },
+
+    /** 已配置 = 从**任一真实来源**取到（`default` 不算"配好了"）。 */
+    isConfigured(key) { return reader.sourceOf(key).configured },
+
+    /** 某一项是否"此刻可解析"（含 default）。 */
+    isResolvable(key) { return reader.sourceOf(key).layer !== 'missing' },
+
+    /**
+     * **逐级现值视图**（含每级的落点路径）：`{ values, detail }`。
+     * ⛔ 返回值里**可能含明文密钥**（它等价于"把每一级都读一遍"）⇒ **只给进程内/CLI 判据用**，
+     * 任何出门的载荷（页面/端点）都走 {@link createReader}#effectiveOf（已脱敏）。
+     */
+    levelsOf(key) { return levelsOf(byKey().get(String(key))) },
+
+    /**
+     * **生效来源**（脱敏、可直接进载荷）：谁赢了、谁被压住、两套链是否分歧。
+     * 见纯函数 {@link resolveEffective}；本方法只负责"把各级现值取出来"。
+     */
+    effectiveOf(key) { return effectiveOf(key) },
+
+    /** 有冲突的项（≥2 级同时有值 ⇒ 有值被压住）：`--all` 与页首计数用。 */
+    conflicts() { return catalog().items.map((it) => effectiveOf(it.key)).filter((e) => e.conflict) },
+
+    /** 按条件列项（`category` / `capability` / `vertical` / `secret`）。 */
+    all(filter = {}) {
+      return catalog().items.filter((it) => {
+        if (filter.category && it.category !== filter.category) return false
+        if (filter.capability && it.capability !== filter.capability) return false
+        if (filter.vertical && it.vertical !== filter.vertical) return false
+        if (filter.secret !== undefined && Boolean(it.secret) !== Boolean(filter.secret)) return false
+        return true
+      })
+    },
+
+    /** 未解析的 `required` 项（装机体检/门禁 ③ 用）。 */
+    missingRequired(filter = {}) {
+      return reader.all(filter)
+        .filter((it) => it.required === true)
+        .map((it) => ({ item: it, res: resolveOne(it) }))
+        .filter((x) => !x.res.found)
+    },
+
+    /**
+     * **给设置页的载荷**（脱敏）。
+     * `secret: true` 的项**永不**出现在 `value` 里 —— 只回 `configured` + `resolvedFrom`。
+     */
+    describe(filter = {}) {
+      const cat = catalog()
+      const items = reader.all(filter).map((it) => {
+        const r = resolveOne(it)
+        const target = writeTargetOf(it)
+        const base = {
+          key: it.key,
+          label: it.label,
+          category: it.category,
+          domain: it.domain,
+          type: it.type,
+          declaredSource: it.source,
+          resolvedFrom: { layer: r.layer, detail: r.found || r.tried.length ? r.detail : '' },
+          configured: r.found && r.layer !== 'default',
+          resolvable: r.found,
+          fromDefault: Boolean(r.fromDefault),
+          required: it.required === true,
+          secret: it.secret === true,
+          editable: it.editable === true,
+          capability: it.capability || null,
+          vertical: it.vertical || null,
+          help: it.help || '',
+          validation: it.validation || null,
+          pendingServer: it.source === 'server',
+          // ── 页面消费面（2026-10-09，设置页批次）——**判断全在 L1**，页面只渲染 ──────────
+          // `writable` = 能写 + 写去哪（既有落点：config.json / 域 env 文件；⛔ 不新增第三套存储）；
+          // 为空且 `editable:true` ⇒ `writeBlocked` 说清为什么改不了（页面不留空白让人猜）。
+          writable: target,
+          writeBlocked: target ? null : writeBlockedReason(it),
+          // 旧优先级提示（`todayChain` 首级 ≠ 规范链首级；全仓库 18 项登记在案）
+          chainNote: chainNoteOf(it),
+          // **今天代码里的优先级**（迁移用；读取器**不**按它解析 —— 解析链恒为 RESOLUTION_ORDER）。
+          // 为空 = 与规范链一致；非空 = 把调用方迁到读取器前必须先核对这条差异。
+          todayChain: Array.isArray(it.todayChain) ? [...it.todayChain] : null,
+          // ── 生效来源（2026-10-09，第三批次）—— **动态**回答"这一项此刻谁赢了" ──────────────
+          // 与上面的 `chainNote`（静态说明"两套链不同序"）互补：`chainNote` 说"链不一样"，
+          // `effective` 说"**这一次**是谁赢了、谁被压住了、旧链第一落点此刻有没有值"。
+          // 判据 = 纯函数 `resolveEffective()`（按规范链取第一有值的级）；⛔ 不含明文密钥。
+          effective: (() => {
+            const e = effectiveOf(it.key)
+            return {
+              from: e.from,
+              present: e.present,
+              shadowed: e.shadowed,
+              conflict: e.conflict,
+              note: e.note,
+              detail: e.detail,
+              todayChain: e.todayChain,
+              todayFirst: e.todayFirst,
+              todayFirstPresent: e.todayFirstPresent,
+              divergent: e.divergent,
+              ...(e.invalid.length ? { invalid: e.invalid } : {}),
+            }
+          })(),
+        }
+        if (it.secret === true) return base                       // ⛔ 不回值、不回长度、不回 default
+        base.value = r.found ? r.value : null
+        base.default = it.default !== undefined ? it.default : null
+        if (r.problems && r.problems.length) base.problems = r.problems
+        return base
+      })
+      // ── 分类树：**次序的唯一真源 = 目录文件的 `order` + 文件内 items 顺序**（契约 §7.2/§7.6）──
+      // 页面按数组顺序分节渲染 ⇒ 加一个域文件（带 order）就多一个分区，⛔ 不改页面代码。
+      // `order`/`domains` 取自**声明**（不受 filter 影响）；计数只统计 filter 后的 items（与改动前一致）。
+      const orderByCat = new Map()
+      const domainsByCat = new Map()
+      for (const it of cat.items) {
+        const k = String(it.category)
+        const o = Number(it._order)
+        if (Number.isFinite(o)) orderByCat.set(k, o)
+        else if (!orderByCat.has(k)) orderByCat.set(k, null)
+        if (!domainsByCat.has(k)) domainsByCat.set(k, new Set())
+        if (it.domain) domainsByCat.get(k).add(String(it.domain))
+      }
+      const byCat = new Map()
+      for (const it of items) {
+        const k = String(it.category)
+        if (!byCat.has(k)) {
+          byCat.set(k, { id: k, label: k, items: 0, secrets: 0, configured: 0, required: 0, capabilities: new Set() })
+          if (!orderByCat.has(k)) orderByCat.set(k, null)
+        }
+        const c = byCat.get(k)
+        c.items++
+        if (it.secret) c.secrets++
+        if (it.configured) c.configured++
+        if (it.required) c.required++
+        if (it.capability) c.capabilities.add(it.capability)
+      }
+      const firstSeen = new Map([...byCat.keys()].map((k, i) => [k, i]))
+      const categories = [...byCat.values()]
+        .map((c) => ({
+          ...c,
+          order: orderByCat.get(c.id) === undefined ? null : orderByCat.get(c.id),
+          domains: [...(domainsByCat.get(c.id) || [])].sort(),
+          capabilities: [...c.capabilities].sort(),
+        }))
+        .sort((a, b) => {
+          const ao = a.order === null || a.order === undefined ? 100 : a.order
+          const bo = b.order === null || b.order === undefined ? 100 : b.order
+          if (ao !== bo) return ao - bo
+          return firstSeen.get(a.id) - firstSeen.get(b.id)
+        })
+      return {
+        schema: CATALOG_SCHEMA,
+        catalogFiles: cat.files,
+        resolutionOrder: [...RESOLUTION_ORDER],
+        dataDir: dataDir(),
+        categories,
+        items,
+        entries: cat.entries.map((e) => ({
+          id: e.id,
+          label: e.label,
+          category: e.category,
+          kind: e.kind || 'action',
+          action: e.action || null,
+          implemented: e.implemented === true,
+          capability: e.capability || null,
+          vertical: e.vertical || null,
+          help: e.help || '',
+          order: Number.isFinite(Number(e._order)) ? Number(e._order) : null,
+          domain: e.domain || null,
+        })),
+        missingRequired: items.filter((i) => i.required && !i.resolvable).map((i) => i.key),
+        // 有冲突的项（≥2 级同时有值 ⇒ 有值被压住）：页面页首计数 + CLI `--all` 的同一判据。
+        conflictKeys: items.filter((i) => i.effective && i.effective.conflict).map((i) => i.key),
+      }
+    },
+
+    /** 显式失效（配置改完页面要立刻看到；也有 mtime 签名兜底）。 */
+    invalidate() { cache.clear(); catCache = null },
+  }
+  return reader
+}
+
+/** **默认读取器**（进程内单例；`ARGENT_CATALOG_ROOT` 可覆盖根，夹具用）。 */
+export const config = createReader()
+export const get = (...a) => config.get(...a)
+export const requireKey = (...a) => config.require(...a)
+export const sourceOf = (...a) => config.sourceOf(...a)
+export const isConfigured = (...a) => config.isConfigured(...a)
+export const all = (...a) => config.all(...a)
+export const describe = (...a) => config.describe(...a)
+export const invalidate = (...a) => config.invalidate(...a)
+
+export default config