@thincoder/core 0.9.4 → 0.10.1

package/context.mjs

@@ -13,7 +13,9 @@
 
 import { chat } from "./provider/index.mjs"
 import { buildCompressMessages } from "./compress-form.mjs"
-import { contextUsage, estimateTokens, collectStaleToolOutputs, keepTailSize, splitHistory, tailBudgetTokens } from "./token-window.mjs"
+import { contextUsage, estimateTokens, keepTailSize, splitHistory, tailBudgetTokens } from "./token-window.mjs"
+import { COMPACTION_PLACEHOLDER, withPlaceholderPrefix } from "./context-echo.mjs"
+import { shrinkOversized } from "./context-degrade.mjs"
 
 export const SUMMARIZE_PROMPT = `The conversation above is our work log so far — summarize it into a compact summary for use as context in the ongoing conversation.
 Requirements:
@@ -34,9 +36,6 @@ const COMPACTION_PREFIX =
   "Treat it as notes, not proof — trust its conclusions (don't redo what it reports as done) " +
   "but re-verify transient state with tools. Check memory search for any missing decisions.]\n\n"
 
-/** Placeholder assistant reply committed right after compaction (D9); D-CC18 merges it into an adjacent tail assistant instead of emitting it as a separate message */
-const COMPACTION_PLACEHOLDER = "Understood. I'll continue from these notes, re-verifying anything transient."
-
 /** After this many consecutive compaction summary failures, degrade to deterministic truncation (losing info is better than task-killing 400 errors) */
 export const COMPRESS_FAILURE_LIMIT = 3
 
@@ -71,115 +70,6 @@ function anchorText(agent) {
   return lines.length > 0 ? lines.join("\n") : null
 }
 
-/**
- * pushReal — the single entry point for REAL conversation messages.
- * A real message (user input, assistant reply, tool result, multimodal image) is appended to BOTH:
- *   agent.history      — the machine context (compaction shrinks this)
- *   agent._fullHistory — the human-readable record (persistence source)
- * Machine-only messages ([System reminder:...], compaction notes, task/plan/checkpoint re-injections)
- * are pushed directly to agent.history WITHOUT going through here, so they never enter _fullHistory.
- * The two lines are written independently at the source — no after-the-fact delta sync.
- * Message timestamps (SESSION.md §6.9): stamped HERE once at push time (epoch ms) — a single
- * point covers every real message. Pre-existing ts (e.g. from another end writing the shared slot)
- * is preserved; restored old messages keep no ts rather than getting a misleading backdate (D-S3).
- * ts is a LOCAL-ONLY field — the send layer strips it before any provider request (T-S3).
- *
- * TUI-OOM-ROOTCAUSE 批（SESSION.md §6.14）——人读线内存有界 + 磁盘为准：
- *   ① `agent._recordStore?.append(msg)`：记录同步追加（磁盘为准——append-only sidecar）；
- *   ② 窗口驱逐：绑定态（agent._historyWindow = 200）下 _fullHistory 只保最近窗口条——
- *      更早内容仅存磁盘（翻页/检索/保存从盘按需读）。未绑定（模式 F）不驱逐（零回归）。
- * 追加失败不阻断回合（独立 try/catch——尽力面 N-S6；store 内部另置 degraded 并停写）。
- */
-export function pushReal(agent, msg) {
-  if (!Array.isArray(agent._fullHistory)) agent._fullHistory = []
-  if (msg && msg.ts === undefined) msg.ts = Date.now()
-  agent._fullHistory.push(msg)
-  try { agent._recordStore?.append(msg) } catch { /* 尽力面：落盘失败不阻断回合（N-S6） */ }
-  const win = agent._historyWindow
-  if (win > 0 && agent._fullHistory.length > win) {
-    agent._fullHistory.splice(0, agent._fullHistory.length - win)
-  }
-  agent.history.push(msg)
-}
-
-/**
- * Content-shape-safe prefixing (D-CC18, generalized for D-CC19 merge reuse):
- * string → text + blank line + original; multimodal array → text part prepended;
- * empty string / null / undefined / other → text alone.
- */
-function prefixContent(content, text) {
-  if (typeof content === "string" && content.length > 0) return `${text}\n\n${content}`
-  if (Array.isArray(content)) return [{ type: "text", text }, ...content]
-  return text
-}
-
-/**
- * D-CC18 echo safety: prefix the placeholder onto an existing assistant message's content.
- * Thin wrapper over prefixContent (behavioral semantics unchanged).
- */
-function withPlaceholderPrefix(content) {
-  return prefixContent(content, COMPACTION_PLACEHOLDER)
-}
-
-/**
- * D-CC19 restore-path echo merge (2026-09-16 ENGINE-DEBT 批 ED-1): persisted `contextHistory`
- * is loaded back VERBATIM on session restore, so the D-CC18 pathological shape (an assistant
- * WITHOUT reasoning_content directly followed by another assistant — DeepSeek-family thinking
- * mode rejects the first request with 400) can revive from disk. Pure in-core function: scans
- * only at restore time, never prompts the user, never rewrites the session file. Merge direction
- * matches D-CC18 (the reasoning-less message is absorbed INTO its follower — the follower's
- * tool_calls / reasoning_content / other fields are kept verbatim; texts joined with a blank
- * line). Iterates to a fixed point (chains collapse in full). Copy-on-write: messages may be
- * shared with other lines, so the merged message is always a NEW object; clean input returns
- * the SAME array reference (zero copy).
- */
-
-/** Pair predicate: prev = assistant with no/empty reasoning_content and no tool_calls,
- * directly followed by another assistant. (Prev WITH tool_calls is never merged — pairing
- * safety, F-3.) */
-export function isAssistantEchoPair(prev, next) {
-  return prev?.role === "assistant"
-    && next?.role === "assistant"
-    && !prev.reasoning_content
-    && !(Array.isArray(prev.tool_calls) && prev.tool_calls.length > 0)
-}
-
-/** Text of a message content in any supported shape (string / parts array / null-ish). */
-function contentTextOf(content) {
-  if (typeof content === "string") return content
-  if (Array.isArray(content)) {
-    return content.filter((p) => p?.type === "text").map((p) => p.text ?? "").join("\n\n")
-  }
-  return ""
-}
-
-/** Absorb prev's text into next's content (blank-line join; empty prev text → next unchanged). */
-function absorbEchoContent(prevContent, nextContent) {
-  const text = contentTextOf(prevContent)
-  if (text.length === 0) return nextContent
-  return prefixContent(nextContent, text)
-}
-
-export function mergeAdjacentAssistantEchoes(history) {
-  if (!Array.isArray(history)) return history
-  let src = history
-  for (;;) {
-    let changed = false
-    const next = []
-    for (let i = 0; i < src.length; i++) {
-      if (i + 1 < src.length && isAssistantEchoPair(src[i], src[i + 1])) {
-        next.push({ ...src[i + 1], content: absorbEchoContent(src[i].content, src[i + 1].content) })
-        i += 1
-        changed = true
-      } else {
-        next.push(src[i])
-      }
-    }
-    if (!changed) return src === history ? history : src
-    src = next
-  }
-}
-
 /** Replace middle with a note, then re-inject task/plan state (shared by LLM summary and truncation fallback) */
 function applyCompression(agent, headEnd, tailStart, note) {
   // _fullHistory already holds every real message (written at the source via pushReal),
@@ -314,7 +204,7 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {},
     messages,
     tools: extras?.tools,
     signal,
-    // §18.6 D-TR4：轨迹元数据增补——kind=compress（上下文构建面——agent 元数据透出；
+    // TRACES.md §6.1 D-TR4：轨迹元数据增补——kind=compress（上下文构建面——agent 元数据透出；
     // depth 经 extras.traceDepth——agent.mjs 主作用域传入——compress 调用点补齐）
     logCtx: {
       stage: "compress", child: agent._logId, kind: "compress",
@@ -342,37 +232,6 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {},
   return true
 }
 
-/** prune stub 逐字（§6.16.3）：只给「已清理 + 原长度 + 重跑路径」——prune 是**删**不是摘要，不声称可复原。 */
-const pruneStub = (chars) => `[pruned: stale tool output dropped (${chars} chars) — re-run the tool if you need it again.]`
-
-/**
- * 陈旧工具输出清理（F-CC3 · §6.16.3）：合格集 = `token-window.mjs` 单源（保护尾外 ∧ `role:"tool"` ∧ ≥ 门槛）；
- * 命中项**原位换「内容」**（`history[i] = { ...m, content: stub }`——数组引用 / 长度 / 索引 / `tool_call_id` 全不变
- * ⇒ 配对**结构上不可能被拆**）。记录面零改（copy-on-write：消息对象与人读线共享）；基线失效同 `shrinkOversized` 先例。
- * @returns {{pruned:number, freed:number, candidates:number, tailKept:number, belowMin:number}}
- */
-export function pruneStaleToolOutputs(agent) {
-  const history = agent.history
-  const stale = collectStaleToolOutputs(history, agent.provider)
-  const counts = {
-    pruned: stale.indexes.length,
-    freed: stale.tokens,
-    candidates: stale.candidates,
-    tailKept: stale.tailKept,
-    belowMin: stale.belowMin,
-  }
-  if (counts.pruned === 0) return counts
-  for (const i of stale.indexes) {
-    const m = history[i]
-    // 多模态 tool 结果（content 数组）整体替换为 stub ⇒ 图像 part 丢弃（不可再取——prune 是删；回执只给重跑路径）
-    const chars = typeof m.content === "string" ? m.content.length : JSON.stringify(m.content ?? "").length
-    history[i] = { ...m, content: pruneStub(chars) }
-  }
-  agent._lastPromptTokens = null
-  agent._usageAtLen = null
-  return counts
-}
-
 /**
  * Deterministic truncation fallback: called when the summary LLM fails repeatedly, no network call.
  * Drops the middle so the task can continue. Returns whether truncation happened.
@@ -389,50 +248,12 @@ export function compressFallback(agent) {
   return true
 }
 
-/** Hard truncation limit for a single message body: when exceeded and the splitter can't find a middle section, truncate to a stub (prevents one giant message from blocking compaction) */
-const OVERSIZE_CONTENT_LIMIT = 8_000
-
-/**
- * Deterministic shrinking: last resort when splitHistory can't find a middle section (history too short) but threshold is exceeded. No LLM call.
- * Truncates user/tool message bodies exceeding OVERSIZE_CONTENT_LIMIT to a stub (keeps head + tail);
- * does not touch reasoning_content (DeepSeek/Kimi echo protocol) or tool_calls pairing structure — no protocol 400
- * risk from this path (this module's echo-safety face is `applyCompression`: the compaction placeholder is never
- * committed as a separate reasoning-less assistant next to another assistant — D-CC18, 2026-09-16 batch).
- * Only called after compressIfNeeded determines threshold is exceeded. Returns whether any message was truncated.
- */
-function shrinkOversized(agent, limit = OVERSIZE_CONTENT_LIMIT) {
-  let shrunk = false
-  // Copy-on-write: build a NEW array and replace only truncated entries. pushReal stores the SAME
-  // message object in both `agent.history` (machine line) and `agent._fullHistory` (human/persistence
-  // line), so in-place `m.content = ...` would ALSO truncate the never-compacted human line and lose
-  // the original pasted content on session persist (session.mjs persists _fullHistory). VS Code port
-  // already copies (`history.map(m => ({ ...m }))`); this brings CLI to parity.
-  const next = agent.history.map((m) => {
-    if ((m.role !== "user" && m.role !== "tool") || typeof m.content !== "string") return m
-    if (m.content.length <= limit) return m
-    // Truncate keeping head + tail, insert stub in between; keepHead/keepTail proportional but not exceeding 50%/25% of limit
-    const keepHead = Math.min(Math.floor(limit * 0.5), 4000)
-    const keepTail = Math.min(Math.floor(limit * 0.25), 2000)
-    shrunk = true
-    return {
-      ...m,
-      content:
-        m.content.slice(0, keepHead) +
-        `\n[... ${m.content.length - keepHead - keepTail} chars truncated — single message too large for context window ...]\n` +
-        m.content.slice(-keepTail),
-    }
-  })
-  if (shrunk) {
-    agent.history = next
-    // Same as compaction: measured token baseline is invalidated by the changed history, fall back to estimation until next response
-    agent._lastPromptTokens = null
-    agent._usageAtLen = null
-  }
-  return shrunk
-}
-
 // ─── 迁出面（import 面保持：TUI / verify-compress / VSC 对拍经本档取——先例 = 下方 explore-distill 再导出）──
 export { estimateTokens }
+// ─── 拆分转口（2026-10-01 拆分批 · #755 ∥ #786）：写缝 ∥ 回声 ∥ 降级三面外提——消费面 / 批内件 import 面零改 ───
+export { pushReal, pushRecord } from "./context-push.mjs"
+export { isAssistantEchoPair, mergeAdjacentAssistantEchoes } from "./context-echo.mjs"
+export { pruneStaleToolOutputs } from "./context-degrade.mjs"
 // ─── End-of-run exploration distillation（2026-09-05 module-split：524 > 500 硬限——verbatim
 // 迁至 explore-distill.mjs，语义零变——VS Code compact.mjs 同款联动；cross-repo parity 锚改指
 // explore-distill.mjs——消费方 import 面不变（re-export））───────────────────────

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"