@thincoder/core 0.9.5 → 0.10.2

package/conventions.mjs

@@ -1,34 +1,48 @@
 /**
- * conventions.mjs — the single authority for code / doc / temp path classification,
- * plus the project convention declaration surface (`.thincoder/conventions.json`).
+ * conventions.mjs — the single authority for code / doc / temp / aux path classification,
+ * plus the project declaration surface (the three declaration families of the project's
+ * `PROJECT-MANIFEST.json`: `codePaths` / `index.*` / `advisor.*`).
  *
- * Why one module: engineering-mode gates and guards (design gate, review-doc gate,
+ * Why one module: the write-domain gates and guards (design gate, review-doc gate,
  * mutation accounting, verify fast path) each carried their own copy of the
  * "what counts as product code" predicate — anchored `^src/` regexes, `docs/`
  * prefix checks, component regexes. Each copy drifted, and each hardcoded THIS
  * repository's layout: a project whose code lives outside `src/` slipped through
- * the design gate silently (PORTABILITY FR12 / PO-10). One classifier + one
- * declaration file = one truth.
+ * the design gate silently (PORTABILITY FR12 / PO-10). One classifier + one declared
+ * carrier = one truth. It is a **shared** classification surface: the gates are consumers,
+ * not owners (consumer faces: advisor / agent-tools / both ends).
  *
- * Defaults are DATA (`DEFAULT_CODE_PATHS`) — overridable per project through the
- * declaration file (§4.1 schema). Missing file → pure defaults (no noise);
- * corrupt/unreadable file → defaults + console.warn + a log event (never crash,
- * never swallow — PORTABILITY FR10).
+ * Declaration (2026-09-27 · `.thincoder/conventions.json` retired — single carrier):
+ *   the three families live in the project manifest and are projected through `manifest.mjs`
+ *   → `declaration.mjs` (declaration loading split out of this file 2026-10-01 — this file keeps the
+ *   classification adjudication; ONE reader / ONE root resolution — `readManifest` + `manifestFilePath`;
+ *   name / shape / defaults are schema-owned by `docs/core/design/MANIFEST.md` §2.2).
+ *   Missing manifest → pure defaults (silent); unusable manifest (invalid / read error) →
+ *   defaults + console.warn + a log event (never crash, never swallow — PORTABILITY FR10/D16).
+ *   A retired `.thincoder/conventions.json` is never read: while present it yields ONE
+ *   visible warning per load (existence check only — zero content parsing — KD-M1-34).
  *
- * Classification vocabulary (PORTABILITY design §3.1):
- *   code — inside a declared code segment (default: the path segment `src`), or
- *          not a documentation extension;  doc — documentation extension outside
- *          any code segment;  temp — tmp-* name or .tmp/.temp extension.
+ * Classification vocabulary (PORTABILITY design §3.2):
+ *   code — inside a declared code segment (default: the path segment `src`), or the
+ *          fallback;  doc — documentation extension outside any code segment and not
+ *          scratch;  temp — tmp-* name or .tmp/.temp extension;  aux — a default
+ *          auxiliary-path segment sequence (test / tests / scripts / .thincoder/tmp —
+ *          F9) that matched no code segment and neither doc nor temp.
+ * Precedence: code segment → temp → doc → aux → fallback code.
+ *
+ * Segment matching runs on the PROJECT-ROOT-RELATIVE FACE of a path (D17 · 2026-09-28): the
+ * machine layout ABOVE the project root never participates. An absolute path outside the
+ * root / an unknown root / a `.`-`..` jump segment ⇒ the face is indeterminate: code segments
+ * fall back to the whole path (the interception surface does not shrink), aux sequences do
+ * NOT match (the former fail-open edge — an ancestor segment exempted a whole subtree).
  */
-import { readFileSync } from "node:fs"
-import { join, resolve } from "node:path"
-import { logEvent } from "./log.mjs"
-
-/** Default code-path segments (data, not logic — a project may replace them). */
-export const DEFAULT_CODE_PATHS = ["src"]
+import { DEFAULT_DECLARATION } from "./declaration.mjs"
 
-/** Project declaration file, relative to the project root. */
-export const CONVENTIONS_REL_PATH = ".thincoder/conventions.json"
+/** Default auxiliary-path segment sequences (data, not logic — F9): the engineering-mode
+ *  parent gate's default exemption surface — `test` / `tests` / `scripts` at any depth,
+ *  plus the `.thincoder/tmp` scratch space (two-segment sequence). Not declarable — a
+ *  project reclaims a sequence by listing it in `codePaths` (code segment wins). */
+export const DEFAULT_AUX_PATHS = ["test", "tests", "scripts", ".thincoder/tmp"]
 
 /** Documentation predicate (moved here verbatim from advisor/repos.mjs — one copy). */
 const DOC_FILE = /(?:^|[/\\])(?:LICENSE|NOTICE|CHANGELOG|AUTHORS)(?:\.\w+)?$|\.(?:md|markdown|mdx|txt|rst|adoc)$/i
@@ -46,18 +60,44 @@ function segmentsOf(p) {
   return String(p ?? "").replace(/\\/g, "/").split("/").filter(Boolean)
 }
 
+const lowerSeg = (s) => s.toLowerCase()
+const isJumpSeg = (seg) => seg === "." || seg === ".."
+
+/**
+ * The segment-matching face of a path — its position INSIDE the project (PORTABILITY design
+ * §3.2 · D17「段匹配面 = 项目根相对面」):
+ *   · absolute form under the root (separators normalized + per-segment case-insensitive
+ *     comparison) ⇒ the REMAINING segments (an EMPTY list when the path IS the root);
+ *   · relative form ⇒ its own segments;
+ *   · anything else — outside the root / root unknown / a `.` / `..` jump segment ⇒
+ *     `null` = indeterminate.
+ */
+function faceOf(p, root) {
+  const s = String(p ?? "").replace(/\\/g, "/")
+  const segs = segmentsOf(s)
+  if (!/^([A-Za-z]:|\/)/.test(s)) return segs.some(isJumpSeg) ? null : segs.map(lowerSeg)
+  if (typeof root !== "string" || root === "") return null
+  const rootSegs = segmentsOf(root).map(lowerSeg)
+  if (segs.length < rootSegs.length) return null
+  for (let i = 0; i < rootSegs.length; i++) {
+    if (lowerSeg(segs[i]) !== rootSegs[i]) return null
+  }
+  const rest = segs.slice(rootSegs.length)
+  if (rest.length === 0) return []
+  return rest.some(isJumpSeg) ? null : rest.map(lowerSeg)
+}
+
 /**
- * True when the path contains a declared code segment sequence at any depth.
+ * True when `segments` contain any of the given segment sequences at any depth.
  * Segment matching (not a prefix anchor) is what closes the nested-layout hole:
- * `packages/foo/src/x.md` is product code, not a document. Comparison is
- * case-insensitive — on case-insensitive filesystems `Src/x.mjs` is the same
- * directory, and the gate must not be bypassable by casing.
+ * `packages/foo/src/x.md` matches the sequence ["src"] — product code, not a
+ * document. Comparison is case-insensitive — on case-insensitive filesystems
+ * `Src/x.mjs` is the same directory, and the gate must not be bypassable by casing.
  */
-function hasCodeSegment(p, conv) {
-  const parts = segmentsOf(p).map((s) => s.toLowerCase())
-  const wanted = conv?.codePaths ?? DEFAULT_CODE_PATHS
-  for (const entry of wanted) {
-    const want = segmentsOf(entry).map((s) => s.toLowerCase())
+function hasSequenceIn(segments, sequences) {
+  const parts = segments.map(lowerSeg)
+  for (const entry of sequences) {
+    const want = segmentsOf(entry).map(lowerSeg)
     if (want.length === 0) continue
     for (let i = 0; i + want.length <= parts.length; i++) {
       if (want.every((seg, j) => parts[i + j] === seg)) return true
@@ -66,15 +106,40 @@ function hasCodeSegment(p, conv) {
   return false
 }
 
-/** "code" | "doc" | "temp" — the single classification decision.
+/**
+ * Segment matching on the project-root-relative face (D17). An indeterminate face splits the
+ * two callers by design: code segments fall back to the WHOLE path (`fallbackAll` — the
+ * interception surface does not shrink), while aux sequences do NOT match (the former
+ * fail-open edge: an ancestor segment above the root used to exempt a whole subtree).
+ */
+function hasSegmentSequence(p, sequences, root, fallbackAll) {
+  const face = faceOf(p, root)
+  if (face === null) return fallbackAll ? hasSequenceIn(segmentsOf(p), sequences) : false
+  return hasSequenceIn(face, sequences)
+}
+
+/** True when the path contains a declared code segment sequence (on the face — D17). */
+function hasCodeSegment(p, conv) {
+  return hasSegmentSequence(p, conv?.codePaths ?? DEFAULT_DECLARATION.codePaths, conv?.root, true)
+}
+
+/** True when the path contains a default auxiliary-path segment sequence (F9 · face-bound). */
+function hasAuxSegment(p, conv) {
+  return hasSegmentSequence(p, DEFAULT_AUX_PATHS, conv?.root, false)
+}
+
+/** "code" | "doc" | "temp" | "aux" — the single classification decision.
  *  Precedence: code segment first (src/** stays product code even when the name
  *  looks scratch — the pre-existing unconditional-src rule), then temp, then a
- *  documentation extension, else code (anything not doc/temp is product code). */
+ *  documentation extension, then an auxiliary-path segment sequence (test / tests
+ *  / scripts / .thincoder/tmp — F9), else code (anything not doc/temp/aux is product
+ *  code). Both segment checks run on the project-root-relative face (D17 — `faceOf`). */
 export function classifyPath(p, conv) {
   const s = String(p ?? "")
   if (hasCodeSegment(s, conv)) return "code"
   if (TEMP_FILE.test(s)) return "temp"
   if (DOC_FILE.test(s)) return "doc"
+  if (hasAuxSegment(s, conv)) return "aux"
   return "code"
 }
 
@@ -90,134 +155,18 @@ export function isDocPath(p, conv) {
   return DOC_FILE.test(s) && !hasCodeSegment(s, conv)
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Declaration loading (cached per project root — `clearConventionsCache()` is
-// the test seam; declaration files change rarely and only at session scope).
-// ─────────────────────────────────────────────────────────────────────────────
-
-function normalizeExtensions(v) {
-  if (!Array.isArray(v)) return []
-  const out = []
-  for (const e of v) {
-    if (typeof e !== "string") continue
-    const t = e.trim().toLowerCase()
-    if (!t) continue
-    const ext = t.startsWith(".") ? t : `.${t}`
-    if (!out.includes(ext)) out.push(ext)
-  }
-  return out
+/** True when the path is an auxiliary path (`classifyPath === "aux"`) — the engineering-mode
+ *  parent gate's default exemption surface (test / tests / scripts at any depth ·
+ *  .thincoder/tmp/** — matched on the project-root-relative face only, D17). Not declarable:
+ *  a project reclaims one by listing its sequence in `codePaths`, which then wins (code
+ *  segment first). Production faces read aux through classifyPath / isCodePath; this
+ *  predicate is the readable form for the test face. */
+export function isAuxPath(p, conv) {
+  return classifyPath(p, conv) === "aux"
 }
 
-/** Declared code paths replace the default (replacement, not union — §4.1). */
-function normalizeCodePaths(v) {
-  if (!Array.isArray(v)) return null
-  const out = []
-  for (const e of v) {
-    if (typeof e !== "string") continue
-    const s = e.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "")
-    if (!s || out.includes(s)) continue
-    out.push(s)
-  }
-  return out.length > 0 ? out : null
-}
-
-function normalizeString(v) {
-  return typeof v === "string" && v.trim() ? v.trim() : ""
-}
-
-/** Per-key type check for recognized keys (present but wrong type). §3.2/§4.1: a
- *  type error degrades WITH a warning — never silently (the fallback semantics stay
- *  per-key; only the visibility is added here). */
-function typeErrorsOf(raw) {
-  const isObj = (v) => v !== undefined && v !== null && typeof v === "object" && !Array.isArray(v)
-  const strArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string")
-  const errs = []
-  if (raw.codePaths !== undefined && !strArray(raw.codePaths)) errs.push("codePaths must be an array of strings")
-  const idx = raw.index
-  if (idx !== undefined && !isObj(idx)) errs.push("index must be an object")
-  else if (isObj(idx)) {
-    for (const k of ["codeExtensions", "docExtensions"]) {
-      if (idx[k] !== undefined && !strArray(idx[k])) errs.push(`index.${k} must be an array of strings`)
-    }
-  }
-  const adv = raw.advisor
-  if (adv !== undefined && !isObj(adv)) errs.push("advisor must be an object")
-  else if (isObj(adv)) {
-    for (const k of ["docMap", "standardsDoc"]) {
-      if (adv[k] !== undefined && typeof adv[k] !== "string") errs.push(`advisor.${k} must be a string`)
-    }
-  }
-  return errs
-}
-
-function buildConventions(raw) {
-  const codePaths = normalizeCodePaths(raw?.codePaths)
-  const codeExtensions = normalizeExtensions(raw?.index?.codeExtensions)
-  const docExtensions = normalizeExtensions(raw?.index?.docExtensions)
-  const docMap = normalizeString(raw?.advisor?.docMap)
-  const standardsDoc = normalizeString(raw?.advisor?.standardsDoc)
-  // `declared` = the declaration actually took effect (at least one recognized key
-  // honored) — the design-gate hint reads it to decide whether to point at the
-  // declaration file ("declare project conventions … to adjust").
-  const declared = Boolean(codePaths || codeExtensions.length || docExtensions.length || docMap || standardsDoc)
-  return Object.freeze({
-    declared,
-    codePaths: Object.freeze(codePaths ?? [...DEFAULT_CODE_PATHS]),
-    index: Object.freeze({
-      codeExtensions: Object.freeze(codeExtensions),
-      docExtensions: Object.freeze(docExtensions),
-    }),
-    advisor: Object.freeze({ docMap, standardsDoc }),
-  })
-}
-
-/** Full-default conventions (no declaration) — the fallback every consumer gets. */
-export const DEFAULT_CONVENTIONS = buildConventions(null)
-
-const _cache = new Map()
-
-/** Drop the per-root cache (test seam — declaration files are read once per root). */
-export function clearConventionsCache() {
-  _cache.clear()
-}
-
-/**
- * Load (and cache) the normalized conventions for a project root.
- * @param {string} cwd — project root (declaration lives at .thincoder/conventions.json)
- * @returns {Readonly<{declared: boolean, codePaths: readonly string[],
- *   index: {codeExtensions: string[], docExtensions: string[]},
- *   advisor: {docMap: string, standardsDoc: string}}>}
- */
-export function loadConventions(cwd) {
-  const root = resolve(cwd ?? process.cwd())
-  const hit = _cache.get(root)
-  if (hit) return hit
-  let conv = DEFAULT_CONVENTIONS
-  try {
-    const text = readFileSync(join(root, CONVENTIONS_REL_PATH), "utf8")
-    try {
-      const raw = JSON.parse(text)
-      if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("top level must be a JSON object")
-      conv = buildConventions(raw)
-      const typeErrs = typeErrorsOf(raw)
-      if (typeErrs.length > 0) {
-        // Wrong-typed keys fall back per-key — but the user must SEE that their
-        // declaration did not take effect (never silently swallowed).
-        console.warn(`[conventions] ${CONVENTIONS_REL_PATH} has invalid value types (${typeErrs.join("; ")}) — those keys fall back to defaults`)
-        logEvent("conventions:error", { cwd: root, err: `type errors: ${typeErrs.join("; ").slice(0, 160)}` })
-      }
-    } catch (e) {
-      // Corrupt file / wrong shape → defaults, visible: warn + event (never silent).
-      console.warn(`[conventions] ${CONVENTIONS_REL_PATH} unreadable (${e?.message ?? e}) — falling back to defaults`)
-      logEvent("conventions:error", { cwd: root, err: String(e?.message ?? e).slice(0, 200) })
-    }
-  } catch (e) {
-    if (e?.code !== "ENOENT") {
-      // File exists but cannot be read (EACCES etc.) — same visible degradation.
-      console.warn(`[conventions] ${CONVENTIONS_REL_PATH} not readable (${e?.message ?? e}) — falling back to defaults`)
-      logEvent("conventions:error", { cwd: root, err: String(e?.message ?? e).slice(0, 200) })
-    }
-  }
-  _cache.set(root, conv)
-  return conv
-}
+// ─────────────────────────────────────────────────────────────────────────────
+// 迁出面（2026-10-01 拆分批 · #755 ∥ #786）：声明装载面外提 `declaration.mjs`——本档经
+// 转口保名（消费面 / 批内件 import 面零改；`DEFAULT_DECLARATION` 另供本档分类裁判缺省取用）。
+// ─────────────────────────────────────────────────────────────────────────────
+export { loadProjectDeclaration, DEFAULT_DECLARATION, isExcludedRelPath, declaredPublicRoots, clearDeclarationCache } from "./declaration.mjs"

package/declaration.mjs

@@ -0,0 +1,194 @@
+/**
+ * declaration.mjs — 声明装载面（PROJECT-MANIFEST.json 三族 `codePaths` / `index.*` / `advisor.*`）
+ * · 自 `conventions.mjs` 迁出 · 2026-10-01 core 拆分批 #755 ∥ #786。
+ * 投影单源 = `manifest.mjs`（ONE reader / ONE root resolution——`readManifest` + `manifestFilePath`；
+ * name / shape / defaults = schema 面 `docs/core/design/MANIFEST.md` §2.2）。迁出块逐字；
+ * 原档 `conventions.mjs` 经 `export { … } from` 转口保名（消费面 / 批内件 import 面零改）。
+ */
+import { existsSync } from "node:fs"
+import { dirname, isAbsolute, join, relative, resolve } from "node:path"
+import { DEFAULT_MANIFEST, manifestFilePath, readManifest } from "./manifest.mjs"
+import { logEvent } from "./log.mjs"
+
+/** Retired declaration carrier (project-root relative). Its EXISTENCE is checked, its
+ *  content is never read — the declaration surface = the manifest three families (KD-M1-34). */
+const RETIRED_REL_PATH = ".thincoder/conventions.json"
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Declaration loading — the three families of PROJECT-MANIFEST.json, projected
+// through manifest.mjs (ONE reader / ONE root resolution) and cached per DATA-FILE
+// PATH (`clearDeclarationCache()` is the test seam; declarations change rarely).
+// ─────────────────────────────────────────────────────────────────────────────
+
+function normalizeExtensions(v) {
+  if (!Array.isArray(v)) return []
+  const out = []
+  for (const e of v) {
+    if (typeof e !== "string") continue
+    const t = e.trim().toLowerCase()
+    if (!t) continue
+    const ext = t.startsWith(".") ? t : `.${t}`
+    if (!out.includes(ext)) out.push(ext)
+  }
+  return out
+}
+
+/** Declared code paths replace the default (replacement, not union — §3.1). An EMPTY
+ *  array is a legal declaration ("no segment-based code face") — only a non-array value
+ *  falls back to `null` (⇒ caller keeps the default). */
+function normalizeCodePaths(v) {
+  if (!Array.isArray(v)) return null
+  const out = []
+  for (const e of v) {
+    if (typeof e !== "string") continue
+    const s = e.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "")
+    if (!s || out.includes(s)) continue
+    out.push(s)
+  }
+  return out
+}
+
+/** 路径列表归一（单源——`index.excludePaths` §6.14 ∥ `index.publicRepos` §6.15 同款）：首部 `./` 剥离 · `\`→`/` · 去尾斜杠 · 空 ∕ 非串剔除 · 去重保序。 */
+function normalizePathList(v) {
+  if (!Array.isArray(v)) return []
+  const out = []
+  for (const e of v) {
+    if (typeof e !== "string") continue
+    const s = e.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "")
+    if (!s || out.includes(s)) continue
+    out.push(s)
+  }
+  return out
+}
+
+function normalizeString(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : ""
+}
+
+/** Project the manifest three families into the frozen declaration object.
+ *  `declared` = VALUE comparison against the defaults — at least one family deviates
+ *  (a key written with its default value still counts as NOT declared; the design-gate
+ *  hint reads it to decide whether to point at the manifest, PORTABILITY §3.1).
+ *  `root` = the project root this declaration belongs to (`dirname(manifestFilePath(cwd))` —
+ *  the segment-matching face's anchor, D18); NOT a declared value (excluded from `declared`);
+ *  `null` = unknown root (`DEFAULT_DECLARATION`). */
+function buildDeclaration(m, root = null) {
+  const codePaths = normalizeCodePaths(m?.codePaths) ?? [...DEFAULT_MANIFEST.codePaths]
+  const codeExtensions = normalizeExtensions(m?.index?.codeExtensions)
+  const docExtensions = normalizeExtensions(m?.index?.docExtensions)
+  const excludePaths = normalizePathList(m?.index?.excludePaths)
+  const publicRepos = normalizePathList(m?.index?.publicRepos)
+  const docMap = normalizeString(m?.advisor?.docMap)
+  const standardsDoc = normalizeString(m?.advisor?.standardsDoc)
+  const defaults = normalizeCodePaths(DEFAULT_MANIFEST.codePaths) ?? []
+  const pathsDiffer = codePaths.length !== defaults.length || codePaths.some((p, i) => p !== defaults[i])
+  const declared = pathsDiffer || codeExtensions.length > 0 || docExtensions.length > 0 || excludePaths.length > 0 || publicRepos.length > 0 || Boolean(docMap) || Boolean(standardsDoc)
+  return Object.freeze({
+    declared,
+    codePaths: Object.freeze(codePaths),
+    index: Object.freeze({
+      codeExtensions: Object.freeze(codeExtensions),
+      docExtensions: Object.freeze(docExtensions),
+      excludePaths: Object.freeze(excludePaths),
+      publicRepos: Object.freeze(publicRepos),
+    }),
+    advisor: Object.freeze({ docMap, standardsDoc }),
+    root,
+  })
+}
+
+/** Full-default declaration (no manifest / unusable manifest) — the fallback every
+ *  consumer gets; built from `DEFAULT_MANIFEST` so the default values stay single-source. */
+export const DEFAULT_DECLARATION = buildDeclaration(null)
+
+/** 排除前缀谓词（单源——§6.14 面①）：`rel`（**`base` 相对**——缺省视为根相对）命中声明前缀（恰等
+ *  ∨ 后随 `/`——`openclaw` 不吞 `openclaw-fork`）⇒ true；缺省 `[]` ⇒ 恒 false（零行为变化）。
+ *  `base`（调用面 cwd/origin·#700）= `rel` 的相对基：`resolve` + `relative` 换算至 `decl.root` 根面
+ *  再比前缀（cwd = 项目根时与既有行为逐字等义）；换算越出根面（`..` 头 ∥ 根外绝对形）⇒ **不命中**
+ *  （保守不排除——沉默洞方向收窄，与 D17 aux 面「indeterminate ⇒ 不匹配」同向）；`decl.root` 缺
+ *  ⇒ `rel` 原样（根起步调用面等义）。 */
+export function isExcludedRelPath(rel, decl, base = null) {
+  const list = decl?.index?.excludePaths
+  if (!Array.isArray(list) || list.length === 0) return false
+  let s = String(rel ?? "").replace(/\\/g, "/")
+  const root = decl?.root
+  if (base != null && root) {
+    const converted = relative(root, resolve(base, s)).replace(/\\/g, "/")
+    if (converted === ".." || converted.startsWith("../") || isAbsolute(converted)) return false
+    s = converted
+  }
+  return list.some((p) => p && (s === p || s.startsWith(`${p}/`)))
+}
+
+/**
+ * 声明公共仓**绝对根集**（§6.15 解析层——检索同步 ∥ 读面 origin 集 ∥ 引用解析三消费面共用的单一定义，
+ * 不得二写）：值形层逐项 `resolve(decl.root, p)` ⇒ 绝对根集（去重保序）；存在性判归消费面（本层不判）。
+ * 缺省 `[]` ⇒ `[]`（零行为）。
+ * @param {string} [cwd] 会话锚（项目根经 manifest.mjs 解析）
+ * @returns {string[]} 绝对路径（去重保序）
+ */
+export function declaredPublicRoots(cwd) {
+  const decl = loadProjectDeclaration(cwd)
+  const list = decl?.index?.publicRepos
+  if (!Array.isArray(list) || list.length === 0) return []
+  const base = typeof decl.root === "string" && decl.root !== "" ? decl.root : resolve(cwd ?? ".")
+  const out = []
+  for (const p of list) {
+    const abs = resolve(base, p)
+    if (!out.includes(abs)) out.push(abs)
+  }
+  return out
+}
+
+const _cache = new Map()
+
+/** Drop the per-data-file-path cache (test seam — declarations are read once per path). */
+export function clearDeclarationCache() {
+  _cache.clear()
+}
+
+/** Retired-carrier warning (existence check only — zero content parsing, zero fallback). */
+function warnRetiredCarrier(root) {
+  console.warn(`[declaration] ${RETIRED_REL_PATH} is retired and no longer read — move codePaths / index.*Extensions / advisor.{docMap,standardsDoc} into PROJECT-MANIFEST.json`)
+  logEvent("declaration:retired-file", { cwd: root })
+}
+
+/**
+ * Load (and cache) the normalized project declaration for a project.
+ * The data file is located through `manifestFilePath(cwd)` (ONE root resolution — a cwd
+ * deeper than the project root still reads the project's manifest) and read through
+ * `readManifest` (ONE reader — this module carries no second parse of the manifest).
+ * Missing manifest → defaults, silently (the returned `root` is still the project root —
+ * `dirname(manifestFilePath(cwd))`, the face's anchor). Unusable manifest (invalid shape /
+ * read error) → defaults + `console.warn` + a log event (visible degradation, never a throw).
+ * A retired `.thincoder/conventions.json` at the manifest's project root → one warning
+ * per cache miss (content zero-parsed, zero effect on the readings — KD-M1-34).
+ * @param {string} cwd — project dir / anchor (root resolved by manifest.mjs)
+ * @returns {Readonly<{declared: boolean, codePaths: readonly string[],
+ *   index: {codeExtensions: string[], docExtensions: string[], excludePaths: string[], publicRepos: string[]},
+ *   advisor: {docMap: string, standardsDoc: string}, root: string|null}>}
+ */
+export function loadProjectDeclaration(cwd) {
+  const file = manifestFilePath(cwd) // data-file path (single source — manifest.mjs KD-M1-18)
+  const hit = _cache.get(file)
+  if (hit) return hit
+  const root = dirname(file) // project root the manifest belongs to (cwd may be deeper) — the face's anchor
+  if (existsSync(join(root, RETIRED_REL_PATH))) warnRetiredCarrier(root)
+  let decl = buildDeclaration(null, root) // missing / unusable manifest → the defaults, root still known
+  try {
+    const r = readManifest(cwd)
+    if (r.ok) {
+      decl = buildDeclaration(r.manifest, root)
+    } else if (r.reason !== "missing") {
+      // Usable-file expectation broken (invalid JSON / wrong shape) → defaults, visible.
+      console.warn(`[declaration] ${file} is not a usable declaration (${(r.errors ?? []).join("; ") || r.reason}) — falling back to defaults`)
+      logEvent("declaration:error", { path: file, err: `invalid: ${(r.errors ?? []).join("; ")}`.slice(0, 200) })
+    }
+  } catch (e) {
+    // Read error (EACCES …) — same visible degradation, never a throw.
+    console.warn(`[declaration] ${file} not readable (${e?.message ?? e}) — falling back to defaults`)
+    logEvent("declaration:error", { path: file, err: String(e?.message ?? e).slice(0, 200) })
+  }
+  _cache.set(file, decl)
+  return decl
+}

package/embedding.mjs

@@ -6,6 +6,7 @@
  */
 
 import { RETRYABLE_STATUS } from "./provider/index.mjs"
+import { resolveEnvRefs } from "./env-ref.mjs"
 const MAX_RETRIES = 3
 const BATCH_SIZE = 32 // max texts per request (within SiliconFlow limits)
 
@@ -16,7 +17,8 @@ export function createEmbedder(config) {
   if (!config?.model) throw new Error("embedding config: model is required — configure embedding.model in ~/.thincoder/config.json")
   return {
     baseURL: config.baseURL.replace(/\/+$/, ""),
-    apiKey: config.apiKey,
+    // #57（provider-config-family 批）：值位 `${env:VAR}` 消费侧解析（CONFIG.md §6.3）——embedder 持解析值，请求侧零改。
+    apiKey: resolveEnvRefs(config.apiKey),
     model: config.model,
   }
 }

package/env-ref.mjs

@@ -0,0 +1,81 @@
+/**
+ * env-ref.mjs — 值位 `${env:NAME}` 引用的消费侧解析（单源叶档；机制 = `docs/core/design/CONFIG.md` §6.3）。
+ *
+ * 语义（零 import 纯函数）：
+ *  - 整值与内嵌同解（`sk-${env:K}` 式）；同一值可含多引用；非字符串值原样通过。
+ *  - 变量未设 ∕ 空串 ⇒ 抛错（点名变量；无「未设即缺省」回退——不静默字面透传）。
+ *  - 畸形引用（`${env:` 起头不构成合法引用）同抛错（点名畸形片段）。
+ *  - 解析单遍：替换产物不再二次扫描；解析产物永不回显、永不回写（调用方纪律——写盘链按磁盘原文）。
+ */
+const REF_PREFIX = "${env:"
+const REF_RE = /\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g
+
+/** 读一个变量（未设 ∕ 空串 ⇒ 抛错，点名变量；错误句零含解析产物 ∕ 前置字面）。 */
+function readVar(name) {
+  const v = process.env[name]
+  if (v === undefined || v === "") {
+    throw new Error(`env reference \${env:${name}}: variable "${name}" ${v === undefined ? "is not set" : "is empty"} — set the variable or replace the reference with a literal value`)
+  }
+  return v
+}
+
+/** 畸形引用抛错（快照自 `${env:` 起截——引用串之前的字面不进错误句）。 */
+function badRef(value, idx) {
+  return new Error(`malformed env reference ${JSON.stringify(value.slice(idx, idx + 24))} — expected \${env:NAME} with NAME matching [A-Za-z_][A-Za-z0-9_]*`)
+}
+
+/** 字符串值解析：无引用 ⇒ 原串返回；逐引用替换（每次 `${env:` 出现必须构成合法引用）。 */
+export function resolveEnvRefs(value) {
+  if (typeof value !== "string" || !value.includes(REF_PREFIX)) return value
+  const out = []
+  let pos = 0
+  while (pos < value.length) {
+    const idx = value.indexOf(REF_PREFIX, pos)
+    if (idx === -1) { out.push(value.slice(pos)); break }
+    REF_RE.lastIndex = idx
+    const m = REF_RE.exec(value)
+    if (!m || m.index !== idx) throw badRef(value, idx)
+    out.push(value.slice(pos, idx), readVar(m[1]))
+    pos = idx + m[0].length
+  }
+  return out.join("")
+}
+
+/** 键值对象解析（headers ∕ env 族）：无引用 ⇒ 原对象返回（零拷贝）；值非字符串原样。 */
+export function resolveEnvRefMap(map) {
+  if (map === null || typeof map !== "object" || Array.isArray(map)) return map
+  let changed = false
+  const out = {}
+  for (const [k, v] of Object.entries(map)) {
+    const rv = resolveEnvRefs(v)
+    if (rv !== v) changed = true
+    out[k] = rv
+  }
+  return changed ? out : map
+}
+
+/** providers[] 条目适配：`apiKey` ∥ `headers.*`（无引用 ⇒ 原对象返回——零拷贝零写回）。 */
+export function resolveProviderSecrets(provider) {
+  if (provider === null || typeof provider !== "object") return provider
+  const apiKey = resolveEnvRefs(provider.apiKey)
+  const headers = resolveEnvRefMap(provider.headers)
+  if (apiKey === provider.apiKey && headers === provider.headers) return provider
+  const out = { ...provider }
+  if (apiKey !== provider.apiKey) out.apiKey = apiKey
+  if (headers !== provider.headers) out.headers = headers
+  return out
+}
+
+/** mcp.servers[] 条目适配：`token` ∥ `headers.*` ∥ `env.*`（无引用 ⇒ 原对象返回）。 */
+export function resolveMcpServerSecrets(config) {
+  if (config === null || typeof config !== "object") return config
+  const token = resolveEnvRefs(config.token)
+  const headers = resolveEnvRefMap(config.headers)
+  const env = resolveEnvRefMap(config.env)
+  if (token === config.token && headers === config.headers && env === config.env) return config
+  const out = { ...config }
+  if (token !== config.token) out.token = token
+  if (headers !== config.headers) out.headers = headers
+  if (env !== config.env) out.env = env
+  return out
+}

package/explore-distill.mjs

@@ -1,6 +1,5 @@
 /**
- * explore-distill.mjs — End-of-run exploration distillation (AGENT-LOOP §13 +
- * CONTEXT-COMPACTION §6.9 H1, 2026-08-23). 2026-09-05 module-split: moved verbatim out of
+ * explore-distill.mjs — End-of-run exploration distillation (CONTEXT-COMPACTION.md §6.9 H1, 2026-08-23). 2026-09-05 module-split: moved verbatim out of
  * context.mjs (524 > 500 hard limit). The main agent's machine line is flooded by inline
  * step-by-step exploration (read/grep/...). At run end we distill THIS run's exploration
  * tool-results into one semantic summary note that replaces them in the machine line,
@@ -99,7 +98,7 @@ async function distillExplorations(history, start, provider, signal, agent, dept
       messages: buildCompressMessages(history, cut, extras?.systemPrompt, EXPLORE_SUMMARY_PROMPT),
       tools: extras?.tools,
       signal,
-      // §18.6 D-TR4：轨迹元数据增补——kind=distill（探索蒸馏面——agent 元数据透出；
+      // TRACES.md §6.1 D-TR4：轨迹元数据增补——kind=distill（探索蒸馏面——agent 元数据透出；
       // depth 经 summarizeRunExplorations 参数透传——agent.mjs 主作用域传入）
       logCtx: {
         stage: "distill", child: agent?._logId ?? null, kind: "distill",